@herb-tools/linter 0.8.7 → 0.8.8

package/src/rules/erb-strict-locals-comment-syntax.ts

@@ -0,0 +1,274 @@
+import { BaseRuleVisitor } from "./rule-utils.js"
+import { ParserRule } from "../types.js"
+
+import { isPartialFile } from "./file-utils.js"
+import { hasBalancedParentheses, splitByTopLevelComma } from "./string-utils.js"
+
+import type { UnboundLintOffense, LintContext, FullRuleConfig } from "../types.js"
+import type { ParseResult, ERBContentNode } from "@herb-tools/core"
+
+export const STRICT_LOCALS_PATTERN = /^locals:\s*\([^)]*\)\s*$/
+
+function isValidStrictLocalsFormat(content: string): boolean {
+  return STRICT_LOCALS_PATTERN.test(content)
+}
+
+function extractERBCommentContent(content: string): string {
+  return content.trim()
+}
+
+function extractRubyCommentContent(content: string): string | null {
+  const match = content.match(/^\s*#\s*(.*)$/)
+
+  return match ? match[1].trim() : null
+}
+
+function extractLocalsRemainder(content: string): string | null {
+  const match = content.match(/^locals?\b(.*)$/)
+
+  return match ? match[1] : null
+}
+
+function looksLikeLocalsDeclaration(content: string): boolean {
+  return /^locals?\b/.test(content) && /[(:)]/.test(content)
+}
+
+function hasLocalsLikeSyntax(remainder: string): boolean {
+  return /[(:)]/.test(remainder)
+}
+
+function detectLocalsWithoutColon(content: string): boolean {
+  return /^locals?\(/.test(content)
+}
+
+function detectSingularLocal(content: string): boolean {
+  return /^local:/.test(content)
+}
+
+function detectMissingColonBeforeParens(content: string): boolean {
+  return /^locals\s+\(/.test(content)
+}
+
+function detectMissingParentheses(content: string): boolean {
+  return /^locals:\s*[^(]/.test(content)
+}
+
+function detectEmptyLocalsWithoutParens(content: string): boolean {
+  return /^locals:\s*$/.test(content)
+}
+
+function validateCommaUsage(inner: string): string | null {
+  if (inner.startsWith(",") || inner.endsWith(",") || /,,/.test(inner)) {
+    return "Unexpected comma in `locals:` parameters."
+  }
+
+  return null
+}
+
+function validateBlockArgument(param: string): string | null {
+  if (param.startsWith("&")) {
+    return `Block argument \`${param}\` is not allowed. Strict locals only support keyword arguments.`
+  }
+
+  return null
+}
+
+function validateSplatArgument(param: string): string | null {
+  if (param.startsWith("*") && !param.startsWith("**")) {
+    return `Splat argument \`${param}\` is not allowed. Strict locals only support keyword arguments.`
+  }
+
+  return null
+}
+
+function validateDoubleSplatArgument(param: string): string | null {
+  if (param.startsWith("**")) {
+    if (/^\*\*\w+$/.test(param)) {
+      return null // Valid double-splat
+    }
+
+    return `Invalid double-splat syntax \`${param}\`. Use \`**name\` format (e.g., \`**attributes\`).`
+  }
+
+  return null
+}
+
+function validateKeywordArgument(param: string): string | null {
+  if (!/^\w+:\s*/.test(param)) {
+    if (/^\w+$/.test(param)) {
+      return `Positional argument \`${param}\` is not allowed. Use keyword argument format: \`${param}:\`.`
+    }
+
+    return `Invalid parameter \`${param}\`. Use keyword argument format: \`name:\` or \`name: default\`.`
+  }
+
+  return null
+}
+
+function validateParameter(param: string): string | null {
+  const trimmed = param.trim()
+
+  if (!trimmed) return null
+
+  return (
+    validateBlockArgument(trimmed) ||
+    validateSplatArgument(trimmed) ||
+    validateDoubleSplatArgument(trimmed) ||
+    (trimmed.startsWith("**") ? null : validateKeywordArgument(trimmed))
+  )
+}
+
+function validateLocalsSignature(paramsContent: string): string | null {
+  const match = paramsContent.match(/^\s*\(([\s\S]*)\)\s*$/)
+  if (!match) return null
+
+  const inner = match[1].trim()
+  if (!inner) return null // Empty locals is valid: locals: ()
+
+  const commaError = validateCommaUsage(inner)
+  if (commaError) return commaError
+
+  const params = splitByTopLevelComma(inner)
+
+  for (const param of params) {
+    const error = validateParameter(param)
+    if (error) return error
+  }
+
+  return null
+}
+
+class ERBStrictLocalsCommentSyntaxVisitor extends BaseRuleVisitor {
+  private seenStrictLocalsComment: boolean = false
+  private firstStrictLocalsLocation: { line: number; column: number } | null = null
+
+  visitERBContentNode(node: ERBContentNode): void {
+    const openingTag = node.tag_opening?.value
+    const content = node.content?.value
+
+    if (!content) return
+
+    const commentContent = this.extractCommentContent(openingTag, content, node)
+    if (!commentContent) return
+
+    const remainder = extractLocalsRemainder(commentContent)
+    if (!remainder || !hasLocalsLikeSyntax(remainder)) return
+
+    this.validateLocalsComment(commentContent, node)
+  }
+
+  private extractCommentContent(openingTag: string | undefined, content: string, node: ERBContentNode): string | null {
+    if (openingTag === "<%#") {
+      return extractERBCommentContent(content)
+    }
+
+    if (openingTag === "<%" || openingTag === "<%-") {
+      const rubyComment = extractRubyCommentContent(content)
+
+      if (rubyComment && looksLikeLocalsDeclaration(rubyComment)) {
+        this.addOffense(`Use \`<%#\` instead of \`${openingTag} #\` for strict locals comments. Only ERB comment syntax is recognized by Rails.`, node.location)
+      }
+    }
+
+    return null
+  }
+
+  private validateLocalsComment(commentContent: string, node: ERBContentNode): void {
+    this.checkPartialFile(node)
+
+    if (!hasBalancedParentheses(commentContent)) {
+      this.addOffense("Unbalanced parentheses in `locals:` comment. Ensure all opening parentheses have matching closing parentheses.", node.location)
+      return
+    }
+
+    if (isValidStrictLocalsFormat(commentContent)) {
+      this.handleValidFormat(commentContent, node)
+      return
+    }
+
+    this.handleInvalidFormat(commentContent, node)
+  }
+
+  private checkPartialFile(node: ERBContentNode): void {
+    const isPartial = isPartialFile(this.context.fileName)
+
+    if (isPartial === false) {
+      this.addOffense("Strict locals (`locals:`) only work in partials (files starting with `_`). This declaration will be ignored.", node.location)
+    }
+  }
+
+  private handleValidFormat(commentContent: string, node: ERBContentNode): void {
+    if (this.seenStrictLocalsComment) {
+      this.addOffense(
+        `Duplicate \`locals:\` declaration. Only one \`locals:\` comment is allowed per partial (first declaration at line ${this.firstStrictLocalsLocation?.line}).`,
+        node.location
+      )
+
+      return
+    }
+
+    this.seenStrictLocalsComment = true
+    this.firstStrictLocalsLocation = {
+      line: node.location.start.line,
+      column: node.location.start.column
+    }
+
+    const paramsMatch = commentContent.match(/^locals:\s*(\([\s\S]*\))\s*$/)
+
+    if (paramsMatch) {
+      const error = validateLocalsSignature(paramsMatch[1])
+
+      if (error) {
+        this.addOffense(error, node.location)
+      }
+    }
+  }
+
+  private handleInvalidFormat(commentContent: string, node: ERBContentNode): void {
+    if (detectLocalsWithoutColon(commentContent)) {
+      this.addOffense("Use `locals:` with a colon, not `locals()`. Correct format: `<%# locals: (...) %>`.", node.location)
+      return
+    }
+
+    if (detectSingularLocal(commentContent)) {
+      this.addOffense("Use `locals:` (plural), not `local:`.", node.location)
+      return
+    }
+
+    if (detectMissingColonBeforeParens(commentContent)) {
+      this.addOffense("Use `locals:` with a colon before the parentheses, not `locals (`.", node.location)
+      return
+    }
+
+    if (detectMissingParentheses(commentContent)) {
+      this.addOffense("Wrap parameters in parentheses: `locals: (name:)` or `locals: (name: default)`.", node.location)
+      return
+    }
+
+    if (detectEmptyLocalsWithoutParens(commentContent)) {
+      this.addOffense("Add parameters after `locals:`. Use `locals: (name:)` or `locals: ()` for no locals.", node.location)
+      return
+    }
+
+    this.addOffense("Invalid `locals:` syntax. Use format: `locals: (name:, option: default)`.", node.location)
+  }
+}
+
+export class ERBStrictLocalsCommentSyntaxRule extends ParserRule {
+  name = "erb-strict-locals-comment-syntax"
+
+  get defaultConfig(): FullRuleConfig {
+    return {
+      enabled: true,
+      severity: "error"
+    }
+  }
+
+  check(result: ParseResult, context?: Partial<LintContext>): UnboundLintOffense[] {
+    const visitor = new ERBStrictLocalsCommentSyntaxVisitor(this.name, context)
+
+    visitor.visit(result.value)
+
+    return visitor.offenses
+  }
+}

package/src/rules/erb-strict-locals-required.ts

@@ -0,0 +1,52 @@
+import { SourceRule } from "../types.js"
+import { Location } from "@herb-tools/core"
+import { BaseSourceRuleVisitor } from "./rule-utils.js"
+
+import { isPartialFile } from "./file-utils.js"
+
+import type { UnboundLintOffense, LintOffense, LintContext, FullRuleConfig } from "../types.js"
+
+function hasStrictLocals(source: string): boolean {
+  return source.includes("<%# locals:") || source.includes("<%#locals:")
+}
+
+class ERBStrictLocalsRequiredVisitor extends BaseSourceRuleVisitor {
+  protected visitSource(source: string): void {
+    const isPartial = isPartialFile(this.context.fileName)
+
+    if (isPartial !== true) return
+    if (hasStrictLocals(source)) return
+
+    const firstLineLength = source.indexOf("\n") === -1 ? source.length : source.indexOf("\n")
+    const location = Location.from(1, 0, 1, firstLineLength)
+
+    this.addOffense(
+      "Partial is missing a strict locals declaration. Add `<%# locals: (...) %>` at the top of the file.",
+      location
+    )
+  }
+}
+
+export class ERBStrictLocalsRequiredRule extends SourceRule {
+  static unsafeAutocorrectable = true
+  name = "erb-strict-locals-required"
+
+  get defaultConfig(): FullRuleConfig {
+    return {
+      enabled: false,
+      severity: "error",
+    }
+  }
+
+  check(source: string, context?: Partial<LintContext>): UnboundLintOffense[] {
+    const visitor = new ERBStrictLocalsRequiredVisitor(this.name, context)
+
+    visitor.visit(source)
+
+    return visitor.offenses
+  }
+
+  autofix(_offense: LintOffense, source: string, _context?: Partial<LintContext>): string | null {
+    return `<%# locals: () %>\n\n${source}`
+  }
+}

package/src/rules/file-utils.ts

@@ -0,0 +1,23 @@
+/**
+ * File path and naming utilities for linter rules
+ */
+
+/**
+ * Extracts the basename (filename) from a file path
+ * Works with both forward slashes and backslashes
+ */
+export function getBasename(filePath: string): string {
+  const lastSlash = Math.max(filePath.lastIndexOf("/"), filePath.lastIndexOf("\\"))
+
+  return lastSlash === -1 ? filePath : filePath.slice(lastSlash + 1)
+}
+
+/**
+ * Checks if a file is a Rails partial (filename starts with `_`)
+ * Returns null if fileName is undefined (unknown context)
+ */
+export function isPartialFile(fileName: string | undefined): boolean | null {
+  if (!fileName) return null
+
+  return getBasename(fileName).startsWith("_")
+}

package/src/rules/html-head-only-elements.ts

@@ -23,6 +23,7 @@ class HeadOnlyElementsVisitor extends BaseRuleVisitor {
     if (!this.insideBody) return
     if (!isHeadOnlyTag(tagName)) return
     if (tagName === "title" && this.insideSVG) return
+    if (tagName === "style" && this.insideSVG) return
     if (tagName === "meta" && this.hasItempropAttribute(node)) return
 
     this.addOffense(

package/src/rules/html-no-empty-headings.ts

@@ -1,31 +1,29 @@
 import { BaseRuleVisitor, getTagName, getAttributes, findAttributeByName, getAttributeValue, HEADING_TAGS } from "./rule-utils.js"
+import { isHTMLOpenTagNode, isLiteralNode, isHTMLTextNode, isHTMLElementNode } from "@herb-tools/core"
 
 import { ParserRule } from "../types.js"
 
 import type { UnboundLintOffense, LintContext, FullRuleConfig } from "../types.js"
-import type { HTMLElementNode, HTMLOpenTagNode, ParseResult, LiteralNode, HTMLTextNode } from "@herb-tools/core"
+import type { HTMLElementNode, HTMLOpenTagNode, ParseResult } from "@herb-tools/core"
 
 class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
   visitHTMLElementNode(node: HTMLElementNode): void {
+    const tagName = getTagName(node.open_tag)?.toLowerCase()
+    if (tagName === "template") return
+
     this.checkHeadingElement(node)
     super.visitHTMLElementNode(node)
   }
 
-
   private checkHeadingElement(node: HTMLElementNode): void {
-    if (!node.open_tag || node.open_tag.type !== "AST_HTML_OPEN_TAG_NODE") {
-      return
-    }
+    if (!node.open_tag) return
+    if (!isHTMLOpenTagNode(node.open_tag)) return
 
-    const openTag = node.open_tag as HTMLOpenTagNode
-    const tagName = getTagName(openTag)
-
-    if (!tagName) {
-      return
-    }
+    const tagName = getTagName(node.open_tag)
+    if (!tagName) return
 
     const isStandardHeading = HEADING_TAGS.has(tagName)
-    const isAriaHeading = this.hasHeadingRole(openTag)
+    const isAriaHeading = this.hasHeadingRole(node.open_tag)
 
     if (!isStandardHeading && !isAriaHeading) {
       return
@@ -43,7 +41,6 @@ class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
     }
   }
 
-
   private isEmptyHeading(node: HTMLElementNode): boolean {
     if (!node.body || node.body.length === 0) {
       return true
@@ -52,24 +49,13 @@ class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
     let hasAccessibleContent = false
 
     for (const child of node.body) {
-      if (child.type === "AST_LITERAL_NODE") {
-        const literalNode = child as LiteralNode
-
-        if (literalNode.content.trim().length > 0) {
+      if (isLiteralNode(child) || isHTMLTextNode(child)) {
+        if (child.content.trim().length > 0) {
           hasAccessibleContent = true
           break
         }
-      } else if (child.type === "AST_HTML_TEXT_NODE") {
-        const textNode = child as HTMLTextNode
-
-        if (textNode.content.trim().length > 0) {
-          hasAccessibleContent = true
-          break
-        }
-      } else if (child.type === "AST_HTML_ELEMENT_NODE") {
-        const elementNode = child as HTMLElementNode
-
-        if (this.isElementAccessible(elementNode)) {
+      } else if (isHTMLElementNode(child)) {
+        if (this.isElementAccessible(child)) {
           hasAccessibleContent = true
           break
         }
@@ -95,12 +81,10 @@ class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
   }
 
   private isElementAccessible(node: HTMLElementNode): boolean {
-    if (!node.open_tag || node.open_tag.type !== "AST_HTML_OPEN_TAG_NODE") {
-      return true
-    }
+    if (!node.open_tag) return true
+    if (!isHTMLOpenTagNode(node.open_tag)) return true
 
-    const openTag = node.open_tag as HTMLOpenTagNode
-    const attributes = getAttributes(openTag)
+    const attributes = getAttributes(node.open_tag)
     const ariaHiddenAttribute = findAttributeByName(attributes, "aria-hidden")
 
     if (ariaHiddenAttribute) {
@@ -116,19 +100,12 @@ class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
     }
 
     for (const child of node.body) {
-      if (child.type === "AST_LITERAL_NODE") {
-        const literalNode = child as LiteralNode
-        if (literalNode.content.trim().length > 0) {
-          return true
-        }
-      } else if (child.type === "AST_HTML_TEXT_NODE") {
-        const textNode = child as HTMLTextNode
-        if (textNode.content.trim().length > 0) {
+      if (isLiteralNode(child) || isHTMLTextNode(child)) {
+        if (child.content.trim().length > 0) {
           return true
         }
-      } else if (child.type === "AST_HTML_ELEMENT_NODE") {
-        const elementNode = child as HTMLElementNode
-        if (this.isElementAccessible(elementNode)) {
+      } else if (isHTMLElementNode(child)) {
+        if (this.isElementAccessible(child)) {
           return true
         }
       } else {

package/src/rules/index.ts

@@ -1,4 +1,6 @@
 export * from "./rule-utils.js"
+export * from "./file-utils.js"
+export * from "./string-utils.js"
 export * from "./herb-disable-comment-base.js"
 
 export * from "./erb-comment-syntax.js"
@@ -12,6 +14,8 @@ export * from "./erb-prefer-image-tag-helper.js"
 export * from "./erb-require-trailing-newline.js"
 export * from "./erb-require-whitespace-inside-tags.js"
 export * from "./erb-right-trim.js"
+export * from "./erb-strict-locals-comment-syntax.js"
+export * from "./erb-strict-locals-required.js"
 
 export * from "./herb-disable-comment-valid-rule-name.js"
 export * from "./herb-disable-comment-no-redundant-all.js"

package/src/rules/string-utils.ts

@@ -0,0 +1,72 @@
+/**
+ * Checks if parentheses in a string are balanced
+ * Returns false if there are more closing parens than opening at any point
+ */
+export function hasBalancedParentheses(content: string): boolean {
+  let depth = 0
+
+  for (const char of content) {
+    if (char === "(") depth++
+    if (char === ")") depth--
+    if (depth < 0) return false
+  }
+
+  return depth === 0
+}
+
+/**
+ * Splits a string by commas at the top level only
+ * Respects nested parentheses, brackets, braces, and strings
+ *
+ * @example
+ * splitByTopLevelComma("a, b, c") // ["a", " b", " c"]
+ * splitByTopLevelComma("a, (b, c), d") // ["a", " (b, c)", " d"]
+ * splitByTopLevelComma('a, "b, c", d') // ["a", ' "b, c"', " d"]
+ */
+export function splitByTopLevelComma(str: string): string[] {
+  const result: string[] = []
+
+  let current = ""
+  let parenDepth = 0
+  let bracketDepth = 0
+  let braceDepth = 0
+  let inString = false
+  let stringChar = ""
+
+  for (let i = 0; i < str.length; i++) {
+    const char = str[i]
+    const previousChar = i > 0 ? str[i - 1] : ""
+
+    if ((char === '"' || char === "'") && previousChar !== "\\") {
+      if (!inString) {
+        inString = true
+        stringChar = char
+      } else if (char === stringChar) {
+        inString = false
+      }
+    }
+
+    if (!inString) {
+      if (char === "(") parenDepth++
+      if (char === ")") parenDepth--
+      if (char === "[") bracketDepth++
+      if (char === "]") bracketDepth--
+      if (char === "{") braceDepth++
+      if (char === "}") braceDepth--
+
+      if (char === "," && parenDepth === 0 && bracketDepth === 0 && braceDepth === 0) {
+        result.push(current)
+        current = ""
+        continue
+      }
+    }
+
+    current += char
+  }
+
+  if (current) {
+    result.push(current)
+  }
+
+  return result
+}

package/src/rules.ts

@@ -11,6 +11,8 @@ import { ERBPreferImageTagHelperRule } from "./rules/erb-prefer-image-tag-helper
 import { ERBRequireTrailingNewlineRule } from "./rules/erb-require-trailing-newline.js"
 import { ERBRequireWhitespaceRule } from "./rules/erb-require-whitespace-inside-tags.js"
 import { ERBRightTrimRule } from "./rules/erb-right-trim.js"
+import { ERBStrictLocalsCommentSyntaxRule } from "./rules/erb-strict-locals-comment-syntax.js"
+import { ERBStrictLocalsRequiredRule } from "./rules/erb-strict-locals-required.js"
 
 import { HerbDisableCommentValidRuleNameRule } from "./rules/herb-disable-comment-valid-rule-name.js"
 import { HerbDisableCommentNoRedundantAllRule } from "./rules/herb-disable-comment-no-redundant-all.js"
@@ -67,6 +69,8 @@ export const rules: RuleClass[] = [
   ERBRequireTrailingNewlineRule,
   ERBRequireWhitespaceRule,
   ERBRightTrimRule,
+  ERBStrictLocalsCommentSyntaxRule,
+  ERBStrictLocalsRequiredRule,
 
   HerbDisableCommentValidRuleNameRule,
   HerbDisableCommentNoRedundantAllRule,

package/src/types.ts

@@ -85,6 +85,8 @@ export abstract class ParserRule<TAutofixContext extends BaseAutofixContext = Ba
   static type = "parser" as const
   /** Indicates whether this rule supports autofix. Defaults to false. */
   static autocorrectable = false
+  /** Indicates whether this rule supports unsafe autofix (requires --fix-unsafely). Defaults to false. */
+  static unsafeAutocorrectable = false
   abstract name: string
 
   get defaultConfig(): FullRuleConfig {
@@ -119,6 +121,8 @@ export abstract class LexerRule<TAutofixContext extends BaseAutofixContext = Bas
   static type = "lexer" as const
   /** Indicates whether this rule supports autofix. Defaults to false. */
   static autocorrectable = false
+  /** Indicates whether this rule supports unsafe autofix (requires --fix-unsafely). Defaults to false. */
+  static unsafeAutocorrectable = false
   abstract name: string
 
   get defaultConfig(): FullRuleConfig {
@@ -176,6 +180,8 @@ export abstract class SourceRule<TAutofixContext extends BaseAutofixContext = Ba
   static type = "source" as const
   /** Indicates whether this rule supports autofix. Defaults to false. */
   static autocorrectable = false
+  /** Indicates whether this rule supports unsafe autofix (requires --fix-unsafely). Defaults to false. */
+  static unsafeAutocorrectable = false
   abstract name: string
 
   get defaultConfig(): FullRuleConfig {