codeproof 1.0.0

package/core/safetyGuards.js

@@ -0,0 +1,51 @@
+// Centralized safety controls. These helpers must stay dependency-light.
+// They enforce fail-open behavior without coupling to specific subsystems.
+
+let warnedExperimental = false;
+
+export function warnExperimentalOnce(message, logWarn) {
+  if (warnedExperimental) {
+    return;
+  }
+  warnedExperimental = true;
+  logWarn(message);
+}
+
+export function reportFeatureDisabled(name, verbose, logInfo) {
+  if (!verbose) {
+    return;
+  }
+  logInfo(`${name} disabled by feature flag.`);
+}
+
+export function withFailOpenReporting(action, onError) {
+  try {
+    return action();
+  } catch {
+    if (onError) {
+      onError();
+    }
+    return null;
+  }
+}
+
+export function withFailOpenIntegration(action) {
+  try {
+    action();
+  } catch {
+    // Integration failures are ignored to avoid affecting commits.
+  }
+}
+
+export function withFailOpenAiEscalation(enabled, action) {
+  if (!enabled) {
+    return [];
+  }
+
+  try {
+    return action();
+  } catch {
+    // AI failures downgrade to warnings by returning no decisions.
+    return [];
+  }
+}

package/engine/aiAnalyzer.js

@@ -0,0 +1,51 @@
+// AI contextual analysis layer. Only low-confidence findings reach this stage.
+// Regex-first keeps the fast baseline deterministic; AI is a cautious fallback.
+
+function callModel(payload) {
+  void payload;
+  // Stubbed: No provider hardcoded. Return null to trigger safe fallback.
+  return null;
+}
+
+function fallbackDecision(finding) {
+  return {
+    findingId: finding.findingId,
+    verdict: "warn",
+    confidence: 0.35,
+    explanation: "AI unavailable; defaulting to warn for manual review.",
+    suggestedFix: "Review the value and move secrets to environment variables."
+  };
+}
+
+export function analyze(findings, projectContext) {
+  const payload = {
+    version: 1,
+    projectContext,
+    findings: findings.map((finding) => ({
+      findingId: finding.findingId,
+      ruleId: finding.ruleId,
+      filePath: finding.filePath,
+      fileType: finding.fileType,
+      isTestLike: finding.isTestLike,
+      snippet: finding.snippet
+    }))
+  };
+
+  const response = callModel(payload);
+
+  if (!response || !Array.isArray(response.decisions)) {
+    return findings.map(fallbackDecision);
+  }
+
+  return response.decisions.map((decision) => ({
+    findingId: decision.findingId,
+    verdict: decision.verdict || "warn",
+    confidence: typeof decision.confidence === "number" ? decision.confidence : 0.5,
+    explanation: decision.explanation || "AI decision provided.",
+    suggestedFix: decision.suggestedFix
+  }));
+}
+
+
+
+

package/engine/aiEscalation.js

@@ -0,0 +1,6 @@
+// Stub interface for future AI contextual review.
+// This keeps the AI boundary clear and avoids network calls at this stage.
+export function aiReview(findings, context) {
+  void context;
+  return findings;
+}

package/engine/contextBuilder.js

@@ -0,0 +1,65 @@
+import fs from "fs";
+import path from "path";
+
+const TEST_PATH_HINTS = [
+  "test",
+  "tests",
+  "__tests__",
+  "spec",
+  "example",
+  "examples",
+  "sample",
+  "samples",
+  "mock",
+  "mocks"
+];
+
+function isTestLike(filePath) {
+  const normalized = filePath.toLowerCase();
+  return TEST_PATH_HINTS.some((hint) => normalized.includes(path.sep + hint));
+}
+
+function getFileType(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return ext ? ext.slice(1) : "unknown";
+}
+
+function getSnippetAroundLine(content, lineNumber, padding = 2, maxChars = 800) {
+  const lines = content.split("\n");
+  const start = Math.max(0, lineNumber - 1 - padding);
+  const end = Math.min(lines.length, lineNumber + padding);
+  const snippet = lines.slice(start, end).join("\n");
+  return snippet.length > maxChars ? snippet.slice(0, maxChars) + "..." : snippet;
+}
+
+export function buildProjectContext({ gitRoot, config }) {
+  return {
+    projectType: config?.projectType || "Unknown",
+    scanMode: config?.scanMode || "staged"
+  };
+}
+
+export function buildAiInputs(findings, projectContext) {
+  return findings.map((finding) => {
+    let content = "";
+    try {
+      content = fs.readFileSync(finding.filePath, "utf8");
+    } catch {
+      content = "";
+    }
+
+    const snippet = content
+      ? getSnippetAroundLine(content, finding.line || 1)
+      : finding.snippet || "";
+
+    return {
+      findingId: finding.findingId,
+      ruleId: finding.ruleId,
+      filePath: finding.filePath,
+      fileType: getFileType(finding.filePath),
+      isTestLike: isTestLike(finding.filePath),
+      snippet,
+      projectContext
+    };
+  });
+}

package/engine/decisionMerger.js

@@ -0,0 +1,30 @@
+// Combine baseline results with AI decisions without overriding blocks.
+
+export function mergeDecisions({ baselineFindings, aiDecisions }) {
+  const blockFindings = baselineFindings.filter(
+    (finding) => finding.severity === "block" && finding.confidence === "high"
+  );
+  const warnFindings = baselineFindings.filter(
+    (finding) => finding.severity === "warn"
+  );
+
+  const aiById = new Map(aiDecisions.map((decision) => [decision.findingId, decision]));
+  const aiReviewed = baselineFindings
+    .filter((finding) => finding.confidence === "low")
+    .map((finding) => ({
+      finding,
+      decision: aiById.get(finding.findingId)
+    }))
+    .filter((entry) => entry.decision);
+
+  const aiBlocks = aiReviewed.filter((entry) => entry.decision.verdict === "block");
+
+  const exitCode = blockFindings.length > 0 || aiBlocks.length > 0 ? 1 : 0;
+
+  return {
+    blockFindings,
+    warnFindings,
+    aiReviewed,
+    exitCode
+  };
+}

package/engine/ruleEngine.js

@@ -0,0 +1,52 @@
+import fs from "fs";
+import { buildLineIndex } from "../rules/ruleUtils.js";
+import { evaluateSecretRule } from "../rules/secretRule.js";
+import { evaluateDangerousUsageRule } from "../rules/dangerousUsageRule.js";
+import { evaluateInsecureConfigRule } from "../rules/insecureConfigRule.js";
+
+// Boundary: rule engine must never import reporting, integration, or remediation.
+// Rationale: regex-first keeps scans fast and deterministic; AI is a cautious fallback.
+
+// The engine aggregates deterministic regex rules and prepares low-confidence items
+// for AI escalation. This keeps the baseline fast and predictable.
+export function runRuleEngine({ files }) {
+  const findings = [];
+  const escalations = [];
+  let counter = 0;
+
+  for (const filePath of files) {
+    let content = "";
+    try {
+      content = fs.readFileSync(filePath, "utf8");
+    } catch {
+      continue;
+    }
+
+    const lineStarts = buildLineIndex(content);
+
+    const secretResult = evaluateSecretRule({ content, filePath, lineStarts });
+    findings.push(...secretResult.findings.map((finding) => ({
+      ...finding,
+      findingId: `f-${counter++}`
+    })));
+    escalations.push(...secretResult.escalations.map((finding) => ({
+      ...finding,
+      findingId: `f-${counter++}`
+    })));
+
+    findings.push(
+      ...evaluateDangerousUsageRule({ content, filePath, lineStarts }).map((finding) => ({
+        ...finding,
+        findingId: `f-${counter++}`
+      }))
+    );
+    findings.push(
+      ...evaluateInsecureConfigRule({ content, filePath, lineStarts }).map((finding) => ({
+        ...finding,
+        findingId: `f-${counter++}`
+      }))
+    );
+  }
+
+  return { findings, escalations };
+}

package/hooks/preCommit.js

@@ -0,0 +1,67 @@
+import fs from "fs";
+import path from "path";
+import { logInfo, logWarn } from "../utils/logger.js";
+
+const HOOK_MARKER = "# CodeProof pre-commit hook";
+
+function getHookPath(gitRoot) {
+  return path.join(gitRoot, ".git", "hooks", "pre-commit");
+}
+
+function getHookBlock() {
+  return [
+    "",
+    HOOK_MARKER,
+    "codeproof run",
+    "RESULT=$?",
+    "if [ $RESULT -ne 0 ]; then",
+    "  echo \"CodeProof checks failed. Commit blocked.\"",
+    "  exit $RESULT",
+    "fi",
+    ""
+  ].join("\n");
+}
+
+export function installPreCommitHook(gitRoot) {
+  const hookPath = getHookPath(gitRoot);
+  const hookDir = path.dirname(hookPath);
+
+  if (!fs.existsSync(hookDir)) {
+    fs.mkdirSync(hookDir, { recursive: true });
+  }
+
+  if (!fs.existsSync(hookPath)) {
+    // Use a POSIX shell hook for cross-platform Git compatibility (Git Bash on Windows).
+    const content = [
+      "#!/bin/sh",
+      "", 
+      "# Auto-generated by CodeProof",
+      "codeproof run",
+      "RESULT=$?",
+      "if [ $RESULT -ne 0 ]; then",
+      "  echo \"CodeProof checks failed. Commit blocked.\"",
+      "  exit $RESULT",
+      "fi",
+      ""
+    ].join("\n");
+    fs.writeFileSync(hookPath, content, "utf8");
+    logInfo("Created new pre-commit hook.");
+  } else {
+    const existing = fs.readFileSync(hookPath, "utf8");
+    if (existing.includes("codeproof run") || existing.includes(HOOK_MARKER)) {
+      logWarn("Pre-commit hook already references CodeProof. Skipping append.");
+    } else {
+      // Append instead of overwrite to avoid breaking existing hook logic.
+      fs.appendFileSync(hookPath, getHookBlock(), "utf8");
+      logInfo("Appended CodeProof to existing pre-commit hook.");
+    }
+  }
+
+  try {
+    fs.chmodSync(hookPath, 0o755);
+  } catch {
+    // Best-effort: Windows may not honor chmod, but Git still runs hooks.
+  }
+}
+
+

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "codeproof",
+  "version": "1.0.0",
+  "description": "CodeProof CLI",
+  "type": "module",
+  "bin": {
+    "codeproof": "./bin/codeproof.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/reporting/reportBuilder.js

@@ -0,0 +1,100 @@
+import path from "path";
+
+// Boundary: reporting only. Must not import rule logic or AI logic.
+// Reports are built from provided inputs to keep dependencies one-directional.
+
+function toRelativePath(projectRoot, filePath) {
+  if (!filePath) {
+    return "";
+  }
+  const relative = path.relative(projectRoot, filePath);
+  return relative || filePath;
+}
+
+function trimSnippet(snippet, maxLength = 200) {
+  if (!snippet) {
+    return "";
+  }
+  const trimmed = String(snippet).trim();
+  if (trimmed.length <= maxLength) {
+    return trimmed;
+  }
+  return trimmed.slice(0, maxLength) + "...";
+}
+
+function redactSecretSnippet(ruleId, snippet) {
+  if (!snippet) {
+    return "";
+  }
+  if (String(ruleId || "").startsWith("secret.")) {
+    return "***";
+  }
+  return snippet;
+}
+
+function mapDecisionConfidence(value) {
+  if (typeof value !== "number") {
+    return "low";
+  }
+  return value >= 0.75 ? "high" : "low";
+}
+
+function normalizeSeverity(value) {
+  return value === "block" ? "block" : "warn";
+}
+
+export function buildReport({
+  projectRoot,
+  scanMode,
+  filesScannedCount,
+  baselineFindings,
+  aiReviewed,
+  runId,
+  timestamp
+}) {
+  const aiById = new Map(aiReviewed.map((entry) => [entry.finding.findingId, entry.decision]));
+
+  const findings = baselineFindings.map((finding) => {
+    const decision = aiById.get(finding.findingId);
+    const severity = normalizeSeverity(decision ? decision.verdict : finding.severity);
+    const confidence = decision
+      ? mapDecisionConfidence(decision.confidence)
+      : finding.confidence === "high"
+        ? "high"
+        : "low";
+
+    return {
+      ruleId: finding.ruleId,
+      severity,
+      confidence,
+      filePath: toRelativePath(projectRoot, finding.filePath),
+      lineNumber: finding.line || null,
+      codeSnippet: trimSnippet(redactSecretSnippet(finding.ruleId, finding.snippet)),
+      explanation: decision?.explanation || finding.message || ""
+    };
+  });
+
+  const blocksCount = findings.filter((finding) => finding.severity === "block").length;
+  const warningsCount = findings.filter((finding) => finding.severity === "warn").length;
+
+  const finalVerdict = blocksCount > 0
+    ? "blocked"
+    : warningsCount > 0
+      ? "allowed_with_warnings"
+      : "allowed";
+
+  return {
+    runId,
+    timestamp,
+    projectRoot,
+    scanMode,
+    summary: {
+      totalFilesScanned: filesScannedCount,
+      totalFindings: findings.length,
+      blocksCount,
+      warningsCount
+    },
+    findings,
+    finalVerdict
+  };
+}

package/reporting/reportWriter.js

@@ -0,0 +1,19 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+// Boundary: reporting storage only. Must not import rule logic, AI logic, or integrations.
+
+export function appendReport({ projectRoot, report }) {
+  const reportPath = path.join(projectRoot, "codeproof-report.log");
+  const line = JSON.stringify(report) + os.EOL;
+
+  // Append-only to preserve an immutable audit trail of every run.
+  const fileHandle = fs.openSync(reportPath, "a");
+  try {
+    fs.writeSync(fileHandle, line, null, "utf8");
+    fs.fsyncSync(fileHandle);
+  } finally {
+    fs.closeSync(fileHandle);
+  }
+}

package/rules/dangerousUsageRule.js

@@ -0,0 +1,11 @@
+import { dangerousUsagePatterns } from "./regexPatterns.js";
+import { extractFindings } from "./ruleUtils.js";
+
+export function evaluateDangerousUsageRule({ content, filePath, lineStarts }) {
+  return extractFindings({
+    patterns: dangerousUsagePatterns,
+    content,
+    filePath,
+    lineStarts
+  });
+}

package/rules/insecureConfigRule.js

@@ -0,0 +1,11 @@
+import { insecureConfigPatterns } from "./regexPatterns.js";
+import { extractFindings } from "./ruleUtils.js";
+
+export function evaluateInsecureConfigRule({ content, filePath, lineStarts }) {
+  return extractFindings({
+    patterns: insecureConfigPatterns,
+    content,
+    filePath,
+    lineStarts
+  });
+}

package/rules/regexPatterns.js

@@ -0,0 +1,53 @@
+// Centralized regex patterns for deterministic rules.
+// Regex-first keeps scans fast and predictable; AI is used only for ambiguous cases.
+
+export const secretPatterns = [
+  {
+    id: "secret.aws_access_key",
+    regex: /\b(AKIA|ASIA)[0-9A-Z]{16}\b/g,
+    severity: "block",
+    confidence: "high",
+    message: "Possible AWS access key detected."
+  },
+  {
+    id: "secret.generic_api_key",
+    regex: /\bapi[_-]?key\s*[:=]\s*['"][A-Za-z0-9\-_]{8,}['"]/gi,
+    severity: "block",
+    confidence: "low",
+    message: "Possible API key detected."
+  },
+  {
+    id: "secret.generic_token",
+    regex: /\b(token|password|secret)\s*[:=]\s*['"][^'"\n]{6,}['"]/gi,
+    severity: "block",
+    confidence: "low",
+    message: "Possible secret material detected."
+  }
+];
+
+export const dangerousUsagePatterns = [
+  {
+    id: "code.dangerous_eval",
+    regex: /\b(eval|exec)\s*\(/g,
+    severity: "warn",
+    confidence: "high",
+    message: "Dangerous function usage detected."
+  }
+];
+
+export const insecureConfigPatterns = [
+  {
+    id: "config.debug_true",
+    regex: /\bDEBUG\s*=\s*true\b/gi,
+    severity: "warn",
+    confidence: "high",
+    message: "Insecure DEBUG flag enabled."
+  },
+  {
+    id: "config.node_env_development",
+    regex: /\bNODE_ENV\s*=\s*development\b/gi,
+    severity: "warn",
+    confidence: "high",
+    message: "NODE_ENV set to development."
+  }
+];

package/rules/ruleUtils.js

@@ -0,0 +1,58 @@
+// Shared helpers for regex-based rule evaluation.
+
+export function buildLineIndex(content) {
+  const starts = [0];
+  for (let i = 0; i < content.length; i += 1) {
+    if (content[i] === "\n") {
+      starts.push(i + 1);
+    }
+  }
+  return starts;
+}
+
+function getLineInfo(content, index, lineStarts) {
+  let low = 0;
+  let high = lineStarts.length - 1;
+  let lineNumber = 1;
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    if (lineStarts[mid] <= index) {
+      lineNumber = mid + 1;
+      low = mid + 1;
+    } else {
+      high = mid - 1;
+    }
+  }
+
+  const lineStart = lineStarts[lineNumber - 1] ?? 0;
+  const lineEnd = content.indexOf("\n", lineStart);
+  const rawLine = content.slice(lineStart, lineEnd === -1 ? content.length : lineEnd);
+  const snippet = rawLine.trim().slice(0, 160);
+
+  return { lineNumber, snippet };
+}
+
+export function extractFindings({ patterns, content, filePath, lineStarts }) {
+  const findings = [];
+
+  for (const pattern of patterns) {
+    const regex = new RegExp(pattern.regex.source, pattern.regex.flags);
+    let match = regex.exec(content);
+    while (match) {
+      const { lineNumber, snippet } = getLineInfo(content, match.index, lineStarts);
+      findings.push({
+        ruleId: pattern.id,
+        severity: pattern.severity,
+        confidence: pattern.confidence,
+        message: pattern.message,
+        filePath,
+        line: lineNumber,
+        snippet: snippet || match[0]
+      });
+      match = regex.exec(content);
+    }
+  }
+
+  return findings;
+}

package/rules/secretRule.js

@@ -0,0 +1,21 @@
+import { secretPatterns } from "./regexPatterns.js";
+import { extractFindings } from "./ruleUtils.js";
+
+// Regex-first for secrets ensures fast, deterministic detection.
+// Low-confidence matches are escalated for future AI context review.
+export function evaluateSecretRule({ content, filePath, lineStarts }) {
+  const findings = extractFindings({ patterns: secretPatterns, content, filePath, lineStarts });
+
+  const highConfidence = [];
+  const lowConfidence = [];
+
+  for (const finding of findings) {
+    if (finding.confidence === "high") {
+      highConfidence.push(finding);
+    } else {
+      lowConfidence.push(finding);
+    }
+  }
+
+  return { findings: highConfidence, escalations: lowConfidence };
+}

package/ui/welcomeScreen.js

@@ -0,0 +1,42 @@
+function padRight(text, width) {
+  const safeText = text ?? "";
+  const padding = Math.max(0, width - safeText.length);
+  return safeText + " ".repeat(padding);
+}
+
+function buildBox(lines) {
+  const width = Math.max(...lines.map((line) => line.length), 0);
+  const top = "─".repeat(width + 4);
+  const bottom = "─".repeat(width + 4);
+  const body = lines.map((line) => `│ ${padRight(line, width)} │`);
+  return [top, ...body, bottom].join("\n");
+}
+
+export function buildWelcomeScreen({ projectType, scanMode, configPath }) {
+  // UX: use a clean box with minimal symbols so the message is readable and calm in any terminal.
+  const lines = [
+    "✓ CodeProof initialized successfully.",
+    "",
+    "What it does: Scans for secrets and risky patterns before you commit.",
+    "When it runs: On pre-commit, or when you run it manually.",
+    "Commit impact: Blocks commits only on high-confidence blockers.",
+    "",
+    `Project type: ${projectType}`,
+    `Scan mode: ${scanMode}`,
+    `Config file: ${configPath}`,
+    "",
+    "Commands:",
+    "→ codeproof run                Manually run checks",
+    "→ codeproof status             Show current configuration",
+    "→ codeproof report@dashboard   View reports (placeholder)",
+    "→ codeproof move-secret        Safely move detected secrets (experimental)"
+  ];
+
+  return buildBox(lines);
+}
+
+export function showWelcomeScreen(details) {
+  // UX: print once after init to reassure users without changing command behavior elsewhere.
+  const message = buildWelcomeScreen(details);
+  console.log(message);
+}