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

package/dist/core/asyncapi/merge/pin.js

@@ -0,0 +1,83 @@
+/**
+ * The pin that tells a QUOTE from an EDIT, on the event axis.
+ *
+ * A feature's asyncapi.yaml is a complete document, so most of what it spells
+ * is quotation: the author restated the living contract around the slot they
+ * were changing. Without a pin the merge cannot tell the two apart and
+ * upserts both — the exact silent-revert the OpenAPI axis's pin closed, with
+ * no overlap between two features required, just two deltas over one service.
+ *
+ * Separate from `./merge.ts` because this is `loam rebase`'s half: it plans
+ * the pins a delta is missing, while the merge only ever reads pins already
+ * written. Slot-keyed over the three named sections exactly as the merge
+ * upserts (core/asyncapi/digest.ts owns the walker and the section→path
+ * spelling); an inline channel message is channel-slot interior and is never
+ * pinned on its own — SCHEMA.md's recorded decision.
+ */
+import { isMap } from "yaml";
+import { writeTreeOver } from "../../openapi/contract-tree.js";
+import { asyncapiRefusal } from "./error.js";
+import { readEventTree, slotPair } from "./markers.js";
+import { ASYNCAPI_BASELINE_KEY, asyncapiSlots, slotDigest, slotKey, slotsByKey, } from "../digest.js";
+/**
+ * Pin every slot in a feature contract against the living one — what
+ * `loam rebase` writes on this axis.
+ *
+ * The pin is always `slotDigest` of the LIVING slot, never of the delta's
+ * own, and that single rule produces both merge verdicts by itself: a slot
+ * the author only QUOTED is byte-equal to living, so its pin equals its own
+ * content and classifies as a quote; one the author EDITED differs from its
+ * pin, so the merge writes it. A slot the living document lacks is
+ * `unresolved` and correct — there is no living version of a channel,
+ * operation or message the contract does not carry yet.
+ */
+export function pinAsyncapiSlots(featureText, livingText, service) {
+    const { doc, plain: featPlain } = readEventTree(featureText, "feature", service);
+    const { plain: livingPlain } = readEventTree(livingText, "living", service);
+    const livingBySlot = slotsByKey(asyncapiSlots(livingPlain));
+    const pins = [];
+    let edited = false;
+    for (const slot of asyncapiSlots(featPlain)) {
+        // A removal marker asserts a slot rather than restating it, so it has
+        // nothing to be based on; `asyncapi.remove-target-missing/-mismatch`
+        // are what guard it against a living slot that moved under it.
+        if (slot.remove)
+            continue;
+        const at = { section: slot.section, key: slot.key };
+        const from = slot.basedOn ?? null;
+        const living = livingBySlot.get(slotKey(slot));
+        if (living === undefined || living.node === null || typeof living.node !== "object" || Array.isArray(living.node)) {
+            pins.push({ ...at, status: "unresolved", from, to: null });
+            continue;
+        }
+        const digest = slotDigest(living.node);
+        if (from === digest) {
+            pins.push({ ...at, status: "unchanged", from: digest, to: digest });
+            continue;
+        }
+        // Located string-matched through the same door as every other slot
+        // access (markers.ts's slotPair): a channel written `404:` is the YAML
+        // number 404, which a raw `getIn("404")` misses — the miss used to grade
+        // every non-string-keyed slot `unwritable`, with an alias diagnosis
+        // nothing in the document backed, and the gate's own remedy was the
+        // command that had just refused. What stays refused: an aliased slot
+        // value (one shared value backs every use of an anchor, so stamping
+        // through it would pin every other use too — the OpenAPI pin's refusal,
+        // for the same data-loss reason) and a slot whose key is not a scalar,
+        // which no string can address.
+        const pair = slotPair(doc, slot.section, slot.key);
+        if (pair === undefined || !isMap(pair.value)) {
+            pins.push({ ...at, status: "unwritable", from, to: null });
+            continue;
+        }
+        pins.push({ ...at, status: from === null ? "pinned" : "repinned", from, to: digest });
+        pair.value.set(ASYNCAPI_BASELINE_KEY, digest);
+        edited = true;
+    }
+    if (!edited)
+        return { text: null, pins };
+    // Over the author's text, so the pins are the only lines this run changes
+    // (`writeTreeOver` says what re-serializing cost).
+    return { text: writeTreeOver(doc, featureText, asyncapiRefusal("feature", service)), pins };
+}
+//# sourceMappingURL=pin.js.map

package/dist/core/asyncapi/merge/pin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pin.js","sourceRoot":"","sources":["../../../../src/core/asyncapi/merge/pin.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The pin that tells a QUOTE from an EDIT, on the event axis.\n *\n * A feature's asyncapi.yaml is a complete document, so most of what it spells\n * is quotation: the author restated the living contract around the slot they\n * were changing. Without a pin the merge cannot tell the two apart and\n * upserts both — the exact silent-revert the OpenAPI axis's pin closed, with\n * no overlap between two features required, just two deltas over one service.\n *\n * Separate from `./merge.ts` because this is `loam rebase`'s half: it plans\n * the pins a delta is missing, while the merge only ever reads pins already\n * written. Slot-keyed over the three named sections exactly as the merge\n * upserts (core/asyncapi/digest.ts owns the walker and the section→path\n * spelling); an inline channel message is channel-slot interior and is never\n * pinned on its own — SCHEMA.md's recorded decision.\n */\nimport { isMap } from \"yaml\";\nimport { writeTreeOver } from \"../../openapi/contract-tree.js\";\nimport { asyncapiRefusal } from \"./error.js\";\nimport { readEventTree, slotPair } from \"./markers.js\";\nimport {\n  ASYNCAPI_BASELINE_KEY,\n  asyncapiSlots,\n  slotDigest,\n  slotKey,\n  slotsByKey,\n  type AsyncapiSection,\n} from \"../digest.js\";\n\n/** What happened to one slot's `x-loam-based-on`. */\nexport interface AsyncapiSlotPin {\n  section: AsyncapiSection;\n  key: string;\n  status:\n    /** It had no pin and now has one. */\n    | \"pinned\"\n    /** It named an older living version; it now names the current one. */\n    | \"repinned\"\n    /** It already named the current living version — no write. */\n    | \"unchanged\"\n    /** The living contract has no slot at this (section, key): this feature is adding it. */\n    | \"unresolved\"\n    /** Written as a YAML alias (one shared value backs every use) or under a key no string can address — loam will not stamp through either. */\n    | \"unwritable\";\n  from: string | null;\n  to: string | null;\n}\n\nexport interface AsyncapiPinPlan {\n  /** The rewritten contract, or null when no pin changes. */\n  text: string | null;\n  pins: AsyncapiSlotPin[];\n}\n\n/**\n * Pin every slot in a feature contract against the living one — what\n * `loam rebase` writes on this axis.\n *\n * The pin is always `slotDigest` of the LIVING slot, never of the delta's\n * own, and that single rule produces both merge verdicts by itself: a slot\n * the author only QUOTED is byte-equal to living, so its pin equals its own\n * content and classifies as a quote; one the author EDITED differs from its\n * pin, so the merge writes it. A slot the living document lacks is\n * `unresolved` and correct — there is no living version of a channel,\n * operation or message the contract does not carry yet.\n */\nexport function pinAsyncapiSlots(featureText: string, livingText: string, service: string): AsyncapiPinPlan {\n  const { doc, plain: featPlain } = readEventTree(featureText, \"feature\", service);\n  const { plain: livingPlain } = readEventTree(livingText, \"living\", service);\n\n  const livingBySlot = slotsByKey(asyncapiSlots(livingPlain));\n  const pins: AsyncapiSlotPin[] = [];\n  let edited = false;\n  for (const slot of asyncapiSlots(featPlain)) {\n    // A removal marker asserts a slot rather than restating it, so it has\n    // nothing to be based on; `asyncapi.remove-target-missing/-mismatch`\n    // are what guard it against a living slot that moved under it.\n    if (slot.remove) continue;\n\n    const at = { section: slot.section, key: slot.key };\n    const from = slot.basedOn ?? null;\n    const living = livingBySlot.get(slotKey(slot));\n    if (living === undefined || living.node === null || typeof living.node !== \"object\" || Array.isArray(living.node)) {\n      pins.push({ ...at, status: \"unresolved\", from, to: null });\n      continue;\n    }\n    const digest = slotDigest(living.node);\n    if (from === digest) {\n      pins.push({ ...at, status: \"unchanged\", from: digest, to: digest });\n      continue;\n    }\n    // Located string-matched through the same door as every other slot\n    // access (markers.ts's slotPair): a channel written `404:` is the YAML\n    // number 404, which a raw `getIn(\"404\")` misses — the miss used to grade\n    // every non-string-keyed slot `unwritable`, with an alias diagnosis\n    // nothing in the document backed, and the gate's own remedy was the\n    // command that had just refused. What stays refused: an aliased slot\n    // value (one shared value backs every use of an anchor, so stamping\n    // through it would pin every other use too — the OpenAPI pin's refusal,\n    // for the same data-loss reason) and a slot whose key is not a scalar,\n    // which no string can address.\n    const pair = slotPair(doc, slot.section, slot.key);\n    if (pair === undefined || !isMap(pair.value)) {\n      pins.push({ ...at, status: \"unwritable\", from, to: null });\n      continue;\n    }\n    pins.push({ ...at, status: from === null ? \"pinned\" : \"repinned\", from, to: digest });\n    pair.value.set(ASYNCAPI_BASELINE_KEY, digest);\n    edited = true;\n  }\n\n  if (!edited) return { text: null, pins };\n  // Over the author's text, so the pins are the only lines this run changes\n  // (`writeTreeOver` says what re-serializing cost).\n  return { text: writeTreeOver(doc, featureText, asyncapiRefusal(\"feature\", service)), pins };\n}\n"]}

package/dist/core/asyncapi/model.js

@@ -0,0 +1,11 @@
+/**
+ * The read model of one AsyncAPI document — what `./read.ts`'s walk produces
+ * and every consumer of the axis branches on. Split from `read.ts` when the
+ * `asyncapiFromText` extraction pushed that module past the 300-line ceiling:
+ * the walk and its result are two subjects (`read.ts` says HOW a document is
+ * read, this file says WHAT a read answers), and the type block is the seam
+ * that already existed. The doctrine comments travel with the fields they
+ * explain — they are the documentation of the model, not of the walk.
+ */
+export {};
+//# sourceMappingURL=model.js.map

package/dist/core/asyncapi/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/core/asyncapi/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * The read model of one AsyncAPI document — what `./read.ts`'s walk produces\n * and every consumer of the axis branches on. Split from `read.ts` when the\n * `asyncapiFromText` extraction pushed that module past the 300-line ceiling:\n * the walk and its result are two subjects (`read.ts` says HOW a document is\n * read, this file says WHAT a read answers), and the type block is the seam\n * that already existed. The doctrine comments travel with the fields they\n * explain — they are the documentation of the model, not of the walk.\n */\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   * The declaration plus every internal `$ref` it reaches, transitively — the\n   * OpenAPI axis's `closureDigester` (core/openapi/digest.ts), so a payload\n   * schema factored into `components.schemas` still moves it. Content equality\n   * only, and so inside the stance read.ts states: what `loam diff` compares to\n   * say a message changed, never a join on a payload field. Absent on a removal\n   * marker, which declares nothing to compare.\n   */\n  closureDigest?: string;\n  /**\n   * Present when the declaration's payload defines no shape a consumer could\n   * code against (`payloadUndeclared`, depth.ts). Set only when true, and\n   * never set for a payload declaring a non-JSON `schemaFormat`.\n   */\n  payloadEmpty?: true;\n  /**\n   * Present when the declaration carries `x-loam-remove: true` — a FEATURE\n   * delta retiring it. A marker asserts a slot rather than declaring a\n   * message, so it joins nothing: excluded from sent/received and from\n   * duplicate counting, the discipline `core/openapi/doc.ts` set for\n   * operation markers. Set only when true, like `payloadEmpty`.\n   */\n  remove?: true;\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  /** Internal `#/` refs that resolve to nothing in this document (depth.ts). */\n  danglingRefs: string[];\n  /**\n   * Where `x-loam-remove: true` appears — at ANY depth (digest.ts's\n   * `removalMarkerPaths`): the three slot depths the format spec gives the\n   * key meaning at, inline channel messages (channel-slot interior the merge\n   * strips at that nested depth), and every place the key means nothing —\n   * the document root, `info`, a `components` sibling. Feature-only\n   * bookkeeping wherever it sits: `validate` grades any of these in a LIVING\n   * contract as `asyncapi.remove-marker-living`, and the sweep is as deep as\n   * the strip so a leaked marker can never be invisible to it.\n   */\n  markers: string[];\n}\n"]}

package/dist/core/asyncapi/producers.js

@@ -0,0 +1,50 @@
+/**
+ * Who produces what across the fleet, read one contract at a time.
+ *
+ * Separate from `./read.ts` because it asks a question no single document can
+ * answer: a message's producer is a claim about some OTHER service's contract,
+ * so this walk is the only part of the axis whose answer depends on how much of
+ * the fleet was readable. That incompleteness is a value it returns, not a
+ * failure it hides — a consumer check that treated an unreadable producer as
+ * "nobody sends this" would report a phantom orphan.
+ */
+import { readAsyncapi } from "./read.js";
+import { locateServicePaths } from "../repo/service-target.js";
+/**
+ * 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((await locateServicePaths(docsDir, service, context)).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=producers.js.map

package/dist/core/asyncapi/producers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"producers.js","sourceRoot":"","sources":["../../../src/core/asyncapi/producers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAe/D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAgB,EAChB,QAAoC,EACpC,OAAsB;IAEtB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC9C,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,MAAM,YAAY,CAAC,CAAC,MAAM,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACxG,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;YACnB,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzB,SAAS;QACX,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,IAAI;YAAE,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;AACnC,CAAC","sourcesContent":["/**\n * Who produces what across the fleet, read one contract at a time.\n *\n * Separate from `./read.ts` because it asks a question no single document can\n * answer: a message's producer is a claim about some OTHER service's contract,\n * so this walk is the only part of the axis whose answer depends on how much of\n * the fleet was readable. That incompleteness is a value it returns, not a\n * failure it hides — a consumer check that treated an unreadable producer as\n * \"nobody sends this\" would report a phantom orphan.\n */\nimport { readAsyncapi } from \"./read.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\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: DocsDir,\n  services: readonly PathableService[],\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((await locateServicePaths(docsDir, service, context)).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\n"]}

package/dist/core/asyncapi/read.js

@@ -0,0 +1,263 @@
+import { isUtf8 } from "node:buffer";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { parse } from "yaml";
+import { danglingRefs, deref, payloadUndeclared } from "./depth.js";
+import { entriesOf, isSlotRemoval, removalMarkerPaths } from "./digest.js";
+import { closureDigester } from "../openapi/digest.js";
+/**
+ * The async contract axis: AsyncAPI 3.0, read the way `core/openapi/doc.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. A 2.x (or 1.x)
+ * document declares no `operations` at all, and it used to read as a contract
+ * with no messages: one `asyncapi.yaml` copied in from an older service turned
+ * into a `spine.message-undefined` per landscape edge, a
+ * `spec-event.message-undefined` per requirement and a knock-on
+ * `spine.message-unproduced` on every consumer, none of them naming the
+ * version and every fix text saying "declare the operation" about a file that
+ * does declare it, as `publish`/`subscribe`. That is exactly the false
+ * diagnosis the unreadable policy below exists to prevent, so an older
+ * version now reads as UNREADABLE (`asyncapiDocOf`): one `asyncapi.invalid`
+ * naming the version and the upgrade command, and nothing graded against it.
+ * `loam diff` skips such a document when the base ref holds the same bytes
+ * (core/diff/semantic.ts's `UNTOUCHED_SKIPS`); without that, one unconverted
+ * file suspended the event axis on every run and failed every PR's diff.
+ *
+ * WHAT THIS READER MUST NEVER DO: join on anything 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, and nothing under `payload` may ever contribute one. The day
+ * something here reads a `required` array or a `fields` list INTO A JOIN, the
+ * Avro migration stops being free. The one look the reader takes inside is
+ * `payloadUndeclared` (depth.ts) — a presence probe that checks whether any
+ * shape was declared at all, reads key existence and never a value, and skips
+ * any payload declaring a non-JSON `schemaFormat`, so the stance holds. The
+ * slot digests (./digest.ts) are COMPATIBLE with it, not an exception: they
+ * hash payload bytes as content equality — a changed payload moves the slot's
+ * identity — and content equality is not a join; nothing a digest reads ever
+ * contributes a name to the spine. The per-message `closureDigest` `loam diff`
+ * compares is the same kind of read followed through `$ref`s: it hashes what
+ * the payload points at, transitively, and still never names a field.
+ */
+/*
+ * The `EventMessage`/`AsyncapiDoc` read model lives in `./model.ts` — split
+ * there when the `asyncapiFromText` extraction pushed this module past the
+ * 300-line ceiling. This module keeps the walk; that one keeps what the walk
+ * answers.
+ */
+/**
+ * A message's join token: its `name`, or the key it is declared under.
+ * Exported for the merge (./merge/merge.ts), whose removal exactness compares
+ * this same spelling — a second definition of the fallback rule is how a
+ * marker would delete a message the reader joins under a different name.
+ */
+export 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;
+}
+/**
+ * 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" };
+    return asyncapiFromText(bytes.toString("utf8"));
+}
+/**
+ * The same read over text already in hand — the parse half of `readAsyncapi`,
+ * split out so `loam diff` can read a contract fetched from a base git ref
+ * (core/diff/base-state.ts) without writing it to disk. The YAML-throw catch
+ * lives here and nowhere else; `asyncapiDocOf` below owns everything after
+ * the parse, and the byte concerns (existence, UTF-8) stay with the reader
+ * that holds the bytes.
+ */
+export function asyncapiFromText(text) {
+    let doc;
+    try {
+        doc = parse(text);
+    }
+    catch (e) {
+        return { ...empty(), unreadable: true, error: e instanceof Error ? e.message : String(e) };
+    }
+    return asyncapiDocOf(doc);
+}
+/**
+ * The same read over an already-parsed root — what the coherence gate's
+ * merge simulation grades (core/coherence/events/), where the "file" is a
+ * document the merge computed and never wrote. One spelling of the walk for
+ * both entries, so a simulated contract can never read differently from the
+ * living file the archive would produce from it.
+ */
+export function asyncapiDocOf(doc) {
+    // 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;
+    // A pre-3.0 document is not a 3.0 document with nothing in it, so it takes
+    // the unreadable path rather than the empty one (see the module header).
+    // Only a version that SAYS 1.x or 2.x is refused: a file with no `asyncapi:`
+    // key at all (a hand-trimmed feature delta that restates slots and not the
+    // header) keeps reading as 3.0, and so does any later major, which is a
+    // question for the day it exists rather than a guess made now. A bare `2`
+    // or `2.6` parses as a YAML number, hence the String() and the `$`.
+    const version = root["asyncapi"];
+    if ((typeof version === "string" || typeof version === "number") && /^[12](\.|$)/.test(String(version))) {
+        return {
+            ...empty(),
+            unreadable: true,
+            error: `AsyncAPI ${String(version)}: loam reads AsyncAPI 3.0 only; \`asyncapi convert --target-version=3.0.0\` upgrades it`,
+        };
+    }
+    const messages = [];
+    const seen = new Map();
+    const closureDigest = closureDigester(root);
+    const declare = (name, slot, node) => {
+        // A declaration carrying the removal marker asserts a slot rather than
+        // declaring a message: it is listed (with `remove`) so the gate can see
+        // it, but it joins nothing — not sent/received, not the duplicate count.
+        if (isSlotRemoval(node)) {
+            messages.push({ name, slot, remove: true });
+            return;
+        }
+        messages.push({ name, slot, closureDigest: closureDigest(node), ...(payloadUndeclared(root, node) ? { payloadEmpty: true } : {}) });
+        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}`, node);
+    }
+    // `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"])) {
+        // A channel-slot removal retires the whole channel, inline interior
+        // included: nothing under it declares or joins anything any more.
+        if (isSlotRemoval(channel)) {
+            channelMessages.set(ck, []);
+            continue;
+        }
+        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);
+            // A name whose declaration is being retired stays off the channel's
+            // list, whether the marker sits on the aliased components entry or on
+            // the inline declaration itself — the operation fallback below must
+            // not join through a message the feature is removing.
+            if (!isSlotRemoval(node))
+                names.push(name);
+            if (!isAlias)
+                declare(name, `channels.${ck}.messages.${mk}`, node);
+        }
+        channelMessages.set(ck, names);
+    }
+    const sent = new Set();
+    const received = new Set();
+    for (const [, operation] of entriesOf(root["operations"])) {
+        const op = operation;
+        // An operation-slot removal retires the operation: it contributes no
+        // send/receive whatever its `action` says.
+        if (isSlotRemoval(op))
+            continue;
+        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;
+                // A pointer into a declaration being retired joins nothing either —
+                // the marker means the message is leaving the contract.
+                if (isSlotRemoval(node))
+                    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,
+        danglingRefs: danglingRefs(root),
+        // One deep scan rather than pushes scattered through the walk above: the
+        // walk only visits the depths that JOIN, and a marker leaked anywhere
+        // else (the root, `info`) was invisible to the living sweep while the
+        // strip still owed its removal.
+        markers: removalMarkerPaths(root, ""),
+    };
+}
+function empty() {
+    return { messages: [], sent: [], received: [], duplicateNames: [], unreadable: false, danglingRefs: [], markers: [] };
+}
+/** 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);
+}
+//# sourceMappingURL=read.js.map

package/dist/core/asyncapi/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../src/core/asyncapi/read.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 { danglingRefs, deref, payloadUndeclared } from \"./depth.js\";\nimport { entriesOf, isSlotRemoval, removalMarkerPaths } from \"./digest.js\";\nimport { closureDigester } from \"../openapi/digest.js\";\nimport type { AsyncapiDoc, EventMessage } from \"./model.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\n\n/**\n * The async contract axis: AsyncAPI 3.0, read the way `core/openapi/doc.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. A 2.x (or 1.x)\n * document declares no `operations` at all, and it used to read as a contract\n * with no messages: one `asyncapi.yaml` copied in from an older service turned\n * into a `spine.message-undefined` per landscape edge, a\n * `spec-event.message-undefined` per requirement and a knock-on\n * `spine.message-unproduced` on every consumer, none of them naming the\n * version and every fix text saying \"declare the operation\" about a file that\n * does declare it, as `publish`/`subscribe`. That is exactly the false\n * diagnosis the unreadable policy below exists to prevent, so an older\n * version now reads as UNREADABLE (`asyncapiDocOf`): one `asyncapi.invalid`\n * naming the version and the upgrade command, and nothing graded against it.\n * `loam diff` skips such a document when the base ref holds the same bytes\n * (core/diff/semantic.ts's `UNTOUCHED_SKIPS`); without that, one unconverted\n * file suspended the event axis on every run and failed every PR's diff.\n *\n * WHAT THIS READER MUST NEVER DO: join on anything inside a message's `payload`.\n * The payload is JSON Schema today and may be Avro later, and that switch is\n * meant to be a line in the document (`schemaFormat`) rather than a branch in\n * loam. Every check on this axis joins on a message NAME; nothing joins on a\n * field, and nothing under `payload` may ever contribute one. The day\n * something here reads a `required` array or a `fields` list INTO A JOIN, the\n * Avro migration stops being free. The one look the reader takes inside is\n * `payloadUndeclared` (depth.ts) — a presence probe that checks whether any\n * shape was declared at all, reads key existence and never a value, and skips\n * any payload declaring a non-JSON `schemaFormat`, so the stance holds. The\n * slot digests (./digest.ts) are COMPATIBLE with it, not an exception: they\n * hash payload bytes as content equality — a changed payload moves the slot's\n * identity — and content equality is not a join; nothing a digest reads ever\n * contributes a name to the spine. The per-message `closureDigest` `loam diff`\n * compares is the same kind of read followed through `$ref`s: it hashes what\n * the payload points at, transitively, and still never names a field.\n */\n\n/*\n * The `EventMessage`/`AsyncapiDoc` read model lives in `./model.ts` — split\n * there when the `asyncapiFromText` extraction pushed this module past the\n * 300-line ceiling. This module keeps the walk; that one keeps what the walk\n * answers.\n */\n\n/**\n * A message's join token: its `name`, or the key it is declared under.\n * Exported for the merge (./merge/merge.ts), whose removal exactness compares\n * this same spelling — a second definition of the fallback rule is how a\n * marker would delete a message the reader joins under a different name.\n */\nexport function 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/**\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  return asyncapiFromText(bytes.toString(\"utf8\"));\n}\n\n/**\n * The same read over text already in hand — the parse half of `readAsyncapi`,\n * split out so `loam diff` can read a contract fetched from a base git ref\n * (core/diff/base-state.ts) without writing it to disk. The YAML-throw catch\n * lives here and nowhere else; `asyncapiDocOf` below owns everything after\n * the parse, and the byte concerns (existence, UTF-8) stay with the reader\n * that holds the bytes.\n */\nexport function asyncapiFromText(text: string): AsyncapiDoc {\n  let doc: unknown;\n  try {\n    doc = parse(text);\n  } catch (e) {\n    return { ...empty(), unreadable: true, error: e instanceof Error ? e.message : String(e) };\n  }\n  return asyncapiDocOf(doc);\n}\n\n/**\n * The same read over an already-parsed root — what the coherence gate's\n * merge simulation grades (core/coherence/events/), where the \"file\" is a\n * document the merge computed and never wrote. One spelling of the walk for\n * both entries, so a simulated contract can never read differently from the\n * living file the archive would produce from it.\n */\nexport function asyncapiDocOf(doc: unknown): AsyncapiDoc {\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  // A pre-3.0 document is not a 3.0 document with nothing in it, so it takes\n  // the unreadable path rather than the empty one (see the module header).\n  // Only a version that SAYS 1.x or 2.x is refused: a file with no `asyncapi:`\n  // key at all (a hand-trimmed feature delta that restates slots and not the\n  // header) keeps reading as 3.0, and so does any later major, which is a\n  // question for the day it exists rather than a guess made now. A bare `2`\n  // or `2.6` parses as a YAML number, hence the String() and the `$`.\n  const version = root[\"asyncapi\"];\n  if ((typeof version === \"string\" || typeof version === \"number\") && /^[12](\\.|$)/.test(String(version))) {\n    return {\n      ...empty(),\n      unreadable: true,\n      error: `AsyncAPI ${String(version)}: loam reads AsyncAPI 3.0 only; \\`asyncapi convert --target-version=3.0.0\\` upgrades it`,\n    };\n  }\n  const messages: EventMessage[] = [];\n  const seen = new Map<string, string[]>();\n  const closureDigest = closureDigester(root);\n  const declare = (name: string, slot: string, node: unknown): void => {\n    // A declaration carrying the removal marker asserts a slot rather than\n    // declaring a message: it is listed (with `remove`) so the gate can see\n    // it, but it joins nothing — not sent/received, not the duplicate count.\n    if (isSlotRemoval(node)) {\n      messages.push({ name, slot, remove: true as const });\n      return;\n    }\n    messages.push({ name, slot, closureDigest: closureDigest(node), ...(payloadUndeclared(root, node) ? { payloadEmpty: true as const } : {}) });\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}`, node);\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    // A channel-slot removal retires the whole channel, inline interior\n    // included: nothing under it declares or joins anything any more.\n    if (isSlotRemoval(channel)) {\n      channelMessages.set(ck, []);\n      continue;\n    }\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      // A name whose declaration is being retired stays off the channel's\n      // list, whether the marker sits on the aliased components entry or on\n      // the inline declaration itself — the operation fallback below must\n      // not join through a message the feature is removing.\n      if (!isSlotRemoval(node)) names.push(name);\n      if (!isAlias) declare(name, `channels.${ck}.messages.${mk}`, node);\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    // An operation-slot removal retires the operation: it contributes no\n    // send/receive whatever its `action` says.\n    if (isSlotRemoval(op)) continue;\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        // A pointer into a declaration being retired joins nothing either —\n        // the marker means the message is leaving the contract.\n        if (isSlotRemoval(node)) 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 {\n    messages,\n    sent: [...sent],\n    received: [...received],\n    duplicateNames,\n    unreadable: false,\n    danglingRefs: danglingRefs(root),\n    // One deep scan rather than pushes scattered through the walk above: the\n    // walk only visits the depths that JOIN, and a marker leaked anywhere\n    // else (the root, `info`) was invisible to the living sweep while the\n    // strip still owed its removal.\n    markers: removalMarkerPaths(root, \"\"),\n  };\n}\n\nfunction empty(): AsyncapiDoc {\n  return { messages: [], sent: [], received: [], duplicateNames: [], unreadable: false, danglingRefs: [], markers: [] };\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"]}