Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

refactor(health): one definition of module per question (#1968)

Raghav Chamadiyaff5243f511d5
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index 8fb647d74..ad8bc01a0 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -138,7 +138,7 @@ core/alembic/versions/
```
core/pipeline/
-├── orchestrator.py # _run_health_analysis(): builds module_map, runs analyzer
+├── orchestrator.py # _run_health_analysis(): builds community_label_map, runs analyzer
└── persist.py # persist_pipeline_result(): writes findings/metrics/snapshot
```
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
index 67161b044..7e5c35459 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -1660,7 +1660,7 @@ def run_update(
# re-embedded, so every update silently evicted its pages from semantic
# search — on long-lived repos the LanceDB corpus ended up holding
# decisions and structural pages but zero current file pages.
- assembler = ContextAssembler(config)
+ assembler = ContextAssembler(config, repo_path=repo_path)
generator = PageGenerator(
provider,
assembler,
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
index 3c2d26dfb..ac3133e4d 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
@@ -179,7 +179,7 @@ def _render_pages(
generator = PageGenerator(
TemplateProvider(),
- ContextAssembler(config),
+ ContextAssembler(config, repo_path=repo_path),
config,
vector_store=vector_store,
language=config.language,
diff --git a/packages/cli/src/repowise/cli/commands/workspace_cmd.py b/packages/cli/src/repowise/cli/commands/workspace_cmd.py
index 1f38d29fa..83232e46b 100644
--- a/packages/cli/src/repowise/cli/commands/workspace_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/workspace_cmd.py
@@ -774,7 +774,7 @@ def _generate_docs_for_added_repo(
# Whole-repo selection, so honour the per-repo file-page cap.
max_file_pages=resolve_max_file_pages(config=repo_cfg),
)
- assembler = ContextAssembler(config)
+ assembler = ContextAssembler(config, repo_path=repo_path)
generator = PageGenerator(
provider, assembler, config, language=config.language, repo_path=repo_path
)
diff --git a/packages/core/src/repowise/core/analysis/health/README.md b/packages/core/src/repowise/core/analysis/health/README.md
index 0a881ccdb..dbc6b93e8 100644
--- a/packages/core/src/repowise/core/analysis/health/README.md
+++ b/packages/core/src/repowise/core/analysis/health/README.md
@@ -18,7 +18,7 @@ analyzer = HealthAnalyzer(
git_meta_map=git_meta_map,
parsed_files=parsed_files,
coverage_map=coverage_map, # optional, see coverage/README.md
- module_map=module_map, # optional, file_path → community label
+ community_label_map=..., # optional, file_path → community label
)
report = analyzer.analyze(config=None)
diff --git a/packages/core/src/repowise/core/analysis/health/engine.py b/packages/core/src/repowise/core/analysis/health/engine.py
index 37c653ec7..b3d09f905 100644
--- a/packages/core/src/repowise/core/analysis/health/engine.py
+++ b/packages/core/src/repowise/core/analysis/health/engine.py
@@ -311,7 +311,7 @@ class HealthAnalyzer:
performance_git_meta_map: dict[str, dict] | None = None,
parsed_files: list[Any] | None = None,
coverage_map: dict[str, dict[str, Any]] | None = None,
- module_map: dict[str, str] | None = None,
+ community_label_map: dict[str, str] | None = None,
duplication_cache_dir: Any | None = None,
repo_root: Any | None = None,
) -> None:
@@ -324,12 +324,11 @@ class HealthAnalyzer:
# total_coverable_lines}``. ``None``-equivalent files are simply
# absent from the map.
self.coverage_map = coverage_map or {}
- # Per-file module label keyed by repo-relative POSIX path.
- # Populated from graph community labels by the orchestrator. When
- # missing, the engine falls back to the top-level directory so
- # module rollups still group sensibly on small repos that didn't
- # produce community labels.
- self.module_map = module_map or {}
+ # Per-file community label keyed by repo-relative POSIX path,
+ # populated from graph community detection by the orchestrator and
+ # consumed only by the refactoring detectors. Distinct from the
+ # ``module`` column, which is a path derived from package boundaries.
+ self.community_label_map = community_label_map or {}
# Directory for the duplication token/window cache (typically the
# repo's ``.repowise``). None disables caching — the duplication
# pass then re-tokenizes everything, exactly as before.
@@ -984,6 +983,8 @@ class HealthAnalyzer:
clones = dup_report.pairs_by_file.get(file_path, [])
dup_pct = dup_report.duplication_pct.get(file_path)
+ # The enclosing package root, falling back to the top-level directory
+ # when the repo has no nested packages.
module = _module_for(file_path, package_roots)
file_git_meta = self.git_meta_map.get(file_path, {}) or {}
@@ -1083,7 +1084,7 @@ class HealthAnalyzer:
findings=findings,
dependents_count=dependents_count,
clones=list(clones),
- module_map=self.module_map,
+ community_label_map=self.community_label_map,
graph=self.graph,
file_scc=(file_scc_index or {}).get(file_path),
file_methods=(
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/extract_helper.py b/packages/core/src/repowise/core/analysis/health/refactoring/extract_helper.py
index 4b2c28bb0..8c85e0dbd 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/extract_helper.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/extract_helper.py
@@ -424,7 +424,7 @@ class ExtractHelperDetector(RefactoringDetector):
in** — ``module: "ui"`` for a block shared by ``packages/api-client``,
``packages/types`` and ``packages/ui``. Acting on it files shared code
into a package two thirds of its callers are not in.
- - **The namespace depended on the writer.** ``module_map`` is populated
+ - **The namespace depended on the writer.** ``community_label_map`` is populated
only by the full-index path; the incremental, re-score and
``repowise health`` paths leave it empty, so the same clone got
``"ui"`` or ``None`` depending on which pass last wrote the row. That
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/models.py b/packages/core/src/repowise/core/analysis/health/refactoring/models.py
index 6be0df786..d3dc57602 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/models.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/models.py
@@ -146,7 +146,7 @@ class RefactoringContext:
# Populated only by the full-index path; the incremental, re-score and
# ``repowise health`` paths leave it empty. Split File degrades to the
# callee's file path, so the signal weakens rather than changing namespace.
- module_map: dict[str, str] = field(default_factory=dict)
+ community_label_map: dict[str, str] = field(default_factory=dict)
# The repo's symbol/file graph (a ``networkx.DiGraph``, typed ``Any`` to
# avoid importing networkx into the model layer). A shared read-only
# reference — the graph-native detectors (Move Method, Break Cycle) read
diff --git a/packages/core/src/repowise/core/analysis/health/refactoring/split_file.py b/packages/core/src/repowise/core/analysis/health/refactoring/split_file.py
index 6f55497cc..1a982c4af 100644
--- a/packages/core/src/repowise/core/analysis/health/refactoring/split_file.py
+++ b/packages/core/src/repowise/core/analysis/health/refactoring/split_file.py
@@ -472,7 +472,7 @@ class SplitFileDetector(RefactoringDetector):
cdata = graph.nodes.get(callee, {})
fpath = cdata.get("file_path")
if fpath and fpath != ctx.file_path:
- label = ctx.module_map.get(fpath) or fpath
+ label = ctx.community_label_map.get(fpath) or fpath
foreign_of[owner].add(label)
# The imported names this file pulls from the callee's
# file approximate the dependency surface this symbol
diff --git a/packages/core/src/repowise/core/generation/context/assembler.py b/packages/core/src/repowise/core/generation/context/assembler.py
index 44c8dc57c..1a9a5b923 100644
--- a/packages/core/src/repowise/core/generation/context/assembler.py
+++ b/packages/core/src/repowise/core/generation/context/assembler.py
@@ -17,6 +17,11 @@ from repowise.core.analysis.dead_code.file_reachability import (
)
from repowise.core.ids import file_path_of, is_external
from repowise.core.ingestion.models import ParsedFile, RepoStructure, Symbol
+from repowise.core.ingestion.package_roots import (
+ module_for,
+ package_roots_from_paths,
+ scan_package_roots,
+)
from ...co_change import parse_partners
from ..categories import file_category
@@ -245,8 +250,11 @@ class ContextAssembler:
``config.token_budget`` tokens.
"""
- def __init__(self, config: GenerationConfig) -> None:
+ def __init__(self, config: GenerationConfig, repo_path: Any | None = None) -> None:
self._config = config
+ # Checkout root, used only to read package boundaries off disk.
+ self._repo_path = repo_path
+ self._package_roots: set[str] | None = None
# ------------------------------------------------------------------
# Token utilities
@@ -618,8 +626,30 @@ class ContextAssembler:
most_fixed_file=most_fixed_file,
)
- @staticmethod
+ def _package_boundaries(self, known_paths: set[str]) -> set[str]:
+ """Package roots for this repo, resolved once.
+
+ Scans the checkout, exactly as the health writer does, so both producers
+ of ``module`` agree. The path-list fallback is for a caller with no
+ checkout, and it only sees manifests already in *known_paths* -- on an
+ incremental run that is the changed files alone, which is why the scan
+ is preferred rather than optional.
+ """
+ if self._package_roots is not None:
+ return self._package_roots
+ roots: set[str] | None = None
+ if self._repo_path is not None:
+ try:
+ roots = scan_package_roots(self._repo_path)
+ except OSError as exc:
+ log.debug("generation_package_root_scan_failed", error=str(exc))
+ if roots is None:
+ roots = package_roots_from_paths(known_paths)
+ self._package_roots = roots
+ return roots
+
def _module_git_enrichment(
+ self,
files: list[str],
member_set: set[str],
git_meta_map: dict[str, dict] | None,
@@ -640,6 +670,8 @@ class ContextAssembler:
if not metas:
return 0, 0, 0, [], 0, {}
+ roots = self._package_boundaries(set(git_meta_map))
+
hotspot_count = sum(1 for m in metas if m.get("is_hotspot"))
stable_count = sum(1 for m in metas if m.get("is_stable"))
# bus_factor is the number of authors covering the bulk of a file's
@@ -654,8 +686,9 @@ class ContextAssembler:
for p in parse_partners(m.get("co_change_partners_json")):
if p.file_path in member_set:
continue
- module = p.file_path.rsplit("/", 1)[0] if "/" in p.file_path else p.file_path
- coupled[module] += 1
+ module = module_for(p.file_path, roots)
+ if module:
+ coupled[module] += 1
coupled_modules = [{"path": path, "count": count} for path, count in coupled.most_common(5)]
bugfix_total = sum(int(m.get("prior_defect_count") or 0) for m in metas)
diff --git a/packages/core/src/repowise/core/pipeline/phases/analysis.py b/packages/core/src/repowise/core/pipeline/phases/analysis.py
index e883693a3..fb2e548a9 100644
--- a/packages/core/src/repowise/core/pipeline/phases/analysis.py
+++ b/packages/core/src/repowise/core/pipeline/phases/analysis.py
@@ -193,11 +193,11 @@ async def _run_health_analysis(
# the entire pre-walk — most of the phase's wall-clock.
progress.on_phase_start("health", 2 * len(parsed_files))
- # Build a {file_path → community label} map so per-file metrics
- # carry a real module name, not None. Community detection is
- # already computed for the graph view, so this is essentially
- # free.
- module_map: dict[str, str] = {}
+ # Build a {file_path → community label} map for the refactoring
+ # detectors. Community detection is already computed for the graph
+ # view, so this is essentially free. It is not the ``module`` column:
+ # that is a path, written from the package boundaries.
+ community_label_map: dict[str, str] = {}
try:
cd = graph_builder.community_detection()
ci = graph_builder.community_info()
@@ -205,9 +205,9 @@ async def _run_health_analysis(
info = ci.get(comm_id)
label = getattr(info, "label", None) if info else None
if label:
- module_map[node_id] = label
+ community_label_map[node_id] = label
except Exception as exc:
- logger.debug("health_module_map_failed", error=str(exc))
+ logger.debug("health_community_label_map_failed", error=str(exc))
# Ingest coverage (auto-discovered or explicitly passed) so biomarkers
# see real line/branch coverage instead of the has_test_file fallback.
@@ -223,7 +223,7 @@ async def _run_health_analysis(
graph_builder.graph(),
git_meta_map=git_meta_map,
parsed_files=parsed_files,
- module_map=module_map,
+ community_label_map=community_label_map,
coverage_map=coverage_map,
duplication_cache_dir=(repo_path / ".repowise") if repo_path is not None else None,
repo_root=repo_path,
diff --git a/packages/core/src/repowise/core/pipeline/phases/generation.py b/packages/core/src/repowise/core/pipeline/phases/generation.py
index 595219cdb..7e31e6477 100644
--- a/packages/core/src/repowise/core/pipeline/phases/generation.py
+++ b/packages/core/src/repowise/core/pipeline/phases/generation.py
@@ -93,7 +93,7 @@ async def run_generation(
# Falls back to defaults when the pipeline entry point did not thread one through.
base_config = generation_config if generation_config is not None else GenerationConfig()
config = replace(base_config, max_concurrency=concurrency)
- assembler = ContextAssembler(config)
+ assembler = ContextAssembler(config, repo_path=repo_path)
# Test-run: limit to top 10 files by PageRank for a fast validation run.
# Applied here rather than only in the orchestrator so it works whether the
diff --git a/packages/server/src/repowise/server/job_executor.py b/packages/server/src/repowise/server/job_executor.py
index 0cee4a74c..06b866eff 100644
--- a/packages/server/src/repowise/server/job_executor.py
+++ b/packages/server/src/repowise/server/job_executor.py
@@ -1255,7 +1255,7 @@ async def _incremental_page_regen(
# level 2 and leave the repo-wide pages for a full run.
file_pages_only=True,
)
- assembler = ContextAssembler(generation_config)
+ assembler = ContextAssembler(generation_config, repo_path=repo_path)
# D3: pass the vector store (re-embed re-rendered pages) and prior pages
# (reuse an unchanged page instead of re-billing it), matching the CLI
# incremental path. Without these, every sync re-billed the repo-wide
diff --git a/packages/server/src/repowise/server/routers/code_health/aggregation.py b/packages/server/src/repowise/server/routers/code_health/aggregation.py
index 75c493750..813097d38 100644
--- a/packages/server/src/repowise/server/routers/code_health/aggregation.py
+++ b/packages/server/src/repowise/server/routers/code_health/aggregation.py
@@ -2,25 +2,15 @@
from __future__ import annotations
-import re
from typing import Any
-# Strip the trailing " (N)" suffix that community detection appends to
-# disambiguate same-named modules. The leak is harmless in the DB but
-# noisy in the dashboard.
-_MODULE_SUFFIX = re.compile(r"\s*\(\d+\)\s*$")
-
-
-def _clean_module(name: str) -> str:
- return _MODULE_SUFFIX.sub("", name).strip()
-
def _module_rollups(metrics: list[Any]) -> list[dict]:
"""NLOC-weighted module rollups derived from ``HealthFileMetric.module``."""
buckets: dict[str, list[Any]] = {}
for m in metrics:
if m.module:
- buckets.setdefault(_clean_module(m.module), []).append(m)
+ buckets.setdefault(m.module, []).append(m)
rows: list[dict] = []
for name, group in buckets.items():
total_nloc = sum(max(r.nloc, 1) for r in group)
diff --git a/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py b/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py
index 36e41863f..f952867b4 100644
--- a/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py
+++ b/packages/server/src/repowise/server/routers/code_health/refactoring_routes.py
@@ -16,7 +16,6 @@ from repowise.core.persistence import crud
from repowise.server.deps import get_db_session
from ._router import router
-from .aggregation import _clean_module
_SEVERITY_ORDER = {"low": 0, "medium": 1, "high": 2, "critical": 3}
@@ -113,7 +112,7 @@ async def health_work_queue(
"file_path": file_path,
"score": round(score, 2),
"nloc": nloc,
- "module": _clean_module(m.module) if (m and m.module) else None,
+ "module": m.module if (m and m.module) else None,
"primary_biomarker": primary.biomarker_type,
"primary_severity": primary.severity,
"primary_reason": primary.reason,
diff --git a/packages/server/src/repowise/server/routers/git.py b/packages/server/src/repowise/server/routers/git.py
index 301f1670e..babd6069f 100644
--- a/packages/server/src/repowise/server/routers/git.py
+++ b/packages/server/src/repowise/server/routers/git.py
@@ -64,6 +64,7 @@ from repowise.server.schemas import (
RiskHistogramBucket,
RiskRangeResponse,
)
+from repowise.server.services.module_health import top_level_module
from repowise.server.services.reviewer_suggestions import suggest_reviewers
# Below this many sampled commits a percentile isn't worth showing; mirrors
@@ -560,9 +561,7 @@ async def get_ownership(
else:
modules: dict[str, list] = {}
for m in all_meta:
- parts = m.file_path.split("/")
- module = parts[0] if len(parts) > 1 else "root"
- modules.setdefault(module, []).append(m)
+ modules.setdefault(top_level_module(m.file_path), []).append(m)
entries = []
for module_path, files in sorted(modules.items()):
diff --git a/packages/server/src/repowise/server/routers/modules.py b/packages/server/src/repowise/server/routers/modules.py
index 4d52be4ba..949ae1e08 100644
--- a/packages/server/src/repowise/server/routers/modules.py
+++ b/packages/server/src/repowise/server/routers/modules.py
@@ -113,7 +113,7 @@ async def get_module_health(
module_path: str,
session: AsyncSession = Depends(get_db_session),
) -> ModuleHealthDetail:
- from repowise.server.services.module_health import module_of
+ from repowise.server.services.module_health import top_level_module
accs = await aggregate_modules(session, repo_id)
decoded = unquote(module_path)
@@ -149,7 +149,7 @@ async def get_module_health(
)
# 3. Parent module fallback
- acc = accs.get(module_of(decoded))
+ acc = accs.get(top_level_module(decoded))
if acc is not None:
base = summarize(acc)
extras = detail_extras(acc)
diff --git a/packages/server/src/repowise/server/routers/overview.py b/packages/server/src/repowise/server/routers/overview.py
index 9cdbcd2ed..0ff6a8a78 100644
--- a/packages/server/src/repowise/server/routers/overview.py
+++ b/packages/server/src/repowise/server/routers/overview.py
@@ -32,6 +32,7 @@ from repowise.core.persistence.models import (
from repowise.server.deps import get_db_session, verify_api_key
from repowise.server.routers.git import _hotspot_from_row
from repowise.server.services.knowledge_map import compute_knowledge_map
+from repowise.server.services.module_health import top_level_module
router = APIRouter(
prefix="/api/repos",
@@ -345,8 +346,7 @@ async def overview_summary(
module_owner_files: dict[str, dict[str, int]] = {}
module_file_totals: dict[str, int] = {}
for fp, owner in owner_rows:
- parts = fp.split("/")
- module = parts[0] if len(parts) > 1 else "root"
+ module = top_level_module(fp)
module_file_totals[module] = module_file_totals.get(module, 0) + 1
if owner:
bucket = module_owner_files.setdefault(module, {})
diff --git a/packages/server/src/repowise/server/routers/stats.py b/packages/server/src/repowise/server/routers/stats.py
index 349c2d50f..abae58e5f 100644
--- a/packages/server/src/repowise/server/routers/stats.py
+++ b/packages/server/src/repowise/server/routers/stats.py
@@ -41,6 +41,7 @@ from repowise.core.persistence.models import (
)
from repowise.core.test_paths import is_test_related_path
from repowise.server.deps import get_db_session, verify_api_key
+from repowise.server.services.module_health import top_level_module
router = APIRouter(
prefix="/api/repos",
@@ -582,8 +583,7 @@ def _people(all_meta: list[Any]) -> dict[str, Any]:
owners[m.primary_owner_name] = owners.get(m.primary_owner_name, 0) + 1
if (m.bus_factor or 0) == 1:
single_owner_files += 1
- parts = m.file_path.split("/")
- module = parts[0] if len(parts) > 1 else "root"
+ module = top_level_module(m.file_path)
module_file_totals[module] = module_file_totals.get(module, 0) + 1
if m.primary_owner_name:
bucket = module_owner_files.setdefault(module, {})
diff --git a/packages/server/src/repowise/server/services/module_health.py b/packages/server/src/repowise/server/services/module_health.py
index 8e194a886..cd5c5cdc6 100644
--- a/packages/server/src/repowise/server/services/module_health.py
+++ b/packages/server/src/repowise/server/services/module_health.py
@@ -3,10 +3,12 @@
Per-module rollup combining ownership, churn, dead code, docs, and
decisions. No core ingestion changes — purely composes existing tables.
-A "module" is the top-level directory of a file path (matches the existing
-``OwnershipEntry`` convention). For nested module views we expose
-``module_path`` as the path prefix the caller passed in, which can be
-arbitrarily deep.
+A "module" here is the top-level directory of a file path, matching the
+``OwnershipEntry`` convention the ownership surfaces already use. It is
+deliberately not ``HealthFileMetric.module``, which names the enclosing package
+boundary: this value is a rollup bucket key and travels in the URL, so the two
+answer different questions. For nested module views we expose ``module_path``
+as the path prefix the caller passed in, which can be arbitrarily deep.
"""
from __future__ import annotations
@@ -31,7 +33,12 @@ from repowise.core.persistence.models import (
)
-def module_of(file_path: str) -> str:
+def top_level_module(file_path: str) -> str:
+ """The top-level directory of *file_path*, or ``"root"`` for a root file.
+
+ The one definition behind every ownership rollup. Not a package boundary --
+ see the module docstring.
+ """
parts = file_path.split("/", 1)
return parts[0] if len(parts) > 1 else "root"
@@ -150,7 +157,7 @@ async def aggregate_modules(
)
for m in files:
- mod = module_of(m.file_path)
+ mod = top_level_module(m.file_path)
acc = accs[mod]
if not acc.module_path:
acc.module_path = mod
@@ -180,7 +187,7 @@ async def aggregate_modules(
)
).all()
for path, doc in sym_rows:
- mod = module_of(path)
+ mod = top_level_module(path)
acc = accs.get(mod)
if acc is None:
continue
@@ -197,7 +204,7 @@ async def aggregate_modules(
)
).all()
for path, lines in dead_rows:
- mod = module_of(path)
+ mod = top_level_module(path)
acc = accs.get(mod)
if acc is None:
continue
diff --git a/packages/server/src/repowise/server/services/owner_profile.py b/packages/server/src/repowise/server/services/owner_profile.py
index ffe10c01b..836898e62 100644
--- a/packages/server/src/repowise/server/services/owner_profile.py
+++ b/packages/server/src/repowise/server/services/owner_profile.py
@@ -31,6 +31,7 @@ from repowise.core.ingestion.git_indexer import (
canonicalize_author_email,
)
from repowise.core.persistence.models import DeadCodeFinding, GitMetadata
+from repowise.server.services.module_health import top_level_module
# ---------------------------------------------------------------------------
# Identity
@@ -53,11 +54,6 @@ def owner_key(name: str | None, email: str | None) -> str:
return ""
-def _module_of(file_path: str) -> str:
- parts = file_path.split("/", 1)
- return parts[0] if len(parts) > 1 else "root"
-
-
def _as_utc(dt: datetime | None) -> datetime | None:
"""Coerce a DB datetime to aware-UTC.
@@ -178,7 +174,7 @@ async def aggregate_owners(
except json.JSONDecodeError:
authors = []
- module = _module_of(m.file_path)
+ module = top_level_module(m.file_path)
module_totals[module] += 1
categories: dict[str, int] = {}
with contextlib.suppress(json.JSONDecodeError):
diff --git a/tests/unit/generation/test_context_assembler.py b/tests/unit/generation/test_context_assembler.py
index 670769271..2c2e785f6 100644
--- a/tests/unit/generation/test_context_assembler.py
+++ b/tests/unit/generation/test_context_assembler.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import dataclasses
+import json
import networkx as nx
@@ -531,3 +532,56 @@ def test_foreign_edge_keeps_real_neighbours():
assert is_foreign_edge("pkg/other.py::Thing", path)
# A path that merely shares a prefix is a different file.
assert is_foreign_edge("pkg/mod_extra.py", path)
+
+
+def test_coupled_modules_name_the_package_not_the_parent_directory(sample_config):
+ """A coupled module must be somewhere a reader can navigate to.
+
+ The parent directory of a coupled file is a location, but on a monorepo it
+ is an arbitrarily deep one that names no subsystem. The package boundary is
+ the unit the rest of the wiki groups by.
+ """
+ assembler = ContextAssembler(sample_config)
+ git_meta_map = {
+ "packages/core/pyproject.toml": {},
+ "packages/ui/package.json": {},
+ "packages/core/src/a.py": {
+ "co_change_partners_json": json.dumps(
+ [{"file_path": "packages/ui/src/deep/nested/widget.ts", "co_change_count": 5}]
+ )
+ },
+ }
+
+ _, _, _, coupled_modules, _, _ = assembler._module_git_enrichment(
+ ["packages/core/src/a.py"], {"packages/core/src/a.py"}, git_meta_map
+ )
+
+ assert coupled_modules == [{"path": "packages/ui", "count": 1}]
+
+
+def test_coupled_modules_survive_a_changed_files_only_git_map(sample_config, tmp_path):
+ """An incremental run passes only the changed files' git metadata.
+
+ Deriving package roots from that map alone finds no manifest, and every
+ coupled partner then falls back to the same top-level bucket. The roots
+ come off the checkout so the answer does not depend on what changed.
+ """
+ (tmp_path / "packages" / "core").mkdir(parents=True)
+ (tmp_path / "packages" / "ui").mkdir(parents=True)
+ (tmp_path / "packages" / "core" / "pyproject.toml").write_text("[project]\n")
+ (tmp_path / "packages" / "ui" / "package.json").write_text("{}\n")
+
+ assembler = ContextAssembler(sample_config, repo_path=tmp_path)
+ changed_only = {
+ "packages/core/src/a.py": {
+ "co_change_partners_json": json.dumps(
+ [{"file_path": "packages/ui/src/deep/widget.ts", "co_change_count": 5}]
+ )
+ }
+ }
+
+ _, _, _, coupled_modules, _, _ = assembler._module_git_enrichment(
+ ["packages/core/src/a.py"], {"packages/core/src/a.py"}, changed_only
+ )
+
+ assert coupled_modules == [{"path": "packages/ui", "count": 1}]
diff --git a/tests/unit/health/test_module_attribution.py b/tests/unit/health/test_module_attribution.py
index 1971933cc..dfc258ccb 100644
--- a/tests/unit/health/test_module_attribution.py
+++ b/tests/unit/health/test_module_attribution.py
@@ -106,7 +106,7 @@ def test_windows_separators_resolve_to_the_same_module():
assert _module_for("packages\\core\\src\\thing.py", roots) == "packages/core"
-def _analyze(tmp_path, *, module_map):
+def _analyze(tmp_path, *, community_label_map):
"""Run the real analyzer over a two-package tree and return {path: module}."""
from repowise.core.analysis.health import HealthAnalyzer
from repowise.core.ingestion.parser import parse_file
@@ -127,7 +127,9 @@ def _analyze(tmp_path, *, module_map):
parse_file(f, (tmp_path / f.path).read_bytes())
for f in FileTraverser(tmp_path).traverse()
]
- report = HealthAnalyzer(None, parsed_files=parsed, module_map=module_map).analyze()
+ report = HealthAnalyzer(
+ None, parsed_files=parsed, community_label_map=community_label_map
+ ).analyze()
return {m.file_path: m.module for m in report.metrics}
@@ -137,7 +139,7 @@ def test_the_engine_wires_real_package_roots_through_to_the_metric(tmp_path):
The helpers can be right while the call site still reads the old value, so
this asserts on what the analyzer actually writes.
"""
- modules = _analyze(tmp_path, module_map=None)
+ modules = _analyze(tmp_path, community_label_map=None)
assert modules["packages/core/thing.py"] == "packages/core"
assert modules["packages/ui/widget.py"] == "packages/ui"
@@ -247,7 +249,7 @@ def test_every_analyzer_call_site_supplies_a_repo_root():
def test_a_community_map_can_no_longer_change_the_answer(tmp_path):
"""The regression that motivated this, as an executable invariant.
- Only the full-index path ever passed a ``module_map``; the incremental,
+ Only the full-index path ever passed a ``community_label_map``; the incremental,
re-score and ``repowise health`` paths did not, so a row's namespace
depended on which one last wrote it. Supplying a hostile map must now be
inert — this is what makes the four paths agree.
@@ -256,4 +258,25 @@ def test_a_community_map_can_no_longer_change_the_answer(tmp_path):
"packages/core/thing.py": "tests/unit",
"packages/ui/widget.py": "repowise/distill (7)",
}
- assert _analyze(tmp_path, module_map=poisoned) == _analyze(tmp_path, module_map=None)
+ assert _analyze(tmp_path, community_label_map=poisoned) == _analyze(
+ tmp_path, community_label_map=None
+ )
+
+
+def test_module_is_always_a_path_never_a_community_label():
+ """Why the dashboard no longer strips a `` (N)`` suffix off ``module``.
+
+ Community detection appends that suffix when two clusters collide on a
+ label, and the rollups used to sanitize it because ``module`` once carried
+ those labels. ``_module_for`` returns a path segment or ``None``, so the
+ suffix cannot reach the column and the sanitizer had nothing left to strip.
+ """
+ roots = {"packages/core", "packages/ui"}
+ for path in (
+ "packages/core/src/thing.py",
+ "packages/ui/src/thing.ts",
+ "docs/guide.md",
+ "README.md",
+ ):
+ module = _module_for(path, roots)
+ assert module is None or path.startswith(module + "/")
diff --git a/tests/unit/health/test_refactoring_extract_helper.py b/tests/unit/health/test_refactoring_extract_helper.py
index c3a73ca95..4112e5e7c 100644
--- a/tests/unit/health/test_refactoring_extract_helper.py
+++ b/tests/unit/health/test_refactoring_extract_helper.py
@@ -65,7 +65,7 @@ def _ctx(
clones: list[ClonePair],
*,
findings: list | None = None,
- module_map: dict[str, str] | None = None,
+ community_label_map: dict[str, str] | None = None,
source_lines: list[str] | None = None,
) -> RefactoringContext:
return RefactoringContext(
@@ -76,7 +76,7 @@ def _ctx(
findings=findings or [],
dependents_count=0,
clones=clones,
- module_map=module_map or {},
+ community_label_map=community_label_map or {},
source_lines=source_lines,
)
@@ -336,8 +336,8 @@ def test_confidence_medium_when_dormant():
# ---- suggested site ------------------------------------------------------
-def _site_for(module_map: dict[str, str] | None) -> dict:
- """The suggested site for one fixed cross-package clone, under *module_map*.
+def _site_for(community_label_map: dict[str, str] | None) -> dict:
+ """The suggested site for one fixed cross-package clone, under *community_label_map*.
The occurrences deliberately live in different top-level packages, so the
only honest shared directory is the shallow ``pkg`` -- the case where a
@@ -346,7 +346,9 @@ def _site_for(module_map: dict[str, str] | None) -> dict:
pair = _pair("pkg/api/a.py", "pkg/core/b.py", 10, 25, 40, 55)
s = next(
s
- for s in detect_refactorings(_ctx("pkg/api/a.py", [pair], module_map=module_map))
+ for s in detect_refactorings(
+ _ctx("pkg/api/a.py", [pair], community_label_map=community_label_map)
+ )
if s.refactoring_type == "extract_helper"
)
return s.plan
@@ -362,7 +364,7 @@ def test_suggested_site_ignores_a_hostile_community_label():
"""The load-bearing property: the plan no longer depends on which write
path produced it.
- ``module_map`` is populated by the full-index path alone -- the incremental,
+ ``community_label_map`` is populated by the full-index path alone -- the incremental,
re-score and ``repowise health`` paths leave it empty -- so a label-derived
site made the payload's namespace a function of the last writer. Here the
label ``ui`` is on *neither* occurrence's path, which is the shape measured
diff --git a/tests/unit/health/test_refactoring_split_file.py b/tests/unit/health/test_refactoring_split_file.py
index 214f71ffd..73fe0e4b8 100644
--- a/tests/unit/health/test_refactoring_split_file.py
+++ b/tests/unit/health/test_refactoring_split_file.py
@@ -71,7 +71,7 @@ def _ctx(
nloc: int = 600,
language: str = "python",
blame_index: BlameIndex | None = None,
- module_map: dict[str, str] | None = None,
+ community_label_map: dict[str, str] | None = None,
) -> RefactoringContext:
return RefactoringContext(
file_path=file_path,
@@ -79,7 +79,7 @@ def _ctx(
nloc=nloc,
graph=g,
blame_index=blame_index,
- module_map=module_map or {},
+ community_label_map=community_label_map or {},
)
@@ -371,8 +371,8 @@ def test_import_name_signal_separates_distinct_dependencies():
_add_foreign_call(g, f"big.py::fn_{i}", "ext/b.py", "beta_dep")
_imports(g, "big.py", "ext/a.py", ["alpha_dep"])
_imports(g, "big.py", "ext/b.py", ["beta_dep"])
- module_map = {"ext/a.py": "extpkg", "ext/b.py": "extpkg"}
- out = _detect(g, "big.py", module_map=module_map)
+ community_label_map = {"ext/a.py": "extpkg", "ext/b.py": "extpkg"}
+ out = _detect(g, "big.py", community_label_map=community_label_map)
assert len(out) == 1
s = out[0]
assert s.evidence["group_count"] == 2
@@ -391,8 +391,8 @@ def test_foreign_module_proxy_is_used_when_imported_names_empty():
_add_foreign_call(g, f"big.py::fn_{i}", "ext/a.py", "alpha_dep")
for i in range(4, 8):
_add_foreign_call(g, f"big.py::fn_{i}", "ext/b.py", "beta_dep")
- module_map = {"ext/a.py": "moda", "ext/b.py": "modb"}
- out = _detect(g, "big.py", module_map=module_map)
+ community_label_map = {"ext/a.py": "moda", "ext/b.py": "modb"}
+ out = _detect(g, "big.py", community_label_map=community_label_map)
assert len(out) == 1
s = out[0]
assert s.evidence["group_count"] == 2
diff --git a/tests/unit/health/test_snapshot_writers_agree.py b/tests/unit/health/test_snapshot_writers_agree.py
index d6176c93f..ec179a513 100644
--- a/tests/unit/health/test_snapshot_writers_agree.py
+++ b/tests/unit/health/test_snapshot_writers_agree.py
@@ -5,7 +5,7 @@ persister, the upgrade flow, the full-index pipeline, and the store wrapper
that forwards to crud. A repo's history is whichever of those wrote it last.
This has already gone wrong once here, with a different argument: four
-``HealthAnalyzer`` call sites of which only one passed ``module_map``, so a
+``HealthAnalyzer`` call sites of which only one passed ``community_label_map``, so a
repo's module namespace flipped depending on which command last ran. The same
shape applied to ``per_file_deductions`` would make a floored file's trend
depth appear and disappear as the user alternated between ``repowise health``,