Linter: Introduce version gated linter rules (#1453)

This pull request introduces version-gated linter rule filtering so that
upgrading Herb doesn't unexpectedly enable new rules for users who have
locked their `.herb.yml` version.

Each rule now declares `static introducedIn = this.version("X.Y.Z")`
indicating the version it was first released in. When a user's
`.herb.yml` version is older than a rule's `introducedIn`, that rule is
automatically skipped. Users can still explicitly enable any rule in
their config regardless of version


**No `.herb.yml`**

<img width="2093" height="623" alt="CleanShot 2026-03-22 at 04 54 37@2x"
src="https://github.com/user-attachments/assets/9449b98d-ace2-4446-a3d4-36d9ffc275ab"
/>

**`.herb.yml` with older version**

<img width="1942" height="2022" alt="CleanShot 2026-03-22 at 04 55
27@2x"
src="https://github.com/user-attachments/assets/95315081-693d-4614-963e-de57428544b5"
/>


**Running `--upgrade`**


<img width="1928" height="1748" alt="CleanShot 2026-03-22 at 04 59
31@2x"
src="https://github.com/user-attachments/assets/245a6ac3-3c3e-4757-aee8-3c938e0da80b"
/>

Author: marcoroth

bin/check_rule_versions

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# Pre-release check: ensures no linter rules have introducedIn = "unreleased".
+# All rules must have a concrete version before publishing a release.
+
+set -euo pipefail
+
+RULES_DIR="javascript/packages/linter/src/rules"
+
+unreleased_rules=$(grep -rl 'static introducedIn = "unreleased"' "$RULES_DIR" 2>/dev/null || true)
+
+if [ -n "$unreleased_rules" ]; then
+  echo ""
+  echo "✗ Found linter rules with introducedIn = \"unreleased\":"
+  echo ""
+
+  for file in $unreleased_rules; do
+    rule_name=$(grep 'static ruleName' "$file" | head -1 | sed 's/.*= "//;s/".*//')
+    echo "  • $rule_name ($file)"
+  done
+
+  echo ""
+  echo "  Update these rules to the release version before publishing."
+  echo ""
+  exit 1
+fi
+
+echo "✓ All linter rules have concrete introducedIn versions."

bin/publish_packages

@@ -4,6 +4,9 @@ set -euo pipefail
 
 npm login
 
+echo "Checking linter rule versions..."
+bin/check_rule_versions
+
 echo "Building all packages..."
 yarn nx run-many -t build --all
 

javascript/packages/config/src/config.ts

@@ -92,6 +92,7 @@ export type LoadOptions = {
 export type FromObjectOptions = {
   projectPath?: string
   version?: string
+  configVersion?: string
 }
 
 export class Config {
@@ -111,10 +112,12 @@ export class Config {
 
   public readonly path: string
   public config: HerbConfig
+  public readonly configVersion: string
 
-  constructor(projectPath: string, config: HerbConfig) {
+  constructor(projectPath: string, config: HerbConfig, configVersion?: string) {
     this.path = Config.configPathFromProjectPath(projectPath)
     this.config = config
+    this.configVersion = configVersion ?? config.version
   }
 
   get projectPath(): string {
@@ -807,7 +810,7 @@ export class Config {
     partial: Partial<HerbConfigOptions>,
     options: FromObjectOptions = {}
   ): Config {
-    const { projectPath = process.cwd(), version = DEFAULT_VERSION } = options
+    const { projectPath = process.cwd(), version = DEFAULT_VERSION, configVersion } = options
     const defaults = this.getDefaultConfig(version)
     const merged: HerbConfig = deepMerge(defaults, partial as any)
 
@@ -825,7 +828,7 @@ export class Config {
       throw error
     }
 
-    return new Config(projectPath, merged)
+    return new Config(projectPath, merged, configVersion)
   }
 
   /**
@@ -1148,19 +1151,14 @@ export class Config {
       throw error
     }
 
-    if (parsed.version && parsed.version !== version) {
-      console.error(`\n⚠️ Configuration version mismatch in ${configPath}`)
-      console.error(`   Config version: ${parsed.version}`)
-      console.error(`   Current version: ${version}`)
-      console.error(`   Consider updating your .herb.yml file.\n`)
-    }
+    const userConfigVersion: string = parsed.version || version
 
     const defaults = this.getDefaultConfig(version)
     const resolved = deepMerge(defaults, parsed as Partial<HerbConfig>)
 
     resolved.version = version
 
-    return new Config(projectRoot, resolved)
+    return new Config(projectRoot, resolved, userConfigVersion)
   }
 
   /**

javascript/packages/config/test/config.test.ts

@@ -1227,4 +1227,122 @@ describe("@herb-tools/config", () => {
       expect(defaultPatterns).toContain("**/*.turbo_stream.erb")
     })
   })
+
+  describe("Config.configVersion", () => {
+    test("defaults to config.version when not provided", () => {
+      const config = new Config(testDir, { version: "0.9.2" })
+
+      expect(config.configVersion).toBe("0.9.2")
+    })
+
+    test("preserves explicit configVersion", () => {
+      const config = new Config(testDir, { version: "0.9.2" }, "0.8.0")
+
+      expect(config.version).toBe("0.9.2")
+      expect(config.configVersion).toBe("0.8.0")
+    })
+
+    test("fromObject passes configVersion through", () => {
+      const config = Config.fromObject({}, { projectPath: testDir, configVersion: "0.7.0" })
+
+      expect(config.configVersion).toBe("0.7.0")
+    })
+
+    test("fromObject defaults configVersion to tool version when not specified", () => {
+      const config = Config.fromObject({}, { projectPath: testDir })
+
+      expect(config.configVersion).toBe(config.version)
+    })
+
+    test("load preserves user config version from .herb.yml", async () => {
+      createTestFile(testDir, ".herb.yml", "version: 0.8.0\n\nlinter:\n  enabled: true\n")
+
+      const config = await Config.load(testDir, { version: "0.9.2", silent: true })
+
+      expect(config.version).toBe("0.9.2")
+      expect(config.configVersion).toBe("0.8.0")
+    })
+
+    test("load defaults configVersion to tool version when .herb.yml has no version", async () => {
+      createTestFile(testDir, ".herb.yml", "linter:\n  enabled: true\n")
+
+      const config = await Config.load(testDir, { version: "0.9.2", silent: true })
+
+      expect(config.configVersion).toBe("0.9.2")
+    })
+  })
+
+  describe("Config upgrade workflow", () => {
+    test("mutateConfigFile adds disabled rules", async () => {
+      const configContent = dedent`
+        version: 0.8.0
+
+        linter:
+          enabled: true
+      `
+
+      createTestFile(testDir, ".herb.yml", configContent + "\n")
+
+      await Config.mutateConfigFile(join(testDir, ".herb.yml"), {
+        linter: {
+          rules: {
+            "new-rule-a": { enabled: false },
+            "new-rule-b": { enabled: false }
+          }
+        }
+      })
+
+      const config = await Config.load(testDir, { version: "0.9.2", silent: true })
+
+      expect(config.linter?.rules?.["new-rule-a"]?.enabled).toBe(false)
+      expect(config.linter?.rules?.["new-rule-b"]?.enabled).toBe(false)
+    })
+
+    test("mutateConfigFile preserves existing rules", async () => {
+      const configContent = dedent`
+        version: 0.8.0
+
+        linter:
+          enabled: true
+          rules:
+            existing-rule:
+              enabled: false
+      `
+
+      createTestFile(testDir, ".herb.yml", configContent + "\n")
+
+      await Config.mutateConfigFile(join(testDir, ".herb.yml"), {
+        linter: {
+          rules: {
+            "new-rule": { enabled: false }
+          }
+        }
+      })
+
+      const config = await Config.load(testDir, { version: "0.9.2", silent: true })
+
+      expect(config.linter?.rules?.["existing-rule"]?.enabled).toBe(false)
+      expect(config.linter?.rules?.["new-rule"]?.enabled).toBe(false)
+    })
+
+    test("version can be updated via file content replacement", async () => {
+      const configContent = dedent`
+        version: 0.8.0
+
+        linter:
+          enabled: true
+      `
+
+      const configPath = createTestFile(testDir, ".herb.yml", configContent + "\n")
+
+      const { readFileSync, writeFileSync } = await import("fs")
+      let content = readFileSync(configPath, "utf-8")
+      content = content.replace(/^version:\s*.+$/m, "version: 0.9.2")
+      writeFileSync(configPath, content, "utf-8")
+
+      const config = await Config.load(testDir, { version: "0.9.2", silent: true })
+
+      expect(config.configVersion).toBe("0.9.2")
+    })
+  })
 })

javascript/packages/language-server/src/linter_service.ts

@@ -161,7 +161,7 @@ export class LinterService {
         }
       }, { projectPath: projectConfig?.projectPath || process.cwd() })
 
-      const filteredRules = Linter.filterRulesByConfig(this.allRules, config.linter?.rules)
+      const { enabled: filteredRules } = Linter.filterRulesByConfig(this.allRules, config.linter?.rules, config.configVersion)
 
       this.linter = new Linter(Herb, filteredRules, config, this.allRules)
     }

javascript/packages/linter/package.json

@@ -22,7 +22,8 @@
     "watch": "tsc -b -w",
     "test": "vitest run",
     "test:watch": "vitest --watch",
-    "prepublishOnly": "yarn clean && yarn build && yarn test"
+    "check:rule-versions": "! grep -rl 'static introducedIn = \"unreleased\"' src/rules/ 2>/dev/null || (echo '\\n✗ Found linter rules with introducedIn = \"unreleased\". Update them to a release version before publishing.\\n' && exit 1)",
+    "prepublishOnly": "yarn check:rule-versions && yarn clean && yarn build && yarn test"
   },
   "exports": {
     "./package.json": "./package.json",

javascript/packages/linter/src/cli.ts

@@ -4,7 +4,10 @@ import { Config, addHerbExtensionRecommendation, getExtensionsJsonRelativePath }
 
 import { existsSync, statSync } from "fs"
 import { resolve, relative } from "path"
+import { colorize } from "@herb-tools/highlighter"
 
+import { Linter } from "./linter.js"
+import { rules } from "./rules.js"
 import { ArgumentParser } from "./cli/argument-parser.js"
 import { FileProcessor } from "./cli/file-processor.js"
 import { OutputManager } from "./cli/output-manager.js"
@@ -144,7 +147,7 @@ export class CLI {
     const startTime = Date.now()
     const startDate = new Date()
 
-    const { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, fixUnsafe, ignoreDisableComments, force, init, loadCustomRules, failLevel, jobs } = this.argumentParser.parse(process.argv)
+    const { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, fixUnsafe, ignoreDisableComments, force, init, upgrade, loadCustomRules, failLevel, jobs } = this.argumentParser.parse(process.argv)
 
     this.determineProjectPath(patterns)
 
@@ -171,6 +174,57 @@ export class CLI {
       process.exit(0)
     }
 
+    if (upgrade) {
+      const configPath = configFile || this.projectPath
+
+      if (!Config.exists(configPath)) {
+        console.error(`\n✗ No .herb.yml found. Run ${colorize("herb-lint --init", "cyan")} first.\n`)
+        process.exit(1)
+      }
+
+      const config = await Config.load(configPath, { version, exitOnError: true, createIfMissing: false, silent: true })
+      const configVersion = config.configVersion
+
+      if (configVersion === version) {
+        console.log(`\n✓ Your .herb.yml is already at version ${version}. Nothing to upgrade.\n`)
+        process.exit(0)
+      }
+
+      const { skippedByVersion } = Linter.filterRulesByConfig(rules, config.linter?.rules, configVersion)
+
+      const rulesMutation: Record<string, { enabled: boolean }> = {}
+
+      for (const rule of skippedByVersion) {
+        rulesMutation[rule.ruleName] = { enabled: false }
+      }
+
+      await Config.mutateConfigFile(config.path, {
+        linter: { rules: rulesMutation }
+      })
+
+      const { promises: fs } = await import("fs")
+      let content = await fs.readFile(config.path, "utf-8")
+      content = content.replace(/^version:\s*.+$/m, `version: ${version}`)
+      await fs.writeFile(config.path, content, "utf-8")
+
+      console.log(`\n${colorize("✓", "brightGreen")} Updated ${colorize(".herb.yml", "cyan")} version from ${colorize(configVersion, "cyan")} to ${colorize(version, "cyan")}`)
+
+      if (skippedByVersion.length > 0) {
+        console.log(`${colorize("✓", "brightGreen")} Disabled ${colorize(String(skippedByVersion.length), "bold")} newly introduced ${skippedByVersion.length === 1 ? "rule" : "rules"}:`)
+        console.log("")
+
+        for (const rule of skippedByVersion) {
+          console.log(`  ${colorize(rule.ruleName, "white")}: ${colorize("enabled: false", "gray")}`)
+        }
+
+        console.log("")
+        console.log(`  Enable rules individually in your ${colorize(".herb.yml", "cyan")} when you're ready.`)
+      }
+
+      console.log("")
+      process.exit(0)
+    }
+
     const silent = formatOption === 'json'
     const config = await Config.load(configFile || this.projectPath, { version, exitOnError: true, createIfMissing: false, silent })
     const linterConfig = config.options.linter || {}
@@ -183,7 +237,8 @@ export class CLI {
       showTiming,
       useGitHubActions,
       startTime,
-      startDate
+      startDate,
+      toolVersion: version
     }
 
     try {
@@ -260,6 +315,13 @@ export class CLI {
       const results = await this.fileProcessor.processFiles(files, formatOption, context)
 
       await this.outputManager.outputResults({ ...results, files }, outputOptions)
+
+      if (!Config.exists(this.projectPath) && formatOption !== 'json' && !useGitHubActions) {
+        console.log("")
+        console.log(` ${colorize("TIP:", "bold")} Run ${colorize("herb-lint --init", "cyan")} to create a ${colorize(".herb.yml", "cyan")} and lock the ${colorize("version", "cyan")}.`)
+        console.log(`      This ensures upgrading Herb won't enable new rules until you update the ${colorize("version", "cyan")} in ${colorize(".herb.yml", "cyan")}.`)
+      }
+
       await this.afterProcess(results, outputOptions)
 
       const effectiveFailLevel = failLevel || linterConfig.failLevel

javascript/packages/linter/src/cli/argument-parser.ts

@@ -26,6 +26,7 @@ export interface ParsedArguments {
   ignoreDisableComments: boolean
   force: boolean
   init: boolean
+  upgrade: boolean
   loadCustomRules: boolean
   failLevel?: DiagnosticSeverity
   jobs: number
@@ -43,6 +44,7 @@ export class ArgumentParser {
       -h, --help                    show help
       -v, --version                 show version
       --init                        create a .herb.yml configuration file in the current directory
+      --upgrade                     update .herb.yml version and disable all newly introduced rules
       -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
@@ -71,6 +73,7 @@ export class ArgumentParser {
         help: { type: "boolean", short: "h" },
         version: { type: "boolean", short: "v" },
         init: { type: "boolean" },
+        upgrade: { type: "boolean" },
         "config-file": { type: "string", short: "c" },
         force: { type: "boolean" },
         fix: { type: "boolean" },
@@ -155,6 +158,7 @@ export class ArgumentParser {
     const ignoreDisableComments = values["ignore-disable-comments"] || false
     const configFile = values["config-file"]
     const init = values.init || false
+    const upgrade = values.upgrade || false
     const loadCustomRules = !values["no-custom-rules"]
 
     let failLevel: DiagnosticSeverity | undefined
@@ -181,7 +185,7 @@ export class ArgumentParser {
       jobs = parsed
     }
 
-    return { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, fixUnsafe, ignoreDisableComments, force, init, loadCustomRules, failLevel, jobs }
+    return { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, fixUnsafe, ignoreDisableComments, force, init, upgrade, loadCustomRules, failLevel, jobs }
   }
 
   private getFilePatterns(positionals: string[]): string[] {