@0xcraft/powershot 1.0.0

package/dist/bench.js

@@ -0,0 +1,179 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadConfig } from './config.js';
+import { review } from './review.js';
+import { openTargetTree, withTargetTree } from './snapshot.js';
+import { decode } from './text.js';
+import { completionOf } from './manifest.js';
+export function key(f) {
+    return f.check + '@' + f.file + ':' + f.line;
+}
+export function score(found, expected) {
+    const got = new Set(found.map(key));
+    const want = new Set(expected);
+    let tp = 0;
+    for (const k of got)
+        if (want.has(k))
+            tp++;
+    return { tp, fp: got.size - tp, fn: want.size - tp };
+}
+export function precision(s) {
+    return s.tp + s.fp === 0 ? 1 : s.tp / (s.tp + s.fp);
+}
+export function recall(s) {
+    return s.tp + s.fn === 0 ? 1 : s.tp / (s.tp + s.fn);
+}
+export function f1(s) {
+    const p = precision(s);
+    const r = recall(s);
+    return p + r === 0 ? 0 : (2 * p * r) / (p + r);
+}
+function git(root, args) {
+    return decode(execFileSync('git', args, { cwd: root, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] }));
+}
+/** The most recent commits, newest first, excluding merges (a merge has no own diff). */
+export function recentCommits(root, count) {
+    return git(root, ['log', '--no-merges', '--format=%H', '-n', String(count)]).split('\n').filter(Boolean);
+}
+export function reviewCompletion(result) {
+    return completionOf({
+        files: result.plan?.items() ?? [],
+        units: [],
+        skippedChecks: result.skippedChecks ?? [],
+        failures: result.failures,
+        cancelled: result.cancelled,
+        budgetStop: result.budgetStop,
+    });
+}
+export function incompleteReasons(result) {
+    return reviewCompletion(result).notLookedAt;
+}
+/**
+ * Replay real history through the deterministic checks.
+ *
+ * On a codebase that was reviewed and shipped, a finding is far more likely to be a
+ * false positive than a defect nobody noticed. That makes this the cheapest honest
+ * precision signal available without labelling anything — and it is measured on real
+ * code rather than on fixtures written by the same person who wrote the checks.
+ */
+export async function replayRepo(root, count, onProgress) {
+    const commits = recentCommits(root, count);
+    const report = {
+        commits: 0, findings: 0, byCheck: new Map(), noisy: [], partial: 0, failed: 0,
+        verified: 0, judged: 0, byConfidence: new Map(),
+        coverage: { selected: 0, limited: 0, waived: 0, failed: 0 },
+        falseClean: 0, positions: { added: 0, context: 0 },
+        usage: { requests: 0, inputTokens: 0, outputTokens: 0, elapsedMs: 0 },
+    };
+    if (commits.length === 0)
+        return report;
+    // One checkout, moved from commit to commit. Each replay has to read the files as
+    // they were at that commit — measuring an old diff against today's working tree is
+    // what made the previous numbers describe a state that never existed — but paying
+    // for a fresh worktree per commit would make the benchmark unusable.
+    const tree = openTargetTree(root, commits[0]);
+    try {
+        for (const commit of commits) {
+            let result;
+            try {
+                tree.checkout(commit);
+                // the policy of the commit being replayed, not today's: scoring old history
+                // against a rule set written afterwards measures the rules, not the history
+                result = await review({
+                    root: tree.dir,
+                    stateRoot: root,
+                    range: { commit },
+                    config: loadConfig(tree.dir),
+                    verifyOnly: true,
+                });
+            }
+            catch {
+                // a commit the pipeline cannot process (submodule, binary-only, first commit)
+                report.failed++;
+                continue;
+            }
+            for (const item of result.plan?.items() ?? []) {
+                if (item.disposition === 'selected' && item.missing?.length)
+                    report.coverage.limited++;
+                else
+                    report.coverage[item.disposition] = (report.coverage[item.disposition] ?? 0) + 1;
+            }
+            if (result.usage) {
+                report.usage.requests += result.usage.requests;
+                report.usage.inputTokens += result.usage.inputTokens;
+                report.usage.outputTokens += result.usage.outputTokens;
+                report.usage.elapsedMs += result.usage.elapsedMs;
+            }
+            const completion = reviewCompletion(result);
+            if (result.findings.length === 0 && completion.state !== 'complete')
+                report.falseClean++;
+            if (result.failures.length > 0 || completion.state === 'failed') {
+                report.failed++;
+                continue;
+            }
+            if (completion.state === 'partial') {
+                report.partial++;
+                continue;
+            }
+            report.commits++;
+            if (result.findings.length === 0)
+                continue;
+            report.findings += result.findings.length;
+            for (const f of result.findings) {
+                report.byCheck.set(f.check, (report.byCheck.get(f.check) ?? 0) + 1);
+                if (f.class === 'verified')
+                    report.verified++;
+                else
+                    report.judged++;
+                report.byConfidence.set(f.confidence, (report.byConfidence.get(f.confidence) ?? 0) + 1);
+                if (f.positioning === 'added')
+                    report.positions.added++;
+                else if (f.positioning === 'context')
+                    report.positions.context++;
+            }
+            let subject = '';
+            try {
+                subject = git(root, ['log', '-1', '--format=%s', commit]).trim();
+            }
+            catch {
+                // a missing subject is cosmetic; the findings still count
+            }
+            report.noisy.push({ commit: commit.slice(0, 8), subject, findings: result.findings });
+            onProgress?.(commit.slice(0, 8) + ' ' + result.findings.length + ' finding(s) — ' + subject);
+        }
+    }
+    finally {
+        tree.close();
+    }
+    return report;
+}
+/** Labelled cases from a directory of .json files, for the repos where truth is known. */
+export function loadCases(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith('.json'))
+        .map((f) => JSON.parse(readFileSync(join(dir, f), 'utf8')));
+}
+export async function runCases(root, cases) {
+    const out = [];
+    for (const c of cases) {
+        // the same bug replayRepo had: scoring an old commit against today's tree makes
+        // every labelled expectation a claim about a state that never existed
+        try {
+            const result = await withTargetTree(root, { commit: c.commit }, (tree) => review({ root: tree, stateRoot: root, range: { commit: c.commit }, config: loadConfig(tree), verifyOnly: true }));
+            const completion = reviewCompletion(result);
+            if (completion.state !== 'complete') {
+                out.push({ name: c.name, complete: false, state: completion.state, reasons: completion.notLookedAt, found: result.findings });
+            }
+            else
+                out.push({ name: c.name, complete: true, score: score(result.findings, c.expect), found: result.findings });
+        }
+        catch (error) {
+            out.push({ name: c.name, complete: false, state: 'failed', reasons: [error.message], found: [] });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=bench.js.map

package/dist/budget.js

@@ -0,0 +1,59 @@
+/**
+ * A ceiling on what a review may spend, and a record of what it did.
+ *
+ * Exhaustion is a planned `partial` outcome with unreached units named, not an
+ * execution failure or a clean verdict.
+ */
+export class Budget {
+    limits;
+    used = { requests: 0, inputTokens: 0, outputTokens: 0, toolCalls: 0, elapsedMs: 0, units: 0 };
+    startedAt;
+    constructor(limits = {}, now = Date.now()) {
+        this.limits = limits;
+        this.startedAt = now;
+    }
+    /** What is exhausted, or undefined while there is room for one more unit. */
+    exhausted(now = Date.now()) {
+        const elapsed = now - this.startedAt;
+        const over = [
+            ['requests', this.used.requests, this.limits.requests],
+            ['inputTokens', this.used.inputTokens, this.limits.inputTokens],
+            ['outputTokens', this.used.outputTokens, this.limits.outputTokens],
+            ['toolCalls', this.used.toolCalls, this.limits.toolCalls],
+            ['elapsedMs', elapsed, this.limits.elapsedMs],
+            ['units', this.used.units, this.limits.units],
+        ];
+        for (const [name, used, limit] of over) {
+            if (limit !== undefined && used >= limit)
+                return String(name) + ' budget reached (' + used + '/' + limit + ')';
+        }
+        return undefined;
+    }
+    spend(delta) {
+        for (const [k, v] of Object.entries(delta)) {
+            if (typeof v === 'number')
+                this.used[k] += v;
+        }
+    }
+    finish(now = Date.now()) {
+        this.used.elapsedMs = now - this.startedAt;
+        return this.used;
+    }
+}
+/** `--budget requests=40,inputTokens=2000000,elapsedMs=600000` */
+export function parseLimits(spec) {
+    const limits = {};
+    const known = new Set(['requests', 'inputTokens', 'outputTokens', 'toolCalls', 'elapsedMs', 'units']);
+    for (const part of spec.split(',').map((p) => p.trim()).filter(Boolean)) {
+        const at = part.indexOf('=');
+        const name = at === -1 ? part : part.slice(0, at);
+        if (!known.has(name))
+            return 'unknown budget "' + name + '" — known: ' + [...known].join(', ');
+        const value = Number(part.slice(at + 1));
+        if (!Number.isFinite(value) || value <= 0)
+            return 'budget ' + name + ' must be a positive number';
+        limits[name] = value;
+    }
+    return limits;
+}
+//# sourceMappingURL=budget.js.map

package/dist/bundle.js

@@ -0,0 +1,173 @@
+import { relPath } from './ground.js';
+import { lines as splitLines } from './text.js';
+/** Past this a model attends to less of the file. Cut into units, never skipped. */
+const MAX_LINES_PER_UNIT = 400;
+export const CONTEXT = 3;
+export function shownLines(files) {
+    const out = new Map();
+    for (const f of files) {
+        const seen = out.get(f.path) ?? new Set();
+        for (const n of f.added)
+            for (let i = n - CONTEXT; i <= n + CONTEXT; i++)
+                if (i >= 1)
+                    seen.add(i);
+        out.set(f.path, seen);
+    }
+    return out;
+}
+export function reviewableOf(f) {
+    return { path: f.changed.path, added: f.changed.added, text: f.sf.getFullText() };
+}
+export function reviewableOfForeign(f) {
+    return { path: f.path, added: f.changed.added, text: f.tree.rootNode.text };
+}
+export function reviewables(g) {
+    return [...g.files.map(reviewableOf), ...g.foreign.map(reviewableOfForeign)];
+}
+/** Roughly what a file costs a prompt: its changed lines plus the context around them. */
+function weightOf(r) {
+    return Math.min(r.added.size * 4, 600);
+}
+function chunk(r) {
+    if (r.added.size <= MAX_LINES_PER_UNIT)
+        return [r];
+    const ordered = [...r.added].sort((a, b) => a - b);
+    const out = [];
+    for (let i = 0; i < ordered.length; i += MAX_LINES_PER_UNIT) {
+        out.push({ path: r.path, added: new Set(ordered.slice(i, i + MAX_LINES_PER_UNIT)), text: r.text });
+    }
+    return out;
+}
+/**
+ * Files that import one another. A judge reasoning about a stale read needs caller
+ * and callee at once. Only TS has a resolved import graph; foreign files pack by size.
+ */
+function components(g) {
+    const byPath = new Map();
+    for (const f of g.files)
+        byPath.set(f.sf.getFilePath(), f);
+    const parent = new Map();
+    const find = (x) => {
+        let root = x;
+        while (parent.get(root) !== root)
+            root = parent.get(root) ?? root;
+        return root;
+    };
+    const union = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb)
+            parent.set(ra, rb);
+    };
+    for (const path of byPath.keys())
+        parent.set(path, path);
+    for (const f of g.files) {
+        for (const imp of f.sf.getImportDeclarations()) {
+            const target = imp.getModuleSpecifierSourceFile();
+            if (!target)
+                continue;
+            const targetPath = target.getFilePath();
+            if (byPath.has(targetPath))
+                union(f.sf.getFilePath(), targetPath);
+        }
+    }
+    const groups = new Map();
+    for (const [path, f] of byPath) {
+        const root = find(path);
+        const list = groups.get(root) ?? [];
+        list.push(reviewableOf(f));
+        groups.set(root, list);
+    }
+    const out = [...groups.values()];
+    const byKey = new Map();
+    for (const f of g.foreign) {
+        const key = groupKey(f.path);
+        const list = byKey.get(key) ?? [];
+        list.push(reviewableOfForeign(f));
+        byKey.set(key, list);
+    }
+    out.push(...byKey.values());
+    return out;
+}
+/** Keep related files together while bin-packing to minimize model calls. */
+export function bundle(g, maxLines) {
+    const groups = components(g)
+        .map((files) => files.flatMap(chunk))
+        .map((files) => ({ files, lines: files.reduce((n, f) => n + weightOf(f), 0) }))
+        .sort((a, b) => b.lines - a.lines);
+    const bundles = [];
+    for (const group of groups) {
+        // better a split component than one prompt the model reads the beginning of
+        if (group.lines > maxLines && group.files.length > 1) {
+            let current = { files: [], lines: 0 };
+            for (const f of group.files) {
+                const w = weightOf(f);
+                if (current.lines + w > maxLines && current.files.length > 0) {
+                    bundles.push(current);
+                    current = { files: [], lines: 0 };
+                }
+                current.files.push(f);
+                current.lines += w;
+            }
+            if (current.files.length > 0)
+                bundles.push(current);
+            continue;
+        }
+        const room = bundles.find((b) => b.lines + group.lines <= maxLines);
+        if (room) {
+            room.files.push(...group.files);
+            room.lines += group.lines;
+        }
+        else {
+            bundles.push({ files: [...group.files], lines: group.lines });
+        }
+    }
+    return bundles;
+}
+/** Paths no unit carries. What this reports makes the run incomplete, not clean. */
+export function uncovered(g, units) {
+    const seen = new Set(units.flatMap((u) => u.files.map((f) => f.path)));
+    return reviewables(g)
+        .map((r) => r.path)
+        .filter((p) => !seen.has(p));
+}
+export function bundleName(b, root) {
+    const first = b.files[0];
+    if (!first)
+        return 'empty';
+    // a chunked file appears in several units; the first line tells them apart
+    const ordered = [...first.added].sort((a, b) => a - b);
+    const suffix = ordered.length > 0 && splitLines(first.text).length > ordered.length ? '@' + ordered[0] : '';
+    const name = first.path + suffix;
+    return b.files.length === 1 ? name : name + ' +' + (b.files.length - 1);
+}
+export { relPath };
+/**
+ * What binds two files of a language into one conversation.
+ *
+ * The TypeScript half has a resolved import graph; nothing else does, and packing the
+ * rest by size alone put a header in one unit and its implementation in another —
+ * exactly the pair a judge needs together to see a contract drift. These are the
+ * cheap structural relationships each language already encodes in its paths.
+ */
+export function groupKey(path) {
+    const dir = path.slice(0, path.lastIndexOf('/') + 1);
+    const name = path.slice(dir.length);
+    const dot = name.lastIndexOf('.');
+    if (dot <= 0)
+        return path;
+    const ext = name.slice(dot);
+    const stem = name.slice(0, dot);
+    // a header and its implementation are one contract written down twice
+    if (/^\.(h|hpp|hh|hxx|c|cc|cpp|cxx|m|mm)$/.test(ext))
+        return dir + stem;
+    // a package is the unit in Go, Java, Kotlin and C#
+    if (/^\.(go|java|kt|kts|cs)$/.test(ext))
+        return dir;
+    // elsewhere a module and the tests that cover it argue about the same behaviour
+    if (/^\.(py|pyi|rs|rb|php|swift)$/.test(ext)) {
+        return dir + stem.replace(/^test_/, '').replace(/_test$/, '').replace(/_spec$/, '').replace(/Test$/, '');
+    }
+    return path;
+}
+//# sourceMappingURL=bundle.js.map

package/dist/cache.js

@@ -0,0 +1,155 @@
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+const FILE = '.powershot/judge-cache.json';
+const MAX_ENTRIES = 2000;
+function readTree(file) {
+    try {
+        return existsSync(file) ? readFileSync(file, 'utf8') : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A per-repository cache the reviewed tree has no way to reach. POWERSHOT_CACHE_DIR
+ * lets CI point it at something it restores between runs.
+ */
+function outsideTree(root) {
+    const home = process.env.POWERSHOT_CACHE_DIR ??
+        process.env.XDG_CACHE_HOME ??
+        join(homedir(), process.platform === 'darwin' ? 'Library/Caches' : '.cache');
+    const id = createHash('sha256').update(repositoryIdentity(root)).digest('hex').slice(0, 32);
+    const file = join(home, 'powershot', id, 'judge-cache.json');
+    assertOutside(root, file);
+    return file;
+}
+function realOf(root) {
+    try {
+        return realpathSync(root);
+    }
+    catch {
+        return root;
+    }
+}
+function repositoryIdentity(root) {
+    const git = (args) => {
+        try {
+            return execFileSync('git', args, {
+                cwd: root,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const remote = git(['config', '--get', 'remote.origin.url']);
+    if (remote)
+        return 'remote:' + remote;
+    const roots = git(['rev-list', '--max-parents=0', '--all']);
+    if (roots)
+        return 'roots:' + roots.split('\n').sort().join(',');
+    return 'path:' + realOf(root);
+}
+/** Resolve the nearest existing ancestor, so nonexistent paths and symlink parents are safe. */
+function canonical(path) {
+    let current = resolve(path);
+    const tail = [];
+    while (!existsSync(current)) {
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        tail.unshift(basename(current));
+        current = parent;
+    }
+    return join(realOf(current), ...tail);
+}
+function assertOutside(root, file) {
+    const rel = relative(canonical(root), canonical(file));
+    const inside = rel === '' || (rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel));
+    if (inside) {
+        throw new Error('POWERSHOT_CACHE_DIR must resolve outside the reviewed repository');
+    }
+}
+/** Judge answers keyed by every input that can change the answer. */
+export class JudgeCache {
+    file;
+    entries;
+    reviewedRoot;
+    constructor(file, entries, reviewedRoot) {
+        this.file = file;
+        this.entries = entries;
+        this.reviewedRoot = reviewedRoot;
+    }
+    /** Gated runs share a per-repository cache that the reviewed tree cannot write. */
+    static open(root, gated = false) {
+        const file = gated ? outsideTree(root) : join(root, FILE);
+        const text = readTree(file);
+        if (text === undefined)
+            return new JudgeCache(file, {}, gated ? root : undefined);
+        try {
+            const parsed = JSON.parse(text);
+            const entries = parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+                ? parsed
+                : {};
+            return new JudgeCache(file, entries, gated ? root : undefined);
+        }
+        catch {
+            return new JudgeCache(file, {}, gated ? root : undefined); // a corrupt cache is not worth failing a review over
+        }
+    }
+    /** Everything an answer depends on. Leave one out and the key collides. */
+    static key(parts) {
+        return createHash('sha256')
+            .update(parts.judge)
+            .update(' ')
+            .update(parts.provider)
+            .update(' ')
+            .update(parts.model)
+            .update(' ')
+            .update(parts.prompt)
+            .update(' ')
+            .update(parts.tools ? 'tools' : 'no-tools')
+            .update(' ')
+            .update(parts.content)
+            .update(' ')
+            .update(parts.intent ?? '')
+            .digest('hex')
+            .slice(0, 32);
+    }
+    get(key) {
+        return this.entries[key]?.findings;
+    }
+    put(key, findings, now) {
+        this.entries[key] = { findings, seen: now };
+    }
+    /** Once at the end: a disk write per model call would eat what the cache saves. */
+    save() {
+        if (this.reviewedRoot)
+            assertOutside(this.reviewedRoot, this.file);
+        try {
+            const keys = Object.keys(this.entries);
+            if (keys.length > MAX_ENTRIES) {
+                // oldest first, so a long-lived repository does not grow a cache without bound
+                const ordered = keys.sort((a, b) => (this.entries[a].seen < this.entries[b].seen ? -1 : 1));
+                for (const k of ordered.slice(0, keys.length - MAX_ENTRIES))
+                    delete this.entries[k];
+            }
+            mkdirSync(dirname(this.file), { recursive: true, mode: 0o700 });
+            const temporary = this.file + '.tmp-' + process.pid;
+            writeFileSync(temporary, JSON.stringify(this.entries), { mode: 0o600 });
+            renameSync(temporary, this.file);
+        }
+        catch {
+            // failing to persist a cache must never fail the review it was speeding up
+        }
+    }
+    get size() {
+        return Object.keys(this.entries).length;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cli/agent-command.js

@@ -0,0 +1,27 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { TARGETS, findTarget } from '#app/agents.js';
+import { repoRoot } from '#app/git.js';
+import { dim, bold, steel } from '#app/report/ansi.js';
+export function runAgentCommand(name) {
+    if (!name || name === 'list') {
+        process.stdout.write('\n ' + bold('Agent targets') + '\n\n');
+        for (const target of TARGETS) {
+            process.stdout.write('  ' + steel(target.name.padEnd(8)) + dim(target.path) + '\n');
+            process.stdout.write('  ' + ' '.repeat(8) + dim(target.serves) + '\n\n');
+        }
+        process.stdout.write(dim(' psh agent agents    # the standard file, covers most tools\n\n'));
+        return 0;
+    }
+    const target = findTarget(name);
+    if (!target) {
+        process.stderr.write('Unknown agent "' + name + '". Try: psh agent list\n');
+        return 2;
+    }
+    const output = join(repoRoot(process.cwd()), target.path);
+    mkdirSync(dirname(output), { recursive: true });
+    writeFileSync(output, target.render());
+    process.stdout.write(output + '\n');
+    return 0;
+}
+//# sourceMappingURL=agent-command.js.map

package/dist/cli/app.js

@@ -0,0 +1,31 @@
+import { parseCliArgs, HELP } from './args.js';
+import { runAgentCommand } from './agent-command.js';
+import { runBenchCommand } from './bench-command.js';
+import { runDismissCommand } from './dismiss-command.js';
+import { loadRepositoryEnv } from './environment.js';
+import { runReviewCommand } from './review-command.js';
+import { runSessionCommand } from './session-command.js';
+const REVIEW_COMMANDS = new Set(['review', 'scan', 'delegate']);
+export async function runCli(args = process.argv.slice(2)) {
+    loadRepositoryEnv();
+    const { values, positionals } = parseCliArgs(args);
+    if (values.help || positionals[0] === 'help') {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    const command = positionals[0] ?? 'review';
+    if (command === 'bench')
+        return runBenchCommand(values);
+    if (command === 'agent')
+        return runAgentCommand(positionals[1]);
+    if (command === 'dismiss')
+        return runDismissCommand(positionals, values.reason);
+    if (command === 'session')
+        return runSessionCommand(positionals);
+    if (!REVIEW_COMMANDS.has(command)) {
+        process.stderr.write('Unknown command "' + command + '". Try: psh --help\n');
+        return 2;
+    }
+    return runReviewCommand(command, values, positionals);
+}
+//# sourceMappingURL=app.js.map