@herb-tools/linter 0.8.7 → 0.8.8

package/dist/index.cjs

@@ -688,6 +688,8 @@ class ParserRule {
     static type = "parser";
     /** 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;
     get defaultConfig() {
         return DEFAULT_RULE_CONFIG;
     }
@@ -699,6 +701,8 @@ class LexerRule {
     static type = "lexer";
     /** 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;
     get defaultConfig() {
         return DEFAULT_RULE_CONFIG;
     }
@@ -716,6 +720,8 @@ class SourceRule {
     static type = "source";
     /** 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;
     get defaultConfig() {
         return DEFAULT_RULE_CONFIG;
     }
@@ -2189,6 +2195,335 @@ class ERBRightTrimRule extends ParserRule {
     }
 }
 
+/**
+ * File path and naming utilities for linter rules
+ */
+/**
+ * Extracts the basename (filename) from a file path
+ * Works with both forward slashes and backslashes
+ */
+function getBasename(filePath) {
+    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)
+ */
+function isPartialFile(fileName) {
+    if (!fileName)
+        return null;
+    return getBasename(fileName).startsWith("_");
+}
+
+/**
+ * Checks if parentheses in a string are balanced
+ * Returns false if there are more closing parens than opening at any point
+ */
+function hasBalancedParentheses(content) {
+    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"]
+ */
+function splitByTopLevelComma(str) {
+    const result = [];
+    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;
+}
+
+const STRICT_LOCALS_PATTERN = /^locals:\s*\([^)]*\)\s*$/;
+function isValidStrictLocalsFormat(content) {
+    return STRICT_LOCALS_PATTERN.test(content);
+}
+function extractERBCommentContent(content) {
+    return content.trim();
+}
+function extractRubyCommentContent(content) {
+    const match = content.match(/^\s*#\s*(.*)$/);
+    return match ? match[1].trim() : null;
+}
+function extractLocalsRemainder(content) {
+    const match = content.match(/^locals?\b(.*)$/);
+    return match ? match[1] : null;
+}
+function looksLikeLocalsDeclaration(content) {
+    return /^locals?\b/.test(content) && /[(:)]/.test(content);
+}
+function hasLocalsLikeSyntax(remainder) {
+    return /[(:)]/.test(remainder);
+}
+function detectLocalsWithoutColon(content) {
+    return /^locals?\(/.test(content);
+}
+function detectSingularLocal(content) {
+    return /^local:/.test(content);
+}
+function detectMissingColonBeforeParens(content) {
+    return /^locals\s+\(/.test(content);
+}
+function detectMissingParentheses(content) {
+    return /^locals:\s*[^(]/.test(content);
+}
+function detectEmptyLocalsWithoutParens(content) {
+    return /^locals:\s*$/.test(content);
+}
+function validateCommaUsage(inner) {
+    if (inner.startsWith(",") || inner.endsWith(",") || /,,/.test(inner)) {
+        return "Unexpected comma in `locals:` parameters.";
+    }
+    return null;
+}
+function validateBlockArgument(param) {
+    if (param.startsWith("&")) {
+        return `Block argument \`${param}\` is not allowed. Strict locals only support keyword arguments.`;
+    }
+    return null;
+}
+function validateSplatArgument(param) {
+    if (param.startsWith("*") && !param.startsWith("**")) {
+        return `Splat argument \`${param}\` is not allowed. Strict locals only support keyword arguments.`;
+    }
+    return null;
+}
+function validateDoubleSplatArgument(param) {
+    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) {
+    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) {
+    const trimmed = param.trim();
+    if (!trimmed)
+        return null;
+    return (validateBlockArgument(trimmed) ||
+        validateSplatArgument(trimmed) ||
+        validateDoubleSplatArgument(trimmed) ||
+        (trimmed.startsWith("**") ? null : validateKeywordArgument(trimmed)));
+}
+function validateLocalsSignature(paramsContent) {
+    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 {
+    seenStrictLocalsComment = false;
+    firstStrictLocalsLocation = null;
+    visitERBContentNode(node) {
+        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);
+    }
+    extractCommentContent(openingTag, content, node) {
+        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;
+    }
+    validateLocalsComment(commentContent, node) {
+        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);
+    }
+    checkPartialFile(node) {
+        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);
+        }
+    }
+    handleValidFormat(commentContent, node) {
+        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);
+            }
+        }
+    }
+    handleInvalidFormat(commentContent, node) {
+        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);
+    }
+}
+class ERBStrictLocalsCommentSyntaxRule extends ParserRule {
+    name = "erb-strict-locals-comment-syntax";
+    get defaultConfig() {
+        return {
+            enabled: true,
+            severity: "error"
+        };
+    }
+    check(result, context) {
+        const visitor = new ERBStrictLocalsCommentSyntaxVisitor(this.name, context);
+        visitor.visit(result.value);
+        return visitor.offenses;
+    }
+}
+
+function hasStrictLocals(source) {
+    return source.includes("<%# locals:") || source.includes("<%#locals:");
+}
+class ERBStrictLocalsRequiredVisitor extends BaseSourceRuleVisitor {
+    visitSource(source) {
+        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 = core.Location.from(1, 0, 1, firstLineLength);
+        this.addOffense("Partial is missing a strict locals declaration. Add `<%# locals: (...) %>` at the top of the file.", location);
+    }
+}
+class ERBStrictLocalsRequiredRule extends SourceRule {
+    static unsafeAutocorrectable = true;
+    name = "erb-strict-locals-required";
+    get defaultConfig() {
+        return {
+            enabled: false,
+            severity: "error",
+        };
+    }
+    check(source, context) {
+        const visitor = new ERBStrictLocalsRequiredVisitor(this.name, context);
+        visitor.visit(source);
+        return visitor.offenses;
+    }
+    autofix(_offense, source, _context) {
+        return `<%# locals: () %>\n\n${source}`;
+    }
+}
+
 /**
  * Utilities for parsing herb:disable comments
  */
@@ -3102,6 +3437,8 @@ class HeadOnlyElementsVisitor extends BaseRuleVisitor {
             return;
         if (tagName === "title" && this.insideSVG)
             return;
+        if (tagName === "style" && this.insideSVG)
+            return;
         if (tagName === "meta" && this.hasItempropAttribute(node))
             return;
         this.addOffense(`Element \`<${tagName}>\` must be placed inside the \`<head>\` tag.`, node.location);
@@ -3970,20 +4307,22 @@ class HTMLNoEmptyAttributesRule extends ParserRule {
 
 class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
     visitHTMLElementNode(node) {
+        const tagName = getTagName(node.open_tag)?.toLowerCase();
+        if (tagName === "template")
+            return;
         this.checkHeadingElement(node);
         super.visitHTMLElementNode(node);
     }
     checkHeadingElement(node) {
-        if (!node.open_tag || node.open_tag.type !== "AST_HTML_OPEN_TAG_NODE") {
+        if (!node.open_tag)
             return;
-        }
-        const openTag = node.open_tag;
-        const tagName = getTagName(openTag);
-        if (!tagName) {
+        if (!core.isHTMLOpenTagNode(node.open_tag))
+            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;
         }
@@ -4000,23 +4339,14 @@ class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
         }
         let hasAccessibleContent = false;
         for (const child of node.body) {
-            if (child.type === "AST_LITERAL_NODE") {
-                const literalNode = child;
-                if (literalNode.content.trim().length > 0) {
-                    hasAccessibleContent = true;
-                    break;
-                }
-            }
-            else if (child.type === "AST_HTML_TEXT_NODE") {
-                const textNode = child;
-                if (textNode.content.trim().length > 0) {
+            if (core.isLiteralNode(child) || core.isHTMLTextNode(child)) {
+                if (child.content.trim().length > 0) {
                     hasAccessibleContent = true;
                     break;
                 }
             }
-            else if (child.type === "AST_HTML_ELEMENT_NODE") {
-                const elementNode = child;
-                if (this.isElementAccessible(elementNode)) {
+            else if (core.isHTMLElementNode(child)) {
+                if (this.isElementAccessible(child)) {
                     hasAccessibleContent = true;
                     break;
                 }
@@ -4038,11 +4368,11 @@ class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
         return roleValue === "heading";
     }
     isElementAccessible(node) {
-        if (!node.open_tag || node.open_tag.type !== "AST_HTML_OPEN_TAG_NODE") {
+        if (!node.open_tag)
             return true;
-        }
-        const openTag = node.open_tag;
-        const attributes = getAttributes(openTag);
+        if (!core.isHTMLOpenTagNode(node.open_tag))
+            return true;
+        const attributes = getAttributes(node.open_tag);
         const ariaHiddenAttribute = findAttributeByName(attributes, "aria-hidden");
         if (ariaHiddenAttribute) {
             const ariaHiddenValue = getAttributeValue(ariaHiddenAttribute);
@@ -4054,21 +4384,13 @@ class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
             return false;
         }
         for (const child of node.body) {
-            if (child.type === "AST_LITERAL_NODE") {
-                const literalNode = child;
-                if (literalNode.content.trim().length > 0) {
+            if (core.isLiteralNode(child) || core.isHTMLTextNode(child)) {
+                if (child.content.trim().length > 0) {
                     return true;
                 }
             }
-            else if (child.type === "AST_HTML_TEXT_NODE") {
-                const textNode = child;
-                if (textNode.content.trim().length > 0) {
-                    return true;
-                }
-            }
-            else if (child.type === "AST_HTML_ELEMENT_NODE") {
-                const elementNode = child;
-                if (this.isElementAccessible(elementNode)) {
+            else if (core.isHTMLElementNode(child)) {
+                if (this.isElementAccessible(child)) {
                     return true;
                 }
             }
@@ -4673,6 +4995,8 @@ const rules = [
     ERBRequireTrailingNewlineRule,
     ERBRequireWhitespaceRule,
     ERBRightTrimRule,
+    ERBStrictLocalsCommentSyntaxRule,
+    ERBStrictLocalsRequiredRule,
     HerbDisableCommentValidRuleNameRule,
     HerbDisableCommentNoRedundantAllRule,
     HerbDisableCommentNoDuplicateRulesRule,
@@ -5086,9 +5410,12 @@ class Linter {
      * @param source - The source code to fix
      * @param context - Optional context for linting (e.g., fileName)
      * @param offensesToFix - Optional array of specific offenses to fix. If not provided, all fixable offenses will be fixed.
+     * @param options - Options for autofix behavior
+     * @param options.includeUnsafe - If true, also apply unsafe fixes (rules with unsafeAutocorrectable = true)
      * @returns AutofixResult containing the corrected source and lists of fixed/unfixed offenses
      */
-    autofix(source, context, offensesToFix) {
+    autofix(source, context, offensesToFix, options) {
+        const includeUnsafe = options?.includeUnsafe ?? false;
         const lintResult = offensesToFix ? { offenses: offensesToFix } : this.lint(source, context);
         const parserOffenses = [];
         const sourceOffenses = [];
@@ -5119,10 +5446,15 @@ class Linter {
                     continue;
                 }
                 const rule = new RuleClass();
+                const isUnsafe = RuleClass.unsafeAutocorrectable === true;
                 if (!rule.autofix) {
                     unfixed.push(offense);
                     continue;
                 }
+                if (isUnsafe && !includeUnsafe) {
+                    unfixed.push(offense);
+                    continue;
+                }
                 if (offense.autofixContext) {
                     const originalNodeType = offense.autofixContext.node.type;
                     const location = offense.autofixContext.node.location ? core.Location.from(offense.autofixContext.node.location) : offense.location;
@@ -5162,10 +5494,15 @@ class Linter {
                     continue;
                 }
                 const rule = new RuleClass();
+                const isUnsafe = RuleClass.unsafeAutocorrectable === true;
                 if (!rule.autofix) {
                     unfixed.push(offense);
                     continue;
                 }
+                if (isUnsafe && !includeUnsafe) {
+                    unfixed.push(offense);
+                    continue;
+                }
                 const correctedSource = rule.autofix(offense, currentSource, context);
                 if (correctedSource) {
                     currentSource = correctedSource;
@@ -5204,6 +5541,8 @@ exports.ERBPreferImageTagHelperRule = ERBPreferImageTagHelperRule;
 exports.ERBRequireTrailingNewlineRule = ERBRequireTrailingNewlineRule;
 exports.ERBRequireWhitespaceRule = ERBRequireWhitespaceRule;
 exports.ERBRightTrimRule = ERBRightTrimRule;
+exports.ERBStrictLocalsCommentSyntaxRule = ERBStrictLocalsCommentSyntaxRule;
+exports.ERBStrictLocalsRequiredRule = ERBStrictLocalsRequiredRule;
 exports.HEADING_TAGS = HEADING_TAGS;
 exports.HEAD_AND_BODY_TAG_NAMES = HEAD_AND_BODY_TAG_NAMES;
 exports.HEAD_ONLY_TAG_NAMES = HEAD_ONLY_TAG_NAMES;
@@ -5253,6 +5592,7 @@ exports.HerbDisableCommentValidRuleNameRule = HerbDisableCommentValidRuleNameRul
 exports.LexerRule = LexerRule;
 exports.Linter = Linter;
 exports.ParserRule = ParserRule;
+exports.STRICT_LOCALS_PATTERN = STRICT_LOCALS_PATTERN;
 exports.SVGTagNameCapitalizationRule = SVGTagNameCapitalizationRule;
 exports.SVG_CAMEL_CASE_ELEMENTS = SVG_CAMEL_CASE_ELEMENTS;
 exports.SVG_LOWERCASE_TO_CAMELCASE = SVG_LOWERCASE_TO_CAMELCASE;
@@ -5269,12 +5609,14 @@ exports.getAttributeValue = getAttributeValue;
 exports.getAttributeValueNodes = getAttributeValueNodes;
 exports.getAttributeValueQuoteType = getAttributeValueQuoteType;
 exports.getAttributes = getAttributes;
+exports.getBasename = getBasename;
 exports.getCombinedAttributeNameString = getCombinedAttributeNameString;
 exports.getStaticAttributeValue = getStaticAttributeValue;
 exports.getStaticAttributeValueContent = getStaticAttributeValueContent;
 exports.getTagName = getTagName;
 exports.hasAttribute = hasAttribute;
 exports.hasAttributeValue = hasAttributeValue;
+exports.hasBalancedParentheses = hasBalancedParentheses;
 exports.hasDynamicAttributeName = hasDynamicAttributeName;
 exports.hasDynamicAttributeValue = hasDynamicAttributeValue;
 exports.hasStaticAttributeValue = hasStaticAttributeValue;
@@ -5290,7 +5632,9 @@ exports.isHeadOnlyTag = isHeadOnlyTag;
 exports.isHeadTag = isHeadTag;
 exports.isHtmlOnlyTag = isHtmlOnlyTag;
 exports.isInlineElement = isInlineElement;
+exports.isPartialFile = isPartialFile;
 exports.isVoidElement = isVoidElement;
 exports.locationsEqual = locationsEqual;
 exports.rules = rules;
+exports.splitByTopLevelComma = splitByTopLevelComma;
 //# sourceMappingURL=index.cjs.map