@wazir-dev/cli 1.3.0 → 1.4.0

package/tooling/src/learn/pipeline.js

@@ -0,0 +1,177 @@
+/**
+ * Learning Pipeline — Findings-to-Antipattern Promotion
+ *
+ * 4-stage pipeline: TALLY → CANDIDATE → PROMOTE → ACTIVE
+ *
+ * Stage 1 (TALLY): Automatic. Every finding is hashed, categorized, and
+ *   clustered by canonical pattern. Happens at finding insertion time.
+ *
+ * Stage 2 (CANDIDATE): Automatic. When a cluster reaches the promotion
+ *   threshold (3+ occurrences across 2+ runs), it becomes a candidate.
+ *
+ * Stage 3 (PROMOTE): Human gate. Candidates are proposed for review.
+ *   User accepts or rejects. Accepted candidates become active antipatterns.
+ *
+ * Stage 4 (ACTIVE): Automatic. Active antipatterns are loaded into
+ *   reviewer context for future runs. Hit-rate tracking enables demotion.
+ *
+ * Drift prevention (from research):
+ * - Max 30 active project-level antipatterns
+ * - 90-day TTL on candidates (auto-expire if not reviewed)
+ * - 5% hit-rate demotion threshold (antipatterns that never trigger get demoted)
+ * - Principle consolidation when count exceeds 25
+ */
+
+import crypto from 'node:crypto';
+import {
+  upsertFindingCluster,
+  getClustersReadyForPromotion,
+  promoteClusterToCandidate,
+  insertAntipatternCandidate,
+  getActiveLearningsCount,
+  expireStaleAntipatternCandidates,
+} from '../state/db.js';
+
+const MAX_ACTIVE_ANTIPATTERNS = 30;
+const PROMOTION_THRESHOLD_OCCURRENCES = 3;
+const PROMOTION_THRESHOLD_RUNS = 2;
+
+/**
+ * Normalize a finding description to a canonical form for clustering.
+ * Strips file paths, line numbers, variable names, and normalizes whitespace.
+ */
+export function canonicalizeFinding(description) {
+  return description
+    // Remove file paths
+    .replace(/[a-zA-Z0-9_\-./]+\.[a-zA-Z]{1,4}(:\d+)?/g, '<FILE>')
+    // Remove line numbers
+    .replace(/line \d+/gi, 'line <N>')
+    // Remove quoted identifiers
+    .replace(/['"`][\w.]+['"`]/g, '<ID>')
+    // Remove hex hashes
+    .replace(/[0-9a-f]{7,40}/gi, '<HASH>')
+    // Normalize whitespace
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+/**
+ * Hash a canonicalized finding for dedup and clustering.
+ */
+export function hashCanonical(canonicalized) {
+  return crypto.createHash('sha256').update(canonicalized).digest('hex').slice(0, 16);
+}
+
+/**
+ * Stage 1: TALLY — Process a finding and cluster it.
+ * Called after each finding is inserted into the findings table.
+ *
+ * @param {object} db - open state database
+ * @param {object} finding - { description, category, finding_hash, run_id }
+ * @returns {string} cluster ID
+ */
+export function tallyFinding(db, finding) {
+  const canonical = canonicalizeFinding(finding.description);
+  const canonicalHash = hashCanonical(canonical);
+
+  return upsertFindingCluster(db, {
+    canonical_hash: canonicalHash,
+    category: finding.category || '',
+    pattern_description: canonical,
+    finding_hash: finding.finding_hash,
+    run_id: finding.run_id,
+    evidence_runs: JSON.stringify([finding.run_id]),
+  });
+}
+
+/**
+ * Stage 2: CANDIDATE — Check clusters that meet the promotion threshold.
+ * Returns clusters ready for promotion.
+ *
+ * @param {object} db - open state database
+ * @returns {Array} clusters ready for promotion
+ */
+export function identifyCandidates(db) {
+  return getClustersReadyForPromotion(
+    db,
+    PROMOTION_THRESHOLD_OCCURRENCES,
+    PROMOTION_THRESHOLD_RUNS,
+  );
+}
+
+/**
+ * Stage 2→3: Promote eligible clusters to candidates and generate
+ * antipattern proposals.
+ *
+ * @param {object} db - open state database
+ * @param {Array} clusters - from identifyCandidates()
+ * @returns {Array} created candidate IDs
+ */
+export function promoteToCandidates(db, clusters) {
+  const activeCount = getActiveLearningsCount(db);
+  if (activeCount >= MAX_ACTIVE_ANTIPATTERNS) {
+    return []; // Drift prevention: don't propose more if at cap
+  }
+
+  const candidateIds = [];
+
+  for (const cluster of clusters) {
+    promoteClusterToCandidate(db, cluster.id);
+
+    const runIds = JSON.parse(cluster.run_ids || '[]');
+    const candidateId = insertAntipatternCandidate(db, {
+      cluster_id: cluster.id,
+      title: `Recurring: ${cluster.category || 'uncategorized'}`,
+      description: cluster.pattern_description,
+      detection_signal: `Pattern occurred ${cluster.occurrence_count} times across ${cluster.distinct_runs} runs`,
+      severity: cluster.occurrence_count >= 5 ? 'high' : 'medium',
+      evidence_runs: runIds,
+      evidence_count: cluster.occurrence_count,
+    });
+
+    candidateIds.push(candidateId);
+  }
+
+  return candidateIds;
+}
+
+/**
+ * Run the full pipeline pass: tally → identify → promote → expire stale.
+ * Called by the learn workflow after a run completes.
+ *
+ * @param {object} db - open state database
+ * @param {string} runId - current run ID
+ * @param {Array} findings - array of { description, category, severity, source }
+ * @returns {object} pipeline results
+ */
+export function runLearningPipeline(db, runId, findings) {
+  // Stage 1: Tally all findings
+  const clusterIds = [];
+  for (const finding of findings) {
+    const hash = crypto.createHash('sha256').update(finding.description).digest('hex');
+    const clusterId = tallyFinding(db, {
+      description: finding.description,
+      category: finding.category || '',
+      finding_hash: hash,
+      run_id: runId,
+    });
+    clusterIds.push(clusterId);
+  }
+
+  // Stage 2: Identify clusters ready for promotion
+  const readyClusters = identifyCandidates(db);
+
+  // Stage 2→3: Promote to candidates
+  const newCandidateIds = promoteToCandidates(db, readyClusters);
+
+  // Housekeeping: expire stale candidates
+  expireStaleAntipatternCandidates(db);
+
+  return {
+    findings_tallied: findings.length,
+    clusters_touched: new Set(clusterIds).size,
+    new_candidates: newCandidateIds.length,
+    candidate_ids: newCandidateIds,
+  };
+}

package/tooling/src/state/db.js

@@ -11,6 +11,21 @@ function hashDescription(description) {
   return crypto.createHash('sha256').update(description).digest('hex');
 }
 
+/**
+ * Normalize a finding description for clustering.
+ * Strips file paths, line numbers, identifiers to produce a canonical pattern.
+ */
+function canonicalizeFindingText(description) {
+  return description
+    .replace(/[a-zA-Z0-9_\-./]+\.[a-zA-Z]{1,4}(:\d+)?/g, '<FILE>')
+    .replace(/line \d+/gi, 'line <N>')
+    .replace(/['"`][\w.]+['"`]/g, '<ID>')
+    .replace(/[0-9a-f]{7,40}/gi, '<HASH>')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
 function ensureStateSchema(db) {
   db.exec(`
     CREATE TABLE IF NOT EXISTS learnings (
@@ -67,7 +82,54 @@ function ensureStateSchema(db) {
     CREATE INDEX IF NOT EXISTS idx_findings_finding_hash ON findings(finding_hash);
     CREATE INDEX IF NOT EXISTS idx_audit_history_run_id ON audit_history(run_id);
     CREATE INDEX IF NOT EXISTS idx_usage_aggregate_run_id ON usage_aggregate(run_id);
+
+    CREATE TABLE IF NOT EXISTS finding_clusters (
+      id TEXT PRIMARY KEY,
+      canonical_hash TEXT NOT NULL,
+      category TEXT NOT NULL,
+      pattern_description TEXT NOT NULL,
+      finding_hashes TEXT NOT NULL DEFAULT '[]',
+      run_ids TEXT NOT NULL DEFAULT '[]',
+      occurrence_count INTEGER DEFAULT 1,
+      distinct_runs INTEGER DEFAULT 1,
+      first_seen TEXT NOT NULL DEFAULT (datetime('now')),
+      last_seen TEXT NOT NULL DEFAULT (datetime('now')),
+      status TEXT NOT NULL DEFAULT 'tally' CHECK(status IN ('tally','candidate','promoted','active','demoted')),
+      promoted_at TEXT,
+      antipattern_id TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS antipattern_candidates (
+      id TEXT PRIMARY KEY,
+      cluster_id TEXT NOT NULL REFERENCES finding_clusters(id),
+      title TEXT NOT NULL,
+      description TEXT NOT NULL,
+      detection_signal TEXT NOT NULL,
+      severity TEXT NOT NULL CHECK(severity IN ('critical','high','medium','low')),
+      scope_roles TEXT DEFAULT 'reviewer',
+      scope_stacks TEXT DEFAULT 'all',
+      evidence_runs TEXT NOT NULL DEFAULT '[]',
+      evidence_count INTEGER DEFAULT 0,
+      status TEXT NOT NULL DEFAULT 'proposed' CHECK(status IN ('proposed','accepted','rejected','expired')),
+      proposed_at TEXT NOT NULL DEFAULT (datetime('now')),
+      reviewed_at TEXT,
+      expires_at TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_finding_clusters_status ON finding_clusters(status);
+    CREATE INDEX IF NOT EXISTS idx_finding_clusters_canonical_hash ON finding_clusters(canonical_hash);
+    CREATE INDEX IF NOT EXISTS idx_antipattern_candidates_status ON antipattern_candidates(status);
   `);
+
+  // Safe migration: add category column to findings if it doesn't exist
+  try {
+    db.exec(`ALTER TABLE findings ADD COLUMN category TEXT DEFAULT ''`);
+  } catch (_) {
+    // Column already exists — ignore
+  }
+
+  // Index on findings.category (must run after migration adds the column)
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_findings_category ON findings(category)`);
 }
 
 // ---------------------------------------------------------------------------
@@ -171,10 +233,11 @@ export function insertFinding(db, record) {
   const id = crypto.randomUUID();
   const findingHash = record.finding_hash ?? hashDescription(record.description);
   const createdAt = new Date().toISOString();
+  const category = record.category || '';
 
   db.prepare(`
-    INSERT INTO findings (id, run_id, phase, source, severity, description, finding_hash, created_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO findings (id, run_id, phase, source, severity, description, finding_hash, category, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     id,
     record.run_id,
@@ -183,9 +246,19 @@ export function insertFinding(db, record) {
     record.severity,
     record.description,
     findingHash,
+    category,
     createdAt,
   );
 
+  // Auto-tally: cluster the finding for the learning pipeline
+  upsertFindingCluster(db, {
+    canonical_hash: hashDescription(canonicalizeFindingText(record.description)),
+    category,
+    pattern_description: canonicalizeFindingText(record.description),
+    finding_hash: findingHash,
+    run_id: record.run_id,
+  });
+
   return id;
 }
 
@@ -273,6 +346,179 @@ export function getUsageSummary(db) {
   return row;
 }
 
+// ---------------------------------------------------------------------------
+// Finding Clusters (Learning Pipeline)
+// ---------------------------------------------------------------------------
+
+export function upsertFindingCluster(db, record) {
+  const existing = db.prepare(`
+    SELECT * FROM finding_clusters WHERE canonical_hash = ?
+  `).get(record.canonical_hash);
+
+  if (existing) {
+    const hashes = JSON.parse(existing.finding_hashes);
+    if (!hashes.includes(record.finding_hash)) {
+      hashes.push(record.finding_hash);
+    }
+    // Track distinct runs from the DB row, not the incoming record
+    const existingRuns = new Set(JSON.parse(existing.run_ids || '[]'));
+    if (record.run_id) existingRuns.add(record.run_id);
+
+    db.prepare(`
+      UPDATE finding_clusters
+      SET finding_hashes = ?,
+          run_ids = ?,
+          occurrence_count = occurrence_count + 1,
+          distinct_runs = ?,
+          last_seen = datetime('now'),
+          category = COALESCE(NULLIF(?, ''), category)
+      WHERE id = ?
+    `).run(
+      JSON.stringify(hashes),
+      JSON.stringify([...existingRuns]),
+      existingRuns.size,
+      record.category || '',
+      existing.id,
+    );
+
+    return existing.id;
+  }
+
+  const id = crypto.randomUUID();
+  db.prepare(`
+    INSERT INTO finding_clusters (id, canonical_hash, category, pattern_description, finding_hashes, run_ids, occurrence_count, distinct_runs)
+    VALUES (?, ?, ?, ?, ?, ?, 1, 1)
+  `).run(
+    id,
+    record.canonical_hash,
+    record.category || 'uncategorized',
+    record.pattern_description,
+    JSON.stringify([record.finding_hash]),
+    JSON.stringify(record.run_id ? [record.run_id] : []),
+  );
+
+  return id;
+}
+
+export function getClustersByStatus(db, status) {
+  return db.prepare(`
+    SELECT * FROM finding_clusters
+    WHERE status = ?
+    ORDER BY occurrence_count DESC
+  `).all(status);
+}
+
+export function getClustersReadyForPromotion(db, minOccurrences = 3, minRuns = 2) {
+  return db.prepare(`
+    SELECT * FROM finding_clusters
+    WHERE status = 'tally'
+      AND occurrence_count >= ?
+      AND distinct_runs >= ?
+    ORDER BY occurrence_count DESC
+  `).all(minOccurrences, minRuns);
+}
+
+export function promoteClusterToCandidate(db, clusterId) {
+  db.prepare(`
+    UPDATE finding_clusters
+    SET status = 'candidate',
+        promoted_at = datetime('now')
+    WHERE id = ?
+  `).run(clusterId);
+}
+
+// ---------------------------------------------------------------------------
+// Antipattern Candidates (Learning Pipeline)
+// ---------------------------------------------------------------------------
+
+export function insertAntipatternCandidate(db, record) {
+  const id = crypto.randomUUID();
+  const expiresAt = new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString(); // 90-day TTL
+
+  db.prepare(`
+    INSERT INTO antipattern_candidates (id, cluster_id, title, description, detection_signal, severity, scope_roles, scope_stacks, evidence_runs, evidence_count, expires_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id,
+    record.cluster_id,
+    record.title,
+    record.description,
+    record.detection_signal,
+    record.severity,
+    record.scope_roles || 'reviewer',
+    record.scope_stacks || 'all',
+    JSON.stringify(Array.isArray(record.evidence_runs) ? record.evidence_runs : []),
+    record.evidence_count || 0,
+    expiresAt,
+  );
+
+  return id;
+}
+
+export function getAntipatternCandidatesByStatus(db, status) {
+  return db.prepare(`
+    SELECT * FROM antipattern_candidates
+    WHERE status = ?
+    ORDER BY proposed_at DESC
+  `).all(status);
+}
+
+export function acceptAntipatternCandidate(db, candidateId) {
+  const now = new Date().toISOString();
+  db.prepare(`
+    UPDATE antipattern_candidates
+    SET status = 'accepted',
+        reviewed_at = ?
+    WHERE id = ?
+  `).run(now, candidateId);
+}
+
+export function rejectAntipatternCandidate(db, candidateId) {
+  const now = new Date().toISOString();
+  // Get the cluster_id before updating so we can reset the cluster
+  const candidate = db.prepare(`SELECT cluster_id FROM antipattern_candidates WHERE id = ?`).get(candidateId);
+  db.prepare(`
+    UPDATE antipattern_candidates
+    SET status = 'rejected',
+        reviewed_at = ?
+    WHERE id = ?
+  `).run(now, candidateId);
+  // Reset cluster back to 'tally' so the pattern can be re-proposed if it keeps recurring
+  if (candidate) {
+    db.prepare(`UPDATE finding_clusters SET status = 'tally' WHERE id = ?`).run(candidate.cluster_id);
+  }
+}
+
+export function expireStaleAntipatternCandidates(db) {
+  const now = new Date().toISOString();
+  // Get cluster IDs for candidates about to expire so we can reset them
+  const expiring = db.prepare(`
+    SELECT cluster_id FROM antipattern_candidates
+    WHERE status = 'proposed' AND expires_at < ?
+  `).all(now);
+
+  const result = db.prepare(`
+    UPDATE antipattern_candidates
+    SET status = 'expired'
+    WHERE status = 'proposed'
+      AND expires_at < ?
+  `).run(now);
+
+  // Reset clusters back to 'tally' so patterns can be re-proposed
+  for (const { cluster_id } of expiring) {
+    db.prepare(`UPDATE finding_clusters SET status = 'tally' WHERE id = ?`).run(cluster_id);
+  }
+
+  return result;
+}
+
+export function getActiveLearningsCount(db) {
+  return db.prepare(`
+    SELECT COUNT(*) AS count FROM antipattern_candidates
+    WHERE status = 'accepted'
+  `).get().count;
+}
+
 // ---------------------------------------------------------------------------
 // Stats (for CLI)
 // ---------------------------------------------------------------------------
@@ -283,5 +529,8 @@ export function getStateCounts(db) {
     finding_count: db.prepare('SELECT COUNT(*) AS count FROM findings').get().count,
     audit_count: db.prepare('SELECT COUNT(*) AS count FROM audit_history').get().count,
     usage_count: db.prepare('SELECT COUNT(*) AS count FROM usage_aggregate').get().count,
+    cluster_count: db.prepare('SELECT COUNT(*) AS count FROM finding_clusters').get().count,
+    candidate_count: db.prepare('SELECT COUNT(*) AS count FROM antipattern_candidates WHERE status = ?').get('proposed').count,
+    active_antipattern_count: db.prepare('SELECT COUNT(*) AS count FROM antipattern_candidates WHERE status = ?').get('accepted').count,
   };
 }