agreement-design-prototype 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b8b0ee3c86692db54196238eb53be579e4b3f8b2bc24dee7a6dc67ca89d7068
+  data.tar.gz: 511c0e41fd44633b68f48efc18cb00a29b7692db569eb3ef112adcb6b7392e87
+SHA512:
+  metadata.gz: 7b167ee34fc849c9d4e4470a93ef8b21283f50c8e2059a5e862e1b1239255122cf605eb397e59da8b308b14138237f632a591330b8f3c72cca570e6afa2de3f8
+  data.tar.gz: feeca74a1f808b7663062910a89719db1c551d9a57b100a4f9088219e17b3141bb6eb88a0c6952bb958c9d75a5371c36279a7edc0223596b16c6bfe37bcc33f9

data/README.md

@@ -0,0 +1,17 @@
+
+# Agreement Design
+
+this is a prototype for an agreement design system. In line with 
+[ADR 0010 - use shared drfinition of cmp agreement](https://github.com/Crown-Commercial-Service/CCS-Architecture-Decision-Records/blob/master/doc/adr/0010-use-shared-definition-of-cmp-agreement-when-building-all-cmp-services.md) we want to define the metamodel
+for Commertial Agreements and supporting data in a common way, so all
+services, interfaces and data types are consistent. 
+
+This prototype
+
+- defines a common metamodel
+- models a number of agreement categories (as alpha prototypes, not as definitive representations)
+- produces API definitions such as Swagger
+- possibly produces domain objects (though these should probably be created from API specs)
+- possibly produces data domain descriptions, e.g. Ruby-on-Rails schema records
+
+

data/Rakefile

@@ -0,0 +1,22 @@
+task default: %w[test build]
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*.rb']
+  t.verbose = true
+end
+
+task :build do
+  ruby "build/build_models.rb"
+end
+
+task :deploy do
+   `gem build agreement-design.gemspec`
+   `gem push *.gem`
+end
+
+require 'rake/clean'
+
+CLEAN.include FileList['out', 'gen', '*.gem']

data/agreement-design.gemspec

@@ -0,0 +1,18 @@
+# agreement-design.gemspec
+Gem::Specification.new do |spec|
+  spec.name          = "agreement-design-prototype"
+  spec.version       = "0.0.3"
+  spec.authors       = ["CCS"]
+  spec.homepage      = 'https://github.com/Crown-Commercial-Service/cmp-design-prototype/agreement-design'
+  spec.email         = ["rubygems@humphries.tech"]
+  spec.description   = %q{A prototype of techniques to manage agreement specifications.}
+  spec.summary       = %q{Agreement prototype .}
+  spec.license       = "MIT"
+
+  spec.files         = Dir["./**/*"]
+  spec.executables   = Dir["./bin/*"]
+  spec.test_files    = Dir["./test/**/*"]
+  spec.require_paths = ["src", "model"]
+
+  spec.add_development_dependency "rake", "12.3.0"
+end

data/build/build_models.rb

@@ -0,0 +1,16 @@
+require_relative "../src/diagram"
+require_relative "../model/agreement"
+
+path= File.join(File.dirname(__FILE__), '../', "gen")
+
+# TODO: escape the path somehow so it works when called direct. Works ok from Rake
+diagram= Diagram.new( path, "data_model")
+diagram.describe  Category, Parties
+
+doc= Doc.new( path, "metamodel")
+doc.document_metamodel  Category, Parties
+
+doc= Doc.new( path, "frameworks")
+require_relative '../model/fm'
+doc.document  Category::FM
+

data/gen/diagrams/data_model.dot

@@ -0,0 +1,34 @@
+strict digraph {
+subgraph cluster_Category {
+node [shape=plaintext margin=0];
+label=Category;
+"ItemParameter" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>ItemParameter</TD></TH><TR><TD ALIGN="LEFT">-id </TD></TR><TR><TD ALIGN="LEFT">-detail </TD></TR><TR><TD ALIGN="LEFT">-keyword [*]</TD></TR><TR><TD ALIGN="LEFT">-valueMin </TD></TR><TR><TD ALIGN="LEFT">-valueMax </TD></TR><TR><TD ALIGN="LEFT">-type </TD></TR><TR><TD ALIGN="LEFT">-standard </TD></TR><TR><TD ALIGN="LEFT">-reference </TD></TR></table>>];
+"Agreement" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Agreement</TD></TH><TR><TD ALIGN="LEFT">-id </TD></TR><TR><TD ALIGN="LEFT">-item_params [*]</TD></TR><TR><TD ALIGN="LEFT">-version </TD></TR><TR><TD ALIGN="LEFT">-start_date </TD></TR><TR><TD ALIGN="LEFT">-end_date </TD></TR></table>>];
+"Framework" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Framework</TD></TH><TR><TD ALIGN="LEFT">-fwk_id </TD></TR></table>>];
+"Lot" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Lot</TD></TH><TR><TD ALIGN="LEFT">-fwk_id </TD></TR></table>>];
+"Item" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Item</TD></TH><TR><TD ALIGN="LEFT">-id </TD></TR><TR><TD ALIGN="LEFT">-params </TD></TR><TR><TD ALIGN="LEFT">-description </TD></TR><TR><TD ALIGN="LEFT">-value </TD></TR></table>>];
+"Catalogue" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Catalogue</TD></TH><TR><TD ALIGN="LEFT">-id </TD></TR><TR><TD ALIGN="LEFT">-items [*]</TD></TR><TR><TD ALIGN="LEFT">-agreement_id </TD></TR></table>>];
+"Offer" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Offer</TD></TH><TR><TD ALIGN="LEFT">-id </TD></TR><TR><TD ALIGN="LEFT">-item_id </TD></TR><TR><TD ALIGN="LEFT">-catalogue_id </TD></TR><TR><TD ALIGN="LEFT">-supplier_id </TD></TR><TR><TD ALIGN="LEFT">-description </TD></TR></table>>];
+"Award" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Award</TD></TH><TR><TD ALIGN="LEFT">-buyer_id </TD></TR></table>>];
+}
+subgraph cluster_Parties {
+node [shape=plaintext margin=0];
+label=Parties;
+"Party" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Party</TD></TH><TR><TD ALIGN="LEFT">-id </TD></TR></table>>];
+"Supplier" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Supplier</TD></TH></table>>];
+"Buyer" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Buyer</TD></TH></table>>];
+}
+"Agreement" -> "ItemParameter" [label="{contains} item_params" arrowhead = "none" arrowtail = "diamond" ];
+"Framework" -> "Agreement" [label="extends" arrowhead = "none" arrowtail = "normal" ];
+"Lot" -> "Framework" [label="fwk_id" arrowhead = "open" arrowtail = "none" ];
+"Lot" -> "Agreement" [label="extends" arrowhead = "none" arrowtail = "normal" ];
+"Item" -> "ItemParameter" [label="params" arrowhead = "open" arrowtail = "none" ];
+"Catalogue" -> "Item" [label="{contains} items" arrowhead = "none" arrowtail = "diamond" ];
+"Catalogue" -> "Agreement" [label="agreement_id" arrowhead = "open" arrowtail = "none" ];
+"Offer" -> "Item" [label="item_id" arrowhead = "open" arrowtail = "none" ];
+"Offer" -> "Catalogue" [label="catalogue_id" arrowhead = "open" arrowtail = "none" ];
+"Offer" -> "Supplier" [label="supplier_id" arrowhead = "open" arrowtail = "none" ];
+"Award" -> "Buyer" [label="buyer_id" arrowhead = "open" arrowtail = "none" ];
+"Supplier" -> "Party" [label="extends" arrowhead = "none" arrowtail = "normal" ];
+"Buyer" -> "Party" [label="extends" arrowhead = "none" arrowtail = "normal" ];
+}

data/gen/doc/frameworks.md

@@ -0,0 +1,19 @@
+# Category: FM
+ ## framework
+### framework RM123 
+   - id RM123
+   - fwk_id RM123
+   - version 1.0.0
+ ## lot
+### lot 1 
+   - id 1
+   - fwk_id RM123
+#### item_params 1 
+     - id 1
+     - valueMin 0
+     - valueMax 100
+     - keyword.1 thing
+     - keyword.2 thing2
+### lot 2 
+   - id 2
+   - fwk_id RM123

data/gen/doc/metamodel.md

@@ -0,0 +1,98 @@
+ # Category
+## ItemParameter
+  Defines the meaning of Items in Catalogues
+
+|attribute|type|multiplicity|description|
+|---------|----|------------|-----------|
+|id|String|1||
+|detail|String|1||
+|keyword|String|*||
+|valueMin|String|1||
+|valueMax|String|1||
+|type|String|1|One of: String, Currency, Location, Amount|
+|standard|String|1|which standard defines the item type, such as UBL2.1|
+|reference|String|1|reference within standard, such as UBL2.1|
+## Agreement
+  General definition of Commercial Agreements
+
+|attribute|type|multiplicity|description|
+|---------|----|------------|-----------|
+|id|String|1||
+|item_params|Category::ItemParameter|*||
+|version|String|1|semantic version id of the form X.Y.Z|
+|start_date|Date|1||
+|end_date|Date|1||
+## Framework extends Category::Agreement
+  A kind of Framework used for calloffs, composed of Lots
+
+|attribute|type|multiplicity|description|
+|---------|----|------------|-----------|
+|id|String|1||
+|item_params|Category::ItemParameter|*||
+|version|String|1|semantic version id of the form X.Y.Z|
+|start_date|Date|1||
+|end_date|Date|1||
+|fwk_id|String|1|Such as the RM number|
+## Lot extends Category::Agreement
+  
+
+|attribute|type|multiplicity|description|
+|---------|----|------------|-----------|
+|id|String|1||
+|item_params|Category::ItemParameter|*||
+|version|String|1|semantic version id of the form X.Y.Z|
+|start_date|Date|1||
+|end_date|Date|1||
+|fwk_id|String|1|Part of framework|
+## Item
+  Something offered to a buyer as part of a contract.Items are defined in Catalogues.
+
+|attribute|type|multiplicity|description|
+|---------|----|------------|-----------|
+|id|String|1|Item id, possibly a concatentation of the standard (in params) and the catalogue and an incrementatl id?|
+|params|String|1||
+|description|String|1||
+|value|String|1||
+## Catalogue
+  A collection of items that can be bought via an Agreement.
+
+|attribute|type|multiplicity|description|
+|---------|----|------------|-----------|
+|id|String|1||
+|items|Category::Item|*||
+|agreement_id|String|1||
+## Offer
+  
+
+|attribute|type|multiplicity|description|
+|---------|----|------------|-----------|
+|id|String|1|Offer id, probably a UUID|
+|item_id|String|1||
+|catalogue_id|String|1||
+|supplier_id|String|1||
+|description|String|1|Description of the offer|
+## Award
+  
+
+|attribute|type|multiplicity|description|
+|---------|----|------------|-----------|
+|buyer_id|String|1||
+ # Parties
+## Party
+  
+
+|attribute|type|multiplicity|description|
+|---------|----|------------|-----------|
+|id|String|1|UUID or Salesforce ID?|
+## Supplier extends Parties::Party
+  
+
+|attribute|type|multiplicity|description|
+|---------|----|------------|-----------|
+|id|String|1|UUID or Salesforce ID?|
+## Buyer extends Parties::Party
+  
+
+|attribute|type|multiplicity|description|
+|---------|----|------------|-----------|
+|id|String|1|UUID or Salesforce ID?|

data/model/agreement.rb

@@ -0,0 +1,69 @@
+require_relative '../src/data_model'
+require_relative 'party'
+require 'date'
+include DataModel
+
+domain :Category do
+
+  datatype(:ItemParameter,
+           description: "Defines the meaning of Items in Catalogues") {
+    attribute :id, String
+    attribute :detail, String
+    attribute :keyword, String, ZERO_TO_MANY
+    attribute :valueMin, String
+    attribute :valueMax, String
+    attribute :type, String, "One of: String, Currency, Location, Amount"
+    attribute :standard, String, "which standard defines the item type, such as UBL2.1"
+    attribute :reference, String, "reference within standard, such as UBL2.1"
+  }
+
+  datatype(:Agreement,
+           description: "General definition of Commercial Agreements") {
+    attribute :id, String
+    attribute :item_params, Category::ItemParameter, ZERO_TO_MANY, links: Category::ItemParameter
+    attribute :version, String, "semantic version id of the form X.Y.Z"
+    attribute :start_date, Date
+    attribute :end_date, Date
+  }
+
+  datatype(:Framework, extends: Category::Agreement,
+           description: "A kind of Framework used for calloffs, composed of Lots") {
+    attribute :fwk_id, String, "Such as the RM number"
+  }
+
+  datatype(:Lot, extends: Category::Agreement) {
+    attribute :fwk_id, String, "Part of framework", links: Category::Framework
+  }
+
+  datatype(:Item,
+           description: "Something offered to a buyer as part of a contract."\
+                        "Items are defined in Catalogues.") {
+    attribute :id, String, "Item id, possibly a concatentation of the standard (in params) and the catalogue and an incrementatl id?"
+    attribute :params, String, links: Category::ItemParameter
+    attribute :description, String
+    attribute :value, String
+  }
+
+  datatype(:Catalogue,
+           description: "A collection of items that can be bought via an Agreement.") {
+    attribute :id, String
+    attribute :items, Category::Item, ZERO_TO_MANY, links: Category::Item
+    attribute :agreement_id, String, links: Category::Agreement
+  }
+
+  datatype(:Offer,
+      description: "")  {
+    attribute :id, String, "Offer id, probably a UUID"
+    attribute :item_id, String, links: Category::Item
+    attribute :catalogue_id, String, links: Category::Catalogue
+    attribute :supplier_id, String, links: Parties::Supplier
+    attribute :description, String, "Description of the offer"
+  }
+
+  datatype(:Award,
+           description: "") {
+    attribute :buyer_id, String, links: Parties::Buyer
+  }
+
+end
+

data/model/fm.rb

@@ -0,0 +1,33 @@
+require_relative 'agreement'
+
+Category.new :FM do
+
+  FM_ID = "RM123"
+  framework do
+    id FM_ID
+    fwk_id FM_ID
+    version "1.0.0"
+  end
+
+  lot do
+    id "1"; fwk_id FM_ID
+    item_params do
+      id 1; valueMin 0; valueMax 100
+      keyword :thing
+      keyword :thing2
+    end
+    item_params do
+      id 2; valueMin 22; valueMax 33
+    end
+  end
+
+  lot do
+    id "2"
+    fwk_id FM_ID
+  end
+
+end
+
+puts Category::FM.contents[:lot]
+
+

data/model/party.rb

@@ -0,0 +1,17 @@
+require_relative '../src/data_model'
+include DataModel
+
+domain :Parties do
+
+  datatype :Party do
+    attribute :id, String, "UUID or Salesforce ID?"
+  end
+
+  datatype :Supplier, extends: Parties::Party do
+
+  end
+
+  datatype :Buyer, extends: Parties::Party do
+
+  end
+end

data/out/test/diagrams/d.dot

@@ -0,0 +1,34 @@
+strict digraph {
+subgraph cluster_Category {
+node [shape=plaintext margin=0];
+label=Category;
+"ItemParameter" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>ItemParameter</TD></TH><TR><TD ALIGN="LEFT">-id </TD></TR><TR><TD ALIGN="LEFT">-detail </TD></TR><TR><TD ALIGN="LEFT">-keyword [*]</TD></TR><TR><TD ALIGN="LEFT">-valueMin </TD></TR><TR><TD ALIGN="LEFT">-valueMax </TD></TR><TR><TD ALIGN="LEFT">-type </TD></TR><TR><TD ALIGN="LEFT">-standard </TD></TR><TR><TD ALIGN="LEFT">-reference </TD></TR></table>>];
+"Agreement" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Agreement</TD></TH><TR><TD ALIGN="LEFT">-id </TD></TR><TR><TD ALIGN="LEFT">-item_params [*]</TD></TR><TR><TD ALIGN="LEFT">-version </TD></TR><TR><TD ALIGN="LEFT">-start_date </TD></TR><TR><TD ALIGN="LEFT">-end_date </TD></TR></table>>];
+"Framework" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Framework</TD></TH><TR><TD ALIGN="LEFT">-fwk_id </TD></TR></table>>];
+"Lot" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Lot</TD></TH><TR><TD ALIGN="LEFT">-fwk_id </TD></TR></table>>];
+"Item" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Item</TD></TH><TR><TD ALIGN="LEFT">-id </TD></TR><TR><TD ALIGN="LEFT">-params </TD></TR><TR><TD ALIGN="LEFT">-description </TD></TR><TR><TD ALIGN="LEFT">-value </TD></TR></table>>];
+"Catalogue" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Catalogue</TD></TH><TR><TD ALIGN="LEFT">-id </TD></TR><TR><TD ALIGN="LEFT">-items [*]</TD></TR><TR><TD ALIGN="LEFT">-agreement_id </TD></TR></table>>];
+"Offer" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Offer</TD></TH><TR><TD ALIGN="LEFT">-id </TD></TR><TR><TD ALIGN="LEFT">-item_id </TD></TR><TR><TD ALIGN="LEFT">-catalogue_id </TD></TR><TR><TD ALIGN="LEFT">-supplier_id </TD></TR><TR><TD ALIGN="LEFT">-description </TD></TR></table>>];
+"Award" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Award</TD></TH><TR><TD ALIGN="LEFT">-buyer_id </TD></TR></table>>];
+}
+subgraph cluster_Parties {
+node [shape=plaintext margin=0];
+label=Parties;
+"Party" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Party</TD></TH><TR><TD ALIGN="LEFT">-id </TD></TR></table>>];
+"Supplier" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Supplier</TD></TH></table>>];
+"Buyer" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>Buyer</TD></TH></table>>];
+}
+"Agreement" -> "ItemParameter" [label="{contains} item_params" arrowhead = "none" arrowtail = "diamond" ];
+"Framework" -> "Agreement" [label="extends" arrowhead = "none" arrowtail = "normal" ];
+"Lot" -> "Framework" [label="fwk_id" arrowhead = "open" arrowtail = "none" ];
+"Lot" -> "Agreement" [label="extends" arrowhead = "none" arrowtail = "normal" ];
+"Item" -> "ItemParameter" [label="params" arrowhead = "open" arrowtail = "none" ];
+"Catalogue" -> "Item" [label="{contains} items" arrowhead = "none" arrowtail = "diamond" ];
+"Catalogue" -> "Agreement" [label="agreement_id" arrowhead = "open" arrowtail = "none" ];
+"Offer" -> "Item" [label="item_id" arrowhead = "open" arrowtail = "none" ];
+"Offer" -> "Catalogue" [label="catalogue_id" arrowhead = "open" arrowtail = "none" ];
+"Offer" -> "Supplier" [label="supplier_id" arrowhead = "open" arrowtail = "none" ];
+"Award" -> "Buyer" [label="buyer_id" arrowhead = "open" arrowtail = "none" ];
+"Supplier" -> "Party" [label="extends" arrowhead = "none" arrowtail = "normal" ];
+"Buyer" -> "Party" [label="extends" arrowhead = "none" arrowtail = "normal" ];
+}

data/out/test/doc/doctest.md

@@ -0,0 +1,19 @@
+# Category: FM
+ ## framework
+### framework RM123 
+   - id RM123
+   - fwk_id RM123
+   - version 1.0.0
+ ## lot
+### lot 1 
+   - id 1
+   - fwk_id RM123
+#### item_params 1 
+     - id 1
+     - valueMin 0
+     - valueMax 100
+     - keyword.1 thing
+     - keyword.2 thing2
+### lot 2 
+   - id 2
+   - fwk_id RM123

data/src/data_model.rb

@@ -0,0 +1,165 @@
+module DataModel
+
+  SINGLE = 1..1
+  ONE_TO_MANY = 1..-1
+  ZERO_TO_MANY = 0..-1
+
+  class DataType
+
+    class << self
+
+      def init(name, domain, extends, description)
+        @attributes = {}
+        @typename = name
+        @domain = domain
+        @extends = extends
+        @description = description
+
+        self.define_singleton_method :domain do
+          @domain
+        end
+        self.define_singleton_method :description do
+          @description
+        end
+
+        self.define_singleton_method(:attributes) do |inherited=true|
+          if inherited && self.superclass.respond_to?(:attributes)
+            self.superclass.attributes.merge @attributes
+          else
+            @attributes
+          end
+        end
+
+      end
+
+      def typename
+        @typename
+      end
+
+      def extends
+        @extends < DataType ? @extends.name : nil
+      end
+
+      def attribute(name, type, *args, multiplicity: SINGLE, description: "", links: nil)
+        options = {:multiplicity => multiplicity, :description => description, :name => name, :type => type}
+        if links
+          options[:links]= links
+        end
+
+        for opt in args
+          if opt.is_a? Range
+            options[:multiplicity] = opt
+          elsif opt.is_a? String
+            options[:description] = opt
+          else
+            raise "optional arguments should be string (description), or range\n " << opt.to_s
+          end
+        end
+        @attributes[name] = options
+      end
+
+    end
+
+    attr_reader :name, :attributes
+
+    def initialize(name)
+      @name = name
+      @attributes = {}
+    end
+
+
+    def method_missing(sym, *args, &block)
+      if (args.length==0) && @attributes[sym]
+        return @attributes[sym]
+      end
+      if self.class.attributes[sym]
+        if self.class.attributes[sym][:multiplicity] != SINGLE
+          @attributes[sym] = [] unless @attributes[sym]
+          @attributes[sym] << valueof(sym, *args, &block)
+        else
+          @attributes[sym] = valueof(sym, *args, &block)
+        end
+        return @attributes[sym]
+      end
+      puts "Warning: unknown attribute #{sym}?"
+    end
+
+    def to_s
+      "#{self.class.typename} #{self.name} #{@attributes}"
+    end
+
+    private
+
+    def valueof(sym, *args, &block)
+      if self.class.attributes[sym][:type] < DataType
+        at = self.class.attributes[sym][:type].new(self.class.attributes[sym][:name])
+        if nil == block
+          raise "Need a block for a nested type #{sym}"
+        end
+        at.instance_exec &block
+        return at
+      else
+        args[0]
+      end
+    end
+
+  end
+
+  class Domain
+
+    class << self
+      def datatype(name, extends: DataType, description: "", &block)
+        @types = {} unless instance_variable_defined? :@types
+        if extends.class != Class
+          extends = @types.fetch(extends, DataType)
+        end
+        type = self.const_set name, Class.new(extends)
+        # puts "defined #{type} from #{name} on #{self }"
+        @types[name] = type
+        self.define_singleton_method(:types) {@types}
+        dom = self
+        type.instance_exec do
+          init name, dom, extends, description
+        end
+        type.instance_exec &block
+        type
+      end
+
+    end
+
+    attr_reader :contents, :name
+
+    def initialize name, &block
+      @contents = {}
+      @name = name
+      self.class.const_set name, self
+      self.instance_exec &block
+    end
+
+    def method_missing(sym, &block)
+      # create a new datatype for each matching type name, and run its block
+      for t in self.class.types.values
+        if t.typename.downcase == sym
+          decl = t.new(sym)
+          @contents[sym] = [] unless @contents[sym]
+          @contents[sym] << decl
+          decl.instance_exec &block
+          return decl
+        end
+      end
+      puts "Warning unknown type #{sym} ignored"
+    end
+
+  end
+
+
+  module_function
+
+  def domain(name, &block)
+    dom = Object.const_set name, Class.new(Domain)
+    dom.instance_exec &block
+    return dom
+  end
+
+
+end # DataModel

data/src/diagram.rb

@@ -0,0 +1,146 @@
+require 'fileutils'
+require_relative 'doc'
+
+
+class TableElement < Element
+  def initialize file, node
+    super(file)
+    @node = node
+    pput %Q("#{@node}" [label=<<table BORDER="1" CELLBORDER="0" CELLSPACING="0"><TH><TD>#{@node}</TD></TH>)
+    @items = []
+  end
+
+  def item i
+    @items << i
+    self.pput %Q(<TR><TD ALIGN="LEFT">-#{i}</TD></TR>)
+  end
+
+  def finish
+    # self.pput " " << @items.join( ",")
+    self.pput "</table>"
+    self.pput ">];\n"
+  end
+
+
+end
+
+class Graph < Element
+  def initialize file
+    super(file)
+    self.pput "strict digraph {\n"
+  end
+
+  def finish
+    self.pput "}\n"
+  end
+
+end
+
+class SubGraph < Element
+  def initialize file, model
+    super(file)
+    self.pput "subgraph cluster_#{model} {\n"
+    self.pput "node [shape=plaintext margin=0];\n"
+    self.pput "label=#{model};\n"
+  end
+
+  def finish
+    self.pput "}\n"
+  end
+
+end
+
+class Links < Element
+
+  def link el1, el2, label: el, arrowhead: nil, arrowtail: nil
+    ah = arrowhead ? %Q!arrowhead = "#{arrowhead}"! : ""
+    at = arrowtail ? %Q!arrowtail = "#{arrowtail}"! : ""
+    pput %Q!"#{el1}" -> "#{el2}" [label="#{label}" #{ah} #{at} ];\n!
+  end
+
+end
+
+class Diagram < Doc
+
+  def dotfile
+    File.join(diagram_path, "#{self.name}.dot")
+  end
+
+  def jpgfile
+    File.join(image_path, "#{self.name}.jpg")
+  end
+
+  def describe *models
+
+    FileUtils.mkpath diagram_path
+    FileUtils.mkpath image_path
+    File.open(self.dotfile, "w") do |file|
+      graph = Graph.new(file)
+      for model in models
+        subgraph = SubGraph.new(file, modelname(model))
+        for type in model.types.values
+          table = TableElement.new(file, typename(type))
+          for att in type.attributes(false).values
+            table.item att_detail(att)
+          end
+          table.finish
+        end
+        subgraph.finish
+      end
+      for model in models
+        links = Links.new(file)
+        for type in model.types.values
+          for att in type.attributes(false).keys
+            if type.attributes[att][:links]
+              contains = (type.attributes[att][:type] < DataType)
+              links.link typename(type),
+                         typename(type.attributes[att][:links]),
+                         label: %Q!#{contains ? "{contains} " : ""}#{type.attributes[att][:name]}!,
+                         arrowhead: contains ? "none": "open",
+                         arrowtail: contains ? "diamond": "none"
+            end
+          end
+          if type.superclass < DataType
+            links.link typename(type),
+                       typename(type.superclass),
+                       label: "extends",
+                       arrowhead: "none",
+                       arrowtail:  "normal"
+          end
+        end
+        links.finish
+      end
+      graph.finish
+    end
+
+    unless system("dot -Tjpg #{self.dotfile} > #{self.jpgfile}")
+      puts "Error: couldn't create jpeg: #{self.jpgfile}"
+    end
+
+  end
+
+  def att_detail(att)
+    mult = att[:multiplicity]
+    mstring = (mult == ZERO_TO_MANY ? "[*]" : mult == ONE_TO_MANY ? "[1..*]" : mult == SINGLE ? "" : "[#{mult.to_s}]")
+    "#{att[:name]} #{mstring}"
+  end
+
+  def modelname m
+    m.name.gsub(/^#{DataModel.name}::/, "").gsub /::/, "-"
+  end
+
+  def typename t
+    t.name.gsub(/^#{t.domain}::/, "").gsub /::/, "-"
+  end
+
+  private
+
+  def image_path
+    File.join(self.path, "images")
+  end
+
+  def diagram_path
+    File.join(self.path, "diagrams")
+  end
+
+end

data/src/doc.rb

@@ -0,0 +1,181 @@
+class Element
+  def initialize file
+    @file = file
+  end
+
+  def finish
+    self
+  end
+
+  protected
+
+  def pput(string)
+    @file.print string
+    self
+  end
+
+end
+
+def cond_call(depth, id, value, lam, lambdas)
+  if lambdas[lam]
+    return lambdas[lam].(depth, id, value)
+  end
+  return 0
+end
+
+# each lambda takes the depth, id, value
+# Lambdas are:
+#               :before_type_lambda,
+#               :after_type_lambda,
+#               :before_array_lambda,
+#               :after_array_lambda,
+#               :attribute_lambda
+# which takes a type and returns an object (the id)
+# depth is the number counting from zero, incremented with array elements and nested types.
+# ID is a nested int of the type a for types and a.b for array types,
+# and is the name of the attribute for attributes
+# decl is the type or attribute or array
+
+def transform_type depth, id, decl, lambdas
+
+  if decl.class <= Array
+    cond_call(depth, id, decl, :before_array_lambda, lambdas)
+    j = 1
+    for aa in decl
+      transform_type(depth , "#{id}.#{j}", aa, lambdas)
+      j = j + 1
+    end
+    cond_call(depth, id, decl, :after_array_lambda, lambdas)
+  elsif decl.class <= DataType
+    cond_call(depth, id, decl, :before_type_lambda, lambdas)
+    for ak in decl.attributes.keys
+      av = decl.attributes[ak]
+      transform_type(depth + 1, ak, av, lambdas)
+    end
+    cond_call(depth, id, decl, :after_type_lambda, lambdas)
+  else
+    cond_call(depth, id, decl, :attribute_lambda, lambdas)
+  end
+  self
+end
+
+class ClassNameElement < Element
+
+  def write cat
+    pput %Q!\# #{cat.class}: #{cat.name}\n!
+    if (cat.respond_to?(:description))
+      pput %Q! #{cat.description}\n!
+    end
+  end
+
+end
+
+class GroupElement < Element
+
+  def write grpname, level: 2
+    pput %Q! #{'#' * level} #{grpname}\n!
+  end
+
+end
+
+class TypeDeclElement < Element
+
+  def write indent, id, decl
+    transform_type(indent, id, decl,
+                   {
+                       :before_type_lambda => lambda do |indent, id, decl|
+                         pput %Q!####{'#' * indent} #{decl.name} #{decl.attributes[:id] || id} \n!
+                       end,
+                       :attribute_lambda => lambda do |indent, id, decl|
+                         pput %Q!#{"  " * indent} - #{id} #{decl}\n!
+                       end
+                   })
+    self
+  end
+
+end
+
+class MetaTypeElement < Element
+
+  def write type
+    pput "## #{type.typename}"
+    if type.extends
+      pput " extends #{type.extends}"
+    end
+    pput "\n  #{type.description}\n\n"
+    pput "|attribute|type|multiplicity|description|\n"
+    pput "|---------|----|------------|-----------|\n"
+    for a in type.attributes.values
+      pput "|#{a[:name]}|#{a[:type]}|#{self.multiplicity(a)}|#{a[:description]}|\n"
+    end
+    self
+  end
+
+  def multiplicity m
+    m = m[:multiplicity]
+    if m.end == -1
+      if m.begin == 0
+        return "*"
+      else
+        return "#{m.begin}..*"
+      end
+    end
+    if m.end == m.begin
+      return m.end.to_s
+    end
+    return m.to_s
+  end
+end
+
+class Doc
+  attr_accessor :path, :name
+
+  def initialize path, name
+    self.path = path
+    self.name = name
+  end
+
+  def document *models
+    FileUtils.mkpath doc_path
+    File.open(self.docfile, "w") do |file|
+      for model in models
+        dom = ClassNameElement.new(file)
+        dom.write model
+        for typename in model.contents.keys
+          grp = GroupElement.new(file)
+          grp.write typename
+          i = 1
+          for decl in model.contents[typename]
+            TypeDeclElement.new(file).write(0, i, decl).finish
+            i = i + 1
+          end
+          grp.finish
+        end
+        dom.finish
+      end
+    end
+  end
+
+  def document_metamodel *models
+    FileUtils.mkpath doc_path
+    File.open(self.docfile, "w") do |file|
+      for model in models
+        dom = GroupElement.new(file)
+        dom.write model.name, level: 1
+        for type in model.types.values
+          MetaTypeElement.new(file).write(type).finish
+        end
+        dom.finish
+      end
+    end
+  end
+
+  def docfile
+    File.join(doc_path, "#{self.name}.md")
+  end
+
+  def doc_path
+    File.join(self.path, "doc")
+  end
+
+end

data/test/data_model_test.rb

@@ -0,0 +1,91 @@
+require 'test/unit'
+require_relative '../src/data_model'
+include DataModel
+
+DataModel::domain :TestMetamodel do
+
+  datatype :BasicType do
+    attribute :id, String
+  end
+
+  datatype :Table, description: "Test type" do
+    MULT = [0..10]
+    DESC = "table of values"
+    attribute :vals, Integer,
+              multiplicity: MULT,
+              :description => DESC
+    attribute :morevals, String, 2..5, "array of strings"
+  end
+
+  datatype :ReferencingType do
+    attribute :id, String
+    attribute :mate, TestMetamodel::BasicType
+  end
+
+  datatype :DerivedType, extends: TestMetamodel::ReferencingType do
+    attribute :more, String
+  end
+
+  datatype :DerivedTypeNamingClass, extends: TestMetamodel::ReferencingType do
+    attribute :othermore, String
+  end
+
+  datatype :Empty do
+
+  end
+
+end
+
+class DataModelTest < Test::Unit::TestCase
+
+
+  def test_metamodel
+    assert(contains(TestMetamodel::BasicType, :id), 'has id attribute')
+    id_t = TestMetamodel::BasicType.attributes[:id]
+    assert_equal(1..1, TestMetamodel::BasicType.attributes[:id][:multiplicity], "has default multiplicity")
+    assert(id_t[:type] == String)
+
+    assert_equal(MULT, TestMetamodel::Table.attributes[:vals][:multiplicity]);
+    assert_equal(2..5, TestMetamodel::Table.attributes[:morevals][:multiplicity]);
+    assert_equal("Test type", TestMetamodel::Table.description);
+
+    assert_equal(MULT, TestMetamodel::Table.attributes[:vals][:multiplicity], "has multiplicity")
+    assert_equal(DESC, TestMetamodel::Table.attributes[:vals][:description], "has description")
+
+    mate_t = TestMetamodel::ReferencingType.attributes[:mate]
+    assert(mate_t[:type] == TestMetamodel::BasicType)
+
+    assert(contains(TestMetamodel::DerivedType, :more), "has derived attribute")
+    assert(contains(TestMetamodel::DerivedType, :mate), "has derived attribute")
+    assert(contains(TestMetamodel::DerivedType, :id), "has derived attribute")
+    assert(contains(TestMetamodel::DerivedTypeNamingClass, :othermore), "has derived attribute")
+    assert(contains(TestMetamodel::DerivedTypeNamingClass, :id), "has derived attribute")
+  end
+
+  TestMetamodel.new :Test_Model do
+    table do
+      vals 1
+      vals 2
+    end
+    referencingtype do
+      id :owner
+      mate do
+        id :content
+      end
+    end
+  end
+
+  def test_model
+    assert_equal(1, TestMetamodel::Test_Model.contents[:table][0].attributes[:vals][0], "has vals")
+    assert_equal(2, TestMetamodel::Test_Model.contents[:table][0].attributes[:vals][1], "has vals")
+    assert_equal(:content, TestMetamodel::Test_Model.contents[:referencingtype][0].attributes[:mate].attributes[:id], "has vals")
+    assert_equal(:content, TestMetamodel::Test_Model.contents[:referencingtype][0].mate.id, "has vals")
+  end
+
+  private
+
+  def contains(type, attr)
+    type.attributes.keys.one? {|k| k == attr}
+  end
+
+end

data/test/diagram_test.rb

@@ -0,0 +1,34 @@
+require 'test/unit'
+require_relative '../src/diagram'
+require_relative '../model/agreement'
+include DataModel
+
+
+class DiagramTest < Test::Unit::TestCase
+
+  # Called before every test method runs. Can be used
+  # to set up fixture information.
+  PATH = "out/test/"
+  NAME = "d"
+
+  def setup
+    @d = Diagram.new(PATH, NAME)
+    if File.file?(@d.dotfile)
+      File.delete(@d.dotfile)
+    end
+    if File.file?(@d.jpgfile)
+      File.delete(@d.jpgfile)
+    end
+  end
+
+  def test_dot
+    assert_equal("out/test/diagrams/d.dot", @d.dotfile, "file format")
+    assert_equal("out/test/images/d.jpg", @d.jpgfile, "file format")
+    assert(!File.file?(@d.dotfile), "no dotfile")
+    @d.describe( Category)
+    assert(File.file?(@d.dotfile), "file created")
+    assert(File.file?(@d.jpgfile), "file created")
+    # TODO test the features in the diagram
+    @d.describe( Category, Parties)
+  end
+end

data/test/doc_test.rb

@@ -0,0 +1,27 @@
+require 'test/unit'
+require_relative '../src/doc'
+require_relative '../model/fm'
+include DataModel
+
+class DocTest < Test::Unit::TestCase
+
+  # Called before every test method runs. Can be used
+  # to set up fixture information.
+  PATH = "out/test/"
+  NAME = "doctest"
+
+  def setup
+    @d = Doc.new(PATH, NAME)
+    if File.file?(@d.docfile)
+      File.delete(@d.docfile)
+    end
+  end
+
+
+  def test_dot
+    assert_equal("#{PATH}doc/#{NAME}.md", @d.docfile, "file name")
+    assert(!File.file?(@d.docfile), "no dotfile")
+    @d.document( Category::FM)
+    assert(File.file?(@d.docfile), "file created")
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: agreement-design-prototype
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- CCS
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-08-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 12.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 12.3.0
+description: A prototype of techniques to manage agreement specifications.
+email:
+- rubygems@humphries.tech
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- "./README.md"
+- "./Rakefile"
+- "./agreement-design.gemspec"
+- "./build/build_models.rb"
+- "./gen/diagrams/data_model.dot"
+- "./gen/doc/frameworks.md"
+- "./gen/doc/metamodel.md"
+- "./gen/images/data_model.jpg"
+- "./model/agreement.rb"
+- "./model/fm.rb"
+- "./model/party.rb"
+- "./out/test/diagrams/d.dot"
+- "./out/test/doc/doctest.md"
+- "./out/test/images/d.jpg"
+- "./src/data_model.rb"
+- "./src/diagram.rb"
+- "./src/doc.rb"
+- "./test/data_model_test.rb"
+- "./test/diagram_test.rb"
+- "./test/doc_test.rb"
+homepage: https://github.com/Crown-Commercial-Service/cmp-design-prototype/agreement-design
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- src
+- model
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Agreement prototype .
+test_files:
+- "./test/diagram_test.rb"
+- "./test/data_model_test.rb"
+- "./test/doc_test.rb"