edsger 0.50.0 → 0.52.0

package/dist/phases/find-shared/mcp.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MCP helpers shared by find-bugs / find-features / find-smells.
+ *
+ * All three load a product's basics (name, description) for prompt context,
+ * pull the open-issue list for dedup, and file findings via `issues/create`.
+ * Centralising the calls means a schema change in MCP only needs touching one
+ * place, and the per-phase orchestrators stay focused on their own logic.
+ */
+import { type IssueInfo } from '../../types/issues.js';
+export interface ProductBasics {
+    name: string;
+    description?: string;
+}
+export declare function fetchProductBasics(productId: string): Promise<ProductBasics>;
+/**
+ * Fetch the product's open issues for dedup context. Filters out terminal
+ * statuses (shipped/archived/closed/...) since those can't conflict with new
+ * findings the agent might surface.
+ */
+export declare function fetchOpenIssues(productId: string): Promise<IssueInfo[]>;
+export declare function isTerminalStatus(status: string): boolean;
+export interface CreateIssueInput {
+    productId: string;
+    /** Issue title for `name`. */
+    title: string;
+    /** Already-formatted markdown body. The caller decides the layout. */
+    description: string;
+}
+/**
+ * File a new issue via MCP. Returns the new issue id, or null if MCP returned
+ * an error / unexpected shape (already logged).
+ */
+export declare function createIssue(input: CreateIssueInput): Promise<string | null>;

package/dist/phases/find-shared/mcp.js

@@ -0,0 +1,69 @@
+/**
+ * MCP helpers shared by find-bugs / find-features / find-smells.
+ *
+ * All three load a product's basics (name, description) for prompt context,
+ * pull the open-issue list for dedup, and file findings via `issues/create`.
+ * Centralising the calls means a schema change in MCP only needs touching one
+ * place, and the per-phase orchestrators stay focused on their own logic.
+ */
+import { callMcpEndpoint } from '../../api/mcp-client.js';
+import { logError, logWarning } from '../../utils/logger.js';
+export async function fetchProductBasics(productId) {
+    try {
+        const result = (await callMcpEndpoint('resources/read', {
+            uri: `product://${productId}`,
+        }));
+        const text = result.contents?.[0]?.text || '{}';
+        const parsed = JSON.parse(text);
+        return {
+            name: parsed.name || productId,
+            description: parsed.description,
+        };
+    }
+    catch {
+        return { name: productId };
+    }
+}
+/**
+ * Fetch the product's open issues for dedup context. Filters out terminal
+ * statuses (shipped/archived/closed/...) since those can't conflict with new
+ * findings the agent might surface.
+ */
+export async function fetchOpenIssues(productId) {
+    try {
+        const result = (await callMcpEndpoint('issues/list', {
+            product_id: productId,
+        }));
+        const all = result.issues || [];
+        return all.filter((i) => !isTerminalStatus(i.status));
+    }
+    catch (error) {
+        logWarning(`Could not load existing issues for dedup: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}
+export function isTerminalStatus(status) {
+    return (status === 'shipped' ||
+        status === 'archived' ||
+        status === 'cancelled' ||
+        status === 'closed' ||
+        status === 'completed');
+}
+/**
+ * File a new issue via MCP. Returns the new issue id, or null if MCP returned
+ * an error / unexpected shape (already logged).
+ */
+export async function createIssue(input) {
+    try {
+        const result = (await callMcpEndpoint('issues/create', {
+            product_id: input.productId,
+            name: input.title,
+            description: input.description,
+        }));
+        return result.issue?.id || result.id || null;
+    }
+    catch (error) {
+        logError(`Failed to create issue for "${input.title}": ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}

package/dist/phases/find-shared/scan-state.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-product scan state, generic across the find-* phases. Each phase has
+ * its own state schema (find-bugs tracks a commit sha, find-features tracks
+ * the most-recent-seen feedback id, etc.) so the type is parametric, but the
+ * file layout, atomic-write, and lock semantics are identical and live here.
+ *
+ * Storage layout: `~/.edsger/<dirName>/<productId>.json` plus a sibling
+ * `.lock` file. The lockfile uses O_EXCL so concurrent acquirers race on the
+ * filesystem, not on application code — atomic on local POSIX filesystems
+ * (good enough; the workspace clone is also machine-local).
+ *
+ * Known limitation: state is machine-local. A scan started on machine A and
+ * next on machine B will look like a first run.
+ */
+export interface LockHandle {
+    release: () => void;
+}
+export interface ScanStateModule<T extends object> {
+    load: (productId: string) => T;
+    save: (productId: string, state: T) => void;
+    /** Merge `patch` into the stored state. Fields not mentioned are preserved. */
+    update: (productId: string, patch: Partial<T>) => T;
+    /**
+     * Acquire an exclusive lock for this product's state. Returns null if held.
+     * Stale locks older than `staleAfterMs` (default 1h) are reclaimed.
+     */
+    acquireLock: (productId: string, staleAfterMs?: number) => LockHandle | null;
+}
+export interface CreateScanStateModuleOptions {
+    /** Subdirectory under ~/.edsger/. Example: 'find-bugs-state'. */
+    dirName: string;
+}
+export declare function createScanStateModule<T extends object>(opts: CreateScanStateModuleOptions): ScanStateModule<T>;

package/dist/phases/find-shared/scan-state.js

@@ -0,0 +1,112 @@
+/**
+ * Per-product scan state, generic across the find-* phases. Each phase has
+ * its own state schema (find-bugs tracks a commit sha, find-features tracks
+ * the most-recent-seen feedback id, etc.) so the type is parametric, but the
+ * file layout, atomic-write, and lock semantics are identical and live here.
+ *
+ * Storage layout: `~/.edsger/<dirName>/<productId>.json` plus a sibling
+ * `.lock` file. The lockfile uses O_EXCL so concurrent acquirers race on the
+ * filesystem, not on application code — atomic on local POSIX filesystems
+ * (good enough; the workspace clone is also machine-local).
+ *
+ * Known limitation: state is machine-local. A scan started on machine A and
+ * next on machine B will look like a first run.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+const DEFAULT_STALE_AFTER_MS = 60 * 60 * 1000;
+export function createScanStateModule(opts) {
+    const { dirName } = opts;
+    // Resolve at call time, not module-load time, so test setups that swap
+    // process.env.HOME between cases see the change.
+    function stateDir() {
+        return join(homedir(), '.edsger', dirName);
+    }
+    function safeProductId(productId) {
+        return productId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    }
+    function statePath(productId) {
+        return join(stateDir(), `${safeProductId(productId)}.json`);
+    }
+    function lockPath(productId) {
+        return join(stateDir(), `${safeProductId(productId)}.lock`);
+    }
+    function ensureStateDir() {
+        const dir = stateDir();
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    function load(productId) {
+        const p = statePath(productId);
+        if (!existsSync(p)) {
+            return {};
+        }
+        try {
+            const raw = readFileSync(p, 'utf-8');
+            const parsed = JSON.parse(raw);
+            return parsed && typeof parsed === 'object' ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    /** Atomic write: stage to a tempfile, then rename. */
+    function save(productId, state) {
+        ensureStateDir();
+        const finalPath = statePath(productId);
+        const tmpPath = `${finalPath}.${process.pid}.tmp`;
+        writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf-8');
+        renameSync(tmpPath, finalPath);
+    }
+    function update(productId, patch) {
+        const merged = { ...load(productId), ...patch };
+        save(productId, merged);
+        return merged;
+    }
+    function acquireLock(productId, staleAfterMs = DEFAULT_STALE_AFTER_MS) {
+        ensureStateDir();
+        const lock = lockPath(productId);
+        if (existsSync(lock)) {
+            try {
+                const raw = readFileSync(lock, 'utf-8');
+                const parsed = JSON.parse(raw);
+                const age = Date.now() - new Date(parsed.acquiredAt ?? 0).getTime();
+                if (age < staleAfterMs) {
+                    return null;
+                }
+                // Stale or corrupt — reclaim. Only reachable if a previous run died
+                // without releasing (SIGKILL, OOM).
+                rmSync(lock, { force: true });
+            }
+            catch {
+                rmSync(lock, { force: true });
+            }
+        }
+        try {
+            // `flag: 'wx'` = open with O_CREAT | O_EXCL — atomic against a racing
+            // peer, and writeFileSync(path, ...) closes the fd internally so no
+            // manual closeSync is needed (vs. the openSync + writeFileSync(fd)
+            // form, which leaks the fd).
+            writeFileSync(lock, JSON.stringify({
+                acquiredAt: new Date().toISOString(),
+                pid: process.pid,
+            }), { flag: 'wx' });
+            return {
+                release: () => {
+                    try {
+                        unlinkSync(lock);
+                    }
+                    catch {
+                        // Already gone — fine.
+                    }
+                },
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    return { load, save, update, acquireLock };
+}

package/dist/phases/find-smells/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Find-smells phase: clone the product's repo, ask Claude to audit code for
+ * code smells (refactor candidates, perf cliffs, dead code, etc.), and file
+ * each new finding as an issue. Subsequent runs are incremental, scoped to
+ * commits since the previous successful scan.
+ *
+ * Companion to find-bugs (real defects) and find-features (missing user
+ * capability). The three phases share the same workspace + state pattern.
+ */
+import { type SmellCategory } from './types.js';
+export interface FindSmellsOptions {
+    productId: string;
+    githubToken: string;
+    owner: string;
+    repo: string;
+    /** Force a full scan even if previous-scan state exists. */
+    full?: boolean;
+    /** Branch to scan; defaults to the repo's default branch. */
+    branch?: string;
+    /** Upper bound on files the auditor may Read. Keeps token cost predictable. */
+    maxFiles?: number;
+    /**
+     * Optional category filter. Agent is asked to honour it via the prompt
+     * AND its output is re-filtered after parsing — both are required because
+     * the agent can't be trusted to obey perfectly.
+     */
+    categories?: SmellCategory[];
+    verbose?: boolean;
+}
+export interface FindSmellsResult {
+    status: 'success' | 'error';
+    message: string;
+    scannedCommitSha?: string;
+    smellsFound?: number;
+    issuesCreated?: number;
+    /** Findings the agent passed off to find-bugs (not filed by this run). */
+    deferredToBugs?: number;
+    /** Findings the agent passed off to find-features (not filed by this run). */
+    deferredToFeatures?: number;
+    summary?: string;
+}
+/** Single source of truth — referenced by the CLI help string too. */
+export declare const DEFAULT_MAX_FILES = 200;
+/**
+ * Scan a product's repository for code smells and file each new finding as an issue.
+ */
+export declare function scanForSmells(options: FindSmellsOptions): Promise<FindSmellsResult>;

package/dist/phases/find-smells/index.js

@@ -0,0 +1,278 @@
+/**
+ * Find-smells phase: clone the product's repo, ask Claude to audit code for
+ * code smells (refactor candidates, perf cliffs, dead code, etc.), and file
+ * each new finding as an issue. Subsequent runs are incremental, scoped to
+ * commits since the previous successful scan.
+ *
+ * Companion to find-bugs (real defects) and find-features (missing user
+ * capability). The three phases share the same workspace + state pattern.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cloneIssueRepo, ensureWorkspaceDir, syncRepoToRef, } from '../../workspace/workspace-manager.js';
+import { detectDefaultBranch, gitRevParse, isAncestor, listChangedPaths, } from '../find-shared/git.js';
+import { createIssue, fetchOpenIssues, fetchProductBasics, } from '../find-shared/mcp.js';
+import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
+import { createFindSmellsSystemPrompt, createFindSmellsUserPrompt, } from './prompts.js';
+import { acquireFindSmellsLock, loadFindSmellsState, updateFindSmellsState, } from './state.js';
+import { isScanResult, isSmellCategory, } from './types.js';
+const WORKSPACE_KEY = 'find-smells';
+/** Single source of truth — referenced by the CLI help string too. */
+export const DEFAULT_MAX_FILES = 200;
+/**
+ * Upper bound on turns for the in-CLI Claude session. Same rationale as
+ * find-bugs: read-only but open-scope audit needs headroom for repo-wide
+ * Glob/Read/Grep without runaway exploration.
+ */
+const MAX_TURNS = 200;
+/**
+ * Scan a product's repository for code smells and file each new finding as an issue.
+ */
+// eslint-disable-next-line complexity
+export async function scanForSmells(options) {
+    const { productId, githubToken, owner, repo, full, maxFiles, categories, verbose, } = options;
+    logInfo(`Starting smell scan for product ${productId} (${owner}/${repo})`);
+    const lock = acquireFindSmellsLock(productId);
+    if (!lock) {
+        logWarning(`Another smell scan is already in progress for product ${productId}; skipping.`);
+        return {
+            status: 'error',
+            message: 'Another smell scan is already in progress for this product',
+        };
+    }
+    try {
+        updateFindSmellsState(productId, {
+            lastAttemptedAt: new Date().toISOString(),
+        });
+        const workspaceRoot = ensureWorkspaceDir();
+        const repoKey = `${WORKSPACE_KEY}-${productId}`;
+        const cloned = cloneIssueRepo(workspaceRoot, repoKey, owner, repo, githubToken);
+        const { repoPath } = cloned;
+        const branch = options.branch ?? detectDefaultBranch(repoPath);
+        logInfo(`Syncing ${owner}/${repo} to branch ${branch}`);
+        syncRepoToRef(repoPath, { branch }, githubToken);
+        const headSha = gitRevParse(repoPath, 'HEAD');
+        const state = loadFindSmellsState(productId);
+        const baseSha = full ? undefined : state.lastScannedCommitSha;
+        let scope = 'full';
+        let changedPaths;
+        if (baseSha && baseSha !== headSha) {
+            const sameTree = isAncestor(repoPath, baseSha, headSha);
+            if (sameTree) {
+                scope = 'incremental';
+                changedPaths = listChangedPaths(repoPath, baseSha, headSha);
+                logInfo(`Incremental scan: ${changedPaths.length} files changed since ${baseSha.slice(0, 8)}`);
+                if (changedPaths.length === 0) {
+                    logSuccess('No code changes since last scan; nothing to do.');
+                    updateFindSmellsState(productId, {
+                        lastScannedCommitSha: headSha,
+                        lastScannedAt: new Date().toISOString(),
+                        lastError: undefined,
+                    });
+                    return {
+                        status: 'success',
+                        message: 'No changes since last scan',
+                        scannedCommitSha: headSha,
+                        smellsFound: 0,
+                        issuesCreated: 0,
+                    };
+                }
+            }
+            else {
+                logWarning(`Last scanned sha ${baseSha.slice(0, 8)} not reachable from HEAD; falling back to full scan.`);
+            }
+        }
+        else if (baseSha === headSha) {
+            // Symmetric with the "no changed files" early return above: even though
+            // the sha didn't move, advance lastScannedAt + clear lastError so the
+            // state file accurately reflects when we last verified the repo.
+            logSuccess('HEAD unchanged since last scan; nothing to do.');
+            updateFindSmellsState(productId, {
+                lastScannedAt: new Date().toISOString(),
+                lastError: undefined,
+            });
+            return {
+                status: 'success',
+                message: 'HEAD unchanged since last scan',
+                scannedCommitSha: headSha,
+                smellsFound: 0,
+                issuesCreated: 0,
+            };
+        }
+        const product = await fetchProductBasics(productId);
+        const existingIssues = await fetchOpenIssues(productId);
+        logInfo(`Loaded ${existingIssues.length} existing issues for dedup context`);
+        const systemPrompt = createFindSmellsSystemPrompt();
+        const userPrompt = createFindSmellsUserPrompt({
+            productName: product.name,
+            productDescription: product.description,
+            scope,
+            baseSha,
+            headSha,
+            changedPaths,
+            maxFiles: maxFiles ?? DEFAULT_MAX_FILES,
+            categories,
+            existingIssues: existingIssues.map((i) => ({
+                id: i.id,
+                name: i.name,
+                description: i.description,
+            })),
+        });
+        let lastAssistantResponse = '';
+        let scanResult = null;
+        logInfo('Running Claude code-smell audit...');
+        for await (const message of query({
+            prompt: createPromptGenerator(userPrompt),
+            options: {
+                systemPrompt: {
+                    type: 'preset',
+                    preset: 'claude_code',
+                    append: systemPrompt,
+                },
+                model: DEFAULT_MODEL,
+                maxTurns: MAX_TURNS,
+                permissionMode: 'bypassPermissions',
+                cwd: repoPath,
+            },
+        })) {
+            if (message.type === 'assistant') {
+                lastAssistantResponse += extractTextFromContent(message.message?.content ?? [], verbose);
+                continue;
+            }
+            if (message.type !== 'result') {
+                continue;
+            }
+            const responseText = message.subtype === 'success'
+                ? message.result || lastAssistantResponse
+                : lastAssistantResponse;
+            const parsed = tryExtractResult(responseText, 'scan_result');
+            if (isScanResult(parsed)) {
+                scanResult = parsed;
+            }
+            else if (message.subtype !== 'success') {
+                logError(`Audit incomplete: ${message.subtype}`);
+            }
+        }
+        if (!scanResult) {
+            const msg = 'Audit failed: could not parse a scan_result from the agent';
+            updateFindSmellsState(productId, { lastError: msg });
+            return {
+                status: 'error',
+                message: msg,
+            };
+        }
+        const { summary, smells } = scanResult;
+        logInfo(`Audit produced ${smells.length} candidate smells. ${summary}`);
+        const deferredBugs = scanResult.deferred_to_bugs ?? [];
+        const deferredFeatures = scanResult.deferred_to_features ?? [];
+        if (deferredBugs.length > 0) {
+            logInfo(`${deferredBugs.length} finding(s) deferred to find-bugs — run \`edsger find-bugs ${productId}\` to pick them up:`);
+            for (const d of deferredBugs) {
+                const loc = d.file ? ` (${d.file}${d.line ? `:${d.line}` : ''})` : '';
+                logInfo(`  • ${d.title}${loc} — ${d.reason}`);
+            }
+        }
+        if (deferredFeatures.length > 0) {
+            logInfo(`${deferredFeatures.length} finding(s) deferred to find-features — run \`edsger find-features ${productId}\` to pick them up:`);
+            for (const d of deferredFeatures) {
+                const loc = d.file ? ` (${d.file}${d.line ? `:${d.line}` : ''})` : '';
+                logInfo(`  • ${d.title}${loc} — ${d.reason}`);
+            }
+        }
+        const { kept: filteredSmells, droppedCategories } = filterByCategories(smells, categories);
+        if (droppedCategories.length > 0) {
+            const summaryLine = droppedCategories
+                .map(({ category, count }) => `${category}×${count}`)
+                .join(', ');
+            logWarning(`Dropped findings outside the requested categories or with unknown category: ${summaryLine}.`);
+        }
+        let created = 0;
+        for (const smell of filteredSmells) {
+            const issueId = await createIssueForSmell(productId, smell);
+            if (issueId) {
+                created++;
+                logSuccess(`Filed issue ${issueId}: ${smell.title}`);
+            }
+        }
+        updateFindSmellsState(productId, {
+            lastScannedCommitSha: headSha,
+            lastScannedAt: new Date().toISOString(),
+            lastError: undefined,
+        });
+        const droppedCount = droppedCategories.reduce((acc, d) => acc + d.count, 0);
+        return {
+            status: 'success',
+            message: `Filed ${created} of ${filteredSmells.length} candidate smells (${droppedCount} dropped by category filter; ${deferredBugs.length} deferred to bugs, ${deferredFeatures.length} to features)`,
+            scannedCommitSha: headSha,
+            smellsFound: filteredSmells.length,
+            issuesCreated: created,
+            deferredToBugs: deferredBugs.length,
+            deferredToFeatures: deferredFeatures.length,
+            summary,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`Smell scan failed: ${errorMessage}`);
+        updateFindSmellsState(productId, { lastError: errorMessage });
+        return {
+            status: 'error',
+            message: `Smell scan failed: ${errorMessage}`,
+        };
+    }
+    finally {
+        lock.release();
+    }
+}
+async function createIssueForSmell(productId, smell) {
+    return createIssue({
+        productId,
+        title: smell.title,
+        description: formatIssueDescription(smell),
+    });
+}
+/**
+ * Filter the agent's findings down to the requested categories. The system
+ * prompt asks the agent to honour the filter, but trusting the prompt alone
+ * lets bad output through; we re-check here. Items with an unknown category
+ * are also dropped — the type system can't enforce that across the JSON
+ * boundary.
+ *
+ * Returns per-category drop counts so the user-facing warning can name the
+ * specific categories that were filtered out (more actionable than a bare
+ * total).
+ */
+function filterByCategories(smells, categories) {
+    const allow = categories?.length ? new Set(categories) : null;
+    const kept = [];
+    const droppedTally = new Map();
+    for (const s of smells) {
+        const known = isSmellCategory(s.category);
+        const inAllow = !allow || (known && allow.has(s.category));
+        if (known && inAllow) {
+            kept.push(s);
+            continue;
+        }
+        const key = known ? s.category : '<unknown>';
+        droppedTally.set(key, (droppedTally.get(key) ?? 0) + 1);
+    }
+    const droppedCategories = Array.from(droppedTally.entries())
+        .map(([category, count]) => ({ category, count }))
+        .sort((a, b) => b.count - a.count);
+    return { kept, droppedCategories };
+}
+function formatIssueDescription(smell) {
+    const location = smell.line ? `${smell.file}:${smell.line}` : smell.file;
+    const lines = [
+        `**Severity**: ${smell.severity}`,
+        `**Category**: ${smell.category}`,
+        `**Location**: \`${location}\``,
+        '',
+        smell.description,
+        '',
+        '---',
+        '_Filed automatically by `edsger find-smells`._',
+    ];
+    return lines.join('\n');
+}

package/dist/phases/find-smells/prompts.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Prompts for the find-smells phase. The agent runs with cwd=repo checkout
+ * and has Read/Grep/Glob/Bash available — it explores the code itself
+ * rather than receiving a pre-baked diff.
+ *
+ * Boundary against neighbouring phases:
+ *   - find-bugs handles real defects (security, correctness, races, etc.)
+ *   - find-features handles missing user-facing capability
+ *   - find-smells (this phase) handles "the code would be better if changed":
+ *     refactor candidates, dead code, perf cliffs, type-safety gaps, etc.
+ */
+export declare function createFindSmellsSystemPrompt(): string;
+export interface FindSmellsUserPromptParams {
+    productName: string;
+    productDescription?: string;
+    scope: 'full' | 'incremental';
+    baseSha?: string;
+    headSha: string;
+    changedPaths?: string[];
+    existingIssues: {
+        id: string;
+        name: string;
+        description?: string;
+    }[];
+    /** Upper bound on files the auditor may Read. Keeps token cost predictable. */
+    maxFiles?: number;
+    /** Optional comma-separated category filter from the CLI. */
+    categories?: string[];
+}
+export declare function createFindSmellsUserPrompt(params: FindSmellsUserPromptParams): string;