@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/session/import/normalize.ts

@@ -0,0 +1,195 @@
+/**
+ * Sub-part opaque-fragment normalization helpers for the load path.
+ *
+ * Slice 2c of refactor/01 package-session. Extracted from
+ * src/io/docx-session.ts (legacy lines ~2590-2720 pre-extraction).
+ *
+ * "Sub-parts" = the ancillary OOXML parts attached to the main
+ * document (headers, footers, footnotes, endnotes). When their block
+ * content includes regions we don't fully model, the parser emits
+ * `opaque_block` nodes carrying the raw XML. These helpers assign
+ * stable fragment/warning/diagnostic IDs, push entries into the
+ * canonical opaque-fragment store, and append matching preservation
+ * warnings — so the load path surfaces every preserved region without
+ * losing the source XML.
+ *
+ * Contract P6 clean. Depends on `src/model/canonical-document.ts`
+ * (allowed) and `./part-discovery.ts` boundary types only.
+ */
+
+import type {
+  BlockNode,
+  CanonicalDocument,
+  FootnoteCollection,
+  OpaqueFragmentRecord,
+} from "../../model/canonical-document.ts";
+
+/** Warning shape carried on `CanonicalDocument.diagnostics.warnings`. */
+type CanonicalWarning = CanonicalDocument["diagnostics"]["warnings"][number];
+
+/**
+ * Mutable bookkeeping so a single load-path run assigns collision-free
+ * fragment/warning/diagnostic IDs + stable range cursors across every
+ * sub-part it normalizes. Seeded from the already-imported state (the
+ * main document may have contributed opaque fragments before sub-part
+ * normalization runs).
+ */
+export interface SubPartOpaqueImportState {
+  nextFragmentIndex: number;
+  nextWarningIndex: number;
+  nextDiagnosticIndex: number;
+  cursor: number;
+}
+
+/**
+ * Seed a fresh `SubPartOpaqueImportState` by scanning the already-
+ * imported opaque fragments + warnings for the highest existing
+ * `fragment:import-N` / `warning:import-N` / `diagnostic:import-N`
+ * indices, and the maximum `lastKnownRange.to` value. This guarantees
+ * the sub-part normalization pass never collides with IDs the main
+ * document already emitted.
+ */
+export function createSubPartOpaqueImportState(
+  opaqueFragments: Record<string, OpaqueFragmentRecord>,
+  warnings: CanonicalWarning[],
+): SubPartOpaqueImportState {
+  const maxByPrefix = (values: Iterable<string>, prefix: string): number => {
+    let max = 0;
+    for (const value of values) {
+      const match = new RegExp(`^${prefix}(\\d+)$`).exec(value);
+      if (!match) continue;
+      const parsed = Number.parseInt(match[1] ?? "0", 10);
+      if (Number.isFinite(parsed) && parsed > max) max = parsed;
+    }
+    return max;
+  };
+
+  const maxCursor = Object.values(opaqueFragments).reduce(
+    (currentMax, fragment) => Math.max(currentMax, fragment.lastKnownRange?.to ?? 0),
+    0,
+  );
+
+  return {
+    nextFragmentIndex:
+      maxByPrefix(Object.keys(opaqueFragments), "fragment:import-") + 1,
+    nextWarningIndex:
+      maxByPrefix(
+        [
+          ...Object.values(opaqueFragments).map((fragment) => fragment.warningId),
+          ...warnings.map((warning) => warning.warningId),
+        ],
+        "warning:import-",
+      ) + 1,
+    nextDiagnosticIndex:
+      maxByPrefix(warnings.map((warning) => warning.diagnosticId), "diagnostic:import-") + 1,
+    cursor: maxCursor,
+  };
+}
+
+/**
+ * Walk a sub-part's block list. For each `opaque_block` carrying raw
+ * XML, register a fresh fragment + warning + diagnostic and replace
+ * the block's ids with the registered ones. Non-opaque blocks pass
+ * through unchanged.
+ */
+export function normalizeSubPartOpaqueBlocks(
+  blocks: BlockNode[],
+  opaqueFragments: Record<string, OpaqueFragmentRecord>,
+  warnings: CanonicalWarning[],
+  packagePartName: string,
+  state: SubPartOpaqueImportState,
+): BlockNode[] {
+  return blocks.map((block) => {
+    if (block.type !== "opaque_block" || typeof block.rawXml !== "string") {
+      return block;
+    }
+    return recordImportedOpaqueBlock(
+      block.rawXml,
+      opaqueFragments,
+      warnings,
+      packagePartName,
+      state,
+    );
+  });
+}
+
+/**
+ * Apply `normalizeSubPartOpaqueBlocks` to every footnote (or endnote,
+ * when `kind === "endnote"`) definition's block list inside a shared
+ * footnote/endnote collection. Mutates the collection in place so
+ * the load path's subsequent passes see the normalized state.
+ */
+export function normalizeFootnoteCollectionOpaqueBlocks(
+  collection: FootnoteCollection | undefined,
+  kind: "footnote" | "endnote",
+  opaqueFragments: Record<string, OpaqueFragmentRecord>,
+  warnings: CanonicalWarning[],
+  packagePartName: string,
+  state: SubPartOpaqueImportState,
+): void {
+  if (!collection) return;
+  const notes = kind === "footnote" ? collection.footnotes : collection.endnotes;
+  for (const definition of Object.values(notes)) {
+    definition.blocks = normalizeSubPartOpaqueBlocks(
+      definition.blocks,
+      opaqueFragments,
+      warnings,
+      packagePartName,
+      state,
+    );
+  }
+}
+
+/**
+ * Register a single opaque block against the imported state:
+ *   - allocate `fragment:import-N` / `warning:import-N` /
+ *     `diagnostic:import-N` ids.
+ *   - push a new `OpaqueFragmentRecord` into `opaqueFragments`.
+ *   - push a matching preservation warning into `warnings`.
+ *   - advance `state.cursor` by 1 (reserving a [from, to) range).
+ * Returns the rebuilt `opaque_block` node carrying the fresh ids.
+ */
+export function recordImportedOpaqueBlock(
+  rawXml: string,
+  opaqueFragments: Record<string, OpaqueFragmentRecord>,
+  warnings: CanonicalWarning[],
+  packagePartName: string,
+  state: SubPartOpaqueImportState,
+): BlockNode {
+  const fragmentId = `fragment:import-${state.nextFragmentIndex}`;
+  state.nextFragmentIndex += 1;
+  const warningId = `warning:import-${state.nextWarningIndex}`;
+  state.nextWarningIndex += 1;
+  const diagnosticId = `diagnostic:import-${state.nextDiagnosticIndex}`;
+  state.nextDiagnosticIndex += 1;
+
+  const rangeStart = state.cursor;
+  const rangeEnd = state.cursor + 1;
+  state.cursor = rangeEnd;
+
+  opaqueFragments[fragmentId] = {
+    fragmentId,
+    payloadKind: "xml-subtree",
+    payloadReference: rawXml,
+    featureClass: "preserve-only",
+    lastKnownRange: {
+      from: rangeStart,
+      to: rangeEnd,
+    },
+    warningId,
+    packagePartName,
+  };
+  warnings.push({
+    diagnosticId,
+    warningId,
+    source: "import",
+    message: "Unsupported sub-part OOXML was preserved as an opaque placeholder.",
+  });
+
+  return {
+    type: "opaque_block",
+    fragmentId,
+    warningId,
+    rawXml,
+  };
+}

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

@@ -0,0 +1,217 @@
+/**
+ * Package-part preservation + relationship utilities.
+ *
+ * Slice 2d of refactor/01 package-session. Extracted from
+ * src/io/docx-session.ts (legacy lines ~3718-3920 pre-extraction).
+ * Groups the pure helpers that deal with OPC package-part accounting
+ * (which parts to preserve verbatim on round-trip, which relationship
+ * ids target a given part, inline-media enumeration, etc.).
+ *
+ * Contract P6 clean. All dependencies live under allowed prefixes
+ * (src/io, src/preservation).
+ */
+
+import type { OpcPackage } from "../../io/opc/package-reader.ts";
+import {
+  normalizePartPath,
+  resolveRelationshipTarget,
+  type OpcRelationship,
+  type OpcSurfaceKind,
+} from "../../io/ooxml/part-manifest.ts";
+import type { PreservedPackagePart } from "../../model/canonical-document.ts";
+
+/**
+ * Core parts that never carry preservation state: they're either
+ * regenerated on export (app / core props, numbering) or their
+ * ownership is tracked elsewhere.
+ */
+export const CORE_NON_PRESERVED_PART_PATHS: ReadonlySet<string> = new Set([
+  "/docProps/app.xml",
+  "/docProps/core.xml",
+  "/word/numbering.xml",
+]);
+
+/**
+ * Decide whether a given package part should round-trip as a
+ * preserved (byte-stable) package part. True for content-kind parts
+ * that aren't owned by the runtime, aren't inline media, and aren't
+ * regenerated on export.
+ */
+export function shouldPreservePackagePart(
+  partPath: string,
+  surfaceKind: OpcSurfaceKind,
+  ownedPartPaths: ReadonlySet<string>,
+): boolean {
+  if (surfaceKind !== "content") return false;
+  if (
+    ownedPartPaths.has(partPath) ||
+    partPath.startsWith("/word/media/") ||
+    CORE_NON_PRESERVED_PART_PATHS.has(partPath)
+  ) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Enumerate every internal relationship id that points at the given
+ * target part. Searches both the package-level relationships and every
+ * part's relationships. Returns a deterministically-sorted list.
+ */
+export function findRelationshipIdsTargetingPart(
+  sourcePackage: OpcPackage,
+  targetPartPath: string,
+): string[] {
+  const ids = new Set<string>();
+
+  for (const relationship of sourcePackage.manifest.packageRelationships) {
+    if (
+      relationship.targetMode === "internal" &&
+      resolveRelationshipTarget(null, relationship) === targetPartPath
+    ) {
+      ids.add(relationship.id);
+    }
+  }
+
+  for (const part of sourcePackage.parts.values()) {
+    for (const relationship of part.relationships) {
+      if (
+        relationship.targetMode === "internal" &&
+        resolveRelationshipTarget(part.path, relationship) === targetPartPath
+      ) {
+        ids.add(relationship.id);
+      }
+    }
+  }
+
+  return [...ids].sort();
+}
+
+/**
+ * Build the `PreservedPackagePart` map keyed by part path. Skips the
+ * parts this load pass explicitly owns (they'll be re-serialized) and
+ * the core non-preserved set.
+ */
+export function collectPreservedPackageParts(
+  sourcePackage: OpcPackage,
+  ownedPartPaths: ReadonlyArray<string | undefined>,
+): Record<string, PreservedPackagePart> {
+  const normalizedOwnedPaths = new Set(
+    ownedPartPaths
+      .filter((value): value is string => typeof value === "string")
+      .map((path) => normalizePartPath(path)),
+  );
+  return Object.fromEntries(
+    [...sourcePackage.parts.values()]
+      .filter((part) =>
+        shouldPreservePackagePart(part.path, part.surfaceKind, normalizedOwnedPaths),
+      )
+      .map((part) => [
+        part.path,
+        {
+          packagePartName: part.path,
+          contentType: part.contentType ?? "application/octet-stream",
+          relationshipIds: findRelationshipIdsTargetingPart(sourcePackage, part.path),
+        } satisfies PreservedPackagePart,
+      ]),
+  );
+}
+
+/**
+ * Enumerate every `/word/media/` part as a simple path + content-type
+ * pair. Used by the secondary-story media catalog merge to thread
+ * inline media through the canonical document.
+ */
+export function collectInlineMediaParts(
+  sourcePackage: OpcPackage,
+): ReadonlyMap<string, { path: string; contentType: string }> {
+  return new Map(
+    [...sourcePackage.parts.values()]
+      .filter(
+        (part) =>
+          part.path.startsWith("/word/media/") && typeof part.contentType === "string",
+      )
+      .map((part) => [
+        part.path,
+        {
+          path: part.path,
+          contentType: part.contentType ?? "application/octet-stream",
+        },
+      ]),
+  );
+}
+
+/**
+ * Allocate a fresh `rIdCommentsN` relationship id that doesn't collide
+ * with any existing relationship in the supplied list. Used by the
+ * export path when re-attaching the comments sub-part.
+ */
+export function createCommentsRelationshipId(
+  relationships: readonly OpcRelationship[],
+): string {
+  let nextIndex = 1;
+  while (
+    relationships.some(
+      (relationship) => relationship.id === `rIdComments${nextIndex}`,
+    )
+  ) {
+    nextIndex += 1;
+  }
+  return `rIdComments${nextIndex}`;
+}
+
+/**
+ * Normalize a part path to a document-relative target string. The
+ * normalized form strips the leading slash + `word/` prefix so the
+ * value is suitable as `<Relationship Target="..."/>` content.
+ */
+export function toDocumentRelativeTarget(partPath: string): string {
+  const normalized = normalizePartPath(partPath);
+  return normalized.startsWith("/word/")
+    ? normalized.slice("/word/".length)
+    : normalized.slice(1);
+}
+
+/** Shallow copy of an OPC relationship. */
+export function cloneRelationship(relationship: OpcRelationship): OpcRelationship {
+  return { ...relationship };
+}
+
+/**
+ * Rebuild a main-document relationship list after toggling whether
+ * each document-related part (comments, header, footer, footnotes,
+ * endnotes, …) is present. Callers pass `include: true` to keep the
+ * relationship, `false` to drop it. Relationships of types listed in
+ * `relatedParts` are always filtered out first (so an incoming list
+ * with include=false effectively removes that relationship type);
+ * every other relationship passes through unchanged via
+ * `cloneRelationship`.
+ */
+export function withDocumentRelatedParts(
+  relationships: readonly OpcRelationship[],
+  relatedParts: ReadonlyArray<{
+    relationshipType: string;
+    partPath: string;
+    existingRelationshipId?: string;
+    include: boolean;
+  }>,
+): OpcRelationship[] {
+  const filteredTypes = new Set(relatedParts.map((part) => part.relationshipType));
+  const nextRelationships = relationships
+    .filter((relationship) => !filteredTypes.has(relationship.type))
+    .map(cloneRelationship);
+
+  for (const part of relatedParts) {
+    if (!part.include) continue;
+    nextRelationships.push({
+      id:
+        part.existingRelationshipId ??
+        createCommentsRelationshipId(nextRelationships),
+      type: part.relationshipType,
+      target: toDocumentRelativeTarget(part.partPath),
+      targetMode: "internal",
+    });
+  }
+
+  return nextRelationships;
+}

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

@@ -0,0 +1,195 @@
+/**
+ * OPC-package-level validation helpers for the load path.
+ *
+ * Slice 2b of refactor/01 package-session. Extracted from
+ * src/io/docx-session.ts (legacy lines ~3920-4070 pre-extraction).
+ * Pure functions over an `OpcPackage`; contract P6 clean (no runtime /
+ * ui / core / review imports). Depends on:
+ *   - src/io/opc/corrupt-package.ts (`createBrokenRelationshipIssue`)
+ *   - src/io/ooxml/part-manifest.ts (`resolveRelationshipTarget`)
+ *   - src/session/import/part-discovery.ts (`OFFICE_DOCUMENT_RELATIONSHIP_TYPE`)
+ *
+ * These helpers detect broken internal relationships in a loaded OPC
+ * package — some fatal (main-document relationship points at a missing
+ * part) and some not (ancillary part relationships outside the editor-
+ * owned graph, surfaced as preservation warnings rather than fatal
+ * diagnostics).
+ */
+
+import type { CanonicalDocument } from "../../model/canonical-document.ts";
+import type { OpcPackage } from "../../io/opc/package-reader.ts";
+import { createBrokenRelationshipIssue } from "../../io/opc/corrupt-package.ts";
+import {
+  resolveRelationshipTarget,
+  type OpcRelationship,
+} from "../../io/ooxml/part-manifest.ts";
+import { OFFICE_DOCUMENT_RELATIONSHIP_TYPE } from "./part-discovery.ts";
+
+/** A broken-relationship issue as produced by `createBrokenRelationshipIssue`. */
+export type BrokenRelationshipIssue = ReturnType<typeof createBrokenRelationshipIssue>;
+
+/** Warning shape carried on `CanonicalDocument.diagnostics.warnings`. */
+type CanonicalWarning = CanonicalDocument["diagnostics"]["warnings"][number];
+
+/**
+ * Enumerate every internal relationship in the package whose target is
+ * absent AND whose absence is fatal. Returns a deterministically-sorted
+ * list. Used by the loader to decide whether to emit a fatal import
+ * diagnostic (main-document missing) vs a preservation warning
+ * (ancillary parts).
+ */
+export function collectBrokenInternalRelationshipIssues(
+  sourcePackage: OpcPackage,
+  mainDocumentPath?: string,
+): BrokenRelationshipIssue[] {
+  const brokenTargets = new Map<string, BrokenRelationshipIssue>();
+
+  for (const relationship of sourcePackage.manifest.packageRelationships) {
+    if (relationship.targetMode !== "internal") continue;
+
+    const target = resolveRelationshipTarget(null, relationship);
+    if (
+      !sourcePackage.parts.has(target) &&
+      isFatalBrokenRelationship({
+        relationshipSourcePath: null,
+        relationship,
+        targetPartPath: target,
+        mainDocumentPath,
+      })
+    ) {
+      brokenTargets.set(
+        `package:${relationship.id}:${target}`,
+        createBrokenRelationshipIssue({
+          relationshipSourcePath: null,
+          relationshipId: relationship.id,
+          targetPartPath: target,
+        }),
+      );
+    }
+  }
+
+  for (const part of sourcePackage.parts.values()) {
+    for (const relationship of part.relationships) {
+      if (relationship.targetMode !== "internal") continue;
+
+      const target = resolveRelationshipTarget(part.path, relationship);
+      if (
+        !sourcePackage.parts.has(target) &&
+        isFatalBrokenRelationship({
+          relationshipSourcePath: part.path,
+          relationship,
+          targetPartPath: target,
+          mainDocumentPath,
+        })
+      ) {
+        brokenTargets.set(
+          `${part.path}:${relationship.id}:${target}`,
+          createBrokenRelationshipIssue({
+            relationshipSourcePath: part.path,
+            relationshipId: relationship.id,
+            targetPartPath: target,
+          }),
+        );
+      }
+    }
+  }
+
+  return [...brokenTargets.values()].sort((left, right) =>
+    `${left.relationshipSourcePath ?? ""}:${left.relationshipId}:${left.targetPartPath}`.localeCompare(
+      `${right.relationshipSourcePath ?? ""}:${right.relationshipId}:${right.targetPartPath}`,
+    ),
+  );
+}
+
+/** Build the one-line summary shown on a fatal broken-relationship diagnostic. */
+export function summarizeBrokenRelationshipIssues(
+  issues: readonly BrokenRelationshipIssue[],
+): string {
+  return `DOCX package has unresolved internal relationships: ${issues
+    .map((issue) => issue.targetPartPath ?? issue.message)
+    .slice(0, 3)
+    .join(", ")}${issues.length > 3 ? ", ..." : ""}.`;
+}
+
+/**
+ * Build preservation-warning entries for the subset of broken
+ * relationships that are NOT fatal — ancillary parts whose targets
+ * sit outside the editor-owned graph. These surface as warnings on
+ * the canonical document rather than blocking the load.
+ */
+export function createBrokenRelationshipWarnings(
+  sourcePackage: OpcPackage,
+  mainDocumentPath?: string,
+): CanonicalWarning[] {
+  const warnings = new Map<string, CanonicalWarning>();
+
+  for (const relationship of sourcePackage.manifest.packageRelationships) {
+    if (relationship.targetMode !== "internal") continue;
+
+    const target = resolveRelationshipTarget(null, relationship);
+    if (
+      sourcePackage.parts.has(target) ||
+      isFatalBrokenRelationship({
+        relationshipSourcePath: null,
+        relationship,
+        targetPartPath: target,
+        mainDocumentPath,
+      })
+    ) {
+      continue;
+    }
+
+    warnings.set(`package:${relationship.id}:${target}`, {
+      diagnosticId: `diagnostic:broken-relationship-package-${relationship.id}`,
+      warningId: `warning:broken-relationship:${relationship.id}`,
+      source: "preservation",
+      message: `DOCX package has unresolved internal relationships outside the editor-owned graph: ${target}.`,
+    });
+  }
+
+  for (const part of sourcePackage.parts.values()) {
+    for (const relationship of part.relationships) {
+      if (relationship.targetMode !== "internal") continue;
+
+      const target = resolveRelationshipTarget(part.path, relationship);
+      if (
+        sourcePackage.parts.has(target) ||
+        isFatalBrokenRelationship({
+          relationshipSourcePath: part.path,
+          relationship,
+          targetPartPath: target,
+          mainDocumentPath,
+        })
+      ) {
+        continue;
+      }
+
+      warnings.set(`${part.path}:${relationship.id}:${target}`, {
+        diagnosticId: `diagnostic:broken-relationship-${relationship.id}`,
+        warningId: `warning:broken-relationship:${relationship.id}`,
+        source: "preservation",
+        message: `DOCX package has unresolved internal relationships outside the editor-owned graph: ${target}.`,
+      });
+    }
+  }
+
+  return [...warnings.values()];
+}
+
+/**
+ * Classifier: is this broken relationship a fatal load error? Only the
+ * package-level officeDocument relationship when its target matches
+ * `mainDocumentPath`. Everything else is a preservation warning.
+ */
+export function isFatalBrokenRelationship(input: {
+  relationshipSourcePath: string | null;
+  relationship: OpcRelationship;
+  targetPartPath: string;
+  mainDocumentPath?: string;
+}): boolean {
+  return (
+    input.relationshipSourcePath === null &&
+    input.relationship.type === OFFICE_DOCUMENT_RELATIONSHIP_TYPE &&
+    input.targetPartPath === input.mainDocumentPath
+  );
+}