From 0a12f3f40f289f5c8352f3da2b96bb9f6cac3966 Mon Sep 17 00:00:00 2001 From: DaisukeYoda <27394393+DaisukeYoda@users.noreply.github.com> Date: Sat, 25 Jul 2026 15:54:06 +0900 Subject: [PATCH 1/5] docs: rework root README as pyscn-style landing page Co-Authored-By: Claude Fable 5 --- README.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 80 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index e2bac38..d00e5e3 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,97 @@ +
+ # polyscan -Multi-language code quality analysis, built as a monorepo around a shared algorithmic core. +**Code quality analyzers for vibe coders, in every language.** + +Building with Cursor, Claude, or ChatGPT? The polyscan family performs structural analysis to keep your codebase maintainable โ€” one shared algorithmic core, one analyzer per language. + +[![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/) +[![Go](https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat-square&logo=go)](https://go.dev/) +[![License](https://img.shields.io/github/license/ludo-technologies/polyscan?style=flat-square)](LICENSE) + +
+ +## Analyzers + +| Language | Analyzer | Install | Where | +|----------|----------|---------|-------| +| JavaScript / TypeScript | [**jscan**](jscan/) | `npx jscan analyze src/` | this monorepo โ€” [`jscan/`](jscan/) | +| Python | [**pyscn**](https://github.com/ludo-technologies/pyscn) | `uvx pyscn@latest analyze .` | independent repository | +| Go | **goscan** | โ€” | planned | + +Every analyzer works the same way: one command scores your whole codebase (0-100 with an A-F grade) and generates an HTML report that shows what to fix first. + +- ๐Ÿงน **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** + +## Shared Core + +All analyzers are built on [`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 +``` + +See [`core/README.md`](core/README.md) for the package catalog and extension points. -## Layout +## 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. + +```bash +# jscan Skills (from this monorepo) +uvx add-skills ludo-technologies/polyscan + +# pyscn Skills +uvx add-skills ludo-technologies/pyscn +``` + +They work with Claude Code, Cursor, Codex, Gemini CLI, and [many other agents](https://github.com/ludo-technologies/add-skills). + +**Claude Code plugin marketplace:** + +```bash +claude plugin marketplace add ludo-technologies/polyscan +claude plugin install jscan@polyscan-marketplace +``` + +## Repository Layout | 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). -Language analyzers planned to move into or start life in this monorepo: +### Versioning + +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* From 93cc4b8b0c9663b433a3f9229c59977d35158893 Mon Sep 17 00:00:00 2001 From: DaisukeYoda <27394393+DaisukeYoda@users.noreply.github.com> Date: Sat, 25 Jul 2026 16:06:02 +0900 Subject: [PATCH 2/5] docs: switch skill installation to Vercel skills CLI (npx skills add) Co-Authored-By: Claude Fable 5 --- README.md | 6 +++--- jscan/README.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d00e5e3..62ec3ca 100644 --- a/README.md +++ b/README.md @@ -48,13 +48,13 @@ The analyzers ship Agent Skills that teach AI coding agents when and how to run ```bash # jscan Skills (from this monorepo) -uvx add-skills ludo-technologies/polyscan +npx skills add ludo-technologies/polyscan # pyscn Skills -uvx add-skills ludo-technologies/pyscn +npx skills add ludo-technologies/pyscn ``` -They work with Claude Code, Cursor, Codex, Gemini CLI, and [many other agents](https://github.com/ludo-technologies/add-skills). +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). **Claude Code plugin marketplace:** 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: From 8b8c55cd647c4fe4ed5c112c4c01c25bba71f48d Mon Sep 17 00:00:00 2001 From: DaisukeYoda <27394393+DaisukeYoda@users.noreply.github.com> Date: Sat, 25 Jul 2026 16:19:39 +0900 Subject: [PATCH 3/5] docs: lead root README with user value, move monorepo details to bottom Co-Authored-By: Claude Fable 5 --- README.md | 61 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 33 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 62ec3ca..09cfa1a 100644 --- a/README.md +++ b/README.md @@ -2,27 +2,30 @@ # polyscan -**Code quality analyzers for vibe coders, in every language.** +**Code quality analyzers for vibe coders โ€” in every language.** -Building with Cursor, Claude, or ChatGPT? The polyscan family performs structural analysis to keep your codebase maintainable โ€” one shared algorithmic core, one analyzer per language. +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/) -[![Go](https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat-square&logo=go)](https://go.dev/) [![License](https://img.shields.io/github/license/ludo-technologies/polyscan?style=flat-square)](LICENSE) -## Analyzers +## Pick Your Language -| Language | Analyzer | Install | Where | -|----------|----------|---------|-------| -| JavaScript / TypeScript | [**jscan**](jscan/) | `npx jscan analyze src/` | this monorepo โ€” [`jscan/`](jscan/) | -| Python | [**pyscn**](https://github.com/ludo-technologies/pyscn) | `uvx pyscn@latest analyze .` | independent repository | -| Go | **goscan** | โ€” | planned | +| Language | Analyzer | Quick start | +|----------|----------|-------------| +| JavaScript / TypeScript | [**jscan**](jscan/) | `npx jscan analyze src/` | +| Python | [**pyscn**](https://github.com/ludo-technologies/pyscn) | `uvx pyscn@latest analyze .` | +| Go | **goscan** | planned | -Every analyzer works the same way: one command scores your whole codebase (0-100 with an A-F grade) and generates an HTML report that shows what to fix first. +No installation needed โ€” the quick-start commands above run the full analysis directly. + +## 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) @@ -30,24 +33,14 @@ Every analyzer works the same way: one command scores your whole codebase (0-100 - ๐Ÿ—๏ธ **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** - -## Shared Core - -All analyzers are built on [`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 -``` - -See [`core/README.md`](core/README.md) for the package catalog and extension points. +**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. ```bash -# jscan Skills (from this monorepo) +# jscan Skills npx skills add ludo-technologies/polyscan # pyscn Skills @@ -56,6 +49,14 @@ npx skills add ludo-technologies/pyscn 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: + +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 @@ -63,21 +64,25 @@ claude plugin marketplace add ludo-technologies/polyscan claude plugin install jscan@polyscan-marketplace ``` -## Repository Layout +--- + +## 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 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). - -### Versioning +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. Each module is tagged with a directory prefix, e.g. `core/v0.2.1`, `jscan/v0.9.1`. ---- - ## Documentation ๐Ÿ“– **[pyscn documentation site](https://ludo-technologies.github.io/pyscn/)** โ€ข **[jscan README](jscan/README.md)** โ€ข **[core README](core/README.md)** From 5cd5ec88d6fb428deef51f0650bb9cc9dde7a512 Mon Sep 17 00:00:00 2001 From: DaisukeYoda <27394393+DaisukeYoda@users.noreply.github.com> Date: Sat, 25 Jul 2026 16:41:45 +0900 Subject: [PATCH 4/5] docs: restructure Quick Start per-language, tighten tagline Co-Authored-By: Claude Fable 5 --- README.md | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 09cfa1a..231edaa 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # polyscan -**Code quality analyzers for vibe coders โ€” in every language.** +**Code quality analyzers for AI Agent** 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. @@ -13,15 +13,25 @@ Building with Cursor, Claude, or ChatGPT? polyscan performs structural analysis -## Pick Your Language +## Quick Start +No installation needed โ€” the quick-start commands below run the full analysis directly. -| Language | Analyzer | Quick start | -|----------|----------|-------------| -| JavaScript / TypeScript | [**jscan**](jscan/) | `npx jscan analyze src/` | -| Python | [**pyscn**](https://github.com/ludo-technologies/pyscn) | `uvx pyscn@latest analyze .` | -| Go | **goscan** | planned | +### JavaScript / TypeScript +``` +npx jscan analyze src/ +``` + +See: [**jscan**](jscan/) + +### Python +``` +uvx pyscn@latest analyze . +``` + +See: [**pyscn**](https://github.com/ludo-technologies/pyscn) -No installation needed โ€” the quick-start commands above run the full analysis directly. +### Others +We are also planning to support other languages (C++, Go, Rust and etc...) ## What You Get @@ -44,10 +54,10 @@ The analyzers ship Agent Skills that teach AI coding agents when and how to run npx skills add ludo-technologies/polyscan # pyscn Skills -npx skills add ludo-technologies/pyscn +uvx add-skills ludo-technologies/pyscn ``` -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). +They work with Claude Code, Cursor, Codex, Gemini CLI, and other agents. Then just ask your agent: From 2caf1bd913c05491aeea7d4ccb5905d41f220264 Mon Sep 17 00:00:00 2001 From: DaisukeYoda <27394393+DaisukeYoda@users.noreply.github.com> Date: Sat, 25 Jul 2026 16:45:31 +0900 Subject: [PATCH 5/5] docs: fix English wording in tagline and Others section Co-Authored-By: Claude Fable 5 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 231edaa..9dc3581 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # polyscan -**Code quality analyzers for AI Agent** +**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. @@ -31,7 +31,7 @@ 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 etc...) +We are also planning to support other languages (C++, Go, Rust, and more). ## What You Get