A Green Build Is Not Proof That Your pbxproj Edit Was Correct

The four things worth checking structurally

So instead of reading the diff, read the parse result. Four checks cover the cases above.

Check C comes from wiring the Firebase Crashlytics dSYM upload into a build phase. Scripts like that succeed by not running. You find out days later, when crash reports arrive unsymbolicated.

Check D came out of moving the Firebase Apple SDK from CocoaPods to Swift Package Manager. The package reference and the target link live in different sections of the file, and a project with only one of them still opens and still builds. Reorganizing the AdMob adapters the same way produced the same shape of half-applied dependency, and a half-applied dependency stays invisible until the day something imports it.

Writing the audit script

Xcode's UI gives you no single place to confirm all four. The pbxproj format is a line-oriented plist dialect, but for this narrow purpose regular expressions read it well enough.

#!/usr/bin/env python3
"""Structural audit for project.pbxproj: editing accidents a build cannot reveal.
Usage: python3 pbxaudit.py <path/to/project.pbxproj>
Exit codes: 0 = clean / 1 = findings / 2 = unparseable
"""
import re
import sys
 
# Multi-line objects (build phases, package references, and so on)
OBJ_BLOCK = re.compile(
    r'^\t\t([0-9A-F]{24})[ \t]*(?:/\*([^\n]*?)\*/)?[ \t]*=[ \t]*\{[ \t]*\n(.*?)^\t\t\};',
    re.M | re.S,
)
# Single-line objects (PBXBuildFile / PBXFileReference are written this way)
OBJ_LINE = re.compile(
    r'^\t\t([0-9A-F]{24})[ \t]*(?:/\*([^\n]*?)\*/)?[ \t]*=[ \t]*\{(.*)\};[ \t]*$',
    re.M,
)
KV = re.compile(r'(\w+)\s*=\s*([^;]+);')
# Headers and products legitimately belong to no target; skip them in check A
SKIP_UNOWNED = ('.h', '.hpp', '.pch', '.app', '.xcodeproj', '.framework')
 
RESOURCE_EXT = ('.png', '.jpg', '.json', '.xcassets', '.storyboard',
                '.xib', '.strings', '.plist', '.mp3', '.m4a', '.html')
 
 
def parse(text):
    """Return UUID -> {isa, comment, attrs, raw body}."""
    objects = {}
    for uid, comment, body in (list(OBJ_BLOCK.findall(text))
                               + list(OBJ_LINE.findall(text))):
        attrs = {}
        for k, v in KV.findall(body):
            attrs[k] = v.strip()
        objects[uid] = {
            'isa': attrs.get('isa', ''),
            'comment': (comment or '').strip(),
            'attrs': attrs,
            'body': body,
        }
    return objects
 
 
def uuids_in(body, key):
    """Pull UUIDs out of files = ( A /* x */, B /* y */, );"""
    m = re.search(key + r'\s*=\s*\((.*?)\);', body, re.S)
    if not m:
        return []
    return re.findall(r'([0-9A-F]{24})', m.group(1))
 
 
def paths_in(body, key):
    m = re.search(key + r'\s*=\s*\((.*?)\);', body, re.S)
    if not m:
        return []
    return [x for x in re.findall(r'"?([^",\s][^",]*)"?\s*,', m.group(1))]

That is the reading half. The checks themselves are just cross-references over what we collected.

def audit(path):
    text = open(path, encoding='utf-8', errors='replace').read()
    objects = parse(text)
    if not objects:
        print('parse failed: no objects found', file=sys.stderr)
        return 2
 
    by_isa = {}
    for uid, o in objects.items():
        by_isa.setdefault(o['isa'], []).append(uid)
 
    # Collect every fileRef a PBXBuildFile points at
    referenced = set()
    buildfile_of = {}
    for uid in by_isa.get('PBXBuildFile', []):
        ref = objects[uid]['attrs'].get('fileRef', '').split('/')[0].strip()
        if ref:
            referenced.add(ref)
            buildfile_of.setdefault(ref, []).append(uid)
 
    # What each build phase actually holds
    phase_files = {}
    for isa in ('PBXResourcesBuildPhase', 'PBXSourcesBuildPhase',
                'PBXFrameworksBuildPhase'):
        s = set()
        for uid in by_isa.get(isa, []):
            s.update(uuids_in(objects[uid]['body'], 'files'))
        phase_files[isa] = s
 
    findings = []
 
    # Check A: file references that belong to no target
    for uid in by_isa.get('PBXFileReference', []):
        name = (objects[uid]['comment']
                or objects[uid]['attrs'].get('path', '')).strip('"')
        if uid in referenced:
            continue
        etype = objects[uid]['attrs'].get('explicitFileType', '')
        if 'wrapper.application' in etype or name.endswith(SKIP_UNOWNED):
            continue
        findings.append(('A', 'not in any target', name))
 
    # Check B: resource files that never reach the Resources phase
    for uid in by_isa.get('PBXFileReference', []):
        name = (objects[uid]['comment']
                or objects[uid]['attrs'].get('path', '')).strip('"')
        if not name.lower().endswith(RESOURCE_EXT):
            continue
        bfs = buildfile_of.get(uid, [])
        if not bfs:
            continue  # already reported by check A
        if not any(b in phase_files['PBXResourcesBuildPhase'] for b in bfs):
            findings.append(('B', 'outside Resources phase', name))
 
    # Check C: Run Script phases with no declared inputs or outputs
    for uid in by_isa.get('PBXShellScriptBuildPhase', []):
        o = objects[uid]
        name = (o['attrs'].get('name', '') or o['comment']).strip('"')
        ins = paths_in(o['body'], 'inputPaths')
        outs = paths_in(o['body'], 'outputPaths')
        if not outs and o['attrs'].get('alwaysOutOfDate', '') != '1':
            findings.append(('C', 'Run Script without output paths', name or uid))
        elif not ins and outs:
            findings.append(('C', 'Run Script without input paths', name or uid))
 
    # Check D: packages added but not linked to a target
    linked = set()
    for uid in by_isa.get('XCSwiftPackageProductDependency', []):
        pkg = objects[uid]['attrs'].get('package', '').split('/')[0].strip()
        if pkg:
            linked.add(pkg)
    for uid in by_isa.get('XCRemoteSwiftPackageReference', []):
        if uid not in linked:
            findings.append(('D', 'package not linked to a target',
                             objects[uid]['comment'] or uid))
 
    for code, label, name in findings:
        print(f'[{code}] {label}: {name}')
    print(f'findings={len(findings)}')
    return 1 if findings else 0
 
 
if __name__ == '__main__':
    if len(sys.argv) != 2:
        print('usage: pbxaudit.py <project.pbxproj>', file=sys.stderr)
        sys.exit(2)
    sys.exit(audit(sys.argv[1]))

The alwaysOutOfDate lookup matters. It is set when you untick "Based on dependency analysis" on a Run Script phase, which means the script is meant to run every time, so a missing output path there is intended rather than an accident.

Testing the check itself: my first draft flagged a correct file

The script above did not work as first written.

I noticed when I fed it a tiny hand-built pbxproj in its correct shape — one image and one JSON file in the Resources phase — and expected findings=0. Instead, all three files that were in the phase came back as "[B] outside Resources phase".

The culprit was the OBJ_BLOCK regex. With re.S on, my comment pattern /\*(.*?)\*/ was free to cross newlines, so it swallowed everything from the /* main.swift in Sources */ comment on a one-line PBXBuildFile all the way to the multi-line /* Resources */ block far below. The Resources phase never made it into the dictionary, phase_files stayed empty, and check B concluded that every resource was missing from the phase.

Two changes fixed it.

After the fix, the correct file produced findings=0, and a copy with one accident planted at a time produced exactly the planted findings. I also pinned both behaviours with a regression test.

# test_pbxaudit.py — pin both "silent on a good file" and "reports a planted accident"
import subprocess
import sys
 
 
def run(path):
    p = subprocess.run([sys.executable, 'pbxaudit.py', path],
                       capture_output=True, text=True)
    return p.returncode, p.stdout
 
 
def test_clean_project_is_silent():
    code, out = run('fixtures/good.pbxproj')
    assert code == 0 and 'findings=0' in out
 
 
def test_dropped_resource_is_reported_once():
    code, out = run('fixtures/dropped_resource.pbxproj')
    assert code == 1
    assert out.count('[B]') == 1

Every pbxproj I used here is a synthetic sample I assembled by hand. A real app project carries far more that this script never reads — groups, build configurations, format quirks. If your first run on a shipping project reports something surprising, suspect the check before the project, then add a fixture that reproduces it.

A check earns trust by staying quiet on a correct file before it reports anything.

Writing a check that finds accidents is the easy half. A check that cries wolf gets ignored within days, so for scripts like this I write the silent-case test first.

What I measured on my machine

Running it against a pbxproj seeded with all four accidents produced exactly four findings.

$ python3 pbxaudit.py sample.pbxproj
[A] not in any target: Localizable.strings
[B] outside Resources phase: categories_v7.json
[C] Run Script without output paths: Upload dSYM to Crashlytics
[D] package not linked to a target: XCRemoteSwiftPackageReference "GoogleMobileAds"
findings=4
$ echo $?
1

Fixing all four in place brought it back to findings=0 and exit code 0, with no leftover noise. That second half matters more than the first. A check that always reports one warning is a check nobody reads after the first week.

Scale behaved well too. On a 404 KB, 3,716-line pbxproj holding 600 sources and 600 images, five consecutive runs each took 0.10 seconds. Twelve hundred files is close to what my wallpaper apps actually carry, and at that cost you can afford to run it on every commit.

Then the single removed line from earlier — the one that was indistinguishable in the diff:

$ python3 pbxaudit.py big_broken.pbxproj
[B] outside Resources phase: img66.png
findings=1

What disappears at the granularity of a diff stands up as one finding at the granularity of structure. That contrast is what convinced me to keep this around.

What to delegate, and what to let Xcode generate

With the check in place, the delegation question becomes answerable. My line is simple: can I reliably get back to the previous state if this goes wrong?

The point is not to keep agents away from the project. It is to move the entry point for edits out of pbxproj and into .xcconfig. Once build settings live in xcconfig files, what the agent touches is ordinary text with a diff you can read, and pbxproj is left holding only the structural parts that Xcode generates faster anyway.

I approached the delegation boundary from a different angle in What I regretted delegating to AI: an indie developer's boundary. pbxproj is one of the few cases where I landed firmly on the "do not delegate" side.

Catch it before the commit lands

A check you have to remember to run is not a check. This one fires only on commits that touch a pbxproj.

#!/bin/sh
# .git/hooks/pre-commit
set -e
 
changed=$(git diff --cached --name-only --diff-filter=ACM | grep 'project\.pbxproj$' || true)
[ -z "$changed" ] && exit 0
 
for f in $changed; do
  # Audit the staged content, not the working tree
  tmp=$(mktemp)
  git show ":$f" > "$tmp"
  if ! python3 tools/pbxaudit.py "$tmp"; then
    echo "Structural audit reported findings for: $f"
    echo "If the change is intentional, add a line to tools/pbxaudit-allow.txt."
    rm -f "$tmp"
    exit 1
  fi
  rm -f "$tmp"
done

git show ":$f" is the part worth copying. Reading the working tree instead would audit content that differs from what actually gets committed whenever you stage selectively with git add -p.

When an Antigravity agent works unattended, this hook becomes the last gate before anything lands. Agents read commit output, so printing the specific finding gives them enough to correct themselves on the next attempt. It pairs well with confirming which files an agent can even see, which I covered in Files Git tracks but your agent cannot read, and where they drop out.

Keeping false positives out

Every project has files deliberately kept out of a target: READMEs, design source assets, JSON used only by tests. Flagging those on every run is how a check earns its way into being ignored.

I keep the exclusions in a repository text file rather than in the script.

# Insert after findings are collected in audit()
def load_allow(path='tools/pbxaudit-allow.txt'):
    try:
        lines = open(path, encoding='utf-8').read().splitlines()
    except FileNotFoundError:
        return set()
    return {l.strip() for l in lines if l.strip() and not l.startswith('#')}
 
allow = load_allow()
findings = [f for f in findings if f[2] not in allow]

A text file lets you write the reason next to the entry, which is what makes it readable six months later. If that list keeps growing, the check itself is out of step with how the project works, and the right move is to fix the check.

Three things I learned putting it into daily use

None of these are about the checks themselves. They are about where the script sits and how its failures are treated.

Do not let an unparseable day pass silently

The script returns exit code 2 when it finds no objects at all. The hook above treats that as a failure because it tests with !, but adding || true to a CI one-liner erases the distinction instantly. From the day Xcode changes the format, the check would quietly stop working. I keep "clean" and "could not read" on separate exit codes and fail the CI job on 2 as well.

Make it fit how agents retry

When pre-commit rejects a commit, an Antigravity agent will rebuild it. If all you print is a check code and a filename, the agent has nothing to act on and repeats the same mistake. Printing which file dropped out of which phase gives it enough to fix itself on the next attempt. In unattended runs, the specificity of your error message is your recovery time.

Put it earlier than production CI

I tried running it only in CI. The finding then arrives minutes after the build starts, which slows down isolating the cause. I recommend the local hook as the primary gate with CI as the backstop — hooks can be disabled per machine, so the CI copy has to stay.

One thing to try next

Run it once against a project you already ship. Three steps:

1. Drop pbxaudit.py into tools/ and run it against the project.pbxproj you are shipping today
2. Read the findings by category A through D, and move only the deliberate ones into tools/pbxaudit-allow.txt with a reason
3. Once the remaining findings reach zero, enable the pre-commit hook

A first run on an existing codebase usually surfaces somewhere between a handful and a dozen findings, and whether any of them is news to you is the honest test of whether this belongs in your pipeline.

For a long time I treated pbxproj as territory Xcode owns and nobody else should enter. Running agents daily changed that view: leaving it untouched is not the same as knowing it is correct, and the difference has to be checked by something that reads structure. I am still adding checks, and I would be glad if this saves someone the same detour.