@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/github/refs.js

@@ -0,0 +1,67 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var refs_exports = {};
+__export(refs_exports, {
+  clearRefCache: () => import_refs_cache2.clearRefCache,
+  fetchRefSha: () => import_refs_rest2.fetchRefSha,
+  fetchRefShaViaGraphQL: () => import_refs_graphql.fetchRefShaViaGraphQL,
+  getGithubCache: () => import_refs_cache2.getGithubCache,
+  resolveRefToSha: () => resolveRefToSha
+});
+module.exports = __toCommonJS(refs_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_refs_rest = require("./refs-rest");
+var import_refs_cache = require("./refs-cache");
+var import_refs_cache2 = require("./refs-cache");
+var import_refs_graphql = require("./refs-graphql");
+var import_refs_rest2 = require("./refs-rest");
+async function resolveRefToSha(owner, repo, ref, options) {
+  const opts = {
+    __proto__: null,
+    ...options
+  };
+  const cacheKey = `${owner}/${repo}@${ref}`;
+  if (import_node_process.default.env["DISABLE_GITHUB_CACHE"]) {
+    return await (0, import_refs_rest.fetchRefSha)(owner, repo, ref, opts);
+  }
+  const cache = (0, import_refs_cache.getGithubCache)();
+  return await cache.getOrFetch(cacheKey, async () => {
+    return await (0, import_refs_rest.fetchRefSha)(owner, repo, ref, opts);
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearRefCache,
+  fetchRefSha,
+  fetchRefShaViaGraphQL,
+  getGithubCache,
+  resolveRefToSha
+});

package/dist/github/token.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @file GitHub token resolution. Three sources, in priority order: environment
+ *   variables, then `git config github.token`. The combined fallback
+ *   (`getGitHubTokenWithFallback`) is what most callers want; the individual
+ *   helpers exist so callers can constrain the search (e.g., env-only contexts
+ *   where shelling out to git would be wrong).
+ */
+import type { SpawnOptions } from '../spawn/types';
+/**
+ * Get GitHub authentication token from environment variables. Checks multiple
+ * environment variable names in priority order.
+ *
+ * Environment variables checked (in order):
+ *
+ * 1. `GITHUB_TOKEN` - Standard GitHub token variable
+ * 2. `GH_TOKEN` - Alternative GitHub CLI token variable
+ * 3. `SOCKET_CLI_GITHUB_TOKEN` - Socket-specific token variable
+ *
+ * @example
+ *   ;```ts
+ *   const token = getGitHubToken()
+ *   if (!token) {
+ *     console.warn('No GitHub token found')
+ *   }
+ *   ```
+ *
+ * @returns The first available GitHub token, or `undefined` if none found
+ */
+export declare function getGitHubToken(): string | undefined;
+/**
+ * Get GitHub authentication token from git config. Reads the `github.token`
+ * configuration value from git config. This is a fallback method when
+ * environment variables don't contain a token.
+ *
+ * @example
+ *   ;```ts
+ *   const token = await getGitHubTokenFromGitConfig()
+ *   if (token) {
+ *     console.log('Found token in git config')
+ *   }
+ *   ```
+ *
+ * @example
+ *   ;```ts
+ *   // With custom working directory
+ *   const token = await getGitHubTokenFromGitConfig({
+ *     cwd: '/path/to/repo',
+ *   })
+ *   ```
+ *
+ * @param options - Spawn options for git command execution.
+ *
+ * @returns GitHub token from git config, or `undefined` if not configured
+ */
+export declare function getGitHubTokenFromGitConfig(options?: SpawnOptions | undefined): Promise<string | undefined>;
+/**
+ * Get GitHub authentication token from all available sources. Checks
+ * environment variables first, then falls back to git config. This is the
+ * recommended way to get a GitHub token with maximum compatibility.
+ *
+ * Priority order:
+ *
+ * 1. Environment variables (GITHUB_TOKEN, GH_TOKEN, SOCKET_CLI_GITHUB_TOKEN)
+ * 2. Git config (github.token)
+ *
+ * @example
+ *   ;```ts
+ *   const token = await getGitHubTokenWithFallback()
+ *   if (!token) {
+ *     throw new ErrorCtor('GitHub token required')
+ *   }
+ *   ```
+ *
+ * @returns GitHub token from first available source, or `undefined` if none
+ *   found.
+ */
+export declare function getGitHubTokenWithFallback(): Promise<string | undefined>;

package/dist/github/token.js

@@ -0,0 +1,55 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var token_exports = {};
+__export(token_exports, {
+  getGitHubToken: () => getGitHubToken,
+  getGitHubTokenFromGitConfig: () => getGitHubTokenFromGitConfig,
+  getGitHubTokenWithFallback: () => getGitHubTokenWithFallback
+});
+module.exports = __toCommonJS(token_exports);
+var import_github = require("../env/github");
+var import_socket_cli = require("../env/socket-cli");
+var import_spawn = require("../spawn/spawn");
+function getGitHubToken() {
+  return (0, import_github.getGithubToken)() || (0, import_github.getGhToken)() || (0, import_socket_cli.getSocketCliGithubToken)() || void 0;
+}
+async function getGitHubTokenFromGitConfig(options) {
+  try {
+    const result = await (0, import_spawn.spawn)("git", ["config", "github.token"], {
+      ...options,
+      stdio: "pipe"
+    });
+    if (result.code === 0 && result.stdout) {
+      return result.stdout.toString().trim();
+    }
+  } catch {
+  }
+  return void 0;
+}
+async function getGitHubTokenWithFallback() {
+  return getGitHubToken() || await getGitHubTokenFromGitConfig();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getGitHubToken,
+  getGitHubTokenFromGitConfig,
+  getGitHubTokenWithFallback
+});

package/dist/github/types.d.ts

@@ -0,0 +1,277 @@
+/**
+ * @file Public type surface for `github/*` modules — pure interfaces. No I/O or
+ *   runtime side effects so this module stays cheap to import everywhere.
+ *   Constants live in `./constants`, named errors in `./errors`.
+ */
+/**
+ * Options for GitHub API fetch requests.
+ */
+export interface GitHubFetchOptions {
+    /**
+     * GitHub authentication token. If not provided, will attempt to use token
+     * from environment variables.
+     */
+    token?: string | undefined;
+    /**
+     * Additional HTTP headers to include in the request. Will be merged with
+     * default headers (Accept, User-Agent, Authorization).
+     */
+    headers?: Record<string, string> | undefined;
+}
+/**
+ * Error thrown when GitHub API rate limit is exceeded. Extends the standard
+ * Error with additional rate limit information.
+ */
+export interface GitHubRateLimitError extends Error {
+    /**
+     * HTTP status code (always 403 for rate limit errors)
+     */
+    status: number;
+    /**
+     * Date when the rate limit will reset. Undefined if reset time is not
+     * available in response headers.
+     */
+    resetTime?: Date | undefined;
+}
+/**
+ * GitHub ref object returned by the API. Represents a git reference (tag or
+ * branch).
+ */
+export interface GitHubRef {
+    /**
+     * The object this ref points to.
+     */
+    object: {
+        /**
+         * SHA of the commit or tag object.
+         */
+        sha: string;
+        /**
+         * Type of object ('commit' or 'tag')
+         */
+        type: string;
+        /**
+         * API URL to fetch the full object details.
+         */
+        url: string;
+    };
+    /**
+     * Full ref path (e.g., 'refs/tags/v1.0.0' or 'refs/heads/main')
+     */
+    ref: string;
+    /**
+     * API URL for this ref.
+     */
+    url: string;
+}
+/**
+ * GitHub annotated tag object returned by the API. Represents a git tag with
+ * metadata.
+ */
+export interface GitHubTag {
+    /**
+     * Tag annotation message.
+     */
+    message: string;
+    /**
+     * The commit this tag points to.
+     */
+    object: {
+        /**
+         * SHA of the commit.
+         */
+        sha: string;
+        /**
+         * Type of object (usually 'commit')
+         */
+        type: string;
+        /**
+         * API URL to fetch the commit details.
+         */
+        url: string;
+    };
+    /**
+     * SHA of this tag object itself.
+     */
+    sha: string;
+    /**
+     * Tag name (e.g., 'v1.0.0')
+     */
+    tag: string;
+    /**
+     * Information about who created the tag. Undefined for lightweight tags.
+     */
+    tagger?: {
+        /**
+         * Tag creation date in ISO 8601 format.
+         */
+        date: string;
+        /**
+         * Tagger's email address.
+         */
+        email: string;
+        /**
+         * Tagger's name.
+         */
+        name: string;
+    };
+    /**
+     * API URL for this tag object.
+     */
+    url: string;
+}
+/**
+ * GitHub commit object returned by the API. Represents a git commit with
+ * metadata.
+ */
+export interface GitHubCommit {
+    /**
+     * Full commit SHA.
+     */
+    sha: string;
+    /**
+     * API URL for this commit.
+     */
+    url: string;
+    /**
+     * Commit details.
+     */
+    commit: {
+        /**
+         * Commit message.
+         */
+        message: string;
+        /**
+         * Author information.
+         */
+        author: {
+            /**
+             * Commit author date in ISO 8601 format.
+             */
+            date: string;
+            /**
+             * Author's email address.
+             */
+            email: string;
+            /**
+             * Author's name.
+             */
+            name: string;
+        };
+    };
+}
+/**
+ * Options for resolving git refs to commit SHAs.
+ */
+export interface ResolveRefOptions {
+    /**
+     * GitHub authentication token. If not provided, will attempt to use token
+     * from environment variables.
+     */
+    token?: string | undefined;
+}
+/**
+ * GitHub Security Advisory (GHSA) details. Represents a complete security
+ * advisory from GitHub's database.
+ */
+export interface GhsaDetails {
+    /**
+     * GHSA identifier (e.g., 'GHSA-xxxx-yyyy-zzzz')
+     */
+    ghsaId: string;
+    /**
+     * Short summary of the vulnerability.
+     */
+    summary: string;
+    /**
+     * Detailed description of the vulnerability.
+     */
+    details: string;
+    /**
+     * Severity level ('low', 'moderate', 'high', 'critical')
+     */
+    severity: string;
+    /**
+     * Alternative identifiers (CVE IDs, etc.)
+     */
+    aliases: string[];
+    /**
+     * ISO 8601 timestamp when advisory was published.
+     */
+    publishedAt: string;
+    /**
+     * ISO 8601 timestamp when advisory was last updated.
+     */
+    updatedAt: string;
+    /**
+     * ISO 8601 timestamp when advisory was withdrawn. `null` if advisory is still
+     * active.
+     */
+    withdrawnAt: string | null;
+    /**
+     * External reference URLs for more information.
+     */
+    references: Array<{
+        url: string;
+    }>;
+    /**
+     * Affected packages and version ranges.
+     */
+    vulnerabilities: Array<{
+        /**
+         * Package information.
+         */
+        package: {
+            /**
+             * Ecosystem (e.g., 'npm', 'pip', 'maven')
+             */
+            ecosystem: string;
+            /**
+             * Package name.
+             */
+            name: string;
+        };
+        /**
+         * Version range expression for vulnerable versions.
+         */
+        vulnerableVersionRange: string;
+        /**
+         * First patched version that fixes the vulnerability. `null` if no patched
+         * version exists yet.
+         */
+        firstPatchedVersion: {
+            identifier: string;
+        } | null;
+    }>;
+    /**
+     * CVSS (Common Vulnerability Scoring System) information. `null` if CVSS
+     * score is not available.
+     */
+    cvss: {
+        /**
+         * CVSS score (0.0-10.0)
+         */
+        score: number;
+        /**
+         * CVSS vector string describing the vulnerability characteristics.
+         */
+        vectorString: string;
+    } | null;
+    /**
+     * CWE (Common Weakness Enumeration) categories.
+     */
+    cwes: Array<{
+        /**
+         * CWE identifier (e.g., 'CWE-79')
+         */
+        cweId: string;
+        /**
+         * Human-readable CWE name.
+         */
+        name: string;
+        /**
+         * Description of the weakness category.
+         */
+        description: string;
+    }>;
+}

package/dist/github/types.js

@@ -0,0 +1,18 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/globs/_internal.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @file Private internals for `globs/*` modules — lazy module accessors,
+ *   normalization helpers, and the matcher LRU cache. The `defaultIgnore` list
+ *   lives in the public `defaults.ts` file; this file re-exports it so
+ *   co-located helpers can import everything through one path.
+ */
+import { defaultIgnore } from './defaults';
+import type * as fastGlobType from '../external/fast-glob';
+import type picomatchType from '../external/picomatch';
+export { defaultIgnore };
+export declare const MATCHER_CACHE_MAX_SIZE = 100;
+export declare const matcherCache: Map<string, (path: string) => boolean>;
+export { getNodeFs as getFs } from '../node/fs';
+export { getNodeFsPromises as getFsPromises } from '../node/fs-promises';
+export declare function getFastGlob(): typeof fastGlobType;
+export declare function getPicomatch(): typeof picomatchType;
+/**
+ * Glob results are normalized to forward slashes regardless of the backend
+ * (node:fs.glob returns native-OS separators on Windows; fast-glob already
+ * returns forward slashes). Single contract: callers don't have to think about
+ * separators per platform. Routes through `paths/normalize.normalizePath` so
+ * this stays consistent with every other path-shaped string in the lib.
+ */
+export declare function normalizeGlobResults(out: string[]): string[];
+/**
+ * Normalize a user-provided ignore array by running every entry through
+ * stripTrailingSlash. Returns undefined when `ignore` is not an array so
+ * callers can skip merging the option entirely.
+ *
+ * Uses a pre-sized for-loop instead of `.map`: socket-lib uses primordials (the
+ * prototype `Array.prototype.map` can be intercepted or replaced by user code
+ * at module load), and a hand-rolled loop is also marginally faster — no
+ * callback indirection, no growth of the result array.
+ */
+export declare function normalizeIgnorePatterns(ignore: unknown): string[] | undefined;
+/**
+ * Strip a trailing `/` from a glob pattern so fast-glob's deep filter matches
+ * it. See header comment in `glob.ts` for the full rationale — shortest
+ * summary: a `dist/` ignore pattern lets fast-glob walk the whole subtree
+ * before filtering, while `dist` (no slash) skips the walk entirely.
+ *
+ * CharCode 47 is `/`. Reading it that way avoids a per-call string allocation
+ * for the literal — primordials-friendly, no behavior change vs.
+ * `pattern.endsWith('/')`.
+ */
+export declare function stripTrailingSlash(pattern: string): string;

package/dist/globs/_internal.js

@@ -0,0 +1,96 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var internal_exports = {};
+__export(internal_exports, {
+  MATCHER_CACHE_MAX_SIZE: () => MATCHER_CACHE_MAX_SIZE,
+  defaultIgnore: () => import_defaults.defaultIgnore,
+  getFastGlob: () => getFastGlob,
+  getFs: () => import_fs.getNodeFs,
+  getFsPromises: () => import_fs_promises.getNodeFsPromises,
+  getPicomatch: () => getPicomatch,
+  matcherCache: () => matcherCache,
+  normalizeGlobResults: () => normalizeGlobResults,
+  normalizeIgnorePatterns: () => normalizeIgnorePatterns,
+  stripTrailingSlash: () => stripTrailingSlash
+});
+module.exports = __toCommonJS(internal_exports);
+var import_array = require("../primordials/array");
+var import_map_set = require("../primordials/map-set");
+var import_string = require("../primordials/string");
+var import_normalize = require("../paths/normalize");
+var import_defaults = require("./defaults");
+var import_fs = require("../node/fs");
+var import_fs_promises = require("../node/fs-promises");
+const MATCHER_CACHE_MAX_SIZE = 100;
+const matcherCache = new import_map_set.MapCtor();
+let _fastGlob;
+let _picomatch;
+// @__NO_SIDE_EFFECTS__
+function getFastGlob() {
+  if (_fastGlob === void 0) {
+    _fastGlob = require("../external/fast-glob.js");
+  }
+  return _fastGlob;
+}
+// @__NO_SIDE_EFFECTS__
+function getPicomatch() {
+  if (_picomatch === void 0) {
+    _picomatch = require("../external/picomatch.js");
+  }
+  return _picomatch;
+}
+function normalizeGlobResults(out) {
+  for (let i = 0; i < out.length; i += 1) {
+    out[i] = (0, import_normalize.normalizePath)(out[i]);
+  }
+  return out;
+}
+function normalizeIgnorePatterns(ignore) {
+  if (!(0, import_array.ArrayIsArray)(ignore)) {
+    return void 0;
+  }
+  const source = ignore;
+  const { length } = source;
+  const normalized = new import_array.ArrayCtor(length);
+  for (let i = 0; i < length; i++) {
+    normalized[i] = stripTrailingSlash(source[i]);
+  }
+  return normalized;
+}
+function stripTrailingSlash(pattern) {
+  if (pattern.length > 1 && (0, import_string.StringPrototypeCharCodeAt)(pattern, pattern.length - 1) === 47) {
+    return pattern.slice(0, -1);
+  }
+  return pattern;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MATCHER_CACHE_MAX_SIZE,
+  defaultIgnore,
+  getFastGlob,
+  getFs,
+  getFsPromises,
+  getPicomatch,
+  matcherCache,
+  normalizeGlobResults,
+  normalizeIgnorePatterns,
+  stripTrailingSlash
+});

package/dist/globs/defaults.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file The npm-packlist-derived `defaultIgnore` list. Public starting point
+ *   for caller-customized ignore arrays — also consumed internally by
+ *   `_internal` (matcher / stream callers fall back to this list when no
+ *   `ignore` option is supplied).
+ */
+export declare const defaultIgnore: readonly string[];