@gmickel/gno 1.31.0 → 1.32.0

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

@@ -0,0 +1,423 @@
+/**
+ * Pure parser-backed reference impact planner for rename / same-collection move.
+ *
+ * Accepts a bounded document snapshot; never reads or writes user files.
+ *
+ * @module src/core/file-refactor-planner
+ */
+
+import type {
+  FileRefactorAffectedDocument,
+  FileRefactorDestinationSpan,
+  FileRefactorExaminedReference,
+  FileRefactorPreviewPlan,
+} from "./file-refactor-contract";
+import type {
+  FileRefactorPlannerDocument,
+  PlanFileRefactorImpactInput,
+} from "./file-refactor-planner-types";
+import type { FileRefactorCatalogDocument } from "./file-refactor-resolve";
+
+import {
+  FILE_REFACTOR_MUTATION_BOUNDARY,
+  FILE_REFACTOR_SCHEMA_VERSION,
+  computeFileRefactorPlanDigest,
+  deriveCanApply,
+  fingerprintUtf8Content,
+  sortExaminedReferences,
+  summarizeReferenceClassifications,
+} from "./file-refactor-contract";
+import { classifyResolvableToken } from "./file-refactor-plan-classify";
+import {
+  pathBasename,
+  pathDirname,
+  validateFileRefactorPlanInputs,
+} from "./file-refactor-plan-validate";
+import { FILE_REFACTOR_PLANNER_CAPS } from "./file-refactor-planner-types";
+import {
+  buildSourceRelevanceKeys,
+  inventoryDocumentLinks,
+} from "./link-inventory";
+
+export {
+  FILE_REFACTOR_PLANNER_CAPS,
+  type FileRefactorPlannerDocument,
+  type PlanFileRefactorImpactInput,
+} from "./file-refactor-planner-types";
+
+function toCatalog(
+  documents: FileRefactorPlannerDocument[]
+): FileRefactorCatalogDocument[] {
+  return documents.map((doc) => ({
+    id: doc.id,
+    uri: doc.uri,
+    relPath: doc.relPath,
+    collection: doc.collection,
+    title: doc.title,
+    active: doc.active,
+  }));
+}
+
+async function emptyBlockedPlan(
+  input: PlanFileRefactorImpactInput,
+  examined: FileRefactorExaminedReference[],
+  warnings: string[]
+): Promise<FileRefactorPreviewPlan> {
+  const orderedExamined = sortExaminedReferences(examined);
+  const safety = summarizeReferenceClassifications(orderedExamined, {
+    warnings,
+    backlinks: orderedExamined.length,
+  });
+  const sourceContentFingerprint = await fingerprintUtf8Content(
+    input.source.content
+  );
+  const targetPathFingerprint = await fingerprintUtf8Content(
+    input.targetPathFingerprintSeed ??
+      `${input.target.collection}:${input.target.relPath}:${input.targetOccupied ? "occupied" : "free"}`
+  );
+  const withoutDigest: Omit<FileRefactorPreviewPlan, "planDigest"> = {
+    schemaVersion: FILE_REFACTOR_SCHEMA_VERSION,
+    operation: input.operation,
+    conflictPolicy: "fail",
+    source: {
+      uri: input.source.uri,
+      relPath: input.source.relPath,
+      collection: input.source.collection,
+    },
+    target: {
+      uri: input.target.uri,
+      relPath: input.target.relPath,
+      collection: input.target.collection,
+    },
+    affectedDocuments: [],
+    examinedReferences: orderedExamined,
+    preconditions: {
+      sourceContentFingerprint,
+      affectedContentFingerprints: [],
+      targetPathFingerprint,
+    },
+    safety,
+    canApply: false,
+    mutationBoundary: FILE_REFACTOR_MUTATION_BOUNDARY,
+  };
+  const planDigest = await computeFileRefactorPlanDigest(withoutDigest);
+  return { ...withoutDigest, planDigest };
+}
+
+/**
+ * Build a deterministic FileRefactorPreviewPlan from an in-memory snapshot.
+ */
+export async function planFileRefactorImpact(
+  input: PlanFileRefactorImpactInput
+): Promise<FileRefactorPreviewPlan> {
+  const validation = validateFileRefactorPlanInputs(input);
+  if (validation) {
+    return emptyBlockedPlan(input, validation.examined, [
+      `plan_invalid:${validation.diagnostic}`,
+    ]);
+  }
+
+  const truncatedReasons = [...new Set(input.truncationReasons ?? [])].sort();
+  const catalogDocs = input.documents;
+
+  if (catalogDocs.length > FILE_REFACTOR_PLANNER_CAPS.maxCatalogDocuments) {
+    truncatedReasons.push("catalog_truncated");
+  }
+  // Inventory + resolution must operate on the bounded catalog slice only.
+  const boundedCatalogDocs = catalogDocs.slice(
+    0,
+    FILE_REFACTOR_PLANNER_CAPS.maxCatalogDocuments
+  );
+  const catalog = toCatalog(boundedCatalogDocs);
+
+  const sourceKeys = buildSourceRelevanceKeys({
+    relPath: input.source.relPath,
+    title: input.source.title,
+  });
+
+  // Inventory source content for self-references, plus every content-bearing
+  // same-collection document (including docs whose only hit is opaque syntax).
+  const contentDocs: FileRefactorPlannerDocument[] = [];
+  const seenContentUris = new Set<string>();
+
+  const pushContentDoc = (doc: FileRefactorPlannerDocument): boolean => {
+    if (seenContentUris.has(doc.uri)) return true;
+    if (doc.collection !== input.source.collection) return true;
+    if (contentDocs.length >= FILE_REFACTOR_PLANNER_CAPS.maxContentDocuments) {
+      truncatedReasons.push("content_documents_truncated");
+      return false;
+    }
+    seenContentUris.add(doc.uri);
+    contentDocs.push(doc);
+    return true;
+  };
+
+  pushContentDoc({
+    id: -1,
+    uri: input.source.uri,
+    relPath: input.source.relPath,
+    collection: input.source.collection,
+    title: input.source.title ?? null,
+    content: input.source.content,
+    editable: input.source.editable,
+  });
+
+  for (const doc of boundedCatalogDocs) {
+    if (doc.contentMissing) {
+      truncatedReasons.push("referrer_content_missing");
+      if (!pushContentDoc(doc)) break;
+      continue;
+    }
+    if (doc.content === undefined || doc.content === null) continue;
+    if (!pushContentDoc(doc)) break;
+  }
+
+  let totalContentChars = 0;
+  const examined: FileRefactorExaminedReference[] = [];
+  const byDocument = new Map<
+    string,
+    {
+      doc: FileRefactorPlannerDocument;
+      examined: FileRefactorExaminedReference[];
+      edits: FileRefactorDestinationSpan[];
+    }
+  >();
+
+  const considerDoc = (
+    doc: FileRefactorPlannerDocument,
+    content: string
+  ): void => {
+    if (doc.contentMissing) {
+      if (examined.length >= FILE_REFACTOR_PLANNER_CAPS.maxExaminedReferences) {
+        truncatedReasons.push("examined_truncated");
+        return;
+      }
+      examined.push({
+        documentUri: doc.uri,
+        documentRelPath: doc.relPath,
+        kind: "opaque",
+        classification: "invalid",
+        reasonCode: "unsafe_target",
+        originalDestination: "referrer_content_missing",
+      });
+      return;
+    }
+    if (
+      content.length > FILE_REFACTOR_PLANNER_CAPS.maxContentCharsPerDocument
+    ) {
+      truncatedReasons.push("content_size_truncated");
+      examined.push({
+        documentUri: doc.uri,
+        documentRelPath: doc.relPath,
+        kind: "opaque",
+        classification: "invalid",
+        reasonCode: "unsafe_target",
+      });
+      return;
+    }
+    totalContentChars += content.length;
+    if (totalContentChars > FILE_REFACTOR_PLANNER_CAPS.maxTotalContentChars) {
+      truncatedReasons.push("total_content_truncated");
+      examined.push({
+        documentUri: doc.uri,
+        documentRelPath: doc.relPath,
+        kind: "opaque",
+        classification: "invalid",
+        reasonCode: "unsafe_target",
+        originalDestination: "total_content_truncated",
+      });
+      return;
+    }
+
+    const inventory = inventoryDocumentLinks(content, { sourceKeys });
+    if (inventory.truncated) {
+      truncatedReasons.push("inventory_truncated");
+      examined.push({
+        documentUri: doc.uri,
+        documentRelPath: doc.relPath,
+        kind: "opaque",
+        classification: "invalid",
+        reasonCode: "unsafe_target",
+      });
+    }
+    if (inventory.overlapping) {
+      truncatedReasons.push("overlapping_destination_spans");
+      examined.push({
+        documentUri: doc.uri,
+        documentRelPath: doc.relPath,
+        kind: "opaque",
+        classification: "invalid",
+        reasonCode: "unsafe_target",
+        originalDestination: "overlapping_destination_spans",
+      });
+    }
+
+    for (const token of inventory.tokens) {
+      const row = classifyResolvableToken({
+        token,
+        doc,
+        sourceUri: input.source.uri,
+        sourceRelPath: input.source.relPath,
+        sourceTitle: input.source.title,
+        targetRelPath: input.target.relPath,
+        targetTitle: input.target.title,
+        catalog,
+      });
+      if (!row) continue;
+      if (examined.length >= FILE_REFACTOR_PLANNER_CAPS.maxExaminedReferences) {
+        truncatedReasons.push("examined_truncated");
+        break;
+      }
+      examined.push(row);
+      let bucket = byDocument.get(doc.uri);
+      if (!bucket) {
+        bucket = { doc, examined: [], edits: [] };
+        byDocument.set(doc.uri, bucket);
+      }
+      bucket.examined.push(row);
+      if (row.edit) bucket.edits.push(row.edit);
+    }
+  };
+
+  for (const doc of contentDocs) {
+    if (truncatedReasons.includes("examined_truncated")) break;
+    if (truncatedReasons.includes("total_content_truncated")) break;
+    considerDoc(doc, doc.content ?? "");
+  }
+
+  const uniqueTruncation = [...new Set(truncatedReasons)].sort();
+  const orderedExamined = sortExaminedReferences(examined);
+  const affectedDocuments: FileRefactorAffectedDocument[] = [];
+  const fingerprintEntries: Array<{ uri: string; fingerprint: string }> = [];
+
+  const sourceContentFingerprint = await fingerprintUtf8Content(
+    input.source.content
+  );
+
+  const orderedBuckets = [...byDocument.values()].sort((a, b) =>
+    a.doc.relPath < b.doc.relPath ? -1 : a.doc.relPath > b.doc.relPath ? 1 : 0
+  );
+
+  for (const bucket of orderedBuckets) {
+    const hasRewrite = bucket.edits.length > 0;
+    const hasBlocking = bucket.examined.some(
+      (row) =>
+        row.classification === "ambiguous" ||
+        row.classification === "unsupported" ||
+        row.classification === "malformed" ||
+        row.classification === "invalid"
+    );
+    if (!hasRewrite && !hasBlocking && bucket.examined.length === 0) continue;
+
+    // Source uses the canonical fingerprint from input.source.content once.
+    const contentFingerprint =
+      bucket.doc.uri === input.source.uri
+        ? sourceContentFingerprint
+        : await fingerprintUtf8Content(bucket.doc.content ?? "");
+    fingerprintEntries.push({
+      uri: bucket.doc.uri,
+      fingerprint: contentFingerprint,
+    });
+    affectedDocuments.push({
+      uri: bucket.doc.uri,
+      relPath: bucket.doc.relPath,
+      contentFingerprint,
+      edits: [...bucket.edits].sort((a, b) =>
+        a.startOffset !== b.startOffset
+          ? a.startOffset - b.startOffset
+          : a.endOffset - b.endOffset
+      ),
+      examined: sortExaminedReferences(bucket.examined),
+    });
+  }
+
+  const wikiLinkCount = orderedExamined.filter(
+    (row) => row.kind === "wiki"
+  ).length;
+  const markdownLinkCount = orderedExamined.filter(
+    (row) => row.kind === "markdown" || row.kind === "markdown_definition"
+  ).length;
+  const filenameChanged =
+    pathBasename(input.source.relPath) !== pathBasename(input.target.relPath);
+  const folderChanged =
+    pathDirname(input.source.relPath) !== pathDirname(input.target.relPath);
+  const warnings: string[] = [];
+  if (orderedExamined.length > 0) {
+    warnings.push(
+      `${orderedExamined.length} backlink${orderedExamined.length === 1 ? "" : "s"} may need review after this refactor.`
+    );
+  }
+  if (filenameChanged && wikiLinkCount > 0) {
+    warnings.push(
+      `${wikiLinkCount} wiki link${wikiLinkCount === 1 ? "" : "s"} may depend on the current title/path identity.`
+    );
+  }
+  if ((filenameChanged || folderChanged) && markdownLinkCount > 0) {
+    warnings.push(
+      `${markdownLinkCount} markdown link${markdownLinkCount === 1 ? "" : "s"} may require path rewrite or manual review.`
+    );
+  }
+  for (const code of uniqueTruncation) {
+    warnings.push(`plan_truncated:${code}`);
+  }
+
+  const safety = summarizeReferenceClassifications(orderedExamined, {
+    warnings,
+    backlinks: orderedExamined.length,
+    wikiLinks: wikiLinkCount,
+    markdownLinks: markdownLinkCount,
+  });
+
+  if (uniqueTruncation.length > 0 && safety.invalidCount === 0) {
+    safety.invalidCount = 1;
+    if (!safety.blockingReasonCodes.includes("unsafe_target")) {
+      safety.blockingReasonCodes = [
+        ...safety.blockingReasonCodes,
+        "unsafe_target" as const,
+      ].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+    }
+  }
+
+  const targetPathFingerprint = await fingerprintUtf8Content(
+    input.targetPathFingerprintSeed ??
+      `${input.target.collection}:${input.target.relPath}:${input.targetOccupied ? "occupied" : "free"}`
+  );
+
+  const canApply = deriveCanApply({
+    safety,
+    sourceEditable: input.source.editable,
+    targetOccupied: input.targetOccupied,
+    sameCollection: true,
+  });
+
+  const withoutDigest: Omit<FileRefactorPreviewPlan, "planDigest"> = {
+    schemaVersion: FILE_REFACTOR_SCHEMA_VERSION,
+    operation: input.operation,
+    conflictPolicy: "fail",
+    source: {
+      uri: input.source.uri,
+      relPath: input.source.relPath,
+      collection: input.source.collection,
+    },
+    target: {
+      uri: input.target.uri,
+      relPath: input.target.relPath,
+      collection: input.target.collection,
+    },
+    affectedDocuments,
+    examinedReferences: orderedExamined,
+    preconditions: {
+      sourceContentFingerprint,
+      affectedContentFingerprints: fingerprintEntries.sort((a, b) =>
+        a.uri < b.uri ? -1 : a.uri > b.uri ? 1 : 0
+      ),
+      targetPathFingerprint,
+    },
+    safety,
+    canApply,
+    mutationBoundary: FILE_REFACTOR_MUTATION_BOUNDARY,
+  };
+
+  const planDigest = await computeFileRefactorPlanDigest(withoutDigest);
+  return { ...withoutDigest, planDigest };
+}

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

@@ -0,0 +1,280 @@
+/**
+ * In-memory wiki/markdown target resolution for reference-safe refactors.
+ *
+ * Mirrors SqliteAdapter / graph-link-resolver ranking and uniqueness rules:
+ * best-rank candidate sets with more than one document are ambiguous.
+ *
+ * Catalog is already bounded (≤5000). Candidate collection never silently
+ * truncates mid-scan — the full bounded catalog is evaluated.
+ *
+ * @module src/core/file-refactor-resolve
+ */
+
+// node:path/posix — no Bun path utils
+import { posix as pathPosix } from "node:path";
+
+import type { FileRefactorReasonCode } from "./file-refactor-contract";
+
+import {
+  stripAngleBracketDestination,
+  unescapeCommonMarkDestination,
+} from "./link-destination-parse";
+import {
+  normalizeMarkdownPath,
+  normalizeWikiName,
+  stripWikiMdExt,
+} from "./links";
+
+export const FILE_REFACTOR_RESOLVE_CAPS = {
+  maxCatalogDocuments: 5_000,
+} as const;
+
+export interface FileRefactorCatalogDocument {
+  /** Stable numeric id for deterministic tie-breaks (matches documents.id). */
+  id: number;
+  uri: string;
+  relPath: string;
+  collection: string;
+  title: string | null;
+  active?: boolean;
+}
+
+export type FileRefactorResolutionStatus =
+  | "unique"
+  | "ambiguous"
+  | "unresolved"
+  | "elsewhere";
+
+export interface FileRefactorResolution {
+  status: FileRefactorResolutionStatus;
+  /** Present when status is unique and matches the expected source. */
+  document?: FileRefactorCatalogDocument;
+  matchRank?: number;
+  matchCount: number;
+  reasonCode?: FileRefactorReasonCode;
+  candidates: FileRefactorCatalogDocument[];
+}
+
+function lowerTrim(value: string): string {
+  return value.toLowerCase().trim();
+}
+
+function endsWithPathSegment(target: string, value: string): boolean {
+  if (!value) return false;
+  if (target === value) return true;
+  return target.endsWith(`/${value}`);
+}
+
+function wikiMatchRank(
+  targetRefNorm: string,
+  doc: FileRefactorCatalogDocument
+): number | null {
+  const baseRef = stripWikiMdExt(targetRefNorm);
+  const baseRefMd = `${baseRef}.md`;
+  const title = lowerTrim(doc.title ?? "");
+  const rel = doc.relPath.toLowerCase();
+
+  if (title === baseRef) return 1;
+  if (title === baseRefMd) return 2;
+  if (endsWithPathSegment(baseRef, title)) return 3;
+  if (endsWithPathSegment(baseRefMd, `${title}.md`)) return 4;
+  if (rel === baseRef) return 5;
+  if (rel === baseRefMd) return 6;
+  if (endsWithPathSegment(rel, baseRefMd)) return 7;
+  if (endsWithPathSegment(rel, baseRef)) return 8;
+  if (endsWithPathSegment(baseRefMd, rel)) return 9;
+  if (endsWithPathSegment(baseRef, rel)) return 10;
+  return null;
+}
+
+function collectWikiCandidates(
+  targetRefNorm: string,
+  collection: string,
+  catalog: readonly FileRefactorCatalogDocument[]
+): Array<{ doc: FileRefactorCatalogDocument; rank: number }> {
+  const matches: Array<{ doc: FileRefactorCatalogDocument; rank: number }> = [];
+  for (const doc of catalog) {
+    if (doc.active === false) continue;
+    if (doc.collection !== collection) continue;
+    const rank = wikiMatchRank(targetRefNorm, doc);
+    if (rank === null) continue;
+    matches.push({ doc, rank });
+  }
+  return matches;
+}
+
+function detectUnicodeAmbiguity(
+  targetRefNorm: string,
+  collection: string,
+  catalog: readonly FileRefactorCatalogDocument[],
+  best: FileRefactorCatalogDocument[]
+): boolean {
+  const nfcKey = normalizeWikiName(stripWikiMdExt(targetRefNorm));
+  if (!nfcKey) return false;
+  const nfcMatches: FileRefactorCatalogDocument[] = [];
+  for (const doc of catalog) {
+    if (doc.active === false) continue;
+    if (doc.collection !== collection) continue;
+    const titleKey = normalizeWikiName(doc.title ?? "");
+    const relKey = normalizeWikiName(stripWikiMdExt(doc.relPath));
+    const baseKey = normalizeWikiName(
+      stripWikiMdExt(pathPosix.basename(doc.relPath))
+    );
+    if (titleKey === nfcKey || relKey === nfcKey || baseKey === nfcKey) {
+      nfcMatches.push(doc);
+    }
+  }
+  if (nfcMatches.length <= 1) return false;
+  const bestIds = new Set(best.map((doc) => doc.id));
+  return nfcMatches.some((doc) => !bestIds.has(doc.id));
+}
+
+/**
+ * Resolve a wiki target against a bounded catalog. Never picks the first
+ * candidate and calls it unique when the best-rank set has multiple docs.
+ */
+export function resolveWikiTarget(input: {
+  targetRef: string;
+  targetCollection: string;
+  sourceUri: string;
+  catalog: readonly FileRefactorCatalogDocument[];
+}): FileRefactorResolution {
+  const targetRefNorm = normalizeWikiName(input.targetRef);
+  const matches = collectWikiCandidates(
+    targetRefNorm,
+    input.targetCollection,
+    input.catalog
+  );
+
+  if (matches.length === 0) {
+    return { status: "unresolved", matchCount: 0, candidates: [] };
+  }
+
+  let bestRank = Number.POSITIVE_INFINITY;
+  for (const match of matches) {
+    if (match.rank < bestRank) bestRank = match.rank;
+  }
+  const best = matches
+    .filter((match) => match.rank === bestRank)
+    .map((match) => match.doc)
+    .sort((a, b) => a.id - b.id);
+
+  const includesSource = best.some((doc) => doc.uri === input.sourceUri);
+  const duplicateBasenames = new Set(
+    best.map((doc) =>
+      normalizeWikiName(stripWikiMdExt(pathPosix.basename(doc.relPath)))
+    )
+  );
+
+  if (best.length > 1) {
+    const reasonCode: FileRefactorReasonCode =
+      duplicateBasenames.size < best.length || best.length > 1
+        ? "duplicate_basename_ambiguity"
+        : "ambiguous_resolution";
+    return {
+      status: "ambiguous",
+      matchRank: bestRank,
+      matchCount: best.length,
+      reasonCode: includesSource ? reasonCode : "ambiguous_resolution",
+      candidates: best,
+    };
+  }
+
+  if (
+    detectUnicodeAmbiguity(
+      targetRefNorm,
+      input.targetCollection,
+      input.catalog,
+      best
+    )
+  ) {
+    return {
+      status: "ambiguous",
+      matchRank: bestRank,
+      matchCount: best.length + 1,
+      reasonCode: "unicode_normalization_mismatch",
+      candidates: best,
+    };
+  }
+
+  const unique = best[0];
+  if (!unique) {
+    return { status: "unresolved", matchCount: 0, candidates: [] };
+  }
+  if (unique.uri !== input.sourceUri) {
+    return {
+      status: "elsewhere",
+      document: unique,
+      matchRank: bestRank,
+      matchCount: 1,
+      candidates: best,
+    };
+  }
+  return {
+    status: "unique",
+    document: unique,
+    matchRank: bestRank,
+    matchCount: 1,
+    candidates: best,
+  };
+}
+
+/**
+ * Resolve a markdown path target (already normalized to collection-relative).
+ */
+export function resolveMarkdownTarget(input: {
+  targetRefNorm: string;
+  targetCollection: string;
+  sourceUri: string;
+  catalog: readonly FileRefactorCatalogDocument[];
+}): FileRefactorResolution {
+  const matches = input.catalog
+    .filter(
+      (doc) =>
+        doc.active !== false &&
+        doc.collection === input.targetCollection &&
+        doc.relPath === input.targetRefNorm
+    )
+    .sort((a, b) => a.id - b.id);
+
+  if (matches.length === 0) {
+    return { status: "unresolved", matchCount: 0, candidates: [] };
+  }
+  if (matches.length > 1) {
+    return {
+      status: "ambiguous",
+      matchCount: matches.length,
+      reasonCode: "ambiguous_resolution",
+      candidates: matches,
+    };
+  }
+  const unique = matches[0]!;
+  if (unique.uri !== input.sourceUri) {
+    return {
+      status: "elsewhere",
+      document: unique,
+      matchCount: 1,
+      candidates: matches,
+    };
+  }
+  return {
+    status: "unique",
+    document: unique,
+    matchCount: 1,
+    candidates: matches,
+  };
+}
+
+/**
+ * Normalize a markdown inventory destination relative to the referring doc.
+ * Unescapes CommonMark punctuation and strips angle brackets before the shared
+ * path normalizer (which rejects raw backslashes).
+ */
+export function normalizeInventoryMarkdownTarget(
+  destination: string,
+  referringRelPath: string
+): string | null {
+  const angled = stripAngleBracketDestination(destination);
+  const unescaped = unescapeCommonMarkDestination(angled.path);
+  return normalizeMarkdownPath(unescaped, referringRelPath);
+}