Linter CLI: Improve --upgrade to only disable rules with offenses (#1484)

This pull request is a follow up on
#1453 and improves the `--upgrade`
command in the linter CLI.

Previously, `herb-lint --upgrade` blindly disabled all newly introduced
rules. Now it lints the codebase first with the new rules and:
 - Enables rules that produce zero offenses (safe to adopt immediately)
- Disables only rules that have existing offenses, with offense counts
shown

<img width="2532" height="1898" alt="CleanShot 2026-03-23 at 23 49
16@2x"
src="https://github.com/user-attachments/assets/6a1e8f39-5059-4788-ab64-f73c881db124"
/>

Demo:




https://github.com/user-attachments/assets/931754bf-a3be-4c9c-a97d-ebf2578fde24

Author: marcoroth

javascript/packages/linter/src/cli.ts

@@ -192,15 +192,58 @@ export class CLI {
 
       const { skippedByVersion } = Linter.filterRulesByConfig(rules, config.linter?.rules, configVersion)
 
-      const rulesMutation: Record<string, { enabled: boolean }> = {}
+      let rulesToDisable: typeof skippedByVersion = []
+      let rulesToEnable: typeof skippedByVersion = []
+      const ruleOffenseCounts = new Map<string, number>()
 
-      for (const rule of skippedByVersion) {
-        rulesMutation[rule.ruleName] = { enabled: false }
-      }
+      if (skippedByVersion.length > 0) {
+        console.log(`\n${colorize("↻", "cyan")} Checking ${colorize(String(skippedByVersion.length), "bold")} new ${skippedByVersion.length === 1 ? "rule" : "rules"} against your codebase...`)
+
+        const skippedRulesConfig: Record<string, { enabled: boolean }> = {}
 
-      await Config.mutateConfigFile(config.path, {
-        linter: { rules: rulesMutation }
-      })
+        for (const rule of skippedByVersion) {
+          skippedRulesConfig[rule.ruleName] = { enabled: true }
+        }
+
+        const upgradeConfig = Config.fromObject({
+          ...config.options,
+          linter: {
+            ...config.options.linter,
+            rules: { ...config.options.linter?.rules, ...skippedRulesConfig }
+          }
+        }, { projectPath: this.projectPath, configVersion: version })
+
+        const upgradeContext: ProcessingContext = {
+          projectPath: this.projectPath,
+          config: upgradeConfig,
+          jobs,
+        }
+
+        await Herb.load()
+
+        const files = await config.findFilesForTool('linter', this.projectPath)
+        const upgradeProcessor = new FileProcessor()
+        const results = await upgradeProcessor.processFiles(files, 'json', upgradeContext)
+
+        for (const [ruleName, data] of results.ruleOffenses) {
+          ruleOffenseCounts.set(ruleName, data.count)
+        }
+
+        rulesToDisable = skippedByVersion.filter(rule => ruleOffenseCounts.has(rule.ruleName))
+        rulesToEnable = skippedByVersion.filter(rule => !ruleOffenseCounts.has(rule.ruleName))
+
+        const rulesMutation: Record<string, { enabled: boolean }> = {}
+
+        for (const rule of rulesToDisable) {
+          rulesMutation[rule.ruleName] = { enabled: false }
+        }
+
+        if (Object.keys(rulesMutation).length > 0) {
+          await Config.mutateConfigFile(config.path, {
+            linter: { rules: rulesMutation }
+          })
+        }
+      }
 
       const { promises: fs } = await import("fs")
       let content = await fs.readFile(config.path, "utf-8")
@@ -209,16 +252,29 @@ export class CLI {
 
       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("")
+      if (rulesToEnable.length > 0) {
+        console.log(`\n${colorize("✓", "brightGreen")} Enabled ${colorize(String(rulesToEnable.length), "bold")} new ${rulesToEnable.length === 1 ? "rule" : "rules"} (no offenses found):\n`)
 
-        for (const rule of skippedByVersion) {
-          console.log(`  ${colorize(rule.ruleName, "white")}: ${colorize("enabled: false", "gray")}`)
+        for (const rule of rulesToEnable) {
+          console.log(`  ${colorize("✓", "brightGreen")} ${colorize(rule.ruleName, "white")}`)
+        }
+      }
+
+      if (rulesToDisable.length > 0) {
+        const totalOffenses = Array.from(ruleOffenseCounts.values()).reduce((sum, count) => sum + count, 0)
+
+        console.log(`\n${colorize("!", "yellow")} Found ${colorize(String(totalOffenses), "bold")} ${totalOffenses === 1 ? "offense" : "offenses"} across ${colorize(String(rulesToDisable.length), "bold")} new ${rulesToDisable.length === 1 ? "rule" : "rules"}. Disabled to ease the upgrade:\n`)
+
+        for (const rule of rulesToDisable) {
+          const offenseCount = ruleOffenseCounts.get(rule.ruleName) || 0
+          console.log(`  ${colorize("✗", "red")} ${colorize(rule.ruleName, "white")} ${colorize(`(${offenseCount} ${offenseCount === 1 ? "offense" : "offenses"})`, "gray")}`)
         }
 
-        console.log("")
-        console.log(`  Enable rules individually in your ${colorize(".herb.yml", "cyan")} when you're ready.`)
+        console.log(`\n  When you're ready, review the disabled ${rulesToDisable.length === 1 ? "rule" : "rules"} in your ${colorize(".herb.yml", "cyan")} and re-enable them after fixing the offenses.`)
+      }
+
+      if (skippedByVersion.length === 0) {
+        console.log(`\n${colorize("✓", "brightGreen")} No new rules to configure.`)
       }
 
       console.log("")
@@ -299,6 +355,8 @@ export class CLI {
         processingConfig = modifiedConfig
       }
 
+      const hasConfigFile = Config.exists(configFile || this.projectPath)
+
       const context: ProcessingContext = {
         projectPath: this.projectPath,
         configPath: configFile,
@@ -308,6 +366,7 @@ export class CLI {
         ignoreDisableComments,
         linterConfig,
         config: processingConfig,
+        hasConfigFile,
         loadCustomRules,
         jobs
       }

javascript/packages/linter/src/cli/file-processor.ts

@@ -33,6 +33,7 @@ export interface ProcessingContext {
   ignoreDisableComments?: boolean
   linterConfig?: HerbConfigOptions['linter']
   config?: Config
+  hasConfigFile?: boolean
   loadCustomRules?: boolean
   jobs?: number
 }

javascript/packages/linter/src/cli/output-manager.ts

@@ -62,6 +62,8 @@ export class OutputManager {
           ignoreDisableComments: context?.ignoreDisableComments,
           rulesSkippedByVersion,
           configVersion: context?.config?.configVersion,
+          configPath: context?.config?.path,
+          hasConfigFile: context?.hasConfigFile,
           toolVersion: options.toolVersion,
         })
       }
@@ -125,6 +127,8 @@ export class OutputManager {
         ignoreDisableComments: context?.ignoreDisableComments,
         rulesSkippedByVersion,
         configVersion: context?.config?.configVersion,
+        configPath: context?.config?.path,
+        hasConfigFile: context?.hasConfigFile,
         toolVersion: options.toolVersion,
       })
     }

javascript/packages/linter/src/cli/summary-reporter.ts

@@ -23,6 +23,8 @@ export interface SummaryData {
   ignoreDisableComments?: boolean
   rulesSkippedByVersion?: VersionSkippedRule[]
   configVersion?: string
+  configPath?: string
+  hasConfigFile?: boolean
   toolVersion?: string
 }
 
@@ -132,22 +134,24 @@ export class SummaryReporter {
       console.log(` ${colorize("✓", "brightGreen")} ${colorize("All files are clean!", "green")}`)
     }
 
-    this.displayVersionSkippedRules(data.rulesSkippedByVersion, data.configVersion, data.toolVersion)
+    this.displayVersionSkippedRules(data)
   }
 
-  displayVersionSkippedRules(skippedRules?: VersionSkippedRule[], configVersion?: string, toolVersion?: string): void {
+  displayVersionSkippedRules(data: SummaryData): void {
+    const { rulesSkippedByVersion: skippedRules, configVersion, configPath, hasConfigFile, toolVersion } = data
+
     if (!skippedRules || skippedRules.length === 0) return
+    if (!hasConfigFile) return
 
     const ruleCount = skippedRules.length
     const suggestedVersion = toolVersion || configVersion || "latest"
 
     console.log("")
     console.log(` ${colorize(`New rules available:`, "bold")}`)
+    console.log(`  Your ${colorize(".herb.yml", "cyan")} version is ${colorize(configVersion!, "cyan")}. ${colorize(String(ruleCount), "bold")} new ${this.pluralize(ruleCount, "rule")} ${ruleCount === 1 ? "is" : "are"} disabled to ease upgrades:`)
 
-    if (configVersion) {
-      console.log(`  Your ${colorize(".herb.yml", "cyan")} version is ${colorize(configVersion, "cyan")}. ${colorize(String(ruleCount), "bold")} new ${this.pluralize(ruleCount, "rule")} ${ruleCount === 1 ? "is" : "are"} disabled to ease upgrades:`)
-    } else {
-      console.log(`  ${colorize(String(ruleCount), "bold")} ${this.pluralize(ruleCount, "rule")} ${ruleCount === 1 ? "is" : "are"} available in newer versions:`)
+    if (configPath) {
+      console.log(`  ${colorize("from Herb config:", "gray")} ${colorize(configPath, "cyan")}`)
     }
 
     console.log("")
@@ -174,8 +178,8 @@ export class SummaryReporter {
     }
 
     console.log("")
-    console.log(`  Run ${colorize("herb-lint --upgrade", "cyan")} to update the version and disable all new rules, or`)
-    console.log(`  update the version in your ${colorize(".herb.yml", "cyan")} to ${colorize(`"${suggestedVersion}"`, "cyan")} to enable them all at once.`)
+    console.log(`  Run ${colorize("herb-lint --upgrade", "cyan")} to update the version. Rules with no offenses will be`)
+    console.log(`  enabled automatically; rules with offenses will be disabled to ease the upgrade.`)
   }
 
   displayMostViolatedRules(ruleOffenses: Map<string, { count: number, files: Set<string> }>, limit: number = 5): void {