Reports, Findings, FailOn, and Exit Codes

Report formats

PSRafScan report formats
Format	Use
`PlainText`	Human-readable summary, findings, issue text, fix text, and recommendations.
`Json`	Structured report for automation, archival, or carefully redacted tool handoff.

Normalized finding fields

Each normalized parser or custom-rule finding can include the following fields. A per-finding File field is not part of the reviewed normalized model.

Source, RuleName, Variant
Severity, Category
Line, Column, Text
Issue, Fix, RawMessage

Severity and FailOn

Severity belongs to the finding. FailOn belongs to the scan decision. FailOn does not remove findings below the selected threshold from the JSON report.

Severity threshold behavior
FailOn	Custom-rule result
`Any`	Information, Warning, or Error can return 1.
`Warning`	Warning or Error can return 1.
`Error`	Only Error can return 1.
`None`	Custom-rule findings do not return 1; parser errors still return 2.

Implemented process results

PSRafScan process result codes
Code	Status	Meaning
`0`	Pass	No finding met the selected threshold after successful parsing.
`1`	Fail	At least one custom-rule finding met the threshold.
`2`	ParseError	One or more native parser errors were reported.

Valid JSON shape

{
  "SchemaVersion": "1.0",
  "Tool": "PSRafScan",
  "ScriptPath": "/work/candidate.ps1",
  "IntendedUse": "Ps1File",
  "FailOn": "Warning",
  "ExitCode": 1,
  "Status": "Fail",
  "Summary": { "Total": 1, "Error": 0, "Warning": 1, "Information": 0 },
  "FailureReason": "A finding met the selected Warning threshold.",
  "Recommendation": { "Lines": ["Review and fix the warning finding before running the script."] },
  "Findings": [
    {
      "Source": "CustomRule",
      "RuleName": "SilentErrorAction",
      "Variant": "",
      "Severity": "Warning",
      "Category": "ErrorHandling",
      "Line": 8,
      "Column": 1,
      "Text": "Get-Item -LiteralPath $Path -ErrorAction SilentlyContinue",
      "Issue": "The script uses -ErrorAction SilentlyContinue, which can hide failures that should be handled.",
      "Fix": "Prefer -ErrorAction Stop with meaningful handling.",
      "RawMessage": ""
    }
  ]
}