@theholocron/datapad 5.0.0-alpha.113 → 5.0.0-alpha.114

package/README.md

@@ -43,13 +43,22 @@ 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`.
+### `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.
 
 ### `loadConfigFromContent<T>({ dir, content, name, extension })`
 
@@ -67,7 +76,7 @@ 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? })`
+### `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

package/dist/index.d.mts

@@ -39,16 +39,32 @@ declare class ConfigFileError extends Error {
  * 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.
  */
 /** 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;
@@ -56,9 +72,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 {

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { readFile, stat, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 //#region src/define.ts
 /**
@@ -73,6 +73,14 @@ function isPlainObject(value) {
 * 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.
 */
 /** Default extension probe order, highest priority first. */
 const DEFAULT_EXTENSIONS = [
@@ -83,21 +91,30 @@ 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.
+* 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;
-	for (const ext of extensions) {
-		const filepath = join(opts.cwd, `${opts.name}.config.${ext}`);
-		if (!await isFile(filepath)) continue;
-		return {
-			config: await loadFile(filepath, ext),
-			filepath
-		};
+	let dir = opts.cwd;
+	for (;;) {
+		for (const ext of extensions) {
+			const filepath = join(dir, `${opts.name}.config.${ext}`);
+			if (!await isFile(filepath)) continue;
+			return {
+				config: await loadFile(filepath, ext),
+				filepath
+			};
+		}
+		if (!opts.walkUp) return null;
+		if (await hasGitEntry(dir)) return null;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
 	}
-	return null;
 }
 /**
 * `<name>.config.*` layered over the `[fallback.key]` of
@@ -113,7 +130,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];
@@ -206,6 +224,15 @@ async function isFile(path) {
 		return false;
 	}
 }
+/** `.git` is a directory in a normal checkout, a file in a worktree/submodule — existence is all that matters. */
+async function hasGitEntry(dir) {
+	try {
+		await stat(join(dir, ".git"));
+		return true;
+	} catch {
+		return false;
+	}
+}
 const message = (err) => err instanceof Error ? err.message : String(err);
 //#endregion
 export { ConfigFileError, DEFAULT_EXTENSIONS, createDefineConfig, loadConfigFile, loadConfigFromContent, loadLayered, mergeConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/datapad",
-  "version": "5.0.0-alpha.113",
+  "version": "5.0.0-alpha.114",
   "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",