clap-ts 0.2.0 → 0.3.0

package/dist/config.js

@@ -0,0 +1,134 @@
+/**
+ * Configuration file loading, layered under the command line and environment.
+ *
+ * ```ts
+ * import { loadConfig } from 'clap-ts/config';
+ *
+ * const config = loadConfig('mytool');
+ * await runMain(main, { config: config?.values });
+ * ```
+ *
+ * Precedence ends up as command line, then environment, then config file, then
+ * the argument's own default. `ctx.valueSources` reports which one won.
+ *
+ * Only JSON is understood out of the box, which keeps this dependency-free.
+ * Point `parse` at a TOML or YAML reader to accept those.
+ *
+ * The search costs one `existsSync` per candidate per directory, so it is
+ * O(directories x candidates) and independent of how many files those
+ * directories hold. Listing each directory once instead would be one syscall
+ * per level, but `readdirSync` is O(entries): measured against a 2000-entry
+ * directory it took 117us where four `existsSync` calls took 2.4us. Walking up
+ * through a large directory is exactly the case that has to stay cheap.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+/** The home directory never changes within a process. */
+const HOME = homedir();
+const defaultFileCache = new Map();
+function defaultFiles(name) {
+    let files = defaultFileCache.get(name);
+    if (files === undefined) {
+        files = [`.${name}rc`, `.${name}rc.json`, `${name}.config.json`, `.config/${name}.json`];
+        defaultFileCache.set(name, files);
+    }
+    return files;
+}
+function asRecord(value, path) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`config at ${path} must be an object`);
+    }
+    return value;
+}
+function readOne(path, parse) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`cannot read config at ${path}: ${message}`);
+    }
+    try {
+        return { values: asRecord(parse(text, path), path), path };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`cannot parse config at ${path}: ${message}`);
+    }
+}
+/**
+ * Find and read the nearest configuration file, walking up from `cwd`.
+ *
+ * Returns `undefined` when nothing is found, and throws only when a file exists
+ * but cannot be read or parsed: a broken config should be loud, a missing one
+ * should not.
+ */
+export function loadConfig(name, opts) {
+    const parse = opts?.parse ?? ((text) => JSON.parse(text));
+    if (opts?.path !== undefined) {
+        return readOne(resolve(opts.path), parse);
+    }
+    const files = opts?.files ?? defaultFiles(name);
+    const packageKey = opts?.packageJsonKey === undefined ? name : opts.packageJsonKey;
+    const stopAt = resolve(opts?.stopAt ?? HOME);
+    const searchParents = opts?.searchParents !== false;
+    let dir = resolve(opts?.cwd ?? process.cwd());
+    for (;;) {
+        for (const file of files) {
+            // Template concatenation rather than join(): join normalises, which this
+            // does not need, and the walk runs this on every candidate at every level.
+            const candidate = `${dir}/${file}`;
+            if (existsSync(candidate)) {
+                return readOne(candidate, parse);
+            }
+        }
+        let atProjectRoot = false;
+        if (packageKey !== null || opts?.stopAtProjectRoot === true) {
+            const pkgPath = `${dir}/package.json`;
+            if (existsSync(pkgPath)) {
+                atProjectRoot = true;
+                if (packageKey !== null) {
+                    const section = readOne(pkgPath, parse).values[packageKey];
+                    if (section !== undefined) {
+                        return { values: asRecord(section, pkgPath), path: pkgPath };
+                    }
+                }
+            }
+        }
+        if (!searchParents) {
+            return undefined;
+        }
+        if (opts?.stopAtProjectRoot === true && (atProjectRoot || existsSync(`${dir}/.git`))) {
+            return undefined;
+        }
+        const parent = dirname(dir);
+        if (parent === dir || dir === stopAt) {
+            return undefined;
+        }
+        dir = parent;
+    }
+}
+/**
+ * Load a config and hand back the run options to spread into `runMain`.
+ *
+ * ```ts
+ * await runMain(main, { ...configOptions('mytool') });
+ * ```
+ */
+export function configOptions(name, opts) {
+    // A thunk, so runMain only searches the filesystem when some argument is
+    // still on its default.
+    let cached;
+    let loadedOnce = false;
+    return {
+        config: () => {
+            if (!loadedOnce) {
+                cached = loadConfig(name, opts)?.values;
+                loadedOnce = true;
+            }
+            return cached;
+        },
+    };
+}

package/dist/help.d.ts

@@ -6,7 +6,7 @@
  * hideShortHelp/hideLongHelp, visibleAlias, hidePossibleValues,
  * and custom styles.
  */
-import type { CommandDef, CommandMeta, StylesDef } from './types.js';
+import type { CommandDef, CommandMeta, OutputSink, StylesDef } from './types.js';
 /**
  * Render the full help text for a command.
  * Matches clap's help format. Supports helpTemplate override,
@@ -20,12 +20,12 @@ export declare function renderUsage(command: CommandDef, parentNames?: string[],
 /**
  * Print help to stdout.
  */
-export declare function showHelp(command: CommandDef, parentNames?: string[], isShortHelp?: boolean, styleOverrides?: Partial<StylesDef>): void;
+export declare function showHelp(command: CommandDef, parentNames?: string[], isShortHelp?: boolean, styleOverrides?: Partial<StylesDef>, out?: OutputSink): void;
 /**
  * Print version to stdout.
  */
-export declare function showVersion(meta: CommandMeta): void;
+export declare function showVersion(meta: CommandMeta, isShort?: boolean, out?: OutputSink): void;
 /**
  * Print an error message with usage hint.
  */
-export declare function showError(message: string, command: CommandDef, parentNames?: string[], styleOverrides?: Partial<StylesDef>): void;
+export declare function showError(message: string, command: CommandDef, parentNames?: string[], styleOverrides?: Partial<StylesDef>, out?: OutputSink): void;