compliance 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8f7ad92baa85021ad2f6d1fc1f38fe8b0661cbcfdc1a186d57a786fe66314a0
-  data.tar.gz: e72c020cae731fe2d6352e0eb994417ff5cfafe98f016b0ac9b87ab3fd0fc235
+  metadata.gz: 3334cb98507d29e5249dc7f542ee2acb68c5dd0fb5a995b0303f2636da8bc6b2
+  data.tar.gz: 2154be63063316e33ca4046d317c7a2a68d20cad649640fe2c10f07358dc7301
 SHA512:
-  metadata.gz: d1e1049191d15e7ab231a33350099e5367ab4fd2a97028a86f39bd16586147c11272083020b9b754288736b3927a9a71555cd91c7e303afadaf1b01bb2a7c4f7
-  data.tar.gz: 03a598d1cf4378bf12d8c5469dd3421165d3c220a1261ee63219281325990df8b4ed270ab4005fbd98086e32d2a1c8a2135a8fe03a76623f9a517acef8260bd5
+  metadata.gz: 70cd172b262c2caa19616dda3fb9ab176baff4a187818bf949f6edc30a1fcdf241409fe4c6435a4d28f326b1fc87f1fd1d85d44776dd3b70e9908b584cf427ab
+  data.tar.gz: 6de40f9d88eff321ed532a124a18a54e7af2f07f61506641fb956d846332da183ed179a273e7aab52f3771063363978e430b1999f8111121a6260bfeb90e2666

data/bake/compliance.rb

@@ -9,27 +9,29 @@ def initialize(...)
 	require 'compliance'
 end
 
-def document
-	document = Compliance::Document.new
+# Load the default compliance policy.
+def policy
+	loader = Compliance::Loader.default([context.root])
 	
-	::Gem.loaded_specs.each do |name, spec|
-		Console.logger.debug(self) {"Checking gem #{name}: #{spec.full_gem_path}..."}
-		
-		if path = spec.full_gem_path and File.directory?(path)
-			Compliance::Loader.load(path, document)
-		end
-	end
-	
-	return document
+	return Compliance::Policy.default(loader)
 end
 
-def check(input:)
-	policy = Compliance::Policy.new
-	document = input || self.document
+# List available compliance documents.
+def list
+	loader = Compliance::Loader.default([context.root])
 	
+	loader.cache.map do |name, path|
+		{name: name, path: path}
+	end
+end
+
+# Check compliance with the policy.
+def check
+	policy = self.policy
+
 	failed_requirements = {}
 	
-	document.check(policy) do |requirement, satisfied, unsatisfied|
+	results = policy.check do |requirement, satisfied, unsatisfied|
 		Console.debug(self) {"Requirement #{requirement.id} is #{satisfied.any? ? "satisfied." : "not satisfied!"}"}
 		
 		if satisfied.empty?
@@ -37,5 +39,53 @@ def check(input:)
 		end
 	end
 	
-	raise Compliance::Error.new(failed_requirements) unless failed_requirements.empty?
+	if failed_requirements.any?
+		raise Compliance::Error.new(failed_requirements)
+	else
+		Console.debug(self) {"All requirements are satisfied."}
+		return results
+	end
+end
+
+# Attest to a requirement.
+# @parameter id [String] The unique identifier for the attestation, matching the requirement.
+# @parameter description [String] A description of how the requirement is satisfied.
+# @parameter by [String] The entity attesting to the requirement.
+def attest(id, description: nil, by: nil)
+	compliance_root = Compliance::Document.path(context.root)
+	
+	if File.exist?(compliance_root)
+		document = Compliance::Document.load(compliance_root)
+	else
+		document = Compliance::Document.new
+	end
+	
+	attestation = self.attestation_for(id, document)
+	
+	if description
+		attestation.metadata[:description] = description
+	end
+	
+	if by
+		attestation.metadata[:by] = by
+	end
+	
+	File.write(compliance_root, JSON.pretty_generate(document))
+	
+	return attestation
+end
+
+private
+
+def attestation_for(id, document)
+	document.attestations.each do |attestation|
+		if attestation.id == id
+			return attestation
+		end
+	end
+	
+	attestation = Compliance::Attestation.new(id: id)
+	document.attestations << attestation
+	
+	return attestation
 end

data/lib/compliance/attestation.rb

@@ -6,6 +6,9 @@
 module Compliance
 	# Represents an attestation of compliance with a requirement.
 	class Attestation
+		class Error < StandardError
+		end
+		
 		def initialize(metadata)
 			@metadata = metadata
 		end
@@ -25,5 +28,9 @@ module Compliance
 		
 		# The metadata associated with this attestation.
 		attr :metadata
+		
+		def [] key
+			@metadata[key]
+		end
 	end
 end

data/lib/compliance/document.rb

@@ -3,65 +3,63 @@
 # Released under the MIT License.
 # Copyright, 2024, by Samuel Williams.
 
+require_relative 'import'
 require_relative 'requirement'
 require_relative 'attestation'
 
 module Compliance
 	# Represents a document containing requirements and attestations.
 	class Document
-		def initialize
-			@requirements = []
-			@attestations = []
+		def self.path(root)
+			File.expand_path("compliance.json", root)
+		end
+		
+		def self.load(path)
+			data = JSON.load_file(path, symbolize_names: true)
 			
-			@attestations_by_id = {}
+			self.new.tap do |document|
+				data[:imports]&.each do |import|
+					document.imports << Import.new(import)
+				end
+				
+				data[:requirements]&.each do |metadata|
+					document.requirements << Requirement.new(metadata)
+				end
+				
+				data[:attestations]&.each do |metadata|
+					document.attestations << Attestation.new(metadata)
+				end
+			end
+		end
+		
+		def initialize(imports: [], requirements: [], attestations: [])
+			@imports = imports
+			@requirements = requirements
+			@attestations = attestations
 		end
 		
 		def as_json(...)
-			{
-				requirements: @requirements,
-				attestations: @attestations
-			}
+			Hash.new.tap do |hash|
+				if @imports.any?
+					hash[:imports] = @imports.map(&:as_json)
+				end
+				
+				if @requirements.any?
+					hash[:requirements] = @requirements.map(&:as_json)
+				end
+				
+				if @attestations.any?
+					hash[:attestations] = @attestations.map(&:as_json)
+				end
+			end
 		end
 		
 		def to_json(...)
 			as_json.to_json(...)
 		end
 		
+		attr :imports
 		attr :requirements
 		attr :attestations
-		
-		# Add a requirement to the document.
-		def add_requirement(requirement)
-			@requirements << requirement
-		end
-		
-		# Add an attestation to the document.
-		# @parameter attestation [Attestation] The attestation to add to the document.
-		def add_attestation(attestation)
-			@attestations << attestation
-			(@attestations_by_id[attestation.id] ||= Array.new) << attestation
-		end
-		
-		# Check the document against a given policy.
-		def check(policy)
-			return to_enum(:check, policy) unless block_given?
-			
-			@requirements.each do |requirement|
-				attestations = @attestations_by_id[requirement.id]
-				
-				satisfied = []
-				unsatisfied = []
-				
-				attestations&.each do |attestation|
-					if policy.satisfies?(requirement, attestation)
-						satisfied << attestation
-					else
-						unsatisfied << attestation
-					end
-				end
-				
-				yield requirement, satisfied, unsatisfied
-			end
-		end
 	end
 end

data/lib/compliance/error.rb

@@ -7,7 +7,24 @@ module Compliance
 	# Represents an error that occurs when requirements are not satisfied.
 	class Error < StandardError
 		def initialize(unsatisfied)
-			super "Unsatisfied requirements: #{unsatisfied.keys.join(', ')}"
+			super "#{unsatisfied.size} unsatisfied requirement(s): #{unsatisfied.keys.join(', ')}"
+			
+			@unsatisfied = unsatisfied
+		end
+		
+		attr :unsatisfied
+		
+		def detailed_message(...)
+			buffer = String.new
+			buffer << super << "\n"
+			
+			@unsatisfied.map do |id, requirement|
+				if description = requirement[:description]
+					buffer << "\t- #{id}: #{description}" << "\n"
+				end
+			end
+			
+			buffer
 		end
 	end
 end

data/lib/compliance/import.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+module Compliance
+	# Represents an attestation of compliance with a requirement.
+	class Import
+		class Error < StandardError
+		end
+		
+		def initialize(name)
+			@name = name
+		end
+		
+		def as_json(...)
+			@name
+		end
+		
+		def to_json(...)
+			as_json.to_json(...)
+		end
+		
+		attr :name
+		
+		def resolve(policy, loader)
+			loader.import(@name, policy)
+		end
+	end
+end

data/lib/compliance/loader.rb

@@ -10,34 +10,88 @@ require 'json'
 
 module Compliance
 	# Load compliance data from JSON files.
-	module Loader
-		def self.add(compliance, document)
-			compliance[:requirements]&.each do |metadata|
-				document.add_requirement(Requirement.new(metadata))
+	class Loader
+		class Error < StandardError
+		end
+		
+		# Setup the default loader.
+		def self.default(roots = [Dir.pwd])
+			::Gem.loaded_specs.each do |name, spec|
+				if path = spec.full_gem_path and File.directory?(path)
+					compliance_path = File.expand_path("compliance.json", path)
+					compliance_directory = File.expand_path("compliance", path)
+					
+					if File.file?(compliance_path) or File.directory?(compliance_directory)
+						roots << path
+					end
+				end
 			end
 			
-			compliance[:attestations]&.each do |metadata|
-				document.add_attestation(Attestation.new(metadata))
+			roots.uniq!
+			
+			self.new(roots)
+		end
+		
+		def initialize(roots = [])
+			@roots = roots
+			@cache = nil
+		end
+		
+		# List of root directories to search for compliance documents.
+		attr :roots
+		
+		# Cache of name to path mappings.
+		def cache
+			@cache ||= build_cache
+		end
+		
+		# Map a name to a path.
+		def resolve(name)
+			cache[name]
+		end
+		
+		# Import a named document into the policy.
+		def import(name, policy)
+			if path = cache[name]
+				begin
+					document = Document.load(path)
+				rescue => error
+					raise Error, "Error loading compliance document: #{path}!"
+				end
+				
+				begin
+					policy.add(document, self)
+				rescue => error
+					raise Error, "Error adding compliance document to policy: #{path}!"
+				end
+			else
+				raise Error, "Could not find import: #{name}"
 			end
 		end
 		
-		# Load compliance data from a directory.
-		# @parameter root [String] The root directory to load compliance data from.
-		# @parameter document [Document] The document to load compliance data into.
-		def self.load(root, document)
-			compliance_json_path = File.expand_path("compliance.json", root)
-			
-			if File.file?(compliance_json_path)
-				data = JSON.load_file(compliance_json_path, symbolize_names: true)
-				self.add(data, document)
+		# Load all top level documents.
+		def documents
+			@roots.filter_map do |path|
+				compliance_path = File.expand_path("compliance.json", path)
+				if File.file?(compliance_path)
+					begin
+						Document.load(compliance_path)
+					rescue => error
+						raise Error, "Error loading compliance document: #{compliance_path}!"
+					end
+				end
 			end
-			
-			compliance_directory = File.expand_path("compliance", root)
-			
-			if File.directory?(compliance_directory)
-				Dir.glob(File.join(compliance_directory, "*.json")) do |path|
-					data = JSON.load_file(path, symbolize_names: true)
-					self.add(data, document)
+		end
+		
+		protected
+		
+		def build_cache
+			Hash.new.tap do |cache|
+				@roots.each do |root|
+					Dir.glob(File.expand_path("compliance/*.json", root)) do |path|
+						name = File.basename(path, ".json")
+						cache[name] = path
+					end
 				end
 			end
 		end

data/lib/compliance/policy.rb

@@ -6,6 +6,77 @@
 module Compliance
 	# Represents a policy for checking compliance.
 	class Policy
+		class Error < StandardError
+		end
+		
+		# Load the policy from a given loader.
+		def self.default(loader = Loader.default)
+			self.new.tap do |policy|
+				loader.documents.each do |document|
+					policy.add(document, loader)
+				end
+			end
+		end
+		
+		def initialize
+			@requirements = {}
+			@attestations = {}
+		end
+		
+		def as_json(...)
+			{
+				requirements: @requirements,
+				attestations: @attestations
+			}
+		end
+		
+		def to_json(...)
+			as_json.to_json(...)
+		end
+		
+		attr :requirements
+		attr :attestations
+		
+		def add(document, loader)
+			document.requirements.each do |requirement|
+				if @requirements.key?(requirement.id)
+					raise Error.new("Duplicate requirement: #{requirement.id}")
+				end
+				
+				@requirements[requirement.id] = requirement
+			end
+			
+			document.attestations.each do |attestation|
+				(@attestations[attestation.id] ||= Array.new) << attestation
+			end
+			
+			document.imports.each do |import|
+				import.resolve(self, loader)
+			end
+		end
+		
+		# Check the document against a given policy.
+		def check
+			return to_enum(:check) unless block_given?
+			
+			@requirements.each do |id, requirement|
+				attestations = @attestations[id]
+				
+				satisfied = []
+				unsatisfied = []
+				
+				attestations&.each do |attestation|
+					if self.satisfies?(requirement, attestation)
+						satisfied << attestation
+					else
+						unsatisfied << attestation
+					end
+				end
+				
+				yield requirement, satisfied, unsatisfied
+			end
+		end
+		
 		def satisfies?(requirement, attestation)
 			requirement.id == attestation.id
 		end

data/lib/compliance/requirement.rb

@@ -25,5 +25,9 @@ module Compliance
 		
 		# The metadata associated with this requirement.
 		attr :metadata
+		
+		def [] key
+			@metadata[key]
+		end
 	end
 end

data/lib/compliance/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2024, by Samuel Williams.
 
 module Compliance
-	VERSION = "0.0.2"
+	VERSION = "0.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: compliance
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -37,7 +37,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-04-17 00:00:00.000000000 Z
+date: 2024-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -64,6 +64,7 @@ files:
 - lib/compliance/attestation.rb
 - lib/compliance/document.rb
 - lib/compliance/error.rb
+- lib/compliance/import.rb
 - lib/compliance/loader.rb
 - lib/compliance/policy.rb
 - lib/compliance/requirement.rb