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/gzu-liyujiang/AndroidPicker 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.

WAIT — Single-maintainer risk — review before adopting

• Last commit 7w ago
• 4 active contributors
• Other licensed
• CI configured
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 96% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No test directory detected

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

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

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "AddressPicker/src/main/java/com/github/gzuliyujiang/wheelpicker/AddressPicker.java" \\
  && ok "AddressPicker/src/main/java/com/github/gzuliyujiang/wheelpicker/AddressPicker.java" \\
  || miss "missing critical file: AddressPicker/src/main/java/com/github/gzuliyujiang/wheelpicker/AddressPicker.java"
test -f "AddressPicker/src/main/assets/china_address.json" \\
  && ok "AddressPicker/src/main/assets/china_address.json" \\
  || miss "missing critical file: AddressPicker/src/main/assets/china_address.json"
test -f "AddressPicker/src/main/java/com/github/gzuliyujiang/wheelpicker/utility/AddressJsonParser.java" \\
  && ok "AddressPicker/src/main/java/com/github/gzuliyujiang/wheelpicker/utility/AddressJsonParser.java" \\
  || miss "missing critical file: AddressPicker/src/main/java/com/github/gzuliyujiang/wheelpicker/utility/AddressJsonParser.java"
test -f "CalendarPicker/src/main/java/com/github/gzuliyujiang/calendarpicker/CalendarPicker.java" \\
  && ok "CalendarPicker/src/main/java/com/github/gzuliyujiang/calendarpicker/CalendarPicker.java" \\
  || miss "missing critical file: CalendarPicker/src/main/java/com/github/gzuliyujiang/calendarpicker/CalendarPicker.java"
test -f "ColorPicker/src/main/java/com/github/gzuliyujiang/colorpicker/ColorPicker.java" \\
  && ok "ColorPicker/src/main/java/com/github/gzuliyujiang/colorpicker/ColorPicker.java" \\
  || miss "missing critical file: ColorPicker/src/main/java/com/github/gzuliyujiang/colorpicker/ColorPicker.java"

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

AndroidPicker is a comprehensive Android UI library providing 10+ specialized picker components (DatePicker, TimePicker, AddressPicker, CalendarPicker, ColorPicker, FilePicker, ImagePicker, etc.) built on a reusable WheelView scrolling mechanism. It solves the common Android problem of implementing polished, configurable selection dialogs without reinventing wheel mechanics or date/address parsing logic for each new feature. Multi-module Gradle monorepo: root project with modular dependencies—Common/ provides base dialog infrastructure, WheelView/ implements the core scrolling control, WheelPicker/ builds date/number/linkage pickers on WheelView, and specialty modules (AddressPicker/, CalendarPicker/, FilePicker/, ImagePicker/, ColorPicker/) layer on these foundations. Each module has its own build.gradle, AndroidManifest.xml, and src/main/java package hierarchy under com.github.gzuliyujiang.wheelpicker.*.

Android developers (API 19+) building consumer apps that need native-feeling date selection (birth dates, business hours), address/region selection (shipping forms, location-based services), file/image browsing, or numeric input (age, temperature) without writing custom picker views.

Production-ready but community-maintained: the original author (李裕江) stopped active Android development in 2022 and explicitly stated the project is 'stable but needs community participation via PRs.' It has GitHub CI/CD workflows (gradle-publish.yml, release-apk.yml) and proper module structure, but relies on community pull requests for maintenance.

Moderate single-maintainer risk: original author inactive since 2022; no visible automated tests in the file structure; dependency chain includes AndroidX libraries (annotation, etc.) requiring ongoing compatibility maintenance. Breaking API changes occurred between v1/v2 and v3.0.0, so upgrading requires caution. However, the library is feature-complete and stable for its stated use cases.

No recent active development visible from the provided snapshot. The project is in 'stable, community-maintained' state awaiting pull requests. GitHub workflows exist for publishing to JitPack and releasing APKs, but no specific in-progress features or milestones are evident from the file list.

Clone the repository and open in Android Studio: git clone https://github.com/gzu-liyujiang/AndroidPicker.git && cd AndroidPicker. Sync Gradle dependencies (Android Studio auto-prompts) targeting API 19+. Run the app module (if present) or build individual picker modules via ./gradlew :AddressPicker:build to verify your environment.

Daily commands: This is a library, not a runnable app directly. To test: import individual modules into an Android app project, add implementation 'com.github.gzu-liyujiang.AndroidPicker:WheelPicker:<version>' to build.gradle (using JitPack), then instantiate pickers (e.g., new DatePicker(context).show()). Check demo.apk in the repo root for a reference implementation.

• AddressPicker/src/main/java/com/github/gzuliyujiang/wheelpicker/AddressPicker.java — Main entry point for the AddressPicker module; defines the public API and dialog lifecycle for address selection across province/city/county levels.
• AddressPicker/src/main/assets/china_address.json — Core data asset containing hierarchical Chinese administrative regions; any address picker functionality depends on parsing and loading this JSON structure.
• AddressPicker/src/main/java/com/github/gzuliyujiang/wheelpicker/utility/AddressJsonParser.java — Parses the china_address.json asset into entity objects; critical for transforming raw data into usable picker state.
• CalendarPicker/src/main/java/com/github/gzuliyujiang/calendarpicker/CalendarPicker.java — Main entry point for calendar-based date selection; handles date range and single-date picking with festival/holiday annotations.
• ColorPicker/src/main/java/com/github/gzuliyujiang/colorpicker/ColorPicker.java — Main entry point for color selection; integrates gradient views and touch handling for HSV-based color picking.
• Common/build.gradle — Shared Gradle configuration and AndroidX dependencies across all picker modules; changing this affects all library components.

Add a New Picker Type (e.g., WeightPicker for body measurements)

1. Create a new module directory with the standard structure: YourPicker/src/main/java/com/github/gzuliyujiang/yourpicker/ (YourPicker/build.gradle)
2. Define data entities inheriting from or paralleling existing patterns (e.g., like NumberEntity for numeric values) (YourPicker/src/main/java/com/github/gzuliyujiang/yourpicker/entity/WeightEntity.java)
3. Create a main dialog/picker class extending the framework's base picker, following AddressPicker or CalendarPicker pattern (YourPicker/src/main/java/com/github/gzuliyujiang/yourpicker/YourPicker.java)
4. Define callback listener interface(s) for selection events (YourPicker/src/main/java/com/github/gzuliyujiang/yourpicker/OnWeightPickedListener.java)
5. Create custom View(s) or Adapter(s) for rendering wheel/list/grid UI, similar to DayView or ColorGradientView (YourPicker/src/main/java/com/github/gzuliyujiang/yourpicker/core/WeightWheelView.java)
6. Update root settings.gradle to include the new module in the multi-module build (settings.gradle)
7. Document usage in YourPicker/README.md following the pattern of existing picker READMEs (YourPicker/README.md)

Add a Custom Address Data Source (e.g., load from Network or Database instead of assets)

1. Create a new class implementing the AddressLoader contract interface (AddressPicker/src/main/java/com/github/gzuliyujiang/wheelpicker/impl/CustomAddressLoader.java)
2. Implement loadProvinces() and loadCities()/loadCounties() methods to fetch data from your source (network, database, etc.) (AddressPicker/src/main/java/com/github/gzuliyujiang/wheelpicker/contract/AddressLoader.java)
3. Parse the response data into ProvinceEntity, CityEntity, and CountyEntity objects (AddressPicker/src/main/java/com/github/gzuliyujiang/wheelpicker/entity/ProvinceEntity.java)
4. Inject your custom loader into AddressPicker via setAddressLoader() before showing the picker (AddressPicker/src/main/java/com/github/gzuliyujiang/wheelpicker/AddressPicker.java)

Extend Calendar Picker with Custom Festival or Holiday Rules

1. Create a custom class implementing or extending FestivalProvider to define your holiday logic (CalendarPicker/src/main/java/com/github/gzuliyujiang/calendarpicker/core/FestivalProvider.java)
2. Override methods to return holiday dates, festival names, and lunar calendar events (CalendarPicker/src/main/java/com/github/gzuliyujiang/calendarpicker/core/TimeUtils.java)
3. Inject your custom FestivalProvider into CalendarPicker via setFestivalProvider() before display (CalendarPicker/src/main/java/com/github/gzuliyujiang/calendarpicker/CalendarPicker.java)

No explicit hidden traps visible, but: (1) AddressPicker depends on china_address.json being present in assets—missing file causes silent failures. (2) Version 3.0.0+ API differs significantly from v1/v2; old tutorials/StackOverflow answers will not apply. (3) The library requires AndroidX (not legacy Support Library); projects still using Support Library need migration. (4) AssetAddressLoader loads the entire JSON into memory—very large custom address datasets may cause memory pressure on low-end devices.

• Wheel View / Scroller Animation — Core mechanism enabling the signature iOS-like scrolling picker UX; understanding fling physics, velocity tracking, and deceleration is essential to modifying or extending AndroidPicker's behavior.
• Android Contract Pattern (Listener/Callback Interfaces) — The library uses contract interfaces (OnAddressPickedListener, AddressLoader, AddressParser) to decouple picker UI from business logic; mastering this pattern is required for extending pickers or adding custom data sources.
• Multi-level Hierarchical Data Binding — AddressPicker and LinkagePicker manage cascading selections (province → city → county); understanding how dependent pickers update and synchronize is crucial for features like vehicle plate selection or category filtering.
• Asset-based Data Loading & JSON Parsing — The library bundles china_address.json in assets and parses it at runtime; this pattern avoids network latency but requires efficient in-memory caching, relevant for offline-first Android apps.
• Android Modular Library Architecture & Gradle Multi-Module — AndroidPicker's strength is its composable modules (Common, WheelView, WheelPicker, specialty pickers); understanding module dependencies and binary publishing (JitPack) is key to maintaining or extending the library.
• Dialog/Modal Fragment Lifecycle & State Preservation — Pickers are dialog components that must handle configuration changes, back press, and state restoration; the library's base picker dialog infrastructure relies on proper Fragment lifecycle patterns.
• JitPack Dynamic Publishing & CI/CD for Android Libraries — The repo uses JitPack for versioning and gradle-publish.yml/release-apk.yml workflows to automate testing and publishing; understanding this reduces friction for contributing pull requests.

• loperSeven/DatePicker — Alternative Android date picker with similar wheel-scroll UX; useful comparison for design patterns and API decisions.
• CymChad/BaseRecyclerViewAdapterHelper — Popular Android adapter helper library addressing similar 'don't reinvent common UI patterns' philosophy for list-based selection.
• android/architecture-samples — Google's reference Android architecture; useful for understanding modern AndroidX, lifecycle patterns, and modularization best practices applicable to AndroidPicker's refactoring.
• alibaba/BeeHive — Plugin-based modular architecture framework for Android; demonstrates advanced monorepo patterns relevant to AndroidPicker's multi-module structure.
• gzu-liyujiang/SwipeBack — Same author's earlier Android library; shows design consistency and dependency patterns used across their open-source Android ecosystem.

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 unit tests for AddressJsonParser and AddressProvider

The AddressPicker module lacks test coverage for its core data parsing and loading logic. AddressJsonParser.java and AssetAddressLoader.java handle the critical task of parsing china_address.json and providing address entities. Unit tests would ensure data integrity, validate the JSON parsing logic, and catch regressions when address data is updated.

• [ ] Create AddressPicker/src/test/java/com/github/gzuliyujiang/wheelpicker/utility/AddressJsonParserTest.java with tests for JSON parsing of provinces, cities, and counties
• [ ] Create AddressPicker/src/test/java/com/github/gzuliyujiang/wheelpicker/impl/AssetAddressLoaderTest.java to test asset loading and OnAddressLoadListener callbacks
• [ ] Add test fixtures or mock the china_address.json asset for reproducible testing
• [ ] Update AddressPicker/build.gradle to include testing dependencies (junit, mockito)

Add instrumented tests for CalendarPicker date selection and range validation

CalendarPicker has complex logic for date selection, month navigation, and range validation (Interval.java, DateUtils.java) but lacks instrumented tests. The CalendarAdapter, CalendarView, and DayStatus classes need validation to ensure calendar rendering, date picking, and range constraints work correctly across different date scenarios and device configurations.

• [ ] Create CalendarPicker/src/androidTest/java/com/github/gzuliyujiang/calendarpicker/core/DateUtilsTest.java for date utility functions and edge cases (leap years, month boundaries)
• [ ] Create CalendarPicker/src/androidTest/java/com/github/gzuliyujiang/calendarpicker/CalendarPickerTest.java for single date and range selection callbacks using Espresso
• [ ] Create CalendarPicker/src/androidTest/java/com/github/gzuliyujiang/calendarpicker/core/IntervalTest.java to validate date range constraints and boundary conditions
• [ ] Update CalendarPicker/build.gradle to include androidTestImplementation dependencies (espresso, androidx.test)

Create GitHub Actions workflow for automated instrumented testing on Android emulator

The repo has gradle-publish.yml and release-apk.yml workflows but lacks automated UI/instrumented testing in CI/CD. Given the repository's focus on picker UI components, running instrumented tests on an Android emulator in GitHub Actions would catch visual/behavioral regressions early and ensure compatibility across Android API levels (API 19+).

• [ ] Create .github/workflows/instrumented-tests.yml using reusable Android emulator action (e.g., android-emulator-runner)
• [ ] Configure the workflow to run ./gradlew connectedAndroidTest against API 19+ emulator images
• [ ] Add test result reporting and artifact uploads for failed test logs and screenshots
• [ ] Document the new workflow in README.md under a 'Contributing' or 'Testing' section

• Add unit tests for AddressJsonParser.java and entity classes (ProvinceEntity, CityEntity, CountyEntity) to improve maintainability—currently no visible test files in the structure despite complex parsing logic.
• Extend AddressPicker's contract (AddressLoader interface) to support remote address data sources (REST API) alongside the current asset-based loader; document the pattern for contributors.
• Create missing README documentation for FilePicker and ImagePicker modules with concrete usage examples and intent-based permission handling for Android 6.0+.

The AndroidPicker codebase demonstrates reasonable security posture for a UI library focused on picker components. No critical vulnerabilities were identified from the static analysis. The main concerns are around data validation (especially for the address JSON loading), code obfuscation, and dependency management. The project uses Apache 2.0 / Mulan PSL v2 licensing and appears well-maintained. Recommendations focus on strengthening input validation, improving ProGuard configuration, and implementing proper exception handling to prevent information disclosure. The modular architecture is a positive security practice.

• Medium · Potential Insecure Data Loading from Assets — AddressPicker/src/main/assets/china_address.json and AddressPicker/src/main/java/com/github/gzuliyujiang/wheelpicker/impl/AssetAddressLoader.java. The AddressPicker module loads address data from a JSON file stored in assets (china_address.json). If this file is modified or tampered with during the build process, it could lead to incorrect address data being presented to users. Additionally, the AssetAddressLoader pattern may not validate the loaded JSON structure. Fix: Implement JSON schema validation after loading the address data. Consider signing the asset file or using integrity checks. Add input validation in AddressJsonParser.java to ensure data conforms to expected format.
• Low · No Explicit ProGuard/R8 Rules Defined — AddressPicker/consumer-rules.pro and other modules. The consumer-rules.pro files are present but appear to be minimal. Without proper ProGuard/R8 configuration, sensitive method names and class structures could be exposed in the compiled APK, potentially aiding reverse engineering. Fix: Enhance consumer-rules.pro files with aggressive obfuscation rules. Keep sensitive classes and methods from being stripped during optimization. Use -keep rules for public APIs while obfuscating implementation details.
• Low · Dependency on Multiple Internal Modules Without Version Pinning — AddressPicker/build.gradle. The AddressPicker build.gradle uses 'api project()' references to Common, WheelView, and WheelPicker without explicit version constraints. This could lead to unexpected version mismatches if transitive dependencies are not carefully managed. Fix: Consider using explicit version constraints for inter-module dependencies. Document the minimum API levels and dependency versions required. Implement dependency version management through a centralized gradle.properties or BOM (Bill of Materials).
• Low · Potential Information Disclosure via Error Messages — Multiple modules - AddressPicker, CalendarPicker, ColorPicker. No evidence of custom exception handling or logging configuration visible. Android applications may inadvertently expose sensitive stack traces or implementation details through uncaught exceptions or verbose logging. Fix: Implement custom exception handling that provides user-friendly error messages without exposing implementation details. Configure logging frameworks to use appropriate log levels for production builds (disable DEBUG/VERBOSE in release builds).

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.