society 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 28dbabe0d73d5d1b9534c4a920d2ff2f8d034e5f
-  data.tar.gz: fca64907dbe65f20fb37a9b3f35c35df5882cdf2
+  metadata.gz: ec8cb5a95664084f02de65ed939e89ec04417295
+  data.tar.gz: 462b53c5009c262f69fab7ddb6c3ba60ce38f227
 SHA512:
-  metadata.gz: 1cc19bd10ff36860d3fba973a339f633bb6719b6993ff9ba6af5fc88f583f4f12618bc796b68d1f79a71d7d3e1a1e3a6d09106c752127942cab5d9f27e0ed2ea
-  data.tar.gz: 4796528f618344ebba13aca58243be429e0d32d0a72174e259b781eec4af56e48ee0f971d9a5ee75f96d550a969a34549613a77cfacb774048755e9d8c943ebc
+  metadata.gz: a84b67d0617f3074d37efe668bec9cb4184615dfa08954134adcfe32f433f546b3cdbe66c857b7a7bfc146a07fb30174f1bfba9216a94172f1e37b0455746c4a
+  data.tar.gz: 8d7d5eb2196abd41d6eeff66453131b1636cb906d34d2dc24469cae44eaadf0a2c5a4b03c7349eab64a5bb7e9292f3552b8f79ab2a61cdaf6bff548745e433c3

data/CODE_OF_CONDUCT.md

@@ -1,13 +1,13 @@
-# CODE OF CONDUCT
-
-This project has adopted version 0.4 of the [Contributor Covenant](https://github.com/bantik/contributor_covenant/).
+# Contributor Code of Conduct
 
 As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
 
-If any participant in this project has issues or takes exception with a contribution, they are obligated to provide constructive feedback and never resort to personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+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, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other 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. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
 
-We promise to extend courtesy and respect to everyone involved in this project regardless of gender, gender identity, sexual orientation, ability or disability, ethnicity, religion, or level of experience.
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -1,6 +1,6 @@
 source 'https://rubygems.org'
 
-ruby '>= 2.1.1'
+raise 'Ruby version must be greater than 2.0' unless RUBY_VERSION.to_f > 2.0
 
 # Specify your gem's dependencies in society.gemspec
 gemspec

data/LICENSE.txt

@@ -1,15 +1,22 @@
-Copyright (c) 2014 Coraline Ada Ehmke  / Instructure.inc
+Copyright (c) 2014 Coraline Ada Ehmke
 
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
+MIT License
 
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
+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:
 
-You should have received a copy of the GNU General Public License
-along with this program in the file COPYING.txt.  If not, see
-<http://www.gnu.org/licenses/>
+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/lib/society.rb

@@ -1,15 +1,14 @@
-require "analyst"
+require "haml"
+require "json"
+require "ripper"
 require "fileutils"
 require "active_support/core_ext/string/inflections"
 
-require_relative "society/association_processor"
-require_relative "society/reference_processor"
 require_relative "society/edge"
-require_relative "society/clusterer"
-require_relative "society/formatter/graph/json"
+require_relative "society/node"
+require_relative "society/object_graph"
 require_relative "society/formatter/report/html"
 require_relative "society/formatter/report/json"
-require_relative "society/object_graph"
 require_relative "society/parser"
 require_relative "society/version"
 

data/lib/society/edge.rb

@@ -1,14 +1,40 @@
 module Society
+
+  # The Edge class represents an edge between two nodes in a graph.  An edge is
+  # assumed to represent a direct relationship between two Classes or Modules.
   class Edge
 
-    attr_reader :from, :to
-    attr_accessor :meta
+    attr_reader :to, :weight
+
+    # Public: Create a new Edge.
+    #
+    # to     - Node to target.
+    # weight - Weight of the edge, representing the number of references to the
+    #          node referenced.  (Default: 1)
+    def initialize(to:, weight: 1)
+      @to     = to
+      @weight = weight
+    end
+
+    # Public: Add two Edges' weights, returning a new Edge.
+    #
+    # edge - An Edge.
+    #
+    # Returns a new Edge if both edges target the same node.
+    # Returns nil otherwise.
+    def +(edge)
+      return nil unless edge.to == to
+
+      Edge.new(to: to, weight: weight + edge.weight)
+    end
 
-    def initialize(from:, to:, meta:nil)
-      @from = from
-      @to = to
-      @meta = meta
+    # Public: Return the name of the node to which the edge points.
+    #
+    # Returns a string.
+    def to_s
+      to.to_s
     end
+    alias_method :inspect, :to_s
 
   end
 

data/lib/society/formatter/report/html.rb

@@ -15,6 +15,7 @@ module Society
           write_html
           copy_assets
           write_json_data
+          puts "Results written to #{self.output_path}." unless self.output_path.nil?
         end
 
         private

data/lib/society/formatter/report/templates/components/society-assets/society.js

@@ -24,14 +24,14 @@
   };
 
   NetworkGraph.prototype.transformData = function(data) {
-    var nodes = data.nodes.map(function(node) {
-      return { name: node.name, relations: [] };
-    });
-    data.edges.forEach(function(edge) {
-      var targetName = nodes[edge.to].name;
-      nodes[edge.from].relations.push(targetName);
-    });
-    return nodes;
+    return(Object.keys(data).map(function(node) {
+      return {
+        name: node,
+        relations: Object.keys(data[node]).filter(function(edge) {
+          return(Object.keys(data).indexOf(edge) != -1);
+        })
+      };
+    }));
   };
 
   NetworkGraph.prototype.init = function() {
@@ -249,12 +249,15 @@
     var findCluster = data.clusters ? _findCluster : function() { return 0; };
 
     return {
-      nodes: data.nodes.map(function(node, index) {
-        return { name: node.name, group: findCluster(index) };
+      nodes: Object.keys(data).map(function(node, index) {
+        return { name: node, group: findCluster(index) };
       }),
-      links: data.edges.map(function(edge) {
-        return { source: edge.from, target: edge.to, value: 1 };
-      })
+      links: Object.keys(data).reduce(function(edges, node, source) {
+        var new_edges = Object.keys(data[node]).map(function(edge, target) {
+          return { source: source, target: target, value: data[node][edge] };
+        });
+        return(edges.concat(new_edges));
+      }, [])
     };
   };
 

data/lib/society/node.rb

@@ -0,0 +1,86 @@
+module Society
+
+  # The Node class represents a single node in a graph.  In this case, nodes
+  # are assumed to be either Classes or Modules.
+  class Node
+
+    attr_reader :name, :type, :edges, :unresolved, :meta
+
+    # Public: Creates a new node.
+    #
+    # name       - Name to be assigned to the node.  Assumed to be a Class or
+    #              Module name.
+    # type       - Type of node.  Assumed to be :class or :module.
+    # edges      - Edges which point to other nodes.
+    # unresolved - References to nodes which have not yet been resolved.
+    #              (default: [])
+    # meta       - Information to be tracked about the node itself.
+    #              (default: [])
+    def initialize(name:, type:, edges: [], unresolved: [], meta: [])
+      @name       = name
+      @type       = type
+      @edges      = edges
+      @unresolved = unresolved
+      @meta       = meta
+    end
+
+    # Public: Reports whether another node intersects.
+    # Nodes are considered to be intersecting if their name and type are equal.
+    #
+    # node - Another Node.
+    #
+    # Returns true or false.
+    def intersects?(node)
+      node.name == name && node.type == type
+    end
+
+    # Public: Create a node representing the sum of the current node and
+    # another, intersecting node.
+    #
+    # node - Another node object.
+    #
+    # Returns self if self is passed.
+    # Returns nil if the nodes do not intersect.
+    # Returns a new node containing the sum of both nodes' edges otherwise.
+    def +(node)
+      return self if self == node
+      return nil unless self.intersects?(node)
+
+      new_edges      = accumulate_edges(edges, node.edges)
+      new_unresolved = accumulate_edges(unresolved, node.unresolved)
+      new_meta       = meta + node.meta
+
+      return Node.new(name: name, type: type, edges: new_edges,
+                      unresolved: new_unresolved, meta: new_meta)
+    end
+
+    # Public: Return the name of the node.
+    #
+    # Returns a string.
+    def to_s
+      name.to_s
+    end
+    alias_method :inspect, :to_s
+
+    private
+
+    # Internal: Reduce two lists of edges to a single list with equivalent
+    # edges summed.
+    #
+    # edges_a - Array of Edges.
+    # edges_b - Array of Edges.
+    #
+    # Returns an array of Edges.
+    def accumulate_edges(edges_a, edges_b)
+      new_edges = (edges_a + edges_b).flatten.reduce([]) do  |edges, edge|
+        if edges.detect { |e| e.to == edge.to }
+          edges.map { |e| e + edge || e }
+        else
+          edges + [edge]
+        end
+      end
+    end
+
+  end
+
+end

data/lib/society/object_graph.rb

@@ -1,12 +1,64 @@
 module Society
 
-  class ObjectGraph
+  # The ObjectGraph class represents a graph of interrelated nodes as an Array
+  # of nodes which can be iterated over.
+  class ObjectGraph < Array
 
-    attr_accessor :nodes, :edges
+    # Public: Override Array#initialize, accepting any number of nodes and
+    # lists of nodes including other ObjectGraphs to create a single graph from
+    # them.
+    #
+    # nodes - Any number of nodes or lists of nodes.
+    def initialize(*nodes)
+      super(nodes.flatten)
+    end
+
+    # Public: Add two graphs together, returning a new ObjectGraph containing
+    # the sum of all nodes contained in both.
+    #
+    # other - Another graph.
+    #
+    # Returns an ObjectGraph.
+    def +(other)
+      other.reduce(self) do |graph, node|
+        if graph.select { |n| n.intersects?(node) }.any?
+          Society::ObjectGraph.new(graph.map { |n| n + node || n  })
+        else
+          Society::ObjectGraph.new(graph, node)
+        end
+      end
+    end
+
+    # Public: Create a new graph, adding another node.
+    #
+    # node - Node to be added to the new graph.
+    #
+    # Returns an ObjectGraph.
+    def <<(node)
+      self + Society::ObjectGraph.new(node)
+    end
+    alias_method :push, :<<
+
+    # Public: Return the graph represented as a Hash.
+    #
+    # Returns a hash.
+    def to_h
+      self.reduce({}) do |hash, node|
+        hash.merge({ node.name => node.edges })
+      end
+    end
 
-    def initialize(nodes: nodes=[], edges: edges=[])
-      @nodes = nodes
-      @edges = edges
+    # Public: Return the graph as a JSON string.
+    #
+    # Returns a string.
+    def to_json
+      to_h.reduce({}) do |hash, node|
+        name, edges_raw = node
+        edges = edges_raw.reduce({}) do |edges, edge|
+          edges.merge({ edge.to => edge.weight })
+        end
+        hash.merge({ name => edges })
+      end.to_json
     end
 
   end

data/lib/society/parser.rb

@@ -1,66 +1,489 @@
 module Society
 
+  # The Parser class is responsible for producing an ObjectGraph from one or
+  # more ruby sources.
   class Parser
 
+    # Public: Generate a list of files from a collection of paths, creating a
+    # new Parser with them.
+    # Note: Since the files are not read, a new Parser MAY be returned such
+    # that initiating processing will cause a crash later.
+    #
+    # file_paths - Any number of Strings representing paths to files.
+    #
+    # Returns a Parser.
     def self.for_files(*file_paths)
-      new(::Analyst.for_files(*file_paths))
+      files = file_paths.flatten.flat_map do |path|
+        File.directory?(path) ? Dir.glob(File.join(path, '**', '*.rb')) : path
+      end
+      new(files.lazy.map { |f| File.read(f) })
     end
 
-    def self.for_source(source)
-      new(::Analyst.for_source(source))
+    # Public: Create a Parser with a collection of ruby sources to be analyzed.
+    #
+    # source - Any number of Strings containing ruby source.
+    #
+    # Returns a Parser.
+    def self.for_source(*source)
+      new(source.lazy)
     end
 
-    attr_reader :analyzer
-
-    def initialize(analyzer)
-      @analyzer = analyzer
+    # Public: Create a Parser, staging ruby source files to be analyzed.
+    #
+    # source - An Enumerable containing ruby source strings.
+    def initialize(source)
+      @source = source.map { |file| graph_from(file) }
     end
 
+    # Public: Generate a report from the object graph.
+    #
+    # format      - A symbol representing any known output format.
+    # output_path - Path to which output should be written. (default: nil)
+    #
+    # Returns nothing.
     def report(format, output_path=nil)
       raise ArgumentError, "Unknown format #{format}" unless known_formats.include?(format)
-      options = { json_data: json_data }
+      options = { json_data: graph.to_json }
       options[:output_path] = output_path unless output_path.nil?
       FORMATTERS[format].new(options).write
     end
 
+    # Public: Return the ObjectGraph representing the analyzed source.  Calling
+    # this method will trigger the analysis of the source if the object was
+    # created with lazy enumerables.
+    #
+    # Returns an ObjectGraph.
+    def graph
+      @graph ||= resolve_known_edges(source.reduce(ObjectGraph.new, &:+))
+    end
+
+    # Public: Return a list of known classes from the object graph.
+    #
+    # Returns an Array of Strings.
+    def classes
+      graph.map(&:name)
+    end
+
     private
 
-    FORMATTERS = {
-      html: Society::Formatter::Report::HTML,
-      json: Society::Formatter::Report::Json
-    }
+    attr_reader :source
 
-    def classes
-      @classes ||= analyzer.classes
+    # AST Node with the current namespace and type (module/class) preserved.
+    NSNode = Struct.new(:namespace, :type, :ast)
+    # ActiveRecord edge, containing the direct reference and any arguments.
+    AREdge = Struct.new(:reference, :args)
+
+    NAMESPACE_NODES     = [:class, :module]
+    NAMESPACE_SEPARATOR = '::'
+    CONSTANT_NAME_NODES = [:const_ref, :const_path_ref, :@const]
+    ACTIVERECORD_NODES  = %w(belongs_to has_one has_many
+                             has_and_belongs_to_many)
+
+    # Internal: Generate an ObjectGraph from a string containing ruby source.
+    #
+    # source - String containing ruby source.
+    #
+    # Returns an ObjectGraph.
+    def graph_from(source)
+      ast = Ripper.sexp(source)
+      nodes_from(ast).reduce(Society::ObjectGraph.new, &:<<)
+    end
+
+    # Internal: Generate a list of Nodes from a string containing ruby source.
+    # Note: All edges are considered unresolved at this stage.
+    #
+    # ast - Array containing an abstract syntax tree generated by Ripper.
+    #
+    # Returns an Array of Nodes.
+    def nodes_from(ast)
+      walk_ast(ast).map do |name, data|
+        init_node = Society::Node.new(name: name, type: data[:type])
+        find_edges(name, data[:ast]).reduce(init_node) do |node, new_edge|
+          edge = [Society::Edge.new(to: new_edge)]
+          type = data[:type]
+          Society::Node.new(name: name, type: type, unresolved: edge) + node
+        end
+      end
     end
 
-    def class_graph
-      @class_graph ||= begin
-        associations = associations_from(classes) + references_from(classes)
-        # TODO: merge identical classes, and (somewhere else) deal with
-        #       identical associations too. need a WeightedEdge, and each
-        #       one will be unique on [from, to], but will have a weight
+    # Internal: Isolate individual namespaces, generating a hash containing
+    # Namespace => AST pairs.
+    #
+    # ast - Array containing an abstract syntax tree generated by Ripper.
+    #
+    # Returns a Hash mapping Namespace => AST.
+    def walk_ast(ast)
+      scoped_nodes = filter_namespace([], ast)
 
-        ObjectGraph.new(nodes: classes, edges: associations)
+      scoped_nodes.reduce({}) do |nodes, node|
+        namespace = node[:namespace] + [node_name(node[:namespace], node[:ast])]
+        filter_namespace(namespace, node[:ast]).each do |sub|
+          scoped_nodes.push(sub)
+        end
+        nodes.merge({ namespace.last => node })
       end
     end
 
-    def json_data
-      Society::Formatter::Graph::JSON.new(class_graph).to_json
+    # Internal: Generate a list of nodes representing a change of namespace
+    # (classes/modules) from an abstract syntax tree, preserving the namespace
+    # associated with them.
+    #
+    # namespace - Array containing the current namespace, to be preserved along
+    #             with the AST.
+    # ast       - AST to be searched for namespace separators.  Note that due
+    #             to this object being globbed, mutating this object will not
+    #             mutate the state of the object passed to this method.
+    #
+    # Returns an Array of NSNodes.
+    def filter_namespace(namespace, *ast)
+      ast.reduce([]) do |nodes, node|
+        if node.is_a?(Array)
+          if NAMESPACE_NODES.include?(node.first)
+            nodes.push(NSNode.new(namespace, node.first, node[1..-1]))
+          else
+            node.each { |sub| ast.push(sub) }
+          end
+        end
+        nodes
+      end
     end
 
-    def known_formats
-      FORMATTERS.keys
+    # Internal: Determine the name of a given node which creates a new
+    # namespace (module/class).
+    #
+    # References to constants appear in the following two forms, with the
+    # indicator that a constant follows (CONSTANT_NAME_NODES) always in the
+    # leftmost branch:
+    #   [:const_ref, [:@const, "Klass", [1, 6]]]
+    # and:
+    #   [:const_path_ref,
+    #     [:var_ref, [:@const, "Namespaced", [1, 6]]],
+    #     [:@const, "Klass", [1, 18]]]
+    #
+    # namespace - Array containing the current namespace, used to determine the
+    #             full namespace of the node.
+    # ast       - AST to be searched for references to constants.  This object
+    #             is globbed, so it may be mutated safely.
+    #
+    # Raises ArgumentError if no name can be found.
+    # Returns a String.
+    def node_name(namespace, *ast)
+      ast.reduce([]) do |path, node|
+        if node.is_a?(Array)
+          if CONSTANT_NAME_NODES.include?(node.first)
+            name = path.push(node.flatten.select { |e| e.is_a?(String) })
+            return((namespace + name).flatten.join(NAMESPACE_SEPARATOR))
+          end
+          ast.push(node.first)
+        end
+        path
+      end
+      raise(ArgumentError, 'No constant name found in the tree.')
+    end
+
+    # Internal: Find all references to edges (defined as references to external
+    # constants) within the current scope.
+    #
+    # parent - String containing the name of the current node.
+    # ast    - AST to be searched for references to constants.
+    #
+    # Returns an Array of Strings and AREdges.
+    def find_edges(parent, ast)
+      direct_reference_edges(parent, ast) + activerecord_edges(ast)
+    end
+
+    # Internal: Find all explicit references to edges within the current scope.
+    #
+    # parent - String containing the name of the current node.
+    # ast    - AST to be searched for references to constants.  This object is
+    #          globbed, so it may be mutated safely.
+    #
+    # Returns an Array of Strings.
+    def direct_reference_edges(parent, *ast)
+      ast.reduce([]) do |edges, node|
+        if node.is_a?(Array) && !NAMESPACE_NODES.include?(node.first)
+          if CONSTANT_NAME_NODES.include?(node.first)
+            edges.push(node)
+          else
+            node.each { |sub| ast.push(sub) }
+          end
+        end
+        edges
+      end.map { |node| node_name([], node) }.reject { |node| parent == node }
+    end
+
+    # Internal: Find all references to edges via ActiveRecord associations
+    # (belongs_to, has_one, has_many, has_and_belongs_to_many) in the current
+    # scope.
+    #
+    # ast - AST to be searched for references to ActiveRecord associations.
+    #       This object is globbed, so it may be mutated safely.
+    #
+    # Returns an Array of AREdges.
+    def activerecord_edges(*ast)
+      activerecord_nodes(ast).reduce([]) do |edges, node|
+        if node.is_a?(Array) && !NAMESPACE_NODES.include?(node.first)
+          node_type, args = node
+          if ACTIVERECORD_NODES.include?(node_type[1])
+            edges.push(activerecord_references(args))
+          end
+        end
+        edges
+      end.compact.map { |edge| AREdge.new(edge[:reference], edge[:args]) }
+    end
+
+    # Internal: Find and return all instances of ActiveRecord association
+    # nodes.
+    #
+    # These will match the following pattern:
+    #   [:command,
+    #     [:@ident, "has_many", [2, 10]],
+    #     [:args_add_block,
+    #       [[:symbol_literal, [:symbol, [:@ident, "associations", [2, 22]]]],
+    #         [:bare_assoc_hash,
+    #           [[:assoc_new,
+    #             [:@label, "polymorphic:", [2, 33]],
+    #             [:var_ref, [:@kw, "true", [2, 46]]]]]]], false]]
+    # Note: the bare_assoc_hash node is optional and only appears in cases
+    # where additional arguments beyond the association name are passed.
+    #
+    # ast - AST to be searched for references to ActiveRecord associations.
+    #
+    # Returns an Array of AST nodes.
+    def activerecord_nodes(ast)
+      ast.reduce([]) do |nodes, node|
+        if node.is_a?(Array) && !NAMESPACE_NODES.include?(node.first)
+          if [:command].include?(node.first)
+            if ACTIVERECORD_NODES.include?(node[1][1])
+              nodes.push(node[1..-1])
+            end
+          else
+            node.each { |sub| ast.push(sub) }
+          end
+        end
+        nodes
+      end
+    end
+
+    # Internal: Process argument blocks (args_add_block nodes), returning a
+    # Hash representative of the arguments passed to a given ActiveRecord
+    # association command.
+    #
+    # The block will match the following pattern:
+    #   [:args_add_block,
+    #     [[:symbol_literal, [:symbol, [:@ident, "associations", [2, 22]]]],
+    #       [:bare_assoc_hash,
+    #         [[:assoc_new,
+    #           [:@label, "polymorphic:", [2, 33]],
+    #           [:var_ref, [:@kw, "true", [2, 46]]]]]]], false]
+    # Note: the bare_assoc_hash node is optional and only appears in cases
+    # where additional arguments beyond the association name are passed.
+    #
+    # args - AST representing an arguments block to be processed.
+    #
+    # Returns a Hash or nil.
+    def activerecord_references(args)
+      return nil unless args.is_a?(Array) && args.first == :args_add_block
+      arg_tree = args[1]
+      arg_tree.reduce({}) do |references, node|
+        if node.is_a?(Array) && !NAMESPACE_NODES.include?(node.first)
+          references.merge(process_reference_ast(node))
+        else
+          references
+        end
+      end
     end
 
-    def associations_from(all_classes)
-      @association_processor ||= AssociationProcessor.new(all_classes)
-      @association_processor.associations
+    # Internal: Process argument blocks (args_add_block nodes), returning a
+    # Hash representative of one of the arguments passed to a given
+    # ActiveRecord association command.
+    #
+    # The block will match the following patterns:
+    #   [:symbol_literal, [:symbol, [:@ident, "associations", [2, 22]]]]
+    # or:
+    #   [:bare_assoc_hash,
+    #     [[:assoc_new,
+    #       [:@label, "polymorphic:", [2, 33]],
+    #       [:var_ref, [:@kw, "true", [2, 46]]]]]]
+    # Note: the bare_assoc_hash node is optional and only appears in cases
+    # where additional arguments beyond the association name are passed.
+    #
+    # node - AST representing an argument block to be processed.
+    #
+    # Returns a Hash.
+    def process_reference_ast(node)
+      if [:symbol_literal].include?(node.first)
+        { reference: node.flatten.detect { |e| e.is_a?(String) } }
+      elsif [:bare_assoc_hash].include?(node.first)
+        { args: arguments_hash(node[1]) }
+      else
+        { }
+      end
+    end
+
+    # Internal: Generate a Hash from a block describing a Hash.
+    #
+    # The block will match the following pattern:
+    #   [[:assoc_new,
+    #     [:@label, "polymorphic:", [2, 33]],
+    #     [:var_ref, [:@kw, "true", [2, 46]]]]]
+    #
+    # node - AST representing a hash definition block to be processed.
+    #
+    # Returns a Hash.
+    def arguments_hash(node)
+      node.select { |node| node.first == :assoc_new }.reduce({}) do |hash, node|
+        key, val = node[1,2].map do |node|
+          if node.is_a?(Array)
+            node.flatten.detect { |element| element.is_a?(String) }
+          end
+        end
+        key && val ? hash.merge({ key.gsub(/:/, '') => val }) : hash
+      end
+    end
+
+    # Internal: Attempt to resolve all edges for the nodes contained within an
+    # ObjectGraph.
+    #
+    # graph - ObjectGraph to process.
+    #
+    # Returns an ObjectGraph.
+    def resolve_known_edges(graph)
+      resolve_known_activerecord_edges(graph) + resolve_direct_edges(graph)
+    end
+
+    # Internal: Attempt to resolve all directly referenced edges for the nodes
+    # contained within an ObjectGraph, discarding all unresolved edges after
+    # this step.
+    #
+    # graph - ObjectGraph to process.
+    #
+    # Returns an ObjectGraph.
+    def resolve_direct_edges(graph)
+      known_nodes = graph.map(&:name)
+      new_graph = graph.map do |node|
+        known = node.unresolved.select { |edge| known_nodes.include?(edge.to) }
+        Society::Node.new(name: node.name, type: node.type, edges: known)
+      end
+      Society::ObjectGraph.new(new_graph)
     end
 
-    def references_from(all_classes)
-      @reference_processor ||= ReferenceProcessor.new(all_classes)
-      @reference_processor.references
+    # Internal: Attempt to resolve all ActiveRecord association edges for the
+    # nodes contained within an ObjectGraph, discarding all unresolved edges
+    # after this step.
+    #
+    # graph - ObjectGraph to process.
+    #
+    # Returns an ObjectGraph.
+    def resolve_known_activerecord_edges(graph)
+      aredges = graph.map do |node|
+        node.unresolved.select { |edge| edge.to.is_a?(AREdge) }
+          .map(&:to).each_with_object(node).to_a.map(&:reverse)
+      end.flatten(1)
+      argraph = aredges.reduce(graph) do |graph, edge_tuple|
+        node, edge = edge_tuple
+        graph << add_meta_to_node(node, edge[:args], edge[:reference])
+      end
+      graph + argraph.map { |n| resolve_activerecord_associations(argraph, n) }
+    end
+
+    # Internal: Generate a Node with metainformation populated from
+    # ActiveRecord association information.
+    #
+    # node      - Node object to which the arglist should be added as meta
+    #             information.
+    # args_hash - Hash containing arguments passed to the ActiveRecord
+    #             association if any; nil otherwise.
+    # ref       - Reference for the ActiveRecord association.
+    #
+    # Returns a Node.
+    def add_meta_to_node(node, args_hash, ref)
+      refs = ({ reference: ref }).merge(args_hash || {})
+      node + Node.new(name: node.name, type: node.type, meta: [refs])
+    end
+
+    # Internal: Generate a Node with edges resolved by searching the graph for
+    # nodes with corresponding ActiveRecord associations (e.g. as: relations
+    # for polymorphic ActiveRecord associations.)
+    #
+    # graph - ObjectGraph containing nodes to search for associations.
+    # node  - Node object for which ActiveRecord associations will be resolved.
+    #
+    # Returns a Node.
+    def resolve_activerecord_associations(graph, node)
+      return node if node.meta.empty?
+      init_data = { name: node.name, type: node.type }
+
+      node.meta.reduce(Society::Node.new(init_data)) do |node, meta|
+        edges = edge_names_from_meta_node(graph, meta).map do |edge_name|
+          Society::Edge.new(to: edge_name)
+        end
+        node + Society::Node.new(init_data.merge({ edges: edges }))
+      end
+    end
+
+    # Internal: Determine all edges for a given ActiveRecord association based
+    # on a search of a global graph for corresponding associations (e.g. as:
+    # for polymorphic associations.)
+    # Only one type of association will be resolved for any given set of
+    # meta-information; the ActiveRecord reference itself is used as a
+    # fallback.
+    #
+    # graph - ObjectGraph containing nodes to search for associations.
+    # meta  - Hash containing meta information to use in resolving the
+    #         association.
+    #
+    # Returns an Array of Strings.
+    def edge_names_from_meta_node(graph, meta)
+      edge = meta['class_name'] ||
+        process_through_meta_node(graph, meta) ||
+        process_polymorphic_meta_node(graph, meta) ||
+        meta[:reference]
+
+      [edge].flatten.map(&:pluralize).map(&:classify)
+    end
+
+    # Internal: Resolve references for 'through' ActiveRecord associations.
+    #
+    # graph - ObjectGraph containing nodes to search for associations.
+    # meta  - Hash containing meta information to use in resolving the
+    #         association.
+    #
+    # Returns an Array of Strings.
+    def process_through_meta_node(graph, meta)
+      return nil unless meta['through']
+
+      through = meta['through'].pluralize.classify
+      ref     = meta['source'] || meta[:reference]
+      graph.select { |n| n.name == through }.flat_map do |n|
+        n.meta.select { |m| [ref, ref.singularize].include?(m[:reference]) }
+      end.map { |meta| edge_names_from_meta_node(graph, meta) }
+    end
+
+    # Internal: Resolve references for polymorphic ActiveRecord associations.
+    #
+    # graph - ObjectGraph containing nodes to search for associations.
+    # meta  - Hash containing meta information to use in resolving the
+    #         association.
+    #
+    # Returns an Array of Strings.
+    def process_polymorphic_meta_node(graph, meta)
+      return nil unless meta['polymorphic']
+      graph.select do |n|
+        n.meta.select { |m| m['as'] == meta[:reference] }.any?
+      end.map(&:name)
+    end
+
+    FORMATTERS = {
+      html: Society::Formatter::Report::HTML,
+      json: Society::Formatter::Report::Json
+    }
+
+    # Internal: List known output formatters.
+    #
+    # Returns an Array of Symbols.
+    def known_formats
+      FORMATTERS.keys
     end
 
   end