feat(tools/prim): primordials audit + codemod CLI

`prim` is a multi-command CLI for auditing and migrating JavaScript
built-in usage to @socketsecurity/lib/primordials. Two questions, one
codemod:

- prim coverage  — call sites a project could migrate to existing
                   primordials today (Object.keys → ObjectKeys,
                   arr.map → ArrayPrototypeMap, etc.).
- prim gaps      — call sites with no matching primordial yet — the
                   input list for expanding socket-lib/src/primordials.ts.
- prim audit     — coverage + gaps in one pass; --update-state writes
                   a JSON snapshot per target for trend tracking.
- prim state     — inspect the persisted state file
                   (.prim-state.json by default).
- prim mod       — codemod source files to use primordials. Dry-run
                   by default; --apply writes; --include-guessed also
                   rewrites prototype-method calls where the receiver
                   type was inferred from the identifier name.

Parser is vendored acorn-wasm (vendor/acorn-wasm/) — no npm install
needed at audit time, no network access. Surface resolution prefers a
sibling socket-lib/src/primordials.ts checkout (picks up unreleased
exports during fleet development), falling back to the installed
@socketsecurity/lib/dist/primordials.js in the target's node_modules.

Receiver-type heuristics:
- Unambiguous-method map: methods that exist on exactly one built-in
  type (.toUpperCase → String, .getTime → Date) classify by method
  name regardless of receiver — strongest signal.
- Variable-name heuristic: `arr.map(...)` → Array. False positives
  surface flagged with `[guessed: …]` for manual dismissal.

Layout:
- tools/prim/ — the CLI (workspace package, type=module, .mts source)
- vendor/acorn-wasm/ — the vendored parser (workspace package)
- pnpm-lock.yaml — workspace package linkage

Author: jdalton

pnpm-lock.yaml

@@ -0,0 +1,116 @@
+# prim
+
+CLI for auditing and migrating JavaScript built-in usage to
+[`@socketsecurity/lib/primordials`](https://github.com/SocketDev/socket-lib).
+
+## What it does
+
+Primordials capture references to JavaScript built-ins (`Object.keys`,
+`Array.prototype.map`, `JSON.parse`, …) at module load time, before user
+code can tamper with prototypes or globals. They're a hardening tool for
+code that processes adversarial input.
+
+`prim` answers two questions across a project's bundled output:
+
+- **Coverage**: which call sites already have a primordial available
+  (i.e. you can replace `arr.map(fn)` with `ArrayPrototypeMap(arr, fn)`
+  today)?
+- **Gaps**: which call sites have no matching primordial yet (and so
+  the surface needs expansion in `socket-lib/src/primordials.ts`)?
+
+It also includes a codemod (`prim mod`) that rewrites source files to
+use primordials, and a state file for tracking progress across runs.
+
+## Install
+
+```sh
+# Local checkout, run directly:
+node /path/to/socket-lib/tools/prim/bin/prim.mts --help
+```
+
+Once published to npm, `pnpm dlx prim` will work too.
+
+## Usage
+
+`prim` is a multi-command CLI. Each subcommand does one thing.
+
+```sh
+# Show help
+prim --help
+
+# Find call sites you could migrate today (existing primordials)
+prim coverage --target ./socket-cli --dir dist
+
+# Find gaps in the primordials surface (need socket-lib expansion)
+prim gaps --target ./socket-cli
+
+# Both at once, as a snapshot
+prim audit --target ./socket-cli --update-state
+
+# Inspect persisted state
+prim state
+
+# Dry-run a codemod over your source tree
+prim mod --target . --dir src
+
+# Apply for real (only after reviewing the dry-run!)
+prim mod --target . --dir src --apply
+
+# Also rewrite prototype-method calls where the receiver type is
+# guessed from the variable name (more aggressive — needs review)
+prim mod --target . --dir src --include-guessed --apply
+```
+
+### Subcommands
+
+| Subcommand      | Purpose                                                                                                                         |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `prim coverage` | Report call sites in the target that could be migrated to existing primordials.                                                 |
+| `prim gaps`     | Report call sites that need a primordial that doesn't exist yet — the input list for expanding `socket-lib/src/primordials.ts`. |
+| `prim audit`    | Run `coverage` + `gaps` and (optionally) persist the snapshot to the state file.                                                |
+| `prim state`    | Inspect the persisted state file.                                                                                               |
+| `prim mod`      | Codemod source files to use primordials. Dry-run by default; pass `--apply` to write.                                           |
+
+## How it knows what's covered
+
+`prim` resolves the primordials surface from one of two locations:
+
+1. A sibling socket-lib checkout: `../socket-lib/src/primordials.ts`
+   (used during fleet development).
+2. The installed `@socketsecurity/lib/dist/primordials.js` in the
+   target's `node_modules`.
+
+Whichever it finds first wins.
+
+## Design
+
+- **Parser**: vendored acorn-wasm at `<socket-lib>/vendor/acorn-wasm`
+  (originally from
+  [sdxgen](https://github.com/SocketDev/sdxgen/tree/main/vendor/acorn-wasm))
+  — no npm install needed, no network access.
+- **Heuristics**: receiver-type guessing for prototype-method calls
+  (e.g. `arr.map(...)` → `Array`). False positives show up flagged
+  with `[guessed: …]` so they can be dismissed manually.
+- **Unambiguous-method map**: methods that exist on exactly one
+  built-in type (`.toUpperCase` → String, `.getTime` → Date) are
+  classified by the method name regardless of receiver, which is a
+  stronger signal than the name heuristic.
+
+## State file format
+
+```json
+{
+  "updated": "2026-04-22T20:10:19.200Z",
+  "targets": {
+    "socket-cli": {
+      "coverage": [
+        { "primordial": "ObjectKeys", "count": 142 },
+        { "primordial": "ArrayPrototypeMap", "count": 86 }
+      ],
+      "gaps": [{ "primordial": "WeakRefPrototypeDeref", "count": 3 }]
+    }
+  }
+}
+```
+
+Default location is `<cwd>/.prim-state.json`; override with `--state`.

tools/prim/README.md

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.mts'
+runCli(process.argv.slice(2))

tools/prim/bin/prim.mts

@@ -0,0 +1,26 @@
+{
+  "name": "prim",
+  "version": "0.1.0",
+  "description": "Audit a project's bundled output for primordials coverage and gaps against @socketsecurity/lib/primordials, and codemod source to use them",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "prim": "./bin/prim.mts"
+  },
+  "main": "./src/index.mts",
+  "exports": {
+    ".": "./src/index.mts"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "dependencies": {
+    "acorn-wasm": "workspace:*"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "license": "MIT"
+}

tools/prim/package.json

@@ -0,0 +1,203 @@
+/**
+ * @fileoverview Walk a directory of bundled JavaScript and emit
+ * findings: every site where a primordial would (or already does)
+ * apply.
+ *
+ * Each finding records:
+ *   - The primordial that maps to the call site (e.g. `ArrayPrototypeMap`).
+ *   - Whether that primordial is currently exported from socket-lib
+ *     (`covered`) or not yet (`gap`).
+ *   - File / line / column / source pattern for human inspection.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+
+import { simple } from 'acorn-wasm'
+
+import {
+  TRACKED_GLOBALS,
+  UNAMBIGUOUS_PROTOTYPE_METHODS,
+  ctorPrimordialName,
+  guessReceiverType,
+  prototypePrimordialName,
+  staticPrimordialName,
+} from './globals.mts'
+
+/**
+ * @typedef {Object} Finding
+ * @property {string} primordial    Name of the matching primordial.
+ * @property {string} pattern       Source-level pattern, e.g. `Object.keys(...)`.
+ * @property {string} file          Path relative to the target root.
+ * @property {number} line
+ * @property {number} column
+ * @property {'covered'|'gap'} kind Whether the primordial exists today.
+ */
+
+/**
+ * @param {Object} opts
+ * @param {string} opts.targetRoot
+ * @param {string} opts.scanDir              Directory to walk (e.g. `dist`).
+ * @param {Set<string>} opts.exported        Currently-exported primordials.
+ * @param {string[]} [opts.skipDirs]         Directories to skip during walk.
+ * @param {string[]} [opts.skipFiles]        Files to skip (basename match).
+ * @returns {Finding[]}
+ */
+export function auditDirectory({
+  targetRoot,
+  scanDir,
+  exported,
+  skipDirs = ['external'],
+  skipFiles = ['primordials.js', 'primordials.mjs', 'primordials.cjs'],
+}) {
+  const findings = []
+  const seen = new Set()
+
+  function record(file, loc, pattern, primordial) {
+    const line = loc?.line ?? 0
+    const column = (loc?.column ?? 0) + 1
+    const dedupKey = `${file}:${line}:${column}:${primordial}`
+    if (seen.has(dedupKey)) {
+      return
+    }
+    seen.add(dedupKey)
+    findings.push({
+      primordial,
+      pattern,
+      file,
+      line,
+      column,
+      kind: exported.has(primordial) ? 'covered' : 'gap',
+    })
+  }
+
+  const visitors = {
+    NewExpression(node) {
+      if (
+        node.callee?.type !== 'Identifier' ||
+        !TRACKED_GLOBALS.has(node.callee.name)
+      ) {
+        return
+      }
+      record(
+        node._relPath,
+        node.loc?.start,
+        `new ${node.callee.name}(...)`,
+        ctorPrimordialName(node.callee.name),
+      )
+    },
+    CallExpression(node) {
+      if (node.callee?.type !== 'MemberExpression') {
+        return
+      }
+      const { object, property } = node.callee
+      if (!object || !property || property.type !== 'Identifier') {
+        return
+      }
+      if (object.type === 'Identifier' && TRACKED_GLOBALS.has(object.name)) {
+        record(
+          node._relPath,
+          node.loc?.start,
+          `${object.name}.${property.name}(...)`,
+          staticPrimordialName(object.name, property.name),
+        )
+        return
+      }
+      if (object.type === 'Identifier') {
+        // Strongest signal: the method name itself maps to one type
+        // unambiguously (e.g. `.toUpperCase()` → String only,
+        // `.getTime()` → Date only).
+        const methodType = UNAMBIGUOUS_PROTOTYPE_METHODS.get(property.name)
+        if (methodType) {
+          record(
+            node._relPath,
+            node.loc?.start,
+            `${object.name}.${property.name}(...)  [method: ${methodType}]`,
+            prototypePrimordialName(methodType, property.name),
+          )
+          return
+        }
+        // Weaker signal: guess the receiver's type from its name.
+        const guess = guessReceiverType(object.name)
+        if (!guess) {
+          return
+        }
+        record(
+          node._relPath,
+          node.loc?.start,
+          `${object.name}.${property.name}(...)  [guessed: ${guess}]`,
+          prototypePrimordialName(guess, property.name),
+        )
+      }
+    },
+    MemberExpression(node) {
+      if (
+        node.computed ||
+        node.object?.type !== 'Identifier' ||
+        !TRACKED_GLOBALS.has(node.object.name) ||
+        !node.property?.name
+      ) {
+        return
+      }
+      const propName = node.property.name
+      if (propName[0] !== propName[0].toLowerCase()) {
+        return
+      }
+      record(
+        node._relPath,
+        node.loc?.start,
+        `${node.object.name}.${propName}`,
+        staticPrimordialName(node.object.name, propName),
+      )
+    },
+  }
+
+  function auditFile(absPath, relPath) {
+    const src = readFileSync(absPath, 'utf8')
+    try {
+      // Inject relPath onto every visited node by wrapping the visitors.
+      // acorn-wasm's `simple` doesn't pass extra context, so we attach
+      // it inside the file walker once.
+      const wrapped = {}
+      for (const [name, fn] of Object.entries(visitors)) {
+        wrapped[name] = node => {
+          node._relPath = relPath
+          fn(node)
+        }
+      }
+      simple(src, wrapped, {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        locations: true,
+        allowImportExportEverywhere: true,
+        allowAwaitOutsideFunction: true,
+        allowHashBang: true,
+      })
+    } catch {
+      // File didn't parse — skip silently. Lint/type pipelines catch
+      // syntax errors elsewhere.
+    }
+  }
+
+  function* walkDir(dir) {
+    for (const entry of readdirSync(dir)) {
+      if (skipDirs.includes(entry) || skipFiles.includes(entry)) {
+        continue
+      }
+      const abs = path.join(dir, entry)
+      const stat = statSync(abs)
+      if (stat.isDirectory()) {
+        yield* walkDir(abs)
+      } else if (entry.endsWith('.js') || entry.endsWith('.mjs')) {
+        yield abs
+      }
+    }
+  }
+
+  for (const abs of walkDir(scanDir)) {
+    const rel = path.relative(targetRoot, abs)
+    auditFile(abs, rel)
+  }
+
+  return findings
+}