@deepseek-ai/dsh-typert-generator 0.0.1-rc.1 → 0.0.1-rc.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/typert/generator/README.md
-README.md: ac2610620af14a30143e95921273a8c254b50a17
+README.md: ee71c26141dc56360f4e9e1ae3c7e2add6e3a19b
 README.zh.md: a1fa777493578533c93db6cd3354b89c8757d837

package/README.md

@@ -8,7 +8,7 @@ The analyzer can use independent `ts.Program` instances seeded from `tsconfig.ho
 
 ## Analysis Model
 
-Each face contains package exports, Cordis services and events, explicitly tagged objects and schemas, and a type graph for their reachable declarations. The graph preserves declaration identity, generic parameters and applications, explicit inheritance, conditional and mapped types, import attributes, abstract modifiers, and source JSDoc. Service and `@typert object` surfaces expose public instance members only; constructors, static members, and non-public members are excluded.
+Each face contains package exports, Cordis services and events, explicitly tagged objects and schemas, and a type graph for their reachable declarations. The graph preserves declaration identity, generic parameters and applications, explicit inheritance, conditional and mapped types, import attributes, abstract modifiers, and source JSDoc. Service and `@typert object` APIs expose public instance members only; constructors, static members, and non-public members are excluded.
 
 `WorkspaceAnalyzer` defaults to `check` mode and fails on TypeScript syntax or semantic diagnostics, missing reachable public annotations, private cross-package references, and reachable declaration merges that the model cannot retain losslessly. `write` mode inserts checker-derived annotations, rebuilds the program, and returns a clean check-mode model.
 

package/lib/index.js

@@ -2491,7 +2491,7 @@ var TypeGraphRenderer = class {
 	}
 	/**
 	* Find the transitive declaration closure referenced by members.
-	* @param memberIds - business-surface member ids.
+	* @param memberIds - business-API member ids.
 	* @returns declarations in graph order, excluding no roots implicitly.
 	*/
 	declarationClosureForMembers(memberIds) {
@@ -3263,7 +3263,7 @@ var CordisCatalogProjector = class {
 		this.renderer = new TypeGraphRenderer(face.graph);
 	}
 	/**
-	* Validate and project the host model's Cordis surface.
+	* Validate and project the host model's Cordis API.
 	* @returns every validated service and event projected from the host model.
 	*/
 	project() {
@@ -3503,10 +3503,10 @@ function parseJsDoc(raw) {
 		returns
 	};
 }
-function checkParams(where, surface, parameters, tags, isExempt, violations) {
+function checkParams(where, apiKind, parameters, tags, isExempt, violations) {
 	for (const parameter of parameters) {
 		if (parameter.binding !== "identifier") {
-			violations.push(`${where}: parameter '${parameter.name}' is a binding pattern; the ${surface} surface needs simple identifier parameters so @param can name them.`);
+			violations.push(`${where}: parameter '${parameter.name}' is a binding pattern; the ${apiKind} API needs simple identifier parameters so @param can name them.`);
 			continue;
 		}
 		if (isExempt(parameter)) continue;
@@ -3601,7 +3601,7 @@ function renderRuntimeApi(services, events, types, inheritedServices) {
 		" *",
 		" * The machine-readable cordis API catalog `cordis_inspect` serves to the",
 		" * model: harness services (summary + public method signatures/JSDoc),",
-		" * harness events (mode + signature/JSDoc), and the inherited `ctx` surface. Produced by",
+		" * harness events (mode + signature/JSDoc), and the inherited `ctx` API. Produced by",
 		" * the same AST walk as docs/cordis-catalog, so this data and the rendered",
 		" * docs cannot diverge.",
 		" *",
@@ -3693,7 +3693,7 @@ function renderRuntimeApi(services, events, types, inheritedServices) {
 		lines.push(`    declaration: ${quote(type.declaration)},`);
 		lines.push("  },");
 	}
-	lines.push("]", "", "/** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */", "export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [");
+	lines.push("]", "", "/** The inherited `ctx` API (cordis core + loader/hmr/timer), in curated order. */", "export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [");
 	for (const inherited of inheritedServices) lines.push(`  { name: ${quote(inherited.name)}, summary: ${quote(inherited.summary)} },`);
 	lines.push("]", "");
 	return lines.join("\n");
@@ -3775,7 +3775,7 @@ const BANNER = [
 /** The shared GENERATED + freshness-gate + fence notice paragraph. */
 const GATE_NOTICE = "This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.";
 /**
-* Render one page's generated `cordis-surface` region: the services mapped to
+* Render one page's generated Cordis API region: the services mapped to
 * the page, then the event scopes mapped to it, markers included. Pure and
 * deterministic given sorted inputs; identical bytes land in both pair sides.
 * @param page - the owning `docs/subsystems/` page basename, e.g. `core.md`.
@@ -3790,9 +3790,9 @@ function renderPageRegion(page, services, events, policy) {
 		"",
 		"<a id=\"cordis-surface\"></a>",
 		"",
-		"## Cordis surface",
+		"## Cordis API",
 		"",
-		"Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).",
+		"Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).",
 		""
 	];
 	for (const s of services) lines.push(...renderService(s, page, policy.linkedTypePages));
@@ -3813,7 +3813,7 @@ function renderPageRegion(page, services, events, policy) {
 function renderInheritedPage(policy) {
 	const lines = [
 		...BANNER,
-		"# Inherited Cordis Surface",
+		"# Inherited Cordis API",
 		"",
 		"The framework `ctx` members and events every plugin sees beyond the harness tier — pinned vendor source ([vendoring policy](../../vendor/README.md)), summarized tersely so the harness pages stay focused on repository-owned vocabulary. Detailed Context, Fiber, Registry, and Service APIs are generated in [context.md](context.md), [fiber.md](fiber.md), [registry.md](registry.md), and [service.md](service.md); the event-dispatch methods in [events.md](events.md).",
 		"",

package/lib/types/cordis-catalog.d.ts

@@ -85,7 +85,7 @@ export declare class CordisCatalogProjector {
      */
     constructor(face: FaceModel, sourceDeclarations: readonly SourceDeclarationModel[], policy: CordisCatalogPolicy);
     /**
-     * Validate and project the host model's Cordis surface.
+     * Validate and project the host model's Cordis API.
      * @returns every validated service and event projected from the host model.
      */
     project(): CordisCatalogModel;
@@ -128,7 +128,7 @@ export declare const REGION_BEGIN = "<!-- BEGIN GENERATED cordis-surface (gen-co
 /** Closing region delimiter matching {@link REGION_BEGIN}. */
 export declare const REGION_END = "<!-- END GENERATED cordis-surface -->";
 /**
- * Render one page's generated `cordis-surface` region: the services mapped to
+ * Render one page's generated Cordis API region: the services mapped to
  * the page, then the event scopes mapped to it, markers included. Pure and
  * deterministic given sorted inputs; identical bytes land in both pair sides.
  * @param page - the owning `docs/subsystems/` page basename, e.g. `core.md`.

package/lib/types/cordis-catalog.js

@@ -49,7 +49,7 @@ export class CordisCatalogProjector {
         this.renderer = new TypeGraphRenderer(face.graph);
     }
     /**
-     * Validate and project the host model's Cordis surface.
+     * Validate and project the host model's Cordis API.
      * @returns every validated service and event projected from the host model.
      */
     project() {
@@ -328,10 +328,10 @@ function parseJsDoc(raw) {
         returns,
     };
 }
-function checkParams(where, surface, parameters, tags, isExempt, violations) {
+function checkParams(where, apiKind, parameters, tags, isExempt, violations) {
     for (const parameter of parameters) {
         if (parameter.binding !== 'identifier') {
-            violations.push(`${where}: parameter '${parameter.name}' is a binding pattern; the ${surface} surface needs simple identifier parameters so @param can name them.`);
+            violations.push(`${where}: parameter '${parameter.name}' is a binding pattern; the ${apiKind} API needs simple identifier parameters so @param can name them.`);
             continue;
         }
         if (isExempt(parameter))
@@ -451,7 +451,7 @@ function renderRuntimeApi(services, events, types, inheritedServices) {
         ' *',
         ' * The machine-readable cordis API catalog `cordis_inspect` serves to the',
         ' * model: harness services (summary + public method signatures/JSDoc),',
-        ' * harness events (mode + signature/JSDoc), and the inherited `ctx` surface. Produced by',
+        ' * harness events (mode + signature/JSDoc), and the inherited `ctx` API. Produced by',
         ' * the same AST walk as docs/cordis-catalog, so this data and the rendered',
         ' * docs cannot diverge.',
         ' *',
@@ -545,7 +545,7 @@ function renderRuntimeApi(services, events, types, inheritedServices) {
         lines.push(`    declaration: ${quote(type.declaration)},`);
         lines.push('  },');
     }
-    lines.push(']', '', '/** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */', 'export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [');
+    lines.push(']', '', '/** The inherited `ctx` API (cordis core + loader/hmr/timer), in curated order. */', 'export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [');
     for (const inherited of inheritedServices) {
         lines.push(`  { name: ${quote(inherited.name)}, summary: ${quote(inherited.summary)} },`);
     }
@@ -631,7 +631,7 @@ const BANNER = [
 /** The shared GENERATED + freshness-gate + fence notice paragraph. */
 const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.';
 /**
- * Render one page's generated `cordis-surface` region: the services mapped to
+ * Render one page's generated Cordis API region: the services mapped to
  * the page, then the event scopes mapped to it, markers included. Pure and
  * deterministic given sorted inputs; identical bytes land in both pair sides.
  * @param page - the owning `docs/subsystems/` page basename, e.g. `core.md`.
@@ -646,9 +646,9 @@ export function renderPageRegion(page, services, events, policy) {
         '',
         '<a id="cordis-surface"></a>',
         '',
-        '## Cordis surface',
+        '## Cordis API',
         '',
-        'Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).',
+        'Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).',
         '',
     ];
     for (const s of services)
@@ -673,7 +673,7 @@ export function renderPageRegion(page, services, events, policy) {
 export function renderInheritedPage(policy) {
     const lines = [
         ...BANNER,
-        '# Inherited Cordis Surface',
+        '# Inherited Cordis API',
         '',
         'The framework `ctx` members and events every plugin sees beyond the harness tier — pinned vendor source ([vendoring policy](../../vendor/README.md)), summarized tersely so the harness pages stay focused on repository-owned vocabulary. Detailed Context, Fiber, Registry, and Service APIs are generated in [context.md](context.md), [fiber.md](fiber.md), [registry.md](registry.md), and [service.md](service.md); the event-dispatch methods in [events.md](events.md).',
         '',

package/lib/types/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Public surface of the Typert analyzer, compiler-independent model, and
+ * Public API of the Typert analyzer, compiler-independent model, and
  * model-driven artifact emitters. Build wiring lives in the `./tsdown`
  * subpath.
  * @module @deepseek-ai/dsh-typert-generator

package/lib/types/index.js

@@ -1,5 +1,5 @@
 /**
- * Public surface of the Typert analyzer, compiler-independent model, and
+ * Public API of the Typert analyzer, compiler-independent model, and
  * model-driven artifact emitters. Build wiring lives in the `./tsdown`
  * subpath.
  * @module @deepseek-ai/dsh-typert-generator

package/lib/types/renderer.d.ts

@@ -68,7 +68,7 @@ export declare class TypeGraphRenderer {
     renderDeclaration(id: SymbolId): string;
     /**
      * Find the transitive declaration closure referenced by members.
-     * @param memberIds - business-surface member ids.
+     * @param memberIds - business-API member ids.
      * @returns declarations in graph order, excluding no roots implicitly.
      */
     declarationClosureForMembers(memberIds: readonly string[]): TypeDeclarationModel[];

package/lib/types/renderer.js

@@ -218,7 +218,7 @@ export class TypeGraphRenderer {
     }
     /**
      * Find the transitive declaration closure referenced by members.
-     * @param memberIds - business-surface member ids.
+     * @param memberIds - business-API member ids.
      * @returns declarations in graph order, excluding no roots implicitly.
      */
     declarationClosureForMembers(memberIds) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-typert-generator",
   "description": "TypeScript project analyzer and model-driven Typert artifact generator",
-  "version": "0.0.1-rc.1",
+  "version": "0.0.1-rc.2",
   "publishConfig": {
     "access": "restricted"
   },
@@ -41,14 +41,14 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2"
   },
   "devDependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-tool-cordis": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-typert-registry": "^0.0.1-rc.1",
-    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-typert-registry": "^0.0.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-tool-cordis": "^0.0.1-rc.2"
   }
 }