@vibecheckai/cli 3.5.0 → 3.5.1

package/mcp-server/lib/ids.ts

@@ -0,0 +1,238 @@
+/**
+ * Deterministic ID Generation
+ * 
+ * Produces stable, reproducible IDs for findings and other entities.
+ * Uses SHA256 for cryptographic stability - same inputs always produce same outputs.
+ * 
+ * CRITICAL: Agents must not thrash. IDs must be deterministic.
+ */
+
+import { createHash } from 'crypto';
+
+/**
+ * Evidence location for ID generation
+ */
+export interface EvidenceLocation {
+  path?: string;
+  lineStart?: number;
+  lineEnd?: number;
+  message?: string;
+}
+
+/**
+ * Generate a deterministic finding ID
+ * 
+ * Formula: sha256(rule_id + path + lineStart + message) truncated to 8 hex chars
+ * This ensures:
+ * - Same finding always gets same ID across runs
+ * - Different findings get different IDs
+ * - IDs are short but collision-resistant
+ */
+export function generateFindingId(
+  ruleId: string,
+  evidence: EvidenceLocation
+): string {
+  const category = ruleId.split('.')[0] || ruleId;
+  const input = [
+    ruleId,
+    evidence.path || '',
+    String(evidence.lineStart || 0),
+    evidence.message || '',
+  ].join(':');
+  
+  const hash = createHash('sha256').update(input).digest('hex');
+  return `${normalizeCategory(category)}-${hash.substring(0, 8)}`;
+}
+
+/**
+ * Normalize category to lowercase snake_case
+ */
+function normalizeCategory(category: string): string {
+  return category
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+}
+
+/**
+ * Generate a deterministic cache key
+ * 
+ * Includes: tool name, vibecheck version, schema version, project fingerprint
+ */
+export function generateCacheKey(
+  tool: string,
+  projectFingerprint: string,
+  options?: Record<string, unknown>,
+  schemaVersion = '1.0.0'
+): string {
+  const optionsHash = options
+    ? createHash('md5')
+        .update(JSON.stringify(sortObject(options)))
+        .digest('hex')
+        .substring(0, 8)
+    : 'default';
+  
+  return `${tool}:${schemaVersion}:${projectFingerprint}:${optionsHash}`;
+}
+
+/**
+ * Generate a deterministic request ID
+ * 
+ * For tracing - includes timestamp component for ordering
+ */
+export function generateRequestId(prefix = 'req'): string {
+  const timestamp = Date.now().toString(36);
+  const random = createHash('md5')
+    .update(`${timestamp}:${Math.random()}`)
+    .digest('hex')
+    .substring(0, 8);
+  return `${prefix}_${timestamp}_${random}`;
+}
+
+/**
+ * Generate a deterministic run ID
+ * 
+ * For correlating multiple findings from the same analysis run
+ */
+export function generateRunId(): string {
+  const timestamp = new Date().toISOString().replace(/[-:T.Z]/g, '');
+  const random = createHash('md5')
+    .update(`${timestamp}:${process.hrtime.bigint()}`)
+    .digest('hex')
+    .substring(0, 8);
+  return `run_${timestamp.substring(0, 14)}_${random}`;
+}
+
+/**
+ * Generate project fingerprint from key files
+ * 
+ * Hashes: vibecheck config + lockfiles + manifests
+ */
+export function generateProjectFingerprint(
+  files: Array<{ path: string; content: string | Buffer }>
+): string {
+  const hash = createHash('sha256');
+  
+  // Sort files for determinism
+  const sorted = [...files].sort((a, b) => a.path.localeCompare(b.path));
+  
+  for (const file of sorted) {
+    hash.update(file.path);
+    hash.update(':');
+    hash.update(file.content);
+    hash.update('\n');
+  }
+  
+  return hash.digest('hex').substring(0, 16);
+}
+
+/**
+ * Sort object keys recursively for deterministic serialization
+ */
+function sortObject(obj: unknown): unknown {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+  
+  if (Array.isArray(obj)) {
+    return obj.map(sortObject);
+  }
+  
+  const sorted: Record<string, unknown> = {};
+  const keys = Object.keys(obj as Record<string, unknown>).sort();
+  
+  for (const key of keys) {
+    sorted[key] = sortObject((obj as Record<string, unknown>)[key]);
+  }
+  
+  return sorted;
+}
+
+/**
+ * Validate a finding ID format
+ */
+export function isValidFindingId(id: string): boolean {
+  return /^[a-z_]+-[a-f0-9]{8}$/.test(id);
+}
+
+/**
+ * Parse a finding ID into components
+ */
+export function parseFindingId(id: string): { category: string; hash: string } | null {
+  const match = id.match(/^([a-z_]+)-([a-f0-9]{8})$/);
+  if (!match) return null;
+  return { category: match[1], hash: match[2] };
+}
+
+/**
+ * Severity order for deterministic sorting
+ * CRITICAL > HIGH > MEDIUM > LOW > INFO
+ */
+export const SEVERITY_ORDER: Record<string, number> = {
+  BLOCK: 0,
+  CRITICAL: 0,
+  HIGH: 1,
+  WARN: 2,
+  MEDIUM: 2,
+  LOW: 3,
+  INFO: 4,
+};
+
+/**
+ * Compare findings for deterministic sorting
+ * 
+ * Order: severity desc, rule_id asc, path asc, lineStart asc, message asc
+ */
+export function compareFindingsForSort(
+  a: { severity?: string; rule_id?: string; ruleId?: string; evidence?: Array<{ file?: string; line?: number }>; title?: string },
+  b: { severity?: string; rule_id?: string; ruleId?: string; evidence?: Array<{ file?: string; line?: number }>; title?: string }
+): number {
+  // Severity (lower order = higher priority)
+  const severityA = SEVERITY_ORDER[a.severity || 'INFO'] ?? 4;
+  const severityB = SEVERITY_ORDER[b.severity || 'INFO'] ?? 4;
+  if (severityA !== severityB) return severityA - severityB;
+  
+  // Rule ID
+  const ruleA = a.rule_id || a.ruleId || '';
+  const ruleB = b.rule_id || b.ruleId || '';
+  const ruleCompare = ruleA.localeCompare(ruleB);
+  if (ruleCompare !== 0) return ruleCompare;
+  
+  // Path (first evidence)
+  const pathA = a.evidence?.[0]?.file || '';
+  const pathB = b.evidence?.[0]?.file || '';
+  const pathCompare = pathA.localeCompare(pathB);
+  if (pathCompare !== 0) return pathCompare;
+  
+  // Line
+  const lineA = a.evidence?.[0]?.line || 0;
+  const lineB = b.evidence?.[0]?.line || 0;
+  if (lineA !== lineB) return lineA - lineB;
+  
+  // Message/title
+  const titleA = a.title || '';
+  const titleB = b.title || '';
+  return titleA.localeCompare(titleB);
+}
+
+/**
+ * Sort findings deterministically
+ */
+export function sortFindings<T extends { severity?: string; rule_id?: string; ruleId?: string; evidence?: Array<{ file?: string; line?: number }>; title?: string }>(
+  findings: T[]
+): T[] {
+  return [...findings].sort(compareFindingsForSort);
+}
+
+export default {
+  generateFindingId,
+  generateCacheKey,
+  generateRequestId,
+  generateRunId,
+  generateProjectFingerprint,
+  isValidFindingId,
+  parseFindingId,
+  compareFindingsForSort,
+  sortFindings,
+  SEVERITY_ORDER,
+};

package/mcp-server/lib/logger.ts

@@ -0,0 +1,368 @@
+/**
+ * Structured Logging & Metrics
+ * 
+ * Provides:
+ * - Structured JSON logs
+ * - Request tracing with IDs
+ * - Span-based timing
+ * - Metrics collection
+ */
+
+import { randomUUID } from 'crypto';
+import { appendFileSync, mkdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+
+/**
+ * Log levels
+ */
+export enum LogLevel {
+  DEBUG = 'debug',
+  INFO = 'info',
+  WARN = 'warn',
+  ERROR = 'error',
+}
+
+/**
+ * Log entry structure
+ */
+export interface LogEntry {
+  timestamp: string;
+  level: LogLevel;
+  message: string;
+  requestId?: string;
+  spanId?: string;
+  tool?: string;
+  durationMs?: number;
+  data?: Record<string, unknown>;
+  error?: {
+    code: string;
+    message: string;
+    stack?: string;
+  };
+}
+
+/**
+ * Span for timing operations
+ */
+export interface Span {
+  id: string;
+  name: string;
+  startTime: number;
+  endTime?: number;
+  status?: 'ok' | 'error';
+  attributes?: Record<string, unknown>;
+  events?: Array<{ name: string; timestamp: number; attributes?: Record<string, unknown> }>;
+}
+
+/**
+ * Metrics entry
+ */
+export interface MetricEntry {
+  name: string;
+  value: number;
+  unit: 'ms' | 'count' | 'bytes' | 'percent';
+  timestamp: number;
+  tags?: Record<string, string>;
+}
+
+/**
+ * Logger configuration
+ */
+export interface LoggerConfig {
+  level?: LogLevel;
+  outputDir?: string;
+  enableConsole?: boolean;
+  enableFile?: boolean;
+  enableMetrics?: boolean;
+  redactSensitive?: boolean;
+}
+
+/**
+ * Main logger class
+ */
+export class VibecheckLogger {
+  private config: Required<LoggerConfig>;
+  private requestId?: string;
+  private spans: Map<string, Span> = new Map();
+  private metrics: MetricEntry[] = [];
+
+  constructor(config: LoggerConfig = {}) {
+    this.config = {
+      level: config.level ?? LogLevel.INFO,
+      outputDir: config.outputDir ?? '.vibecheck/logs',
+      enableConsole: config.enableConsole ?? true,
+      enableFile: config.enableFile ?? false,
+      enableMetrics: config.enableMetrics ?? true,
+      redactSensitive: config.redactSensitive ?? true,
+    };
+  }
+
+  /**
+   * Set request ID for tracing
+   */
+  setRequestId(id: string): void {
+    this.requestId = id;
+  }
+
+  /**
+   * Create child logger with request context
+   */
+  child(context: { requestId?: string; tool?: string }): VibecheckLogger {
+    const child = new VibecheckLogger(this.config);
+    child.requestId = context.requestId ?? this.requestId;
+    return child;
+  }
+
+  /**
+   * Log methods
+   */
+  debug(message: string, data?: Record<string, unknown>): void {
+    this.log(LogLevel.DEBUG, message, data);
+  }
+
+  info(message: string, data?: Record<string, unknown>): void {
+    this.log(LogLevel.INFO, message, data);
+  }
+
+  warn(message: string, data?: Record<string, unknown>): void {
+    this.log(LogLevel.WARN, message, data);
+  }
+
+  error(message: string, error?: Error | Record<string, unknown>): void {
+    const errorData = error instanceof Error
+      ? { code: error.name, message: error.message, stack: error.stack }
+      : error;
+    this.log(LogLevel.ERROR, message, undefined, errorData as { code: string; message: string; stack?: string });
+  }
+
+  /**
+   * Core log method
+   */
+  private log(
+    level: LogLevel,
+    message: string,
+    data?: Record<string, unknown>,
+    error?: { code: string; message: string; stack?: string }
+  ): void {
+    // Check level
+    const levels = [LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARN, LogLevel.ERROR];
+    if (levels.indexOf(level) < levels.indexOf(this.config.level)) {
+      return;
+    }
+
+    const entry: LogEntry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      requestId: this.requestId,
+      data: this.config.redactSensitive && data ? this.redact(data) : data,
+      error,
+    };
+
+    // Output to console
+    if (this.config.enableConsole) {
+      this.writeConsole(entry);
+    }
+
+    // Output to file
+    if (this.config.enableFile) {
+      this.writeFile(entry);
+    }
+  }
+
+  /**
+   * Write to console (structured JSON on stderr)
+   */
+  private writeConsole(entry: LogEntry): void {
+    const line = JSON.stringify(entry);
+    console.error(line);
+  }
+
+  /**
+   * Write to file
+   */
+  private writeFile(entry: LogEntry): void {
+    const logDir = this.config.outputDir;
+    if (!existsSync(logDir)) {
+      mkdirSync(logDir, { recursive: true });
+    }
+
+    const date = new Date().toISOString().split('T')[0];
+    const logFile = join(logDir, `vibecheck-${date}.jsonl`);
+    
+    try {
+      appendFileSync(logFile, JSON.stringify(entry) + '\n');
+    } catch {
+      // Ignore write errors
+    }
+  }
+
+  /**
+   * Redact sensitive data
+   */
+  private redact(data: Record<string, unknown>): Record<string, unknown> {
+    const sensitiveKeys = ['password', 'secret', 'token', 'key', 'auth', 'credential', 'apiKey'];
+    const result: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(data)) {
+      if (sensitiveKeys.some(s => key.toLowerCase().includes(s))) {
+        result[key] = '[REDACTED]';
+      } else if (typeof value === 'object' && value !== null) {
+        result[key] = this.redact(value as Record<string, unknown>);
+      } else {
+        result[key] = value;
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Start a span for timing
+   */
+  startSpan(name: string, attributes?: Record<string, unknown>): string {
+    const id = randomUUID().substring(0, 8);
+    const span: Span = {
+      id,
+      name,
+      startTime: Date.now(),
+      attributes,
+      events: [],
+    };
+    this.spans.set(id, span);
+    
+    this.debug(`Span started: ${name}`, { spanId: id, ...attributes });
+    return id;
+  }
+
+  /**
+   * Add event to span
+   */
+  addSpanEvent(spanId: string, name: string, attributes?: Record<string, unknown>): void {
+    const span = this.spans.get(spanId);
+    if (span) {
+      span.events?.push({ name, timestamp: Date.now(), attributes });
+    }
+  }
+
+  /**
+   * End a span
+   */
+  endSpan(spanId: string, status: 'ok' | 'error' = 'ok'): Span | undefined {
+    const span = this.spans.get(spanId);
+    if (span) {
+      span.endTime = Date.now();
+      span.status = status;
+      const durationMs = span.endTime - span.startTime;
+      
+      this.info(`Span ended: ${span.name}`, {
+        spanId,
+        durationMs,
+        status,
+      });
+
+      // Record as metric
+      if (this.config.enableMetrics) {
+        this.recordMetric(`span.${span.name}.duration`, durationMs, 'ms', {
+          status,
+        });
+      }
+
+      this.spans.delete(spanId);
+      return span;
+    }
+    return undefined;
+  }
+
+  /**
+   * Record a metric
+   */
+  recordMetric(
+    name: string,
+    value: number,
+    unit: 'ms' | 'count' | 'bytes' | 'percent',
+    tags?: Record<string, string>
+  ): void {
+    if (!this.config.enableMetrics) return;
+
+    const metric: MetricEntry = {
+      name,
+      value,
+      unit,
+      timestamp: Date.now(),
+      tags,
+    };
+
+    this.metrics.push(metric);
+
+    // Log metric
+    this.debug(`Metric: ${name}=${value}${unit}`, { tags });
+  }
+
+  /**
+   * Get collected metrics
+   */
+  getMetrics(): MetricEntry[] {
+    return [...this.metrics];
+  }
+
+  /**
+   * Clear metrics
+   */
+  clearMetrics(): void {
+    this.metrics = [];
+  }
+
+  /**
+   * Flush metrics to output
+   */
+  flushMetrics(): void {
+    if (!this.config.enableFile || this.metrics.length === 0) return;
+
+    const logDir = this.config.outputDir;
+    if (!existsSync(logDir)) {
+      mkdirSync(logDir, { recursive: true });
+    }
+
+    const date = new Date().toISOString().split('T')[0];
+    const metricsFile = join(logDir, `metrics-${date}.jsonl`);
+
+    try {
+      const lines = this.metrics.map(m => JSON.stringify(m)).join('\n') + '\n';
+      appendFileSync(metricsFile, lines);
+      this.metrics = [];
+    } catch {
+      // Ignore write errors
+    }
+  }
+}
+
+// Singleton logger
+let globalLogger: VibecheckLogger | null = null;
+
+export function getLogger(): VibecheckLogger {
+  if (!globalLogger) {
+    globalLogger = new VibecheckLogger();
+  }
+  return globalLogger;
+}
+
+export function initLogger(config: LoggerConfig): void {
+  globalLogger = new VibecheckLogger(config);
+}
+
+/**
+ * Convenience function for creating request-scoped logger
+ */
+export function createRequestLogger(requestId?: string): VibecheckLogger {
+  const logger = getLogger().child({ requestId: requestId ?? randomUUID() });
+  return logger;
+}
+
+export default {
+  LogLevel,
+  VibecheckLogger,
+  getLogger,
+  initLogger,
+  createRequestLogger,
+};