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

package/dist/core/c4/arch.js

@@ -0,0 +1,174 @@
+/**
+ * The architecture spec axis — the grammar and resolution of `Covers:` — and
+ * the same endpoint join, reused, for the steps of a use case.
+ *
+ * A business spec will never mention the transactional outbox; that is
+ * architecture, and it lives in `arch.spec.md` — same requirement/scenario
+ * grammar as spec.md, same delta algebra, same merge. What is new is the
+ * `Covers:` line: where a business requirement declares the OPERATIONS it
+ * governs, an architecture requirement declares the MODEL OBJECTS its
+ * scenarios exercise, so coverage can be derived mechanically instead of
+ * trusted to an author who was never going to write the outbox down.
+ *
+ * Four entry forms, resolved against the documents loam already reads:
+ *
+ *   paymentService.db               a C4 element id — resolved against the
+ *                                   in-scope elements the way every check joins
+ *                                   them: the id itself, or the service the
+ *                                   element stands for (binding, then title);
+ *   paymentService -> kafka         an edge — each side resolved the same way,
+ *                                   against the declared relationships;
+ *   alert:<id> / sli:<id>           a health signal — ids `health.yaml`
+ *                                   declares (core/vocabulary/health.ts);
+ *   node:<id>, node:a -> node:b     a deployment object — a node or an instance
+ *                                   in the landscape's `deployment { }` model,
+ *                                   matched literally. This is the form that
+ *                                   lets a requirement about replication name
+ *                                   the two clusters it is written about
+ *                                   (ROADMAP's deployment axis).
+ *
+ * Resolution never reads code. An entry that resolves to nothing is the typo
+ * guard (`covers.unknown`, warn); the emitters live with the other validate
+ * checks, this module owns only the grammar and the matching.
+ *
+ * `attributeStep` used to sit at the foot of this file and now lives in
+ * `./resolve/steps.ts`. It answers the same shape of question for a different
+ * axis — which declared relationship backs a `dynamic view`'s hop — over the
+ * same two tiers and the same cached resolver, and the seam was named here long
+ * before the line limit forced it. What the two still share is
+ * `./resolve/service.ts`'s `resolverFor`, which is where that cache moved with
+ * it: one id→service resolver per document, serving both axes.
+ */
+import {} from "./likec4.js";
+import { elementService, resolverFor } from "./resolve/service.js";
+/** Parse one comma-separated `Covers:` entry into its form. Never fails: an
+ * unclassifiable string is an element entry that will not resolve, and the
+ * covers.unknown message is a better diagnosis than a parse refusal. */
+export function parseCoversEntry(raw) {
+    const alert = /^alert:\s*(.+)$/.exec(raw);
+    if (alert)
+        return { form: "alert", id: alert[1].trim(), raw };
+    const sli = /^sli:\s*(.+)$/.exec(raw);
+    if (sli)
+        return { form: "sli", id: sli[1].trim(), raw };
+    const edge = /^(.+?)\s*->\s*(.+)$/.exec(raw);
+    if (edge) {
+        const source = edge[1].trim();
+        const target = edge[2].trim();
+        const from = nodeId(source);
+        const to = nodeId(target);
+        // BOTH sides, or neither. A mixed entry stays an ordinary edge whose
+        // prefixed side then resolves to nothing — which is the honest answer:
+        // there is no edge in any model with one endpoint in the logical map and
+        // one in the deployment map, so accepting a half-prefixed line would be
+        // inventing a join rather than reading one. The `->` split runs FIRST for
+        // the same reason the alert/sli tests do: `node:a -> node:b` read as a
+        // single id would be one entry that can never resolve.
+        if (from !== undefined && to !== undefined)
+            return { form: "node-edge", source: from, target: to, raw };
+        return { form: "edge", source, target, raw };
+    }
+    const node = nodeId(raw);
+    if (node !== undefined)
+        return { form: "node", id: node, raw };
+    return { form: "element", id: raw, raw };
+}
+/** The id behind a `node:` prefix, or nothing when the entry does not carry one. */
+function nodeId(text) {
+    const m = /^node:\s*(.+)$/.exec(text);
+    return m === null ? undefined : m[1].trim();
+}
+/** Does an element entry name this element? Its id, or the service it stands for. */
+function namesElement(name, e) {
+    return e.id === name || elementService(e) === name;
+}
+/** Does an edge entry's side name this relationship endpoint? */
+function namesEndpoint(name, endpointId, elements, known) {
+    return endpointId === name || resolverFor(elements, known)(endpointId) === name;
+}
+/** Does a Covers entry match this element? (Only element entries can.) */
+export function coversElement(entry, e) {
+    return entry.form === "element" && namesElement(entry.id, e);
+}
+/** Does a Covers entry match this relationship? Endpoints resolved within `elements`, through `known` where the caller has the fleet. */
+export function coversEdge(entry, r, elements, known) {
+    return (entry.form === "edge" &&
+        namesEndpoint(entry.source, r.source, elements, known) &&
+        namesEndpoint(entry.target, r.target, elements, known));
+}
+/** Does a Covers entry name this deployment node or instance? Matched literally — see `entryResolves`. */
+export function coversDeployNode(entry, id) {
+    return entry.form === "node" && entry.id === id;
+}
+/** Does a Covers entry name this deployment edge? Both endpoints, literally. */
+export function coversDeployEdge(entry, source, target) {
+    return entry.form === "node-edge" && entry.source === source && entry.target === target;
+}
+/** Does the entry resolve to ANYTHING in scope? False is `covers.unknown`. */
+export function entryResolves(entry, scope) {
+    switch (entry.form) {
+        case "alert":
+            return scope.health.alerts.includes(entry.id);
+        case "sli":
+            return scope.health.slis.includes(entry.id);
+        case "edge":
+            return scope.relationships.some((r) => coversEdge(entry, r, scope.elements, scope.known));
+        case "element":
+            return scope.elements.some((e) => coversElement(entry, e));
+        case "node":
+            return deployedIds(scope).includes(entry.id);
+        case "node-edge":
+            // Endpoints matched literally, and only literally. The logical forms
+            // resolve a name through `serviceResolver` because an author writes
+            // `checkout-web -> payment-service` about an edge the model draws between
+            // two containers; a deployment id is already the exact path to one place
+            // on the map, there is no coarser name for it, and inventing one would
+            // make `node:eu.dcA` silently match an edge between two clusters inside
+            // it.
+            return (scope.deployment?.relationships ?? []).some((r) => r.source === entry.source && r.target === entry.target);
+    }
+}
+/** Every deployment object a `node:` entry may name: the nodes, and the instances in them. */
+function deployedIds(scope) {
+    const d = scope.deployment;
+    if (d === undefined)
+        return [];
+    return [...d.nodes.map((n) => n.id), ...d.instances.map((i) => i.id)];
+}
+/** Ids a covers.unknown hint may offer for a mistyped entry — always real ones. */
+export function coversCandidates(entry, scope) {
+    switch (entry.form) {
+        case "alert":
+            return closeIds(entry.id, scope.health.alerts).map((id) => `alert:${id}`);
+        case "sli":
+            return closeIds(entry.id, scope.health.slis).map((id) => `sli:${id}`);
+        case "edge":
+        case "node-edge":
+            // Cheap on purpose: no pairwise edge fuzzing — the sides are element
+            // names, so the element hint is the useful one.
+            return [];
+        case "element":
+            return closeIds(entry.id, [...new Set(scope.elements.map((e) => e.id))]);
+        case "node":
+            // Offered WITH the prefix, because that is the line the author has to
+            // type. A hint spelling an id the grammar would then read as an element
+            // entry is a hint that sends the reader round the loop a second time.
+            return closeIds(entry.id, [...new Set(deployedIds(scope))]).map((id) => `node:${id}`);
+    }
+}
+/**
+ * Existing ids near a misspelling — substring containment either way, else a
+ * shared 3-character prefix. Deliberately dumb: no fuzzy library for one hint,
+ * and every id offered is real, so the hint can never point at the typo itself.
+ * (Moved here from validate.ts once `covers.unknown` became its second user.)
+ */
+export function closeIds(typo, ids) {
+    const t = typo.toLowerCase();
+    return ids
+        .filter((id) => {
+        const i = id.toLowerCase();
+        return i.includes(t) || t.includes(i) || (t.length >= 3 && i.startsWith(t.slice(0, 3)));
+    })
+        .slice(0, 5);
+}
+//# sourceMappingURL=arch.js.map

package/dist/core/c4/arch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arch.js","sourceRoot":"","sources":["../../../src/core/c4/arch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The architecture spec axis — the grammar and resolution of `Covers:` — and\n * the same endpoint join, reused, for the steps of a use case.\n *\n * A business spec will never mention the transactional outbox; that is\n * architecture, and it lives in `arch.spec.md` — same requirement/scenario\n * grammar as spec.md, same delta algebra, same merge. What is new is the\n * `Covers:` line: where a business requirement declares the OPERATIONS it\n * governs, an architecture requirement declares the MODEL OBJECTS its\n * scenarios exercise, so coverage can be derived mechanically instead of\n * trusted to an author who was never going to write the outbox down.\n *\n * Four entry forms, resolved against the documents loam already reads:\n *\n *   paymentService.db               a C4 element id — resolved against the\n *                                   in-scope elements the way every check joins\n *                                   them: the id itself, or the service the\n *                                   element stands for (binding, then title);\n *   paymentService -> kafka         an edge — each side resolved the same way,\n *                                   against the declared relationships;\n *   alert:<id> / sli:<id>           a health signal — ids `health.yaml`\n *                                   declares (core/vocabulary/health.ts);\n *   node:<id>, node:a -> node:b     a deployment object — a node or an instance\n *                                   in the landscape's `deployment { }` model,\n *                                   matched literally. This is the form that\n *                                   lets a requirement about replication name\n *                                   the two clusters it is written about\n *                                   (ROADMAP's deployment axis).\n *\n * Resolution never reads code. An entry that resolves to nothing is the typo\n * guard (`covers.unknown`, warn); the emitters live with the other validate\n * checks, this module owns only the grammar and the matching.\n *\n * `attributeStep` used to sit at the foot of this file and now lives in\n * `./resolve/steps.ts`. It answers the same shape of question for a different\n * axis — which declared relationship backs a `dynamic view`'s hop — over the\n * same two tiers and the same cached resolver, and the seam was named here long\n * before the line limit forced it. What the two still share is\n * `./resolve/service.ts`'s `resolverFor`, which is where that cache moved with\n * it: one id→service resolver per document, serving both axes.\n */\nimport { type Elem, type Rel } from \"./likec4.js\";\nimport type { DeploymentModel } from \"./parsed/deployment.js\";\nimport { elementService, resolverFor } from \"./resolve/service.js\";\nimport type { HealthIds } from \"../vocabulary/health.js\";\n\nexport type CoversEntry =\n  | { form: \"element\"; id: string; raw: string }\n  | { form: \"edge\"; source: string; target: string; raw: string }\n  | { form: \"alert\" | \"sli\"; id: string; raw: string }\n  /**\n   * A deployment object — `node:eu.dcA.k8sA`, and the edge form\n   * `node:a -> node:b`. One prefix covers deployment NODES and the INSTANCES\n   * inside them, because both are places on the same map and a requirement\n   * about replication names an instance as readily as a datacenter. A second\n   * prefix for the second kind would make an author pick between two spellings\n   * for one question, and pick wrong.\n   */\n  | { form: \"node\"; id: string; raw: string }\n  | { form: \"node-edge\"; source: string; target: string; raw: string };\n\n/** Parse one comma-separated `Covers:` entry into its form. Never fails: an\n * unclassifiable string is an element entry that will not resolve, and the\n * covers.unknown message is a better diagnosis than a parse refusal. */\nexport function parseCoversEntry(raw: string): CoversEntry {\n  const alert = /^alert:\\s*(.+)$/.exec(raw);\n  if (alert) return { form: \"alert\", id: alert[1]!.trim(), raw };\n  const sli = /^sli:\\s*(.+)$/.exec(raw);\n  if (sli) return { form: \"sli\", id: sli[1]!.trim(), raw };\n  const edge = /^(.+?)\\s*->\\s*(.+)$/.exec(raw);\n  if (edge) {\n    const source = edge[1]!.trim();\n    const target = edge[2]!.trim();\n    const from = nodeId(source);\n    const to = nodeId(target);\n    // BOTH sides, or neither. A mixed entry stays an ordinary edge whose\n    // prefixed side then resolves to nothing — which is the honest answer:\n    // there is no edge in any model with one endpoint in the logical map and\n    // one in the deployment map, so accepting a half-prefixed line would be\n    // inventing a join rather than reading one. The `->` split runs FIRST for\n    // the same reason the alert/sli tests do: `node:a -> node:b` read as a\n    // single id would be one entry that can never resolve.\n    if (from !== undefined && to !== undefined) return { form: \"node-edge\", source: from, target: to, raw };\n    return { form: \"edge\", source, target, raw };\n  }\n  const node = nodeId(raw);\n  if (node !== undefined) return { form: \"node\", id: node, raw };\n  return { form: \"element\", id: raw, raw };\n}\n\n/** The id behind a `node:` prefix, or nothing when the entry does not carry one. */\nfunction nodeId(text: string): string | undefined {\n  const m = /^node:\\s*(.+)$/.exec(text);\n  return m === null ? undefined : m[1]!.trim();\n}\n\n/**\n * What `Covers:` entries resolve against: every element and relationship in\n * view (a service's own model plus the landscape; for a feature, the delta\n * plus both), and the health ids of the service whose spec is being read.\n */\nexport interface CoverageScope {\n  elements: Elem[];\n  relationships: Rel[];\n  /**\n   * The fleet's topology, for the `node:` forms — the LANDSCAPE's deployment\n   * model and no other, even though a service's own `model.likec4` may legally\n   * declare one. Topology is a fleet-level fact for the reason a cross-service\n   * flow is: `architecture/` is the one place that already holds every edge\n   * crossing two services, and a per-service deployment block would let two\n   * documents disagree about where one container runs with nothing able to say\n   * which is right. Absent for every fleet that draws none, which is what makes\n   * a `node:` entry there resolve to nothing and report the typo.\n   */\n  deployment?: DeploymentModel;\n  health: HealthIds;\n  /**\n   * The enumerated fleet (plus the feature's own `specs/` names, where the\n   * caller has them). The Covers matcher resolves edge ENDPOINTS with it, and\n   * it must be the SAME set the caller's own findings resolve with: the finding\n   * says \"write `Covers: checkout-web -> payment-service`\" with the fleet in\n   * hand, and a matcher resolving without it answered that exact line with\n   * `covers.unknown` whenever the edge landed on a modelled container.\n   */\n  known?: ReadonlySet<string>;\n}\n\n/** Does an element entry name this element? Its id, or the service it stands for. */\nfunction namesElement(name: string, e: Elem): boolean {\n  return e.id === name || elementService(e) === name;\n}\n\n/** Does an edge entry's side name this relationship endpoint? */\nfunction namesEndpoint(\n  name: string,\n  endpointId: string,\n  elements: Elem[],\n  known?: ReadonlySet<string>,\n): boolean {\n  return endpointId === name || resolverFor(elements, known)(endpointId) === name;\n}\n\n/** Does a Covers entry match this element? (Only element entries can.) */\nexport function coversElement(entry: CoversEntry, e: Elem): boolean {\n  return entry.form === \"element\" && namesElement(entry.id, e);\n}\n\n/** Does a Covers entry match this relationship? Endpoints resolved within `elements`, through `known` where the caller has the fleet. */\nexport function coversEdge(entry: CoversEntry, r: Rel, elements: Elem[], known?: ReadonlySet<string>): boolean {\n  return (\n    entry.form === \"edge\" &&\n    namesEndpoint(entry.source, r.source, elements, known) &&\n    namesEndpoint(entry.target, r.target, elements, known)\n  );\n}\n\n/** Does a Covers entry name this deployment node or instance? Matched literally — see `entryResolves`. */\nexport function coversDeployNode(entry: CoversEntry, id: string): boolean {\n  return entry.form === \"node\" && entry.id === id;\n}\n\n/** Does a Covers entry name this deployment edge? Both endpoints, literally. */\nexport function coversDeployEdge(entry: CoversEntry, source: string, target: string): boolean {\n  return entry.form === \"node-edge\" && entry.source === source && entry.target === target;\n}\n\n/** Does the entry resolve to ANYTHING in scope? False is `covers.unknown`. */\nexport function entryResolves(entry: CoversEntry, scope: CoverageScope): boolean {\n  switch (entry.form) {\n    case \"alert\":\n      return scope.health.alerts.includes(entry.id);\n    case \"sli\":\n      return scope.health.slis.includes(entry.id);\n    case \"edge\":\n      return scope.relationships.some((r) => coversEdge(entry, r, scope.elements, scope.known));\n    case \"element\":\n      return scope.elements.some((e) => coversElement(entry, e));\n    case \"node\":\n      return deployedIds(scope).includes(entry.id);\n    case \"node-edge\":\n      // Endpoints matched literally, and only literally. The logical forms\n      // resolve a name through `serviceResolver` because an author writes\n      // `checkout-web -> payment-service` about an edge the model draws between\n      // two containers; a deployment id is already the exact path to one place\n      // on the map, there is no coarser name for it, and inventing one would\n      // make `node:eu.dcA` silently match an edge between two clusters inside\n      // it.\n      return (scope.deployment?.relationships ?? []).some(\n        (r) => r.source === entry.source && r.target === entry.target,\n      );\n  }\n}\n\n/** Every deployment object a `node:` entry may name: the nodes, and the instances in them. */\nfunction deployedIds(scope: CoverageScope): string[] {\n  const d = scope.deployment;\n  if (d === undefined) return [];\n  return [...d.nodes.map((n) => n.id), ...d.instances.map((i) => i.id)];\n}\n\n/** Ids a covers.unknown hint may offer for a mistyped entry — always real ones. */\nexport function coversCandidates(entry: CoversEntry, scope: CoverageScope): string[] {\n  switch (entry.form) {\n    case \"alert\":\n      return closeIds(entry.id, scope.health.alerts).map((id) => `alert:${id}`);\n    case \"sli\":\n      return closeIds(entry.id, scope.health.slis).map((id) => `sli:${id}`);\n    case \"edge\":\n    case \"node-edge\":\n      // Cheap on purpose: no pairwise edge fuzzing — the sides are element\n      // names, so the element hint is the useful one.\n      return [];\n    case \"element\":\n      return closeIds(entry.id, [...new Set(scope.elements.map((e) => e.id))]);\n    case \"node\":\n      // Offered WITH the prefix, because that is the line the author has to\n      // type. A hint spelling an id the grammar would then read as an element\n      // entry is a hint that sends the reader round the loop a second time.\n      return closeIds(entry.id, [...new Set(deployedIds(scope))]).map((id) => `node:${id}`);\n  }\n}\n\n/**\n * Existing ids near a misspelling — substring containment either way, else a\n * shared 3-character prefix. Deliberately dumb: no fuzzy library for one hint,\n * and every id offered is real, so the hint can never point at the typo itself.\n * (Moved here from validate.ts once `covers.unknown` became its second user.)\n */\nexport function closeIds(typo: string, ids: readonly string[]): string[] {\n  const t = typo.toLowerCase();\n  return ids\n    .filter((id) => {\n      const i = id.toLowerCase();\n      return i.includes(t) || t.includes(i) || (t.length >= 3 && i.startsWith(t.slice(0, 3)));\n    })\n    .slice(0, 5);\n}\n\n"]}

package/dist/core/c4/likec4.js

@@ -0,0 +1,90 @@
+import { readFile } from "node:fs/promises";
+import { LikeC4 } from "likec4";
+import { declaredService } from "../kernel/ids/service.js";
+import { readDynamicViews } from "./parsed/dynamic-views.js";
+import { readViewIds } from "./parsed/view-ids.js";
+import { readSpecification } from "./parsed/specification.js";
+import { readDeployment } from "./parsed/deployment.js";
+import { descText, metaKey } from "./parsed/values.js";
+/** Flatten a LikeC4 model into loam's neutral `Elem`/`Rel` view. */
+export function flattenModel(model) {
+    const elements = [...model.elements()].map((e) => {
+        // The one crossing between LikeC4's parse output and loam's type system:
+        // a `metadata { service '...' }` binding is text somebody wrote, and this
+        // is where it acquires a type that says so.
+        const bound = metaKey(e.metadata, "service");
+        return {
+            id: e.id,
+            kind: e.kind,
+            title: e.title,
+            description: descText(e.description),
+            ...(bound === undefined ? {} : { service: declaredService(bound) }),
+            tags: [...(e.tags ?? [])],
+        };
+    });
+    const relationships = [...model.relationships()].map((r) => ({
+        source: r.source.id,
+        target: r.target.id,
+        // LikeC4 reports an untitled edge as title: null — normalize to the declared `title?: string`.
+        title: r.title ?? undefined,
+        op: metaKey(r.metadata, "op"),
+        publishes: metaKey(r.metadata, "publishes"),
+        consumes: metaKey(r.metadata, "consumes"),
+        tags: [...(r.tags ?? [])],
+    }));
+    return { elements, relationships };
+}
+/**
+ * Load and validate a single self-contained `.likec4` document, in-process
+ * (no external tool, no JVM). Returns validation errors and, if clean, the
+ * flattened elements + relationships.
+ */
+export async function loadFile(path) {
+    return loadSource(await readFile(path, "utf8"));
+}
+/**
+ * `loadFile` for text that is not (yet) on disk — what the archive merge uses
+ * to prove a computed landscape parses BEFORE anything is written.
+ */
+export async function loadSource(src) {
+    // LikeC4 owns a Langium workspace and registers a process-exit listener for
+    // it. Validation creates many short-lived instances, so every acquired
+    // instance must be disposed even on an invalid document or a failed model
+    // computation. Its logger is disabled because diagnostics are returned in
+    // LoadedDoc instead of being written out-of-band to stderr.
+    const likec4 = await LikeC4.fromSource(src, { logger: false });
+    try {
+        // Assigned, not cast: LikeC4 declares `getErrors()` as a non-nullable array
+        // whose element type is structurally wider than ours, so the compiler can
+        // check the shape here. The cast was the only thing standing between a
+        // dependency renaming `message` and a build that still succeeded — and the
+        // `?? []` it carried could never fire.
+        const errors = likec4.getErrors();
+        if (errors.length > 0) {
+            return { errors, elements: [], relationships: [] };
+        }
+        // `parsedModel`, not `computedModel`: the computed stage RESOLVES every
+        // view — expanding its predicates against the model and deriving the
+        // ancestor edges a diagram needs (and computing a default view when the
+        // document declares none). loam reads what a view DECLARES and never what a
+        // view SHOWS (docs/DESIGN.md rule 26), so none of that resolution is ever
+        // wanted; it renders nothing. That work is superlinear in the number of
+        // RELATIONSHIPS, so a landscape at fleet shape turned `loam list` from under
+        // a second into minutes. The elements and relationships below are identical
+        // either way. The `await` is load-bearing for anything reading `$data`: it is
+        // undefined on the unresolved promise.
+        const model = (await likec4.parsedModel());
+        return {
+            errors,
+            specification: readSpecification(model.specification),
+            views: readDynamicViews(model),
+            viewIds: readViewIds(model),
+            deployment: readDeployment(model),
+            ...flattenModel(model),
+        };
+    }
+    finally {
+        await likec4.dispose();
+    }
+}
+//# sourceMappingURL=likec4.js.map

package/dist/core/c4/likec4.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"likec4.js","sourceRoot":"","sources":["../../../src/core/c4/likec4.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { LikeC4 } from \"likec4\";\nimport { declaredService, type DeclaredService } from \"../kernel/ids/service.js\";\nimport { readDynamicViews, type ParsedView } from \"./parsed/dynamic-views.js\";\nimport { readViewIds, type ViewIdClaim } from \"./parsed/view-ids.js\";\nimport { readSpecification, type DocSpecification } from \"./parsed/specification.js\";\nimport { readDeployment, type DeploymentModel } from \"./parsed/deployment.js\";\nimport { descText, metaKey } from \"./parsed/values.js\";\n\n/** A parse/validation issue reported by LikeC4. */\nexport interface LikeC4Error {\n  message: string;\n  line?: number;\n  sourceFsPath?: string;\n}\n\n/** loam-neutral element view (flattened from the LikeC4 parsed model). */\nexport interface Elem {\n  id: string;\n  kind: string;\n  title: string;\n  description?: string;\n  /**\n   * The `services/<id>` directory this element stands for, from the element's\n   * `metadata { service '...' }`. Absent on the elements nobody has bound —\n   * see `elementService` for the fallback.\n   */\n  service?: DeclaredService;\n  tags: string[];\n}\n\n/** loam-neutral relationship view. */\nexport interface Rel {\n  source: string;\n  target: string;\n  title?: string;\n  /** OpenAPI operationId this call uses, from the relationship's `metadata { op '...' }`. */\n  op?: string;\n  /**\n   * AsyncAPI message this edge PRODUCES, from `metadata { publishes '...' }`.\n   * Resolved against the edge SOURCE's own contract: a service publishes what it\n   * declares an `action: send` for.\n   */\n  publishes?: string;\n  /**\n   * AsyncAPI message this edge CONSUMES, from `metadata { consumes '...' }`.\n   * Two keys rather than one directional `message`, because the async spine is\n   * not symmetric with the HTTP one: there the PROVIDER owns the contract and\n   * every consumer is checked against it, while here the PRODUCER owns the\n   * message and the consumer lives in another repository entirely. Which side of\n   * an edge owes the declaration has to be readable from the edge itself — the\n   * arrow cannot say it, because a Kafka edge points at the broker from both\n   * ends.\n   */\n  consumes?: string;\n  tags: string[];\n}\n\nexport interface LoadedDoc {\n  errors: LikeC4Error[];\n  elements: Elem[];\n  relationships: Rel[];\n  /**\n   * The document's `specification { }` block — what its KINDS declare, as\n   * opposed to what its elements do. Optional because a document that did not\n   * parse has none, and because the several `LoadedDoc` literals standing in for\n   * an absent file (`show`'s missing model.likec4, `unreadableLandscape`) have\n   * nothing to put here: a reader must treat \"absent\" and \"declares nothing\" the\n   * same way. See `./parsed/specification.ts` for why loam reads it at all —\n   * short version: since LikeC4 1.59.0 a kind can carry tags, and only the\n   * specification can tell an inherited tag from an authored one.\n   */\n  specification?: DocSpecification;\n  /**\n   * The `dynamic view`s the document DECLARES — the ordered steps of a use\n   * case, never a rendering (docs/DESIGN.md rule 26). Optional for exactly the\n   * reason `specification` is: a document that did not parse has none, and the\n   * several `LoadedDoc` literals standing in for an absent file have nothing to\n   * put here. Absent and empty mean the same thing to every reader — no views\n   * were declared, or none could be read — and neither is a finding: a fleet\n   * that draws no diagrams owes loam no views block.\n   */\n  views?: ParsedView[];\n  /**\n   * The ids of every view the document AUTHORS, static ones included — a census,\n   * not a read of what any of them shows. Separate from `views` above because\n   * the two answer different questions off different filters (see\n   * `./parsed/view-ids.ts`), and because a static view contributes an id and\n   * nothing else loam may look at.\n   */\n  viewIds?: ViewIdClaim[];\n  /**\n   * The `deployment { }` model the document declares — nodes, instances and the\n   * edges between them (`./parsed/deployment.ts`). Optional for the reason\n   * `views` is, and read the same way by every consumer: absent and empty mean\n   * \"no topology\", and neither is a finding. A fleet that draws no deployment\n   * owes loam none, which is also the whole opt-in the axis has.\n   */\n  deployment?: DeploymentModel;\n}\n\n/**\n * The slice of a LikeC4 model loam reads: elements and relationships, and on\n * each of those only id/kind/title/description/tags/metadata.\n *\n * It is a type of its own, rather than an inline cast at the one call site,\n * because BOTH of LikeC4's model stages expose exactly this slice — which is\n * what makes the cheap stage a safe substitute for the expensive one. The\n * substitution is pinned in test/likec4-model-parity.test.ts, which flattens\n * both stages through `flattenModel` below and compares the results.\n *\n * Views are deliberately NOT in this interface, even though loam does read them.\n * What this interface pins is the two-stage PARITY that makes the cheap stage a\n * safe substitute for the expensive one — and the stages are not claimed to\n * agree about views, nor need to: the parsed stage is the only one rule 26\n * permits. That read has its own adapter, `./parsed/dynamic-views.ts`.\n */\nexport interface ReadableModel {\n  elements: () => Iterable<{\n    id: string;\n    kind: string;\n    title: string;\n    description?: unknown;\n    tags?: readonly string[];\n    metadata?: unknown;\n  }>;\n  relationships: () => Iterable<{\n    source: { id: string };\n    target: { id: string };\n    title?: string | null;\n    tags?: readonly string[];\n    metadata?: unknown;\n  }>;\n  /**\n   * The parsed `specification { }` block. Typed `unknown` and normalized by\n   * `readSpecification` rather than described here, because it is NOT part of\n   * the two-stage parity this interface pins: the shape is LikeC4's internal\n   * record (1.59.2 spells element-kind tags and relationship-kind tags\n   * differently), and writing it out here would be a structural claim about a\n   * dependency's internals that the compiler would then enforce against us.\n   */\n  specification?: unknown;\n}\n\n/** Flatten a LikeC4 model into loam's neutral `Elem`/`Rel` view. */\nexport function flattenModel(model: ReadableModel): { elements: Elem[]; relationships: Rel[] } {\n  const elements: Elem[] = [...model.elements()].map((e) => {\n    // The one crossing between LikeC4's parse output and loam's type system:\n    // a `metadata { service '...' }` binding is text somebody wrote, and this\n    // is where it acquires a type that says so.\n    const bound = metaKey(e.metadata, \"service\");\n    return {\n      id: e.id,\n      kind: e.kind,\n      title: e.title,\n      description: descText(e.description),\n      ...(bound === undefined ? {} : { service: declaredService(bound) }),\n      tags: [...(e.tags ?? [])],\n    };\n  });\n  const relationships: Rel[] = [...model.relationships()].map((r) => ({\n    source: r.source.id,\n    target: r.target.id,\n    // LikeC4 reports an untitled edge as title: null — normalize to the declared `title?: string`.\n    title: r.title ?? undefined,\n    op: metaKey(r.metadata, \"op\"),\n    publishes: metaKey(r.metadata, \"publishes\"),\n    consumes: metaKey(r.metadata, \"consumes\"),\n    tags: [...(r.tags ?? [])],\n  }));\n  return { elements, relationships };\n}\n\n/**\n * Load and validate a single self-contained `.likec4` document, in-process\n * (no external tool, no JVM). Returns validation errors and, if clean, the\n * flattened elements + relationships.\n */\nexport async function loadFile(path: string): Promise<LoadedDoc> {\n  return loadSource(await readFile(path, \"utf8\"));\n}\n\n/**\n * `loadFile` for text that is not (yet) on disk — what the archive merge uses\n * to prove a computed landscape parses BEFORE anything is written.\n */\nexport async function loadSource(src: string): Promise<LoadedDoc> {\n  // LikeC4 owns a Langium workspace and registers a process-exit listener for\n  // it. Validation creates many short-lived instances, so every acquired\n  // instance must be disposed even on an invalid document or a failed model\n  // computation. Its logger is disabled because diagnostics are returned in\n  // LoadedDoc instead of being written out-of-band to stderr.\n  const likec4 = await LikeC4.fromSource(src, { logger: false });\n  try {\n    // Assigned, not cast: LikeC4 declares `getErrors()` as a non-nullable array\n    // whose element type is structurally wider than ours, so the compiler can\n    // check the shape here. The cast was the only thing standing between a\n    // dependency renaming `message` and a build that still succeeded — and the\n    // `?? []` it carried could never fire.\n    const errors: LikeC4Error[] = likec4.getErrors();\n    if (errors.length > 0) {\n      return { errors, elements: [], relationships: [] };\n    }\n\n    // `parsedModel`, not `computedModel`: the computed stage RESOLVES every\n    // view — expanding its predicates against the model and deriving the\n    // ancestor edges a diagram needs (and computing a default view when the\n    // document declares none). loam reads what a view DECLARES and never what a\n    // view SHOWS (docs/DESIGN.md rule 26), so none of that resolution is ever\n    // wanted; it renders nothing. That work is superlinear in the number of\n    // RELATIONSHIPS, so a landscape at fleet shape turned `loam list` from under\n    // a second into minutes. The elements and relationships below are identical\n    // either way. The `await` is load-bearing for anything reading `$data`: it is\n    // undefined on the unresolved promise.\n    const model = (await likec4.parsedModel()) as ReadableModel;\n    return {\n      errors,\n      specification: readSpecification(model.specification),\n      views: readDynamicViews(model),\n      viewIds: readViewIds(model),\n      deployment: readDeployment(model),\n      ...flattenModel(model),\n    };\n  } finally {\n    await likec4.dispose();\n  }\n}\n"]}

package/dist/core/c4/parsed/deployment.js

@@ -0,0 +1,158 @@
+/**
+ * The DEPLOYMENT model a document declares — which physical nodes exist, which
+ * containers are instanced where, and what talks to what across them.
+ *
+ * A `deployment { }` block has been legal in a docs repo since LikeC4 could
+ * parse one, and until this reader existed loam saw none of it. The parser
+ * resolved every `instanceOf` — so a container renamed out from under a
+ * deployment node already failed the gate — and after that no requirement could
+ * name a node, no `#obl-` tag on a datacenter was graded, and the context pack
+ * an agent implements from did not mention topology at all. Integrity held at
+ * the level of syntax and was absent at the level of requirements. ROADMAP's
+ * deployment axis and `meta/docs/features/FEAT-1-the-deployment-axis/` are the
+ * item and the specification; this module is its first half.
+ *
+ * ## Why this is a `parsed/` reader and not a package of its own
+ *
+ * It is the same job the three modules beside it do: take one corner of
+ * LikeC4's parse output and hand back a loam-neutral record, defensively, with
+ * its shape assumptions owned outright. `readSpecification`, `readDynamicViews`
+ * and `readViewIds` are all called on the line above `flattenModel(model)` in
+ * each of loam's three loaders, and so is this. FEAT-1's delta said
+ * `src/core/c4/deploy/`; a package holding this alone would be a directory
+ * pretending to be a subject (docs/DESIGN.md), and the delta was corrected
+ * rather than the code bent to it — which is what an unarchived feature is for.
+ *
+ * **`parsed/` is now AT its five-file limit.** The next reader here needs a
+ * split first, and the seam to split on is the one this file does not share:
+ * `dynamic-views.ts` and `view-ids.ts` read `$data`, this one and
+ * `specification.ts` read the model surface.
+ *
+ * ## What is read, and what is deliberately left
+ *
+ * Nodes, instances and relationships, with the ids, titles and tags each
+ * carries. MEASURED at the 1.59.2 pin, and every line of it needed measuring
+ * rather than assuming:
+ *
+ *  - `nodes()` returns deployment NODES only — an `instanceOf` is not among
+ *    them, which is why instances are a second list rather than a filter.
+ *  - an instance carries the LOGICAL element it deploys as `element.id`, and
+ *    that is the whole join back to the C4 model: `eu.a.dbA -> orders.db`.
+ *  - both nodes and instances carry `tags`, so `#obl-geo` on a datacenter is
+ *    readable — the fail-open case that made this an item.
+ *  - a relationship carries `tags` and `metadata` DIRECTLY (`r.metadata`, no
+ *    `$relationship` indirection), and both model stages return byte-identical
+ *    results, which is what lets `test/likec4-model-parity.test.ts` cover this
+ *    read with the substitution it already pins.
+ *  - a document with NO `deployment { }` block still returns a deployment
+ *    object whose three iterators are empty. Absent and empty are therefore the
+ *    same answer here, deliberately: no reader may distinguish "declares none"
+ *    from "could not be read", because the second is what the defensive returns
+ *    below produce and a fleet that draws no topology owes loam nothing.
+ *
+ * `metadata` is NOT carried on the records below, and neither is an instance's
+ * `kind`. Both are readable; no check reads them yet, and a field carried
+ * before a caller needs it is a field nobody notices going wrong. Add one with
+ * the check that consumes it.
+ */
+/** No topology — what an absent block and an unreadable one both come back as. */
+export const NO_DEPLOYMENT = { nodes: [], instances: [], relationships: [] };
+/** Is there anything here? The opt-in every deployment check is gated on. */
+export function hasDeployment(d) {
+    return d.nodes.length > 0 || d.instances.length > 0 || d.relationships.length > 0;
+}
+/** A record, or nothing — the parse surface hands back `unknown`. */
+function record(v) {
+    return v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+}
+/** An iterable produced by `name()`, or an empty one when the surface is not what we measured. */
+function iterate(source, name) {
+    const fn = source[name];
+    if (typeof fn !== "function")
+        return [];
+    try {
+        const out = fn.call(source);
+        // A generator satisfies this; so does an array. Anything else is a shape
+        // change upstream, and the honest answer to one is "no topology read".
+        return out !== null && typeof out === "object" && Symbol.iterator in out
+            ? [...out]
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** A string field, or the empty string — never `undefined` leaking into a record. */
+function str(o, key) {
+    const v = o[key];
+    return typeof v === "string" ? v : "";
+}
+/** Tags as loam models them: a plain array of strings, always present. */
+function tags(o) {
+    const v = o["tags"];
+    return Array.isArray(v) ? v.filter((t) => typeof t === "string") : [];
+}
+/**
+ * Read the deployment model off an awaited `parsedModel()`.
+ *
+ * Defensive throughout, in the shape `readViewIds` established: an entry
+ * missing the one field that identifies it is DROPPED rather than reported with
+ * a hole, and a surface that is not what was measured yields an empty model
+ * instead of throwing. A check that cannot see the topology must say
+ * could-not-look through its own silence, never fail the fleet's parse.
+ */
+export function readDeployment(model) {
+    const root = record(model);
+    if (root === undefined)
+        return NO_DEPLOYMENT;
+    const deployment = record(root["deployment"]);
+    if (deployment === undefined)
+        return NO_DEPLOYMENT;
+    const nodes = [];
+    for (const raw of iterate(deployment, "nodes")) {
+        const n = record(raw);
+        if (n === undefined)
+            continue;
+        const id = str(n, "id");
+        if (id === "")
+            continue;
+        nodes.push({ id, kind: str(n, "kind"), title: str(n, "title"), tags: tags(n) });
+    }
+    const instances = [];
+    for (const raw of iterate(deployment, "instances")) {
+        const i = record(raw);
+        if (i === undefined)
+            continue;
+        const id = str(i, "id");
+        // The logical element is the whole point of the record. An instance whose
+        // element cannot be read joins to nothing, so reporting it would put a
+        // deployed thing on the map that no requirement could ever cover.
+        const element = record(i["element"]);
+        if (id === "" || element === undefined)
+            continue;
+        const elementId = str(element, "id");
+        if (elementId === "")
+            continue;
+        instances.push({ id, element: elementId, title: str(i, "title"), tags: tags(i) });
+    }
+    const relationships = [];
+    for (const raw of iterate(deployment, "relationships")) {
+        const r = record(raw);
+        if (r === undefined)
+            continue;
+        const source = record(r["source"]);
+        const target = record(r["target"]);
+        if (source === undefined || target === undefined)
+            continue;
+        const from = str(source, "id");
+        const to = str(target, "id");
+        if (from === "" || to === "")
+            continue;
+        // LikeC4 reports an untitled edge as `title: null` — normalized to the
+        // declared optional exactly as `flattenModel` does for the logical model.
+        const title = typeof r["title"] === "string" ? r["title"] : undefined;
+        relationships.push({ source: from, target: to, ...(title === undefined ? {} : { title }), tags: tags(r) });
+    }
+    return { nodes, instances, relationships };
+}
+//# sourceMappingURL=deployment.js.map

package/dist/core/c4/parsed/deployment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment.js","sourceRoot":"","sources":["../../../../src/core/c4/parsed/deployment.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The DEPLOYMENT model a document declares — which physical nodes exist, which\n * containers are instanced where, and what talks to what across them.\n *\n * A `deployment { }` block has been legal in a docs repo since LikeC4 could\n * parse one, and until this reader existed loam saw none of it. The parser\n * resolved every `instanceOf` — so a container renamed out from under a\n * deployment node already failed the gate — and after that no requirement could\n * name a node, no `#obl-` tag on a datacenter was graded, and the context pack\n * an agent implements from did not mention topology at all. Integrity held at\n * the level of syntax and was absent at the level of requirements. ROADMAP's\n * deployment axis and `meta/docs/features/FEAT-1-the-deployment-axis/` are the\n * item and the specification; this module is its first half.\n *\n * ## Why this is a `parsed/` reader and not a package of its own\n *\n * It is the same job the three modules beside it do: take one corner of\n * LikeC4's parse output and hand back a loam-neutral record, defensively, with\n * its shape assumptions owned outright. `readSpecification`, `readDynamicViews`\n * and `readViewIds` are all called on the line above `flattenModel(model)` in\n * each of loam's three loaders, and so is this. FEAT-1's delta said\n * `src/core/c4/deploy/`; a package holding this alone would be a directory\n * pretending to be a subject (docs/DESIGN.md), and the delta was corrected\n * rather than the code bent to it — which is what an unarchived feature is for.\n *\n * **`parsed/` is now AT its five-file limit.** The next reader here needs a\n * split first, and the seam to split on is the one this file does not share:\n * `dynamic-views.ts` and `view-ids.ts` read `$data`, this one and\n * `specification.ts` read the model surface.\n *\n * ## What is read, and what is deliberately left\n *\n * Nodes, instances and relationships, with the ids, titles and tags each\n * carries. MEASURED at the 1.59.2 pin, and every line of it needed measuring\n * rather than assuming:\n *\n *  - `nodes()` returns deployment NODES only — an `instanceOf` is not among\n *    them, which is why instances are a second list rather than a filter.\n *  - an instance carries the LOGICAL element it deploys as `element.id`, and\n *    that is the whole join back to the C4 model: `eu.a.dbA -> orders.db`.\n *  - both nodes and instances carry `tags`, so `#obl-geo` on a datacenter is\n *    readable — the fail-open case that made this an item.\n *  - a relationship carries `tags` and `metadata` DIRECTLY (`r.metadata`, no\n *    `$relationship` indirection), and both model stages return byte-identical\n *    results, which is what lets `test/likec4-model-parity.test.ts` cover this\n *    read with the substitution it already pins.\n *  - a document with NO `deployment { }` block still returns a deployment\n *    object whose three iterators are empty. Absent and empty are therefore the\n *    same answer here, deliberately: no reader may distinguish \"declares none\"\n *    from \"could not be read\", because the second is what the defensive returns\n *    below produce and a fleet that draws no topology owes loam nothing.\n *\n * `metadata` is NOT carried on the records below, and neither is an instance's\n * `kind`. Both are readable; no check reads them yet, and a field carried\n * before a caller needs it is a field nobody notices going wrong. Add one with\n * the check that consumes it.\n */\n\n/** One deployment node — a region, a datacenter, a cluster; the kinds are the fleet's own. */\nexport interface DeployNode {\n  /** The dotted path LikeC4 gives it: `eu.dcA.k8sA`. */\n  id: string;\n  /** The `deploymentNode` kind the specification declares. */\n  kind: string;\n  title: string;\n  tags: string[];\n}\n\n/** One deployed instance of a logical element. */\nexport interface DeployInstance {\n  id: string;\n  /**\n   * The id of the C4 element this instance deploys — the join back to the\n   * logical model, and the only reason an instance is worth reading at all.\n   */\n  element: string;\n  title: string;\n  tags: string[];\n}\n\n/** One edge between deployment objects — replication, failover, a network hop. */\nexport interface DeployRel {\n  source: string;\n  target: string;\n  title?: string;\n  tags: string[];\n}\n\n/** A document's whole deployment model, flattened. */\nexport interface DeploymentModel {\n  nodes: DeployNode[];\n  instances: DeployInstance[];\n  relationships: DeployRel[];\n}\n\n/** No topology — what an absent block and an unreadable one both come back as. */\nexport const NO_DEPLOYMENT: DeploymentModel = { nodes: [], instances: [], relationships: [] };\n\n/** Is there anything here? The opt-in every deployment check is gated on. */\nexport function hasDeployment(d: DeploymentModel): boolean {\n  return d.nodes.length > 0 || d.instances.length > 0 || d.relationships.length > 0;\n}\n\n/** A record, or nothing — the parse surface hands back `unknown`. */\nfunction record(v: unknown): Record<string, unknown> | undefined {\n  return v && typeof v === \"object\" && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined;\n}\n\n/** An iterable produced by `name()`, or an empty one when the surface is not what we measured. */\nfunction iterate(source: Record<string, unknown>, name: string): unknown[] {\n  const fn = source[name];\n  if (typeof fn !== \"function\") return [];\n  try {\n    const out: unknown = (fn as () => unknown).call(source);\n    // A generator satisfies this; so does an array. Anything else is a shape\n    // change upstream, and the honest answer to one is \"no topology read\".\n    return out !== null && typeof out === \"object\" && Symbol.iterator in (out as object)\n      ? [...(out as Iterable<unknown>)]\n      : [];\n  } catch {\n    return [];\n  }\n}\n\n/** A string field, or the empty string — never `undefined` leaking into a record. */\nfunction str(o: Record<string, unknown>, key: string): string {\n  const v = o[key];\n  return typeof v === \"string\" ? v : \"\";\n}\n\n/** Tags as loam models them: a plain array of strings, always present. */\nfunction tags(o: Record<string, unknown>): string[] {\n  const v = o[\"tags\"];\n  return Array.isArray(v) ? v.filter((t): t is string => typeof t === \"string\") : [];\n}\n\n/**\n * Read the deployment model off an awaited `parsedModel()`.\n *\n * Defensive throughout, in the shape `readViewIds` established: an entry\n * missing the one field that identifies it is DROPPED rather than reported with\n * a hole, and a surface that is not what was measured yields an empty model\n * instead of throwing. A check that cannot see the topology must say\n * could-not-look through its own silence, never fail the fleet's parse.\n */\nexport function readDeployment(model: unknown): DeploymentModel {\n  const root = record(model);\n  if (root === undefined) return NO_DEPLOYMENT;\n  const deployment = record(root[\"deployment\"]);\n  if (deployment === undefined) return NO_DEPLOYMENT;\n\n  const nodes: DeployNode[] = [];\n  for (const raw of iterate(deployment, \"nodes\")) {\n    const n = record(raw);\n    if (n === undefined) continue;\n    const id = str(n, \"id\");\n    if (id === \"\") continue;\n    nodes.push({ id, kind: str(n, \"kind\"), title: str(n, \"title\"), tags: tags(n) });\n  }\n\n  const instances: DeployInstance[] = [];\n  for (const raw of iterate(deployment, \"instances\")) {\n    const i = record(raw);\n    if (i === undefined) continue;\n    const id = str(i, \"id\");\n    // The logical element is the whole point of the record. An instance whose\n    // element cannot be read joins to nothing, so reporting it would put a\n    // deployed thing on the map that no requirement could ever cover.\n    const element = record(i[\"element\"]);\n    if (id === \"\" || element === undefined) continue;\n    const elementId = str(element, \"id\");\n    if (elementId === \"\") continue;\n    instances.push({ id, element: elementId, title: str(i, \"title\"), tags: tags(i) });\n  }\n\n  const relationships: DeployRel[] = [];\n  for (const raw of iterate(deployment, \"relationships\")) {\n    const r = record(raw);\n    if (r === undefined) continue;\n    const source = record(r[\"source\"]);\n    const target = record(r[\"target\"]);\n    if (source === undefined || target === undefined) continue;\n    const from = str(source, \"id\");\n    const to = str(target, \"id\");\n    if (from === \"\" || to === \"\") continue;\n    // LikeC4 reports an untitled edge as `title: null` — normalized to the\n    // declared optional exactly as `flattenModel` does for the logical model.\n    const title = typeof r[\"title\"] === \"string\" ? r[\"title\"] : undefined;\n    relationships.push({ source: from, target: to, ...(title === undefined ? {} : { title }), tags: tags(r) });\n  }\n\n  return { nodes, instances, relationships };\n}\n"]}