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 }

In stack #9280, FE-1447 (#9264) sits below 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:

• Provider split (graph.ts): buildGraph splits covered packages by language. TypeScript goes through dependency-cruiser as before, and Python goes through a new collector. Both produce the same file-level dependency 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 (aliases, comma lists, parenthesised continuations, relative imports), a module index over the covered Python packages, and a resolver. Imports that resolve to nothing covered (stdlib, third-party) drop silently, matching the TypeScript behaviour. The parser skips strings and comments conservatively: a missed import loses one edge, while an invented one would put a false claim in the docs.
• Stale captions retired: 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.

Review fixes

• Two packages claiming one dotted module name is an error, reported through the module index's previously-empty diagnostics channel, with tests. Last-write-wins would let an import in one app resolve into another app's file and invent a cross-package edge.
• The openDelimiterAfter comment names its reachable failure case: a single-quoted literal containing a triple quote reads as an unclosed docstring and drops imports until the next """, erring toward a lost edge.

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 22, 2026 3:06am
petrinaut	Ready	Preview	Aug 22, 2026 3:06am
petrinaut-docs	Ready	Preview	Aug 22, 2026 3:06am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 22, 2026 3:06am

[cursor]

PR Summary

Medium Risk
Touches the architecture-docs graph pipeline that CI treats as source of truth; a parser miss or false edge would mis-draw generated diagrams, but it does not change product runtime or security.

Overview
Architecture docs now treat Python imports as first-class graph edges, so the optimizer’s real dependency on the Python bindings shows up as a solid imports edge instead of looking like dead code.

buildGraph splits packages by language: TypeScript still goes through dependency-cruiser, Python through a new conservative line-based collector (python-imports.ts) that parses, indexes, and resolves import/from statements to covered files. Both emit the same file-level records, so aggregation, intra-layer dropping, crossesPackage, and @talksTo duplicate checks apply unchanged. Stdlib/third-party imports drop; colliding module names across packages are errors.

Captions that said Python contributed no edges are updated.

^{Reviewed by Cursor Bugbot for commit 2047c0a. 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.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 576cb87. Configure here.}