dep-oracle 1.1.0 → 1.1.2

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.
Files changed (8) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +388 -210
  3. package/README.tr.md +274 -115
  4. package/dist/cli/index.js +1 -1
  5. package/dist/cli/index.js.map +1 -1
  6. package/dist/mcp/server.js +14 -1
  7. package/dist/mcp/server.js.map +1 -1
  8. package/package.json +2 -1
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Ertugrul Akben
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ertugrul Akben
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,210 +1,388 @@
1
- 🌍 **English** | [Turkce](README.tr.md)
2
-
3
- # dep-oracle 🔮
4
-
5
- > Your dependencies have dependencies. Who's watching them?
6
-
7
- **dep-oracle** is a predictive dependency security engine that calculates **Trust Scores** (0-100) for every package in your dependency tree. It detects zombie dependencies, measures blast radius, catches typosquatting attempts, and predicts future risks — before they become vulnerabilities.
8
-
9
- [![npm version](https://img.shields.io/npm/v/dep-oracle.svg)](https://www.npmjs.com/package/dep-oracle)
10
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
11
-
12
- ## Why?
13
-
14
- - **62% of breaches** in 2025 came from supply chain attacks
15
- - The average project has **683 transitive dependencies**
16
- - `npm audit` only catches **known** CVEs — dep-oracle **predicts** future risks
17
- - You audit your code. But do you audit your **trust**?
18
-
19
- **Claude Code Security** scans YOUR code. **dep-oracle** scans everything your code **depends on**.
20
-
21
- ## Quick Start
22
-
23
- ```bash
24
- # Zero install — just run it
25
- npx dep-oracle
26
-
27
- # Or install globally
28
- npm install -g dep-oracle
29
- dep-oracle scan
30
- ```
31
-
32
- ## What It Does
33
-
34
- | Feature | Description |
35
- |---------|-------------|
36
- | **Trust Score** | 0-100 weighted score per package (maintainer health, security, activity, popularity, funding, license) |
37
- | **Zombie Detection** | Finds unmaintained but critical packages (no commits in 12+ months) |
38
- | **Blast Radius** | Shows how many files are affected if a dependency is compromised |
39
- | **Typosquat Detection** | Catches suspicious package names similar to popular packages |
40
- | **Trend Prediction** | 3-month risk projection based on download/commit trends |
41
- | **Migration Advisor** | Suggests safer alternatives for risky dependencies |
42
- | **Offline Mode** | Works from cache without internet (`--offline`) |
43
-
44
- ## Usage
45
-
46
- ```bash
47
- # Scan current project
48
- dep-oracle scan
49
-
50
- # Scan with specific output
51
- dep-oracle scan --format json
52
- dep-oracle scan --format html
53
- dep-oracle scan --format sarif
54
-
55
- # Check a single package
56
- dep-oracle check lodash
57
-
58
- # Offline mode (uses cached data)
59
- dep-oracle scan --offline
60
-
61
- # Set minimum score threshold (CI/CD)
62
- dep-oracle scan --threshold 60
63
-
64
- # Ignore specific packages
65
- dep-oracle scan --ignore deprecated-but-needed,legacy-pkg
66
- ```
67
-
68
- ## Output Example
69
-
70
- ```
71
- 🔮 dep-oracle v1.0.0
72
- Scanning package.json...
73
- Found 47 direct dependencies, 683 transitive
74
- Collecting data... [=============================] 100% (2.3s)
75
-
76
- DEPENDENCY TRUST REPORT
77
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
78
-
79
- 🚫 CRITICAL (score < 50)
80
-
81
- ■ event-stream@3.3.6 Score: 12 💀 ZOMBIE
82
- Last commit: 2018 | 0 maintainers active
83
- Blast radius: 14 files | Alternative: highland
84
-
85
- ⚠ WARNING (score 50-79)
86
-
87
- ■ moment@2.29.4 Score: 58 💀 ZOMBIE
88
- Maintenance mode | No new features
89
- Blast radius: 23 files | Alternative: dayjs
90
-
91
- ✅ SAFE (score 80+): 679 packages
92
-
93
- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
94
- SUMMARY
95
- Overall Trust Score: 74/100
96
- Critical: 2 | Warning: 3 | Safe: 679
97
- Zombies: 2 | Deprecated: 1
98
- ```
99
-
100
- ## Trust Score Algorithm
101
-
102
- Each package is scored 0-100 based on six weighted metrics:
103
-
104
- | Metric | Weight | What It Measures |
105
- |--------|--------|------------------|
106
- | Security History | 25% | CVE count, average patch time, vulnerability density |
107
- | Maintainer Health | 25% | Active maintainers (bus factor), issue response time, PR merge speed |
108
- | Activity | 20% | Commit frequency trend, release cadence, last publish date |
109
- | Popularity | 15% | Weekly downloads, dependent count, GitHub stars |
110
- | Funding | 10% | GitHub Sponsors, OpenCollective, corporate backing |
111
- | License | 5% | MIT/Apache = safe, GPL = risk, Unknown = red flag |
112
-
113
- **Score Ranges:** 80-100 ✅ Safe | 50-79 ⚠️ Warning | 0-49 🚫 Critical
114
-
115
- ## Claude Code Integration (MCP)
116
-
117
- dep-oracle works as an MCP server for Claude Code:
118
-
119
- ```json
120
- // .claude/settings.json
121
- {
122
- "mcpServers": {
123
- "dep-oracle": {
124
- "command": "npx",
125
- "args": ["dep-oracle", "mcp"]
126
- }
127
- }
128
- }
129
- ```
130
-
131
- Then in Claude Code, just ask:
132
- - "What's the riskiest dependency in this project?"
133
- - "Is lodash safe to use?"
134
- - "Show me zombie dependencies"
135
-
136
- ## GitHub Action
137
-
138
- ```yaml
139
- name: Dependency Trust Check
140
- on: [pull_request]
141
-
142
- jobs:
143
- dep-oracle:
144
- runs-on: ubuntu-latest
145
- steps:
146
- - uses: actions/checkout@v4
147
- - uses: ertugrulakben/dep-oracle-action@v1
148
- with:
149
- threshold: 60
150
- format: sarif
151
- ```
152
-
153
- ## Configuration
154
-
155
- Create `.dep-oraclerc.json` in your project root:
156
-
157
- ```json
158
- {
159
- "threshold": 60,
160
- "ignore": ["known-risky-but-needed"],
161
- "format": "terminal",
162
- "offline": false,
163
- "githubToken": "$GITHUB_TOKEN",
164
- "cacheTtl": 86400
165
- }
166
- ```
167
-
168
- Or add to `package.json`:
169
-
170
- ```json
171
- {
172
- "dep-oracle": {
173
- "threshold": 60,
174
- "ignore": []
175
- }
176
- }
177
- ```
178
-
179
- ## Supported Package Managers
180
-
181
- | Manager | Manifest | Lock File | Status |
182
- |---------|----------|-----------|--------|
183
- | npm | `package.json` | `package-lock.json` | ✅ Supported |
184
- | yarn | `package.json` | `yarn.lock` | ✅ Supported |
185
- | pnpm | `package.json` | `pnpm-lock.yaml` | ✅ Supported |
186
- | pip | `requirements.txt` | `Pipfile.lock` | ✅ Supported |
187
- | poetry | `pyproject.toml` | `poetry.lock` | ✅ Supported |
188
-
189
- ## Comparison
190
-
191
- | Feature | npm audit | Dependabot | Socket.dev | Snyk | **dep-oracle** |
192
- |---------|-----------|------------|------------|------|----------------|
193
- | Known CVE scan | ✅ | ✅ | ✅ | ✅ | ✅ |
194
- | Predictive risk | ❌ | ❌ | Partial | ❌ | **✅** |
195
- | Trust Score (0-100) | ❌ | ❌ | ❌ | ❌ | **✅** |
196
- | Zombie detection | ❌ | ❌ | ❌ | ❌ | **✅** |
197
- | Blast radius | ❌ | ❌ | ❌ | ❌ | **✅** |
198
- | Typosquat detection | ❌ | ❌ | ✅ | ❌ | **✅** |
199
- | Trend prediction | ❌ | ❌ | ❌ | ❌ | **✅** |
200
- | MCP integration | ❌ | ❌ | ✅ | ✅ | **✅** |
201
- | Zero install (npx) | ✅ | ❌ | ❌ | ❌ | **✅** |
202
- | Free | ✅ | ✅ | Freemium | Freemium | **✅** |
203
-
204
- ## Contributing
205
-
206
- See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and how to add new collectors/parsers.
207
-
208
- ## License
209
-
210
- [MIT](LICENSE) — Ertugrul Akben
1
+ <p align="center">
2
+ <img src="cover.jpeg" alt="dep-oracle cover" width="100%">
3
+ </p>
4
+
5
+ <p align="center">
6
+ <h1 align="center">dep-oracle</h1>
7
+ <p align="center"><strong>Predictive Dependency Security Engine</strong></p>
8
+ <p align="center">
9
+ <a href="https://www.npmjs.com/package/dep-oracle"><img src="https://img.shields.io/npm/v/dep-oracle.svg" alt="npm version"></a>
10
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
11
+ <a href="https://www.npmjs.com/package/dep-oracle"><img src="https://img.shields.io/npm/dm/dep-oracle.svg" alt="npm downloads"></a>
12
+ <a href="https://github.com/ertugrulakben/dep-oracle"><img src="https://img.shields.io/github/stars/ertugrulakben/dep-oracle.svg?style=social" alt="GitHub stars"></a>
13
+ <a href="https://modelcontextprotocol.io/registry"><img src="https://img.shields.io/badge/MCP-Registry-blue" alt="MCP Registry"></a>
14
+ </p>
15
+ <p align="center">
16
+ <a href="#quick-start">Quick Start</a> &middot;
17
+ <a href="#features">Features</a> &middot;
18
+ <a href="#trust-score-algorithm">Algorithm</a> &middot;
19
+ <a href="#claude-code-integration-mcp">MCP</a> &middot;
20
+ <a href="#comparison">Comparison</a>
21
+ </p>
22
+ <p align="center">
23
+ <strong>English</strong> | <a href="README.tr.md">Turkce</a>
24
+ </p>
25
+ </p>
26
+
27
+ ---
28
+
29
+ > **Your dependencies have dependencies. Who's watching them?**
30
+
31
+ **dep-oracle** is a predictive dependency security engine that calculates **Trust Scores** (0-100) for every package in your dependency tree. It detects zombie dependencies, measures blast radius, catches typosquatting attempts, and predicts future risks — before they become vulnerabilities.
32
+
33
+ **Claude Code Security** scans YOUR code. **dep-oracle** scans everything your code **depends on**.
34
+
35
+ ## Why?
36
+
37
+ - **62% of breaches** in 2025 came from supply chain attacks
38
+ - The average project has **683 transitive dependencies**
39
+ - `npm audit` only catches **known** CVEs — dep-oracle **predicts** future risks
40
+ - You audit your code. But do you audit your **trust**?
41
+
42
+ ## Quick Start
43
+
44
+ ```bash
45
+ # Zero install — just run it
46
+ npx dep-oracle
47
+
48
+ # Or install globally
49
+ npm install -g dep-oracle
50
+ dep-oracle scan
51
+
52
+ # Check a single package
53
+ dep-oracle check express
54
+ ```
55
+
56
+ ## Features
57
+
58
+ | Feature | Description |
59
+ |---------|-------------|
60
+ | **Trust Score** | 0-100 weighted score per package (security, maintainer health, activity, popularity, funding, license) |
61
+ | **Zombie Detection** | Finds unmaintained but critical packages (no commits in 12+ months) |
62
+ | **Blast Radius** | Shows how many files are affected if a dependency is compromised |
63
+ | **Typosquat Detection** | 1,847+ known packages + live npm registry lookup to catch suspicious names |
64
+ | **Trend Prediction** | 3-month risk projection based on download/commit/release trends |
65
+ | **Migration Advisor** | 131 package mappings with 192 safer alternatives for risky dependencies |
66
+ | **Offline Mode** | Works from cache without internet (`--offline`) |
67
+ | **MCP Server** | Native Claude Code integration — ask about your dependencies in natural language |
68
+ | **Multi-Format Output** | Terminal (colored tree), HTML, JSON, and SARIF |
69
+ | **GitHub Action** | Automate trust checks in your CI/CD pipeline |
70
+
71
+ ## Usage
72
+
73
+ ```bash
74
+ # Scan current project
75
+ dep-oracle scan
76
+
77
+ # Scan with specific output format
78
+ dep-oracle scan --format json
79
+ dep-oracle scan --format html
80
+ dep-oracle scan --format sarif
81
+
82
+ # Check a single package
83
+ dep-oracle check lodash
84
+ dep-oracle check express@4.18.2
85
+
86
+ # Offline mode (uses cached data only)
87
+ dep-oracle scan --offline
88
+
89
+ # Set minimum score threshold (exit code 1 if below)
90
+ dep-oracle scan --threshold 60
91
+
92
+ # Ignore specific packages
93
+ dep-oracle scan --ignore deprecated-but-needed,legacy-pkg
94
+
95
+ # Verbose logging
96
+ dep-oracle scan --verbose
97
+ ```
98
+
99
+ ## Output Example
100
+
101
+ ```
102
+ dep-oracle v1.1.2
103
+ Scanning package.json...
104
+ Found 47 direct dependencies, 683 transitive
105
+ Collecting data... [=============================] 100% (2.3s)
106
+
107
+ DEPENDENCY TRUST REPORT
108
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
109
+
110
+ CRITICAL (score < 50)
111
+
112
+ ■ event-stream@3.3.6 Score: 12 ZOMBIE
113
+ Last commit: 2018 | 0 maintainers active
114
+ Blast radius: 14 files | Alternative: highland
115
+
116
+ WARNING (score 50-79)
117
+
118
+ ■ moment@2.29.4 Score: 58 ZOMBIE
119
+ Maintenance mode | No new features
120
+ Blast radius: 23 files | Alternative: dayjs, date-fns, luxon
121
+
122
+ SAFE (score 80+): 679 packages
123
+
124
+ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
125
+ SUMMARY
126
+ Overall Trust Score: 74/100
127
+ Critical: 2 | Warning: 3 | Safe: 679
128
+ Zombies: 2 | Deprecated: 1
129
+ ```
130
+
131
+ ## Trust Score Algorithm
132
+
133
+ Each package is scored 0-100 based on six weighted metrics:
134
+
135
+ | Metric | Weight | What It Measures |
136
+ |--------|--------|------------------|
137
+ | Security History | 25% | CVE count with diminishing penalty, average patch time, fast-patch bonus |
138
+ | Maintainer Health | 25% | Active maintainers (bus factor), issue response time, PR merge speed |
139
+ | Activity | 20% | Commit frequency trend, release cadence, last publish recency |
140
+ | Popularity | 15% | Weekly downloads, dependent count, GitHub stars |
141
+ | Funding | 10% | GitHub Sponsors, OpenCollective, corporate backing |
142
+ | License | 5% | MIT/Apache = safe, GPL = risk, Unknown = red flag |
143
+
144
+ **Score Ranges:** 80-100 Safe | 50-79 Warning | 0-49 Critical
145
+
146
+ ### Security Scoring
147
+
148
+ The security metric uses a **diminishing penalty** model — the first vulnerability has the highest impact, and each additional one has progressively less effect:
149
+
150
+ | Vulnerabilities | Security Score |
151
+ |-----------------|---------------|
152
+ | 0 | 100 |
153
+ | 1 | 85 |
154
+ | 2 | 72 |
155
+ | 3 | 60 |
156
+ | 4 | 50 |
157
+ | 5+ | max(20, 100 - n*12) |
158
+
159
+ Packages that patch vulnerabilities quickly (within 7 days) receive a **+10 bonus**. Slower patches (within 30 days) receive **+5**.
160
+
161
+ ### Graceful Degradation
162
+
163
+ If an API is unreachable (GitHub down, no internet, rate limited), dep-oracle doesn't crash. The missing metric weight is redistributed across available metrics. If 3+ metrics are unavailable, a reliability warning is shown.
164
+
165
+ ## Typosquat Detection
166
+
167
+ dep-oracle uses a multi-layer approach to catch typosquatting:
168
+
169
+ 1. **Static registry** — 1,847+ known popular package names across 40+ categories (React, Vue, Angular, Express, testing, CLI tools, etc.)
170
+ 2. **Dynamic npm lookup** — Fetches the top 5,000 most-downloaded packages from npm and caches them for 7 days
171
+ 3. **Pattern matching** — Levenshtein distance, prefix/suffix manipulation, character swap, missing/extra letter detection
172
+
173
+ ```bash
174
+ dep-oracle check expresss # Catches: similar to "express" (distance: 1)
175
+ dep-oracle check lodashe # Catches: similar to "lodash" (distance: 1)
176
+ dep-oracle check react-js # Catches: suffix pattern of "react"
177
+ ```
178
+
179
+ ## Migration Advisor
180
+
181
+ When a package scores low or is flagged as a zombie, dep-oracle suggests safer alternatives from a curated database of **131 package mappings** with **192 alternatives**:
182
+
183
+ ```
184
+ moment → dayjs, date-fns, luxon
185
+ request → axios, got, node-fetch, undici
186
+ lodash → lodash-es, radash, just (native alternatives)
187
+ express → fastify, koa, hono
188
+ gulp → esbuild, tsup, vite
189
+ mocha → vitest, jest, node:test
190
+ ...and 125 more
191
+ ```
192
+
193
+ Each suggestion includes difficulty rating (easy/moderate/hard) and migration context.
194
+
195
+ ## Claude Code Integration (MCP)
196
+
197
+ dep-oracle is listed on the official **[MCP Registry](https://modelcontextprotocol.io/registry)** and works as an MCP server for Claude Code:
198
+
199
+ ```json
200
+ // .claude/settings.json
201
+ {
202
+ "mcpServers": {
203
+ "dep-oracle": {
204
+ "command": "npx",
205
+ "args": ["dep-oracle", "mcp"]
206
+ }
207
+ }
208
+ }
209
+ ```
210
+
211
+ Then in Claude Code, just ask:
212
+ - *"What's the riskiest dependency in this project?"*
213
+ - *"Is lodash safe to use?"*
214
+ - *"Show me zombie dependencies"*
215
+ - *"Suggest alternatives for moment.js"*
216
+
217
+ **Available MCP Tools:**
218
+
219
+ | Tool | Description |
220
+ |------|-------------|
221
+ | `dep_oracle_scan` | Full project dependency scan |
222
+ | `dep_oracle_trust_score` | Trust score for a single package |
223
+ | `dep_oracle_blast_radius` | Impact analysis for a package |
224
+ | `dep_oracle_zombies` | List all zombie dependencies |
225
+ | `dep_oracle_suggest_migration` | Get alternative package suggestions |
226
+
227
+ ## GitHub Action
228
+
229
+ ```yaml
230
+ name: Dependency Trust Check
231
+ on: [pull_request]
232
+
233
+ jobs:
234
+ dep-oracle:
235
+ runs-on: ubuntu-latest
236
+ steps:
237
+ - uses: actions/checkout@v4
238
+ - uses: ertugrulakben/dep-oracle-action@v1
239
+ with:
240
+ threshold: 60
241
+ format: sarif
242
+ ```
243
+
244
+ ## Configuration
245
+
246
+ Create `.dep-oraclerc.json` in your project root:
247
+
248
+ ```json
249
+ {
250
+ "threshold": 60,
251
+ "ignore": ["known-risky-but-needed"],
252
+ "format": "terminal",
253
+ "offline": false,
254
+ "githubToken": "$GITHUB_TOKEN",
255
+ "cacheTtl": 86400
256
+ }
257
+ ```
258
+
259
+ Or add to `package.json`:
260
+
261
+ ```json
262
+ {
263
+ "dep-oracle": {
264
+ "threshold": 60,
265
+ "ignore": []
266
+ }
267
+ }
268
+ ```
269
+
270
+ ### Configuration Options
271
+
272
+ | Option | Default | Description |
273
+ |--------|---------|-------------|
274
+ | `threshold` | `60` | Minimum trust score. Packages below trigger warnings and non-zero exit |
275
+ | `ignore` | `[]` | Packages to skip during scanning |
276
+ | `format` | `"terminal"` | Output format: `terminal`, `json`, `html`, `sarif` |
277
+ | `offline` | `false` | Use only cached data, skip all API calls |
278
+ | `githubToken` | `null` | GitHub token for higher API rate limits (5000/hr vs 60/hr) |
279
+ | `cacheTtl` | `86400` | Cache TTL in seconds (default: 24 hours) |
280
+
281
+ ## Supported Package Managers
282
+
283
+ | Manager | Manifest | Lock File | Status |
284
+ |---------|----------|-----------|--------|
285
+ | npm | `package.json` | `package-lock.json` | Supported |
286
+ | yarn | `package.json` | `yarn.lock` | Supported |
287
+ | pnpm | `package.json` | `pnpm-lock.yaml` | Supported |
288
+ | pip | `requirements.txt` | `Pipfile.lock` | Supported |
289
+ | poetry | `pyproject.toml` | `poetry.lock` | Supported |
290
+
291
+ ## Comparison
292
+
293
+ | Feature | npm audit | Dependabot | Socket.dev | Snyk | **dep-oracle** |
294
+ |---------|-----------|------------|------------|------|----------------|
295
+ | Known CVE scan | Yes | Yes | Yes | Yes | **Yes** |
296
+ | Predictive risk | No | No | Partial | No | **Yes** |
297
+ | Trust Score (0-100) | No | No | No | No | **Yes** |
298
+ | Zombie detection | No | No | No | No | **Yes** |
299
+ | Blast radius | No | No | No | No | **Yes** |
300
+ | Typosquat detection | No | No | Yes | No | **Yes** |
301
+ | Trend prediction | No | No | No | No | **Yes** |
302
+ | Migration advisor | No | Partial | No | Partial | **Yes (131 pkgs)** |
303
+ | MCP integration | No | No | Yes | Yes | **Yes** |
304
+ | Zero install (npx) | Yes | No | No | No | **Yes** |
305
+ | Free & open source | Yes | Yes | Freemium | Freemium | **Yes** |
306
+
307
+ ## Programmatic API
308
+
309
+ ```typescript
310
+ import { scan, checkPackage } from 'dep-oracle';
311
+
312
+ // Scan a project
313
+ const report = await scan({ dir: './my-project', format: 'json' });
314
+
315
+ // Check a single package
316
+ const result = await checkPackage('express');
317
+ console.log(result.trustScore); // 74
318
+ console.log(result.isZombie); // false
319
+ ```
320
+
321
+ ## Test Suite
322
+
323
+ dep-oracle has comprehensive test coverage:
324
+
325
+ ```
326
+ 10 test files | 144 tests | 100% passing
327
+
328
+ trust-score.test.ts 34 tests Scoring engine, metrics, edge cases
329
+ zombie-detector.test.ts 10 tests Zombie detection logic
330
+ typosquat.test.ts 15 tests Typosquat pattern matching
331
+ migration-advisor.test.ts 12 tests Migration suggestions
332
+ trend-predictor.test.ts 10 tests Trend prediction engine
333
+ parsers.test.ts 17 tests npm + Python parsers
334
+ cache.test.ts 15 tests Cache store operations
335
+ logger.test.ts 17 tests Logger utility
336
+ rate-limiter.test.ts 6 tests Rate limiter
337
+ schema.test.ts 8 tests Zod schema validation
338
+ ```
339
+
340
+ ```bash
341
+ npm test # Run all tests
342
+ npm run lint # TypeScript type checking
343
+ ```
344
+
345
+ ## Changelog
346
+
347
+ ### v1.1.2 (2026-02-22)
348
+
349
+ - **npm README Fix**: English README with cover image, MCP Registry badge, and complete changelog now properly displayed on npmjs.com
350
+ - **MCP Registry Links**: Updated to official documentation URL
351
+
352
+ ### v1.1.1 (2026-02-22)
353
+
354
+ - **MCP Registry**: Listed on the official [MCP Registry](https://modelcontextprotocol.io/registry) as `io.github.ertugrulakben/dep-oracle`
355
+ - **Dynamic Versioning**: MCP server and SARIF reporter now read version from package.json (no more hardcoded versions)
356
+
357
+ ### v1.1.0 (2026-02-22)
358
+
359
+ - **Typosquat Detection**: Expanded to 1,847+ known packages across 40+ categories, plus dynamic npm registry fetch (top 5,000 packages, 7-day cache)
360
+ - **Migration Advisor**: Expanded to 131 package mappings with 192 safer alternatives
361
+ - **Trust Score Calibration**: Diminishing vulnerability penalty (first CVE has highest impact), fast-patch bonus (+10 for <=7 days)
362
+ - **Poetry.lock Support**: Full poetry.lock parsing for Python projects
363
+ - **Comprehensive Test Suite**: 10 test files, 144 tests covering all analyzers, parsers, cache, and utilities
364
+ - **Turkish README**: Full Turkish documentation (README.tr.md)
365
+ - **Dynamic CLI Version**: Version automatically synced from package.json
366
+
367
+ ### v1.0.0 (2026-02-22)
368
+
369
+ - Initial release
370
+ - Trust Score engine with 6 weighted metrics
371
+ - npm + Python (pip, poetry, pyproject.toml) parsers
372
+ - Zombie detection, blast radius analysis
373
+ - Typosquat detection with Levenshtein distance
374
+ - Trend prediction (3-month risk projection)
375
+ - Migration advisor with curated alternatives
376
+ - Terminal, HTML, JSON, SARIF output formats
377
+ - MCP server for Claude Code integration
378
+ - GitHub Action support
379
+ - Offline mode with SQLite-compatible cache
380
+ - Badge generator (SVG)
381
+
382
+ ## Contributing
383
+
384
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and how to add new collectors, parsers, or analyzers.
385
+
386
+ ## License
387
+
388
+ [MIT](LICENSE) — [Ertugrul Akben](https://ertugrulakben.com)