pr-complexity 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Mellen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# pr-complexity
+
+A GitHub Action that scores pull requests by **information content** instead of lines of code. Language-agnostic: JS/TS, Python, Go, Rust, Ruby, Java, C/C++, C#, PHP, Swift, Kotlin, SQL, shell, Dockerfiles — anything text-based.
+
+It compresses the diff against the rest of your codebase (brotli). Code that repeats existing patterns — boilerplate, renames, house style — compresses to almost nothing. Genuinely new logic doesn't. Deletions earn symmetric credit. The raw byte count is then mapped onto a log-scale points score approximating the Kolmogorov complexity of the change given the codebase: `K(diff | repo)`.
+
+Lockfiles, generated code, and build output are ignored.
+
+## Usage
+
+```yaml
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  complexity:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: sebMellen/pr-complexity@v1
+```
+
+The action posts one comment per PR and updates it on every push.
+
+## CLI (for humans and agents)
+
+Zero dependencies, runs anywhere with Node 20+ and git:
+
+```bash
+npx pr-complexity              # score uncommitted changes vs HEAD (incl. untracked files)
+npx pr-complexity --base main  # score HEAD vs merge-base of main (PR mode)
+npx pr-complexity --json       # machine-readable, per-file attribution
+npx pr-complexity --budget 40  # exit 1 if over budget
+```
+
+Because the score is cheap, deterministic, and signed, an agent can optimize against it — implement, score, simplify, repeat. The cheapest way to lower the score is to reuse existing patterns and delete dead code, so gaming it mostly means doing the right thing:
+
+```bash
+while ! pr-complexity --budget 40 --json > score.json; do
+  agent "Reduce complexity. Biggest contributors: $(jq -c '.files[:5]' score.json)"
+done
+```
+
+Always constrain on behavior (tests must pass) — the score is a simplicity prior, not proof of correctness.
+
+## Reading the score
+
+Points are a **Fahrenheit-style 0–100 scale**: 0 means the PR adds no new information, and 100 is the limit — roughly 16 KB of novel compressed logic, the largest change that should ever land in one PR. Scores are clamped to ±100.
+
+**Points = `min(100, 5 · log2(1 + bytes/100)^1.5)`**, signed — deletions push negative. The 1.5 exponent compresses the everyday range (most PRs land under 50) and stretches the top end, so genuinely huge changes still shoot toward the ceiling. On top of that, a **file-scatter penalty** charges for review context-switching: 0 for ≤10 files, `6·log2(files/10)` beyond, capped at +30. Net-negative PRs are exempt — simplification is never taxed.
+
+| Points | Band | Meaning |
+|---|---|---|
+| `≤ 0` | net simplifier | Removes more information than it adds. Reward these. |
+| `< 10` | trivial | Typos, config tweaks, one-line fixes. |
+| `< 30` | small | A focused fix or small feature slice. |
+| `< 50` | moderate | Real new logic; review carefully. |
+| `< 70` | large | Heavy new complexity — should earn its keep. |
+| `70–99` | split-worthy | Strongly consider splitting. |
+| `100` | the limit | Too big to review. Split it. |
+
+Calibration data from a large production TypeScript API: focused bug fixes score 5–30, feature slices 42–58, major upgrades (Prisma v7, CI reworks) 70–82, and a whole new platform API prototype (~3.3K lines, dozens of files) scores 88. Because the scale is anchored to information content rather than repo size, a point means roughly the same thing across codebases.
+
+## Outputs
+
+The action sets `points` and `net_bytes` as step outputs, so you can gate on them (e.g. require extra review above a threshold).
+
+## How it works
+
+1. Diff the PR against its merge base (`git diff base...head`).
+2. Drop lockfiles (`*.lock`, `*.sum`), generated code (`*.gen.*`, `*.pb.*`), minified files, and build output (`dist/`, `node_modules/`, `target/`, `__pycache__/`, …).
+3. Strip comments (`//`, `#`, `--`, `/* */` — heuristic) and whitespace from the added/removed lines.
+4. Concatenate the repo's source files (capped at 256 KB, excluding the files being changed so new code can't compress against itself) as a compression context.
+5. Score = `compress(context + added) − compress(context)` minus the same for removed lines, **pooled across all files** — a pattern repeated in 20 files is one idea, not twenty. The file-scatter penalty separately captures the per-file review burden, and per-file byte estimates keep the score attributable.
+
+Because compression is a novelty detector, unusual identifiers, magic numbers, and new abstractions cost full entropy, while the 50th `return` statement costs ~zero.
+
+Zero dependencies — just Node's built-in `zlib`, `git`, and the GitHub REST API.

package/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { parseDiff, score, scoreable, sh } from './lib.mjs';
+
+const USAGE = `pr-complexity — score code changes by information content, K(diff | codebase)
+
+Usage:
+  pr-complexity              score uncommitted changes vs HEAD (incl. untracked files)
+  pr-complexity --base main  score HEAD vs merge-base of <ref> (PR mode)
+  pr-complexity --budget 40  exit 1 if the score exceeds <pts> (gate an agent loop)
+  pr-complexity --json       machine-readable output with per-file attribution
+`;
+
+const { values } = parseArgs({
+  options: {
+    base: { type: 'string' },
+    budget: { type: 'string' },
+    json: { type: 'boolean', default: false },
+    help: { type: 'boolean', default: false },
+  },
+});
+
+if (values.help) {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+
+let diff;
+try {
+  diff = values.base
+    ? sh(`git diff --unified=0 --no-color ${values.base}...HEAD`)
+    : sh('git diff --unified=0 --no-color HEAD');
+} catch {
+  console.error('error: not a git repo, or bad --base ref');
+  process.exit(2);
+}
+
+const files = parseDiff(diff);
+if (!values.base) {
+  for (const p of sh('git ls-files --others --exclude-standard').split('\n')) {
+    if (p && scoreable(p)) {
+      try {
+        files.push({ path: p, added: readFileSync(p, 'utf8').split('\n'), removed: [] });
+      } catch {}
+    }
+  }
+}
+
+const result = score(files);
+const budget = values.budget !== undefined ? Number(values.budget) : null;
+const over = budget !== null && result.points > budget;
+const scope = values.base ? `HEAD vs ${values.base}` : 'working tree vs HEAD';
+const hint =
+  'lower the score by reusing existing utilities, matching local patterns, and deleting dead code';
+
+if (values.json) {
+  console.log(JSON.stringify({ scope, ...result, budget, over, hint }));
+} else {
+  const sign = result.net > 0 ? '+' : '';
+  console.log(
+    `${result.points} pts (${result.band}) — net ${sign}${result.net} bytes, ${scope}`
+  );
+  if (result.scatter > 0)
+    console.log(`  scatter: +${result.scatter} pts (${result.filesChanged} files changed)`);
+  for (const f of result.files.filter((f) => f.netBytes > 0).slice(0, 5))
+    console.log(`  +${f.netBytes}B  ${f.path}`);
+  if (budget !== null)
+    console.log(over ? `budget ${budget}: OVER by ${result.points - budget} pts` : `budget ${budget}: ok`);
+  if (result.points > 0) console.log(`hint: ${hint}`);
+}
+
+process.exit(over ? 1 : 0);

package/lib.mjs

@@ -0,0 +1,137 @@
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { brotliCompressSync, constants } from 'node:zlib';
+
+export const INCLUDE =
+  /\.(ts|tsx|js|jsx|mts|cts|mjs|cjs|py|go|rs|rb|java|kt|kts|scala|sc|c|h|cc|cpp|cxx|hpp|cs|php|swift|m|mm|sql|sh|bash|zsh|lua|pl|pm|r|jl|dart|vue|svelte|hs|ml|fs|fsx|ex|exs|erl|clj|cljs|groovy|tf|hcl|graphql|proto|json|ya?ml|toml|xml|html?|css|scss|less|md|mdx)$/;
+export const INCLUDE_FILES = /(^|\/)(Dockerfile|Makefile|Justfile)$/i;
+export const EXCLUDE = [
+  /(^|\/)node_modules\//,
+  /(^|\/)(dist|build|out|coverage|vendor|fixtures?|target|__pycache__)(\/|$)/,
+  /(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb)$/,
+  /\.(min\.(js|css)|map|snap|lock|sum|gen\.\w+|pb\.\w+)$/i,
+];
+export const CTX_LIMIT = 256 * 1024;
+
+export const scoreable = (p) =>
+  (INCLUDE.test(p) || INCLUDE_FILES.test(p)) && !EXCLUDE.some((re) => re.test(p));
+
+export const sh = (cmd) => execSync(cmd, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+
+const CEILING_BYTES = 16 * 1024;
+const SCALE = 100 / Math.pow(Math.log2(1 + CEILING_BYTES / 100), 1.5);
+
+export const toPoints = (b) => {
+  const p = Math.round(SCALE * Math.pow(Math.log2(1 + Math.abs(b) / 100), 1.5));
+  return (b < 0 ? -1 : 1) * Math.min(100, p);
+};
+
+// File-scatter penalty: every file is a fresh review context even when its
+// diff is informationally cheap (renames, repeated patterns). Free up to 10
+// files, +6 pts per doubling beyond, capped at +30 so bytes stay dominant.
+// Net-negative PRs are exempt — don't tax simplification.
+export const scatterOf = (n) =>
+  n <= 10 ? 0 : Math.min(30, Math.round(6 * Math.log2(n / 10)));
+
+export const bandOf = (points) =>
+  points <= 0
+    ? 'net simplifier'
+    : points < 10
+      ? 'trivial'
+      : points < 30
+        ? 'small'
+        : points < 50
+          ? 'moderate'
+          : points < 70
+            ? 'large'
+            : 'split-worthy';
+
+export function parseDiff(diff) {
+  const files = [];
+  let cur = null;
+  for (const line of diff.split('\n')) {
+    if (line.startsWith('diff --git')) {
+      cur = null;
+      continue;
+    }
+    if (line.startsWith('+++ ')) {
+      if (line.startsWith('+++ b/') && scoreable(line.slice(6))) {
+        cur = { path: line.slice(6), added: [], removed: [] };
+        files.push(cur);
+      }
+      continue;
+    }
+    if (!cur) continue;
+    if (line.startsWith('+')) cur.added.push(line.slice(1));
+    else if (line.startsWith('-')) cur.removed.push(line.slice(1));
+  }
+  return files;
+}
+
+// Heuristic comment stripping across languages. `#` and `--` require a
+// following space so JS private fields (`#count`) and decrements (`x--`)
+// survive; `https://` in strings is still mangled. Good enough.
+const norm = (s) =>
+  s
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/(^|\s)\/\/[^\n]*/g, '$1')
+    .replace(/(^|\s)#(\s|$)[^\n]*/g, '$1')
+    .replace(/(^|\s)--(\s|$)[^\n]*/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+const compress = (s) =>
+  brotliCompressSync(Buffer.from(s), {
+    params: { [constants.BROTLI_PARAM_QUALITY]: 11 },
+  }).length;
+
+// Repo content as compression context, excluding files present in the diff
+// so new code can't compress against itself.
+export function buildContext(excludePaths = new Set()) {
+  let ctx = '';
+  for (const p of sh('git ls-files').split('\n')) {
+    if (ctx.length >= CTX_LIMIT) break;
+    if (!p || !scoreable(p) || excludePaths.has(p)) continue;
+    try {
+      ctx += readFileSync(p, 'utf8') + '\n';
+    } catch {}
+  }
+  return ctx.slice(0, CTX_LIMIT);
+}
+
+// Totals are pooled across files: a pattern repeated in 20 files is one
+// idea, not twenty — the file-scatter penalty separately captures the
+// per-file review burden. Per-file bytes are for attribution only.
+export function score(files) {
+  const ctx = buildContext(new Set(files.map((f) => f.path)));
+  const cCtx = compress(ctx);
+  const marginal = (lines) => {
+    const t = norm(lines.join('\n'));
+    return t ? Math.max(0, compress(ctx + t) - cCtx) : 0;
+  };
+  const added = marginal(files.flatMap((f) => f.added));
+  const removed = marginal(files.flatMap((f) => f.removed));
+  for (const f of files) {
+    f.addedBytes = marginal(f.added);
+    f.removedBytes = marginal(f.removed);
+    f.netBytes = f.addedBytes - f.removedBytes;
+    delete f.added;
+    delete f.removed;
+  }
+  files.sort((a, b) => b.netBytes - a.netBytes);
+  const net = added - removed;
+  const bytePoints = toPoints(net);
+  const scatter = net > 0 ? scatterOf(files.length) : 0;
+  const points = net > 0 ? Math.min(100, bytePoints + scatter) : bytePoints;
+  return {
+    added,
+    removed,
+    net,
+    points,
+    bytePoints,
+    scatter,
+    filesChanged: files.length,
+    band: bandOf(points),
+    files,
+  };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "pr-complexity",
+  "version": "1.2.0",
+  "description": "Score code changes by information content — K(diff | codebase)",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "pr-complexity": "./cli.js"
+  },
+  "files": [
+    "cli.js",
+    "lib.mjs"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sebmellen/pr-complexity.git"
+  },
+  "keywords": [
+    "code-complexity",
+    "pull-request",
+    "code-review",
+    "kolmogorov",
+    "compression",
+    "github-action"
+  ]
+}