@socketsecurity/lib 5.27.0 → 5.28.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.28.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.28.0) - 2026-05-06
+
+### Added
+
+- **`compression` (new export)** — brotli + gzip helpers with three calling shapes (in-memory `Buffer`, file-to-file, raw streams) and a single `{ inPlace: true }` option for compress/decompress-in-place. 28 named exports total:
+  - In-memory: `compressBrotli`, `decompressBrotli`, `compressGzip`, `decompressGzip`
+  - File-to-file: `compressBrotliFile`, `decompressBrotliFile`, `compressGzipFile`, `decompressGzipFile` — each with three overloads (explicit dest, in-place, options object). The gzip in-place path follows `.tgz` → `.tar` convention so a round-trip is lossless
+  - Streams: `createBrotliCompressor`, `createBrotliDecompressor`, `createGzipCompressor`, `createGzipDecompressor`
+  - Detection: `isBrotliCompressed(buffer)` / `isGzipCompressed(buffer)` (magic-byte sniffing)
+  - Path classification: `hasBrotliExt(filePath)` / `hasGzipExt(filePath)` — case-insensitive `path.extname` match against `.br` / `.brotli` / `.gz` / `.gzip` / `.tgz`
+  - Helpers: `BROTLI_EXTS` / `GZIP_EXTS` `ReadonlySet<string>` constants; `stripExt(filePath, exts)` for trimming a recognized extension from a path; `resolveBrotliOptions` / `resolveGzipOptions` for translating `CompressOptions` into the underlying zlib option shapes
+  - `CompressOptions` / `CompressFileOptions` interfaces
+- **`socket-lib` CLI (new `bin` entry)** — fleet-wide static-analysis dispatcher invoked via `pnpm exec socket-lib <command>`. Initial subcommand: `check primordials` (alias `check prim`) — diffs every name destructured from `primordials` in scanned source against `@socketsecurity/lib`'s exposed primordials set, emitting unmapped or missing-from-lib findings. Reads sectional config from `.socket-lib.json` (with `.config/socket-lib.json` as a fallback) or a bare object for single-check setups. Flags: `--config / -c <path>` (defaults to `.socket-lib.json`, falls back to `.config/socket-lib.json`), `--explain`, `--json`, `--silent`, `--help`. Lifted from socket-btm's `scripts/check-primordials-coverage.mts` so the same drift gate now ships to every consumer.
+- **`dlx/package` `installRoot` option** — new `EnsurePackageInstallOptions` (and `DlxPackageOptions`) field overriding the install root passed to Arborist. Default remains `~/.socket/_dlx/<cacheKey>/`; when set, the value is used verbatim. Lets build pipelines colocate the install with their own gitignored outputs (e.g. ink-builder bundling ink via esbuild). Caller owns per-spec separation; see JSDoc for the full contract.
+
 ## [5.27.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.27.0) - 2026-05-04
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 [![Socket Badge](https://socket.dev/api/badge/npm/package/@socketsecurity/lib)](https://socket.dev/npm/package/@socketsecurity/lib)
 [![CI](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml)
-![Coverage](https://img.shields.io/badge/coverage-84%25-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-85%25-brightgreen)
 
 [![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
 [![Follow @socket.dev on Bluesky](https://img.shields.io/badge/Follow-@socket.dev-1DA1F2?style=social&logo=bluesky)](https://bsky.app/profile/socket.dev)

package/dist/bin/check-primordials.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview `socket-lib check primordials` handler.
+ *
+ * Loads a JSON config from disk (default
+ * `primordials-coverage.config.json` at the repo root, override with
+ * `--config <path>`), runs the drift check, and renders the result.
+ *
+ *   socket-lib check primordials
+ *   socket-lib check primordials --config ./primordials.config.json
+ *   socket-lib check primordials --json     # machine-readable output
+ *   socket-lib check primordials --explain  # one detailed line per finding
+ *   socket-lib check primordials --silent   # silent on success
+ *
+ * Exit codes:
+ *   0 — no drift
+ *   1 — drift detected (or config / lookup error)
+ */
+export declare function runCheckPrimordials(argv: readonly string[]): Promise<number>;

package/dist/bin/check-primordials.js

@@ -0,0 +1,229 @@
+"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 check_primordials_exports = {};
+__export(check_primordials_exports, {
+  runCheckPrimordials: () => runCheckPrimordials
+});
+module.exports = __toCommonJS(check_primordials_exports);
+var import_node_fs = require("node:fs");
+var import_node_path = __toESM(require("node:path"));
+var import_node_process = __toESM(require("node:process"));
+var import_errors = require("../errors");
+var import_logger = require("../logger");
+var import_primordials = require("../checks/primordials");
+var import_parse = require("../argv/parse");
+const logger = (0, import_logger.getDefaultLogger)();
+const DEFAULT_CONFIG_PATH = ".socket-lib.json";
+const FALLBACK_CONFIG_PATHS = [
+  ".socket-lib.json",
+  ".config/socket-lib.json"
+];
+const CONFIG_SECTION = "primordials";
+function parseArgs(argv) {
+  const { values } = (0, import_parse.parseArgs)({
+    args: argv,
+    strict: false,
+    options: {
+      config: { type: "string", short: "c" },
+      explain: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      json: { type: "boolean" },
+      silent: { type: "boolean" }
+    }
+  });
+  const explicitConfig = values["config"];
+  return {
+    config: typeof explicitConfig === "string" ? explicitConfig : void 0,
+    json: Boolean(values["json"]),
+    explain: Boolean(values["explain"]),
+    silent: Boolean(values["silent"]),
+    help: Boolean(values["help"])
+  };
+}
+function resolveConfigPath(explicit) {
+  if (explicit !== void 0) {
+    return explicit;
+  }
+  for (const candidate of FALLBACK_CONFIG_PATHS) {
+    if ((0, import_node_fs.existsSync)(import_node_path.default.resolve(candidate))) {
+      return candidate;
+    }
+  }
+  return FALLBACK_CONFIG_PATHS[0];
+}
+function printHelp() {
+  logger.log("socket-lib check primordials \u2014 primordials drift check");
+  logger.log("");
+  logger.log("Usage:");
+  logger.log("  socket-lib check primordials [opts]");
+  logger.log("  socket-lib check prim        [opts]    # short alias");
+  logger.log("");
+  logger.log("Options:");
+  logger.log(
+    `  --config, -c <path>   Config file. Default: ${DEFAULT_CONFIG_PATH}`
+  );
+  logger.log(`                        (falls back to .config/socket-lib.json)`);
+  logger.log("  --explain             Print one detailed line per finding.");
+  logger.log("  --json                Machine-readable JSON output.");
+  logger.log("  --silent              Silent on success.");
+  logger.log("  --help, -h            Print this help.");
+  logger.log("");
+  logger.log("Config (.socket-lib.json \u2014 primordials section):");
+  logger.log("  {");
+  logger.log('    "primordials": {');
+  logger.log('      "aliasMap":         { "Array": "ArrayCtor" },');
+  logger.log('      "nodeInternalOnly": ["SafeMap", "SafeSet"],');
+  logger.log(
+    '      "scanDirs":         ["src", "additions/source-patched/lib"]'
+  );
+  logger.log("    }");
+  logger.log("  }");
+  logger.log("");
+  logger.log("A bare object (no `primordials` section) is also accepted for");
+  logger.log("repos that only run this one check.");
+}
+function loadConfig(configPath) {
+  if (!(0, import_node_fs.existsSync)(configPath)) {
+    throw new Error(`config file not found: ${configPath}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse((0, import_node_fs.readFileSync)(configPath, "utf8"));
+  } catch (e) {
+    throw new Error(`config file is not valid JSON: ${(0, import_errors.errorMessage)(e)}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("config root must be an object");
+  }
+  const root = parsed;
+  const sectional = root[CONFIG_SECTION];
+  const raw = sectional !== void 0 ? sectional : root;
+  if (!Array.isArray(raw.scanDirs)) {
+    throw new Error(
+      `config.scanDirs must be an array of strings (got ${typeof raw.scanDirs})`
+    );
+  }
+  for (const [i, v] of raw.scanDirs.entries()) {
+    if (typeof v !== "string") {
+      throw new Error(`config.scanDirs[${i}] must be a string`);
+    }
+  }
+  if (raw.aliasMap !== void 0 && (typeof raw.aliasMap !== "object" || raw.aliasMap === null || Array.isArray(raw.aliasMap))) {
+    throw new Error("config.aliasMap must be an object of source\u2192target");
+  }
+  if (raw.nodeInternalOnly !== void 0 && !Array.isArray(raw.nodeInternalOnly)) {
+    throw new Error("config.nodeInternalOnly must be an array of strings");
+  }
+  const aliasMap = new Map(
+    Object.entries(raw.aliasMap ?? {})
+  );
+  const nodeInternalOnly = new Set(
+    (raw.nodeInternalOnly ?? []).filter(
+      (x) => typeof x === "string"
+    )
+  );
+  return {
+    scanDirs: raw.scanDirs,
+    aliasMap,
+    nodeInternalOnly,
+    socketLibPrimordialsPath: typeof raw.socketLibPrimordialsPath === "string" ? raw.socketLibPrimordialsPath : void 0,
+    repoRoot: import_node_process.default.cwd()
+  };
+}
+function serialize(result) {
+  return {
+    ok: result.findings.length === 0,
+    used: result.used.size,
+    findings: result.findings.map((f) => ({
+      kind: f.kind,
+      name: f.name,
+      files: f.files,
+      hint: f.hint
+    }))
+  };
+}
+function renderHuman(result, args) {
+  if (result.findings.length === 0) {
+    if (!args.silent) {
+      logger.success(
+        `Primordials coverage OK \u2014 ${result.used.size} names used, all accounted for.`
+      );
+    }
+    return;
+  }
+  logger.error(
+    `Primordials drift detected \u2014 ${result.findings.length} unaccounted name(s):`
+  );
+  for (const f of result.findings) {
+    logger.error(`  ${f.name}`);
+    if (args.explain) {
+      logger.error(`    ${f.hint}`);
+      if (f.files.length > 0) {
+        logger.error(`    files: ${f.files.join(", ")}`);
+      }
+    }
+  }
+  if (!args.explain) {
+    logger.error("");
+    logger.error("Run with --explain for fix instructions and file references.");
+  }
+}
+async function runCheckPrimordials(argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    printHelp();
+    return 0;
+  }
+  let config;
+  try {
+    config = loadConfig(import_node_path.default.resolve(resolveConfigPath(args.config)));
+  } catch (e) {
+    logger.error(`socket-lib check primordials: ${(0, import_errors.errorMessage)(e)}`);
+    return 1;
+  }
+  let result;
+  try {
+    result = (0, import_primordials.checkPrimordials)(config);
+  } catch (e) {
+    logger.error(`socket-lib check primordials: ${(0, import_errors.errorMessage)(e)}`);
+    return 1;
+  }
+  if (args.json) {
+    logger.log(JSON.stringify(serialize(result), null, 2));
+  } else {
+    renderHuman(result, args);
+  }
+  return result.findings.length === 0 ? 0 : 1;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  runCheckPrimordials
+});

package/dist/bin/check.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview `socket-lib check <name>` subcommand group.
+ *
+ * Routes to per-check handlers by name. Each check resolves its
+ * config file and runs its check; the group itself just dispatches
+ * and prints help.
+ *
+ * Available checks:
+ *   primordials   Drift between a repo's `primordials` destructures
+ *                 and socket-lib's userland mirror.
+ *
+ * Aliases let callers shorten the common ones:
+ *   prim          → primordials
+ */
+export declare function runCheck(args: readonly string[]): Promise<number>;

package/dist/bin/check.js

@@ -0,0 +1,73 @@
+"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 check_exports = {};
+__export(check_exports, {
+  runCheck: () => runCheck
+});
+module.exports = __toCommonJS(check_exports);
+var import_logger = require("../logger");
+var import_check_primordials = require("./check-primordials");
+const logger = (0, import_logger.getDefaultLogger)();
+const CHECKS = /* @__PURE__ */ new Map([
+  ["primordials", "primordials"],
+  ["prim", "primordials"]
+]);
+const ALIASES = /* @__PURE__ */ new Map([
+  ["primordials", ["prim"]]
+]);
+function printHelp() {
+  logger.log("socket-lib check \u2014 fleet-wide static-analysis checks");
+  logger.log("");
+  logger.log("Usage:");
+  logger.log("  socket-lib check <name> [...opts]");
+  logger.log("");
+  logger.log("Checks:");
+  for (const [canonical, aliases] of ALIASES) {
+    const aliasStr = aliases.length > 0 ? ` (alias: ${aliases.join(", ")})` : "";
+    logger.log(`  ${canonical}${aliasStr}`);
+  }
+  logger.log("");
+  logger.log("Run `socket-lib check <name> --help` for check-specific options.");
+}
+async function runCheck(args) {
+  const name = args[0];
+  if (!name || name === "--help" || name === "-h") {
+    printHelp();
+    return 0;
+  }
+  const canonical = CHECKS.get(name);
+  if (!canonical) {
+    logger.error(`socket-lib check: unknown check '${name}'`);
+    logger.error("Run `socket-lib check --help` for the list of checks.");
+    return 1;
+  }
+  switch (canonical) {
+    case "primordials":
+      return await (0, import_check_primordials.runCheckPrimordials)(args.slice(1));
+    default:
+      logger.error(`socket-lib check: missing handler for '${canonical}'`);
+      return 1;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  runCheck
+});

package/dist/bin/socket-lib.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview `socket-lib` CLI entry point — top-level dispatcher.
+ *
+ *   socket-lib                          — print help, list commands
+ *   socket-lib check <name> [opts...]   — run a fleet-wide check
+ *
+ * Subcommands live as siblings under `src/bin/`; each is its own
+ * file so a misbehaving check can't crash other commands at parse
+ * time. The dispatcher just routes; subcommands own their own arg
+ * parsing.
+ *
+ * The CLI is shipped via the `bin` field in package.json and
+ * intended to be invoked as `pnpm exec socket-lib <command>` from
+ * any consumer that has `@socketsecurity/lib` as a (dev)dependency.
+ */
+export {};

package/dist/bin/socket-lib.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+"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 __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 import_node_process = __toESM(require("node:process"));
+var import_logger = require("../logger");
+var import_check = require("./check");
+const logger = (0, import_logger.getDefaultLogger)();
+function printHelp() {
+  logger.log("socket-lib \u2014 fleet-wide static-analysis CLI");
+  logger.log("");
+  logger.log("Usage:");
+  logger.log("  socket-lib <command> [...args]");
+  logger.log("");
+  logger.log("Commands:");
+  logger.log("  check <name>   Run a fleet-wide check (primordials, ...).");
+  logger.log("");
+  logger.log("Run `socket-lib check --help` for the list of checks.");
+}
+async function main() {
+  const args = import_node_process.default.argv.slice(2);
+  const command = args[0];
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    return 0;
+  }
+  switch (command) {
+    case "check": {
+      return await (0, import_check.runCheck)(args.slice(1));
+    }
+    default: {
+      logger.error(`socket-lib: unknown command '${command}'`);
+      logger.error("Run `socket-lib --help` for the list of commands.");
+      return 1;
+    }
+  }
+}
+if (typeof require !== "undefined" && require.main === module) {
+  void main().then((code) => {
+    import_node_process.default.exit(code);
+  });
+}

package/dist/checks/primordials.d.ts

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Primordials drift check — generic core.
+ *
+ * Each fleet repo that destructures from Node's internal `primordials`
+ * global needs to keep its usage shape-aligned with socket-lib's
+ * userland mirror (`@socketsecurity/lib/primordials`). This module is
+ * the parser + diff engine; per-repo policy (which dirs to scan,
+ * naming aliases, allowlist) lives in a config the caller supplies.
+ *
+ * Used by the `socket-lib check primordials` CLI subcommand. Kept
+ * importable as a library so repos with bespoke needs can compose it
+ * directly without going through the CLI.
+ *
+ * The flow:
+ *
+ *   1. Walk the configured `scanDirs` for `*.js` files.
+ *   2. From each file, extract names from every
+ *      `const { Foo, Bar } = primordials` destructure.
+ *   3. Read socket-lib's `primordials.ts` (sibling clone) or
+ *      `primordials.d.ts` (installed `node_modules`) and pull every
+ *      exported name.
+ *   4. Diff: every destructured name must be either (a) in socket-lib
+ *      verbatim, (b) in socket-lib via the configured alias map, or
+ *      (c) in the configured node-internal-only allowlist.
+ *
+ * Findings come back classified so callers can render or fail-CI on
+ * specific kinds.
+ */
+export interface PrimordialsCheckConfig {
+    /**
+     * Repo-relative directories to scan recursively for `*.js` files
+     * containing `primordials` destructures. Each entry is resolved
+     * against `repoRoot`.
+     */
+    readonly scanDirs: readonly string[];
+    /**
+     * Map from the source name a repo destructures (e.g. `Array`) to
+     * the socket-lib export name it should resolve to (e.g.
+     * `ArrayCtor`). socket-lib uses the `Ctor` suffix to avoid
+     * shadowing globals; repos that need the original name go through
+     * the alias.
+     */
+    readonly aliasMap: ReadonlyMap<string, string>;
+    /**
+     * Names that exist only in Node's internal `primordials` and are
+     * intentionally NOT mirrored to socket-lib. Adding to this set is
+     * a deliberate decision per name.
+     */
+    readonly nodeInternalOnly: ReadonlySet<string>;
+    /**
+     * Override the auto-resolution of socket-lib's primordials source.
+     * Useful for tests; production callers should leave this undefined
+     * so the resolver picks sibling clone → installed `node_modules`.
+     */
+    readonly socketLibPrimordialsPath?: string | undefined;
+    /**
+     * Repo root used to resolve `scanDirs` and to anchor the
+     * sibling-clone fallback (`<repoRoot>/../socket-lib/...`). Defaults
+     * to `process.cwd()`.
+     */
+    readonly repoRoot?: string | undefined;
+}
+export interface PrimordialsFinding {
+    readonly kind: 'unmapped' | 'missing-from-socket-lib';
+    readonly name: string;
+    readonly files: readonly string[];
+    readonly hint: string;
+}
+export interface PrimordialsCheckResult {
+    readonly used: ReadonlySet<string>;
+    readonly usedToFiles: ReadonlyMap<string, readonly string[]>;
+    readonly socketLibNames: ReadonlySet<string>;
+    readonly findings: readonly PrimordialsFinding[];
+}
+/**
+ * Pull every `const { … } = primordials` destructure body out of
+ * `src`. Comments are stripped first so commentary inside a
+ * destructure doesn't leak into captured names. The body regex
+ * disallows nested `}`, which is safe after the comment-strip pass —
+ * destructures themselves don't contain `}`.
+ */
+export declare function extractPrimordialsNames(src: string): string[];
+/**
+ * Pull every `export const Foo` / `export function Foo` /
+ * `export { Foo }` from a TS file. Also matches `.d.ts` declaration
+ * forms (`export declare const Foo`, `export declare function Foo`)
+ * since the fallback path reads `primordials.d.ts` from
+ * `node_modules` when no sibling clone is present.
+ */
+export declare function extractTsExports(src: string): string[];
+/**
+ * Locate socket-lib's primordials source. Search order:
+ *
+ *   1. `config.socketLibPrimordialsPath` if explicitly set.
+ *   2. Sibling clone — `<repoRoot>/../socket-lib/src/primordials.ts`.
+ *      Preferred for the dev-loop case where a developer is editing
+ *      socket-lib and a consumer in parallel.
+ *   3. Installed copy — `<repoRoot>/node_modules/@socketsecurity/lib/
+ *      dist/primordials.d.ts`. The CI fallback.
+ *
+ * Throws when none of the candidates exist.
+ */
+export declare function resolveSocketLibPrimordials(config: PrimordialsCheckConfig): string;
+/**
+ * Run the primordials drift check against the configured repo.
+ * Returns the full result including raw inputs (used names, lib
+ * exports) so renderers can show context, plus a sorted list of
+ * findings classified by kind.
+ */
+export declare function checkPrimordials(config: PrimordialsCheckConfig): PrimordialsCheckResult;