@microsoft/sarif 0.0.1 → 5.2.0

package/dist/skill.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Rewrites every repository-relative markdown link in `markdown` to a raw
+ * permalink pinned to `pinRef`. Absolute URLs, protocol-relative URLs, and
+ * bare fragments are left untouched.
+ */
+export declare function rewriteRelativeLinks(markdown: string, skillSourceDirectory: string, pinRef: string): string;
+/**
+ * Extracts the `description:` scalar from a skill document's leading YAML
+ * frontmatter block. Returns undefined when the document has no frontmatter,
+ * declares no description, or uses a multi-line block scalar.
+ */
+export declare function extractFrontmatterDescription(document: string): string | undefined;

package/dist/skill.js

@@ -0,0 +1,81 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * Shared helper for packages that ship a SKILL.md: rewrites repository-relative
+ * markdown links to commit-pinned raw permalinks so the emitted skill resolves
+ * its references against the exact repository state that shipped the package.
+ *
+ * Ported from src/Sarif.Multitool.Library/GetSkill/GetSkillCommand.cs
+ * (RewriteRelativeLinks / ResolveRepositoryRelative / IsRepositoryRelative).
+ */
+const RAW_CONTENT_BASE_URL = 'https://raw.githubusercontent.com/microsoft/sarif-sdk/';
+const MARKDOWN_LINK = /\]\(([^)\s]+)(\s+"[^"]*")?\)/g;
+const URI_SCHEME = /^[a-zA-Z][a-zA-Z0-9+.\-]*:/;
+/**
+ * Rewrites every repository-relative markdown link in `markdown` to a raw
+ * permalink pinned to `pinRef`. Absolute URLs, protocol-relative URLs, and
+ * bare fragments are left untouched.
+ */
+export function rewriteRelativeLinks(markdown, skillSourceDirectory, pinRef) {
+    return markdown.replace(MARKDOWN_LINK, (match, url, title) => {
+        if (!isRepositoryRelative(url))
+            return match;
+        const fragmentIdx = url.indexOf('#');
+        const path = fragmentIdx >= 0 ? url.slice(0, fragmentIdx) : url;
+        const fragment = fragmentIdx >= 0 ? url.slice(fragmentIdx) : '';
+        const repoPath = resolveRepositoryRelative(skillSourceDirectory, path);
+        return `](${RAW_CONTENT_BASE_URL}${pinRef}/${repoPath}${fragment}${title ?? ''})`;
+    });
+}
+function isRepositoryRelative(url) {
+    if (!url)
+        return false;
+    if (url[0] === '#')
+        return false;
+    if (url.startsWith('//'))
+        return false;
+    if (URI_SCHEME.test(url))
+        return false;
+    return true;
+}
+function resolveRepositoryRelative(baseDirectory, relativePath) {
+    const segments = baseDirectory.split('/').filter((s) => s.length > 0);
+    for (const segment of relativePath.split('/')) {
+        if (segment.length === 0 || segment === '.')
+            continue;
+        if (segment === '..') {
+            if (segments.length > 0)
+                segments.pop();
+            continue;
+        }
+        segments.push(segment);
+    }
+    return segments.join('/');
+}
+/**
+ * Extracts the `description:` scalar from a skill document's leading YAML
+ * frontmatter block. Returns undefined when the document has no frontmatter,
+ * declares no description, or uses a multi-line block scalar.
+ */
+export function extractFrontmatterDescription(document) {
+    if (!document)
+        return undefined;
+    const lines = document.split(/\r?\n/);
+    if (lines[0]?.trim() !== '---')
+        return undefined;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === '---')
+            return undefined;
+        const m = /^description:[ \t]*(.+?)[ \t]*$/.exec(lines[i]);
+        if (!m)
+            continue;
+        let value = m[1];
+        if (value.length >= 2 && (value[0] === '"' || value[0] === "'") && value.at(-1) === value[0]) {
+            value = value.slice(1, -1);
+        }
+        if (/^[>|][0-9+\-]*$/.test(value))
+            return undefined;
+        return value;
+    }
+    return undefined;
+}

package/dist/vcp.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Single source of truth for turning a `versionControlProvenance.repositoryUri`
+ * into a portable artifact root. emit-run validates the shape at receipt;
+ * emit-finalize mints the root.
+ *
+ * Ported from src/Sarif.Multitool.Library/Emit/VcpPortableRoot.cs.
+ */
+import type { Run } from './sarif.js';
+export interface PortableRoot {
+    portableRoot: string;
+    canonicalRepositoryUri: string;
+    leaf: string;
+    revisionWebUrl: string;
+}
+type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+/** Validates that a portable root can be derived (no revisionId required). */
+export declare function tryValidateRepositoryUri(rawRepositoryUri: string): Result<{
+    leaf: string;
+}>;
+/** Mints the portable root for a repository URI + revision id. */
+export declare function tryDerivePortableRoot(rawRepositoryUri: string, revisionId: string): 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 {};

package/dist/vcp.js

@@ -0,0 +1,227 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+const AZURE_DEVOPS_HOST = 'dev.azure.com';
+const AZURE_DEVOPS_SSH_HOST = 'ssh.dev.azure.com';
+const INVALID_SCP_HOST_CHARS = /[@/\\:?#\s]/;
+function ok(value) {
+    return { ok: true, value };
+}
+function err(error) {
+    return { ok: false, error };
+}
+function isGitHubHost(host) {
+    const h = host.toLowerCase();
+    return h === 'github.com' || h.endsWith('.ghe.com');
+}
+function isLegacyAzureDevOpsHost(host) {
+    const h = host.toLowerCase();
+    return h === 'visualstudio.com' || h.endsWith('.visualstudio.com');
+}
+function sanitizeForDisplay(u) {
+    // Never echo credentials or query/fragment in diagnostics.
+    return `${u.protocol}//${u.host}${u.pathname}`;
+}
+function isSingleSafeSegment(rawSegment) {
+    if (!rawSegment)
+        return false;
+    const decoded = decodeURIComponent(rawSegment);
+    return (decoded.length !== 0 &&
+        decoded !== '.' &&
+        decoded !== '..' &&
+        !decoded.includes('/') &&
+        !decoded.includes('\\'));
+}
+function normalizeRepoSegment(rawSegment) {
+    let repo = rawSegment;
+    if (repo.toLowerCase().endsWith('.git'))
+        repo = repo.slice(0, -4);
+    const decoded = decodeURIComponent(repo);
+    if (decoded.length === 0 ||
+        decoded === '.' ||
+        decoded === '..' ||
+        decoded.includes('/') ||
+        decoded.includes('\\')) {
+        return err('the repository name is empty or is not a single valid path segment.');
+    }
+    return ok({ repoForUrl: repo, leaf: decoded });
+}
+// scp syntax: [user@]host:path with no scheme and no slash before the colon.
+function tryParseScp(raw) {
+    if (!raw || raw.includes('://'))
+        return undefined;
+    const colon = raw.indexOf(':');
+    if (colon < 0)
+        return undefined;
+    const authority = raw.slice(0, colon);
+    if (authority.length === 0 || authority.includes('/'))
+        return undefined;
+    let userInfo = '';
+    let host;
+    const at = authority.indexOf('@');
+    if (at >= 0) {
+        if (authority.indexOf('@', at + 1) >= 0)
+            return undefined; // ambiguous double @
+        userInfo = authority.slice(0, at);
+        host = authority.slice(at + 1);
+        if (userInfo.length === 0)
+            return undefined;
+    }
+    else {
+        host = authority;
+    }
+    if (host.length === 0 || INVALID_SCP_HOST_CHARS.test(host))
+        return undefined;
+    const path = raw.slice(colon + 1);
+    if (path.includes('@'))
+        return undefined; // colon was inside user:password
+    if (path.length === 0)
+        return undefined;
+    return { host, userInfo, path };
+}
+function tryNormalizeToHttps(rawRepositoryUri) {
+    // Try absolute URL first.
+    let absolute;
+    try {
+        absolute = new URL(rawRepositoryUri);
+    }
+    catch {
+        /* maybe scp form */
+    }
+    if (absolute && absolute.protocol === 'https:')
+        return ok(absolute);
+    let host, userInfo, path;
+    if (absolute && absolute.protocol === 'ssh:') {
+        if (absolute.port) {
+            return err('an ssh repositoryUri must use the default port; supply the https clone URL instead.');
+        }
+        if (absolute.search || absolute.hash) {
+            return err('an ssh repositoryUri must be a bare clone URL with no query or fragment; supply the https clone URL instead.');
+        }
+        host = absolute.hostname;
+        userInfo = absolute.username + (absolute.password ? `:${absolute.password}` : '');
+        path = absolute.pathname;
+    }
+    else {
+        const scp = tryParseScp(rawRepositoryUri);
+        if (!scp) {
+            return err('repositoryUri must be an absolute https URL, or a github-compatible ssh/scp clone URL (git@host:owner/repo).');
+        }
+        ({ host, userInfo, path } = scp);
+    }
+    if (userInfo.includes(':')) {
+        return err('a repositoryUri carrying credentials (user:password@) cannot be used to derive a portable root.');
+    }
+    const normalizedPath = path.replace(/\\/g, '/').replace(/^\/+/, '');
+    if (host.toLowerCase() === AZURE_DEVOPS_SSH_HOST ||
+        normalizedPath.toLowerCase().startsWith('v3/')) {
+        return err('azure devops ssh repositoryUri normalization is not supported; supply the https clone URL (https://dev.azure.com/<org>/<project>/_git/<repo>).');
+    }
+    try {
+        return ok(new URL(`https://${host}/${normalizedPath}`));
+    }
+    catch {
+        return err('repositoryUri must be an absolute https URL, or a github-compatible ssh/scp clone URL (git@host:owner/repo).');
+    }
+}
+function classify(rawRepositoryUri) {
+    if (!rawRepositoryUri) {
+        return err('repositoryUri is required so a portable root can be derived.');
+    }
+    const norm = tryNormalizeToHttps(rawRepositoryUri);
+    if (!norm.ok)
+        return norm;
+    const u = norm.value;
+    const display = sanitizeForDisplay(u);
+    if (u.port) {
+        return err(`repositoryUri '${display}' must use the host's default port.`);
+    }
+    if (u.search || u.hash) {
+        return err(`repositoryUri '${display}' must be a bare repository URL with no query or fragment.`);
+    }
+    if (u.username || u.password) {
+        return err('a repositoryUri must not carry embedded credentials (no account@ or account:password@); supply the clean https repository URL.');
+    }
+    const segments = u.pathname.split('/').filter((s) => s.length > 0);
+    const schemeAndServer = `${u.protocol}//${u.host}`;
+    const host = u.hostname;
+    if (isGitHubHost(host)) {
+        if (segments.length !== 2) {
+            return err(`github repositoryUri must take the form https://<host>/<owner>/<repo>; '${display}' did not.`);
+        }
+        const repo = normalizeRepoSegment(segments[1]);
+        if (!repo.ok)
+            return err(`github repositoryUri '${display}': ${repo.error}`);
+        return ok({
+            isGitHub: true,
+            isAzureDevOps: false,
+            schemeAndServer,
+            owner: segments[0],
+            repoForUrl: repo.value.repoForUrl,
+            leaf: repo.value.leaf,
+            display,
+        });
+    }
+    if (host.toLowerCase() === AZURE_DEVOPS_HOST) {
+        if (segments.length !== 4 || segments[2].toLowerCase() !== '_git') {
+            return err(`azure devops repositoryUri must take the form https://dev.azure.com/<org>/<project>/_git/<repo>; '${display}' did not.`);
+        }
+        if (!isSingleSafeSegment(segments[0]) || !isSingleSafeSegment(segments[1])) {
+            return err(`azure devops repositoryUri '${display}': the organization and project must each be a single valid path segment.`);
+        }
+        const repo = normalizeRepoSegment(segments[3]);
+        if (!repo.ok)
+            return err(`azure devops repositoryUri '${display}': ${repo.error}`);
+        return ok({
+            isGitHub: false,
+            isAzureDevOps: true,
+            schemeAndServer,
+            adoPrefix: `${segments[0]}/${segments[1]}`,
+            repoForUrl: repo.value.repoForUrl,
+            leaf: repo.value.leaf,
+            display,
+        });
+    }
+    if (isLegacyAzureDevOpsHost(host)) {
+        return err(`the legacy Azure DevOps host form is not supported; supply the repository as https://dev.azure.com/<org>/<project>/_git/<repo>. '${display}' did not.`);
+    }
+    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);
+    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);
+    if (!cr.ok)
+        return cr;
+    const c = cr.value;
+    const canonicalRepositoryUri = c.display;
+    const rev = encodeURIComponent(revisionId);
+    const portableRoot = c.isAzureDevOps
+        ? `${c.schemeAndServer}/${c.adoPrefix}/_git/${c.repoForUrl}/`
+        : `${c.schemeAndServer}/${c.owner}/${c.repoForUrl}/blob/${rev}/`;
+    const revisionWebUrl = c.isAzureDevOps
+        ? `${c.schemeAndServer}/${c.adoPrefix}/_git/${c.repoForUrl}?version=GC${rev}`
+        : `${c.schemeAndServer}/${c.owner}/${c.repoForUrl}/tree/${rev}`;
+    return ok({ portableRoot, canonicalRepositoryUri, leaf: c.leaf, revisionWebUrl });
+}
+/**
+ * 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 function isGitHubHostedRun(run) {
+    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);
+        if (!c.ok || !c.value.isGitHub)
+            return false;
+    }
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/sarif",
-  "version": "0.0.1",
+  "version": "5.2.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",
@@ -30,7 +30,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc"
+    "build": "tsc && node scripts/generate-serialization-model.mjs",
+    "test": "npm run build && node --test test/insertOptionalData.test.js test/regions.test.js test/rollingHash.test.js test/vcp.test.js"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",