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/thoughtbot/Argo 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

• 13 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 5y 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 thoughtbot/Argo repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/thoughtbot/Argo.

What it runs against: a local clone of thoughtbot/Argo — 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 thoughtbot/Argo | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 1719 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "thoughtbot/Argo(\\.git)?\\b" \\
  && ok "origin remote is thoughtbot/Argo" \\
  || miss "origin remote is not thoughtbot/Argo (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 main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Sources/Argo/Types/Decoded/Decoded.swift" \\
  && ok "Sources/Argo/Types/Decoded/Decoded.swift" \\
  || miss "missing critical file: Sources/Argo/Types/Decoded/Decoded.swift"
test -f "Sources/Argo/Types/Decodable.swift" \\
  && ok "Sources/Argo/Types/Decodable.swift" \\
  || miss "missing critical file: Sources/Argo/Types/Decodable.swift"
test -f "Sources/Argo/Functions/decode.swift" \\
  && ok "Sources/Argo/Functions/decode.swift" \\
  || miss "missing critical file: Sources/Argo/Functions/decode.swift"
test -f "Sources/Argo/Types/JSON.swift" \\
  && ok "Sources/Argo/Types/JSON.swift" \\
  || miss "missing critical file: Sources/Argo/Types/JSON.swift"
test -f "Sources/Argo/Types/DecodeError.swift" \\
  && ok "Sources/Argo/Types/DecodeError.swift" \\
  || miss "missing critical file: Sources/Argo/Types/DecodeError.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 1719 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1689d)"
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/thoughtbot/Argo"
  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).

Argo is a functional JSON parsing library for Swift that uses the type system and monadic parsing to extract strongly-typed models from JSON data without manual validation. It provides type-safe, declarative model decoding with explicit failure handling through Result types, eliminating the need for runtime type checking or optional unwrapping boilerplate. Single-framework architecture: Sources/Argo/ contains core parsing logic split into Extensions/ (Dictionary.swift, NSNumber.swift, RawRepresentable.swift) and Functions/ (catDecoded.swift etc.). The library exports a single Argo.framework target with schemes for iOS, macOS, tvOS, and watchOS. Documentation is comprehensive in Documentation/ with guides for enums, root keys, and relationships.

Swift developers building iOS, macOS, tvOS, and watchOS applications who need to parse JSON APIs into strongly-typed domain models and want to avoid writing repetitive validation logic while maintaining compile-time type safety.

Argo is production-ready and actively maintained. The project supports Swift 4.x+ on master, has explicit version compatibility going back to Swift 1.1, uses CI/CD via CircleCI and GitHub Actions (.circleci/config.yml, .github/workflows/swift.yml), and is distributed via CocoaPods and Carthage. The codebase is stable with clear release versioning.

Risk is low but not zero: the library depends on Runes (thoughtbot's functional programming utilities) which adds a transitive dependency, and swift-version fragmentation is managed explicitly across Package@swift-*.swift files. The single maintainer at thoughtbot (thoughtbot-sponsored project) is a moderate concern, but the project's age and integration into established dependency managers mitigates production risk.

The project appears to be in maintenance mode with stable releases aligned to Swift versions. Master actively supports Swift 4.x. No active development is visible in the file list (no open issues data provided), but the presence of .swiftlint.yml and Hound integration suggests ongoing code quality focus.

git clone https://github.com/thoughtbot/Argo.git && cd Argo && carthage update (or pod install if using CocoaPods with use_frameworks! in your Podfile). Open Argo.xcworkspace to build the framework and run the included schemes (Argo-iOS, Argo-Mac, etc.).

Daily commands: Open Argo.xcworkspace in Xcode. Select the Argo-iOS scheme and build (Cmd+B), or run tests via Cmd+U. For Swift Package Manager users: swift build. The library itself is a framework; there is no standalone CLI or server to run.

• Sources/Argo/Types/Decoded/Decoded.swift — Core monad type that wraps parse results and enables functional composition of decoders; foundational to Argo's entire API
• Sources/Argo/Types/Decodable.swift — Protocol that types must conform to in order to be parsed from JSON; defines the contract for all model decoding
• Sources/Argo/Functions/decode.swift — Primary entry point function for parsing JSON into typed models; most common integration point for library users
• Sources/Argo/Types/JSON.swift — Enum representing JSON values and the primary AST that Argo operates on; handles all JSON type handling
• Sources/Argo/Types/DecodeError.swift — Error type that captures why decoding failed with detailed context; essential for debugging parse failures
• Sources/Argo/Functions/catDecoded.swift — Utility for collecting multiple Decoded results and coalescing errors; key helper for batch decoding operations

Add a new Decodable model type

1. Create a new struct or class with properties you want to decode (Tests/ArgoTests/Models/User.swift)
2. Conform to the Decodable protocol by implementing a static decode function that uses JSON operators and monadic composition to extract fields (Sources/Argo/Types/Decodable.swift)
3. In the decode function, use <|> operator to extract required fields and <|? operator for optional fields from the JSON object (Tests/ArgoTests/Models/Post.swift)
4. Compose nested decoders using flatMap or the curry helper to combine extracted values into your model (Tests/ArgoTests/Tests/EmbeddedDecodingTests.swift)

Decode JSON from a string or data source

1. Import Argo and call the decode function with your JSON string and target type (Sources/Argo/Functions/decode.swift)
2. Handle the resulting Decoded<YourType> using pattern matching on success/failure or using monadic operators (Tests/ArgoTests/Tests/ExampleTests.swift)
3. Access DecodeError details to understand what fields failed and why (Sources/Argo/Types/DecodeError.swift)

Add custom decoding logic for a non-standard type

1. Create an extension on the target type or a decoder function that accepts a JSON value (Sources/Argo/Types/StandardTypes.swift)
2. Return a Decoded result by mapping over a required or optional JSON field using monadic operations (Sources/Argo/Types/Decoded/Monad.swift)
3. Use flatMap to chain dependent decodings or pure to wrap successfully decoded values (Tests/ArgoTests/Models/URL.swift)

Handle optional or fallback fields during decoding

1. Use the <|? operator when extracting optional fields from JSON objects (Tests/ArgoTests/Tests/OptionalPropertyDecodingTests.swift)
2. Use the <|> operator with the Alternative instance to provide fallback decoders when primary decoding fails (Sources/Argo/Types/Decoded/Alternative.swift)
3. Combine optional fields in compose functions using Optional.wrap or similar curried helpers (Tests/ArgoTests/Models/Post.swift)

• Swift Generics & Protocol-Oriented Design — Enables type-safe JSON decoding without runtime type checks; leverages Swift compiler to enforce correctness
• Monadic Functional Programming (Functor/Applicative/Monad) — Provides composable error handling and chaining of dependent decoders without nested callbacks
• Operator Overloading (<|>, <|?, flatMap) — Creates concise, readable decoder DSL that mirrors the shape of JSON being decoded
• Enum-based JSON AST — Pattern matching on JSON types is safer than string/dictionary APIs; makes invalid states unrepresentable

• Functional composition over inheritance/delegation

  • Why: Immutability and explicit error flow reduce bugs and make decoder behavior predictable
  • Consequence: Steeper learning curve for developers unfamiliar with functional patterns; requires understanding of currying and monads

• Eager decoding (no lazy evaluation)

  • Why: Simple, deterministic behavior; errors reported immediately and completely
  • Consequence: Cannot decode streaming JSON or pause mid-parse; entire payload validated upfront

• No automatic key/property name mapping

  • Why: Explicit decoder construction prevents silent mismatches between JSON keys and model fields
  • Consequence: More boilerplate than reflection-based libraries; developer must specify each field mapping

• Separate Decoded type instead of throwing

  • Why: Errors are first-class values composable with monadic operators; no try/catch nesting needed
  • Consequence: Pattern matching required for result handling; slightly more verbose than exceptions

• Does not perform automatic camelCase ↔ snake_case conversion
• Does not support lazy or streaming JSON parsing
• Does not generate boilerplate decoders via reflection or macros (pre-Swift 5.4)
• Does not provide built-in validation rules (min/max/regex); validation is user's responsibility after successful decode
• Does not handle circular references or recursive types automatically
• Does not support JSON schema validation or enforcement

Argo requires explicit import of both Argo and Runes frameworks when using Carthage (README notes 'you will need to link both Argo.framework and Runes.framework into your app'). The library has separate Package@swift-*.swift files for different Swift versions—using the wrong one or missing the version-specific file will cause build failures. The Curry library (mentioned in README tl;dr) is optional but examples assume it; using curried initializers without importing Curry will fail.

• Monad (applicative functor) — Argo's core abstraction—all parsing combinators are monadic; understanding >>- (flatMap) and <*> (applicative apply) is essential to using the library effectively
• Parser combinator — Argo's architecture—small parsing functions (extracting a single field) compose via monadic operators to build complex model parsers
• Result type (Either monad) — Argo returns Result<Model, Error> instead of optionals—explicit failure handling without exception throwing; critical for understanding error flow
• Currying — The Curry companion library (mentioned in docs) transforms multi-argument functions into single-argument chains for use with applicative operators; essential pattern in Argo examples
• Phantom types — Argo uses generic phantom parameters in RawRepresentable.swift to encode enum validation at compile time without runtime overhead
• Lens/Optics — Implicit in Argo's approach to nested JSON access via the Decode protocol; related to how Runes operators enable compositional field extraction

• thoughtbot/Runes — Direct dependency providing functional operators (<|>, <*>, >>-) that Argo builds on for its monadic API
• thoughtbot/Curry — Companion library used in Argo examples for curried function initialization, simplifying model decoding syntax
• Alamofire/Alamofire — HTTP client commonly paired with Argo for fetching JSON from APIs and parsing responses
• apple/swift-codable — Modern standard library alternative (Codable protocol) that newer Swift code may prefer over Argo's functional approach
• SwiftyJSON/SwiftyJSON — Alternative JSON parsing library for Swift focusing on convenience over type safety—solves the same problem differently

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 test coverage for StandardTypes.swift decoders

StandardTypes.swift provides decoders for common types (Int, String, Bool, Date, etc.), but there's no dedicated test file for these core decoders. Given Argo's focus on type-safe JSON parsing, testing edge cases (null values, type mismatches, boundary conditions) for standard types would be a high-value addition that prevents regressions.

• [ ] Create Tests/ArgoTests/StandardTypesTests.swift
• [ ] Add test cases for Int, Double, String, Bool, Date, URL decoders with valid/invalid inputs
• [ ] Test edge cases: overflow values, empty strings, malformed dates, invalid URLs
• [ ] Verify DecodeError is properly returned for type mismatches
• [ ] Run tests against all platform schemes (iOS, macOS, tvOS, watchOS)

Add tests for Decoded monad operations (flatMap, applicative)

The Decoded type implements Monad and Applicative patterns (Monad.swift, Applicative.swift, Alternative.swift) which are core to Argo's functional design. These are present in Sources/Argo/Types/Decoded/ but there's no dedicated test file validating monad laws or applicative functor behavior, which could catch subtle bugs in chaining operations.

• [ ] Create Tests/ArgoTests/DecodedMonadTests.swift
• [ ] Test flatMap/bind behavior with success and failure cases
• [ ] Test applicative functor operations (<*>) with multiple decoders
• [ ] Test Alternative/FailureCoalescing behavior with <|> operator
• [ ] Add tests validating monad laws (left identity, right identity, associativity)

Add GitHub Actions workflow for Swift Package Manager compatibility testing

The repo has CircleCI config and a basic swift.yml workflow, but there's no dedicated validation that the Package.swift and Package@swift-*.swift files work correctly across different Swift versions. Given 5 different Package manifest versions exist (3.1, 4, 4.2, 5), a matrix workflow would catch SPM resolution issues early.

• [ ] Expand .github/workflows/swift.yml to include SPM build matrix for Swift 5.1, 5.5, 5.9, 5.10
• [ ] Add swift build and swift test commands for each Swift version
• [ ] Test package resolution with swift package resolve
• [ ] Verify all Package@swift-*.swift variants are valid
• [ ] Add badges to README.md showing SPM compatibility status

• Add type-safe parsing helpers for ISO8601 date formats in Sources/Argo/Extensions/—extend the NSNumber pattern to Date handling with tests
• Write migration guide in Documentation/ for upgrading from Argo 3.x (Swift 3) to 4.x (Swift 4)—documentation folder shows patterns for similar guides
• Implement and document nested error reporting in catDecoded.swift—currently parsing failures lack full path context (e.g., 'failed at key foo.bar.baz'); add breadcrumb tracking

Argo demonstrates a generally strong security posture. As a functional JSON parsing library written in Swift, it has minimal attack surface and no obvious injection vulnerabilities, hardcoded secrets, or dangerous dependencies. The codebase lacks infrastructure concerns (no Docker/exposed services). Primary recommendations focus on best practices: ensuring test data contains no PII, establishing a responsible disclosure policy, and evaluating support for end-of-life Swift versions. The library's functional programming paradigm and type-safety focus inherently mitigate many common security issues. No critical or high-severity vulnerabilities were identified.

• Low · Missing Swift Package Manager Dependency Pinning — Package.swift, Package@swift-*.swift files. The Package.resolved file exists but without examining its content, dependency versions cannot be verified. The project supports multiple Swift versions (3.1, 4.0, 4.2, 5.0) with separate Package manifests, which may lead to version inconsistencies across different build environments. Fix: Ensure Package.resolved is committed and regularly updated. Review pinned dependency versions quarterly and establish a policy for security updates to transitive dependencies.
• Low · Test Data May Contain Sensitive Information — Tests/ArgoTests/JSON/*.json files. Test JSON files in Tests/ArgoTests/JSON/ directory include real-world-like data structures (user_with_email.json, location_post.json, etc.). If these were ever populated with real email addresses or location data, they could expose personally identifiable information (PII) in the repository. Fix: Audit test JSON files to ensure they contain only anonymized or synthetic data. Add documentation/comments clarifying that test data must never contain real PII. Consider using placeholder formats like 'user@example.com' or generic values.
• Low · No Explicit Security Policy Documentation — Repository root. The repository lacks a SECURITY.md file for responsible disclosure. While this is a library with low attack surface, it's a best practice for open-source projects to provide security contact information. Fix: Create a SECURITY.md file documenting the responsible disclosure process and security contact information. Link it in README.md.
• Low · Outdated Build Configuration References — Package@swift-3.1.swift, Package@swift-4.swift. The presence of Package@swift-3.1.swift and Package@swift-4.swift may indicate support for very old Swift versions (3.1 and 4.0 released in 2016-2017) that are no longer receiving security updates. Fix: Consider dropping support for Swift versions older than 5.0 (released 2019). At minimum, document the EOL status and recommend users upgrade to newer Swift versions for security patches.

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.