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

package/dist/commands/validate/fleet/usecases/steps.js

@@ -0,0 +1,197 @@
+/**
+ * The three grades one hop of a use case can earn: `usecase.step-unbacked`,
+ * `usecase.step-contested` and `usecase.step-unlinked`.
+ *
+ * The attribution itself is `core/c4/resolve/steps.ts`'s `attributeStep` — which declared
+ * relationship backs a hop, oriented on `isBackward` and decided by the
+ * DISTINCT-op count — and none of that reasoning is repeated here. This module
+ * owns three things: which verdict earns which code, the three guards that keep
+ * the warn honest, and the sentences.
+ *
+ * WHY `step-unbacked` IS THE CHECK THAT EARNS THE FEATURE. A hop between two
+ * elements that both exist, with no relationship between them anywhere in the
+ * model, is ZERO LikeC4 errors: a `dynamic view` is allowed to show a call the
+ * model never declared, so the diagram renders, the project parses, and every
+ * other check in loam stays green. The flow reads as fine in every tool the
+ * fleet has. If loam does not convict it, nothing does — which is why it is an
+ * error rather than an advisory.
+ *
+ * ONE BREACH, ONE FINDING, and here that is structural rather than remembered.
+ * `contested` and `attributed` are disjoint verdicts, so deriving
+ * `step-unlinked` from the `attributed` arm — never from the candidate
+ * relationships — is what makes a contested step report once. A grader that
+ * walked `rels` looking for a missing `op` would convict the same hop twice:
+ * once for the disagreement, and once for whichever candidate happened to carry
+ * no operation at all.
+ */
+import { attributeStep } from "../../../../core/c4/resolve/steps.js";
+import { ACTOR_KINDS } from "../../../../core/vocabulary/maturity.js";
+import { stepPlace } from "../../../../core/usecases/place.js";
+import { viewPlace } from "./place.js";
+/** `…checkout.likec4 — dynamic view 'uc_checkout' step 2 'authorizes the payment'`. */
+function placeOf(hop) {
+    return `${viewPlace(hop.view)} ${stepPlace(hop.step)}`;
+}
+/**
+ * A hop nothing in the model backs.
+ *
+ * Two fixes, because there are genuinely two mistakes that land here and the
+ * author is the only one who can say which they made: the edge really is
+ * missing, or the hop is a reply written the long way round. The second is
+ * offered as the OTHER spelling of what they already typed — suggesting the
+ * spelling they used would be a hint that restates the defect — and the sentence
+ * says which pair that spelling looks the hop up under, because `<-` attributes
+ * a reply to the CALL it answers rather than to the direction the message
+ * travels (`callPair` in core/c4/resolve/steps.ts holds the measurement).
+ */
+function unbackedFinding(hop, attribution) {
+    const other = hop.step.isBackward
+        ? { spelling: `${hop.step.source} -> ${hop.step.target}`, when: "is not a return step" }
+        : { spelling: `${hop.step.target} <- ${hop.step.source}`, when: "is a return step" };
+    return {
+        severity: "error",
+        code: "usecase.step-unbacked",
+        subject: hop.view.id,
+        message: `${placeOf(hop)}: nothing in the model declares ${attribution.from} -> ${attribution.to}, so this hop is ` +
+            "backed by no relationship — and LikeC4 reports no error for it, so the view still renders and the " +
+            "project still parses. Draw the edge in `model { }` (with `metadata { op '<operationId>' }` where it is " +
+            `a call), or, if this hop ${other.when}, write it as \`${other.spelling}\` — a reply is attributed to the ` +
+            `call it answers, so that spelling looks the hop up under ${attribution.to} -> ${attribution.from} instead.`,
+    };
+}
+/** `web -> orders.api "Calls createOrder" (op: createOrder)`, or `(no op)` where the edge declares none. */
+function candidateLine(rel) {
+    const op = rel.op === undefined ? "no op" : `op: ${rel.op}`;
+    return `${rel.source} -> ${rel.target} "${rel.title ?? ""}" (${op})`;
+}
+/**
+ * A hop whose candidates disagree about the operation.
+ *
+ * WARN, not error, because the model is complete — every candidate is a
+ * relationship somebody drew on purpose — and the honest answer is sometimes
+ * "two paths, one flow". What loam refuses to do is pick: a guessed operation is
+ * indistinguishable from a right one in every rollup built over the use case,
+ * and it stays wrong invisibly.
+ *
+ * `details` carries every candidate rather than the distinct ops, because the
+ * repair is made on a RELATIONSHIP: the author has to find the edge that names
+ * the wrong operation, and a list of operation names does not say which edge
+ * that is. An absent `metadata { op }` prints as `no op` and is a candidate like
+ * any other — it is exactly as much of a disagreement as a second name.
+ */
+function contestedFinding(hop, attribution) {
+    return {
+        severity: "warn",
+        code: "usecase.step-contested",
+        subject: hop.view.id,
+        message: `${placeOf(hop)}: ${attribution.rels.length} relationships back ${attribution.from} -> ` +
+            `${attribution.to} and they name ${attribution.ops.length} different operations, so nothing can say ` +
+            "which one this hop exercises. loam names the candidates instead of picking one — a guessed operation " +
+            "reads exactly like a right one in every rollup built over this flow. Give the candidates one operation, " +
+            "or draw the hop between the elements that name exactly one.",
+        details: attribution.rels.map(candidateLine),
+    };
+}
+/**
+ * The service this hop calls, when the hop is a `step-unlinked` candidate at
+ * all — `null` when any of the three guards refuses. ALL THREE are mechanical,
+ * and each closes a whole class of warnings that would otherwise be simply
+ * wrong. The count is stated because a reader auditing this function is meant to
+ * find three bullets and three `return null`s below and conclude that none of
+ * them is surplus: the one a miscount invites deleting is the last, and deleting
+ * it puts the warning back on the first hop of almost every flow.
+ *
+ *  - A `publishes` or `consumes` on ANY candidate means the hop does reach a
+ *    declared API — an AsyncAPI one. The event spine already grades it
+ *    (`spine.message-undefined` and its family), and asking for an `op` as well
+ *    would be loam demanding an HTTP operationId for a Kafka message. Read
+ *    across every candidate rather than the first, because on the service tier
+ *    the candidates are one call drawn as containers.
+ *  - The target must resolve to a real `services/<id>/`. Without it every hop
+ *    into an `#external` system, an actor, a database, a cache or a queue warns
+ *    — none of which owns an `openapi.yaml`, so none of them CAN carry the
+ *    operationId the message would be asking for. Through the shared resolver,
+ *    so "the provider" here and "the provider" in the spine check cannot
+ *    disagree about which element stands for which directory.
+ *  - The CALLER must not be an actor. A person is not a caller: `customer ->
+ *    checkoutWeb 'opens the basket'` is somebody using the app, and the app owes
+ *    no operationId for a click. The guard above does not cover this, because it
+ *    reads the TARGET — and the target here is one of ours, so without this the
+ *    warning fired on the FIRST HOP OF ALMOST EVERY FLOW, which is where a
+ *    sequence diagram puts its actor. Measured on the published example fleet
+ *    before it was added. This is the same exemption `fleet/census.ts`,
+ *    `arch-coverage.ts`, `core/gate/partners.ts` and `core/verify/checklist.ts`
+ *    each already apply, through the same `ACTOR_KINDS` — a person was never a
+ *    participant in any of loam's other censuses either.
+ *
+ * The op test reads the ATTRIBUTION rather than the relationships: an
+ * `attributed` verdict with no `op` means every candidate agreed the hop names
+ * no operation, which is the state this warn is about. Candidates that disagree
+ * never reach here at all — that is the suppression, and it is why it cannot be
+ * forgotten.
+ */
+function unlinkedProvider(attribution, grading) {
+    if (attribution.op !== undefined)
+        return null;
+    if (attribution.rels.some((rel) => rel.publishes !== undefined || rel.consumes !== undefined))
+        return null;
+    if (isActor(attribution.from, grading.model.elements))
+        return null;
+    const provider = grading.resolve(attribution.to);
+    return grading.services.has(provider) ? provider : null;
+}
+/**
+ * Is this endpoint a person rather than a system?
+ *
+ * Exact id, not the ancestor walk the service resolver does: an actor is a
+ * top-level element in every landscape loam has seen, and a nested one would be
+ * a person inside a system, which is not a shape the model has. An endpoint that
+ * names no element cannot occur — a step naming one is a LikeC4 reference error,
+ * so the document never reaches a check.
+ */
+function isActor(id, elements) {
+    const element = elements.find((candidate) => candidate.id === id);
+    return element !== undefined && ACTOR_KINDS.has(element.kind.toLowerCase());
+}
+/**
+ * A hop backed by the model and joined to no contract.
+ *
+ * The mirror of `spine.op-link-missing` at flow altitude: the use case reaches
+ * the fleet map and stops there, so nothing can say which operation of the
+ * provider's contract the step exercises — and the whole point of grading a use
+ * case is that the flow joins through to the API it drives.
+ */
+function unlinkedFinding(hop, attribution, provider) {
+    const backing = attribution.rels.length === 1 ? "one relationship" : `${attribution.rels.length} relationships`;
+    return {
+        severity: "warn",
+        code: "usecase.step-unlinked",
+        subject: hop.view.id,
+        message: `${placeOf(hop)}: ${attribution.from} -> ${attribution.to} is backed by ${backing} carrying no ` +
+            "`metadata { op }` and no `publishes`/`consumes`, so this hop names no operation of " +
+            `${provider}'s contract — the use case reaches the fleet map and stops there. Add ` +
+            "`metadata { op '<operationId>' }` to the edge in `model { }`, or `metadata { publishes '<message>' }` / " +
+            "`consumes` where the hop is an event.",
+    };
+}
+/**
+ * The findings one hop earns — at most one, whatever is wrong with it.
+ *
+ * A `switch` over the closed verdict union with every arm returning, so a fourth
+ * verdict added upstream is a compile error here rather than a hop that silently
+ * stops being graded.
+ */
+export function stepFindings(hop, grading) {
+    const attribution = attributeStep(hop.step, grading.model);
+    switch (attribution.verdict) {
+        case "unbacked":
+            return [unbackedFinding(hop, attribution)];
+        case "contested":
+            return [contestedFinding(hop, attribution)];
+        case "attributed": {
+            const provider = unlinkedProvider(attribution, grading);
+            return provider === null ? [] : [unlinkedFinding(hop, attribution, provider)];
+        }
+    }
+}
+//# sourceMappingURL=steps.js.map

package/dist/commands/validate/fleet/usecases/steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/usecases/steps.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The three grades one hop of a use case can earn: `usecase.step-unbacked`,\n * `usecase.step-contested` and `usecase.step-unlinked`.\n *\n * The attribution itself is `core/c4/resolve/steps.ts`'s `attributeStep` — which declared\n * relationship backs a hop, oriented on `isBackward` and decided by the\n * DISTINCT-op count — and none of that reasoning is repeated here. This module\n * owns three things: which verdict earns which code, the three guards that keep\n * the warn honest, and the sentences.\n *\n * WHY `step-unbacked` IS THE CHECK THAT EARNS THE FEATURE. A hop between two\n * elements that both exist, with no relationship between them anywhere in the\n * model, is ZERO LikeC4 errors: a `dynamic view` is allowed to show a call the\n * model never declared, so the diagram renders, the project parses, and every\n * other check in loam stays green. The flow reads as fine in every tool the\n * fleet has. If loam does not convict it, nothing does — which is why it is an\n * error rather than an advisory.\n *\n * ONE BREACH, ONE FINDING, and here that is structural rather than remembered.\n * `contested` and `attributed` are disjoint verdicts, so deriving\n * `step-unlinked` from the `attributed` arm — never from the candidate\n * relationships — is what makes a contested step report once. A grader that\n * walked `rels` looking for a missing `op` would convict the same hop twice:\n * once for the disagreement, and once for whichever candidate happened to carry\n * no operation at all.\n */\nimport { attributeStep, type StepAttribution, type StepScope } from \"../../../../core/c4/resolve/steps.js\";\nimport type { Elem, Rel } from \"../../../../core/c4/likec4.js\";\nimport type { ParsedStep, ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport { ACTOR_KINDS } from \"../../../../core/vocabulary/maturity.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { stepPlace } from \"../../../../core/usecases/place.js\";\nimport { viewPlace } from \"./place.js\";\n\n/** One hop being graded and the view it belongs to — never passed apart. */\nexport interface GradedStep {\n  view: ParsedView;\n  step: ParsedStep;\n}\n\n/**\n * What a hop is graded against, built ONCE per run.\n *\n * `services` and `model.known` are the same set by construction (`./usecases.ts`\n * builds both from one value), which is what stops \"which service is this\n * element\" being answered one way by the attribution and another by the provider\n * guard below. `resolve` is injected for the same reason `fleetShapeFindings`\n * takes it: the fleet target already holds the shared element→service resolver,\n * and a second one built here could not disagree today but would be a second\n * place to change.\n */\nexport interface StepGrading {\n  model: StepScope;\n  /** The `services/<id>/` directories that exist. */\n  services: ReadonlySet<string>;\n  /** The shared element→service resolver every other edge join uses. */\n  resolve: (id: string) => string;\n}\n\ntype Unbacked = Extract<StepAttribution, { verdict: \"unbacked\" }>;\ntype Contested = Extract<StepAttribution, { verdict: \"contested\" }>;\ntype Attributed = Extract<StepAttribution, { verdict: \"attributed\" }>;\n\n/** `…checkout.likec4 — dynamic view 'uc_checkout' step 2 'authorizes the payment'`. */\nfunction placeOf(hop: GradedStep): string {\n  return `${viewPlace(hop.view)} ${stepPlace(hop.step)}`;\n}\n\n/**\n * A hop nothing in the model backs.\n *\n * Two fixes, because there are genuinely two mistakes that land here and the\n * author is the only one who can say which they made: the edge really is\n * missing, or the hop is a reply written the long way round. The second is\n * offered as the OTHER spelling of what they already typed — suggesting the\n * spelling they used would be a hint that restates the defect — and the sentence\n * says which pair that spelling looks the hop up under, because `<-` attributes\n * a reply to the CALL it answers rather than to the direction the message\n * travels (`callPair` in core/c4/resolve/steps.ts holds the measurement).\n */\nfunction unbackedFinding(hop: GradedStep, attribution: Unbacked): Finding {\n  const other = hop.step.isBackward\n    ? { spelling: `${hop.step.source} -> ${hop.step.target}`, when: \"is not a return step\" }\n    : { spelling: `${hop.step.target} <- ${hop.step.source}`, when: \"is a return step\" };\n  return {\n    severity: \"error\",\n    code: \"usecase.step-unbacked\",\n    subject: hop.view.id,\n    message:\n      `${placeOf(hop)}: nothing in the model declares ${attribution.from} -> ${attribution.to}, so this hop is ` +\n      \"backed by no relationship — and LikeC4 reports no error for it, so the view still renders and the \" +\n      \"project still parses. Draw the edge in `model { }` (with `metadata { op '<operationId>' }` where it is \" +\n      `a call), or, if this hop ${other.when}, write it as \\`${other.spelling}\\` — a reply is attributed to the ` +\n      `call it answers, so that spelling looks the hop up under ${attribution.to} -> ${attribution.from} instead.`,\n  };\n}\n\n/** `web -> orders.api \"Calls createOrder\" (op: createOrder)`, or `(no op)` where the edge declares none. */\nfunction candidateLine(rel: Rel): string {\n  const op = rel.op === undefined ? \"no op\" : `op: ${rel.op}`;\n  return `${rel.source} -> ${rel.target} \"${rel.title ?? \"\"}\" (${op})`;\n}\n\n/**\n * A hop whose candidates disagree about the operation.\n *\n * WARN, not error, because the model is complete — every candidate is a\n * relationship somebody drew on purpose — and the honest answer is sometimes\n * \"two paths, one flow\". What loam refuses to do is pick: a guessed operation is\n * indistinguishable from a right one in every rollup built over the use case,\n * and it stays wrong invisibly.\n *\n * `details` carries every candidate rather than the distinct ops, because the\n * repair is made on a RELATIONSHIP: the author has to find the edge that names\n * the wrong operation, and a list of operation names does not say which edge\n * that is. An absent `metadata { op }` prints as `no op` and is a candidate like\n * any other — it is exactly as much of a disagreement as a second name.\n */\nfunction contestedFinding(hop: GradedStep, attribution: Contested): Finding {\n  return {\n    severity: \"warn\",\n    code: \"usecase.step-contested\",\n    subject: hop.view.id,\n    message:\n      `${placeOf(hop)}: ${attribution.rels.length} relationships back ${attribution.from} -> ` +\n      `${attribution.to} and they name ${attribution.ops.length} different operations, so nothing can say ` +\n      \"which one this hop exercises. loam names the candidates instead of picking one — a guessed operation \" +\n      \"reads exactly like a right one in every rollup built over this flow. Give the candidates one operation, \" +\n      \"or draw the hop between the elements that name exactly one.\",\n    details: attribution.rels.map(candidateLine),\n  };\n}\n\n/**\n * The service this hop calls, when the hop is a `step-unlinked` candidate at\n * all — `null` when any of the three guards refuses. ALL THREE are mechanical,\n * and each closes a whole class of warnings that would otherwise be simply\n * wrong. The count is stated because a reader auditing this function is meant to\n * find three bullets and three `return null`s below and conclude that none of\n * them is surplus: the one a miscount invites deleting is the last, and deleting\n * it puts the warning back on the first hop of almost every flow.\n *\n *  - A `publishes` or `consumes` on ANY candidate means the hop does reach a\n *    declared API — an AsyncAPI one. The event spine already grades it\n *    (`spine.message-undefined` and its family), and asking for an `op` as well\n *    would be loam demanding an HTTP operationId for a Kafka message. Read\n *    across every candidate rather than the first, because on the service tier\n *    the candidates are one call drawn as containers.\n *  - The target must resolve to a real `services/<id>/`. Without it every hop\n *    into an `#external` system, an actor, a database, a cache or a queue warns\n *    — none of which owns an `openapi.yaml`, so none of them CAN carry the\n *    operationId the message would be asking for. Through the shared resolver,\n *    so \"the provider\" here and \"the provider\" in the spine check cannot\n *    disagree about which element stands for which directory.\n *  - The CALLER must not be an actor. A person is not a caller: `customer ->\n *    checkoutWeb 'opens the basket'` is somebody using the app, and the app owes\n *    no operationId for a click. The guard above does not cover this, because it\n *    reads the TARGET — and the target here is one of ours, so without this the\n *    warning fired on the FIRST HOP OF ALMOST EVERY FLOW, which is where a\n *    sequence diagram puts its actor. Measured on the published example fleet\n *    before it was added. This is the same exemption `fleet/census.ts`,\n *    `arch-coverage.ts`, `core/gate/partners.ts` and `core/verify/checklist.ts`\n *    each already apply, through the same `ACTOR_KINDS` — a person was never a\n *    participant in any of loam's other censuses either.\n *\n * The op test reads the ATTRIBUTION rather than the relationships: an\n * `attributed` verdict with no `op` means every candidate agreed the hop names\n * no operation, which is the state this warn is about. Candidates that disagree\n * never reach here at all — that is the suppression, and it is why it cannot be\n * forgotten.\n */\nfunction unlinkedProvider(attribution: Attributed, grading: StepGrading): string | null {\n  if (attribution.op !== undefined) return null;\n  if (attribution.rels.some((rel) => rel.publishes !== undefined || rel.consumes !== undefined)) return null;\n  if (isActor(attribution.from, grading.model.elements)) return null;\n  const provider = grading.resolve(attribution.to);\n  return grading.services.has(provider) ? provider : null;\n}\n\n/**\n * Is this endpoint a person rather than a system?\n *\n * Exact id, not the ancestor walk the service resolver does: an actor is a\n * top-level element in every landscape loam has seen, and a nested one would be\n * a person inside a system, which is not a shape the model has. An endpoint that\n * names no element cannot occur — a step naming one is a LikeC4 reference error,\n * so the document never reaches a check.\n */\nfunction isActor(id: string, elements: Elem[]): boolean {\n  const element = elements.find((candidate) => candidate.id === id);\n  return element !== undefined && ACTOR_KINDS.has(element.kind.toLowerCase());\n}\n\n/**\n * A hop backed by the model and joined to no contract.\n *\n * The mirror of `spine.op-link-missing` at flow altitude: the use case reaches\n * the fleet map and stops there, so nothing can say which operation of the\n * provider's contract the step exercises — and the whole point of grading a use\n * case is that the flow joins through to the API it drives.\n */\nfunction unlinkedFinding(hop: GradedStep, attribution: Attributed, provider: string): Finding {\n  const backing =\n    attribution.rels.length === 1 ? \"one relationship\" : `${attribution.rels.length} relationships`;\n  return {\n    severity: \"warn\",\n    code: \"usecase.step-unlinked\",\n    subject: hop.view.id,\n    message:\n      `${placeOf(hop)}: ${attribution.from} -> ${attribution.to} is backed by ${backing} carrying no ` +\n      \"`metadata { op }` and no `publishes`/`consumes`, so this hop names no operation of \" +\n      `${provider}'s contract — the use case reaches the fleet map and stops there. Add ` +\n      \"`metadata { op '<operationId>' }` to the edge in `model { }`, or `metadata { publishes '<message>' }` / \" +\n      \"`consumes` where the hop is an event.\",\n  };\n}\n\n/**\n * The findings one hop earns — at most one, whatever is wrong with it.\n *\n * A `switch` over the closed verdict union with every arm returning, so a fourth\n * verdict added upstream is a compile error here rather than a hop that silently\n * stops being graded.\n */\nexport function stepFindings(hop: GradedStep, grading: StepGrading): Finding[] {\n  const attribution = attributeStep(hop.step, grading.model);\n  switch (attribution.verdict) {\n    case \"unbacked\":\n      return [unbackedFinding(hop, attribution)];\n    case \"contested\":\n      return [contestedFinding(hop, attribution)];\n    case \"attributed\": {\n      const provider = unlinkedProvider(attribution, grading);\n      return provider === null ? [] : [unlinkedFinding(hop, attribution, provider)];\n    }\n  }\n}\n"]}

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

@@ -0,0 +1,99 @@
+/**
+ * The use-case axis of `validate --all`: the `dynamic view`s a fleet declares,
+ * graded as business flows against the model they are drawn over.
+ *
+ * ONLY VIEWS CARRYING A RESERVED TAG ARE GRADED, and that opt-in is what lets
+ * this ship into a fleet that already has diagrams. An untagged `dynamic view`
+ * is somebody's hand-drawn sequence — drawn to explain something to a person,
+ * not to be joined to a model — and grading it would turn every existing docs
+ * repo red on upgrade over documents nobody promised anything about. A `#cap-`
+ * or `#req-` tag is the author saying "this is a use case; hold it to the
+ * model", and nothing else says it: a view with no tags and a view whose tags
+ * are all somebody's own vocabulary are the same thing here.
+ *
+ * THE TAG OPTS A VIEW IN WHETHER OR NOT IT RESOLVES. A `#cap-` slug that names
+ * no declared capability is a broken claim about the vocabulary, not a withdrawn
+ * one, so its steps are still graded — and the step grades read
+ * `architecture/capabilities.yaml` nowhere at all. Coupling them would mean a
+ * fleet that has not adopted the capability axis could never have a use case
+ * checked, which inverts the adoption order the whole axis is built on: draw the
+ * flow first, name the capability when the vocabulary exists.
+ *
+ * Everything here is LINEAR IN STEPS over documents `validate --all` has already
+ * parsed, and nothing in it reads a file or throws — a fleet with no tagged view
+ * produces exactly nothing. Linear in steps is not free per step: `attributeStep`
+ * scans `relationships` once for the exact tier and again for the resolved one,
+ * and `isActor` scans `elements`, so the real shape is O(steps × relationships)
+ * plus O(steps × elements). That is why `StepGrading` is built once below rather
+ * than per hop — the per-hop cost is a scan, so anything rebuilt per hop is paid
+ * against every hop in the fleet.
+ */
+import { compareIds } from "../../../../core/repo/entries.js";
+import { resolveCapabilityTags } from "../../../../core/capabilities/usecase-join.js";
+import { isUseCase } from "../../../../core/usecases/fleet.js";
+import { capabilityTagFindings } from "./capability-tag.js";
+import { requirementTagFindings } from "./requirement-tag.js";
+import { stepFindings } from "./steps.js";
+import { viewFile } from "../../../../core/usecases/place.js";
+/**
+ * The views that opted in, in a stable order.
+ *
+ * The opt-in itself is `isUseCase` in `core/usecases/fleet.ts` and is not
+ * restated here. It used to be — the same `startsWith` pair, spelled a second
+ * time — and the two spellings drifted: this one took either reserved prefix
+ * while the reader-side one took `#cap-` alone, so `validate` graded a
+ * `#req-`-only flow that `loam diff`, `delta`, `status`, the packs and `list
+ * capabilities` could not see. What is left here is the ORDER, which is this
+ * package's own concern.
+ *
+ * Sorted by (file, view id) rather than reported in LikeC4's own record order:
+ * nothing in loam has measured that the parse preserves declaration order, so a
+ * report whose row order depends on that would reorder under a dependency bump
+ * — the diff-stability rule `core/capabilities/rollup.ts` states for its rows,
+ * applied to findings.
+ */
+function gradedViews(views) {
+    return views
+        .filter(isUseCase)
+        .sort((a, b) => compareIds(viewFile(a), viewFile(b)) || compareIds(a.id, b.id));
+}
+/**
+ * Every use-case finding a fleet's declared views earn.
+ *
+ * The grading record is built once and shared across every step of every view:
+ * `attributeStep` caches its element→service resolver on the identity of the
+ * elements array and the fleet set, so handing it one `StepScope` for the whole
+ * run is what keeps the fleet's use cases from rebuilding that id map per hop.
+ */
+export function useCaseFindings(scope) {
+    const grading = {
+        // `known` and `services` come from ONE value, so the fleet set the
+        // attribution resolves against and the fleet set the provider guard tests
+        // cannot drift apart into two answers about the same element.
+        model: { elements: scope.elements, relationships: scope.relationships, known: scope.services },
+        services: scope.services,
+        resolve: scope.resolve,
+    };
+    const findings = [];
+    for (const view of gradedViews(scope.views)) {
+        // ONE resolution of this view's capability tags, shared by both grades. The
+        // `#req-` tag is scoped by exactly the capabilities the `#cap-` tags resolve
+        // to, so resolving twice would be two chances to disagree about which
+        // document a `Requirement-ID` is unique inside.
+        //
+        // THE LADDER IS THE `null`, NOT AN EMPTY LIST, and the distinction is a
+        // wrong answer away: a suspended vocabulary handed on as `[]` reads to the
+        // requirement grade as "this view resolves no capability", which is its
+        // `unscoped` ERROR — so every `#req-` tag in a fleet that has not adopted
+        // the capability axis would be convicted for the axis not existing.
+        if (scope.capabilities !== null) {
+            const claims = resolveCapabilityTags(view.tags, scope.capabilities);
+            findings.push(...capabilityTagFindings(view, claims));
+            findings.push(...requirementTagFindings(view, claims, scope.requirementsOf));
+        }
+        for (const step of view.steps)
+            findings.push(...stepFindings({ view, step }, grading));
+    }
+    return findings;
+}
+//# sourceMappingURL=usecases.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usecases.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/usecases/usecases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,+CAA+C,CAAC;AACtF,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAI/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAoB,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AA8C9D;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,WAAW,CAAC,KAA4B;IAC/C,OAAO,KAAK;SACT,MAAM,CAAC,SAAS,CAAC;SACjB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,KAAmB;IACjD,MAAM,OAAO,GAAgB;QAC3B,mEAAmE;QACnE,0EAA0E;QAC1E,8DAA8D;QAC9D,KAAK,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE;QAC9F,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;KACvB,CAAC;IACF,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,4EAA4E;QAC5E,6EAA6E;QAC7E,sEAAsE;QACtE,gDAAgD;QAChD,EAAE;QACF,wEAAwE;QACxE,2EAA2E;QAC3E,wEAAwE;QACxE,0EAA0E;QAC1E,oEAAoE;QACpE,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;YACpE,QAAQ,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;YACtD,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;QAC/E,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * The use-case axis of `validate --all`: the `dynamic view`s a fleet declares,\n * graded as business flows against the model they are drawn over.\n *\n * ONLY VIEWS CARRYING A RESERVED TAG ARE GRADED, and that opt-in is what lets\n * this ship into a fleet that already has diagrams. An untagged `dynamic view`\n * is somebody's hand-drawn sequence — drawn to explain something to a person,\n * not to be joined to a model — and grading it would turn every existing docs\n * repo red on upgrade over documents nobody promised anything about. A `#cap-`\n * or `#req-` tag is the author saying \"this is a use case; hold it to the\n * model\", and nothing else says it: a view with no tags and a view whose tags\n * are all somebody's own vocabulary are the same thing here.\n *\n * THE TAG OPTS A VIEW IN WHETHER OR NOT IT RESOLVES. A `#cap-` slug that names\n * no declared capability is a broken claim about the vocabulary, not a withdrawn\n * one, so its steps are still graded — and the step grades read\n * `architecture/capabilities.yaml` nowhere at all. Coupling them would mean a\n * fleet that has not adopted the capability axis could never have a use case\n * checked, which inverts the adoption order the whole axis is built on: draw the\n * flow first, name the capability when the vocabulary exists.\n *\n * Everything here is LINEAR IN STEPS over documents `validate --all` has already\n * parsed, and nothing in it reads a file or throws — a fleet with no tagged view\n * produces exactly nothing. Linear in steps is not free per step: `attributeStep`\n * scans `relationships` once for the exact tier and again for the resolved one,\n * and `isActor` scans `elements`, so the real shape is O(steps × relationships)\n * plus O(steps × elements). That is why `StepGrading` is built once below rather\n * than per hop — the per-hop cost is a scan, so anything rebuilt per hop is paid\n * against every hop in the fleet.\n */\nimport { compareIds } from \"../../../../core/repo/entries.js\";\nimport { resolveCapabilityTags } from \"../../../../core/capabilities/usecase-join.js\";\nimport { isUseCase } from \"../../../../core/usecases/fleet.js\";\nimport type { Elem, Rel } from \"../../../../core/c4/likec4.js\";\nimport type { ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { capabilityTagFindings } from \"./capability-tag.js\";\nimport { requirementTagFindings } from \"./requirement-tag.js\";\nimport { stepFindings, type StepGrading } from \"./steps.js\";\nimport { viewFile } from \"../../../../core/usecases/place.js\";\n\n/** What the use-case grades run over: the views, the model they are drawn on, and the fleet. */\nexport interface UseCaseScope {\n  /**\n   * Every `dynamic view` the `architecture/` PROJECT declares, each carrying the\n   * file it was written in.\n   *\n   * The caller must pass views that came from `loadProject` and no others. Only\n   * that loader gives a view a `sourcePath` relative to `architecture/`; the\n   * single-file loaders name every document after themselves (`source.c4`), and\n   * a finding built from one of those would name a file that has never existed\n   * — see `./place.ts`, which is where the path is spelled.\n   */\n  views: readonly ParsedView[];\n  elements: Elem[];\n  relationships: Rel[];\n  /** The `services/<id>/` directories that exist. */\n  services: ReadonlySet<string>;\n  /** The shared element→service resolver — the same one every other edge join uses. */\n  resolve: (id: string) => string;\n  /**\n   * The declared capability ids, or `null` when `architecture/capabilities.yaml`\n   * is absent or does not read as a vocabulary.\n   *\n   * `null` and `[]` are deliberately different answers, and the join at\n   * `core/capabilities/usecase-join.ts` says why it cannot tell them apart\n   * itself: an empty list means \"the fleet declares no capabilities\", which is a\n   * real verdict every tag then fails against, while `null` means \"there is no\n   * vocabulary to grade against\" and suspends the tag grade entirely. The\n   * caller applies the ladder because the caller is the one that read the file.\n   */\n  capabilities: readonly string[] | null;\n  /**\n   * The requirement ids one capability's document declares, or `undefined` for a\n   * capability with no document — the scope a `#req-` tag is resolved in.\n   *\n   * A function rather than the map itself, so this package never learns what a\n   * capability document is: the fleet target reads them once\n   * (`capabilityRequirementIndex`) and hands the lookup over. `undefined` and an\n   * empty set are different answers here, exactly as they are one join over —\n   * no document at all, against a document declaring no promises yet.\n   */\n  requirementsOf: (capability: string) => ReadonlySet<string> | undefined;\n}\n\n/**\n * The views that opted in, in a stable order.\n *\n * The opt-in itself is `isUseCase` in `core/usecases/fleet.ts` and is not\n * restated here. It used to be — the same `startsWith` pair, spelled a second\n * time — and the two spellings drifted: this one took either reserved prefix\n * while the reader-side one took `#cap-` alone, so `validate` graded a\n * `#req-`-only flow that `loam diff`, `delta`, `status`, the packs and `list\n * capabilities` could not see. What is left here is the ORDER, which is this\n * package's own concern.\n *\n * Sorted by (file, view id) rather than reported in LikeC4's own record order:\n * nothing in loam has measured that the parse preserves declaration order, so a\n * report whose row order depends on that would reorder under a dependency bump\n * — the diff-stability rule `core/capabilities/rollup.ts` states for its rows,\n * applied to findings.\n */\nfunction gradedViews(views: readonly ParsedView[]): ParsedView[] {\n  return views\n    .filter(isUseCase)\n    .sort((a, b) => compareIds(viewFile(a), viewFile(b)) || compareIds(a.id, b.id));\n}\n\n/**\n * Every use-case finding a fleet's declared views earn.\n *\n * The grading record is built once and shared across every step of every view:\n * `attributeStep` caches its element→service resolver on the identity of the\n * elements array and the fleet set, so handing it one `StepScope` for the whole\n * run is what keeps the fleet's use cases from rebuilding that id map per hop.\n */\nexport function useCaseFindings(scope: UseCaseScope): Finding[] {\n  const grading: StepGrading = {\n    // `known` and `services` come from ONE value, so the fleet set the\n    // attribution resolves against and the fleet set the provider guard tests\n    // cannot drift apart into two answers about the same element.\n    model: { elements: scope.elements, relationships: scope.relationships, known: scope.services },\n    services: scope.services,\n    resolve: scope.resolve,\n  };\n  const findings: Finding[] = [];\n  for (const view of gradedViews(scope.views)) {\n    // ONE resolution of this view's capability tags, shared by both grades. The\n    // `#req-` tag is scoped by exactly the capabilities the `#cap-` tags resolve\n    // to, so resolving twice would be two chances to disagree about which\n    // document a `Requirement-ID` is unique inside.\n    //\n    // THE LADDER IS THE `null`, NOT AN EMPTY LIST, and the distinction is a\n    // wrong answer away: a suspended vocabulary handed on as `[]` reads to the\n    // requirement grade as \"this view resolves no capability\", which is its\n    // `unscoped` ERROR — so every `#req-` tag in a fleet that has not adopted\n    // the capability axis would be convicted for the axis not existing.\n    if (scope.capabilities !== null) {\n      const claims = resolveCapabilityTags(view.tags, scope.capabilities);\n      findings.push(...capabilityTagFindings(view, claims));\n      findings.push(...requirementTagFindings(view, claims, scope.requirementsOf));\n    }\n    for (const step of view.steps) findings.push(...stepFindings({ view, step }, grading));\n  }\n  return findings;\n}\n"]}

package/dist/commands/validate/fleet/views/ids.js

@@ -0,0 +1,40 @@
+import { SUBSYSTEM_VIEW_PREFIX, subsystemViewId } from "../../../../core/repo/tree/views.js";
+/**
+ * `authored` is every view id the `architecture/` project claims, each with the
+ * file that claims it — static views included, because a static view claims an
+ * id exactly as firmly as a dynamic one. Absent (the document did not parse, or
+ * an older loader did not read them) is treated as "nothing to compare", never
+ * as "nothing collides".
+ */
+export function viewIdFindings(authored, tree) {
+    if (authored === undefined || authored.length === 0)
+        return [];
+    const generated = new Map(tree.subsystems.map((sub) => [subsystemViewId(sub), sub.path.join("/")]));
+    const findings = [];
+    // Sorted and de-duplicated by id so a project claiming the same id twice —
+    // itself already a parse error, but reachable through a partial read — yields
+    // one finding per id rather than one per occurrence. The first claimant's file
+    // is the one named: with a duplicate the project does not parse at all, so
+    // there is never a second one to choose between.
+    const claimants = new Map();
+    for (const claim of authored)
+        if (!claimants.has(claim.id))
+            claimants.set(claim.id, claim.sourcePath);
+    for (const [id, file] of [...claimants].sort(([a], [b]) => (a < b ? -1 : 1))) {
+        const owner = generated.get(id);
+        if (owner === undefined)
+            continue;
+        findings.push({
+            severity: "error",
+            code: "subsystem.view-id-collision",
+            subject: id,
+            message: `subsystems: architecture/${file} declares \`view ${id}\`, which is the id loam generates ` +
+                `into architecture/subsystems.likec4 for services/${owner}/ — LikeC4 merges both files into one project, ` +
+                `so it refuses the whole architecture/ project and renders nothing. ` +
+                `Rename the view in architecture/${file}; ids beginning \`${SUBSYSTEM_VIEW_PREFIX}\` are loam's ` +
+                "to mint, and architecture/subsystems.likec4 is generated (`loam subsystem sync`) and must never be hand-edited.",
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=ids.js.map

package/dist/commands/validate/fleet/views/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/views/ids.ts"],"names":[],"mappings":"AAsCA,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAI7F;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAmC,EAAE,IAAe;IACjF,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC/D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACpG,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,8EAA8E;IAC9E,+EAA+E;IAC/E,2EAA2E;IAC3E,iDAAiD;IACjD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,KAAK,MAAM,KAAK,IAAI,QAAQ;QAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAAE,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACtG,KAAK,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,QAAQ,CAAC,IAAI,CAAC;YACZ,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,6BAA6B;YACnC,OAAO,EAAE,EAAE;YACX,OAAO,EACL,4BAA4B,IAAI,oBAAoB,EAAE,qCAAqC;gBAC3F,oDAAoD,KAAK,iDAAiD;gBAC1G,qEAAqE;gBACrE,mCAAmC,IAAI,qBAAqB,qBAAqB,gBAAgB;gBACjG,iHAAiH;SACpH,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * An authored view id that collides with one loam GENERATES into\n * `architecture/subsystems.likec4`.\n *\n * This closes a green-while-broken hole, and the shape of it is measured rather\n * than argued. The LikeC4 renderer merges every `.likec4` file in a project into\n * one model, and `likec4.config.json` scopes the root project to\n * `architecture/` — so `landscape.likec4` and the generated `subsystems.likec4`\n * share ONE flat view-id namespace. Author `view subsystem_commerce { }` in the\n * landscape while the tree has a `commerce` subsystem and the renderer refuses\n * the ENTIRE `architecture/` project with two `Duplicate view` diagnostics, one\n * per file — while `loam validate --all` printed `landscape: N service(s)\n * modelled — architecture/landscape.likec4 and services/ agree`. Reproduced at\n * the 1.59.2 pin.\n *\n * Nothing else in a loam repo can produce this. A duplicate INSIDE one document\n * is already 2 LikeC4 errors, so `landscape.invalid` has it (measured). A\n * service's `model.likec4` and a feature's `delta.likec4` are each their own\n * LikeC4 project — `likec4.config.json` excludes `services/**` and\n * `features/**` from the root — so their view ids cannot collide with the\n * landscape's, and a delta's views never travel through `archive` anyway. That\n * leaves exactly one pair, which is why this check compares exactly one pair\n * rather than taking a census across every document loam parses.\n *\n * ONLY the real collision is refused, never the merely reserved-looking name.\n * A landscape view called `subsystem_overview` with no `overview` subsystem\n * breaks nothing today, and refusing it would be loam inventing a rule about a\n * name that harms no one. The latent case is not lost: the moment somebody\n * creates that subsystem, the generator mints the id, and this same check fires\n * on the same run. The message names the reservation anyway, so an author fixing\n * one collision learns not to make the next.\n *\n * Graded on `validate --all` only, and the caller holds that gate together with\n * the landscape-parsed one: under a single-target run the fleet tree is not\n * walked and the generated ids are unknown, so the question is unanswerable and\n * the check stays silent rather than half-answering.\n */\nimport type { ViewIdClaim } from \"../../../../core/c4/parsed/view-ids.js\";\nimport { SUBSYSTEM_VIEW_PREFIX, subsystemViewId } from \"../../../../core/repo/tree/views.js\";\nimport type { FleetTree } from \"../../../../core/repo/tree/walk.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\n\n/**\n * `authored` is every view id the `architecture/` project claims, each with the\n * file that claims it — static views included, because a static view claims an\n * id exactly as firmly as a dynamic one. Absent (the document did not parse, or\n * an older loader did not read them) is treated as \"nothing to compare\", never\n * as \"nothing collides\".\n */\nexport function viewIdFindings(authored: ViewIdClaim[] | undefined, tree: FleetTree): Finding[] {\n  if (authored === undefined || authored.length === 0) return [];\n  const generated = new Map(tree.subsystems.map((sub) => [subsystemViewId(sub), sub.path.join(\"/\")]));\n  const findings: Finding[] = [];\n  // Sorted and de-duplicated by id so a project claiming the same id twice —\n  // itself already a parse error, but reachable through a partial read — yields\n  // one finding per id rather than one per occurrence. The first claimant's file\n  // is the one named: with a duplicate the project does not parse at all, so\n  // there is never a second one to choose between.\n  const claimants = new Map<string, string>();\n  for (const claim of authored) if (!claimants.has(claim.id)) claimants.set(claim.id, claim.sourcePath);\n  for (const [id, file] of [...claimants].sort(([a], [b]) => (a < b ? -1 : 1))) {\n    const owner = generated.get(id);\n    if (owner === undefined) continue;\n    findings.push({\n      severity: \"error\",\n      code: \"subsystem.view-id-collision\",\n      subject: id,\n      message:\n        `subsystems: architecture/${file} declares \\`view ${id}\\`, which is the id loam generates ` +\n        `into architecture/subsystems.likec4 for services/${owner}/ — LikeC4 merges both files into one project, ` +\n        `so it refuses the whole architecture/ project and renders nothing. ` +\n        `Rename the view in architecture/${file}; ids beginning \\`${SUBSYSTEM_VIEW_PREFIX}\\` are loam's ` +\n        \"to mint, and architecture/subsystems.likec4 is generated (`loam subsystem sync`) and must never be hand-edited.\",\n    });\n  }\n  return findings;\n}\n"]}

package/dist/commands/validate/fleet/views/stale.js

@@ -0,0 +1,59 @@
+/**
+ * Staleness of the GENERATED `architecture/subsystems.likec4` against the
+ * tree: exactly ONE error on exactly one file, repaired by exactly one
+ * command (`loam subsystem sync`).
+ *
+ * A content compare, deliberately — never a parse. A views-only document does
+ * not parse standalone (its `include` lines reference elements the landscape
+ * defines; the spike in `core/repo/tree/views.ts` records it), and no check
+ * anywhere reads the file's MEANING: the file is a scoping convenience for
+ * the LikeC4 renderer, so the only question loam owes it is "is this what the
+ * tree renders to". Rule 26 leaves this untouched: what loam may
+ * read is a `dynamic view`'s declared steps out of a document it already
+ * parses — never a static view's `include` predicates, and never this
+ * generated file at all. Absent counts as a state of its own: a fleet
+ * with subsystems and no file is stale, and a fleet with NO subsystems and a
+ * leftover file is stale too — the render contract says the file must then
+ * not exist, or a group deleted months ago keeps a view forever.
+ *
+ * The compare is over CONTENT, not BYTES, and `viewsAgree` in
+ * `core/repo/tree/views.ts` both performs it and records why: an ordinary
+ * Windows clone hands this file back with CRLF and not one fact in it changed,
+ * and under a byte compare the advertised repair is a loop rather than a
+ * diagnosis. The rule lives beside the generator because the module that mints
+ * the bytes is the one that owes an answer about them.
+ *
+ * Graded only when the landscape PARSED (the caller holds that gate): the
+ * expected bytes resolve members through the landscape's element→service
+ * join, and grading them against a map that is missing or unreadable would
+ * cascade a second error behind `landscape.missing`/`landscape.invalid`,
+ * pointing at a file whose repair command would only re-derive the same
+ * incomplete answer.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { subsystemViewsPath } from "../../../../core/repo/paths.js";
+import { renderSubsystemViews, viewsAgree } from "../../../../core/repo/tree/views.js";
+export async function viewsStaleFindings(docsDir, tree, elements) {
+    const path = subsystemViewsPath(docsDir);
+    const expected = renderSubsystemViews(tree, elements);
+    const actual = existsSync(path) ? await readFile(path, "utf8") : null;
+    if (viewsAgree(actual, expected))
+        return [];
+    const state = actual === null
+        ? "does not exist, but the tree has subsystems to mirror"
+        : expected === null
+            ? "exists, but the tree has no subsystems — the generated file must be absent"
+            : "does not match the tree";
+    return [
+        {
+            severity: "error",
+            code: "subsystem.views-stale",
+            subject: "architecture/subsystems.likec4",
+            message: `subsystems: architecture/subsystems.likec4 ${state} — ` +
+                `it is generated, one view per subsystem, and every derived scope drawn from it is wrong until it agrees. ` +
+                "Run `loam subsystem sync` to regenerate it; never edit it by hand.",
+        },
+    ];
+}
+//# sourceMappingURL=stale.js.map

package/dist/commands/validate/fleet/views/stale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale.js","sourceRoot":"","sources":["../../../../../src/commands/validate/fleet/views/stale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAIvF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAgB,EAChB,IAAe,EACf,QAAgB;IAEhB,MAAM,IAAI,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,oBAAoB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,IAAI,UAAU,CAAC,MAAM,EAAE,QAAQ,CAAC;QAAE,OAAO,EAAE,CAAC;IAC5C,MAAM,KAAK,GACT,MAAM,KAAK,IAAI;QACb,CAAC,CAAC,uDAAuD;QACzD,CAAC,CAAC,QAAQ,KAAK,IAAI;YACjB,CAAC,CAAC,4EAA4E;YAC9E,CAAC,CAAC,yBAAyB,CAAC;IAClC,OAAO;QACL;YACE,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,uBAAuB;YAC7B,OAAO,EAAE,gCAAgC;YACzC,OAAO,EACL,8CAA8C,KAAK,KAAK;gBACxD,2GAA2G;gBAC3G,oEAAoE;SACvE;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Staleness of the GENERATED `architecture/subsystems.likec4` against the\n * tree: exactly ONE error on exactly one file, repaired by exactly one\n * command (`loam subsystem sync`).\n *\n * A content compare, deliberately — never a parse. A views-only document does\n * not parse standalone (its `include` lines reference elements the landscape\n * defines; the spike in `core/repo/tree/views.ts` records it), and no check\n * anywhere reads the file's MEANING: the file is a scoping convenience for\n * the LikeC4 renderer, so the only question loam owes it is \"is this what the\n * tree renders to\". Rule 26 leaves this untouched: what loam may\n * read is a `dynamic view`'s declared steps out of a document it already\n * parses — never a static view's `include` predicates, and never this\n * generated file at all. Absent counts as a state of its own: a fleet\n * with subsystems and no file is stale, and a fleet with NO subsystems and a\n * leftover file is stale too — the render contract says the file must then\n * not exist, or a group deleted months ago keeps a view forever.\n *\n * The compare is over CONTENT, not BYTES, and `viewsAgree` in\n * `core/repo/tree/views.ts` both performs it and records why: an ordinary\n * Windows clone hands this file back with CRLF and not one fact in it changed,\n * and under a byte compare the advertised repair is a loop rather than a\n * diagnosis. The rule lives beside the generator because the module that mints\n * the bytes is the one that owes an answer about them.\n *\n * Graded only when the landscape PARSED (the caller holds that gate): the\n * expected bytes resolve members through the landscape's element→service\n * join, and grading them against a map that is missing or unreadable would\n * cascade a second error behind `landscape.missing`/`landscape.invalid`,\n * pointing at a file whose repair command would only re-derive the same\n * incomplete answer.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport type { Elem } from \"../../../../core/c4/likec4.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport { subsystemViewsPath } from \"../../../../core/repo/paths.js\";\nimport { renderSubsystemViews, viewsAgree } from \"../../../../core/repo/tree/views.js\";\nimport type { FleetTree } from \"../../../../core/repo/tree/walk.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\n\nexport async function viewsStaleFindings(\n  docsDir: DocsDir,\n  tree: FleetTree,\n  elements: Elem[],\n): Promise<Finding[]> {\n  const path = subsystemViewsPath(docsDir);\n  const expected = renderSubsystemViews(tree, elements);\n  const actual = existsSync(path) ? await readFile(path, \"utf8\") : null;\n  if (viewsAgree(actual, expected)) return [];\n  const state =\n    actual === null\n      ? \"does not exist, but the tree has subsystems to mirror\"\n      : expected === null\n        ? \"exists, but the tree has no subsystems — the generated file must be absent\"\n        : \"does not match the tree\";\n  return [\n    {\n      severity: \"error\",\n      code: \"subsystem.views-stale\",\n      subject: \"architecture/subsystems.likec4\",\n      message:\n        `subsystems: architecture/subsystems.likec4 ${state} — ` +\n        `it is generated, one view per subsystem, and every derived scope drawn from it is wrong until it agrees. ` +\n        \"Run `loam subsystem sync` to regenerate it; never edit it by hand.\",\n    },\n  ];\n}\n"]}

package/dist/commands/validate/links/corpus.js

@@ -0,0 +1,92 @@
+/**
+ * Where each target's link findings are filed — the ORDER, not the rule.
+ *
+ * The rule lives in `core/links/`: extract the links, resolve them, name the
+ * ones that point at nothing. WHICH documents belong to a service, a feature or
+ * the fleet lives there too (`core/links/corpus.ts`), because the glossary's
+ * backlink index reads the same list and a second enumeration would be free to
+ * disagree with this one. What is left here is the part that belongs to
+ * `validate`: reading each document, deciding which target carries the finding,
+ * and refusing to let one unreadable file take a whole target down with it.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { pathCaseIndex } from "../../../core/links/case.js";
+import { featureDocuments, fleetDocuments, serviceDocuments } from "../../../core/links/corpus.js";
+import { unresolvedLinkFindings } from "../../../core/links/findings.js";
+import { featureGlossaryOverlay } from "../../../core/glossary/delta.js";
+import { decodeDocument } from "../../../core/kernel/document-bytes.js";
+import {} from "../../../core/repo/paths.js";
+import { repoPath } from "../../../core/envelope/json.js";
+import { FleetContext } from "../../../core/fleet-context.js";
+import {} from "../../../core/vocabulary/report.js";
+/** One service's documents, graded on the service target. */
+export async function serviceLinkFindings(check, paths) {
+    return documentFindings(await serviceDocuments(paths), check);
+}
+/**
+ * One feature's documents, graded on the feature target — with the glossary
+ * terms it introduces treated as already living. See `LinkScope.overlay`: a
+ * feature cites the word it is adding at that word's future path, and an index
+ * built from the living tree alone would refuse the axis's own headline case.
+ */
+export async function featureLinkFindings(check, featureDir) {
+    return documentFindings(await featureDocuments(featureDir, check.fleet), {
+        ...check,
+        overlay: await featureGlossaryOverlay(check.docsDir, featureDir),
+    });
+}
+/**
+ * The fleet's own documents — its ADRs, the living capability tree and the
+ * glossary — graded once on the landscape target. A single-target run says
+ * nothing about them, the rule `permissions.unenforced` already follows: a
+ * finding about the fleet repeated on every service target is the report.
+ */
+export async function fleetLinkFindings(check) {
+    return documentFindings(await fleetDocuments(check.docsDir, check.fleet), check);
+}
+/**
+ * Grade a list of documents, skipping the ones that are not there.
+ *
+ * ABSENCE IS NOT THIS CHECK'S BUSINESS: `service.no-spec` already names a
+ * missing `spec.md`, and most services have no runbook and no ADRs at all.
+ *
+ * AN UNREADABLE DOCUMENT IS NAMED HERE RATHER THAN THROWN, and that is what
+ * `link.unreadable` is for. Every other reader of a service's documents is
+ * wrapped by `report.ts`'s `guarded`, which turns an IO failure into
+ * `service.unreadable` — "nothing about this service was checked". That verdict
+ * is right for `spec.md` and wrong for an ADR: this check is the first to read
+ * those files at all, and a runbook saved as UTF-16 must not be able to blank
+ * a service's entire report when the only thing that could not be graded is one
+ * document's links.
+ */
+async function documentFindings(paths, check) {
+    const findings = [];
+    // One directory-listing memo for this target's whole corpus. Built here
+    // rather than per document because a service's ADRs all resolve through the
+    // same two or three directories, and rather than at module scope because a
+    // listing that outlived the command would answer for a tree that has moved.
+    const scope = { ...check, cases: pathCaseIndex() };
+    for (const path of paths) {
+        if (!existsSync(path))
+            continue;
+        let text;
+        try {
+            text =
+                check.fleet === undefined ? decodeDocument(await readFile(path), path) : await check.fleet.readText(path);
+        }
+        catch (err) {
+            findings.push({
+                severity: "error",
+                code: "link.unreadable",
+                ...(check.subject === undefined ? {} : { subject: check.subject }),
+                message: `${repoPath(check.docsDir, path)} could not be read, so its links were not checked — ` +
+                    `${err instanceof Error ? err.message : String(err)}`,
+            });
+            continue;
+        }
+        findings.push(...unresolvedLinkFindings({ path, text }, scope));
+    }
+    return findings;
+}
+//# sourceMappingURL=corpus.js.map

package/dist/commands/validate/links/corpus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus.js","sourceRoot":"","sources":["../../../../src/commands/validate/links/corpus.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Where each target's link findings are filed — the ORDER, not the rule.\n *\n * The rule lives in `core/links/`: extract the links, resolve them, name the\n * ones that point at nothing. WHICH documents belong to a service, a feature or\n * the fleet lives there too (`core/links/corpus.ts`), because the glossary's\n * backlink index reads the same list and a second enumeration would be free to\n * disagree with this one. What is left here is the part that belongs to\n * `validate`: reading each document, deciding which target carries the finding,\n * and refusing to let one unreadable file take a whole target down with it.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { pathCaseIndex } from \"../../../core/links/case.js\";\nimport { featureDocuments, fleetDocuments, serviceDocuments } from \"../../../core/links/corpus.js\";\nimport { unresolvedLinkFindings, type LinkScope } from \"../../../core/links/findings.js\";\nimport { featureGlossaryOverlay } from \"../../../core/glossary/delta.js\";\nimport { decodeDocument } from \"../../../core/kernel/document-bytes.js\";\nimport { type ServicePaths } from \"../../../core/repo/paths.js\";\nimport { repoPath } from \"../../../core/envelope/json.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport type { DocsDir, FeatureDir } from \"../../../core/kernel/ids/dirs.js\";\n\n/** Where the findings are filed, and how the documents are read. */\nexport interface LinkCheck {\n  docsDir: DocsDir;\n  /** The service or feature the report is about; absent at fleet scope. */\n  subject?: string;\n  fleet?: FleetContext;\n  /** Paths an in-flight feature will create — `LinkScope.overlay` says why. */\n  overlay?: ReadonlySet<string>;\n}\n\n/** One service's documents, graded on the service target. */\nexport async function serviceLinkFindings(check: LinkCheck, paths: ServicePaths): Promise<Finding[]> {\n  return documentFindings(await serviceDocuments(paths), check);\n}\n\n/**\n * One feature's documents, graded on the feature target — with the glossary\n * terms it introduces treated as already living. See `LinkScope.overlay`: a\n * feature cites the word it is adding at that word's future path, and an index\n * built from the living tree alone would refuse the axis's own headline case.\n */\nexport async function featureLinkFindings(check: LinkCheck, featureDir: FeatureDir): Promise<Finding[]> {\n  return documentFindings(await featureDocuments(featureDir, check.fleet), {\n    ...check,\n    overlay: await featureGlossaryOverlay(check.docsDir, featureDir),\n  });\n}\n\n/**\n * The fleet's own documents — its ADRs, the living capability tree and the\n * glossary — graded once on the landscape target. A single-target run says\n * nothing about them, the rule `permissions.unenforced` already follows: a\n * finding about the fleet repeated on every service target is the report.\n */\nexport async function fleetLinkFindings(check: LinkCheck): Promise<Finding[]> {\n  return documentFindings(await fleetDocuments(check.docsDir, check.fleet), check);\n}\n\n/**\n * Grade a list of documents, skipping the ones that are not there.\n *\n * ABSENCE IS NOT THIS CHECK'S BUSINESS: `service.no-spec` already names a\n * missing `spec.md`, and most services have no runbook and no ADRs at all.\n *\n * AN UNREADABLE DOCUMENT IS NAMED HERE RATHER THAN THROWN, and that is what\n * `link.unreadable` is for. Every other reader of a service's documents is\n * wrapped by `report.ts`'s `guarded`, which turns an IO failure into\n * `service.unreadable` — \"nothing about this service was checked\". That verdict\n * is right for `spec.md` and wrong for an ADR: this check is the first to read\n * those files at all, and a runbook saved as UTF-16 must not be able to blank\n * a service's entire report when the only thing that could not be graded is one\n * document's links.\n */\nasync function documentFindings(paths: string[], check: LinkCheck): Promise<Finding[]> {\n  const findings: Finding[] = [];\n  // One directory-listing memo for this target's whole corpus. Built here\n  // rather than per document because a service's ADRs all resolve through the\n  // same two or three directories, and rather than at module scope because a\n  // listing that outlived the command would answer for a tree that has moved.\n  const scope: LinkScope = { ...check, cases: pathCaseIndex() };\n  for (const path of paths) {\n    if (!existsSync(path)) continue;\n    let text: string;\n    try {\n      text =\n        check.fleet === undefined ? decodeDocument(await readFile(path), path) : await check.fleet.readText(path);\n    } catch (err) {\n      findings.push({\n        severity: \"error\",\n        code: \"link.unreadable\",\n        ...(check.subject === undefined ? {} : { subject: check.subject }),\n        message:\n          `${repoPath(check.docsDir, path)} could not be read, so its links were not checked — ` +\n          `${err instanceof Error ? err.message : String(err)}`,\n      });\n      continue;\n    }\n    findings.push(...unresolvedLinkFindings({ path, text }, scope));\n  }\n  return findings;\n}\n"]}