\` tags. Consider using semantic HTML elements like \`
\`, \`\`, \`\`, \`\`, \`\`, \`\`, or \`\` instead.`,
+ node.tag_name.location
+ )
+ }
+}
+
+export default class NoDivTagsRule extends ParserRule {
+ name = "no-div-tags"
+
+ check(result, context) {
+ const visitor = new NoDivTagsVisitor(this.name, context)
+ visitor.visit(result.value)
+ return visitor.offenses
+ }
+}
+```
+
+```js [.herb/rules/no-inline-styles.mjs]
+import { BaseRuleVisitor, getAttributes, getAttributeName } from "@herb-tools/linter"
+
+class NoInlineStylesVisitor extends BaseRuleVisitor {
+ visitHTMLOpenTagNode(node) {
+ const attributes = getAttributes(node)
+
+ for (const attribute of attributes) {
+ const attributeName = getAttributeName(attribute)
+
+ if (attributeName === "style") {
+ this.addOffense(
+ `Avoid using inline \`style\` attributes. Use CSS classes instead.`,
+ attribute.location,
+ "warning"
+ )
+ }
+ }
+
+ super.visitHTMLOpenTagNode(node)
+ }
+}
+
+export default class NoInlineStylesRule {
+ name = "no-inline-styles"
+
+ check(parseResult, context) {
+ const visitor = new NoInlineStylesVisitor(this.name, context)
+ visitor.visit(parseResult.value)
+ return visitor.offenses
+ }
+}
+```
+
+:::
+
+**Rule Configuration:**
+
+The `defaultConfig` getter is optional. If not specified, custom rules default to:
+- `enabled: true` - Rule is enabled by default
+- `severity: "error"` - Offenses are reported as errors
+- `exclude: []` - No files are excluded
+
+You can override the `defaultConfig` getter to customize these defaults, as shown in the example above where severity is set to `"warning"`.
+
+**Rule Properties:**
+
+- `static type` - Optional, defaults to `"parser"`. Can be `"parser"`, `"lexer"`, or `"source"`
+- `name` - Required, the rule identifier used in configuration and output
+- `check()` - Required, the method that checks for offenses
+- `defaultConfig` - Optional, returns the default configuration for the rule
+- `isEnabled()` - Optional, dynamically determines if the rule should run
+- `autofix()` - Optional, implements automatic fixing for the rule
+
+Custom rules are loaded automatically by default. Use `--no-custom-rules` to disable them.
+
+When custom rules are loaded, the linter will display them:
+
+```
+Loaded 2 custom rules:
+ • no-inline-styles (.herb/rules/no-inline-styles.mjs)
+ • require-aria-labels (.herb/rules/require-aria-labels.mjs)
+```
+
+::: warning Rule Name Clashes
+If a custom rule has the same name as a built-in rule or another custom rule, you'll see a warning. The custom rule will override the built-in rule.
+:::
+
+::: tip Hot Reload
+Custom rules are automatically reloaded when changed in editors with the Herb Language Server. No need to restart your editor!
+:::
+
### Language Server Integration
The linter is automatically integrated into the [Herb Language Server](https://herb-tools.dev/projects/language-server), providing real-time validation in supported editors like VS Code, Zed, and Neovim.
diff --git a/javascript/packages/linter/package.json b/javascript/packages/linter/package.json
index d50f79d10..9ad5baf04 100644
--- a/javascript/packages/linter/package.json
+++ b/javascript/packages/linter/package.json
@@ -36,6 +36,12 @@
"types": "./dist/types/src/cli.d.ts",
"require": "./dist/src/cli.js",
"default": "./dist/src/cli.js"
+ },
+ "./loader": {
+ "types": "./dist/types/loader.d.ts",
+ "import": "./dist/loader.js",
+ "require": "./dist/loader.cjs",
+ "default": "./dist/loader.js"
}
},
"dependencies": {
diff --git a/javascript/packages/linter/rollup.config.mjs b/javascript/packages/linter/rollup.config.mjs
index 4a21c39c8..05246e288 100644
--- a/javascript/packages/linter/rollup.config.mjs
+++ b/javascript/packages/linter/rollup.config.mjs
@@ -82,4 +82,44 @@ export default [
}),
],
},
+
+ // Loader entry point (includes custom rule loader)
+ {
+ input: "src/loader.ts",
+ output: {
+ file: "dist/loader.js",
+ format: "esm",
+ sourcemap: true,
+ },
+ external,
+ plugins: [
+ nodeResolve({ preferBuiltins: true }),
+ commonjs(),
+ json(),
+ typescript({
+ tsconfig: "./tsconfig.json",
+ declaration: true,
+ declarationDir: "./dist/types",
+ rootDir: "src/",
+ }),
+ ],
+ },
+ {
+ input: "src/loader.ts",
+ output: {
+ file: "dist/loader.cjs",
+ format: "cjs",
+ sourcemap: true,
+ },
+ external,
+ plugins: [
+ nodeResolve({ preferBuiltins: true }),
+ commonjs(),
+ json(),
+ typescript({
+ tsconfig: "./tsconfig.json",
+ rootDir: "src/",
+ }),
+ ],
+ },
]
diff --git a/javascript/packages/linter/src/cli.ts b/javascript/packages/linter/src/cli.ts
index b0af673ba..2a985759a 100644
--- a/javascript/packages/linter/src/cli.ts
+++ b/javascript/packages/linter/src/cli.ts
@@ -141,7 +141,7 @@ export class CLI {
const startTime = Date.now()
const startDate = new Date()
- let { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, ignoreDisableComments, force, init } = 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(patterns)
@@ -247,7 +247,8 @@ export class CLI {
fix,
ignoreDisableComments,
linterConfig,
- config: processingConfig
+ config: processingConfig,
+ loadCustomRules
}
const results = await this.fileProcessor.processFiles(files, formatOption, context)
diff --git a/javascript/packages/linter/src/cli/argument-parser.ts b/javascript/packages/linter/src/cli/argument-parser.ts
index dd703bcdb..bac1c6529 100644
--- a/javascript/packages/linter/src/cli/argument-parser.ts
+++ b/javascript/packages/linter/src/cli/argument-parser.ts
@@ -23,6 +23,7 @@ export interface ParsedArguments {
ignoreDisableComments: boolean
force: boolean
init: boolean
+ loadCustomRules: boolean
}
export class ArgumentParser {
@@ -46,6 +47,7 @@ export class ArgumentParser {
--json use JSON output format (shortcut for --format json)
--github enable GitHub Actions annotations (combines with --format)
--no-github disable GitHub Actions annotations (even in GitHub Actions environment)
+ --no-custom-rules disable loading custom rules from project (custom rules are loaded by default from .herb/rules/**/*.{mjs,js})
--theme syntax highlighting theme (${THEME_NAMES.join("|")}) or path to custom theme file [default: ${DEFAULT_THEME}]
--no-color disable colored output
--no-timing hide timing information
@@ -73,7 +75,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" },
+ "no-custom-rules": { type: "boolean" }
},
allowPositionals: true
})
@@ -139,8 +142,9 @@ export class ArgumentParser {
const ignoreDisableComments = values["ignore-disable-comments"] || false
const configFile = values["config-file"]
const init = values.init || false
+ const loadCustomRules = !values["no-custom-rules"]
- return { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, ignoreDisableComments, force, init }
+ return { patterns, configFile, formatOption, showTiming, theme, wrapLines, truncateLines, useGitHubActions, fix, ignoreDisableComments, force, init, loadCustomRules }
}
private getFilePatterns(positionals: string[]): string[] {
diff --git a/javascript/packages/linter/src/cli/file-processor.ts b/javascript/packages/linter/src/cli/file-processor.ts
index 82d13ffa8..f675930d7 100644
--- a/javascript/packages/linter/src/cli/file-processor.ts
+++ b/javascript/packages/linter/src/cli/file-processor.ts
@@ -1,5 +1,6 @@
import { Herb } from "@herb-tools/node-wasm"
import { Linter } from "../linter.js"
+import { loadCustomRules } from "../loader.js"
import { Config } from "@herb-tools/config"
import { readFileSync, writeFileSync } from "fs"
@@ -24,6 +25,7 @@ export interface ProcessingContext {
ignoreDisableComments?: boolean
linterConfig?: HerbConfigOptions['linter']
config?: Config
+ loadCustomRules?: boolean
}
export interface ProcessingResult {
@@ -43,6 +45,7 @@ export interface ProcessingResult {
export class FileProcessor {
private linter: Linter | null = null
+ private customRulesLoaded: boolean = false
private isRuleAutocorrectable(ruleName: string): boolean {
if (!this.linter) return false
@@ -68,17 +71,60 @@ export class FileProcessor {
let filesWithOffenses = 0
let filesFixed = 0
let ruleCount = 0
+
const allOffenses: ProcessedFile[] = []
const ruleOffenses = new Map }>()
+ if (!this.linter) {
+ let customRules = undefined
+ let customRuleInfo: Array<{ name: string, path: string }> = []
+ let customRuleWarnings: string[] = []
+
+ if (context?.loadCustomRules && !this.customRulesLoaded) {
+ try {
+ const result = await loadCustomRules({
+ baseDir: context.projectPath,
+ silent: formatOption === 'json'
+ })
+
+ customRules = result.rules
+ customRuleInfo = result.ruleInfo
+ customRuleWarnings = result.warnings
+
+ this.customRulesLoaded = true
+
+ if (customRules.length > 0 && formatOption !== 'json') {
+ const ruleText = customRules.length === 1 ? 'rule' : 'rules'
+ console.log(colorize(`\nLoaded ${customRules.length} custom ${ruleText}:`, "green"))
+
+ for (const { name, path } of customRuleInfo) {
+ const relativePath = context.projectPath ? path.replace(context.projectPath + '/', '') : path
+ console.log(colorize(` • ${name}`, "cyan") + colorize(` (${relativePath})`, "dim"))
+ }
+
+ if (customRuleWarnings.length > 0) {
+ console.log()
+ for (const warning of customRuleWarnings) {
+ console.warn(colorize(` ⚠ ${warning}`, "yellow"))
+ }
+ }
+
+ console.log()
+ }
+ } catch (error) {
+ if (formatOption !== 'json') {
+ console.warn(colorize(`Warning: Failed to load custom rules: ${error}`, "yellow"))
+ }
+ }
+ }
+
+ this.linter = Linter.from(Herb, context?.config, customRules)
+ }
+
for (const filename of files) {
const filePath = context?.projectPath ? resolve(context.projectPath, filename) : resolve(filename)
let content = readFileSync(filePath, "utf-8")
- if (!this.linter) {
- this.linter = Linter.from(Herb, context?.config)
- }
-
const lintResult = this.linter.lint(content, {
fileName: filename,
ignoreDisableComments: context?.ignoreDisableComments
diff --git a/javascript/packages/linter/src/custom-rule-loader.ts b/javascript/packages/linter/src/custom-rule-loader.ts
new file mode 100644
index 000000000..182da84e9
--- /dev/null
+++ b/javascript/packages/linter/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 {
+ 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 {
+ 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 {
+ 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()
+
+ 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 {
+ 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 {
+ const loader = new CustomRuleLoader(options)
+ const customRules = await loader.loadRules()
+
+ return [...defaultRules, ...customRules]
+ }
+}
diff --git a/javascript/packages/linter/src/linter.ts b/javascript/packages/linter/src/linter.ts
index ddd418c82..1ef5833c9 100644
--- a/javascript/packages/linter/src/linter.ts
+++ b/javascript/packages/linter/src/linter.ts
@@ -7,13 +7,45 @@ import { findNodeByLocation } from "./rules/rule-utils.js"
import { parseHerbDisableLine } from "./herb-disable-comment-utils.js"
import { ParserNoErrorsRule } from "./rules/parser-no-errors.js"
+import { DEFAULT_RULE_CONFIG } from "./types.js"
import type { RuleClass, Rule, ParserRule, LexerRule, SourceRule, LintResult, LintOffense, UnboundLintOffense, LintContext, AutofixResult } from "./types.js"
import type { ParseResult, LexResult, HerbBackend } from "@herb-tools/core"
import type { RuleConfig, Config } from "@herb-tools/config"
+export interface LinterOptions {
+ /**
+ * Array of rule classes to use. If not provided, uses default rules.
+ */
+ rules?: RuleClass[]
+
+ /**
+ * Whether to load custom rules from the project.
+ * Defaults to false for backward compatibility.
+ */
+ loadCustomRules?: boolean
+
+ /**
+ * Base directory to search for custom rules.
+ * Defaults to current working directory.
+ */
+ customRulesBaseDir?: string
+
+ /**
+ * Custom glob patterns to search for rule files.
+ */
+ customRulesPatterns?: string[]
+
+ /**
+ * Whether to suppress custom rule loading errors.
+ * Defaults to false.
+ */
+ silentCustomRules?: boolean
+}
+
export class Linter {
protected rules: RuleClass[]
+ protected allAvailableRules: RuleClass[]
protected herb: HerbBackend
protected offenses: LintOffense[]
protected config?: Config
@@ -23,14 +55,16 @@ export class Linter {
*
* @param herb - The Herb backend instance for parsing and lexing
* @param config - Optional full Config instance for rule filtering, severity overrides, and path-based filtering
+ * @param customRules - Optional array of custom rules to include alongside built-in rules
* @returns A configured Linter instance
*/
- static from(herb: HerbBackend, config?: Config): Linter {
+ static from(herb: HerbBackend, config?: Config, customRules?: RuleClass[]): Linter {
+ const allRules = customRules ? [...rules, ...customRules] : rules
const filteredRules = config?.linter?.rules
- ? Linter.filterRulesByConfig(rules, config.linter.rules)
+ ? Linter.filterRulesByConfig(allRules, config.linter.rules)
: undefined
- return new Linter(herb, filteredRules, config)
+ return new Linter(herb, filteredRules, config, allRules)
}
/**
@@ -42,11 +76,13 @@ export class Linter {
* @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.
* @param config - Optional full Config instance for severity overrides and path-based rule filtering
+ * @param allAvailableRules - Optional array of ALL available rules (including disabled) for herb:disable validation
*/
- constructor(herb: HerbBackend, rules?: RuleClass[], config?: Config) {
+ constructor(herb: HerbBackend, rules?: RuleClass[], config?: Config, allAvailableRules?: RuleClass[]) {
this.herb = herb
this.config = config
this.rules = rules !== undefined ? rules : this.getDefaultRules()
+ this.allAvailableRules = allAvailableRules !== undefined ? allAvailableRules : this.rules
this.offenses = []
}
@@ -69,7 +105,7 @@ export class Linter {
const instance = new ruleClass()
const ruleName = instance.name
- const defaultEnabled = instance.defaultConfig.enabled
+ const defaultEnabled = instance.defaultConfig?.enabled ?? DEFAULT_RULE_CONFIG.enabled
const userRuleConfig = userRulesConfig?.[ruleName]
if (userRuleConfig !== undefined) {
@@ -93,10 +129,11 @@ export class Linter {
/**
* Returns all available rule classes that can be referenced in herb:disable comments.
* This includes all rules that exist, regardless of whether they're currently enabled.
+ * Includes both built-in rules and any loaded custom rules.
* @returns Array of all available rule classes
*/
protected getAvailableRules(): RuleClass[] {
- return rules
+ return this.allAvailableRules
}
/**
@@ -150,7 +187,7 @@ export class Linter {
}
if (context?.fileName && !this.config?.linter?.rules?.[rule.name]?.exclude) {
- const defaultExclude = rule.defaultConfig.exclude
+ const defaultExclude = rule.defaultConfig?.exclude ?? DEFAULT_RULE_CONFIG.exclude
if (defaultExclude && defaultExclude.length > 0) {
const isExcluded = defaultExclude.some((pattern: string) => minimatch(context.fileName!, pattern))
@@ -392,7 +429,7 @@ export class Linter {
}
const ruleInstance = new RuleClass()
- const defaultSeverity = ruleInstance.defaultConfig.severity
+ const defaultSeverity = ruleInstance.defaultConfig?.severity ?? DEFAULT_RULE_CONFIG.severity
const userRuleConfig = this.config?.linter?.rules?.[ruleName]
const severity = userRuleConfig?.severity ?? defaultSeverity
diff --git a/javascript/packages/linter/src/loader.ts b/javascript/packages/linter/src/loader.ts
new file mode 100644
index 000000000..d9d222770
--- /dev/null
+++ b/javascript/packages/linter/src/loader.ts
@@ -0,0 +1,30 @@
+export * from "./index.js"
+
+export { CustomRuleLoader } from "./custom-rule-loader.js"
+export type { CustomRuleLoaderOptions } from "./custom-rule-loader.js"
+
+import { CustomRuleLoader } from "./custom-rule-loader.js"
+import type { RuleClass } from "./types.js"
+
+/**
+ * Loads custom rules from the filesystem.
+ * Only available in Node.js environments.
+ */
+export async function loadCustomRules(options?: {
+ baseDir?: string
+ patterns?: string[]
+ silent?: boolean
+}): Promise<{
+ rules: RuleClass[]
+ ruleInfo: Array<{ name: string, path: string }>
+ warnings: string[]
+}> {
+ const loader = new CustomRuleLoader(options)
+ const { rules: customRules, ruleInfo, duplicateWarnings } = await loader.loadRulesWithInfo()
+
+ return {
+ rules: customRules,
+ ruleInfo,
+ warnings: duplicateWarnings
+ }
+}
diff --git a/javascript/packages/linter/src/types.ts b/javascript/packages/linter/src/types.ts
index 8f24469c1..3ac7fe4bc 100644
--- a/javascript/packages/linter/src/types.ts
+++ b/javascript/packages/linter/src/types.ts
@@ -68,6 +68,16 @@ export interface AutofixResult[]
}
+/**
+ * Default configuration for rules when defaultConfig is not specified.
+ * Custom rules can omit defaultConfig and will use these defaults.
+ */
+export const DEFAULT_RULE_CONFIG: FullRuleConfig = {
+ enabled: true,
+ severity: "error",
+ exclude: []
+}
+
/**
* Base class for parser rules.
*/
@@ -77,7 +87,9 @@ export abstract class ParserRule): UnboundLintOffense[]
/**
@@ -109,7 +121,9 @@ export abstract class LexerRule): UnboundLintOffense[]
/**
@@ -164,7 +178,9 @@ export abstract class SourceRule): UnboundLintOffense[]
/**
diff --git a/javascript/packages/linter/test/rules/herb-disable-comment-unnecessary.test.ts b/javascript/packages/linter/test/rules/herb-disable-comment-unnecessary.test.ts
index a43c9919b..d0737addb 100644
--- a/javascript/packages/linter/test/rules/herb-disable-comment-unnecessary.test.ts
+++ b/javascript/packages/linter/test/rules/herb-disable-comment-unnecessary.test.ts
@@ -6,11 +6,13 @@ import { createLinterTest } from "../helpers/linter-test-helper.js"
import { HerbDisableCommentUnnecessaryRule } from "../../src/rules/herb-disable-comment-unnecessary.js"
import { HTMLTagNameLowercaseRule } from "../../src/rules/html-tag-name-lowercase.js"
import { HTMLAttributeDoubleQuotesRule } from "../../src/rules/html-attribute-double-quotes.js"
+import { ERBCommentSyntax } from "../../src/rules/erb-comment-syntax.js"
const { expectNoOffenses, expectWarning, assertOffenses } = createLinterTest([
HerbDisableCommentUnnecessaryRule,
HTMLTagNameLowercaseRule,
HTMLAttributeDoubleQuotesRule,
+ ERBCommentSyntax,
])
describe("HerbDisableCommentUnnecessaryRule", () => {
diff --git a/javascript/packages/linter/test/rules/herb-disable-comment-valid-rule-name.test.ts b/javascript/packages/linter/test/rules/herb-disable-comment-valid-rule-name.test.ts
index 29c750423..77069a9ce 100644
--- a/javascript/packages/linter/test/rules/herb-disable-comment-valid-rule-name.test.ts
+++ b/javascript/packages/linter/test/rules/herb-disable-comment-valid-rule-name.test.ts
@@ -1,9 +1,13 @@
import dedent from "dedent"
import { describe, test } from "vitest"
import { HerbDisableCommentValidRuleNameRule } from "../../src/rules/herb-disable-comment-valid-rule-name.js"
+import { ERBCommentSyntax } from "../../src/rules/erb-comment-syntax.js"
import { createLinterTest } from "../helpers/linter-test-helper.js"
-const { expectNoOffenses, expectWarning, assertOffenses } = createLinterTest(HerbDisableCommentValidRuleNameRule)
+const { expectNoOffenses, expectWarning, assertOffenses } = createLinterTest([
+ HerbDisableCommentValidRuleNameRule,
+ ERBCommentSyntax,
+])
describe("HerbDisableCommentValidRuleNameRule", () => {
test("allows valid single rule name", () => {
@@ -25,7 +29,7 @@ describe("HerbDisableCommentValidRuleNameRule", () => {
})
test("warns on unknown single rule name", () => {
- expectWarning("Unknown rule `this-rule-doesnt-exist`. Did you mean `erb-no-empty-tags`?")
+ expectWarning("Unknown rule `this-rule-doesnt-exist`. Did you mean `erb-comment-syntax`?")
assertOffenses(dedent`
test
<%# herb:disable this-rule-doesnt-exist %>
diff --git a/javascript/packages/linter/test/rules/herb-disable-precise-locations.test.ts b/javascript/packages/linter/test/rules/herb-disable-precise-locations.test.ts
index e7c6ae2b7..643edfa08 100644
--- a/javascript/packages/linter/test/rules/herb-disable-precise-locations.test.ts
+++ b/javascript/packages/linter/test/rules/herb-disable-precise-locations.test.ts
@@ -6,6 +6,8 @@ import { Linter } from "../../src/linter.js"
import { HerbDisableCommentValidRuleNameRule } from "../../src/rules/herb-disable-comment-valid-rule-name.js"
import { HerbDisableCommentNoRedundantAllRule } from "../../src/rules/herb-disable-comment-no-redundant-all.js"
+import { HTMLTagNameLowercaseRule } from "../../src/rules/html-tag-name-lowercase.js"
+import { HTMLAttributeDoubleQuotesRule } from "../../src/rules/html-attribute-double-quotes.js"
describe("Herb Disable Comment Precise Locations", () => {
beforeAll(async () => {
@@ -37,7 +39,11 @@ describe("Herb Disable Comment Precise Locations", () => {
test
<%# herb:disable html-tag-name-lowercase, invalid-rule, html-attribute-double-quotes %>
`
- const linter = new Linter(Herb, [HerbDisableCommentValidRuleNameRule])
+ const linter = new Linter(Herb, [
+ HerbDisableCommentValidRuleNameRule,
+ HTMLTagNameLowercaseRule,
+ HTMLAttributeDoubleQuotesRule,
+ ])
const result = linter.lint(html)
expect(result.offenses).toHaveLength(1)
diff --git a/javascript/packages/rewriter/README.md b/javascript/packages/rewriter/README.md
index a61e7ebc7..135a43e44 100644
--- a/javascript/packages/rewriter/README.md
+++ b/javascript/packages/rewriter/README.md
@@ -201,9 +201,49 @@ export default class AddTrailingNewline extends StringRewriter {
### Using Custom Rewriters
-By default, rewriters are auto-discovered from: `.herb/rewriters/**/*.{js,mjs,cjs}`
+By default, rewriters are auto-discovered from: `.herb/rewriters/**/*.mjs`
-Which means you can just reference and configure them in `.herb.yml` using their filename.
+::: info File Extension
+Custom rewriters must use the `.mjs` extension to avoid Node.js module type warnings. The `.mjs` extension explicitly marks files as ES modules.
+:::
+
+#### Configuring in `.herb.yml`
+
+Reference custom rewriters by their name in your configuration:
+
+```yaml [.herb.yml]
+formatter:
+ enabled: true
+ rewriter:
+ pre:
+ - tailwind-class-sorter # Built-in rewriter
+ - my-ast-rewriter # Custom rewriter
+ post:
+ - add-trailing-newline # Custom rewriter
+```
+
+When custom rewriters are loaded, the formatter will display them:
+
+```
+Loaded 2 custom rewriters:
+ • my-ast-rewriter (.herb/rewriters/my-ast-rewriter.mjs)
+ • add-trailing-newline (.herb/rewriters/add-newline.mjs)
+
+Using 2 pre-format rewriters:
+ • tailwind-class-sorter (built-in)
+ • my-ast-rewriter (.herb/rewriters/my-ast-rewriter.mjs)
+
+Using 1 post-format rewriter:
+ • add-trailing-newline (.herb/rewriters/add-newline.mjs)
+```
+
+::: warning Rewriter Name Clashes
+If a custom rewriter has the same name as a built-in rewriter or another custom rewriter, you'll see a warning. The custom rewriter will override the built-in one.
+:::
+
+::: tip Hot Reload
+Custom rewriters are automatically reloaded when changed in editors with the Herb Language Server. No need to restart your editor!
+:::
## API Reference
diff --git a/javascript/packages/rewriter/src/custom-rewriter-loader.ts b/javascript/packages/rewriter/src/custom-rewriter-loader.ts
index 7ad74aa50..982e0be76 100644
--- a/javascript/packages/rewriter/src/custom-rewriter-loader.ts
+++ b/javascript/packages/rewriter/src/custom-rewriter-loader.ts
@@ -25,7 +25,7 @@ export interface CustomRewriterLoaderOptions {
}
const DEFAULT_PATTERNS = [
- ".herb/rewriters/**/*.{js,mjs,cjs}",
+ ".herb/rewriters/**/*.mjs",
]
/**
@@ -82,25 +82,18 @@ export class CustomRewriterLoader {
async loadRewriterFile(filePath: string): Promise {
try {
const fileUrl = pathToFileURL(filePath).href
- const module = await import(fileUrl)
-
- const rewriters: RewriterClass[] = []
+ const cacheBustedUrl = `${fileUrl}?t=${Date.now()}`
+ const module = await import(cacheBustedUrl)
if (module.default && isRewriterClass(module.default)) {
- rewriters.push(module.default)
- }
-
- for (const [exportName, exportValue] of Object.entries(module)) {
- if (exportName !== 'default' && isRewriterClass(exportValue as any)) {
- rewriters.push(exportValue as RewriterClass)
- }
+ return [module.default]
}
- if (rewriters.length === 0 && !this.silent) {
- console.warn(`Warning: No valid rewriter classes found in "${filePath}"`)
+ if (!this.silent) {
+ console.warn(`Warning: No valid default export found in "${filePath}". Custom rewriters must use default export.`)
}
- return rewriters
+ return []
} catch (error) {
if (!this.silent) {
console.error(`Error loading rewriter file "${filePath}": ${error}`)
diff --git a/javascript/packages/vscode/src/analysis-service.ts b/javascript/packages/vscode/src/analysis-service.ts
index 03e73af7f..5c988c09d 100644
--- a/javascript/packages/vscode/src/analysis-service.ts
+++ b/javascript/packages/vscode/src/analysis-service.ts
@@ -24,9 +24,9 @@ export class AnalysisService {
let formatterIndentWidth = 2
let formatterMaxLineLength = 80
let linterRules = {}
+ const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath || process.cwd()
try {
- const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath
if (workspaceRoot) {
const projectConfig = await Config.loadForEditor(workspaceRoot)
linterEnabled = projectConfig.linter?.enabled ?? true
@@ -50,7 +50,8 @@ export class AnalysisService {
formatterEnabled.toString(),
formatterIndentWidth.toString(),
formatterMaxLineLength.toString(),
- JSON.stringify(linterRules)
+ JSON.stringify(linterRules),
+ workspaceRoot
], { timeout: 1000 })
const result = JSON.parse(stdout.trim())
const failed = result.errors > 0 || result.lintErrors > 0
diff --git a/javascript/packages/vscode/src/parse-worker.js b/javascript/packages/vscode/src/parse-worker.js
index 905075934..a3e3b3ff2 100644
--- a/javascript/packages/vscode/src/parse-worker.js
+++ b/javascript/packages/vscode/src/parse-worker.js
@@ -1,6 +1,6 @@
const fs = require('fs');
const { Herb } = require('@herb-tools/node-wasm');
-const { Linter } = require('@herb-tools/linter');
+const { Linter, loadCustomRules } = require('@herb-tools/linter/loader');
const { Formatter } = require('@herb-tools/formatter');
const { Config } = require('@herb-tools/config');
@@ -11,6 +11,7 @@ const { Config } = require('@herb-tools/config');
const formatterIndentWidth = parseInt(process.argv[5]) || 2;
const formatterMaxLineLength = parseInt(process.argv[6]) || 80;
const linterRulesJson = process.argv[7] || '{}';
+ const workspaceRoot = process.argv[8] || process.cwd();
let linterRules = {};
try {
@@ -57,8 +58,21 @@ const { Config } = require('@herb-tools/config');
enabled: true,
rules: linterRules
}
- }, { projectPath: process.cwd() });
- const linter = Linter.from(Herb, config);
+ }, { projectPath: workspaceRoot });
+
+ let customRules = undefined;
+
+ try {
+ const result = await loadCustomRules({
+ baseDir: workspaceRoot,
+ silent: true
+ });
+ customRules = result.rules;
+ } catch (customRuleError) {
+ // Ignore custom rule loading errors in worker
+ }
+
+ const linter = Linter.from(Herb, config, customRules);
const lintResult = linter.lint(content, { fileName: file });
lintOffenses = lintResult.offenses || [];