@boshu2/vibe-check 1.0.0

package/src/metrics/spirals.ts

@@ -0,0 +1,173 @@
+import { differenceInMinutes } from 'date-fns';
+import { Commit, FixChain, MetricResult, Rating } from '../types';
+
+const SPIRAL_THRESHOLD = 3; // 3+ consecutive fixes = spiral
+
+// Pattern detection regexes
+const PATTERNS: Record<string, RegExp> = {
+  VOLUME_CONFIG: /volume|mount|path|permission|readonly|pvc|storage/i,
+  SECRETS_AUTH: /secret|auth|oauth|token|credential|password|key/i,
+  API_MISMATCH: /api|version|field|spec|schema|crd|resource/i,
+  SSL_TLS: /ssl|tls|cert|fips|handshake|https/i,
+  IMAGE_REGISTRY: /image|pull|registry|docker|tag/i,
+  GITOPS_DRIFT: /drift|sync|argocd|reconcil|outof/i,
+};
+
+export function detectFixChains(commits: Commit[]): FixChain[] {
+  if (commits.length === 0) return [];
+
+  // Sort by date ascending
+  const sorted = [...commits].sort((a, b) => a.date.getTime() - b.date.getTime());
+
+  const chains: FixChain[] = [];
+  let currentChain: Commit[] = [];
+  let currentComponent: string | null = null;
+
+  for (const commit of sorted) {
+    if (commit.type === 'fix') {
+      const component = getComponent(commit);
+
+      if (component === currentComponent || currentComponent === null) {
+        currentChain.push(commit);
+        currentComponent = component;
+      } else {
+        // Different component, save current chain if valid
+        if (currentChain.length >= SPIRAL_THRESHOLD) {
+          chains.push(createFixChain(currentChain, currentComponent));
+        }
+        currentChain = [commit];
+        currentComponent = component;
+      }
+    } else {
+      // Non-fix commit breaks the chain
+      if (currentChain.length >= SPIRAL_THRESHOLD && currentComponent) {
+        chains.push(createFixChain(currentChain, currentComponent));
+      }
+      currentChain = [];
+      currentComponent = null;
+    }
+  }
+
+  // Handle final chain
+  if (currentChain.length >= SPIRAL_THRESHOLD && currentComponent) {
+    chains.push(createFixChain(currentChain, currentComponent));
+  }
+
+  return chains;
+}
+
+function getComponent(commit: Commit): string {
+  // Use scope if available
+  if (commit.scope) {
+    return commit.scope.toLowerCase();
+  }
+
+  // Extract first meaningful word from message
+  const words = commit.message
+    .replace(/^fix\s*:?\s*/i, '')
+    .split(/\s+/)
+    .filter((w) => w.length > 2);
+
+  return words[0]?.toLowerCase() || 'unknown';
+}
+
+function createFixChain(commits: Commit[], component: string): FixChain {
+  const firstCommit = commits[0].date;
+  const lastCommit = commits[commits.length - 1].date;
+  const duration = differenceInMinutes(lastCommit, firstCommit);
+
+  // Detect pattern from commit messages
+  const allMessages = commits.map((c) => c.message).join(' ');
+  const pattern = detectPattern(allMessages);
+
+  return {
+    component,
+    commits: commits.length,
+    duration,
+    isSpiral: commits.length >= SPIRAL_THRESHOLD,
+    pattern,
+    firstCommit,
+    lastCommit,
+  };
+}
+
+function detectPattern(text: string): string | null {
+  for (const [pattern, regex] of Object.entries(PATTERNS)) {
+    if (regex.test(text)) {
+      return pattern;
+    }
+  }
+  return null;
+}
+
+export function calculateDebugSpiralDuration(chains: FixChain[]): MetricResult {
+  const spirals = chains.filter((c) => c.isSpiral);
+
+  if (spirals.length === 0) {
+    return {
+      value: 0,
+      unit: 'min',
+      rating: 'elite',
+      description: 'No debug spirals detected',
+    };
+  }
+
+  const totalDuration = spirals.reduce((sum, s) => sum + s.duration, 0);
+  const avgDuration = totalDuration / spirals.length;
+  const rating = getRating(avgDuration);
+
+  return {
+    value: Math.round(avgDuration),
+    unit: 'min',
+    rating,
+    description: getDescription(rating, spirals.length),
+  };
+}
+
+function getRating(duration: number): Rating {
+  if (duration < 15) return 'elite';
+  if (duration < 30) return 'high';
+  if (duration < 60) return 'medium';
+  return 'low';
+}
+
+function getDescription(rating: Rating, spiralCount: number): string {
+  const spiralText = spiralCount === 1 ? '1 spiral' : `${spiralCount} spirals`;
+
+  switch (rating) {
+    case 'elite':
+      return `${spiralText} resolved quickly`;
+    case 'high':
+      return `${spiralText}, normal debugging time`;
+    case 'medium':
+      return `${spiralText}, consider using tracer tests`;
+    case 'low':
+      return `${spiralText}, extended debugging. Use tracer tests before implementation`;
+  }
+}
+
+export function calculatePatternSummary(chains: FixChain[]): {
+  categories: Record<string, number>;
+  total: number;
+  tracerAvailable: number;
+} {
+  const categories: Record<string, number> = {};
+  let total = 0;
+  let withTracer = 0;
+
+  for (const chain of chains) {
+    const pattern = chain.pattern || 'OTHER';
+    categories[pattern] = (categories[pattern] || 0) + chain.commits;
+    total += chain.commits;
+
+    if (chain.pattern) {
+      withTracer += chain.commits;
+    }
+  }
+
+  return {
+    categories,
+    total,
+    tracerAvailable: total > 0 ? Math.round((withTracer / total) * 100) : 0,
+  };
+}

package/src/metrics/trust.ts

@@ -0,0 +1,80 @@
+import { differenceInMinutes } from 'date-fns';
+import { Commit, MetricResult, Rating } from '../types';
+
+const FOLLOWUP_WINDOW_MINUTES = 30;
+
+export function calculateTrustPassRate(commits: Commit[]): MetricResult {
+  if (commits.length === 0) {
+    return {
+      value: 100,
+      unit: '%',
+      rating: 'elite',
+      description: 'No commits found',
+    };
+  }
+
+  // Sort by date ascending
+  const sorted = [...commits].sort((a, b) => a.date.getTime() - b.date.getTime());
+
+  let trustedCommits = 0;
+
+  for (let i = 0; i < sorted.length; i++) {
+    const commit = sorted[i];
+    const nextCommit = sorted[i + 1];
+
+    // Check if next commit is a fix to same component within 30 min
+    const needsFollowup =
+      nextCommit &&
+      nextCommit.type === 'fix' &&
+      sameComponent(commit, nextCommit) &&
+      differenceInMinutes(nextCommit.date, commit.date) < FOLLOWUP_WINDOW_MINUTES;
+
+    if (!needsFollowup) {
+      trustedCommits++;
+    }
+  }
+
+  const rate = (trustedCommits / commits.length) * 100;
+  const rating = getRating(rate);
+
+  return {
+    value: Math.round(rate),
+    unit: '%',
+    rating,
+    description: getDescription(rating),
+  };
+}
+
+function sameComponent(a: Commit, b: Commit): boolean {
+  // If both have scopes, compare them
+  if (a.scope && b.scope) {
+    return a.scope.toLowerCase() === b.scope.toLowerCase();
+  }
+
+  // If neither has scope, check if messages reference same area
+  // This is a simple heuristic - first word after type
+  const aWords = a.message.split(/\s+/).slice(0, 3);
+  const bWords = b.message.split(/\s+/).slice(0, 3);
+
+  return aWords.some((word) => bWords.includes(word) && word.length > 3);
+}
+
+function getRating(rate: number): Rating {
+  if (rate > 95) return 'elite';
+  if (rate >= 80) return 'high';
+  if (rate >= 60) return 'medium';
+  return 'low';
+}
+
+function getDescription(rating: Rating): string {
+  switch (rating) {
+    case 'elite':
+      return 'Code sticks on first try, high AI trust';
+    case 'high':
+      return 'Occasional fixes needed, mostly autonomous';
+    case 'medium':
+      return 'Regular intervention required';
+    case 'low':
+      return 'Heavy oversight needed, run tracer tests before implementation';
+  }
+}

package/src/metrics/velocity.ts

@@ -0,0 +1,86 @@
+import { differenceInMinutes } from 'date-fns';
+import { Commit, MetricResult, Rating } from '../types';
+
+const SESSION_GAP_MINUTES = 120; // 2 hours = new session
+
+export function calculateIterationVelocity(commits: Commit[]): MetricResult {
+  if (commits.length === 0) {
+    return {
+      value: 0,
+      unit: 'commits/hour',
+      rating: 'low',
+      description: 'No commits found',
+    };
+  }
+
+  const activeHours = calculateActiveHours(commits);
+
+  if (activeHours === 0) {
+    return {
+      value: commits.length,
+      unit: 'commits/hour',
+      rating: 'high',
+      description: 'All commits in rapid succession',
+    };
+  }
+
+  const velocity = commits.length / activeHours;
+  const rating = getRating(velocity);
+
+  return {
+    value: Math.round(velocity * 10) / 10,
+    unit: 'commits/hour',
+    rating,
+    description: getDescription(rating),
+  };
+}
+
+export function calculateActiveHours(commits: Commit[]): number {
+  if (commits.length < 2) {
+    return 0.1; // Minimum to avoid division by zero
+  }
+
+  // Sort by date ascending
+  const sorted = [...commits].sort((a, b) => a.date.getTime() - b.date.getTime());
+
+  let totalMinutes = 0;
+  let sessionStart = sorted[0].date;
+
+  for (let i = 1; i < sorted.length; i++) {
+    const gap = differenceInMinutes(sorted[i].date, sorted[i - 1].date);
+
+    if (gap > SESSION_GAP_MINUTES) {
+      // End current session, start new one
+      totalMinutes += differenceInMinutes(sorted[i - 1].date, sessionStart);
+      sessionStart = sorted[i].date;
+    }
+  }
+
+  // Add final session
+  totalMinutes += differenceInMinutes(sorted[sorted.length - 1].date, sessionStart);
+
+  // Minimum of 10 minutes per session to account for work between commits
+  const minMinutes = Math.max(totalMinutes, commits.length * 10);
+
+  return minMinutes / 60;
+}
+
+function getRating(velocity: number): Rating {
+  if (velocity > 5) return 'elite';
+  if (velocity >= 3) return 'high';
+  if (velocity >= 1) return 'medium';
+  return 'low';
+}
+
+function getDescription(rating: Rating): string {
+  switch (rating) {
+    case 'elite':
+      return 'Excellent iteration speed, tight feedback loops';
+    case 'high':
+      return 'Good iteration speed';
+    case 'medium':
+      return 'Normal pace';
+    case 'low':
+      return 'Slow iteration, consider smaller commits';
+  }
+}

package/src/output/index.ts

@@ -0,0 +1,20 @@
+import { VibeCheckResult, OutputFormat } from '../types';
+import { formatTerminal } from './terminal';
+import { formatJson } from './json';
+import { formatMarkdown } from './markdown';
+
+export function formatOutput(result: VibeCheckResult, format: OutputFormat): string {
+  switch (format) {
+    case 'json':
+      return formatJson(result);
+    case 'markdown':
+      return formatMarkdown(result);
+    case 'terminal':
+    default:
+      return formatTerminal(result);
+  }
+}
+
+export { formatTerminal } from './terminal';
+export { formatJson } from './json';
+export { formatMarkdown } from './markdown';

package/src/output/json.ts

@@ -0,0 +1,51 @@
+import { VibeCheckResult } from '../types';
+
+export function formatJson(result: VibeCheckResult): string {
+  // Create a JSON-friendly version with ISO date strings
+  const output = {
+    period: {
+      from: result.period.from.toISOString(),
+      to: result.period.to.toISOString(),
+      activeHours: result.period.activeHours,
+    },
+    commits: result.commits,
+    metrics: {
+      iterationVelocity: {
+        value: result.metrics.iterationVelocity.value,
+        unit: result.metrics.iterationVelocity.unit,
+        rating: result.metrics.iterationVelocity.rating,
+      },
+      reworkRatio: {
+        value: result.metrics.reworkRatio.value,
+        unit: result.metrics.reworkRatio.unit,
+        rating: result.metrics.reworkRatio.rating,
+      },
+      trustPassRate: {
+        value: result.metrics.trustPassRate.value,
+        unit: result.metrics.trustPassRate.unit,
+        rating: result.metrics.trustPassRate.rating,
+      },
+      debugSpiralDuration: {
+        value: result.metrics.debugSpiralDuration.value,
+        unit: result.metrics.debugSpiralDuration.unit,
+        rating: result.metrics.debugSpiralDuration.rating,
+      },
+      flowEfficiency: {
+        value: result.metrics.flowEfficiency.value,
+        unit: result.metrics.flowEfficiency.unit,
+        rating: result.metrics.flowEfficiency.rating,
+      },
+    },
+    fixChains: result.fixChains.map((chain) => ({
+      component: chain.component,
+      commits: chain.commits,
+      duration: chain.duration,
+      isSpiral: chain.isSpiral,
+      pattern: chain.pattern,
+    })),
+    patterns: result.patterns,
+    overall: result.overall,
+  };
+
+  return JSON.stringify(output, null, 2);
+}

package/src/output/markdown.ts

@@ -0,0 +1,111 @@
+import { VibeCheckResult } from '../types';
+import { format } from 'date-fns';
+
+export function formatMarkdown(result: VibeCheckResult): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push('# Vibe-Check Report');
+  lines.push('');
+
+  // Period
+  const fromStr = format(result.period.from, 'MMM d, yyyy');
+  const toStr = format(result.period.to, 'MMM d, yyyy');
+  lines.push(`**Period:** ${fromStr} - ${toStr} (${result.period.activeHours}h active)`);
+  lines.push(
+    `**Commits:** ${result.commits.total} total (${result.commits.feat} feat, ${result.commits.fix} fix, ${result.commits.docs} docs, ${result.commits.other} other)`
+  );
+  lines.push('');
+
+  // Overall
+  lines.push(`**Overall Rating:** ${result.overall}`);
+  lines.push('');
+
+  // Metrics table
+  lines.push('## Metrics');
+  lines.push('');
+  lines.push('| Metric | Value | Rating | Description |');
+  lines.push('|--------|-------|--------|-------------|');
+
+  const metrics = [
+    { name: 'Iteration Velocity', metric: result.metrics.iterationVelocity },
+    { name: 'Rework Ratio', metric: result.metrics.reworkRatio },
+    { name: 'Trust Pass Rate', metric: result.metrics.trustPassRate },
+    { name: 'Debug Spiral Duration', metric: result.metrics.debugSpiralDuration },
+    { name: 'Flow Efficiency', metric: result.metrics.flowEfficiency },
+  ];
+
+  for (const { name, metric } of metrics) {
+    const rating = metric.rating.toUpperCase();
+    lines.push(
+      `| ${name} | ${metric.value}${metric.unit} | ${rating} | ${metric.description} |`
+    );
+  }
+  lines.push('');
+
+  // Debug spirals
+  if (result.fixChains.length > 0) {
+    lines.push('## Debug Spirals');
+    lines.push('');
+    lines.push('| Component | Commits | Duration | Pattern |');
+    lines.push('|-----------|---------|----------|---------|');
+
+    for (const chain of result.fixChains) {
+      const pattern = chain.pattern || '-';
+      lines.push(
+        `| ${chain.component} | ${chain.commits} | ${chain.duration}m | ${pattern} |`
+      );
+    }
+    lines.push('');
+  }
+
+  // Patterns
+  if (result.patterns.total > 0) {
+    lines.push('## Pattern Analysis');
+    lines.push('');
+    lines.push('| Pattern | Fix Count | Tracer Available |');
+    lines.push('|---------|-----------|------------------|');
+
+    for (const [pattern, count] of Object.entries(result.patterns.categories)) {
+      const tracer = pattern !== 'OTHER' ? 'Yes' : 'No';
+      lines.push(`| ${pattern} | ${count} | ${tracer} |`);
+    }
+    lines.push('');
+    lines.push(
+      `**${result.patterns.tracerAvailable}%** of fix patterns have tracer tests available.`
+    );
+    lines.push('');
+  }
+
+  // Recommendations
+  lines.push('## Recommendations');
+  lines.push('');
+
+  if (result.metrics.reworkRatio.rating === 'low') {
+    lines.push('- High rework ratio detected. Consider running tracer tests before implementation.');
+  }
+  if (result.metrics.trustPassRate.rating === 'low' || result.metrics.trustPassRate.rating === 'medium') {
+    lines.push('- Trust pass rate below target. Validate assumptions before coding.');
+  }
+  if (result.metrics.debugSpiralDuration.rating === 'low') {
+    lines.push('- Long debug spirals detected. Break work into smaller, verifiable steps.');
+  }
+  if (result.fixChains.length > 0) {
+    const patterns = result.fixChains
+      .filter((c) => c.pattern)
+      .map((c) => c.pattern);
+    if (patterns.length > 0) {
+      lines.push(`- Consider adding tracer tests for: ${[...new Set(patterns)].join(', ')}`);
+    }
+  }
+
+  if (lines[lines.length - 1] === '') {
+    lines.push('- All metrics healthy. Maintain current practices.');
+  }
+
+  lines.push('');
+  lines.push('---');
+  lines.push(`*Generated by vibe-check on ${format(new Date(), 'yyyy-MM-dd HH:mm')}*`);
+
+  return lines.join('\n');
+}

package/src/output/terminal.ts

@@ -0,0 +1,109 @@
+import chalk from 'chalk';
+import { VibeCheckResult, Rating, OverallRating } from '../types';
+import { format } from 'date-fns';
+
+export function formatTerminal(result: VibeCheckResult): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push('');
+  lines.push(chalk.bold.cyan('=' .repeat(64)));
+  lines.push(chalk.bold.cyan('                    VIBE-CHECK RESULTS'));
+  lines.push(chalk.bold.cyan('=' .repeat(64)));
+
+  // Period info
+  const fromStr = format(result.period.from, 'MMM d, yyyy');
+  const toStr = format(result.period.to, 'MMM d, yyyy');
+  lines.push('');
+  lines.push(
+    chalk.gray(`  Period: ${fromStr} - ${toStr} (${result.period.activeHours}h active)`)
+  );
+  lines.push(
+    chalk.gray(
+      `  Commits: ${result.commits.total} total (${result.commits.feat} feat, ${result.commits.fix} fix, ${result.commits.docs} docs, ${result.commits.other} other)`
+    )
+  );
+
+  // Metrics table
+  lines.push('');
+  lines.push(chalk.bold.white('  METRIC                      VALUE      RATING'));
+  lines.push(chalk.gray('  ' + '-'.repeat(50)));
+
+  const metrics = [
+    { name: 'Iteration Velocity', metric: result.metrics.iterationVelocity },
+    { name: 'Rework Ratio', metric: result.metrics.reworkRatio },
+    { name: 'Trust Pass Rate', metric: result.metrics.trustPassRate },
+    { name: 'Debug Spiral Duration', metric: result.metrics.debugSpiralDuration },
+    { name: 'Flow Efficiency', metric: result.metrics.flowEfficiency },
+  ];
+
+  for (const { name, metric } of metrics) {
+    const valueStr = `${metric.value}${metric.unit}`.padEnd(10);
+    const ratingStr = formatRating(metric.rating);
+    lines.push(`  ${name.padEnd(26)} ${valueStr} ${ratingStr}`);
+  }
+
+  // Overall rating
+  lines.push('');
+  lines.push(chalk.bold.cyan('-'.repeat(64)));
+  lines.push(`  ${chalk.bold('OVERALL:')} ${formatOverallRating(result.overall)}`);
+  lines.push(chalk.bold.cyan('-'.repeat(64)));
+
+  // Debug spirals
+  if (result.fixChains.length > 0) {
+    lines.push('');
+    lines.push(
+      chalk.bold.yellow(`  DEBUG SPIRALS (${result.fixChains.length} detected):`)
+    );
+    for (const chain of result.fixChains) {
+      const patternStr = chain.pattern ? ` (${chain.pattern})` : '';
+      lines.push(
+        chalk.yellow(
+          `  - ${chain.component}: ${chain.commits} commits, ${chain.duration}m${patternStr}`
+        )
+      );
+    }
+  }
+
+  // Patterns
+  if (result.patterns.total > 0) {
+    lines.push('');
+    lines.push(chalk.bold.magenta('  PATTERNS:'));
+    for (const [pattern, count] of Object.entries(result.patterns.categories)) {
+      const tracerNote = pattern !== 'OTHER' ? ' (tracer available)' : '';
+      lines.push(chalk.magenta(`  - ${pattern}: ${count} fixes${tracerNote}`));
+    }
+  }
+
+  lines.push('');
+  lines.push(chalk.bold.cyan('=' .repeat(64)));
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function formatRating(rating: Rating): string {
+  switch (rating) {
+    case 'elite':
+      return chalk.green.bold('ELITE');
+    case 'high':
+      return chalk.blue.bold('HIGH');
+    case 'medium':
+      return chalk.yellow.bold('MEDIUM');
+    case 'low':
+      return chalk.red.bold('LOW');
+  }
+}
+
+function formatOverallRating(rating: OverallRating): string {
+  switch (rating) {
+    case 'ELITE':
+      return chalk.green.bold('ELITE');
+    case 'HIGH':
+      return chalk.blue.bold('HIGH');
+    case 'MEDIUM':
+      return chalk.yellow.bold('MEDIUM');
+    case 'LOW':
+      return chalk.red.bold('LOW');
+  }
+}

package/src/types.ts

@@ -0,0 +1,68 @@
+export type Rating = 'elite' | 'high' | 'medium' | 'low';
+export type OutputFormat = 'terminal' | 'json' | 'markdown';
+export type OverallRating = 'ELITE' | 'HIGH' | 'MEDIUM' | 'LOW';
+
+export interface Commit {
+  hash: string;
+  date: Date;
+  message: string;
+  type: 'feat' | 'fix' | 'docs' | 'chore' | 'refactor' | 'test' | 'style' | 'other';
+  scope: string | null;
+  author: string;
+}
+
+export interface MetricResult {
+  value: number;
+  unit: string;
+  rating: Rating;
+  description: string;
+}
+
+export interface FixChain {
+  component: string;
+  commits: number;
+  duration: number; // minutes
+  isSpiral: boolean;
+  pattern: string | null;
+  firstCommit: Date;
+  lastCommit: Date;
+}
+
+export interface PatternSummary {
+  categories: Record<string, number>;
+  total: number;
+  tracerAvailable: number;
+}
+
+export interface VibeCheckResult {
+  period: {
+    from: Date;
+    to: Date;
+    activeHours: number;
+  };
+  commits: {
+    total: number;
+    feat: number;
+    fix: number;
+    docs: number;
+    other: number;
+  };
+  metrics: {
+    iterationVelocity: MetricResult;
+    reworkRatio: MetricResult;
+    trustPassRate: MetricResult;
+    debugSpiralDuration: MetricResult;
+    flowEfficiency: MetricResult;
+  };
+  fixChains: FixChain[];
+  patterns: PatternSummary;
+  overall: OverallRating;
+}
+
+export interface CliOptions {
+  since?: string;
+  until?: string;
+  format: OutputFormat;
+  repo: string;
+  verbose: boolean;
+}