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

package/src/legacy-skills.ts

@@ -0,0 +1,133 @@
+import { lstat, readFile, rm } from "node:fs/promises";
+import path from "node:path";
+
+import { valid as validVersion } from "semver";
+
+export const LEGACY_SKILL_NAMES = [
+  "whiteboard",
+  "dev-review",
+  "dev-review-batch",
+  "dev-file-lenses",
+  "scratchpad",
+  "trace-archaeology",
+  "dev-review-map",
+  "review",
+  "review-map",
+  "review-stop",
+  "progressive-review",
+  "pr-review",
+] as const;
+
+export function legacySkillRoots(homeDir: string): string[] {
+  return [
+    path.join(homeDir, ".claude", "skills"),
+    path.join(homeDir, ".cursor", "skills"),
+    path.join(homeDir, ".config", "opencode", "skills"),
+    path.join(homeDir, ".agents", "skills"),
+  ];
+}
+
+/**
+ * True only for a real skill directory (never a symlink to someone else's)
+ * holding a regular SKILL.md whose frontmatter Review Desktop wrote.
+ */
+async function isReviewStamped(skillDir: string): Promise<boolean> {
+  const file = path.join(skillDir, "SKILL.md");
+
+  try {
+    if (!(await lstat(skillDir)).isDirectory()) return false;
+
+    if (!(await lstat(file)).isFile()) return false;
+  } catch {
+    return false;
+  }
+
+  const source = await readTextOrUndefined(file);
+
+  // An unreadable file cannot be verified as Review's, so it is never removed.
+  if (source === undefined) return false;
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source)?.[1];
+
+  const metadata = frontmatter?.match(
+    /^metadata:\r?\n((?:[ \t]+[^\n]*(?:\n|$))*)/m,
+  )?.[1];
+
+  if (
+    !metadata ||
+    !(
+      (/^  review-managed-by: "Review Desktop"\r?$/m.test(metadata) &&
+        /^  review-generated: "[^"\r\n]+"\r?$/m.test(metadata)) ||
+      (/^  whiteboard-managed-by: "Whiteboard(?: Desktop)?"\r?$/m.test(
+        metadata,
+      ) &&
+        /^  whiteboard-generated: "[^"\r\n]+"\r?$/m.test(metadata))
+    )
+  )
+    return false;
+
+  const version = metadata.match(
+    /^  (?:review|whiteboard)-version: "([^"\r\n]+)"\r?$/m,
+  )?.[1];
+
+  return (
+    version !== undefined &&
+    (version === "development" || validVersion(version) !== null)
+  );
+}
+
+const OPENCODE_PLUGIN_MARKER =
+  "// Managed by Review Desktop (@dev.fast/review).";
+
+/** The OpenCode plugin file Review Desktop wrote before it connected over MCP. */
+async function isLegacyOpenCodePlugin(file: string): Promise<boolean> {
+  try {
+    if (!(await lstat(file)).isFile()) return false;
+  } catch {
+    return false;
+  }
+
+  const source = await readTextOrUndefined(file);
+
+  return source?.split(/\r?\n/, 1)[0] === OPENCODE_PLUGIN_MARKER;
+}
+
+async function readTextOrUndefined(file: string): Promise<string | undefined> {
+  try {
+    return await readFile(file, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+export async function scanLegacySkills(homeDir: string): Promise<string[]> {
+  const found: string[] = [];
+
+  for (const name of ["review.ts", "whiteboard.ts"]) {
+    const plugin = path.join(homeDir, ".config", "opencode", "plugins", name);
+
+    if (await isLegacyOpenCodePlugin(plugin)) found.push(plugin);
+  }
+
+  for (const root of legacySkillRoots(homeDir)) {
+    for (const name of LEGACY_SKILL_NAMES) {
+      const skillDir = path.join(root, name);
+
+      if (await isReviewStamped(skillDir)) found.push(skillDir);
+    }
+  }
+
+  return found.sort();
+}
+
+export async function removeLegacySkills(
+  homeDir: string,
+): Promise<{ removed: string[] }> {
+  const removed: string[] = [];
+
+  for (const skillDir of await scanLegacySkills(homeDir)) {
+    await rm(skillDir, { recursive: true, force: true });
+    removed.push(skillDir);
+  }
+
+  return { removed };
+}

package/src/lens-selection.ts

@@ -0,0 +1,230 @@
+import { z } from "zod";
+
+import { type FileLineRange, type SourcePins } from "./source.js";
+import { unionIntervals } from "./viewed-coverage.js";
+
+const ANCHOR_FORMS =
+  '"head/path#L10-L24" or "base/path#L7" (one side, lines 10–24 or line 7); across sides, GitHub diff style "diff/path#L84-R90" (L = base line, R = head line)';
+
+/** Inclusive endpoints in the uncollapsed alignment, independent of diff
+ * layout. `pins` names the repository and commits the selection was read
+ * from; a selection without them resolves against its document's pins. */
+export type DiffSelection = {
+  file: string;
+  start: { side: "base" | "head"; line: number };
+  end: { side: "base" | "head"; line: number };
+  pins?: SourcePins;
+};
+
+/** A selection as written and stored: "head/path#L10-L24", "base/path#L7",
+ * or "diff/path#L84-R90" across sides. Pins live on whatever holds it. */
+export type Anchor = string;
+
+const sameSideAnchor = /^(head|base)\/(.+)#L(\d+)(?:-L(\d+))?$/;
+
+const crossSideAnchor = /^diff\/(.+)#([LR])(\d+)-([LR])(\d+)$/;
+
+/** An anchor's selection, as markdown source links write it too (without
+ * their `review-source:` scheme). Undefined when it isn't one. */
+export function parseAnchor(text: string): DiffSelection | undefined {
+  const same = sameSideAnchor.exec(text);
+
+  if (same) {
+    const side = same[1] === "base" ? "base" : "head";
+
+    return {
+      file: same[2]!,
+      start: { side, line: Number(same[3]) },
+      end: { side, line: Number(same[4] ?? same[3]) },
+    };
+  }
+
+  const cross = crossSideAnchor.exec(text);
+
+  // One side has its own spelling, so a diff anchor must cross.
+  if (!cross || cross[2] === cross[4]) return undefined;
+  const side = (letter: string) => (letter === "L" ? "base" : "head");
+
+  return {
+    file: cross[1]!,
+    start: { side: side(cross[2]!), line: Number(cross[3]) },
+    end: { side: side(cross[4]!), line: Number(cross[5]) },
+  };
+}
+
+/** Why a parsed selection can't be quoted, or undefined when it can. */
+export function selectionProblem(selection: DiffSelection): string | undefined {
+  if (selection.start.line < 1 || selection.end.line < 1)
+    return "Source lines count from 1.";
+
+  if (
+    selection.start.side === selection.end.side &&
+    selection.start.line > selection.end.line
+  )
+    return "Source range ends before it starts.";
+
+  if (
+    selection.pins &&
+    selection.pins.base === undefined &&
+    (selection.start.side === "base" || selection.end.side === "base")
+  )
+    return "A base-side anchor needs base pins.";
+}
+
+export const anchorSchema = z
+  .string({ error: `Expected a source anchor: ${ANCHOR_FORMS}.` })
+  .superRefine((text, context) => {
+    const selection = parseAnchor(text);
+
+    const problem = selection
+      ? selectionProblem(selection)
+      : `Use ${ANCHOR_FORMS} for a source anchor.`;
+
+    if (problem) context.addIssue({ code: "custom", message: problem });
+  })
+  .describe("head/path#L10-L24, base/path#L7, or diff/path#L84-R90");
+
+/** A stored anchor's selection, read at the pins of whatever holds it. */
+export function anchorSelection(
+  anchor: Anchor,
+  pins?: SourcePins,
+): DiffSelection {
+  const selection = parseAnchor(anchor);
+
+  if (!selection) throw new Error(`Not a source anchor: ${anchor}`);
+
+  return pins ? { ...selection, pins } : selection;
+}
+
+/** The anchor that writes a selection; its pins belong to its holder. */
+export function formatAnchor(selection: DiffSelection): Anchor {
+  const { file, start, end } = selection;
+
+  if (start.side === end.side)
+    return start.line === end.line
+      ? `${start.side}/${file}#L${start.line}`
+      : `${start.side}/${file}#L${start.line}-L${end.line}`;
+
+  const letter = (side: "base" | "head") => (side === "base" ? "L" : "R");
+
+  return `diff/${file}#${letter(start.side)}${start.line}-${letter(end.side)}${end.line}`;
+}
+
+/** A selection as its holder stores it: the anchor, and its pins when it
+ * names its own. */
+export function anchored(selection: DiffSelection): {
+  source: Anchor;
+  pins?: SourcePins;
+} {
+  return selection.pins
+    ? { source: formatAnchor(selection), pins: selection.pins }
+    : { source: formatAnchor(selection) };
+}
+
+export type LensSource = DiffSelection;
+
+export type AlignmentRow = readonly [number | null, number | null];
+
+/** Pins-less selections keep the key they always had. */
+export function selectionKey(source: LensSource): string {
+  return JSON.stringify([
+    source.file,
+    source.start.side,
+    source.start.line,
+    source.end.side,
+    source.end.line,
+    ...(source.pins ? [sourcePinsKey(source.pins)] : []),
+  ]);
+}
+
+export function sourcePinsKey(pins: SourcePins): string {
+  return `${pins.repositoryId}:${pins.base ?? ""}:${pins.head}`;
+}
+
+/** The comparison a source's pins name: head alone means head against
+ * itself. Reference coverage is grouped under this key on both sides. */
+export function comparisonKey(pins: SourcePins): string {
+  return `${pins.repositoryId}:${pins.base ?? pins.head}:${pins.head}`;
+}
+
+/** The anchor for one side's line range; its pins belong to its holder. */
+export function rangeAnchor(
+  source: Pick<FileLineRange, "file" | "side" | "fromLine" | "toLine">,
+): Anchor {
+  return formatAnchor({
+    file: source.file,
+    start: { side: source.side, line: source.fromLine },
+    end: { side: source.side, line: source.toLine },
+  });
+}
+
+/** Adapt internal source links (for example software-map evidence) to a selection. */
+export function selectSource(source: FileLineRange): DiffSelection {
+  const selection: DiffSelection = {
+    file: source.file,
+    start: { side: source.side, line: source.fromLine },
+    end: { side: source.side, line: source.toLine },
+  };
+
+  return source.pins ? { ...selection, pins: source.pins } : selection;
+}
+
+/** Navigation/quote anchors only; never use these as lens coverage. */
+export function sourceAnchors(source: LensSource): FileLineRange[] {
+  return (["head", "base"] as const).flatMap((side) => {
+    const lines = [source.start, source.end].flatMap((endpoint) =>
+      endpoint.side === side ? [endpoint.line] : [],
+    );
+
+    if (!lines.length) return [];
+
+    const anchor: FileLineRange = {
+      file: source.file,
+      side,
+      fromLine: Math.min(...lines),
+      toLine: Math.max(...lines),
+    };
+
+    if (source.pins) anchor.pins = source.pins;
+
+    return [anchor];
+  });
+}
+
+export function sourceAnchor(source: LensSource): FileLineRange {
+  return sourceAnchors(source)[0]!;
+}
+
+/** Resolve once against the renderer's rows. No matching or context expansion. */
+export function resolveDiffSelection(
+  source: LensSource,
+  rows: readonly AlignmentRow[],
+  file: { path: string; previousPath?: string },
+): FileLineRange[] {
+  const locate = (endpoint: DiffSelection["start"]): number =>
+    rows.findIndex(
+      (row) => row[endpoint.side === "base" ? 0 : 1] === endpoint.line - 1,
+    );
+
+  const start = locate(source.start);
+  const end = locate(source.end);
+
+  if (start < 0 || end < start)
+    throw new Error(
+      "Lens endpoints do not identify an ordered interval in this diff.",
+    );
+  const selected = rows.slice(start, end + 1);
+
+  return (["base", "head"] as const).flatMap((side, index) =>
+    unionIntervals(
+      selected.flatMap((row) =>
+        row[index] === null ? [] : [[row[index]!, row[index]! + 1]],
+      ),
+    ).map(([from, to]) => ({
+      file: side === "base" ? (file.previousPath ?? file.path) : file.path,
+      side,
+      fromLine: from + 1,
+      toLine: to,
+    })),
+  );
+}

package/src/markdown-latex-math.ts

@@ -0,0 +1,230 @@
+import type {
+  Extension as FromMarkdownExtension,
+  Handle,
+} from "mdast-util-from-markdown";
+import type {
+  Code,
+  Construct,
+  Extension,
+  State,
+  TokenizeContext,
+} from "micromark-util-types";
+
+declare module "micromark-util-types" {
+  interface TokenTypeMap {
+    latexInlineMath: "latexInlineMath";
+    latexDisplayMath: "latexDisplayMath";
+    latexMathSequence: "latexMathSequence";
+    latexMathData: "latexMathData";
+  }
+}
+
+const backslash = 92;
+
+/**
+ * `\(…\)` inline and `\[…\]` display math, read ahead of character escapes.
+ * `\[` and `\]` count only on their own lines, so an escaped `\[1\]` stays prose.
+ */
+export function latexMath(): Extension {
+  return {
+    text: {
+      [backslash]: [
+        delimitedMath("latexInlineMath", 40, 41, false),
+        delimitedMath("latexDisplayMath", 91, 93, true),
+      ],
+    },
+  };
+}
+
+/** Builds the nodes `$` and `$$` produce. */
+export function latexMathFromMarkdown(): FromMarkdownExtension {
+  return {
+    enter: {
+      latexInlineMath(token) {
+        this.enter({ type: "inlineMath", value: "" }, token);
+        this.buffer();
+      },
+      latexDisplayMath(token) {
+        this.enter({ type: "math", value: "" }, token);
+        this.buffer();
+      },
+    },
+    exit: {
+      latexInlineMath: exitMath,
+      latexDisplayMath: exitMath,
+      latexMathData(token) {
+        this.config.enter.data.call(this, token);
+        this.config.exit.data.call(this, token);
+      },
+    },
+  };
+}
+
+const exitMath: Handle = function (token) {
+  const value = this.resume().trim();
+  const node = this.stack.at(-1);
+
+  if (node?.type !== "inlineMath" && node?.type !== "math")
+    throw new Error(`Expected a math node, found ${node?.type}.`);
+  node.value = value;
+  this.exit(token);
+};
+
+const lineEnding = (code: Code) => code !== null && code < -2;
+
+// Space, tab and micromark's virtual space.
+const lineSpace = (code: Code) => code === 32 || code === -2 || code === -1;
+
+function delimitedMath(
+  type: "latexInlineMath" | "latexDisplayMath",
+  open: number,
+  close: number,
+  ownLine: boolean,
+): Construct {
+  const closing: Construct = { tokenize: tokenizeClosing, partial: true };
+
+  return { name: type, tokenize: tokenizeMath };
+
+  function tokenizeMath(
+    this: TokenizeContext,
+    effects: Parameters<Construct["tokenize"]>[0],
+    ok: State,
+    nok: State,
+  ): State {
+    let lineStart = false;
+
+    return start;
+
+    function start(code: Code): State | undefined {
+      effects.enter(type);
+      effects.enter("latexMathSequence");
+      effects.consume(code);
+
+      return opening;
+    }
+
+    function opening(code: Code): State | undefined {
+      if (code !== open) return nok(code);
+      effects.consume(code);
+
+      return ownLine ? openingLine : openingEnd;
+    }
+
+    function openingLine(code: Code): State | undefined {
+      if (lineSpace(code)) {
+        effects.consume(code);
+
+        return openingLine;
+      }
+
+      return lineEnding(code) ? openingEnd(code) : nok(code);
+    }
+
+    function openingEnd(code: Code): State | undefined {
+      effects.exit("latexMathSequence");
+
+      return between(code);
+    }
+
+    function between(code: Code): State | undefined {
+      if (code === null) return nok(code);
+
+      if (code === backslash)
+        return ownLine && !lineStart
+          ? escape(code)
+          : effects.attempt(closing, after, escape)(code);
+
+      if (lineEnding(code)) {
+        effects.enter("lineEnding");
+        effects.consume(code);
+        effects.exit("lineEnding");
+        lineStart = true;
+
+        return between;
+      }
+
+      effects.enter("latexMathData");
+
+      return data(code);
+    }
+
+    // `\\` is one unit, so the `)` in `\\)` never closes.
+    function escape(code: Code): State | undefined {
+      effects.enter("latexMathData");
+      effects.consume(code);
+      lineStart = false;
+
+      return escaped;
+    }
+
+    function escaped(code: Code): State | undefined {
+      if (code === null || lineEnding(code)) {
+        effects.exit("latexMathData");
+
+        return between(code);
+      }
+
+      effects.consume(code);
+
+      return data;
+    }
+
+    function data(code: Code): State | undefined {
+      if (code === null || code === backslash || lineEnding(code)) {
+        effects.exit("latexMathData");
+
+        return between(code);
+      }
+
+      if (!lineSpace(code)) lineStart = false;
+      effects.consume(code);
+
+      return data;
+    }
+
+    function after(code: Code): State | undefined {
+      effects.exit(type);
+
+      return ok(code);
+    }
+  }
+
+  function tokenizeClosing(
+    this: TokenizeContext,
+    effects: Parameters<Construct["tokenize"]>[0],
+    ok: State,
+    nok: State,
+  ): State {
+    return start;
+
+    function start(code: Code): State | undefined {
+      effects.enter("latexMathSequence");
+      effects.consume(code);
+
+      return closer;
+    }
+
+    function closer(code: Code): State | undefined {
+      if (code !== close) return nok(code);
+      effects.consume(code);
+
+      return ownLine ? closingLine : closingEnd;
+    }
+
+    function closingLine(code: Code): State | undefined {
+      if (lineSpace(code)) {
+        effects.consume(code);
+
+        return closingLine;
+      }
+
+      return code === null || lineEnding(code) ? closingEnd(code) : nok(code);
+    }
+
+    function closingEnd(code: Code): State | undefined {
+      effects.exit("latexMathSequence");
+
+      return ok(code);
+    }
+  }
+}

package/src/markdown.ts

@@ -0,0 +1,81 @@
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfmFromMarkdown } from "mdast-util-gfm";
+import { mathFromMarkdown } from "mdast-util-math";
+import { gfm } from "micromark-extension-gfm";
+import { math } from "micromark-extension-math";
+
+import { latexMath, latexMathFromMarkdown } from "./markdown-latex-math";
+
+export interface MarkdownNode {
+  type: string;
+  position?: { start: { offset?: number }; end: { offset?: number } };
+  children?: MarkdownNode[];
+  value?: string;
+  depth?: number;
+  ordered?: boolean | null;
+  start?: number | null;
+  checked?: boolean | null;
+  lang?: string | null;
+  url?: string;
+  title?: string | null;
+  align?: Array<string | null> | null;
+  alt?: string | null;
+  identifier?: string;
+  label?: string | null;
+}
+
+export function* markdownNodes(node: MarkdownNode): Generator<MarkdownNode> {
+  yield node;
+
+  for (const child of node.children ?? []) yield* markdownNodes(child);
+}
+
+/** The text a node carries, its own and every descendant's. */
+export function markdownText(node: MarkdownNode): string {
+  return [...markdownNodes(node)].map((child) => child.value ?? "").join("");
+}
+
+/** Shared syntax for submit-time source checks and safe Markdown rendering. */
+export function parseMarkdown(source: string): MarkdownNode {
+  const tree: MarkdownNode = fromMarkdown(source, {
+    extensions: [gfm(), math(), latexMath()],
+    mdastExtensions: [
+      gfmFromMarkdown(),
+      mathFromMarkdown(),
+      latexMathFromMarkdown(),
+    ],
+  });
+
+  // `$$x$$` alone in its paragraph is a display equation written on one line.
+  for (const node of markdownNodes(tree)) {
+    const [only, ...others] = node.children ?? [];
+
+    if (
+      node.type === "paragraph" &&
+      only?.type === "inlineMath" &&
+      others.length === 0 &&
+      source.startsWith("$$", only.position?.start.offset)
+    )
+      only.type = "math";
+  }
+
+  const definitions = new Map<string, MarkdownNode>();
+
+  for (const node of markdownNodes(tree))
+    if (node.type === "definition" && !definitions.has(node.identifier!))
+      definitions.set(node.identifier!, node);
+
+  for (const node of markdownNodes(tree)) {
+    if (node.type !== "linkReference") continue;
+    const definition = definitions.get(node.identifier!);
+
+    if (definition)
+      Object.assign(node, {
+        type: "link",
+        url: definition.url,
+        title: definition.title,
+      });
+  }
+
+  return tree;
+}