optiprune 2.2.21 → 2.2.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +168 -89
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,131 +1,210 @@
|
|
|
1
|
-
|
|
3
|
-
|
|
1
|
+
|
|
4
2
|
|
|
5
|
-
|
|
6
|
-
---
|
|
3
|
+
[](https://www.npmjs.com/package/@optiprune/cli)[](https://www.npmjs.com/package/@optiprune/core)[](https://github.com/optiprune/cli)[](https://github.com/optiprune/core/actions/workflows/tests.yml)[](./LICENSE)[](https://nodejs.org/)
|
|
7
4
|
|
|
8
|
-
|
|
9
|
-
Most dead-code analyzers just guess. They look at import graphs and hope they don't miss anything critical. This leads to **false positives**, broken builds, and developer frustration.
|
|
5
|
+
# OptiPrune
|
|
10
6
|
|
|
11
|
-
|
|
7
|
+
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.
|
|
12
8
|
|
|
13
|
-
|
|
9
|
+
The CLI package is `@optiprune/cli`. The analysis engine is available separately as the headless package `@optiprune/core`.
|
|
14
10
|
|
|
15
|
-
|
|
11
|
+
## Features
|
|
16
12
|
|
|
17
|
-
|
|
13
|
+
| Area | What is included |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| Project analysis | Entry discovery, module graphs, export/member reachability, dependency edges, strongly connected components, and cycle reporting. |
|
|
16
|
+
| TypeScript and JavaScript | `.ts`, `.tsx`, `.js`, `.jsx`, and `.vue` extensions by default, with custom extension lists available from the CLI or config. |
|
|
17
|
+
| Dynamic paths | Literal and pattern-based dynamic imports, unresolved-path findings, recovery information, and isolated execution checks. |
|
|
18
|
+
| Logic analysis | Constant conditions, contradictory guards, unreachable statements, and schema-impossible guards. |
|
|
19
|
+
| Dependencies | `package.json`, scripts, dependency/devDependency usage, package exports, bins, workspace packages, and lockfile-aware context. |
|
|
20
|
+
| Contracts and entries | Public API contracts, schema-aware protection, conventional entries, entry-file exports, test-file handling, and framework/plugin entry points. |
|
|
21
|
+
| Fixes | Opt-in fixes for unreachable files, unused exports and members, dependencies, development dependencies, and verified conditions. Every fix is confidence-gated and supports dry runs. |
|
|
22
|
+
| Output | Human-readable terminal output, JSON reports, and SARIF output for CI/code-scanning workflows. |
|
|
23
|
+
| Headless usage | `analyze`, `shouldFail`, cache helpers, fix helpers, reporters, and public TypeScript types from `@optiprune/core`. |
|
|
24
|
+
| Plugins | Source-aware adapters for frameworks, build tools, test tools, runtimes, package managers, and workspace conventions. |
|
|
18
25
|
|
|
19
|
-
|
|
20
|
-
While other tools are throttled by the N-API bottleneck, OptiPrune utilizes the **Yuku Engine** written in **Zig**. It minimizes the overhead between native performance and the JavaScript runtime.
|
|
21
|
-
* **The Result:** Up to 3x faster parsing than traditional tools, even in massive monorepos.
|
|
26
|
+
## Installation
|
|
22
27
|
|
|
23
|
-
|
|
24
|
-
OptiPrune is the first analyzer to use a real **SMT Solver (Z3)**. We don't just analyze if a function is exported; we analyze if the code *inside* the function is logically reachable.
|
|
25
|
-
* **The Result:** Detects dead logic paths (e.g., impossible `if` conditions) that are completely invisible to Knip.
|
|
28
|
+
Install the CLI as a development dependency:
|
|
26
29
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
+
```bash
|
|
31
|
+
npm install --save-dev @optiprune/cli
|
|
32
|
+
# or
|
|
33
|
+
pnpm add -D @optiprune/cli
|
|
34
|
+
# or
|
|
35
|
+
yarn add -D @optiprune/cli
|
|
36
|
+
```
|
|
30
37
|
|
|
31
|
-
|
|
38
|
+
The Core package currently requires Node.js 21 or newer.
|
|
32
39
|
|
|
33
|
-
##
|
|
40
|
+
## Quick start
|
|
34
41
|
|
|
35
|
-
|
|
36
|
-
| :--- | :--- | :--- |
|
|
37
|
-
| **Engine** | Babel / OXC (Standard) | **Yuku / Zig (Hyper-Speed)** |
|
|
38
|
-
| **Logic Analysis** | Heuristics (Guessing) | **Z3 SMT Solver (Proving)** |
|
|
39
|
-
| **Dynamic Paths** | Pattern Matching | **WASM Sandbox Execution** |
|
|
40
|
-
| **Interface Audit** | Ignores Members | **Deep Member-Level Analysis** |
|
|
41
|
-
| **Framework Support** | Plugins (Core-Level) | **7-Layer Semantic Context** |
|
|
42
|
-
| **False Positives** | High (in complex setups) | **Near-Zero (Context Aware)** |
|
|
42
|
+
Run an analysis from the project root:
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
```bash
|
|
45
|
+
npx @optiprune/cli analyze
|
|
46
|
+
```
|
|
45
47
|
|
|
46
|
-
|
|
47
|
-
OptiPrune operates in seven specialized layers to guarantee maximum accuracy:
|
|
48
|
+
The default command is `analyze`, so this is equivalent:
|
|
48
49
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
4. **Layer 4: WASM Sandbox** – Dynamic path resolution via execution.
|
|
53
|
-
5. **Layer 6: Schema Shield** – Protection for Zod, Decorators & Contracts.
|
|
54
|
-
6. **Layer 6: Dependency Audit** – Scans lockfiles & package.json scripts.
|
|
55
|
-
7. **Layer 7: Topology Engine** – Understands NestJS DI & Event Buses.
|
|
50
|
+
```bash
|
|
51
|
+
npx @optiprune/cli
|
|
52
|
+
```
|
|
56
53
|
|
|
57
|
-
|
|
54
|
+
Select a machine-readable output format when integrating with tooling:
|
|
58
55
|
|
|
59
|
-
|
|
60
|
-
|
|
56
|
+
```bash
|
|
57
|
+
npx @optiprune/cli analyze --json
|
|
58
|
+
npx @optiprune/cli analyze --sarif > optiprune.sarif
|
|
59
|
+
```
|
|
61
60
|
|
|
62
|
-
|
|
63
|
-
* **OptiPrune Speed:** **0.87s** (Stable & Precise)
|
|
64
|
-
* **Accuracy:** OptiPrune found **15% more** real dead code (unused interface properties & logical errors) that Knip completely missed.
|
|
61
|
+
## Commands
|
|
65
62
|
|
|
66
|
-
|
|
63
|
+
| Command | Purpose |
|
|
64
|
+
| --- | --- |
|
|
65
|
+
| `analyze [options]` | Analyze the project. This is the default command. |
|
|
66
|
+
| `export-cache <targetPath>` | Export the current analysis cache to a JSON file. |
|
|
67
|
+
| `import-cache <sourcePath>` | Import an external cache JSON file into the local project cache. |
|
|
68
|
+
| `optiprune --help` | Print command and option help. |
|
|
69
|
+
| `optiprune --version` | Print the CLI and detected Core versions. |
|
|
67
70
|
|
|
68
|
-
##
|
|
71
|
+
## Analyze flags
|
|
69
72
|
|
|
70
|
-
|
|
73
|
+
| Flag | Description | Default |
|
|
74
|
+
| --- | --- | --- |
|
|
75
|
+
| `-r, --rootDir <path>` | Root directory of the project. | Current working directory |
|
|
76
|
+
| `-e, --entry <patterns...>` | Entry-point patterns, globs, or file paths. | `[]` |
|
|
77
|
+
| `-x, --extensions <exts...>` | File extensions to analyze. | `.ts .tsx .js .jsx .vue` |
|
|
78
|
+
| `-i, --ignore <patterns...>` | Glob patterns to ignore. | `[]` |
|
|
79
|
+
| `--no-report-unused-exports` | Disable unused-export reporting. | Enabled |
|
|
80
|
+
| `--no-conventional-entries` | Exclude conventional entries such as `src/index.ts`. | Included |
|
|
81
|
+
| `--include-entry-exports` | Report unused exports declared directly in entry files. | Disabled |
|
|
82
|
+
| `--cycles` | Print detected dependency cycles. | Disabled |
|
|
83
|
+
| `--ignore-tests` | Ignore test files such as `test.ts`, `*.test.ts`, and `__tests__`. | Disabled |
|
|
84
|
+
| `--fail-on <confidence>` | Exit non-zero when findings meet the selected confidence level: `high`, `medium`, `low`, or `none`. | `high` |
|
|
85
|
+
| `--json` | Print the structured analysis report as JSON. | Disabled |
|
|
86
|
+
| `--sarif` | Print SARIF output. | Disabled |
|
|
87
|
+
| `--skip-3` | Skip the SMT constraint-analysis layer. | Disabled |
|
|
88
|
+
| `--skip-4` | Skip the concolic execution-proof layer. | Disabled |
|
|
89
|
+
| `-v, --verbose` | Print verbose output and internal graph state. | Disabled |
|
|
90
|
+
| `--fix <rules...>` | Select fix targets: `files`, `exports`, `dependencies`, `devDependencies`, or `conditions`. | None |
|
|
91
|
+
| `--confidence <level>` | Minimum fix confidence: `high`, `medium+`, or `low+`. | `high` |
|
|
92
|
+
| `--force` | Allow a selected fix when the source edit is otherwise considered unsafe. | Disabled |
|
|
93
|
+
| `--dry-run` | Log planned fixes without changing files. | Disabled |
|
|
94
|
+
| `--cache-from <path>` | Import a JSON cache before analysis. | None |
|
|
95
|
+
| `--cache-to <path>` | Export the resulting cache after analysis. | None |
|
|
96
|
+
|
|
97
|
+
`--confidence`, `--force`, and `--dry-run` require `--fix`. Unknown fix targets are rejected before analysis begins.
|
|
98
|
+
|
|
99
|
+
## Fixes
|
|
100
|
+
|
|
101
|
+
Fixes are explicit rather than implicit. Start with a dry run, inspect the output, then omit `--dry-run` when the proposed changes are acceptable.
|
|
71
102
|
|
|
72
103
|
```bash
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
104
|
+
npx @optiprune/cli analyze \
|
|
105
|
+
--fix files exports dependencies devDependencies conditions \
|
|
106
|
+
--confidence medium+ \
|
|
107
|
+
--dry-run
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
| Target | Applies to |
|
|
111
|
+
| --- | --- |
|
|
112
|
+
| `files` | Verified unreachable files. |
|
|
113
|
+
| `exports` | Verified unused exports and members. |
|
|
114
|
+
| `dependencies` | Unused runtime dependencies. |
|
|
115
|
+
| `devDependencies` | Unused development dependencies. |
|
|
116
|
+
| `conditions` | Verified constant conditions. |
|
|
78
117
|
|
|
79
|
-
|
|
118
|
+
`--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.
|
|
80
119
|
|
|
81
|
-
##
|
|
120
|
+
## Cache
|
|
82
121
|
|
|
83
|
-
|
|
122
|
+
Use cache files to reuse analysis state in local workflows or CI:
|
|
84
123
|
|
|
85
124
|
```bash
|
|
86
|
-
npx @optiprune/cli
|
|
125
|
+
npx @optiprune/cli analyze \
|
|
126
|
+
--cache-from .optiprune/cache.json \
|
|
127
|
+
--cache-to .optiprune/cache.json
|
|
128
|
+
|
|
129
|
+
npx @optiprune/cli export-cache .optiprune/cache.json
|
|
130
|
+
npx @optiprune/cli import-cache .optiprune/cache.json
|
|
87
131
|
```
|
|
88
132
|
|
|
89
|
-
|
|
133
|
+
`export-cache` and `import-cache` accept `-r, --rootDir <path>` when the cache belongs to a directory other than the current working directory.
|
|
90
134
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
|
|
|
98
|
-
|
|
|
99
|
-
|
|
|
100
|
-
|
|
|
101
|
-
|
|
|
102
|
-
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
135
|
+
## Configuration
|
|
136
|
+
|
|
137
|
+
OptiPrune reads configuration through the Core loader. Supported sources include:
|
|
138
|
+
|
|
139
|
+
| Source | Notes |
|
|
140
|
+
| --- | --- |
|
|
141
|
+
| `optiprune.json` | Standard JSON configuration. |
|
|
142
|
+
| `optiprune.jsonc` | JSON with comments and trailing commas. |
|
|
143
|
+
| `optiprune.config.ts` | TypeScript configuration with a default export. |
|
|
144
|
+
| `optiprune.config.js` | JavaScript ESM configuration with a default export. |
|
|
145
|
+
| `optiprune.config.mjs` | JavaScript ESM configuration with a default export. |
|
|
146
|
+
| `package.json#optiprune` | Package field configuration. |
|
|
147
|
+
|
|
148
|
+
See [`config.md`](./config.md) for the configuration reference and [`schema.json`](https://github.com/optiprune/core/blob/main/schema.json) for the authoritative schema.
|
|
149
|
+
|
|
150
|
+
## Headless Core API
|
|
151
|
+
|
|
152
|
+
Use `@optiprune/core` directly when the CLI is not the right integration boundary:
|
|
108
153
|
|
|
109
154
|
```bash
|
|
110
|
-
|
|
155
|
+
npm install @optiprune/core
|
|
111
156
|
```
|
|
112
157
|
|
|
113
|
-
|
|
158
|
+
```
|
|
159
|
+
import { analyze, shouldFail } from "@optiprune/core";
|
|
114
160
|
|
|
115
|
-
|
|
116
|
-
|
|
161
|
+
const report = await analyze({
|
|
162
|
+
rootDir: process.cwd(),
|
|
163
|
+
entry: ["src/index.ts"],
|
|
164
|
+
output: "json",
|
|
165
|
+
});
|
|
166
|
+
|
|
167
|
+
console.log(report.summary);
|
|
168
|
+
|
|
169
|
+
if (shouldFail(report, "high")) {
|
|
170
|
+
process.exitCode = 1;
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
The Core package also exposes cache helpers, `applyFixes`, reporters, and public types:
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
import { applyFixes, exportCache, importCache } from "@optiprune/core";
|
|
178
|
+
import { formatSarif, formatTerminal } from "@optiprune/core/reporters";
|
|
179
|
+
import type { AnalysisReport, AnalyzerOptions, Finding } from "@optiprune/core/types";
|
|
117
180
|
```
|
|
118
181
|
|
|
119
|
-
|
|
182
|
+
An `AnalysisReport` contains summary counts, findings, entry points, module records, exports, dependency edges, and strongly connected components.
|
|
183
|
+
|
|
184
|
+
## Plugin model
|
|
185
|
+
|
|
186
|
+
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.
|
|
120
187
|
|
|
121
|
-
|
|
188
|
+
Browse the [Core plugin directory](https://github.com/optiprune/core/tree/main/src/plugins) to inspect the current source-backed set and the `AnalyzerPlugin`/`PluginAdapter` contracts.
|
|
189
|
+
|
|
190
|
+
## Development
|
|
191
|
+
|
|
192
|
+
Build the package from this repository:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
npm run build
|
|
196
|
+
npm test
|
|
197
|
+
```
|
|
122
198
|
|
|
123
|
-
|
|
124
|
-
OptiPrune isn't just a tool. It's a technical statement. Help us save the world from dirty code.
|
|
199
|
+
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.
|
|
125
200
|
|
|
126
|
-
|
|
127
|
-
**Web:** [opti.drml.int.yt](https://opti.drml.int.yt)
|
|
201
|
+
## Links
|
|
128
202
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
203
|
+
| Resource | Link |
|
|
204
|
+
| --- | --- |
|
|
205
|
+
| CLI repository | [github.com/optiprune/cli](https://github.com/optiprune/cli) |
|
|
206
|
+
| Core repository | [github.com/optiprune/core](https://github.com/optiprune/core) |
|
|
207
|
+
| CLI package | [npmjs.com/package/@optiprune/cli](https://www.npmjs.com/package/@optiprune/cli) |
|
|
208
|
+
| Core package | [npmjs.com/package/@optiprune/core](https://www.npmjs.com/package/@optiprune/core) |
|
|
209
|
+
| Documentation site | [opti.drml.int.yt](https://opti.drml.int.yt/) |
|
|
210
|
+
| License | [MIT](./LICENSE) |
|