ProofCode

AI writes code. ProofCode proves the change.

Code Change Verification, Blast Radius Analysis & Deterministic Security Guardrails for Modern Development.

📖 Overview

AI coding agents (Cursor, GitHub Copilot, Claude Code, Devin, ChatGPT) can inspect codebases, generate hundreds of lines of code, and modify multiple files in seconds. Writing code is no longer the bottleneck — trusting the result before shipping is.

Real-world development teams using AI code constantly face:

Breaking Contract & Signature Drift: The AI fixes a bug in an exported helper, changes parameter counts or return types, and silently breaks downstream callers.
Compiles, But Silently Broken: Code passes tsc, but the AI omitted an await inside a conditional (if (checkAuth()) returning a Promise that is always truthy in JS), or directly mutated React state with .push(), causing silent production failures.
Phantom Hallucinations: The AI invents non-existent third-party package names, causing runtime Cannot find module crashes.
AI Cheating & Test Weakening: The AI secretly deletes or weakens test assertions to make failing suites pass instead of fixing the root cause.
Scope Creep & Over-Editing: The AI touches sensitive root configuration files (.env, package.json, tsconfig.json) outside its authorized scope.

ProofCode is the deterministic verification layer. It runs AST analysis, call graph dependency tracing, and automated guardrails on every Git diff before code ever reaches production.

⚡ Core Features

1. 💥 Blast Radius & Downstream Dependency Impact

ProofCode constructs a full Abstract Syntax Tree (AST) call graph of your TypeScript / JavaScript workspace and traces exactly which downstream functions, components, and API routes depend on the symbols modified in your Git diff.

Direct & Transitive Callers: Maps every file and function referencing changed code.
Untested Callers Alert: Flags whenever a modified function has downstream dependents with zero test coverage.
API Route Mapping: Detects when modified services touch Next.js App Router (route.ts) or Pages Router endpoints.

2. 🛡️ AI Reliability & Deterministic Risk Engine

ProofCode runs 15+ deterministic, zero-hallucination static rules with verifiable evidence traces:

Rule ID	Category	Name & What It Detects	Severity
`PC-BREAK-001`	Quality	Breaking Contract & Signature Drift: Parameter count shifts, incompatible argument types, or nullable return widening (`null \| undefined`) affecting downstream callers.	HIGH
`PC-REL-008`	Reliability	Unawaited Promise in Conditionals: Calling an async function without `await` inside `if (...)` or boolean checks (Promises are always truthy in JS, causing security bypasses).	HIGH
`PC-TYPE-001`	Quality	Unsafe Type Assertion Bypass: AI using `as any`, `<any>`, or `@ts-ignore` / `@ts-nocheck` to silence compiler errors instead of fixing interfaces.	MEDIUM / HIGH
`PC-IMPORT-001`	Reliability	Phantom / Hallucinated Package Imports: Modules imported that do not exist in `package.json`, preventing runtime resolution crashes.	HIGH
`PC-MUT-001`	Reliability	Direct State Mutation in React/Redux: Direct array/object mutations (`.push()`, `.splice()`) called on state or inside setter callbacks (`setX(prev => { prev.push() })`), breaking React reactivity.	HIGH
`PC-ENV-001`	Reliability	Unchecked Environment Variable Access: Forceful non-null assertions (`process.env.VAR!`) without fallback values or startup validation.	HIGH
`PC-DATA-002`	Security	Silent Security Field Drop: AI refactoring payload structures and inadvertently dropping critical fields (`tenantId`, `userId`, `updatedAt`).	HIGH
`PC-STUB-001`	Quality	Incomplete AI Stubs & Placeholders: Unimplemented stubs (`throw new Error("TODO")`, `Not implemented yet`) left behind in production code paths.	HIGH
`PC-REL-009`	Reliability	Silent Error Swallowing: Catch blocks that silently swallow exceptions without logging or re-throwing.	MEDIUM
`PC-TEST-001`	Quality	AI Test Weakening & Deletion Guard: Detecting when a Git diff deletes or weakens assertions in test suites.	HIGH
`PC-SCOPE-001`	Security	Scope Creep & Sensitive File Guard: Unauthorized modifications to sensitive root configs (`.env`, `package.json`, `tsconfig.json`).	HIGH
`PC-SEC-001`	Security	SQL Injection: Template literals or string concatenation in database query statements.	HIGH
`PC-AUTH-001`	Security	Missing Route Authorization: API route handlers accessing database resources without session authentication.	HIGH
`PC-DATA-001`	Reliability	Unhandled Database Nulls: Query results accessed directly without null guard checks or optional chaining.	MEDIUM
`PC-SEC-003`	Security	Path Traversal in File Operations: Unsanitized user inputs passed to file system functions without `path.basename()`.	HIGH
`PC-SEC-007`	Security	Permissive Wildcard CORS: `Access-Control-Allow-Origin: *` in authenticated APIs.	HIGH
`PC-REL-007`	Reliability	Regular Expression Denial of Service (ReDoS): Nested quantifiers in regular expressions.	HIGH

3. 🧪 Targeted Live Test Execution (<1s)

Autodetected Runners: Automatically detects Vitest, Jest, or Mocha in your project.
Smart Target Slicing: Runs only the test files directly linked to the modified symbols in your Git diff rather than waiting for the entire test suite.
Live Stack Trace Viewer: Clean ANSI-stripped error logs and expandable stack traces rendered directly in the dashboard.

4. 🪝 Automated Git Pre-Commit Hook

Prevent broken AI code from ever being committed:

# Install deterministic pre-commit hook (runs in <1s)
proofcode install-hook

# Uninstall whenever needed
proofcode uninstall-hook

If ProofCode detects critical risks or breaking contracts, the commit is blocked automatically with clear remediation instructions.

5. 🤖 One-Command CI/CD Setup (`proofcode init-ci`)

Drop automated GitHub Actions protection into any repository with one command:

proofcode init-ci

Installs .github/workflows/proofcode.yml.
Automatically analyzes every Pull Request.
Posts and updates an idempotent PR comment with the complete Markdown verification report.
Blocks merge if verification score drops below 75% or has high-severity risks (--strict).

6. 📊 Glassmorphic Verification Dashboard

Inspect full verification metrics in an interactive, dark-mode glassmorphic dashboard:

Radial Score Gauge: Visual score from 0% to 100% with instant status (READY TO SHIP, NEEDS REVIEW, or BLOCKED).
Interactive Blast Tree Call Graph: Visual tree diagram connecting root modifications to affected callers and API routes with live status badges.
1-Click Quick Fix Buttons: Fix detected risks (as any, @ts-ignore, unhandled promises, missing null guards) directly from the dashboard.
"📋 Copy PR Summary": One click copies a formatted GitHub Markdown report ready for Slack, PRs, or issue trackers.

🚀 Quick Start

Installation

Install VS Code Extension (from VSIX)

Download proofcode-0.1.0.vsix from Releases.
In VS Code, open Extensions (Cmd+Shift+X).
Click ··· in the top-right corner and select "Install from VSIX...".
Select proofcode-0.1.0.vsix.

Install Standalone CLI via npm

npm install -g proofcode

🛠️ CLI Reference

# Verify working tree changes against Git HEAD
proofcode verify

# Verify only staged git changes (git diff --cached)
proofcode verify --staged

# Generate PR markdown comment summary and write to file
proofcode pr-summary -o pr-comment.md

# Install automated git pre-commit hook in .git/hooks/pre-commit
proofcode install-hook

# Install GitHub Actions workflow (.github/workflows/proofcode.yml)
proofcode init-ci

# Generate custom configuration (.proofcode/config.json)
proofcode init-config

# CI Mode: Emit GitHub Actions annotations and append to Step Summary
proofcode verify --ci --strict

# Run targeted live unit tests alongside verification
proofcode verify --live

# Output report as JSON or formatted GitHub Markdown
proofcode verify --json
proofcode verify --markdown

Options & Flags

--staged: Verify only staged git changes (git diff --cached).
--live: Run targeted project unit tests (Vitest, Jest, Mocha).
--ci: Output GitHub Actions annotations (::error, ::warning) and write to Step Summary.
--strict: Exit code 1 if score < 75% or verdict is not READY_TO_SHIP.
--markdown, -m: Output report as formatted GitHub Flavored Markdown.
--json: Output report as structured JSON.
-o, --output <file>: Write output directly to the specified file path.

📋 Sample Verification Output

====================================================
             PROOFCODE CHANGE VERIFICATION          
====================================================
Verdict:       BLOCKED
Score:         42%
Files Changed: 3
Functions:     5 affected
API Routes:    1 affected
Risks:         🔴 2 High | 🟠 1 Med | 🟢 0 Low
----------------------------------------------------
WHAT COULD THIS CHANGE BREAK?
- [HIGH] Breaking Contract: Symbol 'getOrder' parameter count changed from 1 to 2.
  Impact: 2 downstream caller(s) broken.
  Dependents: Dashboard.tsx:42, orderService.ts:88
- [HIGH] Reliability: Unawaited Async Call in Conditional Statement
  Impact: Call to 'checkAuth()' is evaluated inside 'if (...)' without 'await'.
  Dependents: route.ts (api/orders)
----------------------------------------------------
CRITICAL FINDINGS:
[HIGH] Breaking Contract Drift at src/services/orderService.ts:18
  -> Function 'getOrder' now requires 2 parameters, but caller 'Dashboard.tsx:42' passes 1.
[HIGH] Unawaited Async Call in Conditional Statement at src/app/api/orders/route.ts:12
  -> Call to 'checkAuth()' returns a Promise object without 'await'.
====================================================

⚙️ Configuration: `.proofcode/config.json`

ProofCode supports custom project configuration via .proofcode/config.json, proofcode.config.json, or a "proofcode" key in package.json:

{
  "thresholds": {
    "minScore": 75,
    "blockOnHighRisk": true
  },
  "ignore": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/.git/**"
  ],
  "rules": {
    "PC-REL-008": "error",
    "PC-TYPE-001": "warn",
    "PC-MUT-001": "error",
    "PC-ENV-001": "error",
    "PC-IMPORT-001": "error"
  }
}

Run proofcode init-config to quickly generate this file in your project. Rule overrides accept "off" (ignore), "warn" / "MEDIUM", or "error" / "HIGH".

📐 Architectural Rules: `.proofcode/rules.md`

Define custom architectural guardrails for your repository in .proofcode/rules.md:

# Architectural Rules

## Rule 1: Authentication & Authorization
- **Pattern**: `src/app/api/**/route.ts`
- **Severity**: HIGH
- **Requirement**: All public API handlers modifying database resources must verify session authentication.

## Rule 2: Data Privacy & Secret Exposure
- **Pattern**: `src/app/api/**`
- **Severity**: HIGH
- **Requirement**: Never return password hashes (`passwordHash`), secret keys, or sensitive credentials in API response JSON.

## Rule 3: Resource Ownership
- **Pattern**: `src/app/api/orders/**`
- **Severity**: HIGH
- **Requirement**: Queries for specific records must enforce user ownership (`userId` constraint) to prevent IDOR attacks.

🧪 Quality & Verification Standards

ProofCode is rigorously tested against its own codebase:

Test Suite: 77 / 77 passing tests across 18 test suites (vitest).
Dogfood Verification: ProofCode self-verifies on every commit with 100% score.
TypeScript: Strict typechecking (tsc --noEmit), 0 errors.
ESLint: Complete code compliance, 0 warnings.
Bundle Performance: Production VS Code extension bundle built with esbuild (dist/extension.js at ~68 KB).

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.proofcode		.proofcode
.vscode		.vscode
examples/demo-app		examples/demo-app
resources		resources
scripts		scripts
src		src
tests		tests
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.npmignore		.npmignore
.vscodeignore		.vscodeignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
esbuild.config.js		esbuild.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository navigation

About

Repository files navigation

ProofCode

AI writes code. ProofCode proves the change.

📖 Overview

⚡ Core Features

1. 💥 Blast Radius & Downstream Dependency Impact

2. 🛡️ AI Reliability & Deterministic Risk Engine

3. 🧪 Targeted Live Test Execution (<1s)

4. 🪝 Automated Git Pre-Commit Hook

5. 🤖 One-Command CI/CD Setup (`proofcode init-ci`)

6. 📊 Glassmorphic Verification Dashboard

🚀 Quick Start

Installation

Install VS Code Extension (from VSIX)

Install Standalone CLI via npm

🛠️ CLI Reference

Options & Flags

📋 Sample Verification Output

⚙️ Configuration: `.proofcode/config.json`

📐 Architectural Rules: `.proofcode/rules.md`

🧪 Quality & Verification Standards

📄 License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

ProofCode

AI writes code. ProofCode proves the change.

📖 Overview

⚡ Core Features

1. 💥 Blast Radius & Downstream Dependency Impact

2. 🛡️ AI Reliability & Deterministic Risk Engine

3. 🧪 Targeted Live Test Execution (<1s)

4. 🪝 Automated Git Pre-Commit Hook

5. 🤖 One-Command CI/CD Setup (proofcode init-ci)

6. 📊 Glassmorphic Verification Dashboard

🚀 Quick Start

Installation

Install VS Code Extension (from VSIX)

Install Standalone CLI via npm

🛠️ CLI Reference

Options & Flags

📋 Sample Verification Output

⚙️ Configuration: .proofcode/config.json

📐 Architectural Rules: .proofcode/rules.md

🧪 Quality & Verification Standards

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

5. 🤖 One-Command CI/CD Setup (`proofcode init-ci`)

⚙️ Configuration: `.proofcode/config.json`

📐 Architectural Rules: `.proofcode/rules.md`