brainclaw 1.25.0 → 1.26.0

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

@@ -8,6 +8,7 @@
  */
 import path from 'node:path';
 import { fileId } from './ids.js';
+import { makeFreshnessBadge } from './freshness.js';
 import { readManifest, readResolutionIndex, readShard, readSymbolsIndex, } from './store.js';
 import { deriveBadge, isTestPath, makeLazyChecker, newAccumulator, validateStoreEntry, } from './query.js';
 /** Direct results and each optional transitive layer are independently bounded. */
@@ -100,12 +101,14 @@ function causeKey(cause) {
         cause.target.kind,
         cause.target.path,
         cause.target.node_id ?? '',
+        cause.caller?.node_id ?? '',
     ].join('\u0001');
 }
 function compareCause(a, b) {
     return a.kind.localeCompare(b.kind)
         || a.target.path.localeCompare(b.target.path)
         || (a.target.node_id ?? '').localeCompare(b.target.node_id ?? '')
+        || (a.caller?.node_id ?? '').localeCompare(b.caller?.node_id ?? '')
         || (a.module ?? '').localeCompare(b.module ?? '')
         || (a.source_line ?? -1) - (b.source_line ?? -1)
         || a.imported.join('\u0000').localeCompare(b.imported.join('\u0000'))
@@ -138,6 +141,33 @@ function addRelation(rows, entry, depth, target, kind) {
     current.causes.sort(compareCause);
     rows.set(entry.path, current);
 }
+function addUsageRelation(rows, entry, depth, target) {
+    const current = rows.get(entry.path) ?? {
+        path: entry.path,
+        file_id: entry.file_id,
+        depth,
+        causes: [],
+        causeKeys: new Set(),
+    };
+    current.depth = Math.min(current.depth, depth);
+    for (const reason of entry.reasons) {
+        const cause = {
+            kind: reason.kind,
+            imported: [],
+            confidence: reason.confidence,
+            ...(reason.source_line !== undefined ? { source_line: reason.source_line } : {}),
+            caller: { node_id: reason.caller_node_id },
+            target,
+        };
+        const key = causeKey(cause);
+        if (!current.causeKeys.has(key)) {
+            current.causeKeys.add(key);
+            current.causes.push(cause);
+        }
+    }
+    current.causes.sort(compareCause);
+    rows.set(entry.path, current);
+}
 function publicRelation(row) {
     return {
         path: row.path,
@@ -205,7 +235,7 @@ export function impact(target, options, ctx) {
         freshness_badge: freshness,
     });
     if (!symbolsIndex || !manifest) {
-        return empty({ status: 'missing_index', coarse: 'missing', details: { hint: 'run refresh' } });
+        return empty(makeFreshnessBadge('missing_index', { extra: { hint: 'run refresh' } }));
     }
     let matchKind = 'none';
     let rawDefinitions = [];
@@ -257,10 +287,12 @@ export function impact(target, options, ctx) {
     const directRows = new Map();
     if (resolution) {
         for (const definition of definitionByNodeId.values()) {
+            const target = { kind: 'symbol', path: definition.path, node_id: definition.node_id, name: definition.name };
             for (const dependent of resolution.dependents_by_symbol[definition.node_id] ?? []) {
-                addRelation(directRows, dependent, 1, {
-                    kind: 'symbol', path: definition.path, node_id: definition.node_id, name: definition.name,
-                }, 'imports_symbol');
+                addRelation(directRows, dependent, 1, target, 'imports_symbol');
+            }
+            for (const dependent of resolution.usages_by_symbol[definition.node_id] ?? []) {
+                addUsageRelation(directRows, dependent, 1, target);
             }
         }
         for (const definitionPath of definitionPaths) {

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

@@ -130,6 +130,29 @@ export function buildResolutionIndex(projectId, shards) {
     // target key -> (importer path -> merged entry)
     const byFile = new Map();
     const bySymbol = new Map();
+    const byUsageSymbol = new Map();
+    const addUsage = (targetSymbolId, importerPath, importerFileId, edge) => {
+        const perImporter = byUsageSymbol.get(targetSymbolId) ?? new Map();
+        const entry = perImporter.get(importerPath) ?? { path: importerPath, file_id: importerFileId, reasons: [] };
+        const reason = {
+            kind: edge.kind,
+            caller_node_id: edge.from,
+            confidence: edge.confidence,
+            ...(edge.source?.line !== undefined ? { source_line: edge.source.line } : {}),
+        };
+        if (!entry.reasons.some((existing) => existing.kind === reason.kind
+            && existing.caller_node_id === reason.caller_node_id
+            && existing.confidence === reason.confidence
+            && existing.source_line === reason.source_line)) {
+            entry.reasons.push(reason);
+            entry.reasons.sort((a, b) => a.kind.localeCompare(b.kind)
+                || a.caller_node_id.localeCompare(b.caller_node_id)
+                || (a.source_line ?? -1) - (b.source_line ?? -1)
+                || a.confidence - b.confidence);
+        }
+        perImporter.set(importerPath, entry);
+        byUsageSymbol.set(targetSymbolId, perImporter);
+    };
     const addDependent = (bucket, targetKey, importerPath, importerFileId, module, imported, confidence, kind, sourceLine) => {
         const perImporter = bucket.get(targetKey) ?? new Map();
         const prev = perImporter.get(importerPath);
@@ -189,6 +212,12 @@ export function buildResolutionIndex(projectId, shards) {
                 moduleById.set(n.id, { name: n.name, imported: n.imported_names ?? [] });
         }
         for (const e of shard.edges) {
+            if (e.kind === 'calls' || e.kind === 'references') {
+                // `possible_textual_match` remains deliberately absent: it is a hint on
+                // the shard, never an impact dependency.
+                addUsage(e.to, shard.path, shard.file_id, { ...e, kind: e.kind });
+                continue;
+            }
             if (e.kind !== 'resolves_to' && e.kind !== 'imports_symbol')
                 continue;
             const mod = moduleById.get(e.from);
@@ -210,12 +239,20 @@ export function buildResolutionIndex(projectId, shards) {
         }
         return out;
     };
+    const finalizeUsages = (bucket) => {
+        const out = Object.create(null);
+        for (const key of [...bucket.keys()].sort()) {
+            out[key] = [...bucket.get(key).values()].sort((a, b) => a.path.localeCompare(b.path));
+        }
+        return out;
+    };
     return {
         schema_version: CODE_MAP_SCHEMA_VERSION,
         project_id: projectId,
         updated_at: new Date().toISOString(),
         dependents_by_file: finalize(byFile),
         dependents_by_symbol: finalize(bySymbol),
+        usages_by_symbol: finalizeUsages(byUsageSymbol),
     };
 }
 //# sourceMappingURL=indexes.js.map

package/dist/core/code-map/lang/python/index.js

@@ -30,6 +30,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadGrammarWasm, grammarHashForWasm } from '../../wasm-loader.js';
 import { extractWithQueries } from '../query-runtime.js';
+import { extractLexicalUsages } from '../usages.js';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 /** The python grammar .wasm: dist basename + node_modules devDep fallback spec. */
 const PY_WASM_BASENAME = 'tree-sitter-python.wasm';
@@ -106,7 +107,7 @@ const queries = {
 };
 const vocabulary = {
     nodeSubtypes: ['function', 'method', 'class', 'variable', 'constant', 'property'],
-    edgeKinds: ['contains', 'defines', 'imports'],
+    edgeKinds: ['contains', 'defines', 'imports', 'calls', 'references', 'possible_textual_match'],
     captureMap: queries.captureMap,
 };
 const capabilities = {
@@ -284,7 +285,8 @@ export class PythonProvider {
             }
             return d;
         });
-        return { ...draft, definitions };
+        const tree = draft.attributes?.__tree;
+        return { ...draft, definitions, usages: extractLexicalUsages(tree?.rootNode, definitions, 'python') };
     }
     /**
      * P1c file-level import resolution (T3). Returns at most one resolution per import:

package/dist/core/code-map/lang/query-runtime.js

@@ -121,6 +121,7 @@ export async function extractWithQueries(input) {
         imports: [],
         exports: [],
         tests: [],
+        usages: [],
         facts,
         attributes: { parseStatus, __tree: tree },
     });
@@ -367,6 +368,7 @@ export async function extractWithQueries(input) {
         imports,
         exports,
         tests: [],
+        usages: [],
         facts,
         attributes: { parseStatus, __tree: tree },
     };

package/dist/core/code-map/lang/typescript/index.js

@@ -26,6 +26,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { grammarHash, grammarName, loadGrammar } from '../../wasm-loader.js';
 import { extractWithQueries } from '../query-runtime.js';
+import { extractLexicalUsages } from '../usages.js';
 import { isTypeScriptResolutionConfig, typeScriptSpecifierBases, } from './config.js';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 /** Resolve a vendored `.scm` next to this module (dist) or from the source tree. */
@@ -150,7 +151,7 @@ const queries = {
 };
 const vocabulary = {
     nodeSubtypes: ['function', 'class', 'type', 'interface', 'variable', 'component', 'hook', 'export'],
-    edgeKinds: ['contains', 'defines', 'imports', 'exports'],
+    edgeKinds: ['contains', 'defines', 'imports', 'exports', 'calls', 'references', 'possible_textual_match'],
     captureMap: queries.captureMap,
 };
 const capabilities = {
@@ -305,7 +306,8 @@ export class TypeScriptProvider {
             }
             return d;
         });
-        return { ...draft, definitions };
+        const tree = draft.attributes?.__tree;
+        return { ...draft, definitions, usages: extractLexicalUsages(tree?.rootNode, definitions, 'js-ts') };
     }
     /**
      * P1c file-level import resolution (intra-project, relative specifiers). Returns

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

@@ -0,0 +1,333 @@
+const FUNCTION_SUBTYPES = new Set(['function', 'component', 'hook']);
+const LOW_CONFIDENCE_TEXTUAL_MATCH = 0.2;
+function sourceOf(definition) {
+    const value = definition.sourceNode;
+    if (!value || typeof value !== 'object' || !('node' in value) || !('nameNode' in value))
+        return null;
+    const candidate = value;
+    return candidate.node && candidate.nameNode ? candidate : null;
+}
+function spanOf(node) {
+    return {
+        start_line: node.startPosition.row + 1,
+        start_col: node.startPosition.column + 1,
+        end_line: node.endPosition.row + 1,
+        end_col: node.endPosition.column + 1,
+    };
+}
+function nodeKey(node) {
+    return `${node.type}:${node.startIndex}:${node.endIndex}`;
+}
+function sameNode(a, b) {
+    return !!a && a.type === b.type && a.startIndex === b.startIndex && a.endIndex === b.endIndex;
+}
+function field(node, name) {
+    try {
+        return node.childForFieldName(name);
+    }
+    catch {
+        return null;
+    }
+}
+function walk(node, visit) {
+    visit(node);
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child)
+            walk(child, visit);
+    }
+}
+function walkScope(node, rootScope, language, visit) {
+    visit(node);
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (!child)
+            continue;
+        // Bindings in a nested function/class/lambda cannot shadow a use in this
+        // scope. Skipping them avoids false abstention between sibling functions.
+        if (child !== rootScope && isScope(child, language))
+            continue;
+        walkScope(child, rootScope, language, visit);
+    }
+}
+function hasAncestor(node, types) {
+    for (let parent = node.parent; parent; parent = parent.parent) {
+        if (types.has(parent.type))
+            return true;
+    }
+    return false;
+}
+function isTopLevelPythonFunction(definition) {
+    const source = sourceOf(definition);
+    if (!source)
+        return false;
+    let parent = source.node.parent;
+    if (parent?.type === 'decorated_definition')
+        parent = parent.parent;
+    return parent?.type === 'module';
+}
+function isLocalFunctionTarget(definition, language) {
+    if (!FUNCTION_SUBTYPES.has(definition.subtype))
+        return false;
+    // JS/TS tags are already program-anchored. Python captures nested functions too,
+    // so retain only module bindings: nested/method names need a real scope engine.
+    return language === 'js-ts' || isTopLevelPythonFunction(definition);
+}
+function isCallerDefinition(definition) {
+    return FUNCTION_SUBTYPES.has(definition.subtype);
+}
+function definitionRange(definition) {
+    const source = sourceOf(definition);
+    if (!source)
+        return null;
+    // A lexical declaration can carry several declarators. The declarator, not the
+    // shared statement span, is the smallest safe caller container for an arrow.
+    return source.nameNode.parent ?? source.node;
+}
+function contains(container, node) {
+    return container.startIndex <= node.startIndex && container.endIndex >= node.endIndex;
+}
+function callerFor(node, definitions) {
+    let winner;
+    for (const definition of definitions) {
+        if (!isCallerDefinition(definition))
+            continue;
+        const range = definitionRange(definition);
+        if (!range || !contains(range, node))
+            continue;
+        const width = range.endIndex - range.startIndex;
+        if (!winner || width < winner.width || (width === winner.width && definition.ordinal > winner.ordinal)) {
+            winner = { ordinal: definition.ordinal, width };
+        }
+    }
+    return winner?.ordinal;
+}
+function isScope(node, language) {
+    if (language === 'python')
+        return ['module', 'function_definition', 'lambda', 'class_definition'].includes(node.type);
+    return ['program', 'function_declaration', 'function_expression', 'arrow_function', 'method_definition'].includes(node.type);
+}
+function isParameterIdentifier(node, language) {
+    const parameterTypes = language === 'python'
+        ? new Set(['parameters', 'lambda_parameters'])
+        : new Set(['formal_parameters', 'required_parameter', 'optional_parameter', 'rest_pattern']);
+    return hasAncestor(node, parameterTypes);
+}
+function isBindingIdentifier(node, language) {
+    if (node.type !== 'identifier')
+        return false;
+    const parent = node.parent;
+    if (!parent)
+        return false;
+    if (sameNode(field(parent, 'name'), node) && [
+        'variable_declarator', 'function_declaration', 'generator_function_declaration',
+        'function_definition', 'class_declaration', 'class_definition', 'aliased_import',
+    ].includes(parent.type))
+        return true;
+    if (sameNode(field(parent, 'left'), node) && [
+        'assignment', 'augmented_assignment', 'for_statement', 'with_item',
+    ].includes(parent.type))
+        return true;
+    return isParameterIdentifier(node, language);
+}
+function scopeBinds(scope, name, language, allowed) {
+    let found = false;
+    walkScope(scope, scope, language, (candidate) => {
+        if (found || candidate.text !== name || !isBindingIdentifier(candidate, language))
+            return;
+        if (!allowed.has(nodeKey(candidate)))
+            found = true;
+    });
+    return found;
+}
+function isShadowed(node, name, language, allowed) {
+    for (let parent = node.parent; parent; parent = parent.parent) {
+        if (isScope(parent, language) && scopeBinds(parent, name, language, allowed))
+            return true;
+    }
+    return false;
+}
+function propertyOf(node) {
+    return field(node, 'property') ?? field(node, 'attribute');
+}
+function isProperty(node) {
+    const parent = node.parent;
+    return !!parent && sameNode(propertyOf(parent), node)
+        && ['member_expression', 'optional_member_expression', 'attribute'].includes(parent.type);
+}
+function isValueReference(node, language) {
+    if (node.type !== 'identifier' || isBindingIdentifier(node, language))
+        return false;
+    const parent = node.parent;
+    if (!parent || isProperty(node))
+        return false;
+    if (hasAncestor(node, new Set(['import_statement', 'import_from_statement'])))
+        return false;
+    if (sameNode(field(parent, 'key'), node) || ['export_specifier', 'export_clause'].includes(parent.type))
+        return false;
+    // Type positions have distinct namespaces in TS and do not prove a value-level use.
+    if (hasAncestor(node, new Set(['type_annotation', 'type_alias_declaration', 'interface_declaration', 'type_identifier'])))
+        return false;
+    return true;
+}
+function addBinding(bindings, localName, binding) {
+    const previous = bindings.get(localName);
+    bindings.set(localName, previous === undefined ? binding : null);
+}
+function stripQuotes(text) {
+    return text.replace(/^['"`]|['"`]$/g, '');
+}
+function jsTsBindings(root) {
+    const bindings = new Map();
+    walk(root, (statement) => {
+        if (statement.type !== 'import_statement')
+            return;
+        const source = field(statement, 'source');
+        if (!source)
+            return;
+        const module = stripQuotes(source.text);
+        let clause = null;
+        for (let i = 0; i < statement.namedChildCount; i++) {
+            const child = statement.namedChild(i);
+            if (child?.type === 'import_clause') {
+                clause = child;
+                break;
+            }
+        }
+        if (!clause)
+            return;
+        walk(clause, (candidate) => {
+            if (candidate.type !== 'import_specifier')
+                return;
+            const imported = field(candidate, 'name');
+            if (!imported || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(imported.text))
+                return;
+            const alias = field(candidate, 'alias');
+            addBinding(bindings, (alias ?? imported).text, {
+                module,
+                importedName: imported.text,
+                bindingNode: alias ?? imported,
+            });
+        });
+    });
+    return bindings;
+}
+function pythonBindings(root) {
+    const bindings = new Map();
+    walk(root, (statement) => {
+        if (statement.type !== 'import_from_statement')
+            return;
+        const source = field(statement, 'module_name');
+        if (!source)
+            return;
+        const module = source.text;
+        for (let i = 0; i < statement.namedChildCount; i++) {
+            const child = statement.namedChild(i);
+            if (!child || sameNode(child, source))
+                continue;
+            if (child.type === 'dotted_name' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(child.text)) {
+                addBinding(bindings, child.text, { module, importedName: child.text, bindingNode: child });
+            }
+            else if (child.type === 'aliased_import') {
+                const imported = field(child, 'name');
+                const alias = field(child, 'alias');
+                if (imported && alias && /^[A-Za-z_][A-Za-z0-9_]*$/.test(imported.text)) {
+                    addBinding(bindings, alias.text, { module, importedName: imported.text, bindingNode: alias });
+                }
+            }
+        }
+    });
+    return bindings;
+}
+/** Extract provider-local, soundness-first usage drafts from an already parsed tree. */
+export function extractLexicalUsages(root, definitions, language) {
+    if (!root)
+        return [];
+    const localTargets = new Map();
+    const allowedBindings = new Set();
+    for (const definition of definitions) {
+        if (!isLocalFunctionTarget(definition, language))
+            continue;
+        const previous = localTargets.get(definition.name);
+        localTargets.set(definition.name, previous === undefined ? definition : null);
+        const source = sourceOf(definition);
+        if (source)
+            allowedBindings.add(nodeKey(source.nameNode));
+    }
+    const bindings = language === 'js-ts' ? jsTsBindings(root) : pythonBindings(root);
+    for (const binding of bindings.values())
+        if (binding)
+            allowedBindings.add(nodeKey(binding.bindingNode));
+    const usages = [];
+    const seen = new Set();
+    const handledCallIdentifiers = new Set();
+    const handledProperties = new Set();
+    const add = (node, kind, target) => {
+        const caller = callerFor(node, definitions);
+        const targetKey = target.kind === 'local'
+            ? `local:${target.definitionOrdinal}`
+            : `import:${target.module}:${target.importedName}`;
+        const key = `${nodeKey(node)}:${kind}:${caller ?? 'file'}:${targetKey}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        usages.push({
+            kind,
+            ...(caller === undefined ? {} : { fromDefinitionOrdinal: caller }),
+            target,
+            span: spanOf(node),
+            confidence: kind === 'possible_textual_match' ? LOW_CONFIDENCE_TEXTUAL_MATCH : 1.0,
+        });
+    };
+    const directUse = (node, kind) => {
+        const name = node.text;
+        const local = localTargets.get(name);
+        const imported = bindings.get(name);
+        if ((local === undefined || local === null) && (!imported || imported === null))
+            return;
+        if (isShadowed(node, name, language, allowedBindings))
+            return;
+        if (local && local !== null) {
+            add(node, kind, { kind: 'local', definitionOrdinal: local.ordinal });
+        }
+        else if (imported) {
+            add(node, kind, { kind: 'import', module: imported.module, importedName: imported.importedName });
+        }
+    };
+    walk(root, (node) => {
+        if (node.type !== 'call_expression' && node.type !== 'call')
+            return;
+        const callee = field(node, 'function');
+        if (callee?.type === 'identifier') {
+            handledCallIdentifiers.add(nodeKey(callee));
+            directUse(callee, 'calls');
+            return;
+        }
+        if (!callee)
+            return;
+        const property = propertyOf(callee);
+        const local = property ? localTargets.get(property.text) : undefined;
+        if (property && local && local !== null) {
+            handledProperties.add(nodeKey(property));
+            add(property, 'possible_textual_match', { kind: 'local', definitionOrdinal: local.ordinal });
+        }
+    });
+    walk(root, (node) => {
+        if (node.type !== 'identifier')
+            return;
+        if (handledCallIdentifiers.has(nodeKey(node)) || handledProperties.has(nodeKey(node)))
+            return;
+        if (isProperty(node)) {
+            const local = localTargets.get(node.text);
+            if (local && local !== null)
+                add(node, 'possible_textual_match', { kind: 'local', definitionOrdinal: local.ordinal });
+            return;
+        }
+        if (isValueReference(node, language))
+            directUse(node, 'references');
+    });
+    return usages.sort((a, b) => a.span.start_line - b.span.start_line
+        || a.span.start_col - b.span.start_col
+        || a.kind.localeCompare(b.kind));
+}
+//# sourceMappingURL=usages.js.map

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

@@ -26,6 +26,12 @@ function coercePaths(raw) {
         return raw.filter((p) => typeof p === 'string');
     return [];
 }
+function optionalString(raw) {
+    return typeof raw === 'string' ? raw : undefined;
+}
+function optionalCount(raw) {
+    return typeof raw === 'number' && Number.isFinite(raw) ? raw : undefined;
+}
 function toRelatedMemoryItem(kind, item) {
     return {
         id: typeof item.id === 'string' ? item.id : '',
@@ -33,6 +39,15 @@ function toRelatedMemoryItem(kind, item) {
         text: typeof item.text === 'string' ? item.text : '',
         tags: coerceTags(item.tags),
         related_paths: coercePaths(item.related_paths),
+        created_at: optionalString(item.created_at),
+        last_confirmed_at: optionalString(item.last_confirmed_at),
+        last_infirmed_at: optionalString(item.last_infirmed_at),
+        confirmation_count: optionalCount(item.confirmation_count),
+        infirmation_count: optionalCount(item.infirmation_count),
+        saved_me_count: optionalCount(item.saved_me_count),
+        misled_me_count: optionalCount(item.misled_me_count),
+        verified_at: optionalString(item.verified_at),
+        verify_cmd: optionalString(item.verify_cmd),
     };
 }
 /**