@metaobjectsdev/cli 0.24.1 → 0.24.3

package/src/lib/codegen-drift.ts

@@ -2,10 +2,25 @@
 //
 // Regenerates the configured codegen into a throwaway temp directory and DIFFs
 // the freshly-generated file tree against the committed output (the config's
-// outDir / per-target outDirs). Any difference — a file present in one tree but
-// not the other, or differing content — is drift: either "metadata changed but
-// `meta gen` wasn't re-run" or "a generated file was hand-edited". Reuses the
-// exact same `runGen` pipeline `meta gen` uses, so the comparison is faithful.
+// outDir / per-target outDirs). Reuses the exact same `runGen` pipeline `meta gen`
+// uses, so the comparison is faithful.
+//
+// A DIFFERENCE IS NOT AUTOMATICALLY DRIFT. This gate used to treat "metadata
+// changed but `meta gen` wasn't re-run" and "a generated file was hand-edited" as
+// one verdict. Only the first is drift; the second is the documented workflow —
+// `meta gen` three-way-merges hand edits and reports "merged", and the product
+// says in as many words that anything inside a generated file is fair game to
+// edit. Convicting both made the gate unusable for anyone who took that offer,
+// and its printed remedy was a LOOP: running `meta gen` merges the edit back in,
+// so the next run failed identically. Requirement-test stubs were the worst case,
+// being worthless until hand-edited.
+//
+// The discriminator is `.gen-state/.hashes.json`, which records what the GENERATOR
+// WROTE rather than what the file became, and is the committed half of `.gen-state`
+// precisely so this is answerable on a machine that did not generate the output.
+// When a fresh regen hashes to what we recorded writing, the generator's
+// contribution is current and the on-disk difference is a preserved hand edit.
+// Design: spec/design-docs/2026-08-27-codegen-drift-hand-edits-design.md
 //
 // Faithfulness note: generated content can embed import paths computed RELATIVE
 // to a target's outDir (and between targets). To keep the regen byte-identical
@@ -24,7 +39,12 @@ import {
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, relative, resolve, isAbsolute } from "node:path";
-import { runGen } from "@metaobjectsdev/codegen-ts";
+import {
+  runGen,
+  contentHash,
+  readGeneratedHash,
+  listGeneratedPaths,
+} from "@metaobjectsdev/codegen-ts";
 import type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 import type { MetaData } from "@metaobjectsdev/metadata";
 
@@ -97,6 +117,11 @@ export async function computeCodegenDrift(
 ): Promise<CodegenDriftResult> {
   const root = isAbsolute(projectRoot) ? projectRoot : resolve(projectRoot);
 
+  // The PROJECT's snapshot manifest, never the temp one built below — that temp
+  // manifest only describes the regen that just ran, so it can say nothing about
+  // what `meta gen` last wrote here. Same default location runner.ts derives.
+  const projectGenStateDir = join(root, ".metaobjects", ".gen-state");
+
   const committedDirs = committedOutDirs(config, root);
   if (committedDirs.length === 0) {
     return {
@@ -171,6 +196,11 @@ export async function computeCodegenDrift(
     // Diff each committed outDir against its temp mirror.
     const driftedFiles = new Set<string>();
     const lines: 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;
     for (const committed of committedDirs) {
       const fresh = tempFor(committed);
       const committedFiles = new Set(listFiles(committed));
@@ -181,6 +211,19 @@ export async function computeCodegenDrift(
         const inCommitted = committedFiles.has(rel);
         const inFresh = freshFiles.has(rel);
         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
+          // anything else it means the file was never ours. outDir is a
+          // directory, not a namespace we own: the documented quickstart itself
+          // fills it with strangers — `npx tsc` under a stock tsconfig (no
+          // `outDir` of its own) drops .js/.d.ts/.map beside the sources — and
+          // convicting those failed a project with no drift of any kind.
+          // `meta gen`'s orphan sweep already scopes itself this way via
+          // `listGeneratedPaths` before it will delete anything; the gate asks
+          // the same question of the same evidence so the two doors agree.
+          if (haveWriteRecords && readGeneratedHash(projectGenStateDir, relKey) === undefined) {
+            continue;
+          }
           driftedFiles.add(relKey);
           lines.push(`- ${relKey} (committed but regen would not emit it)`);
         } else if (!inCommitted && inFresh) {
@@ -189,7 +232,12 @@ export async function computeCodegenDrift(
         } else {
           const a = readFileSync(join(committed, rel), "utf8");
           const b = readFileSync(join(fresh, rel), "utf8");
-          if (a !== b) {
+          // Not `a !== b` alone: that convicts the hand edit `meta gen` preserved.
+          // The question this gate can honestly answer is "is the GENERATED
+          // contribution current?", and the recorded hash answers exactly it.
+          // FAILS CLOSED, matching `isPristineGenerated`: with no recorded hash
+          // nothing is proven, so the old byte verdict stands.
+          if (a !== b && readGeneratedHash(projectGenStateDir, relKey) !== contentHash(b)) {
             driftedFiles.add(relKey);
             lines.push(`~ ${relKey} (committed content differs from a fresh regen)`);
           }

package/src/lib/requirement-check.ts

@@ -48,8 +48,12 @@ export type Severity = "error" | "warn";
 export interface Diagnostic {
   severity: Severity;
   code: string;
-  /** The requirement node's name, when the diagnostic belongs to one. */
-  name?: string;
+  /** The subject's ADDRESS, when the diagnostic has one — the dotted child-name
+   *  path. Two branches of a ledger may reuse a NAME, so a bare name does not
+   *  locate the node, and a diagnostic you cannot locate is one you cannot act on.
+   *  Absent on a diagnostic whose subject is not a requirement (object coverage
+   *  names the entity in its message instead). */
+  path?: string;
   message: string;
 }
 
@@ -151,21 +155,107 @@ function subtreeClaimsAnything(req: MetaRequirement): boolean {
   return false;
 }
 
-/** Every `requirement.*` node in the tree, at any nesting depth. Hierarchy IS
- *  nesting — an L1 solution contains its L2 segments — so this is a walk, not a
- *  scan of a flat list keyed by a `parent` string. */
-export function collectRequirements(root: MetaData): MetaRequirement[] {
-  const out: MetaRequirement[] = [];
-  const walk = (n: MetaData): void => {
+/** A requirement paired with its ADDRESS — the dotted child-name path from the
+ *  root, which is how every other node in the model is addressed, and which the
+ *  requirement-test generator also turns into the stub's filename. */
+export interface AddressedRequirement {
+  readonly node: MetaRequirement;
+  readonly path: string;
+}
+
+/**
+ * Every `requirement.*` node in the tree, at any nesting depth, each with its
+ * dotted path. Hierarchy IS nesting — an L1 solution contains its L2 segments —
+ * so this is a walk, not a scan of a flat list keyed by a `parent` string.
+ *
+ * ONE derivation of the address for the gate AND the authoring lint, deliberately.
+ * They are two sections of a single `meta verify` run, and when they walked
+ * separately they addressed the same node two different ways — the gate by bare
+ * `name`, which is ambiguous the moment two branches of a ledger reuse one, and the
+ * lint by path. A reader cannot reconcile two addressings of one tree.
+ *
+ * The traversal descends through EVERY node rather than only through requirements:
+ * a requirement somewhere the child rules did not anticipate is still gated, which
+ * is the fail-closed direction for a gate.
+ */
+export function collectAddressedRequirements(root: MetaData): AddressedRequirement[] {
+  const out: AddressedRequirement[] = [];
+  const walk = (n: MetaData, prefix: string): void => {
     for (const c of n.children()) {
-      if (c.type === TYPE_REQUIREMENT) out.push(c as MetaRequirement);
-      walk(c);
+      // Only a requirement contributes a path segment. An intervening non-requirement
+      // node is traversed THROUGH, so the address stays the requirement hierarchy.
+      const isReq = c.type === TYPE_REQUIREMENT;
+      const path = isReq ? (prefix === "" ? c.name : `${prefix}.${c.name}`) : prefix;
+      if (isReq) out.push({ node: c as MetaRequirement, path });
+      walk(c, path);
     }
   };
-  walk(root);
+  walk(root, "");
   return out;
 }
 
+
+/**
+ * Resolve a `@supersededBy` reference to a requirement in the same ledger (FR-039).
+ *
+ * A requirement is addressed the way every other node is: a package qualifies the
+ * ROOT-level node only, and each dotted segment after it walks CHILD names — so
+ * `acme::caps::Billing.InvoiceRecord` names the `InvoiceRecord` child of the
+ * root-level `Billing`. A bare reference binds package-locally first and then at
+ * root level, which is the ADR-0042 contract every other reference already follows.
+ *
+ * Deliberately resolves against the LEDGER, not the model: a capability is replaced
+ * by another capability. Pointing this at an entity would be `@implementedBy` wearing
+ * a different name, and `@implementedBy` is exactly what a retired entry may not have.
+ */
+export function resolveRequirementRef(
+  addressed: readonly AddressedRequirement[],
+  ref: string,
+  referrerPkg: string,
+): MetaRequirement | undefined {
+  const keyed = new Map<string, MetaRequirement>();
+  for (const { node, path } of addressed) {
+    const pkg = node.package ?? node.fileDefaultPackage ?? "";
+    if (pkg !== "") keyed.set(`${pkg}::${path}`, node);
+    // Bare path is registered too, so a single-package ledger can reference
+    // without repeating its own package on every line.
+    if (!keyed.has(path)) keyed.set(path, node);
+  }
+  // An FQN binds exactly; a bare ref prefers the referrer's own package.
+  const exact = keyed.get(ref);
+  if (exact !== undefined) return exact;
+  if (referrerPkg !== "") {
+    const local = keyed.get(`${referrerPkg}::${ref}`);
+    if (local !== undefined) return local;
+  }
+  return undefined;
+}
+
+/** The nodes alone, for callers with no use for the address. */
+export function collectRequirements(root: MetaData): MetaRequirement[] {
+  return collectAddressedRequirements(root).map((r) => r.node);
+}
+
+/**
+ * What one `meta verify` run computes once and both requirement passes read.
+ *
+ * The gate and the summary each need the same two things, and each used to derive
+ * both for itself — so a run walked the model twice and resolved every
+ * `@implementedBy` claim twice, the second of which is the expensive half
+ * (resolution is O(claims x root objects)). Threading the result rather than the
+ * function is what the "SHARED by the gate and the summary" note on
+ * `claimedObjectKeys` was always asking for.
+ */
+export interface RequirementScan {
+  readonly addressed: readonly AddressedRequirement[];
+  readonly claimedObjects: ReadonlySet<string>;
+}
+
+export function scanRequirements(root: MetaData): RequirementScan {
+  const addressed = collectAddressedRequirements(root);
+  return { addressed, claimedObjects: claimedObjectKeys(root, addressed.map((r) => r.node)) };
+}
+
 /**
  * Resolution keys of every object claimed by a requirement.
  *
@@ -232,14 +322,12 @@ function coverableEntities(root: MetaData): MetaData[] {
  * prove: that a status is *true*, or that a node actually implements the
  * requirement claiming it. No test can. That truth is the adopter's job.
  */
-export function checkRequirements(root: MetaData): Diagnostic[] {
+export function checkRequirements(root: MetaData, scan: RequirementScan = scanRequirements(root)): Diagnostic[] {
   const out: Diagnostic[] = [];
-  const reqs = collectRequirements(root);
-  if (reqs.length === 0) return out; // opt-in by declaration — no requirements, nothing to say
-
-  const claimedObjects = claimedObjectKeys(root, reqs);
+  const { addressed, claimedObjects } = scan;
+  if (addressed.length === 0) return out; // opt-in by declaration — no requirements, nothing to say
 
-  for (const req of reqs) {
+  for (const { node: req, path: reqPath } of addressed) {
     const architectural = req.subType === REQUIREMENT_SUBTYPE_ARCHITECTURAL;
     const level = req.level();
     const refs = req.implementedBy();
@@ -258,7 +346,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
       if (!levelled || !Number.isInteger(level)
           || level < REQUIREMENT_MIN_LEVEL || level > REQUIREMENT_MAX_LEVEL) {
         out.push({
-          severity: "error", code: ERR_REQUIREMENT_BAD_LEVEL, name: req.name,
+          severity: "error", code: ERR_REQUIREMENT_BAD_LEVEL, path: reqPath,
           message: `level must be an integer ${REQUIREMENT_MIN_LEVEL}-${REQUIREMENT_MAX_LEVEL} (got ${String(level)}). ` +
             `L1 solution, L2 segment (app/library), L3 service, L4 object, L5 member.` +
             (architectural ? ` On an architectural requirement the level is optional — omit it for a flat policy.` : ``),
@@ -270,7 +358,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
         const pl = (parent as MetaRequirement).level();
         if (pl !== undefined && level !== undefined && level <= pl) {
           out.push({
-            severity: "error", code: ERR_REQUIREMENT_LEVEL_NESTING, name: req.name,
+            severity: "error", code: ERR_REQUIREMENT_LEVEL_NESTING, path: reqPath,
             message: `nested under "${parent.name}" (level ${pl}) but declares level ${level}. ` +
               `Nesting is the hierarchy — a child sits strictly below its parent.`,
           });
@@ -281,7 +369,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
     // -- the link boundary ----------------------------------------------------
     if (refs.length > 0 && !req.mayReferenceModel()) {
       out.push({
-        severity: "error", code: ERR_REQUIREMENT_LINK_ABOVE_FLOOR, name: req.name,
+        severity: "error", code: ERR_REQUIREMENT_LINK_ABOVE_FLOOR, path: reqPath,
         message: `'implementedBy' is legal at L${REQUIREMENT_LINK_FLOOR_LEVEL} (object) and ` +
           `L${REQUIREMENT_MAX_LEVEL} (member) only. L1-L3 are organisational and never reference ` +
           `the model — move the links to a nested L${REQUIREMENT_LINK_FLOOR_LEVEL} child.`,
@@ -310,7 +398,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
       // promised.
       if (!architectural && level === REQUIREMENT_LINK_FLOOR_LEVEL && !isObjectRef) {
         out.push({
-          severity: "error", code: ERR_REQUIREMENT_L4_NOT_OBJECT, name: req.name,
+          severity: "error", code: ERR_REQUIREMENT_L4_NOT_OBJECT, path: reqPath,
           message: `L${REQUIREMENT_LINK_FLOOR_LEVEL} references an object; '${ref}' names a member. ` +
             `Move it to a nested L${REQUIREMENT_LEVEL_MEMBER} child, or reference the object itself.`,
         });
@@ -318,7 +406,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
       }
       if (!architectural && level === REQUIREMENT_LEVEL_MEMBER && isObjectRef) {
         out.push({
-          severity: "error", code: ERR_REQUIREMENT_L5_NOT_MEMBER, name: req.name,
+          severity: "error", code: ERR_REQUIREMENT_L5_NOT_MEMBER, path: reqPath,
           message: `L${REQUIREMENT_LEVEL_MEMBER} references a member (field, view or identity); ` +
             `'${ref}' names an object. Move it to its L${REQUIREMENT_LINK_FLOOR_LEVEL} parent.`,
         });
@@ -332,7 +420,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
         // job, and the reason this check cannot live in the loader.
         if (req.requiresLiveNodes()) {
           out.push({
-            severity: "error", code: ERR_REQUIREMENT_DANGLING_REF, name: req.name,
+            severity: "error", code: ERR_REQUIREMENT_DANGLING_REF, path: reqPath,
             message: `'${ref}' does not resolve in the loaded model (status '${String(req.status())}' — ` +
               `the model moved and the requirement is stale).` + didYouMeanHint(root, owner),
           });
@@ -340,6 +428,32 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
       }
     }
 
+    // -- @supersededBy resolution (FR-039) ------------------------------------
+    // The 2026-08-10 ruling asked for exactly this at point 4 — "a supersededBy
+    // that RESOLVES (FQN-checked, so verify can fail on a dangling one), turning
+    // 'deleted in S6' from an inert comment into a build gate" — and 0.24.0
+    // deregistered the unresolved string version without ever building it.
+    //
+    // Resolution is what makes a supersession CHAIN survive. A prose note points
+    // one hop and rots when that hop is itself retired; a resolved reference does
+    // not, because the target is a real node carrying its own @supersededBy.
+    //
+    // The target is a REQUIREMENT, not a model node: a capability is replaced by
+    // another capability. It resolves package-locally under ADR-0042 through the
+    // requirement's own effective package, exactly as @implementedBy does.
+    const superseded = req.supersededBy();
+    if (superseded !== undefined) {
+      const referrerPkg = req.package ?? req.fileDefaultPackage ?? "";
+      if (resolveRequirementRef(addressed, superseded, referrerPkg) === undefined) {
+        out.push({
+          severity: "error", code: ERR_REQUIREMENT_DANGLING_REF, path: reqPath,
+          message: `@supersededBy '${superseded}' does not name a requirement in the loaded ` +
+            `ledger. It must name the requirement that REPLACED this one — if nothing did, ` +
+            `drop the attribute and let \`notes\` carry why the capability went.`,
+        });
+      }
+    }
+
     // -- architectural universality, v1: claim-set arithmetic -----------------
     // A live policy claimed by nothing is the audited-base case: declared and
     // applied to nothing. Deliberately NOT a violation-predicate DSL — that
@@ -362,7 +476,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
     // levelled one, true again at the link floor.
     if (architectural && live && refs.length === 0 && req.mayReferenceModel()) {
       out.push({
-        severity: "error", code: ERR_REQUIREMENT_ARCH_NO_IMPLEMENTERS, name: req.name,
+        severity: "error", code: ERR_REQUIREMENT_ARCH_NO_IMPLEMENTERS, path: reqPath,
         message: `architectural requirement is '${String(status)}' but nothing implements it. ` +
           `Its check is universality — a claim set of zero means the policy is declared and unapplied.`,
       });
@@ -372,7 +486,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
     const disposition = req.disposition();
     if (disposition !== undefined && !req.hasOutstandingWork()) {
       out.push({
-        severity: "warn", code: WARN_REQUIREMENT_DISPOSITION_NOT_APPLICABLE, name: req.name,
+        severity: "warn", code: WARN_REQUIREMENT_DISPOSITION_NOT_APPLICABLE, path: reqPath,
         message: `carries @disposition '${disposition}' but its status is '${String(status)}', which has no ` +
           `outstanding work to decide about. A disposition is meaningful on 'planned' and 'partial' only — ` +
           `on any other status the decision IS the status.`,
@@ -387,7 +501,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
     // is empty is a capability declared and built by nobody.
     if (!architectural && live && !subtreeClaimsAnything(req)) {
       out.push({
-        severity: "warn", code: WARN_REQUIREMENT_NOTHING_IMPLEMENTS, name: req.name,
+        severity: "warn", code: WARN_REQUIREMENT_NOTHING_IMPLEMENTS, path: reqPath,
         message: `is '${String(status)}' but neither it nor anything nested under it names an ` +
           `implementing node. A functional requirement's check is existence — a subtree that claims ` +
           `nothing is a capability nobody built.`,
@@ -396,7 +510,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
 
     if (disposition === REQUIREMENT_DISPOSITION_DEFERRED && req.trackedBy().length === 0) {
       out.push({
-        severity: "warn", code: WARN_REQUIREMENT_DEFERRED_UNTRACKED, name: req.name,
+        severity: "warn", code: WARN_REQUIREMENT_DEFERRED_UNTRACKED, path: reqPath,
         message: `is deferred but names no @trackedBy issue. Deferring without a ticket is how a known gap ` +
           `becomes an unknown one — nothing will raise it again.`,
       });
@@ -447,8 +561,11 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
  * are deliberately the ones an author would otherwise have to write a script to
  * get: how many gaps are recorded, and how many of those nobody has ruled on.
  */
-export function summariseRequirements(root: MetaData): RequirementSummary | undefined {
-  const reqs = collectRequirements(root);
+export function summariseRequirements(
+  root: MetaData,
+  scan: RequirementScan = scanRequirements(root),
+): RequirementSummary | undefined {
+  const reqs = scan.addressed.map((r) => r.node);
   if (reqs.length === 0) return undefined; // opt-in by declaration
 
   const summary: RequirementSummary = {
@@ -475,9 +592,10 @@ export function summariseRequirements(root: MetaData): RequirementSummary | unde
     }
   }
 
-  // Both sides of the ratio come from the SAME helpers the gate uses, so the
-  // printed summary cannot disagree with the diagnostics printed beneath it.
-  const claimed = claimedObjectKeys(root, reqs);
+  // Both sides of the ratio come from the SAME scan the gate read, so the printed
+  // summary cannot disagree with the diagnostics printed beneath it — previously
+  // the same helper, now literally the same result.
+  const claimed = scan.claimedObjects;
   for (const ent of coverableEntities(root)) {
     summary.entitiesTotal++;
     if (claimed.has(ent.resolutionKey())) summary.entitiesClaimed++;