deterministic-abstraction-police

Deterministic static analysis for unnecessary abstractions in TypeScript/JavaScript.

Not a style linter. Not complexity theatre. It builds a project graph (AST + references + call edges) and flags structural redundancy: pure wrappers, identity forwarding, single-use helpers, and forwarding chains.

Install

npm install -D deterministic-abstraction-police
# or run once
npx deterministic-abstraction-police

CLIs installed: abstraction-police and dap.

CLI

# check the project (prettier-like)
npx abstraction-police
npx dap

# paths / globs
npx abstraction-police "src/**/*.ts"

# options
npx abstraction-police --min-confidence 50
npx abstraction-police --skip-exported
npx abstraction-police --format json
npx abstraction-police --format compact
npx abstraction-police --verbose
npx abstraction-police --config tsconfig.json
npx abstraction-police --ignore "generated/**,vendor/**"

Exit code 1 when findings exist (eslint-style). Exit code 0 when clean.

Output example

src/users.ts
  12:1  [wrapper]  'saveUser' is a pure identity wrapper around 'repoSave'  85%
           Inline 'saveUser' into its callers (or replace calls with 'repoSave')

Found 1 potential unnecessary abstraction across 1 file (42ms)

What it detects

| Kind | Structural signal | | --- | --- | | wrapper | Body is a single call / return-call | | parameter-forward | All params forwarded unchanged | | identity-forward | Returns param.prop only | | single-use | One call site, small body, not exported | | forwarding-chain | A→B→C… where intermediates only forward | | one-use-pyramid | Single-caller ladder of tiny helpers |

Confidence scoring (deterministic)

Positive signals: wrapper shape, one caller, one callee, identity forward, tiny body, no branching, no locals.

Negative signals: exported, documented, branching, real logic weight, multiple references, recursion.

| Score | Meaning | | --- | --- | | 0–30 | Probably useful | | 30–60 | Review | | 60–100 | Very likely unnecessary |

Programmatic API

import { analyze, formatReport } from "deterministic-abstraction-police";

const result = analyze({
  paths: ["src/**/*.ts"],
  minConfidence: 40,
});

console.log(formatReport(result, { format: "stylish", verbose: true }));

Development

npm install
npm run build
npm run typecheck
npm run lint
npm run format:check
npm test
npm run check

License

MIT