@metaobjectsdev/sdk 0.23.2 → 0.24.1

package/dist/sources.js

@@ -0,0 +1,130 @@
+// server/typescript/packages/sdk/src/sources.ts
+//
+// Phase-1 metadata-source-resolution — source spec resolution.
+//
+// Turns a declared source SET (`.metaobjects/config.json`'s `sources`) into a
+// canonically-ordered, de-duplicated list of metadata file paths. The FULL
+// result — including which spec each entry attributes to — is a pure
+// function of the source SET, never of declaration order: permuting `specs`
+// cannot change the output, even when two specs overlap on the same file.
+// `test/order-independence.test.ts` pins that (the design's linchpin), so the
+// canonical spec ordering below is load-bearing.
+//
+// Canonical is NOT the same as "flat-sorted". Within one directory spec the
+// order is `listMetadataFiles`'s (metadata-files.ts) — files at a level, then
+// that level's subdirectories, depth-first — because that is the order production
+// has always handed the loader, and declaration order survives into generated
+// output (the barrel's export list, the shared `enums.ts`, `meta docs` page
+// order, `meta export`'s sibling order). A flat sort of absolute paths
+// silently reorders any project with a subdirectory whose name sorts before a
+// sibling file. Across specs, order is decided by spec CONTENT, which is what
+// keeps the whole result permutation-invariant. `test/source-order.test.ts`
+// pins both halves.
+import { stat } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { ParseError, codeSource } from "@metaobjectsdev/metadata";
+import { DEFAULT_METADATA_DIR, listMetadataFiles } from "./metadata-files.js";
+/** Used when `sources` is absent or empty in `.metaobjects/config.json`. A
+ *  DEFAULT, never a requirement — a project that declares `sources` explicitly
+ *  need not include the default directory at all. Built from
+ *  `DEFAULT_METADATA_DIR` (`metadata-files.ts`'s single definition) rather than
+ *  restating that name here: a second independent encoding of the same
+ *  default would let `resolveCollection`'s "does the default dir exist"
+ *  check (`collection.ts`) desync from what `resolveSources` actually
+ *  resolves the moment the default ever changed — silently reproducing the
+ *  "two code paths disagree about where metadata lives" class of bug this
+ *  whole mechanism exists to eliminate. */
+export const DEFAULT_SOURCES = [{ path: DEFAULT_METADATA_DIR }];
+/** Narrows `spec` to its `path` arm, throwing `ERR_SOURCE_KIND_UNSUPPORTED`
+ *  for `resource`/`package` — phase 1 resolves `path` only. Returns rather than
+ *  asserting so one call both validates and narrows: an `asserts` signature has
+ *  to be re-invoked wherever TypeScript's control-flow analysis cannot carry the
+ *  narrowing, which is a language workaround masquerading as a second check. */
+function toPathSpec(spec) {
+    if ("path" in spec)
+        return spec;
+    const kind = "resource" in spec ? "resource" : "package";
+    throw new ParseError(`source kind "${kind}" is not supported by this toolchain yet; use a "path" source`, { code: "ERR_SOURCE_KIND_UNSUPPORTED", source: codeSource("resolveSources") });
+}
+/**
+ * The declared source SET in CANONICAL order — kind-validated, then sorted by
+ * spec CONTENT rather than by declaration order.
+ *
+ * This is the ONE place declaration order is discarded, and the module's "pure
+ * function of the SET" invariant rests on it: the emitted file order, the spec
+ * attributed to a file two specs both reach, and which of several unresolvable
+ * paths reports its `ERR_SOURCE_UNRESOLVED` first are all decided here.
+ * Validation runs across the WHOLE list before any sorting or filesystem I/O —
+ * interleaved with resolution, which error code came back would depend on
+ * declaration order, contradicting that same invariant.
+ *
+ * Exported because `resolveCollection` derives `sourceRoots` from the declared
+ * specs and must use this identical ordering; a second sort would be a second
+ * definition of "canonical".
+ */
+export function orderedPathSpecs(specs) {
+    return specs.map(toPathSpec).sort((a, b) => {
+        const [ja, jb] = [JSON.stringify(a), JSON.stringify(b)];
+        return ja < jb ? -1 : ja > jb ? 1 : 0;
+    });
+}
+/**
+ * Where a declared `path` source lives on disk: absolute as written, otherwise
+ * relative to the DECLARING config's directory — never to ambient
+ * `process.cwd()`.
+ *
+ * One definition, because this expression *is* the rule for where a declared
+ * source lives, which is the single piece of knowledge this module exists to
+ * own. A caller that needs a source's root directory (rather than its files)
+ * calls this rather than restating it.
+ */
+export function resolveSpecPath(configDir, spec) {
+    return isAbsolute(spec.path) ? spec.path : resolve(configDir, spec.path);
+}
+/**
+ * Resolve a declared source SET to a canonically-ordered list of metadata files.
+ *
+ * The full result — each entry's `.file` AND its `.spec` — is a pure function
+ * of the SET of `specs`: permuting `specs` cannot change the output. One thing
+ * makes that hold: the specs are processed in CONTENT order
+ * (`JSON.stringify(spec)`, ascending) rather than declared order, so both the
+ * emitted file order and the spec attributed to a file overlapping two specs
+ * are decided by content alone. Declared order carries no information anywhere
+ * in this function.
+ *
+ * Within one directory spec the file order is `listMetadataFiles`'s — files at
+ * a level, then that level's subdirectories, depth-first. That is deliberately
+ * NOT a flat sort of absolute paths: see the file header, and
+ * `test/source-order.test.ts`.
+ *
+ * Only `path` specs resolve in phase 1: a directory is walked recursively, a
+ * file is taken as-is. An unresolvable `path` throws `ERR_SOURCE_UNRESOLVED`
+ * rather than silently contributing nothing; `resource`/`package` specs throw
+ * `ERR_SOURCE_KIND_UNSUPPORTED`.
+ *
+ * @param configDir absolute directory of the declaring config (the parent of
+ *   `.metaobjects/`) — relative `path` specs resolve against it, never against
+ *   ambient `process.cwd()`.
+ */
+export async function resolveSources(configDir, specs) {
+    // Kind-validated and content-ordered in one pass — see `orderedPathSpecs`.
+    const ordered = orderedPathSpecs(specs);
+    // Insertion order IS output order — a Map preserves it, so the per-spec walk
+    // order above survives to the caller. First contributor wins a shared file,
+    // which is content-determined because `ordered` is.
+    const byFile = new Map();
+    for (const spec of ordered) {
+        const target = resolveSpecPath(configDir, spec);
+        const stats = await stat(target).catch(() => undefined);
+        if (stats === undefined) {
+            throw new ParseError(`source path "${spec.path}" does not exist (resolved to ${target}, relative to ${configDir})`, { code: "ERR_SOURCE_UNRESOLVED", source: codeSource("resolveSources") });
+        }
+        const found = stats.isDirectory() ? await listMetadataFiles(target) : [target];
+        for (const file of found) {
+            if (!byFile.has(file))
+                byFile.set(file, spec);
+        }
+    }
+    return [...byFile].map(([file, spec]) => ({ file, spec }));
+}
+//# sourceMappingURL=sources.js.map

package/dist/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/sdk",
-  "version": "0.23.2",
+  "version": "0.24.1",
   "description": "Workspace helpers and agent-docs utilities for MetaObjects projects.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,7 +56,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "0.23.2",
+    "@metaobjectsdev/metadata": "0.24.1",
     "zod": "^3.23.0"
   },
   "devDependencies": {

package/src/agent-docs/body.ts

@@ -222,7 +222,7 @@ export default defineConfig({
 
 Filters live on the generator entry: \`routesFile({ filter: e => e.name !== "AuditLog" })\`
 
-\`.metaobjects/config.json\` is unchanged — it still holds static project state (schema_version, pending_in_git, confidence_thresholds). Generator wiring belongs in \`metaobjects.config.ts\` so TypeScript can type-check the imports.
+\`.metaobjects/config.json\` holds static project state (schema_version, pending_in_git, confidence_thresholds) **and \`sources\` — the set of places your metadata comes from** (see "Where metadata comes from" below). Generator wiring belongs in \`metaobjects.config.ts\` so TypeScript can type-check the imports.
 
 ## Generated hooks + grids (TanStack)
 
@@ -503,13 +503,35 @@ metaobjects/
 └── _pending/<pkg>.json       proposed packages awaiting review
 
 .metaobjects/
-├── config.json               static project state
+├── config.json               static project state + \`sources\`
 ├── migrations/               written by meta migrate
 └── .gen-state/               codegen merge base (gitignored)
 
 metaobjects.config.ts         generator wiring (committed)
 \`\`\`
 
+### Where metadata comes from — the \`sources\` set
+
+**\`metaobjects/\` is the DEFAULT VALUE of \`sources\`, not a requirement.** When \`sources\` is absent or empty in \`.metaobjects/config.json\`, it takes that default — the \`metaobjects/\` directory beside the \`.metaobjects/\` folder holding the config. \`meta init\` scaffolds \`"sources": []\`, so a project that does nothing takes the default.
+
+Do NOT assume that directory exists. A project may declare \`sources\` and put its metadata anywhere — a sibling module, a shared model repository, a single file — and need not have a directory of that name at all:
+
+\`\`\`json
+{
+  "schema_version": 1,
+  "sources": [
+    { "path": "../model/src/main/resources/metadata" },
+    { "path": "metaobjects" }
+  ]
+}
+\`\`\`
+
+\`meta gen\`, \`meta migrate\`, \`meta verify\`, \`meta docs\` and \`meta export\` all read exactly that set, so pointing \`sources\` elsewhere moves every command together. A \`path\` is read **in place and never installed** or copied.
+
+\`sources\` is read by **all four CLI surfaces** — the Node \`meta\` CLI, \`dotnet meta\` (C#), \`metaobjects\` (Python) and \`metaobjects:generate\` (Java and Kotlin, via Maven). Each resolves the same files from the same declaration.
+
+**\`sources\` is a set, not an ordered list** — resolution is order-independent, so declaration order never changes what loads. \`config.json\` also rejects unknown top-level keys, so a misspelled key is an error rather than a silently ignored one.
+
 ## Worked example
 
 \`\`\`json

package/src/collection.ts

@@ -0,0 +1,268 @@
+// 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 { dirname, extname, join, resolve } from "node:path";
+import { readdir, readFile } from "node:fs/promises";
+import { ParseError, codeSource, SUBTYPE_ROOT, TYPE_METADATA } 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, isMetadataFile } 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;
+}
+
+/** The canonical-JSON document root key (`metadata.root`) and the sigil-free
+ *  YAML root mapping key (`metadata:`, at column 0 — ADR-0006), built from the
+ *  metamodel constants rather than spelled out. */
+const JSON_ROOT_KEY = `${TYPE_METADATA}.${SUBTYPE_ROOT}`;
+const YAML_ROOT_KEY = new RegExp(`^${TYPE_METADATA}\\s*:`, "m");
+
+/** Bound on the sniff below: one hit is enough to diagnose, and this runs only
+ *  on a path that has already failed. */
+const MAX_SNIFFED_FILES = 20;
+
+/**
+ * Cheap "is this file a metadata DOCUMENT?" sniff — for a diagnostic, never for
+ * loading. It decides whether to change an error MESSAGE; nothing downstream
+ * reads its answer, and a false negative costs only the generic message.
+ *
+ * A file-EXTENSION test cannot answer this: `package.json` and `tsconfig.json`
+ * carry a recognized metadata extension ({@link isMetadataFile}), so every JS
+ * project root that has no metadata yet would be misdiagnosed as a metadata
+ * directory — a confidently wrong hint, which is worse than the generic one it
+ * would replace. The document root is `metadata.root` in canonical JSON and the
+ * sigil-free `metadata:` key in YAML authoring (ADR-0006), so those are what
+ * this looks for.
+ */
+async function sniffsAsMetadataDocument(file: string): Promise<boolean> {
+  const text = await readFile(file, "utf8").catch(() => undefined);
+  if (text === undefined) return false;
+  if (extname(file).toLowerCase() !== ".json") {
+    // YAML: the root mapping key, at column 0. Not a parse — this package has
+    // no YAML parser, and acquiring one to improve an error message would be a
+    // dependency bought with nothing.
+    return YAML_ROOT_KEY.test(text);
+  }
+  try {
+    const doc: unknown = JSON.parse(text);
+    return typeof doc === "object" && doc !== null && JSON_ROOT_KEY in doc;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Does `dir` hold metadata but carry no project marker — i.e. is it the
+ * METADATA directory, handed to a command whose directory argument is the
+ * PROJECT ROOT? (#344)
+ *
+ * That mistake is predictable rather than careless: the sibling `docs`
+ * positionals in the Python and C# ports ARE the metadata directory, and all
+ * three are spelled the same way. The generic diagnostic then advises declaring
+ * `sources`, which from inside the metadata directory is a dead end.
+ *
+ * Only the top level is scanned. A metadata directory has metadata files in it;
+ * recursing would walk `node_modules/` on the very input this must NOT
+ * misdiagnose.
+ */
+async function holdsMetadataButIsNoRoot(dir: string, hasConfig: boolean): Promise<boolean> {
+  // A directory carrying the marker IS a project root, by the only definition
+  // of one there is (`discovery.ts`). Nothing to diagnose.
+  if (hasConfig) return false;
+  const entries = await readdir(dir).catch(() => [] as string[]);
+  for (const entry of entries.filter(isMetadataFile).slice(0, MAX_SNIFFED_FILES)) {
+    if (await sniffsAsMetadataDocument(join(dir, entry))) return true;
+  }
+  return false;
+}
+
+/** 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)))) {
+    // #344 — name the one wrong answer worth naming before falling back to the
+    // generic advice. Told "declare sources" while standing in the metadata
+    // directory, an author declares the metadata FILES, and the config schema
+    // then rejects a bare string (a `sources` entry is `{ "path": … }`) — two
+    // dead ends in a row for a caller whose only mistake was passing the
+    // directory the sibling ports' `docs` positional wants.
+    if (await holdsMetadataButIsNoRoot(configDir, hasConfig)) {
+      const parent = dirname(configDir);
+      const near = await discoverCollectionRoot(parent);
+      const suggested = near.hasConfig ? near.dir : parent;
+      throw new ParseError(
+        `${configDir} looks like a metadata directory, not a project root — it holds metadata ` +
+          `files but carries no ${DEFAULT_METAOBJECTS_DIR}/${CONFIG_FILE}. A directory argument here is ` +
+          `the PROJECT ROOT that CONTAINS your metadata; where the metadata lives is then the root's ` +
+          `"sources" (default: the "${DEFAULT_METADATA_DIR}" directory beneath it). Try ${suggested} instead.`,
+        { code: "ERR_COLLECTION_NOT_FOUND", source: codeSource("resolveCollection") },
+      );
+    }
+    throw new ParseError(
+      `no metadata sources declared in ${configDir} and no default "${DEFAULT_METADATA_DIR}" directory found. ` +
+        `Declare "sources" in ${DEFAULT_METAOBJECTS_DIR}/${CONFIG_FILE} — each entry is an OBJECT, ` +
+        `e.g. "sources": [{ "path": "model" }] — 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");