okf-kit 0.9.0 → 0.10.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",
@@ -51,15 +62,36 @@ 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: 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.
+            const repoRelDocPath = toRepoRelDocPath(repoRoot, ctx.bundleDir, doc);
+            const docCommitEpochFor = () => getDocCommitEpochShared(ctx, git, repoRoot, repoRelDocPath);
+            let restampMemo;
+            const restampFor = () => (restampMemo ??= restampedByOwnLastCommit(git, repoRoot, repoRelDocPath, () => isShallowRepoShared(ctx, git, repoRoot)));
+            // 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 +108,35 @@ 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.
+                // Doc committed 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) 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.
                 if (isStale) {
                     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 +152,102 @@ 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": 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.
+ */
+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 +255,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);
@@ -116,4 +270,230 @@ function getLastCommitEpoch(git, repoRoot, source) {
 function epochToIso(epochSeconds) {
     return new Date(epochSeconds * 1000).toISOString();
 }
+/**
+ * Per-run cache of a doc's own 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.
+ */
+const docCommitEpochCache = new WeakMap();
+function getDocCommitEpochShared(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

package/dist/rules/sources-fresh.js.map

@@ -1 +1 @@
-{"version":3,"file":"sources-fresh.js","sourceRoot":"","sources":["../../src/rules/sources-fresh.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sources-fresh.js","sourceRoot":"","sources":["../../src/rules/sources-fresh.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,MAAM,IAAI,aAAa,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAC;AASpB,MAAM,OAAO,GAAG,eAAe,CAAC;AAChC,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAE/C,MAAM,CAAC,MAAM,gBAAgB,GAAS;IACpC,EAAE,EAAE,OAAO;IACX,WAAW,EACT,6vBAA6vB;IAC/vB,GAAG,CAAC,GAAG;QACL,MAAM,QAAQ,GAAc,EAAE,CAAC;QAE/B,MAAM,eAAe,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QAChD,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,QAAQ,CAAC;QAElD,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAClB,sEAAsE;YACtE,mEAAmE;YACnE,qEAAqE;YACrE,oEAAoE;YACpE,mEAAmE;YACnE,oEAAoE;YACpE,oBAAoB;YACpB,QAAQ,CAAC,IAAI,CAAC;gBACZ,MAAM,EAAE,OAAO;gBACf,QAAQ,EAAE,QAAQ;gBAClB,IAAI,EAAE,EAAE;gBACR,OAAO,EAAE,+CAA+C;aACzD,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;QAC9B,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,IAAI,aAAa,CAAC;QAExC,qEAAqE;QACrE,6DAA6D;QAC7D,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAyB,CAAC;QAC1D,MAAM,cAAc,GAAG,CAAC,MAAc,EAAiB,EAAE;YACvD,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC5C,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,MAAM,CAAC;YACxC,MAAM,KAAK,GAAG,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;YACxD,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YACpC,OAAO,KAAK,CAAC;QACf,CAAC,CAAC;QAEF,KAAK,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,eAAe,EAAE,CAAC;YAC/C,MAAM,cAAc,GAAG,iBAAiB,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YACjE,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;gBACjC,QAAQ,CAAC,IAAI,CAAC;oBACZ,MAAM,EAAE,OAAO;oBACf,QAAQ,EAAE,QAAQ;oBAClB,IAAI,EAAE,GAAG,CAAC,OAAO;oBACjB,OAAO,EAAE,8CAA8C;iBACxD,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,sEAAsE;YACtE,qEAAqE;YACrE,qEAAqE;YACrE,qEAAqE;YACrE,sEAAsE;YACtE,uEAAuE;YACvE,mEAAmE;YACnE,mEAAmE;YACnE,qEAAqE;YACrE,eAAe;YACf,EAAE;YACF,8DAA8D;YAC9D,sEAAsE;YACtE,yEAAyE;YACzE,kEAAkE;YAClE,qEAAqE;YACrE,kEAAkE;YAClE,kEAAkE;YAClE,8DAA8D;YAC9D,iDAAiD;YACjD,6DAA6D;YAC7D,gEAAgE;YAChE,kEAAkE;YAClE,kDAAkD;YAClD,MAAM,cAAc,GAAG,gBAAgB,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YACtE,MAAM,iBAAiB,GAAG,GAAkB,EAAE,CAC5C,uBAAuB,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC;YAC9D,IAAI,WAAuC,CAAC;YAC5C,MAAM,UAAU,GAAG,GAAmB,EAAE,CACtC,CAAC,WAAW,KAAK,wBAAwB,CACvC,GAAG,EACH,QAAQ,EACR,cAAc,EACd,GAAG,EAAE,CAAC,mBAAmB,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,CAC9C,CAAC,CAAC;YACL,mEAAmE;YACnE,kDAAkD;YAClD,IAAI,qBAAqB,GAAG,KAAK,CAAC;YAElC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,mEAAmE;gBACnE,oCAAoC;gBACpC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;oBAAE,SAAS;gBAE1D,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;gBAC3C,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;oBACzB,QAAQ,CAAC,IAAI,CAAC;wBACZ,MAAM,EAAE,OAAO;wBACf,QAAQ,EAAE,QAAQ;wBAClB,IAAI,EAAE,GAAG,CAAC,OAAO;wBACjB,OAAO,EAAE,0CAA0C,MAAM,IAAI;qBAC9D,CAAC,CAAC;oBACH,SAAS;gBACX,CAAC;gBAED,IAAI,OAAO,GAAG,WAAW,GAAG,cAAc,CAAC;gBAE3C,8DAA8D;gBAC9D,kEAAkE;gBAClE,oEAAoE;gBACpE,mEAAmE;gBACnE,kEAAkE;gBAClE,kEAAkE;gBAClE,sDAAsD;gBACtD,IAAI,OAAO,EAAE,CAAC;oBACZ,MAAM,cAAc,GAAG,iBAAiB,EAAE,CAAC;oBAC3C,IAAI,cAAc,KAAK,IAAI,IAAI,cAAc,IAAI,WAAW,EAAE,CAAC;wBAC7D,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;wBAC7B,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;4BAC5B,OAAO,GAAG,KAAK,CAAC;wBAClB,CAAC;6BAAM,IACL,OAAO,KAAK,SAAS;4BACrB,OAAO,KAAK,sBAAsB,EAClC,CAAC;4BACD,IAAI,CAAC,qBAAqB,EAAE,CAAC;gCAC3B,qBAAqB,GAAG,IAAI,CAAC;gCAC7B,QAAQ,CAAC,IAAI,CAAC;oCACZ,MAAM,EAAE,OAAO;oCACf,QAAQ,EAAE,QAAQ;oCAClB,IAAI,EAAE,GAAG,CAAC,OAAO;oCACjB,OAAO,EACL,OAAO,KAAK,sBAAsB;wCAChC,CAAC,CAAC,gQAAgQ;wCAClQ,CAAC,CAAC,gHAAgH;iCACvH,CAAC,CAAC;4BACL,CAAC;4BACD,SAAS;wBACX,CAAC;oBACH,CAAC;gBACH,CAAC;gBAED,IAAI,OAAO,EAAE,CAAC;oBACZ,QAAQ,CAAC,IAAI,CAAC;wBACZ,MAAM,EAAE,OAAO;wBACf,QAAQ,EAAE,SAAS;wBACnB,IAAI,EAAE,GAAG,CAAC,OAAO;wBACjB,OAAO,EAAE,YAAY,MAAM,cAAc,UAAU,CAAC,WAAW,CAAC,wBAAwB,UAAU,CAAC,cAAc,CAAC,EAAE;qBACrH,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAS;IAC1C,EAAE,EAAE,cAAc;IAClB,WAAW,EACT,ylBAAylB;IAC3lB,GAAG,CAAC,GAAG;QACL,MAAM,QAAQ,GAAc,EAAE,CAAC;QAE/B,MAAM,eAAe,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;QAChD,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,QAAQ,CAAC;QAClD,IAAI,CAAC,GAAG,CAAC,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAEnC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;QAC9B,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,IAAI,aAAa,CAAC;QACxC,MAAM,WAAW,GACf,GAAG,CAAC,0BAA0B,IAAI,2BAA2B,CAAC;QAEhE,KAAK,MAAM,EAAE,GAAG,EAAE,IAAI,eAAe,EAAE,CAAC;YACtC,MAAM,cAAc,GAAG,iBAAiB,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YACjE,IAAI,cAAc,KAAK,SAAS;gBAAE,SAAS;YAE3C,qEAAqE;YACrE,iEAAiE;YACjE,4DAA4D;YAC5D,oEAAoE;YACpE,8DAA8D;YAC9D,6DAA6D;YAC7D,kEAAkE;YAClE,qEAAqE;YACrE,gBAAgB;YAChB,MAAM,YAAY,GAAG,qBAAqB,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YACnE,IAAI,YAAY,KAAK,SAAS,IAAI,CAAC,gBAAgB,CAAC,YAAY,CAAC,EAAE,CAAC;gBAClE,QAAQ,CAAC,IAAI,CAAC;oBACZ,MAAM,EAAE,cAAc;oBACtB,QAAQ,EAAE,QAAQ;oBAClB,IAAI,EAAE,GAAG,CAAC,OAAO;oBACjB,OAAO,EACL,kIAAkI;iBACrI,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,MAAM,cAAc,GAAG,gBAAgB,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YACtE,MAAM,cAAc,GAAG,uBAAuB,CAC5C,GAAG,EACH,GAAG,EACH,QAAQ,EACR,cAAc,CACf,CAAC;YACF,IAAI,cAAc,KAAK,IAAI;gBAAE,SAAS;YAEtC,IAAI,cAAc,GAAG,cAAc,GAAG,WAAW,EAAE,CAAC;gBAClD,QAAQ,CAAC,IAAI,CAAC;oBACZ,MAAM,EAAE,cAAc;oBACtB,QAAQ,EAAE,SAAS;oBACnB,IAAI,EAAE,GAAG,CAAC,OAAO;oBACjB,OAAO,EAAE,+BAA+B,UAAU,CAAC,cAAc,CAAC,uCAAuC,UAAU,CAAC,cAAc,CAAC,oBAAoB,WAAW,IAAI;iBACvK,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC;AAEF;;;;;GAKG;AACH,SAAS,kBAAkB,CACzB,GAAkB;IAElB,OAAO,GAAG,CAAC,IAAI;SACZ,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;SACzE,MAAM,CACL,CAAC,KAAK,EAAkD,EAAE,CACxD,KAAK,CAAC,OAAO,KAAK,SAAS,CAC9B,CAAC;AACN,CAAC;AAED,yGAAyG;AACzG,SAAS,gBAAgB,CACvB,QAAgB,EAChB,SAAiB,EACjB,GAAc;IAEd,OAAO,IAAI;SACR,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;SACrD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;SACf,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,kBAAkB,CACzB,GAAW,EACX,QAAgB,EAChB,MAAc;IAEd,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC;IACvE,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;AAC5C,CAAC;AAED,SAAS,UAAU,CAAC,YAAoB;IACtC,OAAO,IAAI,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;AACrD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,mBAAmB,GAAG,IAAI,OAAO,EAGpC,CAAC;AAEJ,SAAS,uBAAuB,CAC9B,GAAkB,EAClB,GAAW,EACX,QAAgB,EAChB,cAAsB;IAEtB,IAAI,KAAK,GAAG,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;QAClB,mBAAmB,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACzC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,MAAM,KAAK,GAAG,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC;IAChE,KAAK,CAAC,GAAG,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACjC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,gBAAgB,GAAG,IAAI,OAAO,EAA0B,CAAC;AAE/D,SAAS,mBAAmB,CAC1B,GAAkB,EAClB,GAAW,EACX,QAAgB;IAEhB,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,yBAAyB,CAAC,EAAE,QAAQ,CAAC,CAAC;IACpE,MAAM,SAAS,GAAG,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,MAAM,CAAC;IAC9D,gBAAgB,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACrC,OAAO,SAAS,CAAC;AACnB,CAAC;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,SAAS,wBAAwB,CAC/B,GAAW,EACX,QAAgB,EAChB,cAAsB,EACtB,aAA4B;IAE5B,2EAA2E;IAC3E,yEAAyE;IACzE,2EAA2E;IAC3E,yEAAyE;IACzE,yEAAyE;IACzE,yEAAyE;IACzE,MAAM,IAAI,GAAG,GAAG,CACd,CAAC,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,cAAc,CAAC,EACtD,QAAQ,CACT,CAAC;IACF,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACpC,MAAM,CAAC,GAAG,EAAE,UAAU,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,MAAM,OAAO,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IACtE,oEAAoE;IACpE,wEAAwE;IACxE,uEAAuE;IACvE,oEAAoE;IACpE,uEAAuE;IACvE,2EAA2E;IAC3E,kEAAkE;IAClE,yEAAyE;IACzE,gEAAgE;IAChE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,aAAa,EAAE,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,WAAW,CAAC;IAChE,CAAC;IACD,MAAM,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE/B,MAAM,QAAQ,GAAG,cAAc,CAC7B,GAAG,EACH,QAAQ,EACR,WAAW,EACX,GAAG,EACH,cAAc,CACf,CAAC;IACF,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAClD,IAAI,QAAQ,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IAEpD,MAAM,OAAO,GAAG,GAAG,CAAC,CAAC,MAAM,EAAE,GAAG,GAAG,IAAI,cAAc,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;IACpE,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACvC,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,EAAE,GAAG,WAAW,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC1E,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAEtC,MAAM,YAAY,GAAG,oBAAoB,CACvC,gBAAgB,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,MAAM,CAC7C,CAAC;IACF,MAAM,WAAW,GAAG,oBAAoB,CACtC,gBAAgB,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,MAAM,CAC5C,CAAC;IACF,0EAA0E;IAC1E,oEAAoE;IACpE,OAAO,YAAY,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,eAAe,CAAC;AACtE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,SAAS,cAAc,CACrB,GAAW,EACX,QAAgB,EAChB,SAAiB,EACjB,GAAW,EACX,cAAsB;IAKtB,MAAM,UAAU,GAAG,GAAG,CACpB;QACE,WAAW;QACX,IAAI;QACJ,IAAI;QACJ,IAAI;QACJ,eAAe;QACf,gBAAgB;QAChB,SAAS;QACT,GAAG;KACJ,EACD,QAAQ,CACT,CAAC;IACF,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAEpD,wEAAwE;IACxE,wEAAwE;IACxE,wEAAwE;IACxE,uEAAuE;IACvE,sEAAsE;IACtE,yEAAyE;IACzE,uEAAuE;IACvE,yEAAyE;IACzE,gDAAgD;IAChD,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;IAC9D,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrD,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9B,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC9B,CAAC,IAAI,CAAC,CAAC;YACP,IAAI,OAAO,KAAK,cAAc,EAAE,CAAC;gBAC/B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;YAC5C,CAAC;YACD,SAAS;QACX,CAAC;QACD,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACxB,CAAC,IAAI,CAAC,CAAC;QACP,IAAI,CAAC,KAAK,cAAc;YAAE,SAAS;QACnC,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACvD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IAChD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;AAChD,CAAC"}

package/dist/types.d.ts

@@ -72,6 +72,13 @@ export interface BundleContext {
     requireAnchors?: RequireAnchorsOptions;
     /** See `ProseLineReferencesOptions`. Undefined when `--prose-line-references` was not passed. */
     proseLineReferences?: ProseLineReferencesOptions;
+    /**
+     * Clock-skew allowance (seconds) for `sources-fresh-future` (see
+     * `--future-skew-minutes` in `src/cli.ts` and `DEFAULT_FUTURE_SKEW_SECONDS`
+     * in `src/rules/sources-fresh.ts`). Undefined when `--future-skew-minutes`
+     * was not passed, in which case the rule applies its own default.
+     */
+    freshnessFutureSkewSeconds?: number;
 }
 export interface Rule {
     id: string;

package/dist/util.d.ts

@@ -21,3 +21,55 @@ export declare function getValidSources(parsed: unknown): string[] | undefined;
  * degrade to the no-valid-timestamp notice.
  */
 export declare function getTimestampEpoch(parsed: unknown): number | undefined;
+/**
+ * The frontmatter `timestamp`'s raw string form, or undefined when it is
+ * absent, blank, or not a string -- notably, a native `Date` instance (see
+ * `getTimestampEpoch`'s doc comment) returns undefined here too, since a
+ * `Date`'s `getTime()` is always UTC-unambiguous and carries none of the
+ * local-timezone risk `hasUtcDesignator` exists to catch. Used only by
+ * `sources-fresh-future`'s UTC-designator gate; `sources-fresh` itself has
+ * no need for the raw string, only the resolved epoch.
+ */
+export declare function getRawTimestampString(parsed: unknown): string | undefined;
+/**
+ * Whether an ISO-ish timestamp string carries an explicit UTC designator
+ * (`Z`) or a numeric UTC offset (`+02:00`, `-0500`) at its end. A timestamp
+ * with neither ("2026-01-01T00:00:00", "2026-01-01 00:00:00") parses in
+ * the machine's LOCAL timezone under `Date.parse`, which would make
+ * `sources-fresh-future`'s clock-skew comparison swing by hours depending
+ * on which machine runs the check -- not usable for a check whose default
+ * allowance is only 10 minutes. A numeric offset, unlike a bare local
+ * time, is unambiguous: `Date.parse`/`Date#getTime()` already normalizes
+ * it to a real UTC instant, so no extra conversion is needed here beyond
+ * recognizing it as present. `sources-fresh`'s own thresholds are in
+ * days, wide enough that this ambiguity doesn't practically matter there,
+ * so this helper is deliberately NOT applied to that rule's comparison.
+ */
+export declare function hasUtcDesignator(raw: string): boolean;
+/**
+ * A canonical identity string for the frontmatter `timestamp` VALUE, or
+ * undefined when the key is absent, blank, or not a scalar this tool
+ * understands. Two docs (or two revisions of one doc) are "stamped the same"
+ * iff this returns the same value for both.
+ *
+ * Used by `sources-fresh` to decide whether a commit actually re-stamped a
+ * doc, by comparing the doc's frontmatter at that commit against its
+ * frontmatter in the commit's first parent. Comparing VALUES, not diff text,
+ * is what makes the test immune to the three shapes a diff-text scan gets
+ * wrong: a `timestamp:` line inside a fenced YAML example in the doc BODY (it
+ * is not the frontmatter key, so it never reaches this function at all), a
+ * rename (the two revisions are read by path, not from a diff header), and a
+ * merge commit (whose combined-diff output is empty while its trees are
+ * perfectly readable).
+ *
+ * The `date:`/`string:` prefixes keep the two YAML shapes distinguishable: a
+ * `!!timestamp`-tagged scalar resolving to a native `Date` and a plain string
+ * are different frontmatter, so rewriting one into the other counts as a
+ * re-stamp rather than silently comparing equal. Deliberately NOT normalized
+ * to an epoch: this is an identity test ("did the value change"), not a
+ * chronological one, so re-writing `2026-01-01T00:00:00Z` as
+ * `2026-01-01T00:00:00+00:00` counts as a re-stamp -- the author touched the
+ * stamp. Whether the new value is CORRECT is a separate question this
+ * function deliberately does not answer (see the README's known limitations).
+ */
+export declare function getTimestampIdentity(parsed: unknown): string | undefined;

package/dist/util.js

@@ -47,4 +47,76 @@ export function getTimestampEpoch(parsed) {
         return undefined;
     return Math.floor(ms / 1000);
 }
+/**
+ * The frontmatter `timestamp`'s raw string form, or undefined when it is
+ * absent, blank, or not a string -- notably, a native `Date` instance (see
+ * `getTimestampEpoch`'s doc comment) returns undefined here too, since a
+ * `Date`'s `getTime()` is always UTC-unambiguous and carries none of the
+ * local-timezone risk `hasUtcDesignator` exists to catch. Used only by
+ * `sources-fresh-future`'s UTC-designator gate; `sources-fresh` itself has
+ * no need for the raw string, only the resolved epoch.
+ */
+export function getRawTimestampString(parsed) {
+    if (!isRecord(parsed))
+        return undefined;
+    const timestamp = parsed.timestamp;
+    if (typeof timestamp !== "string" || timestamp.trim() === "")
+        return undefined;
+    return timestamp;
+}
+/**
+ * Whether an ISO-ish timestamp string carries an explicit UTC designator
+ * (`Z`) or a numeric UTC offset (`+02:00`, `-0500`) at its end. A timestamp
+ * with neither ("2026-01-01T00:00:00", "2026-01-01 00:00:00") parses in
+ * the machine's LOCAL timezone under `Date.parse`, which would make
+ * `sources-fresh-future`'s clock-skew comparison swing by hours depending
+ * on which machine runs the check -- not usable for a check whose default
+ * allowance is only 10 minutes. A numeric offset, unlike a bare local
+ * time, is unambiguous: `Date.parse`/`Date#getTime()` already normalizes
+ * it to a real UTC instant, so no extra conversion is needed here beyond
+ * recognizing it as present. `sources-fresh`'s own thresholds are in
+ * days, wide enough that this ambiguity doesn't practically matter there,
+ * so this helper is deliberately NOT applied to that rule's comparison.
+ */
+export function hasUtcDesignator(raw) {
+    return /(?:Z|[+-]\d{2}:?\d{2})$/i.test(raw.trim());
+}
+/**
+ * A canonical identity string for the frontmatter `timestamp` VALUE, or
+ * undefined when the key is absent, blank, or not a scalar this tool
+ * understands. Two docs (or two revisions of one doc) are "stamped the same"
+ * iff this returns the same value for both.
+ *
+ * Used by `sources-fresh` to decide whether a commit actually re-stamped a
+ * doc, by comparing the doc's frontmatter at that commit against its
+ * frontmatter in the commit's first parent. Comparing VALUES, not diff text,
+ * is what makes the test immune to the three shapes a diff-text scan gets
+ * wrong: a `timestamp:` line inside a fenced YAML example in the doc BODY (it
+ * is not the frontmatter key, so it never reaches this function at all), a
+ * rename (the two revisions are read by path, not from a diff header), and a
+ * merge commit (whose combined-diff output is empty while its trees are
+ * perfectly readable).
+ *
+ * The `date:`/`string:` prefixes keep the two YAML shapes distinguishable: a
+ * `!!timestamp`-tagged scalar resolving to a native `Date` and a plain string
+ * are different frontmatter, so rewriting one into the other counts as a
+ * re-stamp rather than silently comparing equal. Deliberately NOT normalized
+ * to an epoch: this is an identity test ("did the value change"), not a
+ * chronological one, so re-writing `2026-01-01T00:00:00Z` as
+ * `2026-01-01T00:00:00+00:00` counts as a re-stamp -- the author touched the
+ * stamp. Whether the new value is CORRECT is a separate question this
+ * function deliberately does not answer (see the README's known limitations).
+ */
+export function getTimestampIdentity(parsed) {
+    if (!isRecord(parsed))
+        return undefined;
+    const timestamp = parsed.timestamp;
+    if (timestamp instanceof Date) {
+        const ms = timestamp.getTime();
+        return Number.isNaN(ms) ? undefined : `date:${ms}`;
+    }
+    if (typeof timestamp !== "string" || timestamp.trim() === "")
+        return undefined;
+    return `string:${timestamp.trim()}`;
+}
 //# sourceMappingURL=util.js.map