@herb-tools/linter 0.8.7 → 0.8.8

package/dist/types/src/rules/index.d.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";
 export * from "./erb-no-case-node-children.js";
@@ -11,6 +13,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";
 export * from "./herb-disable-comment-no-duplicate-rules.js";

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

@@ -0,0 +1,15 @@
+/**
+ * Checks if parentheses in a string are balanced
+ * Returns false if there are more closing parens than opening at any point
+ */
+export declare function hasBalancedParentheses(content: string): boolean;
+/**
+ * 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 declare function splitByTopLevelComma(str: string): string[];

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

@@ -68,6 +68,8 @@ export declare abstract class ParserRule<TAutofixContext extends BaseAutofixCont
     static type: "parser";
     /** Indicates whether this rule supports autofix. Defaults to false. */
     static autocorrectable: boolean;
+    /** Indicates whether this rule supports unsafe autofix (requires --fix-unsafely). Defaults to false. */
+    static unsafeAutocorrectable: boolean;
     abstract name: string;
     get defaultConfig(): FullRuleConfig;
     abstract check(result: ParseResult, context?: Partial<LintContext>): UnboundLintOffense<TAutofixContext>[];
@@ -96,6 +98,8 @@ export declare abstract class LexerRule<TAutofixContext extends BaseAutofixConte
     static type: "lexer";
     /** Indicates whether this rule supports autofix. Defaults to false. */
     static autocorrectable: boolean;
+    /** Indicates whether this rule supports unsafe autofix (requires --fix-unsafely). Defaults to false. */
+    static unsafeAutocorrectable: boolean;
     abstract name: string;
     get defaultConfig(): FullRuleConfig;
     abstract check(lexResult: LexResult, context?: Partial<LintContext>): UnboundLintOffense<TAutofixContext>[];
@@ -139,6 +143,8 @@ export declare abstract class SourceRule<TAutofixContext extends BaseAutofixCont
     static type: "source";
     /** Indicates whether this rule supports autofix. Defaults to false. */
     static autocorrectable: boolean;
+    /** Indicates whether this rule supports unsafe autofix (requires --fix-unsafely). Defaults to false. */
+    static unsafeAutocorrectable: boolean;
     abstract name: string;
     get defaultConfig(): FullRuleConfig;
     abstract check(source: string, context?: Partial<LintContext>): UnboundLintOffense<TAutofixContext>[];

package/dist/types/types.d.ts

@@ -68,6 +68,8 @@ export declare abstract class ParserRule<TAutofixContext extends BaseAutofixCont
     static type: "parser";
     /** Indicates whether this rule supports autofix. Defaults to false. */
     static autocorrectable: boolean;
+    /** Indicates whether this rule supports unsafe autofix (requires --fix-unsafely). Defaults to false. */
+    static unsafeAutocorrectable: boolean;
     abstract name: string;
     get defaultConfig(): FullRuleConfig;
     abstract check(result: ParseResult, context?: Partial<LintContext>): UnboundLintOffense<TAutofixContext>[];
@@ -96,6 +98,8 @@ export declare abstract class LexerRule<TAutofixContext extends BaseAutofixConte
     static type: "lexer";
     /** Indicates whether this rule supports autofix. Defaults to false. */
     static autocorrectable: boolean;
+    /** Indicates whether this rule supports unsafe autofix (requires --fix-unsafely). Defaults to false. */
+    static unsafeAutocorrectable: boolean;
     abstract name: string;
     get defaultConfig(): FullRuleConfig;
     abstract check(lexResult: LexResult, context?: Partial<LintContext>): UnboundLintOffense<TAutofixContext>[];
@@ -139,6 +143,8 @@ export declare abstract class SourceRule<TAutofixContext extends BaseAutofixCont
     static type: "source";
     /** Indicates whether this rule supports autofix. Defaults to false. */
     static autocorrectable: boolean;
+    /** Indicates whether this rule supports unsafe autofix (requires --fix-unsafely). Defaults to false. */
+    static unsafeAutocorrectable: boolean;
     abstract name: string;
     get defaultConfig(): FullRuleConfig;
     abstract check(source: string, context?: Partial<LintContext>): UnboundLintOffense<TAutofixContext>[];

package/docs/rules/README.md

@@ -15,6 +15,7 @@ This page contains documentation for all Herb Linter rules.
 - [`erb-require-whitespace-inside-tags`](./erb-require-whitespace-inside-tags.md) - Requires whitespace around ERB tags
 - [`erb-require-trailing-newline`](./erb-require-trailing-newline.md) - Enforces that all HTML+ERB template files end with exactly one trailing newline character.
 - [`erb-right-trim`](./erb-right-trim.md) - Enforce consistent right-trimming syntax.
+- [`erb-strict-locals-comment-syntax`](./erb-strict-locals-comment-syntax.md) - Enforce strict locals comment syntax.
 - [`herb-disable-comment-malformed`](./herb-disable-comment-malformed.md) - Detect malformed `herb:disable` comments.
 - [`herb-disable-comment-missing-rules`](./herb-disable-comment-missing-rules.md) - Require rule names in `herb:disable` comments.
 - [`herb-disable-comment-no-duplicate-rules`](./herb-disable-comment-no-duplicate-rules.md) - Disallow duplicate rule names in `herb:disable` comments.

package/docs/rules/erb-strict-locals-comment-syntax.md

@@ -0,0 +1,153 @@
+# Linter Rule: Enforce strict locals comment syntax
+
+**Rule:** `erb-strict-locals-comment-syntax`
+
+## Description
+
+Ensures that strict locals comments use the exact `locals: ( ... )` syntax so they are properly recognized by Rails and tooling. Also validates that only keyword arguments are used (no positional, block, or splat arguments).
+
+## Rationale
+
+Strict locals comments declare which locals are expected in a template. Misspellings or malformed syntax silently disable the declaration, leading to confusing runtime errors when required locals are missing.
+
+Additionally, Rails only supports keyword arguments in strict locals declarations. Positional, block, and splat arguments will raise an `ActionView::Error` at render-time.
+
+This rule catches invalid comment forms and argument types early during development.
+
+## Examples
+
+### ✅ Good
+
+Required keyword argument:
+
+```erb
+<%# locals: (user:) %>
+```
+
+Keyword argument with default value:
+
+```erb
+<%# locals: (user:, admin: false) %>
+```
+
+Complex default values:
+
+```erb
+<%# locals: (items: [], config: {}) %>
+```
+
+No locals (empty):
+
+```erb
+<%# locals: () %>
+```
+
+Double-splat for optional keyword arguments:
+
+```erb
+<%# locals: (message: "Hello", **attributes) %>
+```
+
+### 🚫 Bad
+
+#### Wrong comment syntax
+
+Missing colon after `locals`:
+
+```erb
+<%# locals() %>
+```
+
+Singular `local` instead of `locals`:
+
+```erb
+<%# local: (user:) %>
+```
+
+Missing colon before parentheses:
+
+```erb
+<%# locals (user:) %>
+```
+
+Missing parentheses around parameters:
+
+```erb
+<%# locals: user %>
+```
+
+Empty `locals:` without parentheses:
+
+```erb
+<%# locals: %>
+```
+
+Unbalanced parentheses:
+
+```erb
+<%# locals: (user: %>
+```
+
+#### Wrong tag type (must use ERB comment tag)
+
+Ruby comment in execution tag:
+
+```erb
+<% # locals: (user:) %>
+```
+
+#### Unsupported argument types
+
+Positional argument (use `user:` instead):
+
+```erb
+<%# locals: (user) %>
+```
+
+Block argument:
+
+```erb
+<%# locals: (&block) %>
+```
+
+Single splat argument:
+
+```erb
+<%# locals: (*args) %>
+```
+
+Note: Double-splat (`**attributes`) IS supported for optional keyword arguments.
+
+#### Invalid Ruby syntax
+
+Trailing comma:
+
+```erb
+<%# locals: (user:,) %>
+```
+
+Leading comma:
+
+```erb
+<%# locals: (, user:) %>
+```
+
+Double comma:
+
+```erb
+<%# locals: (user:,, admin:) %>
+```
+
+#### Duplicate declarations
+
+Only one `locals:` comment is allowed per partial:
+
+```erb
+<%# locals: (user:) %>
+<p>Content</p>
+<%# locals: (admin:) %>
+```
+
+## References
+
+- [Action View - Strict Locals](https://guides.rubyonrails.org/action_view_overview.html#strict-locals)

package/docs/rules/erb-strict-locals-required.md

@@ -0,0 +1,107 @@
+# Linter Rule: Require strict locals in Rails partials
+
+**Rule:** `erb-strict-locals-required`
+
+**Default:** Disabled (opt-in)
+
+## Description
+
+Requires that every Rails partial template includes a strict locals declaration comment using the supported syntax:
+
+```erb
+<%# locals: () %>
+```
+
+A partial is any template whose filename begins with an underscore (e.g. `_card.html.erb`).
+
+## Rationale
+
+Partials often rely on implicit locals, which makes them harder to understand, refactor, and lint. Requiring strict locals:
+
+- Documents the partial's public API at the top of the file
+- Improves readability and onboarding
+- Enables better static analysis (unknown locals, missing locals, unused locals)
+- Reduces runtime surprises when locals are renamed or removed
+
+This rule encourages partials to be explicit about what they expect. Partials that intentionally accept no locals should still declare an explicit empty signature.
+
+## Configuration
+
+This rule is disabled by default. To enable it, add to your [`.herb.yml`](/configuration):
+
+```yaml [.herb.yml]
+linter:
+  rules:
+    erb-strict-locals-required:
+      enabled: true
+```
+
+## Autofix
+
+This rule supports **unsafe autofix** via `--fix-unsafely`. When applied, it inserts an empty strict locals declaration at the top of the file:
+
+```erb
+<%# locals: () %>
+```
+
+This is considered "unsafe" because:
+- It changes the partial's behavior (strict mode will now error on undeclared locals)
+- You may need to manually add the actual local variables your partial uses
+
+To apply the autofix:
+
+```bash
+herb-lint --fix-unsafely _partial.html.erb
+```
+
+After the autofix runs, review the file and update the locals declaration to include any variables your partial expects.
+
+## Examples
+
+### ✅ Good
+
+Partial with required keyword argument:
+
+```erb
+<%# locals: (user:) %>
+
+<div class="user-card">
+  <%= user.name %>
+</div>
+```
+
+Partial with keyword argument and default:
+
+```erb [app/views/users/_card.html.erb]
+<%# locals: (user:, admin: false) %>
+
+<div class="user-card">
+  <%= user.name %>
+
+  <% if admin %>
+    <span class="badge">Admin</span>
+  <% end %>
+</div>
+```
+
+Partial with no locals (empty declaration):
+
+```erb [app/views/pages/_content.html.erb]
+<%# locals: () %>
+
+<p>Static content only</p>
+```
+
+### 🚫 Bad
+
+Partial without strict locals declaration:
+
+```erb [app/views/users/_card.html.erb]
+<div class="user-card">
+  <%= user.name %>
+</div>
+```
+
+## References
+
+- [Action View - Strict Locals](https://guides.rubyonrails.org/action_view_overview.html#strict-locals)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@herb-tools/linter",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "HTML+ERB linter for validating HTML structure and enforcing best practices",
   "license": "MIT",
   "homepage": "https://herb-tools.dev",
@@ -45,12 +45,12 @@
     }
   },
   "dependencies": {
-    "@herb-tools/config": "0.8.7",
-    "@herb-tools/core": "0.8.7",
-    "@herb-tools/highlighter": "0.8.7",
-    "@herb-tools/node-wasm": "0.8.7",
-    "@herb-tools/printer": "0.8.7",
-    "@herb-tools/rewriter": "0.8.7",
+    "@herb-tools/config": "0.8.8",
+    "@herb-tools/core": "0.8.8",
+    "@herb-tools/highlighter": "0.8.8",
+    "@herb-tools/node-wasm": "0.8.8",
+    "@herb-tools/printer": "0.8.8",
+    "@herb-tools/rewriter": "0.8.8",
     "picomatch": "^4.0.2",
     "tinyglobby": "^0.2.15"
   },

package/src/cli/argument-parser.ts

@@ -21,6 +21,7 @@ export interface ParsedArguments {
   truncateLines: boolean
   useGitHubActions: boolean
   fix: boolean
+  fixUnsafe: boolean
   ignoreDisableComments: boolean
   force: boolean
   init: boolean
@@ -43,6 +44,7 @@ export class ArgumentParser {
       -c, --config-file <path>      explicitly specify path to .herb.yml config file
       --force                       force linting even if disabled in .herb.yml
       --fix                         automatically fix auto-correctable offenses
+      --fix-unsafely                also apply unsafe auto-fixes (implies --fix)
       --ignore-disable-comments     report offenses even when suppressed with <%# herb:disable %> comments
       --fail-level <severity>       exit with error code when diagnostics of this severity or higher are present (error|warning|info|hint) [default: error]
       --format                      output format (simple|detailed|json) [default: detailed]
@@ -68,6 +70,7 @@ export class ArgumentParser {
         "config-file": { type: "string", short: "c" },
         force: { type: "boolean" },
         fix: { type: "boolean" },
+        "fix-unsafely": { type: "boolean" },
         "ignore-disable-comments": { type: "boolean" },
         "fail-level": { type: "string" },
         format: { type: "string" },
@@ -141,7 +144,8 @@ export class ArgumentParser {
 
     const theme = values.theme || DEFAULT_THEME
     const patterns = this.getFilePatterns(positionals)
-    const fix = values.fix || false
+    const fixUnsafe = values["fix-unsafely"] || false
+    const fix = values.fix || fixUnsafe  // --fix-unsafely implies --fix
     const force = !!values.force
     const ignoreDisableComments = values["ignore-disable-comments"] || false
     const configFile = values["config-file"]
@@ -159,7 +163,7 @@ export class ArgumentParser {
       }
     }
 
-    return { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, ignoreDisableComments, force, init, loadCustomRules, failLevel }
+    return { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, fixUnsafe, ignoreDisableComments, force, init, loadCustomRules, failLevel }
   }
 
   private getFilePatterns(positionals: string[]): string[] {

package/src/cli/file-processor.ts

@@ -22,6 +22,7 @@ export interface ProcessingContext {
   projectPath?: string
   pattern?: string
   fix?: boolean
+  fixUnsafe?: boolean
   ignoreDisableComments?: boolean
   linterConfig?: HerbConfigOptions['linter']
   config?: Config
@@ -138,7 +139,7 @@ export class FileProcessor {
         const autofixResult = this.linter.autofix(content, {
           fileName: filename,
           ignoreDisableComments: context?.ignoreDisableComments
-        })
+        }, undefined, { includeUnsafe: context?.fixUnsafe })
 
         if (autofixResult.fixed.length > 0) {
           writeFileSync(filePath, autofixResult.source, "utf-8")

package/src/cli.ts

@@ -66,9 +66,9 @@ export class CLI {
     }
   }
 
-  protected adjustPattern(pattern: string | undefined, configGlobPattern: string): string {
+  protected adjustPattern(pattern: string | undefined, configGlobPatterns: string[]): string {
     if (!pattern) {
-      return configGlobPattern
+      return configGlobPatterns.length === 1 ? configGlobPatterns[0] : `{${configGlobPatterns.join(',')}}`
     }
 
     const resolvedPattern = resolve(pattern)
@@ -77,7 +77,15 @@ export class CLI {
       const stats = statSync(resolvedPattern)
 
       if (stats.isDirectory()) {
-        return configGlobPattern
+        const relativeDir = relative(this.projectPath, resolvedPattern)
+
+        if (relativeDir) {
+          const scopedPatterns = configGlobPatterns.map(pattern => `${relativeDir}/${pattern}`)
+
+          return scopedPatterns.length === 1 ? scopedPatterns[0] : `{${scopedPatterns.join(',')}}`
+        }
+
+        return configGlobPatterns.length === 1 ? configGlobPatterns[0] : `{${configGlobPatterns.join(',')}}`
       } else if (stats.isFile()) {
         return relative(this.projectPath, resolvedPattern)
       }
@@ -96,10 +104,11 @@ export class CLI {
     }
 
     const filesConfig = config.getFilesConfigForTool('linter')
-    const configGlobPattern = filesConfig.include && filesConfig.include.length > 0
-      ? (filesConfig.include.length === 1 ? filesConfig.include[0] : `{${filesConfig.include.join(',')}}`)
-      : '**/*.html.erb'
-    const adjustedPattern = this.adjustPattern(pattern, configGlobPattern)
+    const configGlobPatterns = filesConfig.include && filesConfig.include.length > 0
+      ? filesConfig.include
+      : ['**/*.html.erb']
+
+    const adjustedPattern = this.adjustPattern(pattern, configGlobPatterns)
 
     let files = await glob(adjustedPattern, {
       cwd: this.projectPath,
@@ -135,7 +144,7 @@ export class CLI {
     const startTime = Date.now()
     const startDate = new Date()
 
-    let { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, ignoreDisableComments, force, init, loadCustomRules, failLevel } = this.argumentParser.parse(process.argv)
+    let { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, fixUnsafe, ignoreDisableComments, force, init, loadCustomRules, failLevel } = this.argumentParser.parse(process.argv)
 
     this.determineProjectPath(patterns)
 
@@ -239,6 +248,7 @@ export class CLI {
         projectPath: this.projectPath,
         pattern: patterns.join(' '),
         fix,
+        fixUnsafe,
         ignoreDisableComments,
         linterConfig,
         config: processingConfig,

package/src/custom-rule-loader.ts

@@ -1,5 +1,5 @@
 import { pathToFileURL } from "url"
-import { glob } from "glob"
+import { glob } from "tinyglobby"
 
 import type { RuleClass } from "./types.js"
 
@@ -52,7 +52,7 @@ export class CustomRuleLoader {
         const files = await glob(pattern, {
           cwd: this.baseDir,
           absolute: true,
-          nodir: true
+          onlyFiles: true
         })
 
         allFiles.push(...files)

package/src/linter.ts

@@ -459,9 +459,12 @@ export 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: string, context?: Partial<LintContext>, offensesToFix?: LintOffense[]): AutofixResult {
+  autofix(source: string, context?: Partial<LintContext>, offensesToFix?: LintOffense[], options?: { includeUnsafe?: boolean }): AutofixResult {
+    const includeUnsafe = options?.includeUnsafe ?? false
     const lintResult = offensesToFix ? { offenses: offensesToFix } : this.lint(source, context)
 
     const parserOffenses: LintOffense[] = []
@@ -503,6 +506,7 @@ export class Linter {
         }
 
         const rule = new RuleClass() as ParserRule
+        const isUnsafe = (RuleClass as any).unsafeAutocorrectable === true
 
         if (!rule.autofix) {
           unfixed.push(offense)
@@ -510,6 +514,12 @@ export class Linter {
           continue
         }
 
+        if (isUnsafe && !includeUnsafe) {
+          unfixed.push(offense)
+
+          continue
+        }
+
         if (offense.autofixContext) {
           const originalNodeType = offense.autofixContext.node.type
           const location: Location = offense.autofixContext.node.location ? Location.from(offense.autofixContext.node.location) : offense.location
@@ -562,12 +572,18 @@ export class Linter {
         }
 
         const rule = new RuleClass() as SourceRule
+        const isUnsafe = (RuleClass as any).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) {