seendiff 0.0.2

package/README.md

@@ -0,0 +1,124 @@
+# seendiff (Node.js port)
+
+A Node.js/Fastify port of [seendiff](https://github.com/acme-dot-bot/seendiff) —
+a local, point-in-time diff tool with persistent review state. Faithful 1:1
+port of the original Python/FastAPI tool, including block/section splitting,
+walkthrough mode, syntax highlighting, and search.
+
+## Install & run
+
+No install needed — run directly with npx from inside any git repo:
+
+```bash
+npx seendiff
+```
+
+Or install globally:
+
+```bash
+npm install -g seendiff
+seendiff
+```
+
+Or from this source tree:
+
+```bash
+npm install
+npm link
+seendiff
+```
+
+## Usage
+
+```
+usage: seendiff [-h] [--fetch] [--clear] [--no-auto-seen] [--no-highlight]
+                [--section-min N] [--section-max N] [--port PORT]
+                [--no-browser] [--walkthrough PATH]
+                [--check-walkthrough PATH]
+                [base]
+
+positional arguments:
+  base                  base ref (default: origin/master, with fallbacks)
+
+options:
+  -h, --help            show this help message and exit
+  --fetch               run git fetch before diffing (never implicit)
+  --clear               clear review state for this scope, then continue
+  --no-auto-seen
+  --no-highlight
+  --section-min N       smallest review section, in changed lines (default 12)
+  --section-max N       largest review section, in changed lines (default 48)
+  --port PORT
+  --no-browser
+  --walkthrough PATH    open a walkthrough JSON in walkthrough mode
+  --check-walkthrough PATH
+                        validate a walkthrough JSON, print diagnostics, exit 0/1
+```
+
+Run `seendiff` from inside a git repo with local commits ahead of
+`origin/master`/`origin/main`. It opens a browser tab with a diff viewer
+that groups changes into reviewable blocks, tracks seen/reviewed state
+per-block in a local SQLite database (survives rebases via content hashing),
+and supports syntax-highlighted search across the whole change.
+
+## Architecture
+
+| Module               | Purpose                                                                                                |
+| -------------------- | ------------------------------------------------------------------------------------------------------ |
+| `src/git.js`         | Ref resolution, diff invocation, unified-diff parsing, block grouping/splitting (the core algorithm)   |
+| `src/store.js`       | SQLite review-state persistence via `node:sqlite`                                                      |
+| `src/highlight.js`   | Syntax highlighting via `highlight.js`, mapped to Pygments-compatible CSS classes                      |
+| `src/theme.js`       | Serves pre-generated theme CSS (`src/theme-base.css`), built once from real Pygments for visual parity |
+| `src/walkthrough.js` | JSON walkthrough-script loading, validation, ref resolution                                            |
+| `src/server.js`      | Fastify app — all API routes, caching, host-allowlist guard                                            |
+| `src/cli.js`         | Argument parsing, free-port selection, browser launch                                                  |
+| `bin/seendiff.js`    | npx/global-install entry point                                                                         |
+| `static/index.html`  | Frontend — copied unmodified from upstream (backend-agnostic, talks only via `fetch`)                  |
+
+### Notable porting decisions
+
+- **`node:sqlite`** instead of a third-party driver — zero extra native
+  dependencies, matches the "local, no server infra" spirit of the original.
+- **`highlight.js`** instead of Pygments (Python-only) for tokenization, with
+  a class-mapping layer so the frontend's existing Pygments-derived CSS
+  selectors (`.hl .k`, `.hl .nf`, `.hl .c1`, etc.) work unchanged.
+- **Theme CSS is not hand-approximated** — `src/theme-base.css` was generated
+  by actually running Pygments' `HtmlFormatter` against the same six styles
+  the original uses (`default`, `github-dark`, `solarized-dark`,
+  `solarized-light`, `nord`, `coffee`), so highlighting is visually identical
+  to the Python tool, not a lookalike.
+- **Custom unified-diff parser** — rather than pull in a generic npm unidiff
+  library, `src/git.js` parses exactly the `git diff -U0 --find-renames`
+  subset seendiff needs (headers, renames, binary markers, hunks), which is
+  easier to verify against the original's behavior line-for-line.
+- **Fastify's `listen()` doesn't block** like uvicorn's `run()` does — the
+  CLI intentionally never resolves after a successful listen, so the process
+  stays alive for the life of the server.
+
+## Testing
+
+```bash
+npm install
+node --test test/
+```
+
+Port-fidelity was verified by:
+- Translating the original's `test_sections.py` into `test/sections.test.js`
+  (all 7 cases pass) — validates the block/section-splitting algorithm,
+  the trickiest part of the port.
+- **A/B differential testing**: running the real Python server and this
+  Node port side-by-side against identical repos/diffs and byte-comparing
+  every API response. Covered a 33-file/4,093-line synthetic stress diff
+  (25/25 checks passed: file listing, per-file status, full row-by-row
+  content, search, seen/reviewed mutation, host guard, prefs) and a
+  targeted edge-case repo covering renames-with-edits, binary files, CRLF
+  line endings, no-trailing-newline files, and Unicode filenames (34/34
+  checks passed after two real bugs were found and fixed — see below).
+- Walkthrough parity: `--check-walkthrough` diagnostics, live `/api/walkthrough`
+  payload (including content digest), and a subtle ordering-dependent
+  validation quirk in the original (a step following one with an invalid
+  ref skips duplicate-id detection) were confirmed to match exactly.
+
+## License
+
+MIT

package/bin/seendiff.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+main()
+  .then((code) => process.exit(code ?? 0))
+  .catch((err) => {
+    process.stderr.write(`seendiff: unexpected error: ${err.stack || err.message}\n`);
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,38 @@
+{
+    "name": "seendiff",
+    "version": "0.0.2",
+    "description": "Local, point-in-time diff tool with persistent review state (Node.js port)",
+    "type": "module",
+    "license": "MIT",
+    "author": {
+        "name": "Anand Pilania",
+        "email": "pilaniaanand@gmail.com",
+        "url": "https://github.com/AnandPilania"
+    },
+    "engines": {
+        "node": ">=22.5.0"
+    },
+    "bin": {
+        "seendiff": "./bin/seendiff.js"
+    },
+    "files": [
+        "bin",
+        "src",
+        "static",
+        "README.md",
+        "LICENSE"
+    ],
+    "keywords": [
+        "diff",
+        "code-review",
+        "git",
+        "cli",
+        "coding-agent"
+    ],
+    "dependencies": {
+        "@fastify/compress": "^9.2.0",
+        "fastify": "^5.12.1",
+        "highlight.js": "^11.12.0",
+        "open": "^10.2.0"
+    }
+}

package/src/cli.js

@@ -0,0 +1,216 @@
+import { createServer } from "node:net";
+import open from "open";
+
+import * as G from "./git.js";
+import * as store from "./store.js";
+import * as W from "./walkthrough.js";
+import { AppState, createApp } from "./server.js";
+
+export function freePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.listen(0, "127.0.0.1", () => {
+            const { port } = srv.address();
+            srv.close(() => resolve(port));
+        });
+        srv.on("error", reject);
+    });
+}
+
+function parseArgs(argv) {
+    const args = {
+        base: null,
+        fetch: false,
+        clear: false,
+        noAutoSeen: false,
+        noHighlight: false,
+        sectionMin: G.SECTION_MIN,
+        sectionMax: G.SECTION_MAX,
+        port: null,
+        noBrowser: false,
+        walkthrough: null,
+        checkWalkthrough: null,
+        help: false,
+    };
+    const rest = [...argv];
+    while (rest.length) {
+        const a = rest.shift();
+        switch (a) {
+            case "--fetch":
+                args.fetch = true;
+                break;
+            case "--clear":
+                args.clear = true;
+                break;
+            case "--no-auto-seen":
+                args.noAutoSeen = true;
+                break;
+            case "--no-highlight":
+                args.noHighlight = true;
+                break;
+            case "--section-min":
+                args.sectionMin = parseInt(rest.shift(), 10);
+                break;
+            case "--section-max":
+                args.sectionMax = parseInt(rest.shift(), 10);
+                break;
+            case "--port":
+                args.port = parseInt(rest.shift(), 10);
+                break;
+            case "--no-browser":
+                args.noBrowser = true;
+                break;
+            case "--walkthrough":
+                args.walkthrough = rest.shift();
+                break;
+            case "--check-walkthrough":
+                args.checkWalkthrough = rest.shift();
+                break;
+            case "-h":
+            case "--help":
+                args.help = true;
+                break;
+            default:
+                if (a.startsWith("--section-min=")) args.sectionMin = parseInt(a.split("=")[1], 10);
+                else if (a.startsWith("--section-max=")) args.sectionMax = parseInt(a.split("=")[1], 10);
+                else if (a.startsWith("--port=")) args.port = parseInt(a.split("=")[1], 10);
+                else if (a.startsWith("--walkthrough=")) args.walkthrough = a.split("=").slice(1).join("=");
+                else if (a.startsWith("--check-walkthrough=")) args.checkWalkthrough = a.split("=").slice(1).join("=");
+                else if (!a.startsWith("-") && args.base === null) args.base = a;
+                break;
+        }
+    }
+    return args;
+}
+
+const HELP_TEXT = `usage: seendiff [-h] [--fetch] [--clear] [--no-auto-seen] [--no-highlight]
+                [--section-min N] [--section-max N] [--port PORT]
+                [--no-browser] [--walkthrough PATH]
+                [--check-walkthrough PATH]
+                [base]
+
+Point-in-time diff tool with persistent review state.
+
+positional arguments:
+  base                  base ref (default: origin/master, with fallbacks)
+
+options:
+  -h, --help            show this help message and exit
+  --fetch               run git fetch before diffing (never implicit)
+  --clear               clear review state for this scope, then continue
+  --no-auto-seen
+  --no-highlight
+  --section-min N       smallest review section, in changed lines (default ${G.SECTION_MIN})
+  --section-max N       largest review section, in changed lines (default ${G.SECTION_MAX});
+                        a bigger block is cut at the nearest seam in the code
+  --port PORT
+  --no-browser
+  --walkthrough PATH    open a walkthrough JSON in walkthrough mode
+  --check-walkthrough PATH
+                        validate a walkthrough JSON, print diagnostics, exit 0/1
+`;
+
+export async function main(argv = process.argv.slice(2)) {
+    const args = parseArgs(argv);
+
+    if (args.help) {
+        process.stdout.write(HELP_TEXT);
+        return 0;
+    }
+
+    if (args.sectionMin < 1 || args.sectionMax < 2 * args.sectionMin) {
+        process.stderr.write("seendiff: --section-max must be at least twice --section-min\n");
+        return 1;
+    }
+
+    let repo;
+    try {
+        repo = G.repoRoot(".");
+        if (args.fetch) G.fetch(repo);
+    } catch (e) {
+        if (e instanceof G.GitError) {
+            process.stderr.write(`seendiff: ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+
+    let baseRef;
+    try {
+        baseRef = G.resolveBase(repo, args.base);
+    } catch (e) {
+        if (!(e instanceof G.GitError)) throw e;
+        if (!(args.walkthrough || args.checkWalkthrough)) {
+            process.stderr.write(`seendiff: ${e.message}\n`);
+            return 1;
+        }
+        process.stderr.write(`seendiff: ${e.message} — walkthrough mode, using an empty diff\n`);
+        baseRef = "HEAD";
+    }
+
+    if (args.checkWalkthrough) {
+        const files = G.expandSubmodules(
+            repo,
+            G.identityDiff(repo, G.mergeBase(repo, baseRef), "HEAD", args.sectionMin, args.sectionMax),
+            args.sectionMin,
+            args.sectionMax
+        );
+        const hunkIds = {};
+        for (const fd of files) hunkIds[fd.path] = new Set(fd.blocks.map((b) => b.hunkId));
+        const problems = W.check(args.checkWalkthrough, repo, hunkIds);
+        for (const p of problems) process.stderr.write(p + "\n");
+        if (problems.length) return 1;
+        const wt = W.load(args.checkWalkthrough, repo, hunkIds);
+        if (wt === null) {
+            process.stdout.write("ok: empty walkthrough (plain diff until it's written)\n");
+        } else {
+            process.stdout.write(`ok: ${JSON.stringify(wt.title)} — ${wt.acts.length} acts, ${wt.steps.length} steps\n`);
+        }
+        return 0;
+    }
+
+    const st = new AppState({
+        repo,
+        baseRef,
+        sectionMin: args.sectionMin,
+        sectionMax: args.sectionMax,
+        noHighlight: args.noHighlight,
+        autoSeen: !args.noAutoSeen,
+        wtFile: args.walkthrough,
+    });
+
+    if (args.clear) {
+        const db = store.openDb();
+        const mb = G.mergeBase(repo, baseRef);
+        const scope = store.scopeKey(repo, baseRef, G.branchName(repo), mb);
+        store.clearScope(db, scope);
+        db.close();
+        process.stdout.write(`cleared review state for ${scope}\n`);
+    }
+
+    const app = await createApp(st);
+    if (args.walkthrough) {
+        st.loadWalkthrough();
+        if (st.wt === null && !st.wtEmpty) {
+            process.stderr.write("seendiff: walkthrough failed to load:\n");
+            for (const p of (st.wtError || "?").split("\n")) process.stderr.write(`  ${p}\n`);
+            return 1;
+        }
+        if (st.wt === null) {
+            process.stderr.write(`seendiff: empty walkthrough — plain diff, watching ${args.walkthrough}\n`);
+        }
+    }
+
+    const port = args.port || (await freePort());
+    const url = `http://127.0.0.1:${port}/`;
+    process.stdout.write(
+        `seendiff: ${st.branch || "detached"} vs ${baseRef} (merge base ${st.mbSha.slice(0, 12)}) — ${url}\n`
+    );
+    if (!args.noBrowser) {
+        setTimeout(() => {
+            open(url).catch(() => { });
+        }, 600);
+    }
+    await app.listen({ port, host: "127.0.0.1" });
+    return new Promise(() => { });
+}