okf-kit 0.5.0 → 0.7.0

package/dist/rules/citations-resolve.js

@@ -130,7 +130,256 @@ const RULE_ID = "citations-resolve";
  * this rule emits a single bundle-level notice, matching `sources-fresh`'s
  * "not inside a git work tree" posture.
  */
-const CITATION_RE = /([\w./-]+\.(?:ts|js|mjs|md|yml|yaml|json)):(\d+)(?:-(\d+))?/g;
+/**
+ * Anchored citations. A full citation (never a continuation or short-form
+ * atom -- see below) may carry an anchor directly after its range,
+ * `path:N-M#anchor`, e.g. `` `CHANGELOG.md:50-144#0.24.0` ``. Motivation: a
+ * CHANGELOG.md grows by insertion at the TOP (newest entry first), so every
+ * later entry's absolute line numbers shift on every release; the checks
+ * above (missing-file, inverted-range, range-exceeds-file, blank-start-line,
+ * closing-brace-start-line) are structurally blind to a citation that
+ * shifted a whole release section over and now lands, still non-blank and
+ * in-bounds, inside the WRONG section -- a citation `CHANGELOG.md:738-748`
+ * meant for the "0.7.4" entry that quietly now points at "0.7.3" prose is
+ * exactly as green as before the shift. An anchor closes that gap by
+ * pinning the citation to a piece of the target's own structure/content that
+ * the line-shift does not preserve automatically.
+ *
+ * Two anchor kinds, told apart by the raw anchor text (group 4 of
+ * `CITATION_RE`, see `parseAnchor`):
+ *   - **Heading form** (bare, unquoted, e.g. `#0.24.0` or `#[0.24.0]`):
+ *     the target's nearest *enclosing* Markdown heading -- see
+ *     `findEnclosingHeading` -- must contain the anchor text, and no
+ *     heading of the same or shallower level may start before the range's
+ *     end line (i.e. the heading must actually enclose the whole range, not
+ *     merely precede its start -- see `checkAnchor`). Deliberately capped at
+ *     `ANCHOR_HEADING_MAX_LEVEL` (2): a Keep-a-Changelog CHANGELOG.md nests
+ *     `## [x.y.z]` release headings around identically-named `### Added` /
+ *     `### Changed` / `### Fixed` subsections repeated in every release;
+ *     treating "nearest heading of any level" as the anchor target would
+ *     make a heading anchor nearly useless here (matching the wrong
+ *     release's own "Changed" subsection just as readily as the right
+ *     one's), so subsection headings are transparent to this check and only
+ *     level-1/level-2 headings are ever considered.
+ *   - **String form** (double-quoted, e.g. `#"reproduction requirement"`):
+ *     the anchor text must occur, verbatim, on at least one line of the
+ *     cited range itself (`checkAnchor`'s string branch) -- "occurs inside
+ *     it" rather than "encloses it". No heading structure required, so this
+ *     form also works against a non-Markdown target (`.ts`/`.js`/...) where
+ *     "nearest enclosing heading" has no meaning.
+ * An anchor mismatch is its own drift finding (`anchor-heading-not-found`,
+ * `anchor-heading-mismatch`, `anchor-heading-does-not-enclose`,
+ * `anchor-not-found-in-range`), checked only once the base start/range
+ * checks (blank-start-line, closing-brace-start-line, inverted-range,
+ * range-exceeds-file) already came back clean -- same "one problem per
+ * citation, base checks first" pattern `checkShortFormTarget` already uses
+ * for the block-boundary check. Every one of these four messages names the
+ * anchor text itself, and an anchored full citation's own finding label
+ * (`path:N-M#anchor`, see `formatAnchorForLabel`) carries the anchor too --
+ * without both, two citations to the identical range with different
+ * anchors would be indistinguishable in the output.
+ *
+ * A `#` that immediately follows a citation's range but does not parse as
+ * either anchor form at all (unbalanced quotes, a backtick inside a quoted
+ * anchor, or nothing after the `#`) is its own separate, `notice`-severity
+ * finding, `anchor-malformed` (see `scanDoc`'s main matching loop): the
+ * citation is still checked exactly as an anchorless one would be
+ * (backward compatible, see below), but silently checking it anchorless
+ * when the `#` right there looks like a typo'd anchor attempt would defeat
+ * the entire point of writing one -- a single misplaced character would
+ * quietly turn the very check the anchor was written for back off.
+ *
+ * Backward compatible by construction: the `#anchor` suffix is optional in
+ * `CITATION_RE`, so an existing anchorless citation matches exactly as
+ * before and is checked exactly as before (this section adds a new check
+ * gated on the anchor being present, it does not change any existing one).
+ * Deliberately scoped to full citations only: a continuation (`` `:M` ``
+ * etc.) or a short-form `:N-M` never carries its own path, so there is
+ * nowhere natural to hang an anchor on one without inventing a second,
+ * detached syntax; the migration this rule was built for (CHANGELOG.md
+ * citations) is written as full citations throughout the corpus it targets.
+ *
+ * Rejected alternatives (see the PR/CHANGELOG for the fuller writeup):
+ *   - Embedding the literal heading markup itself, e.g.
+ *     `` `CHANGELOG.md:50-144#"## [0.24.0]"` `` -- verbatim-correct but
+ *     `#`, `[`, `]`, and the space all need quoting/escaping right next to
+ *     the citation, which reads worse in prose than a bare version token
+ *     and gains nothing the structural heading-enclosure check does not
+ *     already provide from the shorter form.
+ *   - A detached anchor, e.g. a trailing parenthetical `(see "0.24.0")`
+ *     elsewhere in the sentence -- unparseable without a second, separate
+ *     grammar next to the existing continuation/short-form machinery, and
+ *     easy to leave behind (or attach to the wrong citation) when a
+ *     sentence is edited later.
+ *   - A named-capture-group slug matching `sources-fresh`'s YAML shape --
+ *     rejected because it would require a second citation site (frontmatter
+ *     plus prose) to stay in sync, the exact class of drift this rule
+ *     exists to catch.
+ */
+const ANCHOR_HEADING_MAX_LEVEL = 2;
+const MD_HEADING_RE = /^(#{1,6})\s+(.*)$/;
+/**
+ * Renders a parsed `Anchor` back to the short form used to disambiguate a
+ * finding's citation label (see the `citation` variable in `scanDoc`'s main
+ * loop): `#text` for a heading anchor (already bracket-stripped by
+ * `parseAnchor`), `#"text"` for a string anchor. Two citations to the same
+ * range with different anchors would otherwise be indistinguishable in the
+ * output -- see the "Anchored citations" doc block above.
+ */
+function formatAnchorForLabel(anchor) {
+    return anchor.kind === "string" ? `#"${anchor.text}"` : `#${anchor.text}`;
+}
+/**
+ * Parses `CITATION_RE`'s optional 4th capture group (the raw anchor text,
+ * including its surrounding quotes or brackets if any) into an `Anchor`, or
+ * `null` when the citation carried no `#anchor` suffix at all. A
+ * double-quoted raw value (`"..."`) is the string form, text taken verbatim
+ * between the quotes; anything else is the heading form, with a single
+ * wrapping `[...]` stripped (so `#[0.24.0]` and `#0.24.0` compare
+ * identically) -- compared as a plain substring against the heading's own
+ * raw text (`findEnclosingHeading`'s `text`, itself never stripped of any
+ * brackets it happens to carry), not a stripped copy of it -- see the
+ * "Anchored citations" doc block above.
+ */
+function parseAnchor(raw) {
+    if (!raw)
+        return null;
+    if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
+        return { kind: "string", text: raw.slice(1, -1) };
+    }
+    const text = raw.startsWith("[") && raw.endsWith("]") ? raw.slice(1, -1) : raw;
+    return { kind: "heading", text };
+}
+/**
+ * The single fence state machine every fence-aware consumer in this file
+ * derives from: one forward pass over `lines`, replaying the same
+ * open/close logic (a line matching `MD_FENCE_DELIM_RE` opens a fence when
+ * none is open, a line starting with the *same* marker closes it) that
+ * `computeFencedSpans`, `computeFencedLineIndices`, and `isFenceOpeningLine`
+ * each used to implement as their own, independently-maintained copy --
+ * nothing enforced the three staying in agreement with each other. An
+ * unterminated fence (no matching close before the end of `lines`) is
+ * reflected by every remaining line coming back `fenced: true` -- each line
+ * is marked while the scan is still inside the open fence, so no separate
+ * post-loop fixup is needed the way the three original copies each had.
+ * State at line `i` never depends on any line after `i`, so a caller that
+ * only needs one line's state (see `isFenceOpeningLine`) can safely ignore
+ * the rest of the array without re-deriving the logic itself.
+ */
+function scanFenceLines(lines) {
+    const states = [];
+    let fenceMarker;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = (lines[i] ?? "").trim();
+        if (!fenceMarker && MD_FENCE_DELIM_RE.test(trimmed)) {
+            fenceMarker = trimmed.slice(0, 3);
+            states.push({ fenced: true, opensFence: true, closesFence: false });
+        }
+        else if (fenceMarker && trimmed.startsWith(fenceMarker)) {
+            states.push({ fenced: true, opensFence: false, closesFence: true });
+            fenceMarker = undefined;
+        }
+        else {
+            states.push({
+                fenced: fenceMarker !== undefined,
+                opensFence: false,
+                closesFence: false,
+            });
+        }
+    }
+    return states;
+}
+/**
+ * 0-based line indices that fall inside a fenced code block (```` ``` ````
+ * or `~~~`, optionally with a trailing language tag), delimiters included --
+ * the target-side twin of `computeFencedSpans` above, which does the same
+ * job for the *citing* doc's short-form matching. Derived from
+ * `scanFenceLines` (see there). Anchor heading-search needs its own copy
+ * because it works from an already-split `lines` array (see
+ * `checkFullTarget`), not the raw `content` string `computeFencedSpans`
+ * takes, and because it must ignore a target's `# not a heading` sitting
+ * inside a fenced example exactly the same way a citing doc's own fences
+ * are already ignored for short-form matching -- without this, a `#`-led
+ * comment line inside e.g. a fenced shell example in the target is
+ * indistinguishable from a real Markdown heading to `MD_HEADING_RE`, and
+ * both `findEnclosingHeading` (picks the wrong "nearest" heading) and the
+ * enclosure walk in `checkAnchor` (treats it as a section boundary) would
+ * misfire on it.
+ */
+function computeFencedLineIndices(lines) {
+    const fenced = new Set();
+    scanFenceLines(lines).forEach((state, i) => {
+        if (state.fenced)
+            fenced.add(i);
+    });
+    return fenced;
+}
+/**
+ * Nearest Markdown heading at or before `startLine` (1-based), considering
+ * only heading levels up to `ANCHOR_HEADING_MAX_LEVEL` -- see the "Anchored
+ * citations" doc block above for why subsection headings are transparent to
+ * this search. `fencedLines` (see `computeFencedLineIndices`) excludes any
+ * line inside a fenced code block from matching, so a `#`-led comment
+ * inside a fenced example is never mistaken for a heading. Returns `null`
+ * when no such heading precedes `startLine` at all (e.g. the citation
+ * lands above the target's first release heading).
+ */
+function findEnclosingHeading(lines, startLine, fencedLines) {
+    for (let i = startLine - 1; i >= 0; i--) {
+        if (fencedLines.has(i))
+            continue;
+        const m = (lines[i] ?? "").match(MD_HEADING_RE);
+        if (m && m[1].length <= ANCHOR_HEADING_MAX_LEVEL) {
+            return { level: m[1].length, text: m[2].trim(), lineNo: i + 1 };
+        }
+    }
+    return null;
+}
+/**
+ * Checks an anchored full citation's anchor against its already-resolved,
+ * already-range-checked target -- see the "Anchored citations" doc block
+ * above for the two forms' semantics. `endLine` is the citation's end line,
+ * or its start line for a single-line citation (a size-1 range).
+ */
+function checkAnchor(anchor, startLine, endLine, lines) {
+    if (anchor.kind === "string") {
+        for (let i = startLine - 1; i <= endLine - 1 && i < lines.length; i++) {
+            if ((lines[i] ?? "").includes(anchor.text))
+                return null;
+        }
+        return {
+            rule: "anchor-not-found-in-range",
+            message: `anchor "${anchor.text}" does not occur in the cited range (${startLine}-${endLine})`,
+        };
+    }
+    const fencedLines = computeFencedLineIndices(lines);
+    const heading = findEnclosingHeading(lines, startLine, fencedLines);
+    if (!heading) {
+        return {
+            rule: "anchor-heading-not-found",
+            message: `no heading (level <= ${ANCHOR_HEADING_MAX_LEVEL}) precedes line ${startLine} to anchor "${anchor.text}" against; use a string anchor (#"...") instead against a target with no heading structure`,
+        };
+    }
+    if (!heading.text.includes(anchor.text)) {
+        return {
+            rule: "anchor-heading-mismatch",
+            message: `nearest enclosing heading ("${heading.text}") does not contain anchor "${anchor.text}"`,
+        };
+    }
+    for (let i = heading.lineNo; i <= endLine - 1; i++) {
+        if (fencedLines.has(i))
+            continue;
+        const m = (lines[i] ?? "").match(MD_HEADING_RE);
+        if (m && m[1].length <= heading.level) {
+            return {
+                rule: "anchor-heading-does-not-enclose",
+                message: `range extends past the section enclosing anchor "${anchor.text}" (next heading "${m[2].trim()}" at line ${i + 1})`,
+            };
+        }
+    }
+    return null;
+}
+const CITATION_RE = /([\w./-]+\.(?:ts|js|mjs|md|yml|yaml|json)):(\d+)(?:-(\d+))?(?:#(\[?\w(?:[\w.-]*\w)?\]?|"[^"\n`]*"))?/g;
 // Continuation citation forms (see the "Continuation citations" doc block
 // above). Each requires the backtick delimiter as part of the match so it
 // can never overlap a CITATION_RE match: a full citation's regex match
@@ -141,6 +390,28 @@ const CONT_DASH_RE = /[-–]`(\d+)`/g;
 const CONT_PAREN_RE = /\(`(\d+)`\)/g;
 const CLOSING_ONLY_EXTS = new Set(["ts", "js", "mjs", "yml", "yaml", "json"]);
 const CLOSING_BRACE_RE = /^[)\]}][;,]?$/;
+// Short-form (paragraph-bound) citation form, see the "Short-form
+// citations" doc block below. Requires an explicit N-M range: a bare single
+// number (`:5`) is not matched -- see that doc block for why. Only the
+// colon form is collected; a bare `(N-M)` is never a short-form citation
+// candidate at all -- see the same doc block for why the paren form was
+// dropped rather than gated.
+const SHORT_FORM_COLON_RE = /:(\d+)-(\d+)/g;
+// Test-file block-boundary check (see checkRangeBoundary): a citation's
+// range into a `.test.ts`/`.spec.ts` (or `.js`/`.mjs` equivalent) target
+// must start on a describe(/it( head line and end on its matching closing
+// `});` line.
+const TEST_FILE_RE = /\.(test|spec)\.(ts|js|mjs)$/i;
+const TEST_HEAD_LINE_RE = /^\s*(?:describe|it)\s*\(/;
+const TEST_CLOSING_LINE_RE = /^\s*\}\)\s*;\s*$/;
+// Markdown block-boundary check (see checkRangeBoundary): a range boundary
+// line that is nothing but a bracket (open or close), optionally with a
+// trailing `,`/`;`, is always a drift signal. A bare code-fence delimiter is
+// its own, separate signal (see MD_FENCE_DELIM_RE): unlike a bracket, a
+// fence line is sometimes the deliberately-correct start of a citation (see
+// checkRangeBoundary's markdown branch for the opening-fence exception).
+const MD_BARE_BRACKET_RE = /^(?:[)\]}][;,]?|[[({])$/;
+const MD_FENCE_DELIM_RE = /^(?:`{3,}\S*|~{3,}\S*)$/;
 const EXCLUDED_DIRS = new Set([
     "node_modules",
     ".git",
@@ -367,14 +638,15 @@ function readTarget(resolvedPath) {
         };
     }
 }
-function checkTarget(citedPath, startLine, endLine, resolvedPath) {
-    const read = readTarget(resolvedPath);
-    if ("rule" in read)
-        return read;
-    const content = read.content;
-    const lines = splitLines(content);
-    const lineCount = lines.length;
-    const bound = checkRangeBound(startLine, endLine, lineCount);
+/**
+ * The non-I/O half of checkTarget: every check that only needs the
+ * target's already-read `lines`, not the filesystem. Split out so a caller
+ * that needs a second, different check against the same target (see
+ * checkShortFormTarget) can read the file once and reuse `lines` for both,
+ * instead of checkTarget re-reading it internally.
+ */
+function checkTargetLines(citedPath, startLine, endLine, lines) {
+    const bound = checkRangeBound(startLine, endLine, lines.length);
     if (bound)
         return bound;
     const startText = lines[startLine - 1] ?? "";
@@ -391,6 +663,34 @@ function checkTarget(citedPath, startLine, endLine, resolvedPath) {
     }
     return null;
 }
+function checkTarget(citedPath, startLine, endLine, resolvedPath) {
+    const read = readTarget(resolvedPath);
+    if ("rule" in read)
+        return read;
+    return checkTargetLines(citedPath, startLine, endLine, splitLines(read.content));
+}
+/**
+ * A full citation's complete check: `checkTargetLines`'s existing checks
+ * (unreadable-target, inverted-range, range-exceeds-file, blank-start-line,
+ * closing-brace-start-line), plus, only when those all pass and the
+ * citation carried an anchor, the anchor check above (see the "Anchored
+ * citations" doc block). Reads the resolved target once, mirroring
+ * `checkShortFormTarget`'s reasoning for the block-boundary check. Anchors
+ * are full-citation-only (see that doc block for why), so `checkTarget`
+ * itself is untouched and still used as-is for a cont-fresh atom.
+ */
+function checkFullTarget(citedPath, startLine, endLine, resolvedPath, anchor) {
+    const read = readTarget(resolvedPath);
+    if ("rule" in read)
+        return read;
+    const lines = splitLines(read.content);
+    const base = checkTargetLines(citedPath, startLine, endLine, lines);
+    if (base)
+        return base;
+    if (!anchor)
+        return null;
+    return checkAnchor(anchor, startLine, endLine ?? startLine, lines);
+}
 // A cont-ext atom only ever extends the *end* of a range whose start line
 // was already fully checked (blank / closing-brace) when it was cited as
 // its own full citation or cont-fresh atom -- re-running checkTarget here
@@ -405,6 +705,161 @@ function checkRangeBoundOnly(startLine, endLine, resolvedPath) {
     const lineCount = splitLines(read.content).length;
     return checkRangeBound(startLine, endLine, lineCount);
 }
+function isTestFile(citedPath) {
+    return TEST_FILE_RE.test(citedPath);
+}
+/**
+ * True when the line at `lines[lineIndex]` is a fence delimiter
+ * (```` ``` ```` or `~~~`, optionally with a trailing language tag) that
+ * *opens* a fenced code block, as opposed to closing one -- determined by
+ * replaying the same open/close state machine `stripFencedCode`-style
+ * scanners use from the top of the document, not by the line's own text
+ * (a bare closing fence and an untagged opening fence are lexically
+ * identical). Used by checkRangeBoundary's markdown branch: citing a
+ * fenced block starting at its own opening fence line is the natural,
+ * correct way to cite it, so that specific case is exempted from the
+ * fence-as-drift-signal check (see there). Derived from `scanFenceLines`
+ * (see there); state at `lineIndex` never depends on any line after it, so
+ * scanning the whole array and reading one index back is equivalent to (and
+ * replaces) the original's own up-to-`lineIndex`-only replay.
+ */
+function isFenceOpeningLine(lines, lineIndex) {
+    return scanFenceLines(lines)[lineIndex]?.opensFence ?? false;
+}
+/**
+ * True when `lines[endLineIndex]` is the closing delimiter that matches
+ * the *opening* fence at `lines[startLineIndex]` (the caller must already
+ * have confirmed the start line is a genuine opening fence, via
+ * isFenceOpeningLine, before calling this) -- the first line after the
+ * opener whose trimmed text starts with the same fence marker. Used by
+ * checkRangeBoundary's markdown branch to also exempt a range's END from
+ * the fence-as-drift-signal check when the range legitimately cites a
+ * whole fenced code block from its own opening delimiter to its own
+ * closing delimiter: the natural, correct way to cite such a block, not
+ * drift, the same reasoning the start-side exception already applies.
+ */
+function isMatchingFenceClosingLine(lines, startLineIndex, endLineIndex) {
+    const fenceMarker = (lines[startLineIndex] ?? "").trim().slice(0, 3);
+    for (let i = startLineIndex + 1; i < lines.length; i++) {
+        const trimmed = (lines[i] ?? "").trim();
+        if (trimmed.startsWith(fenceMarker)) {
+            return i === endLineIndex;
+        }
+    }
+    return false;
+}
+/**
+ * Additional block-boundary check for a short-form citation's range (see
+ * the "Short-form citations" doc block below), layered on top of
+ * checkTarget's existing per-start-line checks via checkShortFormTarget.
+ * Deliberately scoped to short-form citations only, not wired into
+ * checkTarget/checkRangeBoundOnly (the full/continuation citation paths):
+ * applying it there too was tried first and rejected -- the real bundle
+ * this rule was built against has legitimate full citations into test
+ * files that cite a couple of arbitrary lines (e.g. two lines of a shared
+ * regex definition), not a describe/it block, and flagging those as newly
+ * broken would have regressed the existing 0-warning baseline. Short-form
+ * citations are the demonstrated motivating case (a paragraph naming a
+ * test file once, then citing several of its describe/it blocks by bare
+ * range alone), so the check is scoped to exactly that mechanism.
+ *
+ * Test-file targets (`.test.ts`/`.spec.ts`, and their `.js`/`.mjs`
+ * equivalents): the range must start on a `describe(`/`it(` head line and
+ * end on a matching closing `});` line. Severity split, by evidence
+ * strength: a wrong START line is a
+ * *warning* (`test-range-start-not-head`) -- the range beginning somewhere
+ * other than a block head is strong drift evidence. A range whose start IS
+ * correct but whose END is not the matching `});` is only a *notice*
+ * (`test-range-end-not-closing`): this also matches a deliberate partial
+ * citation (citing from a block's head to partway through it), which is not
+ * drift. The start is checked first and returned alone, matching
+ * checkTarget's existing single-problem-per-citation pattern (never both at
+ * once).
+ *
+ * Markdown targets: mechanical verification of "is this still the same
+ * block" is far less reliable for prose than for TS/JS brace structure, so
+ * this is a notice, not a warning (see this rule's own risk note on
+ * markdown false positives). The range's start or end line landing on a
+ * bare bracket (MD_BARE_BRACKET_RE) is always a heads-up that the boundary
+ * likely drifted onto structural punctuation rather than real prose. A bare
+ * code-fence delimiter (MD_FENCE_DELIM_RE) is also always a drift signal at
+ * either boundary, with two exceptions carved out for the one legitimate
+ * way to cite a whole fenced code block by its own delimiters: the START is
+ * exempted when that line is itself a genuine *opening* fence (see
+ * isFenceOpeningLine), and, only when the start already qualified for that
+ * exemption, the END is exempted when it is that same fence's matching
+ * *closing* delimiter (see isMatchingFenceClosingLine) -- citing a fenced
+ * block from its own opening delimiter through its own closing delimiter is
+ * the natural, correct way to cite it, not drift.
+ */
+function checkRangeBoundary(citedPath, startLine, endLine, lines) {
+    if (isTestFile(citedPath)) {
+        const startText = lines[startLine - 1] ?? "";
+        if (!TEST_HEAD_LINE_RE.test(startText)) {
+            return {
+                rule: "test-range-start-not-head",
+                message: `range start is not a "describe(" or "it(" head line ("${startText.trim()}")`,
+            };
+        }
+        const endText = lines[endLine - 1] ?? "";
+        if (!TEST_CLOSING_LINE_RE.test(endText)) {
+            return {
+                rule: "test-range-end-not-closing",
+                message: `range end is not a matching closing "});" line ("${endText.trim()}")`,
+                severity: "notice",
+            };
+        }
+        return null;
+    }
+    if (citedPath.toLowerCase().endsWith(".md")) {
+        const startTrim = (lines[startLine - 1] ?? "").trim();
+        const startIsFence = MD_FENCE_DELIM_RE.test(startTrim);
+        if (MD_BARE_BRACKET_RE.test(startTrim) ||
+            (startIsFence && !isFenceOpeningLine(lines, startLine - 1))) {
+            return {
+                rule: "markdown-range-boundary-bracket-or-fence",
+                message: `range start is a bare bracket/fence line ("${startTrim}")`,
+                severity: "notice",
+            };
+        }
+        const endTrim = (lines[endLine - 1] ?? "").trim();
+        const endIsFence = MD_FENCE_DELIM_RE.test(endTrim);
+        const endIsMatchingClose = startIsFence &&
+            endIsFence &&
+            isMatchingFenceClosingLine(lines, startLine - 1, endLine - 1);
+        if (MD_BARE_BRACKET_RE.test(endTrim) ||
+            (endIsFence && !endIsMatchingClose)) {
+            return {
+                rule: "markdown-range-boundary-bracket-or-fence",
+                message: `range end is a bare bracket/fence line ("${endTrim}")`,
+                severity: "notice",
+            };
+        }
+        return null;
+    }
+    return null;
+}
+/**
+ * A short-form citation's full check: checkTarget's existing checks
+ * (unreadable-target, inverted-range, range-exceeds-file, blank-start-line,
+ * closing-brace-start-line), plus, only when those all pass, the
+ * test-file/markdown block-boundary check above (see checkRangeBoundary).
+ * Reads the resolved target from disk exactly once (a dogfood bundle can
+ * run this against the same target file a dozen-plus times for one
+ * compound short-form list) and reuses the same `lines` array for both
+ * checks, instead of checkTarget and checkRangeBoundary each reading and
+ * re-splitting it independently.
+ */
+function checkShortFormTarget(citedPath, startLine, endLine, resolvedPath) {
+    const read = readTarget(resolvedPath);
+    if ("rule" in read)
+        return read;
+    const lines = splitLines(read.content);
+    const base = checkTargetLines(citedPath, startLine, endLine, lines);
+    if (base)
+        return base;
+    return checkRangeBoundary(citedPath, startLine, endLine, lines);
+}
 /**
  * Collects every continuation-citation atom (see the "Continuation
  * citations" doc block above) in `content`, sorted by document position.
@@ -462,10 +917,230 @@ function collectContinuationAtoms(content) {
     }
     return atoms;
 }
-function pushDrift(findings, file, citation, rule, message, resolvedTo) {
+/**
+ * True when the nearest non-whitespace text before `matchIndex` in
+ * `content` is a serial connective: the single character `,`, `;`, or `(`,
+ * or the word `and`/`or` (case-insensitive, word-boundary-matched so it
+ * does not fire on the tail of a longer word like "brand"). See the
+ * "Short-form citations" doc block above for why this is the gate.
+ */
+function isSerialConnectivePreceded(content, matchIndex) {
+    const before = content.slice(0, matchIndex).trimEnd();
+    if (before === "")
+        return false;
+    const lastChar = before[before.length - 1];
+    if (lastChar === "," || lastChar === ";" || lastChar === "(")
+        return true;
+    return /\b(?:and|or)$/i.test(before);
+}
+function isWithinAnySpan(index, spans) {
+    return spans.some(([start, end]) => index >= start && index < end);
+}
+function collectShortFormMatches(content, excludedSpans) {
+    const out = [];
+    const colonRe = new RegExp(SHORT_FORM_COLON_RE.source, "g");
+    let m;
+    while ((m = colonRe.exec(content)) !== null) {
+        if (isWithinAnySpan(m.index, excludedSpans))
+            continue;
+        if (content[m.index - 1] === "`")
+            continue;
+        if (content[m.index + m[0].length] === "`")
+            continue;
+        if (!isSerialConnectivePreceded(content, m.index))
+            continue;
+        const startLine = Number(m[1]);
+        const endLine = Number(m[2]);
+        out.push({ index: m.index, startLine, endLine });
+    }
+    return out.sort((a, b) => a.index - b.index);
+}
+/**
+ * Char spans of every fenced code block in `content` (```` ``` ```` or
+ * `~~~`, optionally with a trailing language tag), each span running from
+ * the start of the opening fence line to the end of the closing fence line
+ * inclusive. An unterminated fence (no matching close before end of doc) is
+ * treated as running to the end of the content -- conservative, since an
+ * unterminated fence is itself a doc problem outside this rule's scope, not
+ * a reason to scan its contents for short-form citations. Derived from
+ * `scanFenceLines` (see there): per-line fenced/opens/closes state is
+ * converted to char-offset spans by tracking each line's `[start, end)`
+ * offset in `content` alongside it.
+ */
+function computeFencedSpans(content) {
+    const spans = [];
+    const lines = content.split("\n");
+    const states = scanFenceLines(lines);
+    let offset = 0;
+    let spanStart = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const lineEnd = offset + lines[i].length;
+        if (states[i].opensFence)
+            spanStart = offset;
+        if (states[i].closesFence && spanStart >= 0) {
+            spans.push([spanStart, lineEnd]);
+            spanStart = -1;
+        }
+        offset = lineEnd + 1; // +1 for the newline joining this line to the next
+    }
+    if (spanStart >= 0) {
+        spans.push([spanStart, content.length]);
+    }
+    return spans;
+}
+/**
+ * Char spans of every CommonMark-style indented code block in `content`: a
+ * maximal run of consecutive non-blank lines, each indented by at least
+ * four spaces or a leading tab, whose first line is preceded by a blank
+ * line or the start of the document (an indented code block cannot
+ * interrupt a paragraph). A blank line inside the run does not itself end
+ * it, matching CommonMark. Simplified relative to the full CommonMark
+ * spec (no list-item-context awareness); adequate for this mechanical,
+ * warn-only rule.
+ */
+function computeIndentedCodeSpans(content) {
+    const spans = [];
+    const lines = content.split("\n");
+    let offset = 0;
+    let blockStart = -1;
+    let blockEnd = -1;
+    let prevBlank = true;
+    for (const line of lines) {
+        const lineStart = offset;
+        const lineEnd = offset + line.length;
+        const isBlank = line.trim() === "";
+        const isIndented = /^( {4,}|\t)/.test(line);
+        if (!isBlank && isIndented && (blockStart !== -1 || prevBlank)) {
+            if (blockStart === -1)
+                blockStart = lineStart;
+            blockEnd = lineEnd;
+        }
+        else if (isBlank && blockStart !== -1) {
+            // blank line inside an open block: keep it open, don't extend blockEnd
+        }
+        else if (!isBlank) {
+            if (blockStart !== -1)
+                spans.push([blockStart, blockEnd]);
+            blockStart = -1;
+            blockEnd = -1;
+        }
+        prevBlank = isBlank;
+        offset = lineEnd + 1;
+    }
+    if (blockStart !== -1)
+        spans.push([blockStart, blockEnd]);
+    return spans;
+}
+/**
+ * Char spans of every inline code span in `content` (`` `...` ``, or a
+ * longer run of backticks as the delimiter). This is a superset of the
+ * narrower "immediately adjacent to a backtick" guard already applied in
+ * collectShortFormMatches: that guard only rejects a match directly
+ * touching a backtick, so a short form embedded further inside a longer
+ * inline code span (e.g. `` `ports (1-3)` ``) was previously matched and
+ * bound; this closes that gap.
+ *
+ * Confined to a single line (the pairing regex excludes `\n`): CommonMark
+ * inline code spans cannot themselves span multiple lines in the sense
+ * this rule cares about, but more importantly, an unmatched backtick run
+ * (a typo, or a literal backtick in prose) previously paired greedily with
+ * the *next* backtick run anywhere later in the whole document, silently
+ * treating everything in between -- potentially several unrelated
+ * sentences and any short-form citation among them -- as one giant inline
+ * code span. Confining the match to a single line means a backtick run
+ * with no partner on the same line produces no span at all, instead of
+ * reaching across a newline for one.
+ */
+function computeInlineCodeSpans(content) {
+    const spans = [];
+    const re = /(`+)[^`\n]*?\1/g;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        spans.push([m.index, m.index + m[0].length]);
+    }
+    return spans;
+}
+/**
+ * Char spans of every Markdown table row in `content`: a line whose
+ * trimmed form starts and ends with `|`. Decision (documented in the
+ * README): a short-form citation inside a table cell is never recognised,
+ * the same way one inside a code span is not -- excluded here rather than
+ * left to the plausibility gate, since a table cell's content is prose-like
+ * and can otherwise carry a range shape the gate would not reject (e.g.
+ * `| col (5-9) |`).
+ */
+function computeTableRowSpans(content) {
+    const spans = [];
+    const lines = content.split("\n");
+    let offset = 0;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("|") &&
+            trimmed.endsWith("|") &&
+            trimmed.length > 1) {
+            spans.push([offset, offset + line.length]);
+        }
+        offset += line.length + 1;
+    }
+    return spans;
+}
+/**
+ * All char spans short-form matching must never fire inside: fenced code,
+ * indented code, inline code spans, and Markdown table rows. Computed once
+ * per doc and combined with fullSpans (see scanDoc) via the existing
+ * isWithinAnySpan helper -- the same mechanism a full citation's own span
+ * already uses, not a second one.
+ */
+function computeExcludedSpans(content) {
+    return [
+        ...computeFencedSpans(content),
+        ...computeIndentedCodeSpans(content),
+        ...computeInlineCodeSpans(content),
+        ...computeTableRowSpans(content),
+    ];
+}
+/**
+ * Paragraph-start offsets in `content`, ascending, always including 0. A
+ * paragraph boundary is a blank (empty or whitespace-only) line.
+ */
+function computeParagraphStarts(content) {
+    const starts = [0];
+    const re = /\n[ \t]*\n+/g;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        starts.push(m.index + m[0].length);
+    }
+    return starts;
+}
+/** The start offset of the paragraph containing `index` (see computeParagraphStarts). */
+function paragraphStartFor(starts, index) {
+    let result = starts[0];
+    for (const s of starts) {
+        if (s > index)
+            break;
+        result = s;
+    }
+    return result;
+}
+/**
+ * The nearest full citation strictly before `beforeIndex` and at or after
+ * `paragraphStart` -- "the last target document named earlier in the same
+ * paragraph" -- or null when none exists.
+ */
+function findLastNamedTargetInParagraph(fullAtoms, paragraphStart, beforeIndex) {
+    let best = null;
+    for (const a of fullAtoms) {
+        if (a.index >= paragraphStart && a.index < beforeIndex) {
+            if (!best || a.index > best.index)
+                best = a;
+        }
+    }
+    return best;
+}
+function pushDrift(findings, file, citation, rule, message, resolvedTo, severity = "warning") {
     findings.push({
         ruleId: RULE_ID,
-        severity: "warning",
+        severity,
         file,
         message: `\`${citation}\`: ${message} [${rule}]`,
         ...(resolvedTo ? { detail: `resolvedTo: ${resolvedTo}` } : {}),
@@ -508,24 +1183,86 @@ function isWrappedPathContinuation(content, matchIndex) {
     const prevLine = content.slice(prevLineStart, prevLineEnd);
     return /[-–]$/.test(prevLine);
 }
+/**
+ * Raw text following a malformed anchor's `#` (see `anchor-malformed` in
+ * the atom-processing loop below), used only to make that finding's message
+ * concrete -- bounded so it reports roughly what was actually typed as the
+ * failed anchor attempt, not an unrelated run of later prose:
+ *   - a quoted-anchor attempt (the character right after `#` is `"`) stops
+ *     at the next `"` on the same line (the closing quote the author
+ *     presumably meant, embedded backticks and all -- that quote is exactly
+ *     what makes this a *quoted* anchor attempt rather than a heading one),
+ *     or at the end of the line when no such quote exists on it (matches
+ *     `CITATION_RE`'s own string alternative, which cannot cross a
+ *     newline either);
+ *   - any other character after `#` is a heading-anchor attempt, which
+ *     stops at the first whitespace (a heading anchor token, like
+ *     `CITATION_RE`'s own heading alternative, never contains whitespace)
+ *     or the end of the line, whichever comes first;
+ *   - either way, capped at `MAX_RAW_LEN` characters so a heading-form
+ *     attempt with no whitespace at all before the line ends (or a
+ *     pathological single long line) cannot make the message unbounded.
+ */
+const MAX_MALFORMED_ANCHOR_RAW_LEN = 60;
+function extractMalformedAnchorRaw(content, hashIndex) {
+    const from = hashIndex + 1;
+    const nl = content.indexOf("\n", from);
+    const lineEnd = nl === -1 ? content.length : nl;
+    let end;
+    if (content[from] === '"') {
+        const q = content.indexOf('"', from + 1);
+        end = q !== -1 && q < lineEnd ? q + 1 : lineEnd;
+    }
+    else {
+        const rest = content.slice(from, lineEnd);
+        const ws = rest.search(/\s/);
+        end = ws === -1 ? lineEnd : from + ws;
+    }
+    if (end - from > MAX_MALFORMED_ANCHOR_RAW_LEN) {
+        end = from + MAX_MALFORMED_ANCHOR_RAW_LEN;
+    }
+    return content.slice(from, end);
+}
 function scanDoc(cache, root, bundleDir, doc) {
     const findings = [];
     const content = doc.raw;
     const sources = getValidSources(doc.frontmatter.parsed) ?? [];
     const docAbsPath = path.join(bundleDir, doc.relPath);
     const fullAtoms = [];
+    // Char spans of every matched full citation, used to keep short-form
+    // matching (see collectShortFormMatches) from re-matching the tail of a
+    // real `path:N-M` citation as a bare short form.
+    const fullSpans = [];
     const re = new RegExp(CITATION_RE.source, "g");
     let m;
     while ((m = re.exec(content)) !== null) {
         if (isWrappedPathContinuation(content, m.index))
             continue;
+        const matchEnd = m.index + m[0].length;
+        // anchor-malformed detection (see the atom-processing loop below for
+        // where the finding is actually pushed): a `#` immediately follows the
+        // range but group 4 (the anchor) did not match -- unbalanced quotes, a
+        // backtick inside a quoted anchor, or nothing at all after the `#`
+        // (e.g. `path:N-M#` at end of line). Computed here, at match time,
+        // because it needs `content`/`matchEnd`; carried on the atom rather
+        // than pushed immediately so the citation's out-of-scope/resolution
+        // posture (path-traversal-rejected, skip, missing-file, ambiguous) can
+        // gate it exactly the same way every other check on this atom already
+        // is -- an out-of-scope or unresolved citation gets none of those
+        // checks either.
+        const malformedAnchorRaw = m[4] === undefined && content[matchEnd] === "#"
+            ? extractMalformedAnchorRaw(content, matchEnd)
+            : null;
         fullAtoms.push({
             kind: "full",
             index: m.index,
             citedPath: m[1],
             startLine: Number(m[2]),
             endLine: m[3] ? Number(m[3]) : null,
+            anchor: parseAnchor(m[4]),
+            malformedAnchorRaw,
         });
+        fullSpans.push([m.index, matchEnd]);
     }
     const atoms = [...fullAtoms, ...collectContinuationAtoms(content)].sort((a, b) => a.index - b.index);
     // `governing`: nearest preceding citation (full or continuation) that
@@ -564,8 +1301,14 @@ function scanDoc(cache, root, bundleDir, doc) {
             lastStartLine = startLine;
             continue; // governing (same file) carries over unchanged
         }
-        const { citedPath, startLine, endLine } = atom;
-        const citation = `${citedPath}:${startLine}${endLine ? "-" + endLine : ""}`;
+        const { citedPath, startLine, endLine, anchor } = atom;
+        // The anchor, when present, is carried in the citation label itself
+        // (not just the anchor-check finding's own message) so two citations to
+        // the same range with different anchors are distinguishable in the
+        // output -- see formatAnchorForLabel and the "Anchored citations" doc
+        // block above. Continuations and short-form citations never carry an
+        // anchor (see there), so their own citation labels are unaffected.
+        const citation = `${citedPath}:${startLine}${endLine ? "-" + endLine : ""}${anchor ? formatAnchorForLabel(anchor) : ""}`;
         if (hasParentSegment(citedPath)) {
             pushDrift(findings, doc.relPath, citation, "path-traversal-rejected", `citedPath contains a ".." segment and was rejected without resolving: ${citedPath}`);
             governing = null;
@@ -590,7 +1333,19 @@ function scanDoc(cache, root, bundleDir, doc) {
             lastStartLine = null;
             continue;
         }
-        const problem = checkTarget(citedPath, startLine, endLine, resolution.path);
+        // anchor-malformed (notice): only reached for a citation that resolved
+        // to a real file -- see `malformedAnchorRaw`'s doc comment above for
+        // why this is gated the same way missing-file/skip/path-traversal are
+        // already gated for every other check on this atom. The citation is
+        // still checked below via checkFullTarget exactly as an ordinary
+        // anchorless citation would be (anchor is null here by construction --
+        // see parseAnchor); this only ADDS a heads-up that the `#` sitting
+        // right there was silently not read as the anchor it looks like it was
+        // meant to be.
+        if (atom.malformedAnchorRaw !== null) {
+            pushDrift(findings, doc.relPath, citation, "anchor-malformed", `a "#" follows the citation's range but does not parse as a heading or string anchor (raw: "${atom.malformedAnchorRaw}")`, undefined, "notice");
+        }
+        const problem = checkFullTarget(citedPath, startLine, endLine, resolution.path, anchor);
         if (problem?.rule === "unreadable-target") {
             pushUnreadable(findings, doc.relPath, citation, path.relative(root, resolution.path), problem.code ?? "UNKNOWN");
         }
@@ -600,6 +1355,70 @@ function scanDoc(cache, root, bundleDir, doc) {
         governing = { citedPath, resolvedPath: resolution.path };
         lastStartLine = startLine;
     }
+    // Short-form (paragraph-bound) citations -- see that doc block above.
+    // Deliberately independent of `governing`/`lastStartLine`: short-form
+    // binding is paragraph-scoped by design, not chained through the
+    // document-wide continuation state machine above. Reserved files
+    // (index.md, log.md, see doc.isReserved) are skipped entirely: they are
+    // append-only narrative journals, not `sources:`-driven reference docs,
+    // and routinely narrate historical "old N-M -> new X-Y" line-number
+    // deltas as prose data about past changes -- not live citations against
+    // current content -- which this rule's bare-range matching cannot tell
+    // apart from a real short-form citation. Full/continuation citations in
+    // reserved files are still scanned as before; this carve-out is scoped
+    // to short-form matching only.
+    const shortFormMatches = doc.isReserved
+        ? []
+        : collectShortFormMatches(content, [
+            ...fullSpans,
+            ...computeExcludedSpans(content),
+        ]);
+    if (shortFormMatches.length > 0) {
+        const paragraphStarts = computeParagraphStarts(content);
+        const namedFullAtoms = [];
+        for (const a of fullAtoms) {
+            if (a.kind === "full") {
+                namedFullAtoms.push({
+                    index: a.index,
+                    citedPath: a.citedPath,
+                });
+            }
+        }
+        for (const sf of shortFormMatches) {
+            const paragraphStart = paragraphStartFor(paragraphStarts, sf.index);
+            const target = findLastNamedTargetInParagraph(namedFullAtoms, paragraphStart, sf.index);
+            const rangeLabel = `${sf.startLine}-${sf.endLine}`;
+            if (!target) {
+                pushDrift(findings, doc.relPath, `${rangeLabel} (short-form)`, "short-form-unbound", "no full `path:N` citation earlier in this paragraph to bind to", undefined, "notice");
+                continue;
+            }
+            const targetPath = target.citedPath;
+            const citation = `${targetPath}:${rangeLabel} (short-form)`;
+            if (hasParentSegment(targetPath)) {
+                // The full citation that named this target already reported
+                // path-traversal-rejected for itself; not re-flagged a second time.
+                continue;
+            }
+            const resolution = resolveCitation(cache, root, docAbsPath, content, sources, targetPath, sf.index);
+            if (!resolution) {
+                pushDrift(findings, doc.relPath, citation, "missing-file", `could not resolve ${targetPath}: tried doc sources, ancestor climb (bare filenames only), repo-root, doc-relative, nearest prior qualified mention, repo-wide search; no candidate file exists`);
+                continue;
+            }
+            if ("skip" in resolution)
+                continue;
+            if ("ambiguous" in resolution) {
+                pushAmbiguous(findings, doc.relPath, citation, resolution.candidates);
+                continue;
+            }
+            const problem = checkShortFormTarget(targetPath, sf.startLine, sf.endLine, resolution.path);
+            if (problem?.rule === "unreadable-target") {
+                pushUnreadable(findings, doc.relPath, citation, path.relative(root, resolution.path), problem.code ?? "UNKNOWN");
+            }
+            else if (problem) {
+                pushDrift(findings, doc.relPath, citation, problem.rule, problem.message, path.relative(root, resolution.path), problem.severity);
+            }
+        }
+    }
     return findings;
 }
 export const citationsResolveRule = {