carbon-core 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: df956cb1d06f05220b2f44f38aac8279b6238d3a
+  data.tar.gz: fd88b72d02ccd3d2706e750c43c061a4572196c9
+SHA512:
+  metadata.gz: 71426b13ade11afea88c848cb15b4cbabea156b5162c516f1f53d96a57d02b8a4dd56754d522d53f7826891c3f229084e735287895ce89c61b0336945962c82b
+  data.tar.gz: be6a57e2bbf58f024b808cb4f530e55d99221e8c8fd9a614bce8d6069edba375ff8368f28203c3095c3a7113ddd7f63d3bdf322cf904ff443fa80c001c568e23

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/core.rb
+/prof/
+/scripts/
+*.clib

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,38 @@
+AllCops:
+  TargetRubyVersion: 2.3
+
+
+Style/AlignParameters:
+  EnforcedStyle: with_fixed_indentation
+Style/SignalException:
+  EnforcedStyle: only_fail
+Style/AccessModifierIndentation:
+  EnforcedStyle: outdent
+Style/ConditionalAssignment:
+  Enabled: false
+Style/Encoding:
+  Enabled: true
+  EnforcedStyle: always
+  AutoCorrectEncodingComment: "# encoding: utf-8\n"
+Style/MultilineBlockChain:
+  Enabled: false
+Style/MultilineMethodCallIndentation:
+  Enabled: false
+Style/ParallelAssignment:
+  Enabled: false
+Style/RedundantFreeze:
+  Enabled: false
+Style/RegexpLiteral:
+  EnforcedStyle: mixed
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+Style/AndOr:
+  EnforcedStyle: conditionals
+Style/AlignHash:
+  EnforcedLastArgumentHashStyle: ignore_implicit
+Style/AlignArray:
+  Enabled: false
+Style/IndentArray:
+  Enabled: false
+Style/Alias:
+  EnforcedStyle: prefer_alias_method

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.3.0
+before_install: gem install bundler -v 1.11.2

data/.yardopts

@@ -0,0 +1 @@
+-mmarkdown

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at redjazz96@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,11 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in carbon.gemspec
+gemspec
+gem "yardstick"
+gem "concurrent-ruby"
+gem "simplecov", require: false
+gem "simplecov-json", require: false

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Jeremy Rodi
+
+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,41 @@
+# Carbon
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/carbon`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'carbon'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install carbon
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/carbon. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,14 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "yard"
+
+RSpec::Core::RakeTask.new(:spec)
+YARD::Rake::YardocTask.new(:"doc:build") do |t|
+  t.options = ["-mmarkdown"]
+end
+
+task default: :spec
+task doc: [:"doc:build"]

data/carbon.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+# frozen_string_literal: true
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "carbon/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "carbon-core"
+  spec.version       = Carbon::VERSION
+  spec.authors       = ["Jeremy Rodi"]
+  spec.email         = ["redjazz96@gmail.com"]
+
+  spec.summary       = "The Core logic of the Carbon language."
+  spec.homepage      = "https://github.com/carbon-lang/core"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`
+                       .split("\x0")
+                       .reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_dependency "base58", "~> 0.1"
+  spec.add_dependency "msgpack", "~> 1.0"
+  spec.add_dependency "ice_nine", "~> 0.11"
+end

data/lib/carbon.rb

@@ -0,0 +1,54 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "ice_nine"
+require "ice_nine/core_ext/object"
+require "base58"
+require "digest/sha2"
+require "concurrent"
+require "llvm"
+require "llvm/core"
+require "carbon/version"
+require "carbon/tacky"
+require "carbon/concrete"
+
+# Carbon.  The language.
+module Carbon
+  # rubocop:disable Style/MethodName
+
+  # Creates a type.  This uses {Carbon::Concrete::Type}, and assumes that the
+  # parameter must be a string to be parsed.
+  #
+  # @api public
+  # @example
+  #   type = Carbon::Type("Carbon::Boolean")
+  #   type # => #<Carbon::Concrete::Type Carbon::Boolean>
+  # @param string [::String] The string to parse.
+  # @return [Carbon::Concrete::Type] The resulting type.
+  def self.Type(string)
+    Carbon::Concrete::Type.from(string)
+  end
+  # rubocop:enable Style/MethodName
+
+  # Hashes a given string into the format used by Carbon.  The format is a
+  # Base58-encoded SHA256 digest.
+  #
+  # @api semipublic
+  # @example
+  #   Carbon.hash("") # => "gjNT5GbSC-81KmUPncw-hzQAGV3GU-eAXafmkMP-Bw2GMHWM"
+  # @param string [::String] The string to hash.
+  # @return [::String] The hashed string.
+  def self.hash(string)
+    digest = Digest::SHA2.hexdigest(string).hex
+    encoded = Base58.encode(digest)
+    encoded.scan(/.{1,9}/).join("-").freeze
+  end
+
+  # A Boolean type for Carbon.  This is used as a handy shortcut.
+  #
+  # @api private
+  # @return [Carbon::Concrete::Type]
+  Boolean = Carbon::Type("Carbon::Boolean")
+
+  require "carbon/core"
+end

data/lib/carbon/concrete.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "oj"
+require "zlib"
+require "carbon/concrete/build"
+require "carbon/concrete/item"
+require "carbon/concrete/index"
+require "carbon/concrete/request"
+require "carbon/concrete/type"
+
+module Carbon
+  # A concrete representation of the global state of a compilation.  All of
+  # the things within this module should be serializable, so that libraries
+  # may be linked easily back into the process.
+  module Concrete
+    # Loads a dumped object into an instance.  The dumped object should be a
+    # Zlib compressed (with Deflate) string.  The dumped object
+    # is decompressed and loaded, then passed to {.from}.
+    #
+    # @api private
+    # @see .dump
+    # @param source [::String] The dumped object.
+    # @return [::Object] The represented object.
+    def self.load(source)
+      raw = Zlib::Inflate.inflate(source)
+      Oj.load(raw)
+    end
+
+    # Dumps an object to a string.  If the object responds to `#to_basic`, the
+    # result of that method call is used instead.  The object is then
+    # serialized, and then compressed using Zlib (Deflate).
+    #
+    # @api private
+    # @see .load
+    # @param index [::Object] The object to dump.
+    # @return [::String] The dumped object.
+    def self.dump(index)
+      raw = Oj.dump(index, circular: true, class_cache: true)
+      Zlib::Deflate.deflate(raw, 9)
+    end
+  end
+end

data/lib/carbon/concrete/build.rb

@@ -0,0 +1,63 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module Carbon
+  module Concrete
+    # Handles building requests.  This is the step after all requests are
+    # determined from the dependency build stage.  The entire purpose of this
+    # class is to consolidate state information for LLVM module building.
+    #
+    # @api semiprivate
+    class Build
+      # The types that have been defined.  This is a mapping of the
+      # {Concrete::Type} to an arry of the {Concrete::Item} and the
+      # corresponding `LLVM::Type`.  This is so that no information is lost
+      # when converting the item to the type.
+      #
+      # @return [{Concrete::Type => (Concrete::Item, ::LLVM::Type)}]
+      attr_reader :types
+
+      # The functions that have been defined.  This is a mapping of the
+      # {Concrete::Type} to the `LLVM::Function` that was defined.
+      #
+      # @return [{Concrete::Type => ::LLVM::Function}]
+      attr_reader :functions
+
+      # The LLVM module that is being used for compilation.
+      #
+      # @return [::LLVM::Module]
+      attr_reader :module
+
+      # Initialize the build process.  This only initializes instance
+      # variables.
+      #
+      # @param requests [::Enumerable<Concrete::Request>] An enumerable over
+      #   each request that needs to be built.  The requests should be
+      #   resolved, i.e. the generics for the request should resolve to a
+      #   valid type.
+      # @param index [Concrete::Index] The index that is being built from.
+      def initialize(requests, index)
+        @requests = requests
+        @index = index
+      end
+
+      # Performs the build process.  Builds each request in order by calling
+      # {Concrete::Item::Base#call} on each.
+      #
+      # @return [::LLVM::Module] The built module.
+      def call
+        @types = {}
+        @functions = {}
+        @module = ::LLVM::Module.new("__carbon_main")
+
+        @requests.each do |request|
+          item = @index.fetch(request.intern)
+          generics = item.generics.zip(request.generics).to_h
+          item.call(self, generics)
+        end
+
+        @module
+      end
+    end
+  end
+end

data/lib/carbon/concrete/index.rb

@@ -0,0 +1,324 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require "tsort"
+require "forwardable"
+
+module Carbon
+  module Concrete
+    # A list of all of the "items" in the global context of Carbon.  Items are
+    # mostly functions and data definitions.  This keeps track of them and
+    # their dependencies, so that they can be built later.  Indexes are also
+    # designed to be easily serialized if needed (which is likely the case,
+    # for libraries).
+    class Index
+      include TSort
+      extend Forwardable
+
+      # We can't use these methods because we don't fit the bill - we don't
+      # define a `tsort_each_node`, since we don't need it.  We only use
+      # `each_strongly_connected_component_from`, which only requires
+      # `tsort_each_child`.  We could use the module function
+      # `TSort.each_strongly_connected_component_from`, but that only appears
+      # in Ruby versions 2.1.0 and higher.  It's not guarenteed to be there.
+      # However, everything else in TSort is expected to be there, even since
+      # Ruby 1.8.7, and do exactly as expected.
+      undef_method :tsort
+      undef_method :each_strongly_connected_component
+      undef_method :strongly_connected_components
+
+      # Initialize the index with the given data.
+      #
+      # @api public
+      # @param data [{::Symbol => ::Object}] The data to initialize with.
+      # @option data [::Hash] :items ({}) The definitions.
+      # @option data [::String] :id (#id) The ID of the index.  This is
+      #   completely derived from the index itself; or, rather, what's defined
+      #   on the index.  See {#id}.
+      def initialize(data = {})
+        @items = Concurrent::Hash.new.merge(data.fetch(:items, {}))
+        @mutex = Mutex.new
+        @id = data.fetch(:id) { id }
+      end
+
+      # @overload fetch(name, default = CANARY)
+      #   Retrieves the item with the given symbol name.  If no item with the
+      #   given name exists, it tries the following: first, if a block is
+      #   given, the item name is yielded to the block, and the result is
+      #   returned.  Second, if the second argument is passed (i.e. isn't
+      #   `CANARY`), then that is returned instead.  Third, if neither is
+      #   true, then the method raises `KeyError`.
+      #
+      #   @api public
+      #   @example Successful fetch.
+      #     index.fetch("Carbon::Integer") # => #<Carbon::Concrete::Item::Base>
+      #   @example Failed fetch with argument.
+      #     index.fetch("Carbon::Foo", false) # => false
+      #   @example Failed fetch with block.
+      #     index.fetch("Carbon::Foo") { |n| n.sub("F", "B") }
+      #       # => "Carbon::Boo"
+      #   @example Failed fetch with both.
+      #     index.fetch("Carbon::Foo", false) { |n| n.sub("F", "B") }
+      #       # => "Carbon::Boo"
+      #   @param name [::Object] The key of the item to fetch.
+      #   @param default [::Object] The value to return if the key doesn't match
+      #     an item and a block wasn't given.
+      #   @yield [name] If the key doesn't match an item, the method yields.
+      #   @yieldparam name [::Object] The name of the item.
+      #   @return [::Object] The item, if the key matched; otherwise, the result
+      #     of the block, if given; otherwise, the value of the `default`
+      #     parameter.
+      #   @raise [KeyError] If the key doesn't match an item and neither a
+      #     block nor the second argument were passed.
+      def fetch(*options, &block)
+        @mutex.synchronize { @items.fetch(*options, &block) }
+      end
+
+      # @overload [](key)
+      #   Retrieves the item with the given symbol name.  If no item exists,
+      #   it returns `nil`.
+      #
+      #   @api public
+      #   @example Successful retrieval.
+      #     index["Carbon::Integer"] # => #<Carbon::Concrete::Item::Base>
+      #   @example Unsuccessful retrieval.
+      #     index["Carbon::Foo"] # => nil
+      #   @param key [::Object] The key of the item to lookup.
+      #   @return [::Object] The item, if it exists;
+      #   @return [nil] Otherwise.
+      def [](*options)
+        @mutex.synchronize { @items[*options] }
+      end
+
+      # @overload key?(key)
+      #   Determines whether or not the key exists, and an item is paired
+      #   with it.
+      #
+      #   @api public
+      #   @example Existing key.
+      #     index.key?("Carbon::Integer") # => true
+      #   @example Non-existant key.
+      #     index.key?("Carbon::Foo") # => false
+      #   @param key [::Object] The key of the item to check.
+      #   @return [::Boolean] Whether the key exists or not.
+      def key?(*options)
+        @mutex.synchronize { @items.key?(*options) }
+      end
+
+      # Returns all of the keys in the index.  The keys and the array itself
+      # are both frozen.
+      #
+      # @api public
+      # @example
+      #   index.keys # => ["Carbon::Boolean", "Carbon::Integer"]
+      # @return [<::String>] The keys in the index.
+      def keys
+        @mutex.synchronize { @items.keys.deep_freeze! }
+      end
+
+      # Returns all of the values (actual items) in the index.  The items, and
+      # the array containing them, are frozen.
+      #
+      # @api public
+      # @example
+      #   index.values.map(&:class) # => [Carbon::Concrete::Item::Internal, ...]
+      # @return [<Item::Base>] The values in the index.
+      def values
+        @mutex.synchornize { @items.values.freeze }
+      end
+
+      # The digest of the ID.  This uses the SHA256 base58 digest of the items
+      # defined on the current index.  This includes both defined and merged
+      # items.
+      #
+      # @api public
+      # @example
+      #   index.items # => {}
+      #   index.id # => "gjNT5GbSC-81KmUPncw-hzQAGV3GU-eAXafmkMP-Bw2GMHWM"
+      # @return [::String]
+      def id
+        @id ||= Carbon.hash(items.keys.join("\n"))
+      end
+
+      # The items of the index.  This is a frozen duplicate of the items.
+      # Therefore, this is not guarenteed to be up to date.
+      #
+      # @api public
+      # @example Items
+      #   index.items
+      #     # => {"Carbon::Integer" => #<Carbon::Concrete::Item::Base>}
+      # @return [{::String => Item::Base}] The items of the index.
+      def items
+        @mutex.synchronize { @items.dup.deep_freeze! }
+      end
+
+      # Adds a defined item to the index.  The item just has to respond to
+      # the item API (see {Concrete::Item}).  This clears the index's cache,
+      # such that the ID ({#id}) and item list ({#items}) are reset and have
+      # to be recalculated.
+      #
+      # @api public
+      # @example Adding an item.
+      #   index << item
+      #   index.key?(item.intern) # => true
+      # @example Merging an index.
+      #   other.is_a?(Carbon::Concrete::Index) # => true
+      #   index << other
+      #   index.items.keys.to_set <= other.items.keys.to_set
+      # @note
+      #   If the item is an index instead, it passes it to {#merge} and
+      #   returns.  This usage is not recommended for {#add}, but can be
+      #   used for {#<<}.
+      # @param item [Concrete::Item::Base] The item to add.
+      # @return [self]
+      def add(item)
+        return merge(item) if item.is_a?(Index)
+        @mutex.synchronize do
+          @items[item.intern] = item
+          clear!
+        end
+      end
+
+      alias_method :<<, :add
+
+      # Merges items from another index into the merged items of this index.
+      # This clears the index's cache, such that the ID ({#id}) have to be
+      # recalculated.
+      #
+      # @api public
+      # @example Merging.
+      #   index.merge(other)
+      #   index.items.keys.to_set <= other.items.keys.to_set
+      # @param index [Index] The index to merge.
+      # @return [self]
+      def merge(index)
+        @mutex.synchronize do
+          @items.merge(index.items)
+          clear!
+        end
+      end
+
+      # Used only for {#define}.  This maps item "names" to the classes that
+      # represent them.
+      #
+      # @api private
+      # @return [{::Symbol => Item::Base}]
+      ITEMS = {
+        internal: Concrete::Item::Internal,
+        function: Concrete::Item::Function,
+        struct: Concrete::Item::Struct,
+        trait: Concrete::Item::Trait
+      }.freeze
+
+      # Defines a type.  This is mostly a shorthand method.  The purpose of
+      # this is to make it easy to define items on the index.  The only
+      # parameter, data, is a hash.  The key is the name of the type of the
+      # item; this corresponds to the keys in the {ITEMS} hash.  The value is
+      # the {Concrete::Type} that is being defined. The method then yields a
+      # hash that is later used to define the item.
+      #
+      # @api semipublic
+      # @example
+      #   index.class # => Carbon::Concrete::Index
+      #   index.define(internal: Carbon::Boolean) do |bool|
+      #     bool[:size] = 1
+      #     bool[:kind] = :integer
+      #     bool[:implements] << Carbon::Type("Carbon::Numeric")
+      #     bool[:implements] << Carbon::Type("Carbon::Boolean")
+      #   end
+      #   internal = index[Carbon::Boolean]
+      #   internal.name # => "Carbon::Boolean"
+      # @param data [{::Symbol => Concrete::Type}] The name and
+      #   item type information.  There should only be one key
+      #   pair; any more will cause an error.
+      # @yield [data] To construct the data.  At the end of the block, the data
+      #   should contain all the information needed to create the item.
+      # @yieldparam data [{::Symbol => ::Object}] The data to be passed to the
+      #   item's intializer.
+      # @raise [ArgumentError] if more than one key-value pair is provided for
+      #   the `data` argument.
+      # @return [void]
+      def define(data)
+        fail ArgumentError, "Expected only one pair" if data.size > 1
+        data.each do |itype, name|
+          item = ITEMS.fetch(itype)
+          opts = item.from(Carbon::Type(name))
+          yield opts
+          self << item.new(opts)
+        end
+      end
+
+      # Yields the builds that need to be built for the given item.  This uses
+      # the TSort module in order to determine all of the dependencies the
+      # given item has, and yields each; and finally, yields the last item.
+      # The item may not have any generics, even if they are fully formed
+      # generics (e.g. have a definition).  If any items have a cyclic
+      # depdendency, it fails.
+      #
+      # @api semipublic
+      # @example Build request.
+      #   request.intern # => "Main"
+      #   request.generics # => []
+      #   index.build(request).to_a # => [...]
+      # @param item [Item::Base] The item to build.  The {Item::Base} module
+      #   contains behavior that is required by this method (namely,
+      #   {Item::Base#corrected_dependencies}, {Item::Base#intern}, and
+      #   {Item::Base#generics}).
+      # @return [::Enumerable] The build items, if no block is given.
+      # @return [void] If a block is given.
+      # @yield [dep] Multiple times, each with a dependency.
+      # @yieldparam dep [Request] A request.
+      def build(item)
+        @mutex.lock
+        fail ArgumentError, "Passed item cannot be generic" if \
+          item.generics.any?
+        return to_enum(:build, item) unless block_given?
+        request = Request.new(item.intern, [])
+
+        build_from_request(request, &Proc.new)
+      ensure
+        @mutex.unlock
+      end
+
+    private
+
+      # rubocop:disable Metrics/MethodLength
+      def build_from_request(request)
+        components = to_enum(:each_strongly_connected_component_from, request)
+        components.each do |group|
+          fail TSort::Cyclic, "cyclic dependencies: #{group.join(', ')}" if \
+            group.size > 1
+          begin
+            @mutex.unlock
+            yield group.first
+          ensure
+            @mutex.lock
+          end
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Iterates over all of the "children" of a node.  This iterates over all
+      # of the corrected dependencies of a node, allowing the TSort module
+      # to build a dependency map.
+      #
+      # @api private
+      # @param node [#intern] The item.
+      # @yield [request] Yields each corrected dependency of the item.
+      # @yieldparam request [Request]
+      # @return [void]
+      def tsort_each_child(node, &block)
+        @items.fetch(node.intern).corrected_dependencies(node, &block)
+      end
+
+      # Clears the cache, forcing the id to be rebuilt on next call.
+      #
+      # @api private
+      # @return [self]
+      def clear!
+        @id = nil
+        self
+      end
+    end
+  end
+end