Auditing Your Own Code for Required Reason API Declarations with Claude Code

A Python scanner for your own code

First, detect the relevant symbols across the Swift files in your project. I asked Claude Code to "write a scanner that detects the target APIs sorted into four categories, with file and line number," then refined the draft into this.

#!/usr/bin/env python3
"""scan_required_reason.py — find Required Reason APIs in your own code."""
import re
import sys
from pathlib import Path
 
# category -> (detection symbols, candidate reason codes indie apps use)
CATEGORIES = {
    "UserDefaults": (
        [r"\bUserDefaults\b", r"\bNSUserDefaults\b"],
        ["CA92.1"],
    ),
    "FileTimestamp": (
        [r"\.modificationDate\b", r"\.creationDate\b",
         r"\bcontentModificationDateKey\b", r"\bfstat\b", r"\bstat\("],
        ["C617.1", "3B52.1", "0A2A.1"],
    ),
    "DiskSpace": (
        [r"volumeAvailableCapacity\w*Key", r"\bsystemFreeSize\b",
         r"\bvolumeTotalCapacityKey\b"],
        ["85F4.1", "E174.1"],
    ),
    "SystemBootTime": (
        [r"\.systemUptime\b", r"\bmach_absolute_time\b"],
        ["35F9.1"],
    ),
}
 
def scan(root: Path):
    hits = {}  # category -> list[(file, line_no, snippet)]
    for swift in root.rglob("*.swift"):
        if "/Pods/" in str(swift) or "/.build/" in str(swift):
            continue
        for i, line in enumerate(swift.read_text(encoding="utf-8",
                                                 errors="ignore").splitlines(), 1):
            for cat, (patterns, _codes) in CATEGORIES.items():
                if any(re.search(p, line) for p in patterns):
                    hits.setdefault(cat, []).append(
                        (swift.name, i, line.strip()[:80]))
    return hits
 
if __name__ == "__main__":
    root = Path(sys.argv[1] if len(sys.argv) > 1 else ".")
    found = scan(root)
    if not found:
        print("Nothing found. No self-code APIs require a declaration.")
        sys.exit(0)
    for cat, (_, codes) in CATEGORIES.items():
        if cat in found:
            print(f"\n[{cat}] candidate reason codes: {', '.join(codes)}")
            for name, ln, snip in found[cat]:
                print(f"  {name}:{ln}  {snip}")

Run it as python3 scan_required_reason.py ./Sources and you get the matching lines and candidate reason codes grouped by category. On my machine it covered about 120 files and finished in roughly 0.8 seconds, surfacing exactly the three gaps I mentioned. There is far less second-guessing than tracing sources by hand.

Excluding Pods/ and .build/ is deliberate. What I want here is my own code only; dependencies carry the responsibility to declare through their own manifests. Mixing the two muddies the question of which side should file the declaration.

Turning results into .xcprivacy

Using the scan results, assemble the relevant part of PrivacyInfo.xcprivacy. A minimal example declaring UserDefaults and file timestamp looks like this.

<key>NSPrivacyAccessedAPITypes</key>
<array>
  <dict>
    <key>NSPrivacyAccessedAPIType</key>
    <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
    <key>NSPrivacyAccessedAPITypeReasons</key>
    <array>
      <string>CA92.1</string>
    </array>
  </dict>
  <dict>
    <key>NSPrivacyAccessedAPIType</key>
    <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
    <key>NSPrivacyAccessedAPITypeReasons</key>
    <array>
      <string>C617.1</string>
    </array>
  </dict>
</array>

What matters here is not filling reason codes with whatever looks safe. The UserDefaults CA92.1, for instance, carries the condition that access happens only within your app or App Group container and is not shared with third parties. If you hand values to an analytics SDK, that reason does not match reality. Keep the line clear: the script offers candidates, not conclusions.

Before / After — living with the rejection email

The old me went hunting for the offending call only after a rejection arrived. The error message (ITMS-91053) tells you which category is missing, but not where in the code. I would open and close files at random, over and over.

Once the scan became a pre-submission step, that round trip disappeared. Moving from a reactive stance — waiting on the rejection to act — to checking things myself before submitting was a small change, but the little knot of tension I felt on every release loosened.

Handing the diff check to Claude Code

Do not stop at a one-time inventory; re-scan on every release. New code that touches another Required Reason API leaves another gap. I give Claude Code this role:

1. Run scan_required_reason.py and collect the list of detected categories
2. Read the categories already present in the current PrivacyInfo.xcprivacy
3. Point out, as a diff, the categories that were detected but not declared
4. For each diff, summarize the candidate reason codes and the matching lines

Writing these four steps into CLAUDE.md means a single "check the Required Reason APIs" runs the same inspection at the same fidelity every time. Leave only the judgment-bound choice of reason code to a human, and delegate the mechanically decidable detection and diffing. That boundary is what makes this sustainable for a solo developer.

If you fold this into CI, returning a failing exit code when an undeclared category appears is a sturdy design. The idea sits alongside my notes on continuous iOS updates in the Xcode iOS development workflow. When a dependency migration is involved, reading it together with notes on migrating from CocoaPods to SPM will give you the full manifest picture.

Points where you may stumble

A few cautions surfaced in practice. One is false positives on generic C function names like stat, which can match in strings or unrelated contexts, so always eyeball the detected lines. Another is that an App Extension or Widget is a separate target with its own .xcprivacy. Tidy up the main app alone and, if the extension is missing a declaration, you take the same rejection. Include the extension's sources in the scan root to stay safe.

When you are unsure which reason code to pick, there are cases where you can list several that genuinely match rather than forcing a single one. Still, "declare extras to be safe" is a habit to avoid. Listing reasons you do not actually use strays from the point of the declaration. I prefer to verify, one entry at a time, whether the code really uses the API for that purpose.

After you finish reading

Start by running scan_required_reason.py once against your project. If nothing comes up, that is reassurance; if something does, you have just cut one future rejection email. Reconcile the scan output against your current .xcprivacy, and for any undeclared category, weigh the reason codes one entry at a time — beginning from that first step is the right move.

I could not fully prevent declaration gaps myself until I put this in place. The rules will keep changing, and I am still keeping pace with them. If this helps a fellow solo developer take one steadier breath before submitting, I would be glad. Thank you for reading.