@peaske7/readit 0.1.8 → 0.2.1

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 "../types";
+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
@@ -124,7 +113,7 @@ describe("getLineHint", () => {
 
   it("returns range hint for multiple lines", () => {
     const content = "line one\nline two\nline three";
-    expect(getLineHint(content, 0, 20)).toBe("L1-3");
+    expect(getLineHint(content, 0, 20)).toBe("L1-L3");
   });
 });
 
@@ -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,7 +327,6 @@ describe("serializeComments", () => {
           id: "12345678",
           selectedText: "selected text",
           comment: "My comment",
-          createdAt: "2024-12-24T10:30:00Z",
           lineHint: "L42",
           startOffset: 100,
           endOffset: 113,
@@ -347,7 +334,7 @@ describe("serializeComments", () => {
       ],
     };
     const result = serializeComments(file);
-    expect(result).toContain("<!-- c:12345678|L42|2024-12-24T10:30:00Z -->");
+    expect(result).toContain("<!-- c:12345678|L42 -->");
     expect(result).toContain("> selected text");
     expect(result).toContain("My comment");
   });
@@ -362,8 +349,7 @@ describe("serializeComments", () => {
           id: "12345678",
           selectedText: "line one\nline two",
           comment: "Comment",
-          createdAt: "2024-12-24T10:30:00Z",
-          lineHint: "L42-43",
+          lineHint: "L42-L43",
           startOffset: 100,
           endOffset: 120,
         },
@@ -384,7 +370,6 @@ describe("serializeComments", () => {
           id: "12345678",
           selectedText: "truncated text...",
           comment: "Comment",
-          createdAt: "2024-12-24T10:30:00Z",
           lineHint: "L42",
           startOffset: 100,
           endOffset: 500,
@@ -408,7 +393,6 @@ describe("serializeComments", () => {
           id: "12345678",
           selectedText: "short text",
           comment: "Comment",
-          createdAt: "2024-12-24T10:30:00Z",
           lineHint: "L42",
           startOffset: 100,
           endOffset: 110,
@@ -429,7 +413,6 @@ describe("serializeComments", () => {
           id: "12345678",
           selectedText: "selected text",
           comment: "My comment",
-          createdAt: "2024-12-24T10:30:00Z",
           lineHint: "L42",
           startOffset: 100,
           endOffset: 113,
@@ -438,8 +421,7 @@ describe("serializeComments", () => {
           id: "87654321",
           selectedText: "another\nmultiline\nselection",
           comment: "Another comment with\n\nmultiple paragraphs.",
-          createdAt: "2024-12-24T11:00:00Z",
-          lineHint: "L50-52",
+          lineHint: "L50-L52",
           startOffset: 200,
           endOffset: 230,
         },
@@ -460,10 +442,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 +488,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 +527,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);

package/src/lib/comment-storage.ts

@@ -1,17 +1,14 @@
 import * as crypto from "node:crypto";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { Comment, CommentFile } from "../types";
+import type { Comment, CommentFile } from "../schema";
 
 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;
 
-/**
- * Truncate very long selections to first ~500 + ... + last ~500 chars.
- */
 export function truncateSelection(text: string): string {
   if (text.length <= MAX_SELECTION_LENGTH) {
     return text;
@@ -22,18 +19,9 @@ 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 {
-  // Resolve to absolute path
   const absolute = path.resolve(sourcePath);
-
-  // Remove leading slash and drive letter (Windows)
   const normalized = absolute.replace(/^\//, "").replace(/^[A-Z]:[\\/]/, "");
-
-  // Get filename without extension, add .comments.md
   const ext = path.extname(normalized);
   const withoutExt = normalized.slice(0, -ext.length || undefined);
 
@@ -45,9 +33,6 @@ export function getCommentPath(sourcePath: string): string {
   );
 }
 
-/**
- * Compute SHA-256 hash of content, returning first 16 characters.
- */
 export function computeHash(content: string): string {
   return crypto
     .createHash("sha256")
@@ -56,18 +41,12 @@ export function computeHash(content: string): string {
     .slice(0, HASH_LENGTH);
 }
 
-/**
- * Get line number (1-indexed) for a character offset in content.
- */
 export function getLineNumber(content: string, offset: number): number {
   if (offset <= 0 || content.length === 0) return 1;
   const clampedOffset = Math.min(offset, content.length);
   return content.slice(0, clampedOffset).split("\n").length;
 }
 
-/**
- * Get line range string for a selection (e.g., "L42" or "L42-45").
- */
 export function getLineHint(
   content: string,
   startOffset: number,
@@ -75,12 +54,9 @@ export function getLineHint(
 ): string {
   const startLine = getLineNumber(content, startOffset);
   const endLine = getLineNumber(content, endOffset);
-  return startLine === endLine ? `L${startLine}` : `L${startLine}-${endLine}`;
+  return startLine === endLine ? `L${startLine}` : `L${startLine}-L${endLine}`;
 }
 
-/**
- * Parse a comment file's markdown content into a CommentFile structure.
- */
 export function parseCommentFile(content: string): CommentFile {
   const result: CommentFile = {
     source: "",
@@ -93,7 +69,6 @@ export function parseCommentFile(content: string): CommentFile {
     return result;
   }
 
-  // Parse YAML front matter
   const frontMatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
   if (frontMatterMatch) {
     const frontMatter = frontMatterMatch[1];
@@ -105,7 +80,6 @@ export function parseCommentFile(content: string): CommentFile {
     if (hashMatch) result.hash = hashMatch[1].trim();
     if (versionMatch) result.version = Number.parseInt(versionMatch[1], 10);
 
-    // Validate version compatibility
     if (result.version > FORMAT_VERSION) {
       throw new Error(
         `Comment file requires readit v${result.version} or higher. ` +
@@ -114,11 +88,23 @@ export function parseCommentFile(content: string): CommentFile {
     }
   }
 
-  // Remove front matter and split by separator
   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);
@@ -128,35 +114,29 @@ export function parseCommentFile(content: string): CommentFile {
   return result;
 }
 
-/**
- * Parse a single comment block.
- */
 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] = metadataMatch;
 
-  // Extract anchor prefix if present: <!-- anchor:{prefix} -->
   const anchorMatch = block.match(/<!--\s*anchor:(.+?)\s*-->/);
   const anchorPrefix = anchorMatch ? anchorMatch[1] : undefined;
 
-  // Extract selected text from blockquote
   const blockquoteMatch = block.match(/^>\s*(.+(?:\n>\s*.+)*)$/m);
   if (!blockquoteMatch) {
     return undefined;
   }
 
-  // Remove the "> " prefix from each line
   const selectedText = blockquoteMatch[1]
     .split("\n")
     .map((line) => line.replace(/^>\s*/, ""))
     .join("\n");
 
-  // Extract comment body (everything after blockquote)
   const afterBlockquote = block.slice(
     block.indexOf(blockquoteMatch[0]) + blockquoteMatch[0].length,
   );
@@ -166,22 +146,16 @@ function parseCommentBlock(block: string): Comment | undefined {
     id,
     selectedText,
     comment: commentBody,
-    createdAt: createdAt.trim(),
     lineHint,
     anchorPrefix,
-    // Offsets will be resolved by anchor matching when loading
     startOffset: 0,
     endOffset: 0,
   };
 }
 
-/**
- * Serialize a CommentFile structure to markdown content.
- */
 export function serializeComments(file: CommentFile): string {
   const lines: string[] = [];
 
-  // YAML front matter
   lines.push("---");
   lines.push(`source: ${file.source}`);
   lines.push(`hash: ${file.hash}`);
@@ -189,7 +163,6 @@ export function serializeComments(file: CommentFile): string {
   lines.push("---");
   lines.push("");
 
-  // Comments
   for (const comment of file.comments) {
     lines.push(serializeComment(comment));
     lines.push("");
@@ -200,28 +173,21 @@ export function serializeComments(file: CommentFile): string {
   return lines.join("\n");
 }
 
-/**
- * Serialize a single comment to markdown block.
- */
 function serializeComment(comment: Comment): string {
   const lines: string[] = [];
 
-  // Metadata as HTML comment
   const lineHint = comment.lineHint || "L0";
-  lines.push(`<!-- c:${comment.id}|${lineHint}|${comment.createdAt} -->`);
+  lines.push(`<!-- c:${comment.id}|${lineHint} -->`);
 
-  // Anchor prefix for long selections (used for anchor matching when text is truncated)
   if (comment.anchorPrefix) {
     lines.push(`<!-- anchor:${comment.anchorPrefix} -->`);
   }
 
-  // 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);
@@ -230,9 +196,6 @@ function serializeComment(comment: Comment): string {
   return lines.join("\n");
 }
 
-/**
- * Create a new comment with a generated ID and current timestamp.
- */
 export function createComment(
   selectedText: string,
   commentText: string,
@@ -242,8 +205,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;
 
@@ -251,11 +212,9 @@ export function createComment(
     id,
     selectedText: truncateSelection(selectedText),
     comment: commentText,
-    createdAt,
     startOffset,
     endOffset,
     lineHint,
-    // Store first N chars for anchor matching when text is truncated
     anchorPrefix: needsTruncation
       ? selectedText.slice(0, ANCHOR_PREFIX_LENGTH)
       : undefined,

package/src/lib/export.bench.ts

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

package/src/lib/export.ts

@@ -1,19 +1,12 @@
-import type { Comment, Document } from "../types";
+import type { Comment, Document } from "../schema";
 
-export function generatePrompt(comments: Comment[], fileName: string): string {
-  const prompt = comments
-    .map((c) => {
-      return `---\nSelected text: "${c.selectedText}"\nComment: ${c.comment}`;
-    })
-    .join("\n\n");
-
-  return `# Review Comments for ${fileName}\n\n${prompt}`;
+export function formatComment(c: Comment): string {
+  const line = c.lineHint ? `[${c.lineHint}] ` : "";
+  return `${line}"${c.selectedText}"\n${c.comment}`;
 }
 
-export function generateRawText(comments: Comment[]): string {
-  return comments
-    .map((c) => `${c.selectedText}\n\n${c.comment}`)
-    .join("\n\n---\n\n");
+export function generatePrompt(comments: Comment[], fileName: string): string {
+  return `# Review Comments for ${fileName}\n\n${comments.map(formatComment).join("\n\n---\n\n")}`;
 }
 
 export function exportCommentsAsJson(
@@ -27,7 +20,7 @@ export function exportCommentsAsJson(
     comments: comments.map((c) => ({
       selectedText: c.selectedText,
       comment: c.comment,
-      createdAt: c.createdAt,
+      lineHint: c.lineHint,
     })),
   };
 

package/src/lib/headings.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest";
+import { parseMarkdownHeadings } from "./headings";
+
+describe("parseMarkdownHeadings", () => {
+  it("extracts basic headings", () => {
+    const content = `# Heading 1
+## Heading 2
+### Heading 3`;
+
+    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 },
+    ]);
+  });
+
+  it("handles duplicate headings", () => {
+    const content = `## Section
+## Section
+## Section`;
+
+    expect(parseMarkdownHeadings(content)).toEqual([
+      { id: "section", text: "Section", level: 2 },
+      { id: "section-1", text: "Section", level: 2 },
+      { id: "section-2", text: "Section", level: 2 },
+    ]);
+  });
+
+  it("ignores headings inside fenced code blocks", () => {
+    const content = `# Real Heading
+
+\`\`\`bash
+# This is a comment, not a heading
+echo "hello"
+\`\`\`
+
+## Another Real Heading`;
+
+    expect(parseMarkdownHeadings(content)).toEqual([
+      { id: "real-heading", text: "Real Heading", level: 1 },
+      { id: "another-real-heading", text: "Another Real Heading", level: 2 },
+    ]);
+  });
+
+  it("ignores headings inside triple-tilde code blocks", () => {
+    const content = `# Real Heading
+
+~~~python
+# Python comment
+def foo():
+    pass
+~~~
+
+## Another Real Heading`;
+
+    expect(parseMarkdownHeadings(content)).toEqual([
+      { id: "real-heading", text: "Real Heading", level: 1 },
+      { id: "another-real-heading", text: "Another Real Heading", level: 2 },
+    ]);
+  });
+
+  it("handles multiple code blocks", () => {
+    const content = `# Introduction
+
+\`\`\`bash
+# Comment 1
+\`\`\`
+
+## Methods
+
+\`\`\`python
+# Comment 2
+\`\`\`
+
+## Results`;
+
+    expect(parseMarkdownHeadings(content)).toEqual([
+      { id: "introduction", text: "Introduction", level: 1 },
+      { id: "methods", text: "Methods", level: 2 },
+      { id: "results", text: "Results", level: 2 },
+    ]);
+  });
+
+  it("handles code block with language specifier", () => {
+    const content = `# Setup
+
+\`\`\`bash
+# Use a custom port
+npx readit document.md --port 3000
+\`\`\`
+
+## Usage`;
+
+    expect(parseMarkdownHeadings(content)).toEqual([
+      { id: "setup", text: "Setup", level: 1 },
+      { id: "usage", text: "Usage", level: 2 },
+    ]);
+  });
+
+  it("returns empty array for empty content", () => {
+    expect(parseMarkdownHeadings("")).toEqual([]);
+  });
+});

package/src/lib/headings.ts

@@ -0,0 +1,44 @@
+export interface Heading {
+  id: string;
+  text: string;
+  level: 1 | 2 | 3 | 4 | 5 | 6;
+}
+
+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, "");
+  result = result.replace(/(?:^|\n\n)((?:(?:[ ]{4}|\t).+\n?)+)/g, "\n\n");
+
+  return result;
+}
+
+export function parseMarkdownHeadings(content: string): Heading[] {
+  const headings: Heading[] = [];
+  const seenIds = new Map<string, number>();
+  const contentWithoutCode = stripCodeBlocks(content);
+
+  const regex = /^(#{1,6})\s+(.+)$/gm;
+  let match = regex.exec(contentWithoutCode);
+
+  while (match !== null) {
+    const level = match[1].length as 1 | 2 | 3 | 4 | 5 | 6;
+    const text = match[2].trim();
+    const baseId = slugify(text);
+    const count = seenIds.get(baseId) ?? 0;
+    const id = count > 0 ? `${baseId}-${count}` : baseId;
+    seenIds.set(baseId, count + 1);
+
+    headings.push({ id, text, level });
+    match = regex.exec(contentWithoutCode);
+  }
+
+  return headings;
+}