@herb-tools/linter 0.4.2 → 0.4.3

package/dist/index.cjs

@@ -2,15 +2,33 @@
 
 var core = require('@herb-tools/core');
 
+class ParserRule {
+    static type = "parser";
+}
+class LexerRule {
+    static type = "lexer";
+}
+/**
+ * Default context object with all keys defined but set to undefined
+ */
+const DEFAULT_LINT_CONTEXT = {
+    fileName: undefined
+};
+class SourceRule {
+    static type = "source";
+}
+
 /**
  * Base visitor class that provides common functionality for rule visitors
  */
 class BaseRuleVisitor extends core.Visitor {
     offenses = [];
     ruleName;
-    constructor(ruleName) {
+    context;
+    constructor(ruleName, context) {
         super();
         this.ruleName = ruleName;
+        this.context = { ...DEFAULT_LINT_CONTEXT, ...context };
     }
     /**
      * Helper method to create a lint offense
@@ -253,6 +271,19 @@ const ARIA_ATTRIBUTES = new Set([
     'aria-valuenow',
     'aria-valuetext',
 ]);
+/**
+ * Helper function to create a location at the end of the source with a 1-character range
+ */
+function createEndOfFileLocation(source) {
+    const lines = source.split('\n');
+    const lastLineNumber = lines.length;
+    const lastLine = lines[lines.length - 1];
+    const lastColumnNumber = lastLine.length;
+    const startColumn = lastColumnNumber > 0 ? lastColumnNumber - 1 : 0;
+    const start = new core.Position(lastLineNumber, startColumn);
+    const end = new core.Position(lastLineNumber, lastColumnNumber);
+    return new core.Location(start, end);
+}
 /**
  * Checks if an element is inline
  */
@@ -277,6 +308,9 @@ function isBooleanAttribute(attributeName) {
  * and attribute iteration logic. Provides simplified interface with extracted attribute info.
  */
 class AttributeVisitorMixin extends BaseRuleVisitor {
+    constructor(ruleName, context) {
+        super(ruleName, context);
+    }
     visitHTMLOpenTagNode(node) {
         this.checkAttributesOnNode(node);
         super.visitHTMLOpenTagNode(node);
@@ -306,6 +340,56 @@ function forEachAttribute(node, callback) {
         }
     }
 }
+/**
+ * Base source visitor class that provides common functionality for source-based rule visitors
+ */
+class BaseSourceRuleVisitor {
+    offenses = [];
+    ruleName;
+    context;
+    constructor(ruleName, context) {
+        this.ruleName = ruleName;
+        this.context = { ...DEFAULT_LINT_CONTEXT, ...context };
+    }
+    /**
+     * Helper method to create a lint offense for source rules
+     */
+    createOffense(message, location, severity = "error") {
+        return {
+            rule: this.ruleName, // Type assertion for compatibility
+            code: this.ruleName,
+            source: "Herb Linter",
+            message,
+            location,
+            severity,
+        };
+    }
+    /**
+     * Helper method to add an offense to the offenses array
+     */
+    addOffense(message, location, severity = "error") {
+        this.offenses.push(this.createOffense(message, location, severity));
+    }
+    /**
+     * Main entry point for source rule visitors
+     * @param source - The raw source code
+     */
+    visit(source) {
+        this.visitSource(source);
+    }
+    /**
+     * Helper method to create a location for a specific position in the source
+     */
+    createLocationAt(source, position) {
+        const beforePosition = source.substring(0, position);
+        const lines = beforePosition.split('\n');
+        const line = lines.length;
+        const column = lines[lines.length - 1].length + 1;
+        const start = new core.Position(line, column);
+        const end = new core.Position(line, column);
+        return new core.Location(start, end);
+    }
+}
 
 class ERBNoEmptyTagsVisitor extends BaseRuleVisitor {
     visitERBContentNode(node) {
@@ -320,10 +404,10 @@ class ERBNoEmptyTagsVisitor extends BaseRuleVisitor {
         this.addOffense("ERB tag should not be empty. Remove empty ERB tags or add content.", node.location, "error");
     }
 }
-class ERBNoEmptyTagsRule {
+class ERBNoEmptyTagsRule extends ParserRule {
     name = "erb-no-empty-tags";
-    check(node) {
-        const visitor = new ERBNoEmptyTagsVisitor(this.name);
+    check(node, context) {
+        const visitor = new ERBNoEmptyTagsVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -366,15 +450,126 @@ class ERBNoOutputControlFlowRuleVisitor extends BaseRuleVisitor {
         return;
     }
 }
-class ERBNoOutputControlFlowRule {
+class ERBNoOutputControlFlowRule extends ParserRule {
     name = "erb-no-output-control-flow";
-    check(node) {
-        const visitor = new ERBNoOutputControlFlowRuleVisitor(this.name);
+    check(node, context) {
+        const visitor = new ERBNoOutputControlFlowRuleVisitor(this.name, context);
+        visitor.visit(node);
+        return visitor.offenses;
+    }
+}
+
+class ERBPreferImageTagHelperVisitor extends BaseRuleVisitor {
+    visitHTMLOpenTagNode(node) {
+        this.checkImgTag(node);
+        super.visitHTMLOpenTagNode(node);
+    }
+    visitHTMLSelfCloseTagNode(node) {
+        this.checkImgTag(node);
+        super.visitHTMLSelfCloseTagNode(node);
+    }
+    checkImgTag(node) {
+        const tagName = getTagName(node);
+        if (tagName !== "img") {
+            return;
+        }
+        const attributes = getAttributes(node);
+        const srcAttribute = findAttributeByName(attributes, "src");
+        if (!srcAttribute) {
+            return;
+        }
+        if (!srcAttribute.value) {
+            return;
+        }
+        const valueNode = srcAttribute.value;
+        const hasERBContent = this.containsERBContent(valueNode);
+        if (hasERBContent) {
+            const suggestedExpression = this.buildSuggestedExpression(valueNode);
+            this.addOffense(`Prefer \`image_tag\` helper over manual \`<img>\` with dynamic ERB expressions. Use \`<%= image_tag ${suggestedExpression}, alt: "..." %>\` instead.`, srcAttribute.location, "warning");
+        }
+    }
+    containsERBContent(valueNode) {
+        if (!valueNode.children)
+            return false;
+        return valueNode.children.some(child => child.type === "AST_ERB_CONTENT_NODE");
+    }
+    buildSuggestedExpression(valueNode) {
+        if (!valueNode.children)
+            return "expression";
+        let hasText = false;
+        let hasERB = false;
+        for (const child of valueNode.children) {
+            if (child.type === "AST_ERB_CONTENT_NODE") {
+                hasERB = true;
+            }
+            else if (child.type === "AST_LITERAL_NODE") {
+                const literalNode = child;
+                if (literalNode.content && literalNode.content.trim()) {
+                    hasText = true;
+                }
+            }
+        }
+        if (hasText && hasERB) {
+            let result = '"';
+            for (const child of valueNode.children) {
+                if (child.type === "AST_ERB_CONTENT_NODE") {
+                    const erbNode = child;
+                    result += `#{${(erbNode.content?.value || "").trim()}}`;
+                }
+                else if (child.type === "AST_LITERAL_NODE") {
+                    const literalNode = child;
+                    result += literalNode.content || "";
+                }
+            }
+            result += '"';
+            return result;
+        }
+        if (hasERB && !hasText) {
+            const erbNodes = valueNode.children.filter(child => child.type === "AST_ERB_CONTENT_NODE");
+            if (erbNodes.length === 1) {
+                return (erbNodes[0].content?.value || "").trim();
+            }
+            else if (erbNodes.length > 1) {
+                let result = '"';
+                for (const erbNode of erbNodes) {
+                    result += `#{${(erbNode.content?.value || "").trim()}}`;
+                }
+                result += '"';
+                return result;
+            }
+        }
+        return "expression";
+    }
+}
+class ERBPreferImageTagHelperRule extends ParserRule {
+    name = "erb-prefer-image-tag-helper";
+    check(node, context) {
+        const visitor = new ERBPreferImageTagHelperVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
 }
 
+class ERBRequiresTrailingNewlineVisitor extends BaseSourceRuleVisitor {
+    visitSource(source) {
+        if (source.length === 0)
+            return;
+        if (source.endsWith('\n'))
+            return;
+        if (!this.context.fileName)
+            return;
+        this.addOffense("File must end with trailing newline", createEndOfFileLocation(source), "error");
+    }
+}
+class ERBRequiresTrailingNewlineRule extends SourceRule {
+    name = "erb-requires-trailing-newline";
+    check(source, context) {
+        const visitor = new ERBRequiresTrailingNewlineVisitor(this.name, context);
+        visitor.visit(source);
+        return visitor.offenses;
+    }
+}
+
 class RequireWhitespaceInsideTags extends BaseRuleVisitor {
     visitChildNodes(node) {
         this.checkWhitespace(node);
@@ -423,10 +618,10 @@ class RequireWhitespaceInsideTags extends BaseRuleVisitor {
         this.addOffense(`Add whitespace before \`${closeTag.value}\`.`, closeTag.location, "error");
     }
 }
-class ERBRequireWhitespaceRule {
+class ERBRequireWhitespaceRule extends ParserRule {
     name = "erb-require-whitespace-inside-tags";
-    check(node) {
-        const visitor = new RequireWhitespaceInsideTags(this.name);
+    check(node, context) {
+        const visitor = new RequireWhitespaceInsideTags(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -447,10 +642,10 @@ class AnchorRechireHrefVisitor extends BaseRuleVisitor {
         }
     }
 }
-class HTMLAnchorRequireHrefRule {
+class HTMLAnchorRequireHrefRule extends ParserRule {
     name = "html-anchor-require-href";
-    check(node) {
-        const visitor = new AnchorRechireHrefVisitor(this.name);
+    check(node, context) {
+        const visitor = new AnchorRechireHrefVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -470,10 +665,35 @@ class AriaAttributeMustBeValid extends AttributeVisitorMixin {
         }
     }
 }
-class HTMLAriaAttributeMustBeValid {
+class HTMLAriaAttributeMustBeValid extends ParserRule {
     name = "html-aria-attribute-must-be-valid";
-    check(node) {
-        const visitor = new AriaAttributeMustBeValid(this.name);
+    check(node, context) {
+        const visitor = new AriaAttributeMustBeValid(this.name, context);
+        visitor.visit(node);
+        return visitor.offenses;
+    }
+}
+
+class HTMLAriaLevelMustBeValidVisitor extends AttributeVisitorMixin {
+    checkAttribute(attributeName, attributeValue, attributeNode, _parentNode) {
+        if (attributeName !== "aria-level")
+            return;
+        if (attributeValue !== null && attributeValue.includes("<%"))
+            return;
+        if (attributeValue === null || attributeValue === "") {
+            this.addOffense(`The \`aria-level\` attribute must be an integer between 1 and 6, got an empty value.`, attributeNode.location);
+            return;
+        }
+        const number = parseInt(attributeValue);
+        if (isNaN(number) || number < 1 || number > 6 || attributeValue !== number.toString()) {
+            this.addOffense(`The \`aria-level\` attribute must be an integer between 1 and 6, got \`${attributeValue}\`.`, attributeNode.location);
+        }
+    }
+}
+class HTMLAriaLevelMustBeValidRule extends ParserRule {
+    name = "html-aria-level-must-be-valid";
+    check(node, context) {
+        const visitor = new HTMLAriaLevelMustBeValidVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -495,10 +715,10 @@ class AriaRoleHeadingRequiresLevel extends AttributeVisitorMixin {
         }
     }
 }
-class HTMLAriaRoleHeadingRequiresLevelRule {
+class HTMLAriaRoleHeadingRequiresLevelRule extends ParserRule {
     name = "html-aria-role-heading-requires-level";
-    check(node) {
-        const visitor = new AriaRoleHeadingRequiresLevel(this.name);
+    check(node, context) {
+        const visitor = new AriaRoleHeadingRequiresLevel(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -515,10 +735,10 @@ class AriaRoleMustBeValid extends AttributeVisitorMixin {
         this.addOffense(`The \`role\` attribute must be a valid ARIA role. Role \`${attributeValue}\` is not recognized.`, attributeNode.location, "error");
     }
 }
-class HTMLAriaRoleMustBeValidRule {
+class HTMLAriaRoleMustBeValidRule extends ParserRule {
     name = "html-aria-role-must-be-valid";
-    check(node) {
-        const visitor = new AriaRoleMustBeValid(this.name);
+    check(node, context) {
+        const visitor = new AriaRoleMustBeValid(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -535,10 +755,10 @@ class AttributeDoubleQuotesVisitor extends AttributeVisitorMixin {
         this.addOffense(`Attribute \`${attributeName}\` uses single quotes. Prefer double quotes for HTML attribute values: \`${attributeName}="value"\`.`, attributeNode.value.location, "warning");
     }
 }
-class HTMLAttributeDoubleQuotesRule {
+class HTMLAttributeDoubleQuotesRule extends ParserRule {
     name = "html-attribute-double-quotes";
-    check(node) {
-        const visitor = new AttributeDoubleQuotesVisitor(this.name);
+    check(node, context) {
+        const visitor = new AttributeDoubleQuotesVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -556,10 +776,10 @@ class AttributeValuesRequireQuotesVisitor extends AttributeVisitorMixin {
         `Attribute value should be quoted: \`${attributeName}="value"\`. Always wrap attribute values in quotes.`, valueNode.location, "error");
     }
 }
-class HTMLAttributeValuesRequireQuotesRule {
+class HTMLAttributeValuesRequireQuotesRule extends ParserRule {
     name = "html-attribute-values-require-quotes";
-    check(node) {
-        const visitor = new AttributeValuesRequireQuotesVisitor(this.name);
+    check(node, context) {
+        const visitor = new AttributeValuesRequireQuotesVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -574,10 +794,10 @@ class BooleanAttributesNoValueVisitor extends AttributeVisitorMixin {
         this.addOffense(`Boolean attribute \`${attributeName}\` should not have a value. Use \`${attributeName}\` instead of \`${attributeName}="${attributeName}"\`.`, attributeNode.value.location, "error");
     }
 }
-class HTMLBooleanAttributesNoValueRule {
+class HTMLBooleanAttributesNoValueRule extends ParserRule {
     name = "html-boolean-attributes-no-value";
-    check(node) {
-        const visitor = new BooleanAttributesNoValueVisitor(this.name);
+    check(node, context) {
+        const visitor = new BooleanAttributesNoValueVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -602,10 +822,10 @@ class ImgRequireAltVisitor extends BaseRuleVisitor {
         }
     }
 }
-class HTMLImgRequireAltRule {
+class HTMLImgRequireAltRule extends ParserRule {
     name = "html-img-require-alt";
-    check(node) {
-        const visitor = new ImgRequireAltVisitor(this.name);
+    check(node, context) {
+        const visitor = new ImgRequireAltVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -644,10 +864,10 @@ class NoDuplicateAttributesVisitor extends BaseRuleVisitor {
         }
     }
 }
-class HTMLNoDuplicateAttributesRule {
+class HTMLNoDuplicateAttributesRule extends ParserRule {
     name = "html-no-duplicate-attributes";
-    check(node) {
-        const visitor = new NoDuplicateAttributesVisitor(this.name);
+    check(node, context) {
+        const visitor = new NoDuplicateAttributesVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -668,10 +888,10 @@ class NoDuplicateIdsVisitor extends AttributeVisitorMixin {
         this.documentIds.add(id);
     }
 }
-class HTMLNoDuplicateIdsRule {
+class HTMLNoDuplicateIdsRule extends ParserRule {
     name = "html-no-duplicate-ids";
-    check(node) {
-        const visitor = new NoDuplicateIdsVisitor(this.name);
+    check(node, context) {
+        const visitor = new NoDuplicateIdsVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -815,10 +1035,10 @@ class NoEmptyHeadingsVisitor extends BaseRuleVisitor {
         return false;
     }
 }
-class HTMLNoEmptyHeadingsRule {
+class HTMLNoEmptyHeadingsRule extends ParserRule {
     name = "html-no-empty-headings";
-    check(node) {
-        const visitor = new NoEmptyHeadingsVisitor(this.name);
+    check(node, context) {
+        const visitor = new NoEmptyHeadingsVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -859,10 +1079,10 @@ class NestedLinkVisitor extends BaseRuleVisitor {
         super.visitHTMLOpenTagNode(node);
     }
 }
-class HTMLNoNestedLinksRule {
+class HTMLNoNestedLinksRule extends ParserRule {
     name = "html-no-nested-links";
-    check(node) {
-        const visitor = new NestedLinkVisitor(this.name);
+    check(node, context) {
+        const visitor = new NestedLinkVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -906,10 +1126,10 @@ class TagNameLowercaseVisitor extends BaseRuleVisitor {
         }
     }
 }
-class HTMLTagNameLowercaseRule {
+class HTMLTagNameLowercaseRule extends ParserRule {
     name = "html-tag-name-lowercase";
-    check(node) {
-        const visitor = new TagNameLowercaseVisitor(this.name);
+    check(node, context) {
+        const visitor = new TagNameLowercaseVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -962,10 +1182,10 @@ class SVGTagNameCapitalizationVisitor extends BaseRuleVisitor {
         }
     }
 }
-class SVGTagNameCapitalizationRule {
+class SVGTagNameCapitalizationRule extends ParserRule {
     name = "svg-tag-name-capitalization";
-    check(node) {
-        const visitor = new SVGTagNameCapitalizationVisitor(this.name);
+    check(node, context) {
+        const visitor = new SVGTagNameCapitalizationVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
@@ -974,9 +1194,12 @@ class SVGTagNameCapitalizationRule {
 const defaultRules = [
     ERBNoEmptyTagsRule,
     ERBNoOutputControlFlowRule,
+    ERBPreferImageTagHelperRule,
+    ERBRequiresTrailingNewlineRule,
     ERBRequireWhitespaceRule,
     HTMLAnchorRequireHrefRule,
     HTMLAriaAttributeMustBeValid,
+    HTMLAriaLevelMustBeValidRule,
     HTMLAriaRoleHeadingRequiresLevelRule,
     HTMLAriaRoleMustBeValidRule,
     HTMLAttributeDoubleQuotesRule,
@@ -994,12 +1217,15 @@ const defaultRules = [
 
 class Linter {
     rules;
+    herb;
     offenses;
     /**
      * Creates a new Linter instance.
-     * @param rules - Array of rule classes (not instances) to use. If not provided, uses default rules.
+     * @param herb - The Herb backend instance for parsing and lexing
+     * @param rules - Array of rule classes (Parser/AST or Lexer) to use. If not provided, uses default rules.
      */
-    constructor(rules) {
+    constructor(herb, rules) {
+        this.herb = herb;
         this.rules = rules !== undefined ? rules : this.getDefaultRules();
         this.offenses = [];
     }
@@ -1013,11 +1239,39 @@ class Linter {
     getRuleCount() {
         return this.rules.length;
     }
-    lint(document) {
+    /**
+     * Type guard to check if a rule is a LexerRule
+     */
+    isLexerRule(rule) {
+        return rule.constructor.type === "lexer";
+    }
+    /**
+     * Type guard to check if a rule is a SourceRule
+     */
+    isSourceRule(rule) {
+        return rule.constructor.type === "source";
+    }
+    /**
+     * Lint source code using Parser/AST, Lexer, and Source rules.
+     * @param source - The source code to lint
+     * @param context - Optional context for linting (e.g., fileName for distinguishing files vs snippets)
+     */
+    lint(source, context) {
         this.offenses = [];
-        for (const Rule of this.rules) {
-            const rule = new Rule();
-            const ruleOffenses = rule.check(document);
+        const parseResult = this.herb.parse(source);
+        const lexResult = this.herb.lex(source);
+        for (const RuleClass of this.rules) {
+            const rule = new RuleClass();
+            let ruleOffenses;
+            if (this.isLexerRule(rule)) {
+                ruleOffenses = rule.check(lexResult, context);
+            }
+            else if (this.isSourceRule(rule)) {
+                ruleOffenses = rule.check(source, context);
+            }
+            else {
+                ruleOffenses = rule.check(parseResult.value, context);
+            }
             this.offenses.push(...ruleOffenses);
         }
         const errors = this.offenses.filter(offense => offense.severity === "error").length;
@@ -1079,18 +1333,22 @@ class BlockInsideInlineVisitor extends BaseRuleVisitor {
         this.visitBlockElement(node);
     }
 }
-class HTMLNoBlockInsideInlineRule {
+class HTMLNoBlockInsideInlineRule extends ParserRule {
     name = "html-no-block-inside-inline";
-    check(node) {
-        const visitor = new BlockInsideInlineVisitor(this.name);
+    check(node, context) {
+        const visitor = new BlockInsideInlineVisitor(this.name, context);
         visitor.visit(node);
         return visitor.offenses;
     }
 }
 
+exports.DEFAULT_LINT_CONTEXT = DEFAULT_LINT_CONTEXT;
 exports.ERBNoEmptyTagsRule = ERBNoEmptyTagsRule;
 exports.ERBNoOutputControlFlowRule = ERBNoOutputControlFlowRule;
+exports.ERBPreferImageTagHelperRule = ERBPreferImageTagHelperRule;
+exports.ERBRequiresTrailingNewlineRule = ERBRequiresTrailingNewlineRule;
 exports.HTMLAnchorRequireHrefRule = HTMLAnchorRequireHrefRule;
+exports.HTMLAriaLevelMustBeValidRule = HTMLAriaLevelMustBeValidRule;
 exports.HTMLAriaRoleHeadingRequiresLevelRule = HTMLAriaRoleHeadingRequiresLevelRule;
 exports.HTMLAriaRoleMustBeValidRule = HTMLAriaRoleMustBeValidRule;
 exports.HTMLAttributeDoubleQuotesRule = HTMLAttributeDoubleQuotesRule;
@@ -1103,6 +1361,9 @@ exports.HTMLNoDuplicateIdsRule = HTMLNoDuplicateIdsRule;
 exports.HTMLNoEmptyHeadingsRule = HTMLNoEmptyHeadingsRule;
 exports.HTMLNoNestedLinksRule = HTMLNoNestedLinksRule;
 exports.HTMLTagNameLowercaseRule = HTMLTagNameLowercaseRule;
+exports.LexerRule = LexerRule;
 exports.Linter = Linter;
+exports.ParserRule = ParserRule;
 exports.SVGTagNameCapitalizationRule = SVGTagNameCapitalizationRule;
+exports.SourceRule = SourceRule;
 //# sourceMappingURL=index.cjs.map