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

package/dist/core/openapi/contract-tree.js

@@ -0,0 +1,301 @@
+/**
+ * The one way both contract axes read and write a contract document: parse it,
+ * refuse its first parse error, resolve it, and hand it back as text.
+ *
+ * The helpers are axis-neutral and take the refusal to raise as a `fail`
+ * callback, because the event axis's six entry points spelled the same parse,
+ * first-error, resolve and serialize sequence the OpenAPI axis's did, against
+ * its own error class (../asyncapi/merge/error.ts, beside ./merge/error.ts). A
+ * leaf of its own, named for what it holds, at the lowest package both merge
+ * packages already import — not inside either axis's refusal module, where the
+ * event axis would read its contracts through a file named for an error.
+ * Import direction is asyncapi → openapi, as everywhere else on the contract
+ * axes. `writeTreeOver` is the write an EDIT takes — a merge into a living
+ * contract, a strip of a feature's markers, the pins and baseline record
+ * `loam rebase` stamps into one — so that only what changed is re-printed.
+ */
+import { isDeepStrictEqual } from "node:util";
+import { Document, Pair, Scalar, YAMLMap, isMap, isScalar, parseDocument } from "yaml";
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Parse a contract, refuse its first parse error, and resolve it. `check` runs
+ * between the two, on the AST: the event axis refuses an ambiguous slot key
+ * there, BEFORE resolution, so a document that is both ambiguous and carries
+ * an unresolvable alias is refused for the ambiguity, exactly as it was when
+ * each entry point spelled the sequence out.
+ */
+export function readTree(text, fail, check) {
+    const doc = parseDocument(text);
+    if (doc.errors.length > 0)
+        throw fail(doc.errors[0].message);
+    check?.(doc);
+    return { doc, plain: resolveTree(doc, fail) };
+}
+/**
+ * Resolve aliases once with the document's own anchor context. Calling an
+ * individual AST node's toJSON() loses that context and can silently turn an
+ * aliased operation, slot or component into the wrong value. An alias that
+ * cannot be resolved at all is a document loam cannot read, and says so.
+ */
+export function resolveTree(doc, fail) {
+    try {
+        return doc.toJS() ?? {};
+    }
+    catch (error) {
+        throw fail(errorMessage(error));
+    }
+}
+/**
+ * Hand the whole document back through the printer. Not exported: it is
+ * `writeTreeOver`'s first step and its fallback, and a writer calling it
+ * directly would re-print the author's whole contract — the cost
+ * `writeTreeOver` exists to avoid.
+ */
+function writeTree(doc, fail) {
+    try {
+        return doc.toString();
+    }
+    catch (error) {
+        throw fail(errorMessage(error));
+    }
+}
+/**
+ * Hand an EDITED document back over the text it was parsed from: every map
+ * entry the edit did not change keeps its original bytes, and only the entries
+ * it added, replaced or removed are written fresh.
+ *
+ * WHY THE WHOLE-DOCUMENT WRITE WAS NOT ENOUGH. `writeTree` re-serializes every
+ * node, and the `yaml` library's printer has opinions the author never asked
+ * for: it re-folds every plain or quoted scalar at 80 columns, re-pads every
+ * flow sequence (`[a, b]` becomes `[ a, b ]`), and turns CRLF into LF. So an
+ * archive that added one channel to a living contract rewrote a long
+ * `description` three sections away, and the merge's diff — the thing a
+ * reviewer reads to learn what the feature changed — carried lines nobody
+ * touched. `lineWidth: 0` is not the fix, and was measured not to be: it stops
+ * the folding by JOINING every scalar the author folded by hand onto one line,
+ * which on loam's own `examples/docs` rewrote 38 lines of a contract the
+ * default printer had left alone. No printer setting reproduces an author's
+ * layout; only the author's bytes do.
+ *
+ * HOW. Both trees are walked in step, block map by block map, keyed on the
+ * entry key: an entry whose resolved value is unchanged is left exactly where it
+ * is, an entry that changed is either descended into (both sides are block
+ * maps) or replaced by the printer's spelling of its new value, a new entry is
+ * printed after the entry the edit placed it behind, and a removed one is cut
+ * out with the comment lines directly above it — which is where the `yaml`
+ * library attaches such a comment, and so what the whole-document write would
+ * have removed with it.
+ *
+ * VERIFIED, OR NOT USED. The spliced text is parsed back and compared, resolved
+ * value against resolved value, with the edited tree. Anything the walk does
+ * not understand — a key that is not a scalar, a key spelled twice, an entry
+ * not on a line of its own, a reorder, an alias it cannot print alone — makes
+ * it answer nothing, and so does a splice that would read back as a different
+ * document: the fallback is `writeTree`, the old behaviour exactly, so this can
+ * only ever narrow a diff and never change what a contract says. The
+ * whole-document write also runs first, every time, so a document it cannot
+ * print fails the way it always failed.
+ */
+export function writeTreeOver(doc, source, fail) {
+    const whole = writeTree(doc, fail);
+    const spliced = splicedText(doc, source);
+    return spliced !== null && readsAs(spliced, doc) ? spliced : whole;
+}
+function splicedText(doc, source) {
+    const original = parseDocument(source);
+    if (original.errors.length > 0)
+        return null;
+    const run = { source, eol: source.includes("\r\n") ? "\r\n" : "\n", edits: [] };
+    try {
+        // Resolved through each document's own anchors, once — what "unchanged"
+        // means is decided on these, never on the nodes.
+        const before = { node: original.contents, plain: original.toJS() };
+        const after = { node: doc.contents, plain: doc.toJS() };
+        if (!spliceMap(run, before, after))
+            return null;
+    }
+    catch {
+        // A node the printer cannot print alone — an alias whose anchor sits
+        // outside the entry being written — is a document this walk does not
+        // understand, and the answer for those is the whole-document write.
+        return null;
+    }
+    // Stable by position, so two insertions at one point keep the order the
+    // walk emitted them in — which is the edited tree's order.
+    const edits = [...run.edits].sort((a, b) => a.from - b.from);
+    let out = "";
+    let cursor = 0;
+    for (const edit of edits) {
+        if (edit.from < cursor)
+            return null;
+        out += source.slice(cursor, edit.from) + edit.text;
+        cursor = edit.to;
+    }
+    return out + source.slice(cursor);
+}
+/** Does the spliced text read back as exactly the edited document? */
+function readsAs(text, doc) {
+    try {
+        const back = parseDocument(text);
+        return back.errors.length === 0 && isDeepStrictEqual(back.toJS(), doc.toJS());
+    }
+    catch {
+        return false;
+    }
+}
+function blockMap(node) {
+    return isMap(node) && node.flow !== true;
+}
+/**
+ * An entry's key as the resolved tree spells it, or null for a key this walk
+ * will not match on. A key the edit SET arrives as the raw value rather than a
+ * node — `setIn` builds the pair from what it was handed — and is the same key.
+ */
+function keyOf(pair) {
+    const value = isScalar(pair.key) ? pair.key.value : pair.key;
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value) : null;
+}
+function child(plain, key) {
+    return plain !== null && typeof plain === "object" ? plain[key] : undefined;
+}
+/**
+ * Splice one block map. Answers false — and the whole splice is abandoned — on
+ * any shape it does not understand; see `writeTreeOver`.
+ */
+function spliceMap(run, before, after) {
+    if (!blockMap(before.node) || !blockMap(after.node) || before.node.items.length === 0)
+        return false;
+    const located = locateEntries(run.source, before.node.items);
+    if (located === null)
+        return false;
+    const { entries, column: indent } = located;
+    const byKey = new Map();
+    for (const [at, entry] of entries.entries()) {
+        const key = keyOf(entry.pair);
+        if (key === null || byKey.has(key))
+            return false;
+        byKey.set(key, { at, entry });
+    }
+    const kept = new Set();
+    let insertAt = entries[0].lead;
+    let lastAt = -1;
+    for (const pair of after.node.items) {
+        const key = keyOf(pair);
+        if (key === null || kept.has(key))
+            return false;
+        kept.add(key);
+        const was = byKey.get(key);
+        if (was === undefined) {
+            run.edits.push({ from: insertAt, to: insertAt, text: printed(run, pair, indent, insertAt) });
+            continue;
+        }
+        // A reorder is a change this walk cannot express by keeping bytes where
+        // they are, and the whole-document write expresses it exactly.
+        if (was.at < lastAt)
+            return false;
+        lastAt = was.at;
+        insertAt = was.entry.end;
+        const old = { node: was.entry.pair.value, plain: child(before.plain, key) };
+        const now = { node: pair.value, plain: child(after.plain, key) };
+        if (isDeepStrictEqual(old.plain, now.plain))
+            continue;
+        const mark = run.edits.length;
+        if (blockMap(old.node) && blockMap(now.node) && spliceMap(run, old, now))
+            continue;
+        // Not descended into, or the descent failed: drop whatever it collected
+        // and write the entry whole, from its key line to its end. The comment
+        // lines above it stay — they are outside the range, and the key printed
+        // here carries none of its own.
+        run.edits.length = mark;
+        run.edits.push({ from: was.entry.line, to: was.entry.end, text: printed(run, pair, indent, was.entry.line) });
+    }
+    for (const [key, { entry }] of byKey) {
+        if (!kept.has(key))
+            run.edits.push({ from: entry.lead, to: entry.end, text: "" });
+    }
+    return true;
+}
+/** Each entry's line, comment lead and end — or null when one is not on a line of its own at one indentation. */
+function locateEntries(source, items) {
+    const entries = [];
+    let column = null;
+    let bound = 0;
+    for (const pair of items) {
+        const key = pair.key;
+        const value = pair.value;
+        if (!key?.range || !value?.range)
+            return null;
+        const start = key.range[0];
+        const line = source.lastIndexOf("\n", start - 1) + 1;
+        if (line < bound || !/^ *$/.test(source.slice(line, start)))
+            return null;
+        if (column !== null && start - line !== column)
+            return null;
+        column = start - line;
+        const lead = commentLead(source, { line, bound, attached: isScalar(key) && key.commentBefore !== undefined });
+        // An EMPTY value — `a:`, `a: !tag`, `a: &x` — ends AT its line break rather
+        // than past it, measured on both line endings; without the step a cut
+        // leaves a stray blank line, and an insert after it joins the next line.
+        let end = value.range[2];
+        if (end > 0 && source[end - 1] !== "\n") {
+            if (source.startsWith("\r\n", end))
+                end += 2;
+            else if (source[end] === "\n")
+                end += 1;
+        }
+        entries.push({ pair, line, lead, end });
+        bound = end;
+    }
+    return column === null ? null : { entries, column };
+}
+/**
+ * Where the comment block above an entry's key line starts — the lines the
+ * `yaml` library attaches to the key, which a removed entry takes with it, as
+ * the whole-document write would. Contiguous comment lines always; across blank
+ * lines too when the key carries an attached comment, because the library
+ * attaches one separated by a blank line as well. Never above `bound`, the end
+ * of the entry before, and never onto a blank line ABOVE the block: those
+ * separate this entry from the previous one and stay.
+ */
+function commentLead(source, at) {
+    let lead = at.line;
+    for (let cursor = at.line; cursor > at.bound;) {
+        const previous = source.lastIndexOf("\n", cursor - 2) + 1;
+        if (previous < at.bound)
+            break;
+        const text = source.slice(previous, cursor).trim();
+        if (text.startsWith("#"))
+            lead = previous;
+        else if (text !== "" || !at.attached)
+            break;
+        cursor = previous;
+    }
+    return lead;
+}
+/**
+ * One entry as the printer spells it, indented to its map's column, in the
+ * original's line break. The key is printed BARE — a fresh scalar with the
+ * original's quoting style and none of its comments — because the comment
+ * lines above an entry stay in place outside the range being replaced, and the
+ * printer would otherwise write them a second time.
+ */
+function printed(run, pair, indent, at) {
+    const key = new Scalar(isScalar(pair.key) ? pair.key.value : pair.key);
+    if (isScalar(pair.key) && pair.key.type !== undefined)
+        key.type = pair.key.type;
+    const map = new YAMLMap();
+    map.items.push(new Pair(key, pair.value));
+    const single = new Document();
+    single.contents = map;
+    const text = single
+        .toString()
+        .split("\n")
+        .map((line) => (line === "" ? line : " ".repeat(indent) + line))
+        .join(run.eol);
+    // Written where the original stopped without a final line break, the entry
+    // needs one in front of it, or it would join the line it follows.
+    return at === run.source.length && at > 0 && !run.source.endsWith("\n") ? run.eol + text : text;
+}
+//# sourceMappingURL=contract-tree.js.map

package/dist/core/openapi/contract-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-tree.js","sourceRoot":"","sources":["../../../src/core/openapi/contract-tree.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The one way both contract axes read and write a contract document: parse it,\n * refuse its first parse error, resolve it, and hand it back as text.\n *\n * The helpers are axis-neutral and take the refusal to raise as a `fail`\n * callback, because the event axis's six entry points spelled the same parse,\n * first-error, resolve and serialize sequence the OpenAPI axis's did, against\n * its own error class (../asyncapi/merge/error.ts, beside ./merge/error.ts). A\n * leaf of its own, named for what it holds, at the lowest package both merge\n * packages already import — not inside either axis's refusal module, where the\n * event axis would read its contracts through a file named for an error.\n * Import direction is asyncapi → openapi, as everywhere else on the contract\n * axes. `writeTreeOver` is the write an EDIT takes — a merge into a living\n * contract, a strip of a feature's markers, the pins and baseline record\n * `loam rebase` stamps into one — so that only what changed is re-printed.\n */\nimport { isDeepStrictEqual } from \"node:util\";\nimport { Document, Pair, Scalar, YAMLMap, isMap, isScalar, parseDocument, type Node } from \"yaml\";\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\n/** A contract's AST, for the writes, and its resolved plain tree, for every shape question. */\nexport interface ContractTree {\n  doc: Document.Parsed;\n  plain: unknown;\n}\n\n/**\n * Parse a contract, refuse its first parse error, and resolve it. `check` runs\n * between the two, on the AST: the event axis refuses an ambiguous slot key\n * there, BEFORE resolution, so a document that is both ambiguous and carries\n * an unresolvable alias is refused for the ambiguity, exactly as it was when\n * each entry point spelled the sequence out.\n */\nexport function readTree(text: string, fail: (detail: string) => Error, check?: (doc: Document) => void): ContractTree {\n  const doc = parseDocument(text);\n  if (doc.errors.length > 0) throw fail(doc.errors[0]!.message);\n  check?.(doc);\n  return { doc, plain: resolveTree(doc, fail) };\n}\n\n/**\n * Resolve aliases once with the document's own anchor context. Calling an\n * individual AST node's toJSON() loses that context and can silently turn an\n * aliased operation, slot or component into the wrong value. An alias that\n * cannot be resolved at all is a document loam cannot read, and says so.\n */\nexport function resolveTree(doc: Document, fail: (detail: string) => Error): unknown {\n  try {\n    return doc.toJS() ?? {};\n  } catch (error) {\n    throw fail(errorMessage(error));\n  }\n}\n\n/**\n * Hand the whole document back through the printer. Not exported: it is\n * `writeTreeOver`'s first step and its fallback, and a writer calling it\n * directly would re-print the author's whole contract — the cost\n * `writeTreeOver` exists to avoid.\n */\nfunction writeTree(doc: Document, fail: (detail: string) => Error): string {\n  try {\n    return doc.toString();\n  } catch (error) {\n    throw fail(errorMessage(error));\n  }\n}\n\n/**\n * Hand an EDITED document back over the text it was parsed from: every map\n * entry the edit did not change keeps its original bytes, and only the entries\n * it added, replaced or removed are written fresh.\n *\n * WHY THE WHOLE-DOCUMENT WRITE WAS NOT ENOUGH. `writeTree` re-serializes every\n * node, and the `yaml` library's printer has opinions the author never asked\n * for: it re-folds every plain or quoted scalar at 80 columns, re-pads every\n * flow sequence (`[a, b]` becomes `[ a, b ]`), and turns CRLF into LF. So an\n * archive that added one channel to a living contract rewrote a long\n * `description` three sections away, and the merge's diff — the thing a\n * reviewer reads to learn what the feature changed — carried lines nobody\n * touched. `lineWidth: 0` is not the fix, and was measured not to be: it stops\n * the folding by JOINING every scalar the author folded by hand onto one line,\n * which on loam's own `examples/docs` rewrote 38 lines of a contract the\n * default printer had left alone. No printer setting reproduces an author's\n * layout; only the author's bytes do.\n *\n * HOW. Both trees are walked in step, block map by block map, keyed on the\n * entry key: an entry whose resolved value is unchanged is left exactly where it\n * is, an entry that changed is either descended into (both sides are block\n * maps) or replaced by the printer's spelling of its new value, a new entry is\n * printed after the entry the edit placed it behind, and a removed one is cut\n * out with the comment lines directly above it — which is where the `yaml`\n * library attaches such a comment, and so what the whole-document write would\n * have removed with it.\n *\n * VERIFIED, OR NOT USED. The spliced text is parsed back and compared, resolved\n * value against resolved value, with the edited tree. Anything the walk does\n * not understand — a key that is not a scalar, a key spelled twice, an entry\n * not on a line of its own, a reorder, an alias it cannot print alone — makes\n * it answer nothing, and so does a splice that would read back as a different\n * document: the fallback is `writeTree`, the old behaviour exactly, so this can\n * only ever narrow a diff and never change what a contract says. The\n * whole-document write also runs first, every time, so a document it cannot\n * print fails the way it always failed.\n */\nexport function writeTreeOver(doc: Document, source: string, fail: (detail: string) => Error): string {\n  const whole = writeTree(doc, fail);\n  const spliced = splicedText(doc, source);\n  return spliced !== null && readsAs(spliced, doc) ? spliced : whole;\n}\n\n/** One replacement of `source[from, to)`. An insertion is `from === to`. */\ninterface Edit {\n  from: number;\n  to: number;\n  text: string;\n}\n\n/** What one walk shares: the original text, its line break, and the edits collected so far. */\ninterface SpliceRun {\n  source: string;\n  eol: string;\n  edits: Edit[];\n}\n\n/** One original entry, located: where its key line starts, where its comments start, where it ends. */\ninterface Located {\n  pair: Pair;\n  /** Start of the line the key is on. */\n  line: number;\n  /** Start of the contiguous comment lines directly above that line, or `line` when there are none. */\n  lead: number;\n  /** End of the entry, past its line break. */\n  end: number;\n}\n\n\n/** One side of the walk: a node, and the value it resolves to through its own document. */\ninterface Side {\n  node: unknown;\n  plain: unknown;\n}\n\nfunction splicedText(doc: Document, source: string): string | null {\n  const original = parseDocument(source);\n  if (original.errors.length > 0) return null;\n  const run: SpliceRun = { source, eol: source.includes(\"\\r\\n\") ? \"\\r\\n\" : \"\\n\", edits: [] };\n  try {\n    // Resolved through each document's own anchors, once — what \"unchanged\"\n    // means is decided on these, never on the nodes.\n    const before: Side = { node: original.contents, plain: original.toJS() };\n    const after: Side = { node: doc.contents, plain: doc.toJS() };\n    if (!spliceMap(run, before, after)) return null;\n  } catch {\n    // A node the printer cannot print alone — an alias whose anchor sits\n    // outside the entry being written — is a document this walk does not\n    // understand, and the answer for those is the whole-document write.\n    return null;\n  }\n  // Stable by position, so two insertions at one point keep the order the\n  // walk emitted them in — which is the edited tree's order.\n  const edits = [...run.edits].sort((a, b) => a.from - b.from);\n  let out = \"\";\n  let cursor = 0;\n  for (const edit of edits) {\n    if (edit.from < cursor) return null;\n    out += source.slice(cursor, edit.from) + edit.text;\n    cursor = edit.to;\n  }\n  return out + source.slice(cursor);\n}\n\n/** Does the spliced text read back as exactly the edited document? */\nfunction readsAs(text: string, doc: Document): boolean {\n  try {\n    const back = parseDocument(text);\n    return back.errors.length === 0 && isDeepStrictEqual(back.toJS(), doc.toJS());\n  } catch {\n    return false;\n  }\n}\n\nfunction blockMap(node: unknown): node is YAMLMap {\n  return isMap(node) && node.flow !== true;\n}\n\n/**\n * An entry's key as the resolved tree spells it, or null for a key this walk\n * will not match on. A key the edit SET arrives as the raw value rather than a\n * node — `setIn` builds the pair from what it was handed — and is the same key.\n */\nfunction keyOf(pair: Pair): string | null {\n  const value: unknown = isScalar(pair.key) ? pair.key.value : pair.key;\n  return typeof value === \"string\" || typeof value === \"number\" || typeof value === \"boolean\" ? String(value) : null;\n}\n\nfunction child(plain: unknown, key: string): unknown {\n  return plain !== null && typeof plain === \"object\" ? (plain as Record<string, unknown>)[key] : undefined;\n}\n\n/**\n * Splice one block map. Answers false — and the whole splice is abandoned — on\n * any shape it does not understand; see `writeTreeOver`.\n */\nfunction spliceMap(run: SpliceRun, before: Side, after: Side): boolean {\n  if (!blockMap(before.node) || !blockMap(after.node) || before.node.items.length === 0) return false;\n  const located = locateEntries(run.source, before.node.items);\n  if (located === null) return false;\n  const { entries, column: indent } = located;\n  const byKey = new Map<string, { at: number; entry: Located }>();\n  for (const [at, entry] of entries.entries()) {\n    const key = keyOf(entry.pair);\n    if (key === null || byKey.has(key)) return false;\n    byKey.set(key, { at, entry });\n  }\n  const kept = new Set<string>();\n  let insertAt = entries[0]!.lead;\n  let lastAt = -1;\n  for (const pair of after.node.items) {\n    const key = keyOf(pair);\n    if (key === null || kept.has(key)) return false;\n    kept.add(key);\n    const was = byKey.get(key);\n    if (was === undefined) {\n      run.edits.push({ from: insertAt, to: insertAt, text: printed(run, pair, indent, insertAt) });\n      continue;\n    }\n    // A reorder is a change this walk cannot express by keeping bytes where\n    // they are, and the whole-document write expresses it exactly.\n    if (was.at < lastAt) return false;\n    lastAt = was.at;\n    insertAt = was.entry.end;\n    const old: Side = { node: was.entry.pair.value, plain: child(before.plain, key) };\n    const now: Side = { node: pair.value, plain: child(after.plain, key) };\n    if (isDeepStrictEqual(old.plain, now.plain)) continue;\n    const mark = run.edits.length;\n    if (blockMap(old.node) && blockMap(now.node) && spliceMap(run, old, now)) continue;\n    // Not descended into, or the descent failed: drop whatever it collected\n    // and write the entry whole, from its key line to its end. The comment\n    // lines above it stay — they are outside the range, and the key printed\n    // here carries none of its own.\n    run.edits.length = mark;\n    run.edits.push({ from: was.entry.line, to: was.entry.end, text: printed(run, pair, indent, was.entry.line) });\n  }\n  for (const [key, { entry }] of byKey) {\n    if (!kept.has(key)) run.edits.push({ from: entry.lead, to: entry.end, text: \"\" });\n  }\n  return true;\n}\n\n/** A block map's entries, located, and the one column every key in it starts at. */\ninterface LocatedMap {\n  entries: Located[];\n  column: number;\n}\n\n/** Each entry's line, comment lead and end — or null when one is not on a line of its own at one indentation. */\nfunction locateEntries(source: string, items: readonly Pair[]): LocatedMap | null {\n  const entries: Located[] = [];\n  let column: number | null = null;\n  let bound = 0;\n  for (const pair of items) {\n    const key = pair.key as Node | null;\n    const value = pair.value as Node | null;\n    if (!key?.range || !value?.range) return null;\n    const start = key.range[0];\n    const line = source.lastIndexOf(\"\\n\", start - 1) + 1;\n    if (line < bound || !/^ *$/.test(source.slice(line, start))) return null;\n    if (column !== null && start - line !== column) return null;\n    column = start - line;\n    const lead = commentLead(source, { line, bound, attached: isScalar(key) && key.commentBefore !== undefined });\n    // An EMPTY value — `a:`, `a: !tag`, `a: &x` — ends AT its line break rather\n    // than past it, measured on both line endings; without the step a cut\n    // leaves a stray blank line, and an insert after it joins the next line.\n    let end = value.range[2];\n    if (end > 0 && source[end - 1] !== \"\\n\") {\n      if (source.startsWith(\"\\r\\n\", end)) end += 2;\n      else if (source[end] === \"\\n\") end += 1;\n    }\n    entries.push({ pair, line, lead, end });\n    bound = end;\n  }\n  return column === null ? null : { entries, column };\n}\n\n/**\n * Where the comment block above an entry's key line starts — the lines the\n * `yaml` library attaches to the key, which a removed entry takes with it, as\n * the whole-document write would. Contiguous comment lines always; across blank\n * lines too when the key carries an attached comment, because the library\n * attaches one separated by a blank line as well. Never above `bound`, the end\n * of the entry before, and never onto a blank line ABOVE the block: those\n * separate this entry from the previous one and stay.\n */\nfunction commentLead(source: string, at: { line: number; bound: number; attached: boolean }): number {\n  let lead = at.line;\n  for (let cursor = at.line; cursor > at.bound; ) {\n    const previous = source.lastIndexOf(\"\\n\", cursor - 2) + 1;\n    if (previous < at.bound) break;\n    const text = source.slice(previous, cursor).trim();\n    if (text.startsWith(\"#\")) lead = previous;\n    else if (text !== \"\" || !at.attached) break;\n    cursor = previous;\n  }\n  return lead;\n}\n\n/**\n * One entry as the printer spells it, indented to its map's column, in the\n * original's line break. The key is printed BARE — a fresh scalar with the\n * original's quoting style and none of its comments — because the comment\n * lines above an entry stay in place outside the range being replaced, and the\n * printer would otherwise write them a second time.\n */\nfunction printed(run: SpliceRun, pair: Pair, indent: number, at: number): string {\n  const key = new Scalar(isScalar(pair.key) ? pair.key.value : pair.key);\n  if (isScalar(pair.key) && pair.key.type !== undefined) key.type = pair.key.type;\n  const map = new YAMLMap();\n  map.items.push(new Pair(key, pair.value));\n  const single = new Document();\n  single.contents = map;\n  const text = single\n    .toString()\n    .split(\"\\n\")\n    .map((line) => (line === \"\" ? line : \" \".repeat(indent) + line))\n    .join(run.eol);\n  // Written where the original stopped without a final line break, the entry\n  // needs one in front of it, or it would join the line it follows.\n  return at === run.source.length && at > 0 && !run.source.endsWith(\"\\n\") ? run.eol + text : text;\n}\n"]}

package/dist/core/openapi/depth.js

@@ -10,10 +10,14 @@
  * says, only whether one was declared at all, so the reader's structure-only
  * stance holds.
  *
- * A local pointer walk rather than an import from `merge/components.ts`: the merge
- * package already imports this package (`HTTP_METHODS` from doc.ts), so the
- * reverse import would be a package cycle — the same reason read-side
- * `resolvePointer` copies exist on the asyncapi axis.
+ * This module used to keep a private pointer walk rather than import the
+ * merge's: the merge package already imports this package (`HTTP_METHODS` from
+ * doc.ts), so the reverse import would have been a package cycle — the same
+ * reason read-side `resolvePointer` copies exist on the asyncapi axis. The two
+ * plain `$ref` questions now live HERE, at the axis root (`collectRefs` and
+ * `resolvePointer`, at the bottom), so the private copy went: the dangling-ref
+ * probe below, the merge's component closure and the reader's closure digest
+ * (`closureDigester`, ./digest.ts) all ask the same two questions.
  */
 /** Status codes whose response legitimately carries no body. */
 const NO_CONTENT = new Set(["204", "304"]);
@@ -78,45 +82,55 @@ export function failureCodesOf(op) {
  * scope and never graded, matching the merge's documented stance.
  */
 export function danglingRefs(root) {
-    const out = new Set();
-    const walk = (node) => {
-        if (Array.isArray(node)) {
-            for (const value of node)
+    // A Set keeps first-insertion order, so dedup and document order both hold.
+    return [...new Set(collectRefs(root).filter((ref) => ref.startsWith("#/") && !resolvePointer(root, ref).found))];
+}
+/*
+ * `$ref` as a pair of plain questions — which ones does this tree contain, and
+ * what does one point at. Both lived in `./merge/components.ts`, beside the
+ * component closure that was their only caller, until the reader needed the same
+ * walk; the header says why the root and not there.
+ */
+/** Every `$ref` string in a tree, in document order — duplicates kept, external refs included. */
+export function collectRefs(node) {
+    const out = [];
+    const walk = (current) => {
+        if (Array.isArray(current)) {
+            for (const value of current)
                 walk(value);
             return;
         }
-        if (node === null || typeof node !== "object")
-            return;
-        for (const [key, value] of Object.entries(node)) {
-            if (key === "$ref" && typeof value === "string") {
-                if (value.startsWith("#/") && !resolves(root, value))
-                    out.add(value);
-                continue;
+        if (current !== null && typeof current === "object") {
+            for (const [key, value] of Object.entries(current)) {
+                if (key === "$ref" && typeof value === "string")
+                    out.push(value);
+                else
+                    walk(value);
             }
-            walk(value);
         }
     };
-    walk(root);
-    return [...out];
+    walk(node);
+    return out;
 }
-/** Does a local JSON pointer (`#/a/b~1c`) reach a node in this tree? */
-function resolves(root, ref) {
+/** Resolve a local JSON pointer (`#/a/b~1c`) against a plain JS tree. */
+export function resolvePointer(root, ref) {
     let current = root;
     for (const raw of ref.slice(2).split("/")) {
         const segment = raw.replace(/~1/g, "/").replace(/~0/g, "~");
         if (Array.isArray(current)) {
             const index = Number(segment);
-            if (!Number.isInteger(index) || index < 0 || index >= current.length)
-                return false;
+            if (!Number.isInteger(index) || index < 0 || index >= current.length) {
+                return { found: false, value: undefined };
+            }
             current = current[index];
         }
         else if (current !== null && typeof current === "object" && segment in current) {
             current = current[segment];
         }
         else {
-            return false;
+            return { found: false, value: undefined };
         }
     }
-    return true;
+    return { found: true, value: current };
 }
 //# sourceMappingURL=depth.js.map

package/dist/core/openapi/depth.js.map

@@ -1 +1 @@
-{"version":3,"file":"depth.js","sourceRoot":"","sources":["../../../src/core/openapi/depth.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The contract-depth probes: does an operation say anything about what it\n * returns, and does every internal `$ref` point at something.\n *\n * Form validated and depth did not, and that was invisible from the output:\n * an operation whose one response is `description: OK`, and a `$ref` to a\n * schema nobody ever wrote, both validate exactly as cleanly as a complete\n * contract even though a reader still needs the code. Everything here is a\n * PRESENCE probe over the document's own keys: nothing reads what a schema\n * says, only whether one was declared at all, so the reader's structure-only\n * stance holds.\n *\n * A local pointer walk rather than an import from `merge/components.ts`: the merge\n * package already imports this package (`HTTP_METHODS` from doc.ts), so the\n * reverse import would be a package cycle — the same reason read-side\n * `resolvePointer` copies exist on the asyncapi axis.\n */\n\n/** Status codes whose response legitimately carries no body. */\nconst NO_CONTENT = new Set([\"204\", \"304\"]);\n\n/**\n * True when no response declares content with a schema while at least one\n * response should carry a body — an operation with no `responses` at all\n * counts, one whose only responses are 204/304 does not. A response that is\n * itself a `$ref` counts as described: somebody wrote the shape down, and the\n * dangling case is the ref probe's finding, not this one's.\n */\nexport function responseUndescribed(op: unknown): boolean {\n  if (op === null || typeof op !== \"object\") return true;\n  const responses = (op as Record<string, unknown>)[\"responses\"];\n  if (responses === null || responses === undefined || typeof responses !== \"object\" || Array.isArray(responses)) {\n    return true;\n  }\n  const entries = Object.entries(responses as Record<string, unknown>);\n  if (entries.length === 0) return true;\n  let owesBody = false;\n  for (const [code, resp] of entries) {\n    if (NO_CONTENT.has(code)) continue;\n    owesBody = true;\n    if (resp === null || typeof resp !== \"object\" || Array.isArray(resp)) continue;\n    const rec = resp as Record<string, unknown>;\n    if (\"$ref\" in rec) return false;\n    const content = rec[\"content\"];\n    if (content === null || typeof content !== \"object\" || Array.isArray(content)) continue;\n    for (const media of Object.values(content as Record<string, unknown>)) {\n      if (media !== null && typeof media === \"object\" && \"schema\" in (media as Record<string, unknown>)) {\n        return false;\n      }\n    }\n  }\n  return owesBody;\n}\n\n/**\n * The non-2xx response codes an operation declares, in document order.\n *\n * Exact three-digit codes only. `default` names no case — it is whatever else\n * happens — and the `4XX`/`5XX` wildcards name a class rather than a refusal,\n * so no scenario could be written for either and demanding one would teach an\n * author to write a scenario about nothing. 1xx and 3xx are excluded with 2xx:\n * a redirect or a continue is not the service saying no.\n */\nexport function failureCodesOf(op: unknown): string[] {\n  if (op === null || typeof op !== \"object\") return [];\n  const responses = (op as Record<string, unknown>)[\"responses\"];\n  if (responses === null || typeof responses !== \"object\" || Array.isArray(responses)) return [];\n  return Object.keys(responses as Record<string, unknown>).filter((code) => /^[45]\\d\\d$/.test(code));\n}\n\n/**\n * Every internal `#/` reference in the document that resolves to nothing —\n * deduped, document order. External references (URLs, file paths) are out of\n * scope and never graded, matching the merge's documented stance.\n */\nexport function danglingRefs(root: unknown): string[] {\n  const out = new Set<string>();\n  const walk = (node: unknown): void => {\n    if (Array.isArray(node)) {\n      for (const value of node) walk(value);\n      return;\n    }\n    if (node === null || typeof node !== \"object\") return;\n    for (const [key, value] of Object.entries(node as Record<string, unknown>)) {\n      if (key === \"$ref\" && typeof value === \"string\") {\n        if (value.startsWith(\"#/\") && !resolves(root, value)) out.add(value);\n        continue;\n      }\n      walk(value);\n    }\n  };\n  walk(root);\n  return [...out];\n}\n\n/** Does a local JSON pointer (`#/a/b~1c`) reach a node in this tree? */\nfunction resolves(root: unknown, ref: string): boolean {\n  let current: unknown = root;\n  for (const raw of ref.slice(2).split(\"/\")) {\n    const segment = raw.replace(/~1/g, \"/\").replace(/~0/g, \"~\");\n    if (Array.isArray(current)) {\n      const index = Number(segment);\n      if (!Number.isInteger(index) || index < 0 || index >= current.length) return false;\n      current = current[index];\n    } else if (current !== null && typeof current === \"object\" && segment in (current as Record<string, unknown>)) {\n      current = (current as Record<string, unknown>)[segment];\n    } else {\n      return false;\n    }\n  }\n  return true;\n}\n"]}
+{"version":3,"file":"depth.js","sourceRoot":"","sources":["../../../src/core/openapi/depth.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The contract-depth probes: does an operation say anything about what it\n * returns, and does every internal `$ref` point at something.\n *\n * Form validated and depth did not, and that was invisible from the output:\n * an operation whose one response is `description: OK`, and a `$ref` to a\n * schema nobody ever wrote, both validate exactly as cleanly as a complete\n * contract even though a reader still needs the code. Everything here is a\n * PRESENCE probe over the document's own keys: nothing reads what a schema\n * says, only whether one was declared at all, so the reader's structure-only\n * stance holds.\n *\n * This module used to keep a private pointer walk rather than import the\n * merge's: the merge package already imports this package (`HTTP_METHODS` from\n * doc.ts), so the reverse import would have been a package cycle — the same\n * reason read-side `resolvePointer` copies exist on the asyncapi axis. The two\n * plain `$ref` questions now live HERE, at the axis root (`collectRefs` and\n * `resolvePointer`, at the bottom), so the private copy went: the dangling-ref\n * probe below, the merge's component closure and the reader's closure digest\n * (`closureDigester`, ./digest.ts) all ask the same two questions.\n */\n\n/** Status codes whose response legitimately carries no body. */\nconst NO_CONTENT = new Set([\"204\", \"304\"]);\n\n/**\n * True when no response declares content with a schema while at least one\n * response should carry a body — an operation with no `responses` at all\n * counts, one whose only responses are 204/304 does not. A response that is\n * itself a `$ref` counts as described: somebody wrote the shape down, and the\n * dangling case is the ref probe's finding, not this one's.\n */\nexport function responseUndescribed(op: unknown): boolean {\n  if (op === null || typeof op !== \"object\") return true;\n  const responses = (op as Record<string, unknown>)[\"responses\"];\n  if (responses === null || responses === undefined || typeof responses !== \"object\" || Array.isArray(responses)) {\n    return true;\n  }\n  const entries = Object.entries(responses as Record<string, unknown>);\n  if (entries.length === 0) return true;\n  let owesBody = false;\n  for (const [code, resp] of entries) {\n    if (NO_CONTENT.has(code)) continue;\n    owesBody = true;\n    if (resp === null || typeof resp !== \"object\" || Array.isArray(resp)) continue;\n    const rec = resp as Record<string, unknown>;\n    if (\"$ref\" in rec) return false;\n    const content = rec[\"content\"];\n    if (content === null || typeof content !== \"object\" || Array.isArray(content)) continue;\n    for (const media of Object.values(content as Record<string, unknown>)) {\n      if (media !== null && typeof media === \"object\" && \"schema\" in (media as Record<string, unknown>)) {\n        return false;\n      }\n    }\n  }\n  return owesBody;\n}\n\n/**\n * The non-2xx response codes an operation declares, in document order.\n *\n * Exact three-digit codes only. `default` names no case — it is whatever else\n * happens — and the `4XX`/`5XX` wildcards name a class rather than a refusal,\n * so no scenario could be written for either and demanding one would teach an\n * author to write a scenario about nothing. 1xx and 3xx are excluded with 2xx:\n * a redirect or a continue is not the service saying no.\n */\nexport function failureCodesOf(op: unknown): string[] {\n  if (op === null || typeof op !== \"object\") return [];\n  const responses = (op as Record<string, unknown>)[\"responses\"];\n  if (responses === null || typeof responses !== \"object\" || Array.isArray(responses)) return [];\n  return Object.keys(responses as Record<string, unknown>).filter((code) => /^[45]\\d\\d$/.test(code));\n}\n\n/**\n * Every internal `#/` reference in the document that resolves to nothing —\n * deduped, document order. External references (URLs, file paths) are out of\n * scope and never graded, matching the merge's documented stance.\n */\nexport function danglingRefs(root: unknown): string[] {\n  // A Set keeps first-insertion order, so dedup and document order both hold.\n  return [...new Set(collectRefs(root).filter((ref) => ref.startsWith(\"#/\") && !resolvePointer(root, ref).found))];\n}\n\n/*\n * `$ref` as a pair of plain questions — which ones does this tree contain, and\n * what does one point at. Both lived in `./merge/components.ts`, beside the\n * component closure that was their only caller, until the reader needed the same\n * walk; the header says why the root and not there.\n */\n\n/** Every `$ref` string in a tree, in document order — duplicates kept, external refs included. */\nexport function collectRefs(node: unknown): string[] {\n  const out: string[] = [];\n  const walk = (current: unknown): void => {\n    if (Array.isArray(current)) {\n      for (const value of current) walk(value);\n      return;\n    }\n    if (current !== null && typeof current === \"object\") {\n      for (const [key, value] of Object.entries(current)) {\n        if (key === \"$ref\" && typeof value === \"string\") out.push(value);\n        else walk(value);\n      }\n    }\n  };\n  walk(node);\n  return out;\n}\n\n/** Resolve a local JSON pointer (`#/a/b~1c`) against a plain JS tree. */\nexport function resolvePointer(root: unknown, ref: string): { found: boolean; value: unknown } {\n  let current: unknown = root;\n  for (const raw of ref.slice(2).split(\"/\")) {\n    const segment = raw.replace(/~1/g, \"/\").replace(/~0/g, \"~\");\n    if (Array.isArray(current)) {\n      const index = Number(segment);\n      if (!Number.isInteger(index) || index < 0 || index >= current.length) {\n        return { found: false, value: undefined };\n      }\n      current = current[index];\n    } else if (current !== null && typeof current === \"object\" && segment in (current as Record<string, unknown>)) {\n      current = (current as Record<string, unknown>)[segment];\n    } else {\n      return { found: false, value: undefined };\n    }\n  }\n  return { found: true, value: current };\n}\n"]}

package/dist/core/openapi/digest.js

@@ -10,14 +10,17 @@
  * is that it fires only for real ones.
  */
 import { createHash } from "node:crypto";
+import { collectRefs, resolvePointer } from "./depth.js";
 /**
  * The baseline marker: which living version of this operation a FEATURE delta
  * was written against. Same idea as a requirement's `Based-On:` (core/document/spec.ts),
  * in the vendor-extension shape this axis already uses for `x-loam-remove`.
  *
  * This axis needs it MORE than the requirement axis does, because a feature's
- * openapi.yaml is a COMPLETE document rather than a patch: authors restate the
- * living contract around the slot they are changing, and the merge upserts every
+ * openapi.yaml may spell operations it does not change: it needs only what it
+ * adds, changes or removes (the merge leaves everything else to the living
+ * contract), but restating more is legal — for context, or a contract pasted
+ * whole, which is what loam's own docs once taught — and the merge upserts every
  * operation the document spells. So a feature that never meant to touch
  * `refundOrder` — it merely quoted it — pushes its authoring-time copy back over
  * whatever landed in between, reverting another team's shipped change without
@@ -154,6 +157,53 @@ export function valueDigest(node) {
 export function operationDigest(node) {
     return valueDigest(withoutOperationBaseline(node));
 }
+/**
+ * The identity of what a node PROMISES rather than of its own bytes: the
+ * `operationDigest` input plus every internal `$ref` it reaches, transitively,
+ * each paired with the digest of what it resolves to in `root`. One digester per
+ * document; call it once per operation or message.
+ *
+ * `operationDigest` stops at the node on purpose — a pin says which version of
+ * THIS slot a delta was written against, and components carry their own pins.
+ * But a reviewer asking "did this operation change?" means the contract a
+ * consumer codes against, and in a factored document that is mostly somewhere
+ * else: renaming a required field of `#/components/schemas/Payment` leaves every
+ * operation returning it byte-identical, and `loam diff` reported exactly that
+ * PR as "no fleet-meaningful changes". This digest is what diff compares.
+ *
+ * The memo is per document and per ref, so a schema twenty operations reference
+ * is resolved, walked and hashed once. A ref that resolves to nothing still
+ * contributes — as a marker no 16-hex digest can equal — so a dangling ref that
+ * starts resolving reads as a change. External refs (anything not `#/`) are not
+ * followed, matching every other reader here; the ref string itself is part of
+ * the node's own bytes, so re-pointing one still moves the digest.
+ */
+export function closureDigester(root) {
+    const targets = new Map();
+    const target = (ref) => {
+        let hit = targets.get(ref);
+        if (hit === undefined) {
+            const resolved = resolvePointer(root, ref);
+            hit = resolved.found ? { digest: valueDigest(resolved.value), refs: collectRefs(resolved.value) } : { digest: "unresolved", refs: [] };
+            targets.set(ref, hit);
+        }
+        return hit;
+    };
+    return (node) => {
+        const reached = new Map();
+        const queue = collectRefs(node);
+        while (queue.length > 0) {
+            const ref = queue.pop();
+            if (!ref.startsWith("#/") || reached.has(ref))
+                continue;
+            const hit = target(ref);
+            reached.set(ref, hit.digest);
+            queue.push(...hit.refs);
+        }
+        // canonicalJson sorts keys, so the walk order above never reaches the digest.
+        return valueDigest({ node: withoutOperationBaseline(node), refs: Object.fromEntries(reached) });
+    };
+}
 /**
  * What a pin says, from digests alone — the one definition every decider
  * shares: the gate (./baseline/gate.ts) and the merge