debtector 0.4.2__tar.gz → 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {debtector-0.4.2/src/debtector.egg-info → debtector-0.5.0}/PKG-INFO +31 -1
- {debtector-0.4.2 → debtector-0.5.0}/README.md +30 -0
- {debtector-0.4.2 → debtector-0.5.0}/pyproject.toml +2 -2
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/__init__.py +1 -1
- debtector-0.5.0/src/debtector/audit/__init__.py +31 -0
- debtector-0.5.0/src/debtector/audit/cycle_priority.py +60 -0
- debtector-0.5.0/src/debtector/audit/health_score.py +77 -0
- debtector-0.5.0/src/debtector/audit/lcom4.py +47 -0
- debtector-0.5.0/src/debtector/audit/testrisk.py +138 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/cli.py +242 -13
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/git_history.py +100 -45
- {debtector-0.4.2 → debtector-0.5.0/src/debtector.egg-info}/PKG-INFO +31 -1
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector.egg-info/SOURCES.txt +7 -0
- debtector-0.5.0/tests/test_cli_audit.py +219 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_git_history.py +56 -14
- debtector-0.5.0/tests/test_git_paths_integration.py +202 -0
- {debtector-0.4.2 → debtector-0.5.0}/LICENSE +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/setup.cfg +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/config.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/embedder.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/graph_store.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/indexer.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/logging.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/metrics.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/models.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/parser/__init__.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/parser/base.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/parser/js_parser.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/parser/python_parser.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector/utils.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector.egg-info/dependency_links.txt +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector.egg-info/entry_points.txt +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector.egg-info/requires.txt +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/src/debtector.egg-info/top_level.txt +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_ci_reporter.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_cli_baseline.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_cli_git.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_cli_human.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_cli_json.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_cli_metrics.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_codeindexignore.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_config.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_covers.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_fts.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_graph_store.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_graph_store_extra.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_indexer.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_indexer_edge_cases.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_logging.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_metrics.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_metrics_cycles.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_metrics_god_modules.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_metrics_inheritance.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_metrics_resolution.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_metrics_uses_type.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_models.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_ratcheting.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_semantic.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_severity.py +0 -0
- {debtector-0.4.2 → debtector-0.5.0}/tests/test_silent_mode.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: debtector
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.5.0
|
|
4
4
|
Summary: Coupling guardrail for CI/PR: detects cycles, god modules and coupling regressions before merge
|
|
5
5
|
Author: aitormf
|
|
6
6
|
License: AGPL-3.0-or-later
|
|
@@ -220,6 +220,36 @@ Total: 8 hotspots
|
|
|
220
220
|
|
|
221
221
|
---
|
|
222
222
|
|
|
223
|
+
## Identifying files affected by a task
|
|
224
|
+
|
|
225
|
+
When you start from a natural-language description ("add rate limiting", "refactor the payments module") and need to know which files of the repo are involved, debtector provides deterministic data that narrows the search. The recommended flow is:
|
|
226
|
+
|
|
227
|
+
1. **Find candidates by keywords.** `debtector search` (FTS5 + BM25) returns symbols lexically related to the task, ranked by relevance:
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
debtector --json search "rate limit"
|
|
231
|
+
debtector --json search "AuthService" --kind Class
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
2. **Expand the impact radius.** Once seed files are identified, `debtector impact` performs BFS over the graph and returns every file and node that depends on them, directly or transitively:
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
debtector --json impact src/auth/service.py
|
|
238
|
+
debtector --json impact src/auth/service.py src/auth/middleware.py --depth 3
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
3. **Enrich with risk and coverage.** Crossing the resulting set with metrics and tests gives architectural context to prioritize what to read:
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
debtector --json coupling # which modules in the impact set are god / unstable
|
|
245
|
+
debtector --json untested src/auth/ # which parts lack test coverage
|
|
246
|
+
debtector --json hotspots # which modules in the impact set accumulate debt
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
Each step emits stable JSON and composes easily from scripts, IDEs, CI or agents. Step 1 is lexical: if the task uses synonyms that do not appear in the code (e.g. "rate limiting" when the module is called `throttle`), the caller decides which candidates are relevant — debtector does not invent.
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
223
253
|
## Ratcheting in CI
|
|
224
254
|
|
|
225
255
|
The typical CI flow is:
|
|
@@ -200,6 +200,36 @@ Total: 8 hotspots
|
|
|
200
200
|
|
|
201
201
|
---
|
|
202
202
|
|
|
203
|
+
## Identifying files affected by a task
|
|
204
|
+
|
|
205
|
+
When you start from a natural-language description ("add rate limiting", "refactor the payments module") and need to know which files of the repo are involved, debtector provides deterministic data that narrows the search. The recommended flow is:
|
|
206
|
+
|
|
207
|
+
1. **Find candidates by keywords.** `debtector search` (FTS5 + BM25) returns symbols lexically related to the task, ranked by relevance:
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
debtector --json search "rate limit"
|
|
211
|
+
debtector --json search "AuthService" --kind Class
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
2. **Expand the impact radius.** Once seed files are identified, `debtector impact` performs BFS over the graph and returns every file and node that depends on them, directly or transitively:
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
debtector --json impact src/auth/service.py
|
|
218
|
+
debtector --json impact src/auth/service.py src/auth/middleware.py --depth 3
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
3. **Enrich with risk and coverage.** Crossing the resulting set with metrics and tests gives architectural context to prioritize what to read:
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
debtector --json coupling # which modules in the impact set are god / unstable
|
|
225
|
+
debtector --json untested src/auth/ # which parts lack test coverage
|
|
226
|
+
debtector --json hotspots # which modules in the impact set accumulate debt
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Each step emits stable JSON and composes easily from scripts, IDEs, CI or agents. Step 1 is lexical: if the task uses synonyms that do not appear in the code (e.g. "rate limiting" when the module is called `throttle`), the caller decides which candidates are relevant — debtector does not invent.
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
203
233
|
## Ratcheting in CI
|
|
204
234
|
|
|
205
235
|
The typical CI flow is:
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "debtector"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.5.0"
|
|
8
8
|
description = "Coupling guardrail for CI/PR: detects cycles, god modules and coupling regressions before merge"
|
|
9
9
|
license = {text = "AGPL-3.0-or-later"}
|
|
10
10
|
authors = [{name = "aitormf"}]
|
|
@@ -69,7 +69,7 @@ skips = []
|
|
|
69
69
|
# ---------------------------------------------------------------------------
|
|
70
70
|
[tool.commitizen]
|
|
71
71
|
name = "cz_conventional_commits"
|
|
72
|
-
version = "0.
|
|
72
|
+
version = "0.5.0"
|
|
73
73
|
version_files = ["pyproject.toml:version", "src/debtector/__init__.py"]
|
|
74
74
|
tag_format = "v$version"
|
|
75
75
|
annotated_tag = true # git push --follow-tags solo sube tags anotados
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
"""Audit surface: second presenter over the existing graph backend.
|
|
2
|
+
|
|
3
|
+
See ``docs/decisions/003-audit-as-second-surface.md`` for the design rationale.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from .cycle_priority import PrioritizedCycle, prioritize_cycles
|
|
9
|
+
from .health_score import HealthScore, SeverityCounts, compute_health_score
|
|
10
|
+
from .lcom4 import compute_lcom4
|
|
11
|
+
from .testrisk import (
|
|
12
|
+
CohesionFinding,
|
|
13
|
+
TestRiskFinding,
|
|
14
|
+
critical_knowledge_concentration,
|
|
15
|
+
untested_high_coupling,
|
|
16
|
+
untested_hotspots,
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
__all__ = [
|
|
20
|
+
"CohesionFinding",
|
|
21
|
+
"HealthScore",
|
|
22
|
+
"PrioritizedCycle",
|
|
23
|
+
"SeverityCounts",
|
|
24
|
+
"TestRiskFinding",
|
|
25
|
+
"compute_health_score",
|
|
26
|
+
"compute_lcom4",
|
|
27
|
+
"critical_knowledge_concentration",
|
|
28
|
+
"prioritize_cycles",
|
|
29
|
+
"untested_high_coupling",
|
|
30
|
+
"untested_hotspots",
|
|
31
|
+
]
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
"""Cycle prioritization for the audit surface.
|
|
2
|
+
|
|
3
|
+
Cycles are detected by :func:`debtector.metrics.find_cycles` (Tarjan SCCs over
|
|
4
|
+
``IMPORTS_FROM`` and ``CALLS``). For an auditor, the raw list is not enough:
|
|
5
|
+
a cycle that traps a high-fan-in module is far more urgent to break than a
|
|
6
|
+
cycle between two leaf modules.
|
|
7
|
+
|
|
8
|
+
The heuristic adopted here ranks each cycle by the **fan-in (Ca) of its most
|
|
9
|
+
exposed node** — i.e. ``max(fan_in[n] for n in cycle)``. Breaking that cycle
|
|
10
|
+
unblocks the largest blast radius first. This is the "qué ciclo romper primero"
|
|
11
|
+
question stated in the Phase 3 audit spec.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
from dataclasses import dataclass
|
|
17
|
+
|
|
18
|
+
from ..graph_store import GraphStore
|
|
19
|
+
from ..metrics import compute_metrics, find_cycles
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
@dataclass(frozen=True)
|
|
23
|
+
class PrioritizedCycle:
|
|
24
|
+
"""A detected cycle paired with the prioritization signal.
|
|
25
|
+
|
|
26
|
+
Args:
|
|
27
|
+
cycle: Qualified names of the nodes in the strongly connected component.
|
|
28
|
+
max_fan_in: Maximum fan-in (Ca) across ``cycle``. Higher = break first.
|
|
29
|
+
pivot: Node within the cycle that has the highest fan-in (Ca).
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
cycle: list[str]
|
|
33
|
+
max_fan_in: float
|
|
34
|
+
pivot: str = ""
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def prioritize_cycles(store: GraphStore) -> list[PrioritizedCycle]:
|
|
38
|
+
"""Rank detected cycles by the fan-in of their most exposed node.
|
|
39
|
+
|
|
40
|
+
Args:
|
|
41
|
+
store: ``GraphStore`` holding the indexed project.
|
|
42
|
+
|
|
43
|
+
Returns:
|
|
44
|
+
Cycles ordered by ``max_fan_in`` descending. Empty list if no cycles
|
|
45
|
+
exist (including the empty-graph case) — never raises.
|
|
46
|
+
"""
|
|
47
|
+
cycles = find_cycles(store)
|
|
48
|
+
if not cycles:
|
|
49
|
+
return []
|
|
50
|
+
|
|
51
|
+
fan_in_by_file: dict[str, float] = {m.file_path: m.fan_in for m in compute_metrics(store)}
|
|
52
|
+
|
|
53
|
+
ranked: list[PrioritizedCycle] = []
|
|
54
|
+
for cycle in cycles:
|
|
55
|
+
fan_ins = [(n, fan_in_by_file.get(n, 0.0)) for n in cycle]
|
|
56
|
+
max_fan_in = max((f for _, f in fan_ins), default=0.0)
|
|
57
|
+
pivot = max(fan_ins, key=lambda x: x[1])[0] if fan_ins else ""
|
|
58
|
+
ranked.append(PrioritizedCycle(cycle=cycle, max_fan_in=max_fan_in, pivot=pivot))
|
|
59
|
+
ranked.sort(key=lambda c: c.max_fan_in, reverse=True)
|
|
60
|
+
return ranked
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
"""Aggregated health score for the audit surface.
|
|
2
|
+
|
|
3
|
+
Reduces a heterogeneous list of audit findings (testRisk joins, future
|
|
4
|
+
coupling / cycle / cohesion findings) to a single ``0-100`` score plus a
|
|
5
|
+
breakdown by severity (``critical`` / ``high`` / ``medium`` / ``low``).
|
|
6
|
+
|
|
7
|
+
The score is a *deduction-from-100* metric: each finding subtracts a weight
|
|
8
|
+
according to its severity. The weights are tuned so a healthy project stays
|
|
9
|
+
above 80, a project with a handful of high-severity findings hovers around
|
|
10
|
+
50, and chronically debt-loaded projects floor at 0. Severities outside the
|
|
11
|
+
known buckets are ignored — callers can add new dimensions without forcing
|
|
12
|
+
a weight decision here.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
from collections.abc import Iterable
|
|
18
|
+
from dataclasses import dataclass
|
|
19
|
+
from typing import Any
|
|
20
|
+
|
|
21
|
+
#: Per-severity penalty applied to the score. Must match docs/audit-schema.md.
|
|
22
|
+
_SEVERITY_WEIGHTS: dict[str, float] = {
|
|
23
|
+
"critical": 15,
|
|
24
|
+
"high": 5,
|
|
25
|
+
"medium": 2,
|
|
26
|
+
"low": 0.5,
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
@dataclass(frozen=True)
|
|
31
|
+
class SeverityCounts:
|
|
32
|
+
"""Count of findings grouped by severity bucket."""
|
|
33
|
+
|
|
34
|
+
critical: int = 0
|
|
35
|
+
high: int = 0
|
|
36
|
+
medium: int = 0
|
|
37
|
+
low: int = 0
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
@dataclass(frozen=True)
|
|
41
|
+
class HealthScore:
|
|
42
|
+
"""Aggregated audit score and its severity breakdown.
|
|
43
|
+
|
|
44
|
+
Args:
|
|
45
|
+
score: Integer in ``[0, 100]``. ``100`` means no issues, ``0`` is
|
|
46
|
+
the floor when penalties exceed 100 points.
|
|
47
|
+
counts: Number of findings per severity bucket.
|
|
48
|
+
"""
|
|
49
|
+
|
|
50
|
+
score: int
|
|
51
|
+
counts: SeverityCounts
|
|
52
|
+
|
|
53
|
+
# Prevent pytest from collecting this dataclass as a test class.
|
|
54
|
+
__test__ = False
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def compute_health_score(findings: Iterable[Any]) -> HealthScore:
|
|
58
|
+
"""Aggregate audit findings into a single health score.
|
|
59
|
+
|
|
60
|
+
Args:
|
|
61
|
+
findings: Iterable of objects exposing a ``severity`` attribute whose
|
|
62
|
+
value is one of ``"critical"``, ``"high"``, ``"medium"``,
|
|
63
|
+
``"low"`` (case-insensitive). Unknown severities are ignored.
|
|
64
|
+
|
|
65
|
+
Returns:
|
|
66
|
+
A :class:`HealthScore` with the deducted score and per-severity counts.
|
|
67
|
+
"""
|
|
68
|
+
counts: dict[str, int] = dict.fromkeys(_SEVERITY_WEIGHTS, 0)
|
|
69
|
+
for finding in findings:
|
|
70
|
+
severity = str(getattr(finding, "severity", "")).lower()
|
|
71
|
+
if severity in counts:
|
|
72
|
+
counts[severity] += 1
|
|
73
|
+
|
|
74
|
+
penalty = sum(counts[sev] * weight for sev, weight in _SEVERITY_WEIGHTS.items())
|
|
75
|
+
score = max(0, 100 - penalty)
|
|
76
|
+
|
|
77
|
+
return HealthScore(score=score, counts=SeverityCounts(**counts))
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
"""LCOM4 (Lack of Cohesion of Methods, v4) for the audit surface.
|
|
2
|
+
|
|
3
|
+
LCOM4 measures internal class cohesion by counting connected components in the
|
|
4
|
+
undirected graph whose nodes are the methods of the class and whose edges are
|
|
5
|
+
``CALLS`` edges between two methods of the same class.
|
|
6
|
+
|
|
7
|
+
Reading:
|
|
8
|
+
- ``1`` → cohesive class, single internal cluster.
|
|
9
|
+
- ``>1`` → candidate to split (independent responsibilities).
|
|
10
|
+
- ``0`` → class has no methods (no signal to report).
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import networkx as nx
|
|
16
|
+
|
|
17
|
+
from ..graph_store import GraphStore
|
|
18
|
+
from ..models import EdgeKind
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def compute_lcom4(store: GraphStore, class_qualified_name: str) -> int:
|
|
22
|
+
"""Compute LCOM4 for a single class.
|
|
23
|
+
|
|
24
|
+
Args:
|
|
25
|
+
store: ``GraphStore`` holding the indexed project.
|
|
26
|
+
class_qualified_name: Qualified name of the class (e.g.
|
|
27
|
+
``"src/auth/service.py::AuthService"``).
|
|
28
|
+
|
|
29
|
+
Returns:
|
|
30
|
+
Number of connected components among the class methods. ``0`` when the
|
|
31
|
+
class has no methods.
|
|
32
|
+
"""
|
|
33
|
+
methods = {
|
|
34
|
+
e.target_qualified
|
|
35
|
+
for e in store.get_outgoing(class_qualified_name, edge_kind=EdgeKind.HAS_METHOD)
|
|
36
|
+
}
|
|
37
|
+
if not methods:
|
|
38
|
+
return 0
|
|
39
|
+
|
|
40
|
+
graph: nx.Graph = nx.Graph()
|
|
41
|
+
graph.add_nodes_from(methods)
|
|
42
|
+
for method in methods:
|
|
43
|
+
for edge in store.get_outgoing(method, edge_kind=EdgeKind.CALLS):
|
|
44
|
+
if edge.target_qualified in methods:
|
|
45
|
+
graph.add_edge(method, edge.target_qualified)
|
|
46
|
+
|
|
47
|
+
return nx.number_connected_components(graph)
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
"""TestRisk joins: cross-cuts the graph allows but isolated reports don't.
|
|
2
|
+
|
|
3
|
+
Three pure-function joins over already-computed inputs:
|
|
4
|
+
|
|
5
|
+
- ``untested_high_coupling``: uncovered modules × high Ce — most dangerous to
|
|
6
|
+
change blindly (callers everywhere, no tests to catch regressions).
|
|
7
|
+
- ``untested_hotspots``: uncovered modules × high churn — debt most likely
|
|
8
|
+
to materialise into incidents.
|
|
9
|
+
- ``critical_knowledge_concentration``: bus factor 1 × high Ca — a single
|
|
10
|
+
author owns a module many others depend on.
|
|
11
|
+
|
|
12
|
+
The joins operate on dataclasses produced by ``debtector.metrics`` and
|
|
13
|
+
``debtector.git_history`` so unit tests can build inputs directly without
|
|
14
|
+
touching git or the database. The audit command is the orchestrator that
|
|
15
|
+
wires them together end-to-end.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
from collections.abc import Iterable
|
|
21
|
+
from dataclasses import dataclass, field
|
|
22
|
+
|
|
23
|
+
from ..git_history import BusFactorMetrics, ChurnMetrics
|
|
24
|
+
from ..metrics import ModuleMetrics
|
|
25
|
+
|
|
26
|
+
#: Default Ce above which an untested module is flagged "high-coupling".
|
|
27
|
+
DEFAULT_HIGH_CE: float = 10.0
|
|
28
|
+
#: Default commit count above which an untested module is flagged "hotspot".
|
|
29
|
+
DEFAULT_HIGH_CHURN: int = 5
|
|
30
|
+
#: Default Ca above which a bus-factor-1 module is "critical knowledge".
|
|
31
|
+
DEFAULT_HIGH_CA: float = 10.0
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@dataclass(frozen=True)
|
|
35
|
+
class TestRiskFinding:
|
|
36
|
+
"""A module-level risk surfaced by a testRisk join.
|
|
37
|
+
|
|
38
|
+
Args:
|
|
39
|
+
file_path: Module that triggered the finding.
|
|
40
|
+
label: Stable identifier of the join — ``"untested high-coupling"``,
|
|
41
|
+
``"untested hotspots"`` or ``"critical knowledge concentration"``.
|
|
42
|
+
severity: ``"critical"`` for knowledge concentration, ``"high"`` for
|
|
43
|
+
the untested joins. Consumed by the health-score aggregator.
|
|
44
|
+
detail: Metric values that triggered the finding (e.g. ``fan_out``).
|
|
45
|
+
"""
|
|
46
|
+
|
|
47
|
+
file_path: str
|
|
48
|
+
label: str
|
|
49
|
+
severity: str
|
|
50
|
+
detail: dict[str, float] = field(default_factory=dict)
|
|
51
|
+
|
|
52
|
+
# Prevent pytest from collecting this dataclass as a test class.
|
|
53
|
+
__test__ = False
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
@dataclass(frozen=True)
|
|
57
|
+
class CohesionFinding:
|
|
58
|
+
"""A class-level low-cohesion finding.
|
|
59
|
+
|
|
60
|
+
Args:
|
|
61
|
+
qualified_name: Fully qualified name of the class.
|
|
62
|
+
lcom4: LCOM4 value (1 = cohesive, >1 = candidate to split).
|
|
63
|
+
methods_count: Number of methods in the class.
|
|
64
|
+
candidate_to_split: Boolean flag if lcom4 > 1.
|
|
65
|
+
severity: ``"high"`` for low-cohesion classes. Consumed by health-score.
|
|
66
|
+
"""
|
|
67
|
+
|
|
68
|
+
qualified_name: str
|
|
69
|
+
lcom4: float
|
|
70
|
+
methods_count: int
|
|
71
|
+
candidate_to_split: bool
|
|
72
|
+
severity: str = "high"
|
|
73
|
+
|
|
74
|
+
# Prevent pytest from collecting this dataclass as a test class.
|
|
75
|
+
__test__ = False
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def untested_high_coupling(
|
|
79
|
+
untested_files: Iterable[str],
|
|
80
|
+
module_metrics: Iterable[ModuleMetrics],
|
|
81
|
+
ce_threshold: float = DEFAULT_HIGH_CE,
|
|
82
|
+
) -> list[TestRiskFinding]:
|
|
83
|
+
"""Flag uncovered modules whose Ce (fan-out) crosses ``ce_threshold``."""
|
|
84
|
+
untested = set(untested_files)
|
|
85
|
+
findings = [
|
|
86
|
+
TestRiskFinding(
|
|
87
|
+
file_path=m.file_path,
|
|
88
|
+
label="untested high-coupling",
|
|
89
|
+
severity="high",
|
|
90
|
+
detail={"fan_out": m.fan_out},
|
|
91
|
+
)
|
|
92
|
+
for m in module_metrics
|
|
93
|
+
if m.file_path in untested and m.fan_out >= ce_threshold
|
|
94
|
+
]
|
|
95
|
+
findings.sort(key=lambda f: f.detail["fan_out"], reverse=True)
|
|
96
|
+
return findings
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def untested_hotspots(
|
|
100
|
+
untested_files: Iterable[str],
|
|
101
|
+
churn_metrics: Iterable[ChurnMetrics],
|
|
102
|
+
churn_threshold: int = DEFAULT_HIGH_CHURN,
|
|
103
|
+
) -> list[TestRiskFinding]:
|
|
104
|
+
"""Flag uncovered modules whose commit count crosses ``churn_threshold``."""
|
|
105
|
+
untested = set(untested_files)
|
|
106
|
+
findings = [
|
|
107
|
+
TestRiskFinding(
|
|
108
|
+
file_path=c.file_path,
|
|
109
|
+
label="untested hotspots",
|
|
110
|
+
severity="high",
|
|
111
|
+
detail={"commits": float(c.commits)},
|
|
112
|
+
)
|
|
113
|
+
for c in churn_metrics
|
|
114
|
+
if c.file_path in untested and c.commits >= churn_threshold
|
|
115
|
+
]
|
|
116
|
+
findings.sort(key=lambda f: f.detail["commits"], reverse=True)
|
|
117
|
+
return findings
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def critical_knowledge_concentration(
|
|
121
|
+
bus_factor_metrics: Iterable[BusFactorMetrics],
|
|
122
|
+
module_metrics: Iterable[ModuleMetrics],
|
|
123
|
+
ca_threshold: float = DEFAULT_HIGH_CA,
|
|
124
|
+
) -> list[TestRiskFinding]:
|
|
125
|
+
"""Flag bus-factor-1 modules whose Ca crosses ``ca_threshold``."""
|
|
126
|
+
ca_by_file: dict[str, float] = {m.file_path: m.fan_in for m in module_metrics}
|
|
127
|
+
findings = [
|
|
128
|
+
TestRiskFinding(
|
|
129
|
+
file_path=b.file_path,
|
|
130
|
+
label="critical knowledge concentration",
|
|
131
|
+
severity="critical",
|
|
132
|
+
detail={"fan_in": ca_by_file[b.file_path], "bus_factor": float(b.bus_factor)},
|
|
133
|
+
)
|
|
134
|
+
for b in bus_factor_metrics
|
|
135
|
+
if b.bus_factor == 1 and ca_by_file.get(b.file_path, 0.0) >= ca_threshold
|
|
136
|
+
]
|
|
137
|
+
findings.sort(key=lambda f: f.detail["fan_in"], reverse=True)
|
|
138
|
+
return findings
|