okf-kit 0.6.0 → 0.8.0

package/dist/rules/citations-resolve.js

@@ -173,7 +173,21 @@ const RULE_ID = "citations-resolve";
  * 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.
+ * 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
@@ -202,8 +216,112 @@ const RULE_ID = "citations-resolve";
  *     plus prose) to stay in sync, the exact class of drift this rule
  *     exists to catch.
  */
+/**
+ * Anchor strictness (opt-in, `--require-anchors`, see `src/cli.ts`).
+ * Backward compatible by construction: every check in this section is
+ * gated on `ctx.requireAnchors` being present (`RequireAnchorsOptions`, see
+ * `src/types.ts`), so a consumer that never passes `--require-anchors`
+ * sees byte-identical findings to before this section existed. Three new
+ * rule ids, all `warning`-severity, mirroring this rule's own "a wrong
+ * start/target is strong drift evidence" posture rather than the `notice`
+ * posture reserved for the mechanical prose checks with a real
+ * false-positive risk (`markdown-range-boundary-bracket-or-fence` and
+ * friends):
+ *
+ *   - `anchor-required`: an in-repo full citation (`path:N`/`path:N-M`,
+ *     resolved to a real target -- an unresolved citation already gets its
+ *     own `missing-file`/`unresolved-ambiguous` finding, not this one)
+ *     carrying no `#anchor` at all. Exempted the same way this rule already
+ *     exempts short-form matching for a reserved citing doc
+ *     (`doc.isReserved`, e.g. `log.md`'s append-only line-number narration),
+ *     and additionally by `requireAnchors.allow`: a citedPath matching one
+ *     of its glob/exact patterns (matched against the citation's raw,
+ *     as-written `citedPath` text -- see `matchesAllowPattern`) is exempt,
+ *     for a doc category this check is not (yet) meant to cover, e.g. a
+ *     README or install guide whose prose is not line-anchored the way a
+ *     CHANGELOG or source citation is.
+ *   - `anchor-not-on-last-line`: layered on `checkAnchor`'s existing string
+ *     branch. An anchor sitting on the FIRST line of a wide range survives a
+ *     k-line insertion above the range whenever k is smaller than the range
+ *     itself, because the shifted window (the citation's own line numbers,
+ *     re-read after the insertion) still contains the original first
+ *     line's content, just at a different offset inside the window.
+ *     Anchoring on the LAST line instead closes that: the original last
+ *     line falls out of the shifted window on any insertion size >= 1, not
+ *     only large ones.
+ *   - `anchor-not-unique-in-range`: also layered on the string branch. An
+ *     anchor text occurring more than once inside its own cited range is
+ *     ambiguous evidence -- which occurrence is the one actually pinning
+ *     the citation? A count of zero is unaffected (already
+ *     `anchor-not-found-in-range`, unconditionally, not double-reported
+ *     here).
+ *
+ * Both of the last two are checked only once a match exists at all (count
+ * >= 1); uniqueness is checked before last-line placement, since a
+ * non-unique anchor is the more fundamental problem (which of the several
+ * matching lines "is" the anchor is undefined before asking whether the
+ * one occurrence is on the right line).
+ *
+ * A fourth check, `test-range-straddles-block` (warning), applies to a FULL
+ * citation's own range into a `.test.`/`.spec.` target (`.ts`, `.js`,
+ * `.mjs`) under this same opt-in (see `checkTestRangeStraddle`, called
+ * from `checkFullTarget`): a
+ * full citation's range is expected to stay inside a single `describe`/
+ * `it`/`test` block once it starts, so any block-head line
+ * (`describe(`/`describe.only(`/`describe.skip(`/`describe.each(`/`it(`/
+ * `it.only(`/`it.skip(`/`it.each(`/`test(`/`test.only(`/`test.skip(`/
+ * `test.each(`, see `TEST_BLOCK_HEAD_RE`) found on any line of the range
+ * OTHER than its own first line means the citation ran into a sibling or
+ * outer block (or never really started on one). A range that leaves its
+ * block without a later head line inside it (ending on an outer block's
+ * closing line) is not detected by this line-based check. The range's start
+ * line is never itself checked here: it is either a legitimate block head
+ * (the range correctly starts a block) or legitimately inside a block's
+ * body (a partial citation into the middle of a block), and both are fine
+ * -- only a head line reappearing *after* the start is evidence of drift.
+ * Deliberately its own rule id rather than reusing `checkRangeBoundary`'s
+ * `test-range-start-not-head`/`test-range-end-not-closing` (which stay
+ * short-form-only, see `checkShortFormTarget`): those two require the range
+ * to start exactly on a head line and end exactly on the matching closing
+ * `});`, which is far stricter than a full citation's legitimate use
+ * (citing an arbitrary sub-range once a paragraph has already named the
+ * file) needs -- the straddle check only cares whether the range crossed a
+ * block boundary, not whether it captured a whole block precisely.
+ * Deliberately scoped to test-file targets only, same reasoning
+ * `checkShortFormTarget`'s own doc comment already gives for the Markdown
+ * half of the block-boundary check: a full citation into a Markdown target
+ * legitimately cites a couple of arbitrary lines all the time.
+ */
+/**
+ * True when `citedPath` (the citation's raw, as-written path text) matches
+ * one of `patterns`: an exact string match, or a glob with `*` (any run of
+ * characters) and `?` (any single character) as the only wildcards -- the
+ * minimal shape needed for `requireAnchors.allow`'s own documented example
+ * (`["README.md", "INSTALL-AGENT.md"]`), not a general-purpose glob engine.
+ */
+function matchesAllowPattern(citedPath, patterns) {
+    return patterns.some((pattern) => {
+        if (!pattern.includes("*") && !pattern.includes("?")) {
+            return pattern === citedPath;
+        }
+        const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+        const reSource = "^" + escaped.replace(/\*/g, ".*").replace(/\?/g, ".") + "$";
+        return new RegExp(reSource).test(citedPath);
+    });
+}
 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
@@ -225,13 +343,53 @@ function parseAnchor(raw) {
     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. Anchor heading-search
- * needs its own copy because it works from an already-split `lines` array
- * (see `checkFullTarget`), not the raw `content` string `computeFencedSpans`
+ * 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
@@ -243,25 +401,10 @@ function parseAnchor(raw) {
  */
 function computeFencedLineIndices(lines) {
     const fenced = new Set();
-    let fenceMarker;
-    let fenceStart = -1;
-    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);
-            fenceStart = i;
-        }
-        else if (fenceMarker && trimmed.startsWith(fenceMarker)) {
-            for (let j = fenceStart; j <= i; j++)
-                fenced.add(j);
-            fenceMarker = undefined;
-            fenceStart = -1;
-        }
-    }
-    if (fenceMarker && fenceStart >= 0) {
-        for (let j = fenceStart; j < lines.length; j++)
-            fenced.add(j);
-    }
+    scanFenceLines(lines).forEach((state, i) => {
+        if (state.fenced)
+            fenced.add(i);
+    });
     return fenced;
 }
 /**
@@ -285,29 +428,80 @@ function findEnclosingHeading(lines, startLine, fencedLines) {
     }
     return null;
 }
+// A trimmed line composed of nothing but closing brackets/braces/parens
+// plus an optional trailing `,`/`;` -- bare closing boilerplate like `}`,
+// `});`, `]);`, `}),`. Used only by `lastContentLineInRange` (opt-in
+// `anchor-not-on-last-line`, see there): a range that ends on such a line
+// (the common shape of a `});` that closes a whole cited `describe`/`it`
+// block) should not force the anchor onto that boilerplate line itself --
+// the last CONTENT line before it is the meaningful place for an anchor
+// to live.
+const CLOSING_BOILERPLATE_RE = /^[\]\)\};,]*$/;
+function isContentLine(text) {
+    const trimmed = text.trim();
+    return trimmed !== "" && !CLOSING_BOILERPLATE_RE.test(trimmed);
+}
+/**
+ * The last line number (1-based, within `[startLine, endLine]`) whose text
+ * is a "content" line -- see `isContentLine`. Walks backward from `endLine`
+ * so a range ending on one or more bare closing-boilerplate lines (`});`,
+ * `]);`, `}),`, a lone `}`) resolves to the real content line before them
+ * instead of the boilerplate itself. Falls back to `endLine` unchanged when
+ * every line in the range is boilerplate or blank (nothing better to
+ * anchor against).
+ */
+function lastContentLineInRange(lines, startLine, endLine) {
+    for (let ln = endLine; ln >= startLine; ln--) {
+        if (isContentLine(lines[ln - 1] ?? ""))
+            return ln;
+    }
+    return endLine;
+}
 /**
  * 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) {
+function checkAnchor(anchor, startLine, endLine, lines, requireAnchors) {
     if (anchor.kind === "string") {
+        let count = 0;
+        let lastMatchLine = -1;
         for (let i = startLine - 1; i <= endLine - 1 && i < lines.length; i++) {
-            if ((lines[i] ?? "").includes(anchor.text))
-                return null;
+            if ((lines[i] ?? "").includes(anchor.text)) {
+                count++;
+                lastMatchLine = i + 1;
+            }
         }
-        return {
-            rule: "anchor-not-found-in-range",
-            message: `anchor "${anchor.text}" does not occur in the cited range (${startLine}-${endLine})`,
-        };
+        if (count === 0) {
+            return {
+                rule: "anchor-not-found-in-range",
+                message: `anchor "${anchor.text}" does not occur in the cited range (${startLine}-${endLine})`,
+            };
+        }
+        if (requireAnchors) {
+            if (count > 1) {
+                return {
+                    rule: "anchor-not-unique-in-range",
+                    message: `anchor "${anchor.text}" occurs on ${count} lines of the cited range (${startLine}-${endLine}); expected exactly one`,
+                };
+            }
+            const lastContentLine = lastContentLineInRange(lines, startLine, endLine);
+            if (lastMatchLine !== lastContentLine) {
+                return {
+                    rule: "anchor-not-on-last-line",
+                    message: `anchor "${anchor.text}" occurs on line ${lastMatchLine}, not the cited range's last content line (${lastContentLine})`,
+                };
+            }
+        }
+        return null;
     }
     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 against; use a string anchor (#"...") instead against a target with no heading structure`,
+            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)) {
@@ -323,13 +517,93 @@ function checkAnchor(anchor, startLine, endLine, lines) {
         if (m && m[1].length <= heading.level) {
             return {
                 rule: "anchor-heading-does-not-enclose",
-                message: `range extends past its enclosing heading's section (next heading "${m[2].trim()}" at line ${i + 1})`,
+                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;
+/**
+ * Heading-section citations. A CHANGELOG.md that grows by insertion at the
+ * top forces every later `path:N-M#anchor` citation to be re-pointed on
+ * every release, even with the heading anchor above closing the "wrong
+ * section" gap -- the line RANGE itself still drifts on every insertion,
+ * so the citation still needs editing, just not silently mis-validated.
+ * `path:#heading` sidesteps line numbers entirely: it names a heading
+ * (matched the same way the line-range anchor above already matches one,
+ * `heading.text.includes(...)`, reused rather than re-invented -- see
+ * `parseAnchor`/`findHeadingSection`) and resolves to that heading's own
+ * section (from the line after the heading up to, but not including, the
+ * next heading of the same or shallower level, or EOF) -- see
+ * `findHeadingSection`. The section must exist (`heading-section-not-found`
+ * when no such heading is found), must be unambiguous (more than one
+ * matching heading is `heading-section-ambiguous`, never silently the
+ * first hit -- the same posture `unresolved-ambiguous` already takes for
+ * path resolution), and must not be empty (`heading-section-empty`).
+ *
+ * Deliberately reuses `ANCHOR_HEADING_MAX_LEVEL` (2), not a second cap: the
+ * same Keep-a-Changelog nesting that motivates the line-range anchor's cap
+ * (`## [x.y.z]` release headings around identically-named, per-release
+ * `### Added`/`### Changed`/`### Fixed` subsections) means a level-3+
+ * heading name is *never* unique across a real CHANGELOG anyway --
+ * matching it would just turn every such citation into a guaranteed
+ * `heading-section-ambiguous`. Capping the search at level 2 keeps this
+ * form usable for exactly the case it exists for (a release section) and
+ * behaves identically to the line-range anchor for the same reason.
+ *
+ * Optional content anchor: `path:#heading#"text"`, always the quoted form
+ * (a section's body is prose/content, not a second heading to look up) --
+ * the text must occur on EXACTLY one line inside the resolved section
+ * (`heading-section-content-anchor-not-found` / `-ambiguous`), stricter
+ * than the line-range string anchor's "at least one line" (`checkAnchor`'s
+ * string branch): a whole section is a much larger haystack than a
+ * caller-chosen line range, so "present somewhere" is far weaker evidence
+ * the anchor still points at the intended spot, and "found on exactly one
+ * line" is what the task this form was built for (pinning a citation to
+ * one prose sentence inside a growing section) actually needs. The heading
+ * position itself keeps only the bare/bracketed form (`#heading`/
+ * `#[heading]`); the quoted alternative is reserved for the content anchor
+ * position so the two can never be confused by shape alone.
+ *
+ * Backtick-delimited, unlike the line-range form above (which does not
+ * require backticks -- see the "Anchor syntax note" in the README). This
+ * is a deliberate, narrower grammar for this form specifically: a bare
+ * `path#heading` (the grammar this form used in an earlier round) is
+ * indistinguishable from an ordinary Markdown link's target, which
+ * commonly has exactly that shape (`[install](docs/README.md#install)`)
+ * -- unlike the line-range form (gated by a `:N` no ordinary link ever
+ * contains), there was no character available to tell a real citation
+ * apart from a relative link's href written in prose, and measuring
+ * against real bundles (see the CHANGELOG entry that introduced the
+ * `:#` form) showed the collision is not hypothetical: existing docs write
+ * `` `path#heading` `` as inline prose pointing at an unrelated anchor,
+ * each producing a spurious `heading-section-not-found`. The colon
+ * (`path:#heading`) reuses this rule's existing citation signature (a
+ * literal `:` no Markdown link fragment ever contains) instead of relying
+ * on backticks alone to do that job, and is additionally restricted to a
+ * `.md` target: a link fragment's target is always the Markdown doc it
+ * points into, never a source or config file, so a non-`.md` path with
+ * this shape is never a live citation. Requiring the whole citation
+ * inside one pair of backticks stays in place as well, matching this
+ * rule's own general recommendation for the line-range form.
+ */
+const HEADING_SECTION_CITATION_RE = /`([\w./-]+\.md):#(\[?\w(?:[\w.-]*\w)?\]?)(?:#("[^"\n`]+"))?`/g;
+/**
+ * Companion to `HEADING_SECTION_CITATION_RE`: matches the same
+ * backtick + path + `:#` opener but accepts anything up to the closing
+ * backtick, so a heading-section citation that fails to parse (an
+ * unterminated or empty content-anchor quote, an unquoted third segment,
+ * or a non-`.md` target, which includes a non-lowercase `.MD` extension) is
+ * still recognised as an *attempt* rather than
+ * silently vanishing -- mirrors `anchor-malformed`'s
+ * "still-visible-as-a-notice" posture for the line-range anchor form (see
+ * `extractMalformedAnchorRaw`). Only used for a match whose span does not
+ * already overlap a successful `HEADING_SECTION_CITATION_RE` match (see
+ * `collectHeadingSectionMatches`); a well-formed citation never also
+ * produces a malformed notice.
+ */
+const HEADING_SECTION_MALFORMED_RE = /`([\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
@@ -354,6 +628,14 @@ const SHORT_FORM_COLON_RE = /:(\d+)-(\d+)/g;
 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*$/;
+// Block-head detection for test-range-straddles-block (see the doc block
+// above and checkTestRangeStraddle below): a wider set of head shapes than
+// TEST_HEAD_LINE_RE (which stays short-form-only, unchanged, via
+// checkRangeBoundary/checkShortFormTarget) -- describe/it/test, each with
+// an optional .only/.skip/.each modifier. A leading `export `/`async ` is
+// deliberately not handled: not needed for any bundle this rule has been
+// measured against.
+const TEST_BLOCK_HEAD_RE = /^\s*(?:describe|it|test)(?:\.(?:only|skip|each))?\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
@@ -629,17 +911,215 @@ function checkTarget(citedPath, startLine, endLine, resolvedPath) {
  * 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) {
+function checkFullTarget(citedPath, startLine, endLine, resolvedPath, anchor, requireAnchors) {
     const read = readTarget(resolvedPath);
     if ("rule" in read)
-        return 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);
+        return [base];
+    const problems = [];
+    // test-range-straddles-block, opt-in only (see "Anchor strictness
+    // (opt-in)" above and checkTestRangeStraddle): a full citation's own
+    // range into a .test./.spec. target (.ts, .js, .mjs) must not cross
+    // into another block's head after its own first line. Deliberately
+    // scoped to test-file targets only (isTestFile), not also a markdown
+    // branch: a
+    // full citation into a markdown target legitimately cites a couple of
+    // arbitrary lines all the time (e.g. two lines of a code fence example),
+    // the exact reasoning checkShortFormTarget's own doc comment already
+    // gives for why the sibling block-boundary check was scoped to
+    // short-form in the first place. Only meaningful for an actual range
+    // (endLine !== null); a single-line citation trivially starts and ends
+    // on the same line and has nothing to straddle.
+    if (requireAnchors && endLine !== null && isTestFile(citedPath)) {
+        const straddle = checkTestRangeStraddle(startLine, endLine, lines);
+        if (straddle)
+            problems.push(straddle);
+    }
+    // The anchor check is run independently of the straddle check above
+    // (not gated on it having come back clean): a straddling range and a
+    // missing/misplaced anchor are two independent problems with the same
+    // citation, and reporting only the first one found would silently drop
+    // the other from the output every time both happen to co-occur.
+    if (anchor) {
+        const anchorProblem = checkAnchor(anchor, startLine, endLine ?? startLine, lines, requireAnchors);
+        if (anchorProblem)
+            problems.push(anchorProblem);
+    }
+    return problems;
+}
+/**
+ * Every Markdown heading in `lines` up to `ANCHOR_HEADING_MAX_LEVEL`, in
+ * document order -- the whole-document counterpart of `findEnclosingHeading`
+ * (which stops at the nearest heading at or before a given line): a
+ * heading-section citation has no start line to search backward from, it
+ * needs every candidate to test for a unique match. `fencedLines` (see
+ * `computeFencedLineIndices`) excludes a `#`-led line inside a fenced
+ * example, same as `findEnclosingHeading`.
+ */
+function collectHeadingsUpToLevel(lines, fencedLines) {
+    const headings = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (fencedLines.has(i))
+            continue;
+        const m = (lines[i] ?? "").match(MD_HEADING_RE);
+        if (m && m[1].length <= ANCHOR_HEADING_MAX_LEVEL) {
+            headings.push({ level: m[1].length, text: m[2].trim(), lineNo: i + 1 });
+        }
+    }
+    return headings;
+}
+/**
+ * Resolves a heading-section citation's heading text to a single section:
+ * every level <= `ANCHOR_HEADING_MAX_LEVEL` heading whose text contains
+ * `headingText` (same containment check `checkAnchor`'s heading branch
+ * already uses -- reused, not reinvented) is a candidate; zero is
+ * `not-found`, more than one is `ambiguous` (never silently the first
+ * match), exactly one resolves to the section running from the line right
+ * after the heading up to (not including) the next heading at or above the
+ * same level, or EOF -- the same enclosure boundary `checkAnchor`'s heading
+ * branch walks forward to check, just producing a body range here instead
+ * of a pass/fail against an already-known end line.
+ */
+function findHeadingSection(lines, fencedLines, headingText) {
+    const headings = collectHeadingsUpToLevel(lines, fencedLines);
+    const matches = headings.filter((h) => h.text.includes(headingText));
+    if (matches.length === 0)
+        return { kind: "not-found" };
+    if (matches.length > 1)
+        return { kind: "ambiguous", matches };
+    const heading = matches[0];
+    let bodyEnd = lines.length;
+    for (let i = heading.lineNo; i < lines.length; i++) {
+        if (fencedLines.has(i))
+            continue;
+        const m = (lines[i] ?? "").match(MD_HEADING_RE);
+        if (m && m[1].length <= heading.level) {
+            bodyEnd = i;
+            break;
+        }
+    }
+    return { kind: "found", heading, bodyStart: heading.lineNo, bodyEnd };
+}
+/** True when every line in `[bodyStart, bodyEnd)` is empty or whitespace-only. */
+function isSectionEmpty(lines, bodyStart, bodyEnd) {
+    for (let i = bodyStart; i < bodyEnd; i++) {
+        if ((lines[i] ?? "").trim() !== "")
+            return false;
+    }
+    return true;
+}
+/**
+ * Count of lines in `[bodyStart, bodyEnd)` containing `text` -- a heading
+ * section's content anchor must occur on exactly one such line (see the
+ * "Heading-section citations" doc block above for why this is stricter
+ * than the line-range string anchor's "at least one line").
+ */
+function countAnchorOccurrences(lines, bodyStart, bodyEnd, text) {
+    let count = 0;
+    for (let i = bodyStart; i < bodyEnd; i++) {
+        if ((lines[i] ?? "").includes(text))
+            count++;
+    }
+    return count;
+}
+/**
+ * A heading-section citation's complete target check (see the
+ * "Heading-section citations" doc block above): the named heading must
+ * exist exactly once, its section must be non-empty, and, when a content
+ * anchor was given, it must occur on exactly one line inside that section.
+ * One problem per citation, checked in that order, matching every other
+ * check in this file's "base checks first" pattern.
+ */
+function checkHeadingSectionTarget(headingAnchor, contentAnchor, resolvedPath) {
+    const read = readTarget(resolvedPath);
+    if ("rule" in read)
+        return read;
+    const lines = splitLines(read.content);
+    const fencedLines = computeFencedLineIndices(lines);
+    const section = findHeadingSection(lines, fencedLines, headingAnchor.text);
+    if (section.kind === "not-found") {
+        return {
+            rule: "heading-section-not-found",
+            message: `no heading (level <= ${ANCHOR_HEADING_MAX_LEVEL}) contains "${headingAnchor.text}"`,
+        };
+    }
+    if (section.kind === "ambiguous") {
+        return {
+            rule: "heading-section-ambiguous",
+            message: `${section.matches.length} headings contain "${headingAnchor.text}" (lines ${section.matches
+                .map((m) => m.lineNo)
+                .join(", ")}); not evaluated`,
+        };
+    }
+    if (isSectionEmpty(lines, section.bodyStart, section.bodyEnd)) {
+        return {
+            rule: "heading-section-empty",
+            message: `section under heading "${section.heading.text}" (line ${section.heading.lineNo}) has no non-blank content before the next heading`,
+        };
+    }
+    if (contentAnchor) {
+        const count = countAnchorOccurrences(lines, section.bodyStart, section.bodyEnd, contentAnchor.text);
+        if (count === 0) {
+            return {
+                rule: "heading-section-content-anchor-not-found",
+                message: `content anchor "${contentAnchor.text}" does not occur in the section under heading "${section.heading.text}"`,
+            };
+        }
+        if (count > 1) {
+            return {
+                rule: "heading-section-content-anchor-ambiguous",
+                message: `content anchor "${contentAnchor.text}" occurs on ${count} lines in the section under heading "${section.heading.text}"; expected exactly one`,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Every well-formed heading-section citation in `content`, in document
+ * order. Collected once, up front (before `CITATION_RE`'s own scan in
+ * `scanDoc`), so its match spans can gate both `CITATION_RE` (a full
+ * citation never fires inside a heading-section citation's own quoted
+ * content anchor, see the "Heading-section citations" doc block above) and
+ * the malformed companion scan (see `collectHeadingSectionMalformedMatches`)
+ * without re-deriving the same spans twice.
+ */
+function collectHeadingSectionMatches(content) {
+    const out = [];
+    const re = new RegExp(HEADING_SECTION_CITATION_RE.source, HEADING_SECTION_CITATION_RE.flags);
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        out.push({
+            index: m.index,
+            end: m.index + m[0].length,
+            citedPath: m[1],
+            headingAnchor: parseAnchor(m[2]), // group 2 is mandatory
+            contentAnchor: parseAnchor(m[3]),
+        });
+    }
+    return out;
+}
+/**
+ * Every backtick + path + `:#` opener in `content` that did NOT parse as a
+ * well-formed heading-section citation (see `HEADING_SECTION_MALFORMED_RE`'s
+ * doc comment) -- an unterminated content-anchor quote, an unquoted third
+ * segment, or a non-`.md` target. `wellFormedSpans` (from
+ * `collectHeadingSectionMatches`) gates out any match that is really just
+ * the successful citation seen from the outside; a well-formed citation
+ * never also produces a malformed notice.
+ */
+function collectHeadingSectionMalformedMatches(content, wellFormedSpans) {
+    const out = [];
+    const re = new RegExp(HEADING_SECTION_MALFORMED_RE.source, "g");
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        if (isWithinAnySpan(m.index, wellFormedSpans))
+            continue;
+        out.push({ index: m.index, end: m.index + m[0].length, raw: m[0] });
+    }
+    return out;
 }
 // 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
@@ -668,27 +1148,13 @@ function isTestFile(citedPath) {
  * 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).
+ * 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) {
-    let inFence = false;
-    let fenceMarker;
-    for (let i = 0; i <= lineIndex; i++) {
-        const trimmed = (lines[i] ?? "").trim();
-        if (!inFence && MD_FENCE_DELIM_RE.test(trimmed)) {
-            if (i === lineIndex)
-                return true;
-            inFence = true;
-            fenceMarker = trimmed.slice(0, 3);
-        }
-        else if (inFence && fenceMarker && trimmed.startsWith(fenceMarker)) {
-            if (i === lineIndex)
-                return false;
-            inFence = false;
-            fenceMarker = undefined;
-        }
-    }
-    return false;
+    return scanFenceLines(lines)[lineIndex]?.opensFence ?? false;
 }
 /**
  * True when `lines[endLineIndex]` is the closing delimiter that matches
@@ -803,6 +1269,53 @@ function checkRangeBoundary(citedPath, startLine, endLine, lines) {
     }
     return null;
 }
+/**
+ * Width (in characters) of `text`'s leading run of spaces/tabs -- used by
+ * `checkTestRangeStraddle` to tell a NESTED block head (indented deeper
+ * than the range's own start line) apart from a SIBLING or OUTER one
+ * (indented the same or shallower): citing a whole `describe` block
+ * necessarily contains every `it(`/nested-`describe(` head inside its own
+ * body, and those are not straddling anywhere, they are exactly what the
+ * citation is about.
+ */
+function leadingWhitespaceWidth(text) {
+    return (text.match(/^[ \t]*/) ?? [""])[0].length;
+}
+/**
+ * `test-range-straddles-block` (opt-in, warning): a FULL citation's own
+ * range into a `.test.`/`.spec.` target (`.ts`, `.js`, `.mjs`), see the
+ * "Anchor strictness (opt-in)" doc block above for the full rule text.
+ * Checks every line of `[startLine, endLine]` EXCEPT the range's own
+ * first line (`startLine`
+ * itself is never checked -- see that doc block for why) against
+ * `TEST_BLOCK_HEAD_RE`; the first hit (in document order) is reported,
+ * matching this file's "one problem per citation" pattern. A block-head
+ * line indented STRICTLY DEEPER than the range's own start line is a
+ * NESTED block (e.g. the `it(`s inside a `describe(` the range cites in
+ * full) and is skipped, not reported: a citation covering a whole block is
+ * expected to contain every head line nested inside it. A block-head line
+ * at the same or a shallower indent is a SIBLING or OUTER block and is
+ * still reported -- this is an approximation of "which block scope is
+ * this line lexically in" using indentation instead of a real AST, chosen
+ * because it reproduces the AST-based reference verdict on every straddle
+ * finding this rule has been measured against; a file that mixes tabs and
+ * spaces, or that does not indent nested blocks at all, can defeat it.
+ */
+function checkTestRangeStraddle(startLine, endLine, lines) {
+    const startIndent = leadingWhitespaceWidth(lines[startLine - 1] ?? "");
+    for (let i = startLine; i <= endLine - 1 && i < lines.length; i++) {
+        const text = lines[i] ?? "";
+        if (!TEST_BLOCK_HEAD_RE.test(text))
+            continue;
+        if (leadingWhitespaceWidth(text) > startIndent)
+            continue; // nested block
+        return {
+            rule: "test-range-straddles-block",
+            message: `range straddles into another block's head at line ${i + 1} ("${text.trim()}")`,
+        };
+    }
+    return null;
+}
 /**
  * A short-form citation's full check: checkTarget's existing checks
  * (unreadable-target, inverted-range, range-exceeds-file, blank-start-line,
@@ -926,30 +1439,29 @@ function collectShortFormMatches(content, excludedSpans) {
  * 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.
+ * 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 fenceMarker;
-    let fenceStart = -1;
-    for (const line of lines) {
-        const trimmed = line.trim();
-        const lineEnd = offset + line.length;
-        if (!fenceMarker && MD_FENCE_DELIM_RE.test(trimmed)) {
-            fenceMarker = trimmed.slice(0, 3);
-            fenceStart = offset;
-        }
-        else if (fenceMarker && trimmed.startsWith(fenceMarker)) {
-            spans.push([fenceStart, lineEnd]);
-            fenceMarker = undefined;
-            fenceStart = -1;
+    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 (fenceMarker && fenceStart >= 0) {
-        spans.push([fenceStart, content.length]);
+    if (spanStart >= 0) {
+        spans.push([spanStart, content.length]);
     }
     return spans;
 }
@@ -1148,11 +1660,76 @@ function isWrappedPathContinuation(content, matchIndex) {
     const prevLine = content.slice(prevLineStart, prevLineEnd);
     return /[-–]$/.test(prevLine);
 }
-function scanDoc(cache, root, bundleDir, doc) {
+/**
+ * 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, requireAnchors) {
     const findings = [];
     const content = doc.raw;
     const sources = getValidSources(doc.frontmatter.parsed) ?? [];
     const docAbsPath = path.join(bundleDir, doc.relPath);
+    // The four `--require-anchors` opt-in checks (anchor-required,
+    // anchor-not-on-last-line, anchor-not-unique-in-range,
+    // test-range-straddles-block) are all exempt for a reserved citing doc
+    // (index.md/log.md, see doc.isReserved), the same carve-out this rule
+    // already gives reserved docs for short-form matching: an append-only
+    // narrative journal routinely narrates historical line-number deltas as
+    // prose about the past, not live citations against current content.
+    // Threaded as `undefined` here (rather than a second boolean everywhere
+    // `requireAnchors` is read) so every opt-in check downstream stays gated
+    // on the exact same "is this option object present" test it already
+    // uses for the non-reserved case.
+    const requireAnchorsForDoc = doc.isReserved ? undefined : requireAnchors;
+    // Heading-section citations (well-formed and malformed) are collected up
+    // front so their char spans can gate the `CITATION_RE` scan below: a
+    // `CITATION_RE` match landing inside a heading-section citation's own
+    // quoted content anchor (e.g. `` `x.md:#2.0.0#"see other.md:12 now"` ``)
+    // is not a second, independent citation -- it is text the heading-section
+    // citation already owns. Reused again lower down for the heading-section
+    // findings themselves, rather than re-scanning by regex a second time.
+    const headingSectionMatches = collectHeadingSectionMatches(content);
+    const headingSectionSpans = headingSectionMatches.map((hs) => [hs.index, hs.end]);
+    const headingSectionMalformedMatches = collectHeadingSectionMalformedMatches(content, headingSectionSpans);
+    for (const hm of headingSectionMalformedMatches) {
+        headingSectionSpans.push([hm.index, hm.end]);
+    }
     const fullAtoms = [];
     // Char spans of every matched full citation, used to keep short-form
     // matching (see collectShortFormMatches) from re-matching the tail of a
@@ -1163,6 +1740,23 @@ function scanDoc(cache, root, bundleDir, doc) {
     while ((m = re.exec(content)) !== null) {
         if (isWrappedPathContinuation(content, m.index))
             continue;
+        if (isWithinAnySpan(m.index, headingSectionSpans))
+            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,
@@ -1170,8 +1764,9 @@ function scanDoc(cache, root, bundleDir, doc) {
             startLine: Number(m[2]),
             endLine: m[3] ? Number(m[3]) : null,
             anchor: parseAnchor(m[4]),
+            malformedAnchorRaw,
         });
-        fullSpans.push([m.index, m.index + m[0].length]);
+        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
@@ -1211,7 +1806,13 @@ function scanDoc(cache, root, bundleDir, doc) {
             continue; // governing (same file) carries over unchanged
         }
         const { citedPath, startLine, endLine, anchor } = atom;
-        const citation = `${citedPath}:${startLine}${endLine ? "-" + endLine : ""}`;
+        // 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;
@@ -1236,15 +1837,87 @@ function scanDoc(cache, root, bundleDir, doc) {
             lastStartLine = null;
             continue;
         }
-        const problem = checkFullTarget(citedPath, startLine, endLine, resolution.path, anchor);
+        // 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");
+        }
+        // anchor-required (opt-in, warning): see the "Anchor strictness
+        // (opt-in)" doc block above. Gated on the same posture every other
+        // per-atom check already uses (only reached once the citation resolved
+        // to a real, unambiguous, non-skipped target), plus a reserved citing
+        // doc (e.g. log.md, folded into requireAnchorsForDoc above) and an
+        // allowlisted citedPath being exempt.
+        if (requireAnchorsForDoc &&
+            !anchor &&
+            !matchesAllowPattern(citedPath, requireAnchorsForDoc.allow)) {
+            pushDrift(findings, doc.relPath, citation, "anchor-required", `full citation into an in-repo file carries no #anchor (--require-anchors is on)`, path.relative(root, resolution.path));
+        }
+        const problems = checkFullTarget(citedPath, startLine, endLine, resolution.path, anchor, requireAnchorsForDoc);
+        for (const problem of problems) {
+            if (problem.rule === "unreadable-target") {
+                pushUnreadable(findings, doc.relPath, citation, path.relative(root, resolution.path), problem.code ?? "UNKNOWN");
+            }
+            else {
+                pushDrift(findings, doc.relPath, citation, problem.rule, problem.message, path.relative(root, resolution.path));
+            }
+        }
+        governing = { citedPath, resolvedPath: resolution.path };
+        lastStartLine = startLine;
+    }
+    // Heading-section citations -- see the "Heading-section citations" doc
+    // block above. Independent of `governing`/`lastStartLine`/`fullAtoms`:
+    // this form carries its own path on every citation (never a continuation
+    // or short form), so there is nothing to chain off. Iterates over
+    // `headingSectionMatches`, collected up front (see above), rather than
+    // re-scanning `content` with the regex a second time.
+    for (const hs of headingSectionMatches) {
+        const citedPath = hs.citedPath;
+        const headingAnchor = hs.headingAnchor;
+        const contentAnchor = hs.contentAnchor;
+        const citation = `${citedPath}:${formatAnchorForLabel(headingAnchor)}${contentAnchor ? formatAnchorForLabel(contentAnchor) : ""}`;
+        if (hasParentSegment(citedPath)) {
+            pushDrift(findings, doc.relPath, citation, "path-traversal-rejected", `citedPath contains a ".." segment and was rejected without resolving: ${citedPath}`);
+            continue;
+        }
+        const resolution = resolveCitation(cache, root, docAbsPath, content, sources, citedPath, hs.index);
+        if (!resolution) {
+            pushDrift(findings, doc.relPath, citation, "missing-file", `could not resolve ${citedPath}: 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 = checkHeadingSectionTarget(headingAnchor, contentAnchor, 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));
         }
-        governing = { citedPath, resolvedPath: resolution.path };
-        lastStartLine = startLine;
+    }
+    // heading-section-malformed (notice): a backtick + path + `:#` opener
+    // that did not parse as a well-formed heading-section citation above --
+    // mirrors `anchor-malformed`'s posture for the line-range anchor form
+    // (see `extractMalformedAnchorRaw`'s doc comment): a typo should not
+    // silently vanish from the very check it was written to exercise.
+    for (const hm of headingSectionMalformedMatches) {
+        // `hm.raw` includes the delimiting backticks (the regex match itself);
+        // the citation label, like every other citation label in this file,
+        // does not repeat them -- pushDrift's message template already wraps
+        // the label in its own pair.
+        const inner = hm.raw.slice(1, -1);
+        pushDrift(findings, doc.relPath, inner, "heading-section-malformed", `a backtick-delimited "path:#" heading-section citation opener does not parse as a well-formed citation (raw: "${inner}")`, undefined, "notice");
     }
     // Short-form (paragraph-bound) citations -- see that doc block above.
     // Deliberately independent of `governing`/`lastStartLine`: short-form
@@ -1314,7 +1987,7 @@ function scanDoc(cache, root, bundleDir, doc) {
 }
 export const citationsResolveRule = {
     id: RULE_ID,
-    description: "`path:N`/`path:N-M` citations (and their `:N`, -`M`/–`M`, (`N`) continuations) must resolve to a real target file and land on real, non-blank content. Mechanical only: does not verify the cited line is semantically correct.",
+    description: "`path:N`/`path:N-M` citations (and their `:N`, -`M`/–`M`, (`N`) continuations), and backtick-delimited `` `path:#heading` `` heading-section citations (`.md` targets only), must resolve to a real target file and land on real, non-blank content. Mechanical only: does not verify the cited line is semantically correct.",
     run(ctx) {
         if (!ctx.repoRoot) {
             // Never silently skip: mirrors sources-fresh's posture so a "clean"
@@ -1333,7 +2006,7 @@ export const citationsResolveRule = {
         // Fresh per invocation: see findByBasename's doc comment for why this
         // is not held at module scope.
         const cache = new Map();
-        return ctx.docs.flatMap((doc) => scanDoc(cache, root, ctx.bundleDir, doc));
+        return ctx.docs.flatMap((doc) => scanDoc(cache, root, ctx.bundleDir, doc, ctx.requireAnchors));
     },
 };
 //# sourceMappingURL=citations-resolve.js.map