Sourcery

Parses Swift source files using Apple's SwiftSyntax framework (since v1.9.0) to build a complete abstract syntax tree, extracting type definitions, methods, variables, and relationships. Implements an intelligent caching system that fingerprints file contents and skips re-parsing unchanged files, dramatically improving performance on large codebases by avoiding redundant syntax analysis.

Supports three distinct template languages — Stencil (Jinja2-like syntax), native Swift templates, and JavaScript — allowing developers to choose the most ergonomic approach for their code generation needs. Each template language has access to the complete parsed type model through a unified context object, enabling templates to introspect types, iterate over methods/variables, and conditionally generate code based on annotations or type characteristics.

Exposes a comprehensive object model (Type, Class, Struct, Enum, Protocol, Method, Variable, Parameter, etc.) to templates, allowing introspection of type characteristics, methods, properties, and relationships. Templates can query type metadata (name, kind, access level, annotations), iterate over methods and variables with full signature information, and traverse type relationships to make generation decisions based on type structure.

Generates Swift code compatible with multiple Apple platforms (iOS, macOS, tvOS, watchOS) by understanding platform-specific APIs and availability annotations. Templates can query platform availability information and conditionally generate platform-specific code, enabling creation of cross-platform libraries and frameworks that adapt generated code to target platforms.

Provides detailed error messages and diagnostics that include source file paths and line numbers, helping developers quickly locate and fix issues in source code or templates. Errors during parsing, template processing, or code generation include context about what failed and where, reducing debugging time for code generation issues.

Parses documentation comments (/// annotations) embedded in Swift source code to extract metadata that controls code generation behavior. Developers can annotate types, methods, and variables with custom markers (e.g., // sourcery: AutoMockable) that templates can query to conditionally generate code — enabling declarative, in-source configuration of which types receive generated code without separate configuration files.

Builds a complete type relationship graph by composing parsed types to resolve inheritance chains, protocol conformance, and type dependencies. The Composer component walks the parsed AST to establish parent-child relationships, protocol implementations, and generic type bindings, creating a queryable model where templates can traverse inheritance hierarchies, find all types conforming to a protocol, or identify generic type parameters.

Supports flexible input configuration through YAML files (.sourcery.yml) and command-line arguments, enabling developers to specify source files, directories, Xcode project targets, and Swift package targets as input sources. The configuration system resolves these diverse input types into a unified list of Swift files to parse, supporting project-level configuration that can be version-controlled and shared across teams.

Implements optional file system watching that monitors source files and templates for changes, automatically re-running the code generation pipeline when modifications are detected. The watcher uses platform-specific file system events (FSEvents on macOS, inotify on Linux) to trigger incremental re-parsing and re-generation, enabling developers to see generated code updates in real-time during development without manual invocation.

Provides a built-in code generator that automatically creates mock implementations of protocols annotated with // sourcery: AutoMockable. The generator introspects protocol method signatures, parameter types, and return types to synthesize mock objects with recording/verification capabilities, eliminating manual mock writing for unit testing. Mocks include call tracking, argument capture, and return value configuration.

Automatically generates Hashable and Equatable protocol implementations for types annotated with // sourcery: AutoHashable or AutoEquatable. The generator introspects all stored properties of the type and synthesizes hash() and == implementations that include all properties, ensuring consistency between equality and hashing semantics without manual implementation.

Enables developers to write custom code generators by creating templates (in Stencil, Swift, or JavaScript) that have full access to the parsed type model, including types, methods, variables, annotations, and relationships. Templates can iterate over types, filter by annotations or characteristics, and generate arbitrary code based on introspection, allowing creation of domain-specific code generators beyond built-in generators.

Generates output files with awareness of existing content, using diff-based comparison to determine which files have actually changed. Only modified files are written to disk, reducing unnecessary file system churn and avoiding triggering unnecessary Xcode rebuilds. The system preserves file modification times for unchanged files, enabling build systems to skip recompilation when generated code hasn't changed.