[#110] Discovery: Improve heuristic discovery strategy

.gitignore

@@ -244,4 +244,6 @@ qtcreator-*
 COLCON_IGNORE
 AMENT_IGNORE
 
-# End of https://www.toptal.com/developers/gitignore/api/ros2,c++,python
+# End of https://www.toptal.com/developers/gitignore/api/ros2,c++,pythonPLAN.md
+
+PLAN.md

docs/config/discovery-options.rst

@@ -0,0 +1,130 @@
+Discovery Options Reference
+===========================
+
+This document describes configuration options for the gateway's discovery system.
+The discovery system maps ROS 2 graph entities (nodes, topics, services, actions)
+to SOVD entities (areas, components, apps).
+
+Discovery Modes
+---------------
+
+The gateway supports three discovery modes, controlled by the ``discovery.mode`` parameter:
+
+.. list-table:: Discovery Modes
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Mode
+     - Description
+   * - ``runtime_only``
+     - Use ROS 2 graph introspection only. Nodes are discovered at runtime
+       and mapped to SOVD entities using heuristic rules. (default)
+   * - ``manifest_only``
+     - Only expose entities declared in the manifest file. Runtime discovery
+       is disabled.
+   * - ``hybrid``
+     - Manifest defines the structure, runtime links to discovered nodes.
+
+Runtime Discovery Options
+-------------------------
+
+When using ``runtime_only`` or ``hybrid`` mode, the following options control
+how ROS 2 nodes are mapped to SOVD entities.
+
+Synthetic Components
+^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: yaml
+
+   discovery:
+     runtime:
+       create_synthetic_components: true
+       grouping_strategy: "namespace"
+       synthetic_component_name_pattern: "{area}"
+
+When ``create_synthetic_components`` is true:
+
+- Components are created as logical groupings of Apps
+- ``grouping_strategy: "namespace"`` groups nodes by their first namespace segment
+- ``synthetic_component_name_pattern`` defines the component ID format
+
+Topic-Only Namespaces
+^^^^^^^^^^^^^^^^^^^^^
+
+Some ROS 2 systems have topics published to namespaces without any associated nodes.
+This is common with:
+
+- Isaac Sim and other simulators
+- External bridges (MQTT, Zenoh, ROS 1)
+- Dead/orphaned topics from crashed processes
+
+The ``topic_only_policy`` controls how these namespaces are handled:
+
+.. code-block:: yaml
+
+   discovery:
+     runtime:
+       topic_only_policy: "create_component"
+       min_topics_for_component: 1
+
+.. list-table:: Topic-Only Policies
+   :header-rows: 1
+   :widths: 25 75
+
+   * - Policy
+     - Description
+   * - ``ignore``
+     - Don't create any entities for topic-only namespaces.
+       Use this to reduce noise from orphaned topics.
+   * - ``create_component``
+     - Create a Component with ``source: "topic"`` for each topic-only
+       namespace. (default)
+   * - ``create_area_only``
+     - Only create the Area, but don't create a Component.
+       Useful when you want the namespace visible but not as a component.
+
+The ``min_topics_for_component`` parameter (default: 1) sets the minimum number
+of topics required before creating a component. This can filter out namespaces
+with only a few stray topics.
+
+Configuration Example
+---------------------
+
+Complete YAML configuration for runtime discovery:
+
+.. code-block:: yaml
+
+   ros2_medkit_gateway:
+     ros__parameters:
+       discovery:
+         mode: "runtime_only"
+
+         runtime:
+           # Map nodes to Apps
+           expose_nodes_as_apps: true
+
+           # Group Apps into Components by namespace
+           create_synthetic_components: true
+           grouping_strategy: "namespace"
+           synthetic_component_name_pattern: "{area}"
+
+           # Handle topic-only namespaces
+           topic_only_policy: "create_component"
+           min_topics_for_component: 2  # Require at least 2 topics
+
+Command Line Override
+---------------------
+
+Override discovery options via command line:
+
+.. code-block:: bash
+
+   ros2 launch ros2_medkit_gateway gateway.launch.py \
+     discovery.runtime.topic_only_policy:="ignore" \
+     discovery.runtime.min_topics_for_component:=3
+
+See Also
+--------
+
+- :doc:`manifest-schema` - Manifest-based configuration
+- :doc:`/tutorials/heuristic-apps` - Tutorial on runtime discovery

docs/config/index.rst

@@ -6,8 +6,16 @@ This section contains configuration references for ros2_medkit.
 .. toctree::
    :maxdepth: 2
 
+   discovery-options
    manifest-schema
 
+Discovery Options
+-----------------
+
+:doc:`discovery-options`
+   Configuration reference for runtime discovery options.
+   Controls how ROS 2 nodes, topics, and services are mapped to SOVD entities.
+
 Manifest Configuration
 ----------------------
 

docs/config/manifest-schema.rst

@@ -225,6 +225,7 @@ Schema
        tags: [string]          # Optional - tags for filtering
        translation_id: string  # Optional - i18n key
        parent_component_id: string  # Optional - parent component
+       depends_on: [string]    # Optional - component IDs this depends on
        subcomponents: []       # Optional - nested definitions
 
 Fields
@@ -286,6 +287,10 @@ Fields
      - string
      - No
      - Parent component ID
+   * - ``depends_on``
+     - [string]
+     - No
+     - List of component IDs this component depends on
    * - ``subcomponents``
      - [Component]
      - No

docs/requirements/specs/discovery.rst

@@ -52,7 +52,7 @@ Discovery
 
 .. req:: GET /components/{id}/depends-on
    :id: REQ_INTEROP_008
-   :status: open
+   :status: implemented
    :tags: Discovery
 
    The endpoint shall return the list of components that the addressed component depends on.