thuban 0.4.5 → 0.4.7

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 (31) hide show
  1. package/README.md +437 -420
  2. package/dist/README.md +437 -420
  3. package/dist/cli.js +1 -2
  4. package/dist/package.json +7 -4
  5. package/dist/packages/crucible/mutation-engine.js +1 -1
  6. package/dist/packages/crucible/pattern-learner.js +1 -1
  7. package/dist/packages/crucible/rule-loader.js +1 -1
  8. package/dist/packages/crucible/rules/code-scanner-core.json +72 -24
  9. package/dist/packages/crucible/seeding-engine.js +1 -1
  10. package/dist/packages/scanner/ai-confidence-scorer.js +1 -1
  11. package/dist/packages/scanner/code-scanner.js +1 -1
  12. package/dist/packages/scanner/codebase-passport.js +1 -1
  13. package/dist/packages/scanner/copy-paste-detector.js +1 -1
  14. package/dist/packages/scanner/dependency-graph.js +1 -1
  15. package/dist/packages/scanner/drift-detector.js +1 -1
  16. package/dist/packages/scanner/export-verifier.js +1 -1
  17. package/dist/packages/scanner/feedback-client.js +1 -0
  18. package/dist/packages/scanner/file-collector.js +1 -1
  19. package/dist/packages/scanner/ghost-code-detector.js +1 -1
  20. package/dist/packages/scanner/hallucination-detector.js +1 -1
  21. package/dist/packages/scanner/investor-report.js +1 -0
  22. package/dist/packages/scanner/license-manager.js +1 -1
  23. package/dist/packages/scanner/pre-commit-gate.js +1 -1
  24. package/dist/packages/scanner/python_ast_helper.py +426 -0
  25. package/dist/packages/scanner/read-file.js +1 -0
  26. package/dist/packages/scanner/slack-notifier.js +1 -0
  27. package/dist/packages/scanner/support-bot.js +1 -0
  28. package/dist/packages/scanner/support-knowledge.js +1 -0
  29. package/dist/packages/scanner/taint-tracker.js +1 -1
  30. package/dist/packages/scanner/tech-debt-analyzer.js +1 -1
  31. package/package.json +7 -4
package/dist/README.md CHANGED
@@ -1,420 +1,437 @@
1
- # Thuban -- Code Intelligence Scanner
2
-
3
- [![npm version](https://img.shields.io/npm/v/thuban.svg)](https://www.npmjs.com/package/thuban)
4
- [![license](https://img.shields.io/npm/l/thuban.svg)](LICENSE)
5
- [![tests](https://img.shields.io/badge/tests-746%20passing-brightgreen.svg)](#testing)
6
- [![coverage](https://img.shields.io/badge/coverage-91.2%25-brightgreen.svg)](#testing)
7
-
8
- Static analysis, security scanning, dead code detection, clone detection, AI-generated code scoring, dependency analysis, and mutation testing for 12 languages. One command. Zero runtime dependencies beyond `@babel/parser`.
9
-
10
- ---
11
-
12
- ## Quick Start
13
-
14
- ```bash
15
- npm install -g thuban
16
- thuban scan .
17
- ```
18
-
19
- Or run without installing:
20
-
21
- ```bash
22
- npx thuban scan .
23
- ```
24
-
25
- JSON output for CI pipelines:
26
-
27
- ```bash
28
- thuban scan . --json
29
- ```
30
-
31
- ---
32
-
33
- ## Feature Highlights
34
-
35
- ### Security Analysis
36
-
37
- 84 detection rules across multiple categories. Cross-file taint tracking follows user input from sources (`req.query`, `req.body`, `req.params`, `process.argv`, `process.env`) through assignment, concatenation, and template interpolation to dangerous SQL and XSS sinks -- across file boundaries via `require()`, `import`, destructured imports, and re-exports.
38
-
39
- ```bash
40
- thuban scan src/ --json
41
- ```
42
-
43
- ### Control Flow Graph Analysis
44
-
45
- Detects unreachable code, infinite loops, and dead branches through AST-based control flow graph construction.
46
-
47
- ### Clone Detection
48
-
49
- Multi-language code clone detection with AST normalization. Finds duplicated logic across your codebase.
50
-
51
- ```bash
52
- thuban clones src/
53
- ```
54
-
55
- ### AI-Generated Code Scoring
56
-
57
- Scores files for likelihood of AI generation based on structural patterns, naming conventions, and code smells common in LLM output.
58
-
59
- ```bash
60
- thuban aiscore src/
61
- ```
62
-
63
- ### Dependency Analysis
64
-
65
- Maps dependency graphs, detects circular imports, and identifies unused or phantom dependencies.
66
-
67
- ```bash
68
- thuban deps .
69
- ```
70
-
71
- ### Mutation Testing (Crucible)
72
-
73
- Built-in mutation testing engine. 515 seed files generate 1,030 mutations. Validates that your test suite catches real bugs.
74
-
75
- ```bash
76
- thuban crucible --mode kenny # standard mode
77
- thuban crucible --mode hell # maximum mutation density
78
- ```
79
-
80
- ### Ghost Code Detection
81
-
82
- Finds dead exports, unused functions, and unreachable modules.
83
-
84
- ```bash
85
- thuban ghosts src/
86
- ```
87
-
88
- ### Auto-Fix
89
-
90
- Automatically applies safe fixes for supported rule violations.
91
-
92
- ```bash
93
- thuban fix src/
94
- ```
95
-
96
- ### HTML Dashboard
97
-
98
- Generates a visual HTML report with charts, trends, and drill-down by category.
99
-
100
- ```bash
101
- thuban dashboard .
102
- ```
103
-
104
- ### Executive Reports
105
-
106
- PDF-ready executive summary with risk scores, trend data, and remediation priorities.
107
-
108
- ```bash
109
- thuban executive .
110
- thuban pdf .
111
- ```
112
-
113
- ### Baseline Scanning
114
-
115
- Establish a baseline and track only new issues introduced after that point.
116
-
117
- ```bash
118
- thuban baseline . # save current state
119
- thuban scan . --baseline # report only new issues
120
- thuban compare . # compare current scan to baseline
121
- ```
122
-
123
- ### Pre-Commit Gate
124
-
125
- Block commits that introduce issues above a configurable threshold.
126
-
127
- ```bash
128
- thuban gate .
129
- ```
130
-
131
- ### Inline Suppression
132
-
133
- Suppress specific rules on a per-line basis:
134
-
135
- ```javascript
136
- const query = "SELECT * FROM " + input; // thuban-ignore SEC001
137
- ```
138
-
139
- ```python
140
- password = "admin123" # thuban-ignore SEC005
141
- ```
142
-
143
- Suppress all rules on a line:
144
-
145
- ```javascript
146
- eval(code); // thuban-ignore
147
- ```
148
-
149
- ---
150
-
151
- ## Supported Languages
152
-
153
- | Language | Extension(s) | AST Engine |
154
- |------------|----------------------|----------------|
155
- | JavaScript | `.js`, `.mjs`, `.cjs`| Babel |
156
- | TypeScript | `.ts` | Babel |
157
- | JSX | `.jsx` | Babel |
158
- | TSX | `.tsx` | Babel |
159
- | Python | `.py` | Python `ast` |
160
- | Go | `.go` | `go/parser` |
161
- | Rust | `.rs` | Pattern-based |
162
- | Ruby | `.rb` | Pattern-based |
163
- | Java | `.java` | Pattern-based |
164
- | C# | `.cs` | Pattern-based |
165
- | Kotlin | `.kt` | Pattern-based |
166
- | PHP | `.php` | Pattern-based |
167
-
168
- Three AST engines provide deep analysis: Babel for JavaScript/TypeScript/JSX/TSX, Python `ast` for Python, and Go `go/parser` for Go. Remaining languages use pattern-based detection.
169
-
170
- ---
171
-
172
- ## Detection Rules
173
-
174
- 84 rules organized by category:
175
-
176
- | Category | Rule IDs | Description |
177
- |-------------|-----------------------|--------------------------------------------------|
178
- | Security | SEC001--SEC019 | SQL injection, XSS, hardcoded secrets, eval, command injection, path traversal, insecure crypto, SSRF, prototype pollution, and more |
179
- | Security | RUST001--RUST002 | Rust-specific unsafe patterns |
180
- | Quality | QUAL001--QUAL004 | Code quality, naming, structure |
181
- | Performance | PERF001 | Performance anti-patterns |
182
- | AST | AST001--AST005 | Phantom imports, deprecated APIs, unused variables, hallucinated APIs, empty catch blocks |
183
- | AST | AST011--AST014 | Advanced AST patterns |
184
- | Taint | TAINT001--TAINT002 | Cross-file taint tracking for SQLi and XSS |
185
- | CFG | CFG001--CFG005 | Unreachable code, infinite loops, dead branches |
186
- | Nesting | NEST001 | Excessive nesting depth |
187
- | Complexity | CMPLX001--CMPLX002 | Cyclomatic and cognitive complexity |
188
-
189
- ---
190
-
191
- ## CLI Commands
192
-
193
- 28 commands grouped by function:
194
-
195
- ### Core Scanning
196
-
197
- | Command | Description |
198
- |---------------|--------------------------------------------------|
199
- | `scan [path]` | Scan a codebase for issues |
200
- | `diff [path]` | Scan only git-changed files |
201
- | `deps [path]` | Map dependencies and detect circular imports |
202
- | `health [path]`| Run health check on codebase |
203
- | `report [path]`| Full scan + deps + drift combined report |
204
-
205
- ### Detection
206
-
207
- | Command | Description |
208
- |----------------------|--------------------------------------------|
209
- | `hallucinate [path]` | Detect AI hallucinations and phantom imports|
210
- | `ghosts [path]` | Detect dead code and unused exports |
211
- | `aiscore [path]` | Score files for AI-generated code patterns |
212
- | `clones [path]` | Detect code clones across the codebase |
213
- | `drift [path]` | Detect drift from Mother Code annotations |
214
- | `debt [path]` | Analyze technical debt |
215
- | `cost [path]` | Calculate technical debt cost |
216
-
217
- ### Remediation
218
-
219
- | Command | Description |
220
- |---------------|--------------------------------------------------|
221
- | `fix [path]` | Auto-fix supported rule violations |
222
- | `inject [path]`| Inject Mother Code DNA widget into files |
223
- | `gate [path]` | Pre-commit quality gate |
224
-
225
- ### Reporting
226
-
227
- | Command | Description |
228
- |--------------------|-----------------------------------------------|
229
- | `dashboard [path]` | Generate visual HTML dashboard |
230
- | `executive [path]` | Generate executive summary report |
231
- | `pdf [path]` | Generate PDF-ready report |
232
- | `passport [path]` | Generate codebase passport |
233
-
234
- ### Monitoring
235
-
236
- | Command | Description |
237
- |------------------|-------------------------------------------------|
238
- | `watch [path]` | Live sentinel -- continuous file monitoring |
239
- | `monitor [path]` | Recurring scans with history and alerts |
240
- | `history [path]` | View recurring scan history |
241
- | `trend [path]` | Show issue trends across scans |
242
-
243
- ### Baseline and Comparison
244
-
245
- | Command | Description |
246
- |------------------|-------------------------------------------------|
247
- | `baseline [path]`| Save current scan state as baseline |
248
- | `compare [path]` | Compare current scan against baseline |
249
-
250
- ### Licensing
251
-
252
- | Command | Description |
253
- |------------|------------------------------------------------------|
254
- | `activate` | Activate a license key |
255
- | `status` | Show current license status |
256
- | `upgrade` | Upgrade license tier |
257
-
258
- ### Mutation Testing
259
-
260
- | Command | Description |
261
- |------------|------------------------------------------------------|
262
- | `crucible` | Run the Crucible mutation testing engine |
263
-
264
- ---
265
-
266
- ## Configuration
267
-
268
- ### `.thubanrc.json`
269
-
270
- Place a `.thubanrc.json` in your project root to configure scan behavior:
271
-
272
- ```json
273
- {
274
- "$schema": "https://thuban.dev/schema/thubanrc.json",
275
- "minScore": 0,
276
- "ignore": [
277
- "node_modules",
278
- "dist",
279
- ".git",
280
- "coverage"
281
- ],
282
- "hallucination": {
283
- "enabled": true,
284
- "ignore": []
285
- },
286
- "motherCode": {
287
- "enabled": true,
288
- "autoInject": false
289
- },
290
- "report": {
291
- "format": "html",
292
- "outputDir": "."
293
- },
294
- "ci": {
295
- "failOnGrade": "F",
296
- "postComment": true
297
- }
298
- }
299
- ```
300
-
301
- ### `.thubanignore`
302
-
303
- Exclude files and directories from scanning, one glob pattern per line:
304
-
305
- ```
306
- packages/crucible/seeds/**
307
- tests/regression/fixtures/**
308
- vendor/**
309
- ```
310
-
311
- ---
312
-
313
- ## JSON Output
314
-
315
- All scan commands support `--json` for machine-readable output:
316
-
317
- ```bash
318
- thuban scan src/ --json
319
- ```
320
-
321
- ```json
322
- {
323
- "version": "0.4.5",
324
- "timestamp": "2026-07-04T12:00:00.000Z",
325
- "files": 42,
326
- "issues": [
327
- {
328
- "file": "src/api/handler.js",
329
- "line": 17,
330
- "rule": "SEC001",
331
- "severity": "critical",
332
- "category": "security",
333
- "message": "Potential SQL injection: unsanitized input in query string",
334
- "fix": "Use parameterized queries instead of string concatenation"
335
- }
336
- ],
337
- "summary": {
338
- "critical": 1,
339
- "warning": 3,
340
- "info": 5,
341
- "score": 72,
342
- "grade": "C"
343
- }
344
- }
345
- ```
346
-
347
- ---
348
-
349
- ## Performance
350
-
351
- | Metric | Value |
352
- |----------------|--------------------|
353
- | Throughput | ~23,000 lines/sec |
354
- | Test suite | 746 tests |
355
- | Code coverage | 91.2% |
356
- | Dependencies | 1 (`@babel/parser`) |
357
-
358
- ---
359
-
360
- ## Tiers
361
-
362
- | Tier | Limit | Features |
363
- |------------|-----------|---------------------------------------------------|
364
- | Free | 100 files | Core scanning, all 84 rules, JSON output |
365
- | Pro | Unlimited | Recurring scans, history, trends, notifications |
366
- | Team | Unlimited | Dashboard, executive reports, baseline management |
367
- | Enterprise | Unlimited | Custom rules, priority support, SSO |
368
-
369
- Activate a license:
370
-
371
- ```bash
372
- thuban activate <license-key>
373
- thuban status
374
- ```
375
-
376
- ---
377
-
378
- ## CI Integration
379
-
380
- ### GitHub Actions
381
-
382
- ```yaml
383
- - name: Thuban Scan
384
- run: npx thuban scan . --json --baseline
385
- env:
386
- THUBAN_LICENSE: ${{ secrets.THUBAN_LICENSE }}
387
- ```
388
-
389
- ### Pre-Commit Hook
390
-
391
- ```bash
392
- thuban gate . --fail-on critical
393
- ```
394
-
395
- ---
396
-
397
- ## Requirements
398
-
399
- - Node.js >= 16.0.0
400
-
401
- ---
402
-
403
- ## Contributing
404
-
405
- 1. Fork the repository
406
- 2. Create a feature branch (`git checkout -b feature/my-feature`)
407
- 3. Run the test suite (`npm test`)
408
- 4. Submit a pull request
409
-
410
- Issues and feature requests: [github.com/SilverwingsBenefitsGit/thuban/issues](https://github.com/SilverwingsBenefitsGit/thuban/issues)
411
-
412
- ---
413
-
414
- ## License
415
-
416
- [MIT](LICENSE)
417
-
418
- ---
419
-
420
- [thuban.dev](https://thuban.dev)
1
+ # Thuban -- Code Intelligence Scanner
2
+
3
+ [![npm version](https://img.shields.io/npm/v/thuban.svg)](https://www.npmjs.com/package/thuban)
4
+ [![license](https://img.shields.io/npm/l/thuban.svg)](LICENSE)
5
+ [![tests](https://img.shields.io/badge/tests-746%20passing-brightgreen.svg)](#testing)
6
+ [![coverage](https://img.shields.io/badge/coverage-91.2%25-brightgreen.svg)](#testing)
7
+
8
+ AI Code Verification Catch what AI gets wrong.
9
+
10
+ Static analysis, security scanning, dead code detection, clone detection, AI-generated code scoring, dependency analysis, and mutation testing for 12 languages. One command. Zero runtime dependencies beyond `@babel/parser`.
11
+
12
+ ---
13
+
14
+ ## Quick Start
15
+
16
+ ```bash
17
+ npm install -g thuban
18
+ thuban scan .
19
+ ```
20
+
21
+ Or run without installing:
22
+
23
+ ```bash
24
+ npx thuban scan .
25
+ ```
26
+
27
+ JSON output for CI pipelines:
28
+
29
+ ```bash
30
+ thuban scan . --json
31
+ ```
32
+
33
+ ---
34
+
35
+ ## Feature Highlights
36
+
37
+ ### Security Analysis
38
+
39
+ 84 detection rules across multiple categories. Cross-file taint tracking follows user input from sources (`req.query`, `req.body`, `req.params`, `process.argv`, `process.env`) through assignment, concatenation, and template interpolation to dangerous SQL and XSS sinks -- across file boundaries via `require()`, `import`, destructured imports, and re-exports.
40
+
41
+ ```bash
42
+ thuban scan src/ --json
43
+ ```
44
+
45
+ ### OWASP Top 10 & CWE Compliance
46
+
47
+ All security rules (SEC001--SEC019, RUST001--RUST002) map to [OWASP Top 10 2021](https://owasp.org/Top10/) categories and [CWE](https://cwe.mitre.org/) identifiers. Every finding includes machine-readable `owasp` and `cwe` fields in JSON output, enabling direct integration with compliance dashboards and vulnerability management systems.
48
+
49
+ | OWASP 2021 Category | Rules | CWEs |
50
+ |-----------------------------------------|----------------------------------------|-----------------------------------|
51
+ | A01 Broken Access Control | SEC005, SEC013, SEC014 | CWE-22, CWE-942, CWE-601 |
52
+ | A02 Cryptographic Failures | SEC006, SEC007, SEC008, SEC016 | CWE-798, CWE-327, CWE-330, CWE-208 |
53
+ | A03 Injection | SEC001, SEC002, SEC003, SEC004, SEC009, SEC011, SEC018, SEC019 | CWE-95, CWE-79, CWE-89, CWE-78, CWE-1321 |
54
+ | A04 Insecure Design | SEC015 | CWE-209 |
55
+ | A05 Security Misconfiguration | SEC017 | CWE-611 |
56
+ | A06 Vulnerable Components | RUST001, RUST002 | CWE-908, CWE-477 |
57
+ | A08 Software and Data Integrity | SEC012 | CWE-502 |
58
+ | A10 SSRF | SEC010 | CWE-918 |
59
+
60
+ ### Control Flow Graph Analysis
61
+
62
+ Detects unreachable code, infinite loops, and dead branches through AST-based control flow graph construction.
63
+
64
+ ### Clone Detection
65
+
66
+ Multi-language code clone detection with AST normalization. Finds duplicated logic across your codebase.
67
+
68
+ ```bash
69
+ thuban clones src/
70
+ ```
71
+
72
+ ### AI-Generated Code Scoring
73
+
74
+ Scores files for likelihood of AI generation based on structural patterns, naming conventions, and code smells common in LLM output.
75
+
76
+ ```bash
77
+ thuban aiscore src/
78
+ ```
79
+
80
+ ### Dependency Analysis
81
+
82
+ Maps dependency graphs, detects circular imports, and identifies unused or phantom dependencies.
83
+
84
+ ```bash
85
+ thuban deps .
86
+ ```
87
+
88
+ ### Mutation Testing (Crucible)
89
+
90
+ Built-in mutation testing engine. 515 seed files generate 1,030 mutations. Validates that your test suite catches real bugs.
91
+
92
+ ```bash
93
+ thuban crucible --mode kenny # standard mode
94
+ thuban crucible --mode hell # maximum mutation density
95
+ ```
96
+
97
+ ### Ghost Code Detection
98
+
99
+ Finds dead exports, unused functions, and unreachable modules.
100
+
101
+ ```bash
102
+ thuban ghosts src/
103
+ ```
104
+
105
+ ### Auto-Fix
106
+
107
+ Automatically applies safe fixes for supported rule violations.
108
+
109
+ ```bash
110
+ thuban fix src/
111
+ ```
112
+
113
+ ### HTML Dashboard
114
+
115
+ Generates a visual HTML report with charts, trends, and drill-down by category.
116
+
117
+ ```bash
118
+ thuban dashboard .
119
+ ```
120
+
121
+ ### Executive Reports
122
+
123
+ PDF-ready executive summary with risk scores, trend data, and remediation priorities.
124
+
125
+ ```bash
126
+ thuban executive .
127
+ thuban pdf .
128
+ ```
129
+
130
+ ### Baseline Scanning
131
+
132
+ Establish a baseline and track only new issues introduced after that point.
133
+
134
+ ```bash
135
+ thuban baseline . # save current state
136
+ thuban scan . --baseline # report only new issues
137
+ thuban compare . # compare current scan to baseline
138
+ ```
139
+
140
+ ### Pre-Commit Gate
141
+
142
+ Block commits that introduce issues above a configurable threshold.
143
+
144
+ ```bash
145
+ thuban gate .
146
+ ```
147
+
148
+ ### Inline Suppression
149
+
150
+ Suppress specific rules on a per-line basis:
151
+
152
+ ```javascript
153
+ const query = "SELECT * FROM " + input; // thuban-ignore SEC001
154
+ ```
155
+
156
+ ```python
157
+ password = "admin123" # thuban-ignore SEC005
158
+ ```
159
+
160
+ Suppress all rules on a line:
161
+
162
+ ```javascript
163
+ eval(code); // thuban-ignore
164
+ ```
165
+
166
+ ---
167
+
168
+ ## Supported Languages
169
+
170
+ | Language | Extension(s) | AST Engine |
171
+ |------------|----------------------|----------------|
172
+ | JavaScript | `.js`, `.mjs`, `.cjs`| Babel |
173
+ | TypeScript | `.ts` | Babel |
174
+ | JSX | `.jsx` | Babel |
175
+ | TSX | `.tsx` | Babel |
176
+ | Python | `.py` | Python `ast` |
177
+ | Go | `.go` | `go/parser` |
178
+ | Rust | `.rs` | Pattern-based |
179
+ | Ruby | `.rb` | Pattern-based |
180
+ | Java | `.java` | Pattern-based |
181
+ | C# | `.cs` | Pattern-based |
182
+ | Kotlin | `.kt` | Pattern-based |
183
+ | PHP | `.php` | Pattern-based |
184
+
185
+ Three AST engines provide deep analysis: Babel for JavaScript/TypeScript/JSX/TSX, Python `ast` for Python, and Go `go/parser` for Go. Remaining languages use pattern-based detection.
186
+
187
+ ---
188
+
189
+ ## Detection Rules
190
+
191
+ 84 rules organized by category:
192
+
193
+ | Category | Rule IDs | Description |
194
+ |-------------|-----------------------|--------------------------------------------------|
195
+ | Security | SEC001--SEC019 | SQL injection, XSS, hardcoded secrets, eval, command injection, path traversal, insecure crypto, SSRF, prototype pollution, and more |
196
+ | Security | RUST001--RUST002 | Rust-specific unsafe patterns |
197
+ | Quality | QUAL001--QUAL004 | Code quality, naming, structure |
198
+ | Performance | PERF001 | Performance anti-patterns |
199
+ | AST | AST001--AST005 | Phantom imports, deprecated APIs, unused variables, hallucinated APIs, empty catch blocks |
200
+ | AST | AST011--AST014 | Advanced AST patterns |
201
+ | Taint | TAINT001--TAINT002 | Cross-file taint tracking for SQLi and XSS |
202
+ | CFG | CFG001--CFG005 | Unreachable code, infinite loops, dead branches |
203
+ | Nesting | NEST001 | Excessive nesting depth |
204
+ | Complexity | CMPLX001--CMPLX002 | Cyclomatic and cognitive complexity |
205
+
206
+ ---
207
+
208
+ ## CLI Commands
209
+
210
+ 28 commands grouped by function:
211
+
212
+ ### Core Scanning
213
+
214
+ | Command | Description |
215
+ |---------------|--------------------------------------------------|
216
+ | `scan [path]` | Scan a codebase for issues |
217
+ | `diff [path]` | Scan only git-changed files |
218
+ | `deps [path]` | Map dependencies and detect circular imports |
219
+ | `health [path]`| Run health check on codebase |
220
+ | `report [path]`| Full scan + deps + drift combined report |
221
+
222
+ ### Detection
223
+
224
+ | Command | Description |
225
+ |----------------------|--------------------------------------------|
226
+ | `hallucinate [path]` | Detect AI hallucinations and phantom imports|
227
+ | `ghosts [path]` | Detect dead code and unused exports |
228
+ | `aiscore [path]` | Score files for AI-generated code patterns |
229
+ | `clones [path]` | Detect code clones across the codebase |
230
+ | `drift [path]` | Detect drift from Mother Code annotations |
231
+ | `debt [path]` | Analyze technical debt |
232
+ | `cost [path]` | Calculate technical debt cost |
233
+
234
+ ### Remediation
235
+
236
+ | Command | Description |
237
+ |---------------|--------------------------------------------------|
238
+ | `fix [path]` | Auto-fix supported rule violations |
239
+ | `inject [path]`| Inject Mother Code DNA widget into files |
240
+ | `gate [path]` | Pre-commit quality gate |
241
+
242
+ ### Reporting
243
+
244
+ | Command | Description |
245
+ |--------------------|-----------------------------------------------|
246
+ | `dashboard [path]` | Generate visual HTML dashboard |
247
+ | `executive [path]` | Generate executive summary report |
248
+ | `pdf [path]` | Generate PDF-ready report |
249
+ | `passport [path]` | Generate codebase passport |
250
+
251
+ ### Monitoring
252
+
253
+ | Command | Description |
254
+ |------------------|-------------------------------------------------|
255
+ | `watch [path]` | Live sentinel -- continuous file monitoring |
256
+ | `monitor [path]` | Recurring scans with history and alerts |
257
+ | `history [path]` | View recurring scan history |
258
+ | `trend [path]` | Show issue trends across scans |
259
+
260
+ ### Baseline and Comparison
261
+
262
+ | Command | Description |
263
+ |------------------|-------------------------------------------------|
264
+ | `baseline [path]`| Save current scan state as baseline |
265
+ | `compare [path]` | Compare current scan against baseline |
266
+
267
+ ### Licensing
268
+
269
+ | Command | Description |
270
+ |------------|------------------------------------------------------|
271
+ | `activate` | Activate a license key |
272
+ | `status` | Show current license status |
273
+ | `upgrade` | Upgrade license tier |
274
+
275
+ ### Mutation Testing
276
+
277
+ | Command | Description |
278
+ |------------|------------------------------------------------------|
279
+ | `crucible` | Run the Crucible mutation testing engine |
280
+
281
+ ---
282
+
283
+ ## Configuration
284
+
285
+ ### `.thubanrc.json`
286
+
287
+ Place a `.thubanrc.json` in your project root to configure scan behavior:
288
+
289
+ ```json
290
+ {
291
+ "$schema": "https://thuban.dev/schema/thubanrc.json",
292
+ "minScore": 0,
293
+ "ignore": [
294
+ "node_modules",
295
+ "dist",
296
+ ".git",
297
+ "coverage"
298
+ ],
299
+ "hallucination": {
300
+ "enabled": true,
301
+ "ignore": []
302
+ },
303
+ "motherCode": {
304
+ "enabled": true,
305
+ "autoInject": false
306
+ },
307
+ "report": {
308
+ "format": "html",
309
+ "outputDir": "."
310
+ },
311
+ "ci": {
312
+ "failOnGrade": "F",
313
+ "postComment": true
314
+ }
315
+ }
316
+ ```
317
+
318
+ ### `.thubanignore`
319
+
320
+ Exclude files and directories from scanning, one glob pattern per line:
321
+
322
+ ```
323
+ packages/crucible/seeds/**
324
+ tests/regression/fixtures/**
325
+ vendor/**
326
+ ```
327
+
328
+ ---
329
+
330
+ ## JSON Output
331
+
332
+ All scan commands support `--json` for machine-readable output:
333
+
334
+ ```bash
335
+ thuban scan src/ --json
336
+ ```
337
+
338
+ ```json
339
+ {
340
+ "version": "0.4.5",
341
+ "timestamp": "2026-07-04T12:00:00.000Z",
342
+ "files": 42,
343
+ "issues": [
344
+ {
345
+ "file": "src/api/handler.js",
346
+ "line": 17,
347
+ "rule": "SEC001",
348
+ "severity": "critical",
349
+ "category": "security",
350
+ "message": "Potential SQL injection: unsanitized input in query string",
351
+ "fix": "Use parameterized queries instead of string concatenation"
352
+ }
353
+ ],
354
+ "summary": {
355
+ "critical": 1,
356
+ "warning": 3,
357
+ "info": 5,
358
+ "score": 72,
359
+ "grade": "C"
360
+ }
361
+ }
362
+ ```
363
+
364
+ ---
365
+
366
+ ## Performance
367
+
368
+ | Metric | Value |
369
+ |----------------|--------------------|
370
+ | Throughput | ~23,000 lines/sec |
371
+ | Test suite | 746 tests |
372
+ | Code coverage | 91.2% |
373
+ | Dependencies | 1 (`@babel/parser`) |
374
+
375
+ ---
376
+
377
+ ## Tiers
378
+
379
+ | Tier | Limit | Features |
380
+ |------------|-----------|---------------------------------------------------|
381
+ | Free | 100 files | Core scanning, all 84 rules, JSON output |
382
+ | Pro | Unlimited | Recurring scans, history, trends, notifications |
383
+ | Team | Unlimited | Dashboard, executive reports, baseline management |
384
+ | Enterprise | Unlimited | Custom rules, priority support, SSO |
385
+
386
+ Activate a license:
387
+
388
+ ```bash
389
+ thuban activate <license-key>
390
+ thuban status
391
+ ```
392
+
393
+ ---
394
+
395
+ ## CI Integration
396
+
397
+ ### GitHub Actions
398
+
399
+ ```yaml
400
+ - name: Thuban Scan
401
+ run: npx thuban scan . --json --baseline
402
+ env:
403
+ THUBAN_LICENSE: ${{ secrets.THUBAN_LICENSE }}
404
+ ```
405
+
406
+ ### Pre-Commit Hook
407
+
408
+ ```bash
409
+ thuban gate . --fail-on critical
410
+ ```
411
+
412
+ ---
413
+
414
+ ## Requirements
415
+
416
+ - Node.js >= 16.0.0
417
+
418
+ ---
419
+
420
+ ## Contributing
421
+
422
+ 1. Fork the repository
423
+ 2. Create a feature branch (`git checkout -b feature/my-feature`)
424
+ 3. Run the test suite (`npm test`)
425
+ 4. Submit a pull request
426
+
427
+ Issues and feature requests: [github.com/SilverwingsBenefitsGit/thuban/issues](https://github.com/SilverwingsBenefitsGit/thuban/issues)
428
+
429
+ ---
430
+
431
+ ## License
432
+
433
+ [MIT](LICENSE)
434
+
435
+ ---
436
+
437
+ [thuban.dev](https://thuban.dev)