Tianyi Cui
5024cd5757
Add a README to each group dir (core/llm/bash/session-persistence/ui/ support) stating its role and product-vs-support classification, and rewrite packages/README.md around the hierarchy (group table, grouped "what goes where", removed the package-hierarchy FIXME). Move the package-hierarchy RFC to implemented/architecture/ and rewrite it to describe what shipped (placement rationale, the paths-wildcard and publint dedup, the two new guardrail gates). Fold the remaining tsconfig.build.json references dedup into the discover-package-inventory proposal and fix its cross-link. Update AGENTS.md: regrouped repo-layout map, depth-2 globs, the new verify-package-paths gate in the doc-sync listing, and a note that we lean toward stricter lint in the agentic-coding era (machine-caught errors and a consistent foundation outweigh the one-time cost).
3.0 KiB
RFC: Discover package inventories instead of maintaining static lists
Status: proposed
Problem
Package and gate inventories are repeated by hand. The package cookbook tells authors to update several files. The package README carries a hand-written dependency graph. CI and development docs can drift from the actual doc-sync subcommands when new gates are added. tsconfig.build.json lists all 18 packages as explicit project references. These lists are small today, but every new package or gate creates another manual synchronization point.
The package hierarchy already removed several of these by hand: scripts/publint-all.ts now derives its list from the packages/<group>/<pkg> layout, and the two tsconfig paths maps collapsed to one @deepseek-ai/dsh-* wildcard. What remains is the inventory that cannot be globbed away — chiefly tsconfig.build.json's project references, which TypeScript requires as an explicit array (no wildcard form).
Static lists are appropriate when they encode policy; they are needless friction when they duplicate manifest data or layout facts that already exist in package.json, workspace globs, or the package hierarchy.
Proposal
Make the remaining package/gate inventories discoverable. A single canonical source — the packages/<group>/<pkg> hierarchy plus package manifests — should drive tsconfig.build.json's references, the module graph, and any other full-package list, with a generate-and-verify step (the existing gen-module-graph / gen-cordis-catalog pattern: a generator writes the artifact, a --check mode in hygiene/doc-sync fails on a stale committed copy). Module graph generation already reads package manifests. doc-sync should be the one command that defines and prints its sub-gates, with docs linking to that command rather than restating a second list.
The hierarchy does not need to encode every fact about a package, but it should encode the broad maintenance policy: core/product packages, integrations, capability seams, and support/test/example packages should not all require a hand-maintained exception list before scripts can tell them apart.
Acceptance criteria
tsconfig.build.jsonprojectreferencesare generated from the hierarchy (a generator emits them; a--checkgate fails when the committed copy is stale), rather than hand-maintained.- Adding a package does not require editing a static package list for any gate.
- Docs describe the source of truth rather than repeating generated inventories.
- CI invokes the aggregate commands and lets those commands own their sub-gate lists.
What we give up
Discovery scripts can become too clever. The implementation should stay boring: read manifests, filter on explicit fields, print the resolved list, and fail loud. The payoff is removing manual inventory drift, not inventing a build system.