eslint-plugin-oxfmt 0.1.2 → 0.3.0

package/README.md

@@ -13,7 +13,9 @@
 - 🔧 **Auto-fix** - Automatically format code on save or via ESLint's fix command
 - 🎯 **ESLint Integration** - Seamlessly integrates with ESLint v9+ flat config
 - 📦 **Zero Config** - Works out of the box with sensible defaults
-- 🎨 **Highly Configurable** - Support for all oxfmt formatting options
+- 🧩 **Config File Discovery** - Supports `.oxfmtrc.json`, `.oxfmtrc.jsonc`, and `oxfmt.config.ts`
+- 📝 **EditorConfig Integration** - Respects a subset of `.editorconfig` options via [oxfmt's strategy](https://oxc.rs/docs/guide/usage/formatter/config#editorconfig)
+- 🎨 **Highly Configurable** - Supports all oxfmt formatting options
 - 🌐 **Multi-language Support** - JavaScript, TypeScript, JSX, TSX and [more](https://oxc.rs/docs/guide/usage/formatter.html#supported-languages)
 
 ## Requirements
@@ -104,10 +106,17 @@ export default [
           htmlWhitespaceSensitivity: 'css',
           proseWrap: 'preserve',
 
+          // JSDoc
+          jsdoc: {
+            commentLineStrategy: 'singleLine',
+            lineWrappingStyle: 'greedy',
+            separateTagGroups: false,
+          },
+
           // Vue
           vueIndentScriptAndStyle: false,
 
-          // Experiments
+          // Advanced
           sortImports: {
             order: 'asc',
             newlinesBetween: true,
@@ -132,12 +141,27 @@ All options are optional and default to sensible values.
 
 ### Plugin Options
 
-| Option       | Type      | Default | Description                                                                                            |
-| ------------ | --------- | ------- | ------------------------------------------------------------------------------------------------------ |
-| `useConfig`  | `boolean` | `true`  | Load `.oxfmtrc` / config files via `load-oxfmt-config`. Set to `false` to rely only on inline options. |
-| `configPath` | `string`  | —       | Custom path to an oxfmt config file. Resolved from ESLint `cwd` when set.                              |
+| Option       | Type      | Default | Description                                                                                                                                                               |
+| ------------ | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useConfig`  | `boolean` | `true`  | Load `.oxfmtrc.json`, `.oxfmtrc.jsonc`, or `oxfmt.config.ts` via `load-oxfmt-config` (with `.editorconfig` merge support). Set to `false` to rely only on inline options. |
+| `configPath` | `string`  | —       | Custom path to an oxfmt config file. Resolved from ESLint `cwd` when set.                                                                                                 |
 
 > Note: `cwd` is taken from ESLint automatically; you usually do not need to set it manually.
+> `.editorconfig` merge behavior follows oxfmt's documented strategy: https://oxc.rs/docs/guide/usage/formatter/config#editorconfig
+
+### Config Discovery & Precedence
+
+When `useConfig` is `true`, the plugin loads config using `load-oxfmt-config`.
+
+- Config discovery order (from `cwd`, walking upward): `.oxfmtrc.json` → `.oxfmtrc.jsonc` → `oxfmt.config.ts`
+- `.editorconfig` support: nearest `.editorconfig` (including section overrides) is merged into the final options
+- `configPath` overrides discovery and directly targets the specified config file
+- ESLint rule options generally take highest priority because inline rule options are merged after loaded config. However, when `useConfig` is `true`, `overrides` are taken from the loaded config (not from rule options).
+
+For detailed behavior, see:
+
+- [Oxfmt configuration](https://oxc.rs/docs/guide/usage/formatter/config)
+- [Oxfmt `.editorconfig` strategy](https://oxc.rs/docs/guide/usage/formatter/config#editorconfig)
 
 ### Basic Options
 
@@ -199,16 +223,38 @@ All options are optional and default to sensible values.
 | `htmlWhitespaceSensitivity`  | `'css' \| 'ignore' \| 'strict'`     | `'css'`      | Global whitespace sensitivity for HTML-like languages    |
 | `proseWrap`                  | `'always' \| 'never' \| 'preserve'` | `'preserve'` | Control prose wrapping in Markdown/MDX                   |
 
+### JSDoc Options
+
+Use `jsdoc` to enable and configure JSDoc comment formatting. Pass `true` to enable defaults, or pass an object for custom behavior (for example `jsdoc: {}`).
+
+| Option                              | Type                                    | Default        | Description                                            |
+| ----------------------------------- | --------------------------------------- | -------------- | ------------------------------------------------------ |
+| `jsdoc.commentLineStrategy`         | `'singleLine' \| 'multiline' \| 'keep'` | `'singleLine'` | Comment block style policy                             |
+| `jsdoc.lineWrappingStyle`           | `'greedy' \| 'balance'`                 | `'greedy'`     | Wrapping strategy for long descriptions                |
+| `jsdoc.addDefaultToDescription`     | `boolean`                               | `true`         | Append default values to `@param` descriptions         |
+| `jsdoc.bracketSpacing`              | `boolean`                               | `false`        | Add spaces inside JSDoc type braces                    |
+| `jsdoc.capitalizeDescriptions`      | `boolean`                               | `true`         | Capitalize the first letter of tag descriptions        |
+| `jsdoc.descriptionTag`              | `boolean`                               | `false`        | Emit `@description` tag instead of inline description  |
+| `jsdoc.descriptionWithDot`          | `boolean`                               | `false`        | Add a trailing dot to the end of descriptions          |
+| `jsdoc.keepUnparsableExampleIndent` | `boolean`                               | `false`        | Preserve indentation in unparsable `@example` code     |
+| `jsdoc.preferCodeFences`            | `boolean`                               | `false`        | Prefer fenced code blocks over 4-space indentation     |
+| `jsdoc.separateReturnsFromParam`    | `boolean`                               | `false`        | Add a blank line between final `@param` and `@returns` |
+| `jsdoc.separateTagGroups`           | `boolean`                               | `false`        | Add blank lines between different tag groups           |
+
+Tip: `jsdoc: true` is equivalent to enabling JSDoc with default settings.
+
 ### Advanced Options
 
 | Option            | Type                | Default  | Description                                                                  |
 | ----------------- | ------------------- | -------- | ---------------------------------------------------------------------------- |
-| `sortImports`     | `object`            | disabled | Experimental import sorting configuration                                    |
+| `sortImports`     | `boolean \| object` | disabled | Experimental import sorting configuration                                    |
 | `sortPackageJson` | `boolean \| object` | `true`   | Experimental package.json sorting (object form: `{ sortScripts?: boolean }`) |
-| `sortTailwindcss` | `object`            | disabled | Experimental Tailwind CSS class sorting (enable with `{}` for defaults)      |
+| `sortTailwindcss` | `boolean \| object` | disabled | Experimental Tailwind CSS class sorting (enable with `{}` for defaults)      |
 
 #### Import sorting (`sortImports`)
 
+Use `sortImports: true` to enable import sorting with defaults, or pass an object to customize behavior.
+
 Available keys:
 
 - `customGroups`: Ordered custom group definitions `{ elementNamePattern?: string[]; groupName?: string; modifiers?: string[]; selector?: string }[]`
@@ -228,7 +274,7 @@ Available keys:
 
 #### Tailwind CSS class sorting
 
-Enable experimental Tailwind CSS class sorting powered by `prettier-plugin-tailwindcss` (pass an empty object to turn it on):
+Enable experimental Tailwind CSS class sorting powered by `prettier-plugin-tailwindcss` (set `sortTailwindcss: true` for defaults, or pass an object for custom options):
 
 ```js
 // eslint.config.mjs

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import * as eslint from "eslint";
+import * as _$eslint from "eslint";
 import { Linter, Rule } from "eslint";
 
 //#region src/types.d.ts
@@ -23,7 +23,7 @@ declare const meta: {
 //#endregion
 //#region src/rules/index.d.ts
 declare const rules: {
-  oxfmt: eslint.Rule.RuleModule;
+  oxfmt: _$eslint.Rule.RuleModule;
 };
 //#endregion
 //#region src/parser.d.ts

package/dist/index.mjs

@@ -59,7 +59,7 @@ const configs = { recommended };
 //#region src/meta.ts
 const meta = {
 	name: "eslint-plugin-oxfmt",
-	version: "0.1.2"
+	version: "0.3.0"
 };
 //#endregion
 //#region src/dir.ts
@@ -183,6 +183,65 @@ const oxfmtOptionsSchema = {
 			description: `Whether to insert a final newline at the end of the file. (Default: true)`,
 			type: "boolean"
 		},
+		jsdoc: {
+			description: `Enable JSDoc comment formatting.\n\nWhen enabled, JSDoc comments are normalized and reformatted:\ntag aliases are canonicalized, descriptions are capitalized,\nlong lines are wrapped, and short comments are collapsed to single-line.\n\nPass an object (\`jsdoc: {}\`) to enable with defaults, or omit to disable.\n\n- (Default: Disabled)`,
+			oneOf: [{ type: "boolean" }, {
+				additionalProperties: false,
+				type: "object",
+				properties: {
+					addDefaultToDescription: {
+						description: `Append default values to \`@param\` descriptions (e.g. "Default is \`value\`").\n\n- (Default: true)`,
+						type: "boolean"
+					},
+					bracketSpacing: {
+						description: `Add spaces inside JSDoc type braces: \`{string}\` → \`{ string }\`.\n\n- (Default: false)`,
+						type: "boolean"
+					},
+					capitalizeDescriptions: {
+						description: `Capitalize the first letter of tag descriptions.\n\n- (Default: true)`,
+						type: "boolean"
+					},
+					commentLineStrategy: {
+						description: `How to format comment blocks.\n\n- \`"singleLine"\` — Convert to single-line \`/** content */\` when possible.\n- \`"multiline"\` — Always use multi-line format.\n- \`"keep"\` — Preserve original formatting.\n\n- (Default: "singleLine")`,
+						enum: [
+							"singleLine",
+							"multiline",
+							"keep"
+						],
+						type: "string"
+					},
+					descriptionTag: {
+						description: `Emit \`@description\` tag instead of inline description.\n\n- (Default: false)`,
+						type: "boolean"
+					},
+					descriptionWithDot: {
+						description: `Add a trailing dot to the end of descriptions.\n\n- (Default: false)`,
+						type: "boolean"
+					},
+					keepUnparsableExampleIndent: {
+						description: `Preserve indentation in unparsable \`@example\` code.\n\n- (Default: false)`,
+						type: "boolean"
+					},
+					lineWrappingStyle: {
+						description: `Strategy for wrapping description lines at print width.\n\n- \`"greedy"\` — Always re-wrap text to fit within print width.\n- \`"balance"\` — Preserve original line breaks if all lines fit within print width.\n\n- (Default: "greedy")`,
+						enum: ["greedy", "balance"],
+						type: "string"
+					},
+					preferCodeFences: {
+						description: `Use fenced code blocks (\`\`\`) instead of 4-space indentation for code without a language tag.\n\n- (Default: false)`,
+						type: "boolean"
+					},
+					separateReturnsFromParam: {
+						description: `Add a blank line between the last \`@param\` and \`@returns\`.\n\n- (Default: false)`,
+						type: "boolean"
+					},
+					separateTagGroups: {
+						description: `Add blank lines between different tag groups (e.g. between \`@param\` and \`@returns\`).\n\n- (Default: false)`,
+						type: "boolean"
+					}
+				}
+			}]
+		},
 		jsxSingleQuote: {
 			description: `Use single quotes instead of double quotes in JSX. (Default: false)`,
 			type: "boolean"
@@ -231,89 +290,91 @@ const oxfmtOptionsSchema = {
 			type: "boolean"
 		},
 		sortImports: {
-			additionalProperties: false,
 			description: `Experimental: Sort import statements. Disabled by default.`,
-			type: "object",
-			properties: {
-				customGroups: {
-					description: `Define your own groups for matching very specific imports.\n\nThe customGroups list is ordered: The first definition that matches an element will be used.\nCustom groups have a higher priority than any predefined group.\n\nIf you want a predefined group to take precedence over a custom group,\nyou must write a custom group definition that does the same as what the predefined group does, and put it first in the list.\n\n- (Default: [])`,
-					type: "array",
-					items: {
-						additionalProperties: false,
-						type: "object",
-						properties: {
-							elementNamePattern: {
-								description: `List of glob patterns to match import sources for this group.`,
-								type: "array",
-								items: { type: "string" }
-							},
-							groupName: {
-								description: `Name of the custom group, used in the groups option.`,
-								type: "string"
-							},
-							modifiers: {
-								description: `Modifiers to match the import characteristics.\nAll specified modifiers must be present (AND logic).\n\nPossible values: "side_effect", "type", "value", "default", "wildcard", "named"`,
+			oneOf: [{ type: "boolean" }, {
+				additionalProperties: false,
+				type: "object",
+				properties: {
+					customGroups: {
+						description: `Define your own groups for matching very specific imports.\n\nThe customGroups list is ordered: The first definition that matches an element will be used.\nCustom groups have a higher priority than any predefined group.\n\nIf you want a predefined group to take precedence over a custom group,\nyou must write a custom group definition that does the same as what the predefined group does, and put it first in the list.\n\n- (Default: [])`,
+						type: "array",
+						items: {
+							additionalProperties: false,
+							type: "object",
+							properties: {
+								elementNamePattern: {
+									description: `List of glob patterns to match import sources for this group.`,
+									type: "array",
+									items: { type: "string" }
+								},
+								groupName: {
+									description: `Name of the custom group, used in the groups option.`,
+									type: "string"
+								},
+								modifiers: {
+									description: `Modifiers to match the import characteristics.\nAll specified modifiers must be present (AND logic).\n\nPossible values: "side_effect", "type", "value", "default", "wildcard", "named"`,
+									type: "array",
+									items: { type: "string" }
+								},
+								selector: {
+									description: `Selector to match the import kind.\n\nPossible values: "type", "side_effect_style", "side_effect", "style", "index", "sibling", "parent", "subpath", "internal", "builtin", "external", "import"`,
+									type: "string"
+								}
+							}
+						}
+					},
+					groups: {
+						description: `Specifies a list of predefined import groups for sorting.\n\nEach import will be assigned a single group specified in the groups option (or the \`unknown\` group if no match is found).\nThe order of items in the \`groups\` option determines how groups are ordered.\n\nWithin a given group, members will be sorted according to the type, order, ignoreCase, etc. options.\n\nIndividual groups can be combined together by placing them in an array.\nThe order of groups in that array does not matter.\nAll members of the groups in the array will be sorted together as if they were part of a single group.\n\nPredefined groups are characterized by a single selector and potentially multiple modifiers.\nYou may enter modifiers in any order, but the selector must always come at the end.\n\nThe list of selectors is sorted from most to least important:\n- \`type\` — TypeScript type imports.\n- \`side_effect_style\` — Side effect style imports.\n- \`side_effect\` — Side effect imports.\n- \`style\` — Style imports.\n- \`index\` — Main file from the current directory.\n- \`sibling\` — Modules from the same directory.\n- \`parent\` — Modules from the parent directory.\n- \`subpath\` — Node.js subpath imports.\n- \`internal\` — Your internal modules.\n- \`builtin\` — Node.js Built-in Modules.\n- \`external\` — External modules installed in the project.\n- \`import\` — Any import.\n\nThe list of modifiers is sorted from most to least important:\n- \`side_effect\` — Side effect imports.\n- \`type\` — TypeScript type imports.\n- \`value\` — Value imports.\n- \`default\` — Imports containing the default specifier.\n- \`wildcard\` — Imports containing the wildcard (\`* as\`) specifier.\n- \`named\` — Imports containing at least one named specifier.\n\n- Default: See below\n\`\`\`json\n[\n\"builtin\",\n\"external\",\n[\"internal\", \"subpath\"],\n[\"parent\", \"sibling\", \"index\"],\n\"style\",\n\"unknown\"\n]\n\`\`\`\n\nAlso, you can override the global \`newlinesBetween\` setting for specific group boundaries\nby including a \`{ \"newlinesBetween\": boolean }\` marker object in the \`groups\` list at the desired position.`,
+						type: "array",
+						items: { anyOf: [
+							{ type: "string" },
+							{
 								type: "array",
 								items: { type: "string" }
 							},
-							selector: {
-								description: `Selector to match the import kind.\n\nPossible values: "type", "side_effect_style", "side_effect", "style", "index", "sibling", "parent", "subpath", "internal", "builtin", "external", "import"`,
-								type: "string"
+							{
+								additionalProperties: false,
+								required: ["newlinesBetween"],
+								type: "object",
+								properties: { newlinesBetween: {
+									description: `A marker object for overriding \`newlinesBetween\` at a specific group boundary.`,
+									type: "boolean"
+								} }
 							}
-						}
+						] }
+					},
+					ignoreCase: {
+						description: `Ignore case when sorting. (Default: true)`,
+						type: "boolean"
+					},
+					internalPattern: {
+						description: `Glob patterns to identify internal imports.`,
+						type: "array",
+						items: { type: "string" }
+					},
+					newlinesBetween: {
+						description: `Add newlines between import groups. (Default: true)`,
+						type: "boolean"
+					},
+					order: {
+						description: `Sort order. (Default: "asc")`,
+						enum: ["asc", "desc"],
+						type: "string"
+					},
+					partitionByComment: {
+						description: `Partition imports by comments. (Default: false)`,
+						type: "boolean"
+					},
+					partitionByNewline: {
+						description: `Partition imports by newlines. (Default: false)`,
+						type: "boolean"
+					},
+					sortSideEffects: {
+						description: `Sort side-effect imports. (Default: false)`,
+						type: "boolean"
 					}
-				},
-				groups: {
-					description: `Specifies a list of predefined import groups for sorting.\n\nEach import will be assigned a single group specified in the groups option (or the \`unknown\` group if no match is found).\nThe order of items in the \`groups\` option determines how groups are ordered.\n\nWithin a given group, members will be sorted according to the type, order, ignoreCase, etc. options.\n\nIndividual groups can be combined together by placing them in an array.\nThe order of groups in that array does not matter.\nAll members of the groups in the array will be sorted together as if they were part of a single group.\n\nPredefined groups are characterized by a single selector and potentially multiple modifiers.\nYou may enter modifiers in any order, but the selector must always come at the end.\n\nThe list of selectors is sorted from most to least important:\n- \`type\` — TypeScript type imports.\n- \`side_effect_style\` — Side effect style imports.\n- \`side_effect\` — Side effect imports.\n- \`style\` — Style imports.\n- \`index\` — Main file from the current directory.\n- \`sibling\` — Modules from the same directory.\n- \`parent\` — Modules from the parent directory.\n- \`subpath\` — Node.js subpath imports.\n- \`internal\` — Your internal modules.\n- \`builtin\` — Node.js Built-in Modules.\n- \`external\` — External modules installed in the project.\n- \`import\` — Any import.\n\nThe list of modifiers is sorted from most to least important:\n- \`side_effect\` — Side effect imports.\n- \`type\` — TypeScript type imports.\n- \`value\` — Value imports.\n- \`default\` — Imports containing the default specifier.\n- \`wildcard\` — Imports containing the wildcard (\`* as\`) specifier.\n- \`named\` — Imports containing at least one named specifier.\n\n- Default: See below\n\`\`\`json\n[\n\"builtin\",\n\"external\",\n[\"internal\", \"subpath\"],\n[\"parent\", \"sibling\", \"index\"],\n\"style\",\n\"unknown\"\n]\n\`\`\`\n\nAlso, you can override the global \`newlinesBetween\` setting for specific group boundaries\nby including a \`{ \"newlinesBetween\": boolean }\` marker object in the \`groups\` list at the desired position.`,
-					type: "array",
-					items: { anyOf: [
-						{ type: "string" },
-						{
-							type: "array",
-							items: { type: "string" }
-						},
-						{
-							additionalProperties: false,
-							required: ["newlinesBetween"],
-							type: "object",
-							properties: { newlinesBetween: {
-								description: `A marker object for overriding \`newlinesBetween\` at a specific group boundary.`,
-								type: "boolean"
-							} }
-						}
-					] }
-				},
-				ignoreCase: {
-					description: `Ignore case when sorting. (Default: true)`,
-					type: "boolean"
-				},
-				internalPattern: {
-					description: `Glob patterns to identify internal imports.`,
-					type: "array",
-					items: { type: "string" }
-				},
-				newlinesBetween: {
-					description: `Add newlines between import groups. (Default: true)`,
-					type: "boolean"
-				},
-				order: {
-					description: `Sort order. (Default: "asc")`,
-					enum: ["asc", "desc"],
-					type: "string"
-				},
-				partitionByComment: {
-					description: `Partition imports by comments. (Default: false)`,
-					type: "boolean"
-				},
-				partitionByNewline: {
-					description: `Partition imports by newlines. (Default: false)`,
-					type: "boolean"
-				},
-				sortSideEffects: {
-					description: `Sort side-effect imports. (Default: false)`,
-					type: "boolean"
 				}
-			}
+			}]
 		},
 		sortPackageJson: {
 			description: `Experimental: Sort package.json keys. (Default: true)`,
@@ -327,37 +388,39 @@ const oxfmtOptionsSchema = {
 			}]
 		},
 		sortTailwindcss: {
-			additionalProperties: false,
 			description: `Experimental: Enable Tailwind CSS class sorting in JSX class/className attributes.\nWhen enabled, class strings will be collected and passed to a callback for sorting.\nPass an object with options from "prettier-plugin-tailwindcss".\n\n- (Default: disabled)`,
-			type: "object",
-			properties: {
-				attributes: {
-					description: `List of additional attributes to sort beyond "class" and "className" (exact match).\n\nNOTE: Regex patterns are not yet supported.\n\n- (Default: [])\n- Example: ["myClassProp", ":class"]`,
-					type: "array",
-					items: { type: "string" }
-				},
-				config: {
-					description: `Path to your Tailwind CSS configuration file (v3).\n\nNote: Paths are resolved relative to the Oxfmt configuration file.\n\n- (Default: "./tailwind.config.js")`,
-					type: "string"
-				},
-				functions: {
-					description: `List of custom function names whose arguments should be sorted (exact match).\n\nNOTE: Regex patterns are not yet supported.\n\n- (Default: [])\n- Example: ["clsx", "cn", "cva", "tw"]`,
-					type: "array",
-					items: { type: "string" }
-				},
-				preserveDuplicates: {
-					description: `Preserve duplicate classes.\n\n- (Default: false)`,
-					type: "boolean"
-				},
-				preserveWhitespace: {
-					description: `Preserve whitespace around classes.\n\n- (Default: false)`,
-					type: "boolean"
-				},
-				stylesheet: {
-					description: `Path to your Tailwind CSS stylesheet (v4).\n\nNote: Paths are resolved relative to the Oxfmt configuration file.\n\n- (Example: "./src/app.css")`,
-					type: "string"
+			oneOf: [{ type: "boolean" }, {
+				additionalProperties: false,
+				type: "object",
+				properties: {
+					attributes: {
+						description: `List of additional attributes to sort beyond "class" and "className" (exact match).\n\nNOTE: Regex patterns are not yet supported.\n\n- (Default: [])\n- Example: ["myClassProp", ":class"]`,
+						type: "array",
+						items: { type: "string" }
+					},
+					config: {
+						description: `Path to your Tailwind CSS configuration file (v3).\n\nNote: Paths are resolved relative to the Oxfmt configuration file.\n\n- (Default: "./tailwind.config.js")`,
+						type: "string"
+					},
+					functions: {
+						description: `List of custom function names whose arguments should be sorted (exact match).\n\nNOTE: Regex patterns are not yet supported.\n\n- (Default: [])\n- Example: ["clsx", "cn", "cva", "tw"]`,
+						type: "array",
+						items: { type: "string" }
+					},
+					preserveDuplicates: {
+						description: `Preserve duplicate classes.\n\n- (Default: false)`,
+						type: "boolean"
+					},
+					preserveWhitespace: {
+						description: `Preserve whitespace around classes.\n\n- (Default: false)`,
+						type: "boolean"
+					},
+					stylesheet: {
+						description: `Path to your Tailwind CSS stylesheet (v4).\n\nNote: Paths are resolved relative to the Oxfmt configuration file.\n\n- (Example: "./src/app.css")`,
+						type: "string"
+					}
 				}
-			}
+			}]
 		},
 		tabWidth: {
 			description: `Number of spaces per indentation level. (Default: 2)`,
@@ -450,6 +513,8 @@ const rules = { oxfmt: {
 		}
 	},
 	create(context) {
+		const physicalFilename = context.physicalFilename ?? context.filename;
+		if (context.filename !== physicalFilename) return {};
 		if (!formatViaOxfmt) formatViaOxfmt = createSyncFn(join(dirWorkers, "oxfmt.mjs"));
 		const sourceText = context.sourceCode.text;
 		return { [context.sourceCode.ast.type || "Program"]() {

package/dts/rule-options.d.ts

@@ -30,6 +30,31 @@ export type OxfmtOxfmt = []|[{
   
   insertFinalNewline?: boolean
   
+  jsdoc?: (boolean | {
+    
+    addDefaultToDescription?: boolean
+    
+    bracketSpacing?: boolean
+    
+    capitalizeDescriptions?: boolean
+    
+    commentLineStrategy?: ("singleLine" | "multiline" | "keep")
+    
+    descriptionTag?: boolean
+    
+    descriptionWithDot?: boolean
+    
+    keepUnparsableExampleIndent?: boolean
+    
+    lineWrappingStyle?: ("greedy" | "balance")
+    
+    preferCodeFences?: boolean
+    
+    separateReturnsFromParam?: boolean
+    
+    separateTagGroups?: boolean
+  })
+  
   jsxSingleQuote?: boolean
   
   objectWrap?: ("preserve" | "collapse" | "always")
@@ -46,7 +71,7 @@ export type OxfmtOxfmt = []|[{
   
   singleQuote?: boolean
   
-  sortImports?: {
+  sortImports?: (boolean | {
     
     customGroups?: {
       
@@ -77,14 +102,14 @@ export type OxfmtOxfmt = []|[{
     partitionByNewline?: boolean
     
     sortSideEffects?: boolean
-  }
+  })
   
   sortPackageJson?: (boolean | {
     
     sortScripts?: boolean
   })
   
-  sortTailwindcss?: {
+  sortTailwindcss?: (boolean | {
     
     attributes?: string[]
     
@@ -97,7 +122,7 @@ export type OxfmtOxfmt = []|[{
     preserveWhitespace?: boolean
     
     stylesheet?: string
-  }
+  })
   
   tabWidth?: number
   
@@ -135,6 +160,31 @@ export type OxfmtOxfmt = []|[{
       
       insertFinalNewline?: boolean
       
+      jsdoc?: (boolean | {
+        
+        addDefaultToDescription?: boolean
+        
+        bracketSpacing?: boolean
+        
+        capitalizeDescriptions?: boolean
+        
+        commentLineStrategy?: ("singleLine" | "multiline" | "keep")
+        
+        descriptionTag?: boolean
+        
+        descriptionWithDot?: boolean
+        
+        keepUnparsableExampleIndent?: boolean
+        
+        lineWrappingStyle?: ("greedy" | "balance")
+        
+        preferCodeFences?: boolean
+        
+        separateReturnsFromParam?: boolean
+        
+        separateTagGroups?: boolean
+      })
+      
       jsxSingleQuote?: boolean
       
       objectWrap?: ("preserve" | "collapse" | "always")
@@ -151,7 +201,7 @@ export type OxfmtOxfmt = []|[{
       
       singleQuote?: boolean
       
-      sortImports?: {
+      sortImports?: (boolean | {
         
         customGroups?: {
           
@@ -182,14 +232,14 @@ export type OxfmtOxfmt = []|[{
         partitionByNewline?: boolean
         
         sortSideEffects?: boolean
-      }
+      })
       
       sortPackageJson?: (boolean | {
         
         sortScripts?: boolean
       })
       
-      sortTailwindcss?: {
+      sortTailwindcss?: (boolean | {
         
         attributes?: string[]
         
@@ -202,7 +252,7 @@ export type OxfmtOxfmt = []|[{
         preserveWhitespace?: boolean
         
         stylesheet?: string
-      }
+      })
       
       tabWidth?: number
       

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "eslint-plugin-oxfmt",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "An ESLint plugin for formatting code with oxfmt.",
   "keywords": [
     "eslint",
@@ -44,35 +44,35 @@
   "sideEffects": false,
   "peerDependencies": {
     "eslint": "^9.5.0 || ^10.0.0",
-    "oxfmt": ">=0.35.0"
+    "oxfmt": ">=0.43.0"
   },
   "dependencies": {
     "generate-differences": "^0.1.1",
-    "load-oxfmt-config": "^0.2.0",
-    "picomatch": "^4.0.3",
+    "load-oxfmt-config": "^0.3.1",
+    "picomatch": "^4.0.4",
     "synckit": "^0.11.12"
   },
   "devDependencies": {
-    "@ntnyq/eslint-config": "^6.0.0-beta.13",
+    "@ntnyq/eslint-config": "^6.0.0",
     "@types/json-schema": "^7.0.15",
-    "@types/node": "^25.4.0",
-    "@typescript/native-preview": "^7.0.0-dev.20260312.1",
-    "bumpp": "^10.4.1",
-    "eslint": "^10.0.3",
+    "@types/node": "^25.5.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260331.1",
+    "bumpp": "^11.0.1",
+    "eslint": "^10.1.0",
     "eslint-parser-plain": "^0.1.1",
     "eslint-typegen": "^2.3.1",
     "eslint-vitest-rule-tester": "^3.1.0",
     "husky": "^9.1.7",
     "nano-staged": "^0.9.0",
     "npm-run-all2": "^8.0.4",
-    "oxfmt": "^0.39.0",
+    "oxfmt": "^0.43.0",
     "show-invisibles": "^0.0.2",
     "tinyglobby": "^0.2.15",
-    "tsdown": "^0.21.2",
+    "tsdown": "^0.21.7",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18",
-    "eslint-plugin-oxfmt": "0.1.2"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2",
+    "eslint-plugin-oxfmt": "0.3.0"
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"

package/workers/oxfmt.mjs

@@ -1,7 +1,7 @@
 // @ts-check
 
-import { relative } from 'node:path'
-import { loadOxfmtConfig } from 'load-oxfmt-config'
+import { dirname, isAbsolute, join, relative } from 'node:path'
+import { loadOxfmtConfig, resolveOxfmtrcPath } from 'load-oxfmt-config'
 import { format } from 'oxfmt'
 import picomatch from 'picomatch'
 import { runAsWorker } from 'synckit'
@@ -12,17 +12,75 @@ import { runAsWorker } from 'synckit'
  * @property {string} cwd - Current working directory for resolving configuration
  * @property {string} [configPath] - Custom path to oxfmt configuration file
  */
+
 /**
- * @typedef {import('load-oxfmt-config').FormatOptionOverride} Override
+ * @typedef {import('load-oxfmt-config').OxfmtConfigOverride} Override
  */
 /**
  * @typedef {import('load-oxfmt-config').OxfmtOptions & PluginOptions} Options
  */
 
+/**
+ * @typedef {object} ResolvedBaseOptions
+ * @property {import('oxfmt').FormatConfig} baseOptions Resolved base formatter options.
+ * @property {string} configDir Directory of the resolved config file, used as base for config-derived glob patterns.
+ */
+
+const MAX_CACHE_SIZE = 1000
+
+/**
+ * Evict oldest entries when the cache exceeds MAX_CACHE_SIZE.
+ * @param cache - The cache map to evict entries from
+ */
+function evictCache(
+  /** @type {Map<string, unknown>} */
+  cache,
+) {
+  if (cache.size <= MAX_CACHE_SIZE) {
+    return
+  }
+  const keysToDelete = [...cache.keys()].slice(0, cache.size - MAX_CACHE_SIZE)
+  for (const key of keysToDelete) {
+    cache.delete(key)
+  }
+}
+
+/**
+ * JSON.stringify replacer that sorts object keys for stable serialization.
+ * @param key - The key of the property being processed
+ * @param value - The value of the property being processed
+ * @returns - The value to be serialized, with object keys sorted if it's an object
+ */
+function stableReplacer(
+  /** @type {string} */
+  key,
+  /** @type {unknown} */
+  value,
+) {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return Object.keys(value)
+      .sort()
+      .reduce((sorted, k) => {
+        sorted[k] = /** @type {Record<string, unknown>} */ (value)[k]
+        return sorted
+      }, /** @type {Record<string, unknown>} */ ({}))
+  }
+  return value
+}
+
+/** @type {Map<string, Promise<ResolvedBaseOptions>>} */
+const resolvedBaseOptionsCache = new Map()
+
+/** @type {Map<string, import('oxfmt').FormatConfig>} */
+const mergedOptionsCache = new Map()
+
+/** @type {Map<string, ReturnType<typeof picomatch>>} */
+const picomatchCache = new Map()
+
 /**
  * Apply overrides to the base options based on the filename
  * @param filename - The file path
- * @param cwd - Current working directory
+ * @param cwd - Base directory for glob matching
  * @param baseOptions - Base format options
  * @param [overrides] - Override configurations
  * @returns - Merged options
@@ -32,7 +90,7 @@ function applyOverrides(
   filename,
   /** @type {string} */
   cwd,
-  /** @type {import('oxfmt').FormatOptions} */
+  /** @type {import('oxfmt').FormatConfig} */
   baseOptions,
   /** @type {Override[] | undefined} */
   overrides,
@@ -52,12 +110,12 @@ function applyOverrides(
     const { excludeFiles, files, options: overrideOptions } = override
 
     // Check if file matches the files patterns
-    const matches = picomatch.isMatch(relativePath, files)
+    const matches = getCachedMatcher(files)(relativePath)
 
     // Check if file is excluded
     const excluded =
       excludeFiles && excludeFiles.length > 0
-        ? picomatch.isMatch(relativePath, excludeFiles)
+        ? getCachedMatcher(excludeFiles)(relativePath)
         : false
 
     if (matches && !excluded && overrideOptions) {
@@ -69,10 +127,209 @@ function applyOverrides(
   return hasOverrides ? mergedOptions : baseOptions
 }
 
+/**
+ * Get or create a cached picomatch matcher for the given patterns.
+ * @param patterns - Glob patterns to match against file paths
+ * @returns - Picomatch matcher function
+ */
+function getCachedMatcher(
+  /** @type {string | string[]} */
+  patterns,
+) {
+  const key = Array.isArray(patterns) ? patterns.join('\0') : patterns
+  const cached = picomatchCache.get(key)
+  if (cached) {
+    return cached
+  }
+  const matcher = picomatch(patterns)
+  picomatchCache.set(key, matcher)
+  evictCache(picomatchCache)
+  return matcher
+}
+
+/**
+ * Resolve an effective config path for a file.
+ * - Absolute paths are returned as-is.
+ * - Relative paths are resolved from cwd.
+ *
+ * @param cwd - Current working directory from ESLint context.
+ * @param [configPath] - Optional user-provided config path.
+ * @returns Absolute config path when provided, otherwise undefined.
+ */
+function getConfigPathForFile(
+  /** @type {string} */
+  cwd,
+  /** @type {string | undefined} */
+  configPath,
+) {
+  if (!configPath) {
+    return undefined
+  }
+
+  return isAbsolute(configPath) ? configPath : join(cwd, configPath)
+}
+
+/**
+ * Build cache key for merged options per file invocation.
+ * The key includes filename, cwd, configDir, resolved base options, and rule-level
+ * override inputs to avoid stale cache hits.
+ *
+ * @param filename - Current file path.
+ * @param cwd - Base directory used for rule-level glob matching.
+ * @param configDir - Directory of the resolved config file, used for config-derived glob matching.
+ * @param baseOptions - Resolved base options used for formatting.
+ * @param ignorePatterns - Rule-level ignore patterns.
+ * @param overrides - Rule-level override entries.
+ * @param useConfig - Whether config file loading is enabled.
+ * @returns Serialized cache key.
+ */
+function getMergedOptionsCacheKey(
+  /** @type {string} */
+  filename,
+  /** @type {string} */
+  cwd,
+  /** @type {string} */
+  configDir,
+  /** @type {import('oxfmt').FormatConfig} */
+  baseOptions,
+  /** @type {string[] | undefined} */
+  ignorePatterns,
+  /** @type {Override[] | undefined} */
+  overrides,
+  /** @type {boolean} */
+  useConfig,
+) {
+  return JSON.stringify(
+    {
+      baseOptions,
+      configDir,
+      cwd,
+      filename,
+      ignorePatterns,
+      overrides,
+      useConfig,
+    },
+    stableReplacer,
+  )
+}
+
+/**
+ * Build cache key for resolving base formatter options.
+ * The key includes file directory and all resolution inputs.
+ *
+ * @param filename - Current file path.
+ * @param cwd - Current working directory from ESLint context.
+ * @param configPath - Optional user-provided config path.
+ * @param useConfig - Whether config file loading is enabled.
+ * @param formatOptions - Rule-level format options.
+ * @returns Serialized cache key.
+ */
+function getResolvedBaseOptionsCacheKey(
+  /** @type {string} */
+  filename,
+  /** @type {string} */
+  cwd,
+  /** @type {string | undefined} */
+  configPath,
+  /** @type {boolean} */
+  useConfig,
+  /** @type {import('oxfmt').FormatConfig} */
+  formatOptions,
+) {
+  return JSON.stringify(
+    {
+      configPath: configPath || '',
+      cwd,
+      fileDir: dirname(filename),
+      formatOptions,
+      useConfig,
+    },
+    stableReplacer,
+  )
+}
+
+/**
+ * Resolve base formatter options for a file and cache the async result.
+ *
+ * @param filename - Current file path.
+ * @param cwd - Current working directory from ESLint context.
+ * @param configPath - Optional user-provided config path.
+ * @param useConfig - Whether config file loading is enabled.
+ * @param formatOptions - Rule-level format options.
+ * @returns Base options after config loading and inline option merge.
+ */
+async function resolveBaseOptions(
+  /** @type {string} */
+  filename,
+  /** @type {string} */
+  cwd,
+  /** @type {string | undefined} */
+  configPath,
+  /** @type {boolean} */
+  useConfig,
+  /** @type {import('oxfmt').FormatConfig} */
+  formatOptions,
+) {
+  const cacheKey = getResolvedBaseOptionsCacheKey(
+    filename,
+    cwd,
+    configPath,
+    useConfig,
+    formatOptions,
+  )
+
+  const cachedTask = resolvedBaseOptionsCache.get(cacheKey)
+  if (cachedTask) {
+    return cachedTask
+  }
+
+  const task = (async () => {
+    const resolveFromDir = dirname(filename)
+
+    if (!useConfig) {
+      return {
+        configDir: cwd,
+        baseOptions: {
+          ...formatOptions,
+        },
+      }
+    }
+
+    const resolvedConfigPath = getConfigPathForFile(cwd, configPath)
+    const resolvedPath = await resolveOxfmtrcPath(
+      resolveFromDir,
+      resolvedConfigPath,
+    )
+    const configDir = resolvedPath ? dirname(resolvedPath) : cwd
+    const configOptions = await loadOxfmtConfig({
+      configPath: resolvedConfigPath,
+      cwd: resolveFromDir,
+    })
+
+    return {
+      configDir,
+      baseOptions: {
+        ...configOptions,
+        ...formatOptions,
+      },
+    }
+  })()
+
+  resolvedBaseOptionsCache.set(cacheKey, task)
+  evictCache(resolvedBaseOptionsCache)
+
+  try {
+    return await task
+  } catch (err) {
+    resolvedBaseOptionsCache.delete(cacheKey)
+    throw err
+  }
+}
+
 /**
  * Check if a file should be ignored based on ignorePatterns
  * @param filename - The file path
- * @param cwd - Current working directory
+ * @param cwd - Base directory for glob matching
  * @param [ignorePatterns] - Ignore patterns
  * @returns - Whether the file should be ignored
  */
@@ -92,7 +349,7 @@ function shouldIgnoreFile(
   const relativePath = relative(cwd, filename).replace(/\\/g, '/')
 
   // Check if file matches any ignore pattern
-  return picomatch.isMatch(relativePath, ignorePatterns)
+  return getCachedMatcher(ignorePatterns)(relativePath)
 }
 
 runAsWorker(
@@ -119,36 +376,62 @@ runAsWorker(
       ...formatOptions
     } = options
 
-    // Load base options from config or use provided options
-    const baseOptions = {
-      ...(useConfig
-        ? await loadOxfmtConfig({
-            configPath,
-            cwd,
-          })
-        : {}),
-      ...formatOptions,
+    const { baseOptions, configDir } = await resolveBaseOptions(
+      filename,
+      cwd,
+      configPath,
+      useConfig,
+      formatOptions,
+    )
+
+    const mergedOptionsCacheKey = getMergedOptionsCacheKey(
+      filename,
+      cwd,
+      configDir,
+      baseOptions,
+      ignorePatterns,
+      overrides,
+      useConfig,
+    )
+
+    const baseIgnorePatterns = /** @type {string[] | undefined} */ (
+      baseOptions.ignorePatterns
+    )
+    const effectiveIgnorePatterns = ignorePatterns ?? baseIgnorePatterns
+    const ignoreBase = ignorePatterns == null ? configDir : cwd
+
+    if (shouldIgnoreFile(filename, ignoreBase, effectiveIgnorePatterns)) {
+      return { code: sourceText }
     }
 
-    if (
-      shouldIgnoreFile(
+    const cachedMergedOptions = mergedOptionsCache.get(mergedOptionsCacheKey)
+    if (cachedMergedOptions) {
+      return format(filename, sourceText, cachedMergedOptions)
+    }
+
+    const baseOverrides = /** @type {Override[] | undefined} */ (
+      baseOptions.overrides
+    )
+
+    // Apply config-level overrides (relative to config directory)
+    let mergedOptions = baseOptions
+    if (useConfig && baseOverrides && baseOverrides.length > 0) {
+      mergedOptions = applyOverrides(
         filename,
-        cwd,
-        ignorePatterns || baseOptions.ignorePatterns,
+        configDir,
+        mergedOptions,
+        baseOverrides,
       )
-    ) {
-      return { code: sourceText }
     }
 
-    // Apply overrides based on filename
-    const mergedOptions = applyOverrides(
-      filename,
-      cwd,
-      baseOptions,
-      useConfig ? baseOptions.overrides : overrides,
-    )
+    // Apply rule-level overrides (relative to ESLint cwd)
+    if (overrides && overrides.length > 0) {
+      mergedOptions = applyOverrides(filename, cwd, mergedOptions, overrides)
+    }
+
+    mergedOptionsCache.set(mergedOptionsCacheKey, mergedOptions)
+    evictCache(mergedOptionsCache)
 
-    const formatResult = await format(filename, sourceText, mergedOptions)
-    return formatResult
+    return format(filename, sourceText, mergedOptions)
   },
 )