iterate-plugin 2.12.2 → 3.2.1

package/dist/tools/experience-store.js

@@ -0,0 +1,132 @@
+/**
+ * src/tools/experience-store.ts — experience bank storage layer.
+ *
+ * Provides read/write access to the experience bank stored in
+ * .iterate/experience.json. Experiences are accumulated across sessions.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const EXPERIENCE_FILE = 'experience.json';
+/** Default empty experience bank. */
+function emptyBank() {
+    return {
+        entries: [],
+        lastUpdated: new Date().toISOString(),
+        totalHits: 0,
+    };
+}
+/** Read the experience bank from disk. Returns empty bank if not found. */
+export function readExperienceBank(projectRoot) {
+    const filePath = path.join(projectRoot, '.iterate', EXPERIENCE_FILE);
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        if (parsed && Array.isArray(parsed.entries)) {
+            return parsed;
+        }
+    }
+    catch {
+        // File not found or invalid JSON
+    }
+    return emptyBank();
+}
+/** Write the experience bank to disk. */
+export function writeExperienceBank(projectRoot, bank) {
+    const dirPath = path.join(projectRoot, '.iterate');
+    const filePath = path.join(dirPath, EXPERIENCE_FILE);
+    try {
+        if (!fs.existsSync(dirPath)) {
+            fs.mkdirSync(dirPath, { recursive: true });
+        }
+        fs.writeFileSync(filePath, JSON.stringify(bank, null, 2), 'utf-8');
+    }
+    catch {
+        // Silently fail - experience bank is not critical
+    }
+}
+/** Search experience entries by query string. */
+export function searchExperienceEntries(entries, query, opts = {}) {
+    const lowerQuery = query.toLowerCase();
+    return entries.filter((entry) => {
+        // Dimension filter
+        if (opts.dimension && entry.dimension !== opts.dimension) {
+            return false;
+        }
+        // Tags filter (AND logic)
+        if (opts.tags && opts.tags.length > 0) {
+            if (!opts.tags.every((t) => entry.tags.includes(t))) {
+                return false;
+            }
+        }
+        // Text search across multiple fields
+        if (query) {
+            const searchableText = [
+                entry.pattern,
+                entry.description,
+                entry.verifiedFix,
+                entry.findingSummary,
+                entry.dimension,
+                ...entry.files,
+                ...entry.tags,
+            ].join(' ').toLowerCase();
+            if (!searchableText.includes(lowerQuery)) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+/**
+ * Add or update an experience entry.
+ *
+ * An entry with an `id` that already exists, OR a new entry whose
+ * `pattern`+`dimension` pair matches an existing entry, is treated as a HIT:
+ * the matching entry's hitCount is incremented (lastHitAt refreshed) so
+ * repeated encounters of the same pattern do not create duplicates. Otherwise
+ * a fresh entry is appended with hitCount 1. Never mutates the input bank.
+ *
+ * Returns the resulting bank plus whether a NEW entry was created and the id
+ * of the affected entry.
+ */
+export function upsertExperience(bank, entry) {
+    const lastUpdated = new Date().toISOString();
+    const existing = entry.id
+        ? bank.entries.find((e) => e.id === entry.id)
+        : bank.entries.find((e) => e.pattern === entry.pattern && e.dimension === entry.dimension);
+    if (existing) {
+        const updated = {
+            ...existing,
+            hitCount: (existing.hitCount ?? 0) + 1,
+            lastHitAt: lastUpdated,
+        };
+        return {
+            bank: {
+                ...bank,
+                entries: bank.entries.map((e) => (e.id === existing.id ? updated : e)),
+                lastUpdated,
+                totalHits: (bank.totalHits ?? 0) + 1,
+            },
+            added: false,
+            entryId: existing.id,
+        };
+    }
+    // Add new entry
+    const id = entry.id || `exp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const newEntry = {
+        id,
+        timestamp: lastUpdated,
+        hitCount: 1,
+        lastHitAt: lastUpdated,
+        ...entry,
+    };
+    return {
+        bank: {
+            ...bank,
+            entries: [...bank.entries, newEntry],
+            lastUpdated,
+            totalHits: (bank.totalHits ?? 0) + 1,
+        },
+        added: true,
+        entryId: id,
+    };
+}

package/dist/tools/quality-gate.js

@@ -0,0 +1,180 @@
+/**
+ * src/tools/quality-gate.ts — quality gate query & write tool.
+ *
+ *   iterate_quality_gate — query the persisted quality certificate, or compute
+ *                          and persist a new one from review/validation data.
+ *
+ * Provides a machine-readable quality certificate for the current iteration.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { resolveProjectRootForExec } from "../config-loader.js";
+import { readQualityGate, writeQualityGate, computeQualityGate } from "./quality-store.js";
+/** Validate a single finding object; returns true when well-formed. */
+function isValidFinding(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    const f = raw;
+    return (typeof f.dimension === 'string' &&
+        typeof f.severity === 'string' &&
+        typeof f.file === 'string' &&
+        (f.line === undefined || typeof f.line === 'number'));
+}
+/** Validate a single validation result; returns true when well-formed. */
+function isValidValidationResult(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    const r = raw;
+    return typeof r.command === 'string' && typeof r.exitCode === 'number' && Number.isFinite(r.exitCode);
+}
+/** Sanitize a caller-supplied per-dimension number map. */
+function sanitizeNumberMap(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+            out[key] = value;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/** Sanitize a caller-supplied per-dimension round series map. */
+function sanitizeRoundSeries(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (Array.isArray(value)) {
+            const series = value
+                .filter((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0);
+            if (series.length > 0)
+                out[key] = series;
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Register the `iterate_quality_gate` tool.
+ * Reads the persisted quality certificate, or computes + persists a new one.
+ */
+export function registerQualityGateTool(ctx) {
+    ctx.tools.register(defineTool({
+        name: 'iterate_quality_gate',
+        description: 'Query or write the quality gate status: dimension convergence rates, verification pass rates, ' +
+            'and overall PASS/FAIL status. ' +
+            'Operation "read" (default) returns the persisted machine-readable quality certificate. ' +
+            'Operation "compute" computes a fresh snapshot from this round\'s findings/validation results, ' +
+            'persists it to .iterate/quality-gate.json, and returns it.',
+        parameters: {
+            operation: {
+                type: 'string',
+                description: 'Operation: read (load persisted certificate) or compute (recompute + persist). Default: read.',
+                enum: ['read', 'compute'],
+            },
+            dimensions: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Dimensions to gate (required for compute).',
+            },
+            findings: {
+                type: 'json',
+                description: 'Findings array (required for compute). Each item: { dimension, severity (critical|high|medium|low), file, line? }.',
+            },
+            validationResults: {
+                type: 'json',
+                description: 'Validation results array (optional for compute). Each item: { command, exitCode }.',
+            },
+            findingsByRound: {
+                type: 'json',
+                description: 'Optional per-dimension NEW-finding counts across rounds (latest last) — used to compute real convergence rates. ' +
+                    'Example: { "correctness": [5, 2, 0] }.',
+            },
+            fixedByDimension: {
+                type: 'json',
+                description: 'Optional per-dimension count of fixed findings, e.g. { "correctness": 3 }.',
+            },
+            path: {
+                type: 'string',
+                description: 'Project root directory (default: current working directory).',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    ok: { type: 'boolean', required: true },
+                    kind: { type: 'string' },
+                    operation: { type: 'string' },
+                    snapshot: { type: 'json' },
+                    error: { type: 'string' },
+                },
+            },
+            render: (_args, value) => {
+                if (!value.ok)
+                    return [{ type: 'text', text: `quality gate query failed: ${value.error}` }];
+                const operation = typeof value.operation === 'string' ? value.operation : 'read';
+                const snapshot = value.snapshot;
+                if (!snapshot)
+                    return [{ type: 'text', text: 'No quality gate data available.' }];
+                const statusEmoji = snapshot.overallStatus === 'pass' ? '✓' : snapshot.overallStatus === 'fail' ? '✗' : '○';
+                const lines = [
+                    `${statusEmoji} Quality Gate: ${snapshot.overallStatus.toUpperCase()} (score: ${snapshot.overallScore})`,
+                    `Verification: ${snapshot.passedChecks}/${snapshot.totalChecks} passed (${snapshot.verificationPassRate}%)`,
+                    `Findings: ${snapshot.totalFindings} total (${snapshot.criticalCount} critical, ${snapshot.highCount} high, ${snapshot.mediumCount} medium, ${snapshot.lowCount} low)`,
+                    '',
+                    'Dimension Breakdown:',
+                    ...snapshot.dimensions.map((d) => {
+                        const dimStatus = d.status === 'pass' ? '✓' : d.status === 'warn' ? '!' : '✗';
+                        return `  ${dimStatus} ${d.dimension}: score=${d.score}, convergence=${d.convergenceRate}%, findings=${d.findingsCount}, fixed=${d.fixedCount}`;
+                    }),
+                ];
+                if (snapshot.failReason) {
+                    lines.push('', `Fail Reason: ${snapshot.failReason}`);
+                }
+                if (operation === 'compute') {
+                    lines.push('', 'Quality gate snapshot computed and persisted.');
+                }
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
+            if (!resolved.ok)
+                return { ok: false, kind: 'quality_gate', error: resolved.reason };
+            const projectRoot = resolved.root;
+            const operation = typeof args.operation === 'string' ? args.operation : 'read';
+            if (operation === 'compute') {
+                const dimensions = Array.isArray(args.dimensions)
+                    ? args.dimensions.filter((d) => typeof d === 'string' && d.length > 0)
+                    : [];
+                const findings = Array.isArray(args.findings) ? args.findings.filter(isValidFinding) : [];
+                const validationResults = Array.isArray(args.validationResults)
+                    ? args.validationResults.filter(isValidValidationResult)
+                    : undefined;
+                const findingsByRound = sanitizeRoundSeries(args.findingsByRound);
+                const fixedByDimension = sanitizeNumberMap(args.fixedByDimension);
+                const snapshot = computeQualityGate({
+                    dimensions,
+                    findings,
+                    validationResults,
+                    findingsByRound,
+                    fixedByDimension,
+                });
+                writeQualityGate(projectRoot, snapshot);
+                return {
+                    ok: true,
+                    kind: 'quality_gate',
+                    operation: 'compute',
+                    snapshot: snapshot,
+                };
+            }
+            const snapshot = readQualityGate(projectRoot);
+            return {
+                ok: true,
+                kind: 'quality_gate',
+                operation: 'read',
+                snapshot: snapshot,
+            };
+        },
+    }));
+}

package/dist/tools/quality-store.js

@@ -0,0 +1,174 @@
+/**
+ * src/tools/quality-store.ts — quality gate storage layer.
+ *
+ * Provides read/write access to quality gate data stored in
+ * .iterate/quality-gate.json. Quality gate snapshots are generated
+ * from review results and validation outcomes.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const QUALITY_GATE_FILE = 'quality-gate.json';
+/** Default empty quality gate snapshot. */
+function emptySnapshot() {
+    return {
+        timestamp: new Date().toISOString(),
+        overallStatus: 'pending',
+        overallScore: 0,
+        dimensions: [],
+        verificationPassRate: 0,
+        totalChecks: 0,
+        passedChecks: 0,
+        failedChecks: 0,
+        totalFindings: 0,
+        criticalCount: 0,
+        highCount: 0,
+        mediumCount: 0,
+        lowCount: 0,
+    };
+}
+/** Read the quality gate snapshot from disk. */
+export function readQualityGate(projectRoot) {
+    const filePath = path.join(projectRoot, '.iterate', QUALITY_GATE_FILE);
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        if (parsed && typeof parsed === 'object') {
+            return parsed;
+        }
+    }
+    catch {
+        // File not found or invalid JSON
+    }
+    return emptySnapshot();
+}
+/** Write the quality gate snapshot to disk. */
+export function writeQualityGate(projectRoot, snapshot) {
+    const dirPath = path.join(projectRoot, '.iterate');
+    const filePath = path.join(dirPath, QUALITY_GATE_FILE);
+    try {
+        if (!fs.existsSync(dirPath)) {
+            fs.mkdirSync(dirPath, { recursive: true });
+        }
+        fs.writeFileSync(filePath, JSON.stringify(snapshot, null, 2), 'utf-8');
+    }
+    catch {
+        // Silently fail - quality gate is not critical
+    }
+}
+/**
+ * Compute the convergence rate for a dimension.
+ *
+ * Convergence measures how much NEW-finding volume shrank across rounds:
+ * `(first - last) / first` from the dimension's per-round findings series,
+ * expressed as a 0-100 percentage, clamped. A series with no fresh findings
+ * (or a dimension never reporting a first-round reading) counts as fully
+ * converged (100). Returns 0 — no measurable improvement — when a reading
+ * exists but the series is empty or malformed.
+ */
+export function convergenceRateFor(series, currentCount) {
+    if (Array.isArray(series) && series.length > 0) {
+        const first = series.find((n) => typeof n === 'number' && Number.isFinite(n));
+        const last = [...series].reverse().find((n) => typeof n === 'number' && Number.isFinite(n));
+        if (first === undefined || last === undefined)
+            return currentCount === 0 ? 100 : 0;
+        if (first <= 0)
+            return currentCount === 0 ? 100 : 0;
+        const raw = ((first - Math.max(0, last)) / first) * 100;
+        return Math.max(0, Math.min(100, Math.round(raw)));
+    }
+    return currentCount === 0 ? 100 : 0;
+}
+/** Compute a quality gate snapshot from review data. */
+export function computeQualityGate(opts) {
+    const { dimensions, findings, validationResults, findingsByRound, fixedByDimension } = opts;
+    // Count findings by severity
+    const criticalCount = findings.filter((f) => f.severity === 'critical').length;
+    const highCount = findings.filter((f) => f.severity === 'high').length;
+    const mediumCount = findings.filter((f) => f.severity === 'medium').length;
+    const lowCount = findings.filter((f) => f.severity === 'low').length;
+    const totalFindings = findings.length;
+    // Compute dimension scores
+    const dimensionStats = {};
+    for (const dim of dimensions) {
+        dimensionStats[dim] = { count: 0, critical: 0, high: 0, medium: 0, low: 0 };
+    }
+    for (const finding of findings) {
+        const stats = dimensionStats[finding.dimension];
+        if (stats) {
+            stats.count++;
+            if (finding.severity === 'critical')
+                stats.critical++;
+            else if (finding.severity === 'high')
+                stats.high++;
+            else if (finding.severity === 'medium')
+                stats.medium++;
+            else
+                stats.low++;
+        }
+    }
+    // Compute dimension-level quality gates
+    const dimensionGates = dimensions.map((dim) => {
+        const stats = dimensionStats[dim] || { count: 0, critical: 0, high: 0, medium: 0, low: 0 };
+        // Score: 100 - (critical*30 + high*15 + medium*5 + low*1), capped at 0
+        const penalty = stats.critical * 30 + stats.high * 15 + stats.medium * 5 + stats.low * 1;
+        const score = Math.max(0, 100 - penalty);
+        const status = score >= 80 ? 'pass' : score >= 50 ? 'warn' : 'fail';
+        const series = findingsByRound?.[dim];
+        const convergenceRate = convergenceRateFor(Array.isArray(series) ? series : undefined, stats.count);
+        return {
+            dimension: dim,
+            convergenceRate,
+            findingsCount: stats.count,
+            fixedCount: fixedByDimension?.[dim] ?? 0,
+            score,
+            status,
+        };
+    });
+    // Compute verification pass rate
+    const totalChecks = validationResults?.length ?? 0;
+    const passedChecks = validationResults?.filter((r) => r.exitCode === 0).length ?? 0;
+    const failedChecks = totalChecks - passedChecks;
+    const verificationPassRate = totalChecks > 0 ? Math.round((passedChecks / totalChecks) * 100) : 0;
+    // Compute overall score (weighted average of dimension scores)
+    const overallScore = dimensionGates.length > 0
+        ? Math.round(dimensionGates.reduce((sum, d) => sum + d.score, 0) / dimensionGates.length)
+        : 0;
+    // Determine overall status
+    const hasCritical = criticalCount > 0;
+    const hasHighFail = dimensionGates.some((d) => d.status === 'fail');
+    const verificationFails = totalChecks > 0 && failedChecks > 0;
+    let overallStatus = 'pass';
+    let failReason;
+    if (hasCritical) {
+        overallStatus = 'fail';
+        failReason = `${criticalCount} critical findings present`;
+    }
+    else if (hasHighFail) {
+        overallStatus = 'fail';
+        failReason = 'One or more dimensions failed quality gate';
+    }
+    else if (verificationFails) {
+        overallStatus = 'fail';
+        failReason = `${failedChecks} validation checks failed`;
+    }
+    else if (overallScore < 70) {
+        overallStatus = 'fail';
+        failReason = `Overall score ${overallScore} below threshold (70)`;
+    }
+    return {
+        timestamp: new Date().toISOString(),
+        overallStatus,
+        overallScore,
+        dimensions: dimensionGates,
+        verificationPassRate,
+        totalChecks,
+        passedChecks,
+        failedChecks,
+        failReason,
+        totalFindings,
+        criticalCount,
+        highCount,
+        mediumCount,
+        lowCount,
+    };
+}