FE-1414: Support Python packages in the architecture docs - #9230
Draft
Conversation
The generator only accepted TypeScript packages; apps/petrinaut-opt and the new Python bindings could not be documented. The layer pipeline was already language-agnostic, so this teaches the two gates Python: source extensions are resolved per package language, and the tag scanner reads @layerRoot/@ROLE from triple-quoted docstrings (module docstrings are the Python analog of a file's doc comment; # comments are deliberately not scanned). The import graph still receives only TypeScript packages - Python layers render with no edges, and the generated edge-table caption says so. Registers @apps/petrinaut-opt (layer: optimizer) and @local/petrinaut-python (layer: bindings) with docstring declarations, gives both roots diagram colours, and adds an authored page on the optimizer-CLI subprocess boundary, which a static import graph cannot represent. Python import edges are FE-1415.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
github-actions
Bot
added
area/libs
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🌟 What is the purpose of this PR?
The architecture docs generator only accepted TypeScript packages, so
apps/petrinaut-optand the new@local/petrinaut-pythonbindings could not be documented. This teaches it Python: layer pages, roles, file counts, and diagrams for Python packages, with@layerRoot/@roleread from docstrings. Import edges for Python remain out of scope (FE-1415, backlog).Stack #9226 (top): FE-1410 → FE-1411 → FE-1408 → FE-1413 → FE-1270 → FE-1412 → this PR.
🔗 Related links
🔍 What does this change?
Generator (
@local/petrinaut-arch-docs).pyfor Python); the TypeScript-only gate in the extractor is gone. The graph builder still receives only TypeScript packages, exactly as before.@layerRoot/@rolefrom triple-quoted docstrings (both quote styles). Module docstrings are the Python analog of a file's doc comment;#comments are deliberately not scanned. The tag grammar, duplicate detection, and miscasing hints are shared across languages.__pycache__and.venvjoin the ignored directories; the generated edge-table caption now states that Python packages contribute no edges yet.Registrations (42 layers, 433 files — up from 40/423)
@apps/petrinaut-opt→ root layeroptimizer, declared inoptimization_api.py's docstring.@local/petrinaut-python→ root layerbindings, declared in the package docstring.Authored content
content/optimizer/subprocess-boundary.mdx(attached tooptimizer): the optimizer↔CLI relationship is a process contract a static import graph cannot represent — this page is the missing arrow, covering the spawn handshake, the ownership split, isolation, and the bounded limits, linking thecli,bindings, andcli.runtimelayers and the usage manual.Pre-Merge Checklist 🚀
🚢 Has this modified a publishable library?
This PR:
📜 Does this require a change to the docs?
The changes in this PR:
🕸️ Does this require a change to the Turbo Graph?
The changes in this PR:
🛡 What tests cover this?
#-comment/JSDoc-in-string non-matches, duplicate/miscasing diagnostics in Python).lint:arch-docsvalidates the real registrations end to end (full file coverage of both Python packages,attachToresolution); a full bundle build is part of verification.❓ How to test this?
yarn workspace @local/petrinaut-arch-docs lint:arch-docsturbo run dev --filter @apps/petrinaut-docsand open Architecture → optimizer / bindings; the boundary guide hangs off the optimizer page.🤖 Generated with Claude Code