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

#!/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})\s*(?:/\*(.*?)\*/)?\s*=\s*\{(.*?)^\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})\s*(?:/\*(.*?)\*/)?\s*=\s*\{(.*)\};\s*$',
    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))]

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]))

$ 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

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

#!/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

# 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]