refactor: harden integration infrastructure and professionalize static analysis for v1.4.0

Signed-off-by: arounamounchili <patouossa.mounchili@gmail.com>

Author: arounamounchili

Justfile

@@ -1,10 +1,9 @@
 # LinkForge Developer Commands
 # Standardizes workflows across macOS, Linux, and Windows
 
-
 # Default: List available commands
 default:
-    @just --list
+	@just --list
 
 # --- Build ---
 
@@ -13,84 +12,107 @@ build: build-blender
 
 # Build Blender Extension
 build-blender:
-    uv run python platforms/blender/scripts/build.py
+	uv run python platforms/blender/scripts/build.py
 
 # Sync Blender dependencies (downloads platform-specific wheels)
 sync:
-    uv run python platforms/blender/scripts/build.py sync
+	uv run python platforms/blender/scripts/build.py sync
 
 # Link Blender extension for development (Blender 4.2+)
 develop:
-    uv run python platforms/blender/scripts/build.py develop
+	uv run python platforms/blender/scripts/build.py develop
 
 # --- Test ---
 
 # Run all tests (Core + Blender)
 test: test-core test-blender-logic test-blender
 
-# Run Core unit tests (platform-independent)
-test-core:
-    uv run pytest tests/unit/core tests/integration/core
+# Run all unit tests (platform-independent + mock-blender)
+test-unit: test-unit-core test-blender-logic
+
+# Run Core tests (unit + integration)
+test-core: test-unit-core test-integration-core
+
+# Run Core unit tests
+test-unit-core:
+	uv run pytest tests/unit/core
+
+# Run Core integration tests
+test-integration-core:
+	uv run pytest tests/integration/core
 
-# Run Blender logic unit tests (Uses fake-bpy-module)
+# Run Blender logic unit tests (Uses mock_bpy_env)
 test-blender-logic:
-    uv run pytest tests/unit/platforms/blender
+	uv run pytest tests/unit/platforms/blender
 
 # Run Blender integration tests (Requires real Blender)
 test-blender:
-    uv run python blender_launcher.py -- --cov=linkforge --cov-append
+	uv run python blender_launcher.py -- --cov=linkforge --cov-append
 
 # Run tests with coverage
 coverage:
-	rm -f .coverage .coverage.*
+	@rm -f .coverage .coverage.*
 	COVERAGE_FILE=.coverage.core uv run pytest tests/unit/core tests/integration/core --cov=linkforge_core
 	COVERAGE_FILE=.coverage.blender uv run python blender_launcher.py -- --cov=linkforge --cov=linkforge_core
 	uv run coverage combine
 	uv run coverage html
 	uv run coverage report
 
-# Run all quality checks
-check: lint type-check
+# --- Quality ---
+
+# Run all quality checks (format, lint, type)
+check: check-format lint type-check
+
+# Check if code is formatted correctly
+check-format:
+	uv run ruff format --check .
 
 # Run linter (Ruff)
 lint:
-    uv run ruff check .
+	uv run ruff check .
 
-# Fix linting issues automatically
+# Fix linting and formatting issues automatically
 fix:
-    uv run ruff check . --fix
-    uv run ruff format .
+	uv run ruff check . --fix
+	uv run ruff format .
+
+# Run all type checkers (MyPy + Pyright)
+type-check: type-check-mypy type-check-pyright
+
+# Run MyPy type checker
+type-check-mypy:
+	uv run mypy core/src/linkforge_core platforms/blender/linkforge
 
-# Run type checker (MyPy)
-type-check:
-    uv run mypy core/src/linkforge_core platforms/blender/linkforge
+# Run Pyright type checker
+type-check-pyright:
+	uv run pyright
 
 # --- Documentation ---
 
 # Build documentation (Sphinx)
 docs:
-    cd docs && make html
-    @echo "📖 Documentation built at docs/build/html/index.html"
+	@cd docs && make html
+	@echo "📖 Documentation built at docs/build/html/index.html"
 
 # --- Maintenance ---
 
 # Clean build artifacts, caches, and OS junk
 clean:
-    @rm -rf dist/ build/ *.egg-info
-    @rm -rf .pytest_cache .mypy_cache .ruff_cache .codespell_cache
-    @rm -rf htmlcov .coverage coverage.xml
-    @find . -type d -name "__pycache__" -exec rm -rf {} +
-    @find . -type f -name "*.py[co]" -delete
-    @find . -name ".DS_Store" -delete
-    @echo "✨ Project is clean."
+	@rm -rf dist/ build/ *.egg-info
+	@rm -rf .pytest_cache .mypy_cache .ruff_cache .codespell_cache
+	@rm -rf htmlcov .coverage coverage.xml
+	@find . -type d -name "__pycache__" -exec rm -rf {} +
+	@find . -type f -name "*.py[co]" -delete
+	@find . -name ".DS_Store" -delete
+	@echo "✨ Project is clean."
 
 # Deep clean: Includes virtual environment removal
 clean-all: clean
-    @echo "⚠️ Removing virtual environment..."
-    @rm -rf .venv/ venv/
-    @echo "💀 Everything has been removed. Run 'just install' to recover."
+	@echo "⚠️ Removing virtual environment..."
+	@rm -rf .venv/ venv/
+	@echo "💀 Everything has been removed. Run 'just install' to recover."
 
 # Install/Sync dependencies
 install:
-    uv sync --all-extras
-    uv run pre-commit install
+	uv sync --all-extras
+	uv run pre-commit install || true

core/src/linkforge_core/models/__init__.py

@@ -30,7 +30,7 @@
 from .link import Collision, Inertial, InertiaTensor, Link, LinkPhysics, Visual
 from .material import Color, Material
 from .robot import Robot
-from .ros2_control import Ros2Control, Ros2ControlJoint
+from .ros2_control import Ros2Control, Ros2ControlJoint, Ros2ControlSensor
 from .sensor import (
     CameraInfo,
     ContactInfo,
@@ -95,6 +95,7 @@
     # ros2_control
     "Ros2Control",
     "Ros2ControlJoint",
+    "Ros2ControlSensor",
     # Sensor
     "SensorType",
     "SensorNoise",

core/src/linkforge_core/models/ros2_control.py

@@ -54,6 +54,40 @@ def normalized(self) -> Ros2ControlJoint:
         )
 
 
+@dataclass(frozen=True)
+class Ros2ControlSensor:
+    """Sensor configuration in ros2_control block.
+
+    Represents a sensor's state interfaces and parameters.
+    """
+
+    name: str
+    state_interfaces: Sequence[str] = field(default_factory=tuple)
+    parameters: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Validate sensor configuration."""
+        if not self.name:
+            raise RobotValidationError(
+                ValidationErrorCode.NAME_EMPTY,
+                "ROS2 control sensor name cannot be empty",
+                target="SensorName",
+                value=self.name,
+            )
+        object.__setattr__(self, "state_interfaces", tuple(self.state_interfaces))
+
+    def with_prefix(self, prefix: str) -> Ros2ControlSensor:
+        """Create a new control sensor with a prefixed name."""
+        return replace(self, name=f"{prefix}{self.name}")
+
+    def normalized(self) -> Ros2ControlSensor:
+        """Return a new control sensor with sorted interfaces."""
+        return replace(
+            self,
+            state_interfaces=tuple(sorted(self.state_interfaces)),
+        )
+
+
 @dataclass(frozen=True)
 class Ros2Control:
     """ros2_control configuration block.
@@ -66,6 +100,7 @@ class Ros2Control:
     type: str = "system"  # "system", "actuator", or "sensor"
     hardware_plugin: str = ""
     joints: Sequence[Ros2ControlJoint] = field(default_factory=tuple)
+    sensors: Sequence[Ros2ControlSensor] = field(default_factory=tuple)
     parameters: dict[str, str] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
@@ -101,6 +136,15 @@ def __post_init__(self) -> None:
                 target="Ros2ControlJoints",
             )
 
+        # Ensure all sensors have unique names
+        sensor_names = [s.name for s in self.sensors]
+        if len(sensor_names) != len(set(sensor_names)):
+            raise RobotValidationError(
+                ValidationErrorCode.DUPLICATE_NAME,
+                f"Duplicate sensor names found in ROS2 control system '{self.name}'",
+                target="Ros2ControlSensors",
+            )
+
         # Hardware sensors are read-only and do not accept command interfaces
         if self.type == "sensor":
             for joint in self.joints:
@@ -121,18 +165,21 @@ def __post_init__(self) -> None:
                 value=len(self.joints),
             )
         object.__setattr__(self, "joints", tuple(self.joints))
+        object.__setattr__(self, "sensors", tuple(self.sensors))
 
     def with_prefix(self, prefix: str) -> Ros2Control:
         """Create a new control block with prefixed name and joints."""
         return replace(
             self,
             name=f"{prefix}{self.name}",
             joints=tuple(j.with_prefix(prefix) for j in self.joints),
+            sensors=tuple(s.with_prefix(prefix) for s in self.sensors),
         )
 
     def normalized(self) -> Ros2Control:
-        """Return a new control block with sorted joints for comparison."""
+        """Return a new control block with sorted joints and sensors for comparison."""
         return replace(
             self,
             joints=tuple(sorted([j.normalized() for j in self.joints], key=lambda x: x.name)),
+            sensors=tuple(sorted([s.normalized() for s in self.sensors], key=lambda x: x.name)),
         )

core/src/linkforge_core/parsers/urdf_parser.py

@@ -57,6 +57,7 @@
     Robot,
     Ros2Control,
     Ros2ControlJoint,
+    Ros2ControlSensor,
     Sensor,
     SensorNoise,
     SensorType,
@@ -482,17 +483,40 @@ def _parse_ros2_control(self, rc_elem: ET.Element) -> Ros2Control | None:
                     )
                 )
 
+        sensors: list[Ros2ControlSensor] = []
+        for sensor_elem in rc_elem.findall("{*}sensor"):
+            sensor_name = sensor_elem.get("name", "")
+            state_interfaces = [
+                self._normalize_hardware_interface(state.get("name", "position"))
+                for state in sensor_elem.findall("{*}state_interface")
+            ]
+            sensor_params: dict[str, str] = {
+                str(param.get("name")): param.text.strip()
+                for param in sensor_elem.findall("{*}param")
+                if param.get("name") and param.text
+            }
+
+            if state_interfaces or sensor_params:
+                sensors.append(
+                    Ros2ControlSensor(
+                        name=sensor_name,
+                        state_interfaces=state_interfaces,
+                        parameters=sensor_params,
+                    )
+                )
+
         # Catch-all for top-level parameters not inside <hardware>
         for child in rc_elem:
-            if child.tag not in ("hardware", "joint") and child.text:
-                parameters[child.tag] = child.text.strip()
+            if strip_xml_namespace(child.tag) not in ("hardware", "joint", "sensor") and child.text:
+                parameters[strip_xml_namespace(child.tag)] = child.text.strip()
 
         try:
             return Ros2Control(
                 name=name,
                 type=rc_type,
                 hardware_plugin=hardware_plugin,
                 joints=joints,
+                sensors=sensors,
                 parameters=parameters,
             )
         except RobotModelError as e:
@@ -1007,26 +1031,26 @@ def _parse_from_context(
 
                     elif tag == "gazebo":
                         try:
+                            # 1. Try to extract a sensor if present
                             sensor = self._parse_sensor_from_gazebo(elem)
                             if sensor:
                                 delayed_sensors.append(sensor)
-                            else:
-                                # Extract physics fields before they are lost
-                                physics_data = {
-                                    "mu": parse_optional_float(elem, "mu1", default=None),
-                                    "mu2": parse_optional_float(elem, "mu2", default=None),
-                                    "kp": parse_optional_float(elem, "kp", default=None),
-                                    "kd": parse_optional_float(elem, "kd", default=None),
-                                    "self_collide": parse_optional_bool(elem, "selfCollide"),
-                                    "gravity": parse_optional_bool(elem, "gravity"),
-                                }
-                                # Filter out None values
-                                physics_data = {
-                                    k: v for k, v in physics_data.items() if v is not None
-                                }
-                                delayed_gazebo_elements.append(
-                                    (self._parse_gazebo_element(elem), physics_data)
-                                )
+
+                            # 2. Extract physics fields (regardless of sensor presence)
+                            physics_data = {
+                                "mu": parse_optional_float(elem, "mu1", default=None),
+                                "mu2": parse_optional_float(elem, "mu2", default=None),
+                                "kp": parse_optional_float(elem, "kp", default=None),
+                                "kd": parse_optional_float(elem, "kd", default=None),
+                                "self_collide": parse_optional_bool(elem, "selfCollide"),
+                                "gravity": parse_optional_bool(elem, "gravity"),
+                            }
+                            # Filter out None values
+                            physics_data = {k: v for k, v in physics_data.items() if v is not None}
+
+                            # 3. Extract other Gazebo metadata (plugins, material, properties)
+                            gazebo_elem = self._parse_gazebo_element(elem)
+                            delayed_gazebo_elements.append((gazebo_elem, physics_data))
                         except (RobotModelError, ValueError, Exception) as e:
                             logger.warning(
                                 f"Skipping invalid gazebo element '{elem.get('name') or elem.get('reference')}': {e}"