Linter: Use --regenerate-todo to create a todo list for ignoring rules.

Using this parameter creates a .herb-todo.yml file that is used to
ignore rules massively, this is usefull for big projects adopting the
linter, to start ignoring all current offenses without having to ommit
all in the files manually.

Author: domingo2000

javascript/packages/linter/src/cli.ts

@@ -141,7 +141,17 @@ export class CLI {
     const startTime = Date.now()
     const startDate = new Date()
 
-    let { pattern, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix } = this.argumentParser.parse(process.argv)
+    let { 
+      pattern,
+      formatOption,
+      showTiming,
+      theme,
+      wrapLines,
+      truncateLines,
+      useGitHubActions,
+      fix,
+      regenerateTodo
+    } = this.argumentParser.parse(process.argv)
 
     this.determineProjectPath(pattern)
 
@@ -170,7 +180,8 @@ export class CLI {
       const context = {
         projectPath: this.projectPath,
         pattern,
-        fix
+        fix,
+        regenerateTodo
       }
 
       const results = await this.fileProcessor.processFiles(files, formatOption, context)

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

@@ -22,7 +22,8 @@ export interface ParsedArguments {
   wrapLines: boolean
   truncateLines: boolean
   useGitHubActions: boolean
-  fix: boolean
+  fix: boolean,
+  regenerateTodo: boolean,
 }
 
 export class ArgumentParser {
@@ -48,6 +49,7 @@ export class ArgumentParser {
       --no-timing      hide timing information
       --no-wrap-lines  disable line wrapping
       --truncate-lines enable line truncation (mutually exclusive with line wrapping)
+      --regenerate-todo   generate a .herb-todo.yml file with current diagnostics
   `
 
   parse(argv: string[]): ParsedArguments {
@@ -66,7 +68,8 @@ export class ArgumentParser {
         "no-color": { type: "boolean" },
         "no-timing": { type: "boolean" },
         "no-wrap-lines": { type: "boolean" },
-        "truncate-lines": { type: "boolean" }
+        "truncate-lines": { type: "boolean" },
+        "regenerate-todo": { type: "boolean" },
       },
       allowPositionals: true
     })
@@ -125,11 +128,23 @@ export class ArgumentParser {
       process.exit(1)
     }
 
+    const regenerateTodo = values["regenerate-todo"] || false
+
     const theme = values.theme || DEFAULT_THEME
     const pattern = this.getFilePattern(positionals)
     const fix = values.fix || false
 
-    return { pattern, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix }
+    return { 
+      pattern,
+      formatOption,
+      showTiming,
+      theme,
+      wrapLines,
+      truncateLines,
+      useGitHubActions,
+      fix,
+      regenerateTodo,
+    }
   }
 
   private getFilePattern(positionals: string[]): string {

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

@@ -7,6 +7,8 @@ import { colorize } from "@herb-tools/highlighter"
 
 import type { Diagnostic } from "@herb-tools/core"
 import type { FormatOption } from "./argument-parser.js"
+import { LintOffense } from "../types.js"
+import { LinterTodo } from "../linter-todo.js"
 
 export interface ProcessedFile {
   filename: string
@@ -19,6 +21,7 @@ export interface ProcessingContext {
   projectPath?: string
   pattern?: string
   fix?: boolean
+  regenerateTodo?: boolean
 }
 
 export interface ProcessingResult {
@@ -35,6 +38,7 @@ export interface ProcessingResult {
 
 export class FileProcessor {
   private linter: Linter | null = null
+  private linterTodo: LinterTodo | null = null
 
   private isRuleAutocorrectable(ruleName: string): boolean {
     if (!this.linter) return false
@@ -51,6 +55,15 @@ export class FileProcessor {
   }
 
   async processFiles(files: string[], formatOption: FormatOption = 'detailed', context?: ProcessingContext): Promise<ProcessingResult> {
+
+    if (context?.projectPath) {
+      this.linterTodo = new LinterTodo(context.projectPath)
+    }
+
+    if (context?.regenerateTodo) {
+      this.linterTodo?.clearTodoFile()
+    }
+
     let totalErrors = 0
     let totalWarnings = 0
     let totalIgnored = 0
@@ -60,7 +73,9 @@ export class FileProcessor {
     const allOffenses: ProcessedFile[] = []
     const ruleOffenses = new Map<string, { count: number, files: Set<string> }>()
 
-    for (const filename of files) {
+  const todoOffenses: Record<string, LintOffense[]> = {}
+
+  for (const filename of files) {
       const filePath = context?.projectPath ? resolve(context.projectPath, filename) : resolve(filename)
       let content = readFileSync(filePath, "utf-8")
       const parseResult = Herb.parse(content)
@@ -85,10 +100,13 @@ export class FileProcessor {
       }
 
       if (!this.linter) {
-        this.linter = new Linter(Herb)
+        this.linter = new Linter(Herb, undefined, this.linterTodo)
       }
 
       const lintResult = this.linter.lint(content, { fileName: filename })
+      if (context?.regenerateTodo) {
+        todoOffenses[filename] = lintResult.offenses
+      }
 
       if (ruleCount === 0) {
         ruleCount = this.linter.getRuleCount()
@@ -154,6 +172,10 @@ export class FileProcessor {
       totalIgnored += lintResult.ignored
     }
 
+    if (context?.regenerateTodo && this.linterTodo) {
+      this.linterTodo.regenerateTodoConfig(todoOffenses)
+    }
+
     return { totalErrors, totalWarnings, totalIgnored, filesWithOffenses, filesFixed, ruleCount, allOffenses, ruleOffenses, context }
   }
 }

javascript/packages/linter/src/linter-todo.ts

@@ -0,0 +1,142 @@
+import { LintOffense } from "./types"
+import YAML from "yaml"
+import { join, relative, isAbsolute } from "path"
+import { existsSync, unlinkSync, readFileSync, writeFileSync } from "fs"
+
+export interface TodoConfig {
+  excludes: {
+    [ruleName: string]: {
+      [filePath: string]: {
+        warnings: number
+        errors: number
+      }
+    }
+  }
+}
+
+export class LinterTodo {
+  private static readonly TODO_FILE = '.herb-todo.yml'
+  private todoConfig: TodoConfig | null = null
+  private readonly projectPath: string
+  private readonly todoPath: string
+
+  constructor(projectPath: string) {
+    this.projectPath = projectPath
+    this.todoPath = join(this.projectPath, LinterTodo.TODO_FILE)
+    this.loadTodoConfig()
+  }
+
+  clearTodoFile(): void {
+    if (!this.todoExists()) return
+    unlinkSync(this.todoPath)
+    this.loadTodoConfig()
+  }
+
+  regenerateTodoConfig(offenses: Record<string, LintOffense[]>): void {
+    const config: TodoConfig = { excludes: {} }
+    for (const filePath of Object.keys(offenses)) {
+      const fileOffenses = offenses[filePath]
+      const relativePath = isAbsolute(filePath) ? relative(this.projectPath, filePath) : filePath
+      for (const offense of fileOffenses) {
+        const ruleName = offense.rule
+        if (!config.excludes[ruleName]) {
+          config.excludes[ruleName] = {}
+        }
+        if (!config.excludes[ruleName][relativePath]) {
+          config.excludes[ruleName][relativePath] = {
+            warnings: 0,
+            errors: 0
+          }
+        }
+        if (offense.severity === 'warning') {
+          config.excludes[ruleName][relativePath].warnings++
+        } else if (offense.severity === 'error') {
+          config.excludes[ruleName][relativePath].errors++
+        }
+      }
+    }
+    const todoPath = join(this.projectPath, LinterTodo.TODO_FILE)
+    writeFileSync(todoPath, YAML.stringify(config))
+  }
+
+  shouldIgnoreOffense(offenses: LintOffense[], filePath: string): LintOffense[] {
+    if (!this.todoConfig) return offenses
+
+    const relativePath = isAbsolute(filePath) ? relative(this.projectPath, filePath) : filePath
+    const remainingOffenses: LintOffense[] = []
+
+    // Track how many errors/warnings we've skipped per rule
+    const skipped = new Map<string, { errors: number; warnings: number }>()
+
+    for (const offense of offenses) {
+      // Only consider errors and warnings
+      if (offense.severity !== 'error' && offense.severity !== 'warning') {
+        remainingOffenses.push(offense)
+        continue
+      }
+
+      const rule = offense.rule
+      const ruleExcludes = this.todoConfig.excludes[rule]
+      const allowed = ruleExcludes ? ruleExcludes[relativePath] : undefined
+
+      if (!allowed) {
+        // No allowed counts for this rule/file — keep the offense
+        remainingOffenses.push(offense)
+        continue
+      }
+
+      const counts = skipped.get(rule) || { errors: 0, warnings: 0 }
+
+      if (offense.severity === 'error') {
+        if (counts.errors < allowed.errors) {
+          counts.errors++
+          skipped.set(rule, counts)
+          continue
+        }
+        remainingOffenses.push(offense)
+      } else {
+        if (counts.warnings < allowed.warnings) {
+          counts.warnings++
+          skipped.set(rule, counts)
+          continue
+        }
+        remainingOffenses.push(offense)
+      }
+    }
+
+    return remainingOffenses
+  }
+
+  private todoExists(): boolean {
+    return existsSync(this.todoPath)
+  }
+
+  private loadTodoConfig(): void {
+    if (!this.todoExists()) {
+      this.todoConfig = { excludes: {} }
+      return
+    }
+
+    try {
+      const content = readFileSync(this.todoPath, 'utf8')
+      const parsed: TodoConfig = YAML.parse(content)
+      const normalized: TodoConfig = { excludes: {} }
+
+      for (const ruleName of Object.keys(parsed.excludes || {})) {
+        const files = parsed.excludes[ruleName] || {}
+        normalized.excludes[ruleName] = {}
+
+        for (const fileKey of Object.keys(files)) {
+          const targetKey = isAbsolute(fileKey) ? relative(this.projectPath, fileKey) : fileKey
+          normalized.excludes[ruleName][targetKey] = files[fileKey]
+        }
+      }
+
+      this.todoConfig = normalized
+    }
+    catch {
+      console.log('Warning: Failed to load .herb-todo.yml. Ignoring todo configuration.')
+      this.todoConfig = { excludes: {} }
+    }
+  }
+}

javascript/packages/linter/src/linter.ts

@@ -4,22 +4,25 @@ import { IdentityPrinter } from "@herb-tools/printer"
 import { findNodeByLocation } from "./rules/rule-utils.js"
 
 import type { RuleClass, Rule, ParserRule, LexerRule, SourceRule, LintResult, LintOffense, LintContext, AutofixResult } from "./types.js"
+import { LinterTodo } from "./linter-todo.js"
 import type { HerbBackend } from "@herb-tools/core"
 
 export class Linter {
   protected rules: RuleClass[]
   protected herb: HerbBackend
   protected offenses: LintOffense[]
+  private linterTodo: LinterTodo | null
 
   /**
    * Creates a new Linter instance.
    * @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(herb: HerbBackend, rules?: RuleClass[]) {
+  constructor(herb: HerbBackend, rules?: RuleClass[], LinterTodo?: LinterTodo | null) {
     this.herb = herb
     this.rules = rules !== undefined ? rules : this.getDefaultRules()
     this.offenses = []
+    this.linterTodo = LinterTodo || null
   }
 
   /**
@@ -144,15 +147,22 @@ export class Linter {
       this.offenses.push(...kept)
     }
 
+    if (this.linterTodo && context?.fileName) {
+      const filtered: LintOffense[] = this.linterTodo.shouldIgnoreOffense(this.offenses, context.fileName)
+      this.offenses = filtered
+    }
+
     const errors = this.offenses.filter(offense => offense.severity === "error").length
     const warnings = this.offenses.filter(offense => offense.severity === "warning").length
 
-    return {
+    const result: LintResult = {
       offenses: this.offenses,
       errors,
       warnings,
-      ignored: ignoredCount
+      ignored: ignoredCount,
     }
+
+    return result
   }
 
   /**
@@ -213,7 +223,7 @@ export class Linter {
 
         if (offense.autofixContext) {
           const originalNodeType = offense.autofixContext.node.type
-          const location: Location = offense.autofixContext.node.location ? Location.from(offense.autofixContext.node.location) : offense.location
+          const location: Location = offense.autofixContext.node.location ? Location.from(offense.autofixContext.node.location) : offense.location
 
           const freshNode = findNodeByLocation(
             parseResult.value,

javascript/packages/linter/src/types.ts

@@ -142,6 +142,7 @@ export interface LexerRuleConstructor {
  */
 export interface LintContext {
   fileName: string | undefined
+  regenerateTodo?: boolean
 }
 
 /**