@microsoft/sarif-multitool-darwin 4.6.4 → 5.0.0

package/Sarif.xml

@@ -6866,6 +6866,330 @@
             Enables a trace message that summarizes all results and notification by id and severity.
             </summary>
         </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConvention">
+            <summary>
+            Enforces the SARIF SDK AI-authoring convention for <see cref="P:Microsoft.CodeAnalysis.Sarif.Result.RuleId"/>.
+            </summary>
+            <remarks>
+            <para>The emit verb chain (and any future AI-facing acceptor on top of the same SDK)
+            is opinionated about what a well-shaped AI finding's <see cref="P:Microsoft.CodeAnalysis.Sarif.Result.RuleId"/>
+            looks like. Every accepted result MUST carry a ruleId in one of two forms:</para>
+            <list type="bullet">
+            <item><description><b>Taxonomy sub-id</b> — <c>&lt;BASE&gt;/&lt;sub-id&gt;</c> where
+            <c>BASE</c> is a recognized taxonomy entry id (e.g., <c>CWE-89</c>,
+            <c>CVE-2021-12345</c>, <c>OWASP-A01-2021</c>) and <c>sub-id</c> is a non-empty
+            AI-chosen sub-classifier with no slashes or whitespace
+            (e.g., <c>CWE-89/kql-injection-from-config</c>).</description></item>
+            <item><description><b>NOVEL escape hatch</b> — <c>NOVEL-&lt;sub-id&gt;</c> for
+            findings that don't map to any known taxonomy entry
+            (e.g., <c>NOVEL-prompt-injection-via-system-message</c>). The NOVEL- form is
+            exclusive: it does not accept a slash. If the AI can connect the finding back to
+            a taxonomy entry it MUST use the sub-id form instead.</description></item>
+            </list>
+            <para>Rationale: the sub-id form keeps AI1012 silent (sub-classification is what
+            the rule wants) AND lets the CWE taxonomy enricher hydrate the base descriptor
+            from MITRE metadata, so the AI gets enriched output for free while staying
+            honest about which sub-pattern of the base it observed. The NOVEL- form keeps
+            non-taxonomy findings emittable without forcing the AI to pretend a CWE applies.
+            See <c>docs/AI-RuleId-Convention.md</c> for the full rationale and examples.</para>
+            <para>Producers using <see cref="T:Microsoft.CodeAnalysis.Sarif.Writers.SarifLogger"/> directly do not flow through
+            this convention — it is specific to the AI-authoring emit verb path.</para>
+            </remarks>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConvention.IsNovel(System.String)">
+            <summary>
+            Returns true when <paramref name="ruleId"/> starts with the NOVEL- escape-hatch
+            prefix. The full grammar is enforced by <see cref="M:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConvention.IsAcceptable(System.String)"/>; this helper
+            is for consumers (e.g., the AI1012 validation rule) that just need to know
+            whether the ruleId is a NOVEL- finding and therefore already sub-id-bearing by
+            convention.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConvention.IsAcceptable(System.String)">
+            <summary>
+            Returns true when <paramref name="ruleId"/> conforms to one of the two AI ruleId
+            shapes (taxonomy sub-id or NOVEL- prefix). Null and empty are rejected.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConvention.ThrowIfUnacceptable(System.String)">
+            <summary>
+            Throws <see cref="T:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConventionException"/> if <paramref name="ruleId"/>
+            does not conform. The thrown message is shaped for AI consumption: it states
+            what was rejected, why, and exactly which two forms are accepted.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConvention.ThrowIfAnyUnacceptable(System.Collections.Generic.IList{Microsoft.CodeAnalysis.Sarif.Result})">
+            <summary>
+            Validates every result's <see cref="P:Microsoft.CodeAnalysis.Sarif.Result.RuleId"/>. If any violate the convention,
+            throws a single <see cref="T:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConventionException"/> that lists ALL offenders
+            so an AI orchestrator can correct them in one round trip rather than discovering
+            them one at a time.
+            </summary>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConventionException">
+            <summary>
+            Thrown by the AI-authoring emit chain when one or more <see cref="P:Microsoft.CodeAnalysis.Sarif.Result.RuleId"/>
+            values violate <see cref="T:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConvention"/>.
+            </summary>
+            <remarks>
+            <para>The exception's <see cref="P:System.Exception.Message"/> is intentionally shaped for AI
+            consumption: it lists every offending id, explains the two accepted shapes with
+            concrete examples, and points at the documentation. A coding agent that catches the
+            emitted text (e.g., from <c>multitool emit-finalize</c> stderr) can read it directly,
+            correct every offender, and retry — no separate parsing of structured fields is
+            required for the common case. The <see cref="P:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConventionException.OffendingRuleIds"/> property is exposed
+            for programmatic consumers that prefer structured data.</para>
+            </remarks>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConventionException.ErrorCode">
+            <summary>
+            Stable error code so downstream tooling can pattern-match without parsing the
+            human-readable message body.
+            </summary>
+        </member>
+        <member name="P:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConventionException.OffendingRuleIds">
+            <summary>
+            The rejected <see cref="P:Microsoft.CodeAnalysis.Sarif.Result.RuleId"/> values, in source order. An empty string
+            in this list represents a result that supplied no ruleId at all.
+            </summary>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Emit.AtomicSarifWriter">
+            <summary>
+            Atomically writes a SARIF file by staging to a sibling temp file in the same directory
+            and renaming over the destination.
+            </summary>
+            <remarks>
+            <para>The staging file is placed in the same directory as the destination so the final
+            rename is a within-volume operation, which is atomic on every supported filesystem.</para>
+            <para>If the rename fails, the staging file is removed to avoid leaving turds behind.</para>
+            <para>The <c>writeContent</c> callback receives the underlying <see cref="T:System.IO.FileStream"/>;
+            callers MAY dispose any wrapper they construct (e.g., a <see cref="T:System.IO.StreamWriter"/>) — the
+            final fsync is best-effort and tolerates an already-disposed stream.</para>
+            </remarks>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.AtomicSarifWriter.Write(System.String,System.Action{System.IO.Stream})">
+            <summary>
+            Stages writing via <paramref name="writeContent"/>, then atomically replaces
+            <paramref name="destinationPath"/>.
+            </summary>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Emit.SarifEvent">
+            <summary>
+            One line of the append-only event log that backs incremental SARIF authoring.
+            </summary>
+            <remarks>
+            Wire shape: <c>{"v":1,"kind":"&lt;kind&gt;","payload":{ ... }}</c>.
+            The payload is a SARIF object (Run header, Result, Notification, or Invocation) and is
+            preserved as a <see cref="T:Newtonsoft.Json.Linq.JToken"/> until consumers deserialize it into the appropriate
+            strongly-typed SDK object.
+            </remarks>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventKinds">
+            <summary>
+            Canonical event kinds for the JSONL event log that backs incremental SARIF authoring.
+            </summary>
+            <remarks>
+            The event log shape is:
+            <code>{"v":1,"kind":"&lt;kind&gt;","payload":{ ... }}</code>
+            Readers MAY skip unknown <c>kind</c> values when the schema version <c>v</c> is supported;
+            readers MUST fail when <c>v</c> is unknown for a known <c>kind</c>.
+            </remarks>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventKinds.RunHeader">
+            <summary>
+            A partial <see cref="T:Microsoft.CodeAnalysis.Sarif.Run"/> skeleton (everything except <c>results</c>, <c>invocations</c>,
+            and <c>notifications</c>, which arrive as separate events). MUST appear at most once per
+            event log; SHOULD be the first event in the log.
+            </summary>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventKinds.Result">
+            <summary>
+            A single self-contained <see cref="F:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventKinds.Result"/>. Self-contained means the result
+            SHALL NOT carry index references (<c>ruleIndex</c>, <c>artifactLocation.index</c>,
+            etc.) into run-level caches. Use <c>ruleId</c> rather than <c>ruleIndex</c>; the
+            replay engine auto-registers descriptors keyed by <see cref="P:Microsoft.CodeAnalysis.Sarif.Result.RuleId"/>.
+            </summary>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventKinds.ExecutionNotification">
+            <summary>
+            A self-contained <see cref="T:Microsoft.CodeAnalysis.Sarif.Notification"/> destined for
+            <c>invocations[last].toolExecutionNotifications</c>. The replay engine routes events
+            of this kind to the execution-notifications array.
+            </summary>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventKinds.ConfigurationNotification">
+            <summary>
+            A self-contained <see cref="T:Microsoft.CodeAnalysis.Sarif.Notification"/> destined for
+            <c>invocations[last].toolConfigurationNotifications</c>. The replay engine routes
+            events of this kind to the configuration-notifications array.
+            </summary>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventKinds.Invocation">
+            <summary>
+            A complete <see cref="F:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventKinds.Invocation"/> object. Producers may append multiple
+            invocations per run.
+            </summary>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventKinds.RuleDescriptor">
+            <summary>
+            A single <see cref="T:Microsoft.CodeAnalysis.Sarif.ReportingDescriptor"/> targeted at <c>run.tool.driver.rules</c>.
+            Emitted by the <c>add-reporting-descriptor --rules</c> verb. The replayer appends the
+            descriptor to the rules list before result-driven auto-registration runs, so an
+            explicitly-supplied descriptor wins over the minimal one that would otherwise be
+            synthesized from a result's <c>ruleId</c>. The verb enforces
+            <see cref="M:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConvention.IsNovel(System.String)"/> on the descriptor id — this kind is
+            reserved for NOVEL- novel-finding descriptors. Taxonomy-mapped descriptors (e.g.,
+            <c>CWE-89</c>) come from the taxonomy enricher, not from this event.
+            </summary>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventKinds.NotificationDescriptor">
+            <summary>
+            A single <see cref="T:Microsoft.CodeAnalysis.Sarif.ReportingDescriptor"/> targeted at
+            <c>run.tool.driver.notifications</c>. Emitted by the <c>add-reporting-descriptor</c>
+            verb (default target). Notifications use opaque ids by convention (e.g.,
+            <c>progress</c>, <c>config-error</c>) and carry no convention gate — any non-empty id
+            is accepted. The replayer appends the descriptor to the notifications list verbatim.
+            </summary>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventKinds.CurrentSchemaVersion">
+            <summary>The current event-log schema version.</summary>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventLogException">
+            <summary>
+            Thrown when the event log is malformed, corrupt, locked, or carries an unsupported
+            schema version for a known kind.
+            </summary>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventLogReader">
+            <summary>
+            Forward-only reader for a SARIF event log.
+            </summary>
+            <remarks>
+            <para>Tolerates both LF and CRLF line endings (per JSONL convention; emits LF). Tolerates a
+            single optional UTF-8 BOM at the start of the stream; rejects BOM elsewhere.</para>
+            <para>Unknown event <c>kind</c> values at the current schema version are skipped (forward
+            compatibility). Unknown schema <c>v</c> on a known kind is fatal.</para>
+            <para>Malformed JSON on any line is fatal; the reader reports the 1-based line number and
+            reason.</para>
+            </remarks>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventLogReader.Read(System.String)">
+            <summary>
+            Streams events from the given path. Unknown kinds at supported schema versions are
+            silently skipped. Unknown <c>v</c> for a known kind throws.
+            </summary>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventLogWriter">
+            <summary>
+            Append-only writer for a SARIF event log (<c>*.sarif.wip.jsonl</c>).
+            </summary>
+            <remarks>
+            <para>The writer opens the target file with <see cref="F:System.IO.FileShare.Read"/> sharing. On
+            Windows this rejects a concurrent second writer with an <see cref="T:System.IO.IOException"/>; on
+            POSIX the .NET runtime does not enforce FileShare.Read against subsequent opens, so
+            the cross-process exclusive-write guarantee is Windows-only. The emit chain's
+            canonical use is single-process JSONL append; callers should not rely on cross-process
+            locking on Linux/macOS.</para>
+            <para>If the file exists and does not end with a newline, the prior writer was interrupted
+            mid-line; the writer rejects the file with a <see cref="T:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventLogException"/> rather
+            than risk concatenating bytes to a torn line. This is best-effort: a crash AFTER a partial
+            write of the current line but BEFORE the trailing <c>\n</c> still leaves a torn line; the
+            torn-line check protects subsequent <em>append</em> sessions, not the in-progress one.</para>
+            <para>Every event is serialized to a single UTF-8 line terminated with <c>\n</c>. After
+            each line the writer calls <see cref="M:System.IO.FileStream.Flush"/> (managed buffer to OS buffer)
+            — NOT <c>Flush(flushToDisk: true)</c>. The line is durably committed at <c>Dispose</c>
+            when the underlying <see cref="T:System.IO.FileStream"/> flushes and closes; the final SARIF artifact
+            is the durable-write contract, written via <see cref="T:Microsoft.CodeAnalysis.Sarif.Emit.AtomicSarifWriter"/>.</para>
+            </remarks>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventLogWriter.Append(System.String,Newtonsoft.Json.Linq.JToken)">
+            <summary>Appends an event with the given kind and payload.</summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventLogWriter.Append(System.String,System.Object)">
+            <summary>Appends an event whose payload is a strongly-typed SARIF object.</summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventLogWriter.EnsureNoTornTrailingLine(System.String)">
+            <summary>
+            If the file exists and is non-empty, verify its last byte is <c>\n</c>; otherwise the
+            prior writer was interrupted mid-line and the file is in an unrecoverable state for
+            safe append.
+            </summary>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventReplayer">
+            <summary>
+            Replays a SARIF event log into an in-memory <see cref="T:Microsoft.CodeAnalysis.Sarif.SarifLog"/>.
+            </summary>
+            <remarks>
+            <para>v1 contract:</para>
+            <list type="bullet">
+            <item><description>At most one <c>run-header</c> event; if present, it SHOULD be first.
+            The header MAY carry a partial <see cref="T:Microsoft.CodeAnalysis.Sarif.Run"/> shape (tool, language, columnKind,
+            defaultEncoding, defaultSourceLanguage, originalUriBaseIds, versionControlProvenance,
+            automationDetails, baselineGuid, redactionTokens, etc.). <c>results</c>, <c>invocations</c>,
+            and <c>notifications</c> on a header are ignored — those belong in their own events.</description></item>
+            <item><description><c>result</c> events MUST be self-contained: <c>ruleIndex</c> is ignored
+            (re-derived from <c>ruleId</c>); index references into run-level caches are not validated
+            in v1 (producers needing indexed references should use <see cref="T:Microsoft.CodeAnalysis.Sarif.Writers.SarifLogger"/>
+            directly). Every <see cref="P:Microsoft.CodeAnalysis.Sarif.Result.RuleId"/> MUST conform to
+            <see cref="T:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConvention"/> — taxonomy sub-id form
+            (<c>&lt;BASE&gt;/&lt;sub-id&gt;</c>, e.g., <c>CWE-89/kql-injection-from-config</c>) or
+            NOVEL escape hatch (<c>NOVEL-&lt;sub-id&gt;</c>). Violations throw
+            <see cref="T:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConventionException"/> listing every offender at once.</description></item>
+            <item><description><c>invocation</c> events are appended to <c>run.invocations</c> in
+            event order.</description></item>
+            <item><description><c>execution-notification</c> events are buffered and attached at
+            finalize to <c>run.invocations[last].toolExecutionNotifications</c>;
+            <c>configuration-notification</c> events to
+            <c>run.invocations[last].toolConfigurationNotifications</c>. If no invocation has been
+            supplied, a synthetic <c>{ "executionSuccessful": true }</c> invocation is created to
+            hold them (SARIF requires a home for notifications). Notifications whose <c>timeUtc</c>
+            is unset on the event payload are stamped with <see cref="P:System.DateTime.UtcNow"/> at
+            replay time so AI execution-timeline consumers can order events without burdening
+            producers to track wall-clock themselves (cf. AI2019). Producer-supplied
+            <c>timeUtc</c> values are preserved.</description></item>
+            </list>
+            <para>Descriptor auto-registration mirrors <see cref="T:Microsoft.CodeAnalysis.Sarif.Writers.SarifLogger"/>: on first
+            sighting of a <see cref="P:Microsoft.CodeAnalysis.Sarif.Result.RuleId"/>, the replayer appends a minimal
+            <see cref="T:Microsoft.CodeAnalysis.Sarif.ReportingDescriptor"/> to <c>run.tool.driver.rules</c> and back-fills
+            <see cref="P:Microsoft.CodeAnalysis.Sarif.Result.RuleIndex"/>.</para>
+            </remarks>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventReplayer.Replay(System.String)">
+            <summary>
+            Reads the event log at <paramref name="eventLogPath"/> and returns a
+            <see cref="T:Microsoft.CodeAnalysis.Sarif.SarifLog"/> with a single <see cref="T:Microsoft.CodeAnalysis.Sarif.Run"/>.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventReplayer.Replay(System.Collections.Generic.IEnumerable{Microsoft.CodeAnalysis.Sarif.Emit.SarifEvent})">
+            <summary>
+            Reads the supplied <paramref name="events"/> and returns a <see cref="T:Microsoft.CodeAnalysis.Sarif.SarifLog"/> with
+            a single <see cref="T:Microsoft.CodeAnalysis.Sarif.Run"/>.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventReplayer.ReplayToFile(System.String,System.String,System.Boolean)">
+            <summary>
+            Replays the event log and writes the resulting <see cref="T:Microsoft.CodeAnalysis.Sarif.SarifLog"/> atomically to
+            <paramref name="destinationPath"/>.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventReplayer.MergeDescriptors(System.Collections.Generic.IList{Microsoft.CodeAnalysis.Sarif.ReportingDescriptor},System.Collections.Generic.IList{Microsoft.CodeAnalysis.Sarif.ReportingDescriptor},System.String,System.Action{System.Collections.Generic.IList{Microsoft.CodeAnalysis.Sarif.ReportingDescriptor}})">
+            <summary>
+            Merges producer-supplied descriptors emitted as <c>rule-descriptor</c> /
+            <c>notification-descriptor</c> events into the target list on the run's driver.
+            </summary>
+            <remarks>
+            <para>Header pre-populated entries (if any) are preserved by reference, so a producer
+            that supplied a descriptor on the run-header AND via an event for the same id is
+            already a contract violation that the verb's emit-time dedup should have rejected.
+            At replay we trust the invariant and append events after pre-populated entries; if
+            the invariant is violated (e.g., a manually-edited event log) the resulting SARIF
+            will carry two descriptors with the same id and the validator will flag it.</para>
+            <para>For the rules array specifically, this method must run BEFORE
+            <see cref="M:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventReplayer.RegisterDescriptorsFromResults(Microsoft.CodeAnalysis.Sarif.Run,System.Collections.Generic.IList{Microsoft.CodeAnalysis.Sarif.Result})"/> so that the explicit descriptors seed
+            the <c>idToIndex</c> table — auto-registration synthesizes minimal descriptors only
+            for ids that aren't already represented.</para>
+            </remarks>
+        </member>
         <!-- Badly formed XML comment ignored for member "M:Microsoft.CodeAnalysis.Sarif.FileEncoding.IsTextualData(System.Byte[])" -->
         <!-- Badly formed XML comment ignored for member "M:Microsoft.CodeAnalysis.Sarif.FileEncoding.IsTextualData(System.Byte[],System.Int32,System.Int32)" -->
         <member name="T:Microsoft.CodeAnalysis.Sarif.FileRegionsCache">
@@ -6876,7 +7200,20 @@
             snippets associated with region instances.
             </summary>
         </member>
-        <member name="M:Microsoft.CodeAnalysis.Sarif.FileRegionsCache.#ctor(System.Int32,Microsoft.CodeAnalysis.Sarif.IFileSystem)">
+        <member name="P:Microsoft.CodeAnalysis.Sarif.FileRegionsCache.HashAlgorithms">
+            <summary>
+            The hash algorithms this cache computes when producing <see cref="T:Microsoft.CodeAnalysis.Sarif.HashData"/> for files.
+            </summary>
+        </member>
+        <member name="P:Microsoft.CodeAnalysis.Sarif.FileRegionsCache.FileSystem">
+            <summary>
+            The file system this cache uses for all I/O. Exposed to internal callers so that
+            downstream <see cref="M:Microsoft.CodeAnalysis.Sarif.Artifact.Create(System.Uri,Microsoft.CodeAnalysis.Sarif.OptionallyEmittedData,System.Text.Encoding,Microsoft.CodeAnalysis.Sarif.HashData,Microsoft.CodeAnalysis.Sarif.IFileSystem,Microsoft.CodeAnalysis.Sarif.HashAlgorithms)"/> / <see cref="M:Microsoft.CodeAnalysis.Sarif.Run.GetFileIndex(Microsoft.CodeAnalysis.Sarif.ArtifactLocation,System.Boolean,Microsoft.CodeAnalysis.Sarif.OptionallyEmittedData,System.Text.Encoding,Microsoft.CodeAnalysis.Sarif.HashData,Microsoft.CodeAnalysis.Sarif.IFileSystem,Microsoft.CodeAnalysis.Sarif.HashAlgorithms)"/> sites
+            can flow the same <see cref="T:Microsoft.CodeAnalysis.Sarif.IFileSystem"/> instance instead of silently falling
+            back to the default <c>FileSystem.Instance</c>.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.FileRegionsCache.#ctor(System.Int32,Microsoft.CodeAnalysis.Sarif.IFileSystem,Microsoft.CodeAnalysis.Sarif.HashAlgorithms)">
             <summary>
             Creates a new <see cref="T:Microsoft.CodeAnalysis.Sarif.FileRegionsCache"/> object.
             </summary>
@@ -6886,6 +7223,10 @@
             <param name="fileSystem">
             An object that provides access to file system services.
             </param>
+            <param name="hashAlgorithms">
+            The set of hash algorithms this cache will compute when producing <see cref="T:Microsoft.CodeAnalysis.Sarif.HashData"/>
+            for files. Defaults to <see cref="F:Microsoft.CodeAnalysis.Sarif.HashAlgorithms.Default"/> (SHA-256 only).
+            </param>
         </member>
         <member name="M:Microsoft.CodeAnalysis.Sarif.FileRegionsCache.PopulateTextRegionProperties(Microsoft.CodeAnalysis.Sarif.Region,System.Uri,System.Boolean,System.String)">
             <summary>
@@ -7326,6 +7667,126 @@
         <member name="M:Microsoft.CodeAnalysis.Sarif.GitHelper.Dispose">
             <inheritdoc/>
         </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.HashAlgorithms">
+             <summary>
+             Specifies the set of hash algorithms to compute for files persisted into a SARIF log.
+             Used in conjunction with <see cref="F:Microsoft.CodeAnalysis.Sarif.OptionallyEmittedData.Hashes"/>, which acts as the
+             on/off switch for emitting any hashes at all; this enum selects which algorithms are
+             produced.
+             </summary>
+             <remarks>
+             SHA-1 is no longer included in the default set. To preserve legacy behavior, callers
+             must explicitly request <see cref="F:Microsoft.CodeAnalysis.Sarif.HashAlgorithms.Sha1"/>.
+            
+             <see cref="F:Microsoft.CodeAnalysis.Sarif.HashAlgorithms.GitBlobSha1"/> emits a hash with the dictionary key
+             <c>git-blob-sha-1</c>, computed as <c>SHA1("blob " + length + "\0" + content)</c>
+             over the raw bytes of the file on disk. This hash is byte-for-byte sensitive,
+             including line-ending configuration. For the value to match a server-persisted git
+             blob SHA, the on-disk bytes must match what git stored (typically LF line endings
+             for text files in a normalized repository).
+            
+             When a caller of <see cref="T:Microsoft.CodeAnalysis.Sarif.Writers.SarifLogger"/> supplies an explicit
+             <see cref="T:Microsoft.CodeAnalysis.Sarif.FileRegionsCache"/>, the algorithm set configured on that cache wins
+             and the logger's <c>hashAlgorithms</c> parameter is not consulted. Configure
+             algorithms on the cache in that scenario.
+             </remarks>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.HashAlgorithms.None">
+            <summary>
+            Compute no hashes.
+            </summary>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.HashAlgorithms.Sha1">
+            <summary>
+            Compute SHA-1. Emitted under the dictionary key <c>sha-1</c>.
+            </summary>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.HashAlgorithms.Sha256">
+            <summary>
+            Compute SHA-256. Emitted under the dictionary key <c>sha-256</c>.
+            </summary>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.HashAlgorithms.GitBlobSha1">
+            <summary>
+            Compute a GitHub blob SHA-1 over the raw bytes of the file. Emitted under the
+            dictionary key <c>git-blob-sha-1</c>. The value matches what
+            <c>git hash-object &lt;file&gt;</c> would produce for the same bytes.
+            </summary>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.HashAlgorithms.Sha512">
+            <summary>
+            Compute SHA-512. Emitted under the dictionary key <c>sha-512</c>.
+            </summary>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.HashAlgorithms.Default">
+            <summary>
+            The default set of algorithms computed by <see cref="!:SarifLogger"/> and related
+            infrastructure when only <see cref="F:Microsoft.CodeAnalysis.Sarif.OptionallyEmittedData.Hashes"/> is requested.
+            </summary>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.HashData">
+            <summary>
+            A bag of hex-encoded hash values for a single artifact, keyed by algorithm.
+            Populate the algorithm-specific properties via object initializer syntax:
+            <c>new HashData { Sha256 = ..., GitBlobSha1 = ... }</c>. Unset properties are
+            omitted from <see cref="M:Microsoft.CodeAnalysis.Sarif.HashData.ToDictionary"/>.
+            </summary>
+        </member>
+        <member name="P:Microsoft.CodeAnalysis.Sarif.HashData.Sha1">
+            <summary>
+            SHA-1 (uppercase hex). Emitted under the dictionary key <c>sha-1</c>.
+            </summary>
+        </member>
+        <member name="P:Microsoft.CodeAnalysis.Sarif.HashData.Sha256">
+            <summary>
+            SHA-256 (uppercase hex). Emitted under the dictionary key <c>sha-256</c>.
+            </summary>
+        </member>
+        <member name="P:Microsoft.CodeAnalysis.Sarif.HashData.Sha512">
+            <summary>
+            SHA-512 (uppercase hex). Emitted under the dictionary key <c>sha-512</c>.
+            </summary>
+        </member>
+        <member name="P:Microsoft.CodeAnalysis.Sarif.HashData.GitBlobSha1">
+            <summary>
+            The GitHub blob SHA-1 of the file content, computed as
+            <c>SHA1("blob " + length + "\0" + content)</c> over the raw bytes of the file.
+            Emitted under the SARIF artifact hashes dictionary key <c>git-blob-sha-1</c>
+            (lowercase hex, matching git's canonical form).
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.HashUtilities.ComputeHashes(System.String,Microsoft.CodeAnalysis.Sarif.IFileSystem,Microsoft.CodeAnalysis.Sarif.HashAlgorithms)">
+            <summary>
+            Computes the requested set of hashes for a file. Returns <c>null</c> if the file
+            cannot be opened (e.g., I/O error, access denied, or a mock file system returns
+            no stream). Defaults to <see cref="F:Microsoft.CodeAnalysis.Sarif.HashAlgorithms.Default"/> (SHA-256 only).
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.HashUtilities.ComputeHashes(System.IO.Stream,Microsoft.CodeAnalysis.Sarif.HashAlgorithms)">
+            <summary>
+            Computes the requested set of hashes from a stream in a single pass, hashing from
+            the stream's current position to the end. The position is restored on seekable streams.
+            </summary>
+            <remarks>
+            <see cref="F:Microsoft.CodeAnalysis.Sarif.HashAlgorithms.GitBlobSha1"/> uses the byte length of the hashed region
+            (<c>stream.Length - stream.Position</c>) to build the git blob header; the result
+            therefore matches <c>git hash-object</c> when the stream is positioned at zero.
+            Non-seekable streams are buffered in memory as a fallback. SHA-* values are
+            uppercase hex; <c>git-blob-sha-1</c> is lowercase, matching git's canonical form.
+            </remarks>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.HashUtilities.ComputeHashesForText(System.String,Microsoft.CodeAnalysis.Sarif.HashAlgorithms)">
+            <summary>
+            Computes the requested set of hashes for the UTF-8 byte representation of <paramref name="text"/>.
+            Defaults to <see cref="F:Microsoft.CodeAnalysis.Sarif.HashAlgorithms.Default"/> (SHA-256 only).
+            </summary>
+            <remarks>
+            Note that <see cref="F:Microsoft.CodeAnalysis.Sarif.HashAlgorithms.GitBlobSha1"/> computed via this overload reflects
+            the UTF-8 encoding of the supplied text, not the original on-disk bytes. To produce
+            a value that matches a git server's stored blob SHA, prefer the stream- or file-based
+            overloads operating on the raw file bytes.
+            </remarks>
+        </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.HttpClientWrapper">
             <summary>
             A wrapper class for accessing the .NET http client.
@@ -9334,6 +9795,148 @@
             dictates exactly which results land in which output file.
             </summary>
         </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus">
+            <summary>
+            Maturity status of a MITRE CWE entry, as declared in the upstream
+            <see href="https://cwe.mitre.org/data/xml/cwec_latest.xml.zip">CWE XML feed</see>.
+            </summary>
+            <remarks>
+            <para>
+            Every entry in <see cref="T:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomy"/>'s consolidated SARIF and brief artifacts
+            carries one of these statuses as the <c>cwe/status</c> property. Callers select a
+            subset with a bitwise combination of these flags; the default
+            (<see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomy.DefaultStatuses"/>) is <c>Stable | Draft | Incomplete</c>,
+            matching the practical floor of what real-world scanners actually emit.
+            </para>
+            <para>
+            In cwec_v4.20 the distribution is wildly skewed: 26 Stable, 432 Draft, 486 Incomplete,
+            25 Deprecated, 0 Obsolete. See <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomy.DefaultStatuses"/> for why the
+            default deliberately includes Incomplete (to cover OWASP-tier CWEs like SSRF that
+            MITRE has not yet promoted to Draft) and excludes Deprecated (so the enricher leaves
+            a migration signal on stale rule descriptors).
+            </para>
+            </remarks>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomy">
+            <summary>
+            Provides access to the SDK's embedded MITRE CWE taxonomy in SARIF and
+            compact-markdown form. Callers select a subset by <see cref="T:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus"/>;
+            the default (<see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomy.DefaultStatuses"/>) is <c>Stable | Draft | Incomplete</c>,
+            which mirrors what real-world scanners report — see remarks for the rationale.
+            </summary>
+            <remarks>
+            <para>
+            The SDK ships exactly two embedded resources — one consolidated SARIF taxonomy
+            (<c>CweTaxonomy.sarif</c>) and one consolidated markdown table (<c>CweTaxonomy.brief.md</c>) —
+            containing every entry in the upstream MITRE catalog regardless of status.
+            Each taxon carries its <c>cwe/status</c> as a property, and the brief table has
+            a Status column. Filtering by status happens at read time, never at load time.
+            </para>
+            <para>
+            Sized for AI prompt-context injection: the brief table fits ~60K tokens at the
+            default loadout, comfortable for every modern frontier model.
+            </para>
+            </remarks>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomy.DefaultStatuses">
+            <summary>
+            The default set of CWE statuses for read and enrichment operations:
+            <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus.Stable"/> | <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus.Draft"/> | <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus.Incomplete"/>.
+            </summary>
+            <remarks>
+            <para>
+            Notably <em>includes</em> <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus.Incomplete"/> and <em>excludes</em>
+            <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus.Deprecated"/>. This is the non-obvious shape, and it is deliberate.
+            </para>
+            <para>
+            MITRE's "Stable" bar is much higher than common usage suggests — at cwec_v4.20
+            only 26 of 969 entries are Stable. Most household-name CWEs (XXE, deserialization,
+            hardcoded credentials, broken crypto, out-of-bounds write) are still <em>Draft</em>,
+            and SSRF (CWE-918) — an OWASP Top 10 entry since 2021 — is <em>Incomplete</em>.
+            </para>
+            <para>
+            We measured how often Incomplete CWEs show up in real scanner rule metadata
+            across <c>github/codeql</c> (13,143 query files) and <c>semgrep/semgrep-rules</c>
+            (2,183 rule files): of 349 distinct CWEs cited, <strong>136 (39%) are upstream-Incomplete</strong>
+            — including CWE-1220 (Insufficient Granularity of Access Control), the third-most-cited
+            CWE across all of Semgrep at 108 rule files. Defaulting to <c>Stable | Draft</c> would
+            silently exclude two-fifths of what real scanners actually emit. See
+            <c>src/Sarif/Taxonomies/CweReadme.md</c> for the full table and methodology.
+            </para>
+            <para>
+            Excluding <c>Deprecated</c> by default is also intentional and also measured: across
+            those same 349 cited CWEs, exactly one Deprecated CWE appears (CWE-247, once). Real
+            scanners have already migrated off deprecated CWEs. The enricher
+            (<see cref="T:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomyEnricher"/>) intentionally gives no help on a deprecated CWE,
+            leaving the descriptor's metadata empty so the producer notices and migrates to the
+            MITRE-recommended replacement. Callers that want a complete snapshot can pass
+            <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus.All"/>.
+            </para>
+            </remarks>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomy.Load(Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus)">
+            <summary>
+            Loads the consolidated CWE taxonomy, optionally filtered by status.
+            </summary>
+            <param name="statuses">
+            Bitwise combination of <see cref="T:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus"/> flags. Defaults to <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomy.DefaultStatuses"/>
+            (<c>Stable | Draft | Incomplete</c>) — see the documentation on <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomy.DefaultStatuses"/>
+            for why this loadout is the right baseline.
+            </param>
+            <returns>
+            A <see cref="T:Microsoft.CodeAnalysis.Sarif.SarifLog"/> whose <c>runs[0].taxonomies[0].taxa</c> contains every CWE
+            entry whose status matches one of the requested flags. Returns the canonical log
+            directly (no filtering, no copy) when <paramref name="statuses"/> is <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus.All"/>.
+            </returns>
+            <exception cref="T:System.ArgumentException">Thrown if <paramref name="statuses"/> is <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus.None"/>.</exception>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomy.LoadBrief(Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus)">
+            <summary>
+            Loads the compact markdown table of CWE entries, optionally filtered by status.
+            </summary>
+            <param name="statuses">
+            Bitwise combination of <see cref="T:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus"/> flags. Defaults to <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomy.DefaultStatuses"/>.
+            </param>
+            <returns>
+            The verbatim embedded canonical string when <paramref name="statuses"/> is <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus.All"/>;
+            otherwise a re-rendered table with only the matching rows.
+            </returns>
+            <exception cref="T:System.ArgumentException">Thrown if <paramref name="statuses"/> is <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus.None"/>.</exception>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomyEnricher">
+            <summary>
+            Enriches <see cref="T:Microsoft.CodeAnalysis.Sarif.ReportingDescriptor"/> instances on a <see cref="T:Microsoft.CodeAnalysis.Sarif.Run"/> whose
+            <c>id</c> matches a MITRE CWE entry, populating <c>name</c>, <c>shortDescription</c>,
+            <c>fullDescription</c>, <c>helpUri</c>, and <c>help</c> from the SDK's embedded
+            taxonomy artifacts.
+            </summary>
+            <remarks>
+            <para>
+            Producer-supplied descriptor fields are never overwritten — the enricher only fills
+            gaps. This makes the enricher safe to run repeatedly and safe to layer on top of
+            producer authoring.
+            </para>
+            <para>
+            This enricher does not add cross-references via <c>reportingDescriptor.relationships</c>
+            or <c>result.taxa</c>. Producers that author CWE descriptors directly do not need that
+            indirection; the pattern is reserved for tools that map their own rule IDs onto CWE.
+            </para>
+            </remarks>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomyEnricher.Enrich(Microsoft.CodeAnalysis.Sarif.Run,Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus)">
+            <summary>
+            Enriches every descriptor on the supplied <see cref="T:Microsoft.CodeAnalysis.Sarif.Run"/> whose id maps to a
+            CWE entry in the requested statuses.
+            </summary>
+            <param name="run">The run whose <c>tool.driver.rules</c> and <c>tool.extensions[].rules</c> are enriched.</param>
+            <param name="statuses">
+            The CWE statuses to source enrichment data from. Defaults to <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomy.DefaultStatuses"/>
+            (<c>Stable | Draft | Incomplete</c>), which excludes <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus.Deprecated"/> by design —
+            see <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomy.DefaultStatuses"/> for the rationale. Descriptors that reference
+            deprecated CWEs are left untouched so the producer notices the migration signal.
+            </param>
+            <returns>The number of descriptors whose content was modified.</returns>
+        </member>
         <member name="M:Microsoft.CodeAnalysis.Sarif.UriHelper.MakeValidUri(System.String)">
              <summary>
              Create a syntactically valid URI from a path that might be