@metaobjectsdev/cli 1.0.8 → 1.0.9-rc.2

package/src/index.ts

@@ -142,6 +142,8 @@ MIGRATE FLAGS:
                         drop-column,drop-table,type-change,drop-index,drop-fk,
                         drop-check,drop-view,drop-view-cascade,
                         adopt-view,nullable-to-not-null,drop-identity-default
+                        drop-column DELETES the column's data; for a renamed
+                        column use --rename-column, which keeps it
   --on-ambiguous abort|rename|drop-add   Default abort
   --rename-table [schema.]old=new         Declare a table rename (repeatable)
   --rename-column [schema.]table.old=new  Declare a column rename; keeps its data (repeatable)
@@ -151,8 +153,7 @@ MIGRATE FLAGS:
   --yes                 Skip the --remote --apply confirmation pause
   --dry-run             Print SQL to stdout, don't write
 
-Other commands (ingest, mcp, serve, install-hooks, audit, capture, promote)
-ship in later sub-projects. See https://metaobjects.com for docs.
+See https://metaobjects.com for docs.
 `;
 
 /** Focused per-subcommand usage slices shown by `<cmd> --help`. */
@@ -323,6 +324,8 @@ FLAGS:
 A bare 'meta verify' also runs an ADVISORY anti-pattern pass: it scans your authored
 source for hand-rolled aggregates, money-as-float, and CHECK-IN enums and points you
 at the construct that models them (origin.aggregate / field.currency / field.enum).
+The same pass names every foreign key with no index on its referencing column(s)
+and the index.lookup that would cover it (migrate never adds one on its own).
 Warnings only — it never fails the build. Opt out with --no-antipatterns or
 META_NO_ANTIPATTERNS=1.
 

package/src/lib/advisory.ts

@@ -163,6 +163,39 @@ export function libraryPrefixRows(
   }));
 }
 
+/**
+ * Unindexed foreign keys in the same row shape. `construct` is `<entity FQN>.<reference>`,
+ * the node the author edits to declare the index. There is no line: the finding is about the
+ * loaded model, which does not carry source positions.
+ */
+export function unindexedFkRows(
+  findings: readonly { file: string; construct: string; message: string }[],
+): AdvisoryFindingRow[] {
+  return findings.map((f) => ({
+    file: f.file,
+    line: 0,
+    rule: "unindexed-foreign-key",
+    construct: f.construct,
+    message: f.message,
+  }));
+}
+
+/**
+ * Relationships on both sides of one FK that disagree on its referential action, in the
+ * same row shape. `construct` is `<entity FQN>.<reference>` — the FK, where the fix goes.
+ */
+export function referentialActionConflictRows(
+  findings: readonly { file: string; construct: string; message: string }[],
+): AdvisoryFindingRow[] {
+  return findings.map((f) => ({
+    file: f.file,
+    line: 0,
+    rule: "overridden-referential-action",
+    construct: f.construct,
+    message: f.message,
+  }));
+}
+
 // ---------------------------------------------------------------------------
 // text output
 // ---------------------------------------------------------------------------

package/src/lib/allow.ts

@@ -2,7 +2,9 @@
 // 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 type { AllowOptions, Change } from "@metaobjectsdev/migrate-ts";
+import { allowOptionFor, suggestColumnRenames } from "@metaobjectsdev/migrate-ts";
+import type { AllowOptions, Change, ColumnRenameSuggestion } from "@metaobjectsdev/migrate-ts";
+import type { BlockedEntry } from "./output.js";
 
 // Map CLI allow tokens → migrate-ts AllowOptions field names.
 // Exported (not just module-local) so allow-tokens-pinned.test.ts can pin its
@@ -77,9 +79,71 @@ export function describeChange(c: Change): string {
     case "drop-index": return `${c.table} idx ${c.index}`;
     case "add-fk": return `${c.table} fk ${c.fk.name}`;
     case "drop-fk": return `${c.table} fk ${c.fk}`;
+    case "add-check": return `${c.table} check ${c.check.name} (${c.check.expression})`;
+    case "drop-check":
+      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;
-    default: return JSON.stringify(c);
   }
+  // 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).
+  const unhandled: never = c;
+  return unhandled;
+}
+
+/** 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. */
+export function allowFlagFor(c: Change): string {
+  const option = allowOptionFor(c);
+  const token = Object.keys(ALLOW_TOKEN_MAP).find((t) => ALLOW_TOKEN_MAP[t] === option);
+  return token ?? c.kind;
+}
+
+/** `--rename-column [schema.]table.old=new`, spelled with the pair's real names. */
+export function renameColumnFlag(r: ColumnRenameSuggestion): string {
+  return `--rename-column ${r.schema !== undefined ? `${r.schema}.` : ""}${r.table}.${r.from}=${r.to}`;
+}
+
+/**
+ * One reportable entry per blocked change. `changes` is the whole diff the blocked ones came
+ * from: a blocked drop-column that pairs with an add-column in the same table may be a column
+ * the author RENAMED, and `--allow drop-column` would delete its data — so that entry carries
+ * the declared-rename flag, which every renderer prints FIRST.
+ */
+export function blockedEntriesFor(blocked: readonly Change[], changes: readonly Change[]): BlockedEntry[] {
+  const renames = suggestColumnRenames(changes);
+  return blocked.map((c) => {
+    const entry: BlockedEntry = { kind: c.kind, description: describeChange(c), allowFlag: allowFlagFor(c) };
+    if (c.kind !== "drop-column") return entry;
+    const r = renames.find((x) => x.from === c.column && x.table === c.table && x.schema === c.schema);
+    if (r === undefined) return entry;
+    return {
+      ...entry,
+      renameFlag: renameColumnFlag(r),
+      renameTo: `${r.table}.${r.to}`,
+      ...(r.shapeChange !== undefined ? { shapeChange: r.shapeChange } : {}),
+    };
+  });
+}
+
+/**
+ * The hint for one blocked entry, as the lines a renderer prints in order. A rename-pairable
+ * drop leads with the declared rename and names `--allow drop-column` as what deletes the data;
+ * every other entry is the one-line `--allow` hint it always was.
+ */
+export function blockedHintLines(e: BlockedEntry): string[] {
+  if (e.renameFlag === undefined) {
+    return [`blocked '${e.kind}' on ${e.description} (allow with --allow ${e.allowFlag})`];
+  }
+  const shape = e.shapeChange !== undefined
+    ? ` (its ${e.shapeChange} also changes: rename first with the old shape still declared, then change the shape in a second migration)`
+    : "";
+  return [
+    `${e.description} is dropped and ${e.renameTo ?? "a column"} is added in the same table. If it was renamed, keep its data: re-run with ${e.renameFlag}${shape}`,
+    `  (--allow ${e.allowFlag} instead DELETES ${e.description} and all its data)`,
+  ];
 }

package/src/lib/catalog-listing.ts

@@ -334,6 +334,11 @@ export const REFERENCE_HELPER_NOTE: readonly string[] = [
   "render) is not a generator and is not listed here.",
 ];
 
+/** The footer line explaining the `package-only` row mark. */
+export const PACKAGE_ONLY_NOTE =
+  "package-only = no reference template ships for it yet, so `meta eject` cannot copy it; " +
+  "import it from its package instead.";
+
 /** The human rendering: grouped by layer, because layer is the axis you select by. */
 export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
   const lines: string[] = [];
@@ -352,6 +357,7 @@ export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
     const marks: string[] = [];
     if (r.framework !== undefined) marks.push(r.framework);
     if (r.tier === "neutral") marks.push("neutral");
+    if (!r.source.ejectable) marks.push("package-only");
     if (r.project?.wired) marks.push("WIRED");
     if (r.source.owned) marks.push("owned");
     if (probed && r.project?.wouldEmit !== null && r.project?.wouldEmit !== undefined) {
@@ -372,6 +378,7 @@ export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
   lines.push("");
   lines.push("`meta eject <name...>` copies a generator into codegen/generators/ and prints");
   lines.push("the import to add, the entry to wire, and what to install.");
+  if (generators.some((r) => !r.source.ejectable)) lines.push(PACKAGE_ONLY_NOTE);
   if (!probed) {
     lines.push("Add --probe to see how many files each would emit for YOUR model.");
   }

package/src/lib/file-provider.ts

@@ -16,13 +16,23 @@ export class FileProvider implements Provider {
   constructor(private readonly baseDir: string) {}
 
   resolve(ref: string): string | undefined {
+    const path = this.pathOf(ref);
+    return path === undefined ? undefined : readFileSync(path, "utf8");
+  }
+
+  /**
+   * The file `ref` resolves to, or undefined. `resolve` reads exactly this file, so a
+   * diagnostic that names it names the body that was checked.
+   */
+  pathOf(ref: string): string | undefined {
     // `group/source` → <baseDir>/group/source<ext>; node:path.join normalizes
     // the embedded "/" separators for the host OS.
     for (const ext of EXTENSIONS) {
       const path = join(this.baseDir, ref) + ext;
       if (existsSync(path)) {
         try {
-          return readFileSync(path, "utf8");
+          readFileSync(path, "utf8");
+          return path;
         } catch {
           // unreadable — fall through and try the next candidate
         }
@@ -31,3 +41,19 @@ export class FileProvider implements Provider {
     return undefined;
   }
 }
+
+/**
+ * The 1-based line of the first mustache tag naming `path` in `text` — `{{path}}`,
+ * `{{{path}}}`, `{{& path}}`, `{{#path}}`, `{{^path}}` — trying the full dotted path and then
+ * its head segment (a dotted drift is reported on the path, but the tag may open a section on
+ * the head). Undefined when no tag matches, e.g. the variable lives in a partial.
+ */
+export function mustacheTagLine(text: string, path: string): number | undefined {
+  const esc = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const head = path.split(".")[0] ?? path;
+  for (const name of path === head ? [path] : [path, head]) {
+    const m = new RegExp(`\\{\\{\\{?\\s*[#^&]?\\s*${esc(name)}\\s*\\}`).exec(text);
+    if (m !== null) return text.slice(0, m.index).split("\n").length;
+  }
+  return undefined;
+}

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

@@ -0,0 +1,112 @@
+// Foreign keys with no index covering their columns — an advisory authoring lint.
+//
+// `meta migrate` emits a FOREIGN KEY constraint for every enforced `identity.reference`
+// and no index on its columns: neither Postgres nor SQLite indexes the referencing side
+// of a foreign key. Every join from the parent, and every ON DELETE cascade / set-null /
+// restrict check from it, then scans the child table. Generating the index automatically
+// would propose a migration to every existing adopter the release it shipped, so this is
+// advice, never a gate: it names each such key and says how to declare the index.
+//
+// Coverage is read off the EXPECTED SCHEMA migrate itself builds (primary key, every
+// `identity.secondary`, every `index.lookup`, every `@unique` field), not re-derived from
+// the metadata — so "covered" means covered in the DDL migrate would emit. An index covers
+// a key when its leading columns are exactly the key's columns, in any order. Expression
+// indexes are not counted; partial ones are (bias to under-flagging).
+
+import {
+  INDEX_SUBTYPE_LOOKUP,
+  TYPE_INDEX,
+  TYPE_SUBTYPE_SEPARATOR,
+} from "@metaobjectsdev/metadata/constants";
+import {
+  isMetaObject,
+  resolveColumnName,
+  type ColumnNamingStrategy,
+  type MetaData,
+} from "@metaobjectsdev/metadata";
+import {
+  buildExpectedSchemaWithProvenance,
+  qualifiedDbName,
+  type Dialect,
+  type TableDescriptor,
+} from "@metaobjectsdev/migrate-ts";
+
+export interface UnindexedFkFinding {
+  /** The metadata file declaring the entity ("" when the loader recorded none). */
+  file: string;
+  /** `<entity FQN>.<reference name>`. */
+  construct: string;
+  message: string;
+}
+
+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;
+}
+
+const INDEX_LOOKUP = `${TYPE_INDEX}${TYPE_SUBTYPE_SEPARATOR}${INDEX_SUBTYPE_LOOKUP}`;
+
+function covered(table: TableDescriptor, fkColumns: readonly string[]): boolean {
+  const want = new Set(fkColumns);
+  const prefixes = [
+    table.primaryKey,
+    ...table.indexes.filter((i) => i.expr === undefined).map((i) => i.columns),
+  ];
+  return prefixes.some((cols) =>
+    cols.length >= want.size && cols.slice(0, want.size).every((c) => want.has(c)));
+}
+
+function pascal(s: string): string {
+  return s.length === 0 ? s : s[0]!.toUpperCase() + s.slice(1);
+}
+
+export function scanForUnindexedForeignKeys(root: MetaData, opts: UnindexedFkOptions): UnindexedFkFinding[] {
+  const { snapshot, provenance } = buildExpectedSchemaWithProvenance(root, {
+    dialect: opts.dialect,
+    columnNamingStrategy: opts.columnNamingStrategy,
+  });
+  // 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),
+  );
+
+  const out: UnindexedFkFinding[] = [];
+  for (const table of snapshot.tables) {
+    const fqn = provenance.get(qualifiedDbName(table));
+    if (fqn === undefined || opts.skip?.(fqn) === true) continue;
+    const entity = objectsByFqn.get(fqn);
+    if (entity === undefined) continue;
+    const files = "files" in entity.source ? entity.source.files : [];
+    // A node a shipped library contributed is the library's design, not the adopter's.
+    if (files.some((f) => f.startsWith("library:"))) continue;
+
+    for (const fk of table.foreignKeys) {
+      if (covered(table, fk.columns)) continue;
+      // Name the key in the author's terms: the reference and its FIELDS, not columns.
+      // A TPH subtype's reference folds into its base's table and is not on `entity`;
+      // it is then reported by column, which is still enough to act on.
+      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 cols.length === fk.columns.length && cols.every((c, i) => c === fk.columns[i]);
+      });
+      const fields = ref !== undefined ? ref.fields : fk.columns;
+      const label = ref !== undefined ? `${entity.name}.${ref.name}` : `${entity.name} (${fk.name})`;
+      const indexName = `by${fields.map(pascal).join("")}`;
+      const fieldList = fields.length === 1 ? fields[0]! : `[${fields.join(", ")}]`;
+      out.push({
+        file: files[0] ?? "",
+        construct: `${fqn}.${ref?.name ?? fk.name}`,
+        message:
+          `${label}: foreign key (${fields.join(", ")}) → ${fk.refTable} has no index covering it, ` +
+          `so joins from ${fk.refTable} and its ON DELETE checks scan ${table.name}. ` +
+          `Declare one on ${entity.name}: ${INDEX_LOOKUP}: { name: ${indexName}, fields: ${fieldList} }`,
+      });
+    }
+  }
+  return out;
+}

package/src/lib/output.ts

@@ -6,6 +6,7 @@
 import type { Dialect } from "./kysely.js";
 import { toonEncode } from "./format.js";
 import { skippedSection, type AdvisoryFindingRow, type AdvisorySection } from "./advisory.js";
+import { blockedHintLines } from "./allow.js";
 
 export interface FormatOptions {
   isTTY: boolean;
@@ -154,6 +155,15 @@ export interface BlockedEntry {
   kind: string;
   description: string;
   allowFlag: string;
+  /**
+   * Set on a blocked drop-column that pairs with an add-column in the same table: the exact
+   * `--rename-column` flag that keeps the data. Printed BEFORE `--allow`, which deletes it.
+   */
+  renameFlag?: string;
+  /** `table.column` the dropped column may have been renamed to. */
+  renameTo?: string;
+  /** The shape difference that forces the rename and the reshape into two migrations. */
+  shapeChange?: string;
 }
 
 export interface AmbiguousEntry {
@@ -204,9 +214,14 @@ export function formatMigrateResult(result: MigrateResultShape, _opts: FormatOpt
   }
 
   if (result.blocked.length > 0) {
-    lines.push("  Blocked (re-run with --allow):");
+    const anyRename = result.blocked.some((b) => b.renameFlag !== undefined);
+    lines.push(anyRename ? "  Blocked (re-run with the flag shown):" : "  Blocked (re-run with --allow):");
     for (const b of result.blocked) {
-      lines.push(`    ${b.kind}  ${b.description}  (--allow ${b.allowFlag})`);
+      if (b.renameFlag === undefined) {
+        lines.push(`    ${b.kind}  ${b.description}  (--allow ${b.allowFlag})`);
+      } else {
+        for (const l of blockedHintLines(b)) lines.push(`    ${l}`);
+      }
     }
     lines.push("");
   }
@@ -328,8 +343,15 @@ export function migrateResultToData(result: MigrateResultShape): {
   let help: string[];
   if (isBlocked) {
     summary = `${changeSummary}; not applied`;
+    // A rename-pairable drop leads: its `--allow` would delete the data the rename keeps.
+    const renames = result.blocked.filter((b) => b.renameFlag !== undefined);
+    const others = result.blocked.filter((b) => b.renameFlag === undefined);
     help = [
-      ...result.blocked.map((b) => `re-run with --allow ${b.allowFlag} to apply: ${b.description}`),
+      ...renames.map((b) =>
+        `if ${b.description} was renamed to ${b.renameTo ?? "the added column"}, re-run with ${b.renameFlag} to keep its data` +
+        `${b.shapeChange !== undefined ? ` (its ${b.shapeChange} also changes: rename first, reshape in a second migration)` : ""}` +
+        `; --allow ${b.allowFlag} instead DELETES the column and all its data`),
+      ...others.map((b) => `re-run with --allow ${b.allowFlag} to apply: ${b.description}`),
       ...result.ambiguous.map((a) => `re-run with --on-ambiguous to resolve: ${a.hint}`),
     ];
   } else if (result.dryRun) {

package/src/lib/referential-action-advisory.ts

@@ -0,0 +1,58 @@
+// Two relationships over one foreign key that disagree on its referential action.
+//
+// A 1:N may be declared on either side — the parent (`Author` composition `books`) or the
+// FK-owning child (`Book` association `author`) — and each side's subtype implies an
+// ON DELETE default (composition → cascade, association → restrict). When BOTH are
+// declared and disagree, the documented precedence (ADR-0047) lets the FK-owning side
+// govern, so the parent's relationship has no effect on the constraint. That is a
+// defensible rule and a silent one: an adopter declared a composition, read "cascade" in
+// the docs, and got ON DELETE RESTRICT and a 409 with nothing saying why.
+//
+// Advisory, never a gate: changing the precedence would change the DDL of every model
+// that relies on it. This names each such key, the action that governs, and the two
+// one-line ways to say which one the author means. Read off the SAME walk that emits the
+// FK (`buildExpectedSchema`'s `onReferentialActionConflict`), so it can only ever name a
+// constraint migrate actually writes. `meta verify` lists them; `meta migrate` warns.
+
+import type { MetaData } from "@metaobjectsdev/metadata";
+import {
+  buildExpectedSchema,
+  describeReferentialActionConflict,
+  type ReferentialActionConflict,
+} from "@metaobjectsdev/migrate-ts";
+
+export interface ReferentialActionConflictFinding {
+  /** The metadata file declaring the FK-owning entity ("" when the loader recorded none). */
+  file: string;
+  /** `<entity FQN>.<reference name>` — the FK, which is where the fix is declared. */
+  construct: string;
+  message: string;
+}
+
+export interface ReferentialActionConflictOptions {
+  /** Skip an entity by FQN — imported (dependency) metadata is not the adopter's to fix. */
+  skip?: (fqn: string) => boolean;
+}
+
+export function scanForReferentialActionConflicts(
+  root: MetaData,
+  opts: ReferentialActionConflictOptions = {},
+): ReferentialActionConflictFinding[] {
+  const conflicts: ReferentialActionConflict[] = [];
+  buildExpectedSchema(root, { onReferentialActionConflict: (c) => conflicts.push(c) });
+
+  const out: ReferentialActionConflictFinding[] = [];
+  const seen = new Set<string>();
+  for (const c of conflicts) {
+    const fqn = c.entity.resolutionKey();
+    if (opts.skip?.(fqn) === true) continue;
+    const construct = `${fqn}.${c.ref.name}`;
+    if (seen.has(construct)) continue;
+    seen.add(construct);
+    const files = "files" in c.entity.source ? c.entity.source.files : [];
+    // A node a shipped library contributed is the library's design, not the adopter's.
+    if (files.some((f) => f.startsWith("library:"))) continue;
+    out.push({ file: files[0] ?? "", construct, message: describeReferentialActionConflict(c) });
+  }
+  return out;
+}