fix(heading-title-case): treat single letter after 'Phase' as phase label

A single letter immediately after the word 'Phase' (e.g. Phase A:, Phase B) is now treated as a phase label and kept capitalized. Previously the article 'a' in the default minor-words list caused 'Phase A' to be flagged or fixed to 'Phase a'.

Author: cypher0n3

markdownlint-rules/README.md

@@ -94,8 +94,8 @@ Example for a repo that has copied rules into `.markdownlint-rules/`:
     "./.markdownlint-rules/heading-title-case.js",
     "./.markdownlint-rules/no-duplicate-headings-normalized.js",
     "./.markdownlint-rules/no-empty-heading.js",
-    "./.markdownlint-rules/no-heading-like-lines.js",
     "./.markdownlint-rules/no-h1-content.js",
+    "./.markdownlint-rules/no-heading-like-lines.js",
     "./.markdownlint-rules/one-sentence-per-line.js"
   ]
 }
@@ -540,6 +540,7 @@ Content inside inline code (backticks) is ignored.
 
 - **First and last words** of the heading must be capitalized (including the first and last segment of hyphenated compounds).
 - **First word after a colon** (e.g. `Summary: The Results`) and the **first word inside parentheses or brackets** (e.g. `(in Practice)`, `[optional]`) are treated as phrase starts and must be capitalized even if they are in the lowercase list.
+- **Phase labels:** A single letter immediately after the word "Phase" (e.g. `Phase A:`, `Phase B`) is treated as a label and kept capitalized, so the article "a" in the default list does not force lowercase in that context.
 - **Hyphenated compounds** (e.g. `One-Stop`, `Follow-Up`) are split on hyphens; each segment is checked as above (first/last of title or minor word in the middle).
 - **Minor words** (in the default or configured list) must be lowercase when in the middle of the heading; all other words must be capitalized.
 - Leading and trailing punctuation is ignored when evaluating a word (e.g. `(Word)` is evaluated as `Word`).

markdownlint-rules/heading-title-case.js

@@ -70,13 +70,13 @@ function isAllLower(w) {
 }
 
 /**
- * True if this position is exempt from lowercase (first/last/subphrase start/hyphen compound start).
- * @param {{ isFirst: boolean, isLast: boolean, isSubphraseStart?: boolean, isHyphenCompoundStart?: boolean }} opts
+ * True if this position is exempt from lowercase (first/last/subphrase start/hyphen compound start/phase label).
+ * @param {{ isFirst: boolean, isLast: boolean, isSubphraseStart?: boolean, isHyphenCompoundStart?: boolean, isPhaseLabel?: boolean }} opts
  * @returns {boolean}
  */
 function isExemptFromLowercase(opts) {
-  const { isFirst, isLast, isSubphraseStart, isHyphenCompoundStart } = opts;
-  return Boolean(isFirst || isLast || isSubphraseStart || isHyphenCompoundStart);
+  const { isFirst, isLast, isSubphraseStart, isHyphenCompoundStart, isPhaseLabel } = opts;
+  return Boolean(isFirst || isLast || isSubphraseStart || isHyphenCompoundStart || isPhaseLabel);
 }
 
 /**
@@ -93,7 +93,7 @@ function getCapitalizationKind(opts) {
 
 /**
  * Validate one word for title case; returns error detail string or null if valid.
- * @param {{ raw: string, core: string, isFirst: boolean, isLast: boolean, lowercaseWords: Set<string>, isSubphraseStart?: boolean, isHyphenCompoundStart?: boolean }} opts
+ * @param {{ raw: string, core: string, isFirst: boolean, isLast: boolean, lowercaseWords: Set<string>, isSubphraseStart?: boolean, isHyphenCompoundStart?: boolean, isPhaseLabel?: boolean }} opts
  * @returns {string|null}
  */
 function checkWord(opts) {
@@ -111,7 +111,7 @@ function checkWord(opts) {
  * Return the corrected segment text for fixInfo: lowercase or capitalize per AP rules, preserving punctuation.
  * @param {string} rawSeg - Segment as in source (e.g. "And", "(in", "practice)")
  * @param {string} core - stripWordPunctuation(rawSeg)
- * @param {{ isFirst: boolean, isLast: boolean, lowercaseWords: Set<string>, isSubphraseStart?: boolean, isHyphenCompoundStart?: boolean }} opts
+ * @param {{ isFirst: boolean, isLast: boolean, lowercaseWords: Set<string>, isSubphraseStart?: boolean, isHyphenCompoundStart?: boolean, isPhaseLabel?: boolean }} opts
  * @returns {string}
  */
 function getCorrectedSegment(rawSeg, core, opts) {
@@ -140,13 +140,24 @@ function getSegmentPosition(rawSegments, j) {
   return { segmentOffset, segmentLength: rawSegments[j].length };
 }
 
+/**
+ * True when the segment is a single letter immediately after the word "Phase" (phase label).
+ * @param {number} j - Segment index (must be 0 for first segment of word)
+ * @param {string} core - stripWordPunctuation(segment)
+ * @param {string} previousWordCore - Previous word core, lowercased
+ * @returns {boolean}
+ */
+function isPhaseLabelSegment(j, core, previousWordCore) {
+  return j === 0 && core.length === 1 && /^[A-Za-z]$/.test(core) && previousWordCore === "phase";
+}
+
 /**
  * Check one segment of a word for title-case; returns error result or null.
- * @param {{ words: string[], rawSegments: string[], i: number, j: number, wordIsSubphraseStart: boolean, lowercaseWords: Set<string> }} opts
+ * @param {{ words: string[], rawSegments: string[], i: number, j: number, wordIsSubphraseStart: boolean, lowercaseWords: Set<string>, previousWordCore?: string }} opts
  * @returns {{ valid: false, detail: string, wordIndex: number, segmentOffset?: number, segmentLength?: number }|null}
  */
 function checkOneSegment(opts) {
-  const { words, rawSegments, i, j, wordIsSubphraseStart, lowercaseWords } = opts;
+  const { words, rawSegments, i, j, wordIsSubphraseStart, lowercaseWords, previousWordCore } = opts;
   const rawSeg = rawSegments[j];
   const core = stripWordPunctuation(rawSeg);
   if (!core || !/[a-zA-Z]/.test(core)) return null;
@@ -155,6 +166,7 @@ function checkOneSegment(opts) {
   const isLast = i === words.length - 1 && j === rawSegments.length - 1;
   const isSubphraseStart = j === 0 && wordIsSubphraseStart;
   const isHyphenCompoundStart = rawSegments.length > 1 && j === 0;
+  const isPhaseLabel = isPhaseLabelSegment(j, core, previousWordCore);
 
   const detail = checkWord({
     raw: rawSeg,
@@ -164,6 +176,7 @@ function checkOneSegment(opts) {
     lowercaseWords,
     isSubphraseStart,
     isHyphenCompoundStart,
+    isPhaseLabel,
   });
   if (!detail) return null;
 
@@ -173,6 +186,7 @@ function checkOneSegment(opts) {
     lowercaseWords,
     isSubphraseStart,
     isHyphenCompoundStart,
+    isPhaseLabel,
   });
   const seg = getSegmentPosition(rawSegments, j);
   return {
@@ -206,6 +220,7 @@ function checkTitleCase(titleText, lowercaseWords) {
     const prefix = firstAlphaIdx > 0 ? raw.slice(0, firstAlphaIdx) : "";
     const afterColon = i > 0 && words[i - 1].replace(/\s+$/, "").endsWith(":");
     const wordIsSubphraseStart = prefix.includes("(") || prefix.includes("[") || afterColon;
+    const previousWordCore = i > 0 ? stripWordPunctuation(words[i - 1]).toLowerCase() : "";
 
     const rawSegments = raw.split(/-/);
     for (let j = 0; j < rawSegments.length; j++) {
@@ -216,6 +231,7 @@ function checkTitleCase(titleText, lowercaseWords) {
         j,
         wordIsSubphraseStart,
         lowercaseWords,
+        previousWordCore,
       });
       if (result) errors.push({ detail: result.detail, wordIndex: result.wordIndex, insertText: result.insertText, segmentOffset: result.segmentOffset, segmentLength: result.segmentLength });
     }
@@ -245,21 +261,23 @@ function getLowercaseWordsFromOptions(options) {
  * Correct one segment of a word for AP title case.
  * @param {string} rawSeg - Segment as in source
  * @param {string} core - stripWordPunctuation(rawSeg)
- * @param {{ i: number, j: number, words: string[], rawSegments: string[], wordIsSubphraseStart: boolean, lowercaseWords: Set<string> }} ctx
+ * @param {{ i: number, j: number, words: string[], rawSegments: string[], wordIsSubphraseStart: boolean, lowercaseWords: Set<string>, previousWordCore?: string }} ctx
  * @returns {string}
  */
 function correctSegmentForTitleCase(rawSeg, core, ctx) {
-  const { i, j, words, rawSegments, wordIsSubphraseStart, lowercaseWords } = ctx;
+  const { i, j, words, rawSegments, wordIsSubphraseStart, lowercaseWords, previousWordCore } = ctx;
   const isFirst = i === 0 && j === 0;
   const isLast = i === words.length - 1 && j === rawSegments.length - 1;
   const isSubphraseStart = j === 0 && wordIsSubphraseStart;
   const isHyphenCompoundStart = rawSegments.length > 1 && j === 0;
+  const isPhaseLabel = isPhaseLabelSegment(j, core, previousWordCore);
   return getCorrectedSegment(rawSeg, core, {
     isFirst,
     isLast,
     lowercaseWords,
     isSubphraseStart,
     isHyphenCompoundStart,
+    isPhaseLabel,
   });
 }
 
@@ -276,6 +294,7 @@ function processWordForTitleCase(raw, i, words, lowercaseWords) {
   const prefix = firstAlphaIdx > 0 ? raw.slice(0, firstAlphaIdx) : "";
   const afterColon = i > 0 && words[i - 1].replace(/\s+$/, "").endsWith(":");
   const wordIsSubphraseStart = prefix.includes("(") || prefix.includes("[") || afterColon;
+  const previousWordCore = i > 0 ? stripWordPunctuation(words[i - 1]).toLowerCase() : "";
   const rawSegments = raw.split(/-/);
   const segmentParts = [];
   for (let j = 0; j < rawSegments.length; j++) {
@@ -292,6 +311,7 @@ function processWordForTitleCase(raw, i, words, lowercaseWords) {
       rawSegments,
       wordIsSubphraseStart,
       lowercaseWords,
+      previousWordCore,
     }));
   }
   return segmentParts.join("-");

md_test_files/positive_general.md

@@ -18,6 +18,8 @@
   - [3. Using Tools (In Practice)](#3-using-tools-in-practice)
   - [4. How to Do a Follow-Up](#4-how-to-do-a-follow-up)
   - [5. Summary: The Results](#5-summary-the-results)
+  - [6. Phase A: Fixable Rules and Scripts (One-Time)](#6-phase-a-fixable-rules-and-scripts-one-time)
+  - [7. This Has a Lowercase a in the Title](#7-this-has-a-lowercase-a-in-the-title)
 - [Zero-Indexed Heading Numbering](#zero-indexed-heading-numbering)
   - [0. Introduction (Zero-Indexed)](#0-introduction-zero-indexed)
   - [1. First Topic](#1-first-topic)
@@ -135,6 +137,14 @@ AP style: hyphenated compounds (each segment capitalized); "to" and "a" lowercas
 
 AP style: first word after a colon is capitalized (subphrase start).
 
+### 6. Phase A: Fixable Rules and Scripts (One-Time)
+
+Single letter after "Phase" is treated as a phase label and stays capitalized (not the article "a").
+
+### 7. This Has a Lowercase a in the Title
+
+Should not catch.
+
 ## Zero-Indexed Heading Numbering
 
 When the first numbered heading in a section starts at 0, the rule treats that section as 0-based and does not report errors.

test-scripts/test_fix_heading_title_case.py

@@ -108,6 +108,28 @@ def test_fix_heading_with_backticks_and_parentheses(self) -> None:
             self.assertNotIn("(module ", actual, "(module should have been fixed")
             self.assertNotIn(" of file)", actual, "file should have been fixed to File")
 
+    def test_phase_a_label_unchanged_by_fix(self) -> None:
+        """Single letter after 'Phase' is a label; --fix must not lowercase it."""
+        content = """# Doc
+
+## Section
+
+Overview.
+
+### Phase A: Fixable Rules and Scripts (One-Time)
+
+Content.
+"""
+        with tempfile.TemporaryDirectory(prefix="fix_heading_title_case_") as tmp:
+            path = Path(tmp) / "test.md"
+            path.write_text(content, encoding="utf-8")
+            proc = _run_markdownlint(path, fix=False)
+            self.assertEqual(proc.returncode, 0, f"Phase A heading should pass lint: {proc.stderr}")
+            proc_fix = _run_markdownlint(path, fix=True)
+            self.assertEqual(proc_fix.returncode, 0, f"--fix should succeed: {proc_fix.stderr}")
+            actual = path.read_text(encoding="utf-8")
+            self.assertIn("Phase A:", actual, "Phase A must remain capitalized after --fix")
+
     def test_fix_filenames_in_parens_get_backticks_not_title_case(self) -> None:
         """Filenames like (utils.js, allow-custom-anchors.js) get backticks, not Title Case."""
         content_before = """# Suppressions

test/markdownlint-rules/heading-title-case.test.js

@@ -136,6 +136,12 @@ describe("heading-title-case", () => {
     assert.ok(errors[0].detail.includes("the") && errors[0].detail.includes("capitalized"));
   });
 
+  it("allows single letter after 'Phase' as phase label (e.g. Phase A, Phase B)", () => {
+    const lines = ["### Phase A: Fixable Rules and Scripts (One-Time)"];
+    const errors = runRule(rule, lines);
+    assert.strictEqual(errors.length, 0, "Phase A should not be flagged; single letter after 'Phase' is a label");
+  });
+
   it("reports no errors for heading that is only inline code (words.length === 0)", () => {
     const lines = ["## `code only`"];
     const errors = runRule(rule, lines);
@@ -290,6 +296,11 @@ describe("heading-title-case", () => {
       assert.strictEqual(result, "A and the B");
     });
 
+    it("preserves single letter after 'Phase' as phase label", () => {
+      const result = rule.applyTitleCase("Phase A: Fixable Rules and Scripts (One-Time)");
+      assert.strictEqual(result, "Phase A: Fixable Rules and Scripts (One-Time)", "Phase A label stays capitalized");
+    });
+
     it("returns empty or whitespace as-is (words.length === 0 branch)", () => {
       assert.strictEqual(rule.applyTitleCase(""), "");
       assert.strictEqual(rule.applyTitleCase("   "), "   ");