@microsoft/sarif 0.0.1 → 5.2.0

package/README.md

@@ -1,14 +1,83 @@
 # @microsoft/sarif
 
-SARIF SDK for Node.js — native-TypeScript open-typed object model, region/snippet
-resolution, AI ruleId convention, and serialization helpers. No CLR dependency.
+SARIF SDK for Node.js — the base layer that
+[`@microsoft/sarif-multitool-ts`](https://www.npmjs.com/package/@microsoft/sarif-multitool-ts)
+and third-party SARIF producers build on. Native TypeScript; **no CLR
+dependency.**
 
-> **v0.0.x is a placeholder** that reserves the package name and proves the
-> publish pipeline. The implementation lands in a subsequent release; track
-> progress at https://github.com/microsoft/sarif-sdk.
+## What's here
 
-This is the base package. For the multitool verbs (`emit-*`, `get-*`,
-`validate`) see [`@microsoft/sarif-multitool-ts`](https://www.npmjs.com/package/@microsoft/sarif-multitool-ts).
+| | Ported from |
+|---|---|
+| **Open-typed SARIF 2.1.0 object model** — every node carries `properties?` + `[extra: string]: unknown` so caller-supplied data round-trips verbatim | the SARIF schema (subset) |
+| `FileRegionsCache`, `NewLineIndex` — line/col ↔ charOffset, snippet + contextRegion extraction, sha-256 | `src/Sarif/FileRegionsCache.cs`, `NewLineIndex.cs` |
+| `AIRuleIdConvention` — `CWE-<n>/<sub>` \| `NOVEL-<sub>` grammar | `src/Sarif/Emit/AIRuleIdConvention.cs` |
+| `tryDerivePortableRoot`, `isGitHubHostedRun` — repo-URI → GitHub/ADO permalink root | `src/Sarif.Multitool.Library/Emit/VcpPortableRoot.cs` |
+| `insertOptionalData`, `tryReconstructAbsoluteUri` — region/hash enrichment visitor | `src/Sarif/Visitors/InsertOptionalDataVisitor.cs` |
+| `atomicWrite`, `stripNulls`, `serializeSarifLog` — Newtonsoft-parity I/O | `src/Sarif/Emit/AtomicSarifWriter.cs` |
+| `rewriteRelativeLinks`, `extractFrontmatterDescription` — SKILL.md link pinning | `src/Sarif.Multitool.Library/GetSkill/GetSkillCommand.cs` |
+
+This package is a **port**; the C# under `src/Sarif/` is normative. When they
+disagree, this package has a bug.
+
+## Byte-identity with the .NET multitool
+
+`serializeSarifLog` is contracted to produce output **byte-for-byte identical**
+to the raw `dotnet Sarif.Multitool emit-finalize` output for the same input.
+That single-oracle contract is what lets the two runtimes share one set of
+fixtures and fail mutually when either side drifts.
+
+Getting to byte-identity required matching four Newtonsoft traits that
+`JSON.stringify` does not reproduce on its own. The machinery lives in
+[`src/canonicalize.ts`](src/canonicalize.ts) and is driven by a build-time
+generated model, [`scripts/generate-serialization-model.mjs`](scripts/generate-serialization-model.mjs)
+→ `dist/serialization-model.json`:
+
+1. **Key order.** Newtonsoft writes each typed object's members in **C# property
+   declaration order, overridden by `[DataMember(Order=N)]` when present** — not
+   schema order and not insertion order. The generator reads that order straight
+   from the normative `src/Sarif/Autogenerated/*.cs` `[DataMember]` attributes,
+   and pairs it with the schema's `$ref` graph so the canonicalizer knows each
+   property's child type. There is no hand-maintained order table; the
+   autogenerated C# is the only source of truth.
+
+2. **Property bags preserve insertion order.** A `properties` bag (and anything
+   nested inside it) keeps the order the producer inserted keys in — bags are
+   *not* reordered to the model. This is why `security-severity` precedes `tags`
+   in an enriched rule: `emit-finalize` inserts them in that order.
+
+3. **Compact property-bag values.** Newtonsoft stores bag values as
+   pre-serialized `JToken` text and writes them back verbatim, so a bag array
+   lands on one line (`"tags": ["security","external/cwe/cwe-89"]`) while the
+   bag's *keys* stay indented. Typed arrays everywhere else are multi-line. The
+   emitter (`emitCanonicalJson`) reproduces exactly this mixed shape.
+
+4. **Newlines and trailing byte.** The indented writer uses
+   `Environment.NewLine` (CRLF on Windows, LF on Linux) and emits **no trailing
+   newline**. `serializeSarifLog` mirrors `os.EOL` and omits the trailing
+   newline, so a fixture generated on the same host matches on both runtimes.
+
+The contract is enforced live, not against a committed golden, by the
+conformance harness in
+[`npm/sarif-multitool-ts/test/conformance.test.js`](../sarif-multitool-ts/test/conformance.test.js):
+it runs each scenario through both the TS library and the real .NET multitool
+and asserts raw byte-identity (after masking volatile `endTimeUtc` / temp
+paths). Note the committed `*.sarif` taxonomy samples under `src/Sarif/` are
+**not** the byte target — those are re-serialized by their PowerShell
+`*GenerateSample.ps1` scripts (`ConvertTo-Json` + `Add-Member` patches), so they
+gate "PowerShell + multitool", not the raw multitool wire shape. This port
+targets the **raw** .NET output.
+
+## Usage
+
+```ts
+import { FileRegionsCache, AIRuleIdConvention, serializeSarifLog,
+         type SarifLog, type Result } from '@microsoft/sarif';
+```
+
+For the multitool verbs (`emit-*`, `get-*`, `validate`) and the `sarif` CLI,
+install [`@microsoft/sarif-multitool-ts`](https://www.npmjs.com/package/@microsoft/sarif-multitool-ts)
+instead — it re-exports everything here.
 
 ## License
 

package/dist/aiRuleId.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Enforces the SARIF SDK AI-authoring convention for `result.ruleId`.
+ * Ported from src/Sarif/Emit/AIRuleIdConvention.cs.
+ *
+ * Accepted forms:
+ *   - `CWE-<number>/<sub-id>` where sub-id is lowercase-alphanumeric kebab-case
+ *     e.g. `CWE-89/kql-injection-from-config`
+ *   - `NOVEL-<sub-id>` (flat, no slash) for findings with no CWE mapping
+ */
+import type { Result } from './sarif.js';
+export declare class AIRuleIdConventionError extends Error {
+    readonly offenders: readonly string[];
+    constructor(offenders: readonly string[]);
+}
+export declare const AIRuleIdConvention: {
+    /**
+     * Extracts the canonical `CWE-<number>` id (leading-zero-free) from a ruleId,
+     * whether bare (`CWE-89`) or sub-id form (`CWE-89/kql-injection`). Returns
+     * undefined for NOVEL- ids, null/empty, or anything that does not start
+     * with a CWE token.
+     */
+    readonly tryGetCweId: (ruleId: string | undefined) => string | undefined;
+    readonly isNovel: (ruleId: string | undefined) => boolean;
+    readonly isAcceptable: (ruleId: string | undefined) => boolean;
+    readonly throwIfUnacceptable: (ruleId: string | undefined) => void;
+    readonly throwIfAnyUnacceptable: (results: ReadonlyArray<Result> | undefined) => void;
+};

package/dist/aiRuleId.js

@@ -0,0 +1,60 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+const TAXONOMY_SUB_ID = /^CWE-[0-9]+\/[a-z0-9]+(-[a-z0-9]+)*$/;
+const NOVEL_PREFIX = /^NOVEL-[a-z0-9]+(-[a-z0-9]+)*$/;
+const CWE_NUMBER = /^CWE-([0-9]+)(\/|$)/;
+const NOVEL_MARKER = 'NOVEL-';
+export class AIRuleIdConventionError extends Error {
+    offenders;
+    constructor(offenders) {
+        const list = offenders.map((o) => `'${o}'`).join(', ');
+        super(`result.ruleId must follow the AI ruleId convention: 'CWE-<number>/<lowercase-kebab-sub-id>' or 'NOVEL-<lowercase-kebab-sub-id>'. Offending value(s): ${list}.`);
+        this.name = 'AIRuleIdConventionError';
+        this.offenders = offenders;
+    }
+}
+export const AIRuleIdConvention = {
+    /**
+     * Extracts the canonical `CWE-<number>` id (leading-zero-free) from a ruleId,
+     * whether bare (`CWE-89`) or sub-id form (`CWE-89/kql-injection`). Returns
+     * undefined for NOVEL- ids, null/empty, or anything that does not start
+     * with a CWE token.
+     */
+    tryGetCweId(ruleId) {
+        if (!ruleId)
+            return undefined;
+        const m = CWE_NUMBER.exec(ruleId);
+        if (!m)
+            return undefined;
+        const n = Number.parseInt(m[1], 10);
+        if (!Number.isFinite(n))
+            return undefined;
+        return `CWE-${n}`;
+    },
+    isNovel(ruleId) {
+        return !!ruleId && ruleId.startsWith(NOVEL_MARKER);
+    },
+    isAcceptable(ruleId) {
+        if (!ruleId)
+            return false;
+        if (ruleId.startsWith(NOVEL_MARKER))
+            return NOVEL_PREFIX.test(ruleId);
+        return TAXONOMY_SUB_ID.test(ruleId);
+    },
+    throwIfUnacceptable(ruleId) {
+        if (!this.isAcceptable(ruleId)) {
+            throw new AIRuleIdConventionError([ruleId ?? '']);
+        }
+    },
+    throwIfAnyUnacceptable(results) {
+        if (!results || results.length === 0)
+            return;
+        const offenders = [];
+        for (const r of results) {
+            if (!this.isAcceptable(r?.ruleId))
+                offenders.push(r?.ruleId ?? '');
+        }
+        if (offenders.length > 0)
+            throw new AIRuleIdConventionError(offenders);
+    },
+};

package/dist/canonicalize.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns a deep copy of `log` with every typed object's keys reordered to the
+ * .NET model order. The input is not mutated.
+ */
+export declare function canonicalizeSarifLog<T>(log: T): T;
+/**
+ * Serializes a SARIF log to the .NET multitool's byte shape: model-ordered keys,
+ * two-space indent, and verbatim-compact property-bag values. `prettyPrint=false`
+ * yields fully compact output (every value on one line), matching the .NET
+ * minified writer. Uses LF newlines; the caller applies the platform newline.
+ */
+export declare function emitCanonicalJson(log: unknown, prettyPrint: boolean): string;

package/dist/canonicalize.js

@@ -0,0 +1,141 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * Canonical key ordering for byte-identical parity with the .NET multitool.
+ *
+ * The .NET multitool serializes through its typed object model, so its on-disk
+ * key order is the model's DataMember order — independent of the order keys
+ * arrived in. A JS object, by contrast, serializes in insertion order. To match
+ * .NET byte-for-byte we reorder every typed node to the model order.
+ *
+ * The order + type graph live in dist/serialization-model.json, generated at
+ * build time from the same authorities that define .NET's behavior:
+ *   - key order: src/Sarif/Autogenerated/*.cs DataMember attributes
+ *   - prop -> child-type graph: the published SARIF schema's $ref edges
+ * See scripts/generate-serialization-model.mjs.
+ *
+ * Property bags (`@propertyBag`) are passed through untouched: their key order
+ * is producer-determined and preserved by both runtimes.
+ */
+import { readFileSync } from 'node:fs';
+const PROPERTY_BAG = '@propertyBag';
+let modelCache;
+function model() {
+    if (modelCache === undefined) {
+        const url = new URL('./serialization-model.json', import.meta.url);
+        modelCache = JSON.parse(readFileSync(url, 'utf8'));
+    }
+    return modelCache;
+}
+function orderValue(value, def) {
+    if (Array.isArray(value)) {
+        return value.map((v) => orderValue(v, def));
+    }
+    if (value !== null && typeof value === 'object') {
+        if (!def || def === PROPERTY_BAG)
+            return value; // property bag / untyped: preserve insertion order
+        const entry = model()[def];
+        if (!entry)
+            return value;
+        return orderObject(value, entry);
+    }
+    return value;
+}
+function orderObject(value, entry) {
+    const out = {};
+    for (const prop of entry.order) {
+        if (Object.prototype.hasOwnProperty.call(value, prop)) {
+            out[prop] = orderValue(value[prop], entry.children[prop]);
+        }
+    }
+    // Any keys the model doesn't know about (defensive; the typed model normally
+    // covers everything) keep their relative insertion order at the tail.
+    for (const key of Object.keys(value)) {
+        if (!Object.prototype.hasOwnProperty.call(out, key)) {
+            out[key] = value[key];
+        }
+    }
+    return out;
+}
+/**
+ * Returns a deep copy of `log` with every typed object's keys reordered to the
+ * .NET model order. The input is not mutated.
+ */
+export function canonicalizeSarifLog(log) {
+    return orderValue(log, 'sarifLog');
+}
+// ---------------------------------------------------------------------------
+// Canonical JSON emitter
+// ---------------------------------------------------------------------------
+//
+// Newtonsoft (the .NET multitool's writer) serializes a SARIF log indented, but
+// emits property-bag *values* verbatim-compact: they are stored as
+// pre-serialized JToken text, so an array like `tags` lands on a single line
+// (`"tags": ["security","external/cwe/cwe-89"]`) while the bag's keys stay
+// indented. Typed arrays everywhere else are multi-line as usual. JSON.stringify
+// cannot produce this mixed shape, so we emit it ourselves. This reorders to the
+// model order in the same pass, so callers need not pre-canonicalize.
+const INDENT = '  ';
+function pad(depth) {
+    return INDENT.repeat(depth);
+}
+/** Emits a property bag: indented keys, but each value rendered verbatim-compact. */
+function emitPropertyBag(value, depth) {
+    const keys = Object.keys(value);
+    if (keys.length === 0)
+        return '{}';
+    const inner = pad(depth + 1);
+    const lines = keys.map((k) => `${inner}${JSON.stringify(k)}: ${JSON.stringify(value[k])}`);
+    return `{\n${lines.join(',\n')}\n${pad(depth)}}`;
+}
+function emitValue(value, def, depth) {
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '[]';
+        const inner = pad(depth + 1);
+        const lines = value.map((v) => `${inner}${emitValue(v, def, depth + 1)}`);
+        return `[\n${lines.join(',\n')}\n${pad(depth)}]`;
+    }
+    if (value !== null && typeof value === 'object') {
+        if (def === PROPERTY_BAG)
+            return emitPropertyBag(value, depth);
+        const obj = value;
+        const entry = def ? model()[def] : undefined;
+        const keys = orderedKeys(obj, entry);
+        if (keys.length === 0)
+            return '{}';
+        const inner = pad(depth + 1);
+        const lines = keys.map((k) => `${inner}${JSON.stringify(k)}: ${emitValue(obj[k], entry?.children[k], depth + 1)}`);
+        return `{\n${lines.join(',\n')}\n${pad(depth)}}`;
+    }
+    return JSON.stringify(value);
+}
+/** Keys present on `obj`, in model order; unknown keys (defensive) trail in insertion order. */
+function orderedKeys(obj, entry) {
+    if (!entry)
+        return Object.keys(obj);
+    const seen = new Set();
+    const out = [];
+    for (const prop of entry.order) {
+        if (Object.prototype.hasOwnProperty.call(obj, prop)) {
+            out.push(prop);
+            seen.add(prop);
+        }
+    }
+    for (const key of Object.keys(obj)) {
+        if (!seen.has(key))
+            out.push(key);
+    }
+    return out;
+}
+/**
+ * Serializes a SARIF log to the .NET multitool's byte shape: model-ordered keys,
+ * two-space indent, and verbatim-compact property-bag values. `prettyPrint=false`
+ * yields fully compact output (every value on one line), matching the .NET
+ * minified writer. Uses LF newlines; the caller applies the platform newline.
+ */
+export function emitCanonicalJson(log, prettyPrint) {
+    if (!prettyPrint)
+        return JSON.stringify(canonicalizeSarifLog(log));
+    return emitValue(log, 'sarifLog', 0);
+}

package/dist/index.d.ts

@@ -1,9 +1,16 @@
 /**
  * @microsoft/sarif — SARIF SDK for Node.js.
  *
- * v0.0.x PLACEHOLDER. This release reserves the package name and proves the
- * publish pipeline; the implementation (open-typed SARIF object model,
- * FileRegionsCache, AIRuleIdConvention, serialization helpers) lands in a
- * subsequent release tracked at https://github.com/microsoft/sarif-sdk.
+ * Open-typed SARIF 2.1.0 object model, region/snippet resolution, AI ruleId
+ * convention, portable-root derivation, and serialization helpers. Every TS
+ * module names the C# source-of-truth file it was ported from. The C# under
+ * src/Sarif/ is normative; when they disagree this package has a bug.
  */
-export declare const SARIF_SCHEMA_URI = "https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/csd01/schemas/sarif-schema-2.1.0.json";
+export * from './sarif.js';
+export { FileRegionsCache, NewLineIndex } from './regions.js';
+export { computeRollingHashes } from './rollingHash.js';
+export { AIRuleIdConvention, AIRuleIdConventionError } from './aiRuleId.js';
+export { tryValidateRepositoryUri, tryDerivePortableRoot, isGitHubHostedRun, type PortableRoot, } from './vcp.js';
+export { insertOptionalData, tryReconstructAbsoluteUri, PRIMARY_LOCATION_LINE_HASH, type InsertOptionalDataFlags, } from './insertOptionalData.js';
+export { atomicWrite, stripNulls, serializeSarifLog } from './io.js';
+export { rewriteRelativeLinks, extractFrontmatterDescription } from './skill.js';

package/dist/index.js

@@ -3,9 +3,16 @@
 /**
  * @microsoft/sarif — SARIF SDK for Node.js.
  *
- * v0.0.x PLACEHOLDER. This release reserves the package name and proves the
- * publish pipeline; the implementation (open-typed SARIF object model,
- * FileRegionsCache, AIRuleIdConvention, serialization helpers) lands in a
- * subsequent release tracked at https://github.com/microsoft/sarif-sdk.
+ * Open-typed SARIF 2.1.0 object model, region/snippet resolution, AI ruleId
+ * convention, portable-root derivation, and serialization helpers. Every TS
+ * module names the C# source-of-truth file it was ported from. The C# under
+ * src/Sarif/ is normative; when they disagree this package has a bug.
  */
-export const SARIF_SCHEMA_URI = 'https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/csd01/schemas/sarif-schema-2.1.0.json';
+export * from './sarif.js';
+export { FileRegionsCache, NewLineIndex } from './regions.js';
+export { computeRollingHashes } from './rollingHash.js';
+export { AIRuleIdConvention, AIRuleIdConventionError } from './aiRuleId.js';
+export { tryValidateRepositoryUri, tryDerivePortableRoot, isGitHubHostedRun, } from './vcp.js';
+export { insertOptionalData, tryReconstructAbsoluteUri, PRIMARY_LOCATION_LINE_HASH, } from './insertOptionalData.js';
+export { atomicWrite, stripNulls, serializeSarifLog } from './io.js';
+export { rewriteRelativeLinks, extractFrontmatterDescription } from './skill.js';

package/dist/insertOptionalData.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Subset of InsertOptionalDataVisitor needed by emit-finalize: walks every
+ * physical location, populates region snippets / context regions / char
+ * spans, and builds `run.artifacts[]` with sha-256 hashes.
+ *
+ * Ported from src/Sarif/Visitors/InsertOptionalDataVisitor.cs (the
+ * Hashes | RegionSnippets | ContextRegionSnippets | ComprehensiveRegionProperties
+ * subset; OverwriteExistingData is intentionally NOT set — see
+ * EmitFinalizeCommand.cs for rationale).
+ */
+import type { Run, ArtifactLocation } from './sarif.js';
+export interface InsertOptionalDataFlags {
+    hashes: boolean;
+    regionSnippets: boolean;
+    contextRegionSnippets: boolean;
+    comprehensiveRegionProperties: boolean;
+    /**
+     * Stamp the GitHub rolling-hash `primaryLocationLineHash` partial
+     * fingerprint on each result's primary location. GitHub-only — the raw
+     * code-scanning upload API does not backfill it. Off by default; existing
+     * values are preserved (OverwriteExistingData is not honored here).
+     */
+    rollingHashFingerprints?: boolean;
+}
+/** Partial-fingerprint key GitHub reads for cross-scan result de-duplication. */
+export declare const PRIMARY_LOCATION_LINE_HASH = "primaryLocationLineHash";
+/**
+ * Resolves an artifactLocation's `uri` + `uriBaseId` against the run's
+ * `originalUriBaseIds` to an absolute URI string, or undefined if it cannot
+ * be made absolute. Mirrors ArtifactLocation.TryReconstructAbsoluteUri.
+ */
+export declare function tryReconstructAbsoluteUri(loc: ArtifactLocation | undefined, originalUriBaseIds: Record<string, ArtifactLocation> | undefined): string | undefined;
+/**
+ * Walks the run mutating physical-location regions in place and populating
+ * `run.artifacts[]`. Returns the same run (mutation, not a copy — every
+ * caller-supplied key on every node is preserved per the pass-through
+ * guarantee).
+ */
+export declare function insertOptionalData(run: Run, flags: InsertOptionalDataFlags): Run;

package/dist/insertOptionalData.js

@@ -0,0 +1,173 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+import { FileRegionsCache } from './regions.js';
+/** Partial-fingerprint key GitHub reads for cross-scan result de-duplication. */
+export const PRIMARY_LOCATION_LINE_HASH = 'primaryLocationLineHash';
+/**
+ * Resolves an artifactLocation's `uri` + `uriBaseId` against the run's
+ * `originalUriBaseIds` to an absolute URI string, or undefined if it cannot
+ * be made absolute. Mirrors ArtifactLocation.TryReconstructAbsoluteUri.
+ */
+export function tryReconstructAbsoluteUri(loc, originalUriBaseIds) {
+    if (!loc?.uri)
+        return undefined;
+    // Already absolute?
+    try {
+        const u = new URL(loc.uri);
+        if (u.protocol)
+            return u.toString();
+    }
+    catch {
+        /* relative */
+    }
+    // Walk the uriBaseId chain.
+    let baseId = loc.uriBaseId;
+    let composed = loc.uri;
+    const seen = new Set();
+    while (baseId && originalUriBaseIds && !seen.has(baseId)) {
+        seen.add(baseId);
+        const base = originalUriBaseIds[baseId];
+        if (!base?.uri)
+            return undefined;
+        composed = base.uri.replace(/\/?$/, '/') + composed;
+        try {
+            const u = new URL(composed);
+            if (u.protocol)
+                return u.toString();
+        }
+        catch {
+            /* still relative */
+        }
+        baseId = base.uriBaseId;
+    }
+    return undefined;
+}
+/**
+ * Walks the run mutating physical-location regions in place and populating
+ * `run.artifacts[]`. Returns the same run (mutation, not a copy — every
+ * caller-supplied key on every node is preserved per the pass-through
+ * guarantee).
+ */
+export function insertOptionalData(run, flags) {
+    const cache = new FileRegionsCache();
+    const oub = run.originalUriBaseIds;
+    // Scrape file references first so artifacts[] is populated before hashing.
+    if (flags.hashes) {
+        scrapeFileReferences(run);
+    }
+    for (const result of run.results ?? []) {
+        visitResultLocations(result, (pl) => visitPhysicalLocation(pl, oub, cache, flags));
+    }
+    if (flags.hashes && run.artifacts) {
+        for (const artifact of run.artifacts) {
+            const abs = tryReconstructAbsoluteUri(artifact.location, oub);
+            if (!abs)
+                continue;
+            if (!artifact.hashes) {
+                const sha = cache.getSha256(abs);
+                if (sha)
+                    artifact.hashes = { 'sha-256': sha };
+            }
+        }
+    }
+    if (flags.rollingHashFingerprints) {
+        for (const result of run.results ?? []) {
+            stampPrimaryLocationLineHash(result, oub, cache);
+        }
+    }
+    return run;
+}
+/**
+ * Stamps the rolling-hash `primaryLocationLineHash` on a result's primary
+ * location, anchored to its startLine (a result with no region line pertains
+ * to the whole file and is fingerprinted from line 1, matching
+ * github/codeql-action fingerprints.ts). Mirrors the
+ * RollingHashPartialFingerprints branch of InsertOptionalDataVisitor.cs.
+ */
+function stampPrimaryLocationLineHash(result, oub, cache) {
+    if (result.partialFingerprints?.[PRIMARY_LOCATION_LINE_HASH] !== undefined)
+        return;
+    const physicalLocation = result.locations?.[0]?.physicalLocation;
+    if (!physicalLocation?.artifactLocation)
+        return;
+    let startLine = physicalLocation.region?.startLine ?? 0;
+    if (startLine <= 0)
+        startLine = 1;
+    const resolvedUri = tryReconstructAbsoluteUri(physicalLocation.artifactLocation, oub);
+    if (!resolvedUri)
+        return;
+    const lineHash = cache.getRollingHashes(resolvedUri)?.get(startLine);
+    if (lineHash === undefined)
+        return;
+    result.partialFingerprints ??= {};
+    result.partialFingerprints[PRIMARY_LOCATION_LINE_HASH] = lineHash;
+}
+function visitResultLocations(result, visit) {
+    const allLocations = [
+        ...(result.locations ?? []),
+        ...(result.relatedLocations ?? []),
+    ];
+    for (const loc of allLocations) {
+        if (loc?.physicalLocation)
+            visit(loc.physicalLocation);
+    }
+}
+function visitPhysicalLocation(node, oub, cache, flags) {
+    if (!node.region || node.region.byteOffset !== undefined)
+        return;
+    if (!flags.regionSnippets && !flags.contextRegionSnippets && !flags.comprehensiveRegionProperties) {
+        return;
+    }
+    const resolvedUri = tryReconstructAbsoluteUri(node.artifactLocation, oub);
+    if (!resolvedUri)
+        return;
+    const expanded = cache.populateTextRegionProperties(node.region, resolvedUri, flags.regionSnippets);
+    const originalSnippet = node.region.snippet;
+    if (flags.comprehensiveRegionProperties) {
+        // Replace the region wholesale (preserving any property bag the caller
+        // supplied — populateTextRegionProperties spreads the input).
+        node.region = expanded;
+    }
+    node.region.snippet = originalSnippet ?? expanded.snippet;
+    if (flags.contextRegionSnippets && !node.contextRegion) {
+        node.contextRegion = cache.constructMultilineContextSnippet(expanded, resolvedUri);
+    }
+}
+/**
+ * Builds run.artifacts[] from every artifactLocation referenced by results,
+ * deduplicating by (uri, uriBaseId). Mirrors AddFileReferencesVisitor.
+ */
+function scrapeFileReferences(run) {
+    const artifacts = run.artifacts ? [...run.artifacts] : [];
+    const indexByKey = new Map();
+    for (let i = 0; i < artifacts.length; i++) {
+        const k = artifactKey(artifacts[i].location);
+        if (k)
+            indexByKey.set(k, i);
+    }
+    const register = (al) => {
+        if (!al?.uri)
+            return;
+        const k = artifactKey(al);
+        if (!k)
+            return;
+        let idx = indexByKey.get(k);
+        if (idx === undefined) {
+            idx = artifacts.length;
+            artifacts.push({ location: { uri: al.uri, uriBaseId: al.uriBaseId } });
+            indexByKey.set(k, idx);
+        }
+        // Back-reference into run.artifacts[] (mirrors AddFileReferencesVisitor).
+        al.index = idx;
+    };
+    for (const result of run.results ?? []) {
+        visitResultLocations(result, (pl) => register(pl.artifactLocation));
+    }
+    if (artifacts.length > 0)
+        run.artifacts = artifacts;
+}
+function artifactKey(al) {
+    if (!al?.uri)
+        return undefined;
+    return `${al.uriBaseId ?? ''}#${al.uri}`;
+}

package/dist/io.d.ts

@@ -0,0 +1,20 @@
+import type { SarifLog } from './sarif.js';
+/**
+ * Atomically writes a file by staging to a sibling temp file in the same
+ * directory and renaming over the destination. Mirrors AtomicSarifWriter.Write.
+ */
+export declare function atomicWrite(destinationPath: string, content: string): Promise<void>;
+/**
+ * Recursively strips keys whose value is `null` or `undefined`, matching
+ * Newtonsoft `NullValueHandling.Ignore`. Arrays keep null entries (Newtonsoft
+ * does too); only object properties are pruned.
+ */
+export declare function stripNulls<T>(value: T): T;
+/**
+ * Serializes a SarifLog to match the .NET multitool byte-for-byte: model-order
+ * keys, two-space indent, null-stripping, verbatim-compact property-bag values
+ * (a Newtonsoft trait — bag values are stored as pre-serialized JToken text),
+ * `Environment.NewLine` line endings, and no trailing newline. See
+ * canonicalize.ts for the ordering/emit details.
+ */
+export declare function serializeSarifLog(log: SarifLog, prettyPrint?: boolean): string;