fb_bookworm 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a6733ef21b70c3347ab2cd086e16157bf4f73e1dac61e78c0910d66c1d3af461
+  data.tar.gz: 3060f2e89a7619d4d9533a884fd51370b81a99aa74c7a0f11f539f8f1ee1ed3c
+SHA512:
+  metadata.gz: 1b3dfb7904350f6fbbe415765fad80aeb8b436d69273e4df320cede0e1332de932140a17f5a7d69200ad14d1b791db206d2a3376b6ebc7ccfc2d795cca90455a
+  data.tar.gz: d7348f554dd139736c2c3add01a4631d2e3ff169539fa7be05c99957f52ee08c4c5cb6b6a0a8bc071818e90abd40ed4b4c8dd67086051c2a0232dad7a0fcfa40

data/LICENSE

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,161 @@
+fb_bookworm
+===========
+
+[![Continuous Integration](https://github.com/facebook/bookworm/workflows/Continuous%20Integration/badge.svg?event=push)](https://github.com/facebook/bookworm/actions?query=workflow%3A%22Continuous+Integration%22)
+
+Bookworm is a program that gleans context from a Chef/Ruby codebase, which
+recognizes that Ruby source files in different directories have different
+semantic meaning to a larger program (ie Chef)
+
+It currently runs on top of the Chef Workstation Ruby, although there is
+nothing preventing running bookworm on vanilla Ruby using bundler, etc.
+
+Usage
+-----
+
+Bookworm is designed to be installed via Chef cookbook as well as running
+directly from the cookbook. This assumes you have at least [Chef Workstation
+20](https://www.chef.io/downloads/tools/workstation) installed. If you run this
+cookbook in a Chef run, it will also install Bookworm into
+`/usr/local/lib/bookworm` (with a shell script launcher at
+`/usr/local/bin/bookworm`)
+
+```
+# If you're running directly from the cookbook
+cd files/default/bookworm
+
+# Get the program flags
+$ ./bookworm.rb -h
+Usage: bookworm.rb [options]
+        --report CLASS               Give the (class) name of the report you'd like
+        --list-reports               Get the (class) names of available reports
+        --list-rules                 Get the (class) names of available inference rules
+
+Debugging options:
+        --irb-config-step            Open IRB REPL after loading configuration
+        --irb-crawl-step             Open IRB REPL after crawler has run
+        --irb-infer-step             Open IRB REPL after inference has run
+        --irb-report-step            Open IRB REPL after report is generated
+
+# Get a list of reports that can be run
+$ bookworm --list-reports
+AllReferencedRecipes    Determines all recipes that are directly referenced by all roles
+AllRoleDescriptions     Basic report to show extraction of description from roles
+...
+
+# Run a report
+$ bookworm --report AllRoleDescriptions
+```
+
+Configuring Bookworm
+--------------------
+
+Bookworm currently checks 2 different places for configuration,
+`~/.bookworm.yml` and `/usr/local/etc/bookworm/configuration.rb`
+
+### ~/.bookworm.yml
+
+A typical bookworm YAML configuration would look something like this:
+
+```yaml
+# A basic chef layout
+source_dirs:
+  cookbook_dirs:
+    - /absolute/path/to/cookbooks
+    - /absolute/path/to/some/other/cookbooks
+  role_dirs:
+    - /absolute/path/to/role/files
+debug: false   # Additional debug information
+```
+
+### /usr/local/etc/bookworm/configuration.rb
+
+If you need to programmatically determine what your `source_dirs` are (ie if
+you don't know what directories Bookworm will be running on ahead of time), you
+can use `/usr/local/etc/bookworm/configuration.rb` to set `DEFAULT_SOURCE_DIRS`
+and `DEFAULT_DEBUG`. This might be overkill for your needs, and
+`~/.bookworm.yml` is probably your best bet.
+
+Glossary
+--------
+
+### Bookworm key
+
+A bookworm key is a type of file, and all the information that should be
+necessary to handle that file throughout the Bookworm pipeline. By
+encapsulating the "what" and the "how" of a file here, adding new types of
+files to Bookworm shouldn't involve more than adding a new key.
+
+Of note, a 'metakey' isn't a file - it could be a concept or a group of files.
+This is particularly useful with Chef code, since the notion of a 'cookbook' is
+several things, and rather than doing backflips trying to match information to
+specific files within a cookbook directory, it's much simpler to say "this
+cookbook provides this resource/class/attribute."
+
+### Crawler
+
+The crawler is what transforms whatever the key finds into a navigable Ruby
+representation of the file (for Ruby files, this would be an AST representation
+of the source file as generated by the rubocop-ast gem).
+
+### KnowledgeBase
+
+The KnowledgeBase is the singleton object that holds all Ruby representations
+of the crawled files, as well as all information derived by the Bookworm rules.
+
+### Rule
+
+A 'rule' in Bookworm is an auto-generated class that takes the crawled
+representation of a file and extracts specific information about it. If you
+want to know about 3 unrelated patterns in a source file, consider using (or
+writing, if they don't exist yet) 3 rules. Small rules encourage re-use in
+reports, and since rules can reference information about a file derived from
+*other* rules, this is a good place to do any heavy lifting when figuring out
+what's going on with your keys.
+
+### InferEngine
+
+The InferEngine runs the necessary rules against each key that was crawled.
+
+### Reports
+
+The report takes the information that you've extracted from the codebase, and
+pulls it together into a human or machine-readable representation. While this
+is a good place to store specific logic for representation, it doesn't hurt to
+ask 'how do I delegate the hard work to rules' - think of reports as the glue
+that pulls together a bunch of derived facts into something nice that you can
+hand to your boss ;-)
+
+Guiding design principles
+-------------------------
+
+- Easy and fast iteration
+  - Writing a Bookworm rule or report should be as easy as grabbing bash and grep
+  - Profiling and debugging hooks should be in strategic spots to make it easy to debug
+- Each new rule or report unlocks the potential for new discoveries
+  - It should be easy to use existing work, so that building reports is just a matter of grabbing existing rules (or other reports)
+- Zero-cost additions, so you only analyze/execute the report (and supporting
+  rules) that are needed
+  - A slow rule shouldn't matter unless you're actually using it
+  - Accept that copy-paste is going to happen with rules and reports, and make that simple.
+
+Implementation notes - Why Rubocop for AST generation
+-----------------------------------------------------
+
+Because we wanted to use something that was already in Chef Workstation, the
+two choices were Ripper or Parser a la RuboCop (ruby_parser uses racc which has
+a C extension, but no sexp pattern matcher that I know of).
+
+Ripper is fast, but the sexp output is kind of nasty, and cleaning that up
+could be a big timesuck. Since the larger Ruby/Chef community has a bit more
+familiarity with Parser/RuboCop's node pattern matching, it'd be better to stay
+with that for now (there's no reason this couldn't be migrated later with
+helpers to translate patterns). Work could also be done to speed up RuboCop
+(ractor and async support could go a long way here).
+This repo contains attribute-driven-API cookbooks maintained by Facebook. It's
+a large chunk of what we refer to as our "core cookbooks."
+
+License
+-------
+
+See the LICENSE file in this directory

data/lib/bookworm/configuration.rb

@@ -0,0 +1,53 @@
+# Copyright (c) 2022-present, Meta Platforms, Inc. and affiliates
+# All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+module Bookworm
+  class Configuration
+    attr :source_dirs, :debug
+    attr_reader :system_contrib_dir
+
+    # Allow for programmatic configuration override
+    SYSTEM_CONFIGURATION_RUBY_FILE = '/usr/local/etc/bookworm/configuration.rb'.freeze
+    SYSTEM_CONTRIB_DIR = '/usr/local/etc/bookworm/contrib'.freeze
+
+    def initialize
+      begin
+        load SYSTEM_CONFIGURATION_RUBY_FILE
+      rescue LoadError
+        # puts "No configuration found at #{SYSTEM_CONFIGURATION_RUBY_FILE}"
+        config = {}
+      end
+      begin
+        config = YAML.load_file "#{Dir.home}/.bookworm.yml"
+      rescue StandardError
+        config = {}
+      end
+
+      @system_contrib_dir = SYSTEM_CONTRIB_DIR
+      if Bookworm::Configuration.const_defined?(:DEFAULT_SOURCE_DIRS)
+        @source_dirs ||= DEFAULT_SOURCE_DIRS
+      end
+      if Bookworm::Configuration.const_defined?(:DEFAULT_DEBUG)
+        @debug ||= DEFAULT_DEBUG
+      end
+
+      @system_contrib_dir = config['system_contrib_dir'] if config['system_contrib_dir']
+      @source_dirs = config['source_dirs'] if config['source_dirs']
+      @debug = config['debug'] if config['debug']
+
+      @source_dirs ||= []
+    end
+  end
+end

data/lib/bookworm/crawler.rb

@@ -0,0 +1,69 @@
+# Copyright (c) 2022-present, Meta Platforms, Inc. and affiliates
+# All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+require 'rubocop'
+require 'parser/current'
+
+# TODO(dcrosby) Bookworm key should determine which AST parser is chosen. This
+# would allow multiple AST parsers (ie ripper) and a way of ingesting non-Ruby
+# files like JSON/YAML
+
+module Bookworm
+  class Crawler
+    attr_reader :processed_files
+
+    def initialize(config, keys: [])
+      @config = config
+      @intake_queue = {}
+      @processed_files = {}
+
+      # TODO(dcrosby) add messages to verbose mode
+      keys.each do |key|
+        generate_file_queue(key)
+        process_paths(key)
+      end
+    end
+
+    private
+
+    def generate_file_queue(key)
+      v = BOOKWORM_KEYS[key]
+      @intake_queue[key] = @config.source_dirs[v['source_dirs']].
+                           map { |d| Dir.glob("#{d}/#{v['glob_pattern']}") }.flatten
+    end
+
+    def process_paths(key)
+      queue = @intake_queue[key]
+      processed_files = {}
+      until queue.empty?
+        path = queue.pop
+        processed_files[path] = generate_ast(File.read(path))
+      end
+      @processed_files[key] = processed_files
+    end
+
+    # In order to keep rules from barfing on a nil value (when no AST is
+    # generated at all from eg. an empty source code file), we supply a
+    # single node called bookworm_found_nil. It's a magic value that is
+    # 'unique enough' for our purposes
+    EMPTY_RUBOCOP_AST = ::RuboCop::AST::Node.new('bookworm_found_nil').freeze
+    def generate_rubocop_ast(code)
+      ::RuboCop::ProcessedSource.new(code, RUBY_VERSION.to_f)&.ast ||
+        EMPTY_RUBOCOP_AST
+    end
+
+    alias generate_ast generate_rubocop_ast
+  end
+end

data/lib/bookworm/exceptions.rb

@@ -0,0 +1,20 @@
+# Copyright (c) 2022-present, Meta Platforms, Inc. and affiliates
+# All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+module Bookworm
+  # ClassLoadError is where Bookworm tries to autogenerate a class from a file
+  # and cannot
+  class ClassLoadError < RuntimeError; end
+end

data/lib/bookworm/infer_base_classes.rb

@@ -0,0 +1,80 @@
+# Copyright (c) 2022-present, Meta Platforms, Inc. and affiliates
+# All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+require 'rubocop'
+require 'pathname'
+
+module Bookworm
+  class InferRule
+    class << self
+      {
+        'description' => '',
+        'keys' => [],
+      }.each do |attribute, default_value|
+        instance_variable_set("@#{attribute}".to_sym, default_value)
+        define_method(attribute.to_sym) do |val = nil|
+          instance_variable_set("@#{attribute}", val) unless val.nil?
+          instance_variable_get("@#{attribute}")
+        end
+      end
+    end
+
+    extend RuboCop::NodePattern::Macros
+    def initialize(metadata)
+      @metadata = metadata
+      output
+    end
+
+    def to_a
+      []
+    end
+
+    def to_h
+      {}
+    end
+
+    def default_output
+      :to_a
+    end
+
+    def output
+      send(default_output)
+    end
+  end
+
+  # Initializing constant for Bookworm::InferRules
+  module InferRules; end
+
+  def self.load_rule_class(name, dir: '')
+    f = File.read "#{dir}/#{name.to_sym}.rb"
+    ::Bookworm::InferRules.const_set(name.to_sym, ::Class.new(::Bookworm::InferRule))
+    ::Bookworm::InferRules.const_get(name.to_sym).class_eval(f)
+  rescue StandardError
+    raise Bookworm::ClassLoadError
+  end
+
+  def self.load_rules_dir(dir)
+    files = Dir.glob("#{dir}/*.rb")
+    files.each do |f|
+      name = Pathname(f).basename.to_s.gsub('.rb', '')
+      begin
+        Bookworm.load_rule_class name, :dir => dir
+      rescue Bookworm::ClassLoadError
+        puts "Unable to load rule #{f}"
+        exit(false)
+      end
+    end
+  end
+end

data/lib/bookworm/infer_engine.rb

@@ -0,0 +1,45 @@
+# Copyright (c) 2022-present, Meta Platforms, Inc. and affiliates
+# All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+require 'bookworm/knowledge_base'
+require 'bookworm/infer_base_classes'
+
+module Bookworm
+  # The InferEngine class takes a KnowledgeBase object, and then runs the given
+  # rules against the files within each bookworm key in the KnowledgeBase that
+  # the rule uses.
+  class InferEngine
+    def initialize(knowledge_base, rules = [])
+      @kb = knowledge_base
+
+      rules.each do |rule|
+        process_rule(rule)
+      end
+    end
+
+    def process_rule(rule)
+      klass = Bookworm::InferRules.const_get(rule)
+      klass.keys.each do |key|
+        @kb[key].each do |name, metadata|
+          @kb[key][name][rule] = klass.new(metadata).output
+        end
+      end
+    end
+
+    def knowledge_base
+      @kb
+    end
+  end
+end