@beyondwork/docx-react-component 1.0.101 → 1.0.103

package/src/session/import/source-package-evidence.ts

@@ -0,0 +1,1016 @@
+import type { OpcPackage } from "../../io/opc/package-reader.ts";
+import { readOpcPackage } from "../../io/opc/package-reader.ts";
+import { sha256Hex } from "../../io/source-package-provenance.ts";
+import {
+  normalizePartPath,
+  resolveRelationshipTarget,
+  type OpcPackagePart,
+  type OpcRelationship,
+} from "../../io/ooxml/part-manifest.ts";
+import { parseXml, parseXmlWithOffsets } from "../../io/ooxml/xml-parser.ts";
+import type { XmlElementNode } from "../../io/ooxml/xml-element.ts";
+import { localName } from "../../io/ooxml/xml-attr-helpers.ts";
+import {
+  resolveMainDocumentPartPath,
+} from "./part-discovery.ts";
+
+export interface SourcePackageElementCounts {
+  tables: number;
+  tableRows: number;
+  tableCells: number;
+  anchors: number;
+  inlineDrawings: number;
+  drawings: number;
+  vmlShapes: number;
+  contentControls: number;
+  fieldMarkers: number;
+  fieldInstructions: number;
+  simpleFields: number;
+  bookmarks: number;
+  footnotes: number;
+  endnotes: number;
+}
+
+export interface SourcePackagePartEvidence {
+  path: string;
+  storyKind: SourcePackageStoryKind;
+  contentType: string | null;
+  byteLength: number;
+  relationshipCount: number;
+  counts: SourcePackageElementCounts;
+}
+
+export interface SourcePackageRelationshipEvidence {
+  sourcePartPath: string | null;
+  relationshipId: string;
+  relationshipType: string;
+  targetMode: OpcRelationship["targetMode"];
+  target: string;
+  resolvedTarget: string;
+  targetExists: boolean;
+}
+
+export interface SourcePackageLocationEvidence {
+  sourceId: string;
+  partPath: string;
+  storyKind: SourcePackageStoryKind;
+  element: string;
+  ordinal: number;
+  startOffset?: number;
+  endOffset?: number;
+}
+
+export interface SourcePackageStoryPartDescriptor {
+  sourceId: string;
+  partPath: string;
+  storyKind: SourcePackageStoryKind;
+  relationshipId?: string;
+  relationshipType?: string;
+  relationshipSourcePartPath?: string | null;
+}
+
+export interface SourcePackageHeaderFooterReferenceEvidence {
+  kind: "header" | "footer";
+  relationshipId: string;
+  type?: string;
+  resolvedTarget?: string;
+  targetExists?: boolean;
+}
+
+export interface SourcePackageSectionDescriptorEvidence
+  extends SourcePackageLocationEvidence {
+  headerFooterReferences: SourcePackageHeaderFooterReferenceEvidence[];
+}
+
+export interface SourcePackageObjectExtentEvidence
+  extends SourcePackageLocationEvidence {
+  kind: "drawing" | "vml-shape" | "object";
+  display: "inline" | "floating" | "unknown";
+  preserveOnly: true;
+  fallbackHint:
+    | "drawing-inline"
+    | "drawing-floating"
+    | "vml-shape"
+    | "ole-object"
+    | "opaque-object";
+  extentEmu?: { width: number; height: number };
+  extentTwips?: { width: number; height: number };
+  relationshipIds: string[];
+  shapeId?: string;
+  shapeType?: string;
+  vmlStyle?: string;
+}
+
+export interface SourcePackageRelationshipGroupEvidence {
+  headerFooters: SourcePackageRelationshipEvidence[];
+  media: SourcePackageRelationshipEvidence[];
+  charts: SourcePackageRelationshipEvidence[];
+  embedded: SourcePackageRelationshipEvidence[];
+  customXml: SourcePackageRelationshipEvidence[];
+  settings: SourcePackageRelationshipEvidence[];
+  numbering: SourcePackageRelationshipEvidence[];
+  comments: SourcePackageRelationshipEvidence[];
+}
+
+export interface SourcePackagePartGroupEvidence {
+  media: SourcePackageStoryPartDescriptor[];
+  images: SourcePackageStoryPartDescriptor[];
+  charts: SourcePackageStoryPartDescriptor[];
+  embedded: SourcePackageStoryPartDescriptor[];
+  customXml: SourcePackageStoryPartDescriptor[];
+  settings: SourcePackageStoryPartDescriptor[];
+  numbering: SourcePackageStoryPartDescriptor[];
+  comments: SourcePackageStoryPartDescriptor[];
+  themes: SourcePackageStoryPartDescriptor[];
+}
+
+export interface SourcePackageLayoutInventoryEvidence {
+  storyParts: SourcePackageStoryPartDescriptor[];
+  partGroups: SourcePackagePartGroupEvidence;
+  relationships: SourcePackageRelationshipGroupEvidence;
+  sections: SourcePackageSectionDescriptorEvidence[];
+  tables: SourcePackageLocationEvidence[];
+  fields: SourcePackageLocationEvidence[];
+  drawings: SourcePackageLocationEvidence[];
+  vmlShapes: SourcePackageLocationEvidence[];
+  contentControls: SourcePackageLocationEvidence[];
+  bookmarks: SourcePackageLocationEvidence[];
+  notes: SourcePackageLocationEvidence[];
+  objects: SourcePackageObjectExtentEvidence[];
+}
+
+export interface SourcePackageEvidence {
+  schemaVersion: 1;
+  docId: string;
+  sourceLabel?: string;
+  sha256Hex: string;
+  sourceByteLength: number;
+  mainDocumentPartPath?: string;
+  partCount: number;
+  contentPartCount: number;
+  relationshipCount: number;
+  internalRelationshipCount: number;
+  externalRelationshipCount: number;
+  brokenInternalRelationshipCount: number;
+  counts: SourcePackageElementCounts & {
+    headers: number;
+    footers: number;
+    mediaParts: number;
+    imageParts: number;
+    chartParts: number;
+    embeddedParts: number;
+    customXmlParts: number;
+    commentsParts: number;
+    numberingParts: number;
+    settingsParts: number;
+    themeParts: number;
+  };
+  parts: SourcePackagePartEvidence[];
+  relationships: SourcePackageRelationshipEvidence[];
+  layoutInventory: SourcePackageLayoutInventoryEvidence;
+  parseErrors: Array<{ partPath: string; message: string }>;
+}
+
+export type SourcePackageStoryKind =
+  | "main-document"
+  | "header"
+  | "footer"
+  | "footnotes"
+  | "endnotes"
+  | "comments"
+  | "numbering"
+  | "settings"
+  | "styles"
+  | "font-table"
+  | "theme"
+  | "chart"
+  | "media"
+  | "embedded"
+  | "custom-xml"
+  | "relationships"
+  | "content-types"
+  | "other";
+
+const ZERO_COUNTS: SourcePackageElementCounts = {
+  tables: 0,
+  tableRows: 0,
+  tableCells: 0,
+  anchors: 0,
+  inlineDrawings: 0,
+  drawings: 0,
+  vmlShapes: 0,
+  contentControls: 0,
+  fieldMarkers: 0,
+  fieldInstructions: 0,
+  simpleFields: 0,
+  bookmarks: 0,
+  footnotes: 0,
+  endnotes: 0,
+};
+
+export function createSourcePackageEvidenceFromBytes(
+  input: {
+    bytes: Uint8Array | ArrayBuffer;
+    docId: string;
+    sourceLabel?: string;
+  },
+): SourcePackageEvidence {
+  const bytes = input.bytes instanceof Uint8Array
+    ? input.bytes
+    : new Uint8Array(input.bytes);
+  return createSourcePackageEvidence(readOpcPackage(bytes), {
+    docId: input.docId,
+    sourceLabel: input.sourceLabel,
+    sha256Hex: sha256Hex(bytes),
+  });
+}
+
+export function createSourcePackageEvidence(
+  sourcePackage: OpcPackage,
+  input: {
+    docId: string;
+    sourceLabel?: string;
+    sha256Hex?: string;
+  },
+): SourcePackageEvidence {
+  const mainDocumentPartPath = resolveMainDocumentPartPath(sourcePackage);
+  const parseErrors: SourcePackageEvidence["parseErrors"] = [];
+  const parts = [...sourcePackage.parts.values()]
+    .sort((left, right) => left.path.localeCompare(right.path))
+    .map((part) => summarizePart(part, mainDocumentPartPath, parseErrors));
+  const relationships = collectRelationships(sourcePackage);
+  const relationshipCount = relationships.length;
+  const internalRelationshipCount = relationships.filter(
+    (relationship) => relationship.targetMode === "internal",
+  ).length;
+  const externalRelationshipCount = relationshipCount - internalRelationshipCount;
+  const brokenInternalRelationshipCount = relationships.filter(
+    (relationship) =>
+      relationship.targetMode === "internal" && !relationship.targetExists,
+  ).length;
+  const contentParts = parts.filter(
+    (part) => part.storyKind !== "relationships" && part.storyKind !== "content-types",
+  );
+  const aggregateCounts = aggregateElementCounts(parts.map((part) => part.counts));
+  const layoutInventory = collectLayoutInventory(
+    sourcePackage,
+    parts,
+    relationships,
+    mainDocumentPartPath,
+    parseErrors,
+  );
+
+  return {
+    schemaVersion: 1,
+    docId: input.docId,
+    ...(input.sourceLabel !== undefined ? { sourceLabel: input.sourceLabel } : {}),
+    sha256Hex: input.sha256Hex ?? "",
+    sourceByteLength: sourcePackage.sourceByteLength,
+    ...(mainDocumentPartPath !== undefined ? { mainDocumentPartPath } : {}),
+    partCount: sourcePackage.parts.size,
+    contentPartCount: contentParts.length,
+    relationshipCount,
+    internalRelationshipCount,
+    externalRelationshipCount,
+    brokenInternalRelationshipCount,
+    counts: {
+      ...aggregateCounts,
+      headers: countParts(parts, "header"),
+      footers: countParts(parts, "footer"),
+      mediaParts: countParts(parts, "media"),
+      imageParts: parts.filter((part) => part.contentType?.startsWith("image/")).length,
+      chartParts: countParts(parts, "chart"),
+      embeddedParts: countParts(parts, "embedded"),
+      customXmlParts: countParts(parts, "custom-xml"),
+      commentsParts: countParts(parts, "comments"),
+      numberingParts: countParts(parts, "numbering"),
+      settingsParts: countParts(parts, "settings"),
+      themeParts: countParts(parts, "theme"),
+    },
+    parts,
+    relationships,
+    layoutInventory,
+    parseErrors,
+  };
+}
+
+function summarizePart(
+  part: OpcPackagePart,
+  mainDocumentPartPath: string | undefined,
+  parseErrors: SourcePackageEvidence["parseErrors"],
+): SourcePackagePartEvidence {
+  const storyKind = classifyPart(part, mainDocumentPartPath);
+  return {
+    path: part.path,
+    storyKind,
+    contentType: part.contentType,
+    byteLength: part.bytes.byteLength,
+    relationshipCount: part.relationships.length,
+    counts: countPartElements(part, storyKind, parseErrors),
+  };
+}
+
+function countPartElements(
+  part: OpcPackagePart,
+  storyKind: SourcePackageStoryKind,
+  parseErrors: SourcePackageEvidence["parseErrors"],
+): SourcePackageElementCounts {
+  if (!shouldParseXmlPart(part, storyKind)) {
+    return { ...ZERO_COUNTS };
+  }
+
+  try {
+    return countElements(parseXml(new TextDecoder("utf-8").decode(part.bytes)));
+  } catch (error) {
+    parseErrors.push({
+      partPath: part.path,
+      message: error instanceof Error ? error.message : String(error),
+    });
+    return { ...ZERO_COUNTS };
+  }
+}
+
+function shouldParseXmlPart(
+  part: OpcPackagePart,
+  storyKind: SourcePackageStoryKind,
+): boolean {
+  if (part.surfaceKind !== "content") {
+    return false;
+  }
+  if (storyKind === "media" || storyKind === "embedded") {
+    return false;
+  }
+  return (
+    part.contentType?.includes("xml") === true ||
+    part.path.endsWith(".xml")
+  );
+}
+
+function countElements(root: XmlElementNode): SourcePackageElementCounts {
+  const counts = { ...ZERO_COUNTS };
+  const visit = (node: XmlElementNode): void => {
+    const name = localName(node.name);
+    switch (name) {
+      case "tbl":
+        counts.tables += 1;
+        break;
+      case "tr":
+        counts.tableRows += 1;
+        break;
+      case "tc":
+        counts.tableCells += 1;
+        break;
+      case "anchor":
+        counts.anchors += 1;
+        break;
+      case "inline":
+        counts.inlineDrawings += 1;
+        break;
+      case "drawing":
+        counts.drawings += 1;
+        break;
+      case "shape":
+        counts.vmlShapes += 1;
+        break;
+      case "sdt":
+        counts.contentControls += 1;
+        break;
+      case "fldChar":
+        counts.fieldMarkers += 1;
+        break;
+      case "instrText":
+        counts.fieldInstructions += 1;
+        break;
+      case "fldSimple":
+        counts.simpleFields += 1;
+        break;
+      case "bookmarkStart":
+        counts.bookmarks += 1;
+        break;
+      case "footnote":
+        counts.footnotes += 1;
+        break;
+      case "endnote":
+        counts.endnotes += 1;
+        break;
+    }
+
+    for (const child of node.children) {
+      if (child.type === "element") {
+        visit(child);
+      }
+    }
+  };
+
+  visit(root);
+  return counts;
+}
+
+function collectLayoutInventory(
+  sourcePackage: OpcPackage,
+  parts: SourcePackagePartEvidence[],
+  relationships: SourcePackageRelationshipEvidence[],
+  mainDocumentPartPath: string | undefined,
+  parseErrors: SourcePackageEvidence["parseErrors"],
+): SourcePackageLayoutInventoryEvidence {
+  const storyParts = collectStoryPartDescriptors(parts, relationships);
+  const partGroups = groupParts(storyParts, parts);
+  const relationshipGroups = groupRelationships(relationships);
+  const locations: Pick<
+    SourcePackageLayoutInventoryEvidence,
+    | "sections"
+    | "tables"
+    | "fields"
+    | "drawings"
+    | "vmlShapes"
+    | "contentControls"
+    | "bookmarks"
+    | "notes"
+    | "objects"
+  > = {
+    sections: [],
+    tables: [],
+    fields: [],
+    drawings: [],
+    vmlShapes: [],
+    contentControls: [],
+    bookmarks: [],
+    notes: [],
+    objects: [],
+  };
+
+  const partEvidenceByPath = new Map(parts.map((part) => [part.path, part]));
+  const sourceRelationshipByPart = relationships.reduce((map, relationship) => {
+    if (!relationship.sourcePartPath) return map;
+    const list = map.get(relationship.sourcePartPath) ?? [];
+    list.push(relationship);
+    map.set(relationship.sourcePartPath, list);
+    return map;
+  }, new Map<string, SourcePackageRelationshipEvidence[]>());
+
+  for (const part of sourcePackage.parts.values()) {
+    const partEvidence = partEvidenceByPath.get(part.path);
+    const storyKind = partEvidence?.storyKind ?? classifyPart(part, mainDocumentPartPath);
+    if (!shouldParseXmlPart(part, storyKind)) {
+      continue;
+    }
+
+    let root: XmlElementNode;
+    try {
+      root = parseXmlWithOffsets(new TextDecoder("utf-8").decode(part.bytes));
+    } catch (error) {
+      parseErrors.push({
+        partPath: part.path,
+        message: error instanceof Error ? error.message : String(error),
+      });
+      continue;
+    }
+
+    collectPartLocations(
+      root,
+      {
+        partPath: part.path,
+        storyKind,
+        relationships: sourceRelationshipByPart.get(part.path) ?? [],
+      },
+      locations,
+    );
+  }
+
+  return {
+    storyParts,
+    partGroups,
+    relationships: relationshipGroups,
+    ...locations,
+  };
+}
+
+function collectStoryPartDescriptors(
+  parts: SourcePackagePartEvidence[],
+  relationships: SourcePackageRelationshipEvidence[],
+): SourcePackageStoryPartDescriptor[] {
+  const descriptorByPath = new Map<string, SourcePackageStoryPartDescriptor>();
+  for (const part of parts) {
+    if (!isLayoutRelevantStoryKind(part.storyKind)) continue;
+    descriptorByPath.set(part.path, {
+      sourceId: partSourceId(part.path),
+      partPath: part.path,
+      storyKind: part.storyKind,
+    });
+  }
+
+  for (const relationship of relationships) {
+    if (relationship.targetMode !== "internal") continue;
+    const resolvedPath = normalizePartPath(relationship.resolvedTarget);
+    const descriptor = descriptorByPath.get(resolvedPath);
+    if (!descriptor) continue;
+    descriptorByPath.set(resolvedPath, {
+      ...descriptor,
+      relationshipId: relationship.relationshipId,
+      relationshipType: relationship.relationshipType,
+      relationshipSourcePartPath: relationship.sourcePartPath,
+    });
+  }
+
+  return [...descriptorByPath.values()].sort((left, right) =>
+    left.partPath.localeCompare(right.partPath),
+  );
+}
+
+function groupParts(
+  descriptors: SourcePackageStoryPartDescriptor[],
+  parts: SourcePackagePartEvidence[],
+): SourcePackagePartGroupEvidence {
+  const contentTypeByPath = new Map(parts.map((part) => [part.path, part.contentType]));
+  const byKind = (kind: SourcePackageStoryKind): SourcePackageStoryPartDescriptor[] =>
+    descriptors.filter((part) => part.storyKind === kind);
+
+  return {
+    media: byKind("media"),
+    images: byKind("media").filter((part) =>
+      contentTypeByPath.get(part.partPath)?.startsWith("image/") === true,
+    ),
+    charts: byKind("chart"),
+    embedded: byKind("embedded"),
+    customXml: byKind("custom-xml"),
+    settings: byKind("settings"),
+    numbering: byKind("numbering"),
+    comments: byKind("comments"),
+    themes: byKind("theme"),
+  };
+}
+
+function groupRelationships(
+  relationships: SourcePackageRelationshipEvidence[],
+): SourcePackageRelationshipGroupEvidence {
+  const byRole = (role: string): SourcePackageRelationshipEvidence[] =>
+    relationships.filter((relationship) => relationshipRole(relationship) === role);
+
+  return {
+    headerFooters: relationships.filter((relationship) => {
+      const role = relationshipRole(relationship);
+      return role === "header" || role === "footer";
+    }),
+    media: byRole("image"),
+    charts: byRole("chart"),
+    embedded: relationships.filter((relationship) => {
+      const role = relationshipRole(relationship);
+      return role === "oleObject" || role === "package";
+    }),
+    customXml: byRole("customXml"),
+    settings: byRole("settings"),
+    numbering: byRole("numbering"),
+    comments: byRole("comments"),
+  };
+}
+
+function collectPartLocations(
+  root: XmlElementNode,
+  context: {
+    partPath: string;
+    storyKind: SourcePackageStoryKind;
+    relationships: SourcePackageRelationshipEvidence[];
+  },
+  locations: Pick<
+    SourcePackageLayoutInventoryEvidence,
+    | "sections"
+    | "tables"
+    | "fields"
+    | "drawings"
+    | "vmlShapes"
+    | "contentControls"
+    | "bookmarks"
+    | "notes"
+    | "objects"
+  >,
+): void {
+  const ordinals = new Map<string, number>();
+  const nextOrdinal = (element: string): number => {
+    const next = (ordinals.get(element) ?? 0) + 1;
+    ordinals.set(element, next);
+    return next;
+  };
+
+  const visit = (node: XmlElementNode): void => {
+    const name = localName(node.name);
+    switch (name) {
+      case "sectPr":
+        locations.sections.push({
+          ...locationFor(context, node, name, nextOrdinal(name)),
+          headerFooterReferences: collectHeaderFooterReferences(node, context.relationships),
+        });
+        break;
+      case "tbl":
+        locations.tables.push(locationFor(context, node, name, nextOrdinal(name)));
+        break;
+      case "fldSimple":
+      case "fldChar":
+      case "instrText":
+        locations.fields.push(locationFor(context, node, name, nextOrdinal(name)));
+        break;
+      case "drawing": {
+        const ordinal = nextOrdinal(name);
+        locations.drawings.push(locationFor(context, node, name, ordinal));
+        break;
+      }
+      case "inline":
+      case "anchor": {
+        const ordinal = nextOrdinal(name);
+        locations.objects.push(drawingObjectFor(context, node, name, ordinal));
+        break;
+      }
+      case "shape": {
+        const ordinal = nextOrdinal(name);
+        locations.vmlShapes.push(locationFor(context, node, name, ordinal));
+        locations.objects.push(vmlObjectFor(context, node, ordinal));
+        break;
+      }
+      case "object": {
+        const ordinal = nextOrdinal(name);
+        locations.objects.push(objectFor(context, node, ordinal));
+        break;
+      }
+      case "sdt":
+        locations.contentControls.push(locationFor(context, node, name, nextOrdinal(name)));
+        break;
+      case "bookmarkStart":
+        locations.bookmarks.push(locationFor(context, node, name, nextOrdinal(name)));
+        break;
+      case "footnote":
+      case "endnote":
+        locations.notes.push(locationFor(context, node, name, nextOrdinal(name)));
+        break;
+    }
+
+    for (const child of node.children) {
+      if (child.type === "element") {
+        visit(child);
+      }
+    }
+  };
+
+  visit(root);
+}
+
+function locationFor(
+  context: {
+    partPath: string;
+    storyKind: SourcePackageStoryKind;
+  },
+  node: XmlElementNode,
+  element: string,
+  ordinal: number,
+): SourcePackageLocationEvidence {
+  return {
+    sourceId: elementSourceId(context.partPath, element, ordinal),
+    partPath: context.partPath,
+    storyKind: context.storyKind,
+    element,
+    ordinal,
+    ...(node.start !== undefined ? { startOffset: node.start } : {}),
+    ...(node.end !== undefined ? { endOffset: node.end } : {}),
+  };
+}
+
+function drawingObjectFor(
+  context: {
+    partPath: string;
+    storyKind: SourcePackageStoryKind;
+  },
+  node: XmlElementNode,
+  element: string,
+  ordinal: number,
+): SourcePackageObjectExtentEvidence {
+  const extentEmu = readDrawingExtentEmu(node);
+  return {
+    ...locationFor(context, node, element, ordinal),
+    kind: "drawing",
+    display: element === "anchor" ? "floating" : "inline",
+    preserveOnly: true,
+    fallbackHint: element === "anchor" ? "drawing-floating" : "drawing-inline",
+    ...(extentEmu ? { extentEmu, extentTwips: extentEmuToTwips(extentEmu) } : {}),
+    relationshipIds: collectRelationshipIds(node),
+  };
+}
+
+function vmlObjectFor(
+  context: {
+    partPath: string;
+    storyKind: SourcePackageStoryKind;
+  },
+  node: XmlElementNode,
+  ordinal: number,
+): SourcePackageObjectExtentEvidence {
+  const extentTwips = readVmlExtentTwips(node.attributes.style);
+  return {
+    ...locationFor(context, node, "shape", ordinal),
+    kind: "vml-shape",
+    display: "unknown",
+    preserveOnly: true,
+    fallbackHint: "vml-shape",
+    ...(extentTwips ? { extentTwips, extentEmu: extentTwipsToEmu(extentTwips) } : {}),
+    relationshipIds: collectRelationshipIds(node),
+    ...(node.attributes.id ? { shapeId: node.attributes.id } : {}),
+    ...(node.attributes.type ? { shapeType: node.attributes.type } : {}),
+    ...(node.attributes.style ? { vmlStyle: node.attributes.style } : {}),
+  };
+}
+
+function objectFor(
+  context: {
+    partPath: string;
+    storyKind: SourcePackageStoryKind;
+  },
+  node: XmlElementNode,
+  ordinal: number,
+): SourcePackageObjectExtentEvidence {
+  return {
+    ...locationFor(context, node, "object", ordinal),
+    kind: "object",
+    display: "unknown",
+    preserveOnly: true,
+    fallbackHint: hasDescendant(node, "OLEObject") ? "ole-object" : "opaque-object",
+    relationshipIds: collectRelationshipIds(node),
+  };
+}
+
+function collectHeaderFooterReferences(
+  node: XmlElementNode,
+  relationships: SourcePackageRelationshipEvidence[],
+): SourcePackageHeaderFooterReferenceEvidence[] {
+  const byId = new Map(relationships.map((relationship) => [relationship.relationshipId, relationship]));
+  const refs: SourcePackageHeaderFooterReferenceEvidence[] = [];
+  const visit = (current: XmlElementNode): void => {
+    const name = localName(current.name);
+    if (name === "headerReference" || name === "footerReference") {
+      const relationshipId = readRelationshipId(current);
+      if (relationshipId) {
+        const relationship = byId.get(relationshipId);
+        refs.push({
+          kind: name === "headerReference" ? "header" : "footer",
+          relationshipId,
+          ...(current.attributes["w:type"] ?? current.attributes.type
+            ? { type: current.attributes["w:type"] ?? current.attributes.type }
+            : {}),
+          ...(relationship ? { resolvedTarget: relationship.resolvedTarget } : {}),
+          ...(relationship ? { targetExists: relationship.targetExists } : {}),
+        });
+      }
+    }
+    for (const child of current.children) {
+      if (child.type === "element") visit(child);
+    }
+  };
+  visit(node);
+  return refs;
+}
+
+function collectRelationships(
+  sourcePackage: OpcPackage,
+): SourcePackageRelationshipEvidence[] {
+  const relationships: SourcePackageRelationshipEvidence[] = [];
+  const pushRelationship = (
+    sourcePartPath: string | null,
+    relationship: OpcRelationship,
+  ): void => {
+    const resolvedTarget =
+      relationship.targetMode === "internal"
+        ? resolveRelationshipTarget(sourcePartPath, relationship)
+        : relationship.target;
+    relationships.push({
+      sourcePartPath,
+      relationshipId: relationship.id,
+      relationshipType: relationship.type,
+      targetMode: relationship.targetMode,
+      target: relationship.target,
+      resolvedTarget,
+      targetExists:
+        relationship.targetMode === "external" ||
+        sourcePackage.parts.has(normalizePartPath(resolvedTarget)),
+    });
+  };
+
+  for (const relationship of sourcePackage.manifest.packageRelationships) {
+    pushRelationship(null, relationship);
+  }
+  for (const part of sourcePackage.parts.values()) {
+    for (const relationship of part.relationships) {
+      pushRelationship(part.path, relationship);
+    }
+  }
+
+  return relationships.sort((left, right) => {
+    const leftKey = `${left.sourcePartPath ?? ""}:${left.relationshipId}`;
+    const rightKey = `${right.sourcePartPath ?? ""}:${right.relationshipId}`;
+    return leftKey.localeCompare(rightKey);
+  });
+}
+
+function classifyPart(
+  part: OpcPackagePart,
+  mainDocumentPartPath: string | undefined,
+): SourcePackageStoryKind {
+  const path = part.path;
+  if (part.surfaceKind === "relationships") return "relationships";
+  if (part.surfaceKind === "content-types") return "content-types";
+  if (mainDocumentPartPath && path === mainDocumentPartPath) return "main-document";
+  if (/^\/word\/header\d*\.xml$/u.test(path)) return "header";
+  if (/^\/word\/footer\d*\.xml$/u.test(path)) return "footer";
+  if (path === "/word/footnotes.xml") return "footnotes";
+  if (path === "/word/endnotes.xml") return "endnotes";
+  if (path.startsWith("/word/comments")) return "comments";
+  if (path === "/word/numbering.xml") return "numbering";
+  if (path === "/word/settings.xml") return "settings";
+  if (path === "/word/styles.xml") return "styles";
+  if (path === "/word/fontTable.xml") return "font-table";
+  if (path.startsWith("/word/theme/")) return "theme";
+  if (path.startsWith("/word/charts/")) return "chart";
+  if (path.startsWith("/word/media/")) return "media";
+  if (path.startsWith("/word/embeddings/")) return "embedded";
+  if (path.startsWith("/customXml/") && path.endsWith(".xml")) return "custom-xml";
+  return "other";
+}
+
+function aggregateElementCounts(
+  countsList: SourcePackageElementCounts[],
+): SourcePackageElementCounts {
+  const aggregate = { ...ZERO_COUNTS };
+  for (const counts of countsList) {
+    aggregate.tables += counts.tables;
+    aggregate.tableRows += counts.tableRows;
+    aggregate.tableCells += counts.tableCells;
+    aggregate.anchors += counts.anchors;
+    aggregate.inlineDrawings += counts.inlineDrawings;
+    aggregate.drawings += counts.drawings;
+    aggregate.vmlShapes += counts.vmlShapes;
+    aggregate.contentControls += counts.contentControls;
+    aggregate.fieldMarkers += counts.fieldMarkers;
+    aggregate.fieldInstructions += counts.fieldInstructions;
+    aggregate.simpleFields += counts.simpleFields;
+    aggregate.bookmarks += counts.bookmarks;
+    aggregate.footnotes += counts.footnotes;
+    aggregate.endnotes += counts.endnotes;
+  }
+  return aggregate;
+}
+
+function countParts(
+  parts: SourcePackagePartEvidence[],
+  storyKind: SourcePackageStoryKind,
+): number {
+  return parts.filter((part) => part.storyKind === storyKind).length;
+}
+
+function isLayoutRelevantStoryKind(storyKind: SourcePackageStoryKind): boolean {
+  return (
+    storyKind === "main-document" ||
+    storyKind === "header" ||
+    storyKind === "footer" ||
+    storyKind === "footnotes" ||
+    storyKind === "endnotes" ||
+    storyKind === "comments" ||
+    storyKind === "numbering" ||
+    storyKind === "settings" ||
+    storyKind === "theme" ||
+    storyKind === "chart" ||
+    storyKind === "media" ||
+    storyKind === "embedded" ||
+    storyKind === "custom-xml"
+  );
+}
+
+function relationshipRole(relationship: SourcePackageRelationshipEvidence): string {
+  const slashIndex = relationship.relationshipType.lastIndexOf("/");
+  return slashIndex >= 0
+    ? relationship.relationshipType.slice(slashIndex + 1)
+    : relationship.relationshipType;
+}
+
+function partSourceId(partPath: string): string {
+  return `part:${partPath}`;
+}
+
+function elementSourceId(partPath: string, element: string, ordinal: number): string {
+  return `${partSourceId(partPath)}#${element}:${ordinal}`;
+}
+
+function readDrawingExtentEmu(
+  node: XmlElementNode,
+): { width: number; height: number } | undefined {
+  const extent = findFirstDescendantByLocalName(node, "extent");
+  const width = extent ? readIntAttribute(extent, "cx") : undefined;
+  const height = extent ? readIntAttribute(extent, "cy") : undefined;
+  if (width !== undefined && height !== undefined) {
+    return { width, height };
+  }
+
+  const transform = findFirstDescendantByLocalName(node, "xfrm");
+  const ext = transform ? findFirstDescendantByLocalName(transform, "ext") : undefined;
+  const fallbackWidth = ext ? readIntAttribute(ext, "cx") : undefined;
+  const fallbackHeight = ext ? readIntAttribute(ext, "cy") : undefined;
+  if (fallbackWidth !== undefined && fallbackHeight !== undefined) {
+    return { width: fallbackWidth, height: fallbackHeight };
+  }
+  return undefined;
+}
+
+function readVmlExtentTwips(
+  style: string | undefined,
+): { width: number; height: number } | undefined {
+  if (!style) return undefined;
+  const width = readCssLengthTwips(style, "width");
+  const height = readCssLengthTwips(style, "height");
+  if (width !== undefined && height !== undefined) {
+    return { width, height };
+  }
+  return undefined;
+}
+
+function readCssLengthTwips(style: string, property: "width" | "height"): number | undefined {
+  const match = new RegExp(`(?:^|;)\\s*${property}\\s*:\\s*([0-9.]+)\\s*(pt|in|cm|mm|px)?`, "iu")
+    .exec(style);
+  if (!match) return undefined;
+  const value = Number.parseFloat(match[1] ?? "");
+  if (!Number.isFinite(value)) return undefined;
+  const unit = (match[2] ?? "pt").toLowerCase();
+  switch (unit) {
+    case "pt":
+      return Math.round(value * 20);
+    case "in":
+      return Math.round(value * 1440);
+    case "cm":
+      return Math.round(value * 567);
+    case "mm":
+      return Math.round(value * 56.7);
+    case "px":
+      return Math.round(value * 15);
+    default:
+      return undefined;
+  }
+}
+
+function extentEmuToTwips(
+  extent: { width: number; height: number },
+): { width: number; height: number } {
+  return {
+    width: Math.round(extent.width / 635),
+    height: Math.round(extent.height / 635),
+  };
+}
+
+function extentTwipsToEmu(
+  extent: { width: number; height: number },
+): { width: number; height: number } {
+  return {
+    width: Math.round(extent.width * 635),
+    height: Math.round(extent.height * 635),
+  };
+}
+
+function collectRelationshipIds(node: XmlElementNode): string[] {
+  const ids = new Set<string>();
+  const visit = (current: XmlElementNode): void => {
+    const id = readRelationshipId(current);
+    if (id) ids.add(id);
+    for (const child of current.children) {
+      if (child.type === "element") visit(child);
+    }
+  };
+  visit(node);
+  return [...ids].sort();
+}
+
+function readRelationshipId(node: XmlElementNode): string | undefined {
+  return (
+    node.attributes["r:id"] ??
+    node.attributes.id ??
+    node.attributes["r:embed"] ??
+    node.attributes.embed ??
+    node.attributes["r:link"] ??
+    node.attributes.link
+  );
+}
+
+function findFirstDescendantByLocalName(
+  node: XmlElementNode,
+  name: string,
+): XmlElementNode | undefined {
+  for (const child of node.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) === name) return child;
+    const nested = findFirstDescendantByLocalName(child, name);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
+function hasDescendant(node: XmlElementNode, name: string): boolean {
+  return findFirstDescendantByLocalName(node, name) !== undefined;
+}
+
+function readIntAttribute(node: XmlElementNode, name: string): number | undefined {
+  const raw = node.attributes[name];
+  if (raw === undefined) return undefined;
+  const value = Number.parseInt(raw, 10);
+  return Number.isFinite(value) ? value : undefined;
+}