FE-1415: Generate import edges for Python packages

[kube]

🌟 What is the purpose of this PR?

Python packages had layers but no edges, because the import graph came from dependency-cruiser, which reads TypeScript only. The optimizer's real dependency on the Python bindings was invisible, and its diagram suggested dead code. The bundle now derives Python import edges the same way as TypeScript ones:

{ "from": "optimizer", "to": "python-bindings", "provenance": "imports", "fileDependencies": 2, "crossesPackage": true }

FE-1447 (#9264) sits below in this stack and FE-1456 (#9266) above.

🔗 Related links

• FE-1415 (internal): this PR
• FE-1443 (internal): complementary. No Python import crosses the subprocess boundary, so the declared python-bindings → cli edge stays declared, and the duplicate check confirms the two never overlap.

🔍 What does this change?

libs/@local/petrinaut-arch-docs:

• graph.ts: buildGraph splits covered packages by language. TypeScript goes through dependency-cruiser as before, Python through a new collector, and both emit the same file-level records, so aggregation, intra-layer dropping, example pairs, crossesPackage, rules, and the declared-edge duplicate check apply to Python unchanged.
• python-imports.ts (new, no dependencies): a line-based parser for import a.b and from a.b import c, covering aliases, comma lists, parenthesised continuations and relative imports; a module index over the covered packages; and a resolver. Imports resolving to nothing covered drop silently, as the TypeScript ones do. The parser skips strings and comments conservatively, because a missed import loses one edge while an invented one puts a false claim in the docs. Two packages claiming one dotted module name is an error, since last-write-wins would let an import in one app resolve into another's file and invent a cross-package edge.
• Captions: the relations note and content/index.mdx no longer say Python contributes no edges.

The one new edge is the optimizer's import of the bindings. Intra-package Python imports aggregate away as intra-layer, as they should.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies a workspace but not a publishable library

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

🛡 What tests cover this?

• python-imports.test.ts (new): parsing (absolute, from-imports, aliases, relative, continuations, comment and string non-matches), module indexing, the module-name collision diagnostic, and resolution.
• graph.test.ts: a full-chain assertion that a Python cross-package import aggregates into an edge.
• lint:arch-docs exercises the real repo with zero diagnostics.

❓ How to test this?

1. yarn workspace @local/petrinaut-arch-docs lint:arch-docs passes.
2. turbo run dev --filter @apps/petrinaut-docs: the optimizer page shows python-bindings under "Depends on" with an import count, and the overview diagram draws the solid edge beside the dashed declared one.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 26, 2026 12:22pm
petrinaut	Ready	Preview	Aug 26, 2026 12:22pm
petrinaut-docs	Ready	Preview	Aug 26, 2026 12:22pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 26, 2026 12:22pm

[cursor]

PR Summary

Low Risk
Changes are confined to the internal arch-docs generator and docs copy; incorrect Python parsing could misrepresent dependencies in generated diagrams but does not affect runtime services.

Overview
Architecture docs previously built layer-to-layer import edges only from TypeScript (dependency-cruiser), so Python layers like the optimizer appeared disconnected from the bindings they actually import.

buildGraph now takes every covered package, splits by language, and merges the same FileDependency shape from dependency-cruiser (TS) and a new python-imports pipeline (parse import / from … import, index modules across packages, resolve to files). Cross-layer aggregation, crossesPackage, @talksTo duplicate checks, and example pairs behave unchanged for Python edges.

The Python path is intentionally conservative (skips docstrings/comments; errors on duplicate module names across packages) so diagrams do not invent dependencies. Copy in layer-relations and index.mdx now states counts include all covered packages. Tests cover parsing, resolution, module clashes, and an end-to-end cross-package edge in graph.test.ts.

^{Reviewed by Cursor Bugbot for commit 58aab4f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.