@beyondwork/docx-react-component 1.0.29 → 1.0.30

package/src/legal/cross-references.ts

@@ -0,0 +1,414 @@
+import {
+  extractComplexFieldsFromBodyXml,
+  parseFieldsFromParagraphXml,
+} from "../io/ooxml/parse-fields.ts";
+import { parseMainDocumentXml } from "../io/ooxml/parse-main-document.ts";
+import type {
+  CanonicalDocument,
+  DocumentNode,
+  FieldNode,
+  FieldRegistry,
+  HyperlinkNode,
+  ParagraphNode,
+  TocEntry,
+} from "../model/canonical-document.ts";
+
+export interface CrossReferencePattern {
+  kind: "section" | "clause" | "article" | "schedule" | "exhibit" | "appendix";
+  label: string;
+  targetHint: string;
+}
+
+export interface CrossReference {
+  source: "hyperlink" | "field" | "w:ref" | "text-pattern";
+  kind: "bookmark" | "section" | "clause" | "article" | "schedule" | "exhibit" | "appendix";
+  target?: string;
+  instruction?: string;
+  label: string;
+  paragraphIndex?: number;
+  confidence: "high" | "medium";
+}
+
+interface FieldReference {
+  kind: "REF" | "PAGEREF" | "NOTEREF";
+  target: string;
+  instruction: string;
+}
+
+/**
+ * Collect field references from a canonical document, leveraging the
+ * field family classification when available.
+ */
+export function collectFieldReferencesFromCanonicalDocument(
+  document: Pick<CanonicalDocument, "content"> | DocumentNode,
+): Array<{ family: string; target: string; instruction: string; paragraphIndex: number; displayText: string }> {
+  const root = "content" in document ? document.content : document;
+  const results: Array<{ family: string; target: string; instruction: string; paragraphIndex: number; displayText: string }> = [];
+  let paragraphIndex = -1;
+
+  walkDocument(root, (node) => {
+    if (node.type === "paragraph") {
+      paragraphIndex += 1;
+      for (const child of node.children) {
+        if (child.type === "field" && child.fieldFamily && child.fieldTarget) {
+          const family = child.fieldFamily;
+          if (family === "REF" || family === "PAGEREF" || family === "NOTEREF") {
+            results.push({
+              family,
+              target: child.fieldTarget,
+              instruction: child.instruction,
+              paragraphIndex,
+              displayText: flattenInlineText(child.children).trim(),
+            });
+          }
+        }
+      }
+    }
+  });
+
+  return results;
+}
+
+const CROSS_REFERENCE_PATTERN =
+  /\b(Section|Clause|Article|Schedule|Exhibit|Appendix)\s+(\d+(?:\.\d+)*|[A-Z]-\d+|[A-Z])(?=[^A-Za-z0-9]|$)/g;
+const W_REF_PATTERN = /<w:ref\b([^>]*)\/?>/g;
+const ATTRIBUTE_PATTERN = /(?:^|\s)(?:w:)?([A-Za-z][\w-]*)="([^"]*)"/g;
+const COMPLEX_FIELD_PATTERN =
+  /<w:instrText\b[^>]*>([\s\S]*?)<\/w:instrText>[\s\S]*?<w:fldChar\b[^>]*w:fldCharType="separate"[^>]*\/>[\s\S]*?<w:t\b[^>]*>([\s\S]*?)<\/w:t>[\s\S]*?<w:fldChar\b[^>]*w:fldCharType="end"[^>]*\/>/g;
+
+export function parseCrossReferencesFromDocumentXml(xml: string): CrossReference[] {
+  const parsed = parseMainDocumentXml(xml);
+  const results: CrossReference[] = [];
+
+  parsed.blocks.forEach((block, paragraphIndex) => {
+    if (block.type !== "paragraph") {
+      return;
+    }
+
+    for (const child of block.children) {
+      if (child.type === "hyperlink" && child.href.startsWith("#")) {
+        results.push({
+          source: "hyperlink",
+          kind: "bookmark",
+          target: child.href.slice(1),
+          label: flattenInlineText(child.children).trim() || child.href.slice(1),
+          paragraphIndex,
+          confidence: "high",
+        });
+      }
+    }
+
+    const { simpleFields } = parseFieldsFromParagraphXml(block.rawXml);
+    for (const field of simpleFields) {
+      const reference = parseFieldReferenceInstruction(field.instruction);
+      if (!reference) {
+        continue;
+      }
+
+      results.push({
+        source: "field",
+        kind: "bookmark",
+        target: reference.target,
+        instruction: reference.instruction,
+        label: stripXml(field.contentXml) || reference.target,
+        paragraphIndex,
+        confidence: "high",
+      });
+    }
+
+    for (const pattern of detectCrossReferencePatterns(flattenParagraphText(block as unknown as ParagraphNode))) {
+      results.push({
+        source: "text-pattern",
+        kind: pattern.kind,
+        target: pattern.targetHint,
+        label: pattern.label,
+        paragraphIndex,
+        confidence: "medium",
+      });
+    }
+  });
+
+  for (const field of extractComplexFieldsFromBodyXml(xml)) {
+    const reference = parseFieldReferenceInstruction(field.instruction);
+    if (!reference) {
+      continue;
+    }
+    results.push({
+      source: "field",
+      kind: "bookmark",
+      target: reference.target,
+      instruction: reference.instruction,
+      label: stripXml(field.contentXml) || reference.target,
+      confidence: "high",
+    });
+  }
+
+  for (const field of extractComplexFieldsWithRegex(xml)) {
+    const reference = parseFieldReferenceInstruction(field.instruction);
+    if (!reference) {
+      continue;
+    }
+
+    results.push({
+      source: "field",
+      kind: "bookmark",
+      target: reference.target,
+      instruction: reference.instruction,
+      label: field.label || reference.target,
+      confidence: "high",
+    });
+  }
+
+  for (const element of extractWRefElements(xml)) {
+    results.push({
+      source: "w:ref",
+      kind: "bookmark",
+      target: element.target,
+      label: element.label || element.target || "w:ref",
+      confidence: element.target ? "high" : "medium",
+    });
+  }
+
+  return dedupeCrossReferences(results);
+}
+
+export function collectCrossReferencesFromCanonicalDocument(
+  document: Pick<CanonicalDocument, "content"> | DocumentNode,
+): CrossReference[] {
+  const root = "content" in document ? document.content : document;
+  const results: CrossReference[] = [];
+  let paragraphIndex = -1;
+
+  walkDocument(root, (node) => {
+    if (node.type === "paragraph") {
+      paragraphIndex += 1;
+      for (const child of node.children) {
+        if (child.type === "hyperlink" && child.href.startsWith("#")) {
+          results.push({
+            source: "hyperlink",
+            kind: "bookmark",
+            target: child.href.slice(1),
+            label: flattenInlineText(child.children).trim() || child.href.slice(1),
+            paragraphIndex,
+            confidence: "high",
+          });
+          continue;
+        }
+
+        if (child.type === "field") {
+          const reference = parseFieldReferenceInstruction(child.instruction);
+          if (!reference) {
+            continue;
+          }
+          results.push({
+            source: "field",
+            kind: "bookmark",
+            target: reference.target,
+            instruction: reference.instruction,
+            label: flattenInlineText(child.children).trim() || reference.target,
+            paragraphIndex,
+            confidence: "high",
+          });
+        }
+      }
+
+      for (const pattern of detectCrossReferencePatterns(flattenParagraphText(node))) {
+        results.push({
+          source: "text-pattern",
+          kind: pattern.kind,
+          target: pattern.targetHint,
+          label: pattern.label,
+          paragraphIndex,
+          confidence: "medium",
+        });
+      }
+    }
+  });
+
+  return dedupeCrossReferences(results);
+}
+
+export function detectCrossReferencePatterns(text: string): CrossReferencePattern[] {
+  const matches: CrossReferencePattern[] = [];
+
+  for (const match of text.matchAll(CROSS_REFERENCE_PATTERN)) {
+    const referenceType = match[1]?.toLowerCase();
+    const target = match[2];
+    const label = `${match[1]} ${target}`.trim();
+
+    if (!referenceType || !target) {
+      continue;
+    }
+
+    matches.push({
+      kind: referenceType as CrossReferencePattern["kind"],
+      label,
+      targetHint: target,
+    });
+  }
+
+  return matches;
+}
+
+export function parseFieldReferenceInstruction(instruction: string): FieldReference | undefined {
+  const trimmedInstruction = instruction.trim().replace(/\s+/g, " ");
+  const match = /^(REF|PAGEREF|NOTEREF)\s+(?:"([^"]+)"|([^\s\\]+))/i.exec(trimmedInstruction);
+  if (!match) {
+    return undefined;
+  }
+
+  return {
+    kind: match[1].toUpperCase() as FieldReference["kind"],
+    target: (match[2] ?? match[3] ?? "").trim(),
+    instruction: trimmedInstruction,
+  };
+}
+
+function extractWRefElements(xml: string): Array<{ target?: string; label?: string }> {
+  const matches: Array<{ target?: string; label?: string }> = [];
+
+  for (const match of xml.matchAll(W_REF_PATTERN)) {
+    const attributes = readAttributes(match[1] ?? "");
+    matches.push({
+      target: attributes.anchor ?? attributes.name ?? attributes.id,
+      label: attributes.displayText ?? attributes.text,
+    });
+  }
+
+  return matches;
+}
+
+function extractComplexFieldsWithRegex(xml: string): Array<{ instruction: string; label: string }> {
+  const matches: Array<{ instruction: string; label: string }> = [];
+
+  for (const match of xml.matchAll(COMPLEX_FIELD_PATTERN)) {
+    const instruction = stripXml(match[1] ?? "");
+    const label = stripXml(match[2] ?? "");
+    if (!instruction) {
+      continue;
+    }
+    matches.push({ instruction, label });
+  }
+
+  return matches;
+}
+
+function readAttributes(source: string): Record<string, string> {
+  const attributes: Record<string, string> = {};
+
+  for (const match of source.matchAll(ATTRIBUTE_PATTERN)) {
+    const [, key, value] = match;
+    attributes[key] = value;
+  }
+
+  return attributes;
+}
+
+function stripXml(xml: string): string {
+  return xml.replace(/<[^>]+>/g, "").replace(/\s+/g, " ").trim();
+}
+
+function flattenParagraphText(paragraph: ParagraphNode): string {
+  return paragraph.children
+    .map((child) => {
+      switch (child.type) {
+        case "text":
+          return child.text;
+        case "hyperlink":
+          return flattenInlineText(child.children);
+        case "field":
+          return child.children ? flattenInlineText(child.children) : "";
+        case "tab":
+          return "\t";
+        case "hard_break":
+        case "column_break":
+          return "\n";
+        default:
+          return "";
+      }
+    })
+    .join("");
+}
+
+function flattenInlineText(children: HyperlinkNode["children"] | FieldNode["children"]): string {
+  return children
+    .map((child) => {
+      if (child.type === "text") {
+        return child.text;
+      }
+      if (child.type === "tab") {
+        return "\t";
+      }
+      if (child.type === "hard_break" || child.type === "column_break") {
+        return "\n";
+      }
+      return "";
+    })
+    .join("");
+}
+
+function dedupeCrossReferences(references: CrossReference[]): CrossReference[] {
+  const seen = new Set<string>();
+  const deduped: CrossReference[] = [];
+
+  for (const reference of references) {
+    const key = [
+      reference.source,
+      reference.kind,
+      reference.target ?? "",
+      reference.label,
+      String(reference.paragraphIndex ?? -1),
+    ].join("|");
+
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    deduped.push(reference);
+  }
+
+  return deduped;
+}
+
+/**
+ * Collect TOC entries from a field registry's tocStructure.
+ * Returns the entries in document order with their heading text and levels.
+ * Returns an empty array if no TOC structure is available.
+ */
+export function collectTocEntriesFromRegistry(
+  registry: FieldRegistry | undefined,
+): TocEntry[] {
+  return registry?.tocStructure?.entries ?? [];
+}
+
+/**
+ * Assess whether the TOC structure in a field registry is current
+ * with respect to the document's heading structure.
+ */
+export function assessTocFreshness(
+  registry: FieldRegistry | undefined,
+): "current" | "stale" | "absent" {
+  if (!registry?.tocStructure) return "absent";
+  return registry.tocStructure.status;
+}
+
+function walkDocument(node: DocumentNode, visit: (node: DocumentNode) => void): void {
+  visit(node);
+
+  if ("children" in node && Array.isArray(node.children)) {
+    for (const child of node.children) {
+      walkDocument(child, visit);
+    }
+  }
+
+  if (node.type === "table") {
+    for (const row of node.rows) {
+      walkDocument(row, visit);
+    }
+  } else if (node.type === "table_row") {
+    for (const cell of node.cells) {
+      walkDocument(cell, visit);
+    }
+  }
+}

package/src/legal/defined-terms.ts

@@ -0,0 +1,203 @@
+import { parseMainDocumentXml } from "../io/ooxml/parse-main-document.ts";
+import type {
+  CanonicalDocument,
+  DocumentNode,
+  ParagraphNode,
+} from "../model/canonical-document.ts";
+
+export interface DefinedTermOccurrence {
+  paragraphIndex: number;
+  label: string;
+  kind: "definition" | "reference";
+}
+
+export interface DefinedTerm {
+  term: string;
+  normalizedTerm: string;
+  definitionStyle: "quoted" | "bare";
+  definitions: DefinedTermOccurrence[];
+  references: DefinedTermOccurrence[];
+}
+
+const QUOTED_DEFINITION_PATTERN =
+  /["“]([A-Z][A-Za-z0-9]*(?:[ -][A-Z][A-Za-z0-9]*){0,5})["”]\s+(?:means|has the meaning(?: set forth)?|shall mean|refers to)\b/g;
+const BARE_DEFINITION_PATTERN =
+  /\b([A-Z][A-Za-z0-9]*(?:\s+[A-Z][A-Za-z0-9]*){0,5})\s+(?:means|has the meaning(?: set forth)?|shall mean|refers to)\b/g;
+const BLOCKED_BARE_TERMS = new Set([
+  "This Agreement",
+  "Such Term",
+  "The Company",
+  "This Section",
+  "This Clause",
+]);
+
+export function collectDefinedTermsFromDocumentXml(xml: string): DefinedTerm[] {
+  const parsed = parseMainDocumentXml(xml);
+  const paragraphs = parsed.blocks
+    .filter((block): block is typeof parsed.blocks[number] & { type: "paragraph" } => block.type === "paragraph")
+    .map((block) => flattenParagraphText(block as unknown as ParagraphNode));
+
+  return buildDefinedTermCatalog(paragraphs);
+}
+
+export function collectDefinedTermsFromCanonicalDocument(
+  document: Pick<CanonicalDocument, "content"> | DocumentNode,
+): DefinedTerm[] {
+  const root = "content" in document ? document.content : document;
+  const paragraphs: string[] = [];
+
+  walkDocument(root, (node) => {
+    if (node.type === "paragraph") {
+      paragraphs.push(flattenParagraphText(node));
+    }
+  });
+
+  return buildDefinedTermCatalog(paragraphs);
+}
+
+export function buildDefinedTermCatalog(paragraphs: readonly string[]): DefinedTerm[] {
+  const terms = new Map<string, DefinedTerm>();
+
+  paragraphs.forEach((paragraph, paragraphIndex) => {
+    for (const candidate of extractDefinitionCandidates(paragraph)) {
+      const normalized = normalizeTerm(candidate.term);
+      const existing = terms.get(normalized) ?? {
+        term: candidate.term,
+        normalizedTerm: normalized,
+        definitionStyle: candidate.definitionStyle,
+        definitions: [],
+        references: [],
+      };
+
+      if (!terms.has(normalized)) {
+        terms.set(normalized, existing);
+      }
+
+      existing.definitions.push({
+        paragraphIndex,
+        label: candidate.term,
+        kind: "definition",
+      });
+    }
+  });
+
+  paragraphs.forEach((paragraph, paragraphIndex) => {
+    for (const term of terms.values()) {
+      const references = findTermReferences(paragraph, term.term);
+      if (references === 0) {
+        continue;
+      }
+
+      const hasDefinitionInParagraph = term.definitions.some(
+        (definition) => definition.paragraphIndex === paragraphIndex,
+      );
+      const referenceCount = hasDefinitionInParagraph ? 0 : references;
+
+      for (let count = 0; count < referenceCount; count += 1) {
+        term.references.push({
+          paragraphIndex,
+          label: term.term,
+          kind: "reference",
+        });
+      }
+    }
+  });
+
+  return Array.from(terms.values()).sort((left, right) => left.term.localeCompare(right.term));
+}
+
+interface DefinitionCandidate {
+  term: string;
+  definitionStyle: DefinedTerm["definitionStyle"];
+}
+
+function extractDefinitionCandidates(paragraph: string): DefinitionCandidate[] {
+  const candidates: DefinitionCandidate[] = [];
+
+  for (const match of paragraph.matchAll(QUOTED_DEFINITION_PATTERN)) {
+    const term = match[1]?.trim();
+    if (!term) {
+      continue;
+    }
+
+    candidates.push({
+      term,
+      definitionStyle: "quoted",
+    });
+  }
+
+  for (const match of paragraph.matchAll(BARE_DEFINITION_PATTERN)) {
+    const term = match[1]?.trim();
+    if (!term || BLOCKED_BARE_TERMS.has(term) || isQuotedTerm(term, paragraph)) {
+      continue;
+    }
+
+    candidates.push({
+      term,
+      definitionStyle: "bare",
+    });
+  }
+
+  return candidates;
+}
+
+function normalizeTerm(term: string): string {
+  return term.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+function isQuotedTerm(term: string, paragraph: string): boolean {
+  return paragraph.includes(`"${term}"`) || paragraph.includes(`“${term}”`);
+}
+
+function findTermReferences(paragraph: string, term: string): number {
+  const escapedTerm = escapeRegExp(term);
+  const pattern = new RegExp(`(?:^|[^A-Za-z0-9])(?:\"|“)?(${escapedTerm})(?:\"|”)?(?=[^A-Za-z0-9]|$)`, "g");
+  return Array.from(paragraph.matchAll(pattern)).length;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function flattenParagraphText(paragraph: ParagraphNode): string {
+  return paragraph.children
+    .map((child) => {
+      switch (child.type) {
+        case "text":
+          return child.text;
+        case "hyperlink":
+        case "field":
+          return child.children
+            .map((nested) => (nested.type === "text" ? nested.text : nested.type === "tab" ? "\t" : ""))
+            .join("");
+        case "tab":
+          return "\t";
+        case "hard_break":
+        case "column_break":
+          return "\n";
+        default:
+          return "";
+      }
+    })
+    .join("");
+}
+
+function walkDocument(node: DocumentNode, visit: (node: DocumentNode) => void): void {
+  visit(node);
+
+  if ("children" in node && Array.isArray(node.children)) {
+    for (const child of node.children) {
+      walkDocument(child, visit);
+    }
+  }
+
+  if (node.type === "table") {
+    for (const row of node.rows) {
+      walkDocument(row, visit);
+    }
+  } else if (node.type === "table_row") {
+    for (const cell of node.cells) {
+      walkDocument(cell, visit);
+    }
+  }
+}

package/src/legal/index.ts

@@ -0,0 +1,32 @@
+export {
+  parseBookmarksFromDocumentXml,
+  collectBookmarksFromCanonicalDocument,
+  assessBookmarkIntegrity,
+  isHiddenBookmarkName,
+  type BookmarkIntegrityResult,
+  type LegalBookmark,
+} from "./bookmarks.ts";
+
+export {
+  parseCrossReferencesFromDocumentXml,
+  collectCrossReferencesFromCanonicalDocument,
+  detectCrossReferencePatterns,
+  parseFieldReferenceInstruction,
+  type CrossReference,
+  type CrossReferencePattern,
+} from "./cross-references.ts";
+
+export {
+  collectDefinedTermsFromDocumentXml,
+  collectDefinedTermsFromCanonicalDocument,
+  buildDefinedTermCatalog,
+  type DefinedTerm,
+  type DefinedTermOccurrence,
+} from "./defined-terms.ts";
+
+export {
+  detectSignatureBlocksFromCanonicalDocument,
+  type SignatureBlockCandidate,
+  type SignatureBlockReport,
+  type SignatureParty,
+} from "./signature-blocks.ts";