docs(revdep): Analyze and document reverse dependency problems for igraph 2.3.0

revdep/.gitignore

@@ -1,3 +1,4 @@
 /cloud.noindex
 /cloud
 /review/
+/notifications/

revdep/NOTIFY-README.md

@@ -0,0 +1,122 @@
+# Maintainer Notification Script
+
+This script (`notify-maintainers.sh`) automates the process of notifying package maintainers about reverse dependency issues discovered during igraph development.
+
+## Features
+
+- **GitHub Integration**: Automatically creates GitHub issues for packages hosted on GitHub
+- **Email Fallback**: Generates email drafts (with pre-filled `To:` and `Cc:` fields) for packages not on GitHub, or optionally for all packages after filing a GitHub issue
+- **Issue log**: Records all filed GitHub issue URLs for easy follow-up
+- **Template-based**: Creates well-formatted issue descriptions with all relevant information
+
+## Prerequisites
+
+### For GitHub Issues (Optional)
+
+```bash
+# Install GitHub CLI
+# On macOS:
+brew install gh
+
+# On Linux:
+# See https://github.com/cli/cli#installation
+
+# Authenticate with GitHub
+gh auth login
+```
+
+Note: Issues are created on behalf of the authenticated GitHub user. Ensure you are logged in with appropriate credentials before running the script.
+
+### For Email Drafts
+
+No additional setup required – the script automatically fetches maintainer emails from CRAN and pre-fills the `To:` field in each draft.
+
+## Usage
+
+```bash
+./notify-maintainers.sh
+```
+
+The script will:
+
+1. Check if `gh` CLI is available
+2. For each affected package:
+   - Look up the maintainer email from the package DESCRIPTION field stored in CRAN
+   - Determine whether the package repository on GitHub is accessible
+   - If accessible: Create a GitHub issue directly using `gh issue create` and log the issue URL
+   - If not accessible: Create an email draft in `notifications/` with the maintainer email pre-filled
+
+The script determines upfront which action to take for each package (either GitHub issue OR email draft, not both). Regardless of which path is taken, issue links are always stored in `notifications/issue-log.txt` for follow-up tracking.
+
+## Output
+
+Files are created in the `notifications/` directory:
+
+- `issue-log.txt` – URLs of all GitHub issues created (for follow-up)
+- `{Package}-email.txt` – Complete email draft **only for packages that require email drafts** (GitHub not accessible)
+
+For packages with accessible GitHub repositories, issues are created directly; no local files other than the log entry are saved.
+
+## Manual Steps
+
+### If GitHub Issues Fail
+
+If you see authentication or permission errors when creating GitHub issues:
+
+1. Check GitHub authentication: `gh auth status`
+2. Authenticate if needed: `gh auth login`
+3. Or manually create issues via the GitHub web interface
+
+### For Email Drafts
+
+When GitHub repositories are not accessible, email drafts are automatically generated with:
+
+- `To:` pre-filled with the package maintainer's CRAN email address
+- `Cc:` pre-filled with the igraph development team address
+
+To send these emails:
+
+1. Review the email content in `notifications/{Package}-email.txt`
+2. Open your email client and compose a new message
+3. Copy the `To:`, `Cc:`, `Subject:`, and body content
+
+## Package Information
+
+The script's package list and issue templates need to be updated each time a new set of revdep issues is identified. Package information (GitHub URL, maintainer email) is sourced from the CRAN package metadata (`DESCRIPTION` fields as reported by CRAN).
+
+## Customization
+
+To modify the issue templates or add packages to the notification list, edit the script directly. Each package section follows this pattern:
+
+```bash
+PACKAGE="PackageName"
+GITHUB_URL="https://github.com/owner/repo"
+MAINTAINER_EMAIL="maintainer@example.com"  # from CRAN DESCRIPTION
+
+ISSUE_TITLE="Short description of the issue"
+ISSUE_BODY="..."
+EMAIL_SUBJECT="..."
+
+notify_package "$PACKAGE" "$GITHUB_URL" "$MAINTAINER_EMAIL" "$ISSUE_TITLE" "$ISSUE_BODY" "$EMAIL_SUBJECT"
+```
+
+## Troubleshooting
+
+### "gh CLI not found"
+Install the GitHub CLI as described in Prerequisites.
+
+### "Failed to create issue"
+- Check GitHub authentication: `gh auth status`
+- Ensure you have permission to create issues in the repository
+- The repository might be private
+
+### "GitHub repository not accessible"
+- The repository might be private
+- There might be no link to the repository in the package metadata
+- Use the email draft fallback instead
+
+## See Also
+
+- [problems-analysis.md](problems-analysis.md) - Detailed analysis of each issue
+- [examples/](examples/) - Runnable reproduction scripts
+- [cran-response-draft.md](cran-response-draft.md) - Draft response to CRAN review email

revdep/cran-response-draft.md

@@ -0,0 +1,43 @@
+# Draft response to CRAN teams' auto-check for igraph 2.3.0
+
+**Subject**: Re: CRAN pre-release check results for igraph 2.3.0 – reverse dependency issues
+
+---
+
+Dear CRAN team,
+
+Thank you for running the pre-release checks. We have reviewed all 7 flagged packages and reached
+out to the maintainers of all affected packages on 2026-02-20.
+
+- **Cascade**: Namespace collision — the new `circulant()` export in 2.3.0 conflicts with
+  `magic::circulant`. Non-breaking warning only. No GitHub issue filed; maintainer notified
+  by email.
+
+- **DiagrammeR**: Bug in DiagrammeR — `get_leverage_centrality()` passes a vector to
+  `neighbors()`, which now requires a single vertex. Issue filed 2026-02-20:
+  https://github.com/rich-iannone/DiagrammeR/issues/538
+
+- **jewel**: Bug in jewel — non-integer `niter` value (`p * 0.05`) is passed to `rewire()`,
+  which now strictly validates integer arguments. Issue filed 2026-02-20:
+  https://github.com/annaplaksienko/jewel/issues/1
+
+- **rSpectral**: Behavior change in igraph — `modularity()` now auto-uses the `"weight"` edge
+  attribute when present, changing test results. Issue filed 2026-02-20 (resolved 2026-03-05):
+  https://github.com/cmclean5/rSpectral/issues/1
+
+- **rgph**: **False positive / unrelated** — the failure is caused by a Java configuration
+  problem on the check machine, not by igraph changes. igraph is only in `Suggests` for this
+  package and no igraph-related errors appear in the log. No action needed from igraph's side.
+
+- **sfnetworks**: Bug in sfnetworks — `all_shortest_paths(from = ...)` now requires a single
+  vertex; sfnetworks passes a vector. Issue filed 2026-02-20:
+  https://github.com/luukvdmeer/sfnetworks/issues/292
+
+- **tmap.networks**: Cascading failure — imports sfnetworks directly and fails as a consequence.
+  Will be resolved once sfnetworks is updated. Maintainer notified via sfnetworks issue.
+
+All fixes are straightforward and the maintainers were notified well in advance. We are happy to
+provide further details on any individual case.
+
+Best regards,
+The igraph Development Team

revdep/examples/README.md

@@ -0,0 +1,53 @@
+# Reverse Dependency Problem Examples
+
+This directory contains minimal reproducible examples for packages that have newly broken checks compared to the most recent CRAN version of igraph.
+
+## Files
+
+Each issue has two files:
+- `*.R` - Runnable R script with the minimal example
+- `*.md` - Markdown documentation with example output (reprex-style)
+
+### Issues
+
+1. **cascade-circulant-issue** - Namespace collision between `igraph::circulant` and `magic::circulant`
+2. **diagrammer-neighbors-issue** - `neighbors()` now requires exactly one vertex
+3. **jewel-integer-issue** - Strict integer validation in `rewire_impl()`
+4. **manynet-scalar-issue** - Scalar integer validation in `sample_last_cit()`
+5. **rspectral-modularity-issue** - Automatic weight usage in modularity calculations
+6. **sfnetworks-from-issue** - `from` parameter must specify exactly one vertex
+
+## Running the Examples
+
+Each R script can be run with:
+
+```r
+source("revdep/examples/cascade-circulant-issue.R")
+```
+
+Or from the command line:
+
+```bash
+Rscript revdep/examples/cascade-circulant-issue.R
+```
+
+## Format
+
+The examples follow a simplified format:
+- No `cat()` statements for output (comments instead)
+- No `tryCatch()` blocks (commented out error cases)
+- Clean, runnable code that can be used with `reprex::reprex()`
+- Corresponding `.md` files show the expected output
+
+## Summary of Issues
+
+| Package | Issue | Severity | Type |
+|---------|-------|----------|------|
+| Cascade | Namespace collision warning | Low | Inadvertent behavior change |
+| DiagrammeR | `neighbors()` requires single vertex | High | API tightening |
+| jewel | Integer validation error | High | Uncovered downstream bug |
+| manynet | Scalar integer validation | High | API tightening |
+| rSpectral | Modularity test failures | Medium | Behavior change with workaround |
+| sfnetworks | `from` requires single vertex | High | API tightening |
+
+See `../problems-analysis.md` for detailed analysis and recommendations.

revdep/examples/cascade-circulant-issue.R

@@ -0,0 +1,24 @@
+# Cascade namespace collision issue
+# Issue: Warning when loading both igraph and magic packages
+
+library(igraph)
+
+# igraph now exports circulant() as a constructor alias
+"circulant" %in% ls("package:igraph")
+
+# The preferred way is to use make_circulant() directly
+g <- make_circulant(10, c(1, 3))
+vcount(g)
+ecount(g)
+
+# Root cause:
+# - igraph added make_circulant() and constructor alias circulant() in v2.2.1.9003
+# - magic package also has a circulant() function for creating circulant matrices
+# - When both packages are loaded, there's a namespace collision
+# - This produces: Warning: replacing previous import 'igraph::circulant' by 'magic::circulant'
+
+# Assessment:
+# - This is an inadvertent behavior change in igraph
+# - The circulant() function is primarily a constructor alias
+# - Users should use make_circulant() directly
+# - Cascade package can resolve by explicitly importing magic::circulant in NAMESPACE

revdep/examples/cascade-circulant-issue.md

@@ -0,0 +1,33 @@
+# Cascade namespace collision issue
+
+## Issue
+Warning when loading both igraph and magic packages
+
+## Reproducible Example
+
+```r
+library(igraph)
+
+# igraph now exports circulant() as a constructor alias
+"circulant" %in% ls("package:igraph")
+#> [1] TRUE
+
+# The preferred way is to use make_circulant() directly
+g <- make_circulant(10, c(1, 3))
+vcount(g)
+#> [1] 10
+ecount(g)
+#> [1] 20
+```
+
+## Root Cause
+- igraph added `make_circulant()` and constructor alias `circulant()` in v2.2.1.9003
+- magic package also has a `circulant()` function for creating circulant matrices
+- When both packages are loaded, there's a namespace collision
+- This produces: `Warning: replacing previous import 'igraph::circulant' by 'magic::circulant'`
+
+## Assessment
+- This is an inadvertent behavior change in igraph
+- The `circulant()` function is primarily a constructor alias
+- Users should use `make_circulant()` directly
+- Cascade package can resolve by explicitly importing `magic::circulant` in NAMESPACE

revdep/examples/cascade-issue-draft.md

@@ -0,0 +1,34 @@
+# Title
+
+Namespace collision warning when loading Cascade with igraph ≥ 2.3.0
+
+# Body
+
+When loading **Cascade** alongside **igraph** 2.3.0 or later the following warning appears:
+
+```
+Warning: replacing previous import 'igraph::circulant' by 'magic::circulant' when loading 'Cascade'
+```
+
+This is a **non-breaking warning** — Cascade continues to work correctly, but the warning may alarm users and will surface in `R CMD check`.
+
+## Root cause
+
+igraph 2.3.0 added `make_circulant()` and a constructor alias `circulant()`.
+Because **magic** also exports `circulant()`, R detects a conflict between the two imports when Cascade is loaded.
+
+## Suggested fix
+
+Explicitly import `magic::circulant` in your NAMESPACE so that R resolves the conflict deterministically (and silently):
+
+```r
+# In NAMESPACE, or equivalently in a roxygen2 tag somewhere in the package:
+importFrom(magic, circulant)
+```
+
+That single line removes the warning entirely.
+
+---
+
+*This issue was identified during reverse-dependency checks for the upcoming igraph 2.3.0 release.
+See the igraph repository for full analysis: https://github.com/igraph/rigraph*

revdep/examples/diagrammer-neighbors-issue.R

@@ -0,0 +1,36 @@
+# DiagrammeR neighbors() issue
+# Issue: neighbors() now requires exactly one vertex
+
+library(igraph)
+
+# Create a simple graph
+g <- make_ring(5)
+
+# This works - single vertex
+neighbors(g, 1)
+
+# This fails - multiple vertices
+# neighbors(g, c(1, 2))
+# Error: `vid` must specify exactly one vertex
+
+# This also fails - passing a non-scalar
+# degree_vals <- degree(g)
+# neighbors(g, degree_vals)
+# Error: `vid` must specify exactly one vertex
+
+# Root cause:
+# - igraph added stricter validation requiring exactly one vertex for neighbors()
+# - DiagrammeR's get_leverage_centrality() passes degree_vals (a vector) to neighbors()
+# - The code: mean(degree_vals[igraph::neighbors(ig_graph, degree_vals)])
+# - This previously may have worked with implicit vectorization or used first element
+
+# Assessment:
+# - This is an intentional API tightening in igraph for safety
+# - DiagrammeR needs to update to iterate over vertices individually
+# - The fix should loop: lapply(seq_along(degree_vals), function(i) neighbors(g, i))
+
+# Recommendation for DiagrammeR:
+# Change from:
+#   neighbors(ig_graph, degree_vals)
+# To:
+#   lapply(seq_along(degree_vals), function(i) neighbors(ig_graph, i))