catherd-cli 1.0.0 → 1.1.1

package/src/services/global-install.ts

@@ -0,0 +1,99 @@
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { errorMessage } from "../domain/errors.ts";
+import { scrubSecrets } from "../infra/env.ts";
+
+/** How `init` finds and installs the global `catherd` (injectable: tests never reach the registry). */
+export interface GlobalInstallDeps {
+  /**
+   * what the `catherd` in bun's global bin prints for --version; null when there is none or it does not
+   * answer. Never PATH: under `bunx catherd-cli init`, PATH first finds bunx's own transient shim.
+   */
+  globalVersion(): Promise<string | null>;
+  /** what the first `catherd` on PATH outside a bunx transient install prints for --version, or null */
+  pathVersion(): Promise<string | null>;
+  /** `bun add -g catherd-cli@<version>`, with its output */
+  install(version: string): Promise<{ ok: boolean; output: string }>;
+}
+
+export type GlobalInstall =
+  | { state: "current" }
+  | { state: "installed" }
+  /** installed, but the `catherd` first on PATH is another version (or none), so the launcher still runs bunx */
+  | { state: "shadowed"; onPath: string | null }
+  | { state: "failed"; reason: string };
+
+async function run(cmd: string[]): Promise<{ ok: boolean; stdout: string; output: string }> {
+  const p = Bun.spawn(cmd, {
+    env: scrubSecrets(process.env),
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [out, err, code] = await Promise.all([
+    new Response(p.stdout).text(),
+    new Response(p.stderr).text(),
+    p.exited,
+  ]);
+  return { ok: code === 0, stdout: out, output: `${err}${out}` };
+}
+
+/** what `bin --version` prints on stdout (a warning on stderr must not make it look like another version) */
+async function versionOf(bin: string | null): Promise<string | null> {
+  if (!bin) return null;
+  const r = await run([bin, "--version"]).catch(() => null);
+  return r?.ok ? r.stdout.trim() || null : null;
+}
+
+/**
+ * bun's global bin folder: `bun pm bin -g`, else where bun puts it by default. `bun pm bin -g` fails
+ * (Bun 1.4.2) while the global folder exists without a package.json, which is before the first global install.
+ */
+async function globalBin(): Promise<string> {
+  const r = await run([process.execPath, "pm", "bin", "-g"]).catch(() => null);
+  const dir = r?.ok ? r.stdout.trim() : "";
+  if (dir) return dir;
+  return process.env.BUN_INSTALL_BIN || join(process.env.BUN_INSTALL || join(homedir(), ".bun"), "bin");
+}
+
+/** `bunx` runs a package from `<tmp>/bunx-<uid>-<package>@<tag>/node_modules/.bin`, prepended to PATH */
+const isBunxBin = (dir: string) => dir.split(/[\\/]/).some((part) => part.startsWith("bunx-"));
+
+export const realGlobalInstall: GlobalInstallDeps = {
+  async globalVersion() {
+    return versionOf(Bun.which("catherd", { PATH: await globalBin() }));
+  },
+  async pathVersion() {
+    const PATH = (process.env.PATH ?? "")
+      .split(delimiter)
+      .filter((dir) => dir && !isBunxBin(dir))
+      .join(delimiter);
+    return versionOf(Bun.which("catherd", { PATH }));
+  },
+  install: (version) =>
+    run([process.execPath, "add", "-g", `catherd-cli@${version}`]).catch((e: unknown) => ({
+      ok: false,
+      output: errorMessage(e),
+    })),
+};
+
+/**
+ * Spec 1.1 §12: the global CLI at `version`, so the plugin's launcher starts it without a bunx resolve.
+ * `installing` runs before anything is resolved, so the user sees why the next seconds pass.
+ */
+export async function ensureGlobal(
+  version: string,
+  deps: GlobalInstallDeps,
+  installing: () => void,
+): Promise<GlobalInstall> {
+  if ((await deps.globalVersion()) === version) return { state: "current" };
+  installing();
+  // never rejects: a failed install is reported, and init goes on
+  const r = await deps.install(version).catch((e: unknown) => ({ ok: false, output: errorMessage(e) }));
+  if (r.ok) {
+    const onPath = await deps.pathVersion().catch(() => null);
+    return onPath === version ? { state: "installed" } : { state: "shadowed", onPath };
+  }
+  const reason = r.output.split("\n").find((l) => l.trim()) ?? "bun add -g failed";
+  return { state: "failed", reason: reason.trim() };
+}

package/src/services/lane-service.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { relative, sep } from "node:path";
 import { CatherdError } from "../domain/errors.ts";
 import { assertId, ID_PATTERN, parseRung } from "../domain/ids.ts";
-import type { Difficulty, Kind } from "../domain/lane.ts";
+import { assertLaneHeader, type Difficulty, type Kind } from "../domain/lane.ts";
 import type { Role } from "../domain/roles.ts";
 import {
   type ClimbReason,
@@ -14,7 +14,18 @@ import {
 } from "../domain/route.ts";
 import { withFileLock } from "../infra/filelock.ts";
 import { commitExists } from "../infra/git.ts";
+import { laneFile } from "./admission.ts";
 import { budgetOf } from "./budget.ts";
+import {
+  isDocPath,
+  isSourcePath,
+  landedMilestones,
+  fullCommit,
+  milestoneFiles,
+  milestoneStart,
+  reviewerPassed,
+  milestoneVerifier,
+} from "./milestones.ts";
 import type { Deps, Verdict } from "./ports.ts";
 import {
   appendLedger,
@@ -27,6 +38,8 @@ import {
   runFile,
   runPaths,
 } from "./run-store.ts";
+import { writeDigest } from "./protocol.ts";
+import { openQuestions } from "./questions.ts";
 import { type Notes, type NotesPatch, refreshState } from "./state.ts";
 import { appendPrivate } from "../infra/store.ts";
 
@@ -60,7 +73,10 @@ function readLaneFile(run: Run, path: string): { lane: string; text: string } {
     throw new CatherdError("E_LANE_INVALID", `no lane file ${path}`, {
       fix: "write it with write_run_file first",
     });
-  return { lane, text: readFileSync(file, "utf8") };
+  const text = readFileSync(file, "utf8");
+  // spec 1.1 §6: a lane routes only on values the catalog knows
+  assertLaneHeader(text, `lanes/${lane}.md`);
+  return { lane, text };
 }
 
 /** Spec §5.4 through the routing port; a lane's route is recorded in routes.jsonl. */
@@ -105,6 +121,40 @@ export async function route(
   };
 }
 
+/** Evidence that the lane's own ownership is the problem: a design question, never a capability one. */
+const OWNERSHIP = /outside (the )?lane('s)? ownership|owned by/i;
+
+const CLIMB_DESIGN_FIX = "send it to the architect (ask/architect delta), not up the ladder";
+
+/**
+ * Spec 1.1 §9: a climb is for capability. Evidence that points at the plan (a contradiction, a file the
+ * lane does not own, a cross-lane interface) goes to the architect: ownership evidence on a `blocked`
+ * climb is refused outright; with Jev on, its `finding` answer `design` refuses any climb with evidence.
+ * A climb the environment caused (`env`) is never a design question.
+ */
+async function refuseDesign(
+  deps: Deps,
+  run: Run,
+  i: { lane: string; reason: ClimbReason; evidence?: string; env?: boolean },
+): Promise<void> {
+  if (!i.evidence || i.env) return;
+  if (i.reason === "blocked" && OWNERSHIP.test(i.evidence))
+    throw new CatherdError(
+      "E_CLIMB_DESIGN",
+      `climb ${i.lane}: the evidence is about lane ownership, which a higher rung cannot fix`,
+      { fix: CLIMB_DESIGN_FIX },
+    );
+  const use = deps.profiles.forRepo(run.meta.repo).jev.use;
+  if (use === "off") return;
+  const file = laneFile(run, i.lane);
+  if (!existsSync(file)) return;
+  const v = await deps.routing.finding(run.dir, readFileSync(file, "utf8"), i.evidence, use);
+  if (v.value === "design")
+    throw new CatherdError("E_CLIMB_DESIGN", `climb ${i.lane}: Jev calls the evidence a design finding`, {
+      fix: CLIMB_DESIGN_FIX,
+    });
+}
+
 /** Spec §4.5: one rung up the lane's ladder, on a fresh thread; the reason goes to routes.jsonl. */
 export async function climb(
   deps: Deps,
@@ -119,12 +169,16 @@ export async function climb(
 }> {
   const run = findRun(i.run);
   assertId("lane", i.lane);
+  const unrouted = () =>
+    new CatherdError("E_LANE_INVALID", `lane ${i.lane} was never routed`, {
+      fix: `route(run, "lanes/${i.lane}.md") first`,
+    });
+  // an unrouted lane is refused before Jev is asked about its evidence (no call, no jev.jsonl row)
+  if (!currentRoute(readRoutes(run), i.lane)) throw unrouted();
+  await refuseDesign(deps, run, i);
   const { cur, next } = await withFileLock(runPaths(run.dir).routes, () => {
     const cur = currentRoute(readRoutes(run), i.lane);
-    if (!cur)
-      throw new CatherdError("E_LANE_INVALID", `lane ${i.lane} was never routed`, {
-        fix: `route(run, "lanes/${i.lane}.md") first`,
-      });
+    if (!cur) throw unrouted();
     const next = nextRung(cur.ladder, cur.rung);
     appendRoute(run, {
       ...cur,
@@ -160,6 +214,81 @@ export async function climb(
 
 const cell = (s: string) => s.replace(/[|\n]/g, "/").replace(/\s+/g, " ").trim();
 
+export const LAND_SKIPS = ["docs-only", "no-code"] as const;
+export type LandSkip = (typeof LAND_SKIPS)[number];
+
+/**
+ * Spec 1.1 §6: a milestone lands only with a reviewer record and a verifier verdict since its lanes
+ * started, or with a `skip` the commit range bears out. Throws E_LAND_GATE naming what is missing.
+ */
+async function gate(run: Run, m: string, commit: string, skip: LandSkip | undefined): Promise<void> {
+  // spec 1.1 §8: a parked milestone waits on the owner, whatever else it has
+  const question = openQuestions(run).find((q) => q.milestone === m);
+  if (question)
+    throw new CatherdError(
+      "E_LAND_GATE",
+      `land ${m}: it is parked, waiting on the owner: ${question.question}`,
+      {
+        fix: `when the owner answers, call answer(run, "${m}", <their answer>), finish ${m}, then land it`,
+      },
+    );
+  if (skip) {
+    // the range a skip is judged on must be the milestone as it stands: an older commit would leave
+    // later source commits unreviewed
+    const [landed, head] = await Promise.all([fullCommit(run, commit), fullCommit(run, "HEAD")]);
+    if (landed !== head)
+      throw new CatherdError(
+        "E_LAND_GATE",
+        `land ${m}: skip "${skip}" refused: ${commit} is not HEAD (${head.slice(0, 7)}): commits after it would land unreviewed`,
+        {
+          fix: `land ${m} with HEAD (${head.slice(0, 7)}) once it holds the milestone; if source changed, run reviewer-${m} and the verifier and land without skip`,
+        },
+      );
+    const files = await milestoneFiles(run, commit);
+    // an empty range lands nothing: the milestone's work is most likely not committed yet
+    if (files.length === 0) {
+      const last = landedMilestones(run).at(-1);
+      throw new CatherdError(
+        "E_LAND_GATE",
+        `land ${m}: skip "${skip}" refused: ${last ? `the commit range changed nothing since ${last} landed` : `${commit} changed nothing`}`,
+        { fix: `commit the milestone first, then land ${m} with that commit` },
+      );
+    }
+    const against =
+      skip === "docs-only" ? files.filter((f) => !isDocPath(f)) : files.filter((f) => isSourcePath(f));
+    if (against.length === 0) return;
+    const shown = `${against.slice(0, 5).join(", ")}${against.length > 5 ? `, and ${against.length - 5} more` : ""}`;
+    throw new CatherdError(
+      "E_LAND_GATE",
+      `land ${m}: skip "${skip}" refused: ${skip === "docs-only" ? "files outside the docs changed" : "source files changed"}: ${shown}`,
+      { fix: `run the reviewer (reviewer-${m}) and the verifier on ${m}, then land it without skip` },
+    );
+  }
+  const start = milestoneStart(run, m);
+  // the latest verifier attempt, passed or not: a FAIL after a PASS undoes it
+  const verdict = milestoneVerifier(run, m, start);
+  const missing = [
+    ...(reviewerPassed(run, m, start)
+      ? []
+      : [
+          `a reviewer record (a dispatch named reviewer-${m}, or record_agent_run with role reviewer and that name, status ok)`,
+        ]),
+    ...(verdict?.passed
+      ? []
+      : [
+          `a verifier verdict (record_agent_run with role verifier and a name holding ${m}, status ok; a headless verifier's reply opening VERDICT: PASS)${verdict ? `: the latest, ${verdict.name}${verdict.headless ? " (headless)" : ""}, is ${verdict.verdict}` : ""}`,
+        ]),
+  ];
+  if (missing.length)
+    throw new CatherdError(
+      "E_LAND_GATE",
+      `land ${m}: missing ${missing.join(" and ")}, since its lanes started`,
+      {
+        fix: `run reviewer-${m} (a dispatch, or a Claude subagent recorded with record_agent_run(name: "reviewer-${m}")) and the verifier on ${m}, recording it with record_agent_run(name: "verifier-${m}") (a FAIL with status "failed"), then land again; a docs-only milestone passes skip: "docs-only"`,
+      },
+    );
+}
+
 /**
  * Spec §4.7: the full five-column ledger row, with the minutes since the previous landing (or the
  * run's start), and `learned` appended to the repo's knowledge.md.
@@ -174,14 +303,18 @@ export async function land(
     evidence: string;
     next: string;
     learned?: string;
+    skip?: LandSkip;
   },
-): Promise<{ ledger: string; minutes: number; hints?: string[] }> {
+): Promise<{ ledger: string; minutes: number; digest: string; hints?: string[] }> {
   const run = findRun(i.run);
+  // the digest is named after the milestone: an id, checked before anything is written
+  assertId("milestone", i.milestone);
   // commitExists throws E_IO_UNEXPECTED on a timeout, which reaches the caller as is
   if (!/^[0-9a-f]{7,40}$/.test(i.commit) || !(await commitExists(run.meta.repo, i.commit)))
     throw new CatherdError("E_RUN_COMMIT", `no commit ${i.commit} in ${run.meta.repo}`, {
       fix: "commit the milestone first, then pass its hash",
     });
+  await gate(run, i.milestone, i.commit, i.skip);
   const now = new Date(deps.now());
   let row = "";
   let minutes = 0;
@@ -221,7 +354,16 @@ export async function land(
       `- ${now.toISOString().slice(0, 10)} ${run.meta.title} ${i.milestone}: ${cell(i.learned)}\n`,
     );
   }
-  return { ledger: row, minutes, ...withHints(hints) };
+  // spec 1.1 §10: the milestone's digest, which the milestone push links
+  const digest = writeDigest(run, {
+    milestone: i.milestone,
+    what: i.what,
+    commit: i.commit,
+    evidence: i.evidence,
+    minutes,
+    at: now.toISOString(),
+  });
+  return { ledger: row, minutes, digest, ...withHints(hints) };
 }
 
 /** Jev's `finding` or `same-defect` answer, through the routing port. */

package/src/services/milestones.ts

@@ -0,0 +1,208 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CatherdError } from "../domain/errors.ts";
+import type { RunRecord } from "../domain/record.ts";
+import { git } from "../infra/git.ts";
+import { nonBlankLines } from "../infra/store.ts";
+import { listDispatches } from "./dispatches.ts";
+import { readAgentRuns, readRecords, readRoutes, type Run, runPaths } from "./run-store.ts";
+
+// Spec 1.1 §6 and §10: what a milestone has been through, read from the run's own records. `land` gates on
+// it, and the protocol's next step is derived from it.
+
+/** Where a milestone name may end inside a longer name: the end, '-', '.', '_' or whitespace (M1-fix, M1.2). */
+const MILESTONE_END = String.raw`(?=$|[-._\s])`;
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** `name` names milestone `m` as a word: verifier-M1 and M1-verifier do; verifier-M10 and verifier-M1fix do not. */
+export const namesMilestone = (name: string, m: string): boolean =>
+  new RegExp(`(^|[^A-Za-z0-9])${escapeRe(m)}${MILESTONE_END}`).test(name);
+
+/** `name` is milestone `m`'s reviewer: reviewer-<m>, the milestone ending as in namesMilestone (reviewer-M10 is not M1's). */
+export const reviewsMilestone = (name: string, m: string): boolean =>
+  new RegExp(`^reviewer-${escapeRe(m)}${MILESTONE_END}`).test(name);
+
+const inMilestone = (lane: string | null | undefined, m: string): boolean =>
+  typeof lane === "string" && lane.startsWith(`${m}.`);
+
+/**
+ * When the milestone's lanes started: its earliest route row or lane dispatch; null when neither exists
+ * (a milestone with no lanes, such as a docs pass), and every record of the run then counts.
+ */
+export function milestoneStart(run: Run, m: string): string | null {
+  const times = [
+    ...readRoutes(run)
+      .filter((r) => inMilestone(r.lane, m))
+      .map((r) => r.at),
+    ...listDispatches(run)
+      .filter((d) => inMilestone(d.admit.lane, m))
+      .map((d) => d.admit.admittedAt),
+  ].filter((t) => !Number.isNaN(Date.parse(t)));
+  return times.sort()[0] ?? null;
+}
+
+const since = (at: string, start: string | null) => start === null || Date.parse(at) >= Date.parse(start);
+
+/** The milestone's reviewer: its dispatch record, or null for a native Claude subagent (record_agent_run). */
+export interface MilestoneReviewer {
+  name: string;
+  at: string;
+  record: RunRecord | null;
+}
+
+/**
+ * The milestone's latest passing reviewer since its lanes started: a dispatch named reviewer-<m>…, status
+ * ok; or a record_agent_run row with role reviewer and the same name, status ok. Null when there is none.
+ */
+export function milestoneReviewer(
+  run: Run,
+  m: string,
+  start = milestoneStart(run, m),
+): MilestoneReviewer | null {
+  const found: MilestoneReviewer[] = [
+    ...readRecords(run)
+      .records.filter((r) => reviewsMilestone(r.name, m) && r.status === "ok" && since(r.endedAt, start))
+      .map((r) => ({ name: r.name, at: r.endedAt, record: r })),
+    ...readAgentRuns(run)
+      .filter(
+        (a) =>
+          a.role === "reviewer" && reviewsMilestone(a.name, m) && a.status === "ok" && since(a.at, start),
+      )
+      .map((a) => ({ name: a.name, at: a.at, record: null })),
+  ];
+  return found.sort((a, b) => Date.parse(a.at) - Date.parse(b.at)).at(-1) ?? null;
+}
+
+/** A reviewer record for the milestone since its lanes started (see milestoneReviewer). */
+export const reviewerPassed = (run: Run, m: string, start = milestoneStart(run, m)): boolean =>
+  milestoneReviewer(run, m, start) !== null;
+
+/** The verifier's contract puts `VERDICT: PASS` or `VERDICT: FAIL` on the reply's first line (role-prompts.ts). */
+const VERDICT_PASS = /^VERDICT: PASS\b/;
+
+/** A headless verifier's reply: its first non-blank line, trimmed; null when there is no reply to read. */
+export function replyVerdict(run: Run, r: RunRecord): string | null {
+  const file = join(run.dir, r.replyPath);
+  if (!r.replyPath || !existsSync(file)) return null;
+  return (
+    readFileSync(file, "utf8")
+      .split("\n")
+      .map((l) => l.trim())
+      .find(Boolean) ?? null
+  );
+}
+
+/** A headless verifier's reply opens with VERDICT: PASS: its first non-blank line; no reply is no verdict. */
+export function replyPasses(run: Run, r: RunRecord): boolean {
+  const first = replyVerdict(run, r);
+  return first !== null && VERDICT_PASS.test(first);
+}
+
+/** The milestone's latest verifier attempt: a native Claude subagent or a headless dispatch, passed or not. */
+export interface MilestoneVerifier {
+  name: string;
+  at: string;
+  headless: boolean;
+  passed: boolean;
+  /** what the attempt said: a native row's status, or a headless reply's first non-blank line ("no reply") */
+  verdict: string;
+}
+
+/**
+ * The milestone's latest verifier attempt since its lanes started, whatever it said: a record_agent_run row
+ * with role verifier whose name names the milestone (the skill records a FAIL as failed), passing when its
+ * status is ok; or a headless verifier's dispatch record of the same shape, passing when it exited ok and its
+ * reply opens VERDICT: PASS (status ok means only the CLI exited). A later FAIL undoes an earlier PASS. Null
+ * when there is none.
+ */
+export function milestoneVerifier(
+  run: Run,
+  m: string,
+  start = milestoneStart(run, m),
+): MilestoneVerifier | null {
+  const found: MilestoneVerifier[] = [
+    ...readAgentRuns(run)
+      .filter((a) => a.role === "verifier" && namesMilestone(a.name, m) && since(a.at, start))
+      .map((a) => ({
+        name: a.name,
+        at: a.at,
+        headless: false,
+        passed: a.status === "ok",
+        verdict: a.status,
+      })),
+    ...readRecords(run)
+      .records.filter((r) => r.role === "verifier" && namesMilestone(r.name, m) && since(r.endedAt, start))
+      .map((r) => {
+        const first = replyVerdict(run, r);
+        const passed = r.status === "ok" && first !== null && VERDICT_PASS.test(first);
+        const said = first === null ? "no reply" : first.length > 80 ? `${first.slice(0, 80)}…` : first;
+        return {
+          name: r.name,
+          at: r.endedAt,
+          headless: true,
+          passed,
+          verdict: r.status === "ok" ? said : `${r.status}, ${said}`,
+        };
+      }),
+  ];
+  // a stable sort: attempts at the same instant keep their file order, the later row winning
+  return found.sort((a, b) => Date.parse(a.at) - Date.parse(b.at)).at(-1) ?? null;
+}
+
+/** The milestone's latest verifier attempt since its lanes started passed (see milestoneVerifier). */
+export const verifierPassed = (run: Run, m: string, start = milestoneStart(run, m)): boolean =>
+  milestoneVerifier(run, m, start)?.passed === true;
+
+/** The commits of the landed milestones, oldest first, from the ledger. */
+export function landedCommits(run: Run): string[] {
+  return nonBlankLines(runPaths(run.dir).ledger)
+    .slice(1)
+    .map((row) => row.split(" | ")[2]?.trim() ?? "")
+    .filter((c) => /^[0-9a-f]{7,40}$/.test(c));
+}
+
+/** The milestones the ledger holds, in landing order. */
+export function landedMilestones(run: Run): string[] {
+  return nonBlankLines(runPaths(run.dir).ledger)
+    .slice(1)
+    .map((row) => row.split(" | ")[0]?.trim() ?? "")
+    .filter(Boolean);
+}
+
+/**
+ * The files the milestone's commit range changed: from the previous landed commit (else the commit's own
+ * parent) to `commit`. Throws E_IO_UNEXPECTED when git cannot say.
+ */
+export async function milestoneFiles(run: Run, commit: string): Promise<string[]> {
+  const base = landedCommits(run).at(-1);
+  const repo = run.meta.repo;
+  const r = base
+    ? await git(repo, ["diff", "--name-only", base, commit])
+    : await git(repo, ["show", "--name-only", "--format=", "--first-parent", commit]);
+  if (r.kind !== "ok")
+    throw new CatherdError("E_IO_UNEXPECTED", `git could not list the files ${commit} changed`, {
+      fix: `check that git works in ${repo}`,
+    });
+  return r.out.split("\n").filter(Boolean);
+}
+
+/** `rev`'s full commit hash in the run's repo. Throws E_IO_UNEXPECTED when git cannot say. */
+export async function fullCommit(run: Run, rev: string): Promise<string> {
+  const r = await git(run.meta.repo, ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`]);
+  const sha = r.kind === "ok" ? r.out.trim() : "";
+  if (!sha)
+    throw new CatherdError("E_IO_UNEXPECTED", `git could not resolve ${rev} in ${run.meta.repo}`, {
+      fix: `check that git works in ${run.meta.repo}`,
+    });
+  return sha;
+}
+
+/** the repo's own docs/ folder, or a doc extension anywhere: app/docs/page.tsx is code */
+const DOC = /^docs\/|\.(md|mdx|markdown|txt|rst|adoc)$/i;
+/** .txt files that configure a build or pin dependencies: not docs */
+const TXT_MANIFEST = /(^|\/)(requirements[^/]*|constraints[^/]*|CMakeLists)\.txt$/i;
+const SOURCE =
+  /\.(ts|tsx|js|jsx|mjs|cjs|go|py|rs|java|kt|kts|swift|rb|php|c|h|cc|cpp|hpp|cs|m|scala|sh|bash|zsh|sql|vue|svelte|css|scss|sass|less|html|dart|ex|exs|erl|zig|lua)$/i;
+
+export const isDocPath = (p: string): boolean => DOC.test(p) && !TXT_MANIFEST.test(p);
+export const isSourcePath = (p: string): boolean => SOURCE.test(p) && !isDocPath(p);