Merge PR #228: Implement MDS052: no-undefined-reference-labels rule

merge-queue-bot · merge-queue-bot · commit a024cae0dd26 · 2026-05-04T07:35:18.000Z
diff --git a/PLAN.md b/PLAN.md
@@ -39,7 +39,7 @@ footer: |
 | 125 | ✅     | sonnet | [No space inside link text rule](plan/125_no-space-in-link-text.md)                                  |
 | 126 | ✅     | sonnet | [Proper-name capitalization rule](plan/126_proper-names.md)                                          |
 | 127 | ✅     | sonnet | [Single H1 per file rule](plan/127_single-h1.md)                                                     |
-| 128 | 🔲     | sonnet | [Reject undefined reference-link labels](plan/128_no-undefined-reference-labels.md)                  |
+| 128 | ✅     | sonnet | [Reject undefined reference-link labels](plan/128_no-undefined-reference-labels.md)                  |
 | 129 | ✅     | sonnet | [Flag unused or duplicate link reference definitions](plan/129_no-unused-link-definitions.md)        |
 | 52  | ✅     |        | [Archetype / Template Library for Agentic Patterns](plan/52_archetype-template-library.md)           |
 | 61  | ✅     |        | [Required Structure Rule Hardening](plan/61_required-structure-hardening.md)                         |
diff --git a/cmd/mdsmith/main.go b/cmd/mdsmith/main.go
@@ -62,6 +62,7 @@ import (
 	_ "github.com/jeduden/mdsmith/internal/rules/nospaceinlinktext"
 	_ "github.com/jeduden/mdsmith/internal/rules/notrailingpunctuation"
 	_ "github.com/jeduden/mdsmith/internal/rules/notrailingspaces"
+	_ "github.com/jeduden/mdsmith/internal/rules/noundefinedreferencelabels"
 	_ "github.com/jeduden/mdsmith/internal/rules/nounusedlinkdefinitions"
 	_ "github.com/jeduden/mdsmith/internal/rules/orderedlistnumbering"
 	_ "github.com/jeduden/mdsmith/internal/rules/paragraphreadability"
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
@@ -49,6 +49,7 @@ import (
 	_ "github.com/jeduden/mdsmith/internal/rules/nospaceinlinktext"
 	_ "github.com/jeduden/mdsmith/internal/rules/notrailingpunctuation"
 	_ "github.com/jeduden/mdsmith/internal/rules/notrailingspaces"
+	_ "github.com/jeduden/mdsmith/internal/rules/noundefinedreferencelabels"
 	_ "github.com/jeduden/mdsmith/internal/rules/nounusedlinkdefinitions"
 	_ "github.com/jeduden/mdsmith/internal/rules/orderedlistnumbering"
 	_ "github.com/jeduden/mdsmith/internal/rules/paragraphreadability"
diff --git a/internal/engine/categories_test.go b/internal/engine/categories_test.go
@@ -49,6 +49,7 @@ import (
 	_ "github.com/jeduden/mdsmith/internal/rules/nospaceinlinktext"
 	_ "github.com/jeduden/mdsmith/internal/rules/notrailingpunctuation"
 	_ "github.com/jeduden/mdsmith/internal/rules/notrailingspaces"
+	_ "github.com/jeduden/mdsmith/internal/rules/noundefinedreferencelabels"
 	_ "github.com/jeduden/mdsmith/internal/rules/nounusedlinkdefinitions"
 	_ "github.com/jeduden/mdsmith/internal/rules/orderedlistnumbering"
 	_ "github.com/jeduden/mdsmith/internal/rules/paragraphreadability"
diff --git a/internal/integration/rules_test.go b/internal/integration/rules_test.go
@@ -54,6 +54,7 @@ import (
 	_ "github.com/jeduden/mdsmith/internal/rules/nospaceinlinktext"
 	_ "github.com/jeduden/mdsmith/internal/rules/notrailingpunctuation"
 	_ "github.com/jeduden/mdsmith/internal/rules/notrailingspaces"
+	_ "github.com/jeduden/mdsmith/internal/rules/noundefinedreferencelabels"
 	_ "github.com/jeduden/mdsmith/internal/rules/nounusedlinkdefinitions"
 	_ "github.com/jeduden/mdsmith/internal/rules/orderedlistnumbering"
 	_ "github.com/jeduden/mdsmith/internal/rules/paragraphreadability"
diff --git a/internal/rules/MDS054-no-undefined-reference-labels/README.md b/internal/rules/MDS054-no-undefined-reference-labels/README.md
@@ -0,0 +1,174 @@
+---
+id: MDS054
+name: no-undefined-reference-labels
+status: ready
+description: Reference-style links and images must have a matching link reference definition in the same file.
+---
+# MDS054: no-undefined-reference-labels
+
+Reference-style links and images must have a matching link reference
+definition in the same file.
+
+## Settings
+
+| Setting        | Type   | Default     | Description                                                                                                                |
+|----------------|--------|-------------|----------------------------------------------------------------------------------------------------------------------------|
+| `shortcut`     | string | `heuristic` | Controls when bare `[label]` shortcut references are checked: `heuristic`, `always`, or `collapsed-only`.                  |
+| `placeholders` | list   | `[]`        | Placeholder tokens to treat as opaque; see [placeholder grammar](../../../docs/background/concepts/placeholder-grammar.md) |
+
+### `shortcut` values
+
+| Value            | Behaviour                                                                                                                                                                      |
+|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `heuristic`      | Flag bare `[label]` only when the label has no spaces and contains a digit, hyphen, or underscore. Image shortcuts (`![label]`) are always checked regardless of this setting. |
+| `always`         | Flag every bare `[label]` whose definition is missing.                                                                                                                         |
+| `collapsed-only` | Only flag `[text][label]` (full) and `[label][]` (collapsed) forms; never bare `[label]`.                                                                                      |
+
+## Config
+
+```yaml
+rules:
+  no-undefined-reference-labels:
+    shortcut: heuristic
+    placeholders: []
+```
+
+Disable:
+
+```yaml
+rules:
+  no-undefined-reference-labels: false
+```
+
+## Examples
+
+### Good
+
+<?include
+file: good/full-reference.md
+wrap: markdown
+?>
+
+```markdown
+# Full Reference
+
+See [example][site] for more.
+
+[site]: https://example.com
+```
+
+<?/include?>
+
+### Good -- collapsed reference
+
+<?include
+file: good/collapsed-reference.md
+wrap: markdown
+?>
+
+```markdown
+# Collapsed Reference
+
+See [example][] for more.
+
+[example]: https://example.com
+```
+
+<?/include?>
+
+### Good -- prose brackets skipped by heuristic
+
+<?include
+file: good/prose-brackets.md
+wrap: markdown
+?>
+
+```markdown
+# Prose Brackets
+
+Use [just brackets] in prose without a definition; the heuristic
+skips it because the label has spaces.
+```
+
+<?/include?>
+
+### Bad -- undefined full reference
+
+<?include
+file: bad/undefined-full-reference.md
+wrap: markdown
+?>
+
+```markdown
+# Undefined Full Reference
+
+See [example][broken] for more.
+```
+
+<?/include?>
+
+### Bad -- undefined collapsed reference
+
+<?include
+file: bad/undefined-collapsed-reference.md
+wrap: markdown
+?>
+
+```markdown
+# Undefined Collapsed Reference
+
+See [broken][] for more.
+```
+
+<?/include?>
+
+### Bad -- undefined shortcut (heuristic)
+
+<?include
+file: bad/undefined-shortcut-heuristic.md
+wrap: markdown
+?>
+
+```markdown
+# Shortcut Heuristic
+
+See [plan128] for the plan.
+```
+
+<?/include?>
+
+## Diagnostics
+
+| Condition                     | Message                                                       |
+|-------------------------------|---------------------------------------------------------------|
+| undefined full reference      | reference label "X" has no matching link reference definition |
+| undefined collapsed reference | reference label "X" has no matching link reference definition |
+| undefined shortcut (flagged)  | reference label "X" has no matching link reference definition |
+
+## Background
+
+goldmark only constructs an `*ast.Link` for a reference-style usage
+when a matching link reference definition exists. When the definition
+is missing, goldmark leaves the bracketed text as plain text. A
+source-level scan is required to detect these dropped patterns.
+
+Reference labels are CommonMark-normalized before lookup: case-folded,
+inner whitespace collapsed, and ends trimmed. `[Foo Bar][BAR]` resolves
+against `[bar]: url`.
+
+## Meta-Information
+
+- **ID**: MDS054
+- **Name**: `no-undefined-reference-labels`
+- **Status**: ready
+- **Default**: enabled, shortcut: heuristic, placeholders: []
+- **Fixable**: no
+- **Implementation**: [source](./)
+- **Category**: link
+
+## See also
+
+- [MDS027 cross-file-reference-integrity](../MDS027-cross-file-reference-integrity/README.md)
+- [Plan 107: no-reference-style](../../../plan/107_no-reference-style.md)
+- [Plan 129: no-unused-link-definitions](../../../plan/129_no-unused-link-definitions.md)
+- [Placeholder grammar](../../../docs/background/concepts/placeholder-grammar.md)
diff --git a/internal/rules/MDS054-no-undefined-reference-labels/bad/undefined-collapsed-reference.md b/internal/rules/MDS054-no-undefined-reference-labels/bad/undefined-collapsed-reference.md
@@ -0,0 +1,9 @@
+---
+diagnostics:
+  - line: 3
+    column: 5
+    message: 'reference label "broken" has no matching link reference definition'
+---
+# Undefined Collapsed Reference
+
+See [broken][] for more.
diff --git a/internal/rules/MDS054-no-undefined-reference-labels/bad/undefined-full-reference.md b/internal/rules/MDS054-no-undefined-reference-labels/bad/undefined-full-reference.md
@@ -0,0 +1,9 @@
+---
+diagnostics:
+  - line: 3
+    column: 5
+    message: 'reference label "broken" has no matching link reference definition'
+---
+# Undefined Full Reference
+
+See [example][broken] for more.
diff --git a/internal/rules/MDS054-no-undefined-reference-labels/bad/undefined-shortcut-heuristic.md b/internal/rules/MDS054-no-undefined-reference-labels/bad/undefined-shortcut-heuristic.md
@@ -0,0 +1,9 @@
+---
+diagnostics:
+  - line: 3
+    column: 5
+    message: 'reference label "plan128" has no matching link reference definition'
+---
+# Shortcut Heuristic
+
+See [plan128] for the plan.
diff --git a/internal/rules/MDS054-no-undefined-reference-labels/good/case-normalized.md b/internal/rules/MDS054-no-undefined-reference-labels/good/case-normalized.md
@@ -0,0 +1,6 @@
+# Case Normalized
+
+CommonMark normalizes reference labels: [Foo Bar][BAR] resolves to the
+definition below.
+
+[bar]: https://example.com
diff --git a/internal/rules/MDS054-no-undefined-reference-labels/good/code-exclusions.md b/internal/rules/MDS054-no-undefined-reference-labels/good/code-exclusions.md
@@ -0,0 +1,11 @@
+# Code Exclusions
+
+Inline: `` [broken][ref] `` is inside a code span.
+
+Fenced block:
+
+```markdown
+[broken][ref]
+[broken][]
+[broken]
+```
diff --git a/internal/rules/MDS054-no-undefined-reference-labels/good/collapsed-reference.md b/internal/rules/MDS054-no-undefined-reference-labels/good/collapsed-reference.md
@@ -0,0 +1,5 @@
+# Collapsed Reference
+
+See [example][] for more.
+
+[example]: https://example.com
diff --git a/internal/rules/MDS054-no-undefined-reference-labels/good/full-reference.md b/internal/rules/MDS054-no-undefined-reference-labels/good/full-reference.md
@@ -0,0 +1,5 @@
+# Full Reference
+
+See [example][site] for more.
+
+[site]: https://example.com
diff --git a/internal/rules/MDS054-no-undefined-reference-labels/good/pi-block.md b/internal/rules/MDS054-no-undefined-reference-labels/good/pi-block.md
@@ -0,0 +1,10 @@
+# PI Block
+
+Reference-style patterns inside a PI block are not flagged.
+
+<?note
+[broken][ref]
+[broken][]
+?>
+
+Text after the PI block with inline [link](https://example.com).
diff --git a/internal/rules/MDS054-no-undefined-reference-labels/good/placeholder.md b/internal/rules/MDS054-no-undefined-reference-labels/good/placeholder.md
@@ -0,0 +1,8 @@
+---
+settings:
+  placeholders:
+    - var-token
+---
+# Placeholder Label
+
+See [text][{title}] for more.
diff --git a/internal/rules/MDS054-no-undefined-reference-labels/good/prose-brackets.md b/internal/rules/MDS054-no-undefined-reference-labels/good/prose-brackets.md
@@ -0,0 +1,4 @@
+# Prose Brackets
+
+Use [just brackets] in prose without a definition; the heuristic
+skips it because the label has spaces.
diff --git a/internal/rules/MDS054-no-undefined-reference-labels/good/shortcut-reference.md b/internal/rules/MDS054-no-undefined-reference-labels/good/shortcut-reference.md
@@ -0,0 +1,5 @@
+# Shortcut Reference
+
+See [example].
+
+[example]: https://example.com
diff --git a/internal/rules/index.md b/internal/rules/index.md
@@ -72,4 +72,5 @@ row: "| [{id}]({filename}) | `{name}` | {status} | {description} |"
 | [MDS051](MDS051-single-h1/README.md)                          | `single-h1`                          | ready     | At most one H1 heading is allowed per file.                                                                                   |
 | [MDS052](MDS052-no-space-in-code-spans/README.md)             | `no-space-in-code-spans`             | ready     | Inline code spans with leading or trailing whitespace inside the backticks are almost always typos; flag them.                |
 | [MDS053](MDS053-no-unused-link-definitions/README.md)         | `no-unused-link-definitions`         | ready     | Every `[label]: url` definition must be consumed by at least one reference-style link or image; duplicate labels are flagged. |
+| [MDS054](MDS054-no-undefined-reference-labels/README.md)      | `no-undefined-reference-labels`      | ready     | Reference-style links and images must have a matching link reference definition in the same file.                             |
 <?/catalog?>
diff --git a/internal/rules/noundefinedreferencelabels/rule.go b/internal/rules/noundefinedreferencelabels/rule.go
diff --git a/internal/rules/noundefinedreferencelabels/rule_test.go b/internal/rules/noundefinedreferencelabels/rule_test.go
diff --git a/plan/124_no-space-in-code-spans.md b/plan/124_no-space-in-code-spans.md
diff --git a/plan/125_no-space-in-link-text.md b/plan/125_no-space-in-link-text.md
diff --git a/plan/126_proper-names.md b/plan/126_proper-names.md
diff --git a/plan/127_single-h1.md b/plan/127_single-h1.md
diff --git a/plan/128_no-undefined-reference-labels.md b/plan/128_no-undefined-reference-labels.md
