feat(sbom): mark dev-only components with CycloneDX scope "excluded" (#12442)

Saturate · web-flow · commit dcededcd27ca · 2026-06-16T20:29:31.000+02:00
Components reachable only through devDependencies now get
`scope: "excluded"` plus the `cdx:npm:package:development` property in
CycloneDX output. The `excluded` scope documents non-runtime/test usage
(valid in every exported spec version, 1.5/1.6/1.7); the property is the
CycloneDX npm-taxonomy marker emitted by `@cyclonedx/cyclonedx-npm`, so
both modern and existing consumers are covered. Runtime-reachable
components (ProdOnly, DevAndProd, and installed optionalDependencies)
omit both and default to `required`.
diff --git a/.changeset/sbom-dev-scope-excluded.md b/.changeset/sbom-dev-scope-excluded.md
@@ -0,0 +1,6 @@
+---
+"@pnpm/deps.compliance.sbom": minor
+"pnpm": minor
+---
+
+`pnpm sbom` now marks components reachable only through `devDependencies` with CycloneDX `scope: "excluded"` and the `cdx:npm:package:development` property. The `excluded` scope documents "component usage for test and other non-runtime purposes", which matches the semantics of a devDependency; the property is the CycloneDX npm-taxonomy marker emitted by `@cyclonedx/cyclonedx-npm`, so both modern (scope) and existing (property) consumers are covered. Components reachable at runtime (including installed `optionalDependencies`) omit `scope` and default to `required`.
diff --git a/deps/compliance/commands/test/sbom/index.ts b/deps/compliance/commands/test/sbom/index.ts
@@ -186,6 +186,30 @@ test('pnpm sbom --prod excludes devDependencies', async () => {
   expect(componentNames).not.toContain('typescript')
 })
 
+test('pnpm sbom marks dev-only components with scope "excluded" (cyclonedx)', async () => {
+  const workspaceDir = tempDir()
+  f.copy('with-dev-dependency', workspaceDir)
+
+  const { output, exitCode } = await sbom.handler({
+    ...DEFAULT_OPTS,
+    dir: workspaceDir,
+    lockfileDir: workspaceDir,
+    pnpmHomeDir: '',
+    sbomFormat: 'cyclonedx',
+    lockfileOnly: true,
+  })
+
+  expect(exitCode).toBe(0)
+
+  const parsed = JSON.parse(output)
+  const typescript = parsed.components.find((c: { name: string }) => c.name === 'typescript')
+  expect(typescript.scope).toBe('excluded')
+
+  // Prod components default to "required"; scope is omitted
+  const isPositive = parsed.components.find((c: { name: string }) => c.name === 'is-positive')
+  expect(isPositive.scope).toBeUndefined()
+})
+
 test('pnpm sbom invalid --sbom-type throws', async () => {
   const workspaceDir = tempDir()
   f.copy('simple-sbom', workspaceDir)
diff --git a/deps/compliance/sbom/src/serializeCycloneDx.ts b/deps/compliance/sbom/src/serializeCycloneDx.ts
@@ -1,5 +1,7 @@
 import crypto from 'node:crypto'
 
+import { DepType } from '@pnpm/lockfile.detect-dep-types'
+
 import { integrityToHashes } from './integrity.js'
 import { classifyLicense } from './license.js'
 import { encodePurlName } from './purl.js'
@@ -29,6 +31,20 @@ export function serializeCycloneDx (result: SbomResult, opts?: CycloneDxOptions)
       'bom-ref': comp.purl,
     }
 
+    // CycloneDX `excluded` scope (valid in every exported spec version):
+    // "component usage for test and other non-runtime purposes", which is the
+    // semantics of a devDependency.
+    // Components reachable through prod (ProdOnly/DevAndProd) omit scope and
+    // default to `required`. Installed optionalDependencies are runtime-reachable,
+    // so they stay `required` too, not `optional`.
+    if (comp.depType === DepType.DevOnly) {
+      cdxComp.scope = 'excluded'
+      // Also emit the CycloneDX npm-taxonomy marker. `scope` is the modern
+      // signal; `cdx:npm:package:development` is what @cyclonedx/cyclonedx-npm
+      // emits and what older consumers read, so we provide both.
+      cdxComp.properties = [{ name: 'cdx:npm:package:development', value: 'true' }]
+    }
+
     if (group) {
       cdxComp.group = group
     }
diff --git a/deps/compliance/sbom/test/serializeCycloneDx.test.ts b/deps/compliance/sbom/test/serializeCycloneDx.test.ts
@@ -101,6 +101,29 @@ describe('serializeCycloneDx', () => {
     expect(parsed.metadata.component.purl).toBe('pkg:npm/%40acme/sbom-app@1.0.0')
   })
 
+  it('should mark dev-only components with scope "excluded" and leave prod components scopeless', () => {
+    const result = makeSbomResult()
+    const parsed = JSON.parse(serializeCycloneDx(result))
+
+    const babel = parsed.components.find((c: { name: string }) => c.name === 'core')
+    expect(babel.scope).toBe('excluded')
+    expect(babel.properties).toContainEqual({ name: 'cdx:npm:package:development', value: 'true' })
+
+    const lodash = parsed.components.find((c: { name: string }) => c.name === 'lodash')
+    expect(lodash.scope).toBeUndefined()
+    expect(lodash.properties).toBeUndefined()
+  })
+
+  it('should leave dev-and-prod components scopeless without the development marker', () => {
+    const result = makeSbomResult()
+    result.components[1].depType = DepType.DevAndProd
+    const parsed = JSON.parse(serializeCycloneDx(result))
+
+    const babel = parsed.components.find((c: { name: string }) => c.name === 'core')
+    expect(babel.scope).toBeUndefined()
+    expect(babel.properties).toBeUndefined()
+  })
+
   it('should include root component metadata', () => {
     const result = makeSbomResult()
     const parsed = JSON.parse(serializeCycloneDx(result))
