ushman-characterize 0.4.0

package/dist/rebind.js

@@ -0,0 +1,356 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import generate from '@babel/generator';
+import traverse from '@babel/traverse';
+import * as t from '@babel/types';
+import { parseModuleAst } from "./babel-config.js";
+import { recordCharacterizeValidatorResult, writeCharacterizeReport } from "./ledger.js";
+import { relativeImportPath } from "./shared.js";
+import { assertV4Workspace, pathExists } from "./workspace-paths.js";
+const GENERATED_REPLAY_HEADER = '// AUTO-GENERATED by ushman-characterize generate-replay.';
+const GENERATED_MODULE_SEGMENT = '.lab/characterize/modules';
+const importSpecifierName = (specifier) => t.isIdentifier(specifier.imported) ? specifier.imported.name : specifier.imported.value;
+const collectReplayTests = async (root) => {
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    const files = [];
+    for (const entry of entries) {
+        const resolved = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await collectReplayTests(resolved)));
+            continue;
+        }
+        if (entry.isFile() && entry.name.endsWith('.test.ts')) {
+            files.push(resolved);
+        }
+    }
+    return files.sort((left, right) => left.localeCompare(right));
+};
+const buildPreview = ({ after, before, filePath, }) => ({
+    after,
+    before,
+    filePath,
+});
+const isGeneratedReplayFile = (source) => source.startsWith(GENERATED_REPLAY_HEADER);
+const normalizePathFragment = (value) => value
+    .split(path.sep)
+    .join('/')
+    .replace(/^\.\/+/u, '');
+const splitMapping = (pair) => {
+    const separatorIndex = pair.indexOf('=');
+    if (separatorIndex <= 0 || separatorIndex === pair.length - 1) {
+        throw new Error(`Invalid --map value: ${pair}`);
+    }
+    return {
+        symbol: pair.slice(0, separatorIndex),
+        target: pair.slice(separatorIndex + 1),
+    };
+};
+const splitScopedSelector = (selector) => {
+    const separatorIndex = selector.lastIndexOf(':');
+    if (separatorIndex <= 0 || separatorIndex === selector.length - 1) {
+        return {
+            symbol: selector,
+            workspaceModule: null,
+        };
+    }
+    return {
+        symbol: selector.slice(separatorIndex + 1),
+        workspaceModule: normalizePathFragment(selector.slice(0, separatorIndex)),
+    };
+};
+export const parseRebindMapping = (pair) => {
+    const { symbol: selector, target } = splitMapping(pair);
+    const scopedSelector = splitScopedSelector(selector);
+    return {
+        selector: scopedSelector.workspaceModule
+            ? `${scopedSelector.workspaceModule}:${scopedSelector.symbol}`
+            : scopedSelector.symbol,
+        symbol: scopedSelector.symbol,
+        target,
+        workspaceModule: scopedSelector.workspaceModule,
+    };
+};
+const resolveValidatedTargetPath = async ({ targetPath, workspaceRoot, }) => {
+    const absoluteTarget = path.isAbsolute(targetPath)
+        ? path.resolve(targetPath)
+        : path.resolve(workspaceRoot, targetPath);
+    const relativeToWorkspace = path.relative(path.resolve(workspaceRoot), absoluteTarget);
+    if (relativeToWorkspace.startsWith('..') || path.isAbsolute(relativeToWorkspace)) {
+        throw new Error(`Rebind target path escapes the workspace root: ${targetPath}`);
+    }
+    if (!(await pathExists(absoluteTarget))) {
+        throw new Error(`Rebind target path does not exist: ${targetPath}`);
+    }
+    return absoluteTarget;
+};
+const toWorkspaceRelativePath = ({ filePath, workspaceRoot, }) => normalizePathFragment(path.relative(path.resolve(workspaceRoot), path.resolve(filePath)));
+const resolveWorkspaceModule = ({ filePath, importSource, workspaceRoot, }) => toWorkspaceRelativePath({
+    filePath: path.resolve(path.dirname(filePath), importSource),
+    workspaceRoot,
+});
+const collectGeneratedImportSpecifiers = ({ filePath, source, workspaceRoot, }) => {
+    if (!isGeneratedReplayFile(source)) {
+        return [];
+    }
+    const ast = parseModuleAst({
+        source,
+        sourcePath: filePath,
+    });
+    const specifiers = [];
+    traverse(ast, {
+        ImportDeclaration(importPath) {
+            if (importPath.node.importKind === 'type') {
+                return;
+            }
+            if (!importPath.node.source.value.includes(GENERATED_MODULE_SEGMENT)) {
+                return;
+            }
+            const workspaceModule = resolveWorkspaceModule({
+                filePath,
+                importSource: importPath.node.source.value,
+                workspaceRoot,
+            });
+            for (const specifier of importPath.node.specifiers) {
+                if (!t.isImportSpecifier(specifier) || specifier.importKind === 'type') {
+                    continue;
+                }
+                specifiers.push({
+                    filePath,
+                    importedName: importSpecifierName(specifier),
+                    localName: specifier.local.name,
+                    workspaceModule,
+                });
+            }
+        },
+    });
+    return specifiers;
+};
+const resolveMappings = async ({ files, mappings, workspaceRoot, }) => {
+    const importedSpecifiers = (await Promise.all(files.map(async (filePath) => collectGeneratedImportSpecifiers({
+        filePath,
+        source: await Bun.file(filePath).text(),
+        workspaceRoot,
+    })))).flat();
+    const symbolMatches = new Map();
+    for (const specifier of importedSpecifiers) {
+        for (const key of [specifier.importedName, specifier.localName]) {
+            const matches = symbolMatches.get(key) ?? new Set();
+            matches.add(specifier.workspaceModule);
+            symbolMatches.set(key, matches);
+        }
+    }
+    const resolvedMappings = await Promise.all([...mappings.entries()].map(async ([selector, target]) => {
+        const parsed = parseRebindMapping(`${selector}=${target}`);
+        const usedByGeneratedImport = importedSpecifiers.some((specifier) => (parsed.workspaceModule === null || parsed.workspaceModule === specifier.workspaceModule) &&
+            (parsed.symbol === specifier.importedName || parsed.symbol === specifier.localName));
+        return {
+            ...parsed,
+            absoluteTarget: usedByGeneratedImport
+                ? await resolveValidatedTargetPath({
+                    targetPath: parsed.target,
+                    workspaceRoot,
+                })
+                : path.resolve(workspaceRoot, parsed.target),
+        };
+    }));
+    for (const mapping of resolvedMappings) {
+        if (mapping.workspaceModule) {
+            continue;
+        }
+        const modules = symbolMatches.get(mapping.symbol);
+        if (modules && modules.size > 1) {
+            throw new Error(`Rebind mapping "${mapping.symbol}" is ambiguous across generated modules (${[...modules].sort().join(', ')}). Use <workspace-module>:${mapping.symbol}=... instead.`);
+        }
+    }
+    return resolvedMappings;
+};
+const lookupResolvedMapping = ({ localName, mappings, importedName, workspaceModule, }) => mappings.find((mapping) => mapping.workspaceModule === workspaceModule &&
+    (mapping.symbol === importedName || mapping.symbol === localName)) ??
+    mappings.find((mapping) => mapping.workspaceModule === null && (mapping.symbol === importedName || mapping.symbol === localName));
+const appendGroupedSpecifier = ({ declarationOrder, groupedSpecifiers, source, specifier, }) => {
+    const existingGroup = groupedSpecifiers.get(source);
+    if (!existingGroup) {
+        groupedSpecifiers.set(source, [t.cloneNode(specifier, true)]);
+        declarationOrder.push(source);
+        return;
+    }
+    existingGroup.push(t.cloneNode(specifier, true));
+};
+const groupImportSpecifiersBySource = ({ filePath, mappings, specifiers, sourceValue, workspaceModule, }) => {
+    const groupedSpecifiers = new Map();
+    const declarationOrder = [];
+    for (const specifier of specifiers) {
+        if (!t.isImportSpecifier(specifier)) {
+            appendGroupedSpecifier({
+                declarationOrder,
+                groupedSpecifiers,
+                source: sourceValue,
+                specifier,
+            });
+            continue;
+        }
+        if (specifier.importKind === 'type') {
+            appendGroupedSpecifier({
+                declarationOrder,
+                groupedSpecifiers,
+                source: sourceValue,
+                specifier,
+            });
+            continue;
+        }
+        const importedName = importSpecifierName(specifier);
+        const mapping = lookupResolvedMapping({
+            importedName,
+            localName: specifier.local.name,
+            mappings,
+            workspaceModule,
+        });
+        appendGroupedSpecifier({
+            declarationOrder,
+            groupedSpecifiers,
+            source: mapping
+                ? relativeImportPath({
+                    fromFile: filePath,
+                    toFile: mapping.absoluteTarget,
+                })
+                : sourceValue,
+            specifier,
+        });
+    }
+    return {
+        declarationOrder,
+        groupedSpecifiers,
+    };
+};
+const buildReplacementDeclarations = ({ declarationOrder, groupedSpecifiers, }) => declarationOrder.map((declarationSource) => t.importDeclaration(groupedSpecifiers.get(declarationSource) ?? [], t.stringLiteral(declarationSource)));
+const rewriteImportDeclarations = ({ filePath, mappings, source, workspaceRoot, }) => {
+    if (!isGeneratedReplayFile(source)) {
+        return null;
+    }
+    const ast = parseModuleAst({
+        source,
+        sourcePath: filePath,
+    });
+    const beforeImports = [];
+    const afterImports = [];
+    let changed = false;
+    traverse(ast, {
+        ImportDeclaration(importPath) {
+            if (importPath.node.importKind === 'type') {
+                return;
+            }
+            const sourceValue = importPath.node.source.value;
+            if (!sourceValue.includes(GENERATED_MODULE_SEGMENT)) {
+                return;
+            }
+            const workspaceModule = resolveWorkspaceModule({
+                filePath,
+                importSource: sourceValue,
+                workspaceRoot,
+            });
+            const { declarationOrder, groupedSpecifiers } = groupImportSpecifiersBySource({
+                filePath,
+                mappings,
+                sourceValue,
+                specifiers: importPath.node.specifiers,
+                workspaceModule,
+            });
+            if (declarationOrder.length === 1 && declarationOrder[0] === sourceValue) {
+                return;
+            }
+            beforeImports.push(generate(importPath.node, { comments: false }).code);
+            const replacementDeclarations = buildReplacementDeclarations({
+                declarationOrder,
+                groupedSpecifiers,
+            });
+            afterImports.push(replacementDeclarations
+                .map((declaration) => generate(declaration, { comments: false }).code)
+                .join('\n'));
+            importPath.replaceWithMultiple(replacementDeclarations);
+            importPath.skip();
+            changed = true;
+        },
+    });
+    if (!changed) {
+        return null;
+    }
+    const code = generate(ast, { comments: true, compact: false }).code;
+    parseModuleAst({
+        source: code,
+        sourcePath: filePath,
+    });
+    return {
+        code,
+        preview: buildPreview({
+            after: afterImports.join('\n'),
+            before: beforeImports.join('\n'),
+            filePath,
+        }),
+    };
+};
+/**
+ * Rewrite generated replay imports to point at extracted source modules.
+ */
+export const rewriteReplayImports = async ({ dryRun = false, mappings, workspaceRoot, yes = false, }) => {
+    await assertV4Workspace(workspaceRoot);
+    if (!dryRun && !yes) {
+        throw new Error('rewriteReplayImports modifies files in place. Re-run with yes=true or use dryRun=true.');
+    }
+    const replayRoot = path.join(workspaceRoot, 'tests', 'replay');
+    const files = await collectReplayTests(replayRoot);
+    const resolvedMappings = await resolveMappings({
+        files,
+        mappings,
+        workspaceRoot,
+    });
+    const touched = [];
+    const previews = [];
+    for (const filePath of files) {
+        const source = await Bun.file(filePath).text();
+        const rewritten = rewriteImportDeclarations({
+            filePath,
+            mappings: resolvedMappings,
+            source,
+            workspaceRoot,
+        });
+        if (!rewritten) {
+            continue;
+        }
+        touched.push(filePath);
+        previews.push(rewritten.preview);
+        if (!dryRun) {
+            await Bun.write(filePath, `${rewritten.code.trimEnd()}\n`);
+        }
+    }
+    const reportPath = await writeCharacterizeReport({
+        payload: {
+            dryRun,
+            files: touched,
+            mappingCount: mappings.size,
+            previews,
+            yes,
+        },
+        prefix: dryRun ? 'rebind-dry-run' : 'rebind',
+        workspaceRoot,
+    });
+    await recordCharacterizeValidatorResult({
+        affectedFiles: touched.map((filePath) => toWorkspaceRelativePath({
+            filePath,
+            workspaceRoot,
+        })),
+        metrics: {
+            dryRun,
+            mappingCount: mappings.size,
+            previewCount: previews.length,
+            touchedFiles: touched.length,
+        },
+        resultPath: reportPath,
+        summary: `${dryRun ? 'rebind dry-run previewed' : 'rebind rewrote'} ${touched.length} replay test file(s)`,
+        verdict: 'green',
+        workspaceRoot,
+    });
+    return {
+        files: touched,
+        previews,
+    };
+};

package/dist/replay-report.d.ts

@@ -0,0 +1,18 @@
+import { VERIFY_REPORT_SCHEMA_NAME, VERIFY_REPORT_SCHEMA_VERSION } from './constants.ts';
+export type VerifyReport = {
+    readonly exitCode: number;
+    readonly filter: null | string;
+    readonly generatedAt: string;
+    readonly mode: 'lenient' | 'strict';
+    readonly schemaName: typeof VERIFY_REPORT_SCHEMA_NAME;
+    readonly schemaVersion: typeof VERIFY_REPORT_SCHEMA_VERSION;
+    readonly success: boolean;
+    readonly workspaceRoot: string;
+};
+export declare const createVerifyReport: ({ exitCode, filter, mode, workspaceRoot, }: {
+    readonly exitCode: number;
+    readonly filter: null | string;
+    readonly mode: "lenient" | "strict";
+    readonly workspaceRoot: string;
+}) => VerifyReport;
+//# sourceMappingURL=replay-report.d.ts.map

package/dist/replay-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-report.d.ts","sourceRoot":"","sources":["../src/replay-report.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAGzF,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,OAAO,yBAAyB,CAAC;IACtD,QAAQ,CAAC,aAAa,EAAE,OAAO,4BAA4B,CAAC;IAC5D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,4CAKhC;IACC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,KAAG,YASF,CAAC"}

package/dist/replay-report.js

@@ -0,0 +1,12 @@
+import { VERIFY_REPORT_SCHEMA_NAME, VERIFY_REPORT_SCHEMA_VERSION } from "./constants.js";
+import { nowIso } from "./time.js";
+export const createVerifyReport = ({ exitCode, filter, mode, workspaceRoot, }) => ({
+    exitCode,
+    filter,
+    generatedAt: nowIso(),
+    mode,
+    schemaName: VERIFY_REPORT_SCHEMA_NAME,
+    schemaVersion: VERIFY_REPORT_SCHEMA_VERSION,
+    success: exitCode === 0,
+    workspaceRoot,
+});

package/dist/scene.d.ts

@@ -0,0 +1,24 @@
+import { canonicalizeSceneTree } from './trace-format.ts';
+export declare const scaffoldSceneCharacterizationTests: ({ dryRun, workspaceRoot, }: {
+    readonly dryRun?: boolean;
+    readonly workspaceRoot: string;
+}) => Promise<{
+    stale: string[];
+    written: string[];
+}>;
+export { canonicalizeSceneTree };
+type PopulateSmokeScaffoldsOptions = {
+    readonly workspaceDir: string;
+};
+export type PopulateSmokeScaffoldsResult = {
+    readonly sidecarPath: string;
+    readonly skipped: readonly string[];
+    readonly toolingGaps: readonly string[];
+    readonly written: readonly string[];
+};
+/**
+ * Populate seed-time `tests/smoke/<state>.test.ts` scaffolds once the shared smoke harness
+ * and parity baseline PNGs exist. Operator-edited scaffolds are preserved by sidecar hash.
+ */
+export declare const populateSmokeScaffolds: ({ workspaceDir, }: PopulateSmokeScaffoldsOptions) => Promise<PopulateSmokeScaffoldsResult>;
+//# sourceMappingURL=scene.d.ts.map

package/dist/scene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene.d.ts","sourceRoot":"","sources":["../src/scene.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,qBAAqB,EAAsD,MAAM,mBAAmB,CAAC;AA2B9G,eAAO,MAAM,kCAAkC,GAAU,4BAGtD;IACC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC;;;EA8DA,CAAC;AAEF,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAEjC,KAAK,6BAA6B,GAAG;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,CAAC;AA6CF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAAU,mBAE1C,6BAA6B,KAAG,OAAO,CAAC,4BAA4B,CAkItE,CAAC"}

package/dist/scene.js

@@ -0,0 +1,235 @@
+import { mkdir, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { recordCharacterizeToolingGap, recordCharacterizeValidatorResult } from "./ledger.js";
+import { hashSeedScaffoldContent, listFilesRecursive, loadSeedFingerprintSidecar, PARITY_BASELINE_RELATIVE_DIR, toWorkspaceRelativePath, updateSeedFingerprintSidecar, } from "./seed-scaffolds.js";
+import { relativeImportPath } from "./shared.js";
+import { canonicalizeSceneTree, ensureWorkspaceTraceHarness, workspaceHarnessPaths } from "./trace-format.js";
+import { assertV4Workspace, atomicWriteText } from "./workspace-paths.js";
+const slugify = (value) => value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, '-')
+    .replace(/^-+|-+$/gu, '');
+const readScreenshotsIndex = async (workspaceRoot) => {
+    const file = Bun.file(path.join(workspaceRoot, 'screenshots', 'index.json'));
+    if (!(await file.exists())) {
+        return [];
+    }
+    const parsed = (await file.json());
+    return parsed.captures ?? [];
+};
+const quote = (value) => JSON.stringify(value);
+export const scaffoldSceneCharacterizationTests = async ({ dryRun = false, workspaceRoot, }) => {
+    await assertV4Workspace(workspaceRoot);
+    const screenshots = await readScreenshotsIndex(workspaceRoot);
+    const testsDir = path.join(workspaceRoot, 'tests', 'scene');
+    const sceneCaptureDir = workspaceHarnessPaths(workspaceRoot).sceneFixturesDir;
+    await mkdir(testsDir, { recursive: true });
+    await mkdir(sceneCaptureDir, { recursive: true });
+    await ensureWorkspaceTraceHarness(workspaceRoot);
+    const written = [];
+    for (const capture of screenshots) {
+        const stateId = slugify(capture.label) || capture.folderName;
+        const baselinePath = path.join(workspaceRoot, 'screenshots', capture.folderName, 'scene-heavy.json');
+        if (!(await Bun.file(baselinePath).exists())) {
+            continue;
+        }
+        const filePath = path.join(testsDir, `${stateId}.test.ts`);
+        const harnessImport = relativeImportPath({
+            fromFile: filePath,
+            toFile: workspaceHarnessPaths(workspaceRoot).harnessFile,
+        });
+        const sceneOutputPath = path.join(sceneCaptureDir, `${stateId}.json`);
+        const source = `// AUTO-GENERATED by ushman-characterize stub-states. Do not hand-edit.
+import { expect, test } from 'bun:test';
+import { canonicalizeSceneTree } from ${quote(harnessImport)};
+
+const baseline = JSON.parse(await Bun.file(${quote(baselinePath)}).text());
+const outputPath = ${quote(sceneOutputPath)};
+
+const captureLive = async () => {
+  const result = Bun.spawnSync(
+    ['ushman-characterize', 'capture', '.', '--states=${stateId}', '--scene-only'],
+    {
+      cwd: process.cwd(),
+      env: process.env,
+      stderr: 'pipe',
+      stdout: 'pipe',
+    },
+  );
+  expect(result.exitCode, new TextDecoder().decode(result.stderr)).toBe(0);
+  return JSON.parse(await Bun.file(outputPath).text());
+};
+
+test(${quote(`${stateId} scene tree matches baseline`)}, async () => {
+  const live = await captureLive();
+  expect(canonicalizeSceneTree(live)).toEqual(canonicalizeSceneTree(baseline));
+});
+`;
+        if (!dryRun) {
+            await Bun.write(filePath, source);
+        }
+        written.push(filePath);
+    }
+    const stale = (await readdir(testsDir).catch(() => []))
+        .filter((entry) => entry.endsWith('.test.ts'))
+        .filter((entry) => !written.some((filePath) => path.basename(filePath) === entry));
+    return {
+        stale,
+        written,
+    };
+};
+export { canonicalizeSceneTree };
+const REQUIRED_SMOKE_HARNESS_FILES = ['config.ts', 'diff.ts', 'drive.ts'];
+const renderPopulatedSmokeTestSource = (stateId) => [
+    '// AUTO-GENERATED by ushman-characterize populateSmokeScaffolds. Do not hand-edit.',
+    "import { expect, test } from 'bun:test';",
+    "import { SMOKE_STATES } from './config.ts';",
+    "import { diffSmokeStates } from './diff.ts';",
+    "import { captureSmokeStates } from './drive.ts';",
+    '',
+    `const STATE_ID = ${quote(stateId)};`,
+    `const BASELINE_PATH = ${quote(path.join(PARITY_BASELINE_RELATIVE_DIR, `${stateId}.png`).split(path.sep).join('/'))};`,
+    '',
+    `test('${stateId} smoke state matches its baseline', async () => {`,
+    '  expect(await Bun.file(BASELINE_PATH).exists()).toBe(true);',
+    '  const state = SMOKE_STATES.find((entry) => entry.id === STATE_ID);',
+    '  expect(state).toBeDefined();',
+    '  await captureSmokeStates();',
+    '  const diffResults = await diffSmokeStates();',
+    '  const result = diffResults.find((entry) => entry.id === STATE_ID);',
+    '  expect(result).toBeDefined();',
+    '  expect(result!.ratio).toBeLessThanOrEqual(state!.diffThreshold);',
+    '});',
+    '',
+].join('\n');
+const summarizePopulateSmokeScaffolds = ({ skipped, toolingGaps, written, }) => [
+    `populated ${written.length} smoke scaffold file(s)`,
+    skipped.length > 0 ? `skipped ${skipped.length} operator-managed file(s)` : null,
+    toolingGaps.length > 0 ? `${toolingGaps.length} tooling gap(s)` : null,
+]
+    .filter((value) => value !== null)
+    .join('; ');
+/**
+ * Populate seed-time `tests/smoke/<state>.test.ts` scaffolds once the shared smoke harness
+ * and parity baseline PNGs exist. Operator-edited scaffolds are preserved by sidecar hash.
+ */
+export const populateSmokeScaffolds = async ({ workspaceDir, }) => {
+    await assertV4Workspace(workspaceDir);
+    const sidecar = await loadSeedFingerprintSidecar(workspaceDir);
+    const testsDir = path.join(workspaceDir, 'tests', 'smoke');
+    const smokeFiles = (await listFilesRecursive({
+        dir: testsDir,
+        suffix: '.test.ts',
+    })).filter((filePath) => path.basename(filePath) !== 'smoke.test.ts');
+    const nextFingerprints = {};
+    const skipped = [];
+    const toolingGaps = [];
+    const written = [];
+    for (const requiredFile of REQUIRED_SMOKE_HARNESS_FILES) {
+        const requiredFilePath = path.join(testsDir, requiredFile);
+        if (!(await Bun.file(requiredFilePath).exists())) {
+            const gap = `Missing smoke harness file ${toWorkspaceRelativePath({
+                filePath: requiredFilePath,
+                workspaceDir,
+            })}. Re-run \`ushman go --stage=seed\` to restore the smoke harness before retrying population.`;
+            toolingGaps.push(gap);
+            await recordCharacterizeToolingGap({
+                body: gap,
+                summary: `missing smoke harness file ${requiredFile}`,
+                workspaceRoot: workspaceDir,
+            });
+        }
+    }
+    if (toolingGaps.length > 0) {
+        await recordCharacterizeValidatorResult({
+            metrics: {
+                skippedCount: skipped.length,
+                toolingGapCount: toolingGaps.length,
+                writtenCount: written.length,
+            },
+            summary: summarizePopulateSmokeScaffolds({
+                skipped,
+                toolingGaps,
+                written,
+            }),
+            verdict: 'yellow',
+            workspaceRoot: workspaceDir,
+        });
+        return {
+            sidecarPath: sidecar.filePath,
+            skipped,
+            toolingGaps,
+            written,
+        };
+    }
+    for (const filePath of smokeFiles) {
+        const relativeTestPath = toWorkspaceRelativePath({
+            filePath,
+            workspaceDir,
+        });
+        const trackedHash = sidecar.scaffolds[relativeTestPath];
+        if (trackedHash === undefined) {
+            const gap = `Cannot manage ${relativeTestPath} because tests/.seed-fingerprints.json does not track it. Re-run \`ushman go --stage=seed\` for this workspace, or add the scaffold to the sidecar before retrying population.`;
+            toolingGaps.push(gap);
+            await recordCharacterizeToolingGap({
+                body: gap,
+                summary: `untracked smoke scaffold ${relativeTestPath}`,
+                workspaceRoot: workspaceDir,
+            });
+            continue;
+        }
+        const currentSource = await Bun.file(filePath).text();
+        const currentHash = hashSeedScaffoldContent(currentSource);
+        if (trackedHash !== currentHash) {
+            skipped.push(filePath);
+            continue;
+        }
+        const stateId = path.basename(filePath, '.test.ts');
+        const baselinePath = path.join(workspaceDir, PARITY_BASELINE_RELATIVE_DIR, `${stateId}.png`);
+        if (!(await Bun.file(baselinePath).exists())) {
+            const gap = `Missing smoke baseline for ${relativeTestPath}. Expected ${baselinePath}.`;
+            toolingGaps.push(gap);
+            await recordCharacterizeToolingGap({
+                body: `${gap}\nRun \`ushman-characterize stub-states --regen-stale\` after regenerating parity baselines for this workspace.`,
+                summary: `missing smoke baseline for ${relativeTestPath}`,
+                workspaceRoot: workspaceDir,
+            });
+            continue;
+        }
+        const nextSource = renderPopulatedSmokeTestSource(stateId);
+        await atomicWriteText(filePath, `${nextSource.endsWith('\n') ? nextSource : `${nextSource}\n`}`);
+        written.push(filePath);
+        nextFingerprints[relativeTestPath] = hashSeedScaffoldContent(nextSource);
+    }
+    const sidecarPath = Object.keys(nextFingerprints).length > 0
+        ? await updateSeedFingerprintSidecar({
+            entries: nextFingerprints,
+            workspaceDir,
+        })
+        : sidecar.filePath;
+    await recordCharacterizeValidatorResult({
+        affectedFiles: written.map((filePath) => toWorkspaceRelativePath({
+            filePath,
+            workspaceDir,
+        })),
+        metrics: {
+            skippedCount: skipped.length,
+            toolingGapCount: toolingGaps.length,
+            writtenCount: written.length,
+        },
+        summary: summarizePopulateSmokeScaffolds({
+            skipped,
+            toolingGaps,
+            written,
+        }),
+        verdict: toolingGaps.length > 0 ? 'yellow' : 'green',
+        workspaceRoot: workspaceDir,
+    });
+    return {
+        sidecarPath,
+        skipped,
+        toolingGaps,
+        written,
+    };
+};