@nomos-arc/arc 0.1.0

package/src/core/graph/resolver.ts

@@ -0,0 +1,195 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface ResolveResult {
+  resolved: string | null;
+  is_external: boolean;
+}
+
+// ─── ImportResolver ───────────────────────────────────────────────────────────
+
+/**
+ * Resolves import sources to absolute project-relative paths.
+ *
+ * [AMB-4 FIX] Uses a `knownFiles: Set<string>` contract for all existence
+ * checks — zero filesystem calls (no fs.existsSync, fs.access, fs.stat).
+ *
+ * [WATCH-4] The caller MUST populate `knownFiles` from BOTH ScanResult.files
+ * (newly scanned) AND ScanResult.carried (unchanged from previous run) before
+ * any resolve() call. Carried files that are invisible to the set will silently
+ * fail to resolve.
+ *
+ * The `async` signature exists for interface consistency — the implementation
+ * is synchronous.
+ */
+export class ImportResolver {
+  /** Tsconfig path aliases: key pattern → array of substitution templates */
+  private readonly aliasMap: Map<string, string[]>;
+
+  constructor(
+    private readonly projectRoot: string,
+    private readonly logger: { warn(msg: string): void },
+  ) {
+    this.aliasMap = this.loadTsconfigPaths();
+  }
+
+  /**
+   * [AMB-4 FIX] async for interface consistency; synchronous implementation.
+   * All existence checks use `knownFiles.has()` — NO filesystem calls.
+   *
+   * Resolution order:
+   *   1. External check (no leading . / / or matched alias → external)
+   *   2. Tsconfig alias substitution → continue to relative resolution
+   *   3. Relative resolution with extension probing against knownFiles
+   *   4. Path traversal guard (outside projectRoot → external)
+   *   5. Unresolvable → warn, return { resolved: null, is_external: false }
+   */
+  async resolve(
+    importSource: string,
+    importerFile: string,
+    knownFiles: Set<string>,
+  ): Promise<ResolveResult> {
+    // ── 1. External check ──────────────────────────────────────────────────
+    const isRelativeOrAbsolute =
+      importSource.startsWith('.') || importSource.startsWith('/');
+    const aliasMatch = this.matchAlias(importSource);
+
+    if (!isRelativeOrAbsolute && aliasMatch === null) {
+      return { resolved: null, is_external: true };
+    }
+
+    // ── 3. Relative resolution ────────────────────────────────────────────
+    const importerDir = path.dirname(path.join(this.projectRoot, importerFile));
+
+    if (aliasMatch !== null) {
+      // ── 2. Tsconfig alias substitution ──────────────────────────────────
+      // Tsconfig path values are relative to projectRoot (the tsconfig dir).
+      for (const substituted of aliasMatch) {
+        const result = this.resolveRelative(substituted, this.projectRoot, knownFiles);
+        if (result !== null) return result;
+      }
+    } else {
+      // Regular relative import — resolve from importer directory
+      const result = this.resolveRelative(importSource, importerDir, knownFiles);
+      if (result !== null) return result;
+    }
+
+    // ── 5. Unresolvable ───────────────────────────────────────────────────
+    this.logger.warn(
+      `[nomos:graph:warn] Cannot resolve import '${importSource}' from '${importerFile}'`,
+    );
+    return { resolved: null, is_external: false };
+  }
+
+  // ─── Private ──────────────────────────────────────────────────────────────
+
+  /**
+   * Attempt to resolve a (possibly alias-substituted) source string relative
+   * to the importer directory.
+   *
+   * Probes candidate paths in order against `knownFiles`.
+   * [AMB-4] NO filesystem calls — knownFiles.has() only.
+   */
+  private resolveRelative(
+    src: string,
+    importerDir: string,
+    knownFiles: Set<string>,
+  ): ResolveResult | null {
+    const extensions = ['.ts', '.tsx', '.js'];
+    const indexFiles = ['index.ts', 'index.tsx', 'index.js'];
+
+    // Compute base absolute path
+    const absBase = path.resolve(importerDir, src);
+
+    // ── 4. Path traversal guard ───────────────────────────────────────────
+    const rel = path.relative(this.projectRoot, absBase);
+    if (rel.startsWith('..')) {
+      this.logger.warn(
+        `[nomos:graph:warn] Import path traversal outside projectRoot: '${src}'`,
+      );
+      return { resolved: null, is_external: true };
+    }
+
+    const candidates: string[] = [];
+
+    // Direct hit (if src already has extension)
+    candidates.push(absBase);
+
+    // Extension probing
+    for (const ext of extensions) {
+      candidates.push(`${absBase}${ext}`);
+    }
+
+    // Index file resolution
+    for (const idx of indexFiles) {
+      candidates.push(path.join(absBase, idx));
+    }
+
+    for (const candidate of candidates) {
+      const relCandidate = path.relative(this.projectRoot, candidate);
+      if (knownFiles.has(relCandidate)) {
+        return { resolved: relCandidate, is_external: false };
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Match importSource against tsconfig `compilerOptions.paths` aliases.
+   * Returns substituted source strings if matched, null otherwise.
+   */
+  private matchAlias(importSource: string): string[] | null {
+    for (const [pattern, substitutions] of this.aliasMap) {
+      if (pattern.endsWith('/*')) {
+        // Wildcard alias: @/utils/* → src/utils/*
+        const prefix = pattern.slice(0, -2); // remove trailing /*
+        if (importSource.startsWith(prefix + '/') || importSource === prefix) {
+          const capture = importSource.startsWith(prefix + '/')
+            ? importSource.slice(prefix.length + 1)
+            : '';
+          return substitutions.map((sub) =>
+            sub.endsWith('/*') ? sub.slice(0, -2) + '/' + capture : sub,
+          );
+        }
+      } else {
+        // Exact alias
+        if (importSource === pattern) {
+          return [...substitutions];
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Read `tsconfig.json` at projectRoot and extract `compilerOptions.paths`.
+   * Missing or malformed → returns empty map (graceful degradation).
+   */
+  private loadTsconfigPaths(): Map<string, string[]> {
+    const tsconfigPath = path.join(this.projectRoot, 'tsconfig.json');
+    try {
+      const raw = fs.readFileSync(tsconfigPath, 'utf-8');
+      const tsconfig = JSON.parse(raw) as {
+        compilerOptions?: { paths?: Record<string, string[]> };
+      };
+      const paths = tsconfig.compilerOptions?.paths;
+      if (!paths || typeof paths !== 'object') return new Map();
+
+      const map = new Map<string, string[]>();
+      for (const [key, values] of Object.entries(paths)) {
+        if (Array.isArray(values)) {
+          map.set(key, values as string[]);
+        }
+      }
+      return map;
+    } catch {
+      // Missing tsconfig or parse error → empty alias map
+      return new Map();
+    }
+  }
+}

package/src/core/graph/scanner.ts

@@ -0,0 +1,145 @@
+import * as fs from 'node:fs/promises';
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+import fg from 'fast-glob';
+import type { NomosConfig } from '../../types/index.js';
+import type { FileNode, ProjectMap } from '../../types/index.js';
+
+// ─── Language Map ─────────────────────────────────────────────────────────────
+
+export const LANGUAGE_MAP: Record<string, string> = {
+  '.ts': 'typescript',
+  '.tsx': 'tsx',
+  '.mts': 'typescript',
+  '.cts': 'typescript',
+  '.d.ts': 'typescript',
+  '.js': 'javascript',
+  '.mjs': 'javascript',
+  '.cjs': 'javascript',
+  '.jsx': 'jsx',
+  '.py': 'python',
+  '.go': 'go',
+  '.rs': 'rust',
+};
+
+// ─── ScanResult ───────────────────────────────────────────────────────────────
+
+export interface ScanResult {
+  files: Map<string, { file: string; hash: string; language: string; content: string }>;
+  carried: Map<string, FileNode>;
+}
+
+// ─── FileScanner ─────────────────────────────────────────────────────────────
+
+export class FileScanner {
+  constructor(
+    private readonly projectRoot: string,
+    private readonly config: NomosConfig['graph'],
+    private readonly logger: { warn(msg: string): void; info(msg: string): void },
+  ) {}
+
+  async scan(
+    existingMap: ProjectMap | null,
+    force: boolean,
+    globPatterns?: string[],
+  ): Promise<ScanResult> {
+    const ignorePatterns = await this.buildIgnorePatterns();
+
+    const patterns = globPatterns ?? ['**/*'];
+    const absolutePaths = await fg(patterns, {
+      cwd: this.projectRoot,
+      absolute: true,
+      dot: true,
+      ignore: ignorePatterns,
+      followSymbolicLinks: false,
+      onlyFiles: true,
+    });
+
+    const result: ScanResult = {
+      files: new Map(),
+      carried: new Map(),
+    };
+
+    for (const absolutePath of absolutePaths) {
+      const relPath = path.relative(this.projectRoot, absolutePath);
+      const ext = this.resolveExtension(relPath);
+      const language = LANGUAGE_MAP[ext];
+
+      if (!language) continue;
+
+      // [GAP-1 FIX] Skip files exceeding 500KB
+      let stat: Awaited<ReturnType<typeof fs.stat>>;
+      try {
+        stat = await fs.stat(absolutePath);
+      } catch (err: unknown) {
+        const code = (err as NodeJS.ErrnoException).code;
+        if (code === 'ENOENT' || code === 'EACCES') {
+          this.logger.warn(`[nomos:graph:warn] Skipping ${relPath} — cannot stat file`);
+          continue;
+        }
+        throw err;
+      }
+
+      if (stat.size > 512000) {
+        this.logger.warn(`[nomos:graph:warn] Skipping ${relPath} — exceeds 500KB size limit`);
+        continue;
+      }
+
+      let content: string;
+      try {
+        content = await fs.readFile(absolutePath, 'utf-8');
+      } catch (err: unknown) {
+        const code = (err as NodeJS.ErrnoException).code;
+        if (code === 'ENOENT' || code === 'EACCES') {
+          this.logger.warn(`[nomos:graph:warn] Skipping ${relPath} — cannot read file`);
+          continue;
+        }
+        throw err;
+      }
+
+      const hash = `sha256:${crypto.createHash('sha256').update(content).digest('hex')}`;
+
+      // Incremental: carry forward if hash unchanged and not forced
+      if (!force && existingMap) {
+        const existing = existingMap.files[relPath];
+        if (existing && existing.hash === hash) {
+          result.carried.set(relPath, existing);
+          continue;
+        }
+      }
+
+      result.files.set(relPath, { file: relPath, hash, language, content });
+    }
+
+    return result;
+  }
+
+  // ─── Private Helpers ──────────────────────────────────────────────────────
+
+  private resolveExtension(filePath: string): string {
+    // Handle .d.ts before generic .ts
+    if (filePath.endsWith('.d.ts')) return '.d.ts';
+    return path.extname(filePath);
+  }
+
+  private async buildIgnorePatterns(): Promise<string[]> {
+    const patterns: string[] = [...this.config.exclude_patterns];
+
+    try {
+      const gitignoreContent = await fs.readFile(
+        path.join(this.projectRoot, '.gitignore'),
+        'utf-8',
+      );
+      for (const line of gitignoreContent.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed && !trimmed.startsWith('#')) {
+          patterns.push(trimmed);
+        }
+      }
+    } catch {
+      // No .gitignore — use empty list
+    }
+
+    return patterns;
+  }
+}

package/src/core/logger.ts

@@ -0,0 +1,46 @@
+import winston from 'winston';
+import { stripAnsi } from '../utils/ansi.js';
+
+/**
+ * createLogger — Winston logger with two transports:
+ *
+ *  Console transport: colorized, format: [nomos:<level>] <message>
+ *  File transport:    writes to {logDir}/nomos.log, ANSI-stripped, JSON format.
+ *
+ * @param level   - Winston log level (default: 'info')
+ * @param logDir  - Directory for nomos.log. Omit to disable file transport.
+ */
+export function createLogger(level: string = 'info', logDir?: string): winston.Logger {
+  const transports: winston.transport[] = [
+    new winston.transports.Console({
+      format: winston.format.combine(
+        winston.format.colorize({ all: true }),
+        winston.format.printf(({ level: lvl, message }) => {
+          return `[nomos:${lvl}] ${String(message)}`;
+        }),
+      ),
+    }),
+  ];
+
+  if (logDir) {
+    transports.push(
+      new winston.transports.File({
+        filename: `${logDir}/nomos.log`,
+        format: winston.format.combine(
+          // Strip ANSI codes before writing to file
+          winston.format((info) => {
+            info['message'] = stripAnsi(String(info['message']));
+            return info;
+          })(),
+          winston.format.timestamp(),
+          winston.format.json(),
+        ),
+      }),
+    );
+  }
+
+  return winston.createLogger({
+    level,
+    transports,
+  });
+}