uber/needle

Needle is a static and dynamic dependency injection framework for iOS that uses a code generator to analyze Swift source files and produce type-safe dependency providers. It supports both traditional component hierarchies and a pluginized architecture, allowing for modular, dynamically loaded components with runtime lifecycle management. The system ensures build stability through robust parsing, cycle detection, and optimized code serialization, while providing a runtime library for resolving dependencies via key paths.

37 changes.

This period focused on establishing the Needle code generator's foundational structure and refactoring its internal architecture to support modular, concurrent task execution. Significant work was dedicated to implementing and validating pluginized component support, including new data models, parsing logic, and dynamic dependency provider generation. The TicTacToe sample application was also restructured to demonstrate these new capabilities, integrating reactive state management and pluginized dependency injection.

9 changes.

This period focused on establishing the NeedleFoundation framework, introducing a dynamic dependency injection runtime with pluginized component support and comprehensive test coverage. Concurrently, the code generator was refactored to improve parsing performance and visibility handling, while a SwiftUI-MVVM sample application was added to demonstrate the architecture.

The LoggedIn area now provides the core user experience for the Tic-Tac-Toe sample, introducing a LoggedInComponent that wires together the game and score-sheet sub-components, a LoggedInViewController that presents the 'Play TicTacToe' and 'High Scores' buttons, and a ScoreStream implementation that tracks and broadcasts player scores and game-end events via RxSwift.

Sample/MVC/TicTacToe/Sources/LoggedIn · high confidence

The SwiftUI-MVVM sample directory now includes a complete TicTacToe application demonstrating the MVVM architecture with Needle dependency injection. The sample provides a functional iOS app featuring a login screen, game board with move validation, and a high scores view, along with the necessary SwiftUI views, ViewModels, and Needle components to serve as a reference implementation.

Sample/SwiftUI-MVVM · high confidence

The TicTacToeIntegrations sample now includes the GameNonCoreComponent and LoggedInNonCoreComponent classes, which define dependency scopes for the game's non-core logic and wire up the ScoreSheetBuilder and MutableScoreStream. An Info.plist has also been added to configure the new framework bundle.

Sample/Pluginized/TicTacToe/TicTacToeIntegrations · high confidence

Introduces the core source files for a pluginized TicTacToe sample application, including the app delegate, root and game components, view controllers for logged-in/out states, and the Needle-generated dependency injection code. This adds the foundational architecture and UI logic for the sample, demonstrating how to structure a pluginized iOS app with Needle.

Sample/Pluginized/TicTacToe/TicTacToeCore · high confidence

The Tic-Tac-Toe sample app now includes a Score Sheet feature. This change introduces a new view controller that displays player scores in real-time using RxSwift and allows users to dismiss the sheet via an OK button. The component is wired into the app's dependency injection structure (NeedleFoundation) to receive the score stream, and a launch screen storyboard has been added to the base resources.

Sample/MVC/TicTacToe/Sources/Base.lproj, Sample/MVC/TicTacToe/Sources/ScoreSheet · high confidence

The TicTacToe sample app now includes a pluginized ScoreSheet module. This adds a new iOS framework that provides a view controller displaying player scores via a reactive stream and an 'OK' button to signal completion. The module includes the necessary dependency injection component and a corresponding test target to support the plugin architecture.

Sample/Pluginized/TicTacToe/ScoreSheet, Sample/Pluginized/TicTacToe/ScoreSheetTests · high confidence

The Generator now includes an Xcode project file and associated configuration (xcode.xcconfig) to support Carthage integration and IDE-based development, alongside a new .gitignore for Xcode artifacts. Additionally, the tool introduces library wrapper utilities that dynamically load the SourceKit library (sourcekitd) on both macOS and Linux, enabling AST parsing and code generation capabilities across different platforms.

Generator · high confidence

This change establishes the foundational structure of the Needle repository by adding core documentation files (README, API, Generator, Why DI), legal and community guidelines (License, Code of Conduct, Contributing), and build configuration files (Makefile, .gitignore, xcconfig). It introduces the Needle code generator and NeedleFoundation framework documentation, including installation instructions for Carthage, Swift Package Manager, and Homebrew, and sets the iOS deployment target to 9.0.

(repo-wide) · high confidence

This change introduces the foundational Xcode project configuration for NeedleFoundation, establishing the build targets for the main framework, a test support framework, and their respective test bundles. It defines the source file groups for core components (Bootstrap, Component, DependencyProviderRegistry), pluginized components, and internal utilities like StableFNVHasher, while also wiring up the corresponding unit test sources and test targets to enable local development and verification of the library.

NeedleFoundation.xcodeproj · high confidence

NeedleFoundation now provides a new runtime library that enables dynamic dependency injection via the \NEEDLE\_DYNAMIC\ build flag. This adds a \BootstrapComponent\ as the root of the dependency graph, a \Component\ base class with \@dynamicMemberLookup\ support for resolving dependencies via key paths, and a \PluginizedComponent\ system that pairs core components with non-core scopes and manages their lifecycle (active, inactive, deinit). The runtime uses a stable FNV-1a hasher to pre-compute path hashes for efficient provider registration and lookup, and includes a \MockComponentPathBuilder\ in the test support module to facilitate unit testing by allowing mock dependency providers to be registered against simulated component paths.

Sources · high confidence

The generator now includes a new \PluginizedDependencyGraphParser\ that scans Swift source files to build a dependency graph for pluginized components. This parser supports concurrent execution, configurable timeouts, and file exclusion rules (by suffix or path). It performs several validation steps, including detecting duplicate dependencies, linking parent/child relationships, and identifying cycles in plugin extensions and non-core components. Additionally, it validates component instantiations and generates a \needleDependenciesHash\ based on the collected components and dependencies, ensuring build stability.

Generator/Sources/NeedleFramework/Parsing/Pluginized · high confidence

The generator now includes a set of new utility files to support dependency graph printing, source code parsing, and task identification. A new \DependencyGraphPrinter\ allows users to visualize the structure of their dependency hierarchy, while \SwiftSyntaxExtensions\ and \Extensions\ provide helpers for analyzing Swift source code (such as identifying components and dependencies). Additionally, \Constants.swift\ defines core naming conventions (like \BootstrapComponent\ and \Component\), \HashUtils\ enables content hashing for change detection, and \TaskIds.swift\ enumerates the specific generator tasks (e.g., parsing, filtering, serialization) for better tracking and debugging.

Generator/Sources/NeedleFramework/Utilities · high confidence

The Needle dependency injection generator has been updated to version 0.25.1, introducing two new subcommands alongside the existing generation capabilities. Users can now run \needle version\ to check the installed generator version, and \needle print-dependency-tree\ to visualize the static dependency structure starting from a specified root component. The primary \generate\ command has also been expanded with new options, including \--sources-list-format\ for reading source paths from a file, \--exclude-paths\ for path-based exclusions, \--header-doc\ to inject custom documentation, \--emit-input-deps-file\ for pluginized dependency tracking, and configurable timeouts and concurrency limits for parsing and exporting tasks.

Generator/Sources/needle · high confidence

The code generator now supports a new dynamic code path for pluginized components. This change introduces new serialization tasks that produce dynamic dependency providers and plugin extension source code, allowing pluginized components to resolve dependencies dynamically rather than relying solely on static generation. The generator also includes logic to process auxiliary properties from non-core components and plugin extensions, and it skips searching the current scope when fulfilling dependencies to prevent circular or redundant resolution.

Generator/Sources/NeedleFramework/Generating/Pluginized · high confidence

The code generator now includes new serializers to produce the source code for plugin extension providers. This adds logic to generate the provider class name, the class implementation containing dependency properties, and the registration code that registers these providers with the plugin extension registry. Additionally, a serializer handles the generation of dependency property accessors, correctly routing access through either the plugin extension or the non-core component based on the property's source type.

Generator/Sources/NeedleFramework/Generating/Serializers/Pluginized · high confidence

A change to existing behaviour in Generator/bin — 46 commits (4 fixs), 2 files.

Generator/bin · medium confidence · unverified

A new Xcode scheme file (NeedleFoundation.xcscheme) has been added to the project configuration. This scheme defines the build, test, launch, profile, analyze, and archive actions for the NeedleFoundation framework and its associated test targets, enabling developers to run tests and build the project directly within Xcode.

NeedleFoundation.xcodeproj/xcshareddata · high confidence

The project now includes the standard Xcode workspace structure, adding the workspace data file, workspace settings (with autocreate contexts disabled), and IDE workspace checks plist. This ensures the workspace is correctly initialized and shared for development environments.

NeedleFoundation.xcodeproj/project.xcworkspace · high confidence

The TicTacToe sample application has been restructured into the MVC folder and integrated with the released Needle Generator binary. This includes adding the AppDelegate and Info.plist, implementing the LoggedOut component and view controller for player name input, and incorporating the generated NeedleGenerated.swift file which handles dependency provider registration for the application's component hierarchy.

Sample/MVC/TicTacToe/Sources · high confidence

The Tic-Tac-Toe sample application has been reorganized into an MVC structure, introducing a new Root module that manages the app's primary navigation flow. This module implements a reactive PlayersStream using RxSwift to observe player names, automatically switching the displayed view controller between a logged-in game state and a logged-out state based on whether player information is present. The RootComponent now acts as a BootstrapComponent, wiring together the player stream and child components to handle this state-driven UI presentation.

Sample/MVC/TicTacToe/Sources/Root · high confidence

The code generator now includes a new set of internal data models (PluginizedComponent, PluginExtension, PluginizedDependencyGraphNode, etc.) to support the parsing and serialization of plugin extensions. This structural change enables the generator to handle pluginized components and their associated non-core components, laying the groundwork for reduced generated code volume and more accurate dependency provider content.

Generator/Sources/NeedleFramework/Models/Pluginized · high confidence

The Needle code generator now uses a new set of internal data models to represent the parsed structure of Swift source files and the resulting dependency graph. This includes an AST model backed by SwiftSyntax to capture source files and import statements, Component and Dependency models to represent scopes and their protocols, and specialized nodes like DependencyGraphNode and ComponentExtensionNode to handle modular parsing. These models also support tracking parent-child relationships, computing stable hashes for file inputs, and serializing dependency providers, which collectively enable more robust parsing, cycle detection, and optimized code generation.

Generator/Sources/NeedleFramework/Models · high confidence

The Needle generator now uses a dedicated set of post-parsing processors to validate and link component data models before code generation. This change adds specific validators and linkers that detect duplicate component or dependency names, identify ancestor cycles in the dependency graph, verify that components are instantiated correctly (e.g., passing \self\ as the parent argument), consolidate component extensions with their base declarations, and link components to their parent components and dependency protocols. These changes improve the robustness of the build process by catching structural errors early with clear error messages.

Generator/Sources/NeedleFramework/Parsing/Processors · high confidence

The Needle code generator now supports configurable concurrency limits and customizable parsing/exporting timeouts, with automatic retry logic for parsing timeouts to improve reliability on large projects. Additionally, when the --emit-input-deps flag is enabled, the generator writes a file listing all input source files used in the invocation, enabling build systems to track dependencies accurately.

Generator/Sources/NeedleFramework/Entry · high confidence

The Tic-Tac-Toe sample application has been moved into the MVC folder and refactored to use NeedleFoundation for dependency injection. The Game component now explicitly defines dependencies (MutableScoreStream, PlayersStream) and builds the GameViewController, replacing the previous ad-hoc initialization. This change introduces dynamic member lookup for dependencies and alters how the game scope fulfills its requirements, ensuring that dependencies are not searched within the current scope during resolution.

Sample/MVC/TicTacToe/Sources/Game · high confidence

The TicTacToe sample application has been moved into the MVC folder and its Xcode project structure is now defined in the project.pbxproj file. This configuration includes source files for the app's components (Root, LoggedIn, LoggedOut, Game, ScoreSheet), views, and streams, along with dependencies on RxSwift, RxCocoa, and SnapKit. The project also references the NeedleFoundation library and includes a generated NeedleGenerated.swift file, indicating integration with the Needle dependency injection framework.

Sample/MVC/TicTacToe/TicTacToe.xcodeproj · high confidence

The code generator now includes specific processors to handle pluginized components: it automatically links non-core components to their corresponding pluginized components, connects plugin extensions to pluginized components, and validates that no cyclic dependencies exist between a pluginized component, its extension, and its non-core dependency. This ensures that pluginized architectures are correctly wired and free of circular property dependencies during the build process.

Generator/Sources/NeedleFramework/Parsing/Pluginized/Processors · high confidence

The generator's pluginized AST parsing task now filters out internal properties when building component data models for both pluginized and non-core components. This ensures that properties marked as internal are not exposed to the Needle-generated code, preventing access errors or unintended visibility in the resulting dependency graph.

Generator/Sources/NeedleFramework/Parsing/Pluginized/Tasks · high confidence

The code generation logic in the NeedleFramework generator has been restructured from a monolithic approach into a set of specialized, reusable serializer classes (such as DependencyPropsSerializer, DependencyProviderClassSerializer, and OutputSerializer). This refactoring introduces deterministic naming for dependency providers using SHA256 hashes and splits registration code into smaller, 50-line helper functions marked with @inline(never). For users, this results in significantly improved compile times for large codebases by reducing the complexity of the generated Swift source files, while maintaining the same dependency injection capabilities.

Generator/Sources/NeedleFramework/Generating/Serializers · high confidence

The parsing logic in the Generator has been restructured to use a modular, concurrent task-execution framework. The new \DependencyGraphParser\ and \AbstractDependencyGraphParser\ classes orchestrate a pipeline of distinct tasks—filtering, AST production, and parsing—for both component declarations and extensions. This change introduces dedicated validation passes, including checks for duplicate component/dependency names, parent linking, ancestor cycle detection, and component instantiation validation, ensuring that the generated dependency graph is structurally sound before output.

Generator/Sources/NeedleFramework/Parsing · high confidence

The code generation pipeline for dependency providers has been restructured into a modular task-based system (DependencyGraphExporter, DependencyProviderDeclarerTask, DependencyProviderContentTask, and DependencyProviderSerializerTask). This change introduces logic to ignore orphan scopes—components that are not roots and have no parents—preventing them from generating unnecessary provider code. It also alters dependency resolution by excluding the current scope from the search path, ensuring dependencies are only resolved from ancestor scopes. Additionally, the serializer now groups providers by their property sources to reduce code volume, and the exporter includes a check to skip writing the output file if the generated content has not changed, improving build efficiency.

Generator/Sources/NeedleFramework/Generating · high confidence

The parsing logic in the generator has been restructured into distinct, reusable tasks (ASTProducer, ComponentExtensions, ComponentInits, Declarations) to improve modularity. This change introduces support for parsing component extensions, allowing dependencies and properties defined in extension blocks to be recognized. It also filters out internal properties from component declarations, ensuring they are not exposed to generated code, and migrates the underlying syntax parsing to use SwiftSyntax.

Generator/Sources/NeedleFramework/Parsing/Tasks · high confidence

The file filtering logic in the code generator has been restructured from a monolithic approach into distinct, specialized filters (BasicKeywordFilter, ComponentExtensionFilter, ComponentImplFilter, and ComponentInitFilter). This change improves parsing performance and maintainability by separating concerns: basic keyword checks, component extension detection, implementation identification, and instantiation pattern matching are now handled by dedicated classes. Users benefit from more accurate and efficient source code analysis during the generation process.

Generator/Sources/NeedleFramework/Parsing/FileFilters · high confidence

Add unit tests for RootViewController navigation logic; Added test fixtures for Needle component generation; Added test fixtures for invalid component initializations; Added test fixtures for pluginized component scenarios; Added unit tests for NeedleFoundation core components and utilities; Added unit tests for PluginizedPropertiesSerializer; Added unit tests for TicTacToe RootViewController; Added unit tests for the Entry generator; Added unit tests for the Needle Framework parsing and dependency graph pipeline; Added unit tests for the Needle code generator tasks; Added unit tests for the pluginized code generator; Added unit tests for the pluginized dependency graph parser.

The Needle code generator (in Generator/Package.swift) has updated its dependencies to SwiftSyntax 510.0.0+, Swift Tools Support Core 0.2.7, Swift Concurrency 0.6.5+, and Swift Common 0.5.0, and now requires Swift 5.10 tooling. The NeedleFoundation podspec has been updated to version 0.25.1 and now supports Swift 5.2 through 5.6, while the main Package.swift has been set to Swift 5.10 tooling.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 64 → 58 (-5.3)
• Rubric changed (rubric-2026.09.11 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 96 → 95 (-0.1)
• Architecture 94 → 97 (+2.3)
• Maturity 53 → 53 (+0.0)
• Readiness 53 → 40 (-12.3)
• Security 97 → 97 (+0.0)

• Coverage not measured — Swift suite
• Dependency hygiene PARTLY measured — SwiftPM pinning read, dependency currency NOT established
• Duplicate registration methods with different key types. The registry exposes two overloads for registration: one taking an Int (hash) and one taking a String. This forces callers to choose between a hash or a string, or implies internal conversion logic that isn't exposed. It creates ambiguity about whether these are distinct registration paths or if the String version is just a convenience wrapper.
• Duplicated block (19 lines × 2) (Sample/MVC/TicTacToe/Sources/Root/RootComponent.swift)
• Duplicated block (8 lines × 2) (Sample/MVC/TicTacToe/Sources/NeedleGenerated.swift)
• Inconsistent retrieval methods across provider/component types. DependencyProvider, Component, and PluginExtensionProvider use find, while NonCoreComponent uses check. Furthermore, find on Component accepts a skipThisLevel boolean, whereas find on DependencyProvider and PluginExtensionProvider does not, despite likely performing similar lookup logic. check returns an optional T? while find returns non-optional T, implying different error handling or existence guarantees.
• Off the main sequence: NeedleFramework

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

uber/needle was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.