eslint-plugin-oxfmt 0.21.0 → 0.22.0

package/README.md

@@ -22,7 +22,14 @@
 
 - **ESLint**: `>= 9.0.0` (Only supports ESLint flat config)
 - **Node.js**: `^20.19.0 || >=22.12.0`
-- **oxfmt**: `>= 0.66.0`
+- **oxfmt**: `>= 0.67.0`
+
+Oxfmt 0.67.0 preserves JSDoc cast parentheses containing comments, fixes
+CSS/SCSS/Less comment and list formatting, and moves GraphQL comments after
+an opening brace onto their own line. Existing files may receive formatting
+fixes after upgrading. No formatting options were renamed or removed, and
+config merge precedence is unchanged. See the
+[upstream release notes](https://github.com/oxc-project/oxc/releases/tag/oxfmt_v0.67.0).
 
 ## Installation
 
@@ -359,6 +366,8 @@ You can pass the Tailwind plugin options to control which attributes/functions a
 }
 ```
 
+Paths in `sortTailwindcss.config` and `sortTailwindcss.stylesheet` are resolved relative to the oxfmt config file when set in that file or its overrides. Paths set in ESLint rule options or rule-level overrides are resolved relative to ESLint `cwd`. Absolute paths are used directly.
+
 ## File-specific overrides
 
 Use `overrides` to apply different oxfmt options per file glob (later entries win on conflicts):

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Linter, Rule } from "eslint";
+import { Linter, Rule as Rule$1 } from "eslint";
 import "load-oxfmt-config";
 import "oxfmt";
 //#region src/types.d.ts
@@ -13,18 +13,18 @@ interface PluginOxfmt {
     version: string;
   };
   rules: {
-    oxfmt: Rule.RuleModule;
+    oxfmt: Rule$1.RuleModule;
   };
 }
 //#endregion
 //#region src/meta.d.ts
-declare const meta: {
+export declare const meta: {
   name: string;
   version: string;
 };
 //#endregion
 //#region src/rules/index.d.ts
-declare const rules: {
+export declare const rules: {
   oxfmt: import("eslint").Rule.RuleModule;
 };
 //#endregion
@@ -32,12 +32,12 @@ 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 cliParity: Linter.Config<Linter.RulesRecord>;
-declare const configs: PluginOxfmt['configs'];
+export declare const recommendedWithoutParser: Linter.Config<Linter.RulesRecord>;
+export declare const recommended: Linter.Config<Linter.RulesRecord>;
+export declare const cliParity: Linter.Config<Linter.RulesRecord>;
+export declare const configs: PluginOxfmt['configs'];
 //#endregion
 //#region src/index.d.ts
-declare const plugin: PluginOxfmt;
+export declare const plugin: PluginOxfmt;
 //#endregion
-export { cliParity, configs, plugin as default, plugin, meta, parserPlain, recommended, recommendedWithoutParser, rules };
+export { plugin as default, parserPlain };

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { Buffer as Buffer$1 } from "node:buffer";
 import { join } from "node:path";
 import { createSyncFn } from "synckit";
 import { URL, fileURLToPath } from "node:url";
@@ -79,7 +80,7 @@ const configs = {
 //#region src/meta.ts
 const meta = {
 	name: "eslint-plugin-oxfmt",
-	version: "0.21.0"
+	version: "0.22.0"
 };
 //#endregion
 //#region src/dir.ts
@@ -608,33 +609,35 @@ const rules = { oxfmt: {
 					cwd: context.cwd
 				});
 				if (formatResult.ignored) return;
-				if (formatResult.errors?.length) for (const error of formatResult.errors) {
-					const label = error.labels?.[0];
-					if (label) {
-						const start = context.sourceCode.getLocFromIndex(label.start);
-						const end = context.sourceCode.getLocFromIndex(label.end);
-						context.report({
+				if (formatResult.errors?.length) {
+					const sourceBytes = Buffer$1.from(sourceText);
+					for (const error of formatResult.errors) {
+						const label = error.labels?.[0];
+						if (label) {
+							const start = context.sourceCode.getLocFromIndex(sourceBytes.toString("utf8", 0, label.start).length);
+							const end = context.sourceCode.getLocFromIndex(sourceBytes.toString("utf8", 0, label.end).length);
+							context.report({
+								loc: {
+									end,
+									start
+								},
+								message: `Failed to format code: ${error.message}`
+							});
+						} else context.report({
+							message: `Failed to format code: ${error.message}`,
 							loc: {
-								end,
-								start
-							},
-							message: `Failed to format code: ${error.message}`
-						});
-					} else context.report({
-						message: `Failed to format code: ${error.message}`,
-						loc: {
-							end: {
-								column: 0,
-								line: 1
-							},
-							start: {
-								column: 0,
-								line: 1
+								end: {
+									column: 0,
+									line: 1
+								},
+								start: {
+									column: 0,
+									line: 1
+								}
 							}
-						}
-					});
-				}
-				else reportDifferences(context, sourceText, formatResult.code);
+						});
+					}
+				} else reportDifferences(context, sourceText, formatResult.code);
 			} catch (error) {
 				const details = error instanceof Error ? `: ${error.message}` : "";
 				context.report({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "eslint-plugin-oxfmt",
   "type": "module",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "An ESLint plugin for formatting code with oxfmt.",
   "keywords": [
     "eslint",
@@ -47,7 +47,7 @@
   "sideEffects": false,
   "peerDependencies": {
     "eslint": "^9.5.0 || ^10.0.0",
-    "oxfmt": ">=0.66.0",
+    "oxfmt": ">=0.67.0",
     "svelte": "*"
   },
   "peerDependenciesMeta": {
@@ -58,33 +58,33 @@
   "dependencies": {
     "generate-differences": "^0.1.1",
     "ignore": "^7.0.8",
-    "load-oxfmt-config": "^0.22.0",
+    "load-oxfmt-config": "^0.23.0",
     "picomatch": "^4.0.7",
     "synckit": "^0.11.13"
   },
   "devDependencies": {
     "@ntnyq/eslint-config": "^7.0.0-beta.19",
     "@types/json-schema": "^7.0.15",
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.5.0",
     "@typescript/native-preview": "^7.0.0-dev.20260707.2",
-    "bumpp": "^12.2.2",
-    "eslint": "^10.9.1",
+    "bumpp": "^12.3.0",
+    "eslint": "^10.10.0",
     "eslint-parser-plain": "^0.1.1",
-    "eslint-plugin-oxfmt": "0.21.0",
+    "eslint-plugin-oxfmt": "0.22.0",
     "eslint-typegen": "^2.3.1",
     "eslint-vitest-rule-tester": "^3.1.0",
     "husky": "^9.1.7",
     "jsonc-eslint-parser": "^3.3.0",
     "nano-staged": "^1.0.2",
     "npm-run-all2": "^9.0.3",
-    "oxfmt": "^0.66.0",
+    "oxfmt": "^0.67.0",
     "show-invisibles": "^0.0.2",
     "svelte": "^5.57.0",
     "tinyglobby": "^0.2.17",
-    "tsdown": "^0.22.14",
+    "tsdown": "^0.23.0",
     "tsx": "^4.23.13",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": "^20.19.0 || >=22.12.0"

package/workers/oxfmt.mjs

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { dirname, extname, relative } from 'node:path'
+import { dirname, extname, relative, resolve } from 'node:path'
 import ignore from 'ignore'
 import { isOxfmtIgnored, loadOxfmtConfig } from 'load-oxfmt-config'
 import { format } from 'oxfmt'
@@ -8,6 +8,7 @@ import picomatch from 'picomatch'
 import { runAsWorker } from 'synckit'
 
 /**
+ * Options consumed by the worker instead of the formatter.
  * @typedef {object} PluginOnlyOptions
  * @property {string} [cwd] - Base working directory used for path resolution.
  * @property {string} [configPath] - Explicit path to oxfmt config file.
@@ -21,10 +22,17 @@ import { runAsWorker } from 'synckit'
  */
 
 /**
- * @typedef {PluginOnlyOptions & import('load-oxfmt-config').LoadOxfmtConfigOptions & import('oxfmt').FormatConfig} PluginOptions
+ * Formatting options, ignore patterns, and file-specific overrides.
+ * @typedef {import('load-oxfmt-config').OxfmtOptions} OxfmtOptions
  */
 
 /**
+ * Combined rule options accepted by the worker.
+ * @typedef {PluginOnlyOptions & import('load-oxfmt-config').LoadOxfmtConfigOptions & OxfmtOptions} PluginOptions
+ */
+
+/**
+ * Result returned when ignore handling skips a file.
  * @typedef {object} WorkerIgnoredResult
  * @property {true} ignored - Indicates formatting was skipped due to ignore rules.
  * @property {import('load-oxfmt-config').IsOxfmtIgnoredResult['reason']} [reason] - Ignore reason from resolution step.
@@ -33,6 +41,7 @@ import { runAsWorker } from 'synckit'
  */
 
 /**
+ * Result returned after attempting to format a file.
  * @typedef {object} WorkerFormattedResult
  * @property {false} [ignored] - False or undefined when formatting was attempted.
  * @property {string} code - Formatted source code.
@@ -40,20 +49,31 @@ import { runAsWorker } from 'synckit'
  */
 
 /**
+ * Worker response for either ignored or formatted source text.
  * @typedef {WorkerIgnoredResult | WorkerFormattedResult} WorkerFormatResult
  */
 
 /**
+ * Worker controls separated from formatting and file-matching options.
  * @typedef {object} SplitOptionsResult
  * @property {PluginOnlyOptions} pluginOptions - Plugin orchestration options.
- * @property {import('oxfmt').FormatConfig} formatOptions - Pure oxfmt options.
+ * @property {OxfmtOptions} formatOptions - Oxfmt options including ignorePatterns and overrides.
  */
 
 /**
+ * A file-matching override loaded from config or supplied inline.
  * @typedef {import('load-oxfmt-config').OxfmtConfigOverride} OxfmtConfigOverride
  */
 
+/**
+ * Maximum number of compiled matchers retained in each worker cache.
+ * @type {number}
+ */
 const MAX_CACHE_SIZE = 200
+/**
+ * Option names consumed by worker orchestration.
+ * @type {Set<string>}
+ */
 const PLUGIN_ONLY_OPTIONS = new Set([
   'configPath',
   'cwd',
@@ -65,9 +85,15 @@ const PLUGIN_ONLY_OPTIONS = new Set([
   'useConfig',
   'withNodeModules',
 ])
-/** @type {Map<string, import('picomatch').Matcher>} */
+/**
+ * Compiled override globs keyed by their ordered pattern list.
+ * @type {Map<string, import('picomatch').Matcher>}
+ */
 const overrideMatcherCache = new Map()
-/** @type {Map<string, import('ignore').Ignore>} */
+/**
+ * Compiled gitignore-style rules keyed by their ordered pattern list.
+ * @type {Map<string, import('ignore').Ignore>}
+ */
 const ignoreMatcherCache = new Map()
 
 /**
@@ -75,13 +101,18 @@ const ignoreMatcherCache = new Map()
  * @param {string} relativePath - Relative file path used for matching.
  * @param {import('oxfmt').FormatConfig} baseOptions - Base format options.
  * @param {OxfmtConfigOverride[] | undefined} overrides - Override entries.
+ * @param {string} optionsBaseDir - Base directory for paths inside override options.
  * @returns {import('oxfmt').FormatConfig} Options after override merge.
  */
-function applyOverrides(relativePath, baseOptions, overrides) {
+function applyOverrides(relativePath, baseOptions, overrides, optionsBaseDir) {
   if (!overrides?.length) {
     return baseOptions
   }
 
+  /**
+   * Format options after applying each matching override in order.
+   * @type {import('oxfmt').FormatConfig}
+   */
   let merged = baseOptions
   for (const override of overrides) {
     if (!override?.files?.length) {
@@ -99,7 +130,7 @@ function applyOverrides(relativePath, baseOptions, overrides) {
     if (matches && !excluded && override.options) {
       merged = {
         ...merged,
-        ...override.options,
+        ...resolveTailwindPaths(override.options, optionsBaseDir),
       }
     }
   }
@@ -123,6 +154,10 @@ async function formatViaOxfmt(filename, sourceText, options = {}) {
   const useConfig = pluginOptions.useConfig !== false
   const useCache = getUseCacheOption(pluginOptions)
 
+  /**
+   * Inline ignore patterns matched relative to ESLint cwd.
+   * @type {string[] | undefined}
+   */
   const ruleIgnorePatterns = isStringArray(inlineFormatOptions.ignorePatterns)
     ? inlineFormatOptions.ignorePatterns
     : undefined
@@ -138,7 +173,10 @@ async function formatViaOxfmt(filename, sourceText, options = {}) {
   }
 
   if (pluginOptions.respectOxfmtDefaultIgnores !== false && cwd) {
-    /** @type {import('load-oxfmt-config').IsOxfmtIgnoredOptions} */
+    /**
+     * Config and ignore resolution settings for the current file.
+     * @type {import('load-oxfmt-config').IsOxfmtIgnoredOptions}
+     */
     const ignoredOptions = {
       configPath: pluginOptions.configPath,
       cwd,
@@ -168,12 +206,30 @@ async function formatViaOxfmt(filename, sourceText, options = {}) {
     }
   }
 
-  /** @type {OxfmtConfigOverride[] | undefined} */
-  let effectiveOverrides
-  /** @type {string} */
-  let overrideBaseDir = cwd ?? dirname(filename)
-  /** @type {import('oxfmt').FormatConfig} */
-  let finalOptions
+  /**
+   * Base directory for paths supplied in inline rule options.
+   * @type {string}
+   */
+  const inlineBaseDir = cwd ?? dirname(filename)
+  /**
+   * Base for override globs and config-derived paths, updated after discovery.
+   * @type {string}
+   */
+  let overrideBaseDir = inlineBaseDir
+  /**
+   * Inline overrides separated from root options to preserve merge order.
+   * @type {OxfmtOptions}
+   */
+  const { overrides: ruleOverrides, ...inlineOptionsWithoutOverrides } =
+    inlineFormatOptions
+  /**
+   * Effective formatter options with paths resolved against their source.
+   * @type {import('oxfmt').FormatConfig}
+   */
+  let finalOptions = resolveTailwindPaths(
+    inlineOptionsWithoutOverrides,
+    inlineBaseDir,
+  )
 
   if (useConfig) {
     const loaded = await loadOxfmtConfig({
@@ -185,34 +241,26 @@ async function formatViaOxfmt(filename, sourceText, options = {}) {
       useCache,
     })
     const { overrides: configOverrides, ...loadedConfig } = loaded.config
-    const { overrides: ruleOverrides, ...inlineOptionsWithoutOverrides } =
-      inlineFormatOptions
-    effectiveOverrides = [
-      ...(configOverrides ?? []),
-      ...(Array.isArray(ruleOverrides) ? ruleOverrides : []),
-    ]
     overrideBaseDir = loaded.dirname ?? overrideBaseDir
 
     finalOptions = {
-      ...loadedConfig,
-      ...inlineOptionsWithoutOverrides,
-    }
-  } else {
-    const { overrides: ruleOverrides, ...inlineOptionsWithoutOverrides } =
-      inlineFormatOptions
-    effectiveOverrides = Array.isArray(ruleOverrides)
-      ? ruleOverrides
-      : undefined
-    finalOptions = {
-      ...inlineOptionsWithoutOverrides,
+      ...resolveTailwindPaths(loadedConfig, overrideBaseDir),
+      ...finalOptions,
     }
+    finalOptions = applyOverrides(
+      getRelativePath(overrideBaseDir, filename),
+      finalOptions,
+      configOverrides,
+      overrideBaseDir,
+    )
   }
 
   const overrideRelativePath = getRelativePath(overrideBaseDir, filename)
   finalOptions = applyOverrides(
     overrideRelativePath,
     finalOptions,
-    effectiveOverrides,
+    Array.isArray(ruleOverrides) ? ruleOverrides : undefined,
+    inlineBaseDir,
   )
 
   return format(filename, sourceText, finalOptions)
@@ -239,6 +287,7 @@ function getCachedIgnoreMatcher(patterns) {
  * Get or create a cached picomatch matcher for oxfmt override globs.
  * @param {string[]} patterns - Glob patterns.
  * @returns {import('picomatch').Matcher} Compiled matcher.
+ * @throws {Error} If a pattern contains invalid glob syntax.
  */
 function getCachedOverrideMatcher(patterns) {
   const key = patterns.join('\0')
@@ -247,6 +296,10 @@ function getCachedOverrideMatcher(patterns) {
     return cached
   }
 
+  /**
+   * Match oxfmt's dotfile and literal-extglob behavior.
+   * @type {{dot: boolean, noextglob: boolean, strictBrackets: boolean}}
+   */
   const matcherOptions = {
     dot: true,
     noextglob: true,
@@ -306,6 +359,33 @@ function isStringArray(value) {
   return Array.isArray(value) && value.every(item => typeof item === 'string')
 }
 
+/**
+ * Resolve Tailwind paths before merging options from different sources.
+ * @param {import('oxfmt').FormatConfig} options - Format options to normalize.
+ * @param {string} baseDir - Config directory or ESLint cwd for inline options.
+ * @returns {import('oxfmt').FormatConfig} Options with absolute Tailwind paths.
+ */
+function resolveTailwindPaths(options, baseDir) {
+  const { sortTailwindcss } = options
+  if (!sortTailwindcss || typeof sortTailwindcss !== 'object') {
+    return options
+  }
+
+  /**
+   * Copy paths before resolving them to avoid mutating cached config objects.
+   * @type {import('oxfmt').SortTailwindcssConfig}
+   */
+  const resolved = { ...sortTailwindcss }
+  if (resolved.config) {
+    resolved.config = resolve(baseDir, resolved.config)
+  }
+  if (resolved.stylesheet) {
+    resolved.stylesheet = resolve(baseDir, resolved.stylesheet)
+  }
+
+  return { ...options, sortTailwindcss: resolved }
+}
+
 /**
  * Store a value in a FIFO cache map with a bounded size.
  * @template T Cache value type.
@@ -324,9 +404,9 @@ function setCacheEntry(cache, key, value) {
 }
 
 /**
- * Check if a file should be ignored by provided glob patterns.
+ * Check if a file should be ignored by provided gitignore-style patterns.
  * @param {string} relativePath - Relative path against pattern base.
- * @param {string[] | undefined} ignorePatterns - Glob patterns.
+ * @param {string[] | undefined} ignorePatterns - Ordered gitignore-style patterns.
  * @returns {boolean} Whether file is ignored.
  */
 function shouldIgnoreFile(relativePath, ignorePatterns) {
@@ -339,14 +419,20 @@ function shouldIgnoreFile(relativePath, ignorePatterns) {
 }
 
 /**
- * Split worker options into plugin orchestration options and pure format options.
+ * Split worker controls from oxfmt options, ignore patterns, and overrides.
  * @param {PluginOptions} [options] - Raw worker options.
  * @returns {SplitOptionsResult} Split option buckets.
  */
 function splitOptions(options = {}) {
-  /** @type {Record<string, unknown>} */
+  /**
+   * Options consumed by config loading and ignore orchestration.
+   * @type {Record<string, unknown>}
+   */
   const pluginOptions = {}
-  /** @type {Record<string, unknown>} */
+  /**
+   * Remaining oxfmt options, including file-matching configuration.
+   * @type {Record<string, unknown>}
+   */
   const formatOptions = {}
 
   for (const [key, value] of Object.entries(options)) {
@@ -358,7 +444,7 @@ function splitOptions(options = {}) {
   }
 
   return {
-    formatOptions: /** @type {import('oxfmt').FormatConfig} */ (formatOptions),
+    formatOptions: /** @type {OxfmtOptions} */ (formatOptions),
     pluginOptions: /** @type {PluginOnlyOptions} */ (pluginOptions),
   }
 }
@@ -366,11 +452,19 @@ function splitOptions(options = {}) {
 /**
  * Validate plugin-only options before dispatching to helper libraries.
  * @param {PluginOnlyOptions} pluginOptions - Plugin-only options.
+ * @returns {void}
+ * @throws {TypeError} If a supported plugin option has an invalid value type.
  */
 function validatePluginOptions(pluginOptions) {
-  /** @type {('cwd' | 'configPath')[]} */
+  /**
+   * Plugin options validated as strings when provided.
+   * @type {('cwd' | 'configPath')[]}
+   */
   const stringKeys = ['configPath', 'cwd']
-  /** @type {('disableNestedConfig' | 'respectOxfmtDefaultIgnores' | 'useConfig' | 'useCache' | 'withNodeModules')[]} */
+  /**
+   * Plugin switches validated as booleans when provided.
+   * @type {('disableNestedConfig' | 'respectOxfmtDefaultIgnores' | 'useConfig' | 'useCache' | 'withNodeModules')[]}
+   */
   const booleanKeys = [
     'disableNestedConfig',
     'respectOxfmtDefaultIgnores',