lopper

README

Lopper

Lopper is a local-first CLI/TUI for measuring dependency surface area in source repos. It compares imported dependencies to actual usage and reports waste, risk cues, and recommendations.

Install

macOS/Linux (Homebrew tap, stable):

brew tap ben-ranford/tap
brew install lopper

macOS/Linux (Homebrew tap, rolling):

brew install ben-ranford/tap/lopper-rolling

lopper-rolling tracks main and is not a stable semver release.

Windows (GitHub Releases):

# Open latest release page and download the Windows asset for your platform.
gh release view --repo ben-ranford/lopper --web

Run without local install:

docker run --rm ghcr.io/ben-ranford/lopper:latest --help

Quick Start

Analyze one dependency:

lopper analyse lodash --repo . --language js-ts

Rank top dependencies by waste:

lopper analyse --top 20 --repo . --language all --format table

Emit JSON:

lopper analyse --top 20 --repo . --language all --format json

Emit SARIF for code scanning:

lopper analyse --top 20 --repo . --language all --format sarif > lopper.sarif

Launch the interactive TUI:

lopper tui --repo . --language all

Tune thresholds and score weights:

lopper analyse --top 20 \
  --repo . \
  --language all \
  --threshold-fail-on-increase 2 \
  --threshold-low-confidence-warning 35 \
  --threshold-min-usage-percent 45 \
  --score-weight-usage 0.50 \
  --score-weight-impact 0.30 \
  --score-weight-confidence 0.20

Save an immutable baseline snapshot keyed by commit:

lopper analyse --top 20 \
  --repo . \
  --language all \
  --format json \
  --baseline-store .artifacts/lopper-baselines \
  --save-baseline

Save using a human label key:

lopper analyse --top 20 \
  --repo . \
  --language all \
  --format json \
  --baseline-store .artifacts/lopper-baselines \
  --save-baseline \
  --baseline-label release-candidate

Compare against a stored baseline key and gate CI:

lopper analyse --top 20 \
  --repo . \
  --language all \
  --format json \
  --baseline-store .artifacts/lopper-baselines \
  --baseline-key commit:abc123 \
  --threshold-fail-on-increase 2

Terminal demos

Demo	What it demonstrates	GIF preview
Quick start ranking	End-to-end --top workflow and waste-ranked dependency table for fast triage.
Single dependency deep dive	Focused analysis of one dependency with detailed usage signal and recommendation context.
Baseline gate in CI flow	Baseline comparison and increase gating to catch regression risk in automated checks.

Languages

• Supported adapters: js-ts, python, cpp, jvm, go, php, ruby, rust, dotnet, elixir
• Source of truth for adapter IDs: lopper --help
• Language modes:
  • auto: choose highest-confidence adapter
  • all: run all matching adapters and merge results
  • <id>: force one adapter

Repo-level config example (.lopper.yml):

policy:
  packs:
    - ./policies/org-defaults.yml
    - https://example.com/lopper/policy.yml#sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
thresholds:
  fail_on_increase_percent: 2
  low_confidence_warning_percent: 35
  min_usage_percent_for_recommendations: 45
  removal_candidate_weight_usage: 0.50
  removal_candidate_weight_impact: 0.30
  removal_candidate_weight_confidence: 0.20

Threshold defaults:

• fail_on_increase_percent: 0 (disabled unless set above 0)
• low_confidence_warning_percent: 40
• min_usage_percent_for_recommendations: 40
• removal_candidate_weight_usage: 0.50
• removal_candidate_weight_impact: 0.30
• removal_candidate_weight_confidence: 0.20

Threshold ranges:

• fail_on_increase_percent must be >= 0
• low_confidence_warning_percent must be between 0 and 100
• min_usage_percent_for_recommendations must be between 0 and 100
• removal candidate weights must be >= 0 and at least one must be greater than 0

Precedence is CLI > repo config > imported policy packs > defaults.

Tuning guide with strict/balanced/noise-reduction profiles:

• docs/threshold-tuning.md

Launch TUI:

lopper tui --repo . --language all

Runtime trace annotations (JS/TS)

Capture a runtime trace:

export LOPPER_RUNTIME_TRACE=.artifacts/lopper-runtime.ndjson
export NODE_OPTIONS="--require ./scripts/runtime/require-hook.cjs --loader ./scripts/runtime/loader.mjs"
npm test

Or let Lopper run the test command and capture the trace automatically:

lopper analyse --top 20 --repo . --language js-ts --runtime-test-command "npm test"

Use trace in analysis:

lopper analyse --top 20 --repo . --language js-ts --runtime-trace .artifacts/lopper-runtime.ndjson

With runtime traces enabled:

• runtimeUsage.correlation marks each JS/TS dependency as static-only, runtime-only, or overlap.
• runtimeUsage.modules includes runtime-loaded module paths.
• runtimeUsage.topSymbols includes best-effort runtime symbol hits.

If --runtime-trace points to a missing file, analysis continues with static results and adds a warning.

Development

See CONTRIBUTING.md for development setup and commands.

Docs

• Report schema: docs/report-schema.json, docs/report-schema.md
• SARIF code scanning: docs/sarif-code-scanning.md
• Threshold tuning: docs/threshold-tuning.md
• Runtime trace annotations: scripts/runtime/
• Adapter and architecture extensibility: docs/extensibility.md
• CI and release workflow: docs/ci-usage.md
• Contribution guide: CONTRIBUTING.md