eslint-plugin-oxfmt 0.20.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.65.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.20.0"
+	version: "0.22.0"
 };
 //#endregion
 //#region src/dir.ts
@@ -317,7 +318,7 @@ const oxfmtOptionsSchema = {
 				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: [])`,
+						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\nIf you specify multiple conditions like elementNamePattern, selector, and modifiers,\nall conditions must be met for an import to match the custom group (AND logic).\n\nNOTE: Predefined group names (e.g. side_effect, external) and unknown are reserved and cannot be used as groupName.\n\n- (Default: [])`,
 						type: "array",
 						items: {
 							additionalProperties: false,
@@ -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.20.0",
+  "version": "0.22.0",
   "description": "An ESLint plugin for formatting code with oxfmt.",
   "keywords": [
     "eslint",
@@ -19,7 +19,7 @@
   "homepage": "https://github.com/ntnyq/eslint-plugin-oxfmt#readme",
   "repository": {
     "type": "git",
-    "url": "ntnyq/eslint-plugin-oxfmt"
+    "url": "git+https://github.com/ntnyq/eslint-plugin-oxfmt.git"
   },
   "bugs": {
     "url": "https://github.com/ntnyq/eslint-plugin-oxfmt/issues"
@@ -47,7 +47,7 @@
   "sideEffects": false,
   "peerDependencies": {
     "eslint": "^9.5.0 || ^10.0.0",
-    "oxfmt": ">=0.65.0",
+    "oxfmt": ">=0.67.0",
     "svelte": "*"
   },
   "peerDependenciesMeta": {
@@ -57,34 +57,34 @@
   },
   "dependencies": {
     "generate-differences": "^0.1.1",
-    "ignore": "^7.0.6",
-    "load-oxfmt-config": "^0.21.0",
+    "ignore": "^7.0.8",
+    "load-oxfmt-config": "^0.23.0",
     "picomatch": "^4.0.7",
     "synckit": "^0.11.13"
   },
   "devDependencies": {
-    "@ntnyq/eslint-config": "^7.0.0-beta.17",
+    "@ntnyq/eslint-config": "^7.0.0-beta.19",
     "@types/json-schema": "^7.0.15",
-    "@types/node": "^26.3.0",
+    "@types/node": "^26.5.0",
     "@typescript/native-preview": "^7.0.0-dev.20260707.2",
-    "bumpp": "^12.2.1",
-    "eslint": "^10.9.1",
+    "bumpp": "^12.3.0",
+    "eslint": "^10.10.0",
     "eslint-parser-plain": "^0.1.1",
-    "eslint-plugin-oxfmt": "0.20.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.65.0",
+    "oxfmt": "^0.67.0",
     "show-invisibles": "^0.0.2",
-    "svelte": "^5.56.10",
+    "svelte": "^5.57.0",
     "tinyglobby": "^0.2.17",
-    "tsdown": "^0.22.14",
-    "tsx": "^4.23.12",
+    "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',