@microsoft/sarif-multitool-darwin 5.0.1 → 5.0.2

package/Sarif.Multitool.Library.xml

@@ -183,6 +183,18 @@
             </list>
             </remarks>
         </member>
+        <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.RepositoryUri">
+            <summary>
+            Absolute URL identifier of the source repository. Lifted from
+            <c>BUILD_REPOSITORY_URI</c> when present and well-formed; otherwise null.
+            </summary>
+        </member>
+        <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.RevisionId">
+            <summary>
+            The commit identifier (typically a 40-character SHA-1) the pipeline is building.
+            Lifted from <c>BUILD_SOURCEVERSION</c> when present and well-formed; otherwise null.
+            </summary>
+        </member>
         <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.TryDetect(Microsoft.CodeAnalysis.Sarif.Multitool.IEnvironmentVariableGetter,Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext@,System.String@)">
             <summary>
             Reads ADO predefined environment variables via <paramref name="environment"/> and
@@ -229,6 +241,24 @@
             without constructing a typed <see cref="T:Microsoft.CodeAnalysis.Sarif.Run"/>.
             </summary>
         </member>
+        <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.HasVcpFields">
+            <summary>
+            True when this context carries at least one <c>versionControlProvenance</c>
+            field (repository URI, revision id, or branch ref) lifted from the pipeline
+            environment. False indicates the VCP enrichment path is a no-op for this
+            context and callers should leave any caller-supplied VCP untouched.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext.GetVcpFieldValues">
+            <summary>
+            Returns the non-null <c>versionControlProvenance</c> field name/value pairs
+            for this pipeline context. Pairs are ordered <c>repositoryUri</c>,
+            <c>revisionId</c>, <c>branch</c>; absent fields are omitted (the caller
+            should treat the list as the set we know about). Exposed so JSON-direct
+            callers can enrich without constructing a typed
+            <see cref="T:Microsoft.CodeAnalysis.Sarif.VersionControlDetails"/>.
+            </summary>
+        </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitEventLogHelpers">
             <summary>
             Shared plumbing for the emit verb chain (<c>emit-init-run</c>, <c>add-result</c>,
@@ -374,6 +404,48 @@
             non-typed fields are durable only up to that boundary.)
             </summary>
         </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunCommand.TryStampVcp(Newtonsoft.Json.Linq.JObject,System.Uri,System.String,System.String,System.String@)">
+            <summary>
+            Enriches <c>versionControlProvenance</c> on the JSON payload with the resolved
+            repository URI / revision id / branch ref fields (sourced from the pipeline
+            environment via <see cref="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunCommand.TryResolveVcpFields(Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext,Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext,System.Uri@,System.String@,System.String@,System.String@)"/>). Three input shapes:
+            <list type="bullet">
+            <item>VCP absent or empty array → append a synthesized entry with the fields we have
+            (only when a repository URI is known; branch/revision without a repo URI anchor is
+            informationally thin and cannot bind to a repo downstream).</item>
+            <item>VCP contains exactly one entry → enrich missing fields; fail on disagreement.</item>
+            <item>VCP contains multiple entries → leave untouched (caller declared a multi-repo
+            shape; we don't pick which entry names the pipeline's source repo).</item>
+            </list>
+            <para>This method is the env-driven stamper. The verb supports a layered set of
+            VCP sources:</para>
+            <list type="number">
+            <item>ADO pipeline environment — <c>TF_BUILD=True</c> plus the
+            <c>BUILD_REPOSITORY_URI</c> / <c>BUILD_SOURCEVERSION</c> /
+            <c>BUILD_SOURCEBRANCH</c> vars supply repo URI / revision / branch directly.</item>
+            <item>GitHub Actions environment — <c>GITHUB_ACTIONS=true</c> plus
+            <c>GITHUB_SERVER_URL</c> / <c>GITHUB_REPOSITORY</c> / <c>GITHUB_SHA</c> /
+            <c>GITHUB_REF</c> supply the same fields. When both ADO and GHA vars are
+            populated, the sources must agree on every field they both publish.</item>
+            <item>Caller-supplied — if neither CI env is present, the producer populates
+            <c>versionControlProvenance</c> entries directly in the run-header JSON and the
+            verb passes them through after shape validation. Callers running outside a
+            supported CI environment can shell out to <c>git</c> themselves and either
+            populate the entry directly or stage the corresponding env vars before invoking
+            the verb.</item>
+            </list>
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunCommand.TryResolveVcpFields(Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext,Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext,System.Uri@,System.String@,System.String@,System.String@)">
+            <summary>
+            Resolves the three VCP fields (<c>repositoryUri</c>, <c>revisionId</c>,
+            <c>branch</c>) from the ADO and GitHub Actions environment contexts. ADO is the
+            higher-priority source: where ADO supplies a value it wins; GHA fills gaps where
+            ADO is silent. When both sources publish the same field, the values must agree
+            (case-insensitive URI equality for <c>repositoryUri</c>, ordinal for the rest) or
+            the method returns false with a diagnostic naming both sources.
+            </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
@@ -401,6 +473,79 @@
             place of a <c>Run</c>.</para>
             </remarks>
         </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext">
+            <summary>
+            Detects a GitHub Actions execution context from environment variables and surfaces the
+            <c>versionControlProvenance</c> fields the workflow runner publishes
+            (<c>GITHUB_SERVER_URL</c>/<c>GITHUB_REPOSITORY</c> compose the repository URI;
+            <c>GITHUB_SHA</c> supplies the revision; <c>GITHUB_REF</c> supplies the branch
+            ref).
+            </summary>
+            <remarks>
+            <para>This context is VCP-scoped: it does not stamp <c>automationDetails</c> for GitHub
+            Actions. The runner exposes <c>GITHUB_RUN_ID</c> / <c>GITHUB_WORKFLOW</c> / etc., but
+            downstream ingestion conventions for the GitHub-side automationDetails shape are out of
+            scope for this verb today.</para>
+            <para>Detection is gated on the standard runner sentinel <c>GITHUB_ACTIONS=true</c>. When
+            not inside a GitHub Actions workflow, <see cref="F:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.DetectionState.None"/> is returned and no
+            stamping occurs. Inside a workflow three states are possible:</para>
+            <list type="bullet">
+            <item><see cref="F:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.DetectionState.Complete"/> — the runner is active and every populated
+            VCP variable parses cleanly. Absent VCP variables are tolerated: in that case the context
+            is Complete but <see cref="P:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.HasVcpFields"/> returns <c>false</c> and the verb's VCP
+            stamping is a no-op for this source.</item>
+            <item><see cref="F:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.DetectionState.Partial"/> — one or more present VCP variables are
+            malformed (e.g. a non-hex <c>GITHUB_SHA</c>, an unparseable
+            <c>GITHUB_SERVER_URL</c>); the verb should fail loudly rather than stamp a half-derived
+            VCP entry.</item>
+            <item><see cref="F:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.DetectionState.None"/> — <c>GITHUB_ACTIONS</c> is unset or not
+            truthy.</item>
+            </list>
+            </remarks>
+        </member>
+        <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.RepositoryUri">
+            <summary>
+            Absolute URL of the source repository, composed from <c>GITHUB_SERVER_URL</c> and
+            <c>GITHUB_REPOSITORY</c> when both are present and well-formed; otherwise null.
+            </summary>
+        </member>
+        <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.RevisionId">
+            <summary>
+            The commit identifier (typically a 40-character SHA-1) the workflow run is building.
+            Lifted from <c>GITHUB_SHA</c> when present and well-formed; otherwise null.
+            </summary>
+        </member>
+        <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.BranchRef">
+            <summary>
+            The branch ref (e.g. <c>refs/heads/main</c>, <c>refs/pull/42/merge</c>) that
+            triggered the workflow. Lifted from <c>GITHUB_REF</c> when present; null when
+            absent. Pass-through with no normalization — the value is whatever the runner
+            (or hand-built env) published.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.TryDetect(Microsoft.CodeAnalysis.Sarif.Multitool.IEnvironmentVariableGetter,Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext@,System.String@)">
+            <summary>
+            Reads GitHub Actions predefined environment variables via
+            <paramref name="environment"/> and returns one of <see cref="T:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.DetectionState"/>.
+            </summary>
+            <param name="environment">Env getter (test seam).</param>
+            <param name="context">Populated context when state is <see cref="F:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.DetectionState.Complete"/>; otherwise <c>null</c>.</param>
+            <param name="errorMessage">Human-readable description of present/malformed variables when state is <see cref="F:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.DetectionState.Partial"/>; otherwise <c>null</c>.</param>
+        </member>
+        <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.HasVcpFields">
+            <summary>
+            True when this context carries at least one <c>versionControlProvenance</c> field
+            (repository URI, revision id, or branch ref) lifted from the workflow
+            environment. False indicates the VCP enrichment path is a no-op for this context.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext.GetVcpFieldValues">
+            <summary>
+            Returns the non-null <c>versionControlProvenance</c> field name/value pairs for this
+            workflow context. Pairs are ordered <c>repositoryUri</c>, <c>revisionId</c>,
+            <c>branch</c>; absent fields are omitted.
+            </summary>
+        </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.FileWorkItemsCommand">
             <summary>
             A class that drives SARIF work item filing. This class is responsible for

package/package.json

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