@peaske7/readit 0.2.0 → 0.3.0-rc.0

package/src/lib/comment-storage.test.ts

@@ -1,8 +1,12 @@
-import type * as os from "node:os";
 import { describe, expect, it, vi } from "vitest";
 import type { CommentFile } from "../schema";
 import { COMMENT_FILE_LARGE } from "./__fixtures__/bench-data";
-import {
+
+vi.mock("node:os", () => ({
+  homedir: () => "/home/testuser",
+}));
+
+const {
   computeHash,
   createComment,
   getCommentPath,
@@ -11,16 +15,7 @@ import {
   parseCommentFile,
   serializeComments,
   truncateSelection,
-} from "./comment-storage";
-
-// Mock os.homedir for consistent test results
-vi.mock("node:os", async () => {
-  const actual = await vi.importActual<typeof os>("node:os");
-  return {
-    ...actual,
-    homedir: vi.fn(() => "/home/testuser"),
-  };
-});
+} = await import("./comment-storage");
 
 describe("getCommentPath", () => {
   it("handles absolute path", () => {
@@ -37,11 +32,6 @@ describe("getCommentPath", () => {
     );
   });
 
-  it("handles HTML files", () => {
-    const result = getCommentPath("/docs/api.html");
-    expect(result).toBe("/home/testuser/.readit/comments/docs/api.comments.md");
-  });
-
   it("handles root path", () => {
     const result = getCommentPath("/file.md");
     expect(result).toBe("/home/testuser/.readit/comments/file.comments.md");
@@ -103,7 +93,6 @@ describe("getLineNumber", () => {
   });
 
   it("handles many lines", () => {
-    // "line\n" repeated 100 times, each segment is 5 chars
     const content = Array(100).fill("line").join("\n");
     expect(getLineNumber(content, 0)).toBe(1); // Start of line 1
     expect(getLineNumber(content, 250)).toBe(51); // After 50 newlines = line 51
@@ -169,7 +158,6 @@ This is my comment.
     expect(result.comments[0].selectedText).toBe("selected text here");
     expect(result.comments[0].comment).toBe("This is my comment.");
     expect(result.comments[0].lineHint).toBe("L42");
-    expect(result.comments[0].createdAt).toBe("2024-12-24T10:30:00Z");
   });
 
   it("parses multiple comments", () => {
@@ -339,15 +327,15 @@ describe("serializeComments", () => {
           id: "12345678",
           selectedText: "selected text",
           comment: "My comment",
-          createdAt: "2024-12-24T10:30:00Z",
           lineHint: "L42",
+          createdAt: "2026-05-09T00:00:00Z",
           startOffset: 100,
           endOffset: 113,
         },
       ],
     };
     const result = serializeComments(file);
-    expect(result).toContain("<!-- c:12345678|L42|2024-12-24T10:30:00Z -->");
+    expect(result).toContain("<!-- c:12345678|L42|2026-05-09T00:00:00Z -->");
     expect(result).toContain("> selected text");
     expect(result).toContain("My comment");
   });
@@ -362,7 +350,6 @@ describe("serializeComments", () => {
           id: "12345678",
           selectedText: "line one\nline two",
           comment: "Comment",
-          createdAt: "2024-12-24T10:30:00Z",
           lineHint: "L42-L43",
           startOffset: 100,
           endOffset: 120,
@@ -384,7 +371,6 @@ describe("serializeComments", () => {
           id: "12345678",
           selectedText: "truncated text...",
           comment: "Comment",
-          createdAt: "2024-12-24T10:30:00Z",
           lineHint: "L42",
           startOffset: 100,
           endOffset: 500,
@@ -408,7 +394,6 @@ describe("serializeComments", () => {
           id: "12345678",
           selectedText: "short text",
           comment: "Comment",
-          createdAt: "2024-12-24T10:30:00Z",
           lineHint: "L42",
           startOffset: 100,
           endOffset: 110,
@@ -429,7 +414,6 @@ describe("serializeComments", () => {
           id: "12345678",
           selectedText: "selected text",
           comment: "My comment",
-          createdAt: "2024-12-24T10:30:00Z",
           lineHint: "L42",
           startOffset: 100,
           endOffset: 113,
@@ -438,7 +422,6 @@ describe("serializeComments", () => {
           id: "87654321",
           selectedText: "another\nmultiline\nselection",
           comment: "Another comment with\n\nmultiple paragraphs.",
-          createdAt: "2024-12-24T11:00:00Z",
           lineHint: "L50-L52",
           startOffset: 200,
           endOffset: 230,
@@ -460,10 +443,42 @@ describe("serializeComments", () => {
         original.comments[i].selectedText,
       );
       expect(parsed.comments[i].lineHint).toBe(original.comments[i].lineHint);
-      expect(parsed.comments[i].createdAt).toBe(original.comments[i].createdAt);
     }
   });
 
+  it("roundtrip: survives a markdown horizontal rule inside a comment body", () => {
+    const original: CommentFile = {
+      source: "/test.md",
+      hash: "abc123",
+      version: 1,
+      comments: [
+        {
+          id: "aaaaaaaa",
+          selectedText: "first selected",
+          comment: "before\n\n---\n\nafter",
+          lineHint: "L1",
+          startOffset: 0,
+          endOffset: 14,
+        },
+        {
+          id: "bbbbbbbb",
+          selectedText: "second selected",
+          comment: "second body",
+          lineHint: "L5",
+          startOffset: 50,
+          endOffset: 65,
+        },
+      ],
+    };
+
+    const serialized = serializeComments(original);
+    const parsed = parseCommentFile(serialized);
+
+    expect(parsed.comments).toHaveLength(2);
+    expect(parsed.comments[0].id).toBe("aaaaaaaa");
+    expect(parsed.comments[1].id).toBe("bbbbbbbb");
+  });
+
   it("roundtrip: preserves anchorPrefix through serialize/parse", () => {
     const original: CommentFile = {
       source: "/test.md",
@@ -474,7 +489,6 @@ describe("serializeComments", () => {
           id: "12345678",
           selectedText: "truncated text\n...\nend of text",
           comment: "Comment on long selection",
-          createdAt: "2024-12-24T10:30:00Z",
           lineHint: "L42",
           startOffset: 100,
           endOffset: 2000,
@@ -514,11 +528,6 @@ describe("createComment", () => {
     expect(comment.lineHint).toBe("L2");
   });
 
-  it("generates ISO timestamp", () => {
-    const comment = createComment("text", "comment", 0, 4, "text");
-    expect(comment.createdAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
-  });
-
   it("truncates very long selections", () => {
     const longText = "a".repeat(2000);
     const comment = createComment(longText, "comment", 0, 2000, longText);
@@ -583,6 +592,67 @@ describe("truncateSelection", () => {
   });
 });
 
+describe("parseCommentFile cross-runtime format", () => {
+  it("parses 2-field marker (legacy TS-written files)", () => {
+    const content = `---
+source: /test.md
+hash: abc
+version: 1
+---
+
+<!-- c:abcd1234|L5 -->
+> selected text
+some comment
+
+---
+`;
+    const parsed = parseCommentFile(content);
+    expect(parsed.comments).toHaveLength(1);
+    expect(parsed.comments[0].id).toBe("abcd1234");
+    expect(parsed.comments[0].lineHint).toBe("L5");
+    expect(parsed.comments[0].createdAt).toBeUndefined();
+  });
+
+  it("parses 3-field marker (Go-written files)", () => {
+    const content = `---
+source: /test.md
+hash: abc
+version: 1
+---
+
+<!-- c:abcd1234|L5|2026-05-09T12:34:56.789Z -->
+> selected text
+some comment
+
+---
+`;
+    const parsed = parseCommentFile(content);
+    expect(parsed.comments).toHaveLength(1);
+    expect(parsed.comments[0].createdAt).toBe("2026-05-09T12:34:56.789Z");
+  });
+
+  it("serializeComments writes 3-field marker", () => {
+    const file: CommentFile = {
+      source: "/test.md",
+      hash: "abc",
+      version: 1,
+      comments: [
+        {
+          id: "abcd1234",
+          selectedText: "selected",
+          comment: "body",
+          lineHint: "L1",
+          createdAt: "2026-05-09T00:00:00Z",
+          startOffset: 0,
+          endOffset: 8,
+        },
+      ],
+    };
+    const serialized = serializeComments(file);
+    expect(serialized).toContain("<!-- c:abcd1234|L1|2026-05-09T00:00:00Z -->");
+  });
+});
+
 describe("parseCommentFile version check", () => {
   it("accepts current version", () => {
     const content = `---

package/src/lib/comment-storage.ts

@@ -7,7 +7,7 @@ const FORMAT_VERSION = 1;
 const HASH_LENGTH = 16;
 const MAX_SELECTION_LENGTH = 1000;
 const TRUNCATION_MARKER = "\n...\n";
-const ANCHOR_PREFIX_LENGTH = 200; // chars stored for anchor matching when text is truncated
+const ANCHOR_PREFIX_LENGTH = 200;
 
 export function truncateSelection(text: string): string {
   if (text.length <= MAX_SELECTION_LENGTH) {
@@ -19,13 +19,8 @@ export function truncateSelection(text: string): string {
   return text.slice(0, half) + TRUNCATION_MARKER + text.slice(-half);
 }
 
-/**
- * Compute the path where comments for a source file should be stored.
- * Comments are stored in ~/.readit/comments/{absolute-path-structure}/{filename}.comments.md
- */
 export function getCommentPath(sourcePath: string): string {
   const absolute = path.resolve(sourcePath);
-  // Remove leading slash and drive letter (Windows)
   const normalized = absolute.replace(/^\//, "").replace(/^[A-Z]:[\\/]/, "");
   const ext = path.extname(normalized);
   const withoutExt = normalized.slice(0, -ext.length || undefined);
@@ -94,9 +89,22 @@ export function parseCommentFile(content: string): CommentFile {
   }
 
   const bodyContent = content.replace(/^---\n[\s\S]*?\n---\n*/, "");
-  const blocks = bodyContent.split(/\n---\n/).filter((block) => block.trim());
 
-  for (const block of blocks) {
+  const markerRe = /<!--\s*c:[^|]+\|[^|>\s]+(?:\|[^>]*)?\s*-->/g;
+  const markerStarts: number[] = [];
+  for (const m of bodyContent.matchAll(markerRe)) {
+    if (m.index !== undefined) markerStarts.push(m.index);
+  }
+
+  for (let i = 0; i < markerStarts.length; i++) {
+    const start = markerStarts[i];
+    const end =
+      i + 1 < markerStarts.length ? markerStarts[i + 1] : bodyContent.length;
+    const block = bodyContent
+      .slice(start, end)
+      .replace(/\n+---\s*$/, "")
+      .trim();
+    if (!block) continue;
     const comment = parseCommentBlock(block);
     if (comment) {
       result.comments.push(comment);
@@ -107,15 +115,16 @@ export function parseCommentFile(content: string): CommentFile {
 }
 
 function parseCommentBlock(block: string): Comment | undefined {
-  // Extract metadata from HTML comment: <!-- c:{id}|{lineHint}|{timestamp} -->
-  const metadataMatch = block.match(/<!--\s*c:([^|]+)\|([^|]+)\|([^>]+)\s*-->/);
+  const metadataMatch = block.match(
+    /<!--\s*c:([^|]+)\|([^|>\s]+)(?:\|([^>]*))?\s*-->/,
+  );
   if (!metadataMatch) {
     return undefined;
   }
 
-  const [, id, lineHint, createdAt] = metadataMatch;
+  const [, id, lineHint, createdAtRaw] = metadataMatch;
+  const createdAt = createdAtRaw?.trim() || undefined;
 
-  // Extract anchor prefix if present: <!-- anchor:{prefix} -->
   const anchorMatch = block.match(/<!--\s*anchor:(.+?)\s*-->/);
   const anchorPrefix = anchorMatch ? anchorMatch[1] : undefined;
 
@@ -138,10 +147,9 @@ function parseCommentBlock(block: string): Comment | undefined {
     id,
     selectedText,
     comment: commentBody,
-    createdAt: createdAt.trim(),
     lineHint,
+    createdAt,
     anchorPrefix,
-    // Offsets will be resolved by anchor matching when loading
     startOffset: 0,
     endOffset: 0,
   };
@@ -171,7 +179,8 @@ function serializeComment(comment: Comment): string {
   const lines: string[] = [];
 
   const lineHint = comment.lineHint || "L0";
-  lines.push(`<!-- c:${comment.id}|${lineHint}|${comment.createdAt} -->`);
+  const createdAt = comment.createdAt || new Date().toISOString();
+  lines.push(`<!-- c:${comment.id}|${lineHint}|${createdAt} -->`);
 
   if (comment.anchorPrefix) {
     lines.push(`<!-- anchor:${comment.anchorPrefix} -->`);
@@ -199,8 +208,6 @@ export function createComment(
 ): Comment {
   const id = crypto.randomUUID().slice(0, 8);
   const lineHint = getLineHint(sourceContent, startOffset, endOffset);
-  const now = new Date();
-  const createdAt = now.toISOString();
 
   const needsTruncation = selectedText.length > MAX_SELECTION_LENGTH;
 
@@ -208,10 +215,10 @@ export function createComment(
     id,
     selectedText: truncateSelection(selectedText),
     comment: commentText,
-    createdAt,
     startOffset,
     endOffset,
     lineHint,
+    createdAt: new Date().toISOString(),
     anchorPrefix: needsTruncation
       ? selectedText.slice(0, ANCHOR_PREFIX_LENGTH)
       : undefined,

package/src/lib/export.bench.ts

@@ -0,0 +1,21 @@
+import { bench, describe } from "vitest";
+import { COMMENTS_10, COMMENTS_50 } from "./__fixtures__/bench-data";
+import { formatComment, generatePrompt } from "./export";
+
+describe("formatComment", () => {
+  const comment = COMMENTS_10[0];
+
+  bench("single comment", () => {
+    formatComment(comment);
+  });
+});
+
+describe("generatePrompt", () => {
+  bench("10 comments", () => {
+    generatePrompt(COMMENTS_10, "benchmark.md");
+  });
+
+  bench("50 comments", () => {
+    generatePrompt(COMMENTS_50, "benchmark.md");
+  });
+});

package/src/lib/export.ts

@@ -21,7 +21,6 @@ export function exportCommentsAsJson(
       selectedText: c.selectedText,
       comment: c.comment,
       lineHint: c.lineHint,
-      createdAt: c.createdAt,
     })),
   };
 

package/src/lib/fetch-or-throw.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { fetchOrThrow } from "./fetch-or-throw";
+
+function mockFetch(response: Response) {
+  return vi.spyOn(globalThis, "fetch").mockResolvedValue(response);
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("fetchOrThrow", () => {
+  it("returns response on 2xx", async () => {
+    mockFetch(new Response("ok", { status: 200 }));
+    const res = await fetchOrThrow("/api", {}, "fallback");
+    expect(res.ok).toBe(true);
+  });
+
+  it("throws body.error when response is not ok and body has error field", async () => {
+    mockFetch(
+      new Response(JSON.stringify({ error: "EACCES: permission denied" }), {
+        status: 500,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+    await expect(fetchOrThrow("/api", {}, "fallback")).rejects.toThrow(
+      "EACCES: permission denied",
+    );
+  });
+
+  it("falls back to statusText when body is not JSON", async () => {
+    mockFetch(
+      new Response("not json", { status: 500, statusText: "Server Error" }),
+    );
+    await expect(fetchOrThrow("/api", {}, "fallback")).rejects.toThrow(
+      "Server Error",
+    );
+  });
+
+  it("falls back to fallback message when statusText is empty", async () => {
+    mockFetch(new Response("", { status: 500, statusText: "" }));
+    await expect(fetchOrThrow("/api", {}, "fallback message")).rejects.toThrow(
+      "fallback message",
+    );
+  });
+
+  it("falls back to statusText when body is JSON but lacks error field", async () => {
+    mockFetch(
+      new Response(JSON.stringify({ ok: false }), {
+        status: 500,
+        statusText: "Internal Error",
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+    await expect(fetchOrThrow("/api", {}, "fallback")).rejects.toThrow(
+      "Internal Error",
+    );
+  });
+});

package/src/lib/fetch-or-throw.ts

@@ -0,0 +1,12 @@
+export async function fetchOrThrow(
+  url: string,
+  init: RequestInit,
+  fallback: string,
+): Promise<Response> {
+  const response = await fetch(url, init);
+  if (!response.ok) {
+    const body = await response.json().catch(() => null);
+    throw new Error(body?.error || response.statusText || fallback);
+  }
+  return response;
+}

package/src/{hooks/useHeadings.test.ts → lib/headings.test.ts}

@@ -1,16 +1,13 @@
-import { renderHook } from "@testing-library/react";
 import { describe, expect, it } from "vitest";
-import { useHeadings } from "./useHeadings";
+import { parseMarkdownHeadings } from "./headings";
 
-describe("useHeadings", () => {
+describe("parseMarkdownHeadings", () => {
   it("extracts basic headings", () => {
     const content = `# Heading 1
 ## Heading 2
 ### Heading 3`;
 
-    const { result } = renderHook(() => useHeadings(content));
-
-    expect(result.current).toEqual([
+    expect(parseMarkdownHeadings(content)).toEqual([
       { id: "heading-1", text: "Heading 1", level: 1 },
       { id: "heading-2", text: "Heading 2", level: 2 },
       { id: "heading-3", text: "Heading 3", level: 3 },
@@ -22,9 +19,7 @@ describe("useHeadings", () => {
 ## Section
 ## Section`;
 
-    const { result } = renderHook(() => useHeadings(content));
-
-    expect(result.current).toEqual([
+    expect(parseMarkdownHeadings(content)).toEqual([
       { id: "section", text: "Section", level: 2 },
       { id: "section-1", text: "Section", level: 2 },
       { id: "section-2", text: "Section", level: 2 },
@@ -41,9 +36,7 @@ echo "hello"
 
 ## Another Real Heading`;
 
-    const { result } = renderHook(() => useHeadings(content));
-
-    expect(result.current).toEqual([
+    expect(parseMarkdownHeadings(content)).toEqual([
       { id: "real-heading", text: "Real Heading", level: 1 },
       { id: "another-real-heading", text: "Another Real Heading", level: 2 },
     ]);
@@ -60,9 +53,7 @@ def foo():
 
 ## Another Real Heading`;
 
-    const { result } = renderHook(() => useHeadings(content));
-
-    expect(result.current).toEqual([
+    expect(parseMarkdownHeadings(content)).toEqual([
       { id: "real-heading", text: "Real Heading", level: 1 },
       { id: "another-real-heading", text: "Another Real Heading", level: 2 },
     ]);
@@ -83,9 +74,7 @@ def foo():
 
 ## Results`;
 
-    const { result } = renderHook(() => useHeadings(content));
-
-    expect(result.current).toEqual([
+    expect(parseMarkdownHeadings(content)).toEqual([
       { id: "introduction", text: "Introduction", level: 1 },
       { id: "methods", text: "Methods", level: 2 },
       { id: "results", text: "Results", level: 2 },
@@ -102,16 +91,13 @@ npx readit document.md --port 3000
 
 ## Usage`;
 
-    const { result } = renderHook(() => useHeadings(content));
-
-    expect(result.current).toEqual([
+    expect(parseMarkdownHeadings(content)).toEqual([
       { id: "setup", text: "Setup", level: 1 },
       { id: "usage", text: "Usage", level: 2 },
     ]);
   });
 
-  it("returns empty array for null content", () => {
-    const { result } = renderHook(() => useHeadings(null));
-    expect(result.current).toEqual([]);
+  it("returns empty array for empty content", () => {
+    expect(parseMarkdownHeadings("")).toEqual([]);
   });
 });

package/src/{hooks/useHeadings.ts → lib/headings.ts}

@@ -1,21 +1,26 @@
-import { useMemo } from "react";
-import { slugify } from "../lib/utils";
-
 export interface Heading {
   id: string;
   text: string;
   level: 1 | 2 | 3 | 4 | 5 | 6;
 }
 
-function stripCodeBlocks(content: string): string {
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-");
+}
+
+export function stripCodeBlocks(content: string): string {
   let result = content.replace(/^(`{3,}|~{3,}).*$[\s\S]*?^\1\s*$/gm, "");
-  // Only remove indented blocks preceded by a blank line (avoids removing list items)
   result = result.replace(/(?:^|\n\n)((?:(?:[ ]{4}|\t).+\n?)+)/g, "\n\n");
 
   return result;
 }
 
-function parseMarkdownHeadings(content: string): Heading[] {
+export function parseMarkdownHeadings(content: string): Heading[] {
   const headings: Heading[] = [];
   const seenIds = new Map<string, number>();
   const contentWithoutCode = stripCodeBlocks(content);
@@ -37,10 +42,3 @@ function parseMarkdownHeadings(content: string): Heading[] {
 
   return headings;
 }
-
-export function useHeadings(content: string | null): Heading[] {
-  return useMemo(() => {
-    if (!content) return [];
-    return parseMarkdownHeadings(content);
-  }, [content]);
-}

package/src/lib/highlight/core.test.ts

@@ -31,18 +31,14 @@ describe("findTextPosition", () => {
   describe("multiple occurrences", () => {
     it("finds closest occurrence to hint (before)", () => {
       const text = "the cat and the dog and the bird";
-      // "the" occurs at: 0, 12, 24
 
-      // Hint at 10 should find "the" at 12 (closest)
       const result = findTextPosition(text, "the", 10);
       expect(result?.start).toBe(12);
     });
 
     it("finds closest occurrence to hint (after)", () => {
       const text = "the cat and the dog and the bird";
-      // "the" occurs at: 0, 12, 24
 
-      // Hint at 30 should find "the" at 24 (closest)
       const result = findTextPosition(text, "the", 30);
       expect(result?.start).toBe(24);
     });
@@ -61,7 +57,6 @@ describe("findTextPosition", () => {
 
     it("handles exact match at hint position", () => {
       const text = "abc abc abc";
-      // "abc" occurs at: 0, 4, 8
       const result = findTextPosition(text, "abc", 4);
       expect(result?.start).toBe(4);
     });