cgraphx 1.2.0 → 1.3.0

package/dist/api-test/db-query-cli.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * db-query CLI subprocess wrapper — isolated in its own module so tests can
+ * `vi.spyOn` the `runDbQueryCli` export and intercept calls from
+ * `assemble.ts`.
+ *
+ * Why a separate module: when `runDbQueryCli` lived in `assemble.ts`,
+ * `assembleEndpoint` called it as a bare local function reference, which
+ * vitest's `vi.spyOn(module, 'runDbQueryCli')` could not intercept (the spy
+ * replaces the export binding, not the local binding). Cross-module imports
+ * route through the namespace, which the spy CAN replace.
+ *
+ * Independent subsystem — does NOT import from `src/dbquery/`. The db-query
+ * CLI is invoked as a subprocess (spec §12 isolation).
+ */
+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_DB_QUERY_CLI = void 0;
+exports.runDbQueryCli = runDbQueryCli;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+/**
+ * Invoke `cgraphx db query --sql <sql> --format json` via the dist binary.
+ * Returns the parsed rows on success, or `{ ok: false, reason: 'db_query_failed' }`
+ * on any non-zero exit (covers config error exit 2, safety exit 3, connection
+ * /timeout/disabled exit 4, arg error exit 5 — all collapse to the same skip
+ * reason per spec).
+ *
+ * Exported so tests can `vi.spyOn(dbQueryCliModule, 'runDbQueryCli')` instead
+ * of spawning a real subprocess / real DB connection.
+ */
+async function runDbQueryCli(sql, projectRoot) {
+    const binaryPath = resolveCodegraphBinary();
+    if (!binaryPath) {
+        return { ok: false, reason: 'db_query_failed' };
+    }
+    let stdout;
+    try {
+        stdout = (0, node_child_process_1.execFileSync)(process.execPath, [binaryPath, 'db', 'query', '--sql', sql, '--format', 'json'], {
+            encoding: 'utf8',
+            cwd: projectRoot,
+            timeout: 30_000,
+            maxBuffer: 10 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch {
+        // Non-zero exit (config error / connection / timeout / disabled / safety).
+        return { ok: false, reason: 'db_query_failed' };
+    }
+    try {
+        const parsed = JSON.parse(stdout);
+        return { ok: true, rows: parsed.rows ?? [] };
+    }
+    catch {
+        // Unparseable JSON output — treat as db-query failure.
+        return { ok: false, reason: 'db_query_failed' };
+    }
+}
+/**
+ * Resolve the `dist/bin/codegraph.js` binary path. Returns `null` when the
+ * binary can't be located (e.g., running from source without a build, or
+ * tests that don't care because they mock `runDbQueryCli`).
+ *
+ * Resolution order:
+ *   1. `dist/bin/codegraph.js` relative to this module (production —
+ *      `dist/api-test/db-query-cli.js` → `dist/bin/codegraph.js`).
+ *   2. `dist/bin/codegraph.js` relative to the package root when running
+ *      from `src/` via tsx (vitest) — only if the file exists.
+ */
+function resolveCodegraphBinary() {
+    // Production: __dirname = dist/api-test/, binary = dist/bin/codegraph.js
+    const prodPath = path.resolve(__dirname, '..', 'bin', 'codegraph.js');
+    if (fs.existsSync(prodPath))
+        return prodPath;
+    // Dev (tsx): __dirname = src/api-test/, binary = dist/bin/codegraph.js
+    const devPath = path.resolve(__dirname, '..', '..', '..', 'dist', 'bin', 'codegraph.js');
+    if (fs.existsSync(devPath))
+        return devPath;
+    return null;
+}
+/** Internal helper re-exported for tests. */
+exports.__INTERNAL_DB_QUERY_CLI = {
+    resolveCodegraphBinary,
+};
+//# sourceMappingURL=db-query-cli.js.map

package/dist/api-test/db-query-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-query-cli.js","sourceRoot":"","sources":["../../src/api-test/db-query-cli.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqBH,sCAoCC;AAvDD,4CAA8B;AAC9B,gDAAkC;AAClC,2DAAkD;AAOlD;;;;;;;;;GASG;AACI,KAAK,UAAU,aAAa,CACjC,GAAW,EACX,WAAmB;IAEnB,MAAM,UAAU,GAAG,sBAAsB,EAAE,CAAC;IAC5C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAClD,CAAC;IAED,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAA,iCAAY,EACnB,OAAO,CAAC,QAAQ,EAChB,CAAC,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,CAAC,EAC7D;YACE,QAAQ,EAAE,MAAM;YAChB,GAAG,EAAE,WAAW;YAChB,OAAO,EAAE,MAAM;YACf,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;YAC3B,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CACF,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;QAC3E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAClD,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAE/B,CAAC;QACF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,uDAAuD;QACvD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAClD,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,sBAAsB;IAC7B,yEAAyE;IACzE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;IACtE,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAE7C,uEAAuE;IACvE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;IACzF,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAE3C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,6CAA6C;AAChC,QAAA,uBAAuB,GAAG;IACrC,sBAAsB;CACvB,CAAC"}

package/dist/api-test/enhance-prepare.d.ts

@@ -0,0 +1,111 @@
+/**
+ * enhance-prepare phase (L-T-10).
+ *
+ * Aggregates everything an AI needs to infer `fields` for one endpoint into a
+ * single JSON payload (one entry per endpoint). The AI consumes this payload,
+ * infers fields, then `enhance-write` (L-T-20) persists them back to the
+ * `.md` file and `.cgraphx/api-test/ai-fields/`.
+ *
+ * Pipeline per endpoint:
+ *   1. Read the Layer 1 scan `.md` file (`docs/api-test/<service>/<endpoint>.md`).
+ *      Parse the frontmatter — scalars via `parseFrontmatter`, plus a small
+ *      custom parser for the nested `method_attr` block and the `fields` /
+ *      `dep_tables` / `call_chain` arrays (which `parseFrontmatter` skips).
+ *   2. Locate the impl class via `findImplFor(interfaceFqn, allClasses)` over
+ *      the project-wide `.java` cache. `implPath = cls.filePath` or null.
+ *   3. For each `dep_table`, call `runDbQueryCli` to fetch up to 5 sample
+ *      rows. Failures collapse to an empty array (don't block the endpoint).
+ *   4. Merge any previously-persisted AI fields from
+ *      `.cgraphx/api-test/ai-fields/<endpoint>.json` into the result.
+ *
+ * Independent subsystem — depends only on `./java-parser`, `./impl-finder`,
+ * `./report` (parseFrontmatter), `./db-query-cli`, `./ai-fields`, and the
+ * shared types. No imports from `src/extraction/` / `src/resolution/` /
+ * `src/db/`.
+ */
+import { type ClassInfo } from './java-parser';
+import type { EnhancePrepareResult, Field } from './types';
+/**
+ * Run enhance-prepare for one service (or one endpoint within it).
+ *
+ * @param projectRoot Project root containing `docs/api-test/`.
+ * @param service     Service subdirectory name (defaults to `inst-service`).
+ * @param endpoint    Optional endpoint stem (`<svc_id>_<method>`). When set,
+ *                    only that endpoint is prepared; otherwise every `.md`
+ *                    under the service dir is prepared.
+ * @returns One `EnhancePrepareResult` per endpoint (single-element when
+ *          `endpoint` is set, possibly empty when the .md doesn't exist).
+ */
+export declare function enhancePrepare(projectRoot: string, service?: string, endpoint?: string): Promise<EnhancePrepareResult[]>;
+/**
+ * List `.md` files under `serviceDir`. When `endpoint` is set, narrow to the
+ * single file `<endpoint>.md` (returns [] when absent). Otherwise every .md
+ * in the directory.
+ */
+declare function listEndpointMdFiles(serviceDir: string, endpoint?: string): string[];
+/** Parse every `.java` file under `root` into a flat `ClassInfo[]`. */
+declare function collectAllClasses(root: string): Promise<ClassInfo[]>;
+/** Walk `root` and yield every `.java` file path, skipping IGNORE_DIRS. */
+declare function iterJavaFiles(root: string): IterableIterator<string>;
+/**
+ * Prepare a single endpoint .md file. Returns null when the frontmatter is
+ * missing required keys (the .md isn't a valid catalog entry).
+ */
+declare function prepareOneEndpoint(projectRoot: string, mdFile: string, allClasses: ClassInfo[]): Promise<EnhancePrepareResult | null>;
+/**
+ * Fetch up to 5 sample rows from `table` via the db-query CLI. Returns `[]`
+ * on any failure (no profile configured, connection error, etc.) — never
+ * throws.
+ */
+declare function sampleTable(projectRoot: string, table: string): Promise<unknown[]>;
+/**
+ * Merge .md `fields` with previously-persisted AI fields. When the .md fields
+ * are empty (scan phase) but AI fields exist, use the AI fields. Otherwise
+ * keep the .md fields (analyze phase already filled them).
+ */
+declare function mergeFields(mdFields: Field[], projectRoot: string, endpoint: string): Field[];
+/**
+ * Parse the `method_attr:` block from the frontmatter into a typed object.
+ * Defaults match a missing annotation (all false).
+ */
+declare function parseMethodAttr(content: string): {
+    resolveParam: boolean;
+    handleReturn: boolean;
+    open: boolean;
+};
+/**
+ * Parse a YAML string-array field of the form:
+ *   <key>:
+ *     - item1
+ *     - item2
+ * or the inline form `<key>: []`. Returns `[]` when absent or empty.
+ */
+declare function parseStringArray(content: string, key: string): string[];
+/**
+ * Parse the `fields:` block (a YAML list of field maps) into `Field[]`.
+ * Returns `[]` when the block is `[]` or absent.
+ */
+declare function parseFieldsBlock(content: string): Field[];
+/** Parse one `  - param_index: N` + nested `    key: value` block. */
+declare function parseFieldEntry(block: string): Field;
+/** Strip surrounding quotes from a YAML scalar value (or return 'null' as-is). */
+declare function stripQuotes(v: string): string;
+/** Internal helpers re-exported for tests. */
+export declare const __INTERNAL_ENHANCE_PREPARE: {
+    DEFAULT_SERVICE: string;
+    DEFAULT_DOCS_DIR: string;
+    IGNORE_DIRS: Set<string>;
+    listEndpointMdFiles: typeof listEndpointMdFiles;
+    collectAllClasses: typeof collectAllClasses;
+    iterJavaFiles: typeof iterJavaFiles;
+    prepareOneEndpoint: typeof prepareOneEndpoint;
+    sampleTable: typeof sampleTable;
+    mergeFields: typeof mergeFields;
+    parseMethodAttr: typeof parseMethodAttr;
+    parseStringArray: typeof parseStringArray;
+    parseFieldsBlock: typeof parseFieldsBlock;
+    parseFieldEntry: typeof parseFieldEntry;
+    stripQuotes: typeof stripQuotes;
+};
+export {};
+//# sourceMappingURL=enhance-prepare.d.ts.map

package/dist/api-test/enhance-prepare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enhance-prepare.d.ts","sourceRoot":"","sources":["../../src/api-test/enhance-prepare.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,EAAiC,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAK9E,OAAO,KAAK,EAAE,oBAAoB,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAmB3D;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,MAAwB,EACjC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAqBjC;AAED;;;;GAIG;AACH,iBAAS,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAe5E;AAED,uEAAuE;AACvE,iBAAe,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAanE;AAED,2EAA2E;AAC3E,iBAAU,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAgB9D;AAED;;;GAGG;AACH,iBAAe,kBAAkB,CAC/B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,SAAS,EAAE,GACtB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAgEtC;AAED;;;;GAIG;AACH,iBAAe,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAcjF;AAED;;;;GAIG;AACH,iBAAS,WAAW,CAClB,QAAQ,EAAE,KAAK,EAAE,EACjB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,KAAK,EAAE,CAIT;AAID;;;GAGG;AACH,iBAAS,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG;IACzC,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;CACf,CASA;AAoBD;;;;;;GAMG;AACH,iBAAS,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAyBhE;AAED;;;GAGG;AACH,iBAAS,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,CA2BlD;AAED,sEAAsE;AACtE,iBAAS,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CA4B7C;AAED,kFAAkF;AAClF,iBAAS,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQtC;AAED,8CAA8C;AAC9C,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;CAetC,CAAC"}

package/dist/api-test/enhance-prepare.js

@@ -0,0 +1,425 @@
+"use strict";
+/**
+ * enhance-prepare phase (L-T-10).
+ *
+ * Aggregates everything an AI needs to infer `fields` for one endpoint into a
+ * single JSON payload (one entry per endpoint). The AI consumes this payload,
+ * infers fields, then `enhance-write` (L-T-20) persists them back to the
+ * `.md` file and `.cgraphx/api-test/ai-fields/`.
+ *
+ * Pipeline per endpoint:
+ *   1. Read the Layer 1 scan `.md` file (`docs/api-test/<service>/<endpoint>.md`).
+ *      Parse the frontmatter — scalars via `parseFrontmatter`, plus a small
+ *      custom parser for the nested `method_attr` block and the `fields` /
+ *      `dep_tables` / `call_chain` arrays (which `parseFrontmatter` skips).
+ *   2. Locate the impl class via `findImplFor(interfaceFqn, allClasses)` over
+ *      the project-wide `.java` cache. `implPath = cls.filePath` or null.
+ *   3. For each `dep_table`, call `runDbQueryCli` to fetch up to 5 sample
+ *      rows. Failures collapse to an empty array (don't block the endpoint).
+ *   4. Merge any previously-persisted AI fields from
+ *      `.cgraphx/api-test/ai-fields/<endpoint>.json` into the result.
+ *
+ * Independent subsystem — depends only on `./java-parser`, `./impl-finder`,
+ * `./report` (parseFrontmatter), `./db-query-cli`, `./ai-fields`, and the
+ * shared types. No imports from `src/extraction/` / `src/resolution/` /
+ * `src/db/`.
+ */
+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_ENHANCE_PREPARE = void 0;
+exports.enhancePrepare = enhancePrepare;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const java_parser_1 = require("./java-parser");
+const impl_finder_1 = require("./impl-finder");
+const report_1 = require("./report");
+const db_query_cli_1 = require("./db-query-cli");
+const ai_fields_1 = require("./ai-fields");
+/** Default service dir under `docs/api-test/` when `--service` is omitted. */
+const DEFAULT_SERVICE = 'inst-service';
+/** Default docs root (relative to project root). */
+const DEFAULT_DOCS_DIR = 'docs/api-test';
+/** Directories skipped when walking for .java files. */
+const IGNORE_DIRS = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    'target',
+    'out',
+    '.git',
+    '.cgraphx',
+]);
+/**
+ * Run enhance-prepare for one service (or one endpoint within it).
+ *
+ * @param projectRoot Project root containing `docs/api-test/`.
+ * @param service     Service subdirectory name (defaults to `inst-service`).
+ * @param endpoint    Optional endpoint stem (`<svc_id>_<method>`). When set,
+ *                    only that endpoint is prepared; otherwise every `.md`
+ *                    under the service dir is prepared.
+ * @returns One `EnhancePrepareResult` per endpoint (single-element when
+ *          `endpoint` is set, possibly empty when the .md doesn't exist).
+ */
+async function enhancePrepare(projectRoot, service = DEFAULT_SERVICE, endpoint) {
+    const serviceDir = path.join(projectRoot, DEFAULT_DOCS_DIR, service);
+    // 1. Enumerate endpoint .md files.
+    const mdFiles = listEndpointMdFiles(serviceDir, endpoint);
+    if (mdFiles.length === 0)
+        return [];
+    // 2. Initialize the Java parser once for the whole run.
+    await (0, java_parser_1.initJavaParser)();
+    // 3. Build the project-wide allClasses cache (lazy: only when at least one
+    //    .md exists). Skips node_modules / dist / target / etc.
+    const allClasses = await collectAllClasses(projectRoot);
+    // 4. Prepare each endpoint.
+    const results = [];
+    for (const mdFile of mdFiles) {
+        const result = await prepareOneEndpoint(projectRoot, mdFile, allClasses);
+        if (result)
+            results.push(result);
+    }
+    return results;
+}
+/**
+ * List `.md` files under `serviceDir`. When `endpoint` is set, narrow to the
+ * single file `<endpoint>.md` (returns [] when absent). Otherwise every .md
+ * in the directory.
+ */
+function listEndpointMdFiles(serviceDir, endpoint) {
+    if (endpoint) {
+        const file = path.join(serviceDir, `${endpoint}.md`);
+        return fs.existsSync(file) ? [file] : [];
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(serviceDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isFile() && e.name.endsWith('.md'))
+        .map((e) => path.join(serviceDir, e.name))
+        .sort();
+}
+/** Parse every `.java` file under `root` into a flat `ClassInfo[]`. */
+async function collectAllClasses(root) {
+    const out = [];
+    for (const file of iterJavaFiles(root)) {
+        try {
+            const classes = await (0, java_parser_1.parseJavaFile)(file);
+            out.push(...classes);
+        }
+        catch {
+            // Best-effort — unparseable files are skipped. The scan phase already
+            // logs these elsewhere; enhance-prepare shouldn't abort on a single
+            // bad file.
+        }
+    }
+    return out;
+}
+/** Walk `root` and yield every `.java` file path, skipping IGNORE_DIRS. */
+function* iterJavaFiles(root) {
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (IGNORE_DIRS.has(entry.name))
+                continue;
+            if (entry.name.startsWith('.'))
+                continue;
+            yield* iterJavaFiles(path.join(root, entry.name));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.java')) {
+            yield path.join(root, entry.name);
+        }
+    }
+}
+/**
+ * Prepare a single endpoint .md file. Returns null when the frontmatter is
+ * missing required keys (the .md isn't a valid catalog entry).
+ */
+async function prepareOneEndpoint(projectRoot, mdFile, allClasses) {
+    let content;
+    try {
+        content = fs.readFileSync(mdFile, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const endpoint = path.basename(mdFile, '.md');
+    // Scalars (string | null) via the shared parser.
+    const scalars = (0, report_1.parseFrontmatter)(content);
+    const interfaceFqn = scalars.interface_fqn ?? '';
+    const method = scalars.method ?? '';
+    const signature = scalars.signature ?? '';
+    const urlPattern = scalars.url_pattern ?? '';
+    const service = scalars.service ?? '';
+    const javadoc = scalars.javadoc ?? null;
+    if (!interfaceFqn || !method) {
+        // Not a recognizable catalog .md — skip silently.
+        return null;
+    }
+    // Nested / list fields via a small custom parser.
+    const methodAttr = parseMethodAttr(content);
+    const depTables = parseStringArray(content, 'dep_tables');
+    const callChain = parseStringArray(content, 'call_chain');
+    const fields = parseFieldsBlock(content);
+    // Locate the impl class.
+    let implPath = null;
+    try {
+        const impl = await (0, impl_finder_1.findImplFor)(interfaceFqn, allClasses);
+        implPath = impl?.filePath ?? null;
+    }
+    catch {
+        implPath = null;
+    }
+    // Sample each dep table.
+    const dbSamples = {};
+    for (const table of depTables) {
+        dbSamples[table] = await sampleTable(projectRoot, table);
+    }
+    // Merge previously-persisted AI fields (don't overwrite the .md fields —
+    // augment: if the .md has empty fields and AI fields exist, use AI's).
+    const mergedFields = mergeFields(fields, projectRoot, endpoint);
+    return {
+        endpoint,
+        service,
+        interfaceFqn,
+        method,
+        signature,
+        urlPattern,
+        methodAttr,
+        fields: mergedFields,
+        callChain,
+        depTables,
+        javadoc,
+        implPath,
+        dbSamples,
+    };
+}
+/**
+ * Fetch up to 5 sample rows from `table` via the db-query CLI. Returns `[]`
+ * on any failure (no profile configured, connection error, etc.) — never
+ * throws.
+ */
+async function sampleTable(projectRoot, table) {
+    // Defensive: the table name comes from the .md frontmatter (trusted input
+    // from the scan phase), but guard against obvious injection anyway.
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table))
+        return [];
+    try {
+        const result = await (0, db_query_cli_1.runDbQueryCli)(`SELECT * FROM ${table} LIMIT 5`, projectRoot);
+        if (result.ok)
+            return result.rows;
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Merge .md `fields` with previously-persisted AI fields. When the .md fields
+ * are empty (scan phase) but AI fields exist, use the AI fields. Otherwise
+ * keep the .md fields (analyze phase already filled them).
+ */
+function mergeFields(mdFields, projectRoot, endpoint) {
+    if (mdFields.length > 0)
+        return mdFields;
+    const ai = (0, ai_fields_1.readAiFields)(projectRoot, endpoint);
+    return ai?.fields ?? [];
+}
+// ─── Frontmatter nested-field parsers ───────────────────────────────────────
+/**
+ * Parse the `method_attr:` block from the frontmatter into a typed object.
+ * Defaults match a missing annotation (all false).
+ */
+function parseMethodAttr(content) {
+    const resolveParam = matchNestedBool(content, 'method_attr', 'resolve_param');
+    const handleReturn = matchNestedBool(content, 'method_attr', 'handle_return');
+    const open = matchNestedBool(content, 'method_attr', 'open');
+    return {
+        resolveParam: resolveParam ?? false,
+        handleReturn: handleReturn ?? false,
+        open: open ?? false,
+    };
+}
+/** Match `  <key>: true|false` nested under a `<parent>:` block. */
+function matchNestedBool(content, parent, key) {
+    // Find the parent block start.
+    const parentRe = new RegExp(`^${parent}:\\s*$`, 'm');
+    const parentMatch = parentRe.exec(content);
+    if (!parentMatch)
+        return null;
+    const after = content.slice(parentMatch.index + parentMatch[0].length);
+    // Match the first `  <key>: <bool>` at 2-space indent.
+    const re = new RegExp(`^\\s{2}${key}:\\s*(true|false)\\s*$`, 'm');
+    const m = re.exec(after);
+    if (!m)
+        return null;
+    return m[1] === 'true';
+}
+/**
+ * Parse a YAML string-array field of the form:
+ *   <key>:
+ *     - item1
+ *     - item2
+ * or the inline form `<key>: []`. Returns `[]` when absent or empty.
+ */
+function parseStringArray(content, key) {
+    // Inline empty form.
+    const inlineRe = new RegExp(`^${key}:\\s*\\[\\]\\s*$`, 'm');
+    if (inlineRe.test(content))
+        return [];
+    const parentRe = new RegExp(`^${key}:\\s*$`, 'm');
+    const parentMatch = parentRe.exec(content);
+    if (!parentMatch)
+        return [];
+    const after = content.slice(parentMatch.index + parentMatch[0].length);
+    const items = [];
+    const itemRe = /^\s{2}-\s+(.+?)\s*$/gm;
+    let m;
+    while ((m = itemRe.exec(after)) !== null) {
+        // Stop if we hit a non-indented line (next top-level key).
+        if (!/^\s/.test(after[m.index] ?? ' '))
+            break;
+        let v = m[1] ?? '';
+        // Strip surrounding quotes.
+        if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+            v = v.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+        }
+        else if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) {
+            v = v.slice(1, -1).replace(/''/g, "'");
+        }
+        items.push(v);
+    }
+    return items;
+}
+/**
+ * Parse the `fields:` block (a YAML list of field maps) into `Field[]`.
+ * Returns `[]` when the block is `[]` or absent.
+ */
+function parseFieldsBlock(content) {
+    // Inline empty form.
+    const inlineRe = /^fields:\s*\[\]\s*$/m;
+    if (inlineRe.test(content))
+        return [];
+    const parentRe = /^fields:\s*$/m;
+    const parentMatch = parentRe.exec(content);
+    if (!parentMatch)
+        return [];
+    const after = content.slice(parentMatch.index + parentMatch[0].length);
+    const fields = [];
+    // Each field entry starts with `  - param_index: N` and is followed by
+    // `    <key>: <value>` lines until the next entry or a non-indented line.
+    const entryRe = /^\s{2}-\s+param_index:\s*(\d+)\s*$/gm;
+    const entryStarts = [];
+    let m;
+    while ((m = entryRe.exec(after)) !== null) {
+        entryStarts.push(m.index);
+    }
+    for (let i = 0; i < entryStarts.length; i++) {
+        const start = entryStarts[i];
+        const end = i + 1 < entryStarts.length ? entryStarts[i + 1] : after.length;
+        const block = after.slice(start, end);
+        fields.push(parseFieldEntry(block));
+    }
+    return fields;
+}
+/** Parse one `  - param_index: N` + nested `    key: value` block. */
+function parseFieldEntry(block) {
+    const get = (key) => {
+        const re = new RegExp(`^\\s{4}${key}:\\s*(.*?)\\s*$`, 'm');
+        const m = re.exec(block);
+        if (!m)
+            return null;
+        return stripQuotes(m[1] ?? '');
+    };
+    const getBool = (key) => {
+        const v = get(key);
+        return v === 'true';
+    };
+    const getNullStr = (key) => {
+        const v = get(key);
+        if (v === null || v === 'null')
+            return null;
+        return v;
+    };
+    const paramIndex = parseInt(get('param_index') ?? '0', 10);
+    return {
+        paramIndex: Number.isNaN(paramIndex) ? 0 : paramIndex,
+        name: get('name') ?? '',
+        javaType: get('java_type') ?? '',
+        sourceTable: getNullStr('source_table'),
+        sourceColumn: getNullStr('source_column'),
+        sourceFilter: getNullStr('source_filter'),
+        literal: getNullStr('literal'),
+        fixtureOnly: getBool('fixture_only'),
+        required: getBool('required'),
+    };
+}
+/** Strip surrounding quotes from a YAML scalar value (or return 'null' as-is). */
+function stripQuotes(v) {
+    if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+        return v.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+    }
+    if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) {
+        return v.slice(1, -1).replace(/''/g, "'");
+    }
+    return v;
+}
+/** Internal helpers re-exported for tests. */
+exports.__INTERNAL_ENHANCE_PREPARE = {
+    DEFAULT_SERVICE,
+    DEFAULT_DOCS_DIR,
+    IGNORE_DIRS,
+    listEndpointMdFiles,
+    collectAllClasses,
+    iterJavaFiles,
+    prepareOneEndpoint,
+    sampleTable,
+    mergeFields,
+    parseMethodAttr,
+    parseStringArray,
+    parseFieldsBlock,
+    parseFieldEntry,
+    stripQuotes,
+};
+//# sourceMappingURL=enhance-prepare.js.map