diff --git a/README.md b/README.md index e2bac38..9dc3581 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,112 @@ +
+ # polyscan -Multi-language code quality analysis, built as a monorepo around a shared algorithmic core. +**Code quality analyzers for AI agents** + +Building with Cursor, Claude, or ChatGPT? polyscan performs structural analysis to keep your codebase maintainable: one command scores your whole codebase and shows what to fix first. + +[![CI](https://github.com/ludo-technologies/polyscan/actions/workflows/ci.yml/badge.svg)](https://github.com/ludo-technologies/polyscan/actions/workflows/ci.yml) +[![npm](https://img.shields.io/npm/v/jscan?style=flat-square&logo=npm&label=jscan)](https://www.npmjs.com/package/jscan) +[![PyPI](https://img.shields.io/pypi/v/pyscn?style=flat-square&logo=pypi&label=pyscn)](https://pypi.org/project/pyscn/) +[![License](https://img.shields.io/github/license/ludo-technologies/polyscan?style=flat-square)](LICENSE) + +
+ +## Quick Start +No installation needed โ€” the quick-start commands below run the full analysis directly. + +### JavaScript / TypeScript +``` +npx jscan analyze src/ +``` + +See: [**jscan**](jscan/) + +### Python +``` +uvx pyscn@latest analyze . +``` + +See: [**pyscn**](https://github.com/ludo-technologies/pyscn) + +### Others +We are also planning to support other languages (C++, Go, Rust, and more). + +## What You Get + +Every analyzer scores your codebase (0-100 with an A-F grade) and generates an HTML report that shows what to fix first, looking at your code from five angles: + +- ๐Ÿงน **Dead code** - unreachable code you can safely delete +- ๐Ÿ“‹ **Duplicate code** - copy-pasted and structurally similar code worth merging (Type 1-4 clone detection) +- ๐ŸŒ€ **Complexity** - functions that are hard to read and test +- ๐Ÿ—๏ธ **Dependencies** - circular imports and unstable module dependencies +- ๐Ÿงฉ **Class design** - classes that do too much or depend on too much (CBO coupling, LCOM cohesion) + +**Built with Go + tree-sitter** โ€” fast enough to run on every commit. + +## AI Agent Integration + +The analyzers ship Agent Skills that teach AI coding agents when and how to run each analysis: health checks, refactoring, architecture review, and CI-friendly reports. -## Layout +```bash +# jscan Skills +npx skills add ludo-technologies/polyscan + +# pyscn Skills +uvx add-skills ludo-technologies/pyscn +``` + +They work with Claude Code, Cursor, Codex, Gemini CLI, and other agents. + +Then just ask your agent: + +1. "Analyze the code quality of the src/ directory" + +2. "Find duplicate code and help me refactor it" + +3. "Show me complex code and help me simplify it" + +**Claude Code plugin marketplace:** + +```bash +claude plugin marketplace add ludo-technologies/polyscan +claude plugin install jscan@polyscan-marketplace +``` + +--- + +## How It's Built + +All analyzers share [`core/`](core/), a standalone, language-agnostic Go module: APTED tree edit distance, LSH/MinHash clone indexing, CFG analysis, dead code detection, and coupling/cohesion metrics. Language-specific behavior is injected via interfaces, so a new analyzer only implements parsing and classification. + +```bash +go get github.com/ludo-technologies/polyscan/core +``` | Directory | Description | |-----------|-------------| -| [`core/`](core/) | Language-agnostic analysis algorithms (APTED tree edit distance, LSH/MinHash, CFG analysis, clone detection, coupling/cohesion metrics) as a standalone Go module | +| [`core/`](core/) | Language-agnostic analysis algorithms as a standalone Go module | | [`jscan/`](jscan/) | JavaScript/TypeScript code quality analyzer and standalone Go module | -jscan moved here from its former standalone repository, [ludo-technologies/jscan](https://github.com/ludo-technologies/jscan); releases up to v0.9.0 live there, and newer releases ship from this monorepo under the same npm package name [`jscan`](https://www.npmjs.com/package/jscan). +jscan moved here from its former standalone repository, [ludo-technologies/jscan](https://github.com/ludo-technologies/jscan); releases up to v0.9.0 live there, and newer releases ship from this monorepo under the same npm package name [`jscan`](https://www.npmjs.com/package/jscan). [pyscn](https://github.com/ludo-technologies/pyscn) remains an independent repository and consumes `core/` as a Go module dependency. -Language analyzers planned to move into or start life in this monorepo: +Each module is tagged with a directory prefix, e.g. `core/v0.2.1`, `jscan/v0.9.1`. -- **goscan** (Go) โ€” planned +## Documentation -[pyscn](https://github.com/ludo-technologies/pyscn) (Python) remains an independent repository and consumes `core/` as a Go module dependency. +๐Ÿ“– **[pyscn documentation site](https://ludo-technologies.github.io/pyscn/)** โ€ข **[jscan README](jscan/README.md)** โ€ข **[core README](core/README.md)** -## Versioning +For contributors: **[Contributing](CONTRIBUTING.md)** โ€ข **[Code of Conduct](CODE_OF_CONDUCT.md)** โ€ข **[Security](SECURITY.md)** -Each module is tagged with a directory prefix, e.g. `core/v0.2.0`. +## Enterprise Support + +For commercial support, custom integrations, or consulting services, contact us at contact@ludo-tech.org ## License -MIT +MIT License โ€” see [LICENSE](LICENSE) + +--- + +*Built with โค๏ธ using Go and tree-sitter* diff --git a/jscan/README.md b/jscan/README.md index 83b7498..5c3cbf6 100644 --- a/jscan/README.md +++ b/jscan/README.md @@ -48,10 +48,10 @@ jscan ships Agent Skills that teach AI coding agents when and how to run each an ### Agent Skills (Recommended) ```bash -uvx add-skills ludo-technologies/polyscan +npx skills add ludo-technologies/polyscan ``` -This installs the Skills into your project. They work with Claude Code, Cursor, Codex, Gemini CLI, and [many other agents](https://github.com/ludo-technologies/add-skills) (add `--agent cursor` etc. to target one, `--global` for all projects). +This installs the Skills into your project. They work with Claude Code, Cursor, Codex, Gemini CLI, and [70+ other agents](https://github.com/vercel-labs/skills) (add `--agent cursor` etc. to target one, `--global` for all projects). Then just ask your agent: