@metaobjectsdev/cli 1.0.0-rc.5 → 1.0.0-rc.6

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

@@ -18,7 +18,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { log } from "./log.js";
-import { isGitIgnored } from "./git-ignore.js";
+import { gitIgnoreSource, isGitIgnored } from "./git-ignore.js";
 
 /** Project-relative path of the manifest — the one artifact of `.gen-state/` that is
  *  meant to be committed. */
@@ -40,13 +40,28 @@ export function warnIfManifestIgnored(cwd: string): void {
   // per-user ignore file answers it just as truly as a committed .gitignore does.
   if (isGitIgnored(cwd, HASH_MANIFEST_REL, { honourGlobalExcludes: true }) !== true) return;
 
+  // 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
+  // the places the exclusion can sit: an adopter estate had it in the ROOT `.gitignore` as
+  // `.metaobjects/.gen-state/`, so following this advisory to the letter edited a file that
+  // did not hold the rule, changed nothing, and printed this same line again — the loop
+  // shape. `git check-ignore -v` knows the answer, so nothing is guessed. When git cannot
+  // say, the wording degrades to the generic form rather than asserting a location.
+  const src = gitIgnoreSource(cwd, HASH_MANIFEST_REL, { honourGlobalExcludes: true });
+  const where =
+    src !== undefined
+      ? `The rule is '${src.pattern}' at ${src.file}:${src.line} — replace it there with ` +
+        `a '/*' form plus a '!' negation for the manifest ` +
+        `(e.g. '${src.pattern.replace(/\/$/, "")}/*' and '!${src.pattern.replace(/\/$/, "")}/.hashes.json')`
+      : `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(
     `${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. Fix it in ` +
-      `.metaobjects/.gitignore by replacing '.gen-state/' with '.gen-state/*' plus ` +
-      `'!.gen-state/.hashes.json' (the glob matters — git will not descend into an ` +
-      `excluded directory, so a negation under '.gen-state/' can never apply), then ` +
-      `commit the manifest. If you deliberately do not commit generated output, ignore this.`,
+      `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.`,
   );
 }

package/src/lib/output.ts

@@ -31,6 +31,10 @@ export type GenFileStatus =
   | "conflict"
   | "unchanged"
   | "refused"
+  /** `--baseline=adopt`: the file's existing content became the merge base and
+   *  nothing was written. Never folded into "unchanged" — the run's product is the
+   *  manifest, and a summary that showed these as unchanged would hide it. */
+  | "adopted"
   | "removed";
 
 export interface GenFileEntry {
@@ -57,6 +61,14 @@ export interface GenResultShape {
    * structured payload carries every finding.
    */
   antiPatterns?: AdvisorySection<AdvisoryFindingRow>;
+  /**
+   * How many generators the config wired. Required, because the alternative is a
+   * message that GUESSES: with no generators wired, a run over a project with five
+   * entities emitted nothing and reported "no entities to generate … author entities
+   * in this project's metadata sources", sending the reader to edit a file that was
+   * already correct. The output's own first line (`gen: []`) already knew.
+   */
+  generatorCount: number;
 }
 
 const GEN_GLYPHS: Record<GenFileStatus, string> = {
@@ -66,6 +78,7 @@ const GEN_GLYPHS: Record<GenFileStatus, string> = {
   conflict: "✗",
   unchanged: "=",
   refused: "⚠",
+  adopted: "⊕",
   removed: "−",
 };
 
@@ -76,6 +89,7 @@ const GEN_WORDS: Record<GenFileStatus, string> = {
   conflict: "CONFLICT",
   unchanged: "UNCHANGED",
   refused: "REFUSED",
+  adopted: "ADOPTED",
   removed: "REMOVED",
 };
 
@@ -106,7 +120,7 @@ export function formatGenResult(result: GenResultShape, opts: FormatOptions): st
       acc[f.status] = (acc[f.status] ?? 0) + 1;
       return acc;
     },
-    { new: 0, overwrite: 0, merged: 0, conflict: 0, unchanged: 0, refused: 0, removed: 0 },
+    { new: 0, overwrite: 0, merged: 0, conflict: 0, unchanged: 0, refused: 0, adopted: 0, removed: 0 },
   );
   const parts: string[] = [];
   // "written" stays the sum of new + overwrite: that number was always correct and
@@ -118,6 +132,10 @@ export function formatGenResult(result: GenResultShape, opts: FormatOptions): st
   if (counts.conflict > 0) parts.push(`${counts.conflict} conflict`);
   if (counts.unchanged > 0) parts.push(`${counts.unchanged} unchanged`);
   if (counts.refused > 0) parts.push(`${counts.refused} refused`);
+  // `--baseline=adopt`: recorded as the merge base, nothing written. Counted separately
+  // from `unchanged` because the run's product is the manifest, and an adopter who cannot
+  // see how many files it now covers has no way to review what they are about to commit.
+  if (counts.adopted > 0) parts.push(`${counts.adopted} adopted`);
   if (counts.removed > 0) parts.push(`${counts.removed} removed`);
   lines.push("", `  ${parts.join(", ")}`, "");
 
@@ -220,7 +238,7 @@ export function genResultToData(result: GenResultShape): {
 } {
   const counts = result.files.reduce<Record<GenFileStatus, number>>(
     (a, f) => ((a[f.status] = (a[f.status] ?? 0) + 1), a),
-    { new: 0, overwrite: 0, merged: 0, conflict: 0, unchanged: 0, refused: 0, removed: 0 },
+    { new: 0, overwrite: 0, merged: 0, conflict: 0, unchanged: 0, refused: 0, adopted: 0, removed: 0 },
   );
   const parts: string[] = [];
   // Same split as the text formatter: `written` is new + overwrite, and the
@@ -231,13 +249,23 @@ export function genResultToData(result: GenResultShape): {
   if (counts.conflict) parts.push(`${counts.conflict} conflict`);
   if (counts.unchanged) parts.push(`${counts.unchanged} unchanged`);
   if (counts.refused) parts.push(`${counts.refused} refused`);
+  if (counts.adopted) parts.push(`${counts.adopted} adopted`);
   if (counts.removed) parts.push(`${counts.removed} removed`);
-  const summary = result.files.length === 0
-    ? `no entities to generate in ${result.outDir}`
-    : parts.join(", ");
-  const help = result.files.length === 0
-    ? ["author entities in this project's metadata sources then re-run `meta gen`"]
-    : ["typecheck the generated code with `npx tsc`", "create your database tables with `meta migrate --from-db --db <url> --dialect <sqlite|postgres> --slug init --apply`"];
+  // Two ways to emit nothing, and they send the reader to different files. Name the
+  // one that is actually true: a config wiring no generators cannot produce output
+  // however good the metadata is, and telling its author to go write entities is a
+  // false statement about a project that already has them.
+  const noGenerators = result.generatorCount === 0;
+  const summary = result.files.length !== 0
+    ? parts.join(", ")
+    : noGenerators
+      ? "no generators are wired in metaobjects.config.ts, so nothing was generated"
+      : `no entities to generate in ${result.outDir}`;
+  const help = result.files.length !== 0
+    ? ["typecheck the generated code with `npx tsc`", "create your database tables with `meta migrate --from-db --db <url> --dialect <sqlite|postgres> --slug init --apply`"]
+    : 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"]
+      : ["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".
   const antiPatterns = result.antiPatterns

package/src/lib/rel-posix.ts

@@ -0,0 +1,25 @@
+// One spelling of "a path, with forward slashes".
+//
+// Six modules under lib/ carried this rule inline — `git-ignore`, `docs-drift` (twice),
+// `anti-patterns`, `base-url-advisory` and `ignored-scaffold-check` — and one of the six
+// was spelled differently: `.split("\\").join("/")` rather than `.split(sep).join("/")`.
+// On Windows those agree, because `sep` IS a backslash. On POSIX they do not: `sep` is
+// already "/" so the correct form is a no-op, while splitting on a literal backslash
+// rewrites a filename that legitimately CONTAINS one. That is the drift six copies of a
+// one-line rule invite, and it had already happened.
+//
+// Comparisons against git's output are the reason the rule exists at all: `git check-ignore`
+// and `git ls-files` speak forward slashes on every platform, so a Windows path has to be
+// normalized before it can be looked up in a set built from git's answer.
+
+import { relative, sep } from "node:path";
+
+/** A path with the platform separator replaced by "/" — a no-op on POSIX. */
+export function toPosix(p: string): string {
+  return p.split(sep).join("/");
+}
+
+/** `abs` relative to `root`, forward-slashed. */
+export function relPosix(root: string, abs: string): string {
+  return toPosix(relative(root, abs));
+}

package/src/lib/replay-remedy.ts

@@ -0,0 +1,78 @@
+import { MigrationApplyError } from "@metaobjectsdev/migrate-ts";
+
+/**
+ * What to tell someone whose committed chain will not apply to an empty database.
+ *
+ * The message this replaces prescribed ONE fix — *"fix this with a NEW migration that
+ * creates the missing object"* — and it cannot work, in any case. Migrations apply in
+ * timestamp order, so anything authored now sorts AFTER the migration that failed; the
+ * object is still missing when that file runs. Two estates found it from opposite
+ * directions and it is the same defect both times:
+ *
+ * - a chain whose FIRST migration needs a schema an out-of-band script creates (the third
+ *   migration emits `CREATE SCHEMA IF NOT EXISTS`, the first predates it). A new migration
+ *   sorts last, after the one that needs the schema.
+ * - a project where **another tool owns schema creation** — drizzle-kit's chain builds the
+ *   tables, `.metaobjects/migrations/` holds later incremental patches. Following the
+ *   printed remedy literally means hand-authoring every `CREATE TABLE` into the MetaObjects
+ *   chain, i.e. duplicating a schema this project does not own, which is the opposite of
+ *   what the agent context teaches two paragraphs into its own Principles.
+ *
+ * The old message assumed MetaObjects is the only schema authority and offered no third
+ * possibility. These name the fixes that exist, and the head-of-chain case gets the extra
+ * sentence that is only true there: nothing in this chain could have created what the
+ * first migration needs, so the base schema comes from outside it.
+ *
+ * "Applied migrations are immutable" is kept, because it is true and it is the reason the
+ * obvious fix is not offered first — but it is stated as the CONDITION it actually is
+ * (a checksum guard on databases that already ran the file), not as a blanket ban, because
+ * a migration no database has applied yet is edited in place every day.
+ */
+/**
+ * Is this the migrate engine's own apply failure?
+ *
+ * By NAME, not `instanceof`. Two physical copies of `@metaobjectsdev/migrate-ts` in one
+ * process — a globally-installed or linked `meta` alongside a project-local dependency —
+ * give the class object and the instance different identities, so `instanceof` returns
+ * false for a real error and the remedy silently degrades to its un-positioned form. That
+ * is the same class-identity defect that split ts-poet's `Code` in 0.21.6 and drove the
+ * exported node guards in `metadata`. Unreachable through today's single import; costs one
+ * line to make unreachable by construction.
+ */
+function isApplyError(err: unknown): err is MigrationApplyError {
+  return err instanceof MigrationApplyError
+    || (err instanceof Error && err.name === "MigrationApplyError"
+        && typeof (err as MigrationApplyError).migration === "string"
+        && typeof (err as MigrationApplyError).index === "number");
+}
+
+export function replayRemedy(err: unknown): string[] {
+  const applyErr = isApplyError(err) ? err : undefined;
+  const head = applyErr !== undefined && applyErr.index === 0;
+  const which =
+    applyErr === undefined
+      ? "the committed chain does not apply to an empty database."
+      : `'${applyErr.migration}' (migration ${applyErr.index + 1} of ${applyErr.pendingCount}) ` +
+        `does not apply to an empty database.`;
+
+  const out = [which];
+  if (head) {
+    out.push(
+      "It is the FIRST migration in the chain, so nothing here could have created what it " +
+        "needs — this chain has never built a database from empty, and its base schema comes " +
+        "from outside it.",
+    );
+  }
+  out.push(
+    "A NEW migration cannot fix this: migrations apply in timestamp order, so anything you " +
+      "author now sorts after the file that failed.",
+  );
+  out.push(
+    "The fixes that do work: if another tool or an out-of-band script owns schema creation " +
+      "for this project, --replay asserts a property this chain does not have — don't wire " +
+      "it. Otherwise correct the migration in place if no database has applied it yet " +
+      "(the ledger's checksum guard is what stops you once one has), or re-baseline from a " +
+      "live database with `meta migrate baseline --from-db --db <url>`.",
+  );
+  return out;
+}