feat: add a meta scope for a document's machine-readable content

Signed-off-by: Joseph Kato <joseph@jdkato.io>

Author: jdkato

internal/lint/ast.go

@@ -266,6 +266,22 @@ func (l *Linter) lintHTMLTokens(f *core.File, raw []byte, offset int) error { //
 }
 
 func (l *Linter) lintScope(f *core.File, state *walker, txt string) error {
+	// A `data` element holds a document's machine-readable content -- an
+	// anchor name, a file name, an identifier -- which is in the document
+	// without being prose.
+	//
+	// Like `link` and `code`, `meta` is a sibling of `text` rather than a
+	// child of it, so an ordinary rule passes over it and only a rule that
+	// asks for `meta` does any work. That is the whole point: the name is
+	// reachable for a rule about naming, and invisible to a style about
+	// writing. It is not segmented either -- an identifier has no sentences.
+	if core.StringInSlice("data", state.tagHistory) {
+		f.Metrics["meta"]++
+
+		b := state.block(txt, withClasses("meta", state)+f.MetaScope+f.RealExt, 0)
+		return l.lintBlock(f, b, state.lines, 0, false)
+	}
+
 	for _, tag := range state.tagHistory {
 		scope, match := tagToScope[tag]
 		if (match && !core.StringInSlice(tag, inlineTags)) || heading.MatchString(tag) {

internal/lint/qdoc.go

@@ -70,7 +70,6 @@ var qdocSkipLine = map[string]struct{}{
 	"inqmlmodule":         {},
 	"instantiates":        {},
 	"internal":            {},
-	"keyword":             {},
 	"macro":               {},
 	"meta":                {},
 	"module":              {},
@@ -124,7 +123,6 @@ var qdocSkipLine = map[string]struct{}{
 	"snippet":             {},
 	"startpage":           {},
 	"tableofcontents":     {},
-	"target":              {},
 	"threadsafe":          {},
 	"toc":                 {},
 	"tocentry":            {},
@@ -175,6 +173,16 @@ func qdocClass(arg string) string {
 	return arg
 }
 
+// meta writes one piece of the document's machine-readable content -- an
+// anchor name, an image's file name -- under the `meta` scope, where a rule
+// about naming can reach it and a style about prose cannot.
+func (c *qdocConv) meta(kind, value string) {
+	if value == "" {
+		return
+	}
+	c.html.WriteString(`<data class="` + kind + `">` + value + "</data>\n")
+}
+
 // qdocOpenDiv writes a `<div>` carrying `arg`'s class, if it names one.
 func (c *qdocConv) openDiv(arg string) {
 	c.flush()
@@ -531,10 +539,18 @@ func (c *qdocConv) line(raw string) { //nolint:gocyclo // one case per command f
 	case name == "caption":
 		c.flush()
 		c.html.WriteString("<figcaption>" + qdocInline(rest) + "</figcaption>\n")
+	case name == "target", name == "keyword":
+		// The anchor a link points at: a name, reachable under `meta` for a
+		// rule about naming and invisible to one about prose.
+		c.flush()
+		c.meta("anchor", qdocArg(rest))
 	case name == "image", name == "inlineimage":
 		// `\image file.png An optional caption of prose.`
 		c.flush()
 		fields := strings.Fields(rest)
+		if len(fields) > 0 {
+			c.meta("image", fields[0])
+		}
 		if len(fields) > 1 {
 			c.html.WriteString("<figcaption>" +
 				qdocInline(strings.Join(fields[1:], " ")) + "</figcaption>\n")

internal/lint/qdoc_test.go

@@ -97,10 +97,18 @@ func TestQdocHTML(t *testing.T) {
 			[]string{"\\value"},
 		},
 		{
-			"an image's caption is prose, its file markup",
+			"an image's caption is prose, its file name metadata",
 			"\\image diagram.png A caption sentence.\n",
-			[]string{"<figcaption>A caption sentence.</figcaption>"},
-			[]string{"diagram.png"},
+			[]string{`<data class="image">diagram.png</data>`,
+				"<figcaption>A caption sentence.</figcaption>"},
+			nil,
+		},
+		{
+			"an anchor's name is metadata",
+			"\\target some-anchor\n\\keyword {Another Anchor}\n\nProse here.\n",
+			[]string{`<data class="anchor">some-anchor</data>`,
+				`<data class="anchor">Another Anchor</data>`, "<p>Prose here.</p>"},
+			[]string{"\\target", "\\keyword"},
 		},
 		{
 			"sa lines are markup",

testdata/e2e/lint.yaml

@@ -426,6 +426,95 @@ cases:
       api.qdocinc:3:7:T.Sidebar:'ZQX' in the sidebar
       api.qdocinc:8:35:T.Header:'ZQX' in a header span
 
+  - name: html-data
+    about: "`data` holds machine-readable content in any markup format, not
+      only QDoc: an ordinary rule passes over it"
+    files:
+      .vale.ini: |
+        StylesPath = styles
+        MinAlertLevel = suggestion
+
+        [*]
+        T.Prose = YES
+        T.Meta = YES
+      styles/T/Prose.yml: |
+        extends: existence
+        message: "'%s' as prose"
+        level: error
+        nonword: true
+        raw:
+          - ZQX
+      styles/T/Meta.yml: |
+        extends: existence
+        message: "'%s' as metadata"
+        scope: meta
+        level: error
+        nonword: true
+        raw:
+          - ZQX
+      page.html: |
+        <p>A ZQX in a paragraph.</p>
+        <data value="1">ZQX-identifier</data>
+    args: page.html
+    exit: 1
+    want: |
+      page.html:1:6:T.Prose:'ZQX' as prose
+      page.html:2:17:T.Meta:'ZQX' as metadata
+
+  - name: qdoc-meta
+    about: "anchor names and image file names are a document's machine-readable
+      content: an ordinary rule passes over them, and only a rule scoped to
+      `meta` reaches one"
+    files:
+      .vale.ini: |
+        StylesPath = styles
+        MinAlertLevel = suggestion
+
+        [*]
+        T.Prose = YES
+        T.Anchor = YES
+        T.Image = YES
+      styles/T/Prose.yml: |
+        extends: existence
+        message: "'%s' as prose"
+        level: error
+        nonword: true
+        raw:
+          - ZQX
+      styles/T/Anchor.yml: |
+        extends: existence
+        message: "'%s' in an anchor"
+        scope: meta.class.anchor
+        level: error
+        nonword: true
+        raw:
+          - ZQX
+      styles/T/Image.yml: |
+        extends: existence
+        message: "'%s' in a file name"
+        scope: meta.class.image
+        level: error
+        nonword: true
+        raw:
+          - ZQX
+      anchors.qdoc: |
+        /*!
+            \target ZQX-anchor
+            \keyword {ZQX Keyword}
+
+            A ZQX in ordinary prose.
+
+            \image ZQX-diagram.png A caption with a ZQX in it.
+        */
+    args: anchors.qdoc
+    exit: 1
+    want: |
+      anchors.qdoc:2:13:T.Anchor:'ZQX' in an anchor
+      anchors.qdoc:3:15:T.Anchor:'ZQX' in an anchor
+      anchors.qdoc:5:7:T.Prose:'ZQX' as prose
+      anchors.qdoc:7:12:T.Image:'ZQX' in a file name
+      anchors.qdoc:7:45:T.Prose:'ZQX' as prose
+
   - name: qdoc-fragments
     about: doc comments in C++ sources lint as QDoc through `[formats]`, with
       alerts mapped back to the source; only `/*!` is documentation, while