qa: expand rule tests, fix rules and docs

- Add unit tests for fixInfo and edge cases across custom rules.
- fenced-code-under-heading: require H2–H6 in range above blocks; no-heading-like-lines: avoid matching **:**; one-sentence-per-line fixes.
- README and markdownlint-rules README: fixture wording, Node.js/utils.js formatting; expected_errors and test-scripts updates.

Author: cypher0n3

README.md

@@ -73,9 +73,7 @@ Lint and docs-as-code tooling: custom [markdownlint](https://github.com/DavidAns
     - Use when: copying the rule files; required by several of the rules above.
 
 - **JS linting** for the rule code: ESLint (recommended + complexity/max-lines + eslint-plugin-security), aligned with the GitHub Actions workflow.
-- **Markdownlint fixture tests**: [md_test_files/](md_test_files/README.md) includes positive_*.
-  md and negative_*.
-  md fixtures with explicit expected errors, verified by `test-scripts/verify_markdownlint_fixtures.py`.
+- **Markdownlint fixture tests**: [md_test_files/](md_test_files/README.md) includes `positive_*.md` and `negative_*.md` fixtures with explicit expected errors, verified by `test-scripts/verify_markdownlint_fixtures.py`.
 - **Rule unit tests**: Node `node:test` unit tests for each custom rule in `test/markdownlint-rules/` (including security tests for defensive regex handling and ReDoS awareness); run with `make test-rules` or `npm run test:rules`.
   CI runs `make test-rules-coverage` (fails if any rule file is below 90% line/statement coverage).
 - **Python unit tests**: `unittest` tests for [test-scripts/](test-scripts/README.md) in `test-scripts/test_*.py`; run with `make test-python`.
@@ -86,8 +84,7 @@ See **[markdownlint-rules/README.md](markdownlint-rules/README.md)** for rule do
 
 ## Requirements
 
-- Node.
-  js and npm (for JS linting)
+- `Node.js` and npm (for JS linting)
 - Python 3 (for repo test scripts and `make lint-python`)
 - [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) and config (`.markdownlint-cli2.jsonc`, `.markdownlint.yml`) when using the custom rules in another repo
 

markdownlint-rules/README.md

@@ -25,10 +25,8 @@ In this repo they are registered in [.markdownlint-cli2.jsonc](../.markdownlint-
 You can reuse any of them in your own project; see [Reusing These Rules](#reusing-these-rules) below.
 Some rules are **fixable** (heading-title-case, ascii-only, heading-numbering, no-heading-like-lines, one-sentence-per-line): they report `fixInfo` so `markdownlint-cli2 --fix` and the editor "Fix all" can apply corrections automatically.
 
-- **Requirements:** Node.
-  js and [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) (or the [markdownlint](https://github.com/DavidAnson/markdownlint) core with custom rule support).
-  When reusing rules, copy any helper files they depend on; see [Shared Helper](#shared-helper) for which rules require **utils.
-    js**.
+- **Requirements:** `Node.js` and [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) (or the [markdownlint](https://github.com/DavidAnson/markdownlint) core with custom rule support).
+  When reusing rules, copy any helper files they depend on; see [Shared Helper](#shared-helper) for which rules require `utils.js`.
 - **Rule modules**: Each `*.js` file here (except `utils.js`) is a custom rule.
 - **Config**: Rule-specific options are set under the rule name in a markdownlint config file.
   You can use `.markdownlint.yml` or `.markdownlint.json` (markdownlint accepts either).
@@ -42,8 +40,7 @@ To use one or more of these rules in another repo:
 1. Create a `.markdownlint-rules` directory in that repo (if it does not exist).
 2. Copy the rule file(s) you want (e.g. `ascii-only.js`, `no-heading-like-lines.js`) into `.markdownlint-rules`.
 3. If a rule depends on helpers, copy those too.
-   Most rules require **utils.
-    js** (see [Shared Helper](#shared-helper) for the full list).
+   Most rules require `utils.js` (see [Shared Helper](#shared-helper) for the full list).
    Copy `utils.js` into `.markdownlint-rules` and do **not** list it in `customRules` (see below).
    **no-heading-like-lines** optionally uses `heading-title-case.js` and `heading-numbering.js` when `convertToHeading: true` (for AP title case and number prefixes); copy those into the same directory only if you want that behavior.
 4. In the repo root, in `.markdownlint-cli2.jsonc` (or your config file), add the rule name(s) to the `customRules` array and set `customRulePaths` so it points at your `.markdownlint-rules` folder (see [markdownlint-cli2 custom rules](https://github.com/DavidAnson/markdownlint-cli2#custom-rules)).
@@ -298,7 +295,8 @@ document-length:
   Must be a positive integer.
 - **`excludePathPatterns`** (list of strings, default none): Glob patterns for file paths where this rule is skipped.
 
-**Behavior:** When the file has more than `maximum` lines, the rule reports a single error on line 1. The message includes the actual line count and the maximum and suggests splitting into smaller files.
+**Behavior:** When the file has more than `maximum` lines, the rule reports a single error on line 1.
+The message includes the actual line count and the maximum and suggests splitting into smaller files.
 
 ### `ascii-only`
 
@@ -634,18 +632,15 @@ one-sentence-per-line:
 
 ## Shared Helper
 
-**utils.
-js** is not a rule; it provides utilities used by all custom rules in this repo.
+`utils.js` is not a rule; it provides utilities used by all custom rules in this repo.
 Do not list it in `customRules` in `.markdownlint-cli2.jsonc`.
 When reusing any rule, copy `utils.js` into your `.markdownlint-rules` (see [Reusing These Rules](#reusing-these-rules)).
 
-**All custom rules in this repo depend on utils.
-js** (for `pathMatchesAny` and/or other helpers): allow-custom-anchors, ascii-only, document-length, fenced-code-under-heading, heading-min-words, heading-numbering, heading-title-case, no-duplicate-headings-normalized, no-empty-heading, no-heading-like-lines, no-h1-content, one-sentence-per-line.
+**All custom rules in this repo depend on `utils.js`** (for `pathMatchesAny` and/or other helpers): allow-custom-anchors, ascii-only, document-length, fenced-code-under-heading, heading-min-words, heading-numbering, heading-title-case, no-duplicate-headings-normalized, no-empty-heading, no-heading-like-lines, no-h1-content, one-sentence-per-line.
 
 **All custom rules accept `excludePathPatterns`** (optional list of glob patterns).
 When the file path matches any pattern, the rule is skipped for that file.
-This uses `pathMatchesAny` from utils.
-js.
+This uses `pathMatchesAny` from `utils.js`.
 
 - **Heading and content:** `extractHeadings`, `iterateNonFencedLines`, `iterateProseLines`, `stripInlineCode`, `parseHeadingNumberPrefix`, `normalizeHeadingTitleForDup`, `normalizedTitleForDuplicate`, `RE_ATX_HEADING`, `RE_NUMBERING_PREFIX`.
 - **Path/glob matching:** `globToRegExp`, `matchGlob`, `pathMatchesAny` - used for `excludePathPatterns` and other path options (e.g. ascii-only `allowedPathPatternsUnicode`).

markdownlint-rules/fenced-code-under-heading.js

@@ -72,14 +72,15 @@ function processAtxLine(trimmed, lineNumber, opts, headings) {
 }
 
 /**
- * Single pass: find all H2–H6 in range and all opening fence lines for configured languages.
+ * Single pass: find all headings in range, all ATX headings (any level), and opening fence lines.
  *
  * @param {string[]} lines
  * @param {{ minHeadingLevel: number, maxHeadingLevel: number, languages: string[] }} opts
- * @returns {{ headings: { lineNumber: number, level: number }[], blocks: { lineNumber: number, language: string }[] }}
+ * @returns {{ headings: { lineNumber: number, level: number }[], allHeadings: { lineNumber: number, level: number }[], blocks: { lineNumber: number, language: string }[] }}
  */
 function findHeadingsAndBlocks(lines, opts) {
   const headings = [];
+  const allHeadings = [];
   const blocks = [];
   const state = { inFence: false, fenceMarker: null, fenceLen: 0 };
 
@@ -92,10 +93,12 @@ function findHeadingsAndBlocks(lines, opts) {
     }
     if (!state.inFence) {
       processAtxLine(trimmed, lineNumber, opts, headings);
+      const m = trimmed.match(RE_ATX);
+      if (m) allHeadings.push({ lineNumber, level: m[1].length });
     }
   }
 
-  return { headings, blocks };
+  return { headings, allHeadings, blocks };
 }
 
 /**
@@ -136,7 +139,7 @@ function findAllBlocks(lines) {
 }
 
 /**
- * For each block, get the last heading (H2–H6 in range) that appears before the block.
+ * For each block, get the last heading (in range) that appears before the block.
  *
  * @param {{ lineNumber: number, level: number }[]} headings - Sorted by lineNumber
  * @param {number} blockLine
@@ -151,6 +154,22 @@ function precedingHeading(headings, blockLine) {
   return last;
 }
 
+/**
+ * Get the immediately preceding heading (any level) before blockLine.
+ *
+ * @param {{ lineNumber: number, level: number }[]} allHeadings - Sorted by lineNumber
+ * @param {number} blockLine
+ * @returns {{ lineNumber: number, level: number }|null}
+ */
+function precedingHeadingAnyLevel(allHeadings, blockLine) {
+  let last = null;
+  for (const h of allHeadings) {
+    if (h.lineNumber >= blockLine) break;
+    last = h;
+  }
+  return last;
+}
+
 /* c8 ignore start -- path filter branches covered by tests; per-file threshold met by other code */
 function shouldSkipFile(filePath, opts) {
   const includePaths = Array.isArray(opts.includePaths) ? opts.includePaths : [];
@@ -162,10 +181,12 @@ function shouldSkipFile(filePath, opts) {
 /* c8 ignore stop */
 
 function reportBlocksWithoutHeading(ctx) {
-  const { blocks, headings, opts, lines, onError } = ctx;
+  const { blocks, allHeadings, opts, lines, onError } = ctx;
   for (const block of blocks) {
-    const headingLine = precedingHeading(headings, block.lineNumber);
-    if (headingLine != null || !opts.requireHeading) continue;
+    const immediate = precedingHeadingAnyLevel(allHeadings, block.lineNumber);
+    if (!opts.requireHeading) continue;
+    const validLevel = immediate != null && immediate.level >= opts.minHeadingLevel && immediate.level <= opts.maxHeadingLevel;
+    if (validLevel) continue;
     onError({
       lineNumber: block.lineNumber,
       detail: `Fenced code block (${block.language}) must have an H${opts.minHeadingLevel}-H${opts.maxHeadingLevel} heading above it.`,
@@ -242,8 +263,8 @@ function ruleFunction(params, onError) {
   if (opts.languages.length === 0 || shouldSkipFile(filePath, opts)) return;
   /* c8 ignore stop */
 
-  const { headings, blocks } = findHeadingsAndBlocks(lines, opts);
-  reportBlocksWithoutHeading({ blocks, headings, opts, lines, onError });
+  const { headings, allHeadings, blocks } = findHeadingsAndBlocks(lines, opts);
+  reportBlocksWithoutHeading({ blocks, allHeadings, opts, lines, onError });
   if (opts.exclusive) {
     const allBlocks = findAllBlocks(lines);
     reportExclusiveViolations({ allBlocks, headings, opts, lines, onError });

markdownlint-rules/no-heading-like-lines.js

@@ -29,10 +29,10 @@ try {
 }
 /* c8 ignore stop */
 
-/** Patterns: [regex, description]. Order matches EXTRACTORS. Includes MD036-style whole-line emphasis. */
+/** Patterns: [regex, description]. Order matches EXTRACTORS. Includes MD036-style whole-line emphasis. Require content (.+ not .*) so **:** does not match. */
 const PATTERNS = [
-  [/^\s*\*\*.*:\*\*\s*$/, "bold with colon inside (**Text:**)"],
-  [/^\s*\*\*.*\*\*:\s*$/, "bold with colon outside (**Text**:)"],
+  [/^\s*\*\*.+:\*\*\s*$/, "bold with colon inside (**Text:**)"],
+  [/^\s*\*\*.+\*\*:\s*$/, "bold with colon outside (**Text**:)"],
   [/^\s*[0-9]+\.\s+\*\*.*\*\*\s*$/, "numbered list with bold (1. **Text**)"],
   [/^\s*\*.*:\*\s*$/, "italic with colon inside (*Text:*)"],
   [/^\s*\*.*\*:\s*$/, "italic with colon outside (*Text*:)"],
@@ -123,66 +123,97 @@ function buildConvertToHeadingInsertText(opts) {
   return headingLine;
 }
 
+/** True when pattern p matched but content is only colon (e.g. **:**); skip reporting. */
+function skipBoldColonOnly(trimmedLine, p, pattern) {
+  if (![0, 1, 6].includes(p)) return false;
+  const reWithGroup = p <= 1 ? EXTRACTORS[p][0] : pattern;
+  const m = trimmedLine.match(reWithGroup);
+  const content = m?.[1];
+  return content != null && (content.trim() === "" || content.trim() === ":");
+}
+
 /**
- * markdownlint rule: flag lines that look like headings but use bold/italic
- * (e.g. **Section:** or 1. **Item**, or MD036-style **Introduction** / *Note*)
- * so they can be converted to proper ATX headings. Supports fixInfo for --fix.
- *
- * @param {object} params - markdownlint params (lines, name, config)
- * @param {function(object): void} onError - Callback to report an error
+ * Find first pattern index that matches and passes skip checks; returns { p, description, extractedTitle } or null.
  */
-function ruleFunction(params, onError) {
+function findHeadingLikeMatch(trimmedLine, punctuationMarks) {
+  for (let p = 0; p < PATTERNS.length; p++) {
+    const [pattern, description] = PATTERNS[p];
+    if (!pattern.test(trimmedLine) || skipBoldColonOnly(trimmedLine, p, pattern)) continue;
+    const extractedTitle = extractTitleFromHeadingLike(trimmedLine, p);
+    if (MD036_STYLE_PATTERN_INDICES.has(p) && extractedTitle.length > 0) {
+      const lastChar = extractedTitle.slice(-1);
+      if (punctuationMarks.includes(lastChar)) continue;
+    }
+    return { p, description, extractedTitle };
+  }
+  return null;
+}
+
+/** Build and report one heading-like error. */
+function reportHeadingLikeError(line, index, match, ctx) {
+  const { lines, headings, config, ruleConfig, convertToHeading, onError } = ctx;
+  const { description, extractedTitle } = match;
+  const lineNumber = index + 1;
+  const insertText = !convertToHeading
+    ? extractedTitle
+    : buildConvertToHeadingInsertText({
+      lines, index, lineNumber, headings, config, ruleConfig, extractedTitle,
+    });
+  onError({
+    lineNumber,
+    detail: `Line looks like ${description}; use an ATX heading (# Title) instead of heading-like formatting.`,
+    context: line,
+    fixInfo: { editColumn: 1, deleteCount: line.length, insertText },
+  });
+}
+
+/** Normalize rule config and build context for processing. */
+function getNoHeadingLikeContext(params, onError) {
   const lines = params.lines;
-  const filePath = params.name || "";
   const ruleConfig = params.config?.["no-heading-like-lines"] ?? params.config ?? {};
-  const excludePathPatterns = ruleConfig.excludePathPatterns;
-  if (Array.isArray(excludePathPatterns) && excludePathPatterns.length > 0 && pathMatchesAny(filePath, excludePathPatterns)) {
-    return;
-  }
   const convertToHeading = ruleConfig.convertToHeading === true;
   const defaultHeadingLevel = ruleConfig.defaultHeadingLevel;
   const fixedHeadingLevel = ruleConfig.fixedHeadingLevel;
   const punctuationMarks = typeof ruleConfig.punctuationMarks === "string"
     ? ruleConfig.punctuationMarks
     : ".,;!?";
   const config = { defaultHeadingLevel, fixedHeadingLevel };
-
   const headings = convertToHeading ? extractHeadings(lines) : [];
+  return {
+    lines,
+    ruleConfig,
+    excludePathPatterns: ruleConfig.excludePathPatterns,
+    punctuationMarks,
+    config,
+    headings,
+    convertToHeading,
+    onError,
+    ctx: { lines, headings, config, ruleConfig, convertToHeading, onError },
+  };
+}
 
-  lines.forEach((line, index) => {
-    const lineNumber = index + 1;
+/**
+ * markdownlint rule: flag lines that look like headings but use bold/italic
+ * (e.g. **Section:** or 1. **Item**, or MD036-style **Introduction** / *Note*)
+ * so they can be converted to proper ATX headings. Supports fixInfo for --fix.
+ *
+ * @param {object} params - markdownlint params (lines, name, config)
+ * @param {function(object): void} onError - Callback to report an error
+ */
+function ruleFunction(params, onError) {
+  const { lines, excludePathPatterns, punctuationMarks, ctx } = getNoHeadingLikeContext(params, onError);
+  const filePath = params.name || "";
+  if (Array.isArray(excludePathPatterns) && excludePathPatterns.length > 0 && pathMatchesAny(filePath, excludePathPatterns)) {
+    return;
+  }
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
     const trimmedLine = line.trim();
-
-    if (!trimmedLine) return;
-
-    for (let p = 0; p < PATTERNS.length; p++) {
-      const [pattern, description] = PATTERNS[p];
-      if (!pattern.test(trimmedLine)) continue;
-
-      const extractedTitle = extractTitleFromHeadingLike(trimmedLine, p);
-      if (MD036_STYLE_PATTERN_INDICES.has(p) && extractedTitle.length > 0) {
-        const lastChar = extractedTitle.slice(-1);
-        if (punctuationMarks.includes(lastChar)) continue;
-      }
-      let insertText;
-
-      if (!convertToHeading) {
-        insertText = extractedTitle;
-      } else {
-        insertText = buildConvertToHeadingInsertText({
-          lines, index, lineNumber, headings, config, ruleConfig, extractedTitle,
-        });
-      }
-
-      onError({
-        lineNumber,
-        detail: `Line looks like ${description}; use an ATX heading (# Title) instead of heading-like formatting.`,
-        context: line,
-        fixInfo: { editColumn: 1, deleteCount: line.length, insertText },
-      });
-      return;
-    }
-  });
+    if (!trimmedLine) continue;
+    const match = findHeadingLikeMatch(trimmedLine, punctuationMarks);
+    if (!match) continue;
+    reportHeadingLikeError(line, index, match, ctx);
+  }
 }
 
 module.exports = {

markdownlint-rules/one-sentence-per-line.js

@@ -91,7 +91,11 @@ function getNextToken(scanned, startIndex) {
 }
 
 function isAbbreviation(scanned, i, j, abbreviations) {
-  if (scanned[i] === "." && i > 0 && /\d/.test(scanned[i - 1])) return true;
+  if (scanned[i] === "." && i > 0 && /\d/.test(scanned[i - 1])) {
+    const nextToken = getNextToken(scanned, j);
+    if (/^\d/.test(nextToken)) return true;
+    return false;
+  }
   const word = getWordBefore(scanned, i);
   if (word.length === 0) return false;
   const nextToken = getNextToken(scanned, j);
@@ -102,29 +106,40 @@ function isAbbreviation(scanned, i, j, abbreviations) {
     || abbreviations.has(wordWithNext) || abbreviations.has(wordWithNextLower);
 }
 
-/**
- * Find index of the first sentence boundary (space before second sentence) in content.
- * Uses stripInlineCode; skips link/paren context; avoids decimals and abbreviations.
- * @param {string} content - Prose content (no list marker)
- * @param {{ abbreviations?: Set<string> }} opts - Optional abbreviations set
- * @returns {number|null} Index of space before second sentence, or null if at most one sentence
- */
-function trySentenceBoundary(scanned, i, abbreviations) {
+/** Skip optional quotes after position i; return next position or null if no space follows. */
+function skipQuotesThenSpace(scanned, i) {
   let pos = i + 1;
   while (pos < scanned.length && (scanned[pos] === "'" || scanned[pos] === '"')) {
     pos++;
   }
-  if (pos >= scanned.length || scanned[pos] === "\n") return null;
-  if (scanned[pos] !== " ") return null;
-  const spaceStart = pos;
+  if (pos >= scanned.length || scanned[pos] === "\n" || scanned[pos] !== " ") return null;
+  return pos;
+}
+
+/** From start of spaces, skip spaces and return { spaceStart, j } or null if no word char follows. */
+function spaceStartAndNextWordPos(scanned, spaceStart) {
+  let pos = spaceStart;
   while (pos < scanned.length && scanned[pos] === " ") {
     pos++;
   }
   const j = pos;
-  if (j >= scanned.length || scanned[j] === "\n") return null;
-  if (!/[a-zA-Z0-9]/.test(scanned[j])) return null;
-  if (isAbbreviation(scanned, i, j, abbreviations)) return null;
-  return i > 0 ? spaceStart : null;
+  if (j >= scanned.length || scanned[j] === "\n" || !/[a-zA-Z0-9]/.test(scanned[j])) return null;
+  return { spaceStart, j };
+}
+
+/**
+ * Find index of the first sentence boundary (space before second sentence) in content.
+ * Uses stripInlineCode; skips link/paren context; avoids decimals and abbreviations.
+ * @param {string} content - Prose content (no list marker)
+ * @param {{ abbreviations?: Set<string> }} opts - Optional abbreviations set
+ * @returns {number|null} Index of space before second sentence, or null if at most one sentence
+ */
+function trySentenceBoundary(scanned, i, abbreviations) {
+  const spaceStart = skipQuotesThenSpace(scanned, i);
+  if (spaceStart === null) return null;
+  const after = spaceStartAndNextWordPos(scanned, spaceStart);
+  if (!after || isAbbreviation(scanned, i, after.j, abbreviations)) return null;
+  return i > 0 ? after.spaceStart : null;
 }
 
 function getFirstSentenceBoundary(content, opts) {