Dark Code Auditor — User Guide
What is Dark Code?
Dark Code is code in production that nobody fully understands. It could be AI-generated code that was never reviewed, code copied from Stack Overflow without context, or modules written by developers who have left. Dark Code Auditor gives you a score from 0 to 100 measuring how well your team understands the codebase.
Getting Started
1. Connect GitHub
Navigate to Dark Code Auditor in the tool menu under DevOps. Click Connect GitHub to authorize access. We request repo (read access to private repos) and read:user (profile information).
Tokens are stored encrypted in Supabase Vault — we never see the token in plaintext.
2. Select a Repository
After connecting, your GitHub repos appear sorted by last updated. Select the repo you want to scan. Both private and public repos are supported.
3. Run a Scan
Choose your scan mode:
- Heuristic (5 credits) — Automated analysis of documentation, types, error handling, test coverage, and file size. Fast and affordable.
- AI-Augmented (15 credits) — Everything in heuristic + Gemini re-evaluates ambiguous files (score 30–70), detects AI-generated code, and provides natural-language recommendations.
Click Scan and wait. Progress is displayed in real time.
Understanding Results
Overall Score (0–100)
| Score | Grade | Meaning |
|---|---|---|
| 80–100 | A | Well-documented and understood codebase |
| 60–79 | B | Mostly good, some gaps |
| 40–59 | C | Significant Dark Code risk |
| 20–39 | D | Critical — lots of unknown code |
| 0–19 | F | Acute — the codebase is practically incomprehensible |
6 Dimensions
- Structural — Do files have JSDoc/header comments in the first 20 lines?
- Semantic — Do files export type interfaces and classes?
- Test Coverage — Are there matching .test.* or .spec.* files?
- Error Handling — Do files use try/catch, .catch, or throw?
- AI-Generated — Do files contain markers of AI-generated code?
- Dependency Health — Are dependencies up to date and secure?
Per-Module Breakdown
Each directory level in the repo gets its own score. Drill down to find the most problematic modules.
Recommendations
The tool generates prioritized recommendations with:
- Category (documentation, types, testing, error handling, architecture, security)
- Effort (low, medium, high)
- Impact (low, medium, high)
- Number of affected files
Privacy Mode (CLI)
Don't want to grant GitHub access? Use Privacy Mode:
- Generate a manifest locally with our CLI command
- Upload the manifest in the tool
- The same analysis runs without us seeing your source code
Trend Tracking
Run scans regularly to track improvement over time. Under the History tab you can compare two scans and see:
- Score change per dimension
- Modules that improved/degraded
- New/resolved issues
Pricing
| Mode | Credits |
|---|---|
| Heuristic scan | 5 |
| AI-augmented analysis | 15 |
Frequently Asked Questions
Is my code safe? Yes. GitHub tokens are encrypted in Supabase Vault using pgsodium. We only read file content for analysis and delete data after 30 days (Scout) or 12 months (paid plans).
Which languages are supported? TypeScript/JavaScript, Python, Java, Go, and C# in V1.
How many files can be scanned? Up to 10,000 files. Repos with more files use sampling mode.
Can I scan private repos?
Yes, after connecting GitHub with the repo scope.
Last updated 2026-04-14