thuban 0.4.3 → 0.4.5

package/dist/README.md

@@ -1,187 +1,420 @@
-# Thuban
+# Thuban -- Code Intelligence Scanner
 
-Thuban is an independent AI software assurance platform for pull requests, releases, and codebase trust. It combines codebase intelligence, scanner-driven risk detection, and Forge-style verification so teams can decide whether AI-assisted changes are safe to merge.
+[![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)
 
-**Capability boundary:** Thuban is an AI-code-specific triage layer. Deprecated API detection, phantom/hallucinated API detection, and AI code-smell detection are a curated set of common patterns frequently generated by AI coding tools — not an exhaustive or dynamically-learned catalog. The exception is named-export verification, which is real AST-based analysis (via `@babel/parser`, not pattern matching): it checks whether `import { foo } from 'bar'` actually resolves to a real export of `bar`. Thuban's taint tracker (`packages/scanner/taint-tracker.js`) traces user-input sources (`req.query`/`body`/`params`, `process.argv`/`env`, `sys.argv`, `request.args`, etc.) through variable assignment, concatenation, and template interpolation to dangerous SQL/XSS sinks — for JS/TS this now follows taint **across file boundaries** too: if file A exports a tainted value (`module.exports`/`export`) and file B imports it (`require()`/`import`, including destructured imports and re-exports), uses in file B are flagged with `crossFile: true` and a `sourceFile` pointing back to the origin. It does not yet track taint through function call/return boundaries within a file, or across Python module imports. Thuban is not a substitute for deep security auditing. For full interprocedural data-flow assurance, pair Thuban with tools like Semgrep or CodeQL.
+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`.
 
-## Product wedge
+---
 
-Thuban is built around a PR assurance wedge:
+## Quick Start
 
-- connect a GitHub repository through a future GitHub App
-- analyze changed files and architectural blast radius
-- run assurance checks and evidence collection
-- issue a clear verdict with remediation guidance
+```bash
+npm install -g thuban
+thuban scan .
+```
+
+Or run without installing:
 
-This standalone extraction is based on the Thuban product strategy and the prior CODEX specifications inside `orion-main`.
+```bash
+npx thuban scan .
+```
 
-## Repository layout
+JSON output for CI pipelines:
 
-```text
-apps/
-  api/        Express placeholder API for ingestion, assurance, and attestations
-  web/        Next.js placeholder operator UI
-packages/
-  scanner/    Extracted Sentinel scanner and monitoring substrate
-  forge/      Extracted Forge verifier and verification data
-docs/
-  source/     Original CODEX and Orion intelligence specs
-  strategy/   Product strategy and viability docs
-  schema/     Thuban-only database schema extract
-  venture/    Original venture README source
+```bash
+thuban scan . --json
 ```
 
-## What is real today
+---
+
+## Feature Highlights
 
-- `packages/scanner/` contains extracted working Sentinel code from Orion
-- `packages/forge/forge-verifier.js` contains extracted Forge verification logic
-- `packages/forge/data/forge-verifications/` contains historical verification artifacts
-- `docs/` contains the original strategy, viability, and CODEX-era source materials
+### Security Analysis
 
-## What is placeholder today
+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.
+
+```bash
+thuban scan src/ --json
+```
 
-- `apps/api/` is an Express starter aligned to the target product shape
-- `apps/web/` is a minimal Next.js starter for the future assurance dashboard
-- Postgres integration, GitHub App auth, webhook ingestion, PR check-runs, and production orchestration are planned but not yet implemented here
+### Control Flow Graph Analysis
 
-See `ARCHITECTURE.md` for a clear real-vs-placeholder breakdown.
+Detects unreachable code, infinite loops, and dead branches through AST-based control flow graph construction.
 
-## Architecture overview
+### Clone Detection
 
-### Apps
+Multi-language code clone detection with AST normalization. Finds duplicated logic across your codebase.
 
-- `apps/api`: future control plane and integration surface for repos, pull requests, audits, policies, and attestations
-- `apps/web`: future UI for onboarding repos, reviewing audit evidence, and tracking trust history
+```bash
+thuban clones src/
+```
 
-### Packages
+### AI-Generated Code Scoring
 
-- `packages/scanner`: repository scanning, dependency graphing, drift detection, health checks, alerting, and secret/credential exposure scanning for hardcoded API keys, passwords, secrets in source code, `.env` files not gitignored, database connection strings with passwords, private keys, high-entropy strings, and secrets still exposed in git history, and secret/credential exposure scanning for hardcoded API keys, passwords, secrets in source code, `.env` files not gitignored, database connection strings with passwords, private keys, high-entropy strings, and secrets still exposed in git history
-- `packages/forge`: attestation and verification workflow plus verification history
+Scores files for likelihood of AI generation based on structural patterns, naming conventions, and code smells common in LLM output.
 
-### Data
+```bash
+thuban aiscore src/
+```
 
-- Postgres is the intended system of record
-- the included schema extract in `docs/schema/ORION-ECOSYSTEM-SCHEMA.thuban.json` contains only the `thuban` tables from Orion
-- packaged JSON artifacts are historical examples, not the final persistence model
+### Dependency Analysis
 
-## Getting started
+Maps dependency graphs, detects circular imports, and identifies unused or phantom dependencies.
 
-### Prerequisites
+```bash
+thuban deps .
+```
 
-- Node.js 20+
-- npm 10+
-- Postgres 15+ for future API work
+### Mutation Testing (Crucible)
 
-### Install
+Built-in mutation testing engine. 515 seed files generate 1,030 mutations. Validates that your test suite catches real bugs.
 
 ```bash
-npm install
+thuban crucible --mode kenny    # standard mode
+thuban crucible --mode hell     # maximum mutation density
 ```
 
-### Run the placeholder apps
+### Ghost Code Detection
+
+Finds dead exports, unused functions, and unreachable modules.
 
 ```bash
-npm run dev:api
-npm run dev:web
+thuban ghosts src/
 ```
 
-### Explore the extracted code
+### Auto-Fix
 
-- scanner entrypoint: `packages/scanner/index.js`
-- secret scan utility: `quickSecretScan([...files], { rootPath })` or `new SecretScanner({ rootPath }).scanAll()` with output including file path, line number, secret type, severity, and fix recommendation
-- forge verifier: `packages/forge/forge-verifier.js`
-- product strategy: `docs/strategy/THUBAN-PRODUCT-STRATEGY.md`
-- architecture notes: `ARCHITECTURE.md`
+Automatically applies safe fixes for supported rule violations.
 
-## Thuban Pro recurring scans
+```bash
+thuban fix src/
+```
 
-Thuban Pro adds scheduled recurring scans for local repositories with change detection, local history, and notification stubs.
+### HTML Dashboard
 
-### What it does
+Generates a visual HTML report with charts, trends, and drill-down by category.
 
-- stores monitor configuration per repo in `~/.thuban/monitor/config.json`
-- runs the existing scanner pipeline on a schedule
-- saves each run as JSON history in `~/.thuban/monitor/runs/<repo-id>/`
-- compares each run to the previous run to surface:
-  - new issues
-  - resolved issues
-  - issue-count trend
-  - hallucination / secret / tech-debt metric deltas
-- writes notification records to `~/.thuban/monitor/notifications.json`
-- gates monitor/history/trend commands to Pro and above
+```bash
+thuban dashboard .
+```
 
-### Commands
+### Executive Reports
+
+PDF-ready executive summary with risk scores, trend data, and remediation priorities.
 
 ```bash
-npx thuban monitor . --once
-npx thuban monitor . --frequency daily
-npx thuban monitor . --frequency weekly
-npx thuban monitor . --frequency custom --interval-ms 3600000
-npx thuban history .
-npx thuban trend .
+thuban executive .
+thuban pdf .
 ```
 
-### Notification channels
+### Baseline Scanning
 
-Current implementation supports:
+Establish a baseline and track only new issues introduced after that point.
 
-- `inbox` — local notification inbox persisted to disk
-- `console` — console alert via the existing alert manager
-- `email` — stubbed for future delivery integration
-- `webhook` — stubbed for future delivery integration
+```bash
+thuban baseline .          # save current state
+thuban scan . --baseline   # report only new issues
+thuban compare .           # compare current scan to baseline
+```
+
+### Pre-Commit Gate
 
-Example:
+Block commits that introduce issues above a configurable threshold.
 
 ```bash
-npx thuban monitor . --once --notify inbox,console
+thuban gate .
 ```
 
-### How scheduling works
+### 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.
 
-- `daily` = every 24 hours
-- `weekly` = every 7 days
-- `custom` = any interval via `--interval-ms`
-- `npx thuban monitor .` starts a foreground daemon-like process until stopped
-- `npx thuban monitor . --once` performs one scheduled-style run immediately and stores history
+---
 
-### Diff detection
+## Detection Rules
 
-Each issue is fingerprinted from file, category, id, line, and message. Thuban compares the latest run against the previous run and records:
+84 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 84 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
+```
 
-- `added`: issues not seen in the previous run
-- `resolved`: issues that disappeared
-- `metricsDelta`: changes in issue count, hallucinations, secrets, and tech debt metrics
+---
 
-This makes recurring scans useful for “what changed since yesterday?” rather than just “scan again.”
+## Requirements
 
-## Website deployment
+- Node.js >= 16.0.0
 
-The public site at `https://thuban.dev` is deployed from the repository root `docs/` folder via GitHub Pages.
+---
 
-- workflow: `.github/workflows/deploy-website.yml`
-- trigger: pushes to `main` that change `docs/**`, or manual `workflow_dispatch`
-- deploy artifact: the `docs/` directory uploaded directly to GitHub Pages
-- custom domain: `docs/CNAME`
+## Contributing
 
-Important deployment notes:
+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
 
-- `apps/web/` is a placeholder Next.js app and is not part of the live GitHub Pages deployment
-- there is currently no build/export pipeline from `apps/web/` into `docs/`
-- updating `apps/web/` alone will not change `thuban.dev`
-- to update the live site, edit the static files in `docs/` or add a future export step that writes static output into `docs/`
+Issues and feature requests: [github.com/SilverwingsBenefitsGit/thuban/issues](https://github.com/SilverwingsBenefitsGit/thuban/issues)
 
-Current practical workflow:
+---
 
-1. make website content changes in `docs/`
-2. commit and push to `main`
-3. GitHub Actions runs `Deploy Website to GitHub Pages`
-4. GitHub Pages publishes the uploaded `docs/` artifact to `https://thuban.dev`
+## License
 
-## Planned next steps
+[MIT](LICENSE)
 
-1. implement GitHub App installation and webhook ingestion
-2. persist repos, analyses, issues, and fixes in Postgres
-3. convert Sentinel and Forge flows into API-driven services
-4. connect PR check-runs and release attestation exports
-5. build the dashboard for audit runs, verdicts, and trust history
+---
 
+[thuban.dev](https://thuban.dev)