load-oxfmt-config 0.23.0 → 0.25.0

package/README.md

@@ -1,12 +1,14 @@
 # load-oxfmt-config
 
-[![CI](https://github.com/ntnyq/load-oxfmt-config/workflows/CI/badge.svg)](https://github.com/ntnyq/load-oxfmt-config/actions)
+[![CI](https://github.com/ntnyq/eslint-plugin-oxfmt/workflows/CI/badge.svg)](https://github.com/ntnyq/eslint-plugin-oxfmt/actions)
 [![NPM VERSION](https://img.shields.io/npm/v/load-oxfmt-config.svg)](https://www.npmjs.com/package/load-oxfmt-config)
 [![NPM DOWNLOADS](https://img.shields.io/npm/dy/load-oxfmt-config.svg)](https://www.npmjs.com/package/load-oxfmt-config)
-[![LICENSE](https://img.shields.io/github/license/ntnyq/load-oxfmt-config.svg)](https://github.com/ntnyq/load-oxfmt-config/blob/main/LICENSE)
+[![LICENSE](https://img.shields.io/github/license/ntnyq/eslint-plugin-oxfmt.svg)](https://github.com/ntnyq/eslint-plugin-oxfmt/blob/main/LICENSE)
 
 > Load and resolve oxfmt configuration files, including explicit JS/TS config paths, and merge supported `.editorconfig` settings for [oxfmt](https://oxc.rs/docs/guide/usage/formatter.html).
 
+Maintained in the [eslint-plugin-oxfmt monorepo](https://github.com/ntnyq/eslint-plugin-oxfmt). See the root README for development and release instructions.
+
 ## Features
 
 - 🔍 **Auto-discovery** - Automatically searches for config files in current and parent directories
@@ -20,18 +22,18 @@
 ## Install
 
 ```shell
-npm install load-oxfmt-config
+npm install oxfmt load-oxfmt-config
 ```
 
 ```shell
-yarn add load-oxfmt-config
+yarn add oxfmt load-oxfmt-config
 ```
 
 ```shell
-pnpm add load-oxfmt-config
+pnpm add oxfmt load-oxfmt-config
 ```
 
-> `oxfmt` is a peer dependency and should be installed alongside this package.
+> `oxfmt >=0.70.0` is a peer dependency and is installed alongside this package.
 > Node.js `^22.13.0 || >=24` is supported.
 
 ## Usage
@@ -76,6 +78,27 @@ const result = await loadOxfmtConfig({
 })
 ```
 
+### Resolve EditorConfig for One File
+
+Use `loadOxfmtConfigForFile()` when formatting a specific file, especially when
+its oxfmt config and `.editorconfig` live in different directories:
+
+```ts
+import { loadOxfmtConfigForFile } from 'load-oxfmt-config'
+
+const result = await loadOxfmtConfigForFile({
+  cwd: '/path/to/project',
+  filepath: 'packages/app/src/index.ts',
+})
+```
+
+This accepts the same options as `loadOxfmtConfig()`, with `filepath` required.
+EditorConfig sections are matched relative to their own directory and applied
+in source order, including later `[*]` sections. The resulting EditorConfig
+defaults are merged below explicit oxfmt root options. Explicit oxfmt `overrides`
+remain in the returned config and must still be applied by the caller, relative
+to `result.dirname`. Config metadata retains the same meaning as in the static API.
+
 ### Get Config Metadata
 
 ```ts
@@ -342,6 +365,16 @@ Whether to use in-memory cache.
 
 Whether to include ignore patterns defined in the resolved config file.
 
+#### `includeDefaultIgnores`
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to apply default directories, lockfiles, and ignore files (`.gitignore`,
+Git info exclude, `.prettierignore`, and explicit `ignorePath` files).
+Set to `false` to evaluate only config `ignorePatterns`. This does not disable
+config loading or matching; use the separate config options for that.
+
 #### `loadConfigForIgnorePatterns`
 
 - **Type:** `boolean`
@@ -435,7 +468,12 @@ The loader reads the nearest `.editorconfig` file and maps the subset of fields
 - `insert_final_newline` → `insertFinalNewline`
 - `quote_type` → `singleQuote`
 
-Only `[*]` is treated as a global section to match oxfmt. Other sections such as `[**]` and `[*.ts]` are converted into returned `overrides` entries.
+In the static API, `[*]` provides root defaults. A `[*]` section after scoped
+sections also generates an override to preserve source order. Other sections
+such as `[**]` and `[*.ts]` are converted into returned `overrides` entries;
+basename patterns such as `*.ts` are normalized to `**/*.ts` to match descendants.
+The per-file API evaluates matching sections directly, without rebasing them to
+the oxfmt config directory.
 
 ## Ignore Strategy
 
@@ -483,7 +521,12 @@ Section-specific `.editorconfig` entries are represented as generated `overrides
 
 ## Limitations
 
-`loadOxfmtConfig()` returns a static merged `OxfmtOptions` shape. That means `.editorconfig` support is represented as merged root + overrides config data, not as per-file runtime evaluation. In practice this works well for common root settings and section-based overrides, but it is not a full replacement for oxfmt's own file-by-file config resolution.
+`loadOxfmtConfig()` returns a static merged `OxfmtOptions` shape. Its generated
+EditorConfig globs cannot represent every relationship between config directories,
+particularly an ancestor EditorConfig with a nested oxfmt config. Use
+`loadOxfmtConfigForFile()` to resolve EditorConfig against its original directory
+for a specific target file. Both APIs retain the nearest-file discovery strategy;
+they do not merge multiple EditorConfig files.
 
 ## Error Handling
 
@@ -501,16 +544,19 @@ try {
 
 ## Caching Behavior
 
-The caching system maintains two separate caches:
+The caching system maintains bounded caches for:
 
 1. **Path Resolution Cache:** Stores resolved config file paths
-2. **Config Content Cache:** Stores parsed configuration objects
+2. **Config Sources:** Shares parsed oxfmt files and EditorConfig sections between target files
+3. **Config Results:** Stores merged static or per-file configuration objects
+4. **EditorConfig Matchers:** Reuses compiled section patterns
 
 **Cache keys are based on:**
 
 - `cwd` + `configPath` for path resolution
 - or `dirname(filepath)` + `configPath` when `filepath` is provided and nested lookup is enabled
 - Resolved oxfmt path and resolved `.editorconfig` path for config content
+- The target file path for per-file results, isolated from static results
 
 **Cache invalidation:**
 
@@ -527,4 +573,4 @@ The caching system maintains two separate caches:
 
 ## License
 
-[MIT](./LICENSE) License © 2025-PRESENT [ntnyq](https://github.com/ntnyq)
+[MIT](https://github.com/ntnyq/eslint-plugin-oxfmt/blob/main/LICENSE) License © 2025-PRESENT [ntnyq](https://github.com/ntnyq)

package/dist/index.d.mts

@@ -4,13 +4,6 @@ import { FormatConfig } from "oxfmt";
  * Object-form `.editorconfig` option for fine-grained lookup control.
  */
 export interface EditorconfigOption {
-  /**
-   * When `true`, only look for `.editorconfig` in the `cwd` directory itself
-   * (no upward traversal).
-   *
-   * @default false
-   */
-  onlyCwd?: boolean;
   /**
    * Override the directory from which `.editorconfig` resolution starts.
    *
@@ -20,23 +13,92 @@ export interface EditorconfigOption {
    * directory, such as each file's directory.
    */
   cwd?: string;
+  /**
+   * When `true`, only look for `.editorconfig` in the `cwd` directory itself
+   * (no upward traversal).
+   *
+   * @default false
+   */
+  onlyCwd?: boolean;
 }
 /**
- * Format option override for a single matching rule.
+ * Options for resolving whether a single file should be ignored.
  */
-export interface OxfmtConfigOverride {
+export interface IsOxfmtIgnoredOptions {
   /**
-   * Glob patterns to match files.
+   * File path to test.
    */
-  files: string[];
+  filepath: string;
   /**
-   * Glob patterns to exclude files.
+   * Explicit oxfmt config path.
+   *
+   * When provided, nested config lookup is disabled (same as oxfmt CLI -c).
    */
-  excludeFiles?: string[];
+  configPath?: string;
   /**
-   * Format options to apply.
+   * Current working directory.
+   *
+   * Also the base directory for default `.prettierignore` lookup.
    */
-  options?: FormatConfig;
+  cwd?: string;
+  /**
+   * Disable nested config lookup.
+   *
+   * @default false
+   */
+  disableNestedConfig?: boolean;
+  /**
+   * Ignore files to use instead of the default cwd `.prettierignore`.
+   *
+   * Explicit ignore paths do not replace `.gitignore` or `.git/info/exclude`
+   * handling. They can be passed multiple times in CLI style.
+   */
+  ignorePath?: string | string[];
+  /**
+   * Whether to include ignore patterns defined in the config file.
+   *
+   * @default true
+   */
+  includeConfigIgnorePatterns?: boolean;
+  /**
+   * Apply default directories, lockfiles, and ignore files independently of config patterns.
+   *
+   * @default true
+   */
+  includeDefaultIgnores?: boolean;
+  /**
+   * Whether to load resolved oxfmt config when evaluating config ignore patterns.
+   *
+   * When false, only global ignore is applied and config loading is skipped.
+   *
+   * @default true
+   */
+  loadConfigForIgnorePatterns?: boolean;
+  /**
+   * Whether to use in-memory cache.
+   *
+   * @default true
+   */
+  useCache?: boolean;
+  /**
+   * Whether node_modules should be included.
+   *
+   * @default false
+   */
+  withNodeModules?: boolean;
+}
+/**
+ * Ignore resolution result.
+ */
+export interface IsOxfmtIgnoredResult {
+  /**
+   * Whether the file should be ignored.
+   */
+  ignored: boolean;
+  /**
+   * Matched ignore source when `ignored` is true.
+   */
+  reason?: 'config-ignore-patterns' | 'default-dir' | 'git-info-exclude' | 'gitignore' | 'ignore-path' | 'lockfile' | 'prettierignore';
 }
 /**
  * Options for loading and merging oxfmt configuration.
@@ -50,12 +112,6 @@ export interface LoadOxfmtConfigOptions {
    * Current working directory.
    */
   cwd?: string;
-  /**
-   * File path being formatted. When provided (and `configPath` is not set),
-   * config discovery starts from this file's directory to match oxfmt nested
-   * config behavior.
-   */
-  filepath?: string;
   /**
    * Disable nested config lookup.
    * When true, config discovery is anchored to `cwd` (or explicit `configPath`).
@@ -63,12 +119,6 @@ export interface LoadOxfmtConfigOptions {
    * @default false
    */
   disableNestedConfig?: boolean;
-  /**
-   * Whether to use in-memory caches for path resolution and parsed config contents.
-   *
-   * @default true
-   */
-  useCache?: boolean;
   /**
    * Control `.editorconfig` reading.
    * - `true` (default): read and merge `.editorconfig`, walking up from the config
@@ -79,22 +129,18 @@ export interface LoadOxfmtConfigOptions {
    * @default true
    */
   editorconfig?: boolean | EditorconfigOption;
-}
-/**
- * Final oxfmt options, including config `ignorePatterns` and `overrides`.
- */
-export interface OxfmtOptions extends FormatConfig {
   /**
-   * Ignore files matching these glob patterns.
-   *
-   * Patterns use gitignore-style matching rooted at the oxfmt configuration
-   * directory. Parent-directory (`..`) path segments are rejected.
+   * File path being formatted. When provided (and `configPath` is not set),
+   * config discovery starts from this file's directory to match oxfmt nested
+   * config behavior.
    */
-  ignorePatterns?: string[];
+  filepath?: string;
   /**
-   * Array of format option overrides.
+   * Whether to use in-memory caches for path resolution and parsed config contents.
+   *
+   * @default true
    */
-  overrides?: OxfmtConfigOverride[];
+  useCache?: boolean;
 }
 /**
  * Result object with metadata about resolved oxfmt config.
@@ -104,87 +150,47 @@ export interface LoadOxfmtConfigResult {
    * Final merged config from oxfmt and optional `.editorconfig` mapping.
    */
   config: OxfmtOptions;
-  /**
-   * Absolute path of resolved config file.
-   */
-  filepath?: string;
   /**
    * Directory of resolved config file.
    */
   dirname?: string;
+  /**
+   * Absolute path of resolved config file.
+   */
+  filepath?: string;
 }
 /**
- * Options for resolving whether a single file should be ignored.
+ * Format option override for a single matching rule.
  */
-export interface IsOxfmtIgnoredOptions {
-  /**
-   * Current working directory.
-   *
-   * Also the base directory for default `.prettierignore` lookup.
-   */
-  cwd?: string;
-  /**
-   * File path to test.
-   */
-  filepath: string;
-  /**
-   * Explicit oxfmt config path.
-   *
-   * When provided, nested config lookup is disabled (same as oxfmt CLI -c).
-   */
-  configPath?: string;
-  /**
-   * Ignore files to use instead of the default cwd `.prettierignore`.
-   *
-   * Explicit ignore paths do not replace `.gitignore` or `.git/info/exclude`
-   * handling. They can be passed multiple times in CLI style.
-   */
-  ignorePath?: string | string[];
-  /**
-   * Whether node_modules should be included.
-   *
-   * @default false
-   */
-  withNodeModules?: boolean;
-  /**
-   * Disable nested config lookup.
-   *
-   * @default false
-   */
-  disableNestedConfig?: boolean;
+export interface OxfmtConfigOverride {
   /**
-   * Whether to use in-memory cache.
-   *
-   * @default true
+   * Glob patterns to match files.
    */
-  useCache?: boolean;
+  files: string[];
   /**
-   * Whether to include ignore patterns defined in the config file.
-   *
-   * @default true
+   * Glob patterns to exclude files.
    */
-  includeConfigIgnorePatterns?: boolean;
+  excludeFiles?: string[];
   /**
-   * Whether to load resolved oxfmt config when evaluating config ignore patterns.
-   *
-   * When false, only global ignore is applied and config loading is skipped.
-   *
-   * @default true
+   * Format options to apply.
    */
-  loadConfigForIgnorePatterns?: boolean;
+  options?: FormatConfig;
 }
 /**
- * Ignore resolution result.
+ * Final oxfmt options, including config `ignorePatterns` and `overrides`.
  */
-export interface IsOxfmtIgnoredResult {
+export interface OxfmtOptions extends FormatConfig {
   /**
-   * Whether the file should be ignored.
+   * Ignore files matching these glob patterns.
+   *
+   * Patterns use gitignore-style matching rooted at the oxfmt configuration
+   * directory. Parent-directory (`..`) path segments are rejected.
    */
-  ignored: boolean;
+  ignorePatterns?: string[];
   /**
-   * Matched ignore source when `ignored` is true.
+   * Array of format option overrides.
    */
-  reason?: 'default-dir' | 'lockfile' | 'gitignore' | 'git-info-exclude' | 'prettierignore' | 'ignore-path' | 'config-ignore-patterns';
+  overrides?: OxfmtConfigOverride[];
 }
 //#endregion
 //#region src/core.d.ts
@@ -203,27 +209,27 @@ export interface IsOxfmtIgnoredResult {
  * ```
  */
 export declare function loadOxfmtConfig(options?: LoadOxfmtConfigOptions): Promise<LoadOxfmtConfigResult>;
-//#endregion
-//#region src/ignore.d.ts
 /**
- * Resolve whether a file should be ignored using oxfmt-like CLI semantics.
+ * Load config with EditorConfig fallbacks resolved for one file.
+ * Explicit oxfmt overrides remain unevaluated and retain their config-relative globs.
  *
- * @param options - Ignore resolution options.
- * @returns Ignore status with optional reason.
- *
- * @example
- * ```ts
- * import { isOxfmtIgnored } from 'load-oxfmt-config'
- *
- * const result = await isOxfmtIgnored({
- *   cwd: process.cwd(),
- *   filepath: 'src/generated/file.ts',
- * })
- * ```
+ * @param options - Loader settings with the target file path.
+ * @returns Config with per-file EditorConfig defaults and config metadata.
  */
-export declare function isOxfmtIgnored(options: IsOxfmtIgnoredOptions): Promise<IsOxfmtIgnoredResult>;
+export declare function loadOxfmtConfigForFile(options: LoadOxfmtConfigOptions & {
+  filepath: string;
+}): Promise<LoadOxfmtConfigResult>;
 //#endregion
 //#region src/config.d.ts
+/**
+ * Build a cache key for config content; prefixes missing entries.
+ *
+ * @param resolvedPath - Resolved oxfmt config path.
+ * @param editorconfigPath - Resolved editorconfig path.
+ * @param resolveKey - Resolution cache key.
+ * @returns Cache key for config content cache.
+ */
+export declare function getConfigCacheKey(resolvedPath: string | undefined, editorconfigPath: string | undefined, resolveKey: string): string;
 /**
  * Build a cache key for path resolution (cwd + configPath).
  *
@@ -233,14 +239,16 @@ export declare function isOxfmtIgnored(options: IsOxfmtIgnoredOptions): Promise<
  */
 export declare function getResolveCacheKey(cwd: string, configPath?: string): string;
 /**
- * Build a cache key for config content; prefixes missing entries.
+ * Read and parse an oxfmt config file.
  *
- * @param resolvedPath - Resolved oxfmt config path.
- * @param editorconfigPath - Resolved editorconfig path.
- * @param resolveKey - Resolution cache key.
- * @returns Cache key for config content cache.
+ * @param resolvedPath - Absolute path to config file.
+ * @param options - Config loading options.
+ * @param options.useCache - Whether to reuse cached config modules.
+ * @returns Parsed config object.
  */
-export declare function getConfigCacheKey(resolvedPath: string | undefined, editorconfigPath: string | undefined, resolveKey: string): string;
+export declare function readConfigFromFile(resolvedPath: string, options?: {
+  useCache?: boolean;
+}): Promise<OxfmtOptions>;
 /**
  * Resolve the oxfmt config file path.
  *
@@ -260,14 +268,23 @@ export declare function getConfigCacheKey(resolvedPath: string | undefined, edit
  * ```
  */
 export declare function resolveOxfmtrcPath(cwd: string, configPath?: string): Promise<string | undefined>;
+//#endregion
+//#region src/ignore.d.ts
 /**
- * Read and parse an oxfmt config file.
+ * Resolve whether a file should be ignored using oxfmt-like CLI semantics.
  *
- * @param resolvedPath - Absolute path to config file.
- * @param options - Config loading options.
- * @returns Parsed config object.
+ * @param options - Ignore resolution options.
+ * @returns Ignore status with optional reason.
+ *
+ * @example
+ * ```ts
+ * import { isOxfmtIgnored } from 'load-oxfmt-config'
+ *
+ * const result = await isOxfmtIgnored({
+ *   cwd: process.cwd(),
+ *   filepath: 'src/generated/file.ts',
+ * })
+ * ```
  */
-export declare function readConfigFromFile(resolvedPath: string, options?: {
-  useCache?: boolean;
-}): Promise<OxfmtOptions>;
+export declare function isOxfmtIgnored(options: IsOxfmtIgnoredOptions): Promise<IsOxfmtIgnoredResult>;
 //#endregion