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.
| 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. |
Install the CLI as a development dependency:
npm install --save-dev @optiprune/cli
# or
pnpm add -D @optiprune/cli
# or
yarn add -D @optiprune/cliThe Core package currently requires Node.js 21 or newer.
Run an analysis from the project root:
npx @optiprune/cli analyzeThe default command is analyze, so this is equivalent:
npx @optiprune/cliSelect a machine-readable output format when integrating with tooling:
npx @optiprune/cli analyze --json
npx @optiprune/cli analyze --sarif > optiprune.sarif| 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. |
| 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-3 | Skip the SMT constraint-analysis layer. | Disabled |
--skip-4 | Skip the concolic execution-proof layer. | 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 |
--node-llama-cpp | Force-enable the dedicated node-llama-cpp semantic analysis plugin. | 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.
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.
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.jsonexport-cache and import-cache accept -r, --rootDir <path> when the cache belongs to a directory other than the current working directory.
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.
Use @optiprune/core directly when the CLI is not the right integration boundary:
npm install @optiprune/coreimport { 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.
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.
Build the package from this repository:
npm run build
npm testThe 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.
| 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 |