@deepseek-ai/dsh-typert-generator 0.1.6-alpha.1 → 0.1.6-alpha.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: 7177e6a34520ab07645727edb15c5a726b9a2a4c
-README.zh.md: c1add1907c7c14ee7dd440dfaceee0ece0aa036e
+README.md: 399e4fe622a785d68452ffeae79e106246941fa1
+README.zh.md: 1fd19fd76ab804013a8741cb90522e9fd3f608d3

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-typert-generator` lets maintainers turn public TypeScript types into build artifacts and compiler-independent models. Packages opt in through the `./typert` and optional `./client/typert` exports, and generation rejects declarations, publish lists, Remote exports, or Zod projections that it cannot represent correctly. Repository builds can emit executable schemas and matching declarations, while tools can call `WorkspaceAnalyzer` for inspection or catalog generation without publishing artifacts. Generation runs only at build time and never in a live agent session.
+`dsh-typert-generator` lets maintainers turn public TypeScript types into build artifacts and compiler-independent models. Packages opt in through the `./typert` and optional `./client/typert` exports, and generation rejects declarations, publish lists, Remote exports, or Zod projections that it cannot represent correctly. Repository builds emit executable schema factories and matching declarations, while tools can call `WorkspaceAnalyzer` for inspection or catalog generation without publishing artifacts. Generation runs only at build time and never in a live agent session.
 
 ## Table of Contents
 
@@ -83,10 +83,12 @@ Host and Client are independent TypeScript programs. Direct project references e
 
 ### Emission and publication contract
 
-`FaceModelEmitter` emits executable JavaScript containing supported Zod schemas and the `TYPERT` contribution, plus a declaration file whose schemas are typed `z.ZodType<SourceType>` through the package's public export; unsupported Zod projections fail. The Host face with Remote methods additionally emits `typert.remote-client.*` projections of Host Remote contracts for the Client. `WorkspaceTypertGenerator` validates each contributor's `package.json`: `./typert` and `./client/typert` (and `./remote` when Remote methods exist) must point at the exact generated files, and the `files` list must include them.
+`FaceModelEmitter` emits executable JavaScript containing success-cached Zod schema factories and the `TYPERT` contribution, plus a declaration file whose factories return `z.ZodType<SourceType>` through the package's public export; unsupported Zod projections fail. The Host face with Remote methods additionally emits `typert.remote-client.*` projections of Host Remote contracts for the Client. `WorkspaceTypertGenerator` validates each contributor's `package.json`: `./typert` and `./client/typert` (and `./remote` when Remote methods exist) must point at the exact generated files, and the `files` list must include them.
 
 ### Catalog projection
 
+The runtime type closure indexes exported workspace declarations and referenced framework enums. Vendored declarations stay outside business API discovery; their enums remain available when a public result refers to them.
+
 The root export includes the model-driven extraction, completeness checks, and deterministic text renderers used by this repository's Cordis catalogs. They accept a `CordisCatalogPolicy`; repository-owned type links, foundation and exemption classifications, and inherited Cordis entries stay in `scripts/gen-cordis-catalog.ts` and are passed in explicitly, so this package contains projection mechanics, not a hidden copy of the repository's documentation taxonomy.
 
 </details>

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-library"
 
 ## 概述
 
-`dsh-typert-generator` 让维护者把公开的 TypeScript 类型转换为构建产物和与编译器无关的模型。包通过 `./typert` 和可选的 `./client/typert` 导出选择加入；如果声明、发布清单、Remote 导出或 Zod 投影无法被正确表示，生成过程就会失败。仓库构建可以生成可执行 schema 与配套声明，工具也可以调用 `WorkspaceAnalyzer` 完成检查或目录生成而不发布产物。生成过程只在构建时运行，绝不会进入实时 agent（智能体）会话。
+`dsh-typert-generator` 让维护者把公开的 TypeScript 类型转换为构建产物和与编译器无关的模型。包通过 `./typert` 和可选的 `./client/typert` 导出选择加入；如果声明、发布清单、Remote 导出或 Zod 投影无法被正确表示，生成过程就会失败。仓库构建会生成可执行 schema factory 与配套声明，工具也可以调用 `WorkspaceAnalyzer` 完成检查或目录生成而不发布产物。生成过程只在构建时运行，绝不会进入实时 agent（智能体）会话。
 
 ## 目录
 
@@ -83,10 +83,12 @@ Host 与 Client 是两个独立的 TypeScript 程序。直接项目引用确定
 
 ### 生成与发布约定
 
-`FaceModelEmitter` 输出包含受支持 Zod schema 与 `TYPERT` 贡献的可执行 JavaScript，以及把 schema 通过包的公开导出标注为 `z.ZodType<SourceType>` 的声明文件；不支持的 Zod 投影会失败。含 Remote 方法的 Host face 还会额外为 Client 生成 Host Remote 约定的 `typert.remote-client.*` 投影。`WorkspaceTypertGenerator` 校验每个贡献方的 `package.json`：`./typert` 与 `./client/typert`（存在 Remote 方法时还有 `./remote`）必须指向精确的生成文件，且 `files` 清单必须包含它们。
+`FaceModelEmitter` 输出包含只缓存成功结果的 Zod schema factory 与 `TYPERT` 贡献的可执行 JavaScript，以及把 factory 通过包的公开导出标注为返回 `z.ZodType<SourceType>` 的声明文件；不支持的 Zod 投影会失败。含 Remote 方法的 Host face 还会额外为 Client 生成 Host Remote 约定的 `typert.remote-client.*` 投影。`WorkspaceTypertGenerator` 校验每个贡献方的 `package.json`：`./typert` 与 `./client/typert`（存在 Remote 方法时还有 `./remote`）必须指向精确的生成文件，且 `files` 清单必须包含它们。
 
 ### 目录投影
 
+运行时类型闭包索引导出的 workspace 声明和被引用的框架 enum。Vendor 声明不参与业务 API 发现；公共结果引用其中 enum 时，目录仍提供其定义。
+
 根导出包含本仓库 Cordis 目录使用的模型驱动提取逻辑、完整性检查与确定性文本渲染器。它们接受 `CordisCatalogPolicy`；由仓库持有的类型链接、基础类型／豁免分类与继承的 Cordis 条目仍位于 `scripts/gen-cordis-catalog.ts`，由调用方显式传入，因此本包只包含投影机制，不会隐式复制仓库的文档分类体系。
 
 </details>

package/lib/index.js

@@ -238,7 +238,7 @@ var WorkspaceAnalyzer = class WorkspaceAnalyzer {
 	indexSourceDeclarations() {
 		const selected = this.options.packages === void 0 ? void 0 : new Set(this.options.packages);
 		const declarations = [];
-		for (const registration of this.loadRegistrations()) {
+		for (const registration of this.loadRegistrations(true)) {
 			if (!this.options.faces.includes(registration.face) || selected !== void 0 && !selected.has(registration.name)) continue;
 			for (const file of registration.config.parsed.fileNames) {
 				const relativeFile = slash(relative(this.options.root, file));
@@ -264,8 +264,8 @@ var WorkspaceAnalyzer = class WorkspaceAnalyzer {
 		}
 		return uniqueBy(declarations, (declaration) => `${declaration.face}\0${declaration.location.file}\0${String(declaration.location.line)}\0${declaration.name}`).sort((left, right) => left.face.localeCompare(right.face) || left.location.file.localeCompare(right.location.file) || left.location.line - right.location.line);
 	}
-	loadRegistrations() {
-		const inventoryKey = `${this.options.root}\0${this.options.hostConfig}\0${this.options.clientConfig}`;
+	loadRegistrations(includeVendor = false) {
+		const inventoryKey = `${this.options.root}\0${this.options.hostConfig}\0${this.options.clientConfig}\0${String(includeVendor)}`;
 		const cached = this.caches.registrations.get(inventoryKey);
 		if (cached !== void 0) return cached;
 		const registrations = [];
@@ -276,7 +276,7 @@ var WorkspaceAnalyzer = class WorkspaceAnalyzer {
 			for (const reference of aggregate.parsed.projectReferences ?? []) {
 				const configPath = projectConfigPath(reference.path);
 				const packageRoot = dirname(configPath);
-				if (!isWithin(realPath(packageRoot), join(this.options.root, "packages"))) continue;
+				if (!isWithin(realPath(packageRoot), join(this.options.root, "packages")) && !(includeVendor && isWithin(realPath(packageRoot), join(this.options.root, "vendor")))) continue;
 				const manifestPath = join(packageRoot, "package.json");
 				if (!existsSync(manifestPath)) continue;
 				const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
@@ -2821,7 +2821,7 @@ var FaceModelEmitter = class {
 		lines.push(`  package: ${quote$1(packageModel.name)},`);
 		lines.push(`  face: ${quote$1(this.face.face)},`);
 		lines.push("  schemas: [");
-		for (const schema of schemas.exports) lines.push(`    { name: ${quote$1(schema.exportName)}, schema: ${schema.exportName} },`);
+		for (const schema of schemas.exports) lines.push(`    { name: ${quote$1(schema.exportName)}, create: ${schema.exportName} },`);
 		lines.push("  ],");
 		lines.push("  invocations: [");
 		for (const invocation of packageModel.invocations) lines.push(`${indent(this.invocationLiteral(invocation, schemas), 4)},`);
@@ -2842,7 +2842,7 @@ var FaceModelEmitter = class {
 		if (schemas.exports.length > 0) lines.splice(1, 0, "import type { z } from 'zod'");
 		for (const [specifier, names] of [...imports].sort(([left], [right]) => left.localeCompare(right))) lines.push(`import type { ${names.sort().join(", ")} } from ${quote$1(specifier)}`);
 		lines.push("");
-		for (const schema of schemas.exports) lines.push(`export declare const ${schema.exportName}: z.ZodType<${schema.exportName}$source>`);
+		for (const schema of schemas.exports) lines.push(`export declare const ${schema.exportName}: () => z.ZodType<${schema.exportName}$source>`);
 		if (schemas.exports.length > 0) lines.push("");
 		lines.push("export declare const TYPERT: unknown");
 		return `${lines.join("\n")}\n`;
@@ -3056,7 +3056,10 @@ var SchemaEmitter = class {
 	}
 	emit() {
 		const definitions = this.declarations.map((declaration) => this.declarationDefinition(declaration));
-		for (const boundary of this.boundaries) definitions.push(`const ${this.boundaryName(boundary.key)} = ${this.typeSchema(boundary.type)}`);
+		for (const boundary of this.boundaries) {
+			const name = this.boundaryName(boundary.key);
+			definitions.push(`let ${name}$value\nconst ${name} = () => (${name}$value ??= ${this.typeSchema(boundary.type)})`);
+		}
 		return {
 			definitions,
 			exports: this.schemas.map((model) => ({
@@ -3069,7 +3072,7 @@ var SchemaEmitter = class {
 	}
 	declarationDefinition(declaration) {
 		const name = this.schemaName(declaration.id);
-		if (declaration.typeParameters.length === 0) return `const ${name} = ${this.declarationSchema(declaration, /* @__PURE__ */ new Map())}`;
+		if (declaration.typeParameters.length === 0) return `let ${name}$value\nconst ${name} = () => (${name}$value ??= ${this.declarationSchema(declaration, /* @__PURE__ */ new Map())})`;
 		const parameters = declaration.typeParameters.map((parameter, index) => [`type${String(index)}$schema`, parameter.id]);
 		const substitutions = new Map(parameters.map(([schema, id]) => [id, schema]));
 		return `const ${name} = (${parameters.map(([schema]) => schema).join(", ")}) => ${this.declarationSchema(declaration, substitutions)}`;
@@ -3129,7 +3132,7 @@ var SchemaEmitter = class {
 			const declaration = this.renderer.declaration(node.target.symbol);
 			if (declaration.typeParameters.length === 0) {
 				if (node.arguments.length > 0) this.fail(node.name, `non-generic declaration received ${String(node.arguments.length)} type arguments`);
-				return `z.lazy(() => ${name})`;
+				return `z.lazy(() => ${name}())`;
 			}
 			return `z.lazy(() => ${name}(${this.declarationArguments(node, declaration, substitutions).join(", ")}))`;
 		}
@@ -3297,7 +3300,7 @@ function strictCodec(boundary, schema) {
 		"{",
 		"  mode: 'strict',",
 		`  typeSymbol: ${quote$1(boundary.typeSymbol)},`,
-		`  schema: ${schema},`,
+		`  create: ${schema},`,
 		"}"
 	].join("\n");
 }
@@ -3529,13 +3532,14 @@ var CordisCatalogProjector = class {
 	runtimeTypes(services, events) {
 		const declarations = /* @__PURE__ */ new Map();
 		const ambiguous = /* @__PURE__ */ new Set();
+		const maxDeclarationChars = this.policy.runtimeDeclarationMaxChars ?? DEFAULT_MAX_DECL_CHARS;
 		for (const declaration of this.sourceDeclarations) {
-			if (declaration.face !== this.face.face || declaration.kind === "enum" || !/^packages\/[^/]+\/[^/]+\/src\/.+\.tsx?$/.test(declaration.location.file)) continue;
+			if (declaration.face !== this.face.face || !/^packages\/[^/]+\/[^/]+\/src\/.+\.tsx?$/.test(declaration.location.file) && !(declaration.kind === "enum" && /^vendor\/[^/]+\/src\/.+\.ts$/.test(declaration.location.file))) continue;
 			if (declarations.has(declaration.name)) {
 				ambiguous.add(declaration.name);
 				continue;
 			}
-			declarations.set(declaration.name, declaration.text.length > MAX_DECL_CHARS ? `${declaration.text.slice(0, MAX_DECL_CHARS)} /* …truncated — full shape in source */` : declaration.text);
+			declarations.set(declaration.name, declaration.text.length > maxDeclarationChars ? `${declaration.text.slice(0, maxDeclarationChars)} /* …truncated — full shape in source */` : declaration.text);
 		}
 		for (const name of ambiguous) declarations.delete(name);
 		return referencedTypes([...services.flatMap((service) => service.methods.map((method) => method.signature)), ...events.map((event) => event.signature)], declarations);
@@ -3751,7 +3755,7 @@ function signatureTypeNames(renderer, signature) {
 	return [...names].sort();
 }
 /** Declarations longer than this render as a truncated stub. */
-const MAX_DECL_CHARS = 1500;
+const DEFAULT_MAX_DECL_CHARS = 1500;
 /** Render one value as a single-quoted TypeScript literal. */
 function quote(value) {
 	return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'").replaceAll("\n", "\\n")}'`;

package/lib/types/analyzer.js

@@ -254,7 +254,7 @@ export class WorkspaceAnalyzer {
     indexSourceDeclarations() {
         const selected = this.options.packages === undefined ? undefined : new Set(this.options.packages);
         const declarations = [];
-        for (const registration of this.loadRegistrations()) {
+        for (const registration of this.loadRegistrations(true)) {
             if (!this.options.faces.includes(registration.face)
                 || (selected !== undefined && !selected.has(registration.name)))
                 continue;
@@ -297,8 +297,8 @@ export class WorkspaceAnalyzer {
             || left.location.file.localeCompare(right.location.file)
             || left.location.line - right.location.line);
     }
-    loadRegistrations() {
-        const inventoryKey = `${this.options.root}\0${this.options.hostConfig}\0${this.options.clientConfig}`;
+    loadRegistrations(includeVendor = false) {
+        const inventoryKey = `${this.options.root}\0${this.options.hostConfig}\0${this.options.clientConfig}\0${String(includeVendor)}`;
         const cached = this.caches.registrations.get(inventoryKey);
         if (cached !== undefined)
             return cached;
@@ -311,7 +311,8 @@ export class WorkspaceAnalyzer {
             for (const reference of aggregate.parsed.projectReferences ?? []) {
                 const configPath = projectConfigPath(reference.path);
                 const packageRoot = dirname(configPath);
-                if (!isWithin(realPath(packageRoot), join(this.options.root, 'packages')))
+                if (!isWithin(realPath(packageRoot), join(this.options.root, 'packages'))
+                    && !(includeVendor && isWithin(realPath(packageRoot), join(this.options.root, 'vendor'))))
                     continue;
                 const manifestPath = join(packageRoot, 'package.json');
                 if (!existsSync(manifestPath))

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

@@ -72,6 +72,8 @@ export interface CordisCatalogPolicy {
     readonly inheritedEvents: readonly InheritedEntry[];
     /** Manually curated framework context members inherited by every plugin. */
     readonly inheritedServices: readonly InheritedEntry[];
+    /** Maximum rendered characters per runtime type declaration. */
+    readonly runtimeDeclarationMaxChars?: number;
 }
 /** Complete model-level Cordis projection used by every text renderer. */
 export interface CordisCatalogModel {

package/lib/types/cordis-catalog.js

@@ -218,16 +218,18 @@ export class CordisCatalogProjector {
     runtimeTypes(services, events) {
         const declarations = new Map();
         const ambiguous = new Set();
+        const maxDeclarationChars = this.policy.runtimeDeclarationMaxChars ?? DEFAULT_MAX_DECL_CHARS;
         for (const declaration of this.sourceDeclarations) {
-            if (declaration.face !== this.face.face || declaration.kind === 'enum'
-                || !/^packages\/[^/]+\/[^/]+\/src\/.+\.tsx?$/.test(declaration.location.file))
+            if (declaration.face !== this.face.face
+                || (!/^packages\/[^/]+\/[^/]+\/src\/.+\.tsx?$/.test(declaration.location.file)
+                    && !(declaration.kind === 'enum' && /^vendor\/[^/]+\/src\/.+\.ts$/.test(declaration.location.file))))
                 continue;
             if (declarations.has(declaration.name)) {
                 ambiguous.add(declaration.name);
                 continue;
             }
-            declarations.set(declaration.name, declaration.text.length > MAX_DECL_CHARS
-                ? `${declaration.text.slice(0, MAX_DECL_CHARS)} /* …truncated — full shape in source */`
+            declarations.set(declaration.name, declaration.text.length > maxDeclarationChars
+                ? `${declaration.text.slice(0, maxDeclarationChars)} /* …truncated — full shape in source */`
                 : declaration.text);
         }
         for (const name of ambiguous)
@@ -487,7 +489,7 @@ function signatureTypeNames(renderer, signature) {
     return [...names].sort();
 }
 /** Declarations longer than this render as a truncated stub. */
-const MAX_DECL_CHARS = 1500;
+const DEFAULT_MAX_DECL_CHARS = 1_500;
 /** Render one value as a single-quoted TypeScript literal. */
 function quote(value) {
     return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'").replaceAll('\n', '\\n')}'`;

package/lib/types/emitter.js

@@ -121,7 +121,7 @@ export class FaceModelEmitter {
         lines.push(`  face: ${quote(this.face.face)},`);
         lines.push('  schemas: [');
         for (const schema of schemas.exports) {
-            lines.push(`    { name: ${quote(schema.exportName)}, schema: ${schema.exportName} },`);
+            lines.push(`    { name: ${quote(schema.exportName)}, create: ${schema.exportName} },`);
         }
         lines.push('  ],');
         lines.push('  invocations: [');
@@ -151,7 +151,7 @@ export class FaceModelEmitter {
         }
         lines.push('');
         for (const schema of schemas.exports) {
-            lines.push(`export declare const ${schema.exportName}: z.ZodType<${schema.exportName}$source>`);
+            lines.push(`export declare const ${schema.exportName}: () => z.ZodType<${schema.exportName}$source>`);
         }
         if (schemas.exports.length > 0)
             lines.push('');
@@ -410,7 +410,8 @@ class SchemaEmitter {
     emit() {
         const definitions = this.declarations.map(declaration => this.declarationDefinition(declaration));
         for (const boundary of this.boundaries) {
-            definitions.push(`const ${this.boundaryName(boundary.key)} = ${this.typeSchema(boundary.type)}`);
+            const name = this.boundaryName(boundary.key);
+            definitions.push(`let ${name}$value\nconst ${name} = () => (${name}$value ??= ${this.typeSchema(boundary.type)})`);
         }
         const exports = this.schemas.map((model) => ({
             model,
@@ -426,7 +427,7 @@ class SchemaEmitter {
     declarationDefinition(declaration) {
         const name = this.schemaName(declaration.id);
         if (declaration.typeParameters.length === 0) {
-            return `const ${name} = ${this.declarationSchema(declaration, new Map())}`;
+            return `let ${name}$value\nconst ${name} = () => (${name}$value ??= ${this.declarationSchema(declaration, new Map())})`;
         }
         const parameters = declaration.typeParameters.map((parameter, index) => [`type${String(index)}$schema`, parameter.id]);
         const substitutions = new Map(parameters.map(([schema, id]) => [id, schema]));
@@ -500,7 +501,7 @@ class SchemaEmitter {
                 if (node.arguments.length > 0) {
                     this.fail(node.name, `non-generic declaration received ${String(node.arguments.length)} type arguments`);
                 }
-                return `z.lazy(() => ${name})`;
+                return `z.lazy(() => ${name}())`;
             }
             const arguments_ = this.declarationArguments(node, declaration, substitutions);
             return `z.lazy(() => ${name}(${arguments_.join(', ')}))`;
@@ -694,7 +695,7 @@ function strictCodec(boundary, schema) {
         '{',
         '  mode: \'strict\',',
         `  typeSymbol: ${quote(boundary.typeSymbol)},`,
-        `  schema: ${schema},`,
+        `  create: ${schema},`,
         '}',
     ].join('\n');
 }

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.1.6-alpha.1",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -40,8 +40,8 @@
   },
   "devDependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-tool-cordis": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-typert-registry": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-tool-cordis": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-typert-registry": "^0.1.6-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   }
 }