impact-engine

impact-engine helps developers understand dependency structure and failure surfaces before they break builds.

It provides:

• graph extraction with provenance and ambiguity tracking
• blast radius analysis for dependency removal/change
• structural hotspots (collapse sensitivity)
• diagnostics for version drift, duplicates, peer mismatch, and lockfile inconsistencies

Install

Global install:

npm install -g impact-engine

One-off use without install:

npx impact-engine graph .

With pnpm:

pnpm add -g impact-engine
pnpm dlx impact-engine graph .

Quick Start

Run graph:

impact-engine graph .
impact-engine graph . --json

Run blast radius:

impact-engine blast lodash --path .
impact-engine blast lodash --path . --json

Run collapse sensitivity hotspots:

impact-engine hotspots .
impact-engine hotspots . --json

Run dependency doctor:

impact-engine doctor .
impact-engine doctor . --json

Unified JSON Report

All commands with --json emit the same top-level schema:

• schemaVersion
• generatedAt
• project
• graph
• blast
• hotspots
• findings
• summary

Schema definitions are implemented in src/core/report-schema.ts and generated in src/core/report-builder.ts.

findings supports:

• duplicate_versions
• lockfile_manifest_drift
• incompatible_version_ranges
• unsatisfied_peer_dependency
• engine_incompatibility
• optional_dependency_risk
• orphan_dependency

Current Scope

• Lockfile-first structural analysis (npm package-lock v2+ supported)
• Static analysis only (no runtime performance/failure simulation)
• Deterministic ordering for machine consumption

Development

npm install
npm run check

npm run build
npm test

Release Smoke Tests

Validate that the packaged CLI can install and run from a clean environment:

npm run smoke:tarball
npm run smoke:pnpm

Validate what users will experience from npm on another machine:

npx impact-engine@latest --help
npx impact-engine@latest graph . --json
pnpm dlx impact-engine@latest --help
pnpm dlx impact-engine@latest graph . --json

If these succeed, install and one-off execution paths are healthy.