{"schemaVersion":"2.0.0","locale":"en","title":"Understand results","description":"Read coverage before interpreting findings. A report can contain a useful finding and unresolved observations at the same time.","htmlUrl":"https://docs.swift-analyzer.com/guides/results/","markdownUrl":"https://docs.swift-analyzer.com/guides/results/index.md","productRevision":"524fa07e0ae4153c84ac12ae9eb6559df89ec2be","catalogRevision":"4558458d","docsRevision":"1f17ba58ab08627e0de898f1442067b09e960b48cd5605d6529e9275f8930d68","channel":"pre-prod","maturity":"experimental","access":"owner-provided-checkout","markdown":"# Understand results\n\nRead coverage before interpreting findings. A report can contain a useful finding and unresolved observations at the same time.\n\n## Start with the report status\n\n| Status | Meaning in source-scan | Next action |\n| --- | --- | --- |\n| complete | The selected operation has no reported completeness reasons | Inspect each condition and observation; do not extend the result beyond the selected world |\n| degraded | Some analysis ran, but limitations or empty families remain | Review findings together with reasons and unknown observations |\n| unavailable | The requested acquisition or analysis could not be admitted | Fix or narrow the input; do not interpret zero findings |\n\nExit 3 is expected for the three tutorial cases. It reports incomplete capability, not the number of findings. The edited control still exits 3. See [JSON and exit codes](https://docs.swift-analyzer.com/reference/output/) for all process outcomes.\n\n## Read each condition\n\n`requested` means the condition was selected. `executed` means its family evaluator ran. Neither field guarantees that the input produced supported observations for that particular condition.\n\n- `not-run`: the condition did not execute.\n- `no-observations`: its evaluator ran but found no relevant observations.\n- `degraded`: at least one observation is unknown.\n- `completed`: relevant observations were evaluated without an unknown result in that condition's coverage record.\n\nA `completed` row is not a portfolio-wide guarantee. Preserve `observationCount`, `unknownObservationCount`, `findingCount` and the observation identities when reviewing it.\n\n## Follow the evidence\n\nA finding has a condition identity, evidence and source anchors. Inspect the affected source and the rule's assumptions. A source anchor identifies where evidence came from; it does not establish that the rest of the program is covered.\n\nIn the tutorial, V-EXEC-03 finds lost required context through detachment. V-ASYNC-14 finds a guard across suspension while another guard trace remains incomplete. A finding and unknown can therefore coexist even within one requested family.\n\n## Follow one recorded finding\n\nOpen the [positive report](https://docs.swift-analyzer.com/examples/positive/observed.json). The following is a field-by-field walkthrough of that recorded file; the hash is specific to this example.\n\n1. In `conditions`, find the object whose `conditionID` is `V-EXEC-03`. It reports `findingCount: 1` and one entry in `observationIDs`.\n2. In `families`, select the object whose `family` is `execution`. Its `report.rows` contains pairs of observation identity and decision. Match the first member to the condition's observation ID.\n3. In that same family's `report.proofs`, match `conditionID` to the **observation ID**, not to `V-EXEC-03`. This nested field reuses the name `conditionID` but contains the observation hash in this report format.\n4. Read the matched proof's explanation, evidence IDs and `anchors`. Each anchor is a source path and UTF-8 byte offset, not a line number. Inspect those locations in the matching [example source](https://docs.swift-analyzer.com/examples/positive/Sources/Example/Execution.swift).\n\nSelected fields from the recorded condition:\n\n```json\n{\n  \"conditionID\": \"V-EXEC-03\",\n  \"findingCount\": 1,\n  \"observationIDs\": [\n    \"dc834195d051e2852871c5673581baf9b2dee8c0876877b8fd9e7d3cca5131fc\"\n  ]\n}\n```\n\nThe matching execution `report.rows` entry:\n\n```json\n[\n  \"dc834195d051e2852871c5673581baf9b2dee8c0876877b8fd9e7d3cca5131fc\",\n  \"finding\"\n]\n```\n\nThe proof with that same identity includes anchors such as `[\"Sources/Example/Execution.swift\", 67]`. These excerpts omit other fields; keep the full report when filing an issue.\n\nThe `guard` family uses a different shape. For `V-ASYNC-14`, take its condition-level `observationIDs` and match each against `families[family=guard].report.rows[].id`. Each matching object has its own `decision`, `witness`, `evidence` and `sites`; source locations are in `sites`. The positive case has both a `finding` row for Guard.swift and an `unknown:incomplete-guard-trace` row. Do not apply the execution family's pair/proof layout to this family.\n\n## Read one unknown in the control\n\nThe [control report](https://docs.swift-analyzer.com/examples/control/observed.json) has an execution row with `unknown:assumed-isolation-context-unresolved`. The available facts do not resolve the isolation context needed for that observation. It is neither a finding nor proof of safe isolation. Review the corresponding condition's observation IDs and the [control source](https://docs.swift-analyzer.com/examples/control/Sources/Example/Execution.swift), retain that limitation and avoid turning zero findings into a clean result. In the guard family, the edited guard observation becomes `not-applicable`, while a separate incomplete guard trace remains unknown.\n\n## Act within the scope\n\nReview the proposed edit in its actual lifecycle, isolation, error and ownership context. No automatic fix is offered. Re-run after changing code and compare both findings and coverage. If a finding disappears because the new form is unsupported, the result has not established a successful correction.\n\n[Coverage and unknown](https://docs.swift-analyzer.com/concepts/coverage/) explains negative evidence. [Troubleshooting](https://docs.swift-analyzer.com/guides/troubleshooting/) explains common acquisition reasons.\n","anchors":["understand-results","start-with-the-report-status","read-each-condition","follow-the-evidence","follow-one-recorded-finding","read-one-unknown-in-the-control","act-within-the-scope"]}