folderview 0.0.0-stage → 0.2.1

package/dist/review.js

@@ -0,0 +1,290 @@
+// Review comments: on a file or on lines of it, kept in <review dir>/comments.json, with REVIEW.md beside it written
+// for an LLM (or a person) to work through. Edits made to comments.json by hand or by an agent are picked up live.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+const QUOTE_LINES = 12;
+export class Review {
+    dir;
+    root;
+    jsonPath;
+    mdPath;
+    comments = [];
+    lastWritten = '';
+    listeners = new Set();
+    watcher;
+    constructor(dir, root) {
+        this.dir = dir;
+        this.root = root;
+        this.jsonPath = path.join(dir, 'comments.json');
+        this.mdPath = path.join(dir, 'REVIEW.md');
+        this.load();
+    }
+    onChange(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    /** watch comments.json for edits from outside (an agent resolving a comment) */
+    watch() {
+        if (this.watcher)
+            return;
+        const start = () => {
+            try {
+                this.watcher = fs.watch(this.dir, (_e, name) => {
+                    if (name && String(name) !== 'comments.json')
+                        return;
+                    setTimeout(() => this.reloadIfChanged(), 60);
+                });
+            }
+            catch {
+                this.watcher = undefined;
+            }
+        };
+        if (fs.existsSync(this.dir))
+            start();
+        else {
+            // the folder appears with the first comment; poll until then
+            const t = setInterval(() => {
+                if (fs.existsSync(this.dir)) {
+                    clearInterval(t);
+                    start();
+                    this.reloadIfChanged();
+                }
+            }, 2000);
+            t.unref();
+        }
+    }
+    close() {
+        this.watcher?.close();
+    }
+    reloadIfChanged() {
+        let text;
+        try {
+            text = fs.readFileSync(this.jsonPath, 'utf8');
+        }
+        catch {
+            text = '';
+        }
+        if (text === this.lastWritten)
+            return;
+        this.load();
+        this.writeMarkdown(); // keep REVIEW.md in step with the hand edit
+        this.emit();
+    }
+    emit() {
+        for (const fn of this.listeners)
+            fn();
+    }
+    load() {
+        try {
+            const text = fs.readFileSync(this.jsonPath, 'utf8');
+            this.lastWritten = text;
+            const data = JSON.parse(text);
+            const list = data && typeof data === 'object' && 'comments' in data && Array.isArray(data.comments) ? data.comments : [];
+            this.comments = list.filter(isComment);
+        }
+        catch {
+            // no file yet, or a half-written hand edit: keep what we had
+        }
+    }
+    all() {
+        return this.comments;
+    }
+    add(input) {
+        const c = {
+            id: crypto.randomBytes(4).toString('hex'),
+            path: input.path,
+            body: input.body.trim(),
+            author: input.author || 'reviewer',
+            status: 'open',
+            createdAt: new Date().toISOString(),
+        };
+        if (input.line) {
+            c.line = input.line;
+            if (input.endLine && input.endLine > input.line)
+                c.endLine = input.endLine;
+            const quote = this.quote(input.path, input.line, c.endLine ?? input.line);
+            if (quote !== undefined)
+                c.quote = quote;
+        }
+        if (input.area)
+            c.area = input.area;
+        if (input.strokes?.length)
+            c.strokes = input.strokes;
+        if (input.snapshot) {
+            fs.mkdirSync(path.join(this.dir, 'images'), { recursive: true });
+            c.image = `images/${c.id}.png`;
+            fs.writeFileSync(path.join(this.dir, c.image), input.snapshot);
+        }
+        if (input.commit)
+            c.commit = input.commit;
+        this.comments.push(c);
+        this.save();
+        return c;
+    }
+    update(id, patch) {
+        const c = this.comments.find((x) => x.id === id);
+        if (!c)
+            return undefined;
+        if (typeof patch.body === 'string' && patch.body.trim())
+            c.body = patch.body.trim();
+        if (patch.status === 'open' || patch.status === 'resolved')
+            c.status = patch.status;
+        c.updatedAt = new Date().toISOString();
+        this.save();
+        return c;
+    }
+    reply(id, author, body) {
+        const c = this.comments.find((x) => x.id === id);
+        if (!c || !body.trim())
+            return undefined;
+        (c.replies ??= []).push({ id: crypto.randomBytes(3).toString('hex'), author: author || 'reviewer', body: body.trim(), at: new Date().toISOString() });
+        c.updatedAt = new Date().toISOString();
+        this.save();
+        return c;
+    }
+    remove(id) {
+        const gone = this.comments.find((c) => c.id === id);
+        if (!gone)
+            return false;
+        this.comments = this.comments.filter((c) => c.id !== id);
+        this.dropImage(gone);
+        this.save();
+        return true;
+    }
+    clearResolved() {
+        const n = this.comments.length;
+        for (const c of this.comments)
+            if (c.status === 'resolved')
+                this.dropImage(c);
+        this.comments = this.comments.filter((c) => c.status !== 'resolved');
+        this.save();
+        return n - this.comments.length;
+    }
+    /** the marked-up picture of an image comment, as a path inside the review folder (or undefined) */
+    imagePath(id) {
+        const c = this.comments.find((x) => x.id === id);
+        if (!c?.image || !/^images\/[0-9a-f]+\.png$/.test(c.image))
+            return undefined;
+        const abs = path.join(this.dir, c.image);
+        return fs.existsSync(abs) ? abs : undefined;
+    }
+    dropImage(c) {
+        if (c.image && /^images\/[0-9a-f]+\.png$/.test(c.image))
+            fs.rmSync(path.join(this.dir, c.image), { force: true });
+    }
+    quote(rel, from, to) {
+        try {
+            const abs = path.join(this.root, rel);
+            if (fs.statSync(abs).size > 5_000_000)
+                return undefined;
+            const lines = fs.readFileSync(abs, 'utf8').split('\n');
+            const end = Math.min(to, from + QUOTE_LINES - 1);
+            const got = lines.slice(from - 1, end).map((l) => l.replace(/\r$/, ''));
+            if (!got.length)
+                return undefined;
+            return got.join('\n') + (to > end ? '\n…' : '');
+        }
+        catch {
+            return undefined;
+        }
+    }
+    save() {
+        fs.mkdirSync(this.dir, { recursive: true });
+        const sorted = [...this.comments].sort((a, b) => a.path.localeCompare(b.path) || (a.line ?? 0) - (b.line ?? 0) || a.createdAt.localeCompare(b.createdAt));
+        const text = JSON.stringify({ version: 1, comments: sorted }, null, 2) + '\n';
+        writeAtomic(this.jsonPath, text);
+        this.lastWritten = text;
+        this.writeMarkdown();
+        this.emit();
+    }
+    writeMarkdown() {
+        try {
+            fs.mkdirSync(this.dir, { recursive: true });
+            writeAtomic(this.mdPath, toMarkdown(this.comments, path.relative(this.root, this.jsonPath).split(path.sep).join('/')));
+        }
+        catch {
+            // the folder went away; the next save makes it again
+        }
+    }
+}
+/** What to tell an agent: where the feedback is, and how to answer it. */
+export function agentPrompt(mdRel, jsonRel) {
+    return (`Read ${mdRel}. It lists review comments on files in this folder (path:line, the quoted code, and the comment). ` +
+        `Work through each open comment: make the change it asks for, then set that comment's "status" to "resolved" in ${jsonRel} ` +
+        `and add a reply saying what you did. If you can't or shouldn't act on one, leave it open and reply with why. ` +
+        `(\`npx folderview review\` prints the open comments too.)`);
+}
+export function toMarkdown(comments, jsonRel, { openOnly = false } = {}) {
+    const open = comments.filter((c) => c.status === 'open');
+    const done = openOnly ? [] : comments.filter((c) => c.status === 'resolved');
+    const out = [
+        '# Review comments',
+        '',
+        openOnly ? `${open.length} open` : `${open.length} open · ${done.length} resolved · updated ${new Date().toISOString()}`,
+        '',
+        '<!-- Written by folderview. Do not edit this file: it is regenerated from ' + jsonRel + '. -->',
+        '',
+        '## How to work through this (for an agent)',
+        '',
+        '- Each comment is on a file, on lines of it (`path:line`), or on an area of an image (marked by hand; `images/<id>.png` beside this file shows the marks). Paths are relative to the folder folderview serves.',
+        '- The quoted code is what the lines said when the comment was left; the file may have moved on since, so find the code, not just the line number.',
+        `- When a comment is dealt with, set its \`"status"\` to \`"resolved"\` in \`${jsonRel}\` and, if there is something to say, add a reply:`,
+        '  `"replies": [{ "id": "a1", "author": "agent", "body": "Done: …", "at": "<ISO time>" }]`. The reviewer sees it live.',
+        '- Leave comments you could not act on open, with a reply that says why.',
+        '',
+    ];
+    const section = (title, list) => {
+        if (!list.length)
+            return;
+        out.push(`## ${title}`, '');
+        let file = '';
+        for (const c of list) {
+            if (c.path !== file) {
+                file = c.path;
+                out.push(`### ${file || '(the whole folder)'}`, '');
+            }
+            const where = c.line ? `${c.path}:${c.line}${c.endLine ? '-' + c.endLine : ''}` : c.area ? `${c.path} (marked area)` : `${c.path || '.'} (whole file)`;
+            out.push(`#### \`${where}\` — ${c.author}${c.commit ? ` @ ${c.commit}` : ''} · id \`${c.id}\``, '');
+            if (c.quote)
+                out.push('```' + langOf(c.path), c.quote, '```', '');
+            if (c.area)
+                out.push(`Marked area: x ${c.area.x}, y ${c.area.y}, ${c.area.w} × ${c.area.h} px of the image.` + (c.image ? ` The marks are drawn on a copy: ${c.image} (beside this file).` : ''), '');
+            if (c.image)
+                out.push(`![The marked area](${c.image})`, '');
+            out.push(c.body, '');
+            for (const r of c.replies ?? [])
+                out.push(`> **${r.author}**: ${r.body.replace(/\n/g, '\n> ')}`, '');
+        }
+    };
+    const order = (a, b) => a.path.localeCompare(b.path) || (a.line ?? 0) - (b.line ?? 0);
+    section('Open', [...open].sort(order));
+    section('Resolved', [...done].sort(order));
+    if (!comments.length)
+        out.push('No comments yet.', '');
+    else if (openOnly && !open.length)
+        out.push('No open comments.', '');
+    return out.join('\n');
+}
+function langOf(p) {
+    const ext = p.slice(p.lastIndexOf('.') + 1).toLowerCase();
+    return /^[a-z0-9]{1,8}$/.test(ext) && p.includes('.') ? ext : '';
+}
+function writeAtomic(file, text) {
+    const tmp = file + '.' + process.pid + '.tmp';
+    fs.writeFileSync(tmp, text);
+    try {
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        // Windows can refuse a rename over a file another process holds open; write in place instead
+        fs.writeFileSync(file, text);
+        fs.rmSync(tmp, { force: true });
+    }
+}
+function isComment(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const c = x;
+    return typeof c.id === 'string' && typeof c.path === 'string' && typeof c.body === 'string' && (c.status === 'open' || c.status === 'resolved');
+}

package/dist/search.js

@@ -0,0 +1,136 @@
+// The file list (for quick open and name search) and full-text search across it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { isHidden, walk } from './files.js';
+import { pathFilter } from './glob.js';
+const MAX_FILE = 2 * 1024 * 1024;
+const MAX_MATCHES = 3000;
+const MAX_PER_FILE = 200;
+const LINE_CAP = 400;
+export class FileIndex {
+    scope;
+    git;
+    maxFile;
+    cached;
+    constructor(scope, git, maxFile = MAX_FILE) {
+        this.scope = scope;
+        this.git = git;
+        this.maxFile = maxFile;
+    }
+    invalidate() {
+        this.cached = undefined;
+    }
+    async files() {
+        if (this.cached && Date.now() - this.cached.at < 30_000)
+            return this.cached.files;
+        let files;
+        if (this.git)
+            files = await this.git.files().catch(() => undefined);
+        files ??= walk(this.scope);
+        files = files.filter((f) => !f.split('/').some((p) => isHidden(this.scope, p)) && !this.scope.excluded(f) && fs.existsSync(path.join(this.scope.root, f)));
+        this.cached = { at: Date.now(), files };
+        return files;
+    }
+    async search(query) {
+        const t0 = Date.now();
+        const result = { files: [], total: 0, truncated: false, searched: 0, ms: 0 };
+        let re;
+        try {
+            re = makeRegex(query);
+        }
+        catch (e) {
+            return { ...result, error: e instanceof Error ? e.message : String(e) };
+        }
+        const prefix = query.scope.replace(/^\/+|\/+$/g, '');
+        const filter = pathFilter(query.include);
+        const all = (await this.files()).filter((f) => (!prefix || f.startsWith(prefix + '/')) && filter(f));
+        // in git, git grep says which files can match; only those are read (names are still checked on every file)
+        const maybe = this.git ? await this.git.grepFiles(query.q, { regex: query.regex, caseSensitive: query.caseSensitive, word: query.word }) : undefined;
+        // read many files at once (each read is mostly waiting on the disk), keep the results in path order
+        const found = new Array(all.length);
+        let next = 0;
+        const worker = async () => {
+            while (next < all.length && result.total < MAX_MATCHES) {
+                const idx = next++;
+                const file = all[idx] ?? '';
+                const hits = { path: file, matches: [] };
+                re.lastIndex = 0;
+                if (re.test(file.slice(file.lastIndexOf('/') + 1)))
+                    hits.name = true;
+                const text = maybe && !maybe.has(file) ? undefined : await readText(path.join(this.scope.root, file), this.maxFile);
+                if (maybe && !maybe.has(file))
+                    result.searched++;
+                if (text !== undefined) {
+                    result.searched++;
+                    const lines = text.split('\n');
+                    for (let i = 0; i < lines.length && hits.matches.length < MAX_PER_FILE; i++) {
+                        const line = (lines[i] ?? '').replace(/\r$/, '');
+                        const ranges = hitsIn(re, line);
+                        if (ranges.length)
+                            hits.matches.push(clip(i + 1, line, ranges));
+                    }
+                }
+                if (hits.matches.length || hits.name) {
+                    found[idx] = hits;
+                    result.total += hits.matches.length || 1;
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: 48 }, worker));
+        result.truncated = next < all.length;
+        result.files = found.filter((f) => f !== undefined);
+        result.ms = Date.now() - t0;
+        return result;
+    }
+}
+function makeRegex(q) {
+    let src = q.regex ? q.q : q.q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (q.word)
+        src = `\\b(?:${src})\\b`;
+    const re = new RegExp(src, q.caseSensitive ? 'g' : 'gi');
+    if (re.test(''))
+        throw new Error('That pattern matches nothing at all (an empty match).');
+    return re;
+}
+function hitsIn(re, line) {
+    const out = [];
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(line)) && out.length < 50) {
+        if (m[0] === '') {
+            re.lastIndex++;
+            continue;
+        }
+        out.push([m.index, m.index + m[0].length]);
+    }
+    return out;
+}
+/** long lines are cut around the first hit so the result stays readable */
+function clip(line, text, hits) {
+    if (text.length <= LINE_CAP)
+        return { line, text, hits };
+    const first = hits[0]?.[0] ?? 0;
+    const start = Math.max(0, first - 80);
+    const end = Math.min(text.length, start + LINE_CAP);
+    const lead = start > 0 ? '…' : '';
+    const shift = start - lead.length;
+    return {
+        line,
+        text: lead + text.slice(start, end) + (end < text.length ? '…' : ''),
+        hits: hits.filter(([a, b]) => a >= start && b <= end).map(([a, b]) => [a - shift, b - shift]),
+    };
+}
+async function readText(abs, max) {
+    try {
+        const st = await fs.promises.stat(abs);
+        if (!st.isFile() || st.size > max)
+            return undefined;
+        const buf = await fs.promises.readFile(abs);
+        if (buf.subarray(0, 8192).includes(0))
+            return undefined; // binary
+        return buf.toString('utf8');
+    }
+    catch {
+        return undefined;
+    }
+}