modspec 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04b72356e376ccef5b03148c33e1c6a06d78d8ae64610c89eda67d8d68dbcb37
-  data.tar.gz: 6a1960bee2e234b9ca5bb29e9619b3d802831c1660167a3d7730fea0a688bec5
+  metadata.gz: e872dc5ba6f3f5108de783fd4dffe75cdafda9c36e30fada467a0955003e21df
+  data.tar.gz: e1c98c303fa34c9f1d7565545031b95e96062dfd513ed4b378a13de3d216552c
 SHA512:
-  metadata.gz: ce7873a1eaaea400d23e7f29cd8bc8c2e670d6857217424dced043454c863c081f783d6afb56e76dfb85b72f7fe4257ad6a96561fc7339d4b8a65b7b0c4d4d2e
-  data.tar.gz: 8889bde3ccf4cb143d4528768cf0dc38773f2df7368777830f11d0ce7649e9dfc94fd04c8051cf390d4309cd514775932e030274815b71ad94bd81bf5851db5d
+  metadata.gz: 57e6d5c5e5d2300b464fecdf0ca7277c3c1da94739c89209b6ca8f158bd1002ea0de081f5da38342a4bbb714486c45e70a9beec588758d3bc12df80c80c5bcb1
+  data.tar.gz: bbd9e71cc21b306075d30c105043399ea94665e9b3e7ddcf56e942e240c97c254a908bd593bf3566e7b76c54c6dae61f78abd252bb80cfbb513c347ad76a0151

data/.rubocop.yml

@@ -1,3 +1,5 @@
+inherit_from: .rubocop_todo.yml
+
 AllCops:
   TargetRubyVersion: 3.0
 

data/.rubocop_todo.yml

@@ -0,0 +1,118 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2024-09-11 00:07:51 UTC using RuboCop version 1.66.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: TreatCommentsAsGroupSeparators, ConsiderPunctuation, Include.
+# Include: **/*.gemfile, **/Gemfile, **/gems.rb
+Bundler/OrderedGems:
+  Exclude:
+    - 'Gemfile'
+
+# Offense count: 1
+# Configuration parameters: Severity, Include.
+# Include: **/*.gemspec
+Gemspec/RequiredRubyVersion:
+  Exclude:
+    - 'modspec.gemspec'
+
+# Offense count: 10
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: aligned, indented, indented_relative_to_receiver
+Layout/MultilineMethodCallIndentation:
+  Exclude:
+    - 'modspec.gemspec'
+    - 'spec/modspec/suite_spec.rb'
+
+# Offense count: 4
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 33
+
+# Offense count: 6
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 138
+
+# Offense count: 1
+# Configuration parameters: CountComments, CountAsOne.
+Metrics/ClassLength:
+  Max: 204
+
+# Offense count: 1
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/CyclomaticComplexity:
+  Max: 12
+
+# Offense count: 5
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 18
+
+# Offense count: 1
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/PerceivedComplexity:
+  Max: 12
+
+# Offense count: 1
+# Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros.
+# NamePrefix: is_, has_, have_
+# ForbiddenPrefixes: is_, has_, have_
+# AllowedMethods: is_a?
+# MethodDefinitionMacros: define_method, define_singleton_method
+Naming/PredicateName:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/modspec/normative_statement.rb'
+
+# Offense count: 6
+# Configuration parameters: AllowedConstants.
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/modspec/conformance_class.rb'
+    - 'lib/modspec/conformance_test.rb'
+    - 'lib/modspec/normative_statement.rb'
+    - 'lib/modspec/normative_statements_class.rb'
+    - 'lib/modspec/suite.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Style/IfUnlessModifier:
+  Exclude:
+    - 'lib/modspec/conformance_class.rb'
+    - 'lib/modspec/normative_statements_class.rb'
+
+# Offense count: 27
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, no_comma
+Style/TrailingCommaInArguments:
+  Exclude:
+    - 'spec/modspec/conformance_class_spec.rb'
+    - 'spec/modspec/conformance_test_spec.rb'
+    - 'spec/modspec/normative_statement_spec.rb'
+    - 'spec/modspec/normative_statements_class_spec.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, no_comma
+Style/TrailingCommaInArrayLiteral:
+  Exclude:
+    - 'spec/modspec/conformance_class_spec.rb'
+
+# Offense count: 13
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 247

data/Gemfile

@@ -5,5 +5,7 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in modspec.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
-gem "rspec", "~> 3.0"
+gem "equivalent-xml"
+gem "pry"
+gem "rake"
+gem "rspec"

data/README.adoc

@@ -2,44 +2,535 @@
 
 == Purpose
 
-The `modspec` Ruby gem allows you to work with OGC ModSpec instances.
+The `modspec` Ruby library allows you to work with OGC ModSpec instances
+and export/load them from/to YAML.
 
-NOTE: This is a work-in-progress.
+OGC ModSpec is a specification for specifying requirements and conformance tests
+for standards, described in OGC 08-131r3.
 
+== Features
 
-== Library
+This library allows you to:
 
-=== Usage
+* Create and manipulate ModSpec instances:
+** normative statements
+** conformance tests
+** normative statements classes
+** conformance classes
+** unified ModSpec suite
 
-The following code generates OGC ModSpec instances in XML and YAML.
+* Load and save objects from/to YAML
+* Perform validations on ModSpec instances
+* Combine ModSpec suites
+
+
+== Installation
+
+Add this line to your application's Gemfile:
 
 [source,ruby]
 ----
-require 'modspec'
-doc = IO.read('spec/fixtures/chain-rc.yaml')
-ms = Modspec::Suite.from_yaml(doc)
-puts ms.to_yaml
+gem 'modspec'
+----
+
+Then execute:
+
+[source,shell]
+----
+$ bundle install
+----
+
+Or install it yourself:
+
+[source,shell]
+----
+$ gem install modspec
+----
+
+== Basics
+
+ModSpec instances all have the following core attributes:
+
+`identifier`:: A unique identifier for the instance, as a URI.
+
+** The pattern for a ModSpec class is `/<type>/<class>`, where
+*** `<type>` is the type of the instance (`req` for normative statement, `conf` for conformance test)
+*** `<class>` is the name of the class (normative statements class or conformance class)
+
+** The pattern for a normative statement or conformance test is `/<type>/<class>/<name>`, where
+
+*** `<type>` is the type of the instance (`req` for normative statement, `conf` for conformance test)
+*** `<class>` is the name of the class (normative statements class or conformance class)
+*** `<name>` is the name of the instance
+
+`name`::
+A human-readable name for the instance
+
+`description`::
+A description of the instance
+
+`guidance`::
+Guidance on how to implement the instance
+
+
+
+== Usage
+
+=== Normative statements class
+
+A normative statements class groups related normative statements.
+
+A normative statements class has the following attributes in addition to the core attributes:
+
+`subject`::
+The subject of the normative statements class
+
+`dependencies`::
+URI(s) of normative statement classes that this class depends on
+
+`normative_statements`::
+A list of normative statements that belong to this class
+
+`belongs_to`::
+The normative statements class that this class belongs to
+
+`reference`::
+A reference to an external document or resource
+
+`source`::
+The source of the normative statements class
+
+
+.Working with normative statements classes
+[example]
+====
+[source,ruby]
+----
+normative_statements_class = Modspec::NormativeStatementsClass.new(
+  identifier: "/req/example",
+  name: "Requirements class",
+  dependencies: ["/req/baf"],
+  normative_statements: [normative_statement]
+)
 ----
 
+[source,ruby]
+----
+normative_statements_class.to_yaml
+----
+
+[source,yaml]
+----
+identifier: "/req/example"
+name: "Requirements class"
+dependencies:
+- "/req/baf"
+normative_statements:
+- identifier: "/req/example/foo"
+  name: "Example requirement"
+  statement: "This is an example requirement."
+  dependencies:
+  - "/req/bar"
+  - "/req/baz/2"
+----
 
 [source,ruby]
 ----
-require 'modspec'
-doc = IO.read('spec/fixtures/chain-cc.yaml')
-ms = Modspec::Suite.from_yaml(doc)
-puts ms.to_yaml
+> yaml = IO.read('example.yaml')
+> normative_statements_class = Modspec::NormativeStatementsClass.from_yaml(yaml)
+> <#Modspec::NormativeStatementsClass:0x00007f8b1b8b3d08 @identifier="/req/example", @name="Requirements class", @dependencies=["/req/baf"], @normative_statements=[<#Modspec::NormativeStatement:0x00007f8b1b8b3d08 @identifier="/req/example/foo", @name="Example requirement", @statement="This is an example requirement.", @dependencies=["/req/bar", "/req/baz/2"]>]>
+> normative_statements_class.name
+> "Requirements class"
+----
+====
+
+Validations:
+
+* *Identifier prefix*: All normative statements within a normative statements
+class must share the same identifier prefix as the class itself, followed by a
+slash and then the statement's own identifier.
+
+
+=== Normative statement
+
+A normative statement represents a single requirement in the specification.
+
+A normative statement has the following attributes in addition to the core attributes:
+
+`subject`::
+The subject of the normative statement
+
+`obligation`::
+The obligation level of the class, one of `requirement`, `recommendation`, `permission`. Defaults to `requirement`.
+
+`statement`::
+The text of the normative statement
+
+`condition`::
+Conditions that must be met for the statement to apply
+
+`inherit`::
+URI(s) of normative statement(s) that this statement inherits from
+
+`indirect_dependency`::
+URI(s) of normative statement(s) that this statement indirectly depends on
+
+`implements`::
+The higher-level normative statement that this statement implements
+
+`dependencies`::
+A list of identifiers for other normative statements that this statement depends on.
+
+`belongs_to`::
+The normative statements class that this statement belongs to.
+
+`reference`::
+A reference to an external document or resource
+
+`parts`::
+A list of normative statements classes that this class is composed
+
+
+.Working with normative statements
+[example]
+====
+[source,ruby]
+----
+normative_statement = Modspec::NormativeStatement.new(
+  identifier: "/req/example/foo",
+  name: "Example requirement",
+  statement: "This is an example requirement statement.",
+  obligation: "requirement", # default
+  parts: [
+    "This is a part of the requirement.",
+    "This is another part of the requirement."
+  ]
+  dependencies: ["/req/bar", "/req/baz/2"]
+)
+----
+
+[source,ruby]
+----
+normative_statement.to_yaml
+----
+
+Will give out:
+
+[source,yaml]
+----
+identifier: /req/example/foo
+name: Example requirement
+statement: This is an example requirement statement.
+dependencies:
+- /req/bar
+- /req/baz/2
+----
+
+And to load a normative statement from a YAML file:
+
+[source,ruby]
+----
+> yaml = IO.read('example-foo.yaml')
+> normative_statement = Modspec::NormativeStatement.from_yaml(yaml)
+> <#Modspec::NormativeStatement:0x00007f8b1b8b3d08 @identifier="/req/example/foo", @name="Example requirement", @statement="This is an example requirement statement.", @dependencies=["/req/bar", "/req/baz/2"]>
+> normative_statement.name
+> "Example requirement"
+----
+====
+
+
+Validations:
+
+* *Unique identifier*: Each normative statement must have a unique identifier
+within its parent normative statements class.
+
+* *Valid dependencies*: The dependencies listed for a normative statement must
+refer to valid identifiers of other normative statements.
+
+
+=== Conformance class
+
+A conformance class groups related conformance tests.
+
+A conformance class has the following attributes in addition to the core attributes:
+
+`tests`::
+A set of conformance tests that belong to this class
+
+`classification`::
+A classification of the conformance class
+
+`dependencies`::
+A list of identifiers for other conformance classes that this class depends on
+
+`target`::
+A list of identifiers of normative statement(s) that this class targets
+
+`belongs_to`::
+A conformance class that this class belongs to
+
+`reference`::
+A reference to an external document or resource
+
+
+.Working with conformance classes
+[example]
+====
+[source,ruby]
+----
+conformance_class = Modspec::ConformanceClass.new(
+  identifier: "/conf/example",
+  name: "Conformance class",
+  tests: [conformance_test]
+)
+conformance_class.to_yaml
+----
+
+[source,yaml]
+----
+identifier: "/conf/example"
+name: "Conformance class"
+tests:
+- identifier: "/conf/example/foo"
+  name: "Example test"
+  description: "This is an example conformance test."
+  targets:
+  - "/req/example/foo"
+----
+
+[source,ruby]
+----
+> yaml = IO.read('example.yaml')
+> conformance_class = Modspec::ConformanceClass.from_yaml(yaml)
+> <#Modspec::ConformanceClass:0x00007f8b1b8b3d08 @identifier="/conf/example", @name="Conformance class", @tests=[<#Modspec::ConformanceTest:0x00007f8b1b8b3d08 @identifier="/conf/example/foo", @name="Example test", @description="This is an example conformance test.", @targets=["/req/example/foo"]>], @abstract=false>
+> conformance_class.name
+> "Conformance class"
+----
+====
+
+
+Validations:
+
+* *Identifier prefix*: All conformance tests within a conformance class must
+share the same identifier prefix as the class itself, followed by a slash and
+then the test's own identifier.
+
+* *Valid targets*: The targets listed for a conformance test must refer to valid
+identifiers of existing normative statements.
+
+
+
+=== Conformance test
+
+A conformance test verifies compliance with one or more normative statements.
+
+A conformance test has the following attributes in addition to the core attributes:
+
+`targets`::
+A list of identifiers for normative statements that this test targets
+
+`belongs_to`::
+The conformance class that this test belongs to
+
+`guidance`::
+Guidance on how to perform the test
+
+`purpose`::
+The purpose of the test
+
+`method`::
+The method used to perform the test
+
+`type`::
+The type of the test
+
+`reference`::
+A reference to an external document or resource
+
+`abstract`::
+A boolean indicating whether this test is abstract
+
+
+
+.Working with conformance tests
+[example]
+====
+[source,ruby]
+----
+conformance_test = Modspec::ConformanceTest.new(
+  identifier: "/conf/example/foo",
+  name: "Example test",
+  description: "This is an example conformance test.",
+  targets: ["/req/example/foo"],
+  test_method: "manual",
+  abstract: false
+)
+conformance_test.to_yaml
 ----
 
+[source,yaml]
+----
+identifier: "/conf/example/foo"
+name: "Example test"
+description: "This is an example conformance test."
+abstract: false
+test_method: "manual"
+targets:
+- "/req/example/foo"
+----
+
+[source,ruby]
+----
+> yaml = IO.read('example.yaml')
+> conformance_test = Modspec::ConformanceTest.from_yaml(yaml)
+> <#Modspec::ConformanceTest:0x00007f8b1b8b3d08 @identifier="/conf/example/foo", @name="Example test", @description="This is an example conformance test.", @targets=["/req/example/foo"], @test_method="manual", @abstract=false>
+> conformance_test.name
+> "Example test"
+----
+====
+
+
+Validations:
+
+* *Valid targets*: The targets listed for a conformance test must refer to valid
+identifiers of existing normative statements.
+
+
+=== Suite
+
+A suite represents the entire specification, including all normative statements
+and conformance tests.
+
+NOTE: This is not defined in the ModSpec specification.
+
+.Working with suites
+[example]
+====
+[source,ruby]
+----
+suite = Modspec::Suite.new(
+  identifier: "example-suite",
+  name: "Example suite",
+  normative_statements_classes: [normative_statements_class],
+  conformance_classes: [conformance_class]
+)
+suite.to_yaml
+----
+
+[source,yaml]
+----
+identifier: "example-suite"
+name: "Example suite"
+normative_statements_classes:
+  - identifier: "/req/example"
+    name: "Requirements class"
+    normative_statements:
+      - identifier: "/req/example/foo"
+        name: "Example requirement"
+        statement: "This is an example requirement statement."
+        dependencies:
+          - "/req/bar"
+          - "/req/baz/2"
+conformance_classes:
+  - identifier: "/conf/example"
+    name: "Conformance class"
+    tests:
+      - identifier: "/conf/example/foo"
+        name: "Example test"
+        description: "This is an example conformance test."
+        targets:
+          - "/req/example/foo"
+----
+
+[source,ruby]
+----
+> yaml = IO.read('example-suite.yaml')
+> suite = Modspec::Suite.from_yaml(yaml)
+> <#Modspec::Suite:0x00007f8b1b8b3d08 @identifier="example-suite", @name="Example suite", @normative_statements_classes=[<#Modspec::NormativeStatementsClass:0x00007f8b1b8b3d08 @identifier="/req/example", @name="Requirements class", @dependencies=["/req/baf"], @normative_statements=[<#Modspec::NormativeStatement:0x00007f8b1b8b3d08 @identifier="/req/example/foo", @name="Example requirement", @statement="This is an example requirement statement.", @dependencies=["/req/bar", "/req/baz/2"]>]>], @conformance_classes=[<#Modspec::ConformanceClass:0x00007f8b1b8b3d08 @identifier="/conf/example", @name="Conformance class", @tests=[<#Modspec::ConformanceTest:0x00007f8b1b8b3d08 @identifier="/conf/example/foo", @name="Example test", @description="This is an example conformance test.", @targets=["/req/example/foo"]>], @abstract=false>]>
+> suite.normative_statements_classes.first.name
+> "Requirements class"
+----
+====
+
+Validations:
+
+* *No cyclic dependencies*: The suite ensures that there are no circular
+dependencies among normative statements.
+
+* *Label uniqueness*: Labels must be unique across all classes within the suite.
+
+* *Dependency validation*: The suite verifies that all dependencies between
+normative statements and conformance tests are valid and refer to existing
+elements.
+
+
+The Suite class provides a `from_yaml_files` method to load a Suite instance
+from multiple YAML files. This is particularly useful when your specification is
+split across several files for better organization and maintainability.
+
+To load a Suite from multiple YAML files:
 
 [source,ruby]
 ----
 require 'modspec'
-doc = YAML.load(IO.read('spec/fixtures/chain-rc.yaml'))['normative-statements-classes'].first
-ms = Modspec::NormativeStatementsClass.from_hash(doc)
-puts ms.to_yaml
+
+# Specify the paths to your YAML files
+yaml_files = [
+  'path/to/normative_statements.yaml',
+  'path/to/conformance_tests.yaml'
+]
+
+# Create a Suite instance from the YAML files
+suite = Modspec::Suite.from_yaml_files(yaml_files)
+
+# Now you can work with the suite object
+puts suite.name
+puts suite.normative_statements_classes.count
+puts suite.conformance_classes.count
+----
+
+
+The `Suite` class provides a `combine` method to merge two suites:
+
+[source,ruby]
+----
+combined_suite = suite1.combine(suite2)
+----
+
+This method merges the two suites into a single suite, ensuring that the
+resulting suite is consistent and free of conflicts.
+
+
+=== Validation process
+
+Validations are typically performed when:
+
+. Creating or modifying individual elements (normative statements, conformance tests, etc.)
+. Adding elements to their respective classes
+. Combining suites
+. Loading a suite from YAML or other formats
+
+If any validation fails, an error or a collection of errors is returned,
+describing the specific validation issues encountered.
+
+To manually trigger validation on a suite:
+
+[source,ruby]
+----
+errors = suite.validate_all
+if errors.any?
+  puts "Validation errors:"
+  errors.each { |error| puts "- #{error}" }
+else
+  puts "Suite is valid."
+end
 ----
 
-== Credits
+These validation mechanisms help ensure that the created ModSpec instances are
+consistent, well-formed, and adhere to the expected structure and relationships.
+
+
+== Copyright
 
 This gem is developed, maintained and funded by
 https://www.ribose.com[Ribose Inc.]