okf-kit 0.9.0 → 0.11.0

package/dist/rules/sources-fresh.js

@@ -1,16 +1,24 @@
 import fs from "node:fs";
 import path from "node:path";
+import { parseFrontmatter } from "../bundle.js";
 import { runGit as defaultRunGit } from "../git.js";
-import { getTimestampEpoch, getValidSources } from "../util.js";
+import { getRawTimestampString, getTimestampEpoch, getTimestampIdentity, getValidSources, hasUtcDesignator, } from "../util.js";
 const RULE_ID = "sources-fresh";
+const FUTURE_RULE_ID = "sources-fresh-future";
+/**
+ * Default clock-skew allowance (seconds) for `sources-fresh-future`: a doc
+ * timestamp up to this far after the doc's own last commit is still treated
+ * as fresh, absorbing the ordinary gap between "author wrote the timestamp"
+ * and "the commit that carries it landed". Override via
+ * `ctx.freshnessFutureSkewSeconds` (CLI: `--future-skew-minutes`).
+ */
+export const DEFAULT_FUTURE_SKEW_SECONDS = 600;
 export const sourcesFreshRule = {
     id: RULE_ID,
-    description: "Frontmatter `sources` paths must not have a last-commit time newer than the doc's `timestamp` and the doc file's own last commit.",
+    description: "Frontmatter `sources` paths must not have a last-commit time newer than the doc's `timestamp`, unless the doc's own last commit lands at/after the source's and that same commit actually re-stamped the doc: the doc's parsed frontmatter `timestamp` VALUE at that commit differs from its value in the commit's first parent (rename-aware; creating the doc counts as re-stamping it). Creation is trusted only in a genuinely unshallow repository: in a shallow clone, a commit with no parents can simply be where history was cut off, not a real root commit, so it gets the same `not assessable` notice instead of being assumed created. When git cannot answer the question at all, the doc gets a `not assessable` notice instead of either a STALE warning or a silent pass.",
     run(ctx) {
         const findings = [];
-        const docsWithSources = ctx.docs
-            .map((doc) => ({ doc, sources: getValidSources(doc.frontmatter.parsed) }))
-            .filter((entry) => entry.sources !== undefined);
+        const docsWithSources = getDocsWithSources(ctx);
         if (docsWithSources.length === 0)
             return findings;
         if (!ctx.repoRoot) {
@@ -18,6 +26,9 @@ export const sourcesFreshRule = {
             // either (sources-shape), so staleness truly was not assessed, not
             // "everything looked fine". One notice for the whole bundle, not one
             // per doc: this is a bundle-level condition, not a per-doc finding.
+            // sources-fresh-future shares this same population and posture; it
+            // relies on this single notice too instead of emitting its own (see
+            // that rule below).
             findings.push({
                 ruleId: RULE_ID,
                 severity: "notice",
@@ -28,17 +39,39 @@ export const sourcesFreshRule = {
         }
         const repoRoot = ctx.repoRoot;
         const git = ctx.runGit ?? defaultRunGit;
+        // `--dirty-as-now` asked for, but git could not tell us what is dirty
+        // (a `status` past RunGit's output cap, a `rev-parse` failure, git
+        // missing): every path below then falls through to committed history,
+        // which is the RIGHT fallback but the WRONG silence -- "the flag found
+        // nothing dirty" and "the flag never ran" produce the identical empty
+        // finding list. Say so once, bundle-level, in the same style as the
+        // "not inside a git work tree" notice above (and, like that one,
+        // emitted only here: `sources-fresh-future` shares the same degraded
+        // state and relies on this single notice instead of duplicating it).
+        if (ctx.dirtyAsNow && getDirtyStateShared(ctx, git, repoRoot) === null) {
+            findings.push({
+                ruleId: RULE_ID,
+                severity: "notice",
+                file: "",
+                message: "`--dirty-as-now` not applied: git status could not be read, judging by committed history only",
+            });
+        }
         // One git call per unique source path across all docs, even though a
         // STALE/untracked finding is reported per (doc, path) below.
         const commitEpochCache = new Map();
-        const commitEpochFor = (source) => {
+        // `--dirty-as-now`: every dirty path's "commit epoch" is the SAME
+        // virtual-commit instant, shared (by `ctx` identity) with
+        // `sources-fresh-future`'s doc-epoch lookup below -- see
+        // `commitEpochWithDirtyAsNow`'s doc comment for why this lives in one
+        // place instead of being reimplemented per rule.
+        const commitEpochFor = (source) => commitEpochWithDirtyAsNow(ctx, git, repoRoot, source, () => {
             const cached = commitEpochCache.get(source);
             if (cached !== undefined)
                 return cached;
             const epoch = getLastCommitEpoch(git, repoRoot, source);
             commitEpochCache.set(source, epoch);
             return epoch;
-        };
+        });
         for (const { doc, sources } of docsWithSources) {
             const timestampEpoch = getTimestampEpoch(doc.frontmatter.parsed);
             if (timestampEpoch === undefined) {
@@ -51,15 +84,68 @@ export const sourcesFreshRule = {
                 continue;
             }
             // A doc whose own last commit is at or after the source's last commit
-            // (typically: both landed in one squash-merge) is not stale, even if
-            // its frontmatter timestamp is old. Lazy + memoized: the lookup costs a
-            // git process per doc but is only ever consulted on the stale path.
-            const repoRelDocPath = path
-                .relative(repoRoot, path.join(ctx.bundleDir, doc.relPath))
-                .split(path.sep)
-                .join("/");
-            let docCommitEpochMemo;
-            const docCommitEpochFor = () => (docCommitEpochMemo ??= getLastCommitEpoch(git, repoRoot, repoRelDocPath));
+            // (typically: both landed in one squash-merge), AND that same commit
+            // actually re-stamped the doc, is not stale, even if its frontmatter
+            // timestamp predates the merge -- see restampedByOwnLastCommit below
+            // for what "re-stamped" means and why the plain commit-ordering check
+            // alone is not enough. Both lookups are lazy + memoized: they are only
+            // ever consulted on the stale path, and the epoch lookup is shared
+            // with sources-fresh-future via getDocCommitEpochShared so the two
+            // rules don't each spawn their own `git log` for the same doc in one
+            // `check` run.
+            //
+            // GIT PROCESS BUDGET, per doc, per `check` run, with `--dirty-as-now`
+            // OFF (this figure is measured with the flag off; see below for its
+            // extra cost with the flag on): 1 (the shared `git log -1
+            // --format=%ct` epoch lookup, always) + at most 4 more on the
+            // re-stamp path (`git log -1 --format=%H%n%P`, then `git diff-tree`,
+            // then two `git show`s), i.e. AT MOST 5 -- regardless of how many
+            // sources the doc declares, since both lookups are memoized per doc.
+            // A doc created by its last commit (or by the repo's root commit)
+            // stops after 2 (or 1). Plus one `git log` per UNIQUE source path
+            // across the whole bundle (commitEpochCache above). Pinned by
+            // "spends at most five git processes per doc" in
+            // test/sources-fresh.test.ts. PLUS: at most 1 `git rev-parse
+            // --is-shallow-repository` for the ENTIRE run, not per doc (see
+            // isShallowRepoShared below) -- only spent at all when some doc's
+            // re-stamp lookup actually reaches a root commit.
+            //
+            // With `--dirty-as-now` ON, add 2 for the ENTIRE run (not per doc,
+            // not per source -- see readDirtyState): 1 `git status --porcelain`
+            // and 1 `git rev-parse --show-prefix`. Plus, PER DOC, at most 1 `git
+            // ls-tree HEAD -- <doc>` (and, only when the doc already existed at
+            // HEAD, one more `git show HEAD:<doc>`), spent only when that doc is
+            // itself dirty AND some source of its reads stale (see restampFor
+            // below).
+            const repoRelDocPath = toRepoRelDocPath(repoRoot, ctx.bundleDir, doc);
+            const docCommitEpochFor = () => getDocCommitEpochShared(ctx, git, repoRoot, repoRelDocPath);
+            // The single decision point for "did the doc's last commit -- real or
+            // virtual -- actually re-stamp it": a dirty doc (under
+            // `--dirty-as-now`) is judged by its WORKING-TREE value against the
+            // value committed at HEAD (`dirtyDocRestampVerdict`, the virtual
+            // commit's implicit "first parent" is simply HEAD); a doc that is not
+            // itself dirty is judged the ordinary way, against its real last
+            // commit's first parent (`restampedByOwnLastCommit`). This replaces
+            // the round-2 approach of a SEPARATE rescue branch checked before the
+            // co-commit path: once `docCommitEpochFor` above already reports the
+            // dirty doc's epoch as "now" (see `commitEpochWithDirtyAsNow`), the
+            // ordinary `docCommitEpoch >= commitEpoch` gate below fires for a
+            // dirty doc exactly the way it fires for a real co-commit, so only
+            // ONE verdict function needs to be picked here, not two independent
+            // mechanisms answering overlapping questions.
+            let restampMemo;
+            const restampFor = () => {
+                if (restampMemo !== undefined)
+                    return restampMemo;
+                restampMemo =
+                    ctx.dirtyAsNow && isDirtyForShared(ctx, git, repoRoot, repoRelDocPath)
+                        ? dirtyDocRestampVerdict(git, repoRoot, repoRelDocPath, getTimestampIdentity(doc.frontmatter.parsed))
+                        : restampedByOwnLastCommit(git, repoRoot, repoRelDocPath, () => isShallowRepoShared(ctx, git, repoRoot));
+                return restampMemo;
+            };
+            // At most one "not assessable" notice per doc, however many of its
+            // sources hit the unanswerable re-stamp question.
+            let notAssessableReported = false;
             for (const source of sources) {
                 // A missing path on disk is sources-shape's job to report; avoid a
                 // duplicate/confusing finding here.
@@ -76,13 +162,37 @@ export const sourcesFreshRule = {
                     continue;
                 }
                 let isStale = commitEpoch > timestampEpoch;
-                // Doc committed at/after the source: not stale (see comment above).
-                // A doc without git history (null epoch, e.g. uncommitted) keeps the
-                // frontmatter-only comparison.
                 if (isStale) {
+                    // Doc committed (or, under `--dirty-as-now`, virtually committed
+                    // right now) at/after the source, AND that commit actually
+                    // re-stamped it: not stale (see comment above). A doc without git
+                    // history (null epoch, e.g. uncommitted and clean, no dirty
+                    // status at all) keeps the frontmatter-only comparison. When git
+                    // cannot answer the re-stamp question at all, the doc is reported
+                    // as not assessable rather than being guessed either way: calling
+                    // it STALE would turn a git hiccup into a red build, and calling
+                    // it fresh would be a silent pass.
                     const docCommitEpoch = docCommitEpochFor();
                     if (docCommitEpoch !== null && docCommitEpoch >= commitEpoch) {
-                        isStale = false;
+                        const verdict = restampFor();
+                        if (verdict === "restamped") {
+                            isStale = false;
+                        }
+                        else if (verdict === "unknown" ||
+                            verdict === "unknown-shallow-root") {
+                            if (!notAssessableReported) {
+                                notAssessableReported = true;
+                                findings.push({
+                                    ruleId: RULE_ID,
+                                    severity: "notice",
+                                    file: doc.relPath,
+                                    message: verdict === "unknown-shallow-root"
+                                        ? "staleness not assessable: this is a shallow clone (`git clone --depth`), so git cannot tell whether the doc's earliest available commit really created it or is just where history was cut off -- use `fetch-depth: 0` (or an unshallow checkout) to assess it"
+                                        : "staleness not assessable: git could not read the doc's own last commit to decide whether it re-stamped the doc",
+                                });
+                            }
+                            continue;
+                        }
                     }
                 }
                 if (isStale) {
@@ -98,6 +208,109 @@ export const sourcesFreshRule = {
         return findings;
     },
 };
+/**
+ * Complements `sources-fresh`'s "too old" check with the opposite direction:
+ * a doc `timestamp` that is later than the doc file's OWN last commit (past
+ * a small clock-skew allowance) is almost always a mistake, not a real
+ * future date -- typically a local wall-clock time hand-written with a
+ * trailing `Z`/UTC suffix it does not actually have. Unlike `sources-fresh`,
+ * this check never looks at `sources` commit times at all: it only compares
+ * the doc's own `timestamp` against the doc file's own git history, so it
+ * has nothing to say about whether any source is stale.
+ *
+ * Deliberately assessed for the SAME population as `sources-fresh` (docs
+ * with a validly-shaped `sources` list and a repo root available): a
+ * `timestamp` only has "last verified against sources" semantics for a doc
+ * that declares `sources` (see the package README's authoring guidance), so
+ * a sourceless doc is out of scope for both freshness rules, not just this
+ * one. It shares `sources-fresh`'s "staleness unknown" posture for the two
+ * cases that make a real answer impossible: no repo root (silently defers
+ * to the single bundle-level notice `sources-fresh` already emits above,
+ * rather than duplicating it) and no valid `timestamp` (`sources-fresh`
+ * already reports that per-doc notice, so this rule silently skips such a
+ * doc rather than reporting it twice). An uncommitted doc (no own commit
+ * yet) is likewise "unknown, not flagged" by DEFAULT: there is no real
+ * commit time to compare the timestamp against, and flagging every
+ * hand-authored, not-yet-committed doc as "future-dated" would be a false
+ * positive on every fresh draft. Under `--dirty-as-now` (`ctx.dirtyAsNow`),
+ * this changes: `getDocCommitEpochShared` below substitutes the shared
+ * virtual-commit "now" instant for ANY dirty doc's epoch (untracked
+ * included -- see `commitEpochWithDirtyAsNow`), so a dirty doc DOES get a
+ * real comparison here, exactly the working-tree parity `--dirty-as-now`
+ * exists for: a `timestamp` re-stamped to "now" reads fresh (within the
+ * skew allowance), while one still carrying an implausible future value
+ * gets caught before the commit that would otherwise make it so in CI.
+ */
+export const sourcesFreshFutureRule = {
+    id: FUTURE_RULE_ID,
+    description: "A doc's frontmatter `timestamp` must not be later than the doc file's own last commit time by more than a clock-skew allowance (default 10 minutes, `--future-skew-minutes`); catches a local time mistakenly written with a `Z`/UTC suffix. Skipped (notice) for a timestamp with no explicit UTC designator (`Z`) or numeric offset, since that parses in the local timezone and cannot be compared reliably against a minutes-wide allowance. Assessed for the same docs as `sources-fresh` (a `sources` list and a repo root); see the README's \"Staleness (sources-fresh)\" section for how the two rules relate.",
+    run(ctx) {
+        const findings = [];
+        const docsWithSources = getDocsWithSources(ctx);
+        if (docsWithSources.length === 0)
+            return findings;
+        if (!ctx.repoRoot)
+            return findings;
+        const repoRoot = ctx.repoRoot;
+        const git = ctx.runGit ?? defaultRunGit;
+        const skewSeconds = ctx.freshnessFutureSkewSeconds ?? DEFAULT_FUTURE_SKEW_SECONDS;
+        for (const { doc } of docsWithSources) {
+            const timestampEpoch = getTimestampEpoch(doc.frontmatter.parsed);
+            if (timestampEpoch === undefined)
+                continue;
+            // A string timestamp with no `Z`/numeric-offset suffix parses in the
+            // machine's local timezone (`Date.parse`), which would make this
+            // check's verdict swing by hours between machines against a
+            // minutes-wide allowance -- not usable. A native `Date` frontmatter
+            // value (see getTimestampEpoch's doc comment) carries no such
+            // ambiguity and always passes this gate. sources-fresh's own
+            // thresholds are in days, wide enough that this ambiguity doesn't
+            // practically matter there, so this gate is deliberately NOT applied
+            // to that rule.
+            const rawTimestamp = getRawTimestampString(doc.frontmatter.parsed);
+            if (rawTimestamp !== undefined && !hasUtcDesignator(rawTimestamp)) {
+                findings.push({
+                    ruleId: FUTURE_RULE_ID,
+                    severity: "notice",
+                    file: doc.relPath,
+                    message: "future-dated check skipped: timestamp has no UTC designator (`Z`) or numeric offset, can't be compared reliably across timezones",
+                });
+                continue;
+            }
+            const repoRelDocPath = toRepoRelDocPath(repoRoot, ctx.bundleDir, doc);
+            const docCommitEpoch = getDocCommitEpochShared(ctx, git, repoRoot, repoRelDocPath);
+            if (docCommitEpoch === null)
+                continue;
+            if (timestampEpoch > docCommitEpoch + skewSeconds) {
+                findings.push({
+                    ruleId: FUTURE_RULE_ID,
+                    severity: "warning",
+                    file: doc.relPath,
+                    message: `FUTURE-DATED: doc timestamp ${epochToIso(timestampEpoch)} is after the doc's own last commit ${epochToIso(docCommitEpoch)} (skew allowance ${skewSeconds}s)`,
+                });
+            }
+        }
+        return findings;
+    },
+};
+/**
+ * Docs carrying a validly-shaped frontmatter `sources` list (see
+ * `getValidSources`), each paired with that list. Shared by both rules in
+ * this file: `sources-fresh` and `sources-fresh-future` assess the same
+ * doc population, just in opposite time directions.
+ */
+function getDocsWithSources(ctx) {
+    return ctx.docs
+        .map((doc) => ({ doc, sources: getValidSources(doc.frontmatter.parsed) }))
+        .filter((entry) => entry.sources !== undefined);
+}
+/** `doc`'s own path, relative to `repoRoot`, forward-slash separated -- the pathspec `git log` needs. */
+function toRepoRelDocPath(repoRoot, bundleDir, doc) {
+    return path
+        .relative(repoRoot, path.join(bundleDir, doc.relPath))
+        .split(path.sep)
+        .join("/");
+}
 /**
  * Last-commit epoch (seconds) for `source` relative to `repoRoot`, or null
  * when the path has no git history (untracked) or the git call itself
@@ -105,6 +318,10 @@ export const sourcesFreshRule = {
  * empty stdout, which is exactly the "untracked" case, distinct from a real
  * git failure (which RunGit also reports as null): both collapse to null
  * here because sources-fresh treats them the same way, "staleness unknown".
+ * Uses committer time (`%ct`), not author time (`%at`): a rebase or
+ * cherry-pick can carry a stale author date forward while the committer
+ * date reflects when the content actually landed on this branch, which is
+ * what both freshness rules care about.
  */
 function getLastCommitEpoch(git, repoRoot, source) {
     const out = git(["log", "-1", "--format=%ct", "--", source], repoRoot);
@@ -113,7 +330,567 @@ function getLastCommitEpoch(git, repoRoot, source) {
     const epoch = Number.parseInt(out, 10);
     return Number.isNaN(epoch) ? null : epoch;
 }
+/**
+ * The full SET of repo-root-relative paths `git status --porcelain`
+ * reports as dirty (modified, staged, or untracked) across the WHOLE work
+ * tree, read via a SINGLE `status` process for the entire `check` run --
+ * not one process per unique `sources` path (the original, pre-review
+ * implementation), and not one per doc for the local-restamp rescue
+ * below. Used only behind `--dirty-as-now` (`ctx.dirtyAsNow`): a dirty
+ * path has no "last commit" yet that reflects its current content, so
+ * `sources-fresh` substitutes the current time for it instead of falling
+ * through to `getLastCommitEpoch`'s answer (the LAST commit's time, which
+ * for a locally-edited-but-uncommitted file is necessarily stale).
+ *
+ * `--no-optional-locks` skips git's opportunistic index refresh (which can
+ * otherwise rewrite the on-disk index file as a side effect of a plain
+ * `status`) -- unwanted here since this runs as a read-only check, often
+ * from a hook or CI step that should not perturb the index. Ignored files
+ * are deliberately NOT included (no `--ignored`): an ignored source keeps
+ * today's "untracked by git, staleness unknown" notice instead of being
+ * newly reported dirty by this option.
+ *
+ * `--untracked-files=all` (`-uall`) is NOT optional decoration. Under
+ * git's default untracked mode (`normal`), a brand-new directory is
+ * collapsed into ONE record for the directory itself (`? newdir/`) and the
+ * files inside it are never listed. The matcher below matches a queried
+ * path that IS a reported entry or is an ANCESTOR of one, so under that
+ * default a `sources` entry (or a doc) INSIDE a new untracked directory
+ * matched nothing at all and silently kept its committed-history verdict:
+ * `check --dirty-as-now` reported a brand-new source as merely `untracked
+ * by git, staleness unknown` (exit 0) while a plain `check` after
+ * committing it reported STALE (exit 1) -- the precise local/CI divergence
+ * this flag exists to remove. `-uall` makes git enumerate every untracked
+ * FILE as its own record, so the ordinary exact/descendant matching sees
+ * them. The cost is output size: `-uall` prints one record per untracked
+ * file rather than per untracked directory, which in a work tree carrying
+ * a large untracked build or dependency tree (anything not covered by
+ * `.gitignore` -- ignored paths are still excluded, see above) can run to
+ * many thousands of records. That output travels through RunGit's 16 MiB
+ * cap (`MAX_GIT_OUTPUT_BYTES` in src/git.ts), and a status that exceeds it
+ * resolves to null like any other git failure -- reported as the
+ * bundle-level "not applied" notice the rule emits, never as a silent
+ * "nothing is dirty".
+ *
+ * `git rev-parse --show-prefix` is the SECOND (and last) git process this
+ * costs per run. `git status` always reports paths relative to the
+ * repository's TOP LEVEL, while a `sources` entry is relative to
+ * `ctx.repoRoot` -- the same directory only when `--repo-root` names the
+ * top level. Pointed at a SUBDIRECTORY (`--repo-root packages/foo`), every
+ * status path carries a `packages/foo/` prefix the queried path does not,
+ * so nothing ever matched and the flag silently did nothing. Reading the
+ * prefix once and prepending it at match time makes that case work instead
+ * of quietly no-opping.
+ *
+ * Uses `--porcelain=v2 -z`, not the more familiar `--porcelain` (v1) line
+ * format, for one reason that is NOT about renames or quoting (`-z` alone
+ * would fix both): RunGit (src/git.ts) `.trim()`s every git invocation's
+ * output, and a v1 line for an unstaged-only change starts with a LITERAL
+ * SPACE (` M path`, index clean, worktree modified) -- an entirely common
+ * case. When that happens to be the FIRST line of the whole status output,
+ * `.trim()` strips that leading space as ordinary boundary whitespace,
+ * silently shifting every fixed-offset field in that one line and
+ * corrupting its path (verified against real git output: a lone `M
+ * source.ts` line, meant to be ` M source.ts`, parses to the wrong path
+ * with a fixed `line.slice(3)` cut). Every v2 record instead starts with a
+ * digit or letter (`1`, `2`, `u`, `?`) that is never whitespace, so the
+ * SAME `.trim()` can never eat a leading field byte. NUL (`-z`) delimits
+ * every record and untracked/rename path field can safely contain a space,
+ * tab, or non-ASCII byte, mirroring previousPathIn's `-z` rationale
+ * elsewhere in this file. Record shapes actually seen here (verified
+ * against real git output; XY, sub, mode and hash fields are read
+ * positionally, never re-split by content, since a path can itself
+ * legitimately contain a space): `? path` (untracked); `1 XY sub mH mI mW
+ * hH hI path` (ordinary; 8 fixed fields before path); `2 XY sub mH mI mW
+ * hH hI score path\0origPath` (rename/copy; 9 fixed fields before path,
+ * origPath is the FOLLOWING NUL-delimited token verbatim); `u XY sub m1 m2
+ * m3 mW h1 h2 h3 path` (unmerged; 10 fixed fields before path) -- both
+ * sides of a rename count as dirty. `!` (ignored) records are never
+ * produced since `--ignored` is not passed.
+ *
+ * A failed git call (either one: `null`) makes the WHOLE state null, which
+ * every path then falls through on -- it keeps its ordinary commit-epoch
+ * verdict rather than this function inventing a dirty one. Unlike every
+ * other git failure in this file that is silent, this one is surfaced: the
+ * rule turns a null state into a single bundle-level "`--dirty-as-now` not
+ * applied" notice, because "the flag silently did nothing" and "nothing
+ * was dirty" are indistinguishable to a reader of an empty finding list.
+ */
+function readDirtyState(git, repoRoot) {
+    // `""` (this IS the top level) is a valid answer, so only an outright
+    // failure (`null`) disables the flag here.
+    const rawPrefix = git(["rev-parse", "--show-prefix"], repoRoot);
+    if (rawPrefix === null)
+        return null;
+    const prefix = rawPrefix === "" ? "" : `${normalizeRelPath(rawPrefix)}/`;
+    const out = git([
+        "--no-optional-locks",
+        "status",
+        "--porcelain=v2",
+        "-z",
+        "--untracked-files=all",
+    ], repoRoot);
+    if (out === null)
+        return null;
+    const paths = new Set();
+    // `-z` NUL-terminates every record, including the last -- RunGit's
+    // `.trim()` does not strip NUL, so splitting always leaves one empty
+    // trailing token.
+    const tokens = out.split("\0").filter((t) => t !== "");
+    let i = 0;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        const kind = token[0];
+        if (kind === "?") {
+            paths.add(normalizeRelPath(token.slice(2)));
+            i += 1;
+        }
+        else if (kind === "1") {
+            paths.add(normalizeRelPath(token.split(" ").slice(8).join(" ")));
+            i += 1;
+        }
+        else if (kind === "2") {
+            paths.add(normalizeRelPath(token.split(" ").slice(9).join(" ")));
+            const origPath = tokens[i + 1];
+            if (origPath !== undefined)
+                paths.add(normalizeRelPath(origPath));
+            i += 2;
+        }
+        else if (kind === "u") {
+            paths.add(normalizeRelPath(token.split(" ").slice(10).join(" ")));
+            i += 1;
+        }
+        else {
+            // An unrecognized record kind (should not occur without --ignored,
+            // which is never passed): skip rather than mis-parse it as a path.
+            i += 1;
+        }
+    }
+    return { prefix, paths };
+}
+/**
+ * Canonicalizes a repo-relative path spelling before it is used as a dirty
+ * lookup key or matched against one: strips a leading `./`, strips a
+ * trailing `/`, converts backslashes to forward slashes, and collapses `.`
+ * / `..` segments and duplicate slashes via `path.posix.normalize`. `git
+ * status` itself always reports canonical forward-slash paths with neither
+ * a leading `./` nor a trailing `/`, but a frontmatter-authored `sources`
+ * entry (or a doc's own bundle-relative path, joined with `path.join`) is
+ * under no such obligation -- `./srcdir` and `srcdir/` name the exact same
+ * directory `srcdir` does, and MUST match the same dirty entries it does.
+ * Applied on BOTH sides of every dirty-path comparison in this file (here,
+ * at insertion into the dirty-paths Set, and in `isDirtyForShared` on the
+ * queried path already joined with the repo prefix), so any spelling of
+ * the same path always matches.
+ *
+ * `.`, `./` and the empty string all normalize to `.`, the root directory
+ * itself. That is a legal `sources` spelling but never a `git status`
+ * entry, so `isDirtyForShared` answers it by containment instead of by
+ * lookup -- see the `normalized === "."` branch there.
+ *
+ * A round-1-then-round-2 regression this closes: the per-run status
+ * refactor introduced exact-path (`paths.has`) and prefix (`startsWith`)
+ * matching against the RAW `source` string, so `srcdir/` built a
+ * self-defeating double-slash prefix (`srcdir//`) and `./srcdir` never
+ * matched a `git status` path at all (which never carries a `./` prefix) --
+ * both spellings silently lost dirty detection entirely.
+ */
+function normalizeRelPath(relPath) {
+    let p = relPath.replace(/\\/g, "/");
+    while (p.startsWith("./"))
+        p = p.slice(2);
+    p = path.posix.normalize(p);
+    while (p.length > 1 && p.endsWith("/"))
+        p = p.slice(0, -1);
+    return p;
+}
+/**
+ * Per-run cache (keyed by `BundleContext`, same pattern as
+ * `docCommitEpochCache` below) of `readDirtyState`'s answer, so the WHOLE
+ * `check` run -- both rules, every doc, every source -- spends at most one
+ * `git status` (plus one `git rev-parse --show-prefix`) process, not one
+ * per rule. A cached `null` (the git read failed) is a real cached answer,
+ * hence the `.has` check rather than a truthiness test: a failed read is
+ * not retried per source.
+ */
+const dirtyStateCache = new WeakMap();
+function getDirtyStateShared(ctx, git, repoRoot) {
+    if (dirtyStateCache.has(ctx))
+        return dirtyStateCache.get(ctx) ?? null;
+    const state = readDirtyState(git, repoRoot);
+    dirtyStateCache.set(ctx, state);
+    return state;
+}
+/**
+ * Whether `relPath` (a `sources` entry OR a doc's own path relative to
+ * `ctx.repoRoot`, in any spelling `normalizeRelPath` accepts) is dirty per
+ * `git status`. The queried path is first rebased onto the repository top
+ * level with `state.prefix` (a no-op in the ordinary case where
+ * `--repo-root` IS the top level), since that is the frame every reported
+ * dirty path is expressed in. A dirty FILE then matches by exact
+ * (normalized) path; a dirty DIRECTORY source matches if any reported
+ * dirty path lives under it (a `/`-terminated prefix, so a sibling
+ * directory whose name merely starts with the same characters -- `srcdir`
+ * vs `srcdirX/x.ts` -- never falsely matches).
+ *
+ * `.` (or `./`, or any spelling that normalizes to `.`) names the root
+ * directory itself, which `git status` never reports as an entry and which
+ * no `"./"`-prefix test can match either -- so it is matched explicitly as
+ * "any dirty path at all lives under this root", the same containment
+ * question the directory case asks, just with an empty prefix. Without
+ * that branch a bundle declaring `.` as its source silently lost dirty
+ * detection entirely.
+ *
+ * A failed state read (`null`) is treated as "nothing is dirty": every
+ * path falls through to its ordinary (real) commit-epoch path rather than
+ * this function inventing a dirty verdict either way. The rule reports
+ * that case once, bundle-level, rather than letting the flag no-op in
+ * silence (see `readDirtyState`).
+ */
+function isDirtyForShared(ctx, git, repoRoot, relPath) {
+    const state = getDirtyStateShared(ctx, git, repoRoot);
+    if (state === null)
+        return false;
+    const { paths } = state;
+    const normalized = normalizeRelPath(`${state.prefix}${relPath}`);
+    if (normalized === ".")
+        return paths.size > 0;
+    if (paths.has(normalized))
+        return true;
+    const prefix = `${normalized}/`;
+    for (const p of paths) {
+        if (p.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Per-run cache (keyed by `BundleContext`) of the SINGLE "now" instant
+ * `--dirty-as-now` substitutes for every dirty path's commit epoch, shared
+ * across BOTH rules in this file and every doc/source they assess: every
+ * dirty path in one `check` invocation is treated as landing in the exact
+ * same virtual commit, so two dirty sources (or a dirty source and a dirty
+ * doc) never disagree with each other about what "now" was.
+ *
+ * THE CACHE IS THE GUARANTEE, not the order the callers happen to run in.
+ * The rescue gate above is an INEQUALITY on epochs (`docCommitEpoch >=
+ * commitEpoch`) whose two sides are BOTH this value when a dirty doc is
+ * paired with a dirty source. Reading the clock afresh on each side
+ * instead would leave the gate resting on call order: as the rule is
+ * written today the source's epoch is read before the doc's
+ * (`commitEpochFor`, then `docCommitEpochFor`), so a second-boundary
+ * crossing between them could only ever raise the DOC's side and the gate
+ * would survive by accident -- but read in the other order (a reordering
+ * nothing in the rule forbids) the doc's side would be the older one, and
+ * a run that straddled a whole second would flip to a silent,
+ * unreproducible STALE. The cache removes the ordering question entirely:
+ * every dirty path in one run reads the identical integer, so the gate
+ * holds with equality no matter who asks first. Any future caller wanting
+ * "now" here must therefore go through this accessor rather than reading
+ * the clock again.
+ */
+const nowEpochCache = new WeakMap();
+function getNowEpochShared(ctx) {
+    let epoch = nowEpochCache.get(ctx);
+    if (epoch === undefined) {
+        epoch = Math.floor(Date.now() / 1000);
+        nowEpochCache.set(ctx, epoch);
+    }
+    return epoch;
+}
+/**
+ * THE single choke point where `--dirty-as-now`'s virtual-commit model is
+ * applied: a dirty `relPath` (source or doc, see `isDirtyForShared`) is
+ * judged as committed at the shared "now" instant (`getNowEpochShared`)
+ * instead of consulting `actualEpoch` at all; anything else -- the flag
+ * off, or `relPath` not dirty -- defers to `actualEpoch` (typically a
+ * memoized real `git log` lookup), byte-identical to pre-flag behavior.
+ * Every commit-epoch read in this file that is meant to honor
+ * `--dirty-as-now` MUST go through this function (directly, or via
+ * `getDocCommitEpochShared` below, which is itself built on it) rather
+ * than re-implementing the dirty check inline, so a source's epoch and a
+ * doc's own epoch are always read the same way, by both rules.
+ */
+function commitEpochWithDirtyAsNow(ctx, git, repoRoot, relPath, actualEpoch) {
+    if (ctx.dirtyAsNow && isDirtyForShared(ctx, git, repoRoot, relPath)) {
+        return getNowEpochShared(ctx);
+    }
+    return actualEpoch();
+}
+/**
+ * `--dirty-as-now` only: the verdict for "did the doc's OWN uncommitted
+ * working-tree state re-stamp it" -- the virtual-commit analogue of
+ * `restampedByOwnLastCommit`'s co-commit check, used in its place (see
+ * `restampFor` in the rule above) whenever the doc itself is dirty. The
+ * virtual commit's implicit "first parent" is simply HEAD, so this compares
+ * the doc's CURRENT (working-tree) parsed `timestamp` identity -- already
+ * read from disk by the caller, since `BundleDoc` always reflects the
+ * working tree, dirty or not -- against the value committed at HEAD for the
+ * same path. Any change of value, in EITHER direction (including a
+ * backwards re-stamp), counts as re-stamped, mirroring the committed
+ * rescue's "changed, not corrected" semantics documented on
+ * `restampedByOwnLastCommit` below.
+ *
+ * Distinguishes a genuinely untracked/new doc (no entry for this path at
+ * HEAD at all -- `git ls-tree HEAD -- <path>` succeeds with EMPTY output,
+ * never a git failure) from a real git failure reading an EXISTING HEAD
+ * blob (`git show` itself failing -- a corrupt object, an unreadable blob):
+ * the former counts as "restamped" (there is no prior committed value to
+ * compare against, so its whole content, stamp included, is new -- the
+ * working-tree equivalent of "the doc being created there"); the latter is
+ * `unknown`, falling through to the rule's existing not-assessable notice
+ * rather than being silently treated the same as "created". `git ls-tree`
+ * itself failing (an unborn HEAD, git unavailable) is likewise `unknown`.
+ */
+function dirtyDocRestampVerdict(git, repoRoot, repoRelDocPath, onDiskTimestamp) {
+    const treeEntry = git(["ls-tree", "-z", "HEAD", "--", repoRelDocPath], repoRoot);
+    if (treeEntry === null)
+        return "unknown";
+    if (treeEntry === "")
+        return "restamped";
+    const committed = git(["show", `HEAD:${repoRelDocPath}`], repoRoot);
+    if (committed === null)
+        return "unknown";
+    const committedStamp = getTimestampIdentity(parseFrontmatter(committed).frontmatter.parsed);
+    return committedStamp !== onDiskTimestamp ? "restamped" : "not-restamped";
+}
 function epochToIso(epochSeconds) {
     return new Date(epochSeconds * 1000).toISOString();
 }
+/**
+ * Per-run cache of a doc's own REAL (committed) last-commit epoch, keyed by
+ * the `BundleContext` instance so `sources-fresh`'s doc-commit comparison
+ * and `sources-fresh-future`'s timestamp comparison -- both need the
+ * IDENTICAL (repoRoot, doc path) `getLastCommitEpoch` lookup for every doc
+ * in one `check` invocation -- share one `git log` process per doc instead
+ * of each rule spawning its own. Safe to key on the context object itself:
+ * a fresh `BundleContext` is built per `runCheck`/`loadBundle` call, so
+ * nothing reuses a stale cache entry across invocations, and the WeakMap
+ * lets the cache be garbage-collected with the context once a run is done.
+ *
+ * `getDocCommitEpochShared` below is the single place BOTH rules read a
+ * doc's commit epoch from, and it is itself built on
+ * `commitEpochWithDirtyAsNow`: under `--dirty-as-now`, a dirty doc's epoch
+ * is the shared virtual "now" instant instead of this real cache's answer,
+ * so `sources-fresh`'s co-commit rescue and `sources-fresh-future`'s
+ * timestamp comparison always see the identical (real-or-virtual) epoch
+ * for the same doc in the same `check` run.
+ */
+const docCommitEpochCache = new WeakMap();
+function getDocCommitEpochShared(ctx, git, repoRoot, repoRelDocPath) {
+    return commitEpochWithDirtyAsNow(ctx, git, repoRoot, repoRelDocPath, () => {
+        let cache = docCommitEpochCache.get(ctx);
+        if (!cache) {
+            cache = new Map();
+            docCommitEpochCache.set(ctx, cache);
+        }
+        const cached = cache.get(repoRelDocPath);
+        if (cached !== undefined)
+            return cached;
+        const epoch = getLastCommitEpoch(git, repoRoot, repoRelDocPath);
+        cache.set(repoRelDocPath, epoch);
+        return epoch;
+    });
+}
+/**
+ * Per-run cache (keyed by `BundleContext`, same pattern as
+ * `docCommitEpochCache` above) of whether `repoRoot` is a shallow clone
+ * (`git clone --depth <n>`), so `restampedByOwnLastCommit`'s root-commit
+ * shortcut spends at most ONE `git rev-parse --is-shallow-repository` for
+ * the whole `check` run, not one per doc. A failed git call (repoRoot
+ * somehow not a real git work tree after all) is treated as shallow: this
+ * function's only consumer only ever asks it to decide whether a commit
+ * with an empty parent list is trustworthy as a genuine root commit, and
+ * the file's standing rule is to answer "unknown" rather than invent
+ * either verdict when git itself cannot be asked -- so a failure here must
+ * NOT fall back to the previous "always trust it" behavior.
+ */
+const shallowRepoCache = new WeakMap();
+function isShallowRepoShared(ctx, git, repoRoot) {
+    const cached = shallowRepoCache.get(ctx);
+    if (cached !== undefined)
+        return cached;
+    const out = git(["rev-parse", "--is-shallow-repository"], repoRoot);
+    const isShallow = out === null ? true : out.trim() === "true";
+    shallowRepoCache.set(ctx, isShallow);
+    return isShallow;
+}
+/**
+ * Whether `doc`'s own last commit actually re-stamped it, decided by
+ * comparing the doc's PARSED FRONTMATTER `timestamp` VALUE at that commit
+ * against its value in the commit's FIRST PARENT. A doc created by that
+ * commit (or by a genuine root commit of an unshallow repository) counts as
+ * re-stamped: its stamp arrived with it. In a SHALLOW clone (`git clone
+ * --depth`), the doc's last commit can have an EMPTY parent list purely
+ * because that is where history was grafted off, not because it is really
+ * the repo's first commit -- `isShallowRepo` (checked lazily, only when a
+ * commit with no parents is actually seen) distinguishes the two, so a
+ * shallow checkout gets `unknown-shallow-root` there instead of an assumed
+ * `restamped`.
+ *
+ * This is what narrows `sources-fresh`'s co-commit staleness exception: a
+ * commit that merely happens to also touch the doc file (a typo fix, a
+ * repo-wide formatter run, a rename) without changing the stamp carries no
+ * verification claim and must NOT suppress staleness; only a commit that
+ * actually rewrote the stamp (or created the doc) does.
+ *
+ * WHY VALUES AND NOT DIFF TEXT. An earlier version of this check scanned
+ * `git log -1 -p -- <doc>` for a `^\+timestamp:` line. Scanning diff TEXT is
+ * wrong in three distinct, independently reachable ways, each of which this
+ * value comparison closes structurally rather than by another special case:
+ *
+ *  1. A fenced YAML EXAMPLE in the doc's BODY can contain an unindented
+ *     `timestamp:` line. Added in a commit that also changed a source, that
+ *     body line reads as a re-stamp and silently suppresses staleness --
+ *     exactly the review class this rule exists to close. Parsing
+ *     frontmatter cannot see a body line at all.
+ *  2. A RENAME (`git mv`) shows as `new file mode` under a single-path
+ *     `git log -p`, firing the "created counts as stamped" branch even
+ *     though the stamp never moved. The rename-aware lookup below reads the
+ *     doc's real previous path instead.
+ *  3. A MERGE commit prints NO patch at all under `git log -p` (git's
+ *     default combined-diff suppression), so a genuine re-stamp landing on
+ *     a `refs/pull/N/merge` ref -- the ref CI actually checks out -- became
+ *     an invisible false-positive STALE. Both trees are perfectly readable
+ *     via `git show`, merge or not.
+ *
+ * Its limits, stated rather than hidden: this answers "did the value
+ * change", never "is the new value right". A hand-typed or backdated stamp
+ * still counts as a re-stamp (`sources-fresh-future` is the rule that
+ * catches an implausible value), and comparing against only the FIRST parent
+ * means a merge that takes its doc content wholesale from the second parent
+ * is judged against the first-parent baseline, which is the same baseline
+ * the PR under review is measured against.
+ *
+ * Spends at most 4 git processes and returns early before most of them: 1
+ * for the commit + parents, 1 for the rename-aware name-status lookup
+ * (skipped for a root commit), and 2 blob reads (skipped when the doc was
+ * created there). See the GIT PROCESS BUDGET comment in the rule above.
+ */
+function restampedByOwnLastCommit(git, repoRoot, repoRelDocPath, isShallowRepo) {
+    // %H then %P on its own line: the doc's last commit and its parent list in
+    // ONE process. Default history simplification is exactly what this needs
+    // for a single path: a merge whose result for that path differs from every
+    // parent (a conflict resolution, or a clean auto-merge of two sides that
+    // both touched the doc) IS returned here, while a merge that is TREESAME
+    // to a parent resolves to the real content-changing commit on that side.
+    const head = git(["log", "-1", "--format=%H%n%P", "--", repoRelDocPath], repoRoot);
+    if (head === null)
+        return "unknown";
+    const [sha, parentLine] = head.split("\n");
+    if (!sha)
+        return "unknown";
+    const parents = (parentLine ?? "").split(" ").filter((p) => p !== "");
+    // An empty parent list means "the doc arrived with the repo's first
+    // commit, stamp and all" ONLY in a genuinely unshallow repository. In a
+    // shallow clone (`git clone --depth`), the boundary commit git grafted
+    // the history onto also reports an empty parent list for every path
+    // touched at or before it -- indistinguishable from a real root commit
+    // by this lookup alone -- so trusting it there would let the shallow-clone
+    // shortcut fire unconditionally and silently suppress every doc's
+    // staleness. isShallowRepo() is checked here, not unconditionally at the
+    // top of this function, so an unshallow repo never pays for it.
+    if (parents.length === 0) {
+        return isShallowRepo() ? "unknown-shallow-root" : "restamped";
+    }
+    const firstParent = parents[0];
+    const previous = previousPathIn(git, repoRoot, firstParent, sha, repoRelDocPath);
+    if (previous.kind === "unknown")
+        return "unknown";
+    if (previous.kind === "created")
+        return "restamped";
+    const current = git(["show", `${sha}:${repoRelDocPath}`], repoRoot);
+    if (current === null)
+        return "unknown";
+    const before = git(["show", `${firstParent}:${previous.path}`], repoRoot);
+    if (before === null)
+        return "unknown";
+    const currentStamp = getTimestampIdentity(parseFrontmatter(current).frontmatter.parsed);
+    const beforeStamp = getTimestampIdentity(parseFrontmatter(before).frontmatter.parsed);
+    // Both undefined (no parseable stamp on either side) compares equal, i.e.
+    // "not re-stamped" -- nothing was rewritten, so nothing is claimed.
+    return currentStamp !== beforeStamp ? "restamped" : "not-restamped";
+}
+/**
+ * Where the doc lived in `parentSha`, so its previous revision can be read
+ * by that path: the same path (`same`), a different one it was renamed from
+ * (`renamed`), or nowhere at all because that commit created it (`created`).
+ *
+ * Runs `git diff-tree` WITHOUT a pathspec on purpose. A pathspec is applied
+ * BEFORE rename detection, so `git diff-tree -M --name-status <parent> <sha>
+ * -- <doc>` reports a renamed doc as `A` (verified against a real `git mv`
+ * fixture) -- which is precisely the false "created" verdict that made a
+ * rename suppress staleness. The unfiltered output is still bounded and
+ * small: `--name-status -r` prints one line per changed path, not any file
+ * content, and the raised RunGit output cap (see src/git.ts) covers even a
+ * repo-wide formatting commit.
+ *
+ * A doc that does not appear in the diff at all resolves to `same`: the two
+ * revisions are then byte-identical by construction, and the value
+ * comparison above resolves that to "not re-stamped" without a second code
+ * path deciding it.
+ *
+ * Runs with `-z` (NUL-delimited output) rather than the default newline/tab
+ * form, and for one reason that is NOT about newlines: git's default
+ * `--name-status` output C-QUOTES any path containing a non-ASCII byte
+ * (`core.quotePath` defaults to true) as a double-quoted string with octal
+ * escapes (e.g. `"bundle/\303\266lt.md"` for `bundle/ölt.md`), so a plain
+ * `repoRelDocPath` never string-equals that quoted form and a non-ASCII doc
+ * falls through every branch below to the `same` fallback, which returns
+ * the doc's real (unquoted) CURRENT path unchanged. When that commit was
+ * actually a rename or creation, the doc was NOT at that path in the first
+ * parent -- it lived under a different name there, or did not exist yet --
+ * so the caller's `git show <firstParent>:<that path>` blob read fails,
+ * turning a normal rename or creation into a false `not assessable`
+ * notice. `-z` prints every path verbatim,
+ * unquoted, regardless of `core.quotePath`, closing that structurally
+ * rather than by passing `-c core.quotePath=false` (which is a config
+ * override this rule would otherwise have to remember on every git
+ * invocation touching a path, not just this one).
+ */
+function previousPathIn(git, repoRoot, parentSha, sha, repoRelDocPath) {
+    const nameStatus = git([
+        "diff-tree",
+        "-r",
+        "-M",
+        "-z",
+        "--name-status",
+        "--no-commit-id",
+        parentSha,
+        sha,
+    ], repoRoot);
+    if (nameStatus === null)
+        return { kind: "unknown" };
+    // `-z` NUL-terminates every field (status, then path(s)) instead of the
+    // default "status TAB path NEWLINE" (or, for a rename/copy row, "status
+    // TAB old-path TAB new-path NEWLINE") -- including a trailing NUL after
+    // the very last field, which RunGit's `.trim()` does not strip (NUL is
+    // not whitespace), so the split below always drops one empty trailing
+    // token. A rename/copy row is 3 NUL-terminated tokens (status, old path,
+    // new path); every other row is 2 (status, path) -- read positionally,
+    // not by re-joining on a separator, since a path can itself legitimately
+    // contain a tab or newline once quoting is off.
+    const tokens = nameStatus.split("\0").filter((t) => t !== "");
+    let i = 0;
+    while (i < tokens.length) {
+        const status = tokens[i];
+        if (status.startsWith("R") || status.startsWith("C")) {
+            const oldPath = tokens[i + 1];
+            const newPath = tokens[i + 2];
+            i += 3;
+            if (newPath === repoRelDocPath) {
+                return { kind: "renamed", path: oldPath };
+            }
+            continue;
+        }
+        const p = tokens[i + 1];
+        i += 2;
+        if (p !== repoRelDocPath)
+            continue;
+        if (status.startsWith("A"))
+            return { kind: "created" };
+        return { kind: "same", path: repoRelDocPath };
+    }
+    return { kind: "same", path: repoRelDocPath };
+}
 //# sourceMappingURL=sources-fresh.js.map