@nomos-arc/arc 0.1.0

package/src/core/graph/parser.ts

@@ -0,0 +1,336 @@
+import Parser from 'web-tree-sitter';
+import { TS_WASM_PATH, TSX_WASM_PATH } from './grammar-paths.js';
+import type { SymbolEntry, ImportEntry } from '../../types/index.js';
+
+export interface ParseResult {
+  symbols: SymbolEntry[];
+  imports: ImportEntry[];
+}
+
+export class ASTParser {
+  private parser: Parser | null = null;
+  private tsLang: Parser.Language | null = null;
+  private tsxLang: Parser.Language | null = null;
+
+  // [BLK-1 FIX + WATCH-1] WASM-based init — no native .node bindings
+  async init(): Promise<void> {
+    await Parser.init();
+    this.parser = new Parser();
+    // Grammar paths resolved by grammar-paths.ts (Tier A: node_modules, Tier B/C: local)
+    this.tsLang  = await Parser.Language.load(TS_WASM_PATH);
+    this.tsxLang = await Parser.Language.load(TSX_WASM_PATH);
+  }
+
+  // [AMB-3 FIX] No CJS/ESM ambiguity — web-tree-sitter loads .wasm files uniformly
+  private selectLanguage(language: string): Parser.Language | null {
+    switch (language) {
+      case 'tsx':
+        return this.tsxLang;
+      case 'typescript':
+      case 'javascript':
+        return this.tsLang;
+      default:
+        return null;
+    }
+  }
+
+  parse(filePath: string, content: string, language: string): ParseResult {
+    if (!this.parser || !this.tsLang || !this.tsxLang) {
+      throw new Error('ASTParser not initialized. Call init() first.');
+    }
+
+    const lang = this.selectLanguage(language);
+    if (!lang) {
+      // Unsupported language — return empty result with debug log
+      return { symbols: [], imports: [] };
+    }
+
+    this.parser.setLanguage(lang);
+    const tree = this.parser.parse(content);
+
+    // Error-node threshold: if > 20% chars are ERROR nodes, return empty
+    const errorChars = this._countErrorChars(tree.rootNode);
+    if (content.length > 0 && errorChars / content.length > 0.20) {
+      return { symbols: [], imports: [] };
+    }
+
+    const symbols: SymbolEntry[] = [];
+    const imports: ImportEntry[] = [];
+
+    this._walk(tree.rootNode, content, symbols, imports, null, false);
+
+    return { symbols, imports };
+  }
+
+  // ─── Symbol & Import Extraction ─────────────────────────────────────────────
+
+  private _walk(
+    node: Parser.SyntaxNode,
+    source: string,
+    symbols: SymbolEntry[],
+    imports: ImportEntry[],
+    currentClass: string | null,
+    parentIsExport: boolean,
+  ): void {
+    const type = node.type;
+
+    switch (type) {
+      // ── Imports (Step 2.2) ──────────────────────────────────────────────────
+
+      case 'import_statement': {
+        const entry = this._extractImportStatement(node);
+        if (entry) imports.push(entry);
+        return; // no need to descend into import statements
+      }
+
+      case 'call_expression': {
+        const entry = this._extractRequireCall(node);
+        if (entry) imports.push(entry);
+        // still descend — require() may appear in nested expressions
+        break;
+      }
+
+      // ── Symbols ─────────────────────────────────────────────────────────────
+
+      case 'function_declaration': {
+        const sym = this._extractFunction(node, source, parentIsExport);
+        if (sym) symbols.push(sym);
+        return;
+      }
+
+      case 'lexical_declaration':
+      case 'variable_declaration': {
+        // Top-level `export const foo = () => ...` — check for arrow function
+        const isExported = parentIsExport || this._hasExportAncestor(node);
+        for (const child of node.children) {
+          if (child.type === 'variable_declarator') {
+            const nameNode = child.childForFieldName('name');
+            const valueNode = child.childForFieldName('value');
+            if (nameNode && valueNode && valueNode.type === 'arrow_function') {
+              symbols.push({
+                name: nameNode.text,
+                kind: 'function',
+                line: valueNode.startPosition.row + 1,
+                end_line: valueNode.endPosition.row + 1,
+                signature: this._arrowSignature(nameNode.text, valueNode, source),
+                exported: isExported,
+              });
+            } else if (nameNode && isExported) {
+              symbols.push({
+                name: nameNode.text,
+                kind: 'variable',
+                line: nameNode.startPosition.row + 1,
+                end_line: nameNode.endPosition.row + 1,
+                signature: null,
+                exported: true,
+              });
+            }
+            // Also descend into value for nested call_expressions (e.g. require())
+            if (valueNode && valueNode.type !== 'arrow_function') {
+              this._walk(valueNode, source, symbols, imports, currentClass, parentIsExport);
+            }
+          }
+        }
+        return;
+      }
+
+      case 'class_declaration': {
+        const nameNode = node.childForFieldName('name');
+        if (nameNode) {
+          const isExported = parentIsExport || this._hasExportAncestor(node);
+          symbols.push({
+            name: nameNode.text,
+            kind: 'class',
+            line: node.startPosition.row + 1,
+            end_line: node.endPosition.row + 1,
+            signature: `class ${nameNode.text}`,
+            exported: isExported,
+          });
+          // Descend into class body for methods, passing className
+          const body = node.childForFieldName('body');
+          if (body) {
+            for (const child of body.children) {
+              this._walk(child, source, symbols, imports, nameNode.text, false);
+            }
+          }
+        }
+        return;
+      }
+
+      case 'method_definition': {
+        const nameNode = node.childForFieldName('name');
+        if (nameNode && currentClass) {
+          const params = node.childForFieldName('parameters');
+          symbols.push({
+            name: `${currentClass}.${nameNode.text}`,
+            kind: 'method',
+            line: node.startPosition.row + 1,
+            end_line: node.endPosition.row + 1,
+            signature: `${nameNode.text}(${params ? params.text : ''})`,
+            exported: false,
+          });
+        }
+        return;
+      }
+
+      case 'interface_declaration': {
+        const nameNode = node.childForFieldName('name');
+        if (nameNode) {
+          symbols.push({
+            name: nameNode.text,
+            kind: 'interface',
+            line: node.startPosition.row + 1,
+            end_line: node.endPosition.row + 1,
+            signature: `interface ${nameNode.text}`,
+            exported: parentIsExport || this._hasExportAncestor(node),
+          });
+        }
+        return;
+      }
+
+      case 'type_alias_declaration': {
+        const nameNode = node.childForFieldName('name');
+        if (nameNode) {
+          symbols.push({
+            name: nameNode.text,
+            kind: 'type',
+            line: node.startPosition.row + 1,
+            end_line: node.endPosition.row + 1,
+            signature: `type ${nameNode.text}`,
+            exported: parentIsExport || this._hasExportAncestor(node),
+          });
+        }
+        return;
+      }
+
+      case 'enum_declaration': {
+        const nameNode = node.childForFieldName('name');
+        if (nameNode) {
+          symbols.push({
+            name: nameNode.text,
+            kind: 'enum',
+            line: node.startPosition.row + 1,
+            end_line: node.endPosition.row + 1,
+            signature: `enum ${nameNode.text}`,
+            exported: parentIsExport || this._hasExportAncestor(node),
+          });
+        }
+        return;
+      }
+
+      case 'export_statement': {
+        // Recurse into export children with parentIsExport=true
+        for (const child of node.children) {
+          this._walk(child, source, symbols, imports, currentClass, true);
+        }
+        return;
+      }
+    }
+
+    // Default: recurse into children
+    for (const child of node.children) {
+      this._walk(child, source, symbols, imports, currentClass, parentIsExport);
+    }
+  }
+
+  // ─── Import Extraction (Step 2.2) ────────────────────────────────────────────
+
+  private _extractImportStatement(node: Parser.SyntaxNode): ImportEntry | null {
+    // import_statement: `import { A, B } from './foo'` or `import foo from './foo'`
+    let source: string | null = null;
+    const symbolNames: string[] = [];
+
+    for (const child of node.children) {
+      if (child.type === 'string') {
+        source = child.text.replace(/^['"]|['"]$/g, '');
+      } else if (child.type === 'import_clause') {
+        for (const clause of child.children) {
+          if (clause.type === 'named_imports') {
+            for (const spec of clause.children) {
+              if (spec.type === 'import_specifier') {
+                const nameNode = spec.childForFieldName('name') ?? spec.children[0];
+                if (nameNode) symbolNames.push(nameNode.text);
+              }
+            }
+          }
+          // namespace import `* as foo` and default import: leave symbols empty
+        }
+      }
+    }
+
+    if (!source) return null;
+    return {
+      source,
+      resolved: null,
+      symbols: symbolNames,
+      is_external: false, // resolver corrects this later
+    };
+  }
+
+  private _extractRequireCall(node: Parser.SyntaxNode): ImportEntry | null {
+    // call_expression: `require('./foo')`
+    const calleeNode = node.childForFieldName('function');
+    if (!calleeNode || calleeNode.text !== 'require') return null;
+
+    const argsNode = node.childForFieldName('arguments');
+    if (!argsNode) return null;
+
+    for (const arg of argsNode.children) {
+      if (arg.type === 'string') {
+        const source = arg.text.replace(/^['"]|['"]$/g, '');
+        return {
+          source,
+          resolved: null,
+          symbols: [],
+          is_external: false,
+        };
+      }
+    }
+    return null;
+  }
+
+  // ─── Helpers ─────────────────────────────────────────────────────────────────
+
+  private _extractFunction(
+    node: Parser.SyntaxNode,
+    source: string,
+    parentIsExport: boolean,
+  ): SymbolEntry | null {
+    const nameNode = node.childForFieldName('name');
+    if (!nameNode) return null;
+    const params = node.childForFieldName('parameters');
+    const returnType = node.childForFieldName('return_type');
+    const sig = `function ${nameNode.text}(${params ? params.text : ''})${returnType ? ': ' + returnType.text : ''}`;
+    return {
+      name: nameNode.text,
+      kind: 'function',
+      line: node.startPosition.row + 1,
+      end_line: node.endPosition.row + 1,
+      signature: sig,
+      exported: parentIsExport || this._hasExportAncestor(node),
+    };
+  }
+
+  private _arrowSignature(name: string, node: Parser.SyntaxNode, source: string): string {
+    const params = node.childForFieldName('parameters');
+    return `const ${name} = (${params ? params.text.replace(/^\(|\)$/g, '') : ''}) =>`;
+  }
+
+  private _hasExportAncestor(node: Parser.SyntaxNode): boolean {
+    let cur: Parser.SyntaxNode | null = node.parent;
+    while (cur) {
+      if (cur.type === 'export_statement') return true;
+      cur = cur.parent;
+    }
+    return false;
+  }
+
+  private _countErrorChars(node: Parser.SyntaxNode): number {
+    if (node.type === 'ERROR') return node.text.length;
+    let total = 0;
+    for (const child of node.children) {
+      total += this._countErrorChars(child);
+    }
+    return total;
+  }
+}

package/src/core/graph/pipeline.ts

@@ -0,0 +1,209 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import lockfile from 'proper-lockfile';
+import pLimit from 'p-limit';
+import type { NomosConfig, FileNode, ProjectMap } from '../../types/index.js';
+import { readProjectMap } from './map-schema.js';
+import { FileScanner } from './scanner.js';
+import { ASTParser } from './parser.js';
+import { ImportResolver } from './resolver.js';
+import { GraphBuilder } from './builder.js';
+import { SemanticEnricher } from './enricher.js';
+import { AuthManager } from '../auth/manager.js';
+import { ContractWriter } from './contract-writer.js';
+
+// ─── Logger Interface ─────────────────────────────────────────────────────────
+
+interface Logger {
+  info(msg: string): void;
+  warn(msg: string): void;
+  error(msg: string): void;
+}
+
+// ─── PipelineResult ───────────────────────────────────────────────────────────
+
+export interface PipelineResult {
+  map: ProjectMap;
+  aiFailures: number;
+}
+
+// ─── MapPipeline ──────────────────────────────────────────────────────────────
+
+export class MapPipeline {
+  private readonly scanner: FileScanner;
+  private readonly builder: GraphBuilder;
+  private readonly resolver: ImportResolver;
+
+  constructor(
+    private readonly config: NomosConfig,
+    private readonly projectRoot: string,
+    private readonly logger: Logger,
+    private readonly authManager?: AuthManager | null,
+  ) {
+    this.scanner = new FileScanner(projectRoot, config.graph, logger);
+    this.builder = new GraphBuilder(config.graph, logger);
+    this.resolver = new ImportResolver(projectRoot, logger);
+  }
+
+  async run(options: {
+    noAi: boolean;
+    force: boolean;
+    patterns?: string[];
+  }): Promise<PipelineResult> {
+    const outputDir = path.resolve(this.projectRoot, this.config.graph.output_dir);
+    const mapPath = path.join(outputDir, 'project_map.json');
+
+    // ── a. Read existing map ───────────────────────────────────────────────────
+    const existingMap = await readProjectMap(mapPath);
+
+    // ── b. Scan ───────────────────────────────────────────────────────────────
+    const scanResult = await this.scanner.scan(existingMap, options.force, options.patterns);
+    const { files: newFiles, carried } = scanResult;
+
+    // ── c. Empty check ────────────────────────────────────────────────────────
+    if (newFiles.size === 0 && carried.size === 0) {
+      this.logger.warn('[nomos:graph:warn] No files found to map.');
+      const emptyMap: ProjectMap = {
+        schema_version: 1,
+        generated_at: new Date().toISOString(),
+        root: this.projectRoot,
+        files: {},
+        stats: { total_files: 0, total_symbols: 0, total_edges: 0, core_modules: [], structural_only: 0, semantically_enriched: 0, indexed: 0 },
+      };
+      return { map: emptyMap, aiFailures: 0 };
+    }
+
+    // ── d. Init ASTParser (WASM requires async initialization) ────────────────
+    const parser = new ASTParser();
+    await parser.init();
+
+    // ── e. Parse all new/changed files ────────────────────────────────────────
+    const parsedNodes = new Map<string, FileNode>();
+    for (const [relPath, entry] of newFiles) {
+      const parseResult = parser.parse(entry.file, entry.content, entry.language);
+      const node: FileNode = {
+        file: relPath,
+        hash: entry.hash,
+        language: entry.language,
+        symbols: parseResult.symbols,
+        imports: parseResult.imports,
+        dependents: [],
+        dependencies: [],
+        depth: 0,
+        last_parsed_at: new Date().toISOString(),
+        semantic: null,
+        enrichment_status: 'structural',
+      };
+      // Carry over semantic + enrichment_status if hash hasn't changed (incremental)
+      const existing = existingMap?.files[relPath];
+      if (existing?.semantic && existing.semantic.source_hash === entry.hash) {
+        node.semantic = existing.semantic;
+        node.enrichment_status = existing.enrichment_status ?? 'semantic';
+      }
+      parsedNodes.set(relPath, node);
+    }
+
+    // ── f. Merge parsed + carried (backfill enrichment_status for old maps) ──
+    const allFiles = new Map<string, FileNode>();
+    for (const [k, v] of carried) {
+      if (!v.enrichment_status) {
+        v.enrichment_status = v.semantic ? 'semantic' : 'structural';
+      }
+      allFiles.set(k, v);
+    }
+    for (const [k, v] of parsedNodes) allFiles.set(k, v);
+
+    // ── g. [WATCH-4] Build knownFiles BEFORE resolution ───────────────────────
+    const knownFiles = new Set<string>(allFiles.keys());
+
+    const resolveLimit = pLimit(8);
+    await Promise.all(
+      [...allFiles.values()].map(node =>
+        resolveLimit(async () => {
+          for (const imp of node.imports) {
+            const result = await this.resolver.resolve(imp.source, node.file, knownFiles);
+            imp.resolved = result.resolved;
+            imp.is_external = result.is_external;
+          }
+        }),
+      ),
+    );
+
+    // ── h. Build graph ────────────────────────────────────────────────────────
+    const stats = this.builder.build(allFiles);
+
+    // ── i. [GAP-2 FIX] Write intermediate map BEFORE AI enrichment ────────────
+    const intermediateMap: ProjectMap = {
+      schema_version: 1,
+      generated_at: new Date().toISOString(),
+      root: this.projectRoot,
+      files: Object.fromEntries(allFiles),
+      stats,
+    };
+    await this.writeMap(intermediateMap, mapPath);
+
+    let aiFailures = 0;
+
+    // ── j. AI enrichment ──────────────────────────────────────────────────────
+    if (!options.noAi && this.config.graph.ai_enrichment) {
+      // [GAP-3 FIX] Set up cancellation flag
+      const cancellation = { cancelled: false };
+      const sigintHandler = () => { cancellation.cancelled = true; };
+      process.on('SIGINT', sigintHandler);
+
+      try {
+        const enricher = await SemanticEnricher.create(
+          this.projectRoot, this.config.graph, this.logger, this.authManager,
+        );
+        aiFailures = await enricher.enrich(allFiles, cancellation);
+
+        const contractWriter = new ContractWriter(this.projectRoot, this.logger);
+        await contractWriter.writeContracts(allFiles);
+      } finally {
+        process.removeListener('SIGINT', sigintHandler);
+      }
+
+      // Write final map with enriched semantic data
+      const finalMap: ProjectMap = {
+        schema_version: 1,
+        generated_at: new Date().toISOString(),
+        root: this.projectRoot,
+        files: Object.fromEntries(allFiles),
+        stats,
+      };
+      await this.writeMap(finalMap, mapPath);
+
+      return { map: finalMap, aiFailures };
+    }
+
+    // ── l. Return result ──────────────────────────────────────────────────────
+    return { map: intermediateMap, aiFailures };
+  }
+
+  // ─── [BLK-2 FIX + WATCH-3] Atomic write with directory-level lock ────────────
+
+  private async writeMap(map: ProjectMap, mapPath: string): Promise<void> {
+    const outDir = path.dirname(mapPath);
+    await fs.mkdir(outDir, { recursive: true });
+
+    // Lock the DIRECTORY — works even when project_map.json doesn't exist yet.
+    // proper-lockfile creates a .lock file (e.g., tasks-management/graph/.project-map.lock)
+    // which serializes concurrent arc map invocations.
+    const release = await lockfile.lock(outDir, {
+      lockfilePath: path.join(outDir, '.project-map.lock'),
+      realpath: false,
+      retries: { retries: 10, minTimeout: 200, maxTimeout: 2000 },
+      stale: 60000, // 60s stale lock — enrichment writes can be slow
+    });
+
+    try {
+      const tmpPath = `${mapPath}.tmp`;
+      await fs.writeFile(tmpPath, JSON.stringify(map, null, 2), 'utf-8');
+      const fd = await fs.open(tmpPath, 'r+');
+      try { await fd.sync(); } finally { await fd.close(); }
+      await fs.rename(tmpPath, mapPath);
+    } finally {
+      await release();
+    }
+  }
+}

package/src/core/graph/renderer.ts

@@ -0,0 +1,92 @@
+import type { ProjectMap, FileNode } from '../../types/index.js';
+
+// ─── Cytoscape Data Types ─────────────────────────────────────────────────────
+
+export interface CytoscapeNode {
+  data: {
+    id: string;
+    label: string;
+    color: string;
+  } & FileNode;
+}
+
+export interface CytoscapeEdge {
+  data: {
+    id: string;
+    source: string;
+    target: string;
+  };
+}
+
+// ─── MapRenderer ─────────────────────────────────────────────────────────────
+
+export class MapRenderer {
+  /**
+   * Transforms a ProjectMap into Cytoscape.js-compatible nodes and edges.
+   */
+  render(map: ProjectMap): { nodes: CytoscapeNode[]; edges: CytoscapeEdge[] } {
+    const files = Object.values(map.files);
+    const maxDepth = files.reduce((max, f) => Math.max(max, f.depth), 0);
+
+    const nodes: CytoscapeNode[] = files.map((node) => ({
+      data: {
+        ...node,
+        id: node.file,
+        label: node.file.split('/').pop() ?? node.file,
+        color: this.computeColor(node.depth, maxDepth),
+      },
+    }));
+
+    const edges: CytoscapeEdge[] = [];
+    for (const node of files) {
+      for (const dep of node.dependencies) {
+        edges.push({
+          data: {
+            id: `${node.file}→${dep}`,
+            source: node.file,
+            target: dep,
+          },
+        });
+      }
+    }
+
+    return { nodes, edges };
+  }
+
+  /**
+   * Maps a depth value to a hex color along a three-stop gradient:
+   *   depth 0    → #a8d8ea  (cool blue)
+   *   mid depth  → #f9c784  (warm amber)
+   *   max depth  → #c0392b  (deep red)
+   */
+  computeColor(depth: number, maxDepth: number): string {
+    if (maxDepth === 0) return '#a8d8ea';
+
+    const t = Math.min(depth / maxDepth, 1); // 0..1
+
+    // Three color stops
+    const stops = [
+      { r: 0xa8, g: 0xd8, b: 0xea }, // #a8d8ea — blue
+      { r: 0xf9, g: 0xc7, b: 0x84 }, // #f9c784 — amber
+      { r: 0xc0, g: 0x39, b: 0x2b }, // #c0392b — red
+    ];
+
+    let r: number, g: number, b: number;
+
+    if (t <= 0.5) {
+      // Interpolate between blue and amber
+      const u = t / 0.5;
+      r = Math.round(stops[0].r + u * (stops[1].r - stops[0].r));
+      g = Math.round(stops[0].g + u * (stops[1].g - stops[0].g));
+      b = Math.round(stops[0].b + u * (stops[1].b - stops[0].b));
+    } else {
+      // Interpolate between amber and red
+      const u = (t - 0.5) / 0.5;
+      r = Math.round(stops[1].r + u * (stops[2].r - stops[1].r));
+      g = Math.round(stops[1].g + u * (stops[2].g - stops[1].g));
+      b = Math.round(stops[1].b + u * (stops[2].b - stops[1].b));
+    }
+
+    return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
+  }
+}