@rawsql-ts/ztd-cli 0.20.0 → 0.20.2

package/dist/commands/testEvidence.js

@@ -0,0 +1,1220 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestEvidenceRuntimeError = void 0;
+exports.resolveTestEvidenceExitCode = resolveTestEvidenceExitCode;
+exports.registerTestEvidenceCommand = registerTestEvidenceCommand;
+exports.runTestEvidenceSpecification = runTestEvidenceSpecification;
+exports.formatTestEvidenceOutput = formatTestEvidenceOutput;
+exports.stableStringify = stableStringify;
+exports.buildTestEvidencePrDiff = buildTestEvidencePrDiff;
+exports.formatTestEvidencePrMarkdown = formatTestEvidencePrMarkdown;
+exports.runTestEvidencePr = runTestEvidencePr;
+exports.applyEvidenceOutputControls = applyEvidenceOutputControls;
+exports.formatTestDocumentationOutput = formatTestDocumentationOutput;
+const node_fs_1 = require("node:fs");
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const test_evidence_core_1 = require("@rawsql-ts/test-evidence-core");
+const test_evidence_renderer_md_1 = require("@rawsql-ts/test-evidence-renderer-md");
+const sqlCatalogDiscovery_1 = require("../utils/sqlCatalogDiscovery");
+const agentCli_1 = require("../utils/agentCli");
+/**
+ * Runtime/configuration error for test evidence command (maps to exit code 2).
+ */
+class TestEvidenceRuntimeError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.exitCode = 2;
+        this.name = 'TestEvidenceRuntimeError';
+        this.code = options === null || options === void 0 ? void 0 : options.code;
+    }
+}
+exports.TestEvidenceRuntimeError = TestEvidenceRuntimeError;
+/**
+ * Resolve command exit code for test evidence generation.
+ * @param args.result Completed generation result when execution succeeded.
+ * @param args.error Error thrown while generating evidence.
+ * @returns 0 when generation succeeded, 2 for runtime/configuration errors, 1 for other failures.
+ */
+function resolveTestEvidenceExitCode(args) {
+    if (args.error) {
+        return args.error instanceof TestEvidenceRuntimeError ? 2 : 1;
+    }
+    if (!args.result) {
+        return 2;
+    }
+    return 0;
+}
+/**
+ * Register `ztd evidence` command on the CLI root program.
+ */
+function registerTestEvidenceCommand(program) {
+    const evidenceCommand = program
+        .command('evidence')
+        .alias('test-evidence')
+        .description('Generate deterministic test specification evidence artifacts')
+        .option('--mode <mode>', 'Evidence mode (specification)', 'specification')
+        .option('--format <format>', 'Output format (json|markdown|both)', 'both')
+        .option('--out-dir <path>', 'Output directory', '.ztd/test-evidence')
+        .option('--specs-dir <path>', 'Override SQL catalog specs directory (default: src/catalog/specs)')
+        .option('--tests-dir <path>', 'Override tests directory (default: tests)')
+        .option('--spec-module <path>', 'Explicit evidence module path (default: tests/specs/index)')
+        .option('--json <payload>', 'Pass evidence options as a JSON object')
+        .option('--summary-only', 'Write only summary counts without catalog or case detail payloads')
+        .option('--limit <count>', 'Limit returned catalogs and cases in generated artifacts')
+        .action((options) => {
+        var _a;
+        try {
+            const merged = options.json ? { ...options, ...(0, agentCli_1.parseJsonPayload)(options.json, '--json') } : options;
+            const mode = normalizeMode(String(merged.mode));
+            const format = normalizeFormat(String(merged.format));
+            const report = applyEvidenceOutputControls(runTestEvidenceSpecification({
+                mode,
+                rootDir: process.env.ZTD_PROJECT_ROOT,
+                specsDir: merged.specsDir,
+                testsDir: merged.testsDir,
+                specModule: merged.specModule
+            }), {
+                summaryOnly: Boolean(merged.summaryOnly),
+                limit: normalizeEvidenceLimit(merged.limit)
+            });
+            const sourceRootDir = node_path_1.default.resolve((_a = process.env.ZTD_PROJECT_ROOT) !== null && _a !== void 0 ? _a : process.cwd());
+            writeArtifacts({
+                report,
+                format,
+                outDir: node_path_1.default.resolve(process.cwd(), String(merged.outDir)),
+                sourceRootDir
+            });
+            process.exitCode = resolveTestEvidenceExitCode({ result: report });
+        }
+        catch (error) {
+            process.exitCode = resolveTestEvidenceExitCode({ error });
+            console.error(error instanceof Error ? error.message : String(error));
+        }
+    });
+    evidenceCommand
+        .command('test-doc')
+        .description('Generate human-readable Markdown test documentation from ZTD test assets')
+        .option('--out <path>', 'Output markdown path', '.ztd/test-evidence/test-documentation.md')
+        .option('--specs-dir <path>', 'Override SQL catalog specs directory (default: src/catalog/specs)')
+        .option('--tests-dir <path>', 'Override tests directory (default: tests)')
+        .option('--spec-module <path>', 'Explicit evidence module path (default: tests/specs/index)')
+        .option('--json <payload>', 'Pass test-doc options as a JSON object')
+        .action((options) => {
+        var _a, _b;
+        try {
+            const merged = options.json ? { ...options, ...(0, agentCli_1.parseJsonPayload)(options.json, '--json') } : options;
+            const report = runTestEvidenceSpecification({
+                mode: 'specification',
+                rootDir: process.env.ZTD_PROJECT_ROOT,
+                specsDir: merged.specsDir,
+                testsDir: merged.testsDir,
+                specModule: merged.specModule
+            });
+            const sourceRootDir = node_path_1.default.resolve((_a = process.env.ZTD_PROJECT_ROOT) !== null && _a !== void 0 ? _a : process.cwd());
+            writeTestDocumentationArtifact({
+                report,
+                outPath: node_path_1.default.resolve(process.cwd(), String((_b = merged.out) !== null && _b !== void 0 ? _b : '.ztd/test-evidence/test-documentation.md')),
+                sourceRootDir
+            });
+            process.exitCode = resolveTestEvidenceExitCode({ result: report });
+        }
+        catch (error) {
+            process.exitCode = resolveTestEvidenceExitCode({ error });
+            console.error(error instanceof Error ? error.message : String(error));
+        }
+    });
+    evidenceCommand
+        .command('pr')
+        .description('Generate PR diff evidence from base/head specification JSON projections')
+        .option('--base <ref>', 'Base git ref', 'main')
+        .option('--head <ref>', 'Head git ref', 'HEAD')
+        .option('--base-mode <mode>', 'Base resolution mode (merge-base|ref)', 'merge-base')
+        .option('--allow-empty-base', 'Allow empty base evidence when head has catalogs')
+        .option('--removed-detail <level>', 'Removed case detail level (none|input|full)', 'input')
+        .option('--out-dir <path>', 'Output directory', 'artifacts/test-evidence')
+        .option('--specs-dir <path>', 'Override SQL catalog specs directory (default: src/catalog/specs)')
+        .option('--tests-dir <path>', 'Override tests directory (default: tests)')
+        .option('--spec-module <path>', 'Explicit evidence module path (default: tests/specs/index)')
+        .option('--json <payload>', 'Pass PR evidence options as a JSON object')
+        .option('--summary-only', 'Write PR evidence with summary-only base/head projections')
+        .option('--limit <count>', 'Limit returned catalogs and cases in base/head projections')
+        .action((options) => {
+        var _a, _b, _c, _d, _e;
+        try {
+            const merged = options.json ? { ...options, ...(0, agentCli_1.parseJsonPayload)(options.json, '--json') } : options;
+            const output = runTestEvidencePr({
+                baseRef: String((_a = merged.base) !== null && _a !== void 0 ? _a : 'main'),
+                headRef: String((_b = merged.head) !== null && _b !== void 0 ? _b : 'HEAD'),
+                baseMode: normalizeBaseMode(String((_c = merged.baseMode) !== null && _c !== void 0 ? _c : 'merge-base')),
+                allowEmptyBase: Boolean(merged.allowEmptyBase),
+                removedDetail: normalizeRemovedDetail(String((_d = merged.removedDetail) !== null && _d !== void 0 ? _d : 'input')),
+                outDir: String((_e = merged.outDir) !== null && _e !== void 0 ? _e : 'artifacts/test-evidence'),
+                rootDir: process.env.ZTD_PROJECT_ROOT,
+                specsDir: merged.specsDir,
+                testsDir: merged.testsDir,
+                specModule: merged.specModule,
+                summaryOnly: Boolean(merged.summaryOnly),
+                limit: normalizeEvidenceLimit(merged.limit)
+            });
+            process.exitCode = resolveTestEvidenceExitCode({ result: output.headReport });
+        }
+        catch (error) {
+            process.exitCode = resolveTestEvidenceExitCode({ error });
+            console.error(error instanceof Error ? error.message : String(error));
+        }
+    });
+}
+function normalizeMode(mode) {
+    const normalized = mode.trim().toLowerCase();
+    if (normalized !== 'specification') {
+        throw new TestEvidenceRuntimeError(`Unsupported mode: ${mode}`);
+    }
+    return 'specification';
+}
+function normalizeFormat(format) {
+    const normalized = format.trim().toLowerCase();
+    if (normalized === 'json' || normalized === 'markdown' || normalized === 'both') {
+        return normalized;
+    }
+    throw new TestEvidenceRuntimeError(`Unsupported format: ${format}`);
+}
+function normalizeBaseMode(mode) {
+    const normalized = mode.trim().toLowerCase();
+    if (normalized === 'merge-base' || normalized === 'ref') {
+        return normalized;
+    }
+    throw new TestEvidenceRuntimeError(`Unsupported base-mode: ${mode}`);
+}
+function normalizeRemovedDetail(level) {
+    const normalized = level.trim().toLowerCase();
+    if (normalized === 'none' || normalized === 'input' || normalized === 'full') {
+        return normalized;
+    }
+    throw new TestEvidenceRuntimeError(`Unsupported removed-detail: ${level}`);
+}
+/**
+ * Build deterministic specification evidence from SQL catalog specs and test-case catalog exports.
+ */
+function runTestEvidenceSpecification(options) {
+    var _a;
+    const root = node_path_1.default.resolve((_a = options.rootDir) !== null && _a !== void 0 ? _a : process.cwd());
+    const specsDir = options.specsDir ? node_path_1.default.resolve(root, options.specsDir) : node_path_1.default.resolve(root, 'src', 'catalog', 'specs');
+    const testsDir = options.testsDir ? node_path_1.default.resolve(root, options.testsDir) : node_path_1.default.resolve(root, 'tests');
+    const sqlSpecFiles = (0, node_fs_1.existsSync)(specsDir) ? (0, sqlCatalogDiscovery_1.walkSqlCatalogSpecFiles)(specsDir) : [];
+    const evidenceModule = loadEvidenceModule(root, testsDir, options.specModule);
+    const testCaseCatalogFiles = (0, node_fs_1.existsSync)(testsDir) ? walkFiles(testsDir, isTestCaseCatalogFile) : [];
+    const legacyTestCases = evidenceModule ? [] : testCaseCatalogFiles.flatMap((filePath) => loadTestCaseCatalogEvidence(root, filePath));
+    const testCaseCatalogs = evidenceModule
+        ? readTestCaseCatalogsFromModule(evidenceModule)
+            .map((catalog) => ({
+            ...catalog,
+            cases: [...catalog.cases].sort((a, b) => a.id.localeCompare(b.id))
+        }))
+            .sort((a, b) => a.id.localeCompare(b.id))
+        : [];
+    const testCasesFromModule = flattenTestCaseCatalogs(testCaseCatalogs);
+    const sqlCaseCatalogsFromModule = evidenceModule ? readSqlCaseCatalogsFromModule(evidenceModule) : [];
+    if (sqlSpecFiles.length === 0 && testCasesFromModule.length === 0 && legacyTestCases.length === 0 && sqlCaseCatalogsFromModule.length === 0) {
+        throw new TestEvidenceRuntimeError(`No catalog specs or test-case evidence exports were found. Checked specsDir=${specsDir}, testsDir=${testsDir}`, { code: 'NO_SPECS_FOUND' });
+    }
+    const sqlCatalogs = sqlSpecFiles
+        .flatMap((filePath) => (0, sqlCatalogDiscovery_1.loadSqlCatalogSpecsFromFile)(filePath, (message) => new TestEvidenceRuntimeError(message)))
+        .map((loaded) => toSqlEvidence(root, loaded))
+        .sort((a, b) => a.id.localeCompare(b.id) || a.specFile.localeCompare(b.specFile));
+    const testCases = [...testCasesFromModule, ...legacyTestCases]
+        .sort((a, b) => a.id.localeCompare(b.id) || a.filePath.localeCompare(b.filePath));
+    const sqlCaseCatalogs = sqlCaseCatalogsFromModule
+        .sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        schemaVersion: 1,
+        mode: options.mode,
+        summary: {
+            sqlCatalogCount: sqlCatalogs.length,
+            sqlCaseCatalogCount: sqlCaseCatalogs.length,
+            testCaseCount: testCases.length,
+            specFilesScanned: sqlSpecFiles.length,
+            testFilesScanned: evidenceModule ? 1 : testCaseCatalogFiles.length
+        },
+        sqlCatalogs,
+        sqlCaseCatalogs,
+        testCaseCatalogs,
+        testCases
+    };
+}
+/**
+ * Render deterministic JSON or Markdown output text.
+ */
+function formatTestEvidenceOutput(report, format, context) {
+    var _a;
+    if (format === 'json') {
+        return `${JSON.stringify(report, null, 2)}\n`;
+    }
+    if ((_a = report.display) === null || _a === void 0 ? void 0 : _a.summaryOnly) {
+        const lines = [
+            '# Test Specification Summary',
+            '',
+            `- schemaVersion: ${report.schemaVersion}`,
+            `- mode: ${report.mode}`,
+            `- sqlCatalogCount: ${report.summary.sqlCatalogCount}`,
+            `- sqlCaseCatalogCount: ${report.summary.sqlCaseCatalogCount}`,
+            `- testCaseCount: ${report.summary.testCaseCount}`,
+            `- specFilesScanned: ${report.summary.specFilesScanned}`,
+            `- testFilesScanned: ${report.summary.testFilesScanned}`,
+            `- truncated: ${report.display.truncated}`,
+            report.display.limit !== undefined ? `- limit: ${report.display.limit}` : ''
+        ].filter(Boolean);
+        return `${lines.join('\n')}\n`;
+    }
+    const model = (0, test_evidence_core_1.buildSpecificationModel)(report);
+    return `${(0, test_evidence_renderer_md_1.renderSpecificationMarkdown)(model, {
+        definitionLinks: resolveDefinitionLinkOptions(context)
+    })}\n`;
+}
+/**
+ * Stable stringify that sorts object keys recursively for deterministic fingerprinting.
+ */
+function stableStringify(value) {
+    return (0, test_evidence_core_1.stableStringify)(value);
+}
+/**
+ * Build deterministic PR diff JSON from base/head specification reports.
+ */
+function buildTestEvidencePrDiff(args) {
+    return (0, test_evidence_core_1.buildDiffJson)({
+        base: {
+            ref: args.base.ref,
+            sha: args.base.sha,
+            previewJson: args.base.report
+        },
+        head: {
+            ref: args.head.ref,
+            sha: args.head.sha,
+            previewJson: args.head.report
+        },
+        baseMode: args.baseMode
+    });
+}
+/**
+ * Render PR-focused markdown from diff JSON.
+ */
+function formatTestEvidencePrMarkdown(diff, options) {
+    return (0, test_evidence_renderer_md_1.renderDiffMarkdown)(diff, {
+        definitionLinks: resolveDefinitionLinkOptions({
+            markdownPath: options === null || options === void 0 ? void 0 : options.markdownPath,
+            sourceRootDir: options === null || options === void 0 ? void 0 : options.sourceRootDir
+        })
+    });
+}
+function resolveDefinitionLinkOptions(context) {
+    var _a, _b, _c;
+    const serverUrl = (_a = process.env.GITHUB_SERVER_URL) === null || _a === void 0 ? void 0 : _a.trim();
+    const repository = (_b = process.env.GITHUB_REPOSITORY) === null || _b === void 0 ? void 0 : _b.trim();
+    const ref = (_c = process.env.GITHUB_SHA) === null || _c === void 0 ? void 0 : _c.trim();
+    if (serverUrl && repository && ref) {
+        return {
+            mode: 'github',
+            github: {
+                serverUrl,
+                repository,
+                ref
+            }
+        };
+    }
+    if ((context === null || context === void 0 ? void 0 : context.markdownPath) && (context === null || context === void 0 ? void 0 : context.sourceRootDir)) {
+        return {
+            mode: 'path',
+            path: {
+                markdownDir: node_path_1.default.dirname(context.markdownPath),
+                sourceRootDir: context.sourceRootDir
+            }
+        };
+    }
+    return { mode: 'path' };
+}
+/**
+ * Generate base/head reports, compute PR diff JSON, and write PR artifacts.
+ */
+function runTestEvidencePr(options) {
+    var _a;
+    const root = node_path_1.default.resolve((_a = options.rootDir) !== null && _a !== void 0 ? _a : process.cwd());
+    const tempRoot = node_path_1.default.resolve(root, '.tmp', 'test-evidence-worktree');
+    (0, node_fs_1.mkdirSync)(tempRoot, { recursive: true });
+    const createdWorktrees = [];
+    const resolvedHeadSha = resolveGitSha(root, options.headRef);
+    const resolvedBaseSha = options.baseMode === 'merge-base'
+        ? resolveGitMergeBase(root, options.baseRef, options.headRef)
+        : resolveGitSha(root, options.baseRef);
+    const currentHeadSha = resolveGitSha(root, 'HEAD');
+    try {
+        const headMaterialized = materializeEvidenceForRef({
+            repoRoot: root,
+            ref: options.headRef,
+            resolvedSha: resolvedHeadSha,
+            allowCurrentWorkspace: resolvedHeadSha === currentHeadSha,
+            tempRoot,
+            createdWorktrees,
+            specsDir: options.specsDir,
+            testsDir: options.testsDir,
+            specModule: options.specModule,
+            summaryOnly: options.summaryOnly,
+            limit: options.limit
+        });
+        const baseMaterialized = materializeEvidenceForRef({
+            repoRoot: root,
+            ref: options.baseRef,
+            resolvedSha: resolvedBaseSha,
+            allowCurrentWorkspace: resolvedBaseSha === currentHeadSha,
+            tempRoot,
+            createdWorktrees,
+            specsDir: options.specsDir,
+            testsDir: options.testsDir,
+            specModule: options.specModule,
+            summaryOnly: options.summaryOnly,
+            limit: options.limit
+        });
+        console.log(`base preview: ${baseMaterialized.previewJsonPath}`);
+        console.log(`head preview: ${headMaterialized.previewJsonPath}`);
+        const diff = buildTestEvidencePrDiff({
+            base: { ref: options.baseRef, sha: baseMaterialized.sha, report: baseMaterialized.report },
+            head: { ref: options.headRef, sha: headMaterialized.sha, report: headMaterialized.report },
+            baseMode: options.baseMode
+        });
+        if (!options.allowEmptyBase && diff.totals.base.catalogs === 0 && diff.totals.head.catalogs > 0) {
+            throw new TestEvidenceRuntimeError('Base test evidence is empty.\nThis likely indicates preview generation failed at base ref.\nIf this is intentional, re-run with --allow-empty-base.');
+        }
+        const outDir = node_path_1.default.resolve(root, options.outDir);
+        (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+        const diffJsonPath = node_path_1.default.join(outDir, 'test-specification.pr.json');
+        const diffMdPath = node_path_1.default.join(outDir, 'test-specification.pr.md');
+        (0, node_fs_1.writeFileSync)(diffJsonPath, `${JSON.stringify(diff, null, 2)}\n`, 'utf8');
+        (0, node_fs_1.writeFileSync)(diffMdPath, formatTestEvidencePrMarkdown(diff, {
+            removedDetail: options.removedDetail,
+            markdownPath: diffMdPath,
+            sourceRootDir: root
+        }), 'utf8');
+        console.log(`wrote: ${diffJsonPath}`);
+        console.log(`wrote: ${diffMdPath}`);
+        return {
+            baseReport: baseMaterialized.report,
+            headReport: headMaterialized.report,
+            diff
+        };
+    }
+    finally {
+        cleanupWorktrees(root, createdWorktrees);
+    }
+}
+function writeArtifacts(args) {
+    var _a;
+    (0, node_fs_1.mkdirSync)(args.outDir, { recursive: true });
+    const writtenFiles = [];
+    if (args.format === 'json' || args.format === 'both') {
+        const jsonPath = node_path_1.default.join(args.outDir, 'test-specification.json');
+        (0, node_fs_1.writeFileSync)(jsonPath, formatTestEvidenceOutput(args.report, 'json'), 'utf8');
+        writtenFiles.push(jsonPath);
+    }
+    if (args.format === 'markdown' || args.format === 'both') {
+        const markdownPaths = ((_a = args.report.display) === null || _a === void 0 ? void 0 : _a.summaryOnly)
+            ? writeSpecificationSummaryMarkdown(args.report, args.outDir)
+            : writeSpecificationMarkdownArtifacts(args.report, args.outDir, args.sourceRootDir);
+        writtenFiles.push(...markdownPaths);
+    }
+    for (const filePath of writtenFiles.sort((a, b) => a.localeCompare(b))) {
+        console.log(`wrote: ${filePath}`);
+    }
+}
+function writeSpecificationSummaryMarkdown(report, outDir) {
+    const summaryPath = node_path_1.default.join(outDir, 'test-specification.summary.md');
+    (0, node_fs_1.writeFileSync)(summaryPath, formatTestEvidenceOutput(report, 'markdown'), 'utf8');
+    return [summaryPath];
+}
+function writeSpecificationMarkdownArtifacts(report, outDir, sourceRootDir) {
+    var _a, _b;
+    const indexFileName = 'test-specification.index.md';
+    const model = (0, test_evidence_core_1.buildSpecificationModel)(report);
+    const catalogs = [...model.catalogs].sort((a, b) => a.catalogId.localeCompare(b.catalogId));
+    const written = [];
+    const catalogRows = [];
+    for (const catalog of catalogs) {
+        const catalogSlug = toSpecificationSlug(catalog.catalogId);
+        const catalogFileName = `test-specification.catalog.${catalogSlug}.md`;
+        const catalogPath = node_path_1.default.join(outDir, catalogFileName);
+        const catalogDefinitionLinks = resolveDefinitionLinkOptions({ markdownPath: catalogPath, sourceRootDir });
+        const catalogLines = [];
+        catalogLines.push(`# ${catalog.catalogId} Test Cases`);
+        catalogLines.push('');
+        catalogLines.push(`- schemaVersion: ${model.schemaVersion}`);
+        catalogLines.push(`- index: [Unit Test Index](./${indexFileName})`);
+        catalogLines.push(`- title: ${catalog.title}`);
+        const definitionPath = (_a = catalog.definition) !== null && _a !== void 0 ? _a : findCatalogDefinitionPath(report, catalog.catalogId);
+        catalogLines.push(`- definition: ${formatDefinitionLinkMarkdown(definitionPath, catalogDefinitionLinks)}`);
+        if (catalog.description) {
+            catalogLines.push(`- description: ${catalog.description}`);
+        }
+        if (Array.isArray(catalog.refs) && catalog.refs.length > 0) {
+            catalogLines.push('- refs:');
+            for (const ref of catalog.refs) {
+                catalogLines.push(`  - [${ref.label}](${ref.url})`);
+            }
+        }
+        catalogLines.push(`- tests: ${catalog.cases.length}`);
+        if (catalog.kind === 'sql') {
+            catalogLines.push(`- fixtures: ${((_b = catalog.fixtures) !== null && _b !== void 0 ? _b : []).join(', ') || '(none)'}`);
+        }
+        catalogLines.push('');
+        const sortedCases = [...catalog.cases].sort((a, b) => a.id.localeCompare(b.id));
+        for (const testCase of sortedCases) {
+            catalogLines.push(`## ${testCase.id} - ${testCase.title}`);
+            catalogLines.push(`- expected: ${testCase.expected}`);
+            catalogLines.push(`- tags: ${formatCaseTags(testCase.tags)}`);
+            catalogLines.push(`- focus: ${formatCaseFocus(testCase.focus)}`);
+            if (Array.isArray(testCase.refs) && testCase.refs.length > 0) {
+                catalogLines.push('- refs:');
+                for (const ref of testCase.refs) {
+                    catalogLines.push(`  - [${ref.label}](${ref.url})`);
+                }
+            }
+            catalogLines.push('### input');
+            catalogLines.push('```json');
+            catalogLines.push(stringifyStablePretty(testCase.input));
+            catalogLines.push('```');
+            if (testCase.expected === 'throws') {
+                catalogLines.push('### error');
+                catalogLines.push('```json');
+                catalogLines.push(stringifyErrorPretty(testCase.error));
+                catalogLines.push('```');
+            }
+            else {
+                catalogLines.push('### output');
+                catalogLines.push('```json');
+                catalogLines.push(stringifyStablePretty(testCase.output));
+                catalogLines.push('```');
+            }
+            catalogLines.push('');
+        }
+        catalogLines.push('');
+        (0, node_fs_1.writeFileSync)(catalogPath, `${catalogLines.join('\n')}\n`, 'utf8');
+        written.push(catalogPath);
+        catalogRows.push({
+            fileName: catalogFileName,
+            catalogId: catalog.catalogId,
+            title: catalog.title,
+            tests: catalog.cases.length
+        });
+    }
+    const indexPath = node_path_1.default.join(outDir, indexFileName);
+    const indexLines = [];
+    indexLines.push('# Unit Test Index');
+    indexLines.push('');
+    indexLines.push(`- catalogs: ${catalogRows.length}`);
+    indexLines.push('');
+    indexLines.push('## Catalog Files');
+    indexLines.push('');
+    for (const row of catalogRows.sort((a, b) => a.fileName.localeCompare(b.fileName))) {
+        indexLines.push(`- [${row.catalogId}](./${row.fileName})`);
+        indexLines.push(`  - title: ${row.title}`);
+        indexLines.push(`  - tests: ${row.tests}`);
+    }
+    indexLines.push('');
+    (0, node_fs_1.writeFileSync)(indexPath, `${indexLines.join('\n')}\n`, 'utf8');
+    written.push(indexPath);
+    return written;
+}
+function applyEvidenceOutputControls(report, options) {
+    const summaryOnly = Boolean(options.summaryOnly);
+    const limit = options.limit;
+    if (summaryOnly) {
+        return {
+            ...report,
+            sqlCatalogs: [],
+            sqlCaseCatalogs: [],
+            testCaseCatalogs: [],
+            testCases: [],
+            display: {
+                summaryOnly: true,
+                limit,
+                truncated: report.sqlCatalogs.length > 0 ||
+                    report.sqlCaseCatalogs.length > 0 ||
+                    report.testCaseCatalogs.length > 0 ||
+                    report.testCases.length > 0
+            }
+        };
+    }
+    if (limit === undefined) {
+        return report;
+    }
+    const limited = {
+        ...report,
+        sqlCatalogs: report.sqlCatalogs.slice(0, limit),
+        sqlCaseCatalogs: report.sqlCaseCatalogs.slice(0, limit).map((catalog) => ({
+            ...catalog,
+            cases: catalog.cases.slice(0, limit)
+        })),
+        testCaseCatalogs: report.testCaseCatalogs.slice(0, limit).map((catalog) => ({
+            ...catalog,
+            cases: catalog.cases.slice(0, limit)
+        })),
+        testCases: report.testCases.slice(0, limit),
+        display: {
+            summaryOnly: false,
+            limit,
+            truncated: report.sqlCatalogs.length > limit ||
+                report.sqlCaseCatalogs.length > limit ||
+                report.testCaseCatalogs.length > limit ||
+                report.testCases.length > limit ||
+                report.sqlCaseCatalogs.some((catalog) => catalog.cases.length > limit) ||
+                report.testCaseCatalogs.some((catalog) => catalog.cases.length > limit)
+        }
+    };
+    return limited;
+}
+function normalizeEvidenceLimit(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new TestEvidenceRuntimeError(`Unsupported limit: ${value}. Use a positive integer.`);
+    }
+    return parsed;
+}
+function findCatalogDefinitionPath(report, catalogId) {
+    const functionCatalog = report.testCaseCatalogs.find((catalog) => catalog.id === catalogId);
+    if (functionCatalog === null || functionCatalog === void 0 ? void 0 : functionCatalog.definitionPath) {
+        return functionCatalog.definitionPath;
+    }
+    const sqlCatalog = report.sqlCaseCatalogs.find((catalog) => catalog.id === catalogId);
+    if (sqlCatalog === null || sqlCatalog === void 0 ? void 0 : sqlCatalog.definitionPath) {
+        return sqlCatalog.definitionPath;
+    }
+    return undefined;
+}
+function toSpecificationSlug(definition) {
+    if (definition === '(unknown)') {
+        return 'unknown';
+    }
+    const normalized = definition
+        .replace(/\\/g, '/')
+        .replace(/^\//, '')
+        .replace(/[^a-zA-Z0-9/_-]+/g, '-')
+        .replace(/\/+/g, '__')
+        .replace(/-+/g, '-')
+        .replace(/^[-_]+|[-_]+$/g, '');
+    return normalized || 'unknown';
+}
+function formatDefinitionLinkMarkdown(definitionPath, options) {
+    if (!definitionPath) {
+        return '(unknown)';
+    }
+    const normalizedPath = definitionPath.replace(/\\/g, '/').replace(/^\/+/, '');
+    if (!normalizedPath) {
+        return '(unknown)';
+    }
+    if ((options === null || options === void 0 ? void 0 : options.mode) === 'github' && options.github) {
+        const serverUrl = options.github.serverUrl.replace(/\/+$/, '');
+        const repository = options.github.repository.trim();
+        const ref = options.github.ref.trim();
+        if (serverUrl && repository && ref) {
+            const encodedPath = normalizedPath.split('/').map((part) => encodeURIComponent(part)).join('/');
+            const url = `${serverUrl}/${repository}/blob/${encodeURIComponent(ref)}/${encodedPath}`;
+            return `[${normalizedPath}](${url})`;
+        }
+    }
+    if ((options === null || options === void 0 ? void 0 : options.mode) === 'path' && options.path) {
+        const absoluteTarget = node_path_1.default.resolve(options.path.sourceRootDir, normalizedPath);
+        const absoluteMarkdownDir = node_path_1.default.resolve(options.path.markdownDir);
+        const relativePath = node_path_1.default.relative(absoluteMarkdownDir, absoluteTarget).replace(/\\/g, '/');
+        return `[${normalizedPath}](${relativePath || normalizedPath})`;
+    }
+    return `[${normalizedPath}](${normalizedPath})`;
+}
+function materializeEvidenceForRef(args) {
+    const toReport = (rootDir) => {
+        try {
+            return applyEvidenceOutputControls(runTestEvidenceSpecification({
+                mode: 'specification',
+                rootDir,
+                specsDir: args.specsDir,
+                testsDir: args.testsDir,
+                specModule: args.specModule
+            }), {
+                summaryOnly: args.summaryOnly,
+                limit: args.limit
+            });
+        }
+        catch (error) {
+            if (error instanceof TestEvidenceRuntimeError &&
+                error.code === 'NO_SPECS_FOUND') {
+                return createEmptySpecificationEvidence();
+            }
+            throw error;
+        }
+    };
+    if (args.allowCurrentWorkspace) {
+        const report = toReport(args.repoRoot);
+        return {
+            sha: args.resolvedSha,
+            report,
+            previewJsonPath: writePreviewSnapshot(args.repoRoot, report)
+        };
+    }
+    const worktreeDir = (0, node_fs_1.mkdtempSync)(node_path_1.default.join(args.tempRoot, 'wt-'));
+    args.createdWorktrees.push(worktreeDir);
+    runGitCommand(args.repoRoot, ['worktree', 'add', '--detach', worktreeDir, args.resolvedSha]);
+    const report = toReport(worktreeDir);
+    return {
+        sha: args.resolvedSha,
+        report,
+        previewJsonPath: writePreviewSnapshot(worktreeDir, report)
+    };
+}
+function createEmptySpecificationEvidence() {
+    return {
+        schemaVersion: 1,
+        mode: 'specification',
+        summary: {
+            sqlCatalogCount: 0,
+            sqlCaseCatalogCount: 0,
+            testCaseCount: 0,
+            specFilesScanned: 0,
+            testFilesScanned: 0
+        },
+        sqlCatalogs: [],
+        sqlCaseCatalogs: [],
+        testCaseCatalogs: [],
+        testCases: []
+    };
+}
+function writePreviewSnapshot(rootDir, report) {
+    const previewDir = node_path_1.default.resolve(rootDir, 'artifacts', 'test-evidence');
+    (0, node_fs_1.mkdirSync)(previewDir, { recursive: true });
+    const previewPath = node_path_1.default.join(previewDir, 'test-specification.preview.json');
+    (0, node_fs_1.writeFileSync)(previewPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+    return previewPath;
+}
+function cleanupWorktrees(repoRoot, worktreeDirs) {
+    for (const worktreeDir of [...worktreeDirs].reverse()) {
+        try {
+            runGitCommand(repoRoot, ['worktree', 'remove', '--force', worktreeDir]);
+        }
+        catch {
+            (0, node_fs_1.rmSync)(worktreeDir, { recursive: true, force: true });
+        }
+    }
+}
+function runGitCommand(repoRoot, args) {
+    try {
+        return (0, node_child_process_1.execFileSync)('git', args, {
+            cwd: repoRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            encoding: 'utf8'
+        }).trim();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new TestEvidenceRuntimeError(`Git command failed: git ${args.join(' ')} (${message})`);
+    }
+}
+function resolveGitSha(repoRoot, ref) {
+    return runGitCommand(repoRoot, ['rev-parse', ref]);
+}
+function resolveGitMergeBase(repoRoot, baseRef, headRef) {
+    return runGitCommand(repoRoot, ['merge-base', baseRef, headRef]);
+}
+function toSqlEvidence(rootDir, loaded) {
+    var _a, _b, _c;
+    const id = typeof loaded.spec.id === 'string' && loaded.spec.id.trim().length > 0
+        ? loaded.spec.id.trim()
+        : `<missing-id:${node_path_1.default.basename(loaded.filePath)}>`;
+    const sqlFile = typeof loaded.spec.sqlFile === 'string' && loaded.spec.sqlFile.trim().length > 0
+        ? loaded.spec.sqlFile.trim()
+        : null;
+    const paramsShape = ((_a = loaded.spec.params) === null || _a === void 0 ? void 0 : _a.shape) === 'named' || ((_b = loaded.spec.params) === null || _b === void 0 ? void 0 : _b.shape) === 'positional'
+        ? loaded.spec.params.shape
+        : 'unknown';
+    const resolvedSqlPath = sqlFile ? node_path_1.default.resolve(node_path_1.default.dirname(loaded.filePath), sqlFile) : null;
+    const specFile = normalizePath(node_path_1.default.relative(rootDir, loaded.filePath));
+    return {
+        kind: 'sql-catalog',
+        id,
+        specFile,
+        sqlFile,
+        sqlFileResolved: Boolean(resolvedSqlPath && (0, node_fs_1.existsSync)(resolvedSqlPath)),
+        paramsShape,
+        hasOutputMapping: ((_c = loaded.spec.output) === null || _c === void 0 ? void 0 : _c.mapping) !== undefined
+    };
+}
+function loadEvidenceModule(rootDir, testsDir, specModule) {
+    const moduleCandidates = resolveEvidenceModuleCandidates(rootDir, testsDir, specModule);
+    const target = moduleCandidates.find((candidate) => (0, node_fs_1.existsSync)(candidate));
+    if (!target) {
+        return undefined;
+    }
+    try {
+        const requireFn = (0, node_module_1.createRequire)(__filename);
+        const loaded = requireFn(target);
+        const normalized = (loaded === null || loaded === void 0 ? void 0 : loaded.default) && (0, sqlCatalogDiscovery_1.isPlainObject)(loaded.default)
+            ? loaded.default
+            : loaded;
+        return normalized;
+    }
+    catch (error) {
+        throw new TestEvidenceRuntimeError(`Failed to load evidence module ${target}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function resolveEvidenceModuleCandidates(rootDir, testsDir, specModule) {
+    if (specModule) {
+        const absolute = node_path_1.default.resolve(rootDir, specModule);
+        return [
+            absolute,
+            `${absolute}.js`,
+            `${absolute}.cjs`,
+            `${absolute}.ts`
+        ];
+    }
+    const base = node_path_1.default.resolve(testsDir, 'specs', 'index');
+    return [
+        `${base}.js`,
+        `${base}.cjs`,
+        `${base}.ts`
+    ];
+}
+function readTestCaseCatalogsFromModule(moduleValue) {
+    if (!Array.isArray(moduleValue.testCaseCatalogs)) {
+        return [];
+    }
+    return moduleValue.testCaseCatalogs.map((catalog, index) => {
+        if (!(0, sqlCatalogDiscovery_1.isPlainObject)(catalog)) {
+            throw new TestEvidenceRuntimeError(`testCaseCatalogs[${index}] must be an object in evidence module.`);
+        }
+        const id = typeof catalog.id === 'string' ? catalog.id.trim() : '';
+        const title = typeof catalog.title === 'string' ? catalog.title.trim() : '';
+        const cases = Array.isArray(catalog.cases) ? catalog.cases : [];
+        if (!id || !title) {
+            throw new TestEvidenceRuntimeError(`testCaseCatalogs[${index}] requires non-empty id/title.`);
+        }
+        const normalizedCases = cases.map((item, caseIndex) => {
+            if (!(0, sqlCatalogDiscovery_1.isPlainObject)(item)) {
+                throw new TestEvidenceRuntimeError(`testCaseCatalogs[${index}].cases[${caseIndex}] must be an object.`);
+            }
+            const caseId = typeof item.id === 'string' ? item.id.trim() : '';
+            const caseTitle = typeof item.title === 'string' ? item.title.trim() : '';
+            if (!caseId || !caseTitle) {
+                throw new TestEvidenceRuntimeError(`testCaseCatalogs[${index}].cases[${caseIndex}] requires non-empty id/title.`);
+            }
+            const description = typeof item.description === 'string' && item.description.trim().length > 0
+                ? item.description.trim()
+                : undefined;
+            const hasDirectInput = Object.prototype.hasOwnProperty.call(item, 'input');
+            const hasDirectOutput = Object.prototype.hasOwnProperty.call(item, 'output');
+            const hasDirectExpected = Object.prototype.hasOwnProperty.call(item, 'expected');
+            const hasDirectError = Object.prototype.hasOwnProperty.call(item, 'error');
+            const hasDirectTags = Object.prototype.hasOwnProperty.call(item, 'tags');
+            const hasDirectFocus = Object.prototype.hasOwnProperty.call(item, 'focus');
+            const hasDirectRefs = Object.prototype.hasOwnProperty.call(item, 'refs');
+            const evidenceValue = Object.prototype.hasOwnProperty.call(item, 'evidence') ? item.evidence : undefined;
+            const hasEvidence = (0, sqlCatalogDiscovery_1.isPlainObject)(evidenceValue);
+            // Accept both normalized evidence shape and raw test catalog shape (`evidence.*`).
+            const input = hasDirectInput
+                ? item.input
+                : hasEvidence && Object.prototype.hasOwnProperty.call(evidenceValue, 'input')
+                    ? evidenceValue.input
+                    : undefined;
+            const output = hasDirectOutput
+                ? item.output
+                : hasEvidence && Object.prototype.hasOwnProperty.call(evidenceValue, 'output')
+                    ? evidenceValue.output
+                    : undefined;
+            const expectedRaw = hasDirectExpected
+                ? item.expected
+                : hasEvidence && Object.prototype.hasOwnProperty.call(evidenceValue, 'expected')
+                    ? evidenceValue.expected
+                    : undefined;
+            const expected = expectedRaw === 'success' || expectedRaw === 'throws' || expectedRaw === 'errorResult'
+                ? expectedRaw
+                : output === undefined
+                    ? undefined
+                    : 'success';
+            const errorRaw = hasDirectError
+                ? item.error
+                : hasEvidence && Object.prototype.hasOwnProperty.call(evidenceValue, 'error')
+                    ? evidenceValue.error
+                    : undefined;
+            const tagsRaw = hasDirectTags
+                ? item.tags
+                : hasEvidence && Object.prototype.hasOwnProperty.call(evidenceValue, 'tags')
+                    ? evidenceValue.tags
+                    : undefined;
+            const focusRaw = hasDirectFocus
+                ? item.focus
+                : hasEvidence && Object.prototype.hasOwnProperty.call(evidenceValue, 'focus')
+                    ? evidenceValue.focus
+                    : undefined;
+            const refsRaw = hasDirectRefs
+                ? item.refs
+                : hasEvidence && Object.prototype.hasOwnProperty.call(evidenceValue, 'refs')
+                    ? evidenceValue.refs
+                    : undefined;
+            if (input === undefined || expected === undefined) {
+                throw new TestEvidenceRuntimeError(`testCaseCatalogs[${index}].cases[${caseIndex}] requires input/expected evidence fields.`);
+            }
+            if (expected !== 'throws' && output === undefined) {
+                throw new TestEvidenceRuntimeError(`testCaseCatalogs[${index}].cases[${caseIndex}] requires output when expected is not "throws".`);
+            }
+            if (expected === 'throws') {
+                if (!(0, sqlCatalogDiscovery_1.isPlainObject)(errorRaw)) {
+                    throw new TestEvidenceRuntimeError(`testCaseCatalogs[${index}].cases[${caseIndex}] requires error when expected is "throws".`);
+                }
+                if (typeof errorRaw.name !== 'string' ||
+                    typeof errorRaw.message !== 'string' ||
+                    (errorRaw.match !== 'equals' && errorRaw.match !== 'contains')) {
+                    throw new TestEvidenceRuntimeError(`testCaseCatalogs[${index}].cases[${caseIndex}].error must define name/message/match.`);
+                }
+            }
+            const normalizedTags = Array.isArray(tagsRaw) && tagsRaw.every((tag) => typeof tag === 'string' && tag.trim().length > 0)
+                ? normalizeCaseTags(tagsRaw.map((tag) => tag.trim()))
+                : undefined;
+            const normalizedFocus = typeof focusRaw === 'string' && focusRaw.trim().length > 0
+                ? focusRaw.trim()
+                : undefined;
+            const normalizedRefs = normalizeCatalogRefs(refsRaw);
+            if (!normalizedTags || normalizedTags.length !== 2) {
+                throw new TestEvidenceRuntimeError(`testCaseCatalogs[${index}].cases[${caseIndex}] requires tags with exactly 2 axes: [intent, technique].`);
+            }
+            if (!normalizedFocus) {
+                throw new TestEvidenceRuntimeError(`testCaseCatalogs[${index}].cases[${caseIndex}] requires focus sentence.`);
+            }
+            return {
+                id: caseId,
+                title: caseTitle,
+                ...(description ? { description } : {}),
+                input,
+                expected,
+                ...(expected === 'throws'
+                    ? {
+                        error: {
+                            name: errorRaw.name,
+                            message: errorRaw.message,
+                            match: errorRaw.match
+                        }
+                    }
+                    : { output }),
+                tags: normalizedTags,
+                focus: normalizedFocus,
+                ...(normalizedRefs.length > 0 ? { refs: normalizedRefs } : {})
+            };
+        });
+        const description = typeof catalog.description === 'string' && catalog.description.trim().length > 0
+            ? catalog.description.trim()
+            : undefined;
+        const definitionPath = typeof catalog.definitionPath === 'string' && catalog.definitionPath.trim().length > 0
+            ? catalog.definitionPath.trim()
+            : undefined;
+        const refs = normalizeCatalogRefs(catalog.refs);
+        return {
+            id,
+            title,
+            ...(description ? { description } : {}),
+            ...(definitionPath ? { definitionPath } : {}),
+            ...(refs.length > 0 ? { refs } : {}),
+            cases: normalizedCases
+        };
+    });
+}
+function flattenTestCaseCatalogs(catalogs) {
+    const rows = [];
+    for (const catalog of catalogs) {
+        for (const testCase of catalog.cases) {
+            rows.push({
+                kind: 'test-case',
+                id: `${catalog.id}.${testCase.id}`,
+                catalogId: catalog.id,
+                caseId: testCase.id,
+                filePath: 'tests/specs/index',
+                title: testCase.title,
+                ...(testCase.description ? { description: testCase.description } : {})
+            });
+        }
+    }
+    return rows;
+}
+function readSqlCaseCatalogsFromModule(moduleValue) {
+    if (!Array.isArray(moduleValue.sqlCatalogCases)) {
+        return [];
+    }
+    return moduleValue.sqlCatalogCases.map((catalog, index) => normalizeSqlCaseCatalog(catalog, index));
+}
+function normalizeSqlCaseCatalog(catalog, index) {
+    if (!(0, sqlCatalogDiscovery_1.isPlainObject)(catalog)) {
+        throw new TestEvidenceRuntimeError(`sqlCatalogCases[${index}] must be an object in evidence module.`);
+    }
+    const id = typeof catalog.id === 'string' ? catalog.id.trim() : '';
+    const title = typeof catalog.title === 'string' ? catalog.title.trim() : '';
+    if (!id || !title) {
+        throw new TestEvidenceRuntimeError(`sqlCatalogCases[${index}] requires non-empty id/title.`);
+    }
+    const details = (0, sqlCatalogDiscovery_1.isPlainObject)(catalog.catalog) ? catalog.catalog : {};
+    const params = (0, sqlCatalogDiscovery_1.isPlainObject)(details.params) ? details.params : {};
+    const output = (0, sqlCatalogDiscovery_1.isPlainObject)(details.output) ? details.output : {};
+    const mapping = (0, sqlCatalogDiscovery_1.isPlainObject)(output.mapping) ? output.mapping : {};
+    const columnMapRaw = (0, sqlCatalogDiscovery_1.isPlainObject)(mapping.columnMap) ? mapping.columnMap : {};
+    const columnMap = Object.fromEntries(Object.entries(columnMapRaw)
+        .filter((entry) => typeof entry[0] === 'string' && typeof entry[1] === 'string')
+        .sort((a, b) => a[0].localeCompare(b[0])));
+    const sql = typeof details.sql === 'string' ? details.sql : '';
+    const example = (0, sqlCatalogDiscovery_1.isPlainObject)(params.example) ? { ...params.example } : {};
+    const fixturesRaw = Array.isArray(catalog.fixtures) ? catalog.fixtures : [];
+    const fixtures = fixturesRaw
+        .filter((item) => (0, sqlCatalogDiscovery_1.isPlainObject)(item) && typeof item.tableName === 'string')
+        .map((item) => ({
+        tableName: item.tableName,
+        ...((0, sqlCatalogDiscovery_1.isPlainObject)(item.schema) && (0, sqlCatalogDiscovery_1.isPlainObject)(item.schema.columns)
+            ? {
+                schema: {
+                    columns: Object.fromEntries(Object.entries(item.schema.columns)
+                        .filter((entry) => typeof entry[0] === 'string' && typeof entry[1] === 'string')
+                        .sort((a, b) => a[0].localeCompare(b[0])))
+                }
+            }
+            : {}),
+        rowsCount: Array.isArray(item.rows) ? item.rows.length : typeof item.rowsCount === 'number' ? item.rowsCount : 0
+    }))
+        .sort((a, b) => a.tableName.localeCompare(b.tableName));
+    const casesRaw = Array.isArray(catalog.cases) ? catalog.cases : [];
+    const baseParams = (0, sqlCatalogDiscovery_1.isPlainObject)(params.example) ? { ...params.example } : {};
+    const cases = casesRaw
+        .filter((item) => (0, sqlCatalogDiscovery_1.isPlainObject)(item) && typeof item.id === 'string' && typeof item.title === 'string')
+        .map((item, caseIndex) => {
+        const arrangedParams = resolveCaseArrangeParams(item, index, caseIndex);
+        const mergedParams = arrangedParams ? { ...baseParams, ...arrangedParams } : { ...baseParams };
+        const expected = Array.isArray(item.expected) ? [...item.expected] : [];
+        return {
+            id: item.id,
+            title: item.title,
+            params: Object.fromEntries(Object.entries(mergedParams)
+                .filter((entry) => typeof entry[0] === 'string')
+                .sort((a, b) => a[0].localeCompare(b[0]))),
+            expected
+        };
+    })
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const nestedDefinitionPath = typeof details.definitionPath === 'string' && details.definitionPath.trim().length > 0
+        ? details.definitionPath.trim()
+        : undefined;
+    const description = typeof catalog.description === 'string' && catalog.description.trim().length > 0
+        ? catalog.description.trim()
+        : undefined;
+    const definitionPath = typeof catalog.definitionPath === 'string' && catalog.definitionPath.trim().length > 0
+        ? catalog.definitionPath.trim()
+        : nestedDefinitionPath;
+    return {
+        id,
+        title,
+        ...(description ? { description } : {}),
+        ...(definitionPath ? { definitionPath } : {}),
+        params: {
+            shape: 'named',
+            example
+        },
+        output: {
+            mapping: {
+                columnMap
+            }
+        },
+        // Keep SQL text unchanged so evidence remains a direct projection of test source.
+        sql,
+        fixtures,
+        cases
+    };
+}
+function resolveCaseArrangeParams(testCase, catalogIndex, caseIndex) {
+    const arrange = testCase.arrange;
+    if (arrange === undefined) {
+        return undefined;
+    }
+    if (typeof arrange !== 'function') {
+        throw new TestEvidenceRuntimeError(`sqlCatalogCases[${catalogIndex}].cases[${caseIndex}].arrange must be a function when provided.`);
+    }
+    const arranged = arrange();
+    if (!(0, sqlCatalogDiscovery_1.isPlainObject)(arranged)) {
+        throw new TestEvidenceRuntimeError(`sqlCatalogCases[${catalogIndex}].cases[${caseIndex}].arrange must return an object.`);
+    }
+    return arranged;
+}
+function loadTestCaseCatalogEvidence(rootDir, filePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse((0, node_fs_1.readFileSync)(filePath, 'utf8'));
+    }
+    catch (error) {
+        throw new TestEvidenceRuntimeError(`Failed to parse test-case catalog file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!(0, sqlCatalogDiscovery_1.isPlainObject)(parsed)) {
+        throw new TestEvidenceRuntimeError(`Test-case catalog file must contain an object: ${filePath}`);
+    }
+    const document = parsed;
+    if (!Array.isArray(document.catalogs)) {
+        throw new TestEvidenceRuntimeError(`Test-case catalog file must define a catalogs array: ${filePath}`);
+    }
+    const relative = normalizePath(node_path_1.default.relative(rootDir, filePath));
+    const rows = [];
+    const catalogs = document.catalogs;
+    for (const catalog of catalogs) {
+        const catalogId = typeof catalog.id === 'string' ? catalog.id.trim() : '';
+        if (!catalogId) {
+            throw new TestEvidenceRuntimeError(`Test-case catalog id must be a non-empty string: ${filePath}`);
+        }
+        if (!Array.isArray(catalog.cases)) {
+            throw new TestEvidenceRuntimeError(`Test-case catalog "${catalogId}" must define a cases array: ${filePath}`);
+        }
+        const cases = catalog.cases;
+        for (const testCase of cases) {
+            const caseId = typeof testCase.id === 'string' ? testCase.id.trim() : '';
+            const title = typeof testCase.title === 'string' ? testCase.title.trim() : '';
+            if (!caseId || !title) {
+                throw new TestEvidenceRuntimeError(`Test-case catalog "${catalogId}" requires each case to define non-empty id/title: ${filePath}`);
+            }
+            const description = typeof testCase.description === 'string' && testCase.description.trim().length > 0
+                ? testCase.description.trim()
+                : undefined;
+            rows.push({
+                kind: 'test-case',
+                id: `${catalogId}.${caseId}`,
+                catalogId,
+                caseId,
+                filePath: relative,
+                title,
+                ...(description ? { description } : {})
+            });
+        }
+    }
+    return rows;
+}
+function walkFiles(rootDir, predicate) {
+    const stack = [rootDir];
+    const files = [];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        const entries = (0, node_fs_1.readdirSync)(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            const absolute = node_path_1.default.join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(absolute);
+                continue;
+            }
+            if (entry.isFile() && predicate(absolute)) {
+                files.push(absolute);
+            }
+        }
+    }
+    return files.sort((a, b) => a.localeCompare(b));
+}
+function isTestCaseCatalogFile(filePath) {
+    const lowered = filePath.toLowerCase();
+    return lowered.endsWith('.test-case-catalog.json');
+}
+function normalizePath(input) {
+    return input.split(node_path_1.default.sep).join('/');
+}
+function normalizeCatalogRefs(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .filter((item) => (0, sqlCatalogDiscovery_1.isPlainObject)(item))
+        .map((item) => ({
+        label: typeof item.label === 'string' ? item.label.trim() : '',
+        url: typeof item.url === 'string' ? item.url.trim() : ''
+    }))
+        .filter((item) => item.label.length > 0 && item.url.length > 0)
+        .sort((a, b) => a.label.localeCompare(b.label) || a.url.localeCompare(b.url));
+}
+const TAG_NORMALIZATION_MAP = {
+    boundary: 'bva'
+};
+const INTENT_TAGS = ['normalization', 'validation', 'authorization', 'invariant'];
+const TECHNIQUE_TAGS = ['ep', 'bva', 'idempotence', 'state'];
+const INTENT_TAG_SET = new Set(INTENT_TAGS);
+const TECHNIQUE_TAG_SET = new Set(TECHNIQUE_TAGS);
+function normalizeCaseTags(tags) {
+    var _a;
+    const normalized = new Set();
+    for (const rawTag of tags) {
+        const lowered = rawTag.trim().toLowerCase();
+        const mapped = (_a = TAG_NORMALIZATION_MAP[lowered]) !== null && _a !== void 0 ? _a : lowered;
+        if (INTENT_TAG_SET.has(mapped) || TECHNIQUE_TAG_SET.has(mapped)) {
+            normalized.add(mapped);
+        }
+    }
+    const intent = INTENT_TAGS.find((tag) => normalized.has(tag));
+    const technique = TECHNIQUE_TAGS.find((tag) => normalized.has(tag));
+    const result = [];
+    if (intent) {
+        result.push(intent);
+    }
+    if (technique) {
+        result.push(technique);
+    }
+    return result;
+}
+function formatCaseTags(tags) {
+    const normalized = Array.isArray(tags) ? normalizeCaseTags(tags) : [];
+    return `[${normalized.join(', ')}]`;
+}
+function formatCaseFocus(focus) {
+    if (typeof focus === 'string' && focus.trim().length > 0) {
+        return focus.trim();
+    }
+    return '(not specified)';
+}
+function stringifyStablePretty(value) {
+    var _a;
+    return (_a = JSON.stringify(sortDeep(value), null, 2)) !== null && _a !== void 0 ? _a : 'null';
+}
+function stringifyErrorPretty(value) {
+    var _a;
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return 'null';
+    }
+    const source = value;
+    return (_a = JSON.stringify({
+        name: source.name,
+        message: source.message,
+        match: source.match
+    }, null, 2)) !== null && _a !== void 0 ? _a : 'null';
+}
+function sortDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sortDeep(item));
+    }
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .sort((a, b) => a[0].localeCompare(b[0]))
+            .map(([key, nested]) => [key, sortDeep(nested)]);
+        return Object.fromEntries(entries);
+    }
+    return value;
+}
+/**
+ * Render deterministic Markdown focused on human-readable test intent.
+ */
+function formatTestDocumentationOutput(report, context) {
+    const model = (0, test_evidence_core_1.buildSpecificationModel)(report);
+    return `${(0, test_evidence_renderer_md_1.renderTestDocumentationMarkdown)(model, {
+        definitionLinks: resolveDefinitionLinkOptions(context)
+    })}\n`;
+}
+function writeTestDocumentationArtifact(args) {
+    (0, node_fs_1.mkdirSync)(node_path_1.default.dirname(args.outPath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(args.outPath, formatTestDocumentationOutput(args.report, {
+        markdownPath: args.outPath,
+        sourceRootDir: args.sourceRootDir
+    }), 'utf8');
+    console.log(`wrote: ${args.outPath}`);
+}
+//# sourceMappingURL=testEvidence.js.map