@metaobjectsdev/cli 0.22.1 → 0.23.1-rc.1

package/src/lib/requirement-check.ts

@@ -31,6 +31,7 @@ import {
   REQUIREMENT_MIN_LEVEL,
   REQUIREMENT_MAX_LEVEL,
   REQUIREMENT_LEVEL_MEMBER,
+  REQUIREMENT_DISPOSITION_DEFERRED,
   REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES,
   resolveObjectRef,
   didYouMeanHint,
@@ -57,6 +58,26 @@ export const ERR_REQUIREMENT_L4_NOT_OBJECT = "ERR_REQUIREMENT_L4_NOT_OBJECT";
 export const ERR_REQUIREMENT_L5_NOT_MEMBER = "ERR_REQUIREMENT_L5_NOT_MEMBER";
 export const ERR_REQUIREMENT_ARCH_NO_IMPLEMENTERS = "ERR_REQUIREMENT_ARCH_NO_IMPLEMENTERS";
 export const WARN_REQUIREMENT_OBJECT_UNCLAIMED = "WARN_REQUIREMENT_OBJECT_UNCLAIMED";
+export const WARN_REQUIREMENT_DISPOSITION_NOT_APPLICABLE = "WARN_REQUIREMENT_DISPOSITION_NOT_APPLICABLE";
+export const WARN_REQUIREMENT_DEFERRED_UNTRACKED = "WARN_REQUIREMENT_DEFERRED_UNTRACKED";
+export const WARN_REQUIREMENT_NOTHING_IMPLEMENTS = "WARN_REQUIREMENT_NOTHING_IMPLEMENTS";
+
+/** Counts behind the summary line `meta verify` prints on every run, clean or
+ *  not. A clean run that says nothing cannot distinguish "checked, all good"
+ *  from "checked nothing" — and a ledger that skipped an entire grain reads
+ *  identically to a complete one. */
+export interface RequirementSummary {
+  total: number;
+  functional: number;
+  architectural: number;
+  byStatus: Record<string, number>;
+  /** partial or planned with NO disposition recorded — the unreviewed gaps. */
+  undecided: number;
+  /** deferred entries naming no ticket, so nobody will be reminded. */
+  deferredUntracked: number;
+  entitiesTotal: number;
+  entitiesClaimed: number;
+}
 
 /** Severity of the object-coverage gate. Promotion to `"error"` is a one-line
  *  flip here, which activates an already-written test rather than requiring new
@@ -95,6 +116,79 @@ export function splitMemberRef(ref: string): { owner: string; path: string[] } {
   return { owner: ref.slice(0, dot), path: ref.slice(dot + 1).split(".") };
 }
 
+/** Resolution keys of every root-level object whose `extends` chain reaches
+ *  `ancestor`. Walks the RESOLVED super pointer rather than the raw string, so a
+ *  cross-package or dotted reference resolves the same way the loader resolved
+ *  it — reading `superRef` here would be a second, divergent resolver. */
+function subtypesOf(root: MetaData, ancestor: MetaData): string[] {
+  const out: string[] = [];
+  for (const cand of root.children()) {
+    if (cand.type !== TYPE_OBJECT || cand === ancestor) continue;
+    const seen = new Set<MetaData>();
+    let cur = cand.superData;
+    while (cur !== undefined && !seen.has(cur)) {
+      seen.add(cur);
+      if (cur === ancestor) { out.push(cand.resolutionKey()); break; }
+      cur = cur.superData;
+    }
+  }
+  return out;
+}
+
+/** True when this requirement, or anything nested beneath it, names an
+ *  implementing node. Subtree-scoped deliberately: an L1 solution that delegates
+ *  everything to its children implements nothing directly, and flagging that
+ *  would fire on the correct shape of every tree. */
+function subtreeClaimsAnything(req: MetaRequirement): boolean {
+  if (req.implementedBy().length > 0) return true;
+  for (const child of req.children()) {
+    if (child.type !== TYPE_REQUIREMENT) continue;
+    if (subtreeClaimsAnything(child as MetaRequirement)) return true;
+  }
+  return false;
+}
+
+/**
+ * Resolve the owner segment of an `@implementedBy` reference to the node it names.
+ *
+ * OBJECTS FIRST, through the loader's own resolver, so package-local binding stays the
+ * ADR-0042 contract and never a parallel name scan (#228).
+ *
+ * Then ROOT-LEVEL NON-OBJECT nodes — `template.prompt` and its siblings today. The
+ * attribute is documented as naming "the model nodes realising this requirement", and a
+ * declared prompt is one: it is the durable artifact a capability like "the game master
+ * is told what the party can see" actually lives in. Resolving only objects meant the
+ * prompt estate — the thing whose retirement is hardest to see in a model, since a
+ * removed prompt leaves no table behind — was the one part of a model that could not
+ * carry a status. So L4 means "a declared top-level model node", not "an object".
+ *
+ * Requirements themselves are excluded: hierarchy is nesting, and a requirement claiming
+ * a requirement would be a second, contradictory parent mechanism.
+ */
+function resolveClaimTarget(root: MetaData, owner: string, referrerPkg: string): MetaData | undefined {
+  const { node } = resolveObjectRef(root, owner, referrerPkg);
+  if (node !== undefined) return node;
+
+  const candidates = root
+    .children()
+    .filter((c) => c.type !== TYPE_OBJECT && c.type !== TYPE_REQUIREMENT);
+
+  // A fully-qualified reference binds exactly, like every other FQN in the model.
+  if (owner.includes(PACKAGE_SEPARATOR)) {
+    return candidates.find((c) => c.resolutionKey() === owner);
+  }
+  // A bare reference prefers the referrer's own package, then a root-level node of that
+  // bare name. An ambiguous bare name binds NOTHING — same fail-closed rule objects use,
+  // because silently picking one of two same-named nodes is how a claim ends up pointing
+  // at the wrong thing without anyone noticing.
+  const local = referrerPkg === "" ? [] : candidates.filter((c) => c.resolutionKey() === `${referrerPkg}${PACKAGE_SEPARATOR}${owner}`);
+  if (local.length === 1) return local[0];
+  // Root-level (unpackaged) only, matching resolveObjectRef's own bare fallback. A bare
+  // ref must not reach into an arbitrary package just because the name is unique there.
+  const bare = candidates.filter((c) => c.name === owner && c.resolutionKey() === owner);
+  return bare.length === 1 ? bare[0] : undefined;
+}
+
 /** Walk dotted member segments by CHILD NAME from an object node. */
 function resolveMember(obj: MetaData, path: string[]): MetaData | undefined {
   let cur: MetaData | undefined = obj;
@@ -120,6 +214,64 @@ export function collectRequirements(root: MetaData): MetaRequirement[] {
   return out;
 }
 
+/**
+ * Resolution keys of every object claimed by a requirement.
+ *
+ * SHARED by the gate and the summary deliberately. The two used to compute this
+ * separately and drifted: the summary missed the extends-chain propagation the
+ * gate applies to an ARCHITECTURAL claim, so a project using the documented
+ * BaseEntity pattern got a summary reporting entities as unclaimed while the
+ * gate beneath it named none. A summary that contradicts its own diagnostics
+ * reads as a measurement and cannot be reconciled with the run that produced it.
+ */
+function claimedObjectKeys(root: MetaData, reqs: MetaRequirement[]): Set<string> {
+  const claimed = new Set<string>();
+  for (const req of reqs) {
+    // A PLANNED requirement never contributes to coverage. Otherwise the
+    // cheapest way to clear an unclaimed-entity warning would be to declare an
+    // intention — the gate would measure ambition rather than work.
+    if (req.isPlanned()) continue;
+    // referrerPkg is the requirement's own effective package, so a bare ref
+    // binds package-locally under the ADR-0042 contract — the loader's own
+    // resolver, never a parallel name scan (#228).
+    const referrerPkg = req.package ?? req.fileDefaultPackage ?? "";
+    for (const ref of req.implementedBy()) {
+      const { owner, path } = splitMemberRef(ref);
+      const node = resolveClaimTarget(root, owner, referrerPkg);
+      if (node === undefined) continue;
+      if (path.length > 0 && resolveMember(node, path) === undefined) continue;
+      claimed.add(node.resolutionKey());
+      // ARCHITECTURAL claims propagate DOWN the extends chain; functional ones
+      // do not. A policy ("every row is addressable") claimed on an abstract
+      // BaseEntity genuinely holds for everything extending it — that is what
+      // universality means, and without this the documented BaseEntity pattern
+      // is worse than not using it. A functional claim is the opposite: it says
+      // this entity exists for a REASON, and inheriting a reason from a shared
+      // base would mean adding an entity no longer forces anyone to say what it
+      // is for. Same mechanism, opposite polarity — as everywhere else in the
+      // subtype split.
+      if (req.subType === REQUIREMENT_SUBTYPE_ARCHITECTURAL) {
+        for (const sub of subtypesOf(root, node)) claimed.add(sub);
+      }
+    }
+  }
+  return claimed;
+}
+
+/**
+ * The entities object coverage measures — and the same set for the gate and the
+ * summary, for the reason given on `claimedObjectKeys`.
+ *
+ * An ABSTRACT entity is shape, not data: there is no table and no rows, so
+ * demanding a capability claim for it is the same category error as demanding
+ * one for an object.value. It is exempt for the same reason.
+ */
+function coverableEntities(root: MetaData): MetaData[] {
+  return root.children().filter(
+    (n) => n.type === TYPE_OBJECT && n.subType === OBJECT_SUBTYPE_ENTITY && !n.isAbstract,
+  );
+}
+
 /**
  * Check the requirement tree against the loaded model.
  *
@@ -133,20 +285,31 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
   const reqs = collectRequirements(root);
   if (reqs.length === 0) return out; // opt-in by declaration — no requirements, nothing to say
 
-  const claimedObjects = new Set<string>();
+  const claimedObjects = claimedObjectKeys(root, reqs);
 
   for (const req of reqs) {
     const architectural = req.subType === REQUIREMENT_SUBTYPE_ARCHITECTURAL;
     const level = req.level();
     const refs = req.implementedBy();
 
-    if (!architectural) {
-      if (level === undefined || !Number.isInteger(level)
+    // -- the level rules -------------------------------------------------------
+    // A functional requirement MUST be levelled. An architectural one MAY be,
+    // and levelling is the OPT-IN: unlevelled it is the original flat,
+    // object-independent policy and these rules must not touch it. Once a level
+    // is present the node has joined a tree, and `@level`'s own registered
+    // description promises that "the same rules as functional apply: nesting
+    // must agree with the level". Enforcing that here is what makes the promise
+    // true — a levelled architectural node used to be exempt from BOTH checks,
+    // so an ISO-25010 tree could re-ascend or declare a level 7 in silence.
+    const levelled = level !== undefined;
+    if (!architectural || levelled) {
+      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,
           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.`,
+            `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.` : ``),
         });
       }
       // Nesting IS the hierarchy, so a child must sit strictly below its parent.
@@ -180,13 +343,19 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
       // binds package-locally under the ADR-0042 contract — the loader's own
       // resolver, never a parallel name scan (#228).
       const referrerPkg = req.package ?? req.fileDefaultPackage ?? "";
-      const { node } = resolveObjectRef(root, owner, referrerPkg);
+      const node = resolveClaimTarget(root, owner, referrerPkg);
       const isObjectRef = path.length === 0;
 
-      if (node !== undefined && (isObjectRef || resolveMember(node, path) !== undefined)) {
-        claimedObjects.add(node.resolutionKey());
-      }
-
+      // GRAIN, and it stays functional-only DELIBERATELY. On a functional
+      // requirement L4 and L5 MEAN "an object" and "a member" — that is what the
+      // allocation step allocates. On a levelled architectural one the upper
+      // tiers are a quality taxonomy and L4/L5 retain only their link-floor
+      // meaning, so a policy whose claim set legitimately mixes grains ("every
+      // money FIELD declares its currency", claimed alongside the entities that
+      // hold them) must not be forced to split by grain to say so. Extending
+      // this to architectural would be a new rule, not the missing half of an
+      // existing one — unlike the level checks above, which `@level` already
+      // promised.
       if (!architectural && level === REQUIREMENT_LINK_FLOOR_LEVEL && !isObjectRef) {
         out.push({
           severity: "error", code: ERR_REQUIREMENT_L4_NOT_OBJECT, name: req.name,
@@ -227,13 +396,59 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
     const status = req.status();
     const live = status !== undefined
       && REQUIREMENT_STATUSES_REQUIRING_LIVE_NODES.includes(status as RequirementStatus);
-    if (architectural && live && refs.length === 0) {
+    // Two exemptions, both structural rather than lenient.
+    //
+    // `planned` — a policy that is not built yet is SUPPOSED to be applied to
+    // nothing, so the check would fire on precisely the entries it should stay
+    // quiet about.
+    //
+    // An ORGANISATIONAL node in a levelled architectural tree — an "ISO 25010
+    // Security" at L1 delegates to its children and names nothing, exactly as
+    // an L1 functional node does. mayReferenceModel() is the right predicate
+    // because it already encodes "is this tier allowed to name the model at
+    // all": true for a flat policy (the original form), false for L1-L3 of a
+    // 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,
         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.`,
       });
     }
+
+    // -- disposition: the decision, not the state -----------------------------
+    const disposition = req.disposition();
+    if (disposition !== undefined && !req.hasOutstandingWork()) {
+      out.push({
+        severity: "warn", code: WARN_REQUIREMENT_DISPOSITION_NOT_APPLICABLE, name: req.name,
+        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.`,
+      });
+    }
+    // -- functional existence, SUBTREE-scoped ---------------------------------
+    // A functional requirement's check is EXISTENCE: it fails when nothing
+    // implements it. But an organisational tier legitimately implements nothing
+    // ITSELF — it delegates to children, and that is the whole shape of the
+    // tree. So the question is not "does this node claim anything" but "does
+    // anything in this subtree claim anything". A live L1 whose entire subtree
+    // 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,
+        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.`,
+      });
+    }
+
+    if (disposition === REQUIREMENT_DISPOSITION_DEFERRED && req.trackedBy().length === 0) {
+      out.push({
+        severity: "warn", code: WARN_REQUIREMENT_DEFERRED_UNTRACKED, name: req.name,
+        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.`,
+      });
+    }
   }
 
   // -- object coverage: adding an entity forces a requirement -----------------
@@ -257,8 +472,7 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
   //
   // So a green run means "every entity is claimed by something", not "every node is
   // described". The stronger reading would be false.
-  for (const ent of root.children()) {
-    if (ent.type !== TYPE_OBJECT || ent.subType !== OBJECT_SUBTYPE_ENTITY) continue;
+  for (const ent of coverableEntities(root)) {
     const key = ent.resolutionKey();
     if (!claimedObjects.has(key)) {
       out.push({
@@ -270,3 +484,52 @@ export function checkRequirements(root: MetaData): Diagnostic[] {
 
   return out;
 }
+
+/**
+ * Count what the ledger contains, for the line `meta verify` prints on EVERY
+ * run — including a clean one.
+ *
+ * This exists because silence is ambiguous. A run that prints nothing cannot be
+ * told apart from a run that checked nothing, and an entry that skipped a whole
+ * grain of the model looks exactly like one that covered it. The counts below
+ * 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);
+  if (reqs.length === 0) return undefined; // opt-in by declaration
+
+  const summary: RequirementSummary = {
+    total: reqs.length,
+    functional: 0,
+    architectural: 0,
+    byStatus: {},
+    undecided: 0,
+    deferredUntracked: 0,
+    entitiesTotal: 0,
+    entitiesClaimed: 0,
+  };
+
+  for (const req of reqs) {
+    if (req.subType === REQUIREMENT_SUBTYPE_ARCHITECTURAL) summary.architectural++;
+    else summary.functional++;
+
+    const status = req.status();
+    if (status !== undefined) summary.byStatus[status] = (summary.byStatus[status] ?? 0) + 1;
+
+    if (req.hasOutstandingWork() && req.disposition() === undefined) summary.undecided++;
+    if (req.disposition() === REQUIREMENT_DISPOSITION_DEFERRED && req.trackedBy().length === 0) {
+      summary.deferredUntracked++;
+    }
+  }
+
+  // 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);
+  for (const ent of coverableEntities(root)) {
+    summary.entitiesTotal++;
+    if (claimed.has(ent.resolutionKey())) summary.entitiesClaimed++;
+  }
+
+  return summary;
+}