fix(title-require): allow comments inside non-empty <title>

- Check all text nodes inside <title> instead of only the last event, so
  titles mixing text with comments (e.g. Apache SSI directives) are not
  reported as empty
- Remove the @ts-expect-error workaround for event.lastEvent
- Add tests for comment-only and text-with-comment titles
- Update rule docs with comment examples

Fixes #1916

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: coliff

dist/core/rules/title-require.js

@@ -1,4 +1,4 @@
-import { Block, Listener } from '../htmlparser'
+import { Listener } from '../htmlparser'
 import { Rule } from '../types'
 
 export default {
@@ -7,26 +7,33 @@ export default {
   init(parser, reporter) {
     let headBegin = false
     let hasTitle = false
+    let inTitle = false
+    let titleHasText = false
 
     const onTagStart: Listener = (event) => {
       const tagName = event.tagName.toLowerCase()
       if (tagName === 'head') {
         headBegin = true
       } else if (tagName === 'title' && headBegin) {
         hasTitle = true
+        inTitle = true
+        titleHasText = false
+      }
+    }
+
+    // Any non-whitespace text inside <title> counts, so content mixed with
+    // comments (e.g. Apache SSI directives) is not reported as empty.
+    const onText: Listener = (event) => {
+      if (inTitle && /\S/.test(event.raw)) {
+        titleHasText = true
       }
     }
 
     const onTagEnd: Listener = (event) => {
       const tagName = event.tagName.toLowerCase()
       if (hasTitle && tagName === 'title') {
-        // TODO: fix this error
-        // @ts-expect-error
-        const lastEvent: Block = event.lastEvent
-        if (
-          lastEvent.type !== 'text' ||
-          (lastEvent.type === 'text' && /^\s*$/.test(lastEvent.raw) === true)
-        ) {
+        inTitle = false
+        if (!titleHasText) {
           reporter.error(
             '<title></title> must not be empty.',
             event.line,
@@ -48,10 +55,12 @@ export default {
 
         parser.removeListener('tagstart', onTagStart)
         parser.removeListener('tagend', onTagEnd)
+        parser.removeListener('text', onText)
       }
     }
 
     parser.addListener('tagstart', onTagStart)
     parser.addListener('tagend', onTagEnd)
+    parser.addListener('text', onText)
   },
 } as Rule

src/core/rules/title-require.ts

@@ -41,4 +41,30 @@ describe(`Rules: ${ruleId}`, () => {
     messages = HTMLHint.verify(code, ruleOptions)
     expect(messages.length).toBe(1)
   })
+
+  it('<title> containing only a comment should result in an error', () => {
+    const code =
+      '<html><head><title><!-- comment --></title></head><body></body></html>'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(1)
+  })
+
+  it('<title> with text and comments should not result in an error', () => {
+    let code =
+      '<html><head><title>test<!-- comment --></title></head><body></body></html>'
+    let messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+
+    code = `<html><head><title>
+    <!--#if expr="\${REDIRECT_STATUS} = 400"-->
+        Page Name: Bad Request
+    <!--#elif expr="\${REDIRECT_STATUS} = 404"-->
+        Page Name: Resource Not Found
+    <!--#else-->
+        Page Name: Error <!--#echo var="REDIRECT_STATUS"-->
+    <!--#endif-->
+</title></head><body></body></html>`
+    messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+  })
 })

test/rules/title-require.spec.js

@@ -22,13 +22,15 @@ Level: <Badge text="Error" variant="danger" />
 
 ```html
 <html><head><title>test</title></head></html>
+<html><head><title>test <!-- comment --></title></head></html>
 ```
 
 ### The following pattern is considered a rule violation:
 
 ```html
 <html><head></head></html>
 <html><head><title></title></head></html>
+<html><head><title><!-- comment --></title></head></html>
 <html><title></title><head></head></html>
 ```