@rawsql-ts/ztd-cli 0.20.0 → 0.20.3

package/dist/commands/query.js

@@ -0,0 +1,377 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUERY_USES_COMMAND_SPANS = void 0;
+exports.registerQueryCommands = registerQueryCommands;
+const format_1 = require("../query/format");
+const patch_1 = require("../query/patch");
+const lint_1 = require("../query/lint");
+const planner_1 = require("../query/planner");
+const report_1 = require("../query/report");
+const slice_1 = require("../query/slice");
+const structure_1 = require("../query/structure");
+const agentCli_1 = require("../utils/agentCli");
+const telemetry_1 = require("../utils/telemetry");
+exports.QUERY_USES_COMMAND_SPANS = {
+    resolveOptions: 'resolve-query-options',
+    renderOutput: 'render-query-usage-output',
+};
+/**
+ * Register strict-first impact investigation commands on the CLI root.
+ */
+function registerQueryCommands(program) {
+    const query = program.command('query').description('Impact investigation for SQL catalog assets');
+    query.addHelpText('after', `
+Examples:
+  $ ztd query uses table public.users
+  $ ztd query uses column public.users.email
+  $ ztd query uses column public.users.email --view detail
+  $ ztd query uses column users.email --any-schema --format json
+  $ ztd query uses column email --any-schema --any-table --format json
+  $ ztd query outline large_query.sql
+  $ ztd query graph large_query.sql --format dot
+  $ ztd query slice large_query.sql --cte purchase_summary
+  $ ztd query plan large_query.sql --material base_cte --scalar-filter-column sale_date --format json
+  $ ztd query patch apply large_query.sql --cte purchase_summary --from edited_slice.sql --preview
+  $ ztd query lint large_query.sql --format json
+
+Notes:
+  - Strict mode is the default. Relaxed modes are explicit opt-in only.
+  - Impact is the default view. Use --view detail for edit-ready locations/snippets.
+  - Impact representatives may omit select snippets; use --view detail for edit-ready SELECT occurrences.
+  - Use --exclude-generated to skip specs under src/catalog/specs/generated when those files are review-only noise.
+  - Static column analysis is inherently uncertain and labels ambiguity via confidence/notes.
+  - exprHints: best-effort only. Absence of exprHints does not imply the feature is not present.
+  - statement_fingerprint is stable across formatting/comment changes under the current normalization contract.
+`);
+    // Keep outline/graph/slice/plan aligned with the existing query surface from main.
+    // Issue #518 intentionally limits telemetry instrumentation in this file to query uses
+    // so conflict resolution does not narrow the established query command surface.
+    const uses = query.command('uses').description('Find where catalog SQL uses a table or column target');
+    uses
+        .command('table [target]')
+        .description('Find statements that use a table target')
+        .option('--format <format>', 'Output format (text|json)', 'text')
+        .option('--view <view>', 'Investigation view (impact|detail)', 'impact')
+        .option('--specs-dir <path>', 'Override SQL catalog specs directory (default: src/catalog/specs)')
+        .option('--sql-root <path>', 'Resolve sqlFile paths relative to the project SQL root first (default: src/sql)')
+        .option('--exclude-generated', 'Exclude specs under src/catalog/specs/generated from scan targets')
+        .option('--out <path>', 'Write output to file')
+        .option('--summary-only', 'Emit summary counts without per-match details')
+        .option('--limit <count>', 'Limit returned matches and warnings in the output')
+        .option('--json <payload>', 'Pass command options as a JSON object')
+        .option('--any-schema', 'Allow <table> lookup across schemas')
+        .option('--any-table', 'Unsupported for table usage')
+        .action((target, options) => {
+        runQueryUsesCommand('table', target, options);
+    });
+    uses
+        .command('column [target]')
+        .description('Find statements that use a column target')
+        .option('--format <format>', 'Output format (text|json)', 'text')
+        .option('--view <view>', 'Investigation view (impact|detail)', 'impact')
+        .option('--specs-dir <path>', 'Override SQL catalog specs directory (default: src/catalog/specs)')
+        .option('--sql-root <path>', 'Resolve sqlFile paths relative to the project SQL root first (default: src/sql)')
+        .option('--exclude-generated', 'Exclude specs under src/catalog/specs/generated from scan targets')
+        .option('--out <path>', 'Write output to file')
+        .option('--summary-only', 'Emit summary counts without per-match details')
+        .option('--limit <count>', 'Limit returned matches and warnings in the output')
+        .option('--json <payload>', 'Pass command options as a JSON object')
+        .option('--any-schema', 'Allow <table.column> or <column> lookup across schemas')
+        .option('--any-table', 'Allow <column> lookup across tables (requires --any-schema)')
+        .addHelpText('after', `
+Notes:
+  - Impact is the default view. Use --view detail if you need edit-ready locations/snippets.
+  - Impact representatives may omit select snippets; use --view detail for edit-ready SELECT occurrences.
+  - exprHints: best-effort only. Absence of exprHints does not imply the feature is not present.
+`)
+        .action((target, options) => {
+        runQueryUsesCommand('column', target, options);
+    });
+    query
+        .command('outline <sqlFile>')
+        .description('Summarize query structure, CTE dependencies, and base table usage')
+        .option('--format <format>', 'Output format (text|json)', 'text')
+        .option('--out <path>', 'Write output to file')
+        .action((sqlFile, options) => {
+        runQueryStructureCommand(sqlFile, options, false, 'ztd query outline');
+    });
+    query
+        .command('graph <sqlFile>')
+        .description('Emit the query dependency graph in text, JSON, or DOT form')
+        .option('--format <format>', 'Output format (text|json|dot)', 'text')
+        .option('--out <path>', 'Write output to file')
+        .action((sqlFile, options) => {
+        runQueryStructureCommand(sqlFile, options, true, 'ztd query graph');
+    });
+    query
+        .command('slice <sqlFile>')
+        .description('Generate a minimal executable SQL slice for a target CTE or the final query')
+        .option('--cte <name>', 'Slice a specific CTE into a standalone debug query')
+        .option('--final', 'Slice the final query while removing unused CTEs')
+        .option('--limit <count>', 'Add LIMIT to the emitted debug query when supported')
+        .option('--out <path>', 'Write output to file')
+        .action((sqlFile, options) => {
+        runQuerySliceCommand(sqlFile, options);
+    });
+    query
+        .command('plan <sqlFile>')
+        .description('Emit deterministic execution steps from CTE metadata')
+        .option('--format <format>', 'Output format (text|json)', 'text')
+        .option('--material <names>', 'Comma-separated CTE names to materialize')
+        .option('--scalar-filter-column <names>', 'Comma-separated column names to bind from WHERE scalar filters')
+        .option('--json <payload>', 'Pass command options as a JSON object')
+        .option('--out <path>', 'Write output to file')
+        .action((sqlFile, options) => {
+        runQueryPlanCommand(sqlFile, options);
+    });
+    query
+        .command('lint <sqlFile>')
+        .description('Report structural maintainability and analysis-safety issues in a SQL query')
+        .option('--format <format>', 'Output format (text|json)', 'text')
+        .option('--out <path>', 'Write output to file')
+        .action((sqlFile, options) => {
+        runQueryLintCommand(sqlFile, options);
+    });
+    query
+        .command('patch')
+        .description('Apply AI-edited SQL fragments back onto the original query safely')
+        .command('apply <sqlFile>')
+        .description('Replace one CTE in the original SQL with the matching definition from an edited SQL file')
+        .option('--cte <name>', 'Target CTE name to replace in the original query')
+        .option('--from <path>', 'Edited SQL file that contains the replacement CTE definition')
+        .option('--preview', 'Emit a unified diff without writing files')
+        .option('--out <path>', 'Write the patched SQL to a new file instead of overwriting the original')
+        .action((sqlFile, options) => {
+        runQueryPatchApplyCommand(sqlFile, options);
+    });
+}
+function runQueryUsesCommand(kind, target, options) {
+    const resolved = (0, telemetry_1.withSpanSync)(exports.QUERY_USES_COMMAND_SPANS.resolveOptions, () => {
+        var _a, _b, _c;
+        const merged = options.json ? { ...options, ...(0, agentCli_1.parseJsonPayload)(options.json, '--json') } : options;
+        const format = normalizeFormat((_a = normalizeStringOption(merged.format)) !== null && _a !== void 0 ? _a : (0, agentCli_1.getAgentOutputFormat)());
+        const view = normalizeView((_b = normalizeStringOption(merged.view)) !== null && _b !== void 0 ? _b : 'impact');
+        const resolvedTarget = (_c = normalizeStringOption(merged.target)) !== null && _c !== void 0 ? _c : target;
+        if (!resolvedTarget) {
+            throw new Error('A target must be provided either as a positional argument or via --json {"target": "..."}');
+        }
+        return {
+            merged,
+            format,
+            view,
+            resolvedTarget,
+        };
+    }, {
+        kind,
+        targetProvided: Boolean(target),
+        jsonPayload: Boolean(options.json),
+    });
+    const report = (0, report_1.buildQueryUsageReport)({
+        kind,
+        rawTarget: resolved.resolvedTarget,
+        rootDir: process.env.ZTD_PROJECT_ROOT,
+        specsDir: normalizeStringOption(resolved.merged.specsDir),
+        sqlRoot: normalizeStringOption(resolved.merged.sqlRoot),
+        excludeGenerated: normalizeBooleanOption(resolved.merged.excludeGenerated),
+        view: resolved.view,
+        anySchema: normalizeBooleanOption(resolved.merged.anySchema),
+        anyTable: normalizeBooleanOption(resolved.merged.anyTable)
+    });
+    (0, telemetry_1.withSpanSync)(exports.QUERY_USES_COMMAND_SPANS.renderOutput, () => {
+        const limitedReport = (0, format_1.applyQueryOutputControls)(report, {
+            summaryOnly: normalizeBooleanOption(resolved.merged.summaryOnly),
+            limit: normalizeLimit(resolved.merged.limit)
+        });
+        const contents = (0, format_1.formatQueryUsageReport)(limitedReport, resolved.format);
+        const outPath = normalizeStringOption(resolved.merged.out);
+        if (outPath) {
+            (0, report_1.writeQueryUsageOutput)(outPath, contents);
+            return;
+        }
+        console.log(contents.trimEnd());
+    }, {
+        format: resolved.format,
+        writesFile: Boolean(resolved.merged.out),
+    });
+}
+function runQueryStructureCommand(sqlFile, options, allowDot, commandName) {
+    var _a;
+    const format = normalizeStructureFormat((_a = options.format) !== null && _a !== void 0 ? _a : 'text', allowDot);
+    const report = (0, structure_1.buildQueryStructureReport)(sqlFile, commandName);
+    const contents = (0, structure_1.formatQueryStructureReport)(report, format);
+    if (options.out) {
+        (0, report_1.writeQueryUsageOutput)(options.out, contents);
+        return;
+    }
+    console.log(contents.trimEnd());
+}
+function runQuerySliceCommand(sqlFile, options) {
+    const report = (0, slice_1.buildQuerySliceReport)(sqlFile, {
+        cte: normalizeStringOption(options.cte),
+        final: normalizeBooleanOption(options.final),
+        limit: normalizeLimit(options.limit)
+    });
+    if (options.out) {
+        (0, report_1.writeQueryUsageOutput)(options.out, report.sql);
+        return;
+    }
+    console.log(report.sql.trimEnd());
+}
+function runQueryPlanCommand(sqlFile, options) {
+    var _a, _b;
+    const merged = options.json ? { ...options, ...(0, agentCli_1.parseJsonPayload)(options.json, '--json') } : options;
+    const scalarFilterOption = (_a = merged.scalarFilterColumns) !== null && _a !== void 0 ? _a : merged.scalarFilterColumn;
+    if (scalarFilterOption === undefined && merged.scalarMaterial !== undefined) {
+        throw new Error('Use scalarFilterColumns / --scalar-filter-column instead of scalarMaterial / --scalar-material.');
+    }
+    const format = normalizePlanFormat((_b = normalizeStringOption(merged.format)) !== null && _b !== void 0 ? _b : (0, agentCli_1.getAgentOutputFormat)());
+    const plan = (0, planner_1.buildQueryPipelinePlan)(sqlFile, {
+        material: normalizeListOption(merged.material, '--material'),
+        scalarFilterColumns: normalizeListOption(scalarFilterOption, '--scalar-filter-column')
+    });
+    const contents = (0, planner_1.formatQueryPipelinePlan)(plan, format);
+    const outPath = normalizeStringOption(merged.out);
+    if (outPath) {
+        (0, report_1.writeQueryUsageOutput)(outPath, contents);
+        return;
+    }
+    console.log(contents.trimEnd());
+}
+function runQueryLintCommand(sqlFile, options) {
+    var _a;
+    const format = normalizeLintFormat((_a = normalizeStringOption(options.format)) !== null && _a !== void 0 ? _a : (0, agentCli_1.getAgentOutputFormat)());
+    const report = (0, lint_1.buildQueryLintReport)(sqlFile);
+    const contents = (0, lint_1.formatQueryLintReport)(report, format);
+    if (options.out) {
+        (0, report_1.writeQueryUsageOutput)(options.out, contents);
+        return;
+    }
+    console.log(contents.trimEnd());
+}
+function runQueryPatchApplyCommand(sqlFile, options) {
+    const cte = normalizeRequiredStringOption(options.cte, '--cte');
+    const from = normalizeRequiredStringOption(options.from, '--from');
+    const report = (0, patch_1.applyQueryPatch)(sqlFile, {
+        cte,
+        from,
+        out: normalizeStringOption(options.out),
+        preview: normalizeBooleanOption(options.preview)
+    });
+    if ((0, agentCli_1.isJsonOutput)()) {
+        (0, agentCli_1.writeCommandEnvelope)('query patch apply', {
+            file: report.file,
+            edited_file: report.edited_file,
+            target_cte: report.target_cte,
+            preview: report.preview,
+            changed: report.changed,
+            written: report.written,
+            output_file: report.output_file,
+            diff: report.diff,
+            updated_sql: report.updated_sql
+        });
+        return;
+    }
+    if (report.preview) {
+        process.stdout.write(report.diff);
+        if (!report.diff.endsWith('\n')) {
+            process.stdout.write('\n');
+        }
+        return;
+    }
+    process.stdout.write([
+        `Patched CTE: ${report.target_cte}`,
+        `Edited SQL: ${report.edited_file}`,
+        `Output file: ${report.output_file}`,
+        `Changed: ${report.changed ? 'yes' : 'no'}`
+    ].join('\n'));
+    process.stdout.write('\n');
+}
+function normalizeLimit(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string' && typeof value !== 'number') {
+        throw new Error(`Unsupported limit type: ${typeof value}. Use a positive integer.`);
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`Unsupported limit: ${value}. Use a positive integer.`);
+    }
+    return parsed;
+}
+function normalizeStringOption(value) {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`Expected a string option but received ${typeof value}.`);
+    }
+    return value;
+}
+function normalizeRequiredStringOption(value, label) {
+    const normalized = normalizeStringOption(value);
+    if (!normalized) {
+        throw new Error(`${label} is required.`);
+    }
+    return normalized;
+}
+function normalizeBooleanOption(value) {
+    if (value === undefined) {
+        return false;
+    }
+    if (typeof value !== 'boolean') {
+        throw new Error(`Expected a boolean option but received ${typeof value}.`);
+    }
+    return value;
+}
+function normalizeListOption(value, label) {
+    if (value === undefined || value === null || value === '') {
+        return undefined;
+    }
+    const rawValues = Array.isArray(value) ? value : [value];
+    const normalized = [];
+    for (const rawValue of rawValues) {
+        if (typeof rawValue !== 'string') {
+            throw new Error(`Expected ${label} to be a string or string[] but received ${typeof rawValue}.`);
+        }
+        // Accept comma-separated CLI input and JSON arrays with one item per entry.
+        for (const item of rawValue.split(',')) {
+            const trimmed = item.trim();
+            if (trimmed.length > 0) {
+                normalized.push(trimmed);
+            }
+        }
+    }
+    return normalized.length > 0 ? normalized : undefined;
+}
+function normalizeFormat(format) {
+    const normalized = format.trim().toLowerCase();
+    if (normalized === 'text' || normalized === 'json') {
+        return normalized;
+    }
+    throw new Error(`Unsupported format: ${format}`);
+}
+function normalizePlanFormat(format) {
+    return normalizeFormat(format);
+}
+function normalizeLintFormat(format) {
+    return normalizeFormat(format);
+}
+function normalizeStructureFormat(format, allowDot) {
+    const normalized = format.trim().toLowerCase();
+    if (normalized === 'text' || normalized === 'json') {
+        return normalized;
+    }
+    if (allowDot && normalized === 'dot') {
+        return normalized;
+    }
+    throw new Error(`Unsupported format: ${format}`);
+}
+function normalizeView(view) {
+    const normalized = view.trim().toLowerCase();
+    if (normalized === 'impact' || normalized === 'detail') {
+        return normalized;
+    }
+    throw new Error(`Unsupported view: ${view}`);
+}
+//# sourceMappingURL=query.js.map

package/dist/commands/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/commands/query.ts"],"names":[],"mappings":"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"}

package/dist/commands/testEvidence.d.ts

@@ -0,0 +1,237 @@
+import { Command } from 'commander';
+import { type DiffCase as CorePrDiffCase, type DiffCatalog as CorePrDiffCatalog, type DiffJson as CoreTestSpecificationPrDiff } from '@rawsql-ts/test-evidence-core';
+import { type RemovedDetailLevel } from '@rawsql-ts/test-evidence-renderer-md';
+/**
+ * Supported evidence generation modes for `ztd evidence`.
+ */
+export type TestEvidenceMode = 'specification';
+/**
+ * Output formats accepted by `ztd evidence`.
+ */
+export type TestEvidenceFormat = 'json' | 'markdown' | 'both';
+type TestEvidenceErrorCode = 'NO_SPECS_FOUND';
+/**
+ * Evidence row summarizing one SQL catalog spec file.
+ */
+export interface SqlCatalogSpecEvidence {
+    kind: 'sql-catalog';
+    id: string;
+    specFile: string;
+    sqlFile: string | null;
+    sqlFileResolved: boolean;
+    paramsShape: 'named' | 'positional' | 'unknown';
+    hasOutputMapping: boolean;
+}
+/**
+ * Flattened executable test-case evidence row.
+ */
+export interface TestCaseEvidence {
+    kind: 'test-case';
+    id: string;
+    catalogId: string;
+    caseId: string;
+    filePath: string;
+    title: string;
+    description?: string;
+}
+/**
+ * Top-level deterministic evidence document for specification mode.
+ */
+export interface TestSpecificationEvidence {
+    schemaVersion: 1;
+    mode: TestEvidenceMode;
+    summary: {
+        sqlCatalogCount: number;
+        sqlCaseCatalogCount: number;
+        testCaseCount: number;
+        specFilesScanned: number;
+        testFilesScanned: number;
+    };
+    sqlCatalogs: SqlCatalogSpecEvidence[];
+    sqlCaseCatalogs: SqlCaseCatalogEvidence[];
+    testCaseCatalogs: TestCaseCatalogEvidence[];
+    testCases: TestCaseEvidence[];
+    display?: {
+        summaryOnly: boolean;
+        limit?: number;
+        truncated: boolean;
+    };
+}
+/**
+ * Normalized case payload used for deterministic PR diff calculation.
+ */
+export type PrDiffCase = CorePrDiffCase;
+/**
+ * Normalized catalog payload used for deterministic PR diff calculation.
+ */
+export type PrDiffCatalog = CorePrDiffCatalog;
+/**
+ * Deterministic diff document for PR-focused test evidence output.
+ */
+export type TestSpecificationPrDiff = CoreTestSpecificationPrDiff;
+/**
+ * Deterministic evidence representation of an executable function test catalog.
+ */
+export interface TestCaseCatalogEvidence {
+    id: string;
+    title: string;
+    description?: string;
+    definitionPath?: string;
+    refs?: Array<{
+        label: string;
+        url: string;
+    }>;
+    cases: Array<{
+        id: string;
+        title: string;
+        description?: string;
+        input: unknown;
+        expected: 'success' | 'throws' | 'errorResult';
+        output?: unknown;
+        error?: {
+            name: string;
+            message: string;
+            match: 'equals' | 'contains';
+        };
+        tags?: string[];
+        focus?: string;
+        refs?: Array<{
+            label: string;
+            url: string;
+        }>;
+    }>;
+}
+/**
+ * Deterministic evidence representation of an executable SQL case catalog.
+ */
+export interface SqlCaseCatalogEvidence {
+    id: string;
+    title: string;
+    description?: string;
+    definitionPath?: string;
+    params: {
+        shape: 'named';
+        example: Record<string, unknown>;
+    };
+    output: {
+        mapping: {
+            columnMap: Record<string, string>;
+        };
+    };
+    sql: string;
+    fixtures: Array<{
+        tableName: string;
+        schema?: {
+            columns: Record<string, string>;
+        };
+        rowsCount: number;
+    }>;
+    cases: Array<{
+        id: string;
+        title: string;
+        params: Record<string, unknown>;
+        expected: unknown[];
+    }>;
+}
+/**
+ * Runtime/configuration error for test evidence command (maps to exit code 2).
+ */
+export declare class TestEvidenceRuntimeError extends Error {
+    readonly exitCode = 2;
+    readonly code?: TestEvidenceErrorCode;
+    constructor(message: string, options?: {
+        code?: TestEvidenceErrorCode;
+    });
+}
+/**
+ * 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.
+ */
+export declare function resolveTestEvidenceExitCode(args: {
+    result?: TestSpecificationEvidence;
+    error?: unknown;
+}): 0 | 1 | 2;
+/**
+ * Register `ztd evidence` command on the CLI root program.
+ */
+export declare function registerTestEvidenceCommand(program: Command): void;
+/**
+ * Build deterministic specification evidence from SQL catalog specs and test-case catalog exports.
+ */
+export declare function runTestEvidenceSpecification(options: {
+    mode: TestEvidenceMode;
+    rootDir?: string;
+    specsDir?: string;
+    testsDir?: string;
+    specModule?: string;
+}): TestSpecificationEvidence;
+/**
+ * Render deterministic JSON or Markdown output text.
+ */
+export declare function formatTestEvidenceOutput(report: TestSpecificationEvidence, format: Exclude<TestEvidenceFormat, 'both'>, context?: {
+    markdownPath?: string;
+    sourceRootDir?: string;
+}): string;
+/**
+ * Stable stringify that sorts object keys recursively for deterministic fingerprinting.
+ */
+export declare function stableStringify(value: unknown): string;
+/**
+ * Build deterministic PR diff JSON from base/head specification reports.
+ */
+export declare function buildTestEvidencePrDiff(args: {
+    base: {
+        ref: string;
+        sha: string;
+        report: TestSpecificationEvidence;
+    };
+    head: {
+        ref: string;
+        sha: string;
+        report: TestSpecificationEvidence;
+    };
+    baseMode: 'merge-base' | 'ref';
+}): TestSpecificationPrDiff;
+/**
+ * Render PR-focused markdown from diff JSON.
+ */
+export declare function formatTestEvidencePrMarkdown(diff: TestSpecificationPrDiff, options?: {
+    removedDetail?: RemovedDetailLevel;
+    markdownPath?: string;
+    sourceRootDir?: string;
+}): string;
+/**
+ * Generate base/head reports, compute PR diff JSON, and write PR artifacts.
+ */
+export declare function runTestEvidencePr(options: {
+    baseRef: string;
+    headRef: string;
+    baseMode: 'merge-base' | 'ref';
+    allowEmptyBase?: boolean;
+    removedDetail?: RemovedDetailLevel;
+    outDir: string;
+    rootDir?: string;
+    specsDir?: string;
+    testsDir?: string;
+    specModule?: string;
+    summaryOnly?: boolean;
+    limit?: number;
+}): {
+    baseReport: TestSpecificationEvidence;
+    headReport: TestSpecificationEvidence;
+    diff: TestSpecificationPrDiff;
+};
+export declare function applyEvidenceOutputControls(report: TestSpecificationEvidence, options: {
+    summaryOnly?: boolean;
+    limit?: number;
+}): TestSpecificationEvidence;
+/**
+ * Render deterministic Markdown focused on human-readable test intent.
+ */
+export declare function formatTestDocumentationOutput(report: TestSpecificationEvidence, context?: {
+    markdownPath?: string;
+    sourceRootDir?: string;
+}): string;
+export {};