Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
feat(ingest): index module-level constants, as constants (Ix#679) (#691)
Ian Hock88c8843dd290
diff --git a/core-ingestion/src/__tests__/queries.typescript.test.ts b/core-ingestion/src/__tests__/queries.typescript.test.tsindex 305369a8..e544cb0a 100644--- a/core-ingestion/src/__tests__/queries.typescript.test.ts+++ b/core-ingestion/src/__tests__/queries.typescript.test.ts@@ -54,6 +54,59 @@ describe('TypeScript queries', () => {});});+ it('indexes a module-level const, and only a module-level one', () => {+ const result = parseFile(+ '/repo/constants.ts',+ `+ export const SUPPORTED_EXTENSIONS = new Set(['.ts'])+ const BUDGETS = [1, 2]+ export const contextBundleSchema = z.object({})+ export const BUNDLE_SCHEMA = 'ix-context-bundle/1'+ let mutable = 3+ const { destructured } = source+ export const handler = () => 1+ const legacy = function () { return 2 }+ function outer() {+ const local = 5+ return local+ }+ `,+ );++ expect(result).not.toBeNull();+ const byKind = (kind: string) =>+ result!.entities.filter(e => e.kind === kind).map(e => e.name).sort();++ // The four ground-truth symbols from the retrieval benchmark that a graph+ // of this repo could not resolve (Ix#679) — note BUDGETS is unexported.+ expect(byKind('constant')).toEqual([+ 'BUDGETS', 'BUNDLE_SCHEMA', 'SUPPORTED_EXTENSIONS', 'contextBundleSchema',+ ]);++ // A function value is still a function, and the const rule does not add a+ // second `constant` entity for it.+ //+ // Deduped in the assertion because `export const handler = () => 1` already+ // matched two of the four function rules before this change (the plain+ // lexical_declaration rule is unanchored, so it matches inside the+ // export_statement the fourth rule matches). Both entries carry the same+ // name and line range, so patch-builder folds them onto one node id — it is+ // wasted work, not a wrong graph, and it is not this change's to fix.+ expect([...new Set(byKind('function'))]).toEqual(['handler', 'legacy', 'outer']);++ const names = result!.entities.map(e => e.name);+ expect(names).not.toContain('local'); // function-local+ expect(names).not.toContain('mutable'); // `let`, not `const`+ expect(names).not.toContain('destructured'); // binds no single name+ });++ it('gives a constant the line range of its own declaration', () => {+ const result = parseFile('/repo/c.ts', `const A = 1\nconst B = [\n 2,\n]\n`);+ const b = result!.entities.find(e => e.name === 'B')!;+ expect(b.kind).toBe('constant');+ expect([b.lineStart, b.lineEnd]).toEqual([2, 4]);+ });+it('substitutes this → enclosing class for this.method() calls', () => {const result = parseFile('/repo/model.ts',diff --git a/core-ingestion/src/index.ts b/core-ingestion/src/index.tsindex a9b0d0ba..5be757ea 100644--- a/core-ingestion/src/index.ts+++ b/core-ingestion/src/index.ts@@ -309,7 +309,12 @@ const DEFINITION_KIND_MAP: Record<string, string> = {'definition.impl': 'class','definition.type': 'class','definition.property': 'function',- 'definition.const': 'function',+ // Its own kind, not 'function' (Ix#679 / decision D10). Rust const_item,+ // Scala val/var_definition, Java, C#, Swift and CSS keyframes all already+ // routed through here, so every one of them has been arriving as a function:+ // `ix search --kind function`, `ix inventory --kind function` and+ // `ix rank --kind function` have been counting constants as callable code.+ 'definition.const': 'constant','definition.static': 'function','definition.macro': 'macro','definition.union': 'class',@@ -2541,6 +2546,17 @@ export function parseFile(filePath: string, source: string): FileParseResult | nif (defCapture) {const kind = DEFINITION_KIND_MAP[defCapture.name] ?? 'function';++ // A module-level `const` bound to a function is already captured by the+ // TS/JS function rules, which run ahead of the const rule. Without this+ // the one declaration arrives twice — once as `function`, once as+ // `constant` — with the same name, file and line range. Only the JS/TS+ // const rules emit `const.value`; every other language's+ // `definition.const` has no such capture and falls straight through.+ if (defCapture.name === 'definition.const') {+ const valueType = match.captures.find((c: any) => c.name === 'const.value')?.node.type;+ if (valueType === 'arrow_function' || valueType === 'function_expression') continue;+ }const rawName = nameCapture?.node.text?? (defCapture.name === 'definition.constructor' ? 'init' : '');// Strip surrounding quotes only for string-keyed definitions (R S3 method@@ -2740,7 +2756,7 @@ export function parseFile(filePath: string, source: string): FileParseResult | n//// For method_declarations, the paramTypeMap key MUST include the// receiver type (i.e. `Container.method`) because that's what- // findEnclosingFunction returns at call-resolution time. Without+ // findEnclosingDefinition returns at call-resolution time. Without// this, lookups for callers inside methods miss.if (language === SupportedLanguages.Go) {const goParamScope = match.captures.find((c: any) => c.name === '_go_param_scope');@@ -2785,7 +2801,7 @@ export function parseFile(filePath: string, source: string): FileParseResult | nconst line = typedVarScope.node.startPosition.row + 1;const scope = language === SupportedLanguages.PHP? findEnclosing(classRanges, line, '') ?? fileName- : findEnclosingFunction(entities, line)+ : findEnclosingDefinition(entities, line)?? findEnclosing(classRanges, line, '')?? fileName;if (!declaredTypeMap.has(scope)) declaredTypeMap.set(scope, new Map());@@ -2970,7 +2986,7 @@ export function parseFile(filePath: string, source: string): FileParseResult | n// For Python: skip calls that are decorator applications.// When a method is decorated (e.g. @util.deprecated(...)), the call sits at the- // class-body line before the def, so findEnclosingFunction misses the method and+ // class-body line before the def, so findEnclosingDefinition misses the method and// the caller falls back to the enclosing class — producing false edges like// Table → deprecated. Decorator application is not an architectural CALLS edge.if (language === SupportedLanguages.Python) {@@ -3009,7 +3025,7 @@ export function parseFile(filePath: string, source: string): FileParseResult | n// Find enclosing function/method for the call; fall back to enclosing class// (e.g. calls in val/lazy val body at class level) before falling back to file.const callLine = callName.node.startPosition.row + 1;- const caller = findEnclosingFunction(entities, callLine)+ const caller = findEnclosingDefinition(entities, callLine)?? findEnclosing(classRanges, callLine, '')?? fileName;@@ -3041,7 +3057,7 @@ export function parseFile(filePath: string, source: string): FileParseResult | n// Python: if the callee is a local alias for a class, substitute the class name.// e.g. engineclass = base.Engine; engineclass(pool, ...) → Engine(pool, ...)if (language === SupportedLanguages.Python) {- const funcName = findEnclosingFunction(entities, callLine);+ const funcName = findEnclosingDefinition(entities, callLine);if (funcName) {const typeForAssign = assignTypeMap.get(funcName)?.get(callee);if (typeForAssign) return typeForAssign;@@ -3083,7 +3099,7 @@ export function parseFile(filePath: string, source: string): FileParseResult | n// Typed-parameter substitution: if the qualifier is a param with a declared type,// use the type name so e.g. `query.filter(...)` → `Query.filter`.// Also check assignTypeMap for variables assigned from constructor/ORM calls.- const funcName = findEnclosingFunction(entities, callLine);+ const funcName = findEnclosingDefinition(entities, callLine);if (funcName) {const typeForParam = paramTypeMap.get(funcName)?.get(qualifier);const typeForAssign = assignTypeMap.get(funcName)?.get(qualifier);@@ -3096,13 +3112,13 @@ export function parseFile(filePath: string, source: string): FileParseResult | n// type. e.g. `opts.Run()` inside `func F(opts *Options)` → use// qualifier "Options" so dstName is "Options.Run", which// edge-resolver indexes via the container.name fallback key.- const funcName = findEnclosingFunction(entities, callLine);+ const funcName = findEnclosingDefinition(entities, callLine);if (funcName) {const typeForParam = paramTypeMap.get(funcName)?.get(qualifier);if (typeForParam) qualifier = typeForParam;}} else if (language === SupportedLanguages.PHP) {- const funcName = findEnclosingFunction(entities, callLine);+ const funcName = findEnclosingDefinition(entities, callLine);const className = findEnclosing(classRanges, callLine, '');const typeForReceiver = phpPropertyOnThis? (className ? declaredTypeMap.get(className)?.get(qualifier) : undefined)@@ -3110,7 +3126,7 @@ export function parseFile(filePath: string, source: string): FileParseResult | nif (typeForReceiver) qualifier = typeForReceiver;else return callee;} else if (language === SupportedLanguages.C || language === SupportedLanguages.CPlusPlus) {- const funcName = findEnclosingFunction(entities, callLine) ?? fileName;+ const funcName = findEnclosingDefinition(entities, callLine) ?? fileName;const className = findEnclosing(classRanges, callLine, '')?? (funcName.includes('.') ? funcName.slice(0, funcName.lastIndexOf('.')) : undefined);const typeForDecl =@@ -3148,7 +3164,7 @@ export function parseFile(filePath: string, source: string): FileParseResult | n// Prefer the enclosing function/method so parameter and return-type references// point back to the actual caller. Fall back to class, then file.const refLine = refType.node.startPosition.row + 1;- const src = findEnclosingFunction(entities, refLine)+ const src = findEnclosingDefinition(entities, refLine)?? findEnclosing(classRanges, refLine, typeName)?? fileName;@@ -4937,13 +4953,25 @@ function findEnclosing(return best?.name ?? null;}-function findEnclosingFunction(+/**+ * The innermost definition whose body contains `line` — what a call or a+ * reference on that line should be attributed to.+ *+ * `constant` counts. A constant's initializer is a body like any other: the+ * `z.object(...)` in `const schema = z.object({...})` is a call made by+ * `schema`, and a Scala `var baz: NodeKind = NodeKind.File` is the holder of+ * the reference to `NodeKind`, not its enclosing class (#557). Those constants+ * arrived here as `kind: 'function'` until Ix#679 gave them their own kind, so+ * leaving them out would have quietly re-coarsened every such edge to the class+ * or the file.+ */+function findEnclosingDefinition(entities: ParsedEntity[],line: number): string | null {let best: ParsedEntity | null = null;for (const e of entities) {- if (e.kind !== 'function' && e.kind !== 'method') continue;+ if (e.kind !== 'function' && e.kind !== 'method' && e.kind !== 'constant') continue;if (line >= e.lineStart && line <= e.lineEnd) {if (!best || (e.lineEnd - e.lineStart) < (best.lineEnd - best.lineStart)) {best = e;diff --git a/core-ingestion/src/queries.ts b/core-ingestion/src/queries.tsindex 3995ef82..2cb64836 100644--- a/core-ingestion/src/queries.ts+++ b/core-ingestion/src/queries.ts@@ -46,6 +46,36 @@ export const TYPESCRIPT_QUERIES = `name: (identifier) @namevalue: (function_expression)))) @definition.function+; Module-level constants (Ix#679). Anchored under (program ...) so the 5,085+; const declarations in ix-cli/src stay out and the 259 module-scope ones come+; in: a blanket variable_declarator rule multiplies a package's entity count+; ~20x with function-local bindings, which costs every ranking and every bundle+; budget. The literal "const" keeps \`let\` out — mutable module state is not+; the thing an agent searches for by name.+;+; Export is deliberately not required: BUDGETS in commands/context.ts is+; module-scope and unexported, and an export-only rule would still miss it.+; Destructuring patterns do not match either — \`name: (identifier)\` skips+; \`const { a, b } = obj\`, which binds no single name worth indexing.+;+; The value is captured so index.ts can drop the arrow-function and+; function-expression cases, which the four rules above have already claimed as+; definition.function. Without that, an exported arrow function arrives twice.+(program+ (lexical_declaration+ "const"+ (variable_declarator+ name: (identifier) @name+ value: (_) @const.value)) @definition.const)++(program+ (export_statement+ declaration: (lexical_declaration+ "const"+ (variable_declarator+ name: (identifier) @name+ value: (_) @const.value))) @definition.const)+(import_statementsource: (string) @import.source) @import@@ -152,6 +182,36 @@ export const JAVASCRIPT_QUERIES = `name: (identifier) @namevalue: (function_expression)))) @definition.function+; Module-level constants (Ix#679). Anchored under (program ...) so the 5,085+; const declarations in ix-cli/src stay out and the 259 module-scope ones come+; in: a blanket variable_declarator rule multiplies a package's entity count+; ~20x with function-local bindings, which costs every ranking and every bundle+; budget. The literal "const" keeps \`let\` out — mutable module state is not+; the thing an agent searches for by name.+;+; Export is deliberately not required: BUDGETS in commands/context.ts is+; module-scope and unexported, and an export-only rule would still miss it.+; Destructuring patterns do not match either — \`name: (identifier)\` skips+; \`const { a, b } = obj\`, which binds no single name worth indexing.+;+; The value is captured so index.ts can drop the arrow-function and+; function-expression cases, which the four rules above have already claimed as+; definition.function. Without that, an exported arrow function arrives twice.+(program+ (lexical_declaration+ "const"+ (variable_declarator+ name: (identifier) @name+ value: (_) @const.value)) @definition.const)++(program+ (export_statement+ declaration: (lexical_declaration+ "const"+ (variable_declarator+ name: (identifier) @name+ value: (_) @const.value))) @definition.const)+(import_statementsource: (string) @import.source) @importdiff --git a/ix-cli/src/cli/commands/locate.ts b/ix-cli/src/cli/commands/locate.tsindex 4dfc83e7..27b94b2c 100644--- a/ix-cli/src/cli/commands/locate.ts+++ b/ix-cli/src/cli/commands/locate.ts@@ -200,7 +200,7 @@ async function resolveWithAmbiguity(}// Symbol resolution — use full result to detect ambiguity- const allKinds = ["file", "class", "object", "trait", "interface", "module", "function", "method"];+ const allKinds = ["file", "class", "object", "trait", "interface", "module", "function", "method", "constant"];const result = await resolveEntityFull(client, symbol, allKinds, { ...opts, format });if (result.resolved) {diff --git a/ix-cli/src/cli/commands/read.ts b/ix-cli/src/cli/commands/read.tsindex 2a689920..b88c4bb1 100644--- a/ix-cli/src/cli/commands/read.ts+++ b/ix-cli/src/cli/commands/read.ts@@ -638,7 +638,7 @@ async function trySymbolMatch(symbol: string,opts: { kind?: string; path?: string; pick?: number; format?: string }): Promise<SymbolResult> {- const preferredKinds = ["file", "class", "object", "trait", "interface", "module", "function", "method"];+ const preferredKinds = ["file", "class", "object", "trait", "interface", "module", "function", "method", "constant"];const full = await resolveEntityFull(client, symbol, preferredKinds, opts);if (full.resolved) {diff --git a/ix-cli/src/cli/commands/search.ts b/ix-cli/src/cli/commands/search.tsindex f194659e..3d091264 100644--- a/ix-cli/src/cli/commands/search.ts+++ b/ix-cli/src/cli/commands/search.ts@@ -31,6 +31,7 @@ export function renderSearchLlm(/** Structural kinds that should rank higher than incidental matches. */const STRUCTURAL_KINDS = new Set(["class", "trait", "object", "interface", "function", "method", "module", "file",+ "constant",]);/**diff --git a/ix-cli/src/cli/resolve.ts b/ix-cli/src/cli/resolve.tsindex 694d7323..b84277a0 100644--- a/ix-cli/src/cli/resolve.ts+++ b/ix-cli/src/cli/resolve.ts@@ -154,7 +154,7 @@ const CONTAINER_KINDS = new Set(["file", "class", "object", "trait", "interface"/** All kinds that represent real code structure (vs. config/doc/decision). */const STRUCTURAL_KINDS = new Set([- ...CONTAINER_KINDS, "function", "method",+ ...CONTAINER_KINDS, "function", "method", "constant",]);/**@@ -754,7 +754,12 @@ export async function resolveFileOrEntityFull(}// 3. Symbol resolution (handles all entity kinds)- const allKinds = ["file", "class", "object", "trait", "interface", "module", "method", "function"];+ //+ // Order is a tie-break, not a filter — an unlisted kind still resolves, it+ // just sorts last among equal-scoring candidates. `constant` is here so a+ // module-level constant is not ranked behind every config entry and heading+ // that happens to share its name (Ix#679).+ const allKinds = ["file", "class", "object", "trait", "interface", "module", "method", "function", "constant"];return resolveEntityFull(client, target, allKinds, opts);}diff --git a/skills/ix/references/commands.md b/skills/ix/references/commands.mdindex 90e0596e..4cc50c51 100644--- a/skills/ix/references/commands.md+++ b/skills/ix/references/commands.md@@ -152,7 +152,11 @@ ix inventory --kind function --path auth.py## Best Practices-- Always use `--kind` with `ix search` to get bounded results.+- Always use `--kind` with `ix search` to get bounded results. A module-level+ constant is `--kind constant`, not `function` — that covers a `const` bound+ to an object, an array, a `Set`, a schema or a string literal in TS/JS, and+ a Rust `const`, a Scala `val`/`var`, and their Java, C#, and Swift+ equivalents.- Use `ix inventory` instead of `ix search ""` for listing entities by kind.- Use `ix diff --summary` for broad revision comparisons; `--full` only whenevery individual change is needed.