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.
Files changed (60) hide show
  1. {debtector-0.4.2/src/debtector.egg-info → debtector-0.5.0}/PKG-INFO +31 -1
  2. {debtector-0.4.2 → debtector-0.5.0}/README.md +30 -0
  3. {debtector-0.4.2 → debtector-0.5.0}/pyproject.toml +2 -2
  4. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/__init__.py +1 -1
  5. debtector-0.5.0/src/debtector/audit/__init__.py +31 -0
  6. debtector-0.5.0/src/debtector/audit/cycle_priority.py +60 -0
  7. debtector-0.5.0/src/debtector/audit/health_score.py +77 -0
  8. debtector-0.5.0/src/debtector/audit/lcom4.py +47 -0
  9. debtector-0.5.0/src/debtector/audit/testrisk.py +138 -0
  10. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/cli.py +242 -13
  11. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/git_history.py +100 -45
  12. {debtector-0.4.2 → debtector-0.5.0/src/debtector.egg-info}/PKG-INFO +31 -1
  13. {debtector-0.4.2 → debtector-0.5.0}/src/debtector.egg-info/SOURCES.txt +7 -0
  14. debtector-0.5.0/tests/test_cli_audit.py +219 -0
  15. {debtector-0.4.2 → debtector-0.5.0}/tests/test_git_history.py +56 -14
  16. debtector-0.5.0/tests/test_git_paths_integration.py +202 -0
  17. {debtector-0.4.2 → debtector-0.5.0}/LICENSE +0 -0
  18. {debtector-0.4.2 → debtector-0.5.0}/setup.cfg +0 -0
  19. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/config.py +0 -0
  20. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/embedder.py +0 -0
  21. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/graph_store.py +0 -0
  22. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/indexer.py +0 -0
  23. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/logging.py +0 -0
  24. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/metrics.py +0 -0
  25. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/models.py +0 -0
  26. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/parser/__init__.py +0 -0
  27. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/parser/base.py +0 -0
  28. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/parser/js_parser.py +0 -0
  29. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/parser/python_parser.py +0 -0
  30. {debtector-0.4.2 → debtector-0.5.0}/src/debtector/utils.py +0 -0
  31. {debtector-0.4.2 → debtector-0.5.0}/src/debtector.egg-info/dependency_links.txt +0 -0
  32. {debtector-0.4.2 → debtector-0.5.0}/src/debtector.egg-info/entry_points.txt +0 -0
  33. {debtector-0.4.2 → debtector-0.5.0}/src/debtector.egg-info/requires.txt +0 -0
  34. {debtector-0.4.2 → debtector-0.5.0}/src/debtector.egg-info/top_level.txt +0 -0
  35. {debtector-0.4.2 → debtector-0.5.0}/tests/test_ci_reporter.py +0 -0
  36. {debtector-0.4.2 → debtector-0.5.0}/tests/test_cli_baseline.py +0 -0
  37. {debtector-0.4.2 → debtector-0.5.0}/tests/test_cli_git.py +0 -0
  38. {debtector-0.4.2 → debtector-0.5.0}/tests/test_cli_human.py +0 -0
  39. {debtector-0.4.2 → debtector-0.5.0}/tests/test_cli_json.py +0 -0
  40. {debtector-0.4.2 → debtector-0.5.0}/tests/test_cli_metrics.py +0 -0
  41. {debtector-0.4.2 → debtector-0.5.0}/tests/test_codeindexignore.py +0 -0
  42. {debtector-0.4.2 → debtector-0.5.0}/tests/test_config.py +0 -0
  43. {debtector-0.4.2 → debtector-0.5.0}/tests/test_covers.py +0 -0
  44. {debtector-0.4.2 → debtector-0.5.0}/tests/test_fts.py +0 -0
  45. {debtector-0.4.2 → debtector-0.5.0}/tests/test_graph_store.py +0 -0
  46. {debtector-0.4.2 → debtector-0.5.0}/tests/test_graph_store_extra.py +0 -0
  47. {debtector-0.4.2 → debtector-0.5.0}/tests/test_indexer.py +0 -0
  48. {debtector-0.4.2 → debtector-0.5.0}/tests/test_indexer_edge_cases.py +0 -0
  49. {debtector-0.4.2 → debtector-0.5.0}/tests/test_logging.py +0 -0
  50. {debtector-0.4.2 → debtector-0.5.0}/tests/test_metrics.py +0 -0
  51. {debtector-0.4.2 → debtector-0.5.0}/tests/test_metrics_cycles.py +0 -0
  52. {debtector-0.4.2 → debtector-0.5.0}/tests/test_metrics_god_modules.py +0 -0
  53. {debtector-0.4.2 → debtector-0.5.0}/tests/test_metrics_inheritance.py +0 -0
  54. {debtector-0.4.2 → debtector-0.5.0}/tests/test_metrics_resolution.py +0 -0
  55. {debtector-0.4.2 → debtector-0.5.0}/tests/test_metrics_uses_type.py +0 -0
  56. {debtector-0.4.2 → debtector-0.5.0}/tests/test_models.py +0 -0
  57. {debtector-0.4.2 → debtector-0.5.0}/tests/test_ratcheting.py +0 -0
  58. {debtector-0.4.2 → debtector-0.5.0}/tests/test_semantic.py +0 -0
  59. {debtector-0.4.2 → debtector-0.5.0}/tests/test_severity.py +0 -0
  60. {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.4.2
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.4.2"
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.4.2"
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
@@ -4,7 +4,7 @@ from debtector.graph_store import GraphStore
4
4
  from debtector.indexer import Indexer
5
5
  from debtector.models import EdgeInfo, EdgeKind, NodeInfo, NodeKind
6
6
 
7
- __version__ = "0.4.2"
7
+ __version__ = "0.5.0"
8
8
 
9
9
  __all__ = [
10
10
  "GraphStore",
@@ -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