VS Code extension

The extension is the vscode-specific layer around the shared engine. Code: src/extension.ts and src/views/.

#Activation

• Activation event: onStartupFinished. The extension loads after VS Code starts, without slowing startup.
• Workspace trust: untrusted workspaces are not supported, because the extension runs git in the project.
• Multi-root workspaces: only the first workspace folder is used.

On activation it:

1. creates the ReportStore (holds the last report in memory) and the DiagnosticsManager;
2. registers the three sidebar views and the four commands;
3. starts live diagnostics: loads the config, watches .clean-code-tracker.json / .clean-code-tracker.local.json for changes, and listens to editor events.

Reports are kept in memory only. Closing VS Code discards them; the per-commit cache on disk makes the next run fast.

#Commands

Run Analysis and Open Dashboard also appear as ▶ and dashboard icons in the title bar of the sidebar's Dashboard view.

#Run Analysis in detail

1. Reads the VS Code settings (readSettings()), see 10 — Configuration reference.
2. Calls analyzeRepository() with the settings, the cache directory (globalStorageUri), and an AbortSignal connected to Cancel.
3. Shows the stages in the notification: Reading rules → Reading Git history → Scanning files (n/N) → Analyzing commits (n/N).
4. Warnings (e.g. "No config found; using default rules") appear as warning messages.
5. Expected errors (not a repo, no commits, invalid config) appear as error messages.
6. On success: stores the report, replaces all diagnostics, opens the dashboard, and shows a summary: N developers · M violations (U unattributed) · F files.

#Sidebar views

The CleanLens icon in the activity bar opens three views (treeProviders.ts):

#Dashboard

A summary list: developers, total violations, unattributed, analyzed files, analyzed commits, time of the last analysis. Before the first run it shows "No analysis yet".

#Developers

One node per developer:

• Label: display name.
• Description: score/100 · N new · X% contrib, plus · not ranked when below the ranking threshold.
• Tooltip: sub-scores, analyzed lines, confidence, new/fixed/existing/ unattributed counts, weighted points, net quality impact, contribution, first/last contribution, emails.
• Children: the violations scored against that developer, most severe first (up to 500). Click one to open the file at that line.
• An extra Unattributed node appears when some violations could not be attributed.

#Violations

Every violation in the report (up to 1,000), sorted by severity, as [severity] Rule title — path:line. The tooltip shows the message; clicking opens the location.

#Dashboard panel

A webview (dashboardPanel.ts, dashboardHtml.ts).

Contents:

• Stat tiles: developers, violations, unattributed, files, commits, last analysis.
• Developer cards, sorted by score lowest first, non-ranked developers last. Each card has a score bar (green ≥ 80, amber 50–79, red < 50), the three sub-scores, a "Not ranked" note when relevant, and analyzed lines, confidence, contribution, new/fixed, existing/unattributed, weighted violations, net quality impact, active days.
• "How the Clean Code Score is measured": a short explanation of the formula.
• Violations table: severity, rule, status/confidence, "introduced by", location.
  • A search box filters by file, rule and developer name.
  • Severity checkboxes filter by severity.
  • Pagination: 10 rows per page.
  • Clicking a location opens the file at that line.
• Re-run analysis button.

Technical notes:

• One panel at a time; opening it again focuses the existing one.
• retainContextWhenHidden keeps filters and page when you switch tabs.
• A strict Content Security Policy: no external resources, inline styles, and only the nonce-tagged inline script.
• It uses VS Code theme variables, so it matches light, dark and high-contrast themes.
• The HTML builder is pure (renderDashboardDocument(report, { nonce, standalone })). With standalone: true it adds fallback colors so the page can be viewed outside VS Code (used for screenshots).
• Messages from the webview: { type: "run" } and { type: "open", file, line }.

#Inline diagnostics

diagnostics.ts owns the cleanlens diagnostic collection. Diagnostics show in the editor (underlines) and in the Problems panel with source CleanLens and the rule id as the code.

Severity mapping:

The underline covers the finding's whole line range (e.g. the whole long function).

#Two feeds

How they interact:

• When live diagnostics are on and a config is loaded, an open file shows its live results. They replace that file's full-report results while it is open.
• When you close the file, turn live diagnostics off, or the config cannot be loaded, the file goes back to the last full-report results (or nothing).
• If the buffer cannot be parsed mid-edit, the previous diagnostics stay.
• Only files inside the workspace folder, with a supported extension and a file: URI, are checked.
• The live feed does not apply the exclude list and does not do attribution. It is a quick feedback loop, not a report.
• Editing the config or local override file reloads the rules and re-checks all open files immediately.

Setting: cleanlens.liveDiagnostics (default true). The deprecated cleanCodeTracker.liveDiagnostics is still read if it was set explicitly.

#Where the extension stores data

#Debugging the extension

Press F5 in this repository. The Run Extension launch configuration builds first (npm: build) and opens an Extension Development Host. See 15 — Development guide.