@metaobjectsdev/cli 0.24.0 → 0.24.2

package/src/commands/upgrade.ts

@@ -1,6 +1,8 @@
 // server/typescript/packages/cli/src/commands/upgrade.ts
 //
-// `meta upgrade` — rewrite retired vocabulary in this project's metadata.
+// `meta upgrade` — rewrite what the current loader no longer accepts in this project's
+// metadata: RETIRED vocabulary (`retired-vocabulary.ts`) and ATTRIBUTE CONTRADICTIONS —
+// pairs of live attributes that may not sit on one node (`attr-contradictions.ts`).
 //
 // DELIBERATELY NOT `meta migrate`. That command owns DATABASE SCHEMA (ADR-0015) and an
 // adopter reading `migrate` expects DDL. Overloading it with a metadata rewrite would make
@@ -22,8 +24,8 @@ import { resolveCollection } from "@metaobjectsdev/sdk";
 import { rewriteDocument } from "@metaobjectsdev/metadata";
 import { log } from "../lib/log.js";
 
-/** Authoring formats the rewriter cannot edit — see `vocabulary-rewrite.ts` for why. */
-const UNREWRITABLE_EXTENSIONS = new Set([".yaml", ".yml"]);
+/** YAML authoring (ADR-0006). Rewritten by the `yaml`-backed arm, loaded on demand below. */
+const YAML_EXTENSIONS = new Set([".yaml", ".yml"]);
 
 interface UpgradeFlags {
   apply: boolean;
@@ -56,8 +58,11 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
     if ((err as Error).message === "__help__") {
       log.info(
         "meta upgrade [<project>] [--to <version>] [--apply]\n\n" +
-          "  Rewrites retired metadata vocabulary. Previews by default; --apply writes.\n" +
-          "  Retirements needing a human decision are REFUSED and listed with their guide.",
+          "  Rewrites metadata the current loader no longer accepts, in JSON and YAML alike:\n" +
+          "  retired vocabulary, and pairs of live attributes that may no longer sit together.\n" +
+          "  Previews by default; --apply writes.\n" +
+          "  Changes needing a human decision are REFUSED and listed with their guide.\n\n" +
+          "  Exit: 0 clean · 1 refusals remain · 2 bad usage · 3 some files could not be read.",
       );
       return 0;
     }
@@ -78,23 +83,38 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
   let totalChanges = 0;
   let totalRefusals = 0;
   let filesChanged = 0;
-  const skipped: string[] = [];
+  let checked = 0;
+  // Files we could not READ AT ALL. Distinct from "checked and clean" in every report and in
+  // the exit code — conflating them is the whole of #339.
+  const notChecked: string[] = [];
+
+  // The YAML arm carries the `yaml` package, so it lives behind its own subpath and is
+  // loaded only when the estate actually contains YAML. Importing it eagerly would pull a
+  // Node-only dependency into every `meta` invocation.
+  const hasYaml = files.some((f) => YAML_EXTENSIONS.has(extname(f).toLowerCase()));
+  const rewriteYaml = hasYaml
+    ? (await import("@metaobjectsdev/metadata/vocabulary-rewrite-yaml")).rewriteYamlDocument
+    : undefined;
+
+  const opts = flags.maxVersion !== undefined ? { maxVersion: flags.maxVersion } : {};
 
   for (const file of files) {
     const rel = relative(projectRoot, file);
+    const before = await readFile(file, "utf8");
 
-    // A file we cannot rewrite is NAMED, never passed over. Silently skipping it is the
-    // failure this command exists to prevent: the adopter runs the documented migration,
-    // reads "no retired vocabulary found", and ships metadata that does not load.
-    if (UNREWRITABLE_EXTENSIONS.has(extname(file).toLowerCase())) {
-      skipped.push(rel);
-      continue;
+    let r;
+    if (YAML_EXTENSIONS.has(extname(file).toLowerCase())) {
+      const y = rewriteYaml?.(before, opts);
+      // A document that does not parse was not examined, and must never be counted as clean.
+      if (y === undefined || y.unparseable) {
+        notChecked.push(rel);
+        continue;
+      }
+      r = y;
+    } else {
+      r = rewriteDocument(before, opts);
     }
-
-    const before = await readFile(file, "utf8");
-    const r = rewriteDocument(before, {
-      ...(flags.maxVersion !== undefined ? { maxVersion: flags.maxVersion } : {}),
-    });
+    checked++;
     if (r.changes.length === 0 && r.refusals.length === 0) continue;
 
     log.info(`\n${rel}`);
@@ -115,19 +135,23 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
   }
 
   log.info("");
-  if (skipped.length > 0) {
+  if (notChecked.length > 0) {
     log.warn(
-      `${skipped.length} YAML file(s) cannot be rewritten automatically and were NOT ` +
-        `checked — migrate them by hand:\n  ${skipped.join("\n  ")}`,
+      `${notChecked.length} file(s) could not be parsed and were NOT checked — fix these ` +
+        `first, then re-run:\n  ${notChecked.join("\n  ")}`,
     );
   }
 
+  // Every conclusion states how many files it is a conclusion ABOUT. A bare "nothing found"
+  // read on its own says the estate is clean, and it is the last line, so it is the one that
+  // sticks — on the estate that reported this, it was the opposite of the truth.
+  //
+  // It says "nothing to rewrite", not "your metadata loads": this command knows about retired
+  // vocabulary and attribute contradictions, and nothing else. `meta verify` owns the verdict.
+  const scope = `${checked} file(s) checked${notChecked.length > 0 ? `, ${notChecked.length} NOT checked` : ""}`;
+
   if (totalChanges === 0 && totalRefusals === 0) {
-    log.info(
-      skipped.length > 0
-        ? "meta upgrade — no retired vocabulary found in the JSON metadata."
-        : "meta upgrade — no retired vocabulary found.",
-    );
+    log.info(`meta upgrade — nothing to rewrite (${scope}).`);
   } else if (totalChanges === 0) {
     // Refusals only. Reporting "rewrote 0 declarations", or advertising `--apply`, both
     // promise an action guaranteed to change nothing and bury the fact that the remaining
@@ -143,8 +167,7 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
   }
 
   // Non-zero while ANY refusal stands, applied or not. A partial upgrade that exited 0 would
-  // let CI record the migration as done while metadata still fails to load. A file we could
-  // not read at all counts the same way, for the same reason.
+  // let CI record the migration as done while metadata still fails to load.
   if (totalRefusals > 0) {
     log.error(
       `${totalRefusals} declaration(s) need a human decision and were left untouched — ` +
@@ -152,5 +175,11 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
     );
     return 1;
   }
-  return skipped.length > 0 ? 1 : 0;
+
+  // "I could not look" gets its OWN code. It used to share exit 1 with "work remains", so a
+  // script could not tell an estate needing decisions from one the tool never opened — and
+  // an adopter whose whole estate was skipped got a failure exit next to a message saying
+  // nothing was found.
+  if (notChecked.length > 0) return 3;
+  return 0;
 }

package/src/commands/verify.ts

@@ -15,9 +15,12 @@ import { warnIfManifestIgnored } from "../lib/manifest-ignored-check.js";
 import { scanSourceForAntiPatterns } from "../lib/anti-patterns.js";
 import { FileProvider } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
-import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenCollection, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
 import { computeCodegenDrift } from "../lib/codegen-drift.js";
-import { checkRequirements, summariseRequirements } from "../lib/requirement-check.js";
+import {
+  checkRequirements, summariseRequirements, scanRequirements, type Diagnostic,
+} from "../lib/requirement-check.js";
+import { lintRequirements } from "../lib/requirement-lint.js";
 import { resolveD1Config, resolveMigrateConfig } from "../lib/config.js";
 import {
   buildWranglerExecuteArgs,
@@ -461,12 +464,16 @@ export async function verifyCommand(
     // rule reaches the semantic cases. FR-038 retires the attribute rather than
     // narrowing it; the replacement generates the test FROM the requirement, so
     // the link is structural instead of a string the author picks.
-    const diags = [...checkRequirements(root)];
+    // ONE scan for all three passes. The gate and the summary each used to walk the
+    // model AND resolve every @implementedBy claim for themselves — the resolution
+    // being the expensive half — and the lint added a third walk on top.
+    const scan = scanRequirements(root);
+    const diags = [...checkRequirements(root, scan)];
 
     // Printed on EVERY run, clean or not — a gate that says nothing when it
     // passes cannot be told apart from a gate that checked nothing, and the
     // recorded-gap counts are the whole reason to keep a ledger.
-    const s = summariseRequirements(root);
+    const s = summariseRequirements(root, scan);
     if (s !== undefined) {
       const order = [...REQUIREMENT_STATUSES];
       const parts = order
@@ -493,15 +500,51 @@ export async function verifyCommand(
       }
     }
 
-    if (diags.length === 0) return 0;
     const errors = diags.filter((d) => d.severity === "error");
     const warns = diags.filter((d) => d.severity === "warn");
     const CAP = 20;
-    for (const d of errors) log.error(`  ${d.code}${d.name !== undefined ? ` [${d.name}]` : ""}: ${d.message}`);
-    for (const d of warns.slice(0, CAP)) {
-      log.warn(`  ${d.code}${d.name !== undefined ? ` [${d.name}]` : ""}: ${d.message}`);
+    const fmt = (d: Diagnostic): string =>
+      `  ${d.code}${d.path !== undefined ? ` [${d.path}]` : ""}: ${d.message}`;
+    /** Print a capped run of warnings. Capped per SECTION, never across them: a
+     *  ledger of a few hundred entries can produce hundreds of prose findings, and a
+     *  shared cap would let the advisory lint push every gate warning off the end. */
+    const warnCapped = (ds: readonly Diagnostic[]): void => {
+      for (const d of ds.slice(0, CAP)) log.warn(fmt(d));
+      if (ds.length > CAP) log.warn(`  …and ${ds.length - CAP} more.`);
+    };
+    for (const d of errors) log.error(fmt(d));
+    warnCapped(warns);
+
+    // -- the authoring lint: its own section, its own cap ----------------------
+    // Separate from the gate above because it makes a different claim. The gate
+    // says the ledger DISAGREES WITH THE MODEL; the lint says it agrees but
+    // records less than its author thinks — a name that is not an address, two
+    // slots holding one sentence, prose written where no surface reads it.
+    //
+    // The separate cap is the load-bearing part. A ledger of a few hundred
+    // entries can produce hundreds of prose findings, and under one shared cap
+    // those would push every WARN_REQUIREMENT_OBJECT_UNCLAIMED off the end of the
+    // list — the lint would silence the gate it was added beside. Nothing here
+    // reaches the exit code: every lint finding is a warning by construction.
+    // Muted with --no-requirement-lint or META_NO_REQUIREMENT_LINT=1, the same pair
+    // its sibling advisory offers. It mutes the ADVISORY half only — the gate above
+    // still runs and can still fail the build, which is the point of the split.
+    // `s === undefined` means the model declares no requirements at all, which the
+    // two passes above have already established: opt-in by declaration, decided
+    // without a third walk to rediscover it.
+    const lint = s === undefined
+        || flags.noRequirementLint
+        || process.env.META_NO_REQUIREMENT_LINT === "1"
+      ? []
+      : lintRequirements(root, scan.addressed);
+    if (lint.length > 0) {
+      log.warn(
+        `meta verify — requirements: ${lint.length} authoring warning(s) ` +
+        `(advisory — does not fail the build):`,
+      );
+      warnCapped(lint);
     }
-    if (warns.length > CAP) log.warn(`  …and ${warns.length - CAP} more.`);
+
     if (errors.length > 0) {
       log.error(`meta verify — requirements: ${errors.length} error(s).`);
       return 1;
@@ -954,9 +997,33 @@ export async function verifyCommand(
     // question 3) — a `gen` that committed under a narrowed scope and a
     // `verify --codegen` that regenerates unscoped would disagree about which
     // files should exist, reporting every out-of-scope entity as drift.
+    //
+    // The same argument governs the SOURCE SET (#340), and it is the reason this
+    // resolves its own collection instead of reusing the outer one: `gen` in a
+    // sub-project generates from that package's own sources, so a `--codegen` gate
+    // that regenerated from the ancestor's wider set would report every file the
+    // ancestor contributes as drift — turning the #340 fix into a broken gate. It is
+    // re-resolved rather than hoisted because `verify`'s subverbs COMPOSE: `--db` and
+    // `--templates` are answering a question about the whole declared collection, and
+    // narrowing the outer `root` would silently change what they check.
+    const genCollection = await resolveGenCollection(collection, genConfigDir);
+    let codegenRoot = root;
+    if (genCollection !== collection) {
+      try {
+        codegenRoot = await loadMemory(genCollection.configDir, {
+          files: genCollection.files,
+          ...configLoadOptions,
+          strict: !flags.lax,
+        });
+      } catch (err) {
+        log.error(`verify --codegen: failed to load this package's metadata: ${(err as Error).message}`);
+        return 2;
+      }
+    }
+
     let result;
     try {
-      result = await computeCodegenDrift(forgeConfig, root, genConfigDir, collection.inScope);
+      result = await computeCodegenDrift(forgeConfig, codegenRoot, genConfigDir, genCollection.inScope);
     } catch (err) {
       log.error(`verify --codegen: regeneration failed: ${(err as Error).message}`);
       return 1;

package/src/index.ts

@@ -21,7 +21,7 @@ COMMANDS:
   gen [<entity>...]     Codegen TS targets from your declared metadata
   types [query]         Search the metadata vocabulary (types, subtypes, @attrs) by name or description
   export                Flatten loaded metadata to one canonical JSON artifact
-  docs <metadata> --out <dir>  Generate neutral metadata documentation (entity + template pages; --site for HTML site)
+  docs [<project-root>] --out <dir>  Generate neutral metadata documentation (entity + template pages; --site for HTML site)
   verify                Drift gate — subverbs: --templates / --db / --codegen (bare = --templates)
   upgrade               Rewrite retired metadata vocabulary (previews; --apply writes)
   prompt-snapshot       Snapshot rendered template.* output; --check gates drift
@@ -42,9 +42,11 @@ EXPORT FLAGS:
   --out <file>          Write output to a file (default: stdout)
 
 DOCS FLAGS:
-  <metadata>            Project root to resolve metadata from; passing it SCOPES the run (default: cwd)
+  [<project-root>]      PROJECT ROOT to resolve metadata from — the directory that CONTAINS
+                        your metadata, NOT the metadata directory. Passing it SCOPES the run
+                        (default: cwd)
   --out <dir>, -o       Output directory for the pages (default: ./docs)
-  --templates <dir>     Project root to resolve adopter templates/ overrides (default: <metadata>)
+  --templates <dir>     Project root to resolve adopter templates/ overrides (default: <project-root>)
   --prompts <dir>       Extra dir holding prompt .mustache sources for --site (e.g. data/templates/)
 
 VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drift):
@@ -143,6 +145,7 @@ FLAGS:
   --remote              Target remote D1 instead of local (only with --dialect d1) —
                         the ONLY way to verify the actual deployed D1 database
   --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
+  --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
   --help, -h            Print this help
 
 A bare 'meta verify' also runs an ADVISORY anti-pattern pass: it scans your authored
@@ -150,6 +153,12 @@ source for hand-rolled aggregates, money-as-float, and CHECK-IN enums and points
 at the construct that models them (origin.aggregate / field.currency / field.enum).
 Warnings only — it never fails the build. Opt out with --no-antipatterns or
 META_NO_ANTIPATTERNS=1.
+
+If the project declares requirement.* nodes, verify also prints an ADVISORY authoring
+lint in its own section: names that are not addressable, prose slots holding one
+sentence twice, content written where no surface reads it. Warnings only — it can
+never fail the build. Opt out with --no-requirement-lint or META_NO_REQUIREMENT_LINT=1.
+The requirements GATE itself (dangling refs, link floor, levels) always runs.
 `,
   export: `meta export — flatten loaded metadata to one canonical JSON artifact
 
@@ -163,12 +172,15 @@ FLAGS:
   docs: `meta docs — generate neutral metadata documentation (entity + template pages)
 
 USAGE:
-  meta docs [<metadata>] [flags]
+  meta docs [<project-root>] [flags]
 
 FLAGS:
-  <metadata>            Project root to resolve metadata from. Passing it SCOPES the run to
-                        that directory's own sources; no ancestor .metaobjects/config.json is
-                        consulted. Omitted (default), the project is discovered by walking up.
+  [<project-root>]      PROJECT ROOT to resolve metadata from — the directory that CONTAINS
+                        your metadata, NOT the metadata directory itself. (The Python and C#
+                        'docs' positionals mean the metadata dir; this one does not.) Passing
+                        it SCOPES the run to that directory's own sources; no ancestor
+                        .metaobjects/config.json is consulted. Omitted (default), the project
+                        is discovered by walking up.
   --out <dir>, -o       Output directory for the pages (default: ./docs)
   --model               Emit the markdown model surface (entity + template pages)
   --api                 Emit the markdown api surface (generated SDK reference)
@@ -177,7 +189,7 @@ FLAGS:
   --metamodel           Document the built-in metamodel vocabulary (no metadata needed)
   --site                Generate the browsable HTML documentation site (<out>/site/)
   --scaffold-site       Copy the site's templates + assets into codegen/docs-site/ to own (theme) them
-  --templates <dir>     Project root to resolve adopter templates/ overrides (default: <metadata>)
+  --templates <dir>     Project root to resolve adopter templates/ overrides (default: <project-root>)
   --prompts <dir>       Extra dir holding prompt .mustache sources (for --site) when they
                         live outside the metadata sources or templates/ (e.g. data/templates/)
   --help, -h            Print this help

package/src/lib/args.ts

@@ -259,6 +259,14 @@ export interface VerifyFlags {
   anyExplicit: boolean;
   /** Suppress the advisory anti-pattern (verify-as-teacher) pass. */
   noAntipatterns: boolean;
+  /**
+   * Suppress the advisory requirement AUTHORING lint — the second, prose-quality
+   * section, never the gate above it. Its own findings argue that a noisy advisory
+   * gets switched off wholesale, and a ledger mid-migration can print its capped
+   * twenty lines on every run for weeks; a mute for the advisory half is what keeps
+   * the half that CAN fail a build switched on. Same shape as --no-antipatterns.
+   */
+  noRequirementLint: boolean;
   /**
    * ADR-0023 strict-attr load opt-OUT (#96). `verify` is strict-by-default — an
    * undeclared/typo'd own `@attr` fails verify (ERR_UNKNOWN_ATTR). `--lax`
@@ -281,6 +289,7 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
       replay: { type: "boolean", default: false },
       "replay-snapshot": { type: "boolean", default: false },
       "no-antipatterns": { type: "boolean", default: false },
+      "no-requirement-lint": { type: "boolean", default: false },
       lax: { type: "boolean", default: false },
       "d1": { type: "string" },
       "remote": { type: "boolean", default: false },
@@ -330,6 +339,7 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
     replaySnapshot,
     anyExplicit,
     noAntipatterns: !!values["no-antipatterns"],
+    noRequirementLint: !!values["no-requirement-lint"],
     lax: !!values.lax,
     d1: values.d1 as string | undefined,
     remote: !!values.remote,

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

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 import { createJiti } from "jiti";
 import type { MetaDataTypeProvider, MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
+import { resolveCollection, type Collection } from "@metaobjectsdev/sdk";
 
 const CONFIG_FILE = "metaobjects.config.ts";
 
@@ -212,6 +213,50 @@ export function resolveGenConfigDir(startDir: string, fallback: string): string
   return fallback;
 }
 
+/**
+ * The collection a TypeScript package GENERATES FROM (#340).
+ *
+ * #326/#327 established that the two config files answer different questions, and gave
+ * `metaobjects.config.ts` its own walk. This is the remaining half of the same split:
+ * a sub-project whose TS config sits below the collection root was still LOADING the
+ * ancestor's whole source set, so its `src/generated` absorbed metadata belonging to
+ * unrelated parts of the repository — one adopter's web app went from 376 files to 831,
+ * the surplus being another module's server-side prompt payload DTOs. It fails OPEN
+ * (`tsc` passes, tests pass), so the only symptom is a directory that quietly doubled.
+ *
+ * The rule: an ancestor `.metaobjects/config.json` is the DEFAULT for a package that
+ * declares no sources of its own, never an ADDITION to one that does. So when the TS
+ * config sits somewhere the collection did not, that directory is re-resolved as a
+ * collection in its own right, and it wins if it actually resolves any metadata.
+ *
+ * It can only ever NARROW, and only in a shape that could not have worked before:
+ *   - the two directories coincide (every `meta init` project, and every run from a
+ *     project root) — returns the original, untouched, without a second resolve;
+ *   - the sub-project declares no sources — the pinned resolve throws
+ *     `ERR_SOURCE_UNRESOLVED` or comes back empty, and the ancestor stands, so a
+ *     package that genuinely lives off an ancestor tree keeps working;
+ *   - the sub-project has its own metadata — it generates from exactly that, which is
+ *     what it did before source resolution learned to walk upward.
+ *
+ * Deliberately NOT applied to `.metaobjects/` STATE. Migrations, snapshots and the
+ * operational block stay keyed on the discovered collection's directory (#326 settled
+ * that); this narrows what is LOADED, and nothing about where state lives.
+ */
+export async function resolveGenCollection(
+  collection: Collection,
+  genConfigDir: string,
+): Promise<Collection> {
+  if (resolve(genConfigDir) === resolve(collection.configDir)) return collection;
+  try {
+    const pinned = await resolveCollection(genConfigDir, { explicitDir: genConfigDir });
+    return pinned.files.length > 0 ? pinned : collection;
+  } catch {
+    // The sub-project declares nothing resolvable of its own — inherit, exactly as a
+    // package with no config always has.
+    return collection;
+  }
+}
+
 export async function loadMetaobjectsConfig(projectRoot: string): Promise<MetaobjectsGenConfig> {
   const fullPath = resolve(projectRoot, CONFIG_FILE);
   if (!existsSync(fullPath)) {