chore: Split generated `R/aaa-auto.R` into per-category `R/aaa-<cat>.R` files by schochastics · Pull Request #2621 · igraph/rigraph

schochastics · 2026-04-23T12:36:17Z

Summary

Stimulus generates a single ~14,800-line R/aaa-auto.R containing every C igraph wrapper. This PR introduces a categorization layer that splits that monolithic output into 26 per-category files (R/aaa-basicigraph.R, R/aaa-cliques.R, …, R/aaa-visitors.R) so navigating the generated wrappers aligns with how igraph groups functions in its reference manual. Subcategories appear inside each file as banner comments.

Why do this? Today a developer grepping for bfs_impl lands in the middle of a 14.8k-line file with no navigational cues; afterwards they land at the top of R/aaa-visitors.R under the # ==== breadth-first-search ==== banner.

The split happens as a post-processing step on the stimulus output; stimulus itself is unchanged (it doesn't support multi-file output natively). A new tools/aaa-categories.yaml is the single source of truth for which function goes where, and two new tools keep everything reconciled.

What's in the diff

Change	Purpose
`tools/aaa-categories.yaml` (new)	Authoritative map: category → subcategory → list of `igraph_` C functions. 491 entries across 26 categories, covering every `R_igraph_` symbol `.Call()`'d in the generated wrappers.
`tools/rebuild-cats.R` (new)	Reconciles the YAML against whatever R/aaa-*.R files are present. Idempotent; fails loudly if an ungrouped function appears in the generated wrappers.
`tools/split-aaa-auto.R` (new)	Parses the stimulus output, looks up each `_impl` wrapper's category, and writes one file per category with subcategory banners. Preserves each wrapper's source byte-for-byte.
`Makefile-cigraph`	Stimulus now writes to `.build/aaa-auto.R` (ignored), and the split script produces the in-repo `R/aaa-<cat>.R` files. New phony target `r_wrappers` covers the full pipeline.
`R/aaa-auto.R` → `R/aaa-<cat>.R` × 26	The actual split output. All existing `.Call()` semantics unchanged — it is a purely organizational change.
`.gitignore` / `.Rbuildignore`	Ignore `.build/`.

The closure-normalization rule

Nine .Call() targets in the generated wrappers end in _closure (e.g. R_igraph_bfs_closure). These are R-binding helpers defined in src/rcallback.c that wrap an underlying C function with SEXP-callback support — they are not standalone C library functions. rebuild-cats.R encodes the 9-entry whitelist and maps them back to their semantic names (e.g. igraph_bfs_closure → igraph_bfs) so each wrapper lands where a reader would expect. R_igraph_transitive_closure is not affected — there "closure" is a graph-theory term, not a wrapper suffix.

Categorization highlights

The initial YAML layout mirrored igraph's legacy docbook sections. Several cleanups were applied:

Retired the undocumented category — all 8 entries moved to real homes:
- igraph_residual_graph, igraph_reverse_residual_graph → flows/maximum-flows
- igraph_hrg_sample_many → hrg/hrg-sampling
- igraph_has_attribute_table, igraph_finalizer → nongraph/internal
- igraph_eigen_adjacency → structural/spectral-properties
- igraph_eigen_matrix, igraph_eigen_matrix_symmetric, igraph_solve_lsap → nongraph/linear-algebra (new subcategory)
Typo/case fixes: regular-structre-generators → regular-structure-generators; Sparsifiers → sparsifiers; motifs/uncategorized → motifs/graph-census.
Semantic relocations: igraph_transitive_closure and igraph_transitive_closure_dag moved from structural/graph-components → operators/miscellaneous-operators (they produce a derived graph, not component analysis).
Split oversized buckets:
- structural/shortest-path-related-functions (34 entries) → distances-and-metrics (22) + shortest-paths (12).
- structural/other-operations (11) → matrix-representations (5) + mutual-edges (3) + summary-statistics (3).

Developer workflow

After a stimulus upgrade or new igraph C function landing upstream:

make -f Makefile-cigraph r_wrappers   # regenerates the split files
Rscript tools/rebuild-cats.R          # validates/updates the categories YAML

The second step fails loudly with the exact names that need adding if aaa-categories.yaml drifts from the generated wrappers.

Validation performed

All 26 R/aaa-*.R files parse cleanly.
490 _impl wrappers distributed across the files, zero duplicates.
491 unique R_igraph_* symbols preserved (the 491st being R_igraph_finalizer, which appears in every impl's on.exit but has no wrapper of its own).
tools/rebuild-cats.R produces byte-identical output on re-run (idempotent).
tools/split-aaa-auto.R produces byte-identical output on re-run from the same source (idempotent).

Test plan

devtools::load_all(".") succeeds
R CMD check / CI passes
make -f Makefile-cigraph r_wrappers round-trips cleanly on a machine with the stimulus venv
Spot-check that at least one wrapper from each of the 26 category files still behaves correctly (e.g. the existing testthat suite covers igraph_* wrappers broadly, so a green test run is the main check)

cc @maelle for review — this is purely an organizational/tooling change; no behavior should change, but the restructuring is substantial so a second pair of eyes on the categorization choices would be welcome.

🤖 Generated with Claude Code

Stimulus generates one monolithic R/aaa-auto.R (~14.8k lines) covering every C igraph wrapper. This commit introduces a categorization layer that splits the generated output into 26 per-category files matching how the functions are grouped in the igraph reference manual, with subcategory banner comments inside each file. - tools/aaa-categories.yaml: authoritative category -> subcategory -> fn mapping, reconciled against every R_igraph_* symbol .Call()'d from the generated wrappers (491 entries; 8 closure wrappers mapped back to their underlying C functions via the src/rcallback.c whitelist) - tools/rebuild-cats.R: idempotent reconciliation tool; fails loudly if new functions appear in the generated wrappers without a categorization - tools/split-aaa-auto.R: post-processes stimulus output into R/aaa-<cat>.R - Makefile-cigraph: stimulus now writes to .build/aaa-auto.R (ignored), the split script produces the in-repo R/ files. Phony target r_wrappers covers the full pipeline

Run: https://github.com/igraph/rigraph/actions/runs/24835564384

maelle · 2026-04-30T07:32:58Z

A developper grepping for a function name?! Like, not using IDE navigation?!

Anyway awesome, I'll review this now, thanks a ton!

maelle

Thank you! A few comments 😄

maelle · 2026-04-30T07:37:50Z

@@ -0,0 +1,669 @@
+# Functions ordered by category
+basicigraph:


Suggested change

basicigraph:

basic-igraph:

Applied in 8c7fc6b — renamed basicigraph → basic-igraph in the YAML, in tools/rebuild-cats.R, and renamed R/aaa-basicigraph.R → R/aaa-basic-igraph.R.

Generated by Claude Code

maelle · 2026-04-30T07:40:51Z


 # R files that are generated/copied

-RGEN = R/aaa-auto.R src/rinterface.c \


why can't we add the post-processing step to this makefile so that generating the functions remain a single call?

It already is — the .build/r-wrappers.stamp target (lines 128–147) runs both stimulus and tools/split-aaa-auto.R in sequence, so make -f Makefile-cigraph r_wrappers is a single call that produces the split files. The PR description references R/aaa-auto.R as a make target by mistake (the actual target is the stamp file).

Generated by Claude Code

maelle · 2026-04-30T07:42:08Z

           -t $(vendored_srcdir)/interfaces/types.yaml \
           -t tools/stimulus/types-RR.yaml \
           -l RR
+	Rscript tools/split-aaa-auto.R .build/aaa-auto.R


aaah ok, this was wrong in the PR description

maelle · 2026-04-30T07:43:21Z

+  callback
+) {
+  # Argument checks
+  ensure_igraph(graph)


I have no specific opinion on categories but before we validate this (and split the test file), could you please add some stats to the PR thread: min/median/max number of lines per aaa file?

Stats for the 28 R/aaa-*.R files (after the basicigraph rename and status-into-progress merge):

lines

min 20 (aaa-error.R, aaa-spatial.R)

median 352

mean 540

max 2417 (aaa-structural.R)

total 15,118

Full distribution, sorted:

file lines

aaa-error.R 20

aaa-spatial.R 20

aaa-progress.R 40

aaa-separators.R 92

aaa-embedding.R 104

aaa-graphlets.R 106

aaa-coloring.R 119

aaa-processes.R 199

aaa-trees.R 211

aaa-motifs.R 221

aaa-hrg.R 245

aaa-nongraph.R 256

aaa-bipartite.R 286

aaa-visitors.R 316

aaa-cycles.R 389

aaa-foreign.R 436

aaa-operators.R 529

aaa-basic-igraph.R 534

aaa-cliques.R 536

aaa-flows.R 714

aaa-community.R 731

aaa-generators.R 881

aaa-isomorphism.R 957

aaa-layout.R 1000

aaa-centrality.R 1071

aaa-games.R 1145

aaa-paths.R 1543

aaa-structural.R 2417

aaa-structural.R and aaa-paths.R are large enough that splitting them by subcategory is being considered as a follow-up.

Generated by Claude Code

aaa-structural.R was 160 functions / 5,237 lines — too unwieldy for IDE navigation. Promote three natural sub-clusters to top-level categories, shrinking aaa-structural.R to 84 functions / 2,417 lines: - aaa-paths.R (38 fns) — distances, shortest paths, widest paths - aaa-centrality.R (30 fns) — centrality measures + centralization - aaa-trees.R (8 fns) — spanning trees and tree unfolding Implementation: tools/rebuild-cats.R gains a `category_moves` mechanism that relocates whole (cat, sub) groups to a new top-level on the flattened table. The structural/trees subcategory is renamed to spanning-trees-and-forests for clarity inside the new trees category. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

schochastics · 2026-04-30T18:55:03Z

A developper grepping for a function name?! Like, not using IDE navigation?!

Anyway awesome, I'll review this now, thanks a ton!

Claude knows that I dont use IDE navigation I guess 😆

schochastics · 2026-04-30T18:56:29Z

aaa-structural.R	84	2,417
aaa-paths.R	38	1,544
aaa-games.R	36	1,145
aaa-generators.R	35	881
aaa-centrality.R	30	1,071
aaa-layout.R	28	1,000
aaa-operators.R	24	529
aaa-basicigraph.R	23	534
aaa-cliques.R	21	536
aaa-community.R	21	731
aaa-flows.R	21	714
aaa-isomorphism.R	21	957
aaa-foreign.R	18	436
aaa-cycles.R	13	389
aaa-bipartite.R	10	286
aaa-hrg.R	10	245
aaa-nongraph.R	10	258
aaa-motifs.R	9	221
aaa-trees.R	8	211
aaa-coloring.R	5	115
aaa-processes.R	5	199
aaa-separators.R	5	92
aaa-visitors.R	5	316
aaa-embedding.R	3	104
aaa-graphlets.R	3	106
aaa-error.R	1	20
aaa-progress.R	1	22
aaa-spatial.R	1	20
aaa-status.R	1	20
total	490	15,119

cc @maelle. Not very even but I guess that is hard to achieve with a good categorization anyway 🤷

krlmlr

Nice, thanks! Looking forward to it.

krlmlr · 2026-05-04T15:20:13Z

+  nongraph-spatial:
+    - igraph_convex_hull_2d
+
+status:


Merge with progress?

Done in 8c7fc6b — status: removed as a top-level category, igraph_status moved under progress: as invoking-the-status-handler. R/aaa-status.R deleted; both impls now live in R/aaa-progress.R.

Generated by Claude Code

krlmlr · 2026-05-04T15:21:11Z

+  - igraph_is_bipartite_coloring
+  - igraph_is_edge_coloring
+  - igraph_is_perfect
+  - igraph_is_vertex_coloring
+  - igraph_vertex_coloring_greedy


Suggested change

- igraph_is_bipartite_coloring

- igraph_is_edge_coloring

- igraph_is_perfect

- igraph_is_vertex_coloring

- igraph_vertex_coloring_greedy

detect:

- igraph_is_bipartite_coloring

- igraph_is_edge_coloring

- igraph_is_perfect

- igraph_is_vertex_coloring

compute:

- igraph_vertex_coloring_greedy

Applied in 8c7fc6b — coloring now has detect (4 fns) and compute (1 fn) subcategories, and R/aaa-coloring.R has the corresponding banner comments.

Generated by Claude Code

krlmlr · 2026-05-24T06:33:01Z

This now has conflicts, can you resolve please?

krlmlr · 2026-05-24T06:35:05Z

Can we do subcategories for structural and paths?

Run: https://github.com/igraph/rigraph/actions/runs/26368243777

… merge status into progress

Previously split-aaa-auto.R and rebuild-cats.R both stop() if the generated wrappers contain a function missing from tools/aaa-categories.yaml, which would break the build whenever a new igraph C function landed upstream. Both now warn instead and put unassigned functions under a top-level uncategorized: bucket (emitted as R/aaa-uncategorized.R by the splitter) so the package keeps building while the warning lists exactly what needs a home.

krlmlr · 2026-05-24T17:56:36Z

Done for now, no further action needed.

krlmlr · 2026-05-24T17:56:40Z

Thanks for working on this!

schochastics and others added 2 commits April 23, 2026 14:34

chore: Auto-update from GitHub Actions

d6f8d9d

Run: https://github.com/igraph/rigraph/actions/runs/24835564384

maelle reviewed Apr 30, 2026

View reviewed changes

krlmlr reviewed May 4, 2026

View reviewed changes

krlmlr mentioned this pull request May 24, 2026

Bump to igraph/C 1.0.1 #2650

Open

claude and others added 4 commits May 24, 2026 17:13

Merge branch 'main' into categories

9e65a51

chore: Auto-update from GitHub Actions

0e1f871

Run: https://github.com/igraph/rigraph/actions/runs/26368243777

Address review: rename basicigraph→basic-igraph, split coloring subs,…

4f8c6af

… merge status into progress

krlmlr changed the title ~~Split generated R/aaa-auto.R into per-category R/aaa-<cat>.R files~~ chore: Split generated R/aaa-auto.R into per-category R/aaa-<cat>.R files May 24, 2026

krlmlr enabled auto-merge (squash) May 24, 2026 17:56

krlmlr merged commit 455cb71 into main May 24, 2026
5 of 6 checks passed

krlmlr deleted the categories branch May 24, 2026 18:13

		@@ -0,0 +1,669 @@
		# Functions ordered by category
		basicigraph:


		# R files that are generated/copied

		RGEN = R/aaa-auto.R src/rinterface.c \

	lines
min	20 (`aaa-error.R`, `aaa-spatial.R`)
median	352
mean	540
max	2417 (`aaa-structural.R`)
total	15,118

Uh oh!

Conversation

schochastics commented Apr 23, 2026

Summary

What's in the diff

The closure-normalization rule

Categorization highlights

Developer workflow

Validation performed

Test plan

Uh oh!

maelle commented Apr 30, 2026

Uh oh!

maelle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

schochastics commented Apr 30, 2026

Uh oh!

schochastics commented Apr 30, 2026

Uh oh!

krlmlr left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

krlmlr commented May 24, 2026

Uh oh!

krlmlr commented May 24, 2026

Uh oh!

krlmlr commented May 24, 2026

Uh oh!

krlmlr commented May 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants