@metaobjectsdev/cli 1.0.12 → 1.1.0

package/src/lib/codegen-drift.ts

@@ -42,11 +42,19 @@ import { join, relative, resolve, isAbsolute } from "node:path";
 import {
   runGen,
   contentHash,
+  DOCS_TARGET_NAME,
   readGeneratedHash,
   listGeneratedPaths,
+  orphanVerdict,
   NAMES_FILE_SUFFIX,
+  generatorRegistry,
+  normalizeConfig,
+  stableGeneratorName,
 } from "@metaobjectsdev/codegen-ts";
-import type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
+import type { MetaobjectsGenConfig, RunGenOpts } from "@metaobjectsdev/codegen-ts";
+import { DEFAULT_TARGET_NAME } from "@metaobjectsdev/codegen-ts/engine";
+import { gitIgnored } from "./git-ignore.js";
+import { toPosix } from "./rel-posix.js";
 import type { MetaData } from "@metaobjectsdev/metadata";
 
 /** Per-target config as carried on MetaobjectsGenConfig (TargetConfig isn't
@@ -68,6 +76,12 @@ export interface CodegenDriftResult {
    * to end. Two doors asking one question must not answer it twice.
    */
   handEditedNames: string[];
+  /**
+   * The subset of `driftedFiles` that no generator emits any more AND that was edited
+   * since `meta gen` wrote it, sorted. `meta gen` deletes an untouched orphan but refuses
+   * one of these, so prescribing it would loop: the remedy is to delete the file.
+   */
+  editedOrphans: string[];
   /**
    * Project-relative paths of generated files that carry a PRESERVED hand edit, sorted:
    * the generated contribution is current (a fresh regen hashes to what we recorded
@@ -78,10 +92,43 @@ export interface CodegenDriftResult {
    * Never overlaps `driftedFiles`.
    */
   handEdited: string[];
+  /**
+   * Generated documentation pages the repository git-ignores, and so did not check. Only
+   * the directories documentation generators write to are asked: a project that generates
+   * many pages and commits a few on purpose is checked on the few it chose. Reported on
+   * the pass and the fail line so a gate that checked two of 589 pages cannot read as one
+   * that checked them all.
+   */
+  docsIgnored: number;
+  /**
+   * Documentation directories, project-relative, whose every freshly generated page the
+   * repository git-ignores. Not compared at all: a project that generates its documentation
+   * without committing it passes, as it did when 1.0's `verify --codegen` never looked at
+   * documentation.
+   */
+  docsIgnoredDirs: string[];
+  /** Why git could not be asked which pages are ignored (every page was then checked). */
+  docsIgnoreUnavailable?: string;
   /** Set when the gate could not run (e.g. no outDir to compare against). */
   error?: string;
 }
 
+/**
+ * The output directories a documentation generator writes to, absolute. A generator is
+ * documentation when its registry row's layer is `docs`; an owned copy keeps its packaged
+ * name, so it is recognised too.
+ */
+function docsOutDirs(config: MetaobjectsGenConfig, projectRoot: string): Set<string> {
+  const dirs = new Set<string>();
+  for (const g of normalizeConfig(config).generators) {
+    if (generatorRegistry[stableGeneratorName(g, generatorRegistry)]?.layer !== "docs") continue;
+    const target = g.target ?? DOCS_TARGET_NAME;
+    const outDir = target === DEFAULT_TARGET_NAME ? config.outDir : config.targets?.[target]?.outDir;
+    if (outDir !== undefined && outDir.length > 0) dirs.add(resolve(projectRoot, outDir));
+  }
+  return dirs;
+}
+
 /** Collect the committed outDirs declared by the config (default + per-target),
  *  resolved against `projectRoot` — a relative outDir (the common, portable,
  *  `meta init`-scaffolded shape) must resolve against the project the CLI's
@@ -127,12 +174,20 @@ function listFiles(dir: string): string[] {
  *   never committed because the `meta gen` that produced the committed tree
  *   never emitted it either. Undefined ⇒ everything is in scope (byte-identical
  *   to a project with no `scope` declared).
+ * @param sourceFiles the collection's OWN source files, the same list `meta gen`
+ *   threads onto `ctx.sourceFiles`. `shared-model` loads them standalone to build its
+ *   artifact, so without them the regen asked it to publish nothing and this gate
+ *   failed with "no source files to load" on every project that wires it.
+ * @param run what `meta gen` also hands the run and this regen must hand it the same way:
+ *   the source directories (the docs site loads them) and the agent pages' schema builder.
  */
 export async function computeCodegenDrift(
   config: MetaobjectsGenConfig,
   metadata: MetaData,
   projectRoot: string,
   scope?: (fqn: string) => boolean,
+  sourceFiles?: readonly string[],
+  run?: Pick<RunGenOpts, "sourceRoots" | "agentSchema">,
 ): Promise<CodegenDriftResult> {
   const root = isAbsolute(projectRoot) ? projectRoot : resolve(projectRoot);
 
@@ -148,7 +203,10 @@ export async function computeCodegenDrift(
       driftedFiles: [],
       lines: [],
       handEditedNames: [],
+      editedOrphans: [],
       handEdited: [],
+      docsIgnored: 0,
+      docsIgnoredDirs: [],
       error:
         "verify --codegen: no outDir configured — cannot locate the committed " +
         "generated output to diff against. Set 'outDir' (and/or per-target " +
@@ -204,35 +262,75 @@ export async function computeCodegenDrift(
     // Generate fresh into the temp tree. "overwrite" + "fresh" + a temp
     // gen-state dir guarantees every file is written (no merge/skip), so the
     // temp tree is the canonical "what gen would produce right now".
-    await runGen({
+    const regen = await runGen({
       config: tempConfig,
       metadata,
       projectRoot: tempRoot,
       genStateDir: join(tempRoot, ".gen-state"),
       mergeStrategy: "overwrite",
       baseline: "fresh",
+      // The real project, for a generator that reads its files (`ctx.inputRoot`):
+      // `shared-model` takes its default version from the nearest package.json, and an
+      // owned generator may read anything. `projectRoot` stays the temp tree, which the
+      // owned route and entity generators compute their adapter import against.
+      inputRoot: root,
       ...(scope !== undefined ? { scope } : {}),
+      ...(sourceFiles !== undefined ? { sourceFiles } : {}),
+      ...(run?.sourceRoots !== undefined ? { sourceRoots: run.sourceRoots } : {}),
+      ...(run?.agentSchema !== undefined ? { agentSchema: run.agentSchema } : {}),
     });
 
+    // Where gen discards hand edits instead of keeping them (handEdits: "overwrite").
+    const overwrite = regen.handEditsOverwrite;
+
     // Diff each committed outDir against its temp mirror.
     const driftedFiles = new Set<string>();
     const lines: string[] = [];
     const handEditedNames = new Set<string>();
     const handEdited = new Set<string>();
+    const editedOrphans = new Set<string>();
 
     // Whether we have any record of what we wrote here. With records, the orphan
     // branch below can scope itself to our own output; with none, it cannot tell
     // our stale output from a stranger's file, so the old verdict stands.
     const haveWriteRecords = listGeneratedPaths(projectGenStateDir).length > 0;
+    const docsDirs = docsOutDirs(config, root);
+    let docsIgnored = 0;
+    const docsIgnoredDirs: string[] = [];
+    let docsIgnoreUnavailable: string | undefined;
     for (const committed of committedDirs) {
       const fresh = tempFor(committed);
       const committedFiles = new Set(listFiles(committed));
       const freshFiles = new Set(listFiles(fresh));
       const all = new Set([...committedFiles, ...freshFiles]);
+
+      // Documentation the project git-ignores is not checked (carried from 1.0's
+      // `verify --docs`). Asked of the FRESH set by name, present on disk or not, so the
+      // verdict is a property of the repository and not of the machine: a box that ran
+      // `meta gen` has every page on disk and a CI runner has the committed few. A TRACKED
+      // page is never reported ignored by git, so a committed page is always compared.
+      // honourGlobalExcludes: false — a personal ignore file must not change a gate.
+      let ignored: ReadonlySet<string> = new Set<string>();
+      if (docsDirs.has(committed) && all.size > 0) {
+        const prefix = toPosix(relative(root, committed));
+        const fromRoot = (rel: string): string => (prefix === "" ? toPosix(rel) : `${prefix}/${toPosix(rel)}`);
+        const lookup = gitIgnored(root, [...all].map(fromRoot), { honourGlobalExcludes: false });
+        if ("ignored" in lookup) ignored = new Set([...all].map(toPosix).filter((rel) => lookup.ignored.has(fromRoot(rel))));
+        else docsIgnoreUnavailable = lookup.unavailable;
+        const checked = [...freshFiles].filter((rel) => !ignored.has(toPosix(rel)));
+        if (freshFiles.size > 0 && checked.length === 0) {
+          docsIgnoredDirs.push(relative(root, committed) || ".");
+          continue;
+        }
+      }
       for (const rel of [...all].sort()) {
         const relKey = relative(root, join(committed, rel));
         const inCommitted = committedFiles.has(rel);
         const inFresh = freshFiles.has(rel);
+        if (ignored.has(toPosix(rel))) {
+          docsIgnored++;
+          continue;
+        }
         if (inCommitted && !inFresh) {
           // JURISDICTION, not staleness. A regen not emitting a path means
           // "stale generated output" only for a path we have ever WRITTEN; for
@@ -247,8 +345,33 @@ export async function computeCodegenDrift(
           if (haveWriteRecords && readGeneratedHash(projectGenStateDir, relKey) === undefined) {
             continue;
           }
+          const verdict = haveWriteRecords
+            ? orphanVerdict(regen.orphanSweepJobs ?? [], tempRoot, relative(tempRoot, join(fresh, rel)))
+            : undefined;
+          if (verdict?.kept === true) continue;
           driftedFiles.add(relKey);
-          lines.push(`- ${relKey} (committed but regen would not emit it)`);
+          // `meta gen` deletes an orphan it can prove untouched and REFUSES one edited
+          // since it was written, so the remedy differs by which this is. Asked of the
+          // same evidence the sweep asks (the recorded hash), so the two cannot disagree.
+          // With no write records at all, neither verdict can be proven, so the line
+          // stays the plain one.
+          if (!haveWriteRecords) {
+            lines.push(`- ${relKey} (committed but regen would not emit it)`);
+          } else if (readGeneratedHash(projectGenStateDir, relKey) === contentHash(readFileSync(join(committed, rel), "utf8"))) {
+            lines.push(`- ${relKey} (committed but regen would not emit it; 'meta gen' deletes it)`);
+          } else if (verdict?.force === true) {
+            // The sweep force-deletes an edited orphan here, so gen deletes it.
+            lines.push(
+              `- ${relKey} (no generator emits it any more, and it was edited by hand; ` +
+                `a force or handEdits: "overwrite" orphan policy owns it, so 'meta gen' deletes it)`,
+            );
+          } else {
+            editedOrphans.add(relKey);
+            lines.push(
+              `- ${relKey} (no generator emits it any more, and it was edited by hand: ` +
+                `delete it, or move your edits into a file of your own and then delete it)`,
+            );
+          }
         } else if (!inCommitted && inFresh) {
           driftedFiles.add(relKey);
           lines.push(`+ ${relKey} (regen would emit it; not committed — run 'meta gen')`);
@@ -298,6 +421,14 @@ export async function computeCodegenDrift(
               // nothing is proven, so the old byte verdict stands.
               driftedFiles.add(relKey);
               lines.push(`~ ${relKey} (committed content differs from a fresh regen)`);
+            } else if (overwrite?.paths.has(join(fresh, rel)) === true) {
+              // Its generator says handEdits: "overwrite": `meta gen` replaces the edit
+              // with fresh output, so it is drift that gen fixes, not a kept edit.
+              driftedFiles.add(relKey);
+              lines.push(
+                `~ ${relKey} (edited by hand; its generator sets handEdits: "overwrite", so ` +
+                  `'meta gen' replaces it with fresh output)`,
+              );
             } else {
               // The generated contribution is current and the bytes still differ: a
               // hand edit `meta gen` preserved. Not drift, but never silent either.
@@ -314,7 +445,11 @@ export async function computeCodegenDrift(
       driftedFiles: sorted,
       lines,
       handEditedNames: [...handEditedNames].sort(),
+      editedOrphans: [...editedOrphans].sort(),
       handEdited: [...handEdited].sort(),
+      docsIgnored,
+      docsIgnoredDirs,
+      ...(docsIgnoreUnavailable !== undefined ? { docsIgnoreUnavailable } : {}),
     };
   } finally {
     rmSync(tempRoot, { recursive: true, force: true });

package/src/lib/collection-load-options.ts

@@ -26,7 +26,7 @@ import type { Collection, LoadMemoryOptions } from "@metaobjectsdev/sdk";
  */
 export function collectionLoadOptions(
   collection: Collection,
-): Required<Pick<LoadMemoryOptions, "files" | "fileIds" | "importedPackages" | "importedNodes" | "libraries">> {
+): Required<Pick<LoadMemoryOptions, "files" | "fileIds" | "importedPackages" | "importedNodes" | "libraries" | "physicalNaming">> {
   return {
     files: collection.files,
     fileIds: collection.fileIds,
@@ -38,5 +38,6 @@ export function collectionLoadOptions(
     // threaded by `loadMemoryOptionsFrom`, a SECOND helper, and #333 is on record as the
     // bug where one of the two reached every command and the other reached none.
     libraries: collection.libraries,
+    physicalNaming: collection.physicalNaming,
   };
 }

package/src/lib/config.ts

@@ -83,16 +83,18 @@ async function tryLoadConfig(metaRoot: string): Promise<Config | undefined> {
 // ---------------------------------------------------------------------------
 
 /**
- * The migrations directory and dialect `meta migrate` would use with no flags — what
- * `meta gen` needs to word its "now migrate" next step and find the committed snapshot.
+ * The migrations directory, dialect and format `meta migrate` would use with no flags — what
+ * `meta gen` needs to word its "now migrate" next step and read the committed snapshot the
+ * way `meta migrate` reads it.
  */
 export async function resolveMigrateDefaults(
   metaRoot: string,
-): Promise<{ outDir: string; dialect: Dialect | undefined }> {
+): Promise<{ outDir: string; dialect: Dialect | undefined; format: MigrateFormat }> {
   const config = await tryLoadConfig(metaRoot);
   return {
     outDir: config?.migrate?.outDir ?? MIGRATE_DEFAULTS.outDir,
     dialect: config?.migrate?.dialect ?? MIGRATE_DEFAULTS.dialect,
+    format: config?.migrate?.format ?? MIGRATE_DEFAULTS.format,
   };
 }
 

package/src/lib/decimal-precision-advisory.ts

@@ -0,0 +1,50 @@
+// ADR-0019 Amendment 1, W4 — the SQLite and D1 tier has no decimal type. A text value with
+// NUMERIC affinity is stored as an INTEGER or REAL, keeping only its first 15 significant
+// digits, so a `field.decimal` declaring `@precision` above 15 is stored lossily.
+// Advisory, never a gate: `meta migrate` warns once per field, on those dialects only.
+
+import {
+  FIELD_ATTR_PRECISION,
+  FIELD_SUBTYPE_DECIMAL,
+  OBJECT_SUBTYPE_ENTITY,
+  TYPE_FIELD,
+  TYPE_OBJECT,
+  type MetaData,
+} from "@metaobjectsdev/metadata";
+
+/** Significant digits a SQLite or D1 NUMERIC column keeps exactly. */
+export const SQLITE_DECIMAL_EXACT_DIGITS = 15;
+
+const LOSSY_DECIMAL_DIALECTS: readonly string[] = ["sqlite", "d1"];
+
+export interface DecimalPrecisionOptions {
+  /** Skip an entity by FQN — imported (dependency) metadata is not the adopter's to fix. */
+  skip?: (fqn: string) => boolean;
+}
+
+/** One message per `field.decimal` with `@precision` above 15, or [] on any other dialect. */
+export function decimalPrecisionWarnings(
+  root: MetaData,
+  dialect: string,
+  opts: DecimalPrecisionOptions = {},
+): string[] {
+  if (!LOSSY_DECIMAL_DIALECTS.includes(dialect)) return [];
+  const out: string[] = [];
+  for (const obj of root.children()) {
+    if (obj.type !== TYPE_OBJECT || obj.subType !== OBJECT_SUBTYPE_ENTITY || obj.isAbstract) continue;
+    const fqn = obj.resolutionKey();
+    if (opts.skip?.(fqn) === true) continue;
+    // ADR-0039: resolving — fields (and their @precision) inherited via extends count.
+    for (const f of obj.children()) {
+      if (f.type !== TYPE_FIELD || f.subType !== FIELD_SUBTYPE_DECIMAL) continue;
+      const precision = f.attr(FIELD_ATTR_PRECISION);
+      if (typeof precision !== "number" || precision <= SQLITE_DECIMAL_EXACT_DIGITS) continue;
+      out.push(
+        `${fqn}.${f.name} is a decimal with @precision ${precision}, but ${dialect} keeps only ` +
+          `${SQLITE_DECIMAL_EXACT_DIGITS} significant digits of a decimal (it stores NUMERIC as an integer or ` +
+          `a double). Digits beyond the ${SQLITE_DECIMAL_EXACT_DIGITS}th are lost; use Postgres for exact wide decimals.`,
+      );
+    }
+  }
+  return out;
+}

package/src/lib/deprecation-lint.ts

@@ -50,6 +50,7 @@ import {
   ORIGIN_AGGREGATE_ATTR_OF,
   isMetaObject,
   resolveObjectRef,
+  refTarget,
   type MetaData,
   type MetaObject,
 } from "@metaobjectsdev/metadata";
@@ -166,12 +167,11 @@ function findHop(entity: MetaObject, hopName: string): MetaData | undefined {
   );
 }
 
-/** The entity a resolved hop (relationship or identity.reference) points at, raw. */
-function hopTargetRef(hop: MetaData): string | undefined {
-  const v = hop.type === TYPE_RELATIONSHIP
-    ? hop.attr(RELATIONSHIP_ATTR_OBJECT_REF)
-    : hop.attr(IDENTITY_REFERENCE_ATTR_REFERENCES);
-  return typeof v === "string" && v !== "" ? headOf(v) : undefined;
+/** The entity a resolved hop (relationship or identity.reference) points at, as the
+ *  loader bound it (ADR-0059 R7: resolved where the hop's reference was declared). */
+function hopTarget(hop: MetaData): MetaObject | undefined {
+  const target = refTarget(hop, hop.type === TYPE_RELATIONSHIP ? RELATIONSHIP_ATTR_OBJECT_REF : IDENTITY_REFERENCE_ATTR_REFERENCES);
+  return target !== undefined && isMetaObject(target) ? target : undefined;
 }
 
 /**
@@ -187,18 +187,15 @@ function hopTargetRef(hop: MetaData): string | undefined {
  * directory takes.
  */
 function checkEntityFieldPath(
-  root: MetaData,
   referrer: MetaData,
   referrerPath: string,
   verb: string,
   raw: string,
-  referrerPkg: string,
+  entity: MetaObject | undefined,
   out: Diagnostic[],
 ): void {
-  const head = headOf(raw);
-  const entity = resolveEntityRef(root, head, referrerPkg);
   if (entity === undefined) return;
-  const fieldName = raw.slice(head.length + 1);
+  const fieldName = raw.slice(headOf(raw).length + 1);
   const field = fieldName !== "" ? entity.fields().find((f) => f.name === fieldName) : undefined;
   if (field !== undefined && considerTarget(referrer, referrerPath, verb, field, out)) {
     return; // the field itself is the deprecated thing — don't ALSO warn about its (fine) entity.
@@ -232,9 +229,7 @@ function checkViaPath(
     const hop = findHop(current, hopName);
     if (hop === undefined) return;
     considerTarget(origin, referrerPath, verb, hop, out);
-    const targetRef = hopTargetRef(hop);
-    if (targetRef === undefined) return;
-    const next = resolveEntityRef(root, targetRef, packageOf(current));
+    const next = hopTarget(hop);
     if (next === undefined) return;
     considerTarget(origin, referrerPath, verb, next, out);
     current = next;
@@ -252,11 +247,11 @@ function checkOrigin(root: MetaData, origin: MetaData, referrerPath: string, out
   // same stance every origin accessor in meta-origin.ts takes).
   const from = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_FROM);
   if (typeof from === "string" && from !== "") {
-    checkEntityFieldPath(root, origin, referrerPath, `${subtypeLabel} @from references`, from, referrerPkg, out);
+    checkEntityFieldPath(origin, referrerPath, `${subtypeLabel} @from references`, from, resolveEntityRef(root, headOf(from), referrerPkg), out);
   }
   const of_ = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_OF);
   if (typeof of_ === "string" && of_ !== "") {
-    checkEntityFieldPath(root, origin, referrerPath, `${subtypeLabel} @of references`, of_, referrerPkg, out);
+    checkEntityFieldPath(origin, referrerPath, `${subtypeLabel} @of references`, of_, resolveEntityRef(root, headOf(of_), referrerPkg), out);
   }
   const via = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_VIA);
   if (typeof via === "string" && via !== "") {
@@ -273,12 +268,9 @@ function checkNode(root: MetaData, node: MetaData, path: string, out: Diagnostic
   // @objectRef — relationship.* (its target object) and field.object/value (a
   // value-typed field's own objectRef). Same attr name on both (naming-refs.ts).
   if (node.type === TYPE_RELATIONSHIP || node.type === TYPE_FIELD) {
-    const ref = node.attr(node.type === TYPE_RELATIONSHIP ? RELATIONSHIP_ATTR_OBJECT_REF : FIELD_ATTR_OBJECT_REF);
-    if (typeof ref === "string" && ref !== "") {
-      const owner = owningObject(node);
-      const target = resolveEntityRef(root, ref, owner !== undefined ? packageOf(owner) : "");
-      if (target !== undefined) considerTarget(node, path, "references (@objectRef)", target, out);
-    }
+    // ADR-0059 R7: the target the loader bound, resolved where @objectRef was declared.
+    const target = refTarget(node, node.type === TYPE_RELATIONSHIP ? RELATIONSHIP_ATTR_OBJECT_REF : FIELD_ATTR_OBJECT_REF);
+    if (target !== undefined && isMetaObject(target)) considerTarget(node, path, "references (@objectRef)", target, out);
   }
 
   // @references — identity.reference's FK target. May be bare ("Entity",
@@ -290,8 +282,8 @@ function checkNode(root: MetaData, node: MetaData, path: string, out: Diagnostic
   if (node.type === TYPE_IDENTITY && node.subType === IDENTITY_SUBTYPE_REFERENCE) {
     const raw = node.attr(IDENTITY_REFERENCE_ATTR_REFERENCES);
     if (typeof raw === "string" && raw !== "") {
-      const owner = owningObject(node);
-      checkEntityFieldPath(root, node, path, "references (@references)", raw, owner !== undefined ? packageOf(owner) : "", out);
+      const target = refTarget(node, IDENTITY_REFERENCE_ATTR_REFERENCES);
+      checkEntityFieldPath(node, path, "references (@references)", raw, target !== undefined && isMetaObject(target) ? target : undefined, out);
     }
   }
 

package/src/lib/docs-removed.ts

@@ -0,0 +1,41 @@
+// ADR-0034 Amendment 9 — one way to generate. Documentation is written by generators the
+// project lists in `generators`, and `meta gen` runs them. The docs command, `meta verify
+// --docs` and the `docs` config block are gone, and each says so in the amendment's fixed
+// words, pointing at the migration section an agent can apply by hand.
+import { guideUrl } from "@metaobjectsdev/metadata/release-docs";
+
+/** The migration guide every message below points at, and the section for this port. */
+export const DOCS_MIGRATION_GUIDE = guideUrl("docs/features/migrations/docs-are-generators.md");
+const SECTION = `section "TypeScript"`;
+/** Where a TypeScript project declares a docs generator. */
+const WHERE = "in `generators` in metaobjects.config.ts";
+
+/** What `meta docs` prints before it exits 2. */
+export const REMOVED_DOCS_COMMAND =
+  "`meta docs` was removed in 1.1.0. `meta gen` writes documentation now: declare each docs " +
+  `generator ${WHERE}. See ${DOCS_MIGRATION_GUIDE}, ${SECTION}.`;
+
+/** What `meta verify --docs` prints before it exits 2. */
+export const REMOVED_VERIFY_DOCS =
+  "`meta verify --docs` was removed in 1.1.0. `meta verify --codegen` checks documentation now, " +
+  `with everything else \`generators\` declares. See ${DOCS_MIGRATION_GUIDE}, ${SECTION}.`;
+
+/** What a gen run prints, and fails on, when there is no config to read the list from. */
+export const NO_CONFIG_MESSAGE =
+  "meta gen: no metaobjects.config.ts. Nothing is generated until a config declares it, " +
+  "documentation included; `meta init` writes one. A 1.0 project that ran `meta docs` with no " +
+  `config: see ${DOCS_MIGRATION_GUIDE}, ${SECTION}.`;
+
+/** True when a loaded config still carries the 1.0 `docs` block. */
+export function hasLegacyDocsBlock(config: object): boolean {
+  return Object.hasOwn(config, "docs");
+}
+
+/** What `command` prints, and fails on, before it writes anything, for a 1.0 `docs` block. */
+export function legacyDocsConfigMessage(command: string): string {
+  return (
+    `${command}: found 1.0 docs configuration (the docs block in metaobjects.config.ts). ` +
+    "Nothing reads it any more, so this run would write no documentation. Declare each docs " +
+    `generator ${WHERE}. See ${DOCS_MIGRATION_GUIDE}, ${SECTION}.`
+  );
+}

package/src/lib/docs-site-eject.ts

@@ -0,0 +1,48 @@
+// `meta eject docs-site` (ADR-0034 Amendment 9): copy the HTML site's templates and assets
+// into `codegen/docs-site/{templates,assets}`, where `docsSiteFile()` reads them in place of
+// the bundled ones. The site's BUILDER stays packaged (it assembles the page data the
+// templates read; Amendment 8 ruling 3); what an adopter changes is the look, and that is
+// these files. It was `meta docs --scaffold-site` until 1.1.0, and writes the same files to
+// the same place.
+
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { OWNED_DOCS_SITE_DIR } from "@metaobjectsdev/codegen-ts";
+import { readSiteFile, SITE_ASSET_NAMES, SITE_TEMPLATE_NAMES } from "@metaobjectsdev/docs-site";
+
+/** The name `meta eject` takes for the site theme. A catalog entry, but not a generator copy. */
+export const DOCS_SITE_NAME = "docs-site";
+
+export interface DocsSiteFileResult {
+  /** Project-relative path. */
+  path: string;
+  status: "created" | "preserved" | "replaced";
+}
+
+/**
+ * Write each template and asset that is missing. A file already there is kept unless
+ * `force`: a re-run never clobbers a theme the adopter has edited.
+ */
+export async function ejectDocsSite(projectRoot: string, force: boolean): Promise<DocsSiteFileResult[]> {
+  const out: DocsSiteFileResult[] = [];
+  const sets: Array<{ dir: string; names: readonly string[]; kind: "template" | "asset" }> = [
+    { dir: `${OWNED_DOCS_SITE_DIR}/templates`, names: SITE_TEMPLATE_NAMES, kind: "template" },
+    { dir: `${OWNED_DOCS_SITE_DIR}/assets`, names: SITE_ASSET_NAMES, kind: "asset" },
+  ];
+  for (const { dir, names, kind } of sets) {
+    await mkdir(join(projectRoot, dir), { recursive: true });
+    for (const name of names) {
+      const path = `${dir}/${name}`;
+      const abs = join(projectRoot, path);
+      const existed = existsSync(abs);
+      if (existed && !force) {
+        out.push({ path, status: "preserved" });
+        continue;
+      }
+      await writeFile(abs, readSiteFile(kind, name), "utf8");
+      out.push({ path, status: existed ? "replaced" : "created" });
+    }
+  }
+  return out;
+}

package/src/lib/field-lint.ts

@@ -0,0 +1,122 @@
+// `meta verify` — the field AUTHORING lint.
+//
+// Two metadata mistakes about an object's FIELDS load with no error on every port:
+//
+//   1. An `identity.reference` whose `@fields` names a field the object does not have.
+//      The loader resolves `@references` (the target) and never looks at `@fields`, so a
+//      typo there produces a foreign key over a column nothing declares.
+//   2. Two `field.*` children with the same `name` in one object's `children` list. The
+//      later declaration is folded into the first, and one of a different subtype is
+//      dropped, both silently.
+//
+// WHY THESE ARE WARNINGS AND NOT LOAD ERRORS. docs/compatibility-policy.md does not allow
+// a new load error for metadata that loads today — name-lint.ts's header has the same
+// ruling for whitespace names. So, like every sibling lint in this directory:
+//
+// EVERY FINDING IS A WARNING, BY CONSTRUCTION. Nothing here reaches the exit code.
+//
+// THE TWO HALVES READ DIFFERENT THINGS, and have to. The reference half reads the LOADED
+// model, because "does this object have that field" is a question about the EFFECTIVE
+// field set — inherited through `extends` and merged from overlay files. The duplicate
+// half reads the RAW DOCUMENTS, because the merge has already erased the duplicate from
+// the model by the time anything can ask (overlay-lint.ts reads files for the same reason).
+//
+// The codes, the message text and the fixtures are shared with the C#, Java and Python
+// CLIs: fixtures/field-lint-conformance/.
+
+import {
+  IDENTITY_ATTR_FIELDS,
+  IDENTITY_SUBTYPE_REFERENCE,
+  TYPE_FIELD,
+  TYPE_IDENTITY,
+  TYPE_OBJECT,
+  type MetaData,
+  type MetaDataSource,
+} from "@metaobjectsdev/metadata";
+import { declaredDuplicateFields, type DeclaredDuplicateField } from "@metaobjectsdev/metadata/core";
+import type { Diagnostic } from "./requirement-check.js";
+
+/** An `identity.reference` lists a field its object does not have. */
+export const WARN_REFERENCE_FIELD_NOT_FOUND = "WARN_REFERENCE_FIELD_NOT_FOUND";
+/** One `children` list declares the same field name more than once. */
+export const WARN_DUPLICATE_FIELD_NAME = "WARN_DUPLICATE_FIELD_NAME";
+
+/** Resolve one metadata file path to the source the duplicate scan reads it through. */
+export type ReadSource = (path: string) => MetaDataSource;
+
+function warn(path: string, code: string, message: string): Diagnostic {
+  return { severity: "warn", code, path, message };
+}
+
+/**
+ * Report every `identity.reference` whose `@fields` names a field its object lacks.
+ * Returns `[]` for a model where every listed field exists.
+ */
+export function lintReferenceFields(root: MetaData): Diagnostic[] {
+  const out: Diagnostic[] = [];
+  // OWN-ONLY (ADR-0039 sanctioned case): a root has no super, and its own children are
+  // the declared objects.
+  for (const object of root.ownChildren()) {
+    if (object.type !== TYPE_OBJECT) continue;
+    const address = object.resolutionKey();
+    // RESOLVING: the effective field set — a field inherited through `extends` or added
+    // by an overlay file is a field the object has.
+    const fields = new Set(object.children().filter((c) => c.type === TYPE_FIELD).map((c) => c.name));
+    // OWN-ONLY (ADR-0039 sanctioned case): report each DECLARATION once, on the object
+    // that declares it. The resolving `children()` would repeat an inherited reference
+    // on every subtype.
+    for (const identity of object.ownChildren()) {
+      if (identity.type !== TYPE_IDENTITY || identity.subType !== IDENTITY_SUBTYPE_REFERENCE) continue;
+      // RESOLVING: `@fields` may itself be inherited through the identity's `extends`.
+      const listed = identity.attr(IDENTITY_ATTR_FIELDS);
+      const names = Array.isArray(listed) ? listed : typeof listed === "string" ? [listed] : [];
+      for (const name of names) {
+        if (typeof name !== "string" || fields.has(name)) continue;
+        out.push(warn(`${address}.${identity.name}`, WARN_REFERENCE_FIELD_NOT_FOUND, referenceFieldMessage(identity.name, name, address)));
+      }
+    }
+  }
+  return out;
+}
+
+function referenceFieldMessage(identity: string, field: string, object: string): string {
+  return (
+    `identity.reference ${JSON.stringify(identity)} lists ${JSON.stringify(field)} in @fields, but ` +
+    `${object} has no field of that name, inherited and overlaid fields included. Nothing checks ` +
+    `this at load, so the reference is built on a field that does not exist. Rename the entry to ` +
+    `an existing field, or declare the field.`
+  );
+}
+
+/** One raw-scan finding as a diagnostic. Exported so the scan and its text are testable
+ *  without a filesystem. */
+export function duplicateFieldDiagnostic(dup: DeclaredDuplicateField): Diagnostic {
+  return warn(
+    `${dup.object}.${dup.field}`,
+    WARN_DUPLICATE_FIELD_NAME,
+    `${dup.object} declares the field ${JSON.stringify(dup.field)} ${dup.count} times in one children ` +
+      `list. Nothing reports this at load, and only the first declaration is certain to take effect. ` +
+      `Remove or rename the duplicate.`,
+  );
+}
+
+/**
+ * Report every field name declared more than once in one object's `children` list,
+ * scanning each of `files` as raw content.
+ *
+ * Unreadable or unparsable files are skipped — the loader reports those itself.
+ */
+export async function lintDuplicateFields(files: readonly string[], readSource: ReadSource): Promise<Diagnostic[]> {
+  const out: Diagnostic[] = [];
+  for (const path of files) {
+    let declared: ReadonlyArray<DeclaredDuplicateField>;
+    try {
+      const source = readSource(path);
+      declared = declaredDuplicateFields(await source.read(), source.format);
+    } catch {
+      continue;
+    }
+    out.push(...declared.map(duplicateFieldDiagnostic));
+  }
+  return out;
+}