optave-codegraph 3.13.0

package/src/infrastructure/logger.ts

@@ -0,0 +1,24 @@
+let verbose = false;
+
+export function setVerbose(v: boolean): void {
+  verbose = v;
+}
+export function isVerbose(): boolean {
+  return verbose;
+}
+
+export function warn(msg: string): void {
+  process.stderr.write(`[codegraph WARN] ${msg}\n`);
+}
+
+export function debug(msg: string): void {
+  if (verbose) process.stderr.write(`[codegraph DEBUG] ${msg}\n`);
+}
+
+export function info(msg: string): void {
+  process.stderr.write(`[codegraph] ${msg}\n`);
+}
+
+export function error(msg: string): void {
+  process.stderr.write(`[codegraph ERROR] ${msg}\n`);
+}

package/src/infrastructure/native.ts

@@ -0,0 +1,199 @@
+/**
+ * Native addon loader with graceful fallback to WASM.
+ *
+ * Tries to load the platform-specific napi-rs binary built from
+ * crates/codegraph-core.  If unavailable the caller should fall back
+ * to the existing WASM pipeline.
+ */
+
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { EngineError, toErrorMessage } from '../shared/errors.js';
+import type { NativeAddon } from '../types.js';
+import { debug, warn } from './logger.js';
+
+let _cached: NativeAddon | null | undefined; // undefined = not yet tried, null = failed, NativeAddon = module
+let _loadError: Error | null = null;
+const _require = createRequire(import.meta.url);
+
+/**
+ * Detect whether the current Linux environment uses glibc or musl.
+ * Returns 'gnu' for glibc, 'musl' for musl, 'gnu' as fallback.
+ */
+function detectLibc(): 'gnu' | 'musl' {
+  try {
+    const { readdirSync } = _require('node:fs') as typeof import('node:fs');
+    const files = readdirSync('/lib');
+    if (files.some((f: string) => f.startsWith('ld-musl-') && f.endsWith('.so.1'))) {
+      return 'musl';
+    }
+  } catch (e) {
+    debug(`detectLibc: failed to read /lib: ${toErrorMessage(e)}`);
+  }
+  return 'gnu';
+}
+
+/** Map of (platform-arch[-libc]) → npm package name. */
+const PLATFORM_PACKAGES: Record<string, string> = {
+  'linux-x64-gnu': 'optave-codegraph-linux-x64-gnu',
+  'linux-x64-musl': 'optave-codegraph-linux-x64-musl',
+  'linux-arm64-gnu': 'optave-codegraph-linux-arm64-gnu',
+  'linux-arm64-musl': 'optave-codegraph-linux-arm64-musl', // not yet published — placeholder for future CI target
+  'darwin-arm64': 'optave-codegraph-darwin-arm64',
+  'darwin-x64': 'optave-codegraph-darwin-x64',
+  'win32-x64': 'optave-codegraph-win32-x64-msvc',
+};
+
+/**
+ * Map of (platform-arch[-libc]) → locally compiled binary filename.
+ * Checked before the npm package so that locally compiled Rust changes
+ * are picked up immediately in development without publishing a new release.
+ */
+const PLATFORM_LOCAL_BINARIES: Record<string, string> = {
+  'linux-x64-gnu': 'codegraph-core.linux-x64-gnu.node',
+  'linux-x64-musl': 'codegraph-core.linux-x64-musl.node',
+  'linux-arm64-gnu': 'codegraph-core.linux-arm64-gnu.node',
+  'linux-arm64-musl': 'codegraph-core.linux-arm64-musl.node',
+  'darwin-arm64': 'codegraph-core.darwin-arm64.node',
+  'darwin-x64': 'codegraph-core.darwin-x64.node',
+  'win32-x64': 'codegraph-core.win32-x64-msvc.node',
+};
+
+/** Compute the platform key used to index PLATFORM_PACKAGES / PLATFORM_LOCAL_BINARIES. */
+function resolvePlatformKey(): string {
+  const platform = os.platform();
+  const arch = os.arch();
+  return platform === 'linux' ? `${platform}-${arch}-${detectLibc()}` : `${platform}-${arch}`;
+}
+
+/**
+ * Resolve the platform-specific npm package name for the native addon.
+ * Returns null if the current platform is not supported.
+ */
+function resolvePlatformPackage(): string | null {
+  return PLATFORM_PACKAGES[resolvePlatformKey()] ?? null;
+}
+
+/**
+ * Try to load the native napi addon.
+ * Returns the module on success, null on failure.
+ *
+ * Load order:
+ *   1. NAPI_RS_NATIVE_LIBRARY_PATH env var (explicit override)
+ *   2. locally compiled binary in crates/codegraph-core/ (dev mode — preferred
+ *      over the npm package so that Rust changes are picked up immediately
+ *      without publishing a new release)
+ *   3. npm platform package (production path)
+ */
+export function loadNative(): NativeAddon | null {
+  if (_cached !== undefined) return _cached;
+
+  const platformKey = resolvePlatformKey();
+
+  // 1. Explicit path override — highest priority. Failure is fatal: if the
+  //    operator set this variable, silently loading a different binary would
+  //    be harder to diagnose than an explicit error.
+  const envPath = process.env.NAPI_RS_NATIVE_LIBRARY_PATH;
+  if (envPath) {
+    try {
+      _cached = _require(envPath) as NativeAddon;
+      debug(`loadNative: loaded from NAPI_RS_NATIVE_LIBRARY_PATH: ${envPath}`);
+      return _cached;
+    } catch (err) {
+      _loadError = err as Error;
+      warn(
+        `loadNative: NAPI_RS_NATIVE_LIBRARY_PATH is set but failed to load "${envPath}": ${toErrorMessage(err as Error)}`,
+      );
+      _cached = null;
+      return null;
+    }
+  }
+
+  // 2. Locally compiled dev binary — preferred over npm package so that Rust
+  //    changes are visible without publishing. Only used when the file exists.
+  //    If the file exists but fails to load (e.g. stale ABI), we warn and halt
+  //    rather than silently falling through to the npm package — that would
+  //    defeat the purpose of this priority order.
+  const localFile = PLATFORM_LOCAL_BINARIES[platformKey];
+  if (localFile) {
+    const localPath = fileURLToPath(
+      new URL(`../../crates/codegraph-core/${localFile}`, import.meta.url),
+    );
+    if (existsSync(localPath)) {
+      try {
+        _cached = _require(localPath) as NativeAddon;
+        debug(`loadNative: loaded local dev binary: ${localPath}`);
+        return _cached;
+      } catch (err) {
+        _loadError = err as Error;
+        warn(
+          `loadNative: local dev binary exists but failed to load "${localPath}": ${toErrorMessage(err as Error)}`,
+        );
+        _cached = null;
+        return null;
+      }
+    }
+  }
+
+  // 3. Published npm platform package — production path.
+  const pkg = resolvePlatformPackage();
+  if (pkg) {
+    try {
+      _cached = _require(pkg) as NativeAddon;
+      debug(`loadNative: loaded npm package: ${pkg}`);
+      return _cached;
+    } catch (err) {
+      _loadError = err as Error;
+      debug(`loadNative: npm package ${pkg} not available: ${toErrorMessage(err as Error)}`);
+    }
+  } else {
+    _loadError = new Error(`Unsupported platform: ${os.platform()}-${os.arch()}`);
+  }
+
+  _cached = null;
+  return null;
+}
+
+/**
+ * Check whether the native engine is available on this platform.
+ */
+export function isNativeAvailable(): boolean {
+  return loadNative() !== null;
+}
+
+/**
+ * Read the version from the platform-specific npm package.json.
+ * Returns null if the package is not installed or has no version.
+ *
+ * Note: always reports the npm package version. When the local dev binary or
+ * NAPI_RS_NATIVE_LIBRARY_PATH is loaded instead, this version may not match
+ * the running binary.
+ */
+export function getNativePackageVersion(): string | null {
+  const pkg = resolvePlatformPackage();
+  if (!pkg) return null;
+  try {
+    const pkgJson = _require(`${pkg}/package.json`) as { version?: string };
+    return pkgJson.version || null;
+  } catch (e) {
+    debug(`getNativePackageVersion: failed to read package.json for ${pkg}: ${toErrorMessage(e)}`);
+    return null;
+  }
+}
+
+/**
+ * Return the native module or throw if not available.
+ */
+export function getNative(): NativeAddon {
+  const mod = loadNative();
+  if (!mod) {
+    throw new EngineError(
+      `Native codegraph-core not available: ${_loadError?.message || 'unknown error'}. ` +
+        'Install the platform package or use --engine wasm.',
+      { cause: _loadError ?? undefined },
+    );
+  }
+  return mod;
+}

package/src/infrastructure/registry.ts

@@ -0,0 +1,313 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { ConsentDecision } from '../types.js';
+import { debug, warn } from './logger.js';
+
+export const REGISTRY_PATH: string =
+  process.env.CODEGRAPH_REGISTRY_PATH || path.join(os.homedir(), '.codegraph', 'registry.json');
+
+/** Default TTL: entries not accessed within 30 days are pruned. */
+export const DEFAULT_TTL_DAYS = 30;
+
+interface RegistryEntry {
+  path: string;
+  dbPath: string;
+  addedAt: string;
+  lastAccessedAt?: string;
+}
+
+interface UserConfigSection {
+  /** Per-repo consent decisions keyed by absolute repo path. */
+  consent: Record<string, ConsentDecision>;
+}
+
+interface Registry {
+  repos: Record<string, RegistryEntry>;
+  /** User-level global config consent store — separate from MCP repo listings. */
+  userConfig?: UserConfigSection;
+}
+
+/**
+ * Load the registry from disk.
+ * Returns `{ repos: {} }` on missing or corrupt file.
+ */
+export function loadRegistry(registryPath: string = REGISTRY_PATH): Registry {
+  try {
+    const raw = fs.readFileSync(registryPath, 'utf-8');
+    const data = JSON.parse(raw);
+    if (!data || typeof data.repos !== 'object') return { repos: {} };
+    return data as Registry;
+  } catch {
+    return { repos: {} };
+  }
+}
+
+/**
+ * Persist the registry to disk (atomic write via temp + rename).
+ * Creates the parent directory if needed.
+ */
+export function saveRegistry(registry: Registry, registryPath: string = REGISTRY_PATH): void {
+  const dir = path.dirname(registryPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const tmp = `${registryPath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(registry, null, 2), 'utf-8');
+  fs.renameSync(tmp, registryPath);
+}
+
+/**
+ * Register a project directory. Idempotent.
+ * Name defaults to `path.basename(rootDir)`.
+ *
+ * When no explicit name is provided and the basename already exists
+ * pointing to a different path, auto-suffixes (`api` → `api-2`, `api-3`, …).
+ * Re-registering the same path updates in place. Explicit names always overwrite.
+ */
+
+/** Find a unique suffixed name when the base name collides with a different path. */
+function findAvailableName(
+  baseName: string,
+  absRoot: string,
+  repos: Record<string, RegistryEntry>,
+): string {
+  let suffix = 2;
+  while (repos[`${baseName}-${suffix}`]) {
+    const entry = repos[`${baseName}-${suffix}`]!;
+    if (path.resolve(entry.path) === absRoot) return `${baseName}-${suffix}`;
+    suffix++;
+  }
+  return `${baseName}-${suffix}`;
+}
+
+export function registerRepo(
+  rootDir: string,
+  name?: string,
+  registryPath: string = REGISTRY_PATH,
+): { name: string; entry: RegistryEntry } {
+  const absRoot = path.resolve(rootDir);
+  const baseName = name || path.basename(absRoot);
+  const registry = loadRegistry(registryPath);
+
+  let repoName = baseName;
+
+  // Auto-suffix only when no explicit name was provided
+  if (!name) {
+    const existing = registry.repos[baseName];
+    if (existing && path.resolve(existing.path) !== absRoot) {
+      repoName = findAvailableName(baseName, absRoot, registry.repos);
+    }
+  }
+
+  const now = new Date().toISOString();
+  registry.repos[repoName] = {
+    path: absRoot,
+    dbPath: path.join(absRoot, '.codegraph', 'graph.db'),
+    addedAt: registry.repos[repoName]?.addedAt || now,
+    lastAccessedAt: now,
+  };
+
+  saveRegistry(registry, registryPath);
+  debug(`Registered repo "${repoName}" at ${absRoot}`);
+  return { name: repoName, entry: registry.repos[repoName]! };
+}
+
+/**
+ * Remove a repo from the registry. Returns false if not found.
+ */
+export function unregisterRepo(name: string, registryPath: string = REGISTRY_PATH): boolean {
+  const registry = loadRegistry(registryPath);
+  if (!registry.repos[name]) return false;
+  delete registry.repos[name];
+  saveRegistry(registry, registryPath);
+  return true;
+}
+
+export interface RepoListEntry {
+  name: string;
+  path: string;
+  dbPath: string;
+  addedAt: string;
+  lastAccessedAt: string;
+}
+
+/**
+ * List all registered repos, sorted by name.
+ */
+export function listRepos(registryPath: string = REGISTRY_PATH): RepoListEntry[] {
+  const registry = loadRegistry(registryPath);
+  return Object.entries(registry.repos)
+    .map(([name, entry]) => ({
+      name,
+      path: entry.path,
+      dbPath: entry.dbPath,
+      addedAt: entry.addedAt,
+      lastAccessedAt: entry.lastAccessedAt || entry.addedAt,
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Resolve a repo name to its database path.
+ * Returns undefined if the repo is not found or its DB file is missing.
+ */
+export function resolveRepoDbPath(
+  name: string,
+  registryPath: string = REGISTRY_PATH,
+): string | undefined {
+  const registry = loadRegistry(registryPath);
+  const entry = registry.repos[name];
+  if (!entry) return undefined;
+  if (!fs.existsSync(entry.dbPath)) {
+    warn(`Registry: database missing for "${name}" at ${entry.dbPath}`);
+    return undefined;
+  }
+  // Touch lastAccessedAt on successful resolution
+  entry.lastAccessedAt = new Date().toISOString();
+  saveRegistry(registry, registryPath);
+  return entry.dbPath;
+}
+
+// ── User-config consent ────────────────────────────────────────────────
+
+/**
+ * Read the per-repo consent decision for the global user config.
+ * Returns `undefined` when the repo is undecided (no recorded decision).
+ */
+export function getUserConfigConsent(
+  rootDir: string,
+  registryPath: string = REGISTRY_PATH,
+): ConsentDecision | undefined {
+  const registry = loadRegistry(registryPath);
+  const absRoot = path.resolve(rootDir);
+  return registry.userConfig?.consent?.[absRoot];
+}
+
+/**
+ * Persist a per-repo consent decision. Atomic write via temp+rename.
+ */
+export function setUserConfigConsent(
+  rootDir: string,
+  decision: ConsentDecision,
+  registryPath: string = REGISTRY_PATH,
+): void {
+  const registry = loadRegistry(registryPath);
+  const absRoot = path.resolve(rootDir);
+  if (!registry.userConfig) registry.userConfig = { consent: {} };
+  if (!registry.userConfig.consent) registry.userConfig.consent = {};
+  registry.userConfig.consent[absRoot] = decision;
+  saveRegistry(registry, registryPath);
+  debug(`User-config consent for "${absRoot}" set to "${decision}"`);
+}
+
+/**
+ * List every repo with a recorded consent decision, sorted by path.
+ */
+export function listUserConfigConsent(
+  registryPath: string = REGISTRY_PATH,
+): Array<{ path: string; decision: ConsentDecision }> {
+  const registry = loadRegistry(registryPath);
+  const consent = registry.userConfig?.consent ?? {};
+  return Object.entries(consent)
+    .map(([p, decision]) => ({ path: p, decision }))
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * Revert a repo to undecided state. Returns true if a decision was removed.
+ */
+export function clearUserConfigConsent(
+  rootDir: string,
+  registryPath: string = REGISTRY_PATH,
+): boolean {
+  const registry = loadRegistry(registryPath);
+  const absRoot = path.resolve(rootDir);
+  const consent = registry.userConfig?.consent;
+  if (!consent || !(absRoot in consent)) return false;
+  delete consent[absRoot];
+  saveRegistry(registry, registryPath);
+  return true;
+}
+
+interface PrunedEntry {
+  name: string;
+  path: string;
+  reason: 'missing' | 'expired';
+}
+
+/**
+ * Remove registry entries whose repo directory no longer exists on disk,
+ * or that haven't been accessed within `ttlDays` days.
+ * Returns an array of `{ name, path, reason }` for each pruned entry.
+ *
+ * When `dryRun` is true, entries are identified but not removed from disk.
+ */
+/**
+ * Walk `registry.repos`, identify entries that are missing on disk or have
+ * exceeded the TTL, and optionally delete them (when `dryRun` is false).
+ * Returns the list of entries that were (or would be) pruned.
+ */
+function pruneRepoEntries(
+  registry: Registry,
+  cutoff: number,
+  excludeSet: Set<string>,
+  dryRun: boolean,
+): PrunedEntry[] {
+  const pruned: PrunedEntry[] = [];
+  for (const [name, entry] of Object.entries(registry.repos)) {
+    if (excludeSet.has(name)) continue;
+    if (!fs.existsSync(entry.path)) {
+      pruned.push({ name, path: entry.path, reason: 'missing' });
+      if (!dryRun) delete registry.repos[name];
+      continue;
+    }
+    const lastAccess = Date.parse(entry.lastAccessedAt || entry.addedAt);
+    if (lastAccess < cutoff) {
+      pruned.push({ name, path: entry.path, reason: 'expired' });
+      if (!dryRun) delete registry.repos[name];
+    }
+  }
+  return pruned;
+}
+
+/**
+ * Prune consent entries whose repo paths no longer exist on disk.
+ * Consent entries are TTL-exempt — only the missing-path rule applies.
+ * Returns true when at least one entry was removed.
+ */
+function pruneConsentEntries(consent: Record<string, ConsentDecision>): boolean {
+  let changed = false;
+  for (const p of Object.keys(consent)) {
+    if (!fs.existsSync(p)) {
+      delete consent[p];
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+export function pruneRegistry(
+  registryPath: string = REGISTRY_PATH,
+  ttlDays: number = DEFAULT_TTL_DAYS,
+  excludeNames: string[] = [],
+  dryRun = false,
+): PrunedEntry[] {
+  const registry = loadRegistry(registryPath);
+  const cutoff = Date.now() - ttlDays * 24 * 60 * 60 * 1000;
+  const excludeSet = new Set(
+    excludeNames.filter((n) => typeof n === 'string' && n.trim().length > 0),
+  );
+
+  const pruned = pruneRepoEntries(registry, cutoff, excludeSet, dryRun);
+
+  const consentChanged =
+    !dryRun && registry.userConfig?.consent
+      ? pruneConsentEntries(registry.userConfig.consent)
+      : false;
+
+  if (!dryRun && (pruned.length > 0 || consentChanged)) {
+    saveRegistry(registry, registryPath);
+  }
+
+  return pruned;
+}

package/src/infrastructure/result-formatter.ts

@@ -0,0 +1,2 @@
+// Re-export from presentation layer — this file exists for backward compatibility.
+export { outputResult } from '../presentation/result-formatter.js';

package/src/infrastructure/suppress.ts

@@ -0,0 +1,47 @@
+/**
+ * Catch-suppression helpers for intentional error swallowing.
+ *
+ * Lives in `infrastructure/` (not `shared/`) because it depends on the
+ * structured logger — keeping `shared/errors.ts` dependency-free.
+ */
+
+import { toErrorMessage } from '../shared/errors.js';
+import { debug } from './logger.js';
+
+/**
+ * Run `fn` and return its result. If it throws, log a debug message and
+ * return `fallback` instead. Use this for intentional catch suppression
+ * where the error is expected and non-fatal (e.g. optional file reads,
+ * graceful feature probes, cleanup that may fail).
+ *
+ * @example
+ *   const version = suppressError(() => readPkgVersion(), 'read package version', '');
+ */
+export function suppressError<T>(fn: () => T, context: string, fallback: T): T {
+  try {
+    return fn();
+  } catch (e: unknown) {
+    debug(`${context}: ${toErrorMessage(e)}`);
+    return fallback;
+  }
+}
+
+/**
+ * Async variant of {@link suppressError}. Awaits `fn()` and returns `fallback`
+ * on rejection, logging the error via `debug()`.
+ *
+ * @example
+ *   const data = await suppressErrorAsync(() => fetchOptionalData(), 'fetch data', null);
+ */
+export async function suppressErrorAsync<T>(
+  fn: () => Promise<T>,
+  context: string,
+  fallback: T,
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (e: unknown) {
+    debug(`${context}: ${toErrorMessage(e)}`);
+    return fallback;
+  }
+}

package/src/infrastructure/test-filter.ts

@@ -0,0 +1,7 @@
+/** Pattern matching test/spec/stories files. */
+export const TEST_PATTERN = /\.(test|spec)\.|__test__|__tests__|\.stories\./;
+
+/** Check whether a file path looks like a test file. */
+export function isTestFile(filePath: string): boolean {
+  return TEST_PATTERN.test(filePath);
+}