npm - @microsoft/sarif-multitool-darwin - Versions diffs - 5.0.2 → 5.0.3 - Mend

@microsoft/sarif-multitool-darwin 5.0.2 → 5.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/Sarif.Converters.pdb +0 -0
package/Sarif.Driver.pdb +0 -0
package/Sarif.Multitool +0 -0
package/Sarif.Multitool.Library.pdb +0 -0
package/Sarif.Multitool.Library.xml +323 -236
package/Sarif.Multitool.pdb +0 -0
package/Sarif.WorkItems.pdb +0 -0
package/Sarif.pdb +0 -0
package/Sarif.xml +54 -130
package/WorkItems.pdb +0 -0
package/package.json +1 -1

package/Sarif.Converters.pdb CHANGED Viewed

Binary file

package/Sarif.Driver.pdb CHANGED Viewed

Binary file

package/Sarif.Multitool CHANGED Viewed

Binary file

package/Sarif.Multitool.Library.pdb CHANGED Viewed

Binary file

package/Sarif.Multitool.Library.xml CHANGED Viewed

@@ -6,156 +6,88 @@
     <members>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddInvocationCommand">
             <summary>
-            Implements <c>multitool add-invocation</c>: appends a fully-formed SARIF invocation
+            Implements <c>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>
+            <para>The verb gates required AI invocation fields: <c>executionSuccessful</c>,
+            <c>commandLine</c>, <c>workingDirectory.uri</c>, and inline notification <c>timeUtc</c>
+            values. Full structural validation runs at <c>emit-finalize --validate</c>.</para>
+            <para>The verb stamps <c>endTimeUtc</c> with the time of receipt when the producer leaves it unset.</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>.
+            <c>emit-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).
+            The invocation is supplied as a JSON document (file via <c>--input</c> or piped on stdin).
+            Notifications travel inline on <c>toolExecutionNotifications</c> /
+            <c>toolConfigurationNotifications</c>.
             </remarks>
         </member>
-        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddNotificationCommand">
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddNotificationReportingDescriptorCommand">
             <summary>
-            Implements <c>multitool add-notification</c>: appends a fully-formed SARIF notification
-            JSON to <c>&lt;output&gt;.wip.jsonl</c>.
+            Implements <c>add-notification-reporting-descriptor</c>: validates a SARIF
+            reportingDescriptor JSON and appends it to <c>run.tool.driver.notifications[]</c> in a
+            staged event log.
             </summary>
-            <remarks>
-            <para>Unlike <see cref="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddResultCommand"/>, this verb does not enforce the AI ruleId
-            convention on the notification's <c>associatedRule.id</c> — that field references a
-            descriptor in <c>tool.driver.rules</c>, which uses the base taxonomy id (e.g.,
-            <c>CWE-79</c>) per SARIF §3.49.3, not the result-side hierarchical form.</para>
-            <para>Notifications without a <c>timeUtc</c> stamp are auto-stamped at replay time
-            (<see cref="T:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventReplayer"/>), so producers can omit that field without firing
-            AI2019 at validate time.</para>
-            </remarks>
         </member>
-        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddNotificationOptions">
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddNotificationReportingDescriptorOptions">
             <summary>
-            Options for <c>add-notification</c>, which appends a fully-formed SARIF <c>notification</c>
-            object to a staged event log (<c>&lt;output&gt;.wip.jsonl</c>) created by
-            <c>emit-init-run</c>.
+            Options for <c>add-notification-reporting-descriptor</c>, which appends a SARIF
+            <c>reportingDescriptor</c> to <c>run.tool.driver.notifications[]</c> in a staged event log
+            (<c>&lt;output&gt;.wip.jsonl</c>) created by <c>emit-run</c>.
             </summary>
             <remarks>
-            The notification is supplied as a JSON document (file via <c>--input</c> or piped on
-            stdin). AI producers are expected to emit notifications with potentially very rich data
-            — associated rule references, full exception trees, descriptive markdown messages,
-            per-call properties — so the JSON-payload contract avoids encoding-by-flag entirely and
-            preserves whatever the producer chose to express.
+            The descriptor is supplied as a JSON document (file via <c>--input</c> or piped on stdin).
+            Each <c>id</c> may appear at most once in the notifications array.
             </remarks>
         </member>
-        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddReportingDescriptorCommand">
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddResultCommand">
             <summary>
-            Implements <c>multitool add-reporting-descriptor</c>: validates a fully-formed SARIF
-            reportingDescriptor JSON and appends an event to <c>&lt;output&gt;.wip.jsonl</c>.
+            Implements <c>add-result</c>: validates a fully-formed SARIF result JSON and
+            appends a <c>result</c> event to <c>&lt;output&gt;.wip.jsonl</c>.
             </summary>
             <remarks>
-            <para>Default target is <c>run.tool.driver.notifications[]</c>; pass <c>--rules</c> to
-            target <c>run.tool.driver.rules[]</c> instead.</para>
-            <para>On the <c>--rules</c> path, the descriptor id is gated against
-            <see cref="M:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConvention.IsNovel(System.String)"/>: only NOVEL- prefixed ids are accepted.
-            Taxonomy-mapped rule descriptors (e.g., <c>CWE-89</c>) come from the taxonomy enricher
-            at finalize time, not from this verb — this verb is the producer-side authoring path
-            for novel-finding descriptors that have no upstream taxonomy entry.</para>
-            <para>Duplicate-id submissions within the same event log are rejected on receipt — the
-            verb scans the existing event log (including any descriptors pre-populated on the
-            run-header event) and fails before appending. (A future <c>--force</c> escape hatch
-            is acknowledged; not in v1.)</para>
+            The result's <c>ruleId</c> is validated at receipt against the AI ruleId convention
+            (taxonomy sub-id form or NOVEL- escape hatch). On rejection the verb writes the
+            AI-consumable error envelope (error code AI-RULEID-001) to stderr and returns
+            <see cref="F:Microsoft.CodeAnalysis.Sarif.Driver.CommandBase.FAILURE"/> WITHOUT appending — an AI orchestrator can retry the
+            individual result without first having to remove garbage from the event log.
             </remarks>
         </member>
-        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.AddReportingDescriptorCommand.TryFindDuplicate(System.String,System.String,System.String,System.String,System.String@)">
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddResultOptions">
             <summary>
-            Scans the staged event log for a prior descriptor with the same id targeting the
-            same array. Returns <c>true</c> with <paramref name="error"/> populated when a
-            duplicate is found; <c>false</c> otherwise.
+            Options for <c>add-result</c>, which appends a fully-formed SARIF <c>result</c> object
+            to a staged event log (<c>&lt;output&gt;.wip.jsonl</c>) created by <c>emit-run</c>.
             </summary>
             <remarks>
-            Two sources are checked:
-            <list type="bullet">
-            <item><description>Run-header events: <c>payload.tool.driver.&lt;targetArray&gt;[*].id</c>
-            — producers MAY pre-populate descriptors on the header.</description></item>
-            <item><description>Prior descriptor events of the same target kind:
-            <c>payload.id</c>.</description></item>
-            </list>
-            The reader silently skips unknown kinds and malformed-but-skippable rows; for the
-            scan we walk the full event sequence so the event index reported in the error
-            matches the producer's mental model of "the Nth thing I appended."
+            The result is supplied as a JSON document (file via <c>--input</c> or piped on stdin).
+            On receipt the verb validates <c>result.ruleId</c> against the AI ruleId convention.
             </remarks>
         </member>
-        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddReportingDescriptorOptions">
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddRuleReportingDescriptorCommand">
             <summary>
-            Options for <c>add-reporting-descriptor</c>, which appends a fully-formed SARIF
-            <c>reportingDescriptor</c> object to a staged event log
-            (<c>&lt;output&gt;.wip.jsonl</c>) created by <c>emit-init-run</c>.
+            Implements <c>add-rule-reporting-descriptor</c>: validates a SARIF
+            reportingDescriptor JSON with a <c>NOVEL-</c> id and appends it to
+            <c>run.tool.driver.rules[]</c> in a staged event log.
             </summary>
-            <remarks>
-            <para>The verb's default target is <c>run.tool.driver.notifications[]</c> — AI producers
-            routinely emit notification descriptors (progress, telemetry, config errors, handoff
-            breadcrumbs). Pass <c>--rules</c> to target <c>run.tool.driver.rules[]</c> instead;
-            this rule-descriptor path is reserved for NOVEL- novel-finding descriptors (taxonomy
-            rule descriptors such as <c>CWE-89</c> come from the taxonomy enricher, not this
-            verb).</para>
-            <para>The descriptor is supplied as a JSON document (file via <c>--input</c> or piped
-            on stdin). The full SARIF reportingDescriptor shape (id, name, shortDescription,
-            fullDescription, helpUri, messageStrings, defaultConfiguration, properties, …)
-            round-trips byte-for-byte through the staged event log.</para>
-            <para>Each descriptor <c>id</c> may appear at most once per event log. Submitting a
-            duplicate id is rejected with a clear error pointing at the prior occurrence.</para>
-            </remarks>
         </member>
-        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddResultCommand">
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddRuleReportingDescriptorOptions">
             <summary>
-            Implements <c>multitool add-result</c>: validates a fully-formed SARIF result JSON and
-            appends a <c>result</c> event to <c>&lt;output&gt;.wip.jsonl</c>.
+            Options for <c>add-rule-reporting-descriptor</c>, which appends a SARIF
+            <c>reportingDescriptor</c> to <c>run.tool.driver.rules[]</c> in a staged event log
+            (<c>&lt;output&gt;.wip.jsonl</c>) created by <c>emit-run</c>.
             </summary>
             <remarks>
-            The result's <c>ruleId</c> is validated at receipt against the AI ruleId convention
-            (taxonomy sub-id form or NOVEL- escape hatch). On rejection the verb writes the
-            AI-consumable error envelope (error code AI-RULEID-001) to stderr and returns
-            <see cref="F:Microsoft.CodeAnalysis.Sarif.Driver.CommandBase.FAILURE"/> WITHOUT appending — an AI orchestrator can retry the
-            individual result without first having to remove garbage from the event log.
+            Reserved for novel-finding rules: the descriptor <c>id</c> must be a well-formed
+            <c>NOVEL-</c> id. Descriptors for taxonomy-mapped rules (e.g., <c>CWE-89</c>) come from the
+            taxonomy enricher, not this verb. Each <c>id</c> may appear at most once in the rules array.
             </remarks>
         </member>
-        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AddResultOptions">
-             <summary>
-             Options for <c>add-result</c>, which appends a fully-formed SARIF <c>result</c> object
-             to a staged event log (<c>&lt;output&gt;.wip.jsonl</c>) created by <c>emit-init-run</c>.
-             </summary>
-             <remarks>
-             The result is supplied as a JSON document (file via <c>--input</c> or piped on stdin).
-             The SARIF <c>result</c> object can carry rich nested structures (code flows, thread flows,
-             stacks, fixes, taxa, related locations, properties bags). Modeling every field as a CLI
-             flag would explode the surface; the JSON-payload contract keeps the verb generic and lets
-             an AI producer emit arbitrarily-rich findings without losing fidelity.
-             On receipt the verb validates that <c>result.ruleId</c> conforms to the AI ruleId
-             convention (taxonomy sub-id form or NOVEL- escape hatch) so an AI orchestrator gets an
-             immediate, AI-consumable rejection envelope rather than discovering the violation later
-             at <c>emit-finalize</c> time.
-             </remarks>
-        </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext">
             <summary>
             Detects an Azure DevOps pipeline execution context from environment variables and stamps
@@ -216,7 +148,7 @@
             </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
+            callers (notably <c>emit-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>
@@ -261,15 +193,15 @@
         </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>,
-            <c>add-notification</c>, <c>emit-finalize</c>): resolves the staged event log path,
-            reads caller-supplied JSON (file or stdin), and parses it into a
-            <see cref="T:Newtonsoft.Json.Linq.JToken"/> in a date-safe way.
+            Shared plumbing for the emit verb chain (<c>emit-run</c>, <c>add-result</c>,
+            <c>add-invocation</c>, <c>add-notification-reporting-descriptor</c>,
+            <c>add-rule-reporting-descriptor</c>, <c>emit-finalize</c>): resolves
+            the staged event log path, reads caller-supplied JSON (file or stdin), and parses it into
+            a <see cref="T:Newtonsoft.Json.Linq.JToken"/> in a date-safe way.
             </summary>
             <remarks>
-            The verbs share three concerns — locating <c>&lt;output&gt;.wip.jsonl</c>, sourcing
-            the payload, and parsing it without lossy normalization — which live here so the
-            per-verb commands can stay focused on payload-specific validation and append.
+            Shared helpers preserve payload text, including date-looking strings, until the staged
+            event log is finalized.
             </remarks>
         </member>
         <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitEventLogHelpers.TryValidateUri(System.String,System.String,System.String[],System.String@)">
@@ -278,12 +210,8 @@
             absolute URI whose scheme appears in <paramref name="allowedSchemes"/>.
             </summary>
             <remarks>
-            Returning <c>true</c> when the value is empty preserves the "flag is optional"
-            contract — only supplied URIs are validated. We require an absolute URI (relative
-            values would never resolve meaningfully into a SARIF reader downstream) and we
-            constrain the scheme to a documented allow-list so a typo like <c>"htps://..."</c>
-            or an inappropriate scheme like <c>"file:..."</c> on a public-facing URL surfaces
-            here rather than silently shipping in the run header.
+            Empty values are accepted because the corresponding flags are optional. Non-empty
+            values must be absolute and use an allowed scheme.
             </remarks>
         </member>
         <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitEventLogHelpers.TryResolveWipPath(System.String,Microsoft.CodeAnalysis.Sarif.IFileSystem,System.String@)">
@@ -312,18 +240,13 @@
         </member>
         <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitEventLogHelpers.ReadStandardInputAsUtf8">
             <summary>
-            Reads redirected stdin as UTF-8, bypassing <see cref="P:System.Console.InputEncoding"/>.
-            On Windows the console's default input encoding is the active OEM codepage
-            (often cp437 or cp850), which would mangle non-ASCII content in a piped
-            SARIF payload. AI orchestrators routinely emit messages, URIs, and properties
-            containing non-ASCII characters, so we must decode the raw byte stream as UTF-8
-            regardless of the console's current code page. A BOM-stamped input is still
-            honored — <see cref="T:System.IO.StreamReader"/>'s detect-BOM flag handles that case.
+            Reads redirected stdin as UTF-8, bypassing <see cref="P:System.Console.InputEncoding"/> so
+            Windows OEM codepages cannot mangle non-ASCII SARIF payloads. A UTF-8 BOM is honored.
             </summary>
         </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitFinalizeCommand">
             <summary>
-            Implements <c>multitool emit-finalize</c>: replays <c>&lt;output&gt;.wip.jsonl</c>,
+            Implements <c>emit-finalize</c>: replays <c>&lt;output&gt;.wip.jsonl</c>,
             optionally enriches CWE-as-rule-id descriptors, and atomically writes the destination
             SARIF file.
             </summary>
@@ -341,15 +264,41 @@
             writes the destination SARIF file.
             </summary>
         </member>
-        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunCommand">
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitFinalizeRebaseVisitor">
+            <summary>
+            Rewrites absolute local file paths in a run into relative URIs plus portable, per-repository
+            <c>uriBaseId</c>s derived from <c>versionControlProvenance</c>. Each artifact location is
+            resolved against the run's input <c>originalUriBaseIds</c>, attributed to the owning
+            repository by longest-prefix match on the mapped local root, and re-expressed relative to
+            that repository's minted output base. The rebuilt <c>originalUriBaseIds</c> anchor each base
+            at a portable root — a GitHub-compatible blob permalink (commit-pinned in the URL) or an Azure
+            DevOps repository root (commit pinning carried by <c>versionControlProvenance.revisionId</c>),
+            derived from the repositoryUri by <see cref="T:Microsoft.CodeAnalysis.Sarif.Multitool.VcpPortableRoot"/> — so the finalized SARIF
+            carries no machine-specific path.
+            </summary>
+            <remarks>
+            One repository collapses to the bare <c>SRCROOT</c> base. Multiple repositories each receive
+            <c>SRCROOT_&lt;REPO-LEAF&gt;</c>, disambiguated by an ordinal suffix on collision. A result URI
+            that resolves to a local file path under no declared repository root fails finalize (it would
+            leak); an unmatched URI under a portable scheme is inlined as an absolute reference.
+            </remarks>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInputOptionsBase">
+            <summary>
+            Shared options for the emit verbs that append a JSON object to a staged event log: the
+            destination SARIF path and the JSON input (file or stdin).
+            </summary>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitRunCommand">
             <summary>
-            Implements <c>multitool emit-init-run</c>: creates an append-only SARIF event log
+            Implements <c>emit-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 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
+            <c>add-invocation</c>, <c>add-notification-reporting-descriptor</c>,
+            <c>add-rule-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>,
@@ -385,92 +334,53 @@
             </list>
             </remarks>
         </member>
-        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunCommand.TryRequireOptionalObject(Newtonsoft.Json.Linq.JObject,System.String,Newtonsoft.Json.Linq.JObject@)">
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitRunCommand.TryValidateVcpRepositoryShapes(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.
+            Confirms that every present <c>versionControlProvenance[].repositoryUri</c> has a shape
+            from which <see cref="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitFinalizeRebaseVisitor"/> can later derive a portable root. Runs
+            after header validation (which proves each value is an absolute https URI) and after env
+            stamping, so both caller-supplied and stamped entries are covered. Entries without a
+            repositoryUri are left to the finalize-time contract.
             </summary>
         </member>
-        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunCommand.TryStampAdoContext(Newtonsoft.Json.Linq.JObject,Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext,System.String@)">
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitRunCommand.TryRequireOptionalObject(Newtonsoft.Json.Linq.JObject,System.String,Newtonsoft.Json.Linq.JObject@)">
             <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.)
+            Requires an optional token to be null/absent or a JSON object; returns the object via
+            <paramref name="value"/>.
             </summary>
         </member>
-        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunCommand.TryStampVcp(Newtonsoft.Json.Linq.JObject,System.Uri,System.String,System.String,System.String@)">
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitRunCommand.TryStampAdoContext(Newtonsoft.Json.Linq.JObject,Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext,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>
+            Stamps ADO pipeline identity directly onto the JSON payload, preserving fields not
+            surfaced by the typed <see cref="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitRunCommand.Run(Microsoft.CodeAnalysis.Sarif.Multitool.EmitRunOptions,Microsoft.CodeAnalysis.Sarif.IFileSystem)"/> model.
             </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@)">
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitRunCommand.TryStampVcp(Newtonsoft.Json.Linq.JObject,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.
+            Enriches <c>versionControlProvenance</c> with resolved repository URI, revision id,
+            and branch fields. Empty VCP arrays receive a synthesized entry only when a repository
+            URI is known; single-entry arrays are enriched; multi-entry arrays are left untouched.
             </summary>
         </member>
-        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitInitRunOptions">
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.EmitRunCommand.TryResolveVcpFields(Microsoft.CodeAnalysis.Sarif.Multitool.AdoPipelineContext,Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext,System.Uri@,System.String@,System.String@,System.String@)">
             <summary>
-            Options for <c>emit-init-run</c>, which opens an append-only event log
+            Resolves VCP fields from ADO and GitHub Actions contexts. ADO seeds each field; GHA
+            fills only the fields ADO left empty. Any field both sources publish must agree, or
+            stamping is refused.
+            </summary>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitRunOptions">
+            <summary>
+            Options for <c>emit-run</c>, which opens an append-only event log
             (<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>.
+            log via the SARIF emit API and finalize via <c>emit-finalize</c>.
             </summary>
             <remarks>
             <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>
+            stdin) and may contain any partial-<c>Run</c> fields the replayer accepts.</para>
+            <para>Profile-essential defects are validated at receipt: required <c>tool.driver.name</c>,
+            URI schemes, canonical GUIDs, <c>properties["ai/origin"]</c>, and accidental SARIF-log input.</para>
             </remarks>
         </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.GitHubActionsContext">
@@ -546,6 +456,85 @@
             <c>branch</c>; absent fields are omitted.
             </summary>
         </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.ReportingDescriptorEmitter">
+            <summary>
+            Shared implementation behind <c>add-notification-reporting-descriptor</c> and
+            <c>add-rule-reporting-descriptor</c>: validates a SARIF reportingDescriptor JSON and
+            appends an event to <c>&lt;output&gt;.wip.jsonl</c>.
+            </summary>
+            <remarks>
+            Notifications append to <c>run.tool.driver.notifications[]</c>; rules append to
+            <c>run.tool.driver.rules[]</c> and require a well-formed <c>NOVEL-</c> id. Each id may
+            appear at most once in its target array.
+            </remarks>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.ReportingDescriptorEmitter.TryFindDuplicate(System.String,System.String,System.String,System.String,System.String@)">
+            <summary>
+            Scans the staged event log for a prior descriptor with the same id targeting the
+            same array. Returns <c>true</c> with <paramref name="error"/> populated when a
+            duplicate is found; <c>false</c> otherwise.
+            </summary>
+            <remarks>
+            The event index in the error matches the event's position in the staged log.
+            </remarks>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.VcpPortableRoot">
+            <summary>
+            Single source of truth for turning a <c>versionControlProvenance.repositoryUri</c> into a
+            portable artifact root. <see cref="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitFinalizeRebaseVisitor"/> mints the root at finalize;
+            <see cref="T:Microsoft.CodeAnalysis.Sarif.Multitool.EmitRunCommand"/> validates the repositoryUri shape at receipt so a producer learns
+            of a malformed value at authorship rather than after a full run is assembled.
+            </summary>
+            <remarks>
+            Two repository families are recognized:
+            <list type="bullet">
+            <item><description>
+            Azure DevOps: <c>dev.azure.com</c> only, in the exact form
+            <c>https://dev.azure.com/&lt;org&gt;/&lt;project&gt;/_git/&lt;repo&gt;</c>. The portable root is
+            the repository root; commit pinning rides on <c>versionControlProvenance.revisionId</c>
+            because Azure DevOps per-file web URLs are query-based
+            (<c>?path=&amp;version=GC&lt;sha&gt;</c>) and cannot serve as a uriBaseId prefix. The legacy
+            <c>&lt;org&gt;.visualstudio.com</c> form is rejected; callers must supply the dev.azure.com
+            URL, and the derived root is always emitted in that form.
+            </description></item>
+            <item><description>
+            GitHub: <c>github.com</c> (public OSS and Enterprise Managed Users on dotcom) and the
+            data-residency / EMU hosts <c>&lt;slug&gt;.ghe.com</c>, each with a two-segment
+            <c>&lt;owner&gt;/&lt;repo&gt;</c> path. The portable root is a commit-pinned blob permalink
+            (<c>https://&lt;host&gt;/&lt;owner&gt;/&lt;repo&gt;/blob/&lt;revisionId&gt;/</c>). The host set
+            is an allow-list: any other host is rejected so a confidently-wrong link is never minted.
+            Custom-hostname GitHub Enterprise Server deployments are out of scope.
+            </description></item>
+            </list>
+            SSH and scp-style clone URLs for the GitHub family are normalized to https first. Azure DevOps
+            SSH normalization is not supported; such a repositoryUri is rejected with a pointer to the
+            https clone URL. The derivation also yields a canonical repositoryUri — the https identity with
+            any userinfo stripped — so a credential-bearing or ssh clone URL never ships in the finalized
+            run.
+            </remarks>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.VcpPortableRoot.TryValidateRepositoryUri(System.Uri,System.String@,System.String@)">
+            <summary>
+            Validates that <paramref name="rawRepositoryUri"/> has a shape from which a portable root
+            can be derived, without minting one (no revisionId required). Used at emit-run receipt.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.VcpPortableRoot.TryGetAzureDevOpsTarget(System.Uri,System.String@,System.String@,System.String@,System.String@)">
+            <summary>
+            Resolves the Azure DevOps organization, project, and repository from
+            <paramref name="rawRepositoryUri"/>, applying the same host and credential guards as
+            portable-root derivation. Fails when the repository is not an Azure DevOps target. The
+            coordinates are URL-path escaped, ready to compose into a REST endpoint path.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.VcpPortableRoot.TryDerivePortableRoot(System.Uri,System.String,System.Uri@,System.Uri@,System.String@,System.String@)">
+            <summary>
+            Mints the portable root for <paramref name="rawRepositoryUri"/>. Used at emit-finalize.
+            <paramref name="canonicalRepositoryUri"/> is the clean https identity (userinfo stripped,
+            ssh/scp normalized) that should be written back onto the run so the finalized SARIF never
+            ships a credential-bearing or non-https repositoryUri.
+            </summary>
+        </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.FileWorkItemsCommand">
             <summary>
             A class that drives SARIF work item filing. This class is responsible for
@@ -558,6 +547,91 @@
             SarifWorkItemFiler in order to complete the work.
             </summary>
         </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.GetSchemaCommand">
+            <summary>
+            Implements <c>get-schema</c>: emits the embedded JSON Schema that validates the
+            input to a named emit verb.
+            </summary>
+            <remarks>
+            The served bytes are the assembly's embedded resources, byte-identical to the schema files
+            under <c>GetSchema/</c>.
+            </remarks>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.Multitool.GetSchemaCommand.SchemaByVerb">
+            <summary>
+            Maps each emit verb to the embedded schema file that validates its input. A null value
+            marks a verb whose schema is reserved but not yet available.
+            </summary>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.GetSchemaOptions">
+            <summary>
+            Options for <c>get-schema</c>, which emits the JSON Schema that validates the input to a
+            named emit verb. The schema is written verbatim to stdout, or to <c>--output</c>.
+            </summary>
+            <remarks>
+            The schemas served here are the same bytes the emit verbs validate their inputs against,
+            so a producer can fetch the contract for the exact verb it is about to call.
+            </remarks>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.GetSkillCommand">
+            <summary>
+            Implements <c>get-skill</c>: emits an embedded agent skill that drives the multitool emit and
+            validate verbs.
+            </summary>
+            <remarks>
+            The source skill under <c>skills/</c> links its references with repository-relative paths so it
+            renders correctly in the repo. On the way out those links are rewritten to raw permalinks pinned
+            to the build commit SHA, so the emitted skill resolves its references against the exact
+            repository state that shipped the running tool.
+            </remarks>
+        </member>
+        <member name="F:Microsoft.CodeAnalysis.Sarif.Multitool.GetSkillCommand.SkillSourceDirectory">
+            <summary>
+            Maps each skill to the repository-relative directory of its <c>SKILL.md</c>. The directory
+            anchors resolution of the skill's repository-relative links into release-pinned permalinks.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.GetSkillCommand.ResolvePinRef(System.String,System.Version)">
+            <summary>
+            Resolves the git ref the skill's links are pinned to. Prefers the exact build commit SHA
+            that SourceLink stamps into the assembly informational version (<c>&lt;version&gt;+&lt;sha&gt;</c>),
+            so the emitted links resolve to the precise repository state that shipped the running tool —
+            the same tree the embedded skill was taken from. Falls back to the version tag when no SHA
+            is stamped (e.g. a build with no git metadata).
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.GetSkillCommand.ResolveReleaseTag(System.Version)">
+            <summary>
+            Derives the version tag (e.g. <c>v5.0.2</c>) from the assembly version, which tracks the
+            package's <c>VersionPrefix</c>. Used only as a fallback when no build commit SHA is
+            available to pin against.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.GetSkillCommand.RewriteRelativeLinks(System.String,System.String,System.String)">
+            <summary>
+            Rewrites every repository-relative markdown link in <paramref name="markdown"/> to a raw
+            permalink pinned to <paramref name="pinRef"/>. Absolute URLs, protocol-relative URLs, and
+            bare fragments are left untouched.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.GetSkillCommand.ResolveRepositoryRelative(System.String,System.String)">
+            <summary>
+            Resolves a relative path against the skill's repository directory into a repository-root
+            path, collapsing <c>.</c> and <c>..</c> segments.
+            </summary>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.GetSkillOptions">
+            <summary>
+            Options for <c>get-skill</c>, which emits an agent skill that drives the multitool emit and
+            validate verbs. The skill markdown is written to stdout, or to <c>--output</c>.
+            </summary>
+            <remarks>
+            The skill ships embedded in the package, so an agent that resolves the tool (for example via
+            <c>dotnet dnx</c>) obtains the procedure from the same artifact it runs. Relative links in the
+            source skill are rewritten to commit-pinned permalinks on the way out, so the emitted document
+            resolves its references against the exact repository state that built the tool.
+            </remarks>
+        </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.MultitoolResources">
             <summary>
               A strongly-typed resource class, for looking up localized strings, etc.
@@ -641,6 +715,37 @@
                inline: We build a map of the input, so we don't want to write inline and immediately invalidate it.
             </remarks>
         </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.PublishToGhazdoCommand">
+            <summary>
+            Implements <c>publish-to-ghazdo</c>: uploads a SARIF file to GitHub Advanced Security for
+            Azure DevOps. The target organization, project, and repository are derived from the run's
+            <c>versionControlProvenance</c>, and the bearer secret is read from an environment variable
+            named by <c>--token-env-var</c> so it never appears on the command line or in diagnostics.
+            </summary>
+            <remarks>
+            The secret kind selects the authorization scheme: an Entra access token is a JSON Web Token and
+            is sent as <c>Bearer</c>; an Azure DevOps personal access token is opaque and is sent as
+            <c>Basic</c> with an empty user name. The body is gzip-compressed in memory and posted as
+            <c>application/octet-stream</c> with no <c>Content-Encoding</c> header, because the ingestion
+            endpoint gunzips the payload itself. The upload targets <c>advsec.dev.azure.com</c> and falls
+            back to <c>dev.azure.com</c> on a 404.
+            </remarks>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.PublishToGhazdoCommand.DetectScheme(System.String)">
+            <summary>
+            Selects the authorization scheme for <paramref name="secret"/>. An Entra access token is a
+            JSON Web Token (<c>Bearer</c>); an opaque Azure DevOps personal access token is wrapped as
+            <c>Basic</c> with an empty user name.
+            </summary>
+        </member>
+        <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.PublishToGhazdoOptions">
+            <summary>
+            Options for <c>publish-to-ghazdo</c>, which uploads a finalized SARIF file to GitHub Advanced
+            Security for Azure DevOps. The Azure DevOps target is derived from the run's version-control
+            provenance, and the bearer secret is read from an environment variable named by
+            <c>--token-env-var</c>, never from the command line.
+            </summary>
+        </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Multitool.QueryOptions">
             <summary>
              Options for the 'Query' command, which runs a query expression on a SARIF file
@@ -667,14 +772,14 @@
             AI1006
             </summary>
         </member>
-        <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.Rules.ProvideEvidenceBackingUri.Id">
+        <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.Rules.DoNotPersistFingerprints.Id">
             <summary>
-            AI1010
+            AI1007
             </summary>
         </member>
-        <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.Rules.RedactedRunMarker.Id">
+        <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.Rules.ProvideEvidenceBackingUri.Id">
             <summary>
-            AI1011
+            AI1010
             </summary>
         </member>
         <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.Rules.ProvideRuleSubId.Id">
@@ -702,7 +807,7 @@
             AI2010
             </summary>
         </member>
-        <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.Rules.DoNotPersistFingerprints.Id">
+        <member name="P:Microsoft.CodeAnalysis.Sarif.Multitool.Rules.DoNotPersistPartialFingerprints.Id">
             <summary>
             AI2011
             </summary>
@@ -2338,40 +2443,22 @@
             <returns></returns>
         </member>
         <member name="F:Microsoft.CodeAnalysis.Sarif.Multitool.Rules.SarifValidationSkimmerBase.AIOriginPropertyName">
-             <summary>
-             The well-known run property whose presence (with any non-null/non-empty
-             value) declares that the containing run was produced by an AI emitter.
-             AI-emitted SARIF is stochastic by construction — message text is rendered
-             per-result rather than authored against a table of <c>messageStrings</c>
-             templates, and rule ids ride the <c>NOVEL-</c> / <c>BASE/sub-id</c>
-             convention rather than a fixed tool prefix. Style-class validation rules
-             (e.g. SARIF2002, SARIF2009, SARIF2014, SARIF2015) encode human-authoring
-             guidance whose preconditions don't hold for AI output, so they suppress
-             themselves when this marker is set.
-             Correctness-class rules (snippets, hashes, provenance, relative URIs, etc.)
-             must NOT consult this marker — those checks apply uniformly to AI content.
-             </summary>
+            <summary>
+            Run property whose non-empty value declares AI-origin SARIF. Style-class validation
+            rules may suppress human-authoring guidance when this marker is set; correctness-class
+            rules (snippets, hashes, provenance, relative URIs, etc.) must not.
+            </summary>
         </member>
         <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.Rules.SarifValidationSkimmerBase.IsAIOriginRun(Microsoft.CodeAnalysis.Sarif.Run)">
             <summary>
-            Returns true when <paramref name="run"/> declares AI provenance via the
-            <c>ai/origin</c> run property. Any non-null/non-empty value counts; the
-            vocabulary (<c>generated</c>, <c>annotated</c>, <c>synthesized</c>, …)
-            is open by design so AI tooling can self-describe at any granularity.
+            Returns true when <paramref name="run"/> declares AI provenance via a non-empty
+            <c>ai/origin</c> run property.
             </summary>
-            <exception cref="T:System.ArgumentNullException">
-            <paramref name="run"/> is null. Callers reading AI-origin during rule
-            dispatch should already hold a non-null run; the strict contract makes
-            upstream lifecycle bugs loud rather than masking them as "not AI".
-            </exception>
+            <exception cref="T:System.ArgumentNullException"><paramref name="run"/> is null.</exception>
         </member>
         <member name="M:Microsoft.CodeAnalysis.Sarif.Multitool.Rules.SarifValidationSkimmerBase.IsAIOriginRun">
             <summary>
-            Instance convenience: reports whether the run currently being visited
-            declares AI provenance. Returns false when there is no current run
-            scope (e.g. an <c>Analyze(SarifLog)</c> dispatch); otherwise defers to
-            <see cref="M:Microsoft.CodeAnalysis.Sarif.Multitool.Rules.SarifValidationSkimmerBase.IsAIOriginRun(Microsoft.CodeAnalysis.Sarif.Run)"/>.
+            Reports whether the run currently being visited declares AI provenance.
             </summary>
         </member>
     </members>

package/Sarif.Multitool.pdb CHANGED Viewed

Binary file

package/Sarif.WorkItems.pdb CHANGED Viewed

Binary file

package/Sarif.pdb CHANGED Viewed

Binary file

package/Sarif.xml CHANGED Viewed

@@ -6871,38 +6871,21 @@
             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>
+            <para>Accepted ruleId 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>
+            <item><description><c>CWE-&lt;number&gt;/&lt;sub-id&gt;</c>, where <c>sub-id</c> is lowercase
+            alphanumeric kebab-case; for example, <c>CWE-89/kql-injection-from-config</c>.</description></item>
+            <item><description><c>NOVEL-&lt;sub-id&gt;</c> for findings with no CWE mapping; the
+            NOVEL- form is flat and does not accept a slash.</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>
+            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.
+            prefix; the full grammar is enforced by <see cref="M:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConvention.IsAcceptable(System.String)"/>.
             </summary>
         </member>
         <member name="M:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConvention.IsAcceptable(System.String)">
@@ -6914,16 +6897,13 @@
         <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.
+            does not conform.
             </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.
+            Throws a single <see cref="T:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConventionException"/> listing every result whose
+            <see cref="P:Microsoft.CodeAnalysis.Sarif.Result.RuleId"/> violates the convention.
             </summary>
         </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConventionException">
@@ -6932,13 +6912,9 @@
             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>
+            The exception message lists every offending id, the accepted shapes, and the
+            documentation pointer. <see cref="P:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConventionException.OffendingRuleIds"/> exposes the same ids for
+            programmatic consumers.
             </remarks>
         </member>
         <member name="F:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConventionException.ErrorCode">
@@ -7010,45 +6986,24 @@
             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.
+            A complete <see cref="F:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventKinds.Invocation"/> object. Producer-supplied <see cref="T:Microsoft.CodeAnalysis.Sarif.Notification"/>
+            objects travel inline on the invocation's <c>toolExecutionNotifications</c> /
+            <c>toolConfigurationNotifications</c> arrays.
             </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.
+            A <see cref="T:Microsoft.CodeAnalysis.Sarif.ReportingDescriptor"/> targeted at <c>run.tool.driver.rules</c>.
+            Explicit descriptors are merged before result-driven auto-registration and are
+            reserved for NOVEL- ruleIds.
             </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.
+            A <see cref="T:Microsoft.CodeAnalysis.Sarif.ReportingDescriptor"/> targeted at <c>run.tool.driver.notifications</c>.
+            Notification descriptor ids are opaque non-empty strings.
             </summary>
         </member>
         <member name="F:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventKinds.CurrentSchemaVersion">
@@ -7075,8 +7030,7 @@
         </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.
+            Streams events from the given path.
             </summary>
         </member>
         <member name="T:Microsoft.CodeAnalysis.Sarif.Emit.SarifEventLogWriter">
@@ -7123,35 +7077,13 @@
             <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>
+            Header <c>results</c>, <c>invocations</c>, and <c>notifications</c> are ignored.</description></item>
+            <item><description><c>result</c> events MUST be self-contained. <c>ruleIndex</c> is
+            re-derived from <c>ruleId</c>, and every <see cref="P:Microsoft.CodeAnalysis.Sarif.Result.RuleId"/> MUST conform to
+            <see cref="T:Microsoft.CodeAnalysis.Sarif.Emit.AIRuleIdConvention"/>.</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>
+            event order and replayed verbatim.</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)">
@@ -7178,26 +7110,16 @@
             <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>
+            Header entries are preserved by reference, and descriptor events are appended after
+            them. For rules, 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 explicit descriptors seed the <c>idToIndex</c> table.
             </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">
             <summary>
-            This class is a file cache that can be used to populate
-            regions with comprehensive data, to retrieve file text
-            associated with a SARIF log, and to construct text
-            snippets associated with region instances.
+            Caches file text, hashes, newline indexes, and region snippets for SARIF enrichment.
             </summary>
         </member>
         <member name="P:Microsoft.CodeAnalysis.Sarif.FileRegionsCache.HashAlgorithms">
@@ -7228,15 +7150,14 @@
             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)">
+        <member name="M:Microsoft.CodeAnalysis.Sarif.FileRegionsCache.PopulateTextRegionProperties(Microsoft.CodeAnalysis.Sarif.Region,System.Uri,System.Boolean,System.String,System.Boolean)">
             <summary>
             Creates a <see cref="T:Microsoft.CodeAnalysis.Sarif.Region"/> object, based on an existing Region, in which all
             text-related properties have been populated.
             </summary>
             <remarks>
-            For example, if the input Region specifies only the StartLine property, the returned
-            Region instance will have computed and populated other text-related properties, such
-            as properties, such as CharOffset, CharLength, etc.
+            For example, a region with only <see cref="P:Microsoft.CodeAnalysis.Sarif.Region.StartLine"/> can receive computed
+            <see cref="P:Microsoft.CodeAnalysis.Sarif.Region.CharOffset"/> and <see cref="P:Microsoft.CodeAnalysis.Sarif.Region.CharLength"/> values.
             </remarks>
             <param name="inputRegion">
             Region object that forms the basis of the returned Region object.
@@ -7252,6 +7173,12 @@
             An optional argument that, if present, contains the text contents of the file
             specified by <paramref name="uri"/>.
             </param>
+            <param name="overwriteExistingData">
+            Controls how an authored region coordinate that diverges from the value computed
+            from the source text is reconciled. When <c>false</c> (the default), the divergence
+            throws an <see cref="T:System.ArgumentException"/>; when <c>true</c>, the authored value is
+            overwritten with the computed value.
+            </param>
             <returns>
             A Region object whose text-related properties have been fully populated.
             </returns>
@@ -7261,12 +7188,18 @@
             Clear current cache.
             </summary>
         </member>
-        <member name="M:Microsoft.CodeAnalysis.Sarif.FileRegionsCache.BuildIndexForFile(System.String)">
+        <member name="M:Microsoft.CodeAnalysis.Sarif.FileRegionsCache.ReconcileRegionCoordinate(System.Boolean,System.String,System.Int32,System.Int32)">
             <summary>
-             Method to build cache entries which aren't already in the cache.
+            Reconciles an authored region coordinate against the value computed from the source
+            text. If they agree (including the common case where the value was just computed and
+            assigned because the authored value was absent), the value is returned unchanged.
+            On a genuine divergence the behavior depends on <paramref name="overwriteExistingData"/>.
+            </summary>
+        </member>
+        <member name="M:Microsoft.CodeAnalysis.Sarif.FileRegionsCache.ReconcileRegionBounds(System.Boolean,System.Int32,System.Int32,System.Int32)">
+            <summary>
+            Reconciles an authored region whose character span extends beyond the source file.
             </summary>
-            <param name="path">Uri.LocalPath for the file to load</param>
-            <returns>Cache entry to add to cache with file contents and NewLineIndex</returns>
         </member>
         <member name="M:Microsoft.CodeAnalysis.Sarif.FileSearcherHelper.SearchForFileInEnvironmentVariable(System.String,System.String,Microsoft.CodeAnalysis.Sarif.IFileSystem)">
             <summary>
@@ -9919,16 +9852,9 @@
             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>
+            <para>Producer-supplied descriptor fields are never overwritten.</para>
+            <para>This enricher does not add cross-references via
+            <c>reportingDescriptor.relationships</c> or <c>result.taxa</c>.</para>
             </remarks>
         </member>
         <member name="M:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweTaxonomyEnricher.Enrich(Microsoft.CodeAnalysis.Sarif.Run,Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus)">
@@ -9939,9 +9865,7 @@
             <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.
+            (<c>Stable | Draft | Incomplete</c>), which excludes <see cref="F:Microsoft.CodeAnalysis.Sarif.Taxonomies.CweStatus.Deprecated"/>.
             </param>
             <returns>The number of descriptors whose content was modified.</returns>
         </member>

package/WorkItems.pdb CHANGED Viewed

Binary file

package/package.json CHANGED Viewed

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