@ac-kit/app-config 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-2026 Anthony Champagne and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,33 @@
+# @ac-kit/app-config
+
+Loading a command-line tool's configuration file, wherever the user put it.
+
+A CLI is expected to find its config in any of a dozen places — `package.json`,
+a dotfile, a `.config/` directory, with or without an extension — and to let one
+config `extends` another, the way `tsconfig.json` and `.eslintrc` do. This does
+both: `cosmiconfig` performs the search, and this resolves the `extends` chain,
+merges it over your defaults, and hands back a validated object with `extends`
+already removed.
+
+```typescript
+import { loadCliConfig } from "@ac-kit/app-config";
+
+const config = await loadCliConfig(
+  "mytool",
+  (value) => myToolConfigSchema.parse(value),
+  { outDir: "dist", strict: true },
+);
+```
+
+`loadCliConfig` throws when no configuration file is found; the parser you pass
+decides what an invalid one does.
+
+Also exposes `resolveExtendableConfig` and `resolveExtendsValue` for resolving
+an `extends` chain you already loaded yourself, and `editorconfig` helpers for
+reading `.editorconfig` settings.
+
+Node only: it reads the filesystem.
+
+See the
+[generated API docs](https://anthochamp.github.io/node-essentials/api/app-config/)
+for the full reference.

package/dist/editorconfig.d.ts

@@ -0,0 +1,27 @@
+import { type EditorConfigProperties, type EditorConfigSource } from "@ac-kit/format-editorconfig";
+/** Options for {@link readEditorConfigSources}. */
+export type EditorConfigWalkOptions = {
+    /**
+     * Directory to stop at, even if no `root = true` was found. Defaults to the
+     * filesystem root.
+     */
+    readonly stopAt?: string;
+};
+/**
+ * Reads every `.editorconfig` governing `filePath`, outermost first.
+ *
+ * Ascends from the file's own directory, stopping at the first file declaring
+ * `root = true` (that file included) or at
+ * {@link EditorConfigWalkOptions.stopAt}. A directory with no `.editorconfig`,
+ * or one that cannot be read, is skipped — the search is best-effort by design,
+ * since an unreadable parent directory is a permissions fact rather than a
+ * configuration error.
+ *
+ * This is the host-bound half of EditorConfig support;
+ * `@ac-kit/format-editorconfig` owns the parsing and resolution and stays
+ * portable.
+ */
+export declare function readEditorConfigSources(filePath: string, options?: EditorConfigWalkOptions): Promise<EditorConfigSource[]>;
+/** Resolves the EditorConfig properties that apply to `filePath` on disk. */
+export declare function readEditorConfig(filePath: string, options?: EditorConfigWalkOptions): Promise<EditorConfigProperties>;
+//# sourceMappingURL=editorconfig.d.ts.map

package/dist/editorconfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editorconfig.d.ts","sourceRoot":"","sources":["../src/editorconfig.ts"],"names":[],"mappings":"AAGA,OAAO,EACN,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EAGvB,MAAM,6BAA6B,CAAC;AAIrC,mDAAmD;AACnD,MAAM,MAAM,uBAAuB,GAAG;IACrC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,uBAAuB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,uBAAuB,GAC/B,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAoC/B;AAED,6EAA6E;AAC7E,wBAAsB,gBAAgB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CAGjC"}

package/dist/editorconfig.js

@@ -0,0 +1,61 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parseEditorConfig, resolveEditorConfig, } from "@ac-kit/format-editorconfig";
+const FILE_NAME_ = ".editorconfig";
+/**
+ * Reads every `.editorconfig` governing `filePath`, outermost first.
+ *
+ * Ascends from the file's own directory, stopping at the first file declaring
+ * `root = true` (that file included) or at
+ * {@link EditorConfigWalkOptions.stopAt}. A directory with no `.editorconfig`,
+ * or one that cannot be read, is skipped — the search is best-effort by design,
+ * since an unreadable parent directory is a permissions fact rather than a
+ * configuration error.
+ *
+ * This is the host-bound half of EditorConfig support;
+ * `@ac-kit/format-editorconfig` owns the parsing and resolution and stays
+ * portable.
+ */
+export async function readEditorConfigSources(filePath, options) {
+    const absolute = path.resolve(filePath);
+    const stopAt = options?.stopAt ? path.resolve(options.stopAt) : undefined;
+    const sources = [];
+    let directory = path.dirname(absolute);
+    for (;;) {
+        let contents;
+        try {
+            contents = await readFile(path.join(directory, FILE_NAME_), "utf-8");
+        }
+        catch {
+            contents = undefined;
+        }
+        if (contents !== undefined) {
+            const file = parseEditorConfig(contents);
+            // Collected innermost first, reversed below: the caller's contract is
+            // outermost first, and the root is only discovered on the way up.
+            sources.push({ directory: toPosix(directory), file });
+            if (file.root) {
+                break;
+            }
+        }
+        if (stopAt !== undefined && directory === stopAt) {
+            break;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            break;
+        }
+        directory = parent;
+    }
+    return sources.reverse();
+}
+/** Resolves the EditorConfig properties that apply to `filePath` on disk. */
+export async function readEditorConfig(filePath, options) {
+    const sources = await readEditorConfigSources(filePath, options);
+    return resolveEditorConfig(sources, toPosix(path.resolve(filePath)));
+}
+/** Section globs are always `/`-separated, whatever the host uses. */
+function toPosix(value) {
+    return value.split(path.sep).join("/");
+}
+//# sourceMappingURL=editorconfig.js.map

package/dist/editorconfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"editorconfig.js","sourceRoot":"","sources":["../src/editorconfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAGN,iBAAiB,EACjB,mBAAmB,GACnB,MAAM,6BAA6B,CAAC;AAErC,MAAM,UAAU,GAAG,eAAe,CAAC;AAWnC;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC5C,QAAgB,EAChB,OAAiC;IAEjC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE1E,MAAM,OAAO,GAAyB,EAAE,CAAC;IACzC,IAAI,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAEvC,SAAS,CAAC;QACT,IAAI,QAA4B,CAAC;QACjC,IAAI,CAAC;YACJ,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,EAAE,OAAO,CAAC,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACR,QAAQ,GAAG,SAAS,CAAC;QACtB,CAAC;QAED,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YACzC,sEAAsE;YACtE,kEAAkE;YAClE,OAAO,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;YACtD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACf,MAAM;YACP,CAAC;QACF,CAAC;QAED,IAAI,MAAM,KAAK,SAAS,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;YAClD,MAAM;QACP,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACvC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM;QACP,CAAC;QACD,SAAS,GAAG,MAAM,CAAC;IACpB,CAAC;IAED,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;AAC1B,CAAC;AAED,6EAA6E;AAC7E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,QAAgB,EAChB,OAAiC;IAEjC,MAAM,OAAO,GAAG,MAAM,uBAAuB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACjE,OAAO,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,sEAAsE;AACtE,SAAS,OAAO,CAAC,KAAa;IAC7B,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxC,CAAC"}

package/dist/extendable-config/resolve-extendable-config.d.ts

@@ -0,0 +1,62 @@
+import type { UnknownRecord } from "type-fest";
+/**
+ * A configuration object that can extend other configurations via the "extends"
+ * property.
+ *
+ * The "extends" property can be a string or an array of strings, each
+ * representing a module to extend from. The modules will be resolved and merged
+ * into the current configuration.
+ *
+ * Additional properties can be defined as needed.
+ */
+export type ExtendableConfig = UnknownRecord & {
+    /**
+     * A module or an array of modules to extend from.
+     *
+     * Each module can be: - A package name (e.g. "my-config-package"). - A scoped
+     * package name (e.g. "@my-scope/my-config-package"). - A relative or absolute
+     * path to a configuration file.
+     *
+     * The modules will be resolved and merged in the order they are listed.
+     */
+    extends?: string | string[];
+};
+/**
+ * A parser function to validate and transform an extendable configuration
+ * object.
+ *
+ * This function should take the raw configuration data (e.g. from a JSON file
+ * or module) and return a valid `ExtendableConfig` object. It can also throw an
+ * error if the data is invalid.
+ *
+ * @param data The raw configuration data to parse.
+ * @returns The parsed and validated `ExtendableConfig` object.
+ */
+export type ExtendableConfigParser = (data: unknown) => ExtendableConfig;
+/** Options for resolving an extendable configuration. */
+export type ResolveExtendableConfigOptions = {
+    /**
+     * Arguments to pass to configuration modules that export a function.
+     *
+     * If a configuration module exports a function, it will be called with these
+     * arguments to obtain the configuration object.
+     *
+     * Default is an empty array (no arguments).
+     */
+    moduleFunctionCallArgs?: unknown[];
+    /** A callback function that is called when a circular dependency is detected. */
+    onCircularDependency?: ((moduleId: string, modulePath: string, configPath: string) => void) | null;
+};
+/**
+ * Resolve an extendable configuration (with "extends"-property).
+ *
+ * @param configData The configuration data to resolve.
+ * @param configPath The path of the configuration file (used for resolving
+ *   relative paths).
+ * @param configParser The parser function to parse configuration modules.
+ * @param configId The configuration ID (e.g. "eslint", "babel", etc.).
+ * @param options The options for resolving the configuration.
+ * @returns The resolved configuration data, without the "extends"-property.
+ */
+export declare function resolveExtendableConfig<T extends ExtendableConfig>(configData: T, configPath: string, configParser: ExtendableConfigParser, configId: string, options?: ResolveExtendableConfigOptions): Promise<Omit<T, "extends">>;
+//# sourceMappingURL=resolve-extendable-config.d.ts.map

package/dist/extendable-config/resolve-extendable-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-extendable-config.d.ts","sourceRoot":"","sources":["../../src/extendable-config/resolve-extendable-config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAI/C;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG;IAC9C;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,gBAAgB,CAAC;AAEzE,yDAAyD;AACzD,MAAM,MAAM,8BAA8B,GAAG;IAC5C;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,OAAO,EAAE,CAAC;IAEnC,iFAAiF;IACjF,oBAAoB,CAAC,EAClB,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC,GACpE,IAAI,CAAC;CACR,CAAC;AAQF;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,SAAS,gBAAgB,EACvE,UAAU,EAAE,CAAC,EACb,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,sBAAsB,EACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,8BAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAe7B"}

package/dist/extendable-config/resolve-extendable-config.js

@@ -0,0 +1,94 @@
+import * as path from "node:path";
+import { alwaysIterable, clone, defaults, mergeInplace } from "@ac-kit/core";
+import { resolveExtendsValue } from "./resolve-extends-value.js";
+const RESOLVE_EXTENDABLE_CONFIG_DEFAULT_OPTIONS = {
+    moduleFunctionCallArgs: [],
+    onCircularDependency: null,
+};
+/**
+ * Resolve an extendable configuration (with "extends"-property).
+ *
+ * @param configData The configuration data to resolve.
+ * @param configPath The path of the configuration file (used for resolving
+ *   relative paths).
+ * @param configParser The parser function to parse configuration modules.
+ * @param configId The configuration ID (e.g. "eslint", "babel", etc.).
+ * @param options The options for resolving the configuration.
+ * @returns The resolved configuration data, without the "extends"-property.
+ */
+export async function resolveExtendableConfig(configData, configPath, configParser, configId, options) {
+    const effectiveOptions = defaults(options, RESOLVE_EXTENDABLE_CONFIG_DEFAULT_OPTIONS);
+    return internalResolveExtendableConfig(configData, configPath, configParser, configId, effectiveOptions, new Set(), new Set());
+}
+/**
+ * @param configData The configuration data to resolve.
+ * @param configPath The path of the configuration file (used for resolving
+ *   relative paths).
+ * @param configParser The parser function to parse configuration modules.
+ * @param configId The configuration ID (e.g. "eslint", "babel", etc.).
+ * @param options The options for resolving the configuration.
+ * @param globalList A set of already resolved module paths (to avoid
+ *   duplicates).
+ * @param branchList A set of module paths in the current resolution branch (to
+ *   detect circular dependencies).
+ * @returns The resolved configuration data, without the "extends"-property.
+ * @internal
+ *
+ * Internal function to recursively resolve an extendable configuration.
+ */
+async function internalResolveExtendableConfig(configData, configPath, configParser, configId, options, globalList, branchList) {
+    const { extends: extendsData, ...restConfig } = configData;
+    const extendsValues = alwaysIterable(extendsData ?? []);
+    const finalConfig = clone(restConfig, { recursive: true });
+    for (const extendsValue of extendsValues) {
+        let moduleId;
+        let modulePath;
+        try {
+            const result = resolveExtendsValue(extendsValue, configId, [configPath]);
+            if (!result) {
+                throw new Error("not found");
+            }
+            moduleId = result.id;
+            modulePath = result.path;
+        }
+        catch (error) {
+            throw new Error(`resolve module "${extendsValue}" (referenced from "${configPath}")`, {
+                cause: error,
+            });
+        }
+        if (branchList.has(modulePath)) {
+            options.onCircularDependency?.(moduleId, modulePath, configPath);
+            continue;
+        }
+        if (globalList.has(modulePath)) {
+            continue;
+        }
+        globalList.add(modulePath);
+        const module = await import(modulePath);
+        let moduleData;
+        if (typeof module.default === "function") {
+            moduleData = module.default(...options.moduleFunctionCallArgs);
+        }
+        else if (typeof module === "function") {
+            moduleData = module(...options.moduleFunctionCallArgs);
+        }
+        else {
+            moduleData = module.default || module;
+        }
+        let moduleConfig;
+        try {
+            moduleConfig = configParser(moduleData);
+        }
+        catch (error) {
+            throw new Error(`validate config from module "${moduleId}" (referenced from "${configPath}")`, { cause: error });
+        }
+        const resolvedConfig = await internalResolveExtendableConfig(moduleConfig, path.dirname(modulePath), configParser, configId, options, globalList, new Set([...branchList, modulePath]));
+        void mergeInplace(finalConfig, resolvedConfig, {
+            recursive: true,
+            cloneSource: true,
+            arrayMergeMode: "spread",
+        });
+    }
+    return finalConfig;
+}
+//# sourceMappingURL=resolve-extendable-config.js.map

package/dist/extendable-config/resolve-extendable-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-extendable-config.js","sourceRoot":"","sources":["../../src/extendable-config/resolve-extendable-config.ts"],"names":[],"mappings":"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"}

package/dist/extendable-config/resolve-extends-value.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @param value The "extends"-property value to resolve.
+ * @param configId The configuration ID (e.g. "eslint", "babel", etc.).
+ * @param searchPaths The paths to use for module resolution.
+ * @returns The resolve entry name and the resolved module name, or null if not
+ *   found.
+ * @internal
+ *
+ * Resolve the value of an "extends" property in a configuration file.
+ *
+ * Rules:
+ * 1) If the value starts with a @, it is a scoped package. If it does not contain
+ *  a / after the scope, add /<configId>-config. Then check if the package is
+ * resolvable. If not, return null.
+ * 2) If the value does not start with a @,
+ * - First try to resolve @<configId>/config-<value>.
+ * - If that fails, try to resolve <configId>-config-<value> (old style).
+ * - If that fails, try to resolve <value> as is.
+ * - If all attempts fail, return null.
+ */
+export declare function resolveExtendsValue(value: string, configId: string, searchPaths?: string[]): {
+    id: string;
+    path: string;
+} | null;
+//# sourceMappingURL=resolve-extends-value.d.ts.map

package/dist/extendable-config/resolve-extends-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-extends-value.d.ts","sourceRoot":"","sources":["../../src/extendable-config/resolve-extends-value.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,EAAE,GACpB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAwCrC"}

package/dist/extendable-config/resolve-extends-value.js

@@ -0,0 +1,54 @@
+import { resolveModule } from "@ac-kit/node";
+/**
+ * @param value The "extends"-property value to resolve.
+ * @param configId The configuration ID (e.g. "eslint", "babel", etc.).
+ * @param searchPaths The paths to use for module resolution.
+ * @returns The resolve entry name and the resolved module name, or null if not
+ *   found.
+ * @internal
+ *
+ * Resolve the value of an "extends" property in a configuration file.
+ *
+ * Rules:
+ * 1) If the value starts with a @, it is a scoped package. If it does not contain
+ *  a / after the scope, add /<configId>-config. Then check if the package is
+ * resolvable. If not, return null.
+ * 2) If the value does not start with a @,
+ * - First try to resolve @<configId>/config-<value>.
+ * - If that fails, try to resolve <configId>-config-<value> (old style).
+ * - If that fails, try to resolve <value> as is.
+ * - If all attempts fail, return null.
+ */
+export function resolveExtendsValue(value, configId, searchPaths) {
+    let path;
+    if (value[0] === "@") {
+        if (!value.includes("/")) {
+            value += `/${configId}-config`;
+        }
+        path = resolveModule(value, searchPaths);
+        if (path) {
+            return { id: value, path };
+        }
+        return null;
+    }
+    const officialMissingPart = `@${configId}/config`;
+    let testName = `${officialMissingPart}-${value}`;
+    path = resolveModule(testName, searchPaths);
+    if (path) {
+        return { id: testName, path };
+    }
+    const oldStyleOfficialMissingPart = `${configId}-config`;
+    if (!value.startsWith(oldStyleOfficialMissingPart)) {
+        testName = `${oldStyleOfficialMissingPart}-${value}`;
+        path = resolveModule(testName, searchPaths);
+        if (path) {
+            return { id: testName, path };
+        }
+    }
+    path = resolveModule(value, searchPaths);
+    if (path) {
+        return { id: value, path };
+    }
+    return null;
+}
+//# sourceMappingURL=resolve-extends-value.js.map

package/dist/extendable-config/resolve-extends-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-extends-value.js","sourceRoot":"","sources":["../../src/extendable-config/resolve-extends-value.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,mBAAmB,CAClC,KAAa,EACb,QAAgB,EAChB,WAAsB;IAEtB,IAAI,IAAmB,CAAC;IAExB,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,KAAK,IAAI,IAAI,QAAQ,SAAS,CAAC;QAChC,CAAC;QAED,IAAI,GAAG,aAAa,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QACzC,IAAI,IAAI,EAAE,CAAC;YACV,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC5B,CAAC;QAED,OAAO,IAAI,CAAC;IACb,CAAC;IAED,MAAM,mBAAmB,GAAG,IAAI,QAAQ,SAAS,CAAC;IAClD,IAAI,QAAQ,GAAG,GAAG,mBAAmB,IAAI,KAAK,EAAE,CAAC;IAEjD,IAAI,GAAG,aAAa,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC5C,IAAI,IAAI,EAAE,CAAC;QACV,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC/B,CAAC;IAED,MAAM,2BAA2B,GAAG,GAAG,QAAQ,SAAS,CAAC;IACzD,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,2BAA2B,CAAC,EAAE,CAAC;QACpD,QAAQ,GAAG,GAAG,2BAA2B,IAAI,KAAK,EAAE,CAAC;QAErD,IAAI,GAAG,aAAa,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QAC5C,IAAI,IAAI,EAAE,CAAC;YACV,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAC/B,CAAC;IACF,CAAC;IAED,IAAI,GAAG,aAAa,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;IACzC,IAAI,IAAI,EAAE,CAAC;QACV,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC5B,CAAC;IAED,OAAO,IAAI,CAAC;AACb,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./editorconfig.js";
+export * from "./extendable-config/resolve-extendable-config.js";
+export * from "./extendable-config/resolve-extends-value.js";
+export * from "./load-config.js";
+export * from "./resolve-config-value.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kDAAkD,CAAC;AACjE,cAAc,8CAA8C,CAAC;AAC7D,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./editorconfig.js";
+export * from "./extendable-config/resolve-extendable-config.js";
+export * from "./extendable-config/resolve-extends-value.js";
+export * from "./load-config.js";
+export * from "./resolve-config-value.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,kDAAkD,CAAC;AACjE,cAAc,8CAA8C,CAAC;AAC7D,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC"}

package/dist/load-config.d.ts

@@ -0,0 +1,18 @@
+import type { PartialDeep } from "type-fest";
+import { type ExtendableConfig, type ExtendableConfigParser, type ResolveExtendableConfigOptions } from "./extendable-config/resolve-extendable-config.js";
+/** Options for loading CLI configuration. */
+export type LoadConfigOptions = {
+    /** Options for resolving "extends" field in the configuration. */
+    resolveExtendsOptions?: ResolveExtendableConfigOptions;
+};
+/**
+ * Load a CLI configuration file using cosmiconfig, supporting "extends" field.
+ *
+ * @param configId The configuration ID (name) to search for.
+ * @param configParser A parser to validate/transform the config object.
+ * @param defaultConfig Default configuration values.
+ * @param options Optional settings for loading and resolving the config.
+ * @returns The resolved configuration object without the "extends" field.
+ */
+export declare function loadCliConfig<T extends ExtendableConfig>(configId: string, configParser: ExtendableConfigParser, defaultConfig: PartialDeep<T>, options?: LoadConfigOptions): Promise<Omit<T, "extends">>;
+//# sourceMappingURL=load-config.d.ts.map

package/dist/load-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-config.d.ts","sourceRoot":"","sources":["../src/load-config.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,8BAA8B,EAEnC,MAAM,kDAAkD,CAAC;AAE1D,6CAA6C;AAC7C,MAAM,MAAM,iBAAiB,GAAG;IAC/B,kEAAkE;IAClE,qBAAqB,CAAC,EAAE,8BAA8B,CAAC;CACvD,CAAC;AAMF;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,gBAAgB,EAC7D,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,sBAAsB,EACpC,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC,EAC7B,OAAO,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAkB7B"}

package/dist/load-config.js

@@ -0,0 +1,28 @@
+import * as path from "node:path";
+import { defaults, merge } from "@ac-kit/core";
+import { cosmiconfig } from "cosmiconfig";
+import { resolveExtendableConfig, } from "./extendable-config/resolve-extendable-config.js";
+const DEFAULT_LOAD_CONFIG_OPTIONS = {
+    resolveExtendsOptions: {},
+};
+/**
+ * Load a CLI configuration file using cosmiconfig, supporting "extends" field.
+ *
+ * @param configId The configuration ID (name) to search for.
+ * @param configParser A parser to validate/transform the config object.
+ * @param defaultConfig Default configuration values.
+ * @param options Optional settings for loading and resolving the config.
+ * @returns The resolved configuration object without the "extends" field.
+ */
+export async function loadCliConfig(configId, configParser, defaultConfig, options) {
+    const effectiveOptions = defaults(options, DEFAULT_LOAD_CONFIG_OPTIONS);
+    const searchResult = await cosmiconfig(configId).search();
+    if (!searchResult) {
+        throw new Error(`no configuration found`);
+    }
+    return resolveExtendableConfig(merge(defaultConfig, searchResult.config, {
+        recursive: true,
+        cloneSource: true,
+    }), path.dirname(searchResult.filepath), configParser, configId, effectiveOptions.resolveExtendsOptions);
+}
+//# sourceMappingURL=load-config.js.map

package/dist/load-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-config.js","sourceRoot":"","sources":["../src/load-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1C,OAAO,EAIN,uBAAuB,GACvB,MAAM,kDAAkD,CAAC;AAQ1D,MAAM,2BAA2B,GAAgC;IAChE,qBAAqB,EAAE,EAAE;CACzB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,QAAgB,EAChB,YAAoC,EACpC,aAA6B,EAC7B,OAA2B;IAE3B,MAAM,gBAAgB,GAAG,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAC;IAExE,MAAM,YAAY,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC;IAC1D,IAAI,CAAC,YAAY,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,uBAAuB,CAC7B,KAAK,CAAC,aAAa,EAAE,YAAY,CAAC,MAAM,EAAE;QACzC,SAAS,EAAE,IAAI;QACf,WAAW,EAAE,IAAI;KACjB,CAAC,EACF,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,EACnC,YAAY,EACZ,QAAQ,EACR,gBAAgB,CAAC,qBAAqB,CACtC,CAAC;AACH,CAAC"}

package/dist/resolve-config-value.d.ts

@@ -0,0 +1,17 @@
+import { MaybePromiseLike, type MaybeAsyncCallable } from "@ac-kit/core";
+/**
+ * Resolve a configuration value that may be a static value or a function
+ * returning the value.
+ *
+ * If it's a function, it will be called with the provided arguments. If it's a
+ * static value, it will be returned as-is.
+ *
+ * This allows configuration options to be defined either as fixed values or as
+ * functions that compute the value dynamically.
+ *
+ * @param configValue The configuration value or function to resolve.
+ * @param args Arguments to pass if the configValue is a function.
+ * @returns The resolved configuration value, possibly a Promise if async.
+ */
+export declare function resolveConfigValue<A extends unknown[], R>(configValue: MaybeAsyncCallable<A, R> | R, ...args: A): MaybePromiseLike<R>;
+//# sourceMappingURL=resolve-config-value.d.ts.map

package/dist/resolve-config-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-config-value.d.ts","sourceRoot":"","sources":["../src/resolve-config-value.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEzE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EACxD,WAAW,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,EACzC,GAAG,IAAI,EAAE,CAAC,GACR,gBAAgB,CAAC,CAAC,CAAC,CAMrB"}

package/dist/resolve-config-value.js

@@ -0,0 +1,21 @@
+/**
+ * Resolve a configuration value that may be a static value or a function
+ * returning the value.
+ *
+ * If it's a function, it will be called with the provided arguments. If it's a
+ * static value, it will be returned as-is.
+ *
+ * This allows configuration options to be defined either as fixed values or as
+ * functions that compute the value dynamically.
+ *
+ * @param configValue The configuration value or function to resolve.
+ * @param args Arguments to pass if the configValue is a function.
+ * @returns The resolved configuration value, possibly a Promise if async.
+ */
+export function resolveConfigValue(configValue, ...args) {
+    if (typeof configValue === "function") {
+        return configValue(...args);
+    }
+    return configValue;
+}
+//# sourceMappingURL=resolve-config-value.js.map

package/dist/resolve-config-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-config-value.js","sourceRoot":"","sources":["../src/resolve-config-value.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CACjC,WAAyC,EACzC,GAAG,IAAO;IAEV,IAAI,OAAO,WAAW,KAAK,UAAU,EAAE,CAAC;QACvC,OAAQ,WAAwC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,WAAW,CAAC;AACpB,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@ac-kit/app-config",
+  "version": "0.1.0",
+  "description": "CLI configuration loading, built on cosmiconfig.",
+  "keywords": [
+    "cli",
+    "config",
+    "configuration",
+    "cosmiconfig"
+  ],
+  "homepage": "https://anthochamp.github.io/node-essentials/api/app-config/",
+  "bugs": {
+    "url": "https://github.com/anthochamp/node-essentials/issues"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Anthony Champagne <dev@anthonychampagne.fr>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anthochamp/node-essentials.git",
+    "directory": "packages/app-config"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "access": "public"
+  },
+  "scripts": {
+    "compile": "tsc -p ./tsconfig.build.json -outDir dist",
+    "compile:check": "tsc -noEmit -p ./tsconfig.json",
+    "clean": "rimraf dist",
+    "build": "yarn clean && yarn compile",
+    "test": "yarn run -T vitest run",
+    "prepack": "yarn build"
+  },
+  "dependencies": {
+    "@ac-kit/core": "0.1.0",
+    "@ac-kit/format-editorconfig": "^0.1.0",
+    "@ac-kit/node": "0.1.0",
+    "@types/node": "^26.5.1",
+    "cosmiconfig": "^10.0.0",
+    "type-fest": "^5.8.0"
+  },
+  "devDependencies": {
+    "@ac-kit/tsconfig": "0.1.0",
+    "@ac-kit/typedoc-config": "0.1.0",
+    "@typescript/native": "typescript@7.0.2",
+    "rimraf": "6.1.3",
+    "typedoc": "0.28.20",
+    "typescript": "@typescript/typescript6@6.0.2",
+    "vite": "8.3.0",
+    "vitest": "5.0.0",
+    "vitest-mock-extended": "5.1.1"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}