@peaske7/readit 0.3.0-rc.0 → 0.3.0-rc.1

package/e2e/perf/fixtures/generate.ts

@@ -1,327 +0,0 @@
-import * as crypto from "node:crypto";
-import * as fs from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
-
-// ─── Types ───────────────────────────────────────────────────────────
-
-interface Comment {
-  id: string;
-  selectedText: string;
-  comment: string;
-  startOffset: number;
-  endOffset: number;
-  lineHint: string;
-}
-
-interface CommentFile {
-  source: string;
-  hash: string;
-  version: number;
-  comments: Comment[];
-}
-
-export interface Tier {
-  name: string;
-  lines: number;
-  comments: number;
-  fileName: string;
-}
-
-export const TIERS: Tier[] = [
-  { name: "medium", lines: 1000, comments: 100, fileName: "medium.md" },
-  { name: "large", lines: 3000, comments: 200, fileName: "large.md" },
-];
-
-// Second medium doc for tab-switch tests
-export const TAB_SWITCH_TIER: Tier = {
-  name: "medium-b",
-  lines: 1000,
-  comments: 100,
-  fileName: "medium-b.md",
-};
-
-export const FIXTURES_DIR = path.join(os.tmpdir(), "readit-perf-fixtures");
-
-// ─── Markdown generation ─────────────────────────────────────────────
-
-function generateMarkdownDoc(lineCount: number, seed: number): string {
-  const lines: string[] = [];
-  lines.push(`# Performance Benchmark Document (seed=${seed})`);
-  lines.push("");
-  lines.push(
-    "This document is auto-generated for performance benchmarking. It contains realistic markdown patterns.",
-  );
-  lines.push("");
-
-  let sectionNum = 1;
-  while (lines.length < lineCount) {
-    lines.push(`## Section ${sectionNum}: Topic Area ${sectionNum}`);
-    lines.push("");
-    lines.push(
-      `This section covers topic ${sectionNum} in detail. It includes various formatting such as **bold text**, *italic text*, and \`inline code\`. The content is designed to exercise the rendering pipeline.`,
-    );
-    lines.push("");
-
-    // Paragraph
-    lines.push(
-      `When reviewing documents of this complexity, it is important to consider the performance implications of rendering each element. Section ${sectionNum} demonstrates how the margin notes system handles comments distributed across a long document.`,
-    );
-    lines.push("");
-
-    // List
-    for (let j = 1; j <= 4; j++) {
-      lines.push(
-        `- Item ${j} in section ${sectionNum}: a list entry with enough text to be selectable`,
-      );
-    }
-    lines.push("");
-
-    // Code block
-    lines.push("```typescript");
-    lines.push(`function processSection${sectionNum}(data: unknown) {`);
-    lines.push(`  const result = validate(data);`);
-    lines.push(
-      `  if (!result.ok) throw new Error("Section ${sectionNum} failed");`,
-    );
-    lines.push(`  return transform(result.value);`);
-    lines.push("}");
-    lines.push("```");
-    lines.push("");
-
-    // Another paragraph
-    lines.push(
-      `The conclusion of section ${sectionNum} summarizes the key findings and provides actionable recommendations for the reader. This paragraph exists to ensure sufficient text density for highlight testing.`,
-    );
-    lines.push("");
-
-    // Table every 4th section
-    if (sectionNum % 4 === 0) {
-      lines.push("| Metric | Before | After | Change |");
-      lines.push("|--------|--------|-------|--------|");
-      lines.push(
-        `| Latency | ${sectionNum * 10}ms | ${sectionNum * 5}ms | -50% |`,
-      );
-      lines.push(
-        `| Throughput | ${sectionNum * 100} | ${sectionNum * 200} | +100% |`,
-      );
-      lines.push("");
-    }
-
-    // Blockquote every 5th section
-    if (sectionNum % 5 === 0) {
-      lines.push(
-        `> Note: Section ${sectionNum} contains important observations about system behavior under load.`,
-      );
-      lines.push("");
-    }
-
-    sectionNum++;
-  }
-
-  return lines.slice(0, lineCount).join("\n");
-}
-
-// ─── Comment generation ──────────────────────────────────────────────
-
-function makeComment(
-  index: number,
-  doc: string,
-  totalComments: number,
-): Comment {
-  const lines = doc.split("\n");
-
-  // Distribute comments evenly across the document, skipping empty lines and headers
-  const contentLines: { lineIndex: number; text: string }[] = [];
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (
-      line.length > 20 &&
-      !line.startsWith("#") &&
-      !line.startsWith("```") &&
-      !line.startsWith("|") &&
-      !line.startsWith(">") &&
-      !line.startsWith("- ")
-    ) {
-      contentLines.push({ lineIndex: i, text: line });
-    }
-  }
-
-  // Pick a content line for this comment
-  const targetIdx = Math.floor(
-    (index / totalComments) * (contentLines.length - 1),
-  );
-  const target = contentLines[Math.min(targetIdx, contentLines.length - 1)];
-
-  // Select a substring from the target line
-  const selectStart = 0;
-  const selectEnd = Math.min(40, target.text.length);
-  const selectedText = target.text.slice(selectStart, selectEnd);
-
-  // Compute character offset in the full document
-  let startOffset = 0;
-  for (let i = 0; i < target.lineIndex; i++) {
-    startOffset += lines[i].length + 1; // +1 for \n
-  }
-  startOffset += selectStart;
-  const endOffset = startOffset + selectedText.length;
-
-  // Line hint (1-indexed)
-  const lineHint = `L${target.lineIndex + 1}`;
-
-  return {
-    id: `perf${String(index).padStart(4, "0")}`,
-    selectedText,
-    comment: `Review comment #${index + 1}: This section needs attention regarding clarity and accuracy.`,
-    startOffset,
-    endOffset,
-    lineHint,
-  };
-}
-
-// ─── Comment serialization (standalone, no imports from src/) ────────
-
-function computeHash(content: string): string {
-  return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
-}
-
-function serializeComments(file: CommentFile): string {
-  const lines: string[] = [];
-
-  lines.push("---");
-  lines.push(`source: ${file.source}`);
-  lines.push(`hash: ${file.hash}`);
-  lines.push(`version: ${file.version}`);
-  lines.push("---");
-  lines.push("");
-
-  for (const comment of file.comments) {
-    // Metadata
-    lines.push(`<!-- c:${comment.id}|${comment.lineHint} -->`);
-
-    // Selected text as blockquote
-    const quotedLines = comment.selectedText
-      .split("\n")
-      .map((line) => `> ${line}`);
-    lines.push(...quotedLines);
-
-    // Comment body
-    if (comment.comment) {
-      lines.push("");
-      lines.push(comment.comment);
-    }
-
-    lines.push("");
-    lines.push("---");
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}
-
-/**
- * Compute comment path using realpath to match the server's path resolution.
- * The server uses fs.realpath() which resolves symlinks (e.g., /var → /private/var on macOS).
- * The sourcePath must exist on disk before calling this.
- */
-async function getCommentPathReal(sourcePath: string): Promise<string> {
-  const real = await fs.realpath(path.resolve(sourcePath));
-  const normalized = real.replace(/^\//, "").replace(/^[A-Z]:[\\/]/, "");
-  const ext = path.extname(normalized);
-  const withoutExt = normalized.slice(0, -ext.length || undefined);
-  return path.join(
-    os.homedir(),
-    ".readit",
-    "comments",
-    `${withoutExt}.comments.md`,
-  );
-}
-
-/** Sync version for cleanup (file may not exist) */
-function getCommentPathSync(sourcePath: string): string {
-  let absolute: string;
-  try {
-    absolute = require("node:fs").realpathSync(path.resolve(sourcePath));
-  } catch {
-    absolute = path.resolve(sourcePath);
-  }
-  const normalized = absolute.replace(/^\//, "").replace(/^[A-Z]:[\\/]/, "");
-  const ext = path.extname(normalized);
-  const withoutExt = normalized.slice(0, -ext.length || undefined);
-  return path.join(
-    os.homedir(),
-    ".readit",
-    "comments",
-    `${withoutExt}.comments.md`,
-  );
-}
-
-// ─── Public API ──────────────────────────────────────────────────────
-
-export function getFixturePath(tier: Tier): string {
-  return path.join(FIXTURES_DIR, tier.fileName);
-}
-
-export async function generateFixtures(): Promise<void> {
-  await fs.mkdir(FIXTURES_DIR, { recursive: true });
-
-  const allTiers = [...TIERS, TAB_SWITCH_TIER];
-
-  for (const tier of allTiers) {
-    const doc = generateMarkdownDoc(tier.lines, tier.lines);
-    const fixturePath = getFixturePath(tier);
-    await fs.writeFile(fixturePath, doc, "utf-8");
-
-    // Generate and write comment file
-    const comments: Comment[] = [];
-    for (let i = 0; i < tier.comments; i++) {
-      comments.push(makeComment(i, doc, tier.comments));
-    }
-
-    // Use realpath for the comment path (file must exist first)
-    const realFixturePath = await fs.realpath(fixturePath);
-
-    const commentFile: CommentFile = {
-      source: realFixturePath,
-      hash: computeHash(doc),
-      version: 1,
-      comments,
-    };
-
-    const commentPath = await getCommentPathReal(fixturePath);
-    await fs.mkdir(path.dirname(commentPath), { recursive: true });
-    await fs.writeFile(commentPath, serializeComments(commentFile), "utf-8");
-  }
-}
-
-export async function cleanupFixtures(): Promise<void> {
-  // Collect comment paths before removing fixtures (need realpath while files exist)
-  const commentPaths: string[] = [];
-  const allTiers = [...TIERS, TAB_SWITCH_TIER];
-  for (const tier of allTiers) {
-    commentPaths.push(getCommentPathSync(getFixturePath(tier)));
-  }
-
-  // Remove fixture files
-  try {
-    await fs.rm(FIXTURES_DIR, { recursive: true, force: true });
-  } catch {
-    // Ignore if already removed
-  }
-
-  // Remove comment files
-  for (const commentPath of commentPaths) {
-    try {
-      await fs.unlink(commentPath);
-    } catch {
-      // Ignore if already removed
-    }
-  }
-}
-
-// Allow running directly: bun e2e/perf/fixtures/generate.ts
-if (import.meta.url === `file://${process.argv[1]}`) {
-  generateFixtures().then(() => {
-    console.log(`Fixtures generated in ${FIXTURES_DIR}`);
-  });
-}

package/e2e/perf/initial-load.spec.ts

@@ -1,49 +0,0 @@
-import { test } from "@playwright/test";
-import { getFixturePath, TIERS } from "./fixtures/generate";
-import { collectLoadMetrics, reportLoadMetrics } from "./utils/metrics";
-import { spawnPerfCli } from "./utils/perf-cli";
-
-const ITERATIONS = 3;
-
-for (const tier of TIERS) {
-  test(`initial-load: ${tier.name} (${tier.lines} lines, ${tier.comments} comments)`, async ({
-    page,
-  }, testInfo) => {
-    const fixturePath = getFixturePath(tier);
-    const { url, cleanup } = await spawnPerfCli(fixturePath, {
-      port: 4600 + TIERS.indexOf(tier),
-    });
-
-    try {
-      const results: (typeof collected)[] = [];
-      let collected!: Awaited<ReturnType<typeof collectLoadMetrics>>;
-
-      for (let i = 0; i < ITERATIONS; i++) {
-        // Clear performance entries between iterations
-        if (i > 0) {
-          await page.evaluate(() => performance.clearResourceTimings());
-        }
-
-        collected = await collectLoadMetrics(page, url, tier.comments);
-        results.push(collected);
-
-        // Navigate away between iterations to force full reload
-        if (i < ITERATIONS - 1) {
-          await page.goto("about:blank");
-        }
-      }
-
-      // Report median
-      results.sort((a, b) => a.allHighlightsPainted - b.allHighlightsPainted);
-      const median = results[Math.floor(results.length / 2)];
-
-      reportLoadMetrics(
-        testInfo,
-        `initial-load (${tier.name}: ${tier.lines} lines, ${tier.comments} comments)`,
-        median,
-      );
-    } finally {
-      await cleanup();
-    }
-  });
-}

package/e2e/perf/perf.setup.ts

@@ -1,23 +0,0 @@
-import { execFileSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
-import { generateFixtures } from "./fixtures/generate";
-
-async function globalSetup() {
-  // Build the app if dist doesn't exist
-  const distIndex = resolve(import.meta.dirname, "../../dist/cli.js");
-  if (!existsSync(distIndex)) {
-    console.log("[perf] Building app...");
-    execFileSync("bun", ["run", "build"], {
-      cwd: resolve(import.meta.dirname, "../.."),
-      stdio: "inherit",
-    });
-  }
-
-  // Generate fixture files and comment files
-  console.log("[perf] Generating fixtures...");
-  await generateFixtures();
-  console.log("[perf] Setup complete.");
-}
-
-export default globalSetup;

package/e2e/perf/perf.teardown.ts

@@ -1,9 +0,0 @@
-import { cleanupFixtures } from "./fixtures/generate";
-
-async function globalTeardown() {
-  console.log("[perf] Cleaning up fixtures...");
-  await cleanupFixtures();
-  console.log("[perf] Teardown complete.");
-}
-
-export default globalTeardown;

package/e2e/perf/scroll.spec.ts

@@ -1,39 +0,0 @@
-import { test } from "@playwright/test";
-import { getFixturePath, TIERS } from "./fixtures/generate";
-import {
-  collectScrollMetrics,
-  reportScrollMetrics,
-  waitForHighlightCount,
-} from "./utils/metrics";
-import { spawnPerfCli } from "./utils/perf-cli";
-
-for (const tier of TIERS) {
-  test(`scroll: ${tier.name} (${tier.lines} lines, ${tier.comments} comments)`, async ({
-    page,
-  }, testInfo) => {
-    const fixturePath = getFixturePath(tier);
-    const { url, cleanup } = await spawnPerfCli(fixturePath, {
-      port: 4610 + TIERS.indexOf(tier),
-    });
-
-    try {
-      await page.goto(url);
-
-      // Wait for all highlights to be painted before starting scroll
-      await waitForHighlightCount(page, tier.comments);
-
-      // Small pause for layout to settle
-      await page.waitForTimeout(500);
-
-      const metrics = await collectScrollMetrics(page);
-
-      reportScrollMetrics(
-        testInfo,
-        `scroll (${tier.name}: ${tier.lines} lines, ${tier.comments} comments)`,
-        metrics,
-      );
-    } finally {
-      await cleanup();
-    }
-  });
-}

package/e2e/perf/tab-switch.spec.ts

@@ -1,69 +0,0 @@
-import { test } from "@playwright/test";
-import { getFixturePath, TAB_SWITCH_TIER, TIERS } from "./fixtures/generate";
-import {
-  measureInteraction,
-  reportInteraction,
-  waitForHighlightCount,
-} from "./utils/metrics";
-import { spawnPerfCli } from "./utils/perf-cli";
-
-const tierA = TIERS[0]; // medium
-const tierB = TAB_SWITCH_TIER; // medium-b
-
-test(`tab-switch: between two ${tierA.name} documents`, async ({
-  page,
-}, testInfo) => {
-  const pathA = getFixturePath(tierA);
-  const pathB = getFixturePath(tierB);
-
-  const { url, cleanup } = await spawnPerfCli([pathA, pathB], { port: 4640 });
-
-  try {
-    await page.goto(url);
-
-    // Wait for first document to be fully loaded with highlights
-    await waitForHighlightCount(page, tierA.comments);
-    await page.waitForTimeout(500);
-
-    // Find the second tab and measure the switch
-    const duration = await measureInteraction(
-      page,
-      "tab-switch",
-      async () => {
-        // Click the second tab — tabs display file names
-        const tabs = page.locator('[role="tab"], button').filter({
-          hasText: tierB.fileName.replace(".md", ""),
-        });
-
-        // If tabs aren't labeled with role="tab", find by filename text
-        const tabCount = await tabs.count();
-        if (tabCount > 0) {
-          await tabs.first().click();
-        } else {
-          // Fallback: find any clickable element containing the filename
-          const allButtons = page.locator("button, a");
-          const count = await allButtons.count();
-          for (let i = 0; i < count; i++) {
-            const text = await allButtons.nth(i).textContent();
-            if (text?.includes("medium-b")) {
-              await allButtons.nth(i).click();
-              break;
-            }
-          }
-        }
-      },
-      async () => {
-        // Wait for the second document's highlights to paint
-        await waitForHighlightCount(page, tierB.comments, 60_000);
-      },
-    );
-
-    reportInteraction(
-      testInfo,
-      `tab-switch: ${tierA.name} → ${tierB.name} (${tierA.comments} → ${tierB.comments} comments)`,
-      duration,
-    );
-  } finally {
-    await cleanup();
-  }
-});

package/e2e/perf/text-selection.spec.ts

@@ -1,119 +0,0 @@
-import { test } from "@playwright/test";
-import { getFixturePath, TIERS } from "./fixtures/generate";
-import {
-  measureInteraction,
-  reportInteraction,
-  waitForHighlightCount,
-} from "./utils/metrics";
-import { spawnPerfCli } from "./utils/perf-cli";
-
-// Use medium tier
-const tier = TIERS[0];
-const ITERATIONS = 5;
-
-test(`text-selection: ${tier.name} (${tier.lines} lines, ${tier.comments} comments)`, async ({
-  page,
-}, testInfo) => {
-  const fixturePath = getFixturePath(tier);
-  const { url, cleanup } = await spawnPerfCli(fixturePath, { port: 4630 });
-
-  try {
-    await page.goto(url);
-    await waitForHighlightCount(page, tier.comments);
-    await page.waitForTimeout(300);
-
-    // Collect selectable text positions distributed across the document
-    const targets = await page.evaluate((count) => {
-      const article = document.querySelector("article");
-      if (!article) throw new Error("Article not found");
-
-      const paragraphs = [...article.querySelectorAll("p")];
-      const step = Math.floor(paragraphs.length / (count + 1));
-
-      return paragraphs
-        .filter((_, i) => i % step === 0)
-        .slice(0, count)
-        .map((p) => {
-          const text = (p.textContent || "").slice(0, 25).trim();
-          return text;
-        })
-        .filter((t) => t.length > 10);
-    }, ITERATIONS);
-
-    const durations: number[] = [];
-
-    for (const targetText of targets) {
-      // Clear any existing selection state
-      await page.evaluate(() => window.getSelection()?.removeAllRanges());
-      await page.waitForTimeout(100);
-
-      const duration = await measureInteraction(
-        page,
-        `text-selection-${targets.indexOf(targetText)}`,
-        async () => {
-          // Trigger text selection via custom event
-          await page.evaluate((text) => {
-            const article = document.querySelector("article");
-            if (!article) throw new Error("Article not found");
-
-            const walker = document.createTreeWalker(
-              article,
-              NodeFilter.SHOW_TEXT,
-            );
-            let currentOffset = 0;
-
-            while (walker.nextNode()) {
-              const textNode = walker.currentNode as Text;
-              const content = textNode.textContent || "";
-              const index = content.indexOf(text);
-
-              if (index !== -1) {
-                const startOffset = currentOffset + index;
-                const endOffset = startOffset + text.length;
-                window.dispatchEvent(
-                  new CustomEvent("test:select-text", {
-                    detail: { text, startOffset, endOffset },
-                  }),
-                );
-                return;
-              }
-
-              currentOffset += content.length;
-            }
-
-            throw new Error(`Text "${text}" not found`);
-          }, targetText);
-        },
-        async () => {
-          // Wait for comment input textarea to appear
-          await page
-            .locator('textarea[placeholder="Add your comment..."]')
-            .waitFor({ state: "visible", timeout: 10_000 });
-        },
-      );
-
-      durations.push(duration);
-
-      // Cancel the selection (press Escape to dismiss the comment input)
-      await page.keyboard.press("Escape");
-      await page.waitForTimeout(100);
-    }
-
-    // Report median
-    durations.sort((a, b) => a - b);
-    const median = durations[Math.floor(durations.length / 2)];
-
-    reportInteraction(
-      testInfo,
-      `text-selection: median of ${durations.length} iterations (${tier.name})`,
-      median,
-    );
-
-    // Also report all iterations
-    console.log(
-      `  All iterations: ${durations.map((d) => `${Math.round(d)}ms`).join(", ")}`,
-    );
-  } finally {
-    await cleanup();
-  }
-});