@gmickel/gno 1.31.0 → 1.32.0

package/src/core/file-refactor-plan-classify.ts

@@ -0,0 +1,208 @@
+/**
+ * Per-token classification for reference-safe file refactor planning.
+ *
+ * @module src/core/file-refactor-plan-classify
+ */
+
+import type {
+  FileRefactorDestinationSpan,
+  FileRefactorExaminedReference,
+  FileRefactorReasonCode,
+} from "./file-refactor-contract";
+import type { FileRefactorPlannerDocument } from "./file-refactor-planner-types";
+import type { FileRefactorCatalogDocument } from "./file-refactor-resolve";
+import type { LinkInventoryToken } from "./link-inventory-types";
+
+import {
+  computeMarkdownReplacementDestination,
+  computeWikiReplacementDestination,
+  wikiDestinationUnchangedAcceptable,
+} from "./file-refactor-destination";
+import {
+  normalizeInventoryMarkdownTarget,
+  resolveMarkdownTarget,
+  resolveWikiTarget,
+} from "./file-refactor-resolve";
+
+function spanFromToken(
+  token: LinkInventoryToken,
+  replacement: string
+): FileRefactorDestinationSpan {
+  return {
+    coordinateSpace: "utf16_code_units",
+    startOffset: token.destinationStart,
+    endOffset: token.destinationEnd,
+    originalDestination: token.originalDestination,
+    replacementDestination: replacement,
+  };
+}
+
+export function examinedFromToken(
+  doc: FileRefactorPlannerDocument,
+  token: LinkInventoryToken,
+  overrides: Partial<FileRefactorExaminedReference> = {}
+): FileRefactorExaminedReference {
+  return {
+    documentUri: doc.uri,
+    documentRelPath: doc.relPath,
+    kind: token.kind,
+    classification: token.classification ?? "unchanged",
+    reasonCode: token.reasonCode,
+    originalDestination: token.originalDestination,
+    proposedDestination:
+      overrides.proposedDestination ?? token.originalDestination,
+    startLine: token.startLine,
+    startCol: token.startCol,
+    endLine: token.endLine,
+    endCol: token.endCol,
+    ...overrides,
+  };
+}
+
+function capabilityDenied(
+  doc: FileRefactorPlannerDocument,
+  token: LinkInventoryToken
+): FileRefactorExaminedReference {
+  return examinedFromToken(doc, token, {
+    classification: "unsupported",
+    reasonCode:
+      doc.editableReason === "read_only_document"
+        ? "read_only_document"
+        : "capability_denied",
+    proposedDestination: token.originalDestination,
+    edit: undefined,
+  });
+}
+
+/**
+ * Classify one inventory token against the moved source. Returns null when the
+ * token uniquely resolves elsewhere (not about this refactor).
+ */
+export function classifyResolvableToken(input: {
+  token: LinkInventoryToken;
+  doc: FileRefactorPlannerDocument;
+  sourceUri: string;
+  sourceRelPath: string;
+  sourceTitle: string | null | undefined;
+  targetRelPath: string;
+  targetTitle: string | null | undefined;
+  catalog: FileRefactorCatalogDocument[];
+}): FileRefactorExaminedReference | null {
+  const { token, doc } = input;
+
+  if (token.classification) {
+    return examinedFromToken(doc, token, {
+      classification: token.classification,
+      reasonCode: token.reasonCode,
+    });
+  }
+
+  if (token.targetCollection && token.targetCollection !== doc.collection) {
+    return examinedFromToken(doc, token, {
+      classification: "unsupported",
+      reasonCode: "cross_collection_unsupported",
+    });
+  }
+
+  if (token.kind === "wiki") {
+    const resolution = resolveWikiTarget({
+      targetRef: token.targetRef,
+      targetCollection: token.targetCollection ?? doc.collection,
+      sourceUri: input.sourceUri,
+      catalog: input.catalog,
+    });
+    if (
+      resolution.status === "elsewhere" ||
+      resolution.status === "unresolved"
+    ) {
+      return null;
+    }
+    if (resolution.status === "ambiguous") {
+      return examinedFromToken(doc, token, {
+        classification: "ambiguous",
+        reasonCode: resolution.reasonCode ?? "ambiguous_resolution",
+      });
+    }
+    if (doc.editable === false) {
+      return capabilityDenied(doc, token);
+    }
+    const replacement = computeWikiReplacementDestination({
+      originalDestination: token.originalDestination,
+      sourceRelPath: input.sourceRelPath,
+      sourceTitle: input.sourceTitle,
+      targetRelPath: input.targetRelPath,
+      targetTitle: input.targetTitle,
+    });
+    if (
+      wikiDestinationUnchangedAcceptable({
+        originalDestination: token.originalDestination,
+        replacementDestination: replacement,
+      })
+    ) {
+      return examinedFromToken(doc, token, {
+        classification: "unchanged",
+        reasonCode: "destination_unchanged",
+        proposedDestination: token.originalDestination,
+      });
+    }
+    return examinedFromToken(doc, token, {
+      classification: "rewriteable",
+      proposedDestination: replacement,
+      edit: spanFromToken(token, replacement),
+    });
+  }
+
+  const normalized = normalizeInventoryMarkdownTarget(
+    token.targetRef,
+    doc.relPath
+  );
+  if (!normalized) {
+    return examinedFromToken(doc, token, {
+      classification: "invalid",
+      reasonCode: "unsafe_target",
+    });
+  }
+  const resolution = resolveMarkdownTarget({
+    targetRefNorm: normalized,
+    targetCollection: doc.collection,
+    sourceUri: input.sourceUri,
+    catalog: input.catalog,
+  });
+  if (resolution.status === "elsewhere" || resolution.status === "unresolved") {
+    return null;
+  }
+  if (resolution.status === "ambiguous") {
+    return examinedFromToken(doc, token, {
+      classification: "ambiguous",
+      reasonCode: resolution.reasonCode ?? "ambiguous_resolution",
+    });
+  }
+  if (doc.editable === false) {
+    return capabilityDenied(doc, token);
+  }
+
+  const replacement = computeMarkdownReplacementDestination({
+    token,
+    referringRelPath: doc.relPath,
+    targetRelPath: input.targetRelPath,
+  });
+  const reasonCode: FileRefactorReasonCode =
+    token.kind === "markdown_definition"
+      ? "reference_definition_site"
+      : "relative_path_recalculated";
+
+  if (replacement === token.originalDestination) {
+    return examinedFromToken(doc, token, {
+      classification: "unchanged",
+      reasonCode: "destination_unchanged",
+      proposedDestination: token.originalDestination,
+    });
+  }
+
+  return examinedFromToken(doc, token, {
+    classification: "rewriteable",
+    reasonCode,
+    proposedDestination: replacement,
+    edit: spanFromToken(token, replacement),
+  });
+}

package/src/core/file-refactor-plan-validate.ts

@@ -0,0 +1,169 @@
+/**
+ * Input validation for reference-safe file refactor planning.
+ *
+ * Fail closed with stable diagnostics — never throw after a partial plan.
+ *
+ * @module src/core/file-refactor-plan-validate
+ */
+
+// node:path/posix — no Bun path utils
+import { posix as pathPosix } from "node:path";
+
+import type {
+  FileRefactorExaminedReference,
+  FileRefactorOperation,
+  FileRefactorReasonCode,
+} from "./file-refactor-contract";
+
+import { parseUri } from "../app/constants";
+
+export interface FileRefactorPlanValidationFailure {
+  canApply: false;
+  reasonCode: FileRefactorReasonCode;
+  diagnostic: string;
+  examined: FileRefactorExaminedReference[];
+}
+
+function pathBasename(relPath: string): string {
+  const idx = relPath.lastIndexOf("/");
+  return idx >= 0 ? relPath.slice(idx + 1) : relPath;
+}
+
+function pathDirname(relPath: string): string {
+  const idx = relPath.lastIndexOf("/");
+  return idx >= 0 ? relPath.slice(0, idx) : "";
+}
+
+function isUnsafeRelPath(relPath: string): string | null {
+  if (!relPath || !relPath.trim()) return "empty_path";
+  if (relPath.includes("\0")) return "null_byte";
+  if (relPath.includes("\\")) return "backslash_path";
+  if (pathPosix.isAbsolute(relPath) || relPath.startsWith("/")) {
+    return "absolute_path";
+  }
+  if (relPath.endsWith("/")) return "non_file_path";
+  const segments = relPath.split("/");
+  if (segments.some((segment) => segment.length === 0)) {
+    return "non_canonical_path";
+  }
+  if (segments.some((segment) => segment === ".")) {
+    return "dot_component";
+  }
+  if (segments.some((segment) => segment === "..")) {
+    return "path_traversal";
+  }
+  const normalized = pathPosix.normalize(relPath);
+  if (normalized !== relPath) return "non_canonical_path";
+  if (normalized.startsWith("..") || normalized.split("/").includes("..")) {
+    return "path_traversal";
+  }
+  const base = pathBasename(relPath);
+  if (!base || base === "." || base === "..") return "non_file_path";
+  return null;
+}
+
+function uriMatches(uri: string, collection: string, relPath: string): boolean {
+  const parsed = parseUri(uri);
+  if (!parsed) return false;
+  return parsed.collection === collection && parsed.path === relPath;
+}
+
+/**
+ * Validate source/target coherence before computing replacements.
+ * Returns a failure descriptor, or null when inputs are safe to plan.
+ */
+export function validateFileRefactorPlanInputs(input: {
+  operation: FileRefactorOperation;
+  source: {
+    uri: string;
+    relPath: string;
+    collection: string;
+  };
+  target: {
+    uri: string;
+    relPath: string;
+    collection: string;
+  };
+}): FileRefactorPlanValidationFailure | null {
+  const sourceUnsafe = isUnsafeRelPath(input.source.relPath);
+  if (sourceUnsafe) {
+    return failure(
+      input,
+      "unsafe_target",
+      `invalid_source_path:${sourceUnsafe}`
+    );
+  }
+  const targetUnsafe = isUnsafeRelPath(input.target.relPath);
+  if (targetUnsafe) {
+    return failure(
+      input,
+      "unsafe_target",
+      `invalid_target_path:${targetUnsafe}`
+    );
+  }
+
+  if (input.source.collection !== input.target.collection) {
+    return failure(
+      input,
+      "cross_collection_unsupported",
+      "cross_collection_target"
+    );
+  }
+
+  if (
+    input.source.relPath === input.target.relPath ||
+    input.source.uri === input.target.uri
+  ) {
+    return failure(input, "unsafe_target", "source_matches_target");
+  }
+
+  if (
+    !uriMatches(input.source.uri, input.source.collection, input.source.relPath)
+  ) {
+    return failure(input, "unsafe_target", "source_uri_path_mismatch");
+  }
+  if (
+    !uriMatches(input.target.uri, input.target.collection, input.target.relPath)
+  ) {
+    return failure(input, "unsafe_target", "target_uri_path_mismatch");
+  }
+
+  if (input.operation === "rename") {
+    if (
+      pathDirname(input.source.relPath) !== pathDirname(input.target.relPath)
+    ) {
+      return failure(input, "unsafe_target", "rename_directory_changed");
+    }
+  }
+
+  return null;
+}
+
+function failure(
+  input: {
+    source: { uri: string; relPath: string };
+  },
+  reasonCode: FileRefactorReasonCode,
+  diagnostic: string
+): FileRefactorPlanValidationFailure {
+  return {
+    canApply: false,
+    reasonCode,
+    diagnostic,
+    examined: [
+      {
+        documentUri: input.source.uri,
+        documentRelPath: input.source.relPath,
+        kind: "opaque",
+        classification:
+          reasonCode === "cross_collection_unsupported"
+            ? "unsupported"
+            : "invalid",
+        reasonCode,
+        originalDestination: diagnostic,
+      },
+    ],
+  };
+}
+
+export { pathBasename, pathDirname };

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

@@ -0,0 +1,62 @@
+/**
+ * Shared planner document / input types for reference-safe refactors.
+ *
+ * @module src/core/file-refactor-planner-types
+ */
+
+import type { FileRefactorOperation } from "./file-refactor-contract";
+
+export const FILE_REFACTOR_PLANNER_CAPS = {
+  maxCatalogDocuments: 5_000,
+  maxContentDocuments: 5_000,
+  maxExaminedReferences: 10_000,
+  maxContentCharsPerDocument: 1_000_000,
+  /** Aggregate UTF-16 content budget across inventoried documents. */
+  maxTotalContentChars: 20_000_000,
+} as const;
+
+export interface FileRefactorPlannerDocument {
+  id: number;
+  uri: string;
+  relPath: string;
+  collection: string;
+  title: string | null;
+  /** Full UTF-8 markdown body when this document should be inventoried. */
+  content?: string | null;
+  /** True when a potentially relevant doc lacked mirror content. */
+  contentMissing?: boolean;
+  /** False for read-only / logical-record referrers. Defaults to true. */
+  editable?: boolean;
+  /** Optional capability denial reason for diagnostics. */
+  editableReason?: string;
+  active?: boolean;
+}
+
+export interface PlanFileRefactorImpactInput {
+  operation: FileRefactorOperation;
+  source: {
+    uri: string;
+    relPath: string;
+    collection: string;
+    title?: string | null;
+    content: string;
+    editable: boolean;
+  };
+  target: {
+    uri: string;
+    relPath: string;
+    collection: string;
+    title?: string | null;
+  };
+  /** Active documents used for resolution + optional content inventory. */
+  documents: FileRefactorPlannerDocument[];
+  /** Occupancy check: true when target path already exists as another doc. */
+  targetOccupied: boolean;
+  /** Optional content-free occupancy fingerprint seed (defaults to target path). */
+  targetPathFingerprintSeed?: string;
+  /**
+   * Explicit truncation / completeness reasons from the store read seam.
+   * Callers must not drop these — they force canApply=false.
+   */
+  truncationReasons?: readonly string[];
+}