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/apple/swift-algorithms 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

• Last commit 6mo ago
• 41+ active contributors
• Distributed ownership (top contributor 30% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 6mo ago

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

What it runs against: a local clone of apple/swift-algorithms — 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 apple/swift-algorithms | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 202 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "apple/swift-algorithms(\\.git)?\\b" \\
  && ok "origin remote is apple/swift-algorithms" \\
  || miss "origin remote is not apple/swift-algorithms (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"
test -f "Sources/Algorithms/Documentation.docc/Algorithms.md" \\
  && ok "Sources/Algorithms/Documentation.docc/Algorithms.md" \\
  || miss "missing critical file: Sources/Algorithms/Documentation.docc/Algorithms.md"
test -f "Sources/Algorithms/Chain.swift" \\
  && ok "Sources/Algorithms/Chain.swift" \\
  || miss "missing critical file: Sources/Algorithms/Chain.swift"
test -f "Sources/Algorithms/Unique.swift" \\
  && ok "Sources/Algorithms/Unique.swift" \\
  || miss "missing critical file: Sources/Algorithms/Unique.swift"
test -f "Sources/Algorithms/Chunked.swift" \\
  && ok "Sources/Algorithms/Chunked.swift" \\
  || miss "missing critical file: Sources/Algorithms/Chunked.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 202 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~172d)"
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/apple/swift-algorithms"
  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).

Swift Algorithms is an open-source Swift Package Manager library providing battle-tested sequence and collection algorithms—chunking, combinations, permutations, windowing, sampling, and reductions—that extend the Swift standard library without external dependencies. It solves the problem of writing efficient, idiomatic sequence operations by offering highly optimized algorithms like chunked(by:), combinations(ofCount:), and windows(ofCount:) that work directly on any sequence or collection. Flat algorithm library structure: Sources/Algorithms/ contains 60+ individual algorithm files (AdjacentPairs.swift, Chain.swift, Chunked.swift, etc.), each implementing a single algorithm as a type conforming to Sequence/Collection protocols. Guides/ provides markdown documentation with code examples and performance notes for each algorithm. Tests are colocated, and CI runs via GitHub Actions workflow.

Swift app developers (iOS, macOS, server-side) who need efficient, type-safe algorithms for data processing pipelines; library authors building higher-level abstractions on sequences; and contributors interested in functional programming patterns and performance-optimized generic code.

Actively maintained and production-ready. Governed by Apple's Swift evolution process, uses semantic versioning, has comprehensive test coverage via CI/CD in .github/workflows/pull_request.yml, and a 1.2.0+ stable release. The CHANGELOG.md and Guides/ documentation are regularly updated, indicating consistent stewardship and backward-compatibility guarantees under the public API definition in CONTRIBUTING.md.

Very low risk: zero external dependencies (pure Swift stdlib), Apple-backed governance, source-stable API (breaking changes only in major versions per CONTRIBUTING.md), and robust CI validation. Single maintainer risk is minimal given Apple's institutional backing. The only minor risk is that new features require Swift version bumps (documented in README), which may lag older toolchains.

Active maintenance on the swift-algorithms repository with recent focus on expanding algorithm coverage, improving documentation in Guides/, and maintaining compatibility with new Swift language releases. Exact current PRs/milestones are not visible in the file list provided, but the presence of .spi.yml (Swift Package Index configuration) and .swift-format indicates ongoing quality-of-life improvements and documentation publication.

Check README for instructions.

Daily commands: This is a library, not an executable. To use locally: swift build compiles the library; swift test runs the test suite. To experiment with algorithms interactively, create a simple Swift script and import Algorithms or use swift run -c release after adding a simple executable target to Package.swift.

• Package.swift — Defines the Swift package structure, dependencies, and module organization—essential for understanding build configuration and how the library is distributed.
• Sources/Algorithms/Documentation.docc/Algorithms.md — Primary documentation entry point that categorizes all algorithms by functional area and serves as the reference guide for the entire package API.
• Sources/Algorithms/Chain.swift — Foundational sequence composition primitive used throughout the library; demonstrates the core pattern for lazy, composable algorithm implementations.
• Sources/Algorithms/Unique.swift — Exemplifies the filtering/transformation pattern used across multiple algorithms; commonly referenced for understanding lazy evaluation and protocol conformance.
• Sources/Algorithms/Chunked.swift — Complex algorithm implementation demonstrating multi-variant support (by predicate, on keypath, size) and the bidirectional collection pattern used throughout.
• README.md — High-level overview of package purpose, philosophy, and quickstart examples; required reading for onboarding and understanding design goals.
• CONTRIBUTING.md — Defines contribution standards, naming conventions, and expectations for adding new algorithms—critical for maintaining consistency across the codebase.

Add a New Lazy Sequence Algorithm

1. Create a new file in Sources/Algorithms/{AlgorithmName}.swift defining a struct conforming to Sequence and LazySequenceProtocol (Sources/Algorithms/Chain.swift)
2. Implement the struct's iterator type with __consuming next() method for lazy evaluation (Sources/Algorithms/Unique.swift)
3. Add an extension method to Sequence returning your new struct (e.g., func myAlgorithm(...) -> MyAlgorithmSequence) (Sources/Algorithms/Chunked.swift)
4. Create corresponding test file in Tests/SwiftAlgorithmsTests/{AlgorithmName}Tests.swift with lazy and eager evaluation tests (Tests/SwiftAlgorithmsTests/ChainTests.swift)
5. Add a Guides/{AlgorithmName}.md markdown file demonstrating usage and edge cases (Guides/Chain.md)
6. Update Documentation.docc/{Category}.md to include reference to new algorithm (Sources/Algorithms/Documentation.docc/Filtering.md)

Add a New Collection Mutating Algorithm

1. Create Sources/Algorithms/{AlgorithmName}.swift implementing in-place mutation for RandomAccessCollection (Sources/Algorithms/Partition.swift)
2. Define mutating method via extension on Collection with generic constraints matching storage requirements (Sources/Algorithms/Rotate.swift)
3. Add error handling and edge case guards (empty collections, out-of-bounds indices) (Sources/Algorithms/Partition.swift)
4. Write comprehensive tests covering inplace behavior, index preservation, and boundary conditions (Tests/SwiftAlgorithmsTests/PartitionTests.swift)

Add Multi-Variant Algorithm (e.g., chunked(by:), chunked(on:), chunked(into:))

1. Define base struct with associated type Iterator conforming to IteratorProtocol (Sources/Algorithms/Chunked.swift)
2. Create separate iterator types for each variant (PredicateIterator, KeyPathIterator, SizeIterator) (Sources/Algorithms/Chunked.swift)
3. Add three extension methods to Sequence/Collection, each returning the base struct with different iterator configuration (Sources/Algorithms/Chunked.swift)
4. Implement comprehensive tests for each variant including empty input, single element, and edge cases (Tests/SwiftAlgorithmsTests/ChunkedTests.swift)
5. Create Guides/{AlgorithmName}.md explaining when to use each variant with practical examples (Guides/Chunked.md)

• Swift Protocol-Based Generics — Enables zero-cost abstractions and type-safe composition; LazySequenceProtocol ensures lazy evaluation without runtime overhead.
• Iterator Pattern with Associated Types — Allows custom state management per algorithm iteration; avoids closures and heap allocation for simple stateful algorithms.
• Bidirectional & RandomAccess Collection Conformance — Enables algorithms to work on slices and views with preserved index semantics; critical for in-place operations like partition and rotate.
• DocC Documentation Format — Integrates documentation directly into Xcode; supports interactive examples and symbol links for discoverability.

• Lazy evaluation via Sequence/IteratorProtocol vs eager Array-returning methods
  • Why: Lazy avoids intermediate
  • Consequence: undefined

No significant hidden traps: the library is dependency-free and self-contained. Minor notes: (1) Algorithms are implemented lazily via Sequence wrappers, so they do not eagerly allocate memory—this can surprise developers expecting immediate results; (2) Some algorithms (e.g., Combinations, Permutations) have combinatorial complexity and will be slow on large inputs by design; (3) The public API is strictly underscored vs. non-underscored symbols—internal helpers won't be part of stability guarantees.

• Lazy Sequence Evaluation — Most Algorithms are implemented as lazy wrappers (e.g., ChunkedSequence) that defer computation until values are consumed; understanding this prevents unnecessary memory allocation and enables composing multiple algorithms efficiently
• Protocol-Oriented Programming (Swift) — Algorithms leverage Swift's Sequence and Collection protocols for generic, type-safe operations that work on any conforming type; mastering this pattern is essential to reading and extending the codebase
• Generator/Iterator Pattern — Each algorithm wraps an iterator to produce elements on-demand; understanding State, Index, and makeIterator() is critical for implementing new algorithms
• Combinatorics (Permutations, Combinations) — Algorithms like Permutations.swift and Combinations.swift implement combinatorial mathematics; understanding their complexity (factorial growth) prevents performance pitfalls
• Stride and Window Sliding — Algorithms like Windows.swift and Stride.swift use index arithmetic and buffer rotation; understanding these techniques is needed to work with positional sequence traversals
• Semantic Versioning & Source Stability — The codebase enforces strict public API contracts (non-underscored symbols only) and only allows breaking changes in major versions; this is critical for understanding what can safely change in contributions

• apple/swift-collections — Sister Apple project providing OrderedDictionary, Deque, and other collection types that complement Algorithms for data structure needs
• pointfreeco/swift-algorithms — Point-Free's education-focused algorithm library with functional programming patterns; provides alternative learning resources and complementary techniques
• apple/swift-standard-library-preview — Experimental Swift stdlib features that Algorithms algorithms sometimes backport or prepare the ground for standardization
• apple/swift-async-algorithms — Companion library extending Algorithms to async sequences and async iterators for concurrent programming patterns
• realm/SwiftLint — Enforces Swift style guidelines; the Algorithms repo uses similar principles (see .swift-format) for consistent code quality

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 EitherSequence.swift

EitherSequence.swift exists in Sources/Algorithms/ but there is no corresponding test file visible in the repository structure. This is a core utility type that likely needs thorough test coverage for both success and error paths, edge cases, and performance characteristics. Adding tests would improve reliability and serve as documentation for how EitherSequence should behave.

• [ ] Create Tests/AlgorithmsTests/EitherSequenceTests.swift
• [ ] Add tests for initialization and basic iteration of EitherSequence
• [ ] Add tests for error handling and edge cases (empty sequences, single elements)
• [ ] Add tests for protocol conformances (Sequence, Collection if applicable)
• [ ] Ensure tests follow the pattern of existing test files in the repository
• [ ] Run full test suite to verify no regressions

Create missing Guides for algorithms in Sources/ that lack documentation

The Guides/ directory contains .md files for many algorithms (AdjacentPairs.md, Chain.md, Chunked.md, etc.), but EitherSequence.swift has no corresponding Guides/EitherSequence.md. Additionally, examining Sources/Algorithms/ for any other algorithms without guides would catch documentation gaps. These guides are critical for user adoption and understanding of the library.

• [ ] Audit all .swift files in Sources/Algorithms/ against files in Guides/
• [ ] Identify any algorithms without corresponding .md guides
• [ ] Create Guides/EitherSequence.md with clear examples and use cases
• [ ] Follow the structure and format of existing guides (e.g., Guides/Chain.md)
• [ ] Add code examples showing practical usage scenarios
• [ ] Update Guides/README.md to include links to any newly documented algorithms

Add integration tests for algorithm chaining and composition patterns

While individual algorithms likely have unit tests, there are no visible test files that demonstrate composing multiple algorithms together (e.g., chaining .chunked().indexed().compacted()). This is a common use case in the Algorithms library and adding integration tests would validate that algorithms compose correctly, catch subtle interaction bugs, and provide reference patterns for users.

• [ ] Create Tests/AlgorithmsTests/CompositionTests.swift
• [ ] Add tests for chaining 2-3 algorithms together in realistic scenarios
• [ ] Add tests demonstrating the examples from README.md and Guides/
• [ ] Test memory and performance characteristics of common compositions
• [ ] Ensure test cases cover both lazy and eager evaluation combinations
• [ ] Run performance benchmarks to document baseline behavior

• Add comprehensive documentation and examples for the adjacentPairs() and intersperse() algorithms in Guides/; these are lower-complexity algorithms but Guides/ coverage is sparse for some newer additions.
• Expand the test suite for edge cases in Sources/Algorithms/Chunked.swift and Sources/Algorithms/Chain.swift for empty sequences, single-element sequences, and infinite sequences to improve coverage metrics.
• Create a performance benchmarking guide in Guides/ with timing comparisons (naive vs. optimized) for Combinations, Permutations, and Windows algorithms to help users understand when to use each approach.

The swift-algorithms repository is a well-maintained, open-source Swift algorithms library with a strong security posture. No critical vulnerabilities were identified in the static analysis. The codebase follows secure development practices with clear governance (CODE_OF_CONDUCT.md, CONTRIBUTING.md) and CI/CD workflows. Minor recommendations focus on dependency transparency and supply chain security best practices.

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.