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

package/src/lib/detect-stack.ts

@@ -48,14 +48,85 @@ async function probe(cwd: string): Promise<ProjectProbe> {
   };
 }
 
+/**
+ * Spellings accepted for a stack value that is not the canonical one.
+ *
+ * `node` is here because the CLI's OWN `--help` gives it as an example of `--server`, and it
+ * is the more natural word for a Fastify backend run by the Node CLI. It used to be filtered
+ * out silently — see `assertKnownStackValues` for what that silence cost.
+ */
+const SERVER_ALIASES: Readonly<Record<string, ServerLang>> = {
+  node: "typescript",
+  nodejs: "typescript",
+  ts: "typescript",
+  "c#": "csharp",
+  dotnet: "csharp",
+  py: "python",
+};
+
+const CLIENT_ALIASES: Readonly<Record<string, ClientFramework>> = {
+  reactjs: "react",
+  "react-query": "tanstack",
+};
+
+/** Canonicalize one value, or `undefined` when it names nothing we know. */
+function canonical<T extends string>(
+  raw: string,
+  valid: readonly string[],
+  aliases: Readonly<Record<string, T>>,
+): T | undefined {
+  const v = raw.trim().toLowerCase();
+  if (valid.includes(v)) return v as T;
+  return aliases[v];
+}
+
+/**
+ * Refuse an unknown `--server` / `--client` value instead of dropping it.
+ *
+ * `--server node` — the CLI's own help example — used to exit 0 with no warning and record
+ * `"servers": []`. Worse than the missing four reference fragments: a non-empty override
+ * array suppresses BOTH the prior manifest's stack and detection, so the emitted context then
+ * declared "Stack: no server, no client" and told the agent that this project has no
+ * `metaobjects.config.ts` — about a project with a Fastify server, a React client, and the
+ * very config file the same CLI had just read. One silently-dropped flag value made three
+ * statements false in the artifact whose whole job is to orient an agent correctly.
+ *
+ * Either accept the value or say so; never neither.
+ */
+export function assertKnownStackValues(overrides: { servers: string[]; clients: string[] }): void {
+  const bad: string[] = [];
+  for (const s of overrides.servers) {
+    if (canonical(s, SERVER_LANGS as readonly string[], SERVER_ALIASES) === undefined) {
+      bad.push(`--server ${s} (known: ${SERVER_LANGS.join(", ")})`);
+    }
+  }
+  for (const c of overrides.clients) {
+    if (canonical(c, CLIENT_FRAMEWORKS as readonly string[], CLIENT_ALIASES) === undefined) {
+      bad.push(`--client ${c} (known: ${CLIENT_FRAMEWORKS.join(", ")})`);
+    }
+  }
+  if (bad.length > 0) {
+    throw new Error(
+      `unknown stack value(s): ${bad.join("; ")}. A value that names nothing is refused rather ` +
+        "than dropped: an empty stack suppresses both the prior manifest and detection, and the " +
+        "generated agent context then states the project has no server, no client and no " +
+        "metaobjects.config.ts.",
+    );
+  }
+}
+
 /** Resolve the stack: explicit --server/--client overrides take precedence; otherwise detect.
  * Concern tokens (e.g. requirements) are always OBSERVED from project state, independent of
  * any --server/--client override — a concern is not a stack axis. */
 export async function resolveStack(cwd: string, overrides: { servers: string[]; clients: string[] }): Promise<Stack> {
   const validServers = SERVER_LANGS as readonly string[];
   const validClients = CLIENT_FRAMEWORKS as readonly string[];
-  const oServers = overrides.servers.filter((s): s is ServerLang => validServers.includes(s));
-  const oClients = overrides.clients.filter((c): c is ClientFramework => validClients.includes(c));
+  const oServers = overrides.servers
+    .map((s) => canonical<ServerLang>(s, validServers, SERVER_ALIASES))
+    .filter((s): s is ServerLang => s !== undefined);
+  const oClients = overrides.clients
+    .map((c) => canonical<ClientFramework>(c, validClients, CLIENT_ALIASES))
+    .filter((c): c is ClientFramework => c !== undefined);
   const p = await probe(cwd);
   const concerns = detectConcerns(p);
   if (oServers.length > 0 || oClients.length > 0) return makeStack(oServers, oClients, concerns);

package/src/lib/docs-drift.ts

@@ -19,9 +19,11 @@
 //      `.gen-state/.hashes.json` to tell a preserved hand edit from stale output; here
 //      there is no such offer to honour.
 //
-//   2. IT REPORTS A FILE AS EXTRA ONLY WHERE IT OWNS THE DIRECTORY. `docs.outDir`
-//      defaults to `./docs`, which in a real repository is full of hand-written
-//      documentation — this repository's own `docs/` holds a hundred such files. Its
+//   2. IT REPORTS A FILE AS EXTRA ONLY WHERE IT OWNS THE DIRECTORY. `docs.outDir` is a
+//      directory an adopter chooses, and it may well be one full of hand-written
+//      documentation — this repository's own `docs/` holds a hundred such files. (The
+//      default moved to `./docs/generated` for exactly that reason: defaulting into the
+//      most-owned directory name in the ecosystem contradicted this paragraph.) Its
 //      `api/` subtree is not ours either: on a multi-port project those pages are written
 //      by the OTHER port's docs command (`mvn metaobjects:docs`, `metaobjects docs`,
 //      `dotnet meta docs`), which this gate never runs, so a fresh run here legitimately
@@ -47,8 +49,10 @@
 
 import { mkdtempSync, rmSync, existsSync, readFileSync, readdirSync, lstatSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, relative, resolve, isAbsolute, sep } from "node:path";
+import { join, relative, resolve, isAbsolute } from "node:path";
 import { docsCommand } from "../commands/docs.js";
+import { gitIgnored } from "./git-ignore.js";
+import { toPosix } from "./rel-posix.js";
 
 export interface DocsDriftResult {
   /** True when every page a fresh `meta docs` would write is committed and identical. */
@@ -59,8 +63,19 @@ export interface DocsDriftResult {
   /** Human-readable, one line per file. */
   lines: string[];
   /** The denominator both the passing and the failing report divide by: the pages a fresh
-   *  run produced, plus any committed page under `agent/` it no longer emits. */
+   *  run produced, plus any committed page under `agent/` it no longer emits, MINUS the
+   *  git-ignored ones. A pure function of (fresh set, repository ignore rules) — never of
+   *  which files happen to be on this machine's disk. */
   checked: number;
+  /** How many pages a fresh run emits that the project git-ignores, so did not check.
+   *  Reported on BOTH the passing and the failing line: a gate that quietly checked two
+   *  of 589 pages and said "no drift" would be indistinguishable from one that checked
+   *  everything. */
+  ignored: number;
+  /** Why the ignore rules could not be consulted, when they could not be. Undefined means
+   *  they were. The gate then falls back to checking EVERY page a fresh run emits — the
+   *  pre-existing behaviour — and says so rather than degrading silently. */
+  ignoreReason?: string | undefined;
   /** Set when the gate could not run at all. */
   error?: string;
 }
@@ -111,7 +126,7 @@ const GENERATED_MARKER = "@generated";
  * hand-written note inside `agent/` out of it.
  */
 function isOurs(docsDir: string, rel: string): boolean {
-  const normalized = rel.split(sep).join("/");
+  const normalized = toPosix(rel);
   if (!OWNED_PREFIXES.some((p) => normalized.startsWith(p))) return false;
   try {
     return readFileSync(join(docsDir, rel), "utf8")
@@ -163,6 +178,7 @@ export async function computeDocsDrift(args: ComputeDocsDriftArgs): Promise<Docs
         driftedFiles: [],
         lines: [],
         checked: 0,
+        ignored: 0,
         error:
           `verify --docs: 'meta docs' exited ${exit}, so the committed pages could not be ` +
           `compared against a fresh run. Fix that first — the error is above.`,
@@ -176,19 +192,96 @@ export async function computeDocsDrift(args: ComputeDocsDriftArgs): Promise<Docs
         driftedFiles: [],
         lines: [],
         checked: 0,
+        ignored: 0,
         error:
           "verify --docs: a fresh 'meta docs' produced no pages, so there is nothing to " +
           "compare. Check that this project declares metadata the docs surfaces cover.",
       };
     }
 
+    // Committed-but-not-regenerated, inside the directories this command owns.
+    const freshSet = new Set(fresh);
+    const ownedOrphans = listFiles(docsDir)
+      .filter((rel) => !freshSet.has(rel) && isOurs(docsDir, rel))
+      .sort();
+
+    // A page the project deliberately does not commit is not drift.
+    //
+    // `docs.outDir` is a directory, not a namespace MetaObjects owns — the same
+    // jurisdiction ruling 0.24.3 made for `verify --codegen`. But `--codegen` could key
+    // on `.gen-state/.hashes.json`, a record of what the generator WROTE, and `meta
+    // docs` keeps no such manifest. What it can ask instead is what the PROJECT says:
+    // a page under `docs.outDir` that git reports ignored is one the project has
+    // declared it does not commit.
+    //
+    // This is not a guess about intent, it is the project's own statement of it. And it
+    // cannot be used to hide a file the project actually tracks: git never reports a
+    // TRACKED path as ignored, whatever pattern matches it, so a committed page is
+    // always compared.
+    //
+    // The exemption is computed over the FRESH set by NAME, present on disk or not.
+    // That is what makes the verdict machine-independent: a developer box that has run
+    // `meta docs` locally has all 589 pages on disk and a CI runner has two, and both
+    // must report the same denominator. Deciding per-file-existence would have made
+    // `checked` a property of the machine.
+    //
+    // Without it: an estate generating three surfaces and committing 2 files of 589 —
+    // gitignoring the rest with a comment explaining they are a derived view of
+    // metadata that is already the source of truth — was told it had 588 drifted pages,
+    // of which exactly ONE was real.
+    const ignoreCandidates = [...fresh, ...ownedOrphans];
+    // honourGlobalExcludes: false — this verdict must be a property of the repository.
+    // A gate that passes for the author and fails in CI because of a personal ignore
+    // file is worse than no gate.
+    const ignoreLookup = gitIgnored(docsDir, ignoreCandidates, {
+      honourGlobalExcludes: false,
+    });
+    const ignored: ReadonlySet<string> =
+      "ignored" in ignoreLookup ? ignoreLookup.ignored : new Set<string>();
+    const ignoreReason: string | undefined =
+      "unavailable" in ignoreLookup ? ignoreLookup.unavailable : undefined;
+    const isIgnored = (rel: string): boolean => ignored.has(toPosix(rel));
+
+    const toCheck = fresh.filter((rel) => !isIgnored(rel));
+    const orphans = ownedOrphans.filter((rel) => !isIgnored(rel));
+    // BOTH halves. `ignoreCandidates` above tests fresh pages AND owned orphans, so an
+    // ignored orphan is dropped from the check exactly like an ignored fresh page — but
+    // counting only the fresh half reported a number SMALLER than the work actually
+    // skipped. That is the `verify --templates` denominator mistake in miniature (a line
+    // describing work the command did not do), which is the very thing the orphan loop
+    // below is written to avoid; the two must be consistent about the same set.
+    const ignoredCount =
+      fresh.length - toCheck.length + (ownedOrphans.length - orphans.length);
+
+    // A gate asked to check pages that could check NONE must not answer "no drift".
+    if (toCheck.length === 0 && orphans.length === 0) {
+      return {
+        clean: false,
+        driftedFiles: [],
+        lines: [],
+        checked: 0,
+        ignored: ignoredCount,
+        ignoreReason,
+        error:
+          `verify --docs: a fresh 'meta docs' produced ${fresh.length} page(s) and every ` +
+          `one of them is git-ignored, so there is nothing to compare. Commit the pages ` +
+          `you want checked, or run without --docs.`,
+      };
+    }
+
     const driftedFiles: string[] = [];
     const lines: string[] = [];
-    for (const rel of fresh) {
+    for (const rel of toCheck) {
       const committedPath = join(docsDir, rel);
       if (!existsSync(committedPath)) {
         driftedFiles.push(rel);
-        lines.push(`+ ${rel} (a fresh 'meta docs' emits it; not committed)`);
+        // When the rules could not be consulted the last clause would be a claim we
+        // have not checked, so it is dropped rather than asserted.
+        lines.push(
+          ignoreReason === undefined
+            ? `+ ${rel} (a fresh 'meta docs' emits it; not committed, not git-ignored)`
+            : `+ ${rel} (a fresh 'meta docs' emits it; not committed)`,
+        );
         continue;
       }
       const a = readFileSync(committedPath, "utf8");
@@ -198,14 +291,9 @@ export async function computeDocsDrift(args: ComputeDocsDriftArgs): Promise<Docs
         lines.push(`~ ${rel} (committed content differs from a fresh 'meta docs')`);
       }
     }
-    // Committed-but-not-regenerated, inside the directories this command owns. Counted
-    // into `checked` as well as `driftedFiles` so the failing line and the passing line
-    // keep dividing by the same set — the `verify --templates` mistake, where a red run
-    // and a green run reported different denominators for the same project.
-    const freshSet = new Set(fresh);
-    const orphans = listFiles(docsDir)
-      .filter((rel) => !freshSet.has(rel) && isOurs(docsDir, rel))
-      .sort();
+    // Counted into `checked` as well as `driftedFiles` so the failing line and the
+    // passing line keep dividing by the same set — the `verify --templates` mistake,
+    // where a red run and a green run reported different denominators for one project.
     for (const rel of orphans) {
       driftedFiles.push(rel);
       lines.push(`- ${rel} (committed; a fresh 'meta docs' no longer emits it)`);
@@ -214,7 +302,9 @@ export async function computeDocsDrift(args: ComputeDocsDriftArgs): Promise<Docs
       clean: driftedFiles.length === 0,
       driftedFiles: driftedFiles.sort(),
       lines,
-      checked: fresh.length + orphans.length,
+      checked: toCheck.length + orphans.length,
+      ignored: ignoredCount,
+      ignoreReason,
     };
   } finally {
     rmSync(tempRoot, { recursive: true, force: true });

package/src/lib/git-ignore.ts

@@ -0,0 +1,159 @@
+// "Does this project deliberately not commit these files?" — asked of git, once.
+//
+// `check-ignore` is the only reliable answer. Parsing `.gitignore` by hand would have
+// to reimplement precedence, negation and nested ignore files, and the traps are
+// exactly the rules a hand-rolled parser gets wrong: a directory pattern (`docs/`)
+// makes a `!` negation inside it unreachable, and a TRACKED file is never reported
+// ignored no matter what pattern matches it.
+//
+// That last property is what makes this usable as an exemption: a page the project
+// has committed is always compared, whatever its `.gitignore` says. So a rule built
+// on this cannot be used to hide a file the project actually tracks.
+//
+// Paths are evaluated BY NAME — a path need not exist on disk for git to answer. That
+// is deliberate and load-bearing for the docs gate: the exemption is computed over
+// the set a fresh run WOULD emit, so the verdict is identical on a developer box
+// where those files are present and on a CI runner where they are not.
+
+import { spawnSync } from "node:child_process";
+import { toPosix } from "./rel-posix.js";
+
+/** Ignored paths, or the reason the question could not be asked. */
+export type GitIgnoreResult =
+  | { readonly ignored: ReadonlySet<string> }
+  | { readonly unavailable: string };
+
+export interface GitIgnoreOptions {
+  /**
+   * Whether a per-user ignore file (`core.excludesFile`) may contribute to the
+   * verdict.
+   *
+   * `false` for anything whose answer must be a property of the REPOSITORY — a gate
+   * that passes on the author's machine and fails in CI because of a personal ignore
+   * file is worse than no gate. Implemented by pointing `core.excludesFile` at a path
+   * that does not exist, which is the only way to neutralise it.
+   *
+   * `true` where the question is genuinely about this machine — "will this file reach
+   * anyone else?" is answered by every rule that applies here, personal ones included.
+   *
+   * Note `.git/info/exclude` is per-clone and CANNOT be neutralised; it is reported
+   * like any other rule, and the caller's count line is what exposes it.
+   */
+  readonly honourGlobalExcludes: boolean;
+}
+
+/** A path that cannot exist, used to neutralise a per-user excludes file. */
+const NO_SUCH_EXCLUDES_FILE = "/dev/null/metaobjects-no-global-excludes";
+
+/**
+ * Ask git which of `rels` are ignored, relative to `dir`.
+ *
+ * Returns `unavailable` — never throws, never guesses — when git is not on PATH or
+ * `dir` is not inside a repository. A caller must decide what that means for it;
+ * silently treating "cannot say" as "nothing is ignored" is a fallback that lies, and
+ * the callers here say so out loud instead.
+ */
+export function gitIgnored(
+  dir: string,
+  rels: readonly string[],
+  opts: GitIgnoreOptions,
+): GitIgnoreResult {
+  if (rels.length === 0) return { ignored: new Set() };
+
+  const gitBin = process.env.META_GEN_GIT ?? "git";
+  const args: string[] = [];
+  if (!opts.honourGlobalExcludes) {
+    args.push("-c", `core.excludesFile=${NO_SUCH_EXCLUDES_FILE}`);
+  }
+  args.push("-C", dir, "check-ignore", "--stdin", "-z");
+
+  // Forward slashes: git speaks them on every platform, and `listFiles` hands us
+  // platform separators.
+  const input = rels.map(toPosix).join("\0");
+
+  let res;
+  try {
+    res = spawnSync(gitBin, args, { encoding: "utf-8", input });
+  } catch (err) {
+    return { unavailable: `git could not be run (${(err as Error).message})` };
+  }
+  if (res.error !== undefined) {
+    return { unavailable: "git is not on PATH" };
+  }
+  // 0 = at least one ignored, 1 = none ignored, anything else = not a repository
+  // (or a git error), which is a different fact from "nothing is ignored".
+  if (res.status === 1) return { ignored: new Set() };
+  if (res.status !== 0) {
+    const stderr = (res.stderr ?? "").split("\n")[0]?.trim();
+    return {
+      unavailable:
+        stderr !== undefined && stderr !== ""
+          ? stderr
+          : `'${dir}' is not inside a git repository`,
+    };
+  }
+
+  const ignored = new Set(
+    (res.stdout ?? "").split("\0").map((p) => p.trim()).filter((p) => p !== ""),
+  );
+  return { ignored };
+}
+
+/**
+ * Single-path convenience: true / false / undefined when git cannot say.
+ *
+ * `honourGlobalExcludes` is the caller's decision — see the option's doc.
+ */
+export function isGitIgnored(
+  dir: string,
+  rel: string,
+  opts: GitIgnoreOptions,
+): boolean | undefined {
+  const res = gitIgnored(dir, [rel], opts);
+  if ("unavailable" in res) return undefined;
+  return res.ignored.has(toPosix(rel));
+}
+
+/**
+ * WHICH rule ignores `rel` — the `.gitignore` file, its line, and the pattern.
+ *
+ * Advisories that tell an adopter to fix an ignore rule have to name the rule that is
+ * actually in force, not a conventional location. The exclusion can live in ANY
+ * `.gitignore` up the tree, in `.git/info/exclude`, or in a per-user excludes file, and an
+ * advisory that assumes one of them sends the reader to edit a file that does not hold the
+ * rule — after which the same advisory prints again, unchanged. `git check-ignore -v`
+ * answers it exactly, so nothing has to be assumed.
+ *
+ * `undefined` when git cannot say or nothing matches. The verdict itself still comes from
+ * `isGitIgnored`; this is only for the message, so a failure here degrades the wording
+ * rather than the check.
+ */
+export function gitIgnoreSource(
+  dir: string,
+  rel: string,
+  opts: GitIgnoreOptions,
+): { file: string; line: string; pattern: string } | undefined {
+  const gitBin = process.env.META_GEN_GIT ?? "git";
+  const args: string[] = [];
+  if (!opts.honourGlobalExcludes) {
+    args.push("-c", `core.excludesFile=${NO_SUCH_EXCLUDES_FILE}`);
+  }
+  args.push("-C", dir, "check-ignore", "-v", "--", toPosix(rel));
+
+  let res;
+  try {
+    res = spawnSync(gitBin, args, { encoding: "utf-8" });
+  } catch {
+    return undefined;
+  }
+  if (res.error !== undefined || res.status !== 0) return undefined;
+  // `<source>:<line>:<pattern>\t<path>` — the source may itself contain a colon on
+  // Windows, so split from the RIGHT of the first tab-delimited field.
+  const first = (res.stdout ?? "").split("\n")[0];
+  if (first === undefined || first === "") return undefined;
+  const lhs = first.split("\t")[0];
+  if (lhs === undefined) return undefined;
+  const m = /^(.*):(\d+):(.*)$/.exec(lhs);
+  if (m === null) return undefined;
+  return { file: m[1]!, line: m[2]!, pattern: m[3]! };
+}

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

@@ -0,0 +1,78 @@
+// Advisory: did the scaffold land in a directory this repository ignores?
+//
+// `meta init` reports "(11 files)". Eight of them go under `.claude/skills/`, and many
+// projects git-ignore `.claude/` — commonly under a comment about credentials, which is a
+// defensible convention, not a mistake. Ignored, those files exist only on the machine that
+// ran the command: never committed, absent from CI and from a fresh clone, invisible to a
+// teammate — while `.metaobjects/.agent-context.json`, which IS committed, records every one
+// of them. The count says eleven; the repository gets three.
+//
+// The failure is INVISIBLE, which is why it is worth a check rather than a doc: nothing
+// errors, nothing looks wrong, and the whole downstream agent-context design is simply void
+// for that repo.
+//
+// Deliberately ADVISORY. Ignoring `.claude/` may be exactly what the project wants — it is a
+// per-repo policy call, and a scaffolder has no standing to fail a build over it.
+
+import { isAbsolute, relative } from "node:path";
+import { log } from "./log.js";
+import { gitIgnored } from "./git-ignore.js";
+import { toPosix } from "./rel-posix.js";
+
+/**
+ * `meta init` records what it created as paths RELATIVE TO THE PROJECT, and one of them
+ * carries a display decoration ("CLAUDE.md (created with MetaObjects @import)") because the
+ * same array is printed back to the user. Normalize both into a plain project-relative,
+ * POSIX-separated path, and drop anything outside the project.
+ *
+ * The relative case is why this exists at all: `relative(cwd, p)` resolves BOTH arguments
+ * against the ambient `process.cwd()`, so handing it an already-relative path under `--cwd`
+ * produced a "../"-prefixed result for every entry, the filter dropped them all, and the
+ * advisory returned before consulting git. It fired only when the process happened to be
+ * running in the project directory — silent on the path the check exists for.
+ */
+function toProjectRelative(cwd: string, p: string): string | undefined {
+  // Strip a trailing display decoration; handed to git verbatim it is not a path, so a
+  // repository ignoring that file was never told about it.
+  const bare = p.replace(/\s+\(.*\)$/, "");
+  const rel = toPosix(isAbsolute(bare) ? relative(cwd, bare) : bare);
+  if (rel.length === 0 || rel === ".." || rel.startsWith("../")) return undefined;
+  return rel;
+}
+
+/**
+ * Warn when some of the scaffolded paths are git-ignored, naming how many and where.
+ *
+ * Silent when: nothing is ignored, the project is not a git repository, or git cannot be
+ * consulted — "cannot say" must never be reported as "there is a problem".
+ *
+ * `honourGlobalExcludes: false` for the same reason the docs-drift gate uses it: this is a
+ * property of the REPOSITORY, and a personal `~/.gitignore` is not something a teammate
+ * shares. A warning that fires for one developer and not another is worse than none.
+ */
+export function reportIgnoredScaffold(cwd: string, created: readonly string[]): void {
+  const rels = created
+    .map((p) => toProjectRelative(cwd, p))
+    .filter((p): p is string => p !== undefined);
+  if (rels.length === 0) return;
+
+  const res = gitIgnored(cwd, rels, { honourGlobalExcludes: false });
+  if ("unavailable" in res) return;   // not a git repo, or git could not answer
+  const ignored = rels.filter((p) => res.ignored.has(p));
+  if (ignored.length === 0) return;
+
+  // Report the DIRECTORIES rather than every path: an adopter fixes this by editing one
+  // `.gitignore` line, and a wall of forty filenames buries that.
+  const dirs = [...new Set(ignored.map((p) => {
+    const i = p.indexOf("/");
+    return i < 0 ? p : p.slice(0, i) + "/";
+  }))].sort();
+
+  log.warn(
+    `${ignored.length} of ${rels.length} scaffolded file(s) are git-ignored (${dirs.join(", ")}), ` +
+      "so they exist only on this machine — not committed, absent from CI and from a fresh " +
+      "clone, invisible to a teammate — while .metaobjects/.agent-context.json is committed " +
+      "and records them. If the agent context is meant to be shared, un-ignore those paths; " +
+      "if it is deliberately local, nothing to do.",
+  );
+}

package/src/lib/load-error.ts

@@ -0,0 +1,89 @@
+import type { LoaderError } from "@metaobjectsdev/metadata";
+
+/**
+ * One rendering of a metadata LOAD failure, for every command that can hit one.
+ *
+ * The loader builds a full ADR-0009 envelope — a stable `code`, the `files` the node came
+ * from, the `jsonPath` inside the document, and often `suggestions[]` naming the next step.
+ * Five commands then printed `` `failed to load metadata: ${err.message}` `` and threw all
+ * of it away. So `ERR_ABSTRACT_SUBTYPE_AUTHORED` reached an adopter as a paragraph with no
+ * file, no line, no node name and no code — and `--format json` carried the same bare
+ * string, so a CI job could not key on the code ADR-0009 promises and the docs name. Five
+ * metadata files made that a `grep`; two hundred would not.
+ *
+ * This does not invent provenance. It reports exactly what the error carries and stays
+ * silent about what it does not, so a caller can never read more precision into the line
+ * than the loader actually had.
+ */
+export interface LoadErrorReport {
+  /** The message plus whatever provenance the envelope carried, for a human. */
+  readonly text: string;
+  /** ADR-0009 stable code, when the loader attached one. */
+  readonly code?: string;
+  /** The file(s) the failing node was read from. */
+  readonly files?: readonly string[];
+  /** JSON path of the failing node within its document. */
+  readonly jsonPath?: string;
+  /** The loader's own next steps. Printed verbatim; never paraphrased. */
+  readonly suggestions?: readonly string[];
+}
+
+/** True for a thrown value carrying the loader's ADR-0009 envelope. */
+function isLoaderError(err: unknown): err is LoaderError {
+  return (
+    typeof err === "object" && err !== null
+    && typeof (err as { code?: unknown }).code === "string"
+    && typeof (err as { source?: unknown }).source === "object"
+  );
+}
+
+export function describeLoadError(err: unknown): LoadErrorReport {
+  const message = err instanceof Error ? err.message : String(err);
+  if (!isLoaderError(err)) return { text: message };
+
+  const source = err.source as { files?: readonly string[]; jsonPath?: string };
+  const files = source.files?.filter((f) => f.length > 0);
+  const jsonPath = source.jsonPath;
+  const suggestions = err.suggestions?.filter((s) => s.length > 0);
+
+  // `code` first: it is the one part a machine keys on, and a human scanning a terminal
+  // finds it fastest at the front of the line. Then WHERE, which is the question the
+  // message itself can never answer.
+  const where = [
+    files !== undefined && files.length > 0 ? files.join(", ") : undefined,
+    jsonPath !== undefined && jsonPath.length > 0 ? `at ${jsonPath}` : undefined,
+  ].filter((p): p is string => p !== undefined).join(" ");
+
+  const head = `${err.code}: ${message}`;
+  return {
+    text: where.length > 0 ? `${head}\n  in ${where}` : head,
+    code: err.code,
+    ...(files !== undefined && files.length > 0 ? { files } : {}),
+    ...(jsonPath !== undefined && jsonPath.length > 0 ? { jsonPath } : {}),
+    ...(suggestions !== undefined && suggestions.length > 0 ? { suggestions } : {}),
+  };
+}
+
+/**
+ * Print a load failure the one way every command prints it: the described line, then the
+ * loader's own `suggestions[]` indented beneath it, verbatim.
+ *
+ * This lived as a byte-identical private copy in `docs.ts`, `gen.ts` and `migrate.ts`. It
+ * belongs beside `describeLoadError` for the same reason that function exists: the rendering
+ * of a load failure is ONE decision, and three copies of it are three places for the next
+ * improvement to reach two of. `verify.ts`'s variant is deliberately NOT this — it chooses
+ * between the loader's suggestions and its own strict-attr hint (ADR-0023), which is a
+ * different decision, not a different spelling of this one.
+ *
+ * `log` is a parameter rather than an import so a test can capture what was printed without
+ * reaching into module state.
+ */
+export function reportLoadError(
+  log: { error: (msg: string) => void },
+  prefix: string,
+  err: unknown,
+): void {
+  const report = describeLoadError(err);
+  log.error(`${prefix}: ${report.text}`);
+  for (const s of report.suggestions ?? []) log.error(`  ${s}`);
+}