@mmerterden/multi-agent-pipeline 20.8.3 → 20.9.0

package/pipeline/lib/repo-profile-derive.mjs

@@ -0,0 +1,1771 @@
+/**
+ * repo-profile-derive.mjs  -  build a draft repo profile from the repo itself.
+ *
+ * Every heuristic reads what the repo already says about itself: who commits
+ * where (git history), what CI runs (workflow files), which files announce
+ * they are generated (file headers), what the hooks do (hook bodies). Nothing
+ * here knows a particular company, bot, tool or path; a bot is any author
+ * matching `[bot]` or a pattern the caller passes.
+ *
+ * Cost is bounded so a 50k-file repo derives in a few seconds: one `git log`
+ * over a fixed window, one full-history `git log` limited to at most
+ * MAX_CANDIDATES candidate owned paths, one `git ls-files`, a 600-byte header
+ * read per regular source file, and a handful of `git grep` calls restricted to
+ * source extensions. Paths are read NUL-separated with core.quotePath off, so a
+ * non-ASCII path arrives as written.
+ *
+ * @module pipeline/lib/repo-profile-derive
+ */
+
+import { execFileSync } from "node:child_process";
+import { closeSync, lstatSync, openSync, readdirSync, readFileSync, readSync } from "node:fs";
+import { join, posix } from "node:path";
+import { followClaudeMdLinks } from "./claude-md-links.mjs";
+import { mainRepoRoot, SCHEMA_VERSION } from "./repo-profile.mjs";
+
+const DEFAULT_HISTORY = 2000;
+const MIN_OWNED_COMMITS = 3;
+const MAX_CANDIDATES = 50;
+const COMMIT_SAMPLE = 200;
+const MAX_ENTRIES = 50;
+const HEADER_BYTES = 600;
+const HEADER_LINES = 5;
+
+const SOURCE_EXT =
+  /\.(swift|kt|kts|java|m|mm|h|c|cc|cpp|cs|dart|go|rs|py|rb|ts|tsx|js|jsx|mjs|cjs|strings|xml|gradle|sh)$/;
+const GREP_PATHSPEC = [
+  "*.swift",
+  "*.kt",
+  "*.java",
+  "*.m",
+  "*.mm",
+  "*.dart",
+  "*.cs",
+  "*.go",
+  "*.rs",
+  "*.py",
+  "*.ts",
+  "*.tsx",
+  "*.js",
+  "*.jsx",
+];
+const STAMP_RE = /generated by|auto-?generated|do not edit/i;
+// A stamp is a comment line: a docstring or a string that mentions generated
+// code is not one.
+const STAMP_LINE_RE =
+  /^\s*(?:\/\/+|#+|\/\*+|\*+|<!--|--|;+)\s*(?:@?[\w.-]+:\s*)?.*(?:generated by|auto-?generated|do not edit)/i;
+const BOT_DEFAULT = /\[bot\]$/;
+const HOOK_NAMES = new Set([
+  "pre-commit",
+  "prepare-commit-msg",
+  "commit-msg",
+  "post-commit",
+  "pre-push",
+  "post-checkout",
+  "post-merge",
+  "pre-rebase",
+  "post-rewrite",
+]);
+const HOOK_DIRS = [".githooks/", "scripts/git-hooks/", "git-hooks/", ".husky/"];
+
+// ---------------------------------------------------------------------------
+// small helpers
+
+const GIT_PLAIN = ["-c", "core.quotePath=false"];
+
+function run(cwd, cmd, args, { maxBuffer = 512 * 1024 * 1024 } = {}) {
+  try {
+    return execFileSync(cmd, args, {
+      cwd,
+      encoding: "utf8",
+      maxBuffer,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch (err) {
+    // git grep exits 1 on no match; its stdout is still the answer.
+    return typeof err?.stdout === "string" ? err.stdout : "";
+  }
+}
+
+const gitOut = (cwd, args, opts) => run(cwd, "git", [...GIT_PLAIN, ...args], opts);
+
+// lstat, never stat: a tracked symlink can point at a FIFO (an open blocks) or
+// outside the repo, and neither is repo content.
+const isRegular = (p) => {
+  try {
+    return lstatSync(p).isFile();
+  } catch {
+    return false;
+  }
+};
+
+function readText(top, rel, max = 256 * 1024) {
+  try {
+    const p = join(top, rel);
+    if (!isRegular(p)) return null;
+    const buf = readFileSync(p);
+    return buf.subarray(0, max).toString("utf8");
+  } catch {
+    return null;
+  }
+}
+
+function readHeader(top, rel, buf) {
+  let fd;
+  try {
+    const p = join(top, rel);
+    if (!isRegular(p)) return "";
+    fd = openSync(p, "r");
+    const n = readSync(fd, buf, 0, HEADER_BYTES, 0);
+    return buf.toString("utf8", 0, n);
+  } catch {
+    return "";
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const short = (sha) => `commit:${sha.slice(0, 12)}`;
+const unquote = (s) => s.trim().replace(/^(['"])(.*)\1$/, "$2");
+
+function role(value, evidence = [], confidence = "low", note) {
+  const r = { value, source: "derived", evidence: [...new Set(evidence)].slice(0, 8), confidence };
+  if (note) r.note = note;
+  return r;
+}
+
+function entry(fields, evidence, confidence, note) {
+  const e = {
+    ...fields,
+    source: "derived",
+    evidence: [...new Set(evidence)].slice(0, 8),
+    confidence,
+  };
+  if (note) e.note = note;
+  return e;
+}
+
+function ancestors(file) {
+  const out = [];
+  let d = posix.dirname(file);
+  while (d !== "." && d !== "/") {
+    out.push(d);
+    d = posix.dirname(d);
+  }
+  return out;
+}
+
+function topCount(map) {
+  let best = null;
+  for (const [k, v] of map) if (!best || v > best[1]) best = [k, v];
+  return best;
+}
+
+function bump(map, key, by = 1) {
+  map.set(key, (map.get(key) || 0) + by);
+}
+
+const underPrefix = (file, prefix) => file === prefix || file.startsWith(`${prefix}/`);
+const globPrefix = (glob) => glob.replace(/\/?\*.*$/, "").replace(/\/$/, "");
+
+// ---------------------------------------------------------------------------
+// inputs
+
+/** `git log --name-only -z`, one record per commit, each opened by \x01. */
+function parseLog(raw) {
+  const commits = [];
+  for (const chunk of raw.split("\x01")) {
+    const nul = chunk.indexOf("\0");
+    if (nul < 0) continue;
+    const [sha, an, ae, ...rest] = chunk.slice(0, nul).split("\t");
+    if (!/^[0-9a-f]{40}$/.test(sha)) continue;
+    const files = chunk
+      .slice(nul + 1)
+      .replace(/^\n/, "")
+      .split("\0")
+      .filter(Boolean);
+    commits.push({ sha, an, ae, subject: rest.join("\t"), files });
+  }
+  return commits;
+}
+
+const LOG_FORMAT = "--format=%x01%H%x09%an%x09%ae%x09%s";
+
+function readHistory(top, window) {
+  return parseLog(
+    gitOut(top, [
+      "log",
+      `-n${window}`,
+      "--no-merges",
+      "--no-renames",
+      "-z",
+      LOG_FORMAT,
+      "--name-only",
+    ]),
+  );
+}
+
+/** Every commit, whole history, that touches one of `paths`; only those paths are listed. */
+function readPathHistory(top, paths) {
+  if (!paths.length) return [];
+  const specs = paths.map((p) => `:(literal)${p}`);
+  return parseLog(
+    gitOut(top, [
+      "log",
+      "--no-merges",
+      "--no-renames",
+      "-z",
+      LOG_FORMAT,
+      "--name-only",
+      "--",
+      ...specs,
+    ]),
+  );
+}
+
+function botMatcher(pattern) {
+  if (!pattern) return (c) => BOT_DEFAULT.test(c.an) || /\[bot\]@/.test(c.ae || "");
+  const re = new RegExp(pattern);
+  return (c) => re.test(c.an) || re.test(c.ae || "");
+}
+
+/** One line with its `#` comment removed; a `#` inside quotes or glued to a word stays. */
+function stripComment(line) {
+  let quote = null;
+  for (let i = 0; i < line.length; i += 1) {
+    const c = line[i];
+    if (quote) {
+      if (c === quote) quote = null;
+    } else if (c === "'" || c === '"') quote = c;
+    else if (c === "#" && (i === 0 || /\s/.test(line[i - 1]))) return line.slice(0, i).trimEnd();
+  }
+  return line;
+}
+
+/**
+ * Minimal line model of a workflow file: text, lines, the same lines with
+ * comments removed (`code`, line numbers kept), and whether a pull request
+ * triggers it.
+ */
+function readWorkflows(top, files) {
+  return files
+    .filter((f) => /^\.github\/workflows\/[^/]+\.ya?ml$/.test(f))
+    .map((path) => {
+      const text = readText(top, path) || "";
+      const lines = text.split("\n");
+      const code = lines.map(stripComment);
+      const on = code.join("\n");
+      const onPR =
+        /^\s*pull_request(?:_target)?\s*:/m.test(on) ||
+        /^on:\s*(?:\[[^\]]*\bpull_request(?:_target)?\b|pull_request(?:_target)?\s*$)/m.test(on);
+      return { path, text, lines, code, onPR };
+    });
+}
+
+const indentOf = (line) => line.match(/^\s*/)[0].length;
+
+/** `run:` commands, one per logical line, continuations joined, with their line numbers. */
+function runCommands(wf) {
+  const out = [];
+  const { lines } = wf;
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = lines[i].match(/^(\s*)(?:-\s+)?run:\s*(.*)$/);
+    if (!m) continue;
+    const base = indentOf(lines[i]);
+    const val = m[2].trim();
+    const block = [];
+    if (/^[|>][-+]?\s*$/.test(val)) {
+      for (let j = i + 1; j < lines.length; j += 1) {
+        if (lines[j].trim() && indentOf(lines[j]) <= base) break;
+        block.push([j + 1, lines[j].trim()]);
+      }
+    } else if (val) {
+      block.push([i + 1, unquote(val)]);
+    }
+    let pending = null;
+    for (const [n, text] of block) {
+      if (!text || text.startsWith("#")) continue;
+      if (pending) {
+        pending.cmd = `${pending.cmd} ${text.replace(/\\$/, "").trim()}`.trim();
+      } else {
+        pending = { cmd: text.replace(/\\$/, "").trim(), line: n };
+      }
+      if (!text.endsWith("\\")) {
+        out.push({
+          ...pending,
+          cmd: pending.cmd.replace(/\s+/g, " "),
+          path: wf.path,
+          pr: wf.onPR,
+        });
+        pending = null;
+      }
+    }
+    if (pending) out.push({ ...pending, path: wf.path, pr: wf.onPR });
+  }
+  return out;
+}
+
+/** Items of a YAML key given inline (`key: [a, b]`) or as a dash list below it. */
+function yamlList(lines, i) {
+  const m = lines[i].match(/^\s*[\w-]+:\s*(.*)$/);
+  const inline = m ? m[1].trim() : "";
+  if (inline.startsWith("[")) {
+    return inline
+      .replace(/^\[|\].*$/g, "")
+      .split(",")
+      .map(unquote)
+      .filter(Boolean)
+      .map((v) => [v, i + 1]);
+  }
+  if (inline && !inline.startsWith("#")) return [[unquote(inline), i + 1]];
+  const base = indentOf(lines[i]);
+  const items = [];
+  for (let j = i + 1; j < lines.length; j += 1) {
+    if (!lines[j].trim() || lines[j].trim().startsWith("#")) continue;
+    if (indentOf(lines[j]) <= base && !lines[j].trim().startsWith("-")) break;
+    const d = lines[j].match(/^\s*-\s+(.+?)\s*(#.*)?$/);
+    if (!d) break;
+    items.push([unquote(d[1]), j + 1]);
+  }
+  return items;
+}
+
+/** Keys found inside the block that opens at line `i`. */
+function blockKeys(lines, i, key) {
+  const base = indentOf(lines[i]);
+  const found = [];
+  for (let j = i + 1; j < lines.length; j += 1) {
+    if (!lines[j].trim()) continue;
+    if (indentOf(lines[j]) <= base) break;
+    if (new RegExp(`^\\s*${key}:`).test(lines[j])) found.push(j);
+  }
+  return found;
+}
+
+// ---------------------------------------------------------------------------
+// ownedPaths
+
+/**
+ * Glob semantics of the owned-path gate: `**` spans segments, `*` and `?` stay
+ * in one, a glob without a wildcard names a file or a whole directory.
+ */
+function globRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i += 1) {
+    const ch = glob[i];
+    if (ch === "*" && glob[i + 1] === "*") {
+      const atStart = i === 0 || glob[i - 1] === "/";
+      while (glob[i + 1] === "*") i += 1;
+      if (atStart && glob[i + 1] === "/") {
+        re += "(?:[^/]*/)*";
+        i += 1;
+      } else re += ".*";
+    } else if (ch === "*") re += "[^/]*";
+    else if (ch === "?") re += "[^/]";
+    else re += esc(ch);
+  }
+  if (!/[*?[]/.test(glob)) re += "(?:/.*)?";
+  return new RegExp(`^${re}$`);
+}
+
+/**
+ * Per-path author counts over `commits`, for every directory on the way from
+ * each file up to (and including) the deepest of `roots` that holds it.
+ */
+function pathStats(commits, isBot, roots) {
+  const stats = new Map();
+  const rootSet = roots instanceof Set ? roots : new Set(roots);
+  const rootOf = (f) => [f, ...ancestors(f)].find((p) => rootSet.has(p));
+  for (const c of commits) {
+    const bot = isBot(c);
+    const touched = new Set();
+    for (const f of c.files) {
+      const root = rootOf(f);
+      if (root === undefined) continue;
+      touched.add(f);
+      for (const d of ancestors(f)) {
+        if (!underPrefix(d, root)) break;
+        touched.add(d);
+      }
+    }
+    for (const p of touched) {
+      let s = stats.get(p);
+      if (!s) stats.set(p, (s = { bot: 0, human: 0, bots: new Set(), shas: [] }));
+      if (bot) {
+        s.bot += 1;
+        s.bots.add(c.an);
+        if (s.shas.length < 3) s.shas.push(c.sha);
+      } else s.human += 1;
+    }
+  }
+  return stats;
+}
+
+const botOnly = (s) => Boolean(s) && s.human === 0 && s.bot >= MIN_OWNED_COMMITS;
+
+/**
+ * Paths only a bot has ever committed to. The fixed history window only picks
+ * candidates; each candidate is then checked against its whole history, since
+ * a directory whose recent touches are a bot's version bumps can still hold
+ * files people wrote before the window. A candidate with human commits narrows
+ * to the subdirectories and files inside it that only the bot touched.
+ */
+function historyOwned(top, history, isBot, trackedDirs, tracked) {
+  const window = pathStats(
+    history,
+    isBot,
+    new Set(history.flatMap((c) => c.files.map((f) => f.split("/")[0]))),
+  );
+  const dirs = [...window]
+    .filter(([p, s]) => trackedDirs.has(p) && botOnly(s))
+    .filter(([p]) => {
+      const parent = posix.dirname(p);
+      return parent === "." || !botOnly(window.get(parent));
+    })
+    .map(([p, s]) => ({ path: p, dir: true, bot: s.bot }));
+  const loose = [...window]
+    .filter(([p, s]) => tracked.has(p) && s.human === 0 && s.bot >= MIN_OWNED_COMMITS)
+    .filter(([p]) => !dirs.some((d) => underPrefix(p, d.path)))
+    .map(([p, s]) => ({ path: p, dir: false, bot: s.bot }));
+  const candidates = [...dirs, ...loose]
+    .sort((a, b) => b.bot - a.bot || a.path.localeCompare(b.path))
+    .slice(0, MAX_CANDIDATES);
+  if (!candidates.length) return [];
+  const roots = candidates.map((c) => c.path);
+  const full = pathStats(readPathHistory(top, roots), isBot, roots);
+  const units = [];
+  const unit = (path, glob) => {
+    const s = full.get(path);
+    units.push({ glob, prefix: path, count: s.bot, bots: s.bots, shas: s.shas });
+  };
+  const children = new Map();
+  for (const p of full.keys()) {
+    const parent = posix.dirname(p);
+    if (!children.has(parent)) children.set(parent, []);
+    children.get(parent).push(p);
+  }
+  const narrow = (dir) => {
+    for (const child of (children.get(dir) || []).sort()) {
+      const s = full.get(child);
+      if (trackedDirs.has(child)) {
+        if (botOnly(s)) unit(child, `${child}/**`);
+        else if (s.bot > 0) narrow(child);
+      } else if (tracked.has(child) && botOnly(s)) unit(child, child);
+    }
+  };
+  for (const c of candidates) {
+    const s = full.get(c.path);
+    if (!s) continue;
+    if (botOnly(s)) unit(c.path, c.dir ? `${c.path}/**` : c.path);
+    else if (c.dir && s.bot > 0) narrow(c.path);
+  }
+  units.sort((a, b) => b.count - a.count || a.glob.localeCompare(b.glob));
+  return units.slice(0, MAX_ENTRIES);
+}
+
+function ownerPattern(names) {
+  const list = [...names].sort();
+  return list.length === 1 ? `^${esc(list[0])}$` : `^(?:${list.map(esc).join("|")})$`;
+}
+
+/** Bot logins a workflow names in its code; a login inside a YAML or shell comment is an example, not a claim. */
+function workflowBotNames(wf, known) {
+  const named = new Set();
+  const code = wf.code.join("\n");
+  for (const n of known) {
+    const bare = n.replace(/\[bot\]$/, "");
+    if (code.includes(n) || (bare.length >= 4 && code.includes(bare))) named.add(n);
+  }
+  for (const m of code.matchAll(/[A-Za-z0-9._-]+\[bot\]/g)) named.add(m[0]);
+  return named;
+}
+
+/** Whether a workflow reads a bot identity from configuration (`vars.SYNC_BOT_LOGIN`, `BOT_LOGIN:`). */
+const mentionsBot = (wf) =>
+  /\b(?:vars|secrets)\.\w*BOT\w*|\b\w*BOT_(?:LOGIN|NAME|USER|EMAIL|ACTOR)\b/i.test(
+    wf.code.join("\n"),
+  );
+
+// Paths a workflow's steps check: case arms and `git diff -- <pathspec>`. An
+// `on.*.paths` trigger filter only says when the workflow runs, so it is never
+// read as ownership.
+function workflowGlobs(wf) {
+  const globs = [];
+  for (const g of caseArmGlobs(wf.code)) globs.push(g);
+  for (const [p, n] of gitPathspecs(wf.code)) globs.push([p, n, "own"]);
+  return globs.map(([p, n, kind]) => [normalizeGlob(p), n, kind]).filter(([p]) => p);
+}
+
+/** A repo-relative glob: no leading `./` or `/`, no doubled or trailing slash. */
+export function normalizeGlob(glob) {
+  return String(glob)
+    .replace(/\/{2,}/g, "/")
+    .replace(/^(?:\.\/)+/, "")
+    .replace(/^\/+/, "")
+    .replace(/\/+$/, "");
+}
+
+/**
+ * A shell `case` pattern as a gate glob, or null when the gate cannot say the
+ * same thing. A case `*` crosses `/`: a segment that is only stars becomes
+ * `**` (`A/*` + `/G/*` covers `A/x/y/G/z/w`), and a last segment that starts
+ * with a star (`A/*.swift`) becomes `**` + `/` + that segment. Any other star
+ * inside a segment has no exact glob: an owned arm widens to its literal
+ * directory plus `/**`, which can only block more, and an exception arm is
+ * dropped, which can only exempt less.
+ */
+function caseGlob(p, kind = "own") {
+  const segs = p.split("/");
+  const out = [];
+  for (let i = 0; i < segs.length; i += 1) {
+    const seg = segs[i];
+    if (!seg.includes("*")) out.push(seg);
+    else if (/^\*+$/.test(seg)) out.push("**");
+    else if (i === segs.length - 1 && seg.startsWith("*") && !seg.slice(1).includes("*")) {
+      out.push("**", seg);
+    } else {
+      if (kind !== "own") return null;
+      const head = out.join("/");
+      return head ? `${head}/**` : "**";
+    }
+  }
+  return out.join("/");
+}
+
+// Shell `case` arms that match paths. An arm whose body does what the `*)`
+// default arm does is an exception carved out of a broader arm; any other arm
+// is an owned path. Without a default arm every path arm counts as owned.
+function caseArmGlobs(lines) {
+  const out = [];
+  let arms = null;
+  const flush = () => {
+    if (!arms) return;
+    const fallback = arms.find((a) => a.patterns.includes("*"));
+    for (const a of arms) {
+      if (a.patterns.includes("*")) continue;
+      const kind = fallback && a.body === fallback.body ? "except" : "own";
+      for (const p of a.patterns) {
+        if (!p.includes("/") || /\s/.test(p)) continue;
+        const glob = caseGlob(p, kind);
+        if (glob) out.push([glob, a.line, kind]);
+      }
+    }
+    arms = null;
+  };
+  lines.forEach((line, i) => {
+    if (/\bcase\b.+\bin\s*$/.test(line)) {
+      flush();
+      arms = [];
+      return;
+    }
+    if (/^\s*esac\b/.test(line)) {
+      flush();
+      return;
+    }
+    if (!arms) return;
+    const m = line.match(/^\s*\(?([^()\s#;][^();]*)\)(.*)$/);
+    if (!m) return;
+    const body = m[2].replace(/;;\s*$/, "").trim();
+    arms.push({ patterns: m[1].split("|").map(unquote), body, line: i + 1 });
+  });
+  flush();
+  return out;
+}
+
+// An owned path under another owned path adds nothing to the gate: the outer
+// one already covers it. Its evidence and bypass move to the outer entry, and
+// the outer entry takes the higher confidence of the two.
+// `dir/**` with no wildcard in `dir`: a plain subtree another path can sit under.
+const isSubtree = (glob) => glob.endsWith("/**") && !/[*?[]/.test(glob.slice(0, -3));
+
+const RANK = { low: 0, medium: 1, high: 2 };
+
+function joinBasis(a, b) {
+  if (a === b) return a;
+  return "history+workflow";
+}
+
+function absorb(host, e) {
+  for (const ev of e.evidence) if (!host.evidence.includes(ev)) host.evidence.push(ev);
+  if (e.commits !== undefined) host.commits = Math.max(host.commits ?? 0, e.commits);
+  host.bypass = host.bypass || e.bypass;
+  host.basis = joinBasis(host.basis, e.basis);
+  for (const b of e.bots) host.bots.add(b);
+  if (host.basis !== "history" && RANK[e.confidence] > RANK[host.confidence]) {
+    host.confidence = e.confidence;
+  }
+  if (host.basis === "history+workflow") host.confidence = "high";
+}
+
+function foldNested(entries) {
+  const outer = [...entries].sort((a, b) => globPrefix(a.glob).length - globPrefix(b.glob).length);
+  const kept = [];
+  for (const e of outer) {
+    const prefix = globPrefix(e.glob);
+    const host = kept.find((k) => {
+      if (!isSubtree(k.glob)) return false;
+      const kp = globPrefix(k.glob);
+      return prefix === kp || prefix.startsWith(`${kp}/`);
+    });
+    if (!host) {
+      kept.push({ ...e, evidence: [...e.evidence], bots: new Set(e.bots) });
+      continue;
+    }
+    absorb(host, e);
+  }
+  const order = new Map(entries.map((e, i) => [e.glob, i]));
+  return kept.sort((a, b) => order.get(a.glob) - order.get(b.glob));
+}
+
+// Paths after ` -- ` in a git diff/log/ls-files command, the form a lock job
+// uses to list the trees it guards. Backslash continuations are joined so a
+// pathspec on its own line still belongs to the command above it. A bare
+// directory becomes `<dir>/**`.
+function gitPathspecs(lines) {
+  const out = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!/\bgit\s+(?:diff|log|ls-files)\b/.test(lines[i])) continue;
+    let text = lines[i];
+    let j = i;
+    while (/\\\s*$/.test(lines[j]) && j + 1 < lines.length) {
+      j += 1;
+      text = `${text.replace(/\\\s*$/, " ")}${lines[j]}`;
+    }
+    const at = text.search(/\s--\s/);
+    if (at < 0) continue;
+    for (const tok of text.slice(at + 4).match(/'[^']+'|"[^"]+"|[^\s)|;&]+/g) || []) {
+      const p = unquote(tok).replace(/\/+$/, "");
+      if (!p.includes("/") || p.includes("$") || /\s/.test(p) || p.startsWith("-")) continue;
+      out.push([/[*?[]/.test(p) ? p : `${p}/**`, i + 1]);
+    }
+    i = j;
+  }
+  return out;
+}
+
+/** Bots that committed, in the window, to a path `glob` covers. */
+function committersUnder(history, isBot, glob) {
+  const re = globRegExp(glob);
+  const out = new Map();
+  for (const c of history) {
+    if (!isBot(c) || !c.files.some((f) => re.test(f))) continue;
+    bump(out, c.an);
+  }
+  return out;
+}
+
+function deriveOwnedPaths(top, history, isBot, trackedDirs, files, workflows) {
+  const tracked = new Set(files);
+  const botNames = new Set(history.filter(isBot).map((c) => c.an));
+  const entries = historyOwned(top, history, isBot, trackedDirs, tracked).map((o) => ({
+    glob: o.glob,
+    bypass: null,
+    commits: o.count,
+    evidence: o.shas.map(short),
+    confidence: "medium",
+    bots: new Set(o.bots),
+    basis: "history",
+  }));
+  const excepts = [];
+  const fromWorkflows = [];
+  for (const wf of workflows) {
+    const named = workflowBotNames(wf, botNames);
+    if (!named.size && !mentionsBot(wf)) continue;
+    const label = wf.code.join("\n").match(/labels\.\*\.name\s*,\s*['"]([^'"]+)['"]/);
+    const bypass = label ? { label: label[1] } : null;
+    const found = workflowGlobs(wf);
+    for (const [glob, line] of found.filter(([, , kind]) => kind === "except")) {
+      excepts.push([glob, `${wf.path}:${line}`]);
+    }
+    // One lock job guards its paths for one account: the bots that actually
+    // committed under any path it guards, else the bots it names in code.
+    const own = found
+      .filter(([, , kind]) => kind === "own")
+      .map(([glob, line]) => ({ glob, line, committed: committersUnder(history, isBot, glob) }));
+    const committers = new Set(own.flatMap((o) => [...o.committed.keys()]));
+    const bots = committers.size ? committers : named;
+    if (!bots.size) continue;
+    for (const { glob, line, committed } of own) {
+      const commits = [...committed.values()].reduce((a, b) => a + b, 0);
+      fromWorkflows.push({
+        glob,
+        bypass,
+        evidence: [`${wf.path}:${line}`],
+        confidence: commits >= MIN_OWNED_COMMITS ? "high" : "medium",
+        bots: new Set(bots),
+        basis: "workflow",
+      });
+    }
+  }
+  for (const w of fromWorkflows) {
+    const hit = entries.find(
+      (e) => e.glob === w.glob || (isSubtree(w.glob) && globPrefix(e.glob) === globPrefix(w.glob)),
+    );
+    if (hit) absorb(hit, w);
+    else entries.push(w);
+  }
+  // A CI job that locks only part of a directory history calls bot-owned is
+  // the narrower, deliberate rule: the history entry folds into it.
+  const locks = entries
+    .filter((w) => w.basis !== "history" && !isSubtree(w.glob))
+    .map((w) => ({ w, re: globRegExp(w.glob) }));
+  const narrowed = entries.filter((h) => {
+    if (h.basis !== "history" || !locks.length) return true;
+    const root = h.glob.replace(/\/\*\*$/, "");
+    const inside = files.filter((f) => underPrefix(f, root));
+    const host = locks.find(
+      ({ w, re }) => [...h.bots].some((b) => w.bots.has(b)) && inside.some((f) => re.test(f)),
+    )?.w;
+    if (!host) return true;
+    absorb(host, h);
+    return false;
+  });
+  const folded = foldNested(narrowed);
+  for (const [glob, ev] of excepts) {
+    const prefix = globPrefix(glob);
+    const host = folded.find((e) => {
+      if (!isSubtree(e.glob)) return false;
+      const hp = globPrefix(e.glob);
+      return prefix === hp || prefix.startsWith(`${hp}/`);
+    });
+    if (!host) continue;
+    host.except = [...new Set([...(host.except || []), glob])];
+    if (!host.evidence.includes(ev)) host.evidence.push(ev);
+  }
+  const kept = folded.filter((e) => !excepts.some(([g]) => g === e.glob && !e.except));
+  return kept
+    .slice(0, MAX_ENTRIES)
+    .map(({ glob, bots, bypass, commits, evidence, confidence, except, basis }) => {
+      const fields = { glob, owner: ownerPattern(bots), bypass };
+      if (commits !== undefined) fields.commits = commits;
+      fields.basis = basis;
+      if (except && except.length) fields.except = except;
+      return entry(fields, evidence, basis === "history" ? "medium" : confidence);
+    });
+}
+
+// ---------------------------------------------------------------------------
+// generators
+
+function scanStamps(top, files) {
+  const buf = Buffer.alloc(HEADER_BYTES);
+  const stamped = new Map();
+  const scanned = [];
+  for (const f of files) {
+    if (!SOURCE_EXT.test(f)) continue;
+    scanned.push(f);
+    const head = readHeader(top, f, buf);
+    if (!STAMP_RE.test(head)) continue;
+    const lines = head.split("\n").slice(0, HEADER_LINES);
+    const idx = lines.findIndex((l) => STAMP_LINE_RE.test(l));
+    if (idx < 0) continue;
+    const text = lines[idx]
+      .replace(/^[\s/*#<!-]+|[\s*/>-]+$/g, "")
+      .trim()
+      .slice(0, 120);
+    stamped.set(f, { line: idx + 1, text });
+  }
+  return { stamped, scanned };
+}
+
+function stampedOutputs(stamped, scanned) {
+  const total = new Map();
+  const hit = new Map();
+  for (const f of scanned) {
+    for (const d of ancestors(f)) {
+      bump(total, d);
+      if (stamped.has(f)) bump(hit, d);
+    }
+  }
+  const qualifies = (d) => (hit.get(d) || 0) >= 2 && hit.get(d) / total.get(d) >= 0.9;
+  const dirs = [...hit.keys()].filter((d) => {
+    if (!qualifies(d)) return false;
+    const parent = posix.dirname(d);
+    return parent === "." || !qualifies(parent);
+  });
+  const loose = [...stamped.keys()].filter((f) => !dirs.some((d) => underPrefix(f, d)));
+  return { dirs, loose };
+}
+
+function coChange(history, prefix, outputs) {
+  const touching = history.filter((c) => c.files.some((f) => underPrefix(f, prefix)));
+  if (!touching.length) return { input: null, sameCommit: null, commits: 0 };
+  const counts = new Map();
+  for (const c of touching) {
+    const dirs = new Set();
+    for (const f of c.files) {
+      if (underPrefix(f, prefix)) continue;
+      const d = posix.dirname(f);
+      if (d === "." || outputs.some((o) => underPrefix(f, o))) continue;
+      dirs.add(d);
+    }
+    for (const d of dirs) bump(counts, d);
+  }
+  const best = topCount(counts);
+  if (!best || best[1] < 2 || best[1] / touching.length < 0.5) {
+    return {
+      input: null,
+      sameCommit: touching.length >= 3 ? false : null,
+      commits: touching.length,
+    };
+  }
+  // Inputs often span sibling directories (one spec per domain); the input is
+  // their common parent, not whichever sibling happened to count highest.
+  // Peers are grouped by top-level directory and the heaviest group wins, so
+  // one unrelated directory that changes alongside does not lift the input to
+  // the repo root.
+  const groups = new Map();
+  for (const [d, n] of counts) {
+    if (n < 2 || n < best[1] / 2) continue;
+    const head = d.split("/")[0];
+    if (!groups.has(head)) groups.set(head, { weight: 0, dirs: [] });
+    const g = groups.get(head);
+    g.weight += n;
+    g.dirs.push(d.split("/"));
+  }
+  const heaviest = [...groups.values()].sort((a, b) => b.weight - a.weight)[0];
+  let common = heaviest.dirs[0];
+  for (const segs of heaviest.dirs.slice(1)) {
+    let k = 0;
+    while (k < common.length && k < segs.length && common[k] === segs[k]) k += 1;
+    common = common.slice(0, k);
+  }
+  const input = common.join("/");
+  return {
+    input: `${input}/**`,
+    sameCommit: best[1] / touching.length >= 0.8,
+    commits: touching.length,
+  };
+}
+
+/** A command without the logging plumbing CI wraps it in: `2>&1`, `| tee ...`. */
+function stripPlumbing(cmd) {
+  let out = cmd;
+  for (let prev = null; prev !== out;) {
+    prev = out;
+    out = out
+      .replace(/\s*\|\s*tee\b[^|]*$/, "")
+      .replace(/\s+[12]?>&[12]\s*$/, "")
+      .trim();
+  }
+  return out;
+}
+
+/** A run that verifies the output is current and regenerates nothing. */
+const isCheckRun = (cmd) => /(?:^|\s)--(?:check|verify|dry-run)(?:[\s=]|$)/.test(cmd);
+
+/**
+ * The CI steps that produce `prefix`: the regenerate command, and separately
+ * the step that only checks it (`--check`, `--verify`, `--dry-run`).
+ */
+function generatorCommand(stampText, prefix, commands) {
+  const pool = [];
+  const tool = stampText && stampText.match(/generated by\s+([A-Za-z0-9_.-]*[A-Za-z0-9_])/i);
+  if (tool) {
+    const re = new RegExp(`(^|[\\s/])${esc(tool[1])}(\\s|$)`, "i");
+    pool.push(...commands.filter((x) => re.test(x.cmd)));
+  }
+  pool.push(...commands.filter((x) => x.cmd.includes(prefix) && !inspectsOnly(x.cmd)));
+  const clean = [...new Set(pool)].map((x) => ({ ...x, cmd: stripPlumbing(x.cmd) }));
+  return {
+    command: clean.find((x) => !isCheckRun(x.cmd)) || null,
+    check: clean.find((x) => isCheckRun(x.cmd)) || null,
+  };
+}
+
+// A CI line that reads the tree (a drift or lock check) names the output
+// directory too, but running it regenerates nothing.
+function inspectsOnly(cmd) {
+  const body = cmd
+    .replace(/^\s*[A-Za-z_][A-Za-z0-9_]*=\$\(/, "")
+    .replace(/^\s*(?:test|\[)\s+-[nz]\s+"?\$\(/, "");
+  return /^\s*(?:git\s+(?:diff|log|status|ls-files|show|rev-parse)|grep|find|ls|cat|test\b|\[)/.test(
+    body,
+  );
+}
+
+function deriveGenerators(top, files, trackedDirs, history, commands) {
+  const { stamped, scanned } = scanStamps(top, files);
+  const { dirs, loose } = stampedOutputs(stamped, scanned);
+  const outputs = [];
+  for (const d of dirs) {
+    const inside = [...stamped.entries()].filter(([f]) => underPrefix(f, d));
+    outputs.push({
+      prefix: d,
+      glob: `${d}/**`,
+      evidence: inside.slice(0, 3).map(([f, s]) => `${f}:${s.line}`),
+      stamp: inside[0]?.[1].text || null,
+      confidence: inside.length >= 5 ? "high" : "medium",
+    });
+  }
+  const generatedDirs = [...trackedDirs]
+    .filter((d) => /^generated$/i.test(posix.basename(d)))
+    .filter(
+      (d) =>
+        !ancestors(`${d}/x`)
+          .slice(1)
+          .some((a) => /^generated$/i.test(posix.basename(a))),
+    )
+    .sort();
+  for (const d of generatedDirs) {
+    if (outputs.some((o) => underPrefix(d, o.prefix))) continue;
+    outputs.push({ prefix: d, glob: `${d}/**`, evidence: [d], stamp: null, confidence: "medium" });
+  }
+  for (const f of loose) {
+    if (outputs.some((o) => underPrefix(f, o.prefix))) continue;
+    const s = stamped.get(f);
+    outputs.push({
+      prefix: f,
+      glob: f,
+      evidence: [`${f}:${s.line}`],
+      stamp: s.text,
+      confidence: "medium",
+    });
+  }
+  const prefixes = outputs.map((o) => o.prefix);
+  return outputs.slice(0, MAX_ENTRIES).map((o) => {
+    const co = coChange(history, o.prefix, prefixes);
+    const { command, check } = generatorCommand(o.stamp, o.prefix, commands);
+    const evidence = [...o.evidence];
+    for (const c of [command, check]) if (c) evidence.push(`${c.path}:${c.line}`);
+    return entry(
+      {
+        output: o.glob,
+        input: co.input,
+        command: command ? command.cmd : null,
+        check: check ? check.cmd : null,
+        sameCommit: co.sameCommit,
+        stamp: o.stamp,
+      },
+      evidence,
+      o.confidence,
+      co.commits ? `${co.commits} commits touched the output` : undefined,
+    );
+  });
+}
+
+// ---------------------------------------------------------------------------
+// commit format
+
+const TICKET = "(?:[A-Z][A-Z0-9]+-\\d+|#\\d+)";
+const PREFIX_RE = new RegExp(`^\\s*([\\[(]?)\\s*(${TICKET})\\s*([\\])]?)(:?)`);
+const SUFFIX_RE = new RegExp(`([\\[(]?)\\s*(${TICKET})\\s*([\\])]?)\\s*$`);
+const CONV_RE = /^[a-z]+(\([^)]+\))?!?:\s/;
+
+function ticketStyle(open, token, close, colon) {
+  const ph = token.startsWith("#") ? "#123" : "KEY-123";
+  return `${open}${ph}${close}${colon || ""}`;
+}
+
+function classifySubject(subject) {
+  const s = subject.replace(/\s*\(#\d+\)\s*$/, "");
+  const body = s.replace(CONV_RE, "");
+  let m = s.match(PREFIX_RE) || (body !== s ? body.match(PREFIX_RE) : null);
+  if (m && (m[1] === "" || m[3] !== "")) {
+    const rest = (s.match(PREFIX_RE) ? s : body).slice(m[0].length).trim();
+    return {
+      position: "prefix",
+      style: ticketStyle(m[1], m[2], m[3], m[4]),
+      rest: s.match(PREFIX_RE) ? rest : s,
+    };
+  }
+  m = s.match(SUFFIX_RE);
+  if (m && (m[1] === "" || m[3] !== "") && m.index > 0) {
+    return { position: "suffix", style: ticketStyle(m[1], m[2], m[3], ""), rest: s };
+  }
+  return { position: "none", style: null, rest: s };
+}
+
+function deriveCommitFormat(history, isBot) {
+  const sample = history.filter((c) => !isBot(c)).slice(0, COMMIT_SAMPLE);
+  if (!sample.length) return role(null);
+  const rows = sample.map((c) => ({ c, ...classifySubject(c.subject) }));
+  const byPos = new Map();
+  for (const r of rows) bump(byPos, r.position);
+  const [position, count] = topCount(byPos);
+  const styles = new Map();
+  for (const r of rows) if (r.position === position && r.style) bump(styles, r.style);
+  const style = position === "none" ? null : topCount(styles)[0];
+  const convRows = rows.filter((r) => CONV_RE.test(r.rest));
+  const scoped = convRows.filter((r) => /^[a-z]+\([^)]+\)/.test(r.rest));
+  const examples = rows.filter((r) => r.position === position && r.style === style);
+  const share = count / rows.length;
+  const confidence =
+    rows.length >= 20 && share >= 0.8
+      ? "high"
+      : rows.length >= 5 && share >= 0.6
+        ? "medium"
+        : "low";
+  return role(
+    {
+      ticketPosition: position,
+      ticketStyle: style,
+      scopeRequired: convRows.length > 0 && scoped.length / convRows.length >= 0.8,
+      conventional: convRows.length / rows.length >= 0.5,
+      example: examples[0]?.c.subject || null,
+      sampleSize: rows.length,
+    },
+    examples.slice(0, 5).map((r) => short(r.c.sha)),
+    confidence,
+    `${count} of ${rows.length} subjects`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// branches
+
+/** Branches named under an `on:` event block (`pull_request:`, `push:`), per workflow once. */
+function eventBranches(workflows, eventRe) {
+  const targets = new Map();
+  const ev = new Map();
+  for (const wf of workflows) {
+    const seen = new Set();
+    wf.code.forEach((line, i) => {
+      if (!eventRe.test(line)) return;
+      for (const j of blockKeys(wf.code, i, "branches")) {
+        for (const [b, n] of yamlList(wf.code, j)) {
+          if (/[*?[]/.test(b) || seen.has(b)) continue;
+          seen.add(b);
+          bump(targets, b);
+          if (!ev.has(b)) ev.set(b, []);
+          ev.get(b).push(`${wf.path}:${n}`);
+        }
+      }
+    });
+  }
+  return { targets, ev };
+}
+
+const refExists = (top, ref) =>
+  Boolean(gitOut(top, ["rev-parse", "--verify", "--quiet", ref]).trim());
+
+function deriveBranches(top, workflows) {
+  const pr = eventBranches(workflows, /^\s*pull_request(_target)?:\s*$/);
+  const push = eventBranches(workflows, /^\s*push:\s*$/);
+  const originHead = gitOut(top, ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"]).trim();
+  let defaultBranch;
+  if (originHead) {
+    defaultBranch = role(
+      originHead.replace(/^refs\/remotes\/origin\//, ""),
+      ["git:refs/remotes/origin/HEAD"],
+      "high",
+    );
+  } else {
+    const cur = gitOut(top, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    defaultBranch =
+      cur && cur !== "HEAD"
+        ? role(cur, ["git:HEAD"], "low", "no origin/HEAD; current branch")
+        : role(null);
+  }
+  const best = topCount(pr.targets);
+  if (best) {
+    return {
+      workBranch: role(best[0], pr.ev.get(best[0]), best[1] >= 2 ? "high" : "medium"),
+      defaultBranch,
+    };
+  }
+  // No pull request names a target: the branch CI runs on when something is
+  // pushed to it is where work lands. It counts double when the branch exists.
+  const pushed = topCount(push.targets);
+  if (pushed) {
+    const [b, n] = pushed;
+    const local = refExists(top, `refs/heads/${b}`) || refExists(top, `refs/remotes/origin/${b}`);
+    return {
+      workBranch: role(b, push.ev.get(b), n >= 2 || local ? "high" : "medium", "push target"),
+      defaultBranch,
+    };
+  }
+  const candidates = ["develop", "development", "dev", "main", "master", "trunk"];
+  const activity = new Map();
+  const where = new Map();
+  for (const b of candidates) {
+    for (const ref of [`refs/remotes/origin/${b}`, `refs/heads/${b}`]) {
+      if (!refExists(top, ref)) continue;
+      const n = Number(gitOut(top, ["rev-list", "--count", "--since=90.days", ref]).trim()) || 0;
+      if (!activity.has(b) || n > activity.get(b)) {
+        activity.set(b, n);
+        where.set(b, ref);
+      }
+    }
+  }
+  const active = topCount(activity);
+  return {
+    workBranch: active
+      ? role(active[0], [`git:${where.get(active[0])}`], "low", "most active integration branch")
+      : role(null),
+    defaultBranch,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CI commands
+
+const LINT_RE =
+  /\b(swiftlint|ktlint|detekt|eslint|ruff|flake8|golangci-lint|rubocop)\b|\bswiftformat\b.*--lint|\b(npm|pnpm|yarn)\s+(run\s+)?lint\b|\bgradlew?\b.*\b(lint\w*|detekt|ktlintCheck)\b/;
+const TEST_RE =
+  /\bxcodebuild\b.*\btest(-without-building)?\b|\bgradlew?\b.*\b(test\w*|check|connected\w*AndroidTest)\b|\b(npm|pnpm|yarn)\s+(run\s+)?test\b|\bswift\s+test\b|\bpytest\b|\bgo\s+test\b|\bcargo\s+test\b|\bmvn\b.*\btest\b/;
+const BUILD_RE =
+  /\bxcodebuild\b.*\b(build|build-for-testing|archive)\b|\bgradlew?\b.*\b(assemble\w*|build\w*|bundle\w*)\b|\b(npm|pnpm|yarn)\s+(run\s+)?build\b|\bswift\s+build\b|\bgo\s+build\b|\bcargo\s+build\b|\bmvn\b.*\b(package|install|compile)\b/;
+
+function classifyCommand(cmd) {
+  if (LINT_RE.test(cmd)) return "lint";
+  if (TEST_RE.test(cmd)) return "test";
+  if (BUILD_RE.test(cmd)) return "build";
+  return null;
+}
+
+function pickCommand(list) {
+  if (!list.length) return null;
+  const freq = new Map();
+  for (const c of list) bump(freq, c.cmd);
+  const [cmd, n] = topCount(freq);
+  const hits = list.filter((c) => c.cmd === cmd);
+  return {
+    cmd,
+    first: hits[0],
+    evidence: hits.map((c) => `${c.path}:${c.line}`),
+    n,
+    pr: hits.some((c) => c.pr),
+  };
+}
+
+function packageScripts(top, files) {
+  if (!files.includes("package.json")) return {};
+  try {
+    const scripts = JSON.parse(readText(top, "package.json") || "{}").scripts || {};
+    const pm = files.includes("pnpm-lock.yaml")
+      ? "pnpm"
+      : files.includes("yarn.lock")
+        ? "yarn"
+        : "npm";
+    const out = {};
+    for (const k of ["build", "test", "lint"]) if (scripts[k]) out[k] = `${pm} run ${k}`;
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+function deriveCommands(top, files, commands) {
+  const kinds = { build: [], test: [], lint: [] };
+  for (const c of commands) {
+    const k = classifyCommand(c.cmd);
+    if (k) kinds[k].push(c);
+  }
+  const pkg = packageScripts(top, files);
+  const pick = (kind, shape) => {
+    const p = pickCommand(kinds[kind]);
+    // A step a pull request runs is what CI holds every change to.
+    if (p) {
+      return role(shape(p.cmd, p.first.path), p.evidence, p.n >= 2 || p.pr ? "high" : "medium");
+    }
+    if (pkg[kind]) return role(shape(pkg[kind], "package.json"), ["package.json"], "low");
+    return role(null);
+  };
+  const plans = new Set();
+  for (const c of kinds.test)
+    for (const m of c.cmd.matchAll(/-testPlan\s+("[^"]+"|'[^']+'|\S+)/g)) plans.add(unquote(m[1]));
+  for (const f of files) if (f.endsWith(".xctestplan")) plans.add(posix.basename(f, ".xctestplan"));
+  const test = pick("test", (command) => ({ command, plans: [...plans] }));
+  if (test.value === null && plans.size) {
+    test.value = { command: null, plans: [...plans] };
+    test.evidence = files.filter((f) => f.endsWith(".xctestplan")).slice(0, 5);
+  }
+  return {
+    build: pick("build", (command, source) => ({ command, source })),
+    test,
+    lint: pick("lint", (command) => ({ command })),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// accessors, DI, modules, mocks
+
+const DOMAIN_RE = {
+  localization: /locali[sz]|strings|l10n|i18n|translat/i,
+  testingId: /testing.?ident|accessibility.?ident|ui.?test.?ident|test.?id|test.?tag/i,
+  tokens: /token|colou?r|typograph|spacing|radius|font/i,
+};
+const INJECT_RE =
+  /@(Inject|Injected|LazyInjected|WeakLazyInjected|Injection|InjectedObject|Autowired)\b/g;
+const INJECT_LITERALS = ["@Inject", "@LazyInjected", "@WeakLazyInjected", "@Autowired"];
+const MOCK_RE =
+  /import (Mockingbird|Cuckoo|MockSwift|SwiftyMocky|Mockolo)\b|\b(io\.mockk|org\.mockito|jest\.mock|unittest\.mock|gomock|sinon)\b/g;
+const MOCK_LITERALS = [
+  "import Mockingbird",
+  "import Cuckoo",
+  "import MockSwift",
+  "import SwiftyMocky",
+  "import Mockolo",
+  "io.mockk",
+  "org.mockito",
+  "jest.mock",
+  "unittest.mock",
+  "gomock",
+  "sinon",
+];
+
+// Only column-0 declarations are candidate roots: nested types are reached
+// through their root. A top-level `extension` counts, because generators often
+// hang the whole accessor tree off a root type declared elsewhere.
+const TOP_LEVEL_TYPE_RE =
+  /^(?:(?:public|internal|open|final|fileprivate|private|data|sealed|@\w+)\s+)*(?:enum|struct|class|object|extension)\s+([A-Z][A-Za-z0-9_]*)/;
+
+/** Top-level type names the generated files of each domain declare, with where. */
+function accessorCandidates(top, genFiles) {
+  const out = {};
+  for (const domain of Object.keys(DOMAIN_RE)) {
+    const decl = new Map();
+    for (const f of genFiles.filter((g) => DOMAIN_RE[domain].test(g)).slice(0, 20)) {
+      (readText(top, f, 64 * 1024) || "").split("\n").forEach((line, i) => {
+        const m = line.match(TOP_LEVEL_TYPE_RE);
+        if (m && decl.size < 10 && !decl.has(m[1])) decl.set(m[1], `${f}:${i + 1}`);
+      });
+    }
+    out[domain] = decl;
+  }
+  return out;
+}
+
+/**
+ * One fixed-string `git grep` over source files for every literal any usage
+ * heuristic needs, returning the matching lines. Fixed strings keep the scan
+ * linear; the exact patterns (word boundaries, three-segment accessors) are
+ * applied to the returned lines, which POSIX ERE in `git grep -E` could not
+ * express anyway.
+ */
+function scanUsage(top, literals) {
+  if (!literals.length) return [];
+  const args = ["grep", "-I", "--no-color", "-n", "-z", "-F"];
+  for (const l of literals) args.push("-e", l);
+  const out = gitOut(top, [...args, "--", ...GREP_PATHSPEC]);
+  const lines = [];
+  for (const raw of out.split("\n")) {
+    const a = raw.indexOf("\0");
+    const b = a < 0 ? -1 : raw.indexOf("\0", a + 1);
+    if (a > 0 && b > a) {
+      lines.push({
+        path: raw.slice(0, a),
+        line: Number(raw.slice(a + 1, b)),
+        text: raw.slice(b + 1),
+      });
+    }
+  }
+  return lines;
+}
+
+/** Source-file families, so a role read from code comes from the language the repo is written in. */
+const LANGUAGES = {
+  swift: /\.swift$/,
+  jvm: /\.(kt|kts|java)$/,
+  js: /\.(ts|tsx|js|jsx|mjs|cjs)$/,
+  python: /\.py$/,
+  go: /\.go$/,
+  rust: /\.rs$/,
+  dart: /\.dart$/,
+  dotnet: /\.cs$/,
+  objc: /\.(m|mm)$/,
+};
+
+const languageOf = (path) => Object.keys(LANGUAGES).find((k) => LANGUAGES[k].test(path)) || null;
+
+function dominantLanguage(files) {
+  const counts = new Map();
+  for (const f of files) {
+    const l = languageOf(f);
+    if (l) bump(counts, l);
+  }
+  return topCount(counts)?.[0] ?? null;
+}
+
+function accessorRoots(decl, usage, outPrefixes) {
+  if (!decl.size) return [];
+  const re = new RegExp(
+    `\\b(${[...decl.keys()].map(esc).join("|")})\\.[A-Za-z_]\\w*\\.[A-Za-z_]\\w*`,
+    "g",
+  );
+  const counts = new Map();
+  for (const { path, text } of usage) {
+    if (outPrefixes.some((p) => underPrefix(path, p))) continue;
+    for (const m of text.matchAll(re)) bump(counts, m[1]);
+  }
+  return [...counts]
+    .filter(([, n]) => n >= 3)
+    .sort((a, b) => b[1] - a[1])
+    .map(([name, n]) => ({ name, n, evidence: decl.get(name) }));
+}
+
+function conventionRole(bucket) {
+  if (!bucket || !bucket.pattern || !["high", "medium", "low"].includes(bucket.confidence))
+    return null;
+  const ev = (bucket.evidenceFiles || []).filter((e) => typeof e === "string");
+  return role(bucket.pattern, ev, bucket.confidence, "from extract-conventions.sh");
+}
+
+function deriveAccessors(candidates, usage, outPrefixes, conventions) {
+  const one = (domain) => {
+    const roots = accessorRoots(candidates[domain], usage, outPrefixes);
+    if (!roots.length) return role(null);
+    const [r] = roots;
+    return role(r.name, [r.evidence], r.n >= 20 ? "high" : "medium", `${r.n} usages`);
+  };
+  const localization = one("localization");
+  if (localization.value === null && conventions?.localizationKey?.pattern) {
+    localization.note = `key style: ${conventions.localizationKey.pattern}`;
+  }
+  const tokenRoots = accessorRoots(candidates.tokens, usage, outPrefixes).slice(0, 5);
+  return {
+    localization,
+    accessibility: conventionRole(conventions?.accessibilityIdentifier) || role(null),
+    testingId: one("testingId"),
+    tokens: tokenRoots.length
+      ? role(
+          tokenRoots.map((r) => r.name),
+          tokenRoots.map((r) => r.evidence),
+          tokenRoots[0].n >= 20 ? "high" : "medium",
+        )
+      : role([]),
+  };
+}
+
+// The words DI wiring types end in across frameworks. Which compound suffix a
+// repo builds from them (`FeatureAssembly`, `DependencyContainer`) is read from
+// the file names, never listed here.
+const REGISTRAR_WORD_RE =
+  /^([A-Z][A-Za-z0-9]*?)(Registrar|Configurator|Assembly|Container|Module)\.(swift|kt|java|ts)$/;
+
+const camelWords = (name) => name.match(/[A-Z]+(?![a-z])|[A-Z][a-z0-9]*|[a-z0-9]+/g) || [];
+
+/** The longest trailing run of CamelCase words at least 80% of `names` end in. */
+function commonSuffix(names) {
+  const words = names.map(camelWords);
+  let best = null;
+  for (let k = 1; k <= Math.max(...words.map((w) => w.length)); k += 1) {
+    const counts = new Map();
+    for (const w of words) if (w.length > k) bump(counts, w.slice(-k).join(""));
+    const top1 = topCount(counts);
+    if (!top1 || top1[1] < names.length * 0.8) break;
+    best = top1[0];
+  }
+  return best;
+}
+
+function deriveDi(top, files, usage, conventions, language) {
+  const families = new Map();
+  for (const f of files) {
+    if (language && languageOf(f) !== language) continue;
+    const m = posix.basename(f).match(REGISTRAR_WORD_RE);
+    if (!m) continue;
+    if (!families.has(m[2])) families.set(m[2], []);
+    families.get(m[2]).push(f);
+  }
+  let family = null;
+  for (const [word, list] of families)
+    if (!family || list.length > family[1].length) family = [word, list];
+  let registrarSuffix = role(null);
+  let registerMethod = role(null);
+  const suffix =
+    family && family[1].length >= 2
+      ? commonSuffix(family[1].map((f) => posix.basename(f).replace(/\.\w+$/, "")))
+      : null;
+  const byType = suffix
+    ? family[1].filter((f) =>
+        posix
+          .basename(f)
+          .replace(/\.\w+$/, "")
+          .endsWith(suffix),
+      )
+    : [];
+  const best = suffix ? [suffix, byType.length] : null;
+  if (best && best[1] >= 2) {
+    const sample = byType;
+    registrarSuffix = role(
+      best[0],
+      sample.slice(0, 3),
+      best[1] >= 5 ? "high" : "medium",
+      `${best[1]} files`,
+    );
+    const methods = new Map();
+    const where = new Map();
+    for (const f of sample.slice(0, 30)) {
+      (readText(top, f, 64 * 1024) || "").split("\n").forEach((line, i) => {
+        for (const m of line.matchAll(/\b(?:func|fun|function)\s+([a-z]\w*)\s*\(/g)) {
+          bump(methods, m[1]);
+          if (!where.has(m[1])) where.set(m[1], `${f}:${i + 1}`);
+        }
+      });
+    }
+    const top1 = topCount(methods);
+    if (top1 && top1[1] >= 2) {
+      registerMethod = role(
+        top1[0],
+        [where.get(top1[0])],
+        top1[1] >= 5 ? "high" : "medium",
+        `${top1[1]} registrars`,
+      );
+    }
+  }
+  if (registrarSuffix.value === null && conventions?.diRegistration?.pattern) {
+    registrarSuffix.note = `extract-conventions: ${conventions.diRegistration.pattern}`;
+  }
+  const attrs = new Map();
+  const where = new Map();
+  for (const u of usage) {
+    if (!language || languageOf(u.path) !== language) continue;
+    for (const m of u.text.matchAll(INJECT_RE)) {
+      bump(attrs, m[0]);
+      if (!where.has(m[0])) where.set(m[0], []);
+      if (where.get(m[0]).length < 3) where.get(m[0]).push(`${u.path}:${u.line}`);
+    }
+  }
+  const a = topCount(attrs);
+  const injectAttribute =
+    a && a[1] >= 2
+      ? role(a[0], where.get(a[0]), a[1] >= 20 ? "high" : "medium", `${a[1]} uses`)
+      : role(null);
+  return { registrarSuffix, registerMethod, injectAttribute };
+}
+
+const MANIFESTS = new Set([
+  "Package.swift",
+  "build.gradle",
+  "build.gradle.kts",
+  "package.json",
+  "Cargo.toml",
+  "go.mod",
+  "pom.xml",
+]);
+const VALIDATOR_RE =
+  /(^|\/)[^/]*((validate|check|lint|verify)[-_]?modules?|modules?[-_]?(validat|check|lint|verif|structure))[^/]*$/i;
+
+/** One glob covering the largest group of same-named, same-depth paths. */
+function generalize(paths) {
+  const groups = new Map();
+  for (const p of paths) {
+    const parts = p.split("/");
+    const key = `${parts.length}:${parts[parts.length - 1]}`;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(parts);
+  }
+  let best = null;
+  for (const g of groups.values()) if (!best || g.length > best.length) best = g;
+  if (!best) return null;
+  const glob = best[0].map((seg, i) => (best.every((p) => p[i] === seg) ? seg : "*")).join("/");
+  return { glob, count: best.length, sample: best.slice(0, 3).map((p) => p.join("/")) };
+}
+
+function deriveModule(files, commands) {
+  const manifests = files.filter((f) => f.includes("/") && MANIFESTS.has(posix.basename(f)));
+  const g = generalize(manifests);
+  const layout =
+    g && g.count >= 2
+      ? role(g.glob, g.sample, g.count >= 5 ? "high" : "medium", `${g.count} modules`)
+      : role(null);
+  const cmd = commands.find((c) =>
+    VALIDATOR_RE.test(c.cmd.split(/\s+/).find((w) => VALIDATOR_RE.test(w)) || ""),
+  );
+  const file = files.find((f) => VALIDATOR_RE.test(f));
+  const validator = cmd
+    ? role(cmd.cmd, [`${cmd.path}:${cmd.line}`], "medium")
+    : file
+      ? role(file, [file], "low")
+      : role(null);
+  return { layout, validator };
+}
+
+function deriveMock(usage, trackedDirs, generators, language) {
+  const frameworks = new Map();
+  const where = new Map();
+  for (const u of usage) {
+    if (!language || languageOf(u.path) !== language) continue;
+    for (const m of u.text.matchAll(MOCK_RE)) {
+      const name = m[1] || m[2];
+      bump(frameworks, name);
+      if (!where.has(name)) where.set(name, []);
+      if (where.get(name).length < 3) where.get(name).push(`${u.path}:${u.line}`);
+    }
+  }
+  const fw = topCount(frameworks);
+  const fixtureDirs = [...trackedDirs].filter((d) =>
+    /^(mocks?|fixtures?|stubs?|mockdata)$/i.test(posix.basename(d)),
+  );
+  const system = fw
+    ? role(fw[0], where.get(fw[0]), fw[1] >= 10 ? "high" : "medium", `${fw[1]} imports`)
+    : fixtureDirs.length
+      ? role("fixture-tree", fixtureDirs.slice(0, 3), "low")
+      : role(null);
+  const outParents = new Set(generators.map((gen) => posix.dirname(globPrefix(gen.output))));
+  const custom = [...trackedDirs].filter(
+    (d) =>
+      /^Custom(Fixtures|Mocks|Stubs|Sources|Scenarios|Data)$/i.test(posix.basename(d)) ||
+      (/^Custom[A-Z]\w*$/.test(posix.basename(d)) && outParents.has(posix.dirname(d))),
+  );
+  const g = generalize(custom);
+  const customDir = g
+    ? role(g.glob, g.sample, g.count >= 3 ? "medium" : "low", `${g.count} directories`)
+    : role(null);
+  return { system, customDir };
+}
+
+// ---------------------------------------------------------------------------
+// hooks, checks, docs, skills, resource source
+
+function hookEffects(text) {
+  const effects = [];
+  if (/git\s+commit\b[^\n]*--amend/.test(text)) effects.push("amends-commit");
+  if (/git\s+(add|update-index)\b/.test(text)) effects.push("stages-files");
+  if (
+    /\bsed\s+-i\b/.test(text) ||
+    /\b(swiftformat|prettier\s+--write|eslint\s+--fix|black|gofmt\s+-w|ruff\s+format|clang-format\s+-i)\b/.test(
+      text,
+    ) ||
+    /\bswiftlint\s+(--fix|autocorrect)\b|\bktlint\s+(-F|--format)\b/.test(text) ||
+    /(^|[^0-9&>])>{1,2}\s*(?!\/dev\/null|&)[\w.$"'/-]/m.test(text)
+  ) {
+    effects.push("writes-files");
+  }
+  if (/\b(curl|wget)\b|\bgit\s+(push|fetch|pull)\b/.test(text)) effects.push("network");
+  return effects;
+}
+
+function deriveHooks(top, files) {
+  const hooks = [];
+  for (const f of files) {
+    const dir = HOOK_DIRS.find((d) => f.startsWith(d));
+    if (!dir || f.startsWith(".husky/_/")) continue;
+    const name = posix.basename(f).replace(/\.(sh|bash)$/, "");
+    if (!HOOK_NAMES.has(name) || f.slice(dir.length).includes("/")) continue;
+    hooks.push({ name, path: f, dir: dir.replace(/\/$/, "") });
+  }
+  for (const [cfg, name] of [
+    [".pre-commit-config.yaml", "pre-commit-framework"],
+    ["lefthook.yml", "lefthook"],
+  ]) {
+    if (files.includes(cfg)) hooks.push({ name, path: cfg, dir: null });
+  }
+  if (!hooks.length) return [];
+  const setup = gitOut(top, ["grep", "-n", "-z", "-I", "-F", "--max-depth", "3", "core.hooksPath"])
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => l.match(/^([^\0]+)\0(\d+)\0(.*)$/))
+    .filter(Boolean);
+  const configured = gitOut(top, ["config", "--get", "core.hooksPath"]).trim();
+  return hooks.map((h) => {
+    const text = readText(top, h.path) || "";
+    const ev = [h.path];
+    for (const m of setup)
+      if (h.dir && m[3].includes(h.dir) && m[1] !== h.path) ev.push(`${m[1]}:${m[2]}`);
+    if (h.dir && configured.replace(/\/$/, "") === h.dir) ev.push("git:config core.hooksPath");
+    return entry(
+      { name: h.name, path: h.path, sideEffects: hookEffects(text) },
+      ev,
+      ev.length > 1 ? "high" : "medium",
+    );
+  });
+}
+
+function deriveRequiredChecks(top, files, workflows) {
+  const found = new Map();
+  const add = (name, ev) => {
+    const n = unquote(name).trim();
+    if (!n || found.has(n)) return;
+    found.set(n, entry({ name: n }, [ev], "low"));
+  };
+  for (const wf of workflows) {
+    const { lines } = wf;
+    const jobsAt = lines.findIndex((l) => /^jobs:\s*$/.test(l));
+    if (jobsAt < 0) continue;
+    for (let i = jobsAt + 1; i < lines.length; i += 1) {
+      if (!/#.*\brequired\b/i.test(lines[i])) continue;
+      let name = null;
+      for (let j = i + 1; j <= i + 4 && j < lines.length; j += 1) {
+        const m = lines[j].match(/^\s*name:\s*(.+?)\s*$/);
+        if (m) {
+          name = m[1];
+          break;
+        }
+      }
+      if (!name) {
+        for (let j = i; j > jobsAt; j -= 1) {
+          const m = lines[j].match(/^ {2}([A-Za-z0-9_-]+):\s*$/);
+          if (m) {
+            name = m[1];
+            break;
+          }
+        }
+      }
+      if (name) add(name, `${wf.path}:${i + 1}`);
+    }
+  }
+  for (const doc of ["CONTRIBUTING.md", ".github/pull_request_template.md", "CLAUDE.md"]) {
+    if (!files.includes(doc)) continue;
+    (readText(top, doc) || "").split("\n").forEach((line, i) => {
+      if (!/required (status )?checks?/i.test(line)) return;
+      for (const m of line.matchAll(/`([^`]+)`/g)) add(m[1], `${doc}:${i + 1}`);
+    });
+  }
+  return [...found.values()];
+}
+
+/** The in-repo documents the repo's CLAUDE.md files point at, through the shared bounded follower. */
+function deriveDocs(top) {
+  const { files } = followClaudeMdLinks(top, { content: false });
+  const out = new Map();
+  for (const f of files) {
+    if (!out.has(f.path)) out.set(f.path, entry({ path: f.path }, [f.from], "high"));
+  }
+  return [...out.values()].slice(0, MAX_ENTRIES);
+}
+
+function frontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return {};
+  const out = {};
+  const lines = m[1].split("\n");
+  for (let i = 0; i < lines.length; i += 1) {
+    const kv = lines[i].match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!kv) continue;
+    let val = kv[2].trim();
+    if (/^[>|][-+]?$/.test(val)) {
+      const parts = [];
+      while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1]))
+        parts.push(lines[(i += 1)].trim());
+      val = parts.join(" ");
+    }
+    out[kv[1]] = unquote(val);
+  }
+  return out;
+}
+
+function deriveSkills(top) {
+  const dir = join(top, ".claude", "skills");
+  let names;
+  try {
+    names = readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const n of names.sort()) {
+    const rel = `.claude/skills/${n}/SKILL.md`;
+    const text = readText(top, rel);
+    if (text === null) continue;
+    const fm = frontmatter(text);
+    const e = entry(
+      {
+        name: fm.name || n,
+        path: rel,
+        trigger:
+          String(fm["disable-model-invocation"]).toLowerCase() === "true" ? "explicit" : "auto",
+      },
+      [`${rel}:1`],
+      "high",
+    );
+    if (fm.description) e.description = fm.description.slice(0, 300);
+    out.push(e);
+  }
+  return out;
+}
+
+function deriveResourceSource(workflows, history, isBot) {
+  const botNames = new Set(history.filter(isBot).map((c) => c.an));
+  for (const wf of workflows) {
+    if (!workflowBotNames(wf, botNames).size) continue;
+    const i = wf.lines.findIndex((l) => /^\s*repository:\s*[\w.-]+\/[\w.-]+\s*$/.test(l));
+    if (i < 0) continue;
+    const repo = unquote(wf.lines[i].split(":").slice(1).join(":"));
+    return role(
+      { repo, authoring: {} },
+      [`${wf.path}:${i + 1}`],
+      "low",
+      "checkout in a workflow that names a bot",
+    );
+  }
+  return role(null);
+}
+
+// ---------------------------------------------------------------------------
+// entry point
+
+/**
+ * Derive a draft profile. Reads the repo, writes nothing.
+ *
+ * @param {string} repo path inside the repo (a worktree is fine)
+ * @param {{botPattern?: string, historyWindow?: number, conventions?: object|null, now?: Date}} [opts]
+ * @returns {object} a profile that satisfies repo-profile.schema.json
+ */
+export function deriveProfile(repo, opts = {}) {
+  const started = Date.now();
+  const {
+    botPattern,
+    historyWindow = DEFAULT_HISTORY,
+    conventions = null,
+    now = new Date(),
+  } = opts;
+  const repoRoot = mainRepoRoot(repo);
+  const top = gitOut(repo, ["rev-parse", "--show-toplevel"]).trim() || repoRoot;
+  const files = [];
+  const contentFiles = [];
+  for (const rec of gitOut(top, ["ls-files", "-s", "-z"]).split("\0")) {
+    const tab = rec.indexOf("\t");
+    if (tab < 0) continue;
+    const path = rec.slice(tab + 1);
+    files.push(path);
+    // 120000 is a symlink, 160000 a submodule: neither is content to read.
+    if (!/^1[26]0000 /.test(rec)) contentFiles.push(path);
+  }
+  const trackedDirs = new Set();
+  for (const f of files) for (const d of ancestors(f)) trackedDirs.add(d);
+  const history = readHistory(top, historyWindow);
+  const isBot = botMatcher(botPattern);
+  const workflows = readWorkflows(top, files);
+  const commands = workflows.flatMap(runCommands);
+  const head = gitOut(top, ["rev-parse", "--verify", "--quiet", "HEAD"]).trim();
+
+  const language = dominantLanguage(contentFiles);
+  const generators = deriveGenerators(top, contentFiles, trackedDirs, history, commands);
+  const outPrefixes = generators.map((g) => globPrefix(g.output)).filter(Boolean);
+  const genFiles = files.filter(
+    (f) => SOURCE_EXT.test(f) && outPrefixes.some((p) => underPrefix(f, p)),
+  );
+  const candidates = accessorCandidates(top, genFiles);
+  const rootLiterals = Object.values(candidates).flatMap((d) => [...d.keys()].map((n) => `${n}.`));
+  const usage = scanUsage(top, [
+    ...new Set([...rootLiterals, ...INJECT_LITERALS, ...MOCK_LITERALS]),
+  ]);
+  const { build, test, lint } = deriveCommands(top, files, commands);
+  const profile = {
+    schemaVersion: SCHEMA_VERSION,
+    repoRoot,
+    repoHead: /^[0-9a-f]{40}$/.test(head) ? head : null,
+    derivedAt: now.toISOString(),
+    confirmedAt: null,
+    derivation: {
+      botPattern: botPattern || BOT_DEFAULT.source,
+      historyWindow,
+      durationMs: 0,
+      conventions: Boolean(conventions),
+    },
+    repo: deriveBranches(top, workflows),
+    commit: { format: deriveCommitFormat(history, isBot) },
+    build,
+    test,
+    lint,
+    ownedPaths: deriveOwnedPaths(top, history, isBot, trackedDirs, files, workflows),
+    generators,
+    resourceSource: deriveResourceSource(workflows, history, isBot),
+    accessors: deriveAccessors(candidates, usage, outPrefixes, conventions),
+    di: deriveDi(top, contentFiles, usage, conventions, language),
+    module: deriveModule(files, commands),
+    mock: deriveMock(usage, trackedDirs, generators, language),
+    hooks: deriveHooks(top, files),
+    requiredChecks: deriveRequiredChecks(top, files, workflows),
+    docs: { authoritative: deriveDocs(top) },
+    inRepoSkills: deriveSkills(top),
+  };
+  profile.derivation.durationMs = Math.max(0, Date.now() - started);
+  return profile;
+}