@minionry/minion 0.7.36

package/dist/server/services/websocket/quality-review-agent.js

@@ -0,0 +1,526 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, isAbsolute, join } from 'node:path';
+import { loadSkillPrompt } from '../plan/agent-loader.js';
+import { estimateCodebaseSize, estimateReviewMs } from './quality-eta.js';
+import { diskContentReader, stampFingerprints } from './quality-fingerprint.js';
+import { getQualityModels, indexDismissals, recomputeGrade, stampDismissals, stampIntroduced } from './quality-service.js';
+import { runTriagePass } from './quality-triage-agent.js';
+import { jsonCandidates, } from './quality-types.js';
+let reviewHost = null;
+export function setQualityReviewHost(host) {
+    reviewHost = host;
+}
+const DISMISSED_PROMPT_CAP = 100;
+export function buildCodeReviewPrompt(dirPath, cliFindings, dismissed) {
+    const cliFindingsList = cliFindings && cliFindings.length > 0
+        ? `\n## CLI Tool Findings (already detected)\n\nThe following issues were found by automated CLI tools (linters, formatters, complexity analyzers). Review these for context — they are already included in the final report. Focus your analysis on DEEPER issues these tools cannot detect.\n\n${cliFindings.slice(0, 50).map((f, i) => `${i + 1}. [${f.severity.toUpperCase()}] ${f.category} — ${f.file}${f.line ? `:${f.line}` : ''} — ${f.title}: ${f.description}`).join('\n')}\n${cliFindings.length > 50 ? `\n...and ${cliFindings.length - 50} more issues from CLI tools.\n` : ''}`
+        : '';
+    const dismissedList = dismissed && dismissed.length > 0
+        ? `\n## Dismissed by the user — do not report again\n\nThe user reviewed and dismissed the following findings from earlier reviews of this directory. Do NOT report them again, in any wording, and do not report a variant of the same issue at the same place.\n\n${dismissed.slice(0, DISMISSED_PROMPT_CAP).map((d, i) => `${i + 1}. ${d.file} — ${d.title} (dismissed by the user: ${d.reason})`).join('\n')}\n${dismissed.length > DISMISSED_PROMPT_CAP ? `\n...and ${dismissed.length - DISMISSED_PROMPT_CAP} more dismissed findings.\n` : ''}`
+        : '';
+    const cliFindingsSection = `${cliFindingsList}${dismissedList}`;
+    const fromSkill = loadSkillPrompt('code-review', { dirPath, cliFindingsSection });
+    if (fromSkill)
+        return fromSkill;
+    return `You are a senior staff engineer performing a rigorous code review.\n\nIMPORTANT: Your current working directory is "${dirPath}". Only review files within this directory.\n${cliFindingsSection}\nDiscover source files with Glob, read important files, analyze for architecture, SOLID, security, bugs, and performance issues. Each finding needs file, line, evidence. Output one JSON code block with score, grade, findings array, and summary.`;
+}
+const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
+const VALID_CATEGORIES = new Set(['architecture', 'oop', 'security', 'bugs', 'performance', 'logic', 'maintainability']);
+function normalizeFinding(f) {
+    if (typeof f.file !== 'string' || typeof f.title !== 'string')
+        return null;
+    return {
+        severity: VALID_SEVERITIES.has(f.severity) ? f.severity : 'medium',
+        category: VALID_CATEGORIES.has(f.category) ? f.category : 'maintainability',
+        file: f.file,
+        line: typeof f.line === 'number' ? f.line : null,
+        title: f.title,
+        description: typeof f.description === 'string' ? f.description : '',
+        suggestion: typeof f.suggestion === 'string' ? f.suggestion : undefined,
+        evidence: typeof f.evidence === 'string' ? f.evidence : undefined,
+    };
+}
+export function parseCodeReviewResponse(response) {
+    for (const candidate of jsonCandidates(response)) {
+        try {
+            const parsed = JSON.parse(candidate);
+            if (!Array.isArray(parsed.findings))
+                continue;
+            const rawFindings = parsed.findings;
+            const findings = rawFindings.map(normalizeFinding).filter((f) => f !== null);
+            const summary = typeof parsed.summary === 'string' ? parsed.summary : `Found ${findings.length} issue(s).`;
+            const score = typeof parsed.score === 'number' ? Math.max(0, Math.min(100, Math.round(parsed.score))) : null;
+            const grade = typeof parsed.grade === 'string' ? parsed.grade : null;
+            const scoreRationale = typeof parsed.scoreRationale === 'string' ? parsed.scoreRationale : null;
+            return { findings, summary, score, grade, scoreRationale };
+        }
+        catch {
+        }
+    }
+    throw new Error("The AI review's reply had no readable findings, so nothing from it was recorded. Open its Agent tab to see what it said, then retry.");
+}
+function resolveFilePath(dirPath, filePath) {
+    if (isAbsolute(filePath))
+        return filePath;
+    return join(dirPath, filePath);
+}
+function extractClaimedIdentifiers(description, title) {
+    const identifiers = [];
+    const combined = `${title} ${description}`;
+    const callPatterns = combined.matchAll(/\b([a-zA-Z_$][\w.$]*)\s*\(/g);
+    for (const m of callPatterns) {
+        const name = m[1];
+        if (!['If', 'When', 'While', 'For', 'This', 'That', 'The', 'Each', 'Uses', 'Has', 'Does', 'Returns', 'Takes', 'Calls'].includes(name)) {
+            identifiers.push(name);
+        }
+    }
+    const backtickPatterns = combined.matchAll(/`([^`]+)`/g);
+    for (const m of backtickPatterns) {
+        const inner = m[1].replace(/[()[\]{};,]/g, ' ').trim();
+        if (inner && inner.length < 60) {
+            identifiers.push(inner);
+        }
+    }
+    return identifiers;
+}
+export function validateFindings(findings, dirPath) {
+    const validated = [];
+    const rejected = [];
+    for (const finding of findings) {
+        const result = validateSingleFinding(finding, dirPath);
+        if (result.valid) {
+            validated.push({ ...finding, verified: undefined });
+        }
+        else {
+            rejected.push({ ...finding, verified: false, verificationNote: result.reason });
+        }
+    }
+    return {
+        validated,
+        rejected,
+        stats: { total: findings.length, passed: validated.length, failed: rejected.length },
+    };
+}
+function readFileContent(filePath) {
+    try {
+        return readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+const COMMON_KEYWORDS = /^(const|let|var|function|return|import|export|from|this|true|false|null|undefined|new|if|else|for|while|try|catch)$/;
+function checkLineInRange(content, line) {
+    if (line === null || line <= 0)
+        return null;
+    const lineCount = content.split('\n').length;
+    if (line > lineCount)
+        return `Line ${line} exceeds file length (${lineCount} lines)`;
+    return null;
+}
+function checkEvidenceTokens(content, evidence) {
+    if (!evidence)
+        return null;
+    const evidenceTokens = evidence
+        .replace(/['"`;{}[\]()]/g, ' ')
+        .split(/\s+/)
+        .filter(t => t.length > 3 && !COMMON_KEYWORDS.test(t));
+    if (evidenceTokens.length === 0)
+        return null;
+    const matchCount = evidenceTokens.filter(token => content.includes(token)).length;
+    if (matchCount === 0)
+        return `Evidence tokens not found in file: ${evidenceTokens.slice(0, 3).join(', ')}`;
+    return null;
+}
+function checkClaimedIdentifiers(content, finding) {
+    const claimedIds = extractClaimedIdentifiers(finding.description, finding.title);
+    if (claimedIds.length < 2)
+        return null;
+    const foundAny = claimedIds.some(id => {
+        if (id.includes('.'))
+            return content.includes(id);
+        return new RegExp(`\\b${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(content);
+    });
+    if (!foundAny)
+        return `Claimed identifiers not found in file: ${claimedIds.slice(0, 3).join(', ')}`;
+    return null;
+}
+function validateSingleFinding(finding, dirPath) {
+    const filePath = resolveFilePath(dirPath, finding.file);
+    if (!existsSync(filePath)) {
+        return { finding, valid: false, reason: `File does not exist: ${finding.file}` };
+    }
+    const content = readFileContent(filePath);
+    if (!content)
+        return { finding, valid: true };
+    const lineErr = checkLineInRange(content, finding.line);
+    if (lineErr)
+        return { finding, valid: false, reason: lineErr };
+    const evidenceErr = checkEvidenceTokens(content, finding.evidence);
+    if (evidenceErr)
+        return { finding, valid: false, reason: evidenceErr };
+    const idErr = checkClaimedIdentifiers(content, finding);
+    if (idErr)
+        return { finding, valid: false, reason: idErr };
+    return { finding, valid: true };
+}
+export function buildVerificationPrompt(dirPath, findings) {
+    const findingsJson = JSON.stringify(findings.map((f, i) => ({
+        id: i + 1,
+        severity: f.severity,
+        category: f.category,
+        file: f.file,
+        line: f.line,
+        title: f.title,
+        description: f.description,
+        evidence: f.evidence || '(none provided)',
+    })), null, 2);
+    const fromSkill = loadSkillPrompt('verify-review', { dirPath, findingsJson });
+    if (fromSkill)
+        return fromSkill;
+    return `You are an independent code review VERIFIER. Verify each finding below against actual code in "${dirPath}".\n\n## Findings to Verify\n\n${findingsJson}\n\nFor each finding: Read the cited file, check the claim, search for counter-evidence. Output one JSON code block with verifications array containing id, verdict (confirmed|rejected), confidence, and note.`;
+}
+export function parseVerificationResponse(response) {
+    for (const candidate of jsonCandidates(response)) {
+        try {
+            const parsed = JSON.parse(candidate);
+            if (!Array.isArray(parsed.verifications))
+                continue;
+            const raw = parsed.verifications;
+            return raw
+                .filter((v) => typeof v.id === 'number' && typeof v.verdict === 'string')
+                .map(v => ({
+                id: v.id,
+                verdict: v.verdict === 'rejected' ? 'rejected' : 'confirmed',
+                confidence: typeof v.confidence === 'number' ? v.confidence : 0.5,
+                note: typeof v.note === 'string' ? v.note : '',
+            }));
+        }
+        catch {
+        }
+    }
+    return [];
+}
+export function applyVerification(findings, verdicts) {
+    const verdictMap = new Map(verdicts.map(v => [v.id, v]));
+    const verified = [];
+    const rejected = [];
+    for (let i = 0; i < findings.length; i++) {
+        const verdict = verdictMap.get(i + 1);
+        if (!verdict) {
+            verified.push({ ...findings[i], verified: undefined });
+            continue;
+        }
+        if (verdict.verdict === 'confirmed' && verdict.confidence >= 0.6) {
+            verified.push({
+                ...findings[i],
+                verified: true,
+                verificationNote: verdict.note || undefined,
+            });
+        }
+        else {
+            rejected.push({
+                ...findings[i],
+                verified: false,
+                verificationNote: verdict.note || undefined,
+            });
+        }
+    }
+    return { verified, rejected };
+}
+const TOOL_START_MESSAGES = {
+    Glob: 'Discovering project files...',
+    Read: 'Reading source files...',
+    Grep: 'Searching codebase...',
+    Bash: 'Running analysis command...',
+};
+function getToolCompleteMessage(event) {
+    const input = event.completeInput;
+    if (!input)
+        return null;
+    if (event.toolName === 'Read' && input.file_path) {
+        return `Reviewed ${String(input.file_path).split('/').slice(-2).join('/')}`;
+    }
+    if (event.toolName === 'Grep' && input.pattern) {
+        return `Searched for "${String(input.pattern).slice(0, 40)}"`;
+    }
+    return null;
+}
+function createCodeReviewProgressTracker() {
+    const seenToolStarts = new Set();
+    return (event) => {
+        if (event.type === 'tool_start' && event.toolName) {
+            if (seenToolStarts.has(event.toolName))
+                return null;
+            seenToolStarts.add(event.toolName);
+            return TOOL_START_MESSAGES[event.toolName] ?? null;
+        }
+        if (event.type === 'tool_complete')
+            return getToolCompleteMessage(event);
+        return null;
+    };
+}
+function makeToolCallback(send, prefix) {
+    const getProgressMessage = createCodeReviewProgressTracker();
+    return (event) => {
+        const message = getProgressMessage(event);
+        if (message)
+            send(prefix ? `${prefix}${message}` : message);
+    };
+}
+function startHeartbeat(send, phase, intervalMs = 30_000) {
+    let elapsed = 0;
+    const timer = setInterval(() => {
+        elapsed += intervalMs;
+        const mins = Math.floor(elapsed / 60_000);
+        const secs = Math.floor((elapsed % 60_000) / 1000);
+        const timeStr = mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
+        send(`${phase} (${timeStr} elapsed, still working...)`);
+    }, intervalMs);
+    return () => clearInterval(timer);
+}
+function loadCliFindings(persistence, reportPath) {
+    try {
+        return persistence.loadReport(reportPath)?.findings;
+    }
+    catch {
+        return undefined;
+    }
+}
+function dismissedReviewFindings(suppressions, persistence, reportPath) {
+    if (suppressions.length === 0)
+        return [];
+    let scanFingerprints = new Set();
+    try {
+        scanFingerprints = new Set(persistence.loadReport(reportPath)?.fingerprints ?? []);
+    }
+    catch {
+    }
+    return suppressions.filter((s) => !scanFingerprints.has(s.fingerprint)).map(({ file, title, reason }) => ({ file, title, reason }));
+}
+async function runVerificationPass(dirPath, findings, ctx) {
+    const { send, signal, session } = ctx;
+    send(`Verifying ${findings.length} findings against actual code...`);
+    const stopHeartbeat = startHeartbeat(send, 'Verification');
+    ctx.toolProgress.current = makeToolCallback(send, 'Verifying: ');
+    try {
+        const verified = await session.prompt(buildVerificationPrompt(dirPath, findings));
+        if (verified.cancelled || signal.aborted)
+            return findings;
+        const verdicts = parseVerificationResponse(verified.text);
+        if (verdicts.length === 0)
+            return findings;
+        const applied = applyVerification(findings, verdicts);
+        if (applied.rejected.length > 0) {
+            send(`Verification rejected ${applied.rejected.length} inaccurate finding(s)`);
+        }
+        return applied.verified;
+    }
+    finally {
+        stopHeartbeat();
+    }
+}
+export function identifyReviewFindings(findings, dirPath) {
+    return stampFingerprints(findings.map((f) => ({ ...f })), { dirPath, contentOf: diskContentReader(dirPath) });
+}
+function persistReviewResults(reviewResult, reportPath, persistence, reviewDurationMs, reviewSessionId, dismissals) {
+    const existingReport = persistence.loadReport(reportPath);
+    const findings = reviewResult.findings.map((f) => ({ ...f, status: 'confirmed' }));
+    stampDismissals(findings, dismissals);
+    const findingsRecord = findings;
+    if (!existingReport) {
+        persistence.saveCodeReview(reportPath, findingsRecord, reviewResult.summary);
+        return null;
+    }
+    stampDismissals(existingReport.findings ?? [], dismissals);
+    const updatedResults = recomputeGrade({
+        ...existingReport,
+        codeReview: findings,
+        reviewDurationMs,
+        ...(reviewSessionId === undefined ? {} : { reviewSessionId }),
+    });
+    persistence.saveReport(reportPath, updatedResults);
+    persistence.updateHistoryEntry(updatedResults, reportPath);
+    persistence.saveCodeReview(reportPath, findingsRecord, reviewResult.summary, updatedResults.timestamp);
+    return updatedResults;
+}
+const REVIEWER_NAMES = {
+    'claude-code': 'Claude',
+    codex: 'Codex',
+    hermes: 'Hermes',
+};
+async function runInitialReview(dirPath, cliFindings, dismissed, ctx) {
+    const { send, session, models } = ctx;
+    const stopReviewHeartbeat = startHeartbeat(send, 'AI code review');
+    try {
+        send(`${REVIEWER_NAMES[models.engine] ?? 'The reviewer'} is analyzing your codebase...`);
+        const result = await session.prompt(buildCodeReviewPrompt(dirPath, cliFindings, dismissed));
+        if (result.cancelled)
+            return null;
+        try {
+            return parseCodeReviewResponse(result.text);
+        }
+        catch (error) {
+            if (result.notice)
+                throw new Error(`[[MINIONRY_ERROR:${result.notice.code}]] ${result.notice.text}`);
+            throw error;
+        }
+    }
+    finally {
+        stopReviewHeartbeat();
+    }
+}
+async function refineFindings(reviewResult, dirPath, ctx) {
+    const { send, signal } = ctx;
+    send(`Validating ${reviewResult.findings.length} findings against codebase...`);
+    const validation = validateFindings(reviewResult.findings, dirPath);
+    if (validation.stats.failed > 0) {
+        send(`Filtered ${validation.stats.failed} finding(s) with invalid references`);
+    }
+    let finalFindings = validation.validated;
+    if (finalFindings.length > 0 && !signal.aborted) {
+        try {
+            finalFindings = await runVerificationPass(dirPath, finalFindings, ctx);
+        }
+        catch {
+            send('Verification pass skipped (timeout or error)');
+        }
+    }
+    return finalFindings;
+}
+async function computeReviewEta(dirPath, persistence, reportPath) {
+    try {
+        const size = await estimateCodebaseSize(dirPath);
+        return estimateReviewMs(size, persistence.loadHistory(), reportPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function runTriageStep(reportPath, dirPath, persistence, ctx, dismissals) {
+    const { send, signal, models } = ctx;
+    const report = persistence.loadReport(reportPath);
+    if (!report || !Array.isArray(report.findings) || report.findings.length === 0)
+        return;
+    const findings = stampDismissals(report.findings, dismissals);
+    const candidates = findings.filter((f) => f.dismissal === undefined);
+    const hasUncertain = candidates.some((f) => f.status === 'uncertain');
+    if (!hasUncertain)
+        return;
+    const stopHeartbeat = startHeartbeat(send, 'Triage');
+    let triaged;
+    try {
+        triaged = await runTriagePass(dirPath, candidates, send, signal, models.triageModel, models.engine, models.effortLevel, models.fastMode);
+    }
+    catch {
+        send('Triage pass skipped (timeout or error)');
+        return;
+    }
+    finally {
+        stopHeartbeat();
+    }
+    if (signal.aborted || !triaged.ran)
+        return;
+    const verdictByCandidate = new Map();
+    for (let i = 0; i < candidates.length; i++)
+        verdictByCandidate.set(candidates[i], triaged.findings[i]);
+    const updated = recomputeGrade({ ...report, findings: findings.map((f) => verdictByCandidate.get(f) ?? f) });
+    try {
+        persistence.saveReport(reportPath, updated);
+    }
+    catch {
+    }
+}
+function reviewTabLabel(reportPath, dirPath, persistence) {
+    try {
+        const configured = persistence.loadConfig().find((dir) => dir.path === reportPath)?.label;
+        if (configured)
+            return configured;
+    }
+    catch {
+    }
+    return reportPath === '.' ? basename(dirPath) || '.' : reportPath;
+}
+function openReviewSession(options, models, toolProgress) {
+    if (!reviewHost) {
+        throw new Error('the quality review host is not installed — the review leg has no Agent tab to run in');
+    }
+    return reviewHost.open({
+        workingDir: options.workingDir,
+        reportPath: options.reportPath,
+        dirPath: options.dirPath,
+        tabName: `Quality review · ${reviewTabLabel(options.reportPath, options.dirPath, options.persistence)}`,
+        ...(options.initiator ? { initiator: options.initiator } : {}),
+        engine: models.engine,
+        model: models.reviewModel,
+        effortLevel: models.effortLevel,
+        fastMode: models.fastMode,
+        onToolUse: (event) => toolProgress.current(event),
+    });
+}
+export async function runCodeReviewPipeline(options) {
+    const { signal } = options;
+    if (signal.aborted)
+        return null;
+    const startedAt = Date.now();
+    const metaRef = { current: { startedAt } };
+    const send = (message) => {
+        options.onProgress({ message, etaMs: metaRef.current.etaMs, startedAt });
+    };
+    const models = options.models ?? getQualityModels();
+    const toolProgress = { current: makeToolCallback(send) };
+    const session = openReviewSession(options, models, toolProgress);
+    const runCtx = { models, send, signal, session, toolProgress };
+    options.onSession?.(session.sessionId);
+    const cancelSession = () => {
+        try {
+            session.cancel();
+        }
+        catch (error) {
+            console.error('[QualityReview] cancelling the review session failed:', error);
+        }
+    };
+    signal.addEventListener('abort', cancelSession, { once: true });
+    try {
+        return await runReviewPasses(options, runCtx, startedAt, metaRef);
+    }
+    finally {
+        signal.removeEventListener('abort', cancelSession);
+    }
+}
+async function runReviewPasses(options, runCtx, startedAt, metaRef) {
+    const { reportPath, dirPath, persistence, signal } = options;
+    const { send } = runCtx;
+    computeReviewEta(dirPath, persistence, reportPath)
+        .then((etaMs) => { if (etaMs !== undefined)
+        metaRef.current = { ...metaRef.current, etaMs }; })
+        .catch(() => { });
+    send('Starting AI code review...');
+    const suppressions = (options.suppressions ?? []).filter((s) => s.path === reportPath);
+    const dismissals = indexDismissals(reportPath, suppressions);
+    await runTriageStep(reportPath, dirPath, persistence, runCtx, dismissals);
+    if (signal.aborted)
+        return null;
+    const cliFindings = loadCliFindings(persistence, reportPath);
+    const dismissed = dismissedReviewFindings(suppressions, persistence, reportPath);
+    const reviewResult = await runInitialReview(dirPath, cliFindings, dismissed, runCtx);
+    if (!reviewResult || signal.aborted)
+        return null;
+    const refined = await refineFindings(reviewResult, dirPath, runCtx);
+    if (signal.aborted)
+        return null;
+    send('Generating review report...');
+    const finalFindings = identifyReviewFindings(refined, dirPath);
+    if (options.baseline)
+        stampIntroduced(finalFindings, options.baseline);
+    const reviewDurationMs = Date.now() - startedAt;
+    let results = null;
+    try {
+        results = persistReviewResults({ ...reviewResult, findings: finalFindings }, reportPath, persistence, reviewDurationMs, runCtx.session.sessionId, dismissals);
+    }
+    catch {
+    }
+    return { findings: finalFindings, summary: reviewResult.summary, results, reviewDurationMs };
+}