@gmickel/gno 1.31.0 → 1.32.0

package/src/core/file-refactor-contract.ts

@@ -0,0 +1,486 @@
+/**
+ * Transport-neutral, versioned reference-safe rename/move contracts.
+ *
+ * Filesystem atomicity and post-commit index convergence are consecutive,
+ * separate states — never one shared transaction. Destination-only edit spans
+ * preserve aliases, labels, titles, fragments, queries, escaping, and encoding.
+ *
+ * @module src/core/file-refactor-contract
+ */
+
+export const FILE_REFACTOR_SCHEMA_VERSION = "1.0" as const;
+
+/** Exact apply confirmation token — never inferred from free text. */
+export const FILE_REFACTOR_APPLY_CONFIRMATION = "apply" as const;
+
+export type FileRefactorOperation = "rename" | "move";
+
+export type FileRefactorConflictPolicy = "fail";
+
+export type FileRefactorReferenceKind =
+  | "wiki"
+  | "markdown"
+  | "markdown_definition"
+  | "opaque";
+
+/**
+ * Per-reference classification from a conservative impact preview.
+ * Malformed is distinct from unsupported (recognized but unsafe to rewrite).
+ */
+export type FileRefactorReferenceClassification =
+  | "rewriteable"
+  | "unchanged"
+  | "ambiguous"
+  | "unsupported"
+  | "malformed"
+  | "invalid";
+
+/**
+ * Stable reason taxonomy for preview/apply diagnostics.
+ * Codes are closed; surfaces must not invent ad-hoc strings.
+ */
+export const FILE_REFACTOR_REASON_CODES = [
+  "ambiguous_resolution",
+  "unsupported_syntax",
+  "malformed_syntax",
+  "stale_plan",
+  "capability_denied",
+  "occupied_target",
+  "sync_pending",
+  "cross_collection_unsupported",
+  "unsafe_target",
+  "external_destination",
+  "code_fence_context",
+  "inline_code_context",
+  "html_context",
+  "duplicate_basename_ambiguity",
+  "unicode_normalization_mismatch",
+  "destination_unchanged",
+  "read_only_document",
+  "relative_path_recalculated",
+  "reference_definition_site",
+  "filesystem_commit_failed",
+  "rollback_recovery_required",
+] as const;
+
+export type FileRefactorReasonCode =
+  (typeof FILE_REFACTOR_REASON_CODES)[number];
+
+export type FileRefactorApplyStatus =
+  | "applied"
+  | "applied_with_sync_pending"
+  | "conflict"
+  | "stale_plan"
+  | "unsupported"
+  | "failed_rolled_back";
+
+export type FileRefactorFilesystemState =
+  | "committed"
+  | "rolled_back"
+  | "unchanged"
+  | "recovery_required";
+
+export type FileRefactorIndexConvergenceState =
+  | "converged"
+  | "pending"
+  | "not_attempted"
+  | "skipped";
+
+/**
+ * Minimal edit span: ONLY destination/path token content may change.
+ * Alias, Markdown label, title, fragment, query, escaping, and encoding
+ * outside this span must remain identical (UTF-16 code-unit slices).
+ */
+export interface FileRefactorDestinationSpan {
+  coordinateSpace: "utf16_code_units";
+  /** Inclusive start offset (UTF-16 code units) of destination token. */
+  startOffset: number;
+  /** Exclusive end offset (UTF-16 code units) of destination token. */
+  endOffset: number;
+  originalDestination: string;
+  replacementDestination: string;
+}
+
+export interface FileRefactorDocumentRef {
+  uri: string;
+  relPath: string;
+  collection: string;
+}
+
+export interface FileRefactorExaminedReference {
+  documentUri: string;
+  documentRelPath: string;
+  kind: FileRefactorReferenceKind;
+  classification: FileRefactorReferenceClassification;
+  reasonCode?: FileRefactorReasonCode;
+  /** Raw destination text before any rewrite (path portion only when known). */
+  originalDestination?: string;
+  proposedDestination?: string;
+  /** Present only when classification is rewriteable. */
+  edit?: FileRefactorDestinationSpan;
+  startLine?: number;
+  startCol?: number;
+  endLine?: number;
+  endCol?: number;
+}
+
+export interface FileRefactorAffectedDocument {
+  uri: string;
+  relPath: string;
+  /** SHA-256 hex of full document UTF-8 content at plan time. */
+  contentFingerprint: string;
+  edits: FileRefactorDestinationSpan[];
+  examined: FileRefactorExaminedReference[];
+}
+
+export interface FileRefactorPreconditions {
+  sourceContentFingerprint: string;
+  affectedContentFingerprints: Array<{
+    uri: string;
+    fingerprint: string;
+  }>;
+  /** Hex digest over the intended target path absence/occupancy check. */
+  targetPathFingerprint: string;
+}
+
+/**
+ * Explicit split between durable filesystem mutation and index refresh.
+ * Never claim one transaction spans both.
+ */
+export interface FileRefactorMutationBoundary {
+  filesystemCommit: "atomic_all_or_rollback";
+  indexConvergence: "post_commit_separate";
+  syncFailureDoesNotRollbackFilesystem: true;
+}
+
+export interface FileRefactorSafetySummary {
+  rewriteableCount: number;
+  unchangedCount: number;
+  ambiguousCount: number;
+  unsupportedCount: number;
+  malformedCount: number;
+  invalidCount: number;
+  blockingReasonCodes: FileRefactorReasonCode[];
+  warnings: string[];
+  backlinkCount: number;
+  wikiLinkCount: number;
+  markdownLinkCount: number;
+}
+
+export interface FileRefactorPreviewPlan {
+  schemaVersion: typeof FILE_REFACTOR_SCHEMA_VERSION;
+  operation: FileRefactorOperation;
+  conflictPolicy: FileRefactorConflictPolicy;
+  source: FileRefactorDocumentRef;
+  target: FileRefactorDocumentRef;
+  affectedDocuments: FileRefactorAffectedDocument[];
+  /** Deterministic ordered list of every examined reference (incl. opaque). */
+  examinedReferences: FileRefactorExaminedReference[];
+  preconditions: FileRefactorPreconditions;
+  planDigest: string;
+  safety: FileRefactorSafetySummary;
+  canApply: boolean;
+  mutationBoundary: FileRefactorMutationBoundary;
+}
+
+export interface FileRefactorApplyRequest {
+  schemaVersion: typeof FILE_REFACTOR_SCHEMA_VERSION;
+  planDigest: string;
+  confirmation: typeof FILE_REFACTOR_APPLY_CONFIRMATION;
+}
+
+interface FileRefactorApplyResultBase {
+  schemaVersion: typeof FILE_REFACTOR_SCHEMA_VERSION;
+  planDigest: string;
+  operation: FileRefactorOperation;
+  source: FileRefactorDocumentRef;
+  target: FileRefactorDocumentRef;
+}
+
+/** Content-free filesystem receipt — never embeds note bodies. */
+export type FileRefactorApplyResult =
+  | (FileRefactorApplyResultBase & {
+      status: "applied";
+      filesystem: { state: "committed"; recoveryJournalId?: string };
+      indexConvergence: { state: "converged" };
+    })
+  | (FileRefactorApplyResultBase & {
+      status: "applied_with_sync_pending";
+      reasonCode: "sync_pending";
+      filesystem: { state: "committed"; recoveryJournalId?: string };
+      indexConvergence: {
+        state: "pending";
+        recoveryInstruction: string;
+      };
+    })
+  | (FileRefactorApplyResultBase & {
+      status: "conflict" | "stale_plan" | "unsupported";
+      reasonCode: FileRefactorReasonCode;
+      filesystem: { state: "unchanged"; recoveryJournalId?: string };
+      indexConvergence: { state: "not_attempted" | "skipped" };
+    })
+  | (FileRefactorApplyResultBase & {
+      status: "failed_rolled_back";
+      reasonCode: FileRefactorReasonCode;
+      filesystem: {
+        state: "rolled_back" | "recovery_required";
+        recoveryJournalId?: string;
+      };
+      indexConvergence: { state: "not_attempted" | "skipped" };
+    });
+
+export const FILE_REFACTOR_MUTATION_BOUNDARY: FileRefactorMutationBoundary = {
+  filesystemCommit: "atomic_all_or_rollback",
+  indexConvergence: "post_commit_separate",
+  syncFailureDoesNotRollbackFilesystem: true,
+};
+
+const UTF8 = new TextEncoder();
+
+/** SHA-256 hex fingerprint via Web Crypto (browser- and Bun-safe). */
+export async function fingerprintUtf8Content(content: string): Promise<string> {
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", UTF8.encode(content))
+  );
+  return [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Ordinal UTF-16 code-unit comparison — locale/ICU/OS independent.
+ * Uses `<`/`>` on JS strings (16-bit code units), not localeCompare.
+ */
+export function compareUtf16CodeUnits(left: string, right: string): number {
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+/**
+ * Canonical serializer matching JSON transport semantics with sorted keys.
+ * - Object keys with `undefined` values are omitted (like JSON.stringify).
+ * - Array holes / `undefined` items serialize as `null`.
+ * - Non-finite numbers, bigint, symbol, and function values are rejected.
+ */
+export function stableStringify(value: unknown): string {
+  if (value === undefined) {
+    throw new Error("stableStringify cannot serialize top-level undefined");
+  }
+  if (value === null) return "null";
+  const valueType = typeof value;
+  if (valueType === "boolean" || valueType === "string") {
+    return JSON.stringify(value);
+  }
+  if (valueType === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error("stableStringify rejects non-finite numbers");
+    }
+    return JSON.stringify(value);
+  }
+  if (
+    valueType === "bigint" ||
+    valueType === "symbol" ||
+    valueType === "function"
+  ) {
+    throw new Error(`stableStringify rejects unsupported type: ${valueType}`);
+  }
+  if (valueType !== "object") {
+    throw new Error(`stableStringify rejects unsupported type: ${valueType}`);
+  }
+  if (Array.isArray(value)) {
+    return `[${value
+      .map((item) => (item === undefined ? "null" : stableStringify(item)))
+      .join(",")}]`;
+  }
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).sort(compareUtf16CodeUnits);
+  const parts: string[] = [];
+  for (const key of keys) {
+    const entry = record[key];
+    if (entry === undefined) continue;
+    parts.push(`${JSON.stringify(key)}:${stableStringify(entry)}`);
+  }
+  return `{${parts.join(",")}}`;
+}
+
+/**
+ * Deterministic plan digest over material preview fields (excludes planDigest).
+ * Ordering of examined references and affected documents must already be stable.
+ */
+export async function computeFileRefactorPlanDigest(
+  plan: Omit<FileRefactorPreviewPlan, "planDigest">
+): Promise<string> {
+  return fingerprintUtf8Content(
+    stableStringify({
+      schemaVersion: plan.schemaVersion,
+      operation: plan.operation,
+      conflictPolicy: plan.conflictPolicy,
+      source: plan.source,
+      target: plan.target,
+      affectedDocuments: plan.affectedDocuments,
+      examinedReferences: plan.examinedReferences,
+      preconditions: plan.preconditions,
+      safety: plan.safety,
+      canApply: plan.canApply,
+      mutationBoundary: plan.mutationBoundary,
+    })
+  );
+}
+
+/** Compare references for deterministic plan ordering. */
+export function compareExaminedReferences(
+  left: FileRefactorExaminedReference,
+  right: FileRefactorExaminedReference
+): number {
+  const byDoc = compareUtf16CodeUnits(
+    left.documentRelPath,
+    right.documentRelPath
+  );
+  if (byDoc !== 0) return byDoc;
+  const leftLine = left.startLine ?? 0;
+  const rightLine = right.startLine ?? 0;
+  if (leftLine !== rightLine) return leftLine - rightLine;
+  const leftCol = left.startCol ?? 0;
+  const rightCol = right.startCol ?? 0;
+  if (leftCol !== rightCol) return leftCol - rightCol;
+  return compareUtf16CodeUnits(
+    left.originalDestination ?? "",
+    right.originalDestination ?? ""
+  );
+}
+
+export function sortExaminedReferences(
+  references: FileRefactorExaminedReference[]
+): FileRefactorExaminedReference[] {
+  return [...references].sort(compareExaminedReferences);
+}
+
+/**
+ * Apply a destination-only span. Throws when the live slice does not match
+ * originalDestination (stale span / wrong coordinate space).
+ */
+export function applyDestinationOnlyEdit(
+  content: string,
+  span: FileRefactorDestinationSpan
+): string {
+  if (span.coordinateSpace !== "utf16_code_units") {
+    throw new Error("Unsupported coordinate space for destination edit");
+  }
+  if (span.endOffset < span.startOffset) {
+    throw new Error("Invalid destination span offsets");
+  }
+  const actual = content.slice(span.startOffset, span.endOffset);
+  if (actual !== span.originalDestination) {
+    throw new Error(
+      "Destination span does not match originalDestination (stale or misaligned)"
+    );
+  }
+  return (
+    content.slice(0, span.startOffset) +
+    span.replacementDestination +
+    content.slice(span.endOffset)
+  );
+}
+
+/**
+ * True when every UTF-16 code unit outside the destination span is unchanged.
+ * Full-document UTF-8 fingerprints prove content changed; this proves only the
+ * destination token content changed.
+ */
+export function isContentPreservedOutsideSpan(
+  before: string,
+  after: string,
+  span: FileRefactorDestinationSpan
+): boolean {
+  const prefix = before.slice(0, span.startOffset);
+  const suffix = before.slice(span.endOffset);
+  const expected = prefix + span.replacementDestination + suffix;
+  if (after !== expected) {
+    return false;
+  }
+  return (
+    after.slice(0, span.startOffset) === prefix &&
+    after.slice(span.startOffset + span.replacementDestination.length) ===
+      suffix
+  );
+}
+
+/**
+ * @deprecated Prefer {@link isContentPreservedOutsideSpan}. Alias retained for
+ * import stability; compares UTF-16 code-unit slices, not UTF-8 bytes.
+ */
+export const isBytePreservedOutsideSpan = isContentPreservedOutsideSpan;
+
+export function summarizeReferenceClassifications(
+  references: FileRefactorExaminedReference[],
+  warningSnapshot: {
+    warnings?: string[];
+    backlinks?: number;
+    wikiLinks?: number;
+    markdownLinks?: number;
+  } = {}
+): FileRefactorSafetySummary {
+  const counts = {
+    rewriteableCount: 0,
+    unchangedCount: 0,
+    ambiguousCount: 0,
+    unsupportedCount: 0,
+    malformedCount: 0,
+    invalidCount: 0,
+  };
+  const blocking = new Set<FileRefactorReasonCode>();
+
+  for (const reference of references) {
+    switch (reference.classification) {
+      case "rewriteable":
+        counts.rewriteableCount += 1;
+        break;
+      case "unchanged":
+        counts.unchangedCount += 1;
+        break;
+      case "ambiguous":
+        counts.ambiguousCount += 1;
+        if (reference.reasonCode) blocking.add(reference.reasonCode);
+        else blocking.add("ambiguous_resolution");
+        break;
+      case "unsupported":
+        counts.unsupportedCount += 1;
+        if (reference.reasonCode) blocking.add(reference.reasonCode);
+        else blocking.add("unsupported_syntax");
+        break;
+      case "malformed":
+        counts.malformedCount += 1;
+        if (reference.reasonCode) blocking.add(reference.reasonCode);
+        else blocking.add("malformed_syntax");
+        break;
+      case "invalid":
+        counts.invalidCount += 1;
+        if (reference.reasonCode) blocking.add(reference.reasonCode);
+        break;
+    }
+  }
+
+  return {
+    ...counts,
+    blockingReasonCodes: [...blocking].sort(compareUtf16CodeUnits),
+    warnings: warningSnapshot.warnings ?? [],
+    backlinkCount: warningSnapshot.backlinks ?? 0,
+    wikiLinkCount: warningSnapshot.wikiLinks ?? 0,
+    markdownLinkCount: warningSnapshot.markdownLinks ?? 0,
+  };
+}
+
+export function deriveCanApply(input: {
+  safety: FileRefactorSafetySummary;
+  sourceEditable: boolean;
+  targetOccupied: boolean;
+  sameCollection: boolean;
+}): boolean {
+  if (!input.sourceEditable) return false;
+  if (!input.sameCollection) return false;
+  if (input.targetOccupied) return false;
+  if (input.safety.blockingReasonCodes.length > 0) return false;
+  if (input.safety.ambiguousCount > 0) return false;
+  if (input.safety.unsupportedCount > 0) return false;
+  if (input.safety.malformedCount > 0) return false;
+  if (input.safety.invalidCount > 0) return false;
+  return true;
+}

package/src/core/file-refactor-destination.ts

@@ -0,0 +1,123 @@
+/**
+ * Destination token recomputation for wiki / markdown reference rewrites.
+ *
+ * @module src/core/file-refactor-destination
+ */
+
+// node:path/posix — no Bun path utils
+import { posix as pathPosix } from "node:path";
+
+import type { LinkInventoryToken } from "./link-inventory-types";
+
+import {
+  applyDestinationEncodingStyle,
+  stripAngleBracketDestination,
+  unescapeCommonMarkDestination,
+} from "./link-destination-parse";
+import { stripWikiMdExt } from "./links";
+
+function preserveDotSlash(original: string, nextRelative: string): string {
+  if (!original.startsWith("./")) return nextRelative;
+  if (nextRelative.startsWith("../") || nextRelative.startsWith("./")) {
+    return nextRelative;
+  }
+  return `./${nextRelative}`;
+}
+
+/**
+ * Compute a wiki destination token for the new target identity, preserving
+ * basename-vs-path and optional `.md` extension style when safely possible.
+ */
+export function computeWikiReplacementDestination(input: {
+  originalDestination: string;
+  sourceRelPath: string;
+  sourceTitle: string | null | undefined;
+  targetRelPath: string;
+  targetTitle?: string | null;
+}): string {
+  const original = input.originalDestination;
+  const hadMd = original.toLowerCase().endsWith(".md");
+  const originalBase = stripWikiMdExt(pathPosix.basename(original));
+  const sourceBase = stripWikiMdExt(pathPosix.basename(input.sourceRelPath));
+  const targetBase = stripWikiMdExt(pathPosix.basename(input.targetRelPath));
+  const targetTitle =
+    input.targetTitle?.trim() ||
+    pathPosix.basename(
+      input.targetRelPath,
+      pathPosix.extname(input.targetRelPath)
+    );
+
+  const looksLikePath =
+    original.includes("/") ||
+    original.toLowerCase() === input.sourceRelPath.toLowerCase() ||
+    stripWikiMdExt(original).toLowerCase() ===
+      stripWikiMdExt(input.sourceRelPath).toLowerCase();
+
+  if (looksLikePath) {
+    let next = input.targetRelPath;
+    if (!hadMd) {
+      next = stripWikiMdExt(next);
+    }
+    if (!original.includes("/") && pathPosix.basename(original) === original) {
+      next = hadMd ? `${targetBase}.md` : targetBase;
+    }
+    return next;
+  }
+
+  const sourceTitle = input.sourceTitle?.trim() ?? sourceBase;
+  if (
+    originalBase.toLowerCase() === sourceTitle.toLowerCase() ||
+    originalBase.toLowerCase() === sourceBase.toLowerCase()
+  ) {
+    const next = targetTitle;
+    return hadMd ? `${next}.md` : next;
+  }
+
+  return hadMd ? `${targetBase}.md` : targetBase;
+}
+
+/**
+ * Recompute a markdown (or reference-definition) relative destination from the
+ * referring document directory to the new target path, preserving escape style.
+ */
+export function computeMarkdownReplacementDestination(input: {
+  token: Pick<
+    LinkInventoryToken,
+    "originalDestination" | "hadLeadingDotSlash" | "encodingStyle"
+  >;
+  referringRelPath: string;
+  targetRelPath: string;
+}): string {
+  const referringDir = pathPosix.dirname(input.referringRelPath);
+  let relative = pathPosix.relative(referringDir, input.targetRelPath);
+  if (!relative || relative === "") {
+    relative = pathPosix.basename(input.targetRelPath);
+  }
+  const originalForDot = stripAngleBracketDestination(
+    unescapeCommonMarkDestination(input.token.originalDestination)
+  ).path;
+  if (
+    input.token.hadLeadingDotSlash ||
+    originalForDot.startsWith("./") ||
+    input.token.originalDestination.startsWith("./")
+  ) {
+    relative = preserveDotSlash(
+      originalForDot.startsWith("./")
+        ? originalForDot
+        : input.token.originalDestination,
+      relative
+    );
+  }
+  return applyDestinationEncodingStyle(relative, input.token.encodingStyle);
+}
+
+/**
+ * After computing a wiki replacement, decide whether leaving the destination
+ * unchanged is acceptable because the original still uniquely names the target.
+ */
+export function wikiDestinationUnchangedAcceptable(input: {
+  originalDestination: string;
+  replacementDestination: string;
+}): boolean {
+  return input.originalDestination === input.replacementDestination;
+}