feat(tools/prim): add lint subcommand + Node bootstrap surface support

Three additions:

1. **`prim lint`** — new structural lint subcommand for primordials
   destructure blocks. Currently encodes one rule:

   - `ctor-rename`: constructor primordials (`Array`, `Set`,
     `TypeError`, etc.) MUST be aliased `<Name>: <Name>Ctor` when
     destructured from `primordials` or any configured
     primordials-shaped source. Bare `{ Array } = primordials`
     shadows the global and is reported as a violation.

   The set of primordials-shaped sources is configurable via
   `--primordials-source <name>` (repeatable). Defaults cover
   `primordials` (Node bootstrap global) and the
   `internal/socketsecurity/safe-references` re-export module used
   in socket-btm additions. Exits 1 if any violation found.

2. **`--surface <path>`** flag on coverage/gaps/audit. Lets users
   point prim at any primordials source file, overriding the default
   sibling/installed lookup. Use case: auditing socket-btm's
   additions against Node's `lib/internal/per_context/primordials.js`
   surface instead of socket-lib's surface.

3. **Node bootstrap surface derivation**. When `--surface` points at
   a `per_context/primordials.js`-style file, the loader recognizes
   the path and dynamically computes the full surface by enumerating
   the static + prototype methods of the upstream globals (Array,
   Object, String, Number, Map, Set, Error, RegExp, JSON, Math,
   Reflect, etc.) the same way Node does at bootstrap. This goes from
   ~20 detected names (text-only regex) to 541 detected names
   (matches what Node actually installs).

Also: `audit.mts` now resolves constructor primordial names against
the surface — picks `<Name>Ctor` if the surface uses socket-lib's
convention, falls back to bare `<Name>` if the surface uses Node's
bootstrap convention. Eliminates spurious "ArrayCtor missing" gaps
when auditing against Node's surface.

Author: jdalton

tools/prim/README.md

@@ -77,6 +77,7 @@ pnpm prim mod --target . --dir src --include-guessed --apply
 | `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 lint`     | Structural lint rules for primordials destructure blocks. Currently: `ctor-rename` — constructor primordials (`Array`, `Set`, `TypeError`, …) must be aliased `<Name>: <Name>Ctor` when destructured from `primordials` (or any configured primordials-shaped source like `safe-references`). Exits 1 on violations.        |
 | `prim mod`      | Codemod **JavaScript** source files to use primordials. Dry-run by default; pass `--apply` to write. TypeScript is out of scope (rewriting `.ts` requires source-mapping between stripped-types and original byte offsets) — `prim audit` still walks TS, so candidates are visible.                                           |
 
 ## How it knows what's covered

tools/prim/src/audit.mts

@@ -263,6 +263,23 @@ export function auditDirectory({
     return false
   }
 
+  // Constructor naming differs between surfaces:
+  //   socket-lib uses `<Name>Ctor` (e.g. `ArrayCtor`, `SetCtor`)
+  //   Node bootstrap uses bare `<Name>` (e.g. `Array`, `Set`)
+  // Pick whichever variant the surface actually exports; if neither
+  // is present we report the socket-lib convention as the gap so the
+  // expansion target is clear.
+  function resolveCtorName(globalName) {
+    const sktName = ctorPrimordialName(globalName)
+    if (exported.has(sktName)) {
+      return sktName
+    }
+    if (exported.has(globalName)) {
+      return globalName
+    }
+    return sktName
+  }
+
   const visitors = {
     NewExpression(node, _ancestors) {
       if (
@@ -275,7 +292,7 @@ export function auditDirectory({
         currentFile.relPath,
         node.start,
         `new ${node.callee.name}(...)`,
-        ctorPrimordialName(node.callee.name),
+        resolveCtorName(node.callee.name),
       )
     },
     CallExpression(node, _ancestors) {

tools/prim/src/cli.mts

@@ -2,14 +2,19 @@
  * @fileoverview `prim` CLI entry point.
  *
  * Subcommands:
- *   audit     — full report: coverage + gaps in one pass.
- *   coverage  — only call sites where a primordial already exists
- *               (migration candidates).
- *   gaps      — only call sites where no primordial exists yet
- *               (surface-expansion candidates).
- *   mod       — rewrite call sites to use primordials. Dry-run by default;
- *               pass `--apply` to write changes. Adds the import block.
- *   state     — show or diff the persisted state file.
+ *   audit       — full report: coverage + gaps in one pass.
+ *   coverage    — only call sites where a primordial already exists
+ *                 (migration candidates).
+ *   gaps        — only call sites where no primordial exists yet
+ *                 (surface-expansion candidates).
+ *   mod         — rewrite call sites to use primordials. Dry-run by default;
+ *                 pass `--apply` to write changes. Adds the import block.
+ *   lint        — structural lint rules for primordials usage. Currently:
+ *                 ctor-rename (constructor primordials must be aliased
+ *                 `<Name>: <Name>Ctor` when destructured from
+ *                 `primordials` or any configured primordials-shaped
+ *                 source). Exits 1 if violations are found.
+ *   state       — show or diff the persisted state file.
  *
  * Common flags:
  *   --target <path>     The repo to audit. Defaults to cwd.
@@ -36,6 +41,7 @@ import { parseArgs } from 'node:util'
 import { auditDirectory } from './audit.mts'
 import { applyCodemod } from './codemod.mts'
 import { formatHuman, formatJson } from './format.mts'
+import { formatLintFindings, lintSource } from './lint.mts'
 import { defaultStatePath, loadState, rollup, saveState } from './state.mts'
 import { loadPrimordialsSurface } from './surface.mts'
 
@@ -50,6 +56,9 @@ COMMANDS
   coverage             Only show migration candidates — existing primordials.
   gaps                 Only show surface gaps — uncovered patterns.
   mod                  Rewrite call sites to use primordials. Dry-run by default.
+  lint                 Structural lint rules for primordials usage. Currently:
+                       ctor-rename (constructor primordials must be aliased
+                       \`<Name>: <Name>Ctor\`). Exits 1 if violations are found.
   state                Show the persisted state file.
 
 COMMON OPTIONS
@@ -58,6 +67,15 @@ COMMON OPTIONS
                        commands (audit/coverage/gaps); default \`src\` for \`mod\`.
   --json               JSON output instead of human-readable text.
   --state <path>       State file path (default: <cwd>/.prim-state.json).
+  --surface <path>     Explicit primordials source file (overrides the default
+                       sibling/installed lookup). Use this to audit against
+                       Node's lib/internal/per_context/primordials.js or any
+                       other primordials-shaped source.
+  --primordials-source <name>  (lint only, repeatable) Identifier or require()
+                       specifier to treat as a primordials-shaped source.
+                       Defaults: \`primordials\`,
+                       \`internal/socketsecurity/safe-references\`,
+                       \`safe-references\`.
   --update-state       Persist findings into the state file.
   --help, -h           Show this help.
 
@@ -92,6 +110,8 @@ const ARG_OPTIONS = {
   dir: { type: 'string' },
   json: { type: 'boolean', default: false },
   state: { type: 'string' },
+  surface: { type: 'string' },
+  'primordials-source': { type: 'string', multiple: true },
   'update-state': { type: 'boolean', default: false },
   apply: { type: 'boolean', default: false },
   'include-guessed': { type: 'boolean', default: false },
@@ -152,9 +172,31 @@ export async function runCli(argv) {
     )
   }
 
+  // `lint` is purely structural — it doesn't need a primordials surface.
+  // Handle it before the surface load so users don't need to pass
+  // --surface for a lint-only check. The list of "primordials-shaped"
+  // sources can be extended via --primordials-source (repeatable).
+  if (command === 'lint') {
+    const primordialSources = values['primordials-source']
+    const findings = lintSource({
+      targetRoot,
+      scanDir,
+      primordialSources: Array.isArray(primordialSources)
+        ? primordialSources
+        : primordialSources
+          ? [primordialSources]
+          : undefined,
+    })
+    reportLint(findings, json, path.basename(targetRoot))
+    if (findings.length > 0) {
+      process.exitCode = 1
+    }
+    return
+  }
+
   let surface
   try {
-    surface = loadPrimordialsSurface(targetRoot)
+    surface = loadPrimordialsSurface(targetRoot, values.surface)
   } catch (e) {
     fail(e.message)
   }
@@ -220,6 +262,21 @@ function report(findings, json, targetName, mode) {
   }
 }
 
+function reportLint(findings, json, targetName) {
+  if (json) {
+    process.stdout.write(
+      formatJson({
+        targetName,
+        mode: 'lint',
+        count: findings.length,
+        findings,
+      }) + '\n',
+    )
+    return
+  }
+  process.stdout.write(formatLintFindings(findings, { targetName }))
+}
+
 function reportMod(result, json, applied) {
   if (json) {
     process.stdout.write(