Skip to content

HTML Report

Specification for HTML output generated by pyscn analyze (and by default when no --json/--yaml/--csv/--text flag is given).

File characteristics

Property Value
Path .pyscn/reports/analyze_YYYYMMDD_HHMMSS.html
Encoding UTF-8
External assets None (CSS and JS inlined)
Dependencies None (no CDN, no fonts loaded remotely)
Size Typically 50–500 KB

The file is self-contained and safe to archive, email, or serve from any static host.

Document structure

Element Contents
Top bar pyscn version, project name and root, generation timestamp, file count, duration.
Tab bar Overview plus one tab per area that ran, each with a finding count badge.
Overview Health Score ring and grade, a one-paragraph verdict, size facts, per-dimension score cards, top suggestions, hotspot files, complexity histogram, and summary cards for duplication, classes, and structure.
Detail tabs Functions, Duplication, Classes, Architecture.
Footer Link to pyscn repository and version string.

Score cards, summary cards, and tabs only appear for analyzers that ran. Architecture appears when dependency, architecture, or community analysis ran; layer rules need [architecture] layers configured.

Overview

Block Contents
Verdict Health Score (0–100) drawn as a ring, grade badge (A–F), a headline for the grade, and a sentence naming the clean dimensions and the two or three weakest ones with their key numbers.
Score breakdown One card per enabled dimension (Complexity, Dead code, Duplication, Coupling, Cohesion, Dependencies, Architecture, Communities) with its 0–100 score, a bar colored by band, and two supporting numbers. Cards link to the matching detail tab.
Fix first The five highest-priority suggestions with severity, effort, location, and rationale.
Hotspot files Up to eight modules ranked by high-risk functions, then max complexity, then dead code, then clone fragments.
Complexity distribution Histogram of function complexity binned on the configured risk thresholds, with median, deepest nesting, and longest function.
Duplication / Classes / Structure Compact summary cards linking to their detail tabs.

Detail tabs

Tab Contents
Functions Function complexity metrics, most complex functions (top 20), executable class-scope complexity, longest functions, dead code findings across functions and class scopes (top 20), and two collapsed sortable tables: all modules and directory complexity rollups.
Duplication Clone statistics strip, clone groups (top 10) with fragments and optional code previews, or clone pairs when no groups formed.
Classes Coupling (CBO) and cohesion (LCOM4) strips with the most coupled and least cohesive classes (top 15 each).
Architecture Module dependency metrics, main sequence zones, circular dependencies, longest chains, layer rule violations, and community detection with the macro-architecture graph.

JavaScript

Inline scripts switch tabs (the tab is mirrored into the URL hash so a link can open a specific tab), and route the module and directory tables through one shared sorter. No network requests are made. The standalone complexity formatter renders the same directory metrics above separate function and class-scope tables.

Module rollups use the full analyzer population before min_complexity, report_unchanged, or min_severity presentation filters. Directory complexity uses the reported function population after complexity filters, so its counts and averages reconcile with the Functions tab.

CSS

Styles are inlined from service/templates/analyze/report.css and use CSS custom properties. The main tokens:

Variable Semantic role
--good / --warn / --bad Score bands (75+, 60–74, below 60), risk levels, severities.
--accent Navigation, links, neutral chart bars.
--ink / --ink-2 / --muted Body, secondary, and caption text.
--surface / --page / --line Card, page background, and hairlines.

Dark mode follows the prefers-color-scheme media query, and a data-theme="light" or data-theme="dark" attribute on the root element overrides it. No toggle is rendered.

Auto-open behavior

The report opens in the default browser when all of the following are true:

  • Format is HTML.
  • Stdin is a TTY.
  • SSH_TTY and SSH_CONNECTION environment variables are unset.
  • CI environment variable is unset.
  • --no-open is not passed.

Open mechanism: open on macOS, xdg-open (or gnome-open / kde-open) on Linux, cmd /c start on Windows.

File URL form: file:///{absolute-path-to-report}.

The report path is always printed to stderr regardless of auto-open.

Suppressing auto-open

pyscn analyze --no-open .

Or export CI=true in the environment.

Grade badge mapping

Grade Score Badge color
A 90–100 Green (--good)
B 75–89 Green (--good)
C 60–74 Amber (--warn)
D 45–59 Red (--bad)
F 0–44 Red (--bad)

Cross-references