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/json support (#118)
josephismikhailadcf972be0c2
diff --git a/core-ingestion/src/__tests__/queries.json.test.ts b/core-ingestion/src/__tests__/queries.json.test.tsnew file mode 100644index 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.tsindex 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 availablereturn 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 | nif (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 grammarconst isTsx = filePath.endsWith('.tsx');diff --git a/core-ingestion/src/languages.ts b/core-ingestion/src/languages.tsindex 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.tsindex 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.jsonindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 detailsconst [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.tsindex 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 parallelconst [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.tsindex 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.tsindex 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.tsindex 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.scalaindex 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.scalaindex 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.scalaindex 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)