eslint-plugin-oxfmt 0.4.0 → 0.5.0

package/README.md

@@ -55,6 +55,22 @@ export default [
 ]
 ```
 
+`recommended` includes `eslint-parser-plain` as `languageOptions.parser` for convenience.
+
+If you need parser-agnostic composition (for example to keep `jsonc-eslint-parser` from another config), use the dedicated preset:
+
+```js
+// eslint.config.mjs
+import pluginOxfmt from 'eslint-plugin-oxfmt'
+
+export default [
+  {
+    ...pluginOxfmt.configs.recommendedWithoutParser,
+    files: ['**/*.{js,ts,mjs,cjs,jsx,tsx,json,jsonc}'],
+  },
+]
+```
+
 ### Custom Configuration
 
 You can customize the formatting options by configuring the rule:
@@ -156,7 +172,9 @@ 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).
+- ESLint rule options generally take highest priority because inline rule options are merged after loaded config.
+- When `useConfig` is `true`, rule-level `overrides` are ignored. Only `overrides` loaded from the resolved oxfmt config file are applied.
+- Rule-level `ignorePatterns` still override config-derived `ignorePatterns` when provided.
 
 For detailed behavior, see:
 
@@ -365,6 +383,13 @@ This plugin provides a single rule that formats your code using oxfmt.
 
 ## Integration
 
+### Parser Compatibility
+
+- `recommended`: forces `eslint-parser-plain` for matched files
+- `recommendedWithoutParser`: parser-agnostic (safe to compose with language-specific parsers)
+
+When composing shareable configs, prefer `recommendedWithoutParser` if parser ownership belongs to another preset.
+
 ### Format on Save in VS Code
 
 Add this to your `.vscode/settings.json`:

package/dist/index.d.mts

@@ -5,6 +5,7 @@ import { Linter, Rule } from "eslint";
 interface PluginOxfmt {
   configs: {
     recommended: Linter.Config<Linter.RulesRecord>;
+    recommendedWithoutParser: Linter.Config<Linter.RulesRecord>;
   };
   meta: {
     name: string;
@@ -30,10 +31,11 @@ declare const rules: {
 declare const parserPlain: Linter.Parser;
 //#endregion
 //#region src/configs.d.ts
+declare const recommendedWithoutParser: Linter.Config<Linter.RulesRecord>;
 declare const recommended: Linter.Config<Linter.RulesRecord>;
 declare const configs: PluginOxfmt['configs'];
 //#endregion
 //#region src/index.d.ts
 declare const plugin: PluginOxfmt;
 //#endregion
-export { configs, plugin as default, plugin, meta, parserPlain, recommended, rules };
+export { configs, plugin as default, plugin, meta, parserPlain, recommended, recommendedWithoutParser, rules };

package/dist/index.mjs

@@ -46,20 +46,29 @@ const meta$1 = {
 const parserPlain = dist_exports;
 //#endregion
 //#region src/configs.ts
-const recommended = {
-	name: "oxfmt/recommended",
-	languageOptions: { parser: parserPlain },
-	plugins: { get oxfmt() {
+const recommendedWithoutParser = {
+	name: "oxfmt/recommended-without-parser",
+	plugins: { 
+	/* v8 ignore start */
+get oxfmt() {
 		return plugin;
 	} },
 	rules: { "oxfmt/oxfmt": "error" }
 };
-const configs = { recommended };
+const recommended = {
+	...recommendedWithoutParser,
+	name: "oxfmt/recommended",
+	languageOptions: { parser: parserPlain }
+};
+const configs = {
+	recommended,
+	recommendedWithoutParser
+};
 //#endregion
 //#region src/meta.ts
 const meta = {
 	name: "eslint-plugin-oxfmt",
-	version: "0.4.0"
+	version: "0.5.0"
 };
 //#endregion
 //#region src/dir.ts
@@ -550,9 +559,10 @@ const rules = { oxfmt: {
 					});
 				}
 				else reportDifferences(context, sourceText, formatResult.code);
-			} catch {
+			} catch (err) {
+				const details = err instanceof Error ? `: ${err.message}` : "";
 				context.report({
-					message: `Failed to format file: ${context.filename}`,
+					message: `Failed to format file: ${context.filename}${details}`,
 					loc: {
 						end: {
 							column: 0,
@@ -576,4 +586,4 @@ const plugin = {
 	rules
 };
 //#endregion
-export { configs, plugin as default, plugin, meta, parserPlain, recommended, rules };
+export { configs, plugin as default, plugin, meta, parserPlain, recommended, recommendedWithoutParser, rules };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "eslint-plugin-oxfmt",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "An ESLint plugin for formatting code with oxfmt.",
   "keywords": [
     "eslint",
@@ -48,31 +48,32 @@
   },
   "dependencies": {
     "generate-differences": "^0.1.1",
-    "load-oxfmt-config": "^0.4.0",
+    "load-oxfmt-config": "^0.4.1",
     "picomatch": "^4.0.4",
     "synckit": "^0.11.12"
   },
   "devDependencies": {
-    "@ntnyq/eslint-config": "^6.0.1",
+    "@ntnyq/eslint-config": "^6.1.0",
     "@types/json-schema": "^7.0.15",
     "@types/node": "^25.6.0",
-    "@typescript/native-preview": "^7.0.0-dev.20260413.1",
+    "@typescript/native-preview": "^7.0.0-dev.20260429.1",
     "bumpp": "^11.0.1",
-    "eslint": "^10.2.0",
+    "eslint": "^10.2.1",
     "eslint-parser-plain": "^0.1.1",
     "eslint-typegen": "^2.3.1",
     "eslint-vitest-rule-tester": "^3.1.0",
     "husky": "^9.1.7",
+    "jsonc-eslint-parser": "^3.1.0",
     "nano-staged": "^1.0.2",
     "npm-run-all2": "^8.0.4",
-    "oxfmt": "^0.45.0",
+    "oxfmt": "^0.47.0",
     "show-invisibles": "^0.0.2",
     "tinyglobby": "^0.2.16",
-    "tsdown": "^0.21.8",
+    "tsdown": "^0.21.10",
     "tsx": "^4.21.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.4",
-    "eslint-plugin-oxfmt": "0.4.0"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5",
+    "eslint-plugin-oxfmt": "0.5.0"
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"

package/workers/oxfmt.mjs

@@ -20,9 +20,21 @@ import { runAsWorker } from 'synckit'
  * @typedef {import('load-oxfmt-config').OxfmtOptions & PluginOptions} Options
  */
 
+/**
+ * @typedef {object} WorkerOptions
+ * @property {string} cwd Current working directory for resolving rule-relative inputs.
+ * @property {string | undefined} configPath Custom path to an oxfmt configuration file.
+ * @property {string[] | undefined} ignorePatterns Rule-level ignore patterns.
+ * @property {Override[] | undefined} overrides Rule-level override entries.
+ * @property {boolean} useConfig Whether config loading is enabled.
+ * @property {import('oxfmt').FormatConfig} formatOptions Pure formatter options passed to oxfmt.
+ */
+
 /**
  * @typedef {object} ResolvedBaseOptions
- * @property {import('oxfmt').FormatConfig} baseOptions Resolved base formatter options.
+ * @property {import('oxfmt').FormatConfig} formatOptions Resolved base formatter options.
+ * @property {string[] | undefined} ignorePatterns Resolved ignore patterns from config loading.
+ * @property {Override[] | undefined} overrides Resolved overrides from config loading.
  * @property {string} configDir Directory of the resolved config file, used as base for config-derived glob patterns.
  */
 
@@ -79,17 +91,14 @@ const picomatchCache = new Map()
 
 /**
  * Apply overrides to the base options based on the filename
- * @param filename - The file path
- * @param cwd - Base directory for glob matching
+ * @param relativePath - The file path relative to the glob base directory
  * @param baseOptions - Base format options
  * @param [overrides] - Override configurations
  * @returns - Merged options
  */
 function applyOverrides(
   /** @type {string} */
-  filename,
-  /** @type {string} */
-  cwd,
+  relativePath,
   /** @type {import('oxfmt').FormatConfig} */
   baseOptions,
   /** @type {Override[] | undefined} */
@@ -99,9 +108,6 @@ function applyOverrides(
     return baseOptions
   }
 
-  // Get relative path from cwd and normalize to forward slashes for cross-platform compatibility
-  const relativePath = relative(cwd, filename).replace(/\\/g, '/')
-
   let mergedOptions = baseOptions
   let hasOverrides = false
 
@@ -171,48 +177,48 @@ function getConfigPathForFile(
 
 /**
  * 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.
+ * The key only includes data that can affect the final formatter options.
  *
- * @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 relativePath - File path relative to the override base directory.
  * @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 {string | undefined} */
+  relativePath,
   /** @type {Override[] | undefined} */
   overrides,
-  /** @type {boolean} */
-  useConfig,
 ) {
+  const hasOverrides = !!(overrides && overrides.length > 0)
+
   return JSON.stringify(
     {
       baseOptions,
-      configDir,
-      cwd,
-      filename,
-      ignorePatterns,
-      overrides,
-      useConfig,
+      overrides: hasOverrides ? overrides : undefined,
+      relativePath: hasOverrides ? relativePath : undefined,
     },
     stableReplacer,
   )
 }
 
+/**
+ * Normalize a file path relative to the provided base directory.
+ * @param baseDir - Base directory used for glob evaluation
+ * @param filename - Absolute file path
+ * @returns - Normalized relative path using forward slashes
+ */
+function getRelativePath(
+  /** @type {string} */
+  baseDir,
+  /** @type {string} */
+  filename,
+) {
+  return relative(baseDir, filename).replace(/\\/g, '/')
+}
+
 /**
  * Build cache key for resolving base formatter options.
  * The key includes file directory and all resolution inputs.
@@ -248,6 +254,74 @@ function getResolvedBaseOptionsCacheKey(
   )
 }
 
+/**
+ * Validate and normalize worker invocation options.
+ * @param options - Raw worker options
+ * @returns - Validated worker options
+ */
+function getWorkerOptions(
+  /** @type {Options | undefined} */
+  options,
+) {
+  if (!options || typeof options !== 'object') {
+    throw new TypeError('oxfmt worker expected an options object.')
+  }
+
+  const {
+    configPath,
+    cwd,
+    ignorePatterns,
+    overrides,
+    useConfig = true,
+    ...formatOptions
+  } = options
+
+  if (typeof cwd !== 'string' || cwd.length === 0) {
+    throw new TypeError('oxfmt worker requires a non-empty "cwd" option.')
+  }
+  if (configPath != null && typeof configPath !== 'string') {
+    throw new TypeError(
+      'oxfmt worker requires "configPath" to be a string when provided.',
+    )
+  }
+  if (ignorePatterns != null && !isStringArray(ignorePatterns)) {
+    throw new TypeError(
+      'oxfmt worker requires "ignorePatterns" to be an array of strings when provided.',
+    )
+  }
+  if (overrides != null && !Array.isArray(overrides)) {
+    throw new TypeError(
+      'oxfmt worker requires "overrides" to be an array when provided.',
+    )
+  }
+  if (typeof useConfig !== 'boolean') {
+    throw new TypeError(
+      'oxfmt worker requires "useConfig" to be a boolean when provided.',
+    )
+  }
+
+  return {
+    configPath,
+    cwd,
+    formatOptions,
+    ignorePatterns,
+    overrides,
+    useConfig,
+  }
+}
+
+/**
+ * Check whether a value is an array of strings.
+ * @param value - Value to validate
+ * @returns - Whether the value is a string array
+ */
+function isStringArray(
+  /** @type {unknown} */
+  value,
+) {
+  return Array.isArray(value) && value.every(item => typeof item === 'string')
+}
+
 /**
  * Resolve base formatter options for a file and cache the async result.
  *
@@ -290,7 +364,9 @@ async function resolveBaseOptions(
     if (!useConfig) {
       return {
         configDir: cwd,
-        baseOptions: {
+        ignorePatterns: undefined,
+        overrides: undefined,
+        formatOptions: {
           ...formatOptions,
         },
       }
@@ -306,11 +382,15 @@ async function resolveBaseOptions(
       configPath: resolvedConfigPath,
       cwd: resolveFromDir,
     })
+    const { ignorePatterns, overrides, ...loadedFormatOptions } =
+      configOptions ?? {}
 
     return {
       configDir,
-      baseOptions: {
-        ...configOptions,
+      ignorePatterns,
+      overrides,
+      formatOptions: {
+        ...loadedFormatOptions,
         ...formatOptions,
       },
     }
@@ -329,26 +409,19 @@ async function resolveBaseOptions(
 
 /**
  * Check if a file should be ignored based on ignorePatterns
- * @param filename - The file path
- * @param cwd - Base directory for glob matching
+ * @param relativePath - The file path relative to the glob base directory
  * @param [ignorePatterns] - Ignore patterns
  * @returns - Whether the file should be ignored
  */
 function shouldIgnoreFile(
   /** @type {string} */
-  filename,
-  /** @type {string} */
-  cwd,
-  /** @type {string[] | undefined} */
-  ignorePatterns,
+  relativePath,
+  /** @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)
 }
@@ -371,65 +444,62 @@ runAsWorker(
     const {
       configPath,
       cwd,
+      formatOptions,
       ignorePatterns,
       overrides,
-      useConfig = true,
-      ...formatOptions
-    } = options
+      useConfig,
+    } = getWorkerOptions(options)
 
-    const { baseOptions, configDir } = await resolveBaseOptions(
+    const {
+      configDir,
+      formatOptions: baseFormatOptions,
+      ignorePatterns: baseIgnorePatterns,
+      overrides: baseOverrides,
+    } = 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)) {
+    const ignoreRelativePath = effectiveIgnorePatterns?.length
+      ? getRelativePath(ignoreBase, filename)
+      : undefined
+
+    if (
+      ignoreRelativePath &&
+      shouldIgnoreFile(ignoreRelativePath, effectiveIgnorePatterns)
+    ) {
       return { code: sourceText }
     }
 
+    const effectiveOverrides = useConfig ? baseOverrides : overrides
+    const overrideBase = useConfig ? configDir : cwd
+    const overrideRelativePath = effectiveOverrides?.length
+      ? getRelativePath(overrideBase, filename)
+      : undefined
+    const mergedOptionsCacheKey = getMergedOptionsCacheKey(
+      baseFormatOptions,
+      overrideRelativePath,
+      effectiveOverrides,
+    )
+
     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) {
+    let mergedOptions = baseFormatOptions
+    if (overrideRelativePath && effectiveOverrides?.length) {
       mergedOptions = applyOverrides(
-        filename,
-        configDir,
+        overrideRelativePath,
         mergedOptions,
-        baseOverrides,
+        effectiveOverrides,
       )
     }
 
-    // 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)