@visulima/fs 5.1.0 → 6.0.1

package/dist/packem_shared/types.d-B-T1rDxl.d.ts

@@ -0,0 +1,958 @@
+import { PathLike, Dirent } from 'node:fs';
+import { FSLike } from 'fdir';
+/**
+ * Positional information for a YAML error, pointing at the offending
+ * character in the source string.
+ */
+interface Mark {
+  /** Zero-based column (characters into the current line). */
+  column: number;
+  /** Zero-based line number. */
+  line: number;
+  /** Zero-based absolute offset into the source string. */
+  position: number;
+  /** A short excerpt of the source around the error, if available. */
+  snippet?: string;
+}
+/**
+ * Base class for all errors raised by `@visulima/yaml`.
+ */
+declare class YAMLError extends Error {
+  readonly mark?: Mark;
+  constructor(message: string, mark?: Mark, source?: string);
+}
+/**
+ * A non-fatal notice (e.g. a duplicate mapping key) collected during parsing.
+ */
+declare class YAMLWarning extends YAMLError {
+  constructor(message: string, mark?: Mark, source?: string);
+}
+/**
+ * Maps a source offset to a line and column.
+ *
+ * Errors already carry a resolved position, so this exists for callers that
+ * hold offsets of their own — an editor mapping a node's span to a cursor
+ * position, or a linter reporting against its own ranges. The parser fills it
+ * in as it scans, which costs one array push per line and only when a counter
+ * was supplied.
+ */
+declare class LineCounter {
+  /** Offset at which each line begins. Line 1 always starts at 0. */
+  lineStarts: number[];
+  /**
+   * Record the start of a new line.
+   *
+   * The parser re-scans on a speculative parse or a rewind, so the same break
+   * can arrive more than once. Line starts are strictly increasing, so an
+   * offset that is not past the last one has already been seen.
+   */
+  addNewLine(offset: number): void;
+  /**
+   * Resolve an offset to a 1-indexed line and column.
+   *
+   * Binary search rather than a scan, so a lookup stays cheap on a large
+   * document even when a caller resolves many offsets.
+   */
+  linePos(offset: number): {
+    col: number;
+    line: number;
+  };
+}
+/** Which scalar-resolution rules to apply. */
+type SchemaName = "core" | "failsafe" | "json" | "yaml-1.1";
+/** One custom scalar type. */
+interface ScalarTag {
+  /**
+   * Participate in *implicit* resolution — an untagged scalar matching
+   * {@link ScalarTag.test} resolves through this tag. Without it the tag only
+   * applies when written explicitly (`!!name value`).
+   * @default false
+   */
+  default?: boolean;
+  /** Recognise a JS value as belonging to this tag, used when serializing. */
+  identify?: (value: unknown) => boolean;
+  /** Turn the scalar's raw text into a value. */
+  resolve: (raw: string) => unknown;
+  /** Render a value back to scalar text. Defaults to `String(value)`. */
+  stringify?: (value: unknown) => string;
+  /**
+   * The tag name. Either a local `!name` / `!!name`, or a fully qualified
+   * `tag:domain,date:name`.
+   */
+  tag: string;
+  /** Pattern an untagged scalar must match for implicit resolution. */
+  test?: RegExp;
+}
+/** What the `customTags` option accepts. */
+type CustomTags = ScalarTag[] | ((tags: ScalarTag[]) => ScalarTag[]);
+/**
+ * How duplicate keys in a mapping are handled.
+ *
+ * - `error` (default): throw a `YAMLParseError`.
+ * - `overwrite`: keep the last value.
+ * - `ignore`: keep the first value.
+ */
+type DuplicateKeyBehavior = "error" | "ignore" | "overwrite";
+/** Options accepted by `parse`. */
+interface ParseOptions {
+  /**
+   * Extra scalar types. Each tag says how to recognise, resolve and render
+   * one type; set `default` with a `test` pattern to have it participate in
+   * implicit resolution as well as explicit `!!tag` use.
+   */
+  customTags?: CustomTags;
+  /**
+   * How to treat repeated keys inside a single mapping.
+   * @default "error"
+   */
+  duplicateKeys?: DuplicateKeyBehavior;
+  /**
+   * Resolve integers to `BigInt` instead of `number`, so values beyond
+   * `Number.MAX_SAFE_INTEGER` survive. Floats are unaffected.
+   * @default false
+   */
+  intAsBigInt?: boolean;
+  /**
+   * Collects the offset of every line break as the document is scanned, so
+   * `lineCounter.linePos(offset)` can resolve any offset afterwards.
+   */
+  lineCounter?: LineCounter;
+  /**
+   * Build mappings as `Map` rather than plain objects, which keeps complex
+   * keys (sequences, mappings) as their native values instead of flattening
+   * them to strings.
+   * @default false
+   */
+  mapAsMap?: boolean;
+  /**
+   * Maximum number of alias nodes that may be resolved. Guards against
+   * "billion laughs" style alias-expansion attacks.
+   * @default 100
+   */
+  maxAliasCount?: number;
+  /**
+   * Maximum nesting depth of collections. Guards against a deeply nested
+   * document (`[[[[…`) exhausting the call stack with a `RangeError` that
+   * escapes the `YAMLError` hierarchy.
+   * @default 1000
+   */
+  maxDepth?: number;
+  /**
+   * Resolve `<<` merge keys. Disable to treat `<<` as an ordinary key.
+   * @default true
+   */
+  merge?: boolean;
+  /**
+   * Optional callback invoked for every non-fatal `YAMLWarning`. When
+   * omitted, warnings are silently ignored.
+   */
+  onWarning?: (warning: YAMLWarning) => void;
+  /**
+   * When `true`, a `__proto__` mapping key becomes an own data property
+   * instead of being assigned through the inherited setter, so a document can
+   * never reach the prototype chain. Merge keys (`<<`) honour this too.
+   * @default true
+   */
+  preventProtoPollution?: boolean;
+  /**
+   * Applied to every key/value pair after parsing, like the `JSON.parse`
+   * reviver. Returning `undefined` drops the entry.
+   */
+  reviver?: (key: unknown, value: unknown) => unknown;
+  /**
+   * Which scalar-resolution rules to apply.
+   *
+   * `core` (default) is YAML 1.2 core: `~`/`null`, `true`/`false`, decimal,
+   * hex and octal ints, floats, `.inf`/`.nan`.
+   * `failsafe` resolves nothing; every scalar stays a string.
+   * `json` resolves only the JSON grammar; any other unquoted scalar is a
+   * document error.
+   * `yaml-1.1` is the older, wider set: `yes`/`no`/`on`/`off` as booleans,
+   * `010` as octal, `0b` binaries, `1_000` underscores, sexagesimals, and
+   * timestamps as `Date`.
+   *
+   * Defaults to `yaml-1.1` when {@link ParseOptions.version} is `"1.1"`.
+   * @default "core"
+   */
+  schema?: SchemaName;
+  /**
+   * Full YAML 1.2 strictness, on by default. The parser always rejects the
+   * unambiguous spec violations (tabs as indentation, malformed directives,
+   * deficient indentation, comments not separated by white space). With
+   * `strict` it additionally rejects the corner cases that both `yaml` and
+   * `js-yaml` accept but the spec forbids: a node property (anchor or tag)
+   * carried onto a new line yet indented no deeper than its parent key; a
+   * block mapping or sequence whose first entry sits on the document-start
+   * line; two anchors or two tags on one node; and a block scalar whose
+   * leading empty lines out-indent its content or that uses a tab for
+   * indentation. Set `strict: false` to relax exactly those checks (closer to
+   * `js-yaml`); it never changes the value of an accepted document, only
+   * whether these malformed inputs throw.
+   * @default true
+   */
+  strict?: boolean;
+  /**
+   * Keep every mapping key a string, skipping scalar resolution for keys.
+   * @default false
+   */
+  stringKeys?: boolean;
+  /**
+   * YAML version to assume when the document carries no `%YAML` directive.
+   * `"1.1"` selects the `yaml-1.1` schema unless {@link ParseOptions.schema}
+   * says otherwise.
+   * @default "1.2"
+   */
+  version?: "1.1" | "1.2";
+}
+/** Options accepted by `stringify`. */
+interface StringifyOptions {
+  /**
+   * How to render a multi-line string: `literal` (`|`), `folded` (`>`), or
+   * `false` to always use a quoted style.
+   * @default true
+   */
+  blockQuote?: "folded" | "literal" | boolean;
+  /**
+   * Force every collection to one style, overriding {@link StringifyOptions.flowLevel}.
+   * @default "any"
+   */
+  collectionStyle?: "any" | "block" | "flow";
+  /**
+   * Extra scalar types used when serializing: a value claimed by a tag's
+   * `identify` is written with that tag.
+   */
+  customTags?: CustomTags;
+  /**
+   * Emit an explicit document-start marker (`---`) before the document.
+   * @default false
+   */
+  directives?: boolean;
+  /**
+   * String written for `false`.
+   * @default "false"
+   */
+  falseStr?: string;
+  /**
+   * Pad the inside of flow collections: `{ a: 1 }` rather than `{a: 1}`.
+   * @default true
+   */
+  flowCollectionPadding?: boolean;
+  /**
+   * Force flow style (`{a: 1, b: [2, 3]}`) for collections nested deeper than
+   * this level. `-1` disables flow style entirely (everything is block
+   * style). `0` makes the whole document flow style.
+   * @default -1
+   */
+  flowLevel?: number;
+  /**
+   * When `true`, non-ASCII characters are escaped in double-quoted scalars.
+   * @default false
+   */
+  forceQuotes?: boolean;
+  /**
+   * Number of spaces used for each indentation level.
+   * @default 2
+   */
+  indent?: number;
+  /**
+   * Indent block sequences inside a mapping under their key.
+   * @default true
+   */
+  indentSeq?: boolean;
+  /**
+   * Keep `undefined` values instead of dropping them, writing them as `null`.
+   * @default false
+   */
+  keepUndefined?: boolean;
+  /**
+   * Preferred maximum line width for folded scalars. `0` disables folding.
+   * @default 80
+   */
+  lineWidth?: number;
+  /**
+   * String written for `null`.
+   * @default "null"
+   */
+  nullStr?: string;
+  /**
+   * A `JSON.stringify`-style replacer applied to every value before it is
+   * serialized. Return `undefined` to omit the value.
+   */
+  replacer?: (key: string, value: unknown) => unknown;
+  /**
+   * Prefer single quotes over double quotes when a string must be quoted.
+   * @default false
+   */
+  singleQuote?: boolean;
+  /**
+   * When `true`, keys with `undefined` values (and `undefined` array members)
+   * are skipped instead of being written as `null`.
+   * @default false
+   */
+  skipInvalid?: boolean;
+  /**
+   * When `true`, object keys are emitted in sorted order. A comparator can be
+   * supplied for custom ordering.
+   * @default false
+   */
+  sortKeys?: boolean | ((a: string, b: string) => number);
+  /**
+   * String written for `true`.
+   * @default "true"
+   */
+  trueStr?: string;
+}
+//#region src/types.d.ts
+type FileSystemAdapter = Partial<FSLike>;
+interface GlobOptions$1 {
+  /**
+   * Whether to return absolute paths. Disable to have relative paths.
+   * @default false
+   */
+  absolute?: boolean;
+  /**
+   * Enables support for brace expansion syntax, like `{a,b}` or `{1..9}`.
+   * @default true
+   */
+  braceExpansion?: boolean;
+  /**
+   * Whether to match in case-sensitive mode.
+   * @default true
+   */
+  caseSensitiveMatch?: boolean;
+  /**
+   * The working directory in which to search. Results will be returned relative to this directory, unless
+   * {@link absolute} is set.
+   *
+   * It is important to avoid globbing outside this directory when possible, even with absolute paths enabled,
+   * as doing so can harm performance due to having to recalculate relative paths.
+   * @default process.cwd()
+   */
+  cwd?: string | URL;
+  /**
+   * Logs useful debug information. Meant for development purposes. Logs can change at any time.
+   * @default false
+   */
+  debug?: boolean;
+  /**
+   * Maximum directory depth to crawl.
+   * @default Infinity
+   */
+  deep?: number;
+  /**
+   * Whether to return entries that start with a dot, like `.gitignore` or `.prettierrc`.
+   * @default false
+   */
+  dot?: boolean;
+  /**
+   * Whether to automatically expand directory patterns.
+   *
+   * Important to disable if migrating from [`fast-glob`](https://github.com/mrmlnc/fast-glob).
+   * @default true
+   */
+  expandDirectories?: boolean;
+  /**
+   * Enables support for extglobs, like `+(pattern)`.
+   * @default true
+   */
+  extglob?: boolean;
+  /**
+   * Whether to traverse and include symbolic links. Can slightly affect performance.
+   * @default true
+   */
+  followSymbolicLinks?: boolean;
+  /**
+   * An object that overrides `node:fs` functions.
+   * @default import('node:fs')
+   */
+  fs?: FileSystemAdapter;
+  /**
+   * Enables support for matching nested directories with globstars (`**`).
+   * If `false`, `**` behaves exactly like `*`.
+   * @default true
+   */
+  globstar?: boolean;
+  /**
+   * Glob patterns to exclude from the results.
+   * @default []
+   */
+  ignore?: string | readonly string[];
+  /**
+   * Enable to only return directories.
+   * If `true`, disables {@link onlyFiles}.
+   * @default false
+   */
+  onlyDirectories?: boolean;
+  /**
+   * Enable to only return files.
+   * @default true
+   */
+  onlyFiles?: boolean;
+  /**
+   * @deprecated Provide patterns as the first argument instead.
+   */
+  patterns?: string | readonly string[];
+  /**
+   * An `AbortSignal` to abort crawling the file system.
+   * @default undefined
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Constant to check if the path is visible to the calling process.
+ * Corresponds to `node:fs.constants.F_OK`.
+ */
+declare const F_OK: number;
+/**
+ * Constant to check if the path is readable to the calling process.
+ * Corresponds to `node:fs.constants.R_OK`.
+ */
+declare const R_OK: number;
+/**
+ * Constant to check if the path is writable to the calling process.
+ * Corresponds to `node:fs.constants.W_OK`.
+ */
+declare const W_OK: number;
+/**
+ * Constant to check if the path is executable by the calling process.
+ * Corresponds to `node:fs.constants.X_OK`.
+ */
+declare const X_OK: number;
+/**
+ * A special symbol that can be returned by the matcher function in `findUp` or `findUpSync`
+ * to stop the search process prematurely.
+ */
+declare const FIND_UP_STOP: symbol;
+type ColorizeMethod = (value: string) => string;
+/**
+ * Options accepted by `jsonc-parser`'s `parse` function.
+ */
+type JsoncParseOptions = {
+  /**
+   * Allow empty content as a valid input. Defaults to `false`.
+   */
+  allowEmptyContent?: boolean;
+  /**
+   * Allow trailing commas in arrays and objects. Defaults to `false`.
+   */
+  allowTrailingComma?: boolean;
+  /**
+   * Disallow JavaScript-style comments in the input. Defaults to `false` (comments allowed).
+   */
+  disallowComments?: boolean;
+};
+/**
+ * Formatting options for `jsonc-parser` edits.
+ */
+type JsoncFormattingOptions = {
+  /**
+   * The line ending to use in the output.
+   */
+  eol?: string;
+  /**
+   * When `true`, insert a final newline when the output does not end with one.
+   */
+  insertFinalNewline?: boolean;
+  /**
+   * Indent with spaces (`true`) or tabs (`false`). Defaults to `true`.
+   */
+  insertSpaces?: boolean;
+  /**
+   * When `true`, attempt to keep the original line structure when applying edits.
+   */
+  keepLines?: boolean;
+  /**
+   * Indent size when {@link JsoncFormattingOptions.insertSpaces | insertSpaces} is `true`.
+   */
+  tabSize?: number;
+};
+/**
+ * Options accepted by the `ini` library's `stringify` / `encode` functions.
+ * Kept as a local definition so the types compile without the optional peer installed.
+ */
+type IniEncodeOptions = {
+  /**
+   * Align `=` signs across the output.
+   */
+  align?: boolean;
+  /**
+   * Serialize array values using the `key[]` convention. Defaults to `true`.
+   */
+  bracketedArray?: boolean;
+  /**
+   * Append a trailing newline to every section.
+   */
+  newline?: boolean;
+  /**
+   * Target platform for section/key escaping. Defaults to the current platform.
+   */
+  platform?: string;
+  /**
+   * Name of the top-level section.
+   */
+  section?: string;
+  /**
+   * Sort keys alphabetically within sections.
+   */
+  sort?: boolean;
+  /**
+   * Write `key = value` with spaces around `=`. Defaults to `false`.
+   */
+  whitespace?: boolean;
+};
+/**
+ * Replacer accepted by `JSON5.stringify()`.
+ */
+type Json5Replacer = (number | string)[] | ((this: unknown, key: string, value: unknown) => unknown) | null;
+/**
+ * Options for the `glob` and `globSync` functions.
+ *
+ * Re-exported from [`tinyglobby`](https://github.com/SuperchupuDev/tinyglobby) (which is bundled into the built
+ * output, with a local patch adding negated-ignore support). The `ignore` option accepts leading-`!` patterns to
+ * _un-ignore_ entries — for example `ignore: ["dist/**", "!dist/index.d.ts"]` drops the `dist/` tree except for
+ * its type entry point.
+ */
+type GlobOptions = Omit<GlobOptions$1, "patterns">;
+/**
+ * Options for the `walk` and `walkSync` functions.
+ */
+interface WalkOptions {
+  /**
+   * List of file extensions used to filter entries.
+   * If specified, entries without the file extension specified by this option are excluded.
+   * @default {undefined}
+   */
+  extensions?: string[];
+  /**
+   * Indicates whether symlinks should be resolved or not.
+   * @default {false}
+   */
+  followSymlinks?: boolean;
+  /**
+   * Indicates whether directory entries should be included or not.
+   * @default {true}
+   */
+  includeDirs?: boolean;
+  /**
+   * Indicates whether file entries should be included or not.
+   * @default {true}
+   */
+  includeFiles?: boolean;
+  /**
+   * Indicates whether symlink entries should be included or not.
+   * This option is meaningful only if `followSymlinks` is set to `false`.
+   * @default {true}
+   */
+  includeSymlinks?: boolean;
+  /**
+   * List of regular expression or glob patterns used to filter entries.
+   * If specified, entries that do not match the patterns specified by this option are excluded.
+   * @default {undefined}
+   */
+  match?: (RegExp | string)[];
+  /**
+   * The maximum depth of the file tree to be walked recursively.
+   * @default {Infinity}
+   */
+  maxDepth?: number;
+  /**
+   * List of regular expression or glob patterns used to filter entries.
+   * If specified, entries matching the patterns specified by this option are excluded.
+   * @default {undefined}
+   */
+  skip?: (RegExp | string)[];
+}
+/**
+ * Represents an entry found by `walk` or `walkSync`.
+ */
+interface WalkEntry extends Pick<Dirent, "isDirectory" | "isFile" | "isSymbolicLink" | "name"> {
+  /** The full path to the entry. */
+  path: string;
+}
+/**
+ * Supported compression types for file operations.
+ */
+type CompressionType = "brotli" | "gzip" | "none";
+/**
+ * Supported file encodings for reading files.
+ */
+type ReadFileEncoding = "ascii" | "base64" | "base64url" | "hex" | "latin1" | "ucs-2" | "ucs2" | "utf-8" | "utf-16le" | "utf8" | "utf16le";
+/**
+ * Options for reading files.
+ */
+type ReadFileOptions<C> = {
+  /**
+   * Return content as a Buffer. Default: `false`
+   */
+  buffer?: boolean;
+  /**
+   * Compression method to decompress the file against. Default: `none`
+   */
+  compression?: C;
+  /**
+   * The encoding to use. Default: `utf8`
+   * @see https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings
+   */
+  encoding?: ReadFileEncoding;
+  /**
+   * The flag used to open the file. Default: `r`
+   */
+  flag?: number | string;
+};
+/**
+ * Represents the content type of a read file, which can be a Buffer or a string based on options.
+ * @template O - The ReadFileOptions type.
+ */
+type ContentType<O = undefined> = O extends {
+  buffer: true;
+} ? Buffer : string;
+/**
+ * Type for the `reviver` parameter of `JSON.parse()`.
+ * A function that transforms the results. This function is called for each member of the object.
+ * If a member contains nested objects, the nested objects are transformed before the parent object is.
+ */
+type JsonReviver = Parameters<(typeof JSON)["parse"]>["1"];
+/**
+ * Specifies a location (line and column) in a file for code frame generation.
+ */
+type CodeFrameLocation = {
+  /** The column number. */
+  column?: number;
+  /** The line number. */
+  line: number;
+};
+/**
+ * Options for customizing the appearance of code frames.
+ */
+type CodeFrameOptions = {
+  /** Colorization methods for different parts of the code frame. */
+  color?: {
+    /** Color for the gutter (line numbers). */
+    gutter?: ColorizeMethod;
+    /** Color for the marker (pointing to the error). */
+    marker?: ColorizeMethod;
+    /** Color for the message. */
+    message?: ColorizeMethod;
+  };
+};
+/**
+ * Options for reading and parsing JSON files.
+ * Extends {@link CodeFrameOptions}.
+ */
+type ReadJsonOptions = CodeFrameOptions & {
+  /**
+   * A function to transform the string content before parsing.
+   * @param source The raw string content of the file.
+   * @returns The transformed string content.
+   */
+  beforeParse?: (source: string) => string;
+};
+/**
+ * Options for writing files.
+ */
+type WriteFileOptions = {
+  /**
+   * When `true` and the target file already exists, the previous contents are
+   * preserved by renaming the existing file to `${path}.bak` before the new
+   * contents are written. This is independent of {@link WriteFileOptions.overwrite}.
+   *
+   * Default: `false`
+   */
+  backup?: boolean;
+  /**
+   * The group and user ID used to set the file ownership. Default: `undefined`
+   */
+  chown?: {
+    gid: number;
+    uid: number;
+  };
+  /**
+   * The encoding to use. Default: `utf8`
+   */
+  encoding?: BufferEncoding | null;
+  /**
+   * The flag used to write the file. Append flags (containing `a`) concatenate
+   * the new contents onto the existing file; exclusive flags (containing `x`)
+   * throw an `AlreadyExistsError` when the file already exists. Default: `w`
+   */
+  flag?: string;
+  /**
+   * The file mode (permission and sticky bits). Default: `0o666`
+   */
+  mode?: number;
+  /**
+   * Indicates whether the file should be overwritten if it already exists.
+   * When `false` and the target already exists, an `AlreadyExistsError` is thrown.
+   *
+   * Default: `true`
+   */
+  overwrite?: boolean;
+  /**
+   * Recursively create parent directories if needed. Default: `true`
+   */
+  recursive?: boolean;
+};
+/**
+ * Type for the `replacer` parameter of `JSON.stringify()`.
+ * Can be a function that alters the behavior of the stringification process,
+ * or an array of strings and numbers that acts as a whitelist for selecting
+ * the properties of the value object to be included in the JSON string.
+ * If this value is null or not provided, all properties of the object are included in the resulting JSON string.
+ */
+type JsonReplacer = (number | string)[] | ((this: unknown, key: string, value: unknown) => unknown) | null;
+/**
+ * Type for the `replacer` parameter used in YAML serialization, similar to `JSON.stringify`'s replacer.
+ * @deprecated Use {@link JsonReplacer} directly instead.
+ */
+type YamlReplacer = JsonReplacer;
+/**
+ * Options for writing JSON files.
+ * Extends {@link WriteFileOptions}.
+ */
+type WriteJsonOptions = WriteFileOptions & {
+  /**
+   * Detect indentation automatically if the file exists. Default: `false`
+   */
+  detectIndent?: boolean;
+  /**
+   * The space used for pretty-printing.
+   *
+   * Pass in `undefined` for no formatting.
+   */
+  indent?: number | string;
+  /**
+   * Passed into `JSON.stringify`.
+   */
+  replacer?: JsonReplacer;
+  /**
+   * Override the default `JSON.stringify` method.
+   */
+  stringify?: (data: unknown, replacer: JsonReplacer, space: number | string | undefined) => string;
+};
+/**
+ * Options for the `findUp` and `findUpSync` functions.
+ */
+type FindUpOptions = {
+  /**
+   * Whether to follow symbolic links.
+   * @default undefined (behaves like `true` for `findUp`, `false` for `findUpSync` due to `fs.stat` vs `fs.lstat`)
+   */
+  allowSymlinks?: boolean;
+  /**
+   * The current working directory.
+   * @default process.cwd()
+   */
+  cwd?: URL | string;
+  /**
+   * The directory to stop searching at.
+   * @default path.parse(cwd).root
+   */
+  stopAt?: URL | string;
+  /**
+   * The type of path to find.
+   * @default "file"
+   */
+  type?: "directory" | "file";
+};
+/**
+ * The result type for the name matcher function used in `findUp`.
+ * It can be a `PathLike` (string, Buffer, or URL), a Promise resolving to `PathLike` or `FIND_UP_STOP`,
+ * `FIND_UP_STOP` to stop the search, or `undefined` to continue.
+ */
+type FindUpNameFnResult = PathLike | Promise<PathLike | typeof FIND_UP_STOP> | typeof FIND_UP_STOP | undefined;
+/**
+ * Specifies the name(s) of the file or directory to search for in `findUp`.
+ * Can be a single name, an array of names, or a function that returns a name or `FIND_UP_STOP`.
+ */
+type FindUpName = string[] | string | ((directory: string) => FindUpNameFnResult);
+/**
+ * The result type for the name matcher function used in `findUpSync`.
+ * It can be a `PathLike` (string, Buffer, or URL), `FIND_UP_STOP` to stop the search,
+ * or `undefined` to continue.
+ */
+type FindUpNameSyncFnResult = PathLike | typeof FIND_UP_STOP | undefined;
+/**
+ * Specifies the name(s) of the file or directory to search for in `findUpSync`.
+ * Can be a single name, an array of names, or a function that returns a name or `FIND_UP_STOP`.
+ */
+type FindUpNameSync = string[] | string | ((directory: string) => FindUpNameSyncFnResult);
+/**
+ * Options for operations that might require retries, like `emptyDir` or `remove`.
+ */
+type RetryOptions = {
+  /**
+   * If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or
+   * `EPERM` error is encountered, Node.js will retry the operation with a linear
+   * backoff wait of `retryDelay` ms longer on each try. This option represents the
+   * number of retries. This option is ignored if the `recursive` option is not
+   * `true` for operations that support it (like `rm`).
+   * @default 0
+   */
+  maxRetries?: number;
+  /**
+   * The amount of time in milliseconds to wait between retries.
+   * This option is ignored if the `recursive` option is not `true` for operations that support it.
+   * @default 100
+   */
+  retryDelay?: number;
+};
+/**
+ * Options for reading YAML files.
+ * Combines options from `yaml` library (DocumentOptions, ParseOptions, SchemaOptions, ToJSOptions)
+ * and custom {@link ReadFileOptions}.
+ */
+type ReadYamlOptions<C> = ReadFileOptions<C> & ParseOptions;
+/**
+ * Type for the `reviver` parameter used in YAML deserialization, similar to `JSON.parse`'s reviver.
+ * A function that transforms the results. This function is called for each member of the object.
+ * If a member contains nested objects, the nested objects are transformed before the parent object is.
+ */
+type YamlReviver = (key: unknown, value: unknown) => unknown;
+/**
+ * Options for writing YAML files.
+ * Extends {@link WriteFileOptions} and includes options from the `yaml` library for stringification.
+ */
+type WriteYamlExtras = {
+  /**
+   * Passed into `yaml.stringify` as the replacer argument.
+   */
+  replacer?: JsonReplacer;
+  /**
+   * Passed into `yaml.stringify` as the space argument for indentation.
+   * Can be a number of spaces or a string (e.g., a tab character).
+   */
+  space?: number | string;
+};
+type WriteYamlOptions = WriteFileOptions & WriteYamlExtras & StringifyOptions;
+/**
+ * Options for reading TOML files.
+ * Uses `smol-toml`, which does not expose additional parse options.
+ */
+type ReadTomlOptions<C> = ReadFileOptions<C>;
+/**
+ * Options for writing TOML files.
+ * Extends {@link WriteFileOptions}. `smol-toml` does not expose additional stringify options.
+ */
+type WriteTomlOptions = WriteFileOptions;
+/**
+ * Extra options for JSONC parsing on top of file-reading and code-frame options.
+ */
+type ReadJsoncExtras = {
+  /**
+   * A function to transform the string content before parsing.
+   * @param source The raw string content of the file.
+   * @returns The transformed string content.
+   */
+  beforeParse?: (source: string) => string;
+};
+/**
+ * Options for reading JSONC (JSON with comments) files.
+ * Combines options from `jsonc-parser` and custom {@link ReadFileOptions} and {@link CodeFrameOptions}.
+ */
+type ReadJsoncOptions<C> = CodeFrameOptions & JsoncParseOptions & ReadFileOptions<C> & ReadJsoncExtras;
+/**
+ * Options for writing JSONC files with optional comment preservation.
+ * Extends {@link WriteFileOptions}.
+ */
+type WriteJsoncOptions = WriteFileOptions & {
+  /**
+   * Detect indentation automatically if the file exists. Default: `false`.
+   */
+  detectIndent?: boolean;
+  /**
+   * Formatting options forwarded to `jsonc-parser` when modifying existing files.
+   */
+  formattingOptions?: JsoncFormattingOptions;
+  /**
+   * Indentation used when writing a fresh file (no existing file to preserve).
+   * Default: `"\t"`.
+   */
+  indent?: number | string;
+  /**
+   * When `true` and the file already exists, preserve existing comments and formatting
+   * by computing a minimal diff against the new data via `jsonc-parser`'s `modify` API. Default: `true`.
+   */
+  preserveComments?: boolean;
+  /**
+   * Passed into `JSON.stringify` when writing a fresh file.
+   */
+  replacer?: JsonReplacer;
+};
+/**
+ * Type for the `reviver` parameter of `JSON5.parse()`.
+ */
+type Json5Reviver = (this: unknown, key: string, value: unknown) => unknown;
+/**
+ * Extra options for JSON5 parsing on top of file-reading and code-frame options.
+ */
+type ReadJson5Extras = {
+  /**
+   * A function to transform the string content before parsing.
+   */
+  beforeParse?: (source: string) => string;
+};
+/**
+ * Options for reading JSON5 files.
+ */
+type ReadJson5Options<C> = CodeFrameOptions & ReadFileOptions<C> & ReadJson5Extras;
+/**
+ * Options for writing JSON5 files.
+ * Extends {@link WriteFileOptions}.
+ */
+type WriteJson5Options = WriteFileOptions & {
+  /**
+   * Detect indentation automatically if the file exists. Default: `false`.
+   */
+  detectIndent?: boolean;
+  /**
+   * Indentation for pretty-printing.
+   */
+  indent?: number | string;
+  /**
+   * Override the quote character used for strings. See `JSON5.stringify`.
+   */
+  quote?: string;
+  /**
+   * Passed into `JSON5.stringify`.
+   */
+  replacer?: Json5Replacer;
+};
+/**
+ * Options for reading INI files.
+ */
+type ReadIniOptions<C> = ReadFileOptions<C> & {
+  /**
+   * Parse array values (keys ending with `[]`) into native arrays. Default: `true`.
+   */
+  bracketedArray?: boolean;
+};
+/**
+ * Supported INI line-ending values.
+ */
+type IniLineEnding = "\n" | "\r\n";
+/**
+ * Extra options for INI writing on top of the `ini` encoder options and file-writing options.
+ */
+type WriteIniExtras = {
+  /**
+   * Line ending to write. When omitted and {@link WriteIniOptions.preserveStyle | preserveStyle} is `true`,
+   * the line ending is auto-detected from the existing file. Falls back to `"\n"` otherwise.
+   */
+  eol?: IniLineEnding;
+  /**
+   * When `true` and the file already exists, auto-detect and preserve styling described on this type.
+   * Defaults to `true`. Explicit `whitespace` / `eol` values always win over detection.
+   */
+  preserveStyle?: boolean;
+};
+/**
+ * Options for writing INI files.
+ *
+ * Extends {@link WriteFileOptions} and `ini`'s {@link IniEncodeOptions}. When an existing file is present and
+ * {@link WriteIniOptions.preserveStyle | preserveStyle} is `true` (the default), the following styling is
+ * detected from that file and applied unless overridden: space around `=` (via {@link IniEncodeOptions.whitespace | whitespace}),
+ * line ending (via {@link WriteIniOptions.eol | eol}), and per-key original lines (including trailing
+ * whitespace and inline `;` / `#` comments) for unchanged values.
+ */
+type WriteIniOptions = IniEncodeOptions & WriteFileOptions & WriteIniExtras;
+export { CodeFrameLocation as A, FIND_UP_STOP as B, CompressionType as C, F_OK as D, FindUpNameFnResult as E, FindUpName as F, FindUpNameSyncFnResult as G, GlobOptions as H, IniEncodeOptions as I, Json5Reviver as J, R_OK as K, ReadFileEncoding as L, W_OK as M, ReadIniOptions as R, WriteIniOptions as W, X_OK as X, YamlReviver as Y, IniLineEnding as a, ReadJson5Options as b, WriteJson5Options as c, Json5Replacer as d, ReadJsoncOptions as e, WriteJsoncOptions as f, JsoncFormattingOptions as g, JsoncParseOptions as h, ReadTomlOptions as i, WriteTomlOptions as j, CodeFrameOptions as k, JsonReviver as l, ReadYamlOptions as m, WriteYamlOptions as n, JsonReplacer as o, YamlReplacer as p, WalkOptions as q, FindUpOptions as r, FindUpNameSync as s, WalkEntry as t, ReadFileOptions as u, ContentType as v, ReadJsonOptions as w, RetryOptions as x, WriteFileOptions as y, WriteJsonOptions as z };