@optiprune/cli

OptiPrune

OptiPrune is a static dead-code analyzer for TypeScript and JavaScript projects. It combines parser-backed module graphs, export and member reachability, dependency and workspace inspection, dynamic-import analysis, semantic contracts, optional symbolic/concolic checks, and source-aware plugins.

The CLI package is @optiprune/cli. The analysis engine is available separately as the headless package @optiprune/core.

Features

Area	What is included
Project analysis	Entry discovery, module graphs, export/member reachability, dependency edges, strongly connected components, and cycle reporting.
TypeScript and JavaScript	.ts, .tsx, .js, .jsx, and .vue extensions by default, with custom extension lists available from the CLI or config.
Dynamic paths	Literal and pattern-based dynamic imports, unresolved-path findings, recovery information, and isolated execution checks.
Logic analysis	Constant conditions, contradictory guards, unreachable statements, and schema-impossible guards.
Dependencies	package.json, scripts, dependency/devDependency usage, package exports, bins, workspace packages, and lockfile-aware context.
Contracts and entries	Public API contracts, schema-aware protection, conventional entries, entry-file exports, test-file handling, and framework/plugin entry points.
Fixes	Opt-in fixes for unreachable files, unused exports and members, dependencies, development dependencies, verified conditions, and safely recoverable package.json JSON. Every fix is confidence-gated and supports dry runs.
Output	Human-readable terminal output, JSON reports with optional structured debug diagnostics, and SARIF output for CI/code-scanning workflows.
Headless usage	analyze, shouldFail, cache helpers, fix helpers, reporters, and public TypeScript types from @optiprune/core.
Plugins	Source-aware adapters for frameworks, build tools, test tools, runtimes, package managers, and workspace conventions.

Installation

Install the CLI as a development dependency:

npm install --save-dev @optiprune/cli
# or
pnpm add -D @optiprune/cli
# or
yarn add -D @optiprune/cli

The Core package currently requires Node.js 20 or newer.

Quick start

Run an analysis from the project root:

npx @optiprune/cli analyze

The default command is analyze, so this is equivalent:

npx @optiprune/cli

Select a machine-readable output format when integrating with tooling:

npx @optiprune/cli analyze --json
npx @optiprune/cli analyze --sarif > optiprune.sarif

Commands

Command	Purpose
analyze [options]	Analyze the project. This is the default command.
export-cache <targetPath>	Export the current analysis cache to a JSON file.
import-cache <sourcePath>	Import an external cache JSON file into the local project cache.
optiprune --help	Print command and option help.
optiprune --version	Print the CLI and detected Core versions.

Analyze flags

Flag	Description	Default
-r, --rootDir <path>	Root directory of the project.	Current working directory
-e, --entry <patterns...>	Entry-point patterns, globs, or file paths.	[]
-x, --extensions <exts...>	File extensions to analyze.	.ts .tsx .js .jsx .vue
-i, --ignore <patterns...>	Glob patterns to ignore.	[]
--no-report-unused-exports	Disable unused-export reporting.	Enabled
--no-conventional-entries	Exclude conventional entries such as src/index.ts.	Included
--include-entry-exports	Report unused exports declared directly in entry files.	Disabled
--include-entry-members	Report unused members declared in objects exported directly from entry files.	Disabled
--cycles	Print detected dependency cycles.	Disabled
--ignore-tests	Ignore test files such as test.ts, *.test.ts, and __tests__.	Disabled
--fail-on <confidence>	Exit non-zero when findings meet the selected confidence level: high, medium, low, or none.	high
--json	Print the structured analysis report as JSON.	Disabled
--sarif	Print SARIF output.	Disabled
--skip <layers...>	Skip analysis layers 3, 4, or smt; smt also skips layer 3.	Disabled
-v, --verbose	Print verbose output and internal graph state; with --json, include structured debug diagnostics in the report.	Disabled
--fix <rules...>	Select fix targets: files, exports, dependencies, devDependencies, conditions, or json.	None
--fix-json	Safely repair recoverable package.json JSON errors; shorthand for --fix json.	Disabled
--plugins <names...>	Force-enable one or more built-in plugins, such as --plugins astro vite vitest. Names may omit the -plugin suffix; unknown names produce Did you mean ...? when a familiar match exists, otherwise No Plugin found with the name ....	Disabled
--confidence <level>	Minimum fix confidence: high, medium+, low+, or all.	high
--force	Allow a selected fix when the source edit is otherwise considered unsafe.	Disabled
--dry-run	Log planned fixes without changing files.	Disabled
--cache-from <path>	Import a JSON cache before analysis.	None
--cache-to <path>	Export the resulting cache after analysis.	None

--confidence, --force, and --dry-run require --fix or --fix-json. Unknown fix targets are rejected before analysis begins. --plugins is repeatable in one invocation and force-enables the named built-in plugins without changing other plugin settings from project configuration.

Fixes

Fixes are explicit rather than implicit. Start with a dry run, inspect the output, then omit --dry-run when the proposed changes are acceptable.

npx @optiprune/cli analyze \
  --fix files exports dependencies devDependencies conditions json \
  --confidence medium+ \
  --dry-run

# Or repair only safe package.json syntax issues
npx @optiprune/cli analyze --fix-json

Target	Applies to
files	Verified unreachable files.
exports	Verified unused exports and members.
dependencies	Unused runtime dependencies.
devDependencies	Unused development dependencies.
conditions	Verified constant conditions.
json	Safe recovery of malformed package.json syntax, including comments, trailing commas, missing commas, and missing closing delimiters. Unsafe forms such as unquoted keys remain unchanged.

--force changes the safety decision for the selected fix operation; it does not make an unverified finding correct. Use it only when the source edit has been reviewed.

Cache

Use cache files to reuse analysis state in local workflows or CI:

npx @optiprune/cli analyze \
  --cache-from .optiprune/cache.json \
  --cache-to .optiprune/cache.json

npx @optiprune/cli export-cache .optiprune/cache.json
npx @optiprune/cli import-cache .optiprune/cache.json

export-cache and import-cache accept -r, --rootDir <path> when the cache belongs to a directory other than the current working directory.

Cache entries are valid only for the same Core version and the same enabled plugin versions by default. A Core update, enabled-plugin update, or change in which plugins are enabled therefore starts a fresh cache. Use --stop-new-cache-on-update when intentionally reusing an existing cache across such updates.

Configuration

OptiPrune reads configuration through the Core loader. Supported sources include:

Source	Notes
optiprune.json	Standard JSON configuration.
optiprune.jsonc	JSON with comments and trailing commas.
optiprune.config.ts	TypeScript configuration with a default export.
optiprune.config.js	JavaScript ESM configuration with a default export.
optiprune.config.mjs	JavaScript ESM configuration with a default export.
package.json#optiprune	Package field configuration.

See config.md for the configuration reference and schema.json for the authoritative schema.

Headless Core API

Use @optiprune/core directly when the CLI is not the right integration boundary:

npm install @optiprune/core

import { analyze, shouldFail } from "@optiprune/core";

const report = await analyze({
  rootDir: process.cwd(),
  entry: ["src/index.ts"],
  output: "json",
});

console.log(report.summary);

if (shouldFail(report, "high")) {
  process.exitCode = 1;
}

The Core package also exposes cache helpers, applyFixes, reporters, and public types:

import { applyFixes, exportCache, importCache } from "@optiprune/core";
import { formatSarif, formatTerminal } from "@optiprune/core/reporters";
import type { AnalysisReport, AnalyzerOptions, Finding } from "@optiprune/core/types";

An AnalysisReport contains summary counts, findings, entry points, module records, exports, dependency edges, and strongly connected components.

Plugin model

Plugins provide source-aware context for frameworks, build tools, test runners, runtimes, package managers, and workspace conventions. They can contribute entry patterns, mark files or packages as used, interpret project metadata, and participate in analysis lifecycle hooks.

Browse the Core plugin directory to inspect the current source-backed set and the AnalyzerPlugin/PluginAdapter contracts.

Development

Build the package from this repository:

npm run build
npm test

The Core repository uses Vitest for its test suite. The workflow badges above reflect the status reported by GitHub Actions rather than a hard-coded claim in this README.

Links

Resource	Link
CLI repository	github.com/optiprune/cli
Core repository	github.com/optiprune/core
CLI package	npmjs.com/package/@optiprune/cli
Core package	npmjs.com/package/@optiprune/core
Documentation site	opti.drml.int.yt
License	MIT