@metaobjectsdev/sdk 0.23.2 → 0.24.0

package/src/collection.ts

@@ -0,0 +1,183 @@
+// server/typescript/packages/sdk/src/collection.ts
+//
+// Phase-1 metadata-source-resolution — the single authority.
+//
+// `resolveCollection()` composes discovery (`discovery.ts`), config
+// (`config.ts`), source resolution (`sources.ts`) and the scope engine
+// (`scope.ts`) into one function that decides where a project's metadata
+// lives. `metaobjects/` is the DEFAULT value of `sources`, never a
+// requirement — a project that declares nothing still resolves exactly as
+// today (`DEFAULT_SOURCES` in `sources.ts`); a project that declares
+// `sources` can point anywhere. No other call site may assume the directory
+// name — this is where that assumption is allowed to live, exactly once.
+import { join, resolve } from "node:path";
+import { ParseError, codeSource } from "@metaobjectsdev/metadata";
+import { CONFIG_FILE, loadConfig, type Config } from "./config.js";
+import { discoverCollectionRoot, exists, isDir } from "./discovery.js";
+import { compileScope, matchesScope, type Scope } from "./scope.js";
+import { DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR } from "./metadata-files.js";
+import {
+  DEFAULT_SOURCES,
+  orderedPathSpecs,
+  resolveSpecPath,
+  resolveSources,
+  type ResolvedSource,
+  type SourceSpec,
+} from "./sources.js";
+
+export interface Collection {
+  /** Directory whose config declared this collection (or the resolved start
+   *  directory, when nothing was discovered and the default applies). */
+  readonly configDir: string;
+  /** Canonically-ordered absolute metadata file paths — see `resolveSources`.
+   *  Canonical, not sorted: within a directory source the walk order the
+   *  toolchain has always used is preserved, because it survives into
+   *  generated output. */
+  readonly files: readonly string[];
+  /** Same set, carrying the contributing spec for provenance. */
+  readonly sources: readonly ResolvedSource[];
+  /** The distinct roots the declared source specs resolve to, absolute, in the
+   *  same canonical (content) order `files` uses. Derived from the DECLARED
+   *  specs, not from the resolved files, so a source directory that legitimately
+   *  holds no metadata still appears — a consumer listing "where this model
+   *  comes from" (`meta docs --site` groups its pages by source root) must not
+   *  silently lose a declared source because it happens to be empty today. */
+  readonly sourceRoots: readonly string[];
+  /**
+   * Output filter for codegen: does this fully-qualified name survive the
+   * collection's `scope`? Always defined — an unconfigured project compiles to
+   * an empty include/exclude, which admits everything, so callers pass this
+   * through unconditionally rather than branching.
+   *
+   * A PREDICATE rather than the `CompiledScope` it closes over, because nothing
+   * consumes a compiled scope as a compiled scope: every consumer immediately
+   * wrapped it in exactly this lambda, and `migrateScopePatterns` exists
+   * precisely because the compiled form cannot be shown to a human.
+   * `compileScope`/`matchesScope` stay exported for the conformance corpus.
+   */
+  readonly inScope: (fqn: string) => boolean;
+  /** Output filter for migrate/verify --db (`migrate.scope`). Undefined => the
+   *  command governs everything loaded, and that undefined is load-bearing: it
+   *  is what leaves the expected schema untouched (migrate-ts `scope.ts`). */
+  readonly inMigrateScope: ((fqn: string) => boolean) | undefined;
+  /** The patterns `inMigrateScope` was compiled FROM, for diagnostics only —
+   *  `compileScope` produces RegExps, and a regex source is not something to
+   *  show an author who wrote `acme::platform::**`. Carried so the "your scope
+   *  matched nothing" refusal can name the patterns that missed. Always in
+   *  lockstep with `inMigrateScope`: both undefined, or both present. */
+  readonly migrateScopePatterns: readonly string[] | undefined;
+}
+
+/** Narrow the zod-inferred `Config["scope"]` (whose `.optional()` fields are
+ *  typed `T | undefined` even when present) down to `Scope`'s
+ *  exactOptionalPropertyTypes-safe shape — a key is omitted entirely rather
+ *  than assigned `undefined`. */
+function toScope(spec: Config["scope"]): Scope {
+  return {
+    ...(spec?.include !== undefined && { include: spec.include }),
+    ...(spec?.exclude !== undefined && { exclude: spec.exclude }),
+  };
+}
+
+/**
+ * THE single authority on where metadata lives. Every read path routes
+ * through this — `metaobjects/` is the DEFAULT value of `sources`, never an
+ * assumption baked into a call site.
+ *
+ * Resolution order: an explicit `opts.explicitDir` wins outright; otherwise
+ * `discoverCollectionRoot` walks up from `startDir` for the nearest directory
+ * carrying `.metaobjects/config.json` — the ONLY project marker (`discovery.ts`
+ * says why a directory that merely holds metadata is not one) — falling back to
+ * `startDir` itself when none is found. When the resolved directory carries a
+ * config, its declared `sources`/`scope`/`migrate.scope` govern. Only a
+ * genuinely ABSENT `config.json` falls through to `DEFAULT_SOURCES` — the same
+ * directory the pre-source-resolution toolchain always read; a config.json
+ * that EXISTS but fails to load (malformed JSON, schema violation) is the
+ * author's error and propagates rather than silently degrading — a source
+ * that fails to resolve must never look like one that was never declared.
+ * Throws `ERR_COLLECTION_NOT_FOUND` only when BOTH have failed: no
+ * `sources` were declared AND the default source directory does not exist
+ * either.
+ *
+ * A declared source that fails to resolve is a different, louder failure —
+ * `resolveSources` throws `ERR_SOURCE_UNRESOLVED` for that case; only the
+ * DEFAULT is allowed to be silently absent.
+ */
+export async function resolveCollection(
+  startDir: string,
+  opts?: { explicitDir?: string },
+): Promise<Collection> {
+  const explicit = opts?.explicitDir;
+
+  // Whether `configDir` carries a `config.json` — threaded through rather
+  // than re-`stat`'d below. On the non-explicit path, `discoverCollectionRoot`
+  // already proved it either way: it reports `hasConfig` from the same
+  // `.metaobjects/config.json` probe that decided where to stop, and reports
+  // false only after confirming that file is absent at every directory it
+  // examined, `resolve(startDir)` included. A second `stat` of the identical
+  // file would just re-prove what discovery established. The check is only
+  // load-bearing on the `explicitDir` path, where discovery never runs at all.
+  let configDir: string;
+  let hasConfig: boolean;
+  if (explicit !== undefined) {
+    configDir = resolve(explicit);
+    hasConfig = await exists(join(configDir, DEFAULT_METAOBJECTS_DIR, CONFIG_FILE));
+  } else {
+    ({ dir: configDir, hasConfig } = await discoverCollectionRoot(startDir));
+  }
+
+  let specs: readonly SourceSpec[] = DEFAULT_SOURCES;
+  let scopeSpec: Config["scope"];
+  let migrateSpec: string[] | undefined;
+
+  if (hasConfig) {
+    // No try/catch here: a config.json that EXISTS but fails to load
+    // (malformed JSON, a ConfigSchema violation) propagates. Swallowing it
+    // would make a typo'd config behave identically to no config at all —
+    // silently generating from a possibly-stale `metaobjects/` with no
+    // diagnostic, which is a worse failure than the one this design exists
+    // to remove.
+    const cfg = await loadConfig(join(configDir, DEFAULT_METAOBJECTS_DIR));
+    if (cfg.sources.length > 0) specs = cfg.sources;
+    scopeSpec = cfg.scope;
+    migrateSpec = cfg.migrate?.scope;
+  }
+
+  // Only the DEFAULT is allowed to be absent — an explicitly declared source
+  // that does not resolve is `resolveSources`'s ERR_SOURCE_UNRESOLVED, not this.
+  //
+  // This re-`stat`s a directory the non-explicit discovery walk may already
+  // have probed, and that redundancy is intentional: it exists to produce the
+  // friendlier `ERR_COLLECTION_NOT_FOUND` diagnostic below rather than the raw
+  // `ERR_SOURCE_UNRESOLVED` `resolveSources` would throw on a genuinely missing
+  // default directory. Trading that clearer error for one syscall is a bad
+  // trade. It is also load-bearing outright on the `explicitDir` path and
+  // whenever a discovered config declares no `sources`, where nothing has
+  // probed it at all.
+  if (specs === DEFAULT_SOURCES && !(await isDir(join(configDir, DEFAULT_METADATA_DIR)))) {
+    throw new ParseError(
+      `no metadata sources declared in ${configDir} and no default "${DEFAULT_METADATA_DIR}" directory found. ` +
+        `Declare "sources" in ${DEFAULT_METAOBJECTS_DIR}/config.json, or run 'meta init' to scaffold.`,
+      { code: "ERR_COLLECTION_NOT_FOUND", source: codeSource("resolveCollection") },
+    );
+  }
+
+  const sources = await resolveSources(configDir, specs);
+  const scope = compileScope(toScope(scopeSpec));
+  const migrateScope =
+    migrateSpec === undefined ? undefined : compileScope({ include: migrateSpec });
+  return {
+    configDir,
+    files: sources.map((s) => s.file),
+    sources,
+    // Canonical (content) order, from `resolveSources`'s own ordering — so this
+    // list is a pure function of the source SET, exactly like `files`.
+    sourceRoots: [
+      ...new Set(orderedPathSpecs(specs).map((spec) => resolveSpecPath(configDir, spec))),
+    ],
+    inScope: (fqn: string): boolean => matchesScope(fqn, scope),
+    inMigrateScope:
+      migrateScope === undefined ? undefined : (fqn: string): boolean => matchesScope(fqn, migrateScope),
+    migrateScopePatterns: migrateSpec,
+  };
+}

package/src/config.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import type { SourceSpec } from "./sources.js";
 
 const DialectEnum = z.enum(["sqlite", "postgres", "d1"]);
 
@@ -30,14 +31,18 @@ export const AllowTokenEnum = z.enum([
   "adopt-view",
   "nullable-to-not-null",
   "drop-identity-default",
+  "drop-unmanaged",
 ]);
 
+// .strict(), like every other object in this schema: `.partial()` alone leaves
+// zod's default STRIP policy in place, so a misspelled key is silently deleted
+// and the block reads as if the author never wrote it.
 const D1Block = z.object({
   binding: z.string(),
   remote: z.boolean(),
   autoApply: z.boolean(),
   wranglerConfigPath: z.string(),
-}).partial();
+}).partial().strict();
 
 /** #192 — migration output-format adapters; orthogonal to dialect. */
 const MigrateFormatEnum = z.enum(["default", "flyway"]);
@@ -50,8 +55,71 @@ const MigrateBlock = z.object({
   onAmbiguous: OnAmbiguousEnum,
   allow: z.array(AllowTokenEnum),
   d1: D1Block,
-}).partial();
+  /** Restricts a `meta migrate` run to a subset of the loaded metadata, by the
+   *  same package-glob pattern grammar as top-level `scope` (see `scope.ts`).
+   *  Include-only — there's no `migrate.scope.exclude`, since a migration run
+   *  is scoped to what it's touching, not filtered down from "everything". */
+  scope: z.array(z.string().min(1)),
+// .strict() for the same reason as the top level and the source arms below, and
+// with sharper teeth here: `{ migrate: { scopee: [...], dialect: "postgres" } }`
+// used to parse to `{ dialect: "postgres" }`, so a typo'd `scope` key meant
+// "unscoped" — silently governing every table in the database, which is the
+// hazard `migrate.scope` exists to remove.
+}).partial().strict();
 
+/**
+ * Mirrors the hand-written `SourceSpec` union in `./sources.ts` — a
+ * declared source kind, one of `path` (resolves today), `resource`, or
+ * `package` (both reserved, throw `ERR_SOURCE_KIND_UNSUPPORTED` until a
+ * later phase). `.strict()` on every arm: this project is fail-closed on
+ * undeclared keys everywhere else (ADR-0023 makes an unregistered metadata
+ * attribute a hard error for the same reason) — a config schema that
+ * silently strips an unknown key would let `{ path: "model", pathh: "typo"
+ * }` parse clean and resolve one source instead of erroring on the typo.
+ * The pre-phase-1 `{ kind: "path", path: "..." }` shape (the dead 2-arm
+ * discriminated union this replaces) never shipped to an adopter — `meta
+ * init` has only ever scaffolded `"sources": []`, and nothing under `src/`
+ * ever read the old shape — so there is no live config to be lenient for;
+ * it only ever existed in this package's own tests, updated alongside this
+ * schema.
+ */
+const SourceSpecSchema = z.union([
+  z.object({ path: z.string().min(1) }).strict(),
+  z.object({ resource: z.string().min(1) }).strict(),
+  z.object({ package: z.string().min(1) }).strict(),
+]);
+
+// Compile-time parity, BOTH directions: if SourceSpecSchema and the
+// hand-written SourceSpec (./sources.ts) ever drift, one of these two
+// assignments stops compiling. Each direction alone catches only HALF the
+// drift — `z.infer<...>` assignable to `SourceSpec` catches an arm added to
+// the schema but missing from SourceSpec, while `SourceSpec` assignable to
+// `z.infer<...>` catches the opposite: an arm added to the hand-written
+// SourceSpec that the schema never gained. A single one-directional
+// assignment (the prior form of this guard) let a SourceSpec-only addition
+// compile clean — proven by deliberately breaking each direction in
+// isolation; see the quality-pass report for both failing `tsc` outputs. A
+// conditional type (`X extends Y ? true : never`) would silently resolve to
+// `never` instead of erroring — this direct-assignment form fails for real.
+const _sourceSpecParityInferToSpec: SourceSpec = {} as z.infer<typeof SourceSpecSchema>;
+const _sourceSpecParitySpecToInfer: z.infer<typeof SourceSpecSchema> = {} as SourceSpec;
+void _sourceSpecParityInferToSpec;
+void _sourceSpecParitySpecToInfer;
+
+/** Mirrors the hand-written `Scope` interface in `./scope.ts`. An absent or
+ *  empty `include` means "everything" — see `matchesScope`. */
+const ScopeSchema = z
+  .object({
+    include: z.array(z.string().min(1)).optional(),
+    exclude: z.array(z.string().min(1)).optional(),
+  })
+  .strict();
+
+// .strict() at the TOP level too, not just the source-spec arms and the
+// scope block: without it, a misspelled top-level key (e.g. "scopes" for
+// "scope") is silently stripped by zod and the collection resolves as
+// "everything in scope" — the exact silent fail-open .strict() on the
+// nested arms exists to prevent, one level up.
 export const ConfigSchema = z.object({
   schema_version: z.literal(1),
   pending_in_git: z.boolean().default(true),
@@ -61,27 +129,27 @@ export const ConfigSchema = z.object({
       drift_warn: z.number().min(0).max(1).default(0.7),
     })
     .default({}),
-  sources: z
-    .array(
-      z.union([
-        z.object({ kind: z.literal("path"), path: z.string() }),
-        z.object({ kind: z.literal("package"), package: z.string() }),
-      ]),
-    )
-    .default([]),
+  sources: z.array(SourceSpecSchema).default([]),
+  /** Output filter applied across every command — see `./scope.ts`. Absent
+   *  means "everything" (no filtering), matching `Scope`'s own contract. */
+  scope: ScopeSchema.optional(),
   extract: z
     .object({
       metaignore: z.string().optional(),
     })
     .default({}),
   migrate: MigrateBlock.optional(),
-});
+}).strict();
 
 export type Config = z.infer<typeof ConfigSchema>;
 
 export const DEFAULT_CONFIG: Config = ConfigSchema.parse({ schema_version: 1 });
 
-const CONFIG_FILE = "config.json";
+/** `config.json`'s basename — the single owner. `discovery.ts` and
+ *  `collection.ts` import this rather than each keeping their own copy of
+ *  the literal (a duplication that had drifted into three separate
+ *  declarations of the same string). */
+export const CONFIG_FILE = "config.json";
 
 export async function loadConfig(metaRoot: string): Promise<Config> {
   const raw = await readFile(join(metaRoot, CONFIG_FILE), "utf8");

package/src/discovery.ts

@@ -0,0 +1,110 @@
+// server/typescript/packages/sdk/src/discovery.ts
+//
+// Phase-1 metadata-source-resolution — nearest-ancestor collection discovery.
+//
+// Walks up from a starting directory to find the nearest directory that IS a
+// project root. This is what makes a CLI *contextual*: run it inside an app in
+// a monorepo and it finds that app's configuration rather than the repo root's.
+//
+// Three properties are load-bearing.
+//
+// 1. **One marker.** A directory is a project root when it carries
+//    `.metaobjects/config.json`, and on no other evidence. A directory that
+//    merely *holds* metadata is not a project boundary: where metadata lives is
+//    the `sources` key's answer, and `metaobjects/` is only that key's default
+//    value. Stopping on a bare `metaobjects/` directory would put a second
+//    definition of "where metadata lives" back into the walk — the exact
+//    duplication `resolveCollection` exists to be the only instance of — and it
+//    would ignore a project whose config points its `sources` somewhere else
+//    entirely. See design §4.6.1.
+// 2. **Nearest wins** — the walk returns on the FIRST directory carrying the
+//    marker, so a config in a subdirectory beats one in an ancestor.
+// 3. **The walk stops at a repository boundary** (`.git`), so a monorepo
+//    checkout can never silently adopt a *parent checkout's* configuration. The
+//    marker check runs BEFORE the `.git` check within each directory —
+//    reversed, a root-level project (where `.git` also lives) would be
+//    unreachable from any subdirectory, since the boundary would stop the walk
+//    one directory too early.
+import { stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { CONFIG_FILE } from "./config.js";
+import { DEFAULT_METAOBJECTS_DIR } from "./metadata-files.js";
+
+const GIT_DIR = ".git";
+
+/** Exported for reuse — `collection.ts` had its own byte-identical copy
+ *  (`fileExists`); one definition, imported. */
+export async function exists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** `exists`, narrowed to directories — `collection.ts`'s default-source probe
+ *  needs that distinction to raise its friendlier `ERR_COLLECTION_NOT_FOUND`
+ *  (a plain FILE where the default source directory should be is not a
+ *  metadata home). Lives here beside `exists` so there is one filesystem
+ *  predicate pair in the package rather than a copy per caller. */
+export async function isDir(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Where the discovery walk stopped, and what it found there. */
+export interface DiscoveredRoot {
+  /** The project root the walk settled on. Always absolute; falls back to the
+   *  resolved start directory when the walk found no marker at all. */
+  readonly dir: string;
+  /** Whether `dir` carries `.metaobjects/config.json`. False only on the
+   *  no-marker fallback, where the DEFAULT sources apply. */
+  readonly hasConfig: boolean;
+}
+
+/**
+ * Walk up from `startDir` for the nearest project root — a directory holding
+ * `.metaobjects/config.json`, and nothing else (see the file header). The walk
+ * stops after examining a directory that contains `.git`, so a monorepo can
+ * never silently adopt a parent checkout's configuration.
+ *
+ * Never fails: with no config anywhere below the boundary it reports the
+ * resolved `startDir` with `hasConfig: false`, which is what
+ * `resolveCollection` turns into either the default source or
+ * `ERR_COLLECTION_NOT_FOUND`.
+ */
+export async function discoverCollectionRoot(startDir: string): Promise<DiscoveredRoot> {
+  const start = resolve(startDir);
+  let dir = start;
+  for (;;) {
+    if (await exists(join(dir, DEFAULT_METAOBJECTS_DIR, CONFIG_FILE))) {
+      return { dir, hasConfig: true };
+    }
+    // Boundary check AFTER the marker check: a repo-root project (sharing its
+    // directory with `.git`) is still findable from any subdirectory.
+    if (await exists(join(dir, GIT_DIR))) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return { dir: start, hasConfig: false };
+}
+
+/**
+ * The directory whose configuration governs a run started in `startDir` — the
+ * `dir` half of {@link discoverCollectionRoot}.
+ *
+ * Exists as its own export for the callers that must NOT require metadata to
+ * exist: `meta migrate apply-pending` and `--rollback` replay committed SQL and
+ * load no model at all, so they resolve their `.metaobjects/` directory through
+ * this rather than through `resolveCollection`. Sharing the walk is the point —
+ * a second "find the project root" implementation is how the migrations
+ * directory and the metadata directory come to disagree.
+ */
+export async function resolveConfigDir(startDir: string): Promise<string> {
+  return (await discoverCollectionRoot(startDir)).dir;
+}

package/src/index.ts

@@ -76,17 +76,34 @@ export {
 } from "./forge-types.js";
 export type { ForgeType, ForgeAttr } from "./forge-types.js";
 
-// Memory loader — read metaobjects/ into a MetaData tree
-// (workspace-aware: walks extends: deps via pnpm-workspace.yaml or
-//  package.json workspaces field if present)
-export {
-  loadMemory,
-  defaultLoadMemoryProviders,
-  DEFAULT_METADATA_DIR,
-  DEFAULT_METAOBJECTS_DIR,
-} from "./memory.js";
+// Memory loader — read a project's resolved metadata into a MetaData tree.
+// Where those files come from is `resolveCollection`'s decision (below), which
+// `loadMemory` calls when the caller supplies no explicit file set.
+export { loadMemory, defaultLoadMemoryProviders } from "./memory.js";
 export type { LoadMemoryOptions } from "./memory.js";
 
+// Default project layout — the DEFAULT value of `sources` (applied by
+// `resolveCollection` alone) and the fixed directory holding the config that
+// declares them. Exported for `meta init`, which SCAFFOLDS that layout.
+export { DEFAULT_METADATA_DIR, DEFAULT_METAOBJECTS_DIR } from "./metadata-files.js";
+
+// Scope — output filter over fully-qualified node names
+export { compileScope, matchesScope } from "./scope.js";
+export type { Scope, CompiledScope } from "./scope.js";
+
+// Source resolution — a declared source SET to a canonically-sorted file list
+export { resolveSources, resolveSpecPath, orderedPathSpecs, DEFAULT_SOURCES } from "./sources.js";
+export type { SourceSpec, ResolvedSource } from "./sources.js";
+
+// Discovery — nearest-ancestor project root (a `.metaobjects/config.json`,
+// the only marker), bounded by the repo root
+export { discoverCollectionRoot, resolveConfigDir } from "./discovery.js";
+export type { DiscoveredRoot } from "./discovery.js";
+
+// Collection — the single authority on where a project's metadata lives
+export { resolveCollection } from "./collection.js";
+export type { Collection } from "./collection.js";
+
 // Workspace discovery — finds peer metadata packages in a monorepo
 export { discoverWorkspace, resolveExtendsOrder, packageLabel } from "./workspace.js";
 export type { Workspace, WorkspacePackage } from "./workspace.js";