cgraphx 1.2.0 → 1.3.1

package/dist/api-test/cli.js

@@ -0,0 +1,1009 @@
+"use strict";
+/**
+ * CLI wiring for the api-test subsystem.
+ *
+ * Exposes `registerApiTestCommands(program)` — called once from
+ * `src/bin/codegraph.ts`. All api-test subcommands live under
+ * `codegraph api-test <sub>`. The scan subcommand (T-20) is wired here;
+ * the analyze/assemble/run/report/list subcommands will be added in
+ * T-30 / T-40 / T-50 / T-60.
+ *
+ * Spec contract — scan:
+ *   - Full re-scan (delete `docs/api-test/<service>/` subtree, rebuild).
+ *   - Writes one `.bru` + one `.md` per endpoint under
+ *     `docs/api-test/<service>/<svc_id>_<methodName>.{bru,md}`.
+ *   - Writes `docs/api-test/bruno.json` at the api-test root with the
+ *     minimal Bruno collection schema.
+ *   - Failed endpoints don't abort the rest — warnings go to stderr.
+ *
+ * Exit codes:
+ *   0  success (or partial success with warnings)
+ *   2  config error (ConfigError — missing/invalid profile or config)
+ *   5  argument error
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__INTERNAL_CLI = void 0;
+exports.registerApiTestCommands = registerApiTestCommands;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const config_1 = require("./config");
+const errors_1 = require("./errors");
+const parser_httpservice_1 = require("./parser-httpservice");
+const bru_writer_1 = require("./bru-writer");
+const md_writer_1 = require("./md-writer");
+const java_parser_1 = require("./java-parser");
+const impl_finder_1 = require("./impl-finder");
+const field_extractor_1 = require("./field-extractor");
+const call_chain_extractor_1 = require("./call-chain-extractor");
+const assemble_1 = require("./assemble");
+const bru_runner_1 = require("./bru-runner");
+const test_history_1 = require("./test-history");
+const report_1 = require("./report");
+const errors_2 = require("./errors");
+const enhance_prepare_1 = require("./enhance-prepare");
+const enhance_write_1 = require("./enhance-write");
+const snapshot_1 = require("./snapshot");
+const verify_prepare_1 = require("./verify-prepare");
+const verify_write_1 = require("./verify-write");
+/** Default output root (relative to project root). */
+const DEFAULT_OUTPUT_DIR = 'docs/api-test';
+/** Minimal Bruno collection config — written to `<outputDir>/bruno.json`. */
+const BRUNO_COLLECTION_CONFIG = {
+    version: 1,
+    name: 'hx-api-test',
+    type: 'collection',
+};
+class ArgError extends Error {
+}
+/**
+ * Attach the `api-test` command group to a commander program.
+ */
+function registerApiTestCommands(program) {
+    const apiTest = program
+        .command('api-test')
+        .description('Java HTTP-service scan + Bruno test scaffolding (independent subsystem)');
+    // -- api-test scan --------------------------------------------------------
+    apiTest
+        .command('scan')
+        .description('Scan Java source for @Center interfaces and regenerate .bru + .md pairs under docs/api-test/')
+        .option('--project-root <path>', 'Project root to scan (defaults to cwd)', process.cwd())
+        .option('--output-dir <path>', 'Output directory (defaults to <projectRoot>/docs/api-test)')
+        .option('--filter <pattern>', 'Only emit endpoints whose service name matches the regex (optional)')
+        .option('--dry-run', 'Resolve + render, but do not write files')
+        .action(async (options) => {
+        try {
+            const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+            const outputDir = path.resolve(options.outputDir ?? path.join(projectRoot, DEFAULT_OUTPUT_DIR));
+            const config = (0, config_1.loadConfig)(projectRoot);
+            // Filter regex (optional)
+            let filterRe = null;
+            if (options.filter) {
+                try {
+                    filterRe = new RegExp(options.filter);
+                }
+                catch (err) {
+                    throw new ArgError(`--filter is not a valid regex: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            // Full re-scan: clear the existing output subtree before rebuilding.
+            // bruno.json is also rewritten below, so we don't preserve it.
+            if (!options.dryRun) {
+                await clearOutputDir(outputDir);
+            }
+            const endpoints = await (0, parser_httpservice_1.scanEndpoints)(projectRoot, config);
+            const filtered = filterRe
+                ? endpoints.filter((e) => filterRe.test(e.service))
+                : endpoints;
+            let okCount = 0;
+            let warnCount = 0;
+            for (const endpoint of filtered) {
+                try {
+                    if (options.dryRun) {
+                        // Dry-run: render to stdout (or just count) — don't write files.
+                        const bru = (0, bru_writer_1.renderBru)(endpoint, config);
+                        const md = (0, md_writer_1.renderMd)(endpoint);
+                        void bru;
+                        void md;
+                    }
+                    else {
+                        await (0, bru_writer_1.writeBru)(endpoint, config, outputDir);
+                        await (0, md_writer_1.writeMd)(endpoint, outputDir);
+                    }
+                    okCount++;
+                }
+                catch (err) {
+                    warnCount++;
+                    const msg = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`[api-test] warning: failed to write endpoint ${endpoint.svcId}_${endpoint.method}: ${msg}\n`);
+                }
+            }
+            // Write bruno.json at the api-test root (collection metadata).
+            if (!options.dryRun) {
+                await fs.promises.mkdir(outputDir, { recursive: true });
+                const brunoJsonPath = path.join(outputDir, 'bruno.json');
+                await fs.promises.writeFile(brunoJsonPath, JSON.stringify(BRUNO_COLLECTION_CONFIG, null, 2) + '\n', 'utf8');
+            }
+            process.stdout.write(`[api-test] scan complete: ${okCount} endpoint(s) written` +
+                (warnCount > 0 ? `, ${warnCount} warning(s)` : '') +
+                (options.dryRun ? ' (dry-run)' : '') +
+                ` → ${outputDir}\n`);
+            if (warnCount > 0)
+                process.exitCode = 0; // partial success still 0
+        }
+        catch (err) {
+            renderErrorAndExit(err);
+        }
+    });
+    // -- api-test analyze -----------------------------------------------------
+    apiTest
+        .command('analyze')
+        .description('Analyze Java impl classes to fill fields / call_chain / dep_tables / auth_required in .md files')
+        .option('--project-root <path>', 'Project root to scan (defaults to cwd)', process.cwd())
+        .option('--output-dir <path>', 'Output directory (defaults to <projectRoot>/docs/api-test)')
+        .option('--filter <pattern>', 'Only analyze endpoints whose service name matches the regex (optional)')
+        .option('--dry-run', 'Resolve + extract, but do not write files')
+        .action(async (options) => {
+        try {
+            const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+            const outputDir = path.resolve(options.outputDir ?? path.join(projectRoot, DEFAULT_OUTPUT_DIR));
+            const config = (0, config_1.loadConfig)(projectRoot);
+            // Per spec §9, analyze does NOT load the profile (only run does).
+            // Profile.json absence must not fail the analyze phase.
+            // Filter regex (optional)
+            let filterRe = null;
+            if (options.filter) {
+                try {
+                    filterRe = new RegExp(options.filter);
+                }
+                catch (err) {
+                    throw new ArgError(`--filter is not a valid regex: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            // Re-scan to get the fresh Endpoint[] (full overwrite — we don't
+            // read existing .md files because re-scan gives us the same metadata
+            // plus a clean slate; "全部覆盖" semantics).
+            const endpoints = await (0, parser_httpservice_1.scanEndpoints)(projectRoot, config);
+            const filtered = filterRe
+                ? endpoints.filter((e) => filterRe.test(e.service))
+                : endpoints;
+            // Build the allClasses cache: parse every .java file under
+            // projectRoot once, accumulate ClassInfo[]. Used by findImplFor,
+            // findVoClass (called by extractFields).
+            const allClasses = [];
+            for (const javaFile of iterJavaFilesCached(projectRoot)) {
+                try {
+                    const classes = await (0, java_parser_1.parseJavaFile)(javaFile);
+                    allClasses.push(...classes);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`[api-test] warning: failed to parse ${javaFile}: ${msg}\n`);
+                }
+            }
+            let okCount = 0;
+            let skipCount = 0;
+            let warnCount = 0;
+            for (const endpoint of filtered) {
+                try {
+                    const result = await analyzeEndpoint(endpoint, allClasses);
+                    endpoint.fields = result.fields;
+                    endpoint.callChain = result.callChain;
+                    endpoint.depTables = result.depTables;
+                    endpoint.authRequired = result.authRequired;
+                    if (result.skipReason) {
+                        endpoint.status = 'skip';
+                        endpoint.skipReason = result.skipReason;
+                        skipCount++;
+                    }
+                    else {
+                        endpoint.status = 'active';
+                        endpoint.skipReason = null;
+                        okCount++;
+                    }
+                    if (!options.dryRun) {
+                        // Re-render + overwrite the .md file (full overwrite).
+                        await (0, md_writer_1.writeMd)(endpoint, outputDir);
+                    }
+                }
+                catch (err) {
+                    warnCount++;
+                    const msg = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`[api-test] warning: failed to analyze endpoint ${endpoint.svcId}_${endpoint.method}: ${msg}\n`);
+                    // Mark as skip so the failure is visible in the .md.
+                    endpoint.status = 'skip';
+                    endpoint.skipReason = `analyze_error: ${msg}`;
+                    if (!options.dryRun) {
+                        try {
+                            await (0, md_writer_1.writeMd)(endpoint, outputDir);
+                        }
+                        catch {
+                            // swallow — best-effort
+                        }
+                    }
+                }
+            }
+            process.stdout.write(`[api-test] analyze complete: ${okCount} ok, ${skipCount} skipped` +
+                (warnCount > 0 ? `, ${warnCount} warning(s)` : '') +
+                (options.dryRun ? ' (dry-run)' : '') +
+                ` → ${outputDir}\n`);
+            if (warnCount > 0)
+                process.exitCode = 0;
+        }
+        catch (err) {
+            renderErrorAndExit(err);
+        }
+    });
+    // -- api-test assemble -----------------------------------------------------
+    apiTest
+        .command('assemble')
+        .description('Assemble request bodies from fixture/db-query data and write them into .bru body:json blocks')
+        .option('--project-root <path>', 'Project root (defaults to cwd)', process.cwd())
+        .option('--output-dir <path>', 'Output directory (defaults to <projectRoot>/docs/api-test)')
+        .option('--filter <pattern>', 'Only assemble endpoints whose service name matches the regex (optional)')
+        .option('--dry-run', 'Resolve + assemble, but do not write files')
+        .action(async (options) => {
+        try {
+            const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+            const outputDir = path.resolve(options.outputDir ?? path.join(projectRoot, DEFAULT_OUTPUT_DIR));
+            const config = (0, config_1.loadConfig)(projectRoot);
+            const fixtures = (0, config_1.loadFixtures)(projectRoot);
+            // Per spec §9, assemble does NOT load the profile (only run does).
+            // The profile is not needed for body assembly — Bruno's `{{var}}`
+            // syntax resolves env variables at request time during the run phase.
+            // Filter regex (optional)
+            let filterRe = null;
+            if (options.filter) {
+                try {
+                    filterRe = new RegExp(options.filter);
+                }
+                catch (err) {
+                    throw new ArgError(`--filter is not a valid regex: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            // Re-scan + re-analyze to get fresh endpoints with fields populated.
+            // (Same pattern as the analyze CLI — "full overwrite" semantics. The
+            // .md files are human-readable artifacts; the assemble phase doesn't
+            // parse them back, it re-derives from source so the body always
+            // matches the current code.)
+            const endpoints = await (0, parser_httpservice_1.scanEndpoints)(projectRoot, config);
+            const filtered = filterRe
+                ? endpoints.filter((e) => filterRe.test(e.service))
+                : endpoints;
+            // Build the allClasses cache for analyze.
+            const allClasses = [];
+            for (const javaFile of iterJavaFilesCached(projectRoot)) {
+                try {
+                    const classes = await (0, java_parser_1.parseJavaFile)(javaFile);
+                    allClasses.push(...classes);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`[api-test] warning: failed to parse ${javaFile}: ${msg}\n`);
+                }
+            }
+            let okCount = 0;
+            let skipCount = 0;
+            let warnCount = 0;
+            for (const endpoint of filtered) {
+                try {
+                    // Re-analyze to populate fields/callChain/depTables/authRequired.
+                    const result = await analyzeEndpoint(endpoint, allClasses);
+                    endpoint.fields = result.fields;
+                    endpoint.callChain = result.callChain;
+                    endpoint.depTables = result.depTables;
+                    endpoint.authRequired = result.authRequired;
+                    if (result.skipReason) {
+                        // Analyze-phase skip (impl_not_found / param_no_strong_type) —
+                        // propagate to .md, don't attempt assemble.
+                        endpoint.status = 'skip';
+                        endpoint.skipReason = result.skipReason;
+                        skipCount++;
+                        if (!options.dryRun) {
+                            await (0, md_writer_1.writeMd)(endpoint, outputDir);
+                        }
+                        continue;
+                    }
+                    endpoint.status = 'active';
+                    endpoint.skipReason = null;
+                    // Only assemble `active` endpoints.
+                    const assembled = await (0, assemble_1.assembleEndpoint)(endpoint, config, fixtures, projectRoot);
+                    if (assembled.skipped) {
+                        endpoint.status = 'skip';
+                        endpoint.skipReason = assembled.reason;
+                        skipCount++;
+                        if (!options.dryRun) {
+                            // Update .md with the skip status. Don't touch .bru body for
+                            // skipped endpoints (per spec: "skip 状态的 endpoint → 不修改 .bru body").
+                            await (0, md_writer_1.writeMd)(endpoint, outputDir);
+                        }
+                    }
+                    else {
+                        okCount++;
+                        if (!options.dryRun) {
+                            // Write the assembled body into the .bru's body:json block.
+                            // First ensure the .bru exists (scan phase writes it; if the
+                            // user skipped scan, we write it fresh here).
+                            if (!endpoint.bruPath || !fs.existsSync(endpoint.bruPath)) {
+                                await (0, bru_writer_1.writeBru)(endpoint, config, outputDir);
+                            }
+                            await (0, assemble_1.writeBruBody)(endpoint.bruPath, assembled.body);
+                        }
+                    }
+                }
+                catch (err) {
+                    warnCount++;
+                    const msg = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`[api-test] warning: failed to assemble endpoint ${endpoint.svcId}_${endpoint.method}: ${msg}\n`);
+                    endpoint.status = 'skip';
+                    endpoint.skipReason = `assemble_error: ${msg}`;
+                    if (!options.dryRun) {
+                        try {
+                            await (0, md_writer_1.writeMd)(endpoint, outputDir);
+                        }
+                        catch {
+                            // swallow — best-effort
+                        }
+                    }
+                }
+            }
+            process.stdout.write(`[api-test] assemble complete: ${okCount} ok, ${skipCount} skipped` +
+                (warnCount > 0 ? `, ${warnCount} warning(s)` : '') +
+                (options.dryRun ? ' (dry-run)' : '') +
+                ` → ${outputDir}\n`);
+            if (warnCount > 0)
+                process.exitCode = 0;
+        }
+        catch (err) {
+            renderErrorAndExit(err);
+        }
+    });
+    // -- api-test run ----------------------------------------------------------
+    apiTest
+        .command('run')
+        .description('Run assembled .bru requests via Bruno CLI and append results to JSONL history')
+        .option('--project-root <path>', 'Project root (defaults to cwd)', process.cwd())
+        .option('--output-dir <path>', 'Collection directory (defaults to <projectRoot>/docs/api-test)')
+        .option('--filter <pattern>', 'Only run endpoints whose service name matches the regex (optional)')
+        .option('--status <status>', 'Only run endpoints with this status (active|skip)', 'active')
+        .action(async (options) => {
+        try {
+            const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+            const outputDir = path.resolve(options.outputDir ?? path.join(projectRoot, DEFAULT_OUTPUT_DIR));
+            const config = (0, config_1.loadConfig)(projectRoot);
+            const profile = (0, config_1.loadProfile)(projectRoot);
+            // Validate --status.
+            const statusFilter = options.status ?? 'active';
+            if (statusFilter !== 'active' && statusFilter !== 'skip') {
+                throw new ArgError(`--status must be "active" or "skip", got: ${statusFilter}`);
+            }
+            // Filter regex (optional) — narrows by service name.
+            let filterRe = null;
+            if (options.filter) {
+                try {
+                    filterRe = new RegExp(options.filter);
+                }
+                catch (err) {
+                    throw new ArgError(`--filter is not a valid regex: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            // Re-scan to get the endpoint list (service + method + bruPath +
+            // mdPath). The .bru files are assumed to already exist on disk from
+            // a prior scan/analyze/assemble — run doesn't write .bru files.
+            const endpoints = await (0, parser_httpservice_1.scanEndpoints)(projectRoot, config);
+            const filteredEndpoints = filterRe
+                ? endpoints.filter((e) => filterRe.test(e.service))
+                : endpoints;
+            // Read each endpoint's .md file to determine status. Endpoints whose
+            // .md doesn't exist yet (scan never ran) default to 'active' so a
+            // fresh collection still runs.
+            const endpointStatuses = new Map();
+            for (const e of filteredEndpoints) {
+                endpointStatuses.set(`${e.svcId}_${e.method}`, readEndpointStatus(e, outputDir));
+            }
+            // Apply --status filter: only keep endpoints whose status matches.
+            // Bruno CLI runs the whole collection dir (or a service subdir when
+            // --filter narrows to one service); we filter the RESULTS by status
+            // after the run.
+            const filterService = pickFilterService(filterRe, filteredEndpoints);
+            let results;
+            try {
+                results = await (0, bru_runner_1.runBrunoCollection)(outputDir, profile, filterService ? { service: filterService } : undefined);
+            }
+            catch (err) {
+                if (err instanceof errors_1.BrunoCliError) {
+                    process.stderr.write(`[api-test] ${err.message}\n`);
+                    process.exitCode = 4;
+                    return;
+                }
+                throw err;
+            }
+            // Match results back to endpoints by name to enrich with service +
+            // status info. Results without a matching endpoint are still recorded
+            // (service = '(unknown)').
+            const endpointByName = new Map();
+            for (const e of filteredEndpoints) {
+                endpointByName.set(`${e.svcId}_${e.method}`, e);
+            }
+            const ranAt = new Date().toISOString();
+            let passedCount = 0;
+            let failedCount = 0;
+            let skippedCount = 0;
+            for (const result of results) {
+                const endpoint = endpointByName.get(result.endpoint);
+                const service = endpoint?.service ?? '(unknown)';
+                const status = endpointStatuses.get(result.endpoint) ?? 'active';
+                // --status filter: skip endpoints whose status doesn't match.
+                if (status !== statusFilter) {
+                    skippedCount++;
+                    continue;
+                }
+                const judgment = judgePass(result, profile);
+                const testRun = {
+                    endpoint: result.endpoint,
+                    service,
+                    ranAt,
+                    httpStatus: result.httpStatus,
+                    bizCode: judgment.bizCode,
+                    durationMs: result.durationMs,
+                    passed: judgment.passed,
+                    error: judgment.error,
+                };
+                try {
+                    (0, test_history_1.appendTestRunSync)(testRun, projectRoot);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    process.stderr.write(`[api-test] warning: failed to append history for ${result.endpoint}: ${msg}\n`);
+                }
+                if (judgment.passed) {
+                    passedCount++;
+                }
+                else {
+                    failedCount++;
+                }
+            }
+            process.stdout.write(`[api-test] run complete: ${passedCount} passed, ${failedCount} failed` +
+                (skippedCount > 0 ? `, ${skippedCount} skipped` : '') +
+                ` → ${outputDir}\n`);
+            // Non-zero exit when any endpoint failed, so CI can gate on it.
+            if (failedCount > 0)
+                process.exitCode = 1;
+        }
+        catch (err) {
+            renderErrorAndExit(err);
+        }
+    });
+    // -- api-test report -------------------------------------------------------
+    apiTest
+        .command('report')
+        .description('Aggregate the day\'s JSONL run history + .md catalog into a Markdown report')
+        .option('--project-root <path>', 'Project root (defaults to cwd)', process.cwd())
+        .option('--date <YYYY-MM-DD>', 'Report date, defaults to today (local)')
+        .action(async (options) => {
+        try {
+            const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+            const date = options.date ?? todayLocalYmd();
+            const md = await (0, report_1.generateReport)(projectRoot, date);
+            const outPath = (0, report_1.reportFilePath)(projectRoot, date);
+            await fs.promises.mkdir(path.dirname(outPath), { recursive: true });
+            await fs.promises.writeFile(outPath, md + '\n', 'utf8');
+            process.stdout.write(`${outPath}\n`);
+        }
+        catch (err) {
+            renderErrorAndExit(err);
+        }
+    });
+    // -- api-test list ---------------------------------------------------------
+    apiTest
+        .command('list')
+        .description('List every catalog endpoint with its most recent run result, after filters')
+        .option('--project-root <path>', 'Project root (defaults to cwd)', process.cwd())
+        .option('--service <name>', 'Filter by service name (exact match)')
+        .option('--status <status>', 'Filter by status (active|skip)')
+        .option('--svc-id <id>', 'Filter by svc_id (exact match)')
+        .action(async (options) => {
+        try {
+            const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+            const filters = {};
+            if (options.service)
+                filters.service = options.service;
+            if (options.svcId)
+                filters.svcId = options.svcId;
+            if (options.status) {
+                if (options.status !== 'active' && options.status !== 'skip') {
+                    throw new ArgError(`--status must be "active" or "skip", got: ${options.status}`);
+                }
+                filters.status = options.status;
+            }
+            const rows = (0, report_1.listEndpoints)(projectRoot, filters);
+            if (rows.length === 0) {
+                process.stdout.write('(no endpoints match the filters)\n');
+                return;
+            }
+            const table = (0, report_1.renderListTable)(rows);
+            process.stdout.write(table + '\n');
+        }
+        catch (err) {
+            renderErrorAndExit(err);
+        }
+    });
+    // -- api-test enhance-prepare ---------------------------------------------
+    apiTest
+        .command('enhance-prepare')
+        .description('Aggregate catalog .md + impl path + db sample rows + prior AI fields into a JSON payload for AI field inference')
+        .option('--project-root <path>', 'Project root (defaults to cwd)', process.cwd())
+        .option('--service <name>', 'Service subdirectory under docs/api-test/ (defaults to inst-service)', 'inst-service')
+        .option('--endpoint <name>', 'Endpoint stem <svc_id>_<method> (optional; defaults to all .md in the service dir)')
+        .action(async (options) => {
+        try {
+            const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+            const service = options.service ?? 'inst-service';
+            const results = await (0, enhance_prepare_1.enhancePrepare)(projectRoot, service, options.endpoint);
+            process.stdout.write(JSON.stringify(results, null, 2) + '\n');
+        }
+        catch (err) {
+            renderErrorAndExit(err);
+        }
+    });
+    // -- api-test enhance-write -----------------------------------------------
+    apiTest
+        .command('enhance-write')
+        .description('Re-generate a .bru file with AI-produced docs/tests/body blocks and persist AI-inferred fields')
+        .requiredOption('--endpoint <name>', 'Endpoint stem <svc_id>_<method>')
+        .requiredOption('--docs <file>', 'AI-generated docs block content (markdown)')
+        .requiredOption('--tests <file>', 'AI-generated tests block content (JS)')
+        .requiredOption('--body <file>', 'AI-assembled body JSON')
+        .option('--ai-fields <file>', 'AI-inferred source_table fields JSON (optional)')
+        .option('--service <name>', 'Service subdirectory (defaults to inst-service)', 'inst-service')
+        .option('--project-root <path>', 'Project root (defaults to cwd)', process.cwd())
+        .action(async (options) => {
+        try {
+            const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+            const bruPath = await (0, enhance_write_1.enhanceWrite)({
+                projectRoot,
+                endpoint: options.endpoint,
+                docsFile: options.docs,
+                testsFile: options.tests,
+                bodyFile: options.body,
+                aiFieldsFile: options.aiFields ?? null,
+                service: options.service ?? 'inst-service',
+            });
+            process.stdout.write(bruPath + '\n');
+        }
+        catch (err) {
+            renderErrorAndExit(err);
+        }
+    });
+    // -- api-test snapshot -----------------------------------------------------
+    apiTest
+        .command('snapshot')
+        .description('Capture dep_tables row snapshots before bru run, stored as runs/<run-id>-before.json')
+        .requiredOption('--endpoint <name>', 'Endpoint stem <svc_id>_<method>')
+        .requiredOption('--run-id <id>', 'Run identifier for before.json filename')
+        .option('--service <name>', 'Service subdirectory (defaults to inst-service)', 'inst-service')
+        .option('--project-root <path>', 'Project root (defaults to cwd)', process.cwd())
+        .action(async (options) => {
+        try {
+            const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+            const result = await (0, snapshot_1.snapshot)(projectRoot, options.endpoint, options.runId, options.service ?? 'inst-service');
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        }
+        catch (err) {
+            renderErrorAndExit(err);
+        }
+    });
+    // -- api-test verify-prepare ----------------------------------------------
+    apiTest
+        .command('verify-prepare')
+        .description('Read bru run report + before.json + post-run db snapshot, output structured JSON for AI verify')
+        .requiredOption('--endpoint <name>', 'Endpoint stem <svc_id>_<method>')
+        .requiredOption('--results <file>', 'bru run --output JSON report path')
+        .requiredOption('--run-id <id>', 'Run identifier for before.json lookup')
+        .option('--service <name>', 'Service subdirectory (defaults to inst-service)', 'inst-service')
+        .option('--project-root <path>', 'Project root (defaults to cwd)', process.cwd())
+        .action(async (options) => {
+        try {
+            const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+            const result = await (0, verify_prepare_1.verifyPrepare)(projectRoot, options.endpoint, options.results, options.runId, options.service ?? 'inst-service');
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        }
+        catch (err) {
+            renderErrorAndExit(err);
+        }
+    });
+    // -- api-test verify-write ------------------------------------------------
+    apiTest
+        .command('verify-write')
+        .description('Read verify-prepare JSON + AI temp files, compute overall_passed, append to ai JSONL')
+        .requiredOption('--endpoint <name>', 'Endpoint stem <svc_id>_<method>')
+        .requiredOption('--verify-prepare-json <file>', 'verify-prepare output JSON path')
+        .requiredOption('--ai-assertions <file>', 'AI-generated assertions result JSON')
+        .requiredOption('--db-verify <file>', 'AI-generated DB verify result JSON')
+        .requiredOption('--ran-at <iso>', 'ISO-8601 timestamp for JSONL filename + Layer 1 association')
+        .option('--service <name>', 'Service subdirectory (defaults to inst-service)', 'inst-service')
+        .option('--project-root <path>', 'Project root (defaults to cwd)', process.cwd())
+        .action(async (options) => {
+        try {
+            const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+            const jsonlPath = await (0, verify_write_1.verifyWrite)({
+                projectRoot,
+                endpoint: options.endpoint,
+                verifyPrepareJsonFile: options.verifyPrepareJson,
+                aiAssertionsFile: options.aiAssertions,
+                dbVerifyFile: options.dbVerify,
+                ranAt: options.ranAt,
+                service: options.service ?? 'inst-service',
+            });
+            process.stdout.write(jsonlPath + '\n');
+        }
+        catch (err) {
+            renderErrorAndExit(err);
+        }
+    });
+}
+// ─── Helpers ───────────────────────────────────────────────────────────────
+/**
+ * Walk `projectRoot` and yield every `.java` file path. Same ignore list as
+ * the scan phase (parser-httpservice.iterJavaFiles) — duplicated here to
+ * avoid leaking the scan module's internal helper through the CLI surface.
+ * Symlinks are not followed.
+ */
+function* iterJavaFilesCached(root) {
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.')) {
+            if (entry.isDirectory())
+                continue;
+        }
+        if (entry.isDirectory()) {
+            if (DEFAULT_IGNORE_DIRS.has(entry.name))
+                continue;
+            yield* iterJavaFilesCached(path.join(root, entry.name));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.java')) {
+            yield path.join(root, entry.name);
+        }
+    }
+}
+/** Default ignore list — mirrors parser-httpservice.DEFAULT_IGNORE_DIRS. */
+const DEFAULT_IGNORE_DIRS = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    'target',
+    'out',
+    '.git',
+    '.cgraphx',
+]);
+/**
+ * Run the analyze pipeline for one endpoint:
+ *   1. findImplFor(interfaceFqn, allClasses) — locate the impl class.
+ *   2. Match the interface method to the impl method (name + param count).
+ *   3. extractFields + extractCallChain.
+ *
+ * Returns the enriched fields/callChain/depTables/authRequired, plus a
+ * `skipReason` string when the endpoint should be marked `status: skip`.
+ */
+async function analyzeEndpoint(endpoint, allClasses) {
+    // 1. Find the impl class.
+    const implInfo = await (0, impl_finder_1.findImplFor)(endpoint.interfaceFqn, allClasses);
+    if (!implInfo) {
+        return {
+            fields: [],
+            callChain: [],
+            depTables: [],
+            authRequired: false,
+            skipReason: 'impl_not_found',
+        };
+    }
+    // 2. Match the interface method to the impl method by name + param count.
+    // The interface method's signature is on `endpoint.signature` (a string),
+    // but we have `endpoint.method` (name) and can count params from the
+    // signature. The impl method's parameters are on `implInfo.methods`.
+    const paramCount = countParamsInSignature(endpoint.signature);
+    const implMethod = findImplMethod(implInfo, endpoint.method, paramCount);
+    if (!implMethod) {
+        return {
+            fields: [],
+            callChain: [],
+            depTables: [],
+            authRequired: false,
+            skipReason: 'impl_method_not_found',
+        };
+    }
+    // 3. Extract fields + call chain.
+    const fields = await (0, field_extractor_1.extractFields)(endpoint, implInfo, implMethod, allClasses);
+    // When reverse-engineering fails, extractFields returns [] — mark skip.
+    const fieldExtractionFailed = implMethod.parameters.length > 0 && fields.length === 0;
+    const { callChain, depTables, authRequired } = await (0, call_chain_extractor_1.extractCallChain)(implInfo, implMethod);
+    return {
+        fields,
+        callChain,
+        depTables,
+        authRequired,
+        skipReason: fieldExtractionFailed ? 'param_no_strong_type' : null,
+    };
+}
+/** Count parameters in a signature string like `Object qryOrderList(Object reqVo)`. */
+function countParamsInSignature(signature) {
+    const m = /\((.*)\)/.exec(signature);
+    if (!m)
+        return 0;
+    const inner = (m[1] ?? '').trim();
+    if (!inner)
+        return 0;
+    // Naive split on commas — doesn't handle generic commas in `Map<K,V>` etc.
+    // For param-count matching, we strip generic angle-bracket contents first.
+    const cleaned = inner.replace(/<[^>]*>/g, '');
+    return cleaned.split(',').length;
+}
+/**
+ * Find the impl method matching `name` + `paramCount`. Falls back to
+ * name-only match if paramCount is 0 (defensive — shouldn't happen for
+ * real @Center methods, which always have ≥1 param).
+ */
+function findImplMethod(implInfo, name, paramCount) {
+    const byName = implInfo.methods.filter((m) => m.name === name);
+    if (byName.length === 0)
+        return null;
+    if (paramCount === 0)
+        return byName[0] ?? null;
+    const byArity = byName.find((m) => m.parameters.length === paramCount);
+    return byArity ?? byName[0] ?? null;
+}
+/**
+ * Remove the existing output subtree so a re-scan doesn't leave stale
+ * `.bru` / `.md` files behind for endpoints that no longer exist. Safe to
+ * call on a non-existent dir.
+ *
+ * Preserves any files / subdirs the user might have added that are NOT
+ * `.bru` / `.md` pairs? Spec says "full re-scan" = delete the whole
+ * `docs/api-test/<service>/` subtree and rewrite bruno.json. We follow
+ * that literally: delete the entire output dir's *.bru / *.md / bruno.json,
+ * and remove now-empty service subdirs.
+ */
+async function clearOutputDir(outputDir) {
+    let entries;
+    try {
+        entries = await fs.promises.readdir(outputDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    for (const entry of entries) {
+        const full = path.join(outputDir, entry.name);
+        if (entry.isDirectory()) {
+            // Recurse into service subdirs and clear .bru / .md files; remove the
+            // subdir if it ends up empty.
+            await clearServiceSubdir(full);
+        }
+        else if (entry.isFile() && (entry.name.endsWith('.bru') || entry.name.endsWith('.md') || entry.name === 'bruno.json')) {
+            await fs.promises.unlink(full);
+        }
+    }
+}
+/** Clear `.bru` / `.md` files inside a service subdirectory; rmdir if empty. */
+async function clearServiceSubdir(serviceDir) {
+    let entries;
+    try {
+        entries = await fs.promises.readdir(serviceDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    let remaining = 0;
+    for (const entry of entries) {
+        const full = path.join(serviceDir, entry.name);
+        if (entry.isDirectory()) {
+            remaining++; // don't touch nested dirs the user added
+        }
+        else if (entry.isFile() && (entry.name.endsWith('.bru') || entry.name.endsWith('.md'))) {
+            await fs.promises.unlink(full);
+        }
+        else {
+            remaining++;
+        }
+    }
+    if (remaining === 0) {
+        await fs.promises.rmdir(serviceDir).catch(() => { });
+    }
+}
+function renderErrorAndExit(err) {
+    if (err instanceof ArgError) {
+        process.stderr.write(`[api-test] ${err.message}\n`);
+        process.exitCode = 5;
+        return;
+    }
+    if (err instanceof errors_1.ConfigError) {
+        process.stderr.write(`[api-test] config error: ${err.message}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    if (err instanceof errors_2.ReportError) {
+        process.stderr.write(`[api-test] report error: ${err.message}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    if (err instanceof errors_1.BrunoCliError) {
+        process.stderr.write(`[api-test] ${err.message}\n`);
+        process.exitCode = 4;
+        return;
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[api-test] Unexpected error: ${msg}\n`);
+    process.exitCode = 1;
+}
+/** Today's date in the local timezone as `YYYY-MM-DD`. */
+function todayLocalYmd() {
+    const d = new Date();
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}
+// ─── Run-phase helpers ─────────────────────────────────────────────────────
+/**
+ * Read an endpoint's status from its `.md` frontmatter. Returns 'active'
+ * when the .md doesn't exist or the status line can't be found (defensive
+ * — a fresh collection with no analyze phase still runs).
+ */
+function readEndpointStatus(endpoint, outputDir) {
+    const mdPath = path.join(outputDir, endpoint.service, `${endpoint.svcId}_${endpoint.method}.md`);
+    let content;
+    try {
+        content = fs.readFileSync(mdPath, 'utf8');
+    }
+    catch {
+        return 'active';
+    }
+    const m = /^status:\s*(\w+)/m.exec(content);
+    if (!m)
+        return 'active';
+    return m[1] === 'skip' ? 'skip' : 'active';
+}
+/**
+ * When `--filter` narrows to exactly one service, return that service name
+ * so `runBrunoCollection` can narrow Bruno CLI's run to that subdir (faster).
+ * When multiple services match (or none), return null — run the whole
+ * collection and filter results after.
+ */
+function pickFilterService(filterRe, endpoints) {
+    if (!filterRe)
+        return null;
+    const services = new Set();
+    for (const e of endpoints) {
+        if (filterRe.test(e.service)) {
+            services.add(e.service);
+        }
+    }
+    if (services.size === 1) {
+        return [...services][0] ?? null;
+    }
+    return null;
+}
+/**
+ * Judge pass/fail for one Bruno run result against the profile's biz-code rule.
+ *
+ *   - Bruno-reported error (timeout / request_failed) → passed=false, error
+ *     forwarded.
+ *   - HTTP 5xx → passed=false, error=http_5xx.
+ *   - HTTP 4xx → passed=false, error=http_4xx.
+ *   - Other non-200 → passed=false, error=http_non_200.
+ *   - HTTP 200 + bizCodeField null → passed=true (HTTP-only check).
+ *   - HTTP 200 + bizCodeField set + value in bizCodeSuccessValues → passed=true.
+ *   - HTTP 200 + bizCodeField set + value NOT in success values → passed=false,
+ *     error=biz_code_value_mismatch.
+ *   - HTTP 200 + bizCodeField set + field missing from response body →
+ *     passed=false, error=biz_code_field_missing.
+ */
+function judgePass(result, profile) {
+    // Bruno-reported errors take precedence (timeout, request_failed, etc.).
+    if (result.error) {
+        return { passed: false, bizCode: null, error: result.error };
+    }
+    // Non-200 HTTP statuses.
+    if (result.httpStatus >= 500) {
+        return { passed: false, bizCode: null, error: 'http_5xx' };
+    }
+    if (result.httpStatus >= 400) {
+        return { passed: false, bizCode: null, error: 'http_4xx' };
+    }
+    if (result.httpStatus !== 200) {
+        return { passed: false, bizCode: null, error: 'http_non_200' };
+    }
+    // HTTP 200 — check biz code if configured.
+    if (profile.bizCodeField === null) {
+        return { passed: true, bizCode: null, error: null };
+    }
+    const bizCode = extractBizCode(result.responseBody, profile.bizCodeField);
+    if (bizCode === null) {
+        return { passed: false, bizCode: null, error: 'biz_code_field_missing' };
+    }
+    if (profile.bizCodeSuccessValues.includes(bizCode)) {
+        return { passed: true, bizCode, error: null };
+    }
+    return { passed: false, bizCode, error: 'biz_code_value_mismatch' };
+}
+/**
+ * Extract the biz code value from a response body. The body may be a JSON
+ * object or a JSON string. Returns the stringified value, or null when the
+ * field is absent / the body can't be parsed.
+ */
+function extractBizCode(responseBody, bizCodeField) {
+    if (!responseBody)
+        return null;
+    // Try parsing as JSON first.
+    let parsed;
+    try {
+        parsed = JSON.parse(responseBody);
+    }
+    catch {
+        // Not JSON — can't extract a structured field.
+        return null;
+    }
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        const v = parsed[bizCodeField];
+        if (v === undefined || v === null)
+            return null;
+        return String(v);
+    }
+    return null;
+}
+// Internal helpers re-exported for tests.
+exports.__INTERNAL_CLI = {
+    DEFAULT_OUTPUT_DIR,
+    BRUNO_COLLECTION_CONFIG,
+    clearOutputDir,
+    iterJavaFilesCached,
+    analyzeEndpoint,
+    countParamsInSignature,
+    findImplMethod,
+    readEndpointStatus,
+    pickFilterService,
+    judgePass,
+    extractBizCode,
+};
+//# sourceMappingURL=cli.js.map