Skip to content

armgit / Ix

Public Imported from GitHub
0

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

Feat/json support (#118)

josephismikhailadcf972be0c2
diff --git a/core-ingestion/src/__tests__/queries.json.test.ts b/core-ingestion/src/__tests__/queries.json.test.ts
new file mode 100644
index 00000000..dd224878
--- /dev/null
+++ b/core-ingestion/src/__tests__/queries.json.test.ts
@@ -0,0 +1,131 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseFile } from '../index.js';
+import { languageFromPath, SupportedLanguages } from '../languages.js';
+
+describe('JSON parsing', () => {
+ it('recognizes .json as JSON', () => {
+ expect(languageFromPath('/repo/package.json')).toBe(SupportedLanguages.JSON);
+ expect(languageFromPath('/repo/tsconfig.json')).toBe(SupportedLanguages.JSON);
+ });
+
+ it('parses top-level keys from a flat object', () => {
+ const result = parseFile(
+ '/repo/package.json',
+ JSON.stringify({ name: 'my-app', version: '1.0.0', private: true }),
+ );
+
+ expect(result).not.toBeNull();
+ expect(result!.language).toBe(SupportedLanguages.JSON);
+ expect(result!.entities).toContainEqual(
+ expect.objectContaining({ name: 'name', kind: 'config_entry', language: SupportedLanguages.JSON }),
+ );
+ expect(result!.entities).toContainEqual(
+ expect.objectContaining({ name: 'version', kind: 'config_entry' }),
+ );
+ expect(result!.relationships).toContainEqual({
+ srcName: 'package.json',
+ dstName: 'name',
+ predicate: 'CONTAINS',
+ });
+ });
+
+ it('parses nested object keys with correct container', () => {
+ const result = parseFile(
+ '/repo/config.json',
+ JSON.stringify({ database: { host: 'localhost', port: 5432 } }),
+ );
+
+ expect(result).not.toBeNull();
+ expect(result!.entities).toContainEqual(
+ expect.objectContaining({ name: 'database', kind: 'config_entry', container: undefined }),
+ );
+ expect(result!.entities).toContainEqual(
+ expect.objectContaining({ name: 'host', kind: 'config_entry', container: 'database' }),
+ );
+ expect(result!.entities).toContainEqual(
+ expect.objectContaining({ name: 'port', kind: 'config_entry', container: 'database' }),
+ );
+ expect(result!.relationships).toContainEqual({
+ srcName: 'database',
+ dstName: 'host',
+ predicate: 'CONTAINS',
+ });
+ });
+
+ it('parses keys inside array items', () => {
+ const result = parseFile(
+ '/repo/servers.json',
+ JSON.stringify({ servers: [{ host: 'a.example.com' }, { host: 'b.example.com' }] }),
+ );
+
+ expect(result).not.toBeNull();
+ const hostEntities = result!.entities.filter((e) => e.name === 'host');
+ expect(hostEntities.length).toBe(2);
+ });
+
+ it('uses fully qualified containers for repeated nested keys', () => {
+ const result = parseFile(
+ '/repo/countries.json',
+ JSON.stringify({
+ name: { common: 'Aruba' },
+ currencies: { AWG: { name: 'Aruban florin' } },
+ }),
+ );
+
+ expect(result).not.toBeNull();
+ expect(result!.entities).toContainEqual(
+ expect.objectContaining({ name: 'common', container: 'name' }),
+ );
+ expect(result!.entities).toContainEqual(
+ expect.objectContaining({ name: 'name', container: 'currencies.AWG' }),
+ );
+ expect(result!.relationships).toContainEqual({
+ srcName: 'currencies.AWG',
+ dstName: 'name',
+ predicate: 'CONTAINS',
+ });
+ });
+
+ it('parses geojson-style keys nested inside array items', () => {
+ const result = parseFile(
+ '/repo/abw.geo.json',
+ JSON.stringify({
+ type: 'FeatureCollection',
+ features: [{ type: 'Feature', properties: { cca2: 'aw' } }],
+ }),
+ );
+
+ expect(result).not.toBeNull();
+ expect(result!.entities).toContainEqual(
+ expect.objectContaining({ name: 'features', kind: 'config_entry' }),
+ );
+ expect(result!.entities).toContainEqual(
+ expect.objectContaining({ name: 'properties', container: 'features' }),
+ );
+ expect(result!.entities).toContainEqual(
+ expect.objectContaining({ name: 'cca2', container: 'features.properties' }),
+ );
+ });
+
+ it('falls back to file_body chunk for invalid JSON', () => {
+ const result = parseFile('/repo/broken.json', '{ invalid json }');
+
+ expect(result).not.toBeNull();
+ expect(result!.chunks).toHaveLength(1);
+ expect(result!.chunks[0].chunkKind).toBe('file_body');
+ });
+
+ it('emits config_key chunks with content hashes', () => {
+ const result = parseFile(
+ '/repo/settings.json',
+ JSON.stringify({ timeout: 30 }),
+ );
+
+ expect(result).not.toBeNull();
+ const chunk = result!.chunks.find((c) => c.name === 'timeout');
+ expect(chunk).toBeDefined();
+ expect(chunk!.chunkKind).toBe('config_key');
+ expect(chunk!.contentHash).toMatch(/^[0-9a-f]{64}$/);
+ });
+});
diff --git a/core-ingestion/src/index.ts b/core-ingestion/src/index.ts
index cc4b359d..51cce190 100644
--- a/core-ingestion/src/index.ts
+++ b/core-ingestion/src/index.ts
@@ -213,7 +213,7 @@ function builtinsForLanguage(lang: SupportedLanguages): Set<string> {
export function isGrammarSupported(filePath: string): boolean {
const language = languageFromPath(filePath);
if (!language) return false;
- if (language === SupportedLanguages.YAML || language === SupportedLanguages.Dockerfile || language === SupportedLanguages.SQL) return true;
+ if (language === SupportedLanguages.YAML || language === SupportedLanguages.Dockerfile || language === SupportedLanguages.SQL || language === SupportedLanguages.JSON) return true;
if (filePath.endsWith('.tsx')) return true; // TSX uses TypeScript.tsx, always available
return GRAMMAR_MAP[language] !== undefined;
}
@@ -570,6 +570,89 @@ function extractSqlTableRefs(sql: string): string[] {
return [...refs];
}
+function parseJsonFile(filePath: string, source: string): FileParseResult {
+ const language = SupportedLanguages.JSON;
+ const fileName = nodePath.basename(filePath);
+ const sourceLineCount = countSourceLines(source);
+ const fileRole = classifyFileRole(filePath);
+ const entities: ParsedEntity[] = [
+ { name: fileName, kind: 'file', lineStart: 1, lineEnd: sourceLineCount, language },
+ ];
+ const chunks: ParsedChunk[] = [];
+ const relationships: ParsedRelationship[] = [];
+
+ // Walk the parsed JSON value, emitting one entity+chunk per object key.
+ // `path` is the fully qualified key ancestry for the current object.
+ const walk = (
+ value: unknown,
+ path: string,
+ lineHint: number,
+ ): void => {
+ if (value === null || typeof value !== 'object') return;
+
+ if (Array.isArray(value)) {
+ for (const item of value) {
+ walk(item, path, lineHint);
+ }
+ return;
+ }
+
+ for (const key of Object.keys(value as Record<string, unknown>)) {
+ const fullPath = path ? `${path}.${key}` : key;
+ entities.push({
+ name: key,
+ kind: 'config_entry',
+ lineStart: lineHint,
+ lineEnd: lineHint,
+ language,
+ container: path || undefined,
+ });
+ chunks.push({
+ name: key,
+ chunkKind: 'config_key',
+ lineStart: lineHint,
+ lineEnd: lineHint,
+ startByte: 0,
+ endByte: 0,
+ contentHash: crypto
+ .createHash('sha256')
+ .update(`${fullPath}=${JSON.stringify((value as Record<string, unknown>)[key])}`)
+ .digest('hex'),
+ language,
+ container: path || undefined,
+ });
+ relationships.push({
+ srcName: path || fileName,
+ dstName: key,
+ predicate: 'CONTAINS',
+ });
+ walk((value as Record<string, unknown>)[key], fullPath, lineHint);
+ }
+ };
+
+ try {
+ const parsed: unknown = JSON.parse(source);
+ walk(parsed, '', 1);
+ } catch {
+ // Unparseable JSON: fall through to file_body chunk below
+ }
+
+ if (chunks.length === 0) {
+ chunks.push({
+ name: null,
+ chunkKind: 'file_body',
+ lineStart: 1,
+ lineEnd: Math.max(sourceLineCount, 1),
+ startByte: 0,
+ endByte: source.length,
+ contentHash: crypto.createHash('sha256').update(source).digest('hex'),
+ language,
+ });
+ }
+
+ return { filePath, language, entities, chunks, relationships, fileRole };
+}
+
function parseSqlFile(filePath: string, source: string): FileParseResult {
const language = SupportedLanguages.SQL;
const fileName = nodePath.basename(filePath);
@@ -757,6 +840,7 @@ export function parseFile(filePath: string, source: string): FileParseResult | n
if (language === SupportedLanguages.YAML) return parseYamlFile(filePath, source);
if (language === SupportedLanguages.Dockerfile) return parseDockerfileFile(filePath, source);
if (language === SupportedLanguages.SQL) return parseSqlFile(filePath, source);
+ if (language === SupportedLanguages.JSON) return parseJsonFile(filePath, source);
// TypeScript TSX uses a separate grammar
const isTsx = filePath.endsWith('.tsx');
diff --git a/core-ingestion/src/languages.ts b/core-ingestion/src/languages.ts
index 35117828..85464017 100644
--- a/core-ingestion/src/languages.ts
+++ b/core-ingestion/src/languages.ts
@@ -16,6 +16,7 @@ export enum SupportedLanguages {
YAML = 'yaml',
Dockerfile = 'dockerfile',
SQL = 'sql',
+ JSON = 'json',
}
const EXT_MAP: Record<string, SupportedLanguages> = {
@@ -47,6 +48,7 @@ const EXT_MAP: Record<string, SupportedLanguages> = {
'.yml': SupportedLanguages.YAML,
'.dockerfile': SupportedLanguages.Dockerfile,
'.sql': SupportedLanguages.SQL,
+ '.json': SupportedLanguages.JSON,
};
export function languageFromPath(filePath: string): SupportedLanguages | null {
diff --git a/core-ingestion/src/queries.ts b/core-ingestion/src/queries.ts
index 9f423a4c..c6f70893 100644
--- a/core-ingestion/src/queries.ts
+++ b/core-ingestion/src/queries.ts
@@ -1182,5 +1182,6 @@ export const LANGUAGE_QUERIES: Record<SupportedLanguages, string> = {
[SupportedLanguages.YAML]: '',
[SupportedLanguages.Dockerfile]: '',
[SupportedLanguages.SQL]: '',
+ [SupportedLanguages.JSON]: '',
};
diff --git a/ix-cli/package-lock.json b/ix-cli/package-lock.json
index da18c35e..f23b2359 100644
--- a/ix-cli/package-lock.json
+++ b/ix-cli/package-lock.json
@@ -1508,6 +1508,7 @@
"integrity": "sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==",
"dev": true,
"license": "MIT",
+ "peer": true,
"dependencies": {
"esbuild": "^0.27.0",
"fdir": "^6.5.0",
diff --git a/ix-cli/src/cli/__tests__/hierarchy.test.ts b/ix-cli/src/cli/__tests__/hierarchy.test.ts
new file mode 100644
index 00000000..ecb73682
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/hierarchy.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, it, vi } from "vitest";
+import { getEffectiveSystemPath, hasMapData } from "../hierarchy.js";
+
+describe("getEffectiveSystemPath", () => {
+ it("uses the direct system path when it already has map data", async () => {
+ const expand = vi.fn().mockResolvedValue({
+ nodes: [
+ { id: "sys", kind: "system", name: "CLI" },
+ { id: "sub", kind: "subsystem", name: "Client" },
+ ],
+ edges: [],
+ });
+
+ const client = { expand } as any;
+
+ const path = await getEffectiveSystemPath(client, "node-1");
+
+ expect(hasMapData(path)).toBe(true);
+ expect(path.map((n) => n.kind)).toEqual(["system", "subsystem"]);
+ expect(expand).toHaveBeenCalledTimes(1);
+ });
+
+ it("inherits map data from an ancestor file for nested config entries", async () => {
+ const expand = vi.fn(async (id: string, opts?: { predicates?: string[] }) => {
+ if (id === "common" && opts?.predicates?.[0] === "IN_REGION") {
+ return { nodes: [], edges: [] };
+ }
+ if (id === "common" && opts?.predicates?.[0] === "CONTAINS") {
+ return {
+ nodes: [
+ { id: "lang", kind: "config_entry", name: "nob" },
+ { id: "name", kind: "config_entry", name: "name" },
+ { id: "file-1", kind: "file", name: "countries.json" },
+ ],
+ edges: [],
+ };
+ }
+ if (id === "file-1" && opts?.predicates?.[0] === "IN_REGION") {
+ return {
+ nodes: [
+ { id: "sys", kind: "system", name: "Countries" },
+ { id: "sub", kind: "subsystem", name: "JSON corpus" },
+ { id: "file-1", kind: "file", name: "countries.json" },
+ ],
+ edges: [],
+ };
+ }
+ return { nodes: [], edges: [] };
+ });
+
+ const client = { expand } as any;
+
+ const path = await getEffectiveSystemPath(client, "common");
+
+ expect(hasMapData(path)).toBe(true);
+ expect(path.map((n) => n.name)).toEqual(["Countries", "JSON corpus", "countries.json"]);
+ });
+
+ it("returns the direct path when no mapped ancestor exists", async () => {
+ const expand = vi.fn(async (id: string, opts?: { predicates?: string[] }) => {
+ if (id === "leaf" && opts?.predicates?.[0] === "IN_REGION") {
+ return { nodes: [], edges: [] };
+ }
+ if (id === "leaf" && opts?.predicates?.[0] === "CONTAINS") {
+ return { nodes: [{ id: "parent", kind: "config_entry", name: "parent" }], edges: [] };
+ }
+ if (id === "parent" && opts?.predicates?.[0] === "IN_REGION") {
+ return { nodes: [], edges: [] };
+ }
+ return { nodes: [], edges: [] };
+ });
+
+ const client = { expand } as any;
+
+ const path = await getEffectiveSystemPath(client, "leaf");
+
+ expect(path).toEqual([]);
+ expect(hasMapData(path)).toBe(false);
+ });
+});
diff --git a/ix-cli/src/cli/__tests__/trace-path.test.ts b/ix-cli/src/cli/__tests__/trace-path.test.ts
index 15925663..a69a4898 100644
--- a/ix-cli/src/cli/__tests__/trace-path.test.ts
+++ b/ix-cli/src/cli/__tests__/trace-path.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from 'vitest';
-import { findPath } from '../commands/trace.js';
+import { findPath, pickTraceTarget } from '../commands/trace.js';
// ---------------------------------------------------------------------------
// Helpers
@@ -129,3 +129,79 @@ describe('no path between disconnected files', () => {
expect(path).toBeNull();
});
});
+
+describe('trace target selection', () => {
+ it('prefers the exact-name config entry that has traversable downstream edges', async () => {
+ const client = {
+ async search() {
+ return [
+ { id: 'orphan-name', kind: 'config_entry', name: 'name', provenance: { source_uri: '/repo/countries-unescaped.json' } },
+ { id: 'nested-name', kind: 'config_entry', name: 'name', provenance: { source_uri: '/repo/countries.json' } },
+ ];
+ },
+ async expand(id: string, opts?: { direction?: string }) {
+ if (id === 'orphan-name' && opts?.direction === 'out') {
+ return { nodes: [], edges: [] };
+ }
+ if (id === 'nested-name' && opts?.direction === 'out') {
+ return {
+ nodes: [
+ { id: 'common', kind: 'config_entry', name: 'common' },
+ { id: 'official', kind: 'config_entry', name: 'official' },
+ ],
+ edges: [],
+ };
+ }
+ return { nodes: [], edges: [] };
+ },
+ };
+
+ const target = await pickTraceTarget(
+ client as any,
+ 'name',
+ { id: 'orphan-name', kind: 'config_entry', name: 'name', path: '/repo/countries-unescaped.json', resolutionMode: 'exact' },
+ { direction: 'downstream', predicates: ['CONTAINS'] },
+ );
+
+ expect(target.id).toBe('nested-name');
+ expect(target.path).toBe('/repo/countries.json');
+ });
+
+ it('uses trace-ranked candidates when --pick is provided for duplicate config keys', async () => {
+ const client = {
+ async search() {
+ return [
+ { id: 'orphan-name', kind: 'config_entry', name: 'name', provenance: { source_uri: '/repo/countries-unescaped.json' } },
+ { id: 'nested-name', kind: 'config_entry', name: 'name', provenance: { source_uri: '/repo/countries.json' } },
+ { id: 'deep-name', kind: 'config_entry', name: 'name', provenance: { source_uri: '/repo/alt.json' } },
+ ];
+ },
+ async expand(id: string, opts?: { direction?: string }) {
+ if (opts?.direction !== 'out') return { nodes: [], edges: [] };
+ if (id === 'nested-name') {
+ return { nodes: [{ id: 'common', kind: 'config_entry', name: 'common' }], edges: [] };
+ }
+ if (id === 'deep-name') {
+ return {
+ nodes: [
+ { id: 'common', kind: 'config_entry', name: 'common' },
+ { id: 'official', kind: 'config_entry', name: 'official' },
+ { id: 'native', kind: 'config_entry', name: 'native' },
+ ],
+ edges: [],
+ };
+ }
+ return { nodes: [], edges: [] };
+ },
+ };
+
+ const target = await pickTraceTarget(
+ client as any,
+ 'name',
+ { id: 'orphan-name', kind: 'config_entry', name: 'name', path: '/repo/countries-unescaped.json', resolutionMode: 'exact' },
+ { direction: 'downstream', predicates: ['CONTAINS'], pick: 2 },
+ );
+
+ expect(target.id).toBe('nested-name');
+ });
+});
diff --git a/ix-cli/src/cli/commands/ingest.ts b/ix-cli/src/cli/commands/ingest.ts
index 19a77b2f..bab31737 100644
--- a/ix-cli/src/cli/commands/ingest.ts
+++ b/ix-cli/src/cli/commands/ingest.ts
@@ -36,6 +36,7 @@ const SUPPORTED_EXTENSIONS = new Set([
'.yaml', '.yml',
'.dockerfile',
'.sql',
+ '.json',
]);
export function isSupportedSourceFile(filePath: string): boolean {
diff --git a/ix-cli/src/cli/commands/locate.ts b/ix-cli/src/cli/commands/locate.ts
index b1e6f0d6..d791056f 100644
--- a/ix-cli/src/cli/commands/locate.ts
+++ b/ix-cli/src/cli/commands/locate.ts
@@ -9,7 +9,7 @@ import {
import { isFileStale } from "../stale.js";
import { stderr } from "../stderr.js";
import { relativePath } from "../format.js";
-import { getSystemPath, hasMapData } from "../hierarchy.js";
+import { getEffectiveSystemPath, hasMapData } from "../hierarchy.js";
import { humanizeLabel } from "../impact/risk-semantics.js";
import { renderSection, renderKeyValue, renderNote, renderWarning, renderBreadcrumb } from "../ui.js";
@@ -73,9 +73,9 @@ export function registerLocateCommand(program: Command): void {
const isContainer = CONTAINER_KINDS.has(target.kind);
const isFile = FILE_KINDS.has(target.kind);
- // Parallel fetch: system path, parent container (for non-containers), entity details
+ // Parallel fetch: effective system path, parent container (for non-containers), entity details
const [systemPath, containsResult, details] = await Promise.all([
- getSystemPath(client, target.id),
+ getEffectiveSystemPath(client, target.id),
isContainer
? Promise.resolve({ nodes: [] })
: client.expand(target.id, { direction: "in", predicates: ["CONTAINS"] }),
@@ -112,23 +112,14 @@ export function registerLocateCommand(program: Command): void {
// Sub-file entities (table, view, function, etc.) have no IN_REGION edges of their
// own — those belong to the containing file. Walk up via CONTAINS to inherit the
// parent file's system path so hasMapData returns true after `ix map`.
- let effectiveSystemPath = systemPath;
- if (!hasMapData(systemPath) && !isContainer && containsResult.nodes.length > 0) {
- const parentFile = containsResult.nodes[0] as any;
- if (parentFile?.id) {
- const parentPath = await getSystemPath(client, parentFile.id);
- if (hasMapData(parentPath)) effectiveSystemPath = parentPath;
- }
- }
-
// Diagnostic for missing map data
- const hasMap = hasMapData(effectiveSystemPath);
+ const hasMap = hasMapData(systemPath);
if (!hasMap) {
diagnostics.push("No system map. Run `ix map` to see hierarchy.");
}
// Build system path: append resolved symbol for non-file targets
- let systemPathMapped = effectiveSystemPath.map((n) => ({ name: n.name, kind: n.kind }));
+ let systemPathMapped = systemPath.map((n) => ({ name: n.name, kind: n.kind }));
if (!isFile) {
const lastInPath = systemPathMapped[systemPathMapped.length - 1];
if (!lastInPath || lastInPath.name !== target.name) {
diff --git a/ix-cli/src/cli/commands/overview.ts b/ix-cli/src/cli/commands/overview.ts
index ad758b35..f5199787 100644
--- a/ix-cli/src/cli/commands/overview.ts
+++ b/ix-cli/src/cli/commands/overview.ts
@@ -3,7 +3,7 @@ import type { Command } from "commander";
import { IxClient } from "../../client/api.js";
import { getEndpoint } from "../config.js";
import { resolveFileOrEntity, printResolved } from "../resolve.js";
-import { getSystemPath, hasMapData } from "../hierarchy.js";
+import { getEffectiveSystemPath, getSystemPath, hasMapData } from "../hierarchy.js";
import { humanizeLabel } from "../impact/risk-semantics.js";
import { relativePath } from "../format.js";
import { renderSection, renderKeyValue, renderNote, renderBreadcrumb } from "../ui.js";
@@ -226,7 +226,7 @@ async function overviewLeaf(
// Fetch entity details, system path, and parent container in parallel
const [details, systemPath, parentResult] = await Promise.all([
client.entity(target.id),
- getSystemPath(client, target.id),
+ getEffectiveSystemPath(client, target.id),
client.expand(target.id, { direction: "in", predicates: ["CONTAINS"] }),
]);
diff --git a/ix-cli/src/cli/commands/search.ts b/ix-cli/src/cli/commands/search.ts
index 22e87e93..14c9bceb 100644
--- a/ix-cli/src/cli/commands/search.ts
+++ b/ix-cli/src/cli/commands/search.ts
@@ -159,6 +159,7 @@ Examples:
name: s.node.name || (s.node.attrs as any)?.name || "(unnamed)",
kind: s.node.kind,
path: relativePath(s.node.provenance?.sourceUri) ?? undefined,
+ language: (s.node.attrs as any)?.language ?? undefined,
rank: i + 1,
tier: s.rank.tier,
score: s.rank.score,
diff --git a/ix-cli/src/cli/commands/trace.ts b/ix-cli/src/cli/commands/trace.ts
index 6ff8427a..f47d98cd 100644
--- a/ix-cli/src/cli/commands/trace.ts
+++ b/ix-cli/src/cli/commands/trace.ts
@@ -2,9 +2,9 @@ import type { Command } from "commander";
import chalk from "chalk";
import { IxClient } from "../../client/api.js";
import { getEndpoint } from "../config.js";
-import { resolveFileOrEntity, isRawId } from "../resolve.js";
+import { resolveFileOrEntity, isRawId } from "../resolve.js";
+import type { ResolvedEntity } from "../resolve.js";
import { stderr } from "../stderr.js";
-import { buildDependencyTree } from "./depends.js";
import { renderSection, renderKeyValue, renderResolvedHeader, colorizeKind } from "../ui.js";
import { compactTreeNode, relativePath } from "../format.js";
@@ -33,19 +33,114 @@ const MAX_NODES = Infinity;
// ── Helpers ──────────────────────────────────────────────────────────
-const ALL_PREDICATES = ["CALLS", "IMPORTS", "REFERENCES", "EXTENDS", "IMPLEMENTS"];
+const ALL_PREDICATES = ["CALLS", "IMPORTS", "REFERENCES", "EXTENDS", "IMPLEMENTS", "CONTAINS"];
/** Map --kind flag to API predicates. If no kind specified, use all predicates (same as depends). */
-function kindToPredicates(kind?: string): string[] {
- if (!kind) return ALL_PREDICATES;
- switch (kind.toLowerCase()) {
- case "calls": return ["CALLS", "REFERENCES"];
- case "imports": return ["IMPORTS"];
- case "depends": return ["IMPORTS"];
- case "contains": return ["CONTAINS"];
- default: return ALL_PREDICATES;
- }
-}
+function kindToPredicates(kind?: string): string[] {
+ if (!kind) return ALL_PREDICATES;
+ switch (kind.toLowerCase()) {
+ case "calls": return ["CALLS", "REFERENCES"];
+ case "imports": return ["IMPORTS"];
+ case "depends": return ["IMPORTS"];
+ case "contains": return ["CONTAINS"];
+ default: return ALL_PREDICATES;
+ }
+}
+
+function isExactSymbolMatch(node: any, symbol: string): boolean {
+ const name = node?.name || node?.attrs?.name || "";
+ return name === symbol || String(name).toLowerCase() === symbol.toLowerCase();
+}
+
+async function traceEdgeScore(
+ client: IxClient,
+ nodeId: string,
+ direction: "upstream" | "downstream" | "both",
+ predicates: string[],
+): Promise<number> {
+ if (direction === "both") {
+ const [upstream, downstream] = await Promise.all([
+ client.expand(nodeId, { direction: "in", predicates, hops: 1 }),
+ client.expand(nodeId, { direction: "out", predicates, hops: 1 }),
+ ]);
+ return upstream.nodes.length + downstream.nodes.length;
+ }
+
+ const result = await client.expand(nodeId, {
+ direction: direction === "upstream" ? "in" : "out",
+ predicates,
+ hops: 1,
+ });
+ return result.nodes.length;
+}
+
+export async function pickTraceTarget(
+ client: IxClient,
+ symbol: string,
+ target: ResolvedEntity,
+ opts: {
+ direction: "upstream" | "downstream" | "both";
+ predicates: string[];
+ pick?: number;
+ path?: string;
+ },
+): Promise<ResolvedEntity> {
+ if (target.kind !== "config_entry") return target;
+ if (opts.path) return target;
+
+ const candidates = (await client.search(symbol, {
+ limit: 50,
+ kind: "config_entry",
+ nameOnly: true,
+ }))
+ .filter((node: any) => isExactSymbolMatch(node, symbol))
+ .filter((node: any, index: number, all: any[]) =>
+ all.findIndex((other: any) => other.id === node.id) === index,
+ );
+
+ if (candidates.length <= 1) return target;
+
+ const scored = await Promise.all(
+ candidates.map(async (node: any, index: number) => ({
+ node,
+ index,
+ score: await traceEdgeScore(client, node.id, opts.direction, opts.predicates),
+ })),
+ );
+
+ scored.sort((a, b) => {
+ if (a.score !== b.score) return b.score - a.score;
+ if (a.node.id === target.id) return -1;
+ if (b.node.id === target.id) return 1;
+ return a.index - b.index;
+ });
+
+ if (opts.pick !== undefined) {
+ const picked = scored[opts.pick - 1];
+ if (!picked) return target;
+ return {
+ id: picked.node.id,
+ kind: picked.node.kind,
+ name: picked.node.name || picked.node.attrs?.name || symbol,
+ path: picked.node.provenance?.sourceUri ?? picked.node.provenance?.source_uri ?? picked.node.path,
+ resolutionMode: "scored",
+ };
+ }
+
+ const current = scored.find((entry) => entry.node.id === target.id);
+ const best = scored[0];
+ if (!best) return target;
+ if ((current?.score ?? -1) >= best.score) return target;
+ if (best.score <= 0) return target;
+
+ return {
+ id: best.node.id,
+ kind: best.node.kind,
+ name: best.node.name || best.node.attrs?.name || symbol,
+ path: best.node.provenance?.sourceUri ?? best.node.provenance?.source_uri ?? best.node.path,
+ resolutionMode: "scored",
+ };
+}
// ── Tree traversal ───────────────────────────────────────────────────
@@ -368,8 +463,9 @@ export function registerTraceCommand(program: Command): void {
}
// ── Directional mode ────────────────────────────────────────
- const target = await resolveFileOrEntity(client, symbol, resolveOpts);
- if (!target) return;
+ const resolvedTarget = await resolveFileOrEntity(client, symbol, resolveOpts);
+ if (!resolvedTarget) return;
+ let target: ResolvedEntity = resolvedTarget;
const predicates = kindToPredicates(opts.kind);
const relKind = opts.kind ?? "mixed";
@@ -378,21 +474,22 @@ export function registerTraceCommand(program: Command): void {
const doUpstream = opts.upstream === true;
const doDownstream = opts.downstream === true;
const doBoth = !doUpstream && !doDownstream;
- const direction = doBoth ? "both" : doUpstream ? "upstream" : "downstream";
-
+ const direction = doBoth ? "both" : doUpstream ? "upstream" : "downstream";
+ target = await pickTraceTarget(client, symbol, target, {
+ direction,
+ predicates,
+ pick: opts.pick ? parseInt(opts.pick, 10) : undefined,
+ path: opts.path,
+ });
+
// upstream = "in" (who depends on this — same as depends)
// downstream = "out" (what this depends on — inverse of depends)
// ── Both: run up + down in parallel ────────────────────────
if (doBoth) {
const [upResult, downResult] = await Promise.all([
- buildDependencyTree(client, target.id, { maxDepth, maxNodes, predicates }),
- buildTraceTree(client, target.id, {
- direction: "out",
- predicates,
- maxDepth,
- maxNodes,
- }),
+ buildTraceTree(client, target.id, { direction: "in", predicates, maxDepth, maxNodes }),
+ buildTraceTree(client, target.id, { direction: "out", predicates, maxDepth, maxNodes }),
]);
// ── JSON ──────────────────────────────────────────────
@@ -465,7 +562,7 @@ export function registerTraceCommand(program: Command): void {
// ── Single direction ────────────────────────────────────────
const { tree, truncated, nodesVisited, maxDepthReached } = doUpstream
- ? await buildDependencyTree(client, target.id, { maxDepth, maxNodes, predicates })
+ ? await buildTraceTree(client, target.id, { direction: "in", predicates, maxDepth, maxNodes })
: await buildTraceTree(client, target.id, { direction: "out", predicates, maxDepth, maxNodes });
// ── JSON ────────────────────────────────────────────────────
diff --git a/ix-cli/src/cli/hierarchy.ts b/ix-cli/src/cli/hierarchy.ts
index e95abe70..3a59671f 100644
--- a/ix-cli/src/cli/hierarchy.ts
+++ b/ix-cli/src/cli/hierarchy.ts
@@ -3,6 +3,7 @@ import type { IxClient } from "../client/api.js";
export type SystemPath = Array<{ name: string; kind: string; id?: string }>;
const REGION_KINDS = new Set(["system", "subsystem", "module", "region"]);
+const FILE_KINDS = new Set(["file"]);
/** Traverse IN_REGION edges upward to build the system-hierarchy path for a node. */
export async function getSystemPath(client: IxClient, nodeId: string): Promise<SystemPath> {
@@ -37,6 +38,62 @@ export function hasMapData(path: SystemPath): boolean {
return path.some((n) => REGION_KINDS.has(n.kind));
}
+/**
+ * Return the best system path available for a node.
+ * Some nested entities do not carry IN_REGION edges directly and must inherit
+ * map context from a containing ancestor, typically the enclosing file.
+ */
+export async function getEffectiveSystemPath(
+ client: IxClient,
+ nodeId: string,
+ opts?: { maxContainsHops?: number }
+): Promise<SystemPath> {
+ const directPath = await getSystemPath(client, nodeId);
+ if (hasMapData(directPath)) return directPath;
+
+ const maxContainsHops = opts?.maxContainsHops ?? 8;
+ const visited = new Set<string>([nodeId]);
+ let frontier: Array<{ id: string; kind?: string }> = [{ id: nodeId }];
+
+ for (let depth = 0; depth < maxContainsHops; depth += 1) {
+ const nextLevel: Array<{ id: string; kind?: string }> = [];
+
+ for (const current of frontier) {
+ try {
+ const result = await client.expand(current.id, {
+ direction: "in",
+ predicates: ["CONTAINS"],
+ hops: 1,
+ });
+
+ const parents = (result.nodes as Array<{ id: string; kind?: string }>).filter(
+ (node) => node?.id && !visited.has(node.id)
+ );
+
+ const prioritized = [...parents].sort((a, b) => {
+ const aRank = FILE_KINDS.has(a.kind ?? "") ? 0 : 1;
+ const bRank = FILE_KINDS.has(b.kind ?? "") ? 0 : 1;
+ return aRank - bRank;
+ });
+
+ for (const parent of prioritized) {
+ visited.add(parent.id);
+ const parentPath = await getSystemPath(client, parent.id);
+ if (hasMapData(parentPath)) return parentPath;
+ nextLevel.push(parent);
+ }
+ } catch {
+ // Ignore lookup failures and keep climbing through any remaining nodes.
+ }
+ }
+
+ if (nextLevel.length === 0) break;
+ frontier = nextLevel;
+ }
+
+ return directPath;
+}
+
/** Group a set of node IDs by their containing region (IN_REGION). */
export async function bucketByHierarchy(
client: IxClient,
diff --git a/memory-layer/src/main/scala/ix/memory/map/MapGraphBuilder.scala b/memory-layer/src/main/scala/ix/memory/map/MapGraphBuilder.scala
index 53441ca8..55a1d1d1 100644
--- a/memory-layer/src/main/scala/ix/memory/map/MapGraphBuilder.scala
+++ b/memory-layer/src/main/scala/ix/memory/map/MapGraphBuilder.scala
@@ -130,10 +130,11 @@ class MapGraphBuilder(client: ArangoClient) {
* Returns file nodes using provenance.source_uri as the path key.
* Files without source_uri are skipped (unusual but defensive).
*/
- // Source-code extensions to include in the architectural map.
- // Docs (.md), scripts (.sh), config (.yml/.json/.toml) etc. are excluded.
+ // Source-like artifacts to include in the architectural map.
+ // JSON and common config formats are included so data-heavy repos can still
+ // receive file-level singleton regions even when they have little coupling.
private val SourceExtensions =
- Set("scala","java","kt","ts","tsx","js","jsx","py","go","rs","cs","cpp","c","h","hpp","rb")
+ Set("scala","java","kt","ts","tsx","js","jsx","py","go","rs","cs","cpp","c","h","hpp","rb","json","yaml","yml","toml")
private def fetchFiles(): IO[Vector[FileVertex]] =
client.query(
diff --git a/memory-layer/src/main/scala/ix/memory/map/MapService.scala b/memory-layer/src/main/scala/ix/memory/map/MapService.scala
index a0638a65..05325b69 100644
--- a/memory-layer/src/main/scala/ix/memory/map/MapService.scala
+++ b/memory-layer/src/main/scala/ix/memory/map/MapService.scala
@@ -1047,18 +1047,31 @@ class MapService(
doc
}
- private def buildRegionEdgeDocs(
+ private[map] def buildRegionEdgeDocs(
regions: Vector[Region],
newRev: Long,
now: String,
provMap: java.util.Map[String, AnyRef]
): Vector[java.util.Map[String, AnyRef]] = {
- val fileEdges = regions.filter(_.level == 1).flatMap { r =>
- r.memberFiles.toVector.map { fileId =>
- val edgeId = UUID.nameUUIDFromBytes(s"in_region:${r.id.value}:${fileId.value}".getBytes("UTF-8"))
- buildRegionEdgeDoc(edgeId.toString, s"nodes/${r.id.value}", s"nodes/${fileId.value}",
- r.id.value.toString, fileId.value.toString, newRev, now, provMap)
- }
+ val fileRegionById = regions
+ .flatMap(region => region.memberFiles.toVector.map(_ -> region))
+ .groupBy(_._1)
+ .view
+ .mapValues(_.map(_._2).minBy(region => (region.level, region.labelKind)))
+ .toMap
+
+ val fileEdges = fileRegionById.toVector.map { case (fileId, region) =>
+ val edgeId = UUID.nameUUIDFromBytes(s"in_region:${region.id.value}:${fileId.value}".getBytes("UTF-8"))
+ buildRegionEdgeDoc(
+ edgeId.toString,
+ s"nodes/${region.id.value}",
+ s"nodes/${fileId.value}",
+ region.id.value.toString,
+ fileId.value.toString,
+ newRev,
+ now,
+ provMap
+ )
}
val regionEdges = regions.flatMap { r =>
r.parentId.map { pid =>
diff --git a/memory-layer/src/test/scala/ix/memory/map/MapServiceScopeSpec.scala b/memory-layer/src/test/scala/ix/memory/map/MapServiceScopeSpec.scala
index 5a054b31..175ac4e7 100644
--- a/memory-layer/src/test/scala/ix/memory/map/MapServiceScopeSpec.scala
+++ b/memory-layer/src/test/scala/ix/memory/map/MapServiceScopeSpec.scala
@@ -97,6 +97,58 @@ class MapServiceScopeSpec extends AnyFlatSpec with Matchers {
completed.find(_.memberFiles == Set(fileB.id)).map(_.labelKind) shouldBe Some("module")
}
+ it should "emit exactly one edge when a file belongs to multiple level-1 regions" in {
+ val file = NodeId(UUID.randomUUID())
+ val moduleId = NodeId(UUID.randomUUID())
+ val subsystemId = NodeId(UUID.randomUUID())
+
+ // Both regions are level 1 — old code emitted two IN_REGION edges; new code emits one.
+ val moduleRegion = regionWithMembers("Lib", "module", 1, moduleId, Set(file))
+ val subsystemRegion = regionWithMembers("Lib", "subsystem", 1, subsystemId, Set(file))
+
+ val edgeDocs = service.buildRegionEdgeDocs(
+ regions = Vector(moduleRegion, subsystemRegion),
+ newRev = 42L,
+ now = "2026-04-01T00:00:00Z",
+ provMap = new java.util.HashMap[String, AnyRef]()
+ )
+
+ val fileEdges = edgeDocs.filter(_.get("dst").toString == file.value.toString)
+
+ // Exactly one edge — no duplicates from the two level-1 regions.
+ fileEdges should have length 1
+ // "module" sorts before "subsystem" so the module region wins.
+ fileEdges.head.get("src").toString shouldBe moduleId.value.toString
+ }
+
+ "buildRegionEdgeDocs" should "attach files to their most specific surviving region" in {
+ val fileA = NodeId(UUID.randomUUID())
+ val fileB = NodeId(UUID.randomUUID())
+ val sharedRegionId = NodeId(UUID.randomUUID())
+ val childRegionId = NodeId(UUID.randomUUID())
+ val systemRegionId = NodeId(UUID.randomUUID())
+
+ val module = regionWithMembers("Dist", "module", 1, childRegionId, Set(fileA))
+ val system = regionWithMembers("Countries", "system", 2, systemRegionId, Set(fileA, fileB))
+ val collapsedSystem = regionWithMembers("Countries", "system", 2, sharedRegionId, Set(fileA))
+
+ val edgeDocs = service.buildRegionEdgeDocs(
+ regions = Vector(system, collapsedSystem, module),
+ newRev = 42L,
+ now = "2026-04-01T00:00:00Z",
+ provMap = new java.util.HashMap[String, AnyRef]()
+ )
+
+ val fileEdges = edgeDocs.filter { doc =>
+ val dst = doc.get("dst").toString
+ dst == fileA.value.toString || dst == fileB.value.toString
+ }
+ val fileEdgeByDst = fileEdges.map(doc => doc.get("dst").toString -> doc.get("src").toString).toMap
+
+ fileEdgeByDst(fileA.value.toString) shouldBe childRegionId.value.toString
+ fileEdgeByDst(fileB.value.toString) shouldBe systemRegionId.value.toString
+ }
+
private def fileVertex(path: String): FileVertex =
FileVertex(NodeId(UUID.randomUUID()), path)