Skip to content

CLAUDE.md

Latest commit

 

History

History
99 lines (73 loc) · 4.47 KB

CLAUDE.md

File metadata and controls

99 lines (73 loc) · 4.47 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Launchpad is a Python-based microservice for analyzing iOS and Android app bundle sizes. It provides detailed analysis of app binaries, generates optimization insights, and offers size breakdowns with visualization. This is a Sentry internal service that processes mobile app artifacts.

Development Commands

Always use uv run to run scripts instead of manually invoking python.

# Setup
devenv sync                    # or: make install-dev && source .venv/bin/activate

# Code quality (run before committing)
make check                     # All checks: lint, format, types, deps
make fix                       # Auto-fix formatting and imports

# Testing
make test                      # All tests (unit + integration)
make test-unit                 # Unit tests only
make test-integration          # Integration tests only

# Run a single test
uv run pytest tests/unit/path/to/test_file.py::test_function_name -v
uv run pytest tests/unit/path/to/test_file.py -v               # whole file
uv run pytest -k "test_name_pattern" -v                        # by pattern

# CLI usage
launchpad size path/to/app.xcarchive.zip                       # iOS
launchpad size path/to/app.apk                                 # Android
launchpad size app.xcarchive.zip --skip-swift-metadata --skip-symbols  # faster

# Service development
make worker                    # Start Launchpad worker (TaskWorker mode)

Architecture

Core Components

  • CLI (src/launchpad/cli.py): Main entry point, uses Click
  • Worker (src/launchpad/worker/): TaskWorker — receives tasks via TaskBroker RPC (launchpad worker)
  • Analyzers (src/launchpad/size/analyzers/): Platform-specific analysis engines (AppleAppAnalyzer, AndroidAnalyzer)
  • Parsers (src/launchpad/parsers/): Binary parsing - Mach-O via LIEF, custom DEX parsers
  • Insights (src/launchpad/size/insights/): Optimization recommendations (image compression, symbol stripping, etc.)
  • Artifacts (src/launchpad/artifacts/): Artifact handlers - ArtifactFactory creates appropriate handler by file type

Data Flow

  1. Artifact (.xcarchive.zip, .apk, .aab) → ArtifactFactory
  2. Platform-specific analyzer extracts binaries, resources, metadata
  3. Parsers analyze binary structure (symbols, sections, Swift metadata)
  4. Insights engine generates optimization recommendations
  5. Results serialized as JSON with treemap visualization data

Key Data Models

  • AppleAnalysisResults / AndroidAnalysisResults: Platform analysis output
  • AppComponent: Individual app component with size and type info
  • TreemapElement: Hierarchical size data for visualization
  • BaseInsightResult: Optimization recommendation with potential savings

Code Style

  • Python 3.13+ with type hints (use | None not Optional)
  • Ruff for linting/formatting (120 char line length)
  • ty for type checking (not mypy)
  • Empty __init__.py files preferred
  • Comments: Only add comments for complex logic or important business decisions

Security: Path Traversal Prevention

When handling paths derived from untrusted input (zip member names, plist values, manifest entries, user-supplied filenames), use SafeDirectory from launchpad.artifacts.providers.safe_directory — never use raw Path operations.

  • SafeDirectory(base).resolve(untrusted) — validates and returns a safe Path, raises UnsafePathError on traversal attempts
  • SafeDirectory(base).child(untrusted) — returns a new SafeDirectory scoped to a validated subdirectory
  • Trusted operations (glob, /, iterdir) are delegated directly and don't need validation
  • Import UnsafePathError from launchpad.artifacts.providers.exceptions

Testing Strategy

  • Prefer integration tests using real artifacts from tests/_fixtures/ over unit tests with mocks
  • Use pytest fixtures for setup
  • Test artifacts include sample iOS (.xcarchive) and Android (.apk/.aab) files

Feature Completion Requirements

A feature is not complete until:

  1. All tests pass: make test-unit
  2. All checks pass: make check
  3. Code formatted: make fix if needed

Adding New Insights

  1. Create class in insights/apple/, insights/android/, or insights/common/
  2. Implement the Insight protocol
  3. Implement analyze() returning a subclass of BaseInsightResult
  4. Register in platform analyzer's insight list
  5. Add integration tests