@microsoft/sarif

SARIF SDK for Node.js — the base layer that @microsoft/sarif-multitool-ts and third-party SARIF producers build on. Native TypeScript; no CLR dependency.

What's here

| | 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 and is driven by a build-time generated model, 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: 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

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 instead — it re-exports everything here.

License

MIT