@ontrails/config 1.0.0-beta.24 → 1.0.0-beta.29

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @ontrails/config
 
+## 1.0.0-beta.29
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.29
+
+## 1.0.0-beta.28
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.28
+
+## 1.0.0-beta.27
+
+### Patch Changes
+
+- @ontrails/core@1.0.0-beta.27
+
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- 1307568: Centralize Trails config module path conventions, move local config overrides to root `trails.config.local.*`, scaffold the matching gitignore entries, and load project-local Warden rules from `.trails/rules.ts` or `.trails/rules/`.
+- ef09e46: Add shared Trails project-root discovery helpers and use them in Warden so nested
+  cwd invocations still load root `trails.config.*` and project-local
+  `.trails/rules*` governance.
+- 38cd9d6: Add a shared Trails config file loader that treats `trails.config.ts` as the natural primary while supporting JSON, JSONC, YAML, and TOML peer formats. Release and Warden config loading now consume the same loader and local overrides can be authored as data files.
+- Updated dependencies [1307568]
+- Updated dependencies [371d19e]
+  - @ontrails/core@1.0.0-beta.26
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- Updated dependencies [c36aca9]
+- Updated dependencies [3befcf1]
+- Updated dependencies [a4f9cf6]
+- Updated dependencies [9bcf34e]
+  - @ontrails/core@1.0.0-beta.25
+
 ## 1.0.0-beta.24
 
 ### Patch Changes

package/README.md

@@ -90,6 +90,17 @@ Each layer overrides the previous. Environment variables always win.
 
 `appConfig()` discovers `*.config.toml`, `*.config.json`, `*.config.jsonc`, and `*.config.yaml` by default, plus dotfile equivalents when `dotfile: true`.
 
+## Trails project roots
+
+`@ontrails/config` owns the shared project-root convention helpers used by framework tools. `resolveTrailsProjectRoot()` honors an explicit root first, then walks upward from a start directory looking for committed project markers:
+
+- `trails.config.ts`, `.mts`, `.js`, `.mjs`, `.json`, `.jsonc`,
+  `.yaml`, or `.toml`
+- `trails.lock`
+- source-shaped projects with `src/trails/` or `trails/` when no committed marker exists above them
+
+`trails.config.local.*` is a per-developer override and does not mark a project root by itself. A bare `.trails/` directory also does not mark a root; it is the committed-control home for project-local sections after a project root is known.
+
 ## Extensions
 
 ### `env()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/config",
-  "version": "1.0.0-beta.24",
+  "version": "1.0.0-beta.29",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -22,7 +22,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.24",
+    "@ontrails/core": "^1.0.0-beta.29",
     "zod": "^4.3.5"
   }
 }

package/src/define-config.ts

@@ -3,13 +3,11 @@
  * framework conventions for profile selection and local overrides.
  */
 
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-
 import type { z } from 'zod';
 
 import { appConfig } from './app-config.js';
 import { deriveConfig } from './resolve.js';
+import { loadTrailsLocalConfigValue } from './trails-config-file.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -36,13 +34,8 @@ interface DefineConfigResolveOptions {
 // Local overrides discovery
 // ---------------------------------------------------------------------------
 
-const LOCAL_OVERRIDE_CANDIDATES = [
-  'config.local.ts',
-  'config.local.js',
-] as const;
-
 /**
- * Discover and synchronously import a `.trails/config.local.{ts,js}` file.
+ * Discover and synchronously import a `trails.config.local.*` file.
  *
  * Skipped when `TRAILS_ENV=test` for hermetic test environments.
  */
@@ -54,15 +47,10 @@ const discoverLocalOverrides = async (
     return undefined;
   }
 
-  for (const filename of LOCAL_OVERRIDE_CANDIDATES) {
-    const candidate = join(cwd, '.trails', filename);
-    if (existsSync(candidate)) {
-      const mod: Record<string, unknown> = await import(candidate);
-      return (mod['default'] ?? mod) as Record<string, unknown>;
-    }
-  }
-
-  return undefined;
+  const loaded = await loadTrailsLocalConfigValue(cwd);
+  return loaded.value === undefined
+    ? undefined
+    : (loaded.value as Record<string, unknown>);
 };
 
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -9,6 +9,30 @@ export {
 export { collectConfigMeta } from './collect.js';
 export { collectResourceConfigs, type ResourceConfigEntry } from './compose.js';
 export { defineConfig, type DefineConfigOptions } from './define-config.js';
+export {
+  findTrailsConfigPaths,
+  findTrailsLocalConfigPaths,
+  trailsConfigDataCandidates,
+  trailsConfigFileCandidates,
+  findTrailsConfigModulePath,
+  findTrailsLocalConfigModulePath,
+  findTrailsProjectRoot,
+  resolveTrailsProjectRoot,
+  trailsConfigModuleCandidates,
+  trailsLockFileName,
+  trailsLocalConfigDataCandidates,
+  trailsLocalConfigFileCandidates,
+  trailsLocalConfigModuleCandidates,
+  trailsSourceRootCandidates,
+  type TrailsProjectRootMarker,
+  type TrailsProjectRootResolution,
+} from './trails-conventions.js';
+export {
+  loadTrailsConfigFileValue,
+  loadTrailsConfigValue,
+  loadTrailsLocalConfigValue,
+  type LoadedTrailsConfigValue,
+} from './trails-config-file.js';
 export { deriveConfigFields, type FieldDescription } from './derive-fields.js';
 export {
   checkConfig,

package/src/trails-config-file.ts

@@ -0,0 +1,133 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { NotFoundError, ValidationError } from '@ontrails/core';
+
+import {
+  findTrailsConfigPaths,
+  findTrailsLocalConfigPaths,
+} from './trails-conventions.js';
+
+export interface LoadedTrailsConfigValue {
+  readonly configPath?: string | undefined;
+  readonly value?: unknown;
+}
+
+const MODULE_EXTENSIONS = new Set(['.ts', '.mts', '.js', '.mjs']);
+const DATA_EXTENSIONS = new Set(['.json', '.jsonc', '.yaml', '.toml']);
+
+const extensionFor = (filePath: string): string | undefined => {
+  for (const extension of [...MODULE_EXTENSIONS, ...DATA_EXTENSIONS]) {
+    if (filePath.endsWith(extension)) {
+      return extension;
+    }
+  }
+  return undefined;
+};
+
+const isModuleExtension = (extension: string | undefined): boolean =>
+  extension !== undefined && MODULE_EXTENSIONS.has(extension);
+
+const parseDataConfig = (filePath: string, text: string): unknown => {
+  const extension = extensionFor(filePath);
+  try {
+    switch (extension) {
+      case '.json': {
+        return JSON.parse(text);
+      }
+      case '.jsonc': {
+        return Bun.JSONC.parse(text);
+      }
+      case '.toml': {
+        return Bun.TOML.parse(text);
+      }
+      case '.yaml': {
+        return Bun.YAML.parse(text);
+      }
+      default: {
+        throw new ValidationError(
+          `Unsupported Trails config file: ${filePath}`
+        );
+      }
+    }
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      throw error;
+    }
+    throw new ValidationError(
+      `Failed to parse Trails config file: ${filePath}`,
+      {
+        cause: error instanceof Error ? error : new Error(String(error)),
+        context: { path: filePath },
+      }
+    );
+  }
+};
+
+export const loadTrailsConfigFileValue = async (
+  filePath: string
+): Promise<unknown> => {
+  const extension = extensionFor(filePath);
+  if (isModuleExtension(extension)) {
+    const url = pathToFileURL(filePath);
+    url.searchParams.set('t', Date.now().toString());
+    const mod = (await import(url.href)) as Record<string, unknown>;
+    return mod['default'] ?? mod;
+  }
+
+  const text = await Bun.file(filePath).text();
+  return parseDataConfig(filePath, text);
+};
+
+const findSingleConfigPath = (
+  paths: readonly string[],
+  label: string
+): string | undefined => {
+  if (paths.length <= 1) {
+    return paths[0];
+  }
+  throw new ValidationError(
+    `Multiple ${label} config files found: ${paths.join(', ')}. Keep one config file per project root.`
+  );
+};
+
+export const loadTrailsConfigValue = async ({
+  configPath,
+  rootDir,
+}: {
+  readonly configPath?: string | undefined;
+  readonly rootDir: string;
+}): Promise<LoadedTrailsConfigValue> => {
+  const located =
+    configPath === undefined
+      ? findSingleConfigPath(findTrailsConfigPaths(rootDir), 'Trails')
+      : resolve(rootDir, configPath);
+
+  if (located === undefined) {
+    return {};
+  }
+  if (!existsSync(located)) {
+    throw new NotFoundError(`Trails config file not found: ${located}`, {
+      context: { path: located },
+    });
+  }
+
+  return {
+    configPath: located,
+    value: await loadTrailsConfigFileValue(located),
+  };
+};
+
+export const loadTrailsLocalConfigValue = async (
+  rootDir: string
+): Promise<LoadedTrailsConfigValue> => {
+  const located = findSingleConfigPath(
+    findTrailsLocalConfigPaths(rootDir),
+    'Trails local'
+  );
+
+  return located === undefined
+    ? {}
+    : { configPath: located, value: await loadTrailsConfigFileValue(located) };
+};

package/src/trails-conventions.ts

@@ -0,0 +1,197 @@
+import { statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+export const trailsConfigModuleCandidates = [
+  'trails.config.ts',
+  'trails.config.mts',
+  'trails.config.js',
+  'trails.config.mjs',
+] as const;
+
+export const trailsConfigDataCandidates = [
+  'trails.config.json',
+  'trails.config.jsonc',
+  'trails.config.yaml',
+  'trails.config.toml',
+] as const;
+
+export const trailsConfigFileCandidates = [
+  ...trailsConfigModuleCandidates,
+  ...trailsConfigDataCandidates,
+] as const;
+
+export const trailsLocalConfigModuleCandidates = [
+  'trails.config.local.ts',
+  'trails.config.local.mts',
+  'trails.config.local.js',
+  'trails.config.local.mjs',
+] as const;
+
+export const trailsLocalConfigDataCandidates = [
+  'trails.config.local.json',
+  'trails.config.local.jsonc',
+  'trails.config.local.yaml',
+  'trails.config.local.toml',
+] as const;
+
+export const trailsLocalConfigFileCandidates = [
+  ...trailsLocalConfigModuleCandidates,
+  ...trailsLocalConfigDataCandidates,
+] as const;
+
+export const trailsLockFileName = 'trails.lock' as const;
+
+export const trailsSourceRootCandidates = ['src/trails', 'trails'] as const;
+
+export type TrailsProjectRootMarker =
+  | 'config'
+  | 'explicit'
+  | 'fallback'
+  | 'lock'
+  | 'source';
+
+export interface TrailsProjectRootResolution {
+  readonly marker: TrailsProjectRootMarker;
+  readonly markerPath?: string | undefined;
+  readonly rootDir: string;
+}
+
+export interface FindTrailsProjectRootOptions {
+  readonly startDir?: string | undefined;
+}
+
+export interface ResolveTrailsProjectRootOptions extends FindTrailsProjectRootOptions {
+  readonly explicitRootDir?: string | undefined;
+}
+
+const isFile = (path: string): boolean => {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+};
+
+const isDirectory = (path: string): boolean => {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+const firstExistingCandidate = (
+  rootDir: string,
+  candidates: readonly string[]
+): string | undefined =>
+  candidates.map((entry) => resolve(rootDir, entry)).find(isFile);
+
+const existingCandidates = (
+  rootDir: string,
+  candidates: readonly string[]
+): readonly string[] =>
+  candidates.map((entry) => resolve(rootDir, entry)).filter(isFile);
+
+export const findTrailsConfigPaths = (rootDir: string): readonly string[] =>
+  existingCandidates(rootDir, trailsConfigFileCandidates);
+
+export const findTrailsLocalConfigPaths = (
+  rootDir: string
+): readonly string[] =>
+  existingCandidates(rootDir, trailsLocalConfigFileCandidates);
+
+export const findTrailsConfigModulePath = ({
+  configPath,
+  rootDir,
+}: {
+  readonly configPath?: string | undefined;
+  readonly rootDir: string;
+}): string | undefined => {
+  if (configPath !== undefined) {
+    return resolve(rootDir, configPath);
+  }
+  return firstExistingCandidate(rootDir, trailsConfigFileCandidates);
+};
+
+export const findTrailsLocalConfigModulePath = (
+  rootDir: string
+): string | undefined =>
+  firstExistingCandidate(rootDir, trailsLocalConfigFileCandidates);
+
+const firstExistingSourceRoot = (rootDir: string): string | undefined =>
+  trailsSourceRootCandidates
+    .map((entry) => join(rootDir, entry))
+    .find(isDirectory);
+
+const findProjectRootMarkerIn = (
+  rootDir: string
+): Omit<TrailsProjectRootResolution, 'rootDir'> | undefined => {
+  const configPath = findTrailsConfigModulePath({ rootDir });
+  if (configPath !== undefined) {
+    return { marker: 'config', markerPath: configPath };
+  }
+
+  const lockPath = join(rootDir, trailsLockFileName);
+  if (isFile(lockPath)) {
+    return { marker: 'lock', markerPath: lockPath };
+  }
+
+  return undefined;
+};
+
+const findSourceRootMarkerIn = (
+  rootDir: string
+): Omit<TrailsProjectRootResolution, 'rootDir'> | undefined => {
+  const sourcePath = firstExistingSourceRoot(rootDir);
+  if (sourcePath !== undefined) {
+    return { marker: 'source', markerPath: sourcePath };
+  }
+
+  return undefined;
+};
+
+export const findTrailsProjectRoot = ({
+  startDir = process.cwd(),
+}: FindTrailsProjectRootOptions = {}):
+  | TrailsProjectRootResolution
+  | undefined => {
+  let current = resolve(startDir);
+  let sourceFallback: TrailsProjectRootResolution | undefined;
+
+  while (true) {
+    const marker = findProjectRootMarkerIn(current);
+    if (marker !== undefined) {
+      return { ...marker, rootDir: current };
+    }
+
+    const sourceMarker = findSourceRootMarkerIn(current);
+    if (sourceMarker !== undefined) {
+      sourceFallback = { ...sourceMarker, rootDir: current };
+    }
+
+    const parent = dirname(current);
+    if (parent === current) {
+      return sourceFallback;
+    }
+    current = parent;
+  }
+};
+
+export const resolveTrailsProjectRoot = ({
+  explicitRootDir,
+  startDir = process.cwd(),
+}: ResolveTrailsProjectRootOptions = {}): TrailsProjectRootResolution => {
+  if (explicitRootDir !== undefined) {
+    return {
+      marker: 'explicit',
+      rootDir: resolve(startDir, explicitRootDir),
+    };
+  }
+
+  return (
+    findTrailsProjectRoot({ startDir }) ?? {
+      marker: 'fallback',
+      rootDir: resolve(startDir),
+    }
+  );
+};