chati-dev 4.2.1 → 4.3.0

package/scripts/stuck-detector.js

@@ -1,343 +0,0 @@
-/**
- * StuckDetector — Detects stalled execution patterns.
- *
- * Identifies consecutive failures, circular approaches, and stall timeouts
- * to trigger escalation before wasting further resources.
- *
- * @module scripts/stuck-detector
- */
-
-/**
- * @typedef {Object} Attempt
- * @property {string} taskId
- * @property {string} agent
- * @property {string} approach
- * @property {boolean} success
- * @property {number} timestamp
- * @property {string} [error]
- */
-
-/**
- * @typedef {Object} StuckResult
- * @property {boolean} stuck
- * @property {string} reason
- * @property {Object} evidence
- */
-
-/**
- * @typedef {Object} CircularResult
- * @property {boolean} circular
- * @property {string[]} pattern
- */
-
-/**
- * @typedef {Object} EscalationContext
- * @property {Attempt[]} history
- * @property {number} failureCount
- * @property {string[]} approaches
- * @property {string} suggestion
- */
-
-/**
- * @typedef {Object} Stats
- * @property {number} totalAttempts
- * @property {number} failures
- * @property {number} successRate
- * @property {number} averageDuration
- */
-
-export class StuckDetector {
-  /**
-   * @param {Object} [options]
-   * @param {number} [options.maxConsecutiveFailures=3]
-   * @param {number} [options.circularWindow=10]
-   * @param {number} [options.stallTimeout=300000]
-   */
-  constructor(options = {}) {
-    this.maxConsecutiveFailures = options.maxConsecutiveFailures ?? 3;
-    this.circularWindow = options.circularWindow ?? 10;
-    this.stallTimeout = options.stallTimeout ?? 300000; // 5 minutes
-    /** @type {Attempt[]} */
-    this.attempts = [];
-  }
-
-  /**
-   * Records an execution attempt.
-   * @param {Attempt} attempt
-   */
-  recordAttempt(attempt) {
-    if (!attempt || typeof attempt !== 'object') {
-      throw new Error('Attempt must be a non-null object');
-    }
-    if (!attempt.taskId || typeof attempt.taskId !== 'string') {
-      throw new Error('Attempt must have a string taskId');
-    }
-    if (!attempt.agent || typeof attempt.agent !== 'string') {
-      throw new Error('Attempt must have a string agent');
-    }
-    if (!attempt.approach || typeof attempt.approach !== 'string') {
-      throw new Error('Attempt must have a string approach');
-    }
-    if (typeof attempt.success !== 'boolean') {
-      throw new Error('Attempt must have a boolean success');
-    }
-
-    this.attempts.push({
-      taskId: attempt.taskId,
-      agent: attempt.agent,
-      approach: attempt.approach,
-      success: attempt.success,
-      timestamp: attempt.timestamp ?? Date.now(),
-      error: attempt.error ?? null,
-    });
-  }
-
-  /**
-   * Checks whether execution is stuck.
-   * Evaluates: consecutive failures, circular approaches, stall timeout.
-   * @returns {StuckResult}
-   */
-  isStuck() {
-    if (this.attempts.length === 0) {
-      return { stuck: false, reason: 'No attempts recorded', evidence: {} };
-    }
-
-    // --- Check consecutive failures ---
-    const consecutiveFailures = this._countConsecutiveFailures();
-    if (consecutiveFailures >= this.maxConsecutiveFailures) {
-      const failedAttempts = this.attempts.slice(-consecutiveFailures);
-      return {
-        stuck: true,
-        reason: `${consecutiveFailures} consecutive failures detected`,
-        evidence: {
-          type: 'consecutive_failures',
-          count: consecutiveFailures,
-          attempts: failedAttempts.map((a) => ({
-            taskId: a.taskId,
-            agent: a.agent,
-            approach: a.approach,
-            error: a.error,
-          })),
-        },
-      };
-    }
-
-    // --- Check circular approaches ---
-    const recentAttempts = this.attempts.slice(-this.circularWindow);
-    const circular = this.detectCircularApproach(recentAttempts);
-    if (circular.circular) {
-      return {
-        stuck: true,
-        reason: `Circular approach pattern detected: ${circular.pattern.join(' -> ')}`,
-        evidence: {
-          type: 'circular_approach',
-          pattern: circular.pattern,
-          window: recentAttempts.length,
-        },
-      };
-    }
-
-    // --- Check stall timeout ---
-    const stallResult = this._checkStallTimeout();
-    if (stallResult.stalled) {
-      return {
-        stuck: true,
-        reason: `Execution stalled for ${Math.round(stallResult.duration / 1000)}s without success`,
-        evidence: {
-          type: 'stall_timeout',
-          duration: stallResult.duration,
-          threshold: this.stallTimeout,
-          lastSuccess: stallResult.lastSuccessTimestamp,
-        },
-      };
-    }
-
-    return { stuck: false, reason: 'Execution proceeding normally', evidence: {} };
-  }
-
-  /**
-   * Detects if the same approaches are being tried repeatedly (A->B->A->B).
-   * @param {Attempt[]} attempts
-   * @returns {CircularResult}
-   */
-  detectCircularApproach(attempts) {
-    if (!attempts || attempts.length < 4) {
-      return { circular: false, pattern: [] };
-    }
-
-    const approaches = attempts.map((a) => a.approach);
-
-    // Try pattern lengths from 2 to half the window
-    const maxPatternLen = Math.floor(approaches.length / 2);
-    for (let patternLen = 2; patternLen <= maxPatternLen; patternLen++) {
-      const candidate = approaches.slice(0, patternLen);
-      let repeats = 0;
-      let matched = true;
-
-      for (let i = 0; i < approaches.length; i++) {
-        if (approaches[i] !== candidate[i % patternLen]) {
-          matched = false;
-          break;
-        }
-        if (i > 0 && i % patternLen === 0) {
-          repeats++;
-        }
-      }
-
-      // Need at least 2 full repetitions to count as circular
-      if (matched && repeats >= 2) {
-        return { circular: true, pattern: candidate };
-      }
-    }
-
-    // Also check for trailing repetition pattern (recent attempts form a cycle)
-    for (let patternLen = 2; patternLen <= maxPatternLen; patternLen++) {
-      const tail = approaches.slice(-patternLen * 2);
-      if (tail.length < patternLen * 2) continue;
-
-      const firstHalf = tail.slice(0, patternLen);
-      const secondHalf = tail.slice(patternLen);
-      const isRepeat = firstHalf.every((val, idx) => val === secondHalf[idx]);
-
-      if (isRepeat) {
-        return { circular: true, pattern: firstHalf };
-      }
-    }
-
-    return { circular: false, pattern: [] };
-  }
-
-  /**
-   * Builds context for escalation to a human operator.
-   * @returns {EscalationContext}
-   */
-  getEscalationContext() {
-    const failures = this.attempts.filter((a) => !a.success);
-    const uniqueApproaches = [...new Set(this.attempts.map((a) => a.approach))];
-
-    let suggestion = 'Review recent failures and consider an alternative strategy.';
-
-    if (failures.length > 0) {
-      const errorMessages = failures
-        .filter((f) => f.error)
-        .map((f) => f.error);
-      const uniqueErrors = [...new Set(errorMessages)];
-
-      if (uniqueErrors.length === 1) {
-        suggestion = `All failures share the same error: "${uniqueErrors[0]}". Investigate this specific root cause.`;
-      } else if (uniqueApproaches.length <= 2 && failures.length >= 3) {
-        suggestion =
-          'Only 1-2 approaches have been tried. Consider a fundamentally different approach.';
-      } else if (failures.length === this.attempts.length) {
-        suggestion =
-          'No successful attempts at all. The task may need re-scoping or prerequisite work.';
-      }
-    }
-
-    return {
-      history: [...this.attempts],
-      failureCount: failures.length,
-      approaches: uniqueApproaches,
-      suggestion,
-    };
-  }
-
-  /**
-   * Clears all recorded attempts.
-   */
-  reset() {
-    this.attempts = [];
-  }
-
-  /**
-   * Returns aggregate statistics about recorded attempts.
-   * @returns {Stats}
-   */
-  getStats() {
-    const total = this.attempts.length;
-    if (total === 0) {
-      return { totalAttempts: 0, failures: 0, successRate: 0, averageDuration: 0 };
-    }
-
-    const failures = this.attempts.filter((a) => !a.success).length;
-    const successRate = ((total - failures) / total) * 100;
-
-    // Calculate average duration between consecutive attempts
-    let totalDuration = 0;
-    let durationCount = 0;
-    for (let i = 1; i < this.attempts.length; i++) {
-      const diff = this.attempts[i].timestamp - this.attempts[i - 1].timestamp;
-      if (diff > 0) {
-        totalDuration += diff;
-        durationCount++;
-      }
-    }
-    const averageDuration = durationCount > 0 ? totalDuration / durationCount : 0;
-
-    return {
-      totalAttempts: total,
-      failures,
-      successRate: Math.round(successRate * 100) / 100,
-      averageDuration: Math.round(averageDuration),
-    };
-  }
-
-  // ── Private helpers ──────────────────────────────────────────
-
-  /**
-   * Counts consecutive failures from the most recent attempt backward.
-   * @returns {number}
-   * @private
-   */
-  _countConsecutiveFailures() {
-    let count = 0;
-    for (let i = this.attempts.length - 1; i >= 0; i--) {
-      if (!this.attempts[i].success) {
-        count++;
-      } else {
-        break;
-      }
-    }
-    return count;
-  }
-
-  /**
-   * Checks if execution has stalled (no success within stallTimeout).
-   * @returns {{ stalled: boolean, duration: number, lastSuccessTimestamp: number|null }}
-   * @private
-   */
-  _checkStallTimeout() {
-    const now = Date.now();
-    const successes = this.attempts.filter((a) => a.success);
-    const lastSuccessTimestamp =
-      successes.length > 0 ? successes[successes.length - 1].timestamp : null;
-
-    // If we have never succeeded, measure from first attempt
-    const referenceTime = lastSuccessTimestamp ?? this.attempts[0]?.timestamp ?? now;
-    const duration = now - referenceTime;
-
-    // Only consider stalled if there are recent failures after reference
-    const attemptsAfterRef = this.attempts.filter((a) => a.timestamp > referenceTime);
-    const hasRecentFailures = attemptsAfterRef.some((a) => !a.success);
-
-    return {
-      stalled: duration >= this.stallTimeout && (hasRecentFailures || !lastSuccessTimestamp),
-      duration,
-      lastSuccessTimestamp,
-    };
-  }
-}
-
-/**
- * Convenience: creates a StuckDetector and evaluates a batch of attempts.
- * @param {Attempt[]} attempts
- * @param {Object} [options]
- * @returns {StuckResult}
- */
-export function evaluateAttempts(attempts, options = {}) {
-  const detector = new StuckDetector(options);
-  for (const attempt of attempts) {
-    detector.recordAttempt(attempt);
-  }
-  return detector.isStuck();
-}

package/scripts/test-quality-assessment.js

@@ -1,257 +0,0 @@
-/**
- * Test Quality Assessment — Evaluates test file quality through static analysis.
- *
- * Counts test structures, detects anti-patterns, and calculates quality scores
- * to help maintain high testing standards.
- *
- * @module scripts/test-quality-assessment
- */
-
-import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-
-/**
- * @typedef {Object} FileReport
- * @property {string} filePath
- * @property {number} describeCount
- * @property {number} itCount
- * @property {number} assertionCount
- * @property {number} assertionsPerTest
- * @property {boolean} hasEdgeCases
- * @property {boolean} hasErrorHandling
- * @property {boolean} hasSetupTeardown
- * @property {string[]} antiPatterns
- * @property {number} lineCount
- */
-
-/**
- * @typedef {Object} QualityReport
- * @property {FileReport[]} files
- * @property {Object} overall
- * @property {number} overall.score
- * @property {string} overall.grade
- * @property {string[]} overall.issues
- */
-
-// Patterns for detecting various test constructs
-const PATTERNS = {
-  describe: /\bdescribe\s*\(/g,
-  it: /\b(?:it|test)\s*\(/g,
-  assertion: /\b(?:expect|assert|should)\s*[.(]/g,
-  edgeCase: /\b(?:edge|boundary|limit|overflow|underflow|empty|null|undefined|NaN|zero|negative|max|min)\b/gi,
-  errorHandling: /\b(?:throw|reject|error|catch|fail|invalid|malformed|corrupt)\b/gi,
-  beforeEach: /\b(?:beforeEach|beforeAll|before)\s*\(/g,
-  afterEach: /\b(?:afterEach|afterAll|after)\s*\(/g,
-  emptyTest: /\b(?:it|test)\s*\(\s*(['"`]).*?\1\s*,\s*(?:(?:async\s*)?\(\s*\)\s*=>\s*\{\s*\}|function\s*\(\s*\)\s*\{\s*\})\s*\)/g,
-  todoTest: /\b(?:it|test)\s*\.\s*(?:skip|todo)\s*\(/g,
-};
-
-/**
- * Finds all *.test.js and *.spec.js files recursively.
- * @param {string} dir
- * @returns {string[]}
- */
-export function findTestFiles(dir) {
-  const results = [];
-
-  function walk(currentDir) {
-    let entries;
-    try {
-      entries = readdirSync(currentDir);
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      if (entry === 'node_modules' || entry === '.git') continue;
-      const fullPath = join(currentDir, entry);
-      let stat;
-      try {
-        stat = statSync(fullPath);
-      } catch {
-        continue;
-      }
-      if (stat.isDirectory()) {
-        walk(fullPath);
-      } else if (
-        stat.isFile() &&
-        (entry.endsWith('.test.js') || entry.endsWith('.spec.js'))
-      ) {
-        results.push(fullPath);
-      }
-    }
-  }
-
-  walk(dir);
-  return results.sort();
-}
-
-/**
- * Assesses quality of a single test file.
- * @param {string} filePath
- * @returns {FileReport}
- */
-export function assessSingleFile(filePath) {
-  let content;
-  try {
-    content = readFileSync(filePath, 'utf-8');
-  } catch (err) {
-    return {
-      filePath,
-      describeCount: 0,
-      itCount: 0,
-      assertionCount: 0,
-      assertionsPerTest: 0,
-      hasEdgeCases: false,
-      hasErrorHandling: false,
-      hasSetupTeardown: false,
-      antiPatterns: [`Unable to read file: ${err.message}`],
-      lineCount: 0,
-    };
-  }
-
-  const lines = content.split('\n');
-  const lineCount = lines.length;
-
-  const describeCount = (content.match(PATTERNS.describe) || []).length;
-  const itCount = (content.match(PATTERNS.it) || []).length;
-  const assertionCount = (content.match(PATTERNS.assertion) || []).length;
-  const assertionsPerTest = itCount > 0 ? Math.round((assertionCount / itCount) * 100) / 100 : 0;
-
-  const hasEdgeCases = PATTERNS.edgeCase.test(content);
-  PATTERNS.edgeCase.lastIndex = 0; // reset regex state
-
-  const hasErrorHandling = PATTERNS.errorHandling.test(content);
-  PATTERNS.errorHandling.lastIndex = 0;
-
-  const hasBeforeAfter =
-    PATTERNS.beforeEach.test(content) || PATTERNS.afterEach.test(content);
-  PATTERNS.beforeEach.lastIndex = 0;
-  PATTERNS.afterEach.lastIndex = 0;
-
-  // Detect anti-patterns
-  const antiPatterns = [];
-
-  if (itCount > 0 && assertionCount === 0) {
-    antiPatterns.push('Tests have no assertions');
-  }
-
-  const emptyTests = (content.match(PATTERNS.emptyTest) || []).length;
-  if (emptyTests > 0) {
-    antiPatterns.push(`${emptyTests} empty test(s) found`);
-  }
-
-  const todoTests = (content.match(PATTERNS.todoTest) || []).length;
-  if (todoTests > 0) {
-    antiPatterns.push(`${todoTests} skipped/todo test(s)`);
-  }
-
-  // Detect duplicate test names
-  const testNames = [];
-  const testNameRegex = /\b(?:it|test)\s*\(\s*(['"`])(.*?)\1/g;
-  let match;
-  while ((match = testNameRegex.exec(content)) !== null) {
-    testNames.push(match[2]);
-  }
-  const duplicates = testNames.filter((name, idx) => testNames.indexOf(name) !== idx);
-  if (duplicates.length > 0) {
-    const unique = [...new Set(duplicates)];
-    antiPatterns.push(`Duplicate test names: ${unique.join(', ')}`);
-  }
-
-  if (assertionsPerTest > 0 && assertionsPerTest < 1) {
-    antiPatterns.push('Low assertion density (some tests may lack assertions)');
-  }
-
-  return {
-    filePath,
-    describeCount,
-    itCount,
-    assertionCount,
-    assertionsPerTest,
-    hasEdgeCases,
-    hasErrorHandling,
-    hasSetupTeardown: hasBeforeAfter,
-    antiPatterns,
-    lineCount,
-  };
-}
-
-/**
- * Calculates an overall quality score from multiple file reports.
- * @param {FileReport[]} reports
- * @returns {{ score: number, grade: string, issues: string[] }}
- */
-export function calculateOverallScore(reports) {
-  if (reports.length === 0) {
-    return { score: 0, grade: 'F', issues: ['No test files found'] };
-  }
-
-  const issues = [];
-  let score = 100;
-
-  // Aggregate stats
-  const totalTests = reports.reduce((s, r) => s + r.itCount, 0);
-  const totalAssertions = reports.reduce((s, r) => s + r.assertionCount, 0);
-  const filesWithEdgeCases = reports.filter((r) => r.hasEdgeCases).length;
-  const filesWithErrorHandling = reports.filter((r) => r.hasErrorHandling).length;
-  const filesWithSetup = reports.filter((r) => r.hasSetupTeardown).length;
-  const allAntiPatterns = reports.flatMap((r) => r.antiPatterns);
-
-  // Deductions
-  if (totalTests === 0) {
-    score -= 50;
-    issues.push('No test cases found');
-  }
-
-  if (totalTests > 0 && totalAssertions / totalTests < 1) {
-    score -= 15;
-    issues.push('Low assertion density across test suite');
-  }
-
-  const edgeCaseRatio = filesWithEdgeCases / reports.length;
-  if (edgeCaseRatio < 0.3) {
-    score -= 10;
-    issues.push(`Only ${Math.round(edgeCaseRatio * 100)}% of files test edge cases`);
-  }
-
-  const errorHandlingRatio = filesWithErrorHandling / reports.length;
-  if (errorHandlingRatio < 0.3) {
-    score -= 10;
-    issues.push(`Only ${Math.round(errorHandlingRatio * 100)}% of files test error handling`);
-  }
-
-  const setupRatio = filesWithSetup / reports.length;
-  if (setupRatio < 0.2) {
-    score -= 5;
-    issues.push('Few files use setup/teardown (beforeEach/afterEach)');
-  }
-
-  // Anti-pattern deductions (capped)
-  const antiPatternPenalty = Math.min(allAntiPatterns.length * 3, 20);
-  if (antiPatternPenalty > 0) {
-    score -= antiPatternPenalty;
-    issues.push(`${allAntiPatterns.length} anti-pattern(s) detected across files`);
-  }
-
-  score = Math.max(0, Math.min(100, score));
-
-  let grade;
-  if (score >= 90) grade = 'A';
-  else if (score >= 80) grade = 'B';
-  else if (score >= 70) grade = 'C';
-  else if (score >= 60) grade = 'D';
-  else grade = 'F';
-
-  return { score, grade, issues };
-}
-
-/**
- * Assesses quality of multiple test files.
- * @param {string[]} testFilePaths
- * @returns {QualityReport}
- */
-export function assessTestQuality(testFilePaths) {
-  const files = testFilePaths.map((fp) => assessSingleFile(fp));
-  const overall = calculateOverallScore(files);
-  return { files, overall };
-}