@herb-tools/linter 0.6.0 → 0.7.0

package/dist/types/src/cli.d.ts

@@ -1,8 +1,23 @@
+import { ArgumentParser, type FormatOption } from "./cli/argument-parser.js";
+import { FileProcessor } from "./cli/file-processor.js";
+import { OutputManager } from "./cli/output-manager.js";
+export * from "./cli/index.js";
 export declare class CLI {
-    private argumentParser;
-    private fileProcessor;
-    private outputManager;
-    private exitWithError;
-    private exitWithInfo;
+    protected argumentParser: ArgumentParser;
+    protected fileProcessor: FileProcessor;
+    protected outputManager: OutputManager;
+    protected projectPath: string;
+    getProjectPath(): string;
+    protected findProjectRoot(startPath: string): string;
+    protected exitWithError(message: string, formatOption: FormatOption, exitCode?: number): void;
+    protected exitWithInfo(message: string, formatOption: FormatOption, exitCode?: number, timingData?: {
+        startTime: number;
+        startDate: Date;
+        showTiming: boolean;
+    }): void;
+    protected determineProjectPath(pattern: string | undefined): void;
+    protected adjustPattern(pattern: string | undefined): string;
+    protected beforeProcess(): Promise<void>;
+    protected afterProcess(_results: any, _outputOptions: any): Promise<void>;
     run(): Promise<void>;
 }

package/dist/types/src/linter.d.ts

@@ -1,9 +1,9 @@
-import type { RuleClass, LintResult, LintContext } from "./types.js";
+import type { RuleClass, Rule, LexerRule, SourceRule, LintResult, LintOffense, LintContext } from "./types.js";
 import type { HerbBackend } from "@herb-tools/core";
 export declare class Linter {
-    private rules;
-    private herb;
-    private offenses;
+    protected rules: RuleClass[];
+    protected herb: HerbBackend;
+    protected offenses: LintOffense[];
     /**
      * Creates a new Linter instance.
      * @param herb - The Herb backend instance for parsing and lexing
@@ -14,16 +14,16 @@ export declare class Linter {
      * Returns the default set of rule classes used by the linter.
      * @returns Array of rule classes
      */
-    private getDefaultRules;
+    protected getDefaultRules(): RuleClass[];
     getRuleCount(): number;
     /**
      * Type guard to check if a rule is a LexerRule
      */
-    private isLexerRule;
+    protected isLexerRule(rule: Rule): rule is LexerRule;
     /**
      * Type guard to check if a rule is a SourceRule
      */
-    private isSourceRule;
+    protected isSourceRule(rule: Rule): rule is SourceRule;
     /**
      * Lint source code using Parser/AST, Lexer, and Source rules.
      * @param source - The source code to lint

package/dist/types/src/rules/html-no-empty-attributes.d.ts

@@ -0,0 +1,7 @@
+import { ParserRule } from "../types.js";
+import type { LintOffense, LintContext } from "../types.js";
+import type { ParseResult } from "@herb-tools/core";
+export declare class HTMLNoEmptyAttributesRule extends ParserRule {
+    name: string;
+    check(result: ParseResult, context?: Partial<LintContext>): LintOffense[];
+}

package/dist/types/src/rules/html-no-underscores-in-attribute-names.d.ts

@@ -0,0 +1,7 @@
+import { ParserRule } from "../types.js";
+import type { LintContext, LintOffense } from "../types.js";
+import type { ParseResult } from "@herb-tools/core";
+export declare class HTMLNoUnderscoresInAttributeNamesRule extends ParserRule {
+    name: string;
+    check(result: ParseResult, context?: Partial<LintContext>): LintOffense[];
+}

package/dist/types/src/rules/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./rule-utils.js";
 export * from "./erb-no-empty-tags.js";
 export * from "./erb-no-output-control-flow.js";
 export * from "./erb-no-silent-tag-in-attribute-name.js";
@@ -20,6 +21,7 @@ export * from "./html-no-aria-hidden-on-focusable.js";
 export * from "./html-no-block-inside-inline.js";
 export * from "./html-no-duplicate-attributes.js";
 export * from "./html-no-duplicate-ids.js";
+export * from "./html-no-empty-attributes.js";
 export * from "./html-no-empty-headings.js";
 export * from "./html-no-nested-links.js";
 export * from "./html-no-positive-tab-index.js";
@@ -27,3 +29,4 @@ export * from "./html-no-self-closing.js";
 export * from "./html-no-title-attribute.js";
 export * from "./html-tag-name-lowercase.js";
 export * from "./svg-tag-name-capitalization.js";
+export * from "./html-no-underscores-in-attribute-names.js";

package/dist/types/src/rules/rule-utils.d.ts

@@ -1,6 +1,11 @@
 import { Visitor, Location } from "@herb-tools/core";
 import type { HTMLAttributeNode, HTMLAttributeValueNode, HTMLOpenTagNode, LexResult, Token, Node } from "@herb-tools/core";
+import type * as Nodes from "@herb-tools/core";
 import type { LintOffense, LintSeverity, LintContext } from "../types.js";
+export declare enum ControlFlowType {
+    CONDITIONAL = 0,
+    LOOP = 1
+}
 /**
  * Base visitor class that provides common functionality for rule visitors
  */
@@ -18,6 +23,40 @@ export declare abstract class BaseRuleVisitor extends Visitor {
      */
     protected addOffense(message: string, location: Location, severity?: LintSeverity): void;
 }
+/**
+ * Mixin that adds control flow tracking capabilities to rule visitors
+ * This allows rules to track state across different control flow structures
+ * like if/else branches, loops, etc.
+ *
+ * @template TControlFlowState - Type for state passed between onEnterControlFlow and onExitControlFlow
+ * @template TBranchState - Type for state passed between onEnterBranch and onExitBranch
+ */
+export declare abstract class ControlFlowTrackingVisitor<TControlFlowState = any, TBranchState = any> extends BaseRuleVisitor {
+    protected isInControlFlow: boolean;
+    protected currentControlFlowType: ControlFlowType | null;
+    /**
+     * Handle visiting a control flow node with proper scope management
+     */
+    protected handleControlFlowNode(node: Node, controlFlowType: ControlFlowType, visitChildren: () => void): void;
+    /**
+     * Handle visiting a branch node (like else, when) with proper scope management
+     */
+    protected startNewBranch(visitChildren: () => void): void;
+    visitERBIfNode(node: Nodes.ERBIfNode): void;
+    visitERBUnlessNode(node: Nodes.ERBUnlessNode): void;
+    visitERBCaseNode(node: Nodes.ERBCaseNode): void;
+    visitERBCaseMatchNode(node: Nodes.ERBCaseMatchNode): void;
+    visitERBWhileNode(node: Nodes.ERBWhileNode): void;
+    visitERBForNode(node: Nodes.ERBForNode): void;
+    visitERBUntilNode(node: Nodes.ERBUntilNode): void;
+    visitERBBlockNode(node: Nodes.ERBBlockNode): void;
+    visitERBElseNode(node: Nodes.ERBElseNode): void;
+    visitERBWhenNode(node: Nodes.ERBWhenNode): void;
+    protected abstract onEnterControlFlow(controlFlowType: ControlFlowType, wasAlreadyInControlFlow: boolean): TControlFlowState;
+    protected abstract onExitControlFlow(controlFlowType: ControlFlowType, wasAlreadyInControlFlow: boolean, stateToRestore: TControlFlowState): void;
+    protected abstract onEnterBranch(): TBranchState;
+    protected abstract onExitBranch(stateToRestore: TBranchState): void;
+}
 /**
  * Gets attributes from an HTMLOpenTagNode
  */
@@ -30,7 +69,7 @@ export declare function getTagName(node: HTMLOpenTagNode): string | null;
  * Gets the attribute name from an HTMLAttributeNode (lowercased)
  * Returns null if the attribute name contains dynamic content (ERB)
  */
-export declare function getAttributeName(attributeNode: HTMLAttributeNode): string | null;
+export declare function getAttributeName(attributeNode: HTMLAttributeNode, lowercase?: boolean): string | null;
 /**
  * Checks if an attribute has a dynamic (ERB-containing) name
  */
@@ -114,12 +153,14 @@ export interface StaticAttributeStaticValueParams {
     attributeName: string;
     attributeValue: string;
     attributeNode: HTMLAttributeNode;
+    originalAttributeName: string;
     parentNode: HTMLOpenTagNode;
 }
 export interface StaticAttributeDynamicValueParams {
     attributeName: string;
     valueNodes: Node[];
     attributeNode: HTMLAttributeNode;
+    originalAttributeName: string;
     parentNode: HTMLOpenTagNode;
     combinedValue?: string | null;
 }
@@ -176,19 +217,19 @@ export declare abstract class AttributeVisitorMixin extends BaseRuleVisitor {
     /**
      * Static attribute name with static value: class="container"
      */
-    protected checkStaticAttributeStaticValue(params: StaticAttributeStaticValueParams): void;
+    protected checkStaticAttributeStaticValue(_params: StaticAttributeStaticValueParams): void;
     /**
      * Static attribute name with dynamic value: class="<%= css_class %>"
      */
-    protected checkStaticAttributeDynamicValue(params: StaticAttributeDynamicValueParams): void;
+    protected checkStaticAttributeDynamicValue(_params: StaticAttributeDynamicValueParams): void;
     /**
      * Dynamic attribute name with static value: data-<%= key %>="foo"
      */
-    protected checkDynamicAttributeStaticValue(params: DynamicAttributeStaticValueParams): void;
+    protected checkDynamicAttributeStaticValue(_params: DynamicAttributeStaticValueParams): void;
     /**
      * Dynamic attribute name with dynamic value: data-<%= key %>="<%= value %>"
      */
-    protected checkDynamicAttributeDynamicValue(params: DynamicAttributeDynamicValueParams): void;
+    protected checkDynamicAttributeDynamicValue(_params: DynamicAttributeDynamicValueParams): void;
 }
 /**
  * Checks if an attribute value is quoted

package/docs/rules/README.md

@@ -28,11 +28,13 @@ This page contains documentation for all Herb Linter rules.
 - [`html-no-block-inside-inline`](./html-no-block-inside-inline.md) - Prevents block-level elements inside inline elements
 - [`html-no-duplicate-attributes`](./html-no-duplicate-attributes.md) - Prevents duplicate attributes on HTML elements
 - [`html-no-duplicate-ids`](./html-no-duplicate-ids.md) - Prevents duplicate IDs within a document
+- [`html-no-empty-attributes`](./html-no-empty-attributes.md) - Attributes must not have empty values
 - [`html-no-nested-links`](./html-no-nested-links.md) - Prevents nested anchor tags
 - [`html-no-positive-tab-index`](./html-no-positive-tab-index.md) - Avoid positive `tabindex` values
 - [`html-no-self-closing`](./html-no-self-closing.md.md) - Disallow self closing tags
 - [`html-no-title-attribute`](./html-no-title-attribute.md) - Avoid using the `title` attribute
 - [`html-tag-name-lowercase`](./html-tag-name-lowercase.md) - Enforces lowercase tag names in HTML
+- [`html-no-underscores-in-attribute-names`](./html-no-underscores-in-attribute-names.md) - Disallow underscores in HTML attribute names
 - [`parser-no-errors`](./parser-no-errors.md) - Disallow parser errors in HTML+ERB documents
 - [`svg-tag-name-capitalization`](./svg-tag-name-capitalization.md) - Enforces proper camelCase capitalization for SVG elements
 

package/docs/rules/html-img-require-alt.md

@@ -33,8 +33,6 @@ Omitting the `alt` attribute entirely leads to poor accessibility and can negati
 
 <img src="/avatar.jpg" alt> <!-- TODO -->
 
-<img src="/divider.png" alt=> <!-- TODO -->
-
 <%= image_tag image_path("logo.png") %> <!-- TODO -->
 ```
 

package/docs/rules/html-no-empty-attributes.md

@@ -0,0 +1,77 @@
+# Linter Rule: Attributes must not have empty values
+
+**Rule:** `html-no-empty-attributes`
+
+## Description
+
+Warn when certain restricted attributes are present but have an empty string as their value. These attributes are required to have meaningful values to function properly, and leaving them empty is typically either a mistake or unnecessary.
+
+In most cases, if the value is not available, it's better to omit the attribute entirely.
+
+### Restricted attributes
+
+- `id`
+- `class`
+- `name`
+- `for`
+- `src`
+- `href`
+- `title`
+- `data`
+- `role`
+- `data-*`
+- `aria-*`
+
+## Rationale
+
+Many HTML attributes are only useful when they carry a value. Leaving these attributes empty can:
+
+- Produce confusing or misleading markup (e.g., `id=""`, `class=""`)
+- Create inaccessible or invalid HTML
+- Interfere with CSS or JS selectors expecting meaningful values
+- Indicate unused or unfinished logic in ERB
+
+This rule helps ensure that required attributes are only added when they are populated.
+
+## Examples
+
+### ✅ Good
+
+```erb
+<div id="header"></div>
+<img src="/logo.png" alt="Company logo">
+<input type="text" name="email">
+
+<!-- Dynamic attributes with meaningful values -->
+<div data-<%= key %>="<%= value %>" aria-<%= prop %>="<%= description %>">
+  Dynamic content
+</div>
+
+<!-- if no class should be set, omit it completely -->
+<div>Plain div</div>
+```
+
+### 🚫 Bad
+
+```erb
+<div id=""></div>
+<img src="">
+<input name="">
+
+<div data-config="">Content</div>
+<button aria-label="">×</button>
+
+<div class="">Plain div</div>
+
+<!-- Dynamic attribute names with empty static values -->
+<div data-<%= key %>="" aria-<%= prop %>="   ">
+  Problematic dynamic attributes
+</div>
+```
+
+## References
+
+- [HTML Living Standard - Global attributes](https://html.spec.whatwg.org/multipage/dom.html#global-attributes)
+- [WCAG 2.2 - Text Alternatives](https://www.w3.org/WAI/WCAG22/Understanding/text-alternatives.html)
+- [MDN - HTML attribute reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes)
+- [ARIA in HTML](https://www.w3.org/TR/html-aria/)

package/docs/rules/html-no-underscores-in-attribute-names.md

@@ -0,0 +1,45 @@
+# Linter Rule: No underscores on attribute names
+
+**Rule:** `html-no-underscores-in-attribute-names`
+
+## Description
+
+---
+
+Warn when an HTML attribute name contains an underscore (`_`). According to the HTML specification, attribute names should use only lowercase letters, digits, hyphens (`-`), and colons (`:`) in specific namespaces (e.g., `xlink:href` in SVG). Underscores are not valid in standard HTML attribute names and may lead to unpredictable behavior or be ignored by browsers entirely.
+
+## Rationale
+
+---
+
+Underscores in attribute names violate the HTML specification and are not supported in standard markup. Their use is almost always accidental (e.g., mistyping `data-attr_name` instead of `data-attr-name`) or stems from inconsistent naming conventions across backend or templating layers.
+
+## Examples
+
+---
+
+✅ Good
+
+```html
+<div data-user-id="123"></div>
+
+<img aria-label="Close">
+
+<div data-<%= key %>-attribute="value"></div>
+```
+
+🚫 Bad
+
+```html
+<div data_user_id="123"></div>
+
+<img aria_label="Close">
+
+<div data-<%= key %>_attribute="value"></div>
+```
+
+## References
+
+---
+
+\-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herb-tools/linter",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "HTML+ERB linter for validating HTML structure and enforcing best practices",
   "license": "MIT",
   "homepage": "https://herb-tools.dev",
@@ -21,6 +21,7 @@
     "build": "yarn clean && tsc -b && rollup -c",
     "watch": "tsc -b -w",
     "test": "vitest run",
+    "test:watch": "vitest --watch",
     "prepublishOnly": "yarn clean && yarn build && yarn test"
   },
   "exports": {
@@ -30,12 +31,18 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs",
       "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/types/src/cli.d.ts",
+      "require": "./dist/src/cli.js",
+      "default": "./dist/src/cli.js"
     }
   },
   "dependencies": {
-    "@herb-tools/core": "0.6.0",
-    "@herb-tools/highlighter": "0.6.0",
-    "@herb-tools/node-wasm": "0.6.0",
+    "@herb-tools/core": "0.7.0",
+    "@herb-tools/highlighter": "0.7.0",
+    "@herb-tools/node-wasm": "0.7.0",
+    "@herb-tools/printer": "0.7.0",
     "glob": "^11.0.3"
   },
   "files": [

package/src/cli/argument-parser.ts

@@ -11,7 +11,7 @@ import type { ThemeInput } from "@herb-tools/highlighter"
 
 import { name, version } from "../../package.json"
 
-export type FormatOption = "simple" | "detailed" | "json" | "github"
+export type FormatOption = "simple" | "detailed" | "json"
 
 export interface ParsedArguments {
   pattern: string
@@ -20,6 +20,7 @@ export interface ParsedArguments {
   theme: ThemeInput
   wrapLines: boolean
   truncateLines: boolean
+  useGitHubActions: boolean
 }
 
 export class ArgumentParser {
@@ -34,10 +35,11 @@ export class ArgumentParser {
     Options:
       -h, --help       show help
       -v, --version    show version
-      --format         output format (simple|detailed|json|github) [default: detailed]
+      --format         output format (simple|detailed|json) [default: detailed]
       --simple         use simple output format (shortcut for --format simple)
       --json           use JSON output format (shortcut for --format json)
-      --github         use GitHub Actions output format (shortcut for --format github)
+      --github         enable GitHub Actions annotations (combines with --format)
+      --no-github      disable GitHub Actions annotations (even in GitHub Actions environment)
       --theme          syntax highlighting theme (${THEME_NAMES.join("|")}) or path to custom theme file [default: ${DEFAULT_THEME}]
       --no-color       disable colored output
       --no-timing      hide timing information
@@ -55,6 +57,7 @@ export class ArgumentParser {
         simple: { type: "boolean" },
         json: { type: "boolean" },
         github: { type: "boolean" },
+        "no-github": { type: "boolean" },
         theme: { type: "string" },
         "no-color": { type: "boolean" },
         "no-timing": { type: "boolean" },
@@ -75,8 +78,10 @@ export class ArgumentParser {
       process.exit(0)
     }
 
+    const isGitHubActions = process.env.GITHUB_ACTIONS === "true"
+
     let formatOption: FormatOption = "detailed"
-    if (values.format && (values.format === "detailed" || values.format === "simple" || values.format === "json" || values.format === "github")) {
+    if (values.format && (values.format === "detailed" || values.format === "simple" || values.format === "json")) {
       formatOption = values.format
     }
 
@@ -88,8 +93,11 @@ export class ArgumentParser {
       formatOption = "json"
     }
 
-    if (values.github) {
-      formatOption = "github"
+    const useGitHubActions = (values.github || isGitHubActions) && !values["no-github"]
+
+    if (useGitHubActions && formatOption === "json") {
+      console.error("Error: --github cannot be used with --json format. JSON format is already structured for programmatic consumption.")
+      process.exit(1)
     }
 
     if (values["no-color"]) {
@@ -114,7 +122,7 @@ export class ArgumentParser {
     const theme = values.theme || DEFAULT_THEME
     const pattern = this.getFilePattern(positionals)
 
-    return { pattern, formatOption, showTiming, theme, wrapLines, truncateLines }
+    return { pattern, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions }
   }
 
   private getFilePattern(positionals: string[]): string {

package/src/cli/file-processor.ts

@@ -12,6 +12,11 @@ export interface ProcessedFile {
   content: string
 }
 
+export interface ProcessingContext {
+  projectPath?: string
+  pattern?: string
+}
+
 export interface ProcessingResult {
   totalErrors: number
   totalWarnings: number
@@ -19,12 +24,13 @@ export interface ProcessingResult {
   ruleCount: number
   allOffenses: ProcessedFile[]
   ruleOffenses: Map<string, { count: number, files: Set<string> }>
+  context?: ProcessingContext
 }
 
 export class FileProcessor {
   private linter: Linter | null = null
 
-  async processFiles(files: string[], formatOption: FormatOption = 'detailed'): Promise<ProcessingResult> {
+  async processFiles(files: string[], formatOption: FormatOption = 'detailed', context?: ProcessingContext): Promise<ProcessingResult> {
     let totalErrors = 0
     let totalWarnings = 0
     let filesWithOffenses = 0
@@ -33,13 +39,12 @@ export class FileProcessor {
     const ruleOffenses = new Map<string, { count: number, files: Set<string> }>()
 
     for (const filename of files) {
-      const filePath = resolve(filename)
+      const filePath = context?.projectPath ? resolve(context.projectPath, filename) : resolve(filename)
       const content = readFileSync(filePath, "utf-8")
-
       const parseResult = Herb.parse(content)
 
       if (parseResult.errors.length > 0) {
-        if (formatOption !== 'json' && formatOption !== 'github') {
+        if (formatOption !== 'json') {
           console.error(`${colorize(filename, "cyan")} - ${colorize("Parse errors:", "brightRed")}`)
 
           for (const error of parseResult.errors) {
@@ -47,7 +52,6 @@ export class FileProcessor {
           }
         }
 
-        // Add parse errors to offenses for JSON output
         for (const error of parseResult.errors) {
           allOffenses.push({ filename, offense: error, content })
         }
@@ -68,7 +72,7 @@ export class FileProcessor {
       }
 
       if (lintResult.offenses.length === 0) {
-        if (files.length === 1 && formatOption !== 'json' && formatOption !== 'github') {
+        if (files.length === 1 && formatOption !== 'json') {
           console.log(`${colorize("✓", "brightGreen")} ${colorize(filename, "cyan")} - ${colorize("No issues found", "green")}`)
         }
       } else {
@@ -87,6 +91,6 @@ export class FileProcessor {
       }
     }
 
-    return { totalErrors, totalWarnings, filesWithOffenses, ruleCount, allOffenses, ruleOffenses }
+    return { totalErrors, totalWarnings, filesWithOffenses, ruleCount, allOffenses, ruleOffenses, context }
   }
 }

package/src/cli/formatters/detailed-formatter.ts

@@ -1,6 +1,7 @@
 import { colorize, Highlighter, type ThemeInput, DEFAULT_THEME } from "@herb-tools/highlighter"
 
 import { BaseFormatter } from "./base-formatter.js"
+import { LineWrapper } from "@herb-tools/highlighter"
 
 import type { Diagnostic } from "@herb-tools/core"
 import type { ProcessedFile } from "../file-processor.js"
@@ -27,13 +28,12 @@ export class DetailedFormatter extends BaseFormatter {
     }
 
     if (isSingleFile) {
-      // For single file, use inline diagnostics with syntax highlighting
       const { filename, content } = allOffenses[0]
       const diagnostics = allOffenses.map(item => item.offense)
 
       const highlighted = this.highlighter.highlight(filename, content, {
         diagnostics: diagnostics,
-        splitDiagnostics: true, // Use split mode to show each diagnostic separately
+        splitDiagnostics: true,
         contextLines: 2,
         wrapLines: this.wrapLines,
         truncateLines: this.truncateLines
@@ -41,19 +41,18 @@ export class DetailedFormatter extends BaseFormatter {
 
       console.log(`\n${highlighted}`)
     } else {
-      // For multiple files, show individual diagnostics with syntax highlighting
       const totalMessageCount = allOffenses.length
 
       for (let i = 0; i < allOffenses.length; i++) {
         const { filename, offense, content } = allOffenses[i]
-        const formatted = this.highlighter.highlightDiagnostic(filename, offense, content, { 
-          contextLines: 2, 
+        const formatted = this.highlighter.highlightDiagnostic(filename, offense, content, {
+          contextLines: 2,
           wrapLines: this.wrapLines,
           truncateLines: this.truncateLines
         })
         console.log(`\n${formatted}`)
 
-        const width = process.stdout.columns || 80
+        const width = LineWrapper.getTerminalWidth()
         const progressText = `[${i + 1}/${totalMessageCount}]`
         const rightPadding = 16
         const separatorLength = Math.max(0, width - progressText.length - 1 - rightPadding)
@@ -68,7 +67,6 @@ export class DetailedFormatter extends BaseFormatter {
   }
 
   formatFile(_filename: string, _offenses: Diagnostic[]): void {
-    // Not used in detailed formatter
     throw new Error("formatFile is not implemented for DetailedFormatter")
   }
 }