@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/session/import/review-import.ts

@@ -0,0 +1,508 @@
+/**
+ * Review-side import helpers extracted from `src/io/docx-session.ts`
+ * (slice 5e-6d). These functions translate parsed OOXML revisions +
+ * comments into the canonical review shapes and back into the runtime-
+ * facing record map — they are part of the package/session integration
+ * surface, not review-layer state management.
+ *
+ * The module is P6-clean: every cross-layer type reaches through
+ * `src/model/**`, never through `src/review/**` or `src/core/**`.
+ * Anchor mechanics used here (`createDetachedAnchor`) come from
+ * `src/model/anchor.ts`; revision / comment shapes + the pure
+ * `getRevisionActionability` predicate come from `src/model/review/`.
+ */
+
+import { createDetachedAnchor } from "../../model/anchor.ts";
+import type {
+  CanonicalDocument,
+  CommentThread as CommentThreadRecord,
+  OpaqueFragmentRecord,
+  RevisionRecord as RuntimeRevisionRecord,
+} from "../../model/canonical-document.ts";
+import type { CommentThread } from "../../model/review/comment-types.ts";
+import {
+  getRevisionActionability,
+  type RevisionRecord as ReviewRevisionRecord,
+} from "../../model/review/revision-types.ts";
+import type {
+  CommentImportDiagnostic,
+  ImportedCommentDefinition,
+  ParsedCommentsResult,
+} from "../../io/ooxml/parse-comments.ts";
+import type { ParsedRevisionsResult } from "../../io/ooxml/parse-revisions.ts";
+import { serializeRuntimeRevisionsIntoStoryXml } from "../../io/export/serialize-runtime-revisions.ts";
+
+type CanonicalDocumentEnvelope = CanonicalDocument;
+
+export interface NormalizedImportedCommentsResult extends ParsedCommentsResult {
+  preservedDefinitions: readonly ImportedCommentDefinition[];
+}
+
+export function normalizeImportedRevisionRecords(
+  parsed: ParsedRevisionsResult,
+  content: CanonicalDocumentEnvelope["content"],
+  opaqueFragments: Record<string, OpaqueFragmentRecord>,
+): ParsedRevisionsResult {
+  const opaqueRanges = Object.values(opaqueFragments).map((fragment) => fragment.lastKnownRange);
+  const paragraphRanges = collectCanonicalParagraphRanges(content);
+  if (opaqueRanges.length === 0) {
+    return {
+      ...parsed,
+      revisions: parsed.revisions.map((revision) => {
+        if (revision.anchor.kind !== "range" || revision.metadata.preserveOnlyReason) {
+          return revision;
+        }
+
+        const preserveOnlyReason = getStructuralPreserveOnlyReason(
+          revision,
+          paragraphRanges,
+        );
+        if (!preserveOnlyReason) {
+          return revision;
+        }
+
+        return {
+          ...revision,
+          metadata: {
+            ...revision.metadata,
+            preserveOnlyReason,
+          },
+        };
+      }),
+    };
+  }
+
+  return {
+    ...parsed,
+    revisions: parsed.revisions.map((revision) => {
+      const { anchor } = revision;
+      if (anchor.kind !== "range" || revision.metadata.preserveOnlyReason) {
+        return revision;
+      }
+
+      const preserveOnlyReason =
+        getStructuralPreserveOnlyReason(revision, paragraphRanges) ??
+        (opaqueRanges.some((range) => rangesIntersect(range, anchor.range))
+          ? "Imported revision overlaps preserve-only OOXML and remains preserve-only."
+          : undefined);
+
+      if (!preserveOnlyReason) {
+        return revision;
+      }
+
+      return {
+        ...revision,
+        metadata: {
+          ...revision.metadata,
+          preserveOnlyReason,
+        },
+      };
+    }),
+  };
+}
+
+export function normalizeImportedCommentThreads(
+  parsed: ParsedCommentsResult,
+  opaqueFragments: Record<string, OpaqueFragmentRecord>,
+  revisions: readonly ReviewRevisionRecord[],
+): NormalizedImportedCommentsResult {
+  const opaqueRanges = Object.values(opaqueFragments).map((fragment) => fragment.lastKnownRange);
+  // Use getRevisionActionability() — not the raw preserveOnlyReason flag — so
+  // Lane 7b-promoted shapes (cellIns/cellDel/cellMerge, linked-pair moves) that
+  // still carry a default preserveOnlyReason aren't treated as preserve-only
+  // for comment-anchor detachment. See revision-types.ts:192-200.
+  const preserveOnlyRevisionRanges = revisions.flatMap((revision) => {
+    if (
+      revision.anchor.kind !== "range" ||
+      getRevisionActionability(revision) !== "preserve-only"
+    ) {
+      return [];
+    }
+    return [revision.anchor.range];
+  });
+  const preserveOnlyCommentIds = new Set(parsed.diagnostics.map((diagnostic) => diagnostic.commentId));
+  const additionalDiagnostics: CommentImportDiagnostic[] = [];
+  const normalizedThreads: CommentThread[] = parsed.threads.map((thread) => {
+    const { anchor } = thread;
+    if (anchor.kind !== "range") {
+      preserveOnlyCommentIds.add(thread.commentId);
+      return thread;
+    }
+
+    const opaqueOverlap = opaqueRanges.some((range) => rangesIntersect(range, anchor.range));
+    if (opaqueOverlap) {
+      preserveOnlyCommentIds.add(thread.commentId);
+      additionalDiagnostics.push({
+        commentId: thread.commentId,
+        code: "opaque_anchor_preserve_only",
+        message:
+          "Comment anchor intersects preserve-only OOXML content. Thread is visible but detached; anchor cannot be safely remapped.",
+        featureClass: "preserve-only",
+        detachedReason: "opaque-region" as const,
+        actionabilityNote: "The comment body is preserved. The anchor overlaps opaque content that the editor cannot safely modify.",
+      });
+      return {
+        ...thread,
+        anchor: createDetachedAnchor(anchor.range, "importAmbiguity"),
+        status: "detached",
+        metadata: {
+          ...thread.metadata,
+          detachedReason: "opaque-region",
+          actionabilityNote:
+            "The comment body is preserved. The anchor overlaps opaque content that the editor cannot safely modify.",
+        },
+      };
+    }
+
+    const preserveOnlyRevisionOverlap = preserveOnlyRevisionRanges.some((range) =>
+      rangesIntersect(range, anchor.range),
+    );
+    if (preserveOnlyRevisionOverlap) {
+      preserveOnlyCommentIds.add(thread.commentId);
+      additionalDiagnostics.push({
+        commentId: thread.commentId,
+        code: "preserve_only_revision_overlap",
+        message:
+          "Comment anchor overlaps preserve-only review markup. Thread is visible but detached; anchor cannot be safely remapped during editing.",
+        featureClass: "preserve-only",
+        detachedReason: "revision-overlap" as const,
+        actionabilityNote: "The comment body is preserved. The anchor overlaps preserve-only revision markup that the editor cannot safely modify.",
+      });
+      return {
+        ...thread,
+        anchor: createDetachedAnchor(anchor.range, "importAmbiguity"),
+        status: "detached",
+        metadata: {
+          ...thread.metadata,
+          detachedReason: "revision-overlap",
+          actionabilityNote:
+            "The comment body is preserved. The anchor overlaps preserve-only revision markup that the editor cannot safely modify.",
+        },
+      };
+    }
+
+    return thread;
+  });
+
+  return {
+    ...parsed,
+    threads: normalizedThreads,
+    diagnostics: [...parsed.diagnostics, ...additionalDiagnostics],
+    definitions: parsed.definitions,
+    preservedDefinitions: parsed.definitions.filter((definition) =>
+      preserveOnlyCommentIds.has(
+        resolveDefinitionRootCommentId(definition, parsed.definitions),
+      ),
+    ),
+  };
+}
+
+export function resolveImportedCommentThreadOnTranslation(
+  thread: CommentThread,
+  timestamp: string,
+): CommentThread {
+  if (thread.status === "resolved") {
+    return thread;
+  }
+  return {
+    ...thread,
+    status: thread.status === "detached" ? "detached" : "resolved",
+    resolution: thread.resolution ?? {
+      resolvedAt: timestamp,
+      resolvedBy: thread.entries[thread.entries.length - 1]?.authorId ?? thread.createdBy,
+    },
+  };
+}
+
+export function resolveDefinitionRootCommentId(
+  definition: ImportedCommentDefinition,
+  definitions: readonly ImportedCommentDefinition[],
+): string {
+  if (!definition.parentParaId) {
+    return definition.commentId;
+  }
+
+  const definitionsByParaId = new Map(
+    definitions
+      .filter((candidate) => typeof candidate.paraId === "string")
+      .map((candidate) => [candidate.paraId!, candidate]),
+  );
+  const visited = new Set<string>();
+  let current: ImportedCommentDefinition | undefined = definition;
+
+  while (current?.parentParaId) {
+    if (visited.has(current.parentParaId)) {
+      break;
+    }
+    visited.add(current.parentParaId);
+    const parent = definitionsByParaId.get(current.parentParaId);
+    if (!parent) {
+      break;
+    }
+    current = parent;
+  }
+
+  return current?.commentId ?? definition.commentId;
+}
+
+export function getStructuralPreserveOnlyReason(
+  revision: ReviewRevisionRecord,
+  paragraphRanges: ReadonlyArray<{ start: number; end: number }>,
+): string | undefined {
+  const form = revision.metadata.importedRevisionForm;
+  const { anchor } = revision;
+  if (!form || anchor.kind !== "range") {
+    return undefined;
+  }
+
+  if (
+    (form === "run-insertion" || form === "run-deletion") &&
+    anchor.range.from === anchor.range.to
+  ) {
+    return "Imported zero-width run revision remains preserve-only.";
+  }
+
+  if (form === "paragraph-insertion" || form === "paragraph-deletion") {
+    const paragraphBoundary = paragraphRanges.find(
+      (boundary) =>
+        boundary.end === anchor.range.from ||
+        (anchor.range.from >= boundary.start &&
+          anchor.range.from <= boundary.end),
+    );
+    return paragraphBoundary
+      ? undefined
+      : "Imported revision spans paragraph-level structure and remains preserve-only.";
+  }
+
+  const paragraphBoundary = paragraphRanges.find(
+    (boundary) =>
+      anchor.range.from >= boundary.start &&
+      anchor.range.to <= boundary.end,
+  );
+  return paragraphBoundary
+    ? undefined
+    : "Imported revision spans structural boundaries and remains preserve-only.";
+}
+
+export function collectCanonicalParagraphRanges(
+  content: CanonicalDocumentEnvelope["content"],
+): Array<{ start: number; end: number }> {
+  const ranges: Array<{ start: number; end: number }> = [];
+  let cursor = 0;
+  let previousWasParagraph = false;
+
+  for (const block of content.children) {
+    if (block.type === "paragraph") {
+      if (previousWasParagraph) {
+        cursor += 1;
+      }
+      const start = cursor;
+      cursor += measureCanonicalParagraph(block);
+      ranges.push({ start, end: cursor });
+      previousWasParagraph = true;
+      continue;
+    }
+
+    cursor += 1;
+    previousWasParagraph = false;
+  }
+
+  return ranges;
+}
+
+export function measureCanonicalParagraph(
+  paragraph: CanonicalDocumentEnvelope["content"]["children"][number] & { type: "paragraph" },
+): number {
+  return paragraph.children.reduce<number>((size, child) => {
+    if (child.type === "text") {
+      return size + Array.from(child.text).length;
+    }
+    if (child.type === "hyperlink") {
+      return (
+        size +
+        child.children.reduce<number>((childSize, entry) => {
+          if (entry.type === "text") {
+            return childSize + Array.from(entry.text).length;
+          }
+          return childSize + 1;
+        }, 0)
+      );
+    }
+    return size + 1;
+  }, 0);
+}
+
+export function rangesIntersect(
+  left: { from: number; to: number },
+  right: { from: number; to: number },
+): boolean {
+  return left.from < right.to && right.from < left.to;
+}
+
+export function toRuntimeCommentRecords(
+  threads: readonly CommentThread[],
+): Record<string, CommentThreadRecord> {
+  return Object.fromEntries(
+    threads.map((thread) => {
+      return [
+        thread.commentId,
+        {
+          commentId: thread.commentId,
+          body: thread.entries.map((entry) => entry.body).join("\n"),
+          anchor: thread.anchor,
+          createdBy: thread.createdBy,
+          authorId: thread.createdBy,
+          createdAt: thread.createdAt,
+          entries: thread.entries.map((entry) => ({
+            entryId: entry.entryId,
+            authorId: entry.authorId,
+            body: entry.body,
+            createdAt: entry.createdAt,
+            metadata: entry.metadata
+              ? {
+                  ooxmlCommentId: entry.metadata.ooxmlCommentId,
+                  paraId: entry.metadata.paraId,
+                  parentParaId: entry.metadata.parentParaId,
+                  durableId: entry.metadata.durableId,
+                  initials: entry.metadata.initials,
+                }
+              : undefined,
+          })),
+          status: thread.status,
+          resolution: thread.resolution
+            ? {
+                resolvedAt: thread.resolution.resolvedAt,
+                resolvedBy: thread.resolution.resolvedBy,
+              }
+            : undefined,
+          resolvedAt: thread.resolution?.resolvedAt,
+          warningIds: [...thread.warningIds],
+          isResolved: thread.status === "resolved",
+          metadata: thread.metadata
+            ? {
+                source: thread.metadata.source,
+                rootOoxmlCommentId: thread.metadata.rootOoxmlCommentId,
+                rootParaId: thread.metadata.rootParaId,
+              }
+            : undefined,
+        } satisfies CommentThreadRecord,
+      ];
+    }),
+  );
+}
+
+export function toRuntimeRevisionRecords(
+  revisions: readonly ReviewRevisionRecord[],
+): Record<string, RuntimeRevisionRecord> {
+  return Object.fromEntries(
+    revisions.map((revision) => [
+      revision.revisionId,
+      {
+        changeId: revision.revisionId,
+        kind: revision.kind,
+        anchor: revision.anchor,
+        authorId: revision.authorId,
+        createdAt: revision.createdAt,
+        warningIds: [...revision.warningIds],
+        metadata: {
+          source: revision.metadata.source,
+          storyTarget: revision.metadata.storyTarget,
+          preserveOnlyReason: revision.metadata.preserveOnlyReason,
+          suggestionId: revision.metadata.suggestionId,
+          semanticKind: revision.metadata.semanticKind,
+          linkedRevisionIds: revision.metadata.linkedRevisionIds,
+          predecessorSuggestionId: revision.metadata.predecessorSuggestionId,
+          importedRevisionForm: revision.metadata.importedRevisionForm,
+          originalRevisionType: revision.metadata.originalRevisionType,
+          ooxmlRevisionId: revision.metadata.ooxmlRevisionId,
+          propertyChangeData: revision.metadata.propertyChangeData,
+          moveData: revision.metadata.moveData,
+        },
+        status: revision.status === "active" ? "open" : revision.status,
+      } satisfies RuntimeRevisionRecord,
+    ]),
+  );
+}
+
+export function toReviewRevisionRecords(
+  revisions: CanonicalDocumentEnvelope["review"]["revisions"],
+): ReviewRevisionRecord[] {
+  return Object.values(revisions).map((revision) => ({
+    revisionId: revision.changeId,
+    kind: revision.kind,
+    anchor: revision.anchor,
+    authorId: revision.authorId ?? "unknown",
+    createdAt: revision.createdAt,
+    warningIds: [...(revision.warningIds ?? [])],
+    metadata: {
+      source: revision.metadata?.source ?? "runtime",
+      storyTarget: revision.metadata?.storyTarget,
+      preserveOnlyReason: revision.metadata?.preserveOnlyReason,
+      suggestionId: revision.metadata?.suggestionId,
+      semanticKind: revision.metadata?.semanticKind,
+      linkedRevisionIds: revision.metadata?.linkedRevisionIds,
+      predecessorSuggestionId: revision.metadata?.predecessorSuggestionId,
+      importedRevisionForm: revision.metadata?.importedRevisionForm,
+      originalRevisionType: revision.metadata?.originalRevisionType,
+      ooxmlRevisionId: revision.metadata?.ooxmlRevisionId,
+      propertyChangeData: revision.metadata?.propertyChangeData,
+      moveData: revision.metadata?.moveData,
+    },
+    status: revision.status === "open" ? "active" : revision.status,
+  }));
+}
+
+export function serializeSecondaryStoryWithRuntimeRevisions(
+  xml: string,
+  revisions: readonly ReviewRevisionRecord[],
+  label: string,
+): string {
+  if (revisions.length === 0) {
+    return xml;
+  }
+
+  const serialized = serializeRuntimeRevisionsIntoStoryXml(xml, revisions);
+  if (serialized.skippedRevisionIds.length > 0) {
+    throw new Error(
+      `DOCX export is blocked because ${serialized.skippedRevisionIds.length} active revisions overlap unsupported serialization boundaries in ${label}.`,
+    );
+  }
+  return serialized.documentXml;
+}
+
+export function stripCommentMarkup(
+  documentXml: string,
+  ownedCommentIds: readonly string[],
+): string {
+  if (ownedCommentIds.length === 0) {
+    return documentXml;
+  }
+
+  let output = documentXml;
+  for (const commentId of ownedCommentIds) {
+    const escapedCommentId = escapeRegExp(commentId);
+    const attributePattern = `(?:w:id|id)=["']${escapedCommentId}["']`;
+    output = output
+      .replace(
+        new RegExp(`<w:commentRangeStart\\b[^>]*${attributePattern}[^>]*/>`, "gu"),
+        "",
+      )
+      .replace(
+        new RegExp(`<w:commentRangeEnd\\b[^>]*${attributePattern}[^>]*/>`, "gu"),
+        "",
+      )
+      .replace(
+        new RegExp(
+          `<w:r\\b[^>]*>(?:(?!<w:t\\b|</w:r>)[\\s\\S])*?<w:commentReference\\b[^>]*${attributePattern}[^>]*/>(?:(?!<w:t\\b|</w:r>)[\\s\\S])*?</w:r>`,
+          "gu",
+        ),
+        "",
+      );
+  }
+
+  return output;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}