@specverse/engines 6.0.6 → 6.0.8

package/dist/analyse-prepass/adapters/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SpecVerse adapters — translate StructuralPrepass output into SpecVerse
+ * vocabulary (entities / relationships / lifecycles / controllers / etc.).
+ *
+ * Each adapter is per-framework (NOT per-language). Most languages have
+ * 2-4 dominant ORMs / frameworks; ~10 adapters cover ~90% of analyse cases.
+ */
+export { extractTypeScriptPrisma, type PrismaFacts, type PrismaEntity, type PrismaField, type PrismaRelation, } from './typescript-prisma.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/analyse-prepass/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/analyse-prepass/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,uBAAuB,EACvB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,wBAAwB,CAAC"}

package/dist/analyse-prepass/adapters/index.js

@@ -0,0 +1,9 @@
+/**
+ * SpecVerse adapters — translate StructuralPrepass output into SpecVerse
+ * vocabulary (entities / relationships / lifecycles / controllers / etc.).
+ *
+ * Each adapter is per-framework (NOT per-language). Most languages have
+ * 2-4 dominant ORMs / frameworks; ~10 adapters cover ~90% of analyse cases.
+ */
+export { extractTypeScriptPrisma, } from './typescript-prisma.js';
+//# sourceMappingURL=index.js.map

package/dist/analyse-prepass/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/analyse-prepass/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,uBAAuB,GAKxB,MAAM,wBAAwB,CAAC"}

package/dist/analyse-prepass/adapters/typescript-prisma.d.ts

@@ -0,0 +1,67 @@
+/**
+ * TypeScript + Prisma adapter — the first SpecVerse-vocabulary translator.
+ *
+ * Reads `schema.prisma` files surfaced by the structural pre-pass and
+ * extracts SpecVerse facts:
+ *   - Models → entities
+ *   - `@relation` declarations → relationships (belongsTo / hasMany)
+ *   - enum declarations → lifecycle state candidates (when paired with a
+ *     status-typed field on a model)
+ *   - Field types + modifiers (@id, @unique, @default) → SpecVerse attributes
+ *
+ * Why Prisma first: SpecVerse realize emits Prisma in its default backend
+ * stack, so every Class 1 corpus case (poll-app, full-stack-template,
+ * steps-example) uses Prisma. Prisma's vocabulary is also closer to
+ * SpecVerse than other ORMs — minimal semantic translation needed.
+ *
+ * Adapter responsibilities (per the structural-prepass proposal):
+ *   - Consume the StructuralPrepass interface (file listings, source text)
+ *   - NOT parse arbitrary code (that's the backend's job — tree-sitter)
+ *   - Produce SpecVerse-shaped facts that the analyse prompt can consume
+ */
+import type { StructuralPrepass } from '../interface.js';
+export interface PrismaField {
+    name: string;
+    type: string;
+    required: boolean;
+    unique: boolean;
+    default?: string;
+    isId: boolean;
+    isList: boolean;
+}
+export interface PrismaRelation {
+    fromModel: string;
+    toModel: string;
+    /** belongsTo if the FK lives on this side; hasMany if inverse */
+    type: 'belongsTo' | 'hasMany' | 'hasOne';
+    cascade: boolean;
+    /** The field name carrying the relation (for belongsTo) or the inverse field (for hasMany) */
+    fieldName: string;
+}
+export interface PrismaEntity {
+    name: string;
+    filePath: string;
+    fields: PrismaField[];
+    /** Lifecycle state literals from a status field's enum, if detected. */
+    lifecycleStates?: string[];
+    /** The status field name (if a lifecycle was detected). */
+    lifecycleField?: string;
+}
+export interface PrismaFacts {
+    entities: PrismaEntity[];
+    relationships: PrismaRelation[];
+    /** Enum declarations in source — keyed by name. Used by the lifecycle detector. */
+    enums: Record<string, string[]>;
+    /** Schema files found. */
+    schemaFiles: string[];
+}
+/**
+ * Run the Prisma adapter against a structural pre-pass.
+ *
+ * The adapter relies on `prepass.fileSourceText()` to read schema.prisma
+ * directly — it doesn't need any of the backend's call-graph or symbol
+ * indexing for Prisma extraction. Prisma's schema syntax is small enough
+ * that regex over the raw text is the right tool.
+ */
+export declare function extractTypeScriptPrisma(prepass: StructuralPrepass): Promise<PrismaFacts>;
+//# sourceMappingURL=typescript-prisma.d.ts.map

package/dist/analyse-prepass/adapters/typescript-prisma.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript-prisma.d.ts","sourceRoot":"","sources":["../../../src/analyse-prepass/adapters/typescript-prisma.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,aAAa,EAAE,cAAc,EAAE,CAAC;IAChC,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAChC,0BAA0B;IAC1B,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAyG9F"}

package/dist/analyse-prepass/adapters/typescript-prisma.js

@@ -0,0 +1,167 @@
+/**
+ * Run the Prisma adapter against a structural pre-pass.
+ *
+ * The adapter relies on `prepass.fileSourceText()` to read schema.prisma
+ * directly — it doesn't need any of the backend's call-graph or symbol
+ * indexing for Prisma extraction. Prisma's schema syntax is small enough
+ * that regex over the raw text is the right tool.
+ */
+export async function extractTypeScriptPrisma(prepass) {
+    const schemaFiles = await prepass.listFiles({ glob: '**/schema.prisma' });
+    if (schemaFiles.length === 0) {
+        return { entities: [], relationships: [], enums: {}, schemaFiles: [] };
+    }
+    const enums = {};
+    const entities = [];
+    const relationships = [];
+    for (const file of schemaFiles) {
+        const text = await prepass.fileSourceText(file);
+        // Extract enum declarations
+        for (const match of text.matchAll(/enum\s+(\w+)\s*\{([^}]+)\}/g)) {
+            const name = match[1];
+            const body = match[2];
+            const values = body
+                .split(/\r?\n/)
+                .map((l) => l.trim())
+                .filter((l) => l && !l.startsWith('//'))
+                .map((l) => l.split(/\s+/)[0])
+                .filter(Boolean);
+            enums[name] = values;
+        }
+        // Extract model declarations
+        for (const match of text.matchAll(/model\s+(\w+)\s*\{([^}]+)\}/g)) {
+            const modelName = match[1];
+            const body = match[2];
+            const fields = parseFields(body);
+            // Detect lifecycle: a field of an enum type — the enum's values are
+            // candidate states. Common SpecVerse pattern: `status SomeStatus` field
+            // with a corresponding `enum SomeStatus { ... }`.
+            let lifecycleStates;
+            let lifecycleField;
+            for (const f of fields) {
+                // The field type may itself be an enum we extracted above
+                const typeName = f.type.replace(/\?$/, ''); // strip optional marker
+                if (enums[typeName]) {
+                    lifecycleStates = enums[typeName];
+                    lifecycleField = f.name;
+                    break; // Take first enum-typed field; canonical is `status`
+                }
+            }
+            entities.push({
+                name: modelName,
+                filePath: file,
+                fields,
+                lifecycleStates,
+                lifecycleField,
+            });
+            // Extract relationships from this model's fields
+            for (const rel of parseRelationships(modelName, body, fields)) {
+                relationships.push(rel);
+            }
+        }
+    }
+    // Second pass: derive `hasMany` from `belongsTo` declarations on the inverse
+    // side (Prisma schemas typically declare both sides explicitly). Crucially,
+    // we PROPAGATE cascade flags from the belongsTo side (where Prisma's
+    // `onDelete: Cascade` syntactically lives) up to the hasMany side (where
+    // SpecVerse semantics expect the cascade decision to live — "deleting the
+    // parent cascades to its children").
+    const declaredHasMany = new Set(relationships.filter((r) => r.type === 'hasMany').map((r) => `${r.fromModel}→${r.toModel}`));
+    for (const ent of entities) {
+        for (const f of ent.fields) {
+            if (!f.isList)
+                continue;
+            // Is this a list-typed field whose type is another model?
+            const typeName = f.type.replace(/\[\]$/, '').replace(/\?$/, '');
+            const isModel = entities.some((e) => e.name === typeName);
+            if (!isModel)
+                continue;
+            const key = `${ent.name}→${typeName}`;
+            if (!declaredHasMany.has(key)) {
+                // Find the inverse belongsTo (if declared) — it carries the cascade flag
+                // that we want to surface on the hasMany side.
+                const inverse = relationships.find((r) => r.type === 'belongsTo' && r.fromModel === typeName && r.toModel === ent.name);
+                relationships.push({
+                    fromModel: ent.name,
+                    toModel: typeName,
+                    type: 'hasMany',
+                    cascade: inverse?.cascade ?? false,
+                    fieldName: f.name,
+                });
+                declaredHasMany.add(key);
+            }
+        }
+    }
+    // Third pass: clear cascade from belongsTo entries (in SpecVerse vocabulary,
+    // cascade is a property of the parent→child edge, not the child→parent FK
+    // edge). The flag has already been propagated to hasMany above.
+    for (const r of relationships) {
+        if (r.type === 'belongsTo')
+            r.cascade = false;
+    }
+    return { entities, relationships, enums, schemaFiles };
+}
+// ────────────────────────────────────────────────────────────────────
+// Prisma-syntax parsers (regex-based; sufficient for schema.prisma)
+// ────────────────────────────────────────────────────────────────────
+function parseFields(modelBody) {
+    const out = [];
+    for (const rawLine of modelBody.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('//') || line.startsWith('@@'))
+            continue;
+        // A field line: `name Type[?] [modifiers...]`
+        // Skip relation-only lines (they have @relation annotation typically on a separate line — handled below)
+        const match = line.match(/^(\w+)\s+(\w+(?:\[\])?(?:\?)?)\s*(.*)$/);
+        if (!match)
+            continue;
+        const [, name, fullType, rest] = match;
+        const isList = fullType.endsWith('[]');
+        const isOptional = fullType.endsWith('?');
+        const baseType = fullType.replace(/\[\]/, '').replace(/\?$/, '');
+        out.push({
+            name,
+            type: fullType,
+            required: !isOptional && !isList, // List fields are intrinsically optional in Prisma semantics
+            unique: /@unique\b/.test(rest),
+            default: extractDefault(rest),
+            isId: /@id\b/.test(rest),
+            isList,
+        });
+        // Use baseType here to detect what we're actually pointing at — it's a hint for callers
+        void baseType;
+    }
+    return out;
+}
+function extractDefault(rest) {
+    const match = rest.match(/@default\(([^)]+)\)/);
+    return match ? match[1].trim() : undefined;
+}
+/**
+ * Detect `belongsTo` relationships declared via `@relation(fields: [...], references: [...])`.
+ * The model containing such a declaration owns the foreign key — it `belongsTo` the target.
+ */
+function parseRelationships(modelName, modelBody, fields) {
+    const out = [];
+    // Match: `field TargetType[?] @relation(fields: [...], references: [...], onDelete: Cascade)`
+    const relationRegex = /^\s*(\w+)\s+(\w+)(\?)?\s+@relation\(([^)]+)\)/gm;
+    for (const match of modelBody.matchAll(relationRegex)) {
+        const [, fieldName, targetType] = match;
+        const annotation = match[4];
+        // It's a belongsTo — the field's type is the target model
+        const cascade = /onDelete:\s*Cascade/.test(annotation);
+        // Skip self-referential or array-typed entries (those are hasMany, not belongsTo)
+        const f = fields.find((x) => x.name === fieldName);
+        if (f?.isList)
+            continue;
+        out.push({
+            fromModel: modelName,
+            toModel: targetType,
+            type: 'belongsTo',
+            cascade,
+            fieldName,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=typescript-prisma.js.map

package/dist/analyse-prepass/adapters/typescript-prisma.js.map

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

package/dist/analyse-prepass/backends/codegraph.d.ts

@@ -0,0 +1,56 @@
+import type { StructuralPrepass, Symbol, Import, FileFilter, ClassFilter, MethodFilter, InterfaceFilter, IndexResult, MethodFactSheet } from '../interface.js';
+export interface CodeGraphBackendOptions {
+    /** Path to the codegraph binary. Auto-detected if omitted. */
+    codegraphPath?: string;
+    /** Path to the sqlite3 binary. Auto-detected if omitted. */
+    sqlite3Path?: string;
+    /** Skip running `codegraph init` + `codegraph index` if .codegraph/ already exists. */
+    reuseExistingIndex?: boolean;
+}
+export declare class CodeGraphBackend implements StructuralPrepass {
+    private sourceDir;
+    private dbPath;
+    private codegraphPath;
+    private sqlite3Path;
+    private reuseExistingIndex;
+    capabilities: {
+        callGraph: boolean;
+        crossFileResolution: boolean;
+        componentClustering: boolean;
+        fullTextSearch: boolean;
+        fileWatching: boolean;
+    };
+    constructor(options?: CodeGraphBackendOptions);
+    /**
+     * Check if CodeGraph + sqlite3 are available. Use this from the adapter
+     * selector to decide whether to fall back to grep-only.
+     */
+    static isAvailable(): boolean;
+    init(sourceDir: string): Promise<void>;
+    index(): Promise<IndexResult>;
+    listFiles(filter?: FileFilter): Promise<string[]>;
+    listClasses(filter?: ClassFilter): Promise<Symbol[]>;
+    listMethods(filter?: MethodFilter): Promise<Symbol[]>;
+    listInterfaces(filter?: InterfaceFilter): Promise<Symbol[]>;
+    listImports(file: string): Promise<Import[]>;
+    fileSourceText(file: string): Promise<string>;
+    callers(symbol: string): Promise<Symbol[]>;
+    callees(symbol: string): Promise<Symbol[]>;
+    /**
+     * Per-method fact sheet via SQL (for the call graph) + regex over the body
+     * (for everything else: emits, dbWrites, externalCalls, throws, async, branches).
+     *
+     * The SQL piece is what justifies the CodeGraph backend over grep-only here —
+     * tree-sitter resolved cross-file calls deterministically, while a regex over
+     * a single method body would only see same-file references.
+     */
+    getMethodDetails(qualifiedName: string): Promise<MethodFactSheet | null>;
+    /** Run a SQL query; expect 0 or 1 row. Throws if more. */
+    private queryOne;
+    /** Run a SQL query; return all rows as objects (parsed from JSON). */
+    private queryAll;
+    private rowToSymbol;
+    private escape;
+    private detectBinary;
+}
+//# sourceMappingURL=codegraph.d.ts.map

package/dist/analyse-prepass/backends/codegraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegraph.d.ts","sourceRoot":"","sources":["../../../src/analyse-prepass/backends/codegraph.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EACV,iBAAiB,EACjB,MAAM,EACN,MAAM,EACN,UAAU,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,WAAW,EACX,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAyCzB,MAAM,WAAW,uBAAuB;IACtC,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,qBAAa,gBAAiB,YAAW,iBAAiB;IACxD,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,kBAAkB,CAAU;IAEpC,YAAY;;;;;;MAMV;gBAEU,OAAO,GAAE,uBAA4B;IAMjD;;;OAGG;IACH,MAAM,CAAC,WAAW,IAAI,OAAO;IAUvB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBtC,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;IAsB7B,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAcjD,WAAW,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAUpD,WAAW,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAcrD,cAAc,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAU3D,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAc5C,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI7C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAW1C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAWhD;;;;;;;OAOG;IACG,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAgD9E,0DAA0D;IAC1D,OAAO,CAAC,QAAQ;IAMhB,sEAAsE;IACtE,OAAO,CAAC,QAAQ;IAchB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,MAAM;IAKd,OAAO,CAAC,YAAY;CASrB"}

package/dist/analyse-prepass/backends/codegraph.js

@@ -0,0 +1,303 @@
+/**
+ * CodeGraph backend — `StructuralPrepass` against `@colbymchenry/codegraph`.
+ *
+ * Uses CodeGraph's CLI for init/index, and queries its SQLite directly via
+ * the `sqlite3` command-line tool (preinstalled on macOS / Linux / Windows).
+ * Falls back to grep-only style scanning if CodeGraph isn't installed.
+ *
+ * Design rationale: CodeGraph ships a tree-sitter-based indexer for 19+
+ * languages with cross-file resolution + call-graph + FTS, all stored in
+ * SQLite. We get tree-sitter coverage for free; we just translate its
+ * vocabulary (class / method / function / interface) into our SpecVerse
+ * vocabulary downstream in the adapter layer.
+ *
+ * Relies on:
+ *   - `codegraph` CLI on PATH (or installable via `npm i -g @colbymchenry/codegraph`)
+ *   - `sqlite3` CLI on PATH (preinstalled on most Unix systems)
+ */
+import { execSync, execFileSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { walkSourceTree, detectLanguage, globToRegex } from './walk.js';
+import { extractEmits, extractDbWrites, extractExternalCalls, extractThrows, extractAsyncBoundaries, countBranchPoints, sliceBody, } from './method-patterns.js';
+/** Map CodeGraph's `nodes.kind` enum to our Symbol['kind']. */
+function mapKind(cgKind) {
+    switch (cgKind) {
+        case 'class': return 'class';
+        case 'function': return 'function';
+        case 'method': return 'method';
+        case 'interface': return 'interface';
+        case 'type_alias': return 'type_alias';
+        case 'constant': return 'constant';
+        // CodeGraph doesn't always emit 'enum' as a separate kind; treat as type_alias
+        default: return null;
+    }
+}
+export class CodeGraphBackend {
+    sourceDir = '';
+    dbPath = '';
+    codegraphPath;
+    sqlite3Path;
+    reuseExistingIndex;
+    capabilities = {
+        callGraph: true,
+        crossFileResolution: true,
+        componentClustering: false, // CodeGraph doesn't have Leiden
+        fullTextSearch: true, // FTS5 in SQLite
+        fileWatching: true, // OS file watchers + 2s debounce
+    };
+    constructor(options = {}) {
+        this.codegraphPath = options.codegraphPath ?? this.detectBinary('codegraph');
+        this.sqlite3Path = options.sqlite3Path ?? this.detectBinary('sqlite3');
+        this.reuseExistingIndex = options.reuseExistingIndex ?? false;
+    }
+    /**
+     * Check if CodeGraph + sqlite3 are available. Use this from the adapter
+     * selector to decide whether to fall back to grep-only.
+     */
+    static isAvailable() {
+        try {
+            execSync('codegraph --version', { stdio: 'ignore', timeout: 5000 });
+            execSync('sqlite3 --version', { stdio: 'ignore', timeout: 5000 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async init(sourceDir) {
+        this.sourceDir = sourceDir;
+        this.dbPath = join(sourceDir, '.codegraph', 'codegraph.db');
+        if (this.reuseExistingIndex && existsSync(this.dbPath))
+            return;
+        // CodeGraph's `init` is interactive (asks about Claude integration);
+        // we feed "n" via stdin to skip the interactive setup.
+        if (!existsSync(join(sourceDir, '.codegraph'))) {
+            execSync(`echo "n" | ${this.codegraphPath} init`, {
+                cwd: sourceDir,
+                stdio: 'ignore',
+                timeout: 30_000,
+            });
+        }
+    }
+    async index() {
+        const start = Date.now();
+        if (this.reuseExistingIndex && existsSync(this.dbPath)) {
+            // Trust existing index. Stats from DB.
+            const stats = this.queryOne(`SELECT (SELECT COUNT(*) FROM nodes WHERE kind='file') AS files,
+                (SELECT COUNT(*) FROM nodes WHERE kind != 'file') AS symbols`);
+            return { ...stats, durationMs: Date.now() - start };
+        }
+        execSync(`${this.codegraphPath} index`, {
+            cwd: this.sourceDir,
+            stdio: 'ignore',
+            timeout: 600_000, // 10 min for large repos
+        });
+        const stats = this.queryOne(`SELECT (SELECT COUNT(*) FROM nodes WHERE kind='file') AS files,
+              (SELECT COUNT(*) FROM nodes WHERE kind != 'file') AS symbols`);
+        return { ...stats, durationMs: Date.now() - start };
+    }
+    async listFiles(filter) {
+        // listFiles uses an FS walk (not the index) because adapters need to find
+        // arbitrary file types (schema.prisma, package.json, config files) — and
+        // CodeGraph only indexes its 19 supported languages, missing those.
+        let result = walkSourceTree(this.sourceDir);
+        if (filter?.dir)
+            result = result.filter((f) => f.startsWith(filter.dir));
+        if (filter?.lang)
+            result = result.filter((f) => detectLanguage(f) === filter.lang);
+        if (filter?.glob) {
+            const globRegex = globToRegex(filter.glob);
+            result = result.filter((f) => globRegex.test(f));
+        }
+        return result;
+    }
+    async listClasses(filter) {
+        let sql = `SELECT * FROM nodes WHERE kind='class'`;
+        if (filter?.dir)
+            sql += ` AND file_path LIKE '${this.escape(filter.dir)}%'`;
+        sql += ` ORDER BY file_path, start_line`;
+        const rows = this.queryAll(sql);
+        return rows
+            .filter((r) => !filter?.namePattern || filter.namePattern.test(r.name))
+            .map((r) => this.rowToSymbol(r));
+    }
+    async listMethods(filter) {
+        let sql = `SELECT * FROM nodes WHERE kind='method'`;
+        const conditions = [];
+        if (filter?.class)
+            conditions.push(`qualified_name LIKE '${this.escape(filter.class)}%'`);
+        if (filter?.nameIn && filter.nameIn.length > 0) {
+            const list = filter.nameIn.map((n) => `'${this.escape(n)}'`).join(',');
+            conditions.push(`name IN (${list})`);
+        }
+        if (conditions.length)
+            sql += ` AND ${conditions.join(' AND ')}`;
+        sql += ` ORDER BY file_path, start_line`;
+        const rows = this.queryAll(sql);
+        return rows.map((r) => this.rowToSymbol(r));
+    }
+    async listInterfaces(filter) {
+        let sql = `SELECT * FROM nodes WHERE kind='interface'`;
+        if (filter?.dir)
+            sql += ` AND file_path LIKE '${this.escape(filter.dir)}%'`;
+        sql += ` ORDER BY file_path, start_line`;
+        const rows = this.queryAll(sql);
+        return rows
+            .filter((r) => !filter?.namePattern || filter.namePattern.test(r.name))
+            .map((r) => this.rowToSymbol(r));
+    }
+    async listImports(file) {
+        // CodeGraph stores imports as nodes of kind='import' with edges to the imported module.
+        // For v1, we do a simplified query: get all import nodes in this file.
+        const rel = file.startsWith(this.sourceDir) ? file.slice(this.sourceDir.length).replace(/^\//, '') : file;
+        const sql = `SELECT name, qualified_name FROM nodes WHERE kind='import' AND file_path='${this.escape(rel)}'`;
+        const rows = this.queryAll(sql);
+        return rows.map((r) => ({
+            fromFile: file,
+            // qualified_name may encode the module path; name encodes the imported symbol
+            toModule: r.qualified_name.includes(':') ? r.qualified_name.split(':')[0] : r.qualified_name,
+            symbols: [r.name],
+        }));
+    }
+    async fileSourceText(file) {
+        return readFileSync(file, 'utf8');
+    }
+    async callers(symbol) {
+        const sql = `
+      SELECT n.* FROM edges e
+      JOIN nodes n ON e.from_id = n.id
+      WHERE e.to_id = (SELECT id FROM nodes WHERE qualified_name='${this.escape(symbol)}' LIMIT 1)
+        AND e.kind='call'
+    `;
+        const rows = this.queryAll(sql);
+        return rows.map((r) => this.rowToSymbol(r));
+    }
+    async callees(symbol) {
+        const sql = `
+      SELECT n.* FROM edges e
+      JOIN nodes n ON e.to_id = n.id
+      WHERE e.from_id = (SELECT id FROM nodes WHERE qualified_name='${this.escape(symbol)}' LIMIT 1)
+        AND e.kind='call'
+    `;
+        const rows = this.queryAll(sql);
+        return rows.map((r) => this.rowToSymbol(r));
+    }
+    /**
+     * Per-method fact sheet via SQL (for the call graph) + regex over the body
+     * (for everything else: emits, dbWrites, externalCalls, throws, async, branches).
+     *
+     * The SQL piece is what justifies the CodeGraph backend over grep-only here —
+     * tree-sitter resolved cross-file calls deterministically, while a regex over
+     * a single method body would only see same-file references.
+     */
+    async getMethodDetails(qualifiedName) {
+        const methodSql = `
+      SELECT * FROM nodes
+      WHERE qualified_name='${this.escape(qualifiedName)}'
+        AND kind='method'
+      LIMIT 1
+    `;
+        const rows = this.queryAll(methodSql);
+        if (rows.length === 0)
+            return null;
+        const methodRow = rows[0];
+        // Resolve absolute file path (consistent with rowToSymbol)
+        const filePath = methodRow.file_path.startsWith('/')
+            ? methodRow.file_path
+            : join(this.sourceDir, methodRow.file_path);
+        // Read the body — extract via brace-depth scan over the source file
+        const fileText = readFileSync(filePath, 'utf8');
+        const fileLines = fileText.split('\n');
+        const bodyLines = fileLines.slice(methodRow.start_line - 1, methodRow.end_line);
+        const body = bodyLines.join('\n');
+        // Calls — use the call graph (CodeGraph's strength)
+        const calls = await this.callees(qualifiedName);
+        return {
+            qualifiedName,
+            signature: methodRow.signature ?? '',
+            body,
+            filePath,
+            startLine: methodRow.start_line,
+            endLine: methodRow.end_line,
+            language: methodRow.language,
+            calls,
+            emits: extractEmits(body),
+            dbWrites: extractDbWrites(body),
+            externalCalls: extractExternalCalls(body),
+            throws: extractThrows(body),
+            asyncBoundaries: extractAsyncBoundaries(body),
+            branchPoints: countBranchPoints(body),
+            bodyTextSliced: sliceBody(body),
+        };
+    }
+    // ────────────────────────────────────────────────────────────────────
+    // Internals
+    // ────────────────────────────────────────────────────────────────────
+    /** Run a SQL query; expect 0 or 1 row. Throws if more. */
+    queryOne(sql) {
+        const rows = this.queryAll(sql);
+        if (rows.length === 0)
+            return {};
+        return rows[0];
+    }
+    /** Run a SQL query; return all rows as objects (parsed from JSON). */
+    queryAll(sql) {
+        const stdout = execFileSync(this.sqlite3Path, ['-json', this.dbPath, sql], {
+            encoding: 'utf8',
+            timeout: 30_000,
+            maxBuffer: 50 * 1024 * 1024, // 50MB — large repos can produce big result sets
+        });
+        if (!stdout.trim())
+            return [];
+        try {
+            return JSON.parse(stdout);
+        }
+        catch (err) {
+            throw new Error(`CodeGraph backend: failed to parse sqlite3 -json output: ${err}\n--- stdout ---\n${stdout.slice(0, 500)}`);
+        }
+    }
+    rowToSymbol(row) {
+        let decorators;
+        if (row.decorators) {
+            try {
+                decorators = JSON.parse(row.decorators);
+            }
+            catch {
+                // Ignore malformed decorator JSON
+            }
+        }
+        const filePath = row.file_path.startsWith('/')
+            ? row.file_path
+            : join(this.sourceDir, row.file_path);
+        return {
+            kind: mapKind(row.kind) ?? 'function',
+            name: row.name,
+            qualifiedName: row.qualified_name,
+            filePath,
+            startLine: row.start_line,
+            endLine: row.end_line,
+            signature: row.signature ?? undefined,
+            docstring: row.docstring ?? undefined,
+            isExported: !!row.is_exported,
+            decorators,
+            language: row.language,
+        };
+    }
+    escape(s) {
+        // Single-quote escaping for SQL string literals.
+        return s.replace(/'/g, "''");
+    }
+    detectBinary(name) {
+        try {
+            const path = execSync(`which ${name}`, { encoding: 'utf8', timeout: 3000 }).trim();
+            if (path)
+                return path;
+        }
+        catch {
+            // Fall through
+        }
+        return name; // Hope it's on PATH
+    }
+}
+//# sourceMappingURL=codegraph.js.map