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

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

@@ -0,0 +1,353 @@
+/**
+ * The fleet target: `services/` and architecture/landscape.likec4 graded
+ * against each other, plus the two exemptions that decide which drawn element
+ * answers for a service directory at all.
+ *
+ * The landscape is the one artifact no service owns — parsed once for the whole
+ * run and graded on a target of its own, outside the dispatcher's `guarded`.
+ * That is why its IO containment lives in this package instead: see
+ * `unreadableLandscape` in `./load.ts`.
+ */
+import { existsSync } from "node:fs";
+import { relative } from "node:path";
+import { readFile } from "node:fs/promises";
+import { loadFile } from "../../../core/c4/likec4.js";
+import { elementService, serviceResolver } from "../../../core/c4/resolve/service.js";
+import { landscapePath as landscapeFile } from "../../../core/repo/paths.js";
+import { serviceIdFindings } from "../../../core/repo/entries.js";
+import { listFleetTree, listServices } from "../../../core/repo/repo.js";
+import {} from "../../../core/vocabulary/report.js";
+import { landscapeConflictFinding } from "../../../core/conflict-markers.js";
+import { FleetContext } from "../../../core/fleet-context.js";
+import { capabilityFleetFindings, fleetShapeFindings, permissionFindings } from "../checks/fleet-shape.js";
+import { fleetLinkFindings } from "../links/corpus.js";
+import { glossaryFindings } from "../links/glossary.js";
+import { obligationFindings, obligationVocabularyFindings } from "./obligations.js";
+import { readObligations } from "../../../core/obligations/obligations.js";
+import { obligationsPath } from "../../../core/repo/paths.js";
+import { EXTERNAL_TAG } from "../../../core/vocabulary/maturity.js";
+import { errorText } from "../checks/vocabulary.js";
+import { serviceTreePath } from "../../../core/kernel/ids/dirs.js";
+import { drawnSystems, serviceLevelElements } from "./census.js";
+import { unreadableLandscape } from "./load.js";
+import { kindTagFindings } from "./kind-tags.js";
+import { useCaseFindings } from "./usecases/usecases.js";
+import { viewIdFindings } from "./views/ids.js";
+import { viewsStaleFindings } from "./views/stale.js";
+import { readCapabilityVocabulary } from "../../../core/capabilities/capabilities.js";
+import { capabilityRequirementIndex, gradableCapabilityIds } from "../../../core/capabilities/findings.js";
+import { parseRequirements, readRequirementsDocument } from "../../../core/document/parse.js";
+import { isUseCase } from "../../../core/usecases/fleet.js";
+/**
+ * The fleet's flows as a grade may read them, or `null` when loam cannot see
+ * them at all — the same `null`-suspends idiom `gradableCapabilityIds` uses,
+ * and here it guards one specific wrong answer.
+ *
+ * `capability.requirement-unrealized` says a business promise is kept by
+ * nobody. A use case is one of the two things that can keep it, so a run that
+ * could not read the flows must not make that claim: no preload (a single-target
+ * run) and a project that did not parse are both "loam did not look", never
+ * "there is nothing there". A preload that DID parse and declares no views is a
+ * real, empty answer and grades normally.
+ *
+ * Filtered through `isUseCase` — the same opt-in `readUseCases` applies before
+ * `loam list capabilities` asks this question — because the two surfaces must
+ * never disagree about `keptBy`. Handing the unfiltered preload over was
+ * harmless only by luck: an untagged view yields no claims, so the answers
+ * matched for want of an input that could tell them apart. A `#req-`-only view
+ * is exactly that input.
+ */
+function gradableFlows(preloaded) {
+    if (preloaded === null || preloaded === undefined || preloaded.errors.length > 0)
+        return null;
+    return (preloaded.views ?? []).filter(isUseCase);
+}
+/**
+ * The fleet cross-check: `services/` and the landscape both claim to name the
+ * fleet, and nothing used to compare them. A directory nobody drew and an element
+ * with nothing behind it were equally invisible.
+ *
+ * The two directions are graded differently because the evidence differs. A
+ * directory that exists is a fact, so a landscape missing it is an error — every
+ * view derived from that landscape is then incomplete. An element with no
+ * directory may legitimately be someone else's system, so it warns, and
+ * `#external` says "deliberately not ours" and silences it. An explicit
+ * `metadata { service '<id>' }` naming nothing is an error either way: a binding
+ * is a claim about this repo, not a guess at one.
+ *
+ * An ABSENT landscape is a finding, not a skipped check. It used to return null
+ * — no target, no findings, and a fleet gate that went green over a docs repo
+ * with no fleet map at all, which is the single artifact every derived view and
+ * every spine check is computed from. It is graded by what its absence proves:
+ * with services in `services/` it is an ERROR (a fleet that exists is undrawn),
+ * with none it is a WARNING (a docs repo before its first adopt legitimately
+ * has nothing to draw, but the file still belongs there — `loam init` scaffolds
+ * it, and a repo missing it will silently accept never getting one).
+ *
+ * `preloaded` is the already-parsed landscape under --all — the same doc every
+ * service check gets.
+ */
+export async function validateLandscape(docsDir, preloaded, fleet) {
+    const path = landscapeFile(docsDir);
+    const findings = [];
+    const report = {
+        kind: "landscape",
+        id: "landscape",
+        path: "architecture/landscape.likec4",
+        findings,
+    };
+    // The SET of service directories is this target's other subject, so it is
+    // graded before the map is even opened: `service.id-invalid` is a fact about
+    // `services/` that holds whether or not a landscape exists or parses, and
+    // both of those return early below. Emitted here and nowhere else — the
+    // enumeration is what makes the id a question, and one finding per fleet is
+    // what the rename fixes.
+    const entries = await listServices(docsDir, fleet);
+    findings.push(...serviceIdFindings(entries));
+    // The tree walk's own findings ride the same fleet target, before the map's
+    // early returns for the same reason `service.id-invalid` does: a stranded,
+    // colliding or mismarked directory is a fact about `services/` that holds
+    // whether or not a landscape exists or parses — and a broken tree must make
+    // the fleet gate refuse while still naming every service it found.
+    const tree = await listFleetTree(docsDir, fleet);
+    findings.push(...tree.findings);
+    // Before the landscape's own early returns: the authorization and capability
+    // vocabularies are fleet facts that do not depend on the map existing or parsing.
+    findings.push(...(await permissionFindings(docsDir, entries, fleet)));
+    findings.push(...(await capabilityFleetFindings(docsDir, entries, fleet, gradableFlows(preloaded))));
+    // The documents that belong to no service and no feature — the fleet's ADRs
+    // and the living capability tree — are graded for their links here, once,
+    // for the same reason the two vocabularies above are: a fleet fact repeated
+    // on every service target is the report.
+    findings.push(...(await fleetLinkFindings({ docsDir, fleet })));
+    // The glossary is graded on who cites it, which is a question only the whole
+    // repository answers — so it belongs here, beside the two vocabularies, and
+    // nowhere else.
+    findings.push(...(await glossaryFindings(docsDir, fleet)));
+    // The architectural obligation vocabulary, read ONCE here and handed to the
+    // map half below: its own two verdicts hold whether or not the landscape
+    // exists or parses, and a run where somebody is fixing the map must still be
+    // told that this file does not read.
+    const obligations = await readObligations(obligationsPath(docsDir));
+    findings.push(...obligationVocabularyFindings(docsDir, obligations));
+    if (!existsSync(path)) {
+        const count = entries.length;
+        findings.push({
+            severity: count > 0 ? "error" : "warn",
+            code: "landscape.missing",
+            message: `landscape: architecture/landscape.likec4 does not exist — ` +
+                (count > 0
+                    ? `${count} service(s) are adopted and nothing draws the fleet. `
+                    : "nothing draws the fleet. ") +
+                "It is the one map every derived view and the C4↔API spine are computed from: " +
+                "write a `specification { element softwareSystem }` + `model { … }` document there " +
+                "with one element per services/<id>/, bound with `metadata { service '<id>' }`.",
+        });
+        return report;
+    }
+    // Conflict markers before the parse — `loam doctor`'s order, and for its
+    // reason: the markers are the cause and the parse errors are the cascade.
+    // Nothing may be concluded from a file that is two halves of two different
+    // maps, least of all that a service nobody drew is unmodelled, so this
+    // returns the way `landscape.invalid` does. An error, gating by the default
+    // rule and deliberately not carrying `gates` — that field is coherence's,
+    // and the archive gate has to ask this question itself (it does not yet).
+    // Read plainly rather than through FleetContext: this target runs outside
+    // `guarded`, and a document refused for its encoding would surface here as
+    // the whole run's `repository-unavailable` instead of one finding.
+    //
+    // Both reads are contained for that same reason — see `unreadableLandscape`.
+    // The conflict-marker read is the FIRST touch of the file, so it is the one
+    // that fails when the file cannot be opened at all, and it runs before
+    // `preloaded ??` can spare it.
+    let land;
+    try {
+        const conflict = landscapeConflictFinding("architecture/landscape.likec4", await readFile(path, "utf8"));
+        if (conflict !== null) {
+            findings.push(conflict);
+            return report;
+        }
+        land = preloaded ?? (fleet === undefined ? await loadFile(path) : await fleet.loadLikeC4(path));
+    }
+    catch (err) {
+        land = unreadableLandscape(err);
+    }
+    if (land.errors.length > 0) {
+        // Nothing may be concluded from a document that did not parse — in particular
+        // not that every service is unmodelled.
+        //
+        // The fleet map is a PROJECT now, not a file: `architecture/landscape.likec4`
+        // plus every `architecture/usecases/*.likec4`, merged the way the renderer
+        // merges them. So the message names the FILES that broke rather than the
+        // landscape by default — a use case with a typo'd element used to be
+        // reported as the landscape having errors, which sent the author to the
+        // wrong file with a line number that pointed at somebody else's text.
+        const broken = [...new Set(land.errors.map((e) => e.sourceFsPath).filter((p) => p !== undefined))];
+        const spell = (abs) => relative(docsDir, abs).split(/[\\/]/).join("/");
+        const named = broken.length === 0 ? "architecture/landscape.likec4" : broken.map(spell).sort().join(", ");
+        findings.push({
+            severity: "error",
+            code: "landscape.invalid",
+            message: `landscape: ${named} has ${land.errors.length} error(s) — cross-check with services/ impossible`,
+            // Every line carries its own file, because one project's errors can come
+            // from more than one document and a bare `L8:` is unactionable then.
+            details: land.errors.map((e) => e.sourceFsPath === undefined || broken.length < 2 ? errorText(e) : `${spell(e.sourceFsPath)} ${errorText(e)}`),
+        });
+        return report;
+    }
+    // The generated subsystem views, graded only now that the landscape has
+    // parsed: the expected bytes are a function of (tree, landscape elements) —
+    // `views/stale.ts` says why a byte compare and why exactly one finding.
+    findings.push(...(await viewsStaleFindings(docsDir, tree, land.elements)));
+    // Beside staleness, and for the same file: an authored view id that collides
+    // with one loam mints into it takes the whole architecture/ project down in
+    // the renderer while every check here stays green — see views/ids.ts.
+    findings.push(...viewIdFindings(land.viewIds, tree));
+    // The three obligation questions that need the map — where each declared rule
+    // is applied, which tags resolve to nothing, and which applications no living
+    // arch requirement covers. Here rather than beside the vocabulary above
+    // because all three are about the parsed landscape, and `land` is only
+    // trustworthy past this point.
+    findings.push(...(await obligationFindings({ docsDir, vocabulary: obligations, land, services: entries, fleet })));
+    const services = new Set(entries.map((s) => s.id));
+    // Where each service actually sits, for every finding below that names a
+    // directory a reader is meant to open. `services/<id>/` is right only for an
+    // unfiled fleet; a filed service lives at `services/<subsystem>/…/<id>/`, and
+    // a finding pointing at the root form sends the fix to a path that does not
+    // exist. Built once here because three checks below need the same answer.
+    const pathOf = (id) => {
+        const entry = entries.find((s) => s.id === id);
+        return entry === undefined ? `services/${id}` : serviceTreePath(entry);
+    };
+    // Ahead of every exemption below, because it is the one defect that can make
+    // all of them lie at once: a tag loam grades on, declared on a KIND, landing
+    // on an element that stands for one of our own directories — see kind-tags.ts.
+    findings.push(...kindTagFindings({ specification: land.specification, elements: land.elements, services }));
+    const drawn = serviceLevelElements(land.elements, services);
+    // Which services the landscape models, answered by the same resolver every
+    // edge join uses — so "modelled" here and "inbound edge" in the spine check
+    // can never disagree about what an element stands for.
+    const landSvcOf = serviceResolver(land.elements, services);
+    const modelled = new Set(land.elements.map((e) => landSvcOf(e.id)));
+    // Two boxes standing for one service directory. Every join in loam is
+    // `element -> service`, computed by picking the FIRST element that resolves —
+    // so with two of them, which one wins is readdir order, and the edges of the
+    // loser are attributed to a service they do not belong to. Silent until now,
+    // and unfixable by staring at either element on its own.
+    const perService = new Map();
+    for (const e of drawn) {
+        if (e.tags.includes(EXTERNAL_TAG))
+            continue;
+        const id = elementService(e);
+        perService.set(id, [...(perService.get(id) ?? []), e]);
+    }
+    for (const [id, elems] of perService) {
+        if (elems.length < 2)
+            continue;
+        // A collision only matters where it decides something: a real directory to
+        // attribute to, or a binding somebody wrote down on purpose.
+        if (!services.has(id) && !elems.some((e) => e.service !== undefined))
+            continue;
+        findings.push({
+            severity: "warn",
+            code: "landscape.binding-duplicate",
+            subject: id,
+            message: `landscape: ${elems.length} elements resolve to service '${id}' (${elems.map((e) => e.id).join(", ")}) — every element→service join picks one of them arbitrarily, so the others' edges are filed under a service that does not own them; keep one element per services/<id>/`,
+        });
+    }
+    for (const id of services) {
+        if (modelled.has(id))
+            continue;
+        findings.push({
+            severity: "error",
+            code: "landscape.service-unmodelled",
+            subject: id,
+            message: `landscape: ${pathOf(id)}/ exists but nothing in architecture/landscape.likec4 models it — add an element, or bind one with metadata { service '${id}' }`,
+        });
+    }
+    // A binding is a claim about this repo wherever it is written — including
+    // inside another element, which the old top-level filter never looked at, so
+    // a typo one level down bound an edge to a service that does not exist and
+    // nothing said so. Every element with a binding answers for it, at any depth.
+    for (const e of land.elements) {
+        if (e.tags.includes(EXTERNAL_TAG) || e.service === undefined)
+            continue;
+        if (services.has(e.service))
+            continue;
+        findings.push({
+            severity: "error",
+            code: "landscape.binding-unknown",
+            subject: e.service,
+            message: `landscape: '${e.title}' binds to service '${e.service}', but services/${e.service}/ does not exist`,
+        });
+    }
+    // Walked over the SYSTEM census — the same derivation the scorecard counts,
+    // so the map's exemptions and the fleet rollup cannot drift — with the two
+    // residual skips that are not exemptions: a bound element is the binding
+    // pass's subject above, and a title naming a real directory is documented.
+    for (const e of drawnSystems(land.elements, services)) {
+        if (e.service !== undefined)
+            continue; // graded by the binding pass above
+        if (services.has(e.title))
+            continue;
+        findings.push({
+            severity: "warn",
+            code: "landscape.service-undocumented",
+            subject: e.title,
+            message: `landscape: '${e.title}' has no services/${e.title}/ — bind it with metadata { service '<id>' }, or tag it #${EXTERNAL_TAG} if it is not ours`,
+        });
+    }
+    // The shape advisories run LAST, over the same drawn set and resolver the
+    // structural checks used. Any one of them suppresses `landscape.matched`
+    // below on purpose: a map with a shape warning did not fully "agree".
+    findings.push(...fleetShapeFindings({ drawn, relationships: land.relationships, services, resolve: landSvcOf, pathOf }));
+    // The use cases the SAME `architecture/` project declares — every
+    // `dynamic view` in the landscape and in every `architecture/usecases/*.likec4`
+    // — graded against the model above (usecases/usecases.ts owns the opt-in and
+    // the grades). They ride this target for `viewsStaleFindings`' reason: a view
+    // belongs to no service, and only the fleet run has both the whole model and
+    // the enumerated `services/` in view at once.
+    //
+    // The views come from `preloaded` rather than from `land`, and that is the
+    // file-naming rule made mechanical instead of remembered: only the PROJECT
+    // load gives a view the `sourcePath` a finding has to name, while the
+    // single-file fallback a few lines above calls every document `source.c4` —
+    // so a message built from that load would send its reader to
+    // `architecture/source.c4`, a file that has never existed. No preload, no
+    // grading, and nothing to get wrong.
+    //
+    // Read second, and the ladder APPLIED BY ITS OWN FUNCTION rather than
+    // re-spelled here: an absent or unreadable capabilities.yaml means silence for
+    // the whole family, not a fleet full of unresolved tags, so `null` travels
+    // rather than an empty list — which the join would read as "the fleet declares
+    // no capabilities" and grade every tag against. `gradableCapabilityIds` is the
+    // one statement of that rule (`core/capabilities/findings.ts`), and this is a
+    // caller of it precisely so a fourth un-gradable vocabulary state cannot be
+    // fixed in core while the command layer keeps handing the join a whole key set.
+    // `capabilityFleetFindings` above has already paid for this read through the
+    // fleet context's memo.
+    const vocabulary = fleet === undefined ? await readCapabilityVocabulary(docsDir) : await fleet.capabilities(docsDir);
+    // The requirement index behind the `#req-` tag, read here rather than inside
+    // the use-case package so that package never learns what a capability
+    // document is. Under `--all` every document was already parsed by
+    // `capabilityFleetFindings` above and the fleet memo answers from cache.
+    const capabilityReqs = await capabilityRequirementIndex(vocabulary, fleet === undefined ? async (p) => parseRequirements(await readRequirementsDocument(p)) : (p) => fleet.readRequirements(p));
+    findings.push(...useCaseFindings({
+        views: preloaded?.views ?? [],
+        elements: land.elements,
+        relationships: land.relationships,
+        services,
+        resolve: landSvcOf,
+        capabilities: gradableCapabilityIds(vocabulary),
+        requirementsOf: (capability) => capabilityReqs.byCapability.get(capability),
+    }));
+    if (findings.length === 0) {
+        findings.push({
+            severity: "ok",
+            code: "landscape.matched",
+            message: `landscape: ${services.size} service(s) modelled — architecture/landscape.likec4 and services/ agree`,
+        });
+    }
+    return report;
+}
+//# sourceMappingURL=landscape.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"landscape.js","sourceRoot":"","sources":["../../../../src/commands/validate/fleet/landscape.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet target: `services/` and architecture/landscape.likec4 graded\n * against each other, plus the two exemptions that decide which drawn element\n * answers for a service directory at all.\n *\n * The landscape is the one artifact no service owns — parsed once for the whole\n * run and graded on a target of its own, outside the dispatcher's `guarded`.\n * That is why its IO containment lives in this package instead: see\n * `unreadableLandscape` in `./load.ts`.\n */\nimport { existsSync } from \"node:fs\";\nimport { relative } from \"node:path\";\nimport { readFile } from \"node:fs/promises\";\nimport { loadFile, type Elem, type LoadedDoc } from \"../../../core/c4/likec4.js\";\nimport { elementService, serviceResolver } from \"../../../core/c4/resolve/service.js\";\nimport { landscapePath as landscapeFile } from \"../../../core/repo/paths.js\";\nimport { serviceIdFindings } from \"../../../core/repo/entries.js\";\nimport { listFleetTree, listServices } from \"../../../core/repo/repo.js\";\nimport { type Finding, type TargetReport } from \"../../../core/vocabulary/report.js\";\nimport { landscapeConflictFinding } from \"../../../core/conflict-markers.js\";\nimport { FleetContext } from \"../../../core/fleet-context.js\";\nimport { capabilityFleetFindings, fleetShapeFindings, permissionFindings } from \"../checks/fleet-shape.js\";\nimport { fleetLinkFindings } from \"../links/corpus.js\";\nimport { glossaryFindings } from \"../links/glossary.js\";\nimport { obligationFindings, obligationVocabularyFindings } from \"./obligations.js\";\nimport { readObligations } from \"../../../core/obligations/obligations.js\";\nimport { obligationsPath } from \"../../../core/repo/paths.js\";\nimport { EXTERNAL_TAG } from \"../../../core/vocabulary/maturity.js\";\nimport { errorText } from \"../checks/vocabulary.js\";\nimport { serviceTreePath, type DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { drawnSystems, serviceLevelElements } from \"./census.js\";\nimport { unreadableLandscape } from \"./load.js\";\nimport { kindTagFindings } from \"./kind-tags.js\";\nimport { useCaseFindings } from \"./usecases/usecases.js\";\nimport { viewIdFindings } from \"./views/ids.js\";\nimport { viewsStaleFindings } from \"./views/stale.js\";\nimport { readCapabilityVocabulary } from \"../../../core/capabilities/capabilities.js\";\nimport { capabilityRequirementIndex, gradableCapabilityIds } from \"../../../core/capabilities/findings.js\";\nimport { parseRequirements, readRequirementsDocument } from \"../../../core/document/parse.js\";\nimport type { ParsedView } from \"../../../core/c4/parsed/dynamic-views.js\";\nimport { isUseCase } from \"../../../core/usecases/fleet.js\";\n\n/**\n * The fleet's flows as a grade may read them, or `null` when loam cannot see\n * them at all — the same `null`-suspends idiom `gradableCapabilityIds` uses,\n * and here it guards one specific wrong answer.\n *\n * `capability.requirement-unrealized` says a business promise is kept by\n * nobody. A use case is one of the two things that can keep it, so a run that\n * could not read the flows must not make that claim: no preload (a single-target\n * run) and a project that did not parse are both \"loam did not look\", never\n * \"there is nothing there\". A preload that DID parse and declares no views is a\n * real, empty answer and grades normally.\n *\n * Filtered through `isUseCase` — the same opt-in `readUseCases` applies before\n * `loam list capabilities` asks this question — because the two surfaces must\n * never disagree about `keptBy`. Handing the unfiltered preload over was\n * harmless only by luck: an untagged view yields no claims, so the answers\n * matched for want of an input that could tell them apart. A `#req-`-only view\n * is exactly that input.\n */\nfunction gradableFlows(preloaded: LoadedDoc | null | undefined): readonly ParsedView[] | null {\n  if (preloaded === null || preloaded === undefined || preloaded.errors.length > 0) return null;\n  return (preloaded.views ?? []).filter(isUseCase);\n}\n\n/**\n * The fleet cross-check: `services/` and the landscape both claim to name the\n * fleet, and nothing used to compare them. A directory nobody drew and an element\n * with nothing behind it were equally invisible.\n *\n * The two directions are graded differently because the evidence differs. A\n * directory that exists is a fact, so a landscape missing it is an error — every\n * view derived from that landscape is then incomplete. An element with no\n * directory may legitimately be someone else's system, so it warns, and\n * `#external` says \"deliberately not ours\" and silences it. An explicit\n * `metadata { service '<id>' }` naming nothing is an error either way: a binding\n * is a claim about this repo, not a guess at one.\n *\n * An ABSENT landscape is a finding, not a skipped check. It used to return null\n * — no target, no findings, and a fleet gate that went green over a docs repo\n * with no fleet map at all, which is the single artifact every derived view and\n * every spine check is computed from. It is graded by what its absence proves:\n * with services in `services/` it is an ERROR (a fleet that exists is undrawn),\n * with none it is a WARNING (a docs repo before its first adopt legitimately\n * has nothing to draw, but the file still belongs there — `loam init` scaffolds\n * it, and a repo missing it will silently accept never getting one).\n *\n * `preloaded` is the already-parsed landscape under --all — the same doc every\n * service check gets.\n */\nexport async function validateLandscape(\n  docsDir: DocsDir,\n  preloaded?: LoadedDoc | null,\n  fleet?: FleetContext,\n): Promise<TargetReport> {\n  const path = landscapeFile(docsDir);\n  const findings: Finding[] = [];\n  const report: TargetReport = {\n    kind: \"landscape\",\n    id: \"landscape\",\n    path: \"architecture/landscape.likec4\",\n    findings,\n  };\n\n  // The SET of service directories is this target's other subject, so it is\n  // graded before the map is even opened: `service.id-invalid` is a fact about\n  // `services/` that holds whether or not a landscape exists or parses, and\n  // both of those return early below. Emitted here and nowhere else — the\n  // enumeration is what makes the id a question, and one finding per fleet is\n  // what the rename fixes.\n  const entries = await listServices(docsDir, fleet);\n  findings.push(...serviceIdFindings(entries));\n  // The tree walk's own findings ride the same fleet target, before the map's\n  // early returns for the same reason `service.id-invalid` does: a stranded,\n  // colliding or mismarked directory is a fact about `services/` that holds\n  // whether or not a landscape exists or parses — and a broken tree must make\n  // the fleet gate refuse while still naming every service it found.\n  const tree = await listFleetTree(docsDir, fleet);\n  findings.push(...tree.findings);\n  // Before the landscape's own early returns: the authorization and capability\n  // vocabularies are fleet facts that do not depend on the map existing or parsing.\n  findings.push(...(await permissionFindings(docsDir, entries, fleet)));\n  findings.push(...(await capabilityFleetFindings(docsDir, entries, fleet, gradableFlows(preloaded))));\n  // The documents that belong to no service and no feature — the fleet's ADRs\n  // and the living capability tree — are graded for their links here, once,\n  // for the same reason the two vocabularies above are: a fleet fact repeated\n  // on every service target is the report.\n  findings.push(...(await fleetLinkFindings({ docsDir, fleet })));\n  // The glossary is graded on who cites it, which is a question only the whole\n  // repository answers — so it belongs here, beside the two vocabularies, and\n  // nowhere else.\n  findings.push(...(await glossaryFindings(docsDir, fleet)));\n  // The architectural obligation vocabulary, read ONCE here and handed to the\n  // map half below: its own two verdicts hold whether or not the landscape\n  // exists or parses, and a run where somebody is fixing the map must still be\n  // told that this file does not read.\n  const obligations = await readObligations(obligationsPath(docsDir));\n  findings.push(...obligationVocabularyFindings(docsDir, obligations));\n\n  if (!existsSync(path)) {\n    const count = entries.length;\n    findings.push({\n      severity: count > 0 ? \"error\" : \"warn\",\n      code: \"landscape.missing\",\n      message:\n        `landscape: architecture/landscape.likec4 does not exist — ` +\n        (count > 0\n          ? `${count} service(s) are adopted and nothing draws the fleet. `\n          : \"nothing draws the fleet. \") +\n        \"It is the one map every derived view and the C4↔API spine are computed from: \" +\n        \"write a `specification { element softwareSystem }` + `model { … }` document there \" +\n        \"with one element per services/<id>/, bound with `metadata { service '<id>' }`.\",\n    });\n    return report;\n  }\n\n  // Conflict markers before the parse — `loam doctor`'s order, and for its\n  // reason: the markers are the cause and the parse errors are the cascade.\n  // Nothing may be concluded from a file that is two halves of two different\n  // maps, least of all that a service nobody drew is unmodelled, so this\n  // returns the way `landscape.invalid` does. An error, gating by the default\n  // rule and deliberately not carrying `gates` — that field is coherence's,\n  // and the archive gate has to ask this question itself (it does not yet).\n  // Read plainly rather than through FleetContext: this target runs outside\n  // `guarded`, and a document refused for its encoding would surface here as\n  // the whole run's `repository-unavailable` instead of one finding.\n  //\n  // Both reads are contained for that same reason — see `unreadableLandscape`.\n  // The conflict-marker read is the FIRST touch of the file, so it is the one\n  // that fails when the file cannot be opened at all, and it runs before\n  // `preloaded ??` can spare it.\n  let land: LoadedDoc;\n  try {\n    const conflict = landscapeConflictFinding(\n      \"architecture/landscape.likec4\",\n      await readFile(path, \"utf8\"),\n    );\n    if (conflict !== null) {\n      findings.push(conflict);\n      return report;\n    }\n    land = preloaded ?? (fleet === undefined ? await loadFile(path) : await fleet.loadLikeC4(path));\n  } catch (err) {\n    land = unreadableLandscape(err);\n  }\n  if (land.errors.length > 0) {\n    // Nothing may be concluded from a document that did not parse — in particular\n    // not that every service is unmodelled.\n    //\n    // The fleet map is a PROJECT now, not a file: `architecture/landscape.likec4`\n    // plus every `architecture/usecases/*.likec4`, merged the way the renderer\n    // merges them. So the message names the FILES that broke rather than the\n    // landscape by default — a use case with a typo'd element used to be\n    // reported as the landscape having errors, which sent the author to the\n    // wrong file with a line number that pointed at somebody else's text.\n    const broken = [...new Set(land.errors.map((e) => e.sourceFsPath).filter((p): p is string => p !== undefined))];\n    const spell = (abs: string): string => relative(docsDir, abs).split(/[\\\\/]/).join(\"/\");\n    const named = broken.length === 0 ? \"architecture/landscape.likec4\" : broken.map(spell).sort().join(\", \");\n    findings.push({\n      severity: \"error\",\n      code: \"landscape.invalid\",\n      message: `landscape: ${named} has ${land.errors.length} error(s) — cross-check with services/ impossible`,\n      // Every line carries its own file, because one project's errors can come\n      // from more than one document and a bare `L8:` is unactionable then.\n      details: land.errors.map((e) =>\n        e.sourceFsPath === undefined || broken.length < 2 ? errorText(e) : `${spell(e.sourceFsPath)} ${errorText(e)}`,\n      ),\n    });\n    return report;\n  }\n\n  // The generated subsystem views, graded only now that the landscape has\n  // parsed: the expected bytes are a function of (tree, landscape elements) —\n  // `views/stale.ts` says why a byte compare and why exactly one finding.\n  findings.push(...(await viewsStaleFindings(docsDir, tree, land.elements)));\n  // Beside staleness, and for the same file: an authored view id that collides\n  // with one loam mints into it takes the whole architecture/ project down in\n  // the renderer while every check here stays green — see views/ids.ts.\n  findings.push(...viewIdFindings(land.viewIds, tree));\n  // The three obligation questions that need the map — where each declared rule\n  // is applied, which tags resolve to nothing, and which applications no living\n  // arch requirement covers. Here rather than beside the vocabulary above\n  // because all three are about the parsed landscape, and `land` is only\n  // trustworthy past this point.\n  findings.push(...(await obligationFindings({ docsDir, vocabulary: obligations, land, services: entries, fleet })));\n\n  const services: ReadonlySet<string> = new Set(entries.map((s) => s.id));\n  // Where each service actually sits, for every finding below that names a\n  // directory a reader is meant to open. `services/<id>/` is right only for an\n  // unfiled fleet; a filed service lives at `services/<subsystem>/…/<id>/`, and\n  // a finding pointing at the root form sends the fix to a path that does not\n  // exist. Built once here because three checks below need the same answer.\n  const pathOf = (id: string): string => {\n    const entry = entries.find((s) => s.id === id);\n    return entry === undefined ? `services/${id}` : serviceTreePath(entry);\n  };\n  // Ahead of every exemption below, because it is the one defect that can make\n  // all of them lie at once: a tag loam grades on, declared on a KIND, landing\n  // on an element that stands for one of our own directories — see kind-tags.ts.\n  findings.push(...kindTagFindings({ specification: land.specification, elements: land.elements, services }));\n  const drawn = serviceLevelElements(land.elements, services);\n  // Which services the landscape models, answered by the same resolver every\n  // edge join uses — so \"modelled\" here and \"inbound edge\" in the spine check\n  // can never disagree about what an element stands for.\n  const landSvcOf = serviceResolver(land.elements, services);\n  const modelled: ReadonlySet<string> = new Set(land.elements.map((e) => landSvcOf(e.id)));\n\n  // Two boxes standing for one service directory. Every join in loam is\n  // `element -> service`, computed by picking the FIRST element that resolves —\n  // so with two of them, which one wins is readdir order, and the edges of the\n  // loser are attributed to a service they do not belong to. Silent until now,\n  // and unfixable by staring at either element on its own.\n  const perService = new Map<string, Elem[]>();\n  for (const e of drawn) {\n    if (e.tags.includes(EXTERNAL_TAG)) continue;\n    const id = elementService(e);\n    perService.set(id, [...(perService.get(id) ?? []), e]);\n  }\n  for (const [id, elems] of perService) {\n    if (elems.length < 2) continue;\n    // A collision only matters where it decides something: a real directory to\n    // attribute to, or a binding somebody wrote down on purpose.\n    if (!services.has(id) && !elems.some((e) => e.service !== undefined)) continue;\n    findings.push({\n      severity: \"warn\",\n      code: \"landscape.binding-duplicate\",\n      subject: id,\n      message: `landscape: ${elems.length} elements resolve to service '${id}' (${elems.map((e) => e.id).join(\", \")}) — every element→service join picks one of them arbitrarily, so the others' edges are filed under a service that does not own them; keep one element per services/<id>/`,\n    });\n  }\n\n  for (const id of services) {\n    if (modelled.has(id)) continue;\n    findings.push({\n      severity: \"error\",\n      code: \"landscape.service-unmodelled\",\n      subject: id,\n      message: `landscape: ${pathOf(id)}/ exists but nothing in architecture/landscape.likec4 models it — add an element, or bind one with metadata { service '${id}' }`,\n    });\n  }\n\n  // A binding is a claim about this repo wherever it is written — including\n  // inside another element, which the old top-level filter never looked at, so\n  // a typo one level down bound an edge to a service that does not exist and\n  // nothing said so. Every element with a binding answers for it, at any depth.\n  for (const e of land.elements) {\n    if (e.tags.includes(EXTERNAL_TAG) || e.service === undefined) continue;\n    if (services.has(e.service)) continue;\n    findings.push({\n      severity: \"error\",\n      code: \"landscape.binding-unknown\",\n      subject: e.service,\n      message: `landscape: '${e.title}' binds to service '${e.service}', but services/${e.service}/ does not exist`,\n    });\n  }\n\n  // Walked over the SYSTEM census — the same derivation the scorecard counts,\n  // so the map's exemptions and the fleet rollup cannot drift — with the two\n  // residual skips that are not exemptions: a bound element is the binding\n  // pass's subject above, and a title naming a real directory is documented.\n  for (const e of drawnSystems(land.elements, services)) {\n    if (e.service !== undefined) continue; // graded by the binding pass above\n    if (services.has(e.title)) continue;\n    findings.push({\n      severity: \"warn\",\n      code: \"landscape.service-undocumented\",\n      subject: e.title,\n      message: `landscape: '${e.title}' has no services/${e.title}/ — bind it with metadata { service '<id>' }, or tag it #${EXTERNAL_TAG} if it is not ours`,\n    });\n  }\n\n  // The shape advisories run LAST, over the same drawn set and resolver the\n  // structural checks used. Any one of them suppresses `landscape.matched`\n  // below on purpose: a map with a shape warning did not fully \"agree\".\n  findings.push(\n    ...fleetShapeFindings({ drawn, relationships: land.relationships, services, resolve: landSvcOf, pathOf }),\n  );\n\n  // The use cases the SAME `architecture/` project declares — every\n  // `dynamic view` in the landscape and in every `architecture/usecases/*.likec4`\n  // — graded against the model above (usecases/usecases.ts owns the opt-in and\n  // the grades). They ride this target for `viewsStaleFindings`' reason: a view\n  // belongs to no service, and only the fleet run has both the whole model and\n  // the enumerated `services/` in view at once.\n  //\n  // The views come from `preloaded` rather than from `land`, and that is the\n  // file-naming rule made mechanical instead of remembered: only the PROJECT\n  // load gives a view the `sourcePath` a finding has to name, while the\n  // single-file fallback a few lines above calls every document `source.c4` —\n  // so a message built from that load would send its reader to\n  // `architecture/source.c4`, a file that has never existed. No preload, no\n  // grading, and nothing to get wrong.\n  //\n  // Read second, and the ladder APPLIED BY ITS OWN FUNCTION rather than\n  // re-spelled here: an absent or unreadable capabilities.yaml means silence for\n  // the whole family, not a fleet full of unresolved tags, so `null` travels\n  // rather than an empty list — which the join would read as \"the fleet declares\n  // no capabilities\" and grade every tag against. `gradableCapabilityIds` is the\n  // one statement of that rule (`core/capabilities/findings.ts`), and this is a\n  // caller of it precisely so a fourth un-gradable vocabulary state cannot be\n  // fixed in core while the command layer keeps handing the join a whole key set.\n  // `capabilityFleetFindings` above has already paid for this read through the\n  // fleet context's memo.\n  const vocabulary =\n    fleet === undefined ? await readCapabilityVocabulary(docsDir) : await fleet.capabilities(docsDir);\n  // The requirement index behind the `#req-` tag, read here rather than inside\n  // the use-case package so that package never learns what a capability\n  // document is. Under `--all` every document was already parsed by\n  // `capabilityFleetFindings` above and the fleet memo answers from cache.\n  const capabilityReqs = await capabilityRequirementIndex(\n    vocabulary,\n    fleet === undefined ? async (p) => parseRequirements(await readRequirementsDocument(p)) : (p) => fleet.readRequirements(p),\n  );\n  findings.push(\n    ...useCaseFindings({\n      views: preloaded?.views ?? [],\n      elements: land.elements,\n      relationships: land.relationships,\n      services,\n      resolve: landSvcOf,\n      capabilities: gradableCapabilityIds(vocabulary),\n      requirementsOf: (capability) => capabilityReqs.byCapability.get(capability),\n    }),\n  );\n\n  if (findings.length === 0) {\n    findings.push({\n      severity: \"ok\",\n      code: \"landscape.matched\",\n      message: `landscape: ${services.size} service(s) modelled — architecture/landscape.likec4 and services/ agree`,\n    });\n  }\n  return report;\n}\n"]}

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

@@ -0,0 +1,52 @@
+/**
+ * A landscape that could not be READ, shaped as one that did not PARSE.
+ *
+ * The landscape is the one artifact no target owns: it is read once for the
+ * whole run and it is graded on a target of its own, which runs OUTSIDE
+ * `guarded`. So a landscape.likec4 that is a directory, or that carries a
+ * permission bit this process cannot open, escaped every per-target catch and
+ * became the whole run's `repository-unavailable` — one file, and a fleet gate
+ * that said nothing about the ninety-nine services that are fine. A DANGLING
+ * symlink is not one of those shapes and never was: every read of the file is
+ * gated on an `existsSync` that follows the link, so a broken one resolves as
+ * `landscape.missing` long before anything opens it.
+ *
+ * What this contains is the FLEET-level reads, and only those: the `--all`
+ * preload, and both reads inside `validateLandscape` — the conflict-marker
+ * `readFile` and the parse. `loam validate --service <id>` and
+ * `loam validate --feature <id>` hand in no preloaded doc, so `validateService`
+ * and `validateFeature` open the same file again on demand, unwrapped and
+ * INSIDE `guarded`: an EISDIR there is still reported as `service.unreadable`
+ * or `feature.unreadable`, which files the fleet map's failure against the one
+ * target the caller happened to name. That is the wrong subject on a finding
+ * that does at least carry the offending path, and it costs those runs nothing
+ * further — they grade a single target either way, so there is no report left
+ * unwritten — which is why the remainder was left for the change that gives the
+ * landscape one load path instead of three.
+ *
+ * `guarded` is deliberately NOT widened to cover the landscape target instead.
+ * Its code ternary knows only services and features, so it would file the fleet
+ * map's failure as `feature.unreadable`; and a guarded failure yields no
+ * document, so all N services would go on to re-open the same broken file
+ * inside their own guards and emit N copies of it. Containing the IO here needs
+ * no new code and no new sentence: "could not be read" and "did not parse" have
+ * the same consequence — nothing may be concluded from this file — and
+ * `landscape.invalid` is already how that is said.
+ */
+export function unreadableLandscape(err) {
+    return {
+        errors: [{ message: err instanceof Error ? err.message : String(err) }],
+        elements: [],
+        relationships: [],
+    };
+}
+/** One landscape load, answering with `unreadableLandscape` rather than throwing. */
+export async function readLandscape(load) {
+    try {
+        return await load();
+    }
+    catch (err) {
+        return unreadableLandscape(err);
+    }
+}
+//# sourceMappingURL=load.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../../../src/commands/validate/fleet/load.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO;QACL,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QACvE,QAAQ,EAAE,EAAE;QACZ,aAAa,EAAE,EAAE;KAClB,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAA8B;IAChE,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;AACH,CAAC","sourcesContent":["/**\n * The landscape's contained load path — the one phase of the fleet target that\n * touches the filesystem before anything can be graded. Split from\n * `./landscape.ts` when the fleet target grew past the line limit; the\n * containment DOCTRINE below travelled with the functions it explains.\n *\n * The load ITSELF is no longer here. `loadArchitecture` moved to\n * `core/c4/project/architecture.ts` when the use-case axis grew a second reader\n * of it, and that module's banner records why; what stayed is the containment,\n * which is command-layer business because it is about which validate TARGET a\n * failed read is filed against.\n */\nimport type { LoadedDoc } from \"../../../core/c4/likec4.js\";\n\n/**\n * A landscape that could not be READ, shaped as one that did not PARSE.\n *\n * The landscape is the one artifact no target owns: it is read once for the\n * whole run and it is graded on a target of its own, which runs OUTSIDE\n * `guarded`. So a landscape.likec4 that is a directory, or that carries a\n * permission bit this process cannot open, escaped every per-target catch and\n * became the whole run's `repository-unavailable` — one file, and a fleet gate\n * that said nothing about the ninety-nine services that are fine. A DANGLING\n * symlink is not one of those shapes and never was: every read of the file is\n * gated on an `existsSync` that follows the link, so a broken one resolves as\n * `landscape.missing` long before anything opens it.\n *\n * What this contains is the FLEET-level reads, and only those: the `--all`\n * preload, and both reads inside `validateLandscape` — the conflict-marker\n * `readFile` and the parse. `loam validate --service <id>` and\n * `loam validate --feature <id>` hand in no preloaded doc, so `validateService`\n * and `validateFeature` open the same file again on demand, unwrapped and\n * INSIDE `guarded`: an EISDIR there is still reported as `service.unreadable`\n * or `feature.unreadable`, which files the fleet map's failure against the one\n * target the caller happened to name. That is the wrong subject on a finding\n * that does at least carry the offending path, and it costs those runs nothing\n * further — they grade a single target either way, so there is no report left\n * unwritten — which is why the remainder was left for the change that gives the\n * landscape one load path instead of three.\n *\n * `guarded` is deliberately NOT widened to cover the landscape target instead.\n * Its code ternary knows only services and features, so it would file the fleet\n * map's failure as `feature.unreadable`; and a guarded failure yields no\n * document, so all N services would go on to re-open the same broken file\n * inside their own guards and emit N copies of it. Containing the IO here needs\n * no new code and no new sentence: \"could not be read\" and \"did not parse\" have\n * the same consequence — nothing may be concluded from this file — and\n * `landscape.invalid` is already how that is said.\n */\nexport function unreadableLandscape(err: unknown): LoadedDoc {\n  return {\n    errors: [{ message: err instanceof Error ? err.message : String(err) }],\n    elements: [],\n    relationships: [],\n  };\n}\n\n/** One landscape load, answering with `unreadableLandscape` rather than throwing. */\nexport async function readLandscape(load: () => Promise<LoadedDoc>): Promise<LoadedDoc> {\n  try {\n    return await load();\n  } catch (err) {\n    return unreadableLandscape(err);\n  }\n}\n"]}