@theholocron/datapad 5.0.0-alpha.13 → 5.0.0-alpha.134

package/README.md

@@ -43,15 +43,41 @@ export const defineConfig = createDefineConfig<TasksConfig>();
 
 ## API
 
-### `loadConfigFile<T>({ cwd, name, extensions? })`
-
-Loads the first `<name>.config.<ext>` found in `cwd`. Probe order is
-**TS-first** — `.ts` → `.js` → `.mjs` → `.cjs` → `.json` — overridable via
-`extensions`. Returns `{ config, filepath } | null`. `null` means "no such
-file"; a file that exists but cannot be parsed / loaded / has no default
-export throws `ConfigFileError`.
-
-### `loadLayered<T>({ cwd, name, fallback?, extensions? })`
+### `loadConfigFile<T>({ cwd, name, extensions?, walkUp? })`
+
+Loads the first `<name>.config.<ext>` found starting at `cwd`. Probe order
+is **TS-first** — `.ts` → `.js` → `.mjs` → `.cjs` → `.json` — overridable
+via `extensions`. Returns `{ config, filepath } | null`. `null` means "no
+such file anywhere searched"; a file that exists but cannot be parsed /
+loaded / has no default export throws `ConfigFileError`.
+
+`walkUp: true` (off by default) adds the "nearest config" search
+`cosmiconfig`/`postcss`/`stylelint`/ESLint's flat config all do: when `cwd`
+has no match, check its parent, then its parent's parent, and so on —
+stopping at the first directory containing a `.git` entry (that directory
+is still searched before stopping) or the filesystem root. Never wanders
+past a repo boundary into an unrelated enclosing directory. `loadLayered`
+passes its own `walkUp` through to both the dedicated-file and
+fallback-file lookups. Built on `@theholocron/fs-utils`'s generic
+`findUpward`/`hasGitEntry` — not reimplemented here.
+
+### `loadConfigFromContent<T>({ dir, content, name, extension })`
+
+Loads config from content that didn't come from a file already on disk —
+writes it to `<dir>/<name>.config.<extension>` first, then loads it through
+the exact same internals `loadConfigFile` uses for a file it discovered
+itself. `dir` matters: it's what upward `node_modules` resolution sees, so
+content that does `import { defineConfig } from "@theholocron/cli"` only
+resolves if `dir` sits under a tree where that package is a real
+dependency. Callers own creating and cleaning up `dir`. Returns
+`{ config, filepath }`; throws `ConfigFileError` the same way
+`loadConfigFile` does on a parse/load failure.
+
+Built for `@theholocron/sentinel`'s `validateConfig()` — it fetches a
+repo's `holocron.config.*` from GitHub's API, not a local checkout, but
+still needs the fetched content to execute as a real module.
+
+### `loadLayered<T>({ cwd, name, fallback?, extensions?, walkUp? })`
 
 `<name>.config.*` layered over the `[fallback.key]` of
 `<fallback.file>.config.*`. Either, both, or neither may be present; the
@@ -63,7 +89,10 @@ paths actually merged, lowest priority first.
 
 Deep-merge, `vite`-style: plain objects merge recursively, arrays
 concatenate (`base` first), `undefined` in `override` is skipped, every
-other `override` value replaces `base`. Neither input is mutated.
+other `override` value replaces `base`. Neither input is mutated. A
+re-export of `@theholocron/object-utils`'s `deepMerge` under this
+package's established name — the merge logic itself has no awareness of
+configs at all, so it lives there instead of being duplicated here.
 
 ### `createDefineConfig<T>()`
 

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { deepMerge as mergeConfig } from "@theholocron/object-utils";
 //#region src/define.d.ts
 /**
  * Build a typed identity `defineConfig` for a specific config shape.
@@ -31,22 +32,43 @@ declare class ConfigFileError extends Error {
 //#endregion
 //#region src/load.d.ts
 /**
- * Discover and load `<name>.config.*` files. Holocron-agnostic — no
- * schema, no validation, no defaults. Consumers layer those on top.
+ * Discover and load `<name>.config.*` files, or load one from content that
+ * didn't come from a file at all ({@link loadConfigFromContent}).
+ * Holocron-agnostic — no schema, no validation, no defaults. Consumers
+ * layer those on top.
  *
  * Probe order is **TS-first**: `.ts` → `.js` → `.mjs` → `.cjs` → `.json`.
  * TS is loaded through `tsx`'s `tsImport` (a runtime dependency) so a
  * typed `defineConfig` file works with no build step.
+ *
+ * `walkUp` (off by default) adds the "nearest config" search
+ * cosmiconfig/postcss/stylelint/ESLint's flat config all do: when `cwd`
+ * itself has no match, check its parent, then its parent's parent, and so
+ * on — stopping at the first directory containing a `.git` entry (checked
+ * after that directory's own config probe, so the project root itself is
+ * still searched) or the filesystem root. Never wanders past a repo
+ * boundary into an unrelated enclosing directory. Built on
+ * `@theholocron/fs-utils`'s `findUpward`/`hasGitEntry` — the same
+ * upward-walk shape `@theholocron/sentinel`'s own `findPackageRoot` needs,
+ * only with a different predicate.
  */
 /** Default extension probe order, highest priority first. */
 declare const DEFAULT_EXTENSIONS: readonly ["ts", "js", "mjs", "cjs", "json"];
 interface LoadConfigFileOptions {
-  /** Directory to look in. */
+  /** Directory to start looking in. */
   cwd: string;
   /** Base name — `"holocron"` resolves `holocron.config.{ts,js,mjs,cjs,json}`. */
   name: string;
   /** Override the extension probe order. */
   extensions?: readonly string[];
+  /**
+   * Walk upward through ancestor directories when `cwd` itself has no
+   * match, stopping at the first directory containing a `.git` entry (that
+   * directory is still searched before stopping) or the filesystem root.
+   * Off by default — exact-`cwd`-only, unchanged behavior for any existing
+   * caller that doesn't pass this.
+   */
+  walkUp?: boolean;
 }
 interface Loaded<T> {
   config: T;
@@ -54,9 +76,11 @@ interface Loaded<T> {
   filepath: string;
 }
 /**
- * Load the first `<name>.config.<ext>` that exists in `cwd`. Returns
- * `null` when none is present; throws {@link ConfigFileError} when a file
- * exists but cannot be loaded.
+ * Load the first `<name>.config.<ext>` found starting at `cwd` — just
+ * `cwd` itself by default, or walking up through ancestor directories when
+ * `walkUp` is set (see the module doc comment for the stop conditions).
+ * Returns `null` when none is present anywhere searched; throws
+ * {@link ConfigFileError} when a file exists but cannot be loaded.
  */
 declare function loadConfigFile<T>(opts: LoadConfigFileOptions): Promise<Loaded<T> | null>;
 interface LoadLayeredOptions extends LoadConfigFileOptions {
@@ -84,18 +108,33 @@ interface LayeredResult<T> {
  * when neither source resolves.
  */
 declare function loadLayered<T>(opts: LoadLayeredOptions): Promise<LayeredResult<T> | null>;
-//#endregion
-//#region src/merge.d.ts
+interface LoadConfigFromContentOptions {
+  /**
+   * Directory to write `<name>.config.<extension>` into before loading —
+   * this is what upward `node_modules` resolution sees, so a config that
+   * does `import { defineConfig } from "@theholocron/cli"` only resolves
+   * if `dir` sits under a tree where that package is a real dependency.
+   * Callers own creating and cleaning up `dir` — this function only
+   * writes the one file into it.
+   */
+  dir: string;
+  /** Raw file content — not necessarily sourced from a local file at all (a network fetch, a git blob, …). */
+  content: string;
+  /** Base name — `"holocron"` writes `holocron.config.<extension>`. */
+  name: string;
+  /** Which of `DEFAULT_EXTENSIONS` `content` is — determines how it's interpreted (ts/js/mjs/cjs parsed as a module, json as `JSON.parse`). */
+  extension: string;
+}
 /**
- * Deep-merge two config objects, `vite`-style:
- *
- * - plain objects merge recursively
- * - arrays concatenate (`base` first, then `override`)
- * - an `undefined` value in `override` is skipped (keeps `base`)
- * - every other `override` value replaces `base`
- *
- * Neither input is mutated.
+ * Load config from content that didn't come from a file already on disk —
+ * writes it to `<dir>/<name>.config.<extension>` first, then loads it
+ * through the exact same path {@link loadConfigFile} uses for a file it
+ * discovered itself. Exists because sourcing config content from somewhere
+ * other than the local filesystem (a GitHub API fetch, for one — see
+ * `@theholocron/sentinel`) doesn't change what loading it correctly means:
+ * a `.ts` config still needs real module resolution, `defineConfig` import
+ * included, not a re-implemented parser.
  */
-declare function mergeConfig<T>(base: T, override: unknown): T;
+declare function loadConfigFromContent<T>(opts: LoadConfigFromContentOptions): Promise<Loaded<T>>;
 //#endregion
-export { ConfigFileError, DEFAULT_EXTENSIONS, type LayeredResult, type LoadConfigFileOptions, type LoadLayeredOptions, type Loaded, createDefineConfig, loadConfigFile, loadLayered, mergeConfig };
+export { ConfigFileError, DEFAULT_EXTENSIONS, type LayeredResult, type LoadConfigFileOptions, type LoadConfigFromContentOptions, type LoadLayeredOptions, type Loaded, createDefineConfig, loadConfigFile, loadConfigFromContent, loadLayered, mergeConfig };

package/dist/index.mjs

@@ -1,6 +1,9 @@
-import { readFile, stat } from "node:fs/promises";
+import { readFile, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { findUpward, hasGitEntry } from "@theholocron/fs-utils";
+import { deepMerge, deepMerge as mergeConfig } from "@theholocron/object-utils";
 import { pathToFileURL } from "node:url";
+import { errorMessage } from "@theholocron/misc-utils";
 //#region src/define.ts
 /**
 * Build a typed identity `defineConfig` for a specific config shape.
@@ -34,43 +37,97 @@ var ConfigFileError = class extends Error {
 	}
 };
 //#endregion
-//#region src/merge.ts
+//#region src/utils.ts
 /**
-* Deep-merge two config objects, `vite`-style:
-*
-* - plain objects merge recursively
-* - arrays concatenate (`base` first, then `override`)
-* - an `undefined` value in `override` is skipped (keeps `base`)
-* - every other `override` value replaces `base`
-*
-* Neither input is mutated.
+* The actual file-loading mechanics `load.ts`'s exported functions share:
+* JSON parsing, dynamic `import()` (TS via `tsx`'s persistent ESM loader,
+* JS/MJS/CJS natively), and unwrapping the CJS/ESM default-export
+* double-wrap `tsx`'s transform produces. Kept separate from `load.ts`'s
+* own orchestration (which directory, which extension order, upward
+* search) — this file only knows "given one exact filepath and
+* extension, load it," always throwing {@link ConfigFileError} on failure.
+*/
+async function loadFile(filepath, ext) {
+	if (ext === "json") return loadJson(filepath);
+	return extractDefault(filepath, ext === "ts" ? await importTs(filepath) : await importModule(filepath));
+}
+async function loadJson(filepath) {
+	const text = await readFile(filepath, "utf8");
+	try {
+		return JSON.parse(text);
+	} catch (err) {
+		throw new ConfigFileError(`${filepath} is not valid JSON: ${errorMessage(err)}`, filepath);
+	}
+}
+async function importModule(filepath) {
+	try {
+		return await import(pathToFileURL(filepath).href);
+	} catch (err) {
+		throw new ConfigFileError(`could not load ${filepath}: ${errorMessage(err)}`, filepath);
+	}
+}
+let tsRegistered;
+async function registerTsx() {
+	const { register } = await import("tsx/esm/api");
+	register();
+}
+/**
+* Load a `.ts` file. `tsx`'s ESM loader is registered once per process
+* (lazily — only when a `.ts` file is actually loaded). `register()` is
+* used over `tsImport()` because a single run may load several TS files
+* (`loadLayered` reads a dedicated file *and* a parent file) and
+* `tsImport`'s one-off register/unregister cycle is not reentrant.
 */
-function mergeConfig(base, override) {
-	if (!isPlainObject(base) || !isPlainObject(override)) return override === void 0 ? base : override;
-	const out = { ...base };
-	for (const [key, value] of Object.entries(override)) {
-		if (value === void 0) continue;
-		const prev = out[key];
-		if (Array.isArray(prev) && Array.isArray(value)) out[key] = [...prev, ...value];
-		else if (isPlainObject(prev) && isPlainObject(value)) out[key] = mergeConfig(prev, value);
-		else out[key] = value;
+async function importTs(filepath) {
+	tsRegistered ??= registerTsx();
+	await tsRegistered;
+	try {
+		return await import(pathToFileURL(filepath).href);
+	} catch (err) {
+		throw new ConfigFileError(`could not load ${filepath}: ${errorMessage(err)}`, filepath);
 	}
-	return out;
 }
-function isPlainObject(value) {
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-	const proto = Object.getPrototypeOf(value);
-	return proto === Object.prototype || proto === null;
+/**
+* Unwrap `export default`. `tsx` CJS-transforms `export default x` into
+* `exports.default = x`, which dynamic import wraps as
+* `{ default: { __esModule: true, default: x } }` — strip the extra layer
+* when present so ESM and CJS outputs both resolve.
+*/
+function extractDefault(filepath, mod) {
+	const outer = mod.default;
+	const raw = outer?.__esModule === true ? outer.default : outer;
+	if (raw === void 0 || raw === null) throw new ConfigFileError(`${filepath} must have a default export (use \`export default defineConfig({…})\`)`, filepath);
+	return raw;
+}
+async function isFile(path) {
+	try {
+		return (await stat(path)).isFile();
+	} catch {
+		return false;
+	}
 }
 //#endregion
 //#region src/load.ts
 /**
-* Discover and load `<name>.config.*` files. Holocron-agnostic — no
-* schema, no validation, no defaults. Consumers layer those on top.
+* Discover and load `<name>.config.*` files, or load one from content that
+* didn't come from a file at all ({@link loadConfigFromContent}).
+* Holocron-agnostic — no schema, no validation, no defaults. Consumers
+* layer those on top.
 *
 * Probe order is **TS-first**: `.ts` → `.js` → `.mjs` → `.cjs` → `.json`.
 * TS is loaded through `tsx`'s `tsImport` (a runtime dependency) so a
 * typed `defineConfig` file works with no build step.
+*
+* `walkUp` (off by default) adds the "nearest config" search
+* cosmiconfig/postcss/stylelint/ESLint's flat config all do: when `cwd`
+* itself has no match, check its parent, then its parent's parent, and so
+* on — stopping at the first directory containing a `.git` entry (checked
+* after that directory's own config probe, so the project root itself is
+* still searched) or the filesystem root. Never wanders past a repo
+* boundary into an unrelated enclosing directory. Built on
+* `@theholocron/fs-utils`'s `findUpward`/`hasGitEntry` — the same
+* upward-walk shape `@theholocron/sentinel`'s own `findPackageRoot` needs,
+* only with a different predicate.
 */
 /** Default extension probe order, highest priority first. */
 const DEFAULT_EXTENSIONS = [
@@ -81,21 +138,34 @@ const DEFAULT_EXTENSIONS = [
 	"json"
 ];
 /**
-* Load the first `<name>.config.<ext>` that exists in `cwd`. Returns
-* `null` when none is present; throws {@link ConfigFileError} when a file
-* exists but cannot be loaded.
+* Probe `dir` for `<name>.config.<ext>` in extension-priority order,
+* loading and returning the first match. The one piece of per-directory
+* orchestration `loadConfigFile` needs on both its non-walking and
+* walking paths — pulled out so it can be unit-tested directly instead of
+* only through `loadConfigFile`'s full probe/walk behavior.
 */
-async function loadConfigFile(opts) {
-	const extensions = opts.extensions ?? DEFAULT_EXTENSIONS;
+async function probeExtensions(dir, name, extensions) {
 	for (const ext of extensions) {
-		const filepath = join(opts.cwd, `${opts.name}.config.${ext}`);
+		const filepath = join(dir, `${name}.config.${ext}`);
 		if (!await isFile(filepath)) continue;
 		return {
 			config: await loadFile(filepath, ext),
 			filepath
 		};
 	}
-	return null;
+}
+/**
+* Load the first `<name>.config.<ext>` found starting at `cwd` — just
+* `cwd` itself by default, or walking up through ancestor directories when
+* `walkUp` is set (see the module doc comment for the stop conditions).
+* Returns `null` when none is present anywhere searched; throws
+* {@link ConfigFileError} when a file exists but cannot be loaded.
+*/
+async function loadConfigFile(opts) {
+	const extensions = opts.extensions ?? DEFAULT_EXTENSIONS;
+	const checkDir = (dir) => probeExtensions(dir, opts.name, extensions);
+	if (!opts.walkUp) return await checkDir(opts.cwd) ?? null;
+	return await findUpward(opts.cwd, checkDir, hasGitEntry) ?? null;
 }
 /**
 * `<name>.config.*` layered over the `[fallback.key]` of
@@ -111,7 +181,8 @@ async function loadLayered(opts) {
 		const parent = await loadConfigFile({
 			cwd: opts.cwd,
 			name: opts.fallback.file,
-			extensions: opts.extensions
+			extensions: opts.extensions,
+			walkUp: opts.walkUp
 		});
 		if (parent && parent.config[opts.fallback.key] !== void 0) {
 			base = parent.config[opts.fallback.key];
@@ -119,7 +190,7 @@ async function loadLayered(opts) {
 		}
 	}
 	if (!dedicated && base === void 0) return null;
-	const config = mergeConfig(base, dedicated?.config);
+	const config = deepMerge(base, dedicated?.config);
 	const sources = [baseFile, dedicated?.filepath ?? null].filter((s) => s !== null);
 	return {
 		config,
@@ -127,65 +198,23 @@ async function loadLayered(opts) {
 		sources
 	};
 }
-async function loadFile(filepath, ext) {
-	if (ext === "json") return loadJson(filepath);
-	return extractDefault(filepath, ext === "ts" ? await importTs(filepath) : await importModule(filepath));
-}
-async function loadJson(filepath) {
-	const text = await readFile(filepath, "utf8");
-	try {
-		return JSON.parse(text);
-	} catch (err) {
-		throw new ConfigFileError(`${filepath} is not valid JSON: ${message(err)}`, filepath);
-	}
-}
-async function importModule(filepath) {
-	try {
-		return await import(pathToFileURL(filepath).href);
-	} catch (err) {
-		throw new ConfigFileError(`could not load ${filepath}: ${message(err)}`, filepath);
-	}
-}
-let tsRegistered;
-async function registerTsx() {
-	const { register } = await import("tsx/esm/api");
-	register();
-}
-/**
-* Load a `.ts` config. `tsx`'s ESM loader is registered once per process
-* (lazily — only when a `.ts` config is actually loaded). `register()` is
-* used over `tsImport()` because a single run may load several TS configs
-* (`loadLayered` reads a dedicated file *and* a parent file) and
-* `tsImport`'s one-off register/unregister cycle is not reentrant.
-*/
-async function importTs(filepath) {
-	tsRegistered ??= registerTsx();
-	await tsRegistered;
-	try {
-		return await import(pathToFileURL(filepath).href);
-	} catch (err) {
-		throw new ConfigFileError(`could not load ${filepath}: ${message(err)}`, filepath);
-	}
-}
 /**
-* Unwrap `export default`. `tsx` CJS-transforms `export default x` into
-* `exports.default = x`, which dynamic import wraps as
-* `{ default: { __esModule: true, default: x } }` — strip the extra layer
-* when present so ESM and CJS outputs both resolve.
+* Load config from content that didn't come from a file already on disk —
+* writes it to `<dir>/<name>.config.<extension>` first, then loads it
+* through the exact same path {@link loadConfigFile} uses for a file it
+* discovered itself. Exists because sourcing config content from somewhere
+* other than the local filesystem (a GitHub API fetch, for one — see
+* `@theholocron/sentinel`) doesn't change what loading it correctly means:
+* a `.ts` config still needs real module resolution, `defineConfig` import
+* included, not a re-implemented parser.
 */
-function extractDefault(filepath, mod) {
-	const outer = mod.default;
-	const raw = outer?.__esModule === true ? outer.default : outer;
-	if (raw === void 0 || raw === null) throw new ConfigFileError(`${filepath} must have a default export (use \`export default defineConfig({…})\`)`, filepath);
-	return raw;
-}
-async function isFile(path) {
-	try {
-		return (await stat(path)).isFile();
-	} catch {
-		return false;
-	}
+async function loadConfigFromContent(opts) {
+	const filepath = join(opts.dir, `${opts.name}.config.${opts.extension}`);
+	await writeFile(filepath, opts.content, "utf8");
+	return {
+		config: await loadFile(filepath, opts.extension),
+		filepath
+	};
 }
-const message = (err) => err instanceof Error ? err.message : String(err);
 //#endregion
-export { ConfigFileError, DEFAULT_EXTENSIONS, createDefineConfig, loadConfigFile, loadLayered, mergeConfig };
+export { ConfigFileError, DEFAULT_EXTENSIONS, createDefineConfig, loadConfigFile, loadConfigFromContent, loadLayered, mergeConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/datapad",
-  "version": "5.0.0-alpha.13",
+  "version": "5.0.0-alpha.134",
   "description": "Generic config-file loading for Holocron — discover, load (JSON/JS/TS/ESM/CJS), and merge <name>.config.* files with a typed defineConfig.",
   "keywords": [
     "config",
@@ -32,13 +32,16 @@
     "dist"
   ],
   "dependencies": {
+    "@theholocron/fs-utils": "^1.9.2",
+    "@theholocron/misc-utils": "^1.9.2",
+    "@theholocron/object-utils": "^1.9.2",
     "tsx": "4.23.12"
   },
   "devDependencies": {
-    "@theholocron/eslint-config": "^8.0.0",
-    "@theholocron/tsconfig": "^8.0.0",
-    "@theholocron/tsdown-config": "^8.0.0",
-    "@theholocron/vitest-config": "^8.0.0",
+    "@theholocron/eslint-config": "^8.7.1",
+    "@theholocron/tsconfig": "^8.7.1",
+    "@theholocron/tsdown-config": "^8.7.1",
+    "@theholocron/vitest-config": "^8.7.0",
     "@types/node": "^26",
     "@vitest/coverage-v8": "^4.1.11",
     "@vitest/eslint-plugin": "^1.6.27",