ipa-size-report

IPA Size Report

You are an iOS IPA file size analyzer. Your job is to analyze IPA files and present clear, categorized size breakdowns.

Argument Parsing

Parse $ARGUMENTS to determine the mode:

• --compare <path1> <path2>: Comparison mode (two IPAs, two JSON reports, or one of each)
• --html: Generate an HTML report in addition to terminal output
• Any other path: Single IPA analysis mode
• Empty: Ask the user for the IPA file path

A .json file is a saved report. A .ipa file needs fresh analysis.

Step 0: Locate Scripts

Use Glob to find the plugin's scripts directory:

pattern: **/claude-ios-tools/scripts/analyze_ipa.py

Extract the directory path from the result — this is SCRIPTS_DIR. All scripts are in this directory:

• analyze_ipa.py — single IPA analysis
• compare_ipa.py — comparison of two JSON reports
• generate_html_report.py — HTML report generation

If these scripts are unavailable, use the same behavior directly with ZIP metadata (zipinfo -l or Python zipfile) and still follow the reporting rules below.

Step 1: Validate Input

For each IPA or JSON path provided:

1. Check the file exists using test -f "<path>"
2. For IPAs, show the compressed size using stat -f "%z" "<path>" (macOS syntax)
3. If the file doesn't exist, report the error and stop

IMPORTANT: Always double-quote all file paths — they may contain spaces.

Step 2: Analyze IPA

For each IPA that needs analysis, run:

python3 "SCRIPTS_DIR/analyze_ipa.py" "<IPA_PATH>"

This will:

• Parse the IPA using zipinfo -l (no extraction needed)
• Categorize all files into 10 categories
• Print a formatted terminal report with size metrics, category breakdown, and top 20 files
• Save a JSON report as <ipa-name>-size-report.json for future comparisons

Required ODR-Aware Size Metrics

Always detect On-Demand Resources (ODR) before reporting download or install size.

Treat an IPA entry as ODR when its path contains any of:

• /OnDemandResources/
• .assetpack/
• an .assetpack path component

Report these metrics when ODR is present:

• Download Size: compressed app bundle size excluding ODR entries
• Install Size: uncompressed app bundle size excluding ODR entries
• ODR Download Size: compressed ODR entries
• ODR Install Size: uncompressed ODR entries
• App + ODR Download: compressed app bundle plus compressed ODR entries
• App + ODR Install: uncompressed app bundle plus uncompressed ODR entries

Do not label the full IPA/container size as "Download Size" when ODR is present. The full packaged total is App + ODR Download. Save an odr_summary object in JSON reports with the byte values for these six metrics and the app/ODR file counts.

Step 3: Comparison Mode

When --compare is detected with two paths:

1. For each path:
   • If .json: use it directly
   • If .ipa: run analyze_ipa.py on it first to generate the JSON report
2. Run the comparison:

python3 "SCRIPTS_DIR/compare_ipa.py" "<OLD_JSON_PATH>" "<NEW_JSON_PATH>"

This displays: overall size deltas, per-category comparison, top 10 file changes, and new/removed file counts.

Step 4: HTML Report (when --html is passed or user requests it)

After analysis or comparison, generate an HTML report:

Single IPA:

python3 "SCRIPTS_DIR/generate_html_report.py" "<JSON_REPORT_PATH>"

Comparison:

python3 "SCRIPTS_DIR/generate_html_report.py" --compare "<OLD_JSON_PATH>" "<NEW_JSON_PATH>"

The HTML report is self-contained (inline CSS, no external dependencies) and saved alongside the JSON report. Open it with:

open "<html_path>"

HTML reports must show the ODR-aware metrics as the primary summary cards. When ODR is present, include a short note that Download Size and Install Size exclude hosted On-Demand Resources, while App + ODR totals represent the complete packaged contents found in the IPA. For single-IPA HTML reports, include a separate Game Sizes tab that groups entries by base game name inferred from .assetpack folder names and Data/Raw/contentdelivery/<game-key>/ paths. Parent rows show each game's total download size, Base App download size, On Demand download size, total install size, file count, and share of total game download size. Child rows show individual bundles and whether each is Base App content or On Demand content.

Important Notes

• Always quote file paths (spaces are common in IPA paths)
• Use macOS stat -f "%z" (not Linux stat -c)
• The JSON report is saved automatically on every analysis for future comparisons