@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/runtime/scopes/resolve-reference.ts

@@ -0,0 +1,347 @@
+/**
+ * Slice 3 — reference resolution.
+ *
+ * Takes an agent-supplied `ScopeReference` hint + a live document and
+ * returns either a resolved `ScopeHandle`, a list of candidate handles
+ * (ambiguous), a detached placeholder (scopeId was once valid), or a
+ * `not-found`.
+ *
+ * Deterministic hint kinds — `scope-id`, `semantic-path`, `offset`,
+ * `range` — all resolve live today. Natural-language hints return a
+ * `partial` result with `confidence: "low"`; a richer NL matcher lives
+ * in a later slice (the AI API will keep the function at status
+ * `partial` until then).
+ */
+
+import type { CanonicalDocument } from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type { WorkflowOverlay } from "./_scope-dependencies.ts";
+
+import type { EnumeratedScope } from "./enumerate-scopes.ts";
+import { enumerateScopes } from "./enumerate-scopes.ts";
+import { buildScopePositionMap, type ScopePositionRange } from "./position-map.ts";
+import { resolveScopeRange, scopeSpecificity } from "./scope-range.ts";
+import type { ScopeHandle } from "./semantic-scope-types.ts";
+
+export type ScopeReference =
+  | { readonly kind: "scope-id"; readonly value: string }
+  | { readonly kind: "semantic-path"; readonly path: readonly string[] }
+  | { readonly kind: "offset"; readonly at: number }
+  | { readonly kind: "range"; readonly from: number; readonly to: number }
+  | { readonly kind: "natural-language"; readonly hint: string };
+
+export type ResolveReferenceResult =
+  | {
+      readonly status: "resolved";
+      readonly handle: ScopeHandle;
+      readonly confidence: "high" | "medium" | "low";
+    }
+  | {
+      readonly status: "ambiguous";
+      readonly candidates: readonly ScopeHandle[];
+    }
+  | {
+      readonly status: "detached";
+      readonly scopeId: string;
+      readonly lastKnownRange?: ScopePositionRange;
+      readonly reason: string;
+    }
+  | {
+      readonly status: "not-found";
+      readonly reason: string;
+    };
+
+export interface ResolveReferenceInputs {
+  readonly document: Pick<CanonicalDocument, "content" | "docId" | "review"> | CanonicalDocumentEnvelope;
+  readonly overlay?: WorkflowOverlay | null;
+  /** Pre-enumerated scopes; computed when absent. */
+  readonly scopes?: readonly EnumeratedScope[];
+}
+
+function scopesFor(inputs: ResolveReferenceInputs): readonly EnumeratedScope[] {
+  if (inputs.scopes) return inputs.scopes;
+  return enumerateScopes(inputs.document, { overlay: inputs.overlay ?? null });
+}
+
+function rangeForScope(
+  handle: ScopeHandle,
+  entry: EnumeratedScope,
+  positionMap: ReturnType<typeof buildScopePositionMap>,
+): ScopePositionRange | undefined {
+  const range = resolveScopeRange(entry, handle, positionMap);
+  return range ?? undefined;
+}
+
+function resolveByScopeId(
+  value: string,
+  scopes: readonly EnumeratedScope[],
+  overlay: WorkflowOverlay | null | undefined,
+  positionMap: ReturnType<typeof buildScopePositionMap>,
+): ResolveReferenceResult {
+  const match = scopes.find((s) => s.handle.scopeId === value);
+  if (match) {
+    return { status: "resolved", handle: match.handle, confidence: "high" };
+  }
+  // Overlay may know a detached scope not present in the canonical walk.
+  if (overlay?.scopes?.some((s) => s.scopeId === value)) {
+    const lastKnownRange = positionMap.markerScopes.get(value);
+    return {
+      status: "detached",
+      scopeId: value,
+      lastKnownRange,
+      reason: "scope-id known to overlay but absent from canonical walk",
+    };
+  }
+  return { status: "not-found", reason: `no scope with id "${value}"` };
+}
+
+function resolveBySemanticPath(
+  path: readonly string[],
+  scopes: readonly EnumeratedScope[],
+): ResolveReferenceResult {
+  const wanted = path.join("/");
+  const matches = scopes.filter(
+    (s) => s.handle.semanticPath.join("/") === wanted,
+  );
+  if (matches.length === 1) {
+    return { status: "resolved", handle: matches[0]!.handle, confidence: "high" };
+  }
+  if (matches.length > 1) {
+    return { status: "ambiguous", candidates: matches.map((m) => m.handle) };
+  }
+  return {
+    status: "not-found",
+    reason: `no scope at semantic-path "${wanted}"`,
+  };
+}
+
+function innermostContaining(
+  scopes: readonly EnumeratedScope[],
+  positionMap: ReturnType<typeof buildScopePositionMap>,
+  predicate: (range: ScopePositionRange) => boolean,
+): EnumeratedScope | null {
+  let best: {
+    entry: EnumeratedScope;
+    range: ScopePositionRange;
+    specificity: number;
+  } | null = null;
+  for (const entry of scopes) {
+    const range = rangeForScope(entry.handle, entry, positionMap);
+    if (!range) continue;
+    if (!predicate(range)) continue;
+    const specificity = scopeSpecificity(entry.kind);
+    if (!best) {
+      best = { entry, range, specificity };
+      continue;
+    }
+    const bestWidth = best.range.to - best.range.from;
+    const width = range.to - range.from;
+    // Precedence order:
+    //   1. Narrower range wins.
+    //   2. On width-tie, the more specific kind wins (field > paragraph,
+    //      table-cell > table-row > table). This is the adversarial-
+    //      closure fix — nested kinds sharing a canonical block range
+    //      must still resolve to the deepest semantic unit.
+    //   3. On width + specificity tie, later start wins (deeper in the
+    //      document walk — preserves the pre-fix tie-break for legacy
+    //      cases not covered by specificity).
+    if (width < bestWidth) {
+      best = { entry, range, specificity };
+    } else if (width === bestWidth) {
+      if (specificity > best.specificity) {
+        best = { entry, range, specificity };
+      } else if (
+        specificity === best.specificity &&
+        range.from > best.range.from
+      ) {
+        best = { entry, range, specificity };
+      }
+    }
+  }
+  return best?.entry ?? null;
+}
+
+function resolveByOffset(
+  at: number,
+  scopes: readonly EnumeratedScope[],
+  positionMap: ReturnType<typeof buildScopePositionMap>,
+): ResolveReferenceResult {
+  const hit = innermostContaining(
+    scopes,
+    positionMap,
+    (range) => range.from <= at && at <= range.to,
+  );
+  if (!hit) {
+    return { status: "not-found", reason: `no scope contains offset ${at}` };
+  }
+  return {
+    status: "resolved",
+    handle: hit.handle,
+    confidence: hit.handle.provenance === "marker-backed" ? "high" : "medium",
+  };
+}
+
+function resolveByRange(
+  from: number,
+  to: number,
+  scopes: readonly EnumeratedScope[],
+  positionMap: ReturnType<typeof buildScopePositionMap>,
+): ResolveReferenceResult {
+  const low = Math.min(from, to);
+  const high = Math.max(from, to);
+  const hit = innermostContaining(
+    scopes,
+    positionMap,
+    (range) => range.from <= low && high <= range.to,
+  );
+  if (!hit) {
+    return {
+      status: "not-found",
+      reason: `no scope fully contains range [${low}, ${high}]`,
+    };
+  }
+  return {
+    status: "resolved",
+    handle: hit.handle,
+    confidence: hit.handle.provenance === "marker-backed" ? "high" : "medium",
+  };
+}
+
+/**
+ * Extract a short lowercased text snippet from an `EnumeratedScope`
+ * suitable for natural-language substring matching. Paragraph-like and
+ * table-like kinds expose the inline text directly; review-store kinds
+ * expose the comment body / revision summary. Capped at 200 characters so
+ * the linear scan stays bounded.
+ */
+function extractNLHaystack(entry: EnumeratedScope): string {
+  switch (entry.kind) {
+    case "paragraph":
+    case "heading":
+    case "list-item": {
+      let out = "";
+      for (const child of entry.paragraph.children) {
+        if (out.length >= 200) break;
+        if (child.type === "text") out += child.text;
+      }
+      return out.slice(0, 200).toLowerCase();
+    }
+    case "field": {
+      let out = "";
+      for (const child of entry.field.children) {
+        if (out.length >= 200) break;
+        if (child.type === "text") out += child.text;
+      }
+      return out.slice(0, 200).toLowerCase();
+    }
+    case "table":
+    case "table-row":
+    case "table-cell":
+      // Tables carry structured content; skip their haystack to keep the
+      // linear scan cheap. Semantic-path matching still covers them.
+      return "";
+    case "comment-thread": {
+      const body = entry.thread.body ?? "";
+      return body.slice(0, 200).toLowerCase();
+    }
+    case "revision":
+      return `${entry.revision.kind} ${entry.revision.authorId ?? ""}`
+        .toLowerCase();
+    default: {
+      const _never: never = entry;
+      void _never;
+      return "";
+    }
+  }
+}
+
+/**
+ * Natural-language hint resolver (deliberately bounded).
+ *
+ * Contract (documented at `docs/architecture/09-ai-api.md` §A8): this
+ * path is **partial / low-confidence**. It substring-matches on:
+ *   - `semanticPath.join("/")` — structural hints like
+ *     "body/paragraph/3" or "review/comment-thread/..."
+ *   - `scopeId` — direct id substring
+ *   - `overlay.scopes[].label` — human-given scope labels (when the
+ *     overlay is threaded)
+ *   - a capped text excerpt from the scope's content (first 200 chars)
+ *
+ * Every returned `resolved` status carries `confidence: "low"` unchanged
+ * — callers must surface this to humans before committing a mutating
+ * action. Richer NL resolution (embedding-backed, domain-aware) is
+ * explicitly deferred; this matcher is a deterministic structural + text
+ * substring heuristic, not a semantic parser.
+ */
+function resolveByNaturalLanguage(
+  hint: string,
+  scopes: readonly EnumeratedScope[],
+  overlay: WorkflowOverlay | null | undefined,
+): ResolveReferenceResult {
+  const needle = hint.trim().toLowerCase();
+  if (!needle) {
+    return { status: "not-found", reason: "empty natural-language hint" };
+  }
+  const overlayLabelByScopeId = new Map<string, string>();
+  if (overlay?.scopes) {
+    for (const s of overlay.scopes) {
+      if (s.label) overlayLabelByScopeId.set(s.scopeId, s.label.toLowerCase());
+    }
+  }
+  const matches: EnumeratedScope[] = [];
+  for (const entry of scopes) {
+    const path = entry.handle.semanticPath.join("/").toLowerCase();
+    if (path.includes(needle)) {
+      matches.push(entry);
+      continue;
+    }
+    if (entry.handle.scopeId.toLowerCase().includes(needle)) {
+      matches.push(entry);
+      continue;
+    }
+    const label = overlayLabelByScopeId.get(entry.handle.scopeId);
+    if (label && label.includes(needle)) {
+      matches.push(entry);
+      continue;
+    }
+    const haystack = extractNLHaystack(entry);
+    if (haystack && haystack.includes(needle)) {
+      matches.push(entry);
+    }
+  }
+  if (matches.length === 1) {
+    return { status: "resolved", handle: matches[0]!.handle, confidence: "low" };
+  }
+  if (matches.length > 1) {
+    return { status: "ambiguous", candidates: matches.slice(0, 8).map((m) => m.handle) };
+  }
+  return { status: "not-found", reason: `no scope matches hint "${hint}"` };
+}
+
+export function resolveReference(
+  reference: ScopeReference,
+  inputs: ResolveReferenceInputs,
+): ResolveReferenceResult {
+  const scopes = scopesFor(inputs);
+  const positionMap = buildScopePositionMap(inputs.document);
+  switch (reference.kind) {
+    case "scope-id":
+      return resolveByScopeId(reference.value, scopes, inputs.overlay, positionMap);
+    case "semantic-path":
+      return resolveBySemanticPath(reference.path, scopes);
+    case "offset":
+      return resolveByOffset(reference.at, scopes, positionMap);
+    case "range":
+      return resolveByRange(reference.from, reference.to, scopes, positionMap);
+    case "natural-language":
+      return resolveByNaturalLanguage(
+        reference.hint,
+        scopes,
+        inputs.overlay,
+      );
+    default: {
+      const never: never = reference;
+      return { status: "not-found", reason: `unsupported reference kind: ${String((never as { kind?: string }).kind)}` };
+    }
+  }
+}

package/src/runtime/scopes/review-bundle.ts

@@ -0,0 +1,141 @@
+/**
+ * Slice 3 — per-scope review bundle.
+ *
+ * Enumerates comments + revisions (+ eventually issues + suggestions from
+ * the workflow overlay in Slice 6) that overlap one scope. Consumers:
+ * the CLM negotiation-review flow, the AI-API `getScopeBundle`, and the
+ * chrome-side review sidebar.
+ */
+
+import type {
+  CanonicalDocument,
+  CommentThread,
+  RevisionRecord,
+} from "../../model/canonical-document.ts";
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type { WorkflowOverlay } from "./_scope-dependencies.ts";
+
+import { buildScopePositionMap, type ScopePositionRange } from "./position-map.ts";
+import type { EnumeratedScope } from "./enumerate-scopes.ts";
+import { enumerateScopes } from "./enumerate-scopes.ts";
+import { rangesOverlap, resolveScopeRange } from "./scope-range.ts";
+import type { SemanticScope } from "./semantic-scope-types.ts";
+
+export interface ReviewBundleCommentSummary {
+  readonly commentId: string;
+  readonly status: CommentThread["status"];
+  readonly author?: string;
+  readonly body?: string;
+  readonly entryCount: number;
+}
+
+export interface ReviewBundleRevisionSummary {
+  readonly changeId: string;
+  readonly kind: RevisionRecord["kind"];
+  readonly status: RevisionRecord["status"];
+  readonly author?: string;
+  readonly semanticKind?: string;
+}
+
+export interface ReviewBundle {
+  readonly scopeId: string;
+  readonly comments: readonly ReviewBundleCommentSummary[];
+  readonly revisions: readonly ReviewBundleRevisionSummary[];
+  readonly issueIds: readonly string[];
+  readonly suggestionIds: readonly string[];
+}
+
+export interface ComposeReviewBundleInputs {
+  readonly scope: SemanticScope;
+  readonly document: Pick<CanonicalDocument, "content" | "review"> | CanonicalDocumentEnvelope;
+  readonly overlay?: WorkflowOverlay | null;
+  readonly scopes?: readonly EnumeratedScope[];
+}
+
+function anchorToRange(
+  anchor: CommentThread["anchor"] | RevisionRecord["anchor"],
+): ScopePositionRange | null {
+  switch (anchor.kind) {
+    case "range":
+      return { from: anchor.range.from, to: anchor.range.to };
+    case "node":
+      return { from: anchor.at, to: anchor.at };
+    case "detached":
+      return anchor.lastKnownRange;
+    default:
+      return null;
+  }
+}
+
+function findEntryForScope(
+  scope: SemanticScope,
+  scopes: readonly EnumeratedScope[],
+): EnumeratedScope | null {
+  return scopes.find((entry) => entry.handle.scopeId === scope.handle.scopeId) ?? null;
+}
+
+export function composeReviewBundle(
+  inputs: ComposeReviewBundleInputs,
+): ReviewBundle {
+  const { scope, document, overlay } = inputs;
+  const scopes =
+    inputs.scopes ??
+    enumerateScopes(
+      document as Pick<CanonicalDocument, "content" | "docId" | "review">,
+      { overlay: overlay ?? null },
+    );
+  const positionMap = buildScopePositionMap(document);
+  const entry = findEntryForScope(scope, scopes);
+  const selfRange = entry
+    ? resolveScopeRange(entry, scope.handle, positionMap)
+    : null;
+
+  const comments: ReviewBundleCommentSummary[] = [];
+  const revisions: ReviewBundleRevisionSummary[] = [];
+
+  const review = (document as {
+    review?: {
+      comments?: Record<string, CommentThread>;
+      revisions?: Record<string, RevisionRecord>;
+    };
+  }).review;
+
+  if (selfRange && review) {
+    for (const thread of Object.values(review.comments ?? {})) {
+      const range = anchorToRange(thread.anchor);
+      if (!range || !rangesOverlap(selfRange, range)) continue;
+      comments.push({
+        commentId: thread.commentId,
+        status: thread.status,
+        author: thread.authorId ?? thread.createdBy,
+        body: thread.body,
+        entryCount: thread.entries?.length ?? 0,
+      });
+    }
+    for (const rev of Object.values(review.revisions ?? {})) {
+      const range = anchorToRange(rev.anchor);
+      if (!range || !rangesOverlap(selfRange, range)) continue;
+      revisions.push({
+        changeId: rev.changeId,
+        kind: rev.kind,
+        status: rev.status,
+        author: rev.authorId,
+        semanticKind: rev.metadata?.semanticKind,
+      });
+    }
+  }
+
+  comments.sort((a, b) => (a.commentId < b.commentId ? -1 : a.commentId > b.commentId ? 1 : 0));
+  revisions.sort((a, b) => (a.changeId < b.changeId ? -1 : a.changeId > b.changeId ? 1 : 0));
+
+  // Issues + suggestions live on the workflow overlay; Slice 6 lands them
+  // as first-class kinds. For Slice 3 we leave the arrays empty so the
+  // bundle shape stays stable for consumers.
+  return {
+    scopeId: scope.handle.scopeId,
+    comments,
+    revisions,
+    issueIds: [],
+    suggestionIds: [],
+  };
+}

package/src/runtime/scopes/scope-kinds/_paragraph-text.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared paragraph-text extractor used by paragraph/heading/list-item kind
+ * compilers. Excludes markers (bookmarks, scope markers) and non-text
+ * content. Deterministic: identical inputs produce identical output.
+ */
+
+import type {
+  InlineNode,
+  ParagraphNode,
+} from "../../../model/canonical-document.ts";
+
+function inlineText(node: InlineNode): string {
+  switch (node.type) {
+    case "text":
+      return node.text;
+    case "hyperlink":
+    case "field":
+      return node.children
+        .map((child) => inlineText(child as InlineNode))
+        .join("");
+    case "tab":
+      return "\t";
+    case "hard_break":
+    case "column_break":
+      return "\n";
+    case "symbol":
+      return node.char ?? "";
+    default:
+      return "";
+  }
+}
+
+export function extractParagraphText(paragraph: ParagraphNode): string {
+  return paragraph.children
+    .map((child) => inlineText(child as InlineNode))
+    .join("");
+}
+
+const EXCERPT_MAX = 160;
+
+/**
+ * Truncate to at most `EXCERPT_MAX` UTF-16 code units with an ellipsis. We
+ * iterate code points (spread) and rejoin to guarantee we never split a
+ * surrogate pair in half — naive `String.slice` can cut `"😀"` between its
+ * high + low surrogates and produce a malformed string.
+ */
+export function buildExcerpt(text: string): string | undefined {
+  if (!text) return undefined;
+  if (text.length <= EXCERPT_MAX) return text;
+  const codePoints = [...text];
+  let acc = "";
+  for (const cp of codePoints) {
+    if (acc.length + cp.length > EXCERPT_MAX - 1) break;
+    acc += cp;
+  }
+  return `${acc}…`;
+}

package/src/runtime/scopes/scope-kinds/_table-text.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared text extractor for table kinds. Concatenates paragraph text inside
+ * a cell (or across cells in a row / rows in a table). Skips non-paragraph
+ * block children (opaque blocks, section breaks, nested tables — later
+ * slices can recurse for nested table previews).
+ */
+
+import type {
+  BlockNode,
+  TableCellNode,
+  TableNode,
+  TableRowNode,
+} from "../../../model/canonical-document.ts";
+
+import { extractParagraphText } from "./_paragraph-text.ts";
+
+export function extractCellText(cell: TableCellNode): string {
+  const parts: string[] = [];
+  for (const child of cell.children as readonly BlockNode[]) {
+    if (child.type === "paragraph") {
+      const t = extractParagraphText(child);
+      if (t) parts.push(t);
+    }
+  }
+  return parts.join(" ");
+}
+
+export function extractRowText(row: TableRowNode): string {
+  return (row.cells as readonly TableCellNode[])
+    .map((cell) => extractCellText(cell))
+    .filter((t) => t.length > 0)
+    .join(" | ");
+}
+
+export function extractTablePreview(table: TableNode, maxRows = 2): string {
+  const rows: string[] = [];
+  for (let idx = 0; idx < Math.min(table.rows.length, maxRows); idx += 1) {
+    const t = extractRowText(table.rows[idx]!);
+    if (t) rows.push(t);
+  }
+  return rows.join(" ; ");
+}

package/src/runtime/scopes/scope-kinds/comment-thread.ts

@@ -0,0 +1,59 @@
+/**
+ * Comment-thread scope kind — Slice 3.
+ *
+ * Projects a canonical `CommentThread` record into a scope. Content is
+ * the thread body + concatenated entry bodies (the narrative the agent
+ * needs). Workflow mode is `comment` (open threads) / `view` (resolved).
+ */
+
+import type { CommentThreadEnumeratedScope } from "../enumerate-scopes.ts";
+import { deriveReplaceability } from "../replaceability.ts";
+import type {
+  SemanticScope,
+  SemanticScopeWorkflow,
+} from "../semantic-scope-types.ts";
+import { buildExcerpt } from "./_paragraph-text.ts";
+
+function threadText(thread: CommentThreadEnumeratedScope["thread"]): string {
+  const parts: string[] = [];
+  if (thread.body) parts.push(thread.body);
+  for (const entry of thread.entries ?? []) {
+    if (entry.body) parts.push(entry.body);
+  }
+  return parts.join("\n");
+}
+
+export function compileCommentThreadScope(
+  entry: CommentThreadEnumeratedScope,
+): SemanticScope {
+  const { handle, thread } = entry;
+  const text = threadText(thread);
+  const workflow: SemanticScopeWorkflow = {
+    scopeIds: [thread.commentId],
+    effectiveMode: thread.status === "open" ? "comment" : "view",
+    ...(thread.status === "detached"
+      ? { blockedReasons: ["comment-thread-detached"] }
+      : {}),
+  };
+  return {
+    handle,
+    kind: "comment-thread",
+    classifications: entry.classifications,
+    content: {
+      text,
+      excerpt: buildExcerpt(text),
+    },
+    formatting: {},
+    layout: {},
+    geometry: {},
+    workflow,
+    replaceability: deriveReplaceability(entry.kind, handle.provenance),
+    audit: {
+      source: thread.metadata?.source === "import" ? "import" : "runtime",
+      derivedFrom: ["canonical.review.comments", `status:${thread.status}`],
+      confidence: thread.status === "detached" ? "low" : "high",
+    },
+    // layout / geometry projections unpopulated until refactor/05 Slice 5.
+    partial: true,
+  };
+}