edsger 0.51.0 → 0.53.0

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;

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

@@ -0,0 +1,129 @@
+/**
+ * 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 function createFindSmellsSystemPrompt() {
+    return `You are a senior engineer auditing a codebase for **code smells** — concrete improvements the codebase would benefit from. You have read-only access via Read/Grep/Glob and may run shallow Bash queries (e.g. \`git log\`, \`wc -l\`) to navigate.
+
+**What counts as a smell worth filing**:
+1. **Refactor**: duplicated logic across files, tangled module boundaries, leaky abstractions, primitive obsession
+2. **Performance**: clearly-suboptimal patterns (N+1 queries, unbounded loops on growing data, repeated work that could be cached, sync I/O in hot paths) that are not yet causing user-visible bugs
+3. **Duplication**: copy-pasted blocks that should be a single helper
+4. **Complexity**: functions / files that are too long or too deeply nested to reason about, cyclomatic-complexity hotspots
+5. **Dead code**: unreferenced exports, unreachable branches, abandoned feature flags, commented-out blocks
+6. **Type safety**: \`any\` / \`unknown\` casts, \`@ts-ignore\` / \`@ts-expect-error\`, missing null checks at trust boundaries, loose interfaces that should be tightened
+7. **Readability**: misleading names, missing or wrong comments, magic numbers that should be named constants
+8. **Architecture**: cyclic deps, layering violations, modules that have grown into multiple responsibilities
+
+**What does NOT count** (skip these — wrong tool):
+- Real bugs (security holes, logic errors, races, data corruption) — those belong in \`edsger find-bugs\`. **Don't drop them silently — list them in \`deferred_to_bugs\` so the user knows to run that command.**
+- Missing user-facing features or workflows — those belong in \`edsger find-features\`. **List them in \`deferred_to_features\` instead of dropping them.**
+- Pure style / formatting / lint issues a formatter would catch
+- "Could be more idiomatic" rewrites with no concrete benefit
+- Hypothetical future-scaling concerns with no current evidence
+- Missing tests (track those separately, not here)
+
+**Discipline**:
+- Be concrete: cite the exact file and line. Quote the offending snippet in the description, and propose the specific change.
+- Be conservative: if you can't articulate the *benefit* of changing it (clarity, perf number, removed coupling), skip it.
+- Severity rubric:
+  - high = pays back quickly (e.g. removes a hot-path N+1, deletes a large dead module, unblocks future work the team is clearly trying to do)
+  - medium = clear improvement but not urgent (typical refactor candidate)
+  - low = nice-to-have polish; only file if the change is small and obvious
+- **Deduplication**: you will be given the list of existing open issues. Skip any finding that overlaps. Better to under-report than spam duplicates.
+
+**CRITICAL — Output Format**:
+End your response with a single JSON code block in this exact shape:
+
+\`\`\`json
+{
+  "scan_result": {
+    "summary": "Reviewed N files in <scope>; found X smells (Y high, Z medium).",
+    "scanned_commit_sha": "<the HEAD sha you scanned>",
+    "smells": [
+      {
+        "title": "Short, action-oriented title (under 80 chars)",
+        "description": "## What\\nWhat the smell is, with the offending snippet quoted.\\n\\n## Why it matters\\nConcrete benefit of changing it (clarity, perf, decoupling).\\n\\n## Suggested change\\nA specific refactor or replacement.",
+        "file": "relative/path/from/repo/root.ts",
+        "line": 42,
+        "severity": "medium",
+        "category": "refactor",
+        "dedup_signature": "auth-service-duplicated-token-parser"
+      }
+    ],
+    "deferred_to_bugs": [
+      {
+        "title": "Short title of the suspected bug",
+        "reason": "One-line note of why this looks like a real defect, not a smell",
+        "file": "relative/path.ts",
+        "line": 100
+      }
+    ],
+    "deferred_to_features": [
+      {
+        "title": "Short title of the missing capability",
+        "reason": "One-line note of the user need this would address",
+        "file": "relative/path.ts"
+      }
+    ]
+  }
+}
+\`\`\`
+
+If you find nothing worth filing, still emit the JSON with an empty \`smells\` array. The \`deferred_to_*\` arrays are optional — omit them or send \`[]\` if there's nothing to hand off.`;
+}
+export function createFindSmellsUserPrompt(params) {
+    const { productName, productDescription, scope, baseSha, headSha, changedPaths, existingIssues, maxFiles, categories, } = params;
+    const productBlock = productDescription
+        ? `**Product**: ${productName}\n${productDescription}`
+        : `**Product**: ${productName}`;
+    const scopeBlock = scope === 'incremental' && baseSha
+        ? `**Scope**: incremental scan of changes between ${baseSha} and ${headSha}.\nUse \`git diff --name-only ${baseSha}..${headSha}\` to enumerate changed files, then Read/Grep them. Do NOT scan files outside the diff.`
+        : `**Scope**: full repository scan at ${headSha}. Use Glob to enumerate source files. Skip vendored code, build output, generated files, lockfiles, and \`node_modules\`.`;
+    const filesHint = changedPaths && changedPaths.length > 0
+        ? `\n**Changed files in this range** (${changedPaths.length}):\n${changedPaths
+            .slice(0, 200)
+            .map((p) => `- ${p}`)
+            .join('\n')}${changedPaths.length > 200 ? `\n…and ${changedPaths.length - 200} more.` : ''}`
+        : '';
+    const issuesBlock = existingIssues.length === 0
+        ? 'No existing open issues for this product — every finding is new.'
+        : `**Existing open issues** (${existingIssues.length}) — skip findings that overlap with any of these:\n${existingIssues
+            .map((i) => `- [${i.id}] ${i.name}${i.description ? `\n  ${truncate(i.description, 200)}` : ''}`)
+            .join('\n')}`;
+    const budgetBlock = typeof maxFiles === 'number' && maxFiles > 0
+        ? `\n**Budget**: Read at most ${maxFiles} files. Prioritise files most likely to harbour smells (large modules, frequently-edited code per \`git log\`, files with \`any\`/\`@ts-ignore\`, hot data-access paths) over test fixtures and generated code. If the scope is larger than the budget, stop when you hit it and report truncation in \`summary\`.`
+        : '';
+    const categoryBlock = categories && categories.length > 0
+        ? `\n**Category filter**: only file findings whose \`category\` is one of: ${categories.join(', ')}. Drop everything else.`
+        : '';
+    return `${productBlock}
+
+${scopeBlock}${filesHint}${budgetBlock}${categoryBlock}
+
+${issuesBlock}
+
+## How to work
+
+1. Identify the files in scope (per the scope block above).
+2. For each file, Read it and look for the smell categories listed in the system prompt.
+3. When you suspect a smell, re-read the surrounding context to confirm the *benefit* of changing it. If you can't name the benefit, drop it.
+4. If something looks like a real bug (not a smell), drop it — \`edsger find-bugs\` covers that.
+5. Cross-check every candidate against the existing issues list. Drop overlaps.
+6. Produce the final JSON described in the system prompt.
+
+Begin.`;
+}
+function truncate(s, n) {
+    if (s.length <= n) {
+        return s;
+    }
+    return `${s.slice(0, n)}…`;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Per-product scan state for find-smells. Storage at
+ * `~/.edsger/find-smells-state/<productId>.json`.
+ *
+ * Same schema shape as find-bugs (incremental sha tracking) — file/lock
+ * machinery shared via createScanStateModule. Kept as a sibling state file
+ * (not merged with find-bugs) so a smell scan and a bug scan can run
+ * concurrently without contending on the same lock.
+ */
+import { type LockHandle } from '../find-shared/scan-state.js';
+export type { LockHandle };
+export interface FindSmellsState {
+    lastScannedCommitSha?: string;
+    lastScannedAt?: string;
+    lastAttemptedAt?: string;
+    lastError?: string;
+}
+export declare const loadFindSmellsState: (productId: string) => FindSmellsState;
+export declare const saveFindSmellsState: (productId: string, state: FindSmellsState) => void;
+export declare const updateFindSmellsState: (productId: string, patch: Partial<FindSmellsState>) => FindSmellsState;
+export declare const acquireFindSmellsLock: (productId: string, staleAfterMs?: number) => LockHandle | null;

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

@@ -0,0 +1,17 @@
+/**
+ * Per-product scan state for find-smells. Storage at
+ * `~/.edsger/find-smells-state/<productId>.json`.
+ *
+ * Same schema shape as find-bugs (incremental sha tracking) — file/lock
+ * machinery shared via createScanStateModule. Kept as a sibling state file
+ * (not merged with find-bugs) so a smell scan and a bug scan can run
+ * concurrently without contending on the same lock.
+ */
+import { createScanStateModule, } from '../find-shared/scan-state.js';
+const m = createScanStateModule({
+    dirName: 'find-smells-state',
+});
+export const loadFindSmellsState = m.load;
+export const saveFindSmellsState = m.save;
+export const updateFindSmellsState = m.update;
+export const acquireFindSmellsLock = m.acquireLock;

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

@@ -0,0 +1,51 @@
+/**
+ * Types for the find-smells phase.
+ *
+ * A "smell" here is anything the codebase would benefit from changing but that
+ * is **not** a real bug (find-bugs handles those) and **not** a missing feature
+ * (find-features handles those). Refactor candidates, dead code, performance
+ * cliffs, type-safety gaps, and over-complex modules all live here.
+ */
+export type SmellSeverity = 'high' | 'medium' | 'low';
+/**
+ * Authoritative list of allowed categories. Kept as a `const` array so the
+ * type and the runtime whitelist can never drift apart — `SmellCategory` is
+ * derived from it, and `isSmellCategory` checks against it.
+ */
+export declare const SMELL_CATEGORIES: readonly ["refactor", "performance", "duplication", "complexity", "dead_code", "type_safety", "readability", "architecture", "other"];
+export type SmellCategory = (typeof SMELL_CATEGORIES)[number];
+export declare function isSmellCategory(value: unknown): value is SmellCategory;
+export interface SmellFinding {
+    title: string;
+    description: string;
+    file: string;
+    line?: number;
+    severity: SmellSeverity;
+    category: SmellCategory;
+    /** Stable signature for log/audit; not used for storage dedup. */
+    dedup_signature?: string;
+}
+/**
+ * A finding the agent saw but is handing off to a sibling phase rather than
+ * filing as a smell. Surfaced in the run log so the user knows the work
+ * wasn't silently lost — they can run `edsger find-bugs` / `find-features`
+ * to pick it up.
+ */
+export interface DeferredFinding {
+    title: string;
+    /** One-line reason the agent thinks the sibling phase owns this. */
+    reason: string;
+    file?: string;
+    line?: number;
+}
+export declare function isDeferredFinding(value: unknown): value is DeferredFinding;
+export interface ScanResult {
+    summary: string;
+    scanned_commit_sha?: string;
+    smells: SmellFinding[];
+    /** Findings the agent thinks belong in `edsger find-bugs`. */
+    deferred_to_bugs?: DeferredFinding[];
+    /** Findings the agent thinks belong in `edsger find-features`. */
+    deferred_to_features?: DeferredFinding[];
+}
+export declare function isScanResult(value: unknown): value is ScanResult;

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

@@ -0,0 +1,64 @@
+/**
+ * Types for the find-smells phase.
+ *
+ * A "smell" here is anything the codebase would benefit from changing but that
+ * is **not** a real bug (find-bugs handles those) and **not** a missing feature
+ * (find-features handles those). Refactor candidates, dead code, performance
+ * cliffs, type-safety gaps, and over-complex modules all live here.
+ */
+/**
+ * Authoritative list of allowed categories. Kept as a `const` array so the
+ * type and the runtime whitelist can never drift apart — `SmellCategory` is
+ * derived from it, and `isSmellCategory` checks against it.
+ */
+export const SMELL_CATEGORIES = [
+    'refactor',
+    'performance',
+    'duplication',
+    'complexity',
+    'dead_code',
+    'type_safety',
+    'readability',
+    'architecture',
+    'other',
+];
+export function isSmellCategory(value) {
+    return (typeof value === 'string' &&
+        SMELL_CATEGORIES.includes(value));
+}
+export function isDeferredFinding(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const v = value;
+    return typeof v.title === 'string' && typeof v.reason === 'string';
+}
+export function isScanResult(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const v = value;
+    if (typeof v.summary !== 'string' || !Array.isArray(v.smells)) {
+        return false;
+    }
+    const smellsOk = v.smells.every((s) => s &&
+        typeof s === 'object' &&
+        typeof s.title === 'string' &&
+        typeof s.description === 'string' &&
+        typeof s.file === 'string');
+    if (!smellsOk) {
+        return false;
+    }
+    // Deferred arrays are optional but, if present, must be well-formed —
+    // otherwise we'd silently drop hand-offs the agent intended us to log.
+    for (const key of ['deferred_to_bugs', 'deferred_to_features']) {
+        const arr = v[key];
+        if (arr === undefined) {
+            continue;
+        }
+        if (!Array.isArray(arr) || !arr.every(isDeferredFinding)) {
+            return false;
+        }
+    }
+    return true;
+}