rogerchappel/blobbudget

BlobBudget

BlobBudget is a local-first TypeScript CLI that catches repository bloat before clones, fixtures, and release packages get chunky. It scans the working tree, respects .gitignore by default, applies configurable budgets, and writes stable Markdown or JSON reports for CI.

Quick start

npm install
npm run build
node dist/src/cli.js init --preset node-cli
node dist/src/cli.js scan . --out blobbudget.md --fail-on medium

After publishing you can use the package binary directly:

blobbudget scan . --format json --fail-on medium

Scan options are --out/-o, --format, --fail-on, --config, --no-gitignore, and --no-package. Init options are --preset and --force. Value options accept both --name value and --name=value forms; options from one command are rejected when passed to the other.

What it detects

• Oversized files that exceed maxFileBytes.
• Suspicious binary/archive extensions such as .zip, .png, .pdf, and .sqlite.
• Generated artifacts in paths like dist/, build/, and coverage/.
• Duplicate blobs by SHA-256 content hash.
• Directory, path, and extension budgets.
• npm package payload bloat via npm pack --dry-run --json when available.

Configuration

Run blobbudget init --preset node-cli to create .blobbudget.json:

node-cli is the only supported preset. For scans, --fail-on accepts low, medium, or high; other option values are rejected with usage help.

{
  "maxFileBytes": "512 KiB",
  "maxDirectoryBytes": "2 MiB",
  "maxPackageBytes": "750 KiB",
  "failOn": "medium",
  "pathBudgets": [
    { "pattern": "fixtures/**", "maxBytes": "1 MiB", "severity": "medium" }
  ],
  "extensionBudgets": [
    { "extension": ".json", "maxBytes": "256 KiB", "severity": "medium" }
  ]
}

Sizes accept bytes or human units (KiB, MiB, GiB). Globs are intentionally small and deterministic: , ?, and are supported.

Examples

blobbudget scan . --out blobbudget.md
blobbudget scan fixtures/heavy --format json --fail-on medium
blobbudget scan . --no-package --no-gitignore

Run the fixture-backed demo:

bash demo/run-fixture-budget-demo.sh