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

package/dist/core/arch.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"arch.js","sourceRoot":"","sources":["../../src/core/arch.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The architecture spec axis — the grammar and resolution of `Covers:`.\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 * Three 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/health.ts).\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 */\nimport { elementService, serviceResolver, type Elem, type Rel } from \"./likec4.js\";\nimport type { HealthIds } from \"./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/** 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) return { form: \"edge\", source: edge[1]!.trim(), target: edge[2]!.trim(), raw };\n  return { form: \"element\", id: raw, raw };\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  health: HealthIds;\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/**\n * One `id -> service` resolver per document, not one per lookup.\n *\n * `serviceOf` builds a fresh id map on every call, and this axis calls it twice\n * for every relationship in scope — inside loops that already run over every\n * relationship a service can see. `serviceResolver`'s own doc says it is \"built\n * once per document and shared\"; this is where the Covers axis keeps that\n * promise, since `coversEdge` is exported and its callers hold only the element\n * array.\n *\n * A module-level cache is normally the wrong shape here, because a command runs\n * against whatever directory it was invoked in. This one is safe: the key is the\n * per-invocation `Elem[]` a parse produced, its value is a pure function of that\n * key alone, and nothing in it is derived from the working directory — so two\n * runs can never see each other's answer, and the entry dies with the document.\n * Nothing mutates an `Elem[]` after parse.\n */\nconst RESOLVERS = new WeakMap<Elem[], (id: string) => string>();\n\nfunction resolverFor(elements: Elem[]): (id: string) => string {\n  const cached = RESOLVERS.get(elements);\n  if (cached !== undefined) return cached;\n  const resolver = serviceResolver(elements);\n  RESOLVERS.set(elements, resolver);\n  return resolver;\n}\n\n/** Does an edge entry's side name this relationship endpoint? */\nfunction namesEndpoint(name: string, endpointId: string, elements: Elem[]): boolean {\n  return endpointId === name || resolverFor(elements)(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`. */\nexport function coversEdge(entry: CoversEntry, r: Rel, elements: Elem[]): boolean {\n  return (\n    entry.form === \"edge\" &&\n    namesEndpoint(entry.source, r.source, elements) &&\n    namesEndpoint(entry.target, r.target, elements)\n  );\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));\n    case \"element\":\n      return scope.elements.some((e) => coversElement(entry, e));\n  }\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      // 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  }\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: 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"]}

package/dist/core/asyncapi.js

@@ -1,253 +0,0 @@
-import { isUtf8 } from "node:buffer";
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { parse } from "yaml";
-import { servicePaths } from "./repo.js";
-/**
- * The async contract axis: AsyncAPI 3.0, read the way `core/openapi.ts` reads
- * OpenAPI — a shallow structural walk over the `yaml` parse, never a real
- * AsyncAPI parser. `@asyncapi/parser` would be a fourth runtime dependency
- * (AGENTS.md: adding one is a product decision), and loam needs a slice of the
- * document so thin that the parser's whole model would be dead weight.
- *
- * 3.0 only, deliberately. Its operations are named top-level objects carrying
- * `action: send|receive`, which is the exact analog of an `operationId`; 2.x
- * spells the same thing as `publish`/`subscribe` nested under a channel, where
- * the two words are notoriously ambiguous about whose perspective they take.
- * Supporting one dialect is cheaper than supporting two, and a 2.x document
- * declares no `operations` at all — so it reads as a contract with no messages
- * rather than as a silently mis-parsed one.
- *
- * WHAT THIS READER MUST NEVER DO: look inside a message's `payload`. The payload
- * is JSON Schema today and may be Avro later, and that switch is meant to be a
- * line in the document (`schemaFormat`) rather than a branch in loam. Every
- * check on this axis joins on a message NAME; nothing joins on a field. The day
- * something here reads a `required` array or a `fields` list, the Avro migration
- * stops being free.
- */
-/** How deep a `$ref` chain is followed before the reader gives up. */
-const MAX_REF_DEPTH = 8;
-/**
- * Resolve an internal JSON Pointer (`#/a/b/c`) against the document root.
- *
- * Internal only, matching the OpenAPI axis's documented stance: external
- * references — URLs, file paths, anything not starting `#/` — are out of scope,
- * left untouched and never graded. That is also why authors are told to keep
- * payloads inside the document rather than `$ref`-ing an external `.avsc`: the
- * merge cannot carry what this reader cannot see.
- */
-function resolvePointer(root, ref) {
-    if (typeof ref !== "string" || !ref.startsWith("#/"))
-        return undefined;
-    let node = root;
-    for (const raw of ref.slice(2).split("/")) {
-        // JSON Pointer escaping, `~1` before `~0` so an encoded `~1` survives.
-        const seg = raw.replace(/~1/g, "/").replace(/~0/g, "~");
-        if (node === null || typeof node !== "object")
-            return undefined;
-        node = node[seg];
-    }
-    return node;
-}
-/**
- * Follow `$ref` hops until a node that is not a reference, or the depth budget
- * runs out. The budget is the cycle guard: a document whose `$ref` points at
- * itself is legal YAML, and an unbounded walk would hang the whole validate run
- * rather than reporting a contract nobody can read.
- *
- * Returns the resolved node and the last pointer segment that reached it — the
- * segment is the declaration key, which is the message-name fallback, and it is
- * lost by the time a caller holds only the node.
- */
-function deref(root, node, key) {
-    let current = node;
-    let currentKey = key;
-    for (let hop = 0; hop < MAX_REF_DEPTH; hop += 1) {
-        if (current === null || typeof current !== "object" || Array.isArray(current))
-            break;
-        const ref = current["$ref"];
-        if (typeof ref !== "string")
-            break;
-        const resolved = resolvePointer(root, ref);
-        if (resolved === undefined)
-            return { node: undefined, key: currentKey };
-        const seg = ref.slice(ref.lastIndexOf("/") + 1);
-        current = resolved;
-        // An alias keeps the TARGET's key, not the local one it was filed under: a
-        // channel may list `#/components/messages/PaymentAuthorized` under any alias
-        // it likes, and the fallback name has to be the declaration's own identity
-        // or two services aliasing one message differently would stop joining.
-        currentKey = seg.length > 0 ? seg : currentKey;
-    }
-    return { node: current, key: currentKey };
-}
-/** A message's join token: its `name`, or the key it is declared under. */
-function messageName(node, key) {
-    if (node !== null && typeof node === "object" && !Array.isArray(node)) {
-        const name = node["name"];
-        if (typeof name === "string" && name.trim().length > 0)
-            return name.trim();
-    }
-    return key;
-}
-/** Entries of a mapping node, or nothing — every structural read here goes through it. */
-function entriesOf(node) {
-    if (node === null || typeof node !== "object" || Array.isArray(node))
-        return [];
-    return Object.entries(node);
-}
-/**
- * Read an AsyncAPI 3.0 document into the slice loam joins on: the messages it
- * declares, and which of them it sends and receives.
- *
- * The send/receive sets are what make the spine directional, and the direction
- * is not decoration: on the HTTP axis the PROVIDER owns the contract and a
- * consumer's edge is checked against it, while here the PRODUCER owns the
- * message and a consumer joins to it from another repository entirely. That
- * inversion is why `spine.message-unproduced` has no OpenAPI analog.
- *
- * An unreadable document yields empty sets PLUS the `unreadable` flag, the
- * policy every reader here follows: parsers never diagnose. Swallowing the
- * failure into empty sets would make a broken contract indistinguishable from
- * one that declares nothing, and every inbound edge would be graded
- * `spine.message-undefined` — a false diagnosis pointing at the landscape when
- * the truth is this file.
- */
-export async function readAsyncapi(asyncapiPath, context) {
-    if (context !== undefined)
-        return context.readAsyncapi(asyncapiPath);
-    if (!existsSync(asyncapiPath))
-        return empty();
-    const bytes = await readFile(asyncapiPath);
-    // Bytes that are not UTF-8 are as unreadable as broken YAML and for a worse
-    // reason: `toString("utf8")` substitutes U+FFFD and hands the parser a
-    // document nobody wrote. The openapi axis learned this the same way.
-    if (!isUtf8(bytes))
-        return { ...empty(), unreadable: true, error: "file is not valid UTF-8" };
-    let doc;
-    try {
-        doc = parse(bytes.toString("utf8"));
-    }
-    catch (e) {
-        return { ...empty(), unreadable: true, error: e instanceof Error ? e.message : String(e) };
-    }
-    // A scalar or sequence document has no mapping to look `channels` up in, so
-    // nothing can be concluded from it. null (an empty file) stays readable — it
-    // declares nothing, and says so honestly.
-    if (doc !== null && (typeof doc !== "object" || Array.isArray(doc))) {
-        return { ...empty(), unreadable: true, error: "document is not a YAML mapping" };
-    }
-    if (doc === null)
-        return empty();
-    const root = doc;
-    const messages = [];
-    const seen = new Map();
-    const declare = (name, slot) => {
-        messages.push({ name, slot });
-        seen.set(name, [...(seen.get(name) ?? []), slot]);
-    };
-    // `components.messages` — the ordinary place a message is declared.
-    for (const [key, node] of entriesOf(root["components"]?.["messages"])) {
-        declare(messageName(node, key), `components.messages.${key}`);
-    }
-    // `channels.<ck>.messages.<mk>` — an entry here is either an ALIAS of a
-    // components declaration (a `$ref`) or an inline declaration of its own. Only
-    // the second is a new slot: counting an alias would report every properly
-    // factored document as declaring each message twice, which is the shape the
-    // spec's own examples use.
-    const channelMessages = new Map();
-    for (const [ck, channel] of entriesOf(root["channels"])) {
-        const names = [];
-        for (const [mk, entry] of entriesOf(channel?.["messages"])) {
-            const isAlias = entry !== null && typeof entry === "object" && !Array.isArray(entry) && "$ref" in entry;
-            const { node, key } = deref(root, entry, mk);
-            const name = messageName(node, key);
-            names.push(name);
-            if (!isAlias)
-                declare(name, `channels.${ck}.messages.${mk}`);
-        }
-        channelMessages.set(ck, names);
-    }
-    const sent = new Set();
-    const received = new Set();
-    for (const [, operation] of entriesOf(root["operations"])) {
-        const op = operation;
-        const action = op?.["action"];
-        if (action !== "send" && action !== "receive")
-            continue;
-        const into = action === "send" ? sent : received;
-        // The channel this operation acts on, by pointer — its key is what the
-        // fallback below indexes.
-        const channelRef = op?.["channel"]?.["$ref"];
-        const channelKey = typeof channelRef === "string" ? channelRef.slice(channelRef.lastIndexOf("/") + 1) : undefined;
-        const listed = op?.["messages"];
-        if (Array.isArray(listed) && listed.length > 0) {
-            for (const entry of listed) {
-                const { node, key } = deref(root, entry, "");
-                // A pointer that resolves nowhere contributes no name rather than an
-                // empty one: a phantom "" would join to nothing and read as a message
-                // the service produces.
-                if (node === undefined && key === "")
-                    continue;
-                const name = messageName(node, key);
-                if (name.length > 0)
-                    into.add(name);
-            }
-            continue;
-        }
-        // AsyncAPI 3: an operation that lists no messages applies to every message
-        // of its channel. Omitting the list is the normal shape of a minimal
-        // hand-written contract — exactly what a fleet with no registry writes — so
-        // reading it as "produces nothing" would report the common case broken.
-        if (channelKey !== undefined)
-            for (const name of channelMessages.get(channelKey) ?? [])
-                into.add(name);
-    }
-    const duplicateNames = [...seen].filter(([, slots]) => slots.length > 1).map(([name]) => name);
-    return { messages, sent: [...sent], received: [...received], duplicateNames, unreadable: false };
-}
-function empty() {
-    return { messages: [], sent: [], received: [], duplicateNames: [], unreadable: false };
-}
-/** The slots one message name is declared in — what `asyncapi.duplicate-message` names. */
-export function slotsOf(doc, name) {
-    return doc.messages.filter((m) => m.name === name).map((m) => m.slot);
-}
-/**
- * Which services in the fleet declare an `action: send` for each message name.
- *
- * The one question on this axis that no single repository can answer, and the
- * reason `validate --service` reads more than its own service here: a consumer
- * joins to a message the PRODUCER owns, so "does anybody publish this" is a
- * fleet fact. Zero producers is `spine.message-unproduced`; two are
- * `asyncapi.message-contested`, where every consumer's join picks one
- * arbitrarily.
- *
- * The two answers rest on different evidence, and only one of them survives an
- * unreadable contract. Finding two producers is POSITIVE evidence and stays
- * true whatever else in the fleet fails to parse. Finding none is an argument
- * from absence, and one broken file makes it worthless — skipping that service
- * silently would turn its outage into one `spine.message-unproduced` per
- * consuming edge across the whole fleet, every one of them pointing at the
- * wrong repository. So the unreadable services are reported rather than
- * skipped, and the caller suspends the negative answer while any exist.
- *
- * The cost is N small YAML parses, not N LikeC4 workspace spins — the latter is
- * what makes `validate --all` expensive (SCHEMA.md, "Operating at fleet scale"),
- * and a context memoizes these reads across the run.
- */
-export async function producersByMessage(docsDir, services, context) {
-    const byMessage = new Map();
-    const unreadable = [];
-    for (const service of services) {
-        const doc = await readAsyncapi(servicePaths(docsDir, service).asyncapi, context);
-        if (doc.unreadable) {
-            unreadable.push(service);
-            continue;
-        }
-        for (const name of doc.sent)
-            byMessage.set(name, [...(byMessage.get(name) ?? []), service]);
-    }
-    return { byMessage, unreadable };
-}
-//# sourceMappingURL=asyncapi.js.map

package/dist/core/asyncapi.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"asyncapi.js","sourceRoot":"","sources":["../../src/core/asyncapi.ts"],"names":[],"mappings":"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","sourcesContent":["import { isUtf8 } from \"node:buffer\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { parse } from \"yaml\";\nimport type { FleetContext } from \"./fleet-context.js\";\nimport { servicePaths } from \"./repo.js\";\n\n/**\n * The async contract axis: AsyncAPI 3.0, read the way `core/openapi.ts` reads\n * OpenAPI — a shallow structural walk over the `yaml` parse, never a real\n * AsyncAPI parser. `@asyncapi/parser` would be a fourth runtime dependency\n * (AGENTS.md: adding one is a product decision), and loam needs a slice of the\n * document so thin that the parser's whole model would be dead weight.\n *\n * 3.0 only, deliberately. Its operations are named top-level objects carrying\n * `action: send|receive`, which is the exact analog of an `operationId`; 2.x\n * spells the same thing as `publish`/`subscribe` nested under a channel, where\n * the two words are notoriously ambiguous about whose perspective they take.\n * Supporting one dialect is cheaper than supporting two, and a 2.x document\n * declares no `operations` at all — so it reads as a contract with no messages\n * rather than as a silently mis-parsed one.\n *\n * WHAT THIS READER MUST NEVER DO: look inside a message's `payload`. The payload\n * is JSON Schema today and may be Avro later, and that switch is meant to be a\n * line in the document (`schemaFormat`) rather than a branch in loam. Every\n * check on this axis joins on a message NAME; nothing joins on a field. The day\n * something here reads a `required` array or a `fields` list, the Avro migration\n * stops being free.\n */\n\n/** How deep a `$ref` chain is followed before the reader gives up. */\nconst MAX_REF_DEPTH = 8;\n\n/** One message declaration, as the reader sees it. */\nexport interface EventMessage {\n  /**\n   * The join token — what a landscape edge's `metadata { publishes }` and a\n   * requirement's `Publishes:` line name.\n   *\n   * The Message Object's own `name` when it has one, otherwise the key it is\n   * declared under. Both are legal AsyncAPI, and the key is what an author who\n   * never wrote a `name` would reasonably expect to reference; falling back to\n   * it means a minimal hand-written contract still joins to the spine.\n   */\n  name: string;\n  /**\n   * Where it was declared — `components.messages.<key>` or\n   * `channels.<key>.messages.<key>`. Carried so `asyncapi.duplicate-message` can\n   * name both slots instead of only saying that a name repeats, the way\n   * `openapi.duplicate-operationid` names both `METHOD /path` slots.\n   */\n  slot: string;\n}\n\n/** The parse of one AsyncAPI document: what it declares, and whether it could be read at all. */\nexport interface AsyncapiDoc {\n  /** Every message declaration in the document, in document order. */\n  messages: EventMessage[];\n  /** Message names reachable from an `action: send` operation — what this service PRODUCES. */\n  sent: string[];\n  /** Message names reachable from an `action: receive` operation — what this service CONSUMES. */\n  received: string[];\n  /**\n   * Names declared in more than one slot. Every join on this axis is by name, so\n   * two slots claiming one name is the same ambiguity `openapi.duplicate-operationid`\n   * grades: the join picks one arbitrarily and the other declaration is invisible.\n   */\n  duplicateNames: string[];\n  /**\n   * True when the file EXISTS but cannot be read as an AsyncAPI document —\n   * broken YAML, non-UTF-8 bytes, or a document that is not a mapping. A missing\n   * file is not unreadable (absence is `service.no-asyncapi`'s question), and an\n   * empty one parses to null and honestly declares nothing.\n   */\n  unreadable: boolean;\n  /** The parser's own message, when there is one to quote back. */\n  error?: string;\n}\n\n/**\n * Resolve an internal JSON Pointer (`#/a/b/c`) against the document root.\n *\n * Internal only, matching the OpenAPI axis's documented stance: external\n * references — URLs, file paths, anything not starting `#/` — are out of scope,\n * left untouched and never graded. That is also why authors are told to keep\n * payloads inside the document rather than `$ref`-ing an external `.avsc`: the\n * merge cannot carry what this reader cannot see.\n */\nfunction resolvePointer(root: unknown, ref: unknown): unknown {\n  if (typeof ref !== \"string\" || !ref.startsWith(\"#/\")) return undefined;\n  let node = root;\n  for (const raw of ref.slice(2).split(\"/\")) {\n    // JSON Pointer escaping, `~1` before `~0` so an encoded `~1` survives.\n    const seg = raw.replace(/~1/g, \"/\").replace(/~0/g, \"~\");\n    if (node === null || typeof node !== \"object\") return undefined;\n    node = (node as Record<string, unknown>)[seg];\n  }\n  return node;\n}\n\n/**\n * Follow `$ref` hops until a node that is not a reference, or the depth budget\n * runs out. The budget is the cycle guard: a document whose `$ref` points at\n * itself is legal YAML, and an unbounded walk would hang the whole validate run\n * rather than reporting a contract nobody can read.\n *\n * Returns the resolved node and the last pointer segment that reached it — the\n * segment is the declaration key, which is the message-name fallback, and it is\n * lost by the time a caller holds only the node.\n */\nfunction deref(root: unknown, node: unknown, key: string): { node: unknown; key: string } {\n  let current = node;\n  let currentKey = key;\n  for (let hop = 0; hop < MAX_REF_DEPTH; hop += 1) {\n    if (current === null || typeof current !== \"object\" || Array.isArray(current)) break;\n    const ref = (current as Record<string, unknown>)[\"$ref\"];\n    if (typeof ref !== \"string\") break;\n    const resolved = resolvePointer(root, ref);\n    if (resolved === undefined) return { node: undefined, key: currentKey };\n    const seg = ref.slice(ref.lastIndexOf(\"/\") + 1);\n    current = resolved;\n    // An alias keeps the TARGET's key, not the local one it was filed under: a\n    // channel may list `#/components/messages/PaymentAuthorized` under any alias\n    // it likes, and the fallback name has to be the declaration's own identity\n    // or two services aliasing one message differently would stop joining.\n    currentKey = seg.length > 0 ? seg : currentKey;\n  }\n  return { node: current, key: currentKey };\n}\n\n/** A message's join token: its `name`, or the key it is declared under. */\nfunction messageName(node: unknown, key: string): string {\n  if (node !== null && typeof node === \"object\" && !Array.isArray(node)) {\n    const name = (node as Record<string, unknown>)[\"name\"];\n    if (typeof name === \"string\" && name.trim().length > 0) return name.trim();\n  }\n  return key;\n}\n\n/** Entries of a mapping node, or nothing — every structural read here goes through it. */\nfunction entriesOf(node: unknown): [string, unknown][] {\n  if (node === null || typeof node !== \"object\" || Array.isArray(node)) return [];\n  return Object.entries(node as Record<string, unknown>);\n}\n\n/**\n * Read an AsyncAPI 3.0 document into the slice loam joins on: the messages it\n * declares, and which of them it sends and receives.\n *\n * The send/receive sets are what make the spine directional, and the direction\n * is not decoration: on the HTTP axis the PROVIDER owns the contract and a\n * consumer's edge is checked against it, while here the PRODUCER owns the\n * message and a consumer joins to it from another repository entirely. That\n * inversion is why `spine.message-unproduced` has no OpenAPI analog.\n *\n * An unreadable document yields empty sets PLUS the `unreadable` flag, the\n * policy every reader here follows: parsers never diagnose. Swallowing the\n * failure into empty sets would make a broken contract indistinguishable from\n * one that declares nothing, and every inbound edge would be graded\n * `spine.message-undefined` — a false diagnosis pointing at the landscape when\n * the truth is this file.\n */\nexport async function readAsyncapi(asyncapiPath: string, context?: FleetContext): Promise<AsyncapiDoc> {\n  if (context !== undefined) return context.readAsyncapi(asyncapiPath);\n  if (!existsSync(asyncapiPath)) return empty();\n  const bytes = await readFile(asyncapiPath);\n  // Bytes that are not UTF-8 are as unreadable as broken YAML and for a worse\n  // reason: `toString(\"utf8\")` substitutes U+FFFD and hands the parser a\n  // document nobody wrote. The openapi axis learned this the same way.\n  if (!isUtf8(bytes)) return { ...empty(), unreadable: true, error: \"file is not valid UTF-8\" };\n  let doc: unknown;\n  try {\n    doc = parse(bytes.toString(\"utf8\"));\n  } catch (e) {\n    return { ...empty(), unreadable: true, error: e instanceof Error ? e.message : String(e) };\n  }\n  // A scalar or sequence document has no mapping to look `channels` up in, so\n  // nothing can be concluded from it. null (an empty file) stays readable — it\n  // declares nothing, and says so honestly.\n  if (doc !== null && (typeof doc !== \"object\" || Array.isArray(doc))) {\n    return { ...empty(), unreadable: true, error: \"document is not a YAML mapping\" };\n  }\n  if (doc === null) return empty();\n\n  const root = doc as Record<string, unknown>;\n  const messages: EventMessage[] = [];\n  const seen = new Map<string, string[]>();\n  const declare = (name: string, slot: string): void => {\n    messages.push({ name, slot });\n    seen.set(name, [...(seen.get(name) ?? []), slot]);\n  };\n\n  // `components.messages` — the ordinary place a message is declared.\n  for (const [key, node] of entriesOf((root[\"components\"] as Record<string, unknown> | undefined)?.[\"messages\"])) {\n    declare(messageName(node, key), `components.messages.${key}`);\n  }\n\n  // `channels.<ck>.messages.<mk>` — an entry here is either an ALIAS of a\n  // components declaration (a `$ref`) or an inline declaration of its own. Only\n  // the second is a new slot: counting an alias would report every properly\n  // factored document as declaring each message twice, which is the shape the\n  // spec's own examples use.\n  const channelMessages = new Map<string, string[]>();\n  for (const [ck, channel] of entriesOf(root[\"channels\"])) {\n    const names: string[] = [];\n    for (const [mk, entry] of entriesOf((channel as Record<string, unknown> | null)?.[\"messages\"])) {\n      const isAlias =\n        entry !== null && typeof entry === \"object\" && !Array.isArray(entry) && \"$ref\" in (entry as object);\n      const { node, key } = deref(root, entry, mk);\n      const name = messageName(node, key);\n      names.push(name);\n      if (!isAlias) declare(name, `channels.${ck}.messages.${mk}`);\n    }\n    channelMessages.set(ck, names);\n  }\n\n  const sent = new Set<string>();\n  const received = new Set<string>();\n  for (const [, operation] of entriesOf(root[\"operations\"])) {\n    const op = operation as Record<string, unknown> | null;\n    const action = op?.[\"action\"];\n    if (action !== \"send\" && action !== \"receive\") continue;\n    const into = action === \"send\" ? sent : received;\n    // The channel this operation acts on, by pointer — its key is what the\n    // fallback below indexes.\n    const channelRef = (op?.[\"channel\"] as Record<string, unknown> | undefined)?.[\"$ref\"];\n    const channelKey = typeof channelRef === \"string\" ? channelRef.slice(channelRef.lastIndexOf(\"/\") + 1) : undefined;\n    const listed = op?.[\"messages\"];\n    if (Array.isArray(listed) && listed.length > 0) {\n      for (const entry of listed) {\n        const { node, key } = deref(root, entry, \"\");\n        // A pointer that resolves nowhere contributes no name rather than an\n        // empty one: a phantom \"\" would join to nothing and read as a message\n        // the service produces.\n        if (node === undefined && key === \"\") continue;\n        const name = messageName(node, key);\n        if (name.length > 0) into.add(name);\n      }\n      continue;\n    }\n    // AsyncAPI 3: an operation that lists no messages applies to every message\n    // of its channel. Omitting the list is the normal shape of a minimal\n    // hand-written contract — exactly what a fleet with no registry writes — so\n    // reading it as \"produces nothing\" would report the common case broken.\n    if (channelKey !== undefined) for (const name of channelMessages.get(channelKey) ?? []) into.add(name);\n  }\n\n  const duplicateNames = [...seen].filter(([, slots]) => slots.length > 1).map(([name]) => name);\n  return { messages, sent: [...sent], received: [...received], duplicateNames, unreadable: false };\n}\n\nfunction empty(): AsyncapiDoc {\n  return { messages: [], sent: [], received: [], duplicateNames: [], unreadable: false };\n}\n\n/** The slots one message name is declared in — what `asyncapi.duplicate-message` names. */\nexport function slotsOf(doc: AsyncapiDoc, name: string): string[] {\n  return doc.messages.filter((m) => m.name === name).map((m) => m.slot);\n}\n\n/** Who produces what across the fleet, and whether that view is complete. */\nexport interface FleetProducers {\n  /** Message name → the services declaring an `action: send` for it. */\n  byMessage: Map<string, string[]>;\n  /**\n   * Services whose `asyncapi.yaml` exists and could not be read. Non-empty means\n   * the ABSENCE of a producer proves nothing: one of these files may well\n   * declare the message, and nobody can tell without fixing it first.\n   */\n  unreadable: string[];\n}\n\n/**\n * Which services in the fleet declare an `action: send` for each message name.\n *\n * The one question on this axis that no single repository can answer, and the\n * reason `validate --service` reads more than its own service here: a consumer\n * joins to a message the PRODUCER owns, so \"does anybody publish this\" is a\n * fleet fact. Zero producers is `spine.message-unproduced`; two are\n * `asyncapi.message-contested`, where every consumer's join picks one\n * arbitrarily.\n *\n * The two answers rest on different evidence, and only one of them survives an\n * unreadable contract. Finding two producers is POSITIVE evidence and stays\n * true whatever else in the fleet fails to parse. Finding none is an argument\n * from absence, and one broken file makes it worthless — skipping that service\n * silently would turn its outage into one `spine.message-unproduced` per\n * consuming edge across the whole fleet, every one of them pointing at the\n * wrong repository. So the unreadable services are reported rather than\n * skipped, and the caller suspends the negative answer while any exist.\n *\n * The cost is N small YAML parses, not N LikeC4 workspace spins — the latter is\n * what makes `validate --all` expensive (SCHEMA.md, \"Operating at fleet scale\"),\n * and a context memoizes these reads across the run.\n */\nexport async function producersByMessage(\n  docsDir: string,\n  services: readonly string[],\n  context?: FleetContext,\n): Promise<FleetProducers> {\n  const byMessage = new Map<string, string[]>();\n  const unreadable: string[] = [];\n  for (const service of services) {\n    const doc = await readAsyncapi(servicePaths(docsDir, service).asyncapi, context);\n    if (doc.unreadable) {\n      unreadable.push(service);\n      continue;\n    }\n    for (const name of doc.sent) byMessage.set(name, [...(byMessage.get(name) ?? []), service]);\n  }\n  return { byMessage, unreadable };\n}\n"]}