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

package/dist/commands/validate/service/specs.js

@@ -0,0 +1,251 @@
+/**
+ * This service's requirement documents: spec.md, arch.spec.md, and the
+ * obligations the second of them carries that the first never does.
+ *
+ * Two entry points because the two happen at different moments in a service's
+ * grading and the order of findings is part of the report. `readServiceSpecs`
+ * runs first — everything downstream joins through the requirements it parses —
+ * while `archAxisFindings` runs last, after both spines, because `covers.unknown`
+ * resolves against the C4 model and the landscape and cannot be answered until
+ * those are in hand.
+ *
+ * The arch axis is advisory in what it ASKS for (covers.unknown,
+ * health.uncovered are warnings; arch.spec.md's absence is not a finding at all,
+ * because partial adoption is supported) but not in whether the file is
+ * readable: a conflict marker or a stepless scenario is graded exactly as it is
+ * on the business axis. One file, one rule.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import {} from "../../../core/c4/likec4.js";
+import {} from "../../../core/kernel/ids/service.js";
+import {} from "../../../core/repo/paths.js";
+import {} from "../../../core/vocabulary/report.js";
+import { parseRequirements } from "../../../core/document/parse.js";
+import { assertionlessFindings, examplesFindings, steplessFindings, } from "../../../core/document/scenarios.js";
+import {} from "../../../core/document/spec.js";
+import {} from "../../../core/c4/arch.js";
+import { hasDeployment } from "../../../core/c4/parsed/deployment.js";
+import { loadArchitecture } from "../../../core/c4/project/architecture.js";
+import {} from "../../../core/kernel/ids/dirs.js";
+import { readHealth } from "../../../core/vocabulary/health.js";
+import { documentConflictFinding } from "../../../core/conflict-markers.js";
+import { FleetContext } from "../../../core/fleet-context.js";
+import { healthDependencyFindings } from "../checks/health-deps.js";
+import { coverageFinding, coversEntries, coversUnknownFindings, duplicateRequirementFindings, repeatedListLineFindings, requirementIdFindings, } from "../checks/requirements.js";
+export async function readServiceSpecs(input) {
+    const { service, paths, fleet } = input;
+    const findings = [];
+    // Requirement coverage.
+    let reqs = [];
+    if (existsSync(paths.spec)) {
+        const specText = fleet === undefined ? await readFile(paths.spec, "utf8") : await fleet.readText(paths.spec);
+        reqs = fleet === undefined ? parseRequirements(specText) : await fleet.readRequirements(paths.spec);
+        // Conflict markers first, because they say that nothing below this line is
+        // anyone's text. An error, gating by the default rule and deliberately
+        // without `gates`: that field is coherence's (issue.ts) and archive does
+        // not read validate's findings, so claiming it here would be a promise
+        // about a gate that is not wired. What makes it an error rather than a
+        // warning is what the next merge does — `loam archive` rewrites the
+        // requirements section of this very file and takes whichever marker lines
+        // fall inside it, turning a conflict anyone can see into a document nobody
+        // can tell is wrong.
+        const conflict = documentConflictFinding(`${service}: spec.md`, service, specText);
+        if (conflict !== null)
+            findings.push(conflict);
+        // A living spec with no `### Requirement:` block at all is the baseline
+        // `loam adopt` scaffolds and nobody ever filled in. "requirements covered
+        // (0 requirements, all with scenarios)" is true of it and says the opposite
+        // of what a reader needs: every cross-axis check downstream — API
+        // governance, the Operations: spine, gherkin generation — is vacuous here,
+        // and the green tick is what let a whole fleet score `sourced` over empty
+        // files.
+        if (reqs.length === 0) {
+            findings.push({
+                severity: "warn",
+                code: "spec.no-requirements",
+                subject: service,
+                message: `${service}: spec.md holds no '### Requirement:' blocks — every requirement-driven check below is vacuous, and nothing here can go out of date because nothing is written down`,
+            });
+        }
+        else {
+            findings.push(coverageFinding(`${service}: requirements`, reqs));
+        }
+        // The other half of the coverage question, and an error for the same
+        // reason the first half is: the whole claim of coverage is that a
+        // requirement has a scenario something can RUN. A heading with no steps
+        // satisfies the count and tests nothing — cucumber runs it vacuously green
+        // and `loam verify --results` can never confirm it — so a fleet gate that
+        // called it covered was certifying the absence of a test.
+        findings.push(...steplessFindings(`${service}: requirements`, service, reqs));
+        findings.push(...assertionlessFindings(`${service}: requirements`, service, reqs));
+        findings.push(...examplesFindings(`${service}: requirements`, service, reqs));
+        findings.push(...duplicateRequirementFindings(reqs, `${service}: spec.md`, service));
+        findings.push(...requirementIdFindings(reqs, `${service}: spec.md`, service));
+        findings.push(...repeatedListLineFindings(reqs, `${service}: spec.md`, service));
+    }
+    else {
+        findings.push({
+            severity: "warn",
+            code: "service.no-spec",
+            message: `No living spec at ${paths.spec} — requirement coverage and API governance are unchecked`,
+        });
+    }
+    // The requirements that still govern anything. A REMOVED requirement is on
+    // its way out together with the operations it names: it makes no claim on the
+    // contract and governs nothing once the retiring feature archives — the same
+    // position coherence/coherence.ts takes on the delta side.
+    //
+    // Spelled once because it was spelled three times and dropped on the fourth:
+    // `governedOps` filtered, `spec-api.op-undefined` filtered, and the
+    // `api.covered` join did not — so an operation whose only requirement was
+    // REMOVED counted as governed, and the one operation about to be left without
+    // a requirement was the one the report called covered.
+    const livingReqs = reqs.filter((r) => r.kind !== "REMOVED");
+    // The architecture spec, read HERE with spec.md rather than with the rest of
+    // its own axis below, because the event links are a requirement-level join and
+    // BOTH requirement files carry them. Events are architecture as often as they
+    // are business — the outbox requirement in a service's arch.spec.md is the
+    // canonical place a `Publishes:` line belongs — so handing the event axis only
+    // spec.md would silently ignore the lines most authors write.
+    const archText = existsSync(paths.archSpec)
+        ? fleet === undefined
+            ? await readFile(paths.archSpec, "utf8")
+            : await fleet.readText(paths.archSpec)
+        : null;
+    const archReqs = archText === null
+        ? []
+        : fleet === undefined
+            ? parseRequirements(archText)
+            : await fleet.readRequirements(paths.archSpec);
+    return { findings, reqs, livingReqs, archText, archReqs };
+}
+/**
+ * The topology a `node:` Covers entry resolves against, loaded at most once and
+ * only when something asks for it.
+ *
+ * Under `--all` the caller hands in the doc it already loaded — the whole
+ * `architecture/` project — so the deployment model is already here and this
+ * returns it. A SINGLE-service run loads only `landscape.likec4`, and a fleet
+ * that keeps its `deployment { }` block in a file beside it, which is the
+ * ordinary layout once one landscape file is the fleet's convention, would then
+ * resolve one `Covers:` line two different ways depending on which command
+ * asked. `loam status`'s two forms had exactly that disagreement and it was a
+ * defect both times; this is the same class, prevented rather than found.
+ *
+ * The cost is paid only by a service whose `arch.spec.md` actually writes a
+ * `node:` entry. A fleet with no topology at all pays one project load per such
+ * service — a state in which the entry is a typo anyway, and one load is what
+ * buys it a message that names the real ids.
+ */
+async function topology(land, archReqs, docsDir) {
+    if (land?.deployment !== undefined && hasDeployment(land.deployment))
+        return land.deployment;
+    const wanted = coversEntries(archReqs).some((e) => e.form === "node" || e.form === "node-edge");
+    if (!wanted)
+        return undefined;
+    const project = await loadArchitecture(docsDir);
+    return project.errors.length === 0 ? project.deployment : undefined;
+}
+export async function archAxisFindings(axis) {
+    const { service, paths, archText, archReqs, elements, relationships, land, known, docsDir } = axis;
+    const findings = [];
+    // The architecture spec axis — the obligations a business spec never carries
+    // (the transactional outbox, retries, metrics, alerts). arch.spec.md is
+    // optional and its ABSENCE is not a finding (partial adoption is supported);
+    // what exists must hold together: every requirement needs a scenario, every
+    // `Covers:` entry must resolve (covers.unknown), and every alert/SLI that
+    // health.yaml declares wants a covering requirement (health.uncovered) — the
+    // moment health.yaml stops being inert. Warnings, never gates: `--strict` is
+    // the CI escalation.
+    const health = await readHealth(paths.health);
+    // A model that reaches nothing is almost never true — but only when
+    // something else attests it should reach. A deliberately shallow synthetic
+    // fixture can hold elements without relationships beside sources that name
+    // dependencies, yet `0 errors, 0 warnings` would still read as done.
+    // Evidence-gated on purpose: a bare root-plus-one-container baseline stays
+    // silent (nothing PROVES it thin — the standard mid-adoption shape), the
+    // warn needs either a second nested element with no edge joining anything,
+    // or dependencies declared in this service's own health.yaml. The health
+    // half goes quiet when the file is unreadable — no claims on bad data.
+    const nested = elements.filter((e) => e.id.includes(".")).length;
+    const deps = health.unreadable ? [] : health.dependencies;
+    if (elements.length > 0 && relationships.length === 0 && (nested > 1 || deps.length > 0)) {
+        const evidence = [
+            ...(nested > 1 ? [`${nested} nested elements with no edge joining them`] : []),
+            ...(deps.length > 0
+                ? [`health.yaml declares ${deps.length} dependenc${deps.length === 1 ? "y" : "ies"} (${deps.join(", ")})`]
+                : []),
+        ].join(", and ");
+        findings.push({
+            severity: "warn",
+            code: "c4.no-relationships",
+            subject: service,
+            message: `${service}: model.likec4 declares ${elements.length} element(s) and 0 relationships, yet ${evidence} — ` +
+                `a model that reaches nothing is almost never true; draw the edges the service actually has ` +
+                `(what its containers call, what reads and writes its stores, what it depends on at runtime)`,
+        });
+    }
+    if (archText !== null) {
+        // The arch axis is advisory in what it ASKS for (covers.unknown,
+        // health.uncovered are warnings) but not in whether the file is readable:
+        // both breaches below are about the document itself, and they are graded
+        // exactly as they are on the business axis — one file, one rule.
+        const conflict = documentConflictFinding(`${service}: arch.spec.md`, service, archText);
+        if (conflict !== null)
+            findings.push(conflict);
+        findings.push(coverageFinding(`${service}: arch requirements`, archReqs));
+        findings.push(...steplessFindings(`${service}: arch requirements`, service, archReqs));
+        findings.push(...assertionlessFindings(`${service}: arch requirements`, service, archReqs));
+        findings.push(...examplesFindings(`${service}: arch requirements`, service, archReqs));
+        findings.push(...duplicateRequirementFindings(archReqs, `${service}: arch.spec.md`, service));
+        findings.push(...requirementIdFindings(archReqs, `${service}: arch.spec.md`, service));
+        findings.push(...repeatedListLineFindings(archReqs, `${service}: arch.spec.md`, service));
+    }
+    // A health.yaml that exists but does not read is reported once, and the
+    // checks that read it go quiet BOTH ways: its ids are unknown, so no
+    // health.uncovered obligation exists (the empty id set below is already
+    // silent), and no `Covers: alert:/sli:` entry may be graded a typo against
+    // ids nobody could read (coversUnknownFindings mutes on the flag). A warn,
+    // not an error: the axis it feeds is advisory end to end.
+    if (health.unreadable) {
+        findings.push({
+            severity: "warn",
+            code: "health.invalid",
+            subject: service,
+            message: `${service}: health.yaml does not parse — alert/SLI ids are unreadable, so Covers: alert:/sli: entries and health coverage are unchecked`,
+            ...(health.error === undefined ? {} : { details: [health.error] }),
+        });
+    }
+    const landParses = land !== null && land.errors.length === 0 ? land : null;
+    const deployment = await topology(landParses, archReqs, docsDir);
+    const scope = {
+        elements: [...elements, ...(landParses?.elements ?? [])],
+        relationships: [...relationships, ...(landParses?.relationships ?? [])],
+        ...(deployment === undefined ? {} : { deployment }),
+        health: health.ids,
+        known,
+    };
+    findings.push(...coversUnknownFindings(archReqs, { where: `${service}: arch.spec.md`, subject: service }, scope, health.unreadable));
+    const activeCovers = coversEntries(archReqs);
+    for (const { form, ids } of [
+        { form: "alert", ids: health.ids.alerts },
+        { form: "sli", ids: health.ids.slis },
+    ]) {
+        for (const id of ids) {
+            if (activeCovers.some((e) => e.form === form && e.id === id))
+                continue;
+            findings.push({
+                severity: "warn",
+                code: "health.uncovered",
+                subject: service,
+                message: `${service}: health.yaml declares ${form === "alert" ? "alert" : "SLI"} '${id}' but no arch.spec.md requirement covers it — write one with 'Covers: ${form}:${id}', or the signal ships with nothing testing it`,
+            });
+        }
+    }
+    // The other direction health.yaml is read in: its dependencies must be the
+    // model's dependencies. `deps` is already muted on an unreadable file above.
+    findings.push(...healthDependencyFindings({ service, dependencies: deps, elements, modelPath: paths.model }));
+    return findings;
+}
+//# sourceMappingURL=specs.js.map

package/dist/commands/validate/service/specs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs.js","sourceRoot":"","sources":["../../../../src/commands/validate/service/specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAuC,MAAM,4BAA4B,CAAC;AACjF,OAAO,EAAwB,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EAAqB,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAgB,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAoB,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAsB,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAwB,MAAM,uCAAuC,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAC5E,OAAO,EAAgB,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EACL,eAAe,EACf,aAAa,EACb,qBAAqB,EACrB,4BAA4B,EAC5B,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAenC,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAItC;IACC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IACxC,MAAM,QAAQ,GAAc,EAAE,CAAC;IAE/B,wBAAwB;IACxB,IAAI,IAAI,GAAkB,EAAE,CAAC;IAC7B,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,MAAM,QAAQ,GACZ,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9F,IAAI,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpG,2EAA2E;QAC3E,uEAAuE;QACvE,yEAAyE;QACzE,uEAAuE;QACvE,uEAAuE;QACvE,oEAAoE;QACpE,0EAA0E;QAC1E,2EAA2E;QAC3E,qBAAqB;QACrB,MAAM,QAAQ,GAAG,uBAAuB,CAAC,GAAG,OAAO,WAAW,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QACnF,IAAI,QAAQ,KAAK,IAAI;YAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/C,wEAAwE;QACxE,0EAA0E;QAC1E,4EAA4E;QAC5E,kEAAkE;QAClE,2EAA2E;QAC3E,0EAA0E;QAC1E,SAAS;QACT,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,QAAQ,CAAC,IAAI,CAAC;gBACZ,QAAQ,EAAE,MAAM;gBAChB,IAAI,EAAE,sBAAsB;gBAC5B,OAAO,EAAE,OAAO;gBAChB,OAAO,EAAE,GAAG,OAAO,qKAAqK;aACzL,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,OAAO,gBAAgB,EAAE,IAAI,CAAC,CAAC,CAAC;QACnE,CAAC;QACD,qEAAqE;QACrE,kEAAkE;QAClE,wEAAwE;QACxE,2EAA2E;QAC3E,0EAA0E;QAC1E,0DAA0D;QAC1D,QAAQ,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,GAAG,OAAO,gBAAgB,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAC9E,QAAQ,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,GAAG,OAAO,gBAAgB,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QACnF,QAAQ,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,GAAG,OAAO,gBAAgB,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAC9E,QAAQ,CAAC,IAAI,CAAC,GAAG,4BAA4B,CAAC,IAAI,EAAE,GAAG,OAAO,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;QACrF,QAAQ,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,IAAI,EAAE,GAAG,OAAO,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;QAC9E,QAAQ,CAAC,IAAI,CAAC,GAAG,wBAAwB,CAAC,IAAI,EAAE,GAAG,OAAO,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;IACnF,CAAC;SAAM,CAAC;QACN,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,qBAAqB,KAAK,CAAC,IAAI,0DAA0D;SACnG,CAAC,CAAC;IACL,CAAC;IAED,2EAA2E;IAC3E,8EAA8E;IAC9E,6EAA6E;IAC7E,2DAA2D;IAC3D,EAAE;IACF,6EAA6E;IAC7E,oEAAoE;IACpE,0EAA0E;IAC1E,8EAA8E;IAC9E,uDAAuD;IACvD,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAE5D,6EAA6E;IAC7E,+EAA+E;IAC/E,8EAA8E;IAC9E,2EAA2E;IAC3E,+EAA+E;IAC/E,8DAA8D;IAC9D,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC;QACzC,CAAC,CAAC,KAAK,KAAK,SAAS;YACnB,CAAC,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC;YACxC,CAAC,CAAC,MAAM,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC;QACxC,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,QAAQ,GACZ,QAAQ,KAAK,IAAI;QACf,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,KAAK,KAAK,SAAS;YACnB,CAAC,CAAC,iBAAiB,CAAC,QAAQ,CAAC;YAC7B,CAAC,CAAC,MAAM,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAErD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAC5D,CAAC;AAwBD;;;;;;;;;;;;;;;;;GAiBG;AACH,KAAK,UAAU,QAAQ,CACrB,IAAsB,EACtB,QAAuB,EACvB,OAAgB;IAEhB,IAAI,IAAI,EAAE,UAAU,KAAK,SAAS,IAAI,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC,UAAU,CAAC;IAC7F,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;IAChG,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAChD,OAAO,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;AACtE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAc;IACnD,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACnG,MAAM,QAAQ,GAAc,EAAE,CAAC;IAE/B,6EAA6E;IAC7E,wEAAwE;IACxE,6EAA6E;IAC7E,4EAA4E;IAC5E,0EAA0E;IAC1E,6EAA6E;IAC7E,6EAA6E;IAC7E,qBAAqB;IACrB,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAE9C,oEAAoE;IACpE,2EAA2E;IAC3E,2EAA2E;IAC3E,qEAAqE;IACrE,2EAA2E;IAC3E,yEAAyE;IACzE,2EAA2E;IAC3E,yEAAyE;IACzE,uEAAuE;IACvE,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;IACjE,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;IAC1D,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QACzF,MAAM,QAAQ,GAAG;YACf,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,4CAA4C,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9E,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;gBACjB,CAAC,CAAC,CAAC,wBAAwB,IAAI,CAAC,MAAM,aAAa,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;gBAC1G,CAAC,CAAC,EAAE,CAAC;SACR,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACjB,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,OAAO;YAChB,OAAO,EACL,GAAG,OAAO,2BAA2B,QAAQ,CAAC,MAAM,wCAAwC,QAAQ,KAAK;gBACzG,6FAA6F;gBAC7F,6FAA6F;SAChG,CAAC,CAAC;IACL,CAAC;IAED,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,iEAAiE;QACjE,0EAA0E;QAC1E,yEAAyE;QACzE,iEAAiE;QACjE,MAAM,QAAQ,GAAG,uBAAuB,CAAC,GAAG,OAAO,gBAAgB,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QACxF,IAAI,QAAQ,KAAK,IAAI;YAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/C,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,OAAO,qBAAqB,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC1E,QAAQ,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,GAAG,OAAO,qBAAqB,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;QACvF,QAAQ,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,GAAG,OAAO,qBAAqB,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC5F,QAAQ,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,GAAG,OAAO,qBAAqB,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;QACvF,QAAQ,CAAC,IAAI,CAAC,GAAG,4BAA4B,CAAC,QAAQ,EAAE,GAAG,OAAO,gBAAgB,EAAE,OAAO,CAAC,CAAC,CAAC;QAC9F,QAAQ,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,QAAQ,EAAE,GAAG,OAAO,gBAAgB,EAAE,OAAO,CAAC,CAAC,CAAC;QACvF,QAAQ,CAAC,IAAI,CAAC,GAAG,wBAAwB,CAAC,QAAQ,EAAE,GAAG,OAAO,gBAAgB,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5F,CAAC;IACD,wEAAwE;IACxE,qEAAqE;IACrE,wEAAwE;IACxE,2EAA2E;IAC3E,2EAA2E;IAC3E,0DAA0D;IAC1D,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,OAAO;YAChB,OAAO,EAAE,GAAG,OAAO,+HAA+H;YAClJ,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;SACnE,CAAC,CAAC;IACL,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3E,MAAM,UAAU,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACjE,MAAM,KAAK,GAAkB;QAC3B,QAAQ,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,CAAC,UAAU,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC;QACxD,aAAa,EAAE,CAAC,GAAG,aAAa,EAAE,GAAG,CAAC,UAAU,EAAE,aAAa,IAAI,EAAE,CAAC,CAAC;QACvE,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC;QACnD,MAAM,EAAE,MAAM,CAAC,GAAG;QAClB,KAAK;KACN,CAAC;IACF,QAAQ,CAAC,IAAI,CACX,GAAG,qBAAqB,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,OAAO,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CACtH,CAAC;IACF,MAAM,YAAY,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC7C,KAAK,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI;QAC1B,EAAE,IAAI,EAAE,OAAgB,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE;QAClD,EAAE,IAAI,EAAE,KAAc,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE;KAC/C,EAAE,CAAC;QACF,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;YACrB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;gBAAE,SAAS;YACvE,QAAQ,CAAC,IAAI,CAAC;gBACZ,QAAQ,EAAE,MAAM;gBAChB,IAAI,EAAE,kBAAkB;gBACxB,OAAO,EAAE,OAAO;gBAChB,OAAO,EAAE,GAAG,OAAO,0BAA0B,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,yEAAyE,IAAI,IAAI,EAAE,gDAAgD;aAC1N,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,2EAA2E;IAC3E,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,CAAC,GAAG,wBAAwB,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAE9G,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * This service's requirement documents: spec.md, arch.spec.md, and the\n * obligations the second of them carries that the first never does.\n *\n * Two entry points because the two happen at different moments in a service's\n * grading and the order of findings is part of the report. `readServiceSpecs`\n * runs first — everything downstream joins through the requirements it parses —\n * while `archAxisFindings` runs last, after both spines, because `covers.unknown`\n * resolves against the C4 model and the landscape and cannot be answered until\n * those are in hand.\n *\n * The arch axis is advisory in what it ASKS for (covers.unknown,\n * health.uncovered are warnings; arch.spec.md's absence is not a finding at all,\n * because partial adoption is supported) but not in whether the file is\n * readable: a conflict marker or a stepless scenario is graded exactly as it is\n * on the business axis. One file, one rule.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { type Elem, type LoadedDoc, type Rel } from \"../../../core/c4/likec4.js\";\nimport { type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { type ServicePaths } from \"../../../core/repo/paths.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { parseRequirements } from \"../../../core/document/parse.js\";\nimport {\n  assertionlessFindings,\n  examplesFindings,\n  steplessFindings,\n} from \"../../../core/document/scenarios.js\";\nimport { type Requirement } from \"../../../core/document/spec.js\";\nimport { type CoverageScope } from \"../../../core/c4/arch.js\";\nimport { hasDeployment, type DeploymentModel } from \"../../../core/c4/parsed/deployment.js\";\nimport { loadArchitecture } from \"../../../core/c4/project/architecture.js\";\nimport { type DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { readHealth } from \"../../../core/vocabulary/health.js\";\nimport { documentConflictFinding } from \"../../../core/conflict-markers.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { healthDependencyFindings } from \"../checks/health-deps.js\";\nimport {\n  coverageFinding,\n  coversEntries,\n  coversUnknownFindings,\n  duplicateRequirementFindings,\n  repeatedListLineFindings,\n  requirementIdFindings,\n} from \"../checks/requirements.js\";\n\n/** Both requirement documents, parsed once for every axis that joins through them. */\nexport interface ServiceSpecs {\n  /** spec.md's findings, emitted before any cross-axis check runs. */\n  findings: Finding[];\n  /** Every requirement spec.md declares, REMOVED ones included. */\n  reqs: Requirement[];\n  /** The ones that still govern something. */\n  livingReqs: Requirement[];\n  /** arch.spec.md's text, or null when the service has none. */\n  archText: string | null;\n  archReqs: Requirement[];\n}\n\nexport async function readServiceSpecs(input: {\n  service: PathableService;\n  paths: ServicePaths;\n  fleet?: FleetContext;\n}): Promise<ServiceSpecs> {\n  const { service, paths, fleet } = input;\n  const findings: Finding[] = [];\n\n  // Requirement coverage.\n  let reqs: Requirement[] = [];\n  if (existsSync(paths.spec)) {\n    const specText =\n      fleet === undefined ? await readFile(paths.spec, \"utf8\") : await fleet.readText(paths.spec);\n    reqs = fleet === undefined ? parseRequirements(specText) : await fleet.readRequirements(paths.spec);\n    // Conflict markers first, because they say that nothing below this line is\n    // anyone's text. An error, gating by the default rule and deliberately\n    // without `gates`: that field is coherence's (issue.ts) and archive does\n    // not read validate's findings, so claiming it here would be a promise\n    // about a gate that is not wired. What makes it an error rather than a\n    // warning is what the next merge does — `loam archive` rewrites the\n    // requirements section of this very file and takes whichever marker lines\n    // fall inside it, turning a conflict anyone can see into a document nobody\n    // can tell is wrong.\n    const conflict = documentConflictFinding(`${service}: spec.md`, service, specText);\n    if (conflict !== null) findings.push(conflict);\n    // A living spec with no `### Requirement:` block at all is the baseline\n    // `loam adopt` scaffolds and nobody ever filled in. \"requirements covered\n    // (0 requirements, all with scenarios)\" is true of it and says the opposite\n    // of what a reader needs: every cross-axis check downstream — API\n    // governance, the Operations: spine, gherkin generation — is vacuous here,\n    // and the green tick is what let a whole fleet score `sourced` over empty\n    // files.\n    if (reqs.length === 0) {\n      findings.push({\n        severity: \"warn\",\n        code: \"spec.no-requirements\",\n        subject: service,\n        message: `${service}: spec.md holds no '### Requirement:' blocks — every requirement-driven check below is vacuous, and nothing here can go out of date because nothing is written down`,\n      });\n    } else {\n      findings.push(coverageFinding(`${service}: requirements`, reqs));\n    }\n    // The other half of the coverage question, and an error for the same\n    // reason the first half is: the whole claim of coverage is that a\n    // requirement has a scenario something can RUN. A heading with no steps\n    // satisfies the count and tests nothing — cucumber runs it vacuously green\n    // and `loam verify --results` can never confirm it — so a fleet gate that\n    // called it covered was certifying the absence of a test.\n    findings.push(...steplessFindings(`${service}: requirements`, service, reqs));\n    findings.push(...assertionlessFindings(`${service}: requirements`, service, reqs));\n    findings.push(...examplesFindings(`${service}: requirements`, service, reqs));\n    findings.push(...duplicateRequirementFindings(reqs, `${service}: spec.md`, service));\n    findings.push(...requirementIdFindings(reqs, `${service}: spec.md`, service));\n    findings.push(...repeatedListLineFindings(reqs, `${service}: spec.md`, service));\n  } else {\n    findings.push({\n      severity: \"warn\",\n      code: \"service.no-spec\",\n      message: `No living spec at ${paths.spec} — requirement coverage and API governance are unchecked`,\n    });\n  }\n\n  // The requirements that still govern anything. A REMOVED requirement is on\n  // its way out together with the operations it names: it makes no claim on the\n  // contract and governs nothing once the retiring feature archives — the same\n  // position coherence/coherence.ts takes on the delta side.\n  //\n  // Spelled once because it was spelled three times and dropped on the fourth:\n  // `governedOps` filtered, `spec-api.op-undefined` filtered, and the\n  // `api.covered` join did not — so an operation whose only requirement was\n  // REMOVED counted as governed, and the one operation about to be left without\n  // a requirement was the one the report called covered.\n  const livingReqs = reqs.filter((r) => r.kind !== \"REMOVED\");\n\n  // The architecture spec, read HERE with spec.md rather than with the rest of\n  // its own axis below, because the event links are a requirement-level join and\n  // BOTH requirement files carry them. Events are architecture as often as they\n  // are business — the outbox requirement in a service's arch.spec.md is the\n  // canonical place a `Publishes:` line belongs — so handing the event axis only\n  // spec.md would silently ignore the lines most authors write.\n  const archText = existsSync(paths.archSpec)\n    ? fleet === undefined\n      ? await readFile(paths.archSpec, \"utf8\")\n      : await fleet.readText(paths.archSpec)\n    : null;\n  const archReqs =\n    archText === null\n      ? []\n      : fleet === undefined\n        ? parseRequirements(archText)\n        : await fleet.readRequirements(paths.archSpec);\n\n  return { findings, reqs, livingReqs, archText, archReqs };\n}\n\n/** What the arch axis needs once the model and the landscape have been read. */\nexport interface ArchAxis {\n  service: PathableService;\n  paths: ServicePaths;\n  /** arch.spec.md's text, or null — its absence is not a finding. */\n  archText: string | null;\n  archReqs: Requirement[];\n  /** The service's own C4 model, empty when it has none. */\n  elements: Elem[];\n  relationships: Rel[];\n  /** The living landscape, or null when the repo has none. */\n  land: LoadedDoc | null;\n  /** The docs root, for the one lazy load below — see `deployment` in the scope. */\n  docsDir: DocsDir;\n  /**\n   * The enumerated fleet, for the Covers matcher's endpoint resolution — the\n   * same set the caller's own spine resolution uses, so a `Covers:` line\n   * naming a service matches an edge drawn into that service's container.\n   */\n  known?: ReadonlySet<string>;\n}\n\n/**\n * The topology a `node:` Covers entry resolves against, loaded at most once and\n * only when something asks for it.\n *\n * Under `--all` the caller hands in the doc it already loaded — the whole\n * `architecture/` project — so the deployment model is already here and this\n * returns it. A SINGLE-service run loads only `landscape.likec4`, and a fleet\n * that keeps its `deployment { }` block in a file beside it, which is the\n * ordinary layout once one landscape file is the fleet's convention, would then\n * resolve one `Covers:` line two different ways depending on which command\n * asked. `loam status`'s two forms had exactly that disagreement and it was a\n * defect both times; this is the same class, prevented rather than found.\n *\n * The cost is paid only by a service whose `arch.spec.md` actually writes a\n * `node:` entry. A fleet with no topology at all pays one project load per such\n * service — a state in which the entry is a typo anyway, and one load is what\n * buys it a message that names the real ids.\n */\nasync function topology(\n  land: LoadedDoc | null,\n  archReqs: Requirement[],\n  docsDir: DocsDir,\n): Promise<DeploymentModel | undefined> {\n  if (land?.deployment !== undefined && hasDeployment(land.deployment)) return land.deployment;\n  const wanted = coversEntries(archReqs).some((e) => e.form === \"node\" || e.form === \"node-edge\");\n  if (!wanted) return undefined;\n  const project = await loadArchitecture(docsDir);\n  return project.errors.length === 0 ? project.deployment : undefined;\n}\n\nexport async function archAxisFindings(axis: ArchAxis): Promise<Finding[]> {\n  const { service, paths, archText, archReqs, elements, relationships, land, known, docsDir } = axis;\n  const findings: Finding[] = [];\n\n  // The architecture spec axis — the obligations a business spec never carries\n  // (the transactional outbox, retries, metrics, alerts). arch.spec.md is\n  // optional and its ABSENCE is not a finding (partial adoption is supported);\n  // what exists must hold together: every requirement needs a scenario, every\n  // `Covers:` entry must resolve (covers.unknown), and every alert/SLI that\n  // health.yaml declares wants a covering requirement (health.uncovered) — the\n  // moment health.yaml stops being inert. Warnings, never gates: `--strict` is\n  // the CI escalation.\n  const health = await readHealth(paths.health);\n\n  // A model that reaches nothing is almost never true — but only when\n  // something else attests it should reach. A deliberately shallow synthetic\n  // fixture can hold elements without relationships beside sources that name\n  // dependencies, yet `0 errors, 0 warnings` would still read as done.\n  // Evidence-gated on purpose: a bare root-plus-one-container baseline stays\n  // silent (nothing PROVES it thin — the standard mid-adoption shape), the\n  // warn needs either a second nested element with no edge joining anything,\n  // or dependencies declared in this service's own health.yaml. The health\n  // half goes quiet when the file is unreadable — no claims on bad data.\n  const nested = elements.filter((e) => e.id.includes(\".\")).length;\n  const deps = health.unreadable ? [] : health.dependencies;\n  if (elements.length > 0 && relationships.length === 0 && (nested > 1 || deps.length > 0)) {\n    const evidence = [\n      ...(nested > 1 ? [`${nested} nested elements with no edge joining them`] : []),\n      ...(deps.length > 0\n        ? [`health.yaml declares ${deps.length} dependenc${deps.length === 1 ? \"y\" : \"ies\"} (${deps.join(\", \")})`]\n        : []),\n    ].join(\", and \");\n    findings.push({\n      severity: \"warn\",\n      code: \"c4.no-relationships\",\n      subject: service,\n      message:\n        `${service}: model.likec4 declares ${elements.length} element(s) and 0 relationships, yet ${evidence} — ` +\n        `a model that reaches nothing is almost never true; draw the edges the service actually has ` +\n        `(what its containers call, what reads and writes its stores, what it depends on at runtime)`,\n    });\n  }\n\n  if (archText !== null) {\n    // The arch axis is advisory in what it ASKS for (covers.unknown,\n    // health.uncovered are warnings) but not in whether the file is readable:\n    // both breaches below are about the document itself, and they are graded\n    // exactly as they are on the business axis — one file, one rule.\n    const conflict = documentConflictFinding(`${service}: arch.spec.md`, service, archText);\n    if (conflict !== null) findings.push(conflict);\n    findings.push(coverageFinding(`${service}: arch requirements`, archReqs));\n    findings.push(...steplessFindings(`${service}: arch requirements`, service, archReqs));\n    findings.push(...assertionlessFindings(`${service}: arch requirements`, service, archReqs));\n    findings.push(...examplesFindings(`${service}: arch requirements`, service, archReqs));\n    findings.push(...duplicateRequirementFindings(archReqs, `${service}: arch.spec.md`, service));\n    findings.push(...requirementIdFindings(archReqs, `${service}: arch.spec.md`, service));\n    findings.push(...repeatedListLineFindings(archReqs, `${service}: arch.spec.md`, service));\n  }\n  // A health.yaml that exists but does not read is reported once, and the\n  // checks that read it go quiet BOTH ways: its ids are unknown, so no\n  // health.uncovered obligation exists (the empty id set below is already\n  // silent), and no `Covers: alert:/sli:` entry may be graded a typo against\n  // ids nobody could read (coversUnknownFindings mutes on the flag). A warn,\n  // not an error: the axis it feeds is advisory end to end.\n  if (health.unreadable) {\n    findings.push({\n      severity: \"warn\",\n      code: \"health.invalid\",\n      subject: service,\n      message: `${service}: health.yaml does not parse — alert/SLI ids are unreadable, so Covers: alert:/sli: entries and health coverage are unchecked`,\n      ...(health.error === undefined ? {} : { details: [health.error] }),\n    });\n  }\n  const landParses = land !== null && land.errors.length === 0 ? land : null;\n  const deployment = await topology(landParses, archReqs, docsDir);\n  const scope: CoverageScope = {\n    elements: [...elements, ...(landParses?.elements ?? [])],\n    relationships: [...relationships, ...(landParses?.relationships ?? [])],\n    ...(deployment === undefined ? {} : { deployment }),\n    health: health.ids,\n    known,\n  };\n  findings.push(\n    ...coversUnknownFindings(archReqs, { where: `${service}: arch.spec.md`, subject: service }, scope, health.unreadable),\n  );\n  const activeCovers = coversEntries(archReqs);\n  for (const { form, ids } of [\n    { form: \"alert\" as const, ids: health.ids.alerts },\n    { form: \"sli\" as const, ids: health.ids.slis },\n  ]) {\n    for (const id of ids) {\n      if (activeCovers.some((e) => e.form === form && e.id === id)) continue;\n      findings.push({\n        severity: \"warn\",\n        code: \"health.uncovered\",\n        subject: service,\n        message: `${service}: health.yaml declares ${form === \"alert\" ? \"alert\" : \"SLI\"} '${id}' but no arch.spec.md requirement covers it — write one with 'Covers: ${form}:${id}', or the signal ships with nothing testing it`,\n      });\n    }\n  }\n  // The other direction health.yaml is read in: its dependencies must be the\n  // model's dependencies. `deps` is already muted on an unreadable file above.\n  findings.push(...healthDependencyFindings({ service, dependencies: deps, elements, modelPath: paths.model }));\n\n  return findings;\n}\n"]}

package/dist/commands/validate/service/spine.js

@@ -0,0 +1,113 @@
+/**
+ * The inbound half of the C4↔API spine: every cross-system edge the living
+ * landscape draws INTO this service must resolve to a real operation in its
+ * OpenAPI.
+ *
+ * Separate from `./api.js` because the two grade different documents and the
+ * fix lives in different files — a broken edge is the fleet map's mistake, a
+ * missing operation is the contract's — but it may conclude nothing without
+ * `api.js`'s answer, which is why `ServiceContract` is a parameter rather than
+ * a second read of openapi.yaml.
+ *
+ * The event-side mirror of this check is inside `./events.js`: there the
+ * PRODUCER owns the contract and it lives in another repository, so the two
+ * could not share a walk even though they share the shape.
+ */
+import {} from "../../../core/kernel/ids/service.js";
+import {} from "../../../core/c4/likec4.js";
+import {} from "../../../core/kernel/ids/service.js";
+import {} from "../../../core/vocabulary/report.js";
+import { errorText } from "../checks/vocabulary.js";
+import {} from "./api.js";
+export function spineFindings(spine) {
+    const { service, me, land, landSvcOf, contract } = spine;
+    const findings = [];
+    // Landscape spine: cross-system edges calling THIS service must resolve to a real
+    // operation in its OpenAPI — the C4↔API contract, checked in the living landscape,
+    // not only in feature mode. Catches dangling / de-linked op edges.
+    if (land !== null) {
+        if (land.errors.length > 0) {
+            // A living landscape that does not parse disables the C4↔API spine check —
+            // that is a broken source of truth, not a skippable detail.
+            //
+            // The parser's own output is attached ONCE per run, and not here when the
+            // run has a landscape target to carry it. One syntax error in one file
+            // becomes N copies of a dozen cascading diagnostics on a fleet of N
+            // services — the report stops being readable at exactly the moment
+            // somebody needs to read it, and the fix is one file either way.
+            findings.push({
+                severity: "error",
+                code: "spine.landscape-invalid",
+                subject: service,
+                message: `${service}: landscape.likec4 has ${land.errors.length} error(s) — spine check impossible` +
+                    (spine.landscapeReported === true
+                        ? "; the parser output is reported once, on the landscape target"
+                        : ""),
+                ...(spine.landscapeReported === true ? {} : { details: land.errors.map(errorText) }),
+            });
+        }
+        else {
+            // Which element IS this service is the binding's call, then a title that
+            // names a real services/<id>/, and an edge into a modelled container
+            // counts as an edge into its service — matching the exact id alone meant a
+            // container edge left the spine without a word.
+            const svcOf = landSvcOf;
+            const opset = new Set(contract.ops);
+            let checked = 0;
+            let broken = 0;
+            for (const r of land.relationships) {
+                if (svcOf(r.target) !== me)
+                    continue;
+                if (r.op !== undefined) {
+                    // A contract that cannot be read — broken, or not there at all —
+                    // proves nothing about this edge, neither broken nor resolved.
+                    // Grading the edges against an empty operation set turned ONE root
+                    // cause (the file) into one `spine.op-undefined` per inbound edge, so
+                    // a service with twelve consumers reported twelve landscape defects
+                    // and never named the file. `openapi.invalid` / `service.no-openapi`
+                    // already did, from ./api.js; only op-link-missing (which never reads
+                    // the contract) stays live, and `checked` stays 0 so no false
+                    // spine.resolved is claimed either.
+                    if (contract.unreadable)
+                        continue;
+                    checked += 1;
+                    if (!opset.has(r.op)) {
+                        broken += 1;
+                        findings.push({
+                            severity: "error",
+                            code: "spine.op-undefined",
+                            message: `${service}: landscape edge ${svcOf(r.source)} → ${service} calls '${r.op}', not defined in ${service}'s OpenAPI`,
+                        });
+                    }
+                    else if (contract.deprecated.has(r.op)) {
+                        // The contract holds — the op is defined — but it is marked
+                        // `deprecated: true`: the consumer is standing on a contract being
+                        // retired, and should be migrating off it. Warn per inbound edge;
+                        // a deprecated op nobody calls raises no spine finding at all.
+                        findings.push({
+                            severity: "warn",
+                            code: "spine.op-deprecated",
+                            message: `${service}: landscape edge ${svcOf(r.source)} → ${service} calls '${r.op}', which ${service}'s OpenAPI marks deprecated — the consumer should migrate off it`,
+                        });
+                    }
+                }
+                else if ((r.title ?? "").toLowerCase().startsWith("call")) {
+                    findings.push({
+                        severity: "warn",
+                        code: "spine.op-link-missing",
+                        message: `${service}: landscape edge ${svcOf(r.source)} → ${service} ("${r.title}") has no operation link (metadata { op })`,
+                    });
+                }
+            }
+            if (broken === 0 && checked > 0) {
+                findings.push({
+                    severity: "ok",
+                    code: "spine.resolved",
+                    message: `${service}: landscape spine (${checked} inbound call(s) resolve to OpenAPI)`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=spine.js.map

package/dist/commands/validate/service/spine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spine.js","sourceRoot":"","sources":["../../../../src/commands/validate/service/spine.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The inbound half of the C4↔API spine: every cross-system edge the living\n * landscape draws INTO this service must resolve to a real operation in its\n * OpenAPI.\n *\n * Separate from `./api.js` because the two grade different documents and the\n * fix lives in different files — a broken edge is the fleet map's mistake, a\n * missing operation is the contract's — but it may conclude nothing without\n * `api.js`'s answer, which is why `ServiceContract` is a parameter rather than\n * a second read of openapi.yaml.\n *\n * The event-side mirror of this check is inside `./events.js`: there the\n * PRODUCER owns the contract and it lives in another repository, so the two\n * could not share a walk even though they share the shape.\n */\nimport { type DeclaredService } from \"../../../core/kernel/ids/service.js\";\nimport { type LoadedDoc } from \"../../../core/c4/likec4.js\";\nimport { type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { errorText } from \"../checks/vocabulary.js\";\nimport { type ServiceContract } from \"./api.js\";\n\n/** What the service target hands the spine check. */\nexport interface Spine {\n  service: PathableService;\n  /** `service` widened for `===` against the resolver's DOCUMENT text — see service.ts. */\n  me: string;\n  /** The living landscape, or null when the repo has none. */\n  land: LoadedDoc | null;\n  /** Its element→service resolver; null exactly when `land` is. */\n  landSvcOf: ((id: string) => DeclaredService) | null;\n  contract: ServiceContract;\n  /** True when this run also emits a landscape target — see `ServiceCheck`. */\n  landscapeReported?: boolean;\n}\n\nexport function spineFindings(spine: Spine): Finding[] {\n  const { service, me, land, landSvcOf, contract } = spine;\n  const findings: Finding[] = [];\n\n  // Landscape spine: cross-system edges calling THIS service must resolve to a real\n  // operation in its OpenAPI — the C4↔API contract, checked in the living landscape,\n  // not only in feature mode. Catches dangling / de-linked op edges.\n  if (land !== null) {\n    if (land.errors.length > 0) {\n      // A living landscape that does not parse disables the C4↔API spine check —\n      // that is a broken source of truth, not a skippable detail.\n      //\n      // The parser's own output is attached ONCE per run, and not here when the\n      // run has a landscape target to carry it. One syntax error in one file\n      // becomes N copies of a dozen cascading diagnostics on a fleet of N\n      // services — the report stops being readable at exactly the moment\n      // somebody needs to read it, and the fix is one file either way.\n      findings.push({\n        severity: \"error\",\n        code: \"spine.landscape-invalid\",\n        subject: service,\n        message:\n          `${service}: landscape.likec4 has ${land.errors.length} error(s) — spine check impossible` +\n          (spine.landscapeReported === true\n            ? \"; the parser output is reported once, on the landscape target\"\n            : \"\"),\n        ...(spine.landscapeReported === true ? {} : { details: land.errors.map(errorText) }),\n      });\n    } else {\n      // Which element IS this service is the binding's call, then a title that\n      // names a real services/<id>/, and an edge into a modelled container\n      // counts as an edge into its service — matching the exact id alone meant a\n      // container edge left the spine without a word.\n      const svcOf = landSvcOf!;\n      const opset = new Set(contract.ops);\n      let checked = 0;\n      let broken = 0;\n      for (const r of land.relationships) {\n        if (svcOf(r.target) !== me) continue;\n        if (r.op !== undefined) {\n          // A contract that cannot be read — broken, or not there at all —\n          // proves nothing about this edge, neither broken nor resolved.\n          // Grading the edges against an empty operation set turned ONE root\n          // cause (the file) into one `spine.op-undefined` per inbound edge, so\n          // a service with twelve consumers reported twelve landscape defects\n          // and never named the file. `openapi.invalid` / `service.no-openapi`\n          // already did, from ./api.js; only op-link-missing (which never reads\n          // the contract) stays live, and `checked` stays 0 so no false\n          // spine.resolved is claimed either.\n          if (contract.unreadable) continue;\n          checked += 1;\n          if (!opset.has(r.op)) {\n            broken += 1;\n            findings.push({\n              severity: \"error\",\n              code: \"spine.op-undefined\",\n              message: `${service}: landscape edge ${svcOf(r.source)} → ${service} calls '${r.op}', not defined in ${service}'s OpenAPI`,\n            });\n          } else if (contract.deprecated.has(r.op)) {\n            // The contract holds — the op is defined — but it is marked\n            // `deprecated: true`: the consumer is standing on a contract being\n            // retired, and should be migrating off it. Warn per inbound edge;\n            // a deprecated op nobody calls raises no spine finding at all.\n            findings.push({\n              severity: \"warn\",\n              code: \"spine.op-deprecated\",\n              message: `${service}: landscape edge ${svcOf(r.source)} → ${service} calls '${r.op}', which ${service}'s OpenAPI marks deprecated — the consumer should migrate off it`,\n            });\n          }\n        } else if ((r.title ?? \"\").toLowerCase().startsWith(\"call\")) {\n          findings.push({\n            severity: \"warn\",\n            code: \"spine.op-link-missing\",\n            message: `${service}: landscape edge ${svcOf(r.source)} → ${service} (\"${r.title}\") has no operation link (metadata { op })`,\n          });\n        }\n      }\n      if (broken === 0 && checked > 0) {\n        findings.push({\n          severity: \"ok\",\n          code: \"spine.resolved\",\n          message: `${service}: landscape spine (${checked} inbound call(s) resolve to OpenAPI)`,\n        });\n      }\n    }\n  }\n\n  return findings;\n}\n"]}