@herb-tools/linter 0.7.5 → 0.8.0

package/src/cli/summary-reporter.ts

@@ -4,12 +4,18 @@ export interface SummaryData {
   files: string[]
   totalErrors: number
   totalWarnings: number
+  totalInfo?: number
+  totalHints?: number
+  totalIgnored: number
+  totalWouldBeIgnored?: number
   filesWithOffenses: number
   ruleCount: number
   startTime: number
   startDate: Date
   showTiming: boolean
   ruleOffenses: Map<string, { count: number, files: Set<string> }>
+  autofixableCount: number
+  ignoreDisableComments?: boolean
 }
 
 export class SummaryReporter {
@@ -18,7 +24,7 @@ export class SummaryReporter {
   }
 
   displaySummary(data: SummaryData): void {
-    const { files, totalErrors, totalWarnings, filesWithOffenses, ruleCount, startTime, startDate, showTiming } = data
+    const { files, totalErrors, totalWarnings, totalInfo = 0, totalHints = 0, totalIgnored, totalWouldBeIgnored, filesWithOffenses, ruleCount, startTime, startDate, showTiming, autofixableCount, ignoreDisableComments } = data
 
     console.log("\n")
     console.log(` ${colorize("Summary:", "bold")}`)
@@ -62,6 +68,18 @@ export class SummaryReporter {
       parts.push(colorize(colorize(`${totalWarnings} ${this.pluralize(totalWarnings, "warning")}`, "green"), "bold"))
     }
 
+    if (totalInfo > 0) {
+      parts.push(colorize(colorize(`${totalInfo} info`, "brightBlue"), "bold"))
+    }
+
+    if (totalHints > 0) {
+      parts.push(colorize(colorize(`${totalHints} ${this.pluralize(totalHints, "hint")}`, "gray"), "bold"))
+    }
+
+    if (totalIgnored > 0) {
+      parts.push(colorize(colorize(`${totalIgnored} ignored`, "gray"), "bold"))
+    }
+
     if (parts.length === 0) {
       offensesSummary = colorize(colorize("0 offenses", "green"), "bold")
     } else {
@@ -69,17 +87,36 @@ export class SummaryReporter {
 
       let detailText = ""
 
-      const totalOffenses = totalErrors + totalWarnings
+      const totalOffenses = totalErrors + totalWarnings + totalInfo + totalHints
 
       if (filesWithOffenses > 0) {
         detailText = `${totalOffenses} ${this.pluralize(totalOffenses, "offense")} across ${filesWithOffenses} ${this.pluralize(filesWithOffenses, "file")}`
       }
 
-      offensesSummary += ` ${colorize(colorize(`(${detailText})`, "gray"), "dim")}`
+      if (detailText) {
+        offensesSummary += ` ${colorize(colorize(`(${detailText})`, "gray"), "dim")}`
+      }
     }
 
     console.log(`  ${colorize(pad("Offenses"), "gray")} ${offensesSummary}`)
 
+    if (ignoreDisableComments && totalWouldBeIgnored && totalWouldBeIgnored > 0) {
+      const message = `${colorize(colorize(`${totalWouldBeIgnored} additional ${this.pluralize(totalWouldBeIgnored, "offense")} reported (would have been ignored)`, "cyan"), "bold")}`
+      console.log(`  ${colorize(pad("Note"), "gray")} ${message}`)
+    }
+
+    const totalOffenses = totalErrors + totalWarnings + totalInfo + totalHints
+
+    if (autofixableCount > 0 || totalOffenses > 0) {
+      let fixableLine = `${colorize(colorize(`${totalOffenses} ${this.pluralize(totalOffenses, "offense")}`, "brightRed"), "bold")}`
+
+      if (autofixableCount > 0) {
+        fixableLine += ` | ${colorize(colorize(`${autofixableCount} autocorrectable using \`--fix\``, "green"), "bold")}`
+      }
+
+      console.log(`  ${colorize(pad("Fixable"), "gray")} ${fixableLine}`)
+    }
+
     if (showTiming) {
       const duration = Date.now() - startTime
       const timeString = startDate.toTimeString().split(' ')[0]

package/src/cli.ts

@@ -1,11 +1,17 @@
 import { glob } from "glob"
 import { Herb } from "@herb-tools/node-wasm"
+import { Config, addHerbExtensionRecommendation, getExtensionsJsonRelativePath } from "@herb-tools/config"
+
 import { existsSync, statSync } from "fs"
 import { dirname, resolve, relative } from "path"
 
-import { ArgumentParser, type FormatOption } from "./cli/argument-parser.js"
+import { ArgumentParser } from "./cli/argument-parser.js"
 import { FileProcessor } from "./cli/file-processor.js"
 import { OutputManager } from "./cli/output-manager.js"
+import { version } from "../package.json"
+
+import type { ProcessingContext } from "./cli/file-processor.js"
+import type { FormatOption } from "./cli/argument-parser.js"
 
 export * from "./cli/index.js"
 
@@ -19,44 +25,6 @@ export class CLI {
     return this.projectPath
   }
 
-  protected findProjectRoot(startPath: string): string {
-    let currentPath = resolve(startPath)
-
-    if (existsSync(currentPath) && statSync(currentPath).isFile()) {
-      currentPath = dirname(currentPath)
-    }
-
-    const projectIndicators = [
-      'package.json',
-      'Gemfile',
-      '.git',
-      'tsconfig.json',
-      'composer.json',
-      'pyproject.toml',
-      'requirements.txt',
-      '.herb.yml'
-    ]
-
-    while (currentPath !== '/') {
-      for (const indicator of projectIndicators) {
-        if (existsSync(resolve(currentPath, indicator))) {
-          return currentPath
-        }
-      }
-
-      const parentPath = dirname(currentPath)
-      if (parentPath === currentPath) {
-        break
-      }
-
-      currentPath = parentPath
-    }
-
-    return existsSync(startPath) && statSync(startPath).isDirectory()
-      ? startPath
-      : dirname(startPath)
-  }
-
   protected exitWithError(message: string, formatOption: FormatOption, exitCode: number = 1) {
     this.outputManager.outputError(message, {
       formatOption,
@@ -87,7 +55,8 @@ export class CLI {
     process.exit(exitCode)
   }
 
-  protected determineProjectPath(pattern: string | undefined): void {
+  protected determineProjectPath(patterns: string[]): void {
+    const pattern = patterns[0]
     if (pattern) {
       const resolvedPattern = resolve(pattern)
 
@@ -97,15 +66,15 @@ export class CLI {
         if (stats.isDirectory()) {
           this.projectPath = resolvedPattern
         } else {
-          this.projectPath = this.findProjectRoot(resolvedPattern)
+          this.projectPath = dirname(resolvedPattern)
         }
       }
     }
   }
 
-  protected adjustPattern(pattern: string | undefined): string {
+  protected adjustPattern(pattern: string | undefined, configGlobPattern: string): string {
     if (!pattern) {
-      return '**/*.html.erb'
+      return configGlobPattern
     }
 
     const resolvedPattern = resolve(pattern)
@@ -114,7 +83,7 @@ export class CLI {
       const stats = statSync(resolvedPattern)
 
       if (stats.isDirectory()) {
-        return '**/*.html.erb'
+        return configGlobPattern
       } else if (stats.isFile()) {
         return relative(this.projectPath, resolvedPattern)
       }
@@ -123,6 +92,41 @@ export class CLI {
     return pattern
   }
 
+  protected async resolvePatternToFiles(pattern: string, config: Config, force: boolean): Promise<{ files: string[], explicitFile: string | undefined }> {
+    const resolvedPattern = resolve(pattern)
+    const isExplicitFile = existsSync(resolvedPattern) && statSync(resolvedPattern).isFile()
+    let explicitFile: string | undefined
+
+    if (isExplicitFile) {
+      explicitFile = pattern
+    }
+
+    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)
+
+    let files = await glob(adjustedPattern, {
+      cwd: this.projectPath,
+      ignore: filesConfig.exclude || []
+    })
+
+    if (explicitFile && files.length === 0) {
+      if (!force) {
+        console.error(`⚠️  File ${explicitFile} is excluded by configuration patterns.`)
+        console.error(`   Use --force to lint it anyway.\n`)
+        process.exit(0)
+      } else {
+        console.log(`⚠️  Forcing linter on excluded file: ${explicitFile}`)
+        console.log()
+        files = [adjustedPattern]
+      }
+    }
+
+    return { files, explicitFile }
+  }
+
   protected async beforeProcess(): Promise<void> {
     // Hook for subclasses to add custom output before processing
   }
@@ -137,11 +141,36 @@ export class CLI {
     const startTime = Date.now()
     const startDate = new Date()
 
-    let { pattern, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions } = this.argumentParser.parse(process.argv)
+    let { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, ignoreDisableComments, force, init, loadCustomRules } = this.argumentParser.parse(process.argv)
 
-    this.determineProjectPath(pattern)
+    this.determineProjectPath(patterns)
 
-    pattern = this.adjustPattern(pattern)
+    if (init) {
+      const configPath = configFile || this.projectPath
+
+      if (Config.exists(configPath)) {
+        const fullPath = configFile || Config.configPathFromProjectPath(this.projectPath)
+        console.error(`\n✗ Configuration file already exists at ${fullPath}`)
+        console.error(`  Use --config-file to specify a different location.\n`)
+        process.exit(1)
+      }
+
+      const config = await Config.loadForCLI(configPath, version, true)
+      const extensionAdded = addHerbExtensionRecommendation(this.projectPath)
+
+      console.log(`\n✓ Configuration initialized at ${config.path}`)
+
+      if (extensionAdded) {
+        console.log(`✓ VSCode extension recommended in ${getExtensionsJsonRelativePath()}`)
+      }
+
+      console.log(`  Edit this file to customize linter and formatter settings.\n`)
+      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 || {}
 
     const outputOptions = {
       formatOption,
@@ -157,15 +186,69 @@ export class CLI {
     try {
       await this.beforeProcess()
 
-      const files = await glob(pattern, { cwd: this.projectPath })
+      if (linterConfig.enabled === false && !force) {
+        this.exitWithInfo("Linter is disabled in .herb.yml configuration. Use --force to lint anyway.", formatOption, 0, { startTime, startDate, showTiming })
+      }
+
+      if (force && linterConfig.enabled === false) {
+        console.log("⚠️  Forcing linter run (disabled in .herb.yml)")
+        console.log()
+      }
+
+      let files: string[]
+      let explicitFiles: string[] = []
+
+      if (patterns.length === 0) {
+        files = await config.findFilesForTool('linter', this.projectPath)
+      } else {
+        const allFiles: string[] = []
+
+        for (const pattern of patterns) {
+          const { files: patternFiles, explicitFile } = await this.resolvePatternToFiles(pattern, config, force)
+
+          if (patternFiles.length === 0) {
+            console.error(`✗ No files found matching pattern: ${pattern}`)
+            process.exit(1)
+          }
+
+          allFiles.push(...patternFiles)
+          if (explicitFile) {
+            explicitFiles.push(explicitFile)
+          }
+        }
+
+        files = [...new Set(allFiles)]
+      }
 
       if (files.length === 0) {
-        this.exitWithInfo(`No files found matching pattern: ${pattern}`, formatOption, 0, { startTime, startDate, showTiming })
+        this.exitWithInfo(`No files found matching patterns: ${patterns.join(', ') || 'from config'}`, formatOption, 0, { startTime, startDate, showTiming })
+      }
+
+      let processingConfig = config
+
+      if (force && explicitFiles.length > 0) {
+        const modifiedConfig = Object.create(Object.getPrototypeOf(config))
+        Object.assign(modifiedConfig, config)
+
+        modifiedConfig.config = {
+          ...config.config,
+          linter: {
+            ...config.config.linter,
+            exclude: []
+          }
+        }
+
+        processingConfig = modifiedConfig
       }
 
-      const context = {
+      const context: ProcessingContext = {
         projectPath: this.projectPath,
-        pattern: pattern
+        pattern: patterns.join(' '),
+        fix,
+        ignoreDisableComments,
+        linterConfig,
+        config: processingConfig,
+        loadCustomRules
       }
 
       const results = await this.fileProcessor.processFiles(files, formatOption, context)

package/src/custom-rule-loader.ts

@@ -0,0 +1,189 @@
+import { pathToFileURL } from "url"
+import { glob } from "glob"
+
+import type { RuleClass } from "./types.js"
+
+export interface CustomRuleLoaderOptions {
+  /**
+   * Base directory to search for custom rules
+   * Defaults to current working directory
+   */
+  baseDir?: string
+
+  /**
+   * Glob patterns to search for custom rule files
+   * Defaults to looking in common locations
+   */
+  patterns?: string[]
+
+  /**
+   * Whether to suppress errors when loading custom rules
+   * Defaults to false
+   */
+  silent?: boolean
+}
+
+const DEFAULT_PATTERNS = [
+  ".herb/rules/**/*.mjs",
+]
+
+/**
+ * Loads custom linter rules from the user's project
+ */
+export class CustomRuleLoader {
+  private baseDir: string
+  private patterns: string[]
+  private silent: boolean
+
+  constructor(options: CustomRuleLoaderOptions = {}) {
+    this.baseDir = options.baseDir || process.cwd()
+    this.patterns = options.patterns || DEFAULT_PATTERNS
+    this.silent = options.silent || false
+  }
+
+  /**
+   * Discovers custom rule files in the project
+   */
+  async discoverRuleFiles(): Promise<string[]> {
+    const allFiles: string[] = []
+
+    for (const pattern of this.patterns) {
+      try {
+        const files = await glob(pattern, {
+          cwd: this.baseDir,
+          absolute: true,
+          nodir: true
+        })
+
+        allFiles.push(...files)
+      } catch (error) {
+        if (!this.silent) {
+          console.warn(`Warning: Failed to search pattern "${pattern}": ${error}`)
+        }
+      }
+    }
+
+    return [...new Set(allFiles)]
+  }
+
+  /**
+   * Loads a single rule file
+   */
+  async loadRuleFile(filePath: string): Promise<RuleClass[]> {
+    try {
+      const fileUrl = pathToFileURL(filePath).href
+      const cacheBustedUrl = `${fileUrl}?t=${Date.now()}`
+      const module = await import(cacheBustedUrl)
+
+      if (module.default && this.isValidRuleClass(module.default)) {
+        return [module.default]
+      }
+
+      if (!this.silent) {
+        console.warn(`Warning: No valid default export found in "${filePath}". Custom rules must use default export.`)
+      }
+
+      return []
+    } catch (error) {
+      if (!this.silent) {
+        console.error(`Error loading rule file "${filePath}": ${error}`)
+      }
+      return []
+    }
+  }
+
+  /**
+   * Type guard to check if an export is a valid rule class
+   */
+  private isValidRuleClass(value: any): value is RuleClass {
+    if (typeof value !== 'function') return false
+    if (!value.prototype) return false
+
+    const instance = new value()
+
+    return typeof instance.check === 'function' && typeof instance.name === 'string'
+  }
+
+  /**
+   * Loads all custom rules from the project
+   */
+  async loadRules(): Promise<RuleClass[]> {
+    const ruleFiles = await this.discoverRuleFiles()
+
+    if (ruleFiles.length === 0) {
+      return []
+    }
+
+    const allRules: RuleClass[] = []
+
+    for (const filePath of ruleFiles) {
+      const rules = await this.loadRuleFile(filePath)
+      allRules.push(...rules)
+    }
+
+    return allRules
+  }
+
+  /**
+   * Loads all custom rules and returns detailed information about each rule
+   */
+  async loadRulesWithInfo(): Promise<{ rules: RuleClass[], ruleInfo: Array<{ name: string, path: string }>, duplicateWarnings: string[] }> {
+    const ruleFiles = await this.discoverRuleFiles()
+
+    if (ruleFiles.length === 0) {
+      return { rules: [], ruleInfo: [], duplicateWarnings: [] }
+    }
+
+    const allRules: RuleClass[] = []
+    const ruleInfo: Array<{ name: string, path: string }> = []
+    const duplicateWarnings: string[] = []
+    const seenNames = new Map<string, string>()
+
+    for (const filePath of ruleFiles) {
+      const rules = await this.loadRuleFile(filePath)
+      for (const RuleClass of rules) {
+        const instance = new RuleClass()
+        const ruleName = instance.name
+
+        if (seenNames.has(ruleName)) {
+          const firstPath = seenNames.get(ruleName)!
+          duplicateWarnings.push(
+            `Custom rule "${ruleName}" is defined in multiple files: "${firstPath}" and "${filePath}". The later one will be used.`
+          )
+        } else {
+          seenNames.set(ruleName, filePath)
+        }
+
+        allRules.push(RuleClass)
+        ruleInfo.push({
+          name: ruleName,
+          path: filePath
+        })
+      }
+    }
+
+    return { rules: allRules, ruleInfo, duplicateWarnings }
+  }
+
+  /**
+   * Static helper to check if custom rules exist in a project
+   */
+  static async hasCustomRules(baseDir: string = process.cwd()): Promise<boolean> {
+    const loader = new CustomRuleLoader({ baseDir, silent: true })
+    const files = await loader.discoverRuleFiles()
+    return files.length > 0
+  }
+
+  /**
+   * Static helper to load custom rules and merge with default rules
+   */
+  static async loadAndMergeRules(
+    defaultRules: RuleClass[],
+    options: CustomRuleLoaderOptions = {}
+  ): Promise<RuleClass[]> {
+    const loader = new CustomRuleLoader(options)
+    const customRules = await loader.loadRules()
+
+    return [...defaultRules, ...customRules]
+  }
+}

package/src/herb-disable-comment-utils.ts

@@ -0,0 +1,175 @@
+/**
+ * Utilities for parsing herb:disable comments
+ */
+
+/**
+ * Information about a single rule name in a herb:disable comment
+ */
+export interface HerbDisableRuleName {
+  /** The rule name */
+  name: string
+  /** The starting offset of this rule name within the content/line */
+  offset: number
+  /** The length of the rule name */
+  length: number
+}
+
+/**
+ * Result of parsing a herb:disable comment
+ */
+export interface HerbDisableComment {
+  /** The full matched string */
+  match: string
+  /** Array of rule names specified in the comment */
+  ruleNames: string[]
+  /** Array of rule name information with positions */
+  ruleNameDetails: HerbDisableRuleName[]
+  /** The original rules string (e.g., "rule1, rule2") */
+  rulesString: string
+}
+
+/**
+ * Prefix for herb:disable comments
+ */
+const HERB_DISABLE_PREFIX = "herb:disable"
+
+/**
+ * Parse a herb:disable comment from ERB comment content.
+ * Use this when you have the content inside <%# ... %> (e.g., from ERBContentNode.content.value)
+ *
+ * @param content - The content string (without <%# %> delimiters)
+ * @returns Parsed comment data or null if not a valid herb:disable comment
+ *
+ * @example
+ * ```ts
+ * const result = parseHerbDisableContent("herb:disable rule1, rule2")
+ * // { match: "herb:disable rule1, rule2", ruleNames: ["rule1", "rule2"], rulesString: "rule1, rule2" }
+ * ```
+ */
+export function parseHerbDisableContent(content: string): HerbDisableComment | null {
+  const trimmed = content.trim()
+
+  if (!trimmed.startsWith(HERB_DISABLE_PREFIX)) return null
+
+  const afterPrefix = trimmed.substring(HERB_DISABLE_PREFIX.length).trimStart()
+  if (afterPrefix.length === 0) return null
+
+  const rulesString = afterPrefix.trimEnd()
+  const ruleNames = rulesString.split(',').map(name => name.trim())
+
+  if (ruleNames.some(name => name.length === 0)) return null
+  if (ruleNames.length === 0) return null
+
+  const herbDisablePrefix = content.indexOf(HERB_DISABLE_PREFIX)
+  const searchStart = herbDisablePrefix + HERB_DISABLE_PREFIX.length
+  const rulesStringOffset = content.indexOf(rulesString, searchStart)
+
+  const ruleNameDetails: HerbDisableRuleName[] = []
+
+  let currentOffset = 0
+
+  for (const ruleName of ruleNames) {
+    const ruleOffset = rulesString.indexOf(ruleName, currentOffset)
+
+    ruleNameDetails.push({
+      name: ruleName,
+      offset: rulesStringOffset + ruleOffset,
+      length: ruleName.length
+    })
+
+    currentOffset = ruleOffset + ruleName.length
+  }
+
+  return {
+    match: trimmed,
+    ruleNames,
+    ruleNameDetails,
+    rulesString
+  }
+}
+
+/**
+ * Parse a herb:disable comment from a full source line.
+ * Use this when you have a complete line that may contain <%# herb:disable ... %>
+ *
+ * @param line - The source line that may contain a herb:disable comment
+ * @returns Parsed comment data or null if not a valid herb:disable comment
+ *
+ * @example
+ * ```ts
+ * const result = parseHerbDisableLine("<div>test</div> <%# herb:disable rule1, rule2 %>")
+ * // { match: "<%# herb:disable rule1, rule2 %>", ruleNames: ["rule1", "rule2"], rulesString: "rule1, rule2" }
+ * ```
+ */
+export function parseHerbDisableLine(line: string): HerbDisableComment | null {
+  const startTag = "<%#"
+  const endTag = "%>"
+
+  const startIndex = line.indexOf(startTag)
+  if (startIndex === -1) return null
+
+  const endIndex = line.indexOf(endTag, startIndex)
+  if (endIndex === -1) return null
+
+  const content = line.substring(startIndex + startTag.length, endIndex).trim()
+
+  if (!content.startsWith(HERB_DISABLE_PREFIX)) return null
+
+  const afterPrefix = content.substring(HERB_DISABLE_PREFIX.length).trimStart()
+  if (afterPrefix.length === 0) return null
+
+  const rulesString = afterPrefix.trimEnd()
+  const ruleNames = rulesString.split(',').map(name => name.trim())
+
+  if (ruleNames.some(name => name.length === 0)) return null
+  if (ruleNames.length === 0) return null
+
+  const herbDisablePrefix = line.indexOf(HERB_DISABLE_PREFIX)
+  const searchStart = herbDisablePrefix + HERB_DISABLE_PREFIX.length
+  const rulesStringOffset = line.indexOf(rulesString, searchStart)
+
+  const ruleNameDetails: HerbDisableRuleName[] = []
+
+  let currentOffset = 0
+
+  for (const ruleName of ruleNames) {
+    const ruleOffset = rulesString.indexOf(ruleName, currentOffset)
+
+    ruleNameDetails.push({
+      name: ruleName,
+      offset: rulesStringOffset + ruleOffset,
+      length: ruleName.length
+    })
+
+    currentOffset = ruleOffset + ruleName.length
+  }
+
+  const fullMatch = line.substring(startIndex, endIndex + endTag.length)
+
+  return {
+    match: fullMatch,
+    ruleNames,
+    ruleNameDetails,
+    rulesString
+  }
+}
+
+/**
+ * Check if an ERB comment content contains a herb:disable directive.
+ *
+ * @param content - The content string (without <%# %> delimiters)
+ * @returns true if the content contains a herb:disable directive
+ */
+export function isHerbDisableContent(content: string): boolean {
+  return parseHerbDisableContent(content) !== null
+}
+
+/**
+ * Check if a source line contains a herb:disable comment.
+ *
+ * @param line - The source line
+ * @returns true if the line contains a herb:disable comment
+ */
+export function isHerbDisableLine(line: string): boolean {
+  return parseHerbDisableLine(line) !== null
+}