govuk_schemas 0.1.0 → 0.2.0

data/lib/govuk_schemas/random_example.rb

@@ -1,24 +1,46 @@
 require "govuk_schemas/random"
 require "govuk_schemas/random_item_generator"
-require "active_support/core_ext/hash"
 require "json-schema"
 require "json"
 
 module GovukSchemas
   class RandomExample
-    # TODO: add docs
+    # Returns a new `GovukSchemas::RandomExample` object.
+    #
+    # For example:
+    #
+    #     schema = GovukSchemas::Schema.find("detailed_guide", schema_type: "frontend")
+    #     GovukSchemas::RandomExample.new(schema).payload
+    #
+    # @param [Hash] schema A JSON schema.
+    # @return [GovukSchemas::RandomExample]
     def initialize(schema:)
       @schema = schema
       @random_generator = RandomItemGenerator.new(schema: schema)
     end
 
-    # TODO: add docs
+    # Returns a new `GovukSchemas::RandomExample` object.
+    #
+    # For example:
+    #
+    #     generator = GovukSchemas::RandomExample.for_schema("detailed_guide", schema_type: "frontend")
+    #     generator.payload
+    #     # => {"base_path"=>"/e42dd28e", "title"=>"dolor est...", "publishing_app"=>"elit"...}
+    #
+    # @return [GovukSchemas::RandomExample]
     def self.for_schema(schema_name, schema_type:)
       schema = GovukSchemas::Schema.find(schema_name, schema_type: schema_type)
       GovukSchemas::RandomExample.new(schema: schema)
     end
 
-    # TODO: add docs
+    # Return a hash with a random content item
+    #
+    # Example:
+    #
+    #     GovukSchemas::RandomExample.for_schema("detailed_guide", schema_type: "frontend").payload
+    #     # => {"base_path"=>"/e42dd28e", "title"=>"dolor est...", "publishing_app"=>"elit"...}
+    #
+    # @return [Hash] A content item
     def payload
       item = @random_generator.payload
       errors = validation_errors_for(item)
@@ -30,9 +52,20 @@ module GovukSchemas
       item
     end
 
-    # TODO: add docs
+    # Return a content item merged with a hash. If the resulting content item
+    # isn't valid against the schema an error will be raised.
+    #
+    # Example:
+    #
+    #      random = GovukSchemas::RandomExample.for_schema("detailed_guide", schema_type: "frontend")
+    #      random.merge_and_validate(base_path: "/foo")
+    #      # => {"base_path"=>"/e42dd28e", "title"=>"dolor est...", "publishing_app"=>"elit"...}
+    #
+    # @param [Hash] hash The hash to merge the random content with
+    # @return [Hash] A content item
+    # @raise [GovukSchemas::InvalidContentGenerated]
     def merge_and_validate(hash)
-      item = payload.merge(hash.stringify_keys)
+      item = payload.merge(Utils.stringify_keys(hash))
       errors = validation_errors_for(item)
 
       if errors.any?

data/lib/govuk_schemas/random_item_generator.rb

@@ -7,6 +7,8 @@ module GovukSchemas
   # The "randomness" here is quote relative, it's particularly tailored to the
   # GOV.UK content schemas. For example, strings are limited to a couple of
   # hundred characters to keep the resulting items small.
+  #
+  # @private
   class RandomItemGenerator
     def initialize(schema:)
       @schema = schema
@@ -19,6 +21,13 @@ module GovukSchemas
   private
 
     def generate_value(props)
+      # TODO: #/definitions/nested_headers are recursively nested and can cause
+      # infinite loops. We need to add something that detects and prevents the
+      # loop. In the meantime return a valid value.
+      if props['$ref'] == "#/definitions/nested_headers"
+        return [{ "text" => "1", "level" => 1, "id" => "ABC" }]
+      end
+
       # JSON schemas can have "pointers". We use this to extract defintions and
       # reduce duplication. To make the schema easily parsable we inline the
       # reference here.
@@ -39,9 +48,13 @@ module GovukSchemas
       type = Array(type).sample
 
       if props['anyOf']
-        # TODO: this should generate values for 1 or more values, instead of just one
         generate_value(props['anyOf'].sample)
       elsif props['oneOf']
+        # FIXME: Generating valid data for a `oneOf` schema is quite interesting.
+        # According to the JSON Schema spec a `oneOf` schema is only valid if
+        # the data is valid against *only one* of the clauses. To do this
+        # properly, we'd have to verify that the data generated below doesn't
+        # validate against the other schemas in `props['oneOf']`.
         generate_value(props['oneOf'].sample)
       elsif props['allOf']
         props['allOf'].each_with_object({}) do |subschema, hash|

data/lib/govuk_schemas/schema.rb

@@ -3,7 +3,7 @@ module GovukSchemas
     # Find a schema by name
     #
     # @param schema_name [String] Name of the schema/format
-    # @param schema_type [String] The type: frontend, backend or links
+    # @param schema_type [String] The type: frontend, publisher, notification or links
     def self.find(schema_name, schema_type:)
       schema_type = "publisher_v2" if schema_type == "publisher"
       file_path = "#{GovukSchemas::CONTENT_SCHEMA_DIR}/dist/formats/#{schema_name}/#{schema_type}/schema.json"
@@ -11,11 +11,21 @@ module GovukSchemas
     end
 
     # Return all schemas in a hash, keyed by schema name
-    def self.all
-      Dir.glob("#{GovukSchemas::CONTENT_SCHEMA_DIR}/dist/**/*.json").reduce({}) do |hash, file_path|
+    #
+    # @param schema_type [String] The type: frontend, publisher, notification or links
+    def self.all(schema_type: '*')
+      schema_type = "publisher_v2" if schema_type == "publisher"
+      Dir.glob("#{GovukSchemas::CONTENT_SCHEMA_DIR}/dist/formats/*/#{schema_type}/*.json").reduce({}) do |hash, file_path|
         hash[file_path] = JSON.parse(File.read(file_path))
         hash
       end
     end
+
+    # Return a random schema of a certain type
+    #
+    # @param schema_type [String] The type: frontend, publisher, notification or links
+    def self.random_schema(schema_type:)
+      all(schema_type: schema_type).values.sample
+    end
   end
 end

data/lib/govuk_schemas/utils.rb

@@ -0,0 +1,16 @@
+module GovukSchemas
+  # @private
+  module Utils
+    def self.stringify_keys(hash)
+      new_hash = {}
+      hash.each do |k, v|
+        new_hash[k.to_s] = v
+      end
+      new_hash
+    end
+
+    def self.parameterize(string)
+      string.gsub(/[^a-z0-9\-_]+/i, '-')
+    end
+  end
+end

data/lib/govuk_schemas/version.rb

@@ -1,3 +1,4 @@
 module GovukSchemas
-  VERSION = "0.1.0".freeze
+  # @private
+  VERSION = "0.2.0".freeze
 end

metadata

@@ -1,43 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: govuk_schemas
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - GOV.UK Dev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-20 00:00:00.000000000 Z
+date: 2016-09-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json-schema
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: activesupport
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.5.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.5.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +94,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 description: Gem to generate test data based on GOV.UK content schemas
 email:
 - govuk-dev@digital.cabinet-office.gov.uk
@@ -119,11 +119,29 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.md
 - README.md
 - Rakefile
 - bin/console
+- docs/GovukSchemas.html
+- docs/GovukSchemas/RandomExample.html
+- docs/GovukSchemas/Schema.html
+- docs/_index.html
+- docs/class_list.html
+- docs/css/common.css
+- docs/css/full_list.css
+- docs/css/style.css
+- docs/file.README.html
+- docs/file_list.html
+- docs/frames.html
+- docs/index.html
+- docs/js/app.js
+- docs/js/full_list.js
+- docs/js/jquery.js
+- docs/method_list.html
+- docs/top-level-namespace.html
 - govuk_schemas.gemspec
 - jenkins-schema.sh
 - jenkins.sh
@@ -132,6 +150,7 @@ files:
 - lib/govuk_schemas/random_example.rb
 - lib/govuk_schemas/random_item_generator.rb
 - lib/govuk_schemas/schema.rb
+- lib/govuk_schemas/utils.rb
 - lib/govuk_schemas/version.rb
 homepage: https://github.com/alphagov/govuk_schemas_gem
 licenses: