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/patchthecode/JTAppleCalendar 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

• 24+ active contributors
• Distributed ownership (top contributor 46% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y 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 patchthecode/JTAppleCalendar repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/patchthecode/JTAppleCalendar.

What it runs against: a local clone of patchthecode/JTAppleCalendar — 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 patchthecode/JTAppleCalendar | 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 | Last commit ≤ 685 days ago | Catches sudden abandonment since generation |

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

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

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

JTAppleCalendar is a fully customizable iOS calendar view library written in Swift that provides date cell rendering, month/week switching, range selection, and boundary date constraints without enforcing any visual design. It solves the problem of iOS developers needing calendar functionality without Apple's limited UICalendarView or third-party libraries that force specific UI/UX patterns. Monorepo structure: JTAppleCalendar.xcodeproj contains the core Swift library with podspec configuration, SampleJTAppleCalendar.xcodeproj contains runnable example apps (TestViewController.swift, TestRangeSelectionViewController.swift, TestYearViewViewController.swift demonstrate feature patterns), and Package.swift enables SPM distribution. Cell rendering logic lives in reusable DateCell classes.

iOS developers building apps that need calendar features (event scheduling, date picking, booking systems) who want complete control over cell appearance and calendar layout rather than accepting pre-built UI constraints. Particularly useful for developers creating financial, travel, or appointment management apps.

Production-ready and actively maintained. The repo shows 263K+ lines of Swift code, comprehensive sample projects (SampleJTAppleCalendar), CocoaPods/Carthage/SPM support, and CI via Travis. However, the wiki links external documentation that is currently down, suggesting some documentation debt despite code maturity.

Low-to-moderate risk. Single maintainer (@patchthecode) dependency is present but mitigated by stable, feature-complete codebase. The documentation gap (broken external wiki links) is the primary risk—new contributors may struggle onboarding. No visibility into test coverage or recent commit frequency from provided data.

Visible development includes Persian calendar support (TestPersianCalendar.swift), orientation change handling (TestOrientationChanges.swift), range selection enhancements (TestRangeSelectionViewController.swift), and year-view variants (TestYearViewViewController.swift). No specific PR/milestone data provided, but example calendar proliferation suggests active feature development.

git clone https://github.com/patchthecode/JTAppleCalendar.git && cd JTAppleCalendar && open JTAppleCalendar.xcodeproj (for library development) or open SampleJTAppleCalendar.xcodeproj (to run examples). CocoaPods: pod repo update && pod install. SPM: File → Add Packages → paste repo URL.

Daily commands: Open SampleJTAppleCalendar.xcodeproj in Xcode, select SampleJTAppleCalendar scheme, and press Cmd+R. Run individual example controllers via ViewController.swift entry point or select specific TestViewController subclasses from the Example Calendars folder.

• JTAppleCalendar.xcodeproj/project.pbxproj: Core project configuration defining the library targets, build settings, and CocoaPods/SPM integration points
• [SampleJTAppleCalendar/Example Calendars/TestViewController.swift](https://github.com/patchthecode/JTAppleCalendar/blob/master/SampleJTAppleCalendar/Example Calendars/TestViewController.swift): Canonical example showing basic calendar setup, cell configuration delegate, and date selection callback patterns
• SampleJTAppleCalendar/ExampleDateCells/DateCellCreatedWithXIB/CellView.xib: Reference XIB-based date cell design demonstrating the UI customization philosophy—users replicate this pattern for their own designs
• SampleJTAppleCalendar/ExampleDateCells/DateCellCreatedWithCode/CodeCellView.swift: Reference programmatic date cell showing programmatic-only customization approach without XIB dependencies
• [SampleJTAppleCalendar/Example Calendars/TestRangeSelectionViewController.swift](https://github.com/patchthecode/JTAppleCalendar/blob/master/SampleJTAppleCalendar/Example Calendars/TestRangeSelectionViewController.swift): Advanced feature example demonstrating date range selection logic, essential for understanding multi-date workflows
• Package.swift: Swift Package Manager manifest enabling SPM distribution alongside CocoaPods, critical for modern iOS dependency management
• JTAppleCalendar.podspec: CocoaPods specification defining library metadata, version, and dependency constraints for pod repository integration

Start in SampleJTAppleCalendar/Example Calendars/ to understand feature patterns (TestViewController.swift for basics, TestRangeSelectionViewController.swift for selection logic). Modify cell appearance in ExampleDateCells/ (CellView.xib for XIB cells, CodeCellView.swift for programmatic cells). Core calendar behavior lives in the JTAppleCalendar.xcodeproj framework targets.

Orientation changes require special handling (TestOrientationChanges.swift exists as test—check implementation for required delegate callbacks). Calendar math varies by calendar system (Persian calendar example implies locale-aware date calculations beyond Gregorian). XIB-based cells require proper registration via Bundle; code-based cells bypass this but require programmatic layout. The broken wiki documentation means actual delegate methods and configuration APIs must be reverse-engineered from sample code.

• UICollectionView subclassing for calendar rendering — JTAppleCalendar's entire architecture is built on UICollectionView cell recycling and layout logic; understanding cell reuse patterns, IndexPath mapping to dates, and custom UICollectionViewLayout behavior is essential to extending or debugging calendar behavior
• Calendar system abstraction (Gregorian, Persian, Hebrew, etc.) — The codebase includes TestPersianCalendar.swift, showing support for non-Gregorian calendars; date arithmetic differs fundamentally across calendar systems (leap month rules, epoch), requiring NSCalendar-level abstraction rather than hardcoded day counts
• Cell registration and XIB vs programmatic layout trade-offs — JTAppleCalendar exposes two cell creation patterns (XIB and code-based in ExampleDateCells/); understanding when to use each (XIB for designer collaboration vs code for complex logic) affects maintainability and performance in custom calendar apps
• Delegate pattern for event-driven UI updates — Calendar selection, scrolling to dates, and range changes all flow through delegates (implied by sample code patterns); mastering this pattern is critical for wiring date selection callbacks and custom animations
• Date range selection with visual feedback (UI state for start/mid/end dates) — TestRangeSelectionViewController.swift demonstrates complex state management (tracking selected range, updating cell appearance dynamically); this pattern is non-trivial because cells are recycled and state must survive scrolling
• Horizontal and vertical scrolling layout modes — The library supports both axes; UICollectionViewFlowLayout behavior, scroll direction configuration, and paging differ significantly between modes, affecting how boundary dates and month transitions are implemented
• Month header decoration with variable sizing — JTAppleCalendar allows custom month headers of varying sizes (mentioned in README); implementing supplementary views (headers) requires UICollectionViewLayout subclassing and careful size/offset calculation to avoid cell overlap

• WenchaoD/FSCalendar — Direct alternative: also a highly customizable iOS calendar library (Objective-C base with Swift support), solves identical problem with different API and slightly more opinionated styling defaults
• jonkykong/SideMenu — Common companion repo: often paired with JTAppleCalendar for date-picker sidebars or navigation menus in calendar apps needing custom interaction patterns
• airbnb/lottie-ios — Common enhancement: developers integrate Lottie animations into JTAppleCalendar date cells for event indicators, transitions, and visual feedback on date selection
• realm/realm-swift — Common data layer: sample apps using JTAppleCalendar typically persist calendar events/selections with Realm rather than CoreData for easier date-range queries
• apple/swift-corelibs-foundation — Foundational dependency: JTAppleCalendar relies heavily on Foundation Calendar and DateComponents APIs for all date arithmetic and locale-aware calendar logic

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 CalendarEnums.swift and CalendarStructs.swift

The Sources/JTAppleCalendar/ directory contains core enum and struct definitions but there's no visible test directory structure in the file listing. These foundational types (CalendarEnums, CalendarStructs) are critical to the library's functionality and need test coverage to prevent regressions as contributors modify the API.

• [ ] Create Tests/JTAppleCalendarTests/ directory structure
• [ ] Add unit tests for all cases in CalendarEnums.swift (testing enum rawValues, initializers, computed properties)
• [ ] Add unit tests for CalendarStructs.swift validation logic (date ranges, boundary conditions, invalid inputs)
• [ ] Verify tests run in the existing JTAppleCalendar.xcodeproj scheme
• [ ] Add test target to Package.swift for SPM compatibility

Create GitHub Actions workflow to replace .travis.yml for Swift package validation

The repo has an outdated .travis.yml but no visible GitHub Actions workflows in .github/workflows/. Modern Swift projects use GitHub Actions for CI/CD. This would ensure the library builds, tests pass, and validates against multiple Swift versions on every PR.

• [ ] Create .github/workflows/swift-ci.yml that builds for iOS minimum deployment target specified in Package.swift
• [ ] Add test execution step for the test target created above
• [ ] Add SPM build validation (swift build) step
• [ ] Add CocoaPods linting step (pod spec lint JTAppleCalendar.podspec) to catch podspec regressions
• [ ] Configure workflow to run on pull_request and push to main/develop branches

Add API documentation comments to GlobalFunctionsAndExtensions.swift and create DocC catalog

The library exports public APIs through GlobalFunctionsAndExtensions.swift but these lack Swift-Docc compatible documentation comments (/// comments with parameter descriptions). With modern Xcode supporting DocC, this enables inline documentation and generated documentation website.

• [ ] Add detailed documentation comments (///) to all public functions in GlobalFunctionsAndExtensions.swift with @parameter, @returns, @throws where applicable
• [ ] Create Sources/JTAppleCalendar/Documentation.docc directory structure
• [ ] Add JTAppleCalendar.md overview page with basic usage examples
• [ ] Add Article pages for key workflows (e.g., DateSelection.md, CustomizingCells.md)
• [ ] Update Package.swift to include .documentation dependency for proper DocC integration

• Add comprehensive unit tests for date range selection logic in TestRangeSelectionViewController—currently no visible test target in file structure; create Tests/ directory and add XCTest cases for boundary conditions (leap years, Persian calendar, timezone edge cases)
• Document the specific delegate methods and protocol requirements (likely JTAppleCalendarDelegate or similar) by extracting API signatures from framework code and adding inline code comments to SampleJTAppleCalendar/Example Calendars/TestViewController.swift with before/after examples
• Fix the broken wiki references in README.md by migrating tutorial content from docs/ folder into well-formatted markdown files and updating links; start with docs/get-started/Get%20Started.md as the entry point and cross-link from README

The JTAppleCalendar repository appears to be a well-structured iOS calendar library with no critical security vulnerabilities visible in the file structure. The main concerns are: (1) inability to verify dependency security without Package.swift content, (2) minor exposure of Xcode configuration files in version control, and (3) inclusion of a sample application. The codebase is primarily UI/calendar logic without apparent database interactions, file operations, or network calls that would introduce injection risks. No hardcoded secrets were identifiable from the file structure. Overall security posture is solid for a UI library, but standard best practices for dependency management and CI/CD configuration should be followed.

• Medium · Dependency Management Visibility — Package.swift. The Package.swift file content was not provided for analysis. This makes it impossible to assess whether the project uses secure, up-to-date dependencies or if there are known vulnerable packages in use. Fix: Provide Package.swift content and implement regular dependency scanning using tools like Swift Package Manager's vulnerability database or third-party tools like Dependabot.
• Low · Travis CI Configuration Exposed — .travis.yml. The .travis.yml file is present in the repository. While this is standard practice, it could potentially expose CI/CD pipeline details if it contains sensitive information or configuration that could aid attackers. Fix: Review .travis.yml to ensure no credentials, API keys, or sensitive tokens are hardcoded. Use encrypted environment variables for any secrets needed in CI/CD pipelines.
• Low · Xcodeproj Configuration Files Included — JTAppleCalendar.xcodeproj/project.pbxproj, SampleJTAppleCalendar.xcodeproj/project.pbxproj. Xcode project files (.pbxproj, .xcscheme) are version controlled. These binary-format files can contain build settings, code signing identities, and other sensitive configuration that could be exposed. Fix: Review these files to ensure they don't contain hardcoded secrets, credentials, or API keys. Consider using environment variables or separate configuration files for sensitive settings.
• Low · Sample Project Included in Repository — SampleJTAppleCalendar/. A complete sample application (SampleJTAppleCalendar) is included in the main repository. While useful for documentation, this increases the codebase surface area and could inadvertently expose sensitive patterns or implementation details. Fix: Ensure the sample application doesn't contain any hardcoded credentials, test data, or security-sensitive logic. Consider moving it to a separate repository if it becomes large.

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.