Add plans 87 and 88: GitHub Alerts and TOC directive rules by jeduden · Pull Request #139 · jeduden/mdsmith

jeduden · 2026-04-18T00:15:13Z

Summary

This PR adds two new planning documents that outline upcoming linting rules for mdsmith, and bumps the merge-queue-action to v0.5.0:

Plan 87: Flavor validation for GitHub Alerts (MDS034 extension)
Plan 88: TOC directive migration aid (new rule MDS035)
CI: bump jeduden/merge-queue-action from v0.4.1 → v0.5.0

Changes

plan/87_markdown-flavor-github-alerts.md (new)
- Extends MDS034 to detect GitHub Alerts syntax (> [!NOTE] blockquote prefix)
- Flags alerts as GFM-only features when target flavor is CommonMark or goldmark
- Includes auto-fix to demote alerts to plain blockquotes for compatibility
- Defines detection via AST walk over blockquote nodes matching five standard tokens
- Specifies error message, configuration, and comprehensive acceptance criteria
plan/88_toc-directive-migration.md (new)
- New rule MDS035 to detect renderer-specific TOC directives
- Targets four variants: [TOC], [[_TOC_]], [[toc]], ${toc}
- Suggests mdsmith's <?catalog?> directive for the file-index use case; calls out that heading-TOCs have no mdsmith equivalent
- Detection via line-level regex scoped to paragraph nodes, with link-reference-definition suppression for [TOC]
- Disabled by default (opt-in), detection-only with no auto-fix
- Includes rationale for separate rule vs. MDS034 integration
PLAN.md (regenerated)
- mdsmith fix PLAN.md expanded the catalog directive to include plans 87 and 88
.github/workflows/merge-queue.yml (workflow bump)
- Bump jeduden/merge-queue-action from v0.4.1 (10aad589) to v0.5.0 (fd94568d)
- Rationale: keep the workflow on the latest released version of the merge-queue-action. Follows the same pattern as PR Update merge-queue-action to v0.4.1 #138 (v0.4.0 → v0.4.1), just consolidated onto this branch rather than split into a dedicated PR

Implementation Notes

Both plans follow the established pattern from plan 86 (flavor validation framework):

Plan 87 builds on the dual parser and feature enum infrastructure
Plan 88 is independent but complements the flavor validation work
Both include detailed task breakdowns and acceptance criteria for implementation

https://claude.ai/code/session_018Y66EF7D9E8kC3mwTh9E2m

codecov · 2026-04-18T00:16:06Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.25%. Comparing base (a1226fa) to head (417a0cb).
⚠️ Report is 12 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #139   +/-   ##
=======================================
  Coverage   86.25%   86.25%           
=======================================
  Files          92       92           
  Lines        9880     9880           
=======================================
  Hits         8522     8522           
  Misses        886      886           
  Partials      472      472

☔ 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 two new roadmap plan documents for upcoming mdsmith lint rules (GitHub Alerts flavor validation and TOC-directive detection), and updates the plans index in PLAN.md so they appear in the generated plans table.

Changes:

Added plan 87 describing an MDS034 extension to detect/fix GitHub Alerts markers in non-GFM target flavors.
Added plan 88 describing a new opt-in MDS035 rule to detect renderer-specific TOC directives.
Updated PLAN.md catalog output to include plans 87 and 88.

Reviewed changes

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

File	Description
plan/87_markdown-flavor-github-alerts.md	New plan documenting detection/fix behavior to extend flavor validation for GitHub Alerts syntax.
plan/88_toc-directive-migration.md	New plan for an opt-in rule to flag renderer-specific TOC directives and guide migration.
PLAN.md	Updates the generated plans catalog table to include the two new plans.

Plan 87 extends MDS034 (flavor validation, plan 86) with a 13th feature: GitHub Alerts `> [!NOTE]` blockquotes. Detected via AST walk on the dual parser, no new goldmark extension needed. Fix strips the marker line while preserving the blockquote body. Plan 88 adds a new rule MDS035 that flags four renderer-specific TOC directives (`[TOC]`, `[[_TOC_]]`, `[[toc]]`, `${toc}`) which silently disappear on CommonMark / goldmark, and suggests the existing `<?catalog?>` directive as a portable replacement. These address the high-value items from the markdown-extension survey comment. Items evaluated and deliberately skipped: - Spoilers `||text||`: only Discord/Mattermost, severe ambiguity with table pipes, no linter in the ecosystem covers it. - Generic attribute syntax beyond heading IDs: plan 86 already enables `parser.WithAttribute()`; heading IDs are feature 8. - Pandoc `:::` fenced divs / MyST / MkDocs admonitions: five mutually incompatible variants, no standardization, goldmark renders them as plain paragraphs (not a lint-visible failure).

Address Copilot review: - catalog replacement mismatch: <?catalog?> is a file-index generator (needs glob + frontmatter), not an in-document heading TOC generator. Add a comparison table, explain that <?catalog?> is the right replacement only for index-page uses of [[_TOC_]]/[TOC], and note mdsmith has no built-in heading TOC generator for the more common in-document case. - Error message: combine into a single fenced code block (no longer split across two inline spans) and name both CommonMark and goldmark as failure renderers.

Copilot

Pull request overview

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

Address Copilot review: - Error message: drop trailing period and capital leading 'For', matching the mdsmith CLAUDE.md convention (lowercase, no trailing punctuation). New message keeps both pointers — the missing heading-TOC generator and MDS019 for file indexes. - Detection: `[TOC]` is a valid CommonMark shortcut reference link. The earlier design would false-positive when a matching `[TOC]: <url>` definition is present. Add an explicit link-reference map lookup (case-insensitive label) before emitting the diagnostic for this pattern; the other three patterns keep their simple regex match. - Tasks: add a step for the link-reference suppression and a good fixture exercising it.

Copilot

Pull request overview

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

Address Copilot review: - Failure description: earlier text said the directives "simply disappear from the rendered output" / render as "empty text". That was wrong — goldmark and CommonMark render the literal directive token (`[TOC]`, `[[_TOC_]]`, etc.) as paragraph text. Rewrite the Context section to describe the actual behavior: a visible failure where the author's intent is lost but the token itself is shown. Update the front-matter summary and Goal paragraph to match. - Error message: the previous version started with `[TOC]`, which read as a capitalized leading token and conflicted with the note claiming a "Lowercase start". Reword to start with the lowercase word "unsupported": `unsupported TOC directive \`[TOC]\`; mdsmith has no heading TOC equivalent; use <?catalog?> for file indexes (MDS019)`. The backticked directive token is quotation, not prose capitalization. Also addresses a Copilot comment on PLAN.md: the catalog table rows for plans 87 and 88 were added by running `mdsmith fix PLAN.md`, not edited by hand. Re-running `mdsmith fix PLAN.md` after this change produces no diff, confirming the table is in sync with the plan files.

Copilot

Pull request overview

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

Copilot review noted the error message backticked `[TOC]` but left `<?catalog?>` as bare text, inconsistent with the following explanation that says directive tokens are backticked. Add backticks around `<?catalog?>` and update the explanation to cover both tokens. Two other comments in the same review batch — claiming the comparison tables in plans 87 and 88 start each row with `||` and have an empty leading column — are factually incorrect. Both tables use a single leading `|`; replies posted on the threads with the verbatim current content.

Copilot

Pull request overview

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

Copilot review: the example error message hardcoded [TOC], which would misrepresent the diagnostic for the other three patterns ([[_TOC_]], [[toc]], ${toc}). Change: describe the message as templated on `{directive}` and show the concrete message each of the four patterns would emit. The template itself is unchanged; only the documentation makes clear that the matched token is substituted per call site. Also explicitly document the mdsmith error-message convention (lowercase start, no trailing punctuation) inline so that implementation follows it for every pattern.

Copilot

Pull request overview

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

Address two Copilot review points: - plan 87: described the non-GFM render of `> [!NOTE]` as a "silent failure", but the literal marker text is visibly rendered — that is a visible failure. Reword to match. - plan 88: the phrase "None are part of CommonMark, GFM, or goldmark" was ambiguous — `[TOC]` IS valid CommonMark syntax as a shortcut reference link. Reword to make clear that none of the four tokens are standardized as TOC directives, while `[TOC]` remains a valid (but differently-resolved) link shorthand.

Copilot

Pull request overview

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

jeduden · 2026-04-19T13:59:37Z

🟢 Merge Queue — picked up

This PR is in the queue and will be batched with other queue-labelled PRs.

Next: No action needed — you'll get another comment when CI starts on the batch. View merge queue run.

jeduden · 2026-04-19T13:59:52Z

🔵 Merge Queue — CI running

Merged into batch branch merge-queue/batch-139-1776607178 alongside #141. View CI run.

Next: No action needed — you'll be notified when CI completes.

jeduden · 2026-04-19T14:02:07Z

✅ Merge Queue — merged

This PR landed on main via commit 24d674d. CI run that validated the merge.

Next: Done — nothing more to do here.

Copilot AI review requested due to automatic review settings April 18, 2026 00:15

Copilot started reviewing on behalf of jeduden April 18, 2026 00:15 View session