ros2inspector 0.1.0__tar.gz

ros2inspector-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amine Bensaid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ros2inspector-0.1.0/PKG-INFO

@@ -0,0 +1,312 @@
+Metadata-Version: 2.4
+Name: ros2inspector
+Version: 0.1.0
+Summary: Static ROS 2 architecture analysis, visualization, and policy checking
+Author-email: Amine Bensaid <aminebensaid66@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/aminebensaid66/ros2_inspector
+Project-URL: Documentation, https://github.com/aminebensaid66/ros2_inspector_website
+Project-URL: Repository, https://github.com/aminebensaid66/ros2_inspector
+Project-URL: Issues, https://github.com/aminebensaid66/ros2_inspector/issues
+Keywords: ros2,robotics,architecture,static-analysis,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: networkx<3.5,>=3.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: orjson>=3.10
+Requires-Dist: tree-sitter>=0.22
+Requires-Dist: tree-sitter-cpp>=0.22
+Requires-Dist: diskcache>=5.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# ros2inspector
+
+**Static ROS 2 architecture analysis, visualization, and policy checks.**
+
+`ros2inspector` scans supported Python, C++, interface, and launch-file patterns in a ROS 2 workspace. It builds an evidence-backed architecture graph, renders that graph in several formats, and enforces architecture policies in CI.
+
+This first release ships seven commands: `scan`, `packages`, `nodes`, `graph`, `viz`, `audit`, and `validate`.
+
+## Features
+
+- Static node and endpoint discovery with Python AST and Tree-sitter C++ parsers
+- `.msg`, `.srv`, and `.action` interface parsing and type resolution
+- Python, XML, and YAML launch-file analysis with per-node remapping
+- NetworkX Unified Architecture Model for packages, nodes, topics, services, actions, and interfaces
+- Content-fingerprinted incremental analysis cache backed by diskcache
+- Rich table, JSON, YAML, Mermaid, DOT, and interactive HTML output
+- Built-in connectivity audit and YAML policy enforcement
+
+## Analysis scope
+
+ROS 2 Inspector analyzes source files without executing or building the workspace. Unsupported or ambiguous constructs are reported through evidence, confidence, dynamic-name flags, or diagnostics rather than presented as complete architectural truth.
+
+## Installation
+
+Requires Python 3.10 or newer. A ROS 2 installation is not required for source analysis.
+
+For a globally available CLI in an isolated environment, use `pipx`:
+
+```bash
+pipx install ros2inspector
+```
+
+Run it once without keeping it installed:
+
+```bash
+pipx run ros2inspector --help
+```
+
+Inside an existing Python virtual environment, use `pip`:
+
+```bash
+pip install ros2inspector
+```
+
+Install from source for development:
+
+```bash
+git clone https://github.com/aminebensaid66/ros2_inspector
+cd ros2_inspector
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```bash
+# Workspace summary
+ros2inspector scan
+
+# Package metadata and dependencies
+ros2inspector packages --show-deps
+
+# Nodes and their connections
+ros2inspector nodes --show-connections
+
+# Communication graph as Mermaid
+ros2inspector graph comms --format mermaid
+
+# Interactive HTML graph
+ros2inspector viz --no-open
+
+# Built-in architecture checks
+ros2inspector audit
+
+# Policy enforcement
+ros2inspector validate --policy ros2inspector_policy.yaml
+```
+
+## Commands
+
+### `scan`
+
+```bash
+ros2inspector scan [PATH] [--format table|json|yaml]
+```
+
+Discovers ROS 2 packages and displays a health-scored workspace summary.
+
+### `packages`
+
+```bash
+ros2inspector packages [-C PATH] [--filter cpp|python|meta] [--sort name|score|version] [--show-deps] [--format table|json|yaml]
+```
+
+Shows package metadata, type, license, maintainers, health score, and optional dependency details.
+
+### `nodes`
+
+```bash
+ros2inspector nodes [-C PATH] [--format table|json|yaml] [-p PACKAGE] [-o FILE] [--show-connections] [--no-cache]
+```
+
+Lists discovered nodes and their publishers, subscriptions, services, clients, action servers, and action clients. `--show-connections` includes resolved peer connections and interface types.
+
+### `graph`
+
+```bash
+ros2inspector graph [deps|comms|full] [-C PATH] [--format mermaid|dot|json] [-p PACKAGE] [-o FILE] [--no-cache]
+```
+
+Graph views:
+
+| View | Contents |
+|---|---|
+| `deps` | Package dependencies |
+| `comms` | Node-to-topic, service, and action communication |
+| `full` | Dependency and communication relationships together |
+
+Examples:
+
+```bash
+ros2inspector graph deps --format json
+ros2inspector graph comms --format mermaid -o architecture.mmd
+ros2inspector graph full --format dot | dot -Tsvg -o architecture.svg
+```
+
+### `viz`
+
+```bash
+ros2inspector viz [-C PATH] [-o FILE] [--open|--no-open] [--no-cache]
+```
+
+Generates a self-contained interactive Cytoscape.js HTML graph.
+
+### `audit`
+
+```bash
+ros2inspector audit [PATH] [--format table|json|yaml] [--fail-on error|warning|info] [--strict] [--exclude NAME] [--no-cache]
+```
+
+Runs built-in connectivity checks for orphan topics, dead outputs, isolated nodes, and unmatched service or action endpoints.
+
+### `validate`
+
+```bash
+ros2inspector validate [PATH] --policy FILE [--fail-on error|warning|info] [--format table|json|yaml] [--no-cache]
+```
+
+Validates the workspace against a YAML policy file.
+
+## Global options
+
+```bash
+ros2inspector --version
+ros2inspector --quiet scan
+```
+
+`--version` prints the package version. `--quiet` suppresses diagnostic headers and progress output.
+
+## Output formats
+
+`scan`, `packages`, `nodes`, `audit`, and `validate` support table, JSON, and YAML output where applicable. `graph` supports Mermaid, DOT, and JSON. `viz` writes interactive HTML.
+
+Machine-readable records go to standard output while diagnostics go to standard error, which keeps pipelines clean:
+
+```bash
+ros2inspector nodes --format json | jq '.[] | select(.package == "my_pkg")'
+ros2inspector audit --format yaml > audit.yaml
+ros2inspector graph comms --format mermaid -o architecture.mmd
+```
+
+## Policy files
+
+Create a `ros2inspector_policy.yaml` file:
+
+```yaml
+version: 1
+rules:
+  - type: health_threshold
+    min_score: 70
+    severity: warning
+
+  - type: license
+    allowed: [Apache-2.0, MIT]
+    severity: error
+
+  - type: naming
+    packages:
+      pattern: '^[a-z][a-z0-9_]*$'
+      severity: warning
+    nodes:
+      pattern: '^[A-Z][a-zA-Z0-9]*Node$'
+      severity: info
+
+  - type: dependency
+    forbidden:
+      - { from: perception, to: planner, severity: error }
+    required:
+      - { package: navigation, depends_on: nav_core, severity: warning }
+
+  - type: no_circular_deps
+    severity: error
+
+  - type: topic_connectivity
+    no_publisher: true
+    no_subscriber: true
+    exclude: [/rosout, /clock]
+
+  - type: maintainer_required
+    require_email: true
+    severity: warning
+```
+
+Supported rule types are `health_threshold`, `license`, `naming`, `dependency`, `no_circular_deps`, `topic_connectivity`, `node_isolation`, `service_connectivity`, `action_connectivity`, `maintainer_required`, and `version_not_default`.
+
+## CI integration
+
+```yaml
+- name: Install ROS 2 Inspector
+  run: pip install ros2inspector
+
+- name: Architecture audit
+  run: ros2inspector audit --fail-on warning --format json > audit.json
+
+- name: Policy validation
+  run: ros2inspector validate --policy .ros2inspector_policy.yaml --fail-on error
+```
+
+Relevant exit codes:
+
+| Code | Meaning |
+|---|---|
+| `0` | Success or no findings at the configured threshold |
+| `1` | Findings at or above the configured threshold |
+| `2` | Invalid invocation or policy configuration |
+| `3` | Workspace or policy file not found |
+
+## Architecture
+
+```text
+ros2inspector/
+├── cli/           # scan, packages, nodes, graph, viz, audit, validate
+├── discovery/     # workspace, package, and interface discovery
+├── static/        # Python, C++, interface, launch, package, and health parsers
+├── model/         # Pydantic schemas and the NetworkX UAM
+├── graph/         # Mermaid, DOT, and JSON renderers
+├── viz/           # interactive HTML renderer and bundled Cytoscape.js
+├── policy/        # policy loader, engine, and rules
+├── cache/         # diskcache-backed incremental analysis
+├── output/        # output package plumbing
+└── utils/         # shared utilities
+```
+
+The Unified Architecture Model is a `networkx.MultiDiGraph`. Graph nodes represent packages, ROS nodes, topics, services, actions, and interfaces. Edges carry relationships such as `depends_on`, `publishes`, `subscribes`, `provides`, `calls`, `defined_in`, and `uses_interface`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check ros2inspector/
+mypy ros2inspector/
+```
+
+The test suite uses fixture workspaces under `tests/fixtures/` and does not require a live ROS 2 environment.
+
+## Publishing
+
+Maintainers should follow [`RELEASING.md`](RELEASING.md). Publishing is performed by
+GitHub Actions through PyPI Trusted Publishing when a GitHub Release is published.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

ros2inspector-0.1.0/README.md

@@ -0,0 +1,273 @@
+# ros2inspector
+
+**Static ROS 2 architecture analysis, visualization, and policy checks.**
+
+`ros2inspector` scans supported Python, C++, interface, and launch-file patterns in a ROS 2 workspace. It builds an evidence-backed architecture graph, renders that graph in several formats, and enforces architecture policies in CI.
+
+This first release ships seven commands: `scan`, `packages`, `nodes`, `graph`, `viz`, `audit`, and `validate`.
+
+## Features
+
+- Static node and endpoint discovery with Python AST and Tree-sitter C++ parsers
+- `.msg`, `.srv`, and `.action` interface parsing and type resolution
+- Python, XML, and YAML launch-file analysis with per-node remapping
+- NetworkX Unified Architecture Model for packages, nodes, topics, services, actions, and interfaces
+- Content-fingerprinted incremental analysis cache backed by diskcache
+- Rich table, JSON, YAML, Mermaid, DOT, and interactive HTML output
+- Built-in connectivity audit and YAML policy enforcement
+
+## Analysis scope
+
+ROS 2 Inspector analyzes source files without executing or building the workspace. Unsupported or ambiguous constructs are reported through evidence, confidence, dynamic-name flags, or diagnostics rather than presented as complete architectural truth.
+
+## Installation
+
+Requires Python 3.10 or newer. A ROS 2 installation is not required for source analysis.
+
+For a globally available CLI in an isolated environment, use `pipx`:
+
+```bash
+pipx install ros2inspector
+```
+
+Run it once without keeping it installed:
+
+```bash
+pipx run ros2inspector --help
+```
+
+Inside an existing Python virtual environment, use `pip`:
+
+```bash
+pip install ros2inspector
+```
+
+Install from source for development:
+
+```bash
+git clone https://github.com/aminebensaid66/ros2_inspector
+cd ros2_inspector
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```bash
+# Workspace summary
+ros2inspector scan
+
+# Package metadata and dependencies
+ros2inspector packages --show-deps
+
+# Nodes and their connections
+ros2inspector nodes --show-connections
+
+# Communication graph as Mermaid
+ros2inspector graph comms --format mermaid
+
+# Interactive HTML graph
+ros2inspector viz --no-open
+
+# Built-in architecture checks
+ros2inspector audit
+
+# Policy enforcement
+ros2inspector validate --policy ros2inspector_policy.yaml
+```
+
+## Commands
+
+### `scan`
+
+```bash
+ros2inspector scan [PATH] [--format table|json|yaml]
+```
+
+Discovers ROS 2 packages and displays a health-scored workspace summary.
+
+### `packages`
+
+```bash
+ros2inspector packages [-C PATH] [--filter cpp|python|meta] [--sort name|score|version] [--show-deps] [--format table|json|yaml]
+```
+
+Shows package metadata, type, license, maintainers, health score, and optional dependency details.
+
+### `nodes`
+
+```bash
+ros2inspector nodes [-C PATH] [--format table|json|yaml] [-p PACKAGE] [-o FILE] [--show-connections] [--no-cache]
+```
+
+Lists discovered nodes and their publishers, subscriptions, services, clients, action servers, and action clients. `--show-connections` includes resolved peer connections and interface types.
+
+### `graph`
+
+```bash
+ros2inspector graph [deps|comms|full] [-C PATH] [--format mermaid|dot|json] [-p PACKAGE] [-o FILE] [--no-cache]
+```
+
+Graph views:
+
+| View | Contents |
+|---|---|
+| `deps` | Package dependencies |
+| `comms` | Node-to-topic, service, and action communication |
+| `full` | Dependency and communication relationships together |
+
+Examples:
+
+```bash
+ros2inspector graph deps --format json
+ros2inspector graph comms --format mermaid -o architecture.mmd
+ros2inspector graph full --format dot | dot -Tsvg -o architecture.svg
+```
+
+### `viz`
+
+```bash
+ros2inspector viz [-C PATH] [-o FILE] [--open|--no-open] [--no-cache]
+```
+
+Generates a self-contained interactive Cytoscape.js HTML graph.
+
+### `audit`
+
+```bash
+ros2inspector audit [PATH] [--format table|json|yaml] [--fail-on error|warning|info] [--strict] [--exclude NAME] [--no-cache]
+```
+
+Runs built-in connectivity checks for orphan topics, dead outputs, isolated nodes, and unmatched service or action endpoints.
+
+### `validate`
+
+```bash
+ros2inspector validate [PATH] --policy FILE [--fail-on error|warning|info] [--format table|json|yaml] [--no-cache]
+```
+
+Validates the workspace against a YAML policy file.
+
+## Global options
+
+```bash
+ros2inspector --version
+ros2inspector --quiet scan
+```
+
+`--version` prints the package version. `--quiet` suppresses diagnostic headers and progress output.
+
+## Output formats
+
+`scan`, `packages`, `nodes`, `audit`, and `validate` support table, JSON, and YAML output where applicable. `graph` supports Mermaid, DOT, and JSON. `viz` writes interactive HTML.
+
+Machine-readable records go to standard output while diagnostics go to standard error, which keeps pipelines clean:
+
+```bash
+ros2inspector nodes --format json | jq '.[] | select(.package == "my_pkg")'
+ros2inspector audit --format yaml > audit.yaml
+ros2inspector graph comms --format mermaid -o architecture.mmd
+```
+
+## Policy files
+
+Create a `ros2inspector_policy.yaml` file:
+
+```yaml
+version: 1
+rules:
+  - type: health_threshold
+    min_score: 70
+    severity: warning
+
+  - type: license
+    allowed: [Apache-2.0, MIT]
+    severity: error
+
+  - type: naming
+    packages:
+      pattern: '^[a-z][a-z0-9_]*$'
+      severity: warning
+    nodes:
+      pattern: '^[A-Z][a-zA-Z0-9]*Node$'
+      severity: info
+
+  - type: dependency
+    forbidden:
+      - { from: perception, to: planner, severity: error }
+    required:
+      - { package: navigation, depends_on: nav_core, severity: warning }
+
+  - type: no_circular_deps
+    severity: error
+
+  - type: topic_connectivity
+    no_publisher: true
+    no_subscriber: true
+    exclude: [/rosout, /clock]
+
+  - type: maintainer_required
+    require_email: true
+    severity: warning
+```
+
+Supported rule types are `health_threshold`, `license`, `naming`, `dependency`, `no_circular_deps`, `topic_connectivity`, `node_isolation`, `service_connectivity`, `action_connectivity`, `maintainer_required`, and `version_not_default`.
+
+## CI integration
+
+```yaml
+- name: Install ROS 2 Inspector
+  run: pip install ros2inspector
+
+- name: Architecture audit
+  run: ros2inspector audit --fail-on warning --format json > audit.json
+
+- name: Policy validation
+  run: ros2inspector validate --policy .ros2inspector_policy.yaml --fail-on error
+```
+
+Relevant exit codes:
+
+| Code | Meaning |
+|---|---|
+| `0` | Success or no findings at the configured threshold |
+| `1` | Findings at or above the configured threshold |
+| `2` | Invalid invocation or policy configuration |
+| `3` | Workspace or policy file not found |
+
+## Architecture
+
+```text
+ros2inspector/
+├── cli/           # scan, packages, nodes, graph, viz, audit, validate
+├── discovery/     # workspace, package, and interface discovery
+├── static/        # Python, C++, interface, launch, package, and health parsers
+├── model/         # Pydantic schemas and the NetworkX UAM
+├── graph/         # Mermaid, DOT, and JSON renderers
+├── viz/           # interactive HTML renderer and bundled Cytoscape.js
+├── policy/        # policy loader, engine, and rules
+├── cache/         # diskcache-backed incremental analysis
+├── output/        # output package plumbing
+└── utils/         # shared utilities
+```
+
+The Unified Architecture Model is a `networkx.MultiDiGraph`. Graph nodes represent packages, ROS nodes, topics, services, actions, and interfaces. Edges carry relationships such as `depends_on`, `publishes`, `subscribes`, `provides`, `calls`, `defined_in`, and `uses_interface`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check ros2inspector/
+mypy ros2inspector/
+```
+
+The test suite uses fixture workspaces under `tests/fixtures/` and does not require a live ROS 2 environment.
+
+## Publishing
+
+Maintainers should follow [`RELEASING.md`](RELEASING.md). Publishing is performed by
+GitHub Actions through PyPI Trusted Publishing when a GitHub Release is published.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

ros2inspector-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ros2inspector"
+version = "0.1.0"
+description = "Static ROS 2 architecture analysis, visualization, and policy checking"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Amine Bensaid", email = "aminebensaid66@gmail.com" }]
+keywords = ["ros2", "robotics", "architecture", "static-analysis", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Quality Assurance",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.7",
+    "networkx>=3.3,<3.5",
+    "pydantic>=2.7",
+    "pyyaml>=6.0",
+    "orjson>=3.10",
+    "tree-sitter>=0.22",
+    "tree-sitter-cpp>=0.22",
+    "diskcache>=5.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/aminebensaid66/ros2_inspector"
+Documentation = "https://github.com/aminebensaid66/ros2_inspector_website"
+Repository = "https://github.com/aminebensaid66/ros2_inspector"
+Issues = "https://github.com/aminebensaid66/ros2_inspector/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.2",
+    "pytest-cov>=5.0",
+    "ruff>=0.4",
+    "mypy>=1.10",
+]
+
+[project.scripts]
+ros2inspector = "ros2inspector.cli.app:run"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["ros2inspector*"]
+
+[tool.setuptools.package-data]
+"ros2inspector.viz" = ["_cytoscape.min.js"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "requires_ros2: marks tests that need a live ROS 2 environment",
+    "integration: marks portable full-pipeline integration tests",
+]
+addopts = "--cov=ros2inspector --cov-report=term-missing"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+# This file embeds HTML/CSS/JS templates where long lines are unavoidable.
+"ros2inspector/viz/renderer.py" = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0",
+    "pytest>=9.1.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.17",
+]

ros2inspector-0.1.0/ros2inspector/__init__.py

@@ -0,0 +1,10 @@
+"""ROS2 Inspector — architectural analysis and governance for ROS 2 workspaces."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ros2inspector")
+except PackageNotFoundError:  # pragma: no cover - only when run from an uninstalled checkout
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]