eslint-plugin-oxfmt 0.1.1 → 0.2.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,6 +223,24 @@ 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 an object to enable it (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           |
+
 ### Advanced Options
 
 | Option            | Type                | Default  | Description                                                                  |

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

@@ -2,23 +2,17 @@ import { join } from "node:path";
 import { createSyncFn } from "synckit";
 import { URL, fileURLToPath } from "node:url";
 import { DIFFERENCE, generateDifferences } from "generate-differences";
-
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
-	for (var name in all) {
-		__defProp(target, name, {
-			get: all[name],
-			enumerable: true
-		});
-	}
-	if (!no_symbols) {
-		__defProp(target, Symbol.toStringTag, { value: "Module" });
-	}
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
 	return target;
 };
-
 //#endregion
 //#region node_modules/.pnpm/eslint-parser-plain@0.1.1/node_modules/eslint-parser-plain/dist/index.mjs
 var dist_exports = /* @__PURE__ */ __exportAll({
@@ -47,11 +41,9 @@ const meta$1 = {
 	name: name$1,
 	version: version$1
 };
-
 //#endregion
 //#region src/parser.ts
 const parserPlain = dist_exports;
-
 //#endregion
 //#region src/configs.ts
 const recommended = {
@@ -63,23 +55,15 @@ const recommended = {
 	rules: { "oxfmt/oxfmt": "error" }
 };
 const configs = { recommended };
-
-//#endregion
-//#region package.json
-var name = "eslint-plugin-oxfmt";
-var version = "0.1.1";
-
 //#endregion
 //#region src/meta.ts
 const meta = {
-	name,
-	version
+	name: "eslint-plugin-oxfmt",
+	version: "0.2.0"
 };
-
 //#endregion
 //#region src/dir.ts
 const dirWorkers = fileURLToPath(new URL("../workers", import.meta.url));
-
 //#endregion
 //#region node_modules/.pnpm/show-invisibles@0.0.2/node_modules/show-invisibles/dist/index.js
 const DEFAULT_MAPPINGS = new Map([
@@ -112,7 +96,6 @@ function showInvisibles(input, options = {}) {
 	if (typeof input !== "string") throw new TypeError(`Expected input to type string, got ${typeof input}`);
 	return input.split("").map((c) => mappings.get(c) || c).join("");
 }
-
 //#endregion
 //#region src/reporter.ts
 /**
@@ -149,7 +132,6 @@ function _reportDifference(context, difference, rangeOffset = 0) {
 		fix: (fixer) => fixer.replaceTextRange(range, insertText)
 	});
 }
-
 //#endregion
 //#region src/schema.ts
 const oxfmtOptionsSchema = {
@@ -201,6 +183,63 @@ const oxfmtOptionsSchema = {
 			description: `Whether to insert a final newline at the end of the file. (Default: true)`,
 			type: "boolean"
 		},
+		jsdoc: {
+			additionalProperties: false,
+			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)`,
+			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"
@@ -449,11 +488,12 @@ const oxfmtRuleSchema = {
 		}
 	}
 };
-
 //#endregion
 //#region src/rules/oxfmt.ts
 let formatViaOxfmt;
-const oxfmt = {
+//#endregion
+//#region src/rules/index.ts
+const rules = { oxfmt: {
 	meta: {
 		defaultOptions: [],
 		fixable: "whitespace",
@@ -467,6 +507,8 @@ const 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"]() {
@@ -519,12 +561,7 @@ const oxfmt = {
 			}
 		} };
 	}
-};
-
-//#endregion
-//#region src/rules/index.ts
-const rules = { oxfmt };
-
+} };
 //#endregion
 //#region src/index.ts
 const plugin = {
@@ -532,6 +569,5 @@ const plugin = {
 	meta,
 	rules
 };
-
 //#endregion
-export { configs, plugin as default, plugin, meta, parserPlain, recommended, rules };
+export { configs, plugin as default, plugin, meta, parserPlain, recommended, rules };

package/dts/rule-options.d.ts

@@ -30,6 +30,31 @@ export type OxfmtOxfmt = []|[{
   
   insertFinalNewline?: boolean
   
+  jsdoc?: {
+    
+    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")
@@ -135,6 +160,31 @@ export type OxfmtOxfmt = []|[{
       
       insertFinalNewline?: boolean
       
+      jsdoc?: {
+        
+        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")

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "eslint-plugin-oxfmt",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.2.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.42.0"
   },
   "dependencies": {
     "generate-differences": "^0.1.1",
-    "load-oxfmt-config": "^0.1.1",
-    "picomatch": "^4.0.3",
+    "load-oxfmt-config": "^0.3.0",
+    "picomatch": "^4.0.4",
     "synckit": "^0.11.12"
   },
   "devDependencies": {
-    "@ntnyq/eslint-config": "^6.0.0-beta.9",
+    "@ntnyq/eslint-config": "^6.0.0-beta.15",
     "@types/json-schema": "^7.0.15",
-    "@types/node": "^25.3.0",
-    "@typescript/native-preview": "^7.0.0-dev.20260224.1",
-    "bumpp": "^10.4.1",
-    "eslint": "^10.0.2",
+    "@types/node": "^25.5.0",
+    "@typescript/native-preview": "^7.0.0-dev.20260328.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.35.0",
+    "oxfmt": "^0.42.0",
     "show-invisibles": "^0.0.2",
     "tinyglobby": "^0.2.15",
-    "tsdown": "^0.20.3",
+    "tsdown": "^0.21.7",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.18",
-    "eslint-plugin-oxfmt": "0.1.1"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2",
+    "eslint-plugin-oxfmt": "0.2.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,6 +127,231 @@ 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 - Base directory for glob matching
+ * @param [ignorePatterns] - Ignore patterns
+ * @returns - Whether the file should be ignored
+ */
+function shouldIgnoreFile(
+  /** @type {string} */
+  filename,
+  /** @type {string} */
+  cwd,
+  /** @type {string[] | undefined} */
+  ignorePatterns,
+) {
+  if (!ignorePatterns || ignorePatterns.length === 0) {
+    return false
+  }
+
+  // Get relative path from cwd and normalize to forward slashes for cross-platform compatibility
+  const relativePath = relative(cwd, filename).replace(/\\/g, '/')
+
+  // Check if file matches any ignore pattern
+  return getCachedMatcher(ignorePatterns)(relativePath)
+}
+
 runAsWorker(
   async (
     /**
@@ -87,31 +370,68 @@ runAsWorker(
     const {
       configPath,
       cwd,
+      ignorePatterns,
       overrides,
       useConfig = true,
       ...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,
+    )
 
-    // Apply overrides based on filename
-    const mergedOptions = applyOverrides(
+    const mergedOptionsCacheKey = getMergedOptionsCacheKey(
       filename,
       cwd,
+      configDir,
       baseOptions,
-      useConfig ? baseOptions.overrides : overrides,
+      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 }
+    }
+
+    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,
+        configDir,
+        mergedOptions,
+        baseOverrides,
+      )
+    }
+
+    // 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)
   },
 )