typespun-codegen 0.0.4

package/dist/cli/main.js

@@ -0,0 +1,157 @@
+import { generateProject } from '../generate.js';
+import { formatDiagnostic } from './diagnostics.js';
+import { initializeProject } from './init.js';
+const HELP = `Usage: typespun <command> [options]
+
+Commands:
+  init       Initialize a Typespun project
+  generate   Generate the typed configuration loader
+  check      Check that generated output is current
+
+Options:
+  -h, --help              Show help
+
+Init options:
+  --style interface|class
+  --input <path>
+  --output <path>
+  --env-prefix <prefix>
+
+Generate/check options:
+  --config <path>
+`;
+class UsageError extends Error {
+}
+export async function runCli(args, streams = process, cwd = process.cwd()) {
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        streams.stdout.write(HELP);
+        return 0;
+    }
+    try {
+        const [command, ...commandArgs] = args;
+        if (command === 'generate' || command === 'check') {
+            if (isHelpOnly(commandArgs)) {
+                streams.stdout.write(HELP);
+                return 0;
+            }
+            const configPath = parseConfigArguments(commandArgs);
+            const result = await generateProject({
+                projectDirectory: cwd,
+                mode: command === 'generate' ? 'write' : 'check',
+                ...(configPath === undefined ? {} : { configPath }),
+            });
+            const color = streams.stderr.isTTY === true && process.env.NO_COLOR === undefined;
+            for (const warning of result.warnings) {
+                streams.stderr.write(`${formatDiagnostic(warning, { cwd, color })}\n`);
+            }
+            for (const diagnostic of result.diagnostics) {
+                streams.stderr.write(`${formatDiagnostic(diagnostic, { cwd, color })}\n`);
+            }
+            if (result.diagnostics.length > 0) {
+                return result.diagnostics.some((diagnostic) => diagnostic.code === 'typescript_config')
+                    ? 2
+                    : 1;
+            }
+            if (result.status === 'stale') {
+                streams.stderr.write(`${relativeOutput(result.outputPath, cwd)} is stale; run typespun generate.\n`);
+                return 1;
+            }
+            streams.stdout.write(command === 'generate'
+                ? `${result.status === 'written' ? 'Generated' : 'Unchanged'} ${relativeOutput(result.outputPath, cwd)}.\n`
+                : `${relativeOutput(result.outputPath, cwd)} is up to date.\n`);
+            return 0;
+        }
+        if (command === 'init') {
+            if (isHelpOnly(commandArgs)) {
+                streams.stdout.write(HELP);
+                return 0;
+            }
+            const result = await initializeProject(cwd, parseInitArguments(commandArgs));
+            for (const line of result.messages)
+                streams.stdout.write(`${line}\n`);
+            for (const line of result.warnings)
+                streams.stderr.write(`${line}\n`);
+            const color = streams.stderr.isTTY === true && process.env.NO_COLOR === undefined;
+            for (const diagnostic of result.diagnostics) {
+                streams.stderr.write(`${formatDiagnostic(diagnostic, { cwd, color })}\n`);
+            }
+            return result.exitCode;
+        }
+        throw new UsageError(`Unknown command: ${command ?? ''}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        streams.stderr.write(`typespun: ${message}\n`);
+        if (error instanceof UsageError || isProjectConfigurationError(error)) {
+            streams.stderr.write('Run typespun --help for usage.\n');
+            return 2;
+        }
+        return 1;
+    }
+}
+function parseConfigArguments(args) {
+    let configPath;
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (argument !== '--config')
+            throw new UsageError(`Unknown option: ${argument}`);
+        if (configPath !== undefined)
+            throw new UsageError('--config may be specified only once');
+        configPath = requiredValue(args, ++index, '--config');
+    }
+    return configPath;
+}
+function parseInitArguments(args) {
+    const options = {};
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (argument === '--style') {
+            const style = requiredValue(args, ++index, argument);
+            if (style !== 'interface' && style !== 'class') {
+                throw new UsageError('--style must be interface or class');
+            }
+            if (options.style !== undefined)
+                throw new UsageError('--style may be specified only once');
+            options.style = style;
+        }
+        else if (argument === '--input') {
+            options.input = uniqueValue(options.input, requiredValue(args, ++index, argument), argument);
+        }
+        else if (argument === '--output') {
+            options.output = uniqueValue(options.output, requiredValue(args, ++index, argument), argument);
+        }
+        else if (argument === '--env-prefix') {
+            options.envPrefix = uniqueValue(options.envPrefix, requiredValue(args, ++index, argument), argument);
+        }
+        else {
+            throw new UsageError(`Unknown option: ${argument}`);
+        }
+    }
+    return options;
+}
+function requiredValue(args, index, flag) {
+    const value = args[index];
+    if (value === undefined || value.length === 0 || value.startsWith('--')) {
+        throw new UsageError(`${flag} requires a value`);
+    }
+    return value;
+}
+function uniqueValue(previous, value, flag) {
+    if (previous !== undefined)
+        throw new UsageError(`${flag} may be specified only once`);
+    return value;
+}
+function isHelpOnly(args) {
+    return args.length === 1 && (args[0] === '--help' || args[0] === '-h');
+}
+function isProjectConfigurationError(error) {
+    if (!(error instanceof Error))
+        return false;
+    return (error.name === 'ProjectConfigError' ||
+        error.name === 'ProjectDiscoveryError' ||
+        error.name === 'InitProjectError' ||
+        error.message.startsWith('Could not find tsconfig.json'));
+}
+function relativeOutput(path, cwd) {
+    return (path.startsWith(cwd) ? path.slice(cwd.length + 1) : path) || path;
+}

package/dist/contracts.d.ts

@@ -0,0 +1,33 @@
+import type { FieldKind, FieldSchema } from 'typespun/generated';
+export interface SourceLocation {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+}
+export interface Diagnostic {
+    readonly code: string;
+    readonly message: string;
+    readonly location: SourceLocation;
+    readonly suggestion?: string;
+}
+export interface FieldIR extends FieldSchema {
+    readonly location: SourceLocation;
+    readonly kind: FieldKind;
+}
+export type RootExport = {
+    readonly kind: 'named';
+    readonly name: string;
+} | {
+    readonly kind: 'default';
+};
+export interface AnalyzeResult {
+    readonly inputPath: string;
+    readonly rootName?: string;
+    /** The import binding for the selected root, present on successful analysis. */
+    readonly rootExport?: RootExport;
+    readonly fields: readonly FieldIR[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+export type UnknownKeysPolicy = 'error' | 'warn' | 'ignore';
+export type SecretDefaultsPolicy = 'warn' | 'allow' | 'error';
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,OAAQ,SAAQ,WAAW;IAC1C,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEjC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;CAC7C;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE5D,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC"}

package/dist/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/emitter/emit.d.ts

@@ -0,0 +1,13 @@
+import ts from 'typescript';
+import type { FieldIR, RootExport } from '../contracts.js';
+export interface EmitGeneratedModuleOptions {
+    readonly rootExport: RootExport;
+    readonly rootName: string;
+    readonly typeImport: string;
+    readonly fields: readonly FieldIR[];
+    readonly compiledDefaults: Readonly<Record<string, unknown>>;
+    readonly fingerprint: string;
+}
+export declare function emitGeneratedModule(options: EmitGeneratedModuleOptions): string;
+export declare function relativeTypeImportSpecifier(inputPath: string, outputPath: string, compilerOptions: ts.CompilerOptions): string;
+//# sourceMappingURL=emit.d.ts.map

package/dist/emitter/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/emitter/emit.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAG3D,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,MAAM,CAwBR;AAED,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,EAAE,CAAC,eAAe,GAClC,MAAM,CAUR"}

package/dist/emitter/emit.js

@@ -0,0 +1,65 @@
+import { dirname, extname, relative, sep } from 'node:path';
+import ts from 'typescript';
+import { stableJson } from './fingerprint.js';
+export function emitGeneratedModule(options) {
+    const fields = options.fields.map(stripLocation);
+    const schema = {
+        compiledDefaults: options.compiledDefaults,
+        fields,
+        protocolVersion: 1,
+    };
+    const typeImport = options.rootExport.kind === 'default'
+        ? `import type TypespunConfig from ${quote(options.typeImport)};`
+        : `import type { ${formatExportName(options.rootExport.name)} as TypespunConfig } from ${quote(options.typeImport)};`;
+    return `// Generated by typespun-codegen. Do not edit.
+// Schema fingerprint: ${options.fingerprint}
+
+import { createLoader, type GeneratedSchema } from 'typespun/generated';
+${typeImport}
+
+export type Config = TypespunConfig;
+
+const schema = ${stableJson(schema, 2)} as const satisfies GeneratedSchema;
+
+export const loadConfig = createLoader<Config>(schema);
+`;
+}
+export function relativeTypeImportSpecifier(inputPath, outputPath, compilerOptions) {
+    const relativePath = relative(dirname(outputPath), inputPath)
+        .split(sep)
+        .join('/');
+    const withoutExtension = relativePath.slice(0, -extname(relativePath).length);
+    const prefix = withoutExtension.startsWith('.')
+        ? withoutExtension
+        : `./${withoutExtension}`;
+    return `${prefix}${usesNodeEmittedSpecifiers(compilerOptions) ? emittedExtension(inputPath) : ''}`;
+}
+function stripLocation(field) {
+    const { location: _location, ...schemaField } = field;
+    return schemaField;
+}
+function usesNodeEmittedSpecifiers(options) {
+    return (options.moduleResolution === ts.ModuleResolutionKind.Node16 ||
+        options.moduleResolution === ts.ModuleResolutionKind.NodeNext ||
+        options.moduleResolution === ts.ModuleResolutionKind.Bundler ||
+        (options.moduleResolution === undefined &&
+            (options.module === ts.ModuleKind.Node16 ||
+                options.module === ts.ModuleKind.NodeNext)));
+}
+function emittedExtension(path) {
+    switch (extname(path)) {
+        case '.mts':
+            return '.mjs';
+        case '.cts':
+            return '.cjs';
+        default:
+            return '.js';
+    }
+}
+function formatExportName(name) {
+    return /^[$A-Z_a-z][$\w]*$/u.test(name) ? name : quote(name);
+}
+function quote(value) {
+    const json = stableJson(value);
+    return `'${json.slice(1, -1).replace(/'/g, "\\'").replace(/\\"/g, '"')}'`;
+}

package/dist/emitter/fingerprint.d.ts

@@ -0,0 +1,10 @@
+export interface FingerprintInput {
+    readonly protocolVersion: number;
+    readonly generatorVersion: string;
+    readonly configuration: unknown;
+    readonly analysis: unknown;
+    readonly compiledDefaults: unknown;
+}
+export declare function createFingerprint(input: FingerprintInput): string;
+export declare function stableJson(value: unknown, space?: number): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/emitter/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../src/emitter/fingerprint.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAEjE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjE"}

package/dist/emitter/fingerprint.js

@@ -0,0 +1,28 @@
+import { createHash } from 'node:crypto';
+export function createFingerprint(input) {
+    return createHash('sha256').update(stableJson(input)).digest('hex');
+}
+export function stableJson(value, space) {
+    return escapeLineSeparators(JSON.stringify(canonicalize(value), null, space));
+}
+function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalize(item));
+    }
+    if (isRecord(value)) {
+        const result = {};
+        for (const key of Object.keys(value).sort()) {
+            if (value[key] !== undefined) {
+                result[key] = canonicalize(value[key]);
+            }
+        }
+        return result;
+    }
+    return value;
+}
+function escapeLineSeparators(value) {
+    return value.replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/generate.d.ts

@@ -0,0 +1,29 @@
+import type { Diagnostic } from './contracts.js';
+import { type FingerprintInput } from './emitter/fingerprint.js';
+import { type DefaultsDiagnostic } from './project/defaults.js';
+export interface GenerateProjectOptions {
+    readonly configPath?: string;
+    readonly projectDirectory?: string;
+    readonly mode: 'write' | 'check';
+}
+export interface GenerationIoDiagnostic {
+    readonly code: 'defaults_read_failed';
+    readonly file: string;
+    readonly path: string;
+    readonly message: string;
+}
+export interface GenerationSafetyDiagnostic {
+    readonly code: 'overlapping_paths';
+    readonly message: string;
+}
+export type GenerateDiagnostic = Diagnostic | DefaultsDiagnostic | GenerationIoDiagnostic | GenerationSafetyDiagnostic;
+export interface GenerateResult {
+    readonly status: 'unchanged' | 'written' | 'stale';
+    readonly outputPath: string;
+    readonly warnings: readonly GenerateDiagnostic[];
+    readonly diagnostics: readonly GenerateDiagnostic[];
+}
+export declare function generateProject(options: GenerateProjectOptions): Promise<GenerateResult>;
+export declare function createGenerationFingerprint(input: Omit<FingerprintInput, 'generatorVersion'>, packageJsonUrl?: URL): string;
+export declare function atomicWrite(path: string, contents: string, temporaryPathForAttempt?: (attempt: number) => string): Promise<void>;
+//# sourceMappingURL=generate.d.ts.map

package/dist/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,UAAU,EAAW,MAAM,gBAAgB,CAAC;AAK1D,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,0BAA0B,CAAC;AAKlC,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAM/B,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,kBAAkB,GAClB,sBAAsB,GACtB,0BAA0B,CAAC;AAE/B,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACrD;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,cAAc,CAAC,CA4GzB;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,EACjD,cAAc,GAAE,GAAsB,GACrC,MAAM,CAYR;AA0ED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,uBAAuB,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MACI,GACjD,OAAO,CAAC,IAAI,CAAC,CA8Bf"}

package/dist/generate.js

@@ -0,0 +1,267 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { mkdir, open, readFile, realpath, rename, stat, unlink, } from 'node:fs/promises';
+import { basename, dirname, relative, resolve, sep } from 'node:path';
+import ts from 'typescript';
+import { analyzeProgram } from './analyzer/analyze.js';
+import { emitGeneratedModule, relativeTypeImportSpecifier, } from './emitter/emit.js';
+import { createFingerprint, } from './emitter/fingerprint.js';
+import { loadProjectConfig, } from './project/config.js';
+import { compileDefaults, } from './project/defaults.js';
+const PROTOCOL_VERSION = 1;
+const TEMPORARY_ATTEMPTS = 8;
+const PACKAGE_JSON_URL = new URL('../package.json', import.meta.url);
+export async function generateProject(options) {
+    const projectDirectory = resolve(options.projectDirectory ?? process.cwd());
+    const config = loadProjectConfig({
+        projectDirectory,
+        ...(options.configPath === undefined
+            ? {}
+            : { configPath: options.configPath }),
+    });
+    if (await referToSameFile(config.inputPath, config.outputPath)) {
+        return failedResult(config.outputPath, [
+            {
+                code: 'overlapping_paths',
+                message: 'The schema input and generated output must be different files.',
+            },
+        ]);
+    }
+    const programResult = createProjectProgram(config);
+    if (programResult.diagnostics.length > 0) {
+        return failedResult(config.outputPath, programResult.diagnostics);
+    }
+    const analysis = analyzeProgram(programResult.program, config.inputPath, config.envPrefix);
+    if (analysis.diagnostics.length > 0 ||
+        analysis.rootName === undefined ||
+        analysis.rootExport === undefined) {
+        return failedResult(config.outputPath, analysis.diagnostics);
+    }
+    const defaultsDocument = config.defaultsPath === undefined
+        ? { path: config.inputPath, content: '{}' }
+        : await readDefaults(config.defaultsPath);
+    if ('diagnostic' in defaultsDocument) {
+        return failedResult(config.outputPath, [defaultsDocument.diagnostic]);
+    }
+    const defaults = compileDefaults({
+        path: defaultsDocument.path,
+        content: defaultsDocument.content,
+    }, analysis.fields, {
+        unknownKeys: config.unknownKeys,
+        secretDefaults: config.secretDefaults,
+    });
+    if (defaults.errors.length > 0) {
+        return failedResult(config.outputPath, defaults.errors, defaults.warnings);
+    }
+    const portableConfig = normalizeConfiguration(config);
+    const typeImport = relativeTypeImportSpecifier(config.inputPath, config.outputPath, programResult.program.getCompilerOptions());
+    const portableAnalysis = {
+        rootExport: analysis.rootExport,
+        fields: analysis.fields.map(withoutLocation),
+        typeImport,
+    };
+    const fingerprint = createGenerationFingerprint({
+        protocolVersion: PROTOCOL_VERSION,
+        configuration: portableConfig,
+        analysis: portableAnalysis,
+        compiledDefaults: defaults.values,
+    });
+    const canonical = emitGeneratedModule({
+        rootExport: analysis.rootExport,
+        rootName: analysis.rootName,
+        typeImport,
+        fields: analysis.fields,
+        compiledDefaults: defaults.values,
+        fingerprint,
+    });
+    const existing = await readExisting(config.outputPath);
+    if (existing === canonical) {
+        return {
+            status: 'unchanged',
+            outputPath: config.outputPath,
+            warnings: defaults.warnings,
+            diagnostics: [],
+        };
+    }
+    if (options.mode === 'check') {
+        return {
+            status: 'stale',
+            outputPath: config.outputPath,
+            warnings: defaults.warnings,
+            diagnostics: [],
+        };
+    }
+    await atomicWrite(config.outputPath, canonical);
+    return {
+        status: 'written',
+        outputPath: config.outputPath,
+        warnings: defaults.warnings,
+        diagnostics: [],
+    };
+}
+export function createGenerationFingerprint(input, packageJsonUrl = PACKAGE_JSON_URL) {
+    const manifest = JSON.parse(readFileSync(packageJsonUrl, 'utf8'));
+    if (typeof manifest !== 'object' ||
+        manifest === null ||
+        !('version' in manifest) ||
+        typeof manifest.version !== 'string' ||
+        manifest.version.length === 0) {
+        throw new Error('typespun-codegen package version is missing');
+    }
+    return createFingerprint({ ...input, generatorVersion: manifest.version });
+}
+function createProjectProgram(config) {
+    const loaded = ts.readConfigFile(config.tsconfigPath, ts.sys.readFile);
+    if (loaded.error !== undefined) {
+        return {
+            program: ts.createProgram([], {}),
+            diagnostics: [typescriptConfigDiagnostic(config.tsconfigPath)],
+        };
+    }
+    const parsed = ts.parseJsonConfigFileContent(loaded.config, ts.sys, dirname(config.tsconfigPath), undefined, config.tsconfigPath);
+    if (parsed.errors.length > 0) {
+        return {
+            program: ts.createProgram([], parsed.options),
+            diagnostics: [typescriptConfigDiagnostic(config.tsconfigPath)],
+        };
+    }
+    const rootNames = Array.from(new Set([
+        ...parsed.fileNames.map((path) => resolve(path)),
+        resolve(config.inputPath),
+    ]));
+    return {
+        program: ts.createProgram(rootNames, parsed.options),
+        diagnostics: [],
+    };
+}
+function typescriptConfigDiagnostic(path) {
+    return {
+        code: 'typescript_config',
+        message: 'The TypeScript project configuration could not be loaded.',
+        location: { file: path, line: 1, column: 1 },
+    };
+}
+async function readDefaults(path) {
+    try {
+        return { path, content: await readFile(path, 'utf8') };
+    }
+    catch {
+        return {
+            diagnostic: {
+                code: 'defaults_read_failed',
+                file: path,
+                path: '',
+                message: 'The configured defaults file could not be read.',
+            },
+        };
+    }
+}
+async function readExisting(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+export async function atomicWrite(path, contents, temporaryPathForAttempt = (_attempt) => `${dirname(path)}/.typespun.${randomUUID()}.tmp`) {
+    await mkdir(dirname(path), { recursive: true });
+    let temporaryPath;
+    let handle;
+    for (let attempt = 0; attempt < TEMPORARY_ATTEMPTS; attempt++) {
+        const candidate = temporaryPathForAttempt(attempt);
+        try {
+            handle = await open(candidate, 'wx');
+            temporaryPath = candidate;
+            break;
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === 'EEXIST')
+                continue;
+            throw error;
+        }
+    }
+    if (handle === undefined || temporaryPath === undefined) {
+        throw new Error('Could not reserve a temporary generated-output file.');
+    }
+    let renamed = false;
+    try {
+        await handle.writeFile(contents, 'utf8');
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporaryPath, path);
+        renamed = true;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        if (!renamed)
+            await unlink(temporaryPath).catch(() => undefined);
+    }
+}
+function failedResult(outputPath, diagnostics, warnings = []) {
+    return { status: 'unchanged', outputPath, warnings, diagnostics };
+}
+function normalizeConfiguration(config) {
+    return {
+        input: portableRelative(config.configDirectory, config.inputPath),
+        output: portableRelative(config.configDirectory, config.outputPath),
+        tsconfig: portableRelative(config.configDirectory, config.tsconfigPath),
+        ...(config.defaultsPath === undefined
+            ? {}
+            : {
+                defaults: portableRelative(config.configDirectory, config.defaultsPath),
+            }),
+        ...(config.envPrefix === undefined ? {} : { envPrefix: config.envPrefix }),
+        unknownKeys: config.unknownKeys,
+        secretDefaults: config.secretDefaults,
+    };
+}
+async function referToSameFile(first, second) {
+    const [firstIdentity, secondIdentity] = await Promise.all([
+        fileIdentity(first),
+        fileIdentity(second),
+    ]);
+    if (firstIdentity.stat !== undefined &&
+        secondIdentity.stat !== undefined &&
+        firstIdentity.stat.dev === secondIdentity.stat.dev &&
+        firstIdentity.stat.ino === secondIdentity.stat.ino) {
+        return true;
+    }
+    return firstIdentity.canonicalPath === secondIdentity.canonicalPath;
+}
+async function fileIdentity(path) {
+    try {
+        return { canonicalPath: await realpath(path), stat: await stat(path) };
+    }
+    catch {
+        let ancestor = dirname(path);
+        const remainder = [basename(path)];
+        while (true) {
+            try {
+                return {
+                    canonicalPath: resolve(await realpath(ancestor), ...remainder),
+                };
+            }
+            catch {
+                const parent = dirname(ancestor);
+                if (parent === ancestor)
+                    return { canonicalPath: resolve(path) };
+                remainder.unshift(basename(ancestor));
+                ancestor = parent;
+            }
+        }
+    }
+}
+function portableRelative(from, to) {
+    return relative(from, to).split(sep).join('/');
+}
+function withoutLocation(field) {
+    const { location: _location, ...portable } = field;
+    return portable;
+}
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/** Public code-generation entry point. APIs will be added in the first implementation slice. */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,OAAO,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+/** Public code-generation entry point. APIs will be added in the first implementation slice. */
+export {};

package/dist/project/config.d.ts

@@ -0,0 +1,20 @@
+import type { SecretDefaultsPolicy, UnknownKeysPolicy } from '../contracts.js';
+export interface LoadProjectConfigOptions {
+    readonly projectDirectory: string;
+    readonly configPath?: string;
+}
+export interface ProjectConfigResult {
+    readonly configDirectory: string;
+    readonly inputPath: string;
+    readonly outputPath: string;
+    readonly tsconfigPath: string;
+    readonly defaultsPath?: string;
+    readonly envPrefix?: string;
+    readonly unknownKeys: UnknownKeysPolicy;
+    readonly secretDefaults: SecretDefaultsPolicy;
+}
+export declare class ProjectConfigError extends Error {
+    constructor(message: string);
+}
+export declare function loadProjectConfig(options: LoadProjectConfigOptions): ProjectConfigResult;
+//# sourceMappingURL=config.d.ts.map

package/dist/project/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/project/config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAO/E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,oBAAoB,CAAC;CAC/C;AA4BD,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,wBAAwB,GAChC,mBAAmB,CAuCrB"}