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.

feat(communities): count production files, read conductance, name the ungrouped (#2112)

Raghav Chamadiya1748b7944a44
diff --git a/packages/api-client/src/graph.ts b/packages/api-client/src/graph.ts
index 22d0a13b4..a96366840 100644
--- a/packages/api-client/src/graph.ts
+++ b/packages/api-client/src/graph.ts
@@ -15,6 +15,7 @@ import type {
HotFilesGraphResponse,
ModuleGraphResponse,
NodeSearchResult,
+ PopulationParams,
} from "./types";
export async function getGraph(
@@ -68,9 +69,11 @@ export async function getArchitectureGraph(repoId: string): Promise<GraphExportR
export async function getArchitectureCommunityGraph(
repoId: string,
minMembers = 2,
+ population?: PopulationParams,
): Promise<ArchitectureGraphResponse> {
return apiGet<ArchitectureGraphResponse>(`/api/graph/${repoId}/architecture`, {
min_members: minMembers,
+ ...population,
});
}
@@ -82,8 +85,9 @@ export async function getArchitectureCommunityGraph(
export async function getArchitecture(
repoId: string,
minMembers = 2,
+ population?: PopulationParams,
): Promise<ArchitectureGraphResponse> {
- return getArchitectureCommunityGraph(repoId, minMembers);
+ return getArchitectureCommunityGraph(repoId, minMembers, population);
}
export async function getDeadCodeGraph(repoId: string): Promise<DeadCodeGraphResponse> {
@@ -102,14 +106,17 @@ export async function getHotFilesGraph(
// Graph Intelligence
// ---------------------------------------------------------------------------
-export async function getCommunities(repoId: string): Promise<CommunitySummaryItem[]> {
- return apiGet<CommunitySummaryItem[]>(`/api/graph/${repoId}/communities`);
+export async function getCommunities(
+ repoId: string,
+ population?: PopulationParams,
+): Promise<CommunitySummaryItem[]> {
+ return apiGet<CommunitySummaryItem[]>(`/api/graph/${repoId}/communities`, population);
}
export async function getCommunityDetail(
repoId: string,
communityId: number,
- params?: { include_members?: boolean; member_limit?: number },
+ params?: { include_members?: boolean; member_limit?: number } & PopulationParams,
): Promise<CommunityDetailResponse> {
return apiGet<CommunityDetailResponse>(
`/api/graph/${repoId}/communities/${communityId}`,
@@ -125,9 +132,11 @@ export async function getCommunityDetail(
export async function getCommunitySlice(
repoId: string,
communityId: number,
+ population?: PopulationParams,
): Promise<CommunitySliceResponse> {
return apiGet<CommunitySliceResponse>(
`/api/graph/${repoId}/communities/${communityId}/slice`,
+ population,
);
}
diff --git a/packages/api-client/src/types/graph.ts b/packages/api-client/src/types/graph.ts
index ef20c9f67..5d17e5606 100644
--- a/packages/api-client/src/types/graph.ts
+++ b/packages/api-client/src/types/graph.ts
@@ -63,6 +63,7 @@ export interface CommunitySliceResponse
community_id: number;
member_count: number;
truncated?: boolean;
+ hidden_member_count?: number;
}
// Architecture super-node graph (Phase A)
@@ -70,7 +71,9 @@ export interface ArchitectureNodeResponse {
community_id: number;
label: string;
cohesion: number;
+ conductance?: number | null;
member_count: number;
+ hidden_member_count?: number;
top_file: string;
avg_pagerank: number;
hotspot_count: number;
@@ -86,11 +89,36 @@ export interface ArchitectureEdgeResponse {
edge_count: number;
}
+export interface PopulationBreakdownResponse {
+ total: number;
+ visible: number;
+ tests?: number;
+ examples?: number;
+ docs?: number;
+ include_tests?: boolean;
+ include_examples?: boolean;
+ include_docs?: boolean;
+}
+
+export interface UnclusteredFilesResponse {
+ file_count: number;
+ files?: string[];
+}
+
export interface ArchitectureGraphResponse {
nodes: ArchitectureNodeResponse[];
edges: ArchitectureEdgeResponse[];
+ population?: PopulationBreakdownResponse | null;
+ unclustered?: UnclusteredFilesResponse | null;
}
+/** Query flags shared by every community endpoint. Omitted = production only. */
+export type PopulationParams = {
+ include_tests?: boolean;
+ include_examples?: boolean;
+ include_docs?: boolean;
+};
+
export interface GraphPathResponse {
path: string[];
distance: number;
diff --git a/packages/api-client/src/types/intelligence.ts b/packages/api-client/src/types/intelligence.ts
index d7771a83a..ee300515b 100644
--- a/packages/api-client/src/types/intelligence.ts
+++ b/packages/api-client/src/types/intelligence.ts
@@ -63,7 +63,9 @@ export interface CommunityDetailResponse {
community_id: number;
label: string;
cohesion: number;
+ conductance?: number | null;
member_count: number;
+ hidden_member_count?: number;
members: CommunityMember[];
truncated: boolean;
neighboring_communities: NeighboringCommunity[];
@@ -91,7 +93,9 @@ export interface CommunitySummaryItem {
community_id: number;
label: string;
cohesion: number;
+ conductance?: number | null;
member_count: number;
+ hidden_member_count?: number;
top_file: string;
}
diff --git a/packages/core/src/repowise/core/analysis/communities.py b/packages/core/src/repowise/core/analysis/communities.py
index 06a92e512..1875684d9 100644
--- a/packages/core/src/repowise/core/analysis/communities.py
+++ b/packages/core/src/repowise/core/analysis/communities.py
@@ -73,6 +73,9 @@ class CommunityInfo:
size: int
cohesion: float
dominant_language: str
+ #: ``cut / (2 * intra + cut)`` over the production members, lower is
+ #: tighter. ``None`` when nothing is linked. Does not decay with size.
+ conductance: float | None = None
# ---------------------------------------------------------------------------
@@ -210,6 +213,29 @@ def _cohesion_score(graph: nx.Graph, community_nodes: list[str]) -> float:
return round(actual / possible, 4) if possible > 0 else 0.0
+def _conductance(graph: nx.Graph, community_nodes: list[str]) -> float | None:
+ """Share of the community's edge volume that crosses its boundary.
+
+ ``cohesion`` divides by ``n(n-1)/2`` and so measures size on anything
+ above a few dozen files; this compares edges leaving against edges staying.
+ """
+ members = set(community_nodes)
+ intra = 0
+ cut = 0
+ for node in members:
+ if node not in graph:
+ continue
+ for neighbor in graph.neighbors(node):
+ if neighbor in members:
+ intra += 1 # counted from both ends: 2 * intra
+ else:
+ cut += 1
+ volume = intra + cut # intra is already doubled
+ if volume == 0:
+ return None
+ return round(cut / volume, 4)
+
+
# ---------------------------------------------------------------------------
# Heuristic labeling
# ---------------------------------------------------------------------------
@@ -281,6 +307,24 @@ def _best_sub_label(
return ""
+def _join_segments(member_paths: list[str], primary: str, sub: str) -> str:
+ """``"a/b"`` with the two segments in the order the paths nest them.
+
+ Frequency picked them, so it says nothing about which is the parent.
+ Ties keep *primary* first.
+ """
+ primary_first = 0
+ sub_first = 0
+ for path in member_paths:
+ lowers = [p.lower() for p in PurePosixPath(path).parts[:-1]]
+ if primary in lowers and sub in lowers:
+ if lowers.index(primary) <= lowers.index(sub):
+ primary_first += 1
+ else:
+ sub_first += 1
+ return f"{sub}/{primary}" if sub_first > primary_first else f"{primary}/{sub}"
+
+
def _heuristic_label(
member_paths: list[str],
community_id: int,
@@ -305,7 +349,12 @@ def _heuristic_label(
if best_count / len(member_paths) >= 0.4:
# Try to find a distinguishing sub-segment
sub = _best_sub_label(member_paths, best_seg, extra_generic)
- return f"{best_seg}/{sub}" if sub else best_seg
+ return _join_segments(member_paths, best_seg, sub) if sub else best_seg
+ # Two areas sharing one community: name both rather than fall through
+ # to a filename stem.
+ top = seg_counter.most_common(2)
+ if len(top) == 2 and all(c / len(member_paths) >= 0.2 for _, c in top):
+ return f"{top[0][0]}, {top[1][0]}"
# Strategy 2: keyword frequency in filenames
stem_counter: Counter[str] = Counter()
@@ -324,7 +373,12 @@ def _heuristic_label(
stem_counter2: Counter[str] = Counter()
for path in member_paths:
stem = PurePosixPath(path).stem.lower()
- if stem not in _GENERIC_SEGMENTS and stem not in extra_generic and len(stem) > 1:
+ if (
+ stem not in _GENERIC_SEGMENTS
+ and stem not in extra_generic
+ and len(stem) > 1
+ and not stem.startswith("__") # __init__, __main__: not a name
+ ):
stem_counter2[stem] += 1
if stem_counter2:
return stem_counter2.most_common(1)[0][0]
@@ -335,11 +389,14 @@ def _heuristic_label(
def _deduplicate_labels(
communities_info: dict[int, CommunityInfo],
extra_generic: frozenset[str] = frozenset(),
+ label_members: dict[int, list[str]] | None = None,
) -> None:
"""Add sub-labels to disambiguate communities that share the same label.
Mutates *communities_info* in place. Only touches communities whose
- label (before the ``/``) duplicates another community.
+ label (before the ``/``) duplicates another community. *label_members*
+ narrows the paths a sub-label is drawn from (the production members);
+ without it every member counts.
"""
# Group by base label (part before "/")
by_base: dict[str, list[int]] = {}
@@ -357,16 +414,20 @@ def _deduplicate_labels(
if "/" in ci.label:
continue # already has a sub-label
- sub = _best_sub_label(ci.members, base, extra_generic)
+ paths = label_members.get(cid, ci.members) if label_members else ci.members
+ sub = _best_sub_label(paths, base, extra_generic)
if sub:
- ci.label = f"{base}/{sub}"
+ ci.label = _join_segments(paths, base, sub)
+
+ # If duplicates still remain, append the labelled member count
+ def _count(c: int) -> int:
+ return len(label_members[c]) if label_members and c in label_members else communities_info[c].size
- # If duplicates still remain, append size as disambiguator
seen_labels: dict[str, int] = {}
- for cid in sorted(cids, key=lambda c: -communities_info[c].size):
+ for cid in sorted(cids, key=lambda c: -_count(c)):
ci = communities_info[cid]
if ci.label in seen_labels:
- ci.label = f"{ci.label} ({ci.size})"
+ ci.label = f"{ci.label} ({_count(cid)})"
seen_labels[ci.label] = cid
@@ -430,14 +491,17 @@ def _assign_tests_to_communities(
test_community_id = next_cid # shared fallback
for test_path in test_nodes:
- # Production files this test links to, either direction. Every link
- # weighs the same, so the tie is broken on the path. Edge iteration
- # order is graph insertion order and varies between runs.
+ # The community most of the linked production files belong to, one
+ # vote per linked file, either direction. Ties break on community id:
+ # edge iteration order is insertion order and varies between runs.
+ votes: Counter[int] = Counter()
linked = {t for _, t in graph.out_edges(test_path) if t in prod_assignment}
linked |= {s for s, _ in graph.in_edges(test_path) if s in prod_assignment}
+ for prod_path in linked:
+ votes[prod_assignment[prod_path]] += 1
- if linked:
- result[test_path] = prod_assignment[min(linked)]
+ if votes:
+ result[test_path] = min(votes, key=lambda cid: (-votes[cid], cid))
else:
result[test_path] = test_community_id
@@ -451,9 +515,13 @@ def _assign_tests_to_communities(
def detect_file_communities(
graph: nx.DiGraph,
+ repo_name: str | None = None,
) -> tuple[dict[str, int], dict[int, CommunityInfo], str]:
"""Detect communities among file nodes.
+ *repo_name* is a generic segment for labelling: a monorepo repeating
+ ``packages/<x>/src/<repo>`` keeps it under ``dominant_segments``' bar.
+
Returns:
(file_assignment, communities_info, algorithm_used)
- file_assignment: {file_path: community_id}
@@ -563,22 +631,33 @@ def detect_file_communities(
# Repo-dominant namespace segments (the repo's own package name, ``src``…)
# are noise, not labels — same data-driven stripping as module naming.
- extra_generic = frozenset(s.lower() for s in dominant_segments(sorted(file_nodes)))
-
+ generic = {s.lower() for s in dominant_segments(sorted(file_nodes))}
+ if repo_name:
+ stem = repo_name.rsplit("/", 1)[-1].lower()
+ generic |= {stem, stem.replace("-", "_"), stem.replace("_", "-")}
+ extra_generic = frozenset(generic)
+
+ # Labels and conductance come from the production members: tests were kept
+ # out of the partition so they would not shape a community, and they must
+ # not name it either. The non-core catch-all is labelled from what it has.
+ label_members: dict[int, list[str]] = {}
for cid, members in community_members.items():
sorted_members = sorted(members)
+ prod_members = [m for m in sorted_members if not non_core[m]]
+ label_members[cid] = prod_members or sorted_members
communities_info[cid] = CommunityInfo(
community_id=cid,
- label=_heuristic_label(sorted_members, cid, extra_generic),
+ label=_heuristic_label(label_members[cid], cid, extra_generic),
members=sorted_members,
size=len(sorted_members),
cohesion=_cohesion_score(full_undirected, sorted_members),
dominant_language=_dominant_language(sorted_members, graph),
+ conductance=_conductance(undirected, prod_members),
)
# Deduplicate labels — add sub-labels when multiple communities
# share the same base (e.g. "web" → "web/components", "web/api")
- _deduplicate_labels(communities_info, extra_generic)
+ _deduplicate_labels(communities_info, extra_generic, label_members)
log.info(
"file_communities_detected",
diff --git a/packages/core/src/repowise/core/analysis/knowledge_graph.py b/packages/core/src/repowise/core/analysis/knowledge_graph.py
index 6368d21d9..4c73ad982 100644
--- a/packages/core/src/repowise/core/analysis/knowledge_graph.py
+++ b/packages/core/src/repowise/core/analysis/knowledge_graph.py
@@ -17,6 +17,7 @@ from pathlib import Path, PurePosixPath
from typing import Any
from repowise.core.generation.entry_points import orientation_entry_points
+from repowise.core.support_paths import CONFIG_EXTENSIONS, DOC_EXTENSIONS
_log = logging.getLogger(__name__)
@@ -147,10 +148,7 @@ class KnowledgeGraphResult:
# Node classification helpers
# ---------------------------------------------------------------------------
-_CONFIG_EXTENSIONS = frozenset({
- ".yaml", ".yml", ".toml", ".json", ".env", ".ini", ".cfg", ".conf",
- ".properties", ".xml",
-})
+_CONFIG_EXTENSIONS = CONFIG_EXTENSIONS
_INFRA_EXTENSIONS = frozenset({
".dockerfile", ".tf", ".hcl",
@@ -163,9 +161,7 @@ _INFRA_NAMES = frozenset({
_INFRA_LANGUAGES = frozenset({"dockerfile", "makefile"})
-_DOC_EXTENSIONS = frozenset({
- ".md", ".rst", ".txt", ".adoc",
-})
+_DOC_EXTENSIONS = DOC_EXTENSIONS
def _classify_file_type(path: str, language: str, is_config: bool) -> str:
diff --git a/packages/core/src/repowise/core/ingestion/graph/_metrics.py b/packages/core/src/repowise/core/ingestion/graph/_metrics.py
index ca33c2e39..c45c0a1f5 100644
--- a/packages/core/src/repowise/core/ingestion/graph/_metrics.py
+++ b/packages/core/src/repowise/core/ingestion/graph/_metrics.py
@@ -265,7 +265,10 @@ class MetricsMixin:
from repowise.core.analysis.communities import detect_file_communities
try:
- assignment, info, algo = detect_file_communities(self._graph)
+ repo_path = getattr(self, "_repo_path", None)
+ assignment, info, algo = detect_file_communities(
+ self._graph, repo_name=repo_path.name if repo_path else None
+ )
self._community_cache = assignment
self._community_info_cache = info
self._community_algo = algo
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index 8037cab24..597b9485c 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -375,6 +375,7 @@ async def persist_graph_nodes(
community_meta = {
"label": comm_info.label,
"cohesion": comm_info.cohesion,
+ "conductance": comm_info.conductance,
}
elif node_type == "symbol":
sym_cid = sc.get(node_id)
diff --git a/packages/core/src/repowise/core/support_paths.py b/packages/core/src/repowise/core/support_paths.py
index ffd0514b2..756263539 100644
--- a/packages/core/src/repowise/core/support_paths.py
+++ b/packages/core/src/repowise/core/support_paths.py
@@ -12,8 +12,17 @@ so callers meaning "written to illustrate the subject" want the former.
from __future__ import annotations
from pathlib import PurePosixPath
+from typing import Literal
-__all__ = ["is_example_path", "is_support_path"]
+__all__ = [
+ "CONFIG_EXTENSIONS",
+ "DOC_EXTENSIONS",
+ "FilePopulation",
+ "file_population",
+ "is_doc_or_config_path",
+ "is_example_path",
+ "is_support_path",
+]
# Example/demo/benchmark directories: documentation-by-code and support
@@ -62,6 +71,40 @@ def is_example_path(path: str) -> bool:
return _has_dir_token(path, EXAMPLE_DIR_TOKENS)
+# Shared with the knowledge graph's node classifier.
+CONFIG_EXTENSIONS = frozenset(
+ {
+ ".yaml", ".yml", ".toml", ".json", ".env", ".ini", ".cfg", ".conf",
+ ".properties", ".xml",
+ }
+)
+DOC_EXTENSIONS = frozenset({".md", ".mdx", ".rst", ".txt", ".adoc"})
+
+
+def is_doc_or_config_path(path: str) -> bool:
+ """Whether *path* is documentation or configuration rather than code."""
+ ext = PurePosixPath(path).suffix.lower()
+ return ext in CONFIG_EXTENSIONS or ext in DOC_EXTENSIONS
+
+
+FilePopulation = Literal["production", "test", "example", "doc"]
+
+
+def file_population(path: str, *, is_test: bool) -> FilePopulation:
+ """Which population a file belongs to, for surfaces that hide non-production.
+
+ Disjoint, in precedence order: ``tests/data/x.json`` is a test, not a doc.
+ *is_test* is the flag ingestion stored; the path rules cover the other two.
+ """
+ if is_test:
+ return "test"
+ if is_example_path(path):
+ return "example"
+ if is_doc_or_config_path(path):
+ return "doc"
+ return "production"
+
+
def is_support_path(path: str) -> bool:
"""Whether *path* is support material (examples/benchmarks/docs sites).
diff --git a/packages/server/src/repowise/server/mcp_server/_graph_utils.py b/packages/server/src/repowise/server/mcp_server/_graph_utils.py
index 3d36d96e7..13b4996ad 100644
--- a/packages/server/src/repowise/server/mcp_server/_graph_utils.py
+++ b/packages/server/src/repowise/server/mcp_server/_graph_utils.py
@@ -57,6 +57,13 @@ def community_cohesion(node: GraphNode) -> float:
return float(meta.get("cohesion", 0.0) or 0.0)
+def community_conductance(node: GraphNode) -> float | None:
+ """Conductance from community_meta_json; ``None`` on an older index."""
+ meta = parse_community_meta(node)
+ value = meta.get("conductance")
+ return float(value) if value is not None else None
+
+
def entry_point_score(node: GraphNode) -> float:
"""Extract entry_point_score from community_meta_json (symbol nodes only)."""
meta = parse_community_meta(node)
diff --git a/packages/server/src/repowise/server/routers/graph/community.py b/packages/server/src/repowise/server/routers/graph/community.py
index 7833e685f..bac90eb31 100644
--- a/packages/server/src/repowise/server/routers/graph/community.py
+++ b/packages/server/src/repowise/server/routers/graph/community.py
@@ -3,6 +3,9 @@
The architecture and slice endpoints are thin wrappers over
:mod:`repowise.server.services.graph_views` so non-HTTP consumers can build
the same payloads without FastAPI.
+
+Every endpoint takes the same three population flags (all off), so the map,
+the list, the panel and the drill-down count the same files.
"""
from __future__ import annotations
@@ -11,9 +14,12 @@ from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.ext.asyncio import AsyncSession
from repowise.core.persistence import crud
-from repowise.core.persistence.models import GraphNode
from repowise.server.deps import get_db_session
-from repowise.server.mcp_server._graph_utils import community_cohesion, community_label
+from repowise.server.mcp_server._graph_utils import (
+ community_cohesion,
+ community_conductance,
+ community_label,
+)
from repowise.server.routers.graph._common import with_repo
from repowise.server.schemas import (
ArchitectureGraphResponse,
@@ -24,38 +30,53 @@ from repowise.server.schemas import (
NeighboringCommunity,
)
from repowise.server.services.graph_views import (
+ MEMBER_READ_CAP,
SLICE_MEMBER_CAP,
+ Population,
+ bucket_by_community,
build_architecture_graph,
build_community_slice,
+ neighbour_edge_counts,
+ split_population,
)
from repowise.server.services.node_signals import EMPTY_SIGNALS, collect_node_signals
-# How many members the detail endpoint reads to compute the community's shape
-# and state. It used to be 200, which silently disagreed with the community
-# *list* — a 587-file community reported 587 there and 200 here, and every
-# rollup below covered a third of it.
-#
-# Ceiling: a community larger than this still reports this number, and its
-# counts still cover only the top slice by PageRank. The largest community in
-# any repo indexed so far is under 600, so nothing reaches it. If one does, the
-# upgrade is a `SELECT COUNT(*)` for the true `member_count` plus an explicit
-# "counted over the top N" field, not a bigger constant.
-_MEMBER_READ_CAP = 2000
-
router = APIRouter()
+def population_params(
+ include_tests: bool = Query(
+ False, description="Count test files as members. Off: production only."
+ ),
+ include_examples: bool = Query(
+ False, description="Count example, demo and benchmark files as members."
+ ),
+ include_docs: bool = Query(
+ False, description="Count documentation and configuration files as members."
+ ),
+) -> Population:
+ """The population flags, shared by every community endpoint."""
+ return Population(
+ include_tests=include_tests,
+ include_examples=include_examples,
+ include_docs=include_docs,
+ )
+
+
@router.get("/{repo_id}/architecture", response_model=ArchitectureGraphResponse)
async def architecture_graph(
repo_id: str,
min_members: int = Query(
2, ge=1, description="Drop communities smaller than this from the view."
),
+ population: Population = Depends(population_params),
session: AsyncSession = Depends(get_db_session),
_repo: object = Depends(with_repo),
) -> ArchitectureGraphResponse:
"""High-level architecture view: one node per detected community."""
- return await build_architecture_graph(session, repo_id, min_members=min_members)
+ return await build_architecture_graph(
+ session, repo_id, min_members=min_members, population=population
+ )
@router.get(
@@ -66,12 +87,13 @@ async def community_slice(
repo_id: str,
community_id: int,
member_limit: int = Query(SLICE_MEMBER_CAP, ge=1, le=600),
+ population: Population = Depends(population_params),
session: AsyncSession = Depends(get_db_session),
_repo: object = Depends(with_repo),
) -> CommunitySliceResponse:
- """Return a single community's sub-graph for the constellation blossom."""
+ """Return a single community's sub-graph for the drill-down."""
return await build_community_slice(
- session, repo_id, community_id, member_limit=member_limit
+ session, repo_id, community_id, member_limit=member_limit, population=population
)
@@ -79,20 +101,17 @@ async def community_slice(
async def list_communities(
repo_id: str,
limit: int = Query(20, ge=1, le=100),
+ population: Population = Depends(population_params),
session: AsyncSession = Depends(get_db_session),
_repo: object = Depends(with_repo),
) -> list[CommunitySummaryItem]:
- """Return top communities by member count with labels and cohesion scores."""
+ """Return top communities by visible member count with labels and shape scores."""
all_nodes = await crud.get_all_file_metrics(session, repo_id)
-
- # Group by community_id
- buckets: dict[int, list[GraphNode]] = {}
- for n in all_nodes:
- cid = n.community_id if n.community_id is not None else 0
- buckets.setdefault(cid, []).append(n)
+ visible, _counts = split_population(all_nodes, population)
+ buckets, hidden = bucket_by_community(all_nodes, visible)
items: list[CommunitySummaryItem] = []
- for cid, members in sorted(buckets.items(), key=lambda kv: -len(kv[1])):
+ for cid, members in sorted(buckets.items(), key=lambda kv: (-len(kv[1]), kv[0])):
# Pick top-pagerank member for label/cohesion extraction
top = max(members, key=lambda m: m.pagerank or 0.0)
items.append(
@@ -100,7 +119,9 @@ async def list_communities(
community_id=cid,
label=community_label(top),
cohesion=community_cohesion(top),
+ conductance=community_conductance(top),
member_count=len(members),
+ hidden_member_count=hidden[cid],
top_file=top.node_id,
)
)
@@ -119,25 +140,32 @@ async def get_community_detail(
community_id: int,
include_members: bool = Query(True),
member_limit: int = Query(30, ge=1, le=200),
+ population: Population = Depends(population_params),
session: AsyncSession = Depends(get_db_session),
_repo: object = Depends(with_repo),
) -> CommunityDetailResponse:
"""Return detailed info for a single community."""
all_members = await crud.get_community_members(
- session, repo_id, community_id, node_type="file", limit=_MEMBER_READ_CAP
+ session, repo_id, community_id, node_type="file", limit=MEMBER_READ_CAP
)
if not all_members:
raise HTTPException(status_code=404, detail="Community not found or empty")
+ # Label and shape are stored on every member; the counts below are over the
+ # visible members only. An all-hidden group reports zero, not 404.
top = max(all_members, key=lambda m: m.pagerank or 0.0)
label = community_label(top)
cohesion = community_cohesion(top)
+ conductance = community_conductance(top)
+
+ members, counts = split_population(all_members, population)
+ hidden_member_count = sum(counts.values()) - len(members)
# State of the area, in two path-scoped reads over the same member list the
# shape figures above are computed from. `collect_node_signals` is the same
# join `build_architecture_graph` uses for the hub discs, so a community's
# hot/dead counts here and its disc on the canvas can never disagree.
- member_paths = [m.node_id for m in all_members]
+ member_paths = [m.node_id for m in members]
signals = await collect_node_signals(session, repo_id, member_paths)
hot_count = sum(1 for p in member_paths if signals.get(p, EMPTY_SIGNALS).is_hotspot)
dead_count = sum(1 for p in member_paths if signals.get(p, EMPTY_SIGNALS).is_dead)
@@ -164,8 +192,10 @@ async def get_community_detail(
# `rollup_health`: effective score prefers the split defect_score and falls
# back to the overall score, weight is max(nloc, 1), and a community where
# nothing is scored gets None rather than a zero it never measured.
- health_metrics = await crud.get_health_metrics(
- session, repo_id, file_paths=member_paths
+ health_metrics = (
+ await crud.get_health_metrics(session, repo_id, file_paths=member_paths)
+ if member_paths
+ else []
)
weighted_sum = 0.0
weight = 0.0
@@ -182,7 +212,7 @@ async def get_community_detail(
members_out: list[CommunityMember] = []
if include_members:
- for m in all_members[:member_limit]:
+ for m in members[:member_limit]:
sig = signals.get(m.node_id, EMPTY_SIGNALS)
members_out.append(
CommunityMember(
@@ -194,15 +224,15 @@ async def get_community_detail(
)
)
- # Neighboring communities. `get_cross_community_edges` orders by edge count
- # descending, so the top slice is taken *before* the label loop: it used to
- # resolve a label for every neighbour in the repo and then keep ten.
- cross_edges = (await crud.get_cross_community_edges(session, repo_id, community_id))[
- :10
- ]
- neighbor_cids = [ce["target_community_id"] for ce in cross_edges]
+ # Same population on both ends as the map's cross edges; sliced before the
+ # label loop.
+ cross_edges = (
+ await neighbour_edge_counts(
+ session, repo_id, community_id, member_paths, population=population
+ )
+ )[:10]
neighbor_labels: dict[int, str] = {}
- for ncid in neighbor_cids:
+ for ncid, _count in cross_edges:
nbr_members = await crud.get_community_members(
session, repo_id, ncid, node_type="file", limit=1
)
@@ -213,20 +243,22 @@ async def get_community_detail(
neighbors = [
NeighboringCommunity(
- community_id=ce["target_community_id"],
- label=neighbor_labels.get(ce["target_community_id"], ""),
- cross_edge_count=ce["edge_count"],
+ community_id=ncid,
+ label=neighbor_labels.get(ncid, ""),
+ cross_edge_count=count,
)
- for ce in cross_edges
+ for ncid, count in cross_edges
]
return CommunityDetailResponse(
community_id=community_id,
label=label,
cohesion=cohesion,
- member_count=len(all_members),
+ conductance=conductance,
+ member_count=len(members),
+ hidden_member_count=hidden_member_count,
members=members_out,
- truncated=len(all_members) > member_limit,
+ truncated=len(members) > member_limit,
neighboring_communities=neighbors,
health_score=health_score,
scored_member_count=scored_member_count,
diff --git a/packages/server/src/repowise/server/schemas/__init__.py b/packages/server/src/repowise/server/schemas/__init__.py
index 5ce6352f7..d7033786a 100644
--- a/packages/server/src/repowise/server/schemas/__init__.py
+++ b/packages/server/src/repowise/server/schemas/__init__.py
@@ -145,6 +145,8 @@ from .graph import (
ModuleGraphResponse,
ModuleNodeResponse,
NodeSearchResult,
+ PopulationBreakdown,
+ UnclusteredFiles,
)
from .health import (
CoordinatorHealthResponse,
@@ -430,6 +432,7 @@ __all__ = [
"PageSummaryResponse",
"PageVersionResponse",
"Paginated",
+ "PopulationBreakdown",
"ProviderEntry",
"ProviderStatusResponse",
"ProviderValidationResponse",
@@ -460,6 +463,7 @@ __all__ = [
"SymbolNodeSummary",
"SymbolResponse",
"TransitiveEntry",
+ "UnclusteredFiles",
"UpdateMcpToolsRequest",
"VersionResponse",
"WebhookResponse",
diff --git a/packages/server/src/repowise/server/schemas/graph.py b/packages/server/src/repowise/server/schemas/graph.py
index 86112d105..374c66bcb 100644
--- a/packages/server/src/repowise/server/schemas/graph.py
+++ b/packages/server/src/repowise/server/schemas/graph.py
@@ -62,11 +62,44 @@ class GraphExportResponse(BaseModel):
# Architecture / community super-node graph
+class PopulationBreakdown(BaseModel):
+ """What the map is counting.
+
+ Every count in the payload is over ``visible``. The category totals are
+ reported whether or not included, so a client can offer "show tests (N)".
+ """
+
+ total: int
+ visible: int
+ tests: int = 0
+ examples: int = 0
+ docs: int = 0
+ include_tests: bool = False
+ include_examples: bool = False
+ include_docs: bool = False
+
+
+class UnclusteredFiles(BaseModel):
+ """Visible files below ``min_members``; almost all have no dependency edge.
+
+ ``files`` is the head by PageRank, capped.
+ """
+
+ file_count: int
+ files: list[str] = []
+
+
class ArchitectureNodeResponse(BaseModel):
community_id: int
label: str
+ #: Decays with size; kept for older clients. The map reads ``conductance``.
cohesion: float
+ #: ``cut / (2 * intra + cut)`` over production members, lower is tighter.
+ #: ``None`` on an older index or when nothing is linked.
+ conductance: float | None = None
+ #: Members in the requested population; every figure below is over them.
member_count: int
+ hidden_member_count: int = 0
top_file: str
avg_pagerank: float
hotspot_count: int = 0
@@ -85,6 +118,8 @@ class ArchitectureEdgeResponse(BaseModel):
class ArchitectureGraphResponse(BaseModel):
nodes: list[ArchitectureNodeResponse]
edges: list[ArchitectureEdgeResponse]
+ population: PopulationBreakdown | None = None
+ unclustered: UnclusteredFiles | None = None
class CommunitySliceNodeResponse(GraphNodeResponse):
@@ -102,6 +137,7 @@ class CommunitySliceResponse(BaseModel):
member_count: int
# True if members were capped (very large community).
truncated: bool = False
+ hidden_member_count: int = 0
class EgoGraphResponse(BaseModel):
diff --git a/packages/server/src/repowise/server/schemas/intelligence.py b/packages/server/src/repowise/server/schemas/intelligence.py
index 4623fa6a0..b2f7f55a1 100644
--- a/packages/server/src/repowise/server/schemas/intelligence.py
+++ b/packages/server/src/repowise/server/schemas/intelligence.py
@@ -154,8 +154,14 @@ class NeighboringCommunity(BaseModel):
class CommunityDetailResponse(BaseModel):
community_id: int
label: str
+ #: Decays with size; kept for older clients. The panel reads ``conductance``.
cohesion: float
+ #: ``cut / (2 * intra + cut)`` over production members, lower is tighter.
+ #: ``None`` on an older index or when nothing is linked.
+ conductance: float | None = None
+ #: Members in the requested population; every count below is over them.
member_count: int
+ hidden_member_count: int = 0
members: list[CommunityMember]
truncated: bool
neighboring_communities: list[NeighboringCommunity]
@@ -187,7 +193,9 @@ class CommunitySummaryItem(BaseModel):
community_id: int
label: str
cohesion: float
+ conductance: float | None = None
member_count: int
+ hidden_member_count: int = 0
top_file: str
diff --git a/packages/server/src/repowise/server/services/graph_views.py b/packages/server/src/repowise/server/services/graph_views.py
index 5fba4bea4..0809de654 100644
--- a/packages/server/src/repowise/server/services/graph_views.py
+++ b/packages/server/src/repowise/server/services/graph_views.py
@@ -11,13 +11,21 @@ SAME functions so both serving paths emit byte-identical shapes
from __future__ import annotations
import json
+from collections import Counter
+from dataclasses import dataclass
from sqlalchemy import or_, select
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.ids import is_external
from repowise.core.persistence import crud
from repowise.core.persistence.models import GraphEdge, GraphNode
-from repowise.server.mcp_server._graph_utils import community_cohesion, community_label
+from repowise.core.support_paths import FilePopulation, file_population
+from repowise.server.mcp_server._graph_utils import (
+ community_cohesion,
+ community_conductance,
+ community_label,
+)
from repowise.server.schemas import (
ArchitectureEdgeResponse,
ArchitectureGraphResponse,
@@ -25,6 +33,8 @@ from repowise.server.schemas import (
CommunitySliceNodeResponse,
CommunitySliceResponse,
GraphEdgeResponse,
+ PopulationBreakdown,
+ UnclusteredFiles,
)
from repowise.server.services.node_signals import (
EMPTY_SIGNALS,
@@ -43,6 +53,98 @@ SLICE_BOUNDARY_CAP = 40
# (source + target) in one statement, so we cap each chunk well under SQLite's
# 999-parameter limit to leave room for both lists plus the repo_id bind.
_SLICE_IN_CHUNK = 400
+# Members read before the population filter and any display cap apply.
+# Ceiling: a larger community still reports this number. The largest indexed so
+# far is under 800; past it the upgrade is a COUNT(*) plus a "counted over the
+# top N" field, not a bigger constant.
+MEMBER_READ_CAP = 2000
+# Boundary candidates resolved (rows carry `is_test`) before the filter and cap.
+# Ceiling: mostly-hidden neighbourhoods return fewer than SLICE_BOUNDARY_CAP.
+_SLICE_BOUNDARY_CANDIDATES = SLICE_BOUNDARY_CAP * 3
+# Head of the unclustered list carried on the architecture payload.
+UNCLUSTERED_SAMPLE_CAP = 200
+
+
+@dataclass(frozen=True)
+class Population:
+ """Which non-production populations a community view counts.
+
+ Production is always in. Applied before anything is sized or ranked, so no
+ number on the map describes files it does not draw.
+ """
+
+ include_tests: bool = False
+ include_examples: bool = False
+ include_docs: bool = False
+
+ def keeps(self, kind: FilePopulation) -> bool:
+ if kind == "test":
+ return self.include_tests
+ if kind == "example":
+ return self.include_examples
+ if kind == "doc":
+ return self.include_docs
+ return True
+
+
+PRODUCTION_ONLY = Population()
+
+
+def is_external_node(node: GraphNode) -> bool:
+ """``external:`` and ``framework:`` rows are stored as files; they are not."""
+ return is_external(node.node_id)
+
+
+def bucket_by_community(
+ all_nodes: list[GraphNode], visible: list[GraphNode]
+) -> tuple[dict[int, list[GraphNode]], Counter[int]]:
+ """Visible members per community, and how many each community hides."""
+ visible_ids = {n.node_id for n in visible}
+ buckets: dict[int, list[GraphNode]] = {}
+ hidden: Counter[int] = Counter()
+ for n in all_nodes:
+ if is_external_node(n):
+ continue
+ cid = n.community_id if n.community_id is not None else 0
+ if n.node_id in visible_ids:
+ buckets.setdefault(cid, []).append(n)
+ else:
+ hidden[cid] += 1
+ return buckets, hidden
+
+
+def split_population(
+ nodes: list[GraphNode], population: Population
+) -> tuple[list[GraphNode], Counter[str]]:
+ """Return the nodes *population* keeps, and a count of every kind seen.
+
+ External nodes are dropped and not counted.
+ """
+ kept: list[GraphNode] = []
+ counts: Counter[str] = Counter()
+ for n in nodes:
+ if is_external_node(n):
+ continue
+ kind = file_population(n.node_id, is_test=bool(n.is_test))
+ counts[kind] += 1
+ if population.keeps(kind):
+ kept.append(n)
+ return kept, counts
+
+
+def population_breakdown(
+ counts: Counter[str], visible: int, population: Population
+) -> PopulationBreakdown:
+ return PopulationBreakdown(
+ total=sum(counts.values()),
+ visible=visible,
+ tests=counts["test"],
+ examples=counts["example"],
+ docs=counts["doc"],
+ include_tests=population.include_tests,
+ include_examples=population.include_examples,
+ include_docs=population.include_docs,
+ )
def _parse_imported_names(raw: str | None) -> list[str]:
@@ -70,6 +172,7 @@ async def build_architecture_graph(
session: AsyncSession,
repo_id: str,
min_members: int = 2,
+ population: Population = PRODUCTION_ONLY,
) -> ArchitectureGraphResponse:
"""High-level architecture view: one node per detected community.
@@ -77,26 +180,29 @@ async def build_architecture_graph(
edges that cross the boundary. Each super-node also carries signal counts
(hotspots, dead files, decisions, doc coverage) so the architecture view
surfaces health at a glance.
+
+ Every figure, the ranking and the ``min_members`` cut are computed over
+ the *population*.
"""
all_nodes = await crud.get_all_file_metrics(session, repo_id)
if not all_nodes:
return ArchitectureGraphResponse(nodes=[], edges=[])
- # Group file nodes by community
- buckets: dict[int, list[GraphNode]] = {}
- node_to_community: dict[str, int] = {}
- for n in all_nodes:
- cid = n.community_id if n.community_id is not None else 0
- buckets.setdefault(cid, []).append(n)
- node_to_community[n.node_id] = cid
+ visible, counts = split_population(all_nodes, population)
+ breakdown = population_breakdown(counts, len(visible), population)
- # Pull cross-link signals once for the whole repo so super-nodes can
- # aggregate hotspot/dead/decision counts without N round-trips.
- signals = await collect_node_signals(session, repo_id, [n.node_id for n in all_nodes])
+ buckets, hidden_per_community = bucket_by_community(all_nodes, visible)
+ node_to_community = {n.node_id: cid for cid, members in buckets.items() for n in members}
+
+ # Pull cross-link signals once for the visible population so super-nodes
+ # can aggregate hotspot/dead/decision counts without N round-trips.
+ signals = await collect_node_signals(session, repo_id, [n.node_id for n in visible])
arch_nodes: list[ArchitectureNodeResponse] = []
+ unclustered: list[GraphNode] = []
for cid, members in buckets.items():
if len(members) < min_members:
+ unclustered.extend(members)
continue
top = max(members, key=lambda m: m.pagerank or 0.0)
hotspot_count = 0
@@ -124,7 +230,9 @@ async def build_architecture_graph(
community_id=cid,
label=community_label(top),
cohesion=community_cohesion(top),
+ conductance=community_conductance(top),
member_count=len(members),
+ hidden_member_count=hidden_per_community[cid],
top_file=top.node_id,
avg_pagerank=avg_pr,
hotspot_count=hotspot_count,
@@ -156,7 +264,59 @@ async def build_architecture_graph(
for (s, t), c in edge_counts.items()
]
- return ArchitectureGraphResponse(nodes=arch_nodes, edges=arch_edges)
+ unclustered.sort(key=lambda n: (-(n.pagerank or 0.0), n.node_id))
+ return ArchitectureGraphResponse(
+ nodes=arch_nodes,
+ edges=arch_edges,
+ population=breakdown,
+ unclustered=UnclusteredFiles(
+ file_count=len(unclustered),
+ files=[n.node_id for n in unclustered[:UNCLUSTERED_SAMPLE_CAP]],
+ ),
+ )
+
+
+async def neighbour_edge_counts(
+ session: AsyncSession,
+ repo_id: str,
+ community_id: int,
+ member_ids: list[str],
+ population: Population = PRODUCTION_ONLY,
+) -> list[tuple[int, int]]:
+ """``[(community_id, edge_count)]`` for the communities *member_ids* depend on.
+
+ Outbound file edges to another community, both ends in the *population*,
+ most-connected first. ``crud.get_cross_community_edges`` is the unfiltered
+ SQL form.
+ """
+ if not member_ids:
+ return []
+ member_set = set(member_ids)
+ targets: Counter[str] = Counter()
+ for start in range(0, len(member_ids), _SLICE_IN_CHUNK):
+ chunk = member_ids[start : start + _SLICE_IN_CHUNK]
+ rows = await session.execute(
+ select(GraphEdge.target_node_id).where(
+ GraphEdge.repository_id == repo_id,
+ GraphEdge.source_node_id.in_(chunk),
+ )
+ )
+ for (target,) in rows.all():
+ if target not in member_set:
+ targets[target] += 1
+
+ outside = await crud.get_graph_nodes_by_ids(session, repo_id, list(targets))
+ per_community: Counter[int] = Counter()
+ for target, count in targets.items():
+ node = outside.get(target)
+ if node is None or node.node_type != "file" or node.community_id == community_id:
+ continue
+ if is_external_node(node):
+ continue
+ if not population.keeps(file_population(node.node_id, is_test=bool(node.is_test))):
+ continue
+ per_community[node.community_id] += count
+ return sorted(per_community.items(), key=lambda kv: (-kv[1], kv[0]))
async def build_community_slice(
@@ -164,6 +324,7 @@ async def build_community_slice(
repo_id: str,
community_id: int,
member_limit: int = SLICE_MEMBER_CAP,
+ population: Population = PRODUCTION_ONLY,
) -> CommunitySliceResponse:
"""Return a single community's sub-graph for the constellation blossom.
@@ -172,11 +333,16 @@ async def build_community_slice(
that share an edge with a member, returned as minimal nodes flagged
``is_boundary=true`` so cross-cluster edges can render without dragging the
whole neighbor cluster in. Sized to ~50-300 nodes.
+
+ Members and boundary stubs are both filtered to the *population*.
"""
- members = await crud.get_community_members(
- session, repo_id, community_id, node_type="file", limit=member_limit + 1
+ all_members = await crud.get_community_members(
+ session, repo_id, community_id, node_type="file", limit=MEMBER_READ_CAP
)
- truncated = len(members) > member_limit
+ members, counts = split_population(all_members, population)
+ hidden_member_count = sum(counts.values()) - len(members)
+ visible_member_count = len(members) # before the display cap
+ truncated = visible_member_count > member_limit
if truncated:
members = members[:member_limit]
member_ids = {m.node_id for m in members}
@@ -214,28 +380,34 @@ async def build_community_slice(
if not src_in and not tgt_in:
continue
kept_edges.append(e)
- if not src_in:
+ # External stubs are ranked out here, not after the cap, so they
+ # cannot take the boundary slots from real files.
+ if not src_in and not is_external(e.source_node_id):
boundary_degree[e.source_node_id] = boundary_degree.get(e.source_node_id, 0) + 1
- if not tgt_in:
+ if not tgt_in and not is_external(e.target_node_id):
boundary_degree[e.target_node_id] = boundary_degree.get(e.target_node_id, 0) + 1
# Cap boundary stubs to the most-connected neighbors: hub communities can
# touch thousands of outside files, which would flood the blossom with
# dust. Edges to dropped stubs are filtered by the visible_ids pass below.
- boundary_ids = set(
- sorted(boundary_degree, key=lambda n: (-boundary_degree[n], n))[:SLICE_BOUNDARY_CAP]
- )
+ candidate_ids = sorted(boundary_degree, key=lambda n: (-boundary_degree[n], n))[
+ :_SLICE_BOUNDARY_CANDIDATES
+ ]
# Resolve boundary stub rows (minimal: just need a node row to render).
boundary_nodes: list[GraphNode] = []
- if boundary_ids:
+ if candidate_ids:
stub_result = await session.execute(
select(GraphNode).where(
GraphNode.repository_id == repo_id,
- GraphNode.node_id.in_(boundary_ids),
+ GraphNode.node_id.in_(candidate_ids),
)
)
- boundary_nodes = list(stub_result.scalars().all())
+ by_id = {n.node_id: n for n in stub_result.scalars()}
+ kept, _ = split_population(
+ [by_id[n] for n in candidate_ids if n in by_id], population
+ )
+ boundary_nodes = kept[:SLICE_BOUNDARY_CAP]
resolved_boundary = {n.node_id for n in boundary_nodes}
# Drop edges whose outside endpoint has no resolvable node (orphan ref).
@@ -261,6 +433,7 @@ async def build_community_slice(
nodes=nodes,
links=links,
community_id=community_id,
- member_count=len(members),
+ member_count=visible_member_count,
truncated=truncated,
+ hidden_member_count=hidden_member_count,
)
diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.ts
index 43d2f225a..541a40dd8 100644
--- a/packages/types/src/generated/http.ts
+++ b/packages/types/src/generated/http.ts
@@ -108,13 +108,17 @@ export interface ArchitectureEdgeResponse {
export interface ArchitectureGraphResponse {
nodes: ArchitectureNodeResponse[];
edges: ArchitectureEdgeResponse[];
+ population?: PopulationBreakdown | null;
+ unclustered?: UnclusteredFiles | null;
}
export interface ArchitectureNodeResponse {
community_id: number;
label: string;
cohesion: number;
+ conductance?: number | null;
member_count: number;
+ hidden_member_count?: number;
top_file: string;
avg_pagerank: number;
hotspot_count?: number;
@@ -500,7 +504,9 @@ export interface CommunityDetailResponse {
community_id: number;
label: string;
cohesion: number;
+ conductance?: number | null;
member_count: number;
+ hidden_member_count?: number;
members: CommunityMember[];
truncated: boolean;
neighboring_communities: NeighboringCommunity[];
@@ -547,13 +553,16 @@ export interface CommunitySliceResponse {
community_id: number;
member_count: number;
truncated?: boolean;
+ hidden_member_count?: number;
}
export interface CommunitySummaryItem {
community_id: number;
label: string;
cohesion: number;
+ conductance?: number | null;
member_count: number;
+ hidden_member_count?: number;
top_file: string;
}
@@ -2019,6 +2028,23 @@ export interface Paginated_SymbolResponse_ {
next_offset?: number | null;
}
+/**
+ * What the map is counting.
+ *
+ * Every count in the payload is over ``visible``. The category totals are
+ * reported whether or not included, so a client can offer "show tests (N)".
+ */
+export interface PopulationBreakdown {
+ total: number;
+ visible: number;
+ tests?: number;
+ examples?: number;
+ docs?: number;
+ include_tests?: boolean;
+ include_examples?: boolean;
+ include_docs?: boolean;
+}
+
/** One provider in the catalog, as the settings picker renders it. */
export interface ProviderEntry {
id: string;
@@ -2564,6 +2590,16 @@ export interface TransitiveEntry {
depth: number;
}
+/**
+ * Visible files below ``min_members``; almost all have no dependency edge.
+ *
+ * ``files`` is the head by PageRank, capped.
+ */
+export interface UnclusteredFiles {
+ file_count: number;
+ files?: string[];
+}
+
/**
* Persist a new ``mcp.tools`` override for a repo.
*
diff --git a/packages/types/src/graph.ts b/packages/types/src/graph.ts
index afe8d31bc..47a5cbf0d 100644
--- a/packages/types/src/graph.ts
+++ b/packages/types/src/graph.ts
@@ -74,8 +74,15 @@ export interface GraphExport {
export interface ArchitectureNode {
community_id: number;
label: string;
+ /** Decays with size; kept for older servers. Read `conductance` instead. */
cohesion: number;
+ /** Share of this group's dependency volume that leaves it, lower is tighter.
+ * Absent or null on an older index. */
+ conductance?: number | null;
+ /** Members in the requested population; every figure is over them. */
member_count: number;
+ /** Members the population filter left out. */
+ hidden_member_count?: number;
top_file: string;
avg_pagerank: number;
hotspot_count: number;
@@ -91,9 +98,39 @@ export interface ArchitectureEdge {
edge_count: number;
}
+/** Which non-production files a community view counts. All off = production only. */
+export interface GraphPopulation {
+ tests: boolean;
+ examples: boolean;
+ docs: boolean;
+}
+
+export const PRODUCTION_ONLY: GraphPopulation = { tests: false, examples: false, docs: false };
+
+/** What the map is counting. Category totals are always reported. */
+export interface PopulationBreakdown {
+ total: number;
+ visible: number;
+ tests?: number;
+ examples?: number;
+ docs?: number;
+ include_tests?: boolean;
+ include_examples?: boolean;
+ include_docs?: boolean;
+}
+
+/** Visible files in no drawn community. `files` is the head by PageRank. */
+export interface UnclusteredFiles {
+ file_count: number;
+ files?: string[];
+}
+
export interface ArchitectureGraph {
nodes: ArchitectureNode[];
edges: ArchitectureEdge[];
+ /** Both absent on an older server. */
+ population?: PopulationBreakdown | null;
+ unclustered?: UnclusteredFiles | null;
}
// ---------------------------------------------------------------------------
@@ -111,6 +148,7 @@ export interface CommunitySlice {
community_id: number;
member_count: number;
truncated?: boolean;
+ hidden_member_count?: number;
}
// ---------------------------------------------------------------------------
@@ -354,8 +392,14 @@ export interface NeighboringCommunity {
export interface CommunityDetail {
community_id: number;
label: string;
+ /** Decays with size; kept for older servers. The panel reads `conductance`. */
cohesion: number;
+ /** Share of this group's dependency volume that leaves it, lower is tighter.
+ * Absent or null on an older index. */
+ conductance?: number | null;
+ /** Members in the requested population; every count is over them. */
member_count: number;
+ hidden_member_count?: number;
members: CommunityMember[];
truncated: boolean;
neighboring_communities: NeighboringCommunity[];
@@ -383,7 +427,9 @@ export interface CommunitySummaryItem {
community_id: number;
label: string;
cohesion: number;
+ conductance?: number | null;
member_count: number;
+ hidden_member_count?: number;
top_file: string;
}
diff --git a/packages/ui/__tests__/graph/constellation-adapter.test.ts b/packages/ui/__tests__/graph/constellation-adapter.test.ts
index a078a3ed7..b6079bdab 100644
--- a/packages/ui/__tests__/graph/constellation-adapter.test.ts
+++ b/packages/ui/__tests__/graph/constellation-adapter.test.ts
@@ -3,6 +3,8 @@ import {
architectureToGraphology,
hubNodeId,
CORE_NODE_ID,
+ UNCLUSTERED_COMMUNITY_ID,
+ UNCLUSTERED_NODE_ID,
mergeCommunitySlice,
satelliteSizeFromPagerank,
} from "../../src/graph/sigma/constellation-adapter";
@@ -324,3 +326,30 @@ describe("mergeCommunitySlice", () => {
expect(satelliteIds).toEqual([]);
});
});
+
+describe("architectureToGraphology unclustered disc", () => {
+ it("draws the ungrouped files as one neutral hub outside the ranking", () => {
+ const arch: ArchitectureGraph = {
+ ...makeArch([makeArchNode({ community_id: 0 })]),
+ unclustered: { file_count: 72, files: ["README.md"] },
+ };
+ const g = architectureToGraphology(arch);
+ expect(g.hasNode(UNCLUSTERED_NODE_ID)).toBe(true);
+ expect(hubNodeId(UNCLUSTERED_COMMUNITY_ID)).toBe(UNCLUSTERED_NODE_ID);
+ const attrs = g.getNodeAttributes(UNCLUSTERED_NODE_ID);
+ expect(attrs.nodeType).toBe("hub");
+ expect(attrs.communityId).toBe(UNCLUSTERED_COMMUNITY_ID);
+ expect(attrs.memberCount).toBe(72);
+ // Past the outer ring, so the ranked hubs keep their positions.
+ const hub = g.getNodeAttributes(hubNodeId(0));
+ expect(Math.hypot(attrs.x, attrs.y)).toBeGreaterThan(Math.hypot(hub.x, hub.y));
+ });
+
+ it("draws nothing when there is nothing ungrouped", () => {
+ const g = architectureToGraphology({
+ ...makeArch([makeArchNode({ community_id: 0 })]),
+ unclustered: { file_count: 0, files: [] },
+ });
+ expect(g.hasNode(UNCLUSTERED_NODE_ID)).toBe(false);
+ });
+});
diff --git a/packages/ui/__tests__/graph/graph-community-panel.test.tsx b/packages/ui/__tests__/graph/graph-community-panel.test.tsx
index abf8ec1a4..bdac5ceb0 100644
--- a/packages/ui/__tests__/graph/graph-community-panel.test.tsx
+++ b/packages/ui/__tests__/graph/graph-community-panel.test.tsx
@@ -313,3 +313,36 @@ describe("GraphCommunityPanel truthfulness", () => {
expect(screen.getByText("82.0%")).toBeTruthy();
});
});
+
+describe("GraphCommunityPanel population and shape", () => {
+ it("reads conductance as the share that stays inside, and says what is hidden", () => {
+ render(
+ <GraphCommunityPanel
+ communityId={7}
+ community={{ ...sampleCommunity, conductance: 0.28, hidden_member_count: 393 }}
+ isLoading={false}
+ onClose={vi.fn()}
+ />,
+ );
+ expect(screen.getByText("Stays inside")).toBeTruthy();
+ expect(screen.getByText("72%")).toBeTruthy();
+ expect(screen.queryByText("Cohesion")).toBeNull();
+ expect(
+ screen.getByText("3 files, grouped automatically · 393 hidden by the file filter"),
+ ).toBeTruthy();
+ });
+
+ it("falls back to cohesion on an index without conductance", () => {
+ render(
+ <GraphCommunityPanel
+ communityId={7}
+ community={sampleCommunity}
+ isLoading={false}
+ onClose={vi.fn()}
+ />,
+ );
+ expect(screen.getByText("Cohesion")).toBeTruthy();
+ expect(screen.getByText("82.0%")).toBeTruthy();
+ expect(screen.queryByText("Stays inside")).toBeNull();
+ });
+});
diff --git a/packages/ui/__tests__/graph/graph-population-control.test.tsx b/packages/ui/__tests__/graph/graph-population-control.test.tsx
new file mode 100644
index 000000000..1e668b1d8
--- /dev/null
+++ b/packages/ui/__tests__/graph/graph-population-control.test.tsx
@@ -0,0 +1,54 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { GraphPopulationControl } from "../../src/graph/graph-population-control.js";
+import { PRODUCTION_ONLY } from "@repowise-dev/types/graph";
+
+const breakdown = {
+ total: 4104,
+ visible: 2427,
+ tests: 1398,
+ examples: 27,
+ docs: 293,
+};
+
+describe("GraphPopulationControl", () => {
+ it("summarises what is counted and offers each kind with its count", () => {
+ const onChange = vi.fn();
+ render(
+ <GraphPopulationControl
+ population={PRODUCTION_ONLY}
+ breakdown={breakdown}
+ onChange={onChange}
+ />,
+ );
+ const trigger = screen.getByRole("button", { name: /Files counted/ });
+ expect(trigger.textContent).toContain("2,427 of 4,104 files");
+
+ fireEvent.click(trigger);
+ expect(screen.getByText("1,398")).toBeTruthy();
+ fireEvent.click(screen.getByLabelText(/Tests/));
+ expect(onChange).toHaveBeenCalledWith({ tests: true, examples: false, docs: false });
+ });
+
+ it("says all files when nothing is hidden", () => {
+ render(
+ <GraphPopulationControl
+ population={{ tests: true, examples: true, docs: true }}
+ breakdown={{ ...breakdown, visible: 4104 }}
+ onChange={vi.fn()}
+ />,
+ );
+ expect(screen.getByRole("button", { name: /Files counted/ }).textContent).toContain(
+ "All 4,104 files",
+ );
+ });
+
+ it("degrades to labels without counts when the breakdown is absent", () => {
+ render(<GraphPopulationControl population={PRODUCTION_ONLY} onChange={vi.fn()} />);
+ const trigger = screen.getByRole("button", { name: /Files counted/ });
+ expect(trigger.textContent).toContain("Production files");
+ fireEvent.click(trigger);
+ expect(screen.getByLabelText(/Docs and config/)).toBeTruthy();
+ expect(screen.queryByText("293")).toBeNull();
+ });
+});
diff --git a/packages/ui/src/graph/graph-canvas-shell.tsx b/packages/ui/src/graph/graph-canvas-shell.tsx
index 4d7973a0b..e57ecebb4 100644
--- a/packages/ui/src/graph/graph-canvas-shell.tsx
+++ b/packages/ui/src/graph/graph-canvas-shell.tsx
@@ -120,7 +120,9 @@ export function GraphCanvasShell({
// still yields to the context menu and the help modal.
"absolute inset-x-0 bottom-0 z-[var(--z-dropdown)] flex max-h-[70%] flex-col overflow-hidden",
"rounded-t-xl border-t border-[var(--color-border-default)] bg-[var(--color-bg-surface)] shadow-xl shadow-black/20",
- "lg:static lg:max-h-none lg:rounded-none lg:border-t-0 lg:border-l lg:shadow-none",
+ // `h-0 min-h-full`: fill the row without contributing to its
+ // height, so a tall panel scrolls instead of stretching the canvas.
+ "lg:static lg:h-0 lg:min-h-full lg:max-h-none lg:rounded-none lg:border-t-0 lg:border-l lg:shadow-none",
)}
>
{rail}
diff --git a/packages/ui/src/graph/graph-community-panel.tsx b/packages/ui/src/graph/graph-community-panel.tsx
index 7cf07f912..b0c32bef0 100644
--- a/packages/ui/src/graph/graph-community-panel.tsx
+++ b/packages/ui/src/graph/graph-community-panel.tsx
@@ -96,6 +96,8 @@ export function GraphCommunityPanel({
// read as a summary.
<p className="text-[11px] text-[var(--color-text-secondary)]">
{community.member_count} files, grouped automatically
+ {(community.hidden_member_count ?? 0) > 0 &&
+ ` · ${community.hidden_member_count} hidden by the file filter`}
</p>
)}
</div>
@@ -352,13 +354,21 @@ function FactGrid({
),
tip: "Members named by a recorded architectural decision.",
},
- {
- label: "Cohesion",
- value: <FactValue>{(community.cohesion * 100).toFixed(1)}%</FactValue>,
- // "depend on", not "import": the edge set behind this is every file
- // dependency kind, so "import" would understate what counted.
- tip: "The share of possible file pairs in this group that actually depend on each other. It drops as a group grows, so it compares groups of similar size rather than a group against the repo.",
- },
+ // Conductance where the index has it; the old density is the fallback for
+ // an index that predates it, since it decays with size.
+ community.conductance != null
+ ? {
+ label: "Stays inside",
+ value: (
+ <FactValue>{Math.round((1 - community.conductance) * 100)}%</FactValue>
+ ),
+ tip: "The share of this group's file dependencies that stay inside it rather than reaching another group. Higher is tighter, and it does not fall as a group grows.",
+ }
+ : {
+ label: "Cohesion",
+ value: <FactValue>{(community.cohesion * 100).toFixed(1)}%</FactValue>,
+ tip: "The share of possible file pairs in this group that actually depend on each other. It drops as a group grows, so it compares groups of similar size rather than a group against the repo.",
+ },
];
if (owner) {
@@ -376,10 +386,11 @@ function FactGrid({
});
}
- // Cohesion is 1.0 for a single-file community by definition, so a one-file
- // group would show a perfect score beside a tooltip about pairs.
+ // A one-file group has no pairs and nothing inside to stay in.
const visible =
- community.member_count <= 1 ? cells.filter((c) => c.label !== "Cohesion") : cells;
+ community.member_count <= 1
+ ? cells.filter((c) => c.label !== "Cohesion" && c.label !== "Stays inside")
+ : cells;
return (
<dl className="grid grid-cols-2 border-y border-[var(--color-border-default)]">
diff --git a/packages/ui/src/graph/graph-flow.tsx b/packages/ui/src/graph/graph-flow.tsx
index 91d529036..f5b38f687 100644
--- a/packages/ui/src/graph/graph-flow.tsx
+++ b/packages/ui/src/graph/graph-flow.tsx
@@ -39,19 +39,26 @@ import { GraphContextMenu } from "./graph-context-menu";
import { GraphInspectionPanel } from "./graph-inspection-panel";
import { GraphFlowPanel } from "./graph-flow-panel";
import { GraphShortcutHelp } from "./graph-shortcut-help";
+import { GraphPopulationControl } from "./graph-population-control";
+import { GraphUnclusteredPanel } from "./graph-unclustered-panel";
import type {
GraphExport,
ExecutionFlows,
CommunitySummaryItem,
ArchitectureGraph,
CommunitySlice,
+ GraphPopulation,
} from "@repowise-dev/types/graph";
import { SigmaCanvas, type SigmaCanvasHandle } from "./sigma/sigma-canvas";
import {
fileGraphToGraphology,
fileGraphToGraphologyAsync,
} from "./sigma/graphology-adapter";
-import { architectureToGraphology, hubNodeId } from "./sigma/constellation-adapter";
+import {
+ architectureToGraphology,
+ hubNodeId,
+ UNCLUSTERED_COMMUNITY_ID,
+} from "./sigma/constellation-adapter";
import { computeRadialLayout } from "./sigma/radial-layout";
import { ELK_MAX_NODES, elkSkipReason } from "./sigma/use-elk-sigma-layout";
import type { SigmaNodeAttributes, SigmaEdgeAttributes } from "./sigma/types";
@@ -87,6 +94,11 @@ export interface GraphFlowProps {
* stubs. Fetched by the host in response to {@link onActiveCommunityChange}. */
communitySlice?: CommunitySlice | undefined;
isLoadingCommunitySlice?: boolean | undefined;
+ /** Which non-production files the community views count. Controlled by the
+ * host, which fetches with it. The control renders only when both are
+ * supplied. */
+ population?: GraphPopulation | undefined;
+ onPopulationChange?: ((next: GraphPopulation) => void) | undefined;
/** Repo name for the constellation core label. */
repoName?: string;
deadCodeGraph: GraphExport | undefined;
@@ -182,6 +194,8 @@ export function GraphFlow(props: GraphFlowProps) {
constellationGraph,
isLoadingConstellationGraph,
activeCommunity: controlledActiveCommunity,
+ population,
+ onPopulationChange,
onActiveCommunityChange,
communitySlice,
isLoadingCommunitySlice,
@@ -367,6 +381,11 @@ export function GraphFlow(props: GraphFlowProps) {
// unified single-click grammar (expansion is reserved for double-click).
const handleConstellationHubClick = useCallback(
(cid: number) => {
+ if (cid === UNCLUSTERED_COMMUNITY_ID) {
+ // Not a community: the host is not told, so it never fetches one.
+ setCommunityPanelId(cid);
+ return;
+ }
const nodeId = hubNodeId(cid);
setSelectedNodeId(nodeId);
sigmaRef.current?.focusNode(nodeId, HUB_FOCUS_RATIO);
@@ -911,6 +930,13 @@ export function GraphFlow(props: GraphFlowProps) {
if (selectedNodeId === nodeId) return;
if (nodeType === "hub" && displayGraph?.hasNode(nodeId)) {
const cid = displayGraph.getNodeAttribute(nodeId, "communityId");
+ // The "not grouped" disc is a list, not a community: it opens its panel
+ // without being selected, since selection dims everything it does not
+ // link to, which is everything.
+ if (cid === UNCLUSTERED_COMMUNITY_ID) {
+ setCommunityPanelId(cid);
+ return;
+ }
if (typeof cid === "number" && cid >= 0) {
setSelectedNodeId(nodeId);
sigmaRef.current?.focusNode(nodeId, HUB_FOCUS_RATIO);
@@ -1213,7 +1239,17 @@ export function GraphFlow(props: GraphFlowProps) {
)
: rail
? rail
- : communityPanelId !== null && renderCommunityPanel
+ : communityPanelId === UNCLUSTERED_COMMUNITY_ID && constellationGraph?.unclustered
+ ? (
+ <GraphUnclusteredPanel
+ unclustered={constellationGraph.unclustered}
+ onClose={() => setCommunityPanelId(null)}
+ fileHrefFor={fileHrefFor}
+ />
+ )
+ : communityPanelId !== null &&
+ communityPanelId !== UNCLUSTERED_COMMUNITY_ID &&
+ renderCommunityPanel
? renderCommunityPanel({
communityId: communityPanelId,
onClose: () => setCommunityPanelId(null),
@@ -1282,6 +1318,10 @@ export function GraphFlow(props: GraphFlowProps) {
`plus ${stubs} faded file${stubs === 1 ? "" : "s"} outside it that they reach`,
);
}
+ const hidden = communitySlice.hidden_member_count ?? 0;
+ if (hidden > 0) {
+ parts.push(`${hidden} more hidden by the file filter`);
+ }
return `${parts.join(", ")}.`;
})();
@@ -1314,6 +1354,13 @@ export function GraphFlow(props: GraphFlowProps) {
titleActions={
<div className="flex flex-wrap items-center justify-end gap-2">
{headerActions}
+ {population && onPopulationChange && (isConstellation || isInsideCommunity) && (
+ <GraphPopulationControl
+ population={population}
+ breakdown={constellationGraph?.population}
+ onChange={onPopulationChange}
+ />
+ )}
<GraphToolbar
viewMode={viewMode}
colorMode={colorMode}
@@ -1418,6 +1465,14 @@ export function GraphFlow(props: GraphFlowProps) {
graphTheme={graphTheme}
constellationEntries={isConstellation ? constellationLegend : undefined}
onConstellationHubClick={handleConstellationHubClick}
+ constellationUnclustered={
+ isConstellation && constellationGraph?.unclustered
+ ? {
+ count: constellationGraph.unclustered.file_count,
+ onClick: () => handleConstellationHubClick(UNCLUSTERED_COMMUNITY_ID),
+ }
+ : undefined
+ }
/>
{hasCanvasStatus && (
<div className="flex flex-wrap items-center gap-x-3 gap-y-1">
diff --git a/packages/ui/src/graph/graph-legend.tsx b/packages/ui/src/graph/graph-legend.tsx
index db950be9b..982368c08 100644
--- a/packages/ui/src/graph/graph-legend.tsx
+++ b/packages/ui/src/graph/graph-legend.tsx
@@ -134,6 +134,8 @@ interface GraphLegendProps {
| undefined;
/** Click a constellation row → focus that hub's camera. */
onConstellationHubClick?: ((communityId: number) => void) | undefined;
+ /** Files in no community, keyed as its own row outside the ranking. */
+ constellationUnclustered?: { count: number; onClick?: (() => void) | undefined } | undefined;
/**
* Name of the one community being drawn, when the canvas has been drilled
* into. Its presence selects the scoped reading of this key.
@@ -170,6 +172,7 @@ export const GraphLegend = memo(function GraphLegend({
graphTheme = "dark",
constellationEntries,
onConstellationHubClick,
+ constellationUnclustered,
scopeLabel,
sliceCounts,
scopeCommunityId,
@@ -225,6 +228,20 @@ export const GraphLegend = memo(function GraphLegend({
+{overflow} smaller not listed
</p>
)}
+ {constellationUnclustered && constellationUnclustered.count > 0 && (
+ <button
+ type="button"
+ onClick={constellationUnclustered.onClick}
+ className={rowClass}
+ title="Files with no dependency on the rest of the repo"
+ >
+ <Swatch color="var(--color-text-tertiary)" />
+ <span>Not grouped</span>
+ <span className="shrink-0 tabular-nums text-[10px] text-[var(--color-text-tertiary)]">
+ {constellationUnclustered.count}
+ </span>
+ </button>
+ )}
</div>
)}
</div>
diff --git a/packages/ui/src/graph/graph-population-control.tsx b/packages/ui/src/graph/graph-population-control.tsx
new file mode 100644
index 000000000..b923cc489
--- /dev/null
+++ b/packages/ui/src/graph/graph-population-control.tsx
@@ -0,0 +1,89 @@
+"use client";
+
+import { useState } from "react";
+import { ChevronDown, Filter } from "lucide-react";
+import { Popover, PopoverTrigger, PopoverContent } from "../ui/popover";
+import { formatNumber } from "../lib/format";
+import type { GraphPopulation, PopulationBreakdown } from "@repowise-dev/types/graph";
+
+const ROWS: { key: keyof GraphPopulation; label: string; count: keyof PopulationBreakdown }[] = [
+ { key: "tests", label: "Tests", count: "tests" },
+ { key: "examples", label: "Examples and benchmarks", count: "examples" },
+ { key: "docs", label: "Docs and config", count: "docs" },
+];
+
+/**
+ * Which files the community views count. Production is always in; the three
+ * toggles add the rest. The server recomputes sizes, ranking, labels and the
+ * health rollup over whatever is on, so this is a change to the data, not a
+ * paint filter.
+ */
+export function GraphPopulationControl({
+ population,
+ breakdown,
+ onChange,
+ className,
+}: {
+ population: GraphPopulation;
+ /** From the architecture payload; absent while it loads or in a scope that
+ * does not fetch it, in which case the rows show without counts. */
+ breakdown?: PopulationBreakdown | null | undefined;
+ onChange: (next: GraphPopulation) => void;
+ className?: string | undefined;
+}) {
+ const [open, setOpen] = useState(false);
+ const allOn = population.tests && population.examples && population.docs;
+ const summary = breakdown
+ ? allOn || breakdown.visible === breakdown.total
+ ? `All ${formatNumber(breakdown.total)} files`
+ : `${formatNumber(breakdown.visible)} of ${formatNumber(breakdown.total)} files`
+ : allOn
+ ? "All files"
+ : "Production files";
+
+ return (
+ <Popover open={open} onOpenChange={setOpen}>
+ <PopoverTrigger asChild>
+ <button
+ type="button"
+ aria-label={`Files counted: ${summary}`}
+ className={`inline-flex h-7 items-center gap-1.5 rounded-md border border-[var(--color-border-default)] px-2 text-xs text-[var(--color-text-secondary)] transition-colors hover:text-[var(--color-text-primary)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent-primary)] ${className ?? ""}`}
+ >
+ <Filter className="h-3 w-3" />
+ <span className="tabular-nums">{summary}</span>
+ <ChevronDown className="h-3 w-3" />
+ </button>
+ </PopoverTrigger>
+ <PopoverContent align="end" aria-label="Files counted" className="w-64 p-2">
+ <p className="px-1 pb-1.5 text-[11px] text-[var(--color-text-secondary)]">
+ Production code is always counted. Turning a kind on re-sizes and
+ re-ranks every group.
+ </p>
+ {ROWS.map((row) => {
+ const count = breakdown?.[row.count];
+ return (
+ <label
+ key={row.key}
+ className="flex cursor-pointer items-center justify-between gap-2 rounded px-1 py-1.5 text-xs text-[var(--color-text-primary)] hover:bg-[var(--color-bg-wash-hover)]"
+ >
+ <span className="flex items-center gap-2">
+ <input
+ type="checkbox"
+ checked={population[row.key]}
+ onChange={(e) => onChange({ ...population, [row.key]: e.target.checked })}
+ className="h-3.5 w-3.5 accent-[var(--color-accent-primary)]"
+ />
+ {row.label}
+ </span>
+ {typeof count === "number" && (
+ <span className="tabular-nums text-[11px] text-[var(--color-text-tertiary)]">
+ {formatNumber(count)}
+ </span>
+ )}
+ </label>
+ );
+ })}
+ </PopoverContent>
+ </Popover>
+ );
+}
diff --git a/packages/ui/src/graph/graph-unclustered-panel.tsx b/packages/ui/src/graph/graph-unclustered-panel.tsx
new file mode 100644
index 000000000..2817d5218
--- /dev/null
+++ b/packages/ui/src/graph/graph-unclustered-panel.tsx
@@ -0,0 +1,84 @@
+"use client";
+
+import { X } from "lucide-react";
+import { ScrollArea } from "../ui/scroll-area";
+import { truncatePath } from "../lib/format";
+import type { UnclusteredFiles } from "@repowise-dev/types/graph";
+
+/**
+ * The files no community claims. Almost all carry no dependency edge, so no
+ * import-based grouping can place them; they get a named home outside the
+ * ranking instead of an arbitrary attachment.
+ */
+export function GraphUnclusteredPanel({
+ unclustered,
+ onClose,
+ fileHrefFor,
+}: {
+ unclustered: UnclusteredFiles;
+ onClose: () => void;
+ fileHrefFor?: ((path: string) => string) | undefined;
+}) {
+ const files = unclustered.files ?? [];
+ const more = unclustered.file_count - files.length;
+ return (
+ <div className="flex h-full min-h-0 flex-col">
+ <div className="flex shrink-0 items-start justify-between gap-2 border-b border-[var(--color-border-default)] px-4 py-3">
+ <div className="min-w-0">
+ <p className="font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">
+ Not grouped
+ </p>
+ <p className="mt-0.5 text-sm font-medium text-[var(--color-text-primary)]">
+ {unclustered.file_count} file{unclustered.file_count === 1 ? "" : "s"} in no
+ community
+ </p>
+ <p className="text-[11px] text-[var(--color-text-secondary)]">
+ Nothing here imports or is imported by the rest of the repo, so the
+ grouping has nothing to place them by.
+ </p>
+ </div>
+ <button
+ type="button"
+ onClick={onClose}
+ aria-label="Close ungrouped files"
+ className="shrink-0 rounded p-1 transition-colors hover:bg-[var(--color-bg-elevated)]"
+ >
+ <X className="h-4 w-4 text-[var(--color-text-tertiary)]" />
+ </button>
+ </div>
+ <ScrollArea className="min-h-0 flex-1">
+ {/* `w-px min-w-full`: the scroll viewport lays its child out as a
+ table, which sizes to the longest path; this pins it to the rail. */}
+ <div className="w-px min-w-full space-y-1 px-4 py-3">
+ {files.map((path) => (
+ <div
+ key={path}
+ className="flex items-center rounded px-1.5 py-1 hover:bg-[var(--color-bg-elevated)]"
+ >
+ <div className="min-w-0 flex-1">
+ {fileHrefFor ? (
+ <a
+ href={fileHrefFor(path)}
+ title={path}
+ className="block truncate font-mono text-xs text-[var(--color-text-primary)] hover:text-[var(--color-accent-primary)] hover:underline"
+ >
+ {truncatePath(path)}
+ </a>
+ ) : (
+ <p title={path} className="truncate font-mono text-xs text-[var(--color-text-primary)]">
+ {truncatePath(path)}
+ </p>
+ )}
+ </div>
+ </div>
+ ))}
+ {more > 0 && (
+ <p className="px-1.5 pt-1 text-[11px] text-[var(--color-text-tertiary)]">
+ +{more} more, by rank
+ </p>
+ )}
+ </div>
+ </ScrollArea>
+ </div>
+ );
+}
diff --git a/packages/ui/src/graph/index.ts b/packages/ui/src/graph/index.ts
index 50380b03a..dce92fb22 100644
--- a/packages/ui/src/graph/index.ts
+++ b/packages/ui/src/graph/index.ts
@@ -17,6 +17,8 @@ export * from "./edge-provenance";
export * from "./context";
export * from "./elk-layout";
export * from "./graph-scope-controls";
+export * from "./graph-population-control";
+export * from "./graph-unclustered-panel";
export * from "./use-module-filter";
export * from "./sigma/sigma-canvas";
export * from "./sigma/types";
diff --git a/packages/ui/src/graph/sigma/constellation-adapter.ts b/packages/ui/src/graph/sigma/constellation-adapter.ts
index caf9ea2d2..3b8c04377 100644
--- a/packages/ui/src/graph/sigma/constellation-adapter.ts
+++ b/packages/ui/src/graph/sigma/constellation-adapter.ts
@@ -19,8 +19,13 @@ import type { SigmaNodeAttributes, SigmaEdgeAttributes } from "./types";
import { EDGE_COLORS } from "./constants";
import { computeRadialLayout, hubSizeFromMembers } from "./radial-layout";
+/** Pseudo community id of the "not grouped" disc. Never a real community. */
+export const UNCLUSTERED_COMMUNITY_ID = -2;
+export const UNCLUSTERED_NODE_ID = "__unclustered__";
+
/** Stable hub node id derived from the community id. */
export function hubNodeId(communityId: number): string {
+ if (communityId === UNCLUSTERED_COMMUNITY_ID) return UNCLUSTERED_NODE_ID;
return `__community__${communityId}`;
}
@@ -129,6 +134,33 @@ export function architectureToGraphology(
});
}
+ // The files no community claims, as one disc past the outer ring at six
+ // o'clock: outside the ranking, so it is not passed to the radial layout.
+ const unclustered = arch.unclustered;
+ if (unclustered && unclustered.file_count > 0) {
+ result.addNode(UNCLUSTERED_NODE_ID, {
+ x: layout.core.x,
+ y: layout.core.y + layout.ringRadii[2] * 1.18,
+ size: hubSizeFromMembers(unclustered.file_count),
+ color: PLACEHOLDER_HUB_COLOR,
+ label: "NOT GROUPED",
+ nodeType: "hub",
+ fullPath: "",
+ language: "",
+ communityId: UNCLUSTERED_COMMUNITY_ID,
+ pagerank: 0,
+ betweenness: 0,
+ isTest: false,
+ isEntryPoint: false,
+ hasDoc: false,
+ symbolCount: 0,
+ memberCount: unclustered.file_count,
+ forceLabel: true,
+ zIndex: 2,
+ originalColor: PLACEHOLDER_HUB_COLOR,
+ });
+ }
+
// Aggregated cross-community edges: thin plum spokes beneath the hubs.
const maxEdgeCount = arch.edges.reduce((m, e) => Math.max(m, e.edge_count), 1);
for (const edge of arch.edges) {
diff --git a/packages/ui/src/graph/sigma/use-sigma.ts b/packages/ui/src/graph/sigma/use-sigma.ts
index 23ec06c42..169d07d35 100644
--- a/packages/ui/src/graph/sigma/use-sigma.ts
+++ b/packages/ui/src/graph/sigma/use-sigma.ts
@@ -16,6 +16,7 @@ import {
languageColor,
} from "./constants";
import { resolveToken, useCommunityFamilies, useThemeVersion } from "../../shared/use-theme-tokens";
+import { UNCLUSTERED_COMMUNITY_ID } from "./constellation-adapter";
// ---- Color helpers (kept minimal — avoid regex in hot paths) ----
@@ -177,7 +178,10 @@ function makeDrawNodeHover(theme: VizPalette): NodeLabelDrawingFunction {
const lines: string[] = [];
if (extra.nodeType === "hub") {
const members = (extra.memberCount as number) ?? 0;
- lines.push(`${members} file${members === 1 ? "" : "s"} · ${docPct}% documented`);
+ // The "not grouped" disc carries no coverage figure.
+ const coverage =
+ typeof extra.docCoveragePct === "number" ? ` · ${docPct}% documented` : "";
+ lines.push(`${members} file${members === 1 ? "" : "s"}${coverage}`);
const langs = ((extra.languages as string[]) ?? []).slice(0, 3).join(", ");
if (langs) lines.push(langs);
} else {
@@ -550,6 +554,7 @@ export function useSigmaRenderer(options: UseSigmaOptions): UseSigmaReturn {
if (!graph || graph.order === 0) return;
const cm = options.colorMode;
const coreColor = resolveToken("--color-bg-inset", "#141415");
+ const unclusteredColor = resolveToken("--color-text-tertiary", "#7c7c82");
graph.updateEachNodeAttributes(
(_node, attrs) => {
let color: string;
@@ -557,7 +562,11 @@ export function useSigmaRenderer(options: UseSigmaOptions): UseSigmaReturn {
// the active colorMode — the radial view *is* the community view. The
// repo-core is a dark plum disc; its halo borrows the soft canvas dot.
if (attrs.nodeType === "hub") {
- const family = communityFamilies(attrs.communityId);
+ // The "not grouped" disc is no family: it is painted neutral.
+ const family =
+ attrs.communityId === UNCLUSTERED_COMMUNITY_ID
+ ? { hub: unclusteredColor, satellite: unclusteredColor }
+ : communityFamilies(attrs.communityId);
color = family.hub;
const haloColor = family.satellite || family.hub;
const labelInk = discInkFor(color);
diff --git a/packages/web/src/app/repos/[id]/architecture/page.tsx b/packages/web/src/app/repos/[id]/architecture/page.tsx
index 802ce22bf..1cc5ba643 100644
--- a/packages/web/src/app/repos/[id]/architecture/page.tsx
+++ b/packages/web/src/app/repos/[id]/architecture/page.tsx
@@ -28,6 +28,8 @@
* - `?module=` a path prefix the file scope is filtered to
* - `?community=` the community the file scope is drilled into. One axis with
* `?module=`: both narrow the file graph, so at most one is ever set.
+ * - `?show=` which non-production files the community views count
+ * (`tests,examples,docs`); absent means production only.
*
* `?view=` and `?viewMode=` used to encode the same axis twice — `view=explore`
* and `viewMode=full` both meant "the file graph", and they could disagree.
@@ -128,6 +130,7 @@ export default function ArchitecturePage({
const [, setSignal] = useQueryState("signal");
const [, setModule] = useQueryState("module");
const [, setCommunity] = useQueryState("community");
+ const [, setShow] = useQueryState("show");
const [, setFocus] = useQueryState("focus");
const [, setNode] = useQueryState("node");
@@ -169,10 +172,11 @@ export default function ArchitecturePage({
void setSignal(null);
void setModule(null);
void setCommunity(null);
+ void setShow(null);
void setNode(null);
}
},
- [setView, setFocus, setSignal, setModule, setCommunity, setNode],
+ [setView, setFocus, setSignal, setModule, setCommunity, setShow, setNode],
);
const handleScopeChange = useCallback(
diff --git a/packages/web/src/components/architecture/graph-view.tsx b/packages/web/src/components/architecture/graph-view.tsx
index b8b9bc2bd..73d20d5bf 100644
--- a/packages/web/src/components/architecture/graph-view.tsx
+++ b/packages/web/src/components/architecture/graph-view.tsx
@@ -15,6 +15,7 @@ import type { ModuleGroup } from "@repowise-dev/ui/graph/use-module-filter";
import { getGraph } from "@/lib/api/graph";
import { useCommunities } from "@/lib/hooks/use-graph";
import type { GraphExportResponse } from "@/lib/api/types";
+import { PRODUCTION_ONLY, type GraphPopulation } from "@repowise-dev/types/graph";
type ViewMode = "full" | "architecture" | "dead" | "hotfiles" | "unified";
type ColorMode = "language" | "community";
@@ -24,6 +25,17 @@ type Scope = "communities" | "files";
// falls through to the "community" default rather than erroring.
const VALID_COLOR_MODES = new Set<ColorMode>(["language", "community"]);
+/** `?show=tests,docs` ↔ the population flags. Absent or empty = production only. */
+const POPULATION_KEYS = ["tests", "examples", "docs"] as const;
+function parsePopulation(raw: string | null): GraphPopulation {
+ const on = new Set((raw ?? "").split(",").map((s) => s.trim()));
+ return { tests: on.has("tests"), examples: on.has("examples"), docs: on.has("docs") };
+}
+function serializePopulation(p: GraphPopulation): string | null {
+ const on = POPULATION_KEYS.filter((k) => p[k]);
+ return on.length ? on.join(",") : null;
+}
+
/** Scope + signal → the canvas's internal ViewMode. The overlay wins, because
* dead/hot are only ever drawn on the file graph. */
function toViewMode(scope: Scope, signal: string | null): ViewMode {
@@ -60,6 +72,17 @@ export function GraphView({
// every other param on this page, so Back leaves the page rather than
// stepping out of the community — the breadcrumb and Escape are the way up.
const [communityParam, setCommunityParam] = useQueryState("community");
+ const [showParam, setShowParam] = useQueryState("show");
+ const population = useMemo<GraphPopulation>(
+ () => (showParam ? parsePopulation(showParam) : PRODUCTION_ONLY),
+ [showParam],
+ );
+ const handlePopulationChange = useCallback(
+ (next: GraphPopulation) => {
+ void setShowParam(serializePopulation(next));
+ },
+ [setShowParam],
+ );
const [docNodeId, setDocNodeId] = useState<string | null>(null);
const [graphLimit, setGraphLimit] = useState<number | undefined>(undefined);
const [moduleGroups, setModuleGroups] = useState<ModuleGroup[]>([]);
@@ -78,7 +101,12 @@ export function GraphView({
? Number(communityParam)
: null;
- const { communities } = useCommunities(repoId);
+ // The whole-repo file graph is not population-filtered, so its labels and
+ // narrowing list are not either.
+ const { communities } = useCommunities(
+ repoId,
+ effectiveScope === "communities" || activeCommunity !== null ? population : undefined,
+ );
// Only the unfiltered file scope renders the capped `/api/graph` payload.
// The constellation, and each of the dead/hot signals, has its own endpoint —
@@ -275,6 +303,8 @@ export function GraphView({
activeModule={activeModule}
activeCommunity={activeCommunity}
onActiveCommunityChange={handleActiveCommunityChange}
+ population={population}
+ onPopulationChange={handlePopulationChange}
// Same value the banner reports, so the caption and the canvas can
// never disagree about how many files are drawn.
graphLimit={graphLimit}
diff --git a/packages/web/src/components/graph/graph-community-panel.tsx b/packages/web/src/components/graph/graph-community-panel.tsx
index 6fb964466..b7b1b944f 100644
--- a/packages/web/src/components/graph/graph-community-panel.tsx
+++ b/packages/web/src/components/graph/graph-community-panel.tsx
@@ -3,11 +3,12 @@
import { GraphCommunityPanel as GraphCommunityPanelShell } from "@repowise-dev/ui/graph/graph-community-panel";
import { fileEntityPath } from "@repowise-dev/ui/shared/entity";
import { useCommunityDetail } from "@/lib/hooks/use-graph";
-import type { CommunityDetail } from "@repowise-dev/types/graph";
+import type { CommunityDetail, GraphPopulation } from "@repowise-dev/types/graph";
interface GraphCommunityPanelWrapperProps {
repoId: string;
communityId: number;
+ population?: GraphPopulation | undefined;
onClose: () => void;
onEnterCommunity?: (() => void) | undefined;
onNeighborSelect?: ((communityId: number) => void) | undefined;
@@ -16,11 +17,12 @@ interface GraphCommunityPanelWrapperProps {
export function GraphCommunityPanel({
repoId,
communityId,
+ population,
onClose,
onEnterCommunity,
onNeighborSelect,
}: GraphCommunityPanelWrapperProps) {
- const { community, isLoading } = useCommunityDetail(repoId, communityId);
+ const { community, isLoading } = useCommunityDetail(repoId, communityId, population);
return (
<GraphCommunityPanelShell
diff --git a/packages/web/src/components/graph/graph-flow.tsx b/packages/web/src/components/graph/graph-flow.tsx
index 295ecdc9d..cd931e454 100644
--- a/packages/web/src/components/graph/graph-flow.tsx
+++ b/packages/web/src/components/graph/graph-flow.tsx
@@ -25,6 +25,7 @@ import type {
CommunitySummaryItem,
ArchitectureGraph,
CommunitySlice,
+ GraphPopulation,
} from "@repowise-dev/types/graph";
type ViewMode = "full" | "architecture" | "dead" | "hotfiles" | "unified";
@@ -40,6 +41,10 @@ export interface GraphFlowProps {
/** Controlled drill-down — the page owns it via `?community=`. */
activeCommunity?: number | null;
onActiveCommunityChange?: (communityId: number | null) => void;
+ /** Which non-production files the community views count — the page owns it
+ * via `?show=`. */
+ population?: GraphPopulation | undefined;
+ onPopulationChange?: ((next: GraphPopulation) => void) | undefined;
/** Node cap for the full-graph fetch, stepped up by the truncation banner.
* Must be the SAME value the banner is reporting: this and the banner's own
* fetch share an SWR key, so a mismatch means the caption describes a
@@ -80,6 +85,8 @@ export function GraphFlow({
activeModule,
activeCommunity,
onActiveCommunityChange,
+ population,
+ onPopulationChange,
graphLimit,
onModuleGroupsChange,
initialColorMode,
@@ -116,7 +123,7 @@ export function GraphFlow({
);
// Constellation community super-graph — only fetched for the radial scope.
const { graph: constellationGraph, isLoading: constellationLoading } =
- useArchitectureCommunityGraph(viewMode === "architecture" ? repoId : null);
+ useArchitectureCommunityGraph(viewMode === "architecture" ? repoId : null, population);
const { graph: deadGraph, isLoading: deadLoading } = useDeadCodeGraph(
viewMode === "dead" ? repoId : null,
);
@@ -128,10 +135,11 @@ export function GraphFlow({
const { slice: communitySlice, isLoading: sliceLoading } = useCommunitySlice(
viewMode !== "architecture" && activeCommunity != null ? repoId : null,
activeCommunity ?? null,
+ population,
);
const { repo } = useRepo(repoId);
const resolvedRepoName = repoName ?? repo?.name;
- const { communities } = useCommunities(repoId);
+ const { communities } = useCommunities(repoId, population);
// File-level only (the constellation has no file nodes), and only once the
// panel that reads them has been opened.
const { flows: executionFlowsData } = useExecutionFlows(
@@ -156,6 +164,8 @@ export function GraphFlow({
isLoadingCommunitySlice={sliceLoading}
activeCommunity={activeCommunity}
onActiveCommunityChange={onActiveCommunityChange}
+ population={population}
+ onPopulationChange={onPopulationChange}
{...(resolvedRepoName ? { repoName: resolvedRepoName } : {})}
deadCodeGraph={deadGraph as GraphExport | undefined}
isLoadingDeadCodeGraph={deadLoading}
@@ -213,6 +223,7 @@ export function GraphFlow({
<GraphCommunityPanel
repoId={repoId}
communityId={props.communityId}
+ population={population}
onClose={props.onClose}
onEnterCommunity={props.onEnterCommunity}
onNeighborSelect={props.onNeighborSelect}
diff --git a/packages/web/src/lib/hooks/use-graph.ts b/packages/web/src/lib/hooks/use-graph.ts
index b6517c76d..df6ad317f 100644
--- a/packages/web/src/lib/hooks/use-graph.ts
+++ b/packages/web/src/lib/hooks/use-graph.ts
@@ -16,6 +16,7 @@ import {
getHotFilesGraph,
getZoomMap,
} from "@/lib/api/graph";
+import type { GraphPopulation } from "@repowise-dev/types/graph";
import type {
ArchitectureGraphResponse,
CallersCalleesResponse,
@@ -31,6 +32,16 @@ import type {
const SWR_OPTS = { revalidateOnFocus: false, revalidateOnReconnect: false };
+/** The population flags as a key fragment and as query params. */
+function populationKey(p?: GraphPopulation): string {
+ return p ? `${+p.tests}${+p.examples}${+p.docs}` : "000";
+}
+function populationParams(p?: GraphPopulation) {
+ return p
+ ? { include_tests: p.tests, include_examples: p.examples, include_docs: p.docs }
+ : undefined;
+}
+
export function useZoomMap(
repoId: string | null,
params?: { max_depth?: number; focus?: string },
@@ -60,10 +71,13 @@ export function useGraph(repoId: string | null, limit?: number) {
* Conditional SWR: only fetched when a repoId is given (the wrapper gates it
* to the constellation scope).
*/
-export function useArchitectureCommunityGraph(repoId: string | null) {
+export function useArchitectureCommunityGraph(
+ repoId: string | null,
+ population?: GraphPopulation,
+) {
const { data, error, isLoading } = useSWR<ArchitectureGraphResponse>(
- repoId ? `arch-community:${repoId}` : null,
- () => getArchitecture(repoId!),
+ repoId ? `arch-community:${repoId}:${populationKey(population)}` : null,
+ () => getArchitecture(repoId!, 2, populationParams(population)),
SWR_OPTS,
);
return { graph: data, error, isLoading };
@@ -100,19 +114,25 @@ export function useHotFilesGraph(repoId: string | null, days = 30, limit = 25) {
// Graph Intelligence
// ---------------------------------------------------------------------------
-export function useCommunities(repoId: string | null) {
+export function useCommunities(repoId: string | null, population?: GraphPopulation) {
const { data, error, isLoading } = useSWR<CommunitySummaryItem[]>(
- repoId ? `communities:${repoId}` : null,
- () => getCommunities(repoId!),
+ repoId ? `communities:${repoId}:${populationKey(population)}` : null,
+ () => getCommunities(repoId!, populationParams(population)),
SWR_OPTS,
);
return { communities: data, error, isLoading };
}
-export function useCommunityDetail(repoId: string | null, communityId: number | null) {
+export function useCommunityDetail(
+ repoId: string | null,
+ communityId: number | null,
+ population?: GraphPopulation,
+) {
const { data, error, isLoading } = useSWR<CommunityDetailResponse>(
- repoId && communityId !== null ? `community:${repoId}:${communityId}` : null,
- () => getCommunityDetail(repoId!, communityId!),
+ repoId && communityId !== null
+ ? `community:${repoId}:${communityId}:${populationKey(population)}`
+ : null,
+ () => getCommunityDetail(repoId!, communityId!, populationParams(population)),
SWR_OPTS,
);
return { community: data, error, isLoading };
@@ -122,10 +142,16 @@ export function useCommunityDetail(repoId: string | null, communityId: number |
* The drill-down payload: one community's members plus the one-hop stubs that
* bound them. Conditional — no request until somebody enters a community.
*/
-export function useCommunitySlice(repoId: string | null, communityId: number | null) {
+export function useCommunitySlice(
+ repoId: string | null,
+ communityId: number | null,
+ population?: GraphPopulation,
+) {
const { data, error, isLoading } = useSWR<CommunitySliceResponse>(
- repoId && communityId != null ? `community-slice:${repoId}:${communityId}` : null,
- () => getCommunitySlice(repoId!, communityId!),
+ repoId && communityId != null
+ ? `community-slice:${repoId}:${communityId}:${populationKey(population)}`
+ : null,
+ () => getCommunitySlice(repoId!, communityId!, populationParams(population)),
SWR_OPTS,
);
return { slice: data, error, isLoading };
diff --git a/tests/unit/analysis/test_community_labels.py b/tests/unit/analysis/test_community_labels.py
index 1bc5d1752..7998f79b2 100644
--- a/tests/unit/analysis/test_community_labels.py
+++ b/tests/unit/analysis/test_community_labels.py
@@ -15,6 +15,8 @@ import networkx as nx
from repowise.core.analysis.communities import (
CommunityInfo,
+ _assign_tests_to_communities,
+ _conductance,
_deduplicate_labels,
_heuristic_label,
detect_file_communities,
@@ -115,6 +117,79 @@ class TestDetectFileCommunitiesLabels:
assert "ingestion" in joined and "web" in joined
+class TestRootFirstLabels:
+ def test_sub_label_follows_path_order(self):
+ # Frequency picks "ingestion" (in every path) as primary and "engine"
+ # as the sub-segment; the label must still read the way the paths nest.
+ paths = [f"engine/ingestion/r{i}.py" for i in range(4)] + [
+ "other/ingestion/z.py",
+ ]
+ assert _heuristic_label(paths, 0) == "engine/ingestion"
+
+ def test_repo_name_is_generic(self):
+ # "acme" sits under packages/*/src in half the paths, below the
+ # dominant-segment bar, so only the explicit repo name strips it.
+ ingest = [f"packages/core/src/acme/ingestion/m{i}.py" for i in range(6)]
+ web = [f"packages/web/components/w{i}.tsx" for i in range(6)]
+ edges = list(itertools.pairwise(ingest)) + list(itertools.pairwise(web))
+ _, info, _ = detect_file_communities(_graph(ingest + web, edges), repo_name="Acme")
+ labels = {ci.label for ci in info.values()}
+ assert "ingestion" in labels
+ for label in labels:
+ assert "acme" not in label.split("/")
+
+
+class TestTestAssignment:
+ def test_most_linked_community_wins(self):
+ # The test imports one file from community 0 and two from community 1.
+ # Alphabetical order would file it under community 0 ("a.py").
+ g = nx.DiGraph()
+ for p in ["src/a.py", "src/m.py", "src/n.py", "tests/test_x.py"]:
+ g.add_node(p, node_type="file")
+ for target in ["src/a.py", "src/m.py", "src/n.py"]:
+ g.add_edge("tests/test_x.py", target, edge_type="imports")
+ prod = {"src/a.py": 0, "src/m.py": 1, "src/n.py": 1}
+ assert _assign_tests_to_communities(["tests/test_x.py"], prod, g) == {
+ "tests/test_x.py": 1
+ }
+
+ def test_ties_break_on_lowest_community_id(self):
+ g = nx.DiGraph()
+ for p in ["src/a.py", "src/b.py", "tests/test_x.py"]:
+ g.add_node(p, node_type="file")
+ g.add_edge("tests/test_x.py", "src/b.py", edge_type="imports")
+ g.add_edge("tests/test_x.py", "src/a.py", edge_type="imports")
+ prod = {"src/a.py": 2, "src/b.py": 1}
+ assert _assign_tests_to_communities(["tests/test_x.py"], prod, g) == {
+ "tests/test_x.py": 1
+ }
+
+
+class TestConductance:
+ def test_cut_over_volume(self):
+ g = nx.Graph()
+ g.add_edges_from([("a", "b"), ("b", "c"), ("c", "x"), ("a", "y")])
+ # intra a-b, b-c (volume 4 counted from both ends); cut c-x, a-y.
+ assert _conductance(g, ["a", "b", "c"]) == round(2 / 6, 4)
+
+ def test_none_when_nothing_is_linked(self):
+ g = nx.Graph()
+ g.add_nodes_from(["a", "b"])
+ assert _conductance(g, ["a", "b"]) is None
+
+ def test_detection_reads_it_off_production_members(self):
+ prod = [f"src/p{i}.py" for i in range(4)]
+ g = _graph([*prod, "tests/test_p.py"], list(itertools.combinations(prod, 2)))
+ g.nodes["tests/test_p.py"]["is_test"] = True
+ g.add_edge("tests/test_p.py", "src/p0.py", edge_type="imports")
+ _, info, _ = detect_file_communities(g)
+ (ci,) = [c for c in info.values() if "src/p0.py" in c.members]
+ # One production community, all its edges internal: nothing leaves.
+ assert ci.conductance == 0.0
+ # Labelled from the production members, not the attached test.
+ assert ci.label != "tests"
+
+
class TestExampleSeparation:
"""Example trees are demoted alongside tests, not partitioned as production."""
diff --git a/tests/unit/server/services/test_graph_views.py b/tests/unit/server/services/test_graph_views.py
index c6ef9e63d..94aca7007 100644
--- a/tests/unit/server/services/test_graph_views.py
+++ b/tests/unit/server/services/test_graph_views.py
@@ -24,9 +24,11 @@ from repowise.server.schemas import (
CommunitySliceResponse,
)
from repowise.server.services.graph_views import (
+ Population,
build_architecture_graph,
build_community_slice,
edge_response,
+ neighbour_edge_counts,
)
@@ -170,7 +172,158 @@ async def test_build_community_slice_member_limit_truncates(async_session, tmp_p
)
assert payload.truncated is True
- assert payload.member_count == 1
+ # The true visible size, so the banner can say "1 most connected of 2".
+ assert payload.member_count == 2
+ assert [n.node_id for n in payload.nodes if not n.is_boundary] == ["src/a.py"]
+
+
+async def _seed_mixed_population(session, tmp_path) -> str:
+ """Community 0: two production files and three tests; community 1: one
+ production file, one test, one doc; community 2: a test-only pair."""
+ repo = await upsert_repository(session, name="mixed", local_path=str(tmp_path))
+ nodes = [
+ ("src/a.py", 0, 0.9, False),
+ ("src/b.py", 0, 0.5, False),
+ ("tests/test_a.py", 0, 0.95, True),
+ ("tests/test_b.py", 0, 0.4, True),
+ ("tests/test_c.py", 0, 0.3, True),
+ ("src/c.py", 1, 0.6, False),
+ ("tests/test_d.py", 1, 0.2, True),
+ ("docs/guide.md", 1, 0.1, False),
+ ("tests/fixtures/x.py", 2, 0.1, True),
+ ("tests/fixtures/y.py", 2, 0.1, True),
+ # An unresolved import, stored as a file row: never a member.
+ ("external:pytest", 0, 0.99, False),
+ ]
+ await batch_upsert_graph_nodes(
+ session,
+ repo.id,
+ [
+ {
+ "node_id": path,
+ "node_type": "file",
+ "language": "python",
+ "pagerank": pr,
+ "community_id": cid,
+ "is_test": is_test,
+ "community_meta_json": json.dumps(
+ {"label": f"c{cid}", "cohesion": 0.1, "conductance": 0.25}
+ ),
+ }
+ for path, cid, pr, is_test in nodes
+ ],
+ )
+ await batch_upsert_graph_edges(
+ session,
+ repo.id,
+ [
+ {"source_node_id": "src/a.py", "target_node_id": "src/b.py"},
+ {"source_node_id": "src/a.py", "target_node_id": "src/c.py"},
+ {"source_node_id": "tests/test_a.py", "target_node_id": "src/a.py"},
+ {"source_node_id": "tests/test_a.py", "target_node_id": "src/c.py"},
+ {"source_node_id": "src/b.py", "target_node_id": "tests/test_d.py"},
+ ],
+ )
+ await session.flush()
+ return repo.id
+
+
+async def test_architecture_graph_counts_production_only_by_default(async_session, tmp_path):
+ repo_id = await _seed_mixed_population(async_session, tmp_path)
+
+ view = await build_architecture_graph(async_session, repo_id, min_members=1)
+
+ by_cid = {n.community_id: n for n in view.nodes}
+ # The test-only community is not drawn at all.
+ assert set(by_cid) == {0, 1}
+ assert by_cid[0].member_count == 2
+ assert by_cid[0].hidden_member_count == 3
+ # The top file is the top *visible* file, not the higher-ranked test.
+ assert by_cid[0].top_file == "src/a.py"
+ assert by_cid[0].conductance == 0.25
+ assert by_cid[1].member_count == 1
+ assert by_cid[1].hidden_member_count == 2
+ # Cross edges count only visible endpoints: a->c stays, b->test_d goes.
+ assert [(e.source, e.target, e.edge_count) for e in view.edges] == [(0, 1, 1)]
+ assert view.population is not None
+ assert (view.population.total, view.population.visible) == (10, 3)
+ assert (view.population.tests, view.population.docs) == (6, 1)
+ assert view.population.include_tests is False
+
+
+async def test_architecture_graph_population_flags_change_the_counts(async_session, tmp_path):
+ repo_id = await _seed_mixed_population(async_session, tmp_path)
+
+ view = await build_architecture_graph(
+ async_session,
+ repo_id,
+ min_members=1,
+ population=Population(include_tests=True, include_docs=True),
+ )
+
+ by_cid = {n.community_id: n for n in view.nodes}
+ assert set(by_cid) == {0, 1, 2}
+ assert by_cid[0].member_count == 5
+ assert by_cid[0].hidden_member_count == 0
+ assert by_cid[0].top_file == "tests/test_a.py"
+ assert by_cid[1].member_count == 3
+ assert {(e.source, e.target, e.edge_count) for e in view.edges} == {(0, 1, 3)}
+ assert view.population is not None
+ assert view.population.visible == 10
+ assert view.population.include_tests is True
+
+
+async def test_architecture_graph_names_the_unclustered(async_session, tmp_path):
+ repo_id = await _seed_mixed_population(async_session, tmp_path)
+
+ view = await build_architecture_graph(async_session, repo_id, min_members=2)
+
+ # Community 1 has one visible file, so it is below the cut and unclustered.
+ assert [n.community_id for n in view.nodes] == [0]
+ assert view.unclustered is not None
+ assert view.unclustered.file_count == 1
+ assert view.unclustered.files == ["src/c.py"]
+
+
+async def test_community_slice_filters_members_and_boundary(async_session, tmp_path):
+ repo_id = await _seed_mixed_population(async_session, tmp_path)
+
+ payload = await build_community_slice(async_session, repo_id, community_id=0)
+
+ by_id = {n.node_id: n for n in payload.nodes}
+ members = {k for k, n in by_id.items() if not n.is_boundary}
+ boundary = {k for k, n in by_id.items() if n.is_boundary}
+ assert members == {"src/a.py", "src/b.py"}
+ # test_d is a boundary neighbour but a test, so it is filtered like a member.
+ assert boundary == {"src/c.py"}
+ assert payload.member_count == 2
+ assert payload.hidden_member_count == 3
+
+ shown = await build_community_slice(
+ async_session, repo_id, community_id=0, population=Population(include_tests=True)
+ )
+ assert shown.member_count == 5
+ assert shown.hidden_member_count == 0
+ assert {n.node_id for n in shown.nodes if n.is_boundary} == {"src/c.py", "tests/test_d.py"}
+
+
+async def test_neighbour_edge_counts_respect_population(async_session, tmp_path):
+ repo_id = await _seed_mixed_population(async_session, tmp_path)
+ members = ["src/a.py", "src/b.py", "tests/test_a.py"]
+
+ hidden = await neighbour_edge_counts(async_session, repo_id, 0, members)
+ shown = await neighbour_edge_counts(
+ async_session, repo_id, 0, members, population=Population(include_tests=True)
+ )
+
+ # a->c and test_a->c reach community 1; b->test_d only counts with tests on.
+ assert hidden == [(1, 2)]
+ assert shown == [(1, 3)]
@pytest.mark.asyncio