feat: Replace hardcoded SPDX enum with spdx-licenses gem for dynamic validation (#44)

The license/spdx annotation previously used a hardcoded enum of ~20 licenses,
requiring manual updates whenever a new SPDX ID appeared. Now uses the
spdx-licenses gem which provides the full canonical list of 500+ identifiers.

- Add spdx-licenses gem dependency
- Remove hardcoded enum from license/spdx annotation
- Replace KNOWN_SPDX set with SpdxLicenses.exist? calls in LicenseAnalyzer
- Add validator: option to Annotation class for custom validation lambdas
- Add SPDX_VALIDATOR on TechnologyArtifact to validate license values at lint time
- Add BUSL-1.1 as source-available category for risk assessment

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: ionos-landgraf-vin

.rubocop.yml

@@ -81,7 +81,7 @@ Metrics/BlockLength:
     - "*.gemspec"
 
 Metrics/ParameterLists:
-  Max: 10
+  Max: 12
   Exclude:
     - "test/**/*"
 

Gemfile.lock

@@ -12,6 +12,7 @@ PATH
       rouge (~> 4.7.0)
       sinatra (~> 4.0)
       sinatra-contrib (~> 4.0)
+      spdx-licenses (~> 1.0)
       thor (~> 1.0)
       tty-markdown (~> 0.7)
 
@@ -206,6 +207,7 @@ GEM
       rack-protection (= 4.2.1)
       sinatra (= 4.2.1)
       tilt (~> 2.0)
+    spdx-licenses (1.4.0)
     steep (1.10.0)
       activesupport (>= 5.1)
       concurrent-ruby (>= 1.1.10)
@@ -356,6 +358,7 @@ CHECKSUMS
   simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
   sinatra (4.2.1) sha256=b7aeb9b11d046b552972ade834f1f9be98b185fa8444480688e3627625377080
   sinatra-contrib (4.2.1) sha256=10d091c944d268aa910c618ea40a3c3ebe0533e6e32990d84af92235a3d26b4a
+  spdx-licenses (1.4.0) sha256=953820f3714b5f998b56a2a663ebeac51667a4017392ad53cd30709e8fa4f67d
   steep (1.10.0) sha256=1b295b55f9aaff1b8d3ee42453ee55bc2a1078fda0268f288edb2dc014f4d7d1
   stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
   strings (0.2.1) sha256=933293b3c95cf85b81eb44b3cf673e3087661ba739bbadfeadf442083158d6fb

archsight.gemspec

@@ -51,6 +51,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "rouge", "~> 4.7.0"
   spec.add_dependency "sinatra", "~> 4.0"
   spec.add_dependency "sinatra-contrib", "~> 4.0"
+  spec.add_dependency "spdx-licenses", "~> 1.0"
   spec.add_dependency "thor", "~> 1.0"
   spec.add_dependency "tty-markdown", "~> 0.7"
 end

lib/archsight/annotations/annotation.rb

@@ -12,6 +12,7 @@ def initialize(key, options = {})
     @explicit_title = options[:title]
     @filter = options[:filter]
     @enum = options[:enum]
+    @validator = options[:validator]
     @sidebar = options.fetch(:sidebar, true)
     @list = options.fetch(:list, false)
     @editor = options.fetch(:editor, true)
@@ -54,7 +55,7 @@ def list_display?
   end
 
   def has_validation?
-    @enum || @type.is_a?(Class)
+    @enum || @validator || @type.is_a?(Class)
   end
 
   # === Value Methods (for instance values) ===
@@ -85,6 +86,7 @@ def validate(value)
     return errors if value.nil?
 
     validate_enum(value, errors)
+    validate_custom(value, errors) if errors.empty?
     validate_type(value, errors) if errors.empty?
     validate_code(value, errors) if errors.empty?
 
@@ -147,6 +149,16 @@ def validate_enum(value, errors)
     end
   end
 
+  def validate_custom(value, errors)
+    return unless @validator
+
+    values = list? ? value.to_s.split(",").map(&:strip) : [value.to_s]
+    values.each do |v|
+      message = @validator.call(v) # steep:ignore
+      errors << message if message
+    end
+  end
+
   def validate_type(value, errors)
     return unless @type.is_a?(Class)
 

lib/archsight/import/license_analyzer.rb

@@ -2,6 +2,7 @@
 
 require "open3"
 require "json"
+require "spdx-licenses"
 require "archsight/import"
 
 # License detection and dependency license scanning for repositories
@@ -32,6 +33,7 @@ class Archsight::Import::LicenseAnalyzer
     { id: "Unlicense",    re: /\bThis is free and unencumbered software\b/mi },
     { id: "CC0-1.0",      re: /Creative Commons.*CC0|CC0 1\.0 Universal/mi },
     { id: "BSL-1.0",      re: /Boost Software License/mi },
+    { id: "BUSL-1.1",     re: /Business Source License.*1\.1/mi },
     { id: "EUPL-1.2",     re: /European Union Public Licen[cs]e.*1\.2/mi }
   ].freeze
 
@@ -40,6 +42,7 @@ class Archsight::Import::LicenseAnalyzer
     "permissive" => %w[Apache-2.0 MIT BSD-3-Clause BSD-2-Clause ISC Unlicense CC0-1.0 BSL-1.0 0BSD Ruby],
     "copyleft" => %w[GPL-3.0 GPL-2.0 AGPL-3.0],
     "weak-copyleft" => %w[LGPL-3.0 LGPL-2.1 MPL-2.0 EUPL-1.2 CDDL-1.0],
+    "source-available" => %w[BUSL-1.1],
     "proprietary" => %w[proprietary]
   }.freeze
 
@@ -56,10 +59,8 @@ class Archsight::Import::LicenseAnalyzer
     \(c\)\s
   /xi
 
-  # Known SPDX IDs for dual-license splitting
-  KNOWN_SPDX = Set.new(
-    CATEGORIES.values.flatten + %w[NOASSERTION unknown]
-  ).freeze
+  # Custom non-SPDX values we accept
+  CUSTOM_LICENSE_VALUES = Set.new(%w[NOASSERTION proprietary unknown]).freeze
 
   # License file names to search (in order of priority)
   LICENSE_FILES = %w[
@@ -289,7 +290,7 @@ def normalize_spdx(raw)
       parts = cleaned.split(%r{\s*/\s*|\s+OR\s+}i)
       parts.each do |part|
         normalized = normalize_spdx_single(part.strip)
-        return normalized if KNOWN_SPDX.include?(normalized)
+        return normalized if known_spdx?(normalized)
       end
     end
 
@@ -322,6 +323,11 @@ def normalize_spdx_single(cleaned)
     end
   end
 
+  # Check if a value is a known SPDX ID or one of our custom values
+  def known_spdx?(value)
+    CUSTOM_LICENSE_VALUES.include?(value) || SpdxLicenses.exist?(value)
+  end
+
   # Categorize a license SPDX identifier
   def categorize(spdx)
     CATEGORY_LOOKUP[spdx] || "unknown"
@@ -633,13 +639,15 @@ def assess_risk(license_names, total)
 
     strong_copyleft = CATEGORIES["copyleft"]
     weak_copyleft = CATEGORIES["weak-copyleft"]
+    source_available = CATEGORIES["source-available"]
 
     has_strong = license_names.any? { |l| strong_copyleft.include?(l) }
     has_weak = license_names.any? { |l| weak_copyleft.include?(l) }
+    has_source_available = license_names.any? { |l| source_available.include?(l) }
     unknown_count = license_names.count { |l| l == "unknown" }
     many_unknown = unknown_count.positive? && (unknown_count.to_f / license_names.size) > 0.5
 
-    if has_strong || many_unknown
+    if has_strong || many_unknown || has_source_available
       "copyleft"
     elsif has_weak
       "weak-copyleft"

lib/archsight/resources/base.rb

@@ -25,10 +25,10 @@ def self.relations
 
       # Define an annotation using the Annotation class
       def self.annotation(key, description: nil, filter: nil, title: nil, format: nil, enum: nil, sidebar: true,
-                          type: nil, list: false, editor: true)
+                          type: nil, list: false, editor: true, validator: nil)
         @annotations ||= [] #: Array[Archsight::Annotations::Annotation]
         options = { description: description, filter: filter, title: title, format: format, enum: enum,
-                    sidebar: sidebar, type: type, list: list, editor: editor }
+                    sidebar: sidebar, type: type, list: list, editor: editor, validator: validator }
         @annotations << Archsight::Annotations::Annotation.new(key, options)
       end
 

lib/archsight/resources/technology_artifact.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "uri"
+require "spdx-licenses"
 
 # TechnologyArtifact usually a source code repository or container
 class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
@@ -159,14 +160,17 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
              enum: %w[unprivileged privileged]
 
   # License information
+  SPDX_CUSTOM_VALUES = Set.new(%w[NOASSERTION proprietary unknown]).freeze
+  SPDX_VALIDATOR = lambda { |v|
+    "invalid SPDX license identifier '#{v}'" unless SPDX_CUSTOM_VALUES.include?(v) || SpdxLicenses.exist?(v)
+  }
+
   annotation "license/spdx",
              description: "SPDX license identifier",
              title: "License",
              filter: :word,
              sidebar: false,
-             enum: %w[Apache-2.0 MIT BSD-3-Clause BSD-2-Clause GPL-3.0 GPL-2.0 LGPL-3.0
-                      LGPL-2.1 MPL-2.0 ISC AGPL-3.0 Unlicense CC0-1.0 BSL-1.0 EUPL-1.2
-                      0BSD CDDL-1.0 Ruby NOASSERTION proprietary unknown]
+             validator: SPDX_VALIDATOR
   annotation "license/file",
              description: "License file path",
              title: "License File",

sig/archsight/annotations.rbs

@@ -11,6 +11,7 @@ module Archsight
       attr_reader list: bool
 
       @explicit_title: String?
+      @validator: (^(String) -> String?)?
       @regex: untyped
 
       def initialize: (String, ?Hash[Symbol, untyped]) -> void
@@ -34,6 +35,7 @@ module Archsight
 
       def type_error_message: () -> String
       def validate_enum: (untyped, Array[String]) -> void
+      def validate_custom: (untyped, Array[String]) -> void
       def validate_type: (untyped, Array[String]) -> void
       def valid_type_value?: (String) -> bool
       def valid_uri?: (String) -> bool

test/import/license_analyzer_test.rb

@@ -646,8 +646,112 @@ def test_normalize_parenthesized_or_expression
     assert_equal "MIT", result["license_spdx"]
   end
 
+  # --- SPDX gem validation (known_spdx?) ---
+
+  def test_dual_license_recognizes_spdx_id_not_in_categories
+    # Artistic-2.0 is a valid SPDX ID but not in our CATEGORIES hash;
+    # the gem should still recognize it during dual-license splitting
+    write_license_manifest("Artistic-2.0/MIT")
+    result = analyze
+
+    assert_equal "Artistic-2.0", result["license_spdx"]
+  end
+
+  def test_dual_license_recognizes_mpl_2_0_plus_uncommon_spdx
+    # Zlib is valid SPDX but was never in the old hardcoded list
+    write_license_manifest("Zlib OR MIT")
+    result = analyze
+
+    assert_equal "Zlib", result["license_spdx"]
+  end
+
+  def test_dual_license_recognizes_custom_value_noassertion
+    write_license_manifest("NOASSERTION/MIT")
+    result = analyze
+
+    assert_equal "NOASSERTION", result["license_spdx"]
+  end
+
+  def test_dual_license_skips_unrecognized_picks_known
+    # "FooBar-1.0" is not a real SPDX ID; should skip it and pick MIT
+    write_license_manifest("FooBar-1.0/MIT")
+    result = analyze
+
+    assert_equal "MIT", result["license_spdx"]
+  end
+
+  # --- BUSL-1.1 (source-available) ---
+
+  def test_detects_busl_license_file
+    write_license("Business Source License 1.1\nLicensor: Acme Corp")
+    result = analyze
+
+    assert_equal "BUSL-1.1", result["license_spdx"]
+  end
+
+  def test_busl_categorized_as_source_available
+    assert_equal "source-available",
+                 Archsight::Import::LicenseAnalyzer::CATEGORY_LOOKUP["BUSL-1.1"]
+  end
+
+  # --- SpdxLicenses gem integration ---
+
+  def test_spdx_gem_recognizes_common_licenses
+    %w[MIT Apache-2.0 GPL-3.0-only BSD-3-Clause ISC].each do |id|
+      assert SpdxLicenses.exist?(id), "Expected SpdxLicenses to recognize #{id}"
+    end
+  end
+
+  def test_spdx_gem_rejects_invalid_ids
+    %w[NOASSERTION proprietary unknown FooBar-1.0].each do |id|
+      refute SpdxLicenses.exist?(id), "Expected SpdxLicenses to NOT recognize #{id}"
+    end
+  end
+
+  def test_custom_license_values_includes_our_special_ids
+    custom = Archsight::Import::LicenseAnalyzer::CUSTOM_LICENSE_VALUES
+
+    assert_includes custom, "NOASSERTION"
+    assert_includes custom, "proprietary"
+    assert_includes custom, "unknown"
+  end
+
+  # --- Lint validation (TechnologyArtifact license/spdx annotation) ---
+
+  def test_spdx_annotation_validates_valid_license
+    annotation = spdx_annotation
+
+    assert_empty annotation.validate("MIT")
+    assert_empty annotation.validate("Apache-2.0")
+    assert_empty annotation.validate("GPL-3.0-only")
+  end
+
+  def test_spdx_annotation_validates_custom_values
+    annotation = spdx_annotation
+
+    assert_empty annotation.validate("NOASSERTION")
+    assert_empty annotation.validate("proprietary")
+    assert_empty annotation.validate("unknown")
+  end
+
+  def test_spdx_annotation_rejects_invalid_license
+    annotation = spdx_annotation
+    errors = annotation.validate("NotARealLicense-1.0")
+
+    refute_empty errors
+    assert_match(/invalid SPDX/, errors.first)
+  end
+
+  def test_spdx_annotation_has_validation
+    assert_predicate spdx_annotation, :has_validation?, "license/spdx annotation should have validation"
+  end
+
   private
 
+  def spdx_annotation
+    Archsight::Resources::TechnologyArtifact.annotations.find { |a| a.key == "license/spdx" }
+  end
+
   # Write a license string via package.json manifest (simulates dependency-tool output)
   def write_license_manifest(license_string)
     File.write(File.join(@repo_dir, "package.json"),