@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.2

package/dist/core/provenance/gitq/moves.js

@@ -0,0 +1,182 @@
+/**
+ * The subsystem surface's git questions, beside the provenance ones
+ * (`../git.ts`) whose timeout and capped stdout reader they share. A package
+ * of their own because `git.ts` sits against the 300-line limit and these
+ * three are one subject: what a `subsystem move` must know before renaming
+ * (`gitDirtyPaths`), what `subsystem history` asks after (`gitRenameHops`),
+ * and the ONE write the roadmap blesses (`gitStageRenames` — "move stages
+ * renames without committing"). The doctrine is unchanged: every way git can
+ * decline reads as "git will not say", never as an error a caller must
+ * handle.
+ */
+import { spawn } from "node:child_process";
+import { collectStdout, GIT_TIMEOUT_MS } from "../git.js";
+/**
+ * Which of these repo-relative paths carry UNCOMMITTED work — anything
+ * `git status --porcelain` reports beneath them, untracked files included: an
+ * untracked file is exactly a change no commit records. Null for every way
+ * git declines (not a repository, not installed, a timeout, a non-zero exit),
+ * and the one caller — `subsystem move`'s only refusal — treats null as
+ * "proceed": a refusal needs positive evidence, and a fleet that does not use
+ * git must not be refused a move over it.
+ *
+ * `-z` for the same reason `gitTrackedFiles` uses it: line output QUOTES
+ * paths with spaces or non-ASCII bytes. A rename entry (`R ` when something
+ * is already staged) carries a second NUL-separated path; both belong in the
+ * answer.
+ */
+export async function gitDirtyPaths(repoDir, rels) {
+    if (rels.length === 0)
+        return [];
+    return new Promise((done) => {
+        const child = spawn("git", ["status", "--porcelain", "-z", "--", ...rels], {
+            cwd: repoDir,
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: GIT_TIMEOUT_MS,
+        });
+        const out = collectStdout(child);
+        child.on("error", () => done(null));
+        child.on("close", (code) => {
+            if (code !== 0 || out.overflowed()) {
+                done(null);
+                return;
+            }
+            const tokens = out.text().split("\0").filter((t) => t !== "");
+            const paths = [];
+            for (let i = 0; i < tokens.length; i += 1) {
+                const entry = tokens[i];
+                // "XY <path>" — two status letters and a space. A rename/copy entry's
+                // ORIGINAL path follows as its own NUL token; take it too.
+                paths.push(entry.slice(3));
+                if (entry.startsWith("R") || entry.startsWith("C")) {
+                    i += 1;
+                    if (tokens[i] !== undefined)
+                        paths.push(tokens[i]);
+                }
+            }
+            done(paths);
+        });
+    });
+}
+/**
+ * How this file moved over time, OLDEST hop first — or null when git will not
+ * say. The question follows one FILE deliberately: `git log --follow` is
+ * defined for a single file and prints NOTHING for a directory path, so
+ * `subsystem history` follows a representative file inside the directory it
+ * is asked about (a service's spec.md, a subsystem's marker) and reads each
+ * hop's directories off the file's own rename record. An empty array is git
+ * ANSWERING "never renamed"; null is git declining — the caller renders the
+ * two differently and exits 0 for both, per the doctrine above.
+ *
+ * Output shape under `-z --format=%H`: `<hash>\0\nR<score>\0<old>\0<new>\0…`,
+ * newest commit first — the token walk below is anchored on the two shapes a
+ * token can have (a 40-hex hash, an R-status) so an unexpected shape yields
+ * fewer hops, never a wrong pairing.
+ */
+export async function gitRenameHops(repoDir, rel) {
+    return new Promise((done) => {
+        const child = spawn("git", ["log", "--follow", "--diff-filter=R", "--name-status", "-z", "--format=%H", "--", rel], { cwd: repoDir, stdio: ["ignore", "pipe", "ignore"], timeout: GIT_TIMEOUT_MS });
+        const out = collectStdout(child);
+        child.on("error", () => done(null));
+        child.on("close", (code) => {
+            if (code !== 0 || out.overflowed()) {
+                done(null);
+                return;
+            }
+            const tokens = out.text().split("\0").map((t) => (t.startsWith("\n") ? t.slice(1) : t));
+            const hops = [];
+            let commit = "";
+            for (let i = 0; i < tokens.length; i += 1) {
+                const token = tokens[i];
+                if (/^[0-9a-f]{40}$/.test(token))
+                    commit = token;
+                else if (/^R\d*$/.test(token) && tokens[i + 1] !== undefined && tokens[i + 2] !== undefined) {
+                    hops.push({ commit, from: tokens[i + 1], to: tokens[i + 2] });
+                    i += 2;
+                }
+            }
+            done(hops.reverse());
+        });
+    });
+}
+/**
+ * Was the rename record that produced a hop into `dest` at `commit` a GUESS?
+ * `git log --follow` pairs old and new paths by CONTENT similarity, and two
+ * identical files moved (or one moved while its twin is created or deleted)
+ * in the same commit give it a coin to flip — subsystem markers are routinely
+ * byte-identical (often empty), so a multi-directory move can report a hop
+ * from a directory the followed file never occupied. The cross-check asks the
+ * commit itself: if two or more of its diff entries carry the same blob as
+ * the one `dest` received, the pairing chose between equals and the hop is
+ * not evidence. `false` = unambiguous; `true` = a guess; null = git will not
+ * say — and the caller must treat BOTH non-false answers as "will not say",
+ * because repeating a maybe-phantom hop is worse than answering nothing.
+ */
+export async function gitRenamePairingAmbiguous(repoDir, commit, dest) {
+    return new Promise((done) => {
+        const child = spawn("git", ["diff-tree", "-r", "-M", "-z", commit], {
+            cwd: repoDir,
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: GIT_TIMEOUT_MS,
+        });
+        const out = collectStdout(child);
+        child.on("error", () => done(null));
+        child.on("close", (code) => {
+            if (code !== 0 || out.overflowed()) {
+                done(null);
+                return;
+            }
+            // `-z` raw form: `:<mode> <mode> <sha> <sha> <status>` NUL, then one
+            // path token — two for a rename/copy. The leading token is the commit.
+            const tokens = out.text().split("\0").filter((t) => t !== "");
+            const entries = [];
+            for (let i = 0; i < tokens.length; i += 1) {
+                const token = tokens[i];
+                if (!token.startsWith(":"))
+                    continue;
+                const fields = token.slice(1).split(" ");
+                const status = fields[4] ?? "";
+                const paths = status.startsWith("R") || status.startsWith("C") ? [tokens[i + 1], tokens[i + 2]] : [tokens[i + 1]];
+                entries.push({
+                    srcSha: fields[2] ?? "",
+                    dstSha: fields[3] ?? "",
+                    status,
+                    paths: paths.filter((p) => p !== undefined),
+                });
+                i += paths.length;
+            }
+            const own = entries.find((e) => e.status.startsWith("R") && e.paths[1] === dest);
+            if (own === undefined) {
+                // The hop's own rename is not in the commit's record — an answer this
+                // check cannot ground is an answer git will not give.
+                done(null);
+                return;
+            }
+            const twins = entries.filter((e) => e.srcSha === own.dstSha || e.dstSha === own.dstSha);
+            done(twins.length > 1);
+        });
+    });
+}
+/**
+ * Best-effort `git add -A` over these repo-relative paths — the ONE write
+ * (module banner): after a `subsystem move` lands its renames, staging the
+ * delete-side and add-side together is what lets git record the pair as a
+ * rename, which is what keeps `subsystem history` answerable after the user
+ * commits. Failure-silent in every direction: a fleet without git, an index
+ * lock, a timeout — the move already succeeded, and nothing here may turn it
+ * into an error.
+ */
+export async function gitStageRenames(repoDir, rels) {
+    if (rels.length === 0)
+        return;
+    return new Promise((done) => {
+        const child = spawn("git", ["add", "-A", "--", ...rels], {
+            cwd: repoDir,
+            stdio: ["ignore", "ignore", "ignore"],
+            timeout: GIT_TIMEOUT_MS,
+        });
+        child.on("error", () => done());
+        child.on("close", () => done());
+    });
+}
+//# sourceMappingURL=moves.js.map

package/dist/core/provenance/gitq/moves.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moves.js","sourceRoot":"","sources":["../../../../src/core/provenance/gitq/moves.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The subsystem surface's git questions, beside the provenance ones\n * (`../git.ts`) whose timeout and capped stdout reader they share. A package\n * of their own because `git.ts` sits against the 300-line limit and these\n * three are one subject: what a `subsystem move` must know before renaming\n * (`gitDirtyPaths`), what `subsystem history` asks after (`gitRenameHops`),\n * and the ONE write the roadmap blesses (`gitStageRenames` — \"move stages\n * renames without committing\"). The doctrine is unchanged: every way git can\n * decline reads as \"git will not say\", never as an error a caller must\n * handle.\n */\nimport { spawn } from \"node:child_process\";\nimport { collectStdout, GIT_TIMEOUT_MS } from \"../git.js\";\n\n/**\n * Which of these repo-relative paths carry UNCOMMITTED work — anything\n * `git status --porcelain` reports beneath them, untracked files included: an\n * untracked file is exactly a change no commit records. Null for every way\n * git declines (not a repository, not installed, a timeout, a non-zero exit),\n * and the one caller — `subsystem move`'s only refusal — treats null as\n * \"proceed\": a refusal needs positive evidence, and a fleet that does not use\n * git must not be refused a move over it.\n *\n * `-z` for the same reason `gitTrackedFiles` uses it: line output QUOTES\n * paths with spaces or non-ASCII bytes. A rename entry (`R ` when something\n * is already staged) carries a second NUL-separated path; both belong in the\n * answer.\n */\nexport async function gitDirtyPaths(repoDir: string, rels: string[]): Promise<string[] | null> {\n  if (rels.length === 0) return [];\n  return new Promise<string[] | null>((done) => {\n    const child = spawn(\"git\", [\"status\", \"--porcelain\", \"-z\", \"--\", ...rels], {\n      cwd: repoDir,\n      stdio: [\"ignore\", \"pipe\", \"ignore\"],\n      timeout: GIT_TIMEOUT_MS,\n    });\n    const out = collectStdout(child);\n    child.on(\"error\", () => done(null));\n    child.on(\"close\", (code) => {\n      if (code !== 0 || out.overflowed()) {\n        done(null);\n        return;\n      }\n      const tokens = out.text().split(\"\\0\").filter((t) => t !== \"\");\n      const paths: string[] = [];\n      for (let i = 0; i < tokens.length; i += 1) {\n        const entry = tokens[i]!;\n        // \"XY <path>\" — two status letters and a space. A rename/copy entry's\n        // ORIGINAL path follows as its own NUL token; take it too.\n        paths.push(entry.slice(3));\n        if (entry.startsWith(\"R\") || entry.startsWith(\"C\")) {\n          i += 1;\n          if (tokens[i] !== undefined) paths.push(tokens[i]!);\n        }\n      }\n      done(paths);\n    });\n  });\n}\n\n/** One hop of a path's rename history: the commit, and the path either side of it. */\nexport interface RenameHop {\n  commit: string;\n  from: string;\n  to: string;\n}\n\n/**\n * How this file moved over time, OLDEST hop first — or null when git will not\n * say. The question follows one FILE deliberately: `git log --follow` is\n * defined for a single file and prints NOTHING for a directory path, so\n * `subsystem history` follows a representative file inside the directory it\n * is asked about (a service's spec.md, a subsystem's marker) and reads each\n * hop's directories off the file's own rename record. An empty array is git\n * ANSWERING \"never renamed\"; null is git declining — the caller renders the\n * two differently and exits 0 for both, per the doctrine above.\n *\n * Output shape under `-z --format=%H`: `<hash>\\0\\nR<score>\\0<old>\\0<new>\\0…`,\n * newest commit first — the token walk below is anchored on the two shapes a\n * token can have (a 40-hex hash, an R-status) so an unexpected shape yields\n * fewer hops, never a wrong pairing.\n */\nexport async function gitRenameHops(repoDir: string, rel: string): Promise<RenameHop[] | null> {\n  return new Promise<RenameHop[] | null>((done) => {\n    const child = spawn(\n      \"git\",\n      [\"log\", \"--follow\", \"--diff-filter=R\", \"--name-status\", \"-z\", \"--format=%H\", \"--\", rel],\n      { cwd: repoDir, stdio: [\"ignore\", \"pipe\", \"ignore\"], timeout: GIT_TIMEOUT_MS },\n    );\n    const out = collectStdout(child);\n    child.on(\"error\", () => done(null));\n    child.on(\"close\", (code) => {\n      if (code !== 0 || out.overflowed()) {\n        done(null);\n        return;\n      }\n      const tokens = out.text().split(\"\\0\").map((t) => (t.startsWith(\"\\n\") ? t.slice(1) : t));\n      const hops: RenameHop[] = [];\n      let commit = \"\";\n      for (let i = 0; i < tokens.length; i += 1) {\n        const token = tokens[i]!;\n        if (/^[0-9a-f]{40}$/.test(token)) commit = token;\n        else if (/^R\\d*$/.test(token) && tokens[i + 1] !== undefined && tokens[i + 2] !== undefined) {\n          hops.push({ commit, from: tokens[i + 1]!, to: tokens[i + 2]! });\n          i += 2;\n        }\n      }\n      done(hops.reverse());\n    });\n  });\n}\n\n/**\n * Was the rename record that produced a hop into `dest` at `commit` a GUESS?\n * `git log --follow` pairs old and new paths by CONTENT similarity, and two\n * identical files moved (or one moved while its twin is created or deleted)\n * in the same commit give it a coin to flip — subsystem markers are routinely\n * byte-identical (often empty), so a multi-directory move can report a hop\n * from a directory the followed file never occupied. The cross-check asks the\n * commit itself: if two or more of its diff entries carry the same blob as\n * the one `dest` received, the pairing chose between equals and the hop is\n * not evidence. `false` = unambiguous; `true` = a guess; null = git will not\n * say — and the caller must treat BOTH non-false answers as \"will not say\",\n * because repeating a maybe-phantom hop is worse than answering nothing.\n */\nexport async function gitRenamePairingAmbiguous(\n  repoDir: string,\n  commit: string,\n  dest: string,\n): Promise<boolean | null> {\n  return new Promise<boolean | null>((done) => {\n    const child = spawn(\"git\", [\"diff-tree\", \"-r\", \"-M\", \"-z\", commit], {\n      cwd: repoDir,\n      stdio: [\"ignore\", \"pipe\", \"ignore\"],\n      timeout: GIT_TIMEOUT_MS,\n    });\n    const out = collectStdout(child);\n    child.on(\"error\", () => done(null));\n    child.on(\"close\", (code) => {\n      if (code !== 0 || out.overflowed()) {\n        done(null);\n        return;\n      }\n      // `-z` raw form: `:<mode> <mode> <sha> <sha> <status>` NUL, then one\n      // path token — two for a rename/copy. The leading token is the commit.\n      const tokens = out.text().split(\"\\0\").filter((t) => t !== \"\");\n      const entries: { srcSha: string; dstSha: string; status: string; paths: string[] }[] = [];\n      for (let i = 0; i < tokens.length; i += 1) {\n        const token = tokens[i]!;\n        if (!token.startsWith(\":\")) continue;\n        const fields = token.slice(1).split(\" \");\n        const status = fields[4] ?? \"\";\n        const paths = status.startsWith(\"R\") || status.startsWith(\"C\") ? [tokens[i + 1], tokens[i + 2]] : [tokens[i + 1]];\n        entries.push({\n          srcSha: fields[2] ?? \"\",\n          dstSha: fields[3] ?? \"\",\n          status,\n          paths: paths.filter((p): p is string => p !== undefined),\n        });\n        i += paths.length;\n      }\n      const own = entries.find((e) => e.status.startsWith(\"R\") && e.paths[1] === dest);\n      if (own === undefined) {\n        // The hop's own rename is not in the commit's record — an answer this\n        // check cannot ground is an answer git will not give.\n        done(null);\n        return;\n      }\n      const twins = entries.filter((e) => e.srcSha === own.dstSha || e.dstSha === own.dstSha);\n      done(twins.length > 1);\n    });\n  });\n}\n\n/**\n * Best-effort `git add -A` over these repo-relative paths — the ONE write\n * (module banner): after a `subsystem move` lands its renames, staging the\n * delete-side and add-side together is what lets git record the pair as a\n * rename, which is what keeps `subsystem history` answerable after the user\n * commits. Failure-silent in every direction: a fleet without git, an index\n * lock, a timeout — the move already succeeded, and nothing here may turn it\n * into an error.\n */\nexport async function gitStageRenames(repoDir: string, rels: string[]): Promise<void> {\n  if (rels.length === 0) return;\n  return new Promise<void>((done) => {\n    const child = spawn(\"git\", [\"add\", \"-A\", \"--\", ...rels], {\n      cwd: repoDir,\n      stdio: [\"ignore\", \"ignore\", \"ignore\"],\n      timeout: GIT_TIMEOUT_MS,\n    });\n    child.on(\"error\", () => done());\n    child.on(\"close\", () => done());\n  });\n}\n"]}

package/dist/core/provenance/gitq/vouched-ancestor.js

@@ -0,0 +1,179 @@
+/**
+ * Doc-body ancestry in the DOCS repo — the two git questions behind
+ * `loam vouch --pack`'s body delta: which commit last held the body a person
+ * vouched for (`findVouchedAncestor`), and what the file's diff from that
+ * commit to the working tree says (`bodyDiffText`). Read-only throughout:
+ * `rev-parse`/`log`/`show`/`diff`, no checkout, no temp writes.
+ *
+ * The mechanics are `core/diff/base-git.ts`'s to the letter — literally so:
+ * both import the one `gitText`/`GitAnswer`/`declineDetail` set from
+ * `../git.js`, so a hardening lands in both or in neither — but the doctrine
+ * is deliberately the OPPOSITE consequence. `loam diff` REFUSES when git
+ * cannot answer, because a silently empty base would report the whole fleet
+ * as added — a lie with a green exit code. The pack DEGRADES to "full read"
+ * instead: its output is a reading list, and for a reading list the
+ * conservative direction — read more, never less — is always honest, the same
+ * direction as provenance's existing hash-everything fallback. The shared
+ * helpers carry no verdict, so neither module can borrow the other's
+ * consequence by accident; each spells its own at its own call sites.
+ *
+ * The walk is BOUNDED at `ANCESTOR_WALK_CAP` commits. A vouched commit pushed
+ * past the cap by a very active docs repo degrades a legitimate incremental
+ * read to a full read — safe direction, and the `none` reason names the cap
+ * so the human understands why. Within the walk, one commit whose version of
+ * the file is absent (git answering "not here") is skipped; a git that stops
+ * answering mid-walk (spawn error, kill, timeout, output cap) aborts the whole
+ * search as `no-git` rather than letting 200 futile spawns each wait out the
+ * timeout.
+ */
+import { declineDetail, gitText } from "../git.js";
+import { contentDigest } from "../stamp.js";
+/**
+ * How many commits touching the file the ancestor search will read before
+ * declaring the vouched state unreachable. Past it the answer is `none` — a
+ * full read — with a reason that names the cap.
+ */
+const ANCESTOR_WALK_CAP = 200;
+/**
+ * How much diff text the pack will print. A body diff past this is not a
+ * reading list any more — the honest answer is "read the file", as `failed`.
+ */
+const MAX_DIFF_TEXT_CHARS = 1024 * 1024;
+/**
+ * The shared `gitText` (`../git.js`) with colour forced off. base-git's three
+ * questions (`rev-parse`/`ls-tree`/`show`) never colour, but this module runs
+ * `log` and `diff`, and a user's `color.ui = always` forces SGR escape
+ * sequences into their output even on a pipe — which would put terminal codes
+ * inside the `--json` payload's diff text and make the 40-hex-anchored log
+ * walk silently match nothing on exactly that machine. The flag lives here,
+ * not in the shared helper, because it is this module's need, not a property
+ * of asking git a question.
+ */
+async function gitPlain(docsDir, args) {
+    return gitText(docsDir, ["-c", "color.ui=false", ...args]);
+}
+/**
+ * The bytes this commit's blob would carry on a CRLF checkout. The stamped
+ * `content_digest` is byte-exact over the WORKING-TREE file (stamp.ts), while
+ * `git show` hands back the BLOB — and on a Windows checkout with
+ * `core.autocrlf=true` the blob is LF where every working-tree byte is CRLF,
+ * so the exact digest of the blob would never equal a stamp taken over the
+ * same content and every vouched ancestor would be invisible on exactly those
+ * machines. Same hazard, same direction as `core/verify/pins/pin.ts`'s
+ * `pinnedDigest`, resolved the inverse way because the stamp's recipe is
+ * published and cannot be re-normalized after the fact: instead of
+ * normalizing both sides, the search hashes each candidate twice — as the
+ * blob is, and as its CRLF checkout rendering — and a match on either is a
+ * match. Only lone LFs are rewritten, so a blob that already carries CRLFs
+ * (committed without the clean filter, hence byte-identical on disk) is
+ * covered by the exact hash.
+ */
+function checkoutRendering(text) {
+    return text.replace(/(?<!\r)\n/g, "\r\n");
+}
+/**
+ * The last commit in the docs repo's history whose version of `rel` (a
+ * docs-relative, `/`-separated path) has a body hashing to the stamped
+ * `content_digest` — newest first, because the reading list wants the
+ * SHORTEST honest diff, and any older commit holding the same bytes yields
+ * the same one.
+ */
+export async function findVouchedAncestor(docsDir, rel, stampedDigest) {
+    // Belt to the callers' braces: `rel` is derived from loam's own path
+    // spelling, never argv, but every spelled pathspec below rides an argv, so
+    // an option-shaped or empty value is refused here rather than parsed by
+    // git as a flag. Same reason base-git.ts refuses option-shaped refs.
+    if (rel.trim() === "" || rel.startsWith("-")) {
+        return { kind: "no-git", detail: `'${rel}' is not a path git can be asked about.` };
+    }
+    // `--show-prefix` first, and not decoration (base-git.ts proved this): a
+    // docs repo checked out as a subdirectory of a larger repository answers
+    // `show` only under that prefix, and a walk whose paths all miss would
+    // report "no vouched ancestor" about a history that holds one.
+    const where = await gitPlain(docsDir, ["rev-parse", "--show-prefix"]);
+    if (where.spawnError !== undefined || where.code !== 0) {
+        return { kind: "no-git", detail: declineDetail(where) };
+    }
+    const prefix = where.out.trim();
+    // The pathspec is cwd-relative (no prefix — `log` resolves it against the
+    // cwd, unlike `show`'s repo-root spelling below). `-n` is the walk's bound.
+    const log = await gitPlain(docsDir, [
+        "log", "-n", String(ANCESTOR_WALK_CAP), "--format=%H", "--", rel,
+    ]);
+    if (log.spawnError !== undefined || log.code !== 0 || log.overflowed) {
+        return { kind: "no-git", detail: declineDetail(log) };
+    }
+    // Only shas shaped like shas walk on — an unexpected line yields a shorter
+    // walk, never a malformed argv (the gitq/moves.ts token-anchoring rule).
+    const commits = log.out.split("\n").map((l) => l.trim()).filter((l) => /^[0-9a-f]{40}$/.test(l));
+    // Sequential on purpose: newest-first order is the answer's definition, and
+    // the walk stops at the first match — a fan-out would read history it does
+    // not need and could answer with an older commit than the newest match.
+    for (const commit of commits) {
+        const shown = await gitPlain(docsDir, ["show", `${commit}:${prefix}${rel}`]);
+        if (shown.spawnError !== undefined || shown.code === null) {
+            // Git stopped answering (not installed mid-walk, killed, timed out, or
+            // the output cap fired on a monstrous version). Abort rather than walk
+            // on: each further spawn could wait out the whole timeout, and a "none"
+            // built over commits nobody read would claim the history was searched.
+            return {
+                kind: "no-git",
+                detail: shown.overflowed
+                    ? `the file at ${commit.slice(0, 12)} exceeds the git output cap.`
+                    : declineDetail(shown),
+            };
+        }
+        // A real non-zero exit is git ANSWERING — the file is absent at this
+        // commit (renamed since, or the commit only deleted it). Skip it.
+        if (shown.code !== 0)
+            continue;
+        if (contentDigest(shown.out) === stampedDigest ||
+            contentDigest(checkoutRendering(shown.out)) === stampedDigest) {
+            return { kind: "found", commit, text: shown.out };
+        }
+    }
+    return {
+        kind: "none",
+        reason: commits.length < ANCESTOR_WALK_CAP
+            ? "body has no vouched ancestor in history"
+            : `body has no vouched ancestor in history — only the last ${ANCESTOR_WALK_CAP} commits touching the file were walked, and the vouched state may lie beyond them`,
+    };
+}
+/**
+ * The file's diff from its last vouched state: `git diff <commit> -- <rel>`,
+ * commit-to-working-tree, in the docs repo. The output is git's own — when a
+ * hand edit touched the frontmatter after the vouch, its hunks ride along,
+ * which is why the pack's prose says "the file's diff", never "the body's".
+ */
+export async function bodyDiffText(docsDir, commit, rel) {
+    // The commit came out of `findVouchedAncestor`'s own regex-vetted walk, but
+    // this function is exported API: re-vet, so no future caller can place an
+    // option-shaped string in the one argv slot that is not behind `--`.
+    if (!/^[0-9a-f]{40}$/.test(commit)) {
+        return { kind: "failed", reason: `'${commit}' is not a commit this diff can be asked about.` };
+    }
+    if (rel.trim() === "" || rel.startsWith("-")) {
+        return { kind: "failed", reason: `'${rel}' is not a path git can be asked about.` };
+    }
+    // `--no-optional-locks`: a commit-to-worktree diff may opportunistically
+    // refresh `.git/index`'s stat cache, which is a WRITE — small, benign, and
+    // exactly what a command documented as "writes nothing" must not do. The
+    // global flag tells git to skip any operation that would take a lock it
+    // does not strictly need. `--no-ext-diff --no-textconv` close the rest of
+    // the config surface: `diff.external` / a `.gitattributes` diff driver make
+    // `git diff` EXECUTE a user-configured program instead of printing a diff —
+    // an arbitrary write hazard on a read-only path, and output no machine
+    // consumer of `body.diff` could parse. The pack's diff is a machine
+    // artifact, not a terminal rendering; git's own plumbing flags say so.
+    const answer = await gitPlain(docsDir, [
+        "--no-optional-locks", "diff", "--no-ext-diff", "--no-textconv", commit, "--", rel,
+    ]);
+    if (answer.spawnError !== undefined || answer.code !== 0 || answer.overflowed) {
+        return { kind: "failed", reason: declineDetail(answer) };
+    }
+    if (answer.out.length > MAX_DIFF_TEXT_CHARS) {
+        return { kind: "failed", reason: "the body diff exceeds the pack's print cap — read the file" };
+    }
+    return { kind: "ok", diff: answer.out };
+}
+//# sourceMappingURL=vouched-ancestor.js.map

package/dist/core/provenance/gitq/vouched-ancestor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vouched-ancestor.js","sourceRoot":"","sources":["../../../../src/core/provenance/gitq/vouched-ancestor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Doc-body ancestry in the DOCS repo — the two git questions behind\n * `loam vouch --pack`'s body delta: which commit last held the body a person\n * vouched for (`findVouchedAncestor`), and what the file's diff from that\n * commit to the working tree says (`bodyDiffText`). Read-only throughout:\n * `rev-parse`/`log`/`show`/`diff`, no checkout, no temp writes.\n *\n * The mechanics are `core/diff/base-git.ts`'s to the letter — literally so:\n * both import the one `gitText`/`GitAnswer`/`declineDetail` set from\n * `../git.js`, so a hardening lands in both or in neither — but the doctrine\n * is deliberately the OPPOSITE consequence. `loam diff` REFUSES when git\n * cannot answer, because a silently empty base would report the whole fleet\n * as added — a lie with a green exit code. The pack DEGRADES to \"full read\"\n * instead: its output is a reading list, and for a reading list the\n * conservative direction — read more, never less — is always honest, the same\n * direction as provenance's existing hash-everything fallback. The shared\n * helpers carry no verdict, so neither module can borrow the other's\n * consequence by accident; each spells its own at its own call sites.\n *\n * The walk is BOUNDED at `ANCESTOR_WALK_CAP` commits. A vouched commit pushed\n * past the cap by a very active docs repo degrades a legitimate incremental\n * read to a full read — safe direction, and the `none` reason names the cap\n * so the human understands why. Within the walk, one commit whose version of\n * the file is absent (git answering \"not here\") is skipped; a git that stops\n * answering mid-walk (spawn error, kill, timeout, output cap) aborts the whole\n * search as `no-git` rather than letting 200 futile spawns each wait out the\n * timeout.\n */\nimport { declineDetail, gitText, type GitAnswer } from \"../git.js\";\nimport { contentDigest } from \"../stamp.js\";\n\n/**\n * How many commits touching the file the ancestor search will read before\n * declaring the vouched state unreachable. Past it the answer is `none` — a\n * full read — with a reason that names the cap.\n */\nconst ANCESTOR_WALK_CAP = 200;\n\n/**\n * How much diff text the pack will print. A body diff past this is not a\n * reading list any more — the honest answer is \"read the file\", as `failed`.\n */\nconst MAX_DIFF_TEXT_CHARS = 1024 * 1024;\n\n/**\n * The shared `gitText` (`../git.js`) with colour forced off. base-git's three\n * questions (`rev-parse`/`ls-tree`/`show`) never colour, but this module runs\n * `log` and `diff`, and a user's `color.ui = always` forces SGR escape\n * sequences into their output even on a pipe — which would put terminal codes\n * inside the `--json` payload's diff text and make the 40-hex-anchored log\n * walk silently match nothing on exactly that machine. The flag lives here,\n * not in the shared helper, because it is this module's need, not a property\n * of asking git a question.\n */\nasync function gitPlain(docsDir: string, args: string[]): Promise<GitAnswer> {\n  return gitText(docsDir, [\"-c\", \"color.ui=false\", ...args]);\n}\n\n/**\n * The bytes this commit's blob would carry on a CRLF checkout. The stamped\n * `content_digest` is byte-exact over the WORKING-TREE file (stamp.ts), while\n * `git show` hands back the BLOB — and on a Windows checkout with\n * `core.autocrlf=true` the blob is LF where every working-tree byte is CRLF,\n * so the exact digest of the blob would never equal a stamp taken over the\n * same content and every vouched ancestor would be invisible on exactly those\n * machines. Same hazard, same direction as `core/verify/pins/pin.ts`'s\n * `pinnedDigest`, resolved the inverse way because the stamp's recipe is\n * published and cannot be re-normalized after the fact: instead of\n * normalizing both sides, the search hashes each candidate twice — as the\n * blob is, and as its CRLF checkout rendering — and a match on either is a\n * match. Only lone LFs are rewritten, so a blob that already carries CRLFs\n * (committed without the clean filter, hence byte-identical on disk) is\n * covered by the exact hash.\n */\nfunction checkoutRendering(text: string): string {\n  return text.replace(/(?<!\\r)\\n/g, \"\\r\\n\");\n}\n\nexport type AncestorSearch =\n  | {\n      kind: \"found\";\n      commit: string;\n      /** The file exactly as that commit holds it — what the section delta reads. */\n      text: string;\n    }\n  /** The walk completed and nothing matched — the honest verdict is a full read. */\n  | { kind: \"none\"; reason: string }\n  /** Git declined somewhere the walk could not continue past — also a full read. */\n  | { kind: \"no-git\"; detail: string };\n\n/**\n * The last commit in the docs repo's history whose version of `rel` (a\n * docs-relative, `/`-separated path) has a body hashing to the stamped\n * `content_digest` — newest first, because the reading list wants the\n * SHORTEST honest diff, and any older commit holding the same bytes yields\n * the same one.\n */\nexport async function findVouchedAncestor(\n  docsDir: string,\n  rel: string,\n  stampedDigest: string,\n): Promise<AncestorSearch> {\n  // Belt to the callers' braces: `rel` is derived from loam's own path\n  // spelling, never argv, but every spelled pathspec below rides an argv, so\n  // an option-shaped or empty value is refused here rather than parsed by\n  // git as a flag. Same reason base-git.ts refuses option-shaped refs.\n  if (rel.trim() === \"\" || rel.startsWith(\"-\")) {\n    return { kind: \"no-git\", detail: `'${rel}' is not a path git can be asked about.` };\n  }\n  // `--show-prefix` first, and not decoration (base-git.ts proved this): a\n  // docs repo checked out as a subdirectory of a larger repository answers\n  // `show` only under that prefix, and a walk whose paths all miss would\n  // report \"no vouched ancestor\" about a history that holds one.\n  const where = await gitPlain(docsDir, [\"rev-parse\", \"--show-prefix\"]);\n  if (where.spawnError !== undefined || where.code !== 0) {\n    return { kind: \"no-git\", detail: declineDetail(where) };\n  }\n  const prefix = where.out.trim();\n\n  // The pathspec is cwd-relative (no prefix — `log` resolves it against the\n  // cwd, unlike `show`'s repo-root spelling below). `-n` is the walk's bound.\n  const log = await gitPlain(docsDir, [\n    \"log\", \"-n\", String(ANCESTOR_WALK_CAP), \"--format=%H\", \"--\", rel,\n  ]);\n  if (log.spawnError !== undefined || log.code !== 0 || log.overflowed) {\n    return { kind: \"no-git\", detail: declineDetail(log) };\n  }\n  // Only shas shaped like shas walk on — an unexpected line yields a shorter\n  // walk, never a malformed argv (the gitq/moves.ts token-anchoring rule).\n  const commits = log.out.split(\"\\n\").map((l) => l.trim()).filter((l) => /^[0-9a-f]{40}$/.test(l));\n  // Sequential on purpose: newest-first order is the answer's definition, and\n  // the walk stops at the first match — a fan-out would read history it does\n  // not need and could answer with an older commit than the newest match.\n  for (const commit of commits) {\n    const shown = await gitPlain(docsDir, [\"show\", `${commit}:${prefix}${rel}`]);\n    if (shown.spawnError !== undefined || shown.code === null) {\n      // Git stopped answering (not installed mid-walk, killed, timed out, or\n      // the output cap fired on a monstrous version). Abort rather than walk\n      // on: each further spawn could wait out the whole timeout, and a \"none\"\n      // built over commits nobody read would claim the history was searched.\n      return {\n        kind: \"no-git\",\n        detail: shown.overflowed\n          ? `the file at ${commit.slice(0, 12)} exceeds the git output cap.`\n          : declineDetail(shown),\n      };\n    }\n    // A real non-zero exit is git ANSWERING — the file is absent at this\n    // commit (renamed since, or the commit only deleted it). Skip it.\n    if (shown.code !== 0) continue;\n    if (\n      contentDigest(shown.out) === stampedDigest ||\n      contentDigest(checkoutRendering(shown.out)) === stampedDigest\n    ) {\n      return { kind: \"found\", commit, text: shown.out };\n    }\n  }\n  return {\n    kind: \"none\",\n    reason:\n      commits.length < ANCESTOR_WALK_CAP\n        ? \"body has no vouched ancestor in history\"\n        : `body has no vouched ancestor in history — only the last ${ANCESTOR_WALK_CAP} commits touching the file were walked, and the vouched state may lie beyond them`,\n  };\n}\n\nexport type BodyDiff =\n  | { kind: \"ok\"; diff: string }\n  /** No diff to print — the honest degrade is a full read, with this reason. */\n  | { kind: \"failed\"; reason: string };\n\n/**\n * The file's diff from its last vouched state: `git diff <commit> -- <rel>`,\n * commit-to-working-tree, in the docs repo. The output is git's own — when a\n * hand edit touched the frontmatter after the vouch, its hunks ride along,\n * which is why the pack's prose says \"the file's diff\", never \"the body's\".\n */\nexport async function bodyDiffText(docsDir: string, commit: string, rel: string): Promise<BodyDiff> {\n  // The commit came out of `findVouchedAncestor`'s own regex-vetted walk, but\n  // this function is exported API: re-vet, so no future caller can place an\n  // option-shaped string in the one argv slot that is not behind `--`.\n  if (!/^[0-9a-f]{40}$/.test(commit)) {\n    return { kind: \"failed\", reason: `'${commit}' is not a commit this diff can be asked about.` };\n  }\n  if (rel.trim() === \"\" || rel.startsWith(\"-\")) {\n    return { kind: \"failed\", reason: `'${rel}' is not a path git can be asked about.` };\n  }\n  // `--no-optional-locks`: a commit-to-worktree diff may opportunistically\n  // refresh `.git/index`'s stat cache, which is a WRITE — small, benign, and\n  // exactly what a command documented as \"writes nothing\" must not do. The\n  // global flag tells git to skip any operation that would take a lock it\n  // does not strictly need. `--no-ext-diff --no-textconv` close the rest of\n  // the config surface: `diff.external` / a `.gitattributes` diff driver make\n  // `git diff` EXECUTE a user-configured program instead of printing a diff —\n  // an arbitrary write hazard on a read-only path, and output no machine\n  // consumer of `body.diff` could parse. The pack's diff is a machine\n  // artifact, not a terminal rendering; git's own plumbing flags say so.\n  const answer = await gitPlain(docsDir, [\n    \"--no-optional-locks\", \"diff\", \"--no-ext-diff\", \"--no-textconv\", commit, \"--\", rel,\n  ]);\n  if (answer.spawnError !== undefined || answer.code !== 0 || answer.overflowed) {\n    return { kind: \"failed\", reason: declineDetail(answer) };\n  }\n  if (answer.out.length > MAX_DIFF_TEXT_CHARS) {\n    return { kind: \"failed\", reason: \"the body diff exceeds the pack's print cap — read the file\" };\n  }\n  return { kind: \"ok\", diff: answer.out };\n}\n"]}