JSON and exit codes
This page describes source-scan schema 1.0.0 at product 524fa07e. Other subcommands have separate report contracts; do not deserialize them as source-scan reports.
Report fields#
| Field | Interpretation |
|---|---|
| kind | swift-analyzer.source-scan identifies this report type |
| schemaVersion | 1.0.0 for the documented source-scan report |
| maturity | experimental; independent of the documentation's pre-prod channel |
| status | complete, degraded or unavailable |
| requestedConditions | Selected condition IDs, not a finding list |
| conditions | Per-condition requested/executed state, coverage, observations and counts |
| families | Family-level coverage, observations, findings, reasons and evidence payload |
| reasons | Machine-readable limitations or acquisition reasons |
| admittedSourceCount | Sources admitted to the analysis, not all files on disk |
| snapshot | Admitted snapshot identity, or null when unavailable |
| sourceInputDigest | Identity of discovered input, when available |
Additional discovery/admission counters distinguish authored, generated, Swift and native inputs. Read them alongside reasons; discovered inputs are not necessarily admitted. Fields may be absent when their acquisition stage did not finish.
Condition coverage#
A condition row includes conditionID, ruleID, requested, executed, coverage, observationCount, unknownObservationCount, findingCount, notApplicableCount and observationIDs. Coverage values are not-run, no-observations, degraded and completed. Understand results explains their use.
Exit codes#
| Code | Meaning |
|---|---|
| 0 | Operation completed; a configured gate passed where applicable |
| 1 | An explicitly configured findings gate failed |
| 2 | Invalid CLI, schema, manifest or configuration input |
| 3 | Requested definitive analysis lacks sufficient quality or capability |
| 4 | Acquisition, source, index or toolchain failure |
| 5 | Internal invariant or serialization failure |
| 130 | Cancelled; do not treat output as a complete result |
These are the shared analyzer outcome codes. Argument parsing and the separate experimental preview can report errors through their own command error path; preserve stderr and do not infer source-scan coverage from those failures. Source-scan returns 3 when degraded, even if useful findings are present. It has no findings-gate option.
Streams and stability#
Execution proof anchors are pairs such as ["Sources/Example/Execution.swift", 67]: the logical source path followed by a zero-based UTF-8 byte offset from the start of that file. The number is not a line number or a character index. Open the matching source snapshot; non-ASCII characters can occupy several bytes. Other report payloads may use separate line/column or range fields, so interpret each named field according to its report contract.
JSON is written to stdout after validation and serialization. Timing is written to stderr. Preserve the process result separately from JSON. Snapshot IDs, evidence IDs and timings are not expected to match across differently located or rebuilt inputs. Do not parse human-readable output as a stable schema.
Follow one recorded finding walks from a catalog condition through observation IDs to the actual family-specific proof and source locations. It also explains a remaining unknown in the edited control.