@purpleprivacy/tesseract-cli

Tesseract — Cognitive & Architectural Compass for Codebases

Tesseract helps you see where thinking gets hard in a TypeScript/JavaScript codebase.
Unlike linters (syntax/style) or generic code smells, Tesseract focuses on cognitive load, coupling, and architecture health using a project-wide import graph.

Status: MVP metrics & CLI are working (table output).
Next: JSON/PDF reports, dead code reachability, orphan exports, cycles, instability.

✨ What It Does (Today)

Runs a static analysis over your TS/JS project and reports per-file metrics:

• Cyclomatic Complexity — branching points (if/for/while/switch/&&/||) aggregated per file
• Nesting Depth — approximation of average nested block depth
• Fan-Out — number of imports in a file (currently all imports, incl. third‑party)
• Fan-In — how many other files import this file (local dependency graph)
• Token Density — tokens per line (visual density proxy)
• Score — weighted composite (0–100) approximating cognitive load

Example output:

npx tsx src/cli.ts ./src

┌───────────────────────────┬───────┬──────┬───────┬────────┬─────────┬───────┐
│ File                      │ Cyclo │ Nest │ FanIn │ FanOut │ Density │ Score │
├───────────────────────────┼───────┼──────┼───────┼────────┼─────────┼───────┤
│ ./src/cli.ts              │ 0     │ 0    │ 0     │ 3      │ 2.94    │ 1     │
│ ./src/core/analyzer.ts    │ 12    │ 0    │ 1     │ 5      │ 3.86    │ 6     │
│ ./src/core/metrics.ts     │ 6     │ 0    │ 1     │ 0      │ 4.35    │ 3     │
│ ./src/core/parser.ts      │ 1     │ 0    │ 1     │ 1      │ 2.83    │ 1     │
│ ./src/core/scorer.ts      │ 1     │ 0    │ 1     │ 0      │ 4.00    │ 1     │
│ ./src/output/reporter.ts  │ 5     │ 0    │ 1     │ 2      │ 3.46    │ 3     │
└───────────────────────────┴───────┴──────┴───────┴────────┴─────────┴───────┘

🧭 Why It’s Different (State of the Art)

• ESLint excels at file‑local rules (unused vars/imports, style, safety).
  Tesseract focuses on project-wide cognition and architecture signals.
• SonarQube surfaces code smells & coverage.
  Tesseract adds a graph perspective (fan‑in/out, reachability, cycles soon) and cognitive weighting to prioritize what to refactor first.
• Dependency graph tools show links; Tesseract combines graph + complexity to identify hotspots (high load + high coupling).

Positioning: a Refactoring Compass that guides legacy migrations and Clean Architecture / DDD alignment.

🚀 Quick Start

Requirements: Node 18+ (Node 20+ recommended), npm.

# install dependencies
npm install

# run analysis against your 'src' folder
npx tsx src/cli.ts ./src

By default, Tesseract scans recursively for .ts and .js files.

CLI Options (current)

• <path>: folder to analyze (e.g., ./src)

Upcoming flags (next iteration):

• --out <dir>: reports output directory (default report/)
• --json <file> / --pdf <file>: override output paths
• --no-json / --no-pdf: disable a report type

🧠 Metric Definitions

Metric	What it measures	Why it matters
Cyclomatic	Total decision points across functions	More paths → harder reasoning & testing
Nesting	Approx. average nested block depth	Indentation increases mental effort
Fan‑Out	Count of imports (local and third‑party, today)	Coupling & outward dependencies
Fan‑In	Count of files that import this file (local graph)	Indicates how many depend on you
Token Density	Tokens per line	Visual parsing difficulty
Score	Weighted composite (0–100)	Single “load” index for prioritization

Risk Bands (Score):

• 🟢 0–29 — Clear
• 🟡 30–59 — Manageable
• 🔴 60–100 — Heavy (consider refactor)

Note: thresholds will be tuned with real‑world datasets.

🧩 How Fan‑In / Fan‑Out Are Computed

• Fan‑Out: count of import … from "<specifier>" statements in a file (currently includes third‑party and local).
  Planned: --local-only to restrict Fan‑Out to relative (.//../) imports.
• Fan‑In: number of files that import this file. We resolve relative module specifiers to actual files using these candidates:
  • dep, dep.ts, dep.js, dep/index.ts, dep/index.js
  • Non‑relative imports (e.g. "react", "fs") are ignored for Fan‑In.

📦 Project Layout

src/
  cli.ts                # CLI entry
  core/
    parser.ts           # ts-morph source loading & import collection
    metrics.ts          # metric computations
    scorer.ts           # composite score weighting
    analyzer.ts         # orchestrates parse → metrics → score
  output/
    reporter.ts         # CLI table rendering
    formatter.ts        # risk bands, colors, benchmarks (extensible)

🧪 Current Limitations

• Cyclomatic & nesting are first‑pass approximations (AST‑aware upgrades planned).
• Fan‑Out includes third‑party imports by default (may inflate coupling; configurable soon).
• Fan‑In only tracks relative imports (by design); workspace/TSPath aliases require mapping (planned).
• No JSON/PDF reports in main yet — tracked in Next (see roadmap).

🛣️ Roadmap (Next Iterations)

• Reports
  • JSON report writer (summary + per‑file), default report/cognitive-report.json
  • PDF report (legend, benchmarks, hotspots, full listing), default report/cognitive-report.pdf
• Graph & Architecture
  • Dead Modules (unreachable from configured entry points)
  • Orphan Exports (exported but unused across project)
  • Cycles (SCC detection) and cycle mass
  • Instability I = fanOut / (fanIn + fanOut) + outlier surfacing
• Config
  • .tesseract.json: entry points, ignore globs, analysis depth, local‑only fan‑out
  • TS path alias resolution (paths/baseUrl)
• Quality
  • AST‑level cognitive complexity improvements
  • Performance profiling for large repos

🔧 Development

Useful commands during development:

# run analysis against this repo
npx tsx src/cli.ts ./src

# typecheck
npx tsc --noEmit

Tech: TypeScript, ts‑morph, commander, cli‑table3.

🤝 Contributing

PRs welcome! Please keep changes small and focused.

• Prefer adding metrics behind flags/config.
• Include before/after examples for any scoring change.
• Mind performance (avoid O(N²) surprises on large graphs).

(CONTRIBUTING.md coming soon)

Thanks !

📄 License

MIT — see LICENSE (to be added).