chore(release): v5.28.0

### 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. 28 named exports including BROTLI_EXTS /
  GZIP_EXTS constants, stripExt, resolveBrotliOptions /
  resolveGzipOptions for callers building their own pipelines.
- socket-lib CLI (new bin entry) — pnpm exec socket-lib <command>.
  Initial subcommand: check primordials (alias check prim). Sectional
  config in .socket-lib.json with .config/socket-lib.json fallback.
  Flags: --config/-c, --explain, --json, --silent, --help.

Coverage: compression.ts at 100% / 100% / 100% / 100%
(statements / branches / funcs / lines), 64 tests.

Author: jdalton

CHANGELOG.md

@@ -5,6 +5,20 @@ 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.
+
 ## [5.27.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.27.0) - 2026-05-04
 
 ### Added

src/bin/check-primordials.ts

@@ -32,15 +32,26 @@ import { parseArgs as parseLibArgs } from '../argv/parse'
 
 const logger = getDefaultLogger()
 
-// Lives in `.config/` next to tsconfig.base.json, taze.config.mts,
-// etc. — the existing fleet pattern for tooling configs that
-// consumers read. One file per repo for all socket-lib checks;
-// section per check.
-const DEFAULT_CONFIG_PATH = '.config/socket-lib.json'
+// Default config name. We accept both the root-level dotfile (the
+// canonical `.<tool>rc.json` shape) and the `.config/`-rooted variant
+// (the fleet pattern for tooling configs). Look up in this order when
+// `--config` was not explicitly passed, falling through to the next
+// candidate if the file is missing — first hit wins. One file per
+// repo for all socket-lib checks; section per check.
+// At the repo root we use the canonical `.<tool>.json` dotfile shape.
+// Inside `.config/`, the directory itself is already hidden, so the
+// fleet convention drops the leading dot — every existing file under
+// `.config/` (taze.config.mts, vitest.config.mts, tsconfig.base.json,
+// ...) is bare-named. Match that.
+const DEFAULT_CONFIG_PATH = '.socket-lib.json'
+const FALLBACK_CONFIG_PATHS: readonly string[] = [
+  '.socket-lib.json',
+  '.config/socket-lib.json',
+]
 const CONFIG_SECTION = 'primordials'
 
 interface ParsedArgs {
-  readonly config: string
+  readonly config: string | undefined
   readonly json: boolean
   readonly explain: boolean
   readonly silent: boolean
@@ -52,22 +63,46 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
     args: argv,
     strict: false,
     options: {
-      config: { type: 'string', default: DEFAULT_CONFIG_PATH },
+      config: { type: 'string', short: 'c' },
       explain: { type: 'boolean' },
       help: { type: 'boolean', short: 'h' },
       json: { type: 'boolean' },
       silent: { type: 'boolean' },
     },
   })
+  // `config` is left undefined when neither `--config` nor `-c` was
+  // passed, so the resolver below can fall back to the search list.
+  // An explicit value short-circuits the search.
+  const explicitConfig = values['config']
   return {
-    config: String(values['config'] ?? DEFAULT_CONFIG_PATH),
+    config: typeof explicitConfig === 'string' ? explicitConfig : undefined,
     json: Boolean(values['json']),
     explain: Boolean(values['explain']),
     silent: Boolean(values['silent']),
     help: Boolean(values['help']),
   }
 }
 
+/**
+ * Pick the config file. Returns the explicit `--config` argument when
+ * given (even if it doesn't exist — the caller will surface the error
+ * with the path they typed). Otherwise probes the fallback list in
+ * order and returns the first hit. Returns the head of the list when
+ * none exist, so the caller's "config file not found" error message
+ * names the canonical default.
+ */
+function resolveConfigPath(explicit: string | undefined): string {
+  if (explicit !== undefined) {
+    return explicit
+  }
+  for (const candidate of FALLBACK_CONFIG_PATHS) {
+    if (existsSync(path.resolve(candidate))) {
+      return candidate
+    }
+  }
+  return FALLBACK_CONFIG_PATHS[0]!
+}
+
 function printHelp(): void {
   logger.log('socket-lib check primordials — primordials drift check')
   logger.log('')
@@ -76,13 +111,16 @@ function printHelp(): void {
   logger.log('  socket-lib check prim        [opts]    # short alias')
   logger.log('')
   logger.log('Options:')
-  logger.log(`  --config <path>   Config file. Default: ${DEFAULT_CONFIG_PATH}`)
-  logger.log('  --explain         Print one detailed line per finding.')
-  logger.log('  --json            Machine-readable JSON output.')
-  logger.log('  --quiet           Silent on success.')
-  logger.log('  --help, -h        Print this help.')
+  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 (.config/socket-lib.json — primordials section):')
+  logger.log('Config (.socket-lib.json — primordials section):')
   logger.log('  {')
   logger.log('    "primordials": {')
   logger.log('      "aliasMap":         { "Array": "ArrayCtor" },')
@@ -238,7 +276,7 @@ export async function runCheckPrimordials(
   }
   let config: PrimordialsCheckConfig
   try {
-    config = loadConfig(path.resolve(args.config))
+    config = loadConfig(path.resolve(resolveConfigPath(args.config)))
   } catch (e) {
     logger.error(`socket-lib check primordials: ${errorMessage(e)}`)
     return 1

src/compression.ts

@@ -53,6 +53,7 @@ import {
 import { promisify } from 'node:util'
 
 import { safeDelete } from './fs'
+import { StringPrototypeToLowerCase } from './primordials'
 
 const brotliCompressAsync = promisify(brotliCompress)
 const brotliDecompressAsync = promisify(brotliDecompress)
@@ -99,7 +100,13 @@ interface ResolvedBrotliOptions extends BrotliOptions {
   params: NonNullable<BrotliOptions['params']>
 }
 
-function resolveBrotliOptions(
+/**
+ * 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 function resolveBrotliOptions(
   options: CompressOptions | undefined,
 ): ResolvedBrotliOptions {
   const level = options?.level ?? 11
@@ -112,7 +119,15 @@ function resolveBrotliOptions(
   return { params }
 }
 
-function resolveGzipOptions(options: CompressOptions | undefined): ZlibOptions {
+/**
+ * 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 function resolveGzipOptions(
+  options: CompressOptions | undefined,
+): ZlibOptions {
   const level = options?.level
   if (level === undefined) {
     return { __proto__: null } as unknown as ZlibOptions
@@ -229,7 +244,7 @@ export async function decompressBrotliFile(
           `decompressBrotliFile: ${p} has no .br/.brotli extension; can't infer destination`,
         )
       }
-      return stripCompressedExt(p, BROTLI_EXTS)
+      return stripExt(p, BROTLI_EXTS)
     },
   )
   await pipeline(
@@ -356,7 +371,12 @@ export async function decompressGzipFile(
           `decompressGzipFile: ${p} has no .gz/.gzip/.tgz extension; can't infer destination`,
         )
       }
-      return stripCompressedExt(p, GZIP_EXTS)
+      // .tgz is conventionally .tar.gz collapsed — recover the .tar so
+      // a round-trip through compress/decompress is lossless.
+      const stripped = stripExt(p, GZIP_EXTS)
+      return StringPrototypeToLowerCase(path.extname(p)) === '.tgz'
+        ? `${stripped}.tar`
+        : stripped
     },
   )
   await pipeline(
@@ -429,45 +449,48 @@ export function isGzipCompressed(input: Buffer): boolean {
 // is case-sensitive (it reflects the OS path semantics), but our
 // extension classifier is policy: ".BR" should classify the same as
 // ".br" regardless of host OS. Lowercase the extname before lookup.
-const BROTLI_EXTS: ReadonlySet<string> = new Set(['.br', '.brotli'])
-const GZIP_EXTS: ReadonlySet<string> = new Set(['.gz', '.gzip', '.tgz'])
+//
+// Exported so callers can introspect what counts as a "brotli" or
+// "gzip" extension without re-implementing the list, and so tests can
+// pin the recognized sets.
+export const BROTLI_EXTS: ReadonlySet<string> = new Set(['.br', '.brotli'])
+export const GZIP_EXTS: ReadonlySet<string> = new Set(['.gz', '.gzip', '.tgz'])
 
 /**
  * Extension check for brotli paths — matches `.br` / `.brotli`
  * (case-insensitive). Naming follows node:path's `extname`.
  */
 export function hasBrotliExt(filePath: string): boolean {
-  return BROTLI_EXTS.has(path.extname(filePath).toLowerCase())
+  return BROTLI_EXTS.has(StringPrototypeToLowerCase(path.extname(filePath)))
 }
 
 /**
  * Extension check for gzip paths — matches `.gz` / `.gzip` / `.tgz`
  * (case-insensitive). Naming follows node:path's `extname`.
  */
 export function hasGzipExt(filePath: string): boolean {
-  return GZIP_EXTS.has(path.extname(filePath).toLowerCase())
+  return GZIP_EXTS.has(StringPrototypeToLowerCase(path.extname(filePath)))
 }
 
 /**
- * Strip a recognized compression extension from a filename, returning
- * the path without it. Returns the input unchanged when no recognized
- * extension is present. Case-insensitive — preserves the rest of the
- * path's casing. The `.tgz` extension maps to `.tar` (not "no
- * extension"), since `.tgz` is conventionally `.tar.gz` collapsed.
+ * 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).
  */
-function stripCompressedExt(
-  filePath: string,
-  exts: ReadonlySet<string>,
-): string {
+export function stripExt(filePath: string, exts: ReadonlySet<string>): string {
   const ext = path.extname(filePath)
-  const lower = ext.toLowerCase()
-  if (!exts.has(lower)) {
+  if (!exts.has(StringPrototypeToLowerCase(ext))) {
     return filePath
   }
-  // .tgz is short for .tar.gz — when stripping, recover the .tar.
-  if (lower === '.tgz') {
-    return filePath.slice(0, -ext.length) + '.tar'
-  }
   return filePath.slice(0, -ext.length)
 }