@grafema/util 0.3.0-beta

package/src/storage/backends/typeValidation.ts

@@ -0,0 +1,154 @@
+/**
+ * Type Validation Utilities
+ *
+ * Levenshtein distance and typo detection for node/edge types.
+ * Extracted from ReginaFlowBackend for use in multiple contexts.
+ */
+
+// Known node types - source of truth for validation
+// Initial set of types, dynamically expanded as new valid types are encountered
+const KNOWN_NODE_TYPES = new Set<string>([
+  // Base types
+  'FUNCTION', 'CLASS', 'METHOD', 'VARIABLE', 'PARAMETER', 'CONSTANT', 'LITERAL',
+  'MODULE', 'IMPORT', 'EXPORT', 'CALL', 'PROJECT', 'SERVICE', 'FILE', 'SCOPE',
+  'EXTERNAL', 'EXTERNAL_MODULE', 'SIDE_EFFECT',
+  // Namespaced types - HTTP/Express
+  'http:route', 'http:request',
+  'express:router', 'express:middleware', 'express:mount',
+  // Namespaced types - Socket.IO
+  'socketio:emit', 'socketio:on', 'socketio:namespace', 'socketio:room',
+  // Namespaced types - Database
+  'db:query', 'db:connection', 'db:table',
+  // Namespaced types - File System
+  'fs:read', 'fs:write', 'fs:operation',
+  // Namespaced types - Network/IO
+  'net:request', 'net:stdio',
+  // Namespaced types - Events
+  'event:listener', 'event:emit',
+  // Service layer types (legacy, to be refactored)
+  'SERVICE_CLASS', 'SERVICE_INSTANCE', 'SERVICE_REGISTRATION', 'SERVICE_USAGE',
+  // Guarantees/Invariants
+  'GUARANTEE',
+]);
+
+// Store initial types for reset
+const INITIAL_NODE_TYPES = [...KNOWN_NODE_TYPES];
+
+// Known edge types - source of truth for validation
+const KNOWN_EDGE_TYPES = new Set<string>([
+  // Base edge types
+  'UNKNOWN', 'CONTAINS', 'DEPENDS_ON', 'CALLS', 'EXTENDS', 'IMPLEMENTS',
+  'USES', 'DEFINES', 'IMPORTS', 'EXPORTS', 'ROUTES_TO', 'HAS_SCOPE',
+  'CAPTURES', 'MODIFIES', 'DECLARES', 'WRITES_TO', 'INSTANCE_OF',
+  'HAS_CALLBACK', 'IMPORTS_FROM', 'HANDLED_BY', 'MAKES_REQUEST',
+  'PASSES_ARGUMENT', 'ASSIGNED_FROM', 'MOUNTS', 'EXPOSES',
+  'INTERACTS_WITH', 'CALLS_API', 'LISTENS_TO', 'JOINS_ROOM', 'EMITS_EVENT',
+  'RETURNS', 'RECEIVES_ARGUMENT', 'READS_FROM', 'THROWS', 'REGISTERS_VIEW',
+  'GOVERNS', 'VIOLATES', 'HAS_PARAMETER', 'DERIVES_FROM',
+  'RESOLVES_TO',  // Promise resolve() data flow
+  'YIELDS',       // Generator yield data flow (REG-270)
+  'DELEGATES_TO', // Generator yield* delegation (REG-270)
+]);
+
+// Store initial edge types for reset
+const INITIAL_EDGE_TYPES = [...KNOWN_EDGE_TYPES];
+
+export interface TypoCheckResult {
+  isTooSimilar: boolean;
+  similarTo: string | null;
+}
+
+/**
+ * Levenshtein distance for typo detection
+ */
+export function levenshtein(a: string, b: string): number {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  const matrix: number[][] = [];
+  for (let i = 0; i <= b.length; i++) matrix[i] = [i];
+  for (let j = 0; j <= a.length; j++) matrix[0][j] = j;
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      matrix[i][j] = b[i - 1] === a[j - 1]
+        ? matrix[i - 1][j - 1]
+        : Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+    }
+  }
+  return matrix[b.length][a.length];
+}
+
+/**
+ * Check if a type is too similar to any existing known type (possible typo)
+ */
+export function checkTypoAgainstKnownTypes(newType: string): TypoCheckResult {
+  const newTypeLower = newType.toLowerCase();
+  for (const known of KNOWN_NODE_TYPES) {
+    const dist = levenshtein(newTypeLower, known.toLowerCase());
+    if (dist > 0 && dist <= 2) {
+      return { isTooSimilar: true, similarTo: known };
+    }
+  }
+  return { isTooSimilar: false, similarTo: null };
+}
+
+/**
+ * Reset KNOWN_NODE_TYPES to initial state (for testing)
+ */
+export function resetKnownNodeTypes(): void {
+  KNOWN_NODE_TYPES.clear();
+  for (const t of INITIAL_NODE_TYPES) {
+    KNOWN_NODE_TYPES.add(t);
+  }
+}
+
+/**
+ * Get current known node types (for testing/debugging)
+ */
+export function getKnownNodeTypes(): Set<string> {
+  return new Set(KNOWN_NODE_TYPES);
+}
+
+/**
+ * Check if an edge type is too similar to any existing known edge type (possible typo)
+ */
+export function checkTypoAgainstKnownEdgeTypes(newType: string): TypoCheckResult {
+  const newTypeLower = newType.toLowerCase();
+  for (const known of KNOWN_EDGE_TYPES) {
+    const dist = levenshtein(newTypeLower, known.toLowerCase());
+    if (dist > 0 && dist <= 2) {
+      return { isTooSimilar: true, similarTo: known };
+    }
+  }
+  return { isTooSimilar: false, similarTo: null };
+}
+
+/**
+ * Reset KNOWN_EDGE_TYPES to initial state (for testing)
+ */
+export function resetKnownEdgeTypes(): void {
+  KNOWN_EDGE_TYPES.clear();
+  for (const t of INITIAL_EDGE_TYPES) {
+    KNOWN_EDGE_TYPES.add(t);
+  }
+}
+
+/**
+ * Get current known edge types (for testing/debugging)
+ */
+export function getKnownEdgeTypes(): Set<string> {
+  return new Set(KNOWN_EDGE_TYPES);
+}
+
+/**
+ * Add a new node type to the known types set
+ */
+export function addKnownNodeType(nodeType: string): void {
+  KNOWN_NODE_TYPES.add(nodeType);
+}
+
+/**
+ * Add a new edge type to the known types set
+ */
+export function addKnownEdgeType(edgeType: string): void {
+  KNOWN_EDGE_TYPES.add(edgeType);
+}

package/src/utils/findRfdbBinary.ts

@@ -0,0 +1,288 @@
+/**
+ * Unified binary lookup for Grafema native binaries.
+ *
+ * Used by CLI, MCP server, and the unified grafema package.
+ * Finds rfdb-server, grafema-orchestrator, or any binary by name.
+ *
+ * Search order:
+ * 1. Explicit path (from config or flag)
+ * 2. Environment variable (GRAFEMA_RFDB_SERVER / GRAFEMA_ORCHESTRATOR)
+ * 3. Platform package (@grafema/grafema-{os}-{arch})
+ * 4. Monorepo target/release (development)
+ * 5. Monorepo target/debug (development)
+ * 6. System PATH lookup
+ * 7. ~/.grafema/bin/ (lazy-downloaded analyzers)
+ * 8. ~/.local/bin/ (user-installed)
+ */
+
+import { existsSync } from 'fs';
+import { join, delimiter, dirname, resolve } from 'path';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export type BinaryName = 'rfdb-server' | 'grafema-orchestrator';
+
+export interface FindBinaryOptions {
+  /** Explicit path to binary (highest priority) */
+  explicitPath?: string;
+  /** Base directory for monorepo search (defaults to auto-detect) */
+  monorepoRoot?: string;
+}
+
+interface BinaryConfig {
+  envVar: string;
+  monorepoPackage: string;
+}
+
+const BINARY_CONFIG: Record<BinaryName, BinaryConfig> = {
+  'rfdb-server': {
+    envVar: 'GRAFEMA_RFDB_SERVER',
+    monorepoPackage: 'rfdb-server',
+  },
+  'grafema-orchestrator': {
+    envVar: 'GRAFEMA_ORCHESTRATOR',
+    monorepoPackage: 'grafema-orchestrator',
+  },
+};
+
+/**
+ * Get platform directory name for prebuilt binaries.
+ * E.g., "darwin-arm64", "linux-x64"
+ */
+export function getPlatformDir(): string {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  if (platform === 'darwin') {
+    return arch === 'arm64' ? 'darwin-arm64' : 'darwin-x64';
+  } else if (platform === 'linux') {
+    return arch === 'arm64' ? 'linux-arm64' : 'linux-x64';
+  }
+  return `${platform}-${arch}`;
+}
+
+/**
+ * Get platform package name for the current OS/arch.
+ * E.g., "@grafema/grafema-darwin-arm64"
+ */
+export function getPlatformPackageName(): string {
+  const platform = process.platform === 'darwin' ? 'darwin' : 'linux';
+  const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+  return `@grafema/grafema-${platform}-${arch}`;
+}
+
+/**
+ * Try to load the platform package and get a binary path from it.
+ */
+function tryPlatformPackage(binaryName: BinaryName): string | null {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkgName = getPlatformPackageName();
+    const pkg = require(pkgName);
+
+    if (binaryName === 'rfdb-server' && pkg.rfdbServerPath) {
+      const p = pkg.rfdbServerPath;
+      if (existsSync(p)) return p;
+    }
+    if (binaryName === 'grafema-orchestrator' && pkg.orchestratorPath) {
+      const p = pkg.orchestratorPath;
+      if (existsSync(p)) return p;
+    }
+
+    // Fallback: try binDir + binaryName
+    if (pkg.binDir) {
+      const p = join(pkg.binDir, binaryName);
+      if (existsSync(p)) return p;
+    }
+  } catch {
+    // Platform package not installed
+  }
+  return null;
+}
+
+/**
+ * Find monorepo root by looking for characteristic files.
+ */
+function findMonorepoRoot(startDir?: string): string | null {
+  // Walk up from provided dir or this file's location
+  let dir = startDir || join(__dirname, '..', '..', '..', '..');
+  for (let i = 0; i < 8; i++) {
+    const hasPackagesDir = existsSync(join(dir, 'packages', 'util'));
+    const hasPnpmWorkspace = existsSync(join(dir, 'pnpm-workspace.yaml'));
+    if (hasPackagesDir && hasPnpmWorkspace) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // Try GRAFEMA_ROOT env var
+  const envRoot = process.env.GRAFEMA_ROOT;
+  if (envRoot && existsSync(join(envRoot, 'packages', 'util'))) {
+    return envRoot;
+  }
+
+  return null;
+}
+
+/**
+ * Find a Grafema native binary.
+ *
+ * @param binaryName - Which binary to find
+ * @param options - Search options
+ * @returns Absolute path to the binary, or null if not found
+ */
+export function findBinary(binaryName: BinaryName, options: FindBinaryOptions = {}): string | null {
+  const config = BINARY_CONFIG[binaryName];
+
+  // 1. Explicit path (from config or flag) — no fallback
+  if (options.explicitPath) {
+    const resolved = resolve(options.explicitPath);
+    return existsSync(resolved) ? resolved : null;
+  }
+
+  // 2. Environment variable
+  const envPath = process.env[config.envVar];
+  if (envPath && existsSync(envPath)) {
+    return envPath;
+  }
+
+  // 3. Platform package (@grafema/grafema-{os}-{arch})
+  const platformPath = tryPlatformPackage(binaryName);
+  if (platformPath) return platformPath;
+
+  // 4-5. Monorepo development builds
+  const monorepoRoot = findMonorepoRoot(options.monorepoRoot);
+  if (monorepoRoot) {
+    for (const profile of ['release', 'debug']) {
+      const p = join(monorepoRoot, 'packages', config.monorepoPackage, 'target', profile, binaryName);
+      if (existsSync(p)) return p;
+    }
+  }
+
+  // 6. System PATH lookup
+  const pathDirs = (process.env.PATH || '').split(delimiter);
+  for (const dir of pathDirs) {
+    if (!dir) continue;
+    const p = join(dir, binaryName);
+    if (existsSync(p)) return p;
+  }
+
+  // 7. ~/.grafema/bin/ (lazy-downloaded analyzers)
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  if (home) {
+    const p = join(home, '.grafema', 'bin', binaryName);
+    if (existsSync(p)) return p;
+  }
+
+  // 8. ~/.local/bin/ (user-installed)
+  if (home) {
+    const p = join(home, '.local', 'bin', binaryName);
+    if (existsSync(p)) return p;
+  }
+
+  // Legacy: @grafema/rfdb npm package (old prebuilt location)
+  if (binaryName === 'rfdb-server') {
+    try {
+      const require = createRequire(import.meta.url);
+      const rfdbPkg = require.resolve('@grafema/rfdb');
+      const rfdbDir = dirname(rfdbPkg);
+      const platformDir = getPlatformDir();
+      const npmBinary = join(rfdbDir, 'prebuilt', platformDir, 'rfdb-server');
+      if (existsSync(npmBinary)) {
+        return npmBinary;
+      }
+    } catch {
+      // @grafema/rfdb not installed
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Find rfdb-server binary.
+ *
+ * @param options - Search options
+ * @returns Path to binary or null if not found
+ */
+export function findRfdbBinary(options: FindBinaryOptions = {}): string | null {
+  return findBinary('rfdb-server', options);
+}
+
+/**
+ * Find grafema-orchestrator binary.
+ *
+ * @param options - Search options
+ * @returns Path to binary or null if not found
+ */
+export function findOrchestratorBinary(options: FindBinaryOptions = {}): string | null {
+  return findBinary('grafema-orchestrator', options);
+}
+
+/**
+ * Find an analyzer binary by name (e.g. "grafema-analyzer", "haskell-resolve").
+ *
+ * Simpler search than findBinary() — no env var or platform package lookup.
+ * Search order: ~/.grafema/bin/, ~/.local/bin/, ~/.cabal/bin/, system PATH.
+ */
+export function findAnalyzerBinary(binaryName: string): string | null {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+
+  // ~/.grafema/bin/ (lazy-downloaded)
+  if (home) {
+    const p = join(home, '.grafema', 'bin', binaryName);
+    if (existsSync(p)) return p;
+  }
+
+  // ~/.local/bin/
+  if (home) {
+    const p = join(home, '.local', 'bin', binaryName);
+    if (existsSync(p)) return p;
+  }
+
+  // ~/.cabal/bin/ (Haskell builds)
+  if (home) {
+    const p = join(home, '.cabal', 'bin', binaryName);
+    if (existsSync(p)) return p;
+  }
+
+  // System PATH
+  const pathDirs = (process.env.PATH || '').split(delimiter);
+  for (const dir of pathDirs) {
+    if (!dir) continue;
+    const p = join(dir, binaryName);
+    if (existsSync(p)) return p;
+  }
+
+  return null;
+}
+
+/**
+ * Get human-readable error message when binary not found.
+ */
+export function getBinaryNotFoundMessage(binaryName?: BinaryName): string {
+  const name = binaryName || 'rfdb-server';
+  const config = BINARY_CONFIG[name];
+  const platformDir = getPlatformDir();
+
+  return `${name} binary not found for ${platformDir}
+
+Options:
+1. Install the grafema package (includes all binaries):
+   npm install grafema
+
+2. Set environment variable:
+   export ${config.envVar}=/path/to/${name}
+
+3. Build from source:
+   cd packages/${config.monorepoPackage} && cargo build --release
+
+4. Install to system PATH or ~/.local/bin:
+   cp target/release/${name} ~/.local/bin/
+`;
+}

package/src/utils/lazyDownload.ts

@@ -0,0 +1,206 @@
+/**
+ * Lazy binary downloader for Grafema.
+ *
+ * Downloads Haskell analyzer binaries from GitHub Releases on first use.
+ * Binaries are cached in ~/.grafema/bin/ and reused across projects.
+ *
+ * Asset naming convention: {binary-name}-{platform}
+ * Example: grafema-analyzer-darwin-arm64
+ */
+
+import { existsSync, mkdirSync, chmodSync, renameSync, unlinkSync, createWriteStream } from 'fs';
+import { join } from 'path';
+import { get as httpsGet } from 'https';
+import type { IncomingMessage } from 'http';
+import { getPlatformDir } from './findRfdbBinary.js';
+
+const GITHUB_REPO = 'Disentinel/grafema';
+
+/** All analyzer binaries that can be lazy-downloaded. */
+const DOWNLOADABLE_BINARIES = [
+  'grafema-analyzer',
+  'grafema-resolve',
+  'haskell-analyzer',
+  'haskell-resolve',
+  'grafema-rust-analyzer',
+  'grafema-rust-resolve',
+  'grafema-java-analyzer',
+  'java-resolve',
+  'java-parser',
+  'grafema-kotlin-analyzer',
+  'kotlin-resolve',
+  'kotlin-parser',
+  'jvm-cross-resolve',
+  'grafema-python-analyzer',
+  'python-resolve',
+  'grafema-go-analyzer',
+  'go-resolve',
+  'go-parser',
+  'grafema-cpp-analyzer',
+  'cpp-resolve',
+];
+
+/**
+ * Get the directory where lazy-downloaded binaries are stored.
+ */
+export function getGrafemaBinDir(): string {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  return join(home, '.grafema', 'bin');
+}
+
+/**
+ * Check if a binary name is eligible for lazy download.
+ */
+export function isDownloadable(binaryName: string): boolean {
+  return DOWNLOADABLE_BINARIES.includes(binaryName);
+}
+
+/**
+ * Find a binary in ~/.grafema/bin/.
+ */
+export function findInGrafemaBin(binaryName: string): string | null {
+  const binDir = getGrafemaBinDir();
+  const p = join(binDir, binaryName);
+  return existsSync(p) ? p : null;
+}
+
+/**
+ * Simple HTTPS GET that follows redirects (GitHub uses 302 → S3).
+ */
+function httpsGetFollowRedirects(url: string): Promise<IncomingMessage> {
+  return new Promise((resolve, reject) => {
+    const req = httpsGet(url, { headers: { 'User-Agent': 'grafema-cli' } }, (res) => {
+      if (res.statusCode === 301 || res.statusCode === 302) {
+        const location = res.headers.location;
+        if (!location) return reject(new Error('Redirect without location'));
+        httpsGetFollowRedirects(location).then(resolve, reject);
+        return;
+      }
+      resolve(res);
+    });
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Find the latest binaries-v* release tag from GitHub API.
+ */
+async function findLatestReleaseTag(): Promise<string> {
+  const url = `https://api.github.com/repos/${GITHUB_REPO}/releases?per_page=30`;
+  const res = await httpsGetFollowRedirects(url);
+
+  const chunks: Buffer[] = [];
+  for await (const chunk of res) {
+    chunks.push(chunk as Buffer);
+  }
+  const body = Buffer.concat(chunks).toString('utf-8');
+
+  if (res.statusCode !== 200) {
+    throw new Error(`GitHub API returned ${res.statusCode}: ${body.slice(0, 200)}`);
+  }
+
+  const releases = JSON.parse(body) as Array<{ tag_name: string }>;
+  const binRelease = releases.find(r => r.tag_name.startsWith('binaries-v'));
+  if (!binRelease) {
+    throw new Error('No binaries-v* release found on GitHub');
+  }
+  return binRelease.tag_name;
+}
+
+/**
+ * Download a single binary from a GitHub Release.
+ *
+ * @param binaryName - e.g. "grafema-analyzer"
+ * @param tag - e.g. "binaries-v0.3.0-beta"
+ * @param onProgress - optional callback for download progress
+ * @returns Path to the downloaded binary
+ */
+export async function downloadBinary(
+  binaryName: string,
+  tag?: string,
+  onProgress?: (msg: string) => void,
+): Promise<string> {
+  const platform = getPlatformDir();
+  const assetName = `${binaryName}-${platform}`;
+  const binDir = getGrafemaBinDir();
+
+  // Ensure ~/.grafema/bin/ exists
+  if (!existsSync(binDir)) {
+    mkdirSync(binDir, { recursive: true });
+  }
+
+  const targetPath = join(binDir, binaryName);
+  const tmpPath = `${targetPath}.downloading`;
+
+  // Resolve tag
+  const releaseTag = tag || await findLatestReleaseTag();
+  const downloadUrl = `https://github.com/${GITHUB_REPO}/releases/download/${releaseTag}/${assetName}`;
+
+  const log = onProgress || (() => {});
+  log(`Downloading ${binaryName} for ${platform}...`);
+
+  // Download to temp file
+  const res = await httpsGetFollowRedirects(downloadUrl);
+
+  if (res.statusCode !== 200) {
+    throw new Error(
+      `Failed to download ${assetName}: HTTP ${res.statusCode}. ` +
+      `Check that release ${releaseTag} has asset ${assetName}.`
+    );
+  }
+
+  const contentLength = parseInt(res.headers['content-length'] || '0', 10);
+  const sizeMB = contentLength > 0 ? `${(contentLength / 1024 / 1024).toFixed(1)}MB` : 'unknown size';
+  log(`  ${assetName} (${sizeMB})`);
+
+  await new Promise<void>((resolve, reject) => {
+    const file = createWriteStream(tmpPath);
+    res.pipe(file);
+    file.on('finish', () => { file.close(); resolve(); });
+    file.on('error', (err) => { unlinkSync(tmpPath); reject(err); });
+    res.on('error', (err) => { unlinkSync(tmpPath); reject(err); });
+  });
+
+  // Atomic rename + make executable
+  renameSync(tmpPath, targetPath);
+  chmodSync(targetPath, 0o755);
+
+  log(`  Installed to ${targetPath}`);
+  return targetPath;
+}
+
+/**
+ * Ensure a binary exists, downloading it if missing and eligible.
+ *
+ * This is the main entry point for lazy downloading. Call it before
+ * spawning an analyzer binary. Returns the path if found or downloaded,
+ * null if the binary can't be obtained.
+ *
+ * @param binaryName - e.g. "grafema-analyzer"
+ * @param existingPath - path from findBinary() (null = not found locally)
+ * @param onProgress - optional callback for download progress
+ */
+export async function ensureBinary(
+  binaryName: string,
+  existingPath: string | null,
+  onProgress?: (msg: string) => void,
+): Promise<string | null> {
+  // Already found locally
+  if (existingPath) return existingPath;
+
+  // Check ~/.grafema/bin/ first (may have been downloaded previously)
+  const cached = findInGrafemaBin(binaryName);
+  if (cached) return cached;
+
+  // Not downloadable (e.g. rfdb-server, grafema-orchestrator — these must be in npm package)
+  if (!isDownloadable(binaryName)) return null;
+
+  // Download
+  try {
+    return await downloadBinary(binaryName, undefined, onProgress);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    (onProgress || console.error)(`Failed to download ${binaryName}: ${msg}`);
+    return null;
+  }
+}