jscan

README

jscan

A code quality analyzer for JavaScript/TypeScript vibe coders.

Building with Cursor, Claude, or ChatGPT? jscan performs structural analysis to keep your codebase maintainable.

Working with Python? Check out pyscn

Quick Start

# Run analysis without installation
npx jscan analyze src/

Demo

https://github.com/user-attachments/assets/6c491b52-99d3-4fa4-b628-e09c0b61451d

Features

• Dead code detection – CFG + DFS reachability analysis for unreachable code, unused imports/exports, and orphan files
• Clone detection – APTED tree edit distance with MinHash/LSH pre-filtering (Type 1–4)
• Circular dependency detection – Tarjan's Strongly Connected Components (O(V+E))
• Cyclomatic complexity – McCabe complexity including logical operators and ternaries
• CBO / Instability – Graph-based dependency metrics (Ca, Ce, Instability, Main Sequence distance)
• Health score – Weighted multi-factor scoring based on violation ratios

Parallel execution • Multiple output formats (Analyze: HTML/JSON/Text, Deps: Text/JSON/DOT) • Built with Go + tree-sitter

Installation

# Install globally with npm (recommended)
npm install -g jscan

Alternative installation methods

Build from source

git clone https://github.com/ludo-technologies/jscan.git
cd jscan
go build -o jscan ./cmd/jscan

Go install

go install github.com/ludo-technologies/jscan/cmd/jscan@latest

Common Commands

jscan analyze

Run comprehensive analysis with HTML report

jscan analyze src/                              # All analyses with HTML report
jscan analyze --format json src/                # Generate JSON report
jscan analyze --select complexity src/          # Only complexity analysis
jscan analyze --select deadcode src/            # Only dead code analysis
jscan analyze --select complexity,deadcode,clone src/  # Multiple analyses

jscan check

Fast CI-friendly quality gate

jscan check src/                         # Quick pass/fail check

jscan init

Create configuration file

jscan init                               # Generate jscan.config.json

jscan deps

Dependency visualization

jscan deps src/ --format dot | dot -Tsvg -o deps.svg

💡 Run jscan --help or jscan <command> --help for complete options

Configuration

Create a jscan.config.json or .jscanrc.json in your project root:

{
  "complexity": {
    "low_threshold": 10,
    "medium_threshold": 20,
    "enabled": true
  },
  "dead_code": {
    "enabled": true,
    "min_severity": "warning"
  },
  "output": {
    "format": "text",
    "show_details": true
  }
}

⚙️ Run jscan init to generate a configuration file with core options

Roadmap

• TypeScript-specific analysis features (type-aware dead code, generic complexity)
• Vue / JSX single-file component support
• IDE / editor integrations
• Watch mode for continuous analysis

---

Documentation

📚 Development Guide • Architecture • Testing • Contributing

Enterprise Support

For commercial support, custom integrations, or consulting services, contact us at contact@ludo-tech.org

License

MIT License — see LICENSE

---

Built with ❤️ using Go and tree-sitter