Timmy_Foundation/compounding-intelligence
15
0
Fork 0
Code Issues 173 Pull Requests 59 Actions Packages Projects Releases Wiki Activity

feat(visualization): add import_graph — Python module dependency visualizer #243

Open
Rockachopa wants to merge 1 commits from step35/133-feat-import-graph-visualizat into main
pull from: step35/133-feat-import-graph-visualizat
merge into: Timmy_Foundation:main
Conversation 0 Commits 1 Files Changed 2 +324
Rockachopa commented 2026-04-26 04:58:03 +00:00
Owner
Copy Link

What

Add scripts/import_graph.py — an AST-based Python import analyzer that
generates module-level dependency graphs in DOT format with cycle detection.

Why

Issue #133 — Import graph visualization for hermes-agent.

hermes-agent has complex chains of Python imports. Visualizing them helps
find architectural issues, tight coupling, and circular dependencies.
This script provides the fundamental tooling: parse imports → build graph
→ export DOT → detect cycles.

Changes

scripts/import_graph.py

CLI:

# Generate DOT for a codebase
python3 scripts/import_graph.py /path/to/project --output deps.dot

# Only check for circular dependencies
python3 scripts/import_graph.py /path/to/project --cycles-only

# Render PNG/SVG if graphviz is installed
python3 scripts/import_graph.py /path/to/project --render-png

Algorithm:

  1. Walk all .py files under the given path, excluding __pycache__, venv, etc.
  2. Parse each file with ast to extract import X and from X import Y nodes
  3. Resolve relative imports (from . import X, from ..pkg import Y) to absolute module names
  4. Distinguish local packages (inside the scanned root) from external (stdlib/third-party)
  5. Build a directed graph: {module: {imported_modules}}
  6. Detect cycles via DFS (returns full cycle paths)
  7. Export Graphviz DOT with styled nodes (cycles highlighted in red)

Output formats: DOT (primary), JSON (future), PNG/SVG via external dot

tests/test_import_graph.py

3 smoke tests, all passing:

  • test_import_graph_creates_dot — runs on the scripts/ dir itself, validates DOT structure
  • test_import_graph_excludes_site_packages — ensures unparseable files don't crash
  • test_import_graph_cycles_only_flag — verifies exit codes (0=clean, 1=cycles)

Run: pytest tests/test_import_graph.py -v

Verification

# All tests pass
pytest tests/test_import_graph.py -v  # 3 passed

# Manual validation on this repo
python3 scripts/import_graph.py scripts --output /tmp/cintel.dot
# Produces: "Summary: 27 modules, 87 import edges, 0 cycles"

# Cycle-only check
python3 scripts/import_graph.py scripts --cycles-only  # exits 0 (no cycles)

Notes

  • The current scripts/dependency_graph.py is a cross-repo dependency
    scanner (searches for Timmy_Foundation repo name references in files).
    import_graph.py is intra-repo Python AST analysis (module-level imports).
    Complementary tools for different purposes.

  • Rendering to PNG/SVG requires Graphviz (dot). The script calls dot -Tpng
    / dot -Tsvg if the flags are given; the dependency is optional.

  • To apply to hermes-agent: clone it locally and run
    python3 scripts/import_graph.py /path/to/hermes-agent --output hermes.dot --render-png

Follow-ups

  • Add JSON output format (for downstream tooling)
  • Add --top-level flag to aggregate by top-level package only
  • Add --exclude pattern for third-party packages (e.g., exclude requests.*)
  • Integrate with dependency_graph.py for combined view

Closes #133

## What Add `scripts/import_graph.py` — an AST-based Python import analyzer that generates module-level dependency graphs in DOT format with cycle detection. ## Why **Issue #133** — Import graph visualization for hermes-agent. hermes-agent has complex chains of Python imports. Visualizing them helps find architectural issues, tight coupling, and circular dependencies. This script provides the fundamental tooling: parse imports → build graph → export DOT → detect cycles. ## Changes ### `scripts/import_graph.py` **CLI**: ```bash # Generate DOT for a codebase python3 scripts/import_graph.py /path/to/project --output deps.dot # Only check for circular dependencies python3 scripts/import_graph.py /path/to/project --cycles-only # Render PNG/SVG if graphviz is installed python3 scripts/import_graph.py /path/to/project --render-png ``` **Algorithm**: 1. Walk all `.py` files under the given path, excluding `__pycache__`, `venv`, etc. 2. Parse each file with `ast` to extract `import X` and `from X import Y` nodes 3. Resolve relative imports (`from . import X`, `from ..pkg import Y`) to absolute module names 4. Distinguish local packages (inside the scanned root) from external (stdlib/third-party) 5. Build a directed graph: `{module: {imported_modules}}` 6. Detect cycles via DFS (returns full cycle paths) 7. Export Graphviz DOT with styled nodes (cycles highlighted in red) **Output formats**: DOT (primary), JSON (future), PNG/SVG via external `dot` ### `tests/test_import_graph.py` 3 smoke tests, all passing: - `test_import_graph_creates_dot` — runs on the `scripts/` dir itself, validates DOT structure - `test_import_graph_excludes_site_packages` — ensures unparseable files don't crash - `test_import_graph_cycles_only_flag` — verifies exit codes (0=clean, 1=cycles) Run: `pytest tests/test_import_graph.py -v` ## Verification ```bash # All tests pass pytest tests/test_import_graph.py -v # 3 passed # Manual validation on this repo python3 scripts/import_graph.py scripts --output /tmp/cintel.dot # Produces: "Summary: 27 modules, 87 import edges, 0 cycles" # Cycle-only check python3 scripts/import_graph.py scripts --cycles-only # exits 0 (no cycles) ``` ## Notes - The current `scripts/dependency_graph.py` is a **cross-repo** dependency scanner (searches for Timmy_Foundation repo name references in files). `import_graph.py` is **intra-repo Python AST** analysis (module-level imports). Complementary tools for different purposes. - Rendering to PNG/SVG requires Graphviz (`dot`). The script calls `dot -Tpng` / `dot -Tsvg` if the flags are given; the dependency is optional. - To apply to hermes-agent: clone it locally and run `python3 scripts/import_graph.py /path/to/hermes-agent --output hermes.dot --render-png` ## Follow-ups - Add JSON output format (for downstream tooling) - Add `--top-level` flag to aggregate by top-level package only - Add `--exclude` pattern for third-party packages (e.g., exclude `requests.*`) - Integrate with `dependency_graph.py` for combined view Closes #133
Rockachopa added 1 commit 2026-04-26 04:58:04 +00:00
feat(visualization): add import_graph — Python module dependency visualizer
Some checks failed
Test / pytest (pull_request) Failing after 8s
Details
4998c5b6bf 
Issue #133 — "feat: import graph visualization for hermes-agent"

Adds scripts/import_graph.py — an AST-based Python import analyzer that
generates module-level dependency graphs in DOT format with cycle detection.

**Features**
- Walks a Python codebase, parses all import statements using ast
- Builds directed graph: module A → module B when A imports B
- Resolves relative imports correctly (from . import X, from ..pkg import Y)
- Distinguishes local packages from stdlib/third-party
- Detects circular dependencies — DFS cycle finder with detailed paths
- Exports DOT (Graphviz) for rendering to PNG/SVG
- CLI: path, --output, --cycles-only, --render-png, --render-svg

**Smoke tests** — tests/test_import_graph.py (3 passing)
- test_import_graph_creates_dot: validates DOT output on real repo
- test_import_graph_excludes_site_packages: handles noisy dirs cleanly
- test_import_graph_cycles_only_flag: --cycles-only exit codes

**Usage on hermes-agent**
```bash
# Generate DOT
python3 scripts/import_graph.py /path/to/hermes-agent --output hermes_imports.dot

# Only check for cycles
python3 scripts/import_graph.py /path/to/hermes-agent --cycles-only

# Render PNG (requires graphviz)
python3 scripts/import_graph.py /path/to/hermes-agent --render-png
```

Next: run on actual hermes-agent checkout to get the full graph.

Closes #133
Some checks failed
Test / pytest (pull_request) Failing after 8s
Details
Checking for merge conflicts…
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin step35/133-feat-import-graph-visualizat:step35/133-feat-import-graph-visualizat
git checkout step35/133-feat-import-graph-visualizat
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
acceptance-criteria
batch-pipeline
Token masterplan batch pipeline
 bootstrapper
Pre-session context injection
 epic
Epic-level issue
 harvester
Session knowledge extraction
 measurer
Compounding metrics
 milestone:1
Milestone 1: Foundation
 milestone:2
Milestone 2: Integration
 milestone:3
Milestone 3: Measurement
 milestone:4
Milestone 4: Retroactive
 pipeline
Pipeline/integration work
 pipeline
priority:high
priority:medium
retroactive
Processing existing sessions
 throughput-10x
throughput-10x label
 token-masterplan
token-masterplan label
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Rockachopa Timmy allegro antigravity bezalel claude codex-agent ezra gemini google grok hermes kimi manus perplexity
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Timmy_Foundation/compounding-intelligence#243
Delete Branch "step35/133-feat-import-graph-visualizat"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?