@dev.fast/whiteboard 0.0.0-stage → 0.2.1-preview.20261005.98

package/src/review-api/diff-lenses.ts

@@ -0,0 +1,175 @@
+import {
+  type LensSource,
+  anchorSchema,
+  anchorSelection,
+} from "@review/lens-selection.js";
+import type { FileLineRange } from "@review/source.js";
+import { z } from "zod";
+
+import { label } from "./blocks/definition.js";
+import { ReviewInputError } from "./input-error.js";
+
+/**
+ * Lenses partition a review's change for the Diff view. They live on the
+ * snapshot beside the document, are versioned with it, and are written one
+ * at a time with the lens command; the document never holds them.
+ */
+
+const patternsSchema = z.array(label).min(1).max(1000);
+
+export const lensTargetSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("files"), patterns: patternsSchema }),
+  z.strictObject({
+    kind: z.literal("ranges"),
+    sources: z.array(anchorSchema).min(1).max(10000),
+  }),
+]);
+
+export type LensTarget = z.infer<typeof lensTargetSchema>;
+
+export const lensTargetsSchema = z
+  .array(lensTargetSchema)
+  .min(1)
+  .max(1000)
+  .describe(
+    "Select changed lines using repository-relative paths/globs or source ranges. Counts and viewed actions apply only to those lines.",
+  );
+
+export const lensSchema = z.strictObject({
+  id: label,
+  title: label,
+  targets: lensTargetsSchema,
+});
+
+export type Lens = z.infer<typeof lensSchema>;
+
+export const LENS_LIMIT = 200;
+
+/** One lens edit. Ids are host-assigned (`lens-N`); an update patches only
+ * the fields it names. */
+export const lensEditSchema = z.discriminatedUnion("type", [
+  z.strictObject({
+    type: z.literal("insert"),
+    title: label,
+    targets: lensTargetsSchema,
+    afterId: label
+      .optional()
+      .describe("The lens this one follows. Omitted appends."),
+  }),
+  z.strictObject({
+    type: z.literal("update"),
+    targetId: label,
+    title: label.optional(),
+    targets: lensTargetsSchema.optional(),
+  }),
+  z.strictObject({ type: z.literal("remove"), targetId: label }),
+]);
+
+export type LensEdit = z.infer<typeof lensEditSchema>;
+
+/** Patterns are evaluated against the changed-file list, never the
+ * filesystem, but must still read as repository-relative globs. */
+export function checkLensTargets(targets: readonly LensTarget[]): void {
+  for (const pattern of targets.flatMap((target) =>
+    target.kind === "files" ? target.patterns : [],
+  ))
+    if (
+      pattern.startsWith("/") ||
+      pattern.split("/").includes("..") ||
+      pattern.includes("\\") ||
+      pattern.includes("\0")
+    )
+      throw new ReviewInputError(
+        "File lens patterns must be repository-relative paths or globs using forward slashes.",
+      );
+}
+
+/** Apply one edit in place and return the lens it landed on. */
+export function applyLensEdit(
+  lenses: Lens[],
+  edit: LensEdit,
+  allocate: () => string,
+): Lens {
+  const index = (id: string) => {
+    const at = lenses.findIndex((lens) => lens.id === id);
+
+    if (at < 0) throw new ReviewInputError(`Lens ${id} does not exist.`);
+
+    return at;
+  };
+
+  if (edit.type === "insert") {
+    if (lenses.length >= LENS_LIMIT)
+      throw new ReviewInputError(
+        `A review holds at most ${LENS_LIMIT} lenses.`,
+      );
+    checkLensTargets(edit.targets);
+
+    const lens: Lens = {
+      id: allocate(),
+      title: edit.title,
+      targets: edit.targets,
+    };
+
+    lenses.splice(
+      edit.afterId === undefined ? lenses.length : index(edit.afterId) + 1,
+      0,
+      lens,
+    );
+
+    return lens;
+  }
+
+  const at = index(edit.targetId);
+  const lens = lenses[at]!;
+
+  if (edit.type === "remove") {
+    lenses.splice(at, 1);
+
+    return lens;
+  }
+
+  if (edit.title === undefined && edit.targets === undefined)
+    throw new ReviewInputError("A lens update names a title or targets.");
+
+  if (edit.targets) checkLensTargets(edit.targets);
+
+  const next: Lens = {
+    ...lens,
+    ...(edit.title !== undefined && { title: edit.title }),
+    ...(edit.targets !== undefined && { targets: edit.targets }),
+  };
+
+  lenses[at] = next;
+
+  return next;
+}
+
+/** Every range a lens selects, with an id stable for its position. Lens
+ * ranges read at the review's pins. */
+export function lensSelections(
+  lenses: readonly Lens[],
+): { id: string; source: LensSource }[] {
+  return lenses.flatMap((lens) =>
+    lens.targets.flatMap((target, index) =>
+      target.kind === "ranges"
+        ? target.sources.map((source, range) => ({
+            id: `${lens.id}:target:${index}:${range}`,
+            source: anchorSelection(source),
+          }))
+        : [],
+    ),
+  );
+}
+
+/** A lens the Diff view lists: a named set of changed lines. */
+export interface DiffLens {
+  id: string;
+  title: string;
+  sources: FileLineRange[];
+  fileCount?: number;
+  wholeFiles?: boolean;
+}
+
+/** The lens id the Diff view gives changed lines no lens selects. */
+export const UNCATEGORIZED_LENS_ID = "automatic-uncategorized";

package/src/review-api/document-headings.ts

@@ -0,0 +1,51 @@
+import { markdownText, parseMarkdown } from "@review/markdown.js";
+import { slugify, uniqueId } from "@review/slug.js";
+
+import { type Block, elements } from "./document.js";
+
+export type ReviewHeadingLevel = "h2" | "h3";
+
+/** A section title or a root-level h2/h3 of a markdown block. `block` rather
+ * than its id: import needs slugs before the store has assigned ids. */
+export interface DocumentHeading {
+  id: string;
+  text: string;
+  level: ReviewHeadingLevel;
+  block: Block;
+  /** Position among the markdown block's own headings; absent for a section. */
+  index?: number;
+}
+
+/** Heading ids by the rule the MDX renderer published, `slugify(text)` made
+ * unique in document order, so imported `#fragment` links still land. */
+export function documentHeadings(blocks: Block[]): DocumentHeading[] {
+  const used = new Set<string>();
+
+  const assign = (heading: Omit<DocumentHeading, "id">): DocumentHeading => {
+    const id = uniqueId(slugify(heading.text) || "section", used);
+    used.add(id);
+
+    return { id, ...heading };
+  };
+
+  return elements(blocks).flatMap((block): DocumentHeading[] => {
+    if (block.type === "section")
+      return [assign({ text: block.title, level: "h2", block })];
+
+    if (block.type !== "markdown") return [];
+    let index = 0;
+
+    return (parseMarkdown(block.markdown).children ?? []).flatMap((node) =>
+      node.type === "heading" && (node.depth === 2 || node.depth === 3)
+        ? [
+            assign({
+              text: markdownText(node),
+              level: node.depth === 2 ? "h2" : "h3",
+              block,
+              index: index++,
+            }),
+          ]
+        : [],
+    );
+  });
+}

package/src/review-api/document-text.ts

@@ -0,0 +1,200 @@
+import { type Element, ReviewInputError, elements } from "./document.js";
+import type { Snapshot } from "./store.js";
+
+/** A reading view of saved content, not another document format to maintain. */
+export function documentText(
+  snapshot: Snapshot,
+  targetId?: string,
+  full = false,
+): string {
+  const target =
+    targetId === undefined
+      ? undefined
+      : elements(snapshot.document).find((item) => item.id === targetId);
+
+  if (targetId !== undefined && !target)
+    throw new ReviewInputError("Target not found in this version.", 404);
+  const detailed = full || target !== undefined;
+
+  const lines = [
+    `# ${snapshot.title}`,
+    `Session ${snapshot.reviewId} · version ${snapshot.version}`,
+    "",
+  ];
+
+  const write = (depth: number, text: string) => {
+    for (const line of text.split("\n")) lines.push("  ".repeat(depth) + line);
+  };
+
+  const code = (depth: number, value: { language: string; text: string }) => {
+    write(depth, `Code (${value.language}):`);
+    write(depth + 1, value.text);
+  };
+
+  const render = (element: Element, depth: number) => {
+    const title = "title" in element ? element.title : undefined;
+    write(depth, `[${element.id}] ${element.type}${title ? `: ${title}` : ""}`);
+    const detail = (text: string) => write(depth + 1, text);
+
+    switch (element.type) {
+      case "section":
+      case "callout":
+        if (element.type === "callout") detail(`Tone: ${element.tone}`);
+
+        if (element.type === "section" && element.defaultCollapsed)
+          detail("Initially collapsed");
+        element.children.forEach((child) => render(child, depth + 1));
+        break;
+      case "markdown":
+        detail(
+          detailed
+            ? element.markdown
+            : element.markdown.split("\n")[0] +
+                (element.markdown.includes("\n") ? " …" : ""),
+        );
+        break;
+      case "code":
+        if (element.caption) detail(element.caption);
+
+        if (detailed) code(depth + 1, element);
+        else
+          detail(
+            `${element.language}, ${element.text.split("\n").length} lines`,
+          );
+        break;
+      case "divider":
+        break;
+      case "code_peek":
+        detail(element.source);
+
+        if (element.caption) detail(element.caption);
+        break;
+      case "sequence":
+        for (const [key, label] of Object.entries(element.actors))
+          detail(`Actor ${key}: ${label}`);
+        element.steps.forEach((step) => render(step, depth + 1));
+        break;
+      case "step":
+        detail(
+          `${element.from} → ${element.to}: ${element.label} (${element.style})`,
+        );
+
+        if (element.source) detail(element.source);
+
+        if (detailed && element.explanation) detail(element.explanation);
+
+        if (detailed && element.code) code(depth + 1, element.code);
+        break;
+      case "call_stack_diff":
+        for (const side of ["base", "head"] as const) {
+          detail(`${side}:`);
+          element[side].forEach((frame) => {
+            write(
+              depth + 2,
+              `${frame.label ?? frame.key ?? "Frame"}: ${frame.source}`,
+            );
+
+            if (detailed && frame.via)
+              write(depth + 3, `${frame.via.kind}: ${frame.via.reason}`);
+          });
+        }
+
+        break;
+      case "database_lens":
+        for (const [key, label] of Object.entries(element.actors))
+          detail(`Actor ${key}: ${label}`);
+
+        for (const [key, store] of Object.entries(element.stores)) {
+          detail(`Store ${key}: ${store.label} (${store.storage})`);
+
+          for (const [key, collection] of Object.entries(store.collections)) {
+            write(depth + 2, `Collection ${key}: ${collection.label}`);
+
+            if (detailed)
+              for (const [key, field] of Object.entries(collection.fields)) {
+                write(
+                  depth + 3,
+                  `${key}: ${field.label}, ${field.dataType}${field.primaryKey ? ", primary key" : ""}${field.nullable ? ", nullable" : ""}${field.references ? ` → ${field.references.store}.${field.references.collection}.${field.references.field}` : ""}`,
+                );
+              }
+          }
+        }
+
+        for (const useCase of element.useCases) {
+          detail(`Use case: ${useCase.label}`);
+
+          if (detailed && useCase.summary) write(depth + 2, useCase.summary);
+
+          for (const operation of useCase.operations)
+            write(
+              depth + 2,
+              `${operation.actor}: ${operation.kind} ${operation.store}.${operation.collection}${operation.field ? `.${operation.field}` : ""} — ${operation.label} (${operation.source})`,
+            );
+        }
+
+        break;
+      case "image":
+        detail(`${element.alt} (asset: ${element.assetId})`);
+
+        if (element.caption) detail(element.caption);
+        break;
+      case "trace_quote":
+        detail(`${element.traceId}, event ${element.eventId}`);
+        detail(element.text);
+        break;
+      case "flow_diagram":
+        if (element.description) detail(element.description);
+
+        for (const node of element.nodes) {
+          detail(`[${node.id}] ${node.key}: ${node.label}`);
+
+          if (detailed && node.description) write(depth + 2, node.description);
+
+          for (const attachment of node.attachments)
+            write(
+              depth + 2,
+              `${attachment.label}: ${attachment.sources.join(", ")}`,
+            );
+        }
+
+        for (const edge of element.edges)
+          detail(
+            `[${edge.id}] ${edge.from} → ${edge.to}${edge.label ? `: ${edge.label}` : ""}`,
+          );
+        break;
+      case "software_map":
+        detail(
+          `Map: ${element.mapVersionId}${element.focusElementId ? `, focus: ${element.focusElementId}` : ""}`,
+        );
+        break;
+    }
+  };
+
+  (target ? [target] : snapshot.document).forEach((element) =>
+    render(element, 0),
+  );
+
+  if (!snapshot.document.length) lines.push("(Empty review)");
+
+  // Lenses sit beside the document; list them so their ids are at hand.
+  if (!target && snapshot.lenses?.length) {
+    lines.push("", "Lenses (edit with session_lens_edit):");
+
+    for (const lens of snapshot.lenses) {
+      write(0, `[${lens.id}] ${lens.title}`);
+
+      for (const item of lens.targets)
+        if (item.kind === "files")
+          write(1, `Files: ${item.patterns.join(", ")}`);
+        else for (const source of item.sources) write(1, `Range: ${source}`);
+    }
+  }
+
+  if (!detailed && snapshot.document.length)
+    lines.push(
+      "",
+      "Use targetId for one component's complete content, or full:true for the whole review.",
+    );
+
+  return lines.join("\n");
+}