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/krzysztofzablocki/Sourcery 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 the board

• Last commit 4d ago
• 30+ active contributors
• Distributed ownership (top contributor 24% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{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 krzysztofzablocki/Sourcery repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/krzysztofzablocki/Sourcery.

What it runs against: a local clone of krzysztofzablocki/Sourcery — 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 krzysztofzablocki/Sourcery | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of krzysztofzablocki/Sourcery. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/krzysztofzablocki/Sourcery.git
#   cd Sourcery
#
# 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 krzysztofzablocki/Sourcery and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "krzysztofzablocki/Sourcery(\\.git)?\\b" \\
  && ok "origin remote is krzysztofzablocki/Sourcery" \\
  || miss "origin remote is not krzysztofzablocki/Sourcery (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
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/krzysztofzablocki/Sourcery"
  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).

Sourcery is a meta-programming code generator for Swift that eliminates boilerplate by analyzing your source code with Apple's SwiftSyntax and automatically generating conformances, mocks, and other repetitive code via Stencil templates. It's used in 40,000+ projects including Airbnb and The New York Times to generate hundreds of lines of mock implementations, equality conformances, and Codable implementations automatically. Monolithic Swift Package (Package.swift) with the core code generation engine at the root, Plugins/SourceryCommandPlugin/ providing Xcode integration, .sourcery-macOS.yml and .sourcery-ubuntu.yml as example configurations, and CI workflows in .github/workflows/ testing on both platforms. Heavy reliance on SwiftSyntax for AST parsing and Stencil for template rendering.

iOS/macOS Swift developers who are tired of writing repetitive boilerplate for protocol mocks, Equatable/Hashable conformances, and other generated code. Test engineers building mock frameworks, and platform teams establishing code generation workflows across their organization.

Highly mature and production-ready. The project has 15,000+ GitHub stars, is used by Fortune 500 companies, includes comprehensive CI/CD across macOS and Ubuntu (.github/workflows/), has an active community of contributors, maintains both CLI and Xcode plugin (Plugins/SourceryCommandPlugin/) distributions, and regularly ships updates via Homebrew.

Very low risk. Actively maintained with strong community adoption and regular releases via GitHub Actions workflows. Primary risk is the Swift/Xcode ecosystem dependency chain—SwiftSyntax version compatibility matters significantly—but this is documented in .swift-version and Package.resolved. No single-maintainer bottleneck evident from contributor graphs.

Active development with recent Xcode plugin support, cross-platform CI testing (test_macOS.yml, test_ubuntu.yml), Homebrew distribution automation (bump_homebrew.yml), and documentation updates via jazzy (jazzy.yaml). The Plugins/ directory suggests recent work on native Xcode integration beyond the CLI tool.

Clone with submodules: git clone --recursive https://github.com/krzysztofzablocki/Sourcery.git. Install via Homebrew: brew install sourcery or build locally: swift build -c release. Verify with sourcery --version. Test configuration exists in .sourcery-macOS.yml showing a minimal working setup.

Daily commands: Development: swift build creates executable in .build/debug/sourcery. Run with sourcery --help to see options. Watch mode: sourcery watch --sources . --output Generated/. Use included configurations: sourcery --config .sourcery-macOS.yml. The Rakefile and Scripts/ directory contain automation for package building and distribution.

• Package.swift: Defines the entire Swift package structure, dependencies (SwiftSyntax, Stencil), and build targets for CLI and plugins
• Plugins/SourceryCommandPlugin/SourceryCommandPlugin.swift: Xcode integration layer—enables sourcery to run as a native Xcode build phase via SPM Plugins
• .sourcery-macOS.yml: Canonical example configuration showing how to configure template sources, output paths, and code generation rules
• .github/workflows/test_macOS.yml: CI pipeline for macOS testing—reveals the minimum Swift version, test commands, and validation strategy
• .jazzy.yaml: Documentation generation config—shows how API docs are built and deployed to krzysztofzablocki.github.io/Sourcery
• LinuxMain.swift: Linux-specific test manifest—indicates platform support and test organization structure
• Dockerfile: Container image definition for reproducible builds and CI/CD—shows exact dependencies and build environment

For template features: study Resources/ and examine .sourcery-macOS.yml examples. For parser improvements: SourceryFramework (inferred) handles SwiftSyntax integration—this is where AST analysis happens. For CLI: entry point likely in Sources/SourceryCLI or main.swift. For tests: LinuxMain.swift indicates test organization; run via swift test. For distribution: Scripts/package_content and .github/workflows/ handle release automation.

Swift version pinning: .swift-version and Package.resolved lock specific Swift/SwiftSyntax versions—updating SwiftSyntax requires careful validation since AST changes break parsing. Plugin setup: Xcode plugin requires Xcode 14.0+; older projects won't support build phase integration. Template errors fail silently: malformed Stencil templates in user configs may not produce obvious error messages. Watch mode on file systems: daemon.gif suggests watch mode exists, but filesystem watchers behave differently on macOS (FSEvents) vs Linux (inotify), causing potential timing issues. Homebrew version lag: bump_homebrew.yml automates releases, but there's typically a 1-2 day lag for formula availability.

• Abstract Syntax Tree (AST) Visitor Pattern — Sourcery walks the Swift AST generated by SwiftSyntax to extract type information, method signatures, and conformances—understanding visitor traversal is fundamental to extending the code generator
• SwiftSyntax — The core parsing library that Sourcery uses to build and traverse the AST—version mismatches between SwiftSyntax and your Swift/Xcode version will break code generation
• Stencil Templating Language — Users write Stencil templates to define code generation rules; understanding template filters, control flow, and variable scoping is essential for writing custom generators beyond the built-in ones
• Meta-programming / Code Generation — Sourcery is fundamentally a meta-programming tool that generates code at build time to avoid runtime reflection costs—understanding the trade-offs between static generation and runtime introspection is critical
• Protocol Conformance Synthesis — Sourcery's primary use case is auto-generating Equatable, Hashable, and Codable conformances for types; understanding Swift's protocol system and conformance rules is necessary for debugging generator output
• Daemon/Watch Mode — Sourcery can run in watch mode (daemon.gif hints at this feature) to regenerate code on file changes during development—understanding file system event handling and incremental generation prevents stale code
• Swift Package Plugins (SPM Plugins) — Plugins/SourceryCommandPlugin/ integrates Sourcery into Xcode via SPM Plugins—understanding how build phase plugins work is essential for modern Xcode integration beyond the legacy CLI tool

• apple/swift-syntax — The underlying AST library that Sourcery depends on—essential to understand for parser modifications and version compatibility issues
• stencilproject/stencil — The templating engine Sourcery uses; mastering Stencil is required for writing custom code generation templates
• realm/SwiftLint — Complementary Swift linting tool that Sourcery often pairs with (included in repo via .swiftlint.yml) to enforce code quality on generated code
• kishikawakatsumi/SourceKitten — Alternative AST parsing library for Swift that some users prefer; SourceKittenFramework integration may exist in Sourcery for enhanced code intelligence
• nicklockwood/SwiftFormat — Common downstream tool—Sourcery often feeds generated code to SwiftFormat for consistent formatting in CI pipelines

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 test coverage for Sourcery Command Plugin (SourceryCommandPlugin.swift)

The Plugins/SourceryCommandPlugin/SourceryCommandPlugin.swift file exists but there are no visible test files for the Swift Package Manager command plugin. This is critical because plugins are a key distribution mechanism for Sourcery on modern Swift projects, and lacking tests means regressions could break the plugin workflow silently.

• [ ] Create Tests/SourceryCommandPluginTests/ directory structure
• [ ] Add unit tests for SourceryCommandPlugin.swift covering plugin invocation, argument parsing, and file I/O
• [ ] Integrate plugin tests into Package.swift test targets
• [ ] Add plugin test execution to .github/workflows/test_macOS.yml and test_ubuntu.yml

Add GitHub Actions workflow for testing Swift Package Manager integration

While test_macOS.yml and test_ubuntu.yml exist, there's no dedicated workflow validating that sourcery-build-tool-plugin and SourceryCommandPlugin work correctly in realistic SPM project scenarios. This is important because users rely on swift package sourcery command working seamlessly.

• [ ] Create .github/workflows/test_spm_plugin.yml workflow
• [ ] Add steps to create a minimal SPM project, add Sourcery as a plugin dependency, and run code generation
• [ ] Verify generated code compiles and matches expected output
• [ ] Test on both macOS and Ubuntu runners to ensure cross-platform compatibility

Add missing documentation section for LINUX.md on Swift Package Manager plugin usage

LINUX.md exists but the current file structure suggests it may not document the modern SPM plugin approach (Plugins/SourceryCommandPlugin/). With .swiftVersion and Package.swift in place, Linux users need clear instructions on how to use Sourcery as an SPM plugin rather than just Homebrew installation.

• [ ] Review current LINUX.md and identify gaps in SPM plugin documentation
• [ ] Add 'Using Sourcery as an SPM Plugin' section with example Package.swift configuration
• [ ] Include step-by-step examples for common workflows (dependency declaration, invocation, output handling)
• [ ] Add troubleshooting section specific to Linux environment (Swift version requirements, path issues)

• Add Swift package-level documentation to Sources/ directories explaining the AST visitor pattern and how SwiftSyntax declarations are traversed—currently no in-code docs visible in file list
• Create a troubleshooting guide documenting common Stencil template errors with examples, since .sourcery-macOS.yml suggests users write custom templates but no validation documentation is referenced
• Add integration tests for the Xcode command plugin (Plugins/SourceryCommandPlugin/) that verify build phase invocation succeeds on different Xcode 14+ versions—currently only CLI tests are visible

The Sourcery repository demonstrates reasonable security practices with automated testing (test_macOS.yml, test_ubuntu.yml) and CI/CD pipelines in place. However, several improvements are recommended: (1) Pin Docker base images to specific SHA256 digests instead of tags; (2) Enhance container metadata and documentation; (3) Implement vulnerability scanning in CI/CD pipelines; (4) Verify pre-commit hook configuration includes security checks; (5) Add artifact signing to release workflows. No hardcoded secrets, SQL injection risks, or XSS vulnerabilities are apparent from the file structure analysis. The codebase follows good practices with security linting (.swiftlint.yml) and code review processes (Dangerfile, PR workflow automation).

• Medium · Dockerfile uses ARG with default values for base images without pinning — Dockerfile (lines 1-2). The Dockerfile uses ARG BUILDER_IMAGE=swift:6.0-jammy and RUNTIME_IMAGE=swift:6.0-jammy-slim without specifying full image digests. This allows for image spoofing or unexpected updates. While 'jammy' provides some versioning, digest pinning is the most secure approach. Fix: Pin Docker images to specific SHA256 digests: FROM swift:6.0-jammy@sha256:<full_digest> to ensure immutable base image versions.
• Medium · Dockerfile apt-get cache not verified with validation — Dockerfile (lines 5-10). The Dockerfile runs 'apt-get update && apt-get install' without using '-y --no-install-recommends' consistently or verifying package checksums. While the cache is properly cleaned with 'rm -r /var/lib/apt/lists/*', package integrity could be enhanced. Fix: Add package verification, use specific versions for critical packages, and consider using '--no-install-recommends' to minimize attack surface.
• Low · Incomplete container metadata in runtime image — Dockerfile (line 20). The runtime image LABEL declaration is incomplete (org.opencontainers.image with no value specified). While not a direct security issue, it suggests incomplete container configuration that could impact supply chain transparency. Fix: Complete container metadata labels including version, source, maintainer, and build timestamp for better provenance tracking.
• Low · No security scanning or signing mentioned in CI/CD — .github/workflows/ and .circleci/. Based on the GitHub workflows visible (.circleci/config.yml, .github/workflows/), there is no evidence of container image scanning, vulnerability scanning, or signed releases documented in the file structure. Fix: Integrate container scanning tools (Trivy, Grype) and implement image signing with cosign or similar tools in CI/CD pipelines.
• Low · Pre-commit hooks present but configuration not visible for verification — .pre-commit-hooks.yaml. A '.pre-commit-hooks.yaml' file exists but its content is not provided, making it impossible to verify if security hooks (linting, secret scanning) are properly configured. Fix: Ensure pre-commit hooks include security checks: secrets detection (detect-secrets), SAST scanning, and code quality validation.
• Low · No visible code signing configuration — .github/workflows/release_*.yml. The repository includes release workflows (release_macOS.yml, release_ubuntu.yml) but no visible code signing or artifact verification strategy is documented in the file structure. Fix: Implement artifact signing (GPG or cosign) and publish signatures alongside releases for user verification.

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.