@deepseek-ai/dsh-typert-generator 0.2.1-alpha.2 → 0.2.1-alpha.4

package/lib/types/analyzer.d.ts

@@ -30,6 +30,15 @@ export interface WorkspaceAnalyzerOptions {
     readonly mode?: AnalysisMode;
     /** Shared workspace memo; supply one instance to reuse parses across analyzers. */
     readonly caches?: WorkspaceCaches;
+    /**
+     * Fail analysis when a face program loads a file from a workspace
+     * package's `lib/` directory, or cannot resolve an import of a workspace
+     * package (default false). Enable it for faces that import no generated
+     * output, so that the result depends only on workspace source and never on
+     * whether package compilation ran; the failure names each importing
+     * specifier and the source a `paths` alias should map it to.
+     */
+    readonly rejectBuildOutputs?: boolean;
 }
 /** One package face whose public export graph contains Typert business declarations. */
 export interface DiscoveredTypertPackage {
@@ -44,6 +53,15 @@ export interface ParsedConfig {
     /** The TypeScript parse result. */
     readonly parsed: ts.ParsedCommandLine;
 }
+/** The settings Typert reads from one face aggregate tsconfig. */
+export interface AggregateConfig {
+    /** Absolute config path. */
+    readonly path: string;
+    /** The aggregate's effective compiler options. */
+    readonly options: ts.CompilerOptions;
+    /** The package projects the aggregate references. */
+    readonly projectReferences: readonly ts.ProjectReference[];
+}
 /** One package face registration discovered from an aggregate tsconfig. */
 export interface PackageRegistration {
     /** The face whose aggregate references this package project. */
@@ -52,7 +70,11 @@ export interface PackageRegistration {
     readonly name: string;
     /** Real package root directory. */
     readonly root: string;
-    /** The package's own parsed tsconfig. */
+    /**
+     * The package's own tsconfig, parsed on first read. Typert parses only the
+     * tsconfigs of packages it analyzes; validating every referenced tsconfig
+     * belongs to the preceding `tsc -b`.
+     */
     readonly config: ParsedConfig;
     /** The parsed package.json content. */
     readonly manifest: Record<string, unknown>;
@@ -73,6 +95,7 @@ export declare class WorkspaceCaches {
     readonly configs: Map<string, ParsedConfig>;
     /** Registration inventories keyed by root and aggregate config paths. */
     readonly registrations: Map<string, PackageRegistration[]>;
+    private readonly aggregates;
     private readonly hosts;
     /**
      * Parse one tsconfig once per workspace snapshot.
@@ -80,6 +103,14 @@ export declare class WorkspaceCaches {
      * @returns the memoized parse result.
      */
     config(path: string): ParsedConfig;
+    /**
+     * Read one face aggregate tsconfig once per workspace snapshot. An aggregate
+     * that declares `references` is parsed without expanding its `include`
+     * patterns, which affect neither its options nor its references.
+     * @param path - absolute aggregate config path.
+     * @returns the memoized compiler options and project references.
+     */
+    aggregate(path: string): AggregateConfig;
     /**
      * Return the shared compiler host for one face. Every program of one face
      * is built from the same aggregate compiler options (the first call wins),
@@ -123,9 +154,10 @@ export declare class WorkspaceAnalyzer {
     /**
      * Discover package faces from public-export-reachable Cordis augmentations
      * and explicit `@typert` roots without constructing a type-checker program.
+     * @param includeManifest - optional `package.json` predicate; a rejected package's sources and project config are not read.
      * @returns contributors grouped by package with deterministic face order.
      */
-    discoverPackages(): DiscoveredTypertPackage[];
+    discoverPackages(includeManifest?: (manifest: Readonly<Record<string, unknown>>) => boolean): DiscoveredTypertPackage[];
     /**
      * Index top-level exported type declarations without promoting them to graph
      * roots. Consumers use this lexical index for ambiguity checks while all

package/lib/types/analyzer.js

@@ -7,6 +7,7 @@
 import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, relative, resolve, sep } from 'node:path';
 import ts from 'typescript';
+import { findBuildOutputLoads, findUnresolvedWorkspaceImports } from "./build-output-guard.js";
 const PUBLIC_REMOTE_TYPE_ROOTS = new Set([
     '@deepseek-ai/dsh-util-values',
 ]);
@@ -49,6 +50,7 @@ export class WorkspaceCaches {
     configs = new Map();
     /** Registration inventories keyed by root and aggregate config paths. */
     registrations = new Map();
+    aggregates = new Map();
     hosts = new Map();
     /**
      * Parse one tsconfig once per workspace snapshot.
@@ -63,6 +65,22 @@ export class WorkspaceCaches {
         }
         return parsed;
     }
+    /**
+     * Read one face aggregate tsconfig once per workspace snapshot. An aggregate
+     * that declares `references` is parsed without expanding its `include`
+     * patterns, which affect neither its options nor its references.
+     * @param path - absolute aggregate config path.
+     * @returns the memoized compiler options and project references.
+     */
+    aggregate(path) {
+        let aggregate = this.aggregates.get(path);
+        if (aggregate === undefined) {
+            const { parsed } = parseConfig(path, true);
+            aggregate = { path, options: parsed.options, projectReferences: parsed.projectReferences ?? [] };
+            this.aggregates.set(path, aggregate);
+        }
+        return aggregate;
+    }
     /**
      * Return the shared compiler host for one face. Every program of one face
      * is built from the same aggregate compiler options (the first call wins),
@@ -131,6 +149,7 @@ export class WorkspaceAnalyzer {
             faces: options.faces ?? ['host', 'client'],
             checkDiagnostics: options.checkDiagnostics ?? true,
             mode: options.mode ?? 'check',
+            rejectBuildOutputs: options.rejectBuildOutputs ?? false,
             ...(options.packages === undefined ? {} : { packages: options.packages }),
         };
         this.caches = options.caches ?? new WorkspaceCaches();
@@ -156,16 +175,19 @@ export class WorkspaceAnalyzer {
                         this.checkProject(registration);
                 }
                 const aggregatePath = resolve(this.options.root, face === 'host' ? this.options.hostConfig : this.options.clientConfig);
-                const aggregate = this.caches.config(aggregatePath);
+                const aggregate = this.caches.aggregate(aggregatePath);
                 const rootNames = [...new Set(registrations.flatMap(registration => registration.config.parsed.fileNames))];
                 const options = {
-                    ...aggregate.parsed.options,
+                    ...aggregate.options,
                     composite: false,
                     incremental: false,
                     noEmit: true,
                 };
                 const host = this.caches.programHost(face, options);
                 const program = ts.createProgram({ rootNames, options, host });
+                if (this.options.rejectBuildOutputs) {
+                    rejectBuildOutputLoads(face, this.options.root, aggregatePath, findBuildOutputLoads(program, this.options.root, host), findUnresolvedWorkspaceImports(program, this.options.root, host));
+                }
                 faces.push(new FaceAnalyzer({
                     root: this.options.root,
                     face,
@@ -222,11 +244,13 @@ export class WorkspaceAnalyzer {
     /**
      * Discover package faces from public-export-reachable Cordis augmentations
      * and explicit `@typert` roots without constructing a type-checker program.
+     * @param includeManifest - optional `package.json` predicate; a rejected package's sources and project config are not read.
      * @returns contributors grouped by package with deterministic face order.
      */
-    discoverPackages() {
+    discoverPackages(includeManifest) {
         const registrations = this.loadRegistrations()
-            .filter(registration => this.options.faces.includes(registration.face))
+            .filter(registration => this.options.faces.includes(registration.face)
+            && (includeManifest === undefined || includeManifest(registration.manifest)))
             .filter(registration => this.registrationHasSurface(registration));
         const packages = new Map();
         for (const registration of registrations) {
@@ -307,8 +331,8 @@ export class WorkspaceAnalyzer {
             const aggregatePath = resolve(this.options.root, face === 'host' ? this.options.hostConfig : this.options.clientConfig);
             if (!existsSync(aggregatePath))
                 continue;
-            const aggregate = this.caches.config(aggregatePath);
-            for (const reference of aggregate.parsed.projectReferences ?? []) {
+            const aggregate = this.caches.aggregate(aggregatePath);
+            for (const reference of aggregate.projectReferences) {
                 const configPath = projectConfigPath(reference.path);
                 const packageRoot = dirname(configPath);
                 if (!isWithin(realPath(packageRoot), join(this.options.root, 'packages'))
@@ -318,28 +342,31 @@ export class WorkspaceAnalyzer {
                 if (!existsSync(manifestPath))
                     continue;
                 const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-                if (typeof manifest.name !== 'string')
+                const name = manifest.name;
+                if (typeof name !== 'string')
                     continue;
-                const registration = {
-                    face,
-                    name: manifest.name,
-                    root: realPath(packageRoot),
-                    config: this.caches.config(configPath),
+                const root = realPath(packageRoot);
+                const caches = this.caches;
+                // The project config is parsed on first use, so discovery and analysis
+                // read only the projects they select.
+                const register = (registrationFace, exportSubpaths) => ({
+                    face: registrationFace,
+                    name,
+                    root,
+                    get config() { return caches.config(configPath); },
                     manifest,
-                };
+                    ...(exportSubpaths === undefined ? {} : { exportSubpaths }),
+                });
                 if (!isDualFacePackage(manifest)) {
-                    registrations.push(registration);
+                    registrations.push(register(face));
                 }
                 else if (configPath === join(packageRoot, 'tsconfig.json')) {
-                    registrations.push({ ...registration, face: 'host', exportSubpaths: hostExportSubpaths(manifest) }, { ...registration, face: 'client', exportSubpaths: clientExportSubpaths(manifest) });
+                    registrations.push(register('host', hostExportSubpaths(manifest)), register('client', clientExportSubpaths(manifest)));
                 }
                 else {
-                    registrations.push({
-                        ...registration,
-                        exportSubpaths: face === 'host'
-                            ? hostExportSubpaths(manifest)
-                            : clientExportSubpaths(manifest),
-                    });
+                    registrations.push(register(face, face === 'host'
+                        ? hostExportSubpaths(manifest)
+                        : clientExportSubpaths(manifest)));
                 }
             }
         }
@@ -870,6 +897,7 @@ class FaceAnalyzer {
         if ((method.typeParameters?.length ?? 0) > 0) {
             this.fail(method, 'generic Remote methods are not supported');
         }
+        const documentation = documentationOf(method);
         const methodName = method.name.text;
         const exportedMethod = invocation.exportName ?? methodName;
         const lookups = this.lookupDeclarations();
@@ -934,7 +962,8 @@ class FaceAnalyzer {
             if (wires.has(modeled.wire))
                 this.fail(parameter, `duplicate Remote wire field ${modeled.wire}`);
             wires.add(modeled.wire);
-            parameters.push(modeled);
+            const description = documentation.tags.find(tag => tag.name === 'param' && tag.argument === modeled.name)?.comment?.replace(/^[-—–]\s*/, '');
+            parameters.push({ ...modeled, ...(description === undefined ? {} : { description }) });
         }
         let receiver = { kind: 'direct' };
         if (invocation.kind === 'context') {
@@ -975,6 +1004,7 @@ class FaceAnalyzer {
                 boundary: this.remoteBoundary(uplinkType, `${registration.name}#${binding.namespace}/${exportedMethod}:uplink`, false, 'undefined'),
             };
         return {
+            ...documentation,
             id: `${registration.name}#${binding.namespace}/${exportedMethod}`,
             service: binding.service,
             namespace: binding.namespace,
@@ -1101,35 +1131,29 @@ class FaceAnalyzer {
                     marker = { kind: 'direct', exportName };
                 }
                 else {
-                    if (!ts.isObjectLiteralExpression(argument) || argument.properties.length !== 1) {
-                        this.fail(argument, 'Remote() options must contain exactly mode: "stream"');
-                    }
-                    const [property] = argument.properties;
-                    if (property === undefined)
-                        this.fail(argument, 'Remote() options must contain exactly mode: "stream"');
-                    const mode = ts.isPropertyAssignment(property) && memberName(property.name) === 'mode'
-                        ? stringLiteralValue(property.initializer)
-                        : undefined;
-                    if (mode !== 'stream')
-                        this.fail(property, 'Remote() options must contain exactly mode: "stream"');
-                    marker = { kind: 'direct', mode };
+                    marker = { kind: 'direct', ...this.remoteOptions(argument, 'Remote') };
                 }
             }
             else if (ts.isCallExpression(expression)
                 && this.isTypeMetaSymbol(expression.expression, 'RemoteScope')) {
                 if (expression.arguments.length < 1 || expression.arguments.length > 2) {
-                    this.fail(expression, 'RemoteScope() requires a Context key and optional exported method name');
+                    this.fail(expression, 'RemoteScope() requires a Context key and an optional exported method name or options object');
                 }
                 const context = stringLiteralValue(expression.arguments[0]);
                 if (context === undefined || !isRemoteSegment(context)) {
                     this.fail(expression.arguments[0] ?? expression, 'RemoteScope() key must be a string literal containing only RPC endpoint segment characters');
                 }
-                const exportArgument = expression.arguments[1];
-                const exportName = exportArgument === undefined ? undefined : stringLiteralValue(exportArgument);
-                if (exportArgument !== undefined && (exportName === undefined || !isRemoteSegment(exportName))) {
-                    this.fail(exportArgument, 'RemoteScope() name must be a string literal containing only RPC endpoint segment characters');
+                const option = expression.arguments[1];
+                const exportName = option === undefined ? undefined : stringLiteralValue(option);
+                if (option === undefined || exportName !== undefined) {
+                    if (exportName !== undefined && !isRemoteSegment(exportName)) {
+                        this.fail(option ?? expression, 'RemoteScope() name must be a string literal containing only RPC endpoint segment characters');
+                    }
+                    marker = { kind: 'context', context, ...exportName === undefined ? {} : { exportName } };
+                }
+                else {
+                    marker = { kind: 'context', context, ...this.remoteOptions(option, 'RemoteScope') };
                 }
-                marker = { kind: 'context', context, ...exportName === undefined ? {} : { exportName } };
             }
             else {
                 continue;
@@ -1140,6 +1164,38 @@ class FaceAnalyzer {
         }
         return found;
     }
+    /**
+     * Read the options object of `@Remote` or `@RemoteScope`. `resources`
+     * accepts any expression: its readers run only at runtime, where the
+     * Gateway reads them from the prototype descriptor, so generation records
+     * nothing for them.
+     */
+    remoteOptions(argument, decorator) {
+        const requirement = decorator === 'Remote'
+            ? 'Remote() options require name, mode: "stream", or resources'
+            : 'RemoteScope() options require name or resources';
+        if (!ts.isObjectLiteralExpression(argument) || argument.properties.length === 0)
+            this.fail(argument, requirement);
+        let options = {};
+        for (const property of argument.properties) {
+            if (!ts.isPropertyAssignment(property))
+                this.fail(property, `${decorator}() options must use named values`);
+            const name = memberName(property.name);
+            if (decorator === 'Remote' && name === 'mode' && stringLiteralValue(property.initializer) === 'stream') {
+                options = { ...options, mode: 'stream' };
+            }
+            else if (name === 'name') {
+                const value = stringLiteralValue(property.initializer);
+                if (value === undefined || !isRemoteSegment(value))
+                    this.fail(property, `${decorator}() name must be an endpoint segment`);
+                options = { ...options, exportName: value };
+            }
+            else if (name !== 'resources') {
+                this.fail(property, requirement);
+            }
+        }
+        return options;
+    }
     /**
      * The item types a Remote method's authored return type declares. Unary
      * methods unwrap `Promise<T>`; stream methods unwrap `Iterable<Out>`,
@@ -1359,6 +1415,12 @@ class FaceAnalyzer {
                     completed.set(type, id);
                     return id;
                 };
+                const alias = type.aliasSymbol;
+                const aliasDeclaration = alias === undefined ? undefined : preferredDeclaration(this.resolveSymbol(alias));
+                if (alias?.name === 'JsonValue' && aliasDeclaration !== undefined
+                    && this.registrationForFile(aliasDeclaration.getSourceFile().fileName)?.name === '@deepseek-ai/dsh-util-values') {
+                    return add({ kind: 'keyword', name: 'unknown', json: true });
+                }
                 const flags = type.flags;
                 if (this.isRemoteByteArray(type)) {
                     return add({ kind: 'reference', name: 'Uint8Array', target: { kind: 'standard', name: 'Uint8Array' }, arguments: [] });
@@ -1402,9 +1464,23 @@ class FaceAnalyzer {
                     const value = type.intrinsicName === 'true';
                     return add({ kind: 'literal', value, text: String(value) });
                 }
-                if (type.isUnionOrIntersection()) {
+                if (type.isIntersection()) {
+                    const material = type.types.filter(member => !this.isRemotePhantomConstraint(member));
+                    if (material.length === 1) {
+                        const projected = convert(material[0]);
+                        const { id: _projectedId, ...value } = this.nodes.get(projected);
+                        return add(value);
+                    }
+                    // Object intersections contribute one request object; closing each operand
+                    // separately would reject fields declared by its sibling operands.
+                    if (!material.every(member => (member.flags & ts.TypeFlags.Object) !== 0
+                        && !this.checker.isArrayType(member) && !this.checker.isTupleType(member))) {
+                        return add({ kind: 'intersection', types: material.map(convert) });
+                    }
+                }
+                else if (type.isUnion()) {
                     return add({
-                        kind: (flags & ts.TypeFlags.Union) !== 0 ? 'union' : 'intersection',
+                        kind: 'union',
                         types: type.types.map(convert),
                     });
                 }
@@ -1447,7 +1523,7 @@ class FaceAnalyzer {
                     const propertyType = this.checker.getTypeOfSymbolAtLocation(property, declaration ?? authoredType);
                     const symbolKey = property.getName();
                     members.push({
-                        ...EMPTY_DOCUMENTATION,
+                        ...(declaration === undefined ? EMPTY_DOCUMENTATION : documentationOf(declaration)),
                         id: `${id}#${symbolKey}`,
                         name: symbolKey,
                         ...(symbolKey.startsWith('__@') ? { computed: 'symbol' } : {}),
@@ -2427,12 +2503,26 @@ function mergeWorkspaceModels(models) {
         crossFaceLinks: [...links.values()].sort(compareCrossFaceLinks),
     };
 }
-function parseConfig(path) {
+/** {@link ts.sys} config reads without directory listing, so `include` patterns match no files. */
+const UNLISTED_CONFIG_HOST = {
+    useCaseSensitiveFileNames: ts.sys.useCaseSensitiveFileNames,
+    readDirectory: () => [],
+    fileExists: file => ts.sys.fileExists(file),
+    readFile: file => ts.sys.readFile(file),
+};
+function parseConfig(path, aggregate = false) {
     const compilerPath = path.split(sep).join('/');
     const read = ts.readConfigFile(compilerPath, file => ts.sys.readFile(file));
     if (read.error !== undefined)
         throw new TypertAnalysisError(formatDiagnostic(read.error));
-    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(compilerPath), undefined, compilerPath);
+    // Include expansion only fills `fileNames`, and TypeScript reports missing
+    // inputs only for a config without `files` or `references`; skipping it for
+    // an aggregate with `references` keeps diagnostics, options, and references.
+    const raw = read.config;
+    const host = aggregate && typeof raw === 'object' && raw !== null && Object.hasOwn(raw, 'references')
+        ? UNLISTED_CONFIG_HOST
+        : ts.sys;
+    const parsed = ts.parseJsonConfigFileContent(read.config, host, dirname(compilerPath), undefined, compilerPath);
     if (parsed.errors.length > 0)
         throw new TypertAnalysisError(parsed.errors.map(formatDiagnostic).join('\n'));
     return { path, parsed };
@@ -2908,6 +2998,47 @@ function isWithin(path, root) {
 function slash(value) {
     return value.replaceAll('\\', '/');
 }
+function rejectBuildOutputLoads(face, root, aggregatePath, loads, unresolved) {
+    if (loads.length === 0 && unresolved.length === 0)
+        return;
+    const path = (file) => slash(relative(root, file));
+    const config = path(aggregatePath);
+    const lines = [];
+    const addAlias = (specifier, source) => {
+        lines.push(`    add ${JSON.stringify(specifier)}: [${JSON.stringify(`./${path(source)}`)}] to the compilerOptions.paths of ${config} or the config it extends`);
+    };
+    if (unresolved.length > 0) {
+        lines.push(`typert(${face}): the ${face} program cannot resolve workspace imports, which would analyze as unknown types; map each import below to source:`);
+        for (const entry of unresolved) {
+            lines.push(`  '${entry.specifier}' imported by ${path(entry.file)}`);
+            if (entry.source === undefined)
+                lines.push(`    add a compilerOptions.paths alias for it to ${config} or the config it extends`);
+            else
+                addAlias(entry.specifier, entry.source);
+        }
+    }
+    if (loads.length > 0) {
+        lines.push(`typert(${face}): the ${face} program loads workspace build outputs instead of source; resolve each import below to source so that generation does not depend on package compilation:`);
+    }
+    for (const load of loads) {
+        lines.push(`  ${path(load.file)}`);
+        if (load.importers.length === 0) {
+            lines.push('    no program source imports it directly; another build output or a reference directive loads it');
+        }
+        for (const importer of load.importers) {
+            lines.push(`    imported as '${importer.specifier}' by ${path(importer.file)}`);
+        }
+        const specifiers = [...new Set(load.importers.map(importer => importer.specifier))];
+        if (load.source === undefined) {
+            lines.push('    no workspace source compiles to it; import a source module instead');
+        }
+        else {
+            for (const specifier of specifiers)
+                addAlias(specifier, load.source);
+        }
+    }
+    throw new TypertAnalysisError(lines.join('\n'));
+}
 function uniqueBy(values, key) {
     const result = new Map();
     for (const value of values)

package/lib/types/artifact-files.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-local files of generated Typert artifacts. The tsdown plugin and
+ * standalone workspace generation both write through this module, so a pass
+ * over the same artifacts leaves the same bytes on disk.
+ * @module @deepseek-ai/dsh-typert-generator/artifact-files
+ */
+import type { WorkspaceEmitResult } from './workspace.ts';
+/**
+ * Write one package's artifacts under `<packageDir>/lib`: `typert.<face>.js`
+ * and `typert.<face>.d.ts` per artifact, plus the three
+ * `typert.remote-client.*` files when an artifact carries Remote methods. A
+ * Host artifact without Remote methods removes any Remote client files left
+ * by an earlier pass. Files are written one by one, so a failed write can
+ * leave this package's outputs partially replaced.
+ * @param packageDir - absolute package root.
+ * @param artifacts - artifacts of that package only.
+ * @throws A file-system error when the output directory or a file cannot be written.
+ */
+export declare function writePackageArtifacts(packageDir: string, artifacts: readonly WorkspaceEmitResult[]): void;
+/**
+ * Write every artifact of one workspace pass into its own package, in
+ * artifact order, with {@link writePackageArtifacts}. A failed write stops
+ * the pass; earlier packages keep their new files and later ones keep their
+ * previous files.
+ * @param root - workspace root that each artifact's `packageRoot` is relative to.
+ * @param artifacts - artifacts returned by one `WorkspaceTypertGenerator` pass.
+ * @throws A file-system error when an output directory or file cannot be written.
+ */
+export declare function writeWorkspaceArtifacts(root: string, artifacts: readonly WorkspaceEmitResult[]): void;
+//# sourceMappingURL=artifact-files.d.ts.map

package/lib/types/artifact-files.js

@@ -0,0 +1,57 @@
+/**
+ * Package-local files of generated Typert artifacts. The tsdown plugin and
+ * standalone workspace generation both write through this module, so a pass
+ * over the same artifacts leaves the same bytes on disk.
+ * @module @deepseek-ai/dsh-typert-generator/artifact-files
+ */
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const REMOTE_CLIENT_FILES = [
+    'typert.remote-client.js',
+    'typert.remote-client.d.ts',
+    'typert.remote-client.d.ts.map',
+];
+/**
+ * Write one package's artifacts under `<packageDir>/lib`: `typert.<face>.js`
+ * and `typert.<face>.d.ts` per artifact, plus the three
+ * `typert.remote-client.*` files when an artifact carries Remote methods. A
+ * Host artifact without Remote methods removes any Remote client files left
+ * by an earlier pass. Files are written one by one, so a failed write can
+ * leave this package's outputs partially replaced.
+ * @param packageDir - absolute package root.
+ * @param artifacts - artifacts of that package only.
+ * @throws A file-system error when the output directory or a file cannot be written.
+ */
+export function writePackageArtifacts(packageDir, artifacts) {
+    const output = join(packageDir, 'lib');
+    mkdirSync(output, { recursive: true });
+    let emittedRemote = false;
+    for (const artifact of artifacts) {
+        writeFileSync(join(output, `typert.${artifact.face}.js`), artifact.js);
+        writeFileSync(join(output, `typert.${artifact.face}.d.ts`), artifact.dts);
+        if (artifact.remote !== undefined) {
+            emittedRemote = true;
+            writeFileSync(join(output, 'typert.remote-client.js'), artifact.remote.js);
+            writeFileSync(join(output, 'typert.remote-client.d.ts'), artifact.remote.dts);
+            writeFileSync(join(output, 'typert.remote-client.d.ts.map'), artifact.remote.dtsMap);
+        }
+    }
+    if (!emittedRemote && artifacts.some(artifact => artifact.face === 'host')) {
+        for (const file of REMOTE_CLIENT_FILES)
+            rmSync(join(output, file), { force: true });
+    }
+}
+/**
+ * Write every artifact of one workspace pass into its own package, in
+ * artifact order, with {@link writePackageArtifacts}. A failed write stops
+ * the pass; earlier packages keep their new files and later ones keep their
+ * previous files.
+ * @param root - workspace root that each artifact's `packageRoot` is relative to.
+ * @param artifacts - artifacts returned by one `WorkspaceTypertGenerator` pass.
+ * @throws A file-system error when an output directory or file cannot be written.
+ */
+export function writeWorkspaceArtifacts(root, artifacts) {
+    for (const artifact of artifacts)
+        writePackageArtifacts(join(root, artifact.packageRoot), [artifact]);
+}
+//# sourceMappingURL=artifact-files.js.map

package/lib/types/build-output-guard.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Detection of workspace build outputs loaded into an analyzed face program,
+ * and of workspace imports that resolve to nothing. Typert reads workspace
+ * packages only from source when a caller rejects build outputs, so its
+ * result cannot depend on whether, or when, package compilation ran: an
+ * import that reaches `lib/` on a compiled tree resolves to nothing on a
+ * clean one, and both are rejected.
+ * @module @deepseek-ai/dsh-typert-generator/build-output-guard
+ */
+import ts from 'typescript';
+/** One program file that a workspace package's `lib/` holds, with the imports that load it. */
+export interface BuildOutputLoad {
+    /** Absolute path of the build output. */
+    readonly file: string;
+    /** Program files outside build outputs whose import specifier resolves to {@link file}. */
+    readonly importers: readonly BuildOutputImporter[];
+    /** Absolute path of the workspace source compiled to {@link file}, when one exists. */
+    readonly source: string | undefined;
+}
+/** One import of a build output from a program file outside build outputs. */
+export interface BuildOutputImporter {
+    /** Absolute path of the importing file. */
+    readonly file: string;
+    /** Import specifier as written. */
+    readonly specifier: string;
+}
+/**
+ * List the program files that a workspace package holds under its `lib/`
+ * directory. A package is the nearest directory with a `package.json` at or
+ * below `root`; files under `node_modules` are external. Importers are found
+ * by resolving each program file's import specifiers again, so this pass
+ * costs extra only when an output is present.
+ * @param program - the analyzed face program.
+ * @param root - workspace root.
+ * @param host - module resolution host of the program.
+ * @returns loads in file-path order; empty when every workspace file comes from source.
+ */
+export declare function findBuildOutputLoads(program: ts.Program, root: string, host: ts.ModuleResolutionHost): BuildOutputLoad[];
+/** One import of a workspace package from a program source file that module resolution cannot resolve. */
+export interface UnresolvedWorkspaceImport {
+    /** Absolute path of the importing file. */
+    readonly file: string;
+    /** Import specifier as written. */
+    readonly specifier: string;
+    /** Absolute path of the workspace source the specifier's package export compiles from, when one exists. */
+    readonly source: string | undefined;
+}
+/**
+ * List the imports in workspace program files that name a workspace package
+ * and resolve to nothing. A workspace package is one whose `node_modules` link,
+ * found from the importing file's directories, leads inside `root` outside any
+ * `node_modules`; without that link or a `paths` alias the package cannot be
+ * identified, and type checking reports the import. The source of a subpath is
+ * derived from the package's `exports` `types` condition under `lib/types/`.
+ * @param program - the analyzed face program.
+ * @param root - workspace root.
+ * @param host - module resolution host of the program.
+ * @returns unresolved imports in file and specifier order.
+ */
+export declare function findUnresolvedWorkspaceImports(program: ts.Program, root: string, host: ts.ModuleResolutionHost): UnresolvedWorkspaceImport[];
+//# sourceMappingURL=build-output-guard.d.ts.map