If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mac-cain13/R.swift shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 14 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Single-maintainer risk — top contributor 83% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mac-cain13/R.swift repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mac-cain13/R.swift.

What it runs against: a local clone of mac-cain13/R.swift — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mac-cain13/R.swift | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 434 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mac-cain13/R.swift. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mac-cain13/R.swift.git
#   cd R.swift
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mac-cain13/R.swift and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mac-cain13/R.swift(\\.git)?\\b" \\
  && ok "origin remote is mac-cain13/R.swift" \\
  || miss "origin remote is not mac-cain13/R.swift (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Documentation/Readme.md" \\
  && ok "Documentation/Readme.md" \\
  || miss "missing critical file: Documentation/Readme.md"
test -f "Documentation/Contribute.md" \\
  && ok "Documentation/Contribute.md" \\
  || miss "missing critical file: Documentation/Contribute.md"
test -f ".github/workflows/checks.yml" \\
  && ok ".github/workflows/checks.yml" \\
  || miss "missing critical file: .github/workflows/checks.yml"
test -f ".gitignore" \\
  && ok ".gitignore" \\
  || miss "missing critical file: .gitignore"
test -f "Examples/FileSystemSynchronized" \\
  && ok "Examples/FileSystemSynchronized" \\
  || miss "missing critical file: Examples/FileSystemSynchronized"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 434 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~404d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mac-cain13/R.swift"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

R.swift is a code generator that creates a strongly-typed R struct mirroring your iOS/macOS project's resources (images, fonts, colors, strings, storyboards, nibs, segues). Instead of using error-prone string literals like UIImage(named: "settings-icon"), you write R.image.settingsIcon() with full type safety, autocomplete, and compile-time verification. It integrates as a build phase tool and regenerates the R struct whenever resources change. Single-package Swift tool structure: top-level source code generates R.swift as an executable binary. Examples/ contains FileSystemSynchronized project demonstrating real-world setup with Assets.xcassets, storyboards, and localization bundles (nl.lproj/). Documentation/ houses guides for installation, migration, Q&A, and contribution workflows. Ruby scripts likely handle release automation (.github/workflows/).

iOS/macOS developers building Swift apps who want to eliminate runtime crashes from typos in resource names and gain IDE autocomplete for all assets. Specifically useful for teams working with large Asset Catalogs, localized strings, storyboards, and custom fonts where string-based lookups are error-prone.

Production-ready and actively maintained. The repo shows consistent CI workflows (.github/workflows/checks.yml, release.yml), comprehensive documentation across Documentation/ folder, and multiple example projects (FileSystemSynchronized). Last activity and version tagging via CocoaPods indicates ongoing support for Xcode integration.

Low risk for core functionality, but single-maintainer concern (mac-cain13 organization). Build phase integration means it's tightly coupled to Xcode versions—breaking Xcode updates could require quick fixes. No visible test directory in the file listing is a potential gap, though the example projects may contain integration tests.

Active maintenance visible through CI workflow files (checks.yml for PR validation, release.yml for automated releases). Support for Swift Package Manager build tool plugins (referenced in docs: RswiftSPMInstallation.mp4) indicates recent modernization away from legacy build phases. Documentation updates suggest ongoing effort to ease adoption and address common integration questions.

git clone https://github.com/mac-cain13/R.swift.git
cd R.swift
swift build -c release
# Or examine Examples/FileSystemSynchronized/FileSystemSynchronized.xcodeproj in Xcode

Daily commands: Not a server. Build the Swift executable with swift build -c release, then integrate into your Xcode project as a build phase pointing to the binary, or use SPM build tool plugin. Example projects can be opened in Xcode directly: open Examples/FileSystemSynchronized/FileSystemSynchronized.xcodeproj.

• Documentation/Readme.md — Complete feature overview and value proposition explaining what R.swift does and why it matters
• Documentation/Contribute.md — Setup instructions and contribution guidelines that all new developers must follow
• .github/workflows/checks.yml — CI/CD pipeline configuration defining build and test requirements that all PRs must pass
• .gitignore — Specifies which generated R.swift files and build artifacts should never be committed
• Examples/FileSystemSynchronized — Primary reference example showing the full R.swift integration pattern with Assets, Localization, and Storyboards
• Documentation/Examples.md — Concrete usage examples showing how to access typed resources for images, fonts, colors, and strings
• Documentation/Migration.md — Guide for upgrading existing codebases to R.swift, critical for understanding breaking changes

• R.swift Generator (Swift, file system I/O, Xcode project parsing) — Main code generation engine that introspects Xcode asset catalogs, localization files, storyboards, and other resources; outputs R.swift file with type-safe accessors
  • Failure mode: If generator crashes or encounters malformed resources, build fails; developers must fix resource definitions or configuration
• Build Phase Integration (Xcode build system, shell scripting, Swift Package Manager plugins) — Xcode run script or SPM plugin that invokes R.swift generator at appropriate build stage before Swift compilation
  • Failure mode: If build phase is misconfigured or R.swift binary is missing, build fails; requires developer intervention to restore or fix configuration
• Asset Catalog Parser (JSON parsing, file system traversal) — Reads Assets.xcassets JSON metadata and image files; generates R.image and R.color accessors with correct namespaces
  • Failure mode: Malformed Contents

Add a new Image Resource

1. Create a new image file (.png, .pdf, etc.) in your Assets.xcassets folder (Examples/FileSystemSynchronized/MainUI/Assets.xcassets)
2. Organize in subfolders if desired; R.swift mirrors folder structure as Swift namespaces (Examples/FileSystemSynchronized/MainUI/Assets.xcassets)
3. Run R.swift code generation (typically via build phase or SPM plugin) (.github/workflows/checks.yml)
4. Reference in code using typed R.image.imageName() instead of UIImage(named:) (Examples/FileSystemSynchronized/MainUI/ContentView.swift)

Add Localized Strings

1. Create or edit Localizable.strings files in language-specific .lproj folders (Examples/FileSystemSynchronized/TheAppClip/en.lproj/Localizable.strings)
2. Use dot-notation keys like 'welcome.greeting' to create nested Swift accessors (Examples/LocalizedStringApp/LocalizedStringApp/Base.lproj/eight.strings)
3. Run R.swift code generation to create R.string type-safe accessors (.github/workflows/checks.yml)
4. Call R.string.welcome.greeting() in code with full type safety and IDE autocomplete (Examples/LocalizedStringApp/LocalizedStringApp/AppDelegate.swift)

Configure Resources to Ignore

1. Review Ignoring.md documentation to understand exclusion patterns (Documentation/Ignoring.md)
2. Add .ignoreme suffix to resource filenames (e.g., 'temp.ignoreme.png') (Examples/FileSystemSynchronized/MainUI/Assets.xcassets/hand.ignoreme.imageset)
3. Alternatively configure R.swift settings file with exclusion rules (Documentation/Ignoring.md)
4. Regenerate code; excluded resources will not appear in R.swift output (.github/workflows/checks.yml)

Migrate Existing Project to R.swift

1. Read Migration.md to understand version-specific upgrade paths and breaking changes (Documentation/Migration.md)
2. Follow Contribute.md setup instructions to install R.swift via CocoaPods or SPM (Documentation/Contribute.md)
3. Add R.swift build phase to your Xcode project or configure SPM plugin (Examples/FileSystemSynchronized/FileSystemSynchronized.xcodeproj/project.pbxproj)
4. Replace string-based resource calls with typed R.* accessors per Examples.md (Documentation/Examples.md)

• Swift — R.swift is a Swift code generation tool specifically designed for iOS/macOS projects; Swift provides strong typing and compile-time safety
• Xcode Build Phases & SPM Build Plugins — Enables automatic code generation during build without manual intervention; deeply integrated with native Apple development workflow
• Asset Catalogs (Assets.xcassets) & .strings files — Xcode's native mechanisms for managing images, colors, and localized strings; R.swift introspects these to generate typed interfaces

• Build-time code generation instead of runtime reflection

  • Why: Enables compile-time type checking and eliminates string-based lookups that fail at runtime
  • Consequence: Requires a build step and generated files that must be kept in sync with resources; adds complexity to build pipeline but eliminates entire classes of runtime crashes

• Read-only generated R.swift file auto-overwritten on each build

  • Why: Ensures consistency between resources and generated code; prevents manual edits from diverging
  • Consequence: Developers cannot modify generated file directly; must understand generated code is ephemeral and controlled by build system

• Mirror folder structure as Swift namespaces (e.g., Folder1/Image1 → R.image.folder1.image1())

  • Why: Provides intuitive organization matching file system layout; reduces naming collisions
  • Consequence: Deeply nested resources create deeply nested Swift accessors; folder reorganization invalidates all references (though compiler catches this)

• Exclude resources via .ignoreme suffix or configuration rather than separate list

  • Why: Keeps exclusion rules colocated with resources; minimal configuration overhead
  • Consequence: Less explicit than a dedicated configuration file; naming conventions become part of tribal knowledge

• Runtime resource discovery or reflection (strictly compile-time generation)
• Support for resources outside Xcode's native systems (only Assets.xcassets, .strings, Storyboards, Nib files, Fonts)
• Cross-platform support beyond iOS, macOS, tvOS, watchOS (Swift platform only)
• Manual string resource management (R.swift generates from Xcode-managed files only)
• Dynamic resource loading or late binding

Ignore rules: Documentation/Ignoring.md exists, suggesting .ignoreme suffix is required for assets to be skipped (see hand.ignoreme.imageset). Build phase ordering: R.swift must run before Swift compilation, else generated R.swift won't be found. Custom modules: Documentation/Images/CustomImport.png hints at non-trivial module/import configuration for embedded frameworks. Storyboard segue safety: Segue strongness depends on proper storyboard setup; misconfigured identifiers won't be caught at compile time if not wired correctly. No visible test suite in file listing—integration relies on example projects passing CI.

• Code Generation via AST — R.swift parses .xcassets, .storyboard, and .strings files to generate a Swift struct; understanding how it walks these file formats and emits type-safe Swift code is core to modifying or extending the generator
• Build Phase Integration — R.swift runs as an Xcode build phase before Swift compilation; understanding build phase ordering, artifact caching, and how Xcode passes file lists is critical for debugging integration issues
• String Localization (Stringsdict) — R.swift generates type-safe wrappers around NSLocalizedString and handles plural forms via .stringsdict files; understanding iOS localization structure is essential for working on the strings resource parser
• Xcode Asset Catalog Format — Assets.xcassets is a directory bundle with JSON metadata (Contents.json); R.swift must parse this format to extract image names and properties, requiring knowledge of how Xcode organizes assets
• Storyboard XML & Segue Resolution — R.swift parses .storyboard files (XML format) to extract view controllers, outlets, and segues; understanding storyboard structure is needed to add or improve storyboard resource support
• Swift Package Manager Build Tool Plugins — R.swift migrated from legacy Xcode build phases to SPM plugins (visible in recent docs); understanding how SPM plugins hook into the build system is essential for modern integration and troubleshooting
• Type-Safe Resource Wrappers — R.swift generates Swift structs with computed properties and closures (e.g., R.image.settingsIcon()) that wrap runtime resource lookups; understanding how to design these wrappers for compile-time safety informs contributions to new resource types

• realm/realm-swift — Complementary to R.swift—Realm is often used in the same iOS projects for data persistence while R.swift handles resource type-safety; Realm itself has been featured in similar talks on moving iOS toward strong typing
• SwiftGen/SwiftGen — Direct alternative to R.swift solving the same problem (type-safe resource generation) with different architecture; worth studying for design pattern differences
• Carthage/Carthage — Dependency manager often paired with R.swift installation in iOS projects; users integrate both into the same Xcode build phases
• apple/swift-package-manager — R.swift recently modernized to support SPM build tool plugins (visible in docs); understanding SPM's plugin architecture is essential for contributors working on the SPM integration
• pointfreeco/swift-syntax — If R.swift's code generation uses AST manipulation for generating the R struct, swift-syntax is the canonical library; studying it helps understand how to extend R.swift's code generation safely

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for R.swift code generation in Tests directory

The repo lacks a visible Tests directory despite being a code generation tool. Core functionality like asset parsing, localization string extraction, and Swift code generation needs unit test coverage to prevent regressions. This is critical for a tool that modifies project files.

• [ ] Create Tests/ directory structure mirroring Sources/ organization
• [ ] Add unit tests for image asset parsing (testing various xcassets structures)
• [ ] Add unit tests for localization string extraction (testing Localizable.strings and .stringsdict formats)
• [ ] Add unit tests for Swift code generation output validation
• [ ] Integrate tests into .github/workflows/checks.yml to run on every PR

Document the complete resource type support matrix in Documentation/Readme.md

The README is incomplete (text cut off mid-example). It should explicitly document which resource types are supported (images, fonts, colors, segues, localizations, etc.), what iOS versions are supported, and show complete before/after examples. This helps new users understand R.swift's full capabilities.

• [ ] Complete the truncated example in the README showing all resource types
• [ ] Add a 'Supported Resources' section listing: Images, Colors, Fonts, Segues, Localizations, Storyboards, XIBs, Intent Definitions
• [ ] Add a compatibility matrix (iOS versions, Swift versions, Xcode versions)
• [ ] Add before/after code examples for each resource type
• [ ] Link to Documentation/Examples.md for detailed usage patterns

Add integration test workflow in .github/workflows/ to validate SPM and CocoaPods installations

The repo has release.yml and checks.yml workflows, but lacks an integration test that validates R.swift works end-to-end with real Xcode projects using both SPM (with build tool plugins) and CocoaPods. This prevents installation regressions and validates the examples actually work.

• [ ] Create .github/workflows/integration-tests.yml workflow file
• [ ] Add job to build Examples/FileSystemSynchronized with SPM build tool plugin integration
• [ ] Add job to test R.swift with CocoaPods dependency manager
• [ ] Validate generated R.generated.swift file is correctly created and syntactically valid
• [ ] Test against multiple Xcode versions (current and previous)

• Add unit tests for the Ruby release scripts (.github/workflows/) to validate version bumping and tarball generation—currently only integration-tested via CI.
• Expand Documentation/Examples.md with a 'Common Integration Issues' section covering SPM build plugin setup (currently only explained via video RswiftSPMInstallation.mp4) with step-by-step text and screenshots.
• Create a test case in Examples/ for edge cases like folder names with spaces and special characters (e.g., 'Folder3 copy/Folder3 copy 2/' shown in FileSystemSynchronized) to ensure the parser handles them consistently.

R.swift is a resource code generation tool for iOS/Swift projects with a relatively secure posture. The codebase demonstrates good security practices as a build-time tool that generates strongly-typed Swift code. No critical vulnerabilities were identified in the provided file structure and documentation snippets. However, there are some general recommendations for maintaining security in this tool's usage and distribution.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.