brainclaw 1.9.0 → 1.10.0

package/dist/core/code-map/backend.js

@@ -0,0 +1,123 @@
+/**
+ * CodeQueryBackend — the agent-facing query contract (spec §8).
+ *
+ * Introduced in P0 so a future Memgraph (or other) backend can be added without
+ * changing the agent-facing APIs. P0 ships exactly one implementation:
+ * `JsonlBackend`. In this sprint, `status()` and `refresh()` are minimally real
+ * (they read/init the durable store and report freshness); `find()`/`brief()`
+ * return not-yet-implemented placeholders that still carry a real
+ * `freshness_badge`, locking the response shape for later sprints.
+ */
+import path from 'node:path';
+import { readManifest, storeExists } from './store.js';
+import { refresh as runRefresh } from './refresh.js';
+import { brief as runBrief, find as runFind } from './query.js';
+import { defaultMemoryReader } from './memory-reader.js';
+/** spec §9 caps the brief reading list at 12 files. */
+export const BRIEF_FILE_CAP = 12;
+function badge(status, details = {}) {
+    return { status, details };
+}
+/**
+ * P0 JSONL-backed query backend. Reads the durable file store (manifest +
+ * shards + indexes); no graph DB. find()/brief() are stubbed for Sprint 1.
+ */
+export class JsonlBackend {
+    /**
+     * Related-memory read seam (spec §11). Defaults to the canonical entity read
+     * path; tests inject an in-memory reader to assert attachment without a store.
+     */
+    memoryReader;
+    constructor(opts = {}) {
+        this.memoryReader = opts.memoryReader ?? defaultMemoryReader;
+    }
+    async status(input) {
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        if (!manifest) {
+            return {
+                store_exists: storeExists(input.cwd, input.preferredDirName),
+                freshness_badge: badge('missing_index'),
+                stats: null,
+            };
+        }
+        return {
+            store_exists: true,
+            freshness_badge: badge(manifest.freshness.status, {
+                stale_file_count: manifest.freshness.stale_file_count,
+                partial_reason: manifest.freshness.partial_reason,
+            }),
+            stats: {
+                files_indexed: manifest.stats.files_indexed,
+                nodes: manifest.stats.nodes,
+                edges: manifest.stats.edges,
+            },
+        };
+    }
+    /**
+     * Real refresh (spec §7): resolves project identity (input -> manifest ->
+     * cwd-derived default), then runs the Tree-sitter parse + index + materialize
+     * pipeline behind the project lock. A live competing lock fails fast with a
+     * clear status — refresh never blocks bclaw_work (rule 8).
+     */
+    async refresh(input) {
+        const scope = input.scope ?? 'changed';
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const projectRoot = input.projectRoot ?? manifest?.project_root ?? input.cwd ?? process.cwd();
+        const projectId = input.projectId ?? manifest?.project_id ?? `prj_${path.basename(path.resolve(projectRoot))}`;
+        const result = await runRefresh({
+            projectId,
+            projectRoot,
+            scope,
+            cwd: input.cwd,
+            preferredDirName: input.preferredDirName,
+            ownerAgent: input.ownerAgent ?? null,
+            ownerAgentId: input.ownerAgentId ?? null,
+        });
+        return {
+            ran: result.ran,
+            scope,
+            lock_acquired: result.lock_acquired,
+            freshness_badge: badge(result.freshness.status, {
+                stale_file_count: result.freshness.stale_file_count,
+                partial_reason: result.freshness.partial_reason,
+                files_parsed: result.files_parsed,
+                files_compacted: result.files_compacted,
+                duration_ms: result.duration_ms,
+            }),
+            ...(result.lock_status ? { lock_status: result.lock_status } : {}),
+        };
+    }
+    /**
+     * Agent-facing symbol search (spec §12.1). Ranks symbols-index matches and
+     * lazily validates each backing shard against the live file before serving it
+     * as confident (§6.1); the response badge reflects any detected drift.
+     */
+    async find(input) {
+        const ctx = this.queryContext(input);
+        const out = runFind(input.query, input.limit, ctx);
+        return {
+            query: out.query,
+            matches: out.matches,
+            freshness_badge: { status: out.freshness_badge.status, details: out.freshness_badge.details },
+        };
+    }
+    /**
+     * Agent-facing reading list (spec §9, §11). Produces a ranked
+     * suggested_files_to_read (cap 12), attaches related brainclaw memory (cap 5),
+     * and carries a §6.1 lazy-validated freshness badge.
+     */
+    async brief(input) {
+        const ctx = this.queryContext(input);
+        const out = runBrief(input.target, input.limit, ctx, this.memoryReader);
+        return {
+            target: out.target,
+            suggested_files_to_read: out.suggested_files_to_read,
+            related_memory: out.related_memory,
+            freshness_badge: { status: out.freshness_badge.status, details: out.freshness_badge.details },
+        };
+    }
+    queryContext(input) {
+        return { cwd: input.cwd, preferredDirName: input.preferredDirName };
+    }
+}
+//# sourceMappingURL=backend.js.map

package/dist/core/code-map/core.js

@@ -0,0 +1,81 @@
+import { finalize } from './finalizer.js';
+import { defaultRegistry } from './lang/providers.js';
+/**
+ * The default registry is constructed + registered in `lang/providers.ts` (P1b
+ * §3.2) — the declared extension point for "which providers ship by default".
+ * Re-exported here so existing importers (`core.js`) keep working unchanged.
+ */
+export { defaultRegistry };
+const SERVICES = { version: '0.1.0' };
+function fileOnlyResult(input, parseStatus) {
+    // Reuse the finalizer over an empty draft so the file node id matches exactly.
+    return finalize({
+        file: { path: input.path },
+        definitions: [],
+        imports: [],
+        exports: [],
+        tests: [],
+        facts: [{ code: 'skipped_unsupported', message: `no provider for ${input.path}` }],
+        attributes: { parseStatus },
+    }, input);
+}
+/** Delete the retained parse tree (best-effort). */
+function releaseTree(draft) {
+    const tree = draft.attributes?.__tree;
+    if (tree) {
+        try {
+            tree.delete();
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+/**
+ * Extract a single file via the provider pipeline. Signature-compatible with the
+ * legacy `extractor.ts:extractFile`. Resolves the provider by path; an unsupported
+ * extension yields a `skipped_unsupported` file-only result (never throws).
+ */
+export async function extractFile(input, registry = defaultRegistry) {
+    const resolved = registry.providerForPath(input.path);
+    if (!resolved) {
+        return fileOnlyResult(input, 'skipped_unsupported');
+    }
+    const { provider, lang } = resolved;
+    // The caller's `input.lang` is authoritative for identity (it matches what the
+    // refresh pipeline resolved + what the oracle froze). We pass it through; the
+    // resolved `lang` is used only as a cross-check / for providers that re-resolve.
+    const providerInput = {
+        projectId: input.projectId,
+        path: input.path,
+        lang: input.lang,
+        source: input.source,
+        sizeBytes: input.sizeBytes,
+        maxParseFileBytes: input.maxParseFileBytes,
+        maxQueryWaitMs: input.maxQueryWaitMs,
+    };
+    void lang;
+    let draft = await provider.extractDraft(providerInput, SERVICES);
+    if (provider.refine) {
+        try {
+            draft = await provider.refine(draft, { input: providerInput, lang: input.lang });
+        }
+        catch (err) {
+            // Fall back to the pre-refine draft + a loud diagnostic (never drop the file).
+            draft = {
+                ...draft,
+                facts: [
+                    ...draft.facts,
+                    { code: 'refine_error', message: err instanceof Error ? err.message : String(err) },
+                ],
+            };
+        }
+    }
+    try {
+        return finalize(draft, input);
+    }
+    finally {
+        releaseTree(draft);
+    }
+}
+//# sourceMappingURL=core.js.map

package/dist/core/code-map/drafts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=drafts.js.map

package/dist/core/code-map/extractor.js

@@ -0,0 +1,29 @@
+/**
+ * Code Map extractor — THIN backward-compat surface (spec §3, §9 cutover).
+ *
+ * P1a cutover (Sprint 4): the legacy 540-line imperative extractor has been
+ * replaced by the query-driven provider pipeline. The real `extractFile` now
+ * lives on the CORE (`core.ts` → registry → provider.extractDraft → refine →
+ * finalize). This module keeps the historical import surface stable:
+ *
+ *  - `extractFile`            re-exported from `core.ts` (provider pipeline).
+ *  - `ExtractInput` / `ExtractResult`  the public extraction shapes (owned here so
+ *                            `core.ts`, `finalizer.ts`, and the oracle tests keep
+ *                            importing them from this module).
+ *  - `hashContent`           sha256 of file contents (used by refresh.ts + query.ts).
+ *
+ * The legacy imperative bodies (handleFunctionDeclaration / handleClassDeclaration
+ * / classifySubtype / returnsJsx / handleImport / markOrAddExport / …) are GONE.
+ * The oracle (`oracle.test.ts`) now exercises this re-export and so doubles as a
+ * provider-path regression guard against the frozen `oracle-golden.json`.
+ */
+import crypto from 'node:crypto';
+// The query-driven CORE entrypoint, re-exported under the historical name so all
+// existing importers (refresh.ts, oracle.test.ts, …) keep resolving `extractFile`
+// here. core.ts imports the types above (type-only → erased, so no runtime cycle).
+export { extractFile } from './core.js';
+/** sha256 of file contents (file_hash on the shard). */
+export function hashContent(source) {
+    return `sha256:${crypto.createHash('sha256').update(source, 'utf-8').digest('hex')}`;
+}
+//# sourceMappingURL=extractor.js.map

package/dist/core/code-map/finalizer.js

@@ -0,0 +1,191 @@
+/**
+ * Code Map P1a — CORE finalizer (spec §3, §6; dec#108 #1, dec#109 P0 #4 / P1 #5/#6/#7).
+ *
+ * The finalizer is the ONE AND ONLY identity authority. Providers hand it typed,
+ * id-free {@link ExtractionDraft}s; this module reproduces TODAY'S exact legacy
+ * `extractor.ts` output: byte-identical node/edge IDs (via `ids.ts`), spans,
+ * confidence, the `exported` flag, and — critically — the LEGACY SOURCE-APPEND
+ * ORDER. Nothing here sorts node/edge content: draft items carry an `ordinal`
+ * (their traversal position) and the finalizer replays them in that order.
+ *
+ * Emission contract (mirrors the legacy `addSymbol` / `addModule` / `markOrAddExport`):
+ *  - File node FIRST.
+ *  - Per definition (ascending ordinal): symbol node, `contains` edge, `defines` edge.
+ *  - Per import / re-export source: `module` node, `imports` edge.
+ *  - Per export clause / default-id (`markOrAddExport`): if the name matches an
+ *    already-emitted symbol, set that node `exported=true` + emit ONE `exports`
+ *    edge to it (no new node); otherwise fabricate an `export`-subtype symbol
+ *    (node + `contains` + `defines`) then emit the `exports` edge to it.
+ *
+ * The `exported` FLAG is NOT an `exports` EDGE: in-place exported declarations set
+ * only `node.exported=true`; only export clauses / default-identifier exports emit
+ * an `exports` edge (and they ALSO flip the referenced node's flag, matching legacy).
+ *
+ * Output nodes/edges are validated against the `types.ts` zod schemas before return.
+ */
+import { edgeId, fileNodeId, nodeId } from './ids.js';
+import { EdgeSchema, NodeSchema } from './types.js';
+/** Compute the legacy `sym:<hash>` node id (mirrors `extractor.ts:symId`). */
+function symNodeId(projectId, path, lang, subtype, name, span) {
+    return `sym:${nodeId({
+        projectId,
+        path,
+        lang,
+        kind: 'symbol',
+        subtype,
+        name,
+        startLine: span.start_line,
+        startCol: span.start_col,
+    })}`;
+}
+/** Compute the legacy `module:<hash>` node id (mirrors `extractor.ts:addModule`). */
+function moduleNodeId(projectId, path, lang, source, span) {
+    return `module:${nodeId({
+        projectId,
+        path,
+        lang,
+        kind: 'module',
+        subtype: null,
+        name: source,
+        startLine: span.start_line,
+        startCol: span.start_col,
+    })}`;
+}
+/**
+ * Turn a provider draft into the final {@link ExtractResult}. The ONLY identity
+ * authority — reproduces the legacy extractor output exactly (see file header).
+ *
+ * `input` supplies `projectId`/`path`/`lang` (the id inputs). `parseStatus`
+ * defaults to `'parsed'`; provider diagnostics ride on `draft.facts`.
+ */
+export function finalize(draft, input) {
+    const { projectId, path, lang } = input;
+    const fileNode = fileNodeId(projectId, path, lang);
+    const nodes = [
+        {
+            id: fileNode,
+            kind: 'file',
+            subtype: null,
+            lang,
+            name: path,
+            path,
+            span: null,
+            exported: false,
+            confidence: 1.0,
+            related_memory_ids: [],
+            imported_names: [],
+        },
+    ];
+    const edges = [];
+    // symbol name -> node id, mirroring the legacy `ctx.byName` (used by export
+    // clauses to mark-or-add). Last writer per name wins, exactly like legacy.
+    const byName = new Map();
+    // node id -> index in `nodes`, so an export clause can flip `exported` in place.
+    const nodeIndexById = new Map();
+    const pushSymbol = (subtype, name, span, exported, confidence) => {
+        const id = symNodeId(projectId, path, lang, subtype, name, span);
+        nodeIndexById.set(id, nodes.length);
+        nodes.push({
+            id,
+            kind: 'symbol',
+            subtype,
+            lang,
+            name,
+            path,
+            span,
+            exported,
+            confidence,
+            related_memory_ids: [],
+            imported_names: [],
+        });
+        byName.set(name, id);
+        edges.push({
+            id: edgeId({ projectId, from: fileNode, to: id, kind: 'contains' }),
+            from: fileNode,
+            to: id,
+            kind: 'contains',
+            confidence: 1.0,
+            source: { path, line: span.start_line },
+        });
+        edges.push({
+            id: edgeId({ projectId, from: fileNode, to: id, kind: 'defines' }),
+            from: fileNode,
+            to: id,
+            kind: 'defines',
+            confidence: 1.0,
+            source: { path, line: span.start_line },
+        });
+        return id;
+    };
+    // Build a single ordinal-ordered stream across all draft kinds so the finalizer
+    // replays the legacy source-append order without ever sorting node/edge content.
+    const items = [
+        ...draft.definitions.map((ref) => ({ kind: 'def', ordinal: ref.ordinal, ref })),
+        ...draft.imports.map((ref) => ({ kind: 'import', ordinal: ref.ordinal, ref })),
+        ...draft.exports.map((ref) => ({ kind: 'export', ordinal: ref.ordinal, ref })),
+    ].sort((a, b) => a.ordinal - b.ordinal);
+    for (const item of items) {
+        if (item.kind === 'def') {
+            const d = item.ref;
+            pushSymbol(d.subtype, d.name, d.span, d.exported === true, d.confidence ?? 1.0);
+        }
+        else if (item.kind === 'import') {
+            const im = item.ref;
+            const id = moduleNodeId(projectId, path, lang, im.source, im.span);
+            nodeIndexById.set(id, nodes.length);
+            nodes.push({
+                id,
+                kind: 'module',
+                subtype: null,
+                lang,
+                name: im.source,
+                path,
+                span: im.span,
+                exported: false,
+                confidence: im.confidence ?? 1.0,
+                related_memory_ids: [],
+                imported_names: [...im.importedNames],
+            });
+            edges.push({
+                id: edgeId({ projectId, from: fileNode, to: id, kind: 'imports' }),
+                from: fileNode,
+                to: id,
+                kind: 'imports',
+                confidence: 1.0,
+                source: { path, line: im.span.start_line },
+            });
+        }
+        else {
+            // export clause / default-identifier — legacy `markOrAddExport`.
+            const ex = item.ref;
+            const existing = byName.get(ex.name);
+            let target;
+            if (existing) {
+                const idx = nodeIndexById.get(existing);
+                if (idx !== undefined)
+                    nodes[idx] = { ...nodes[idx], exported: true };
+                target = existing;
+            }
+            else {
+                target = pushSymbol('export', ex.name, ex.span, true, ex.confidence ?? 1.0);
+            }
+            edges.push({
+                id: edgeId({ projectId, from: fileNode, to: target, kind: 'exports' }),
+                from: fileNode,
+                to: target,
+                kind: 'exports',
+                confidence: 1.0,
+                source: { path, line: ex.span.start_line },
+            });
+        }
+    }
+    const parseStatus = draft.attributes?.parseStatus ?? 'parsed';
+    const diagnostics = draft.facts.map((f) => ({ ...f }));
+    // Validate the finalized output against the durable schemas (spec §6).
+    for (const n of nodes)
+        NodeSchema.parse(n);
+    for (const e of edges)
+        EdgeSchema.parse(e);
+    return { parseStatus, nodes, edges, diagnostics };
+}
+//# sourceMappingURL=finalizer.js.map

package/dist/core/code-map/freshness.js

@@ -0,0 +1,108 @@
+/**
+ * Write-side freshness hashing + per-shard freshness classification
+ * (spec §5.1, §6.2, §12.4).
+ *
+ * The READ-path lazy freshness check (§6.1) is Sprint 3 — NOT implemented here.
+ * This module owns only:
+ *  - `computeExtractorConfigHash` — sha256 of a stable serialization of
+ *    extractor_config + the active language set + (P1a) the registry's
+ *    `configHashInputs()` (provider versions + every query-asset hash). Changing
+ *    ignore rules, size caps, supported extensions, query budget, active langs, a
+ *    provider version, OR a tags/imports `.scm` => stale_extractor.
+ *    NOTE: grammar/engine hashes are deliberately NOT folded in (spec §6.2):
+ *    stale_grammar (changed parse binary) is kept separable from stale_extractor.
+ *  - `shardFreshnessStatus` — classify a stored shard against the current
+ *    extractor_config_hash + per-language grammar hashes.
+ */
+import crypto from 'node:crypto';
+/** Stable serialization: sort object keys recursively so hashing is order-independent. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`;
+}
+/**
+ * spec §5.1 / §9 — sha256 of (extractor_config + active language set + the
+ * registry's provider/query-asset fingerprint). The active language set is the
+ * sorted list of enabled languages, so enabling/disabling a language invalidates
+ * affected shards as stale_extractor. `registryInputs` (from
+ * `registry.configHashInputs()`) folds in provider `version` + every tags/imports
+ * `.scm` hash, so editing a query asset flips affected shards to stale_extractor
+ * (dec#109 P0#3). Optional + omitted-vs-undefined hash the same so legacy callers
+ * (config-only) keep a stable hash for that input combination.
+ */
+export function computeExtractorConfigHash(config, activeLanguages, registryInputs) {
+    const payload = {
+        extractor_config: config,
+        active_languages: [...activeLanguages].sort(),
+        registry: registryInputs ?? null,
+    };
+    return `sha256:${crypto.createHash('sha256').update(stableStringify(payload)).digest('hex')}`;
+}
+/**
+ * spec §12.4 — classify a stored shard:
+ *  - extractor_config_hash mismatch => stale_extractor
+ *  - tree_sitter_grammar_hash mismatch => stale_grammar
+ *  - otherwise fresh (content/path drift is the §6.1 read-path concern, Sprint 3)
+ *
+ * Precedence: extractor first, then grammar — both are "the binary/logic that
+ * produced this shard changed", and the badge only needs to surface one reason;
+ * extractor-config drift is the cheaper, more common cause.
+ */
+export function shardFreshnessStatus(input) {
+    const { shard } = input;
+    if (shard.extractor_config_hash !== input.currentExtractorConfigHash) {
+        return 'stale_extractor';
+    }
+    const expectedGrammar = input.grammarHashFor(shard.lang);
+    if (expectedGrammar !== undefined &&
+        shard.tree_sitter_grammar_hash != null &&
+        shard.tree_sitter_grammar_hash !== expectedGrammar) {
+        return 'stale_grammar';
+    }
+    return 'fresh';
+}
+/**
+ * Roll per-shard freshness up into a manifest-level freshness summary
+ * (spec §5.1). `missing_index` when nothing parsed; otherwise the dominant
+ * stale reason, else fresh.
+ */
+export function summarizeFreshness(shards) {
+    if (shards.length === 0) {
+        return { status: 'missing_index', stale_file_count: 0, partial_reason: null };
+    }
+    let staleExtractor = 0;
+    let staleGrammar = 0;
+    let staleChanged = 0;
+    for (const s of shards) {
+        switch (s.freshness.status) {
+            case 'stale_extractor':
+                staleExtractor++;
+                break;
+            case 'stale_grammar':
+                staleGrammar++;
+                break;
+            case 'stale_changed_files':
+                staleChanged++;
+                break;
+            default:
+                break;
+        }
+    }
+    const staleTotal = staleExtractor + staleGrammar + staleChanged;
+    if (staleTotal === 0) {
+        return { status: 'fresh', stale_file_count: 0, partial_reason: null };
+    }
+    // Surface the dominant reason for the manifest badge.
+    let status = 'stale_changed_files';
+    if (staleExtractor >= staleGrammar && staleExtractor >= staleChanged)
+        status = 'stale_extractor';
+    else if (staleGrammar >= staleChanged)
+        status = 'stale_grammar';
+    return { status, stale_file_count: staleTotal, partial_reason: null };
+}
+//# sourceMappingURL=freshness.js.map

package/dist/core/code-map/importable.js

@@ -0,0 +1,35 @@
+import { defaultImportableSymbol } from './lang/provider.js';
+/**
+ * Build `name -> importable symbol candidates` for one target file. `nodes` is the
+ * target shard's node list; only `kind: 'symbol'` nodes are considered, and the full
+ * symbol set is passed to the provider hook (Python needs it for top-level span
+ * containment).
+ */
+export function buildImportableIndex(nodes, provider) {
+    const symbols = nodes.filter((n) => n.kind === 'symbol');
+    const predicate = provider?.isImportableSymbol
+        ? (n) => provider.isImportableSymbol(n, symbols)
+        : defaultImportableSymbol;
+    const byName = new Map();
+    for (const n of symbols) {
+        if (!predicate(n))
+            continue;
+        const arr = byName.get(n.name);
+        if (arr)
+            arr.push(n);
+        else
+            byName.set(n.name, [n]);
+    }
+    return byName;
+}
+/**
+ * Resolve one imported name to its UNAMBIGUOUS importable symbol, or null when the
+ * name is absent OR matches more than one importable candidate (ambiguous → skip).
+ */
+export function lookupImportable(index, name) {
+    const cands = index.get(name);
+    if (!cands || cands.length !== 1)
+        return null;
+    return cands[0];
+}
+//# sourceMappingURL=importable.js.map