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/google/libphonenumber 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 the board

• Last commit 2d ago
• 9 active contributors
• Distributed ownership (top contributor 41% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

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

What it runs against: a local clone of google/libphonenumber — 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 google/libphonenumber | 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 master exists | Catches branch renames | | 4 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "google/libphonenumber(\\.git)?\\b" \\
  && ok "origin remote is google/libphonenumber" \\
  || miss "origin remote is not google/libphonenumber (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 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 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
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/google/libphonenumber"
  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).

libphonenumber is Google's production-grade library for parsing, formatting, validating, and analyzing international phone numbers across Java, C++, and JavaScript. It handles the complex country-specific rules for phone number formats, carrier mapping, timezone inference, and offline geocoding—used by Android since v4.0 and deployed at scale across Google services. Monorepo structure with language-specific trees: cpp/ contains ~4M LoC C++ implementation with base utilities (memory/, synchronization/, strings/) and domain modules (geocoding/, carrier/), java/ holds ~2.2M LoC Maven modules (libphonenumber-parent at root with child artifacts like carrier/), and javascript/ wraps the library for Node/browser. Metadata-driven design—phone number rules and geocoding data live in resource files (data directories), not code.

Backend engineers building telephony systems, mobile app developers (especially Android via framework integration), payment processors and telecom platforms that need reliable phone number validation, and porters building language-specific bindings for this library.

Highly mature and production-ready. The project shows 4M+ LoC in C++, active CI/CD workflows (CodeQL, unit tests across all three languages in .github/workflows/), parent POM at v9.0.31-SNAPSHOT indicating continued releases, and integration into Android OS itself since 2011. Actively maintained with security scanning (OSV, CodeQL) and dependency management (dependabot.yml).

Standard open source risks apply.

Active security and dependency management: CodeQL workflow in .github/workflows/codeql.yml, OSV scanner, Scorecards checks, and dependabot.yml configured for updates. Parent POM is at v9.0.31-SNAPSHOT (post-release development), indicating ongoing work. Three parallel CI workflows (cpp-unit-test.yml, java-unit-test.yml) suggest feature parity maintenance across languages.

git clone https://github.com/google/libphonenumber.git && cd libphonenumber. For Java: cd java && mvn clean install (Maven is the package manager; see parent pom.xml). For C++: cd cpp && mkdir build && cd build && cmake .. && make. For JavaScript: cd javascript && npm install (see js package.json if present). Run unit tests: mvn test (Java) or ctest (C++) to verify setup.

Daily commands: Java: mvn test runs unit tests; no dev server (library, not app). C++: cmake --build . && ctest. JavaScript: npm test. The actual library usage is via API calls, not a server—see java/run-java-demo.md for the demo app setup (App Engine deployment for the web demo at libphonenumber.appspot.com).

• java/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java: Core API: parsing, formatting, validation, and number type detection logic for the Java implementation
• cpp/src/phonenumbers/phonenumberutil.h: C++ public API header; declares the exact same interface as Java version for cross-language consistency
• java/src/com/google/i18n/phonenumbers/data/: Metadata directory containing proto-generated country-specific phone number rules (formats, validation patterns, examples)
• cpp/CMakeLists.txt: C++ build configuration; entry point for compiling C++ library and understanding dependency management
• java/carrier/src/com/google/i18n/phonenumbers/carrier/PhoneNumberToCarrierMapper.java: Carrier lookup service; demonstrates how metadata-driven lookups work for non-validation features
• .github/workflows/: CI/CD pipeline: three language-specific unit test workflows + security scanning (CodeQL, OSV, Scorecards)
• FALSEHOODS.md: Critical reading: documents edge cases and international phone number misconceptions that drive design decisions
• cpp/src/phonenumbers/base/: Platform abstraction layer: synchronization (locks), memory management (singletons), and string utilities for cross-platform C++ support

For validation rule changes: metadata lives in java/src/com/google/i18n/phonenumbers/data/ (proto-generated). Modify metadata, regenerate protos. For new features: java/src/phonenumber/PhoneNumberUtil.java is the main API; cpp/src/phonenumbers/phonenumberutil.h is the C++ equivalent. Add tests in java/test/ (mirror the source structure). For carrier/timezone mapping: see java/carrier/src and java/phonenumbergeocoder/ directories. Read CONTRIBUTING.md and making-metadata-changes.md before submitting changes.

Metadata synchronization: phone number rules must be regenerated from proto definitions; changes to data/ files require running a build tool (not committed by hand). Thread-safety: C++ singleton implementations vary by platform (POSIX, Windows, Boost); ensure you understand cpp/src/phonenumbers/base/memory/singleton_*.h for your target platform. Breaking changes in metadata formats can invalidate cached phone number objects across releases—version your serialized data. JavaScript closure compiler mode requires understanding of externs files if extending the library.

• Metadata-Driven Validation — libphonenumber's entire validation engine is data-driven via proto-generated metadata files rather than hardcoded rules; understanding how data/ is structured and regenerated is critical for extending the library
• E.164 Formatting — The library's core output format is E.164 (the international standard for phone numbers); knowing +<country><number> notation is essential for understanding validation and formatting logic
• Platform-Specific Singletons — C++ implementation uses conditional compilation (base/memory/singleton_*.h) to swap threading implementations (POSIX, Windows, Boost) at compile time; this is a key pattern for the codebase's cross-platform support
• Offline Geocoding — PhoneNumberOfflineGeocoder provides geographical data without network calls by embedding compressed binary data files; understanding this tradeoff (size vs. freshness) is critical for deployment in embedded systems
• Confidence-Level Number Matching — isNumberMatch returns confidence levels (EXACT_MATCH, NSN_MATCH, POSSIBLE_MATCH, etc.) rather than binary yes/no; this reflects real-world ambiguity in phone number comparison
• As-You-Type Formatting — AsYouTypeFormatter incrementally formats digits as users type (key UX feature for mobile); the stateful implementation in asyoutypeformatter.cc shows how to maintain partial parse state without full validation overhead
• Carrier and TimeZone Mapping — libphonenumber provides PhoneNumberToCarrierMapper and PhoneNumberToTimeZonesMapper—these are separate Maven artifacts (java/carrier, java/phonenumbergeocoder) showing how to layer optional enrichment on top of core validation

• google/protobuf — libphonenumber uses Protocol Buffers for metadata serialization and code generation; understanding protobuf is essential for modifying phone number rules
• google/i18n — Related Google i18n efforts; libphonenumber is part of the broader internationalization ecosystem and may share patterns
• android/platform_frameworks_base — libphonenumber is integrated into Android's telephony framework since v4.0; this is the primary consumer of the Java library
• twilio/twilio-go — Alternative telephony library; useful for comparing API design and validation rule handling in competing systems
• estesp/manifest-tool — Not directly related but shares Google's build infrastructure patterns (CMake, multi-language support, CI/CD in .github/workflows/)

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 JavaScript/Node.js unit test GitHub Action workflow

The repo has CI workflows for Java (java-unit-test.yml) and C++ (cpp-unit-test.yml), but no corresponding workflow for the JavaScript implementation. This is a gap in coverage since libphonenumber supports JavaScript as a primary language per the README. A new workflow would ensure JavaScript code quality and prevent regressions.

• [ ] Create .github/workflows/javascript-unit-test.yml following the pattern of java-unit-test.yml and cpp-unit-test.yml
• [ ] Configure it to run on pushes and pull requests targeting master
• [ ] Add test execution steps for the JavaScript implementation (likely using npm/yarn based on typical JS project structure)
• [ ] Update .github/CODEOWNERS if needed to assign JavaScript owners
• [ ] Test the workflow by running it locally or creating a draft PR

Add missing README files for JavaScript and Java implementations

The file structure shows README files exist for cpp/ (cpp/README) and the root, but based on the repo structure with separate java/ and javascript/ directories (common in multi-language projects), these likely lack README documentation. The root README references checking READMEs in relevant directories, indicating contributors should find them but they may be missing.

• [ ] Verify if java/README and javascript/README exist; if not, create them
• [ ] Document language-specific setup, build instructions, and testing procedures for each implementation
• [ ] Include quick-start examples for parsing, formatting, and validating phone numbers in each language
• [ ] Reference the parent README and link to language-specific contribution guidelines
• [ ] Ensure consistency in structure and tone across all language-specific READMEs

Add TypeScript type definitions for the JavaScript library

Modern JavaScript libraries increasingly provide TypeScript definitions (.d.ts files) for better IDE support and type safety. Given that libphonenumber's JavaScript implementation is used widely (including Android framework context), adding TypeScript support would significantly improve developer experience and reduce runtime type errors for TypeScript users.

• [ ] Analyze the JavaScript implementation's public API surface (likely in javascript/src or similar)
• [ ] Create comprehensive .d.ts type definition files mirroring the API structure
• [ ] Add a typescript build/publish step to ensure definitions stay in sync with source
• [ ] Include documentation comments in definitions for key classes/functions (PhoneNumberUtil, PhoneNumber, etc.)
• [ ] Consider publishing to DefinitelyTyped (@types/libphonenumber-js) or bundling with the package
• [ ] Add a TypeScript-based example/test file to validate the definitions work correctly

• Add missing unit tests for cpp/src/phonenumbers/alternate_format.cc (likely has lower test coverage than PhoneNumberUtil); grep test/ for existing patterns and create parallel test file following same structure
• Document the exact protobuf schema used for metadata in java/src/com/google/i18n/phonenumbers/data/ (add a METADATA_FORMAT.md explaining version, field semantics, and how to validate custom metadata files)
• Add TypeScript definitions for the JavaScript library in javascript/types/ to improve IDE support (scan js/ exports and create corresponding .d.ts files mirroring Java API surface)

The libphonenumber codebase demonstrates a reasonable security posture with GitHub Actions workflows for code quality scanning (CodeQL, dependency review, OSV scanning). No critical vulnerabilities were identified in the analyzed configuration. Minor concerns include the use of SNAPSHOT versions in the POM file and outdated plugin versions that should be regularly reviewed. The project follows good practices by maintaining security-focused CI/CD workflows. The codebase does not appear to contain hardcoded secrets, SQL injection risks, or XSS vulnerabilities based on the file structure analysis. Recommendations focus on ensuring dependency versions are kept current and considering additional security tooling in the Maven build process.

• Medium · Outdated Maven Bundle Plugin — pom.xml - maven-bundle-plugin dependency. The pom.xml uses maven-bundle-plugin version 5.1.9. While not extremely old, it should be verified against known CVE databases. Maven plugins can be vectors for supply chain attacks if outdated. Fix: Verify the current version is the latest stable release and check Maven Central for known vulnerabilities. Consider using dependency-check or similar tools in CI/CD.
• Low · SNAPSHOT Version in Production Build — pom.xml - parent version specification. The pom.xml specifies version '9.0.31-SNAPSHOT' for the parent dependency. SNAPSHOT versions are development builds and should not be used in production releases as they may change without notice and could introduce unexpected behavior. Fix: For production builds, use stable released versions instead of SNAPSHOT versions. Reserve SNAPSHOT versions for development and testing environments only.
• Low · Missing Dependency Management — pom.xml - overall structure. The pom.xml does not explicitly declare all transitive dependencies. This can lead to version conflicts and makes it harder to track which versions are actually being used, potentially including vulnerable transitive dependencies. Fix: Add a <dependencyManagement> section to explicitly manage all dependency versions. Use 'mvn dependency:tree' to audit transitive dependencies.
• Low · No Security Scanning in Maven Configuration — pom.xml - plugins section. The pom.xml does not include security scanning plugins like OWASP Dependency-Check or similar tools to automatically detect known vulnerabilities in dependencies. Fix: Integrate OWASP Dependency-Check Maven plugin or similar security scanning tools. The repository does have GitHub Actions (osv-scanner-unified.yml, dependency-review.yml, codeql.yml) which partially mitigates this.

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.