kyle-reese

kyle-reese finds JavaScript and TypeScript functions that have grown too hard to reason about. It audits three function-level metrics and can apply a narrow set of verified refactors.

The default health contract is:

• cyclomatic complexity < 22;
• cognitive complexity < 22;
• Halstead difficulty < 80.

The limits are exclusive. A value of 22 fails a < 22 limit.

Install from GitHub

The package has not been published to npm yet. Install it directly from this repository:

npm install --save-dev github:ddoug220/kyle-reese

Run the first audit from your project root:

npx kyle-reese audit .

The command exits with 0 when every parsed function passes, 1 for metric or parse failures, and 2 for command or configuration errors.

Read the report

Text output lists the 50 worst functions by default:

Scanned 148 functions in 23 files.
Limits are strict: cyclomatic < 22, cognitive < 22, Halstead difficulty < 80.

Violations (2 functions):
  src/planner.ts:48:1 planWork — cyclomatic=27, cognitive=31
  src/parser.ts:92:1 parseInput — halstead=84.5

Limit the text report or emit complete JSON:

npx kyle-reese audit . --limit 10
npx kyle-reese audit . --json

Apply verified fixes

Fix mode extracts eligible branch-bearing statements into local arrow functions. The refactor preserves closure access, lexical this, execution order, and thrown errors.

Every written edit requires a verification command. kyle-reese runs the command after each edit and restores an edit when verification fails.

npx kyle-reese fix . \
  --check-command '["npm","test"]'

Inspect one proposed extraction without writing files:

npx kyle-reese fix . --dry-run

Fix mode refuses to move returns, jumps, await, yield, declarations whose scope would change, labels, function-scoped var, or direct eval. It stops and reports remaining violations when it cannot prove a conservative extraction is available. See Fix-mode safety for the complete contract.

Configure a project

Create kyle-reese.config.json in the project root:

{
  "thresholds": {
    "cyclomatic": 22,
    "cognitive": 22,
    "halsteadDifficulty": 80
  },
  "include": ["src/**/*.{js,jsx,ts,tsx}"],
  "exclude": ["**/*.generated.ts", "**/fixtures/**"],
  "fix": {
    "checkCommand": ["npm", "test"],
    "maxPasses": 50
  }
}

Command-line thresholds override configuration values:

npx kyle-reese audit . --cyclomatic 18 --cognitive 20 --halstead 70

Run in continuous integration

Add a script to the audited project's package.json:

{
  "scripts": {
    "audit:complexity": "kyle-reese audit ."
  }
}

Run npm run audit:complexity in CI. Metric failures produce exit code 1, so the job fails without extra glue code.

Use the library interface

import { auditProject, fixProject } from 'kyle-reese';

const report = await auditProject({
  root: process.cwd(),
  thresholds: {
    cyclomatic: 22,
    cognitive: 22,
    halsteadDifficulty: 80,
  },
});

const result = await fixProject({
  root: process.cwd(),
  checkCommand: ['npm', 'test'],
});

The library returns data instead of printing or exiting. See Metric definitions for the counting rules and JSON fields.

CLI reference

kyle-reese <audit|fix> [path] [options]

--cyclomatic <n>       Require cyclomatic complexity to be less than n.
--cognitive <n>        Require cognitive complexity to be less than n.
--halstead <n>         Require Halstead difficulty to be less than n.
--config <path>        Read a config file relative to the project root.
--json                 Print machine-readable JSON.
--limit <n>            Limit violations in text output.
--dry-run              Show one safe extraction without writing it.
--check-command <json> Verification command required by fix mode.
--max-passes <n>       Set the maximum verified edits in one run.
--help                 Show command help.

Develop and contribute

The project requires Node.js 20 or newer.

git clone https://github.com/ddoug220/kyle-reese.git
cd kyle-reese
npm ci
npm run verify

Read CONTRIBUTING.md before changing metric rules or fix safety. Security reports belong in a private GitHub security advisory, not a public issue.

License

MIT