@microsoft/sarif 0.0.1 → 5.2.0

package/dist/io.js

@@ -0,0 +1,77 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * SARIF serialization helpers + atomic file writer.
+ *
+ * Ported from src/Sarif/Emit/AtomicSarifWriter.cs and the Newtonsoft-parity
+ * serialization conventions used throughout the .NET SDK
+ * (NullValueHandling.Ignore, two-space indent).
+ */
+import { promises as fs, existsSync, mkdirSync } from 'node:fs';
+import { dirname, basename, resolve as resolvePath, join as joinPath } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { EOL } from 'node:os';
+import { emitCanonicalJson } from './canonicalize.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 async function atomicWrite(destinationPath, content) {
+    if (!destinationPath)
+        throw new Error('Destination path must be supplied.');
+    const full = resolvePath(destinationPath);
+    const dir = dirname(full);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const stagingPath = joinPath(dir, `${basename(full)}.${randomUUID().replace(/-/g, '')}.tmp`);
+    try {
+        const handle = await fs.open(stagingPath, 'wx');
+        try {
+            await handle.writeFile(content, 'utf8');
+            await handle.sync().catch(() => { });
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(stagingPath, full);
+    }
+    catch (err) {
+        await fs.unlink(stagingPath).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * 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 function stripNulls(value) {
+    if (Array.isArray(value)) {
+        return value.map((v) => stripNulls(v));
+    }
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (v === null || v === undefined)
+                continue;
+            out[k] = stripNulls(v);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * 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 function serializeSarifLog(log, prettyPrint = true) {
+    const json = emitCanonicalJson(stripNulls(log), prettyPrint);
+    // Newtonsoft's indented writer uses Environment.NewLine; mirror it so a
+    // Windows-generated fixture is CRLF and a Linux one is LF, matching .NET on
+    // the same host. Only structural newlines are affected — JSON escapes any
+    // newline inside a string value as \n, so it never reaches this split.
+    return prettyPrint && EOL !== '\n' ? json.split('\n').join(EOL) : json;
+}

package/dist/regions.d.ts

@@ -0,0 +1,51 @@
+import type { Region } from './sarif.js';
+/**
+ * Index of newline start locations so a char offset can cheaply turn into a
+ * 1-based line/column and vice versa. Mirrors NewLineIndex.cs.
+ */
+export declare class NewLineIndex {
+    readonly text: string;
+    private readonly lineOffsetStarts;
+    constructor(text: string);
+    get maximumLineNumber(): number;
+    /** Char offset at which the given 1-based line begins. */
+    startOffsetForLine(lineNumber: number): number;
+    /** 1-based {line, column} for the given char offset. */
+    offsetInfo(offset: number): {
+        lineNumber: number;
+        columnNumber: number;
+    };
+}
+export declare class FileRegionsCache {
+    private readonly textCache;
+    private readonly indexCache;
+    private readonly hashCache;
+    private readonly rollingHashCache;
+    private localPathFor;
+    /** Returns file text or null if unreadable. */
+    getText(absoluteUri: string): string | null;
+    getNewLineIndex(absoluteUri: string): NewLineIndex | null;
+    /** sha-256 over the raw bytes of the file. */
+    getSha256(absoluteUri: string): string | undefined;
+    /**
+     * CodeQL-style per-line rolling-hash fingerprints for the file, keyed by
+     * 1-based line number, or null if the file is unreadable. Mirrors
+     * InsertOptionalDataVisitor.GetRollingHashes.
+     */
+    getRollingHashes(absoluteUri: string): Map<number, string> | null;
+    /**
+     * Returns a copy of `inputRegion` with all text-related properties
+     * populated (line/col ↔ charOffset/charLength) and optionally a snippet.
+     * Mirrors FileRegionsCache.PopulateTextRegionProperties.
+     *
+     * `overwriteExistingData=false` (the default) throws on author/source
+     * coordinate divergence; `true` replaces the authored value.
+     */
+    populateTextRegionProperties(inputRegion: Region, absoluteUri: string, populateSnippet: boolean, overwriteExistingData?: boolean): Region;
+    /**
+     * Builds a context region that spans roughly one line above and one line
+     * below the input region (or a ±128-char window if that overflows 512
+     * chars). Mirrors FileRegionsCache.ConstructMultilineContextSnippet.
+     */
+    constructMultilineContextSnippet(inputRegion: Region, absoluteUri: string): Region | undefined;
+}

package/dist/regions.js

@@ -0,0 +1,281 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * NewLineIndex + FileRegionsCache: line/column ↔ char-offset resolution and
+ * snippet / context-region extraction.
+ *
+ * Ported from:
+ *   src/Sarif/NewLineIndex.cs
+ *   src/Sarif/FileRegionsCache.cs (text-region subset)
+ */
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { computeRollingHashes } from './rollingHash.js';
+const NEWLINE_CHARS = new Set(['\n', '\r']);
+const BIG_SNIPPET_LENGTH = 512;
+const SMALL_SNIPPET_LENGTH = 128;
+// ---------------------------------------------------------------------------
+// NewLineIndex
+// ---------------------------------------------------------------------------
+/**
+ * Index of newline start locations so a char offset can cheaply turn into a
+ * 1-based line/column and vice versa. Mirrors NewLineIndex.cs.
+ */
+export class NewLineIndex {
+    text;
+    // lineOffsetStarts[n] is the char offset at which (1-based) line n+1 begins.
+    lineOffsetStarts;
+    constructor(text) {
+        this.text = text;
+        const starts = [0];
+        for (let i = 0; i < text.length; i++) {
+            const c = text[i];
+            // Detect \r, \n, but NOT the \r in \r\n (the following \n handles it).
+            if (NEWLINE_CHARS.has(c)) {
+                if (c !== '\r' || i + 1 >= text.length || text[i + 1] !== '\n') {
+                    starts.push(i + 1);
+                }
+            }
+        }
+        this.lineOffsetStarts = starts;
+    }
+    get maximumLineNumber() {
+        return this.lineOffsetStarts.length;
+    }
+    /** Char offset at which the given 1-based line begins. */
+    startOffsetForLine(lineNumber) {
+        if (lineNumber <= 0 || lineNumber > this.maximumLineNumber + 1) {
+            throw new RangeError(`Line number ${lineNumber} is out of range.`);
+        }
+        if (lineNumber === this.maximumLineNumber + 1)
+            return this.text.length;
+        return this.lineOffsetStarts[lineNumber - 1];
+    }
+    /** 1-based {line, column} for the given char offset. */
+    offsetInfo(offset) {
+        if (offset < 0)
+            throw new RangeError('Offset cannot be negative.');
+        // Binary-search for the greatest start ≤ offset.
+        let lo = 0, hi = this.lineOffsetStarts.length - 1, idx = 0;
+        while (lo <= hi) {
+            const mid = (lo + hi) >> 1;
+            const v = this.lineOffsetStarts[mid];
+            if (v === offset) {
+                idx = mid;
+                break;
+            }
+            if (v < offset) {
+                idx = mid;
+                lo = mid + 1;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        const startOffset = this.lineOffsetStarts[idx];
+        return { lineNumber: idx + 1, columnNumber: offset - startOffset + 1 };
+    }
+}
+// ---------------------------------------------------------------------------
+// FileRegionsCache (text-region subset)
+// ---------------------------------------------------------------------------
+export class FileRegionsCache {
+    textCache = new Map();
+    indexCache = new Map();
+    hashCache = new Map();
+    rollingHashCache = new Map();
+    localPathFor(absoluteUri) {
+        try {
+            const u = new URL(absoluteUri);
+            if (u.protocol === 'file:')
+                return fileURLToPath(u);
+        }
+        catch {
+            /* not a URL */
+        }
+        return undefined;
+    }
+    /** Returns file text or null if unreadable. */
+    getText(absoluteUri) {
+        if (this.textCache.has(absoluteUri))
+            return this.textCache.get(absoluteUri);
+        const path = this.localPathFor(absoluteUri);
+        let text = null;
+        if (path) {
+            try {
+                text = readFileSync(path, 'utf8');
+            }
+            catch {
+                text = null;
+            }
+        }
+        this.textCache.set(absoluteUri, text);
+        return text;
+    }
+    getNewLineIndex(absoluteUri) {
+        if (this.indexCache.has(absoluteUri))
+            return this.indexCache.get(absoluteUri);
+        const text = this.getText(absoluteUri);
+        const idx = text !== null ? new NewLineIndex(text) : null;
+        this.indexCache.set(absoluteUri, idx);
+        return idx;
+    }
+    /** sha-256 over the raw bytes of the file. */
+    getSha256(absoluteUri) {
+        if (this.hashCache.has(absoluteUri))
+            return this.hashCache.get(absoluteUri);
+        const path = this.localPathFor(absoluteUri);
+        if (!path)
+            return undefined;
+        let buf;
+        try {
+            buf = readFileSync(path);
+        }
+        catch {
+            return undefined;
+        }
+        // .NET HashUtilities emits uppercase hex; match it for byte parity.
+        const hash = createHash('sha256').update(buf).digest('hex').toUpperCase();
+        this.hashCache.set(absoluteUri, hash);
+        return hash;
+    }
+    /**
+     * CodeQL-style per-line rolling-hash fingerprints for the file, keyed by
+     * 1-based line number, or null if the file is unreadable. Mirrors
+     * InsertOptionalDataVisitor.GetRollingHashes.
+     */
+    getRollingHashes(absoluteUri) {
+        if (this.rollingHashCache.has(absoluteUri))
+            return this.rollingHashCache.get(absoluteUri);
+        const text = this.getText(absoluteUri);
+        const hashes = text !== null ? computeRollingHashes(text) : null;
+        this.rollingHashCache.set(absoluteUri, hashes);
+        return hashes;
+    }
+    /**
+     * Returns a copy of `inputRegion` with all text-related properties
+     * populated (line/col ↔ charOffset/charLength) and optionally a snippet.
+     * Mirrors FileRegionsCache.PopulateTextRegionProperties.
+     *
+     * `overwriteExistingData=false` (the default) throws on author/source
+     * coordinate divergence; `true` replaces the authored value.
+     */
+    populateTextRegionProperties(inputRegion, absoluteUri, populateSnippet, overwriteExistingData = false) {
+        if (!inputRegion || isBinaryRegion(inputRegion))
+            return inputRegion;
+        const idx = this.getNewLineIndex(absoluteUri);
+        if (!idx)
+            return inputRegion;
+        const fileText = idx.text;
+        const region = { ...inputRegion };
+        if (!region.startLine || region.startLine === 0) {
+            populateFromCharOffsetAndLength(idx, region, overwriteExistingData);
+        }
+        else {
+            populateFromStartAndEndProperties(idx, region, fileText, overwriteExistingData);
+        }
+        if (populateSnippet &&
+            (region.charOffset ?? -1) >= 0 &&
+            (region.charLength ?? -1) >= 0 &&
+            (region.charOffset ?? 0) + (region.charLength ?? 0) <= fileText.length) {
+            region.snippet ??= {};
+            const snippetText = fileText.substring(region.charOffset, region.charOffset + region.charLength);
+            if (region.snippet.text === undefined) {
+                region.snippet.text = snippetText;
+            }
+        }
+        return region;
+    }
+    /**
+     * Builds a context region that spans roughly one line above and one line
+     * below the input region (or a ±128-char window if that overflows 512
+     * chars). Mirrors FileRegionsCache.ConstructMultilineContextSnippet.
+     */
+    constructMultilineContextSnippet(inputRegion, absoluteUri) {
+        if (!inputRegion || isBinaryRegion(inputRegion))
+            return undefined;
+        const idx = this.getNewLineIndex(absoluteUri);
+        if (!idx)
+            return undefined;
+        const fileText = idx.text;
+        const original = this.populateTextRegionProperties(inputRegion, absoluteUri, true);
+        if ((original.charLength ?? 0) >= BIG_SNIPPET_LENGTH) {
+            return { ...original };
+        }
+        const maxLine = idx.maximumLineNumber;
+        const startLine = (inputRegion.startLine ?? 1) === 1 ? 1 : (inputRegion.startLine ?? 1) - 1;
+        const endLineIn = inputRegion.endLine ?? inputRegion.startLine ?? 1;
+        const endLine = endLineIn === maxLine ? maxLine : endLineIn + 1;
+        let context = this.populateTextRegionProperties({ startLine, endLine }, absoluteUri, true);
+        if ((original.charLength ?? 0) <= (context.charLength ?? 0) &&
+            (context.charLength ?? 0) <= BIG_SNIPPET_LENGTH) {
+            return context;
+        }
+        const charOffset = Math.max(0, (original.charOffset ?? 0) - SMALL_SNIPPET_LENGTH);
+        const charLength = Math.min(BIG_SNIPPET_LENGTH, fileText.length - charOffset);
+        context = this.populateTextRegionProperties({ charOffset, charLength }, absoluteUri, true);
+        return context;
+    }
+}
+// ---------------------------------------------------------------------------
+// Region coordinate population (mirrors private helpers in FileRegionsCache)
+// ---------------------------------------------------------------------------
+function isBinaryRegion(r) {
+    return r.byteOffset !== undefined && r.byteOffset >= 0;
+}
+function reconcile(overwrite, propertyName, computed, authored) {
+    if (authored === computed)
+        return authored;
+    if (overwrite)
+        return computed;
+    throw new Error(`The input region specifies '${propertyName}' = ${authored}, but the value computed from the source file is ${computed}. Authored region coordinates must exactly match the source text; omit a coordinate to have the SDK compute it, or set overwriteExistingData to recompute (overwrite) it.`);
+}
+function populateFromCharOffsetAndLength(idx, region, overwrite) {
+    const charOffset = region.charOffset ?? 0;
+    const charLength = region.charLength ?? 0;
+    const start = idx.offsetInfo(charOffset);
+    const end = idx.offsetInfo(charOffset + charLength);
+    if (!region.startLine)
+        region.startLine = start.lineNumber;
+    if (!region.startColumn)
+        region.startColumn = start.columnNumber;
+    if (!region.endLine)
+        region.endLine = end.lineNumber;
+    if (!region.endColumn)
+        region.endColumn = end.columnNumber;
+    region.startLine = reconcile(overwrite, 'startLine', start.lineNumber, region.startLine);
+    region.startColumn = reconcile(overwrite, 'startColumn', start.columnNumber, region.startColumn);
+    region.endLine = reconcile(overwrite, 'endLine', end.lineNumber, region.endLine);
+    region.endColumn = reconcile(overwrite, 'endColumn', end.columnNumber, region.endColumn);
+}
+function populateFromStartAndEndProperties(idx, region, fileText, overwrite) {
+    // Order is significant; each step relies on coordinates populated earlier.
+    region.endLine = region.endLine && region.endLine !== 0 ? region.endLine : region.startLine;
+    region.startColumn = region.startColumn && region.startColumn !== 0 ? region.startColumn : 1;
+    if (!region.endColumn || region.endColumn === 0) {
+        // No explicit end column: scan to the line terminator.
+        const lineStart = idx.startOffsetForLine(region.endLine);
+        let p = lineStart;
+        while (p < fileText.length && !NEWLINE_CHARS.has(fileText[p]))
+            p++;
+        region.endColumn = p - lineStart + 1;
+    }
+    // charOffset
+    const startLineOffset = idx.startOffsetForLine(region.startLine);
+    const computedOffset = startLineOffset + region.startColumn - 1;
+    if (region.charOffset === undefined || region.charOffset === 0 || region.charOffset === -1) {
+        region.charOffset = computedOffset;
+    }
+    region.charOffset = reconcile(overwrite, 'charOffset', computedOffset, region.charOffset);
+    // charLength
+    const endLineOffset = idx.startOffsetForLine(region.endLine);
+    const computedLength = endLineOffset - region.charOffset + region.endColumn - 1;
+    if (region.charLength === undefined || region.charLength === 0) {
+        region.charLength = computedLength;
+    }
+    region.charLength = reconcile(overwrite, 'charLength', computedLength, region.charLength);
+    if (region.charOffset + region.charLength > fileText.length && !overwrite) {
+        throw new Error(`The input region's character span (charOffset ${region.charOffset} + charLength ${region.charLength} = ${region.charOffset + region.charLength}) extends beyond the source file length (${fileText.length}). Authored region coordinates must lie within the source text; omit them to have the SDK compute the span, or set overwriteExistingData to recompute it.`);
+    }
+}

package/dist/rollingHash.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Computes the rolling-hash fingerprint for every line of `fileText`, keyed by
+ * 1-based line number, with values of the form `"<hex>:<ordinal>"` where the
+ * ordinal disambiguates lines whose hash collides (identical normalized
+ * content). Mirrors HashUtilities.RollingHash.
+ */
+export declare function computeRollingHashes(fileText: string): Map<number, string>;

package/dist/rollingHash.js

@@ -0,0 +1,111 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * CodeQL-style rolling-hash partial fingerprints (`primaryLocationLineHash`).
+ *
+ * The normative source for this algorithm is github/codeql-action's
+ * fingerprints.ts (https://github.com/github/codeql-action, src/fingerprints.ts);
+ * src/Sarif/HashUtilities.cs is itself a port of it, and src/Sarif/Numeric/Long.cs
+ * exists only to re-emulate JS 64-bit `Long` arithmetic in the CLR. This module
+ * returns to that source: it reproduces the same per-line `"<hex>:<count>"`
+ * fingerprints byte-for-byte using native BigInt mod-2^64 arithmetic, so no
+ * `Long` emulation (or npm `long` dependency) is needed.
+ *
+ * GitHub's raw code-scanning SARIF upload API does NOT backfill
+ * partialFingerprints, so a GitHub-hosted producer must stamp this itself to
+ * avoid duplicate alerts across scans. See InsertOptionalDataVisitor.cs.
+ */
+const TAB = 0x09;
+const SPACE = 0x20;
+const LF = 0x0a;
+const CR = 0x0d;
+const EOF = 65535;
+const BLOCK_SIZE = 100;
+// 64-bit two's-complement ring. BigInt `& MASK` reduces any (incl. negative)
+// intermediate to its low 64 bits, exactly matching the CLR `Long` wraparound
+// and `ToUnsigned()` the C# performs before `ToString(16)`.
+const MASK = (1n << 64n) - 1n;
+const MOD = 37n;
+function computeFirstMod() {
+    let firstMod = 1n;
+    for (let i = 0; i < BLOCK_SIZE; i++) {
+        firstMod = (firstMod * MOD) & MASK;
+    }
+    return firstMod;
+}
+/**
+ * Computes the rolling-hash fingerprint for every line of `fileText`, keyed by
+ * 1-based line number, with values of the form `"<hex>:<ordinal>"` where the
+ * ordinal disambiguates lines whose hash collides (identical normalized
+ * content). Mirrors HashUtilities.RollingHash.
+ */
+export function computeRollingHashes(fileText) {
+    const rollingHashes = new Map();
+    if (fileText == null)
+        return rollingHashes;
+    // A rolling view into the input.
+    const window = new Array(BLOCK_SIZE).fill(0);
+    const lineNumbers = new Array(BLOCK_SIZE).fill(-1);
+    let hashRaw = 0n;
+    const firstMod = computeFirstMod();
+    let index = 0;
+    let lineNumber = 0;
+    let lineStart = true;
+    let prevCR = false;
+    const hashCounts = new Map();
+    const outputHash = () => {
+        const hashValue = (hashRaw & MASK).toString(16);
+        const count = (hashCounts.get(hashValue) ?? 0) + 1;
+        hashCounts.set(hashValue, count);
+        rollingHashes.set(lineNumbers[index], `${hashValue}:${count}`);
+        lineNumbers[index] = -1;
+    };
+    const updateHash = (current) => {
+        const begin = window[index];
+        window[index] = current;
+        hashRaw = (MOD * hashRaw + BigInt(current) - firstMod * BigInt(begin)) & MASK;
+        index = (index + 1) % BLOCK_SIZE;
+    };
+    const processCharacter = (current) => {
+        // Skip tabs, spaces, and line feeds that come directly after a carriage return.
+        if (current === SPACE || current === TAB || (prevCR && current === LF)) {
+            prevCR = false;
+            return;
+        }
+        // Replace CR with LF. (\u2028 / \u2029 are intentionally not handled,
+        // matching the reference implementation.)
+        if (current === CR) {
+            current = LF;
+            prevCR = true;
+        }
+        else {
+            prevCR = false;
+        }
+        if (lineNumbers[index] !== -1) {
+            outputHash();
+        }
+        if (lineStart) {
+            lineStart = false;
+            lineNumber++;
+            lineNumbers[index] = lineNumber;
+        }
+        if (current === LF) {
+            lineStart = true;
+        }
+        updateHash(current);
+    };
+    // `charCodeAt` yields UTF-16 code units, matching the C# `char` iteration the
+    // reference algorithm is defined over.
+    for (let i = 0; i < fileText.length; i++) {
+        processCharacter(fileText.charCodeAt(i));
+    }
+    processCharacter(EOF);
+    // Flush the remaining lines.
+    for (let i = 0; i < BLOCK_SIZE; i++) {
+        if (lineNumbers[index] !== -1) {
+            outputHash();
+        }
+        updateHash(0);
+    }
+    return rollingHashes;
+}