Purpose
=======

Source files which were commited frequently and had high complexity are risky item to be reviewed and/or refactored.

See also: http://www.stickyminds.com/sitewide.asp?Function=edetail&ObjectType=COL&ObjectId=16679

Prerequisite
============

   * Perl > 5.x
   * Python > 2.6
      * pandas module: http://pandas.pydata.org/pandas-docs/stable/install.html
      * lxml module  : http://lxml.de/installation.html
      * pygal module : http://pygal.org/download/
   * Scitools Understand >= 3.1 above (build >= 676)

PATH environment should include the directory path where 'und' and 'perl' executable exists

Component(s)
============

   * run.batch.at.sh              // batch file for large project
   * list.all.repos.from.sh       // listing all git repos 
   * scan.all.repos.at.pl         // perl version (listing.all.repos.from.sh) 
   * gather.all.repos.from.sh     // execute churn.ccn.analyzer.pl for each git

   * churn.ccn.analyzer.pl   // main script (calls und.file.complexity.pl)
   * und.file.complexity.pl  // by using understand CLI, to get loc and complelxity

Instruction
============

1. For analyzing single git

Get modified files from specific date range and Acquire complexity of each file by using Scitools' Understand. Then export csv files 'file_churn_complexity.csv' which sorted by churn (commits) and file complexity descending order.

  Usage
  =====

   $ churn.ccn.analyzer.pl [git path] [language] [since]

      - git path    directory path of target git repository

      - language    supported langauges: c++, java, web

                    * c++ : C/C++ language
                    * java: Java language
                    * web : javascript, php, css, html

                    you can use compound form: "c++", "java", "c++ java web"

      - since       (optional) you can designate specific starting date, not whole history

  Examples
  ========

   $ churn.ccn.analyzer.pl junit "java" 
   $ churn.ccn.analyzer.pl git "c++" "one month ago"
   $ churn.ccn.analyzer.pl junit "java" "2013-12-01"

  Output
  ======

  Result will be stored at the 'churn-complexity-output' directory.

      * file_churn_complexity.csv
        - filename
        - commits (churn)
        - file complexity
        - number of function
        - function name which has max cyclomatic complexity in the file
        - max cyclomatic complexity
     * file_churn_complexity_functions.csv
        - filename (line position)
        - function name
        - cyclomatic complexity ('Cyclomatic' metric)
        - sloc ('CountLineCode' metric)

2. For large project which has multiple sub git repositories

Scan all git repositories of project and Run 'churn.ccn.analyzer.pl' script onto each git repository. Gather all 'file_churn_complexity.csv' and sorted by churn (commits) and file complexity descending order. Export top risky items to be reviewed or refactored to 'top_20_risk_files(file).csv'.

  Usage
  =====

   $ run.batch.at.sh [top path of project] [criteria] [limit]

      - top path    directory path of target project

      - criteria    (optional) supported options: file, max

                    * file: sorted by file complexity
                    * max : sorted by max function complexity

                    default criteria is 'file'

      - limit       (optional) how many items filtered out (default 20)

  Examples
  ========

   $ run.batch.at.sh ~/he/wall/ file 10
   $ run.batch.at.sh ~/mc/lgapps/ max

  Output
  ======

     * top_20_risk_files(file).csv
        - repo_name
        - filename
        - commits (churn)
        - file complexity
        - avg complexity
     * top_20_risk_files(max).csv
        - repo_name
        - filename
        - function name
        - commits (churn)
        - function complexity
        - file complexity
        - avg complexity

---

cf) File complexity is calculated as followed:

   (Sum of complexity of all function in the file) - (number of function in the file) + 1