SARIFレポート

--sarif <path>は、--jsonが出すエンジンの生の結果の代わりに、またはそれと並べて、SARIF 2.1.0のログを書き出します。GitHub Code Scanning（やその他のSARIFを読み込むダッシュボード）が前提とする標準形式です。

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

スキャンを実行してresults.sarifを「Security」タブにアップロードする、そのまま貼り付けて使えるGitHub ActionsのワークフローはCI連携を参照してください。

--jsonとは別の形式にしている理由

--jsonの生の結果（出力スキーマを参照）はこのエンジン独自の契約で、API_STABILITY.mdに従ってバージョン管理され、安定しています。SARIFはそれとは別の、外部で定義された契約で、コードスキャンのダッシュボード向けに作られています。checksResults[]のエントリーとSARIFのresultは1対1に対応しないので、これは単なるシリアライズのし直しではなく、本当の意味での変換です。

SARIFのresultになるもの

SARIFのresultになるのはfail／cantTellの検出箇所だけです（HTMLレポートと同じく「違反だけ」という考え方です）。そのため、resultのないログが示すのは、実行されたチェックの中に不合格やレビューが必要なものがなかったということだけです。何がチェックされたかは示さず、適合の表明でもありません。それにはJSONの結果を保存してください。

notApplicableのチェックが常に空とは限りません。ルールは、判定する対象がなかった理由を説明する検出箇所を1つ付けることがあり、コントラストのルールは、背景を計算できるテキストが1つもなかったときにそうします。これらがresultになることはありません（利用側はすべてのresultをアラートとして扱いますが、「評価されなかった」はアラートではないからです）。ただし、捨てられもしません。runs[0].invocations[0].toolExecutionNotificationsにnoteレベルのエントリーとして記録され、それぞれassociatedRule.idで元のルールを示します。

"invocations": [
  {
    "executionSuccessful": true,
    "toolExecutionNotifications": [
      {
        "level": "note",
        "message": { "text": "No eligible text had computable contrast (eligible text nodes: 13). See the contrast computability rule for details." },
        "associatedRule": { "id": "contrast-minimum" }
      }
    ]
  }
]

これにより、SARIFだけを使うパイプラインが、何も報告がないことを問題なしと読み違えずに済みます。コントラストのアラートがないのは、ページに問題がないからかもしれませんし、コントラストがそもそも計算できなかったからかもしれません。その2つを区別できるのはこの通知だけです。このブロックは伝えることがあるときにだけ出力されるので、報告することがない実行ではinvocationsキー自体がありません。合格したルールは通知を書き出しません。

完了しなかったルール（例外を投げたもの。検出箇所がなくerrorを持つcantTell）は何も判定していないので、これもresultにはなりません。同じリストのerrorレベルの通知"The rule <id> did not complete: <error>"になり、associatedRule.idでルールを示します。そのため、カバレッジの抜けが合格と読まれることはありません。

傾きのある未判定の検出結果は、どのlevelで報告されても、それをproperties.leanに持ちます：{ "toward": "fail", "why": "The heading skips a level after the one before it." }。傾きにあれば、誤りになりうる要因であるcaution（"A layout table can also hold numbers."）と、これまでどれだけ正しかったかを示すmeasured（{ "agreed": 47, "cases": 50, "corpus": "…", "coreVersion": "…" }。5件のケースで数えられた傾きにだけ付きますが、まだそうした傾きはありません）も持つので、アラートはHTMLレポートが傾きと並べて示すものを示します。signalsとi18nのキーはスキャン結果に残ります。

WCAGの達成基準がすべてスキャンの目標の外にあるルール（engineOptions.wcagLevel: 'AA'のもとでのAAAのルールや、WCAG 2.2のもとでのduplicate-id。後述のwcag-<SC>タグと同じく、スキャンがrulesResultsから外した達成基準です）も実行されており、そのfailとcantTellの検出結果はresultとして残ります。レベルはnoteで、目標に合わせたビルドを不合格にせずに目に入るようにしています。それぞれproperties.outsideTargetで理由を示します：{ "criteria": ["1.4.6"], "target": "WCAG 2.2 AA" }。

実行されたルールは（resultを出したかどうかにかかわらず）すべてruns[0].tool.driver.rulesに1度ずつ列挙され、defaultConfiguration.levelはルールのtypeから決まります。automatic（failを出せる）ならerror、manual（failにはならない）ならwarningです。保存された結果で文字列でないルールIDは、そのテキストとして書き出されます。ルールIDのないチェックはどのルールも示さないため、JUnitやEARLと同じく省かれます。

フィールドの対応

コンパクトな結果（engineOptions.output.detail: 'findings'。出力スキーマを参照）は、それが表す完全な結果として読まれるので、同じように報告されます。standardsの一覧がないか壊れている結果でも、ルールが指定するすべての規格がタグ付けされます。

位置情報

DOMベースのスキャンには報告できる行／列がないので、physicalLocation.artifactLocation.uriはソースファイル上の位置ではなく、スキャン対象そのものになります。

• ローカルファイルのスキャン：現在の作業ディレクトリ内のファイルは、そこからの相対パス（区切りはスラッシュ）になり、各セグメントはパーセントエンコードされます（build%20out/index.html）。これがリポジトリ内の実在するファイルと一致すれば、GitHub Code Scanningは検出結果をインラインの注釈として表示できます。作業ディレクトリの外にあるファイルは、../でリポジトリの外へ出る相対パスではなく、絶対file: URLになります。そのような相対パスは、受け取る側が解決できないためです。
• URLのスキャン：スキャンしたURLそのものです。GitHub Code Scanningは検出結果を一覧には表示しますが、リポジトリ内のファイルではないURLにインラインの注釈を付けることはできません。これはSARIF／Code Scanningが検出結果とソースを結び付ける仕組みによるもので、surea11yの制限ではありません。インラインの注釈が必要なら、公開中のURLではなく、レンダリング済みのHTMLファイル（ビルド成果物など）をスキャンしてください。URLはURLパーサーがシリアライズするとおりに書き出されるため、URIに入れられない文字はパーセントエンコードされます（https://example.test/a%20b）。
• その他の対象：urlがURLでない結果、たとえばページをスキャンしたときのパス（runDomRulesInPage('dist/my page.html', …)）は、相対パス（区切りはスラッシュ）になり、各セグメントはパーセントエンコードされます（dist/my%20page.html）。Windowsのパスは絶対file: URLになります。urlがない結果や、文字列でない結果の位置はabout:blankです。

要素の位置（そのセレクター。シャドウツリー内にある場合は、シャドウホストのセレクターと >>> を前に付けたもの）はlogicalLocations[].fullyQualifiedNameとしても記録されるので、論理的な位置を読む利用側なら、使える物理的な位置がなくても「どの要素か」という情報を得られます。

フレーム横断の結果

runa11yCoreAcrossFrames、またはバインディングの.frames(true)によるスキャンの結果（出力スキーマを参照）は1つの実行になり、すべてのフレームの検出結果がその中のresultになります。フレーム内の検出結果の位置はそのフレームのドキュメントで（artifactLocation.uriはフレームのURL）、properties.frameにフレームのパスを持ちます。

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

パスは検出結果の識別（partialFingerprints）にも含まれるため、ページとフレーム、あるいは2つのフレームにある同じ欠陥は、2つのアラートになります。応答しなかったフレーム（応答側がない、またはタイムアウトした）は、その中の何も検査されていないため、warningレベルの通知"The frame #ads (https://ads.example/) was not scanned: <error>"になります。

複数のビューポート幅でのスキャン

レイアウトに依存するルールは、あるビューポート幅ではfailになり、別の幅ではpassになることがあります（既知の制限事項を参照）。そのため、2つの幅でスキャンしたページは、1つの分析ではなく2つの分析です。それぞれに独自のカテゴリーを指定してください。

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}` }));
}

そのうえで、各ファイルを別々にアップロードします。GitHub Code Scanningは、カテゴリーごとに独立した分析として扱います。1つのカテゴリー内では、後のアップロードが前のものを置き換え、そこに含まれないアラートは閉じられます。そのため、2つの幅を同じカテゴリーでアップロードすると、幅に固有のアラートが実行のたびに開いたり閉じたりします。また、GitHubは、同じツールとカテゴリーの実行を2つ含む1つのSARIFファイルを拒否します。github/codeql-action/upload-sarifにはcategory入力があり、ファイルにカテゴリーがない場合は同じ役割を果たします。

検出結果の識別にはビューポートは含まれず、含める必要もありません。同じ要素の同じ欠陥は、どの幅でも同じ検出結果であり、分析を分けておくのはカテゴリーの役割です。runs[0].properties.environmentには、各実行が使ったビューポートが記録されます。

オプション

@surea11y/core/sarifのrenderSarifReport(result, options)は、ログをJSONのテキストとして返します。次のオプションを取ります。

--baselineとの併用

一般的なSARIFの利用側には、「既知なのでこれでは止めない」という概念がありません。SARIFの出力でベースラインを忠実に反映する唯一の方法は、既知のfailの検出箇所をwarningに格下げするのではなく、完全に省くことです。

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

cantTellの検出箇所がベースラインで除外されることはありません。buildBaselineEntries(result, { leanFail: true })で書いたベースラインは、不適合に傾く検出結果もlean: 'fail'と示したエントリーとして記録します（ベースライン／許可リストを参照）。leanFailAs: 'error'のもとでは、そうした検出結果はerrorに引き上げられずwarningのままなので、チームはすでにある不適合の可能性が高いものを受け入れつつ、新しいものでゲートできます。--write-baselineが記録するのはfailの検出箇所だけです。

--html／--jsonとの併用

--sarif、--html、--jsonは互いに独立した出力フラグです。1回の実行でどう組み合わせても構いません。どれも同じ1回のスキャンから、それぞれのレポートを書き出し／出力します。