@socketsecurity/lib 5.26.1 → 5.28.0

package/dist/checks/primordials.js

@@ -0,0 +1,244 @@
+"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 primordials_exports = {};
+__export(primordials_exports, {
+  checkPrimordials: () => checkPrimordials,
+  extractPrimordialsNames: () => extractPrimordialsNames,
+  extractTsExports: () => extractTsExports,
+  resolveSocketLibPrimordials: () => resolveSocketLibPrimordials
+});
+module.exports = __toCommonJS(primordials_exports);
+var import_node_fs = require("node:fs");
+var import_node_path = __toESM(require("node:path"));
+var import_arrays = require("../arrays");
+const NAME_HEAD_RE = /^([A-Za-z_$][A-Za-z0-9_$]*)/;
+function stripComments(src) {
+  let out = src.replace(/\/\*[\s\S]*?\*\//g, "");
+  out = out.replace(/^[\t ]*\/\/.*$/gm, "");
+  out = out.replace(/[\t ]+\/\/.*$/gm, "");
+  return out;
+}
+function collectJsFiles(dir) {
+  const out = [];
+  if (!(0, import_node_fs.existsSync)(dir)) {
+    return out;
+  }
+  const stack = [dir];
+  while (stack.length > 0) {
+    const cur = stack.pop();
+    let entries;
+    try {
+      entries = (0, import_node_fs.readdirSync)(cur);
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      const full = import_node_path.default.join(cur, name);
+      let stat;
+      try {
+        stat = (0, import_node_fs.statSync)(full);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        stack.push(full);
+      } else if (stat.isFile() && full.endsWith(".js")) {
+        out.push(full);
+      }
+    }
+  }
+  return out;
+}
+function extractPrimordialsNames(src) {
+  const cleaned = stripComments(src);
+  const re = /const\s*\{\s*([^}]*?)\}\s*=\s*primordials\b/g;
+  const out = [];
+  let m;
+  while ((m = re.exec(cleaned)) !== null) {
+    for (const raw of m[1].split(",")) {
+      const trimmed = raw.trim();
+      if (!trimmed) {
+        continue;
+      }
+      const nameMatch = NAME_HEAD_RE.exec(trimmed);
+      if (nameMatch) {
+        out.push(nameMatch[1]);
+      }
+    }
+  }
+  return out;
+}
+function extractTsExports(src) {
+  const out = /* @__PURE__ */ new Set();
+  for (const m of src.matchAll(
+    /^export\s+(?:declare\s+)?const\s+([A-Za-z_$][A-Za-z0-9_$]*)/gm
+  )) {
+    out.add(m[1]);
+  }
+  for (const m of src.matchAll(
+    /^export\s+(?:declare\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)/gm
+  )) {
+    out.add(m[1]);
+  }
+  for (const m of src.matchAll(/^export\s*\{\s*([^}]+)\}/gm)) {
+    for (const raw of m[1].split(",")) {
+      const trimmed = raw.trim();
+      if (!trimmed) {
+        continue;
+      }
+      const nameMatch = NAME_HEAD_RE.exec(trimmed);
+      if (nameMatch) {
+        out.add(nameMatch[1]);
+      }
+    }
+  }
+  return [...out];
+}
+function resolveSocketLibPrimordials(config) {
+  if (config.socketLibPrimordialsPath) {
+    if (!(0, import_node_fs.existsSync)(config.socketLibPrimordialsPath)) {
+      throw new Error(
+        `socketLibPrimordialsPath does not exist: ${config.socketLibPrimordialsPath}`
+      );
+    }
+    return config.socketLibPrimordialsPath;
+  }
+  const repoRoot = config.repoRoot ?? process.cwd();
+  const sibling = import_node_path.default.resolve(
+    repoRoot,
+    "..",
+    "socket-lib",
+    "src",
+    "primordials.ts"
+  );
+  if ((0, import_node_fs.existsSync)(sibling)) {
+    return sibling;
+  }
+  const installed = import_node_path.default.resolve(
+    repoRoot,
+    "node_modules",
+    "@socketsecurity",
+    "lib",
+    "dist",
+    "primordials.d.ts"
+  );
+  if ((0, import_node_fs.existsSync)(installed)) {
+    return installed;
+  }
+  throw new Error(
+    `Cannot locate socket-lib primordials source. Looked at:
+  ${sibling}
+  ${installed}
+Either clone socket-lib at ../socket-lib or run \`pnpm install\`.`
+  );
+}
+function checkPrimordials(config) {
+  const repoRoot = config.repoRoot ?? process.cwd();
+  const used = /* @__PURE__ */ new Set();
+  const usedToFiles = /* @__PURE__ */ new Map();
+  for (const dir of config.scanDirs) {
+    const fullDir = import_node_path.default.resolve(repoRoot, dir);
+    const jsFiles = collectJsFiles(fullDir);
+    for (const file of jsFiles) {
+      let src;
+      try {
+        src = (0, import_node_fs.readFileSync)(file, "utf8");
+      } catch {
+        continue;
+      }
+      if (!src.includes("primordials")) {
+        continue;
+      }
+      const names = extractPrimordialsNames(src);
+      if (names.length === 0) {
+        continue;
+      }
+      const rel = import_node_path.default.relative(repoRoot, file);
+      for (const name of names) {
+        used.add(name);
+        const arr = usedToFiles.get(name) ?? [];
+        if (!arr.includes(rel)) {
+          arr.push(rel);
+        }
+        usedToFiles.set(name, arr);
+      }
+    }
+  }
+  const socketLibPath = resolveSocketLibPrimordials(config);
+  const socketLibNames = new Set(
+    extractTsExports((0, import_node_fs.readFileSync)(socketLibPath, "utf8"))
+  );
+  const findings = [];
+  for (const name of [...used].sort()) {
+    if (config.nodeInternalOnly.has(name)) {
+      continue;
+    }
+    if (socketLibNames.has(name)) {
+      continue;
+    }
+    const aliased = config.aliasMap.get(name);
+    if (aliased) {
+      if (socketLibNames.has(aliased)) {
+        continue;
+      }
+      findings.push({
+        kind: "missing-from-socket-lib",
+        name,
+        files: usedToFiles.get(name) ?? [],
+        hint: `\`${name}\` is mapped to socket-lib's \`${aliased}\`, but \`${aliased}\` is not exported. Add \`export const ${aliased} = ${name}\` to socket-lib/src/primordials.ts.`
+      });
+      continue;
+    }
+    findings.push({
+      kind: "unmapped",
+      name,
+      files: usedToFiles.get(name) ?? [],
+      hint: `\`${name}\` is destructured from \`primordials\` but no socket-lib mapping exists. Pick one: ` + (0, import_arrays.joinOr)([
+        `add \`${name}\` to socket-lib/src/primordials.ts`,
+        `add a \`${name}\` \u2192 \`<libName>\` entry to the alias map`,
+        `add \`${name}\` to nodeInternalOnly (if Node-internal only)`
+      ]) + "."
+    });
+  }
+  return {
+    used,
+    usedToFiles,
+    socketLibNames,
+    findings
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  checkPrimordials,
+  extractPrimordialsNames,
+  extractTsExports,
+  resolveSocketLibPrimordials
+});

package/dist/compression.d.ts

@@ -0,0 +1,218 @@
+/**
+ * @fileoverview Async compression / decompression helpers (brotli + gzip).
+ *
+ * Three calling shapes cover most use cases:
+ *
+ *   1. In-memory — compress/decompress a Buffer or string, get a Buffer
+ *      back. For payloads small enough to fit in memory.
+ *
+ *      const compressed = await compressBrotli(JSON.stringify(payload))
+ *      const original = await decompressBrotli(compressed)
+ *
+ *   2. File-to-file — stream pipeline through zlib, no memory hit.
+ *      For arbitrary-sized files (build artifacts, scan output, logs).
+ *
+ *      await compressBrotliFile('input.json', 'input.json.br')
+ *      await decompressBrotliFile('input.json.br', 'input.json')
+ *
+ *   3. Raw streams — use directly in your own pipeline. The factory
+ *      returns the underlying zlib transform so you can compose it
+ *      with anything (e.g. tar pipelines, HTTP body streams).
+ *
+ *      readable.pipe(createBrotliCompressor()).pipe(writable)
+ *
+ * Detection:
+ *
+ *   - `isBrotliCompressed(buf)` — peek the first byte for the brotli
+ *     magic-byte signature (no full parse).
+ *   - `hasBrotliExtension(path)` — `.br` / `.brotli` filename suffix.
+ *
+ * Compression-level defaults are tuned for one-shot CLI use: brotli at
+ * quality 11 (max compression, slow but it's a one-shot upload), gzip
+ * at level 6 (the zlib default). Override via the `level` option if
+ * the call is hot or the input is large.
+ */
+import { Buffer } from 'node:buffer';
+import { type BrotliOptions, type ZlibOptions } from 'node:zlib';
+export interface CompressOptions {
+    /**
+     * Compression level. Brotli accepts 0–11 (11 = max, slowest). Gzip
+     * accepts 0–9 (9 = max). Defaults: brotli 11, gzip 6.
+     */
+    level?: number | undefined;
+    /**
+     * Hint for the input size in bytes. Lets brotli pick a better
+     * window/blocking strategy. Pass when known; ignored for gzip.
+     */
+    size?: number | undefined;
+}
+/**
+ * Options for the file-to-file helpers. Pass `{ inPlace: true }` to
+ * skip the explicit destPath argument: the helper picks the
+ * canonical destination (`.br` / `.gz` suffix on compress; suffix
+ * stripped on decompress) and removes the source file on success.
+ *
+ *   await compressBrotliFile('input.json', { inPlace: true })
+ *   // => writes input.json.br, deletes input.json
+ *
+ *   await decompressBrotliFile('input.json.br', { inPlace: true })
+ *   // => writes input.json, deletes input.json.br
+ */
+export interface CompressFileOptions extends CompressOptions {
+    /**
+     * Replace the source file: derive destPath from srcPath, then
+     * `safeDelete(srcPath)` after the write succeeds. When set, the
+     * `destPath` positional argument must be omitted.
+     */
+    inPlace?: boolean | undefined;
+}
+interface ResolvedBrotliOptions extends BrotliOptions {
+    params: NonNullable<BrotliOptions['params']>;
+}
+/**
+ * Translate `CompressOptions` into the `BrotliOptions` zlib expects.
+ * Defaults `quality` to 11 (max) when not provided, and forwards a
+ * positive `size` hint. Exposed for callers building their own zlib
+ * pipelines and for unit-test coverage.
+ */
+export declare function resolveBrotliOptions(options: CompressOptions | undefined): ResolvedBrotliOptions;
+/**
+ * Translate `CompressOptions` into the `ZlibOptions` zlib expects.
+ * Returns an empty options object when no `level` is given (zlib uses
+ * its default, level 6). Exposed for parity with
+ * `resolveBrotliOptions` and for unit-test coverage.
+ */
+export declare function resolveGzipOptions(options: CompressOptions | undefined): ZlibOptions;
+/**
+ * Compress a string or Buffer with brotli. Strings are encoded as UTF-8
+ * before compression — pass an explicit Buffer if you have non-UTF-8
+ * input.
+ */
+export declare function compressBrotli(input: string | Buffer, options?: CompressOptions | undefined): Promise<Buffer>;
+/**
+ * Decompress a brotli-compressed Buffer.
+ */
+export declare function decompressBrotli(input: Buffer): Promise<Buffer>;
+/**
+ * Stream-compress a file with brotli. Two call shapes:
+ *
+ *   compressBrotliFile(src, dest, options?)
+ *     Writes compressed output to `dest`. Source is left intact.
+ *
+ *   compressBrotliFile(src, { inPlace: true, ...options })
+ *     Writes to `<src>.br` and deletes `src` after the write
+ *     succeeds. Returns the new path.
+ *
+ * Returns the destination path in both shapes — same string the
+ * caller passed in or the computed `.br` path for inPlace.
+ */
+export declare function compressBrotliFile(srcPath: string, destPath: string, options?: CompressOptions | undefined): Promise<string>;
+export declare function compressBrotliFile(srcPath: string, options: CompressFileOptions): Promise<string>;
+/**
+ * Stream-decompress a brotli file. Two call shapes:
+ *
+ *   decompressBrotliFile(src, dest)
+ *     Writes decompressed output to `dest`. Source is left intact.
+ *
+ *   decompressBrotliFile(src, { inPlace: true })
+ *     Strips the `.br`/`.brotli` suffix to derive the destination,
+ *     then deletes the compressed source after the write succeeds.
+ *     Throws if `src` has no recognizable extension.
+ *
+ * Returns the destination path in both shapes.
+ */
+export declare function decompressBrotliFile(srcPath: string, destPath: string): Promise<string>;
+export declare function decompressBrotliFile(srcPath: string, options: CompressFileOptions): Promise<string>;
+/**
+ * Create a brotli compress transform stream. Compose into your own
+ * pipeline. The `pipeline` from `node:stream/promises` is the safe
+ * way to wire it up — it handles error propagation across all stages.
+ */
+export declare function createBrotliCompressor(options?: CompressOptions | undefined): import("zlib").BrotliCompress;
+/**
+ * Create a brotli decompress transform stream.
+ */
+export declare function createBrotliDecompressor(): import("zlib").BrotliDecompress;
+/**
+ * Compress a string or Buffer with gzip. Strings are encoded as UTF-8
+ * before compression. Default level is 6 (zlib default).
+ */
+export declare function compressGzip(input: string | Buffer, options?: CompressOptions | undefined): Promise<Buffer>;
+/**
+ * Decompress a gzip-compressed Buffer.
+ */
+export declare function decompressGzip(input: Buffer): Promise<Buffer>;
+/**
+ * Stream-compress a file with gzip. Two call shapes:
+ *
+ *   compressGzipFile(src, dest, options?)
+ *     Writes compressed output to `dest`. Source is left intact.
+ *
+ *   compressGzipFile(src, { inPlace: true, ...options })
+ *     Writes to `<src>.gz` and deletes `src` after the write
+ *     succeeds. Returns the new path.
+ */
+export declare function compressGzipFile(srcPath: string, destPath: string, options?: CompressOptions | undefined): Promise<string>;
+export declare function compressGzipFile(srcPath: string, options: CompressFileOptions): Promise<string>;
+/**
+ * Stream-decompress a gzip file. Two call shapes:
+ *
+ *   decompressGzipFile(src, dest)
+ *     Writes decompressed output to `dest`. Source is left intact.
+ *
+ *   decompressGzipFile(src, { inPlace: true })
+ *     Strips the `.gz`/`.gzip`/`.tgz` suffix to derive the
+ *     destination, then deletes the compressed source after the
+ *     write succeeds. Throws if `src` has no recognizable extension.
+ */
+export declare function decompressGzipFile(srcPath: string, destPath: string): Promise<string>;
+export declare function decompressGzipFile(srcPath: string, options: CompressFileOptions): Promise<string>;
+/**
+ * Create a gzip compress transform stream.
+ */
+export declare function createGzipCompressor(options?: CompressOptions | undefined): import("zlib").Gzip;
+/**
+ * Create a gzip decompress transform stream.
+ */
+export declare function createGzipDecompressor(): import("zlib").Gunzip;
+/**
+ * Cheap pre-flight check: does the buffer look like it could be
+ * brotli? Returns false for inputs too short to be valid. Brotli has
+ * no fixed magic bytes, so this is intentionally permissive — the
+ * authoritative test is `decompressBrotli(buf)` succeeding. Use for
+ * UI hints, not correctness.
+ */
+export declare function isBrotliCompressed(input: Buffer): boolean;
+/**
+ * Magic-byte check for gzip. Reads the first two bytes and matches
+ * the gzip spec's 0x1f 0x8b signature. Authoritative.
+ */
+export declare function isGzipCompressed(input: Buffer): boolean;
+export declare const BROTLI_EXTS: ReadonlySet<string>;
+export declare const GZIP_EXTS: ReadonlySet<string>;
+/**
+ * Extension check for brotli paths — matches `.br` / `.brotli`
+ * (case-insensitive). Naming follows node:path's `extname`.
+ */
+export declare function hasBrotliExt(filePath: string): boolean;
+/**
+ * Extension check for gzip paths — matches `.gz` / `.gzip` / `.tgz`
+ * (case-insensitive). Naming follows node:path's `extname`.
+ */
+export declare function hasGzipExt(filePath: string): boolean;
+/**
+ * Strip the trailing extension from a filename when it matches one of
+ * `exts`. Returns the input unchanged when the trailing extname isn't
+ * in the set. Case-insensitive on the extension — preserves the rest
+ * of the path's casing.
+ *
+ * The `exts` set decides what counts. Pass `BROTLI_EXTS` / `GZIP_EXTS`
+ * (re-exported from this module) for the canonical compression sets,
+ * or your own set for custom classifiers.
+ *
+ * This helper is generic — it does NOT know that `.tgz` is short for
+ * `.tar.gz`. Callers that need that convention compose this with their
+ * own follow-up (see `decompressGzipFile` for the canonical example).
+ */
+export declare function stripExt(filePath: string, exts: ReadonlySet<string>): string;
+export {};