okf-kit 0.8.0 → 0.10.0

package/dist/rules/prose-line-references.js

@@ -0,0 +1,512 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getValidSources } from "../util.js";
+import { CITATION_RE, computeExcludedSpans, computeFencedSpans, computeIndentedCodeSpans, computeParagraphStarts, computeTableRowSpans, hasParentSegment, paragraphStartFor, resolveCitation, } from "./citations-resolve.js";
+const RULE_ID = "prose-line-references";
+/**
+ * Opt-in (`--prose-line-references`, see `src/cli.ts`) checker for a prose
+ * line reference outside `citations-resolve`'s own `` `path:N` `` grammar:
+ * plain English shapes like "lines 496-498" or "generate-codex-config.ts
+ * lines 129-132" that name a line number but were never written as a
+ * backtick-delimited citation. `citations-resolve`'s `CITATION_RE` requires
+ * a literal `:` between the path and the digits, so these are structurally
+ * invisible to it -- a doc can be re-verified, re-stamped, and pass `check`
+ * with 0 findings while its prose line numbers are drifted, because nothing
+ * ever looked at them. See harness task ad66c43f (2026-08-30/31): both
+ * review rounds of that OKF sweep found wrong prose line numbers behind a
+ * fresh `citations-resolve`-clean stamp, and named the missing mechanical
+ * guard as the structural cause.
+ *
+ * Gated on `ctx.proseLineReferences` being present (see
+ * `ProseLineReferencesOptions` in `src/types.ts`), mirroring
+ * `citations-resolve`'s own `ctx.requireAnchors` discipline: a consumer
+ * that never passes `--prose-line-references` gets byte-identical `check`
+ * output to before this rule existed.
+ *
+ * Extraction grammar (conservative, see the README's "Prose line references
+ * (opt-in, `--prose-line-references`)" section for the authoritative
+ * writeup): `line N`, `lines N-M`, `lines N-M` with an en-dash/em-dash, and
+ * `lines N to M` (`LINE_REF_RE`). Deliberately NOT matched:
+ *   - `L N` / `L1` -- not observed in the corpus this rule was measured
+ *     against (see the CHANGELOG entry), and far more ambiguous than
+ *     `line N` (`L1` already means "review finding 1" in this package's own
+ *     README authoring convention for `citations-resolve`'s short-form
+ *     citations).
+ *   - `<file>:N` outside backticks -- already matched by
+ *     `citations-resolve`'s own `CITATION_RE`, which has no backtick
+ *     requirement (only its heading-section form does); duplicating it here
+ *     would double-report the same drift under two rule ids.
+ *   - a comma-separated list of several line numbers/ranges after one
+ *     `lines` keyword (e.g. "lines 178, 234, 265-268") -- only the first
+ *     number/range immediately after the keyword is extracted; the rest are
+ *     silently under-extracted rather than mis-parsed. Conservative
+ *     under-extraction, never mis-binding, matches this rule's "never
+ *     guess" posture throughout.
+ *   - a second, unlabelled range chained by "vs"/"and" onto an already-
+ *     extracted one (e.g. "lines 676-698 vs 564-591" only extracts
+ *     676-698) -- same reasoning.
+ *
+ * Exemptions for the LINE REFERENCE match itself (`line N`/`lines N-M`):
+ * fenced code blocks, indented code blocks, inline code spans, and
+ * Markdown table rows (`computeExcludedSpans`, reused verbatim from
+ * `citations-resolve`), the char span of any real `citations-resolve`
+ * full citation (`CITATION_RE`, reused verbatim) -- the latter mostly
+ * matters for a citation's own quoted string anchor, e.g.
+ * `` `path.md:10-20#"see line 5 above"` ``, whose anchor text could
+ * otherwise itself look like a bare prose line reference -- and an HTML
+ * comment span (`` <!-- see line 5 above --> ``, `computeHtmlCommentSpans`),
+ * which narrates a past state rather than citing current content. A
+ * reference is also skipped when its own line is a Markdown ATX heading
+ * (`## Line 3 semantics`, `isAtxHeadingAt`): a heading names a section
+ * about a line, not a citation to it. A URL with a port (`host:8080`), an
+ * ISO timestamp, and a version string (`1.2.3`) need no special-casing:
+ * `LINE_REF_RE` requires the literal word `line`/`lines` immediately
+ * before the digits, which none of those three shapes contain.
+ *
+ * A DIFFERENT, narrower exclusion set applies to FILE MENTION detection:
+ * fenced code, indented code, and table rows only -- deliberately NOT
+ * `computeInlineCodeSpans`. A bare backtick-wrapped filename
+ * (`` `src/cli.ts` ``) is the normal, encouraged way to name a file in this
+ * package's own prose (see the README's authoring guidance), so excluding
+ * inline code from mention detection the way `citations-resolve` excludes
+ * it from short-form citation matching would make this rule unable to bind
+ * against the overwhelming majority of real file mentions in a bundle.
+ *
+ * Binding rule (conservative, "never guess across paragraphs"): a bare line
+ * reference is bound to a "file mention" -- a path-like token
+ * (`FILE_MENTION_RE`, the same extension set `CITATION_RE` recognises) that
+ * resolves to a real file under the bundle's repo root via
+ * `resolveCitation`, reused verbatim from `citations-resolve` so file
+ * resolution follows the identical rules (frontmatter `sources` match,
+ * ancestor climb for a bare filename, repo-root-relative, doc-relative,
+ * "last full path mentioned", repo-wide basename search) rather than a
+ * second, drift-prone copy of that logic:
+ *   1. the nearest file mention in the same sentence, preceding first, then
+ *      following (`findSentenceStart`/`findSentenceEnd` locate the sentence
+ *      boundary around the reference; see there for the "what counts as a
+ *      sentence end" heuristic);
+ *   2. otherwise the nearest PRECEDING file mention in the same paragraph
+ *      (`computeParagraphStarts`/`paragraphStartFor`, reused verbatim);
+ *   3. otherwise `unresolvable` -- never guessed, never silently bound to
+ *      the wrong file.
+ * A candidate file-mention token that itself fails to resolve (a stray
+ * path-like word that is not a real file) or resolves ambiguously (more
+ * than one real file shares its basename) is NOT skipped in favor of a
+ * farther candidate: "nearest wins" is taken literally, so the outcome is
+ * `unresolvable`/`ambiguous` rather than quietly falling through to a
+ * second-nearest mention that was not what the prose actually named.
+ *
+ * Reserved citing docs (`index.md`/`log.md`, `doc.isReserved`) are skipped
+ * entirely, the same carve-out `citations-resolve` already gives them: an
+ * append-only narrative journal routinely narrates historical line-number
+ * deltas as prose about the past, not live citations against current
+ * content.
+ *
+ * Findings, one per extracted reference (`--prose-line-references-strict`
+ * can add a second, see below): `unresolvable` and `ambiguous` are
+ * `notice`-severity (real false-positive risk: "line" occurs in ordinary
+ * English -- "in line with", "product line" -- with no adjacent number
+ * often enough that "no file mention nearby" is weaker evidence of drift
+ * than a resolved-but-wrong reference); `out-of-bounds` (covers both
+ * range-exceeds-file and an inverted range) and `blank-start-line` are
+ * `warning`-severity, mirroring `citations-resolve`'s own "a wrong
+ * start/target is strong drift evidence" posture once a reference DOES
+ * resolve to a single real file.
+ *
+ * Strict mode (`ProseLineReferencesOptions.strict`, `--prose-line-
+ * references-strict`, ignored unless `--prose-line-references` is also
+ * passed -- same "ignored unless the base flag is set" discipline
+ * `--require-anchors-allow` already uses): flags EVERY extracted reference,
+ * regardless of whether it also resolved cleanly, with its own
+ * `warning`-severity `prose-line-reference-not-anchored` finding and a
+ * fixed remedy: lift it into a backtick `path:N-M` citation (so
+ * `citations-resolve` can verify it going forward), or de-precise it to a
+ * symbol name. This is intentionally additive, not a replacement for the
+ * base checks above: a drifted reference under strict mode gets both its
+ * `out-of-bounds`/etc. finding AND the policy finding, since both facts are
+ * independently true of it.
+ */
+// Same extension set CITATION_RE recognises -- see the "Extraction
+// grammar" doc block above for why this rule does not invent a second one.
+// The trailing `(?!\w)` matters here in a way it does not for CITATION_RE:
+// CITATION_RE requires a literal `:` immediately after the extension
+// group, which already forces the regex engine to backtrack past a
+// shorter alternative that is a prefix of a longer one (`js` is a prefix
+// of `json`) until the full, correct extension matches. FILE_MENTION_RE
+// has nothing after the extension group to force that backtracking, so
+// without this lookahead a real `foo.json` mention would silently match
+// as `foo.js` (the `on` left dangling) -- `(?!\w)` rejects that truncated
+// match outright, so the engine backtracks to the real extension instead.
+const FILE_MENTION_RE = /[\w./-]+\.(?:ts|js|mjs|md|yml|yaml|json)(?!\w)/g;
+// "line N" / "lines N-M" / "lines N-M" (en-/em-dash) / "lines N to M".
+// Deliberately requires the literal keyword right before the digits -- see
+// the "Extraction grammar" doc block above for every shape this leaves out
+// on purpose. The leading `(?<![\w-])` (rather than a plain `\b`) rejects a
+// match starting right after a hyphen: `\b` alone is a word/non-word
+// transition, and `-` is a non-word character, so `\b` still fires between
+// the `-` and the `l` of "in-line 999" / "multi-line 999" /
+// "command-line 999" -- all compound words meaning "an in-place edit" or
+// "the shell", not a citation to line 999. Node 20 supports lookbehind
+// assertions.
+const LINE_REF_RE = /(?<![\w-])[Ll]ines?\s+(\d+)(?:\s*(?:-|–|—|to)\s*(\d+))?\b/g;
+// An HTML comment span (`<!-- ... -->`), excluded from LINE_REF_RE
+// extraction: a comment narrating a past state ("<!-- see line 5 above
+// for the earlier draft -->") is not a live prose citation any more than
+// a fenced code block's own example is. Scoped to prose-line-references'
+// own extraction only (not folded into citations-resolve's shared
+// `computeExcludedSpans`), since that function's own callers were not
+// asked to change behavior here.
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+function computeHtmlCommentSpans(content) {
+    const spans = [];
+    const re = new RegExp(HTML_COMMENT_RE.source, HTML_COMMENT_RE.flags);
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        spans.push([m.index, m.index + m[0].length]);
+    }
+    return spans;
+}
+/**
+ * True when the line containing `index` is a Markdown ATX heading
+ * (`# Heading` through `###### Heading`, up to 3 leading spaces per
+ * CommonMark). A heading like "## Line 3 semantics" names a section about
+ * line 3, not a citation to it -- excluded from LINE_REF_RE extraction the
+ * same way a fenced code block's example is.
+ */
+function isAtxHeadingAt(content, index) {
+    const lineStart = content.lastIndexOf("\n", index - 1) + 1;
+    let lineEnd = content.indexOf("\n", index);
+    if (lineEnd === -1)
+        lineEnd = content.length;
+    const line = content.slice(lineStart, lineEnd);
+    return /^ {0,3}#{1,6}(?:\s|$)/.test(line);
+}
+function isWithinAnySpan(index, spans) {
+    return spans.some(([start, end]) => index >= start && index < end);
+}
+/** 1-based line number of `index` within `content`. */
+function lineNumberAt(content, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < content.length; i++) {
+        if (content[i] === "\n")
+            line++;
+    }
+    return line;
+}
+// Duplicated from citations-resolve's own splitLines (not exported: this
+// rule needs the identical "trailing newline does not count as an extra
+// blank final line" semantics so a file's line count agrees with what
+// citations-resolve would report for the same file, but the function
+// itself is a two-line utility not worth threading a new export for).
+function splitLines(content) {
+    const lines = content.split("\n");
+    if (lines.length > 0 &&
+        lines[lines.length - 1] === "" &&
+        content.endsWith("\n")) {
+        lines.pop();
+    }
+    return lines;
+}
+/**
+ * Every `FILE_MENTION_RE` match in `content` outside `mentionExcludedSpans`
+ * (fenced/indented code, table rows -- see the "Exemptions" doc block
+ * above for why inline code is deliberately NOT one of these), skipping a
+ * leading-`/` (out-of-scope, same as `citations-resolve`'s
+ * `citedPath.startsWith("/")`) or `..`-segment (`hasParentSegment`, same as
+ * `citations-resolve`'s `path-traversal-rejected`) token outright -- such a
+ * token is never a candidate binding target, so it is left out of the
+ * mention list entirely rather than being found nearest and then reported
+ * unresolvable.
+ */
+function collectFileMentions(content, mentionExcludedSpans) {
+    const mentions = [];
+    const re = new RegExp(FILE_MENTION_RE.source, FILE_MENTION_RE.flags);
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        if (isWithinAnySpan(m.index, mentionExcludedSpans))
+            continue;
+        const text = m[0];
+        if (text.startsWith("/") || hasParentSegment(text))
+            continue;
+        mentions.push({ index: m.index, end: m.index + text.length, text });
+    }
+    return mentions;
+}
+/**
+ * True when `content[i]` is a sentence-ending `.`/`!`/`?` NOT inside
+ * `protectedSpans` (fenced/inline code, table rows, or a real citation's
+ * own span) and followed, after any run of repeated terminal punctuation,
+ * by whitespace and then either the end of the content or a character that
+ * plausibly starts a new sentence (uppercase letter, digit, backtick,
+ * quote, or open paren/bracket). This is a heuristic, not a real sentence
+ * grammar -- it exists only to scope the "same sentence" binding
+ * preference (see the "Binding rule" doc block above); getting it wrong in
+ * either direction degrades to the paragraph-level fallback, never to a
+ * silently wrong bind, since a reference with no in-sentence mention still
+ * falls through to `nearestPrecedingMentionInParagraph`. A filename's own
+ * internal dot (`generate-codex-config.ts`) never needs a dedicated
+ * exemption here: it is never followed by whitespace (the extension
+ * letters come right after), so the "followed by whitespace" requirement
+ * below already disqualifies it on its own.
+ */
+function isSentenceEnderAt(content, i, protectedSpans) {
+    const ch = content[i];
+    if (ch !== "." && ch !== "!" && ch !== "?")
+        return false;
+    if (isWithinAnySpan(i, protectedSpans))
+        return false;
+    let j = i + 1;
+    while (content[j] === "." || content[j] === "!" || content[j] === "?")
+        j++;
+    const after = content[j];
+    if (after !== undefined && !/\s/.test(after))
+        return false;
+    let k = j;
+    while (k < content.length && /\s/.test(content[k]))
+        k++;
+    const nextChar = content[k];
+    if (nextChar === undefined)
+        return true;
+    return /[A-Z0-9`"'([]/.test(nextChar);
+}
+/** Nearest sentence-ender at or after `paragraphStart` and before `idx`, or `paragraphStart` when none exists. */
+function findSentenceStart(content, idx, paragraphStart, protectedSpans) {
+    for (let i = idx - 1; i >= paragraphStart; i--) {
+        if (isSentenceEnderAt(content, i, protectedSpans))
+            return i + 1;
+    }
+    return paragraphStart;
+}
+/** Nearest sentence-ender at or after `idx` and before `paragraphEnd`, or `paragraphEnd` when none exists. */
+function findSentenceEnd(content, idx, paragraphEnd, protectedSpans) {
+    for (let i = idx; i < paragraphEnd; i++) {
+        if (isSentenceEnderAt(content, i, protectedSpans))
+            return i + 1;
+    }
+    return paragraphEnd;
+}
+/** Offset one past the paragraph starting at `paragraphStart` (see computeParagraphStarts), or `contentLength` for the last paragraph. */
+function paragraphEndFor(starts, paragraphStart, contentLength) {
+    for (const s of starts) {
+        if (s > paragraphStart)
+            return s;
+    }
+    return contentLength;
+}
+/**
+ * The binding target for a line reference at `idx`: the nearest file
+ * mention in the same sentence (preceding first, then following), or
+ * `null` when the sentence has none at all -- see the "Binding rule" doc
+ * block above.
+ */
+function nearestMentionInSentence(mentions, idx, sentenceStart, sentenceEnd) {
+    let preceding = null;
+    for (const mention of mentions) {
+        if (mention.index >= sentenceStart && mention.end <= idx) {
+            if (!preceding || mention.index > preceding.index)
+                preceding = mention;
+        }
+    }
+    if (preceding)
+        return preceding;
+    let following = null;
+    for (const mention of mentions) {
+        if (mention.index >= idx && mention.end <= sentenceEnd) {
+            if (!following || mention.index < following.index)
+                following = mention;
+        }
+    }
+    return following;
+}
+/** Nearest preceding file mention anywhere in the same paragraph -- the fallback once the same-sentence search finds nothing. */
+function nearestPrecedingMentionInParagraph(mentions, idx, paragraphStart) {
+    let best = null;
+    for (const mention of mentions) {
+        if (mention.index >= paragraphStart && mention.end <= idx) {
+            if (!best || mention.index > best.index)
+                best = mention;
+        }
+    }
+    return best;
+}
+/**
+ * Base drift checks against an already-resolved single target: an
+ * inverted or file-exceeding range, a start line below 1, or a blank
+ * start line (`blank-start-line`) -- one problem reported, `out-of-bounds`
+ * checked first since a blank-line check on an out-of-range line number
+ * is meaningless. A start line below 1 is checked before the file-length
+ * comparison and reported as its own `out-of-bounds` message, rather than
+ * falling through to `lines[startLine - 1]` (`line 0` would otherwise
+ * index `lines[-1]`, i.e. `undefined`, and read as a blank start line
+ * instead of the invalid line number it actually is). Returns `null` (no
+ * `Problem`, not "unreadable") when the
+ * target cannot be read at all; the caller folds that into `unresolvable`
+ * (see the "Findings" doc block above: a fifth, `unreadable-target`
+ * reason was deliberately not added, to keep to the four reasons this
+ * rule's design settled on).
+ */
+function checkTarget(resolvedPath, startLine, endLine) {
+    let content;
+    try {
+        content = fs.readFileSync(resolvedPath, "utf8");
+    }
+    catch {
+        return "unreadable";
+    }
+    const lines = splitLines(content);
+    const last = endLine ?? startLine;
+    if (endLine !== null && endLine < startLine) {
+        return {
+            reason: "out-of-bounds",
+            message: `range end (${endLine}) is before its start (${startLine})`,
+        };
+    }
+    if (startLine < 1) {
+        return {
+            reason: "out-of-bounds",
+            message: `start line (${startLine}) is not a valid line number`,
+        };
+    }
+    if (startLine > lines.length || last > lines.length) {
+        return {
+            reason: "out-of-bounds",
+            message: `citation exceeds file length (${lines.length} line(s))`,
+        };
+    }
+    const startText = (lines[startLine - 1] ?? "").trim();
+    if (startText === "") {
+        return { reason: "blank-start-line", message: "start line is blank" };
+    }
+    return null;
+}
+/** Canonical hyphen-ranged rendering, e.g. `lines 2-3` -- distinct from a
+ * doc's own matched text, which may use an en-dash, an em-dash, or "to".
+ * See `pushFinding` below for why this is kept separate from what gets
+ * quoted in a finding's message. */
+function formatRef(startLine, endLine) {
+    return endLine !== null
+        ? `lines ${startLine}-${endLine}`
+        : `line ${startLine}`;
+}
+/**
+ * `matchedText` is the doc's own matched text verbatim (`m[0]`, e.g.
+ * `lines 2–3` with its original en-dash, or `lines 2` for a comma-separated
+ * list like "lines 2, 99, 100-200" where only the first number is
+ * extracted -- see the "Extraction grammar" doc block above). Quoting this
+ * rather than a re-rendering means a reader can always find the exact text
+ * the doc actually contains. `normalizedRef` is `formatRef`'s canonical
+ * hyphen-ranged rendering of the same startLine/endLine; it is folded into
+ * the message body (not the leading quote) only when it differs from
+ * `matchedText`, so the overwhelming common case (a doc already using a
+ * plain hyphen) produces the identical message this rule always has.
+ */
+function pushFinding(findings, file, matchedText, normalizedRef, docLine, reason, message, severity, detail) {
+    const normalizedNote = matchedText === normalizedRef ? "" : ` (normalized \`${normalizedRef}\`)`;
+    findings.push({
+        ruleId: RULE_ID,
+        severity,
+        file,
+        message: `\`${matchedText}\`${normalizedNote} (doc line ${docLine}): ${message} [${reason}]`,
+        ...(detail ? { detail } : {}),
+    });
+}
+function scanDoc(cache, root, bundleDir, doc, options) {
+    if (doc.isReserved)
+        return [];
+    const findings = [];
+    const content = doc.raw;
+    const sources = getValidSources(doc.frontmatter.parsed) ?? [];
+    const docAbsPath = path.join(bundleDir, doc.relPath);
+    const excludedSpans = computeExcludedSpans(content);
+    const citationSpans = [];
+    const citationRe = new RegExp(CITATION_RE.source, "g");
+    let cm;
+    while ((cm = citationRe.exec(content)) !== null) {
+        citationSpans.push([cm.index, cm.index + cm[0].length]);
+    }
+    const htmlCommentSpans = computeHtmlCommentSpans(content);
+    const protectedSpans = [
+        ...excludedSpans,
+        ...citationSpans,
+        ...htmlCommentSpans,
+    ];
+    // A narrower exclusion set for file-mention detection: fenced/indented
+    // code and table rows, but NOT inline code -- see the "Exemptions" doc
+    // block above.
+    const mentionExcludedSpans = [
+        ...computeFencedSpans(content),
+        ...computeIndentedCodeSpans(content),
+        ...computeTableRowSpans(content),
+    ];
+    const fileMentions = collectFileMentions(content, mentionExcludedSpans);
+    const paragraphStarts = computeParagraphStarts(content);
+    const re = new RegExp(LINE_REF_RE.source, LINE_REF_RE.flags);
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        if (isWithinAnySpan(m.index, protectedSpans))
+            continue;
+        if (isAtxHeadingAt(content, m.index))
+            continue;
+        const startLine = Number(m[1]);
+        const endLine = m[2] !== undefined ? Number(m[2]) : null;
+        const matchedText = m[0];
+        const normalizedRef = formatRef(startLine, endLine);
+        const docLine = lineNumberAt(content, m.index);
+        const paragraphStart = paragraphStartFor(paragraphStarts, m.index);
+        const paragraphEnd = paragraphEndFor(paragraphStarts, paragraphStart, content.length);
+        const sentenceStart = findSentenceStart(content, m.index, paragraphStart, protectedSpans);
+        const sentenceEnd = findSentenceEnd(content, m.index, paragraphEnd, protectedSpans);
+        const mention = nearestMentionInSentence(fileMentions, m.index, sentenceStart, sentenceEnd) ??
+            nearestPrecedingMentionInParagraph(fileMentions, m.index, paragraphStart);
+        let boundFile = null;
+        if (!mention) {
+            pushFinding(findings, doc.relPath, matchedText, normalizedRef, docLine, "unresolvable", "no file mention could be bound to this prose line reference", "notice");
+        }
+        else {
+            const resolution = resolveCitation(cache, root, docAbsPath, content, sources, mention.text, mention.index);
+            if (!resolution || "skip" in resolution) {
+                pushFinding(findings, doc.relPath, matchedText, normalizedRef, docLine, "unresolvable", `nearest file mention \`${mention.text}\` does not resolve to a real file`, "notice");
+            }
+            else if ("ambiguous" in resolution) {
+                pushFinding(findings, doc.relPath, matchedText, normalizedRef, docLine, "ambiguous", `file mention \`${mention.text}\` resolves to more than one file, not evaluated`, "notice", `candidates: ${resolution.candidates.join(", ")}`);
+            }
+            else {
+                boundFile = path.relative(root, resolution.path);
+                const problem = checkTarget(resolution.path, startLine, endLine);
+                if (problem === "unreadable") {
+                    pushFinding(findings, doc.relPath, matchedText, normalizedRef, docLine, "unresolvable", `bound target \`${boundFile}\` exists but could not be read`, "notice");
+                }
+                else if (problem) {
+                    pushFinding(findings, doc.relPath, matchedText, normalizedRef, docLine, problem.reason, `bound to \`${boundFile}\`, ${problem.message}`, "warning", `resolvedTo: ${boundFile}`);
+                }
+            }
+        }
+        if (options.strict) {
+            const boundSuffix = boundFile ? ` (bound to \`${boundFile}\`)` : "";
+            pushFinding(findings, doc.relPath, matchedText, normalizedRef, docLine, "prose-line-reference-not-anchored", `prose line reference; lift into a backtick anchored citation or de-precise to a symbol name${boundSuffix}`, "warning");
+        }
+    }
+    return findings;
+}
+export const proseLineReferencesRule = {
+    id: RULE_ID,
+    description: "(opt-in, `--prose-line-references`) Prose-embedded line references outside citations-resolve's backtick grammar (`line N`, `lines N-M`, `lines N to M`) are bound to the nearest named file mention (same sentence, then same paragraph) and flagged when the bound reference is out of bounds, blank, or unresolvable/ambiguous. `--prose-line-references-strict` additionally flags every such reference as a formatting policy violation, resolved or not.",
+    run(ctx) {
+        if (!ctx.proseLineReferences)
+            return [];
+        if (!ctx.repoRoot) {
+            return [
+                {
+                    ruleId: RULE_ID,
+                    severity: "notice",
+                    file: "",
+                    message: "prose line reference resolution skipped: not inside a git work tree",
+                },
+            ];
+        }
+        const root = ctx.repoRoot;
+        const cache = new Map();
+        return ctx.docs.flatMap((doc) => scanDoc(cache, root, ctx.bundleDir, doc, ctx.proseLineReferences));
+    },
+};
+//# sourceMappingURL=prose-line-references.js.map

package/dist/rules/prose-line-references.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prose-line-references.js","sourceRoot":"","sources":["../../src/rules/prose-line-references.ts"],"names":[],"mappings":"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"}

package/dist/rules/sources-fresh.d.ts

@@ -1,2 +1,37 @@
 import type { Rule } from "../types.js";
+/**
+ * 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 declare const DEFAULT_FUTURE_SKEW_SECONDS = 600;
 export declare const sourcesFreshRule: Rule;
+/**
+ * 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 declare const sourcesFreshFutureRule: Rule;