debt_ceiling 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bb989ae976353da509970f25093e1ae303ec8b6f
-  data.tar.gz: a473a4ba56137d62578d03522e1519f11ab4d982
+  metadata.gz: 1121dd0d368a02bfad9d6f2fd21a15707c8089d8
+  data.tar.gz: 7dca6e9d0b291318e5e67b99a5aa96245a416c7e
 SHA512:
-  metadata.gz: 1d4243bb0c4569c7d42d37de59102d36dc29211647f087295fe4b5807f5493c416203f54734a295a744b8b0adc65672263dedabaa2f38594ea4f67e214e6f288
-  data.tar.gz: a4820d63a6f400e833c7015d85751aa539a58ae2c89d979d087b17eb350f397b1c2382cba9105cd5c8297b1d4b7adcb02d1e9929127c9038dad905c77cf04e74
+  metadata.gz: bf8aee5e06f3ec57e6215bd2e3a8d88471f2185b053cf4acb76a82ed175c6b5163f869f02dd6b30766f81cf68483fb01082dafc1ae91b9594139496c0bc34339
+  data.tar.gz: a3b9a6ae68acf71df05fca377df940dc5a3b85c1ed4dcaf188a681d3aeff177582c262ad3b6b6429fdf133f99f5c26ea0be16e8215196bbfe65b407188e5729d

data/README.md

@@ -1,8 +1,76 @@
+[![Debt Ceiling Chat](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/bglusman/debt_ceiling)
+
 #DebtCeiling
 
-###
-Work in progress, trying to use some automatic heuristic plus manual mechanisms to help visibility and tracking of technical debt.
 
-Current plan is to configure/customize the weight given to heuristic grade
-based first on a simple DSL in a .debt_ceiling file in the project's home directory, and if additional customization is desired, pass a path to 
-`extension_file_path` command in the DSL file to a file defining DebtCeiling::Debt like the one in examples directory, and replace/augment it's methods with your own additional calculation per file.
+### Work in progress, trying to use some automatic heuristic plus manual mechanisms to help visibility and tracking of technical debt.
+
+Current features include:
+* configuring points per [RubyCritic](https://github.com/whitesmith/rubycritic) grade per file line
+* Whitelisting/blacklisting files by filename
+* Modifying or replacing default calculation on a per file basis
+* Reporting the single greatest source of debt based on your definitions
+* Reporting total debt for the git repo based on your definitions
+* Running the binary from a test suite to fail if debt ceiling is exceeded
+* Running the binary from a test suite to fail if debt deadline is missed
+
+These features are largely are demonstrated/discussed in [examples/.debt_ceiling](https://github.com/bglusman/debt_ceiling/blob/master/examples/.debt_ceiling.example) which demonstrates configuring debt ceiling
+
+Additional customization is supported via two method hooks in the debt class, which debt_ceiling will load from a provided extension_file_path in the main config file, which should look like the [example file](https://github.com/bglusman/debt_ceiling/blob/master/examples/debt.rb.example)
+
+You can configure/customize the debt calculated using a few simple commands in a .debt_ceiling file in the project's home directory
+
+```
+set_debt_ceiling 500
+#exceeding this will fail a test, if you run debt_ceiling binary from test suite
+debt_reduction_target_and_date 100, 'Jan 1 2015'
+#exceeding this will fail after the target date (parsed by Chronic)
+
+#set the multipliers per line of code in a file with each letter grade
+b_cost_per_line 10
+c_cost_per_line 20
+d_cost_per_line 40
+f_cost_per_line 100
+
+#load custom debt calculations (see examples/debt.rb) from this path
+extension_file_path "./debt.rb"
+
+#only count debt scores for files matching these strings (converted to regexes)
+whitelist_matching %w(app lib)
+
+#or.... exclude debt scores for files matching these strings (obviously mutually exclusive, raises error if both present)
+#blacklist_matching %w(schema.rb routes.rb)
+```
+
+As mentioned/linked above, additional customization is supported.
+
+As shown in example file, pass a path to `extension_file_path` command pointing to a file defining DebtCeiling::Debt like the one in examples directory, and define its methods for your own additional calculation per file.
+
+Right now it lacks all tests...  feel free to open a PR!  
+
+I'll try and add test coverage where it makes sense as API matures.
+
+## TODO: planned features/ideas
+
+todo_cost 500      #cost per comment matching /TODO/
+
+debt_per_reference_to deprecated_regex, 500 # help transition away from deprecated APIs 
+
+points_per_regex_match REGEX, 500 # seems like an alias for above maybe, nix?
+
+
+### Other ideas:
+
+rubocop/cane integration debt for style violations
+
+every line over x ideal file size is y points of debt
+
+multipliers for important files
+
+include one of the JS complexity/debt analysis libraries below, or another if anyone had another suggestion: 
+
+* https://github.com/es-analysis/plato
+
+* https://github.com/dpnishant/jsprime
+
+* https://github.com/mozilla/doctorjs

data/bin/debt_ceiling

@@ -21,4 +21,4 @@ end
 extension_path = DebtCeiling.current_extension_file_path
 load extension_path if File.exists?(extension_path)
 
-DebtCeiling.enforce(ARGV[0] ? ARGV[0] : ".")
+DebtCeiling.calculate(ARGV[0] ? ARGV[0] : ".")

data/debt_ceiling.gemspec

@@ -3,23 +3,19 @@ lib = File.expand_path('../lib/', __FILE__)
 $:.unshift lib unless $:.include?(lib)
 require "debt_ceiling/version"
 
-# module ::Gem
-#  post_install {|gem_installer| puts 'in hook'; DebtCeiling.post_install(gem_installer) }
-# end
-
 Gem::Specification.new do |s|
   s.name        = "debt_ceiling"
   s.version     = DebtCeiling::VERSION
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Brian Glusman"]
   s.email       = ["bglusman@shutterstock.com"]
-  s.homepage    = "https://github.com/bglusman/DebtCeiling"
+  s.homepage    = "https://github.com/bglusman/debt_ceiling"
   s.summary     = "DebtCeiling helps you track Tech Debt"
   s.rubyforge_project = "debt_ceiling"
   s.extensions = ["Rakefile"]
 
   s.description = <<-DESC
-    Quantify and add visibility/history to (some half-baked standin for) Technical Debt
+    Get a grip on your technical debt
   DESC
 
 
@@ -29,7 +25,8 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_runtime_dependency "rubycritic", "~> 1.1.1"
-  s.add_runtime_dependency "pry"
-  s.add_development_dependency "rake"
-  s.add_development_dependency "minitest"
+  s.add_runtime_dependency "chronic", "~> 0.10"
+  s.add_development_dependency "pry", '~> 0.10'
+  s.add_development_dependency "rake", '~> 10.3'
+  s.add_development_dependency "minitest", '~> 5.4'
 end

data/examples/.debt_ceiling.example

@@ -1,36 +1,19 @@
-#TODO example gradings
-# debt_ceiling 15000
+set_debt_ceiling 500
+#exceeding this will fail a test, if you run debt_ceiling binary from test suite
+debt_reduction_target_and_date 100, 'Jan 1 2015'
+#exceeding this will fail after the target date (parsed by Chronic)
 
+#set the multipliers per line of code in a file with each letter grade
 b_cost_per_line 10
 c_cost_per_line 20
 d_cost_per_line 40
 f_cost_per_line 100
-# todo_cost 500
 
-# debt_per_reference_to blah
+#load custom debt calculations (see examples/debt.rb) from this path
+extension_file_path "./debt.rb"
 
-# points_per_regex_match REGEX, points
-
-#rubocop/cane integration debt for style violations
-
-#every line over x ideal file size is y points of debt
-
-#whitelist/blacklist API: TODO
-
-#multipliers for important files
-
-#ditch/augment module eval and use below or something
-
-# class DebtRule
-#   def measure_file(filename, metrics)
-#     cost = 0
-
-#     cost += 0 if metrics.rubycritic.grade == :a
-#     cost += 10 if metrics.rubycritic.grade == :b
-
-#     churn = measure_churn(filename)
-#     cost += whatever if churn > something
-#   end
-
-#   def measure_churn...
-# end 
+#only count debt scores for files matching these strings (converted to regexes)
+whitelist_matching %w(app lib)
+#or
+#exclude debt scores for files matching these strings (commented as mutually exclusive)
+#blacklist_matching %w(schema.rb routes.rb)

data/examples/debt.rb.example

@@ -10,10 +10,11 @@ module DebtCeiling
     end
 
     #OR do your own calcuation first, and add defaults on top of that
-    def augment_custom_debt
+    def augment_debt
       #output additional cost beyond defaults based on #file_attributes
     end
 
-    #augment_custom_debt is only called if measure_debt is undefined or returns nil/false
+    #augment_debt is only called if measure_debt is undefined or returns nil/false 
+    #for this instance of debt (which is 1:1 mapping of Rubycritic::AnalysedModule at the moment)
   end
 end

data/lib/debt_ceiling/debt.rb

@@ -1,31 +1,54 @@
 module DebtCeiling
   class Debt
-    attr_reader :file_attributes
+    DoNotWhitelistAndBlacklistSimulateneously = Class.new(StandardError)
+
+    attr_reader :file_attributes, :path, :analysed_module, :module_name, :linecount
     attr_accessor :debt_amount
     def initialize(file_attributes)
-      @file_attributes = file_attributes
-      default_measure_debt
+      @file_attributes  = file_attributes
+      @path             = file_attributes.path
+      @analysed_module  = file_attributes.analysed_module
+      @module_name      = file_attributes.name
+      @linecount        = file_attributes.linecount
+      default_measure_debt if valid_debt?
     end
 
     def default_measure_debt
-      if self.respond_to?(:measure_file)
+      if self.respond_to?(:measure_debt)
         cost = self.public_send(:measure_debt)
       end
       if !cost
-        cost = if self.respond_to?(:augment_custom_debt)
-          self.public_send(:augment_custom_debt) || 0
+        cost = if self.respond_to?(:augment_debt)
+          self.public_send(:augment_debt) || 0
         else
           0
         end
-        letter_grade = file_attributes.analyzed_module.rating.to_s.downcase
+        letter_grade = file_attributes.analysed_module.rating.to_s.downcase
         cost_per_line = DebtCeiling.public_send("#{letter_grade}_current_cost_per_line")
         cost += file_attributes.linecount * cost_per_line
       end
       self.debt_amount = cost
     end
 
+    def valid_debt?
+      black_empty = DebtCeiling.blacklist.empty?
+      white_empty = DebtCeiling.whitelist.empty?
+      raise DoNotWhitelistAndBlacklistSimulateneously if (!black_empty && !white_empty)
+      (black_empty && white_empty) ||
+      (black_empty && self.class.whitelist_includes?(self)) ||
+      (white_empty && !self.class.blacklist_includes?(self))
+    end
+
+    def self.whitelist_includes?(debt)
+      DebtCeiling.whitelist.detect {|filename| filename.match debt.path }
+    end
+
+    def self.blacklist_includes?(debt)
+      DebtCeiling.blacklist.detect {|filename| filename.match debt.path }
+    end
+
     def to_i
-      debt_amount
+      debt_amount.to_i
     end
 
     def +(other)

data/lib/debt_ceiling/version.rb

@@ -1,3 +1,3 @@
 module DebtCeiling
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/debt_ceiling.rb

@@ -1,35 +1,16 @@
-require 'ripper'
-require_relative 'debt_ceiling/enforcement'
+require_relative 'debt_ceiling/accounting'
 require_relative 'debt_ceiling/debt'
-
-
+require 'chronic'
 
 module DebtCeiling
   extend self
 
-  def debt_ceiling(pattern, message=nil, options={})
-    if pattern.kind_of?(String)
-      rule = Rule.new(pattern, message, options)
-      DebtCeiling::Enforcement.add(rule)
-    else
-      DebtCeiling::Enforcement.add(self.send(pattern))
-    end
-  end
-
-  def enforce(dir=".")
-    DebtCeiling::Enforcement.process_directory(dir, :stdout)
+  def calculate(dir=".")
+    @debt = DebtCeiling::Accounting.calculate(dir)
+    evaluate
   end
 
-  def validate_files(files)
-    files.reduce(error: false, output:"") do |results, file|
-      error, output = DebtCeiling::Enforcement.process_file(file)
-      results[:error] ||= error
-      results[:output] += output
-      results
-    end
-  end
-
-  @extension_file_path = "#{Dir.pwd}/debt_rule.rb"
+  @extension_file_path = "#{Dir.pwd}/debt.rb"
   def extension_file_path(path)
     @extension_file_path = path
   end
@@ -38,12 +19,43 @@ module DebtCeiling
     @extension_file_path
   end
 
-  GRADES = [:a, :b, :c, :d, :f]
-  GRADE_DEFAULTS = [0, 10, 20, 40, 100]
-  GRADE_MAP = GRADES.zip(0..4).to_h
-  GRADES.each do |grade|
-    default_index = GRADE_MAP[grade]
-    instance_variable_set "@#{grade}_cost_per_line", GRADE_DEFAULTS[default_index]
+  def blacklist_matching(matchers)
+    @blacklist = matchers.map {|matcher| Regexp.new(matcher)}
+  end
+
+  def whitelist_matching(matchers)
+    @whitelist =  matchers.map {|matcher| Regexp.new(matcher)}
+  end
+
+  def set_debt_ceiling(value)
+    @ceiling_amount = value
+  end
+
+  def debt_reduction_target_and_date(target_value, date_to_parse)
+    @reduction_target = target_value
+    @reduction_date   = Chronic.parse(date_to_parse)
+  end
+
+  def evaluate
+    if ceiling_amount && ceiling_amount <= debt
+      fail_test
+    elsif reduction_target && reduction_target <= debt && 
+          Time.now > reduction_date
+      fail_test
+    end
+  end
+
+  def fail_test
+    Kernel.exit 1
+  end
+
+  attr_reader :blacklist, :whitelist, :ceiling_amount, :reduction_date, :reduction_target, :debt
+  @blacklist = []
+  @whitelist = []
+
+  GRADE_MAP = {a: 0, b: 10, c: 20, d: 40, f: 100} #arbitrary default grades for now
+  GRADE_MAP.keys.each do |grade|
+    instance_variable_set "@#{grade}_cost_per_line", GRADE_MAP[grade]
     define_method("#{grade}_current_cost_per_line") do
       instance_variable_get "@#{grade}_cost_per_line"
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: debt_ceiling
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Brian Glusman
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-12 00:00:00.000000000 Z
+date: 2014-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubycritic
@@ -25,49 +25,63 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 1.1.1
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: chronic
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.3'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '5.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '5.4'
 description: |2
-      Quantify and add visibility/history to (some half-baked standin for) Technical Debt
+      Get a grip on your technical debt
 email:
 - bglusman@shutterstock.com
 executables:
@@ -87,11 +101,10 @@ files:
 - examples/debt.rb.example
 - lib/debt_ceiling.rb
 - lib/debt_ceiling/debt.rb
-- lib/debt_ceiling/enforcement.rb
 - lib/debt_ceiling/version.rb
 - test/debt_ceiling_test.rb
 - test/test_helper.rb
-homepage: https://github.com/bglusman/DebtCeiling
+homepage: https://github.com/bglusman/debt_ceiling
 licenses: []
 metadata: {}
 post_install_message: 

data/lib/debt_ceiling/enforcement.rb

@@ -1,25 +0,0 @@
-require 'rubycritic'
-require 'ostruct'
-module DebtCeiling
-  class Enforcement
-    class << self
-      attr_reader :rules
-      def add(rule)
-        @rules ||= []
-        @rules << rule
-      end
-
-      def process_directory(path, output=:destructured)
-        modules = Rubycritic::Orchestrator.new.critique([path])
-        debts = modules.map do |mod| 
-          file_attributes = OpenStruct.new
-          file_attributes.linecount = `wc -l #{mod.path}`.match(/\d+/)[0].to_i
-          file_attributes.path = mod.path
-          file_attributes.analyzed_module = mod
-          debt_rule = Debt.new(file_attributes)
-        end
-        puts "Current total tech debt: #{debts.map(&:to_i).reduce(&:+)}"
-      end
-    end
-  end
-end