@cassiomc1/forgeloop 1.10.1 → 1.10.2

package/src/adapters/ripwire/normalize.js

@@ -0,0 +1,352 @@
+import path from "node:path";
+
+import {
+  isPathWithin,
+} from "../../core/filesystem.js";
+import {
+  ADVISORY_CONTEXT_LIMITS,
+  normalizeAdvisoryRecallOptions,
+} from "../../core/advisory-context/constants.js";
+import {
+  E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+  E_ADVISORY_CONTEXT_RESULT_INVALID,
+} from "../../core/error-codes.js";
+
+const METADATA_KEYS = Object.freeze([
+  "at",
+  "bundle",
+  "capped",
+  "confidence",
+  "corpus",
+  "est_tokens",
+  "kept",
+  "lens",
+  "margin_pct",
+  "parse_health",
+  "scored",
+  "sigs_capped",
+  "sigs_shown",
+  "sigs_total",
+  "truncated",
+  "unindexed",
+  "ambiguous",
+  "unresolved",
+  "unsupported_languages",
+]);
+
+function adapterError(code, message) {
+  const error = new Error(message);
+  error.name = "RipwireAdapterError";
+  error.code = code;
+  return error;
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function boundedText(value, maxLength = 240) {
+  if (typeof value !== "string") return null;
+  if (value.length === 0 || /\p{Cc}/u.test(value)) return null;
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, Math.max(1, maxLength - 1))}…`;
+}
+
+function safeString(value) {
+  if (typeof value === "string") return value;
+  if (value === undefined || value === null) return "";
+  try {
+    return String(value);
+  } catch {
+    return null;
+  }
+}
+
+function fitText(value, maxLength) {
+  if (value.length <= maxLength) return value;
+  return `${value.slice(0, Math.max(1, maxLength - 1))}…`;
+}
+
+function metadataValue(value) {
+  if (typeof value === "string") return boundedText(value, 160);
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  if (typeof value === "boolean") return String(value);
+  return null;
+}
+
+function extractCandidateRows(raw) {
+  if (Array.isArray(raw.sigs)) return raw.sigs;
+  return null;
+}
+
+function normalizeReportedPath(reportedPath, projectPath) {
+  if (typeof reportedPath !== "string" || reportedPath.trim() === "" || /\p{Cc}/u.test(reportedPath)) {
+    return null;
+  }
+  const slashPath = reportedPath.replaceAll("\\", "/");
+  const windowsAbsolute = /^[A-Za-z]:\//u.test(slashPath) || slashPath.startsWith("//");
+  const posixAbsolute = slashPath.startsWith("/");
+  let relative = slashPath;
+
+  if (windowsAbsolute || posixAbsolute) {
+    if (!projectPath) return null;
+    const absolute = windowsAbsolute && process.platform !== "win32"
+      ? path.win32.normalize(slashPath)
+      : path.resolve(slashPath);
+    if (!isPathWithin(path.resolve(projectPath), absolute)) return null;
+    relative = path.relative(path.resolve(projectPath), absolute).replaceAll(path.sep, "/");
+  }
+
+  const segments = relative.split("/");
+  if (segments.some((segment) => segment === ".." || segment === "")) return null;
+  const normalized = path.posix.normalize(relative);
+  if (normalized === "." || normalized.startsWith("../") || path.posix.isAbsolute(normalized)) return null;
+  if (projectPath && !isPathWithin(path.resolve(projectPath), path.resolve(projectPath, normalized))) return null;
+  return normalized;
+}
+
+function rowPath(row) {
+  if (!isRecord(row)) return undefined;
+  return row.p ?? row.path ?? row.file ?? row.source ?? row.filePath;
+}
+
+function rowLine(row) {
+  const value = row.l ?? row.line ?? row.lineNumber;
+  if (value === undefined || value === null || value === "") return null;
+  if (!Number.isSafeInteger(value) || value < 1) return null;
+  return value;
+}
+
+function rowName(row) {
+  return row.n ?? row.name ?? row.symbol ?? row.id;
+}
+
+function rowSignature(row) {
+  return row.sig ?? row.signature ?? row.doc ?? row.text ?? row.annotation ?? row.body;
+}
+
+function rowRank(row) {
+  const value = row.r ?? row.rank;
+  return Number.isSafeInteger(value) && value > 0 ? value : null;
+}
+
+function rowScore(row) {
+  const value = row.k ?? row.score ?? row.relevance;
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function validConfidence(value) {
+  return typeof value === "number"
+    && Number.isFinite(value)
+    && value >= 0
+    && value <= 1;
+}
+
+function hasInvalidReportedLine(row, line) {
+  const reportedLine = row.l ?? row.line ?? row.lineNumber;
+  const lineWasReported = reportedLine !== undefined && reportedLine !== null && reportedLine !== "";
+  return lineWasReported && line === null;
+}
+
+function candidateSummary(row, signatureValue) {
+  const signature = boundedText(signatureValue, 1000);
+  const rank = rowRank(row);
+  const score = rowScore(row);
+  const annotations = [
+    rank === null ? null : `rank=${rank}`,
+    score === null ? null : `ranking_score=${score}`,
+    row.ambiguous === true ? "ambiguous=true" : null,
+    row.unresolved === true ? "unresolved=true" : null,
+  ].filter(Boolean);
+  const parts = [signature, ...annotations].filter(Boolean);
+  return parts.join(" | ") || "Ripwire returned a candidate without a signature";
+}
+
+function statusDetails(raw, totalCandidates, acceptedCandidates, rejectedCandidates, returnedCandidates) {
+  const details = [];
+  for (const key of METADATA_KEYS) {
+    const value = metadataValue(raw[key]);
+    if (value !== null) details.push(`${key}=${value}`);
+  }
+
+  const reportedTotal = Number.isSafeInteger(raw.sigs_total) ? raw.sigs_total : null;
+  const reportedShown = Number.isSafeInteger(raw.sigs_shown) ? raw.sigs_shown : null;
+  const capped = raw.capped === true || raw.truncated === true || raw.sigs_capped === true
+    || (reportedTotal !== null && reportedShown !== null && reportedShown < reportedTotal);
+  if (capped) details.push("output_capped_or_truncated=true");
+  if (raw.lens) details.push("unreported_lenses_remain_unknown=true");
+  if (raw.unindexed !== undefined) details.push("unindexed_content_is_not_proven_complete=true");
+  if (raw.ambiguous !== undefined || raw.unresolved !== undefined) details.push("ambiguous_or_unresolved_edges_may_be_missing=true");
+  if (rejectedCandidates > 0) details.push(`rejected_candidates=${rejectedCandidates}`);
+  if (totalCandidates === 0) details.push("no_symbol_candidates_returned; absence_is_not_proof_of_no_impact=true");
+  if (returnedCandidates === 0 && totalCandidates > 0) details.push("no_symbol_candidates_fit_the_requested_safety_or_budget=true");
+  return details;
+}
+
+function compactNotice(notice) {
+  return notice
+    .replace(/^adapter_omitted_candidates=/u, "omitted=")
+    .replace(/^candidate_text_shortened=/u, "shortened=");
+}
+
+function fitStatusWithSuffix(notices, suffix, maxLength) {
+  if (suffix.length > maxLength) return fitText(suffix, maxLength);
+  const prefix = notices.map(compactNotice).filter(Boolean).join("; ");
+  if (!prefix) return suffix;
+  const full = `${prefix}; ${suffix}`;
+  if (full.length <= maxLength) return full;
+  const first = `${prefix.split("; ", 1)[0]}; ${suffix}`;
+  return first.length <= maxLength ? first : suffix;
+}
+
+function buildStatusSummary(raw, totalCandidates, acceptedCandidates, rejectedCandidates, returnedCandidates, maxLength, notices = [], { noFit = false } = {}) {
+  const details = statusDetails(raw, totalCandidates, acceptedCandidates, rejectedCandidates, returnedCandidates);
+  const mandatory = `Ripwire advisory; approximate graph guidance only; no authority/evidence/action; index_completeness=unknown; candidates=${totalCandidates}; accepted=${acceptedCandidates}; returned=${returnedCandidates}`;
+  const complete = `${[...notices, mandatory, ...details].join("; ")}.`;
+  if (!noFit && complete.length <= maxLength) return complete;
+
+  const compactBase = noFit
+    ? "No symbol items fit; Ripwire advisory; approximate; completeness=unknown; diagnostics omitted."
+    : `Ripwire advisory; approximate; completeness=unknown; diagnostics_omitted=true; candidates=${totalCandidates}; returned=${returnedCandidates}.`;
+  if (compactBase.length <= maxLength) return fitStatusWithSuffix(notices, compactBase, maxLength);
+
+  const minimalBase = "Advisory; approximate; completeness=unknown; diagnostics omitted.";
+  return fitStatusWithSuffix(notices, minimalBase, maxLength);
+}
+
+function normalizeCandidate(row, {
+  projectPath,
+  sourcePathValidator,
+} = {}) {
+  if (!isRecord(row)) return { candidate: null, rejected: true };
+  const rawPath = rowPath(row);
+  const relativePath = normalizeReportedPath(rawPath, projectPath);
+  if (rawPath !== undefined && relativePath === null) return { candidate: null, rejected: true };
+  if (relativePath && sourcePathValidator) {
+    let safe = false;
+    try {
+      safe = sourcePathValidator(relativePath) === true;
+    } catch {
+      safe = false;
+    }
+    if (!safe) return { candidate: null, rejected: true };
+  }
+  const line = rowLine(row);
+  if (hasInvalidReportedLine(row, line)) return { candidate: null, rejected: true };
+  const sourceRef = relativePath ? `${relativePath}${line === null ? "" : `:${line}`}` : undefined;
+  const rawName = rowName(row);
+  const normalizedName = rawName === undefined || rawName === null ? "Ripwire candidate" : safeString(rawName);
+  const normalizedSignature = safeString(rowSignature(row) ?? "");
+  if (normalizedName === null || normalizedSignature === null) return { candidate: null, rejected: true };
+  const title = boundedText(normalizedName, 180)
+    ?? "Ripwire candidate";
+  const summary = candidateSummary(row, normalizedSignature);
+  const confidence = validConfidence(row.confidence) ? row.confidence : undefined;
+  return {
+    rejected: false,
+    candidate: {
+      title,
+      summary,
+      ...(sourceRef ? { sourceRef } : {}),
+      ...(confidence === undefined ? {} : { confidence }),
+    },
+  };
+}
+
+/**
+ * Convert Ripwire's documented --for --json shape into ForgeLoop advisory
+ * items. The status card is deliberate: the approximate graph, caps, omitted
+ * lenses, and unknown completeness must remain visible after core allowlist
+ * normalization discards provider-specific metadata.
+ */
+export function normalizeRipwireResult(raw, {
+  projectPath,
+  limit,
+  maxItemChars,
+  maxTotalChars,
+  timeoutMs,
+  sourcePathValidator,
+} = {}) {
+  if (!isRecord(raw)) {
+    throw adapterError(E_ADVISORY_CONTEXT_RESULT_INVALID, "Ripwire JSON result must be an object");
+  }
+  const rows = extractCandidateRows(raw);
+  if (!rows) {
+    throw adapterError(E_ADVISORY_CONTEXT_RESULT_INVALID, "Ripwire JSON result did not contain the supported flat sigs array");
+  }
+  if (rows.length > ADVISORY_CONTEXT_LIMITS.maxProviderReturnedItems) {
+    throw adapterError(
+      E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+      `Ripwire returned ${rows.length} candidates, exceeding the raw item ceiling of ${ADVISORY_CONTEXT_LIMITS.maxProviderReturnedItems}`,
+    );
+  }
+  const options = normalizeAdvisoryRecallOptions({ limit, maxItemChars, maxTotalChars, timeoutMs });
+  const normalizedCandidates = [];
+  const seen = new Set();
+  let rejectedCandidates = 0;
+
+  for (const row of rows) {
+    const normalized = normalizeCandidate(row, { projectPath, sourcePathValidator });
+    if (normalized.rejected || !normalized.candidate) {
+      rejectedCandidates += 1;
+      continue;
+    }
+    const key = [normalized.candidate.title, normalized.candidate.summary, normalized.candidate.sourceRef ?? ""].join("\u0000");
+    if (seen.has(key)) continue;
+    seen.add(key);
+    normalizedCandidates.push(normalized.candidate);
+  }
+
+  const preparedCandidates = normalizedCandidates.map((candidate) => {
+    const summary = fitText(candidate.summary, options.maxItemChars);
+    return {
+      ...candidate,
+      summary,
+      summaryShortened: summary.length < candidate.summary.length,
+    };
+  });
+
+  const itemChars = (item) => (item.title?.length ?? 0) + item.summary.length + (item.sourceRef?.length ?? 0);
+  let selectedCount = -1;
+  let selectedStatus = null;
+  const maxCandidateCount = Math.min(preparedCandidates.length, Math.max(0, options.limit - 1));
+  for (let count = maxCandidateCount; count >= 0; count -= 1) {
+    const returnedCandidates = preparedCandidates.slice(0, count);
+    const notices = [];
+    if (preparedCandidates.length > count) notices.push(`adapter_omitted_candidates=${preparedCandidates.length - count}`);
+    const shortenedCandidates = returnedCandidates.filter((candidate) => candidate.summaryShortened).length;
+    if (shortenedCandidates > 0) notices.push(`candidate_text_shortened=${shortenedCandidates}`);
+    if (rejectedCandidates > 0) notices.push(`rejected_candidates=${rejectedCandidates}`);
+    const noFit = count === 0 && rows.length > 0;
+    const status = {
+      title: "Ripwire advisory status",
+      summary: buildStatusSummary(
+        raw,
+        rows.length,
+        preparedCandidates.length,
+        rejectedCandidates,
+        count,
+        options.maxItemChars,
+        notices,
+        { noFit },
+      ),
+    };
+    const totalChars = status.title.length + status.summary.length
+      + returnedCandidates.reduce((total, candidate) => total + itemChars(candidate), 0);
+    if (totalChars <= options.maxTotalChars) {
+      selectedCount = count;
+      selectedStatus = status;
+      break;
+    }
+  }
+
+  if (selectedCount < 0 || !selectedStatus) {
+    throw adapterError(E_ADVISORY_CONTEXT_OUTPUT_LIMIT, "Ripwire advisory status cannot fit the requested output budget");
+  }
+
+  const items = [selectedStatus, ...preparedCandidates.slice(0, selectedCount)];
+  for (const item of items) delete item.summaryShortened;
+  return { items };
+}
+
+export { extractCandidateRows, normalizeReportedPath, rowPath as getRipwireRowPath };

package/src/adapters/ripwire/process.js

@@ -0,0 +1,248 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import path from "node:path";
+
+import {
+  E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+  E_ADVISORY_CONTEXT_PROVIDER_INVALID,
+  E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+  E_ADVISORY_CONTEXT_RESULT_INVALID,
+  E_ADVISORY_CONTEXT_TIMEOUT,
+} from "../../core/error-codes.js";
+
+export const RIPWIRE_PROCESS_LIMITS = Object.freeze({
+  maxStdoutBytes: 1024 * 1024,
+  maxStderrBytes: 64 * 1024,
+  terminationGraceMs: 100,
+});
+
+function processError(code, message) {
+  const error = new Error(message);
+  error.name = "RipwireProcessError";
+  error.code = code;
+  return error;
+}
+
+function assertSafeText(value, label) {
+  if (typeof value !== "string" || value.length === 0 || /\p{Cc}/u.test(value)) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, `${label} must be a non-empty portable string`);
+  }
+  return value;
+}
+
+function assertAbsolutePath(value, label) {
+  assertSafeText(value, label);
+  if (!path.isAbsolute(value)) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, `${label} must be an absolute path`);
+  }
+  return value;
+}
+
+function outputBytes(chunk) {
+  return Buffer.isBuffer(chunk) ? chunk.byteLength : Buffer.byteLength(String(chunk));
+}
+
+function terminateChild(child) {
+  if (!child || typeof child.kill !== "function") return;
+  try {
+    child.kill("SIGTERM");
+  } catch {
+    // The process may have exited between the limit check and kill.
+  }
+  setTimeout(() => {
+    try {
+      child.kill("SIGKILL");
+    } catch {
+      // Preserve the original timeout or output-limit error.
+    }
+  }, RIPWIRE_PROCESS_LIMITS.terminationGraceMs).unref?.();
+}
+
+function waitForChildClose(child) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(fallbackTimer);
+      resolve();
+    };
+    const finishAfterClose = () => {
+      // Windows can retain a child working directory for a short interval
+      // after close; allow the OS to release it before the caller tears down
+      // a temporary project tree.
+      setTimeout(finish, 500);
+    };
+    child.once?.("close", finishAfterClose);
+    const fallbackTimer = setTimeout(finish, RIPWIRE_PROCESS_LIMITS.terminationGraceMs + 1000);
+  });
+}
+
+function normalizeRunOptions({
+  cwd,
+  timeoutMs,
+  maxStdoutBytes,
+  maxStderrBytes,
+  spawnImpl,
+  env,
+} = {}) {
+  assertAbsolutePath(cwd, "Ripwire project path");
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire timeout must be a positive integer");
+  }
+  if (!Number.isSafeInteger(maxStdoutBytes) || maxStdoutBytes < 1) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire stdout limit must be a positive integer");
+  }
+  if (!Number.isSafeInteger(maxStderrBytes) || maxStderrBytes < 1) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire stderr limit must be a positive integer");
+  }
+  if (typeof spawnImpl !== "function") {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire spawn implementation must be a function");
+  }
+  if (env !== undefined && (!env || typeof env !== "object" || Array.isArray(env))) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire process environment must be an object");
+  }
+  return {
+    cwd,
+    timeoutMs,
+    maxStdoutBytes,
+    maxStderrBytes,
+    spawnImpl,
+    env,
+  };
+}
+
+/**
+ * Run one explicitly constructed Ripwire command.
+ *
+ * This helper is intentionally private to the adapter boundary: callers pass
+ * an absolute executable and an argv array, while this function always keeps
+ * shell execution disabled and never returns raw stderr in an error message.
+ */
+export function runRipwireCommand(executablePath, args, options = {}) {
+  assertAbsolutePath(executablePath, "Ripwire executable path");
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string" || /\p{Cc}/u.test(arg))) {
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_INVALID, "Ripwire arguments must be a portable string array");
+  }
+
+  const runOptions = normalizeRunOptions({
+    cwd: options.cwd,
+    timeoutMs: options.timeoutMs,
+    maxStdoutBytes: options.maxStdoutBytes ?? RIPWIRE_PROCESS_LIMITS.maxStdoutBytes,
+    maxStderrBytes: options.maxStderrBytes ?? RIPWIRE_PROCESS_LIMITS.maxStderrBytes,
+    spawnImpl: options.spawnImpl ?? nodeSpawn,
+    env: options.env,
+  });
+
+  const startedAt = Date.now();
+  let child;
+  try {
+    child = runOptions.spawnImpl(executablePath, [...args], {
+      cwd: runOptions.cwd,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+      ...(runOptions.env ? { env: { ...process.env, ...runOptions.env } } : {}),
+    });
+  } catch (error) {
+    throw processError(
+      E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+      error?.code === "ENOENT" ? "Ripwire executable is unavailable" : "Unable to start Ripwire",
+      error,
+    );
+  }
+
+  if (!child || !child.stdout || !child.stderr || typeof child.on !== "function") {
+    terminateChild(child);
+    throw processError(E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE, "Ripwire process did not expose piped stdout and stderr");
+  }
+
+  return new Promise((resolve, reject) => {
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    const stdoutChunks = [];
+    let settled = false;
+    let timer = null;
+
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      child.stdout?.removeAllListeners?.("data");
+      child.stderr?.removeAllListeners?.("data");
+    };
+
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      terminateChild(child);
+      child.stdout?.resume?.();
+      child.stderr?.resume?.();
+      waitForChildClose(child).then(() => reject(error));
+    };
+
+    const succeed = (code, signal) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (code !== 0) {
+        reject(processError(
+          E_ADVISORY_CONTEXT_RESULT_INVALID,
+          `Ripwire exited unsuccessfully (${code ?? "null"}/${signal ?? "none"})`,
+        ));
+        return;
+      }
+      resolve({
+        stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+        stderrBytes,
+        stdoutBytes,
+        durationMs: Math.max(0, Date.now() - startedAt),
+      });
+    };
+
+    child.stdout.on("data", (chunk) => {
+      stdoutBytes += outputBytes(chunk);
+      if (stdoutBytes > runOptions.maxStdoutBytes) {
+        fail(processError(
+          E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+          `Ripwire stdout exceeded ${runOptions.maxStdoutBytes} bytes`,
+        ));
+        return;
+      }
+      stdoutChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    });
+    child.stderr.on("data", (chunk) => {
+      stderrBytes += outputBytes(chunk);
+      if (stderrBytes > runOptions.maxStderrBytes) {
+        fail(processError(
+          E_ADVISORY_CONTEXT_OUTPUT_LIMIT,
+          `Ripwire stderr exceeded ${runOptions.maxStderrBytes} bytes`,
+        ));
+      }
+    });
+    child.on("error", (error) => {
+      fail(processError(
+        E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE,
+        error?.code === "ENOENT" ? "Ripwire executable is unavailable" : "Ripwire process failed",
+        error,
+      ));
+    });
+    child.on("close", (code, signal) => succeed(code, signal));
+    timer = setTimeout(() => {
+      fail(processError(
+        E_ADVISORY_CONTEXT_TIMEOUT,
+        `Ripwire exceeded the ${runOptions.timeoutMs}ms timeout`,
+      ));
+    }, runOptions.timeoutMs);
+  });
+}
+
+export function parseRipwireVersion(stdout) {
+  if (typeof stdout !== "string") {
+    throw processError(E_ADVISORY_CONTEXT_RESULT_INVALID, "Ripwire version output was not text");
+  }
+  const match = /^\s*ripwire\s+([^\s]+)(?:\s|$)/iu.exec(stdout);
+  if (!match) {
+    throw processError(E_ADVISORY_CONTEXT_RESULT_INVALID, "Ripwire version output did not contain a qualified version");
+  }
+  return match[1];
+}
+
+export { processError as ripwireProcessError };