feat(bazel): add bounded verbose diagnostics

Author: simonhj

CHANGELOG.md

@@ -9,7 +9,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Added
 - **`socket manifest bazel [beta]`** — Generate Bazel JVM SBOM manifests by running `bazel query` against discovered Maven repos in a Bazel workspace. Closes the inline-Maven-declaration gap that lockfile-only parsing misses for repos like envoy, ray, tensorflow, tink-java, and or-tools. Auto-detects Bzlmod and legacy `WORKSPACE`.
 - **`socket scan create --auto-manifest`** now covers Bazel workspaces in addition to Gradle/Scala/Kotlin/Conda. Repos with `MODULE.bazel`, `WORKSPACE`, or `WORKSPACE.bazel` are detected automatically and their Maven dependencies extracted as part of the standard scan-create flow.
-- **Bazel PyPI extraction** — `socket manifest bazel` now generates `requirements.txt` for Python Bazel workspaces via the new repeatable `--ecosystem pypi` flag, or via auto-detection when no `--ecosystem` flag is supplied. Discovers custom `rules_python` pip hub names, queries `py_library` / `py_binary` / `py_test` dependencies, resolves canonical pinned versions from `requirements_lock.txt`, and emits PEP 503-normalized `name==version` lines. Supports both Bzlmod (`pip.parse`) and legacy `WORKSPACE` (`pip_parse` / `pip_install`) configurations. `socket scan create --auto-manifest` picks up the generated PyPI manifest alongside Maven.
+- **Bazel PyPI extraction** — `socket manifest bazel --ecosystem pypi` now generates `requirements.txt` for Python Bazel workspaces. Discovers custom `rules_python` pip hub names with Bazel command output first, queries `py_library` / `py_binary` / `py_test` dependencies, resolves canonical pinned versions from `requirements_lock.txt`, and emits PEP 503-normalized `name==version` lines. Supports both Bzlmod (`pip.parse`) and legacy `WORKSPACE` (`pip_parse` / `pip_install`) configurations. PyPI remains explicit opt-in for `socket scan create --auto-manifest` until real-world no-lockfile recovery is validated.
+
+### Changed
+- **Bazel diagnostics** — `socket manifest bazel --verbose` now emits bounded subprocess traces with argv, cwd, duration, exit status, output sizes, and failure stderr tails to make customer log-only triage safer and faster.
 
 ## [1.1.100](https://github.com/SocketDev/socket-cli/releases/tag/v1.1.100) - 2026-05-21
 

src/commands/manifest/README.md

@@ -37,20 +37,20 @@ socket manifest bazel [options] [DIR=.]
 - `--bazel-rc <path>` — path to additional `.bazelrc` fragments forwarded to bazel.
 - `--bazel-flags <str>` — flags forwarded to every bazel invocation (single quoted string).
 - `--bazel-output-base <dir>` — Bazel `--output_base` for read-only-cache CI environments.
-- `--ecosystem <name>` — ecosystem(s) to extract; repeatable. Supported values: `maven`, `pypi`. When omitted, every detected supported ecosystem is generated automatically.
+- `--ecosystem <name>` — ecosystem(s) to extract; repeatable. Supported values: `maven`, `pypi`. When omitted, Maven is generated by default; PyPI is explicit opt-in.
 - `--out <dir>` — output directory; default `./.socket/bazel-manifests/`.
 - `--dry-run`, `--verbose` — standard diagnostic flags.
 
 > **Upload**: This subcommand only generates manifests. To generate and
 > upload in one step, use `socket scan create --auto-manifest .` — it
-> detects the workspace, runs the same extraction this subcommand performs,
-> and uploads the result.
+> detects the workspace, generates Bazel Maven manifests by default, and
+> uploads the result. Bazel PyPI auto-manifest generation requires an explicit
+> `defaults.manifest.bazel.ecosystem` config value that includes `pypi`.
 
 ### Examples
 
 ```bash
-# Auto-detect and generate every supported ecosystem from the current
-# Bazel workspace (Maven and/or PyPI).
+# Generate the default Bazel Maven manifest from the current workspace.
 socket manifest bazel .
 
 # Generate only the PyPI manifest.
@@ -65,10 +65,9 @@ socket manifest bazel --bazel=/usr/local/bin/bazelisk .
 
 ### Python/PyPI Extraction
 
-When `--ecosystem pypi` is selected (or PyPI rules are auto-detected), the
-command:
+When `--ecosystem pypi` is selected, the command:
 
-1. Discovers `rules_python` pip hubs from `MODULE.bazel` (`pip.parse(hub_name = "...")`) and legacy `WORKSPACE` (`pip_parse(name = "...")` / `pip_install(name = "...")`). Hub names are never hardcoded; custom names like `my_pypi` are detected automatically.
+1. Discovers `rules_python` pip hubs from Bazel's `mod show_extension` output when available, with bounded static parsing of `MODULE.bazel` (`pip.parse(hub_name = "...")`) and legacy `WORKSPACE` (`pip_parse(name = "...")` / `pip_install(name = "...")`) retained as fallback. Hub names are never hardcoded; custom names like `my_pypi` are detected automatically.
 2. Validates each candidate hub by probing it with `bazel query` for `:pkg` targets / `alias(` rules. Invalid candidates are dropped.
 3. Runs `bazel query 'deps(kind("py_library|py_binary|py_test", //...))'` to determine which PyPI packages are actually reached by Python rules in the repo (test dependencies included for whole-repo scope).
 4. Reads `requirements_lock.txt` (the path discovered from `pip.parse(requirements_lock = "...")`) for canonical pinned versions. When the lockfile is unavailable, falls back to parsing `pypi_name=` and `pypi_version=` tags from the spoke `py_library` rules in the hub-and-spoke architecture.

src/commands/manifest/bazel/bazel-query-runner.mts

@@ -25,6 +25,8 @@ export type BazelQueryResult = {
 // Default per-invocation timeout for bazel queries. Bazel cold-cache starts
 // can take several minutes; 10 minutes is generous while still bounding CI hangs.
 const BAZEL_QUERY_TIMEOUT_MS = 600_000
+const STDERR_TAIL_BYTES = 4_096
+const STDOUT_EXCERPT_BYTES = 1_024
 
 // Splits the user-supplied --bazel-flags string on whitespace.
 // Empty / undefined returns []. No shell parsing — quoted args with embedded
@@ -111,6 +113,58 @@ function numericExitCode(value: unknown): number | undefined {
   return typeof value === 'number' && Number.isFinite(value) ? value : undefined
 }
 
+function byteLength(value: string): number {
+  return Buffer.byteLength(value, 'utf8')
+}
+
+function excerpt(value: string, maxBytes: number): string {
+  if (byteLength(value) <= maxBytes) {
+    return value
+  }
+  return value.slice(0, maxBytes) + '\n[truncated]'
+}
+
+function logBazelTrace({
+  argv,
+  durationMs,
+  opts,
+  result,
+  step,
+}: {
+  argv: string[]
+  durationMs: number
+  opts: BazelQueryOptions
+  result: BazelQueryResult
+  step: string
+}): void {
+  if (!opts.verbose) {
+    return
+  }
+  const stderrBytes = byteLength(result.stderr)
+  const stdoutBytes = byteLength(result.stdout)
+  const category = result.code === 0 ? 'ok' : 'bazel-query-failed'
+  logger.log('[VERBOSE] bazel subprocess trace:', `category=${category}`, {
+    argv,
+    category,
+    code: result.code,
+    cwd: opts.cwd,
+    durationMs,
+    stderrBytes,
+    stdoutBytes,
+    step,
+    timedOut: false,
+    timeoutMs: BAZEL_QUERY_TIMEOUT_MS,
+  })
+  if (result.code !== 0 && result.stderr) {
+    logger.log(
+      '[VERBOSE] bazel stderr tail:',
+      excerpt(result.stderr.slice(-STDERR_TAIL_BYTES), STDERR_TAIL_BYTES),
+    )
+  } else if (result.stdout && stdoutBytes <= STDOUT_EXCERPT_BYTES) {
+    logger.log('[VERBOSE] bazel stdout excerpt:', result.stdout)
+  }
+}
+
 function normalizeSpawnError(error: unknown): BazelQueryResult {
   const e = error as {
     code?: unknown
@@ -140,6 +194,7 @@ export async function runBazelQuery(
   if (opts.verbose) {
     logger.log('[VERBOSE] Executing:', opts.bin, ', args:', argv)
   }
+  const startedAt = Date.now()
   const { spinner } = constants
   let result: BazelQueryResult | undefined
   try {
@@ -162,6 +217,15 @@ export async function runBazelQuery(
     } else {
       spinner.failAndStop(`bazel query failed (${truncated}).`)
     }
+    if (result) {
+      logBazelTrace({
+        argv,
+        durationMs: Date.now() - startedAt,
+        opts,
+        result,
+        step: `bazel query ${truncated}`,
+      })
+    }
   }
 }
 
@@ -177,17 +241,27 @@ export async function runBazelModShowVisibleRepos(
   if (opts.verbose) {
     logger.log('[VERBOSE] Executing:', opts.bin, ', args:', argv)
   }
+  const startedAt = Date.now()
+  let result: BazelQueryResult
   try {
     const output = await spawn(opts.bin, argv, {
       cwd: opts.cwd,
       timeout: BAZEL_QUERY_TIMEOUT_MS,
       ...(opts.env ? { env: opts.env } : {}),
     })
     const { code, stderr, stdout } = output
-    return { code, stdout, stderr }
+    result = { code, stdout, stderr }
   } catch (e) {
-    return normalizeSpawnError(e)
+    result = normalizeSpawnError(e)
   }
+  logBazelTrace({
+    argv,
+    durationMs: Date.now() - startedAt,
+    opts,
+    result,
+    step: 'bazel mod dump_repo_mapping',
+  })
+  return result
 }
 
 /**
@@ -202,17 +276,27 @@ export async function runBazelModShowPipExtension(
   if (opts.verbose) {
     logger.log('[VERBOSE] Executing:', opts.bin, ', args:', argv)
   }
+  const startedAt = Date.now()
+  let result: BazelQueryResult
   try {
     const output = await spawn(opts.bin, argv, {
       cwd: opts.cwd,
       timeout: BAZEL_QUERY_TIMEOUT_MS,
       ...(opts.env ? { env: opts.env } : {}),
     })
     const { code, stderr, stdout } = output
-    return { code, stdout, stderr }
+    result = { code, stdout, stderr }
   } catch (e) {
-    return normalizeSpawnError(e)
+    result = normalizeSpawnError(e)
   }
+  logBazelTrace({
+    argv,
+    durationMs: Date.now() - startedAt,
+    opts,
+    result,
+    step: 'bazel mod show_extension rules_python pip',
+  })
+  return result
 }
 
 /**

src/commands/manifest/bazel/bazel-query-runner.test.mts

@@ -15,6 +15,7 @@ vi.mock('../../../constants.mts', () => ({
   },
 }))
 
+import { logger } from '@socketsecurity/registry/lib/logger'
 import { spawn } from '@socketsecurity/registry/lib/spawn'
 
 import {
@@ -192,6 +193,28 @@ describe('runBazelQuery', () => {
     })
     expect(r).toEqual({ code: -1, stdout: '', stderr: 'missing bazel' })
   })
+
+  it('emits bounded subprocess trace when verbose is true', async () => {
+    const logSpy = vi.spyOn(logger, 'log').mockImplementation(() => logger)
+    try {
+      // @ts-ignore — narrow return shape for the test's purposes.
+      mocked.mockResolvedValueOnce({ code: 7, stdout: 'OUT', stderr: 'ERR' })
+      await runBazelQuery('q', {
+        bin: 'bazel',
+        cwd: '/r',
+        invocationFlags: [],
+        verbose: true,
+      })
+      const text = logSpy.mock.calls
+        .map(args => args.map(a => String(a)).join(' '))
+        .join('\n')
+      expect(text).toContain('bazel subprocess trace')
+      expect(text).toContain('bazel stderr tail')
+      expect(text).toContain('bazel-query-failed')
+    } finally {
+      logSpy.mockRestore()
+    }
+  })
 })
 
 describe('runBazelModShowVisibleRepos', () => {

src/commands/manifest/bazel/cmd-manifest-bazel.mts

@@ -57,7 +57,8 @@ const config: CliCommandConfig = {
     },
     verbose: {
       type: 'boolean',
-      description: 'Stream bazel stdout/stderr',
+      description:
+        'Emit bounded Bazel diagnostics with argv, duration, exit status, and output sizes',
     },
   },
   help: (command, config) => `

src/commands/manifest/bazel/extract_bazel_to_maven.mts

@@ -463,7 +463,9 @@ export async function extractBazelToMaven(
     if (!allArtifacts.length) {
       if (!repos.size) {
         if (verbose) {
-          logger.info('No Maven artifacts extracted.')
+          logger.info(
+            'No Maven artifacts extracted. failureCategory=no-supported-ecosystem',
+          )
         }
         return {
           artifactCount: 0,
@@ -473,7 +475,7 @@ export async function extractBazelToMaven(
         }
       }
       logger.fail(
-        `Discovered Maven repo(s) ${repoNames.join(', ')} but extracted zero artifacts.`,
+        `Discovered Maven repo(s) ${repoNames.join(', ')} but extracted zero artifacts. failureCategory=ecosystem-detected-but-empty`,
       )
       return {
         artifactCount: 0,

src/commands/manifest/bazel/extract_bazel_to_pypi.mts

@@ -175,7 +175,9 @@ export async function extractBazelToPypi(
 
     if (!hubs.size) {
       if (verbose) {
-        logger.info('No PyPI hubs discovered.')
+        logger.info(
+          'No PyPI hubs discovered. failureCategory=no-supported-ecosystem',
+        )
       }
       return {
         artifactCount: 0,
@@ -270,7 +272,9 @@ export async function extractBazelToPypi(
     }
 
     if (!allLines.length) {
-      logger.fail('No PyPI packages extracted. See warnings above.')
+      logger.fail(
+        'No PyPI packages extracted. failureCategory=ecosystem-detected-but-empty. See warnings above.',
+      )
       return { artifactCount: 0, manifestPath, ok: false }
     }
     logger.success(