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

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