use_claude_code()

Author: hadley

.Rbuildignore

@@ -19,3 +19,4 @@
 ^.cache$
 ^AGENTS\.md$
 ^compile_commands\.json$
+^\.claude$

.claude/.gitignore

@@ -0,0 +1 @@
+settings.local.json

.claude/CLAUDE.md

@@ -1,117 +1,82 @@
-# CLAUDE.md
+## R package development
 
-This file provides guidance to Claude Code when working with code in this repository.
+### Key commands
 
-## About This Project
+```
+# To run code
+Rscript -e "devtools::load_all(); code"
 
-lobstr is a package for R developers that prints data structures and objects in a tree-like fashion. It provides specialized `base::str()`-like functions that help visualize objects during development:
+# To run all tests
+Rscript -e "devtools::test()"
 
-- `ast()`: draws the abstract syntax tree of R expressions
-- `ref()`: shows hows objects can be shared across data structures by digging into the underlying references
-- `obj_size()`: computes the size of an object taking these shared references into account
-- `cst()` shows how frames on the call stack are connected
+# To run all tests for files starting with {name}
+Rscript -e "devtools::test(filter = '^{name}')"
 
+# To run all tests for R/{name}.R
+Rscript -e "devtools::test_active_file('R/{name}.R')"
 
-## Key development commands
+# To run a single test "blah" for R/{name}.R
+Rscript -e "devtools::test_active_file('R/{name}.R', desc = 'blah')"
+
+# To redocument the package
+Rscript -e "devtools::document()"
+
+# To check pkgdown documentation
+Rscript -e "pkgdown::check_pkgdown()"
+
+# To check the package with R CMD check
+Rscript -e "devtools::check()"
+
+# To format code
+air format .
+```
+
+### Coding
 
-General advice:
-* When running R from the console, always run it with `--quiet`
 * Always run `air format .` after generating code
+* Use the base pipe operator (`|>`) not the magrittr pipe (`%>%`)
+* Don't use `_$x` or `_$[["x"]]` since this package must work on R 4.1.
+* Use `\() ...` for single-line anonymous functions. For all other cases, use `function() {...}` 
 
 ### Testing
 
-- Use `devtools::test()` to run all tests
-- Use `devtools::test_file("tests/testthat/test-filename.R")` to run tests in a specific file
-- DO NOT USE `devtools::test_active_file()`
-- All testing functions automatically load code; you don't needs to.
-
+- Tests for `R/{name}.R` go in `tests/testthat/test-{name}.R`. 
 - All new code should have an accompanying test.
-- Tests for `R/{name}.R` go in `tests/testthat/test-{name}.R`.
 - If there are existing tests, place new tests next to similar existing tests.
+- Strive to keep your tests minimal with few comments.
 
 ### Documentation
 
-- Run `devtools::document()` after changing any roxygen2 docs.
-- Every user facing function should be exported and have roxygen2 documentation.
-- Whenever you add a new documentation file, make sure to also add the topic name to `_pkgdown.yml`.
-- Run `pkgdown::check_pkgdown()` to check that all topics are included in the reference index.
-- Use sentence case for all headings
-
-## Core Architecture
-
-### Main Components
-
-1. **Abstract Syntax Trees** (`R/ast.R`):
-   - `ast()` - Visualizes R expression structure as a tree
-   - Recursively processes calls, symbols, and literals
-   - Uses rlang for quosure handling and expression manipulation
-   - Output formatting handled by tree display utilities
-
-2. **Reference Tracking** (`R/ref.R`, `src/address.cpp`):
-   - `ref()` - Shows memory addresses and shared references
-   - `obj_addr()`, `obj_addrs()` - Get memory locations of objects
-   - Tracks how objects are shared across data structures
-   - Handles lists, environments, and optionally character vectors (global string pool)
-   - Uses depth-first search with seen tracking to avoid infinite loops
-
-3. **Object Size Calculation** (`R/size.R`, `src/size.cpp`):
-   - `obj_size()` - Computes memory size accounting for shared references
-   - `obj_sizes()` - Shows individual contributions of multiple objects
-   - Handles ALTREP objects correctly (R 3.5+)
-   - Smart environment handling: stops at global, base, empty, and namespace environments
-   - C++ implementation traverses object tree with deduplication
-
-4. **Call Stack Trees** (`R/cst.R`):
-   - `cst()` - Displays call stack relationships
-   - Wrapper around `rlang::trace_back()` with simplified output
-   - Shows how frames are connected through parent relationships
-
-5. **Low-Level Inspection** (`R/sxp.R`, `src/inspect.cpp`):
-   - `sxp()` - Deep inspection of C-level SEXP structures
-   - Recursive descent into R's internal data structures
-   - Optional expansion of: character pool, ALTREP, environments, calls, bytecode
-   - Returns structured list with metadata (type, length, address, named status, etc.)
-
-6. **Memory Utilities** (`R/mem.R`):
-   - `mem_used()` - Current R memory usage via `gc()`
-   - Platform-aware node size calculation (32-bit vs 64-bit)
-
-7. **Generic Tree Printing** (`R/tree.R`):
-   - `tree()` - General-purpose tree printer for nested lists
-   - Highly customizable (depth, length limits, value/class printers)
-   - Handles environments with cycle detection
-   - Attribute display support
-
-### Key Design Patterns
-
-- **Tree Visualization**: Consistent tree-based output across all functions using shared utilities (`R/tree.R`, `R/utils.R`)
-- **C++ Integration**: Performance-critical operations (memory addresses, size calculation, SEXP inspection) implemented in C++ via cpp11
-- **Reference Tracking**: Inspection functions use `seen` sets to handle cycles and shared references
-- **Lazy Evaluation**: `ast()` and `obj_addr()` use rlang quasiquotation to quote the AST or avoid taking unnecessary references
-- **Testing Stability**: Address normalization in tests (sequential IDs instead of actual pointers)
-
-### File Organization
-
-- `R/` - R source code organized by main user-facing functions
-  - `ast.R`, `ref.R`, `size.R`, `cst.R`, `sxp.R` - Main visualization functions
-  - `mem.R` - Memory utilities
-  - `address.R` - Address helper functions
-  - `tree.R` - Generic tree printing infrastructure
-  - `utils.R` - Shared utilities (string, display, box characters)
-- `src/` - C++ source code using cpp11
-  - `address.cpp` - Memory address extraction
-  - `size.cpp` - Object size calculation with tree traversal
-  - `inspect.cpp` - Deep SEXP inspection
-  - `utils.h` - Shared C++ utilities
-- `tests/testthat/` - Comprehensive test suite
-
-### C++ Implementation Details
-
-All C++ code uses the cpp11 interface for R integration:
-- Uses `std::set<SEXP>` for tracking seen objects during traversal
-- Implements custom vector size calculation matching R's memory allocation strategy
-- Handles ALTREP objects (R 3.5+) with conditional compilation
-- Recursive tree traversal with depth limits to prevent stack overflow
-- Namespace and special environment detection to avoid infinite recursion
-
-This codebase prioritizes accurate visualization of R's internal structures while maintaining performance through C++ implementation of core algorithms.
+- Every user-facing function should be exported and have roxygen2 documentation.
+- Wrap roxygen comments at 80 characters.
+- Internal functions should not have roxygen documentation.
+- Whenever you add a new (non-internal) documentation topic, also add the topic to `_pkgdown.yml`. 
+- Always re-document the package after changing a roxygen2 comment.
+- Use `pkgdown::check_pkgdown()` to check that all topics are included in the reference index.
+
+### `NEWS.md`
+
+- Every user-facing change should be given a bullet in `NEWS.md`. Do not add bullets for small documentation changes or internal refactorings.
+- Each bullet should briefly describe the change to the end user and mention the related issue in parentheses.
+- A bullet can consist of multiple sentences but should not contain any new lines (i.e. DO NOT line wrap).
+- If the change is related to a function, put the name of the function early in the bullet.
+- Order bullets alphabetically by function name. Put all bullets that don't mention function names at the beginning.
+
+### GitHub
+
+- If you use `gh` to retrieve information about an issue, always use `--comments` to read all the comments.
+
+### Writing
+
+- Use sentence case for headings.
+- Use US English.
+
+### Proofreading
+
+If the user asks you to proofread a file, act as an expert proofreader and editor with a deep understanding of clear, engaging, and well-structured writing. 
+
+Work paragraph by paragraph, always starting by making a TODO list that includes individual items for each top-level heading. 
+
+Fix spelling, grammar, and other minor problems without asking the user. Label any unclear, confusing, or ambiguous sentences with a FIXME comment.
+
+Only report what you have changed.

.claude/settings.json

@@ -0,0 +1,31 @@
+{
+  "permissions": {
+    "$schema": "https://json.schemastore.org/claude-code-settings.json",
+    "defaultMode": "acceptEdits",
+    "allow": [
+      "Bash(air:*)",
+      "Bash(cat:*)",
+      "Bash(find:*)",
+      "Bash(gh issue list:*)",
+      "Bash(gh issue view:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(gh pr view:*)",
+      "Bash(git checkout:*)",
+      "Bash(git grep:*)",
+      "Bash(grep:*)",
+      "Bash(ls:*)",
+      "Bash(R:*)",
+      "Bash(rm:*)",
+      "Bash(Rscript:*)",
+      "Bash(sed:*)",
+      "Skill(*)",
+      "WebFetch(domain:cran.r-project.org)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)"
+    ],
+    "deny": [
+      "Read(.Renviron)", 
+      "Read(.env)"
+    ]
+  }
+}