diff-easy 0.1.0

package/dist/server/grouping/cache.d.ts

@@ -0,0 +1,3 @@
+import type { GroupingResult } from './types.js';
+export declare function readCache(baseDir: string, targetHash: string, model: string): GroupingResult | null;
+export declare function writeCache(baseDir: string, targetHash: string, model: string, result: GroupingResult): void;

package/dist/server/grouping/cache.js

@@ -0,0 +1,22 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+function fileFor(baseDir, targetHash, model) {
+    const safe = `${targetHash}-${model}`.replace(/[^a-zA-Z0-9._-]/g, '_');
+    return join(baseDir, 'grouping', `${safe}.json`);
+}
+export function readCache(baseDir, targetHash, model) {
+    const file = fileFor(baseDir, targetHash, model);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCache(baseDir, targetHash, model, result) {
+    const file = fileFor(baseDir, targetHash, model);
+    mkdirSync(join(baseDir, 'grouping'), { recursive: true });
+    writeFileSync(file, JSON.stringify(result), 'utf8');
+}

package/dist/server/grouping/claudeCli.d.ts

@@ -0,0 +1,10 @@
+import type { DiffResponse } from '../../types/diff.js';
+import type { GroupingResult } from './types.js';
+/** Injectable so tests never spawn a process. */
+export interface ClaudeRunner {
+    run(prompt: string, model: string): Promise<string>;
+}
+export declare function groupWithClaude(diff: DiffResponse, intent: string | null, opts: {
+    model: string;
+    runner?: ClaudeRunner;
+}): Promise<GroupingResult>;

package/dist/server/grouping/claudeCli.js

@@ -0,0 +1,95 @@
+// src/server/grouping/claudeCli.ts
+import { spawn } from 'child_process';
+import { groupSmart } from '../../shared/grouping.js';
+import { buildDigest } from './digest.js';
+import { reconcile } from './reconcile.js';
+// User-invoked (they click Group and wait), and a cold `claude -p` start with a
+// multi-file digest routinely exceeds 20s — a short timeout made the AI path
+// almost always fall back to heuristic. 60s gives real calls room to finish.
+const DEFAULT_TIMEOUT_MS = 60_000;
+function buildPrompt(digest) {
+    return [
+        'You are grouping the changed files of a code diff for review.',
+        'Return ONLY a JSON object, no prose, of the form:',
+        '{"groups":[{"label":"short intent phrase","rationale":"one line","files":["path"]}],"noise":["generated/path"]}',
+        'Rules: use ONLY the paths listed below; put generated/lockfile/build-output paths in "noise";',
+        'order groups so the most important thing to review is first; every non-noise path in exactly one group.',
+        '',
+        digest,
+    ].join('\n');
+}
+/** Extract a JSON object from the CLI envelope, tolerant of surrounding prose. */
+function extractGrouping(stdout) {
+    const envelope = JSON.parse(stdout);
+    if (typeof envelope.result !== 'string')
+        throw new Error('envelope missing result');
+    const inner = envelope.result;
+    const start = inner.indexOf('{');
+    const end = inner.lastIndexOf('}');
+    if (start === -1 || end === -1 || end < start)
+        throw new Error('no JSON object in output');
+    return JSON.parse(inner.slice(start, end + 1));
+}
+const defaultRunner = {
+    run(prompt, model) {
+        return new Promise((resolve, reject) => {
+            const child = spawn('claude', ['-p', '--output-format', 'json', '--model', model], {
+                // Capture stderr so a failing call reports *why* instead of silently
+                // falling back to heuristic with no diagnostic.
+                stdio: ['pipe', 'pipe', 'pipe'],
+                // Mark this Claude session as diff-easy-internal so our own turn-capture
+                // hook (the `snapshot` command) no-ops instead of recording the grouping
+                // call as a spurious agent turn. See src/cli/turns.ts:runSnapshot.
+                env: { ...process.env, DIFIT_INTERNAL_CLAUDE: '1' },
+            });
+            let out = '';
+            let err = '';
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                child.kill('SIGKILL');
+                reject(new Error(`claude timed out after ${DEFAULT_TIMEOUT_MS}ms`));
+            }, DEFAULT_TIMEOUT_MS);
+            child.stdout.on('data', (d) => (out += d.toString()));
+            child.stderr.on('data', (d) => (err += d.toString()));
+            child.on('error', (e) => {
+                clearTimeout(timer);
+                if (settled)
+                    return;
+                settled = true;
+                reject(e);
+            });
+            child.on('close', (code) => {
+                clearTimeout(timer);
+                if (settled)
+                    return;
+                settled = true;
+                if (code === 0)
+                    resolve(out);
+                else
+                    reject(new Error(`claude exited ${code}: ${err.trim().slice(0, 300) || '(no stderr)'}`));
+            });
+            child.stdin.end(prompt);
+        });
+    },
+};
+export async function groupWithClaude(diff, intent, opts) {
+    const runner = opts.runner ?? defaultRunner;
+    const { text, changedPaths } = buildDigest(diff, intent);
+    try {
+        const stdout = await runner.run(buildPrompt(text), opts.model);
+        const raw = extractGrouping(stdout);
+        const { groups, noise } = reconcile(raw, changedPaths);
+        return { mode: 'ai', groups, noise, model: opts.model, generatedAt: Date.now() };
+    }
+    catch (error) {
+        // Any failure (process error, timeout, unparseable output, invalid shape)
+        // degrades gracefully to the heuristic provider rather than surfacing an error.
+        // Log why, so "grouped without AI" is diagnosable instead of a silent mystery.
+        const reason = error instanceof Error ? error.message : String(error);
+        console.warn(`[grouping] claude grouping failed for ${changedPaths.length} files; using heuristic. Reason: ${reason}`);
+        return { ...groupSmart(diff.files), fallbackFrom: 'ai' };
+    }
+}

package/dist/server/grouping/digest.d.ts

@@ -0,0 +1,15 @@
+import type { DiffResponse } from '../../types/diff.js';
+export interface Digest {
+    text: string;
+    changedPaths: string[];
+}
+/** Hunk headers add function/scope context but drive most of the model's output
+ * tokens (which dominate latency). They pay off on small diffs and starve large
+ * ones — a 64-file digest with 8 headers/file made the `claude -p` call exceed
+ * the 60s timeout, while paths alone grouped the same files in ~18s. So scale
+ * the per-file header budget down as the file count grows. */
+export declare function hunkHeaderBudget(fileCount: number): number;
+/** Compact, token-bounded representation of a diff for the grouping model.
+ * We send file paths + status + line counts + (for smaller diffs) a few hunk
+ * headers, not the full diff, to keep latency/cost low. */
+export declare function buildDigest(diff: DiffResponse, intent: string | null): Digest;

package/dist/server/grouping/digest.js

@@ -0,0 +1,38 @@
+/** Hunk headers add function/scope context but drive most of the model's output
+ * tokens (which dominate latency). They pay off on small diffs and starve large
+ * ones — a 64-file digest with 8 headers/file made the `claude -p` call exceed
+ * the 60s timeout, while paths alone grouped the same files in ~18s. So scale
+ * the per-file header budget down as the file count grows. */
+export function hunkHeaderBudget(fileCount) {
+    if (fileCount > 40)
+        return 0;
+    if (fileCount > 15)
+        return 3;
+    return 8;
+}
+/** Compact, token-bounded representation of a diff for the grouping model.
+ * We send file paths + status + line counts + (for smaller diffs) a few hunk
+ * headers, not the full diff, to keep latency/cost low. */
+export function buildDigest(diff, intent) {
+    const changedPaths = diff.files.map((f) => f.path);
+    const perFileHeaders = hunkHeaderBudget(diff.files.length);
+    const lines = [];
+    if (intent && intent.trim()) {
+        lines.push('INTENT (the change was made to accomplish this):');
+        lines.push(intent.trim().slice(0, 2000));
+        lines.push('');
+    }
+    lines.push(`CHANGED FILES (${diff.files.length}):`);
+    for (const file of diff.files) {
+        lines.push(`${file.status}  ${file.path} (+${file.additions} -${file.deletions})`);
+        if (perFileHeaders === 0)
+            continue;
+        const headers = file.chunks
+            .map((c) => c.header)
+            .filter((h) => typeof h === 'string' && h.length > 0)
+            .slice(0, perFileHeaders);
+        for (const h of headers)
+            lines.push(`    ${h}`);
+    }
+    return { text: lines.join('\n'), changedPaths };
+}

package/dist/server/grouping/reconcile.d.ts

@@ -0,0 +1,6 @@
+import type { FileGroup, RawGrouping } from './types.js';
+/** Force the model's loose output onto the real changed-file set. */
+export declare function reconcile(raw: RawGrouping, changedPaths: string[]): {
+    groups: FileGroup[];
+    noise: string[];
+};

package/dist/server/grouping/reconcile.js

@@ -0,0 +1,34 @@
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((v) => typeof v === 'string');
+}
+/** Force the model's loose output onto the real changed-file set. */
+export function reconcile(raw, changedPaths) {
+    const changed = new Set(changedPaths);
+    const assigned = new Set();
+    const noise = asStringArray(raw.noise).filter((p) => changed.has(p));
+    for (const p of noise)
+        assigned.add(p);
+    const groups = [];
+    for (const g of Array.isArray(raw.groups) ? raw.groups : []) {
+        const files = asStringArray(g.files).filter((p) => changed.has(p) && !assigned.has(p));
+        if (files.length === 0)
+            continue;
+        for (const p of files)
+            assigned.add(p);
+        groups.push({
+            id: `g${groups.length + 1}`,
+            label: typeof g.label === 'string' && g.label.trim()
+                ? g.label.trim()
+                : `Group ${groups.length + 1}`,
+            rationale: typeof g.rationale === 'string' ? g.rationale : undefined,
+            files,
+        });
+    }
+    const leftover = changedPaths.filter((p) => !assigned.has(p));
+    if (leftover.length > 0) {
+        groups.push({ id: `g${groups.length + 1}`, label: 'Other', files: leftover });
+    }
+    return { groups, noise };
+}

package/dist/server/grouping/types.d.ts

@@ -0,0 +1,9 @@
+export type { FileGroup, GroupingResult } from '../../types/diff.js';
+export interface RawGrouping {
+    groups: Array<{
+        label?: unknown;
+        rationale?: unknown;
+        files?: unknown;
+    }>;
+    noise?: unknown;
+}

package/dist/server/grouping/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/server.d.ts

@@ -0,0 +1,37 @@
+import { type Server } from 'http';
+import { DiffMode } from '../types/watch.js';
+import { type CommentImport, type DiffSelection } from '@/types/diff.js';
+interface ServerOptions {
+    selection?: DiffSelection;
+    stdinDiff?: string;
+    preferredPort?: number;
+    host?: string;
+    openBrowser?: boolean;
+    ignoreWhitespace?: boolean;
+    clearComments?: boolean;
+    commentImports?: CommentImport[];
+    keepAlive?: boolean;
+    diffMode?: DiffMode;
+    repoPath?: string;
+    contextLines?: number;
+    /** Hub mode: start with no workspace and let the UI pick one at runtime. */
+    hub?: boolean;
+    /** CLI `--pr` launch: the PR's title/body, for grouping intent. */
+    prTitle?: string;
+    prBody?: string;
+}
+/**
+ * Disable git's optional index-refresh lock for every git child this process
+ * spawns. Read commands (git status/diff) otherwise opportunistically rewrite
+ * `.git/index`'s stat cache; the file watcher treats that as a change and
+ * triggers an endless reload loop (fetch → index rewrite → reload → fetch …).
+ * `??=` respects an explicit operator override.
+ */
+export declare function disableGitOptionalLocks(): void;
+export declare function startServer(options: ServerOptions): Promise<{
+    port: number;
+    url: string;
+    isEmpty?: boolean;
+    server?: Server;
+}>;
+export {};