Merge branch 'main' (early part) into next

Author: krlmlr

.github/workflows/R-CMD-check.yaml

@@ -76,7 +76,7 @@ jobs:
           ref: ${{ inputs.ref }}
 
       - name: Update status for rcc
-        if: github.actor != 'github-copilot[bot]'
+        if: github.actor != 'Copilot'
         # FIXME: Wrap into action
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -182,7 +182,7 @@ jobs:
 
       - name: Update status for rcc
         # FIXME: Wrap into action
-        if: always() && (github.actor != 'github-copilot[bot]')
+        if: always() && (github.actor != 'Copilot')
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
@@ -219,7 +219,7 @@ jobs:
 
       - name: Update status for rcc (Copilot)
         # Update status directly when triggered by Copilot or bots, since they can't dispatch workflows
-        if: always() && (github.actor == 'github-copilot[bot]')
+        if: always() && (github.actor == 'Copilot')
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |

.gitignore

@@ -24,3 +24,4 @@ cran
 /src/symbols.rds
 /tests/testthat/testthat-problems.rds
 /covr
+/.vscode/launch.json

AGENTS.md

@@ -31,15 +31,16 @@ pak::pak(dependencies = "Config/Needs/build")
 
 - When run on GitHub Actions, assume that R, the package in its current state and all dependencies are installed.
 - Only install new packages when needed for implementing new features or tests.
-- Run `R -q -e 'testthat::test_local(reporter = "check")'` to execute tests as a final step.
+- Run `R -q -e 'devtools::check()'` to execute all checks as a final step.
 
 ### Building and Testing
 
 - Load package for development: `pkgload::load_all()`
 - Run tests: `testthat::test_local(reporter = "check")`
+- Run tests for a single file `test-foo.R`: `testthat::test_local(filter = "foo", reporter = "check")`
 - Build package: `devtools::build()`
 - Check package: `devtools::check()`
-- Update documentation: `devtools::document()`
+- Update `.Rd` documentation: `devtools::document()`
 - Format code: `air format .`
 
 ## Code Style and Documentation
@@ -54,22 +55,24 @@ pak::pak(dependencies = "Config/Needs/build")
 - Prefer expressive code over comments where possible
 - Add comments to utility functions that cannot be made immediately obvious
 - Focus comments on explaining the "why" and "how", the "what" should be clear from the code itself
-- Use line breaks after each sentence in multi-sentence comments
+- Use line breaks after each sentence
 
 ### R Code Conventions
 
-- Follow the [tidyverse style guide](https://style.tidyverse.org)
+- Follow the [tidyverse style guide](https://style.tidyverse.org) and the [tidyverse design guide](https://design.tidyverse.org)
 - Use `snake_case` for new functions
 - Use explicit package prefixes (e.g., `withr::local_db_connection()`) for clarity
 - Maintain consistent indentation (2 spaces) and spacing patterns
 - Use meaningful variable names that reflect context
 - Run `air format .` before committing changes to ensure consistent formatting
+- Never change deprecated functions
 
 ### Documentation
 
 - Use roxygen2 with Markdown syntax for all function documentation
 - Use math notation for formulas: `\eqn{...}` for inline, `\deqn{...}` for display equations
 - Keep each sentence on its own line in roxygen2 comments for better readability
+- Document all arguments and return values
 - Document internal functions using devtag (work in progress)
 - Link to C documentation using `@cdocs` tag: `#' @cdocs igraph_function_name`
 - Always run `devtools::document()` after updating documentation
@@ -84,7 +87,7 @@ All new functions must include:
 
 - Examples
 - Tests
-- Proper documentation
+- Proper documentation, including arguments and return values
 - A concept so that it exists in the pkgdown reference index
 - An "experimental" badge via `r lifecycle::badge("experimental")`
 
@@ -118,4 +121,7 @@ These are build artifacts that are regenerated automatically (see `src/README.md
 - Add test cases for all new functionality
 - For newly created autogenerated functions, always add a test to `test-aaa-auto.R`
 - Test file naming should mirror source file naming
+- Implement both structured and snapshot tests. For the latter, ensure stability by setting a random seed and calling `local_igraph_options(print.id = FALSE)` if graph IDs are involved.
+- When testing error behavior, prefer snapshot tests.
 - Run tests frequently during development and at the end: `testthat::test_local(reporter = "check")`
+- Run `devtools::check()` as a final step to ensure all checks pass.

NAMESPACE

@@ -529,6 +529,7 @@ export(induced_subgraph)
 export(infomap.community)
 export(interconnected.islands.game)
 export(intersection)
+export(invalidate_cache)
 export(is.bipartite)
 export(is.chordal)
 export(is.connected)

R/interface.R

@@ -714,3 +714,35 @@ incident_edges <- function(graph, v, mode = c("out", "in", "all", "total")) {
 
   res
 }
+
+#' Invalidate the cache of a graph
+#'
+#' igraph graphs cache some basic properties (such as whether the graph is a
+#' DAG or whether it is simple) in an internal data structure for faster
+#' repeated queries. This function invalidates the cache, forcing a
+#' recalculation of the cached properties the next time they are needed.
+#'
+#' You should not need to call this function during normal usage; however, it
+#' may be useful for debugging cache-related issues. A tell-tale sign of an
+#' invalid cache entry is when the result of a cached function (such as
+#' \code{\link{is_dag}()} or \code{\link{is_simple}()}) changes after calling
+#' this function.
+#'
+#' @param graph The graph whose cache is to be invalidated.
+#' @return The graph with its cache invalidated. Since the graph is modified
+#'   in place in R as well, you can also ignore the return value.
+#'
+#' @family low-level operations
+#'
+#' @export
+#' @examples
+#' g <- make_ring(10)
+#' # Cache is populated when calling is_simple()
+#' is_simple(g)
+#' # Invalidate cache (for debugging purposes)
+#' invalidate_cache(g)
+#' # Result should be the same
+#' is_simple(g)
+invalidate_cache <- function(graph) {
+  invalidate_cache_impl(graph)
+}

_pkgdown.yml

@@ -113,6 +113,9 @@ reference:
   - running_mean
   - sample_seq
   - fit_power_law
+- subtitle: Low-level operations
+- contents:
+  - has_concept("low-level operations")
 # [[[ network analysis start
 - title: Structural properties
 - contents:

man/invalidate_cache.Rd

@@ -229,3 +229,29 @@ test_that("incident() works", {
   expect_snapshot(incident(g, 1))
   expect_snapshot(incident(g, 34))
 })
+
+test_that("invalidate_cache works", {
+  g <- make_ring(10)
+
+  # Cache is populated when calling is_simple()
+  expect_true(is_simple(g))
+
+  # Invalidate cache
+  result <- invalidate_cache(g)
+
+  # Result should be the same after cache invalidation
+  expect_true(is_simple(result))
+
+  # Function should return a graph object
+  expect_true(is_igraph(result))
+
+  # Graph properties should be preserved
+  expect_equal(vcount(result), 10)
+  expect_equal(ecount(result), 10)
+})
+
+test_that("invalidate_cache errors on invalid input", {
+  expect_error(invalidate_cache(NULL))
+  expect_error(invalidate_cache("not a graph"))
+  expect_error(invalidate_cache(123))
+})