Fix MDS068 reference-style image misclassification (MD054)

checkLinkImageStyle routed every *ast.Image through the inline-image
toggle, ignoring node.Reference. Reference-style images (![alt][label],
![alt][], ![alt]) were therefore flagged by inline-image=false (wrong:
they are not inline images) and ignored by full/collapsed/shortcut=false
(wrong: those are their actual sub-forms) — contradicting the README and
struct comment, which scope inline-image to ![alt](src) only. The fork's
ast.Image embeds the same baseLink.Reference as ast.Link, so images now
route through the shared reference classifier: inline images use
inline-image; reference images use full/collapsed/shortcut, matching
MD054.

Also in autolinkPosition, match the literal `<url>` including the
closing `>` so a short autolink whose URL prefixes a neighbour's
(`<a.com>` beside `<a.com/x>`) resolves to its own column instead of the
longer one, and correct a comment that wrongly claimed email autolinks
are mailto:-prefixed (this fork returns the bare address).

Tests: reference-style image routing per sub-form, the regression guard
that inline-image=false leaves reference images alone, the autolink
prefix-collision column, and a deep-merge guard proving the
link-image-style sub-map merges across config layers.

https://claude.ai/code/session_015t5KNNUG7YjqTVr9ERXVyZ

Author: claude

internal/rules/MDS068-link-style/README.md

@@ -42,9 +42,9 @@ and `validate-reference-style` flow to MDS027, while `style` and
 | `links.style.link-image-style`              | map    | absent  | MD054 per-style toggles; absent means the axis is inactive (see below)                                                         |
 | `links.style.link-image-style.autolink`     | bool   | `true`  | Allow or forbid `<https://x>` autolinks                                                                                        |
 | `links.style.link-image-style.inline`       | bool   | `true`  | Allow or forbid `[t](u)` inline links                                                                                          |
-| `links.style.link-image-style.full`         | bool   | `true`  | Allow or forbid `[t][label]` full reference links                                                                              |
-| `links.style.link-image-style.collapsed`    | bool   | `true`  | Allow or forbid `[t][]` collapsed reference links                                                                              |
-| `links.style.link-image-style.shortcut`     | bool   | `true`  | Allow or forbid `[t]` shortcut reference links                                                                                 |
+| `links.style.link-image-style.full`         | bool   | `true`  | Allow or forbid `[t][label]` / `![alt][label]` full reference links and images                                                 |
+| `links.style.link-image-style.collapsed`    | bool   | `true`  | Allow or forbid `[t][]` / `![alt][]` collapsed reference links and images                                                      |
+| `links.style.link-image-style.shortcut`     | bool   | `true`  | Allow or forbid `[t]` / `![alt]` shortcut reference links and images                                                           |
 | `links.style.link-image-style.inline-image` | bool   | `true`  | Allow or forbid `![alt](src)` inline images                                                                                    |
 | `links.external-skip`                       | list   | `[]`    | Regex patterns reserved for the future external-link-check rule (issue #47); parsed here so users can declare it once per kind |
 
@@ -63,8 +63,11 @@ forced to migrate to `link-image-style`.
 
 External URLs (`http:`, `https:`, `mailto:`), local-anchor-only
 references are excluded from the `path`, `extension`, and `form`
-axes. The `link-image-style` axis checks `<url>` autolinks and inline
-images in addition to text links. The `path` and `form` axes apply to
+axes. The `link-image-style` axis checks `<url>` autolinks, inline and
+reference-style links, and inline and reference-style images. The
+reference sub-form toggles (`full`, `collapsed`, `shortcut`) apply to
+both links and images; `inline-image` governs only `![alt](src)`. The
+`path` and `form` axes apply to
 every local text link, including non-Markdown targets like `theme.css`.
 The `extension` axis is the only Markdown-shaped axis, described below.
 

internal/rules/linkstyle/rule.go

@@ -160,6 +160,17 @@ func (r *Rule) checkLinkImageStyle(f *lint.File) []lint.Diagnostic {
 	}
 	lis := r.Links.Style.LinkImageStyle
 	var diags []lint.Diagnostic
+	add := func(line, col int, msg string) {
+		diags = append(diags, lint.Diagnostic{
+			File:     f.Path,
+			Line:     line,
+			Column:   col,
+			RuleID:   r.ID(),
+			RuleName: r.Name(),
+			Severity: lint.Warning,
+			Message:  msg,
+		})
+	}
 	_ = ast.Walk(f.AST, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
 		if !entering {
 			return ast.WalkContinue, nil
@@ -168,60 +179,49 @@ func (r *Rule) checkLinkImageStyle(f *lint.File) []lint.Diagnostic {
 		case *ast.AutoLink:
 			if !lis.Autolink {
 				line, col := autolinkPosition(f, node)
-				diags = append(diags, lint.Diagnostic{
-					File:     f.Path,
-					Line:     line,
-					Column:   col,
-					RuleID:   r.ID(),
-					RuleName: r.Name(),
-					Severity: lint.Warning,
-					Message:  msgLISAutolink,
-				})
+				add(line, col, msgLISAutolink)
 			}
 		case *ast.Link:
-			msg := linkImageStyleMsg(lis, node)
-			if msg != "" {
+			if msg := linkImageStyleMsg(lis, node.Reference, false); msg != "" {
 				line, col := linkNodePosition(f, node)
-				diags = append(diags, lint.Diagnostic{
-					File:     f.Path,
-					Line:     line,
-					Column:   col,
-					RuleID:   r.ID(),
-					RuleName: r.Name(),
-					Severity: lint.Warning,
-					Message:  msg,
-				})
+				add(line, col, msg)
 			}
 		case *ast.Image:
-			if !lis.InlineImage {
+			// Images carry the same Reference sub-form as links, so a
+			// reference-style image (![alt][label], ![alt][], ![alt])
+			// is checked against full/collapsed/shortcut; only an
+			// inline image (![alt](src)) uses the inline-image toggle.
+			if msg := linkImageStyleMsg(lis, node.Reference, true); msg != "" {
 				line, col := linkNodePosition(f, node)
-				diags = append(diags, lint.Diagnostic{
-					File:     f.Path,
-					Line:     line,
-					Column:   col,
-					RuleID:   r.ID(),
-					RuleName: r.Name(),
-					Severity: lint.Warning,
-					Message:  msgLISInlineImage,
-				})
+				add(line, col, msg)
 			}
 		}
 		return ast.WalkContinue, nil
 	})
 	return diags
 }
 
-// linkImageStyleMsg returns the forbidden-style message for a Link
-// node, or "" if the node's form is allowed.
-func linkImageStyleMsg(lis LinkImageStyleConfig, l *ast.Link) string {
-	if l.Reference == nil {
-		// Inline link: [text](url)
+// linkImageStyleMsg returns the forbidden-style message for a link or
+// image node given its reference (nil for the inline form), or "" if
+// the form is allowed. isImage selects the inline-image vs inline
+// message for the non-reference case; the three reference sub-forms
+// (full/collapsed/shortcut) share their messages across links and
+// images, matching MD054.
+func linkImageStyleMsg(lis LinkImageStyleConfig, ref *ast.ReferenceLink, isImage bool) string {
+	if ref == nil {
+		// Inline form: [text](url) or ![alt](src).
+		if isImage {
+			if !lis.InlineImage {
+				return msgLISInlineImage
+			}
+			return ""
+		}
 		if !lis.Inline {
 			return msgLISInline
 		}
 		return ""
 	}
-	switch l.Reference.Type {
+	switch ref.Type {
 	case ast.ReferenceLinkFull:
 		if !lis.Full {
 			return msgLISFull
@@ -250,18 +250,22 @@ func autolinkPosition(f *lint.File, n *ast.AutoLink) (int, int) {
 	if len(url) == 0 {
 		return 1, 1
 	}
-	pat := append([]byte{'<'}, url...)
+	// Match the literal `<url>` including the closing `>`, so a short
+	// autolink whose URL is a prefix of a neighbour's (e.g. `<a.com>`
+	// beside `<a.com/x>` on one line) does not match the longer one.
+	pat := make([]byte, 0, len(url)+2)
+	pat = append(pat, '<')
+	pat = append(pat, url...)
+	pat = append(pat, '>')
 	// Walk up to the nearest block ancestor for a source range to
 	// search. Lines() panics on inline nodes, so skip any ancestor
 	// that is not a block (emphasis, link text, the document root).
 	for p := n.Parent(); p != nil; p = p.Parent() {
 		if p.Type() != ast.TypeBlock {
 			continue
 		}
-		// Search each source line for `<` followed by the URL. A block
-		// with no lines, or a URL that does not appear verbatim (e.g.
-		// an email autolink whose URL() is mailto:-prefixed), falls
-		// through to the (1,1) fallback below.
+		// Search each source line for the literal `<url>`. If no block
+		// line contains it, fall through to the (1,1) fallback below.
 		lines := p.Lines()
 		for i := range lines.Len() {
 			seg := lines.At(i)

internal/rules/linkstyle/rule_test.go

@@ -795,6 +795,119 @@ func TestAutolinkPosition_NotFoundFallsBack(t *testing.T) {
 	assert.Equal(t, 1, col)
 }
 
+// TestCheck_LinkImageStyle_ReferenceImagesUseReferenceToggles verifies
+// that reference-style images route to the full/collapsed/shortcut
+// toggles (shared with links), not the inline-image toggle.
+func TestCheck_LinkImageStyle_ReferenceImagesUseReferenceToggles(t *testing.T) {
+	cases := []struct {
+		name    string
+		src     string
+		lis     LinkImageStyleConfig
+		wantMsg string
+	}{
+		{
+			"full reference image forbidden by full",
+			"# Doc\n\n![alt][label]\n\n[label]: img.png\n",
+			LinkImageStyleConfig{Active: true, Autolink: true, Inline: true,
+				Full: false, Collapsed: true, Shortcut: true, InlineImage: true},
+			"full",
+		},
+		{
+			"collapsed reference image forbidden by collapsed",
+			"# Doc\n\n![label][]\n\n[label]: img.png\n",
+			LinkImageStyleConfig{Active: true, Autolink: true, Inline: true,
+				Full: true, Collapsed: false, Shortcut: true, InlineImage: true},
+			"collapsed",
+		},
+		{
+			"shortcut reference image forbidden by shortcut",
+			"# Doc\n\n![label]\n\n[label]: img.png\n",
+			LinkImageStyleConfig{Active: true, Autolink: true, Inline: true,
+				Full: true, Collapsed: true, Shortcut: false, InlineImage: true},
+			"shortcut",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			f := newFile(t, tc.src)
+			r := &Rule{Links: LinksConfig{Style: StyleConfig{LinkImageStyle: tc.lis}}}
+			diags := r.Check(f)
+			require.Len(t, diags, 1)
+			assert.Contains(t, diags[0].Message, tc.wantMsg)
+		})
+	}
+}
+
+// TestCheck_LinkImageStyle_ReferenceImageIgnoresInlineImageToggle is the
+// regression guard for the bug where every *ast.Image used the
+// inline-image toggle: a reference-style image must NOT be flagged by
+// inline-image:false, which governs only inline ![alt](src) images.
+func TestCheck_LinkImageStyle_ReferenceImageIgnoresInlineImageToggle(t *testing.T) {
+	src := "# Doc\n\n![alt][label]\n\n[label]: img.png\n"
+	f := newFile(t, src)
+	r := &Rule{Links: LinksConfig{Style: StyleConfig{
+		LinkImageStyle: LinkImageStyleConfig{
+			Active: true, Autolink: true, Inline: true, Full: true, Collapsed: true, Shortcut: true,
+			InlineImage: false,
+		},
+	}}}
+	assert.Empty(t, r.Check(f), "reference-style image must not be flagged by inline-image:false")
+}
+
+// TestCheck_LinkImageStyle_AutolinkPositionDistinguishesPrefixURLs
+// verifies the search pattern includes the closing `>` so a short
+// autolink whose URL prefixes a neighbour's resolves to its own column.
+func TestCheck_LinkImageStyle_AutolinkPositionDistinguishesPrefixURLs(t *testing.T) {
+	src := "# Doc\n\n<https://a.com/x> and <https://a.com>\n"
+	f := newFile(t, src)
+	r := &Rule{Links: LinksConfig{Style: StyleConfig{
+		LinkImageStyle: LinkImageStyleConfig{Active: true, Autolink: false,
+			Inline: true, Full: true, Collapsed: true, Shortcut: true, InlineImage: true},
+	}}}
+	diags := r.Check(f)
+	require.Len(t, diags, 2)
+	// Document order: the longer URL at column 1, then the short URL
+	// after "> and " at column 23 — not column 1 (the prefix match).
+	assert.Equal(t, 1, diags[0].Column)
+	assert.Equal(t, 23, diags[1].Column, "short autolink resolves to its own column, not the prefix match")
+}
+
+// TestApplySettings_LinkImageStyle_DeepMergeAcrossLayers verifies the
+// link-image-style sub-map deep-merges across config layers: a base
+// rules: layer and a kind layer each set a different toggle, and both
+// survive in the effective config.
+func TestApplySettings_LinkImageStyle_DeepMergeAcrossLayers(t *testing.T) {
+	cfg := &config.Config{
+		Rules: map[string]config.RuleCfg{
+			"link-style": {Enabled: true, Settings: map[string]any{
+				"links": map[string]any{"style": map[string]any{
+					"link-image-style": map[string]any{"inline": false},
+				}},
+			}},
+		},
+		Kinds: map[string]config.KindBody{
+			"docs": {Rules: map[string]config.RuleCfg{
+				"link-style": {Enabled: true, Settings: map[string]any{
+					"links": map[string]any{"style": map[string]any{
+						"link-image-style": map[string]any{"full": false},
+					}},
+				}},
+			}},
+		},
+		KindAssignment: []config.KindAssignmentEntry{
+			{Files: []string{"docs/**/*.md"}, Kinds: []string{"docs"}},
+		},
+	}
+	rules := config.Effective(cfg, "docs/guides/foo.md", nil, nil)
+	r := &Rule{}
+	require.NoError(t, r.ApplySettings(rules["link-style"].Settings))
+	lis := r.Links.Style.LinkImageStyle
+	assert.True(t, lis.Active)
+	assert.False(t, lis.Inline, "base layer inline:false must survive the kind's full:false override")
+	assert.False(t, lis.Full, "kind layer full:false must apply")
+	assert.True(t, lis.Collapsed, "an untouched toggle stays at its default allow")
+}
+
 func newFile(t *testing.T, src string) *lint.File {
 	t.Helper()
 	f, err := lint.NewFile("doc.md", []byte(src))