@davmash/bygone 0.10.0 → 0.11.0

package/out/changeCorrespondence.js

@@ -0,0 +1,739 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/changeCorrespondence.ts
+var changeCorrespondence_exports = {};
+__export(changeCorrespondence_exports, {
+  importChangeCorrespondence: () => importChangeCorrespondence,
+  loadChangeCorrespondence: () => loadChangeCorrespondence,
+  readCorrespondenceJson: () => readCorrespondenceJson,
+  validateChangeCorrespondence: () => validateChangeCorrespondence
+});
+module.exports = __toCommonJS(changeCorrespondence_exports);
+var import_crypto = require("crypto");
+var import_child_process = require("child_process");
+var import_fs = require("fs");
+
+// node_modules/diff/lib/index.mjs
+function Diff() {
+}
+Diff.prototype = {
+  diff: function diff(oldString, newString) {
+    var _options$timeout;
+    var options = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : {};
+    var callback = options.callback;
+    if (typeof options === "function") {
+      callback = options;
+      options = {};
+    }
+    this.options = options;
+    var self = this;
+    function done(value) {
+      if (callback) {
+        setTimeout(function() {
+          callback(void 0, value);
+        }, 0);
+        return true;
+      } else {
+        return value;
+      }
+    }
+    oldString = this.castInput(oldString);
+    newString = this.castInput(newString);
+    oldString = this.removeEmpty(this.tokenize(oldString));
+    newString = this.removeEmpty(this.tokenize(newString));
+    var newLen = newString.length, oldLen = oldString.length;
+    var editLength = 1;
+    var maxEditLength = newLen + oldLen;
+    if (options.maxEditLength) {
+      maxEditLength = Math.min(maxEditLength, options.maxEditLength);
+    }
+    var maxExecutionTime = (_options$timeout = options.timeout) !== null && _options$timeout !== void 0 ? _options$timeout : Infinity;
+    var abortAfterTimestamp = Date.now() + maxExecutionTime;
+    var bestPath = [{
+      oldPos: -1,
+      lastComponent: void 0
+    }];
+    var newPos = this.extractCommon(bestPath[0], newString, oldString, 0);
+    if (bestPath[0].oldPos + 1 >= oldLen && newPos + 1 >= newLen) {
+      return done([{
+        value: this.join(newString),
+        count: newString.length
+      }]);
+    }
+    var minDiagonalToConsider = -Infinity, maxDiagonalToConsider = Infinity;
+    function execEditLength() {
+      for (var diagonalPath = Math.max(minDiagonalToConsider, -editLength); diagonalPath <= Math.min(maxDiagonalToConsider, editLength); diagonalPath += 2) {
+        var basePath = void 0;
+        var removePath = bestPath[diagonalPath - 1], addPath = bestPath[diagonalPath + 1];
+        if (removePath) {
+          bestPath[diagonalPath - 1] = void 0;
+        }
+        var canAdd = false;
+        if (addPath) {
+          var addPathNewPos = addPath.oldPos - diagonalPath;
+          canAdd = addPath && 0 <= addPathNewPos && addPathNewPos < newLen;
+        }
+        var canRemove = removePath && removePath.oldPos + 1 < oldLen;
+        if (!canAdd && !canRemove) {
+          bestPath[diagonalPath] = void 0;
+          continue;
+        }
+        if (!canRemove || canAdd && removePath.oldPos + 1 < addPath.oldPos) {
+          basePath = self.addToPath(addPath, true, void 0, 0);
+        } else {
+          basePath = self.addToPath(removePath, void 0, true, 1);
+        }
+        newPos = self.extractCommon(basePath, newString, oldString, diagonalPath);
+        if (basePath.oldPos + 1 >= oldLen && newPos + 1 >= newLen) {
+          return done(buildValues(self, basePath.lastComponent, newString, oldString, self.useLongestToken));
+        } else {
+          bestPath[diagonalPath] = basePath;
+          if (basePath.oldPos + 1 >= oldLen) {
+            maxDiagonalToConsider = Math.min(maxDiagonalToConsider, diagonalPath - 1);
+          }
+          if (newPos + 1 >= newLen) {
+            minDiagonalToConsider = Math.max(minDiagonalToConsider, diagonalPath + 1);
+          }
+        }
+      }
+      editLength++;
+    }
+    if (callback) {
+      (function exec() {
+        setTimeout(function() {
+          if (editLength > maxEditLength || Date.now() > abortAfterTimestamp) {
+            return callback();
+          }
+          if (!execEditLength()) {
+            exec();
+          }
+        }, 0);
+      })();
+    } else {
+      while (editLength <= maxEditLength && Date.now() <= abortAfterTimestamp) {
+        var ret = execEditLength();
+        if (ret) {
+          return ret;
+        }
+      }
+    }
+  },
+  addToPath: function addToPath(path, added, removed, oldPosInc) {
+    var last = path.lastComponent;
+    if (last && last.added === added && last.removed === removed) {
+      return {
+        oldPos: path.oldPos + oldPosInc,
+        lastComponent: {
+          count: last.count + 1,
+          added,
+          removed,
+          previousComponent: last.previousComponent
+        }
+      };
+    } else {
+      return {
+        oldPos: path.oldPos + oldPosInc,
+        lastComponent: {
+          count: 1,
+          added,
+          removed,
+          previousComponent: last
+        }
+      };
+    }
+  },
+  extractCommon: function extractCommon(basePath, newString, oldString, diagonalPath) {
+    var newLen = newString.length, oldLen = oldString.length, oldPos = basePath.oldPos, newPos = oldPos - diagonalPath, commonCount = 0;
+    while (newPos + 1 < newLen && oldPos + 1 < oldLen && this.equals(newString[newPos + 1], oldString[oldPos + 1])) {
+      newPos++;
+      oldPos++;
+      commonCount++;
+    }
+    if (commonCount) {
+      basePath.lastComponent = {
+        count: commonCount,
+        previousComponent: basePath.lastComponent
+      };
+    }
+    basePath.oldPos = oldPos;
+    return newPos;
+  },
+  equals: function equals(left, right) {
+    if (this.options.comparator) {
+      return this.options.comparator(left, right);
+    } else {
+      return left === right || this.options.ignoreCase && left.toLowerCase() === right.toLowerCase();
+    }
+  },
+  removeEmpty: function removeEmpty(array) {
+    var ret = [];
+    for (var i = 0; i < array.length; i++) {
+      if (array[i]) {
+        ret.push(array[i]);
+      }
+    }
+    return ret;
+  },
+  castInput: function castInput(value) {
+    return value;
+  },
+  tokenize: function tokenize(value) {
+    return value.split("");
+  },
+  join: function join(chars) {
+    return chars.join("");
+  }
+};
+function buildValues(diff2, lastComponent, newString, oldString, useLongestToken) {
+  var components = [];
+  var nextComponent;
+  while (lastComponent) {
+    components.push(lastComponent);
+    nextComponent = lastComponent.previousComponent;
+    delete lastComponent.previousComponent;
+    lastComponent = nextComponent;
+  }
+  components.reverse();
+  var componentPos = 0, componentLen = components.length, newPos = 0, oldPos = 0;
+  for (; componentPos < componentLen; componentPos++) {
+    var component = components[componentPos];
+    if (!component.removed) {
+      if (!component.added && useLongestToken) {
+        var value = newString.slice(newPos, newPos + component.count);
+        value = value.map(function(value2, i) {
+          var oldValue = oldString[oldPos + i];
+          return oldValue.length > value2.length ? oldValue : value2;
+        });
+        component.value = diff2.join(value);
+      } else {
+        component.value = diff2.join(newString.slice(newPos, newPos + component.count));
+      }
+      newPos += component.count;
+      if (!component.added) {
+        oldPos += component.count;
+      }
+    } else {
+      component.value = diff2.join(oldString.slice(oldPos, oldPos + component.count));
+      oldPos += component.count;
+      if (componentPos && components[componentPos - 1].added) {
+        var tmp = components[componentPos - 1];
+        components[componentPos - 1] = components[componentPos];
+        components[componentPos] = tmp;
+      }
+    }
+  }
+  var finalComponent = components[componentLen - 1];
+  if (componentLen > 1 && typeof finalComponent.value === "string" && (finalComponent.added || finalComponent.removed) && diff2.equals("", finalComponent.value)) {
+    components[componentLen - 2].value += finalComponent.value;
+    components.pop();
+  }
+  return components;
+}
+var characterDiff = new Diff();
+var extendedWordChars = /^[A-Za-z\xC0-\u02C6\u02C8-\u02D7\u02DE-\u02FF\u1E00-\u1EFF]+$/;
+var reWhitespace = /\S/;
+var wordDiff = new Diff();
+wordDiff.equals = function(left, right) {
+  if (this.options.ignoreCase) {
+    left = left.toLowerCase();
+    right = right.toLowerCase();
+  }
+  return left === right || this.options.ignoreWhitespace && !reWhitespace.test(left) && !reWhitespace.test(right);
+};
+wordDiff.tokenize = function(value) {
+  var tokens = value.split(/([^\S\r\n]+|[()[\]{}'"\r\n]|\b)/);
+  for (var i = 0; i < tokens.length - 1; i++) {
+    if (!tokens[i + 1] && tokens[i + 2] && extendedWordChars.test(tokens[i]) && extendedWordChars.test(tokens[i + 2])) {
+      tokens[i] += tokens[i + 2];
+      tokens.splice(i + 1, 2);
+      i--;
+    }
+  }
+  return tokens;
+};
+var lineDiff = new Diff();
+lineDiff.tokenize = function(value) {
+  if (this.options.stripTrailingCr) {
+    value = value.replace(/\r\n/g, "\n");
+  }
+  var retLines = [], linesAndNewlines = value.split(/(\n|\r\n)/);
+  if (!linesAndNewlines[linesAndNewlines.length - 1]) {
+    linesAndNewlines.pop();
+  }
+  for (var i = 0; i < linesAndNewlines.length; i++) {
+    var line = linesAndNewlines[i];
+    if (i % 2 && !this.options.newlineIsToken) {
+      retLines[retLines.length - 1] += line;
+    } else {
+      if (this.options.ignoreWhitespace) {
+        line = line.trim();
+      }
+      retLines.push(line);
+    }
+  }
+  return retLines;
+};
+function diffLines(oldStr, newStr, callback) {
+  return lineDiff.diff(oldStr, newStr, callback);
+}
+var sentenceDiff = new Diff();
+sentenceDiff.tokenize = function(value) {
+  return value.split(/(\S.+?[.!?])(?=\s+|$)/);
+};
+var cssDiff = new Diff();
+cssDiff.tokenize = function(value) {
+  return value.split(/([{}:;,]|\s+)/);
+};
+function _typeof(obj) {
+  "@babel/helpers - typeof";
+  if (typeof Symbol === "function" && typeof Symbol.iterator === "symbol") {
+    _typeof = function(obj2) {
+      return typeof obj2;
+    };
+  } else {
+    _typeof = function(obj2) {
+      return obj2 && typeof Symbol === "function" && obj2.constructor === Symbol && obj2 !== Symbol.prototype ? "symbol" : typeof obj2;
+    };
+  }
+  return _typeof(obj);
+}
+var objectPrototypeToString = Object.prototype.toString;
+var jsonDiff = new Diff();
+jsonDiff.useLongestToken = true;
+jsonDiff.tokenize = lineDiff.tokenize;
+jsonDiff.castInput = function(value) {
+  var _this$options = this.options, undefinedReplacement = _this$options.undefinedReplacement, _this$options$stringi = _this$options.stringifyReplacer, stringifyReplacer = _this$options$stringi === void 0 ? function(k, v) {
+    return typeof v === "undefined" ? undefinedReplacement : v;
+  } : _this$options$stringi;
+  return typeof value === "string" ? value : JSON.stringify(canonicalize(value, null, null, stringifyReplacer), stringifyReplacer, "  ");
+};
+jsonDiff.equals = function(left, right) {
+  return Diff.prototype.equals.call(jsonDiff, left.replace(/,([\r\n])/g, "$1"), right.replace(/,([\r\n])/g, "$1"));
+};
+function canonicalize(obj, stack, replacementStack, replacer, key) {
+  stack = stack || [];
+  replacementStack = replacementStack || [];
+  if (replacer) {
+    obj = replacer(key, obj);
+  }
+  var i;
+  for (i = 0; i < stack.length; i += 1) {
+    if (stack[i] === obj) {
+      return replacementStack[i];
+    }
+  }
+  var canonicalizedObj;
+  if ("[object Array]" === objectPrototypeToString.call(obj)) {
+    stack.push(obj);
+    canonicalizedObj = new Array(obj.length);
+    replacementStack.push(canonicalizedObj);
+    for (i = 0; i < obj.length; i += 1) {
+      canonicalizedObj[i] = canonicalize(obj[i], stack, replacementStack, replacer, key);
+    }
+    stack.pop();
+    replacementStack.pop();
+    return canonicalizedObj;
+  }
+  if (obj && obj.toJSON) {
+    obj = obj.toJSON();
+  }
+  if (_typeof(obj) === "object" && obj !== null) {
+    stack.push(obj);
+    canonicalizedObj = {};
+    replacementStack.push(canonicalizedObj);
+    var sortedKeys = [], _key;
+    for (_key in obj) {
+      if (obj.hasOwnProperty(_key)) {
+        sortedKeys.push(_key);
+      }
+    }
+    sortedKeys.sort();
+    for (i = 0; i < sortedKeys.length; i += 1) {
+      _key = sortedKeys[i];
+      canonicalizedObj[_key] = canonicalize(obj[_key], stack, replacementStack, replacer, _key);
+    }
+    stack.pop();
+    replacementStack.pop();
+  } else {
+    canonicalizedObj = obj;
+  }
+  return canonicalizedObj;
+}
+var arrayDiff = new Diff();
+arrayDiff.tokenize = function(value) {
+  return value.slice();
+};
+arrayDiff.join = arrayDiff.removeEmpty = function(value) {
+  return value;
+};
+
+// src/changeCorrespondence.ts
+var MAX_BYTES = 16 * 1024 * 1024;
+var MAX_SOURCE_BYTES = 8 * 1024 * 1024;
+var digest = (text) => (0, import_crypto.createHash)("sha256").update(text, "utf8").digest("hex");
+function object(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid correspondence object.");
+  return value;
+}
+function list(value, max = 2e4) {
+  if (!Array.isArray(value) || value.length > max) throw new Error("Invalid or over-budget correspondence array.");
+  return value;
+}
+function string(value) {
+  if (typeof value !== "string" || !value || value.length > 4096) throw new Error("Invalid correspondence string.");
+  return value;
+}
+function integer(value) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error("Invalid correspondence offset.");
+  return value;
+}
+function filePath(value) {
+  const name = string(value);
+  if (name.startsWith("/") || name.includes("\\") || name.includes("\0") || name.split("/").some((p) => !p || p === "." || p === "..")) {
+    throw new Error("Invalid correspondence repository path.");
+  }
+  return name;
+}
+function hash(value) {
+  const result = string(value);
+  if (!/^[0-9a-f]{64}$/.test(result)) throw new Error("Invalid correspondence digest.");
+  return result;
+}
+function status(value) {
+  if (value !== "complete" && value !== "partial" && value !== "unavailable") throw new Error("Invalid correspondence analysis status.");
+  return value;
+}
+function readCorrespondenceJson(file) {
+  if ((0, import_fs.statSync)(file).size > MAX_BYTES) throw new Error("Correspondence file exceeds 16 MiB.");
+  return JSON.parse((0, import_fs.readFileSync)(file, "utf8"));
+}
+function validateRange(value, expected) {
+  const input = object(value);
+  for (const key of ["baseOid", "headOid"]) {
+    if (input[key] !== expected[key] || !/^[0-9a-f]{40,64}$/.test(expected[key])) {
+      throw new Error("Correspondence revisions do not match the selected merge-base/head comparison.");
+    }
+  }
+  return { ...expected };
+}
+function validateChangeCorrespondence(repoRoot, input, expected) {
+  const data = object(input);
+  if (data.version !== 1) throw new Error("Unsupported correspondence version.");
+  const range = validateRange(data.range, expected);
+  const documents = object(data.documents), symbols = object(data.symbols);
+  const result = {
+    version: 1,
+    range,
+    producer: string(data.producer),
+    status: status(data.status),
+    documents: { before: [], after: [] },
+    symbols: { before: [], after: [] },
+    relations: [],
+    unresolved: [],
+    limitations: list(data.limitations, 100).map(string)
+  };
+  const entries = /* @__PURE__ */ new Map();
+  const documentsBySide = { before: /* @__PURE__ */ new Map(), after: /* @__PURE__ */ new Map() };
+  const lineIndexes = /* @__PURE__ */ new Map();
+  const lineAt = (side, path, start) => {
+    const key = `${side}:${path}`;
+    let lines = lineIndexes.get(key);
+    if (!lines) {
+      const text = documentsBySide[side].get(path);
+      lines = [0];
+      for (let at = text.indexOf("\n"); at !== -1; at = text.indexOf("\n", at + 1)) lines.push(at + 1);
+      lineIndexes.set(key, lines);
+    }
+    let low = 0, high = lines.length;
+    while (low < high) {
+      const mid = Math.floor((low + high) / 2);
+      if (lines[mid] <= start) low = mid + 1;
+      else high = mid;
+    }
+    return low;
+  };
+  let sourceBytes = 0, symbolBytes = 0;
+  for (const side of ["before", "after"]) {
+    const texts = /* @__PURE__ */ new Map();
+    const oid = side === "before" ? range.baseOid : range.headOid;
+    for (const value of list(documents[side], 128)) {
+      const doc = object(value), name = filePath(doc.path), expectedDigest = hash(doc.digest);
+      const documentStatus = string(doc.status);
+      if (!["complete", "invalid", "unsupported"].includes(documentStatus) || texts.has(name)) throw new Error("Invalid or duplicate correspondence document.");
+      const bytes = (0, import_child_process.execFileSync)("git", ["show", `${oid}:${name}`], { cwd: repoRoot, timeout: 1e4, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+      const text = bytes.toString("utf8");
+      sourceBytes += bytes.length;
+      if (sourceBytes > MAX_SOURCE_BYTES || !Buffer.from(text, "utf8").equals(bytes) || digest(text) !== expectedDigest) {
+        throw new Error(`Correspondence source digest mismatch or source budget exceeded: ${side}/${name}`);
+      }
+      texts.set(name, { text, status: documentStatus });
+      documentsBySide[side].set(name, text);
+      result.documents[side].push({ path: name, digest: expectedDigest, status: documentStatus, text });
+    }
+    for (const value of list(symbols[side])) {
+      const entry = object(value), name = filePath(entry.path), doc = texts.get(name);
+      const id = string(entry.id), start = integer(entry.start), end = integer(entry.end);
+      if (!doc || start >= end || end > doc.text.length || entries.has(id)) throw new Error("Invalid correspondence symbol ownership/range/ID.");
+      const text = doc.text.slice(start, end);
+      symbolBytes += Buffer.byteLength(text);
+      if (symbolBytes > MAX_SOURCE_BYTES || digest(text) !== hash(entry.digest)) throw new Error(`Correspondence symbol digest mismatch or budget exceeded: ${name}`);
+      const symbol = {
+        id,
+        path: name,
+        name: string(entry.name),
+        kind: string(entry.kind),
+        start,
+        end,
+        digest: digest(text),
+        text,
+        startLine: lineAt(side, name, start),
+        endLine: lineAt(side, name, end - 1)
+      };
+      entries.set(id, { side, symbol, documentStatus: doc.status });
+      result.symbols[side].push(symbol);
+    }
+  }
+  const ids = /* @__PURE__ */ new Set(), sources = /* @__PURE__ */ new Set(), destinations = /* @__PURE__ */ new Set();
+  for (const value of list(data.relations)) {
+    const relation = object(value), id = string(relation.id), sourceId = string(relation.sourceId), destinationId = string(relation.destinationId);
+    const source = entries.get(sourceId), destination = entries.get(destinationId);
+    if (ids.has(id) || sources.has(sourceId) || destinations.has(destinationId)) throw new Error("Conflicting correspondence continuations; preserve them as unresolved candidates.");
+    if (source?.side !== "before" || destination?.side !== "after" || source.documentStatus !== "complete" || destination.documentStatus !== "complete") {
+      throw new Error("Correspondence endpoints must resolve to valid, parsed before/after documents.");
+    }
+    ids.add(id);
+    sources.add(sourceId);
+    destinations.add(destinationId);
+    const producers = list(relation.producers, 10).map(string);
+    if (relation.coverage !== void 0 && relation.coverage !== "complete") throw new Error("Invalid correspondence relation coverage.");
+    const covered = result.status === "partial" && relation.coverage === "complete" && producers.some((producer) => ["refactoring-miner", "bygone-strand"].includes(producer));
+    if (result.status !== "complete" && !covered && !(producers.includes("exact-declaration") && source.symbol.text === destination.symbol.text)) continue;
+    const a = source.symbol, b = destination.symbol;
+    result.relations.push({
+      id,
+      sourceId,
+      destinationId,
+      producers,
+      pathChanged: a.path !== b.path,
+      nameChanged: a.name !== b.name,
+      ...relation.coverage === "complete" ? { coverage: "complete" } : {},
+      rawEqual: a.text === b.text,
+      behavior: "unassessed",
+      localDiff: (diffLines(a.text, b.text, { timeout: 100, maxEditLength: 2e3 }) || [{ value: a.text, removed: true }, { value: b.text, added: true }]).map((part) => ({
+        value: part.value,
+        ...part.added ? { added: true } : {},
+        ...part.removed ? { removed: true } : {}
+      }))
+    });
+  }
+  for (const value of list(data.unresolved)) {
+    const candidate = object(value);
+    const sourceIds = list(candidate.sourceIds).map(string), destinationIds = list(candidate.destinationIds).map(string);
+    if (!sourceIds.length && !destinationIds.length) throw new Error("Unresolved correspondence needs candidate endpoints.");
+    if (sourceIds.some((id) => entries.get(id)?.side !== "before") || destinationIds.some((id) => entries.get(id)?.side !== "after")) {
+      throw new Error("Unresolved correspondence references unknown endpoints.");
+    }
+    if (sourceIds.some((id) => sources.has(id)) || destinationIds.some((id) => destinations.has(id))) throw new Error("Ambiguous endpoints cannot also be accepted continuations.");
+    result.unresolved.push({ reason: string(candidate.reason), sourceIds, destinationIds });
+  }
+  if (data.diagnostics !== void 0) {
+    const diagnostics = object(data.diagnostics);
+    if (diagnostics.version !== 1) throw new Error("Unsupported correspondence diagnostics version.");
+    let locationCount = 0;
+    result.diagnostics = { version: 1, scope: list(diagnostics.scope, 20).map(string), records: list(diagnostics.records).map((value) => {
+      const record = object(value), category = string(record.category);
+      if (!["outside", "syntax", "rejected", "unmatched", "relationship", "problem"].includes(category)) throw new Error("Invalid correspondence diagnostic category.");
+      return {
+        category,
+        reason: string(record.reason),
+        ...record.message !== void 0 ? { message: string(record.message) } : {},
+        ...record.producerId !== void 0 ? { producerId: string(record.producerId) } : {},
+        locations: list(record.locations, 100).map((value2) => {
+          if (++locationCount > 4e4) throw new Error("Correspondence diagnostic location budget exceeded.");
+          const location = object(value2), path = filePath(location.path);
+          const side = location.side;
+          if (side !== void 0 && side !== "before" && side !== "after") throw new Error("Invalid diagnostic revision side.");
+          const symbolId = location.symbolId === void 0 ? void 0 : string(location.symbolId);
+          if (symbolId && (entries.get(symbolId)?.side !== side || entries.get(symbolId)?.symbol.path !== path)) throw new Error("Invalid diagnostic symbol reference.");
+          const start = location.start === void 0 ? symbolId ? entries.get(symbolId).symbol.start : void 0 : integer(location.start);
+          const text = side ? documentsBySide[side].get(path) : void 0;
+          if (start !== void 0 && (text === void 0 || start > text.length)) throw new Error("Invalid diagnostic source location.");
+          return {
+            path,
+            ...side ? { side } : {},
+            ...symbolId ? { symbolId } : {},
+            ...start !== void 0 ? { start, line: lineAt(side, path, start) } : {},
+            ...location.reason !== void 0 ? { reason: string(location.reason) } : {}
+          };
+        })
+      };
+    }) };
+  }
+  return result;
+}
+function loadChangeCorrespondence(repoRoot, file, range) {
+  return validateChangeCorrespondence(repoRoot, readCorrespondenceJson(file), range);
+}
+function importChangeCorrespondence(repoRoot, input, range) {
+  const analysis = object(object(input).analysis);
+  if (analysis.version !== 1) throw new Error("Unsupported producer analysis version.");
+  const inventories = object(analysis.inventories);
+  const before = object(inventories.before), after = object(inventories.after);
+  const inventoryEntries = {
+    before: new Map(list(before.entries).map(object).map((e) => [e.id, e])),
+    after: new Map(list(after.entries).map(object).map((e) => [e.id, e]))
+  };
+  const unresolved = list(analysis.unresolved).map((value) => {
+    const candidate = object(value);
+    return {
+      reason: candidate.reason || candidate.kind || "competing-origins",
+      sourceIds: candidate.sources || candidate.sourceIds || [],
+      destinationIds: candidate.destinations || candidate.destinationIds || []
+    };
+  });
+  const limitations = [
+    "Correspondence is inferred from externally supplied analysis; source checks do not prove lineage or behavior.",
+    "Symbol slices can exclude enclosing export/const/let syntax and surrounding bindings/imports; inspect complete file diffs for that context.",
+    "Analysis covers only the supplied documents and inventoried declarations; unmatched does not mean repository-wide absence.",
+    `${list(analysis.groups).length} extraction/inline groups are not accepted continuations.`,
+    `${list(analysis.rejected).length} producer candidates were rejected; ${list(analysis.issues).length} producer issues.`,
+    `${list(before.exclusions || []).length + list(after.exclusions || []).length} inventoried syntax exclusions (for example unsupported declaration forms).`,
+    `${list(analysis.unmatchedBefore).length} unmatched before symbols; ${list(analysis.unmatchedAfter).length} unmatched after symbols.`
+  ];
+  const engine = object(analysis.engine);
+  if (analysis.status === "complete" && (engine.truncated === true || engine.status !== "complete")) throw new Error("Incomplete engine analysis cannot be complete.");
+  if ((engine.truncated === true || engine.status !== "complete") && list(analysis.relations).some((value) => object(value).coverage === "complete")) {
+    throw new Error("Incomplete engine analysis cannot claim complete relation coverage.");
+  }
+  const detailed = ["before", "after"].every((side) => Array.isArray(object(inventories[side]).exclusions) && list(object(inventories[side]).documents).every((doc) => Array.isArray(object(doc).diagnostics)));
+  const records = [];
+  const add = (category, raw, locations = []) => {
+    const value = object(raw);
+    records.push({
+      category,
+      reason: string(value.reason),
+      locations,
+      ...value.message ? { message: string(value.message).slice(0, 4e3) } : {},
+      ...value.mapperId ? { producerId: string(value.mapperId) } : {}
+    });
+  };
+  const location = (raw, side, offsets = true) => {
+    if (!raw || typeof raw !== "object") return [];
+    const value = object(raw);
+    if (!value.path) return [];
+    return [{
+      path: filePath(value.path),
+      ...side ? { side } : {},
+      ...offsets && Number.isSafeInteger(value.start) && value.start >= 0 ? { start: value.start } : {},
+      ...value.symbolId ? { symbolId: string(value.symbolId) } : {},
+      ...value.reason ? { reason: string(value.reason) } : {}
+    }];
+  };
+  if (detailed) {
+    for (const side of ["before", "after"]) {
+      const inventory = object(inventories[side]);
+      for (const exclusion of list(inventory.exclusions)) add("syntax", exclusion, location(exclusion, side));
+      for (const raw of list(inventory.documents)) {
+        const doc = object(raw);
+        for (const diagnostic of list(doc.diagnostics)) add("problem", { ...object(diagnostic), reason: "parser-diagnostic" }, location({ ...object(diagnostic), path: doc.path }, side));
+      }
+    }
+    for (const raw of list(analysis.rejected)) {
+      const record = object(raw);
+      const endpoints = record.endpoints === void 0 ? [] : list(record.endpoints, 2);
+      add("rejected", record, endpoints.length ? endpoints.flatMap((endpoint) => {
+        const e = object(endpoint);
+        return location(e, e.side);
+      }) : [...location(record.source, "before", false), ...location(record.destination, "after", false)]);
+    }
+    for (const raw of list(analysis.issues)) {
+      const issue = object(raw), side = issue.side === "before" || issue.side === "after" ? issue.side : void 0;
+      const mapping = issue.mapping ? object(issue.mapping) : void 0;
+      add("problem", issue, [
+        ...location(issue, side, false),
+        ...location(issue.span, side, false),
+        ...location(mapping?.source, "before", false),
+        ...location(mapping?.destination, "after", false)
+      ]);
+    }
+    for (const raw of list(analysis.groups)) {
+      const group = object(raw), locations = [];
+      for (const [side, id] of [["before", group.sourceId], ["after", group.destinationId]]) {
+        const entry = inventoryEntries[side].get(id);
+        if (entry) locations.push(...location({ ...entry, symbolId: id }, side));
+      }
+      add("relationship", { reason: group.kind, message: "Detected relationship; not an accepted continuation. Behavior unassessed." }, locations);
+    }
+    for (const raw of list(analysis.unresolved)) {
+      const group = object(raw);
+      if (!["repeated-exact-occurrences", "ambiguous-js-candidates", "ambiguous-python-candidates"].includes(String(group.reason)) || group.competingSources === void 0) continue;
+      const locations = [];
+      for (const side of ["before", "after"]) {
+        for (const id of list(side === "before" ? group.competingSources : group.competingDestinations)) {
+          const entry = inventoryEntries[side].get(id);
+          if (!entry) throw new Error("Invalid competing-origin diagnostic symbol.");
+          locations.push(...location({ ...entry, symbolId: id }, side));
+        }
+      }
+      add("unmatched", {
+        reason: group.reason,
+        message: "Competing origins; retained local continuations are included as reference points, not unresolved bindings."
+      }, locations);
+    }
+    for (const raw of list(analysis.unmatchedDiagnostics || [])) {
+      const record = object(raw), side = record.side;
+      if (side !== "before" && side !== "after") throw new Error("Invalid unmatched diagnostic side.");
+      const entry = inventoryEntries[side].get(record.symbolId);
+      if (!entry) throw new Error("Invalid unmatched diagnostic symbol.");
+      add("unmatched", record, location({ ...entry, symbolId: record.symbolId }, side));
+    }
+    if (engine.status !== "complete" || engine.truncated === true) add("problem", {
+      reason: engine.truncated === true ? "engine-truncated" : "engine-incomplete",
+      message: `Engine status: ${string(engine.status)}${engine.reason ? `; ${string(engine.reason)}` : "; no reason supplied"}.`
+    });
+    const scope = analysis.scope === void 0 ? {} : object(analysis.scope);
+    for (const raw of list(scope.excluded || [])) {
+      const record = object(raw), side = record.oid === range.baseOid ? "before" : record.oid === range.headOid ? "after" : void 0;
+      add("outside", record, location(record, side, false));
+    }
+  }
+  const producer = engine.producer === "bygone-strand" ? "Bygone Strand correspondence engine v1" : "RefactoringMiner research mapping adapter v1";
+  const artifact = {
+    version: 1,
+    range,
+    producer,
+    status: analysis.status,
+    documents: { before: before.documents, after: after.documents },
+    symbols: { before: before.entries, after: after.entries },
+    relations: analysis.relations,
+    unresolved,
+    limitations,
+    ...detailed ? { diagnostics: { version: 1, scope: [String(object(analysis.scope || {}).note || "Supplied documents only; repository-wide origins were not searched.")], records } } : {}
+  };
+  return validateChangeCorrespondence(repoRoot, artifact, range);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  importChangeCorrespondence,
+  loadChangeCorrespondence,
+  readCorrespondenceJson,
+  validateChangeCorrespondence
+});
+//# sourceMappingURL=changeCorrespondence.js.map