Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

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.ts
index 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.ts
index 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 | n
if (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 | n
const 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 | n
if (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.ts
index 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) @name
value: (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_statement
source: (string) @import.source) @import
@@ -152,6 +182,36 @@ export const JAVASCRIPT_QUERIES = `
name: (identifier) @name
value: (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_statement
source: (string) @import.source) @import
diff --git a/ix-cli/src/cli/commands/locate.ts b/ix-cli/src/cli/commands/locate.ts
index 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.ts
index 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.ts
index 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.ts
index 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.md
index 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 when
every individual change is needed.