@metaobjectsdev/cli 1.0.13 → 1.1.0

package/src/lib/fk-index-advisory.ts

@@ -21,7 +21,7 @@ import {
 import {
   isMetaObject,
   resolveColumnName,
-  type ColumnNamingStrategy,
+  physicalNamingOf,
   type MetaData,
 } from "@metaobjectsdev/metadata";
 import {
@@ -41,7 +41,6 @@ export interface UnindexedFkFinding {
 
 export interface UnindexedFkOptions {
   dialect: Dialect;
-  columnNamingStrategy: ColumnNamingStrategy;
   /** Skip an entity by FQN — imported (dependency) metadata is not the adopter's to index. */
   skip?: (fqn: string) => boolean;
 }
@@ -65,8 +64,9 @@ function pascal(s: string): string {
 export function scanForUnindexedForeignKeys(root: MetaData, opts: UnindexedFkOptions): UnindexedFkFinding[] {
   const { snapshot, provenance } = buildExpectedSchemaWithProvenance(root, {
     dialect: opts.dialect,
-    columnNamingStrategy: opts.columnNamingStrategy,
   });
+  // ADR-0058: the same column rule the expected schema just used, from the loaded root.
+  const columnNamingStrategy = physicalNamingOf(root).columns;
   // ADR-0039: effective children — resolve rather than rely on root being unextended.
   const objectsByFqn = new Map(
     root.children().filter(isMetaObject).map((o) => [o.resolutionKey(), o] as const),
@@ -90,7 +90,7 @@ export function scanForUnindexedForeignKeys(root: MetaData, opts: UnindexedFkOpt
       const ref = entity.referenceIdentities().find((r) => {
         const cols = r.fields.map((f) => {
           const field = entity.fields().find((x) => x.name === f);
-          return field !== undefined ? resolveColumnName(field, opts.columnNamingStrategy) : f;
+          return field !== undefined ? resolveColumnName(field, columnNamingStrategy) : f;
         });
         return cols.length === fk.columns.length && cols.every((c, i) => c === fk.columns[i]);
       });

package/src/lib/format.ts

@@ -1,4 +1,5 @@
 import { encode } from "@toon-format/toon";
+import { log } from "./log.js";
 
 export type OutputFormat = "toon" | "json" | "text";
 
@@ -35,3 +36,14 @@ export function emitStructured(payload: unknown, fmt: OutputFormat): void {
   if (fmt === "json") console.log(JSON.stringify(payload, null, 2));
   else if (fmt === "toon") console.log(toonEncode(payload));
 }
+
+/**
+ * One narration line, on the other side of the split {@link emitStructured} states:
+ * stdout in text format, stderr in a structured run, so a document never has a
+ * sentence in front of it. Every command that prints prose alongside a document
+ * routes it through here.
+ */
+export function narrate(fmt: OutputFormat, line: string): void {
+  if (fmt === "text") log.info(line);
+  else log.warn(line);
+}

package/src/lib/gen-migrate-advice.ts

@@ -26,6 +26,7 @@ import {
   parseWranglerConfig,
   readSnapshot,
   snapshotPath,
+  withoutFlywayHistory,
   type Change,
   type D1Binding,
 } from "@metaobjectsdev/migrate-ts";
@@ -43,10 +44,12 @@ export interface GenMigrateAdviceInput {
   dialect: "sqlite" | "postgres" | "mysql" | undefined;
   /** `.metaobjects/config.json` `migrate.dialect`, when set (may say `d1`). */
   migrateDialect: "sqlite" | "postgres" | "d1" | undefined;
-  columnNamingStrategy: "snake_case" | "literal" | "kebab-case" | undefined;
   projectRoot: string;
   /** The migrations directory `meta migrate` uses (holds the committed snapshot). */
   migrateOutDir: string;
+  /** `.metaobjects/config.json` `migrate.format`. Under `flyway` the snapshot is read without
+   *  Flyway's history table, as `meta migrate` reads it. */
+  migrateFormat: "default" | "flyway";
   /** Paths (any form) of the files this run wrote, merged or removed. */
   changedFiles: readonly string[];
 }
@@ -63,7 +66,6 @@ export async function genMigrateAdvice(input: GenMigrateAdviceInput): Promise<st
   try {
     built = buildExpectedSchemaWithProvenance(input.metadata, {
       dialect: schemaDialect,
-      ...(input.columnNamingStrategy !== undefined ? { columnNamingStrategy: input.columnNamingStrategy } : {}),
     });
   } catch {
     // A model `meta migrate` would refuse (it says why); gen is not the place to report it.
@@ -75,7 +77,8 @@ export async function genMigrateAdvice(input: GenMigrateAdviceInput): Promise<st
   const snapPath = snapshotPath(resolvePath(input.projectRoot, input.migrateOutDir), schemaDialect);
   const snapshot = existsSync(snapPath) ? await readSnapshot(snapPath) : null;
   if (snapshot !== null) {
-    const actual = { ...snapshot, views: [] };
+    const committed = input.migrateFormat === "flyway" ? withoutFlywayHistory(snapshot) : snapshot;
+    const actual = { ...committed, views: [] };
     try {
       const d = await diff({ expected, actual, dialect: schemaDialect });
       if (d.changes.every((c) => VIEW_CHANGE_KINDS.has(c.kind))) return undefined;
@@ -107,7 +110,6 @@ function mysqlAdvice(input: GenMigrateAdviceInput): string | undefined {
   try {
     provenance = buildExpectedSchemaWithProvenance(input.metadata, {
       dialect: "postgres",
-      ...(input.columnNamingStrategy !== undefined ? { columnNamingStrategy: input.columnNamingStrategy } : {}),
     }).provenance;
   } catch {
     return undefined;

package/src/lib/install-set.ts

@@ -38,6 +38,19 @@ import type { PackageManifest } from "./package-manifest.js";
  * never gated — `.` is the one subpath every package exports.
  */
 export function peerRangesOf(packageName: string): Record<string, string> {
+  return manifestRangesOf(packageName, "peerDependencies");
+}
+
+/**
+ * The ranges a package declares for its own dependencies, or `{}` if they cannot be read.
+ * What a copied template module imports from outside the engine is read from the package it
+ * was copied from — never restated here, for the reason `peerRangesOf` gives.
+ */
+export function dependencyRangesOf(packageName: string): Record<string, string> {
+  return manifestRangesOf(packageName, "dependencies");
+}
+
+function manifestRangesOf(packageName: string, field: "peerDependencies" | "dependencies"): Record<string, string> {
   try {
     const req = createRequire(import.meta.url);
     let dir = dirname(req.resolve(packageName));
@@ -50,7 +63,7 @@ export function peerRangesOf(packageName: string): Record<string, string> {
         };
         // Guard against stopping at a nested manifest that is not the package itself.
         if (manifest.name === packageName) {
-          return (manifest.peerDependencies ?? {}) as Record<string, string>;
+          return (manifest[field] ?? {}) as Record<string, string>;
         }
       }
       const up = dirname(dir);
@@ -125,6 +138,9 @@ export function installSetFor(
    *  project, and what that copy imports. Their output no longer imports the runtime package,
    *  so it is not installed on their account; the copy's own imports are, instead. */
   ownedRuntime?: OwnedRuntimeInstall,
+  /** Third-party packages the copied template modules import, with the range the codegen
+   *  package that ships them declares. Build-time, so dev. */
+  templateThirdParty: ReadonlyMap<string, string | undefined> = new Map(),
 ): InstallSet {
   const version = cliVersion();
   const dev = new Map<string, string | undefined>();
@@ -157,6 +173,9 @@ export function installSetFor(
   for (const p of templatePackages) {
     if (!runtime.has(p)) addPackage(dev, p, `^${version}`);
   }
+  for (const [name, range] of templateThirdParty) {
+    if (!runtime.has(name)) addPackage(dev, name, range);
+  }
 
   const devList = specs(dev);
   const runtimeList = specs(runtime);

package/src/lib/load-metaobjects-config.ts

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
+import { physicalNamingGuideUrl } from "@metaobjectsdev/metadata/release-docs";
 import { readFile, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
@@ -7,6 +8,7 @@ import { randomBytes } from "node:crypto";
 import { createJiti } from "jiti";
 import type { MetaDataTypeProvider, MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 import { resolveCollection, type Collection } from "@metaobjectsdev/sdk";
+import { physicalNamingRemovedMessage } from "@metaobjectsdev/metadata";
 
 const CONFIG_FILE = "metaobjects.config.ts";
 
@@ -132,88 +134,53 @@ function resolveCliPkg(specifier: string): string {
  * jiti's alias map on non-Bun runtimes).
  */
 /**
- * 1.0 removed `entityFile` / `queriesFile` / `routesFile` / `barrel` from
- * `@metaobjectsdev/codegen-ts/generators` (ADR-0035 A3; ADR-0034 scaffold-and-own). Without
- * this check the removal surfaces as a bare runtime TypeError from the transpiled config —
- * `(0, _index2.entityFile) is not a function` — which names neither MetaObjects, nor the
- * removal, nor the one-command remedy. A breaking change an adopter WILL hit deserves a
- * diagnostic, and this is the only place that can give one: the subpath still exists (it is
- * the supported home of the generators with no ownable copy), so nothing upstream of here
- * can tell a correct import from a removed one.
+ * Generator factories `@metaobjectsdev/codegen-ts/generators` used to export and no longer
+ * does, each with what an adopter does instead.
  *
- * It reads the config SOURCE because that is the arm that can name the FILE and the exact
- * import. `removedGeneratorRuntimeError` below is the second arm, and an adopter estate is
- * why there are two: the import does not have to be in the config. This project's config
- * imported an OWNED generator — `./codegen/generators/entityFileTyped`, the shape `meta
- * eject` itself produces — and THAT file carried the stale
- * `import { entityFile } from "@metaobjectsdev/codegen-ts/generators"`. The source scan saw
- * a clean config and the adopter got exactly the bare TypeError this check exists to
- * prevent: `(0 , _generators.entityFile) is not a function`, exit 2, no file, no remedy.
+ * Without this, a removal an adopter WILL hit surfaces as whatever the runtime says about a
+ * missing export: `(0 , _generators.mermaidErDiagram) is not a function` from a transpiled
+ * config, or `does not provide an export named 'mermaidErDiagram'` from native ESM. Neither
+ * names MetaObjects, the removal or the remedy. This is the only place that can: the
+ * subpath still exists and serves every other factory, so nothing upstream of here can tell
+ * a correct import from a removed one.
+ *
+ * The diagnostic is recovered from the THROW, in `removedGeneratorRuntimeError`, so it
+ * answers for a live import only, wherever that import is: the config itself or a module
+ * the config imports (an owned generator under `codegen/generators/`, typically).
+ *
+ * `mermaidErDiagram` (removed in 1.1) wrote the ER diagram to a file of its own. It was the
+ * older home of a diagram the `docs` generator (`docsFile()`) draws.
  */
-const REMOVED_GENERATOR_EXPORTS = ["entityFile", "queriesFile", "routesFile", "barrel"] as const;
+const REMOVED_GENERATOR_EXPORTS: Readonly<Record<string, string>> = {
+  mermaidErDiagram:
+    "The `docs` generator (`docsFile()`) draws the ER diagram, for the whole model on its " +
+    "overview page (README.md) and around each entity on that entity's page.\n" +
+    "  Fix: delete the import and the `mermaidErDiagram()` entry; list `docsFile()` instead, " +
+    "with a `docs` target, and run `meta gen`. " +
+    "The file it wrote (`docs/model.md` under your output directory, unless you moved it " +
+    "with `outFile`) is no longer generated; delete that too.",
+};
 const GENERATORS_SUBPATH = "@metaobjectsdev/codegen-ts/generators";
 
-export function removedGeneratorImportError(source: string): string | undefined {
-  const re = new RegExp(
-    `import\\s*(?:type\\s+)?\\{([^}]*)\\}\\s*from\\s*['"]${GENERATORS_SUBPATH.replace(/[/\\]/g, "\\$&")}['"]`,
-    "g",
-  );
-  const hits = new Set<string>();
-  for (const m of source.matchAll(re)) {
-    for (const raw of (m[1] ?? "").split(",")) {
-      const name = raw.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim();
-      if (name && (REMOVED_GENERATOR_EXPORTS as readonly string[]).includes(name)) hits.add(name);
-    }
-  }
-  if (hits.size === 0) return undefined;
-  const names = [...hits].sort();
-  const templateOf = (n: string) => n.replace(/File$/, "");
-  // One command per name: `meta eject` takes at most one generator name.
-  const commands = names.map((n) => `    meta eject ${templateOf(n)}`).join("\n");
-  const example = names[0] ?? "";
-  return (
-    `metaobjects.config.ts imports ${names.join(", ")} from "${GENERATORS_SUBPATH}". ` +
-    `1.0 REMOVED ${names.length === 1 ? "that export" : "those exports"} (ADR-0034 scaffold-and-own): ` +
-    `these generators are yours to own, so the package no longer ships them as an import.\n` +
-    `  Fix — copy ${names.length === 1 ? "it" : "each of them"} into your repo:\n${commands}\n` +
-    `  then import the copies, e.g. ` +
-    `import { ${example} } from "./codegen/generators/${templateOf(example)}";\n` +
-    `  The subpath itself is fine — promptRender, outputParser, routesFileHono and the rest ` +
-    `still live there. Only ${names.length === 1 ? "this one" : `these ${names.length}`} moved.\n` +
-    `  Guide: docs/features/migrations/0.x-to-1.0.md §11`
-  );
-}
-
 /**
- * The same diagnostic, recovered from the THROW instead of the source — for the case the
- * source scan structurally cannot see: a removed export imported by a module the config
- * imports, rather than by the config itself.
- *
- * It cannot name the file (the TypeError carries no reference back to the import that
- * produced it — that limitation is real, it is just not a reason to say nothing), so it
- * names what it does know: the symbol, the removal, and the one-command remedy. Matching is
- * on the SYMBOL, not the message shape, because the shape is the transpiler's: Bun says
- * `(0 , _generators.entityFile) is not a function` and Node ESM says
- * `entityFile is not a function`.
+ * The diagnostic for a throw that names a removed factory; undefined for any other throw.
+ * It cannot name the file (the error carries no reference back to the import that produced
+ * it), so it says where to look instead. Matching is on the SYMBOL and on the fact of a
+ * missing export, not on one message shape: the shape is the runtime's, and an adopter's
+ * runtime is not ours to choose.
  */
 export function removedGeneratorRuntimeError(err: unknown): string | undefined {
   const message = err instanceof Error ? err.message : String(err ?? "");
-  if (!/is not a function/.test(message)) return undefined;
-  const hit = REMOVED_GENERATOR_EXPORTS.find((n) => new RegExp(`\\b${n}\\b`).test(message));
+  if (!/is not a function|does not provide an export named|[Ee]xport named .* not found/.test(message)) {
+    return undefined;
+  }
+  const hit = Object.keys(REMOVED_GENERATOR_EXPORTS).find((n) => new RegExp(`\\b${n}\\b`).test(message));
   if (hit === undefined) return undefined;
-  const template = hit.replace(/File$/, "");
   return (
-    `${hit}() is not a function — 1.0 REMOVED it from "${GENERATORS_SUBPATH}" ` +
-    `(ADR-0034 scaffold-and-own): these generators are yours to own, so the package no ` +
-    `longer ships them as an import. Your metaobjects.config.ts does not import it, so ` +
-    `the import is in a module the config imports — most often an OWNED generator under ` +
-    `codegen/generators/, which is exactly what 'meta eject' writes.\n` +
-    `  Fix — copy it into your repo:\n    meta eject ${template}\n` +
-    `  then change that module's import to: ` +
-    `import { ${hit} } from "./codegen/generators/${template}";\n` +
-    `  The subpath itself is fine — promptRender, outputParser, routesFileHono and the ` +
-    `rest still live there.\n` +
-    `  Guide: docs/features/migrations/0.x-to-1.0.md §11`
+    `${hit} is no longer exported from "${GENERATORS_SUBPATH}": 1.1 removed that generator. ` +
+    `The import is in your metaobjects.config.ts or in a module the config imports, most ` +
+    `often one of your own under codegen/generators/. ` +
+    `${REMOVED_GENERATOR_EXPORTS[hit] ?? ""}`
   );
 }
 
@@ -342,6 +309,14 @@ export async function resolveGenCollection(
   }
 }
 
+/**
+ * A `metaobjects.config.ts` that still sets column naming (ADR-0058). Its own class because
+ * the commands that tolerate a missing or broken config (`meta migrate` falls back to
+ * defaults) must NOT tolerate this one: falling back to the default rule would propose
+ * renaming every column of a database built with the old value.
+ */
+export class RemovedNamingConfigError extends Error {}
+
 export async function loadMetaobjectsConfig(projectRoot: string): Promise<MetaobjectsGenConfig> {
   const fullPath = resolve(projectRoot, CONFIG_FILE);
   if (!existsSync(fullPath)) {
@@ -450,8 +425,6 @@ export async function loadMetaobjectsConfig(projectRoot: string): Promise<Metaob
   // a belt-and-suspenders fallback for runtimes where jiti's transformer IS
   // active, but under Bun the pre-processed source is the operative fix.
   const original = await readFile(fullPath, "utf8");
-  const removed = removedGeneratorImportError(original);
-  if (removed !== undefined) throw new Error(removed);
   const processed = rewriteImportSpecifiers(original, aliasMap);
 
   // When any specifiers were rewritten, write the modified source to a temp
@@ -501,10 +474,6 @@ export async function loadMetaobjectsConfig(projectRoot: string): Promise<Metaob
     try {
       raw = (await jiti.import(loadPath)) as MetaobjectsGenConfig | { default: MetaobjectsGenConfig };
     } catch (err) {
-      // The second arm of the ADR-0034 diagnostic: a removed export imported by a module the
-      // config imports rather than by the config itself. Rethrown as the migration message,
-      // because what reaches the adopter otherwise is `(0 , _generators.entityFile) is not a
-      // function` — the exact unactionable failure the source scan above exists to prevent.
       const runtime = removedGeneratorRuntimeError(err);
       if (runtime !== undefined) throw new Error(runtime);
       throw err;
@@ -531,6 +500,16 @@ export async function loadMetaobjectsConfig(projectRoot: string): Promise<Metaob
           `verbatim — the tokens are unchanged.`,
       );
     }
+    // ADR-0058 — column naming moved to `naming` in .metaobjects/config.json, the one
+    // setting every port reads. Refused, never dropped: the old value may be the one that
+    // matches this project's database, and dropping it would rename every column.
+    const removedNaming = (cfg as unknown as Record<string, unknown>).columnNamingStrategy;
+    if (removedNaming !== undefined) {
+      throw new RemovedNamingConfigError(
+        `metaobjects.config.ts at ${fullPath}: ` +
+          physicalNamingRemovedMessage("columnNamingStrategy in metaobjects.config.ts", String(removedNaming), physicalNamingGuideUrl()),
+      );
+    }
     return cfg;
   } finally {
     // Restoring is safe: Babel's installer self-neuters after the first call, so

package/src/lib/manifest-ignored-check.ts

@@ -30,15 +30,18 @@ export const HASH_MANIFEST_REL = join(".metaobjects", ".gen-state", ".hashes.jso
  * Silent when: it is tracked correctly, the project is not a git repository, git is
  * unavailable, or no generated output has ever been produced (nothing to protect yet).
  * Never throws, never blocks.
+ *
+ * Returns the line it printed, so a command with a structured result can carry it
+ * there too; undefined when it said nothing.
  */
-export function warnIfManifestIgnored(cwd: string): void {
+export function warnIfManifestIgnored(cwd: string): string | undefined {
   // Nothing generated yet ⇒ nothing at risk ⇒ nothing worth saying.
-  if (!existsSync(join(cwd, HASH_MANIFEST_REL))) return;
+  if (!existsSync(join(cwd, HASH_MANIFEST_REL))) return undefined;
 
   // honourGlobalExcludes: TRUE here, and that is the opposite call to the docs gate.
   // The question this warning asks is "will this file reach another machine?", and a
   // per-user ignore file answers it just as truly as a committed .gitignore does.
-  if (isGitIgnored(cwd, HASH_MANIFEST_REL, { honourGlobalExcludes: true }) !== true) return;
+  if (isGitIgnored(cwd, HASH_MANIFEST_REL, { honourGlobalExcludes: true }) !== true) return undefined;
 
   // WHERE the rule actually lives, asked of git rather than assumed. This used to name
   // `.metaobjects/.gitignore` and the literal pattern `.gen-state/`, which is only one of
@@ -56,12 +59,13 @@ export function warnIfManifestIgnored(cwd: string): void {
       : `Find the rule with 'git check-ignore -v ${HASH_MANIFEST_REL}' and replace it with ` +
         `a '/*' form plus a '!' negation for the manifest`;
 
-  log.warn(
+  const msg =
     `${HASH_MANIFEST_REL} is git-ignored, so it never reaches another machine — ` +
-      `on a fresh clone or CI runner 'meta gen' cannot tell your hand edits from its ` +
-      `own stale output, and will refuse to overwrite rather than guess. ${where} ` +
-      `(the glob matters — git will not descend into an excluded directory, so a negation ` +
-      `INSIDE an excluded directory can never apply), then commit the manifest. ` +
-      `If you deliberately do not commit generated output, ignore this.`,
-  );
+    `on a fresh clone or CI runner 'meta gen' cannot tell your hand edits from its ` +
+    `own stale output, and will refuse to overwrite rather than guess. ${where} ` +
+    `(the glob matters — git will not descend into an excluded directory, so a negation ` +
+    `INSIDE an excluded directory can never apply), then commit the manifest. ` +
+    `If you deliberately do not commit generated output, ignore this.`;
+  log.warn(msg);
+  return msg;
 }

package/src/lib/output.ts

@@ -203,6 +203,13 @@ export interface MigrateResultShape {
    * caller sees the risk before applying.
    */
   warnings?: string[];
+  /**
+   * Explanations of planned changes that are not what they look like — today, views the
+   * migration drops and recreates only because it alters a table they read (D3).
+   */
+  notes?: string[];
+  /** A dry run's SQL. Text format prints it as a preview; JSON/toon carry it here. */
+  sql?: { up: string; down: string };
 }
 
 export function formatMigrateResult(result: MigrateResultShape, _opts: FormatOptions): string {
@@ -219,6 +226,12 @@ export function formatMigrateResult(result: MigrateResultShape, _opts: FormatOpt
     lines.push(`  Changes: ${summary}`, "");
   }
 
+  const notes = result.notes ?? [];
+  if (notes.length > 0) {
+    for (const n of notes) lines.push(`  Note: ${n}`);
+    lines.push("");
+  }
+
   if (result.blocked.length > 0) {
     const anyRename = result.blocked.some((b) => b.renameFlag !== undefined);
     lines.push(anyRename ? "  Blocked (re-run with the flag shown):" : "  Blocked (re-run with --allow):");
@@ -292,7 +305,7 @@ export function genResultToData(result: GenResultShape): {
   const help = result.files.length !== 0
     ? ["typecheck the generated code with `npx tsc`", ...(result.migrateAdvice !== undefined ? [result.migrateAdvice] : [])]
     : noGenerators
-      ? ["add generators to the `generators: []` array in metaobjects.config.ts — `meta eject --list` names every generator you can own, and `meta init` scaffolds the usual set"]
+      ? ["add generators to the `generators: []` array in metaobjects.config.ts — `meta gen --list` names each one with the import that runs it as shipped, and `meta eject <name>` copies one into your repo to change what it emits"]
       : ["author entities in this project's metadata sources then re-run `meta gen`"];
   // An absent section is STATED, never omitted: a reader must be able to tell
   // "the scan found nothing" from "the scan never ran".
@@ -329,6 +342,8 @@ export function migrateResultToData(result: MigrateResultShape): {
   summary: string;
   help: string[];
   warnings?: string[];
+  notes?: string[];
+  sql?: { up: string; down: string };
 } {
   const changeEntries = Object.entries(result.changeCounts).filter(([, v]) => v > 0);
   const changes = changeEntries.map(([kind, count]) => ({ kind, count }));
@@ -395,6 +410,8 @@ export function migrateResultToData(result: MigrateResultShape): {
     changes, written: result.writtenPaths, summary, help,
     // Only when present, so a run with no hazard keeps its existing shape.
     ...(warnings.length > 0 ? { warnings } : {}),
+    ...((result.notes ?? []).length > 0 ? { notes: result.notes } : {}),
+    ...(result.sql !== undefined ? { sql: result.sql } : {}),
   };
 }
 

package/src/lib/payload-field-tree.ts

@@ -7,54 +7,37 @@
 
 import {
   type MetaData,
-  TYPE_FIELD,
   FIELD_SUBTYPE_OBJECT,
   FIELD_ATTR_OBJECT_REF,
-  resolveObjectRef,
+  isMetaField,
+  refTarget,
 } from "@metaobjectsdev/metadata";
 import type { PayloadField } from "@metaobjectsdev/render";
 
-function findObject(root: MetaData, name: string, referrerPkg: string): MetaData | undefined {
-  // ADR-0039: effective children — resolve rather than rely on root being unextended.
-  // ADR-0042: package-local — an FQN @objectRef binds the exact package; a bare ref
-  // binds the referrer's package FIRST (else root-level), never a same-named object.value
-  // in another package. The SAME resolver render-helper.ts's findObject uses (must not drift).
-  return resolveObjectRef(root, name, referrerPkg).node;
-}
-
 /**
  * Walk an `object.value` view-object into a render `PayloadField[]`. Object-ref
- * fields recurse into their referenced view-object; a `seen` set guards against
- * a (pathological) reference cycle. `referrerPkg` (ADR-0042) is the package of
- * the node that declares `voName` (the template for the root call; the parent VO
- * for a nested recursion), so a bare ref resolves package-locally.
+ * fields recurse into the view-object the loader bound for their `@objectRef`
+ * (ADR-0059 R7); a `seen` set guards against a (pathological) reference cycle.
+ * Returns `[]` when `vo` is undefined (the ref did not resolve).
  */
 export function derivePayloadFieldTree(
-  root: MetaData,
-  voName: string,
-  referrerPkg = "",
-  seen: ReadonlySet<string> = new Set(),
+  vo: MetaData | undefined,
+  seen: ReadonlySet<MetaData> = new Set(),
 ): PayloadField[] {
-  if (seen.has(voName)) return [];
-  const vo = findObject(root, voName, referrerPkg);
-  if (!vo) return [];
-  // A nested @objectRef resolves in the FIELD's own declaring package (fallback
-  // below), which differs from this VO's when the field is inherited via extends
-  // from an abstract VO in another package (the bare ref was authored there).
-  const voPkg = vo.package ?? vo.fileDefaultPackage ?? "";
-  const nextSeen = new Set(seen).add(voName);
+  if (vo === undefined || seen.has(vo)) return [];
+  const nextSeen = new Set(seen).add(vo);
   const fields: PayloadField[] = [];
-  for (const f of vo.children().filter((c) => c.type === TYPE_FIELD)) {
-    if (f.subType === FIELD_SUBTYPE_OBJECT) {
+  for (const f of vo.children().filter(isMetaField)) {
+    // ADR-0039: effective array-ness — `isArray` may be inherited via extends. Carried only
+    // when true, so verify can tell a list of objects from a single object and a list of
+    // scalars from a scalar.
+    const arrayness = f.resolvedIsArray() ? { isArray: true } : {};
+    if (f.subType === FIELD_SUBTYPE_OBJECT && typeof f.attr(FIELD_ATTR_OBJECT_REF) === "string") {
       // ADR-0039: effective attr — @objectRef may be inherited via extends.
-      const ref = f.attr(FIELD_ATTR_OBJECT_REF);
-      if (typeof ref === "string") {
-        const fieldPkg = f.parent?.package ?? f.parent?.fileDefaultPackage ?? voPkg;
-        fields.push({ name: f.name, fields: derivePayloadFieldTree(root, ref, fieldPkg, nextSeen) });
-        continue;
-      }
+      fields.push({ name: f.name, fields: derivePayloadFieldTree(refTarget(f, FIELD_ATTR_OBJECT_REF), nextSeen), ...arrayness });
+      continue;
     }
-    fields.push({ name: f.name });
+    fields.push({ name: f.name, ...arrayness });
   }
   return fields;
 }

package/src/lib/requirement-check.ts

@@ -36,6 +36,7 @@ import {
   // One shared resolver (FR-038): codegen's requirement-test fan-out needs the same
   // ADR-0042 package-local binding, so these moved to @metaobjectsdev/metadata rather
   // than being reimplemented there.
+  effectiveRequirementPackage,
   resolveClaimTarget,
   resolveMember,
   didYouMeanHint,
@@ -233,7 +234,7 @@ export function resolveRequirementRef(
 ): MetaRequirement | undefined {
   const keyed = new Map<string, MetaRequirement>();
   for (const { node, path } of addressed) {
-    const pkg = node.package ?? node.fileDefaultPackage ?? "";
+    const pkg = effectiveRequirementPackage(node);
     if (pkg !== "") keyed.set(`${pkg}::${path}`, node);
     // Bare path is registered too, so a single-package ledger can reference
     // without repeating its own package on every line.
@@ -279,6 +280,11 @@ export interface RequirementScan {
    *  printed a ratio the gate had not enforced would be a measurement nobody could
    *  reconcile with the diagnostics beneath it. */
   readonly measureCoverage: boolean;
+  /** ADR-0057 — the strict switch. When true, the functional EXISTENCE finding
+   *  (`WARN_REQUIREMENT_NOTHING_IMPLEMENTS`) is reported at severity `error`; the code,
+   *  path and message do not change, and no other diagnostic is touched. Carried on
+   *  the scan, like `measureCoverage`, so a caller decides it once per run. */
+  readonly requireImplementers: boolean;
 }
 
 /**
@@ -306,7 +312,7 @@ export interface RequirementScan {
 function projectAuthoredRequirements(addressed: readonly AddressedRequirement[]): boolean {
   const libPkgs = libraryPackages();
   return addressed.some((r) => {
-    const pkg = r.node.package ?? r.node.fileDefaultPackage ?? "";
+    const pkg = effectiveRequirementPackage(r.node);
     return !libPkgs.has(pkg);
   });
 }
@@ -321,6 +327,8 @@ export function scanRequirements(
      *  by its own ledger" is exactly what is being asserted — so the derivation would
      *  switch the check off precisely where it is the point. */
     measureCoverage?: boolean;
+    /** Raise WARN_REQUIREMENT_NOTHING_IMPLEMENTS to severity "error". Default false. */
+    requireImplementers?: boolean;
   },
 ): RequirementScan {
   const addressed = collectAddressedRequirements(root);
@@ -328,6 +336,7 @@ export function scanRequirements(
     addressed,
     claimedObjects: claimedObjectKeys(root, addressed.map((r) => r.node)),
     measureCoverage: opts?.measureCoverage ?? projectAuthoredRequirements(addressed),
+    requireImplementers: opts?.requireImplementers ?? false,
     // `exactOptionalPropertyTypes` — an omitted key, never an explicit `undefined`.
     ...(opts?.coverable !== undefined ? { coverable: opts.coverable } : {}),
   };
@@ -353,7 +362,7 @@ function claimedObjectKeys(root: MetaData, reqs: MetaRequirement[]): Set<string>
     // referrerPkg is the requirement's own effective package, so a bare ref
     // binds package-locally under the ADR-0042 contract — the loader's own
     // resolver, never a parallel name scan (#228).
-    const referrerPkg = req.package ?? req.fileDefaultPackage ?? "";
+    const referrerPkg = effectiveRequirementPackage(req);
     for (const ref of req.implementedBy()) {
       const { owner, path } = splitMemberRef(ref);
       const node = resolveClaimTarget(root, owner, referrerPkg);
@@ -471,7 +480,7 @@ export function checkRequirements(root: MetaData, scan: RequirementScan = scanRe
       // referrerPkg is the requirement's own effective package, so a bare ref
       // binds package-locally under the ADR-0042 contract — the loader's own
       // resolver, never a parallel name scan (#228).
-      const referrerPkg = req.package ?? req.fileDefaultPackage ?? "";
+      const referrerPkg = effectiveRequirementPackage(req);
       const node = resolveClaimTarget(root, owner, referrerPkg);
       const isObjectRef = path.length === 0;
 
@@ -536,7 +545,7 @@ export function checkRequirements(root: MetaData, scan: RequirementScan = scanRe
     // requirement's own effective package, exactly as @implementedBy does.
     const superseded = req.supersededBy();
     if (superseded !== undefined) {
-      const referrerPkg = req.package ?? req.fileDefaultPackage ?? "";
+      const referrerPkg = effectiveRequirementPackage(req);
       if (resolveRequirementRef(addressed, superseded, referrerPkg) === undefined) {
         out.push({
           severity: "error", code: ERR_REQUIREMENT_DANGLING_REF, path: reqPath,
@@ -593,9 +602,15 @@ export function checkRequirements(root: MetaData, scan: RequirementScan = scanRe
     // tree. So the question is not "does this node claim anything" but "does
     // anything in this subtree claim anything". A live L1 whose entire subtree
     // is empty is a capability declared and built by nobody.
+    //
+    // The strict switch (ADR-0057, `meta verify --require-implementers`) raises the
+    // SEVERITY for a project whose ledger has caught up with its links. The code
+    // keeps its `WARN_` name on purpose: it identifies the finding, and one finding
+    // under two codes would split every suppression and corpus case that keys on it.
     if (!architectural && live && !subtreeClaimsAnything(req)) {
       out.push({
-        severity: "warn", code: WARN_REQUIREMENT_NOTHING_IMPLEMENTS, path: reqPath,
+        severity: scan.requireImplementers ? "error" : "warn",
+        code: WARN_REQUIREMENT_NOTHING_IMPLEMENTS, path: reqPath,
         message: `is '${String(status)}' but neither it nor anything nested under it names an ` +
           `implementing node. A functional requirement's check is existence — a subtree that claims ` +
           `nothing is a capability nobody built.`,