load-oxfmt-config 0.4.1 → 0.6.0

package/README.md

@@ -12,6 +12,7 @@
 - 🔍 **Auto-discovery** - Automatically searches for config files in current and parent directories
 - 📦 **Multiple formats** - Supports `.oxfmtrc.json`, `.oxfmtrc.jsonc`, and `oxfmt.config.ts`
 - 🧩 **EditorConfig fallback** - Merges supported `.editorconfig` fields into the returned oxfmt config result
+- 🚫 **Ignore resolution** - Resolves ignore status with oxfmt CLI-like global + config-scoped semantics
 - ⚡ **Built-in caching** - Caches both file resolution and parsed configs for optimal performance
 - 🎯 **TypeScript support** - Fully typed with comprehensive type definitions
 - 🛠️ **Flexible API** - Support explicit config paths or automatic discovery
@@ -37,22 +38,22 @@ pnpm add load-oxfmt-config
 Load config from current directory or parent directories:
 
 ```ts
-import { loadOxfmtConfig } from 'load-oxfmt-config'
+import { loadOxfmtConfigResult } from 'load-oxfmt-config'
 
 // Automatically searches for oxfmt config files and the nearest .editorconfig
-const config = await loadOxfmtConfig()
-console.log(config) // { printWidth: 80, ... }
+const result = await loadOxfmtConfigResult()
+console.log(result.config) // { printWidth: 80, ... }
 ```
 
 ### Merge With `.editorconfig`
 
 ```ts
-import { loadOxfmtConfig } from 'load-oxfmt-config'
+import { loadOxfmtConfigResult } from 'load-oxfmt-config'
 
-const config = await loadOxfmtConfig({ cwd: '/path/to/project' })
+const result = await loadOxfmtConfigResult({ cwd: '/path/to/project' })
 
 // Returns one merged static config object
-console.log(config)
+console.log(result.config)
 // {
 //   tabWidth: 2,
 //   printWidth: 100,
@@ -65,26 +66,52 @@ console.log(config)
 ### Specify Working Directory
 
 ```ts
-import { loadOxfmtConfig } from 'load-oxfmtConfig'
+import { loadOxfmtConfigResult } from 'load-oxfmt-config'
 
-const config = await loadOxfmtConfig({
+const result = await loadOxfmtConfigResult({
   cwd: '/path/to/project',
 })
 ```
 
+### Get Config Metadata
+
+```ts
+import { loadOxfmtConfigResult } from 'load-oxfmt-config'
+
+const result = await loadOxfmtConfigResult({ cwd: '/path/to/project' })
+
+console.log(result.config) // merged oxfmt options
+console.log(result.filepath) // /path/to/project/.oxfmtrc.json (or undefined)
+console.log(result.dirname) // /path/to/project (or undefined)
+```
+
+### Resolve Ignore Status
+
+```ts
+import { isOxfmtIgnored } from 'load-oxfmt-config'
+
+const result = await isOxfmtIgnored({
+  cwd: '/path/to/project',
+  filepath: '/path/to/project/src/generated/foo.ts',
+})
+
+console.log(result)
+// { ignored: true, reason: 'config-ignore-patterns' }
+```
+
 ### Explicit Config Path
 
 ```ts
-import { loadOxfmtConfig } from 'load-oxfmt-config'
+import { loadOxfmtConfigResult } from 'load-oxfmt-config'
 
 // Relative path (resolved relative to cwd)
-const config = await loadOxfmtConfig({
+const result = await loadOxfmtConfigResult({
   configPath: 'configs/.oxfmtrc.json',
   cwd: '/path/to/project',
 })
 
 // Absolute path
-const config = await loadOxfmtConfig({
+const absoluteResult = await loadOxfmtConfigResult({
   configPath: '/absolute/path/to/.oxfmtrc.json',
 })
 ```
@@ -92,10 +119,10 @@ const config = await loadOxfmtConfig({
 ### Disable `.editorconfig`
 
 ```ts
-import { loadOxfmtConfig } from 'load-oxfmt-config'
+import { loadOxfmtConfigResult } from 'load-oxfmt-config'
 
 // Skip .editorconfig reading entirely
-const config = await loadOxfmtConfig({
+const result = await loadOxfmtConfigResult({
   editorconfig: false,
 })
 ```
@@ -103,10 +130,10 @@ const config = await loadOxfmtConfig({
 ### Limit `.editorconfig` to `cwd`
 
 ```ts
-import { loadOxfmtConfig } from 'load-oxfmt-config'
+import { loadOxfmtConfigResult } from 'load-oxfmt-config'
 
 // Only look in the cwd directory itself, no upward traversal
-const config = await loadOxfmtConfig({
+const result = await loadOxfmtConfigResult({
   editorconfig: { onlyCwd: true },
 })
 ```
@@ -114,10 +141,10 @@ const config = await loadOxfmtConfig({
 ### Override `.editorconfig` Search Directory
 
 ```ts
-import { loadOxfmtConfig } from 'load-oxfmt-config'
+import { loadOxfmtConfigResult } from 'load-oxfmt-config'
 
 // Search .editorconfig from a custom directory instead of the config file's directory
-const config = await loadOxfmtConfig({
+const result = await loadOxfmtConfigResult({
   editorconfig: {
     cwd: '/path/to/editorconfig-dir',
   },
@@ -127,14 +154,23 @@ const config = await loadOxfmtConfig({
 ### Disable Caching
 
 ```ts
-import { loadOxfmtConfig } from 'load-oxfmt-config'
+import { loadOxfmtConfigResult } from 'load-oxfmt-config'
 
 // Force reload from disk, bypassing cache
-const config = await loadOxfmtConfig({
+const result = await loadOxfmtConfigResult({
   useCache: false,
 })
 ```
 
+### Legacy API (Deprecated)
+
+```ts
+import { loadOxfmtConfig } from 'load-oxfmt-config'
+
+// Deprecated: prefer loadOxfmtConfigResult
+const config = await loadOxfmtConfig({ cwd: '/path/to/project' })
+```
+
 ### Path Resolution Only
 
 ```ts
@@ -149,39 +185,83 @@ console.log(configPath) // '/path/to/.oxfmtrc.json' or undefined
 
 ### `loadOxfmtConfig(options?)`
 
+> Deprecated. Prefer `loadOxfmtConfigResult(options?)`.
+
 Load and parse oxfmt configuration files, then merge supported `.editorconfig` fields into the returned result.
 
 **Parameters:**
 
-- `options` - Optional configuration object
+- `options` - Optional configuration object (`Options`)
 
-**Returns:** `Promise<FormatOptions>` - Parsed and merged oxfmt configuration object. Returns empty object `{}` if no supported config file is found.
+Option fields:
 
-**Throws:** Error if config file exists but cannot be parsed.
+#### `cwd`
 
-### `resolveOxfmtrcPath(cwd, configPath?)`
+- **Type:** `string`
+- **Default:** `process.cwd()`
 
-Resolve the absolute path to oxfmt config file.
+Current working directory to start searching for config files. The loader will walk up from this directory to find a config file.
 
-**Parameters:**
+#### `configPath`
 
-- `cwd` - Starting directory for resolution
-- `configPath` - Optional explicit path (absolute or relative to cwd)
+- **Type:** `string`
+- **Default:** `undefined`
 
-**Returns:** `Promise<string | undefined>` - Absolute path to config file, or `undefined` if not found.
+Explicit path to the config file:
+
+- **Relative path:** Resolved relative to `cwd`
+- **Absolute path:** Used as-is
+- **When provided:** Skips auto-discovery and uses this path directly
+
+#### `useCache`
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Enable in-memory caching for both path resolution and parsed config contents. When enabled:
+
+- Config file paths are cached to avoid repeated filesystem lookups
+- Parsed config objects are cached to avoid re-parsing
+- Subsequent calls with the same parameters return cached results instantly
 
-## Options
+Set to `false` to force reload from disk on every call.
+
+#### `editorconfig`
+
+- **Type:** `boolean | EditorconfigOption`
+- **Default:** `true`
 
-All options are optional.
+Control how `.editorconfig` files are read and merged:
+
+- **`true`** — Read and merge the nearest `.editorconfig`, walking up from the config file's directory (or `cwd` when no config path is given).
+- **`false`** — Disable `.editorconfig` reading entirely.
+- **`EditorconfigOption`** — Enable with additional settings:
 
-### `cwd`
+| Property  | Type      | Default     | Description                                                                                                           |
+| --------- | --------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
+| `onlyCwd` | `boolean` | `false`     | When `true`, only look for `.editorconfig` in `cwd` itself — no upward traversal.                                     |
+| `cwd`     | `string`  | `undefined` | Override the directory from which `.editorconfig` resolution starts, instead of the config file's directory or `cwd`. |
+
+**Returns:** `Promise<OxfmtOptions>` - Parsed and merged oxfmt configuration object. Returns empty object `{}` if no supported config file is found.
+
+### `loadOxfmtConfigResult(options?)`
+
+Load and parse oxfmt configuration files, merge supported `.editorconfig` fields, and return metadata for the resolved config file.
+
+**Parameters:**
+
+- `options` - Optional configuration object (`Options`)
+
+Option fields:
+
+#### `cwd`
 
 - **Type:** `string`
 - **Default:** `process.cwd()`
 
 Current working directory to start searching for config files. The loader will walk up from this directory to find a config file.
 
-### `configPath`
+#### `configPath`
 
 - **Type:** `string`
 - **Default:** `undefined`
@@ -192,7 +272,7 @@ Explicit path to the config file:
 - **Absolute path:** Used as-is
 - **When provided:** Skips auto-discovery and uses this path directly
 
-### `useCache`
+#### `useCache`
 
 - **Type:** `boolean`
 - **Default:** `true`
@@ -205,7 +285,7 @@ Enable in-memory caching for both path resolution and parsed config contents. Wh
 
 Set to `false` to force reload from disk on every call.
 
-### `editorconfig`
+#### `editorconfig`
 
 - **Type:** `boolean | EditorconfigOption`
 - **Default:** `true`
@@ -221,6 +301,105 @@ Control how `.editorconfig` files are read and merged:
 | `onlyCwd` | `boolean` | `false`     | When `true`, only look for `.editorconfig` in `cwd` itself — no upward traversal.                                     |
 | `cwd`     | `string`  | `undefined` | Override the directory from which `.editorconfig` resolution starts, instead of the config file's directory or `cwd`. |
 
+**Returns:** `Promise<LoadOxfmtConfigResult>`
+
+- `config` - Parsed and merged oxfmt configuration object
+- `filepath` - Resolved config absolute path (undefined when not found)
+- `dirname` - Config directory (undefined when not found)
+
+**Throws:** Error if config file exists but cannot be parsed.
+
+### `resolveOxfmtrcPath(cwd, configPath?)`
+
+Resolve the absolute path to oxfmt config file.
+
+**Parameters:**
+
+- `cwd` - Starting directory for resolution
+- `configPath` - Optional explicit path (absolute or relative to cwd)
+
+**Returns:** `Promise<string | undefined>` - Absolute path to config file, or `undefined` if not found.
+
+### `isOxfmtIgnored(options)`
+
+Resolve whether a file should be ignored with oxfmt CLI-like semantics.
+
+**Parameters:**
+
+- `options` - Required configuration object (`IsOxfmtIgnoredOptions`)
+
+Option fields:
+
+#### `cwd`
+
+- **Type:** `string`
+- **Default:** `process.cwd()`
+
+Current working directory.
+Also the base directory for default `.gitignore`/`.prettierignore` lookup.
+
+#### `filepath`
+
+- **Type:** `string`
+- **Default:** required
+
+File path to test.
+
+#### `configPath`
+
+- **Type:** `string`
+- **Default:** `undefined`
+
+Explicit oxfmt config path.
+When provided, nested config lookup is disabled (same as oxfmt CLI `-c`).
+
+#### `ignorePath`
+
+- **Type:** `string | string[]`
+- **Default:** `undefined`
+
+Ignore files to use instead of cwd `.gitignore`/`.prettierignore`.
+Can be passed multiple times in CLI style.
+
+#### `withNodeModules`
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether `node_modules` should be included.
+
+#### `disableNestedConfig`
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Disable nested config lookup.
+
+#### `useCache`
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to use in-memory cache.
+
+#### `includeConfigIgnorePatterns`
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to include ignore patterns defined in the resolved config file.
+
+**Returns:** `Promise<IsOxfmtIgnoredResult>`
+
+- `ignored` - Whether the file is ignored
+- `reason` - One of:
+  - `default-dir`
+  - `lockfile`
+  - `gitignore`
+  - `prettierignore`
+  - `ignore-path`
+  - `config-ignore-patterns`
+
 ## Config File Discovery
 
 When `configPath` is not provided, the loader automatically searches for config files:
@@ -229,9 +408,7 @@ When `configPath` is not provided, the loader automatically searches for config
 2. **Supported filenames:**
    - `.oxfmtrc.json`
    - `.oxfmtrc.jsonc`
-
-- `oxfmt.config.ts`
-
+   - `oxfmt.config.ts`
 3. **Stops when:**
    - A valid config file is found
    - Reaches the filesystem root
@@ -278,6 +455,8 @@ export default {
 }
 ```
 
+When `configPath` is passed explicitly, extensions `.json`, `.jsonc`, `.ts`, `.mts`, `.cts`, `.js`, `.mjs`, and `.cjs` are supported. Extensionless paths are also accepted and parsed as JSON.
+
 ## `.editorconfig` Support
 
 The loader reads the nearest `.editorconfig` file and maps the subset of fields that oxfmt supports:
@@ -292,6 +471,35 @@ The loader reads the nearest `.editorconfig` file and maps the subset of fields
 
 Only `[*]` is treated as a global section to match oxfmt. Other sections such as `[**]` and `[*.ts]` are converted into returned `overrides` entries.
 
+## Ignore Strategy
+
+`isOxfmtIgnored()` applies two layers:
+
+1. Global ignore
+2. Ignore patterns from the resolved oxfmt config (`ignorePatterns`)
+
+Set `includeConfigIgnorePatterns: false` to keep only global ignore behavior (skip config `ignorePatterns`).
+
+Global ignore includes:
+
+- Default ignored directories: `.git`, `.svn`, `.jj`, `node_modules`
+- Default lockfiles: `package-lock.json`, `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `bun.lockb`
+- Ignore files:
+  - If `ignorePath` is provided: use those files only (multiple supported)
+  - If `ignorePath` is not provided: use `.gitignore` and `.prettierignore` from `cwd`
+
+Notes:
+
+- `node_modules` can be included by passing `withNodeModules: true`.
+- This package does not read parent `.gitignore` files or global gitignore settings.
+- The default lockfile list mirrors oxfmt documentation intent (`package-lock.json`, `pnpm-lock.yaml`, etc.) and common ecosystem lockfiles. It is not guaranteed to be a complete internal oxfmt list.
+- `ignorePatterns` are always interpreted relative to the resolved oxfmt config directory.
+- `includeConfigIgnorePatterns` defaults to `true` to preserve current behavior.
+- Nested config behavior follows oxfmt semantics:
+  - default: nearest config from target file directory upward
+  - `disableNestedConfig: true`: resolve from `cwd` only
+  - `configPath`: also disables nested lookup (same intent as CLI `-c`)
+
 ## Precedence
 
 The merged result follows this order:
@@ -305,17 +513,18 @@ This means explicit oxfmt config values always win over `.editorconfig` fallback
 
 ## Limitations
 
-`loadOxfmtConfig()` returns a static `OxfmtOptions` object. That means `.editorconfig` support is represented as a merged config shape, 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.
+`loadOxfmtConfigResult()` (and the deprecated `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.
 
 ## Error Handling
 
 ```ts
-import { loadOxfmtConfig } from 'load-oxfmt-config'
+import { loadOxfmtConfigResult } from 'load-oxfmt-config'
 
 try {
-  const config = await loadOxfmtConfig()
+  const result = await loadOxfmtConfigResult()
+  console.log(result.config)
 } catch (error) {
-  // Thrown when config file exists but contains invalid JSON
+  // Thrown when config file exists but contains invalid JSON/JSONC
   console.error('Failed to parse oxfmt config:', error.message)
 }
 ```

package/dist/index.d.mts

@@ -77,35 +77,161 @@ interface OxfmtOptions extends FormatConfig {
    */
   overrides?: OxfmtConfigOverride[];
 }
+/**
+ * Result object with metadata about resolved oxfmt config.
+ */
+interface LoadOxfmtConfigResult {
+  /**
+   * Final merged config (oxfmt + optional editorconfig mapping)
+   */
+  config: OxfmtOptions;
+  /**
+   * Absolute path of resolved config file
+   */
+  filepath?: string;
+  /**
+   * Directory of resolved config file
+   */
+  dirname?: string;
+}
+/**
+ * Options for resolving whether a single file should be ignored.
+ */
+interface IsOxfmtIgnoredOptions {
+  /**
+   * Current working directory.
+   * Also the base directory for default .gitignore/.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 cwd .gitignore/.prettierignore.
+   * Can be passed multiple times in CLI style.
+   */
+  ignorePath?: string | string[];
+  /**
+   * Whether node_modules should be included.
+   * @default true
+   */
+  withNodeModules?: boolean;
+  /**
+   * Disable nested config lookup.
+   * @default false
+   */
+  disableNestedConfig?: boolean;
+  /**
+   * Whether to use in-memory cache.
+   * @default true
+   */
+  useCache?: boolean;
+  /**
+   * Whether to include ignore patterns defined in the config file.
+   * @default true
+   */
+  includeConfigIgnorePatterns?: boolean;
+}
+/**
+ * Ignore resolution result.
+ */
+interface IsOxfmtIgnoredResult {
+  /**
+   * Whether the file should be ignored.
+   */
+  ignored: boolean;
+  /**
+   * Matched ignore source.
+   */
+  reason?: 'default-dir' | 'lockfile' | 'gitignore' | 'prettierignore' | 'ignore-path' | 'config-ignore-patterns';
+}
 /**
  * @deprecated Use `OxfmtConfigOverride` instead
  */
 type FormatOptionOverride = OxfmtConfigOverride;
 //#endregion
-//#region src/core.d.ts
+//#region src/config-file.d.ts
 /**
  * Resolve the oxfmt config file path.
- * - If `configPath` is provided, absolute paths are returned as-is; relative paths are joined to cwd.
- * - Otherwise, walk upward from cwd to find known filenames.
+ *
+ * - If `configPath` is provided, absolute paths are returned as-is;
+ *   relative paths are joined to `cwd`.
+ * - Otherwise, walk upward from `cwd` to find known filenames.
  *
  * @param cwd - Starting directory for resolution.
- * @param configPath - Optional explicit path (absolute or relative to cwd).
- * @returns Absolute path to the config file, or undefined when not found.
+ * @param configPath - Optional explicit path.
+ * @returns Absolute path to config file, or undefined when not found.
+ *
+ * @example
+ * ```ts
+ * import { resolveOxfmtrcPath } from 'load-oxfmt-config'
+ *
+ * const path = await resolveOxfmtrcPath(process.cwd())
+ * ```
  */
 declare function resolveOxfmtrcPath(cwd: string, configPath?: string): Promise<string | undefined>;
+//#endregion
+//#region src/core.d.ts
+/**
+ * Resolve config + editorconfig and return merged config with metadata.
+ *
+ * @param options - Loader settings.
+ * @returns Merged config and optional resolved config metadata.
+ *
+ * @example
+ * ```ts
+ * import { loadOxfmtConfigResult } from 'load-oxfmt-config'
+ *
+ * const result = await loadOxfmtConfigResult({ cwd: process.cwd() })
+ * console.log(result.config)
+ * ```
+ */
+declare function loadOxfmtConfigResult(options?: Options): Promise<LoadOxfmtConfigResult>;
+//#endregion
+//#region src/ignore.d.ts
+/**
+ * Resolve whether a file should be ignored using oxfmt-like CLI semantics.
+ *
+ * @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',
+ * })
+ * ```
+ */
+declare function isOxfmtIgnored(options: IsOxfmtIgnoredOptions): Promise<IsOxfmtIgnoredResult>;
+//#endregion
+//#region src/legacy.d.ts
 /**
- * Load oxfmt configuration: resolve the file path, then read and parse it.
- * Caching is enabled by default; pass `useCache: false` to force a re-read.
+ * Legacy API that returns only the merged config object.
+ *
+ * Prefer using `loadOxfmtConfigResult` when you also need resolved config metadata.
  *
- * @param options - Optional loader settings (cwd, configPath, useCache).
- * @returns Parsed oxfmt OxfmtOptions or an empty object when missing.
- * @throws {Error} when the config file exists but cannot be parsed.
+ * @deprecated Prefer `loadOxfmtConfigResult`.
+ *
+ * @param options - Loader options.
+ * @returns Parsed and merged oxfmt options.
  *
  * @example
  * ```ts
- * const config = await loadOxfmtConfig({ cwd: '/project' })
+ * import { loadOxfmtConfig } from 'load-oxfmt-config'
+ *
+ * // Deprecated: prefer loadOxfmtConfigResult.
+ * const config = await loadOxfmtConfig({ cwd: process.cwd() })
  * ```
  */
 declare function loadOxfmtConfig(options?: Options): Promise<OxfmtOptions>;
 //#endregion
-export { EditorconfigOption, FormatOptionOverride, Options, OxfmtConfigOverride, OxfmtOptions, loadOxfmtConfig, resolveOxfmtrcPath };
+export { EditorconfigOption, FormatOptionOverride, IsOxfmtIgnoredOptions, IsOxfmtIgnoredResult, LoadOxfmtConfigResult, Options, OxfmtConfigOverride, OxfmtOptions, isOxfmtIgnored, loadOxfmtConfig, loadOxfmtConfigResult, resolveOxfmtrcPath };

package/dist/index.mjs

@@ -1,9 +1,11 @@
-import { readFile, stat } from "node:fs/promises";
-import { dirname, isAbsolute, join, relative } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import process from "node:process";
 import { interopDefault, isBoolean, isNumber, isObject } from "@ntnyq/utils";
-import { parse } from "jsonc-parser";
+import { readFile, stat } from "node:fs/promises";
+import { parse, printParseErrorCode } from "jsonc-parser";
 import { parseBuffer } from "editorconfig";
+import ignore from "ignore";
+import picomatch from "picomatch";
 //#region src/constants.ts
 /**
 * Supported configuration files for oxfmt.
@@ -15,6 +17,46 @@ const OXFMT_CONFIG_FILES = [
 	"oxfmt.config.ts"
 ];
 /**
+* Supported extensions for explicit config paths.
+*/
+const OXFMT_EXPLICIT_CONFIG_EXTENSIONS = [
+	".json",
+	".jsonc",
+	".ts",
+	".mts",
+	".cts",
+	".js",
+	".mjs",
+	".cjs"
+];
+/**
+* Default ignored directories used by oxfmt CLI semantics.
+*/
+const DEFAULT_IGNORED_DIRS = [
+	".git",
+	".svn",
+	".jj",
+	"node_modules"
+];
+/**
+* Common lockfiles ignored by default.
+*
+* Note: oxfmt docs only list package-lock.json and pnpm-lock.yaml explicitly,
+* then mention "etc.". This list mirrors common ecosystem lockfiles.
+*/
+const DEFAULT_IGNORED_LOCKFILES = [
+	"package-lock.json",
+	"npm-shrinkwrap.json",
+	"pnpm-lock.yaml",
+	"yarn.lock",
+	"bun.lock",
+	"bun.lockb"
+];
+/**
+* Default ignore files loaded from cwd when --ignore-path is not provided.
+*/
+const DEFAULT_IGNORE_FILES = [".gitignore", ".prettierignore"];
+/**
 * Supported EditorConfig filename.
 */
 const EDITORCONFIG_FILE = ".editorconfig";
@@ -23,6 +65,131 @@ const EDITORCONFIG_FILE = ".editorconfig";
 */
 const EDITORCONFIG_GLOBAL_SECTION_NAMES = ["*"];
 //#endregion
+//#region src/config-file.ts
+/**
+* Build a cache key for path resolution (cwd + configPath).
+*
+* @param cwd - Current working directory.
+* @param configPath - Optional config path.
+* @returns Cache key for resolve cache.
+*/
+function getResolveCacheKey(cwd, configPath) {
+	return `${cwd}::${configPath || ""}`;
+}
+/**
+* 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.
+*/
+function getConfigCacheKey(resolvedPath, editorconfigPath, resolveKey) {
+	return `${resolvedPath || `missing-oxfmt:${resolveKey}`}::${editorconfigPath || `missing-editorconfig:${resolveKey}`}`;
+}
+/**
+* Resolve the oxfmt config file path.
+*
+* - If `configPath` is provided, absolute paths are returned as-is;
+*   relative paths are joined to `cwd`.
+* - Otherwise, walk upward from `cwd` to find known filenames.
+*
+* @param cwd - Starting directory for resolution.
+* @param configPath - Optional explicit path.
+* @returns Absolute path to config file, or undefined when not found.
+*
+* @example
+* ```ts
+* import { resolveOxfmtrcPath } from 'load-oxfmt-config'
+*
+* const path = await resolveOxfmtrcPath(process.cwd())
+* ```
+*/
+async function resolveOxfmtrcPath(cwd, configPath) {
+	const resolvedCwd = resolve(cwd);
+	if (configPath) return isAbsolute(configPath) ? configPath : join(resolvedCwd, configPath);
+	let currentDir = resolvedCwd;
+	while (true) {
+		for (const filename of OXFMT_CONFIG_FILES) {
+			const configFilePath = join(currentDir, filename);
+			try {
+				if ((await stat(configFilePath)).isFile()) return configFilePath;
+			} catch {}
+		}
+		const parentDir = join(currentDir, "..");
+		if (parentDir === currentDir) break;
+		currentDir = parentDir;
+	}
+}
+/**
+* Read and parse an oxfmt config file.
+*
+* @param resolvedPath - Absolute path to config file.
+* @returns Parsed config object.
+*/
+async function readConfigFromFile(resolvedPath) {
+	const extension = extname(resolvedPath);
+	if (extension === ".ts" || extension === ".mts" || extension === ".cts" || extension === ".js" || extension === ".mjs" || extension === ".cjs") {
+		const mod = await (await interopDefault(import("jiti")))(import.meta.url).import(resolvedPath);
+		return mod["default"] ?? mod;
+	}
+	const content = await readFile(resolvedPath, "utf8");
+	if (extension === ".jsonc") {
+		const parseErrors = [];
+		const parsed = parse(content, parseErrors);
+		if (parseErrors.length > 0) {
+			const firstError = parseErrors[0];
+			const errorCode = firstError === void 0 ? "Unknown" : printParseErrorCode(firstError.error);
+			throw new Error(`Invalid JSONC syntax: ${errorCode}`);
+		}
+		return parsed;
+	}
+	if (extension === ".json") return JSON.parse(content);
+	if (!extension) return JSON.parse(content);
+	if (!OXFMT_EXPLICIT_CONFIG_EXTENSIONS.includes(extension)) throw new Error(`Unsupported oxfmt config extension "${extension}" at ${resolvedPath}`);
+	return JSON.parse(content);
+}
+//#endregion
+//#region src/utils.ts
+/**
+* Return a cached promise by key, creating and storing it on miss.
+*
+* If the promise rejects, the cache entry is removed so future calls can retry.
+*
+* @param cache - Map used to store inflight/resolved promises.
+* @param key - Cache key.
+* @param factory - Factory to create the promise when missing.
+* @returns Cached or newly created promise.
+*/
+function cachePromise(cache, key, factory) {
+	const cached = cache.get(key);
+	if (cached) return cached;
+	const task = factory().catch((error) => {
+		cache.delete(key);
+		throw error;
+	});
+	cache.set(key, task);
+	return task;
+}
+/**
+* Normalize a filesystem path to POSIX-style separators.
+*
+* @param path - Original path.
+* @returns Path using `/` as separator.
+*/
+function toPosixPath(path) {
+	return path.replaceAll("\\", "/");
+}
+/**
+* Split a path into non-empty segments.
+*
+* @param path - Original path.
+* @returns Path segments.
+*/
+function splitPathSegments(path) {
+	return path.split(/[\\/]+/u).filter(Boolean);
+}
+//#endregion
 //#region src/editorconfig.ts
 /**
 * Builds the cache key used for resolved EditorConfig lookups.
@@ -89,15 +256,6 @@ async function resolveEditorconfigPath(startDir, onlyCwd = false) {
 	}
 }
 /**
-* Normalizes a file path to POSIX separators for glob compatibility.
-*
-* @param path - The path to normalize.
-* @returns The path with forward slashes.
-*/
-function toPosixPath(path) {
-	return path.replaceAll("\\", "/");
-}
-/**
 * Checks whether an EditorConfig section should be treated as a global section.
 *
 * @param sectionName - The section name parsed from .editorconfig.
@@ -189,7 +347,7 @@ function mapEditorconfigSectionToOptions(section) {
 function rebaseEditorconfigPattern(pattern, editorconfigDir, anchorDir) {
 	const relativePrefix = toPosixPath(relative(anchorDir, editorconfigDir));
 	if (!relativePrefix || relativePrefix === ".") return pattern;
-	return `${relativePrefix}/${pattern.replace(/^\//, "")}`;
+	return `${relativePrefix}/${pattern.replace(/^\//u, "")}`;
 }
 /**
 * Reads a .editorconfig file and converts it into root options and override entries.
@@ -226,129 +384,231 @@ async function readEditorconfigFromFile(editorconfigPath, anchorDir) {
 const resolveCache = /* @__PURE__ */ new Map();
 const configCache = /* @__PURE__ */ new Map();
 /**
-* Return a cached promise by key, creating and storing it on miss; failures clear the entry.
+* Resolve config + editorconfig and return merged config with metadata.
 *
-* @param cache - Map used to store inflight/resolved promises.
-* @param key - Cache key.
-* @param factory - Factory to create the promise when missing.
-* @returns Cached or newly created promise.
+* @param options - Loader settings.
+* @returns Merged config and optional resolved config metadata.
+*
+* @example
+* ```ts
+* import { loadOxfmtConfigResult } from 'load-oxfmt-config'
+*
+* const result = await loadOxfmtConfigResult({ cwd: process.cwd() })
+* console.log(result.config)
+* ```
 */
-function cachePromise(cache, key, factory) {
-	const cached = cache.get(key);
-	if (cached) return cached;
-	const task = factory().catch((error) => {
-		cache.delete(key);
+async function loadOxfmtConfigResult(options = {}) {
+	const useCache = options.useCache !== false;
+	const cwd = resolve(options.cwd || process.cwd());
+	const editorconfig = options.editorconfig ?? true;
+	const useEditorconfig = editorconfig !== false;
+	const isEditorconfigOptionsObject = useEditorconfig && isObject(editorconfig);
+	const onlyCwd = isEditorconfigOptionsObject ? editorconfig.onlyCwd ?? false : false;
+	const editorconfigCwd = isEditorconfigOptionsObject && editorconfig.cwd ? resolve(editorconfig.cwd) : void 0;
+	const resolveKey = getResolveCacheKey(cwd, options.configPath);
+	const editorconfigSearchDir = editorconfigCwd || getEditorconfigSearchDir(cwd, options.configPath);
+	const editorconfigResolveKey = editorconfigCwd ? getEditorconfigResolveCacheKey(`${editorconfigCwd}::${options.configPath || ""}`) : getEditorconfigResolveCacheKey(resolveKey);
+	const resolvedPath = useCache ? await cachePromise(resolveCache, resolveKey, () => resolveOxfmtrcPath(cwd, options.configPath)) : await resolveOxfmtrcPath(cwd, options.configPath);
+	const editorconfigPath = useEditorconfig ? await (useCache ? cachePromise(resolveCache, editorconfigResolveKey, () => resolveEditorconfigPath(editorconfigSearchDir, onlyCwd)) : resolveEditorconfigPath(editorconfigSearchDir, onlyCwd)) : void 0;
+	const anchorDir = dirname(resolvedPath || editorconfigPath || cwd);
+	const loadTask = async () => {
+		const oxfmtConfig = resolvedPath ? await readConfigFromFile(resolvedPath).catch((error) => {
+			throw new Error(`Failed to parse oxfmt configuration file at ${resolvedPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		}) : {};
+		if (!editorconfigPath) return oxfmtConfig;
+		const editorconfigData = await readEditorconfigFromFile(editorconfigPath, anchorDir);
+		const mergedConfig = mergeRootOptions(oxfmtConfig, editorconfigData.rootOptions);
+		const mergedOverrides = mergeOverrides(oxfmtConfig.overrides, editorconfigData.overrides);
+		if (!mergedOverrides) return mergedConfig;
+		return {
+			...mergedConfig,
+			overrides: mergedOverrides
+		};
+	};
+	const hasNoConfigSources = !resolvedPath && !editorconfigPath;
+	return {
+		config: await (async () => {
+			if (hasNoConfigSources) return useCache ? await cachePromise(configCache, getConfigCacheKey(resolvedPath, editorconfigPath, resolveKey), () => Promise.resolve({})) : {};
+			return useCache ? await cachePromise(configCache, getConfigCacheKey(resolvedPath, editorconfigPath, resolveKey), loadTask) : await loadTask();
+		})(),
+		...resolvedPath ? {
+			filepath: resolvedPath,
+			dirname: dirname(resolvedPath)
+		} : {}
+	};
+}
+//#endregion
+//#region src/ignore.ts
+const ignoreMatcherCache = /* @__PURE__ */ new Map();
+/**
+* Check whether a file is under oxfmt's default ignored directories.
+*
+* @param filepath - Absolute file path to test.
+* @param options - Matching options.
+* @returns True when the path should be ignored by default directory rules.
+*/
+function isDefaultIgnoredDir(filepath, options) {
+	const directories = options.withNodeModules ? DEFAULT_IGNORED_DIRS.filter((dir) => dir !== "node_modules") : DEFAULT_IGNORED_DIRS;
+	const segments = splitPathSegments(dirname(filepath));
+	return directories.some((dir) => segments.includes(dir));
+}
+/**
+* Check whether a file is a default ignored lockfile.
+*
+* @param filepath - Absolute file path.
+* @returns True when the basename matches a default lockfile name.
+*/
+function isLockfile(filepath) {
+	return DEFAULT_IGNORED_LOCKFILES.includes(basename(filepath));
+}
+/**
+* Read and parse an ignore file into an `ignore` matcher.
+*
+* @param ignoreFilePath - Ignore file path.
+* @param useCache - Whether to cache matcher instances.
+* @returns Parsed matcher, or undefined when file does not exist.
+*/
+function loadIgnoreMatcher(ignoreFilePath, useCache) {
+	const loadTask = () => readFile(ignoreFilePath, "utf8").then((content) => {
+		const ig = ignore();
+		ig.add(content);
+		return ig;
+	}).catch((error) => {
+		const code = error.code;
+		if (code === "ENOENT" || code === "ENOTDIR") return;
 		throw error;
 	});
-	cache.set(key, task);
-	return task;
+	if (!useCache) return loadTask();
+	return cachePromise(ignoreMatcherCache, ignoreFilePath, loadTask);
 }
 /**
-* Build a cache key for config content; prefixes missing entries with `missing:`.
+* Build a POSIX relative path.
 *
-* @param resolvedPath - Resolved config path or undefined when missing.
-* @param editorconfigPath - Resolved editorconfig path or undefined when missing.
-* @param resolveKey - Key used for path resolution caching.
-* @returns Cache key for config content.
+* @param from - Base directory.
+* @param to - Target path.
+* @returns POSIX relative path.
 */
-function getConfigCacheKey(resolvedPath, editorconfigPath, resolveKey) {
-	return `${resolvedPath || `missing-oxfmt:${resolveKey}`}::${editorconfigPath || `missing-editorconfig:${resolveKey}`}`;
+function relativeSafe(from, to) {
+	return toPosixPath(relative(from, to));
 }
 /**
-* Resolve the oxfmt config file path.
-* - If `configPath` is provided, absolute paths are returned as-is; relative paths are joined to cwd.
-* - Otherwise, walk upward from cwd to find known filenames.
+* Match file path against one ignore file.
 *
-* @param cwd - Starting directory for resolution.
-* @param configPath - Optional explicit path (absolute or relative to cwd).
-* @returns Absolute path to the config file, or undefined when not found.
+* @param filepath - Absolute file path.
+* @param ignoreFilePath - Ignore file path.
+* @param useCache - Whether to use matcher cache.
+* @returns True when ignored by this file.
 */
-async function resolveOxfmtrcPath(cwd, configPath) {
-	if (configPath) return isAbsolute(configPath) ? configPath : join(cwd, configPath);
-	let currentDir = cwd;
-	while (true) {
-		for (const filename of OXFMT_CONFIG_FILES) {
-			const configFilePath = join(currentDir, filename);
-			try {
-				if ((await stat(configFilePath)).isFile()) return configFilePath;
-			} catch {}
-		}
-		const parentDir = join(currentDir, "..");
-		if (parentDir === currentDir) break;
-		currentDir = parentDir;
-	}
+async function matchIgnoreFile(filepath, ignoreFilePath, useCache) {
+	const matcher = await loadIgnoreMatcher(ignoreFilePath, useCache);
+	if (!matcher) return false;
+	const relativeToIgnore = relativeSafe(dirname(ignoreFilePath), filepath);
+	if (relativeToIgnore === ".." || relativeToIgnore.startsWith("../")) return false;
+	return matcher.ignores(relativeToIgnore);
 }
 /**
-* Build a cache key for path resolution (cwd + configPath).
+* Resolve an ignore file path against cwd when needed.
 *
+* @param path - Absolute or relative path.
 * @param cwd - Current working directory.
-* @param configPath - Optional config path.
-* @returns Cache key for resolve cache.
+* @returns Absolute ignore file path.
 */
-function getResolveCacheKey(cwd, configPath) {
-	return `${cwd}::${configPath || ""}`;
+function resolveIgnoreFilePath(path, cwd) {
+	return isAbsolute(path) ? path : resolve(cwd, path);
 }
 /**
-* Read and parse config file, supporting JSON, JSONC, and TypeScript/JavaScript.
+* Match `ignorePatterns` from config with support for negated patterns.
 *
-* @param resolvedPath - Absolute path to the config file.
-* @returns Parsed OxfmtOptions object.
+* @param filepath - Absolute file path.
+* @param configDir - Resolved config directory.
+* @param patterns - Config ignore patterns.
+* @returns True when patterns mark the file as ignored.
 */
-async function readConfigFromFile(resolvedPath) {
-	if (resolvedPath.endsWith(".ts")) {
-		const mod = await (await interopDefault(import("jiti")))(import.meta.url).import(resolvedPath);
-		return mod["default"] ?? mod;
+function matchConfigIgnorePatterns(filepath, configDir, patterns) {
+	const relativeFile = relativeSafe(configDir, filepath);
+	let ignored = false;
+	for (const rawPattern of patterns) {
+		if (!rawPattern) continue;
+		const isNegative = rawPattern.startsWith("!");
+		const pattern = isNegative ? rawPattern.slice(1) : rawPattern;
+		if (!pattern) continue;
+		if (picomatch(pattern, { dot: true })(relativeFile)) ignored = !isNegative;
 	}
-	const content = await readFile(resolvedPath, "utf8");
-	if (resolvedPath.endsWith(".jsonc")) return parse(content);
-	return JSON.parse(content);
+	return ignored;
 }
 /**
-* Load oxfmt configuration: resolve the file path, then read and parse it.
-* Caching is enabled by default; pass `useCache: false` to force a re-read.
+* Resolve whether a file should be ignored using oxfmt-like CLI semantics.
 *
-* @param options - Optional loader settings (cwd, configPath, useCache).
-* @returns Parsed oxfmt OxfmtOptions or an empty object when missing.
-* @throws {Error} when the config file exists but cannot be parsed.
+* @param options - Ignore resolution options.
+* @returns Ignore status with optional reason.
 *
 * @example
 * ```ts
-* const config = await loadOxfmtConfig({ cwd: '/project' })
+* import { isOxfmtIgnored } from 'load-oxfmt-config'
+*
+* const result = await isOxfmtIgnored({
+*   cwd: process.cwd(),
+*   filepath: 'src/generated/file.ts',
+* })
 * ```
 */
-async function loadOxfmtConfig(options = {}) {
+async function isOxfmtIgnored(options) {
 	const useCache = options.useCache !== false;
-	const cwd = options.cwd || process.cwd();
-	const editorconfig = options.editorconfig ?? true;
-	const useEditorconfig = editorconfig !== false;
-	const onlyCwd = useEditorconfig && isObject(editorconfig) ? editorconfig.onlyCwd ?? false : false;
-	const editorconfigCwd = useEditorconfig && isObject(editorconfig) ? editorconfig.cwd : void 0;
-	const resolveKey = getResolveCacheKey(cwd, options.configPath);
-	const editorconfigSearchDir = editorconfigCwd || getEditorconfigSearchDir(cwd, options.configPath);
-	const editorconfigResolveKey = editorconfigCwd ? getEditorconfigResolveCacheKey(`${editorconfigCwd}::${options.configPath || ""}`) : getEditorconfigResolveCacheKey(resolveKey);
-	const resolvedPath = useCache ? await cachePromise(resolveCache, resolveKey, () => resolveOxfmtrcPath(cwd, options.configPath)) : await resolveOxfmtrcPath(cwd, options.configPath);
-	const editorconfigPath = useEditorconfig ? await (useCache ? cachePromise(resolveCache, editorconfigResolveKey, () => resolveEditorconfigPath(editorconfigSearchDir, onlyCwd)) : resolveEditorconfigPath(editorconfigSearchDir, onlyCwd)) : void 0;
-	const anchorDir = dirname(resolvedPath || editorconfigPath || cwd);
-	const loadTask = async () => {
-		const oxfmtConfig = resolvedPath ? await readConfigFromFile(resolvedPath).catch((error) => {
-			throw new Error(`Failed to parse oxfmt configuration file at ${resolvedPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
-		}) : {};
-		if (!editorconfigPath) return oxfmtConfig;
-		const editorconfigData = await readEditorconfigFromFile(editorconfigPath, anchorDir);
-		const mergedConfig = mergeRootOptions(oxfmtConfig, editorconfigData.rootOptions);
-		const mergedOverrides = mergeOverrides(oxfmtConfig.overrides, editorconfigData.overrides);
-		if (!mergedOverrides) return mergedConfig;
-		return {
-			...mergedConfig,
-			overrides: mergedOverrides
+	const includeConfigIgnorePatterns = options.includeConfigIgnorePatterns !== false;
+	const cwd = resolve(options.cwd ?? process.cwd());
+	const filepath = isAbsolute(options.filepath) ? resolve(options.filepath) : resolve(cwd, options.filepath);
+	if (isDefaultIgnoredDir(filepath, options.withNodeModules ? { withNodeModules: true } : {})) return {
+		ignored: true,
+		reason: "default-dir"
+	};
+	if (isLockfile(filepath)) return {
+		ignored: true,
+		reason: "lockfile"
+	};
+	const explicitIgnorePaths = (typeof options.ignorePath === "string" ? [options.ignorePath] : options.ignorePath)?.map((path) => resolveIgnoreFilePath(path, cwd));
+	if (explicitIgnorePaths && explicitIgnorePaths.length > 0) {
+		for (const ignoreFilePath of explicitIgnorePaths) if (await matchIgnoreFile(filepath, ignoreFilePath, useCache)) return {
+			ignored: true,
+			reason: "ignore-path"
 		};
+	} else for (const ignoreFile of DEFAULT_IGNORE_FILES) if (await matchIgnoreFile(filepath, resolve(cwd, ignoreFile), useCache)) return {
+		ignored: true,
+		reason: ignoreFile === ".gitignore" ? "gitignore" : "prettierignore"
 	};
-	if (!resolvedPath && !editorconfigPath) {
-		if (!useCache) return {};
-		return cachePromise(configCache, getConfigCacheKey(resolvedPath, editorconfigPath, resolveKey), () => Promise.resolve({}));
-	}
-	if (!useCache) return loadTask();
-	return cachePromise(configCache, getConfigCacheKey(resolvedPath, editorconfigPath, resolveKey), loadTask);
+	const configResult = await loadOxfmtConfigResult({
+		cwd: options.configPath || options.disableNestedConfig ? cwd : dirname(filepath),
+		...options.configPath ? { configPath: options.configPath } : {},
+		editorconfig: false,
+		useCache
+	});
+	if (includeConfigIgnorePatterns && configResult.dirname && configResult.config.ignorePatterns && configResult.config.ignorePatterns.length > 0 && matchConfigIgnorePatterns(filepath, configResult.dirname, configResult.config.ignorePatterns)) return {
+		ignored: true,
+		reason: "config-ignore-patterns"
+	};
+	return { ignored: false };
+}
+//#endregion
+//#region src/legacy.ts
+/**
+* Legacy API that returns only the merged config object.
+*
+* Prefer using `loadOxfmtConfigResult` when you also need resolved config metadata.
+*
+* @deprecated Prefer `loadOxfmtConfigResult`.
+*
+* @param options - Loader options.
+* @returns Parsed and merged oxfmt options.
+*
+* @example
+* ```ts
+* import { loadOxfmtConfig } from 'load-oxfmt-config'
+*
+* // Deprecated: prefer loadOxfmtConfigResult.
+* const config = await loadOxfmtConfig({ cwd: process.cwd() })
+* ```
+*/
+async function loadOxfmtConfig(options = {}) {
+	return (await loadOxfmtConfigResult(options)).config;
 }
 //#endregion
-export { loadOxfmtConfig, resolveOxfmtrcPath };
+export { isOxfmtIgnored, loadOxfmtConfig, loadOxfmtConfigResult, resolveOxfmtrcPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "load-oxfmt-config",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Load oxfmt config files and merge supported .editorconfig options.",
   "keywords": [
     "editorconfig",
@@ -41,19 +41,22 @@
   "dependencies": {
     "@ntnyq/utils": "^0.13.2",
     "editorconfig": "^3.0.2",
-    "jiti": "^2.6.1",
-    "jsonc-parser": "^3.3.1"
+    "ignore": "^7.0.5",
+    "jiti": "^2.7.0",
+    "jsonc-parser": "^3.3.1",
+    "picomatch": "^4.0.4"
   },
   "devDependencies": {
     "@ntnyq/tsconfig": "^3.1.0",
     "@types/node": "^25.6.0",
-    "@typescript/native-preview": "^7.0.0-dev.20260426.1",
+    "@types/picomatch": "^4.0.3",
+    "@typescript/native-preview": "^7.0.0-dev.20260506.1",
     "bumpp": "^11.0.1",
     "husky": "^9.1.7",
     "nano-staged": "^1.0.2",
     "npm-run-all2": "^8.0.4",
-    "oxfmt": "^0.46.0",
-    "oxlint": "^1.61.0",
+    "oxfmt": "^0.48.0",
+    "oxlint": "^1.63.0",
     "tsdown": "^0.21.10",
     "vitest": "^4.1.5"
   },