@chappibunny/repolens 1.15.4 → 1.16.0

package/src/core/scan.js

@@ -5,6 +5,8 @@ import { info, warn } from "../utils/logger.js";
 import { trackScan } from "../utils/telemetry.js";
 import { detectMonorepo } from "../analyzers/monorepo-detector.js";
 import { isInsideRoot } from "../utils/safe-path.js";
+import { isNonProductPath, isTestPath } from "../utils/path-roles.js";
+import { replaceBracketParams } from "../utils/route-params.js";
 
 const norm = (p) => p.replace(/\\/g, "/");
 
@@ -92,7 +94,13 @@ async function readFileSafe(file) {
   }
 }
 
-function moduleKeyForFile(file, moduleRoots) {
+function rootModuleLabel(repoRoot) {
+  const base = path.basename(path.resolve(repoRoot || ""));
+  if (!base || base === "." || base === "..") return "root";
+  return base;
+}
+
+function moduleKeyForFile(file, moduleRoots, rootLabel = "root") {
   const normalized = norm(file);
 
   const sortedRoots = [...moduleRoots].sort((a, b) => b.length - a.length);
@@ -101,13 +109,18 @@ function moduleKeyForFile(file, moduleRoots) {
     if (normalized === root) return root;
     if (normalized.startsWith(`${root}/`)) {
       const remainder = normalized.slice(root.length + 1);
+      // A file directly under the root belongs to the root itself. Only a sub-directory
+      // is its own module, so a flat `src/` is one module and not one module per file.
+      if (!remainder.includes("/")) return root;
       const nextSegment = remainder.split("/")[0];
       return nextSegment ? `${root}/${nextSegment}` : root;
     }
   }
 
   const parts = normalized.split("/");
-  return parts.length > 1 ? parts[0] : "root";
+  // A file next to go.mod or package.json is one module, named for the directory.
+  // Calling it "root" hid that package on the system map.
+  return parts.length > 1 ? parts[0] : rootLabel;
 }
 
 function routePathFromFile(file) {
@@ -117,10 +130,9 @@ function routePathFromFile(file) {
     const appIndex = f.indexOf("/app/");
     const relative = f.slice(appIndex + 5);
 
-    const cleaned = relative
+    const cleaned = replaceBracketParams(relative
       .replace(/\/page\.(ts|tsx|js|jsx)$/, "")
-      .replace(/\/route\.(ts|tsx|js|jsx)$/, "")
-      .replace(/\[(.*?)\]/g, ":$1")
+      .replace(/\/route\.(ts|tsx|js|jsx)$/, ""))
       .replace(/\/$/, "");
 
     return cleaned ? `/${cleaned}` : "/";
@@ -137,10 +149,9 @@ function routePathFromFile(file) {
     const pagesIndex = f.indexOf("/pages/");
     const relative = f.slice(pagesIndex + 7);
 
-    const cleaned = relative
+    const cleaned = replaceBracketParams(relative
       .replace(/\.(ts|tsx|js|jsx)$/, "")
-      .replace(/\/index$/, "")
-      .replace(/\[(.*?)\]/g, ":$1")
+      .replace(/\/index$/, ""))
       .replace(/\/$/, "");
 
     return cleaned ? `/${cleaned}` : "/";
@@ -149,6 +160,26 @@ function routePathFromFile(file) {
   return file;
 }
 
+/**
+ * Source files a package.json names as its public entry: `main`, `module`, `types`, and every
+ * string under `exports`. Paths are repo-relative with no leading `./`.
+ */
+function packageEntryFiles(pkg) {
+  const found = new Set();
+  const add = (value) => {
+    if (typeof value !== "string" || !/\.(c|m)?[jt]sx?$/.test(value) || value.endsWith(".d.ts")) return;
+    found.add(value.replace(/^\.\//, ""));
+  };
+  const walk = (value) => {
+    if (typeof value === "string") add(value);
+    else if (value && typeof value === "object") Object.values(value).forEach(walk);
+  };
+  add(pkg.main);
+  add(pkg.module);
+  walk(pkg.exports);
+  return [...found];
+}
+
 /**
  * Detect languages from file extensions
  */
@@ -204,9 +235,12 @@ function detectLanguagesFromFiles(files) {
 
   for (const file of files) {
     const ext = path.extname(file).toLowerCase();
-    if (extensionMap[ext]) {
-      languages.add(extensionMap[ext]);
-    }
+    if (!extensionMap[ext]) continue;
+    // Type declarations (`index.d.ts`) and type tests describe a JavaScript library's
+    // types. They do not make the library a TypeScript project.
+    if (ext === ".ts" && /\.d\.ts$/i.test(file)) continue;
+    if (extensionMap[ext] === "TypeScript" && isTestPath(file)) continue;
+    languages.add(extensionMap[ext]);
   }
 
   return languages;
@@ -268,7 +302,9 @@ async function extractRepoMetadata(repoRoot, files = []) {
     if (allDeps["parcel"]) metadata.buildTools.push("Parcel");
 
     // Detect TypeScript from dependencies (supplements file detection)
-    if (allDeps["typescript"]) metadata.languages.add("TypeScript");
+    // A `typescript` devDependency alone does not make the source TypeScript: plain JavaScript
+    // libraries use it to check their `.d.ts` files. Trust it only when no files were scanned.
+    if (allDeps["typescript"] && files.length === 0) metadata.languages.add("TypeScript");
 
     // Detect Node.js runtime indicators
     const hasNodeEngines = pkg.engines && pkg.engines.node;
@@ -279,6 +315,25 @@ async function extractRepoMetadata(repoRoot, files = []) {
     if (hasNodeEngines || hasBin || hasNodeDeps || pkg.type === "module") {
       metadata.languages.add("Node.js");
     }
+
+    // A package with a library entry point (main, module, exports, types) is a library even
+    // when it also ships a `bin/` helper. Only a package with a bin and no library entry is a CLI.
+    // When it has both, the description decides: "Library that parses..." is a library,
+    // while a package that calls itself a CLI keeps that label.
+    const hasLibraryEntry = Boolean(pkg.main || pkg.module || pkg.exports || pkg.types || pkg.typings || pkg.browser);
+    const isShippedApp = Boolean(allDeps["electron"] || allDeps["next"]);
+    metadata.packageEntryFiles = packageEntryFiles(pkg);
+    const description = String(pkg.description || "");
+    const keywords = Array.isArray(pkg.keywords) ? pkg.keywords.join(" ") : "";
+    const saysLibrary = /\b(library|sdk|parser|toolkit|framework)\b/i.test(`${description} ${keywords}`);
+    const saysCli = /\bcli\b|command[- ]line/i.test(`${description} ${keywords}`);
+    // Express 5 publishes index.js with no `main` field. A description that says
+    // library or framework is enough; Node's default entry is that index.js.
+    if ((hasLibraryEntry || saysLibrary) && !isShippedApp) {
+      metadata.projectKind = hasBin && !saysLibrary && saysCli ? "cli" : "library";
+    } else if (hasBin && !hasLibraryEntry) {
+      metadata.projectKind = "cli";
+    }
   } catch {
     // No package.json or invalid JSON
   }
@@ -362,16 +417,37 @@ async function extractRepoMetadata(repoRoot, files = []) {
   return metadata;
 }
 
+function isCommentLine(line) {
+  const trimmed = String(line || "").trim();
+  return trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*");
+}
+
+function lineAt(content, index) {
+  const start = content.lastIndexOf("\n", Math.max(0, index - 1)) + 1;
+  const end = content.indexOf("\n", index);
+  return content.slice(start, end === -1 ? content.length : end);
+}
+
+/** Express route paths start with `/`. `app.get('query parser fn')` is a setting. */
+function isExpressPath(routePath) {
+  return typeof routePath === "string"
+    && routePath.length > 0
+    && routePath.length <= 200
+    && (routePath.startsWith("/") || routePath === "*");
+}
+
 function extractExpressRoutes(content) {
   const routes = [];
   const seenRoutes = new Set();
 
-  // Match app.METHOD(path) or router.METHOD(path)
+  // Match app.METHOD(path) or router.METHOD(path). Skip comments and setting lookups.
   const methodPattern = /(?:app|router)\.(get|post|put|patch|delete|all)\s*\(\s*['"`]([^'"`]+)['"`]/gi;
   let match;
 
   while ((match = methodPattern.exec(content)) !== null) {
+    if (isCommentLine(lineAt(content, match.index))) continue;
     const [, method, path] = match;
+    if (!isExpressPath(path)) continue;
     const routeKey = `${method.toUpperCase()}:${path}`;
     
     if (!seenRoutes.has(routeKey)) {
@@ -394,7 +470,9 @@ function extractExpressRoutes(content) {
   // Match app.route(path).METHOD()
   const routePattern = /(?:app|router)\.route\s*\(\s*['"`]([^'"`]+)['"`]\s*\)([.\s\w()]*)/gi;
   while ((match = routePattern.exec(content)) !== null) {
+    if (isCommentLine(lineAt(content, match.index))) continue;
     const [, path, chain] = match;
+    if (!isExpressPath(path)) continue;
     const methods = [];
     
     if (chain.includes(".get(")) methods.push("GET");
@@ -510,21 +588,28 @@ export async function scanRepo(cfg) {
   }
 
   const moduleCounts = new Map();
+  const flatKeys = new Set();
+  const rootLabel = rootModuleLabel(repoRoot);
 
   for (const file of files) {
     // Go test files belong to the package they exercise. Counting each
     // *_test.go as its own module (the filename under module_roots) splits
     // one package into a source module and a test module.
     if (/_test\.go$/.test(norm(file))) continue;
-    const key = moduleKeyForFile(file, cfg.module_roots || []);
+    const key = moduleKeyForFile(file, cfg.module_roots || [], rootLabel);
+    if (!norm(file).includes("/")) flatKeys.add(key);
     moduleCounts.set(key, (moduleCounts.get(key) || 0) + 1);
   }
 
   const modules = [...moduleCounts.entries()]
-    .map(([key, fileCount]) => ({ key, fileCount }))
+    .map(([key, fileCount]) => ({
+      key,
+      fileCount,
+      ...(flatKeys.has(key) ? { flat: true } : {}),
+    }))
     .sort((a, b) => b.fileCount - a.fileCount);
 
-  const apiFiles = files.filter(isNextRoute);
+  const apiFiles = files.filter((file) => isNextRoute(file) && !isNonProductPath(file));
   const api = [];
 
   // Extract Next.js API routes
@@ -547,8 +632,9 @@ export async function scanRepo(cfg) {
     });
   }
 
-  // Extract Express.js routes
+  // Extract Express.js routes. Tests and examples are not the product API.
   for (const file of files) {
+    if (isNonProductPath(file)) continue;
     if (file.endsWith(".ts") || file.endsWith(".js")) {
       const absoluteFile = path.join(repoRoot, file);
       const content = await readFileSafe(absoluteFile);
@@ -567,7 +653,7 @@ export async function scanRepo(cfg) {
     }
   }
 
-  const pageFiles = files.filter(isNextPage);
+  const pageFiles = files.filter((file) => isNextPage(file) && !isNonProductPath(file));
   const pages = pageFiles.map((file) => ({
     file,
     path: routePathFromFile(file),
@@ -576,6 +662,7 @@ export async function scanRepo(cfg) {
 
   // Extract React Router routes
   for (const file of files) {
+    if (isNonProductPath(file)) continue;
     if (file.endsWith(".tsx") || file.endsWith(".jsx")) {
       const absoluteFile = path.join(repoRoot, file);
       const content = await readFileSafe(absoluteFile);
@@ -589,6 +676,7 @@ export async function scanRepo(cfg) {
 
   // Extract Vue Router routes
   for (const file of files) {
+    if (isNonProductPath(file)) continue;
     if (file.endsWith(".ts") || file.endsWith(".js") || file.endsWith(".vue")) {
       const absoluteFile = path.join(repoRoot, file);
       const content = await readFileSafe(absoluteFile);

package/src/docs/generate-doc-set.js

@@ -130,6 +130,11 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
   
   for (const docPlan of activeDocuments) {
     docIndex++;
+    const emptyReason = emptyDocumentReason(docPlan, { config, scanResult, graphqlResult });
+    if (emptyReason) {
+      info(`[${docIndex}/${totalDocs}] Skipping ${docPlan.key}: ${emptyReason}`);
+      continue;
+    }
     info(`[${docIndex}/${totalDocs}] Generating ${docPlan.key}...`);
     let content = null;
     
@@ -237,6 +242,22 @@ export async function generateDocumentSet(scanResult, config, diffData = null, p
   };
 }
 
+/**
+ * Documents that would only say "nothing found" are not written. A library has no GraphQL
+ * schema and no routes, so those two pages would be noise. A document the config lists
+ * explicitly in `documentation.sections` is always written.
+ */
+export function emptyDocumentReason(docPlan, { config, scanResult, graphqlResult }) {
+  if (config?.documentation?.sections?.includes(docPlan.key)) return null;
+  if (docPlan.key === "graphql_schema" && !graphqlResult?.detected) {
+    return "no GraphQL schema detected";
+  }
+  if (docPlan.key === "route_map" && !(scanResult?.pages?.length) && !(scanResult?.api?.length)) {
+    return "no pages or API routes detected";
+  }
+  return null;
+}
+
 async function generateDocument(docPlan, context) {
   const { key } = docPlan;
   const { scanResult, config, aiContext, moduleContext, flows, diffData, graphqlResult, tsResult, jsdocResult, depGraph, driftResult, securityResult, codeHealthResult, ownershipMap, pluginManager } = context;

package/src/docs/llms-text.js

@@ -34,6 +34,7 @@ RepoLens is the npm package \`@chappibunny/repolens\` (Node.js 18+). It is a CLI
 - [publish](${REPO_URL}/blob/main/docs/INSTALLATION.md): \`npx @chappibunny/repolens publish\` scans and publishes
 - [badge](${REPO_URL}/blob/main/README.md): \`npx @chappibunny/repolens badge\` prints shields.io code-health JSON, SVG, or markdown
 - [comment](${REPO_URL}/blob/main/README.md): \`npx @chappibunny/repolens comment --base <ref> --head <ref>\` prints an architecture diff
+- [app](${REPO_URL}/blob/main/docs/GITHUB_APP.md): \`npx @chappibunny/repolens app\` self-hosts the GitHub App webhook. \`--manifest\` prints the manifest. No credentials are required to print it
 - [doctor](${REPO_URL}/blob/main/docs/INSTALLATION.md): \`npx @chappibunny/repolens doctor\` validates setup
 - [mcp](${REPO_URL}/blob/main/docs/MCP.md): \`npx -y @chappibunny/repolens mcp\` starts the stdio server
 
@@ -95,6 +96,7 @@ Agent-oriented install steps, including the Cline MCP snippet, are in llms-insta
 - \`repolens watch\` regenerates docs on change and exits 2 when nothing matches.
 - \`repolens badge\` prints a shields.io endpoint JSON document for the code-health score (0–100). \`--format svg\` prints a square SVG. \`--format markdown --url https://host/repolens-badge.json\` prints a README snippet. \`--format all --out repolens-badge.json\` writes JSON and SVG. Exit 2 when no JavaScript, TypeScript, Python, or Go files were scored. The score is not reported as 100 when zero files match.
 - \`repolens comment --base <ref> --head <ref>\` compares those commits. It prints markdown locally. In GitHub Actions, with \`GITHUB_TOKEN\`, \`GITHUB_REPOSITORY\`, and a pull_request event, it creates or updates one comment.
+- \`repolens app\` self-hosts a GitHub App webhook. It verifies \`X-Hub-Signature-256\`, posts a Check Run named RepoLens, and updates the sticky architecture comment. \`repolens app --manifest\` prints the manifest and needs no secrets. Listening needs \`REPOLENS_APP_ID\`, \`REPOLENS_WEBHOOK_SECRET\`, and a private key. See docs/GITHUB_APP.md.
 - \`repolens mcp\` starts the stdio MCP server. \`repolens-mcp\` is the same entry.
 
 Exit codes: 0 success, 1 runtime error or unknown command, 2 validation failure (bad flags, missing config, empty scan, and the other cases in the README).

package/src/github-app/auth.js

@@ -0,0 +1,130 @@
+import { createSign } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { fetchWithRetry } from "../utils/retry.js";
+import { sanitizeSecrets } from "../utils/secrets.js";
+
+function base64url(value) {
+  return Buffer.from(value).toString("base64url");
+}
+
+/**
+ * GitHub App JWT (RS256). `iat` is 60s in the past so a skewed clock still works.
+ * `exp` is 9 minutes ahead (GitHub rejects more than 10).
+ */
+export function createAppJwt({ appId, privateKey, now = Date.now() }) {
+  if (!appId) throw new Error("Missing GitHub App id");
+  if (!privateKey || !String(privateKey).includes("BEGIN")) {
+    throw new Error("GitHub App private key must be a PEM body");
+  }
+  const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const payload = base64url(JSON.stringify({
+    iat: Math.floor(now / 1000) - 60,
+    exp: Math.floor(now / 1000) + 9 * 60,
+    iss: String(appId),
+  }));
+  const unsigned = `${header}.${payload}`;
+  const signer = createSign("RSA-SHA256");
+  signer.update(unsigned);
+  signer.end();
+  const signature = signer.sign(privateKey).toString("base64url");
+  return `${unsigned}.${signature}`;
+}
+
+export function readAppPrivateKey(env = process.env) {
+  const file = env.REPOLENS_APP_PRIVATE_KEY_PATH;
+  if (file) {
+    return readFileSync(file, "utf8");
+  }
+  const raw = env.REPOLENS_APP_PRIVATE_KEY || "";
+  return raw.includes("\\n") ? raw.replace(/\\n/g, "\n") : raw;
+}
+
+export function redactToken(text, token) {
+  const value = String(text || "");
+  if (!token) return value;
+  return value.split(token).join("[redacted]");
+}
+
+/**
+ * Exchange the app JWT for an installation access token.
+ * `fetchImpl` is injectable in tests. It must return a Response.
+ */
+export async function fetchInstallationToken({
+  appId,
+  privateKey,
+  installationId,
+  fetchImpl,
+  now,
+}) {
+  if (!/^[0-9]+$/.test(String(installationId))) {
+    throw new Error("Invalid installation id");
+  }
+  const jwt = createAppJwt({ appId, privateKey, now });
+  const url = `https://api.github.com/app/installations/${installationId}/access_tokens`;
+  const send = fetchImpl || ((resource, options) => fetchWithRetry(resource, options, {
+    retries: 2,
+    baseDelayMs: 400,
+    maxDelayMs: 2000,
+    label: "GitHub App token",
+  }));
+  const response = await send(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${jwt}`,
+      Accept: "application/vnd.github+json",
+      "User-Agent": "RepoLens",
+      "X-GitHub-Api-Version": "2022-11-28",
+    },
+  });
+  const text = await response.text();
+  if (!response.ok) {
+    const clipped = sanitizeSecrets(String(text || "").replace(/\s+/g, " ").slice(0, 300));
+    throw Object.assign(new Error(`GitHub App token request failed (${response.status}): ${clipped}`), {
+      status: response.status,
+    });
+  }
+  const json = text ? JSON.parse(text) : {};
+  if (!json.token) throw new Error("GitHub App token response had no token");
+  return json.token;
+}
+
+export function createGitHubRequest(token, fetchImpl) {
+  if (typeof token !== "string" || !/^[A-Za-z0-9_]+$/.test(token)) {
+    throw new Error("Installation token has an unexpected shape");
+  }
+  return async function githubRequest(method, urlPath, body) {
+    const send = fetchImpl || ((resource, options) => fetchWithRetry(resource, options, {
+      retries: 2,
+      baseDelayMs: 400,
+      maxDelayMs: 2000,
+      label: `GitHub ${method}`,
+    }));
+    const response = await send(`https://api.github.com${urlPath}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/vnd.github+json",
+        "Content-Type": "application/json",
+        "User-Agent": "RepoLens",
+        "X-GitHub-Api-Version": "2022-11-28",
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await response.text();
+    let json = null;
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = null;
+      }
+    }
+    if (!response.ok) {
+      const clipped = sanitizeSecrets(redactToken(text, token).replace(/\s+/g, " ").slice(0, 300));
+      throw Object.assign(new Error(`GitHub API error ${response.status}: ${clipped}`), {
+        status: response.status,
+      });
+    }
+    return json;
+  };
+}

package/src/github-app/checkout.js

@@ -0,0 +1,70 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { isSafeGitRef } from "../core/diff.js";
+import { assertGitHubRepo } from "../utils/github-repo.js";
+import { redactToken } from "./auth.js";
+
+function assertToken(token) {
+  if (typeof token !== "string" || !/^[A-Za-z0-9_]+$/.test(token)) {
+    throw new Error("Installation token has an unexpected shape");
+  }
+}
+
+function git(args, cwd, token) {
+  try {
+    execFileSync("git", [
+      "-c", "safe.directory=*",
+      "-c", `http.extraheader=AUTHORIZATION: bearer ${token}`,
+      ...args,
+    ], {
+      cwd,
+      env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 10 * 1024 * 1024,
+    });
+  } catch (error) {
+    const stderr = redactToken(error.stderr || error.message || error, token)
+      .replace(/\s+/g, " ")
+      .slice(0, 300);
+    throw new Error(`git failed: ${stderr}`);
+  }
+}
+
+/**
+ * Clone the base repository and fetch the pull request head plus the base SHA.
+ * The token is passed as an HTTP header, not in the remote URL, and is stripped
+ * from git's error text. It can still appear in the process list on the host.
+ */
+export async function checkoutPullRequest({ token, owner, repo, pullNumber, baseSha, headSha }) {
+  assertToken(token);
+  assertGitHubRepo(`${owner}/${repo}`);
+  if (!/^[0-9]+$/.test(String(pullNumber))) {
+    throw new Error("Invalid pull request number");
+  }
+  if (!isSafeGitRef(baseSha) || !isSafeGitRef(headSha)) {
+    throw new Error("Invalid base or head commit");
+  }
+
+  const parent = await fs.mkdtemp(path.join(os.tmpdir(), "repolens-app-"));
+  const dir = path.join(parent, "repo");
+  const remote = `https://github.com/${owner}/${repo}.git`;
+  try {
+    await fs.mkdir(dir);
+    git(["init", "--quiet"], dir, token);
+    git(["remote", "add", "origin", remote], dir, token);
+    git(["fetch", "--quiet", "--depth", "1", "origin", baseSha], dir, token);
+    git(["fetch", "--quiet", "--depth", "1", "origin", `pull/${pullNumber}/head`], dir, token);
+    git(["checkout", "--quiet", "--detach", headSha], dir, token);
+    return {
+      dir,
+      async cleanup() {
+        await fs.rm(parent, { recursive: true, force: true });
+      },
+    };
+  } catch (error) {
+    await fs.rm(parent, { recursive: true, force: true });
+    throw error;
+  }
+}

package/src/github-app/handler.js

@@ -0,0 +1,170 @@
+import { compareArchitecture, renderArchitectureComment, upsertArchitectureComment } from "../delivery/architecture-comment.js";
+import { assertGitHubRepo } from "../utils/github-repo.js";
+import { sanitizeSecrets } from "../utils/secrets.js";
+import { createGitHubRequest, fetchInstallationToken } from "./auth.js";
+import { checkoutPullRequest } from "./checkout.js";
+
+const CHECK_NAME = "RepoLens";
+const ANALYZE_ACTIONS = new Set(["opened", "synchronize", "reopened", "ready_for_review"]);
+const SUMMARY_LIMIT = 65000;
+
+export function checkRunBody(headSha, summary, conclusion = "success") {
+  const text = String(summary || "RepoLens completed with no summary.").slice(0, SUMMARY_LIMIT);
+  return {
+    name: CHECK_NAME,
+    head_sha: headSha,
+    status: "completed",
+    conclusion,
+    output: {
+      title: conclusion === "success" ? "Architecture diff" : "Architecture diff failed",
+      summary: text,
+    },
+  };
+}
+
+async function defaultAnalyze(dir, base, head) {
+  const report = await compareArchitecture(dir, base, head);
+  return { summary: renderArchitectureComment(report), report };
+}
+
+function installationIdOf(payload) {
+  const id = payload?.installation?.id;
+  return id == null ? "" : String(id);
+}
+
+/**
+ * Handle one verified GitHub App webhook.
+ *
+ * installation and installation_repositories are acknowledged.
+ * pull_request opened / synchronize / reopened / ready_for_review runs the
+ * existing architecture diff, then posts a Check Run and the sticky comment.
+ *
+ * Inject `prepareRepo`, `analyze`, `request`, or `getInstallationToken` in tests.
+ * Returns `{ status, body }`.
+ */
+export async function handleGitHubAppEvent({
+  eventName,
+  payload,
+  appId,
+  privateKey,
+  prepareRepo = checkoutPullRequest,
+  analyze = defaultAnalyze,
+  request,
+  getInstallationToken = fetchInstallationToken,
+  fetchImpl,
+  now,
+} = {}) {
+  if (!eventName) {
+    return { status: 400, body: { ok: false, error: "Missing X-GitHub-Event" } };
+  }
+  if (eventName === "ping") {
+    return { status: 200, body: { ok: true, handled: "ping" } };
+  }
+  if (eventName === "installation" || eventName === "installation_repositories") {
+    return {
+      status: 200,
+      body: {
+        ok: true,
+        handled: eventName,
+        action: payload?.action || "",
+        installationId: installationIdOf(payload),
+      },
+    };
+  }
+  if (eventName !== "pull_request") {
+    return { status: 200, body: { ok: true, ignored: eventName } };
+  }
+
+  const action = payload?.action || "";
+  if (!ANALYZE_ACTIONS.has(action)) {
+    return { status: 200, body: { ok: true, ignored: "pull_request", action } };
+  }
+
+  const pull = payload?.pull_request;
+  const repository = payload?.repository?.full_name;
+  const installationId = installationIdOf(payload);
+  const baseSha = pull?.base?.sha;
+  const headSha = pull?.head?.sha;
+  const pullNumber = pull?.number;
+  if (!pull || !repository || !installationId || !baseSha || !headSha || pullNumber == null) {
+    return { status: 422, body: { ok: false, error: "Pull request payload is missing repository, installation, or commits" } };
+  }
+
+  let owner;
+  let repo;
+  try {
+    assertGitHubRepo(repository);
+    [owner, repo] = repository.split("/");
+  } catch (error) {
+    return { status: 422, body: { ok: false, error: error.message } };
+  }
+
+  let call = request;
+  let token = "";
+  if (!call) {
+    try {
+      token = await getInstallationToken({
+        appId,
+        privateKey,
+        installationId,
+        fetchImpl,
+        now,
+      });
+      call = createGitHubRequest(token, fetchImpl);
+    } catch (error) {
+      return { status: 502, body: { ok: false, error: sanitizeSecrets(error.message || String(error)) } };
+    }
+  }
+
+  let workspace;
+  try {
+    workspace = await prepareRepo({
+      token,
+      owner,
+      repo,
+      pullNumber,
+      baseSha,
+      headSha,
+    });
+    const analyzed = await analyze(workspace.dir, baseSha, headSha);
+    const summary = analyzed?.summary || "";
+    const check = await call(
+      "POST",
+      `/repos/${owner}/${repo}/check-runs`,
+      checkRunBody(headSha, summary, "success"),
+    );
+    const comment = await upsertArchitectureComment({
+      owner,
+      repo,
+      issueNumber: pullNumber,
+      body: summary,
+      request: call,
+    });
+    return {
+      status: 200,
+      body: {
+        ok: true,
+        handled: "pull_request",
+        action,
+        checkRunId: check?.id ?? null,
+        comment: comment?.action || null,
+      },
+    };
+  } catch (error) {
+    const message = sanitizeSecrets(error.message || String(error));
+    try {
+      await call(
+        "POST",
+        `/repos/${owner}/${repo}/check-runs`,
+        checkRunBody(headSha, message, "failure"),
+      );
+    } catch {
+      // The failed check is best-effort. The caller still sees the error.
+    }
+    return { status: 500, body: { ok: false, error: message } };
+  } finally {
+    if (workspace?.cleanup) {
+      await workspace.cleanup();
+    }
+  }
+}