@herb-tools/linter 0.8.10 → 0.9.1

package/src/cli/file-processor.ts

@@ -3,13 +3,17 @@ import { Linter } from "../linter.js"
 import { loadCustomRules } from "../loader.js"
 import { Config } from "@herb-tools/config"
 
-import { readFileSync, writeFileSync } from "fs"
-import { resolve } from "path"
+import { Worker } from "node:worker_threads"
+import { readFileSync, writeFileSync } from "node:fs"
+import { resolve, dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { availableParallelism } from "node:os"
 import { colorize } from "@herb-tools/highlighter"
 
 import type { Diagnostic } from "@herb-tools/core"
 import type { FormatOption } from "./argument-parser.js"
 import type { HerbConfigOptions } from "@herb-tools/config"
+import type { WorkerInput, WorkerResult } from "./lint-worker.js"
 
 export interface ProcessedFile {
   filename: string
@@ -20,6 +24,7 @@ export interface ProcessedFile {
 
 export interface ProcessingContext {
   projectPath?: string
+  configPath?: string
   pattern?: string
   fix?: boolean
   fixUnsafe?: boolean
@@ -27,6 +32,7 @@ export interface ProcessingContext {
   linterConfig?: HerbConfigOptions['linter']
   config?: Config
   loadCustomRules?: boolean
+  jobs?: number
 }
 
 export interface ProcessingResult {
@@ -44,6 +50,13 @@ export interface ProcessingResult {
   context?: ProcessingContext
 }
 
+/**
+ * Minimum number of files required to use parallel processing.
+ * Below this threshold, sequential processing is faster due to
+ * worker thread startup overhead (loading WASM, config, etc.).
+ */
+const PARALLEL_FILE_THRESHOLD = 10
+
 export class FileProcessor {
   private linter: Linter | null = null
   private customRulesLoaded: boolean = false
@@ -51,18 +64,27 @@ export class FileProcessor {
   private isRuleAutocorrectable(ruleName: string): boolean {
     if (!this.linter) return false
 
-    const RuleClass = (this.linter as any).rules.find((rule: any) => {
-      const instance = new rule()
-
-      return instance.name === ruleName
-    })
+    const ruleClass = (this.linter as any).rules.find(
+      (rule: any) => rule.ruleName === ruleName
+    )
 
-    if (!RuleClass) return false
+    if (!ruleClass) return false
 
-    return RuleClass.autocorrectable === true
+    return ruleClass.autocorrectable === true
   }
 
   async processFiles(files: string[], formatOption: FormatOption = 'detailed', context?: ProcessingContext): Promise<ProcessingResult> {
+    const jobs = context?.jobs ?? 1
+    const shouldParallelize = jobs > 1 && files.length >= PARALLEL_FILE_THRESHOLD
+
+    if (shouldParallelize) {
+      return this.processFilesInParallel(files, jobs, formatOption, context)
+    }
+
+    return this.processFilesSequentially(files, formatOption, context)
+  }
+
+  private async processFilesSequentially(files: string[], formatOption: FormatOption = 'detailed', context?: ProcessingContext): Promise<ProcessingResult> {
     let totalErrors = 0
     let totalWarnings = 0
     let totalInfo = 0
@@ -147,7 +169,7 @@ export class FileProcessor {
           filesFixed++
 
           if (formatOption !== 'json') {
-            console.log(`${colorize("✓", "brightGreen")} ${colorize(filename, "cyan")} - ${colorize(`Fixed ${autofixResult.fixed.length} offense(s)`, "green")}`)
+            console.log(`${colorize("✓", "brightGreen")} ${colorize(filename, "cyan")} - ${colorize(`Fixed ${autofixResult.fixed.length} ${autofixResult.fixed.length === 1 ? "offense" : "offenses"}`, "green")}`)
           }
         }
 
@@ -225,4 +247,161 @@ export class FileProcessor {
 
     return result
   }
+
+  private async processFilesInParallel(files: string[], jobs: number, formatOption: FormatOption, context?: ProcessingContext): Promise<ProcessingResult> {
+    const workerCount = Math.min(jobs, files.length)
+    const chunks = this.splitIntoChunks(files, workerCount)
+    const workerPath = this.resolveWorkerPath()
+
+    const workerPromises = chunks.map(chunk => this.runWorker(workerPath, chunk, context))
+    const workerResults = await Promise.all(workerPromises)
+
+    for (const result of workerResults) {
+      if (result.error) {
+        throw new Error(`Worker error: ${result.error}`)
+      }
+    }
+
+    return this.aggregateWorkerResults(workerResults, formatOption, context)
+  }
+
+  private resolveWorkerPath(): string {
+    try {
+      const currentDir = dirname(fileURLToPath(import.meta.url))
+
+      return join(currentDir, "lint-worker.js")
+    } catch {
+      return join(__dirname, "lint-worker.js")
+    }
+  }
+
+  private splitIntoChunks(files: string[], chunkCount: number): string[][] {
+    const chunks: string[][] = Array.from({ length: chunkCount }, () => [])
+
+    for (let i = 0; i < files.length; i++) {
+      chunks[i % chunkCount].push(files[i])
+    }
+
+    return chunks.filter(chunk => chunk.length > 0)
+  }
+
+  private runWorker(workerPath: string, files: string[], context?: ProcessingContext): Promise<WorkerResult> {
+    return new Promise((resolve, reject) => {
+      const workerData: WorkerInput = {
+        files,
+        projectPath: context?.projectPath || process.cwd(),
+        configPath: context?.configPath,
+        fix: context?.fix || false,
+        fixUnsafe: context?.fixUnsafe || false,
+        ignoreDisableComments: context?.ignoreDisableComments || false,
+        loadCustomRules: context?.loadCustomRules || false,
+      }
+
+      const worker = new Worker(workerPath, { workerData })
+
+      worker.on("message", (result: WorkerResult) => {
+        resolve(result)
+      })
+
+      worker.on("error", (error) => {
+        reject(error)
+      })
+
+      worker.on("exit", (code) => {
+        if (code !== 0) {
+          reject(new Error(`Worker exited with code ${code}`))
+        }
+      })
+    })
+  }
+
+  private aggregateWorkerResults(results: WorkerResult[], formatOption: FormatOption, context?: ProcessingContext): ProcessingResult {
+    let totalErrors = 0
+    let totalWarnings = 0
+    let totalInfo = 0
+    let totalHints = 0
+    let totalIgnored = 0
+    let totalWouldBeIgnored = 0
+    let filesWithOffenses = 0
+    let filesFixed = 0
+    let ruleCount = 0
+
+    const allOffenses: ProcessedFile[] = []
+    const ruleOffenses = new Map<string, { count: number, files: Set<string> }>()
+
+    for (const result of results) {
+      totalErrors += result.totalErrors
+      totalWarnings += result.totalWarnings
+      totalInfo += result.totalInfo
+      totalHints += result.totalHints
+      totalIgnored += result.totalIgnored
+      totalWouldBeIgnored += result.totalWouldBeIgnored
+      filesWithOffenses += result.filesWithOffenses
+      filesFixed += result.filesFixed
+
+      if (result.ruleCount > 0) {
+        ruleCount = result.ruleCount
+      }
+
+      for (const offense of result.offenses) {
+        allOffenses.push({
+          filename: offense.filename,
+          offense: offense.offense,
+          content: offense.content,
+          autocorrectable: offense.autocorrectable
+        })
+      }
+
+      for (const [rule, data] of result.ruleOffenses) {
+        const existing = ruleOffenses.get(rule) || { count: 0, files: new Set<string>() }
+        existing.count += data.count
+
+        for (const file of data.files) {
+          existing.files.add(file)
+        }
+
+        ruleOffenses.set(rule, existing)
+      }
+
+      if (formatOption !== 'json') {
+        for (const fixMessage of result.fixMessages) {
+          const [filename, countStr] = fixMessage.split("\t")
+          const count = parseInt(countStr, 10)
+          console.log(`${colorize("\u2713", "brightGreen")} ${colorize(filename, "cyan")} - ${colorize(`Fixed ${count} ${count === 1 ? "offense" : "offenses"}`, "green")}`)
+        }
+      }
+    }
+
+    const processingResult: ProcessingResult = {
+      totalErrors,
+      totalWarnings,
+      totalInfo,
+      totalHints,
+      totalIgnored,
+      filesWithOffenses,
+      filesFixed,
+      ruleCount,
+      allOffenses,
+      ruleOffenses,
+      context
+    }
+
+    if (totalWouldBeIgnored > 0) {
+      processingResult.totalWouldBeIgnored = totalWouldBeIgnored
+    }
+
+    return processingResult
+  }
+
+  /**
+   * Returns the default number of parallel jobs based on available CPU cores.
+   * Returns 1 if parallelism detection fails.
+   */
+  static defaultJobs(): number {
+    try {
+      return availableParallelism()
+    } catch {
+      return 1
+    }
+  }
 }

package/src/cli/file-url.ts

@@ -0,0 +1,6 @@
+import { resolve } from "node:path"
+
+export function fileUrl(filePath: string): string {
+  const absolutePath = resolve(filePath)
+  return `file://${absolutePath}`
+}

package/src/cli/formatters/detailed-formatter.ts

@@ -2,6 +2,8 @@ import { colorize, Highlighter, type ThemeInput, DEFAULT_THEME } from "@herb-too
 
 import { BaseFormatter } from "./base-formatter.js"
 import { LineWrapper } from "@herb-tools/highlighter"
+import { ruleDocumentationUrl } from "../../urls.js"
+import { fileUrl } from "../file-url.js"
 
 import type { Diagnostic } from "@herb-tools/core"
 import type { ProcessedFile } from "../file-processor.js"
@@ -27,24 +29,24 @@ export class DetailedFormatter extends BaseFormatter {
       await this.highlighter.initialize()
     }
 
+    const correctableTag = colorize(colorize("[Correctable]", "green"), "bold")
+    const autocorrectableSet = new Set(
+      allOffenses.filter(item => item.autocorrectable).map(item => item.offense)
+    )
+
     if (isSingleFile) {
       const { filename, content } = allOffenses[0]
-      const diagnostics = allOffenses.map(item => {
-        if (item.autocorrectable && item.offense.code) {
-          return {
-            ...item.offense,
-            message: `${item.offense.message} ${colorize(colorize("[Correctable]", "green"), "bold")}`
-          }
-        }
-        return item.offense
-      })
+      const diagnostics = allOffenses.map(item => item.offense)
 
       const highlighted = this.highlighter.highlight(filename, content, {
         diagnostics: diagnostics,
         splitDiagnostics: true,
         contextLines: 2,
         wrapLines: this.wrapLines,
-        truncateLines: this.truncateLines
+        truncateLines: this.truncateLines,
+        codeUrlBuilder: ruleDocumentationUrl,
+        fileUrlBuilder: (path) => fileUrl(path),
+        suffixBuilder: (diagnostic) => autocorrectableSet.has(diagnostic) ? correctableTag : undefined,
       })
 
       console.log(`\n${highlighted}`)
@@ -54,19 +56,15 @@ export class DetailedFormatter extends BaseFormatter {
       for (let i = 0; i < allOffenses.length; i++) {
         const { filename, offense, content, autocorrectable } = allOffenses[i]
 
-        let modifiedOffense = offense
-
-        if (autocorrectable && offense.code) {
-          modifiedOffense = {
-            ...offense,
-            message: `${offense.message} ${colorize(colorize("[Correctable]", "green"), "bold")}`
-          }
-        }
-
-        const formatted = this.highlighter.highlightDiagnostic(filename, modifiedOffense, content, {
+        const codeUrl = offense.code ? ruleDocumentationUrl(offense.code) : undefined
+        const suffix = autocorrectable ? correctableTag : undefined
+        const formatted = this.highlighter.highlightDiagnostic(filename, offense, content, {
           contextLines: 2,
           wrapLines: this.wrapLines,
-          truncateLines: this.truncateLines
+          truncateLines: this.truncateLines,
+          codeUrl,
+          fileUrl: fileUrl(filename),
+          suffix,
         })
         console.log(`\n${formatted}`)
 

package/src/cli/formatters/simple-formatter.ts

@@ -1,6 +1,8 @@
-import { colorize } from "@herb-tools/highlighter"
+import { colorize, hyperlink, TextFormatter } from "@herb-tools/highlighter"
 
 import { BaseFormatter } from "./base-formatter.js"
+import { ruleDocumentationUrl } from "../../urls.js"
+import { fileUrl } from "../file-url.js"
 
 import type { Diagnostic } from "@herb-tools/core"
 import type { ProcessedFile } from "../file-processor.js"
@@ -24,33 +26,41 @@ export class SimpleFormatter extends BaseFormatter {
   }
 
   formatFile(filename: string, offenses: Diagnostic[]): void {
-    console.log(`${colorize(filename, "cyan")}:`)
+    const filenameText = colorize(filename, "cyan")
+    const filenameLink = hyperlink(filenameText, fileUrl(filename))
+    console.log(`${filenameLink}:`)
 
     for (const offense of offenses) {
       const isError = offense.severity === "error"
       const severity = isError ? colorize("✗", "brightRed") : colorize("⚠", "brightYellow")
-      const rule = colorize(`(${offense.code})`, "blue")
-      const locationString = `${offense.location.start.line}:${offense.location.start.column}`
-      const paddedLocation = locationString.padEnd(4)
+      const ruleText = `(${offense.code})`
+      const rule = offense.code ? hyperlink(ruleText, ruleDocumentationUrl(offense.code)) : ruleText
+      const { line, column } = offense.location.start
+      const locationString = `${line}:${column}`
+      const paddedLocation = colorize(locationString.padEnd(4), "gray")
+      const message = TextFormatter.highlightBackticks(offense.message)
 
-      console.log(`  ${colorize(paddedLocation, "gray")} ${severity} ${offense.message} ${rule}`)
+      console.log(`  ${paddedLocation} ${severity} ${message} ${rule}`)
     }
-    console.log("")
   }
 
   formatFileProcessed(filename: string, processedFiles: ProcessedFile[]): void {
-    console.log(`${colorize(filename, "cyan")}:`)
+    const filenameText = colorize(filename, "cyan")
+    const filenameLink = hyperlink(filenameText, fileUrl(filename))
+    console.log(`${filenameLink}:`)
 
     for (const { offense, autocorrectable } of processedFiles) {
       const isError = offense.severity === "error"
       const severity = isError ? colorize("✗", "brightRed") : colorize("⚠", "brightYellow")
-      const rule = colorize(`(${offense.code})`, "blue")
-      const locationString = `${offense.location.start.line}:${offense.location.start.column}`
-      const paddedLocation = locationString.padEnd(4)
+      const ruleText = `(${offense.code})`
+      const rule = offense.code ? hyperlink(ruleText, ruleDocumentationUrl(offense.code)) : ruleText
+      const { line, column } = offense.location.start
+      const locationString = `${line}:${column}`
+      const paddedLocation = colorize(locationString.padEnd(4), "gray")
       const correctable = autocorrectable ? colorize(colorize(" [Correctable]", "green"), "bold") : ""
+      const message = TextFormatter.highlightBackticks(offense.message)
 
-      console.log(`  ${colorize(paddedLocation, "gray")} ${severity} ${offense.message} ${rule}${correctable}`)
+      console.log(`  ${paddedLocation} ${severity} ${message} ${rule}${correctable}`)
     }
-    console.log("")
   }
 }

package/src/cli/index.ts

@@ -3,4 +3,6 @@ export { FileProcessor } from "./file-processor.js"
 export { SummaryReporter } from "./summary-reporter.js"
 export { OutputManager } from "./output-manager.js"
 
+export type { WorkerInput, WorkerResult, WorkerOffense } from "./lint-worker.js"
+
 export * from "./formatters/index.js"

package/src/cli/lint-worker.ts

@@ -0,0 +1,208 @@
+import { workerData, parentPort } from "node:worker_threads"
+import { readFileSync, writeFileSync } from "node:fs"
+import { resolve } from "node:path"
+
+import { Herb } from "@herb-tools/node-wasm"
+import { Config } from "@herb-tools/config"
+
+import { Diagnostic } from "@herb-tools/core"
+import { Linter } from "../linter.js"
+import { loadCustomRules } from "../loader.js"
+
+export interface WorkerInput {
+  files: string[]
+  projectPath: string
+  configPath?: string
+  fix: boolean
+  fixUnsafe: boolean
+  ignoreDisableComments: boolean
+  loadCustomRules: boolean
+}
+
+export interface WorkerOffense {
+  filename: string
+  offense: Diagnostic
+  content: string
+  autocorrectable: boolean
+}
+
+export interface WorkerResult {
+  totalErrors: number
+  totalWarnings: number
+  totalInfo: number
+  totalHints: number
+  totalIgnored: number
+  totalWouldBeIgnored: number
+  filesWithOffenses: number
+  filesFixed: number
+  ruleCount: number
+  offenses: WorkerOffense[]
+  ruleOffenses: [string, { count: number, files: string[] }][]
+  fixMessages: string[]
+  error?: string
+}
+
+async function run() {
+  const data = workerData as WorkerInput
+
+  await Herb.load()
+
+  const config = await Config.load(data.configPath || data.projectPath, {
+    exitOnError: false,
+    createIfMissing: false,
+    silent: true
+  })
+
+  let customRules = undefined
+
+  if (data.loadCustomRules) {
+    try {
+      const result = await loadCustomRules({ baseDir: data.projectPath, silent: true })
+      customRules = result.rules
+    } catch {
+      // Silently ignore custom rule loading failures in workers
+    }
+  }
+
+  const linter = Linter.from(Herb, config, customRules)
+
+  let totalErrors = 0
+  let totalWarnings = 0
+  let totalInfo = 0
+  let totalHints = 0
+  let totalIgnored = 0
+  let totalWouldBeIgnored = 0
+  let filesWithOffenses = 0
+  let filesFixed = 0
+
+  const ruleCount = linter.getRuleCount()
+  const allOffenses: WorkerOffense[] = []
+  const ruleOffenses = new Map<string, { count: number, files: Set<string> }>()
+  const fixMessages: string[] = []
+
+  const isRuleAutocorrectable = (ruleName: string): boolean => {
+    const ruleClass = linter.rules.find(
+      (rule) => rule.ruleName === ruleName
+    )
+
+    if (!ruleClass) return false
+
+    // TODO: fix types
+    return (ruleClass as any).autocorrectable === true
+  }
+
+  for (const filename of data.files) {
+    const filePath = data.projectPath ? resolve(data.projectPath, filename) : resolve(filename)
+    let content = readFileSync(filePath, "utf-8")
+
+    const lintResult = linter.lint(content, {
+      fileName: filename,
+      ignoreDisableComments: data.ignoreDisableComments
+    })
+
+    if (data.fix && lintResult.offenses.length > 0) {
+      const autofixResult = linter.autofix(content, {
+        fileName: filename,
+        ignoreDisableComments: data.ignoreDisableComments
+      }, undefined, { includeUnsafe: data.fixUnsafe })
+
+      if (autofixResult.fixed.length > 0) {
+        writeFileSync(filePath, autofixResult.source, "utf-8")
+        filesFixed++
+        fixMessages.push(`${filename}\t${autofixResult.fixed.length}`)
+      }
+
+      content = autofixResult.source
+
+      for (const offense of autofixResult.unfixed) {
+        allOffenses.push({
+          filename,
+          offense,
+          content,
+          autocorrectable: isRuleAutocorrectable(offense.rule)
+        })
+
+        const ruleData = ruleOffenses.get(offense.rule) || { count: 0, files: new Set() }
+        ruleData.count++
+        ruleData.files.add(filename)
+        ruleOffenses.set(offense.rule, ruleData)
+      }
+
+      if (autofixResult.unfixed.length > 0) {
+        totalErrors += autofixResult.unfixed.filter(o => o.severity === "error").length
+        totalWarnings += autofixResult.unfixed.filter(o => o.severity === "warning").length
+        totalInfo += autofixResult.unfixed.filter(o => o.severity === "info").length
+        totalHints += autofixResult.unfixed.filter(o => o.severity === "hint").length
+        filesWithOffenses++
+      }
+    } else if (lintResult.offenses.length > 0) {
+      for (const offense of lintResult.offenses) {
+        allOffenses.push({
+          filename,
+          offense,
+          content,
+          autocorrectable: isRuleAutocorrectable(offense.rule)
+        })
+
+        const ruleData = ruleOffenses.get(offense.rule) || { count: 0, files: new Set() }
+        ruleData.count++
+        ruleData.files.add(filename)
+        ruleOffenses.set(offense.rule, ruleData)
+      }
+
+      totalErrors += lintResult.errors
+      totalWarnings += lintResult.warnings
+      totalInfo += lintResult.offenses.filter(o => o.severity === "info").length
+      totalHints += lintResult.offenses.filter(o => o.severity === "hint").length
+      filesWithOffenses++
+    }
+
+    totalIgnored += lintResult.ignored
+
+    if (lintResult.wouldBeIgnored) {
+      totalWouldBeIgnored += lintResult.wouldBeIgnored
+    }
+  }
+
+  const serializedRuleOffenses: [string, { count: number, files: string[] }][] =
+    Array.from(ruleOffenses.entries()).map(
+      ([rule, data]) => [rule, { count: data.count, files: Array.from(data.files) }]
+    )
+
+  const result: WorkerResult = {
+    totalErrors,
+    totalWarnings,
+    totalInfo,
+    totalHints,
+    totalIgnored,
+    totalWouldBeIgnored,
+    filesWithOffenses,
+    filesFixed,
+    ruleCount,
+    offenses: allOffenses,
+    ruleOffenses: serializedRuleOffenses,
+    fixMessages
+  }
+
+  parentPort!.postMessage(result)
+}
+
+run().catch(error => {
+  const errorResult: WorkerResult = {
+    totalErrors: 0,
+    totalWarnings: 0,
+    totalInfo: 0,
+    totalHints: 0,
+    totalIgnored: 0,
+    totalWouldBeIgnored: 0,
+    filesWithOffenses: 0,
+    filesFixed: 0,
+    ruleCount: 0,
+    offenses: [],
+    ruleOffenses: [],
+    fixMessages: [],
+    error: error instanceof Error ? error.message : String(error)
+  }
+
+  parentPort!.postMessage(errorResult)
+})