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

Generate a local manpage:

make manpage

The generated manpage is available as docs/man/lopper.1 and is installed automatically by the Homebrew formulas.

Run without local install:

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

Terminal demos

Demo	What it demonstrates	GIF preview
Quick start ranking	End-to-end --top workflow with license, policy, and candidate-score context for fast triage.
Single dependency deep dive	Focused analysis of one dependency with current usage, license, and scoring context.
Baseline gate in CI flow	Baseline comparison with threshold policy and delta summary to catch regression risk in automated checks.

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 CSV for spreadsheet or pipeline ingestion:

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

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

Generate an org-level dashboard across multiple repos:

lopper dashboard \
  --repos "./api,./frontend,./worker" \
  --format html \
  --output org-report.html

Use a dashboard config file:

lopper dashboard --config lopper-org.yml --format json

Languages

• Supported adapters: js-ts, python, cpp, jvm, kotlin-android, go, php, ruby, rust, dotnet, elixir, swift, dart, powershell
• js-ts merges workspace-level declarations from pnpm-workspace.yaml, package.json#workspaces, and Yarn .yarnrc.yml catalogs.
• 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.

Additional guides:

• docs/threshold-tuning.md
• docs/notifications.md
• docs/feature-flags.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 LOPPER_ROOT=/path/to/lopper
export NODE_OPTIONS="--require ${LOPPER_ROOT}/scripts/runtime/require-hook.cjs --loader ${LOPPER_ROOT}/scripts/runtime/loader.mjs"
npm test

Use the hook files from the lopper checkout or install tree. Relative hook paths resolve from the repo running npm test, not from lopper itself.

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. For watched hotspot packages, run make mem-profiles to capture alloc-space summaries before or after performance-sensitive changes.

Docs

• Report schema: docs/report-schema.json, docs/report-schema.md
• Multi-repo dashboard: docs/dashboard.md
• Memory profiling workflow: docs/memory-profiling.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