banalize 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8a4e26483ea5692063efa9d08adb90fcbc552243
+  data.tar.gz: 1225cf15d13b89501f0d6bf2cdff359f2927bcf6
+SHA512:
+  metadata.gz: 0ac7bff7e15664f2beb9aa862c539451f8dab4531346abfca0d1f4fff5f13c7769666440c24e50c792f10aedaeb7bedf7d8b1c41d92cb53a917c812a65abef95
+  data.tar.gz: 940407208055587056763facf1b72c5720a5933f35cc01284e0d54e6d84bf54259b279ae2fea15202ee44e8c9a3bc5c3f7c0947bb697a8288cbb68f62fc7b146

data/PARSER.md

@@ -0,0 +1,43 @@
+
+![banalize](images/banalize_small.png)
+
+Parser architecture
+===========
+
+Class Parser
+-----------
+
+Bash basic parser defines following methods:
+
+- {Banalize::Parser#shebang} - first line of the script if it's in `#!` format or nil
+- {Banalize::Parser#comments} - all block comments of the file, excluding shebang line
+- {Banalize::Parser#code} - all non-comments of the script, excluding shebang line
+
+
+All data returned by parser methods are instances of {Banalize::Numbered} class, i.e. they are lines of code with corresponing line number in the script file.
+
+Class Numbered
+----------------------
+
+Class {Banalize::Numbered} provides some helper methods to make searches simpler in the script files:
+
+- {Banalize::Numbered#grep}
+
+  Find and return lines matching regular expresion.
+
+- {Banalize::Numbered#has?}  Aliased to {Banalize::Numbered#have?}.
+
+  Search for pattern in all lines, return true or false
+  
+- {Banalize::Numbered#does\_not\_have?} Alias {Banalize::Numbered#dont_have?}
+  
+  Opposite for the above method. Return true if pattern in not found.
+
+- {Banalize::Numbered#search} - attribute accessor. It always contains result of the last grep search.
+- {Banalize::Numbered#lines} 
+- {Banalize::Numbered#to_s} (alias: {Banalize::Numbered#inspect})
+
+Additional parsers
+===========
+
+Will be added in the future.

data/README.md

@@ -0,0 +1,168 @@
+[![Wizcorp](images/wizcorp-logo.png)](http://wizcorp.jp)
+
+**Note** See formatted documentation at http://wizcorp.github.com/Banalize
+
+Name
+===========
+
+Banalize - static code analyzer for Bash
+
+![banalize](images/banalize.png)
+
+Version {include:file:version.txt}
+-----------
+
+Description
+===========
+
+Banalizer is syntax analyzer for bash scripts. It is modelled after ideas of [`Perl::Critic`](http://en.wikipedia.org/wiki/Perl::Critic) static analyzer for Perl. Most of the Banalizer is written in Ruby. Exception is policy files which are language agnostic, and can be written in any language: scripting or compiled.
+
+Banalizer consists of main binary file, banalyzer libraries, command line interface (CLI) and policies. 
+
+Policy is requirement for bash script/file. For example: each script must have 'shebang' as first line.
+
+Each policy is implemented as Ruby or other programming/scripting language file able to perform single check on single bash script file. Rest - aggregating checks, reporting, filtering etc - is handled by Banalizer.
+
+### Severity
+
+From [`Perl::Critic`](http://perlcritic.tigris.org/) page:
+
+> severity is the level of importance you wish to assign to the Policy. All Policy modules are defined with a default severity value ranging from 1 (least severe) to 5 (most severe). However, you may disagree with the default severity and choose to give it a higher or lower severity, based on your own coding philosophy. You can set the severity to an integer from 1 to 5, or use one of the equivalent names:
+>
+>      SEVERITY NAME ...is equivalent to... SEVERITY NUMBER
+>      ----------------------------------------------------
+>      gentle                                             5
+>      stern                                              4
+>      harsh                                              3
+>      cruel                                              2
+>      brutal                                             1
+>
+
+### Policy style
+
+Banalizer's policy style more or less correspond to `Perl::Critic`'s policy theme with exclusion of Perl specific themes. Again quote from `Perl::Critic`:
+
+
+>        THEME             DESCRIPTION
+>        --------------------------------------------------------------------------
+>        core              All policies that ship with Perl::Critic
+>        pbp               Policies that come directly from "Perl Best Practices"
+>        bugs              Policies that that prevent or reveal bugs
+>        maintenance       Policies that affect the long-term health of the code
+>        cosmetic          Policies that only have a superficial effect
+>        complexity        Policies that specificaly relate to code complexity
+>        security          Policies that relate to security issues
+>        tests             Policies that are specific to test scripts
+>   
+
+See http://perlcritic.tigris.org/#THE%20POLICIES
+
+Conventions
+===========
+
+Policies
+-----------
+
+- All policies (policy files) installed in `./lib/policies` and users home `~/.banalize/policies` directories. 
+
+- There are two classes of policies recognized by Banalizer: Ruby and _'other'_
+- Ruby policy files detected by `.rb` extension. Files without `.rb` extension are considered to be 'others'
+- Policy name is detected from
+  - file name of 'other' policy
+  - first argument for `banalizer` method for Ruby policy
+- all names should be unique, or they will be overwritten
+
+### Attributes
+
+All policies have these attributes:
+
+- policy (i.e. name)
+- synopsis
+- description
+- severity
+- style
+
+Depending on the type of policy some of the attributes are required, some optional or can be set to reasonable default.
+
+### Non-ruby policies (i.e. others)
+
+Policy should conform to few rules:
+
+1. it must return information about itself when called with parameter `config`
+  - Output of the `config` command is YAML formatted text
+    - Command returns attributes names and values of the policy
+    - All attributes in case of 'other' policy are optional
+
+      They are either set to default values if missing, or detected from other meta-data (like, for example, name of a policy is `$(basename file)` of policy file.
+2. Policy script must be able to perform single (syntax/semantic/format) check on bash script file and:
+  - return non-zero status if check fails or 0 if succeeds
+  - return (optional) error massages on STDOUT
+
+    **Note**: Only STDOUT is honored by Banalizer. 
+    
+    If your check command, for example, prints to STDERR but not to STDOUT, you'd need to redirect shell streams accordingly.
+
+#### Example config section
+
+```yaml
+    ---
+    name: $(basename $0)
+    style: 
+      - :bug
+      - :test
+    severity: 5
+    description: Runs bash syntax check using 'bash -n' option
+```
+
+### Ruby policy
+
+1. Ruby policy has two required items: 
+   - name  (_Note_: to avoid clashes with Ruby standard `name` method we use `policy` DSL method)
+   - must define method called `run`
+1. Policy is defined in top-level namespace's method called `banalizer`
+   - name is string or Ruby symbol parameter to `banalizer` method
+   - additional (optional) attributes are defined as DSL methods calls inside block given to `banalizer` method
+   - run method is defined in the same block
+1. DSL methods names correspond to policy attributes :
+   - policy (i.e. policy name)
+   - synopsis
+   - description
+   - style
+   - severity
+1. `run` method :
+   - need to return result of a check as something that can be evaluated into true or false
+   - optionally can pass along error messages from the check, using `errors.add` DSL method to populate errors object (instance of {Banalize::Errors} class
+1. Additionally Ruby policies have DSL method `default`. It sets default values for variables, that can be overridden by personal style configuration file ( See {file:CONFIGURATION.md}).
+
+#### Examples
+
+This is full working example of Ruby DSL policy:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ruby
+banalizer :shebang_format do
+  
+  synopsis    'Format of shebang should be #!/usr/bin/env bash'
+  severity    5
+
+  def run
+    unless shebang.has?(%r{\#!/usr/bin/env\s+bash})
+
+      errors.add "First line is not in the format #!/usr/bin/env bash", 1
+      return false
+    end
+  end
+
+end
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to use filename of Ruby policy as its name, do this:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ruby
+banalizer File.basename(__FILE__, '.rb').to_sym do
+
+end
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+<!--  LocalWords:  banalize
+ -->

data/bin/banalize

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+
+require 'banalize'
+
+include         GLI::App
+commands_from   "commands"
+version         Banalize::VERSION
+config_file     Banalize::USER[:config]
+program_desc    <<-EOF 
+
+Banalize is Bash files static code analyzer. It runs each policy
+corresponding to the required level of test severity and policies. 
+
+Policies are Ruby or other programming languages (Bash, perl)
+executable scripts located in `lib/policies` directories.
+
+EOF
+
+
+
+flag   [:group,    :g],    :desc => 'Use only policies included in specified group'
+flag   [:severity, :s],    :desc => 'Use only policies of specified severity and above'
+flag   [:policy,   :p],    :desc => 'Apply single policy only (by name)'
+flag   [:style,    :S],    :desc => 'Use custom style file instead of default one.',
+                           :default_value => Banalize::USER[:styles]
+
+switch [:color,    :c],    :desc => "Use colored output"
+
+pre do |global,command,options,args|
+
+  $color = true if global[:color]
+
+  #
+  # Load styles file. Styles override defaults defined in policies.
+  #
+  $styles = if global[:style] != Banalize::USER[:styles] || 
+                File.exist?(File.expand_path(Banalize::USER[:styles]))
+              begin
+                YAML.load_file global[:style]
+              rescue Banalize::BanalizeError => e
+                abort "#{e.class} error: Can not load styles file #{e.message}"
+              end
+
+            end
+
+  search = { }
+
+  if global[:policy]
+    search = global[:policy]
+  else
+    search.merge!({ :policy   => global[:group]         }) if global[:group]
+    search.merge!({ :severity => global[:severity].to_i }) if global[:severity]
+  end
+
+  $search   = search
+  $policies = Banalize::Policy.search search 
+
+  # - results of checks
+  # - count of failed checks
+  # - total count of checks
+  $res, $status, $total = { }, 0, 0
+  true
+end
+
+post do |global,command,options,args|
+  #
+  # output results of the check
+  #
+  unless $res.empty?
+
+    if options[:dots]
+      dots = ''
+      $res.each do |file,res|
+        $total += res.count
+        res.each do |k,v|
+          dots << (v[:status] ? '.' : "F".color(:red))
+          $status += 1 unless v[:status]
+        end
+      end
+      puts dots
+
+    else
+      out = { }
+      $res.each do |file,res|
+
+        failure = res.select { |k,v| !v[:status] }
+
+        # Ignore all other keys, only bring messages up. If no errors
+        # switch is set. only list empty policy names
+        failure.map do |k,v|
+          failure[k] = options[:errors] ? v[:messages]  : nil
+        end
+
+        out[file] = { "Fail" => failure } unless failure.empty?
+
+        if options[:all]
+          out[file] ||= {} 
+          out[file].merge!({ "Success" => res.keys.select { |k| res[k][:status] } }) 
+        end
+
+        $total  += res.count
+        $status += failure.count
+      end
+
+      print ::Banalize.beautify(out)
+    end
+    
+    puts "\n#{$res.count} files, #{$total.to_s} checks, #{$status.to_s} failed"
+  end
+
+  $status
+end
+
+on_error do |exception|
+  exit_now! exception.message unless exception.is_a? GLI::BadCommandLine
+  true
+end
+
+exit run(ARGV) && $status == 0
+

data/lib/banalize.rb

@@ -0,0 +1,64 @@
+$: << File.dirname(__FILE__)
+
+require 'gli'
+require 'mash'
+require 'active_support/inflector'
+require 'active_support/core_ext'
+
+# Order is not important, load all of them
+Dir.glob("#{File.dirname(__FILE__)}/{core_extensions,helpers}/*.rb").each do |r|
+  require r
+end
+
+##
+# This is shamelessly stolen form Rspec::DSL. Inject method `policy`
+# into the top level namespace, so the we can use in policy definition
+# without need to define class inheritance.
+#
+# Registerd policies are listed in `@@policies` array.
+#
+module Banalize
+  ROOT      = File.dirname(File.dirname(__FILE__))
+  VERSION   = File.read(ROOT+'/version.txt').chomp.strip
+
+  # Local user directory with banalize config and policies
+  
+  dot_banalize = "#{Dir.home}/.banalize"
+
+  USER = {
+    dot_banalize: dot_banalize,
+    config:       "#{dot_banalize}/config", # Default user config file
+    styles:       "#{dot_banalize}/style",  # Default style file
+    policies:     "#{dot_banalize}/policies"
+  }
+
+  # Truncate long error lines
+  TRUNCATE  = ENV["BANALIZE_TRUNCATE_LINES"] == 'false' ? nil : 60
+
+  module DSL
+    @@policies = []
+    def banalizer my_name, &block
+      klass = Banalize::Registry.register(my_name, &block)
+      @@policies  << klass
+      klass
+    end
+
+    def policies
+      @@policies
+    end
+  end
+end
+
+include Banalize::DSL
+
+require 'banalize/parser/numbered'
+require 'banalize/parser'
+require 'banalize/exception'
+require 'banalize/registry'
+
+require 'banalize/errors'
+require 'banalize/policy/severity'
+require 'banalize/policy'
+require 'banalize/files'
+require 'banalize/runner'
+

data/lib/banalize/errors.rb

@@ -0,0 +1,43 @@
+module Banalize
+  ##
+  # Errors class provides stograge of error messages while running policy checks. 
+  class Errors
+
+    def initialize klass
+      @klass = klass
+      @messages = []
+    end
+
+    attr_accessor :messages
+
+    def add message, line=nil
+      @messages << { :message => message, :line => line }
+    end
+    
+    ##
+    # Retrun true if there are no errors
+    def empty?
+      @messages.empty?
+    end
+
+    ##
+    # Retrun true if there are any errors
+    #
+    def any?
+      ! empty?
+    end
+
+
+    ##
+    # Convert Array of Hashes of error messages into readable form
+    #
+    def self.to_s messages=[]
+      return '' if messages.empty?
+
+      messages.map do |err|
+        "#{err[:message]}#{err[:line] ? ", on line #{err[:line]}" : ''}"
+      end
+    end
+    
+  end
+end