rankforge 0.3.0

package/src/repo-detect.mjs

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import path from "node:path";
+import { discoverStaticRoutes } from "./repo-routes.mjs";
+
+const staticDirCandidates = ["dist", "build", "out", "public"];
+
+const frameworkSignals = [
+  ["next", "next"],
+  ["astro", "astro"],
+  ["@sveltejs/kit", "@sveltejs/kit"],
+  ["@remix-run/node", "@remix-run/node"],
+  ["vite", "vite"],
+];
+
+const readPackageJson = (repoRoot) => {
+  const packageJsonPath = path.join(repoRoot, "package.json");
+  if (!fs.existsSync(packageJsonPath)) return null;
+  return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+};
+
+const detectPackageManager = (repoRoot) => {
+  if (fs.existsSync(path.join(repoRoot, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(repoRoot, "yarn.lock"))) return "yarn";
+  if (fs.existsSync(path.join(repoRoot, "package-lock.json"))) return "npm";
+  if (fs.existsSync(path.join(repoRoot, "package.json"))) return "npm";
+  return null;
+};
+
+const scriptCommand = (packageManager, scriptName, packageJson) => {
+  if (!packageManager || !packageJson?.scripts?.[scriptName]) return null;
+  return `${packageManager} run ${scriptName}`;
+};
+
+const dependenciesFor = (packageJson) => ({
+  ...packageJson?.dependencies,
+  ...packageJson?.devDependencies,
+});
+
+const detectFramework = (packageJson, hasStaticOutput) => {
+  const dependencies = dependenciesFor(packageJson);
+  for (const [dependencyName, framework] of frameworkSignals) {
+    if (dependencies[dependencyName]) {
+      return { detectedFramework: framework, confidence: "high" };
+    }
+  }
+
+  if (packageJson) {
+    return { detectedFramework: "generic-node", confidence: "medium" };
+  }
+
+  if (hasStaticOutput) {
+    return { detectedFramework: "generic-static", confidence: "medium" };
+  }
+
+  return { detectedFramework: null, confidence: "low" };
+};
+
+const detectStaticDir = (repoRoot) => {
+  for (const dirRelative of staticDirCandidates) {
+    const dir = path.join(repoRoot, dirRelative);
+    if (fs.existsSync(path.join(dir, "index.html"))) {
+      return { staticDir: dir, staticDirRelative: dirRelative };
+    }
+  }
+
+  return { staticDir: null, staticDirRelative: null };
+};
+
+export const detectRepo = (repoRoot, options = {}) => {
+  const resolvedRepoRoot = path.resolve(repoRoot);
+  const packageJson = options.packageJson ?? readPackageJson(resolvedRepoRoot);
+  const packageManager = detectPackageManager(resolvedRepoRoot);
+  const { staticDir, staticDirRelative } = detectStaticDir(resolvedRepoRoot);
+  const { detectedFramework, confidence } = detectFramework(packageJson, Boolean(staticDir));
+
+  return {
+    repoRoot: resolvedRepoRoot,
+    detectedFramework,
+    confidence,
+    packageManager,
+    buildCommand: scriptCommand(packageManager, "build", packageJson),
+    previewCommand: scriptCommand(packageManager, "preview", packageJson),
+    staticDir,
+    staticDirRelative,
+    routeSources: staticDir ? discoverStaticRoutes(staticDir) : [],
+  };
+};

package/src/repo-findings.mjs

@@ -0,0 +1,9 @@
+export const sourceFinding = ({ id, severity = "P1", message, evidence, recommendation, confidence = "high", details }) => ({
+  id,
+  severity,
+  message,
+  evidence,
+  recommendation,
+  confidence,
+  ...(details ? { details } : {}),
+});

package/src/repo-manifests.mjs

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import path from "node:path";
+import { sourceFinding } from "./repo-findings.mjs";
+
+const manifestConfigs = {
+  next: {
+    type: "next_prerender_manifest",
+    relativePath: path.join(".next", "prerender-manifest.json"),
+    routesFor: (json) =>
+      json?.routes && typeof json.routes === "object" && !Array.isArray(json.routes) ? Object.keys(json.routes) : null,
+  },
+};
+
+const normalizeRoute = (route) => {
+  if (typeof route !== "string") return null;
+  const cleanRoute = route.trim();
+  if (!cleanRoute) return null;
+  const withLeadingSlash = cleanRoute.startsWith("/") ? cleanRoute : `/${cleanRoute}`;
+  if (withLeadingSlash === "/") return "/";
+  if (withLeadingSlash.endsWith("/") || withLeadingSlash.endsWith(".html")) return withLeadingSlash;
+  return `${withLeadingSlash}/`;
+};
+
+const routeEntry = (route) => {
+  if (typeof route !== "string") return null;
+  const cleanRoute = route.trim();
+  const normalizedRoute = normalizeRoute(cleanRoute);
+  if (!normalizedRoute) return null;
+
+  const withLeadingSlash = cleanRoute.startsWith("/") ? cleanRoute : `/${cleanRoute}`;
+  return {
+    route: normalizedRoute,
+    extensionless: withLeadingSlash !== "/" && !withLeadingSlash.endsWith("/") && !withLeadingSlash.endsWith(".html"),
+  };
+};
+
+const uniqueRouteEntries = (routes) => {
+  const entries = [];
+  const seen = new Set();
+  for (const route of routes) {
+    const entry = routeEntry(route);
+    if (!entry) continue;
+    const key = `${entry.route}:${entry.extensionless ? "extensionless" : "explicit"}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    entries.push(entry);
+  }
+  return entries;
+};
+
+const uniqueNormalizedRoutes = (routes) => {
+  const normalized = [];
+  const seen = new Set();
+  for (const { route } of routes) {
+    if (seen.has(route)) continue;
+    seen.add(route);
+    normalized.push(route);
+  }
+  return normalized;
+};
+
+const uniqueNormalizedRouteStrings = (routes) => {
+  const normalized = [];
+  const seen = new Set();
+  for (const route of routes) {
+    const normalizedRoute = normalizeRoute(route);
+    if (!normalizedRoute || seen.has(normalizedRoute)) continue;
+    seen.add(normalizedRoute);
+    normalized.push(normalizedRoute);
+  }
+  return normalized;
+};
+
+const isPathInside = (root, candidate) => {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+
+const htmlPathsForRoute = (staticDir, { route, extensionless = false }) => {
+  if (!staticDir) return [];
+  const safePaths = (candidates) => candidates.filter((candidate) => isPathInside(staticDir, candidate));
+  if (route === "/") return safePaths([path.join(staticDir, "index.html")]);
+
+  const relativeRoute = route.startsWith("/") ? route.slice(1) : route;
+  if (relativeRoute.endsWith(".html")) return safePaths([path.join(staticDir, relativeRoute)]);
+  const directoryHtmlPath = path.join(staticDir, relativeRoute, "index.html");
+  if (!extensionless) return safePaths([directoryHtmlPath]);
+  return safePaths([directoryHtmlPath, path.join(staticDir, relativeRoute.replace(/\/$/, ".html"))]);
+};
+
+const hasGeneratedHtmlForRoute = (staticDir, entry) =>
+  htmlPathsForRoute(staticDir, entry).some((htmlPath) => fs.existsSync(htmlPath) && fs.statSync(htmlPath).isFile());
+
+const extensionlessHtmlRoute = (route) => (route !== "/" && route.endsWith("/") ? `${route.slice(0, -1)}.html` : null);
+
+const isStaticRouteListed = (staticRoute, manifestEntries) => {
+  for (const entry of manifestEntries) {
+    if (entry.route === staticRoute) return true;
+    if (entry.extensionless && extensionlessHtmlRoute(entry.route) === staticRoute) return true;
+  }
+  return false;
+};
+
+const invalidManifestFinding = (manifestPath, error) =>
+  sourceFinding({
+    id: "repo.route_manifest_invalid",
+    message: "Framework route manifest could not be parsed.",
+    evidence: manifestPath,
+    recommendation: "Regenerate the framework build output and rerun the repository audit.",
+    details: { message: error?.message },
+  });
+
+const manifestRouteMissingFinding = (route) =>
+  sourceFinding({
+    id: "repo.manifest_route_missing",
+    message: "Framework route manifest lists a route that is missing from static output.",
+    evidence: route,
+    recommendation: "Ensure the framework build emits this route or remove it from generated route metadata.",
+  });
+
+const staticRouteUnlistedFinding = (route) =>
+  sourceFinding({
+    id: "repo.static_route_unlisted",
+    message: "Static output includes a route that is not listed in the framework route manifest.",
+    evidence: route,
+    recommendation: "Confirm the generated route is intentional and represented in framework route metadata.",
+  });
+
+export const analyzeFrameworkRouteManifests = ({ repoPath, staticDir, detectedFramework, staticRoutes = [] }) => {
+  const config = manifestConfigs[detectedFramework];
+  const frameworkManifests = [];
+  const sourceFindings = [];
+  if (!config) return { frameworkManifests, sourceFindings };
+
+  const manifestPath = path.join(repoPath, config.relativePath);
+  if (!fs.existsSync(manifestPath)) return { frameworkManifests, sourceFindings };
+
+  let json;
+  try {
+    json = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    return {
+      frameworkManifests,
+      sourceFindings: [invalidManifestFinding(manifestPath, error)],
+    };
+  }
+
+  const routes = config.routesFor(json);
+  if (!routes) return { frameworkManifests, sourceFindings };
+
+  const manifestEntries = uniqueRouteEntries(routes);
+  const manifestRoutes = uniqueNormalizedRoutes(manifestEntries);
+  frameworkManifests.push({
+    type: config.type,
+    path: manifestPath,
+    routes: manifestRoutes,
+  });
+
+  const staticRouteSet = new Set(uniqueNormalizedRouteStrings(staticRoutes.map((route) => route.route)));
+
+  for (const entry of manifestEntries) {
+    if (!hasGeneratedHtmlForRoute(staticDir, entry)) sourceFindings.push(manifestRouteMissingFinding(entry.route));
+  }
+  for (const route of staticRouteSet) {
+    if (!isStaticRouteListed(route, manifestEntries)) sourceFindings.push(staticRouteUnlistedFinding(route));
+  }
+
+  return { frameworkManifests, sourceFindings };
+};

package/src/repo-process.mjs

@@ -0,0 +1,298 @@
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { setTimeout as sleep } from "node:timers/promises";
+import { fetchWithGuards } from "./io-guards.mjs";
+
+const outputCaptureLimitBytes = 64 * 1024;
+const pollIntervalMs = 50;
+const fetchAttemptTimeoutMs = 500;
+const preflightTimeoutMs = 250;
+const shutdownGraceMs = 500;
+
+const isExited = (child) => child.exitCode !== null || child.signalCode !== null;
+
+const waitForExit = async (child, timeoutMs) => {
+  if (isExited(child)) {
+    return true;
+  }
+
+  let timer;
+  try {
+    return await Promise.race([
+      once(child, "exit").then(() => true),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), timeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+const killChild = (child, signal) => {
+  if (!child.pid || isExited(child)) {
+    return;
+  }
+
+  try {
+    if (process.platform === "win32") {
+      child.kill(signal);
+    } else {
+      process.kill(-child.pid, signal);
+    }
+  } catch (error) {
+    if (error?.code !== "ESRCH") {
+      throw error;
+    }
+  }
+};
+
+const capStringByBytes = (value, maxBytes) => {
+  if (Buffer.byteLength(value) <= maxBytes) {
+    return value;
+  }
+  return Buffer.from(value).subarray(-maxBytes).toString();
+};
+
+const appendCappedChunk = (chunks, chunk) => {
+  const capped = capStringByBytes(`${chunks.join("")}${String(chunk)}`, outputCaptureLimitBytes);
+  chunks.splice(0, chunks.length, capped);
+};
+
+const stderrTail = (stderr) => {
+  const tail = stderr.join("").trim();
+  return tail ? ` Stderr: ${tail}` : "";
+};
+
+const previewError = (message, preview) => {
+  const error = new Error(message);
+  error.preview = preview;
+  return error;
+};
+
+const earlyExitError = (preview, code, signal) =>
+  previewError(
+    `Preview command exited before server became reachable (${code === null ? `signal ${signal}` : `code ${code}`}).${stderrTail(preview.stderr)}`,
+    preview,
+  );
+
+const commandExecutionDisabledError = () =>
+  new Error("Restricted security mode disables local command execution for repo audits.");
+
+const commandError = (message, commandResult) => {
+  const error = new Error(message);
+  error.commandResult = commandResult;
+  return error;
+};
+
+export const runCommand = async ({ command, cwd, timeoutMs = 120000, label = "Command", security }) => {
+  if (!command) {
+    throw new Error(`${label} command is required.`);
+  }
+  if (security?.mode === "restricted") {
+    throw commandExecutionDisabledError();
+  }
+
+  const child = spawn(command, {
+    cwd,
+    shell: true,
+    detached: process.platform !== "win32",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  const startedAt = Date.now();
+  const commandResult = {
+    command,
+    stdout: [],
+    stderr: [],
+    exitCode: null,
+    signal: null,
+    durationMs: 0,
+    timedOut: false,
+  };
+
+  child.stdout?.on("data", (chunk) => appendCappedChunk(commandResult.stdout, chunk));
+  child.stderr?.on("data", (chunk) => appendCappedChunk(commandResult.stderr, chunk));
+
+  let timeout;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeout = setTimeout(() => {
+      commandResult.timedOut = true;
+      void (async () => {
+        try {
+          await stopPreview({ child });
+        } catch {
+          // Keep the timeout error as the actionable failure.
+        }
+        commandResult.durationMs = Date.now() - startedAt;
+        reject(commandError(`${label} command timed out after ${timeoutMs} ms.`, commandResult));
+      })();
+    }, timeoutMs);
+  });
+
+  const exitPromise = new Promise((resolve, reject) => {
+    child.once("error", (error) => {
+      commandResult.durationMs = Date.now() - startedAt;
+      reject(commandError(`${label} command failed to start: ${error.message}`, commandResult));
+    });
+    child.once("close", (code, signal) => {
+      commandResult.exitCode = code;
+      commandResult.signal = signal;
+      commandResult.durationMs = Date.now() - startedAt;
+      if (commandResult.timedOut) {
+        return;
+      }
+      if (code === 0) {
+        resolve(commandResult);
+        return;
+      }
+      reject(
+        commandError(
+          `${label} command exited with ${code === null ? `signal ${signal}` : `code ${code}`}.`,
+          commandResult,
+        ),
+      );
+    });
+  });
+
+  try {
+    return await Promise.race([exitPromise, timeoutPromise]);
+  } finally {
+    clearTimeout(timeout);
+  }
+};
+
+const isSecurityGuardError = (error) => String(error?.message || "").startsWith("Restricted security mode ");
+
+export const waitForHttp = async (url, options = {}) => {
+  const timeoutMs = options.timeoutMs ?? 30000;
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+
+  while (true) {
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      break;
+    }
+
+    const attemptTimeoutMs = Math.min(fetchAttemptTimeoutMs, remainingMs);
+
+    try {
+      const response = await fetchWithGuards(url, {
+        security: options.security,
+        limits: { ...(options.limits || {}), timeoutMs: attemptTimeoutMs },
+        fetchOptions: { redirect: "manual" },
+      });
+      if (response.status < 500) {
+        await response.body?.cancel();
+        return;
+      }
+      await response.body?.cancel();
+      lastError = new Error(`HTTP ${response.status}`);
+    } catch (error) {
+      if (isSecurityGuardError(error)) throw error;
+      lastError = error;
+    }
+
+    await sleep(Math.min(pollIntervalMs, Math.max(0, deadline - Date.now())));
+  }
+
+  const suffix = lastError?.message ? ` Last error: ${lastError.message}` : "";
+  throw new Error(`Preview server did not become reachable at ${url}.${suffix}`);
+};
+
+export const startPreview = async ({ command, cwd, previewUrl, timeoutMs = 30000, security, limits }) => {
+  if (!command) {
+    throw new Error("--preview-command is required for preview repo audits.");
+  }
+  if (!previewUrl) {
+    throw new Error("--preview-url is required for preview repo audits.");
+  }
+  if (security?.mode === "restricted") {
+    throw commandExecutionDisabledError();
+  }
+
+  let previewUrlAlreadyReachable = false;
+  try {
+    await waitForHttp(previewUrl, { timeoutMs: preflightTimeoutMs, security, limits });
+    previewUrlAlreadyReachable = true;
+  } catch (error) {
+    if (isSecurityGuardError(error)) throw error;
+    previewUrlAlreadyReachable = false;
+  }
+
+  if (previewUrlAlreadyReachable) {
+    throw new Error(`Preview URL is already reachable before starting command: ${previewUrl}`);
+  }
+
+  const child = spawn(command, {
+    cwd,
+    shell: true,
+    detached: process.platform !== "win32",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  const preview = {
+    child,
+    url: previewUrl,
+    stdout: [],
+    stderr: [],
+  };
+
+  child.stdout?.on("data", (chunk) => appendCappedChunk(preview.stdout, chunk));
+  child.stderr?.on("data", (chunk) => appendCappedChunk(preview.stderr, chunk));
+
+  const startupError = new Promise((_, reject) => {
+    child.once("error", (error) => {
+      reject(previewError(`Preview command failed to start: ${error.message}`, preview));
+    });
+    child.once("close", (code, signal) => {
+      reject(earlyExitError(preview, code, signal));
+    });
+  });
+
+  try {
+    await Promise.race([waitForHttp(previewUrl, { timeoutMs, security, limits }), startupError]);
+    if (isExited(child)) {
+      throw earlyExitError(preview, child.exitCode, child.signalCode);
+    }
+  } catch (error) {
+    try {
+      await stopPreview(preview);
+    } catch {
+      // Preserve the startup failure, which is the actionable error for callers.
+    }
+    error.preview ??= preview;
+    throw error;
+  }
+
+  return preview;
+};
+
+export const stopPreview = async (preview) => {
+  const child = preview?.child;
+  if (!child || isExited(child)) {
+    return;
+  }
+
+  if (preview.stopPromise) {
+    return preview.stopPromise;
+  }
+
+  preview.stopPromise = (async () => {
+    if (isExited(child)) {
+      return;
+    }
+
+    killChild(child, "SIGTERM");
+    const terminated = await waitForExit(child, shutdownGraceMs);
+    if (terminated || isExited(child)) {
+      return;
+    }
+
+    killChild(child, "SIGKILL");
+    await waitForExit(child, shutdownGraceMs);
+  })();
+
+  return preview.stopPromise;
+};

package/src/repo-routes.mjs

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const ordinalCompare = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+
+const htmlFiles = (dir) => {
+  const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((left, right) => ordinalCompare(left.name, right.name));
+  const files = [];
+
+  for (const entry of entries) {
+    const itemPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...htmlFiles(itemPath));
+      continue;
+    }
+    if (entry.isFile() && entry.name.endsWith(".html")) files.push(itemPath);
+  }
+
+  return files;
+};
+
+const routeFor = (root, file) => {
+  const relative = path.relative(root, file);
+  const parsed = path.parse(relative);
+  const routePath = relative.split(path.sep).join("/");
+
+  if (routePath === "index.html") return "/";
+  if (parsed.base === "index.html") return `/${parsed.dir.split(path.sep).join("/")}/`;
+  return `/${routePath}`;
+};
+
+export const discoverStaticRoutes = (staticDir) => {
+  const root = path.resolve(staticDir);
+
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`Static directory does not exist or is not a directory: ${root}`);
+  }
+
+  return htmlFiles(root)
+    .map((file) => ({
+      type: "static_html",
+      route: routeFor(root, file),
+      path: file,
+    }))
+    .sort((left, right) => ordinalCompare(left.route, right.route) || ordinalCompare(left.path, right.path));
+};