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.

fix(generation): make wiki page ids stable across runs (#974)

Raghav Chamadiyad35c2005b9db
diff --git a/packages/core/src/repowise/core/analysis/communities.py b/packages/core/src/repowise/core/analysis/communities.py
index 499847baf..d607c1c6d 100644
--- a/packages/core/src/repowise/core/analysis/communities.py
+++ b/packages/core/src/repowise/core/analysis/communities.py
@@ -144,7 +144,8 @@ def _partition(G: nx.Graph) -> tuple[dict, str]:
log.warning("louvain_failed_using_directory_fallback", error=str(exc))
# Final fallback: directory-based grouping
- return _directory_fallback(list(G.nodes())), "directory"
+ # Sorted: _directory_fallback numbers directories in first-seen order.
+ return _directory_fallback(sorted(G.nodes())), "directory"
# ---------------------------------------------------------------------------
@@ -401,7 +402,7 @@ def _assign_tests_to_communities(
prod_assignment: dict[str, int],
graph: nx.DiGraph,
) -> dict[str, int]:
- """Assign each test file to the community of its most-imported production file.
+ """Assign each test file to the community of a production file it links to.
Falls back to a catch-all "tests" community when no import link exists.
"""
@@ -410,22 +411,14 @@ def _assign_tests_to_communities(
test_community_id = next_cid # shared fallback
for test_path in test_nodes:
- # Find which production file this test imports most
- best_prod: str | None = None
- best_weight = 0
- for _, target, d in graph.out_edges(test_path, data=True):
- if target in prod_assignment:
- w = 1
- best_prod = target if w > best_weight else best_prod
- best_weight = max(best_weight, w)
- for source, _, d in graph.in_edges(test_path, data=True):
- if source in prod_assignment:
- w = 1
- best_prod = source if w > best_weight else best_prod
- best_weight = max(best_weight, w)
-
- if best_prod is not None:
- result[test_path] = prod_assignment[best_prod]
+ # 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.
+ 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}
+
+ if linked:
+ result[test_path] = prod_assignment[min(linked)]
else:
result[test_path] = test_community_id
@@ -504,8 +497,12 @@ def detect_file_communities(
# Split oversized communities
split_lists = _split_oversized(undirected, raw_communities)
- # Re-index by size descending for deterministic ordering
- split_lists.sort(key=len, reverse=True)
+ # Re-index by size descending. The rank becomes the community id, which
+ # becomes a module page's target_path, so it has to be a total order:
+ # size alone leaves same-size communities in partition-iteration order,
+ # and Leiden (tried before Louvain) returns a partition dict ordered by
+ # its own internals rather than by the node list we sorted above.
+ split_lists.sort(key=lambda members: (-len(members), min(members)))
# Build production file assignment
prod_assignment: dict[str, int] = {}
@@ -573,10 +570,13 @@ def detect_symbol_communities(graph: nx.DiGraph) -> dict[str, int]:
Returns {symbol_id: community_id}.
"""
- symbol_nodes = [
+ # Sorted for the same reason detect_file_communities sorts its node list:
+ # insertion order seeds the partition, and the graph's is not stable
+ # between runs. This half was left unsorted when the file half was fixed.
+ symbol_nodes = sorted(
n for n, d in graph.nodes(data=True)
if d.get("node_type") == "symbol"
- ]
+ )
if not symbol_nodes:
return {}
@@ -586,15 +586,14 @@ def detect_symbol_communities(graph: nx.DiGraph) -> dict[str, int]:
undirected = nx.Graph()
undirected.add_nodes_from(symbol_nodes)
- for u, v, d in graph.edges(data=True):
- edge_type = d.get("edge_type")
- if (
- edge_type in _SYMBOL_COMMUNITY_EDGE_TYPES
- and u in symbol_set
- and v in symbol_set
- ):
- if not undirected.has_edge(u, v):
- undirected.add_edge(u, v)
+ community_edges = sorted(
+ (u, v)
+ for u, v, d in graph.edges(data=True)
+ if d.get("edge_type") in _SYMBOL_COMMUNITY_EDGE_TYPES
+ and u in symbol_set
+ and v in symbol_set
+ )
+ undirected.add_edges_from(community_edges)
# Separate isolates
connected = [n for n in undirected.nodes() if undirected.degree(n) > 0]
@@ -618,8 +617,9 @@ def detect_symbol_communities(graph: nx.DiGraph) -> dict[str, int]:
raw[next_cid] = [node]
next_cid += 1
- # Re-index by size descending
- ordered = sorted(raw.values(), key=len, reverse=True)
+ # Re-index by size descending, first member breaking ties (same total-order
+ # argument as detect_file_communities).
+ ordered = sorted(raw.values(), key=lambda members: (-len(members), min(members)))
result: dict[str, int] = {}
for cid, members in enumerate(ordered):
for node in members:
diff --git a/packages/core/src/repowise/core/generation/context/assembler.py b/packages/core/src/repowise/core/generation/context/assembler.py
index a1eb25225..51a7e4cd4 100644
--- a/packages/core/src/repowise/core/generation/context/assembler.py
+++ b/packages/core/src/repowise/core/generation/context/assembler.py
@@ -424,8 +424,11 @@ class ContextAssembler:
decision_records: list[dict] | None = None,
) -> RepoOverviewContext:
"""Assemble context for the repo_overview template."""
- # Top files sorted by PageRank descending
- sorted_pr = sorted(pagerank.items(), key=lambda x: x[1], reverse=True)
+ # Top files sorted by PageRank descending, path breaking ties. Leaf
+ # files share a PageRank in bulk, and dict order here is graph
+ # insertion order, so without the tiebreak the overview's top-file
+ # list is a different list on every run.
+ sorted_pr = sorted(pagerank.items(), key=lambda x: (-x[1], x[0]))
top_files = [
_TopFile(path=p, score=s)
for p, s in sorted_pr[:_MAX_TOP_FILES]
@@ -449,7 +452,9 @@ class ContextAssembler:
"cohesion": round(ci.cohesion, 2),
}
)
- communities_list.sort(key=lambda c: c["size"], reverse=True)
+ # Id, not label: two same-size communities can carry the same
+ # label, so the label is not a total order.
+ communities_list.sort(key=lambda c: (-c["size"], c["id"]))
communities_list = communities_list[:10]
except Exception:
pass
@@ -500,27 +505,41 @@ class ContextAssembler:
max_diagram_nodes = 50
max_diagram_edges = 200
- # Top-N nodes by PageRank (exclude external nodes)
+ # Top-N nodes by PageRank (exclude external nodes). Path breaks the
+ # tie, otherwise which 50 nodes make the cut changes between runs and
+ # the diagram is not comparable to the one it replaces.
top_nodes = set(
p
- for p, _ in sorted(pagerank.items(), key=lambda x: x[1], reverse=True)[
+ for p, _ in sorted(pagerank.items(), key=lambda x: (-x[1], str(x[0])))[
:max_diagram_nodes
]
if not str(p).startswith("external:")
)
nodes = sorted(top_nodes)
- # Only edges between selected nodes
- edges = [(src, dst) for src, dst in graph.edges() if src in top_nodes and dst in top_nodes][
- :max_diagram_edges
- ]
+ # Only edges between selected nodes. Ranked by the endpoints' PageRank
+ # rather than alphabetically: the cap bites on dense repos, and a plain
+ # sort would fill all 200 slots from whichever package sorts first and
+ # draw nothing from the rest of the graph. Path breaks the tie.
+ edges = sorted(
+ ((src, dst) for src, dst in graph.edges() if src in top_nodes and dst in top_nodes),
+ key=lambda e: (
+ -pagerank.get(e[0], 0.0),
+ -pagerank.get(e[1], 0.0),
+ str(e[0]),
+ str(e[1]),
+ ),
+ )[:max_diagram_edges]
# Community → members mapping (top-10 communities, cap members to 5)
raw_communities: dict[int, list[str]] = {}
for path, cid in community.items():
if not path.startswith("external:"):
raw_communities.setdefault(cid, []).append(path)
- comm_sorted = sorted(raw_communities.items(), key=lambda x: len(x[1]), reverse=True)[:10]
+ comm_sorted = sorted(
+ ((cid, sorted(members)) for cid, members in raw_communities.items()),
+ key=lambda x: (-len(x[1]), x[0]),
+ )[:10]
communities: dict[int, list[str]] = {cid: members[:5] for cid, members in comm_sorted}
# SCC groups (only non-singleton)
diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.py
index 1c44d80ad..d3da3b625 100644
--- a/packages/core/src/repowise/core/generation/models.py
+++ b/packages/core/src/repowise/core/generation/models.py
@@ -295,6 +295,24 @@ def compute_page_id(page_type: str, target_path: str) -> str:
return f"{page_type}:{target_path}"
+def scc_page_slug(members: list[str]) -> str:
+ """Return the ``target_path`` for a cycle's ``scc_page``, keyed by contents.
+
+ An SCC has no name of its own, so the page id used to be the component's
+ position in the list the graph layer handed over. That position moved
+ whenever the cycle set changed, or (before the graph layer sorted its
+ components) between two runs at the same commit. A moved id means the
+ update path deletes and recreates the page instead of updating it, losing
+ its history.
+
+ Hashing the sorted member paths ties the id to the one thing that actually
+ identifies the cycle. It survives a re-ordering, an unrelated cycle
+ appearing or disappearing, and a change of detection algorithm.
+ """
+ digest = hashlib.sha256("\n".join(sorted(members)).encode("utf-8")).hexdigest()
+ return f"scc-{digest[:12]}"
+
+
def _parse_datetime(ts: str) -> datetime:
"""Parse an ISO-8601 UTC timestamp to a timezone-aware datetime."""
ts = ts.replace("Z", "+00:00")
diff --git a/packages/core/src/repowise/core/generation/page_generator/helpers.py b/packages/core/src/repowise/core/generation/page_generator/helpers.py
index 1a0b65f74..155a8a275 100644
--- a/packages/core/src/repowise/core/generation/page_generator/helpers.py
+++ b/packages/core/src/repowise/core/generation/page_generator/helpers.py
@@ -173,7 +173,12 @@ def _select_clone_representatives(
for members in clusters.values():
if len(members) < min_cluster_size:
continue
- members.sort(key=lambda p: pagerank.get(p.file_info.path, 0.0), reverse=True)
+ # Near-clones usually share a PageRank (often 0.0), so the path breaks
+ # the tie. Without it the survivor of each cluster changes between
+ # runs, and with it which file gets a page at all.
+ members.sort(
+ key=lambda p: (-pagerank.get(p.file_info.path, 0.0), p.file_info.path)
+ )
for loser in members[1:]:
drop.add(loser.file_info.path)
return drop
diff --git a/packages/core/src/repowise/core/generation/selection/selector.py b/packages/core/src/repowise/core/generation/selection/selector.py
index cf299382e..72dbdedd9 100644
--- a/packages/core/src/repowise/core/generation/selection/selector.py
+++ b/packages/core/src/repowise/core/generation/selection/selector.py
@@ -16,6 +16,7 @@ import structlog
from repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTRY
+from ..models import scc_page_slug
from ..tour import DEFAULT_MAX_LANDMARKS, tour_landmark_paths
from .budget import (
BucketAllocation,
@@ -225,7 +226,7 @@ def _build_file_candidates(
)
if s > 0.0:
scored.append((s, path))
- scored.sort(key=lambda x: x[0], reverse=True)
+ scored.sort(key=lambda x: (-x[0], x[1]))
return scored
@@ -243,7 +244,7 @@ def _build_symbol_candidates(
s = score_symbol(sym, file_pr, max_pr)
if s > 0.0:
scored.append((s, (p.file_info.path, sym.name)))
- scored.sort(key=lambda x: x[0], reverse=True)
+ scored.sort(key=lambda x: (-x[0], x[1]))
# A spotlight page is keyed by ``(file_path, symbol_name)``, but one file
# can declare that pair twice: two classes in the same Java file each
# with a ``toString``, two Rust impl blocks each with a ``new``. Left in,
@@ -385,13 +386,13 @@ def _build_module_groups(inputs: SelectionInputs) -> list[tuple[float, ModuleGro
key=key,
display=group_display.get(key, key),
language=group_lang.get(key, "unknown"),
- file_paths=tuple(p.file_info.path for p in files),
+ file_paths=tuple(sorted(p.file_info.path for p in files)),
label=group_label.get(key),
cohesion=group_cohesion.get(key),
),
)
)
- scored.sort(key=lambda x: x[0], reverse=True)
+ scored.sort(key=lambda x: (-x[0], x[1].key))
return scored
@@ -401,7 +402,7 @@ def _build_api_candidates(inputs: SelectionInputs) -> list[tuple[float, str]]:
if not p.file_info.is_api_contract:
continue
scored.append((score_api_contract(p), p.file_info.path))
- scored.sort(key=lambda x: x[0], reverse=True)
+ scored.sort(key=lambda x: (-x[0], x[1]))
return scored
@@ -411,7 +412,7 @@ def _build_infra_candidates(inputs: SelectionInputs) -> list[tuple[float, str]]:
if not _is_infra_file(p):
continue
scored.append((score_infra(p), p.file_info.path))
- scored.sort(key=lambda x: x[0], reverse=True)
+ scored.sort(key=lambda x: (-x[0], x[1]))
return scored
@@ -419,13 +420,15 @@ def _build_scc_candidates(
inputs: SelectionInputs,
) -> list[tuple[float, tuple[str, list[str]]]]:
scored: list[tuple[float, tuple[str, list[str]]]] = []
- for i, scc in enumerate(inputs.sccs):
- files = list(scc)
+ for scc in inputs.sccs:
+ files = sorted(scc)
s = score_scc(cycle_size=len(files))
if s <= 0.0:
continue
- scored.append((s, (f"scc-{i}", sorted(files))))
- scored.sort(key=lambda x: x[0], reverse=True)
+ scored.append((s, (scc_page_slug(files), files)))
+ # Tie-break on the slug: score alone leaves equal-sized cycles in list
+ # order, and the page-id set must not depend on how they got there.
+ scored.sort(key=lambda x: (-x[0], x[1][0]))
return scored
diff --git a/packages/core/src/repowise/core/ingestion/graph/_betweenness.py b/packages/core/src/repowise/core/ingestion/graph/_betweenness.py
index 4a87ac289..dac56324c 100644
--- a/packages/core/src/repowise/core/ingestion/graph/_betweenness.py
+++ b/packages/core/src/repowise/core/ingestion/graph/_betweenness.py
@@ -134,7 +134,12 @@ def betweenness_centrality_fast(
log.warning("betweenness_parallel_unavailable", reason="networkx internals moved")
return nx.betweenness_centrality(g, normalized=normalized)
- nodes = list(g)
+ # Sorted, not graph order: the node numbering fixes the order the partial
+ # sums are accumulated in, and float addition is not associative. Graph
+ # insertion order varies between runs, so an unsorted numbering shifts
+ # scores in the last ULP, which is enough to flip every downstream
+ # tie-break that ranks on betweenness.
+ nodes = sorted(g)
index = {node: i for i, node in enumerate(nodes)}
edges = [(index[u], index[v]) for u, v in g.edges()]
diff --git a/packages/core/src/repowise/core/ingestion/graph/_centrality_cache.py b/packages/core/src/repowise/core/ingestion/graph/_centrality_cache.py
index 3245921bd..4eb1d2baa 100644
--- a/packages/core/src/repowise/core/ingestion/graph/_centrality_cache.py
+++ b/packages/core/src/repowise/core/ingestion/graph/_centrality_cache.py
@@ -33,7 +33,11 @@ import structlog
log = structlog.get_logger(__name__)
-_CACHE_VERSION = 1
+# Bumped to 2 when betweenness was made order-independent: the signature keys
+# on graph structure only, so a warm cache would keep serving the old,
+# insertion-order-dependent values and two installs at the same commit would
+# still disagree.
+_CACHE_VERSION = 2
_CACHE_FILENAME = "centrality_cache.pkl"
__all__ = ["CentralityCache", "subgraph_signature"]
diff --git a/packages/core/src/repowise/core/ingestion/graph/_metrics.py b/packages/core/src/repowise/core/ingestion/graph/_metrics.py
index b01d805a9..d64be7441 100644
--- a/packages/core/src/repowise/core/ingestion/graph/_metrics.py
+++ b/packages/core/src/repowise/core/ingestion/graph/_metrics.py
@@ -57,7 +57,11 @@ class MetricsMixin:
cd = self.community_detection()
ind = self.in_degree()
outd = self.out_degree()
- nodes = set(pr) | set(bc) | set(cd) | set(ind) | set(outd)
+ # Sorted: this dict's order becomes the graph_metrics row order, which
+ # load_metrics_from_sql then replays into the metric caches. Set
+ # iteration order would carry a run's hash seed into the next run's
+ # rankings.
+ nodes = sorted(set(pr) | set(bc) | set(cd) | set(ind) | set(outd))
return {
n: {
"pagerank": pr.get(n, 0.0),
@@ -135,8 +139,20 @@ class MetricsMixin:
# ------------------------------------------------------------------
def strongly_connected_components(self) -> list[frozenset[str]]:
- """Return SCCs as a list of frozensets."""
- return [frozenset(scc) for scc in nx.strongly_connected_components(self.file_subgraph())]
+ """Return SCCs as a list of frozensets, in a run-stable order.
+
+ NetworkX yields components in graph-iteration order, and the graph's
+ node insertion order varies between runs (git-indexer threads finish
+ in whatever order they finish). Callers that index into this list, such
+ as the wiki's SCC page ids and the repo-overview cycle listing, would
+ otherwise name the same cycle differently on two runs at the same
+ HEAD. Sorting by size then by first member fixes the order to
+ something that depends only on the component contents.
+ """
+ return sorted(
+ (frozenset(scc) for scc in nx.strongly_connected_components(self.file_subgraph())),
+ key=lambda scc: (-len(scc), min(scc)),
+ )
def pagerank(self, alpha: float = 0.85) -> dict[str, float]:
"""Return PageRank scores for file nodes only (cached)."""
@@ -293,10 +309,21 @@ class MetricsMixin:
if n > _LARGE_REPO_THRESHOLD:
k = min(500, n)
# Seeded: k-sampling is the one randomized kernel left in the
- # pipeline — unseeded it made every large-repo index emit a
+ # pipeline. Unseeded it made every large-repo index emit a
# different betweenness ranking (typst's entry-point order
# flapped between runs).
- values = nx.betweenness_centrality(g, k=k, normalized=True, seed=42)
+ #
+ # The seed alone is not enough. NetworkX samples from
+ # ``list(G.nodes())``, so a fixed seed over a population in a
+ # different order still draws a different 500 nodes, and that is a
+ # different ranking rather than a rounding difference. Re-inserting
+ # the nodes in sorted order is what makes the sample reproducible.
+ # The copy costs one pass over a graph we are about to run 500
+ # shortest-path trees on.
+ ordered = nx.DiGraph() if g.is_directed() else nx.Graph()
+ ordered.add_nodes_from(sorted(g.nodes()))
+ ordered.add_edges_from(g.edges())
+ values = nx.betweenness_centrality(ordered, k=k, normalized=True, seed=42)
else:
from ._betweenness import betweenness_centrality_fast
@@ -377,7 +404,14 @@ class MetricsMixin:
def _build_scc_map(self) -> dict[str, int]:
"""Assign a numeric SCC ID to each node."""
result: dict[str, int] = {}
- for scc_id, scc in enumerate(nx.strongly_connected_components(self.graph())):
+ # Sorted for the same reason as strongly_connected_components: the
+ # enumerate index is persisted as graph_nodes.scc_id, so it must not
+ # depend on graph insertion order.
+ components = sorted(
+ nx.strongly_connected_components(self.graph()),
+ key=lambda scc: (-len(scc), min(scc)),
+ )
+ for scc_id, scc in enumerate(components):
for node in scc:
result[node] = scc_id
return result
@@ -400,7 +434,10 @@ class MetricsMixin:
"""
out: dict[str, dict[str, Any]] = {}
- for scc_id, scc in enumerate(nx.strongly_connected_components(self.file_subgraph())):
+ # strongly_connected_components() is run-stably ordered, so the
+ # scc_id persisted on GraphNodeMembership names the same cycle across
+ # runs at the same HEAD.
+ for scc_id, scc in enumerate(self.strongly_connected_components()):
if len(scc) < 2:
continue
for node in scc:
diff --git a/packages/core/src/repowise/core/persistence/stores/in_process_graph_store.py b/packages/core/src/repowise/core/persistence/stores/in_process_graph_store.py
index 7bf6f7517..a6745a001 100644
--- a/packages/core/src/repowise/core/persistence/stores/in_process_graph_store.py
+++ b/packages/core/src/repowise/core/persistence/stores/in_process_graph_store.py
@@ -140,13 +140,17 @@ class InProcessGraphStore(GraphStore):
file_subgraph = self._file_subgraph().to_undirected()
mapping: dict[str, int] = {}
if file_subgraph.number_of_nodes():
- # Use NetworkX's greedy modularity communities — deterministic,
- # no external dependency, fine quality at this graph size.
+ # Use NetworkX's greedy modularity communities: no external
+ # dependency, fine quality at this graph size. Deterministic
+ # only for a fixed node order, which the graph does not
+ # guarantee, so sort the result before numbering it.
from networkx.algorithms.community import greedy_modularity_communities
- for cid, members in enumerate(
- greedy_modularity_communities(file_subgraph)
- ):
+ components = sorted(
+ (sorted(members) for members in greedy_modularity_communities(file_subgraph)),
+ key=lambda members: (-len(members), members[0] if members else ""),
+ )
+ for cid, members in enumerate(components):
for node in members:
mapping[node] = cid
self._communities_cache = mapping
diff --git a/tests/integration/test_generation_determinism.py b/tests/integration/test_generation_determinism.py
new file mode 100644
index 000000000..2ef92755c
--- /dev/null
+++ b/tests/integration/test_generation_determinism.py
@@ -0,0 +1,164 @@
+"""Two indexes of the same tree must produce the same page ids.
+
+The graph's node and edge insertion order is not stable between runs: files
+are parsed in a process pool and co-change edges arrive in git-indexer thread
+completion order. Anything that ranks on a score without a tiebreak, or turns
+a position in an unsorted list into an id, inherits that instability — and an
+id that moves means the update path deletes and recreates the page instead of
+updating it, losing its history.
+
+Running the pipeline twice in one process would not catch this: the hash seed
+is fixed for the life of the process, so both runs would see the same order.
+These tests feed the graph the same files in two different orders instead,
+which is what actually varies in production.
+
+Read this file as the end-to-end contract, not as the regression test. The
+sample repo is small enough that most of the individual ties never arise in
+it, so these pass with several of the fixes reverted. The discriminating
+cases live in ``tests/unit/generation/test_selection_determinism.py``, which
+constructs the ties deliberately.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import networkx as nx
+import pytest
+
+from repowise.core.generation.context_assembler import ContextAssembler
+from repowise.core.generation.models import GenerationConfig, scc_page_slug
+from repowise.core.generation.page_generator import PageGenerator
+from repowise.core.ingestion.graph import GraphBuilder
+from repowise.core.ingestion.models import PackageInfo, ParsedFile, RepoStructure
+from repowise.core.ingestion.parser import ASTParser
+from repowise.core.ingestion.traverser import FileTraverser
+from repowise.core.providers.llm.template import TemplateProvider
+
+SAMPLE_REPO = Path(__file__).parents[1] / "fixtures" / "sample_repo"
+
+
+def _parse_sample_repo() -> tuple[list[ParsedFile], dict[str, bytes]]:
+ traverser = FileTraverser(SAMPLE_REPO)
+ parser = ASTParser()
+ parsed_files: list[ParsedFile] = []
+ source_map: dict[str, bytes] = {}
+ for fi in traverser.traverse():
+ try:
+ src = Path(fi.abs_path).read_bytes()
+ parsed_files.append(parser.parse_file(fi, src))
+ source_map[fi.path] = src
+ except Exception:
+ pass
+ return parsed_files, source_map
+
+
+async def _generate(parsed_files, source_map, tmp, *, order) -> list:
+ """Generate the wiki with files added to the graph in *order*."""
+ builder = GraphBuilder()
+ for p in order:
+ builder.add_file(p)
+ builder.build()
+
+ packages = [
+ PackageInfo(
+ name=d.name, path=d.name, language="unknown", entry_points=[], manifest_file=""
+ )
+ for d in SAMPLE_REPO.iterdir()
+ if d.is_dir()
+ ]
+ repo_structure = RepoStructure(
+ is_monorepo=len(packages) > 1,
+ packages=packages,
+ root_language_distribution={"python": 0.7, "typescript": 0.3},
+ total_files=len(parsed_files),
+ total_loc=sum(
+ len(source_map.get(p.file_info.path, b"").splitlines()) for p in parsed_files
+ ),
+ entry_points=[],
+ )
+ config = GenerationConfig(deterministic=True, max_concurrency=3, jobs_dir=str(tmp / "jobs"))
+ generator = PageGenerator(TemplateProvider(), ContextAssembler(config), config)
+ return await generator.generate_all(
+ parsed_files, source_map, builder, repo_structure, "sample_repo", job_system=None
+ )
+
+
[email protected](scope="module")
+async def two_runs(tmp_path_factory):
+ """The same repo generated twice, with opposite graph insertion orders."""
+ tmp = tmp_path_factory.mktemp("gen_determinism")
+ parsed_files, source_map = _parse_sample_repo()
+ forward = await _generate(parsed_files, source_map, tmp / "a", order=parsed_files)
+ reverse = await _generate(
+ parsed_files, source_map, tmp / "b", order=list(reversed(parsed_files))
+ )
+ return forward, reverse
+
+
+class TestPageIdStability:
+ def test_runs_are_not_empty(self, two_runs):
+ forward, reverse = two_runs
+ assert forward and reverse
+
+ def test_page_id_sets_are_identical(self, two_runs):
+ """The headline contract: same tree, same commit, same page ids."""
+ forward, reverse = two_runs
+ assert {p.page_id for p in forward} == {p.page_id for p in reverse}
+
+ def test_target_paths_are_identical_per_page_type(self, two_runs):
+ """A weaker restatement that localises a failure to one page type."""
+ forward, reverse = two_runs
+
+ def by_type(pages):
+ out: dict[str, set[str]] = {}
+ for p in pages:
+ out.setdefault(p.page_type, set()).add(p.target_path)
+ return out
+
+ assert by_type(forward) == by_type(reverse)
+
+ def test_titles_are_identical(self, two_runs):
+ """Titles carry the derived ids (community numbers, cycle slugs), so a
+ stable id set with unstable titles still means a churning wiki."""
+ forward, reverse = two_runs
+ f = {p.page_id: p.title for p in forward}
+ r = {p.page_id: p.title for p in reverse}
+ assert f == r
+
+
+class TestSccSlug:
+ """SCC pages motivated the content-derived id. The sample repo has exactly
+ one cycle, so its slug is stable whatever the ordering does; these exercise
+ the slug's properties directly instead."""
+
+ def test_slug_ignores_member_order(self):
+ assert scc_page_slug(["b.py", "a.py"]) == scc_page_slug(["a.py", "b.py"])
+
+ def test_slug_distinguishes_different_cycles(self):
+ assert scc_page_slug(["a.py", "b.py"]) != scc_page_slug(["a.py", "c.py"])
+
+ def test_slug_is_page_id_shaped(self):
+ slug = scc_page_slug(["a.py", "b.py"])
+ assert slug.startswith("scc-")
+ # No path separator and no extension: the MCP answer layer uses that
+ # shape to keep graph ids out of agent-readable file targets.
+ assert "/" not in slug and "." not in slug
+
+ def test_component_order_survives_graph_insertion_order(self):
+ """GraphBuilder-level check that the component list itself is stable."""
+ from repowise.core.ingestion.graph._metrics import MetricsMixin
+
+ cycles = [("a.py", "b.py"), ("c.py", "d.py"), ("e.py", "f.py")]
+
+ def components(edge_order):
+ g = nx.DiGraph()
+ for u, v in edge_order:
+ g.add_edge(u, v)
+ g.add_edge(v, u)
+ holder = type("H", (MetricsMixin,), {})()
+ holder.graph = lambda: g
+ holder.file_subgraph = lambda: g
+ return [sorted(c) for c in holder.strongly_connected_components()]
+
+ assert components(cycles) == components(list(reversed(cycles)))
diff --git a/tests/unit/generation/test_selection_determinism.py b/tests/unit/generation/test_selection_determinism.py
new file mode 100644
index 000000000..f290d5763
--- /dev/null
+++ b/tests/unit/generation/test_selection_determinism.py
@@ -0,0 +1,164 @@
+"""Ties must be broken on content, not on iteration order.
+
+Scores collide constantly: every leaf file shares a PageRank, every isolate is
+a size-1 community, every same-length cycle scores the same. Python's sort is
+stable, so a score-only key leaves tied entries in whatever order they arrived
+in — and they arrive in graph insertion order, which varies between runs
+because parsing is pooled and co-change edges land in thread-completion order.
+
+The effect is not cosmetic: the allocator slices the sorted candidate list, so
+a shuffled tie changes *which pages get generated*, and a shuffled community
+list changes the ids that name module pages. These tests feed identical input
+in two different orders and require identical output.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+
+from repowise.core.analysis.communities import detect_file_communities
+from repowise.core.generation.models import GenerationConfig
+from repowise.core.generation.selection import SelectionInputs, select_pages
+
+from .test_selection_budget import FakeFileInfo, FakeParsedFile, FakeSymbol
+
+
+def _tied_repo(n_files: int = 60):
+ """A repo where every file scores identically — all ties, no signal."""
+ parsed = [
+ FakeParsedFile(
+ file_info=FakeFileInfo(path=f"pkg{i // 20}/module_{i:02d}.py"),
+ symbols=[FakeSymbol(name=f"handler_{i:02d}")],
+ )
+ for i in range(n_files)
+ ]
+ pagerank = {p.file_info.path: 0.5 for p in parsed}
+ betweenness = {p.file_info.path: 0.25 for p in parsed}
+ community = {p.file_info.path: 0 for p in parsed}
+ return parsed, pagerank, betweenness, community
+
+
+def _select(parsed, pagerank, betweenness, community):
+ cfg = GenerationConfig(coverage_pct=0.30)
+ return select_pages(
+ SelectionInputs(
+ parsed_files=parsed,
+ pagerank=pagerank,
+ betweenness=betweenness,
+ community=community,
+ community_info=None,
+ sccs=[],
+ git_meta_map=None,
+ config=cfg,
+ )
+ )
+
+
+class TestSelectionTies:
+ def test_file_pages_survive_input_reordering(self):
+ parsed, pr, bet, comm = _tied_repo()
+ forward = _select(parsed, pr, bet, comm)
+ reverse = _select(list(reversed(parsed)), pr, bet, comm)
+ assert set(forward.file_page_paths) == set(reverse.file_page_paths)
+
+ def test_symbol_spotlights_survive_input_reordering(self):
+ parsed, pr, bet, comm = _tied_repo()
+ forward = _select(parsed, pr, bet, comm)
+ reverse = _select(list(reversed(parsed)), pr, bet, comm)
+ assert set(forward.symbol_spotlights) == set(reverse.symbol_spotlights)
+
+ def test_budget_actually_drops_some_files(self):
+ """Guards the guard: if coverage took everything, the tests above
+ would pass no matter how the candidate list was ordered."""
+ parsed, pr, bet, comm = _tied_repo()
+ sel = _select(parsed, pr, bet, comm)
+ assert 0 < len(sel.file_page_paths) < len(parsed)
+
+
+class TestCommunityTies:
+ def _graph(self, edge_order):
+ g = nx.DiGraph()
+ for u, v in edge_order:
+ g.add_node(u, node_type="file", language="python")
+ g.add_node(v, node_type="file", language="python")
+ g.add_edge(u, v, edge_type="imports")
+ return g
+
+ def test_equal_sized_communities_get_stable_ids(self):
+ """Three disconnected pairs: identical size, so the id each pair gets
+ is decided entirely by the tiebreak. The community id is a module
+ page's target_path, so a shuffled id deletes and recreates the page."""
+ edges = [
+ ("alpha/a.py", "alpha/b.py"),
+ ("bravo/a.py", "bravo/b.py"),
+ ("charlie/a.py", "charlie/b.py"),
+ ]
+ forward, _, _ = detect_file_communities(self._graph(edges))
+ reverse, _, _ = detect_file_communities(self._graph(list(reversed(edges))))
+ assert forward == reverse
+
+ def test_reindex_is_a_total_order_on_equal_sizes(self):
+ """Goes straight at the re-index step, which is where the id is minted.
+
+ The graph-level tests above cannot fail while the partition input
+ happens to be sorted upstream, but Leiden (tried before Louvain, and
+ absent from CI) returns a partition ordered by its own internals. This
+ asserts the property the re-index has to hold on its own."""
+ from repowise.core.analysis.communities import detect_file_communities as _detect
+
+ groups = [["b/1.py", "b/2.py"], ["a/1.py", "a/2.py"], ["c/1.py", "c/2.py"]]
+
+ def rank(order):
+ g = nx.DiGraph()
+ for members in order:
+ for p in members:
+ g.add_node(p, node_type="file", language="python")
+ g.add_edge(members[0], members[1], edge_type="imports")
+ return _detect(g)[0]
+
+ # Same three communities, three different arrival orders, one answer.
+ assert rank(groups) == rank(list(reversed(groups))) == rank([groups[i] for i in (1, 2, 0)])
+
+ def test_community_labels_are_stable(self):
+ edges = [
+ ("alpha/a.py", "alpha/b.py"),
+ ("bravo/a.py", "bravo/b.py"),
+ ("charlie/a.py", "charlie/b.py"),
+ ]
+ _, forward, _ = detect_file_communities(self._graph(edges))
+ _, reverse, _ = detect_file_communities(self._graph(list(reversed(edges))))
+ assert {cid: ci.label for cid, ci in forward.items()} == {
+ cid: ci.label for cid, ci in reverse.items()
+ }
+
+ def test_isolates_get_stable_ids(self):
+ """Every isolate is its own size-1 community — the worst tie case."""
+
+ def assign(paths):
+ g = nx.DiGraph()
+ for p in paths:
+ g.add_node(p, node_type="file", language="python")
+ return detect_file_communities(g)[0]
+
+ paths = [f"pkg/mod_{i:02d}.py" for i in range(10)]
+ assert assign(paths) == assign(list(reversed(paths)))
+
+ def test_test_files_attach_stably(self):
+ """A test file linked to two production files must pick the same one
+ regardless of which edge the graph happened to store first."""
+
+ def assign(edge_order):
+ g = nx.DiGraph()
+ for u, v in edge_order:
+ g.add_node(u, node_type="file", language="python")
+ g.add_node(v, node_type="file", language="python")
+ g.add_edge(u, v, edge_type="imports")
+ return detect_file_communities(g)[0]["tests/test_thing.py"]
+
+ edges = [
+ ("alpha/a.py", "alpha/b.py"),
+ ("bravo/a.py", "bravo/b.py"),
+ ("tests/test_thing.py", "alpha/a.py"),
+ ("tests/test_thing.py", "bravo/a.py"),
+ ]
+ assert assign(edges) == assign(list(reversed(edges)))