ludo-technologies/polyscan/cli-analysis

Code Quality Analysis with the polyscan CLI

Use the polyscan command-line tool when the task needs report files, CI integration, or machine-readable results. It analyzes JavaScript, TypeScript, Go, Rust and C++ in one run; the language of each file is detected from its extension.

No install needed: npx polyscan@latest analyze <path> (or npm install -g polyscan for a permanent install). The examples below use a bare polyscan for readability — prefix with npx polyscan@latest when polyscan isn't installed.

analyze — the one command

polyscan analyze .                            # HTML report (polyscan-report.html) + opens browser
polyscan analyze --no-open .                  # HTML report without opening a browser
polyscan analyze --format json src/           # JSON results to stdout
polyscan analyze --format text src/           # human-readable text to stdout
polyscan analyze --select complexity,clone .  # only specific analyses
polyscan analyze --no-open -o report.html .   # custom report path
polyscan analyze --min-complexity 10 .        # list only functions at or above 10

Key flags:

• --format html|json|text (-f): output format; json and text write to stdout instead of an HTML report
• --select (-s): complexity,deadcode,clone,cbo,lcom,deps (all run by default); deps applies to Go and JavaScript/TypeScript; cbo to Go, Rust and JavaScript/TypeScript; lcom to Go and Rust; deadcode to JavaScript/TypeScript only
• --no-open: don't auto-open the HTML report in a browser (use in scripts)
• -o <path>: HTML report path (default: polyscan-report.html in the current directory)
• --min-complexity <n>: hide functions below this complexity from the listing (scores still cover everything)
• --exclude <patterns>: leave files and directories out of every analysis; a glob without a slash matches a file name or a directory anywhere on the path (fixtures), one with a slash matches a path relative to the analyzed directory with ** for any number of segments (src/generated/**)
• --include-tests: analyze test files and test code, which are left out by default (*_test.go, *.test.*, *.spec.*, __tests__/, Rust #[cfg(test)] and tests/, C++ *_test.* and test/)

With --format json, the machine-readable results go to stdout and the health-score summary goes to stderr, so stdout stays parseable.

Language coverage

Complexity and clone detection cover every supported language. Dependency analysis covers Go and JavaScript/TypeScript. Class coupling (CBO) covers Go, Rust and JavaScript/TypeScript, and class cohesion (LCOM4) Go and Rust. Dead code exists for JavaScript/TypeScript only. The health score is computed over the dimensions that ran: a dimension a language does not have is left out, not scored as clean.

check — CI quality gate

polyscan check                                # check the current directory
polyscan check --select complexity src/       # complexity only
polyscan check --max-complexity 15 src/       # raise the complexity limit
polyscan check --max-cycles 3 .               # allow up to 3 dependency cycles
polyscan check --allow-dead-code .            # report dead code without failing
polyscan check -q .                           # quiet: output only on issues

Exit codes: 0 no issues, 1 quality issues found, 2 analysis failed (invalid flag, missing path, unparsable file). Default gates: a function with complexity above 10 fails, critical dead code fails (JavaScript/TypeScript only), and any circular dependency fails. Clone detection runs only with --select clone and never fails the check.

--select accepts: complexity, deadcode, clone, deps (default: complexity,deadcode,deps).

analyze always exits 0 when the analysis ran. To gate on the health score or another report field, use its JSON output:

polyscan analyze --format json src/ > report.json
jq -e '.summary.health_score >= 75' report.json

Configuration

One .polyscan.toml configures every language. polyscan reads the nearest one in the first analyzed path or a directory above it; --config <file> (-c) names a different file. Flags take precedence over the file, and --exclude adds to its patterns.

[analysis]
exclude = ["fixtures", "src/generated/**"]
 
[complexity]
low_threshold = 10
medium_threshold = 20
 
[check]
max_complexity = 15

The file is strict: an unknown key or an out-of-range value fails the run. polyscan does not read jscan.config.json; a directory that has one and no .polyscan.toml fails with an error naming the file. The full key list is at https://docs.codescan.dev/polyscan/configuration/reference/.

Reporting Results

Summarize the health score and grade, list the specific functions/files behind each failing category, and suggest fixes. For CI setup, recommend polyscan check in the pipeline and periodic polyscan analyze HTML reports for deep reviews.