SARIF report

--sarif <path> writes a SARIF 2.1.0 log — the standard format GitHub Code Scanning (and other SARIF-consuming dashboards) expect — instead of, or alongside, --json's raw engine result.

$ surea11y scan ./dist/index.html --sarif results.sarif

See CI integration for a ready-to-paste GitHub Actions workflow that runs a scan and uploads results.sarif to the "Security" tab.

Why a separate format from --json

--json's raw result (see Output schema) is this engine's own contract, versioned and stable per API_STABILITY.md. SARIF is a different, externally-defined contract purpose-built for code-scanning dashboards — a checksResults[] entry and a SARIF result don't map 1:1, so this is a real conversion, not a re-serialization.

What becomes a SARIF result

Only fail/cantTell occurrences produce SARIF results (same "violations only" framing as the HTML report). So a log with no results says nothing failed or needs review among the checks that ran; it doesn't say what was checked, and it is not a conformance claim. Keep the JSON result for that.

A notApplicable check is not always empty: a pack's or custom rule may attach one occurrence explaining why it had nothing to judge (core's rules attach none, since 1.16.0). Those never become results — a consumer treats every result as an alert, and "this was not evaluated" is not one — but they are not dropped either. They are carried as note-level entries in runs[0].invocations[0].toolExecutionNotifications, each naming the rule it came from via associatedRule.id:

"invocations": [
  {
    "executionSuccessful": true,
    "toolExecutionNotifications": [
      {
        "level": "note",
        "message": { "text": "No form on this page could be checked: each is inside a closed shadow root." },
        "associatedRule": { "id": "acme-form-review" }
      }
    ]
  }
]

That keeps a SARIF-only pipeline from reading silence as a clean bill of health. Core's contrast rules need no notice for it: text whose contrast could not be computed is a contrast-computable result. The block is emitted only when there is something to say, so a run with nothing to report has no invocations key at all. A rule that passed writes no notification.

A rule that did not complete (it threw: cantTell with no occurrences and an error) judged nothing, so it is no result either. It is an error-level notification in the same list, "The rule <id> did not complete: <error>", naming the rule in associatedRule.id, so the gap in coverage doesn't read as a pass.

An undecided finding with a lean carries it in properties.lean: { "toward": "fail", "why": "The heading skips a level after the one before it." }, whichever level it is reported at. Where the lean has them, it also carries caution, what could make it wrong ("A layout table can also hold numbers."), and measured, how often it has been right ({ "agreed": 47, "cases": 50, "corpus": "…", "coreVersion": "…" }, once a lean has been counted on five cases, which none has yet), so an alert shows what the HTML report shows beside the lean. Its signals and i18n keys stay in the scan result.

A rule whose every WCAG criterion is outside the scan's target (an AAA rule under engineOptions.wcagLevel: 'AA', or duplicate-id under WCAG 2.2: the criteria the scan left out of rulesResults, as for the wcag-<SC> tags below) still ran, and its fail and cantTell findings are still results, at level note, so they are seen without failing a build scoped to the target. Each says why in properties.outsideTarget: { "criteria": ["1.4.6"], "target": "WCAG 2.2 AA" }.

Every rule that ran (regardless of whether it produced a result) is listed once in runs[0].tool.driver.rules, with defaultConfiguration.level set from the rule's type: automatic (fail-capable) → error, manual (never fail) → warning. A rule id that is not a string, in a stored result, is written as its text; a check with no rule id names no rule, and is left out, as JUnit and EARL leave it.

Field mapping

A compact result (engineOptions.output.detail: 'findings', see Output schema) is read as the full result it stands for, so it is reported the same. A result whose standards list is missing or damaged still tags every standard its rules name.

Locations

DOM-based scanning has no line/column to report, so physicalLocation.artifactLocation.uri is the scanned target itself, not a source-file position:

• Local file scans: a file inside the current working directory is a path relative to it, forward-slashed, with each segment percent-encoded (build%20out/index.html). If this matches a real file in your repository, GitHub Code Scanning can render the finding as an inline annotation. A file outside the working directory is an absolute file: URL, not a relative path climbing out of the repository with ../, which a consumer could not resolve.
• URL scans: the scanned URL itself. GitHub Code Scanning will still list the finding, but can't attach an inline annotation to a URL that isn't a file in the repository — this is inherent to how SARIF/Code Scanning associate findings with source, not a surea11y limitation. If you need inline annotations, scan the rendered HTML file (e.g. a build output artifact) rather than a live URL. The URL is written as a URL parser serializes it, so what a URI can't hold is percent-encoded (https://example.test/a%20b).
• Other targets: a result whose url is not a URL, such as the path a page was scanned under (runDomRulesInPage('dist/my page.html', …)), is a relative path, forward-slashed, with each segment percent-encoded (dist/my%20page.html); a Windows path is an absolute file: URL. A result with no url, or one that is not a string, is located at about:blank.

The element's location (its selector, prefixed with its shadow hosts' selectors and >>> when it is inside a shadow tree) is additionally carried as a logicalLocations[].fullyQualifiedName, so a consumer that reads logical locations still gets the "which element" signal even without a usable physical location.

Cross-frame results

A result from runa11yCoreAcrossFrames, or a binding's .frames(true) scan (see Output schema), is one run: every frame's findings are results in it. A finding in a frame is located in that frame's document (artifactLocation.uri is the frame's URL), and carries the frame's path in properties.frame:

"properties": {
  "severity": "serious",
  "confidence": "high",
  "reasonCode": "DEFAULT",
  "html": "<img src=\"card.png\">",
  "frame": ["#checkout"]
}

The path is part of the finding's identity too (partialFingerprints), so the same defect in the page and in a frame, or in two frames, are two alerts. A frame that did not answer (no responder, or it timed out) is a warning-level notification, "The frame #ads (https://ads.example/) was not scanned: <error>", since nothing in it was checked.

Scanning at several viewport widths

A layout-dependent rule can fail at one viewport width and pass at another (see Known limitations), so a page scanned at two widths is two analyses, not one. Give each its own category:

const { renderSarifReport } = require('@surea11y/core/sarif');
 
for (const width of [390, 1280]) {
  // ...scan the page at this width into `result`...
  fs.writeFileSync(`a11y-${width}.sarif`, renderSarifReport(result, { category: `a11y-${width}` }));
}

and upload each file separately. GitHub Code Scanning treats each category as its own analysis. Within one category, a later upload replaces the earlier one, and an alert missing from it is closed, so two widths uploaded under the same category would open and close a width-specific alert on every run. GitHub also rejects a single SARIF file holding two runs from the same tool and category. github/codeql-action/upload-sarif has a category input that does the same job when the file carries none.

The finding's identity doesn't include the viewport, and doesn't need to: the same element with the same defect is the same finding at any width, and the category is what keeps the analyses apart. runs[0].properties.environment records the viewport each run used.

Options

renderSarifReport(result, options) from @surea11y/core/sarif returns the log as JSON text. It takes:

Combining with --baseline

A generic SARIF consumer has no "known, don't gate on this" concept of its own — the only faithful way to honor a baseline in SARIF output is to omit already-known fail occurrences entirely, rather than downgrade them to warning:

$ surea11y scan ./dist/index.html --baseline baseline.json --sarif results.sarif

cantTell occurrences are never left out by a baseline. A baseline written with buildBaselineEntries(result, { leanFail: true }) also records the findings that lean fail, as entries marked lean: 'fail' (see Baseline / allowlist); under leanFailAs: 'error' such a finding stays a warning instead of being raised to error, so a team can accept the likely failures it already has and still gate on new ones. --write-baseline records fail occurrences only.

Combining with --html/--json

--sarif, --html, and --json are independent output flags — pass any combination in one run; each writes/prints its own report from the same single scan.