iterate-plugin 3.5.2 → 3.5.4

package/dist/tools/defense-store.js

@@ -8,6 +8,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { iterateDir } from "../paths.js";
 import { writeJsonAtomic } from "../atomic-fs.js";
+import { hashString } from "./fix.js";
 const DEFENSE_EVENTS_FILE = 'defense-events.json';
 /** Valid defense event types (must stay in sync with DefenseEventType). */
 const VALID_EVENT_TYPES = new Set([
@@ -39,11 +40,45 @@ function emptyStream() {
         },
     };
 }
+/** Valid severity values (kept in sync with DefenseEvent). */
+const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
+/**
+ * Normalize one persisted event. Hand-edited files can carry events missing
+ * `timestamp`/`round`/`description`/`defense`/`outcome`/`severity` — readers
+ * (list sort by timestamp, render label selection) must never crash or emit
+ * NaN for those. Returns null when the entry is not an object or has no usable
+ * `type`; otherwise fills every required field with a safe default. An event
+ * missing its `id` gets a DETERMINISTIC id derived from its content and
+ * position (never a random one) so a read→write cycle cannot silently churn
+ * ids on every mutation.
+ */
+function normalizeEvent(raw, index) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const e = raw;
+    if (typeof e.type !== 'string' || !VALID_EVENT_TYPES.has(e.type))
+        return null;
+    const derivedId = `def-${hashString(`${index}|${String(e.timestamp ?? '')}|${e.type}|${String(e.description ?? '')}|${String(e.defense ?? '')}`)}`;
+    return {
+        id: typeof e.id === 'string' && e.id ? e.id : derivedId,
+        timestamp: typeof e.timestamp === 'string' && e.timestamp ? e.timestamp : new Date().toISOString(),
+        round: typeof e.round === 'number' && Number.isFinite(e.round) ? Math.floor(e.round) : 0,
+        type: e.type,
+        description: typeof e.description === 'string' ? e.description : '',
+        defense: typeof e.defense === 'string' ? e.defense : '',
+        outcome: typeof e.outcome === 'string' ? e.outcome : '',
+        ...(typeof e.file === 'string' && e.file.length > 0 ? { file: e.file } : {}),
+        ...(typeof e.line === 'number' && Number.isFinite(e.line) && e.line >= 0 ? { line: e.line } : {}),
+        severity: VALID_SEVERITIES.has(String(e.severity)) ? e.severity : 'low',
+    };
+}
 /**
  * Read the defense events stream from disk.
  * Normalizes the persisted stream so a hand-edited / partial file can never
  * produce NaN counts: `counts` is recomputed from the events when missing or
- * malformed, and every type key is guaranteed present.
+ * malformed, every type key is guaranteed present, and every surviving event is
+ * shape-normalized so consumers (timestamp sort, render label selection) cannot
+ * throw on missing fields.
  */
 export function readDefenseEvents(projectRoot) {
     const filePath = path.join(projectRoot, '.iterate', DEFENSE_EVENTS_FILE);
@@ -51,7 +86,9 @@ export function readDefenseEvents(projectRoot) {
         const content = fs.readFileSync(filePath, 'utf-8');
         const parsed = JSON.parse(content);
         if (parsed && Array.isArray(parsed.events)) {
-            const events = parsed.events.filter((e) => !!e && typeof e === 'object' && typeof e.type === 'string');
+            const events = parsed.events
+                .map((raw, i) => normalizeEvent(raw, i))
+                .filter((e) => e !== null);
             const counts = computeCounts(events);
             return {
                 events,
@@ -87,13 +124,34 @@ export function writeDefenseEvents(projectRoot, stream) {
     }
     return { ok: true };
 }
+/**
+ * Clear the persisted defense-event stream (`.iterate/defense-events.json`).
+ * Mirrors `clearQualityGate` in quality-store.ts: a stale event stream from a
+ * previous iteration must be resettable before a fresh run. Returns whether a
+ * file existed and was removed, or a structured error when removal fails.
+ */
+export function clearDefenseEvents(projectRoot) {
+    const filePath = path.join(iterateDir(projectRoot), DEFENSE_EVENTS_FILE);
+    const existed = fs.existsSync(filePath);
+    if (!existed)
+        return { ok: true, existed: false };
+    try {
+        fs.rmSync(filePath, { force: true });
+    }
+    catch (err) {
+        return { ok: false, error: `unable to remove ${filePath}: ${String(err)}` };
+    }
+    return { ok: true, existed: true };
+}
 /** Add a defense event to the stream. */
 export function addDefenseEvent(stream, event) {
-    const id = `def-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    // Spread the caller-shaped event FIRST so the store-generated `id` and
+    // `timestamp` always win — a caller-supplied id/timestamp must never
+    // override the stream's own identity fields.
     const newEvent = {
-        id,
-        timestamp: new Date().toISOString(),
         ...event,
+        id: `def-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        timestamp: new Date().toISOString(),
     };
     // Always recompute from the events array instead of mutating a possibly
     // stale/malformed persisted `counts` object — guarantees the stream counts

package/dist/tools/experience-bank.js

@@ -67,9 +67,12 @@ function normalizeExperienceInput(raw) {
 export function registerExperienceBankTool(ctx) {
     ctx.tools.register(defineTool({
         name: 'iterate_experience',
-        // List/search/get never write; only `add` upserts the bank → read shapes
-        // join a parallel dispatch group.
-        isConcurrencySafe: (args) => args.operation !== 'add',
+        // List/search/get never write; `add` upserts the bank and `remove`
+        // rewrites it → only the read shapes may join a parallel dispatch group.
+        isConcurrencySafe: (args) => {
+            const op = args.operation;
+            return op !== 'add' && op !== 'remove';
+        },
         description: 'Query or extend the experience bank: browse/search historical fixes and patterns, ' +
             'or record a new verified fix (operation:"add"). ' +
             'List/search/get return matching entries with hit counts, verified fixes, and related context. ' +
@@ -144,8 +147,8 @@ export function registerExperienceBankTool(ctx) {
                                 `Dimension: ${entry.dimension}`,
                                 `Description: ${entry.description}`,
                                 `Fix: ${entry.verifiedFix}`,
-                                `Files: ${entry.files.join(', ')}`,
-                                `Tags: ${entry.tags.join(', ')}`,
+                                `Files: ${Array.isArray(entry.files) ? entry.files.join(', ') : ''}`,
+                                `Tags: ${Array.isArray(entry.tags) ? entry.tags.join(', ') : ''}`,
                             ].join('\n') }];
                 }
                 if (value.operation === 'remove') {
@@ -158,9 +161,9 @@ export function registerExperienceBankTool(ctx) {
                                 `Pattern: ${entry.pattern}`,
                                 `Description: ${entry.description}`,
                                 `Fix: ${entry.verifiedFix}`,
-                                `Files: ${entry.files.join(', ')}`,
+                                `Files: ${Array.isArray(entry.files) ? entry.files.join(', ') : ''}`,
                                 `Hits: ${entry.hitCount}`,
-                                `Tags: ${entry.tags.join(', ')}`,
+                                `Tags: ${Array.isArray(entry.tags) ? entry.tags.join(', ') : ''}`,
                             ].join('\n') }];
                 }
                 const entries = value.entries ?? [];
@@ -252,7 +255,7 @@ export function registerExperienceBankTool(ctx) {
                     operation: 'get',
                     count: 1,
                     entry: entry,
-                    totalHits: bank.totalHits,
+                    totalHits: bank.totalHits ?? 0,
                 };
             }
             if (operation === 'search' && typeof args.query === 'string') {
@@ -266,7 +269,7 @@ export function registerExperienceBankTool(ctx) {
                     operation: 'search',
                     count: entries.length,
                     entries: entries,
-                    totalHits: bank.totalHits,
+                    totalHits: bank.totalHits ?? 0,
                 };
             }
             // Default: list with optional filters
@@ -275,7 +278,7 @@ export function registerExperienceBankTool(ctx) {
                 entries = entries.filter((e) => e.dimension === args.dimension);
             }
             if (Array.isArray(args.tags) && args.tags.length > 0) {
-                entries = entries.filter((e) => args.tags.every((t) => e.tags.includes(t)));
+                entries = entries.filter((e) => args.tags.every((t) => Array.isArray(e.tags) && e.tags.includes(t)));
             }
             return {
                 ok: true,
@@ -283,7 +286,7 @@ export function registerExperienceBankTool(ctx) {
                 operation: 'list',
                 count: Math.min(entries.length, limit),
                 entries: entries.slice(0, limit),
-                totalHits: bank.totalHits,
+                totalHits: bank.totalHits ?? 0,
             };
         },
     }));

package/dist/tools/experience-store.js

@@ -8,6 +8,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { iterateDir } from "../paths.js";
 import { writeJsonAtomic } from "../atomic-fs.js";
+import { hashString } from "./fix.js";
 const EXPERIENCE_FILE = 'experience.json';
 /** Default empty experience bank. */
 function emptyBank() {
@@ -17,6 +18,49 @@ function emptyBank() {
         totalHits: 0,
     };
 }
+/** Valid severity values (kept in sync with ExperienceEntry). */
+const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
+/** String array guard for fields that must be arrays (`files`, `tags`). */
+function stringArray(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => typeof x === 'string');
+}
+/**
+ * Normalize one persisted experience entry. A hand-edited bank entry can be
+ * missing `files`/`tags` arrays (or `hitCount`) — consumers rendering/searching
+ * entries (`render` `.join(', ')`, `searchExperienceEntries` spread) must never
+ * throw or emit NaN. Returns null for non-object entries; every required field
+ * gets a safe default.
+ */
+function normalizeEntry(raw, index) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const e = raw;
+    const pattern = typeof e.pattern === 'string' ? e.pattern : '';
+    const dimension = typeof e.dimension === 'string' ? e.dimension : '';
+    // Deterministic id (content + position based) so a read→write cycle never
+    // churns random ids on entries that were hand-edited without one.
+    const derivedId = `exp-${hashString(`${index}|${pattern}|${dimension}`)}`;
+    const id = typeof e.id === 'string' && e.id ? e.id : derivedId;
+    if (!pattern && !dimension)
+        return null;
+    const hitCount = typeof e.hitCount === 'number' && Number.isFinite(e.hitCount) ? e.hitCount : 0;
+    return {
+        id,
+        timestamp: typeof e.timestamp === 'string' ? e.timestamp : new Date().toISOString(),
+        dimension,
+        pattern,
+        description: typeof e.description === 'string' ? e.description : '',
+        verifiedFix: typeof e.verifiedFix === 'string' ? e.verifiedFix : '',
+        findingSummary: typeof e.findingSummary === 'string' ? e.findingSummary : '',
+        files: stringArray(e.files),
+        hitCount,
+        ...(typeof e.lastHitAt === 'string' ? { lastHitAt: e.lastHitAt } : {}),
+        tags: stringArray(e.tags),
+        severity: VALID_SEVERITIES.has(String(e.severity)) ? e.severity : 'low',
+    };
+}
 /** Read the experience bank from disk. Returns empty bank if not found. */
 export function readExperienceBank(projectRoot) {
     const filePath = path.join(projectRoot, '.iterate', EXPERIENCE_FILE);
@@ -24,7 +68,14 @@ export function readExperienceBank(projectRoot) {
         const content = fs.readFileSync(filePath, 'utf-8');
         const parsed = JSON.parse(content);
         if (parsed && Array.isArray(parsed.entries)) {
-            return parsed;
+            const entries = parsed.entries
+                .map((raw, i) => normalizeEntry(raw, i))
+                .filter((e) => e !== null);
+            return {
+                entries,
+                lastUpdated: typeof parsed.lastUpdated === 'string' ? parsed.lastUpdated : emptyBank().lastUpdated,
+                totalHits: typeof parsed.totalHits === 'number' && Number.isFinite(parsed.totalHits) ? parsed.totalHits : 0,
+            };
         }
     }
     catch {
@@ -58,17 +109,23 @@ export function writeExperienceBank(projectRoot, bank) {
 export function searchExperienceEntries(entries, query, opts = {}) {
     const lowerQuery = query.toLowerCase();
     return entries.filter((entry) => {
+        if (!entry || typeof entry !== 'object')
+            return false;
+        const rawEntry = entry;
+        const tags = stringArray(rawEntry.tags);
         // 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))) {
+            if (!opts.tags.every((t) => tags.includes(t))) {
                 return false;
             }
         }
-        // Text search across multiple fields
+        // Text search across multiple fields. Guards against a hand-edited bank entry
+        // whose `files`/`tags` are missing or non-array (the spread below would
+        // otherwise throw a TypeError on a non-iterable).
         if (query) {
             const searchableText = [
                 entry.pattern,
@@ -76,8 +133,8 @@ export function searchExperienceEntries(entries, query, opts = {}) {
                 entry.verifiedFix,
                 entry.findingSummary,
                 entry.dimension,
-                ...entry.files,
-                ...entry.tags,
+                ...stringArray(entry.files),
+                ...stringArray(entry.tags),
             ].join(' ').toLowerCase();
             if (!searchableText.includes(lowerQuery)) {
                 return false;
@@ -89,8 +146,11 @@ export function searchExperienceEntries(entries, query, opts = {}) {
 /**
  * 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:
+ * An entry with an `id` that already exists is treated as an UPDATE + HIT:
+ * the caller-supplied fields replace the stored ones and the hitCount is
+ * incremented (lastHitAt refreshed) — this fulfills the documented
+ * "update a specific entry via add" contract. 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.
@@ -104,11 +164,14 @@ export function upsertExperience(bank, entry) {
         ? 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,
-        };
+        // Explicit-id updates REPLACE the editable fields (fulfilling the
+        // documented "update a specific entry via add" contract); a pattern+
+        // dimension HIT only bumps the hit metadata so a repeat encounter never
+        // overwrites the curated entry.
+        const byId = typeof entry.id === 'string' && entry.id.length > 0;
+        const updated = byId
+            ? { ...existing, ...entry, id: existing.id, hitCount: (existing.hitCount ?? 0) + 1, lastHitAt: lastUpdated }
+            : { ...existing, hitCount: (existing.hitCount ?? 0) + 1, lastHitAt: lastUpdated };
         return {
             bank: {
                 ...bank,
@@ -120,14 +183,16 @@ export function upsertExperience(bank, entry) {
             entryId: existing.id,
         };
     }
-    // Add new entry
+    // Add new entry. Spread the caller input FIRST so the store-generated
+    // `id`/`timestamp`/`hitCount`/`lastHitAt` always win — a hostile or
+    // malformed input can never forge its own identity or hit count.
     const id = entry.id || `exp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     const newEntry = {
+        ...entry,
         id,
         timestamp: lastUpdated,
         hitCount: 1,
         lastHitAt: lastUpdated,
-        ...entry,
     };
     return {
         bank: {

package/dist/tools/fix.js

@@ -120,9 +120,22 @@ export function readRegistry(projectRoot) {
         const parsed = JSON.parse(readFileSync(file, 'utf-8'));
         if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.rounds))
             return emptyRegistry();
-        // Defensive: a hand-edited or partially-written registry may contain a
-        // round without a `records` array — normalize instead of crashing readers.
-        parsed.rounds = parsed.rounds.filter((r) => r && typeof r === 'object' && Array.isArray(r.records));
+        // Defensive normalization: a hand-edited or partially-written registry may
+        // contain a round without a `records` array, or records that are missing
+        // their id / finding object — all of which would make readers
+        // (findFixRecord / recordsForFile / iterate_diff) throw or sum NaN.
+        parsed.rounds = parsed.rounds
+            .filter((r) => r && typeof r === 'object' && Array.isArray(r.records))
+            .map((r) => ({
+            ...r,
+            round: typeof r.round === 'number' && Number.isFinite(r.round) ? Math.floor(r.round) : 0,
+            records: r.records.filter((rec) => !!rec &&
+                typeof rec === 'object' &&
+                typeof rec.id === 'string' &&
+                !!rec.finding &&
+                typeof rec.finding === 'object'),
+        }))
+            .filter((r) => typeof r.round === 'number' && Number.isFinite(r.round));
         return parsed;
     }
     catch {
@@ -611,20 +624,27 @@ export function registerDiffTool(ctx) {
                 for (const r of round.records) {
                     if (!r.success)
                         continue;
-                    const existing = files.find((f) => f.file === r.finding.file);
+                    const file = typeof r.finding.file === 'string' ? r.finding.file : '';
+                    if (!file)
+                        continue;
+                    // Coerce defensively: a hand-edited registry record missing the
+                    // numeric fields must not produce NaN in the accumulated summary.
+                    const added = Number(r.linesAdded) || 0;
+                    const removed = Number(r.linesRemoved) || 0;
+                    const existing = files.find((f) => f.file === file);
                     if (existing) {
-                        existing.linesAdded += r.linesAdded;
-                        existing.linesRemoved += r.linesRemoved;
+                        existing.linesAdded += added;
+                        existing.linesRemoved += removed;
                         // Recompute the summary from the summed counts so a multi-fix
                         // file's text does not contradict its accumulated numbers.
                         existing.diffSummary = `+${existing.linesAdded}/-${existing.linesRemoved} lines`;
                     }
                     else {
                         files.push({
-                            file: r.finding.file,
-                            diffSummary: r.diffSummary,
-                            linesAdded: r.linesAdded,
-                            linesRemoved: r.linesRemoved,
+                            file,
+                            diffSummary: typeof r.diffSummary === 'string' ? r.diffSummary : `+${added}/-${removed} lines`,
+                            linesAdded: added,
+                            linesRemoved: removed,
                         });
                     }
                 }

package/dist/tools/history.js

@@ -46,8 +46,10 @@ export function filterDecisionEntries(entries, opts) {
 export function summarizeFixRegistry(registry) {
     const rounds = (registry.rounds ?? []).map((r) => ({
         round: r.round,
-        fixedCount: r.fixedCount,
-        failedCount: r.failedCount,
+        // Coerce defensively so a hand-edited registry round missing either count
+        // can never propagate NaN into the integer output fields.
+        fixedCount: Number(r.fixedCount) || 0,
+        failedCount: Number(r.failedCount) || 0,
     }));
     return {
         totalFixed: rounds.reduce((s, r) => s + r.fixedCount, 0),
@@ -74,7 +76,7 @@ export function registerHistoryTool(ctx) {
             type: {
                 type: 'string',
                 description: 'Optional entry-type filter: round_start, review_result, atomic_fix, architectural_fix, ' +
-                    'revert, validation, decision, report.',
+                    'revert, round_failed, validation, decision, report, resume.',
             },
             since: {
                 type: 'string',