@metaobjectsdev/cli 1.0.13 → 1.1.0

package/src/index.ts

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import { log } from "./lib/log.js";
-import { cliVersion } from "./lib/version.js";
+import { cliVersion, isVersionFlag } from "./lib/version.js";
 import { resolveFormat, isValidFormat, VALID_FORMATS, type OutputFormat } from "./lib/format.js";
 import { resolveCollection } from "@metaobjectsdev/sdk";
 import { GENERATOR_HELP } from "./commands/generator-help.js";
@@ -42,12 +42,11 @@ COMMANDS:
   types [query]         Search the metadata vocabulary (types, subtypes, @attrs) by name or description
   export                Flatten loaded metadata to one canonical JSON artifact
   fmt [<file>...]       Rewrite metadata files into canonical form; --check lists drift, exits non-zero
-  docs [<project-root>] --out <dir>  Generate neutral metadata documentation (entity + template pages; --site for HTML site)
-  verify                Drift gate — subverbs: --templates / --db / --codegen / --docs / --deps (bare = --templates)
+  verify                Drift gate — subverbs: --templates / --db / --codegen / --deps (bare = --templates)
   upgrade               Rewrite retired metadata vocabulary (previews; --apply writes)
   prompt-snapshot       Snapshot rendered template.* output; --check gates drift
   migrate               Diff metadata vs live DB; emit migration SQL files
-  --version, -v         Print version
+  --version, -v, -V     Print version
   --help, -h            Print this help
 
 GLOBAL OPTIONS:
@@ -81,8 +80,12 @@ GEN FLAGS:
   --limit <n|all>       How many advisory lines TEXT output prints before it truncates
                         (default 20). Never applies to --format toon/json, which
                         carry every finding.
+  --generators <names>  Narrow the run to these DECLARED generators, by stable name, comma-
+                        separated (e.g. docs,api-docs to write only the documentation). A
+                        name metaobjects.config.ts does not declare is refused: it never adds one.
   <entity> [<entity>]   Positional filter on entity names
-  (outDir, dialect, dbImport, extStyle are read from metaobjects.config.ts)
+  (outDir, dialect, dbImport, extStyle are read from metaobjects.config.ts. Every generator,
+  documentation included, is an entry in its \`generators\`; nothing else is generated.)
 
 EXPORT FLAGS:
   --out <file>          Write output to a file (default: stdout)
@@ -102,26 +105,10 @@ FMT FLAGS:
                         find-or-reuse behavior would otherwise silently fold a same-file
                         base + overlay into one node, dropping the overlay marker.
 
-DOCS FLAGS:
-  [<project-root>]      PROJECT ROOT to resolve metadata from — the directory that CONTAINS
-                        your metadata, NOT the metadata directory. Passing it SCOPES the run
-                        (default: cwd)
-  --out <dir>, -o       Output directory for THIS run (default: ./docs/generated). It does
-                        NOT survive the run — set 'docs: { outDir }' in metaobjects.config.ts
-                        for a directory that persists, which is what 'meta verify --docs'
-                        measures. The default is a sub-directory on purpose: these pages are
-                        regenerated and overwritten, and 'docs/' itself is usually yours.
-  --templates <dir>     Project root to resolve adopter templates/ overrides (default: <project-root>)
-  --prompts <dir>       Extra dir holding prompt .mustache sources for --site (e.g. data/templates/)
-
 VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drift):
   --templates           Template/prompt {{field}}↔payload drift (the bare-verify default)
   --codegen             Codegen drift — regenerate to a temp dir and diff the committed
-                        output (config outDir/targets). Needs metaobjects.config.ts; exit 2 if absent.
-  --docs                Docs drift — run 'meta docs' into a temp dir and diff the committed
-                        docs tree (docs.outDir). Reports a page that changed or that a fresh
-                        run would emit; never reports an extra file, because docs.outDir
-                        holds hand-written documentation MetaObjects did not write.
+                        output (config outDir/targets), documentation included.
                         Needs metaobjects.config.ts; exit 2 if absent.
   --deps                Dependency drift — re-resolve each declared dependency and compare
                         its installed artifact's hash against .metaobjects/deps.lock.json
@@ -135,18 +122,31 @@ VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drif
   --allow <csv>         Accepted for parity with 'migrate'; does NOT affect the
                         verify drift gate (the gate fails on ANY detected change)
   --skip-schema         Skip the schema-drift gate even when --db is present
+  --migration-format default|flyway
+                        Migration file layout (default: default), as for 'meta migrate'.
+                        Under 'flyway' the schema-drift gate leaves flyway_schema_history
+                        out of the comparison, because Flyway owns it. Also settable
+                        once as migrate.format in .metaobjects/config.json.
   --d1 <binding>        D1 binding name from wrangler.toml (only with --dialect d1)
   --remote              Target remote D1 instead of local (only with --dialect d1) —
                         the ONLY way to verify the actual deployed D1 database
   --no-antipatterns     Suppress the advisory "you hand-rolled what MetaObjects can
                         model" pass (aggregate/currency/enum hints; warnings only)
   --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
+  --require-implementers
+                        Fail (exit 1) when a live functional requirement has nothing
+                        implementing it. That finding is a warning without this flag;
+                        with it, the same WARN_REQUIREMENT_NOTHING_IMPLEMENTS code is
+                        reported as an error. Also: META_REQUIRE_IMPLEMENTERS=1.
   --no-overlay-lint     Suppress the advisory overlay-redeclaration AUTHORING lint
                         (never a gate — this lint can't fail the build)
   --no-name-lint        Suppress the advisory node-name AUTHORING lint (whitespace
                         in a name; never a gate — this lint can't fail the build)
   --no-deprecation-lint Suppress the advisory deprecated-reference AUTHORING lint
                         (never a gate — this lint can't fail the build)
+  --no-field-lint       Suppress the advisory field AUTHORING lint (a reference
+                        identity over a missing field; a duplicate field name —
+                        never a gate; this lint can't fail the build)
   --limit <n|all>       How many advisory lines TEXT output prints per section before
                         it truncates (default 20). Never applies to --format
                         toon/json, which carry every finding and every diagnostic.
@@ -175,9 +175,9 @@ MIGRATE FLAGS:
   --remote              Target remote D1 instead of local (only with --dialect d1)
   --apply               Run 'wrangler d1 migrations apply' after writing files
   --yes                 Skip the --remote --apply confirmation pause
-  --dry-run             Print SQL to stdout, don't write
+  --dry-run             Print the SQL, don't write (json/toon: in the document's sql field)
 
-See https://metaobjects.com for docs.
+See https://metaobjects.dev for docs.
 `;
 
 /** Focused per-subcommand usage slices shown by `<cmd> --help`. */
@@ -206,6 +206,9 @@ FLAGS:
                         overwrites them with fresh output and re-baselines (discards edits).
   --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
   --limit <n|all>       Advisory lines TEXT output prints before truncating (default 20)
+  --generators <names>  Narrow the run to these DECLARED generators, by stable name, comma-
+                        separated (e.g. docs,api-docs to write only the documentation). A
+                        name metaobjects.config.ts does not declare is refused: it never adds one.
   --format <toon|json|text>   Output format (global flag; default toon off-TTY)
   <entity> [<entity>]   Positional filter on entity names
   --help, -h            Print this help
@@ -229,8 +232,9 @@ USAGE:
   meta eject <name>...   Copy each generator into codegen/generators/<name>.ts
   meta eject --list      List every ejectable generator name, grouped by package
 
-Codegen is opt-in — \`meta init\` wires nothing — so this is the door every generator
-you run comes through. Take several at once: the install set is CONSOLIDATED, so
+Eject a generator to CHANGE what it emits. To run one as shipped, import its factory
+from its package instead — \`meta gen --list\` prints the import line — and copy
+nothing. Take several at once: the install set is CONSOLIDATED, so
 \`meta eject form hooks grid\` prints one install line, not three. An unknown name
 refuses the whole call and copies nothing.
 
@@ -243,9 +247,9 @@ FLAGS:
   --help, -h             Print this help
 
 \`meta init\` copies NO generators — codegen is opt-in, and codegen/generators/
-starts empty on purpose. Everything you run comes through here (ADR-0034
-scaffold-and-own): the file is YOURS to edit, and \`meta gen\` runs your copy, not
-the package's. It prints the import line and the entry to add in
+starts empty on purpose. An ejected file is YOURS to edit (ADR-0034
+scaffold-and-own), and \`meta gen\` runs your copy, not the package's. Eject prints
+the import line to swap in for the package one and the entry to add in
 metaobjects.config.ts, and never overwrites a file you already own without --force.
 
 Find names with \`meta gen --list\` — add --probe to see how many files each would
@@ -299,12 +303,8 @@ FLAGS:
                         (a notice, exit code unchanged), so an edit is never invisible.
   --forbid-hand-edits   With --codegen: fail (exit 1) on ANY hand edit inside generated
                         code, for teams that want generated files untouchable.
-  --docs                Docs drift — run 'meta docs' to a temp dir and diff docs.outDir
-                        Needs metaobjects.config.ts; exit 2 if absent. A page the
-                        project GIT-IGNORES is exempt (docs.outDir is a directory, not
-                        a namespace MetaObjects owns); the count of exempt pages is
-                        reported either way, and a run where every page is ignored is
-                        refused rather than reported clean.
+  --docs                Removed in 1.1.0: says so and exits 2. --codegen checks documentation
+                        with everything else \`generators\` declares.
   --deps                Dependency drift — re-resolve each declared dependency exactly as
                         'meta deps check' does and compare its installed artifact's hash
                         against .metaobjects/deps.lock.json. Exits 1 if any dependency has
@@ -329,6 +329,11 @@ FLAGS:
   --dialect sqlite|postgres|d1   Optional override (auto-detected from --db URL scheme)
   --allow <csv>         Accepted for parity with 'migrate'; does NOT affect the drift gate
   --skip-schema         Skip the schema-drift gate even when --db is present
+  --migration-format default|flyway
+                        Migration file layout (default: default), as for 'meta migrate'.
+                        Under 'flyway' the schema-drift gate leaves flyway_schema_history
+                        out of the comparison, because Flyway owns it. Also settable
+                        once as migrate.format in .metaobjects/config.json.
   --d1 <binding>        D1 binding name from wrangler.toml (only with --dialect d1)
   --remote              Target remote D1 instead of local (only with --dialect d1) —
                         the ONLY way to verify the actual deployed D1 database
@@ -338,12 +343,20 @@ FLAGS:
                         migrating a model onto a registered provider.
   --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
   --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
+  --require-implementers
+                        Fail (exit 1) when a live functional requirement has nothing
+                        implementing it. That finding is a warning without this flag;
+                        with it, the same WARN_REQUIREMENT_NOTHING_IMPLEMENTS code is
+                        reported as an error. Also: META_REQUIRE_IMPLEMENTERS=1.
   --no-overlay-lint     Suppress the advisory overlay-redeclaration AUTHORING lint —
                         never a gate; this lint can't fail the build
   --no-name-lint        Suppress the advisory node-name AUTHORING lint (whitespace in
                         a name) — never a gate; this lint can't fail the build
   --no-deprecation-lint Suppress the advisory deprecated-reference AUTHORING lint —
                         never a gate; this lint can't fail the build
+  --no-field-lint       Suppress the advisory field AUTHORING lint (a reference
+                        identity over a missing field; a duplicate field name) —
+                        never a gate; this lint can't fail the build
   --limit <n|all>       Advisory lines TEXT output prints PER SECTION before truncating
                         (default 20; per-section so the authoring lint can never push
                         the gate's own warnings off the end)
@@ -367,6 +380,9 @@ lint in its own section: names that are not addressable, prose slots holding one
 sentence twice, content written where no surface reads it. Warnings only — it can
 never fail the build. Opt out with --no-requirement-lint or META_NO_REQUIREMENT_LINT=1.
 The requirements GATE itself (dangling refs, link floor, levels) always runs.
+One of its findings is a warning you can raise: a live functional requirement that
+nothing implements fails the build under --require-implementers or
+META_REQUIRE_IMPLEMENTERS=1. The diagnostic keeps its code; only its severity moves.
 
 verify also prints an ADVISORY overlay authoring lint, in its own section: a
 top-level declaration redeclared in two or more files where more than one
@@ -389,6 +405,12 @@ the deprecated node also carries @replacedBy, the finding names the replacement.
 A node referencing itself (a recursive FK, a same-entity passthrough) is not a
 finding. Warnings only — it can never fail the build. Opt out with
 --no-deprecation-lint or META_NO_DEPRECATION_LINT=1.
+
+verify also prints an ADVISORY field authoring lint, in its own section. It reports
+an identity.reference whose @fields names a field the object does not have
+(inherited and overlaid fields count as present), and a field name declared more
+than once in one object's children list. Both load with no error. Warnings only —
+it can never fail the build. Opt out with --no-field-lint or META_NO_FIELD_LINT=1.
 `,
   export: `meta export — flatten loaded metadata to one canonical JSON artifact
 
@@ -431,42 +453,6 @@ skipped — not only when no base exists in the same file. A formatter never
 changes structure: even when a same-file base IS present, merging it with
 the overlay (what the ordinary loader would do) would drop the overlay
 marker from the output, so fmt refuses that too and leaves the file as-is.
-`,
-  docs: `meta docs — generate neutral metadata documentation (entity + template pages)
-
-USAGE:
-  meta docs [<project-root>] [flags]
-
-FLAGS:
-  [<project-root>]      PROJECT ROOT to resolve metadata from — the directory that CONTAINS
-                        your metadata, NOT the metadata directory itself. (The Python and C#
-                        'docs' positionals mean the metadata dir; this one does not.) Passing
-                        it SCOPES the run to that directory's own sources; no ancestor
-                        .metaobjects/config.json is consulted. Omitted (default), the project
-                        is discovered by walking up.
-  --out <dir>, -o       Output directory for THIS run (default: ./docs/generated). It does
-                        NOT survive the run — set 'docs: { outDir }' in metaobjects.config.ts
-                        for a directory that persists, which is what 'meta verify --docs'
-                        measures. The default is a sub-directory on purpose: these pages are
-                        regenerated and overwritten, and 'docs/' itself is usually yours.
-  --model               Emit the markdown model surface (entity + template pages)
-  --api                 Emit the markdown api surface (generated SDK reference)
-  --requirements        Emit the declared requirement ledger (requirements.md + .toon).
-                        Emits nothing when the project declares no requirement.* node.
-  --agent               Emit the agent surface — agent/schema.md (the physical schema),
-                        agent/ui.md (the generated forms and grids) and
-                        agent/requirements.md (the ledger plus a claimed-node index).
-                        Needs metaobjects.config.ts (the dialect and physical names come
-                        from it); each page is skipped when its tier has nothing to describe
-                        — agent/ui.md needs a UI generator (a form, hook or grid) in the
-                        suite, not merely objects that could have one.
-  --metamodel           Document the built-in metamodel vocabulary (no metadata needed)
-  --site                Generate the browsable HTML documentation site (<out>/site/)
-  --scaffold-site       Copy the site's templates + assets into codegen/docs-site/ to own (theme) them
-  --templates <dir>     Project root to resolve adopter templates/ overrides (default: <project-root>)
-  --prompts <dir>       Extra dir holding prompt .mustache sources (for --site) when they
-                        live outside the metadata sources or templates/ (e.g. data/templates/)
-  --help, -h            Print this help
 `,
   init: `meta init — scaffold a MetaObjects project in the current repo
 
@@ -604,7 +590,7 @@ export async function run(argv: string[]): Promise<number> {
   }
 
   // Intercept per-subcommand --help / -h before dispatching (mirrors migrate's own pattern).
-  if (cmd !== undefined && cmd !== "--help" && cmd !== "-h" && cmd !== "--version" && cmd !== "-v") {
+  if (cmd !== undefined && cmd !== "--help" && cmd !== "-h" && !isVersionFlag(cmd)) {
     if (rest.includes("--help") || rest.includes("-h")) {
       const helpText = COMMAND_HELP[cmd];
       if (helpText !== undefined) {
@@ -651,6 +637,7 @@ export async function run(argv: string[]): Promise<number> {
       return 0;
     case "--version":
     case "-v":
+    case "-V":
       log.info(VERSION);
       return 0;
     case "init": {

package/src/lib/agent-context-staleness.ts

@@ -6,25 +6,40 @@ import { join } from "node:path";
 // star one, so the root barrel now hands out the dependency manifest under this
 // name. `init.ts` already imports these from the subpath; this was the last site
 // reading them from the root.
-import { AGENT_CONTEXT_MANIFEST_PATH, agentContextStaleness, type Manifest } from "@metaobjectsdev/sdk/agent-context";
+import { AGENT_CONTEXT_MANIFEST_PATH, agentContextStaleness, hashAgentContextRoot, resolveAgentContextRoot, type Manifest } from "@metaobjectsdev/sdk/agent-context";
+import { docsRefForVersion } from "@metaobjectsdev/metadata";
 import { cliVersion } from "./version.js";
 import { log } from "./log.js";
 
+/** The installed content's hash, or nothing when the content tree cannot be found (version compare then). */
+export function currentContentHash(): { currentContentHash?: string } {
+  try {
+    return { currentContentHash: hashAgentContextRoot(resolveAgentContextRoot(), docsRefForVersion(cliVersion())) };
+  } catch {
+    return {};
+  }
+}
+
 /**
  * Advisory: if a scaffolded MetaObjects agent context predates this CLI version,
  * print a one-line nudge to re-scaffold. Never throws, never blocks — an absent or
  * corrupt manifest is silently ignored (this is a reminder, not a gate).
+ *
+ * Returns the line it printed, so a command with a structured result can carry it
+ * there too; undefined when it said nothing.
  */
-export function warnIfAgentContextStale(cwd: string): void {
+export function warnIfAgentContextStale(cwd: string): string | undefined {
   const p = join(cwd, AGENT_CONTEXT_MANIFEST_PATH);
   let manifest: Manifest | undefined;
   if (existsSync(p)) {
     try {
       manifest = JSON.parse(readFileSync(p, "utf8")) as Manifest;
     } catch {
-      return; // unreadable/corrupt — say nothing
+      return undefined; // unreadable/corrupt — say nothing
     }
   }
-  const msg = agentContextStaleness({ manifest, currentVersion: cliVersion() });
-  if (msg !== null) log.warn(msg);
+  const msg = agentContextStaleness({ manifest, currentVersion: cliVersion(), ...currentContentHash() });
+  if (msg === null) return undefined;
+  log.warn(msg);
+  return msg;
 }

package/src/lib/agent-schema.ts

@@ -0,0 +1,74 @@
+// The physical schema `agent/schema.md` describes (the `agent-docs` generator), built by the
+// package that owns it, `migrate-ts`, with its own resolvers handed across. codegen-ts
+// deliberately computes none of it (see agent-schema-input.ts there), so `meta gen` and
+// `meta verify --codegen` build it here and hand it to the run as `RunGenOpts.agentSchema`;
+// the runner calls it only when a declared generator asks.
+
+import {
+  buildProjectionViews,
+  dbEmittingObjects,
+  DEFAULT_DIALECT,
+  missingDialectMessage,
+} from "@metaobjectsdev/codegen-ts";
+import type { AgentSchemaInput, Dialect, SchemaColumnLike } from "@metaobjectsdev/codegen-ts";
+import { buildExpectedSchemaWithProvenance, columnTypeSql, qualifiedDbName } from "@metaobjectsdev/migrate-ts";
+import type { MetaRoot } from "@metaobjectsdev/metadata";
+import { describeError } from "./error-text.js";
+
+/**
+ * The schema for `agent/schema.md`, or undefined, after saying why through `warn`, when the
+ * page is to be SKIPPED. A skipped page is not a silent pass: `meta verify --codegen` convicts
+ * a committed `agent/schema.md` that a fresh run no longer writes.
+ */
+export function buildAgentSchemaInput(
+  root: MetaRoot,
+  configured: Dialect | undefined,
+  warn: (message: string) => void,
+): AgentSchemaInput | undefined {
+  // THE RUNNER'S OWN GUARD DECIDES THIS, not a default applied here. `DEFAULT_DIALECT` is
+  // inert: `meta gen` refuses a model that emits database code with no dialect declared, so a
+  // persisted model with no dialect is not a sqlite project. Documenting it as one would state
+  // an answer the toolchain never gave. A model with no persisted object needs no dialect and
+  // renders an empty schema page anyway, so the inert default is right for exactly the
+  // projects the guard lets through.
+  const dbEmitting = dbEmittingObjects(root.objects());
+  if (dbEmitting.length > 0 && configured === undefined) {
+    warn(`agent/schema.md skipped — ${missingDialectMessage(dbEmitting)}`);
+    return undefined;
+  }
+  // MySQL: MetaObjects does not own the schema, so there is no migrate-built schema to
+  // describe. The generated Drizzle tables are the description.
+  if (configured === "mysql") {
+    warn("agent/schema.md skipped — MetaObjects does not own a MySQL schema (the generated Drizzle tables describe it).");
+    return undefined;
+  }
+  const dialect = configured ?? DEFAULT_DIALECT;
+  try {
+    const built = buildExpectedSchemaWithProvenance(root, {
+      dialect,
+      // Views come from codegen-ts (migrate-ts never generates view DDL), exactly as
+      // `verify --db` threads them.
+      views: buildProjectionViews(root, { dialect }),
+    });
+    return {
+      dialect,
+      tables: built.snapshot.tables,
+      views: built.snapshot.views,
+      provenance: built.provenance,
+      // The structural `SchemaColumnLike` is migrate-ts's own ColumnDescriptor, narrowed to
+      // what the page reads; the cast hands the full descriptor back to the renderer that
+      // produced it.
+      columnType: (c: SchemaColumnLike) => columnTypeSql(c as never, dialect),
+      qualify: qualifiedDbName,
+    };
+  } catch (err) {
+    // A model the schema builder refuses is a real condition (a primary-key move, a duplicate
+    // physical name) that `meta migrate` reports properly. Documentation must not be the
+    // command that fails on it, so the schema page is skipped and the other pages still emit.
+    warn(
+      `agent/schema.md skipped — the expected schema could not be built ` +
+        `(${describeError(err)}). Run 'meta migrate' for the full diagnosis.`,
+    );
+    return undefined;
+  }
+}

package/src/lib/allow.ts

@@ -2,8 +2,8 @@
 // both `meta migrate` and `meta verify --db`. Keeping a single copy avoids the
 // two commands drifting on which `--allow` tokens exist or how a change reads.
 
-import { allowOptionFor, suggestColumnRenames } from "@metaobjectsdev/migrate-ts";
-import type { AllowOptions, Change, ColumnRenameSuggestion } from "@metaobjectsdev/migrate-ts";
+import { allowOptionFor, describeSqlType, isViewRecreateOnly, suggestColumnRenames } from "@metaobjectsdev/migrate-ts";
+import type { AllowOptions, Change, ColumnRenameSuggestion, ViewChangeReason } from "@metaobjectsdev/migrate-ts";
 import type { BlockedEntry } from "./output.js";
 
 // Map CLI allow tokens → migrate-ts AllowOptions field names.
@@ -71,7 +71,7 @@ export function describeChange(c: Change): string {
       const from = c.fromDefault?.value ?? "none";
       const to = c.toDefault?.value ?? "none";
       const dflt = from === to && c.fromDefault?.kind === c.toDefault?.kind ? "" : `, default ${from} → ${to}`;
-      return `${c.table}.${c.column} (${c.from.kind} → ${c.to.kind}${dflt})`;
+      return `${c.table}.${c.column} (${describeSqlType(c.from)} → ${describeSqlType(c.to)}${dflt})`;
     }
     case "change-column-nullable": return `${c.table}.${c.column} (${c.from ? "NULL" : "NOT NULL"} → ${c.to ? "NULL" : "NOT NULL"})`;
     case "change-column-default": return `${c.table}.${c.column}`;
@@ -84,9 +84,9 @@ export function describeChange(c: Change): string {
       return c.restore !== undefined
         ? `${c.table} check ${c.check} (${c.restore.expression})`
         : `${c.table} check ${c.check}`;
-    case "create-view": return c.view.name;
-    case "replace-view": return c.view.name;
-    case "drop-view": return c.view;
+    case "create-view": return withViewReason(c.view.name, c.reason);
+    case "replace-view": return withViewReason(c.view.name, c.reason);
+    case "drop-view": return withViewReason(c.view, c.reason);
   }
   // Exhaustive: a new Change kind fails to compile here rather than printing a JSON dump
   // of the change object to a person (which is what a blocked drop-check used to do).
@@ -94,6 +94,57 @@ export function describeChange(c: Change): string {
   return unhandled;
 }
 
+/**
+ * A view's name plus WHY the diff planned its change. A bare name was all a view change
+ * ever printed, so a view whose definition matched the metadata — dropped and recreated only
+ * because the migration alters a table it reads — read exactly like one that differed (D3).
+ */
+function withViewReason(name: string, reason: ViewChangeReason | undefined): string {
+  return reason === undefined ? name : `${name} (${viewReasonText(reason)})`;
+}
+
+function viewReasonText(r: ViewChangeReason): string {
+  switch (r.kind) {
+    case "missing": return "declared by the metadata, not in the database";
+    case "undeclared": return "in the database, declared by no metadata object";
+    case "definition": {
+      const what = r.compared === "fingerprint"
+        ? "definition differs: the database view's fingerprint does not match the metadata's"
+        : r.firstDifference !== undefined
+          ? `definition text differs: metadata «${r.firstDifference.expected}» vs database «${r.firstDifference.actual}»`
+          : "definition text differs";
+      return recreatedAround(what, r.tables);
+    }
+    case "unfingerprinted":
+      return recreatedAround(
+        "the database view carries no MetaObjects fingerprint, so its definition cannot be compared",
+        r.tables,
+      );
+    case "unchanged":
+      return `definition matches the metadata; recreated because the migration alters ${tableList(r.tables)}`;
+  }
+}
+
+function recreatedAround(what: string, tables: readonly string[] | undefined): string {
+  return tables === undefined ? what : `${what}; recreated around the change to ${tableList(tables)}`;
+}
+
+function tableList(tables: readonly string[]): string {
+  return `${tables.length === 1 ? "table" : "tables"} ${tables.join(", ")}`;
+}
+
+/**
+ * One line naming the views a migration drops and recreates only because it alters a table
+ * they read. Their definitions match the metadata, and the migration needs the pair, but
+ * without this line the DROP VIEW / CREATE VIEW in the SQL reads like a view change (D3).
+ */
+export function viewRecreateNote(changes: readonly Change[]): string | undefined {
+  const views = changes.flatMap((c) => c.kind === "create-view" && isViewRecreateOnly(c) ? [c.view.name] : []);
+  if (views.length === 0) return undefined;
+  return `${views.length} view(s) match the metadata and are recreated only because the migration ` +
+    `alters a table they read: ${views.join(", ")}`;
+}
+
 /** The `--allow` token that unblocks `c`. migrate-ts picks the permission by what blocked the
  *  change (a type change can be blocked by the auto-sequence default it carries), so this only
  *  maps that permission back to its CLI token. */

package/src/lib/anti-patterns.ts

@@ -202,8 +202,10 @@ function matchLine(line: string, isSql: boolean):
 
 const ADVICE: Record<AntiPatternFinding["rule"], string> = {
   "hand-rolled-aggregate":
-    "you're computing an aggregate by hand — MetaObjects derives it: declare an " +
-    "object.projection with an origin.aggregate child and call its generated query",
+    "you're computing an aggregate by hand — MetaObjects derives it: for grouped, " +
+    "served or reported figures declare an object.report (dimensions + measures, a " +
+    "read-only list route); an object.projection with an origin.aggregate child still " +
+    "fits a per-row figure on one entity read through its generated query",
   "money-float":
     "money handled as a float / hand-rolled minor units — MetaObjects has " +
     "field.currency (integer minor units stored, formatted client-side)",