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

package/dist/commands/validate/checks/requirements.js

@@ -0,0 +1,254 @@
+/**
+ * What a requirement document owes, checked the same way wherever it lives.
+ *
+ * The same `### Requirement:` grammar is authored in four places — a service's
+ * spec.md and arch.spec.md, and a feature's per-service deltas of both — and
+ * every breach below carries from a delta into the living document through the
+ * archive merge. So the checks are one set called from both target kinds
+ * (`service/` and `feature/`): grading a delta more leniently than the file it
+ * is about to become is how a defect acquires a signature saying it was
+ * reviewed.
+ *
+ * None of these read the filesystem and none of them print — they take parsed
+ * requirements and answer in findings.
+ */
+import {} from "../../../core/vocabulary/report.js";
+import { requirementsMissingScenarios } from "../../../core/document/scenarios.js";
+import { requirementIdProblems } from "../../../core/document/spec.js";
+import { closeIds, coversCandidates, entryResolves, parseCoversEntry, } from "../../../core/c4/arch.js";
+import {} from "../../../core/permissions/permissions.js";
+import {} from "../../../core/openapi/doc.js";
+/** The parsed Covers entries of every requirement that will live (REMOVED covers nothing). */
+export function coversEntries(reqs) {
+    return reqs.filter((r) => r.kind !== "REMOVED").flatMap((r) => r.covers.map(parseCoversEntry));
+}
+/**
+ * `spec.duplicate-requirement` — two `### Requirement:` blocks with one name in
+ * one LIVING document. Nothing else catches it, and the merge algebra
+ * (applyRequirementDelta) matches by name and edits only the FIRST match: a
+ * later archive rewrites one copy and the other survives as a stale snapshot
+ * of whatever the requirement used to say. Per file on purpose — spec.md and
+ * arch.spec.md are separate requirement namespaces (their merges never cross
+ * files), so one name appearing in both is legal and unflagged.
+ */
+export function duplicateRequirementFindings(reqs, where, subject) {
+    const counts = new Map();
+    for (const r of reqs)
+        counts.set(r.name, (counts.get(r.name) ?? 0) + 1);
+    return [...counts]
+        .filter(([, n]) => n > 1)
+        .map(([name, n]) => ({
+        severity: "error",
+        code: "spec.duplicate-requirement",
+        subject,
+        message: `${where}: requirement '${name}' is defined ${n} times — a merge edits only the first, every other copy lives on stale; keep exactly one`,
+    }));
+}
+/** Stable IDs are optional, but once authored they must select exactly one requirement. */
+export function requirementIdFindings(reqs, where, subject) {
+    return requirementIdProblems(reqs).map((problem) => {
+        if (problem.kind === "invalid") {
+            return {
+                severity: "error",
+                code: "spec.requirement-id-invalid",
+                subject,
+                message: `${where}: requirement '${problem.requirement}' has invalid Requirement-ID '${problem.value}' — use 1-128 characters matching [A-Za-z][A-Za-z0-9._-]*`,
+            };
+        }
+        if (problem.kind === "repeated") {
+            return {
+                severity: "error",
+                code: "spec.requirement-id-repeated",
+                subject,
+                message: `${where}: requirement '${problem.requirement}' declares Requirement-ID ${problem.values.length} times — identity must be declared exactly once`,
+            };
+        }
+        return {
+            severity: "error",
+            code: "spec.requirement-id-duplicate",
+            subject,
+            message: `${where}: Requirement-ID '${problem.id}' is shared by ${problem.requirements.map((name) => `'${name}'`).join(", ")} — one ID may identify only one requirement`,
+        };
+    });
+}
+/**
+ * The two list lines of the requirement grammar, exactly as core/document/spec.ts spells
+ * them (mirrored here, not exported from there, because the parser's grammar is
+ * its own; a drift shows up as this check counting differently than the parser
+ * assigns). A SECOND matching line in one requirement body REPLACES the first —
+ * assignment, not append, the documented keep-last quirk — so the author's
+ * "long list in two lines" pattern silently loses its first line.
+ */
+const OPERATIONS_LINE_RE = /^\s*Operations?:\s*(.+?)\s*$/i;
+const COVERS_LINE_RE = /^\s*Covers?:\s*(.+?)\s*$/i;
+/**
+ * `spec.repeated-operations` / `spec.repeated-covers` — warn on the silent
+ * loss, keep the keep-last semantics (changing them would re-read every spec
+ * in the fleet). Scenario bodies never count: the parser only assigns from the
+ * requirement's own body lines, and `Requirement.text` is exactly those.
+ * REMOVED requirements are exempt the way coversEntries exempts them — content
+ * on its way out obliges nothing.
+ */
+export function repeatedListLineFindings(reqs, where, subject) {
+    const out = [];
+    for (const r of reqs) {
+        if (r.kind === "REMOVED")
+            continue;
+        for (const { re, label, code } of [
+            { re: OPERATIONS_LINE_RE, label: "Operations:", code: "spec.repeated-operations" },
+            { re: COVERS_LINE_RE, label: "Covers:", code: "spec.repeated-covers" },
+        ]) {
+            const n = r.text.filter((line) => re.test(line)).length;
+            if (n < 2)
+                continue;
+            out.push({
+                severity: "warn",
+                code,
+                subject,
+                message: `${where}: requirement '${r.name}' has ${n} '${label}' lines — the last REPLACES the others (assignment, not append), the earlier list is silently lost; merge them into one comma-separated line`,
+            });
+        }
+    }
+    return out;
+}
+export function coversUnknownFindings(reqs, target, scope, healthUnreadable = false) {
+    const { where, subject } = target;
+    const out = [];
+    for (const r of reqs) {
+        if (r.kind === "REMOVED")
+            continue;
+        for (const raw of r.covers) {
+            const entry = parseCoversEntry(raw);
+            if (healthUnreadable && (entry.form === "alert" || entry.form === "sli"))
+                continue;
+            if (entryResolves(entry, scope))
+                continue;
+            const close = coversCandidates(entry, scope);
+            out.push({
+                severity: "warn",
+                code: "covers.unknown",
+                subject,
+                message: `${where}: requirement '${r.name}' — Covers: '${raw}' resolves to nothing` +
+                    (close.length > 0
+                        ? `. Did you mean: ${close.join(", ")}?`
+                        : " in the model, the landscape or health.yaml"),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * `permissions.unknown` — the typo guard on the `Requires:` line, and an ERROR
+ * where its `Covers:` sibling is a warning.
+ *
+ * The two differ because what they promise differs. `Covers:` is advisory end
+ * to end: a wrong id costs its author the coverage they wrote the line for and
+ * nothing else. `Requires:` names authorization the service actually enforces,
+ * and the failure it guards is the one an unaided reader cannot see — an
+ * invented permission reads exactly like a real one, in the requirement, in the
+ * generated scenario, and in the test somebody then writes against it. Its
+ * grade is `Operations:`', not `Covers:`'.
+ *
+ * Silent on ONE case only: an unreadable vocabulary, where
+ * `permissions.invalid` is the honest finding and grading every entry against a
+ * file nobody could parse is the false cascade `healthUnreadable` exists to
+ * stop one axis over. A MISSING vocabulary is not that case — the `Requires:`
+ * line is itself the opt-in, and a line that resolves against nothing while
+ * reading like a join is the failure this whole axis exists to prevent.
+ */
+export function requiresUnknownFindings(reqs, target, vocabulary) {
+    const { where, subject } = target;
+    if (vocabulary.invalid !== undefined)
+        return [];
+    const known = [...vocabulary.byId.keys()];
+    const out = [];
+    for (const r of reqs) {
+        if (r.kind === "REMOVED")
+            continue;
+        for (const raw of r.requires) {
+            if (vocabulary.byId.has(raw))
+                continue;
+            const close = closeIds(raw, known);
+            out.push({
+                severity: "error",
+                code: "permissions.unknown",
+                subject,
+                message: `${where}: requirement '${r.name}' — Requires: '${raw}' is not declared in architecture/permissions.yaml` +
+                    (!vocabulary.present
+                        ? ", which does not exist. The `Requires:` line is the opt-in: create the fleet vocabulary with this permission under its subject kind, or drop the line"
+                        : close.length > 0
+                            ? `. Did you mean: ${close.join(", ")}?`
+                            : ". Entries are '<subject>/<permission>'; declare it there, or fix the spelling"),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * `api.response-ungoverned` — a declared 4xx/5xx response no scenario reaches.
+ *
+ * The gap this closes is the one a whole adoption can fall into: `api.ungoverned`
+ * grades OPERATIONS against requirements, so an endpoint with one happy-path
+ * requirement and twelve declared failure codes is fully governed by every
+ * check loam had. The refusals are where a service's decision layer surfaces —
+ * a permission denied, a field combination rejected, a state that forbids the
+ * transition — and the contract is the only artifact in the corpus that already
+ * enumerates them.
+ *
+ * A scenario "reaches" a code when the code appears as a standalone number
+ * anywhere in its body, `Examples` rows included — which is why this arrived
+ * with outline support and not before: a status column is exactly where a
+ * matrix puts its codes, and before it those rows were prose in a description.
+ * The match is textual and therefore generous by design. It answers "did
+ * anybody write this case down", not "is this scenario correct", and the
+ * failure it is built to catch is the code nobody mentioned at all. Warn, like
+ * its sibling: a service may legitimately declare a code its scenarios describe
+ * in words, and an error would teach authors to paste numbers into prose.
+ *
+ * Operations no requirement governs are skipped: `api.ungoverned` already
+ * names those, and reporting each of their codes as well is one defect
+ * counted twice.
+ */
+export function responseGovernanceFindings(service, ops, livingReqs) {
+    const ungoverned = [];
+    for (const op of ops) {
+        if (op.failureCodes.length === 0)
+            continue;
+        const governing = livingReqs.filter((r) => r.kind !== "REMOVED" && r.operations.includes(op.id));
+        if (governing.length === 0)
+            continue;
+        const body = governing.flatMap((r) => r.scenarios.flatMap((s) => s.lines)).join("\n");
+        const missing = op.failureCodes.filter((code) => !new RegExp(`(?<!\\d)${code}(?!\\d)`).test(body));
+        if (missing.length > 0)
+            ungoverned.push(`${op.id}: ${missing.join(", ")}`);
+    }
+    if (ungoverned.length === 0)
+        return [];
+    return [
+        {
+            severity: "warn",
+            code: "api.response-ungoverned",
+            subject: service,
+            message: `${service}: ${ungoverned.length} operation(s) declare a failure response no scenario reaches — write the refusal as a scenario, or as a row in one`,
+            details: ungoverned,
+        },
+    ];
+}
+export function coverageFinding(label, reqs) {
+    const missing = requirementsMissingScenarios(reqs);
+    if (missing.length === 0) {
+        return {
+            severity: "ok",
+            code: "requirements.covered",
+            message: `${label} covered (${reqs.length} requirement${reqs.length === 1 ? "" : "s"}, all with scenarios)`,
+        };
+    }
+    return {
+        severity: "error",
+        code: "requirements.missing-scenarios",
+        message: `${label}: ${missing.length} requirement(s) without a scenario`,
+        details: missing.map((r) => r.name),
+        text: { detailPrefix: "- " },
+    };
+}
+//# sourceMappingURL=requirements.js.map

package/dist/commands/validate/checks/requirements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirements.js","sourceRoot":"","sources":["../../../../src/commands/validate/checks/requirements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAgB,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,4BAA4B,EAAE,MAAM,qCAAqC,CAAC;AACnF,OAAO,EAAE,qBAAqB,EAAoB,MAAM,gCAAgC,CAAC;AACzF,OAAO,EACL,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,gBAAgB,GAGjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAmB,MAAM,0CAA0C,CAAC;AAC3E,OAAO,EAAkB,MAAM,8BAA8B,CAAC;AAE9D,8FAA8F;AAC9F,MAAM,UAAU,aAAa,CAAC,IAAmB;IAC/C,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC;AACjG,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B,CAAC,IAAmB,EAAE,KAAa,EAAE,OAAe;IAC9F,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxE,OAAO,CAAC,GAAG,MAAM,CAAC;SACf,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;SACxB,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACnB,QAAQ,EAAE,OAAgB;QAC1B,IAAI,EAAE,4BAA4B;QAClC,OAAO;QACP,OAAO,EAAE,GAAG,KAAK,kBAAkB,IAAI,gBAAgB,CAAC,0FAA0F;KACnJ,CAAC,CAAC,CAAC;AACR,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,qBAAqB,CAAC,IAAmB,EAAE,KAAa,EAAE,OAAe;IACvF,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACjD,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO;gBACL,QAAQ,EAAE,OAAgB;gBAC1B,IAAI,EAAE,6BAA6B;gBACnC,OAAO;gBACP,OAAO,EAAE,GAAG,KAAK,kBAAkB,OAAO,CAAC,WAAW,iCAAiC,OAAO,CAAC,KAAK,2DAA2D;aAChK,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAChC,OAAO;gBACL,QAAQ,EAAE,OAAgB;gBAC1B,IAAI,EAAE,8BAA8B;gBACpC,OAAO;gBACP,OAAO,EAAE,GAAG,KAAK,kBAAkB,OAAO,CAAC,WAAW,6BAA6B,OAAO,CAAC,MAAM,CAAC,MAAM,iDAAiD;aAC1J,CAAC;QACJ,CAAC;QACD,OAAO;YACL,QAAQ,EAAE,OAAgB;YAC1B,IAAI,EAAE,+BAA+B;YACrC,OAAO;YACP,OAAO,EAAE,GAAG,KAAK,qBAAqB,OAAO,CAAC,EAAE,kBAAkB,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,6CAA6C;SAC1K,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,kBAAkB,GAAG,+BAA+B,CAAC;AAC3D,MAAM,cAAc,GAAG,2BAA2B,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAmB,EAAE,KAAa,EAAE,OAAe;IAC1F,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QACnC,KAAK,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI;YAChC,EAAE,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,0BAA0B,EAAE;YAClF,EAAE,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,sBAAsB,EAAE;SACvE,EAAE,CAAC;YACF,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;YACxD,IAAI,CAAC,GAAG,CAAC;gBAAE,SAAS;YACpB,GAAG,CAAC,IAAI,CAAC;gBACP,QAAQ,EAAE,MAAM;gBAChB,IAAI;gBACJ,OAAO;gBACP,OAAO,EAAE,GAAG,KAAK,kBAAkB,CAAC,CAAC,IAAI,SAAS,CAAC,KAAK,KAAK,8IAA8I;aAC5M,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAiBD,MAAM,UAAU,qBAAqB,CACnC,IAAmB,EACnB,MAAsB,EACtB,KAAoB,EACpB,gBAAgB,GAAG,KAAK;IAExB,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAClC,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QACnC,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;YACpC,IAAI,gBAAgB,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC;gBAAE,SAAS;YACnF,IAAI,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC;gBAAE,SAAS;YAC1C,MAAM,KAAK,GAAG,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAC7C,GAAG,CAAC,IAAI,CAAC;gBACP,QAAQ,EAAE,MAAM;gBAChB,IAAI,EAAE,gBAAgB;gBACtB,OAAO;gBACP,OAAO,EACL,GAAG,KAAK,kBAAkB,CAAC,CAAC,IAAI,gBAAgB,GAAG,uBAAuB;oBAC1E,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;wBACf,CAAC,CAAC,mBAAmB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;wBACxC,CAAC,CAAC,6CAA6C,CAAC;aACrD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CACrC,IAAmB,EACnB,MAAsB,EACtB,UAAsB;IAEtB,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAClC,IAAI,UAAU,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAChD,MAAM,KAAK,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QACnC,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;YAC7B,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YACvC,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACnC,GAAG,CAAC,IAAI,CAAC;gBACP,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,qBAAqB;gBAC3B,OAAO;gBACP,OAAO,EACL,GAAG,KAAK,kBAAkB,CAAC,CAAC,IAAI,kBAAkB,GAAG,oDAAoD;oBACzG,CAAC,CAAC,UAAU,CAAC,OAAO;wBAClB,CAAC,CAAC,uJAAuJ;wBACzJ,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;4BAChB,CAAC,CAAC,mBAAmB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;4BACxC,CAAC,CAAC,+EAA+E,CAAC;aACzF,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAe,EACf,GAAgB,EAChB,UAAyB;IAEzB,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,IAAI,EAAE,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAC3C,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACjG,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACrC,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtF,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,WAAW,IAAI,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACnG,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACvC,OAAO;QACL;YACE,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,yBAAyB;YAC/B,OAAO,EAAE,OAAO;YAChB,OAAO,EAAE,GAAG,OAAO,KAAK,UAAU,CAAC,MAAM,oHAAoH;YAC7J,OAAO,EAAE,UAAU;SACpB;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,IAAmB;IAChE,MAAM,OAAO,GAAG,4BAA4B,CAAC,IAAI,CAAC,CAAC;IACnD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,QAAQ,EAAE,IAAI;YACd,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EAAE,GAAG,KAAK,aAAa,IAAI,CAAC,MAAM,eAAe,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,uBAAuB;SAC5G,CAAC;IACJ,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,gCAAgC;QACtC,OAAO,EAAE,GAAG,KAAK,KAAK,OAAO,CAAC,MAAM,oCAAoC;QACxE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACnC,IAAI,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;KAC7B,CAAC;AACJ,CAAC","sourcesContent":["/**\n * What a requirement document owes, checked the same way wherever it lives.\n *\n * The same `### Requirement:` grammar is authored in four places — a service's\n * spec.md and arch.spec.md, and a feature's per-service deltas of both — and\n * every breach below carries from a delta into the living document through the\n * archive merge. So the checks are one set called from both target kinds\n * (`service/` and `feature/`): grading a delta more leniently than the file it\n * is about to become is how a defect acquires a signature saying it was\n * reviewed.\n *\n * None of these read the filesystem and none of them print — they take parsed\n * requirements and answer in findings.\n */\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { requirementsMissingScenarios } from \"../../../core/document/scenarios.js\";\nimport { requirementIdProblems, type Requirement } from \"../../../core/document/spec.js\";\nimport {\n  closeIds,\n  coversCandidates,\n  entryResolves,\n  parseCoversEntry,\n  type CoverageScope,\n  type CoversEntry,\n} from \"../../../core/c4/arch.js\";\nimport { type Vocabulary } from \"../../../core/permissions/permissions.js\";\nimport { type Operation } from \"../../../core/openapi/doc.js\";\n\n/** The parsed Covers entries of every requirement that will live (REMOVED covers nothing). */\nexport function coversEntries(reqs: Requirement[]): CoversEntry[] {\n  return reqs.filter((r) => r.kind !== \"REMOVED\").flatMap((r) => r.covers.map(parseCoversEntry));\n}\n\n/**\n * `spec.duplicate-requirement` — two `### Requirement:` blocks with one name in\n * one LIVING document. Nothing else catches it, and the merge algebra\n * (applyRequirementDelta) matches by name and edits only the FIRST match: a\n * later archive rewrites one copy and the other survives as a stale snapshot\n * of whatever the requirement used to say. Per file on purpose — spec.md and\n * arch.spec.md are separate requirement namespaces (their merges never cross\n * files), so one name appearing in both is legal and unflagged.\n */\nexport function duplicateRequirementFindings(reqs: Requirement[], where: string, subject: string): Finding[] {\n  const counts = new Map<string, number>();\n  for (const r of reqs) counts.set(r.name, (counts.get(r.name) ?? 0) + 1);\n  return [...counts]\n    .filter(([, n]) => n > 1)\n    .map(([name, n]) => ({\n      severity: \"error\" as const,\n      code: \"spec.duplicate-requirement\",\n      subject,\n      message: `${where}: requirement '${name}' is defined ${n} times — a merge edits only the first, every other copy lives on stale; keep exactly one`,\n    }));\n}\n\n/** Stable IDs are optional, but once authored they must select exactly one requirement. */\nexport function requirementIdFindings(reqs: Requirement[], where: string, subject: string): Finding[] {\n  return requirementIdProblems(reqs).map((problem) => {\n    if (problem.kind === \"invalid\") {\n      return {\n        severity: \"error\" as const,\n        code: \"spec.requirement-id-invalid\",\n        subject,\n        message: `${where}: requirement '${problem.requirement}' has invalid Requirement-ID '${problem.value}' — use 1-128 characters matching [A-Za-z][A-Za-z0-9._-]*`,\n      };\n    }\n    if (problem.kind === \"repeated\") {\n      return {\n        severity: \"error\" as const,\n        code: \"spec.requirement-id-repeated\",\n        subject,\n        message: `${where}: requirement '${problem.requirement}' declares Requirement-ID ${problem.values.length} times — identity must be declared exactly once`,\n      };\n    }\n    return {\n      severity: \"error\" as const,\n      code: \"spec.requirement-id-duplicate\",\n      subject,\n      message: `${where}: Requirement-ID '${problem.id}' is shared by ${problem.requirements.map((name) => `'${name}'`).join(\", \")} — one ID may identify only one requirement`,\n    };\n  });\n}\n\n/**\n * The two list lines of the requirement grammar, exactly as core/document/spec.ts spells\n * them (mirrored here, not exported from there, because the parser's grammar is\n * its own; a drift shows up as this check counting differently than the parser\n * assigns). A SECOND matching line in one requirement body REPLACES the first —\n * assignment, not append, the documented keep-last quirk — so the author's\n * \"long list in two lines\" pattern silently loses its first line.\n */\nconst OPERATIONS_LINE_RE = /^\\s*Operations?:\\s*(.+?)\\s*$/i;\nconst COVERS_LINE_RE = /^\\s*Covers?:\\s*(.+?)\\s*$/i;\n\n/**\n * `spec.repeated-operations` / `spec.repeated-covers` — warn on the silent\n * loss, keep the keep-last semantics (changing them would re-read every spec\n * in the fleet). Scenario bodies never count: the parser only assigns from the\n * requirement's own body lines, and `Requirement.text` is exactly those.\n * REMOVED requirements are exempt the way coversEntries exempts them — content\n * on its way out obliges nothing.\n */\nexport function repeatedListLineFindings(reqs: Requirement[], where: string, subject: string): Finding[] {\n  const out: Finding[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const { re, label, code } of [\n      { re: OPERATIONS_LINE_RE, label: \"Operations:\", code: \"spec.repeated-operations\" },\n      { re: COVERS_LINE_RE, label: \"Covers:\", code: \"spec.repeated-covers\" },\n    ]) {\n      const n = r.text.filter((line) => re.test(line)).length;\n      if (n < 2) continue;\n      out.push({\n        severity: \"warn\",\n        code,\n        subject,\n        message: `${where}: requirement '${r.name}' has ${n} '${label}' lines — the last REPLACES the others (assignment, not append), the earlier list is silently lost; merge them into one comma-separated line`,\n      });\n    }\n  }\n  return out;\n}\n\n/**\n * `covers.unknown` — the typo guard on the Covers: line. Warn, not error: the\n * axis is advisory end to end, and a wrong id already costs its author the\n * coverage they wrote the line for. The hint offers only real ids (closeIds's\n * rule), and says where resolution looked when there is nothing close.\n * `healthUnreadable` mutes the alert:/sli: forms only: against a health.yaml\n * nobody could read, \"did you mean\" is a false diagnosis of a typo —\n * health.invalid (emitted by the service target) is the honest one.\n */\n/** Which document is being graded, and under whose name the finding is filed. */\nexport interface CoverageTarget {\n  where: string;\n  subject: string;\n}\n\nexport function coversUnknownFindings(\n  reqs: Requirement[],\n  target: CoverageTarget,\n  scope: CoverageScope,\n  healthUnreadable = false,\n): Finding[] {\n  const { where, subject } = target;\n  const out: Finding[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const raw of r.covers) {\n      const entry = parseCoversEntry(raw);\n      if (healthUnreadable && (entry.form === \"alert\" || entry.form === \"sli\")) continue;\n      if (entryResolves(entry, scope)) continue;\n      const close = coversCandidates(entry, scope);\n      out.push({\n        severity: \"warn\",\n        code: \"covers.unknown\",\n        subject,\n        message:\n          `${where}: requirement '${r.name}' — Covers: '${raw}' resolves to nothing` +\n          (close.length > 0\n            ? `. Did you mean: ${close.join(\", \")}?`\n            : \" in the model, the landscape or health.yaml\"),\n      });\n    }\n  }\n  return out;\n}\n\n/**\n * `permissions.unknown` — the typo guard on the `Requires:` line, and an ERROR\n * where its `Covers:` sibling is a warning.\n *\n * The two differ because what they promise differs. `Covers:` is advisory end\n * to end: a wrong id costs its author the coverage they wrote the line for and\n * nothing else. `Requires:` names authorization the service actually enforces,\n * and the failure it guards is the one an unaided reader cannot see — an\n * invented permission reads exactly like a real one, in the requirement, in the\n * generated scenario, and in the test somebody then writes against it. Its\n * grade is `Operations:`', not `Covers:`'.\n *\n * Silent on ONE case only: an unreadable vocabulary, where\n * `permissions.invalid` is the honest finding and grading every entry against a\n * file nobody could parse is the false cascade `healthUnreadable` exists to\n * stop one axis over. A MISSING vocabulary is not that case — the `Requires:`\n * line is itself the opt-in, and a line that resolves against nothing while\n * reading like a join is the failure this whole axis exists to prevent.\n */\nexport function requiresUnknownFindings(\n  reqs: Requirement[],\n  target: CoverageTarget,\n  vocabulary: Vocabulary,\n): Finding[] {\n  const { where, subject } = target;\n  if (vocabulary.invalid !== undefined) return [];\n  const known = [...vocabulary.byId.keys()];\n  const out: Finding[] = [];\n  for (const r of reqs) {\n    if (r.kind === \"REMOVED\") continue;\n    for (const raw of r.requires) {\n      if (vocabulary.byId.has(raw)) continue;\n      const close = closeIds(raw, known);\n      out.push({\n        severity: \"error\",\n        code: \"permissions.unknown\",\n        subject,\n        message:\n          `${where}: requirement '${r.name}' — Requires: '${raw}' is not declared in architecture/permissions.yaml` +\n          (!vocabulary.present\n            ? \", which does not exist. The `Requires:` line is the opt-in: create the fleet vocabulary with this permission under its subject kind, or drop the line\"\n            : close.length > 0\n              ? `. Did you mean: ${close.join(\", \")}?`\n              : \". Entries are '<subject>/<permission>'; declare it there, or fix the spelling\"),\n      });\n    }\n  }\n  return out;\n}\n\n/**\n * `api.response-ungoverned` — a declared 4xx/5xx response no scenario reaches.\n *\n * The gap this closes is the one a whole adoption can fall into: `api.ungoverned`\n * grades OPERATIONS against requirements, so an endpoint with one happy-path\n * requirement and twelve declared failure codes is fully governed by every\n * check loam had. The refusals are where a service's decision layer surfaces —\n * a permission denied, a field combination rejected, a state that forbids the\n * transition — and the contract is the only artifact in the corpus that already\n * enumerates them.\n *\n * A scenario \"reaches\" a code when the code appears as a standalone number\n * anywhere in its body, `Examples` rows included — which is why this arrived\n * with outline support and not before: a status column is exactly where a\n * matrix puts its codes, and before it those rows were prose in a description.\n * The match is textual and therefore generous by design. It answers \"did\n * anybody write this case down\", not \"is this scenario correct\", and the\n * failure it is built to catch is the code nobody mentioned at all. Warn, like\n * its sibling: a service may legitimately declare a code its scenarios describe\n * in words, and an error would teach authors to paste numbers into prose.\n *\n * Operations no requirement governs are skipped: `api.ungoverned` already\n * names those, and reporting each of their codes as well is one defect\n * counted twice.\n */\nexport function responseGovernanceFindings(\n  service: string,\n  ops: Operation[],\n  livingReqs: Requirement[],\n): Finding[] {\n  const ungoverned: string[] = [];\n  for (const op of ops) {\n    if (op.failureCodes.length === 0) continue;\n    const governing = livingReqs.filter((r) => r.kind !== \"REMOVED\" && r.operations.includes(op.id));\n    if (governing.length === 0) continue;\n    const body = governing.flatMap((r) => r.scenarios.flatMap((s) => s.lines)).join(\"\\n\");\n    const missing = op.failureCodes.filter((code) => !new RegExp(`(?<!\\\\d)${code}(?!\\\\d)`).test(body));\n    if (missing.length > 0) ungoverned.push(`${op.id}: ${missing.join(\", \")}`);\n  }\n  if (ungoverned.length === 0) return [];\n  return [\n    {\n      severity: \"warn\",\n      code: \"api.response-ungoverned\",\n      subject: service,\n      message: `${service}: ${ungoverned.length} operation(s) declare a failure response no scenario reaches — write the refusal as a scenario, or as a row in one`,\n      details: ungoverned,\n    },\n  ];\n}\n\nexport function coverageFinding(label: string, reqs: Requirement[]): Finding {\n  const missing = requirementsMissingScenarios(reqs);\n  if (missing.length === 0) {\n    return {\n      severity: \"ok\",\n      code: \"requirements.covered\",\n      message: `${label} covered (${reqs.length} requirement${reqs.length === 1 ? \"\" : \"s\"}, all with scenarios)`,\n    };\n  }\n  return {\n    severity: \"error\",\n    code: \"requirements.missing-scenarios\",\n    message: `${label}: ${missing.length} requirement(s) without a scenario`,\n    details: missing.map((r) => r.name),\n    text: { detailPrefix: \"- \" },\n  };\n}\n"]}

package/dist/commands/validate/checks/sources.js

@@ -0,0 +1,76 @@
+import { existsSync } from "node:fs";
+import {} from "../../../core/kernel/ids/service.js";
+import { SPEC_AXES } from "../../../core/repo/paths.js";
+import { locateServicePaths } from "../../../core/repo/service-target.js";
+import { listField, readFrontmatter } from "../../../core/document/frontmatter.js";
+import {} from "../../../core/vocabulary/report.js";
+import { missingSources, patternSources, unsafeSources } from "../../../core/provenance/sources.js";
+import { emptySourcesMessage, expandSourceFiles } from "../../../core/provenance/stamp.js";
+import { UNVERIFIABLE } from "./vocabulary.js";
+/**
+ * The two things a `sources` list can be that `serviceProvenance` cannot say.
+ *
+ * `sources.unverifiable-from-here` — the spec names sources and loam is NOT in
+ * that service's repository, so every sources check (existence, digest,
+ * staleness) is skipped. serviceProvenance returns an empty list in that case
+ * and the silence read as "checked and fine". It used to be counted only under
+ * `--all` and printed as one rollup line, which meant `validate --service X`
+ * run from the docs repo — the single most common way anyone looks at one
+ * service — reported nothing at all about its own blind spot. Severity `ok`,
+ * deliberately: nothing is WRONG with the docs, the check simply cannot run
+ * here, and grading it a warning would make a fully documented fleet
+ * permanently yellow and `--strict` permanently red in the docs repo's CI.
+ *
+ * `sources.empty` — the paths exist, and expand to no files at all: an empty
+ * directory, or a tree the repository itself ignores. A digest over nothing
+ * never changes, so the stamp would read as current forever. `loam vouch`
+ * already refuses to stamp it; until now `validate` said nothing, so an author
+ * got a green run followed by a refusal, two commands contradicting each other
+ * about one document. The sentence comes from `emptySourcesMessage`, the same
+ * definition vouch refuses with, under the label vouch uses.
+ */
+export async function sourceScopeFindings(docsDir, service, repoDir, fleet) {
+    const paths = await locateServicePaths(docsDir, service, fleet);
+    const out = [];
+    // The axis pair is SPEC_AXES', not this function's: `serviceProvenance` grades
+    // the same two files from the same list, and a scope check that walked a
+    // shorter list than the grading would go quiet on the axis it forgot.
+    for (const { path, file } of SPEC_AXES.map((axis) => ({ path: paths[axis.key], file: axis.file }))) {
+        if (!existsSync(path))
+            continue;
+        const sources = listField(await readFrontmatter(path), "sources");
+        if (sources.length === 0)
+            continue;
+        // vouch's own labelling: a bare service id for spec.md, qualified for the
+        // arch axis. The refusal and the finding must be the same sentence.
+        const label = file === "spec.md" ? service : `${service}: ${file}`;
+        if (repoDir === undefined) {
+            out.push({
+                severity: "ok",
+                code: UNVERIFIABLE,
+                subject: service,
+                message: `${label}: ${sources.length} source(s) declared, but this is not ${service}'s repository — nothing here can resolve them. Run \`loam validate --service ${service}\` from inside it.`,
+            });
+            continue;
+        }
+        // Every other shape of broken list is serviceProvenance's to grade, and
+        // grading them twice would send an author fixing one thing from two
+        // findings. "Covers no files" is only meaningful once the paths are real.
+        if (patternSources(sources).length > 0 ||
+            unsafeSources(repoDir, sources).length > 0 ||
+            missingSources(repoDir, sources).length > 0) {
+            continue;
+        }
+        const expansion = await expandSourceFiles(repoDir, sources, label);
+        if (expansion.files.length > 0)
+            continue;
+        out.push({
+            severity: "warn",
+            code: "sources.empty",
+            subject: service,
+            message: expansion.empty ?? emptySourcesMessage(label, sources),
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=sources.js.map

package/dist/commands/validate/checks/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../../../../src/commands/validate/checks/sources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAwB,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAExD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACnF,OAAO,EAAgB,MAAM,oCAAoC,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACpG,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAC3F,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAgB,EAChB,OAAwB,EACxB,OAA2B,EAC3B,KAAoB;IAEpB,MAAM,KAAK,GAAG,MAAM,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IAChE,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,+EAA+E;IAC/E,yEAAyE;IACzE,sEAAsE;IACtE,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QACnG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAChC,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,eAAe,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC;QAClE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACnC,0EAA0E;QAC1E,oEAAoE;QACpE,MAAM,KAAK,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,IAAI,EAAE,CAAC;QACnE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,GAAG,CAAC,IAAI,CAAC;gBACP,QAAQ,EAAE,IAAI;gBACd,IAAI,EAAE,YAAY;gBAClB,OAAO,EAAE,OAAO;gBAChB,OAAO,EAAE,GAAG,KAAK,KAAK,OAAO,CAAC,MAAM,wCAAwC,OAAO,gFAAgF,OAAO,oBAAoB;aAC/L,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,wEAAwE;QACxE,oEAAoE;QACpE,0EAA0E;QAC1E,IACE,cAAc,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC;YAClC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC;YAC1C,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAC3C,CAAC;YACD,SAAS;QACX,CAAC;QACD,MAAM,SAAS,GAAG,MAAM,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;QACnE,IAAI,SAAS,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,SAAS;QACzC,GAAG,CAAC,IAAI,CAAC;YACP,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,OAAO;YAChB,OAAO,EAAE,SAAS,CAAC,KAAK,IAAI,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC;SAChE,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["import { existsSync } from \"node:fs\";\nimport { type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { SPEC_AXES } from \"../../../core/repo/paths.js\";\nimport type { FleetContext } from \"../../../core/fleet-context.js\";\nimport { locateServicePaths } from \"../../../core/repo/service-target.js\";\nimport { listField, readFrontmatter } from \"../../../core/document/frontmatter.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport { missingSources, patternSources, unsafeSources } from \"../../../core/provenance/sources.js\";\nimport { emptySourcesMessage, expandSourceFiles } from \"../../../core/provenance/stamp.js\";\nimport { UNVERIFIABLE } from \"./vocabulary.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\n\n/**\n * The two things a `sources` list can be that `serviceProvenance` cannot say.\n *\n * `sources.unverifiable-from-here` — the spec names sources and loam is NOT in\n * that service's repository, so every sources check (existence, digest,\n * staleness) is skipped. serviceProvenance returns an empty list in that case\n * and the silence read as \"checked and fine\". It used to be counted only under\n * `--all` and printed as one rollup line, which meant `validate --service X`\n * run from the docs repo — the single most common way anyone looks at one\n * service — reported nothing at all about its own blind spot. Severity `ok`,\n * deliberately: nothing is WRONG with the docs, the check simply cannot run\n * here, and grading it a warning would make a fully documented fleet\n * permanently yellow and `--strict` permanently red in the docs repo's CI.\n *\n * `sources.empty` — the paths exist, and expand to no files at all: an empty\n * directory, or a tree the repository itself ignores. A digest over nothing\n * never changes, so the stamp would read as current forever. `loam vouch`\n * already refuses to stamp it; until now `validate` said nothing, so an author\n * got a green run followed by a refusal, two commands contradicting each other\n * about one document. The sentence comes from `emptySourcesMessage`, the same\n * definition vouch refuses with, under the label vouch uses.\n */\nexport async function sourceScopeFindings(\n  docsDir: DocsDir,\n  service: PathableService,\n  repoDir: string | undefined,\n  fleet?: FleetContext,\n): Promise<Finding[]> {\n  const paths = await locateServicePaths(docsDir, service, fleet);\n  const out: Finding[] = [];\n  // The axis pair is SPEC_AXES', not this function's: `serviceProvenance` grades\n  // the same two files from the same list, and a scope check that walked a\n  // shorter list than the grading would go quiet on the axis it forgot.\n  for (const { path, file } of SPEC_AXES.map((axis) => ({ path: paths[axis.key], file: axis.file }))) {\n    if (!existsSync(path)) continue;\n    const sources = listField(await readFrontmatter(path), \"sources\");\n    if (sources.length === 0) continue;\n    // vouch's own labelling: a bare service id for spec.md, qualified for the\n    // arch axis. The refusal and the finding must be the same sentence.\n    const label = file === \"spec.md\" ? service : `${service}: ${file}`;\n    if (repoDir === undefined) {\n      out.push({\n        severity: \"ok\",\n        code: UNVERIFIABLE,\n        subject: service,\n        message: `${label}: ${sources.length} source(s) declared, but this is not ${service}'s repository — nothing here can resolve them. Run \\`loam validate --service ${service}\\` from inside it.`,\n      });\n      continue;\n    }\n    // Every other shape of broken list is serviceProvenance's to grade, and\n    // grading them twice would send an author fixing one thing from two\n    // findings. \"Covers no files\" is only meaningful once the paths are real.\n    if (\n      patternSources(sources).length > 0 ||\n      unsafeSources(repoDir, sources).length > 0 ||\n      missingSources(repoDir, sources).length > 0\n    ) {\n      continue;\n    }\n    const expansion = await expandSourceFiles(repoDir, sources, label);\n    if (expansion.files.length > 0) continue;\n    out.push({\n      severity: \"warn\",\n      code: \"sources.empty\",\n      subject: service,\n      message: expansion.empty ?? emptySourcesMessage(label, sources),\n    });\n  }\n  return out;\n}\n"]}

package/dist/commands/validate/checks/vocabulary.js

@@ -0,0 +1,31 @@
+/**
+ * The handful of facts every validate check speaks, and none of them owns.
+ *
+ * A leaf module rather than a paragraph beside its first caller, because the
+ * checks are spread across packages and each of these is read from more than
+ * one of them: the dispatcher's rollup and the service target's sources check
+ * both name one finding code, and several targets render parser diagnostics
+ * the same way. ACTOR_KINDS and EXTERNAL_TAG lived here too, until they
+ * reached a third copy (`core/gate/partners.ts`, `core/verify/checklist.ts`);
+ * their shared spelling is now `core/vocabulary/maturity.ts`, beside the
+ * landscape evidence that asks the same questions.
+ */
+import {} from "../../../core/c4/likec4.js";
+/** The one code the rollup line counts; spelled once so the two cannot drift. */
+export const UNVERIFIABLE = "sources.unverifiable-from-here";
+/**
+ * One parser diagnostic as a finding's evidence line: `L12:` when the parser
+ * knew a line, because that lets a reader open the file at the fault instead of
+ * searching for it.
+ *
+ * Three other modules hand-roll the same ternary (`commands/show.ts`,
+ * `commands/delta.ts`, `core/c4/splice/landscape-merge.ts`). All four belong
+ * beside `LikeC4Error` in `core/c4/likec4.ts`. That used to be blocked by the
+ * file limit — nine lines of headroom — and is not any more: moving the resolver
+ * out to `core/c4/resolve/service.ts` left the loader around 100 lines under.
+ * The consolidation is now unblocked and simply owed.
+ */
+export function errorText(e) {
+    return typeof e.line === "number" ? `L${e.line}: ${e.message}` : e.message;
+}
+//# sourceMappingURL=vocabulary.js.map

package/dist/commands/validate/checks/vocabulary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary.js","sourceRoot":"","sources":["../../../../src/commands/validate/checks/vocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAoB,MAAM,4BAA4B,CAAC;AAE9D,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAG,gCAAgC,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,CAAc;IACtC,OAAO,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;AAC7E,CAAC","sourcesContent":["/**\n * The handful of facts every validate check speaks, and none of them owns.\n *\n * A leaf module rather than a paragraph beside its first caller, because the\n * checks are spread across packages and each of these is read from more than\n * one of them: the dispatcher's rollup and the service target's sources check\n * both name one finding code, and several targets render parser diagnostics\n * the same way. ACTOR_KINDS and EXTERNAL_TAG lived here too, until they\n * reached a third copy (`core/gate/partners.ts`, `core/verify/checklist.ts`);\n * their shared spelling is now `core/vocabulary/maturity.ts`, beside the\n * landscape evidence that asks the same questions.\n */\nimport { type LikeC4Error } from \"../../../core/c4/likec4.js\";\n\n/** The one code the rollup line counts; spelled once so the two cannot drift. */\nexport const UNVERIFIABLE = \"sources.unverifiable-from-here\";\n\n/**\n * One parser diagnostic as a finding's evidence line: `L12:` when the parser\n * knew a line, because that lets a reader open the file at the fault instead of\n * searching for it.\n *\n * Three other modules hand-roll the same ternary (`commands/show.ts`,\n * `commands/delta.ts`, `core/c4/splice/landscape-merge.ts`). All four belong\n * beside `LikeC4Error` in `core/c4/likec4.ts`. That used to be blocked by the\n * file limit — nine lines of headroom — and is not any more: moving the resolver\n * out to `core/c4/resolve/service.ts` left the loader around 100 lines under.\n * The consolidation is now unblocked and simply owed.\n */\nexport function errorText(e: LikeC4Error): string {\n  return typeof e.line === \"number\" ? `L${e.line}: ${e.message}` : e.message;\n}\n"]}