thuban 0.4.10 → 0.4.12

package/README.md

@@ -1,437 +1,437 @@
-# Thuban -- Code Intelligence Scanner
-
-[![npm version](https://img.shields.io/npm/v/thuban.svg)](https://www.npmjs.com/package/thuban)
-[![license](https://img.shields.io/npm/l/thuban.svg)](LICENSE)
-[![tests](https://img.shields.io/badge/tests-746%20passing-brightgreen.svg)](#testing)
-[![coverage](https://img.shields.io/badge/coverage-91.2%25-brightgreen.svg)](#testing)
-
-AI Code Verification — Catch what AI gets wrong.
-
-Static analysis, security scanning, dead code detection, clone detection, AI-generated code scoring, dependency analysis, and mutation testing for 10 languages. One command. Zero runtime dependencies beyond `@babel/parser`.
-
----
-
-## Quick Start
-
-```bash
-npm install -g thuban
-thuban scan .
-```
-
-Or run without installing:
-
-```bash
-npx thuban scan .
-```
-
-JSON output for CI pipelines:
-
-```bash
-thuban scan . --json
-```
-
----
-
-## Feature Highlights
-
-### Security Analysis
-
-69 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.
-
-```bash
-thuban scan src/ --json
-```
-
-### OWASP Top 10 & CWE Compliance
-
-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.
-
-| OWASP 2021 Category                    | Rules                                  | CWEs                              |
-|-----------------------------------------|----------------------------------------|-----------------------------------|
-| A01 Broken Access Control               | SEC005, SEC013, SEC014                 | CWE-22, CWE-942, CWE-601         |
-| A02 Cryptographic Failures              | SEC006, SEC007, SEC008, SEC016         | CWE-798, CWE-327, CWE-330, CWE-208 |
-| A03 Injection                           | SEC001, SEC002, SEC003, SEC004, SEC009, SEC011, SEC018, SEC019 | CWE-95, CWE-79, CWE-89, CWE-78, CWE-1321 |
-| A04 Insecure Design                     | SEC015                                 | CWE-209                          |
-| A05 Security Misconfiguration           | SEC017                                 | CWE-611                          |
-| A06 Vulnerable Components               | RUST001, RUST002                       | CWE-908, CWE-477                 |
-| A08 Software and Data Integrity         | SEC012                                 | CWE-502                          |
-| A10 SSRF                                | SEC010                                 | CWE-918                          |
-
-### Control Flow Graph Analysis
-
-Detects unreachable code, infinite loops, and dead branches through AST-based control flow graph construction.
-
-### Clone Detection
-
-Multi-language code clone detection with AST normalization. Finds duplicated logic across your codebase.
-
-```bash
-thuban clones src/
-```
-
-### AI-Generated Code Scoring
-
-Scores files for likelihood of AI generation based on structural patterns, naming conventions, and code smells common in LLM output.
-
-```bash
-thuban aiscore src/
-```
-
-### Dependency Analysis
-
-Maps dependency graphs, detects circular imports, and identifies unused or phantom dependencies.
-
-```bash
-thuban deps .
-```
-
-### Mutation Testing (Crucible)
-
-Built-in mutation testing engine. 515 seed files generate 1,030 mutations. Validates that your test suite catches real bugs.
-
-```bash
-thuban crucible --mode kenny    # standard mode
-thuban crucible --mode hell     # maximum mutation density
-```
-
-### Ghost Code Detection
-
-Finds dead exports, unused functions, and unreachable modules.
-
-```bash
-thuban ghosts src/
-```
-
-### Auto-Fix
-
-Automatically applies safe fixes for supported rule violations.
-
-```bash
-thuban fix src/
-```
-
-### HTML Dashboard
-
-Generates a visual HTML report with charts, trends, and drill-down by category.
-
-```bash
-thuban dashboard .
-```
-
-### Executive Reports
-
-PDF-ready executive summary with risk scores, trend data, and remediation priorities.
-
-```bash
-thuban executive .
-thuban pdf .
-```
-
-### Baseline Scanning
-
-Establish a baseline and track only new issues introduced after that point.
-
-```bash
-thuban baseline .          # save current state
-thuban scan . --baseline   # report only new issues
-thuban compare .           # compare current scan to baseline
-```
-
-### Pre-Commit Gate
-
-Block commits that introduce issues above a configurable threshold.
-
-```bash
-thuban gate .
-```
-
-### Inline Suppression
-
-Suppress specific rules on a per-line basis:
-
-```javascript
-const query = "SELECT * FROM " + input; // thuban-ignore SEC001
-```
-
-```python
-password = "admin123"  # thuban-ignore SEC005
-```
-
-Suppress all rules on a line:
-
-```javascript
-eval(code); // thuban-ignore
-```
-
----
-
-## Supported Languages
-
-| Language   | Extension(s)         | AST Engine     |
-|------------|----------------------|----------------|
-| JavaScript | `.js`, `.mjs`, `.cjs`| Babel          |
-| TypeScript | `.ts`                | Babel          |
-| JSX        | `.jsx`               | Babel          |
-| TSX        | `.tsx`               | Babel          |
-| Python     | `.py`                | Python `ast`   |
-| Go         | `.go`                | `go/parser`    |
-| Rust       | `.rs`                | Pattern-based  |
-| Ruby       | `.rb`                | Pattern-based  |
-| Java       | `.java`              | Pattern-based  |
-| C#         | `.cs`                | Pattern-based  |
-| Kotlin     | `.kt`                | Pattern-based  |
-| PHP        | `.php`               | Pattern-based  |
-
-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.
-
----
-
-## Detection Rules
-
-69 rules organized by category:
-
-| Category    | Rule IDs              | Description                                      |
-|-------------|-----------------------|--------------------------------------------------|
-| Security    | SEC001--SEC019        | SQL injection, XSS, hardcoded secrets, eval, command injection, path traversal, insecure crypto, SSRF, prototype pollution, and more |
-| Security    | RUST001--RUST002      | Rust-specific unsafe patterns                    |
-| Quality     | QUAL001--QUAL004      | Code quality, naming, structure                  |
-| Performance | PERF001               | Performance anti-patterns                        |
-| AST         | AST001--AST005        | Phantom imports, deprecated APIs, unused variables, hallucinated APIs, empty catch blocks |
-| AST         | AST011--AST014        | Advanced AST patterns                            |
-| Taint       | TAINT001--TAINT002    | Cross-file taint tracking for SQLi and XSS       |
-| CFG         | CFG001--CFG005        | Unreachable code, infinite loops, dead branches  |
-| Nesting     | NEST001               | Excessive nesting depth                          |
-| Complexity  | CMPLX001--CMPLX002   | Cyclomatic and cognitive complexity              |
-
----
-
-## CLI Commands
-
-28 commands grouped by function:
-
-### Core Scanning
-
-| Command       | Description                                      |
-|---------------|--------------------------------------------------|
-| `scan [path]` | Scan a codebase for issues                       |
-| `diff [path]` | Scan only git-changed files                      |
-| `deps [path]` | Map dependencies and detect circular imports     |
-| `health [path]`| Run health check on codebase                    |
-| `report [path]`| Full scan + deps + drift combined report        |
-
-### Detection
-
-| Command              | Description                                |
-|----------------------|--------------------------------------------|
-| `hallucinate [path]` | Detect AI hallucinations and phantom imports|
-| `ghosts [path]`      | Detect dead code and unused exports        |
-| `aiscore [path]`     | Score files for AI-generated code patterns |
-| `clones [path]`      | Detect code clones across the codebase     |
-| `drift [path]`       | Detect drift from Mother Code annotations  |
-| `debt [path]`        | Analyze technical debt                     |
-| `cost [path]`        | Calculate technical debt cost              |
-
-### Remediation
-
-| Command       | Description                                      |
-|---------------|--------------------------------------------------|
-| `fix [path]`  | Auto-fix supported rule violations               |
-| `inject [path]`| Inject Mother Code DNA widget into files        |
-| `gate [path]` | Pre-commit quality gate                          |
-
-### Reporting
-
-| Command            | Description                                   |
-|--------------------|-----------------------------------------------|
-| `dashboard [path]` | Generate visual HTML dashboard                |
-| `executive [path]` | Generate executive summary report             |
-| `pdf [path]`       | Generate PDF-ready report                     |
-| `passport [path]`  | Generate codebase passport                    |
-
-### Monitoring
-
-| Command          | Description                                     |
-|------------------|-------------------------------------------------|
-| `watch [path]`   | Live sentinel -- continuous file monitoring     |
-| `monitor [path]` | Recurring scans with history and alerts         |
-| `history [path]` | View recurring scan history                     |
-| `trend [path]`   | Show issue trends across scans                  |
-
-### Baseline and Comparison
-
-| Command          | Description                                     |
-|------------------|-------------------------------------------------|
-| `baseline [path]`| Save current scan state as baseline             |
-| `compare [path]` | Compare current scan against baseline           |
-
-### Licensing
-
-| Command    | Description                                          |
-|------------|------------------------------------------------------|
-| `activate` | Activate a license key                               |
-| `status`   | Show current license status                          |
-| `upgrade`  | Upgrade license tier                                 |
-
-### Mutation Testing
-
-| Command    | Description                                          |
-|------------|------------------------------------------------------|
-| `crucible` | Run the Crucible mutation testing engine             |
-
----
-
-## Configuration
-
-### `.thubanrc.json`
-
-Place a `.thubanrc.json` in your project root to configure scan behavior:
-
-```json
-{
-  "$schema": "https://thuban.dev/schema/thubanrc.json",
-  "minScore": 0,
-  "ignore": [
-    "node_modules",
-    "dist",
-    ".git",
-    "coverage"
-  ],
-  "hallucination": {
-    "enabled": true,
-    "ignore": []
-  },
-  "motherCode": {
-    "enabled": true,
-    "autoInject": false
-  },
-  "report": {
-    "format": "html",
-    "outputDir": "."
-  },
-  "ci": {
-    "failOnGrade": "F",
-    "postComment": true
-  }
-}
-```
-
-### `.thubanignore`
-
-Exclude files and directories from scanning, one glob pattern per line:
-
-```
-packages/crucible/seeds/**
-tests/regression/fixtures/**
-vendor/**
-```
-
----
-
-## JSON Output
-
-All scan commands support `--json` for machine-readable output:
-
-```bash
-thuban scan src/ --json
-```
-
-```json
-{
-  "version": "0.4.5",
-  "timestamp": "2026-07-04T12:00:00.000Z",
-  "files": 42,
-  "issues": [
-    {
-      "file": "src/api/handler.js",
-      "line": 17,
-      "rule": "SEC001",
-      "severity": "critical",
-      "category": "security",
-      "message": "Potential SQL injection: unsanitized input in query string",
-      "fix": "Use parameterized queries instead of string concatenation"
-    }
-  ],
-  "summary": {
-    "critical": 1,
-    "warning": 3,
-    "info": 5,
-    "score": 72,
-    "grade": "C"
-  }
-}
-```
-
----
-
-## Performance
-
-| Metric         | Value              |
-|----------------|--------------------|
-| Throughput     | ~23,000 lines/sec  |
-| Test suite     | 746 tests          |
-| Code coverage  | 91.2%              |
-| Dependencies   | 1 (`@babel/parser`) |
-
----
-
-## Tiers
-
-| Tier       | Limit     | Features                                          |
-|------------|-----------|---------------------------------------------------|
-| Free       | 100 files | Core scanning, all 69 rules, JSON output          |
-| Pro        | Unlimited | Recurring scans, history, trends, notifications   |
-| Team       | Unlimited | Dashboard, executive reports, baseline management |
-| Enterprise | Unlimited | Custom rules, priority support, SSO               |
-
-Activate a license:
-
-```bash
-thuban activate <license-key>
-thuban status
-```
-
----
-
-## CI Integration
-
-### GitHub Actions
-
-```yaml
-- name: Thuban Scan
-  run: npx thuban scan . --json --baseline
-  env:
-    THUBAN_LICENSE: ${{ secrets.THUBAN_LICENSE }}
-```
-
-### Pre-Commit Hook
-
-```bash
-thuban gate . --fail-on critical
-```
-
----
-
-## Requirements
-
-- Node.js >= 16.0.0
-
----
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/my-feature`)
-3. Run the test suite (`npm test`)
-4. Submit a pull request
-
-Issues and feature requests: [github.com/SilverwingsBenefitsGit/thuban/issues](https://github.com/SilverwingsBenefitsGit/thuban/issues)
-
----
-
-## License
-
-[MIT](LICENSE)
-
----
-
-[thuban.dev](https://thuban.dev)
+# Thuban -- Code Intelligence Scanner
+
+[![npm version](https://img.shields.io/npm/v/thuban.svg)](https://www.npmjs.com/package/thuban)
+[![license](https://img.shields.io/npm/l/thuban.svg)](LICENSE)
+[![tests](https://img.shields.io/badge/tests-746%20passing-brightgreen.svg)](#testing)
+[![coverage](https://img.shields.io/badge/coverage-91.2%25-brightgreen.svg)](#testing)
+
+AI Code Verification — Catch what AI gets wrong.
+
+Static analysis, security scanning, dead code detection, clone detection, AI-generated code scoring, dependency analysis, and mutation testing for 10 languages. One command. Zero runtime dependencies beyond `@babel/parser`.
+
+---
+
+## Quick Start
+
+```bash
+npm install -g thuban
+thuban scan .
+```
+
+Or run without installing:
+
+```bash
+npx thuban scan .
+```
+
+JSON output for CI pipelines:
+
+```bash
+thuban scan . --json
+```
+
+---
+
+## Feature Highlights
+
+### Security Analysis
+
+69 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.
+
+```bash
+thuban scan src/ --json
+```
+
+### OWASP Top 10 & CWE Compliance
+
+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.
+
+| OWASP 2021 Category                    | Rules                                  | CWEs                              |
+|-----------------------------------------|----------------------------------------|-----------------------------------|
+| A01 Broken Access Control               | SEC005, SEC013, SEC014                 | CWE-22, CWE-942, CWE-601         |
+| A02 Cryptographic Failures              | SEC006, SEC007, SEC008, SEC016         | CWE-798, CWE-327, CWE-330, CWE-208 |
+| A03 Injection                           | SEC001, SEC002, SEC003, SEC004, SEC009, SEC011, SEC018, SEC019 | CWE-95, CWE-79, CWE-89, CWE-78, CWE-1321 |
+| A04 Insecure Design                     | SEC015                                 | CWE-209                          |
+| A05 Security Misconfiguration           | SEC017                                 | CWE-611                          |
+| A06 Vulnerable Components               | RUST001, RUST002                       | CWE-908, CWE-477                 |
+| A08 Software and Data Integrity         | SEC012                                 | CWE-502                          |
+| A10 SSRF                                | SEC010                                 | CWE-918                          |
+
+### Control Flow Graph Analysis
+
+Detects unreachable code, infinite loops, and dead branches through AST-based control flow graph construction.
+
+### Clone Detection
+
+Multi-language code clone detection with AST normalization. Finds duplicated logic across your codebase.
+
+```bash
+thuban clones src/
+```
+
+### AI-Generated Code Scoring
+
+Scores files for likelihood of AI generation based on structural patterns, naming conventions, and code smells common in LLM output.
+
+```bash
+thuban aiscore src/
+```
+
+### Dependency Analysis
+
+Maps dependency graphs, detects circular imports, and identifies unused or phantom dependencies.
+
+```bash
+thuban deps .
+```
+
+### Mutation Testing (Crucible)
+
+Built-in mutation testing engine. 515 seed files generate 1,030 mutations. Validates that your test suite catches real bugs.
+
+```bash
+thuban crucible --mode kenny    # standard mode
+thuban crucible --mode hell     # maximum mutation density
+```
+
+### Ghost Code Detection
+
+Finds dead exports, unused functions, and unreachable modules.
+
+```bash
+thuban ghosts src/
+```
+
+### Auto-Fix
+
+Automatically applies safe fixes for supported rule violations.
+
+```bash
+thuban fix src/
+```
+
+### HTML Dashboard
+
+Generates a visual HTML report with charts, trends, and drill-down by category.
+
+```bash
+thuban dashboard .
+```
+
+### Executive Reports
+
+PDF-ready executive summary with risk scores, trend data, and remediation priorities.
+
+```bash
+thuban executive .
+thuban pdf .
+```
+
+### Baseline Scanning
+
+Establish a baseline and track only new issues introduced after that point.
+
+```bash
+thuban baseline .          # save current state
+thuban scan . --baseline   # report only new issues
+thuban compare .           # compare current scan to baseline
+```
+
+### Pre-Commit Gate
+
+Block commits that introduce issues above a configurable threshold.
+
+```bash
+thuban gate .
+```
+
+### Inline Suppression
+
+Suppress specific rules on a per-line basis:
+
+```javascript
+const query = "SELECT * FROM " + input; // thuban-ignore SEC001
+```
+
+```python
+password = "admin123"  # thuban-ignore SEC005
+```
+
+Suppress all rules on a line:
+
+```javascript
+eval(code); // thuban-ignore
+```
+
+---
+
+## Supported Languages
+
+| Language   | Extension(s)         | AST Engine     |
+|------------|----------------------|----------------|
+| JavaScript | `.js`, `.mjs`, `.cjs`| Babel          |
+| TypeScript | `.ts`                | Babel          |
+| JSX        | `.jsx`               | Babel          |
+| TSX        | `.tsx`               | Babel          |
+| Python     | `.py`                | Python `ast`   |
+| Go         | `.go`                | `go/parser`    |
+| Rust       | `.rs`                | Pattern-based  |
+| Ruby       | `.rb`                | Pattern-based  |
+| Java       | `.java`              | Pattern-based  |
+| C#         | `.cs`                | Pattern-based  |
+| Kotlin     | `.kt`                | Pattern-based  |
+| PHP        | `.php`               | Pattern-based  |
+
+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.
+
+---
+
+## Detection Rules
+
+69 rules organized by category:
+
+| Category    | Rule IDs              | Description                                      |
+|-------------|-----------------------|--------------------------------------------------|
+| Security    | SEC001--SEC019        | SQL injection, XSS, hardcoded secrets, eval, command injection, path traversal, insecure crypto, SSRF, prototype pollution, and more |
+| Security    | RUST001--RUST002      | Rust-specific unsafe patterns                    |
+| Quality     | QUAL001--QUAL004      | Code quality, naming, structure                  |
+| Performance | PERF001               | Performance anti-patterns                        |
+| AST         | AST001--AST005        | Phantom imports, deprecated APIs, unused variables, hallucinated APIs, empty catch blocks |
+| AST         | AST011--AST014        | Advanced AST patterns                            |
+| Taint       | TAINT001--TAINT002    | Cross-file taint tracking for SQLi and XSS       |
+| CFG         | CFG001--CFG005        | Unreachable code, infinite loops, dead branches  |
+| Nesting     | NEST001               | Excessive nesting depth                          |
+| Complexity  | CMPLX001--CMPLX002   | Cyclomatic and cognitive complexity              |
+
+---
+
+## CLI Commands
+
+28 commands grouped by function:
+
+### Core Scanning
+
+| Command       | Description                                      |
+|---------------|--------------------------------------------------|
+| `scan [path]` | Scan a codebase for issues                       |
+| `diff [path]` | Scan only git-changed files                      |
+| `deps [path]` | Map dependencies and detect circular imports     |
+| `health [path]`| Run health check on codebase                    |
+| `report [path]`| Full scan + deps + drift combined report        |
+
+### Detection
+
+| Command              | Description                                |
+|----------------------|--------------------------------------------|
+| `hallucinate [path]` | Detect AI hallucinations and phantom imports|
+| `ghosts [path]`      | Detect dead code and unused exports        |
+| `aiscore [path]`     | Score files for AI-generated code patterns |
+| `clones [path]`      | Detect code clones across the codebase     |
+| `drift [path]`       | Detect drift from Mother Code annotations  |
+| `debt [path]`        | Analyze technical debt                     |
+| `cost [path]`        | Calculate technical debt cost              |
+
+### Remediation
+
+| Command       | Description                                      |
+|---------------|--------------------------------------------------|
+| `fix [path]`  | Auto-fix supported rule violations               |
+| `inject [path]`| Inject Mother Code DNA widget into files        |
+| `gate [path]` | Pre-commit quality gate                          |
+
+### Reporting
+
+| Command            | Description                                   |
+|--------------------|-----------------------------------------------|
+| `dashboard [path]` | Generate visual HTML dashboard                |
+| `executive [path]` | Generate executive summary report             |
+| `pdf [path]`       | Generate PDF-ready report                     |
+| `passport [path]`  | Generate codebase passport                    |
+
+### Monitoring
+
+| Command          | Description                                     |
+|------------------|-------------------------------------------------|
+| `watch [path]`   | Live sentinel -- continuous file monitoring     |
+| `monitor [path]` | Recurring scans with history and alerts         |
+| `history [path]` | View recurring scan history                     |
+| `trend [path]`   | Show issue trends across scans                  |
+
+### Baseline and Comparison
+
+| Command          | Description                                     |
+|------------------|-------------------------------------------------|
+| `baseline [path]`| Save current scan state as baseline             |
+| `compare [path]` | Compare current scan against baseline           |
+
+### Licensing
+
+| Command    | Description                                          |
+|------------|------------------------------------------------------|
+| `activate` | Activate a license key                               |
+| `status`   | Show current license status                          |
+| `upgrade`  | Upgrade license tier                                 |
+
+### Mutation Testing
+
+| Command    | Description                                          |
+|------------|------------------------------------------------------|
+| `crucible` | Run the Crucible mutation testing engine             |
+
+---
+
+## Configuration
+
+### `.thubanrc.json`
+
+Place a `.thubanrc.json` in your project root to configure scan behavior:
+
+```json
+{
+  "$schema": "https://thuban.dev/schema/thubanrc.json",
+  "minScore": 0,
+  "ignore": [
+    "node_modules",
+    "dist",
+    ".git",
+    "coverage"
+  ],
+  "hallucination": {
+    "enabled": true,
+    "ignore": []
+  },
+  "motherCode": {
+    "enabled": true,
+    "autoInject": false
+  },
+  "report": {
+    "format": "html",
+    "outputDir": "."
+  },
+  "ci": {
+    "failOnGrade": "F",
+    "postComment": true
+  }
+}
+```
+
+### `.thubanignore`
+
+Exclude files and directories from scanning, one glob pattern per line:
+
+```
+packages/crucible/seeds/**
+tests/regression/fixtures/**
+vendor/**
+```
+
+---
+
+## JSON Output
+
+All scan commands support `--json` for machine-readable output:
+
+```bash
+thuban scan src/ --json
+```
+
+```json
+{
+  "version": "0.4.5",
+  "timestamp": "2026-07-04T12:00:00.000Z",
+  "files": 42,
+  "issues": [
+    {
+      "file": "src/api/handler.js",
+      "line": 17,
+      "rule": "SEC001",
+      "severity": "critical",
+      "category": "security",
+      "message": "Potential SQL injection: unsanitized input in query string",
+      "fix": "Use parameterized queries instead of string concatenation"
+    }
+  ],
+  "summary": {
+    "critical": 1,
+    "warning": 3,
+    "info": 5,
+    "score": 72,
+    "grade": "C"
+  }
+}
+```
+
+---
+
+## Performance
+
+| Metric         | Value              |
+|----------------|--------------------|
+| Throughput     | ~23,000 lines/sec  |
+| Test suite     | 746 tests          |
+| Code coverage  | 91.2%              |
+| Dependencies   | 1 (`@babel/parser`) |
+
+---
+
+## Tiers
+
+| Tier       | Limit     | Features                                          |
+|------------|-----------|---------------------------------------------------|
+| Free       | 100 files | Core scanning, all 69 rules, JSON output          |
+| Pro        | Unlimited | Recurring scans, history, trends, notifications   |
+| Team       | Unlimited | Dashboard, executive reports, baseline management |
+| Enterprise | Unlimited | Custom rules, priority support, SSO               |
+
+Activate a license:
+
+```bash
+thuban activate <license-key>
+thuban status
+```
+
+---
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+- name: Thuban Scan
+  run: npx thuban scan . --json --baseline
+  env:
+    THUBAN_LICENSE: ${{ secrets.THUBAN_LICENSE }}
+```
+
+### Pre-Commit Hook
+
+```bash
+thuban gate . --fail-on critical
+```
+
+---
+
+## Requirements
+
+- Node.js >= 16.0.0
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Run the test suite (`npm test`)
+4. Submit a pull request
+
+Issues and feature requests: [github.com/SilverwingsBenefitsGit/thuban/issues](https://github.com/SilverwingsBenefitsGit/thuban/issues)
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+[thuban.dev](https://thuban.dev)