chore(hooks): rename logger-guard marker to allow console; allow pnpm dlx in npx scanner

- logger-guard: canonical marker `# socket-hook: allow console`
  (was `allow logger`); the construct being suppressed is the
  console / direct-stream write, not the recommended replacement.
  Legacy `allow logger` accepted via a one-cycle alias.
- _helpers.mts: introduce RULE_ALIASES + aliasMatches() so future
  rule-marker renames don't break existing comments mid-flight.
- npx-dlx scanner: drop `pnpm dlx` from the offending forms (it's
  the fleet-canonical fetch-and-run for documentation lines that
  describe ad-hoc CLI usage where the consumer doesn't have the
  package pinned). suggestNpxReplacement now suggests `pnpm dlx`
  for runtime npx swaps that need fetch semantics.
- pre-commit.mts: route the npx loop through shouldSkipFile so
  tests, fixtures, and .git-hooks themselves are skipped; covers
  cases like socket-lib's bin.test.mts which legitimately mention
  npx in resolution-logic test fixtures.

Author: jdalton

.claude/hooks/logger-guard/README.md

@@ -44,9 +44,11 @@ The hook is intentionally narrow:
 - **Exempts** `.claude/hooks/`, `.git-hooks/`, `scripts/`, tests,
   fixtures, and external/vendored code — those have legitimate
   reasons to write directly.
-- **Exempts** lines tagged `# socket-hook: allow logger` (canonical
-  per-line opt-out). The bare form `# socket-hook: allow` also
-  works for blanket suppression.
+- **Exempts** lines tagged `# socket-hook: allow console` (canonical
+  per-line opt-out — names the construct being allowed, not the
+  recommended replacement). The bare form `# socket-hook: allow`
+  also works for blanket suppression. Legacy `allow logger` is
+  accepted as an alias for one deprecation cycle.
 - **Exempts** lines that look like documentation: lines starting
   with `*`, `//`, or `#`; JSDoc tags; fully-backticked code spans.
 

.claude/hooks/logger-guard/index.mts

@@ -27,8 +27,10 @@
 //     extensions. Hooks (.claude/hooks/), git-hooks (.git-hooks/),
 //     scripts (scripts/), tests, fixtures, and external/ vendored code
 //     are exempt — see EXEMPT_PATH_PATTERNS.
-//   - Lines marked `# socket-hook: allow logger` are exempt (canonical
+//   - Lines marked `# socket-hook: allow console` are exempt (canonical
 //     opt-out marker, same as path-guard / token-guard / npx-guard).
+//     The legacy spelling `allow logger` is accepted as an alias for
+//     one cycle (deprecation grace period).
 //   - Lines that look like documentation (comment lines, JSDoc tags,
 //     fully backticked code spans) are exempt — handled by the shared
 //     `looksLikeDocumentation` heuristic in `_helpers.mts`.
@@ -70,7 +72,7 @@ const COMMENT_LINE_RE = /^\s*(\*|\/\/|#)/
 const JSDOC_TAG_RE = /@(example|param|returns?|see|link)\b/
 // Accept `#`, `//`, or `/*` comment prefixes — same as the git pre-
 // commit/pre-push scanners. This hook is invoked on TS/JS edits where
-// `// socket-hook: allow logger` is the only natural spelling.
+// `// socket-hook: allow console` is the natural spelling.
 const SOCKET_HOOK_MARKER_RE =
   /(?:#|\/\/|\/\*)\s*socket-hook:\s*allow(?:\s+([\w-]+))?/
 
@@ -79,9 +81,10 @@ function isMarkerSuppressed(line: string): boolean {
   if (!m) {
     return false
   }
-  // No specific rule named → blanket allow. Targeted form must name
-  // 'logger' to suppress this scanner.
-  return !m[1] || m[1] === 'logger'
+  // No specific rule named → blanket allow. Targeted form names what
+  // the line is doing ('console' for direct stream writes); 'logger'
+  // is accepted as a one-cycle alias for the legacy spelling.
+  return !m[1] || m[1] === 'console' || m[1] === 'logger'
 }
 
 function isInsideBackticks(line: string): boolean {
@@ -220,7 +223,7 @@ function emitBlock(filePath: string, hits: Hit[]): void {
     out.push(`  …and ${hits.length - 3} more.`)
   }
   out.push(
-    '  Opt-out for one line (rare): append `// socket-hook: allow logger`.',
+    '  Opt-out for one line (rare): append `// socket-hook: allow console`.',
   )
   out.push('')
   process.stderr.write(out.join('\n'))

.claude/hooks/logger-guard/test/logger-guard.test.mts

@@ -92,7 +92,20 @@ test('allows tests to use console.log', async () => {
   assert.equal(code, 0)
 })
 
-test('respects # socket-hook: allow logger marker', async () => {
+test('respects # socket-hook: allow console marker', async () => {
+  const { code } = await runHook({
+    tool_name: 'Edit',
+    tool_input: {
+      file_path: 'src/foo.ts',
+      new_string:
+        'const x = 1; console.error("a") // # socket-hook: allow console',
+    },
+  })
+  assert.equal(code, 0)
+})
+
+// Legacy spelling — accepted as alias for one deprecation cycle.
+test('respects # socket-hook: allow logger marker (legacy alias)', async () => {
   const { code } = await runHook({
     tool_name: 'Edit',
     tool_input: {
@@ -115,23 +128,23 @@ test('respects bare # socket-hook: allow marker', async () => {
   assert.equal(code, 0)
 })
 
-test('respects // socket-hook: allow logger marker (slash-slash prefix)', async () => {
+test('respects // socket-hook: allow console marker (slash-slash prefix)', async () => {
   const { code } = await runHook({
     tool_name: 'Edit',
     tool_input: {
       file_path: 'src/foo.ts',
-      new_string: 'process.stderr.write(buf) // socket-hook: allow logger',
+      new_string: 'process.stderr.write(buf) // socket-hook: allow console',
     },
   })
   assert.equal(code, 0)
 })
 
-test('respects /* socket-hook: allow logger */ marker (block-comment prefix)', async () => {
+test('respects /* socket-hook: allow console */ marker (block-comment prefix)', async () => {
   const { code } = await runHook({
     tool_name: 'Edit',
     tool_input: {
       file_path: 'src/foo.ts',
-      new_string: 'console.error("a") /* socket-hook: allow logger */',
+      new_string: 'console.error("a") /* socket-hook: allow console */',
     },
   })
   assert.equal(code, 0)

.git-hooks/_helpers.mts

@@ -167,6 +167,27 @@ export const socketHookMarkerFor = (filePath: string, rule: string): string =>
     : `# socket-hook: allow ${rule}`
 const LEGACY_ZIZMOR_MARKER_RE = /(?:#|\/\/|\/\*)\s*zizmor:\s*[\w-]+/
 
+// Aliases: legacy marker names recognized as equivalent to a current
+// rule for one deprecation cycle, so callers can rename the canonical
+// rule without breaking files that still carry the old marker.
+//
+// Add entries as `<alias>: <canonical>`; both directions match in the
+// comparison below.
+const RULE_ALIASES: { [k: string]: string | undefined } = {
+  __proto__: null,
+  // 'logger' was the original name when the scanner only flagged
+  // process.std{out,err}.write; it now flags console.* too, so the
+  // canonical marker is 'console'. Keep 'logger' for one cycle.
+  logger: 'console',
+}
+
+function aliasMatches(marker: string, rule: string): boolean {
+  if (marker === rule) {
+    return true
+  }
+  return RULE_ALIASES[marker] === rule || RULE_ALIASES[rule] === marker
+}
+
 function lineIsSuppressed(line: string, rule?: string): boolean {
   if (LEGACY_ZIZMOR_MARKER_RE.test(line)) {
     return true
@@ -179,8 +200,9 @@ function lineIsSuppressed(line: string, rule?: string): boolean {
   if (!m[1]) {
     return true
   }
-  // Marker named a specific rule → only suppress that rule.
-  return rule === undefined || m[1] === rule
+  // Marker named a specific rule → suppress when the names match
+  // directly OR through an alias.
+  return rule === undefined || aliasMatches(m[1], rule)
 }
 
 // Heuristic context flags: lines that look like "this is a doc example"
@@ -354,30 +376,39 @@ export const scanPrivateKeys = (text: string): LineHit[] => {
 
 // ── npx/dlx scanner ────────────────────────────────────────────────
 //
-// Match `npx` / `pnpm dlx` / `yarn dlx` only when the token sits at a
-// command position — preceded by start-of-line / whitespace / shell
-// separator (`&&`, `||`, `;`, `|`, `(`, backtick), or directly after a
-// PowerShell `& ` invoke. Exclude JSON-key, env-value, and identifier
-// suffix contexts where `npx` shows up as an embedded substring:
+// Match `npx` / `yarn dlx` only when the token sits at a command
+// position — preceded by start-of-line / whitespace / shell separator
+// (`&&`, `||`, `;`, `|`, `(`, backtick), or directly after a PowerShell
+// `& ` invoke. Exclude JSON-key, env-value, and identifier suffix
+// contexts where `npx` shows up as an embedded substring:
 //   - `"socket-npx": …`            (bin-name suffix)
 //   - `"dev:npx": "…SOCKET_CLI_MODE=npx node …"` (script key + env value)
 //   - `cmd-npx-helper`             (identifier interior)
 // The negative lookbehind catches hyphen / colon / equals / underscore /
 // dot prefixes; the negative lookahead catches the same followed forms
 // (`npx-helper`, `npx:foo`).
+//
+// **Allowed:** `pnpm dlx` / `pnpm exec` / `pn dlx` / `pn exec` / `pnx`
+// (the pnpm v11 shorthands for `pnpm dlx`). `pnpm dlx` is the
+// fleet-canonical fetch-and-run form for documentation lines that
+// describe ad-hoc CLI usage (where the consumer doesn't have the
+// package pinned in their workspace). `pnx` is the v11 shorthand and
+// is equally allowed.
 
-const NPX_DLX_RE = /(?<![\w\-:=.])\b(npx|pnpm dlx|yarn dlx)\b(?![\w\-:=.])/
+const NPX_DLX_RE = /(?<![\w\-:=.])\b(npx|yarn dlx)\b(?![\w\-:=.])/
 
 // Suggest the canonical replacement for a runtime npx/dlx call.
 // Documentation contexts (comments, JSDoc) are exempt via
 // looksLikeDocumentation(); we only ever land here for code lines, where
 // the right swap is `pnpm exec` (since `pnpm` is the fleet's package
-// manager) or `pnpm run` for script entries.
+// manager) or `pnpm run` for script entries. For documentation lines
+// that legitimately need a fetch-and-run command (user-facing
+// instructions where the consumer doesn't have the package pinned),
+// use `pnpm dlx` or its pnpm v11 shorthand `pnx` instead of `npx`.
 function suggestNpxReplacement(line: string): string {
   return line
-    .replace(/\bpnpm dlx\b/g, 'pnpm exec')
     .replace(/\byarn dlx\b/g, 'pnpm exec')
-    .replace(/\bnpx\b/g, 'pnpm exec')
+    .replace(/\bnpx\b/g, 'pnpm dlx')
 }
 
 export const scanNpxDlx = (text: string): LineHit[] => {
@@ -406,8 +437,9 @@ export const scanNpxDlx = (text: string): LineHit[] => {
 // `@socketsecurity/lib/logger`. Direct calls to `process.stderr.write`,
 // `process.stdout.write`, `console.log`, `console.error`, `console.warn`,
 // `console.info`, `console.debug` are blocked. Doc-context lines are
-// exempt; lines carrying `// socket-hook: allow logger` (or `#` in
-// non-TS files) are exempt too.
+// exempt; lines carrying `// socket-hook: allow console` (or `#` in
+// non-TS files) are exempt too. Legacy `allow logger` is accepted as
+// an alias for one deprecation cycle.
 
 const LOGGER_LEAK_RE =
   /\b(process\.std(?:err|out)\.write|console\.(?:log|error|warn|info|debug))\s*\(/
@@ -435,7 +467,7 @@ export const scanLoggerLeaks = (text: string): LineHit[] => {
     if (!LOGGER_LEAK_RE.test(line)) {
       continue
     }
-    if (looksLikeDocumentation(line, LOGGER_LEAK_RE, 'logger')) {
+    if (looksLikeDocumentation(line, LOGGER_LEAK_RE, 'console')) {
       continue
     }
     hits.push({

.git-hooks/pre-commit.mts

@@ -179,10 +179,14 @@ const main = (): number => {
   // npx/dlx usage.
   logger.info('Checking for npx/dlx usage...')
   for (const file of stagedFiles) {
+    // shouldSkipFile covers tests, fixtures, .git-hooks, etc. — test
+    // files frequently mention `npx` as part of fixture paths or
+    // resolution-logic test cases (see socket-lib/test/unit/bin.test.mts).
+    if (shouldSkipFile(file)) {
+      continue
+    }
     if (
-      file.includes('node_modules/') ||
       file.endsWith('pnpm-lock.yaml') ||
-      file.includes('.git-hooks/') ||
       // CHANGELOG entries discuss npx ecosystem *behavior* (cache
       // semantics, naming conventions) as historical documentation —
       // they're not commands. Skip the npx/dlx scan for changelogs.