Skip to content

feat(cluster): bunch-search-based modularization (tasks 5-7) - #248

Merged
jeremiepas merged 6 commits into
mainfrom
spec/bunch-search-based-modularization
Nov 12, 2026
Merged

jeremiepas merged 6 commits into
mainfrom
spec/bunch-search-based-modularization

Conversation

@jeremiepas

Copy link
Copy Markdown
Owner

Summary

Completes the bunch-search-based-modularization OpenSpec change (tasks 5–7): Bunch orchestration in UseCase/Cluster.hs, the landscape evaluation path in UseCase/ClusterEval.hs, CLI/config wiring, partition-quality report lines, and the recorded validation evidence.

Leiden remains the default. Bunch is opt-in via --cluster-algorithm bunch / clustering.algorithm: bunch.

Scope

  • ClusterAlgorithm = Leiden | Bunch BunchSettings dispatch from clustering.algorithm/seed/bunch.*, CLI wins over config.
  • File cap reports BunchSkip and falls back to Leiden; symbols are pushed back to their file's cluster.
  • ClusterQuality (algorithm, MQ, modularity, intra-edge fraction) printed from the same CommunityMap the export writes.
  • clustereval landscape (--graph, --runs, --seed, --random-partitions, --random-graph, --json, --out) with atomic landscape.json and a markdown summary.
  • Flags: --cluster-algorithm, --seed, --bunch-population, --bunch-threshold, --bunch-sa, --bunch-max-iterations, --bunch-max-files, --bunch-weighted.

Out of scope (per issue): Bunch subsystem hierarchy, omnipresent-module isolation, GA search, MoJo/EdgeSim/MeCl, changing the default algorithm.

Validation

Recorded in openspec/changes/bunch-search-based-modularization/tasks.md:

  • cabal build --flag dev all (-Werror): green in the prior run; re-run on this rebased branch below.
  • cabal test: 1608 examples, 0 failures, 4 pending, after excluding two pre-existing unrelated issues (TypeScript grammars failure; a non-terminating BoundedDeltaCommunitySpec property). Both scaffold golden fixtures updated by this change are green.
  • openspec validate bunch-search-based-modularization --strict: exit 0.
  • Landscape smoke on the Graphos repo (1,782-file MDG): Zero + High = 68.87% vs 0.81% on rnd:100:0.5; Leiden point MQ 7.7619 / 1,164 clusters. η ∈ {0,50,100} and annealing runs recorded in tasks.md.

This run

  • Rebased the prior commit 991f3d5 onto current main (5a2e3af, PR openspec: Bunch search-based modularization proposal #241 with tasks 0–4) as ab6df994f0363755cae2354811645d0d5df3f69f.
  • openspec validate ... --strict: exit 0.
  • cabal build --flag dev all: green (needed --constraint="zlib +bundled-c-zlib" in this sandbox because the system zlib headers are absent; CI/devenv supplies them).
  • CLI smoke: clustereval landscape --random-graph rnd:100:0.05 --runs 5 --random-partitions 50 --json wrote landscape.json with runs/similarity/basins/random_baseline/config (leiden correctly absent on a control graph); a Bunch build on a tiny tree printed Partition quality: algorithm=bunch ...; --bunch-max-files 1 warned Bunch skipped: 3 files exceeds --bunch-max-files 1; running Leiden and fell back.
  • cabal test: 1615 examples, 4 failures, 4 pending with two pre-existing issues skipped (small random graphs property that does not terminate; the pre-existing TypeScript grammar case). All 4 remaining failures are in GrammarsSpec (PHP/Perl/C# vendored grammar tests, files untouched by this change). Change-relevant specs are green: Bunch 22/0, Landscape 3/0, modularization 23/0, cluster 44/0, parser 12/0, config 25/0, report 36/0, determinism 17/0, permutation 6/0; the focus suite is 19/0.

Notes for the reviewer

  • Do not merge; merging is graphos-keeper via the merge-gate skill.
  • Prior commit was kept as an artifact while the managed GitHub broker was unavailable; this PR restores the normal push/PR path.

graphos developer and others added 3 commits November 11, 2026 17:35
- dispatch ClusterAlgorithm from clustering.algorithm/seed/bunch.* with CLI
  precedence; file cap reports BunchSkip and falls back to Leiden
- add --cluster-algorithm, --seed and --bunch-* build flags plus the
  clustereval landscape subcommand with atomic landscape.json and markdown
  summary
- print a Partition quality line computed from the exported CommunityMap
- record landscape/threshold/annealing smoke results and test evidence in
  the openspec tasks

Co-Authored-By: Paperclip <noreply@paperclip.ing>
…landscape)

Wire the Bunch clustering algorithm end to end and archive the change.

- Build flags --cluster-algorithm leiden|bunch, --seed, --bunch-population,
  --bunch-threshold (0..100), --bunch-sa T0,ALPHA, --bunch-max-iterations,
  --bunch-max-files, --bunch-weighted; graphos.yaml clustering.algorithm,
  clustering.seed, clustering.bunch.* with CLI precedence and validation
- Cluster stage dispatches through runClustering (Leiden stays
  byte-identical), logs a Bunch skip above the file cap, and re-scores the
  final capped partition into Analysis.analysisPartitionQuality
- GRAPH_REPORT.md: "Partition quality (<algo>): MQ, modularity, intra-edge
  fraction" plus a Bunch-skip line
- graphos clustereval landscape: runs, basins, edge similarity, random
  baseline, Leiden point; landscape.json written atomically or --json
- Fix UseCase/ClusterEval.hs, which did not compile on main (invalid
  string escape, two type errors)
- Basin cluster range is now min..max instead of first/last run
- Spec: replace the infeasible bip:100:0.75 = 3,712 scenario with
  bip:100:0.25 = 1,237 and a saturation scenario (2,500)
- Smoke results (landscape, eta/annealing sweep) recorded in tasks.md;
  change archived to openspec/changes/archive/2026-11-11-...
The export path re-derived the algorithm name from config, so a Bunch run
that fell back to Leiden above --bunch-max-files was reported as
algorithm=bunch with no skip. The pipeline already computed the correct
ClusterQuality from the partition actually written (coQuality) but never
read it.

Move ClusterQuality/BunchSkip to Graphos.Domain.Community.Quality, thread
the stage's record through exportAll/epExportAll on the full,
--cluster-only, incremental and merge paths, and render it instead of
recomputing from config. The report now also names the skip on the Leiden
fallback. Add an ExportSpec regression for that path.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

Copy link
Copy Markdown
Owner Author

Review fix — AVI-95 changes requested (head 1f27f6c)

The blocking finding from the AVI-95 review is fixed: GRAPH_REPORT.md derived the algorithm from config, so a Bunch run that fell back to Leiden above --bunch-max-files was reported as algorithm=bunch with no skip, while the correct ClusterQuality (coQuality) was computed and discarded.

  • ClusterQuality/BunchSkip moved to Graphos.Domain.Community.Quality.
  • exportAll/epExportAll now take the stage's record; the full, --cluster-only, incremental, single-file and merge paths pass it.
  • The report renders the actual algorithm and the skip: algorithm=leiden, ..., bunch skipped: N files > --bunch-max-files M (ran Leiden fallback).
  • New ExportSpec regression covers the fallback path.

Validation at 1f27f6c

  • cabal build --flag dev --constraint="zlib +bundled-c-zlib" all → green with -Werror.
  • Full suite with two pre-existing exclusions → 1616 examples, 4 failures, 4 pending. The 4 failures are the pre-existing GrammarsSpec PHP/Perl/C# vendored-grammar cases, untouched by this change. Change-relevant specs green.
  • openspec validate bunch-search-based-modularization --strict → valid (exit 0).
  • CLI smoke: --cluster-algorithm bunch --bunch-max-files 1 writes algorithm=leiden ... bunch skipped: 10 files > --bunch-max-files 1; a tiny normal Bunch run writes algorithm=bunch.
  • Not re-run: the landscape/η/annealing matrix (unchanged by this fix); the four grammar failures were not re-run on main.

Non-blocking review observations (config decode normalisation, CLI option auto validation, double formatting) are recorded in openspec/changes/bunch-search-based-modularization/tasks.md and deferred out of this PR.

Re-review is AVI-96; AVI-65 is blocked by it. Merging stays with graphos-keeper.

jeremiepas and others added 3 commits November 12, 2026 09:38
…dularization-finish

feat: finish bunch-search-based-modularization (CLI, config, report, landscape)
…icts, AVI-99)

main already finished and archived bunch-search-based-modularization in #249
(CLI/config wiring, ClusterQuality in Domain.Types.Analysis, report line and
landscape). This merge adopts main's implementation of tasks 5-7 wholesale and
keeps PR #248's lane evidence: the archived tasks.md gains the AVI-65
verification record (validation at head 1f27f6c, AVI-95 review fix history,
landscape smokes), marked superseded where it described the pre-resolution
implementation.

Code and tests after this merge are identical to main@bb5597a; the only delta
is openspec/changes/archive/2026-11-11-bunch-search-based-modularization/tasks.md.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
Co-Authored-By: Paperclip <noreply@paperclip.ing>
@jeremiepas
jeremiepas merged commit dba0cf5 into main Nov 12, 2026
8 of 9 checks passed
@jeremiepas
jeremiepas deleted the spec/bunch-search-based-modularization branch November 12, 2026 12:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant