fix: escape QDoc markup

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

Author: jdkato

internal/lint/fragment.go

@@ -123,7 +123,7 @@ func (l *Linter) lintFragments(f *core.File) error {
 		case ".org":
 			err = l.lintOrg(f)
 		case ".qdoc":
-			err = l.lintQDoc(f)
+			err = l.lintQDocFragment(f)
 		default:
 			return fmt.Errorf("unsupported markup format '%s'", f.NormedExt)
 		}

internal/lint/qdoc.go

@@ -180,7 +180,7 @@ func (c *qdocConv) meta(kind, value string) {
 	if value == "" {
 		return
 	}
-	c.html.WriteString(`<data class="` + kind + `">` + value + "</data>\n")
+	c.html.WriteString(`<data class="` + kind + `">` + qdocEsc(value) + "</data>\n")
 }
 
 // qdocOpenDiv writes a `<div>` carrying `arg`'s class, if it names one.
@@ -200,6 +200,17 @@ var qdocInlineNames = map[string]struct{}{
 	"sub": {}, "sup": {}, "tt": {}, "uicontrol": {}, "underline": {},
 }
 
+// qdocEsc makes text safe to write into the HTML the walker reads.
+//
+// QDoc prose is kept word-for-word, and Qt's prose talks about markup: a
+// sentence explaining that a file "must be included using a <script> tag"
+// carries a real tag. Written straight through, it opens an element in the
+// converted document -- and `<script>` in particular puts the tokenizer into
+// raw-text mode, so the rest of the page is swallowed looking for a close
+// that never comes. The tokenizer decodes these again, so the text a rule
+// sees, and the text located in the source, are unchanged.
+var qdocEsc = strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;").Replace
+
 // qdocArg strips the braces from a command argument.
 func qdocArg(arg string) string {
 	if strings.HasPrefix(arg, "{") && strings.HasSuffix(arg, "}") {
@@ -217,10 +228,10 @@ func qdocInline(text string) string {
 	for {
 		loc := qdocInlineCmd.FindStringSubmatchIndex(text)
 		if loc == nil {
-			out.WriteString(text)
+			out.WriteString(qdocEsc(text))
 			break
 		}
-		out.WriteString(text[:loc[0]])
+		out.WriteString(qdocEsc(text[:loc[0]]))
 
 		if loc[2] < 0 {
 			// `\\` is a literal backslash, not a command.
@@ -238,15 +249,15 @@ func qdocInline(text string) string {
 
 		switch name {
 		case "c", "tt", "a":
-			out.WriteString("<code>" + qdocArg(arg) + "</code>")
+			out.WriteString("<code>" + qdocEsc(qdocArg(arg)) + "</code>")
 		case "b", "bold", "uicontrol":
-			out.WriteString("<strong>" + qdocArg(arg) + "</strong>")
+			out.WriteString("<strong>" + qdocEsc(qdocArg(arg)) + "</strong>")
 		case "e", "i":
-			out.WriteString("<em>" + qdocArg(arg) + "</em>")
+			out.WriteString("<em>" + qdocEsc(qdocArg(arg)) + "</em>")
 		case "underline":
-			out.WriteString("<u>" + qdocArg(arg) + "</u>")
+			out.WriteString("<u>" + qdocEsc(qdocArg(arg)) + "</u>")
 		case "sub", "sup":
-			out.WriteString("<" + name + ">" + qdocArg(arg) + "</" + name + ">")
+			out.WriteString("<" + name + ">" + qdocEsc(qdocArg(arg)) + "</" + name + ">")
 		case "l":
 			label := qdocArg(arg)
 			if strings.HasPrefix(arg, "{") {
@@ -255,7 +266,7 @@ func qdocInline(text string) string {
 					rest = rest[len(m):]
 				}
 			}
-			out.WriteString(`<a href="#">` + label + "</a>")
+			out.WriteString(`<a href="#">` + qdocEsc(label) + "</a>")
 		case "span":
 			// `\span {class="x"} {text}`: the attribute names a class a rule
 			// can be scoped to, the braced text that follows is prose.
@@ -265,9 +276,9 @@ func qdocInline(text string) string {
 				rest = rest[len(m):]
 			}
 			if class := qdocClass(arg); class != "" {
-				out.WriteString(`<span class="` + class + `">` + label + "</span>")
+				out.WriteString(`<span class="` + class + `">` + qdocEsc(label) + "</span>")
 			} else {
-				out.WriteString("<span>" + label + "</span>")
+				out.WriteString("<span>" + qdocEsc(label) + "</span>")
 			}
 		case "image", "inlineimage":
 			// The argument is a file name; a caption, if any, follows as
@@ -301,6 +312,11 @@ type qdocConv struct {
 	stack    []qdocContext
 	verbatim string // the \end command that closes the open verbatim block
 	omitted  bool
+
+	// inComment says whether the reader is inside a `/*! ... */` block, the
+	// only place QDoc looks. A comment body extracted from a source file
+	// starts inside one; a whole file starts outside.
+	inComment bool
 }
 
 func (c *qdocConv) flush() {
@@ -394,20 +410,46 @@ func (c *qdocConv) endsVerbatim(name string) bool {
 	return name == qdocVerbatim[c.verbatim] || name == "end"+c.verbatim
 }
 
-func (c *qdocConv) line(raw string) { //nolint:gocyclo // one case per command family
+// opensComment reports whether the line starts a `/*!` documentation comment.
+func qdocOpensComment(raw string) bool {
+	i := strings.Index(raw, "/*!")
+	return i >= 0 && strings.TrimSpace(raw[:i]) == ""
+}
+
+// line reads one line of a QDoc source, tracking which of them the reader is
+// meant to see at all.
+//
+// QDoc documents a project from its `/*! ... */` comments and nothing else.
+// A `.qdoc` file is a file of those comments, and what sits between them --
+// a licence header, a `//! [name]` snippet whose body is shell or C++ -- is
+// no more prose than the code in a `.cpp` file is.
+func (c *qdocConv) line(raw string) {
+	closes := strings.HasSuffix(strings.TrimSpace(raw), "*/")
+
 	// A verbatim or omitted block cannot outlive the comment holding it. An
 	// unterminated one -- a `\code` whose `\endcode` was never written, or a
 	// spelling this converter does not know -- would otherwise swallow the
 	// rest of the file.
-	if strings.HasSuffix(strings.TrimSpace(raw), "*/") {
+	if closes {
 		if c.verbatim != "" {
 			c.html.WriteString("</code></pre>\n")
 			c.verbatim = ""
 		}
 		c.omitted = false
 	}
 
-	raw = qdocBlankDelims(raw)
+	if c.inComment || qdocOpensComment(raw) {
+		c.inComment = true
+		c.content(qdocBlankDelims(raw))
+	}
+
+	if closes {
+		c.inComment = false
+		c.closeDiv()
+	}
+}
+
+func (c *qdocConv) content(raw string) { //nolint:gocyclo // one case per command family
 	trimmed := strings.TrimSpace(raw)
 
 	if c.verbatim != "" {
@@ -516,7 +558,7 @@ func (c *qdocConv) line(raw string) { //nolint:gocyclo // one case per command f
 		c.flush()
 		fields := strings.Fields(rest)
 		if len(fields) > 1 {
-			c.html.WriteString("<p><code>" + fields[0] + "</code> " +
+			c.html.WriteString("<p><code>" + qdocEsc(fields[0]) + "</code> " +
 				qdocInline(strings.Join(fields[1:], " ")) + "</p>\n")
 		}
 	case name == "quotation":
@@ -570,8 +612,16 @@ func (c *qdocConv) line(raw string) { //nolint:gocyclo // one case per command f
 	}
 }
 
-func qdocToHTML(content string) string {
-	conv := &qdocConv{}
+// qdocToHTML converts a whole QDoc source: the `/*! ... */` comments in it
+// are the document, and everything else is code.
+func qdocToHTML(content string) string { return qdocConvert(content, false) }
+
+// qdocFragmentToHTML converts the body of a single comment, already extracted
+// from a source file, so there is no `/*!` left to wait for.
+func qdocFragmentToHTML(content string) string { return qdocConvert(content, true) }
+
+func qdocConvert(content string, inComment bool) string {
+	conv := &qdocConv{inComment: inComment}
 	for _, line := range strings.Split(content, "\n") {
 		conv.line(line)
 	}
@@ -580,8 +630,17 @@ func qdocToHTML(content string) string {
 	return conv.html.String()
 }
 
-// lintQDoc lints QDoc: Qt's documentation markup.
+// lintQDoc lints a QDoc source: Qt's documentation markup.
 func (l *Linter) lintQDoc(f *core.File) error {
+	return l.lintQDocWith(f, qdocToHTML)
+}
+
+// lintQDocFragment lints one QDoc comment lifted out of a code file.
+func (l *Linter) lintQDocFragment(f *core.File) error {
+	return l.lintQDocWith(f, qdocFragmentToHTML)
+}
+
+func (l *Linter) lintQDocWith(f *core.File, convert func(string) string) error {
 	err := l.lintMetadata(f)
 	if err != nil {
 		return err
@@ -592,5 +651,5 @@ func (l *Linter) lintQDoc(f *core.File) error {
 		return err
 	}
 
-	return l.lintHTMLTokens(f, []byte(qdocToHTML(s)), 0)
+	return l.lintHTMLTokens(f, []byte(convert(s)), 0)
 }

internal/lint/qdoc_test.go

@@ -116,6 +116,12 @@ func TestQdocHTML(t *testing.T) {
 			[]string{"Prose one.", "Prose two."},
 			[]string{"intro", "//!"},
 		},
+		{
+			"prose about markup stays prose",
+			"The file must be included using a <script> tag.\n\nProse after it.\n",
+			[]string{"using a &lt;script&gt; tag.", "<p>Prose after it.</p>"},
+			nil,
+		},
 		{
 			"sa lines are markup",
 			"Prose here.\n\n\\sa QWidget, QObject\n",
@@ -251,7 +257,7 @@ func TestQdocHTML(t *testing.T) {
 
 	for _, c := range cases {
 		t.Run(c.name, func(t *testing.T) {
-			html := qdocToHTML(c.in)
+			html := qdocFragmentToHTML(c.in)
 
 			for _, want := range c.want {
 				if !strings.Contains(html, want) {
@@ -283,7 +289,7 @@ func TestQdocVerbatimClose(t *testing.T) {
 
 	for _, c := range cases {
 		t.Run(c.name, func(t *testing.T) {
-			html := qdocToHTML(c.in)
+			html := qdocFragmentToHTML(c.in)
 			if !strings.Contains(html, "<p>Prose here.</p>") {
 				t.Errorf("prose did not survive the block:\n%s", html)
 			}
@@ -293,3 +299,36 @@ func TestQdocVerbatimClose(t *testing.T) {
 		})
 	}
 }
+
+// TestQdocWholeFile pins that a `.qdoc` file is a file of `/*! ... */`
+// comments: a licence header, a `//! [name]` snippet body, and anything else
+// between them is code, however much it reads like prose.
+func TestQdocWholeFile(t *testing.T) {
+	const src = `// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial
+
+//! [15]
+md build_shared
+cd build_shared
+//! [15]
+
+/*!
+    \title A Real Heading
+    Real prose here.
+*/
+
+Trailing text outside any comment.
+`
+
+	html := qdocToHTML(src)
+	for _, want := range []string{"<h1>A Real Heading</h1>", "Real prose here."} {
+		if !strings.Contains(html, want) {
+			t.Errorf("missing %q in:\n%s", want, html)
+		}
+	}
+	for _, absent := range []string{"Copyright", "SPDX", "build_shared", "Trailing"} {
+		if strings.Contains(html, absent) {
+			t.Errorf("content outside a comment was kept (%q):\n%s", absent, html)
+		}
+	}
+}

testdata/e2e/lint.yaml

@@ -380,10 +380,107 @@ cases:
       test.qdoc:108:70:vale.Annotations:'TODO' left in text
       test.qdoc:113:45:vale.Annotations:'TODO' left in text
       test.qdoc:116:51:vale.Annotations:'XXX' left in text
+      test.qdoc:120:45:vale.Annotations:'TODO' left in text
+      test.qdoc:122:42:vale.Annotations:'XXX' left in text
     absent:
       - FIXME
       - NOTE
 
+  - name: qdoc-line-accuracy
+    about: an alert keeps its source line through the constructs a real Qt
+      page is built from -- a link split across lines, snippet markers,
+      custom macros, and a snippet reference
+    files:
+      .vale.ini: |
+        StylesPath = styles
+        MinAlertLevel = suggestion
+
+        [*]
+        T.Mark = YES
+      styles/T/Mark.yml: |
+        extends: existence
+        message: "'%s'"
+        level: error
+        nonword: true
+        raw:
+          - MARK[A-E]
+      crosslink.qdoc: |
+        /*!
+            \page qt-edu-for-designers.html
+            \title Qt Edu for Designers
+
+        //! [intro]
+            \e {Qt Edu for Designers} package contains \l {Qt Design Studio Manual}
+            {Qt Design Studio Enterprise}, allowing you to MARKA import.
+        //! [intro]
+
+            These instructions walk you through the installation.
+
+            \include qt-edu-steps.qdocinc {qt-edu-common-steps} {Qt Design Studio}
+
+            \image qt-edu-install-design-studio.png
+
+            With \e {Qt Edu for Designers} license, you get access to Qt Design
+            Studio. Select the \uicontrol {Design Tools} shortcut to install.
+
+            Select \uicontrol {Next}.
+
+            \include qt-edu-steps.qdocinc qt-edu-license-agreement
+
+            \section1 9. Finish the installation
+
+            Select \uicontrol {Install} to start the installation process.
+
+            Once installation is complete, you'll see the screen.
+
+            \image qt-edu-install-finish-design-studio.png
+
+            Select \uicontrol {Finish} to exit the installer.
+
+            \section1 10. Open Qt Design Studio
+
+            Go to the MARKB folder to see the tools that were installed.
+            Qt Design Studio is MARKC located under its own folder.
+        */
+      macros.qdoc: |
+        /*!
+            \class Example
+            \brief A brief description.
+
+            This works on \macos and \linux MARKA platforms.
+            The \QUL framework handles MARKB rendering accordingly.
+            Final sentence after MARKC macros.
+        */
+      markers.qdoc: |
+        /*!
+        //! [intro]
+            Prose line MARKA three.
+        //! [intro]
+
+            Prose line MARKB six.
+        */
+      snippet.qdoc: |
+        /*!
+            \class Loader
+            \brief Loads resources.
+
+            Use the loader as follows:
+            \snippet examples/loader.cpp setup
+            Prose after MARKA snippet should be included.
+        */
+    args: .
+    exit: 1
+    want: |
+      crosslink.qdoc:7:52:T.Mark:'MARKA'
+      crosslink.qdoc:35:15:T.Mark:'MARKB'
+      crosslink.qdoc:36:25:T.Mark:'MARKC'
+      macros.qdoc:5:37:T.Mark:'MARKA'
+      macros.qdoc:6:32:T.Mark:'MARKB'
+      macros.qdoc:7:26:T.Mark:'MARKC'
+      markers.qdoc:3:16:T.Mark:'MARKA'
+      markers.qdoc:6:16:T.Mark:'MARKB'
+      snippet.qdoc:7:17:T.Mark:'MARKA'
+
   - name: qdoc-classes
     about: "`.qdocinc` is QDoc without configuration, and `\\div` and `\\span`
       carry their class into the scope so a rule can target the prose they

testdata/fixtures/formats/test.qdoc

@@ -115,3 +115,9 @@
 
     \image screenshot-FIXME.png A caption with an XXX in it.
 */
+
+/*!
+    Include it with a <script> tag, and the TODO after it still counts.
+
+    Prose in a later paragraph keeps its XXX.
+*/