commit-cop 1.0.1 → 1.1.0

package/README.md

@@ -4,13 +4,39 @@ Commit Cop is a pre-commit safety checker that scans your **staged files** and w
 
 Built for students, hackathons, and dev teams who want practical guardrails—not just formatting checks.
 
+> **Commit Cop** (`commit-cop`) — catch bad commits before they hit GitHub.
+
 ## Install
 
 ```bash
 npm install commit-cop
 ```
 
-Run it on staged changes:
+### Run automatically on every commit (recommended)
+
+From your Git repo:
+
+```bash
+npx commit-cop install
+```
+
+This adds a pre-commit hook. After that, **Commit Cop runs whenever you `git commit`**. If it finds errors, the commit is blocked.
+
+Treat warnings as errors in the hook:
+
+```bash
+npx commit-cop install --strict
+```
+
+Remove the hook:
+
+```bash
+npx commit-cop uninstall
+```
+
+### Run manually
+
+Scan staged changes once:
 
 ```bash
 npx commit-cop
@@ -22,6 +48,39 @@ Treat warnings as errors:
 npx commit-cop --strict
 ```
 
+Allow `console.log` in staged code (skips the console.log check):
+
+```bash
+npx commit-cop --allow-console-log
+```
+
+## Auto-fix (work in progress)
+
+`wip-fix` is a placeholder command name that applies common repo fixes. More fixes may be added over time.
+
+```bash
+npx commit-cop wip-fix
+```
+
+By default, `wip-fix` does **not** remove `console.log` lines. Pass `--fix-console-log` to include that fix. `debugger` lines are still removed from staged files.
+
+```bash
+npx commit-cop wip-fix --fix-console-log
+```
+
+| Check | Fix |
+| --- | --- |
+| Generated folders / env files | Adds missing `.gitignore` entries (`.env`, `node_modules/`, `dist/`, `build/`, `.next/`, `coverage/`, junk patterns) |
+| Focused tests | Replaces `test.only`, `it.only`, `describe.only` in test/spec files |
+| Debug logs | Removes standalone `console.log(...)` from **staged** JS/TS files only with `--fix-console-log` |
+| Debugger | Always removes standalone `debugger` lines from **staged** JS/TS files |
+| Junk files | Deletes `.DS_Store`, `Thumbs.db`, swap/backup files found on disk |
+| Env / sensitive / generated / junk / binary / large (staged) | Runs `git restore --staged` on matching staged files |
+| Lockfile drift | Runs `npm install` when `package-lock.json` is missing or older than `package.json` |
+| Merge conflicts, secrets, localhost | **Manual only** — reported at the end; not auto-fixed |
+
+Review all changes before committing. `wip-fix` may run `npm install` and unstaging commands against your Git index.
+
 ## What it checks
 
 | Check | Severity | What it catches |
@@ -32,7 +91,7 @@ npx commit-cop --strict
 | Generated folders | Error | `node_modules/`, `dist/`, `build/`, `.next/`, `coverage/` (including nested paths) |
 | Secrets | Error | API keys, GitHub/AWS/Stripe tokens, JWT secrets, database URLs |
 | Focused tests | Error | `test.only`, `it.only`, `describe.only` left in test files |
-| Debug logs | Warning | `console.log` in staged JS/TS code |
+| Debug logs | Warning | `console.log` in staged JS/TS code (skip with `--allow-console-log`) |
 | Debugger statements | Warning | `debugger` in staged JS/TS code |
 | Localhost URLs | Warning | Hardcoded `localhost` or `127.0.0.1` URLs |
 | Junk files | Warning | `.DS_Store`, `Thumbs.db`, swap/backup files |
@@ -47,6 +106,7 @@ Errors block the commit. Warnings are reported but do not block unless you use `
 ```bash
 npm install
 npm run commit-cop
+npm run commit-cop -- wip-fix
 ```
 
 Build and run the compiled CLI:
@@ -60,19 +120,21 @@ npm start
 
 ```
 src/
-  index.ts       CLI entry point
+  index.ts       CLI entry point (scan + wip-fix subcommand)
   git.ts         Reads staged files from Git
   scanner.ts     Runs all checks
   reporter.ts    Prints the report
   types.ts       Shared types
   checks/        One file per check
+  fix/           Auto-fix helpers used by wip-fix
 ```
 
 Each check implements the same interface: receive staged files, return findings with a message and suggested fix.
 
 ## How it works
 
-1. Read staged file paths with `git diff --cached --name-only`
-2. Run every check in `src/checks/`
-3. Print a summary with file locations and fix suggestions
-4. Exit with code `1` if errors are found (or warnings in strict mode)
+1. Install the hook with `npx commit-cop install` (or run manually)
+2. Read staged file paths with `git diff --cached --name-only`
+3. Run every check in `src/checks/`
+4. Print a summary with file locations and fix suggestions
+5. Exit with code `1` if errors are found (or warnings in strict mode), which blocks the commit

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "commit-cop",
-  "version": "1.0.1",
-  "description": "A pre-commit safety checker that scans staged files for risky commits.",
+  "version": "1.1.0",
+  "description": "Commit Cop — a pre-commit safety checker that scans staged files for risky commits.",
   "type": "module",
   "bin": {
     "commit-cop": "./dist/index.js"
@@ -10,7 +10,8 @@
     "dev": "tsx src/index.ts",
     "build": "tsc",
     "start": "node dist/index.js",
-    "commit-cop": "tsx src/index.ts"
+    "commit-cop": "tsx src/index.ts",
+    "demo:setup": "node scripts/setup-demo.mjs"
   },
   "repository": {
     "type": "git",

package/src/brand.ts

@@ -0,0 +1,3 @@
+export const PRODUCT_NAME = "Commit Cop";
+export const CLI_NAME = "commit-cop";
+export const TAGLINE = "Catch bad commits before they hit GitHub";

package/src/checks/binaryFileCheck.ts

@@ -52,9 +52,9 @@ export const binaryFileCheck: Check = {
           severity: "warning",
           checkName: this.name,
           file,
-          message: "Binary or non-text file is staged.",
-          suggestion:
-            "Remove it from the commit or store it outside Git (e.g. Git LFS).",
+          message:
+            "Binary file detected — archives, executables, and media don't belong in source control.",
+          suggestion: "Remove it from the commit or store it with Git LFS.",
         });
       }
     }

package/src/checks/consoleLogCheck.ts

@@ -27,8 +27,9 @@ export const consoleLogCheck: Check = {
             checkName: this.name,
             file,
             line: index + 1,
-            message: "console.log found in staged code.",
-            suggestion: "Remove debug logs before committing.",
+            message:
+              "Debug log left in code — easy to miss and clutters production output.",
+            suggestion: "Delete the console.log before committing.",
           });
         }
       });

package/src/checks/debuggerCheck.ts

@@ -20,8 +20,9 @@ export const debuggerCheck: Check = {
             checkName: this.name,
             file,
             line: index + 1,
-            message: "debugger statement found in staged code.",
-            suggestion: "Remove debugger statements before committing.",
+            message:
+              "debugger statement left in code — pauses execution and breaks CI/headless runs.",
+            suggestion: "Delete the debugger statement before committing.",
           });
         }
       });

package/src/checks/envFileCheck.ts

@@ -14,8 +14,9 @@ export const envFileCheck: Check = {
           severity: "error",
           checkName: this.name,
           file,
-          message: "Environment file is staged and may contain secrets.",
-          suggestion: `Run: git restore --staged ${file}`,
+          message:
+            ".env file detected — these often hold API keys, passwords, and tokens.",
+          suggestion: `Unstage it: git restore --staged ${file}`,
         });
       }
     }

package/src/checks/focusedTestCheck.ts

@@ -28,8 +28,8 @@ export const focusedTestCheck: Check = {
               checkName: this.name,
               file,
               line: index + 1,
-              message: `${pattern} found. This may skip the rest of the test suite.`,
-              suggestion: `Replace ${pattern} with the normal test function.`,
+              message: `${pattern} detected — only that test will run, hiding failures in the rest of the suite.`,
+              suggestion: `Change ${pattern} back to ${pattern.replace(".only", "")}.`,
             });
           }
         }

package/src/checks/generatedFolderCheck.ts

@@ -34,8 +34,8 @@ export const generatedFolderCheck: Check = {
           severity: "error",
           checkName: this.name,
           file,
-          message: `${matchedFolder} is staged but is usually generated and should not be committed.`,
-          suggestion: `Add ${matchedFolder} to .gitignore and run: git restore --staged ${file}`,
+          message: `Generated folder (${matchedFolder}) — auto-built files bloat the repo and cause merge pain.`,
+          suggestion: `Add ${matchedFolder} to .gitignore, then: git restore --staged ${file}`,
         });
       }
     }

package/src/checks/junkFileCheck.ts

@@ -28,8 +28,9 @@ export const junkFileCheck: Check = {
           severity: "warning",
           checkName: this.name,
           file,
-          message: "OS or editor junk file is staged.",
-          suggestion: `Run: git restore --staged ${file}`,
+          message:
+            "OS or editor junk file — adds noise and has no place in the repo.",
+          suggestion: `Unstage it: git restore --staged ${file}`,
         });
       }
     }

package/src/checks/largeFileCheck.ts

@@ -20,8 +20,8 @@ export const largeFileCheck: Check = {
           severity: "warning",
           checkName: this.name,
           file,
-          message: `Large file staged: ${sizeMb.toFixed(2)} MB.`,
-          suggestion: "Consider removing this file from Git or using Git LFS.",
+          message: `Large file (${sizeMb.toFixed(2)} MB) — slows clones and may hit GitHub's size limits.`,
+          suggestion: "Remove it from Git or use Git LFS for big assets.",
         });
       }
     }

package/src/checks/localHostCheck.ts

@@ -27,8 +27,8 @@ export const localHostCheck: Check = {
               checkName: this.name,
               file,
               line: index + 1,
-              message: `Hardcoded local URL found: ${pattern}`,
-              suggestion: "Use an environment variable instead of a hardcoded localhost URL.",
+              message: `Hardcoded local URL (${pattern}) — won't work in production or for teammates.`,
+              suggestion: "Move the URL to an environment variable (e.g. process.env.API_URL).",
             });
           }
         }

package/src/checks/lockfileDriftCheck.ts

@@ -18,8 +18,9 @@ export const lockfileDriftCheck: Check = {
         severity: "warning",
         checkName: this.name,
         file: "package.json",
-        message: "package.json is staged but package-lock.json is not.",
-        suggestion: "Run npm install and stage package-lock.json.",
+        message:
+          "package.json changed without its lockfile — teammates may get different dependency versions.",
+        suggestion: "Run npm install, then stage package-lock.json.",
       });
     }
 
@@ -28,8 +29,9 @@ export const lockfileDriftCheck: Check = {
         severity: "warning",
         checkName: this.name,
         file: "package-lock.json",
-        message: "package-lock.json is staged but package.json is not.",
-        suggestion: "Stage package.json or unstage the lockfile.",
+        message:
+          "Lockfile changed without package.json — the lockfile may not match your declared dependencies.",
+        suggestion: "Stage package.json too, or unstage package-lock.json.",
       });
     }
 

package/src/checks/mergeConflictCheck.ts

@@ -25,9 +25,10 @@ export const mergeConflictCheck: Check = {
               checkName: this.name,
               file,
               line: index + 1,
-              message: "Merge conflict marker found in staged file.",
+              message:
+                "Unresolved merge conflict — this file won't run correctly until fixed.",
               suggestion:
-                "Resolve the conflict, remove the markers, and restage the file.",
+                "Resolve the conflict, remove the <<<<<<< / ======= / >>>>>>> markers, then restage.",
             });
             return;
           }

package/src/checks/secretCheck.ts

@@ -6,21 +6,21 @@ import {
   shouldSkipContentScan,
 } from "./utils.js";
 
-const secretPatterns = [
-  /OPENAI_API_KEY\s*=/i,
-  /DATABASE_URL\s*=/i,
-  /JWT_SECRET\s*=/i,
-  /AUTH_SECRET\s*=/i,
-  /PRIVATE_KEY\s*=/i,
-  /SECRET_KEY\s*=/i,
-  /sk-[A-Za-z0-9_-]{20,}/,
-  /ghp_[A-Za-z0-9]{36,}/,
-  /github_pat_[A-Za-z0-9_]+/,
-  /AKIA[0-9A-Z]{16}/,
-  /sk_live_[A-Za-z0-9]+/,
-  /AIza[0-9A-Za-z_-]{35}/,
-  /hooks\.slack\.com\/services\//,
-  /password\s*=\s*['"][^'"]{8,}['"]/i,
+const secretRules: { pattern: RegExp; label: string }[] = [
+  { pattern: /OPENAI_API_KEY\s*=/i, label: "OpenAI API key" },
+  { pattern: /DATABASE_URL\s*=/i, label: "database connection string" },
+  { pattern: /JWT_SECRET\s*=/i, label: "JWT secret" },
+  { pattern: /AUTH_SECRET\s*=/i, label: "auth secret" },
+  { pattern: /PRIVATE_KEY\s*=/i, label: "private key" },
+  { pattern: /SECRET_KEY\s*=/i, label: "secret key" },
+  { pattern: /sk-[A-Za-z0-9_-]{20,}/, label: "API key" },
+  { pattern: /ghp_[A-Za-z0-9]{36,}/, label: "GitHub personal access token" },
+  { pattern: /github_pat_[A-Za-z0-9_]+/, label: "GitHub personal access token" },
+  { pattern: /AKIA[0-9A-Z]{16}/, label: "AWS access key" },
+  { pattern: /sk_live_[A-Za-z0-9]+/, label: "Stripe live secret key" },
+  { pattern: /AIza[0-9A-Za-z_-]{35}/, label: "Google API key" },
+  { pattern: /hooks\.slack\.com\/services\//, label: "Slack webhook URL" },
+  { pattern: /password\s*=\s*['"][^'"]{8,}['"]/i, label: "hardcoded password" },
 ];
 
 export const secretCheck: Check = {
@@ -38,16 +38,16 @@ export const secretCheck: Check = {
       lines.forEach((line, index) => {
         if (isCommentLine(line) || isPlaceholderValue(line)) return;
 
-        for (const pattern of secretPatterns) {
-          if (pattern.test(line)) {
+        for (const rule of secretRules) {
+          if (rule.pattern.test(line)) {
             findings.push({
               severity: "error",
               checkName: this.name,
               file,
               line: index + 1,
-              message: "Possible secret found in staged file.",
+              message: `Possible ${rule.label} — credentials pushed to GitHub can be scraped instantly.`,
               suggestion:
-                "Remove the secret and rotate it if it was already pushed.",
+                "Remove it from the code, unstage the file, and rotate the credential if it was ever pushed.",
             });
             return;
           }

package/src/checks/sensitiveFilenameCheck.ts

@@ -39,8 +39,9 @@ export const sensitiveFilenameCheck: Check = {
           severity: "error",
           checkName: this.name,
           file,
-          message: "Sensitive credential file is staged.",
-          suggestion: `Run: git restore --staged ${file}`,
+          message:
+            "Credential or key file detected — private keys and auth config should not be in Git.",
+          suggestion: `Unstage it: git restore --staged ${file}`,
         });
       }
     }

package/src/fix/debugCode.ts

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isCodeFile } from "../checks/utils.js";
+import { getStagedFiles } from "../git.js";
+import type { WipFixOptions } from "../types.js";
+
+const CONSOLE_LOG_LINE = /^\s*console\.log\([^)]*\);?\s*$/;
+const DEBUGGER_LINE = /^\s*debugger;?\s*$/;
+
+function stripDebugLines(
+  content: string,
+  options: { removeConsoleLog: boolean; removeDebugger: boolean }
+): { updated: string; removed: number } {
+  const lines = content.split("\n");
+  const kept: string[] = [];
+  let removed = 0;
+
+  for (const line of lines) {
+    const isConsoleLog = CONSOLE_LOG_LINE.test(line);
+    const isDebugger = DEBUGGER_LINE.test(line);
+
+    if (
+      (options.removeConsoleLog && isConsoleLog) ||
+      (options.removeDebugger && isDebugger)
+    ) {
+      removed += 1;
+      continue;
+    }
+    kept.push(line);
+  }
+
+  return { updated: kept.join("\n"), removed };
+}
+
+export function fixDebugCode(
+  cwd = process.cwd(),
+  options: WipFixOptions = {}
+): string[] {
+  const removeConsoleLog = Boolean(options.fixConsoleLog);
+  const removeDebugger = true;
+
+  if (!removeConsoleLog && !removeDebugger) {
+    return [];
+  }
+
+  let stagedFiles: string[];
+
+  try {
+    stagedFiles = getStagedFiles();
+  } catch {
+    return [];
+  }
+
+  const fixed: string[] = [];
+
+  for (const file of stagedFiles) {
+    if (!isCodeFile(file)) continue;
+
+    const absolutePath = path.resolve(cwd, file);
+    if (!fs.existsSync(absolutePath)) continue;
+
+    const content = fs.readFileSync(absolutePath, "utf-8");
+    const { updated, removed } = stripDebugLines(content, {
+      removeConsoleLog,
+      removeDebugger,
+    });
+    if (removed === 0) continue;
+
+    fs.writeFileSync(absolutePath, updated, "utf-8");
+    fixed.push(file);
+  }
+
+  return fixed;
+}

package/src/fix/focusedTests.ts

@@ -0,0 +1,26 @@
+import fs from "node:fs";
+import path from "node:path";
+import { walkCodeFiles } from "./utils.js";
+
+const FOCUSED_TEST_PATTERN = /\b(test|it|describe)\.only\b/g;
+
+function isTestFile(filePath: string): boolean {
+  return filePath.includes("test") || filePath.includes("spec");
+}
+
+export function fixFocusedTests(cwd = process.cwd()): string[] {
+  const files = walkCodeFiles(cwd, isTestFile);
+  const fixed: string[] = [];
+
+  for (const absolutePath of files) {
+    const content = fs.readFileSync(absolutePath, "utf-8");
+    if (!FOCUSED_TEST_PATTERN.test(content)) continue;
+
+    FOCUSED_TEST_PATTERN.lastIndex = 0;
+    const updated = content.replace(FOCUSED_TEST_PATTERN, "$1");
+    fs.writeFileSync(absolutePath, updated, "utf-8");
+    fixed.push(path.relative(cwd, absolutePath));
+  }
+
+  return fixed;
+}

package/src/fix/gitignore.ts

@@ -0,0 +1,108 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const GITIGNORE_PATH = ".gitignore";
+
+type GitignoreEntry = {
+  line: string;
+  isPresent: (lines: string[]) => boolean;
+};
+
+const entries: GitignoreEntry[] = [
+  {
+    line: ".env",
+    isPresent: (lines) =>
+      lines.some((line) => line === ".env" || line.startsWith(".env")),
+  },
+  {
+    line: "node_modules/",
+    isPresent: (lines) =>
+      lines.some(
+        (line) => line === "node_modules" || line === "node_modules/"
+      ),
+  },
+  {
+    line: "dist/",
+    isPresent: (lines) =>
+      lines.some((line) => line === "dist" || line === "dist/"),
+  },
+  {
+    line: "build/",
+    isPresent: (lines) =>
+      lines.some((line) => line === "build" || line === "build/"),
+  },
+  {
+    line: ".next/",
+    isPresent: (lines) =>
+      lines.some((line) => line === ".next" || line === ".next/"),
+  },
+  {
+    line: "coverage/",
+    isPresent: (lines) =>
+      lines.some((line) => line === "coverage" || line === "coverage/"),
+  },
+  {
+    line: ".DS_Store",
+    isPresent: (lines) =>
+      lines.some((line) => line.toLowerCase() === ".ds_store"),
+  },
+  {
+    line: "Thumbs.db",
+    isPresent: (lines) =>
+      lines.some((line) => line.toLowerCase() === "thumbs.db"),
+  },
+  {
+    line: "desktop.ini",
+    isPresent: (lines) =>
+      lines.some((line) => line.toLowerCase() === "desktop.ini"),
+  },
+  {
+    line: "*.swp",
+    isPresent: (lines) => lines.includes("*.swp"),
+  },
+  {
+    line: "*.bak",
+    isPresent: (lines) => lines.includes("*.bak"),
+  },
+  {
+    line: "*.tmp",
+    isPresent: (lines) => lines.includes("*.tmp"),
+  },
+];
+
+function parseGitignoreLines(content: string): string[] {
+  return content
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith("#"));
+}
+
+export function fixGitignore(cwd = process.cwd()): string[] {
+  const filePath = path.join(cwd, GITIGNORE_PATH);
+  const applied: string[] = [];
+
+  const existingContent = fs.existsSync(filePath)
+    ? fs.readFileSync(filePath, "utf-8")
+    : "";
+  const existingLines = parseGitignoreLines(existingContent);
+
+  const missing = entries.filter((entry) => !entry.isPresent(existingLines));
+  if (missing.length === 0) {
+    return applied;
+  }
+
+  const additions = missing.map((entry) => entry.line);
+  const needsLeadingNewline =
+    existingContent.length > 0 && !existingContent.endsWith("\n");
+  const block =
+    (needsLeadingNewline ? "\n" : "") +
+    (existingContent.length > 0 ? "\n" : "") +
+    "# Added by commit-cop wip-fix\n" +
+    additions.join("\n") +
+    "\n";
+
+  fs.writeFileSync(filePath, existingContent + block, "utf-8");
+  applied.push(...additions);
+
+  return applied;
+}

package/src/fix/junkFiles.ts

@@ -0,0 +1,16 @@
+import fs from "node:fs";
+import { isJunkFile } from "./matchers.js";
+import { walkRepo } from "./utils.js";
+
+export function fixJunkFiles(cwd = process.cwd()): string[] {
+  const removed: string[] = [];
+
+  walkRepo(cwd, (absolutePath, relativePath) => {
+    if (!isJunkFile(relativePath)) return;
+
+    fs.unlinkSync(absolutePath);
+    removed.push(relativePath);
+  });
+
+  return removed;
+}

package/src/fix/lockfile.ts

@@ -0,0 +1,23 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+export function fixLockfile(cwd = process.cwd()): boolean {
+  const packageJson = path.join(cwd, "package.json");
+  const packageLock = path.join(cwd, "package-lock.json");
+
+  if (!fs.existsSync(packageJson)) {
+    return false;
+  }
+
+  const needsInstall =
+    !fs.existsSync(packageLock) ||
+    fs.statSync(packageJson).mtimeMs > fs.statSync(packageLock).mtimeMs;
+
+  if (!needsInstall) {
+    return false;
+  }
+
+  execSync("npm install", { cwd, stdio: "inherit" });
+  return true;
+}