@chappibunny/repolens 1.15.4 → 1.16.0

package/src/github-app/manifest.js

@@ -0,0 +1,36 @@
+/**
+ * GitHub App manifest. Minimal permissions for architecture check runs
+ * and the existing pull request comment. `metadata: read` is required by
+ * GitHub on every app.
+ *
+ * `hook_attributes.url` is a placeholder. Replace it with the public URL of
+ * `repolens app` before registering. This repository does not register the app.
+ */
+export const GITHUB_APP_WEBHOOK_PATH = "/api/github/webhooks";
+
+export const GITHUB_APP_MANIFEST = {
+  name: "RepoLens",
+  description: "Posts an architecture diff as a check run and one sticky pull request comment.",
+  url: "https://github.com/CHAPIBUNNY/repolens",
+  hook_attributes: {
+    url: `https://example.com${GITHUB_APP_WEBHOOK_PATH}`,
+    active: true,
+  },
+  redirect_url: "https://github.com/CHAPIBUNNY/repolens",
+  public: false,
+  default_permissions: {
+    checks: "write",
+    pull_requests: "write",
+    contents: "read",
+    metadata: "read",
+  },
+  default_events: [
+    "installation",
+    "installation_repositories",
+    "pull_request",
+  ],
+};
+
+export function manifestDocument() {
+  return JSON.stringify(GITHUB_APP_MANIFEST, null, 2);
+}

package/src/github-app/run.js

@@ -0,0 +1,67 @@
+import { manifestDocument } from "./manifest.js";
+import { readAppPrivateKey } from "./auth.js";
+import { createGitHubAppServer, listenGitHubApp } from "./server.js";
+import { GITHUB_APP_WEBHOOK_PATH } from "./manifest.js";
+
+function positiveInteger(value, fallback) {
+  if (value == null || value === "") return fallback;
+  if (!/^[0-9]+$/.test(String(value))) return null;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) return null;
+  return parsed;
+}
+
+/**
+ * `repolens app` self-hosts the webhook.
+ * `--manifest` prints the manifest JSON and does not need credentials.
+ * Returns a process exit code. The server process stays up on success.
+ */
+export async function runGitHubApp({
+  manifest = false,
+  port,
+  host,
+  webhookPath,
+  env = process.env,
+  stdout = console.log,
+  stderr = console.error,
+} = {}) {
+  if (manifest) {
+    stdout(`${manifestDocument()}\n`);
+    return 0;
+  }
+
+  const appId = env.REPOLENS_APP_ID || "";
+  const webhookSecret = env.REPOLENS_WEBHOOK_SECRET || "";
+  let privateKey = "";
+  try {
+    privateKey = readAppPrivateKey(env);
+  } catch (error) {
+    stderr(`Could not read REPOLENS_APP_PRIVATE_KEY_PATH: ${error.message}`);
+    return 2;
+  }
+  if (!appId || !webhookSecret || !privateKey) {
+    stderr("repolens app needs REPOLENS_APP_ID, REPOLENS_WEBHOOK_SECRET, and REPOLENS_APP_PRIVATE_KEY or REPOLENS_APP_PRIVATE_KEY_PATH.");
+    stderr("Print the manifest with: repolens app --manifest");
+    return 2;
+  }
+
+  const chosenPort = positiveInteger(port ?? env.REPOLENS_APP_PORT, 8787);
+  if (chosenPort == null) {
+    stderr("--port must be an integer from 0 to 65535");
+    return 2;
+  }
+  const chosenHost = host || env.REPOLENS_APP_HOST || "127.0.0.1";
+  const chosenPath = webhookPath || env.REPOLENS_APP_WEBHOOK_PATH || GITHUB_APP_WEBHOOK_PATH;
+
+  const server = createGitHubAppServer({
+    webhookSecret,
+    webhookPath: chosenPath,
+    appId,
+    privateKey,
+  });
+  const bound = await listenGitHubApp(server, { port: chosenPort, host: chosenHost });
+  stderr(`RepoLens GitHub App listening on http://${chosenHost}:${bound}${chosenPath}`);
+  stderr("GitHub must reach that URL over HTTPS. The process stays running until you stop it.");
+  await new Promise(() => {});
+  return 0;
+}

package/src/github-app/server.js

@@ -0,0 +1,120 @@
+import http from "node:http";
+import { GITHUB_APP_WEBHOOK_PATH } from "./manifest.js";
+import { verifyHubSignature256 } from "./signature.js";
+import { handleGitHubAppEvent } from "./handler.js";
+
+const MAX_BODY_BYTES = 2_000_000;
+
+function sendJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Content-Length": Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        reject(Object.assign(new Error("Payload too large"), { status: 413 }));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}
+
+/**
+ * HTTP server for the GitHub App webhook.
+ *
+ * GitHub gives a webhook about 10 seconds. Analysis can take longer, so the
+ * default response is 202 and the check run is posted afterwards. Tests pass
+ * `inline: true` and wait for the handler before the response is sent.
+ */
+export function createGitHubAppServer(options) {
+  const webhookPath = options.webhookPath || GITHUB_APP_WEBHOOK_PATH;
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url || "/", "http://127.0.0.1");
+    if (req.method === "GET" && (url.pathname === "/health" || url.pathname === "/")) {
+      sendJson(res, 200, { ok: true, service: "repolens-github-app" });
+      return;
+    }
+    if (req.method !== "POST" || url.pathname !== webhookPath) {
+      sendJson(res, 404, { ok: false, error: "Not found" });
+      return;
+    }
+
+    let raw;
+    try {
+      raw = await readBody(req);
+    } catch (error) {
+      sendJson(res, error.status || 400, { ok: false, error: error.message || "Could not read the body" });
+      return;
+    }
+
+    if (!verifyHubSignature256(raw, req.headers["x-hub-signature-256"], options.webhookSecret)) {
+      sendJson(res, 401, { ok: false, error: "Invalid signature" });
+      return;
+    }
+
+    let payload;
+    try {
+      payload = JSON.parse(raw.toString("utf8") || "null");
+    } catch {
+      sendJson(res, 400, { ok: false, error: "Invalid JSON" });
+      return;
+    }
+
+    const eventName = req.headers["x-github-event"];
+    const run = () => handleGitHubAppEvent({
+      eventName: typeof eventName === "string" ? eventName : "",
+      payload,
+      appId: options.appId,
+      privateKey: options.privateKey,
+      prepareRepo: options.prepareRepo,
+      analyze: options.analyze,
+      request: options.request,
+      getInstallationToken: options.getInstallationToken,
+      fetchImpl: options.fetchImpl,
+    });
+
+    if (options.inline) {
+      try {
+        const result = await run();
+        sendJson(res, result.status, result.body);
+      } catch (error) {
+        sendJson(res, 500, { ok: false, error: error.message || "Webhook failed" });
+      }
+      return;
+    }
+
+    sendJson(res, 202, { ok: true, accepted: true });
+    run().then((result) => {
+      if (result?.body?.ok === false) {
+        console.error(`RepoLens GitHub App: ${result.body.error || "event failed"}`);
+      }
+    }).catch((error) => {
+      console.error(`RepoLens GitHub App: ${error.message || error}`);
+    });
+  });
+  return server;
+}
+
+export function listenGitHubApp(server, { port, host }) {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => {
+      server.removeListener("error", reject);
+      const address = server.address();
+      resolve(typeof address === "object" && address ? address.port : port);
+    });
+  });
+}

package/src/github-app/signature.js

@@ -0,0 +1,22 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * Verify a GitHub `X-Hub-Signature-256` header against the raw request body.
+ * The comparison is constant-time when the header has the expected length.
+ */
+export function verifyHubSignature256(rawBody, signatureHeader, secret) {
+  if (!secret || typeof secret !== "string") return false;
+  if (typeof signatureHeader !== "string" || !signatureHeader.startsWith("sha256=")) return false;
+  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody));
+  const digest = createHmac("sha256", secret).update(body).digest("hex");
+  const expected = Buffer.from(`sha256=${digest}`, "utf8");
+  const actual = Buffer.from(signatureHeader, "utf8");
+  if (actual.length !== expected.length) return false;
+  return timingSafeEqual(actual, expected);
+}
+
+export function signHubBody(rawBody, secret) {
+  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody));
+  const digest = createHmac("sha256", secret).update(body).digest("hex");
+  return `sha256=${digest}`;
+}

package/src/help.js

@@ -8,6 +8,7 @@ const EXIT_CODES = `Exit codes:
      badge scored 0 source files,
      comment is missing a base or head ref,
      publish --strict is missing publisher credentials,
+     app is missing its id, webhook secret, or private key,
      or feedback has no terminal`;
 
 const COMMAND_HELP = {
@@ -283,6 +284,42 @@ ${EXIT_CODES}
 Examples:
   repolens comment --base origin/main --head HEAD
 `,
+
+  app: `
+RepoLens app — self-host the GitHub App webhook
+
+Usage:
+  repolens app [--port <n>] [--host <address>] [--webhook-path <path>]
+  repolens app --manifest
+
+Options:
+  --port <n>            Listen port (default 8787, or REPOLENS_APP_PORT)
+  --host <address>      Listen address (default 127.0.0.1, or REPOLENS_APP_HOST)
+  --webhook-path <path> Path GitHub posts to (default /api/github/webhooks)
+  --manifest            Print the GitHub App manifest JSON and exit
+  --help, -h            Show this help
+
+Verifies X-Hub-Signature-256, acknowledges installation events, and on
+pull_request opened, synchronize, reopened, and ready_for_review runs the
+architecture diff. It posts a Check Run named RepoLens and updates the
+sticky pull request comment. The check is informational: a completed diff
+is success, and a failed analysis is a failed check.
+
+\`--manifest\` needs no credentials. Running the server needs
+REPOLENS_APP_ID, REPOLENS_WEBHOOK_SECRET, and either
+REPOLENS_APP_PRIVATE_KEY or REPOLENS_APP_PRIVATE_KEY_PATH.
+Replace hook_attributes.url in the manifest before you register the app.
+This command does not register an app on GitHub.
+
+GitHub allows about 10 seconds for the HTTP response. The server answers
+202 and posts the check after the analysis finishes.
+
+${EXIT_CODES}
+
+Examples:
+  repolens app --manifest
+  repolens app --port 8787
+`,
 };
 
 const GLOBAL_HELP = `
@@ -306,6 +343,7 @@ Commands:
   mcp         Start the stdio MCP server (also available as repolens-mcp)
   badge       Print a shields.io code-health badge (JSON, SVG, or markdown)
   comment     Print or post an architecture diff for a pull request
+  app         Self-host the GitHub App webhook (check run and PR comment)
   version     Print the current RepoLens version
   help        Show this help message
 
@@ -320,6 +358,10 @@ Options:
   --label <text>    badge: shields.io label (default: code health)
   --base <ref>      comment: base commit or ref
   --head <ref>      comment: head commit or ref
+  --port <n>        app: listen port (default 8787)
+  --host <address>  app: listen address (default 127.0.0.1)
+  --webhook-path    app: webhook path (default /api/github/webhooks)
+  --manifest        app: print the GitHub App manifest JSON and exit
   --quick           Scaffold without the wizard (also --non-interactive).
                     Markdown only; globs follow the detected language.
   --strict          publish: exit 2 when publisher credentials are missing
@@ -356,6 +398,8 @@ Examples:
   repolens badge
   repolens badge --format markdown --url https://example.github.io/repo/repolens-badge.json
   repolens comment --base origin/main --head HEAD
+  repolens app --manifest
+  repolens app --port 8787
   repolens --version
 `;
 

package/src/renderers/render.js

@@ -1,4 +1,4 @@
-import { computeModuleLevelMetrics, describeModuleDepRole } from "../analyzers/context-builder.js";
+import { computeModuleLevelMetrics, describeModuleDepRole, isCliProject, isLibraryProject } from "../analyzers/context-builder.js";
 import { moduleEvidence, pathHasKeyword } from "../analyzers/domain-inference.js";
 
 export function renderSystemOverview(cfg, scan, depGraph = null) {
@@ -447,8 +447,8 @@ export function renderRouteMap(cfg, scan, aiContext = null) {
   if (!scan.pages?.length && !scan.api?.length) {
     // Determine project type for context-aware messaging
     const patterns = aiContext?.patterns || [];
-    const isCLI = patterns.some(p => p.toLowerCase().includes("cli"));
-    const isLibrary = patterns.some(p => p.toLowerCase().includes("library") || p.toLowerCase().includes("shared"));
+    const isCLI = isCliProject(aiContext);
+    const isLibrary = isLibraryProject(aiContext) || patterns.some(p => p.toLowerCase().includes("library") || p.toLowerCase().includes("shared"));
     const techStack = aiContext?.techStack || {};
     const hasWebFramework = (techStack.frameworks || []).some(f =>
       /next|react|vue|angular|express|fastify|hono|koa|django|flask|rails|spring/i.test(f)

package/src/renderers/renderAnalysis.js

@@ -343,7 +343,11 @@ export function renderDependencyGraph(depResult) {
   lines.push(`|--------|-------|`);
   lines.push(`| Source files | ${s.totalFiles} |`);
   lines.push(`| Import edges | ${s.totalEdges} |`);
-  lines.push(`| External packages | ${s.externalDeps} |`);
+  if (Array.isArray(depResult.externalDev) && depResult.externalDev.length > 0) {
+    lines.push(`| External packages | ${s.externalDeps} (${depResult.externalRuntime.length} runtime, ${depResult.externalDev.length} dev/test tooling) |`);
+  } else {
+    lines.push(`| External packages | ${s.externalDeps} |`);
+  }
   lines.push(`| Circular dependencies | ${s.cycles} |`);
   lines.push(`| Orphan files (no imports or importers) | ${s.orphanFiles} |`);
   lines.push("");
@@ -352,7 +356,7 @@ export function renderDependencyGraph(depResult) {
   if (s.hubs.length > 0) {
     lines.push("## Hub Modules");
     lines.push("");
-    lines.push("These are the most-imported modules in the codebase. Changes to hub modules have the widest blast radius and should be reviewed carefully:");
+    lines.push("These are the most-imported product modules (tests, examples, and build scripts are not counted). Changes to hub modules have the widest blast radius and should be reviewed carefully:");
     lines.push("");
     lines.push("| Module | Imported By |");
     lines.push("|--------|-------------|");
@@ -384,14 +388,29 @@ export function renderDependencyGraph(depResult) {
     lines.push("");
     lines.push(`The codebase imports **${depResult.externalDeps.length}** external package${depResult.externalDeps.length === 1 ? "" : "s"}. These are third-party modules (not the language standard library):`);
     lines.push("");
-    // Render as a compact table for cleaner output
-    const sorted = [...depResult.externalDeps].sort();
-    lines.push("| Package |");
-    lines.push("|---------|");
-    for (const dep of sorted) {
-      lines.push(`| \`${dep}\` |`);
+    const split = Array.isArray(depResult.externalDev) && depResult.externalDev.length > 0;
+    if (split) {
+      const renderTable = (title, names) => {
+        if (names.length === 0) return;
+        lines.push(`### ${title}`);
+        lines.push("");
+        lines.push("| Package |");
+        lines.push("|---------|");
+        for (const dep of [...names].sort()) lines.push(`| \`${dep}\` |`);
+        lines.push("");
+      };
+      renderTable(`Runtime (${depResult.externalRuntime.length})`, depResult.externalRuntime);
+      renderTable(`Development and test tooling (${depResult.externalDev.length})`, depResult.externalDev);
+    } else {
+      // Render as a compact table for cleaner output
+      const sorted = [...depResult.externalDeps].sort();
+      lines.push("| Package |");
+      lines.push("|---------|");
+      for (const dep of sorted) {
+        lines.push(`| \`${dep}\` |`);
+      }
+      lines.push("");
     }
-    lines.push("");
   }
 
   lines.push("---");

package/src/renderers/renderDiff.js

@@ -1,3 +1,5 @@
+import { replaceBracketParams } from "../utils/route-params.js";
+
 function isRouteFile(file) {
   return (
     file.includes("/pages/api/") ||
@@ -15,10 +17,10 @@ function routePathFromFile(file) {
     const appIndex = file.indexOf("/app/");
     const relative = file.slice(appIndex + 5);
 
-    return "/" + relative
+    const cleaned = relative
       .replace(/\/page\.(ts|tsx|js|jsx)$/, "")
-      .replace(/\/route\.(ts|tsx|js|jsx)$/, "")
-      .replace(/\[(.*?)\]/g, ":$1");
+      .replace(/\/route\.(ts|tsx|js|jsx)$/, "");
+    return `/${replaceBracketParams(cleaned)}`;
   }
 
   if (file.includes("/pages/api/")) {

package/src/renderers/renderMap.js

@@ -1,13 +1,12 @@
+import { replaceLeadingAppGroup, replaceSlashGroups } from "../utils/route-params.js";
+
 function sanitizeNodeId(value) {
   return value.replace(/[^a-zA-Z0-9_]/g, "_");
 }
 
 function normalizeLabel(value) {
-  return value
-    .replace(/^src\//, "")
-    .replace(/^app\/\((.*?)\)/, "app/$1")
-    .replace(/\/\((.*?)\)/g, "/$1")
-    .replace(/\/+/g, "/");
+  const withoutSrc = value.replace(/^src\//, "");
+  return replaceSlashGroups(replaceLeadingAppGroup(withoutSrc)).replace(/\/+/g, "/");
 }
 
 function buildModuleGraph(modules, depGraph) {
@@ -96,9 +95,11 @@ function buildModuleGraph(modules, depGraph) {
  */
 function findModuleForFile(fileKey, modules) {
   const normalized = fileKey.replace(/\\/g, "/");
+  const flat = modules.find((mod) => mod.flat) || modules.find((mod) => mod.key === "root");
   let bestMatch = null;
   for (const mod of modules) {
     const modKey = mod.key;
+    if (flat && modKey === flat.key) continue;
     // Direct match (with or without extension)
     if (normalized === modKey || normalized === modKey.replace(/\.[^/.]+$/, "")) {
       return modKey;
@@ -110,6 +111,7 @@ function findModuleForFile(fileKey, modules) {
       }
     }
   }
+  if (!bestMatch && flat && !normalized.includes("/")) return flat.key;
   return bestMatch;
 }
 

package/src/utils/path-roles.js

@@ -0,0 +1,58 @@
+// Path roles: is a file test code, or tooling/example code rather than the product?
+// Shared by the dependency graph, flow inference, pattern inference, and security scan
+// so tests and examples never drive hub lists, coupling advice, or severity.
+
+const TEST_DIRECTORIES = new Set([
+  "test", "tests", "spec", "specs", "__tests__", "__mocks__", "fixtures", "testdata", "e2e", "cypress",
+]);
+
+// Directories holding tooling, samples, and docs. Code in here describes a build script
+// or an example, not how the product works.
+export const TOOLING_DIRECTORIES = new Set([
+  "doc", "docs", "doc-gen", "docgen", "scripts", "script", "tools", "tooling",
+  "example", "examples", "demo", "demos", "sample", "samples",
+  "benchmark", "benchmarks", "bench", "fixtures", "tasks",
+]);
+
+function segments(filePath) {
+  return String(filePath || "").replace(/\\/g, "/").toLowerCase().split("/");
+}
+
+// Directory part of a path. A last segment without an extension (`test`, `examples/amd`)
+// is a directory key such as a module, so it counts too.
+function directorySegments(filePath) {
+  const parts = segments(filePath);
+  const last = parts[parts.length - 1] || "";
+  return /\.[a-z0-9]+$/.test(last) ? parts.slice(0, -1) : parts;
+}
+
+/** True for files in a test directory or named like a test (`a.test.js`, `a_test.go`, `test_a.py`). */
+export function isTestPath(filePath) {
+  const parts = segments(filePath);
+  if (directorySegments(filePath).some((segment) => TEST_DIRECTORIES.has(segment))) return true;
+  const base = parts[parts.length - 1] || "";
+  if (/^(test_|spec_)/.test(base)) return true;
+  if (/(_test|_spec)\.[a-z0-9]+$/.test(base)) return true;
+  if (/\.(test|spec)\.[a-z0-9]+$/.test(base)) return true;
+  return false;
+}
+
+/** True when a directory above the file is a tooling, example, or docs directory. */
+export function isToolingPath(filePath) {
+  return directorySegments(filePath).some((segment) => TOOLING_DIRECTORIES.has(segment));
+}
+
+/**
+ * Build-time or example code: runs on a maintainer's machine or in a browser demo, not in
+ * the shipped library. Includes `build*.js` scripts and anything under a tooling directory.
+ */
+export function isBuildOrExamplePath(filePath) {
+  if (isToolingPath(filePath)) return true;
+  const base = segments(filePath).pop() || "";
+  return /^build([-_.]|$)/.test(base);
+}
+
+/** Test code or tooling/example code: not part of the product's own architecture. */
+export function isNonProductPath(filePath) {
+  return isTestPath(filePath) || isToolingPath(filePath);
+}

package/src/utils/route-params.js

@@ -0,0 +1,50 @@
+/**
+ * Linear replacements for route and label text.
+ *
+ * A lazy `.*?` between two markers is polynomial: on a long string with no
+ * closer, each start position scans to the end (CodeQL js/polynomial-redos).
+ * These walks stop at the first closer and never re-scan, which matches the
+ * old `String.prototype.replace` result.
+ */
+
+function replaceMarked(input, open, close, mapInner) {
+  const value = String(input ?? "");
+  let out = "";
+  let cursor = 0;
+  while (cursor < value.length) {
+    const start = value.indexOf(open, cursor);
+    if (start === -1) {
+      out += value.slice(cursor);
+      break;
+    }
+    const end = value.indexOf(close, start + open.length);
+    if (end === -1) {
+      out += value.slice(cursor);
+      break;
+    }
+    out += value.slice(cursor, start);
+    out += mapInner(value.slice(start + open.length, end));
+    cursor = end + close.length;
+  }
+  return out;
+}
+
+/** `[param]` → `:param`, including the first `]` only. Global, non-overlapping. */
+export function replaceBracketParams(value) {
+  return replaceMarked(value, "[", "]", (inner) => `:${inner}`);
+}
+
+/** `/(group)` → `/group`. Used for Next.js route groups in diagram labels. */
+export function replaceSlashGroups(value) {
+  return replaceMarked(value, "/(", ")", (inner) => `/${inner}`);
+}
+
+/** A leading `app/(group)` → `app/group`. Later groups use {@link replaceSlashGroups}. */
+export function replaceLeadingAppGroup(value) {
+  const input = String(value ?? "");
+  const prefix = "app/(";
+  if (!input.startsWith(prefix)) return input;
+  const end = input.indexOf(")", prefix.length);
+  if (end === -1) return input;
+  return `app/${input.slice(prefix.length, end)}${input.slice(end + 1)}`;
+}

package/src/utils/yaml.js

@@ -1,14 +1,15 @@
-import yaml from "js-yaml";
+import { CORE_SCHEMA, load, mergeTag } from "js-yaml";
 
 const MAX_YAML_CHARS = 1_000_000;
 const MAX_YAML_ALIASES = 2000;
 
 /**
  * Parse YAML without executing custom tags.
- * js-yaml 4 `load` is already safe (no JS types). This adds a size cap and
- * an alias cap so a config cannot expand into a billion-laughs document.
- * The js-yaml 4 default schema is unchanged (`true`/`false` are booleans;
- * the YAML 1.1 spellings `yes` and `no` stay strings).
+ * js-yaml 5 `load` uses the YAML 1.2 Core schema (`true`/`false` are booleans;
+ * the YAML 1.1 spellings `yes` and `no` stay strings). The merge key (`<<`)
+ * is added back so configs that relied on js-yaml 4's merge still parse.
+ * A size cap and `maxAliases` stop a billion-laughs document.
+ * An empty file returns `undefined`, matching the previous loader.
  */
 export function loadYaml(raw) {
   if (typeof raw !== "string") {
@@ -17,11 +18,15 @@ export function loadYaml(raw) {
   if (raw.length > MAX_YAML_CHARS) {
     throw new Error(`YAML document exceeds ${MAX_YAML_CHARS} characters`);
   }
+  if (raw.trim() === "") return undefined;
 
   const aliasUses = raw.match(/(^|[\s\[\{,])\*[A-Za-z_][\w-]*/g);
   if (aliasUses && aliasUses.length > MAX_YAML_ALIASES) {
     throw new Error(`YAML document has too many aliases (${aliasUses.length})`);
   }
 
-  return yaml.load(raw);
+  return load(raw, {
+    schema: CORE_SCHEMA.withTags(mergeTag),
+    maxAliases: MAX_YAML_ALIASES,
+  });
 }