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

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

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
@@ -351,6 +351,63 @@ export async function loadMetaobjectsConfig(projectRoot: string): Promise<Metaob
     } catch { /* no ts-poet adjacent to codegen-ts — leave project resolution in place */ }
   }
 
+  // EVERY DECLARED SUBPATH EXPORT NEEDS ITS OWN ENTRY, because jiti's `alias` matches by
+  // PREFIX and then concatenates the remainder onto the mapped value. The mapped value is
+  // a FILE, so `@metaobjectsdev/codegen-ts/templates/inferred-types` became
+  // `…/codegen-ts/dist/index.js/templates/inferred-types` — a path that has never existed,
+  // named in an error message that mentions neither jiti nor the alias map:
+  //
+  //     Cannot find module '…/@metaobjectsdev/codegen-ts/dist/index.js/templates/inferred-types'
+  //
+  // So every subpath the package deliberately exports was unloadable from an owned
+  // generator, and the documented escape (a dynamic `import()`, which this file's own
+  // comment offers) failed identically, because it falls back to the same broken matcher.
+  // A cold adoption probe hit this retargeting the entity tier off Drizzle and got past it
+  // only by reading this file's compiled output — the subpath holds `fieldTsTypeString`,
+  // the one neutral MetaField→TypeScript mapper, which anyone replacing `renderDrizzleSchema`
+  // needs. `rewriteImportSpecifiers` above was always correct here (it anchors on the
+  // closing quote, so a subpath is left alone); only the alias fallback was wrong, and the
+  // fallback is what an OWNED GENERATOR gets, since only the config file is pre-processed.
+  //
+  // DERIVED from each package's own `exports` map rather than listed. A hand-kept list of
+  // subpaths is the same defect one level up: the package adds an export, nobody edits this
+  // file, and it is unloadable again with the same unrecognisable error. Resolution goes
+  // through `createRequire().resolve`, so the exports map — including its conditions — is
+  // the authority, and a subpath that does not resolve is skipped rather than guessed at.
+  for (const [specifier, resolvedPath] of [...Object.entries(aliasMap)]) {
+    if (!specifier.startsWith("@metaobjectsdev/")) continue;
+    // The package root is the specifier itself; a specifier that is already a subpath
+    // (e.g. ".../generators") contributes nothing further.
+    if (specifier.slice("@metaobjectsdev/".length).includes("/")) continue;
+    // Read the manifest off the FILE SYSTEM by walking up from the resolved entry, not by
+    // requiring `<specifier>/package.json` — these packages do not list `./package.json` in
+    // their own exports map, so requiring it throws ERR_PACKAGE_PATH_NOT_EXPORTED and the
+    // derivation silently produces nothing. (Which it did, on the first cut of this fix:
+    // the gate in test/owned-generator-subpath-import.test.ts stayed red and named the
+    // same impossible path, which is exactly what that assertion is for.)
+    let manifest: { exports?: Record<string, unknown> } | undefined;
+    for (let dir = dirname(resolvedPath); ; dir = dirname(dir)) {
+      try {
+        const parsed = JSON.parse(readFileSync(resolve(dir, "package.json"), "utf8")) as {
+          name?: string;
+          exports?: Record<string, unknown>;
+        };
+        if (parsed.name === specifier) { manifest = parsed; break; }
+      } catch { /* not this directory — keep walking */ }
+      const parent = dirname(dir);
+      if (parent === dir) break;   // filesystem root
+    }
+    if (manifest === undefined) continue;   // no readable manifest — leave normal resolution
+    for (const key of Object.keys(manifest?.exports ?? {})) {
+      if (!key.startsWith("./") || key.includes("*")) continue;
+      const sub = `${specifier}/${key.slice(2)}`;
+      if (aliasMap[sub] !== undefined) continue;   // an explicit CLI_PKG_PATHS entry wins
+      try {
+        aliasMap[sub] = createRequire(resolvedPath).resolve(sub);
+      } catch { /* not resolvable under these conditions — skip rather than invent a path */ }
+    }
+  }
+
   // Pre-process the config file content to rewrite @metaobjectsdev/* import
   // specifiers to resolved absolute paths. This is the primary mechanism that
   // ensures the CLI's own copies are used: jiti's `alias` map is kept below as

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

@@ -16,40 +16,14 @@
 // unused artifact would be wrong.
 
 import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { log } from "./log.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. */
 export const HASH_MANIFEST_REL = join(".metaobjects", ".gen-state", ".hashes.json");
 
-/**
- * Ask git whether `relPath` is ignored, or undefined when the question cannot be
- * answered (not a repository, git missing).
- *
- * `check-ignore` is the only reliable answer: parsing `.gitignore` by hand would have
- * to reimplement precedence, negation and nested ignore files — and the specific trap
- * this check exists to catch (`.gen-state/` excluding a directory so a `!` negation
- * inside it can never apply) is exactly the rule a hand-rolled parser gets wrong.
- */
-function isGitIgnored(cwd: string, relPath: string): boolean | undefined {
-  const gitBin = process.env.META_GEN_GIT ?? "git";
-  let res;
-  try {
-    res = spawnSync(gitBin, ["-C", cwd, "check-ignore", "-q", "--", relPath], {
-      encoding: "utf-8",
-    });
-  } catch {
-    return undefined;
-  }
-  if (res.error !== undefined) return undefined;
-  // 0 = ignored, 1 = not ignored, 128 = not a git repo / other git error.
-  if (res.status === 0) return true;
-  if (res.status === 1) return false;
-  return undefined;
-}
-
 /**
  * Warn once when the hash manifest is git-ignored, naming the fix.
  *
@@ -61,15 +35,33 @@ export function warnIfManifestIgnored(cwd: string): void {
   // Nothing generated yet ⇒ nothing at risk ⇒ nothing worth saying.
   if (!existsSync(join(cwd, HASH_MANIFEST_REL))) return;
 
-  if (isGitIgnored(cwd, HASH_MANIFEST_REL) !== true) return;
+  // 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;
+
+  // 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

@@ -15,7 +15,27 @@ export interface FormatOptions {
 // gen
 // ---------------------------------------------------------------------------
 
-export type GenFileStatus = "new" | "merged" | "conflict" | "unchanged" | "refused" | "removed";
+/**
+ * `overwrite` is distinct from `new` on purpose. Reviewing a run, "an entity
+ * appeared" and "an existing artifact was rewritten" are different facts, and the
+ * CLI used to report both as `new` — the engine has always distinguished them
+ * (`WriteStatus.overwrite`), and the reporting layer collapsed the two. Found on
+ * two adopter estates independently, which is what makes it a reporting defect
+ * rather than a preference: the summary line was right and the per-file status
+ * was not.
+ */
+export type GenFileStatus =
+  | "new"
+  | "overwrite"
+  | "merged"
+  | "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 {
   path: string;
@@ -41,23 +61,35 @@ 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> = {
   new: "✓",
+  overwrite: "↻",
   merged: "↺",
   conflict: "✗",
   unchanged: "=",
   refused: "⚠",
+  adopted: "⊕",
   removed: "−",
 };
 
 const GEN_WORDS: Record<GenFileStatus, string> = {
   new: "NEW",
+  overwrite: "OVERWRITE",
   merged: "MERGED",
   conflict: "CONFLICT",
   unchanged: "UNCHANGED",
   refused: "REFUSED",
+  adopted: "ADOPTED",
   removed: "REMOVED",
 };
 
@@ -88,14 +120,22 @@ export function formatGenResult(result: GenResultShape, opts: FormatOptions): st
       acc[f.status] = (acc[f.status] ?? 0) + 1;
       return acc;
     },
-    { new: 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[] = [];
-  if (counts.new > 0) parts.push(`${counts.new} written`);
+  // "written" stays the sum of new + overwrite: that number was always correct and
+  // adopters read it. Splitting the SUMMARY as well would change a line nothing was
+  // wrong with; the per-file status is the one that was lying.
+  const written = counts.new + counts.overwrite;
+  if (written > 0) parts.push(`${written} written`);
   if (counts.merged > 0) parts.push(`${counts.merged} merged`);
   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(", ")}`, "");
 
@@ -198,21 +238,34 @@ 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, 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[] = [];
-  if (counts.new) parts.push(`${counts.new} written`);
+  // Same split as the text formatter: `written` is new + overwrite, and the
+  // per-file rows carry which one each was.
+  const written = counts.new + counts.overwrite;
+  if (written) parts.push(`${written} written`);
   if (counts.merged) parts.push(`${counts.merged} merged`);
   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;
+}

package/src/lib/requirement-lint.ts

@@ -155,6 +155,26 @@ const INERT_SLOTS = [DOC_ATTR_SUMMARY] as const;
  */
 const TITLE_IS_AN_ID = /^[A-Z]{2,}[- ]?\d+/;
 
+/**
+ * What is LEFT of a title once a leading catalogue id and its separator are removed.
+ *
+ * The rule fires only when that remainder is empty — when the label IS the id and
+ * nothing else. A title that carries an id AND a noun phrase is not "an id"; it is a
+ * label with a citation prefix, which is a house style, and the warning's own name is
+ * false for it.
+ *
+ * Measured on a 323-node adopter ledger that uses `@title` deliberately as its bridge
+ * to a spec catalogue: the un-narrowed rule fired **203 times**, on every run, telling
+ * that author their entire convention was wrong and offering a 203-entry edit. That is
+ * the "355 findings, all false" shape the 0.24.2 narrowing exists to avoid, reproduced
+ * by the check that narrowing shipped alongside. A lint people argue with is a lint
+ * people mute, and muting takes the six useful checks with it.
+ *
+ * `@title: "REQ-1234"` — a slot holding only a citation, with no label anywhere — is
+ * still caught, and that is the case the rule was written for.
+ */
+const TITLE_ID_ONLY = /^[A-Z]{2,}[- ]?\d+[\s\-–—:.]*$/;
+
 /** Lowercase, drop everything that is not alphanumeric, collapse the gaps.
  *  Two slots "say the same thing" only if they survive this identically — no
  *  similarity score, no threshold. A fuzzy match on prose produces findings the
@@ -343,12 +363,13 @@ export function lintRequirements(
 
     // -- an id is not a label -------------------------------------------------
     const title = readOwnSlot(node, DOC_ATTR_TITLE);
-    if (title !== undefined && TITLE_IS_AN_ID.test(title.trim())) {
+    if (title !== undefined && TITLE_ID_ONLY.test(title.trim())) {
       out.push(warn(path, WARN_REQUIREMENT_TITLE_IS_AN_ID,
-        `@title opens with a catalogue or ticket id: ${excerpt(title)}. A title is a NOUN PHRASE and ` +
-        `an id is not a name, so this is two things in one slot. SPLIT them — put the id in ` +
-        `@${REQUIREMENT_ATTR_TRACKED_BY}, which is the free-form reference slot and IS read, and leave ` +
-        `the phrase as the title. Moving the whole string would throw the label away.`));
+        `@title holds only a catalogue or ticket id: ${excerpt(title)}. A title is the entry's ` +
+        `LABEL and an id is not a name, so this slot says nothing a reader can use. Put the id in ` +
+        `@${REQUIREMENT_ATTR_TRACKED_BY}, which is the free-form reference slot and IS read, and ` +
+        `give @${DOC_ATTR_TITLE} a noun phrase. A title that carries an id AND a phrase ` +
+        `("FR-448 — prompt construction as typed payloads") is a house style and is NOT flagged.`));
     }
   }