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

package/dist/core/openapi/merge/merge.js

@@ -0,0 +1,232 @@
+/**
+ * The archive-time merge: a feature's contract folded into the living one, and
+ * every condition the caller has to surface afterwards.
+ *
+ * The result type carries far more than the merged text on purpose. A merge
+ * that quietly overwrote an operation, dropped a component, or ran against a
+ * stale baseline is not an error — it is a fact the archiving human has to be
+ * told, and a return value nobody can forget to read is the only place that
+ * survives a refactor.
+ */
+import { isDeepStrictEqual } from "node:util";
+import { isMap } from "yaml";
+// Every `isRecord` below asks one question of a resolved plain tree: is this a
+// node that can hold OpenAPI keys — an object, not an array?
+import { isRecord } from "../../kernel/records.js";
+import { HTTP_METHODS } from "../doc.js";
+import { OpenapiMergeError, openapiRefusal } from "./error.js";
+import { readTree, writeTreeOver } from "../contract-tree.js";
+import { classifyOperationBaseline } from "./pin.js";
+import { classifyBaselineDigests, isRemoval, valueDigest } from "../digest.js";
+import { entryFor, readBaselineRecord, restatedSurfaces } from "../baseline/record.js";
+import { dropPathIfNoOperations, opLabel, operationIdOf, plainChild, withoutFeatureMarkers } from "./markers.js";
+import { mergeComponentClosure } from "./components.js";
+/**
+ * Merge the feature's `paths` into the living OpenAPI structurally (YAML AST, not
+ * text splicing). A feature document restating NOTHING — no path entry and no
+ * component — is a successful no-op; one whose whole delta is a component is
+ * merged like any other, through the closure at the end of this function.
+ * The merged operations' local component-ref closure rides along recursively;
+ * external refs are left untouched and never gated.
+ *
+ * Every SHAPE question — is there a `paths` mapping, is this path item a
+ * mapping, which methods does it hold — is answered from the RESOLVED plain
+ * trees, never from the AST node. Asking the AST (`isMap(node)`) answers a
+ * different question: an alias node is not a map even when it resolves to one.
+ * `paths: *alias` therefore read as "no paths to merge" and the whole contract
+ * delta was dropped with a successful exit, and an aliased path ITEM fell into
+ * the wholesale-replace branch and deleted every living operation on that path
+ * that the alias did not restate. Aliases are legal OpenAPI and the natural way
+ * to write a delta that repeats a shape; nothing here may treat them as absent.
+ * An alias that cannot be resolved at all is a document loam cannot read, and
+ * says so — it is never "nothing to merge".
+ */
+export function mergeOpenapiPaths(livingText, featureText, service) {
+    // Aliases resolved once, with the document's own anchor context (readTree).
+    const { plain: featPlain } = readTree(featureText, openapiRefusal("feature", service));
+    const featPathsPlain = plainChild(featPlain, "paths");
+    // The SHAPE refusal is unchanged and stays first: a `paths` that is a
+    // sequence or a scalar is a document loam cannot merge. Absent and null
+    // (`paths:` with nothing under it) are not shape faults — they are documents
+    // holding no path entries, which is a different sentence and now has a
+    // different answer.
+    if (featPathsPlain !== undefined && featPathsPlain !== null && !isRecord(featPathsPlain)) {
+        throw new OpenapiMergeError("feature", service, "`paths` is not a mapping");
+    }
+    const featPathEntries = isRecord(featPathsPlain) ? Object.entries(featPathsPlain) : [];
+    // "Is there anything to merge?" is a question about the whole delta, and for
+    // years it was asked of `paths` alone — an absence test standing in for the
+    // decision. It returned here, before the living document was even parsed, so
+    // the component closure (the last statement of this function, and the only
+    // thing that writes a component) never ran: a feature whose entire change was
+    // a shared schema passed the gate and archived at exit 0 having merged
+    // NOTHING. The components answer it too now, over the ONE surface
+    // enumeration the gate and the rebase plan already grade the delta with.
+    const componentsAreTheDelta = featPathEntries.length === 0;
+    if (componentsAreTheDelta && !restatedSurfaces(featPlain).some((s) => s.kind === "component")) {
+        return noop();
+    }
+    const { doc: living, plain: livingPlain } = readTree(livingText, openapiRefusal("living", service));
+    const livingPathsPlain = plainChild(livingPlain, "paths");
+    if (livingPathsPlain !== undefined && livingPathsPlain !== null && !isRecord(livingPathsPlain)) {
+        throw new OpenapiMergeError("living", service, "`paths` is not a mapping");
+    }
+    const modified = [];
+    const modifiedOperationIds = new Map();
+    const pathItemModified = [];
+    const removed = [];
+    const quoted = [];
+    const baselineStale = [];
+    const pathItemQuoted = [];
+    const pathItemStale = [];
+    // The surface record, read ONCE for the path-item loop and the component
+    // closure. Malformed entries read back as absent — the gate refuses them,
+    // and a value nobody can evaluate must never be why a merge skips a write.
+    const { record } = readBaselineRecord(featPlain);
+    // The plain values this merge actually WRITES, labelled for the ref sweep:
+    // the closure copies new components reachable from these, and only these —
+    // a quoted operation's refs are living's own business.
+    const written = [];
+    for (const [path, featItemPlain] of featPathEntries) {
+        const existing = living.getIn(["paths", path]);
+        const existingPlain = plainChild(livingPathsPlain, path);
+        if (existing !== undefined && !isRecord(existingPlain)) {
+            // The living contract holds this path as something other than a path
+            // item. Replacing it wholesale is the one branch that may delete living
+            // operations without naming them, so it is reserved for paths the living
+            // contract does not have at all.
+            throw new OpenapiMergeError("living", service, `path '${path}' is not a mapping`);
+        }
+        if (existing !== undefined) {
+            if (!isRecord(featItemPlain)) {
+                throw new OpenapiMergeError("feature", service, `path '${path}' is not a mapping`);
+            }
+            // EVERY branch publishes through withoutFeatureMarkers. This one used to
+            // copy every key of the feature path item and guard only the HTTP
+            // methods, so a path-level `x-loam-remove` landed in the living contract
+            // with `modified: []` and no warning. A key the strip drops is never
+            // written; the removal handling below still reads the RAW item, because
+            // that is where the markers it acts on live.
+            const publish = withoutFeatureMarkers(featItemPlain);
+            const publishable = isRecord(publish) ? publish : {};
+            for (const [m, afterPlain] of Object.entries(featItemPlain)) {
+                const before = living.getIn(["paths", path, m]);
+                const beforePlain = plainChild(existingPlain, m);
+                if (HTTP_METHODS.has(m) && isRemoval(afterPlain)) {
+                    // Coherence validates the marker and gates absent/mismatched targets.
+                    // The merge remains defensive under --approve: never delete a
+                    // different operation merely because it occupies the requested slot.
+                    if (before !== undefined &&
+                        operationIdOf(beforePlain) !== undefined &&
+                        operationIdOf(beforePlain) === operationIdOf(afterPlain)) {
+                        removed.push(opLabel(beforePlain, afterPlain, m, path));
+                        living.deleteIn(["paths", path, m]);
+                    }
+                    continue;
+                }
+                if (HTTP_METHODS.has(m)) {
+                    const verdict = classifyOperationBaseline(afterPlain, before === undefined ? undefined : beforePlain);
+                    // A QUOTE is not a merge input. The author wrote this operation down
+                    // as a restatement, not because they changed it, so
+                    // the living contract keeps whatever it holds — including a change
+                    // that landed after this delta was written. This is mechanical, not a
+                    // judgement, so `--approve` does not turn it back on: overriding a
+                    // gate is a decision, reverting an operation nobody edited is a bug.
+                    if (verdict === "quote") {
+                        quoted.push(opLabel(beforePlain, afterPlain, m, path));
+                        continue;
+                    }
+                    if (verdict === "stale")
+                        baselineStale.push(opLabel(beforePlain, afterPlain, m, path));
+                }
+                if (!(m in publishable)) {
+                    // A feature-only marker at path level. It is never published, and
+                    // never reported as a path-item overwrite either — it is not a key of
+                    // the contract at all. The archive gate names it to the author.
+                    continue;
+                }
+                if (!HTTP_METHODS.has(m)) {
+                    // The operations' verdict, for the keys beside them, from the root
+                    // record instead of an in-value pin. A QUOTE is skipped for the
+                    // operations' reason — the author restated it, they did not edit it
+                    // — and skipping matters MORE here: a path-level key applies to
+                    // every operation on the path, including ones this feature never
+                    // mentions. Stale still writes: reaching the merge means --approve.
+                    const verdict = classifyBaselineDigests(entryFor(record, { kind: "path-item", path, key: m, value: afterPlain }), valueDigest(afterPlain), before === undefined ? undefined : valueDigest(beforePlain));
+                    if (verdict === "quote") {
+                        pathItemQuoted.push(`'${m}' (${path})`);
+                        continue;
+                    }
+                    if (verdict === "stale")
+                        pathItemStale.push(`'${m}' (${path})`);
+                }
+                // The difference check covers EVERY key of the path item; only the
+                // LABEL depends on whether the key is an HTTP method.
+                if (before !== undefined && !isDeepStrictEqual(beforePlain, afterPlain)) {
+                    if (HTTP_METHODS.has(m)) {
+                        const label = opLabel(beforePlain, afterPlain, m, path);
+                        modified.push(label);
+                        const id = operationIdOf(beforePlain) ?? operationIdOf(afterPlain);
+                        if (id !== undefined)
+                            modifiedOperationIds.set(label, id);
+                    }
+                    else {
+                        pathItemModified.push(`'${m}' (${path})`);
+                    }
+                }
+                // Every shape question above was answered from the RESOLVED tree, which
+                // is exactly what makes an aliased path item read as an ordinary
+                // mapping. The WRITE cannot be that forgiving: `setIn` walks the AST,
+                // and one shared value backs every use of an anchor, so an operation
+                // merged through the alias would land in every other path that
+                // references it. There is no way to write into one use of an anchor and
+                // not the rest, so this is a refusal rather than a fallback — and it is
+                // asked here, at the write, because reading is safe and writing is not.
+                if (!isMap(living.getIn(["paths", path]))) {
+                    throw new OpenapiMergeError("living", service, `path '${path}' is written as a YAML alias — one shared value backs every use, so merging into it would rewrite every other path that aliases it. Expand it before archiving.`);
+                }
+                // Without the strip the living contract would grow a pin to a version
+                // of itself, and the NEXT feature's baseline would hash it.
+                living.setIn(["paths", path, m], publishable[m]);
+                written.push({ from: `paths ${path}`, value: publishable[m] });
+            }
+            // No methods left means the path goes, whatever else survived beside
+            // them — the same cleanup stripOpenapiRemovalMarkers does on the
+            // feature side, and the reason is spelled once, on the helper.
+            dropPathIfNoOperations(living, path);
+            continue;
+        }
+        if (!isRecord(featItemPlain)) {
+            throw new OpenapiMergeError("feature", service, `path '${path}' is not a mapping`);
+        }
+        const clean = withoutFeatureMarkers(featItemPlain);
+        if (clean !== undefined) {
+            living.setIn(["paths", path], clean);
+            written.push({ from: `paths ${path}`, value: clean });
+        }
+    }
+    const closure = mergeComponentClosure({ living, featPlain, livingPlain, record, written, componentsAreTheDelta });
+    const { componentsModified, componentsAdded, componentsQuoted, componentsStale, unresolved } = closure;
+    // Over the living text, so every entry the merge did not touch keeps the
+    // author's bytes (`writeTreeOver` says what re-serializing cost).
+    const text = writeTreeOver(living, livingText, openapiRefusal("living", service));
+    return {
+        text, modified, modifiedOperationIds, pathItemModified, removed, quoted, baselineStale,
+        pathItemQuoted, pathItemStale, componentsModified, componentsAdded, componentsQuoted, componentsStale, unresolved,
+    };
+}
+/**
+ * The successful "the feature document has nothing to merge" answer. Every key
+ * of the result is spelled here, empty, rather than left off: the two objects
+ * are compared field by field in the tests and read field by field by the plan,
+ * and a `noop()` that quietly lacked a key would make "no delta" and "a delta
+ * that merged nothing" structurally different shapes of the same answer.
+ */
+function noop() {
+    return {
+        text: null, modified: [], modifiedOperationIds: new Map(), pathItemModified: [], removed: [], quoted: [],
+        baselineStale: [], pathItemQuoted: [], pathItemStale: [], componentsModified: [], componentsAdded: [],
+        componentsQuoted: [], componentsStale: [], unresolved: [],
+    };
+}
+//# sourceMappingURL=merge.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"merge.js","sourceRoot":"","sources":["../../../../src/core/openapi/merge/merge.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The archive-time merge: a feature's contract folded into the living one, and\n * every condition the caller has to surface afterwards.\n *\n * The result type carries far more than the merged text on purpose. A merge\n * that quietly overwrote an operation, dropped a component, or ran against a\n * stale baseline is not an error — it is a fact the archiving human has to be\n * told, and a return value nobody can forget to read is the only place that\n * survives a refactor.\n */\nimport { isDeepStrictEqual } from \"node:util\";\nimport { isMap } from \"yaml\";\n// Every `isRecord` below asks one question of a resolved plain tree: is this a\n// node that can hold OpenAPI keys — an object, not an array?\nimport { isRecord } from \"../../kernel/records.js\";\nimport { HTTP_METHODS } from \"../doc.js\";\nimport { OpenapiMergeError, openapiRefusal } from \"./error.js\";\nimport { readTree, writeTreeOver } from \"../contract-tree.js\";\nimport { classifyOperationBaseline } from \"./pin.js\";\nimport { classifyBaselineDigests, isRemoval, valueDigest } from \"../digest.js\";\nimport { entryFor, readBaselineRecord, restatedSurfaces } from \"../baseline/record.js\";\nimport { dropPathIfNoOperations, opLabel, operationIdOf, plainChild, withoutFeatureMarkers } from \"./markers.js\";\nimport { mergeComponentClosure } from \"./components.js\";\n\n/** What an OpenAPI path merge computed, including every condition the caller must surface. */\nexport interface OpenapiMergeResult {\n  /**\n   * The merged living document, or null when the feature document restates\n   * nothing at all — neither a path entry nor a component. It used to be null\n   * for a document with no `paths` key whatever its components said, and a\n   * delta whose whole change was a shared schema archived at exit 0 having\n   * merged nothing.\n   */\n  text: string | null;\n  /** Labels of existing operations overwritten with different content. */\n  modified: string[];\n  /**\n   * The operationId each `modified` label overwrites, keyed by the label: the\n   * LIVING operation's id, or the delta's when the living slot carries none.\n   * The living id first because it is the join key consumers name today —\n   * `loam archive` asks the fleet's consumer scan with it, to say who the\n   * overwrite lands on. A label whose operation carries no id on either side\n   * is absent: nothing can name it, so no consumer joins to it by name.\n   */\n  modifiedOperationIds: ReadonlyMap<string, string>;\n  /**\n   * Labels of PATH-LEVEL keys (`parameters`, `servers`, `summary`, `x-*`)\n   * overwritten with different content. They are not operations, so they were\n   * excluded from the difference check entirely and overwritten in silence —\n   * a delta restating a path with a shorter `parameters` list dropped shared\n   * parameters from every operation under it, and the plan said nothing.\n   */\n  pathItemModified: string[];\n  /** Labels of living operations deleted by `x-loam-remove: true` markers. */\n  removed: string[];\n  /**\n   * Labels of operations the delta QUOTED — pinned, and equal to their own\n   * baseline — so the merge left the living contract's own copy alone. Reported\n   * rather than silent: \"your delta mentions this and I did not write it\" is\n   * exactly the sentence whose absence made the revert invisible.\n   */\n  quoted: string[];\n  /**\n   * Labels of operations whose pin matches neither the delta's own content nor\n   * the living one: edited here AND changed by somebody else in between.\n   * `openapi.baseline-stale` refuses these at the gate; the merge still\n   * overwrites, because reaching it at all means `--approve` said to.\n   */\n  baselineStale: string[];\n  /** Path-level keys the delta QUOTED (`x-loam-baselines` entry equal to own content) — skipped, living's copy kept. */\n  pathItemQuoted: string[];\n  /** Path-level keys written on a stale record entry — reaching the merge means `--approve` said to. */\n  pathItemStale: string[];\n  /** `<kind>/<name>` of living components overwritten with different content. */\n  componentsModified: string[];\n  /**\n   * `<kind>/<name>` of components written into a living contract that did not\n   * have them. Beside `componentsModified` because the plan needs a name for\n   * what a merge ADDED: a components-only delta merges no operation, and the\n   * plan line naming the merged operation ids read `merged ()` for it — empty\n   * parentheses, which is how a merge that published a new shared schema\n   * looked exactly like one that did nothing.\n   */\n  componentsAdded: string[];\n  /** Components the delta QUOTED — not copied, living's copy kept. */\n  componentsQuoted: string[];\n  /** Components written on a stale record entry — under `--approve`, like the operations. */\n  componentsStale: string[];\n  /** Local refs reachable from merged content that resolve in neither document. */\n  unresolved: Array<{ ref: string; from: string }>;\n}\n\n\n/**\n * Merge the feature's `paths` into the living OpenAPI structurally (YAML AST, not\n * text splicing). A feature document restating NOTHING — no path entry and no\n * component — is a successful no-op; one whose whole delta is a component is\n * merged like any other, through the closure at the end of this function.\n * The merged operations' local component-ref closure rides along recursively;\n * external refs are left untouched and never gated.\n *\n * Every SHAPE question — is there a `paths` mapping, is this path item a\n * mapping, which methods does it hold — is answered from the RESOLVED plain\n * trees, never from the AST node. Asking the AST (`isMap(node)`) answers a\n * different question: an alias node is not a map even when it resolves to one.\n * `paths: *alias` therefore read as \"no paths to merge\" and the whole contract\n * delta was dropped with a successful exit, and an aliased path ITEM fell into\n * the wholesale-replace branch and deleted every living operation on that path\n * that the alias did not restate. Aliases are legal OpenAPI and the natural way\n * to write a delta that repeats a shape; nothing here may treat them as absent.\n * An alias that cannot be resolved at all is a document loam cannot read, and\n * says so — it is never \"nothing to merge\".\n */\nexport function mergeOpenapiPaths(\n  livingText: string,\n  featureText: string,\n  service: string,\n): OpenapiMergeResult {\n  // Aliases resolved once, with the document's own anchor context (readTree).\n  const { plain: featPlain } = readTree(featureText, openapiRefusal(\"feature\", service));\n  const featPathsPlain = plainChild(featPlain, \"paths\");\n  // The SHAPE refusal is unchanged and stays first: a `paths` that is a\n  // sequence or a scalar is a document loam cannot merge. Absent and null\n  // (`paths:` with nothing under it) are not shape faults — they are documents\n  // holding no path entries, which is a different sentence and now has a\n  // different answer.\n  if (featPathsPlain !== undefined && featPathsPlain !== null && !isRecord(featPathsPlain)) {\n    throw new OpenapiMergeError(\"feature\", service, \"`paths` is not a mapping\");\n  }\n  const featPathEntries = isRecord(featPathsPlain) ? Object.entries(featPathsPlain) : [];\n  // \"Is there anything to merge?\" is a question about the whole delta, and for\n  // years it was asked of `paths` alone — an absence test standing in for the\n  // decision. It returned here, before the living document was even parsed, so\n  // the component closure (the last statement of this function, and the only\n  // thing that writes a component) never ran: a feature whose entire change was\n  // a shared schema passed the gate and archived at exit 0 having merged\n  // NOTHING. The components answer it too now, over the ONE surface\n  // enumeration the gate and the rebase plan already grade the delta with.\n  const componentsAreTheDelta = featPathEntries.length === 0;\n  if (componentsAreTheDelta && !restatedSurfaces(featPlain).some((s) => s.kind === \"component\")) {\n    return noop();\n  }\n\n  const { doc: living, plain: livingPlain } = readTree(livingText, openapiRefusal(\"living\", service));\n  const livingPathsPlain = plainChild(livingPlain, \"paths\");\n  if (livingPathsPlain !== undefined && livingPathsPlain !== null && !isRecord(livingPathsPlain)) {\n    throw new OpenapiMergeError(\"living\", service, \"`paths` is not a mapping\");\n  }\n  const modified: string[] = [];\n  const modifiedOperationIds = new Map<string, string>();\n  const pathItemModified: string[] = [];\n  const removed: string[] = [];\n  const quoted: string[] = [];\n  const baselineStale: string[] = [];\n  const pathItemQuoted: string[] = [];\n  const pathItemStale: string[] = [];\n  // The surface record, read ONCE for the path-item loop and the component\n  // closure. Malformed entries read back as absent — the gate refuses them,\n  // and a value nobody can evaluate must never be why a merge skips a write.\n  const { record } = readBaselineRecord(featPlain);\n  // The plain values this merge actually WRITES, labelled for the ref sweep:\n  // the closure copies new components reachable from these, and only these —\n  // a quoted operation's refs are living's own business.\n  const written: Array<{ from: string; value: unknown }> = [];\n  for (const [path, featItemPlain] of featPathEntries) {\n    const existing = living.getIn([\"paths\", path]);\n    const existingPlain = plainChild(livingPathsPlain, path);\n    if (existing !== undefined && !isRecord(existingPlain)) {\n      // The living contract holds this path as something other than a path\n      // item. Replacing it wholesale is the one branch that may delete living\n      // operations without naming them, so it is reserved for paths the living\n      // contract does not have at all.\n      throw new OpenapiMergeError(\"living\", service, `path '${path}' is not a mapping`);\n    }\n    if (existing !== undefined) {\n      if (!isRecord(featItemPlain)) {\n        throw new OpenapiMergeError(\"feature\", service, `path '${path}' is not a mapping`);\n      }\n      // EVERY branch publishes through withoutFeatureMarkers. This one used to\n      // copy every key of the feature path item and guard only the HTTP\n      // methods, so a path-level `x-loam-remove` landed in the living contract\n      // with `modified: []` and no warning. A key the strip drops is never\n      // written; the removal handling below still reads the RAW item, because\n      // that is where the markers it acts on live.\n      const publish = withoutFeatureMarkers(featItemPlain);\n      const publishable = isRecord(publish) ? publish : {};\n      for (const [m, afterPlain] of Object.entries(featItemPlain)) {\n        const before = living.getIn([\"paths\", path, m]);\n        const beforePlain = plainChild(existingPlain, m);\n        if (HTTP_METHODS.has(m) && isRemoval(afterPlain)) {\n          // Coherence validates the marker and gates absent/mismatched targets.\n          // The merge remains defensive under --approve: never delete a\n          // different operation merely because it occupies the requested slot.\n          if (\n            before !== undefined &&\n            operationIdOf(beforePlain) !== undefined &&\n            operationIdOf(beforePlain) === operationIdOf(afterPlain)\n          ) {\n            removed.push(opLabel(beforePlain, afterPlain, m, path));\n            living.deleteIn([\"paths\", path, m]);\n          }\n          continue;\n        }\n        if (HTTP_METHODS.has(m)) {\n          const verdict = classifyOperationBaseline(afterPlain, before === undefined ? undefined : beforePlain);\n          // A QUOTE is not a merge input. The author wrote this operation down\n          // as a restatement, not because they changed it, so\n          // the living contract keeps whatever it holds — including a change\n          // that landed after this delta was written. This is mechanical, not a\n          // judgement, so `--approve` does not turn it back on: overriding a\n          // gate is a decision, reverting an operation nobody edited is a bug.\n          if (verdict === \"quote\") {\n            quoted.push(opLabel(beforePlain, afterPlain, m, path));\n            continue;\n          }\n          if (verdict === \"stale\") baselineStale.push(opLabel(beforePlain, afterPlain, m, path));\n        }\n        if (!(m in publishable)) {\n          // A feature-only marker at path level. It is never published, and\n          // never reported as a path-item overwrite either — it is not a key of\n          // the contract at all. The archive gate names it to the author.\n          continue;\n        }\n        if (!HTTP_METHODS.has(m)) {\n          // The operations' verdict, for the keys beside them, from the root\n          // record instead of an in-value pin. A QUOTE is skipped for the\n          // operations' reason — the author restated it, they did not edit it\n          // — and skipping matters MORE here: a path-level key applies to\n          // every operation on the path, including ones this feature never\n          // mentions. Stale still writes: reaching the merge means --approve.\n          const verdict = classifyBaselineDigests(\n            entryFor(record, { kind: \"path-item\", path, key: m, value: afterPlain }),\n            valueDigest(afterPlain),\n            before === undefined ? undefined : valueDigest(beforePlain),\n          );\n          if (verdict === \"quote\") {\n            pathItemQuoted.push(`'${m}' (${path})`);\n            continue;\n          }\n          if (verdict === \"stale\") pathItemStale.push(`'${m}' (${path})`);\n        }\n        // The difference check covers EVERY key of the path item; only the\n        // LABEL depends on whether the key is an HTTP method.\n        if (before !== undefined && !isDeepStrictEqual(beforePlain, afterPlain)) {\n          if (HTTP_METHODS.has(m)) {\n            const label = opLabel(beforePlain, afterPlain, m, path);\n            modified.push(label);\n            const id = operationIdOf(beforePlain) ?? operationIdOf(afterPlain);\n            if (id !== undefined) modifiedOperationIds.set(label, id);\n          } else {\n            pathItemModified.push(`'${m}' (${path})`);\n          }\n        }\n        // Every shape question above was answered from the RESOLVED tree, which\n        // is exactly what makes an aliased path item read as an ordinary\n        // mapping. The WRITE cannot be that forgiving: `setIn` walks the AST,\n        // and one shared value backs every use of an anchor, so an operation\n        // merged through the alias would land in every other path that\n        // references it. There is no way to write into one use of an anchor and\n        // not the rest, so this is a refusal rather than a fallback — and it is\n        // asked here, at the write, because reading is safe and writing is not.\n        if (!isMap(living.getIn([\"paths\", path]))) {\n          throw new OpenapiMergeError(\n            \"living\",\n            service,\n            `path '${path}' is written as a YAML alias — one shared value backs every use, so merging into it would rewrite every other path that aliases it. Expand it before archiving.`,\n          );\n        }\n        // Without the strip the living contract would grow a pin to a version\n        // of itself, and the NEXT feature's baseline would hash it.\n        living.setIn([\"paths\", path, m], publishable[m]);\n        written.push({ from: `paths ${path}`, value: publishable[m] });\n      }\n      // No methods left means the path goes, whatever else survived beside\n      // them — the same cleanup stripOpenapiRemovalMarkers does on the\n      // feature side, and the reason is spelled once, on the helper.\n      dropPathIfNoOperations(living, path);\n      continue;\n    }\n    if (!isRecord(featItemPlain)) {\n      throw new OpenapiMergeError(\"feature\", service, `path '${path}' is not a mapping`);\n    }\n    const clean = withoutFeatureMarkers(featItemPlain);\n    if (clean !== undefined) {\n      living.setIn([\"paths\", path], clean);\n      written.push({ from: `paths ${path}`, value: clean });\n    }\n  }\n\n  const closure = mergeComponentClosure({ living, featPlain, livingPlain, record, written, componentsAreTheDelta });\n  const { componentsModified, componentsAdded, componentsQuoted, componentsStale, unresolved } = closure;\n\n  // Over the living text, so every entry the merge did not touch keeps the\n  // author's bytes (`writeTreeOver` says what re-serializing cost).\n  const text = writeTreeOver(living, livingText, openapiRefusal(\"living\", service));\n  return {\n    text, modified, modifiedOperationIds, pathItemModified, removed, quoted, baselineStale,\n    pathItemQuoted, pathItemStale, componentsModified, componentsAdded, componentsQuoted, componentsStale, unresolved,\n  };\n}\n\n/**\n * The successful \"the feature document has nothing to merge\" answer. Every key\n * of the result is spelled here, empty, rather than left off: the two objects\n * are compared field by field in the tests and read field by field by the plan,\n * and a `noop()` that quietly lacked a key would make \"no delta\" and \"a delta\n * that merged nothing\" structurally different shapes of the same answer.\n */\nfunction noop(): OpenapiMergeResult {\n  return {\n    text: null, modified: [], modifiedOperationIds: new Map(), pathItemModified: [], removed: [], quoted: [],\n    baselineStale: [], pathItemQuoted: [], pathItemStale: [], componentsModified: [], componentsAdded: [],\n    componentsQuoted: [], componentsStale: [], unresolved: [],\n  };\n}\n\n"]}

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

@@ -0,0 +1,110 @@
+/**
+ * The pin that tells a QUOTE from an EDIT.
+ *
+ * A feature's openapi.yaml needs only what it adds, changes or removes, but it
+ * may also restate living operations it does not change — for context, or a
+ * contract pasted whole — and then much of what it spells is quotation. Without
+ * a pin the merge cannot tell the two apart and upserts both,
+ * which is how a feature that only meant to touch `cancelOrder` silently
+ * reverted another team's landed change to `refundOrder` — no overlap between
+ * the 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.
+ */
+import { isMap } from "yaml";
+// Every `isRecord` below asks one question of a resolved plain tree: is this a
+// node that can hold OpenAPI keys — an object, not an array?
+import { isRecord } from "../../kernel/records.js";
+import { HTTP_METHODS } from "../doc.js";
+import { classifyBaselineDigests, operationBaselineOf, operationDigest, OPENAPI_BASELINE_KEY, } from "../digest.js";
+import { openapiRefusal } from "./error.js";
+import { readTree, writeTreeOver } from "../contract-tree.js";
+import { isRemoval } from "../digest.js";
+import { plainChild } from "./markers.js";
+/**
+ * Classify one feature operation against its living counterpart, from the raw
+ * YAML trees the merge works in: what the operation IS, relative to the living
+ * contract — the one judgement that tells a QUOTE from an EDIT (the module
+ * header says why that judgement exists). The rule itself lives in
+ * ../digest.ts, so the gate and the merge cannot drift apart about which
+ * operations get written.
+ *
+ * A malformed pin matches no digest and lands in `stale`, which merges rather
+ * than skips. Deliberate: `openapi.baseline-invalid` refuses it at the gate, and
+ * a value nobody can evaluate must never be the reason a merge quietly drops an
+ * operation.
+ */
+export function classifyOperationBaseline(featureOp, livingOp) {
+    return classifyBaselineDigests(operationBaselineOf(featureOp), operationDigest(featureOp), livingOp === undefined ? undefined : operationDigest(livingOp));
+}
+/**
+ * Pin every operation in a feature contract against the living one — what
+ * `loam rebase` writes on this axis.
+ *
+ * The pin is always `operationDigest` of the LIVING operation, never of the
+ * delta's own, and that single rule produces both merge verdicts by itself: an
+ * operation the author only QUOTED is byte-equal to living, so its pin equals
+ * its own content and `classifyOperationBaseline` calls it a quote; one the
+ * author EDITED differs from its pin, so the merge writes it. Nothing has to
+ * guess at intent — the document already records it, and the pin makes it
+ * legible to the merge.
+ *
+ * Slot-keyed (path + method), exactly as the merge upserts. An operationId that
+ * moved to another slot is a new slot with nothing living behind it, which is
+ * `unresolved` and correct: there is no living version of an operation at a
+ * path the contract does not serve yet.
+ */
+export function pinOpenapiOperations(featureText, livingText, service) {
+    const { doc, plain: featPlain } = readTree(featureText, openapiRefusal("feature", service));
+    const { plain: livingPlain } = readTree(livingText, openapiRefusal("living", service));
+    const featPaths = plainChild(featPlain, "paths");
+    if (!isRecord(featPaths))
+        return { text: null, pins: [] };
+    const livingPaths = plainChild(livingPlain, "paths");
+    const pins = [];
+    let edited = false;
+    for (const [path, item] of Object.entries(featPaths)) {
+        if (!isRecord(item))
+            continue;
+        for (const [method, op] of Object.entries(item)) {
+            if (!HTTP_METHODS.has(method) || !isRecord(op))
+                continue;
+            // A removal marker asserts a slot rather than restating an operation, so
+            // it has nothing to be based on; `openapi.remove-target-mismatch` is what
+            // guards it against a living slot that moved under it.
+            if (isRemoval(op))
+                continue;
+            const id = typeof op["operationId"] === "string" ? op["operationId"] : "";
+            const at = { path, method, operationId: id };
+            const from = operationBaselineOf(op) ?? null;
+            const livingItem = plainChild(livingPaths, path);
+            const livingOp = isRecord(livingItem) ? livingItem[method] : undefined;
+            if (!isRecord(livingOp)) {
+                pins.push({ ...at, status: "unresolved", from, to: null });
+                continue;
+            }
+            const digest = operationDigest(livingOp);
+            if (from === digest) {
+                pins.push({ ...at, status: "unchanged", from: digest, to: digest });
+                continue;
+            }
+            // One shared value backs every use of an anchor, so `setIn` through an
+            // alias would pin every other use of it too — the same reason
+            // stripOpenapiRemovalMarkers refuses to edit aliases in place.
+            if (!isMap(doc.getIn(["paths", path, method]))) {
+                pins.push({ ...at, status: "unwritable", from, to: null });
+                continue;
+            }
+            pins.push({ ...at, status: from === null ? "pinned" : "repinned", from, to: digest });
+            doc.setIn(["paths", path, method, OPENAPI_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, openapiRefusal("feature", service)), pins };
+}
+//# sourceMappingURL=pin.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pin.js","sourceRoot":"","sources":["../../../../src/core/openapi/merge/pin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAC7B,+EAA+E;AAC/E,6DAA6D;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAAkB,EAAE,QAAiB;IAC7E,OAAO,uBAAuB,CAC5B,mBAAmB,CAAC,SAAS,CAAC,EAC9B,eAAe,CAAC,SAAS,CAAC,EAC1B,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,QAAQ,CAAC,CAC/D,CAAC;AACJ,CAAC;AA6BD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmB,EAAE,UAAkB,EAAE,OAAe;IAC3F,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5F,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IAEvF,MAAM,SAAS,GAAG,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACjD,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IAC1D,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAErD,MAAM,IAAI,GAAmB,EAAE,CAAC;IAChC,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,SAAS;QAC9B,KAAK,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAAE,SAAS;YACzD,yEAAyE;YACzE,0EAA0E;YAC1E,uDAAuD;YACvD,IAAI,SAAS,CAAC,EAAE,CAAC;gBAAE,SAAS;YAE5B,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC,aAAa,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1E,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;YAC7C,MAAM,IAAI,GAAG,mBAAmB,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC;YAC7C,MAAM,UAAU,GAAG,UAAU,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;YACjD,MAAM,QAAQ,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACvE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACxB,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC3D,SAAS;YACX,CAAC;YACD,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;YACzC,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;gBACpB,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;gBACpE,SAAS;YACX,CAAC;YACD,uEAAuE;YACvE,8DAA8D;YAC9D,+DAA+D;YAC/D,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/C,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC3D,SAAS;YACX,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;YACtF,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,oBAAoB,CAAC,EAAE,MAAM,CAAC,CAAC;YACjE,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;IACH,CAAC;IAED,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACzC,0EAA0E;IAC1E,mDAAmD;IACnD,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,GAAG,EAAE,WAAW,EAAE,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;AAC7F,CAAC","sourcesContent":["/**\n * The pin that tells a QUOTE from an EDIT.\n *\n * A feature's openapi.yaml needs only what it adds, changes or removes, but it\n * may also restate living operations it does not change — for context, or a\n * contract pasted whole — and then much of what it spells is quotation. Without\n * a pin the merge cannot tell the two apart and upserts both,\n * which is how a feature that only meant to touch `cancelOrder` silently\n * reverted another team's landed change to `refundOrder` — no overlap between\n * the two features required, just two deltas over one service.\n *\n * Separate from `./merge.ts` because this is `loam rebase`'s half: it plans the\n * pins a delta is missing, while the merge only ever reads pins already written.\n */\nimport { isMap } from \"yaml\";\n// Every `isRecord` below asks one question of a resolved plain tree: is this a\n// node that can hold OpenAPI keys — an object, not an array?\nimport { isRecord } from \"../../kernel/records.js\";\nimport { HTTP_METHODS } from \"../doc.js\";\nimport {\n  classifyBaselineDigests,\n  operationBaselineOf,\n  operationDigest,\n  OPENAPI_BASELINE_KEY,\n} from \"../digest.js\";\nimport { openapiRefusal } from \"./error.js\";\nimport { readTree, writeTreeOver } from \"../contract-tree.js\";\nimport { isRemoval } from \"../digest.js\";\nimport { plainChild } from \"./markers.js\";\n\n/**\n * Classify one feature operation against its living counterpart, from the raw\n * YAML trees the merge works in: what the operation IS, relative to the living\n * contract — the one judgement that tells a QUOTE from an EDIT (the module\n * header says why that judgement exists). The rule itself lives in\n * ../digest.ts, so the gate and the merge cannot drift apart about which\n * operations get written.\n *\n * A malformed pin matches no digest and lands in `stale`, which merges rather\n * than skips. Deliberate: `openapi.baseline-invalid` refuses it at the gate, and\n * a value nobody can evaluate must never be the reason a merge quietly drops an\n * operation.\n */\nexport function classifyOperationBaseline(featureOp: unknown, livingOp: unknown): ReturnType<typeof classifyBaselineDigests> {\n  return classifyBaselineDigests(\n    operationBaselineOf(featureOp),\n    operationDigest(featureOp),\n    livingOp === undefined ? undefined : operationDigest(livingOp),\n  );\n}\n\n/** What happened to one operation's `x-loam-based-on`. */\nexport interface OperationPin {\n  path: string;\n  method: string;\n  /** Empty when the operation declares none — the slot is still the identity. */\n  operationId: 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 operation at this slot: this feature is adding it. */\n    | \"unresolved\"\n    /** Written as a YAML alias — one shared value backs every use, so loam will not stamp through it. */\n    | \"unwritable\";\n  from: string | null;\n  to: string | null;\n}\n\nexport interface OpenapiPinPlan {\n  /** The rewritten contract, or null when no pin changes. */\n  text: string | null;\n  pins: OperationPin[];\n}\n\n/**\n * Pin every operation in a feature contract against the living one — what\n * `loam rebase` writes on this axis.\n *\n * The pin is always `operationDigest` of the LIVING operation, never of the\n * delta's own, and that single rule produces both merge verdicts by itself: an\n * operation the author only QUOTED is byte-equal to living, so its pin equals\n * its own content and `classifyOperationBaseline` calls it a quote; one the\n * author EDITED differs from its pin, so the merge writes it. Nothing has to\n * guess at intent — the document already records it, and the pin makes it\n * legible to the merge.\n *\n * Slot-keyed (path + method), exactly as the merge upserts. An operationId that\n * moved to another slot is a new slot with nothing living behind it, which is\n * `unresolved` and correct: there is no living version of an operation at a\n * path the contract does not serve yet.\n */\nexport function pinOpenapiOperations(featureText: string, livingText: string, service: string): OpenapiPinPlan {\n  const { doc, plain: featPlain } = readTree(featureText, openapiRefusal(\"feature\", service));\n  const { plain: livingPlain } = readTree(livingText, openapiRefusal(\"living\", service));\n\n  const featPaths = plainChild(featPlain, \"paths\");\n  if (!isRecord(featPaths)) return { text: null, pins: [] };\n  const livingPaths = plainChild(livingPlain, \"paths\");\n\n  const pins: OperationPin[] = [];\n  let edited = false;\n  for (const [path, item] of Object.entries(featPaths)) {\n    if (!isRecord(item)) continue;\n    for (const [method, op] of Object.entries(item)) {\n      if (!HTTP_METHODS.has(method) || !isRecord(op)) continue;\n      // A removal marker asserts a slot rather than restating an operation, so\n      // it has nothing to be based on; `openapi.remove-target-mismatch` is what\n      // guards it against a living slot that moved under it.\n      if (isRemoval(op)) continue;\n\n      const id = typeof op[\"operationId\"] === \"string\" ? op[\"operationId\"] : \"\";\n      const at = { path, method, operationId: id };\n      const from = operationBaselineOf(op) ?? null;\n      const livingItem = plainChild(livingPaths, path);\n      const livingOp = isRecord(livingItem) ? livingItem[method] : undefined;\n      if (!isRecord(livingOp)) {\n        pins.push({ ...at, status: \"unresolved\", from, to: null });\n        continue;\n      }\n      const digest = operationDigest(livingOp);\n      if (from === digest) {\n        pins.push({ ...at, status: \"unchanged\", from: digest, to: digest });\n        continue;\n      }\n      // One shared value backs every use of an anchor, so `setIn` through an\n      // alias would pin every other use of it too — the same reason\n      // stripOpenapiRemovalMarkers refuses to edit aliases in place.\n      if (!isMap(doc.getIn([\"paths\", path, method]))) {\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      doc.setIn([\"paths\", path, method, OPENAPI_BASELINE_KEY], digest);\n      edited = true;\n    }\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, openapiRefusal(\"feature\", service)), pins };\n}\n\n\n"]}