@nomos-arc/arc 0.1.0

package/src/core/graph/constraints.ts

@@ -0,0 +1,94 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { readProjectMap, migrateProjectMap } from './map-schema.js';
+import { NomosError } from '../errors.js';
+
+// ─── readArchitecturalConstraints ─────────────────────────────────────────────
+
+/**
+ * Reads `project_map.json` and builds an architectural constraints string
+ * describing what symbols from `contextFiles` are consumed by their dependents.
+ *
+ * Returns `null` if the map doesn't exist or no constraints are found.
+ *
+ * [AMB-7 FIX] Context file paths are normalized to project-root-relative
+ * forward-slash paths before map lookup — handles relative paths like
+ * `../src/core/state.ts` correctly.
+ */
+export async function readArchitecturalConstraints(
+  projectRoot: string,
+  outputDir: string,
+  contextFiles: string[],
+): Promise<string | null> {
+  // ── 1. Read project_map.json ───────────────────────────────────────────────
+  const mapPath = path.join(outputDir, 'project_map.json');
+  let raw: string;
+  try {
+    raw = await fs.readFile(mapPath, 'utf-8');
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw new NomosError(
+      'graph_parse_error',
+      `Failed to read project map at ${mapPath}: ${String(err)}`,
+    );
+  }
+
+  // ── 2. Parse with migrateProjectMap ───────────────────────────────────────
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  let map;
+  try {
+    map = migrateProjectMap(parsed);
+  } catch {
+    return null;
+  }
+
+  // ── 3. Collect constraints for each context file ──────────────────────────
+  const lines: string[] = [];
+
+  for (const contextFile of contextFiles) {
+    // [AMB-7 FIX] Normalize to project-root-relative forward-slash path
+    const normalizedPath = path.relative(projectRoot, path.resolve(projectRoot, contextFile))
+      .split(path.sep).join('/');
+
+    const fileNode = map.files[normalizedPath];
+    if (!fileNode) continue;
+
+    // ── 4. Collect dependents with non-null semantic ───────────────────────
+    const enrichedDependents = fileNode.dependents
+      .map(dep => map.files[dep])
+      .filter((dep): dep is NonNullable<typeof dep> => dep != null && dep.semantic !== null);
+
+    if (enrichedDependents.length === 0) continue;
+
+    // For each exported symbol in the context file, find which dependents consume it
+    for (const symbol of fileNode.symbols) {
+      if (!symbol.exported) continue;
+
+      const consumers = enrichedDependents.filter(dep =>
+        dep.imports.some(imp =>
+          imp.resolved === normalizedPath && imp.symbols.includes(symbol.name),
+        ),
+      );
+
+      if (consumers.length === 0) continue;
+
+      const consumerNames = consumers.map(c => c.file).join(', ');
+      const contract = consumers[0]?.semantic?.purpose ?? consumers[0]?.semantic?.overview ?? '';
+
+      lines.push(
+        `- ${normalizedPath} → symbol: ${symbol.signature ?? symbol.name}`,
+        `  Consumed by: ${consumerNames}`,
+        `  Contract: "${contract}"`,
+      );
+    }
+  }
+
+  if (lines.length === 0) return null;
+  return lines.join('\n');
+}

package/src/core/graph/contract-writer.ts

@@ -0,0 +1,93 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { FileNode } from '../../types/index.js';
+
+// ─── ContractWriter ───────────────────────────────────────────────────────────
+
+export class ContractWriter {
+  constructor(
+    private readonly projectRoot: string,
+    private readonly logger: {
+      info(msg: string): void;
+      debug?(msg: string): void;
+    },
+  ) {}
+
+  /**
+   * Writes `.semantic.md` files next to each source file that has been enriched.
+   * Skips files where `semantic === null`.
+   * Skips files where the existing `.semantic.md` already contains the current `source_hash`.
+   *
+   * [AMB-5 FIX] Creates parent directory before writing, even if it doesn't exist.
+   */
+  async writeContracts(fileNodes: Map<string, FileNode>): Promise<void> {
+    for (const fileNode of fileNodes.values()) {
+      if (fileNode.semantic === null) continue;
+
+      const sourcePath = path.join(this.projectRoot, fileNode.file);
+      const ext = path.extname(sourcePath);
+      const outputPath = ext
+        ? sourcePath.slice(0, -ext.length) + '.semantic.md'
+        : sourcePath + '.semantic.md';
+
+      // Overwrite skip: if existing file already contains current source_hash
+      try {
+        const existing = await fs.readFile(outputPath, 'utf-8');
+        if (existing.includes(fileNode.semantic.source_hash)) {
+          continue;
+        }
+      } catch (err: unknown) {
+        if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+        // File doesn't exist — proceed to write
+      }
+
+      // [AMB-5 FIX] Ensure parent directory exists before writing
+      await fs.mkdir(path.dirname(outputPath), { recursive: true });
+
+      const markdown = renderContract(fileNode);
+      await fs.writeFile(outputPath, markdown, 'utf-8');
+
+      this.logger.debug?.(
+        `[nomos:graph:debug] Wrote semantic contract: ${path.relative(this.projectRoot, outputPath)}`,
+      );
+    }
+  }
+}
+
+// ─── Template renderer ────────────────────────────────────────────────────────
+
+function renderContract(fileNode: FileNode): string {
+  const semantic = fileNode.semantic!;
+  const filename = path.basename(fileNode.file);
+
+  const keyLogicLines = semantic.key_logic
+    .map((item, i) => `${i + 1}. ${item}`)
+    .join('\n');
+
+  const usageContextLines = semantic.usage_context.map((item) => `- ${item}`).join('\n');
+
+  const dependentsList =
+    fileNode.dependents.length > 0 ? fileNode.dependents.join(', ') : '(none)';
+
+  return [
+    `# ${filename} — Semantic Contract`,
+    `> Auto-generated by \`arc map\` — do not edit manually.`,
+    '',
+    `## Overview`,
+    semantic.overview,
+    '',
+    `## Purpose`,
+    semantic.purpose,
+    '',
+    `## Key Logic`,
+    keyLogicLines,
+    '',
+    `## Usage Context`,
+    `Used by: ${dependentsList}`,
+    usageContextLines,
+    '',
+    '---',
+    `*Enriched at: ${semantic.enriched_at} | Model: ${semantic.model} | Hash: ${semantic.source_hash}*`,
+    '',
+  ].join('\n');
+}

package/src/core/graph/drift/__tests__/classifier.test.ts

@@ -0,0 +1,215 @@
+import { describe, it, expect } from 'vitest';
+import { classify } from '../classifier.js';
+import type { DriftReport } from '../../../../types/index.js';
+
+// ─── Fixture helpers ──────────────────────────────────────────────────────────
+
+function emptySummary(): DriftReport['summary'] {
+  return {
+    files_added: 0,
+    files_removed: 0,
+    files_modified: 0,
+    symbols_added: 0,
+    symbols_removed: 0,
+    symbols_changed: 0,
+    imports_added: 0,
+    imports_removed: 0,
+    depth_changes: 0,
+    stale_enrichments: 0,
+  };
+}
+
+function emptyReport(): DriftReport {
+  return {
+    files: [],
+    symbols: [],
+    imports: [],
+    graph: { depth_changes: [], core_modules_added: [], core_modules_removed: [] },
+    stale_enrichments: [],
+    summary: emptySummary(),
+  };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('classify()', () => {
+  it('1. exported symbol removed, 3 dependents → severity "breaking"', () => {
+    const report = emptyReport();
+    report.symbols.push({
+      file: 'src/foo.ts',
+      name: 'doSomething',
+      kind: 'function',
+      status: 'removed',
+      exported: true,
+      signature_before: null,
+      signature_after: null,
+      dependents_affected: ['a.ts', 'b.ts', 'c.ts'],
+    });
+    const result = classify(report);
+    expect(result.changes).toHaveLength(1);
+    expect(result.changes[0].severity).toBe('breaking');
+    expect(result.has_breaking).toBe(true);
+  });
+
+  it('2. exported symbol removed, 0 dependents → severity "warning"', () => {
+    const report = emptyReport();
+    report.symbols.push({
+      file: 'src/foo.ts',
+      name: 'doSomething',
+      kind: 'function',
+      status: 'removed',
+      exported: true,
+      signature_before: null,
+      signature_after: null,
+      dependents_affected: [],
+    });
+    const result = classify(report);
+    expect(result.changes).toHaveLength(1);
+    expect(result.changes[0].severity).toBe('warning');
+    expect(result.has_breaking).toBe(false);
+  });
+
+  it('3. non-exported symbol removed → severity "info"', () => {
+    const report = emptyReport();
+    report.symbols.push({
+      file: 'src/foo.ts',
+      name: 'internalHelper',
+      kind: 'function',
+      status: 'removed',
+      exported: false,
+      signature_before: null,
+      signature_after: null,
+      dependents_affected: [],
+    });
+    const result = classify(report);
+    expect(result.changes).toHaveLength(1);
+    expect(result.changes[0].severity).toBe('info');
+  });
+
+  it('4. file removed → severity "warning"', () => {
+    const report = emptyReport();
+    report.files.push({
+      file: 'src/utils.ts',
+      status: 'removed',
+      hash_before: 'abc123',
+      hash_after: null,
+    });
+    const result = classify(report);
+    const fileChange = result.changes.find((c) => c.category === 'file');
+    expect(fileChange).toBeDefined();
+    expect(fileChange!.severity).toBe('warning');
+    expect(fileChange!.message).toContain('src/utils.ts');
+  });
+
+  it('5. file added → severity "info"', () => {
+    const report = emptyReport();
+    report.files.push({
+      file: 'src/new.ts',
+      status: 'added',
+      hash_before: null,
+      hash_after: 'def456',
+    });
+    const result = classify(report);
+    const fileChange = result.changes.find((c) => c.category === 'file');
+    expect(fileChange).toBeDefined();
+    expect(fileChange!.severity).toBe('info');
+  });
+
+  it('6. stale enrichment (hash_changed true) → severity "stale"', () => {
+    const report = emptyReport();
+    report.stale_enrichments.push({
+      file: 'src/foo.ts',
+      hash_changed: true,
+      was_semantic_now_structural: false,
+    });
+    const result = classify(report);
+    const staleChange = result.changes.find((c) => c.category === 'enrichment');
+    expect(staleChange).toBeDefined();
+    expect(staleChange!.severity).toBe('stale');
+    expect(staleChange!.suggestion).toContain('arc map');
+  });
+
+  it('7. has_breaking is true when breaking changes exist', () => {
+    const report = emptyReport();
+    report.symbols.push({
+      file: 'src/foo.ts',
+      name: 'criticalFn',
+      kind: 'function',
+      status: 'removed',
+      exported: true,
+      signature_before: null,
+      signature_after: null,
+      dependents_affected: ['consumer.ts'],
+    });
+    const result = classify(report);
+    expect(result.has_breaking).toBe(true);
+  });
+
+  it('8. has_breaking is false when no breaking changes exist', () => {
+    const report = emptyReport();
+    report.files.push({
+      file: 'src/new.ts',
+      status: 'added',
+      hash_before: null,
+      hash_after: 'abc',
+    });
+    const result = classify(report);
+    expect(result.has_breaking).toBe(false);
+  });
+
+  it('9. core module demoted → severity "warning"', () => {
+    const report = emptyReport();
+    report.graph.core_modules_removed.push('src/core/critical.ts');
+    const result = classify(report);
+    const graphChange = result.changes.find(
+      (c) => c.category === 'graph' && c.file === 'src/core/critical.ts',
+    );
+    expect(graphChange).toBeDefined();
+    expect(graphChange!.severity).toBe('warning');
+    expect(graphChange!.message).toContain('demoted');
+  });
+
+  it('10. depth increase >= 2 → severity "warning"', () => {
+    const report = emptyReport();
+    report.graph.depth_changes.push({ file: 'src/foo.ts', before: 1, after: 4 });
+    const result = classify(report);
+    const depthChange = result.changes.find((c) => c.category === 'graph');
+    expect(depthChange).toBeDefined();
+    expect(depthChange!.severity).toBe('warning');
+    expect(depthChange!.detail).toContain('+3');
+  });
+
+  it('depth change with abs(delta) < 2 → no graph change classified', () => {
+    const report = emptyReport();
+    report.graph.depth_changes.push({ file: 'src/foo.ts', before: 1, after: 2 }); // delta = 1
+    const result = classify(report);
+    expect(result.changes.filter((c) => c.category === 'graph')).toHaveLength(0);
+  });
+
+  it('exported symbol signature_changed with dependents → severity "breaking"', () => {
+    const report = emptyReport();
+    report.symbols.push({
+      file: 'src/foo.ts',
+      name: 'computeHash',
+      kind: 'function',
+      status: 'signature_changed',
+      exported: true,
+      signature_before: '(input: string): string',
+      signature_after: '(input: string, salt: string): string',
+      dependents_affected: ['src/consumer.ts'],
+    });
+    const result = classify(report);
+    expect(result.changes[0].severity).toBe('breaking');
+    expect(result.changes[0].detail).toContain('Before:');
+    expect(result.changes[0].detail).toContain('After:');
+  });
+
+  it('summary is copied from DriftReport', () => {
+    const report = emptyReport();
+    report.summary.files_added = 3;
+    report.summary.symbols_removed = 2;
+    const result = classify(report);
+    expect(result.summary.files_added).toBe(3);
+    expect(result.summary.symbols_removed).toBe(2);
+  });
+});