@microsoft/sarif 5.4.3 → 5.5.0

package/dist/index.d.ts

@@ -10,7 +10,7 @@ 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 { tryValidateRepositoryUri, tryDerivePortableRoot, isGitHubHostedRun, parseAuthorizedHosts, type PortableRoot, type VcpOptions, type AuthorizedHost, type AuthorizedHostType, } 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

@@ -12,7 +12,7 @@ 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 { tryValidateRepositoryUri, tryDerivePortableRoot, isGitHubHostedRun, parseAuthorizedHosts, } 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/regions.js

@@ -201,7 +201,11 @@ export class FileRegionsCache {
         const fileText = idx.text;
         const original = this.populateTextRegionProperties(inputRegion, absoluteUri, true);
         if ((original.charLength ?? 0) >= BIG_SNIPPET_LENGTH) {
-            return { ...original };
+            // A context region must be a proper superset of the region (SARIF §3.29.5,
+            // enforced by SARIF1008). The region already meets the snippet cap, so no
+            // larger in-cap snippet exists; omit the context region rather than return
+            // one identical to the region.
+            return undefined;
         }
         const maxLine = idx.maximumLineNumber;
         const startLine = (inputRegion.startLine ?? 1) === 1 ? 1 : (inputRegion.startLine ?? 1) - 1;
@@ -215,7 +219,11 @@ export class FileRegionsCache {
         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;
+        // The capped char-offset window does not always contain the region (a region
+        // longer than the window's reach past its start runs off the end). Emit the
+        // context region only when it is a genuine proper superset of the region;
+        // otherwise omit it (SARIF §3.29.5 / SARIF1008).
+        return isProperSupersetOf(context, original) ? context : undefined;
     }
 }
 // ---------------------------------------------------------------------------
@@ -224,6 +232,67 @@ export class FileRegionsCache {
 function isBinaryRegion(r) {
     return r.byteOffset !== undefined && r.byteOffset >= 0;
 }
+// ---------------------------------------------------------------------------
+// Proper-superset test (mirrors Region.IsProperSupersetOf)
+// ---------------------------------------------------------------------------
+/**
+ * True when `sup` strictly contains `sub`: every position covered by `sub` lies
+ * within `sup` and the two spans are not identical. Each populated coordinate
+ * dimension (line/column, char offset) must independently hold. Mirrors
+ * Region.IsProperSupersetOf.
+ */
+function isProperSupersetOf(sup, sub) {
+    if (isLineColumnBasedRegion(sup) &&
+        isLineColumnBasedRegion(sub) &&
+        !isLineColumnProperSupersetOf(sup, sub)) {
+        return false;
+    }
+    if (isOffsetBasedRegion(sup) &&
+        isOffsetBasedRegion(sub) &&
+        !isOffsetProperSupersetOf(sup, sub)) {
+        return false;
+    }
+    return true;
+}
+function isLineColumnBasedRegion(r) {
+    return (r.startLine ?? 0) >= 1;
+}
+function isOffsetBasedRegion(r) {
+    return (r.charOffset ?? -1) >= 0;
+}
+function isLineColumnProperSupersetOf(sup, sub) {
+    const supStartLine = sup.startLine ?? 0;
+    const supEndLine = sup.endLine ?? supStartLine;
+    const supStartColumn = sup.startColumn ?? 1;
+    const supEndColumn = sup.endColumn ?? Number.MAX_SAFE_INTEGER;
+    const subStartLine = sub.startLine ?? 0;
+    const subEndLine = sub.endLine ?? subStartLine;
+    const subStartColumn = sub.startColumn ?? 1;
+    const subEndColumn = sub.endColumn ?? Number.MAX_SAFE_INTEGER;
+    if (supStartLine > subStartLine || supEndLine < subEndLine)
+        return false;
+    if (supStartLine === subStartLine && supStartColumn > subStartColumn)
+        return false;
+    if (supEndLine === subEndLine && supEndColumn < subEndColumn)
+        return false;
+    // Identical span is not a proper superset.
+    return !(supStartLine === subStartLine &&
+        supEndLine === subEndLine &&
+        supStartColumn === subStartColumn &&
+        supEndColumn === subEndColumn);
+}
+function isOffsetProperSupersetOf(sup, sub) {
+    const supOffset = sup.charOffset ?? 0;
+    const supLength = sup.charLength ?? 0;
+    const subOffset = sub.charOffset ?? 0;
+    const subLength = sub.charLength ?? 0;
+    if (supOffset > subOffset)
+        return false;
+    if (supOffset + supLength < subOffset + subLength)
+        return false;
+    // Same start and no greater length is not a proper superset.
+    return !(supOffset === subOffset && supLength <= subLength);
+}
 function reconcile(overwrite, propertyName, computed, authored) {
     if (authored === computed)
         return authored;

package/dist/vcp.d.ts

@@ -12,6 +12,31 @@ export interface PortableRoot {
     leaf: string;
     revisionWebUrl: string;
 }
+/**
+ * A VCS product recognized by portable-root derivation. Extensible: a new
+ * product (e.g. `gitlab`, `bitbucket`) is a new type with its own permalink
+ * shape in `classify`/`tryDerivePortableRoot`. Currently only `ghe` (GitHub
+ * Enterprise Server) is recognized.
+ */
+export type AuthorizedHostType = 'ghe';
+export interface AuthorizedHost {
+    /** The VCS product running on `host`. */
+    type: AuthorizedHostType;
+    /** The host, lowercased, e.g. `githost.contoso.com`. */
+    host: string;
+}
+export interface VcpOptions {
+    /**
+     * Caller-attested hosts, each tagged with the VCS product running there (see
+     * `parseAuthorizedHosts` for the `<hostType>:<host>` grammar). A self-hosted
+     * instance runs on a custom domain that is structurally indistinguishable
+     * from any other host, so it cannot be auto-recognized; an attested host is
+     * classified per its type (a `ghe` host mints a github.com-style
+     * `{host}/{owner}/{repo}/blob/{sha}/` portable root). Matched
+     * case-insensitively.
+     */
+    authorizedHosts?: readonly AuthorizedHost[];
+}
 type Result<T> = {
     ok: true;
     value: T;
@@ -19,16 +44,24 @@ type Result<T> = {
     ok: false;
     error: string;
 };
+/**
+ * Parses a comma-separated `--authorized-hosts` value of `<hostType>:<host>`
+ * tokens (e.g. `ghe:githost.contoso.com,ghe:other.example.com`) into attested
+ * hosts. A new VCS product is added by extending `AuthorizedHostType` and the
+ * derivation switch, not by changing this grammar. Currently only `ghe`
+ * (GitHub Enterprise Server) is recognized.
+ */
+export declare function parseAuthorizedHosts(raw: string | undefined): Result<AuthorizedHost[]>;
 /** Validates that a portable root can be derived (no revisionId required). */
-export declare function tryValidateRepositoryUri(rawRepositoryUri: string): Result<{
+export declare function tryValidateRepositoryUri(rawRepositoryUri: string, options?: VcpOptions): Result<{
     leaf: string;
 }>;
 /** Mints the portable root for a repository URI + revision id. */
-export declare function tryDerivePortableRoot(rawRepositoryUri: string, revisionId: string): Result<PortableRoot>;
+export declare function tryDerivePortableRoot(rawRepositoryUri: string, revisionId: string, options?: VcpOptions): Result<PortableRoot>;
 /**
  * Default-deny: true only when the run carries ≥1 VCP entry and every entry's
  * repositoryUri classifies as a supported GitHub host. Mirrors
  * VcpPortableRoot.IsGitHubHostedRun.
  */
-export declare function isGitHubHostedRun(run: Run): boolean;
+export declare function isGitHubHostedRun(run: Run, options?: VcpOptions): boolean;
 export {};

package/dist/vcp.js

@@ -3,15 +3,52 @@
 const AZURE_DEVOPS_HOST = 'dev.azure.com';
 const AZURE_DEVOPS_SSH_HOST = 'ssh.dev.azure.com';
 const INVALID_SCP_HOST_CHARS = /[@/\\:?#\s]/;
+const AUTHORIZED_HOST_TYPES = ['ghe'];
 function ok(value) {
     return { ok: true, value };
 }
 function err(error) {
     return { ok: false, error };
 }
-function isGitHubHost(host) {
+/**
+ * Parses a comma-separated `--authorized-hosts` value of `<hostType>:<host>`
+ * tokens (e.g. `ghe:githost.contoso.com,ghe:other.example.com`) into attested
+ * hosts. A new VCS product is added by extending `AuthorizedHostType` and the
+ * derivation switch, not by changing this grammar. Currently only `ghe`
+ * (GitHub Enterprise Server) is recognized.
+ */
+export function parseAuthorizedHosts(raw) {
+    const hosts = [];
+    if (!raw?.trim())
+        return ok(hosts);
+    for (const token of raw.split(',')) {
+        const spec = token.trim();
+        if (!spec)
+            continue;
+        const colon = spec.indexOf(':');
+        if (colon <= 0 || colon === spec.length - 1) {
+            return err(`authorized host '${spec}' must take the form <hostType>:<host> (e.g. ghe:githost.contoso.com).`);
+        }
+        const type = spec.slice(0, colon).toLowerCase();
+        const host = spec.slice(colon + 1).trim().toLowerCase();
+        if (!AUTHORIZED_HOST_TYPES.includes(type)) {
+            return err(`authorized host '${spec}' uses unknown host type '${type}'; supported types: ${AUTHORIZED_HOST_TYPES.join(', ')}.`);
+        }
+        if (!host || INVALID_SCP_HOST_CHARS.test(host)) {
+            return err(`authorized host '${spec}' has an invalid host.`);
+        }
+        hosts.push({ type: type, host });
+    }
+    return ok(hosts);
+}
+function isGitHubHost(host, authorizedHosts) {
     const h = host.toLowerCase();
-    return h === 'github.com' || h.endsWith('.ghe.com');
+    if (h === 'github.com' || h.endsWith('.ghe.com'))
+        return true;
+    // A caller-attested GitHub Enterprise Server runs on a custom domain that is
+    // structurally indistinguishable from any other host, so it cannot be
+    // auto-recognized; an attested `ghe` host is classified as GitHub.
+    return authorizedHosts?.some((a) => a.type === 'ghe' && a.host.toLowerCase() === h) ?? false;
 }
 function isLegacyAzureDevOpsHost(host) {
     const h = host.toLowerCase();
@@ -123,7 +160,7 @@ function tryNormalizeToHttps(rawRepositoryUri) {
         return err('repositoryUri must be an absolute https URL, or a github-compatible ssh/scp clone URL (git@host:owner/repo).');
     }
 }
-function classify(rawRepositoryUri) {
+function classify(rawRepositoryUri, options) {
     if (!rawRepositoryUri) {
         return err('repositoryUri is required so a portable root can be derived.');
     }
@@ -144,7 +181,7 @@ function classify(rawRepositoryUri) {
     const segments = u.pathname.split('/').filter((s) => s.length > 0);
     const schemeAndServer = `${u.protocol}//${u.host}`;
     const host = u.hostname;
-    if (isGitHubHost(host)) {
+    if (isGitHubHost(host, options?.authorizedHosts)) {
         if (segments.length !== 2) {
             return err(`github repositoryUri must take the form https://<host>/<owner>/<repo>; '${display}' did not.`);
         }
@@ -187,13 +224,13 @@ function classify(rawRepositoryUri) {
     return err(`portable root derivation supports GitHub (github.com or <slug>.ghe.com) and Azure DevOps (dev.azure.com); '${display}' is not a supported host.`);
 }
 /** Validates that a portable root can be derived (no revisionId required). */
-export function tryValidateRepositoryUri(rawRepositoryUri) {
-    const c = classify(rawRepositoryUri);
+export function tryValidateRepositoryUri(rawRepositoryUri, options) {
+    const c = classify(rawRepositoryUri, options);
     return c.ok ? ok({ leaf: c.value.leaf }) : c;
 }
 /** Mints the portable root for a repository URI + revision id. */
-export function tryDerivePortableRoot(rawRepositoryUri, revisionId) {
-    const cr = classify(rawRepositoryUri);
+export function tryDerivePortableRoot(rawRepositoryUri, revisionId, options) {
+    const cr = classify(rawRepositoryUri, options);
     if (!cr.ok)
         return cr;
     const c = cr.value;
@@ -212,14 +249,14 @@ export function tryDerivePortableRoot(rawRepositoryUri, revisionId) {
  * repositoryUri classifies as a supported GitHub host. Mirrors
  * VcpPortableRoot.IsGitHubHostedRun.
  */
-export function isGitHubHostedRun(run) {
+export function isGitHubHostedRun(run, options) {
     const vcp = run.versionControlProvenance;
     if (!vcp || vcp.length === 0)
         return false;
     for (const d of vcp) {
         if (!d)
             return false;
-        const c = classify(d.repositoryUri);
+        const c = classify(d.repositoryUri, options);
         if (!c.ok || !c.value.isGitHub)
             return false;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/sarif",
-  "version": "5.4.3",
+  "version": "5.5.0",
   "description": "SARIF SDK for Node.js: open-typed object model, region/snippet resolution, AI ruleId convention, and serialization helpers. Native TypeScript; no CLR dependency.",
   "author": "Microsoft",
   "license": "MIT",