Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
refactor(cli): stage health_command into view, scope and renderer functions (#4074)
Raghav Chamadiya8a86c65a7b79
diff --git a/packages/cli/src/repowise/cli/commands/health_cmd/command.py b/packages/cli/src/repowise/cli/commands/health_cmd/command.pyindex 8a483191a..1aa8760ef 100644--- a/packages/cli/src/repowise/cli/commands/health_cmd/command.py+++ b/packages/cli/src/repowise/cli/commands/health_cmd/command.py@@ -9,6 +9,7 @@ table, writes it back to the index.from __future__ import annotationsimport json+from dataclasses import dataclassfrom pathlib import Pathfrom typing import Any@@ -205,97 +206,172 @@ def health_command(``--recompute`` re-runs it in-process over the working tree."""configure_cli_logging(verbose=verbose)+ opts = _Options(+ fmt=fmt,+ file_filter=file_filter,+ module_filter=module_filter,+ refactoring_targets=refactoring_targets,+ plan_id=plan_id,+ recompute=recompute,+ generate_code=generate_code,+ scope=scope,+ counts=counts,+ trend_view=trend_view,+ )- # Silence structlog/stdlib info+debug lines when the user asked for a- # machine-readable format so stdout is pure JSON/Markdown and safe to- # pipe into jq or other tools (e.g. `repowise health --format json | jq .kpis`).+ # A machine-readable format keeps stdout pure for `--format json | jq`:+ # logs are silenced and status lines go to stderr.if fmt != "table":silence_logs_for_machine_output_until_close()-- # Status output goes to stderr when the user asked for a machine-readable- # format — otherwise rich's banner pollutes stdout and breaks- # `repowise health --format json | jq …` (and the CI smoke test).status = err_console if fmt != "table" else console+ repo_path = _resolve_repo_path(path, no_workspace, repo_alias, status)+ status.print(f"[bold]repowise health[/bold] — {repo_path}")+ if _render_stored_view(repo_path, status, opts):+ return++ report, hotspots, languages = _load_report(repo_path, opts)+ metrics, findings, unanalysed = _scope_report(report, hotspots, opts)+ metrics_sorted = sorted(metrics, key=lambda m: m.score)++ if generate_code is not None:+ suggestions = _scoped_suggestions(report, opts)+ # Attaches the same batched validation block the read surfaces emit;+ # code generation remains explicitly requested and never auto-applies.+ _load_recommendations(repo_path, suggestions, metrics_sorted, findings)+ _generate_refactoring_code(repo_path, suggestions, generate_code, fmt=fmt)+ elif refactoring_targets:+ suggestions = _scoped_suggestions(report, opts)+ recommendations = _load_recommendations(repo_path, suggestions, metrics_sorted, findings)+ _render_refactoring_targets(metrics_sorted, findings, recommendations, fmt=fmt)+ elif badge_view:+ _render_badge(report.kpis.get("average_health"), report.kpis.get("analysed_share"))+ elif fmt == "json":+ _render_json(repo_path, report, metrics_sorted, findings, opts)+ elif fmt == "md":+ _render_md(report, findings)+ else:+ _render_table(+ repo_path, report, (metrics, metrics_sorted), findings, unanalysed, languages, opts+ )+++@dataclass(frozen=True)+class _Options:+ """The options that pick a view and narrow the report."""++ fmt: str+ file_filter: str | None+ module_filter: str | None+ refactoring_targets: bool+ plan_id: str | None+ recompute: bool+ generate_code: str | None+ scope: str+ counts: str+ trend_view: bool++ @property+ def controls_set(self) -> bool:+ """``--scope`` or ``--counts`` asks for other than the stored reading."""+ return (+ parse_scope(self.scope) != DEFAULT_SCOPE or parse_counts(self.counts) != DEFAULT_COUNTS+ )++ def keeps(self, file_path: str) -> bool:+ """Whether ``--file`` and ``--module`` keep a row on *file_path*."""+ if self.file_filter and file_path != self.file_filter:+ return False+ return not (self.module_filter and not file_path.startswith(self.module_filter))+++def _resolve_repo_path(+ path: str | None, no_workspace: bool, repo_alias: str | None, status: Any+) -> Path:+ """The repository to report on: the named or primary workspace repo, else *path*'s."""target = resolve_command_target(path=path, no_workspace_flag=no_workspace, repo_alias=repo_alias)target.notice(status, command="health")-- if target.is_workspace:- if target.repo_filter is not None:- picked = target.resolve_repo_alias(target.repo_filter)- if picked is None:- raise click.ClickException(f"Unknown repo alias: {target.repo_filter}")- repo_path = picked- else:- primary = target.primary_path()- if primary is None:- raise click.ClickException("Workspace has no primary repo configured.")- repo_path = primary- else:+ if not target.is_workspace:assert target.repo_path is not None- repo_path = target.repo_path-- status.print(f"[bold]repowise health[/bold] — {repo_path}")-- if trend_view:- # The trend reads stored snapshots, which carry the calibrated score- # only. Saying so beats printing a projected headline's flag over an- # unprojected line.- if parse_scope(scope) != DEFAULT_SCOPE or parse_counts(counts) != DEFAULT_COUNTS:+ return target.repo_path+ if target.repo_filter is not None:+ picked = target.resolve_repo_alias(target.repo_filter)+ if picked is None:+ raise click.ClickException(f"Unknown repo alias: {target.repo_filter}")+ return picked+ primary = target.primary_path()+ if primary is None:+ raise click.ClickException("Workspace has no primary repo configured.")+ return primary+++def _render_stored_view(repo_path: Path, status: Any, opts: _Options) -> bool:+ """The trend, one plan or the stored refactoring queue; ``False`` when none was asked for."""+ if opts.trend_view:+ # Stored snapshots carry the calibrated score only: say so rather than+ # print a projected headline's flag over an unprojected line.+ if opts.controls_set:status.print("[dim]The trend reads stored snapshots, so --scope and --counts ""do not apply to it.[/dim]")- _render_trend(repo_path, fmt=fmt)- return-- if plan_id is not None:- if not _render_plan_recipe(repo_path, plan_id, fmt=fmt):+ _render_trend(repo_path, fmt=opts.fmt)+ return True+ if opts.plan_id is not None:+ if not _render_plan_recipe(repo_path, opts.plan_id, fmt=opts.fmt):raise click.ClickException(- f"No stored refactoring plan {plan_id}. `repowise health --refactoring-targets` "- "lists the current plans."+ f"No stored refactoring plan {opts.plan_id}. "+ "`repowise health --refactoring-targets` lists the current plans.")- return-- if refactoring_targets and not recompute and generate_code is None:+ return True+ if opts.refactoring_targets and not opts.recompute and opts.generate_code is None:# The stored queue is the calibrated reading, as on MCP and the web UI.- if parse_scope(scope) != DEFAULT_SCOPE or parse_counts(counts) != DEFAULT_COUNTS:+ if opts.controls_set:status.print("[dim]The stored queue does not take --scope or --counts; pass ""--recompute to apply them.[/dim]")if not _render_stored_refactoring_targets(- repo_path, fmt=fmt, file_filter=file_filter, module_filter=module_filter+ repo_path, fmt=opts.fmt, file_filter=opts.file_filter, module_filter=opts.module_filter):raise click.ClickException("No stored refactoring analysis for this repository. Run `repowise init` ""or `repowise update`, or pass --recompute to analyze in-process.")- return+ return True+ return False- if recompute or generate_code is not None:++def _load_report(repo_path: Path, opts: _Options) -> tuple[Any, set[str], dict[str, str]]:+ """``(report, hotspot paths, language by path)``, recomputed or as stored."""+ if opts.recompute or opts.generate_code is not None:# Written back only for a whole-repo table: json/md are read by scripts# and CI, and a file or module run is an inspection, not repo state.- report, hotspots, languages = _recompute_report(- repo_path, persist=fmt == "table" and not file_filter and not module_filter+ return _recompute_report(+ repo_path,+ persist=opts.fmt == "table" and not opts.file_filter and not opts.module_filter,)- else:- stored = _load_stored_report(repo_path)- if stored is None:- raise click.ClickException(- "No stored health analysis for this repository. Run `repowise init` "- "or `repowise update`, or pass --recompute to analyze in-process."- )- report, hotspots, languages = stored-- metrics = report.metrics- if file_filter:- metrics = [m for m in metrics if m.file_path == file_filter]- if module_filter:- metrics = [m for m in metrics if m.file_path.startswith(module_filter)]- narrowed = parse_scope(scope) == "production"+ stored = _load_stored_report(repo_path)+ if stored is None:+ raise click.ClickException(+ "No stored health analysis for this repository. Run `repowise init` "+ "or `repowise update`, or pass --recompute to analyze in-process."+ )+ return stored+++def _scope_report(+ report: Any, hotspots: set[str], opts: _Options+) -> tuple[list[Any], list[Any], int]:+ """``(metrics, findings, unanalysed)`` narrowed by the filters, ``--scope`` and ``--counts``.++ When ``--scope`` or ``--counts`` changes the reading, ``report.kpis`` is+ recomputed over the narrowed metrics.+ """+ metrics = [m for m in report.metrics if opts.keeps(m.file_path)]+ narrowed = parse_scope(opts.scope) == "production"if narrowed:metrics = [m for m in metrics if not m.is_test]# Taken before the projection, so a row the projection cannot read still@@ -304,132 +380,135 @@ def health_command(# Files in a language health has no dialect for carry no score: they are# counted, never ranked or averaged.metrics, unanalysed = split_unscored(metrics)- code_shape = parse_counts(counts) == "code_shape"+ code_shape = parse_counts(opts.counts) == "code_shape"if code_shape:# No `unscored` counterpart to the API's: this command scores live, so# every row carries the split the projection reads.- metrics, _ = project_counts(counts, metrics)+ metrics, _ = project_counts(opts.counts, metrics)if narrowed or code_shape:- # Every figure the controls select for. Defect accuracy below is not- # one of them: it scores the ranking against `prior_defect`, and- # narrowing leaves it no labels to be accurate about.+ # Defect accuracy is not recomputed: it scores the ranking against+ # `prior_defect`, and narrowing leaves it no labels.report.kpis = compute_kpis(metrics,hotspots,unanalysed=unanalysed,deductions=deduction_by_path(report.findings),)- metrics_sorted = sorted(metrics, key=lambda m: m.score)- findings = report.findings- if file_filter:- findings = [f for f in findings if f.file_path == file_filter]- if module_filter:- findings = [f for f in findings if f.file_path.startswith(module_filter)]- if narrowed:+ findings = _scope_findings(report.findings, opts, scoped_paths if narrowed else None)+ return metrics, findings, unanalysed+++def _scope_findings(+ findings: list[Any], opts: _Options, scoped_paths: set[str] | None+) -> list[Any]:+ """*findings* the filters keep, on *scoped_paths* when ``--scope`` narrowed the files."""+ findings = [f for f in findings if opts.keeps(f.file_path)]+ if scoped_paths is not None:findings = [f for f in findings if f.file_path in scoped_paths]- if code_shape:+ if parse_counts(opts.counts) == "code_shape":# A history finding cannot explain a score the history half was taken# out of, so it is not part of this reading.findings = split_by_origin(findings)[0]+ return findings- if generate_code is not None:- suggestions = getattr(report, "refactoring_suggestions", None) or []- if file_filter:- suggestions = [s for s in suggestions if s.file_path == file_filter]- if module_filter:- suggestions = [s for s in suggestions if s.file_path.startswith(module_filter)]- # Attaches the same batched validation block the read surfaces emit;- # code generation remains explicitly requested and never auto-applies.- _load_recommendations(repo_path, suggestions, metrics_sorted, findings)- _generate_refactoring_code(repo_path, suggestions, generate_code, fmt=fmt)- return- if refactoring_targets:- suggestions = getattr(report, "refactoring_suggestions", None) or []- if file_filter:- suggestions = [s for s in suggestions if s.file_path == file_filter]- if module_filter:- suggestions = [s for s in suggestions if s.file_path.startswith(module_filter)]- recommendations = _load_recommendations(repo_path, suggestions, metrics_sorted, findings)- _render_refactoring_targets(metrics_sorted, findings, recommendations, fmt=fmt)- return+def _scoped_suggestions(report: Any, opts: _Options) -> list[Any]:+ suggestions = getattr(report, "refactoring_suggestions", None) or []+ return [s for s in suggestions if opts.keeps(s.file_path)]- if badge_view:- _render_badge(report.kpis.get("average_health"), report.kpis.get("analysed_share"))- return- if fmt == "json":+def _render_json(+ repo_path: Path, report: Any, metrics_sorted: list[Any], findings: list[Any], opts: _Options+) -> None:+ click.echo(+ json.dumps(+ {+ "kpis": report.kpis,+ "scope": parse_scope(opts.scope),+ "counts": parse_counts(opts.counts),+ # Findings, causes, plans and Fix first items, as every+ # surface counts them; ``shown`` is 0, nothing is listed.+ "queue_counts": _load_queue_counts(repo_path),+ "metrics": [+ {+ "file_path": m.file_path,+ "score": m.score,+ "max_ccn": m.max_ccn,+ "max_nesting": m.max_nesting,+ "nloc": m.nloc,+ "has_test_file": m.has_test_file,+ "line_coverage_pct": m.line_coverage_pct,+ "branch_coverage_pct": m.branch_coverage_pct,+ "duplication_pct": m.duplication_pct,+ }+ for m in metrics_sorted+ ],+ "findings": [+ {+ "biomarker_type": f.biomarker_type,+ "severity": str(f.severity),+ "file_path": f.file_path,+ "function_name": f.function_name,+ "health_impact": f.health_impact,+ "details": detail_map(f),+ "reason": f.reason,+ }+ for f in findings+ ],+ },+ indent=2,+ )+ )+++def _render_md(report: Any, findings: list[Any]) -> None:+ click.echo("# Code Health Report\n")+ for k, v in report.kpis.items():+ click.echo(f"- **{k}**: {v}")+ click.echo("\n## Findings\n")+ for f in findings:click.echo(- json.dumps(- {- "kpis": report.kpis,- "scope": parse_scope(scope),- "counts": parse_counts(counts),- # Findings, causes, plans and Fix first items, as every- # surface counts them; ``shown`` is 0, nothing is listed.- "queue_counts": _load_queue_counts(repo_path),- "metrics": [- {- "file_path": m.file_path,- "score": m.score,- "max_ccn": m.max_ccn,- "max_nesting": m.max_nesting,- "nloc": m.nloc,- "has_test_file": m.has_test_file,- "line_coverage_pct": m.line_coverage_pct,- "branch_coverage_pct": m.branch_coverage_pct,- "duplication_pct": m.duplication_pct,- }- for m in metrics_sorted- ],- "findings": [- {- "biomarker_type": f.biomarker_type,- "severity": str(f.severity),- "file_path": f.file_path,- "function_name": f.function_name,- "health_impact": f.health_impact,- "details": detail_map(f),- "reason": f.reason,- }- for f in findings- ],- },- indent=2,- )+ f"- [{f.severity}] `{f.file_path}` {f.function_name or ''} "+ f"- {f.reason} (impact -{f.health_impact:.2f})")- return- if fmt == "md":- click.echo("# Code Health Report\n")- for k, v in report.kpis.items():- click.echo(f"- **{k}**: {v}")- click.echo("\n## Findings\n")- for f in findings:- click.echo(- f"- [{f.severity}] `{f.file_path}` {f.function_name or ''} "- f"- {f.reason} (impact -{f.health_impact:.2f})"- )- return- # Table format+def _render_table(+ repo_path: Path,+ report: Any,+ metrics: tuple[list[Any], list[Any]],+ findings: list[Any],+ unanalysed: int,+ languages: dict[str, str],+ opts: _Options,+) -> None:+ """The terminal report. *metrics* is ``(as scoped, sorted by score)``."""+ from repowise.core.analysis.health.grading import distribution as health_distribution++ scoped, metrics_sorted = metrics+ # Lead with what to fix; a narrowed run is an inspection, not the worklist.+ if not opts.file_filter and not opts.module_filter:+ _render_fix_first(_load_fix_first(repo_path, limit=FIX_FIRST_ROWS))+ _render_headline(report.kpis, parse_counts(opts.counts) == "code_shape", unanalysed)+ _render_split_line(report.kpis)+ _render_distribution_line(health_distribution(scoped))+ _render_defect_accuracy_line(report)+ # Lead with the finding count, density and coverage, not the bounded /10+ # average. Metrics carry no language, so it comes with the report.+ _render_performance_section(report, languages)+ _render_files_table(metrics_sorted)+ _render_findings_table(findings)+++def _render_headline(kpis: dict[str, Any], code_shape: bool, unanalysed: int) -> None:from repowise.core.analysis.health.grading import (BAND_LABEL,BAND_TERMINAL_COLOR,analysed_note,- band_for,headline_band,)- from repowise.core.analysis.health.grading import (- distribution as health_distribution,- )- # Lead with what to fix; a narrowed run is an inspection, not the worklist.- if not file_filter and not module_filter:- _render_fix_first(_load_fix_first(repo_path, limit=FIX_FIRST_ROWS))-- kpis = report.kpisavg = kpis.get("average_health")band_str = ""band = headline_band(avg, kpis.get("analysed_share"))@@ -453,15 +532,10 @@ def health_command(note = analysed_note(kpis.get("file_count") or 0, kpis.get("unanalysed_file_count") or 0)if note:console.print(f"[dim]Code health {note}.[/dim]")- _render_split_line(kpis)- _render_distribution_line(health_distribution(metrics))- _render_defect_accuracy_line(report)- # Performance pillar section: lead with the finding COUNT + density +- # coverage (the honest signal), not the bounded /10 average. Metrics carry- # no language, so it comes with the report from either source.- _render_performance_section(report, languages)+def _render_files_table(metrics_sorted: list[Any]) -> None:+ from repowise.core.analysis.health.grading import BAND_TERMINAL_COLOR, band_fortable = Table(title=f"Lowest-scoring files ({min(len(metrics_sorted), 20)})")table.add_column("File", style="cyan")@@ -482,26 +556,29 @@ def health_command()console.print(table)- if findings:- # The total get_overview prints; advisory rows are listed, not counted.- console.print(f"\n[bold]{open_finding_count(findings)}[/bold] open findings:")- f_table = Table()- f_table.add_column("Severity", style="magenta")- f_table.add_column("Marker", style="cyan")- f_table.add_column("File")- f_table.add_column("Function")- f_table.add_column("Impact", justify="right")- for f in findings[:30]:- f_table.add_row(- str(f.severity),- f.biomarker_type,- f.file_path,- f.function_name or "-",- f"-{f.health_impact:.2f}",- )- console.print(f_table)- for line in preview_lines("health", findings[:30], kind="biomarker_type"):- console.print(f"[dim]{line}[/dim]")++def _render_findings_table(findings: list[Any]) -> None:+ if not findings:+ return+ # The total get_overview prints; advisory rows are listed, not counted.+ console.print(f"\n[bold]{open_finding_count(findings)}[/bold] open findings:")+ f_table = Table()+ f_table.add_column("Severity", style="magenta")+ f_table.add_column("Marker", style="cyan")+ f_table.add_column("File")+ f_table.add_column("Function")+ f_table.add_column("Impact", justify="right")+ for f in findings[:30]:+ f_table.add_row(+ str(f.severity),+ f.biomarker_type,+ f.file_path,+ f.function_name or "-",+ f"-{f.health_impact:.2f}",+ )+ console.print(f_table)+ for line in preview_lines("health", findings[:30], kind="biomarker_type"):+ console.print(f"[dim]{line}[/dim]")def _recompute_report(repo_path: Path, *, persist: bool) -> tuple[Any, set[str], dict[str, str]]: