@nimiplatform/nimi-coding 0.3.1 → 0.5.0

package/cli/lib/authority/diff.mjs

@@ -0,0 +1,310 @@
+import { Buffer } from "node:buffer";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+
+import { compileAuthorityPath } from "./compile.mjs";
+import { createCompiledAuthoritySnapshot } from "./compiled-snapshot.mjs";
+import { compareText, makeDiagnostic, portablePath, sortDiagnostics } from "./diagnostics.mjs";
+
+const DIFF_FORMAT = "nimicoding.authority-diff/v1";
+
+async function sourceRoot(inputPath) {
+  const absolute = path.resolve(inputPath);
+  try {
+    const info = await stat(absolute);
+    return info.isDirectory() ? absolute : path.dirname(absolute);
+  } catch {
+    return path.dirname(absolute);
+  }
+}
+
+function sidePath(file, basePath, side) {
+  const relative = portablePath(file, basePath);
+  const safe = path.isAbsolute(relative) ? path.basename(relative) : relative;
+  return path.posix.join(side, safe || ".");
+}
+
+function compareRelated(left, right) {
+  return compareText(left.path, right.path)
+    || left.range.start.line - right.range.start.line
+    || left.range.start.column - right.range.start.column
+    || compareText(left.pointer, right.pointer)
+    || compareText(left.role, right.role);
+}
+
+function sideDiagnostics(diagnostics, basePath, side) {
+  return diagnostics.map((diagnostic) => ({
+    ...diagnostic,
+    path: sidePath(diagnostic.path, basePath, side),
+    related: diagnostic.related
+      .map((related) => ({ ...related, path: sidePath(related.path, basePath, side) }))
+      .sort(compareRelated),
+  }));
+}
+
+function portableMapping(mapping, basePath) {
+  if (!mapping) return null;
+  return { ...mapping, file: portablePath(mapping.file, basePath) };
+}
+
+function mappedAt(snapshot, unitIndex, pointer) {
+  const exact = snapshot.compiled.sourceMap.fields[`/units/${unitIndex}${pointer}`];
+  if (exact) return portableMapping(exact, snapshot.inputRoot);
+  const prefix = `/units/${unitIndex}${pointer}/`;
+  const nested = Object.entries(snapshot.compiled.sourceMap.fields)
+    .filter(([candidate]) => candidate.startsWith(prefix))
+    .sort(([left], [right]) => compareText(left, right))[0]?.[1];
+  return portableMapping(nested, snapshot.inputRoot);
+}
+
+function addChange(changes, { unitId, operation = "modified", pointer, before, after, beforeSource = null, afterSource = null }) {
+  changes.push({
+    unitId,
+    operation,
+    pointer,
+    before,
+    after,
+    ...(beforeSource ? { beforeSource } : {}),
+    ...(afterSource ? { afterSource } : {}),
+  });
+}
+
+function compareScalar(changes, beforeSnapshot, afterSnapshot, beforeEntry, afterEntry, pointer) {
+  const before = beforeEntry.unit;
+  const after = afterEntry.unit;
+  const read = (value, parts) => parts.reduce((current, part) => current?.[part], value);
+  const parts = pointer.slice(1).split("/");
+  const left = read(before, parts) ?? null;
+  const right = read(after, parts) ?? null;
+  if (JSON.stringify(left) === JSON.stringify(right)) return;
+  addChange(changes, {
+    unitId: after.id,
+    pointer,
+    before: left,
+    after: right,
+    beforeSource: mappedAt(beforeSnapshot, beforeEntry.unitIndex, pointer),
+    afterSource: mappedAt(afterSnapshot, afterEntry.unitIndex, pointer),
+  });
+}
+
+function compareValueSet(changes, beforeSnapshot, afterSnapshot, beforeEntry, afterEntry, pointer) {
+  const parts = pointer.slice(1).split("/");
+  const read = (unit) => parts.reduce((current, part) => current?.[part], unit) ?? [];
+  const beforeValues = read(beforeEntry.unit);
+  const afterValues = read(afterEntry.unit);
+  const beforeSet = new Set(beforeValues.map((value) => JSON.stringify(value)));
+  const afterSet = new Set(afterValues.map((value) => JSON.stringify(value)));
+  for (const [operation, values, otherSet, snapshot, entry, sourceSide] of [
+    ["removed", beforeValues, afterSet, beforeSnapshot, beforeEntry, "beforeSource"],
+    ["added", afterValues, beforeSet, afterSnapshot, afterEntry, "afterSource"],
+  ]) {
+    values.forEach((value, index) => {
+      if (otherSet.has(JSON.stringify(value))) return;
+      addChange(changes, {
+        unitId: afterEntry.unit.id,
+        operation,
+        pointer,
+        before: operation === "removed" ? value : null,
+        after: operation === "added" ? value : null,
+        [sourceSide]: mappedAt(snapshot, entry.unitIndex, `${pointer}/${index}`),
+      });
+    });
+  }
+}
+
+function compareRelations(changes, beforeSnapshot, afterSnapshot, beforeEntry, afterEntry) {
+  const beforeRelations = beforeEntry.unit.relations;
+  const afterRelations = afterEntry.unit.relations;
+  const beforeSet = new Set(beforeRelations.map((edge) => `${edge.type}\0${edge.target}`));
+  const afterSet = new Set(afterRelations.map((edge) => `${edge.type}\0${edge.target}`));
+  for (const [operation, edges, otherSet, snapshot, entry, sourceSide] of [
+    ["removed", beforeRelations, afterSet, beforeSnapshot, beforeEntry, "beforeSource"],
+    ["added", afterRelations, beforeSet, afterSnapshot, afterEntry, "afterSource"],
+  ]) {
+    edges.forEach((edge, index) => {
+      if (otherSet.has(`${edge.type}\0${edge.target}`)) return;
+      addChange(changes, {
+        unitId: afterEntry.unit.id,
+        operation,
+        pointer: "/relations",
+        before: operation === "removed" ? edge : null,
+        after: operation === "added" ? edge : null,
+        [sourceSide]: mappedAt(snapshot, entry.unitIndex, `/relations/${index}`),
+      });
+    });
+  }
+}
+
+function sideMappedAt(snapshot, unitIndex, pointer, side) {
+  const mapped = mappedAt(snapshot, unitIndex, pointer);
+  return { ...mapped, file: path.posix.join(side, mapped.file) };
+}
+
+function transitionDiagnostics(before, after) {
+  const diagnostics = [];
+  for (const entry of before.byId.values()) {
+    const { unit, unitIndex } = entry;
+    if (after.byId.has(unit.id)) continue;
+    const mapped = sideMappedAt(before, unitIndex, "/id", "before");
+    diagnostics.push(makeDiagnostic({
+      code: "AUTH_DIFF_TRANSITION_INVALID",
+      file: mapped.file,
+      range: mapped.range,
+      pointer: mapped.sourcePointer,
+      reason: `authority identity cannot physically disappear: ${unit.id}`,
+      repair: unit.lifecycle === "removed"
+        ? "retain the removed tombstone; permanent reserved-ID storage is not admitted"
+        : "replace the active unit with a valid removed tombstone carrying an explicit reason",
+    }));
+  }
+  for (const entry of after.byId.values()) {
+    const { unit, unitIndex } = entry;
+    const previous = before.byId.get(unit.id)?.unit;
+    if (!previous) continue;
+    const mapped = sideMappedAt(after, unitIndex, "/id", "after");
+    if (previous.lifecycle === "removed" && unit.lifecycle !== "removed") diagnostics.push(makeDiagnostic({
+      code: "AUTH_DIFF_TRANSITION_INVALID",
+      file: mapped.file,
+      range: mapped.range,
+      pointer: mapped.sourcePointer,
+      reason: `removed identity cannot return to ${unit.lifecycle}: ${unit.id}`,
+      repair: "retain the removed identity and declare a new product-authorized ID",
+    }));
+    if (previous.kind !== unit.kind) diagnostics.push(makeDiagnostic({
+      code: "AUTH_DIFF_TRANSITION_INVALID",
+      file: mapped.file,
+      range: mapped.range,
+      pointer: mapped.sourcePointer,
+      reason: `authority identity cannot change kind from ${previous.kind} to ${unit.kind}: ${unit.id}`,
+      repair: "retain the original identity and declare a distinct ID for the new kind",
+    }));
+  }
+  return sortDiagnostics(diagnostics);
+}
+
+function compareUnits(before, after) {
+  const changes = [];
+  const ids = [...new Set([...before.byId.keys(), ...after.byId.keys()])].sort(compareText);
+  for (const id of ids) {
+    const left = before.byId.get(id);
+    const right = after.byId.get(id);
+    if (!left) {
+      addChange(changes, {
+        unitId: id,
+        operation: "unit_added",
+        pointer: "",
+        before: null,
+        after: right.unit,
+        afterSource: mappedAt(after, right.unitIndex, "/id"),
+      });
+      continue;
+    }
+    if (!right) continue;
+    for (const pointer of ["/kind", "/owner", "/lifecycle", "/metadata/title", "/metadata/reason", "/semantic/meaning", "/semantic/modality", "/semantic/statement", "/semantic/condition", "/semantic/failure"]) {
+      compareScalar(changes, before, after, left, right, pointer);
+    }
+    compareValueSet(changes, before, after, left, right, "/semantic/scope");
+    compareRelations(changes, before, after, left, right);
+  }
+  return changes.sort((left, right) => (
+    compareText(left.unitId, right.unitId)
+    || compareText(left.pointer, right.pointer)
+    || compareText(left.operation, right.operation)
+    || compareText(JSON.stringify(left.before), JSON.stringify(right.before))
+    || compareText(JSON.stringify(left.after), JSON.stringify(right.after))
+  ));
+}
+
+export function canonicalDiffBytes(diff) {
+  return Buffer.byteLength(JSON.stringify(diff), "utf8");
+}
+
+function budgetDiagnostic(requiredBytes, maxBytes) {
+  return makeDiagnostic({
+    code: "AUTH_DIFF_BUDGET",
+    file: ".",
+    range: { start: { line: 1, column: 1 }, end: { line: 1, column: 1 } },
+    pointer: "",
+    reason: `complete semantic diff requires ${requiredBytes} UTF-8 bytes but max-bytes is ${maxBytes}`,
+    repair: "increase the explicit byte budget; partial semantic diff is forbidden",
+  });
+}
+
+export async function diffAuthorityPathsWithSnapshots(beforePath, afterPath, { maxBytes = null } = {}) {
+  const [before, after, beforeBase, afterBase] = await Promise.all([
+    compileAuthorityPath(beforePath),
+    compileAuthorityPath(afterPath),
+    sourceRoot(beforePath),
+    sourceRoot(afterPath),
+  ]);
+  if (!before.ok || !after.ok) return {
+    beforeSnapshot: null,
+    afterSnapshot: null,
+    result: {
+      ok: false,
+      diagnostics: sortDiagnostics([
+        ...sideDiagnostics(before.diagnostics, beforeBase, "before"),
+        ...sideDiagnostics(after.diagnostics, afterBase, "after"),
+      ]),
+      fileCount: before.fileCount + after.fileCount,
+      unitCount: 0,
+      diff: null,
+      partial: false,
+    },
+  };
+  const beforeSnapshot = createCompiledAuthoritySnapshot(before, beforeBase);
+  const afterSnapshot = createCompiledAuthoritySnapshot(after, afterBase);
+  return {
+    beforeSnapshot,
+    afterSnapshot,
+    result: diffAuthoritySnapshots(beforeSnapshot, afterSnapshot, { maxBytes }),
+  };
+}
+
+export async function diffAuthorityPaths(beforePath, afterPath, options = {}) {
+  return (await diffAuthorityPathsWithSnapshots(beforePath, afterPath, options)).result;
+}
+
+export function diffAuthoritySnapshots(beforeSnapshot, afterSnapshot, { maxBytes = null } = {}) {
+  const before = beforeSnapshot.compiled;
+  const after = afterSnapshot.compiled;
+  const invalidTransitions = transitionDiagnostics(beforeSnapshot, afterSnapshot);
+  if (invalidTransitions.length > 0) return {
+    ok: false,
+    diagnostics: invalidTransitions,
+    fileCount: before.fileCount + after.fileCount,
+    unitCount: 0,
+    diff: null,
+    partial: false,
+  };
+  const changes = compareUnits(beforeSnapshot, afterSnapshot);
+  const diff = {
+    format: DIFF_FORMAT,
+    changes,
+    summary: {
+      units: new Set(changes.map((change) => change.unitId)).size,
+      changes: changes.length,
+    },
+  };
+  const payloadBytes = canonicalDiffBytes(diff);
+  if (maxBytes !== null && payloadBytes > maxBytes) return {
+    ok: false,
+    diagnostics: [budgetDiagnostic(payloadBytes, maxBytes)],
+    fileCount: before.fileCount + after.fileCount,
+    unitCount: 0,
+    payloadBytes,
+    diff: null,
+    partial: false,
+  };
+  return {
+    ok: true,
+    diagnostics: [],
+    fileCount: before.fileCount + after.fileCount,
+    unitCount: new Set([...beforeSnapshot.byId.keys(), ...afterSnapshot.byId.keys()]).size,
+    payloadBytes,
+    diff,
+    before,
+    after,
+    partial: false,
+  };
+}