@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/runtime/scopes/enumerate-scopes.ts

@@ -0,0 +1,543 @@
+/**
+ * Slice 1+2 enumeration — walks the canonical document and yields one
+ * `EnumeratedScope` per paragraph, heading, list-item, table, table-row,
+ * table-cell, field, comment-thread, or revision.
+ *
+ * ## Generic substrate (post 2026-04-22 taxonomy-genericization pass)
+ *
+ * The compiler does NOT carry any vertical vocabulary in its kind
+ * taxonomy. A paragraph that a host has wrapped in a marker-backed
+ * overlay scope (for example a CLM clause marker) stays `kind:
+ * "paragraph"` — but its `provenance` is `"marker-backed"` and the
+ * compiler propagates the overlay's metadata as generic `classifications`
+ * on the compiled scope. Hosts read classifications to drive
+ * vertical behaviour (CLM legal clause treatment, compliance
+ * annotations, etc.) without the compiler encoding that vocabulary.
+ *
+ * See `docs/wiki/use-case-domains/clm/semantic-scope-usage.md` for the
+ * CLM worked example.
+ *
+ * S3 (determinism): for identical inputs this function yields an
+ * identical handle sequence. Handle ids derive from structural position;
+ * no ambient state, no timestamps, no random ids.
+ */
+
+import type {
+  CanonicalDocument,
+  CommentThread,
+  DocumentRootNode,
+  FieldNode,
+  InlineNode,
+  ParagraphNode,
+  RevisionRecord,
+  TableCellNode,
+  TableNode,
+  TableRowNode,
+} from "../../model/canonical-document.ts";
+import {
+  buildParagraphScopeId,
+  detectParagraphKind,
+} from "../../model/paragraph-scope-ids.ts";
+export {
+  buildParagraphScopeId,
+  detectParagraphKind,
+} from "../../model/paragraph-scope-ids.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type {
+  WorkflowOverlay,
+  WorkflowScope,
+  WorkflowScopeMetadataField,
+} from "./_scope-dependencies.ts";
+
+import type { ScopeHandle, SemanticScopeKind } from "./semantic-scope-types.ts";
+
+const MAIN_STORY = { kind: "main" as const };
+
+/**
+ * Paragraph-bearing variant — paragraph / heading / list-item.
+ *
+ * Classifications are collected from the overlay scope the paragraph
+ * belongs to (if marker-backed). Empty array when no overlay match.
+ */
+export interface ParagraphLikeEnumeratedScope {
+  readonly kind: "paragraph" | "heading" | "list-item";
+  readonly handle: ScopeHandle;
+  readonly paragraph: ParagraphNode;
+  readonly blockIndex: number;
+  readonly classifications: readonly string[];
+}
+
+export interface TableEnumeratedScope {
+  readonly kind: "table";
+  readonly handle: ScopeHandle;
+  readonly table: TableNode;
+  readonly blockIndex: number;
+  readonly classifications: readonly string[];
+}
+
+export interface TableRowEnumeratedScope {
+  readonly kind: "table-row";
+  readonly handle: ScopeHandle;
+  readonly row: TableRowNode;
+  readonly table: TableNode;
+  readonly blockIndex: number;
+  readonly rowIndex: number;
+  readonly classifications: readonly string[];
+}
+
+export interface TableCellEnumeratedScope {
+  readonly kind: "table-cell";
+  readonly handle: ScopeHandle;
+  readonly cell: TableCellNode;
+  readonly row: TableRowNode;
+  readonly table: TableNode;
+  readonly blockIndex: number;
+  readonly rowIndex: number;
+  readonly cellIndex: number;
+  readonly classifications: readonly string[];
+}
+
+export interface FieldEnumeratedScope {
+  readonly kind: "field";
+  readonly handle: ScopeHandle;
+  readonly field: FieldNode;
+  readonly paragraph: ParagraphNode;
+  readonly blockIndex: number;
+  readonly inlineIndex: number;
+  readonly classifications: readonly string[];
+}
+
+export interface CommentThreadEnumeratedScope {
+  readonly kind: "comment-thread";
+  readonly handle: ScopeHandle;
+  readonly thread: CommentThread;
+  readonly classifications: readonly string[];
+}
+
+export interface RevisionEnumeratedScope {
+  readonly kind: "revision";
+  readonly handle: ScopeHandle;
+  readonly revision: RevisionRecord;
+  readonly classifications: readonly string[];
+}
+
+/**
+ * Discriminated by `kind`. Paragraph-bearing entries carry `paragraph`;
+ * table-bearing entries carry the matching canonical node; field entries
+ * carry the inline `FieldNode` + containing paragraph; review-store
+ * entries carry the thread / revision record directly.
+ */
+export type EnumeratedScope =
+  | ParagraphLikeEnumeratedScope
+  | TableEnumeratedScope
+  | TableRowEnumeratedScope
+  | TableCellEnumeratedScope
+  | FieldEnumeratedScope
+  | CommentThreadEnumeratedScope
+  | RevisionEnumeratedScope;
+
+export interface EnumerateScopesInputs {
+  readonly overlay?: WorkflowOverlay | null;
+}
+
+function buildParagraphSemanticPath(
+  kind: "paragraph" | "heading" | "list-item",
+  blockIndex: number,
+  paragraph: ParagraphNode,
+): readonly string[] {
+  switch (kind) {
+    case "heading":
+      return [
+        "body",
+        "heading",
+        String(paragraph.outlineLevel ?? 0),
+        String(blockIndex),
+      ];
+    case "list-item":
+      return [
+        "body",
+        "list-item",
+        paragraph.numbering?.numberingInstanceId ?? "unknown",
+        String(paragraph.numbering?.level ?? 0),
+        String(blockIndex),
+      ];
+    case "paragraph":
+    default:
+      return ["body", "paragraph", String(blockIndex)];
+  }
+}
+
+function buildHandle(
+  scopeId: string,
+  documentId: string,
+  semanticPath: readonly string[],
+  provenance: ScopeHandle["provenance"],
+  rangePrecision: ScopeHandle["rangePrecision"],
+  parentScopeId?: string,
+  stableRef?: ScopeHandle["stableRef"],
+): ScopeHandle {
+  return {
+    scopeId,
+    documentId,
+    storyTarget: MAIN_STORY,
+    semanticPath,
+    ...(parentScopeId !== undefined ? { parentScopeId } : {}),
+    stableRef: stableRef ?? {
+      kind: "semantic-path",
+      value: semanticPath.join("/"),
+    },
+    provenance,
+    ...(rangePrecision ? { rangePrecision } : {}),
+  };
+}
+
+/**
+ * Collect generic classification tags from a workflow overlay scope.
+ * The compiler does NOT interpret these strings — it surfaces them
+ * verbatim. Hosts define the vocabulary: CLM hosts use `"clause"`,
+ * `"domain:legal"`, `"label:Liability"`; compliance hosts may use
+ * `"issue"`, `"severity:high"`; etc.
+ *
+ * Grammar (convention, not enforced):
+ *   - bare strings (`"clause"`, `"issue"`) for primary classifications
+ *   - `key:value` pairs (`"domain:legal"`, `"label:Liability"`) for
+ *     structured metadata
+ *
+ * Order is stable: `kind` field first (if present), then `domain`,
+ * then `label`, then remaining metadata keys sorted alphabetically.
+ * This keeps classification arrays byte-stable across compiles for
+ * identical inputs (S3 determinism).
+ */
+function classificationsFromOverlayScope(
+  scope: WorkflowScope,
+): readonly string[] {
+  const tags: string[] = [];
+  const metadata = scope.metadata ?? [];
+
+  const kindField = metadata.find(
+    (f: WorkflowScopeMetadataField) => f.key === "kind",
+  );
+  if (kindField && typeof kindField.value === "string") {
+    tags.push(kindField.value);
+  }
+  if (typeof scope.domain === "string" && scope.domain.length > 0) {
+    tags.push(`domain:${scope.domain}`);
+  }
+  if (typeof scope.label === "string" && scope.label.length > 0) {
+    tags.push(`label:${scope.label}`);
+  }
+  const remaining = metadata
+    .filter(
+      (f: WorkflowScopeMetadataField) =>
+        f.key !== "kind" && typeof f.value === "string",
+    )
+    .sort((a, b) => a.key.localeCompare(b.key));
+  for (const field of remaining) {
+    if (typeof field.value === "string") {
+      tags.push(`${field.key}:${field.value}`);
+    }
+  }
+  return Object.freeze(tags);
+}
+
+/**
+ * For each marker-backed overlay scope, map scopeId → classifications.
+ * Built once per enumeration; reused across every paragraph / table /
+ * row / cell that might be marker-backed by one of these scopes.
+ */
+function buildClassificationIndex(
+  overlay: WorkflowOverlay | null | undefined,
+): Map<string, readonly string[]> {
+  const out = new Map<string, readonly string[]>();
+  if (!overlay) return out;
+  for (const scope of overlay.scopes as readonly WorkflowScope[]) {
+    out.set(scope.scopeId, classificationsFromOverlayScope(scope));
+  }
+  return out;
+}
+
+/**
+ * Walk paragraph children and return the first scope-marker id that
+ * *starts* inside the paragraph. When a paragraph carries multiple
+ * nested marker starts, the outermost structural interpretation is the
+ * first start marker — consistent with OOXML document order.
+ *
+ * Hosts that need richer multi-marker semantics should compose
+ * `classifications` from the matching overlay scope themselves.
+ */
+function paragraphFirstMarkerStart(
+  paragraph: ParagraphNode,
+  knownScopeIds: ReadonlySet<string>,
+): string | null {
+  if (knownScopeIds.size === 0) return null;
+  for (const child of paragraph.children) {
+    if (
+      child.type === "scope_marker_start" &&
+      knownScopeIds.has(child.scopeId)
+    ) {
+      return child.scopeId;
+    }
+  }
+  return null;
+}
+
+function enumerateFieldsInParagraph(
+  paragraph: ParagraphNode,
+  blockIndex: number,
+  documentId: string,
+  parentScopeId: string,
+): FieldEnumeratedScope[] {
+  const out: FieldEnumeratedScope[] = [];
+  for (let i = 0; i < paragraph.children.length; i += 1) {
+    const child = paragraph.children[i] as InlineNode;
+    if (child.type !== "field") continue;
+    const semanticPath = [
+      "body",
+      "paragraph",
+      String(blockIndex),
+      "field",
+      String(i),
+    ];
+    const scopeId = `field:${blockIndex}:${i}`;
+    const handle: ScopeHandle = {
+      scopeId,
+      documentId,
+      storyTarget: MAIN_STORY,
+      semanticPath,
+      parentScopeId,
+      stableRef: { kind: "semantic-path", value: semanticPath.join("/") },
+      provenance: "derived",
+      rangePrecision: "canonical",
+    };
+    out.push({
+      kind: "field",
+      handle,
+      field: child,
+      paragraph,
+      blockIndex,
+      inlineIndex: i,
+      classifications: Object.freeze<string[]>([]),
+    });
+  }
+  return out;
+}
+
+function enumerateCommentThreads(
+  document: Pick<CanonicalDocument, "review"> | CanonicalDocumentEnvelope,
+  documentId: string,
+): CommentThreadEnumeratedScope[] {
+  const review = (document as { review?: { comments?: Record<string, CommentThread> } }).review;
+  const comments = review?.comments;
+  if (!comments) return [];
+  const entries = Object.values(comments);
+  entries.sort((a, b) => a.commentId.localeCompare(b.commentId));
+  return entries.map((thread) => {
+    const semanticPath = ["review", "comment-thread", thread.commentId];
+    const provenance: ScopeHandle["provenance"] =
+      thread.anchor.kind === "detached" ? "detached" : "marker-backed";
+    const handle: ScopeHandle = {
+      scopeId: thread.commentId,
+      documentId,
+      storyTarget: MAIN_STORY,
+      semanticPath,
+      stableRef: { kind: "scope-id", value: thread.commentId },
+      provenance,
+      rangePrecision: "marker-backed",
+    };
+    return {
+      kind: "comment-thread",
+      handle,
+      thread,
+      classifications: Object.freeze<string[]>([]),
+    } as CommentThreadEnumeratedScope;
+  });
+}
+
+function enumerateRevisions(
+  document: Pick<CanonicalDocument, "review"> | CanonicalDocumentEnvelope,
+  documentId: string,
+): RevisionEnumeratedScope[] {
+  const review = (document as { review?: { revisions?: Record<string, RevisionRecord> } }).review;
+  const revisions = review?.revisions;
+  if (!revisions) return [];
+  const entries = Object.values(revisions);
+  entries.sort((a, b) => a.changeId.localeCompare(b.changeId));
+  return entries.map((revision) => {
+    const semanticPath = ["review", "revision", revision.changeId];
+    const provenance: ScopeHandle["provenance"] =
+      revision.anchor.kind === "detached" ? "detached" : "marker-backed";
+    const handle: ScopeHandle = {
+      scopeId: revision.changeId,
+      documentId,
+      storyTarget: MAIN_STORY,
+      semanticPath,
+      stableRef: { kind: "scope-id", value: revision.changeId },
+      provenance,
+      rangePrecision: "marker-backed",
+    };
+    return {
+      kind: "revision",
+      handle,
+      revision,
+      classifications: Object.freeze<string[]>([]),
+    } as RevisionEnumeratedScope;
+  });
+}
+
+export function enumerateScopes(
+  document: Pick<CanonicalDocument, "content" | "docId" | "review"> | CanonicalDocumentEnvelope,
+  inputs: EnumerateScopesInputs = {},
+): EnumeratedScope[] {
+  const envelope = document as CanonicalDocumentEnvelope;
+  const root: DocumentRootNode =
+    "content" in envelope
+      ? (envelope.content as DocumentRootNode)
+      : (document as unknown as DocumentRootNode);
+  const documentId = (envelope.docId as unknown as string) ?? "";
+  const classificationIndex = buildClassificationIndex(inputs.overlay);
+  const knownOverlayScopeIds = new Set(classificationIndex.keys());
+
+  const results: EnumeratedScope[] = [];
+  for (let index = 0; index < root.children.length; index += 1) {
+    const block = root.children[index];
+    if (!block) continue;
+
+    if (block.type === "paragraph") {
+      const markerScopeId = paragraphFirstMarkerStart(
+        block,
+        knownOverlayScopeIds,
+      );
+      const kind = detectParagraphKind(block);
+      const semanticPath = buildParagraphSemanticPath(kind, index, block);
+      const scopeId =
+        markerScopeId !== null
+          ? markerScopeId
+          : buildParagraphScopeId(kind, index, block);
+      const provenance: ScopeHandle["provenance"] =
+        markerScopeId !== null ? "marker-backed" : "derived";
+      const rangePrecision: ScopeHandle["rangePrecision"] =
+        markerScopeId !== null ? "marker-backed" : "canonical";
+      const handle = buildHandle(
+        scopeId,
+        documentId,
+        semanticPath,
+        provenance,
+        rangePrecision,
+        undefined,
+        markerScopeId !== null
+          ? { kind: "scope-id", value: markerScopeId }
+          : undefined,
+      );
+      const classifications =
+        markerScopeId !== null
+          ? (classificationIndex.get(markerScopeId) ?? Object.freeze<string[]>([]))
+          : Object.freeze<string[]>([]);
+      results.push({
+        kind,
+        handle,
+        paragraph: block,
+        blockIndex: index,
+        classifications,
+      });
+      // Fields inside this paragraph carry the paragraph's real scopeId
+      // as their parent — NOT a hardcoded `para:${index}`, which would
+      // be wrong whenever the paragraph upgraded to heading / list-item.
+      const fields = enumerateFieldsInParagraph(block, index, documentId, scopeId);
+      for (const field of fields) results.push(field);
+      continue;
+    }
+
+    if (block.type === "table") {
+      const tableSemanticPath = ["body", "table", String(index)];
+      const tableScopeId = `table:${index}`;
+      const tableHandle = buildHandle(
+        tableScopeId,
+        documentId,
+        tableSemanticPath,
+        "derived",
+        "canonical",
+      );
+      results.push({
+        kind: "table",
+        handle: tableHandle,
+        table: block,
+        blockIndex: index,
+        classifications: Object.freeze<string[]>([]),
+      });
+
+      for (let rowIdx = 0; rowIdx < block.rows.length; rowIdx += 1) {
+        const row = block.rows[rowIdx]!;
+        const rowSemanticPath = [
+          "body",
+          "table",
+          String(index),
+          "row",
+          String(rowIdx),
+        ];
+        const rowScopeId = `row:${index}:${rowIdx}`;
+        const rowHandle = buildHandle(
+          rowScopeId,
+          documentId,
+          rowSemanticPath,
+          "derived",
+          "synthetic",
+          tableScopeId,
+        );
+        results.push({
+          kind: "table-row",
+          handle: rowHandle,
+          row,
+          table: block,
+          blockIndex: index,
+          rowIndex: rowIdx,
+          classifications: Object.freeze<string[]>([]),
+        });
+
+        for (let cellIdx = 0; cellIdx < row.cells.length; cellIdx += 1) {
+          const cell = row.cells[cellIdx]!;
+          const cellSemanticPath = [
+            "body",
+            "table",
+            String(index),
+            "row",
+            String(rowIdx),
+            "cell",
+            String(cellIdx),
+          ];
+          const cellScopeId = `cell:${index}:${rowIdx}:${cellIdx}`;
+          const cellHandle = buildHandle(
+            cellScopeId,
+            documentId,
+            cellSemanticPath,
+            "derived",
+            "synthetic",
+            rowScopeId,
+          );
+          results.push({
+            kind: "table-cell",
+            handle: cellHandle,
+            cell,
+            row,
+            table: block,
+            blockIndex: index,
+            rowIndex: rowIdx,
+            cellIndex: cellIdx,
+            classifications: Object.freeze<string[]>([]),
+          });
+        }
+      }
+    }
+  }
+
+  // Review-store scopes — threads + revisions — enumerate after document
+  // walk so their block ordering in `results` stays stable (all block scopes
+  // first, then review).
+  for (const thread of enumerateCommentThreads(document, documentId)) {
+    results.push(thread);
+  }
+  for (const revision of enumerateRevisions(document, documentId)) {
+    results.push(revision);
+  }
+
+  return results;
+}