Merge PR #153: Plan 87: add GitHub Alerts detection and fix to MDS034

Author: jeduden

.gitignore

@@ -1,3 +1,4 @@
 /mdsmith
 eval/corpus/config.local.yml
 coverage.out
+cover.out

PLAN.md

@@ -44,7 +44,7 @@ footer: |
 | 84  | 🔲     | [Symlink default-deny for file discovery](plan/84_symlink-default-deny.md)                                      |
 | 85  | 🔳     | [Increase test coverage to 95% by extracting shared rule helpers](plan/85_coverage-to-95-percent.md)            |
 | 86  | 🔳     | [Markdown flavor validation](plan/86_markdown-flavor-validation.md)                                             |
-| 87  | 🔲     | [Flavor validation for GitHub Alerts](plan/87_markdown-flavor-github-alerts.md)                                 |
+| 87  | ✅     | [Flavor validation for GitHub Alerts](plan/87_markdown-flavor-github-alerts.md)                                 |
 | 88  | ✅     | [TOC directive migration aid](plan/88_toc-directive-migration.md)                                               |
 | 89  | 🔲     | [TOC generator directive and MDS035 auto-fix](plan/89_toc-generator-directive.md)                               |
 <?/catalog?>

internal/rules/MDS034-markdown-flavor/README.md

@@ -15,7 +15,7 @@ flavor does not render.
 - **Name**: `markdown-flavor`
 - **Status**: ready
 - **Default**: disabled
-- **Fixable**: no (fix pipeline lands in a follow-up)
+- **Fixable**: partially (GitHub Alerts only)
 - **Implementation**:
   [source](./)
 - **Category**: meta
@@ -73,7 +73,7 @@ rules:
 
 ## Detected features
 
-MDS034 tracks twelve syntax features whose
+MDS034 tracks thirteen syntax features whose
 support varies across Markdown flavors.
 
 Eleven features are detected from the goldmark AST
@@ -89,6 +89,13 @@ detector scans text nodes from the main parse for
 URL-shaped text. It skips links, autolinks, code
 spans, and code blocks.
 
+GitHub Alerts are detected from the CommonMark
+AST. The detector matches the five GFM tokens
+(`NOTE`, `TIP`, `IMPORTANT`, `WARNING`,
+`CAUTION`) on the first line of a blockquote
+paragraph. Matching is case-sensitive per the
+GFM spec.
+
 `flavor: any` accepts every feature and is omitted
 from the table below.
 
@@ -106,6 +113,7 @@ from the table below.
 | math blocks        | no         | no  | no       | yes    | no       | yes           | yes  |
 | inline math        | no         | no  | no       | yes    | no       | yes           | yes  |
 | abbreviations      | no         | no  | no       | no     | yes      | yes           | no   |
+| github alerts      | no         | yes | no       | no     | no       | no            | no   |
 
 ## Examples
 

internal/rules/MDS034-markdown-flavor/bad/commonmark-github-alerts.md

@@ -0,0 +1,12 @@
+---
+settings:
+  flavor: commonmark
+diagnostics:
+  - line: 3
+    column: 1
+    message: "github alerts are not supported by commonmark"
+---
+# Alerts
+
+> [!NOTE]
+> Something to remember.

internal/rules/MDS034-markdown-flavor/bad/goldmark-github-alerts.md

@@ -0,0 +1,12 @@
+---
+settings:
+  flavor: goldmark
+diagnostics:
+  - line: 3
+    column: 1
+    message: "github alerts are not supported by goldmark"
+---
+# Alerts
+
+> [!WARNING]
+> Something to remember.

internal/rules/MDS034-markdown-flavor/fixed/commonmark-github-alerts.md

@@ -0,0 +1,3 @@
+# Alerts
+
+> Something to remember.

internal/rules/MDS034-markdown-flavor/fixed/goldmark-github-alerts.md

@@ -0,0 +1,3 @@
+# Alerts
+
+> Something to remember.

internal/rules/markdownflavor/detect.go

@@ -1,6 +1,7 @@
 package markdownflavor
 
 import (
+	"bytes"
 	"regexp"
 	"sort"
 
@@ -45,6 +46,10 @@ type HeadingIDExtra struct {
 	AttrEnd   int // byte offset one past '}'
 }
 
+// alertTokenRe matches the exact content of a GitHub Alert marker line
+// inside a blockquote (case-sensitive per GFM spec).
+var alertTokenRe = regexp.MustCompile(`^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]\s*$`)
+
 // bareURLPattern mirrors goldmark's linkify http/https/ftp URL regex
 // closely enough to catch bare URLs in text. Anchors removed so it can
 // match anywhere inside a Text segment. The TLD class accepts both
@@ -92,6 +97,10 @@ func DetectFiltered(f *lint.File, accept func(Feature) bool) []Finding {
 		out = append(out, detectBareURLs(f)...)
 	}
 
+	if keep(FeatureGitHubAlerts) {
+		out = append(out, detectGitHubAlerts(f)...)
+	}
+
 	sort.SliceStable(out, func(i, j int) bool {
 		return out[i].Start < out[j].Start
 	})
@@ -488,3 +497,35 @@ func insideNonBareContext(n ast.Node) bool {
 	}
 	return false
 }
+
+// detectGitHubAlerts walks f.AST for Blockquote nodes whose first paragraph
+// child starts with a GFM alert token (e.g. [!NOTE]).
+func detectGitHubAlerts(f *lint.File) []Finding {
+	var findings []Finding
+	_ = ast.Walk(f.AST, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
+		if !entering {
+			return ast.WalkContinue, nil
+		}
+		bq, ok := n.(*ast.Blockquote)
+		if !ok {
+			return ast.WalkContinue, nil
+		}
+		if isGitHubAlert(bq, f.Source) {
+			findings = append(findings, blockFinding(f, bq, FeatureGitHubAlerts))
+		}
+		return ast.WalkContinue, nil
+	})
+	return findings
+}
+
+// isGitHubAlert reports whether bq is a GitHub Alert blockquote: its first
+// paragraph child's first line matches one of the five GFM alert tokens.
+func isGitHubAlert(bq *ast.Blockquote, source []byte) bool {
+	para, ok := bq.FirstChild().(*ast.Paragraph)
+	if !ok {
+		return false
+	}
+	seg := para.Lines().At(0)
+	firstLine := bytes.TrimRight(source[seg.Start:seg.Stop], "\r\n")
+	return alertTokenRe.Match(firstLine)
+}

internal/rules/markdownflavor/detect_test.go

@@ -231,3 +231,33 @@ func TestDetectFindingsAreSortedByStart(t *testing.T) {
 			i-1, fs[i-1], i, fs[i])
 	}
 }
+
+func TestDetectGitHubAlerts(t *testing.T) {
+	tokens := []string{"NOTE", "TIP", "IMPORTANT", "WARNING", "CAUTION"}
+	for _, tok := range tokens {
+		t.Run(tok, func(t *testing.T) {
+			fs := findings(t, "> [!"+tok+"]\n> Something.\n")
+			assert.True(t, hasFeature(fs, FeatureGitHubAlerts))
+		})
+	}
+}
+
+func TestDetectGitHubAlertsLowercaseNoMatch(t *testing.T) {
+	for _, src := range []string{
+		"> [!note]\n> text.\n",
+		"> [!INFO]\n> text.\n",
+	} {
+		fs := findings(t, src)
+		assert.False(t, hasFeature(fs, FeatureGitHubAlerts), "should not match: %q", src)
+	}
+}
+
+func TestDetectGitHubAlertsMixedContent(t *testing.T) {
+	fs := findings(t, "> [!NOTE]\n> Line one.\n> Line two.\n")
+	assert.True(t, hasFeature(fs, FeatureGitHubAlerts))
+}
+
+func TestDetectGitHubAlertsOnlyLine(t *testing.T) {
+	fs := findings(t, "> [!WARNING]\n")
+	assert.True(t, hasFeature(fs, FeatureGitHubAlerts))
+}

internal/rules/markdownflavor/features.go

@@ -108,6 +108,7 @@ const (
 	FeatureMathBlock
 	FeatureMathInline
 	FeatureAbbreviations
+	FeatureGitHubAlerts
 )
 
 // AllFeatures returns every tracked feature in declaration order.
@@ -125,6 +126,7 @@ func AllFeatures() []Feature {
 		FeatureMathBlock,
 		FeatureMathInline,
 		FeatureAbbreviations,
+		FeatureGitHubAlerts,
 	}
 }
 
@@ -136,6 +138,8 @@ func (f Feature) Verb() string {
 	case FeatureStrikethrough, FeatureSuperscript, FeatureSubscript,
 		FeatureMathInline:
 		return "is"
+	case FeatureGitHubAlerts:
+		return "are"
 	}
 	return "are"
 }
@@ -167,6 +171,8 @@ func (f Feature) Name() string {
 		return "inline math"
 	case FeatureAbbreviations:
 		return "abbreviations"
+	case FeatureGitHubAlerts:
+		return "github alerts"
 	}
 	return ""
 }
@@ -183,6 +189,7 @@ var support = map[Flavor]map[Feature]bool{
 		FeatureTaskLists:        true,
 		FeatureStrikethrough:    true,
 		FeatureBareURLAutolinks: true,
+		FeatureGitHubAlerts:     true,
 	},
 	FlavorGoldmark: {
 		FeatureTables:           true,