@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/dist/commands/validate/service/usecases/tags.js

@@ -0,0 +1,113 @@
+/**
+ * The two tag grades of a SERVICE-LOCAL use case: `usecase.requirement-unresolved`
+ * with service-worded arms, and `usecase.capability-unresolved`'s placement arm.
+ *
+ * Both codes are REUSED from the fleet target rather than minted, under
+ * add-error-code's "prefer existing" rule: a caller acts the same way (fix the
+ * tag, or the `Requirement-ID:` line it names), and only the sentences differ.
+ * The fleet's own graders (`core/usecases/grade/{requirement,capability}-tag.ts`)
+ * are not reused for the sentences, because every one of theirs names a
+ * capability document, and a service-local flow has none.
+ *
+ * WHY `#req-` IS SCOPED BY THE SERVICE. Inside `architecture/`, a `#req-` tag
+ * means nothing until a `#cap-` tag has said which capability document the
+ * `Requirement-ID` is unique inside. Beside a model there is no such question:
+ * the directory IS the scope, and the ids are the ones THIS service's `spec.md`
+ * and `arch.spec.md` declare — the flow keeps a container-level promise the way
+ * a fleet flow keeps a business one. The join is `resolveRequirementTags` with
+ * the service as its one-element scope, so the arms fall out mechanically and
+ * `unscoped` is unreachable.
+ *
+ * WHY `#cap-` IS REFUSED, NOT IGNORED AND NOT RESOLVED. A capability is
+ * realized by a hop sequence across the fleet map — "the only join that
+ * crosses services" — and `keptBy` reads the fleet project only. Ignoring the
+ * tag would leave `#cap-checkout` on a service flow green and silently unread;
+ * resolving it against the vocabulary would make validate see a claim no other
+ * surface sees. So it is refused by PLACEMENT, whether or not
+ * `architecture/capabilities.yaml` exists: the reason is where the tag sits,
+ * not what the vocabulary says. The view stays opted in and its steps are
+ * graded — either prefix is the opt-in, exactly as at fleet altitude.
+ */
+import { CAP_TAG_PREFIX, REQ_TAG_PREFIX, resolveRequirementTags, tagSlug, } from "../../../../core/capabilities/usecase-join.js";
+import { compareIds } from "../../../../core/repo/entries.js";
+/** A `Requirement-ID` as an author must write it in a tag: `PAY.AUTH (#req-PAY-AUTH)`. */
+function idAndTag(id) {
+    return `${id} (#${REQ_TAG_PREFIX}${tagSlug(id)})`;
+}
+/**
+ * The fix for one unresolved claim, in the service's own vocabulary. The same
+ * arms the fleet grade has, each sentence pointing at the document that
+ * carries the fix here — spec.md and arch.spec.md, never a capability.
+ */
+function advice(claim, scope) {
+    const where = `${scope.service} (spec.md or arch.spec.md)`;
+    switch (claim.kind) {
+        case "unscoped":
+            // Unreachable: the scope is always exactly one service. A sentence
+            // rather than a throw, because this runs inside a validate run over
+            // somebody's fleet, and a broken invariant there is one finding, not a
+            // crash.
+            return "the flow could not be scoped to this service — report this: a service-local flow is always scoped to its own directory.";
+        case "undocumented":
+            return (`${scope.treePath}/ has no spec.md and no arch.spec.md, so it carries no requirements to satisfy. ` +
+                "Write the requirement first — a flow keeps a promise a document makes.");
+        case "empty":
+            return (`${scope.service}'s spec.md and arch.spec.md declare no \`Requirement-ID:\` at all — a #req- tag joins by ` +
+                "stable id, and a requirement without one cannot be named by a flow. Add `Requirement-ID: <id>` to the " +
+                "requirement this flow keeps.");
+        case "none":
+            return claim.close.length > 0
+                ? `no requirement of ${where} flattens to '${claim.slug}'. Did you mean: ${claim.close.map(idAndTag).join(", ")}?`
+                : `no requirement of ${where} flattens to '${claim.slug}' — check the \`Requirement-ID:\` lines in both documents.`;
+        default:
+            return (`${claim.ids.length} requirements of ${scope.service} flatten to '${claim.slug}' (${claim.ids.join(", ")}) — ` +
+                "a Requirement-ID is unique inside ONE document and this service has two, so nothing in the tag can say " +
+                "which promise the flow keeps. Rename one of them.");
+    }
+}
+/**
+ * One finding per `#req-` tag that does not resolve against the service's own
+ * ids — never one per view, for the fleet grade's reason: several `#req-` tags
+ * on one view are legal and normal, and a broken tag beside a working one must
+ * neither swallow the break nor lose the promise the view genuinely keeps.
+ */
+function requirementFindings(view, scope, place) {
+    const findings = [];
+    for (const claim of resolveRequirementTags(view.tags, [scope.service], () => scope.requirementIds)) {
+        if (claim.kind === "resolved")
+            continue;
+        findings.push({
+            severity: "error",
+            code: "usecase.requirement-unresolved",
+            // The VIEW, not the tag, as at fleet altitude: a subject is what a reader
+            // goes and opens, and one broken use case counts once however many of
+            // its tags are wrong.
+            subject: view.id,
+            message: `${place} is tagged #${claim.tag}, and it does not resolve: ${advice(claim, scope)}`,
+        });
+    }
+    return findings;
+}
+/**
+ * One finding per `#cap-` tag the view carries — the placement refusal. Sorted
+ * and de-duplicated for `resolveCapabilityTags`' reason: nothing in loam has
+ * measured that LikeC4 preserves the author's tag order, and one breach earns
+ * one finding.
+ */
+function capabilityFindings(view, place) {
+    const claimed = [...new Set(view.tags.filter((tag) => tag.startsWith(CAP_TAG_PREFIX)))].sort(compareIds);
+    return claimed.map((tag) => ({
+        severity: "error",
+        code: "usecase.capability-unresolved",
+        subject: view.id,
+        message: `${place} is tagged #${tag} inside this service's own project, where no capability can be claimed: ` +
+            "a capability is a fleet promise, and only a flow in architecture/usecases/ can keep one; a flow beside " +
+            "model.likec4 keeps THIS service's promises (#req-<Requirement-ID>). Drop the tag: the capability's promise " +
+            "is kept by the fleet flow that calls this service, and this flow is the hop sequence inside it.",
+    }));
+}
+/** Every tag finding one service-local view earns: the placement refusals first, then the requirement claims. */
+export function serviceTagFindings(view, scope, place) {
+    return [...capabilityFindings(view, place), ...requirementFindings(view, scope, place)];
+}
+//# sourceMappingURL=tags.js.map

package/dist/commands/validate/service/usecases/tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../../../../../src/commands/validate/service/usecases/tags.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The two tag grades of a SERVICE-LOCAL use case: `usecase.requirement-unresolved`\n * with service-worded arms, and `usecase.capability-unresolved`'s placement arm.\n *\n * Both codes are REUSED from the fleet target rather than minted, under\n * add-error-code's \"prefer existing\" rule: a caller acts the same way (fix the\n * tag, or the `Requirement-ID:` line it names), and only the sentences differ.\n * The fleet's own graders (`core/usecases/grade/{requirement,capability}-tag.ts`)\n * are not reused for the sentences, because every one of theirs names a\n * capability document, and a service-local flow has none.\n *\n * WHY `#req-` IS SCOPED BY THE SERVICE. Inside `architecture/`, a `#req-` tag\n * means nothing until a `#cap-` tag has said which capability document the\n * `Requirement-ID` is unique inside. Beside a model there is no such question:\n * the directory IS the scope, and the ids are the ones THIS service's `spec.md`\n * and `arch.spec.md` declare — the flow keeps a container-level promise the way\n * a fleet flow keeps a business one. The join is `resolveRequirementTags` with\n * the service as its one-element scope, so the arms fall out mechanically and\n * `unscoped` is unreachable.\n *\n * WHY `#cap-` IS REFUSED, NOT IGNORED AND NOT RESOLVED. A capability is\n * realized by a hop sequence across the fleet map — \"the only join that\n * crosses services\" — and `keptBy` reads the fleet project only. Ignoring the\n * tag would leave `#cap-checkout` on a service flow green and silently unread;\n * resolving it against the vocabulary would make validate see a claim no other\n * surface sees. So it is refused by PLACEMENT, whether or not\n * `architecture/capabilities.yaml` exists: the reason is where the tag sits,\n * not what the vocabulary says. The view stays opted in and its steps are\n * graded — either prefix is the opt-in, exactly as at fleet altitude.\n */\nimport {\n  CAP_TAG_PREFIX,\n  REQ_TAG_PREFIX,\n  resolveRequirementTags,\n  tagSlug,\n  type RequirementClaim,\n} from \"../../../../core/capabilities/usecase-join.js\";\nimport type { ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport { compareIds } from \"../../../../core/repo/entries.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\n\n/** What the tag grades resolve against: the service, and its own identified requirements. */\nexport interface ServiceTagScope {\n  service: string;\n  /** Repo-relative tree path of the service directory, for the sentences. */\n  treePath: string;\n  /**\n   * Every `Requirement-ID` this service's spec.md (living, REMOVED skipped) and\n   * arch.spec.md declare, or `undefined` when NEITHER document exists — the\n   * same two answers `requirementsOf` gives one join over: no document at all,\n   * against documents declaring no identified promise yet.\n   */\n  requirementIds: ReadonlySet<string> | undefined;\n}\n\n/** A `Requirement-ID` as an author must write it in a tag: `PAY.AUTH (#req-PAY-AUTH)`. */\nfunction idAndTag(id: string): string {\n  return `${id} (#${REQ_TAG_PREFIX}${tagSlug(id)})`;\n}\n\n/**\n * The fix for one unresolved claim, in the service's own vocabulary. The same\n * arms the fleet grade has, each sentence pointing at the document that\n * carries the fix here — spec.md and arch.spec.md, never a capability.\n */\nfunction advice(claim: Exclude<RequirementClaim, { kind: \"resolved\" }>, scope: ServiceTagScope): string {\n  const where = `${scope.service} (spec.md or arch.spec.md)`;\n  switch (claim.kind) {\n    case \"unscoped\":\n      // Unreachable: the scope is always exactly one service. A sentence\n      // rather than a throw, because this runs inside a validate run over\n      // somebody's fleet, and a broken invariant there is one finding, not a\n      // crash.\n      return \"the flow could not be scoped to this service — report this: a service-local flow is always scoped to its own directory.\";\n    case \"undocumented\":\n      return (\n        `${scope.treePath}/ has no spec.md and no arch.spec.md, so it carries no requirements to satisfy. ` +\n        \"Write the requirement first — a flow keeps a promise a document makes.\"\n      );\n    case \"empty\":\n      return (\n        `${scope.service}'s spec.md and arch.spec.md declare no \\`Requirement-ID:\\` at all — a #req- tag joins by ` +\n        \"stable id, and a requirement without one cannot be named by a flow. Add `Requirement-ID: <id>` to the \" +\n        \"requirement this flow keeps.\"\n      );\n    case \"none\":\n      return claim.close.length > 0\n        ? `no requirement of ${where} flattens to '${claim.slug}'. Did you mean: ${claim.close.map(idAndTag).join(\", \")}?`\n        : `no requirement of ${where} flattens to '${claim.slug}' — check the \\`Requirement-ID:\\` lines in both documents.`;\n    default:\n      return (\n        `${claim.ids.length} requirements of ${scope.service} flatten to '${claim.slug}' (${claim.ids.join(\", \")}) — ` +\n        \"a Requirement-ID is unique inside ONE document and this service has two, so nothing in the tag can say \" +\n        \"which promise the flow keeps. Rename one of them.\"\n      );\n  }\n}\n\n/**\n * One finding per `#req-` tag that does not resolve against the service's own\n * ids — never one per view, for the fleet grade's reason: several `#req-` tags\n * on one view are legal and normal, and a broken tag beside a working one must\n * neither swallow the break nor lose the promise the view genuinely keeps.\n */\nfunction requirementFindings(view: ParsedView, scope: ServiceTagScope, place: string): Finding[] {\n  const findings: Finding[] = [];\n  for (const claim of resolveRequirementTags(view.tags, [scope.service], () => scope.requirementIds)) {\n    if (claim.kind === \"resolved\") continue;\n    findings.push({\n      severity: \"error\",\n      code: \"usecase.requirement-unresolved\",\n      // The VIEW, not the tag, as at fleet altitude: a subject is what a reader\n      // goes and opens, and one broken use case counts once however many of\n      // its tags are wrong.\n      subject: view.id,\n      message: `${place} is tagged #${claim.tag}, and it does not resolve: ${advice(claim, scope)}`,\n    });\n  }\n  return findings;\n}\n\n/**\n * One finding per `#cap-` tag the view carries — the placement refusal. Sorted\n * and de-duplicated for `resolveCapabilityTags`' reason: nothing in loam has\n * measured that LikeC4 preserves the author's tag order, and one breach earns\n * one finding.\n */\nfunction capabilityFindings(view: ParsedView, place: string): Finding[] {\n  const claimed = [...new Set(view.tags.filter((tag) => tag.startsWith(CAP_TAG_PREFIX)))].sort(compareIds);\n  return claimed.map((tag) => ({\n    severity: \"error\",\n    code: \"usecase.capability-unresolved\",\n    subject: view.id,\n    message:\n      `${place} is tagged #${tag} inside this service's own project, where no capability can be claimed: ` +\n      \"a capability is a fleet promise, and only a flow in architecture/usecases/ can keep one; a flow beside \" +\n      \"model.likec4 keeps THIS service's promises (#req-<Requirement-ID>). Drop the tag: the capability's promise \" +\n      \"is kept by the fleet flow that calls this service, and this flow is the hop sequence inside it.\",\n  }));\n}\n\n/** Every tag finding one service-local view earns: the placement refusals first, then the requirement claims. */\nexport function serviceTagFindings(view: ParsedView, scope: ServiceTagScope, place: string): Finding[] {\n  return [...capabilityFindings(view, place), ...requirementFindings(view, scope, place)];\n}\n"]}

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

@@ -0,0 +1,209 @@
+/**
+ * The use-case axis of the SERVICE target: the `dynamic view`s a service's own
+ * LikeC4 project declares, graded as the hop sequences behind its requirements.
+ *
+ * The fleet target grades flows drawn over the map (`core/usecases/grade/`);
+ * this grades flows drawn over ONE service's containers, which only that
+ * service's project can resolve — the whole reason the slot exists
+ * (`core/usecases/service/flows.ts` carries the report). The step grades are
+ * the fleet's own `stepFindings`, reused with the service's project as the
+ * model, the enumerated fleet as `services`, and one injection: where a
+ * finding says the view is. A second verdict→code mapping here would be the
+ * drift that package's banner forbids.
+ *
+ * ONLY VIEWS CARRYING A RESERVED TAG ARE GRADED, as at fleet altitude and for
+ * the same reason: a service's `views.likec4` full of hand-drawn diagrams must
+ * not turn red on upgrade. The reader applies the opt-in; this module never
+ * sees an untagged view. Graded is narrower than LOADED, and the difference is
+ * the reader's gate (`core/usecases/service/flows.ts`): an untagged sibling is
+ * not even loaded while no view in the project opts in and no sibling mentions
+ * a reserved prefix anywhere in its bytes — but once a view in
+ * model.likec4 itself opts in, or a sibling mentions `req-`, `cap-` or `suite-`
+ * in a comment or a title, every sibling is staged, and a project that does not
+ * read is one `usecase.flow-invalid` whether or not any view in it opted in.
+ *
+ * A SIBLING THAT BREAKS THE PROJECT is ONE `usecase.flow-invalid` — reused,
+ * because its meaning is exactly this ("loam could not read the flows against
+ * the map they are drawn over, so it graded none of them, and the renderer
+ * refuses the same project") applied to the service project instead of the
+ * merge preview — and NEVER `c4.invalid`: that code means "model.likec4 does
+ * not parse, every model check is suspended", and here the model parses and
+ * every model check RAN. Reusing it would tell an agent to fix the wrong file
+ * and tell the brief's `checks[]` row ("every other check stops here") a lie.
+ */
+import { existsSync } from "node:fs";
+import { relative } from "node:path";
+import { serviceResolver } from "../../../../core/c4/resolve/service.js";
+import { compareIds } from "../../../../core/repo/entries.js";
+import { errorText } from "../../../../core/c4/likec4.js";
+import { CAP_TAG_PREFIX, REQ_TAG_PREFIX } from "../../../../core/capabilities/usecase-join.js";
+import { stepFindings } from "../../../../core/usecases/grade/steps.js";
+import { serviceTagFindings } from "./tags.js";
+/** `<svc>: services/<tree>/<file> — dynamic view '<id>'` — the service target's spelling of `viewPlace`. */
+function servicePlace(scope, view) {
+    // An absent `sourcePath` names the directory rather than guessing a file,
+    // for `viewFile`'s reason; nothing at the 1.59.2 pin reaches that arm.
+    return `${scope.service}: ${scope.treePath}/${view.sourcePath ?? ""} — dynamic view '${view.id}'`;
+}
+/** The repo-relative spelling of a project error's document, or the whole project when it carries none. */
+function fileOf(scope, error) {
+    return error.sourceFsPath === undefined
+        ? `${scope.treePath}/`
+        : relative(scope.docsDir, error.sourceFsPath).split(/[\\/]/).join("/");
+}
+/**
+ * The one finding a broken project earns. `details` is one `errorText` line
+ * per error, each prefixed by its file, because the project may hold several
+ * siblings and the fault may sit in any of them — including `model.likec4`
+ * itself when a sibling re-declares its `specification` block, an error LikeC4
+ * blames on both files. `locations` names the first broken file, in the sorted
+ * order the reader produced.
+ */
+function flowInvalidFinding(scope, errors) {
+    const files = [...new Set(errors.map((error) => fileOf(scope, error)))];
+    const [first = `${scope.treePath}/`, ...others] = files;
+    const named = others.length === 0 ? first : `${first} and ${others.length} more file(s)`;
+    return {
+        severity: "error",
+        code: "usecase.flow-invalid",
+        subject: scope.service,
+        message: `${scope.service}: ${named} has ${errors.length} error(s) — every .likec4 beside model.likec4 is one LikeC4 ` +
+            "project, read the way the renderer reads it, and the renderer refuses the whole project over one broken " +
+            "file; no flow in it was graded. model.likec4 itself parses and is graded alone.",
+        // The hint first, for `c4.invalid`'s reason (`../model/grade.ts`):
+        // `capDetails` keeps ten lines, one broken document can carry more than ten
+        // errors, and a diagnosis appended after them is dropped exactly when the
+        // reader needs it.
+        details: [...tagHint(errors), ...errors.map((error) => `${fileOf(scope, error)}: ${errorText(error)}`)],
+        locations: [{ path: first, role: "primary" }],
+    };
+}
+/** `Could not resolve reference to Tag named '#req-PAY-AUTH'.` — measured at the 1.59.2 pin. */
+const UNDECLARED_TAG = /reference to Tag named '#?([\w.-]+)'/;
+/**
+ * The one line an undeclared RESERVED tag earns.
+ *
+ * The opt-in is a tag, LikeC4 refuses a tag no `specification` declares, and the
+ * refusal is a bare `Could not resolve reference to Tag named …` — so an author
+ * following the protocol's "tag the view `#req-<id>`" got a parse error naming
+ * the thing they had just been told to write, with nothing saying a tag must be
+ * declared first (verification 2026-09-04, D10). One line, from the first such
+ * error only: the second one has the same repair.
+ */
+function tagHint(errors) {
+    for (const error of errors) {
+        const match = UNDECLARED_TAG.exec(error.message);
+        const name = match?.[1];
+        if (name === undefined)
+            continue;
+        // `cap-` and `req-` do NOT share a repair here, and covering both with one
+        // hint sent an author two steps where one would do: declaring `tag cap-…`
+        // makes the file parse and the very next run says `usecase.capability-
+        // unresolved` — "no capability can be claimed inside this service's own
+        // project. Drop the tag." A capability is claimed at fleet altitude, so the
+        // tag can never resolve to anything beside a model, whatever is declared
+        // (verification 2026-09-04).
+        if (name.startsWith(CAP_TAG_PREFIX)) {
+            return [
+                `\`#${name}\` claims a capability, and a capability is claimed at FLEET altitude only — a flow beside ` +
+                    "model.likec4 is read in this service's own project, where no capability can be resolved. Declaring " +
+                    `\`tag ${name}\` makes the file parse and earns \`usecase.capability-unresolved\` on the next run: ` +
+                    `drop the tag, and tag the flow \`#${REQ_TAG_PREFIX}<Requirement-ID>\` instead, or draw it in ` +
+                    "`architecture/usecases/` where a capability tag belongs",
+            ];
+        }
+        if (!name.startsWith(REQ_TAG_PREFIX))
+            continue;
+        return [
+            `declare \`tag ${name}\` in the \`specification { }\` block this project reads — model.likec4's own ` +
+                "for a model that stands alone, the fleet map's for one that extends it (or a tags-only " +
+                "`specification` in a document beside the model)",
+        ];
+    }
+    return [];
+}
+/**
+ * The FILE each finding is about, as `locations[0]`.
+ *
+ * The step and tag grades carry no `locations` of their own, so `findingJson`
+ * fell back to the target's scope — `services/<tree>` and nothing else — and an
+ * agent reading `--json`, which is the reason the envelope exists, had to parse
+ * the prose to learn which `.likec4` to open. `usecase.flow-invalid` on this
+ * same arm already names its file; these say the file the same way, with the
+ * service directory kept beside it as `scope` (`../spine.ts`'s shape).
+ */
+function atView(scope, view, findings) {
+    const file = view.sourcePath === undefined ? `${scope.treePath}/` : `${scope.treePath}/${view.sourcePath}`;
+    return findings.map((finding) => finding.locations === undefined
+        ? {
+            ...finding,
+            locations: [
+                { path: file, role: "primary" },
+                { path: scope.treePath, role: "scope" },
+            ],
+        }
+        : finding);
+}
+/**
+ * Every use-case finding a service's own project earns.
+ *
+ * Views are sorted by (file, view id) for the fleet grader's reason: nothing in
+ * loam has measured that the parse preserves declaration order, and a report
+ * whose row order depends on it would reorder under a dependency bump.
+ */
+export function serviceUseCaseFindings(scope) {
+    const { scan } = scope;
+    if (scan.kind === "none")
+        return [];
+    if (scan.kind === "unreadable")
+        return [flowInvalidFinding(scope, scan.errors)];
+    const place = (view) => servicePlace(scope, view);
+    const grading = {
+        model: scan.model,
+        services: scope.services,
+        // Built over the PROJECT's elements with the fleet set, exactly as the
+        // attribution's own fallback tier resolves — so "which service is this
+        // container" cannot be answered one way by `attributeStep` and another by
+        // the provider guard.
+        resolve: serviceResolver(scan.model.elements, scan.model.known),
+        place,
+    };
+    const findings = [];
+    const views = [...scan.views].sort((a, b) => compareIds(a.sourcePath ?? "", b.sourcePath ?? "") || compareIds(a.id, b.id));
+    for (const view of views) {
+        const forView = [...serviceTagFindings(view, scope, place(view))];
+        for (const step of view.steps)
+            forView.push(...stepFindings({ view, step }, grading));
+        findings.push(...atView(scope, view, forView));
+    }
+    return findings;
+}
+/**
+ * The `Requirement-ID`s a service-local `#req-` tag may name: every identified
+ * requirement of spec.md (living — a REMOVED one is on its way out and keeps no
+ * promise) and of arch.spec.md, as ONE set. `undefined` when NEITHER document
+ * exists, which the tag grade reads as "no requirement to satisfy" rather than
+ * "none flattening to this slug" — the same two answers the fleet's
+ * `requirementsOf` gives for a capability with no document at all.
+ *
+ * An id both documents declare resolves once (a set dedupes it); two ids that
+ * merely flatten alike — `PAY.AUTH` in one file, `PAY-AUTH` in the other — are
+ * the `many` arm, because a Requirement-ID is unique inside one document and a
+ * flow beside the model has two.
+ *
+ * It lives beside the grade it feeds rather than in `../service.ts`, which is
+ * the ORDER and nothing else: the set is this axis's input, its two answers are
+ * this axis's vocabulary, and the order module had grown past its line limit
+ * carrying it.
+ */
+export function requirementIdsOf(paths, livingReqs, archReqs) {
+    if (!existsSync(paths.spec) && !existsSync(paths.archSpec))
+        return undefined;
+    const ids = new Set();
+    for (const req of [...livingReqs, ...archReqs.filter((r) => r.kind !== "REMOVED")]) {
+        if (req.id !== undefined)
+            ids.add(req.id);
+    }
+    return ids;
+}
+//# sourceMappingURL=usecases.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usecases.js","sourceRoot":"","sources":["../../../../../src/commands/validate/service/usecases/usecases.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The use-case axis of the SERVICE target: the `dynamic view`s a service's own\n * LikeC4 project declares, graded as the hop sequences behind its requirements.\n *\n * The fleet target grades flows drawn over the map (`core/usecases/grade/`);\n * this grades flows drawn over ONE service's containers, which only that\n * service's project can resolve — the whole reason the slot exists\n * (`core/usecases/service/flows.ts` carries the report). The step grades are\n * the fleet's own `stepFindings`, reused with the service's project as the\n * model, the enumerated fleet as `services`, and one injection: where a\n * finding says the view is. A second verdict→code mapping here would be the\n * drift that package's banner forbids.\n *\n * ONLY VIEWS CARRYING A RESERVED TAG ARE GRADED, as at fleet altitude and for\n * the same reason: a service's `views.likec4` full of hand-drawn diagrams must\n * not turn red on upgrade. The reader applies the opt-in; this module never\n * sees an untagged view. Graded is narrower than LOADED, and the difference is\n * the reader's gate (`core/usecases/service/flows.ts`): an untagged sibling is\n * not even loaded while no view in the project opts in and no sibling mentions\n * a reserved prefix anywhere in its bytes — but once a view in\n * model.likec4 itself opts in, or a sibling mentions `req-`, `cap-` or `suite-`\n * in a comment or a title, every sibling is staged, and a project that does not\n * read is one `usecase.flow-invalid` whether or not any view in it opted in.\n *\n * A SIBLING THAT BREAKS THE PROJECT is ONE `usecase.flow-invalid` — reused,\n * because its meaning is exactly this (\"loam could not read the flows against\n * the map they are drawn over, so it graded none of them, and the renderer\n * refuses the same project\") applied to the service project instead of the\n * merge preview — and NEVER `c4.invalid`: that code means \"model.likec4 does\n * not parse, every model check is suspended\", and here the model parses and\n * every model check RAN. Reusing it would tell an agent to fix the wrong file\n * and tell the brief's `checks[]` row (\"every other check stops here\") a lie.\n */\nimport { existsSync } from \"node:fs\";\nimport { relative } from \"node:path\";\nimport type { LikeC4Error } from \"../../../../core/c4/likec4.js\";\nimport type { Requirement } from \"../../../../core/document/spec.js\";\nimport type { ServicePaths } from \"../../../../core/repo/paths.js\";\nimport type { ParsedView } from \"../../../../core/c4/parsed/dynamic-views.js\";\nimport { serviceResolver } from \"../../../../core/c4/resolve/service.js\";\nimport type { DocsDir } from \"../../../../core/kernel/ids/dirs.js\";\nimport { compareIds } from \"../../../../core/repo/entries.js\";\nimport type { ServiceFlowScan } from \"../../../../core/usecases/service/flows.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { errorText } from \"../../../../core/c4/likec4.js\";\nimport { CAP_TAG_PREFIX, REQ_TAG_PREFIX } from \"../../../../core/capabilities/usecase-join.js\";\nimport { stepFindings, type StepGrading } from \"../../../../core/usecases/grade/steps.js\";\nimport { serviceTagFindings, type ServiceTagScope } from \"./tags.js\";\n\n/** What the service's use-case grades run over. */\nexport interface ServiceUseCaseScope extends ServiceTagScope {\n  /** The docs root, so a project error's absolute path can be spelled repo-relative. */\n  docsDir: DocsDir;\n  scan: ServiceFlowScan;\n  /**\n   * The `services/<id>/` directories that exist — the SAME enumerated set the\n   * fleet target hands `stepFindings`, never an empty one: `StepGrading`\n   * documents why the intra-service exemption is a guard and not a scope.\n   */\n  services: ReadonlySet<string>;\n}\n\n/** `<svc>: services/<tree>/<file> — dynamic view '<id>'` — the service target's spelling of `viewPlace`. */\nfunction servicePlace(scope: ServiceUseCaseScope, view: ParsedView): string {\n  // An absent `sourcePath` names the directory rather than guessing a file,\n  // for `viewFile`'s reason; nothing at the 1.59.2 pin reaches that arm.\n  return `${scope.service}: ${scope.treePath}/${view.sourcePath ?? \"\"} — dynamic view '${view.id}'`;\n}\n\n/** The repo-relative spelling of a project error's document, or the whole project when it carries none. */\nfunction fileOf(scope: ServiceUseCaseScope, error: LikeC4Error): string {\n  return error.sourceFsPath === undefined\n    ? `${scope.treePath}/`\n    : relative(scope.docsDir, error.sourceFsPath).split(/[\\\\/]/).join(\"/\");\n}\n\n/**\n * The one finding a broken project earns. `details` is one `errorText` line\n * per error, each prefixed by its file, because the project may hold several\n * siblings and the fault may sit in any of them — including `model.likec4`\n * itself when a sibling re-declares its `specification` block, an error LikeC4\n * blames on both files. `locations` names the first broken file, in the sorted\n * order the reader produced.\n */\nfunction flowInvalidFinding(scope: ServiceUseCaseScope, errors: readonly LikeC4Error[]): Finding {\n  const files = [...new Set(errors.map((error) => fileOf(scope, error)))];\n  const [first = `${scope.treePath}/`, ...others] = files;\n  const named = others.length === 0 ? first : `${first} and ${others.length} more file(s)`;\n  return {\n    severity: \"error\",\n    code: \"usecase.flow-invalid\",\n    subject: scope.service,\n    message:\n      `${scope.service}: ${named} has ${errors.length} error(s) — every .likec4 beside model.likec4 is one LikeC4 ` +\n      \"project, read the way the renderer reads it, and the renderer refuses the whole project over one broken \" +\n      \"file; no flow in it was graded. model.likec4 itself parses and is graded alone.\",\n    // The hint first, for `c4.invalid`'s reason (`../model/grade.ts`):\n    // `capDetails` keeps ten lines, one broken document can carry more than ten\n    // errors, and a diagnosis appended after them is dropped exactly when the\n    // reader needs it.\n    details: [...tagHint(errors), ...errors.map((error) => `${fileOf(scope, error)}: ${errorText(error)}`)],\n    locations: [{ path: first, role: \"primary\" }],\n  };\n}\n\n/** `Could not resolve reference to Tag named '#req-PAY-AUTH'.` — measured at the 1.59.2 pin. */\nconst UNDECLARED_TAG = /reference to Tag named '#?([\\w.-]+)'/;\n\n/**\n * The one line an undeclared RESERVED tag earns.\n *\n * The opt-in is a tag, LikeC4 refuses a tag no `specification` declares, and the\n * refusal is a bare `Could not resolve reference to Tag named …` — so an author\n * following the protocol's \"tag the view `#req-<id>`\" got a parse error naming\n * the thing they had just been told to write, with nothing saying a tag must be\n * declared first (verification 2026-09-04, D10). One line, from the first such\n * error only: the second one has the same repair.\n */\nfunction tagHint(errors: readonly LikeC4Error[]): string[] {\n  for (const error of errors) {\n    const match = UNDECLARED_TAG.exec(error.message);\n    const name = match?.[1];\n    if (name === undefined) continue;\n    // `cap-` and `req-` do NOT share a repair here, and covering both with one\n    // hint sent an author two steps where one would do: declaring `tag cap-…`\n    // makes the file parse and the very next run says `usecase.capability-\n    // unresolved` — \"no capability can be claimed inside this service's own\n    // project. Drop the tag.\" A capability is claimed at fleet altitude, so the\n    // tag can never resolve to anything beside a model, whatever is declared\n    // (verification 2026-09-04).\n    if (name.startsWith(CAP_TAG_PREFIX)) {\n      return [\n        `\\`#${name}\\` claims a capability, and a capability is claimed at FLEET altitude only — a flow beside ` +\n          \"model.likec4 is read in this service's own project, where no capability can be resolved. Declaring \" +\n          `\\`tag ${name}\\` makes the file parse and earns \\`usecase.capability-unresolved\\` on the next run: ` +\n          `drop the tag, and tag the flow \\`#${REQ_TAG_PREFIX}<Requirement-ID>\\` instead, or draw it in ` +\n          \"`architecture/usecases/` where a capability tag belongs\",\n      ];\n    }\n    if (!name.startsWith(REQ_TAG_PREFIX)) continue;\n    return [\n      `declare \\`tag ${name}\\` in the \\`specification { }\\` block this project reads — model.likec4's own ` +\n        \"for a model that stands alone, the fleet map's for one that extends it (or a tags-only \" +\n        \"`specification` in a document beside the model)\",\n    ];\n  }\n  return [];\n}\n\n/**\n * The FILE each finding is about, as `locations[0]`.\n *\n * The step and tag grades carry no `locations` of their own, so `findingJson`\n * fell back to the target's scope — `services/<tree>` and nothing else — and an\n * agent reading `--json`, which is the reason the envelope exists, had to parse\n * the prose to learn which `.likec4` to open. `usecase.flow-invalid` on this\n * same arm already names its file; these say the file the same way, with the\n * service directory kept beside it as `scope` (`../spine.ts`'s shape).\n */\nfunction atView(scope: ServiceUseCaseScope, view: ParsedView, findings: Finding[]): Finding[] {\n  const file = view.sourcePath === undefined ? `${scope.treePath}/` : `${scope.treePath}/${view.sourcePath}`;\n  return findings.map((finding) =>\n    finding.locations === undefined\n      ? {\n          ...finding,\n          locations: [\n            { path: file, role: \"primary\" as const },\n            { path: scope.treePath, role: \"scope\" as const },\n          ],\n        }\n      : finding,\n  );\n}\n\n/**\n * Every use-case finding a service's own project earns.\n *\n * Views are sorted by (file, view id) for the fleet grader's reason: nothing in\n * loam has measured that the parse preserves declaration order, and a report\n * whose row order depends on it would reorder under a dependency bump.\n */\nexport function serviceUseCaseFindings(scope: ServiceUseCaseScope): Finding[] {\n  const { scan } = scope;\n  if (scan.kind === \"none\") return [];\n  if (scan.kind === \"unreadable\") return [flowInvalidFinding(scope, scan.errors)];\n\n  const place = (view: ParsedView): string => servicePlace(scope, view);\n  const grading: StepGrading = {\n    model: scan.model,\n    services: scope.services,\n    // Built over the PROJECT's elements with the fleet set, exactly as the\n    // attribution's own fallback tier resolves — so \"which service is this\n    // container\" cannot be answered one way by `attributeStep` and another by\n    // the provider guard.\n    resolve: serviceResolver(scan.model.elements, scan.model.known),\n    place,\n  };\n  const findings: Finding[] = [];\n  const views = [...scan.views].sort(\n    (a, b) => compareIds(a.sourcePath ?? \"\", b.sourcePath ?? \"\") || compareIds(a.id, b.id),\n  );\n  for (const view of views) {\n    const forView: Finding[] = [...serviceTagFindings(view, scope, place(view))];\n    for (const step of view.steps) forView.push(...stepFindings({ view, step }, grading));\n    findings.push(...atView(scope, view, forView));\n  }\n  return findings;\n}\n\n/**\n * The `Requirement-ID`s a service-local `#req-` tag may name: every identified\n * requirement of spec.md (living — a REMOVED one is on its way out and keeps no\n * promise) and of arch.spec.md, as ONE set. `undefined` when NEITHER document\n * exists, which the tag grade reads as \"no requirement to satisfy\" rather than\n * \"none flattening to this slug\" — the same two answers the fleet's\n * `requirementsOf` gives for a capability with no document at all.\n *\n * An id both documents declare resolves once (a set dedupes it); two ids that\n * merely flatten alike — `PAY.AUTH` in one file, `PAY-AUTH` in the other — are\n * the `many` arm, because a Requirement-ID is unique inside one document and a\n * flow beside the model has two.\n *\n * It lives beside the grade it feeds rather than in `../service.ts`, which is\n * the ORDER and nothing else: the set is this axis's input, its two answers are\n * this axis's vocabulary, and the order module had grown past its line limit\n * carrying it.\n */\nexport function requirementIdsOf(\n  paths: ServicePaths,\n  livingReqs: readonly Requirement[],\n  archReqs: readonly Requirement[],\n): ReadonlySet<string> | undefined {\n  if (!existsSync(paths.spec) && !existsSync(paths.archSpec)) return undefined;\n  const ids = new Set<string>();\n  for (const req of [...livingReqs, ...archReqs.filter((r) => r.kind !== \"REMOVED\")]) {\n    if (req.id !== undefined) ids.add(req.id);\n  }\n  return ids;\n}\n"]}