ludo-technologies/pyscn/cli-analysis

Python Code Quality Analysis with the pyscn CLI

Use the pyscn command-line tool when the task needs report files, CI integration, or project configuration.

No install needed: uvx pyscn@latest <command> (or pip install pyscn for a permanent install).

Commands

analyze — full analysis and reports

pyscn analyze .                          # human-readable summary + health score
pyscn analyze --json src/                # also write a JSON report file
pyscn analyze --html src/                # interactive HTML report
pyscn analyze --select complexity,deadcode src/   # only specific analyses
pyscn analyze --skip-clones src/         # clones are the slowest analysis
pyscn analyze --min-complexity 10 --min-severity critical src/

Key flags:

• --json / --html / --csv / --yaml: generate a report file
• --select: complexity,deadcode,clones,cbo,lcom,deps,communities
• --skip-clones, --skip-cbo, --skip-deps, ...: skip individual analyses
• --clone-threshold (default 0.65), --min-complexity (default 5), --min-cbo
• --no-open: don't auto-open HTML reports in a browser (use in scripts)

Report files are NOT written to stdout. They go to .pyscn/reports/ under the current working directory with timestamped names like analyze_20260702_221139.json, and the path is printed on completion. To consume results programmatically: run with --json, capture the printed path (or take the newest file in .pyscn/reports/), then read that file.

check — CI quality gate

pyscn check .                                        # complexity + deadcode + clones
pyscn check --select complexity --max-complexity 10 src/
pyscn check --select deps src/                       # fail on circular dependencies
pyscn check --allow-dead-code --skip-clones src/
pyscn check -q .                                     # quiet: output only on issues

Exit codes: 0 no issues, 1 quality issues found, 2 analysis failed (invalid input, missing files). Default gates: complexity > 10 fails, critical dead code fails, clones warn only, dependency cycles fail.

--select accepts: complexity, deadcode, clones, deps, mockdata, di (dependency-injection anti-patterns).

Configuration

Settings load in priority order: command-line flags > .pyscn.toml > [tool.pyscn] in pyproject.toml > defaults. Run pyscn init to scaffold .pyscn.toml when a project wants persistent thresholds.

Reporting Results

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