deepseek-harness/docs/typert-catalog-integration-design.md

Typert Catalog Integration Design

English | 中文

Current State and Problem

Typert already provides separate host/client FaceModel instances, a TypeGraph with explicit cross-face references, and analysis support for services, events, @typert object, generics, inheritance, and External types. The TypeScript compiler API should only translate source code into this standard model; downstream consumers should not traverse the TypeScript AST again.

The repository currently has two catalog pipelines that analyze TypeScript source directly: the static API catalog consumed by tool-cordis, and the generation and freshness gate for docs/cordis-catalog/events.md and docs/cordis-catalog/services.md. They analyze the same services, events, and related types, but maintain separate collection and rendering logic, so they cannot prove that the Typert model is sufficient to represent the existing domain semantics.

The first phase makes both pipelines consume the Typert model while keeping the three committed artifacts character-for-character identical to their pre-migration versions:

• docs/cordis-catalog/events.md
• docs/cordis-catalog/services.md
• packages/cordis/tool-cordis/src/api-catalog.ts

This phase does not require product plugins to publish Typert subpaths, example applications to load Typert, or changes to the runtime dependencies of tool-cordis.

Options

Drive tool-cordis from the Runtime Registry

Each plugin publishes and loads Typert artifacts, then tool-cordis reads the current runtime model from ctx.typert. This path reflects the set of plugins actually loaded, but it requires every product package represented in the catalog to add package exports, generated artifacts, registry contributions, and application assembly. That integration surface is much larger than the analysis capability being validated now.

Publish Typert Artifacts Repository-Wide, Then Aggregate Them Statically

All product packages generate host/client JS and DTS during the normal build/typecheck process, then the catalog generator aggregates those artifacts. This path establishes the complete publication protocol up front, but it also changes many package manifests and the build topology at once, coupling catalog migration to repository-wide Typert publication.

Analyze at Build Time, Then Project the Catalog

WorkspaceAnalyzer builds a WorkspaceModel and TypeGraph from the host TypeScript project. The repository-specific CordisCatalogProjector consumes only that model and generates the three texts. tool-cordis continues to import the committed static api-catalog.ts, so the runtime does not need the Typert service.

This phase uses build-time projection. It directly verifies that the standard Typert model can replace the existing AST collector while leaving runtime publication and automatic loading to separate follow-up decisions.

Phase-One Architecture

tsconfig.host.json
        │
        ▼
WorkspaceAnalyzer ── TypeScript compiler API 的唯一边界
        │
        ▼
WorkspaceModel + TypeGraph
        │
        ▼
CordisCatalogProjector ── 不依赖 TypeScript AST
        ├── docs/cordis-catalog/events.md
        ├── docs/cordis-catalog/services.md
        └── packages/cordis/tool-cordis/src/api-catalog.ts

The objects have the following responsibilities:

• WorkspaceAnalyzer analyzes packages, exports, services, events, type declarations, and reference relationships, and produces a compiler-independent model.
• WorkspaceModel and TypeGraph are the standard data structures shared by all generation and scanning analyses. They preserve developer-authored generics, inheritance, and type trees without retaining the TypeScript AST.
• The root entry point of @deepseek-ai/dsh-typert-generator exports CordisCatalogProjector, which performs model-driven selection, sorting, summary extraction, source location handling, JSDoc completeness checks, type-link closure, and rendering in three text formats. Its implementation remains in a dedicated Cordis catalog file, but it does not create another package subpath or embed a list of repository type names.
• scripts/gen-cordis-catalog.ts provides LINK_MAP, FOUNDATION_TYPE_NAMES, TYPE_LINK_EXEMPTIONS, and the inherited Cordis list, injects them explicitly into the projector through CordisCatalogPolicy, and owns the write/check CLI behavior. The vendor Cordis core pages continue to be generated by a separate pinned-source projector.
• tool-cordis imports only the static api-catalog.ts and does not depend on typert-registry or typert-loader.

CordisCatalogProjector is a repository-specific downstream consumer and is not part of Typert's general-purpose model. When adding another category, first extend the standard model, then add the corresponding projector. The Typert analyzer must not absorb Cordis documentation formats or tool-cordis presentation logic.

Model Additions

In addition to type structure, the catalog's character-for-character projection needs the declaration forms written by developers and exact source locations. The standard model therefore retains event/service locations, body-free text for events and members, parameter initializers, and the export status and canonical text of type declarations. SourceDeclarationModel also indexes top-level exported declarations for ambiguity checks and static type closure, without promoting them to domain graph roots.

interface SourceLocation {
  readonly file: string
  readonly line: number
  readonly column: number
}

interface EventModel {
  readonly location: SourceLocation
  readonly text: string
}

Repository-wide analysis supports building bounded ts.Program instances in package batches, then merging them through source-location-stable graph ids into a face model equivalent to monolithic analysis. This capability changes only the memory boundary of the compiler program; it does not change package, declaration, or type graph semantics.

All information required by the projector must come from WorkspaceModel or TypeGraph. If a fact required for character-for-character compatibility cannot be expressed by the model, extend the standard model; do not reintroduce ts.Node, ts.Symbol, or ts.TypeChecker in the projector or script.

Character-for-Character Migration Oracle

Before migration, retain the three texts produced by the old generator against the same source state. After migration, run the new analyzer and projector and require the three outputs to be byte-for-byte identical. Newlines, spaces, ordering, JSDoc, source pointers, and generated headers are all part of the comparison.

pnpm run verify-cordis-catalog retains its --check mode, which reads the three committed artifacts and compares them directly with the newly computed results. A missing file or any differing character makes the artifact stale, and the error points to the single pnpm run gen-cordis-catalog repair command.

Tests pin both of the following layers:

• Typert fixture snapshots pin the WorkspaceModel, TypeGraph, JS, DTS, and Zod outputs, proving the behavior of the standard model and general-purpose emitters.
• Cordis catalog tests or snapshots pin the projector's three complete texts, proving that the repository-specific product projection does not bypass the standard model and providing directly reviewable textual evidence.

The three committed artifacts are the migration oracle between the old and new implementations and the continuing freshness oracle after migration. The old gen-cordis-api AST collector is removed. The scripts and commands with that name remain only as compatibility entry points for the unified projector because the generated file header itself contains the command; retaining the entry point preserves the character-for-character oracle without creating a second source of truth.

Exact Change List

Typert Generator

• Add the locations, authored declaration text, parameter initializers, export status, and top-level source declaration index needed for character-for-character projection, with coverage in analyzer and model snapshots.
• Support bounded package-batch analysis and prove that direct and batched models are equivalent.
• Confirm that the catalog's required service declarations, public instance members, JSDoc, generics, inheritance, and referenced types are all available from the model.
• Keep the TypeScript compiler API encapsulated within the analyzer; the public model and projector inputs do not expose compiler objects.

Cordis Catalog Projector

• Select the complete set of Cordis services and events from the host WorkspaceModel.
• Preserve the old generator's JSDoc rules: events must have @mode and payload @param tags; service methods must have a matching @param for every parameter; non-void returns must have @returns.
• Compute the type links used by signatures and the transitive public type closure required by tool-cordis from the type graph.
• Receive caller-maintained type classifications and the inherited surface through an explicit CordisCatalogPolicy; do not maintain the repository documentation taxonomy inside the generator package.
• Preserve the existing output rules for source pointers, signatures, summaries, ordering, declaration truncation, and the inherited context catalog.
• Project once and render the events Markdown, services Markdown, and TypeScript API catalog, preventing drift between documentation and tool data.

Commands and Consumers

• scripts/gen-cordis-catalog.ts maintains repository policy data, assembles the analyzer and projector, and writes/checks all three artifacts together. Parsing, validation, and rendering logic lives in the generator's dedicated Cordis source file and is exported uniformly from the package root entry point.
• Narrow scripts/gen-cordis-api.ts to a logic-free compatibility entry point for the unified CLI; the root gen-cordis-api and verify-cordis-api aliases point to that entry point.
• Restore the static catalog default in tool-cordis and remove its dependencies on ctx.typert, typert-registry, and runtime package-model completeness.
• gen-doc-graphs obtains the projector's model-level result once and reuses its services and events; it must not continue to import the AST collector or analyze the repository again.

Narrow the Scope of Phase-One Changes

• Remove the newly added ./typert and ./client/typert exports and lib/typert.* files from product plugin package.json files.
• Remove typert-registry and typert-loader assembly from examples.
• Normal build/typecheck does not run repository-wide gen-typert or require product-package Typert artifacts to exist before it runs on a clean tree.
• Retain packages/typert/generator, packages/typert/registry, and packages/typert/loader, along with their independent fixture, emitter, and runtime registration tests.

Future Extensions

The runtime registry remains the receiving and query layer for generated JS/Zod, and the loader remains the automatic loading mechanism; neither supplies data to the first-phase static catalog. When product packages need runtime reflection, they can opt in by publishing package/typert and package/client/typert, which the loader then registers with ctx.typert.

Future integration does not change the phase-one layering: only the analyzer handles TypeScript, the standard model serves both static generation and scan analysis, and the emitter produces runtime artifacts from that same model. Whether to extend publication to more packages, enable the loader by default, or extend the runtime registry's query capabilities are separate review decisions and remain decoupled from the Cordis catalog migration.