appstore-precheck 1.5.2 → 1.7.0

package/CHANGELOG.md

@@ -3,6 +3,57 @@
 All notable changes to this project are documented here. Versioning follows
 [SemVer](https://semver.org/). Released as git tags.
 
+## [Unreleased]
+
+## [1.7.0] - 2026-07-02
+
+Smarter analysis (roadmap #2b): the scanner now resolves the iOS source directory
+and `Info.plist` from the Xcode **project model** (`.pbxproj`) instead of a pure
+grep heuristic, eliminating the dominant remaining false-positive source in
+monorepo / SPM / multi-target layouts. Zero new runtime dependencies (pure
+bash + awk), READ-ONLY preserved, and default text output stays byte-identical for
+any repo without a `.pbxproj`.
+
+### Added
+- **Project-model detection** (`skills/appstore-precheck/scripts/project-model.sh`):
+  parses `.pbxproj` to find the primary `application`-type target and resolve its
+  source dir + `INFOPLIST_FILE` authoritatively, across ALL `.xcodeproj` in a
+  monorepo. `detect_ios_dir` now chains: config `.iosSourceDir` > project-model
+  parse > the original grep heuristic (unchanged, kept as fallback).
+- Per-target `INFOPLIST_FILE` attribution via the build-config graph
+  (target → `buildConfigurationList` → `XCBuildConfiguration`), used as a last
+  resort so already-correct apps are untouched; unexpanded build-variable paths
+  (`$(SRCROOT)` etc.) are guarded, and app targets under vendored paths
+  (`ThirdParty`/`Vendor`) are deprioritized so a vendored sample app never wins.
+
+### Measured impact (18-app open-source panel, candidate/directional labels)
+- Corrects detection on `wikipedia-ios`, `pocket-casts-ios`, `cwa-app-ios`
+  (now read their real custom-named plists) and `brave-ios` (real app over a
+  vendored sample). `usage-description-crosscheck` false positives 9 → 6, with
+  content-grounded findings surfaced by finally reading the correct plist; zero
+  true-positive loss. See `docs/fp-reduction-report.md`.
+
+## [1.6.0] - 2026-07-01
+
+Measurement release: structured findings, suppression, and a published
+precision/recall scorecard, plus a measurement-driven false-positive reduction
+round. Default text output stays byte-identical (verified across 11 fixtures);
+every behavior change is gated by TDD and the synthetic-corpus `--check`.
+
+### Added
+- **`scan.sh --format json`**: structured findings envelope (`{tool, version, verdict, summary{fail,warn,pass,suppressed}, findings[{rule_id, severity, guideline, message, file, line, suppressed}]}`) for tooling and measurement. Stable `rule_id` per vector via a 41-slug catalog. Default text output is unchanged.
+- **`.precheck-ignore` suppression**: repo-root rules (`<rule-id>`, `<rule-id> <path-glob>`, `<path-glob>`-exclude) and inline `# precheck:ignore [rule-id]` directives (`//`, `#`, `<!-- -->`). Suppression is emit-time — a suppressed FAIL no longer forces RED — and always transparent: suppressed findings stay in `findings[]` with `suppressed:true`, count in `summary.suppressed`, and a text footer reports the count only when non-zero (byte-identity preserved otherwise).
+- **Precision/recall scorecard**: `scripts/scorecard.sh` (`--check` / `--selftest` / default) over a synthetic labelled corpus (`corpus/synthetic/labels.json`), plus `scripts/scorecard-real.sh` over an 18-app commit-pinned open-source real panel (`corpus/real/`). Published to `docs/scorecard.md` with a mandatory honesty section (neither corpus claims agreement with Apple's actual decisions). Synthetic `--check` is a blocking CI gate; the real panel is non-blocking.
+- File/line threading into locatable checks (surfaced in JSON; text output unchanged).
+
+### Fixed
+- **False-positive reduction round** (measurement-driven; ~33 FP eliminated across the 18-app panel with zero true-positive loss, char-limit-excluded precision 0.37 → ~0.54):
+  - **Analytics detection** now requires an import/API-qualified form, so a bare `Segment` substring (e.g. `UISegmentedControl`) no longer trips 5.1.1.
+  - **IAP gate** requires a real purchase API, ignoring `SKStoreReviewController` / `SKAdNetwork` / the `AppStore.` namespace.
+  - **Usage-description checks** are capture-gated: playback-only AVFoundation / PhotosPicker no longer false-fire; mic matches `.playAndRecord`; video-only `AVCaptureDevice` no longer triggers the microphone check.
+  - **Minimum-functionality navigation** detects UIKit / `NavigationView` / React-Navigation repo-wide.
+  - **Screenshots-per-locale**: no in-repo screenshots directory is an advisory PASS (managed in App Store Connect), not a WARN.
+
 ## [1.5.2] - 2026-06-30
 
 ### Fixed

package/README.md

@@ -240,8 +240,14 @@ npx appstore-precheck --fail-on YELLOW
 
 ```bash
 bash skills/appstore-precheck/scripts/scan.sh   # from a clone of this repo
+bash skills/appstore-precheck/scripts/scan.sh --format json   # structured findings, for tooling
 ```
 
+`--format json` emits a structured findings envelope (`rule_id`, `severity`, `guideline`,
+`message`, and optional `file`/`line` per finding, plus the verdict summary) instead of the
+default text lines, for scripts and measurement tooling to consume. It's read-only and additive;
+the default text output is unchanged.
+
 ### CI
 
 Drop the static scan into a workflow with the bundled composite action. It fails the
@@ -320,6 +326,26 @@ and [Phase 2 `fastlane precheck`](examples/fastlane-precheck.md) results.
 | 🟡 **YELLOW** | 0 FAIL, 5+ WARN | not written | blocked; needs confirmation |
 | 🔴 **RED** | ≥1 FAIL | removed | blocked; shows the FAIL list |
 
+## Measured accuracy
+
+[`docs/scorecard.md`](docs/scorecard.md) is generated by `scripts/scorecard.sh` and tracks two
+independent measurements:
+
+- **Synthetic precision** — the project's own labelled fixtures (`corpus/synthetic/`), each tagging
+  the rule-ids it must fire and the rule-ids that must stay silent. This is a **CI-gated floor**:
+  `scripts/scorecard.sh --check` fails the build if precision drops below 0.80 or the doc goes stale.
+- **Real-panel FP rate** — a pinned, license-verified panel of permissively-licensed open-source
+  iOS/Swift/React-Native apps (`corpus/real/manifest.json`), scanned and joined against a one-time
+  human TP/FP labelling pass (`corpus/real/labels.json`). Every finding is reported `UNLABELED` until
+  a human reviews it, so **no unreviewed number is ever published**. Run it yourself with
+  `bash scripts/scorecard.sh --real`; CI runs it as a separate **non-blocking, informational** job
+  (`continue-on-error: true`) that never gates a PR.
+
+**Neither measurement claims agreement with Apple's actual review decisions.** Synthetic precision
+measures intended-behaviour fidelity against fixtures this project wrote; real-panel precision
+measures the false-positive rate on real, unrelated open-source code. See
+[`docs/scorecard.md`](docs/scorecard.md) for the current numbers and full methodology.
+
 ## Configuration
 
 Zero config for a standard fastlane + Xcode layout. The scanner auto-detects your source directory,
@@ -327,6 +353,37 @@ fastlane metadata, screenshots, String Catalog, paywall view, and locales. Overr
 `.appstore-precheck.json` at your repo root (copy
 [`config.example.json`](skills/appstore-precheck/config.example.json)).
 
+### Suppressing findings (`.precheck-ignore`)
+
+Drop a `.precheck-ignore` file at your repo root to suppress findings you've reviewed and accepted
+on purpose. One entry per line; `#` starts a trailing comment. Three grammar forms:
+
+| Form | Example | Effect |
+|------|---------|--------|
+| `<rule-id>` | `account-no-delete` | suppress that rule everywhere in the repo |
+| `<rule-id> <path-glob>` | `ats-arbitrary-loads ios/Legacy/` | suppress that rule only under the matching path |
+| `<path-glob>` | `vendor/` | exclude the matching path from scanning entirely |
+
+You can also suppress a single finding inline, with a `//`, `#`, or `<!-- -->` comment marker on the
+flagged line or the line directly above it:
+
+```swift
+let x = UIWebView() // precheck:ignore private-api
+```
+
+```html
+<!-- precheck:ignore -->
+<key>NSAllowsArbitraryLoads</key>
+```
+
+A bare `precheck:ignore` (no rule-id) suppresses **any** rule on that line; a scoped
+`precheck:ignore <rule-id>` only suppresses that one rule, leaving every other rule on the same line
+free to fire.
+
+**Suppressed findings are always counted, never silently hidden.** `scan.sh --format json` still
+emits them with `"suppressed": true`, and the text/summary output always states how many findings
+were suppressed.
+
 ## Cross-tool support
 
 `SKILL.md` follows the [Agent Skills open standard](https://agentskills.io), with no per-tool conversion.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appstore-precheck",
-  "version": "1.5.2",
+  "version": "1.7.0",
   "description": "Read-only iOS App Store pre-submission check, packaged as a portable Agent Skill with native Claude Code, Cursor, and Codex plugins, plus an npx CLI.",
   "license": "MIT",
   "author": "Berkay Turk (https://github.com/berkayturk)",
@@ -25,7 +25,7 @@
   "scripts": {
     "test": "bash tests/all.sh",
     "check-versions": "bash scripts/check-versions.sh",
-    "lint": "node --check bin/cli.js && bash -n skills/appstore-precheck/scripts/scan.sh && bash -n skills/appstore-precheck/scripts/verdict.sh && bash -n skills/appstore-precheck/scripts/phase2-precheck.sh && bash -n hooks/fastlane-guard.sh && bash -n install.sh && bash -n tests/run.sh && bash -n tests/all.sh && bash -n tests/test-verdict.sh && bash -n tests/test-guard.sh && bash -n tests/test-config.sh && bash -n tests/test-install.sh && bash -n tests/test-phase2.sh && bash -n tests/test-cli.sh"
+    "lint": "node --check bin/cli.js && bash -n skills/appstore-precheck/scripts/scan.sh && bash -n skills/appstore-precheck/scripts/verdict.sh && bash -n skills/appstore-precheck/scripts/phase2-precheck.sh && bash -n skills/appstore-precheck/scripts/findings.sh && bash -n skills/appstore-precheck/scripts/suppress.sh && bash -n hooks/fastlane-guard.sh && bash -n install.sh && bash -n tests/run.sh && bash -n tests/all.sh && bash -n tests/test-verdict.sh && bash -n tests/test-guard.sh && bash -n tests/test-config.sh && bash -n tests/test-install.sh && bash -n tests/test-phase2.sh && bash -n tests/test-cli.sh && bash -n tests/test-findings.sh && bash -n tests/test-format-json.sh && bash -n tests/test-suppress.sh && bash -n tests/test-scorecard.sh && bash -n scripts/scorecard.sh && bash -n scripts/scorecard-real.sh"
   },
   "keywords": ["ios", "app-store", "fastlane", "agent-skill", "claude-code", "precheck"]
 }

package/skills/appstore-precheck/SKILL.md

@@ -4,7 +4,7 @@ description: Read-only pre-submission check for an iOS app before App Store revi
 license: MIT
 metadata:
   author: Berkay Turk
-  version: 1.5.2
+  version: 1.7.0
 allowed-tools: Bash Read Grep Glob WebFetch
 ---
 
@@ -136,6 +136,11 @@ full check table is in
 The scanner is portable Bash, so you can also run it directly, outside any agent, for a quick CI
 or pre-commit check.
 
+`scan.sh --format json` emits a structured findings envelope (`rule_id`, `severity`, `guideline`,
+`message`, optional `file`/`line` per finding, plus the verdict summary) instead of the default
+text lines, for tooling and measurement to consume. It's read-only and additive; the default text
+output is unchanged.
+
 ### Phase 2: Apple's official `fastlane precheck`
 
 Requires `bundleId` in config (or pass `app_identifier` directly) and App Store Connect API

package/skills/appstore-precheck/scripts/findings.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# findings.sh — structured-findings layer for scan.sh.
+# Sourced by scan.sh. Adds a parallel machine-readable channel; text output is untouched.
+# Bash 3.2 compatible: NO associative arrays (catalog is a case lookup).
+
+# rule_slug <section-number> -> stable kebab-case slug, or "" if unknown.
+rule_slug() {
+  case "$1" in
+    1) echo privacy-manifest-parity ;;        2) echo usage-description-crosscheck ;;
+    3) echo att-usage ;;                       4) echo competitor-mentions ;;
+    5) echo metadata-char-limits ;;            6) echo locale-metadata-parity ;;
+    7) echo screenshots-per-locale ;;          8) echo trial-disclosure ;;
+    9) echo autorenew-disclosure ;;           10) echo subscription-links-restore ;;
+    11) echo private-api ;;                    12) echo min-functionality-nav ;;
+    13) echo screentime-justification ;;       14) echo siwa-parity ;;
+    15) echo external-purchase-link ;;         16) echo tracking-sdk-no-att ;;
+    17) echo export-compliance ;;              18) echo support-privacy-url ;;
+    19) echo analytics-privacyinfo-mismatch ;; 20) echo placeholder-metadata ;;
+    21) echo thirdparty-payment-sdk ;;         22) echo ugc-no-moderation ;;
+    23) echo ats-arbitrary-loads ;;            24) echo applepay-recurring-disclosure ;;
+    25) echo custom-review-prompt ;;           26) echo misleading-marketing ;;
+    27) echo kids-wording ;;                   28) echo keyboard-full-access ;;
+    29) echo health-icloud-sync ;;             30) echo vpn-networkextension ;;
+    31) echo demo-account ;;                   32) echo executable-code-download ;;
+    33) echo background-modes-unused ;;        34) echo crypto-wallet-mining ;;
+    35) echo webview-wrapper ;;                36) echo remote-desktop ;;
+    37) echo safari-extension ;;               38) echo account-no-delete ;;
+    39) echo kids-ads-analytics ;;             40) echo realmoney-gambling ;;
+    41) echo mdm ;;                            *) echo "" ;;
+  esac
+}
+
+_CURRENT_RULE=""
+set_rule() { _CURRENT_RULE="$1"; }
+
+: "${FINDINGS_TMP:=}"
+
+# _record <severity> <message> [<file>] [<line>]
+_record() {
+  [[ -z "$FINDINGS_TMP" ]] && return 0
+  local sev="$1" msg="$2" file="${3:-}" line="${4:-}" guideline
+  guideline="$(printf '%s' "$msg" | awk '{print $1}')"
+  jq -nc --arg r "$_CURRENT_RULE" --arg s "$sev" --arg g "$guideline" \
+        --arg m "$msg" --arg f "$file" --arg l "$line" \
+    '{rule_id:$r, severity:$s, guideline:$g, message:$m,
+      file:(if $f=="" then null else $f end),
+      line:(if $l=="" then null else ($l|tonumber) end),
+      suppressed:false}' >> "$FINDINGS_TMP"
+}
+
+: "${_SUPPRESSED_COUNT:=0}"
+
+# _record_suppressed <severity> <message> [<file>] [<line>]
+# Same JSONL record as _record but suppressed:true, and bumps the counter.
+_record_suppressed() {
+  [[ -z "$FINDINGS_TMP" ]] && { _SUPPRESSED_COUNT=$((_SUPPRESSED_COUNT + 1)); return 0; }
+  local sev="$1" msg="$2" file="${3:-}" line="${4:-}" guideline
+  guideline="$(printf '%s' "$msg" | awk '{print $1}')"
+  jq -nc --arg r "$_CURRENT_RULE" --arg s "$sev" --arg g "$guideline" \
+        --arg m "$msg" --arg f "$file" --arg l "$line" \
+    '{rule_id:$r, severity:$s, guideline:$g, message:$m,
+      file:(if $f=="" then null else $f end),
+      line:(if $l=="" then null else ($l|tonumber) end),
+      suppressed:true}' >> "$FINDINGS_TMP"
+  _SUPPRESSED_COUNT=$((_SUPPRESSED_COUNT + 1))
+}
+
+: "${PRECHECK_VERSION:=dev}"
+
+# render_json -> prints the structured envelope. Verdict reuses verdict.sh thresholds
+# (RED >=1 FAIL; YELLOW >=5 WARN; else GREEN), counting non-suppressed findings only.
+render_json() {
+  local buf="${FINDINGS_TMP:-/dev/null}"
+  [[ -s "$buf" ]] || { printf '%s\n' '{"findings":[]}' | jq \
+     --arg v "$PRECHECK_VERSION" '{tool:"appstore-precheck",version:$v,verdict:"GREEN",summary:{fail:0,warn:0,pass:0,suppressed:0},findings:[]}'; return 0; }
+  jq -s --arg v "$PRECHECK_VERSION" '
+    (map(select(.suppressed==false))) as $live
+    | ($live|map(select(.severity=="FAIL"))|length) as $f
+    | ($live|map(select(.severity=="WARN"))|length) as $w
+    | ($live|map(select(.severity=="PASS"))|length) as $p
+    | (map(select(.suppressed==true))|length) as $s
+    | (if $f>=1 then "RED" elif $w>=5 then "YELLOW" else "GREEN" end) as $verdict
+    | {tool:"appstore-precheck", version:$v, verdict:$verdict,
+       summary:{fail:$f, warn:$w, pass:$p, suppressed:$s},
+       findings: .}' "$buf"
+}

package/skills/appstore-precheck/scripts/project-model.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# project-model.sh — resolve the primary app target's source dir + Info.plist from
+# an Xcode project model (.pbxproj), authoritatively and dependency-free.
+# Sourced by scan.sh. Pure bash + awk. READ-ONLY. Bash 3.2 compatible.
+
+# pm_app_targets <pbxproj> -> names of targets whose productType is the application type.
+# .pbxproj PBXNativeTarget blocks list `name` before `productType`; the block closes
+# with a bare `};`. Nested lists close with `)`, never `};`, so `};` reliably ends a block.
+pm_app_targets() {
+  awk '
+    /isa = PBXNativeTarget;/ { in_t=1; name=""; pt=""; next }
+    in_t && /^[[:space:]]*name = / {
+      l=$0; sub(/^[[:space:]]*name = /,"",l); sub(/;[[:space:]]*$/,"",l); gsub(/^"|"$/,"",l); name=l
+    }
+    in_t && /^[[:space:]]*productType = / {
+      l=$0; sub(/^[[:space:]]*productType = /,"",l); sub(/;[[:space:]]*$/,"",l); gsub(/^"|"$/,"",l); pt=l
+    }
+    in_t && /^[[:space:]]*};[[:space:]]*$/ {
+      if (pt == "com.apple.product-type.application" && name != "") print name
+      in_t=0
+    }
+  ' "$1"
+}
+
+# pm_infoplist_files <pbxproj> -> every INFOPLIST_FILE value, unquoted, sorted, deduped.
+pm_infoplist_files() {
+  awk '/^[[:space:]]*INFOPLIST_FILE = /{
+    l=$0; sub(/^[[:space:]]*INFOPLIST_FILE = /,"",l); sub(/;[[:space:]]*$/,"",l); gsub(/^"|"$/,"",l); print l
+  }' "$1" | sort -u
+}
+
+# pm_target_infoplist <pbxproj> <target> -> the target's own INFOPLIST_FILE via its
+# build configurations (first non-empty), or non-zero. Handles quoted paths with spaces.
+#
+# A repo may declare INFOPLIST_FILE for several targets whose leading path
+# component does not match the target name (e.g. Client's plist lives under
+# "iOS/Supporting Files"). pm_infoplist_files() alone cannot attribute a given
+# plist to a specific target, so this walks the actual pbxproj graph:
+# PBXNativeTarget "name = X" -> buildConfigurationList = <UUID> -> the
+# XCConfigurationList block for that UUID -> its buildConfigurations list ->
+# each XCBuildConfiguration block, looking for INFOPLIST_FILE.
+#
+# NOTE: this returns the FIRST build config's plist, which is only reliable
+# when all configs agree. Per-configuration plists (Debug vs Release) can
+# legitimately differ (e.g. cwa-app-ios's ENA target), so pm_resolve() only
+# calls this as a LAST RESORT — after the leading-component match and the
+# GENERATE dir-name branch have both failed. Callers must also guard against
+# unexpanded Xcode build variables (e.g. "$(SRCROOT)/...") in the returned
+# path, since those can never resolve to a real file on disk.
+pm_target_infoplist() {
+  local pbx="$1" target="$2" cl u ip
+  cl="$(awk -v t="$target" '
+    /isa = PBXNativeTarget;/{inb=1;nm="";c="";next}
+    inb&&/^[[:space:]]*name = /{l=$0;sub(/^[[:space:]]*name = /,"",l);sub(/;[[:space:]]*$/,"",l);gsub(/^"|"$/,"",l);nm=l}
+    inb&&/^[[:space:]]*buildConfigurationList = /{l=$0;sub(/^[[:space:]]*buildConfigurationList = /,"",l);sub(/;[[:space:]]*$/,"",l);sub(/ .*/,"",l);c=l}
+    inb&&/^[[:space:]]*};[[:space:]]*$/{if(nm==t&&c!=""){print c;exit}inb=0}
+  ' "$pbx")"
+  [[ -z "$cl" ]] && return 1
+  # Match only the block-OPENING line for a UUID (ends in "{"), never a
+  # reference to that UUID inside some other list (e.g. the UUID also
+  # appears as a bare list item "CFG1 /* Debug */," inside the
+  # buildConfigurations array itself, which would otherwise false-match).
+  local bcs; bcs="$(awk -v cl="$cl" '
+    $0 ~ ("^[[:space:]]*" cl "[[:space:]]") && /\{[[:space:]]*$/ {inb=1}
+    inb&&/buildConfigurations = \(/{inl=1;next}
+    inb&&inl&&/\)/{exit}
+    inb&&inl{l=$0;sub(/\/\*.*/,"",l);gsub(/[[:space:]]/,"",l);sub(/,$/,"",l);if(l!="")print l}
+  ' "$pbx")"
+  [[ -z "$bcs" ]] && return 1
+  for u in $bcs; do
+    ip="$(awk -v u="$u" '
+      $0 ~ ("^[[:space:]]*" u "[[:space:]]") && /\{[[:space:]]*$/ {inb=1}
+      inb&&/^[[:space:]]*INFOPLIST_FILE = /{l=$0;sub(/^[[:space:]]*INFOPLIST_FILE = /,"",l);sub(/;[[:space:]]*$/,"",l);gsub(/^"|"$/,"",l);print l;exit}
+      inb&&/^[[:space:]]*};[[:space:]]*$/{exit}
+    ' "$pbx")"
+    [[ -n "$ip" ]] && { printf '%s\n' "$ip"; return 0; }
+  done
+  return 1
+}
+
+# Vendored dirs whose .xcodeproj must never win detection.
+PM_PRUNE_DIRS='node_modules|Pods|Carthage|\.build|DerivedData|\.git'
+
+# App targets whose project lives under a vendored/sample path are deprioritized:
+# they only win when no primary (non-vendored) app target exists. This is a
+# deprioritization heuristic (mirrors scan.sh's NONAPP_TARGET), bounded on
+# purpose: a sample app under a clearly-vendored path (ThirdParty/Vendor)
+# loses to a primary app, but the heuristic deliberately does NOT match
+# Demo/Sample/Example-named dirs, because those often hold a library repo's
+# real deliverable app rather than a throwaway sample (Pods/Carthage/
+# node_modules are already fully pruned by PM_PRUNE_DIRS in
+# pm_find_pbxprojs, so they need not be listed here either).
+PM_SAMPLE_PATH='(^|/)(ThirdParty|Vendor(ed)?)(/|$)'
+
+# pm_find_pbxprojs <root> -> all project.pbxproj under *.xcodeproj (pruned), deterministic order.
+pm_find_pbxprojs() {
+  local root="${1:-.}"
+  find "$root" -name 'project.pbxproj' -path '*.xcodeproj/*' 2>/dev/null \
+    | grep -Ev "/($PM_PRUNE_DIRS)/" \
+    | LC_ALL=C sort
+}
+
+# pm_resolve <root> -> "DIR<TAB>PLIST" (ROOT-relative; PLIST may be empty) for the
+# primary app target, or non-zero with no output.
+#
+# A monorepo may contain several .xcodeproj (samples, sub-projects, the real
+# app). The shallowest one is not necessarily the real app, so every pbxproj
+# is resolved on its own terms (against its own SRCROOT-relative projdir) and
+# the single global best — most *.swift sources — wins across all of them.
+pm_resolve() {
+  local root="${1:-.}" pbx rel projdir apps plists app plist dir n cand_dir cand_plist
+  # "best" is the primary (non-vendored/sample) bucket; "alt" collects app
+  # targets whose project lives under a vendored/sample path (PM_SAMPLE_PATH).
+  # alt only wins when no primary candidate exists at all — see the tail.
+  local best="" best_plist="" best_n=-1
+  local alt="" alt_plist="" alt_n=-1
+  local found=0
+  # Normalize a trailing slash so the ROOT-relative strip below reliably matches
+  # (root="/" strips to "" and must stay "/"; root="." is untouched).
+  root="${root%/}"; [[ -z "$root" ]] && root="/"
+  while IFS= read -r pbx; do
+    [[ -z "$pbx" ]] && continue
+    apps="$(pm_app_targets "$pbx")"; [[ -z "$apps" ]] && continue
+    found=1
+    # ROOT-relative dir that contains this .xcodeproj (SRCROOT). Its
+    # INFOPLIST_FILE paths and app source dir are relative to this.
+    rel="${pbx#"$root"/}"                 # e.g. ios/App.xcodeproj/project.pbxproj
+    projdir="$(dirname "$(dirname "$rel")")"; projdir="${projdir#./}"
+    [[ "$projdir" == "." ]] && projdir=""
+    plists="$(pm_infoplist_files "$pbx")"
+    while IFS= read -r app; do
+      [[ -z "$app" ]] && continue
+      # Priority 1: a declared plist whose leading path component equals the
+      # app target name.
+      plist="$(printf '%s\n' "$plists" | awk -v a="$app" -F/ '$1==a{print; exit}')"
+      if [[ -n "$plist" ]]; then
+        dir="$(dirname "$plist")"
+      else
+        # Priority 2 (GENERATE_INFOPLIST_FILE): no leading-component plist.
+        # Use the dir named after the target.
+        dir="$(cd "$root${projdir:+/$projdir}" 2>/dev/null && \
+               find . -type d -name "$app" 2>/dev/null | sed 's#^\./##' \
+               | awk '{print length, $0}' | sort -n | head -1 | cut -d' ' -f2-)"
+        if [[ -z "$dir" ]]; then
+          # Priority 3 (LAST RESORT — only reached when both of the above
+          # fail, i.e. the target would otherwise be skipped entirely):
+          # attribute the target's OWN INFOPLIST_FILE via the pbxproj's
+          # build-config graph. Works even when the plist's leading path
+          # component doesn't match the target name (e.g. brave-ios's
+          # Client -> "iOS/Supporting Files/Info.plist"), but must not
+          # override a working leading-component or GENERATE resolution
+          # (e.g. eigen's Artsy, cwa-app-ios's ENA), so it stays last.
+          plist="$(pm_target_infoplist "$pbx" "$app" 2>/dev/null)"
+          # A literal, unexpanded Xcode build variable (e.g. $(SRCROOT),
+          # $(PROJECT_DIR)) can never be found on disk — treat it as
+          # unusable rather than resolving to a broken path.
+          [[ "$plist" == *'$('* ]] && plist=""
+          if [[ -n "$plist" ]]; then
+            dir="$(dirname "$plist")"
+          else
+            continue
+          fi
+        fi
+      fi
+      n="$(cd "$root${projdir:+/$projdir}" 2>/dev/null && \
+           find "$dir" -name '*.swift' 2>/dev/null | wc -l | tr -d ' ')"
+      # Prefix the projdir so paths are ROOT-relative before comparing/storing.
+      cand_dir="${projdir:+$projdir/}$dir"
+      cand_plist=""
+      [[ -n "$plist" ]] && cand_plist="${projdir:+$projdir/}$plist"
+      if [[ "$projdir" =~ $PM_SAMPLE_PATH ]]; then
+        if (( n > alt_n )); then
+          alt_n=$n; alt="$cand_dir"; alt_plist="$cand_plist"
+        fi
+      else
+        if (( n > best_n )); then
+          best_n=$n; best="$cand_dir"; best_plist="$cand_plist"
+        fi
+      fi
+    done <<< "$apps"
+  done <<< "$(pm_find_pbxprojs "$root")"
+  [[ $found -eq 0 ]] && return 1
+  if [[ -n "$best" ]]; then
+    printf '%s\t%s\n' "$best" "$best_plist"
+  elif [[ -n "$alt" ]]; then
+    printf '%s\t%s\n' "$alt" "$alt_plist"
+  else
+    return 1
+  fi
+}

package/skills/appstore-precheck/scripts/scan.sh

@@ -12,6 +12,29 @@ set -u
 ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || ROOT="$(pwd)"
 cd "$ROOT" || { echo "FAIL: repo-root — could not enter repository root"; exit 0; }
 
+source "$(dirname "${BASH_SOURCE[0]}")/findings.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/suppress.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/project-model.sh"
+FINDINGS_TMP="$(mktemp)"; export FINDINGS_TMP
+trap 'rm -f "$FINDINGS_TMP"' EXIT
+FORMAT="text"
+# The envelope `version` is the appstore-precheck TOOL's own version (from this
+# skill's SKILL.md), never the scanned repo's — $ROOT above is the SCANNED app's
+# git root, so reading its package.json here would leak the wrong version.
+PRECHECK_VERSION="$(grep -m1 -E '^[[:space:]]*version:' "$(dirname "${BASH_SOURCE[0]}")/../SKILL.md" 2>/dev/null | sed -E 's/.*version:[[:space:]]*//; s/[[:space:]]*$//')"
+[[ -z "$PRECHECK_VERSION" ]] && PRECHECK_VERSION="dev"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --format)
+      if [[ $# -lt 2 ]]; then echo "scan.sh: --format needs a value (text|json)" >&2; exit 64; fi
+      FORMAT="$2"; shift 2 ;;
+    --format=*) FORMAT="${1#*=}"; shift ;;
+    *) shift ;;
+  esac
+done
+[[ "$FORMAT" == json || "$FORMAT" == text ]] || { echo "scan.sh: --format must be text|json" >&2; exit 64; }
+
 CONFIG="${APPSTORE_PRECHECK_CONFIG:-.appstore-precheck.json}"
 have_jq() { command -v jq >/dev/null 2>&1; }
 
@@ -32,9 +55,13 @@ cfg_bool() { # cfg_bool <json-path> — echoes "true"/"false"
   echo "false"
 }
 
-fail() { echo "FAIL: $1"; }
-warn() { echo "WARN: $1"; }
-pass() { echo "PASS: $1"; }
+_LAST_SUPPRESSED=0
+fail() { if is_suppressed "$_CURRENT_RULE" "${2:-}" "${3:-}"; then _record_suppressed FAIL "$1" "${2:-}" "${3:-}"; _LAST_SUPPRESSED=1; else echo "FAIL: $1"; _record FAIL "$1" "${2:-}" "${3:-}"; _LAST_SUPPRESSED=0; fi; }
+warn() { if is_suppressed "$_CURRENT_RULE" "${2:-}" "${3:-}"; then _record_suppressed WARN "$1" "${2:-}" "${3:-}"; _LAST_SUPPRESSED=1; else echo "WARN: $1"; _record WARN "$1" "${2:-}" "${3:-}"; _LAST_SUPPRESSED=0; fi; }
+pass() { if is_suppressed "$_CURRENT_RULE" "${2:-}" "${3:-}"; then _record_suppressed PASS "$1" "${2:-}" "${3:-}"; _LAST_SUPPRESSED=1; else echo "PASS: $1"; _record PASS "$1" "${2:-}" "${3:-}"; _LAST_SUPPRESSED=0; fi; }
+
+# detail <text> — indented evidence under the previous finding; skipped when it was suppressed.
+detail() { [[ "${_LAST_SUPPRESSED:-0}" == 1 ]] || printf '%s\n' "$1" | sed 's/^/      /'; }
 
 # ===================================================================
 # Auto-detection of the project layout
@@ -55,6 +82,17 @@ GREP_PRUNE=( --exclude-dir=.git --exclude-dir=Pods --exclude-dir=Carthage
             --exclude-dir=.claude --exclude-dir=worktrees
             --exclude-dir=node_modules --exclude-dir=vendor )
 
+# Load .precheck-ignore path exclusions (Task 2 suppress.sh) and extend both
+# prune sets so a suppressed path is skipped by detection AND grep passes.
+load_precheck_ignore "$ROOT"
+while IFS= read -r _g; do
+  [[ -z "$_g" ]] && continue
+  PRUNE+=( -not -path "*/$_g/*" -not -path "$_g/*" )
+  GREP_PRUNE+=( --exclude-dir="${_g##*/}" )
+done <<PRUNE_GLOBS
+$(precheck_prune_globs)
+PRUNE_GLOBS
+
 # Reads newline-separated paths on stdin, prints the one with the fewest path
 # segments (the shallowest, i.e. the real project copy rather than a nested one).
 pick_shallowest() { awk '{ n=gsub(/\//,"/"); print n"\t"$0 }' | sort -n | head -1 | cut -f2-; }
@@ -72,9 +110,21 @@ NONAPP_TARGET='(Watch|Extension|Widget|Intents|Clip|Notification|Share|Sticker|T
 # can land on a Watch app, an app extension, or a framework instead of the real app.
 # We score candidates by Swift-file count and deprioritize obvious non-app targets, so
 # they only win when nothing app-like exists.
+# Sets the globals IOS_DIR (and, when resolved via the project model, PM_INFO_PLIST)
+# directly rather than echoing a result — this function MUST be called without
+# command substitution (no `IOS_DIR="$(detect_ios_dir)"`) so its assignments run
+# in the caller's shell instead of a subshell, where they would be discarded.
 detect_ios_dir() {
   local d; d=$(cfg '.iosSourceDir')
-  [[ -n "$d" ]] && { echo "$d"; return; }
+  [[ -n "$d" ]] && { IOS_DIR="$d"; return; }
+  # Authoritative: parse the Xcode project model when a .pbxproj exists.
+  local pm; pm="$(pm_resolve . 2>/dev/null)"
+  if [[ -n "$pm" ]]; then
+    PM_INFO_PLIST="$(printf '%s' "$pm" | cut -f2)"
+    IOS_DIR="$(printf '%s' "$pm" | cut -f1)"
+    return
+  fi
+  # Fallback: the original grep heuristic (unchanged).
   local candidates plist entry
   candidates=$(
     find . "${PRUNE[@]}" -name Info.plist 2>/dev/null | while IFS= read -r plist; do dirname "$plist"; done
@@ -92,17 +142,18 @@ detect_ios_dir() {
       (( n > best_n )) && { best_n=$n; best="$dir"; }
     fi
   done <<< "$candidates"
-  [[ -n "$best" ]] && { echo "$best"; return; }
-  echo "$alt"
+  if [[ -n "$best" ]]; then IOS_DIR="$best"; else IOS_DIR="$alt"; fi
 }
 
-IOS_DIR="$(detect_ios_dir)"
+PM_INFO_PLIST=""
+IOS_DIR=""
+detect_ios_dir
 META_DIR="$(cfg '.metadataDir')";      [[ -z "$META_DIR" ]]   && META_DIR="$(detect_first -type d -name metadata -path '*fastlane*')"
 SCREEN_DIR="$(cfg '.screenshotsDir')"; [[ -z "$SCREEN_DIR" ]] && SCREEN_DIR="$(detect_first -type d -name screenshots -path '*fastlane*')"
 XCSTRINGS="$(cfg '.xcstringsPath')";   [[ -z "$XCSTRINGS" ]]  && XCSTRINGS="$(detect_first -name 'Localizable.xcstrings')"
 [[ -z "$XCSTRINGS" ]] && XCSTRINGS="$(detect_first -name '*.xcstrings')"
 PRIVACY_FILE="$(detect_first -name 'PrivacyInfo.xcprivacy')"
-INFO_PLIST="${IOS_DIR%/}/Info.plist"
+INFO_PLIST="${PM_INFO_PLIST:-${IOS_DIR%/}/Info.plist}"
 REVIEW_PREP="$(cfg '.reviewPrepNotes')"
 
 # Paywall / subscription views. A real app spreads its purchase UI across several files
@@ -150,6 +201,8 @@ SUB_KEY="$(cfg '.disclosureKeys.subscription' 'subscription_disclosure')"
 TRIAL_KEY="$(cfg '.disclosureKeys.trial' 'subscription_trial_disclosure')"
 CHECK_FAMILY="$(cfg_bool '.optionalChecks.familyControls')"
 
+if [[ "$FORMAT" == json ]]; then exec 4>&1 1>/dev/null; fi
+
 echo "PASS: layout — ios='${IOS_DIR:-?}' metadata='${META_DIR:-?}' xcstrings='${XCSTRINGS:-?}' locales=${#LOCALES[@]}"
 
 # ===================================================================
@@ -159,14 +212,15 @@ echo "PASS: layout — ios='${IOS_DIR:-?}' metadata='${META_DIR:-?}' xcstrings='
 # (v) "Account Sign-In" is a different rule — its account-deletion requirement is
 # checked separately in §38.
 # ===================================================================
+set_rule "privacy-manifest-parity"
 check_required_reason_api() {
   local cat="$1" pattern="$2" hits declared
   hits=$(grep -rEl "$pattern" "$IOS_DIR" --include="*.swift" 2>/dev/null | head -3)
   declared=$(grep -c "NSPrivacyAccessedAPICategory${cat}" "$PRIVACY_FILE" 2>/dev/null)
   if [[ -n "$hits" && "${declared:-0}" -eq 0 ]]; then
-    fail "5.1.1 Required Reason API — '$cat' used in code (e.g. $(echo "$hits" | head -1)) but not declared in PrivacyInfo.xcprivacy"
+    fail "5.1.1 Required Reason API — '$cat' used in code (e.g. $(echo "$hits" | head -1)) but not declared in PrivacyInfo.xcprivacy" "$PRIVACY_FILE"
   elif [[ -z "$hits" && "${declared:-0}" -gt 0 ]]; then
-    warn "5.1.1 PrivacyInfo — '$cat' declared but no code usage grepped (may be a false positive, verify manually)"
+    warn "5.1.1 PrivacyInfo — '$cat' declared but no code usage grepped (may be a false positive, verify manually)" "$PRIVACY_FILE"
   elif [[ -n "$hits" && "${declared:-0}" -gt 0 ]]; then
     pass "5.1.1 Required Reason API — '$cat' parity OK"
   fi
@@ -174,7 +228,7 @@ check_required_reason_api() {
 if [[ -z "$IOS_DIR" ]]; then
   warn "layout — could not auto-detect iOS source dir; set .iosSourceDir in $CONFIG"
 elif [[ -z "$PRIVACY_FILE" ]]; then
-  fail "5.1.1 Required Reason API — PrivacyInfo.xcprivacy not found (required since May 2024 for apps using Required Reason APIs)"
+  fail "5.1.1 Required Reason API — PrivacyInfo.xcprivacy not found (required since May 2024 for apps using Required Reason APIs)" "$INFO_PLIST"
 else
   check_required_reason_api "UserDefaults"   'UserDefaults|@AppStorage'
   check_required_reason_api "FileTimestamp"  'attributesOfItem|creationDate|modificationDate|\.fileCreationDate|\.fileModificationDate'
@@ -186,26 +240,52 @@ fi
 # ===================================================================
 # §2 — 5.1.1 NSUsageDescription cross-check (Info.plist)
 # ===================================================================
+set_rule "usage-description-crosscheck"
 if [[ ! -f "$INFO_PLIST" ]]; then
-  [[ -n "$IOS_DIR" ]] && warn "5.1.1 Info.plist not found at $INFO_PLIST (modern Xcode may auto-generate it; verify purpose strings in build settings)"
+  [[ -n "$IOS_DIR" ]] && warn "5.1.1 Info.plist not found at $INFO_PLIST (modern Xcode may auto-generate it; verify purpose strings in build settings)" "$INFO_PLIST"
 else
   awk '/NS[A-Za-z]+UsageDescription/{key=$0; getline; if($0 ~ /<string>[[:space:]]*<\/string>/) print "EMPTY:"key}' "$INFO_PLIST" | while read -r line; do
-    [[ -n "$line" ]] && fail "5.1.1 Purpose String — $line (empty usage description is rejected by App Review)"
+    [[ -n "$line" ]] && fail "5.1.1 Purpose String — $line (empty usage description is rejected by App Review)" "$INFO_PLIST"
   done
   for fw in \
     "FamilyControls|ManagedSettings|DeviceActivity:NSFamilyControlsUsageDescription" \
     "CoreLocation:NSLocationWhenInUseUsageDescription" \
-    "AVFoundation:NSCameraUsageDescription|NSMicrophoneUsageDescription" \
-    "Photos:NSPhotoLibraryUsageDescription" \
     "Contacts:NSContactsUsageDescription" \
     "HealthKit:NSHealthShareUsageDescription"; do
     framework="${fw%%:*}"; needed_key="${fw##*:}"
     if grep -rqE "import ($framework)|($framework)\." "$IOS_DIR" --include="*.swift" 2>/dev/null; then
       if ! grep -qE "$needed_key" "$INFO_PLIST" 2>/dev/null; then
-        fail "5.1.1 framework '${framework%%|*}' imported but Info.plist is missing '${needed_key%%|*}'"
+        fail "5.1.1 framework '${framework%%|*}' imported but Info.plist is missing '${needed_key%%|*}'" "$INFO_PLIST"
       fi
     fi
   done
+  # AVFoundation and Photos are gated on real capture/read APIs, not bare
+  # imports: an import only signals framework linkage, not camera/mic/library
+  # access (e.g. AVFoundation is commonly imported for playback-only use via
+  # AVAudioPlayer/AVPlayer, and Photos/PhotosUI's PhotosPicker/PHPickerViewController
+  # run out-of-process and need no Info.plist key at all).
+  # Camera: purpose string required only when a capture API is actually used.
+  if grep -rqE 'AVCaptureDevice|AVCaptureSession|UIImagePickerController' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
+    grep -qE 'NSCameraUsageDescription' "$INFO_PLIST" 2>/dev/null || \
+      fail "5.1.1 camera capture API used but Info.plist is missing 'NSCameraUsageDescription'" "$INFO_PLIST"
+  fi
+  # Microphone: required only for recording/capture, not playback. Matched
+  # separately from the camera check above: a bare AVCaptureDevice only
+  # implies microphone use when it is audio-typed (`.audio` device/media
+  # type), not for a video-only capture device.
+  if grep -rqE 'AVAudioRecorder|installTap\(|AVAudioEngine\(|AVAudioSession[^;]*\.(playAndRecord|record)|AVCaptureDevice[^;)]*\.audio|for:[[:space:]]*\.audio' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
+    grep -qE 'NSMicrophoneUsageDescription' "$INFO_PLIST" 2>/dev/null || \
+      fail "5.1.1 microphone/recording API used but Info.plist is missing 'NSMicrophoneUsageDescription'" "$INFO_PLIST"
+  fi
+  # Photo library READ: PhotosPicker/PHPicker need no key; only true read/fetch APIs do.
+  if grep -rqE 'PHAsset\b|PHFetchResult|PHImageManager|fetchAssets|PHAssetCollection' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
+    grep -qE 'NSPhotoLibraryUsageDescription' "$INFO_PLIST" 2>/dev/null || \
+      fail "5.1.1 Photos read API used but Info.plist is missing 'NSPhotoLibraryUsageDescription'" "$INFO_PLIST"
+  elif grep -rqE 'PHAssetCreationRequest|UIImageWriteToSavedPhotosAlbum|performChanges' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
+    # Add-only save: covered by the add-only key.
+    grep -qE 'NSPhotoLibraryAddUsageDescription' "$INFO_PLIST" 2>/dev/null || \
+      fail "5.1.1 Photos add-only API used but Info.plist is missing 'NSPhotoLibraryAddUsageDescription'" "$INFO_PLIST"
+  fi
 fi
 
 # ===================================================================
@@ -214,13 +294,14 @@ fi
 # Ad / attribution / IDFA SDK signal, shared with §16. The reverse of §3: §3 fires
 # when the ATT framework IS imported; §16 fires when a tracking SDK is present but
 # the ATT prompt is NOT. Computed once here so the two checks never contradict.
+set_rule "att-usage"
 tracking_sdk=$(grep -rlE 'advertisingIdentifier|ASIdentifierManager|GADMobileAds|GoogleMobileAds|AppLovinSDK|ALSdk|AppsFlyerLib|import Adjust|Adjust\.|FBAudienceNetwork|BranchSDK|IronSource' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
 att_used=$(grep -rlE 'AppTrackingTransparency|ATTrackingManager' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
 if [[ -n "$att_used" ]]; then
   if grep -q "NSUserTrackingUsageDescription" "$INFO_PLIST" 2>/dev/null; then
     pass "5.1.2 ATT — used + NSUserTrackingUsageDescription present"
   else
-    fail "5.1.2 ATT framework imported but NSUserTrackingUsageDescription missing in Info.plist ($att_used)"
+    fail "5.1.2 ATT framework imported but NSUserTrackingUsageDescription missing in Info.plist ($att_used)" "$INFO_PLIST"
   fi
 elif [[ -z "$tracking_sdk" ]]; then
   pass "5.1.2 ATT — not used (no tracking)"
@@ -231,12 +312,13 @@ fi
 # ===================================================================
 # §4 — 2.3.10 Other-platform / competitor mentions in metadata
 # ===================================================================
+set_rule "competitor-mentions"
 if [[ -d "$META_DIR" ]]; then
   banned_re='Android|Google[[:space:]]?Play|Play[[:space:]]?Store|Windows[[:space:]]?Phone|Samsung Galaxy|Huawei AppGallery|F-Droid'
   hits=$(grep -rEnI "$banned_re" "$META_DIR" 2>/dev/null | grep -v "^Binary file" | head -30)
   if [[ -n "$hits" ]]; then
     fail "2.3.10 Other-platform mention — banned reference in metadata:"
-    echo "$hits" | sed 's/^/      /'
+    detail "$hits"
   else
     pass "2.3.10 Other-platform mentions — metadata clean"
   fi
@@ -245,6 +327,7 @@ fi
 # ===================================================================
 # §5 — 2.3.1 Metadata character limits (Unicode codepoints, like ASC)
 # ===================================================================
+set_rule "metadata-char-limits"
 check_len() {
   local file="$1" limit="$2" label="$3" len
   [[ -f "$file" ]] || return
@@ -254,7 +337,7 @@ check_len() {
     len=$(wc -m < "$file" | tr -d ' ')
   fi
   [[ -z "$len" ]] && return
-  (( len > limit )) && fail "2.3.1 $label — $file ${len} chars (limit ${limit})"
+  (( len > limit )) && fail "2.3.1 $label — $file ${len} chars (limit ${limit})" "$file"
 }
 for loc in "${LOCALES[@]+"${LOCALES[@]}"}"; do
   d="$META_DIR/$loc"; [[ -d "$d" ]] || continue
@@ -268,6 +351,7 @@ done
 # ===================================================================
 # §6 — 2.3.7 Localized metadata parity across all detected locales
 # ===================================================================
+set_rule "locale-metadata-parity"
 if (( ${#LOCALES[@]} > 0 )); then
   expected_files=(name.txt subtitle.txt description.txt keywords.txt)
   for loc in "${LOCALES[@]+"${LOCALES[@]}"}"; do
@@ -294,6 +378,7 @@ fi
 # ===================================================================
 # §7 — 2.3.3 Screenshots per locale
 # ===================================================================
+set_rule "screenshots-per-locale"
 if [[ -n "$SCREEN_DIR" && -d "$SCREEN_DIR" ]]; then
   for loc in "${LOCALES[@]+"${LOCALES[@]}"}"; do
     d="$SCREEN_DIR/$loc"
@@ -307,20 +392,24 @@ if [[ -n "$SCREEN_DIR" && -d "$SCREEN_DIR" ]]; then
   done
   pass "2.3.3 Screenshots — checked ${#LOCALES[@]} locales under $SCREEN_DIR"
 else
-  warn "2.3.3 Screenshots — screenshots dir not found (set .screenshotsDir if you manage them in-repo)"
+  pass "2.3.3 Screenshots — no in-repo screenshots dir; assumed managed in App Store Connect (set .screenshotsDir to check in-repo)"
 fi
 
 # ===================================================================
 # In-app purchase gate — only run 3.1.2 checks if IAP signals exist
 # ===================================================================
 iap_detected=""
-grep -rqE 'import StoreKit|RevenueCat|Purchases\.|Product\(for:|AppStore\.|SKProduct|StoreKit2' "$IOS_DIR" --include="*.swift" 2>/dev/null && iap_detected=1
+grep -rqE 'SKPaymentQueue|SKProduct|SKMutablePayment|Product\.products|Product\(for:|Product\(id:|\.purchase\(|Transaction\.currentEntitlements|Transaction\.updates|RevenueCat|Purchases\.(shared|configure|logIn|getProducts)|Adapty|Glassfy|import Qonversion' "$IOS_DIR" --include="*.swift" 2>/dev/null && iap_detected=1
 [[ -n "$SUB_VIEW" ]] && iap_detected=1
 
 if [[ -z "$iap_detected" ]]; then
+  # Not one of the 41 catalog sections — clear the rule_id so this PASS doesn't
+  # inherit §7's "screenshots-per-locale" slug in the JSON output.
+  set_rule ""
   pass "3.1.2 IAP — no in-app purchase / subscription signals detected, skipping paywall checks"
 else
   # ---- §8 3.1.2 Trial disclosure -------------------------------------------------
+  set_rule "trial-disclosure"
   trial_re='free[[:space:]]?trial|trial[[:space:]]?period|ücretsiz[[:space:]]?dene|kostenlos[[:space:]]?test|essai[[:space:]]?gratuit|prueba[[:space:]]?grat|無料.*トライアル|무료[[:space:]]?체험'
   if [[ -n "$XCSTRINGS" ]] && grep -EqI "$trial_re" "$XCSTRINGS" 2>/dev/null; then
     if grep -q "$TRIAL_KEY" "$XCSTRINGS" 2>/dev/null; then
@@ -333,6 +422,7 @@ else
   fi
 
   # ---- §9 3.1.2 Auto-renew subscription disclosure -------------------------------
+  set_rule "autorenew-disclosure"
   if [[ -n "$XCSTRINGS" ]]; then
     if have_jq && jq -e ".strings | has(\"$SUB_KEY\")" "$XCSTRINGS" >/dev/null 2>&1; then
       pass "3.1.2 subscription disclosure key '$SUB_KEY' present"
@@ -353,6 +443,7 @@ else
   # Grep across the whole paywall cluster: a link present in ANY paywall view satisfies
   # the requirement; only its absence from ALL of them is a FAIL. SUB_VIEW names the
   # representative file in messages.
+  set_rule "subscription-links-restore"
   if (( ${#PAYWALL_FILES[@]} > 0 )); then
     if grep -qE 'restore|restorePurchases' "${PAYWALL_FILES[@]}"; then
       pass "3.1.2 Restore Purchases — present in $(basename "$SUB_VIEW")"
@@ -377,11 +468,15 @@ fi
 # ===================================================================
 # §11 — 2.5.1 Private / banned API
 # ===================================================================
+set_rule "private-api"
 banned_api='UIWebView|setSelectionIndicatorImage|_UIBackdropView|NSURLConnection[^a-zA-Z]|UIAlertView[^Q]|UIActionSheet[^Q]'
 banned_hits=$(grep -rEnI "$banned_api" "$IOS_DIR" --include="*.swift" --include="*.m" --include="*.h" 2>/dev/null | head -5)
 if [[ -n "$banned_hits" ]]; then
-  fail "2.5.1 Private/Deprecated API:"
-  echo "$banned_hits" | sed 's/^/      /'
+  pa_first="$(printf '%s\n' "$banned_hits" | head -1)"   # "path:line:match"
+  pa_file="${pa_first%%:*}"
+  pa_rest="${pa_first#*:}"; pa_line="${pa_rest%%:*}"
+  fail "2.5.1 Private/Deprecated API:" "$pa_file" "$pa_line"
+  detail "$banned_hits"
 else
   pass "2.5.1 Private API — clean"
 fi
@@ -389,7 +484,8 @@ fi
 # ===================================================================
 # §12 — 4.2 Minimum functionality — navigation hubs
 # ===================================================================
-tab_count=$(grep -rcE 'TabView|NavigationStack|NavigationSplitView' "$IOS_DIR" --include="*.swift" 2>/dev/null | awk -F: '{sum+=$2} END {print sum+0}')
+set_rule "min-functionality-nav"
+tab_count=$(grep -rcE 'TabView|NavigationStack|NavigationSplitView|NavigationView|UITabBarController|UINavigationController|createBottomTabNavigator|createStackNavigator|createNativeStackNavigator' . "${GREP_PRUNE[@]}" --include='*.swift' --include='*.m' --include='*.js' --include='*.jsx' --include='*.ts' --include='*.tsx' 2>/dev/null | awk -F: '{sum+=$2} END {print sum+0}')
 if (( tab_count < 1 )); then
   warn "4.2 Minimum functionality — no TabView/NavigationStack found (heuristic, may be a false positive)"
 else
@@ -399,6 +495,7 @@ fi
 # ===================================================================
 # §13 — 5.1.5 Screen Time / sensitive-API justification (optional, opt-in)
 # ===================================================================
+set_rule "screentime-justification"
 if [[ "$CHECK_FAMILY" == "true" ]] && grep -q "NSFamilyControlsUsageDescription" "$INFO_PLIST" 2>/dev/null; then
   if [[ -n "$REVIEW_PREP" && -f "$REVIEW_PREP" ]] && grep -qiE 'family|screen[[:space:]]?time' "$REVIEW_PREP" 2>/dev/null; then
     pass "5.1.5 Screen Time API — reviewer-prep justification note present"
@@ -410,6 +507,7 @@ fi
 # ===================================================================
 # §14 — 4.8 Sign in with Apple parity (only when a third-party social login is used)
 # ===================================================================
+set_rule "siwa-parity"
 if [[ -n "$IOS_DIR" ]]; then
   social_login=$(grep -rlE 'GIDSignIn|import GoogleSignIn|FBSDKLoginKit|FBSDKLoginManager|FacebookLogin|import Auth0|LineSDK|VKSdkAuthorization' "$IOS_DIR" --include='*.swift' 2>/dev/null | head -1)
   if [[ -n "$social_login" ]]; then
@@ -424,6 +522,7 @@ fi
 # ===================================================================
 # §15 — 3.1.1(a) External purchase link (StoreKit External Purchase)
 # ===================================================================
+set_rule "external-purchase-link"
 ext_purchase=""
 grep -rqE 'ExternalPurchase|ExternalPurchaseLink|ExternalPurchaseCustomLink' "${IOS_DIR:-.}" --include='*.swift' 2>/dev/null && ext_purchase=1
 grep -rqE 'external-purchase' "${IOS_DIR:-.}" --include='*.entitlements' 2>/dev/null && ext_purchase=1
@@ -437,6 +536,7 @@ fi
 # §3 catches "ATT framework imported but no usage string". This catches the more
 # common rejection: shipping an ad / attribution SDK (or touching the IDFA) without
 # ever presenting the ATT prompt. `tracking_sdk` and `att_used` are computed in §3.
+set_rule "tracking-sdk-no-att"
 if [[ -n "$tracking_sdk" ]]; then
   att_present=""
   [[ -n "$att_used" ]] && att_present=1
@@ -455,11 +555,12 @@ fi
 # submission. Setting it (true/false) removes that friction. Only checked when an
 # Info.plist exists; a modern app may auto-generate it, in which case the key lives
 # in build settings, so we stay silent rather than nag.
+set_rule "export-compliance"
 if [[ -f "$INFO_PLIST" ]]; then
   if grep -q "ITSAppUsesNonExemptEncryption" "$INFO_PLIST" 2>/dev/null; then
     pass "export-compliance — ITSAppUsesNonExemptEncryption set in Info.plist"
   else
-    warn "export-compliance — Info.plist has no ITSAppUsesNonExemptEncryption; set it (true/false) to skip the App Store Connect encryption-export prompt every submission"
+    warn "export-compliance — Info.plist has no ITSAppUsesNonExemptEncryption; set it (true/false) to skip the App Store Connect encryption-export prompt every submission" "$INFO_PLIST"
   fi
 fi
 
@@ -470,6 +571,7 @@ fi
 # support_url.txt / privacy_url.txt / marketing_url.txt. Apple requires a working
 # support URL, and a privacy policy URL for apps with accounts or IAP. Flag when
 # they are absent across every locale, or contain an obvious placeholder.
+set_rule "support-privacy-url"
 if [[ -d "$META_DIR" ]]; then
   support_found="" privacy_found=""
   for loc in "${LOCALES[@]+"${LOCALES[@]}"}"; do
@@ -482,8 +584,9 @@ if [[ -d "$META_DIR" ]]; then
   fi
   url_ph=$(grep -rEnI 'example\.com|localhost|\bTODO\b|\bchangeme\b' "$META_DIR" --include='*_url.txt' 2>/dev/null | grep -v "^Binary file" | head -10)
   if [[ -n "$url_ph" ]]; then
-    warn "2.3 Metadata URL — placeholder URL in fastlane metadata (replace before submitting):"
-    echo "$url_ph" | sed 's/^/      /'
+    url_ph_file="$(printf '%s\n' "$url_ph" | head -1 | cut -d: -f1)"
+    warn "2.3 Metadata URL — placeholder URL in fastlane metadata (replace before submitting):" "$url_ph_file"
+    detail "$url_ph"
   fi
 fi
 
@@ -495,7 +598,8 @@ fi
 # domains, the privacy manifest and the App Privacy nutrition labels are probably
 # incomplete. Soft "verify" wording (a crash-only Sentry may genuinely collect
 # nothing), so WARN, never FAIL.
-analytics_sdk=$(grep -rlE 'FirebaseAnalytics|import Firebase|Amplitude|Mixpanel|import Sentry|Segment|Bugsnag|AppCenterAnalytics|Datadog' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
+set_rule "analytics-privacyinfo-mismatch"
+analytics_sdk=$(grep -rlE 'FirebaseAnalytics|import Firebase|import Amplitude|Amplitude\(|import Mixpanel|Mixpanel\.|import Sentry|SentrySDK|import Segment|SEGAnalytics|Analytics\.shared\(|import Bugsnag|Bugsnag\.|AppCenterAnalytics|import Datadog|DatadogCore' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
 if [[ -n "$analytics_sdk" ]]; then
   declared_data=""
   if [[ -n "$PRIVACY_FILE" && -f "$PRIVACY_FILE" ]]; then
@@ -507,7 +611,7 @@ if [[ -n "$analytics_sdk" ]]; then
   if [[ -n "$declared_data" ]]; then
     pass "5.1.1 Privacy manifest — analytics SDK present and PrivacyInfo declares collected data"
   else
-    warn "5.1.1 Privacy manifest — analytics SDK detected (e.g. $(basename "$analytics_sdk")) but PrivacyInfo declares no collected data types or tracking domains; verify your privacy manifest and App Privacy nutrition labels"
+    warn "5.1.1 Privacy manifest — analytics SDK detected (e.g. $(basename "$analytics_sdk")) but PrivacyInfo declares no collected data types or tracking domains; verify your privacy manifest and App Privacy nutrition labels" "$PRIVACY_FILE"
   fi
 fi
 
@@ -518,12 +622,14 @@ fi
 # get rejected under 2.1 and look unfinished. Conservative, specific patterns to
 # avoid flagging legitimate words. Overlaps the Phase 2 precheck "No placeholder
 # text" rule, but this one is local and runs before any network call.
+set_rule "placeholder-metadata"
 if [[ -d "$META_DIR" ]]; then
   ph_re='lorem ipsum|Lorem ipsum|\bTODO\b|\bFIXME\b|example\.com|placeholder|insert .* here|\bchangeme\b'
   ph_hits=$(grep -rEnI "$ph_re" "$META_DIR" 2>/dev/null | grep -v "^Binary file" | head -20)
   if [[ -n "$ph_hits" ]]; then
-    warn "2.1 Metadata content — placeholder/dummy text in store metadata (looks unfinished; rejected under 2.1):"
-    echo "$ph_hits" | sed 's/^/      /'
+    ph_file="$(printf '%s\n' "$ph_hits" | head -1 | cut -d: -f1)"
+    warn "2.1 Metadata content — placeholder/dummy text in store metadata (looks unfinished; rejected under 2.1):" "$ph_file"
+    detail "$ph_hits"
   fi
 fi
 
@@ -534,6 +640,7 @@ fi
 # third-party payment SDK (Stripe, Braintree, PayPal, …) is legitimate for
 # PHYSICAL goods/services but a frequent rejection when used to sell digital
 # content. We can't tell digital from physical statically, so this is advisory.
+set_rule "thirdparty-payment-sdk"
 if [[ -n "$IOS_DIR" ]]; then
   payment_sdk=$(grep -rlE 'import Stripe|StripePaymentSheet|StripeApplePay|import Braintree|BTPaymentFlow|import PayPal|PayPalCheckout|PayPalNativeCheckout|import Square|SquareInAppPayments|import Adyen|AdyenComponents|RazorpaySDK|import Paddle' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   if [[ -n "$payment_sdk" ]]; then
@@ -547,6 +654,7 @@ fi
 # Apps with UGC must provide: a content filter, a report mechanism, the ability
 # to block abusive users, and published contact info. We detect a UGC signal and
 # warn when no report/block/moderation affordance is found anywhere in the source.
+set_rule "ugc-no-moderation"
 if [[ -n "$IOS_DIR" ]]; then
   ugc_signal=$(grep -rlE 'userGeneratedContent|\bUGC\b|StreamChat|MessageKit|SendbirdSDK|PubNub|postComment|submitComment|createPost|publishPost|uploadUserPhoto|uploadVideo' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   if [[ -n "$ugc_signal" ]]; then
@@ -563,12 +671,13 @@ fi
 # ===================================================================
 # NSAllowsArbitraryLoads=true turns off ATS for the whole app, weakening
 # data-in-transit security and inviting a 1.6 / data-security question at review.
+set_rule "ats-arbitrary-loads"
 if [[ -f "$INFO_PLIST" ]]; then
   # Anchor to the exact key: `NSAllowsArbitraryLoads</key>` (followed by `<`), so the
   # narrower scoped exceptions NSAllowsArbitraryLoadsInWebContent / ...ForMedia — which
   # do NOT disable ATS app-wide and are the recommended alternative — don't false-fire.
   if awk '/NSAllowsArbitraryLoads</{getline; if ($0 ~ /<true/) print "ON"}' "$INFO_PLIST" 2>/dev/null | grep -q ON; then
-    warn "1.6 App Transport Security — NSAllowsArbitraryLoads=true in Info.plist disables ATS app-wide; prefer per-domain exceptions, and expect a data-security justification request at review (1.6)"
+    warn "1.6 App Transport Security — NSAllowsArbitraryLoads=true in Info.plist disables ATS app-wide; prefer per-domain exceptions, and expect a data-security justification request at review (1.6)" "$INFO_PLIST"
   fi
 fi
 
@@ -580,6 +689,7 @@ fi
 # Pay recurring API (PKRecurringPaymentRequest) so it does NOT conflate StoreKit
 # auto-renew copy or a one-time PassKit payment with recurring Apple Pay. We don't
 # try to detect the disclosure text (too noisy) — we flag it for manual verify.
+set_rule "applepay-recurring-disclosure"
 if [[ -n "$IOS_DIR" ]] && grep -rqE 'PKRecurringPaymentRequest' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
   warn "4.9 Apple Pay — recurring Apple Pay (PKRecurringPaymentRequest) detected; verify you disclose the renewal term, what's provided, the charges, and how to cancel before purchase (4.9)"
 fi
@@ -589,6 +699,7 @@ fi
 # ===================================================================
 # Apple disallows custom review prompts and direct write-review links — apps must
 # use the system SKStoreReviewController / requestReview API.
+set_rule "custom-review-prompt"
 if [[ -n "$IOS_DIR" ]]; then
   review_link=$(grep -rlE 'write-review|action=write-review|itms-apps[^"]*review' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   if [[ -n "$review_link" ]]; then
@@ -605,12 +716,14 @@ fi
 # ===================================================================
 # Marketing the app for things iOS apps can't actually do (virus/malware
 # scanners, fake speed boosters) is a 2.3.1 removal vector.
+set_rule "misleading-marketing"
 if [[ -d "$META_DIR" ]]; then
   mislead_re='virus scan|virus scanner|antivirus|anti-virus|malware (scan|remov|clean)|spyware remov|clean your (iphone|device)|speed booster|boost.*(speed|ram)|free money|guaranteed.*(win|prize)'
   mislead_hits=$(grep -rEniI "$mislead_re" "$META_DIR" 2>/dev/null | grep -v "^Binary file" | head -10)
   if [[ -n "$mislead_hits" ]]; then
-    warn "2.3.1 Misleading marketing — claims that often violate 2.3.1 (e.g. iOS virus/malware scanners, fake speed boosters) in metadata; verify the app truly delivers them or remove the claim:"
-    echo "$mislead_hits" | sed 's/^/      /'
+    mislead_file="$(printf '%s\n' "$mislead_hits" | head -1 | cut -d: -f1)"
+    warn "2.3.1 Misleading marketing — claims that often violate 2.3.1 (e.g. iOS virus/malware scanners, fake speed boosters) in metadata; verify the app truly delivers them or remove the claim:" "$mislead_file"
+    detail "$mislead_hits"
   fi
 fi
 
@@ -619,6 +732,7 @@ fi
 # ===================================================================
 # Terms implying a child audience in name/subtitle/keywords/description are
 # reserved for the Kids Category (2.3.8 / 5.1.4).
+set_rule "kids-wording"
 if [[ -d "$META_DIR" ]]; then
   kids_re='for kids|for children|for your (kid|child)|kids[[:space:]]?app|für kinder|para niños|pour enfants'
   kids_hits=$(grep -rEniI "$kids_re" "$META_DIR" 2>/dev/null | grep -v "^Binary file" | head -10)
@@ -626,8 +740,9 @@ if [[ -d "$META_DIR" ]]; then
   # more specific Kids finding for the same wording signal — don't double-count it here
   # (one root signal must not cost two WARNs against the 5-WARN YELLOW threshold).
   if [[ -n "$kids_hits" && -z "${tracking_sdk:-}" && -z "${analytics_sdk:-}" ]]; then
-    warn "2.3.8 'For Kids/Children' wording — terms implying a child audience are reserved for the Kids Category (2.3.8); if not enrolled, remove them from name/subtitle/keywords/description:"
-    echo "$kids_hits" | sed 's/^/      /'
+    kids_file="$(printf '%s\n' "$kids_hits" | head -1 | cut -d: -f1)"
+    warn "2.3.8 'For Kids/Children' wording — terms implying a child audience are reserved for the Kids Category (2.3.8); if not enrolled, remove them from name/subtitle/keywords/description:" "$kids_file"
+    detail "$kids_hits"
   fi
 fi
 
@@ -636,6 +751,7 @@ fi
 # ===================================================================
 # Keyboards must stay functional without full network access / "full access",
 # and may only collect data to enhance the keyboard.
+set_rule "keyboard-full-access"
 kb_plist=$(grep -rlE 'com\.apple\.keyboard-service' --include='Info.plist' "${GREP_PRUNE[@]}" . 2>/dev/null | pick_shallowest)
 if [[ -n "$kb_plist" ]]; then
   if grep -A1 'RequestsOpenAccess' "$kb_plist" 2>/dev/null | grep -q '<true'; then
@@ -650,6 +766,7 @@ fi
 # ===================================================================
 # Personal health information must not be stored in iCloud, and HealthKit data
 # may not be used for advertising/marketing.
+set_rule "health-icloud-sync"
 if [[ -n "$IOS_DIR" ]] && grep -rqE 'import HealthKit|HKHealthStore' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
   if grep -rqE 'import CloudKit|CKRecord|CKContainer|NSUbiquitousKeyValueStore|NSUbiquitousContainer' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
     warn "5.1.3 Health data — HealthKit and iCloud/CloudKit are both used; personal health information must not be stored in iCloud (5.1.3). Verify HealthKit data is not synced to iCloud."
@@ -663,6 +780,7 @@ fi
 # ===================================================================
 # VPN apps must be offered by an organization account, declare data collection
 # on-screen before use, and may not sell/share data.
+set_rule "vpn-networkextension"
 if [[ -n "$IOS_DIR" ]]; then
   vpn_use=$(grep -rlE 'NEVPNManager|NETunnelProviderManager|NEPacketTunnelProvider|NEVPNProtocol' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   if [[ -n "$vpn_use" ]]; then
@@ -677,6 +795,7 @@ fi
 # or notes). We fire only on a credential-login signal (a password field or a
 # Login/SignIn view), then look for demo creds in fastlane review_information or
 # the reviewer-prep notes. Social-only logins are not gated here (too noisy).
+set_rule "demo-account"
 if [[ -n "$IOS_DIR" ]]; then
   auth_signal=$(grep -rlE 'SecureField' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   [[ -z "$auth_signal" ]] && auth_signal=$(find "$IOS_DIR" "${PRUNE[@]}" \( -name '*Login*View*.swift' -o -name '*SignIn*View*.swift' \) 2>/dev/null | head -1)
@@ -703,6 +822,7 @@ fi
 # Apps must be self-contained; native hot-patching frameworks (JSPatch, Rollout,
 # DynamicCocoa) download code that changes features and are a removal vector.
 # JS-bundle OTA for React Native (CodePush) is allowed, so we do NOT flag it.
+set_rule "executable-code-download"
 if [[ -n "$IOS_DIR" ]]; then
   hotcode=$(grep -rlE 'import JSPatch|JSPatch\.|[Jj][Ss][Pp]atch|import Rollout|Rollout\.|rollout\.io|DynamicCocoa|import SwiftPatch' "$IOS_DIR" --include="*.swift" --include="*.m" --include="*.h" 2>/dev/null | head -1)
   if [[ -n "$hotcode" ]]; then
@@ -716,6 +836,7 @@ fi
 # Declare only the UIBackgroundModes the app actually uses; a mode declared with
 # no matching API is a frequent rejection. We parse the array and check each
 # declared mode against its framework/API in Swift.
+set_rule "background-modes-unused"
 if [[ -f "$INFO_PLIST" && -n "$IOS_DIR" ]]; then
   modes=$(awk '/<key>UIBackgroundModes<\/key>/{f=1;next} f&&/<\/array>/{f=0} f&&/<string>/{gsub(/.*<string>|<\/string>.*/,""); print}' "$INFO_PLIST" 2>/dev/null)
   if [[ -n "$modes" ]]; then
@@ -733,7 +854,7 @@ if [[ -f "$INFO_PLIST" && -n "$IOS_DIR" ]]; then
       esac
     done <<< "$modes"
     if [[ -n "$unused" ]]; then
-      warn "2.5.4 Background modes —$unused declared in UIBackgroundModes but no matching API usage found in Swift; declare only the background modes the app actually uses (2.5.4)"
+      warn "2.5.4 Background modes —$unused declared in UIBackgroundModes but no matching API usage found in Swift; declare only the background modes the app actually uses (2.5.4)" "$INFO_PLIST"
     else
       pass "2.5.4 Background modes — declared modes have matching API usage"
     fi
@@ -743,6 +864,7 @@ fi
 # ===================================================================
 # §34 — 3.1.5(a) Cryptocurrency wallet / exchange / mining
 # ===================================================================
+set_rule "crypto-wallet-mining"
 if [[ -n "$IOS_DIR" ]]; then
   crypto_sdk=$(grep -rlE 'import Web3|web3swift|Web3Swift|WalletConnect|TrustWalletCore|CoinbaseWalletSDK|SolanaSwift|CryptoMining|coinhive|MoneroMiner' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   if [[ -n "$crypto_sdk" ]]; then
@@ -756,6 +878,7 @@ fi
 # A thin WKWebView wrapper around a website is rejected under minimum
 # functionality. Heuristic: WKWebView present in a project with very few Swift
 # files. WARN (verify) — this is the most false-positive-prone of the batch.
+set_rule "webview-wrapper"
 if [[ -n "$IOS_DIR" ]]; then
   if grep -rqE 'WKWebView' "$IOS_DIR" --include="*.swift" 2>/dev/null; then
     swift_n=$(find "$IOS_DIR" "${PRUNE[@]}" -name '*.swift' 2>/dev/null | wc -l | tr -d ' ')
@@ -768,6 +891,7 @@ fi
 # ===================================================================
 # §36 — 4.2.7 Remote desktop / host-mirroring
 # ===================================================================
+set_rule "remote-desktop"
 if [[ -n "$IOS_DIR" ]]; then
   remote_desktop=$(grep -rlE 'import libvncclient|LibVNC|VNCClient|RDPSession|RDPKit|RemoteDesktopClient|import FreeRDP|JumpDesktop' "$IOS_DIR" --include="*.swift" --include="*.m" 2>/dev/null | head -1)
   if [[ -n "$remote_desktop" ]]; then
@@ -778,6 +902,7 @@ fi
 # ===================================================================
 # §37 — 4.4.2 Safari extension / content blocker
 # ===================================================================
+set_rule "safari-extension"
 safari_ext=$(grep -rlE 'com\.apple\.Safari\.(content-blocker|web-extension|extension)' --include='Info.plist' "${GREP_PRUNE[@]}" . 2>/dev/null | pick_shallowest)
 if [[ -n "$safari_ext" ]]; then
   warn "4.4.2 Safari extension — a Safari content-blocker / web extension was detected ($(basename "$safari_ext")); it must use the extension APIs as intended, do only what it declares, and not include hidden analytics/ads or track without consent (4.4.2). Verify."
@@ -789,6 +914,7 @@ fi
 # Apple 5.1.1(v): apps that support account creation must also let users delete
 # their account from within the app. Detect account-creation signals, then look
 # for an in-app deletion path. Deletion via a web page is missed → WARN, not FAIL.
+set_rule "account-no-delete"
 if [[ -n "$IOS_DIR" ]]; then
   signup=$(grep -rlE 'createUser|signUp|signup|createAccount|registerUser|registerNewUser|Auth\.auth\(\)\.createUser' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   if [[ -n "$signup" ]]; then
@@ -807,6 +933,7 @@ fi
 # must include a parental gate. We fire when the metadata targets a child
 # audience AND an ad/analytics SDK is linked. tracking_sdk/analytics_sdk come
 # from §3/§19.
+set_rule "kids-ads-analytics"
 if [[ -d "$META_DIR" && -n "$IOS_DIR" ]]; then
   if grep -rqEiI 'for kids|for children|kids[[:space:]]?app|für kinder|para niños|pour enfants' "$META_DIR" 2>/dev/null; then
     if [[ -n "$tracking_sdk" || -n "$analytics_sdk" ]]; then
@@ -818,18 +945,23 @@ fi
 # ===================================================================
 # §40 — 5.3.4 Real-money gambling
 # ===================================================================
+set_rule "realmoney-gambling"
 if [[ -d "$META_DIR" ]]; then
   gamble_re='real[ -]?money|gambling|casino|sportsbook|sports[ -]?betting|place[ -].*bets|wager(ing)?|roulette.*real'
   gamble_hits=$(grep -rEniI "$gamble_re" "$META_DIR" 2>/dev/null | grep -v "^Binary file" | head -10)
   if [[ -n "$gamble_hits" ]]; then
-    warn "5.3.4 Gambling — real-money gaming language in metadata; real-money gambling/lotteries need the proper licenses, must be geo-restricted to permitted regions, and must be free on the App Store (5.3.4):"
-    echo "$gamble_hits" | sed 's/^/      /'
+    gamble_first="$(printf '%s\n' "$gamble_hits" | head -1)"   # "path:line:match"
+    gamble_file="${gamble_first%%:*}"
+    gamble_rest="${gamble_first#*:}"; gamble_line="${gamble_rest%%:*}"
+    warn "5.3.4 Gambling — real-money gaming language in metadata; real-money gambling/lotteries need the proper licenses, must be geo-restricted to permitted regions, and must be free on the App Store (5.3.4):" "$gamble_file" "$gamble_line"
+    detail "$gamble_hits"
   fi
 fi
 
 # ===================================================================
 # §41 — 5.5 Mobile Device Management
 # ===================================================================
+set_rule "mdm"
 if [[ -n "$IOS_DIR" ]]; then
   mdm_sig=$(grep -rlE 'import DeviceManagement|MDMConfiguration|ManagedAppConfiguration|com\.apple\.mdm' "$IOS_DIR" --include="*.swift" 2>/dev/null | head -1)
   [[ -z "$mdm_sig" ]] && mdm_sig=$(grep -rlE 'com\.apple\.configuration\.managed' --include='*.plist' "${GREP_PRUNE[@]}" . 2>/dev/null | pick_shallowest)
@@ -839,3 +971,7 @@ if [[ -n "$IOS_DIR" ]]; then
 fi
 
 echo "---END-OF-SCAN---"
+if [[ "$FORMAT" == text && "${_SUPPRESSED_COUNT:-0}" -gt 0 ]]; then
+  printf '(%s finding(s) suppressed via .precheck-ignore)\n' "$_SUPPRESSED_COUNT"
+fi
+if [[ "$FORMAT" == json ]]; then exec 1>&4 4>&-; render_json; fi

package/skills/appstore-precheck/scripts/suppress.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# suppress.sh — .precheck-ignore + inline suppression for scan.sh.
+# Sourced by scan.sh AFTER findings.sh (needs rule_slug). Bash 3.2: no associative arrays.
+
+_SUPP_RULES=""        # rule-ids suppressed everywhere, one per line
+_SUPP_RULE_PATH=""    # "rule<TAB>glob" per line
+_SUPP_PATHS=""        # path globs excluded from scanning, one per line (trailing / stripped)
+_SUPP_REASON=""       # set by is_suppressed on a hit
+
+# _is_catalog_rule <token> -> 0 if token is a known rule slug.
+_is_catalog_rule() {
+  local n s
+  n=1
+  while [[ $n -le 41 ]]; do
+    s="$(rule_slug "$n")"
+    [[ "$s" == "$1" ]] && return 0
+    n=$((n + 1))
+  done
+  return 1
+}
+
+# load_precheck_ignore [root]
+load_precheck_ignore() {
+  local root="${1:-.}" file line t1 t2
+  file="$root/.precheck-ignore"
+  _SUPP_RULES=""; _SUPP_RULE_PATH=""; _SUPP_PATHS=""
+  [[ -f "$file" ]] || return 0
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    line="${line%%#*}"                                   # strip trailing comment
+    line="$(printf '%s' "$line" | awk '{$1=$1;print}')"  # trim ends, collapse ws
+    [[ -z "$line" ]] && continue
+    t1="$(printf '%s' "$line" | awk '{print $1}')"
+    t2="$(printf '%s' "$line" | awk '{print $2}')"
+    if _is_catalog_rule "$t1"; then
+      if [[ -n "$t2" ]]; then
+        _SUPP_RULE_PATH="${_SUPP_RULE_PATH}${t1}	${t2%/}
+"
+      else
+        _SUPP_RULES="${_SUPP_RULES}${t1}
+"
+      fi
+    elif [[ "$t1" == */* || "$t1" == *.* || "$t1" == *"*"* ]]; then
+      _SUPP_PATHS="${_SUPP_PATHS}${t1%/}
+"
+    else
+      printf 'suppress: unknown rule-id %s in .precheck-ignore (ignored)\n' "$t1" >&2
+    fi
+  done < "$file"
+}
+
+# precheck_prune_globs -> one path glob per line (for scan.sh PRUNE/GREP_PRUNE).
+precheck_prune_globs() { printf '%s' "$_SUPP_PATHS"; }
+
+# _inline_marker <line-text> <rule> -> 0 if a real comment marker suppresses <rule>.
+_inline_marker() {
+  local text="$1" rule="$2" spec
+  printf '%s' "$text" | grep -qE '(//|#|<!--)[[:space:]]*precheck:ignore' || return 1
+  spec="$(printf '%s' "$text" | sed -nE 's/.*precheck:ignore[[:space:]]*([a-z][a-z0-9-]*).*/\1/p')"
+  [[ -z "$spec" ]] && return 0        # bare marker suppresses any rule
+  [[ "$spec" == "$rule" ]]            # scoped marker must match
+}
+
+# is_suppressed <rule> <file> <line> -> 0 if suppressed (+ _SUPP_REASON), else 1.
+is_suppressed() {
+  local rule="$1" file="${2:-}" line="${3:-}" r g target
+  _SUPP_REASON=""
+  if [[ -n "$rule" ]] && printf '%s\n' "$_SUPP_RULES" | grep -qxF "$rule"; then
+    _SUPP_REASON="rule:$rule"; return 0
+  fi
+  if [[ -n "$rule" && -n "$file" && -n "$_SUPP_RULE_PATH" ]]; then
+    while IFS='	' read -r r g; do
+      [[ -z "$r" ]] && continue
+      if [[ "$r" == "$rule" ]]; then
+        # shellcheck disable=SC2254
+        case "$file" in
+          $g|*/$g|$g/*|*/$g/*) _SUPP_REASON="rule-path:$rule:$g"; return 0 ;;
+        esac
+      fi
+    done <<INNER
+$_SUPP_RULE_PATH
+INNER
+  fi
+  if [[ -n "$file" && -n "$line" && -f "$file" ]]; then
+    target="$(sed -n "${line}p" "$file" 2>/dev/null)"
+    if _inline_marker "$target" "$rule"; then _SUPP_REASON="inline"; return 0; fi
+    if [[ "$line" -gt 1 ]]; then
+      target="$(sed -n "$((line - 1))p" "$file" 2>/dev/null)"
+      if _inline_marker "$target" "$rule"; then _SUPP_REASON="inline-above"; return 0; fi
+    fi
+  fi
+  return 1
+}