@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.2

package/dist/commands/validate/fleet/obligations.js

@@ -0,0 +1,270 @@
+/**
+ * The architectural obligation axis, graded against the fleet it is about.
+ *
+ * `core/obligations/obligations.ts` states what the axis IS and why it has this
+ * shape. This module is the four questions asked of a fleet that has one, and
+ * the order they are asked in — the same division `checks/fleet-shape.ts` keeps
+ * for the authorization and capability vocabularies, which this sits beside on
+ * the `landscape` target for their reason: an obligation crosses services by
+ * construction, so no service target can answer for it.
+ *
+ * THE FOUR ARE TWO PAIRS, and each pair is one join read in both directions.
+ * A tag nothing declares is an ERROR (`obligation.unknown`) and a declaration
+ * nothing tags is a WARNING (`obligation.unapplied`) — exactly the asymmetry
+ * `permissions.unknown`/`permissions.unenforced` already carry, and for the
+ * same reason: a typo in a tag reads like a rule, while a word nobody has
+ * adopted yet is an honest state. Then a tagged object no requirement covers is
+ * a WARNING (`obligation.uncovered`) and an `adr:` naming no file is an ERROR
+ * (`obligation.adr-missing`): the team's work being outstanding is normal, and
+ * a pointer at a decision nobody can read is not.
+ *
+ * `obligation.uncovered` IS THE PREREQUISITE THE ROADMAP NAMED. `c4.uncovered`
+ * has always been able to say "this architecture object owes a requirement",
+ * but only about a NEW tagged element in a feature's `delta.likec4` — never
+ * about the map the fleet actually runs on. This asks the same question of the
+ * LIVING landscape, against the union of every service's living `arch.spec.md`
+ * `Covers:` lines, which is the index that did not exist before.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {} from "../../../core/c4/likec4.js";
+import { closeIds, coversDeployEdge, coversDeployNode, coversEdge, coversElement, } from "../../../core/c4/arch.js";
+import { NO_DEPLOYMENT } from "../../../core/c4/parsed/deployment.js";
+import { taggedDeployment } from "../../../core/deployment/objects.js";
+import { elementService } from "../../../core/c4/resolve/service.js";
+import { OBLIGATION_TAG_PREFIX } from "../../../core/obligations/obligations.js";
+import { servicePathsAt } from "../../../core/repo/paths.js";
+import {} from "../../../core/repo/entries.js";
+import {} from "../../../core/vocabulary/report.js";
+import { FleetContext } from "../../../core/fleet-context.js";
+import { readRequirementsDocument, parseRequirements } from "../../../core/document/parse.js";
+import { coversEntries } from "../checks/requirements.js";
+/**
+ * The half that does not depend on the map: the file reads, and its `adr:`
+ * pointers resolve.
+ *
+ * Separate from the map questions because the landscape target returns early
+ * twice — an absent map, and one that did not parse — and a broken vocabulary
+ * must still be named in exactly the runs where somebody is fixing something
+ * else. The same placement `permissionFindings` and `capabilityFleetFindings`
+ * already have, one level of precision finer.
+ */
+export function obligationVocabularyFindings(docsDir, vocabulary) {
+    if (!vocabulary.present)
+        return [];
+    if (vocabulary.invalid !== undefined) {
+        // Reported ALONE, exactly as `permissions.invalid` and `capability.invalid`
+        // are: every `#obl-` tag in the fleet resolves against this file, so grading
+        // them on top of a broken vocabulary is a cascade, not a diagnosis.
+        return [
+            {
+                severity: "error",
+                code: "obligation.invalid",
+                message: `landscape: architecture/obligations.yaml does not read as a vocabulary — ${vocabulary.invalid}. ` +
+                    "Every `#obl-` tag on the fleet map resolves against this file, so none of them can be graded until it parses. " +
+                    "The shape is `obligations: {<id>: {description, adr}}`, ids spelled with letters, digits, `_` and `-` only.",
+            },
+        ];
+    }
+    return adrFindings(docsDir, [...vocabulary.byId.values()]);
+}
+/** The three questions that need the map, suspended entirely when it could not be read. */
+export async function obligationFindings(check) {
+    const { vocabulary } = check;
+    if (!vocabulary.present || vocabulary.invalid !== undefined)
+        return [];
+    const findings = [];
+    // Which objects carry which obligation. Elements and edges are collected
+    // together because every question below treats them alike: an obligation
+    // applies to a thing on the map, and whether that thing is a box or an arrow
+    // changes only how the message spells it and how `Covers:` matches it.
+    // The enumerated fleet rides in for the deployment half of the walk: an
+    // instance deploys a CONTAINER more often than a whole system, and resolving
+    // which service owns one needs the ancestor walk `serviceResolver` performs.
+    // It is the same set `uncoveredFindings` resolves edge endpoints with, or the
+    // message would name one service and the coverage check count another.
+    const known = new Set(check.services.map((s) => s.id));
+    const tagged = taggedObjects(check.land, known);
+    const applied = new Set(tagged.map((t) => t.obligation));
+    for (const id of [...applied].sort()) {
+        if (vocabulary.byId.has(id))
+            continue;
+        const close = closeIds(id, [...vocabulary.byId.keys()]);
+        findings.push({
+            severity: "error",
+            code: "obligation.unknown",
+            subject: id,
+            message: `landscape: #${OBLIGATION_TAG_PREFIX}${id} tags ${count(tagged.filter((t) => t.obligation === id).length, "object")} on the fleet map, ` +
+                `and architecture/obligations.yaml declares no obligation '${id}'` +
+                (close.length > 0 ? ` — did you mean: ${close.join(", ")}?` : "") +
+                ". A tag that resolves to nothing reads exactly like a rule the fleet keeps: declare it, or fix the tag.",
+            details: tagged.filter((t) => t.obligation === id).map((t) => t.where),
+        });
+    }
+    const unapplied = [...vocabulary.byId.keys()].filter((id) => !applied.has(id)).sort();
+    if (unapplied.length > 0) {
+        findings.push({
+            severity: "warn",
+            code: "obligation.unapplied",
+            message: `landscape: ${unapplied.length} declared obligation(s) that no \`#${OBLIGATION_TAG_PREFIX}\` tag applies anywhere on the fleet map — ` +
+                "either a decision that was reversed and left its word behind, or one nobody has placed yet. " +
+                "Tag the elements and edges it governs, or drop the declaration; a vocabulary is worth what cites it.",
+            details: unapplied,
+        });
+    }
+    // ONLY A RESOLVED APPLICATION IS ASKED ABOUT COVERAGE. A tag naming no
+    // declared obligation has already earned its error above, and "no requirement
+    // covers #obl-typo" is not a second breach — it is the same one restated in
+    // words that ask the reader to write a requirement for a rule that does not
+    // exist. The use-case axis draws this line in the same place: only a resolved
+    // `#cap-` claim keeps a promise.
+    findings.push(...(await uncoveredFindings(check, tagged.filter((t) => vocabulary.byId.has(t.obligation)))));
+    return findings;
+}
+/**
+ * Every `#obl-` tag on the living map, one entry per (obligation, object) pair.
+ *
+ * A bare `#obl-` slugs to the empty string and is kept as an application on
+ * purpose, exactly as a bare `#cap-` is kept as a claim: the prefix is the
+ * author's opt-in however little follows it, and dropping it as unreserved
+ * would leave an object that asked to be graded silently ungraded. It then
+ * resolves to `obligation.unknown` in every fleet that did not declare an empty
+ * id, which is the honest answer.
+ */
+function taggedObjects(land, known) {
+    const out = [];
+    for (const element of land.elements) {
+        for (const tag of element.tags.filter((t) => t.startsWith(OBLIGATION_TAG_PREFIX))) {
+            out.push({
+                obligation: tag.slice(OBLIGATION_TAG_PREFIX.length),
+                element,
+                where: element.id,
+                subject: elementService(element),
+            });
+        }
+    }
+    for (const edge of land.relationships) {
+        for (const tag of edge.tags.filter((t) => t.startsWith(OBLIGATION_TAG_PREFIX))) {
+            out.push({
+                obligation: tag.slice(OBLIGATION_TAG_PREFIX.length),
+                edge,
+                where: `${edge.source} -> ${edge.target}`,
+                subject: edge.target,
+            });
+        }
+    }
+    // The topology, walked by the same rule and for the reason the rule exists: a
+    // tag is a claim about the object it sits on, and which MODEL that object
+    // lives in is not something a reader of the tag can see. Until this walk the
+    // same undeclared tag was an error on a container and silence on a
+    // datacenter — fail-open, and the case FEAT-1's ARCH-LOAM-DEPLOY-TAGGED was
+    // written about. A fleet that draws no topology contributes nothing here.
+    for (const d of taggedDeployment(land.deployment ?? NO_DEPLOYMENT, land.elements, known, OBLIGATION_TAG_PREFIX)) {
+        out.push({
+            obligation: d.obligation,
+            deployed: d,
+            where: d.where,
+            ...(d.service === undefined ? {} : { subject: d.service }),
+        });
+    }
+    return out;
+}
+/**
+ * `obligation.uncovered` — a tagged object no living arch requirement covers.
+ *
+ * The index is the union of EVERY service's living `arch.spec.md` `Covers:`
+ * lines, because an obligation is placed by the architect on the map and met by
+ * whichever team owns the thing it sits on — and a per-service index would
+ * report an edge as uncovered because the requirement that covers it lives in
+ * the service at the other end. `coversEntries` already drops REMOVED
+ * requirements: a retired requirement covers nothing.
+ *
+ * ONE FINDING PER TAGGED OBJECT, subject = the service that owns it, so a
+ * fleet-wide report reads as a worklist per team rather than as one line naming
+ * forty edges.
+ */
+async function uncoveredFindings(check, tagged) {
+    if (tagged.length === 0)
+        return [];
+    const covers = await livingCovers(check);
+    const elements = check.land.elements;
+    const known = new Set(check.services.map((s) => s.id));
+    const covered = (t) => {
+        if (t.element !== undefined)
+            return covers.some((c) => coversElement(c, t.element));
+        if (t.edge !== undefined)
+            return covers.some((c) => coversEdge(c, t.edge, elements, known));
+        const d = t.deployed;
+        return d.edge === undefined
+            ? covers.some((c) => coversDeployNode(c, d.id))
+            : covers.some((c) => coversDeployEdge(c, d.edge.source, d.edge.target));
+    };
+    return tagged
+        .filter((t) => !covered(t))
+        .map((t) => ({
+        severity: "warn",
+        code: "obligation.uncovered",
+        ...(t.subject === undefined ? {} : { subject: t.subject }),
+        message: `${t.where} carries #${OBLIGATION_TAG_PREFIX}${t.obligation} and no living arch requirement covers it — ` +
+            `the obligation is placed and nothing says it is met. Write the requirement in ` +
+            // A region, a datacenter or a cluster is owned by no service, so the
+            // sentence stays general rather than naming a team at random. Every
+            // other object here has a real owner and keeps the actionable form.
+            `${t.subject === undefined ? "the arch.spec.md of whichever service answers for this topology" : `${t.subject}'s arch.spec.md`}` +
+            ` with \`Covers: ${t.where}\` and a scenario that proves it, or drop the tag if the decision no longer applies here.`,
+    }));
+}
+/**
+ * Every `Covers:` entry the LIVING fleet writes, across both requirement
+ * documents of every service.
+ *
+ * Existence is checked for both files and for the same reason
+ * `permissionFindings` checks it: `arch.spec.md` is optional and most of a
+ * legacy fleet has none, while `spec.md` is missing on a half-adopted service —
+ * and `FleetContext.readRequirements` throws ENOENT, which surfaces as
+ * `repository-unavailable` and takes the whole `--all` run down. Both axes are
+ * read, not only the architecture one: `Covers:` is parsed everywhere for one
+ * grammar's sake, and a fleet that wrote its outbox requirement in `spec.md`
+ * has said the thing loam is asking about.
+ */
+async function livingCovers(check) {
+    const entries = [];
+    for (const service of check.services) {
+        const paths = servicePathsAt(service.dir);
+        for (const path of [paths.spec, paths.archSpec]) {
+            if (!existsSync(path))
+                continue;
+            const reqs = check.fleet === undefined
+                ? parseRequirements(await readRequirementsDocument(path))
+                : await check.fleet.readRequirements(path);
+            entries.push(...coversEntries(reqs));
+        }
+    }
+    return entries;
+}
+/**
+ * `obligation.adr-missing` — an `adr:` path that names no file.
+ *
+ * The path is relative to the docs repo root rather than to
+ * `architecture/obligations.yaml`, because that is how a reader of a fleet
+ * document thinks about a fleet path, and because the value is a YAML field
+ * rather than a markdown link — `link.unresolved` grades links written in prose,
+ * and this one is written in a slot loam defined.
+ */
+function adrFindings(docsDir, obligations) {
+    return obligations
+        .filter((o) => o.adr !== undefined && !existsSync(join(docsDir, o.adr)))
+        .map((o) => ({
+        severity: "error",
+        code: "obligation.adr-missing",
+        subject: o.id,
+        message: `landscape: obligation '${o.id}' names \`adr: ${o.adr}\` and no such file exists — ` +
+            "the ADR is where the decision itself is written, so a pointer at nothing leaves every tag citing a rule nobody can read. " +
+            "Fix the path (it is relative to the docs repo root), write the record, or drop the field.",
+    }));
+}
+/** `1 object` / `3 objects` — the plural spelled once, because three messages count things. */
+function count(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+//# sourceMappingURL=obligations.js.map

package/dist/commands/validate/fleet/obligations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"obligations.js","sourceRoot":"","sources":["../../../../src/commands/validate/fleet/obligations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The architectural obligation axis, graded against the fleet it is about.\n *\n * `core/obligations/obligations.ts` states what the axis IS and why it has this\n * shape. This module is the four questions asked of a fleet that has one, and\n * the order they are asked in — the same division `checks/fleet-shape.ts` keeps\n * for the authorization and capability vocabularies, which this sits beside on\n * the `landscape` target for their reason: an obligation crosses services by\n * construction, so no service target can answer for it.\n *\n * THE FOUR ARE TWO PAIRS, and each pair is one join read in both directions.\n * A tag nothing declares is an ERROR (`obligation.unknown`) and a declaration\n * nothing tags is a WARNING (`obligation.unapplied`) — exactly the asymmetry\n * `permissions.unknown`/`permissions.unenforced` already carry, and for the\n * same reason: a typo in a tag reads like a rule, while a word nobody has\n * adopted yet is an honest state. Then a tagged object no requirement covers is\n * a WARNING (`obligation.uncovered`) and an `adr:` naming no file is an ERROR\n * (`obligation.adr-missing`): the team's work being outstanding is normal, and\n * a pointer at a decision nobody can read is not.\n *\n * `obligation.uncovered` IS THE PREREQUISITE THE ROADMAP NAMED. `c4.uncovered`\n * has always been able to say \"this architecture object owes a requirement\",\n * but only about a NEW tagged element in a feature's `delta.likec4` — never\n * about the map the fleet actually runs on. This asks the same question of the\n * LIVING landscape, against the union of every service's living `arch.spec.md`\n * `Covers:` lines, which is the index that did not exist before.\n */\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { type Elem, type LoadedDoc, type Rel } from \"../../../core/c4/likec4.js\";\nimport {\n  closeIds,\n  coversDeployEdge,\n  coversDeployNode,\n  coversEdge,\n  coversElement,\n  type CoversEntry,\n} from \"../../../core/c4/arch.js\";\nimport { NO_DEPLOYMENT } from \"../../../core/c4/parsed/deployment.js\";\nimport { taggedDeployment, type TaggedDeployment } from \"../../../core/deployment/objects.js\";\nimport { elementService } from \"../../../core/c4/resolve/service.js\";\nimport { OBLIGATION_TAG_PREFIX, type ObligationVocabulary } from \"../../../core/obligations/obligations.js\";\nimport { servicePathsAt } from \"../../../core/repo/paths.js\";\nimport { type ServiceEntry } from \"../../../core/repo/entries.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { readRequirementsDocument, parseRequirements } from \"../../../core/document/parse.js\";\nimport { coversEntries } from \"../checks/requirements.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\n\nexport interface ObligationCheck {\n  docsDir: DocsDir;\n  vocabulary: ObligationVocabulary;\n  /**\n   * The living landscape, PARSED. Not nullable, and the absence is the point:\n   * the landscape target returns before it reaches this call when the map is\n   * missing or did not parse, so a run that could not read the map asks none of\n   * the three questions below rather than answering them empty. \"Loam did not\n   * look\" is never the same answer as \"there is nothing there\" — an unreadable\n   * map graded as empty would report every declared obligation as applied\n   * nowhere — and the suspension lives at the call site because that is where\n   * the fact is known. It is also why the vocabulary half is a separate\n   * function: those two verdicts must survive exactly those early returns.\n   */\n  land: LoadedDoc;\n  services: ServiceEntry[];\n  fleet?: FleetContext;\n}\n\n/**\n * The half that does not depend on the map: the file reads, and its `adr:`\n * pointers resolve.\n *\n * Separate from the map questions because the landscape target returns early\n * twice — an absent map, and one that did not parse — and a broken vocabulary\n * must still be named in exactly the runs where somebody is fixing something\n * else. The same placement `permissionFindings` and `capabilityFleetFindings`\n * already have, one level of precision finer.\n */\nexport function obligationVocabularyFindings(docsDir: DocsDir, vocabulary: ObligationVocabulary): Finding[] {\n  if (!vocabulary.present) return [];\n  if (vocabulary.invalid !== undefined) {\n    // Reported ALONE, exactly as `permissions.invalid` and `capability.invalid`\n    // are: every `#obl-` tag in the fleet resolves against this file, so grading\n    // them on top of a broken vocabulary is a cascade, not a diagnosis.\n    return [\n      {\n        severity: \"error\",\n        code: \"obligation.invalid\",\n        message:\n          `landscape: architecture/obligations.yaml does not read as a vocabulary — ${vocabulary.invalid}. ` +\n          \"Every `#obl-` tag on the fleet map resolves against this file, so none of them can be graded until it parses. \" +\n          \"The shape is `obligations: {<id>: {description, adr}}`, ids spelled with letters, digits, `_` and `-` only.\",\n      },\n    ];\n  }\n\n  return adrFindings(docsDir, [...vocabulary.byId.values()]);\n}\n\n/** The three questions that need the map, suspended entirely when it could not be read. */\nexport async function obligationFindings(check: ObligationCheck): Promise<Finding[]> {\n  const { vocabulary } = check;\n  if (!vocabulary.present || vocabulary.invalid !== undefined) return [];\n  const findings: Finding[] = [];\n\n  // Which objects carry which obligation. Elements and edges are collected\n  // together because every question below treats them alike: an obligation\n  // applies to a thing on the map, and whether that thing is a box or an arrow\n  // changes only how the message spells it and how `Covers:` matches it.\n  // The enumerated fleet rides in for the deployment half of the walk: an\n  // instance deploys a CONTAINER more often than a whole system, and resolving\n  // which service owns one needs the ancestor walk `serviceResolver` performs.\n  // It is the same set `uncoveredFindings` resolves edge endpoints with, or the\n  // message would name one service and the coverage check count another.\n  const known = new Set(check.services.map((s) => s.id));\n  const tagged = taggedObjects(check.land, known);\n  const applied = new Set(tagged.map((t) => t.obligation));\n\n  for (const id of [...applied].sort()) {\n    if (vocabulary.byId.has(id)) continue;\n    const close = closeIds(id, [...vocabulary.byId.keys()]);\n    findings.push({\n      severity: \"error\",\n      code: \"obligation.unknown\",\n      subject: id,\n      message:\n        `landscape: #${OBLIGATION_TAG_PREFIX}${id} tags ${count(tagged.filter((t) => t.obligation === id).length, \"object\")} on the fleet map, ` +\n        `and architecture/obligations.yaml declares no obligation '${id}'` +\n        (close.length > 0 ? ` — did you mean: ${close.join(\", \")}?` : \"\") +\n        \". A tag that resolves to nothing reads exactly like a rule the fleet keeps: declare it, or fix the tag.\",\n      details: tagged.filter((t) => t.obligation === id).map((t) => t.where),\n    });\n  }\n\n  const unapplied = [...vocabulary.byId.keys()].filter((id) => !applied.has(id)).sort();\n  if (unapplied.length > 0) {\n    findings.push({\n      severity: \"warn\",\n      code: \"obligation.unapplied\",\n      message:\n        `landscape: ${unapplied.length} declared obligation(s) that no \\`#${OBLIGATION_TAG_PREFIX}\\` tag applies anywhere on the fleet map — ` +\n        \"either a decision that was reversed and left its word behind, or one nobody has placed yet. \" +\n        \"Tag the elements and edges it governs, or drop the declaration; a vocabulary is worth what cites it.\",\n      details: unapplied,\n    });\n  }\n\n  // ONLY A RESOLVED APPLICATION IS ASKED ABOUT COVERAGE. A tag naming no\n  // declared obligation has already earned its error above, and \"no requirement\n  // covers #obl-typo\" is not a second breach — it is the same one restated in\n  // words that ask the reader to write a requirement for a rule that does not\n  // exist. The use-case axis draws this line in the same place: only a resolved\n  // `#cap-` claim keeps a promise.\n  findings.push(...(await uncoveredFindings(check, tagged.filter((t) => vocabulary.byId.has(t.obligation)))));\n  return findings;\n}\n\n/** One place an obligation is applied: which obligation, on what, and how a message names it. */\ninterface TaggedObject {\n  obligation: string;\n  /** The element, the edge, or the deployment object — exactly one is set. */\n  element?: Elem;\n  edge?: Rel;\n  deployed?: TaggedDeployment;\n  /**\n   * How the finding spells this object, and how a `Covers:` line has to: an\n   * element id, `source -> target`, or the `node:` forms.\n   */\n  where: string;\n  /**\n   * What the finding is filed under — the service that owns it, where one\n   * does. ABSENT for a region, a datacenter or a cluster: nobody-s service\n   * runs one, and naming a team that did not ask for the work is worse than\n   * leaving the sentence general.\n   */\n  subject?: string;\n}\n\n/**\n * Every `#obl-` tag on the living map, one entry per (obligation, object) pair.\n *\n * A bare `#obl-` slugs to the empty string and is kept as an application on\n * purpose, exactly as a bare `#cap-` is kept as a claim: the prefix is the\n * author's opt-in however little follows it, and dropping it as unreserved\n * would leave an object that asked to be graded silently ungraded. It then\n * resolves to `obligation.unknown` in every fleet that did not declare an empty\n * id, which is the honest answer.\n */\nfunction taggedObjects(land: LoadedDoc, known: ReadonlySet<string>): TaggedObject[] {\n  const out: TaggedObject[] = [];\n  for (const element of land.elements) {\n    for (const tag of element.tags.filter((t) => t.startsWith(OBLIGATION_TAG_PREFIX))) {\n      out.push({\n        obligation: tag.slice(OBLIGATION_TAG_PREFIX.length),\n        element,\n        where: element.id,\n        subject: elementService(element),\n      });\n    }\n  }\n  for (const edge of land.relationships) {\n    for (const tag of edge.tags.filter((t) => t.startsWith(OBLIGATION_TAG_PREFIX))) {\n      out.push({\n        obligation: tag.slice(OBLIGATION_TAG_PREFIX.length),\n        edge,\n        where: `${edge.source} -> ${edge.target}`,\n        subject: edge.target,\n      });\n    }\n  }\n  // The topology, walked by the same rule and for the reason the rule exists: a\n  // tag is a claim about the object it sits on, and which MODEL that object\n  // lives in is not something a reader of the tag can see. Until this walk the\n  // same undeclared tag was an error on a container and silence on a\n  // datacenter — fail-open, and the case FEAT-1's ARCH-LOAM-DEPLOY-TAGGED was\n  // written about. A fleet that draws no topology contributes nothing here.\n  for (const d of taggedDeployment(land.deployment ?? NO_DEPLOYMENT, land.elements, known, OBLIGATION_TAG_PREFIX)) {\n    out.push({\n      obligation: d.obligation,\n      deployed: d,\n      where: d.where,\n      ...(d.service === undefined ? {} : { subject: d.service }),\n    });\n  }\n  return out;\n}\n\n/**\n * `obligation.uncovered` — a tagged object no living arch requirement covers.\n *\n * The index is the union of EVERY service's living `arch.spec.md` `Covers:`\n * lines, because an obligation is placed by the architect on the map and met by\n * whichever team owns the thing it sits on — and a per-service index would\n * report an edge as uncovered because the requirement that covers it lives in\n * the service at the other end. `coversEntries` already drops REMOVED\n * requirements: a retired requirement covers nothing.\n *\n * ONE FINDING PER TAGGED OBJECT, subject = the service that owns it, so a\n * fleet-wide report reads as a worklist per team rather than as one line naming\n * forty edges.\n */\nasync function uncoveredFindings(check: ObligationCheck, tagged: TaggedObject[]): Promise<Finding[]> {\n  if (tagged.length === 0) return [];\n  const covers = await livingCovers(check);\n  const elements = check.land.elements;\n  const known = new Set(check.services.map((s) => s.id));\n  const covered = (t: TaggedObject): boolean => {\n    if (t.element !== undefined) return covers.some((c) => coversElement(c, t.element!));\n    if (t.edge !== undefined) return covers.some((c) => coversEdge(c, t.edge!, elements, known));\n    const d = t.deployed!;\n    return d.edge === undefined\n      ? covers.some((c) => coversDeployNode(c, d.id!))\n      : covers.some((c) => coversDeployEdge(c, d.edge!.source, d.edge!.target));\n  };\n  return tagged\n    .filter((t) => !covered(t))\n    .map((t) => ({\n      severity: \"warn\" as const,\n      code: \"obligation.uncovered\",\n      ...(t.subject === undefined ? {} : { subject: t.subject }),\n      message:\n        `${t.where} carries #${OBLIGATION_TAG_PREFIX}${t.obligation} and no living arch requirement covers it — ` +\n        `the obligation is placed and nothing says it is met. Write the requirement in ` +\n        // A region, a datacenter or a cluster is owned by no service, so the\n        // sentence stays general rather than naming a team at random. Every\n        // other object here has a real owner and keeps the actionable form.\n        `${t.subject === undefined ? \"the arch.spec.md of whichever service answers for this topology\" : `${t.subject}'s arch.spec.md`}` +\n        ` with \\`Covers: ${t.where}\\` and a scenario that proves it, or drop the tag if the decision no longer applies here.`,\n    }));\n}\n\n/**\n * Every `Covers:` entry the LIVING fleet writes, across both requirement\n * documents of every service.\n *\n * Existence is checked for both files and for the same reason\n * `permissionFindings` checks it: `arch.spec.md` is optional and most of a\n * legacy fleet has none, while `spec.md` is missing on a half-adopted service —\n * and `FleetContext.readRequirements` throws ENOENT, which surfaces as\n * `repository-unavailable` and takes the whole `--all` run down. Both axes are\n * read, not only the architecture one: `Covers:` is parsed everywhere for one\n * grammar's sake, and a fleet that wrote its outbox requirement in `spec.md`\n * has said the thing loam is asking about.\n */\nasync function livingCovers(check: ObligationCheck): Promise<CoversEntry[]> {\n  const entries: CoversEntry[] = [];\n  for (const service of check.services) {\n    const paths = servicePathsAt(service.dir);\n    for (const path of [paths.spec, paths.archSpec]) {\n      if (!existsSync(path)) continue;\n      const reqs =\n        check.fleet === undefined\n          ? parseRequirements(await readRequirementsDocument(path))\n          : await check.fleet.readRequirements(path);\n      entries.push(...coversEntries(reqs));\n    }\n  }\n  return entries;\n}\n\n/**\n * `obligation.adr-missing` — an `adr:` path that names no file.\n *\n * The path is relative to the docs repo root rather than to\n * `architecture/obligations.yaml`, because that is how a reader of a fleet\n * document thinks about a fleet path, and because the value is a YAML field\n * rather than a markdown link — `link.unresolved` grades links written in prose,\n * and this one is written in a slot loam defined.\n */\nfunction adrFindings(docsDir: DocsDir, obligations: readonly { id: string; adr?: string }[]): Finding[] {\n  return obligations\n    .filter((o) => o.adr !== undefined && !existsSync(join(docsDir, o.adr)))\n    .map((o) => ({\n      severity: \"error\" as const,\n      code: \"obligation.adr-missing\",\n      subject: o.id,\n      message:\n        `landscape: obligation '${o.id}' names \\`adr: ${o.adr!}\\` and no such file exists — ` +\n        \"the ADR is where the decision itself is written, so a pointer at nothing leaves every tag citing a rule nobody can read. \" +\n        \"Fix the path (it is relative to the docs repo root), write the record, or drop the field.\",\n    }));\n}\n\n/** `1 object` / `3 objects` — the plural spelled once, because three messages count things. */\nfunction count(n: number, noun: string): string {\n  return `${n} ${noun}${n === 1 ? \"\" : \"s\"}`;\n}\n"]}

package/dist/commands/validate/fleet/scorecard/adoption.js

@@ -0,0 +1,102 @@
+/**
+ * The adoption vocabulary of the fleet scorecard: which contract axes a
+ * service PARTICIPATES in, summed to the fleet's per-axis participation
+ * counts, and the mechanical rule for which warnings the `--all` text report
+ * may fold under a per-axis "not started" banner.
+ *
+ * A leaf on purpose: it imports nothing, so `../report.ts` (the text
+ * renderer) and `./contracts.js` (which computes the per-service booleans)
+ * can both use it without closing a cycle — `adoptionOf` takes the smallest
+ * structural parameter it needs instead of the ContractCounts type,
+ * core/vocabulary/maturity.ts's EdgeSource precedent for staying a leaf.
+ */
+/**
+ * The six contract axes a service adopts one at a time, in the order every
+ * rendering walks them. Participation is a per-service boolean with one
+ * mechanical rule per axis, spelled on `Scorecard.adoption` (./scorecard.js)
+ * where the payload key freezes them.
+ */
+export const ADOPTION_AXES = [
+    "requirements",
+    "arch",
+    "openapi",
+    "asyncapi",
+    "permissions",
+    "capabilities",
+];
+/** Sum the per-service participation booleans into the fleet's counts. */
+export function adoptionOf(perService) {
+    const out = { requirements: 0, arch: 0, openapi: 0, asyncapi: 0, permissions: 0, capabilities: 0 };
+    for (const svc of perService) {
+        for (const axis of ADOPTION_AXES)
+            if (svc.participates[axis])
+                out[axis] += 1;
+    }
+    return out;
+}
+/**
+ * THE QUALIFICATION RULE — this table IS the rule, and it is mechanical and
+ * fail-closed. A finding is grouped under an axis's "not started" banner iff
+ * (1) its severity is `warn`, (2) its code is listed in this table's row for
+ * the axis, (3) this run's `adoption[axis] === 0`, and (4) the run could
+ * measure that zero at all — a fleet with at least one service and no
+ * `service.unreadable` subject (report.ts enforces this half, beside the
+ * banner it gates: "0 of 0" is no fleet, and an unreadable service's
+ * all-false participation must not manufacture the zero). Anything else —
+ * every error, every warn code not listed here, every warn on an axis with
+ * even one participating service — prints ungrouped, exactly as before. When
+ * in doubt a code stays OUT of the table: the cost of a wrongly-ungrouped
+ * warning is noise, the cost of a wrongly-grouped one is a hidden defect.
+ *
+ * A row lists exactly the warn codes whose SOLE cause is the axis not being
+ * started fleet-wide — codes whose remedy presupposes starting the axis at
+ * all, so with zero participating services the per-target repetition carries
+ * no information the one banner does not:
+ *
+ * - requirements: `service.no-spec` and `spec.no-requirements` fire once per
+ *   service when nobody in the fleet has written a requirement block.
+ * - openapi: `service.no-openapi`'s WARN form (the error form — dangling
+ *   authored links into the absent file — never groups, by condition 1), and
+ *   `spine.op-link-missing`, which never reads the contract (service/spine.ts
+ *   documents exactly that) and so fires per titled Calls-edge even with zero
+ *   contracts fleet-wide.
+ * - permissions: `permissions.unenforced` — one finding whose whole content
+ *   is "the vocabulary exists and nothing cites it yet".
+ * - capabilities: `capability.unrealized` — deliberately one warn PER
+ *   declared capability (core/capabilities/findings.ts), so a freshly landed
+ *   vocabulary warns M times before the first requirement names any of them.
+ * - arch and asyncapi have NO code whose sole cause is fleet-wide absence
+ *   (an absent arch.spec.md is silent; an absent asyncapi.yaml is silent or
+ *   an error when authored links strand on it), so their rows are empty and
+ *   those axes surface only in the scorecard's not-started one-liner.
+ *
+ * Rows are disjoint — a code belongs to exactly one axis — which is what lets
+ * `groupedWarnCodes` invert the table into a Map. Not prose alone:
+ * test/adoption-rollup.test.ts asserts the flattened rows hold no duplicate,
+ * because a code filed under two axes would be grouped under whichever
+ * happens to sit at zero — possibly hiding it behind a fully adopted axis.
+ */
+export const AXIS_GROUPED_WARNS = {
+    requirements: ["service.no-spec", "spec.no-requirements"],
+    arch: [],
+    openapi: ["service.no-openapi", "spine.op-link-missing"],
+    asyncapi: [],
+    permissions: ["permissions.unenforced"],
+    capabilities: ["capability.unrealized"],
+};
+/**
+ * The table inverted for this run: warn code → its axis, for exactly the axes
+ * this run's adoption counts put at zero. Insertion order is ADOPTION_AXES
+ * order then row order, so every walk over the Map renders deterministically.
+ */
+export function groupedWarnCodes(adoption) {
+    const out = new Map();
+    for (const axis of ADOPTION_AXES) {
+        if (adoption[axis] !== 0)
+            continue;
+        for (const code of AXIS_GROUPED_WARNS[axis])
+            out.set(code, axis);
+    }
+    return out;
+}
+//# sourceMappingURL=adoption.js.map

package/dist/commands/validate/fleet/scorecard/adoption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adoption.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/scorecard/adoption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,cAAc;IACd,MAAM;IACN,SAAS;IACT,UAAU;IACV,aAAa;IACb,cAAc;CACN,CAAC;AAaX,0EAA0E;AAC1E,MAAM,UAAU,UAAU,CACxB,UAA6F;IAE7F,MAAM,GAAG,GAAa,EAAE,YAAY,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IAC7G,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,aAAa;YAAE,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA4C;IACzE,YAAY,EAAE,CAAC,iBAAiB,EAAE,sBAAsB,CAAC;IACzD,IAAI,EAAE,EAAE;IACR,OAAO,EAAE,CAAC,oBAAoB,EAAE,uBAAuB,CAAC;IACxD,QAAQ,EAAE,EAAE;IACZ,WAAW,EAAE,CAAC,wBAAwB,CAAC;IACvC,YAAY,EAAE,CAAC,uBAAuB,CAAC;CACxC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAkB;IACjD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,SAAS;QACnC,KAAK,MAAM,IAAI,IAAI,kBAAkB,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["/**\n * The adoption vocabulary of the fleet scorecard: which contract axes a\n * service PARTICIPATES in, summed to the fleet's per-axis participation\n * counts, and the mechanical rule for which warnings the `--all` text report\n * may fold under a per-axis \"not started\" banner.\n *\n * A leaf on purpose: it imports nothing, so `../report.ts` (the text\n * renderer) and `./contracts.js` (which computes the per-service booleans)\n * can both use it without closing a cycle — `adoptionOf` takes the smallest\n * structural parameter it needs instead of the ContractCounts type,\n * core/vocabulary/maturity.ts's EdgeSource precedent for staying a leaf.\n */\n\n/**\n * The six contract axes a service adopts one at a time, in the order every\n * rendering walks them. Participation is a per-service boolean with one\n * mechanical rule per axis, spelled on `Scorecard.adoption` (./scorecard.js)\n * where the payload key freezes them.\n */\nexport const ADOPTION_AXES = [\n  \"requirements\",\n  \"arch\",\n  \"openapi\",\n  \"asyncapi\",\n  \"permissions\",\n  \"capabilities\",\n] as const;\n\nexport type AdoptionAxis = (typeof ADOPTION_AXES)[number];\n\n/**\n * Participating services per axis. Flat counts — the denominator is\n * `Scorecard.services`, carried once so two copies cannot disagree. An axis\n * at 0 reads \"not started\"; 0 < N < M is \"partially adopted\", and the two\n * must never be conflated: a banner that grouped a partially-adopted axis's\n * warnings would hide the exact services the count says are missing.\n */\nexport type Adoption = Record<AdoptionAxis, number>;\n\n/** Sum the per-service participation booleans into the fleet's counts. */\nexport function adoptionOf(\n  perService: ReadonlyArray<{ readonly participates: Readonly<Record<AdoptionAxis, boolean>> }>,\n): Adoption {\n  const out: Adoption = { requirements: 0, arch: 0, openapi: 0, asyncapi: 0, permissions: 0, capabilities: 0 };\n  for (const svc of perService) {\n    for (const axis of ADOPTION_AXES) if (svc.participates[axis]) out[axis] += 1;\n  }\n  return out;\n}\n\n/**\n * THE QUALIFICATION RULE — this table IS the rule, and it is mechanical and\n * fail-closed. A finding is grouped under an axis's \"not started\" banner iff\n * (1) its severity is `warn`, (2) its code is listed in this table's row for\n * the axis, (3) this run's `adoption[axis] === 0`, and (4) the run could\n * measure that zero at all — a fleet with at least one service and no\n * `service.unreadable` subject (report.ts enforces this half, beside the\n * banner it gates: \"0 of 0\" is no fleet, and an unreadable service's\n * all-false participation must not manufacture the zero). Anything else —\n * every error, every warn code not listed here, every warn on an axis with\n * even one participating service — prints ungrouped, exactly as before. When\n * in doubt a code stays OUT of the table: the cost of a wrongly-ungrouped\n * warning is noise, the cost of a wrongly-grouped one is a hidden defect.\n *\n * A row lists exactly the warn codes whose SOLE cause is the axis not being\n * started fleet-wide — codes whose remedy presupposes starting the axis at\n * all, so with zero participating services the per-target repetition carries\n * no information the one banner does not:\n *\n * - requirements: `service.no-spec` and `spec.no-requirements` fire once per\n *   service when nobody in the fleet has written a requirement block.\n * - openapi: `service.no-openapi`'s WARN form (the error form — dangling\n *   authored links into the absent file — never groups, by condition 1), and\n *   `spine.op-link-missing`, which never reads the contract (service/spine.ts\n *   documents exactly that) and so fires per titled Calls-edge even with zero\n *   contracts fleet-wide.\n * - permissions: `permissions.unenforced` — one finding whose whole content\n *   is \"the vocabulary exists and nothing cites it yet\".\n * - capabilities: `capability.unrealized` — deliberately one warn PER\n *   declared capability (core/capabilities/findings.ts), so a freshly landed\n *   vocabulary warns M times before the first requirement names any of them.\n * - arch and asyncapi have NO code whose sole cause is fleet-wide absence\n *   (an absent arch.spec.md is silent; an absent asyncapi.yaml is silent or\n *   an error when authored links strand on it), so their rows are empty and\n *   those axes surface only in the scorecard's not-started one-liner.\n *\n * Rows are disjoint — a code belongs to exactly one axis — which is what lets\n * `groupedWarnCodes` invert the table into a Map. Not prose alone:\n * test/adoption-rollup.test.ts asserts the flattened rows hold no duplicate,\n * because a code filed under two axes would be grouped under whichever\n * happens to sit at zero — possibly hiding it behind a fully adopted axis.\n */\nexport const AXIS_GROUPED_WARNS: Record<AdoptionAxis, readonly string[]> = {\n  requirements: [\"service.no-spec\", \"spec.no-requirements\"],\n  arch: [],\n  openapi: [\"service.no-openapi\", \"spine.op-link-missing\"],\n  asyncapi: [],\n  permissions: [\"permissions.unenforced\"],\n  capabilities: [\"capability.unrealized\"],\n};\n\n/**\n * The table inverted for this run: warn code → its axis, for exactly the axes\n * this run's adoption counts put at zero. Insertion order is ADOPTION_AXES\n * order then row order, so every walk over the Map renders deterministically.\n */\nexport function groupedWarnCodes(adoption: Adoption): Map<string, AdoptionAxis> {\n  const out = new Map<string, AdoptionAxis>();\n  for (const axis of ADOPTION_AXES) {\n    if (adoption[axis] !== 0) continue;\n    for (const code of AXIS_GROUPED_WARNS[axis]) out.set(code, axis);\n  }\n  return out;\n}\n"]}

package/dist/commands/validate/fleet/scorecard/contracts.js

@@ -0,0 +1,98 @@
+/**
+ * One service's contract-axis contributions to the fleet scorecard: the HTTP
+ * and event counts off its living documents, its arch `Covers:` entries for
+ * the C4 census, and the per-axis adoption booleans (`participates`).
+ * `./scorecard.js` sums these across the fleet; this module owns the
+ * per-service reads and their containment, and never prints.
+ */
+import { existsSync } from "node:fs";
+import { readAsyncapi } from "../../../../core/asyncapi/read.js";
+import {} from "../../../../core/c4/arch.js";
+import {} from "../../../../core/fleet-context.js";
+import { readOpenapi } from "../../../../core/openapi/doc.js";
+import {} from "../../../../core/repo/entries.js";
+import { servicePathsAt } from "../../../../core/repo/paths.js";
+import { coversEntries } from "../../checks/requirements.js";
+import {} from "./adoption.js";
+export async function contractCounts(svc, fleet, inbound) {
+    try {
+        return await readContracts(svc, fleet, inbound);
+    }
+    catch {
+        // `guarded`'s doctrine, one rollup down: these are the same memoized reads
+        // this service's own target already failed on, and a memoized REJECTION
+        // rejects again on every await — so a spec.md that is not UTF-8, or an
+        // openapi.yaml that is a directory, deleted the whole fleet's card from
+        // inside Promise.all. The service's `service.unreadable` finding names the
+        // cause; here the one unreadable service contributes zeros and the
+        // fleet's rollup survives. Participation is all-false the way the counts
+        // are zero — NOT because the service started nothing (an unreadable
+        // service proves nothing, least of all that), but because no claim can be
+        // made; the text renderer therefore refuses to group warnings on any run
+        // with an unreadable service (report.ts), since a false `false` here
+        // could manufacture the fleet-wide N=0 that licenses suppression.
+        return {
+            operations: { defined: 0, governed: 0, deprecated: 0, deprecatedStillConsumed: 0 },
+            messages: { defined: 0, linked: 0 },
+            covers: [],
+            participates: { requirements: false, arch: false, openapi: false, asyncapi: false, permissions: false, capabilities: false },
+        };
+    }
+}
+async function readContracts(svc, fleet, inbound) {
+    const paths = servicePathsAt(svc.dir);
+    const reqs = existsSync(paths.spec) ? await fleet.readRequirements(paths.spec) : [];
+    const archReqs = existsSync(paths.archSpec) ? await fleet.readRequirements(paths.archSpec) : [];
+    // The living rule the service target applies (service/specs.ts): a REMOVED
+    // requirement is on its way out and governs nothing. Hoisted for BOTH
+    // documents because the `linked` join and the participation booleans below
+    // read the same non-REMOVED sets.
+    const living = reqs.filter((r) => r.kind !== "REMOVED");
+    const archLiving = archReqs.filter((r) => r.kind !== "REMOVED");
+    const api = await readOpenapi(paths.openapi, fleet);
+    // Removal markers are never callable operations (service/api.ts's liveOps
+    // rule), and an unreadable contract defines nothing this census may count —
+    // swallowing it into its parsed subset would grade a broken file as a thin one.
+    const ops = api.unreadable ? [] : api.ops.filter((o) => !o.remove);
+    const governed = new Set(living.flatMap((r) => r.operations));
+    const deprecated = new Set(ops.filter((o) => o.deprecated).map((o) => o.id));
+    const events = await readAsyncapi(paths.asyncapi, fleet);
+    // Distinct names — every join on the event spine is by NAME, so a duplicate
+    // slot is one message — and the governance join is requirement lines from
+    // BOTH documents, never landscape edges: an edge is a claim about traffic,
+    // a requirement is governance (service/events/events.ts).
+    const declared = events.unreadable
+        ? []
+        : [...new Set(events.messages.filter((m) => m.remove !== true).map((m) => m.name))];
+    const linked = new Set([...living, ...archLiving].flatMap((r) => [...r.publishes, ...r.consumes]));
+    // The per-axis participation booleans, each the one-line rule the Scorecard
+    // doc comment pins. Requirements/arch count ANY parsed block (REMOVED
+    // included — a spec retiring its last requirement still started the axis),
+    // while permissions/capabilities apply the non-REMOVED rule their fleet
+    // checks apply (fleet-shape.ts's used sets), so "participates" and "cites"
+    // cannot disagree about the same line.
+    const participates = {
+        requirements: reqs.length > 0,
+        arch: archReqs.length > 0,
+        openapi: existsSync(paths.openapi),
+        asyncapi: existsSync(paths.asyncapi),
+        permissions: [...living, ...archLiving].some((r) => r.requires.length > 0),
+        capabilities: [...living, ...archLiving].some((r) => r.capabilities.length > 0),
+    };
+    return {
+        operations: {
+            defined: ops.length,
+            governed: ops.filter((o) => governed.has(o.id)).length,
+            deprecated: deprecated.size,
+            deprecatedStillConsumed: [...deprecated].filter((id) => governed.has(id) || inbound.has(id)).length,
+        },
+        messages: {
+            defined: declared.length,
+            linked: declared.filter((name) => linked.has(name)).length,
+        },
+        // coversEntries already drops REMOVED requirements.
+        covers: coversEntries(archReqs),
+        participates,
+    };
+}
+//# sourceMappingURL=contracts.js.map

package/dist/commands/validate/fleet/scorecard/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/scorecard/contracts.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One service's contract-axis contributions to the fleet scorecard: the HTTP\n * and event counts off its living documents, its arch `Covers:` entries for\n * the C4 census, and the per-axis adoption booleans (`participates`).\n * `./scorecard.js` sums these across the fleet; this module owns the\n * per-service reads and their containment, and never prints.\n */\nimport { existsSync } from \"node:fs\";\nimport { readAsyncapi } from \"../../../../core/asyncapi/read.js\";\nimport { type CoversEntry } from \"../../../../core/c4/arch.js\";\nimport { type FleetContext } from \"../../../../core/fleet-context.js\";\nimport { readOpenapi } from \"../../../../core/openapi/doc.js\";\nimport { type ServiceEntry } from \"../../../../core/repo/entries.js\";\nimport { servicePathsAt } from \"../../../../core/repo/paths.js\";\nimport { coversEntries } from \"../../checks/requirements.js\";\nimport { type AdoptionAxis } from \"./adoption.js\";\n\n/**\n * One service's contributions. Structurally identical to the `operations` and\n * `messages` sections of the Scorecard payload — spelled here rather than\n * imported from `./scorecard.js`, because that import would close a file\n * cycle with the module that sums these.\n */\nexport interface ContractCounts {\n  operations: { defined: number; governed: number; deprecated: number; deprecatedStillConsumed: number };\n  messages: { defined: number; linked: number };\n  covers: CoversEntry[];\n  /**\n   * Whether THIS service has started each adoption axis — the per-service\n   * booleans `adoptionOf` (./adoption.js) sums into the fleet's participation\n   * counts. The six rules are spelled on `Scorecard.adoption` (./scorecard.js),\n   * where the payload key freezes them; every input is a read this function\n   * already pays for.\n   */\n  participates: Record<AdoptionAxis, boolean>;\n}\n\nexport async function contractCounts(\n  svc: ServiceEntry,\n  fleet: FleetContext,\n  inbound: ReadonlySet<string>,\n): Promise<ContractCounts> {\n  try {\n    return await readContracts(svc, fleet, inbound);\n  } catch {\n    // `guarded`'s doctrine, one rollup down: these are the same memoized reads\n    // this service's own target already failed on, and a memoized REJECTION\n    // rejects again on every await — so a spec.md that is not UTF-8, or an\n    // openapi.yaml that is a directory, deleted the whole fleet's card from\n    // inside Promise.all. The service's `service.unreadable` finding names the\n    // cause; here the one unreadable service contributes zeros and the\n    // fleet's rollup survives. Participation is all-false the way the counts\n    // are zero — NOT because the service started nothing (an unreadable\n    // service proves nothing, least of all that), but because no claim can be\n    // made; the text renderer therefore refuses to group warnings on any run\n    // with an unreadable service (report.ts), since a false `false` here\n    // could manufacture the fleet-wide N=0 that licenses suppression.\n    return {\n      operations: { defined: 0, governed: 0, deprecated: 0, deprecatedStillConsumed: 0 },\n      messages: { defined: 0, linked: 0 },\n      covers: [],\n      participates: { requirements: false, arch: false, openapi: false, asyncapi: false, permissions: false, capabilities: false },\n    };\n  }\n}\n\nasync function readContracts(\n  svc: ServiceEntry,\n  fleet: FleetContext,\n  inbound: ReadonlySet<string>,\n): Promise<ContractCounts> {\n  const paths = servicePathsAt(svc.dir);\n  const reqs = existsSync(paths.spec) ? await fleet.readRequirements(paths.spec) : [];\n  const archReqs = existsSync(paths.archSpec) ? await fleet.readRequirements(paths.archSpec) : [];\n  // The living rule the service target applies (service/specs.ts): a REMOVED\n  // requirement is on its way out and governs nothing. Hoisted for BOTH\n  // documents because the `linked` join and the participation booleans below\n  // read the same non-REMOVED sets.\n  const living = reqs.filter((r) => r.kind !== \"REMOVED\");\n  const archLiving = archReqs.filter((r) => r.kind !== \"REMOVED\");\n\n  const api = await readOpenapi(paths.openapi, fleet);\n  // Removal markers are never callable operations (service/api.ts's liveOps\n  // rule), and an unreadable contract defines nothing this census may count —\n  // swallowing it into its parsed subset would grade a broken file as a thin one.\n  const ops = api.unreadable ? [] : api.ops.filter((o) => !o.remove);\n  const governed = new Set(living.flatMap((r) => r.operations));\n  const deprecated = new Set(ops.filter((o) => o.deprecated).map((o) => o.id));\n\n  const events = await readAsyncapi(paths.asyncapi, fleet);\n  // Distinct names — every join on the event spine is by NAME, so a duplicate\n  // slot is one message — and the governance join is requirement lines from\n  // BOTH documents, never landscape edges: an edge is a claim about traffic,\n  // a requirement is governance (service/events/events.ts).\n  const declared = events.unreadable\n    ? []\n    : [...new Set(events.messages.filter((m) => m.remove !== true).map((m) => m.name))];\n  const linked = new Set(\n    [...living, ...archLiving].flatMap((r) => [...r.publishes, ...r.consumes]),\n  );\n\n  // The per-axis participation booleans, each the one-line rule the Scorecard\n  // doc comment pins. Requirements/arch count ANY parsed block (REMOVED\n  // included — a spec retiring its last requirement still started the axis),\n  // while permissions/capabilities apply the non-REMOVED rule their fleet\n  // checks apply (fleet-shape.ts's used sets), so \"participates\" and \"cites\"\n  // cannot disagree about the same line.\n  const participates: Record<AdoptionAxis, boolean> = {\n    requirements: reqs.length > 0,\n    arch: archReqs.length > 0,\n    openapi: existsSync(paths.openapi),\n    asyncapi: existsSync(paths.asyncapi),\n    permissions: [...living, ...archLiving].some((r) => r.requires.length > 0),\n    capabilities: [...living, ...archLiving].some((r) => r.capabilities.length > 0),\n  };\n\n  return {\n    operations: {\n      defined: ops.length,\n      governed: ops.filter((o) => governed.has(o.id)).length,\n      deprecated: deprecated.size,\n      deprecatedStillConsumed: [...deprecated].filter((id) => governed.has(id) || inbound.has(id)).length,\n    },\n    messages: {\n      defined: declared.length,\n      linked: declared.filter((name) => linked.has(name)).length,\n    },\n    // coversEntries already drops REMOVED requirements.\n    covers: coversEntries(archReqs),\n    participates,\n  };\n}\n"]}

package/dist/commands/validate/fleet/scorecard/print.js

@@ -0,0 +1,63 @@
+/**
+ * The fleet scorecard's one table — how the `--all` text report renders what
+ * `./scorecard.js` derived. A module of its own for validate's own discipline
+ * (validate.ts's header: the checks produce findings and none of them print;
+ * printing happens after the last target is graded), and so the derivation
+ * and the formatting do not share a file whose one seam is exactly that.
+ *
+ * One line per axis, ceiling before actual, read left to right the way the
+ * numbers are read in a CI log — except the adoption row, which states
+ * participation over the denominator (`requirements 3/40`): adoption is an
+ * N-of-M spread, not a ceiling chased by an actual, and forcing it into the
+ * arrow idiom would read as one. It prints under `--errors-only` too, on
+ * purpose: like the summary footer it is a rollup, not a finding, and
+ * `--errors-only` is a findings-rendering lever (report.ts).
+ */
+import { ARTIFACT_STATUSES } from "../../../../core/status/report.js";
+import { ANSWERED_BY } from "../../../../core/verify/answers.js";
+import { VERIFICATION_VERDICTS } from "../../../../core/verify/record.js";
+import { MATURITY_LADDER } from "../../../../core/vocabulary/maturity.js";
+import { ADOPTION_AXES } from "./adoption.js";
+import {} from "./scorecard.js";
+export function printScorecard(card) {
+    const { maturity, provenance: p, verification: v, operations: o, messages: m, c4, features: f } = card;
+    console.log("\nfleet scorecard (ceiling → actual)");
+    console.log(`  services      ${card.services} — ` +
+        MATURITY_LADDER.map((rung) => `${maturity[rung]} ${rung}`).join(" · "));
+    console.log(
+    // The sampled count rides INSIDE the vouched number rather than after it,
+    // because that is where it changes the reading: "120 vouched" and "120
+    // vouched (100 sampled)" are different fleets, and a reader who stops at
+    // the first number must not have been told the stronger of the two.
+    `  provenance    ${p.vouched} vouched${p.sampledVouched > 0 ? ` (${p.sampledVouched} sampled)` : ""} — ` +
+        `${p.staleDigests} stale digest(s) · ${p.unverifiableFromHere} unverifiable from here`);
+    // The ceiling is the features axis's `active` — the payload deliberately
+    // carries that denominator once, so this line reads it from there.
+    console.log(`  verification  ${f.active} feature(s) → ${v.recorded} recorded — ` +
+        VERIFICATION_VERDICTS.map((verdict) => `${v.verdicts[verdict]} ${verdict}`).join(" · ") +
+        ` — claims ${v.claims.confirmed}/${v.claims.total} confirmed ` +
+        // Every provenance, under its own `answered_by` spelling and always all
+        // three — the same stable-shape rendering as the verdicts before it. Two
+        // buckets could not name what they held: the line said "runner" over
+        // claims no runner answered, and no label short of the real one fixes
+        // that, because `external-runner` is neither of the other two.
+        `(${ANSWERED_BY.map((who) => `${v.claims.answered[who]} ${who}`).join(" · ")})`);
+    console.log(`  operations    ${o.defined} defined → ${o.governed} governed · ` +
+        `${o.deprecated} deprecated (${o.deprecatedStillConsumed} still consumed)`);
+    console.log(`  messages      ${m.defined} defined → ${m.linked} linked`);
+    console.log(`  c4            ${c4.elements} elements → ${c4.covered} covered`);
+    // Participation per axis over the one denominator, then the same facts as
+    // the sentence a standup reads out: which axes the fleet has started at
+    // all. "adopted" here means at least one participating service — the
+    // per-axis counts on the line above say how many.
+    const a = card.adoption;
+    console.log(`  adoption      ` +
+        ADOPTION_AXES.map((axis) => `${axis} ${a[axis]}/${card.services}`).join(" · "));
+    const adopted = ADOPTION_AXES.filter((axis) => a[axis] > 0);
+    const notStarted = ADOPTION_AXES.filter((axis) => a[axis] === 0);
+    console.log(`  axes          adopted: ${adopted.length === 0 ? "none" : adopted.join(", ")}` +
+        (notStarted.length === 0 ? "" : ` · not started: ${notStarted.join(", ")}`));
+    console.log(`  features      ${f.active} active — ` +
+        ARTIFACT_STATUSES.map((stage) => `${f.stages[stage]} ${stage}`).join(" · "));
+}
+//# sourceMappingURL=print.js.map