@vibecheckai/cli 3.5.1 → 3.5.2

package/bin/runners/lib/exit-codes.js

@@ -0,0 +1,275 @@
+/**
+ * Vibecheck CLI Exit Codes - Standardized for World-Class UX
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * EXIT CODE REFERENCE
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Standard Unix conventions extended for CLI tooling:
+ * 
+ * 0    SUCCESS         Command completed successfully, no issues found
+ * 1    WARNINGS        Command completed with warnings (non-blocking issues)
+ * 2    BLOCKING        Command found blocking issues (critical/high severity)
+ * 3    USER_ERROR      Invalid arguments, missing required flags, bad input
+ * 4    NOT_FOUND       Command not found, file not found, resource missing
+ * 5    AUTH_REQUIRED   Authentication required but not provided
+ * 6    AUTH_FAILED     Authentication failed (invalid/expired credentials)
+ * 7    TIER_REQUIRED   Feature requires higher subscription tier
+ * 8    RATE_LIMITED    API rate limit exceeded
+ * 9    NETWORK_ERROR   Network connectivity issue
+ * 10   INTERNAL_ERROR  Unexpected internal error
+ * 
+ * CI-Friendly: Exit codes 0-2 are "soft" (scan results), 3+ are "hard" (errors)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+
+"use strict";
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXIT CODE CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const EXIT = {
+  // Success states (0-2)
+  SUCCESS: 0,           // All good, no issues
+  WARNINGS: 1,          // Completed with warnings (medium/low severity)
+  BLOCKING: 2,          // Blocking issues found (critical/high severity)
+  
+  // User errors (3-4)
+  USER_ERROR: 3,        // Bad args, invalid input, usage error
+  NOT_FOUND: 4,         // Resource/command/file not found
+  
+  // Auth errors (5-7)
+  AUTH_REQUIRED: 5,     // Need to log in
+  AUTH_FAILED: 6,       // Bad credentials
+  TIER_REQUIRED: 7,     // Need higher plan
+  
+  // Transient errors (8-9)
+  RATE_LIMITED: 8,      // Try again later
+  NETWORK_ERROR: 9,     // Connectivity issue
+  
+  // Fatal errors (10+)
+  INTERNAL_ERROR: 10,   // Bug, unexpected error
+  
+  // Process signals (standard Unix)
+  SIGINT: 130,          // Ctrl+C
+  SIGTERM: 143,         // kill
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXIT CODE METADATA
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const EXIT_INFO = {
+  [EXIT.SUCCESS]: {
+    name: "SUCCESS",
+    description: "Command completed successfully",
+    ciStatus: "success",
+    recoverable: true,
+  },
+  [EXIT.WARNINGS]: {
+    name: "WARNINGS",
+    description: "Completed with warnings (non-blocking issues)",
+    ciStatus: "warning",
+    recoverable: true,
+  },
+  [EXIT.BLOCKING]: {
+    name: "BLOCKING",
+    description: "Blocking issues found (critical/high severity)",
+    ciStatus: "failure",
+    recoverable: true,
+  },
+  [EXIT.USER_ERROR]: {
+    name: "USER_ERROR",
+    description: "Invalid arguments or usage",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Check command usage with --help",
+  },
+  [EXIT.NOT_FOUND]: {
+    name: "NOT_FOUND",
+    description: "Resource not found",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Verify the path or resource exists",
+  },
+  [EXIT.AUTH_REQUIRED]: {
+    name: "AUTH_REQUIRED",
+    description: "Authentication required",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Run 'vibecheck login' to authenticate",
+  },
+  [EXIT.AUTH_FAILED]: {
+    name: "AUTH_FAILED",
+    description: "Authentication failed",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Check your API key or run 'vibecheck login' again",
+  },
+  [EXIT.TIER_REQUIRED]: {
+    name: "TIER_REQUIRED",
+    description: "Higher subscription tier required",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Upgrade at https://vibecheckai.dev/pricing",
+  },
+  [EXIT.RATE_LIMITED]: {
+    name: "RATE_LIMITED",
+    description: "Rate limit exceeded",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Wait a moment and try again",
+  },
+  [EXIT.NETWORK_ERROR]: {
+    name: "NETWORK_ERROR",
+    description: "Network connectivity issue",
+    ciStatus: "failure",
+    recoverable: true,
+    hint: "Check your internet connection or try --offline mode",
+  },
+  [EXIT.INTERNAL_ERROR]: {
+    name: "INTERNAL_ERROR",
+    description: "Unexpected internal error",
+    ciStatus: "failure",
+    recoverable: false,
+    hint: "Please report this issue at https://github.com/vibecheckai/vibecheck/issues",
+  },
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Convert verdict string to exit code
+ * @param {string} verdict - SHIP, WARN, BLOCK, PASS, FAIL
+ * @returns {number} exit code
+ */
+function verdictToExitCode(verdict) {
+  const v = String(verdict).toUpperCase();
+  if (v === "SHIP" || v === "PASS" || v === "SUCCESS" || v === "OK") {
+    return EXIT.SUCCESS;
+  }
+  if (v === "WARN" || v === "WARNING" || v === "WARNINGS") {
+    return EXIT.WARNINGS;
+  }
+  if (v === "BLOCK" || v === "FAIL" || v === "FAILURE" || v === "ERROR") {
+    return EXIT.BLOCKING;
+  }
+  return EXIT.WARNINGS; // Default to warnings for unknown
+}
+
+/**
+ * Convert exit code to verdict string
+ * @param {number} exitCode 
+ * @returns {string} verdict
+ */
+function exitCodeToVerdict(exitCode) {
+  switch (exitCode) {
+    case EXIT.SUCCESS: return "SHIP";
+    case EXIT.WARNINGS: return "WARN";
+    case EXIT.BLOCKING: return "BLOCK";
+    default: return "BLOCK";
+  }
+}
+
+/**
+ * Get exit info for an exit code
+ * @param {number} exitCode 
+ * @returns {object} exit info
+ */
+function getExitInfo(exitCode) {
+  return EXIT_INFO[exitCode] || EXIT_INFO[EXIT.INTERNAL_ERROR];
+}
+
+/**
+ * Check if exit code represents success (including warnings)
+ * @param {number} exitCode 
+ * @returns {boolean}
+ */
+function isSuccess(exitCode) {
+  return exitCode === EXIT.SUCCESS;
+}
+
+/**
+ * Check if exit code represents a "soft" failure (scan results, not errors)
+ * @param {number} exitCode 
+ * @returns {boolean}
+ */
+function isSoftFailure(exitCode) {
+  return exitCode === EXIT.WARNINGS || exitCode === EXIT.BLOCKING;
+}
+
+/**
+ * Check if exit code represents a "hard" failure (errors)
+ * @param {number} exitCode 
+ * @returns {boolean}
+ */
+function isHardFailure(exitCode) {
+  return exitCode >= EXIT.USER_ERROR;
+}
+
+/**
+ * Check if the error is recoverable (user can fix and retry)
+ * @param {number} exitCode 
+ * @returns {boolean}
+ */
+function isRecoverable(exitCode) {
+  const info = EXIT_INFO[exitCode];
+  return info ? info.recoverable : false;
+}
+
+/**
+ * Get hint message for exit code
+ * @param {number} exitCode 
+ * @returns {string|null}
+ */
+function getHint(exitCode) {
+  const info = EXIT_INFO[exitCode];
+  return info?.hint || null;
+}
+
+/**
+ * Get CI status for exit code
+ * @param {number} exitCode 
+ * @returns {string} "success" | "warning" | "failure"
+ */
+function getCIStatus(exitCode) {
+  const info = EXIT_INFO[exitCode];
+  return info?.ciStatus || "failure";
+}
+
+/**
+ * Create an error object with proper exit code
+ * @param {string} message 
+ * @param {number} exitCode 
+ * @param {object} details 
+ * @returns {Error}
+ */
+function createExitError(message, exitCode, details = {}) {
+  const error = new Error(message);
+  error.exitCode = exitCode;
+  error.exitInfo = getExitInfo(exitCode);
+  Object.assign(error, details);
+  return error;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  EXIT,
+  EXIT_INFO,
+  verdictToExitCode,
+  exitCodeToVerdict,
+  getExitInfo,
+  isSuccess,
+  isSoftFailure,
+  isHardFailure,
+  isRecoverable,
+  getHint,
+  getCIStatus,
+  createExitError,
+};

package/bin/runners/lib/finding-id.js

@@ -0,0 +1,69 @@
+/**
+ * Finding ID Generation - Stable, Deterministic IDs
+ * 
+ * Generates stable finding IDs that remain consistent across rescans.
+ * Same finding should get same ID for proper tracking and deduplication.
+ */
+
+const crypto = require('crypto');
+
+/**
+ * @typedef {Object} FindingInput
+ * @property {string} rule - Rule ID (e.g., 'SEC001')
+ * @property {string} file - File path
+ * @property {number} line - Line number
+ * @property {number} [column] - Column number (optional)
+ * @property {string} message - Finding message
+ */
+
+/**
+ * Generate stable, deterministic finding ID.
+ * Same finding on rescan should get same ID.
+ * 
+ * @param {FindingInput} finding - Finding input data
+ * @returns {string} Stable finding ID (format: vbc_<16-char-hex>)
+ */
+function generateFindingId(finding) {
+  const components = [
+    finding.rule || 'UNKNOWN',
+    finding.file || '',
+    String(finding.line || 0),
+    String(finding.column || 0),
+  ];
+  
+  const hash = crypto
+    .createHash('sha256')
+    .update(components.join(':'))
+    .digest('hex')
+    .slice(0, 16);
+  
+  return `vbc_${hash}`;
+}
+
+/**
+ * Generate deduplication key for finding.
+ * Used to detect duplicate findings across scans.
+ * 
+ * Note: Line number is excluded for fuzzy matching (same issue on different lines)
+ * 
+ * @param {FindingInput} finding - Finding input data
+ * @returns {string} Deduplication key (64-char hex)
+ */
+function generateDeduplicationKey(finding) {
+  const components = [
+    finding.rule || 'UNKNOWN',
+    finding.file || '',
+    // Line number excluded for fuzzy matching
+    (finding.message || '').slice(0, 100), // First 100 chars of message
+  ];
+  
+  return crypto
+    .createHash('sha256')
+    .update(components.join(':'))
+    .digest('hex');
+}
+
+module.exports = {
+  generateFindingId,
+  generateDeduplicationKey,
+};

package/bin/runners/lib/finding-sorter.js

@@ -0,0 +1,89 @@
+/**
+ * Finding Sorter - Deterministic Ordering
+ * 
+ * Sorts findings deterministically for stable output across runs.
+ * Order: severity DESC, file ASC, line ASC, rule ASC
+ */
+
+/**
+ * @typedef {Object} Finding
+ * @property {string} severity - critical, high, medium, low, info
+ * @property {string} file - File path
+ * @property {number} line - Line number
+ * @property {string} rule - Rule ID
+ * @property {string} [category] - Category
+ * @property {string} [title] - Title
+ */
+
+/**
+ * Severity order mapping (lower number = higher priority)
+ */
+const SEVERITY_ORDER = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+  info: 4,
+};
+
+/**
+ * Sort findings deterministically for stable output.
+ * Order: severity DESC, file ASC, line ASC, rule ASC
+ * 
+ * @param {Finding[]} findings - Array of findings to sort
+ * @returns {Finding[]} Sorted findings array
+ */
+function sortFindings(findings) {
+  return [...findings].sort((a, b) => {
+    // 1. Severity (critical first)
+    const sevA = SEVERITY_ORDER[a.severity?.toLowerCase()] ?? 5;
+    const sevB = SEVERITY_ORDER[b.severity?.toLowerCase()] ?? 5;
+    if (sevA !== sevB) return sevA - sevB;
+    
+    // 2. File path (alphabetical)
+    const fileA = (a.file || '').toLowerCase();
+    const fileB = (b.file || '').toLowerCase();
+    const fileCompare = fileA.localeCompare(fileB);
+    if (fileCompare !== 0) return fileCompare;
+    
+    // 3. Line number
+    const lineA = a.line || 0;
+    const lineB = b.line || 0;
+    if (lineA !== lineB) return lineA - lineB;
+    
+    // 4. Rule ID (alphabetical)
+    const ruleA = (a.rule || a.ruleId || '').toLowerCase();
+    const ruleB = (b.rule || b.ruleId || '').toLowerCase();
+    return ruleA.localeCompare(ruleB);
+  });
+}
+
+/**
+ * Generate stable JSON output (sorted keys, consistent spacing)
+ * 
+ * @param {unknown} obj - Object to stringify
+ * @returns {string} Stable JSON string
+ */
+function stableStringify(obj) {
+  if (typeof obj !== 'object' || obj === null) {
+    return JSON.stringify(obj);
+  }
+  
+  if (Array.isArray(obj)) {
+    return '[' + obj.map(stableStringify).join(',') + ']';
+  }
+  
+  // Sort keys for stable output
+  const sortedKeys = Object.keys(obj).sort();
+  const pairs = sortedKeys.map(key => {
+    const value = obj[key];
+    return JSON.stringify(key) + ':' + stableStringify(value);
+  });
+  
+  return '{' + pairs.join(',') + '}';
+}
+
+module.exports = {
+  sortFindings,
+  stableStringify,
+};