@peaske7/readit 0.1.4 → 0.1.6

package/src/lib/comment-storage.ts

@@ -0,0 +1,263 @@
+import * as crypto from "node:crypto";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { Comment, CommentFile } from "../types";
+
+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
+
+/**
+ * Truncate very long selections to first ~500 + ... + last ~500 chars.
+ */
+export function truncateSelection(text: string): string {
+  if (text.length <= MAX_SELECTION_LENGTH) {
+    return text;
+  }
+  const half = Math.floor(
+    (MAX_SELECTION_LENGTH - TRUNCATION_MARKER.length) / 2,
+  );
+  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);
+
+  return path.join(
+    os.homedir(),
+    ".readit",
+    "comments",
+    `${withoutExt}.comments.md`,
+  );
+}
+
+/**
+ * Compute SHA-256 hash of content, returning first 16 characters.
+ */
+export function computeHash(content: string): string {
+  return crypto
+    .createHash("sha256")
+    .update(content)
+    .digest("hex")
+    .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,
+  endOffset: number,
+): string {
+  const startLine = getLineNumber(content, startOffset);
+  const endLine = getLineNumber(content, endOffset);
+  return startLine === endLine ? `L${startLine}` : `L${startLine}-${endLine}`;
+}
+
+/**
+ * Parse a comment file's markdown content into a CommentFile structure.
+ */
+export function parseCommentFile(content: string): CommentFile {
+  const result: CommentFile = {
+    source: "",
+    hash: "",
+    version: FORMAT_VERSION,
+    comments: [],
+  };
+
+  if (!content.trim()) {
+    return result;
+  }
+
+  // Parse YAML front matter
+  const frontMatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (frontMatterMatch) {
+    const frontMatter = frontMatterMatch[1];
+    const sourceMatch = frontMatter.match(/^source:\s*(.+)$/m);
+    const hashMatch = frontMatter.match(/^hash:\s*(.+)$/m);
+    const versionMatch = frontMatter.match(/^version:\s*(\d+)$/m);
+
+    if (sourceMatch) result.source = sourceMatch[1].trim();
+    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. ` +
+          `Current version supports format v${FORMAT_VERSION}.`,
+      );
+    }
+  }
+
+  // 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 comment = parseCommentBlock(block);
+    if (comment) {
+      result.comments.push(comment);
+    }
+  }
+
+  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*-->/);
+  if (!metadataMatch) {
+    return undefined;
+  }
+
+  const [, id, lineHint, createdAt] = 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,
+  );
+  const commentBody = afterBlockquote.trim();
+
+  return {
+    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}`);
+  lines.push(`version: ${file.version}`);
+  lines.push("---");
+  lines.push("");
+
+  // Comments
+  for (const comment of file.comments) {
+    lines.push(serializeComment(comment));
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+  }
+
+  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} -->`);
+
+  // 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);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Create a new comment with a generated ID and current timestamp.
+ */
+export function createComment(
+  selectedText: string,
+  commentText: string,
+  startOffset: number,
+  endOffset: number,
+  sourceContent: string,
+): 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;
+
+  return {
+    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/context.bench.ts

@@ -0,0 +1,41 @@
+import { bench, describe } from "vitest";
+import { HTML_DOC, LARGE_DOC } from "./__fixtures__/bench-data";
+import { extractContext, formatForLLM, stripHtmlTags } from "./context";
+
+describe("stripHtmlTags", () => {
+  bench("200-line HTML document", () => {
+    stripHtmlTags(HTML_DOC);
+  });
+
+  bench("short HTML string", () => {
+    stripHtmlTags(
+      "<p>Hello &amp; <strong>world</strong> with &#60;entities&#62;</p>",
+    );
+  });
+});
+
+describe("extractContext", () => {
+  bench("single-line selection, markdown", () => {
+    extractContext({ content: LARGE_DOC, startOffset: 500, endOffset: 530 });
+  });
+
+  bench("multi-line selection, markdown", () => {
+    extractContext({ content: LARGE_DOC, startOffset: 500, endOffset: 800 });
+  });
+
+  bench("HTML content (triggers stripHtmlTags)", () => {
+    extractContext({ content: HTML_DOC, startOffset: 100, endOffset: 200 });
+  });
+});
+
+describe("formatForLLM", () => {
+  const ctx = extractContext({
+    content: LARGE_DOC,
+    startOffset: 500,
+    endOffset: 530,
+  });
+
+  bench("format with comment", () => {
+    formatForLLM({ context: ctx, fileName: "doc.md", comment: "Needs review" });
+  });
+});

package/src/lib/context.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, it } from "vitest";
+import { extractContext, formatForLLM, stripHtmlTags } from "./context";
+
+describe("stripHtmlTags", () => {
+  it("removes simple HTML tags", () => {
+    expect(stripHtmlTags("<p>Hello</p>")).toBe("Hello");
+    expect(stripHtmlTags("<div><span>Nested</span></div>")).toBe("Nested");
+  });
+
+  it("removes script and style content entirely", () => {
+    expect(stripHtmlTags('<script>alert("xss")</script>text')).toBe("text");
+    expect(stripHtmlTags("<style>.foo { color: red }</style>text")).toBe(
+      "text",
+    );
+  });
+
+  it("decodes common named entities", () => {
+    expect(stripHtmlTags("&lt;tag&gt;")).toBe("<tag>");
+    expect(stripHtmlTags("&amp;&nbsp;&quot;&#39;")).toBe("& \"'");
+  });
+
+  it("decodes numeric entities (decimal)", () => {
+    expect(stripHtmlTags("&#65;&#66;&#67;")).toBe("ABC");
+  });
+
+  it("decodes numeric entities (hex)", () => {
+    expect(stripHtmlTags("&#x41;&#x42;&#x43;")).toBe("ABC");
+    expect(stripHtmlTags("&#X41;&#X42;&#X43;")).toBe("ABC"); // case-insensitive
+  });
+
+  it("handles mixed content", () => {
+    const html = "<p>Hello &amp; <strong>World</strong>!</p>";
+    expect(stripHtmlTags(html)).toBe("Hello & World!");
+  });
+
+  it("preserves plain text", () => {
+    expect(stripHtmlTags("plain text")).toBe("plain text");
+  });
+});
+
+describe("extractContext", () => {
+  it("extracts single-line selection with markers", () => {
+    const content = "line1\nline2\nline3\nline4\nline5";
+    // "line2" starts at offset 6, ends at 11
+    const result = extractContext({ content, startOffset: 6, endOffset: 11 });
+
+    expect(result.startLine).toBe(2);
+    expect(result.endLine).toBe(2);
+    // Should have >>> and <<< markers around "line2"
+    expect(result.lines.some((l) => l.includes(">>> line2 <<<"))).toBe(true);
+  });
+
+  it("includes context lines before and after", () => {
+    const content = "line1\nline2\nline3\nline4\nline5";
+    // Select "line3" at offset 12
+    const result = extractContext({
+      content,
+      startOffset: 12,
+      endOffset: 17,
+      contextLines: 2,
+    });
+
+    expect(result.startLine).toBe(3);
+    expect(result.endLine).toBe(3);
+    // Should include 2 lines before (line1, line2) and 2 after (line4, line5)
+    expect(result.lines.length).toBe(5);
+  });
+
+  it("handles multi-line selection", () => {
+    const content = "line1\nline2\nline3\nline4\nline5";
+    // Select from "line2" to "line3" (offset 6 to 17)
+    const result = extractContext({ content, startOffset: 6, endOffset: 17 });
+
+    expect(result.startLine).toBe(2);
+    expect(result.endLine).toBe(3);
+    // Start line should have >>> marker
+    expect(result.lines.some((l) => l.includes(">>>"))).toBe(true);
+    // End line should have <<< marker
+    expect(result.lines.some((l) => l.includes("<<<"))).toBe(true);
+  });
+
+  it("handles selection at start of document", () => {
+    const content = "line1\nline2\nline3";
+    // Select "line1" at start
+    const result = extractContext({ content, startOffset: 0, endOffset: 5 });
+
+    expect(result.startLine).toBe(1);
+    expect(result.endLine).toBe(1);
+    expect(result.lines[0]).toContain(">>> line1 <<<");
+  });
+
+  it("handles selection at end of document", () => {
+    const content = "line1\nline2\nline3";
+    // Select "line3" (offset 12 to 17)
+    const result = extractContext({ content, startOffset: 12, endOffset: 17 });
+
+    expect(result.startLine).toBe(3);
+    expect(result.endLine).toBe(3);
+    expect(result.lines.some((l) => l.includes(">>> line3 <<<"))).toBe(true);
+  });
+
+  it("truncates very long lines", () => {
+    const longLine = "a".repeat(250);
+    const content = `short\n${longLine}\nshort`;
+    // Select part of the long line
+    const result = extractContext({ content, startOffset: 6, endOffset: 256 });
+
+    // Long line should be truncated with ...
+    const longLineOutput = result.lines.find((l) => l.length > 100);
+    expect(longLineOutput?.endsWith("...")).toBe(true);
+  });
+
+  it("handles HTML content by stripping tags", () => {
+    const html = "<p>paragraph</p>\n<div>div content</div>";
+    // After stripping: "paragraph\ndiv content"
+    // Select "paragraph" at offset 0-9
+    const result = extractContext({
+      content: html,
+      startOffset: 0,
+      endOffset: 9,
+    });
+
+    expect(result.lines.some((l) => l.includes(">>> paragraph <<<"))).toBe(
+      true,
+    );
+  });
+
+  it("normalizes CRLF to LF", () => {
+    const content = "line1\r\nline2\r\nline3";
+    // After normalization: "line1\nline2\nline3"
+    // Select "line2" at offset 6
+    const result = extractContext({ content, startOffset: 6, endOffset: 11 });
+
+    expect(result.startLine).toBe(2);
+    expect(result.lines.some((l) => l.includes(">>> line2 <<<"))).toBe(true);
+  });
+
+  it("limits context lines to document bounds", () => {
+    const content = "only\ntwo\nlines";
+    // Select middle line with 5 context lines requested
+    const result = extractContext({
+      content,
+      startOffset: 5,
+      endOffset: 8,
+      contextLines: 5,
+    });
+
+    // Should not go beyond document bounds
+    expect(result.lines.length).toBeLessThanOrEqual(3);
+  });
+
+  it("truncates very long selections with ellipsis", () => {
+    // Create content with more than MAX_SELECTION_LINES (10) lines
+    const lines = Array.from({ length: 15 }, (_, i) => `line${i + 1}`);
+    const content = lines.join("\n");
+    // Select all content
+    const result = extractContext({
+      content,
+      startOffset: 0,
+      endOffset: content.length,
+      contextLines: 0,
+    });
+
+    // Should include ... for truncated middle
+    expect(result.lines.some((l) => l === "...")).toBe(true);
+  });
+});
+
+describe("formatForLLM", () => {
+  it("formats context with header and line range", () => {
+    const context = {
+      lines: ["before", ">>> selected <<<", "after"],
+      startLine: 5,
+      endLine: 5,
+    };
+
+    const result = formatForLLM({ context, fileName: "test.md" });
+
+    expect(result).toContain("# From: test.md");
+    expect(result).toContain("Lines 5-5:");
+    expect(result).toContain("---");
+    expect(result).toContain(">>> selected <<<");
+  });
+
+  it("includes optional comment", () => {
+    const context = {
+      lines: ["text"],
+      startLine: 1,
+      endLine: 1,
+    };
+
+    const result = formatForLLM({
+      context,
+      fileName: "test.md",
+      comment: "This needs review",
+    });
+
+    expect(result).toContain("Comment: This needs review");
+  });
+
+  it("omits comment section when not provided", () => {
+    const context = {
+      lines: ["text"],
+      startLine: 1,
+      endLine: 1,
+    };
+
+    const result = formatForLLM({ context, fileName: "test.md" });
+
+    expect(result).not.toContain("Comment:");
+  });
+
+  it("formats multi-line range correctly", () => {
+    const context = {
+      lines: [">>> start", "middle", "end <<<"],
+      startLine: 10,
+      endLine: 12,
+    };
+
+    const result = formatForLLM({ context, fileName: "doc.html" });
+
+    expect(result).toContain("Lines 10-12:");
+  });
+});