swiftsyntax-based ast parsing with intelligent caching
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.
Unique: Uses Apple's official SwiftSyntax framework for structurally-aware parsing instead of regex or custom lexers, combined with file-level content hashing for incremental re-parsing — enabling accurate handling of Swift's complex syntax including generics, opaque types, and macro annotations
vs alternatives: More accurate than regex-based parsers (handles edge cases like string literals containing type syntax) and faster than re-parsing on every invocation due to intelligent caching, though slower than simple text-based pattern matching for small files
multi-template language support with stencil, swift, and javascript
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.
Unique: Supports three distinct template languages (Stencil, Swift, JavaScript) with unified access to the same parsed type model, allowing developers to choose the most ergonomic approach — Swift templates can use native language features, Stencil templates leverage familiar Jinja2 syntax, and JavaScript templates enable cross-platform logic
vs alternatives: More flexible than single-language generators (e.g., Sourcegen which only supports Stencil) and more accessible than code-as-configuration approaches (e.g., SwiftGen's YAML) by supporting multiple familiar syntaxes
type model introspection api for templates
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.
Unique: Exposes a rich object model (Type, Method, Variable, Parameter, etc.) to templates with full access to parsed type information including signatures, annotations, and relationships, enabling templates to make sophisticated code generation decisions based on type structure without re-parsing
vs alternatives: More complete than simple string-based type information (enables type-aware generation) and more accessible than requiring templates to parse AST directly (abstracts away syntax details)
multi-platform swift code generation for ios, macos, tvos, watchos
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.
Unique: Parses @available annotations to understand platform-specific APIs and makes this information available to templates, enabling generation of platform-adapted code without requiring templates to manually parse availability syntax
vs alternatives: More maintainable than manual platform-specific code generation (availability information is automatically extracted) and more flexible than single-platform generators, though requires templates to implement platform-specific logic
error reporting and diagnostics with file/line information
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.
Unique: Includes file paths and line numbers in error messages for parsing, template processing, and code generation errors, helping developers quickly locate issues in source code or templates without manual debugging
vs alternatives: More helpful than generic error messages (includes context about location and cause) and more accessible than requiring manual debugging with print statements
annotation-driven code generation with documentation comments
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.
Unique: Extracts code generation directives from documentation comments (/// sourcery: annotations) parsed by SwiftSyntax, allowing developers to declare generation intent inline with type definitions rather than in separate configuration files — the parsed annotations are available to templates as queryable metadata on Type objects
vs alternatives: More discoverable than external configuration files (annotations live next to the code they affect) and more flexible than attribute-based approaches (e.g., @Codable) which require language-level support, though less type-safe than compile-time annotations
type relationship composition and inheritance resolution
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.
Unique: The Composer component explicitly walks the parsed AST to resolve type relationships (inheritance, protocol conformance, generic bindings) into a queryable graph structure, allowing templates to traverse hierarchies and find related types — rather than requiring templates to manually parse relationship information
vs alternatives: More complete than simple type listing (enables hierarchical queries) and more efficient than re-parsing relationships in each template (relationships are computed once during composition phase)
configuration-driven file discovery and multi-source input
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.
Unique: Supports three input source types (direct files, Xcode project targets, Swift package targets) resolved through a unified configuration system that can be specified via YAML or CLI, allowing teams to configure code generation at the project level rather than manually listing files
vs alternatives: More flexible than file-list-based approaches (e.g., specifying individual files) because it understands Xcode and SPM project structures, and more maintainable than CLI-only configuration because YAML files can be version-controlled
+5 more capabilities