appstore-precheck 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project are documented here. Versioning follows
 
 ## [Unreleased]
 
+## [1.10.0] - 2026-07-02
+
+Roadmap #4: **SARIF output + opt-in GitHub PR annotations** — read-only, no auto-fix.
+
+The scanner can now emit its deterministic findings as **SARIF 2.1.0**
+(`scan.sh --format sarif`, also `npx appstore-precheck --format sarif`), built from
+the same structured findings as `--format json` with pure `jq` (no new dependency).
+`results[]` contains the non-suppressed FAIL and WARN findings (FAIL → `error`,
+WARN → `warning`); PASS and suppressed findings are excluded; findings that carry a
+`file`/`line` become SARIF `physicalLocation`s so GitHub can anchor annotations. Only
+the deterministic scan findings are included — the agent-mode Pierre deep-review
+findings are not (SARIF is a deterministic CI artifact).
+
+The GitHub Action gains two **opt-in** inputs (both default `false`, so existing
+usage is unchanged): `sarif` uploads the SARIF to code-scanning via `upload-sarif`
+(PR annotations + Security tab; needs `permissions: security-events: write`), and
+`annotations` emits inline `::error`/`::warning` PR annotations. Both run even when
+the scan verdict fails, and neither modifies the project.
+
+### Added
+- **`skills/appstore-precheck/scripts/sarif.sh`** — `render_sarif()`, a SARIF 2.1.0
+  writer over the findings buffer (pure `jq`).
+- **`scan.sh --format sarif`** (and `bin/cli.js --format text|json|sarif`).
+- **`action.yml`** opt-in inputs `sarif` and `annotations` (default off): SARIF
+  upload via `github/codeql-action/upload-sarif@v3` and inline PR annotations.
+- Tests: `tests/test-sarif.sh` and `tests/test-action-sarif.sh`.
+
+### Notes
+- Read-only preserved: the scanner writes only to stdout; the Action redirects SARIF
+  to a CI workspace file. No auto-fix. Default `--format text`/`--format json` output
+  and the Action's default behavior are byte-identical to before.
+
 ## [1.9.0] - 2026-07-02
 
 Smarter analysis (roadmap #2a): **screenshot vision**, in two layers.

package/README.md

@@ -264,6 +264,29 @@ job on a RED verdict; set `fail-on: YELLOW` to be stricter:
 Both inputs are optional: with none set, the action scans the repo root and fails the job only on
 a RED verdict. No App Store Connect credentials are needed; the action runs the static scan only.
 
+### SARIF & PR annotations (opt-in)
+
+The Action can surface findings as GitHub code-scanning results and inline PR annotations. Both are
+off by default; enable either or both:
+
+```yaml
+permissions:
+  contents: read
+  security-events: write   # required for SARIF upload
+jobs:
+  precheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: berkayturk/appstore-precheck@v1
+        with:
+          sarif: true         # upload SARIF to the Security tab + PR annotations
+          annotations: true   # also emit inline ::error/::warning annotations
+```
+
+Locally / via npx: `npx appstore-precheck --format sarif > results.sarif`. The scan stays read-only;
+nothing is auto-fixed.
+
 ## How it works
 
 | Phase | Step |

package/bin/cli.js

@@ -36,6 +36,7 @@ function printHelp() {
     `Options:\n` +
     `  --dir <path>        Directory to scan (default: current directory)\n` +
     `  --fail-on <level>   Exit non-zero at RED (default) or YELLOW\n` +
+    `  --format <fmt>      Output format: text (default), json, or sarif\n` +
     `  -v, --version       Print the version and exit\n` +
     `  -h, --help          Show this help and exit\n` +
     `\n` +
@@ -53,7 +54,7 @@ function fail(message, code) {
 }
 
 function parseArgs(argv) {
-  const opts = { dir: process.cwd(), failOn: 'RED' };
+  const opts = { dir: process.cwd(), failOn: 'RED', format: 'text' };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '-h' || a === '--help') { printHelp(); process.exit(0); }
@@ -69,6 +70,12 @@ function parseArgs(argv) {
       opts.failOn = v;
       continue;
     }
+    if (a === '--format') {
+      const v = (argv[++i] || '').toLowerCase();
+      if (v !== 'text' && v !== 'json' && v !== 'sarif') fail('--format must be text, json, or sarif', 64);
+      opts.format = v;
+      continue;
+    }
     fail(`unknown option: ${a} (try --help)`, 64);
   }
   return opts;
@@ -84,7 +91,8 @@ function main() {
     fail(`not a directory: ${opts.dir}`, 64);
   }
 
-  const scan = spawnSync('bash', [SCAN], {
+  const scanArgs = opts.format === 'text' ? [SCAN] : [SCAN, '--format', opts.format];
+  const scan = spawnSync('bash', scanArgs, {
     cwd: opts.dir,
     encoding: 'utf8',
     maxBuffer: 32 * 1024 * 1024,
@@ -97,6 +105,10 @@ function main() {
   const scanOut = scan.stdout || '';
   process.stdout.write(scanOut);
 
+  if (opts.format !== 'text') {
+    process.exit(scan.status === 0 ? 0 : (scan.status || 0));
+  }
+
   const verdict = spawnSync('bash', [VERDICT], { input: scanOut, encoding: 'utf8' });
   if (verdict.error) fail(`failed to compute the verdict: ${verdict.error.message}`, 70);
   const summary = verdict.stdout || '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appstore-precheck",
-  "version": "1.9.0",
+  "version": "1.10.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)",

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.9.0
+  version: 1.10.0
 allowed-tools: Bash Read Grep Glob WebFetch
 ---
 

package/skills/appstore-precheck/references/methodology.md

@@ -11,6 +11,7 @@ whole file to run the skill.
 - [Phase 4: Pierre deep review (28 checks)](#phase-4-pierre-deep-review-28-semantic-checks)
 - [Auto-detection rules](#auto-detection-rules)
 - [Verdict thresholds](#verdict-thresholds)
+- [SARIF output](#sarif-output---format-sarif)
 - [Pre-submit manual checklist](#pre-submit-manual-checklist)
 
 ---
@@ -221,6 +222,18 @@ blocks, but it can be the fifth WARN that tips GREEN into YELLOW.
 
 ---
 
+## SARIF output (`--format sarif`)
+
+`scan.sh --format sarif` emits a SARIF 2.1.0 log built from the same structured findings as
+`--format json` (pure `jq`, no new dependency). `results[]` contains the non-suppressed FAIL and
+WARN findings (FAIL → `error`, WARN → `warning`); PASS and suppressed findings are excluded. Findings
+that carry a `file`/`line` become SARIF `physicalLocation`s so GitHub can anchor PR annotations. Only
+the deterministic scan findings are included — the agent-mode Pierre deep-review findings are not
+(SARIF is a deterministic CI artifact). The GitHub Action uploads this via `upload-sarif` and/or
+emits inline `::error`/`::warning` annotations, both opt-in.
+
+---
+
 ## Pre-submit manual checklist
 
 Things the scanner cannot verify; confirm by hand before you submit:

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# sarif.sh — SARIF 2.1.0 output layer for scan.sh. Sourced; pure jq over the
+# findings buffer. No side effects, no output on load. bash 3.2 compatible.
+
+: "${PRECHECK_VERSION:=dev}"
+
+# render_sarif -> prints a SARIF 2.1.0 log built from the FINDINGS_TMP buffer.
+# results[] = non-suppressed FAIL/WARN only (PASS + suppressed excluded);
+# level: FAIL->error, WARN->warning. rules[] = distinct non-empty ruleIds present.
+render_sarif() {
+  local buf="${FINDINGS_TMP:-/dev/null}"
+  local uri="https://github.com/berkayturk/appstore-precheck"
+  local help="https://github.com/berkayturk/appstore-precheck/blob/main/skills/appstore-precheck/references/methodology.md"
+  if [[ ! -s "$buf" ]]; then
+    jq -nc --arg v "$PRECHECK_VERSION" --arg u "$uri" '
+      {"$schema":"https://json.schemastore.org/sarif-2.1.0.json", "version":"2.1.0",
+       "runs":[{"tool":{"driver":{"name":"appstore-precheck","version":$v,"informationUri":$u,"rules":[]}},"results":[]}]}'
+    return 0
+  fi
+  jq -s --arg v "$PRECHECK_VERSION" --arg u "$uri" --arg help "$help" '
+    (map(select(.suppressed==false and (.severity=="FAIL" or .severity=="WARN")))) as $issues
+    | ($issues
+        | map({id:.rule_id, text:.guideline})
+        | map(select(.id != "" and .id != null))
+        | unique_by(.id)
+        | map({id:.id, name:.id, shortDescription:{text:.text}, helpUri:$help})) as $rules
+    | ($issues | map(
+        ( (if (.rule_id // "") == "" then {} else {ruleId:.rule_id} end)
+          + {level:(if .severity=="FAIL" then "error" else "warning" end),
+             message:{text:.message}}
+          + (if .file != null
+               then {locations:[{physicalLocation:(
+                       {artifactLocation:{uri:.file}}
+                       + (if .line != null then {region:{startLine:.line}} else {} end))}]}
+               else {locations:[]} end) )
+      )) as $results
+    | {"$schema":"https://json.schemastore.org/sarif-2.1.0.json", "version":"2.1.0",
+       "runs":[{"tool":{"driver":{"name":"appstore-precheck","version":$v,"informationUri":$u,"rules":$rules}},"results":$results}]}
+  ' "$buf"
+}

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

@@ -16,6 +16,7 @@ source "$(dirname "${BASH_SOURCE[0]}")/findings.sh"
 source "$(dirname "${BASH_SOURCE[0]}")/suppress.sh"
 source "$(dirname "${BASH_SOURCE[0]}")/project-model.sh"
 source "$(dirname "${BASH_SOURCE[0]}")/image-dims.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/sarif.sh"
 FINDINGS_TMP="$(mktemp)"; export FINDINGS_TMP
 trap 'rm -f "$FINDINGS_TMP"' EXIT
 FORMAT="text"
@@ -28,13 +29,13 @@ PRECHECK_VERSION="$(grep -m1 -E '^[[:space:]]*version:' "$(dirname "${BASH_SOURC
 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
+      if [[ $# -lt 2 ]]; then echo "scan.sh: --format needs a value (text|json|sarif)" >&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; }
+[[ "$FORMAT" == json || "$FORMAT" == text || "$FORMAT" == sarif ]] || { echo "scan.sh: --format must be text|json|sarif" >&2; exit 64; }
 
 CONFIG="${APPSTORE_PRECHECK_CONFIG:-.appstore-precheck.json}"
 have_jq() { command -v jq >/dev/null 2>&1; }
@@ -202,7 +203,7 @@ 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
+if [[ "$FORMAT" != text ]]; then exec 4>&1 1>/dev/null; fi
 
 echo "PASS: layout — ios='${IOS_DIR:-?}' metadata='${META_DIR:-?}' xcstrings='${XCSTRINGS:-?}' locales=${#LOCALES[@]}"
 
@@ -1011,4 +1012,5 @@ 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
+if [[ "$FORMAT" == json ]]; then exec 1>&4 4>&-; render_json;
+elif [[ "$FORMAT" == sarif ]]; then exec 1>&4 4>&-; render_sarif; fi