@microsoft/sarif-multitool-darwin 5.0.0 → 5.0.1

package/Sarif.Multitool.Library.xml

@@ -4,6 +4,39 @@
         <name>Sarif.Multitool.Library</name>
     </assembly>
     <members>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddInvocationCommand">
+            <summary>
+            Implements <c>multitool add-invocation</c>: appends a fully-formed SARIF invocation
+            JSON to <c>&lt;output&gt;.wip.jsonl</c>.
+            </summary>
+            <remarks>
+            <para>The verb performs no schema validation on the invocation payload beyond "must be
+            a JSON object" — SARIF §3.20 makes every field on <c>Invocation</c> optional, and AI
+            producers vary widely in which fields they have meaningful values for (a daemon may
+            know its <c>startTimeUtc</c> but not its <c>exitCode</c>; a one-shot scanner may know
+            both). Full-log validation belongs in <c>emit-finalize --validate</c>, not at receipt.</para>
+            <para>Invocations are replayed in event order to <c>run.invocations[]</c>. Subsequent
+            <c>execution-notification</c> and <c>configuration-notification</c> events attach to
+            the most recent invocation, so emitting a fresh invocation event MAY be used to start
+            a new notification group within the same scan.</para>
+            </remarks>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddInvocationOptions">
+            <summary>
+            Options for <c>add-invocation</c>, which appends a fully-formed SARIF <c>invocation</c>
+            object to a staged event log (<c>&lt;output&gt;.wip.jsonl</c>) created by
+            <c>emit-init-run</c>.
+            </summary>
+            <remarks>
+            The invocation is supplied as a JSON document (file via <c>--input</c> or piped on
+            stdin). <see cref="!:SarifEventReplayer"/> strips any <c>invocations</c> array carried on
+            the run header — invocations must arrive as their own events — so this verb is the
+            only path a producer has to populate <c>run.invocations[]</c>. Subsequent
+            <c>add-notification</c> events attach to the most recent invocation in event order,
+            so producers MAY append additional invocations to start a new notification group
+            (e.g., to model a re-run within the same scan).
+            </remarks>
+        </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddNotificationCommand">
             <summary>
             Implements <c>multitool add-notification</c>: appends a fully-formed SARIF notification
@@ -138,7 +171,7 @@
             <para>Inside an ADO pipeline three states are possible:</para>
             <list type="bullet">
             <item><see cref="F:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.DetectionState.Complete"/> — every required logical variable is present
-            and well-formed; <see cref="M:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.ApplyTo(Microsoft.CodeAnalysis.Sarif.Run)"/> writes <c>automationDetails.id</c> plus the
+            and well-formed; <see cref="!:ApplyTo(Run)"/> writes <c>automationDetails.id</c> plus the
             four <c>azuredevops/pipeline/build/*</c> property keys that ADO ingestion validates.</item>
             <item><see cref="F:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.DetectionState.None"/> — no required variables are populated; nothing is
             stamped (e.g. a manual local invocation that happens to have <c>TF_BUILD</c> set without
@@ -159,11 +192,41 @@
             <param name="context">Populated context when state is <see cref="F:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.DetectionState.Complete"/>; otherwise <c>null</c>.</param>
             <param name="errorMessage">Human-readable description of present/missing/malformed variables when state is <see cref="F:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.DetectionState.Partial"/>; otherwise <c>null</c>.</param>
         </member>
-        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.ApplyTo(Microsoft.CodeAnalysis.Sarif.Run)">
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.TryApplyTo(Microsoft.CodeAnalysis.Sarif.Run,System.String@)">
             <summary>
-            Stamps the detected pipeline identity onto <paramref name="run"/>.
-            Creates <see cref="P:Microsoft.CodeAnalysis.Sarif.Run.AutomationDetails"/> if absent; does not overwrite
-            <c>Guid</c> or <c>CorrelationGuid</c> fields populated from other sources.
+            Stamps the detected pipeline identity onto <paramref name="run"/>, returning
+            <c>true</c> when no conflict was detected. When the run already carries a
+            non-conflicting <c>automationDetails.id</c> or any of the four
+            <c>azuredevops/pipeline/build/*</c> property values, the existing values are
+            preserved. When the run carries a conflicting value, this method returns
+            <c>false</c> with a diagnostic on <paramref name="conflictError"/> and leaves
+            the run unchanged.
+            </summary>
+            <remarks>
+            <para>The "stamp only when absent, fail on conflict" contract is required because
+            callers (notably <c>emit-init-run</c>'s JSON-payload contract) may supply these
+            fields directly. An unconditional overwrite would silently clobber a producer's
+            declared identity; a conflict is a misconfiguration signal that we want to surface
+            at the verb rather than ship in the run.</para>
+            <para>Producer-supplied <see cref="P:Microsoft.CodeAnalysis.Sarif.RunAutomationDetails.Guid"/> and
+            <see cref="P:Microsoft.CodeAnalysis.Sarif.RunAutomationDetails.CorrelationGuid"/> fields are never touched —
+            they name a different scope (run / run-equivalence-class identity) than the
+            pipeline identity stamped here.</para>
+            </remarks>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.BuildCanonicalAutomationId">
+            <summary>
+            Computes the canonical <c>automationDetails.id</c>
+            (<c>azuredevops/pipeline/build/&lt;org&gt;/&lt;projectId&gt;/&lt;buildDefId&gt;/&lt;phaseId&gt;/&lt;branch&gt;/&lt;buildId&gt;</c>)
+            for this pipeline context. Exposed so JSON-direct callers can stamp the id without
+            constructing a typed <see cref="T:Microsoft.CodeAnalysis.Sarif.Run"/>.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.GetPipelinePropertyValues">
+            <summary>
+            Returns the four <c>azuredevops/pipeline/build/*</c> property name/value pairs
+            validated by <c>GHAzDO1019</c>. Exposed so JSON-direct callers can stamp them
+            without constructing a typed <see cref="T:Microsoft.CodeAnalysis.Sarif.Run"/>.
             </summary>
         </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitEventLogHelpers">
@@ -251,10 +314,17 @@
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunCommand">
             <summary>
             Implements <c>multitool emit-init-run</c>: creates an append-only SARIF event log
-            (<c>&lt;output&gt;.wip.jsonl</c>) seeded with a <c>run-header</c> event built from the
-            supplied tool / repo flags.
+            (<c>&lt;output&gt;.wip.jsonl</c>) seeded with a <c>run-header</c> event built from a
+            caller-supplied SARIF <c>Run</c> JSON document (file via <c>--input</c> or stdin).
             </summary>
             <remarks>
+            <para>The JSON-payload contract matches the other emit verbs (<c>add-result</c>,
+            <c>add-notification</c>, <c>add-reporting-descriptor</c>). The supplied <c>Run</c> may
+            carry any subset of the partial-Run shape the replayer accepts (<c>tool</c>,
+            <c>language</c>, <c>columnKind</c>, <c>defaultEncoding</c>, <c>defaultSourceLanguage</c>,
+            <c>originalUriBaseIds</c>, <c>versionControlProvenance</c>, <c>automationDetails</c>,
+            <c>baselineGuid</c>, <c>redactionTokens</c>, …). <c>results</c>, <c>invocations</c>, and
+            notifications on the header are ignored at replay; those belong in their own events.</para>
             <para>State table:</para>
             <list type="table">
             <listheader>
@@ -285,18 +355,50 @@
             </list>
             </remarks>
         </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunCommand.TryRequireOptionalObject(Newtonsoft.Json.Linq.JObject,System.String,Newtonsoft.Json.Linq.JObject@)">
+            <summary>
+            If <paramref name="parent"/> carries a token at <paramref name="key"/>, requires it to
+            be a JSON object and returns it via <paramref name="value"/>. Returns true when the key
+            is absent (or explicitly null) without surfacing an error; returns false with a clear
+            AI-consumable diagnostic when the key is present but the wrong shape (e.g.
+            <c>"tool": "x"</c>). Walking parent shapes up front prevents JValue indexer accesses
+            further down the validator chain from throwing InvalidOperationException.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunCommand.TryStampAdoContext(Newtonsoft.Json.Linq.JObject,Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext,System.String@)">
+            <summary>
+            Stamps ADO pipeline identity directly onto the JSON payload. Mutating the JObject
+            rather than round-tripping through the typed <see cref="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunCommand.Run(Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunOptions,Microsoft.CodeAnalysis.Sarif.IFileSystem)"/> model preserves any
+            SARIF Run fields the typed model doesn't surface (e.g., <c>redactionTokens</c>) in
+            the wip line. (The replayer materializes a typed <c>Run</c> at finalize time, so
+            non-typed fields are durable only up to that boundary.)
+            </summary>
+        </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunOptions">
             <summary>
             Options for <c>emit-init-run</c>, which opens an append-only event log
-            (<c>&lt;output&gt;.wip.jsonl</c>) seeded with a <c>run-header</c> event for the supplied
-            tool. Subsequent producers append events to the log via the SARIF emit API and finalize
-            via <c>multitool emit-finalize</c>.
+            (<c>&lt;output&gt;.wip.jsonl</c>) seeded with a <c>run-header</c> event built from a
+            caller-supplied SARIF <c>Run</c> JSON document. Subsequent producers append events to the
+            log via the SARIF emit API and finalize via <c>multitool emit-finalize</c>.
             </summary>
             <remarks>
-            CLI flags mirror the SARIF interior paths they populate (e.g., <c>--tool-driver-name</c>
-            populates <c>run.tool.driver.name</c>; <c>--vcp-revisionid</c> populates
-            <c>run.versionControlProvenance[0].revisionId</c>). This trades verbosity for a one-to-one
-            mapping that a SARIF-literate user can read without a help page.
+            <para>The run JSON is supplied as a JSON document (file via <c>--input</c> or piped on
+            stdin), matching the contract used by <c>add-result</c>, <c>add-notification</c>, and
+            <c>add-reporting-descriptor</c>. SARIF <c>Run</c> is by far the richest object in the
+            schema; modeling each field as a CLI flag would require a sprawling and ever-expanding
+            surface that still could not express the legal partial-<c>Run</c> shape the replayer
+            accepts (multiple <c>versionControlProvenance</c> entries, <c>properties</c> bags,
+            <c>language</c>, <c>columnKind</c>, <c>defaultEncoding</c>, <c>redactionTokens</c>, …).
+            The JSON-payload contract keeps the verb generic and lets an AI producer emit
+            arbitrarily-rich run headers without losing fidelity.</para>
+            <para>Profile-essential defects are validated at receipt: <c>tool.driver.name</c> must
+            be a non-empty string; <c>tool.driver.informationUri</c> and
+            <c>versionControlProvenance[*].repositoryUri</c> must be <c>https</c>;
+            <c>originalUriBaseIds["SRCROOT"].uri</c> must be <c>https</c> or <c>file</c>;
+            <c>automationDetails.guid</c> / <c>correlationGuid</c> must be canonical 8-4-4-4-12
+            GUIDs; <c>properties["ai/origin"]</c> must be <c>generated</c>, <c>annotated</c>, or
+            <c>synthesized</c>. The verb also rejects a SARIF <em>log</em> accidentally supplied in
+            place of a <c>Run</c>.</para>
             </remarks>
         </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.FileWorkItemsCommand">

package/Sarif.xml

@@ -9274,6 +9274,14 @@
             </summary>
             <param name="underlyingStream"></param>
         </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.RuleKind">
+            <summary>
+            Identifies the validator family that applies a SARIF reporting-descriptor rule.
+            </summary>
+            <remarks>
+            Not a <c>[Flags]</c> enum; combinations are expressed via <see cref="T:Microsoft.CodeAnalysis.Sarif.RuleKindSet"/>.
+            </remarks>
+        </member>
         <member name="F:Microsoft.CodeAnalysis.Sarif.SarifConstants.SarifFileExtension">
             <summary>
             The standard file extension for SARIF files.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@microsoft/sarif-multitool-darwin",
 	"description": "SARIF Multitool for MacOS (Darwin)",
-	"version": "5.0.0",
+	"version": "5.0.1",
 	"scripts": {
 		"postinstall": "chmod u+x Sarif.Multitool"
 	},