@metaobjectsdev/cli 0.24.1 → 0.24.2

package/dist/src/lib/requirement-lint.js

@@ -0,0 +1,318 @@
+// `meta verify` — the requirement AUTHORING lint.
+//
+// A different kind of claim from the gate in `requirement-check.ts`, which is why
+// it is a separate function rather than more branches inside `checkRequirements`.
+//
+//   THE GATE   referential integrity — links sit at or below the floor, nesting
+//              agrees with levels, references resolve. A finding there means the
+//              ledger DISAGREES WITH THE MODEL.
+//   THE LINT   authoring quality — the name is addressable, the prose slots hold
+//              distinct content, nothing was written into a slot no surface reads.
+//              A finding here means the ledger is INTERNALLY WASTEFUL: it still
+//              agrees with the model, it just records less than its author thinks.
+//
+// Keeping them apart is not tidiness. `meta verify` prints at most 20 warnings, and
+// a ledger with 240 entries can produce hundreds of prose findings — enough to push
+// every WARN_REQUIREMENT_OBJECT_UNCLAIMED off the end of the list. Two sections with
+// two caps means the lint cannot drown the gate.
+//
+// IT READS THE LOADED MODEL, NEVER THE FILES. Extensions and overlays mean the text
+// on disk is not the effective model: an attr set in one file and overridden in
+// another, or inherited through `extends`, reads differently from every angle except
+// the loaded tree. A raw-file linter would be wrong for any project using either.
+//
+// EVERY FINDING IS A WARNING, BY CONSTRUCTION — not by a switch. Stated as a rule so
+// the next check added here follows it: a check newly added to a shipping gate cannot
+// be shown not to fire on an estate that already exists, and prose findings that turn
+// `meta verify` red on upgrade teach people to switch the gate off, which costs more
+// than the padding they caught. The precedent is object coverage, which stayed a
+// warning because on one real estate it reported every entity in the repository.
+//
+// There is deliberately NO severity constant to flip. `verify` prints this section
+// with `log.warn` unconditionally and computes its exit code from the GATE alone, so
+// a constant here would have promised a promotion it could not deliver. If a check in
+// this file ever has to fail a build, the honest move is to move the check into the
+// gate — which is a decision about what the check IS, not a severity edit.
+import { DOC_ATTR_DESCRIPTION, DOC_ATTR_SUMMARY, DOC_ATTR_TITLE, REQUIREMENT_ATTR_COUNTEREXAMPLE, REQUIREMENT_ATTR_STATEMENT, REQUIREMENT_ATTR_TRACKED_BY, 
+// The port's ONE identifier splitter, used here for its word boundaries rather
+// than its underscores: `normalise` lowercases and maps every separator to a
+// space, so `toSnakeCase(name)` and a hand-rolled camel split are identical
+// downstream (checked over 20k random identifiers). Sharing it means the lint
+// splits a name the same way the column/table/kebab namers do — a private copy
+// would silently stop agreeing the day that rule is corrected.
+toSnakeCase, } from "@metaobjectsdev/metadata";
+// The SAME collection the gate walks, so the two sections of one `meta verify` run
+// address a node identically — and the dotted path each reports is the address the
+// requirement-test generator turns into the stub's filename. (Pinned by a test that
+// compares this path set against `walkRequirements()`, the generator's own walk,
+// rather than leaving the two to agree by inspection.)
+import { collectAddressedRequirements, } from "./requirement-check.js";
+export const WARN_REQUIREMENT_NAME_NOT_ADDRESSABLE = "WARN_REQUIREMENT_NAME_NOT_ADDRESSABLE";
+export const WARN_REQUIREMENT_NAME_READS_AS_PROSE = "WARN_REQUIREMENT_NAME_READS_AS_PROSE";
+export const WARN_REQUIREMENT_NAME_RESTATES_STATEMENT = "WARN_REQUIREMENT_NAME_RESTATES_STATEMENT";
+export const WARN_REQUIREMENT_PROSE_DUPLICATED = "WARN_REQUIREMENT_PROSE_DUPLICATED";
+export const WARN_REQUIREMENT_PROSE_EMPTY = "WARN_REQUIREMENT_PROSE_EMPTY";
+export const WARN_REQUIREMENT_INERT_DOC_SLOT = "WARN_REQUIREMENT_INERT_DOC_SLOT";
+export const WARN_REQUIREMENT_TITLE_IS_AN_ID = "WARN_REQUIREMENT_TITLE_IS_AN_ID";
+/**
+ * Characters that break the two things a requirement's `name` IS.
+ *
+ *   `.`  the dotted-path separator. A name containing one is INDISTINGUISHABLE
+ *        from nesting: a single node named "Orders.Recorded" and a node "Orders"
+ *        containing a node "Recorded" both produce the path `Orders.Recorded`, so
+ *        the address stops identifying one node and the two collide on the same
+ *        emitted stub file.
+ *   `/`  `\`  path separators. The default stub path is
+ *        `requirements/<path>.test.ts`, so a name of `../../thing` writes OUTSIDE
+ *        the stub directory — and `owns()`, which is what lets the runner reap a
+ *        stub whose requirement was deleted, will never claim it back.
+ *   the rest  illegal in a filename on Windows, so the stub cannot be written at
+ *        all there. `:` doubles as half of the `::` package separator.
+ *
+ * Every one of these loads today: the loader constrains a requirement's name no
+ * more than any other node's, and nothing downstream re-checks it.
+ *
+ * A SEAM, recorded so the decision stays visible: the general form of this rule is
+ * not requirement-specific at all — a `.` in ANY node's name breaks the dotted
+ * child-name addressing the whole metamodel uses — so it arguably belongs in the
+ * loader as a cross-port warning, beside WARN_ENUM_NORMALIZE_AMBIGUOUS. It is
+ * scoped here because the requirement surface is where it currently bites (a name
+ * becomes a stub FILENAME only here), and because promoting it means five ports,
+ * expected-warnings.json, conformance fixtures and a metamodelVersion question.
+ * That is an FR, not a line in this file.
+ */
+const UNADDRESSABLE = /[./\\:*?"<>|\p{Cc}]/gu;
+/** How one offending character is named in the message, so the author is told which
+ *  one to remove rather than left to diff their name against a regex.
+ *
+ *  Only `.` needs a written entry — the rest are self-describing once quoted, and a
+ *  hand-written entry per character was a table that had to be kept in step with
+ *  UNADDRESSABLE: adding a character to the regex and forgetting the table printed
+ *  a bare code point where the character itself was meant. Derived, so it cannot
+ *  drift. */
+function describeChar(c) {
+    if (c === ".")
+        return "'.' (the dotted-path separator)";
+    // A control character has no printable form to quote, so name its code point.
+    return /\p{Cc}/u.test(c) ? `U+${c.charCodeAt(0).toString(16).padStart(4, "0")}` : `'${c}'`;
+}
+/**
+ * Word count at which a name stops reading as a label and starts reading as prose.
+ *
+ * A threshold, and the only one in this file — chosen high on purpose. Five words
+ * is still plausibly a label ("Order recording for placed orders"); six is a
+ * sentence. Under-firing is the right failure here: renaming a requirement changes
+ * its address AND its emitted stub filename, so a false positive asks the author to
+ * pay a migration for nothing.
+ */
+const PROSE_WORD_COUNT = 6;
+/**
+ * Slots that say nothing on a requirement — and the two deliberate exclusions.
+ *
+ * `summary` qualifies: `@statement` is REQUIRED on both subtypes and is already the
+ * one-line sentence, so a summary beside it can only repeat it, and nothing reads
+ * it. `spec/capability-ledger.md`'s requirement attribute table does not list it.
+ *
+ * `title` is NOT on this list, and an earlier version of this file had it there —
+ * wrongly. That same attribute table charters it BY NAME on a requirement ("a short
+ * noun-phrase label — `name` is an identifier, this is what an index shows"), which
+ * is exactly this node type's situation: a requirement's address renders as a dotted
+ * camelCase path. Measured against three real ledgers the ban would have told two
+ * adopters to delete 355 authored labels, 123 of which carry words the name does not.
+ * That the requirements page does not render `title` yet is a gap in the RENDERER,
+ * and a tool reporting its own backlog in an adopter's terminal is noise.
+ *
+ * `notes` is excluded for the opposite reason: chartered internal-only, so being
+ * unrendered is the point of it.
+ */
+const INERT_SLOTS = [DOC_ATTR_SUMMARY];
+/**
+ * A catalogue or ticket id at the head of a label — `FR-448 …`, `PLAT-77 …`.
+ *
+ * The real failure the id case represents is FIELD OVERLOADING, not an unread slot:
+ * a citation lives in the display label because nothing else was offered, and
+ * `@trackedBy` (free-form, deliberately never resolved) is what was. The measured
+ * values carry an id AND a noun phrase — "FR-448 — prompt construction as typed
+ * payloads through a render engine" — so the fix is to SPLIT them. Moving the whole
+ * string to `@trackedBy` would throw the label away, which is why the message says
+ * split rather than move.
+ */
+const TITLE_IS_AN_ID = /^[A-Z]{2,}[- ]?\d+/;
+/** Lowercase, drop everything that is not alphanumeric, collapse the gaps.
+ *  Two slots "say the same thing" only if they survive this identically — no
+ *  similarity score, no threshold. A fuzzy match on prose produces findings the
+ *  author can argue with, and a gate people argue with is a gate people mute. */
+function normalise(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+/** Whether `text`'s LEADING sentence says the same thing as `key`. False when the
+ *  text is a single sentence — the caller's whole-string comparison covers that.
+ *
+ *  Newlines are collapsed FIRST. A `description` is routinely authored as a YAML
+ *  literal block, so the repeated opening sentence usually wraps — and `.` in a JS
+ *  regex does not cross a newline, which made this arm silently miss exactly the
+ *  authoring style most likely to trip it. The whole-string arm never had the bug
+ *  because `normalise` already flattens whitespace. */
+function leadingSentenceMatches(text, key) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    const m = /^(.+?[.!?])\s+\S/.exec(flat);
+    return m?.[1] !== undefined && normalise(m[1]) === key;
+}
+/** A resolving string read, normalised so "declared but blank" and "absent" are
+ *  distinguishable — the first is a finding, the second usually is not.
+ *  `attr()` RESOLVES in TypeScript (ADR-0039), so a requirement inheriting its
+ *  prose through `extends` is linted on what it effectively carries. */
+function readSlot(node, name) {
+    const raw = node.attr(name);
+    return typeof raw === "string" ? raw : undefined;
+}
+/**
+ * An OWN-ONLY string read — one of the two sanctioned `own*()` uses in this file
+ * (ADR-0039 requires every such call to name its case).
+ *
+ * The checks split by what they are ABOUT, and the split decides the accessor:
+ *
+ *   RESOLVING  a check about what a node effectively SAYS. Two slots holding one
+ *              sentence is a property of the effective node — a child may override
+ *              one slot and inherit the other, and only the resolved pair shows it.
+ *   OWN-ONLY   a check about a DECLARATION, whose fix is a single edit at a single
+ *              node. `title` set once on an abstract is inherited by every child, so
+ *              a resolving read reports it once per child at addresses where the
+ *              author will find no `title` to delete — on a ledger using the shared
+ *              abstract idiom, one mistake can fill the whole lint cap with lines
+ *              nobody can act on where they are pointed.
+ */
+function readOwnSlot(node, name) {
+    const raw = node.ownAttr(name);
+    return typeof raw === "string" ? raw : undefined;
+}
+/** Echo an authored value back inside a message without letting a long one take over
+ *  the terminal. Findings are printed one per line and a `description`-length slot
+ *  would wrap for a dozen of them. */
+function excerpt(value) {
+    const LIMIT = 80;
+    const flat = value.replace(/\s+/g, " ").trim();
+    return JSON.stringify(flat.length > LIMIT ? `${flat.slice(0, LIMIT - 1)}…` : flat);
+}
+function warn(path, code, message) {
+    return { severity: "warn", code, path, message };
+}
+/**
+ * Lint every `requirement.*` node in the loaded model.
+ *
+ * Returns `[]` for a model declaring none — opt-in by declaration, the same way
+ * the gate and the docs surface are, so turning this on by default is a no-op for
+ * every project without a ledger.
+ *
+ * What it CANNOT tell you: whether a statement is true, whether a description is
+ * useful, or whether the counterexample would actually falsify the claim. Those
+ * are the judgements the ledger exists to record and no check reaches them. Every
+ * finding below is about a slot's MECHANICS — is this content reachable, is it
+ * distinct from its neighbour, is the name still an address.
+ */
+export function lintRequirements(root, 
+/** The run's already-collected requirements, when one exists. The lint takes the
+ *  ADDRESSES alone rather than the gate's full `RequirementScan`: it has nothing
+ *  to do with who claims what, and asking for the claim set would make a
+ *  standalone call pay for a resolution it never reads. */
+addressed = collectAddressedRequirements(root)) {
+    const out = [];
+    for (const { node, path } of addressed) {
+        const name = node.name;
+        // -- the name is an address, not prose ------------------------------------
+        // EVERY problem with one name is reported in ONE finding. These were two
+        // branches of an if/else, so a name that was both padded and dotted reported
+        // only the dot: the author fixed it, re-ran, and was told about the padding on
+        // a second pass. One name is one edit, so it is one finding.
+        const problems = [];
+        const offenders = [...new Set(name.match(UNADDRESSABLE) ?? [])];
+        if (offenders.length > 0) {
+            problems.push(`contains ${offenders.map(describeChar).join(", ")}`);
+        }
+        if (name.trim() === "")
+            problems.push("is blank");
+        else if (name.trim() !== name)
+            problems.push("has leading or trailing whitespace");
+        if (problems.length > 0) {
+            out.push(warn(path, WARN_REQUIREMENT_NAME_NOT_ADDRESSABLE, `name ${JSON.stringify(name)} ${problems.join(", and ")}. A requirement's name is its ` +
+                `address — it is the segment of the dotted path '${path}' and the filename of its generated ` +
+                `test stub — so this either collides with nesting or produces a path the stub cannot be ` +
+                `written to.`));
+        }
+        const statementKey = normalise(readSlot(node, REQUIREMENT_ATTR_STATEMENT) ?? "");
+        // -- the name is not the claim --------------------------------------------
+        // Ordered before the prose-shape check and exclusive with it: when the name IS
+        // the statement, "rename it" is the wrong instruction. The instruction is "you
+        // have written the claim twice; @statement is the one that is read".
+        if (statementKey !== "" && normalise(toSnakeCase(name)) === statementKey) {
+            out.push(warn(path, WARN_REQUIREMENT_NAME_RESTATES_STATEMENT, `name '${name}' says the same thing as @statement. The claim belongs in @statement, which every ` +
+                `surface reads; the name is an address and is better as a short identifier.`));
+        }
+        else if (name.trim().split(/\s+/).filter((w) => w !== "").length >= PROSE_WORD_COUNT) {
+            out.push(warn(path, WARN_REQUIREMENT_NAME_READS_AS_PROSE, `name '${name}' reads as a sentence. The name is an address — the dotted path other entries and ` +
+                `the generated stub filename are built from — so a short identifier keeps both legible. Put the ` +
+                `prose in @statement.`));
+        }
+        // -- required prose that is present but says nothing -----------------------
+        // The loader enforces PRESENCE (min: 1), never content, so `statement: ""`
+        // loads clean today and satisfies a required attribute with nothing in it.
+        for (const slot of [REQUIREMENT_ATTR_STATEMENT, REQUIREMENT_ATTR_COUNTEREXAMPLE]) {
+            // OWN-ONLY: the fix is deleting or filling one declaration. See readOwnSlot.
+            const value = readOwnSlot(node, slot);
+            if (value !== undefined && value.trim() === "") {
+                out.push(warn(path, WARN_REQUIREMENT_PROSE_EMPTY, `@${slot} is declared but empty. The loader requires the attribute to be present, not to say ` +
+                    `anything — an empty one passes every check while recording nothing.`));
+            }
+        }
+        // -- two slots holding one sentence ---------------------------------------
+        // The padding failure the authoring guidance names: restating the claim under a
+        // second heading reads as diligence and makes every later reader trust the
+        // ledger less. Only EXACT repeats are reported, whole or as the description's
+        // leading sentence; paraphrase is the broader failure and no mechanical rule
+        // reaches it without inventing findings.
+        if (statementKey !== "") {
+            // No blank-check needed: this arm only runs when `statementKey` is non-empty,
+            // and a blank description normalises to "" — which cannot equal it. That makes
+            // this guard identical to the `counterexample` arm below.
+            const description = readSlot(node, DOC_ATTR_DESCRIPTION);
+            if (description !== undefined) {
+                if (normalise(description) === statementKey) {
+                    out.push(warn(path, WARN_REQUIREMENT_PROSE_DUPLICATED, `description repeats @statement verbatim. @statement already IS the description of what the ` +
+                        `requirement is; description holds the SCOPE — what the claim covers, what it deliberately ` +
+                        `does not, which sibling entry owns the rest. If the scope is obvious, leave it off.`));
+                }
+                else if (leadingSentenceMatches(description, statementKey)) {
+                    out.push(warn(path, WARN_REQUIREMENT_PROSE_DUPLICATED, `description opens by repeating @statement verbatim, then continues. Drop the first sentence — ` +
+                        `it is already read from @statement, and description is only the scope that follows it.`));
+                }
+            }
+            const counterexample = readSlot(node, REQUIREMENT_ATTR_COUNTEREXAMPLE);
+            if (counterexample !== undefined && normalise(counterexample) === statementKey) {
+                out.push(warn(path, WARN_REQUIREMENT_PROSE_DUPLICATED, `@counterexample repeats @statement verbatim. It must describe what BREAKING the claim looks ` +
+                    `like — the thing you could point at to falsify it — which is what makes the claim checkable.`));
+            }
+        }
+        // -- content written where nothing reads it --------------------------------
+        for (const slot of INERT_SLOTS) {
+            // OWN-ONLY: the fix is deleting one attribute. See readOwnSlot.
+            const value = readOwnSlot(node, slot);
+            if (value === undefined || value.trim() === "")
+                continue;
+            out.push(warn(path, WARN_REQUIREMENT_INERT_DOC_SLOT, `@${slot} says nothing here that @${REQUIREMENT_ATTR_STATEMENT} does not. A requirement's ` +
+                `statement is REQUIRED and is already the one-line sentence, so a summary beside it can only ` +
+                `repeat it — and no requirement surface reads it. Its content is invisible: ${excerpt(value)}. ` +
+                `Delete it. (@title is different and is NOT flagged: it is chartered as the entry's LABEL, ` +
+                `because a requirement's name is an identifier.)`));
+        }
+        // -- an id is not a label -------------------------------------------------
+        const title = readOwnSlot(node, DOC_ATTR_TITLE);
+        if (title !== undefined && TITLE_IS_AN_ID.test(title.trim())) {
+            out.push(warn(path, WARN_REQUIREMENT_TITLE_IS_AN_ID, `@title opens with a catalogue or ticket id: ${excerpt(title)}. A title is a NOUN PHRASE and ` +
+                `an id is not a name, so this is two things in one slot. SPLIT them — put the id in ` +
+                `@${REQUIREMENT_ATTR_TRACKED_BY}, which is the free-form reference slot and IS read, and leave ` +
+                `the phrase as the title. Moving the whole string would throw the label away.`));
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=requirement-lint.js.map

package/dist/src/lib/requirement-lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirement-lint.js","sourceRoot":"","sources":["../../../src/lib/requirement-lint.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,EAAE;AACF,kFAAkF;AAClF,kFAAkF;AAClF,EAAE;AACF,gFAAgF;AAChF,iFAAiF;AACjF,gDAAgD;AAChD,iFAAiF;AACjF,mFAAmF;AACnF,gFAAgF;AAChF,mFAAmF;AACnF,EAAE;AACF,oFAAoF;AACpF,oFAAoF;AACpF,qFAAqF;AACrF,iDAAiD;AACjD,EAAE;AACF,oFAAoF;AACpF,gFAAgF;AAChF,qFAAqF;AACrF,kFAAkF;AAClF,EAAE;AACF,qFAAqF;AACrF,sFAAsF;AACtF,sFAAsF;AACtF,qFAAqF;AACrF,iFAAiF;AACjF,iFAAiF;AACjF,EAAE;AACF,mFAAmF;AACnF,qFAAqF;AACrF,sFAAsF;AACtF,oFAAoF;AACpF,2EAA2E;AAE3E,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,+BAA+B,EAC/B,0BAA0B,EAC1B,2BAA2B;AAC3B,+EAA+E;AAC/E,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAC9E,+EAA+E;AAC/E,+DAA+D;AAC/D,WAAW,GAEZ,MAAM,0BAA0B,CAAC;AAClC,mFAAmF;AACnF,mFAAmF;AACnF,oFAAoF;AACpF,iFAAiF;AACjF,uDAAuD;AACvD,OAAO,EACL,4BAA4B,GAC7B,MAAM,wBAAwB,CAAC;AAEhC,MAAM,CAAC,MAAM,qCAAqC,GAAG,uCAAuC,CAAC;AAC7F,MAAM,CAAC,MAAM,oCAAoC,GAAG,sCAAsC,CAAC;AAC3F,MAAM,CAAC,MAAM,wCAAwC,GAAG,0CAA0C,CAAC;AACnG,MAAM,CAAC,MAAM,iCAAiC,GAAG,mCAAmC,CAAC;AACrF,MAAM,CAAC,MAAM,4BAA4B,GAAG,8BAA8B,CAAC;AAC3E,MAAM,CAAC,MAAM,+BAA+B,GAAG,iCAAiC,CAAC;AACjF,MAAM,CAAC,MAAM,+BAA+B,GAAG,iCAAiC,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,aAAa,GAAG,uBAAuB,CAAC;AAE9C;;;;;;;aAOa;AACb,SAAS,YAAY,CAAC,CAAS;IAC7B,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,iCAAiC,CAAC;IACxD,8EAA8E;IAC9E,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;AAC7F,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,GAAG,CAAC,gBAAgB,CAAU,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,MAAM,cAAc,GAAG,oBAAoB,CAAC;AAE5C;;;iFAGiF;AACjF,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AAC/D,CAAC;AAED;;;;;;;uDAOuD;AACvD,SAAS,sBAAsB,CAAC,IAAY,EAAE,GAAW;IACvD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;AACzD,CAAC;AAED;;;wEAGwE;AACxE,SAAS,QAAQ,CAAC,IAAc,EAAE,IAAY;IAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAS,WAAW,CAAC,IAAc,EAAE,IAAY;IAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACnD,CAAC;AAED;;sCAEsC;AACtC,SAAS,OAAO,CAAC,KAAa;IAC5B,MAAM,KAAK,GAAG,EAAE,CAAC;IACjB,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/C,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACrF,CAAC;AAED,SAAS,IAAI,CAAC,IAAY,EAAE,IAAY,EAAE,OAAe;IACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAc;AACd;;;2DAG2D;AAC3D,YAA6C,4BAA4B,CAAC,IAAI,CAAC;IAE/E,MAAM,GAAG,GAAiB,EAAE,CAAC;IAE7B,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,SAAS,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAEvB,4EAA4E;QAC5E,yEAAyE;QACzE,6EAA6E;QAC7E,+EAA+E;QAC/E,6DAA6D;QAC7D,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAChE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,QAAQ,CAAC,IAAI,CAAC,YAAY,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;aAC7C,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,IAAI;YAAE,QAAQ,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;QACnF,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,qCAAqC,EACvD,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,gCAAgC;gBACvF,mDAAmD,IAAI,sCAAsC;gBAC7F,yFAAyF;gBACzF,aAAa,CAAC,CAAC,CAAC;QACpB,CAAC;QAED,MAAM,YAAY,GAAG,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC,IAAI,EAAE,CAAC,CAAC;QAEjF,4EAA4E;QAC5E,+EAA+E;QAC/E,+EAA+E;QAC/E,qEAAqE;QACrE,IAAI,YAAY,KAAK,EAAE,IAAI,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,YAAY,EAAE,CAAC;YACzE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,wCAAwC,EAC1D,SAAS,IAAI,oFAAoF;gBACjG,4EAA4E,CAAC,CAAC,CAAC;QACnF,CAAC;aAAM,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,IAAI,gBAAgB,EAAE,CAAC;YACvF,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,oCAAoC,EACtD,SAAS,IAAI,oFAAoF;gBACjG,iGAAiG;gBACjG,sBAAsB,CAAC,CAAC,CAAC;QAC7B,CAAC;QAED,6EAA6E;QAC7E,2EAA2E;QAC3E,2EAA2E;QAC3E,KAAK,MAAM,IAAI,IAAI,CAAC,0BAA0B,EAAE,+BAA+B,CAAC,EAAE,CAAC;YACjF,6EAA6E;YAC7E,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACtC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;gBAC/C,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,4BAA4B,EAC9C,IAAI,IAAI,sFAAsF;oBAC9F,qEAAqE,CAAC,CAAC,CAAC;YAC5E,CAAC;QACH,CAAC;QAED,4EAA4E;QAC5E,gFAAgF;QAChF,2EAA2E;QAC3E,8EAA8E;QAC9E,6EAA6E;QAC7E,yCAAyC;QACzC,IAAI,YAAY,KAAK,EAAE,EAAE,CAAC;YACxB,8EAA8E;YAC9E,+EAA+E;YAC/E,0DAA0D;YAC1D,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;YACzD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;gBAC9B,IAAI,SAAS,CAAC,WAAW,CAAC,KAAK,YAAY,EAAE,CAAC;oBAC5C,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,iCAAiC,EACnD,6FAA6F;wBAC7F,4FAA4F;wBAC5F,qFAAqF,CAAC,CAAC,CAAC;gBAC5F,CAAC;qBAAM,IAAI,sBAAsB,CAAC,WAAW,EAAE,YAAY,CAAC,EAAE,CAAC;oBAC7D,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,iCAAiC,EACnD,gGAAgG;wBAChG,wFAAwF,CAAC,CAAC,CAAC;gBAC/F,CAAC;YACH,CAAC;YAED,MAAM,cAAc,GAAG,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC,CAAC;YACvE,IAAI,cAAc,KAAK,SAAS,IAAI,SAAS,CAAC,cAAc,CAAC,KAAK,YAAY,EAAE,CAAC;gBAC/E,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,iCAAiC,EACnD,8FAA8F;oBAC9F,8FAA8F,CAAC,CAAC,CAAC;YACrG,CAAC;QACH,CAAC;QAED,6EAA6E;QAC7E,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,gEAAgE;YAChE,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACtC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;gBAAE,SAAS;YACzD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,+BAA+B,EACjD,IAAI,IAAI,4BAA4B,0BAA0B,6BAA6B;gBAC3F,8FAA8F;gBAC9F,8EAA8E,OAAO,CAAC,KAAK,CAAC,IAAI;gBAChG,4FAA4F;gBAC5F,iDAAiD,CAAC,CAAC,CAAC;QACxD,CAAC;QAED,4EAA4E;QAC5E,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAChD,IAAI,KAAK,KAAK,SAAS,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAC7D,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,+BAA+B,EACjD,+CAA+C,OAAO,CAAC,KAAK,CAAC,iCAAiC;gBAC9F,qFAAqF;gBACrF,IAAI,2BAA2B,iEAAiE;gBAChG,8EAA8E,CAAC,CAAC,CAAC;QACrF,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/cli",
-  "version": "0.24.1",
+  "version": "0.24.2",
   "description": "CLI for MetaObjects: scaffold, codegen, migrate, and drift-detection commands.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -49,15 +49,15 @@
   ],
   "dependencies": {
     "@libsql/kysely-libsql": "^0.4.0",
-    "@metaobjectsdev/codegen-ts": "0.24.1",
-    "@metaobjectsdev/codegen-ts-react": "0.24.1",
-    "@metaobjectsdev/codegen-ts-tanstack": "0.24.1",
-    "@metaobjectsdev/docs-site": "0.24.1",
-    "@metaobjectsdev/metadata": "0.24.1",
-    "@metaobjectsdev/migrate-ts": "0.24.1",
-    "@metaobjectsdev/render": "0.24.1",
-    "@metaobjectsdev/runtime-ts": "0.24.1",
-    "@metaobjectsdev/sdk": "0.24.1",
+    "@metaobjectsdev/codegen-ts": "0.24.2",
+    "@metaobjectsdev/codegen-ts-react": "0.24.2",
+    "@metaobjectsdev/codegen-ts-tanstack": "0.24.2",
+    "@metaobjectsdev/docs-site": "0.24.2",
+    "@metaobjectsdev/metadata": "0.24.2",
+    "@metaobjectsdev/migrate-ts": "0.24.2",
+    "@metaobjectsdev/render": "0.24.2",
+    "@metaobjectsdev/runtime-ts": "0.24.2",
+    "@metaobjectsdev/sdk": "0.24.2",
     "@toon-format/toon": "^2.3.0",
     "jiti": "^2.4.0"
   },

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
@@ -56,9 +58,10 @@ 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 in JSON and YAML metadata alike.\n" +
+          "  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" +
-          "  Retirements needing a human decision are REFUSED and listed with their guide.\n\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;
@@ -139,13 +142,16 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
     );
   }
 
-  // Every conclusion states how many files it is a conclusion ABOUT. "No retired vocabulary
-  // 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.
+  // 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(`meta upgrade — no retired vocabulary found (${scope}).`);
+    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

package/src/commands/verify.ts

@@ -17,7 +17,10 @@ import { FileProvider } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.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;

package/src/index.ts

@@ -145,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
@@ -152,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
 

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,