@ontrails/adapter-kit 1.0.0-beta.30 → 1.0.0-beta.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/adapter-kit",
-  "version": "1.0.0-beta.30",
+  "version": "1.0.0-beta.39",
   "description": "Internal adapter authoring kit for Trails metadata, scaffolding, and checks.",
   "files": [
     "src/**/*.ts",
@@ -19,5 +19,11 @@
     "typecheck": "tsc --noEmit",
     "lint": "oxlint ./src",
     "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/core": "^1.0.0-beta.39"
+  },
+  "peerDependencies": {
+    "zod": "^4.3.5"
   }
 }

package/src/catalog.ts

@@ -6,15 +6,11 @@
  * internal tooling package.
  */
 
-import {
-  existsSync,
-  readdirSync,
-  readFileSync,
-  realpathSync,
-  statSync,
-} from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
+import { listWorkspacePackages } from '@ontrails/core';
+
 export const adapterTargetPlacements = ['extracted', 'subpath'] as const;
 
 export type AdapterTargetPlacementValue =
@@ -66,16 +62,16 @@ export interface AdapterTargetCatalog {
   readonly targets: readonly AdapterTargetCatalogEntry[];
 }
 
-interface RootManifest {
-  readonly workspaces?: unknown;
-}
-
 export interface AdapterTargetPackageManifest {
   readonly exports?: unknown;
   readonly name?: unknown;
   readonly trails?: unknown;
 }
 
+type NamedAdapterTargetPackageManifest = AdapterTargetPackageManifest & {
+  readonly name: string;
+};
+
 export interface AdapterTargetParseContext {
   readonly blockedExportSpecifiers: readonly string[];
   readonly exportTargets: Readonly<Record<string, string>>;
@@ -181,14 +177,6 @@ const localDeclarationKind = (
   return typeDeclarationPattern.test(code) ? 'type' : undefined;
 };
 
-const readJson = <T>(path: string): T | undefined => {
-  try {
-    return JSON.parse(readFileSync(path, 'utf8')) as T;
-  } catch {
-    return undefined;
-  }
-};
-
 const maskDeadSourceText = (
   source: string,
   options: { strings: boolean }
@@ -414,44 +402,6 @@ const exportedLocalBindingKind = (
   return importSpecifier ? resolveImportKind(importSpecifier) : undefined;
 };
 
-const workspacePatternsFromManifest = (
-  manifest: RootManifest | undefined
-): readonly string[] => {
-  const { workspaces } = manifest ?? {};
-  if (Array.isArray(workspaces)) {
-    return workspaces.filter(
-      (pattern): pattern is string => typeof pattern === 'string'
-    );
-  }
-
-  const packages = isRecord(workspaces) ? workspaces['packages'] : undefined;
-  return Array.isArray(packages)
-    ? packages.filter(
-        (pattern): pattern is string => typeof pattern === 'string'
-      )
-    : [];
-};
-
-const workspaceDirsForPattern = (
-  rootDir: string,
-  pattern: string
-): readonly string[] => {
-  if (!pattern.endsWith('/*')) {
-    const workspaceDir = join(rootDir, pattern);
-    return existsSync(workspaceDir) ? [workspaceDir] : [];
-  }
-
-  const groupDir = join(rootDir, pattern.slice(0, -2));
-  if (!existsSync(groupDir)) {
-    return [];
-  }
-
-  return readdirSync(groupDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => join(groupDir, entry.name))
-    .toSorted();
-};
-
 const exportConditions = new Set([
   'bun',
   'node',
@@ -1401,40 +1351,27 @@ export const parseAdapterTargetsFromManifest = (
 export const deriveAdapterTargetCatalog = (
   rootDir: string
 ): AdapterTargetCatalog => {
-  const normalizedRoot = normalizeRealPath(rootDir);
-  const rootManifest = readJson<RootManifest>(
-    join(normalizedRoot, 'package.json')
-  );
   const diagnostics: AdapterTargetCatalogDiagnostic[] = [];
   const targets: AdapterTargetCatalogEntry[] = [];
 
-  for (const pattern of workspacePatternsFromManifest(rootManifest)) {
-    for (const workspaceDir of workspaceDirsForPattern(
-      normalizedRoot,
-      pattern
-    )) {
-      const packageJsonPath = join(workspaceDir, 'package.json');
-      const manifest = readJson<AdapterTargetPackageManifest>(packageJsonPath);
-      if (!manifest || typeof manifest.name !== 'string') {
-        continue;
-      }
-
-      const packageRoot = normalizeRealPath(dirname(packageJsonPath));
-      const normalizedExports = normalizeExportTargets(
-        packageRoot,
-        manifest.name,
-        manifest.exports
-      );
-      const parsed = parseAdapterTargetsFromManifest(manifest, {
-        blockedExportSpecifiers: normalizedExports.blocked,
-        exportTargets: normalizedExports.targets,
-        packageJsonPath: normalizeRealPath(packageJsonPath),
-        packageName: manifest.name,
-        packageRoot,
-      });
-      diagnostics.push(...parsed.diagnostics);
-      targets.push(...parsed.targets);
-    }
+  for (const workspacePackage of listWorkspacePackages<NamedAdapterTargetPackageManifest>(
+    rootDir
+  )) {
+    const { manifest, packageJsonPath, packageRoot } = workspacePackage;
+    const normalizedExports = normalizeExportTargets(
+      packageRoot,
+      manifest.name,
+      manifest.exports
+    );
+    const parsed = parseAdapterTargetsFromManifest(manifest, {
+      blockedExportSpecifiers: normalizedExports.blocked,
+      exportTargets: normalizedExports.targets,
+      packageJsonPath,
+      packageName: manifest.name,
+      packageRoot,
+    });
+    diagnostics.push(...parsed.diagnostics);
+    targets.push(...parsed.targets);
   }
 
   const sortedTargets = targets.toSorted((left, right) =>

package/src/check.ts

@@ -14,6 +14,12 @@ import {
 } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 
+import { escapeRegExp, listWorkspacePackages } from '@ontrails/core';
+import type {
+  DiagnosticBase,
+  WorkspacePackage as CoreWorkspacePackage,
+} from '@ontrails/core';
+
 import { deriveAdapterTargetCatalog } from './catalog.js';
 import type {
   AdapterTargetCatalog,
@@ -33,15 +39,14 @@ export type AdapterCheckDiagnosticCode =
   | 'unknown-adapter-target'
   | 'unsupported-placement';
 
-export type AdapterCheckDiagnosticSeverity = 'error' | 'warn';
+export type AdapterCheckDiagnosticSeverity = DiagnosticBase['severity'];
 
-export interface AdapterCheckDiagnostic {
+export interface AdapterCheckDiagnostic extends DiagnosticBase<AdapterCheckDiagnosticCode> {
   readonly code: AdapterCheckDiagnosticCode;
   readonly message: string;
   readonly packageJsonPath: string;
   readonly packageName?: string | undefined;
   readonly placement?: AdapterTargetPlacement | undefined;
-  readonly severity: AdapterCheckDiagnosticSeverity;
   readonly target?: string | undefined;
 }
 
@@ -93,10 +98,6 @@ export interface AdapterCheckReport {
   readonly targets: readonly AdapterTargetCatalogEntry[];
 }
 
-interface RootManifest {
-  readonly workspaces?: unknown;
-}
-
 interface AdapterCheckPackageManifest {
   readonly dependencies?: unknown;
   readonly devDependencies?: unknown;
@@ -107,12 +108,7 @@ interface AdapterCheckPackageManifest {
   readonly trails?: unknown;
 }
 
-interface WorkspacePackage {
-  readonly manifest: AdapterCheckPackageManifest;
-  readonly packageJsonPath: string;
-  readonly packageRoot: string;
-  readonly workspacePath: string;
-}
+type WorkspacePackage = CoreWorkspacePackage<AdapterCheckPackageManifest>;
 
 interface AdapterMetadata {
   readonly target: string;
@@ -135,84 +131,8 @@ const normalizeRealPath = (path: string): string => {
   }
 };
 
-const readJson = <T>(path: string): T | undefined => {
-  try {
-    return JSON.parse(readFileSync(path, 'utf8')) as T;
-  } catch {
-    return undefined;
-  }
-};
-
-const workspacePatternsFromManifest = (
-  manifest: RootManifest | undefined
-): readonly string[] => {
-  const { workspaces } = manifest ?? {};
-  if (Array.isArray(workspaces)) {
-    return workspaces.filter(
-      (pattern): pattern is string => typeof pattern === 'string'
-    );
-  }
-
-  const packages = isRecord(workspaces) ? workspaces['packages'] : undefined;
-  return Array.isArray(packages)
-    ? packages.filter(
-        (pattern): pattern is string => typeof pattern === 'string'
-      )
-    : [];
-};
-
-const workspaceDirsForPattern = (
-  rootDir: string,
-  pattern: string
-): readonly string[] => {
-  if (!pattern.endsWith('/*')) {
-    const workspaceDir = join(rootDir, pattern);
-    return existsSync(workspaceDir) ? [workspaceDir] : [];
-  }
-
-  const groupDir = join(rootDir, pattern.slice(0, -2));
-  if (!existsSync(groupDir)) {
-    return [];
-  }
-
-  return readdirSync(groupDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => join(groupDir, entry.name))
-    .toSorted();
-};
-
-const workspacePackages = (rootDir: string): readonly WorkspacePackage[] => {
-  const normalizedRoot = normalizeRealPath(rootDir);
-  const rootManifest = readJson<RootManifest>(
-    join(normalizedRoot, 'package.json')
-  );
-  const packages: WorkspacePackage[] = [];
-
-  for (const pattern of workspacePatternsFromManifest(rootManifest)) {
-    for (const workspaceDir of workspaceDirsForPattern(
-      normalizedRoot,
-      pattern
-    )) {
-      const packageJsonPath = join(workspaceDir, 'package.json');
-      const manifest = readJson<AdapterCheckPackageManifest>(packageJsonPath);
-      if (!manifest || typeof manifest.name !== 'string') {
-        continue;
-      }
-
-      const packageRoot = normalizeRealPath(dirname(packageJsonPath));
-      packages.push({
-        manifest,
-        packageJsonPath: normalizeRealPath(packageJsonPath),
-        packageRoot,
-        workspacePath: normalizePath(relative(normalizedRoot, packageRoot)),
-      });
-    }
-  }
-
-  return packages.toSorted((left, right) =>
-    left.workspacePath.localeCompare(right.workspacePath)
-  );
-};
+const workspacePackages = (rootDir: string): readonly WorkspacePackage[] =>
+  listWorkspacePackages<AdapterCheckPackageManifest>(rootDir);
 
 const resolveExportTarget = (
   target: unknown,
@@ -433,9 +353,6 @@ const collectSourceFiles = (dir: string): readonly string[] => {
   return files.toSorted();
 };
 
-const escapeRegExp = (value: string): string =>
-  value.replaceAll(/[.*+?^${}()|[\]\\]/gu, '\\$&');
-
 const isIdentifierChar = (char: string | undefined): boolean =>
   char !== undefined && /[$\w]/u.test(char);
 

package/src/index.ts

@@ -1,4 +1,6 @@
 export { checkAdapters } from './check.js';
+export { isOverlay, resolveTrailsOverlays } from './overlay.js';
+export type { Overlay } from './overlay.js';
 export type {
   AdapterCheckDiagnostic,
   AdapterCheckDiagnosticCode,

package/src/overlay.ts

@@ -0,0 +1,158 @@
+/**
+ * The adapter overlay contract.
+ *
+ * Adapters export an overlay object describing one namespaced fact
+ * overlay; the app module re-exports it (conventionally as
+ * `trailsOverlays`), and the compile path validates `derive(topo)`
+ * output against the overlay's schema before embedding the facts as
+ * `overlays.<namespace>` in `trails.lock`. The lock schema and graph type
+ * never change — unknown namespaces are preserved byte-for-byte by older
+ * toolchains (tolerant reader).
+ */
+
+import { ValidationError } from '@ontrails/core';
+import type { OverlayProvenance, Topo } from '@ontrails/core';
+import type { z } from 'zod';
+
+/**
+ * One adapter-owned namespaced fact overlay for `trails.lock`.
+ *
+ * An overlay is authored by an adapter package and opted into by the
+ * app: the app module exports `trailsOverlays` next to its topo export,
+ * and `trails compile` runs each overlay's {@link derive} over the
+ * compiled topo, validates the result against {@link schema}, and embeds it
+ * as `overlays.<namespace>` in the committed lock.
+ *
+ * @example
+ * ```ts
+ * import type { Overlay } from '@ontrails/adapter-kit';
+ * import { z } from 'zod';
+ *
+ * const factsSchema = z.object({ regions: z.array(z.string()) }).strict();
+ *
+ * export const overlay = {
+ *   namespace: 'acme',
+ *   schema: factsSchema,
+ *   derive: (topo) => ({
+ *     regions: topo
+ *       .listResources()
+ *       .map((definition) => definition.id)
+ *       .toSorted(),
+ *   }),
+ * } satisfies Overlay;
+ *
+ * // In the app module, next to the topo export:
+ * // export const trailsOverlays = [overlay];
+ * // `trails compile` then embeds the facts as `overlays.acme`.
+ * ```
+ */
+export interface Overlay {
+  /**
+   * The lock overlay this overlay owns.
+   *
+   * Dotted kebab-case: `/^[a-z][a-z0-9-]*(\.[a-z0-9-]+)*$/`. Each
+   * overlay owns exactly one namespace, and the facts land at
+   * `overlays.<namespace>` in `trails.lock`. Unknown namespaces are
+   * preserved byte-for-byte by older toolchains, so new overlays never
+   * break existing lock readers.
+   */
+  readonly namespace: string;
+  /**
+   * Who authored this overlay. Absent means adapter-derived.
+   *
+   * Surfaces obey app-authored overlays only: the well-known `surfaces`
+   * namespace requires `provenance: 'app-authored'` (authored via
+   * `surfaceOverlay()` in the app module), and the compile path rejects
+   * adapter-derived envelopes that claim it. Adapter overlays contribute
+   * facts, never bindings, and can leave this field absent.
+   */
+  readonly provenance?: OverlayProvenance | undefined;
+  /**
+   * The elevated fact schema.
+   *
+   * The compile path enforces this schema against every {@link derive}
+   * output before embedding the facts, so a drifting derive function fails
+   * `trails compile` instead of committing invalid facts.
+   */
+  readonly schema: z.ZodType;
+  /**
+   * Project the topo into this overlay's facts.
+   *
+   * Must be deterministic — the same topo always yields the same facts
+   * (sort any collections) — and must return JSON-plain data, because the
+   * result is embedded verbatim in the committed lock.
+   */
+  readonly derive: (topo: Topo) => unknown;
+}
+
+const isFunction = (value: unknown): value is (...args: unknown[]) => unknown =>
+  typeof value === 'function';
+
+/**
+ * Structurally recognize an {@link Overlay}.
+ *
+ * Used by the compile-side collector when scanning an app module's
+ * `trailsOverlays` export — adapters never import this at runtime. The
+ * check is hand-rolled (string `namespace`, schema object exposing a
+ * `safeParse` function, function `derive`) so recognizing overlays
+ * needs no zod runtime dependency.
+ *
+ * @example
+ * ```ts
+ * import { isOverlay } from '@ontrails/adapter-kit';
+ *
+ * const recognized = candidates.filter(isOverlay);
+ * ```
+ */
+export const isOverlay = (value: unknown): value is Overlay => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const candidate = value as Partial<Record<keyof Overlay, unknown>>;
+  return (
+    typeof candidate.namespace === 'string' &&
+    typeof candidate.schema === 'object' &&
+    candidate.schema !== null &&
+    isFunction((candidate.schema as { safeParse?: unknown }).safeParse) &&
+    isFunction(candidate.derive)
+  );
+};
+
+/**
+ * Read an app module's `trailsOverlays` export as validated overlays.
+ *
+ * This is the one shared collection channel for app-module overlays: the
+ * compile path's fresh app lease and Warden's fresh topo loading both read
+ * the export through this function, so every fresh derivation carries the
+ * same overlays the committed lock embeds. An absent export returns
+ * `undefined`; a present export that is not an array of {@link Overlay}
+ * values throws a fix-forward `ValidationError` naming `sourceLabel`.
+ *
+ * @example
+ * ```ts
+ * import { resolveTrailsOverlays } from '@ontrails/adapter-kit';
+ *
+ * const mod = await import(appModulePath);
+ * const overlays = resolveTrailsOverlays(
+ *   mod as Record<string, unknown>,
+ *   appModulePath
+ * );
+ * // => readonly Overlay[] | undefined
+ * ```
+ */
+export const resolveTrailsOverlays = (
+  moduleExports: Record<string, unknown>,
+  sourceLabel: string
+): readonly Overlay[] | undefined => {
+  const value = moduleExports['trailsOverlays'];
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(value) || !value.every(isOverlay)) {
+    throw new ValidationError(
+      `trailsOverlays export in "${sourceLabel}" must be an array of overlays ({ namespace, schema, derive }). Fix the app module export and rerun \`trails compile\`.`
+    );
+  }
+
+  return value;
+};