ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/codegraph.mjs

@@ -0,0 +1,405 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { assertPathInside, atomicWrite } from "./fs-utils.mjs";
+import { readWorkspaceConfiguration } from "./workspace.mjs";
+
+const DOCTOR_TIMEOUT_MS = 5000;
+
+function windowsCommandInvocation(command, args) {
+  if (process.platform !== "win32") return { command, args };
+  const extension = path.extname(command).toLowerCase();
+  const explicit = path.isAbsolute(command) || command.includes("\\") || command.includes("/");
+  const candidates = explicit
+    ? [command]
+    : (process.env.PATH || "")
+      .split(path.delimiter)
+      .filter(Boolean)
+      .flatMap((directory) => [
+        path.join(directory.replace(/^"|"$/g, ""), `${command}.exe`),
+        path.join(directory.replace(/^"|"$/g, ""), `${command}.ps1`),
+      ]);
+  const resolved = extension ? command : candidates.find((candidate) => fs.existsSync(candidate));
+  if (resolved?.toLowerCase().endsWith(".ps1")) {
+    return {
+      command: "powershell.exe",
+      args: ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", resolved, ...args],
+    };
+  }
+  return { command: resolved || command, args };
+}
+
+function defaultRunner(args, options = {}) {
+  const command = options.command || "codegraph";
+  const invocation = windowsCommandInvocation(command, args);
+  return spawnSync(invocation.command, invocation.args, {
+    cwd: options.cwd,
+    encoding: "utf8",
+    windowsHide: true,
+    timeout: options.timeout,
+    env: {
+      ...process.env,
+      ...options.env,
+      CODEGRAPH_TELEMETRY: "0",
+      NO_COLOR: "1",
+    },
+  });
+}
+
+function normalizedPath(value) {
+  const resolved = path.resolve(value).replaceAll("\\", "/");
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function failureDetail(result) {
+  return String(result?.stderr || result?.stdout || result?.error?.message || "no valid output")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 500);
+}
+
+function statusResult(workspace, runner, command, env, timeout) {
+  const result = runner(["status", workspace.codeRoot, "--json"], {
+    cwd: workspace.codeRoot,
+    command,
+    env,
+    timeout,
+  });
+  let status = null;
+  if (result?.status === 0) {
+    try {
+      status = JSON.parse(result.stdout);
+    } catch {
+      status = null;
+    }
+  }
+  return { result, status };
+}
+
+function versionResult(workspace, runner, command, env, timeout) {
+  return runner(["--version"], {
+    cwd: workspace.codeRoot,
+    command,
+    env,
+    timeout,
+  });
+}
+
+function requireCommand(result, description) {
+  if (result?.error?.code === "ENOENT") {
+    throw new Error("CodeGraph CLI is unavailable; install it explicitly before running CodeGraph commands");
+  }
+  if (result?.status !== 0) {
+    throw new Error(`${description} failed: ${failureDetail(result)}`);
+  }
+}
+
+function indexDescriptor(codeRoot, indexPath) {
+  if (typeof indexPath !== "string" || !path.isAbsolute(indexPath)) {
+    throw new Error("CodeGraph index path must be a safe direct subdirectory of the code repository");
+  }
+  const absolutePath = path.resolve(indexPath);
+  const relativePath = path.relative(codeRoot, absolutePath);
+  if (!relativePath
+    || relativePath === ".."
+    || relativePath.startsWith(`..${path.sep}`)
+    || path.isAbsolute(relativePath)
+    || relativePath.includes(path.sep)
+    || !/^\.codegraph(?:-[A-Za-z0-9][A-Za-z0-9._-]*)?$/.test(relativePath)) {
+    throw new Error("CodeGraph index path must be a dedicated .codegraph or .codegraph-* directory in the code repository");
+  }
+  assertPathInside(codeRoot, absolutePath);
+  return {
+    absolutePath,
+    relativePath,
+    excludeEntry: `/${relativePath}/`,
+  };
+}
+
+function configuredIndexDescriptor(codeRoot, env) {
+  const configured = typeof env.CODEGRAPH_DIR === "string" ? env.CODEGRAPH_DIR.trim() : "";
+  const directoryName = configured || ".codegraph";
+  return indexDescriptor(codeRoot, path.join(codeRoot, directoryName));
+}
+
+function indexInitialized(codeRoot, index) {
+  if (!fs.existsSync(index.absolutePath)) return false;
+  assertPathInside(codeRoot, index.absolutePath);
+  if (!fs.statSync(index.absolutePath).isDirectory()) return false;
+  const database = path.join(index.absolutePath, "codegraph.db");
+  if (!fs.existsSync(database)) return false;
+  assertPathInside(codeRoot, database);
+  return fs.statSync(database).isFile();
+}
+
+function gitCommand(codeRoot, args) {
+  return spawnSync("git", args, {
+    cwd: codeRoot,
+    encoding: "utf8",
+    windowsHide: true,
+    timeout: DOCTOR_TIMEOUT_MS,
+  });
+}
+
+function requireGitCommand(result, description) {
+  if (result?.error?.code === "ENOENT") {
+    throw new Error(`${description} failed: Git CLI is unavailable`);
+  }
+  if (result?.status !== 0) {
+    throw new Error(`${description} failed: ${failureDetail(result)}`);
+  }
+}
+
+function trackedIndexPaths(codeRoot, index) {
+  const tracked = gitCommand(codeRoot, [
+    "ls-files",
+    "--",
+    index.relativePath,
+    `${index.relativePath}/**`,
+  ]);
+  requireGitCommand(tracked, "Checking the CodeGraph index Git boundary");
+  return tracked.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+
+function localGitExcludeFile(codeRoot) {
+  const gitDirectory = gitCommand(codeRoot, ["rev-parse", "--git-dir"]);
+  requireGitCommand(gitDirectory, "Resolving the code repository Git directory");
+  const absoluteGitDirectory = path.resolve(codeRoot, gitDirectory.stdout.trim());
+  const relativeGitDirectory = path.relative(codeRoot, absoluteGitDirectory);
+  if (!relativeGitDirectory
+    || relativeGitDirectory === ".."
+    || relativeGitDirectory.startsWith(`..${path.sep}`)
+    || path.isAbsolute(relativeGitDirectory)) {
+    throw new Error("CodeGraph setup requires the configured code repository to own its local Git directory");
+  }
+  try {
+    assertPathInside(codeRoot, absoluteGitDirectory);
+  } catch {
+    throw new Error("CodeGraph setup requires the configured code repository to own its local Git directory");
+  }
+  return path.join(absoluteGitDirectory, "info", "exclude");
+}
+
+function requireIndexIgnored(codeRoot, index) {
+  const ignored = gitCommand(codeRoot, [
+    "check-ignore",
+    "--quiet",
+    "--no-index",
+    "--",
+    `${index.relativePath}/`,
+  ]);
+  if (ignored?.status === 1) {
+    throw new Error(`CodeGraph index ${index.excludeEntry} is not ignored by the code repository`);
+  }
+  requireGitCommand(ignored, "Checking whether the CodeGraph index is ignored");
+}
+
+function inspectIndexBoundary(codeRoot, index, options = {}) {
+  try {
+    localGitExcludeFile(codeRoot);
+    const tracked = trackedIndexPaths(codeRoot, index);
+    if (tracked.length) {
+      return `CodeGraph index contains tracked paths under ${index.excludeEntry}: ${tracked.slice(0, 5).join(", ")}`;
+    }
+    if (options.requireIgnored) {
+      requireIndexIgnored(codeRoot, index);
+    }
+    return null;
+  } catch (error) {
+    return error.message;
+  }
+}
+
+function ensureLocalIndexExclude(codeRoot, index) {
+  const excludeFile = localGitExcludeFile(codeRoot);
+  const existed = fs.existsSync(excludeFile);
+  const existing = existed ? fs.readFileSync(excludeFile, "utf8") : "";
+  const entry = index.excludeEntry;
+  if (existing.split(/\r?\n/).some((line) => line.trim() === entry)) {
+    return { changed: false, excludeFile, existed, existing };
+  }
+  const separator = existing && !existing.endsWith("\n") ? "\n" : "";
+  atomicWrite(excludeFile, `${existing}${separator}${entry}\n`);
+  return { changed: true, excludeFile, existed, existing };
+}
+
+function restoreLocalIndexExclude(change) {
+  if (!change.changed) return;
+  if (change.existed) {
+    atomicWrite(change.excludeFile, change.existing);
+  } else {
+    fs.unlinkSync(change.excludeFile);
+  }
+}
+
+export function inspectCodeGraph(workspaceRoot, options = {}) {
+  const workspace = readWorkspaceConfiguration(workspaceRoot);
+  const runner = options.runner || defaultRunner;
+  const env = { ...process.env, ...options.env };
+  const base = { required: false, scope: "codegraph" };
+  let index = null;
+  let initialized = false;
+  try {
+    index = configuredIndexDescriptor(workspace.codeRoot, env);
+    initialized = indexInitialized(workspace.codeRoot, index);
+  } catch (error) {
+    return {
+      ...base,
+      ok: false,
+      message: error.message,
+    };
+  }
+  const boundaryIssue = inspectIndexBoundary(workspace.codeRoot, index, {
+    requireIgnored: initialized,
+  });
+  if (boundaryIssue) {
+    return {
+      ...base,
+      ok: false,
+      message: boundaryIssue,
+    };
+  }
+  let version = null;
+  try {
+    version = versionResult(
+      workspace,
+      runner,
+      options.command,
+      env,
+      options.timeout ?? DOCTOR_TIMEOUT_MS,
+    );
+  } catch (error) {
+    return {
+      ...base,
+      ok: false,
+      message: `CodeGraph version check failed for the code repository: ${error.message}`,
+    };
+  }
+  if (version?.error?.code === "ENOENT") {
+    return {
+      ...base,
+      ok: false,
+      message: "CodeGraph CLI is unavailable; code intelligence will fall back to Semble and direct source search",
+    };
+  }
+  if (version?.status !== 0) {
+    return {
+      ...base,
+      ok: false,
+      message: `CodeGraph version check failed for the code repository: ${failureDetail(version)}`,
+    };
+  }
+  const versionText = version.stdout.trim() || "unknown";
+  if (!initialized) {
+    return {
+      ...base,
+      ok: false,
+      message: `CodeGraph ${versionText} index is not initialized for the code repository; run ai-delivery codegraph setup for this workspace`,
+    };
+  }
+  return {
+    ...base,
+    ok: true,
+    message: `CodeGraph ${versionText} index files are present and isolated in the configured code repository`,
+  };
+}
+
+export function runCodeGraphAction(workspaceRoot, action, options = {}) {
+  if (!new Set(["setup", "sync"]).has(action)) throw new Error(`Unknown CodeGraph action: ${action}`);
+  const workspace = readWorkspaceConfiguration(workspaceRoot);
+  const runner = options.runner || defaultRunner;
+  const env = { ...process.env, ...options.env };
+  const index = configuredIndexDescriptor(workspace.codeRoot, env);
+  const initializedBefore = indexInitialized(workspace.codeRoot, index);
+  const boundaryIssue = inspectIndexBoundary(workspace.codeRoot, index);
+  if (boundaryIssue) throw new Error(boundaryIssue);
+  const version = versionResult(workspace, runner, options.command, env);
+  requireCommand(version, "CodeGraph version check");
+  const versionText = version.stdout.trim() || null;
+  if (action === "sync" && !initializedBefore) {
+    throw new Error("CodeGraph index is not initialized; run ai-delivery codegraph setup first");
+  }
+
+  const codeRepository = {
+    repo_id: workspace.configuration.code_repository.repo_id,
+    path: workspace.configuration.code_repository.path,
+    absolute_path: workspace.codeRoot,
+  };
+  if (options.dryRun) {
+    const plannedActions = [];
+    if (action === "setup") plannedActions.push("disable CodeGraph telemetry");
+    plannedActions.push(`exclude ${index.excludeEntry} in the code repository local Git config`);
+    if (action === "setup" && !initializedBefore) {
+      plannedActions.push("initialize the CodeGraph index");
+    } else if (action === "sync") {
+      plannedActions.push("synchronize the CodeGraph index");
+    }
+    return {
+      provider: "codegraph",
+      action,
+      dry_run: true,
+      initialized: initializedBefore,
+      would_initialize: action === "setup" && !initializedBefore,
+      telemetry: action === "setup" ? "would-disable" : "disabled-for-command",
+      version: versionText,
+      index_path: index.absolutePath,
+      planned_actions: plannedActions,
+      code_repository: codeRepository,
+    };
+  }
+
+  const excludeChange = ensureLocalIndexExclude(workspace.codeRoot, index);
+  try {
+    requireIndexIgnored(workspace.codeRoot, index);
+  } catch (error) {
+    restoreLocalIndexExclude(excludeChange);
+    throw error;
+  }
+  if (action === "setup") {
+    const telemetry = runner(["telemetry", "off"], {
+      cwd: workspace.codeRoot,
+      command: options.command,
+      env,
+    });
+    requireCommand(telemetry, "Disabling CodeGraph telemetry");
+  }
+  if (action === "setup" && !initializedBefore) {
+    const initialized = runner(["init", workspace.codeRoot], {
+      cwd: workspace.codeRoot,
+      command: options.command,
+      env,
+    });
+    requireCommand(initialized, "CodeGraph initialization");
+  } else if (action === "sync") {
+    const synchronized = runner(["sync", workspace.codeRoot], {
+      cwd: workspace.codeRoot,
+      command: options.command,
+      env,
+    });
+    requireCommand(synchronized, "CodeGraph synchronization");
+  }
+
+  const after = statusResult(workspace, runner, options.command, env);
+  requireCommand(after.result, "CodeGraph status verification");
+  if (!after.status?.initialized
+    || normalizedPath(after.status.projectPath) !== normalizedPath(workspace.codeRoot)) {
+    throw new Error(`CodeGraph ${action} did not produce a valid index for the configured code repository`);
+  }
+  const finalIndex = indexDescriptor(workspace.codeRoot, after.status.indexPath);
+  if (normalizedPath(finalIndex.absolutePath) !== normalizedPath(index.absolutePath)) {
+    throw new Error(`CodeGraph ${action} changed the configured index path unexpectedly`);
+  }
+  const finalBoundaryIssue = inspectIndexBoundary(workspace.codeRoot, finalIndex, {
+    requireIgnored: true,
+  });
+  if (finalBoundaryIssue) throw new Error(finalBoundaryIssue);
+  return {
+    provider: "codegraph",
+    action,
+    initialized: true,
+    telemetry: action === "setup" ? "off" : "disabled-for-command",
+    version: after.status.version || versionText,
+    index_path: finalIndex.absolutePath,
+    code_repository: codeRepository,
+  };
+}