@redocly/recheck 0.1.0 → 0.2.0

package/dist/rules/scope/consistency.js

@@ -0,0 +1,178 @@
+import { formatTemplate } from '../token/messages.js';
+import { newLineRe, offsetToLineColumn } from '../../core/line-endings.js';
+import { applyMatchCase } from '../../core/case-preserve.js';
+// Mechanical proxy for "is this pair a same-word normalization (safe to
+// rewrite blindly) or a substitution that can expand ambiguously (not
+// safe)?" -- same shape as applyMatchCase's multi-word guard in
+// case-preserve.ts: a checkable structural property (word count) that
+// correlates with the semantic hazard, rather than an attempt to
+// understand the words themselves. `colour`/`color` is one word either
+// way. `it's`/`it is` is one word vs. two -- and that word-count jump is
+// exactly where the ambiguity lives: `it's` expands to EITHER "it is" OR
+// "it has", so picking "it is" as the winner and rewriting every "it's" to
+// it is flat wrong whenever the source meant "it has" (see this file's
+// fix() doc comment and the bug this guard closes: "It is fine. ... it's
+// been growing for hours." -> "it is been growing for hours."). Splitting
+// on whitespace is deliberately simple -- like applyMatchCase's `/\s/`
+// check, it does not try to be a linguistic word tokenizer, just a cheap,
+// reliable signal for "the replacement isn't shaped like the match
+// any more."
+//
+// KNOWN EDGE, not fixed here (false positive, accepted cost): this guard
+// cannot distinguish "crosses a word boundary AND is ambiguous" (`it's` ->
+// EITHER "it is" or "it has") from "crosses a word boundary but has only
+// ONE possible expansion" (`don't` -> always "do not", never anything
+// else). `microsoft/contraction-consistency` ships exactly this shape
+// alongside `it's`/`it is`: `don't`/`do not`, `won't`/`will not`, and
+// `isn't`/`is not` are each a single, unambiguous contraction/expansion
+// pair (1 word vs. 2), and this guard blocks fixing all three, same as it
+// blocks `it's`/`it is` -- even though, unlike `it's`, none of them has a
+// second meaning a blind rewrite could pick wrong. `can't`/`cannot` is the
+// one pair in that same rule the guard does NOT block, only because
+// "cannot" happens to be written as one word rather than two ("can not"
+// would trip the guard identically, despite being just as unambiguous as
+// "do not"). Word count is a proxy for "may be ambiguous," not a test of
+// ambiguity itself, so it necessarily also catches unambiguous pairs that
+// merely happen to differ in word count -- the same shape as
+// applyMatchCase's own accepted edge (a hyphen-only replacement counts as
+// "one word" and still gets shouted). Narrowing further (e.g. a hand-listed
+// exception for "known-unambiguous" contractions) would repeat the exact
+// per-pair-criterion pattern this whole change retires elsewhere in this
+// package -- so the false positive is accepted, not patched, and recorded
+// here so it is a known trade-off rather than an undocumented side effect.
+function wordCount(text) {
+    return text.trim().split(/\s+/).filter(Boolean).length;
+}
+// On the segment's first line, segment.content starts mid-source-line (e.g.
+// a heading's content excludes the '## ' marker), so segment.startColumn
+// must be added -- see pattern.ts's toSourceColumn.
+function toSourceColumn(segment, localLine, localColumn) {
+    return localLine === 1 ? segment.startColumn + (localColumn - 1) : localColumn;
+}
+// Fallback when a programmatically-built rule has no `message` (validate()
+// requires one). %s slots: matched text, then the first-seen winner.
+const FALLBACK_MESSAGE = 'Inconsistent spelling: "%s" conflicts with first-seen "%s".';
+// Shared by execute() and fix(). For each `either` pair, scans ALL segments
+// for BOTH variants (regex-escaped literals with \b word boundaries, like
+// `swap` keys), maps every match to its absolute source position, then:
+//
+// 1. Dedupes by `line:column:variant` BEFORE deciding the winner:
+//    overlapping scopes (e.g. `[paragraph, sentence]`) match the same
+//    source occurrence once per covering segment, double-counting it and
+//    scrambling which variant looks 'first'.
+// 2. Sorts by (line, column): the winner is the first match in SOURCE
+//    ORDER, file-wide -- not collection order, which scans the pair's key
+//    before its value and would always crown the key.
+//
+// Every later match of the OTHER (losing) variant yields one site.
+function collectMatches(rule, ctx) {
+    const options = (rule.assertions['consistency'] ?? {});
+    const flags = options.ignoreCase ? 'gi' : 'g';
+    const sites = [];
+    for (const [key, value] of Object.entries(options.either ?? {})) {
+        // Same-word-count guard, computed once per PAIR (not per occurrence):
+        // whichever variant wins first-seen, a fix is only offered when the key
+        // and value are the same number of words. See wordCount()'s doc comment
+        // above for why a word-count mismatch (e.g. `it's` vs. `it is`) is
+        // exactly where a contraction's ambiguous expansion lives.
+        const fixable = wordCount(key) === wordCount(String(value));
+        const seen = new Set();
+        const matches = [];
+        for (const variant of [key, String(value)]) {
+            // An empty variant (only reachable when a caller bypasses validate())
+            // would escape to the zero-width `\b\b`, matching nearly every
+            // position and spuriously winning as "first-seen". Skip it.
+            if (variant.length === 0)
+                continue;
+            // Same escaping as swap keys: variants are literals, so regex
+            // metacharacters (e.g. 'e.g.') must not act as syntax.
+            const escaped = variant.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const regex = new RegExp(`\\b${escaped}\\b`, flags);
+            for (const segment of ctx.segments) {
+                // newLineRe, not '\n': a bare split leaves a trailing '\r' on CRLF content.
+                const contentLines = segment.content.split(newLineRe);
+                regex.lastIndex = 0;
+                let match;
+                while ((match = regex.exec(segment.content)) !== null) {
+                    // No zero-width guard needed (unlike swap/conditional/repetition):
+                    // the empty-variant skip above guarantees `escaped` is a non-empty
+                    // literal, and \b...\b only adds zero-width assertions around it,
+                    // so `match[0]` can never be empty here.
+                    const local = offsetToLineColumn(segment.content, match.index);
+                    const line = segment.startLine + local.line - 1;
+                    const column = toSourceColumn(segment, local.line, local.column);
+                    const positionKey = `${line}:${column}:${variant}`;
+                    if (seen.has(positionKey))
+                        continue; // overlapping segments, same source occurrence
+                    seen.add(positionKey);
+                    matches.push({
+                        line,
+                        column,
+                        text: match[0],
+                        lineText: contentLines[local.line - 1] ?? '',
+                        variant,
+                    });
+                }
+            }
+        }
+        if (matches.length === 0)
+            continue;
+        matches.sort((a, b) => a.line - b.line || a.column - b.column);
+        const winner = matches[0].variant;
+        for (const found of matches) {
+            if (found.variant !== winner) {
+                sites.push({
+                    line: found.line,
+                    column: found.column,
+                    text: found.text,
+                    lineText: found.lineText,
+                    winner,
+                    fixable,
+                });
+            }
+        }
+    }
+    // Pairs are processed one at a time, so multi-pair results arrive grouped
+    // by pair; re-sort so problems/fixes read in source order.
+    sites.sort((a, b) => a.line - b.line || a.column - b.column);
+    return sites;
+}
+const execute = async (rule, file, ctx) => {
+    return collectMatches(rule, ctx).map((site) => ({
+        file,
+        line: site.line,
+        column: site.column,
+        text: site.lineText,
+        match: site.text,
+        ruleName: rule.name,
+        severity: rule.severity,
+        message: formatTemplate(rule.message ?? FALLBACK_MESSAGE, site.text, site.winner),
+    }));
+};
+const fix = async (rule, file, ctx) => {
+    // Same-word-count guard (see wordCount()'s doc comment above): a
+    // different-word-count pair (e.g. `it's`/`it is`) still gets REPORTED by
+    // execute() above -- collectMatches() doesn't distinguish the two
+    // functions -- but must never be auto-fixed, so it's filtered out here,
+    // after collection, rather than skipped during collection itself.
+    return collectMatches(rule, ctx)
+        .filter((site) => site.fixable)
+        .map((site) => ({
+        file,
+        ruleName: rule.name,
+        lineNumber: site.line,
+        editColumn: site.column,
+        deleteCount: site.text.length,
+        // Apply the MATCHED text's observed casing to the winner, not the
+        // winner as authored in config: with `ignoreCase: true`, a
+        // sentence-initial 'Behaviour' would otherwise be replaced by the
+        // literal (lowercase-first) authored winner 'behavior', silently
+        // lowercasing the start of the sentence -- the exact hazard
+        // applyMatchCase exists to prevent, and swap.ts:177 already guards
+        // against for the `swap` assertion. `consistency` shares the same
+        // ignoreCase/fix shape, so it needs the same guard.
+        insertText: applyMatchCase(site.text, site.winner),
+    }));
+};
+export const consistency = { id: 'consistency', fixable: true, execute, fix };
+//# sourceMappingURL=consistency.js.map

package/dist/rules/scope/consistency.js.map

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

package/dist/rules/scope/length.d.ts

@@ -0,0 +1,3 @@
+import type { ScopeRule } from '../types.js';
+export declare const length: ScopeRule;
+//# sourceMappingURL=length.d.ts.map

package/dist/rules/scope/length.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"length.d.ts","sourceRoot":"","sources":["../../../src/rules/scope/length.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,aAAa,CAAC;AAsF/D,eAAO,MAAM,MAAM,EAAE,SAAqD,CAAC"}

package/dist/rules/scope/length.js

@@ -0,0 +1,69 @@
+import { formatTemplate } from '../token/messages.js';
+import { newLineRe } from '../../core/line-endings.js';
+import { splitSentences } from '../../scopes/sentences.js';
+import { tokenizeWords } from '../../metrics/statistics.js';
+const FALLBACK_MAX = 'Segment is %s %s; at most %s allowed';
+const FALLBACK_MIN = 'Segment is %s %s; at least %s required';
+// Single measurement helper, used by nothing else: `sentences` delegates to
+// the shared sentence-boundary definition (scopes/sentences.ts), and `words`
+// delegates to the metrics module's own tokenizer (see its export-site
+// comment for why sharing that implementation with `metric` matters).
+//
+// `characters` takes the whole segment, not just its content, because a masked
+// markdoc tag's span is blanked to same-width spaces rather than removed.
+// `tokenizeWords` and `splitSentences` already read through that mask
+// correctly, treating a run of blanks as a gap like real whitespace, but a raw
+// `content.length` would count those invisible characters as visible prose:
+// `# Head text {% #averylonganchorname %}` measured 36 characters for the 10 a
+// reader actually sees. Subtracting each masked span's width corrects the
+// count. A segment that was never masked has no `maskedRanges`, so this is
+// exactly `content.length`.
+function measure(segment, unit) {
+    const { content } = segment;
+    if (unit === 'characters') {
+        const maskedWidth = (segment.maskedRanges ?? []).reduce((total, range) => total + (range.end - range.start), 0);
+        return content.length - maskedWidth;
+    }
+    if (unit === 'sentences')
+        return splitSentences(content).length;
+    return tokenizeWords(content).length;
+}
+// Recheck-original `length` check: measures each scoped segment's size and
+// flags it when the measurement falls outside `[min, max]`. Detection-only
+// -- like `occurrence`, a size violation has no single position to anchor
+// an edit to (shrinking or growing a segment to fit is an editorial
+// decision, not a mechanical rewrite). Unlike `metric`, this honors
+// whichever `scope` the rule configures -- e.g. `scope: alt` to cap image
+// alt text length, `scope: sentence` to cap sentence length in words.
+const execute = async (rule, file, ctx) => {
+    const problems = [];
+    const o = rule.assertions['length'];
+    for (const segment of ctx.segments) {
+        const size = measure(segment, o.unit);
+        const tooSmall = o.min !== undefined && size < o.min;
+        const tooLarge = o.max !== undefined && size > o.max;
+        if (!tooSmall && !tooLarge)
+            continue;
+        // Picking `tooSmall`'s branch first is only exhaustive because
+        // validate() rejects `min > max`, so a segment can never be both
+        // tooSmall and tooLarge at once -- a hand-built rule that skips
+        // validate() must preserve that invariant itself or this silently
+        // reports the wrong bound.
+        const bound = tooSmall ? o.min : o.max;
+        problems.push({
+            file,
+            line: segment.startLine,
+            column: segment.startColumn,
+            // newLineRe, not '\n': a bare split leaves a trailing '\r' on CRLF
+            // content (see occurrence.ts).
+            text: segment.content.split(newLineRe)[0] ?? '',
+            match: String(size),
+            ruleName: rule.name,
+            severity: rule.severity,
+            message: formatTemplate(rule.message ?? (tooSmall ? FALLBACK_MIN : FALLBACK_MAX), String(size), o.unit, String(bound)),
+        });
+    }
+    return problems;
+};
+export const length = { id: 'length', fixable: false, execute };
+//# sourceMappingURL=length.js.map

package/dist/rules/scope/length.js.map

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

package/dist/rules/scope/max-image-size.d.ts

@@ -0,0 +1,3 @@
+import type { ScopeRule } from '../types.js';
+export declare const maxImageSize: ScopeRule;
+//# sourceMappingURL=max-image-size.d.ts.map

package/dist/rules/scope/max-image-size.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"max-image-size.d.ts","sourceRoot":"","sources":["../../../src/rules/scope/max-image-size.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,aAAa,CAAC;AA0F/D,eAAO,MAAM,YAAY,EAAE,SAA6D,CAAC"}

package/dist/rules/scope/max-image-size.js

@@ -0,0 +1,65 @@
+import { newLineRe } from '../../core/line-endings.js';
+import { getImageDestinations, hasOverlap } from '../token/helpers.js';
+function getFileExtension(filePath) {
+    const lastDot = filePath.lastIndexOf('.');
+    return lastDot === -1 ? '' : filePath.substring(lastDot + 1).toLowerCase();
+}
+// `ctx.segments` is a single synthetic `scope: 'all'` segment (see
+// `wholeFileSegment` in core/runner.ts) exactly when the rule is unscoped
+// (the default) — `extractScopes` itself never emits a segment with that
+// scope name, so this check is an unambiguous whole-file-vs-scoped
+// discriminator, matching the convention documented for scope rules in
+// rules/CONTRIBUTING.md ("Unscoped rules (`scope: all`, the default):
+// `ctx.segments` is a single whole-file segment with `scope: 'all'`").
+function isWholeFile(segments) {
+    return segments.length === 1 && segments[0].scope === 'all';
+}
+const execute = async (rule, file, ctx) => {
+    const problems = [];
+    const options = rule.assertions['max-image-size'];
+    const maxSizeKB = options?.maxSizeKB ?? 100;
+    const allowedExtensions = new Set(options?.extensions ?? ['jpg', 'jpeg', 'png', 'gif', 'webp', 'svg']);
+    const maxSizeBytes = maxSizeKB * 1024;
+    // Reference-style destinations (`![alt][ref]`) resolve against
+    // definitions anywhere in the document, so resolution always runs over
+    // the whole tree; only the resulting image tokens are scope-filtered
+    // below, matching how every other scope rule narrows to `ctx.segments`
+    // without re-deriving cross-references itself.
+    const wholeFile = isWholeFile(ctx.segments);
+    const images = getImageDestinations(ctx.tree).filter(({ token }) => wholeFile || ctx.segments.some((segment) => hasOverlap(segment, token)));
+    // newLineRe (never a bare '\n'): these lines feed Problem.text, and a
+    // '\n' split of CRLF content would leave a trailing '\r' on each one.
+    const lines = ctx.content.split(newLineRe);
+    for (const { token, destination } of images) {
+        if (destination.startsWith('http://') || destination.startsWith('https://')) {
+            continue;
+        }
+        const extension = getFileExtension(destination);
+        if (!allowedExtensions.has(extension)) {
+            continue;
+        }
+        const imageMetadata = ctx.fileMetadata?.images?.get(destination);
+        if (!imageMetadata) {
+            continue;
+        }
+        if (!imageMetadata.exists) {
+            continue;
+        }
+        if (imageMetadata.size > maxSizeBytes) {
+            const actualSizeKB = Math.round(imageMetadata.size / 1024);
+            problems.push({
+                file,
+                line: token.startLine,
+                column: token.startColumn,
+                text: lines[token.startLine - 1] || '',
+                match: token.text,
+                ruleName: rule.name,
+                severity: rule.severity,
+                message: (rule.message ?? '').replace('%s', `${destination} (${actualSizeKB}KB > ${maxSizeKB}KB)`),
+            });
+        }
+    }
+    return problems;
+};
+export const maxImageSize = { id: 'max-image-size', fixable: false, execute };
+//# sourceMappingURL=max-image-size.js.map

package/dist/rules/scope/max-image-size.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"max-image-size.js","sourceRoot":"","sources":["../../../src/rules/scope/max-image-size.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEvE,SAAS,gBAAgB,CAAC,QAAgB;IACxC,MAAM,OAAO,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1C,OAAO,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;AAC7E,CAAC;AAED,mEAAmE;AACnE,0EAA0E;AAC1E,yEAAyE;AACzE,mEAAmE;AACnE,uEAAuE;AACvE,sEAAsE;AACtE,uEAAuE;AACvE,SAAS,WAAW,CAAC,QAAyB;IAC5C,OAAO,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC;AAC9D,CAAC;AAED,MAAM,OAAO,GAAG,KAAK,EACnB,IAAoB,EACpB,IAAY,EACZ,GAAqB,EACD,EAAE;IACtB,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAA0B,CAAC;IAE3E,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,GAAG,CAAC;IAC5C,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAC/B,OAAO,EAAE,UAAU,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CACpE,CAAC;IACF,MAAM,YAAY,GAAG,SAAS,GAAG,IAAI,CAAC;IAEtC,+DAA+D;IAC/D,uEAAuE;IACvE,qEAAqE;IACrE,uEAAuE;IACvE,+CAA+C;IAC/C,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,CAClD,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,SAAS,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CACvF,CAAC;IAEF,sEAAsE;IACtE,sEAAsE;IACtE,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAE3C,KAAK,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,MAAM,EAAE,CAAC;QAC5C,IAAI,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,WAAW,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC5E,SAAS;QACX,CAAC;QAED,MAAM,SAAS,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;QAChD,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACtC,SAAS;QACX,CAAC;QAED,MAAM,aAAa,GAAG,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;QAEjE,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,SAAS;QACX,CAAC;QAED,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,CAAC;YAC1B,SAAS;QACX,CAAC;QAED,IAAI,aAAa,CAAC,IAAI,GAAG,YAAY,EAAE,CAAC;YACtC,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;YAC3D,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI;gBACJ,IAAI,EAAE,KAAK,CAAC,SAAS;gBACrB,MAAM,EAAE,KAAK,CAAC,WAAW;gBACzB,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE;gBACtC,KAAK,EAAE,KAAK,CAAC,IAAI;gBACjB,QAAQ,EAAE,IAAI,CAAC,IAAI;gBACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,OAAO,CACnC,IAAI,EACJ,GAAG,WAAW,KAAK,YAAY,QAAQ,SAAS,KAAK,CACtD;aACF,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAc,EAAE,EAAE,EAAE,gBAAgB,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC"}

package/dist/rules/scope/metric.d.ts

@@ -0,0 +1,17 @@
+import type { ScopeRule } from '../types.js';
+/**
+ * Strips markup that is never readable prose (Markdoc tag markers, inline
+ * code spans) from RAW segment text -- i.e. text that has not already been
+ * structurally masked, see `MARKDOC_TAG_RE`'s comment. Inline code spans
+ * are REMOVED outright (not masked-and-restored like
+ * capitalization.ts/spelling.ts do): there is no position-sensitive rewrite
+ * downstream to keep offsets aligned for, just a word/syllable count that
+ * must never include a code span's content. BACKTICK_SPAN_RE
+ * (core/inline-code.ts) gives this the same CommonMark-correct
+ * open-run/close-run-of-equal-length span recognition capitalization.ts and
+ * spelling.ts use, including a span whose content itself contains a
+ * shorter, unpaired backtick run. Exported for direct unit testing.
+ */
+export declare function stripNonProse(text: string): string;
+export declare const metric: ScopeRule;
+//# sourceMappingURL=metric.d.ts.map

package/dist/rules/scope/metric.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric.d.ts","sourceRoot":"","sources":["../../../src/rules/scope/metric.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,aAAa,CAAC;AAwB/D;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AA4MD,eAAO,MAAM,MAAM,EAAE,SAAqD,CAAC"}

package/dist/rules/scope/metric.js

@@ -0,0 +1,216 @@
+import { formatTemplate } from '../token/messages.js';
+import { computeTextStatistics, computeReadability } from '../../metrics/index.js';
+import { BACKTICK_SPAN_RE } from '../../core/inline-code.js';
+/**
+ * Markdoc tag-marker spans -- `{% tag attr="x" %}`, `{% /tag %}`, and the
+ * `{%- ... -%}` whitespace-trim variant. Non-greedy (`[\s\S]*?`) so it stops
+ * at the NEAREST `%}`: back-to-back tags like `{% admonition %}` ...
+ * `{% /admonition %}` each strip as their OWN span rather than one tag's
+ * opener swallowing everything up to the other tag's closer -- which would
+ * delete the prose BETWEEN them too.
+ *
+ * Only used when markdoc parsing is off. With it on, `maskProse` in
+ * scopes/extractor.ts has already found every real `markdocTag` token and
+ * recorded its exact span in the segment's `maskedRanges`, so `extractProse`
+ * below splices those spans out instead of re-discovering tags with this
+ * regex. The regex is still needed with the flag off: the parser doesn't
+ * recognize tags at all in that mode, so `{% ... %}` is just ordinary text and
+ * nothing else keeps it out of the readability formulas.
+ */
+const MARKDOC_TAG_RE = /\{%-?[\s\S]*?-?%\}/g;
+/**
+ * Strips markup that is never readable prose (Markdoc tag markers, inline
+ * code spans) from RAW segment text -- i.e. text that has not already been
+ * structurally masked, see `MARKDOC_TAG_RE`'s comment. Inline code spans
+ * are REMOVED outright (not masked-and-restored like
+ * capitalization.ts/spelling.ts do): there is no position-sensitive rewrite
+ * downstream to keep offsets aligned for, just a word/syllable count that
+ * must never include a code span's content. BACKTICK_SPAN_RE
+ * (core/inline-code.ts) gives this the same CommonMark-correct
+ * open-run/close-run-of-equal-length span recognition capitalization.ts and
+ * spelling.ts use, including a span whose content itself contains a
+ * shorter, unpaired backtick run. Exported for direct unit testing.
+ */
+export function stripNonProse(text) {
+    return text.replace(MARKDOC_TAG_RE, '').replace(BACKTICK_SPAN_RE, '');
+}
+/**
+ * Counterpart to `stripNonProse` for a masked segment: its tag spans are
+ * already known exactly (`segment.maskedRanges`, set by `maskProse` only when
+ * it actually blanked something), so this splices each span out of `content`
+ * rather than leaving the mask's same-width spaces in place.
+ *
+ * Deletion, not blanking, matters here. `length.ts`'s `measure()` only needs a
+ * width to subtract from a character count, so reading through the mask as if
+ * it were whitespace is harmless there. `metric` tokenizes words by splitting
+ * on whitespace, so mask spaces are not interchangeable with deletion whenever
+ * a tag sits flush against real text with no separating space — for example
+ * `<code>{% $optionName %}</code>`, a shape that occurs in the repo's own docs.
+ * Left as mask spaces, `<code>` and `</code>` tokenize as two separate words;
+ * deleting the span joins them back into the single adjacent run they actually
+ * are. Splicing reproduces exactly what the regex strip did on unmasked source.
+ */
+function spliceOutMaskedSpans(segment) {
+    const ranges = segment.maskedRanges;
+    if (ranges === undefined)
+        return segment.content;
+    let result = '';
+    let cursor = 0;
+    for (const range of ranges) {
+        // `maskedRanges` is produced ascending and non-overlapping (maskProse
+        // sorts and clamps; shiftRanges preserves order). The clamp here mirrors
+        // maskProse's own defense: an out-of-order range would otherwise move
+        // `cursor` backward and re-emit already-copied characters.
+        result += segment.content.slice(cursor, Math.max(range.start, cursor));
+        cursor = Math.max(range.end, cursor);
+    }
+    return result + segment.content.slice(cursor);
+}
+const FALLBACK_MESSAGE = 'Readability (%s) is %s; expected between %s and %s.';
+// Compares two (line, column) source positions the way source order does:
+// earlier line first, then earlier column on the same line.
+function comparePosition(aLine, aColumn, bLine, bColumn) {
+    return aLine - bLine || aColumn - bColumn;
+}
+/**
+ * Whether `outer`'s span fully contains `inner`'s -- `outer` starts at or
+ * before `inner` and ends at or after it. `startLine`/`startColumn`/
+ * `endLine`/`endColumn` are already the exact verbatim source span each
+ * segment's `content` covers (see extractor.ts's `segmentFromToken` and the
+ * `tableRow` case's explicit anchor/trim arithmetic), so containment can be
+ * decided directly from those four numbers -- no separate span needs
+ * re-deriving from `content` (e.g. via counting newlines) here.
+ */
+function spanContains(outer, inner) {
+    return (comparePosition(outer.startLine, outer.startColumn, inner.startLine, inner.startColumn) <= 0 &&
+        comparePosition(outer.endLine, outer.endColumn, inner.endLine, inner.endColumn) >= 0);
+}
+/**
+ * Dedupes prose segments whose source span is fully nested inside another
+ * kept segment's span. A list nested inside a blockquote emits BOTH the
+ * blockquote segment (its whole raw body, list markup and all) AND each
+ * list-item segment (the same words again, just the item's own subspan);
+ * a blockquote nested inside another blockquote is the same shape one
+ * level up. Left uncaught, the nested words are scored twice and
+ * readability drifts. The old dedup only matched IDENTICAL start
+ * positions, which misses every one of these cases (the nested segment
+ * starts later than its container).
+ *
+ * Segments are sorted by (startLine, startColumn) ascending so a container
+ * is always visited before anything nested inside it; ties (a container
+ * and its first child starting at the exact same position, e.g. a
+ * blockquote and its very first list item) are broken by span
+ * DESCENDING -- the later-ending segment first -- so the outer container is
+ * always the one considered "already kept" when its nested sibling is
+ * checked, never the other way around.
+ *
+ * `stack` holds the chain of still-open containers, innermost last. Only
+ * the top is ever checked against a new candidate: markdown block spans
+ * form a laminar family (any two are either disjoint or one fully
+ * contains the other, never a partial "crossing" overlap), so once
+ * containers whose span has already ended (`end < candidate.start`) are
+ * popped off, the remaining top is the ONLY still-open span the next
+ * candidate could possibly nest inside. This is what keeps same-line
+ * SIBLINGS with disjoint spans (e.g. two table cells on one row) safe:
+ * each one's span ends before the next one's begins, so it is popped
+ * before the next is checked, and neither is ever mistaken for containing
+ * the other.
+ */
+function dedupeBySpanContainment(segments) {
+    const ordered = [...segments].sort((a, b) => {
+        const byStart = comparePosition(a.startLine, a.startColumn, b.startLine, b.startColumn);
+        if (byStart !== 0)
+            return byStart;
+        return comparePosition(b.endLine, b.endColumn, a.endLine, a.endColumn);
+    });
+    const stack = [];
+    const kept = [];
+    for (const segment of ordered) {
+        while (stack.length > 0) {
+            const top = stack[stack.length - 1];
+            if (comparePosition(top.endLine, top.endColumn, segment.startLine, segment.startColumn) < 0) {
+                stack.pop();
+            }
+            else {
+                break;
+            }
+        }
+        const container = stack[stack.length - 1];
+        if (container && spanContains(container, segment))
+            continue;
+        kept.push(segment);
+        stack.push(segment);
+    }
+    return kept;
+}
+/**
+ * Builds the whole-document prose string `metric` scores against, from
+ * `ctx.segments`.
+ *
+ * `metric` rules are always summary-scoped: config normalization
+ * (config/validate.ts, normalizeMetricScope) forces `scope: 'summary'` on
+ * every rule with a `metric` assertion — readability is a whole-document
+ * score over the document's prose, exactly what the extractor's `summary`
+ * segments carry — so `ctx.segments` arrives as those summary segments and
+ * no scope re-extraction happens here. See the README's `metric` entry.
+ */
+function extractProse(ctx) {
+    // Span-containment dedup: a segment fully nested inside another kept
+    // segment's source span must not have its text counted a second time --
+    // see dedupeBySpanContainment. The extractor already avoids the most
+    // common case on its own (see its `isNestedContainerParagraph`), but
+    // this catches every other overlap among the summary segments too
+    // (e.g. a list nested inside a blockquote).
+    const deduped = dedupeBySpanContainment(ctx.segments);
+    // Re-sort explicitly so the joined prose's sentence order can never
+    // depend on the extractor's traversal order (or dedupeBySpanContainment's
+    // own tie-breaking order, which favors span DESC, not source order).
+    deduped.sort((a, b) => a.startLine - b.startLine || a.startColumn - b.startColumn);
+    return deduped
+        .map((segment) => segment.maskedRanges !== undefined
+        ? // This segment's tag spans are already known exactly, so splice them
+            // out directly instead of re-discovering them with MARKDOC_TAG_RE,
+            // which couldn't match them anyway now that their `{`/`%` characters
+            // are mask spaces. Backtick stripping still runs: masking never
+            // touches inline code spans.
+            spliceOutMaskedSpans(segment).replace(BACKTICK_SPAN_RE, '')
+        : // Markdoc parsing off, or a tag the extractor never recognized as one
+            // (e.g. written inside an inline code span): content still carries
+            // whatever raw markup it always did, so fall back to the regex-based
+            // strip.
+            stripNonProse(segment.content))
+        .join('\n');
+}
+const execute = async (rule, file, ctx) => {
+    const options = rule.assertions['metric'];
+    const prose = extractProse(ctx);
+    const stats = computeTextStatistics(prose);
+    // computeReadability returns 0 for zero words/sentences as a "not enough
+    // text to score" placeholder (see metrics/formulas.ts), not a genuine
+    // score -- a file with no prose must never be flagged as "too low", so
+    // skip the bounds check entirely.
+    if (stats.words === 0 || stats.sentences === 0)
+        return [];
+    const score = computeReadability(options.formula, stats);
+    const tooLow = options.min !== undefined && score < options.min;
+    const tooHigh = options.max !== undefined && score > options.max;
+    if (!tooLow && !tooHigh)
+        return [];
+    // Detection-only, whole-document: always exactly one problem, always at
+    // line 1 column 1 -- there is no single source position a readability
+    // score "belongs" to.
+    return [
+        {
+            file,
+            line: 1,
+            column: 1,
+            text: '',
+            match: '',
+            ruleName: rule.name,
+            severity: rule.severity,
+            message: formatTemplate(rule.message ?? FALLBACK_MESSAGE, options.formula, String(score), options.min !== undefined ? String(options.min) : '-∞', options.max !== undefined ? String(options.max) : '∞'),
+        },
+    ];
+};
+export const metric = { id: 'metric', fixable: false, execute };
+//# sourceMappingURL=metric.js.map

package/dist/rules/scope/metric.js.map

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

package/dist/rules/scope/occurrence.d.ts

@@ -0,0 +1,3 @@
+import type { ScopeRule } from '../types.js';
+export declare const occurrence: ScopeRule;
+//# sourceMappingURL=occurrence.d.ts.map

package/dist/rules/scope/occurrence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"occurrence.d.ts","sourceRoot":"","sources":["../../../src/rules/scope/occurrence.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAoB,MAAM,aAAa,CAAC;AA2D/D,eAAO,MAAM,UAAU,EAAE,SAAyD,CAAC"}