Plan: Add MDS034 markdown-flavor validation rule by jeduden · Pull Request #127 · jeduden/mdsmith

jeduden · 2026-04-06T22:09:07Z

Summary

This PR adds a comprehensive design plan for MDS034, a new opt-in rule that validates Markdown files against a declared flavor (CommonMark, GFM, or Goldmark) and reports unsupported syntax with auto-fix capabilities where applicable.

Key Changes

New planning document (plan/86_markdown-flavor-validation.md): Detailed specification for MDS034 including:
- Background on common Markdown flavors and their syntax differences
- Evaluation of three detection approaches, selecting a dual-parser strategy to avoid impacting existing rules
- Justification for five custom goldmark extensions (~1250 LOC total) to detect features without built-in support (superscript, subscript, math inline/block, abbreviations)
- Feature registry mapping each flavor to supported syntax
- AST-based detection for all 12 features (tables, task lists, strikethrough, autolinks, footnotes, definition lists, heading IDs, superscript, subscript, math block, math inline, abbreviations)
- Auto-fix strategy for fixable features (autolinks, strikethrough, heading IDs, task lists, superscript, subscript)
- Clear error messages and integration notes with existing rules
Updated PLAN.md: Added entry for plan Add research and implementation plans for directive unification #86 in the roadmap

Notable Implementation Details

Dual parser approach: MDS034 creates a second goldmark parser with all extensions enabled, leaving the main parser untouched to avoid breaking existing rules (MDS001-MDS033)
Custom extensions: Five detection-only extensions follow the pattern of the existing PI block parser, producing AST nodes with precise source positions for diagnostics
Abbreviation complexity: The abbreviation extension includes both block-level definition parsing and paragraph-level occurrence detection to report every use of abbreviated terms
Math inline disambiguation: Uses Pandoc-style flanking rules to distinguish $x+y$ (math) from costs $5 (currency) and $PATH (environment variables)
Opt-in by default: Rule is disabled by default, so most users pay zero performance cost
Comprehensive test coverage: Includes 16 detailed acceptance criteria and test fixture requirements

https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

codecov · 2026-04-06T22:10:23Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.16%. Comparing base (357cc49) to head (0c470f3).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #127   +/-   ##
=======================================
  Coverage   86.16%   86.16%           
=======================================
  Files          92       92           
  Lines        9868     9868           
=======================================
  Hits         8503     8503           
  Misses        891      891           
  Partials      474      474

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

Adds plan #86 describing the design for a new opt-in rule (MDS034) to validate Markdown files against a declared Markdown flavor, and updates the plans index to include the new plan.

Changes:

Added plan/86_markdown-flavor-validation.md with a detailed design/spec for MDS034 (flavor registry, dual-parser approach, detectors, auto-fix strategy, tasks, acceptance criteria).
Updated PLAN.md generated catalog output to include plan 86.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
plan/86_markdown-flavor-validation.md	New design plan/spec for MDS034 markdown flavor validation rule.
PLAN.md	Adds plan 86 to the generated plans catalog table.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

New rule MDS034 that validates Markdown files against a declared flavor (CommonMark, GFM, Goldmark) and reports unsupported syntax with auto-fix where possible. https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

Evaluated three detection approaches (enable extensions in main parser, regex-only, dual parser). Chose dual parser: MDS034 creates a second goldmark parser with all built-in extensions enabled, giving precise AST detection for 7 of 11 features without affecting existing rules. Regex fallback only for math, abbreviations, superscript, subscript. https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

subscript, math-block Evaluated custom extensions vs regex vs third-party deps for the 4 features without built-in goldmark support. Third-party extensions are abandoned or unsuitable. Custom inline/block parsers cost ~200 LOC each and give precise AST detection. Regex kept only for math-inline ($ too ambiguous) and abbreviations (too rare to justify ~400 LOC extension). https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

Regex cannot reliably distinguish $x+y$ (math) from costs $5 (currency) or $PATH (env var) without delimiter-state tracking. Added MathInlineExt with Pandoc-style flanking rules. Now 4 custom extensions (superscript, subscript, math-block, math-inline) + 1 regex (abbreviation definitions only). https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

Diagnostics must flag every inline occurrence of an abbreviated term, not just the definition line. Regex can't reliably find term occurrences inside code spans or link URLs. All 12 features now detected via AST with 5 custom goldmark extensions (~1250 LOC total with tests), zero regex fallback. https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

Replaced verbose tables with prose, trimmed redundant sections. 170 lines (under 300 max), no lines over 80 chars, no tables needing pad formatting. Fixes mdsmith CI check failure. https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

- Convert inline code paths to Markdown links per plan template - Note sync.Once caching for dual parser (rule cloning concern) - Fix task 11: implement rule.Configurable, not add interface https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

internal/rules/markdownflavor/ext/ does not exist yet, so the Markdown link breaks the strict cross-file-reference check. Use backticked path (allowed for placeholders per CLAUDE.md). https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

Break 59-word single sentence into shorter sentences (max 40 words per sentence). Update PI parser reference to include both pi_parser.go and pi.go. Clarify parser caching must be package-level, not per-clone. https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

Split paragraphs to reduce readability index below 14.0 and sentence count below 6. Verified clean with mdsmith check. https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

The rebase silently reverted config changes from main: lost directory-structure rule, docs/security and docs/research overrides, cross-file-reference exclude path fix, and AGENTS-PR-FIXUP.md path fix. Restore by checking out from origin/main. https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

Use mdsmith fix to regenerate PLAN.md instead of hand-editing. Rename "autolinks" to "bare-URL autolinks" throughout plan 86 to distinguish from CommonMark's <...> autolinks. https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

…interaction - Constrain bare-URL autolink fix to scheme-bearing URLs; www.-only URLs use explicit Markdown link syntax instead - List exact features accepted/flagged by flavor: goldmark - Replace vague "no conflict with MDS012" criterion with specific per-flavor behavior for bare-URL diagnostics https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

Explicitly list every accepted and flagged feature for commonmark, gfm, and goldmark flavors so the planned registry and test fixtures are unambiguous. https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

Replace vague "and five others" with explicit list of all 12 features that vary across flavors, matching the acceptance criteria. https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

- Replace vague Pandoc flanking description with explicit rules, allow/deny examples, and spec link - Expand task-list auto-fix to cover all bullet markers and checked/unchecked states https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

…tensions Align narrative with acceptance criteria: goldmark for MDS034 means the default config (GFM-like features + heading IDs), not all optional extensions. https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

…task - Rephrase goldmark flavor as an mdsmith-defined profile, not upstream Goldmark defaults - Add explicit task to implement rule.Defaultable for opt-in behavior https://claude.ai/code/session_01NXoimZjyg4zz55zx1YXi7W

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Copilot