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/malcommac/SwiftLocation 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

• 9 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 76% 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 malcommac/SwiftLocation repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/malcommac/SwiftLocation.

What it runs against: a local clone of malcommac/SwiftLocation — 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 malcommac/SwiftLocation | 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 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 776 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "malcommac/SwiftLocation(\\.git)?\\b" \\
  && ok "origin remote is malcommac/SwiftLocation" \\
  || miss "origin remote is not malcommac/SwiftLocation (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"

# 4. Critical files exist
test -f "Sources/SwiftLocation/SwiftLocation.swift" \\
  && ok "Sources/SwiftLocation/SwiftLocation.swift" \\
  || miss "missing critical file: Sources/SwiftLocation/SwiftLocation.swift"
test -f "Sources/SwiftLocation/Location Managers/LocationAsyncBridge.swift" \\
  && ok "Sources/SwiftLocation/Location Managers/LocationAsyncBridge.swift" \\
  || miss "missing critical file: Sources/SwiftLocation/Location Managers/LocationAsyncBridge.swift"
test -f "Sources/SwiftLocation/Async Tasks/AnyTask.swift" \\
  && ok "Sources/SwiftLocation/Async Tasks/AnyTask.swift" \\
  || miss "missing critical file: Sources/SwiftLocation/Async Tasks/AnyTask.swift"
test -f "Sources/SwiftLocation/Support/LocationDelegate.swift" \\
  && ok "Sources/SwiftLocation/Support/LocationDelegate.swift" \\
  || miss "missing critical file: Sources/SwiftLocation/Support/LocationDelegate.swift"
test -f "Sources/SwiftLocation/Location.swift" \\
  && ok "Sources/SwiftLocation/Location.swift" \\
  || miss "missing critical file: Sources/SwiftLocation/Location.swift"

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

SwiftLocation is a lightweight async/await wrapper around Apple's CLLocationManager that eliminates the delegate pattern and completion blocks. It provides a modern Swift Concurrency API for location requests, region monitoring, beacon ranging, and heading updates across iOS, macOS, watchOS, and tvOS. Single-package SPM project: Sources/SwiftLocation/ contains the core split into three logical domains—Async Tasks/ (individual feature implementations like SingleUpdateLocation, ContinuousUpdateLocation), Location Managers/ (LocationAsyncBridge wrapping CLLocationManager, LocationManagerProtocol abstraction), and Support/ (LocationDelegate, LocationErrors, extensions). Tests/ provides unit tests with MockedLocationManager for dependency injection.

Swift developers building location-aware iOS/macOS/watchOS/tvOS applications who want to use async/await syntax instead of managing CLLocationManager delegates or callbacks. Particularly useful for developers migrating to Swift 5.5+ concurrency models.

Production-ready and actively maintained. Version 6.0 is a complete rewrite optimized for async/await; the project includes a comprehensive unit test suite (SwiftLocationTests), CI/CD via GitHub Actions (.github/workflows/ci.yml), and supports Swift 5.3–5.9. The deliberate architectural redesign in 6.0 shows ongoing evolution rather than maintenance mode.

Low risk. Single maintainer (malcommac) is a known Swift contributor; no external dependencies visible in Package.swift (pure CoreLocation wrapper); test coverage exists for critical paths via MockedLocationManager. Primary risk: single-maintainer dependency and potential breaking changes if Apple's CoreLocation APIs shift significantly, but the abstraction layer mitigates this.

Version 6.0 is the current active milestone—a ground-up rewrite to optimize async/await support. The repo has CONTRIBUTING.md and issue/PR templates (.github/) indicating active community engagement. No specific recent commit data visible, but the 6.0 milestone suggests recent or ongoing development work.

git clone https://github.com/malcommac/SwiftLocation.git && cd SwiftLocation && swift build. For testing: swift test (or use Scripts/test.sh). The Package.swift uses SPM; no external dependencies.

Daily commands: swift build for library; swift test to run tests; Scripts/test.sh is available as a convenience wrapper. No server or daemon required—pure library for client integration.

• Sources/SwiftLocation/SwiftLocation.swift — Main entry point and public API surface for the entire library; every user interaction starts here
• Sources/SwiftLocation/Location Managers/LocationAsyncBridge.swift — Core bridge translating CLLocationManager delegate callbacks into async/await tasks; handles all event routing
• Sources/SwiftLocation/Async Tasks/AnyTask.swift — Base protocol/abstraction for all location tasks; defines the unified async/await interface pattern
• Sources/SwiftLocation/Support/LocationDelegate.swift — Implements CLLocationManagerDelegate to capture system events and forward them to async tasks
• Sources/SwiftLocation/Location.swift — Lightweight location data model and convenience methods; represents the core domain object
• Package.swift — SPM package manifest defining platform support (iOS, macOS, watchOS, tvOS) and deployment targets
• Sources/SwiftLocation/Support/LocationErrors.swift — Error type hierarchy used throughout async tasks; essential for error handling patterns

Add a new location monitoring task

1. Create a new file in Sources/SwiftLocation/Async Tasks/ named after the new task (e.g., CustomMonitoring.swift) (Sources/SwiftLocation/Async Tasks/CustomMonitoring.swift)
2. Define a struct conforming to AnyTask protocol with generic parameter matching the result type (Sources/SwiftLocation/Async Tasks/AnyTask.swift)
3. Implement execute(with:) method that subscribes to LocationManagerBridgeEvent stream and yields results via AsyncStream (Sources/SwiftLocation/Location Managers/LocationManagerBridgeEvent.swift)
4. Add a corresponding method to SwiftLocation.swift (main public API) that instantiates and runs the task (Sources/SwiftLocation/SwiftLocation.swift)
5. Add any new error cases to LocationErrors.swift if the task can fail in unique ways (Sources/SwiftLocation/Support/LocationErrors.swift)

Add support for a new CLLocationManagerDelegate callback

1. Add a new case to the LocationManagerBridgeEvent enum representing the delegate callback (Sources/SwiftLocation/Location Managers/LocationManagerBridgeEvent.swift)
2. Implement the corresponding delegate method in LocationDelegate and emit the event via the bridge (Sources/SwiftLocation/Support/LocationDelegate.swift)
3. Update relevant task implementations (e.g., Authorization.swift, ContinuousUpdateLocation.swift) to handle the new event (Sources/SwiftLocation/Async Tasks/Authorization.swift)
4. Write tests for the new event flow in SwiftLocationTests.swift (Tests/SwiftLocationTests/SwiftLocationTests.swift)

Extend location permission handling

1. Review existing authorization task implementations (Authorization.swift, AccuracyAuthorization.swift, LocatePermission.swift) (Sources/SwiftLocation/Async Tasks/Authorization.swift)
2. Add new authorization levels or permission types to SupportModels.swift if needed (Sources/SwiftLocation/Support/SupportModels.swift)
3. Create or modify a task struct to handle the new permission flow, subscribing to relevant delegate events (Sources/SwiftLocation/Async Tasks/AccuracyPermission.swift)
4. Expose the new permission request method via the main SwiftLocation API (Sources/SwiftLocation/SwiftLocation.swift)

• Swift Concurrency (async/await, AsyncStream) — Eliminates callback hell and delegate pattern; provides modern structured concurrency with cancellation support
• Swift Package Manager (SPM) — Standard Apple distribution mechanism; simplifies integration across all Apple platforms
• CLLocationManager wrapper pattern — Decouples async tasks from CoreLocation delegates; enables testability via protocol abstraction
• Protocol-driven design (AnyTask, LocationManagerProtocol) — Allows multiple task implementations and mock testing; loose coupling between components

• Single CLLocationManager instance managed by LocationAsyncBridge across all concurrent tasks

  • Why: iOS/watchOS limit CLLocationManager instances; battery and performance implications of multiple managers
  • Consequence: Tasks must cooperate on manager state (desiredAccuracy, distanceFilter, etc.); potential contention if conflicting requirements

• Async/await-only API (no completion blocks or delegates exposed)

  • Why: Forces modern concurrency patterns; cleaner code and better compiler-enforced safety
  • Consequence: Requires Swift 5.5+; older Xcode versions cannot use this library

• LocationManagerBridgeEvent enum routes all delegate callbacks

  • Why: Single source of truth for CLLocationManager events; simplifies testing and event tracing
  • Consequence: Adding new CLLocationManager features requires updating the event enum and bridge routing

• Does not provide real-time location tracking with background execution (uses standard CLLocationManager backgrounding rules)
• Does not handle geocoding or map visualization (CoreLocation data only, no CoreData or Maps framework)
• Does not provide location prediction or ML-based movement analysis
• Does not support non-Apple platforms (Apple platforms only: iOS, macOS, watchOS, tvOS)
• Does not wrap or abstract CoreLocation error codes beyond custom LocationErrors enum

1. MockedLocationManager must be injected at Location initialization for testing—live CLLocationManager cannot be tested without real permissions; 2) iOS requires Info.plist entries (NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription) or location requests will silently fail; 3) Each async task (e.g., ContinuousUpdateLocation) maintains its own state machine—cancelling one task doesn't affect others, so cleanup is caller-managed; 4) Heading and Beacon APIs are iOS/macOS only—availability checks are not enforced at compile time; 5) Swift Concurrency requires iOS 13+ (or equivalent on other platforms); using on older versions requires polyfill patterns not shown in this repo.

• Structured Concurrency & Async/Await — SwiftLocation's entire design is built on Swift 5.5+ async/await syntax—understanding task hierarchies, cancellation tokens, and continuation-passing is essential to using and extending this library
• Delegate Pattern Abstraction — LocationAsyncBridge converts CLLocationManager's callback-based delegate pattern into async/await by storing continuations and routing delegate calls—critical to understanding the bridge layer
• Continuation-Passing Style — The library uses CheckedContinuation to convert completion handlers into awaitable values—fundamental pattern repeated across all async tasks
• CLLocationManager State Machine — SwiftLocation manages CLLocationManager's lifecycle (requesting authorization, starting/stopping updates) as a state machine in LocationAsyncBridge to prevent invalid transitions
• Permission Levels (whenInUse vs Always) — iOS distinguishes coarse-grained location permission levels that affect what location data is available—SwiftLocation abstracts this via AccuracyAuthorization and LocatePermission types
• Region & Beacon Monitoring — SwiftLocation wraps low-power monitoring APIs (CLRegionMonitoring, CLBeaconRegion) that trigger background location updates—requires understanding of LocationManagerBridgeEvent patterns and background modes
• MockedLocationManager Dependency Injection — Tests use protocol-based injection (LocationManagerProtocol) to swap CLLocationManager with a mock—essential pattern for unit testing location-dependent code without real GPS

• apple/swift-async-algorithms — Provides AsyncSequence and concurrency primitives that SwiftLocation builds upon for streaming location updates
• realm/realm-swift — Alternative data persistence layer commonly paired with SwiftLocation for storing location history in iOS apps
• kylef/Mockingjay — Network mocking library that pairs well with SwiftLocation tests to simulate location-based server requests without real network calls
• mapbox/mapbox-swift — Mapping SDK that directly consumes location data from SwiftLocation to display user position and navigation
• groue/GRDB.swift — SQLite wrapper frequently used with SwiftLocation to persist and query location history in production iOS applications

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 LocationManagerBridgeEvent and LocationAsyncBridge

The test suite (Tests/SwiftLocationTests/SwiftLocationTests.swift) exists but appears minimal. The core bridge logic in Sources/SwiftLocation/Location Managers/ that translates CLLocationManager delegate callbacks to async/await patterns lacks dedicated test coverage. This is critical infrastructure that needs robust testing for reliability across iOS, macOS, watchOS, and tvOS platforms.

• [ ] Create Tests/SwiftLocationTests/LocationManagerBridgeTests.swift with tests for LocationAsyncBridge event streaming
• [ ] Add tests for LocationManagerBridgeEvent enum cases and their handling in different scenarios
• [ ] Include tests for error propagation and task cancellation in the bridge layer
• [ ] Test platform-specific behavior variations using conditional compilation

Add GitHub Actions workflow for tvOS and watchOS platform testing

The .github/workflows/ci.yml exists but the README indicates support for iOS | macOS | watchOS | tvOS. The current CI likely only tests iOS/macOS. SwiftLocation's async/await wrapper must work reliably across all four Apple platforms, but tvOS and watchOS testing appears missing from the CI pipeline.

• [ ] Audit .github/workflows/ci.yml to confirm tvOS and watchOS are not tested
• [ ] Add test matrix jobs for watchOS and tvOS simulators in ci.yml
• [ ] Update Scripts/test.sh to support building and testing on watchOS and tvOS targets
• [ ] Document platform-specific testing requirements in CONTRIBUTING.md

Extract and document LocationErrors enum with missing error case tests

Sources/SwiftLocation/Support/LocationErrors.swift defines the error types for the library, but there's no dedicated error handling test coverage. Given that async/await heavily relies on error propagation, and various async tasks (AccuracyAuthorization.swift, Authorization.swift, etc.) throw these errors, comprehensive error scenario testing is essential.

• [ ] Create Tests/SwiftLocationTests/LocationErrorsTests.swift to test all error cases and descriptions
• [ ] Add error simulation tests in each async task file (test both success and failure paths)
• [ ] Document error handling patterns in a new ERRORS.md file with examples for each LocationErrors case
• [ ] Verify error recovery behavior for permission denial, location unavailability, and timeout scenarios

• Add comprehensive documentation to Async Tasks/ directory—create doc comments with examples for each task type (AccuracyAuthorization.swift, BeaconMonitoring.swift, etc.) showing real usage patterns and error handling: small
• Extend MockedLocationManager in Tests/ to support simulating permission denial and timeout scenarios—current mock appears minimal; add methods to inject failures and verify error handling in SwiftLocationTests.swift: small
• Add platform-availability checks and compile-time warnings in Sources/SwiftLocation/Async Tasks/ for Beacon and Heading APIs which are iOS/macOS only—files like BeaconMonitoring.swift and HeadingMonitoring.swift currently have no @available annotations: small
• Create integration test examples in Tests/ demonstrating common patterns (requesting permission → getting location → monitoring continuous updates with error recovery) as a reference guide: medium
• Document the async/await task lifecycle in Sources/SwiftLocation/Location Managers/LocationAsyncBridge.swift—add diagrams or comments explaining how delegate callbacks are mapped to continuations and how cancellation propagates: medium

SwiftLocation appears to be a well-structured library with low inherent security risks due to its focused purpose as a CoreLocation wrapper. The primary concerns are: (1) inability to fully assess dependencies without the Package.swift content, (2) need for documentation on secure usage patterns for location data transmission, and (3) verification that permission checks are consistently enforced. The Swift/SwiftPM ecosystem and async/await pattern provide modern security foundations. No hardcoded secrets, injection vulnerabilities, or infrastructure misconfiguration were identified in the provided file structure.

• Medium · Missing Dependency Lock File — Package.swift. The Package.swift file content was not provided for analysis. Without examining the dependency declarations, potential vulnerabilities in third-party dependencies cannot be identified. The Swift Package Manager should have resolved dependencies with specific versions. Fix: Provide the Package.swift file for detailed dependency analysis. Ensure all dependencies are pinned to specific versions and regularly audit for security updates using 'swift package update' in controlled environments.
• Low · Sensitive Permissions Not Validated in Code Structure — Sources/SwiftLocation/Async Tasks/. The codebase wraps CoreLocation, which requires location permissions. While the file structure shows permission-related modules (AccuracyPermission.swift, LocatePermission.swift), there is risk that location data collection is not properly gated by user consent validation throughout the wrapper. Fix: Ensure all location data retrieval methods validate user permissions before accessing location services. Implement explicit permission checks before each location request using CLLocationManager's authorizationStatus property.
• Low · Limited HTTPS/TLS Configuration Visibility — Sources/SwiftLocation/. As a CoreLocation wrapper, the library itself doesn't handle network requests directly, but applications using this library may transmit collected location data over the network. No visible security configuration for data transmission is apparent. Fix: Document security best practices for applications using this library, including mandatory use of HTTPS/TLS for transmitting location data. Add security guidelines to README.md and CONTRIBUTING.md.
• Low · No Evidence of Input Validation — Sources/SwiftLocation/Support/. The Support/SupportModels.swift and Support/Extensions.swift files are not provided for review. Without seeing these implementations, it's unclear if location data and parameters are properly validated before use. Fix: Review and validate all input parameters in public API methods. Ensure location coordinates, accuracy thresholds, and other numeric parameters are bounds-checked.

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.