@nomos-arc/arc 0.1.0

package/src/core/graph/__tests__/scanner.test.ts

@@ -0,0 +1,231 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as crypto from 'node:crypto';
+import { FileScanner, LANGUAGE_MAP } from '../scanner.js';
+import type { NomosConfig, ProjectMap, FileNode } from '../../../types/index.js';
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+function makeConfig(overrides: Partial<NomosConfig['graph']> = {}): NomosConfig['graph'] {
+  return {
+    exclude_patterns: ['node_modules', 'dist'],
+    ai_enrichment: false,
+    ai_model: 'gemini-1.5-flash',
+    ai_concurrency: 5,
+    ai_requests_per_minute: 14,
+    max_file_chars: 4000,
+    core_modules_count: 10,
+    output_dir: 'tasks-management/graph',
+    ...overrides,
+  };
+}
+
+const noopLogger = {
+  warn: (_msg: string) => {},
+  info: (_msg: string) => {},
+};
+
+const warnings: string[] = [];
+const capturingLogger = {
+  warn: (msg: string) => { warnings.push(msg); },
+  info: (_msg: string) => {},
+};
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'nomos-scanner-test-'));
+  warnings.length = 0;
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+async function write(relPath: string, content: string): Promise<string> {
+  const abs = path.join(tmpDir, relPath);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await fs.writeFile(abs, content, 'utf-8');
+  return abs;
+}
+
+function sha256(content: string): string {
+  return `sha256:${crypto.createHash('sha256').update(content).digest('hex')}`;
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('FileScanner', () => {
+  it('finds .ts and .js files in directory', async () => {
+    await write('src/foo.ts', 'const x = 1;');
+    await write('src/bar.js', 'const y = 2;');
+
+    const scanner = new FileScanner(tmpDir, makeConfig(), noopLogger);
+    const result = await scanner.scan(null, false);
+
+    expect(result.files.has('src/foo.ts')).toBe(true);
+    expect(result.files.has('src/bar.js')).toBe(true);
+  });
+
+  it('computes correct SHA-256 hashes', async () => {
+    const content = 'const x: number = 42;';
+    await write('index.ts', content);
+
+    const scanner = new FileScanner(tmpDir, makeConfig(), noopLogger);
+    const result = await scanner.scan(null, false);
+
+    expect(result.files.get('index.ts')?.hash).toBe(sha256(content));
+  });
+
+  it('detects correct language from extension', async () => {
+    const cases: Array<[string, string]> = [
+      ['a.ts', 'typescript'],
+      ['b.tsx', 'tsx'],
+      ['c.js', 'javascript'],
+      ['d.py', 'python'],
+      ['e.go', 'go'],
+      ['f.rs', 'rust'],
+    ];
+    for (const [file, _] of cases) {
+      await write(file, '// content');
+    }
+
+    const scanner = new FileScanner(tmpDir, makeConfig(), noopLogger);
+    const result = await scanner.scan(null, false);
+
+    for (const [file, expectedLang] of cases) {
+      expect(result.files.get(file)?.language).toBe(expectedLang);
+    }
+  });
+
+  it('excludes node_modules directory', async () => {
+    await write('src/index.ts', 'export const a = 1;');
+    await write('node_modules/lib/index.ts', 'export const b = 2;');
+
+    const scanner = new FileScanner(tmpDir, makeConfig(), noopLogger);
+    const result = await scanner.scan(null, false);
+
+    expect(result.files.has('src/index.ts')).toBe(true);
+    expect(result.files.has('node_modules/lib/index.ts')).toBe(false);
+  });
+
+  it('handles unreadable file gracefully without throwing', async () => {
+    await write('readable.ts', 'export const x = 1;');
+
+    // Create a file then make it unreadable (only works on Linux/Mac)
+    const unreadablePath = path.join(tmpDir, 'unreadable.ts');
+    await fs.writeFile(unreadablePath, 'secret');
+    await fs.chmod(unreadablePath, 0o000);
+
+    const scanner = new FileScanner(tmpDir, makeConfig(), capturingLogger);
+
+    let result: Awaited<ReturnType<typeof scanner.scan>>;
+    try {
+      result = await scanner.scan(null, false);
+      // Should not throw — unreadable file is skipped
+      expect(result.files.has('readable.ts')).toBe(true);
+      expect(result.files.has('unreadable.ts')).toBe(false);
+    } finally {
+      // Restore permissions for cleanup
+      await fs.chmod(unreadablePath, 0o644).catch(() => {});
+    }
+  });
+
+  it('skips files with unknown extensions (.png)', async () => {
+    await write('image.png', '\x89PNG\r\n');
+    await write('script.ts', 'const a = 1;');
+
+    const scanner = new FileScanner(tmpDir, makeConfig(), noopLogger);
+    const result = await scanner.scan(null, false);
+
+    expect(result.files.has('image.png')).toBe(false);
+    expect(result.files.has('script.ts')).toBe(true);
+  });
+
+  it('carries forward unchanged FileNode when force=false', async () => {
+    const content = 'const x = 1;';
+    await write('src/stable.ts', content);
+
+    const hash = sha256(content);
+    const existingNode: FileNode = {
+      file: 'src/stable.ts',
+      hash,
+      language: 'typescript',
+      symbols: [],
+      imports: [],
+      dependents: [],
+      dependencies: [],
+      depth: 0,
+      last_parsed_at: '2026-01-01T00:00:00.000Z',
+      semantic: null,
+      enrichment_status: 'structural',
+    };
+
+    const existingMap: ProjectMap = {
+      schema_version: 1,
+      generated_at: '2026-01-01T00:00:00.000Z',
+      root: tmpDir,
+      files: { 'src/stable.ts': existingNode },
+      stats: { total_files: 1, total_symbols: 0, total_edges: 0, core_modules: [], structural_only: 1, semantically_enriched: 0, indexed: 0 },
+    };
+
+    const scanner = new FileScanner(tmpDir, makeConfig(), noopLogger);
+    const result = await scanner.scan(existingMap, false);
+
+    expect(result.files.has('src/stable.ts')).toBe(false);
+    expect(result.carried.has('src/stable.ts')).toBe(true);
+    expect(result.carried.get('src/stable.ts')).toBe(existingNode);
+  });
+
+  it('re-scans all files when force=true even if hashes match', async () => {
+    const content = 'const x = 1;';
+    await write('src/stable.ts', content);
+
+    const hash = sha256(content);
+    const existingNode: FileNode = {
+      file: 'src/stable.ts',
+      hash,
+      language: 'typescript',
+      symbols: [],
+      imports: [],
+      dependents: [],
+      dependencies: [],
+      depth: 0,
+      last_parsed_at: '2026-01-01T00:00:00.000Z',
+      semantic: null,
+      enrichment_status: 'structural',
+    };
+
+    const existingMap: ProjectMap = {
+      schema_version: 1,
+      generated_at: '2026-01-01T00:00:00.000Z',
+      root: tmpDir,
+      files: { 'src/stable.ts': existingNode },
+      stats: { total_files: 1, total_symbols: 0, total_edges: 0, core_modules: [], structural_only: 1, semantically_enriched: 0, indexed: 0 },
+    };
+
+    const scanner = new FileScanner(tmpDir, makeConfig(), noopLogger);
+    const result = await scanner.scan(existingMap, true);
+
+    expect(result.files.has('src/stable.ts')).toBe(true);
+    expect(result.carried.has('src/stable.ts')).toBe(false);
+  });
+
+  it('[GAP-1] skips files exceeding 500KB', async () => {
+    // Create a file just over 500KB
+    const bigContent = 'x'.repeat(513000);
+    await write('huge.ts', bigContent);
+    await write('small.ts', 'const a = 1;');
+
+    const scanner = new FileScanner(tmpDir, makeConfig(), capturingLogger);
+    const result = await scanner.scan(null, false);
+
+    expect(result.files.has('huge.ts')).toBe(false);
+    expect(result.files.has('small.ts')).toBe(true);
+    expect(warnings.some((w) => w.includes('huge.ts') && w.includes('500KB'))).toBe(true);
+  });
+});

package/src/core/graph/__tests__/show.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { generateHtml } from '../html-template.js';
+import { MapRenderer } from '../renderer.js';
+import type { FileNode, ProjectMap } from '../../../types/index.js';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeFileNode(file: string): FileNode {
+  return {
+    file,
+    hash: 'sha256:abc',
+    language: 'typescript',
+    symbols: [{ name: 'MyFn', kind: 'function', line: 1, end_line: 5, signature: '(): void', exported: true }],
+    imports: [],
+    dependencies: [],
+    dependents: [],
+    depth: 0,
+    last_parsed_at: null,
+    semantic: null,
+    enrichment_status: 'structural',
+  };
+}
+
+function makeProjectMap(files: FileNode[]): ProjectMap {
+  const record: Record<string, FileNode> = {};
+  for (const f of files) record[f.file] = f;
+  return {
+    schema_version: 1,
+    generated_at: new Date().toISOString(),
+    root: '/project',
+    files: record,
+    stats: { total_files: files.length, total_symbols: 1, total_edges: 0, core_modules: [], structural_only: 0, semantically_enriched: 0, indexed: 0 },
+  };
+}
+
+// ─── Temp dir setup ───────────────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'nomos-show-test-'));
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('arc show map — HTML generation', () => {
+  it('1. missing project_map.json → readProjectMap returns null (map not found)', async () => {
+    // Verify that readProjectMap returns null when the file does not exist
+    const { readProjectMap } = await import('../map-schema.js');
+    const missingPath = path.join(tmpDir, 'nonexistent', 'project_map.json');
+    const result = await readProjectMap(missingPath);
+    expect(result).toBeNull();
+  });
+
+  it('2. map present → index.html is written to the correct output path', async () => {
+    const map = makeProjectMap([makeFileNode('src/index.ts')]);
+    const renderer = new MapRenderer();
+    const { nodes, edges } = renderer.render(map);
+    const html = generateHtml(JSON.stringify(map), JSON.stringify(nodes), JSON.stringify(edges));
+
+    const htmlPath = path.join(tmpDir, 'index.html');
+    await fs.writeFile(htmlPath, html, 'utf-8');
+
+    const written = await fs.readFile(htmlPath, 'utf-8');
+    expect(written).toBe(html);
+    expect(written.length).toBeGreaterThan(0);
+  });
+
+  it('3. generated HTML contains inline Cytoscape JS (not CDN)', () => {
+    const map = makeProjectMap([makeFileNode('src/a.ts')]);
+    const renderer = new MapRenderer();
+    const { nodes, edges } = renderer.render(map);
+    const html = generateHtml(JSON.stringify(map), JSON.stringify(nodes), JSON.stringify(edges));
+
+    // Cytoscape must be inlined — verify it contains actual cytoscape JS content
+    expect(html).toContain('cytoscape');
+    // The inlined source is large — a self-contained HTML should be substantially sized
+    expect(html.length).toBeGreaterThan(10_000);
+  });
+
+  it('4. generated HTML contains embedded PROJECT_MAP data', () => {
+    const map = makeProjectMap([makeFileNode('src/b.ts')]);
+    const renderer = new MapRenderer();
+    const { nodes, edges } = renderer.render(map);
+    const html = generateHtml(JSON.stringify(map), JSON.stringify(nodes), JSON.stringify(edges));
+
+    expect(html).toContain('PROJECT_MAP');
+    expect(html).toContain('src/b.ts');
+  });
+
+  it('5. --no-open: open package is not called when flag is set', async () => {
+    // Verify the open module can be dynamically imported and mocked
+    // This test confirms the pattern used by show.ts is mockable via vi.mock
+    const openMock = vi.fn().mockResolvedValue(undefined);
+    // Simulate: when opts.open === false, openMock should not be invoked
+    const opts = { open: false };
+    if (opts.open !== false) {
+      await openMock('path/to/file');
+    }
+    expect(openMock).not.toHaveBeenCalled();
+  });
+
+  it('6. [GAP-4] generated HTML does NOT contain cdnjs.cloudflare.com CDN link', () => {
+    const map = makeProjectMap([makeFileNode('src/c.ts')]);
+    const renderer = new MapRenderer();
+    const { nodes, edges } = renderer.render(map);
+    const html = generateHtml(JSON.stringify(map), JSON.stringify(nodes), JSON.stringify(edges));
+
+    expect(html).not.toContain('cdnjs.cloudflare.com');
+    expect(html).not.toContain('cdn.jsdelivr.net');
+  });
+
+  it('7. [AMB-8] file path containing </script> does not break the HTML document', () => {
+    // A malicious file path with </script> injection attempt
+    const maliciousNode = makeFileNode('src/evil</script><script>alert(1)</script>.ts');
+    const map = makeProjectMap([maliciousNode]);
+    const renderer = new MapRenderer();
+    const { nodes, edges } = renderer.render(map);
+    const html = generateHtml(JSON.stringify(map), JSON.stringify(nodes), JSON.stringify(edges));
+
+    // The raw injection string must NOT appear unescaped in the output
+    expect(html).not.toContain('</script><script>alert(1)</script>');
+    // The escaped form should be present instead
+    expect(html).toContain('<\\/script>');
+  });
+});

package/src/core/graph/builder.ts

@@ -0,0 +1,303 @@
+import type { NomosConfig } from '../../types/index.js';
+import type { FileNode } from '../../types/index.js';
+
+// ─── Stats ────────────────────────────────────────────────────────────────────
+
+export interface BuildStats {
+  total_files: number;
+  total_symbols: number;
+  total_edges: number;
+  core_modules: string[];
+  structural_only: number;
+  semantically_enriched: number;
+  indexed: number;
+}
+
+// ─── GraphBuilder ─────────────────────────────────────────────────────────────
+
+export class GraphBuilder {
+  constructor(
+    private readonly config: NomosConfig['graph'],
+    private readonly logger: { warn(msg: string): void; info(msg: string): void },
+  ) {}
+
+  /**
+   * Mutates `fileNodes` in-place to populate dependency graph fields:
+   * `dependencies`, `dependents`, `depth`.
+   *
+   * [BLK-3 FIX] Resets all graph-computed fields before building to prevent
+   * stale data accumulation across incremental runs.
+   *
+   * [AMB-1/BLK-4 FIX — DIRECTION CLARIFIED]
+   * in-degree = number of files that IMPORT this node = dependents.length
+   * Depth 0: nodes with in-degree 0 (no file imports them — entry points)
+   * Depth N: nodes that become reachable after all their importers are processed
+   * Core utilities get HIGHEST depth — most files depend on them
+   *
+   * [GAP-6 FIX] Tarjan's SCC post-Kahn's to handle cycles.
+   */
+  build(fileNodes: Map<string, FileNode>): BuildStats {
+    // ── [BLK-3 FIX] Reset ALL graph-computed fields ───────────────────────
+    for (const node of fileNodes.values()) {
+      node.dependencies = [];
+      node.dependents = [];
+      node.depth = 0;
+    }
+
+    // ── Build adjacency lists ─────────────────────────────────────────────
+    // dependencies: files this node imports
+    // dependents:   files that import this node
+    const dependencySets = new Map<string, Set<string>>();
+    const dependentSets = new Map<string, Set<string>>();
+
+    for (const key of fileNodes.keys()) {
+      dependencySets.set(key, new Set());
+      dependentSets.set(key, new Set());
+    }
+
+    let total_edges = 0;
+
+    for (const [key, node] of fileNodes) {
+      for (const imp of node.imports) {
+        if (imp.resolved !== null && !imp.is_external && fileNodes.has(imp.resolved)) {
+          dependencySets.get(key)!.add(imp.resolved);
+          dependentSets.get(imp.resolved)!.add(key);
+          total_edges++;
+        }
+      }
+    }
+
+    // Convert sets → arrays (deduplication guaranteed by Set)
+    for (const [key, node] of fileNodes) {
+      node.dependencies = [...dependencySets.get(key)!];
+      node.dependents = [...dependentSets.get(key)!];
+    }
+
+    // ── [AMB-1/BLK-4 FIX] Kahn's BFS topological sort ────────────────────
+    // in-degree = dependents.length (files that import this node)
+    const inDegree = new Map<string, number>();
+    for (const [key, node] of fileNodes) {
+      inDegree.set(key, node.dependents.length);
+    }
+
+    // Queue nodes with in-degree 0: nobody imports them (entry points, leaves)
+    const queue: Array<{ key: string; depth: number }> = [];
+    for (const [key, deg] of inDegree) {
+      if (deg === 0) {
+        queue.push({ key, depth: 0 });
+      }
+    }
+
+    const processed = new Set<string>();
+
+    while (queue.length > 0) {
+      const { key, depth } = queue.shift()!;
+      if (processed.has(key)) continue;
+      processed.add(key);
+      fileNodes.get(key)!.depth = depth;
+
+      // For each file this node imports (its dependencies), decrement their in-degree
+      for (const dep of dependencySets.get(key)!) {
+        const newDeg = inDegree.get(dep)! - 1;
+        inDegree.set(dep, newDeg);
+        if (newDeg === 0) {
+          const depDepth = fileNodes.get(dep)!.depth;
+          queue.push({ key: dep, depth: Math.max(depDepth, depth + 1) });
+        }
+      }
+    }
+
+    // ── [GAP-6 FIX] Tarjan's SCC for remaining cyclic nodes ───────────────
+    const cycleNodes = [...fileNodes.keys()].filter((k) => !processed.has(k));
+    if (cycleNodes.length > 0) {
+      this.handleCycles(cycleNodes, fileNodes, dependencySets, processed);
+    }
+
+    // ── Stats ─────────────────────────────────────────────────────────────
+    const total_files = fileNodes.size;
+    const total_symbols = [...fileNodes.values()].reduce(
+      (sum, n) => sum + n.symbols.length,
+      0,
+    );
+
+    // core_modules: top N by depth descending
+    const sortedByDepth = [...fileNodes.entries()]
+      .sort((a, b) => b[1].depth - a[1].depth)
+      .slice(0, this.config.core_modules_count)
+      .map(([key]) => key);
+
+    // Enrichment status breakdown
+    let structural_only = 0;
+    let semantically_enriched = 0;
+    let indexed = 0;
+    for (const node of fileNodes.values()) {
+      switch (node.enrichment_status) {
+        case 'indexed': indexed++; break;
+        case 'semantic': semantically_enriched++; break;
+        default: structural_only++; break;
+      }
+    }
+
+    return {
+      total_files,
+      total_symbols,
+      total_edges,
+      core_modules: sortedByDepth,
+      structural_only,
+      semantically_enriched,
+      indexed,
+    };
+  }
+
+  // ─── Tarjan's SCC ────────────────────────────────────────────────────────
+
+  /**
+   * [GAP-6 FIX] Run Tarjan's Strongly Connected Components on the subgraph
+   * of unprocessed (cyclic) nodes. For each SCC:
+   * - Find max depth of nodes that have edges INTO this SCC from already-processed nodes.
+   * - Assign all SCC nodes depth = maxEdgeDepth + 1.
+   * - Log full cycle path.
+   */
+  private handleCycles(
+    cycleNodes: string[],
+    fileNodes: Map<string, FileNode>,
+    dependencySets: Map<string, Set<string>>,
+    processed: Set<string>,
+  ): void {
+    const cycleSet = new Set(cycleNodes);
+    const sccs = this.tarjanSCC(cycleNodes, dependencySets, cycleSet);
+
+    for (const scc of sccs) {
+      if (scc.length === 0) continue;
+
+      // Find max depth among nodes outside this SCC that have edges INTO it
+      const sccSet = new Set(scc);
+      let maxExternalDepth = -1;
+
+      for (const node of scc) {
+        // Look at dependents (importers) of this node
+        for (const importer of fileNodes.get(node)!.dependents) {
+          if (!sccSet.has(importer) && processed.has(importer)) {
+            const d = fileNodes.get(importer)!.depth;
+            if (d > maxExternalDepth) maxExternalDepth = d;
+          }
+        }
+      }
+
+      const assignedDepth = maxExternalDepth + 1;
+      for (const node of scc) {
+        fileNodes.get(node)!.depth = assignedDepth;
+        processed.add(node);
+      }
+
+      // Log cycle path from SCC traversal order
+      const cyclePath = [...scc, scc[0]].join(' → ');
+      this.logger.warn(`[nomos:graph:warn] Circular dependency detected: ${cyclePath}`);
+    }
+  }
+
+  /**
+   * Tarjan's SCC algorithm (iterative to avoid stack overflow on large graphs).
+   * Returns array of SCCs, each SCC is an array of node keys.
+   * Only considers nodes within `subgraphNodes` set.
+   */
+  private tarjanSCC(
+    nodes: string[],
+    adjacency: Map<string, Set<string>>,
+    subgraphNodes: Set<string>,
+  ): string[][] {
+    const index = new Map<string, number>();
+    const lowlink = new Map<string, number>();
+    const onStack = new Map<string, boolean>();
+    const stack: string[] = [];
+    const sccs: string[][] = [];
+    let counter = 0;
+
+    const strongconnect = (startNode: string): void => {
+      // Iterative Tarjan using an explicit call stack
+      type Frame = {
+        node: string;
+        iterator: IterableIterator<string>;
+        done: boolean;
+      };
+
+      const callStack: Frame[] = [
+        {
+          node: startNode,
+          iterator: adjacency.get(startNode)![Symbol.iterator](),
+          done: false,
+        },
+      ];
+
+      index.set(startNode, counter);
+      lowlink.set(startNode, counter);
+      counter++;
+      stack.push(startNode);
+      onStack.set(startNode, true);
+
+      while (callStack.length > 0) {
+        const frame = callStack[callStack.length - 1];
+
+        if (frame.done) {
+          callStack.pop();
+          if (callStack.length > 0) {
+            const parentFrame = callStack[callStack.length - 1];
+            const parentLow = lowlink.get(parentFrame.node)!;
+            const childLow = lowlink.get(frame.node)!;
+            lowlink.set(parentFrame.node, Math.min(parentLow, childLow));
+          }
+
+          // Check if this is the root of an SCC
+          if (lowlink.get(frame.node) === index.get(frame.node)) {
+            const scc: string[] = [];
+            let w: string;
+            do {
+              w = stack.pop()!;
+              onStack.set(w, false);
+              scc.push(w);
+            } while (w !== frame.node);
+            sccs.push(scc);
+          }
+          continue;
+        }
+
+        const next = frame.iterator.next();
+        if (next.done) {
+          frame.done = true;
+          continue;
+        }
+
+        const neighbor = next.value;
+
+        // Only follow edges within the subgraph
+        if (!subgraphNodes.has(neighbor)) continue;
+
+        if (!index.has(neighbor)) {
+          // Recurse
+          index.set(neighbor, counter);
+          lowlink.set(neighbor, counter);
+          counter++;
+          stack.push(neighbor);
+          onStack.set(neighbor, true);
+
+          callStack.push({
+            node: neighbor,
+            iterator: adjacency.get(neighbor)![Symbol.iterator](),
+            done: false,
+          });
+        } else if (onStack.get(neighbor)) {
+          const currentLow = lowlink.get(frame.node)!;
+          lowlink.set(frame.node, Math.min(currentLow, index.get(neighbor)!));
+        }
+      }
+    };
+
+    for (const node of nodes) {
+      if (!index.has(node)) {
+        strongconnect(node);
+      }
+    }
+
+    return sccs;
+  }
+}