✨ --include-metadata (metadata.tools) & --enrich-components #40

pboling · 2025-10-26T08:10:35Z

#	📍 NOTE	What
1️⃣	Please see #38 first	Modernize gem structure
2️⃣	Then see #37 next	Upgrade to v1.7 spec
3️⃣	Then see #39	Add --validate feature
4️⃣	Then this one	Add --include-metadata feature	<=== You are here

CLI and wiring

--include-metadata
- When provided, metadata.tools identifies this producer:
  - vendor: CycloneDX
  - name: cyclonedx-ruby
  - version: the gem’s version
- Emitted for both JSON and XML, and only when the selected spec supports metadata (>= 1.2).
--enrich-components
- Updated Cyclonedx::BomBuilder to add:
  - CLI: --enrich-components to opt-in enrichment.
  - Pass include_enrichment to build_bom(...).
- Note: This does not alter default outputs; enrichment only applies with the flag.
Help and README updated.

JSON and XML emission

Updated Cyclonedx::BomHelpers:
- build_bom supports include_enrichment and passes it to both JSON and XML builders.
- build_json_bom adds bom-ref and publisher via BomComponent when include_enrichment: true.
- build_bom_xml adds:
  - bom-ref attribute on using purl.
  - first_author if authors are present (first item split on commas/ampersands).
- Added a small _get helper to read properties from either Hash or OpenStruct-like objects.

Component shape

Updated Cyclonedx::BomComponent:
- Added optional keyword parameter include_enrichment: false to hash_val.
- When true, include:
  - "bom-ref": purl (if present)
  - "publisher": first author (if present)
- Made property access robust across Hash/OpenStruct.
- Ensured hashes is an array with an object { alg, content } as expected by existing specs.

Tests

features/metadata_tools.feature (integration)
spec/cyclonedx/metadata_tools_spec.rb (unit, offline-safe)
Added spec/cyclonedx/component_enrichment_spec.rb:
- Verifies JSON has bom-ref and publisher when include_enrichment: true and omits them otherwise.
- Verifies XML has bom-ref attribute and when include_enrichment: true and omits otherwise.

Signed-off-by: Peter H. Boling [email protected]

Copilot

Pull Request Overview

This pull request introduces support for emitting metadata.tools information in CycloneDX BOMs when the --include-metadata flag is provided. The tools metadata identifies the producer (CycloneDX, cyclonedx-ruby, and the gem version) and is emitted for both JSON and XML formats when the selected spec version is >= 1.2.

Key changes:

Added --include-metadata CLI flag to control metadata.tools emission
Implemented metadata.tools generation for JSON and XML BOM formats
Restructured test files and added RSpec configuration
Added unit and integration tests for the new functionality

Reviewed Changes

Copilot reviewed 62 out of 82 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
spec/spec_helper.rb	Replaced Aruba-based configuration with standard RSpec setup including SimpleCov initialization
spec/cyclonedx/ruby_spec.rb	Added version number existence test for the gem
spec/cyclonedx/metadata_tools_spec.rb	New test file validating metadata.tools emission in JSON and XML BOMs
spec/cyclonedx/bom_helpers_spec.rb	Tests for BomHelpers.purl method with legacy method compatibility check
spec/cyclonedx/bom_component_spec.rb	Updated to use namespaced class name (Cyclonedx::BomComponent)
spec/bom_helpers_spec.rb	Deleted legacy test file
sig/cyclonedx/ruby.rbs	Added RBS type signature for the Ruby module with VERSION constant
schema/*.{json,xsd,proto}	Added CycloneDX schema files for various versions and formats
schema/README.md	Documentation about the CycloneDX specification and schemas
lib/cyclonedx_deprecated.rb	Backward compatibility layer providing deprecated global methods
lib/cyclonedx/ruby/version.rb	Version constant definition (VERSION = "1.2.0")
lib/cyclonedx/ruby.rb	Main entry point requiring dependencies and gem components
features/support/*.rb	Added frozen_string_literal comments

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-10-26T08:11:04Z

schema/xmlcatalog.xml

+  validation without needing internet access.
+  Namespace: urn:oasis:names:tc:entity:xmlns:xml:catalog
+-->
+<!-- to prevent unintendedn notwork access, we do not set a DTD/XSD in this XML -->


Corrected spelling of 'unintended' (was 'unintendedn') and 'network' (was 'notwork').

Suggested change

Signed-off-by: Peter H. Boling <[email protected]>

- .gitignore - .rspec Signed-off-by: Peter H. Boling <[email protected]>

Signed-off-by: Peter H. Boling <[email protected]>

### Added - `CHANGELOG.md` file to document notable changes in keep-a-changelog format - `Cyclonedx::BomHelpers` module to house helper methods, replacing global methods - `Cyclonedx::BomBuilder` class, replacing `Bombuilder` (note the capitalization change) - `Cyclonedx::BomComponent` class, replacing `BomComponent` - `Cyclonedx::Ruby::Version::VERSION` constant to hold the version number (also available as `Cyclonedx::VERSION`) - `Cyclonedx::Ruby::Deprecation` module to help manage deprecations ### Changed - Updated gemspec metadata for clarity and consistency - Modernized Rakefile, dotfiles, and test setup - `LICENSE` => `LICENSE.txt` to simplify parsing consistency on various platforms and tools - `cucumber` v8 => v10 - `aruba` v2.1 => v2.2 ### Deprecated - `BomComponent` => `Cyclonedx::BomComponent` - `Bombuilder` => `Cyclonedx::BomBuilder` (note the capitalization change) - `Object.purl` => `Cyclonedx::BomHelpers.purl` - `Object.random_urn_uuid` => `Cyclonedx::BomHelpers.random_urn_uuid` - `Object.build_bom` => `Cyclonedx::BomHelpers.build_bom` - `Object.build_json_bom` => `Cyclonedx::BomHelpers.build_json_bom` - `Object.build_bom_xml` => `Cyclonedx::BomHelpers.build_bom_xml` - `Object.get_gem` => `Cyclonedx::BomHelpers.get_gem` Signed-off-by: Peter H. Boling <[email protected]>

### Added - `CHANGELOG.md` file to document notable changes in keep-a-changelog format - `Cyclonedx::BomHelpers` module to house helper methods, replacing global methods - `Cyclonedx::BomBuilder` class, replacing `Bombuilder` (note the capitalization change) - `Cyclonedx::BomComponent` class, replacing `BomComponent` - `Cyclonedx::Ruby::Version::VERSION` constant to hold the version number (also available as `Cyclonedx::VERSION`) - `Cyclonedx::Ruby::Deprecation` module to help manage deprecations ### Changed - Updated gemspec metadata for clarity and consistency - Modernized Rakefile, dotfiles, and test setup - `LICENSE` => `LICENSE.txt` to simplify parsing consistency on various platforms and tools - `cucumber` v8 => v10 - `aruba` v2.1 => v2.2 ### Deprecated - `BomComponent` => `Cyclonedx::BomComponent` - `Bombuilder` => `Cyclonedx::BomBuilder` (note the capitalization change) - `Object.purl` => `Cyclonedx::BomHelpers.purl` - `Object.random_urn_uuid` => `Cyclonedx::BomHelpers.random_urn_uuid` - `Object.build_bom` => `Cyclonedx::BomHelpers.build_bom` - `Object.build_json_bom` => `Cyclonedx::BomHelpers.build_json_bom` - `Object.build_bom_xml` => `Cyclonedx::BomHelpers.build_bom_xml` - `Object.get_gem` => `Cyclonedx::BomHelpers.get_gem` ### Fixed - `Nokogiri::XML::Builder` context relies on `method_missing` - Globally defined `Object#purl` conflicted with `<purl>`. - Moved to `Cyclonedx::BomHelpers.purl` to avoid conflict in v2.0.0 (along with all other global methods) - Fixed existing usage via the built-in Nokogiri workaround of adding an underscore `purl_` - The XML tag is unchanged as `<purl>` Signed-off-by: Peter H. Boling <[email protected]>

Signed-off-by: Peter H. Boling <[email protected]>

- Bigger build matrix changes are needed to continue running against older bunlders. - will introduce the appraisal pattern later Signed-off-by: Peter H. Boling <[email protected]>

Signed-off-by: Peter H. Boling <[email protected]>

Signed-off-by: Jan Kowalleck <[email protected]>

- cleanup spec.files Signed-off-by: Peter H. Boling <[email protected]>

Signed-off-by: Peter H. Boling <[email protected]>

@Gems

- Add spec version selection end-to-end with a new --spec-version flag (default 1.7). - Update JSON and XML outputs to honor the selected spec version. - Update fixtures, help text, tests, and docs. Files: - lib/bom_helpers.rb: - Added SUPPORTED_SPEC_VERSIONS, cyclonedx_xml_namespace helper. build_bom now accepts spec_version and routes to: - build_json_bom(gems, spec_version) sets specVersion to the provided version. - build_bom_xml(gems, spec_version) sets xmlns to http://cyclonedx.org/schema/bom/<version>.</version> - lib/bom_builder.rb: - Added --spec-version with validation; default is 1.7. - Pass @spec_version into build_bom(@Gems, @bom_output_format, @spec_version). Signed-off-by: Peter H. Boling <[email protected]>

Signed-off-by: Peter H. Boling <[email protected]>

- Added --validate and --validate-file flags in Cyclonedx::BomBuilder. - After writing the BOM, if --validate is set, validate JSON via JSON Schema and XML via XSD with local files under schema/. - Added logic to validate an existing file with --validate --validate-file <path>, inferring format from extension unless --format is provided.</path> - In validate-only mode, project path isn’t required. - Added Cyclonedx::BomHelpers.validate_bom_content(content, format, spec_version) which: - For JSON: uses json_schemer to validate against bom-<ver>.schema.json.</ver> - For XML: uses Nokogiri::XML::Schema with bom-<ver>.xsd.</ver> - Uses local schemas at schema/ and surfaces compact error messages; returns non-zero exit on failure. - Added json_schemer (~> 2.2) to cyclonedx-ruby.gemspec. - Required json_schemer in lib/cyclonedx/ruby.rb. - Updated features/help.feature to show the new flags. - Added features/validate.feature: - Validate XML BOM succeeds. - Validate JSON BOM succeeds. - Validate fails for invalid XML BOM (corrupts namespace and expects exit 1). - Infer format from file extension when using --validate-file and no --format provided. Signed-off-by: Peter H. Boling <[email protected]>

Signed-off-by: Peter H. Boling <[email protected]>

@Gems

- Add spec version selection end-to-end with a new --spec-version flag (default 1.7). - Update JSON and XML outputs to honor the selected spec version. - Update fixtures, help text, tests, and docs. Files: - lib/bom_helpers.rb: - Added SUPPORTED_SPEC_VERSIONS, cyclonedx_xml_namespace helper. build_bom now accepts spec_version and routes to: - build_json_bom(gems, spec_version) sets specVersion to the provided version. - build_bom_xml(gems, spec_version) sets xmlns to http://cyclonedx.org/schema/bom/<version>.</version> - lib/bom_builder.rb: - Added --spec-version with validation; default is 1.7. - Pass @spec_version into build_bom(@Gems, @bom_output_format, @spec_version). Signed-off-by: Peter H. Boling <[email protected]>

- Added --validate and --validate-file flags in Cyclonedx::BomBuilder. - After writing the BOM, if --validate is set, validate JSON via JSON Schema and XML via XSD with local files under schema/. - Added logic to validate an existing file with --validate --validate-file <path>, inferring format from extension unless --format is provided.</path> - In validate-only mode, project path isn’t required. - Added Cyclonedx::BomHelpers.validate_bom_content(content, format, spec_version) which: - For JSON: uses json_schemer to validate against bom-<ver>.schema.json.</ver> - For XML: uses Nokogiri::XML::Schema with bom-<ver>.xsd.</ver> - Uses local schemas at schema/ and surfaces compact error messages; returns non-zero exit on failure. - Added json_schemer (~> 2.2) to cyclonedx-ruby.gemspec. - Required json_schemer in lib/cyclonedx/ruby.rb. - Updated features/help.feature to show the new flags. - Added features/validate.feature: - Validate XML BOM succeeds. - Validate JSON BOM succeeds. - Validate fails for invalid XML BOM (corrupts namespace and expects exit 1). - Infer format from file extension when using --validate-file and no --format provided. Signed-off-by: Peter H. Boling <[email protected]>

- When provided, metadata.tools identifies this producer: - vendor: CycloneDX - name: cyclonedx-ruby - version: the gem’s version - Emitted for both JSON and XML, and only when the selected spec supports metadata (>= 1.2). - Help and README updated. - features/metadata_tools.feature (integration) - spec/cyclonedx/metadata_tools_spec.rb (unit, offline-safe) Signed-off-by: Peter H. Boling <[email protected]>

- Updated Cyclonedx::BomBuilder to add: - CLI: --enrich-components to opt-in enrichment. - Pass include_enrichment to build_bom(...). - Note: This does not alter default outputs; enrichment only applies with the flag. - Updated Cyclonedx::BomHelpers: - build_bom supports include_enrichment and passes it to both JSON and XML builders. - build_json_bom adds bom-ref and publisher via BomComponent when include_enrichment: true. - build_bom_xml adds: - bom-ref attribute on <component> using purl. - <publisher>first_author</publisher> if authors are present (first item split on commas/ampersands). - Added a small _get helper to read properties from either Hash or OpenStruct-like objects. - Updated Cyclonedx::BomComponent: - Added optional keyword parameter include_enrichment: false to hash_val. - When true, include: - "bom-ref": purl (if present) - "publisher": first author (if present) - Made property access robust across Hash/OpenStruct. - Ensured hashes is an array with an object { alg, content } as expected by existing specs. - Added spec/cyclonedx/component_enrichment_spec.rb: - Verifies JSON has bom-ref and publisher when include_enrichment: true and omits them otherwise. - Verifies XML has bom-ref attribute and <publisher> when include_enrichment: true and omits otherwise. Signed-off-by: Peter H. Boling <[email protected]>

- Fix link to renamed LICENSE => LICENSE.txt Signed-off-by: Peter H. Boling <[email protected]>

Signed-off-by: Peter H. Boling <[email protected]>

Copilot AI review requested due to automatic review settings October 26, 2025 08:10

Copilot AI reviewed Oct 26, 2025

View reviewed changes

This was referenced Oct 26, 2025

🎨 modernize for 2025 #38

Open

✨ Core v1.7 Enablement #37

Open

✨ --validate #39

Open

pboling changed the title ~~✨ --include-metadata (metadata.tools)~~ ✨ --include-metadata (metadata.tools) & --enrich-components Oct 26, 2025

pboling added 12 commits October 30, 2025 00:59

🔨 binstubs: console, setup, rake, rspec, cucumber

6a174b8

Signed-off-by: Peter H. Boling <[email protected]>

🚚 rename LICENSE => LICENSE.txt

76c388f

Signed-off-by: Peter H. Boling <[email protected]>

🎨 modernize dotfiles

6d29520

- .gitignore - .rspec Signed-off-by: Peter H. Boling <[email protected]>

🎨 modernize Rakefile

ea1339d

Signed-off-by: Peter H. Boling <[email protected]>

⚡️ Frozen Strings (performance benefit)

c91de22

Signed-off-by: Peter H. Boling <[email protected]>

⏪️ Revert accidental changes

cbd8f71

Signed-off-by: Peter H. Boling <[email protected]>

🚨 Linting

dded808

Signed-off-by: Peter H. Boling <[email protected]>

🔒️ Signed releases, checksums & CONTRIBUTING.md

14413f0

Signed-off-by: Peter H. Boling <[email protected]>

👷 Update build matrix (light)

9980c19

- Bigger build matrix changes are needed to continue running against older bunlders. - will introduce the appraisal pattern later Signed-off-by: Peter H. Boling <[email protected]>

🔨 binstub: gem_checksums

e0de431

Signed-off-by: Peter H. Boling <[email protected]>

pboling force-pushed the feat/metadata-tools branch from e20181d to bc50e2a Compare October 30, 2025 07:49

pboling requested a review from a team as a code owner October 30, 2025 07:49

jkowalleck and others added 4 commits October 30, 2025 20:53

Merge branch 'master' into fix/nokogiri-incompatible-with-global-purl

9f75e11

add NOTICE to extra_rdoc_files

9422296

Signed-off-by: Jan Kowalleck <[email protected]>

📝 Use hardcoded homepage roots

a492361

- cleanup spec.files Signed-off-by: Peter H. Boling <[email protected]>

🔥 Remove unnecessary test artifacts

d243fe2

Signed-off-by: Peter H. Boling <[email protected]>

pboling force-pushed the feat/metadata-tools branch 2 times, most recently from 4b7c15e to 20ae716 Compare October 31, 2025 16:34

pboling added 4 commits October 31, 2025 10:36

🔥 Remove gem release signing logic

a5df2d4

Signed-off-by: Peter H. Boling <[email protected]>

🔥 Remove documentation uri

b2182d3

Signed-off-by: Peter H. Boling <[email protected]>

🙈 Ignore .idea

86a28e6

Signed-off-by: Peter H. Boling <[email protected]>

pboling added 11 commits October 31, 2025 10:43

✏️ Fix typo

2144134

Signed-off-by: Peter H. Boling <[email protected]>

📌 specification v1.7 (as fixture)

c0bda69

Signed-off-by: Peter H. Boling <[email protected]>

🦺 schemas for validation

21398eb

Signed-off-by: Peter H. Boling <[email protected]>

📝 Document --validate and --validate-file

45eef49

Signed-off-by: Peter H. Boling <[email protected]>

✏️ CR from @jkowalleck

e3eea68

- Fix link to renamed LICENSE => LICENSE.txt Signed-off-by: Peter H. Boling <[email protected]>

📝 Add CODE_OF_CONDUCT.md based on contributor covenant v2.1

d059d79

Signed-off-by: Peter H. Boling <[email protected]>

pboling force-pushed the feat/metadata-tools branch from 20ae716 to d059d79 Compare October 31, 2025 16:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

✨ --include-metadata (metadata.tools) & --enrich-components #40

✨ --include-metadata (metadata.tools) & --enrich-components #40

Uh oh!

pboling commented Oct 26, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	<!-- to prevent unintendedn notwork access, we do not set a DTD/XSD in this XML -->
	<!-- to prevent unintended network access, we do not set a DTD/XSD in this XML -->

Uh oh!

✨ --include-metadata (metadata.tools) & --enrich-components #40

Are you sure you want to change the base?

✨ --include-metadata (metadata.tools) & --enrich-components #40

Uh oh!

Conversation

pboling commented Oct 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CLI and wiring

JSON and XML emission

Component shape

Tests

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 26, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

pboling commented Oct 26, 2025 •

edited

Loading