@grafema/util 0.3.0-beta

package/src/utils/moduleResolution.ts

@@ -0,0 +1,271 @@
+/**
+ * Module Resolution Utilities (REG-320)
+ *
+ * Unified module path resolution logic extracted from:
+ * - MountPointResolver.resolveImportSource()
+ * - JSModuleIndexer.resolveModulePath()
+ * - FunctionCallResolver._resolveImportPath()
+ * - IncrementalModuleIndexer.tryResolve()
+ *
+ * Provides consistent module resolution across all plugins.
+ */
+
+import { existsSync, statSync } from 'fs';
+import { dirname, extname, resolve, join } from 'path';
+
+/**
+ * Default file extensions to try when resolving modules.
+ * Order: exact match first, then JS variants, then TS variants.
+ */
+export const DEFAULT_EXTENSIONS = ['', '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx'];
+
+/**
+ * TypeScript extension redirects (REG-426).
+ * Maps JS-family extensions to their TS equivalents.
+ * Used when an import specifies a .js extension but only a .ts file exists.
+ * This matches TypeScript's own module resolution behavior for ESM.
+ */
+const TS_EXTENSION_REDIRECTS: Record<string, string[]> = {
+  '.js': ['.ts', '.tsx'],
+  '.jsx': ['.tsx'],
+  '.mjs': ['.mts'],
+  '.cjs': ['.cts'],
+};
+
+/**
+ * Default index files to try when resolving directory imports.
+ * Order: JS variants first (most common), then TS variants.
+ */
+export const DEFAULT_INDEX_FILES = [
+  'index.js',
+  'index.ts',
+  'index.mjs',
+  'index.cjs',
+  'index.jsx',
+  'index.tsx'
+];
+
+/**
+ * Options for module path resolution.
+ *
+ * @example Filesystem mode (default)
+ * ```ts
+ * resolveModulePath('/app/utils')
+ * // → '/app/utils.js' if exists
+ * ```
+ *
+ * @example In-memory mode (for enrichment plugins)
+ * ```ts
+ * resolveModulePath('/app/utils', {
+ *   useFilesystem: false,
+ *   fileIndex: new Set(['/app/utils.ts'])
+ * })
+ * // → '/app/utils.ts'
+ * ```
+ */
+export interface ModuleResolutionOptions {
+  /**
+   * Use filesystem for path verification.
+   * Default: true
+   *
+   * When true: uses existsSync() to check if files exist
+   * When false: uses fileIndex.has() for lookup
+   *
+   * Performance note: For high-frequency calls during enrichment,
+   * use in-memory mode (useFilesystem: false) with a pre-built fileIndex.
+   * For indexing phase, filesystem mode is acceptable.
+   */
+  useFilesystem?: boolean;
+
+  /**
+   * Pre-built set of known file paths.
+   * Required when useFilesystem=false.
+   *
+   * Throws Error if useFilesystem=false and fileIndex is not provided.
+   */
+  fileIndex?: Set<string> | null;
+
+  /**
+   * Extensions to try (in order).
+   * Default: ['', '.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx']
+   *
+   * Empty string '' means try exact path first.
+   */
+  extensions?: string[];
+
+  /**
+   * Index files to try (in order).
+   * Default: ['index.js', 'index.ts', 'index.mjs', 'index.cjs', 'index.jsx', 'index.tsx']
+   */
+  indexFiles?: string[];
+}
+
+/**
+ * Check if path exists using the configured method.
+ */
+function pathExists(
+  testPath: string,
+  useFilesystem: boolean,
+  fileIndex?: Set<string> | null
+): boolean {
+  if (useFilesystem) {
+    return existsSync(testPath);
+  }
+  return fileIndex?.has(testPath) ?? false;
+}
+
+/**
+ * Check if path is a directory (filesystem mode only).
+ */
+function isDirectory(path: string, useFilesystem: boolean): boolean {
+  if (!useFilesystem) {
+    // In in-memory mode, we can't check if it's a directory
+    // The fileIndex should only contain file paths, not directories
+    return false;
+  }
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve a base path to an actual file by trying extensions and index files.
+ *
+ * @param basePath - Absolute path (without extension) to resolve
+ * @param options - Resolution options (filesystem vs in-memory, extensions, index files)
+ * @returns Resolved file path or null if not found
+ *
+ * @example Filesystem mode (default)
+ * ```ts
+ * resolveModulePath('/app/utils')
+ * // → '/app/utils.js' (if exists)
+ * ```
+ *
+ * @example In-memory mode (for enrichment plugins)
+ * ```ts
+ * resolveModulePath('/app/utils', {
+ *   useFilesystem: false,
+ *   fileIndex: new Set(['/app/utils.ts'])
+ * })
+ * // → '/app/utils.ts'
+ * ```
+ *
+ * Note: Symbolic links are followed by existsSync(). Assumes all paths
+ * are within the project workspace as determined by discovery phase.
+ */
+export function resolveModulePath(
+  basePath: string,
+  options?: ModuleResolutionOptions
+): string | null {
+  const useFilesystem = options?.useFilesystem ?? true;
+  const fileIndex = options?.fileIndex;
+  const extensions = options?.extensions ?? DEFAULT_EXTENSIONS;
+  const indexFiles = options?.indexFiles ?? DEFAULT_INDEX_FILES;
+
+  // Validation: fail fast if misconfigured
+  if (!useFilesystem && !fileIndex) {
+    throw new Error('fileIndex is required when useFilesystem=false');
+  }
+
+  // Handle empty path gracefully
+  if (!basePath) {
+    return null;
+  }
+
+  // Normalize path (remove trailing slash)
+  const normalizedPath = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+
+  // Try extensions (including '' for exact match)
+  for (const ext of extensions) {
+    const testPath = normalizedPath + ext;
+    if (pathExists(testPath, useFilesystem, fileIndex)) {
+      // In filesystem mode, don't return directories
+      if (useFilesystem && ext === '' && isDirectory(testPath, useFilesystem)) {
+        // It's a directory, skip to index files
+        continue;
+      }
+      return testPath;
+    }
+  }
+
+  // TypeScript extension redirect (REG-426):
+  // import './foo.js' → try ./foo.ts when ./foo.js doesn't exist
+  const ext = extname(normalizedPath);
+  const tsAlternatives = TS_EXTENSION_REDIRECTS[ext];
+  if (tsAlternatives) {
+    const withoutExt = normalizedPath.slice(0, -ext.length);
+    for (const tsExt of tsAlternatives) {
+      const testPath = withoutExt + tsExt;
+      if (pathExists(testPath, useFilesystem, fileIndex)) {
+        return testPath;
+      }
+    }
+  }
+
+  // Try index files in directory
+  for (const indexFile of indexFiles) {
+    const testPath = join(normalizedPath, indexFile);
+    if (pathExists(testPath, useFilesystem, fileIndex)) {
+      return testPath;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if import specifier is a relative import.
+ *
+ * @param specifier - The import specifier (e.g., './utils', 'lodash')
+ * @returns true if relative import (./ or ../), false otherwise
+ *
+ * @example
+ * ```ts
+ * isRelativeImport('./utils')      // true
+ * isRelativeImport('../shared')    // true
+ * isRelativeImport('lodash')       // false
+ * isRelativeImport('@scope/pkg')   // false
+ * isRelativeImport('node:fs')      // false
+ * ```
+ */
+export function isRelativeImport(specifier: string): boolean {
+  return specifier.startsWith('./') || specifier.startsWith('../');
+}
+
+/**
+ * Resolve relative import specifier to actual file path.
+ *
+ * Combines relative path resolution with module path resolution.
+ * Returns null for non-relative specifiers (bare modules, scoped packages).
+ *
+ * @param specifier - The import specifier (e.g., './utils', '../shared')
+ * @param containingFile - The file containing the import
+ * @param options - Resolution options
+ * @returns Resolved file path or null if not found or not relative
+ *
+ * @example
+ * ```ts
+ * // From /project/src/main.js, import './utils'
+ * resolveRelativeSpecifier('./utils', '/project/src/main.js')
+ * // → '/project/src/utils.js' (if exists)
+ * ```
+ */
+export function resolveRelativeSpecifier(
+  specifier: string,
+  containingFile: string,
+  options?: ModuleResolutionOptions
+): string | null {
+  // Only handle relative imports
+  if (!isRelativeImport(specifier)) {
+    return null;
+  }
+
+  // Resolve relative path to absolute base path
+  const dir = dirname(containingFile);
+  const basePath = resolve(dir, specifier);
+
+  // Use main resolution function
+  return resolveModulePath(basePath, options);
+}

package/src/utils/resolveNodeFile.ts

@@ -0,0 +1,18 @@
+/**
+ * Resolve a node's file path to an absolute path.
+ *
+ * After REG-408, node.file stores paths relative to projectPath.
+ * This utility resolves them back to absolute for file system access.
+ * Also handles legacy absolute paths for backward compatibility.
+ *
+ * @param nodeFile - The file field from a graph node (relative or absolute)
+ * @param projectPath - The absolute project root path
+ * @returns Absolute file path
+ */
+
+import { isAbsolute, join } from 'path';
+
+export function resolveNodeFile(nodeFile: string, projectPath: string): string {
+  if (isAbsolute(nodeFile)) return nodeFile;
+  return join(projectPath, nodeFile);
+}

package/src/utils/startRfdbServer.ts

@@ -0,0 +1,197 @@
+/**
+ * Shared utility for starting rfdb-server
+ *
+ * Single authoritative function for spawning rfdb-server. All spawn sites
+ * (RFDBServerBackend, CLI server command, ParallelAnalysisRunner) delegate here.
+ *
+ * If pidPath is provided, checks for an existing server via PID file before
+ * spawning. Returns null when an existing server is detected (caller should
+ * not kill it).
+ */
+
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname } from 'path';
+import { spawn, type ChildProcess } from 'child_process';
+import { setTimeout as sleep } from 'timers/promises';
+import { findRfdbBinary } from './findRfdbBinary.js';
+
+export interface StartRfdbServerOptions {
+  dbPath: string;
+  socketPath: string;
+  /** Override binary path; if absent, findRfdbBinary() is called */
+  binaryPath?: string;
+  /** If provided, PID file is written after spawn and checked before spawn */
+  pidPath?: string;
+  /** Socket poll timeout in ms (default: 5000) */
+  waitTimeoutMs?: number;
+  /** Optional logger for debug messages */
+  logger?: { debug(msg: string): void };
+  /** Internal: dependency injection for testing */
+  _deps?: {
+    spawn?: typeof spawn;
+    findRfdbBinary?: () => string | null;
+    existsSync?: (path: string) => boolean;
+    unlinkSync?: (path: string) => void;
+    writeFileSync?: (path: string, data: string) => void;
+    readFileSync?: (path: string, encoding: 'utf8') => string;
+    killProcess?: (pid: number, signal: number) => boolean;
+  };
+}
+
+/**
+ * Check if an existing server is running based on PID file.
+ *
+ * Returns:
+ * - 'alive' — PID file exists, process is alive, socket is present
+ * - 'stale' — PID file exists but process is dead or PID is invalid
+ * - 'none'  — no PID file
+ */
+export function checkExistingServer(
+  pidPath: string,
+  socketPath: string,
+  deps: {
+    existsSync: (path: string) => boolean;
+    readFileSync: (path: string, encoding: 'utf8') => string;
+    killProcess: (pid: number, signal: number) => boolean;
+  },
+): 'alive' | 'stale' | 'none' {
+  if (!deps.existsSync(pidPath)) return 'none';
+
+  let pidStr: string;
+  try {
+    pidStr = deps.readFileSync(pidPath, 'utf8').trim();
+  } catch {
+    return 'stale';
+  }
+
+  const pid = parseInt(pidStr, 10);
+  if (isNaN(pid) || pid <= 0) return 'stale';
+
+  try {
+    deps.killProcess(pid, 0);
+    // Process is alive — check socket too
+    if (deps.existsSync(socketPath)) {
+      return 'alive';
+    }
+    // PID alive but socket gone (server crashed partially)
+    return 'stale';
+  } catch (err: unknown) {
+    if (err && typeof err === 'object' && 'code' in err && (err as { code: string }).code === 'ESRCH') {
+      return 'stale';
+    }
+    // Unexpected error — re-throw rather than silently treating as stale
+    throw err;
+  }
+}
+
+/**
+ * Start an rfdb-server process (or detect existing one via PID file).
+ *
+ * 0. Check PID file for existing server (if pidPath provided)
+ * 1. Resolve binary (explicit or via findRfdbBinary)
+ * 2. Remove stale socket
+ * 3. Spawn detached process
+ * 4. Write PID file (if pidPath provided)
+ * 5. Poll for socket file up to waitTimeoutMs
+ * 6. Return ChildProcess (caller decides whether to kill later)
+ *
+ * Returns null if an existing server is already running (pidPath + alive PID).
+ */
+export async function startRfdbServer(options: StartRfdbServerOptions): Promise<ChildProcess | null> {
+  const {
+    dbPath,
+    socketPath,
+    pidPath,
+    waitTimeoutMs = 5000,
+    logger,
+    _deps,
+  } = options;
+
+  const _spawn = _deps?.spawn ?? spawn;
+  const _findRfdbBinary = _deps?.findRfdbBinary ?? findRfdbBinary;
+  const _existsSync = _deps?.existsSync ?? existsSync;
+  const _unlinkSync = _deps?.unlinkSync ?? unlinkSync;
+  const _writeFileSync = _deps?.writeFileSync ?? writeFileSync;
+  const _readFileSync = _deps?.readFileSync ?? readFileSync;
+  const _killProcess = _deps?.killProcess ?? ((pid: number, signal: number) => process.kill(pid, signal));
+
+  // 0. Check for existing server via PID file
+  if (pidPath) {
+    const status = checkExistingServer(pidPath, socketPath, {
+      existsSync: _existsSync,
+      readFileSync: _readFileSync,
+      killProcess: _killProcess,
+    });
+    if (status === 'alive') {
+      logger?.debug(`rfdb-server already running (PID file: ${pidPath}), reusing`);
+      return null;
+    }
+    if (status === 'stale') {
+      logger?.debug(`Stale PID file found at ${pidPath}, removing`);
+      try { _unlinkSync(pidPath); } catch { /* ignore */ }
+    }
+  }
+
+  // 1. Resolve binary
+  const binaryPath = options.binaryPath || _findRfdbBinary();
+  if (!binaryPath) {
+    throw new Error(
+      'RFDB server binary not found.\n' +
+      'Install @grafema/rfdb: npm install @grafema/rfdb\n' +
+      'Or build from source: cargo build --release --bin rfdb-server'
+    );
+  }
+
+  // 2. Remove stale socket
+  if (_existsSync(socketPath)) {
+    _unlinkSync(socketPath);
+  }
+
+  const dataDir = dirname(socketPath);
+  logger?.debug(`Starting rfdb-server: ${binaryPath} ${dbPath} --socket ${socketPath} --data-dir ${dataDir}`);
+
+  // 3. Spawn server (detached, survives parent exit)
+  // Mutable container to capture async spawn errors (Dijkstra amendment B)
+  const state = { spawnError: null as Error | null };
+
+  const serverProcess = _spawn(binaryPath, [dbPath, '--socket', socketPath, '--data-dir', dataDir], {
+    stdio: ['ignore', 'ignore', process.stderr.isTTY ? 'inherit' : 'ignore'],
+    detached: true,
+  });
+
+  serverProcess.unref();
+
+  // Wire error handler to capture ENOENT and other spawn failures
+  serverProcess.on('error', (err: Error) => {
+    state.spawnError = err;
+  });
+
+  // 4. Write PID file if requested and pid is available
+  if (pidPath && serverProcess.pid) {
+    _writeFileSync(pidPath, String(serverProcess.pid));
+  }
+
+  // 5. Poll for socket file
+  const maxAttempts = Math.ceil(waitTimeoutMs / 100);
+  let attempts = 0;
+  while (!_existsSync(socketPath) && attempts < maxAttempts) {
+    if (state.spawnError) {
+      throw new Error(
+        `RFDB server failed to start: ${state.spawnError.message} — check binary: ${binaryPath}`
+      );
+    }
+    await sleep(100);
+    attempts++;
+  }
+
+  // 6. Final check
+  if (!_existsSync(socketPath)) {
+    const detail = state.spawnError ? `: ${state.spawnError.message}` : '';
+    throw new Error(
+      `RFDB server failed to start after ${waitTimeoutMs}ms${detail} — check binary: ${binaryPath}`
+    );
+  }
+
+  logger?.debug(`rfdb-server started on ${socketPath}`);
+  return serverProcess;
+}