govuk_taxonomy_helpers 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4a9bcf516b96e7dcec97d7c83fc3915100922700
+  data.tar.gz: ded38f9b3e0d1602a22b4d3d1e498995a65048a9
+SHA512:
+  metadata.gz: 2a7bbbb176477e4d4c7611c900f4df8830579cc9b2289b93cb18b3a39bf397c2cfca51e57b3ef3c274cc1140fb4548a83e5912a9e85a22f34312593e4c3b6bdd
+  data.tar.gz: 2730337dfffb046d85fb25c84c728285bdd111245e3758ff7e0188dd87d2545936cfab48e3e7c4a7f4af3363e897e84cd673e14f43ce72c80b3b785c34f52642

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,12 @@
+AllCops:
+  TargetRubyVersion: 2.3
+
+# Method documentation is required to ensure the gem is fully documented
+Style/DocumentationMethod:
+  Enabled: true
+
+Style/VariableNumber:
+  Enabled: false
+
+Style/SafeNavigation:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+2.4.0

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.0.1
+
+* Gem created

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in govuk_taxonomy_helpers.gemspec
+gemspec

data/Jenkinsfile

@@ -0,0 +1,44 @@
+#!/usr/bin/env groovy
+
+REPOSITORY = 'govuk_taxonomy_helpers'
+
+node {
+  def govuk = load '/var/lib/jenkins/groovy_scripts/govuk_jenkinslib.groovy'
+
+  try {
+    stage('Checkout') {
+      checkout scm
+    }
+
+    stage('Clean') {
+      govuk.cleanupGit()
+      govuk.mergeMasterBranch()
+    }
+
+    stage('Bundle') {
+      govuk.bundleGem()
+    }
+
+    stage('Linter') {
+      govuk.rubyLinter()
+    }
+
+    stage('Tests') {
+      govuk.runTests('spec')
+    }
+
+    if(env.BRANCH_NAME == "master") {
+      stage('Publish Gem') {
+        govuk.publishGem(REPOSITORY, env.BRANCH_NAME)
+      }
+    }
+
+  } catch (e) {
+    currentBuild.result = 'FAILED'
+    step([$class: 'Mailer',
+          notifyEveryUnstableBuild: true,
+          recipients: 'govuk-ci-notifications@digital.cabinet-office.gov.uk',
+          sendToIndividuals: true])
+    throw e
+  }
+}

data/LICENCE.txt

@@ -0,0 +1,19 @@
+Copyright (C) 2017 Crown copyright (Government Digital Service)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,90 @@
+# GovukTaxonomyHelpers
+
+Parses the taxonomy of GOV.UK into a browseable tree structure.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'govuk_taxonomy_helpers'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install govuk_taxonomy_helpers
+
+## Usage
+
+The API is provisional and is likely to change for versions < 1.0.0.
+
+To access the taxonomy, first request the content from the [publishing api](https://github.com/alphagov/publishing-api), then parse it to get a `LinkedContentItem` object.
+
+```ruby
+require 'govuk_taxonomy_helpers'
+
+content_item = Services.publishing_api.get_content("c75c541-403f-4cb1-9b34-4ddde816a80d")
+expanded_links = Services.publishing_api.get_expanded_links("c75c541-403f-4cb1-9b34-4ddde816a80d")
+
+taxonomy = GovukTaxonomyHelpers::LinkedContentItem.from_publishing_api(
+  content_item: content_item,
+  expanded_links: expanded_links
+)
+```
+
+A `LinkedContentItem` built from a taxon can access all *narrower term* taxons below it and all *broader term* taxons above it.
+
+A taxon may have many child taxons, but can only have one or zero parents.
+
+```ruby
+taxon.children
+# => [LinkedContentItem(title: child-1-id, ...), LinkedContentItem(title: child-2, ...)]
+
+taxon.parent
+# => LinkedContentItem(title: root, ...)
+
+taxon.breadcrumb_trail
+# => [LinkedContentItem(title: root, ...), LinkedContentItem(title: taxon, ...)]
+```
+
+A `LinkedContentItem` built from an content_item that isn't a taxon can access all taxons associated with it.
+
+```ruby
+content_item.taxons
+# => [LinkedContentItem(title: taxon, ...),
+#     LinkedContentItem(title: another-taxon, ...)]
+
+content_item.taxons_with_ancestors
+# => [LinkedContentItem(title: root, ...),
+#     LinkedContentItem(title: taxon-parent, ...),
+#     LinkedContentItem(title: taxon, ...),
+#     LinkedContentItem(title: another-taxon, ...)]
+```
+
+## Nomenclature
+
+- **Taxonomy**: The hierarchy of topics used to classify content by subject on GOV.UK. Not all content is tagged to the taxonomy. We are rolling out the taxonomy and navigation theme-by-theme.
+- **Taxon**: Any topic within the taxonomy.
+- **Content Item**: A distinct version of a document. A taxon is also a type of content item.
+
+## Documentation
+
+To run a Yard server locally to preview documentation, run:
+
+    $ bundle exec yard server --reload
+
+## Contributing
+
+1. Fork it ( https://github.com/alphagov/govuk_taxonomy_helpers/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+[MIT License](LICENCE.txt)

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/govuk_taxonomy_helpers.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'govuk_taxonomy_helpers/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "govuk_taxonomy_helpers"
+  spec.version       = GovukTaxonomyHelpers::VERSION
+  spec.authors       = ["Government Digital Service"]
+  spec.email         = ["govuk-dev@digital.cabinet-office.gov.uk"]
+  spec.summary       = "Parses the taxonomy of GOV.UK into a browseable tree structure."
+  spec.homepage      = "https://github.com/alphagov/govuk_taxonomy_helpers"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake", "~> 10.0"
+
+  spec.add_development_dependency "rspec", "~> 3.5"
+  spec.add_development_dependency "govuk-lint", "~> 2.0.0"
+  spec.add_development_dependency "pry-byebug", "~> 3.4"
+  spec.add_development_dependency "yard", "~> 0.9.8"
+end

data/lib/govuk_taxonomy_helpers.rb

@@ -0,0 +1,3 @@
+require "govuk_taxonomy_helpers/version"
+require "govuk_taxonomy_helpers/publishing_api_response"
+require "govuk_taxonomy_helpers/linked_content_item"

data/lib/govuk_taxonomy_helpers/linked_content_item.rb

@@ -0,0 +1,111 @@
+module GovukTaxonomyHelpers
+  # A LinkedContentItem can be anything that has a content store representation
+  # on GOV.UK.
+  #
+  # It can be used with "taxon" content items (a topic in the taxonomy) or
+  # other document types that link to taxons.
+  #
+  # Taxon instances can have an optional parent and any number of child taxons.
+  class LinkedContentItem
+    extend Forwardable
+    attr_reader :title, :content_id, :base_path, :children, :internal_name
+    attr_accessor :parent
+    attr_reader :taxons
+    def_delegators :tree, :map, :each
+
+    # @param title [String] the user facing name for the content item
+    # @param base_path [String] the relative URL, starting with a leading "/"
+    # @param content_id [UUID] unique identifier of the content item
+    # @param internal_name [String] an internal name for the content item
+    def initialize(title:, base_path:, content_id:, internal_name: nil)
+      @title = title
+      @internal_name = internal_name
+      @content_id = content_id
+      @base_path = base_path
+      @children = []
+      @taxons = []
+    end
+
+    # Add a LinkedContentItem as a child of this one
+    def <<(child_node)
+      child_node.parent = self
+      @children << child_node
+    end
+
+    # Get taxons in the taxon's branch of the taxonomy.
+    #
+    # @return [Array] all taxons in this branch of the taxonomy, including the content item itself
+    def tree
+      return [self] if @children.empty?
+
+      @children.each_with_object([self]) do |child, tree|
+        tree.concat(child.tree)
+      end
+    end
+
+
+    # Get descendants of a taxon
+    #
+    # @return [Array] all taxons in this branch of the taxonomy, excluding the content item itself
+    def descendants
+      tree.tap(&:shift)
+    end
+
+    # Get ancestors of a taxon
+    #
+    # @return [Array] all taxons in the path from the root of the taxonomy to the parent taxon
+    def ancestors
+      if parent.nil?
+        []
+      else
+        parent.ancestors + [parent]
+      end
+    end
+
+    # Get a breadcrumb trail for a taxon
+    #
+    # @return [Array] all taxons in the path from the root of the taxonomy to this taxon
+    def breadcrumb_trail
+      ancestors + [self]
+    end
+
+    # Get all linked taxons and their ancestors
+    #
+    # @return [Array] all taxons that this content item can be found in
+    def taxons_with_ancestors
+      taxons.flat_map(&:breadcrumb_trail)
+    end
+
+    # @return [Integer] the number of taxons in this branch of the taxonomy
+    def count
+      tree.count
+    end
+
+    # @return [Boolean] whether this taxon is the root of its taxonomy
+    def root?
+      parent.nil?
+    end
+
+    # @return [Integer] the number of taxons between this taxon and the taxonomy root
+    def depth
+      return 0 if root?
+      1 + parent.depth
+    end
+
+    # Link this content item to a taxon
+    #
+    # @param taxon_node [LinkedContentItem] A taxon content item
+    def add_taxon(taxon_node)
+      taxons << taxon_node
+    end
+
+    # @return [String] the string representation of the content item
+    def inspect
+      if internal_name.nil?
+        "LinkedContentItem(title: '#{title}', content_id: '#{content_id}', base_path: '#{base_path}')"
+      else
+        "LinkedContentItem(title: '#{title}', internal_name: '#{internal_name}', content_id: '#{content_id}', base_path: '#{base_path}')"
+      end
+    end
+  end
+end

data/lib/govuk_taxonomy_helpers/publishing_api_response.rb

@@ -0,0 +1,101 @@
+require 'govuk_taxonomy_helpers/linked_content_item'
+
+module GovukTaxonomyHelpers
+  class LinkedContentItem
+    # Extract a LinkedContentItem from publishing api response data.
+    #
+    # @param content_item [Hash] Publishing API `get_content` response hash
+    # @param expanded_links [Hash] Publishing API `get_expanded_links` response hash
+    # @return [LinkedContentItem]
+    # @see http://www.rubydoc.info/gems/gds-api-adapters/GdsApi/PublishingApiV2#get_content-instance_method
+    # @see http://www.rubydoc.info/gems/gds-api-adapters/GdsApi%2FPublishingApiV2:get_expanded_links
+    def self.from_publishing_api(content_item:, expanded_links:)
+      PublishingApiResponse.new(
+        content_item: content_item,
+        expanded_links: expanded_links,
+      ).linked_content_item
+    end
+  end
+
+  class PublishingApiResponse
+    attr_accessor :linked_content_item
+
+    # @param content_item [Hash] Publishing API `get_content` response hash
+    # @param expanded_links [Hash] Publishing API `get_expanded_links` response hash
+    def initialize(content_item:, expanded_links:)
+      @linked_content_item = LinkedContentItem.new(
+        title: content_item["title"],
+        internal_name: content_item["details"]["internal_name"],
+        content_id: content_item["content_id"],
+        base_path: content_item["base_path"]
+      )
+
+      add_expanded_links(expanded_links)
+    end
+
+  private
+
+    def add_expanded_links(expanded_links_response)
+      child_taxons = expanded_links_response["expanded_links"]["child_taxons"]
+      parent_taxons = expanded_links_response["expanded_links"]["parent_taxons"]
+      taxons = expanded_links_response["expanded_links"]["taxons"]
+
+      if !child_taxons.nil?
+        child_taxons.each do |child|
+          linked_content_item << parse_nested_child(child)
+        end
+      end
+
+      if !parent_taxons.nil?
+        # Assume no taxon has multiple parents
+        single_parent = parent_taxons.first
+
+        parse_nested_parent(single_parent) << linked_content_item
+      end
+
+      if !taxons.nil?
+        taxons.each do |taxon|
+          taxon_node = parse_nested_parent(taxon)
+          linked_content_item.add_taxon(taxon_node)
+        end
+      end
+    end
+
+    def parse_nested_child(nested_item)
+      nested_linked_content_item = LinkedContentItem.new(
+        title: nested_item["title"],
+        internal_name: nested_item["details"]["internal_name"],
+        content_id: nested_item["content_id"],
+        base_path: nested_item["base_path"]
+      )
+
+      child_taxons = nested_item["links"]["child_taxons"]
+
+      if !child_taxons.nil?
+        child_taxons.each do |child|
+          nested_linked_content_item << parse_nested_child(child)
+        end
+      end
+
+      nested_linked_content_item
+    end
+
+    def parse_nested_parent(nested_item)
+      nested_linked_content_item = LinkedContentItem.new(
+        title: nested_item["title"],
+        internal_name: nested_item["details"]["internal_name"],
+        content_id: nested_item["content_id"],
+        base_path: nested_item["base_path"]
+      )
+
+      parent_taxons = nested_item["links"]["parent_taxons"]
+
+      if !parent_taxons.nil?
+        single_parent = parent_taxons.first
+        parse_nested_parent(single_parent) << nested_linked_content_item
+      end
+
+      nested_linked_content_item
+    end
+  end
+end

data/lib/govuk_taxonomy_helpers/version.rb

@@ -0,0 +1,3 @@
+module GovukTaxonomyHelpers
+  VERSION = "0.0.1".freeze
+end

data/spec/linked_content_item_spec.rb

@@ -0,0 +1,158 @@
+require_relative 'spec_helper'
+require 'govuk_taxonomy_helpers/linked_content_item'
+
+RSpec.describe GovukTaxonomyHelpers::LinkedContentItem do
+  let(:root_node) { GovukTaxonomyHelpers::LinkedContentItem.new(title: "root-id", content_id: "abc", base_path: "/root-id") }
+  let(:child_node_1) { GovukTaxonomyHelpers::LinkedContentItem.new(title: "child-1-id", content_id: "abc", base_path: "/child-1-id") }
+
+  describe "#<<(child_node)" do
+    it "makes one node the child of another node" do
+      root_node << child_node_1
+
+      expect(root_node.tree).to include child_node_1
+      expect(child_node_1.parent).to eq root_node
+    end
+  end
+
+  describe "#tree" do
+    context "given a node with a tree of successors" do
+      it "returns an array representing a pre-order traversal of the tree" do
+        child_node_2 = GovukTaxonomyHelpers::LinkedContentItem.new(title: "child-2-id", content_id: "abc", base_path: "/child-2-id")
+        child_node_3 = GovukTaxonomyHelpers::LinkedContentItem.new(title: "child-3-id", content_id: "abc", base_path: "/child-3-id")
+
+        root_node << child_node_1
+        child_node_1 << child_node_3
+        child_node_1 << child_node_2
+
+        expect(root_node.tree.count).to eq 4
+        expect(root_node.tree.first).to eq root_node
+        expect(root_node.tree.map(&:title)).to eq %w(root-id child-1-id child-3-id child-2-id)
+        expect(child_node_1.tree.map(&:title)).to eq %w(child-1-id child-3-id child-2-id)
+      end
+    end
+
+    context "given a single node" do
+      it "returns an array containing only that node" do
+        expect(root_node.tree.map(&:title)).to eq %w(root-id)
+      end
+    end
+  end
+
+  describe "#root?" do
+    before do
+      root_node << child_node_1
+    end
+
+    it "returns true when a node is the root" do
+      expect(root_node.root?).to be
+    end
+
+    it "returns false when a node is not the root" do
+      expect(child_node_1.root?).to_not be
+    end
+  end
+
+  describe "#depth" do
+    it "returns the depth of the node in its tree" do
+      child_node_2 = GovukTaxonomyHelpers::LinkedContentItem.new(title: "child-2-id", content_id: "abc", base_path: "/child-2-id")
+      root_node << child_node_1
+      child_node_1 << child_node_2
+
+      expect(root_node.depth).to eq 0
+      expect(child_node_1.depth).to eq 1
+      expect(child_node_2.depth).to eq 2
+    end
+  end
+
+  describe "#count" do
+    it "returns the total number of nodes in the tree" do
+      root_node << child_node_1
+
+      expect(root_node.count).to eq 2
+    end
+  end
+
+  context "taxon with ancestors" do
+    let(:child_node_2) do
+      GovukTaxonomyHelpers::LinkedContentItem.new(
+        title: "child-2-id",
+        content_id: "abc",
+        base_path: "/child-2-id"
+      )
+    end
+
+    before do
+      root_node << child_node_1
+      child_node_1 << child_node_2
+    end
+
+    describe "#breadcrumb_trail" do
+      it "includes the ancestors plus the content item itself" do
+        expect(child_node_2.breadcrumb_trail.map(&:title)).to eq %w(root-id child-1-id child-2-id)
+      end
+
+      it "is just contains itself for the root node" do
+        expect(root_node.breadcrumb_trail.map(&:title)).to eq %w(root-id)
+      end
+    end
+
+    describe "#ancestors" do
+      it "includes the ancestors but not the content item itself" do
+        expect(child_node_2.ancestors.map(&:title)).to eq %w(root-id child-1-id)
+      end
+
+      it "is the reverse of #descendants" do
+        have_descendant_node = lambda do |ancestor|
+          ancestor.descendants.include?(child_node_2)
+        end
+
+        expect(child_node_2.ancestors).to all(satisfy(&have_descendant_node))
+      end
+
+      it "is an empty array for the root node" do
+        expect(root_node.ancestors).to be_empty
+      end
+    end
+
+    describe "#taxons" do
+      let(:content_item) do
+        GovukTaxonomyHelpers::LinkedContentItem.new(
+          title: "content",
+          content_id: "abc",
+          base_path: "/content"
+        )
+      end
+
+      it "includes only the directly linked taxons" do
+        content_item.add_taxon(child_node_2)
+
+        expect(content_item.taxons.map(&:title)).to eq ["child-2-id"]
+      end
+    end
+
+    describe "#taxons_with_ancestors" do
+      let(:another_taxon) do
+        GovukTaxonomyHelpers::LinkedContentItem.new(
+          title: "another-taxon",
+          content_id: "abc",
+          base_path: "/another-taxon"
+        )
+      end
+
+      let(:content_item) do
+        GovukTaxonomyHelpers::LinkedContentItem.new(
+          title: "content",
+          content_id: "abc",
+          base_path: "/content"
+        )
+      end
+
+      it "includes all of the taxons and all of their anscestors" do
+        content_item.add_taxon(child_node_2)
+        content_item.add_taxon(another_taxon)
+
+        expect(content_item.taxons_with_ancestors.map(&:title).sort).to eq %w(another-taxon child-1-id child-2-id root-id)
+      end
+    end
+  end
+end

data/spec/publishing_api_response_spec.rb

@@ -0,0 +1,343 @@
+require_relative 'spec_helper'
+require 'govuk_taxonomy_helpers'
+
+RSpec.describe GovukTaxonomyHelpers::PublishingApiResponse do
+  let(:content_item) do
+    {
+      "content_id" => "64aadc14-9bca-40d9-abb4-4f21f9792a05",
+      "base_path" => "/taxon",
+      "title" => "Taxon",
+      "details" => {
+        "internal_name" => "My lovely taxon"
+      }
+    }
+  end
+
+  let(:linked_content_item) do
+    GovukTaxonomyHelpers::LinkedContentItem.from_publishing_api(
+      content_item: content_item,
+      expanded_links: expanded_links
+    )
+  end
+
+  context "content item with multiple levels of descendants" do
+    let(:expanded_links) do
+      grandchild_1 = {
+        "content_id" => "84aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/grandchild-1",
+        "title" => "Grandchild 1",
+        "details" => {
+          "internal_name" => "GC 1",
+        },
+        "links" => {}
+      }
+
+      grandchild_2 = {
+        "content_id" => "94aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/grandchild-2",
+        "title" => "Grandchild 2",
+        "details" => {
+          "internal_name" => "GC 2",
+        },
+        "links" => {}
+      }
+
+      child_1 = {
+        "content_id" => "74aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/child-1",
+        "title" => "Child 1",
+        "details" => {
+          "internal_name" => "C 1",
+        },
+        "links" => {
+          "child_taxons" => [
+            grandchild_1,
+            grandchild_2
+          ]
+        }
+      }
+
+      {
+        "content_id" => "64aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "expanded_links" => {
+          "child_taxons" => [child_1]
+        }
+      }
+    end
+
+    it "parses titles" do
+      expect(linked_content_item.title).to eq("Taxon")
+      expect(linked_content_item.children.map(&:title)).to eq(['Child 1'])
+      expect(linked_content_item.children.first.children.map(&:title)).to eq(["Grandchild 1", "Grandchild 2"])
+    end
+
+    it "parses internal names" do
+      expect(linked_content_item.internal_name).to eq("My lovely taxon")
+      expect(linked_content_item.children.map(&:internal_name)).to eq(['C 1'])
+      expect(linked_content_item.children.first.children.map(&:internal_name)).to eq(["GC 1", "GC 2"])
+    end
+  end
+
+  context "content item with no descendants" do
+    let(:expanded_links) do
+      {
+        "content_id" => "64aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "expanded_links" => {}
+      }
+    end
+
+    it "parses each level of taxons" do
+      expect(linked_content_item.title).to eq("Taxon")
+      expect(linked_content_item.children).to be_empty
+    end
+  end
+
+  context "content item with children but no grandchildren" do
+    let(:expanded_links) do
+      child_1 = {
+        "content_id" => "74aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/child-1",
+        "title" => "Child 1",
+        "details" => {
+          "internal_name" => "C 1",
+        },
+        "links" => {}
+      }
+
+      child_2 = {
+        "content_id" => "84aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/child-2",
+        "title" => "Child 2",
+        "details" => {
+          "internal_name" => "C 2",
+        },
+        "links" => {}
+      }
+
+      {
+        "content_id" => "64aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "expanded_links" => {
+          "child_taxons" => [child_1, child_2]
+        }
+      }
+    end
+
+    it "parses each level of taxons" do
+      expect(linked_content_item.title).to eq("Taxon")
+      expect(linked_content_item.children.map(&:title)).to eq(["Child 1", "Child 2"])
+      expect(linked_content_item.children.map(&:children)).to all(be_empty)
+    end
+  end
+
+  context "content item with parents and grandparents" do
+    let(:expanded_links) do
+      grandparent_1 = {
+        "content_id" => "84aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/grandparent-1",
+        "title" => "Grandparent 1",
+        "details" => {
+          "internal_name" => "GP 1",
+        },
+        "links" => {}
+      }
+
+      parent_1 = {
+        "content_id" => "74aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/parent-1",
+        "title" => "Parent 1",
+        "details" => {
+          "internal_name" => "P 1",
+        },
+        "links" => {
+          "parent_taxons" => [
+            grandparent_1
+          ]
+        }
+      }
+
+      {
+        "content_id" => "64aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "expanded_links" => {
+          "parent_taxons" => [parent_1]
+        }
+      }
+    end
+
+    it "parses the ancestors" do
+      expect(linked_content_item.title).to eq("Taxon")
+      expect(linked_content_item.parent.title).to eq("Parent 1")
+      expect(linked_content_item.ancestors.map(&:title)).to eq(["Grandparent 1", "Parent 1"])
+    end
+  end
+
+
+  context "content item with parents and no grandparents" do
+    let(:expanded_links) do
+      parent_1 = {
+        "content_id" => "74aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/parent-1",
+        "title" => "Parent 1",
+        "details" => {
+          "internal_name" => "P 1",
+        },
+        "links" => {}
+      }
+
+      {
+        "content_id" => "64aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "expanded_links" => {
+          "parent_taxons" => [parent_1]
+        }
+      }
+    end
+
+    it "parses the ancestors" do
+      expect(linked_content_item.title).to eq("Taxon")
+      expect(linked_content_item.parent.title).to eq("Parent 1")
+      expect(linked_content_item.ancestors.map(&:title)).to eq(["Parent 1"])
+    end
+  end
+
+  context "content item with no parents" do
+    let(:expanded_links) do
+      {
+        "content_id" => "64aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "expanded_links" => {}
+      }
+    end
+
+    it "parses the ancestors" do
+      expect(linked_content_item.title).to eq("Taxon")
+      expect(linked_content_item.parent).to be_nil
+      expect(linked_content_item.ancestors.map(&:title)).to be_empty
+    end
+  end
+
+  context "content item with multiple parents" do
+    let(:expanded_links) do
+      parent_1 = {
+        "content_id" => "74aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/parent-1",
+        "title" => "Parent 1",
+        "details" => {
+          "internal_name" => "P 1",
+        },
+        "links" => {}
+      }
+
+      parent_2 = {
+        "content_id" => "84aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/parent-2",
+        "title" => "Parent 2",
+        "details" => {
+          "internal_name" => "P 2",
+        },
+        "links" => {}
+      }
+
+      {
+        "content_id" => "64aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "expanded_links" => {
+          "parent_taxons" => [parent_1, parent_2]
+        }
+      }
+    end
+
+    it "uses only the first parent" do
+      expect(linked_content_item.title).to eq("Taxon")
+      expect(linked_content_item.parent.title).to eq("Parent 1")
+      expect(linked_content_item.ancestors.map(&:title)).to eq(["Parent 1"])
+    end
+  end
+
+  context "a content item tagged to multiple taxons" do
+    let(:expanded_links) do
+      grandparent_1 = {
+        "content_id" => "22aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/grandparent-1",
+        "title" => "Grandparent 1",
+        "details" => {
+          "internal_name" => "GP 1",
+        },
+        "links" => {}
+      }
+
+      parent_1 = {
+        "content_id" => "11aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/parent-1",
+        "title" => "Parent 1",
+        "details" => {
+          "internal_name" => "P 1",
+        },
+        "links" => {
+          "parent_taxons" => [grandparent_1]
+        }
+      }
+
+      taxon_1 = {
+        "content_id" => "00aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/this-is-a-taxon",
+        "title" => "Taxon 1",
+        "details" => {
+          "internal_name" => "T 1",
+        },
+        "links" => {
+          "parent_taxons" => [parent_1]
+        }
+      }
+
+      grandparent_2 = {
+        "content_id" => "03aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/grandparent-2",
+        "title" => "Grandparent 2",
+        "details" => {
+          "internal_name" => "GP 2",
+        },
+        "links" => {}
+      }
+
+      parent_2 = {
+        "content_id" => "02aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/parent-2",
+        "title" => "Parent 2",
+        "details" => {
+          "internal_name" => "P 2",
+        },
+        "links" => {
+          "parent_taxons" => [grandparent_2]
+        }
+      }
+
+      taxon_2 = {
+        "content_id" => "01aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "base_path" => "/this-is-also-a-taxon",
+        "title" => "Taxon 2",
+        "details" => {
+          "internal_name" => "T 2",
+        },
+        "links" => {
+          "parent_taxons" => [parent_2]
+        }
+      }
+
+      {
+        "content_id" => "64aadc14-9bca-40d9-abb4-4f21f9792a05",
+        "expanded_links" => {
+          "taxons" => [taxon_1, taxon_2]
+        }
+      }
+    end
+
+    it "parses the taxons and their ancestors" do
+      expect(linked_content_item.parent).to be_nil
+      expect(linked_content_item.taxons.map(&:title)).to eq(["Taxon 1", "Taxon 2"])
+      expect(linked_content_item.taxons_with_ancestors.map(&:title).sort).to eq(
+        [
+          "Grandparent 1", "Grandparent 2",
+          "Parent 1", "Parent 2",
+          "Taxon 1", "Taxon 2",
+        ]
+      )
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,99 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause
+# this file to always be loaded, without a need to explicitly require it in any
+# files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need
+# it.
+#
+# The `.rspec` file also contains a few flags that are not defaults but that
+# users commonly want.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+
+require 'pry-byebug'
+
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+# The settings below are suggested to provide a good initial experience
+# with RSpec, but feel free to customize to your heart's content.
+=begin
+  # These two settings work together to allow you to limit a spec run
+  # to individual examples or groups you care about by tagging them with
+  # `:focus` metadata. When nothing is tagged with `:focus`, all examples
+  # get run.
+  config.filter_run :focus
+  config.run_all_when_everything_filtered = true
+
+  # Allows RSpec to persist some state between runs in order to support
+  # the `--only-failures` and `--next-failure` CLI options. We recommend
+  # you configure your source control system to ignore this file.
+  config.example_status_persistence_file_path = "spec/examples.txt"
+
+  # Limits the available syntax to the non-monkey patched syntax that is
+  # recommended. For more details, see:
+  #   - http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax
+  #   - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   - http://myronmars.to/n/dev-blog/2014/05/notable-changes-in-rspec-3#new__config_option_to_disable_rspeccore_monkey_patching
+  config.disable_monkey_patching!
+
+  # This setting enables warnings. It's recommended, but in some cases may
+  # be too noisy due to issues in dependencies.
+  config.warnings = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = 'doc'
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+=end
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: govuk_taxonomy_helpers
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Government Digital Service
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-03-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: govuk-lint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.8
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.8
+description: 
+email:
+- govuk-dev@digital.cabinet-office.gov.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- ".yardopts"
+- CHANGELOG.md
+- Gemfile
+- Jenkinsfile
+- LICENCE.txt
+- README.md
+- Rakefile
+- govuk_taxonomy_helpers.gemspec
+- lib/govuk_taxonomy_helpers.rb
+- lib/govuk_taxonomy_helpers/linked_content_item.rb
+- lib/govuk_taxonomy_helpers/publishing_api_response.rb
+- lib/govuk_taxonomy_helpers/version.rb
+- spec/linked_content_item_spec.rb
+- spec/publishing_api_response_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/alphagov/govuk_taxonomy_helpers
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+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.6.8
+signing_key: 
+specification_version: 4
+summary: Parses the taxonomy of GOV.UK into a browseable tree structure.
+test_files:
+- spec/linked_content_item_spec.rb
+- spec/publishing_api_response_spec.rb
+- spec/spec_helper.rb