notes-cli 1.1.0 → 2.0.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    NDVlYWYwYTAwMGM0ZDVmMTlkMTYzOTFkZGM4NDk2NDRkYTgxMzIwMQ==
-  data.tar.gz: !binary |-
-    ZTY5ZGIxZjFhNDYxMzYxNmJlYTZjMWI2YWYxNDFkNjZkOTc3OGY1Yw==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    MGQ4NTExODhiZmYwYTk1NjI5N2JmMzRmYTFjMGI1YzdmOWVhZTQwYTg1NDMz
-    ZjgyMTI4ZTgxN2U5MTY4NzNkOWMyODMwODkwYTM2NDkyYjcyZjYzZGU2YjUx
-    MTgxZTEzZjk4YzI0MTUzY2Y1NzcxOGQyMDgxMTBlMTgyYTUyYzY=
-  data.tar.gz: !binary |-
-    YTIwZjcwOGZjYTQyZTlhYjBkNGVlNmZlOTcwZDZhZDU3NmJhZjlhNmY5Y2Ri
-    MzQ5YzE0Y2U4ZmQ0YjU2YWEwYzQ1ZWUxYTUzNDU5NTQzOWY5YjYwNDA2ZWZm
-    ZjI2MzVkYzNlMWQ5MzQ5YWVkMGMzNWFjMDc5MjdjN2M2NWExZTk=
+SHA1:
+  metadata.gz: 8226fe40296b703c5bfd3e60e83ef9cb29bc4a18
+  data.tar.gz: 1a01f8184c299f371ba8e1483214981a5da02184
+SHA512:
+  metadata.gz: 78a371528ef86d9288193d841b06810a17162f8a55573ad5962fc313b8d1460eaa1333fb65a89f34acfca11c2450484c161ad1b487daed2badcacf8cc2240ac6
+  data.tar.gz: 8bcfa278c5f87e1e2eca7f741e9151176fd13c5cadbd1391a634fb0f028e3ca730f25c815cd36764500da5e4300417808d6495d98840bc5862b62963b0c30b18

data/.gitignore

@@ -0,0 +1,44 @@
+# Numerous always-ignore extensions
+*.diff
+*.err
+*.orig
+*.log
+*.rej
+*.swo
+*.swp
+*.vi
+*~
+*.sass-cache
+
+# OS or Editor folders
+.DS_Store
+.cache
+.project
+.settings
+.tmproj
+nbproject
+Thumbs.db
+
+# Dreamweaver added files
+_notes
+dwsync.xml
+
+# Komodo
+*.komodoproject
+.komodotools
+
+# Folders to ignore
+.hg
+.svn
+.CVS
+intermediate
+publish
+.idea
+.bundle
+db/*.sqlite3
+log/*.log
+tmp/
+.sass-cache/
+dump.rdb
+*.gem
+Makefile

data/.ruby-gemset

@@ -0,0 +1 @@
+notes-cli

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in sourcing.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright © 2013 Andrew Berls, http://andrewberls.com/
+
+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:
+
+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/README.md

@@ -0,0 +1,71 @@
+## Notes - A tool for managing source code annotations
+
+Notes is a tool for tracking source code annotations such as TODO or FIXME. A command-line interface searches files
+in a directory and prints annotations, while a web interface provides visualization and filtering tools.
+
+
+Default annotations searched for are: __TODO__, __FIXME__, and __OPTIMIZE__. Custom annotations or directories to ignore (such as log directories) can be specified with command-line arguments, detailed further.
+
+
+### INSTALLATION:
+`gem install notes-cli`
+
+This will install the `notes` executable on your system.
+
+## Using the web interface
+
+Notes ships with a web interface for displaying and filtering annotations. It can be run as a standalone server, 
+or mounted as a Rack endpoint within another application (e.g., a Rails app)
+
+![](https://dl.dropboxusercontent.com/u/7949088/notes-cli/notes-web2.png)
+
+### As a standalone server:
+
+Once the gem is installed, you can start a server with the `notes server` command, run from the directory
+you wish to search in. The port can be customized with the `-p` flag (e.g. `notes server -p 8000`). 
+The default port is 9292.
+
+### Mounted in a Rails application:
+
+Notes can expose its web interface as part of a host application. First, add `notes-cli` as a dependency in your Gemfile and run `bundle install`. Next, add the following to `config/routes.rb`:
+
+```ruby
+require 'notes-cli/web'
+
+mount Notes::Web => '/notes'
+```
+
+Now, after starting a server normally, you can browse to `'/notes'` (or whichever URL you chose) in your application
+to access the web interface.
+
+
+## Using the CLI
+
+Usage: `notes [DIRECTORY=. | FILES=<...>] [-f FLAGS] [-e EXCLUDES]`
+
+### OPTIONS:
+```
+-f, --flags    # List of custom annotations, ex: '-f broken refactor' (case insensitive)
+-e, --exclude  # List of directories to ignore, ex: '-e tmp/ log/'
+-h, --help     # Display the help menu
+```
+
+### EXAMPLES:
+```
+notes                 # Show default annotations for all files in current directory (default)
+notes app/ -f broken  # Only examine files in the app/ directory and add the 'broken' flag
+notes -e tmp/ log/    # Ignore any files in tmp/ or log/
+notes one.rb two.rb   # Show default annotations for one.rb and two.rb
+```
+
+A sample run might look like the following:
+```
+$ notes src/ -f failing
+
+app/models/user.rb:
+  ln 2: # TODO: Condense this eventually
+  ln 34: # OPTIMIZE: This can be prettier
+
+test/unit/group.rb
+  ln 72: # FAILING
+```

data/bin/notes

@@ -2,6 +2,11 @@
 
 require 'notes-cli'
 
+if ARGV.any? { |arg| ["-v", "--version"].include?(arg) }
+  puts Notes::VERSION
+  exit
+end
+
 if ARGV.any? { |arg| ["-h", "--help"].include?(arg) }
   puts %Q{\
 Recursively search source files for annotations. Default annotations are TODO, OPTIMIZE, and FIXME.
@@ -12,6 +17,7 @@ Options:
   -f, --flags    # List of custom annotations, ex: '-f broken refactor' (case insensitive)
   -e, --exclude  # List of directories to ignore, ex: '-e tmp/ log/'
   -h, --help     # Display this menu
+  -v, --version  # Display the currently installed version
 
 Examples:
   notes                 # Show default annotations for all files in current directory (default)
@@ -19,8 +25,18 @@ Examples:
   notes app/ -e logs/   # Show default annotations for files in app/ directory, excluding files in logs/
   notes one.rb two.rb   # Show default annotations for one.rb and two.rb
 
+You can also start a standalone server for the web interface with `notes server`
+The default port is 9292.
+
+Server options:
+  -p, --port  # Set the port to run on, ex: `notes server -p 3000`
+
 }
   exit(0)
 end
 
-Notes::CLI.new.find_all
+if ARGV.first == 'server'
+  Notes::Server.new(ARGV).start
+else
+  Notes::CLI.new(ARGV).find_all
+end

data/config.ru

@@ -0,0 +1,4 @@
+require File.expand_path('../lib/notes-cli', __FILE__)
+require File.expand_path('../lib/notes-cli/web', __FILE__)
+
+run Notes::Web

data/lib/notes-cli.rb

@@ -1,2 +1,112 @@
-require 'notes-cli/opts'
+module Notes
+  extend self
+
+  # The root directory in which we're searching
+  def root
+    defined?(Rails) ? Rails.root : Dir.pwd
+  end
+
+  # Are we being included into a Rails project?
+  #
+  # TODO: this is pretty hacky but we can't rely on the definition
+  # of the Rails constant from the CLI and it works on both 3 & 4
+  def rails?
+    path = root.to_s + '/config/application.rb'
+    return false unless File.exists?(path)
+    File.read(path).include?('Rails::Application')
+  end
+
+  # Are we in a git repo?
+  def git?
+    Dir.chdir(root) do
+      `git status 2>/dev/null`
+      return $?.success?
+    end
+  end
+
+  # Convert a filename to a relative path
+  #
+  # filename - String
+  #
+  # Ex:
+  #   shortname("/Users/andrew/code/notes-cli/bin/notes")
+  #   => "bin/notes"
+  #
+  # Returns String
+  def shortname(filename)
+    filename.gsub(Dir.pwd, '').gsub(/^\//, '')
+  end
+
+  # Parse raw output from git-blame(1)
+  # (results not interpreted except for SHA)
+  #
+  # Returns Hash
+  def blame(filename, line_num)
+    fields = {}
+
+    begin
+      Dir.chdir(root) do
+        blame = `git blame -L#{line_num},#{line_num} --line-porcelain -- #{filename} 2>/dev/null`.split("\n")
+        sha = blame.shift.split(' ').first
+        fields['sha'] = sha if sha != '0'*40 # Only use actual commit SHAs
+
+        blame.each do |line|
+          fieldname, *values = line.split(' ')
+          fields[fieldname]  = values.join(' ')
+        end
+      end
+    rescue
+    end
+
+    fields
+  end
+
+  COLORS = {
+    'yellow' => 33
+  }
+
+  def colorize(color, str)
+    "\e[#{COLORS[color]};1m#{str}\033[0m"
+  end
+
+  # Determine if a file handle should be rejected based on type and
+  # directories specified in options[:exclude]
+  #
+  # excluded - Array of directories to exclude from search
+  # f - A String filename
+  #
+  # Return Boolean
+  def is_directory_or_excluded?(excluded, f)
+    is_in_excluded_dir = excluded.any? { |dir| File.dirname(f).include?(dir) }
+    File.directory?(f) || is_in_excluded_dir
+  end
+
+  # Return an array of valid filenames for parsing
+  #
+  # options
+  #   :locations - Array of files and directories to search
+  #   :exclude   - Array of directories to exclude from search
+  #
+  # Return Array<String>
+  def valid_files(options)
+    locations = options[:locations]
+    excluded  = options[:exclude]
+
+    locations.flat_map do |loc|
+      if File.directory?(loc)
+        Dir[ File.join(loc, "**/*") ]
+          .reject do |f| is_directory_or_excluded?(excluded, f) end
+      else
+        loc
+      end
+    end
+  end
+
+end
+
+require 'notes-cli/version'
+require 'notes-cli/options'
+require 'notes-cli/tasks'
+require 'notes-cli/stats'
 require 'notes-cli/cli'
+require 'notes-cli/server'

data/lib/notes-cli/cli.rb

@@ -1,62 +1,20 @@
-
 module Notes
   class CLI
-    attr_accessor :options
-
-    def initialize
-      @options = Opts.parse(ARGV)
-    end
-
-    # Print a formatted task, with highlighting
-    def print_task(task)
-      flag_regex = Regexp.new(@options[:flags].join('|'), true)
-      color = 33 # yellow
-      line  = task[:line].gsub(flag_regex) do |flag|
-        "\e[#{color};1m#{flag}\033[0m"
-      end
-
-      puts "  ln #{task[:line_num]}: #{line}"
-    end
-
-    # Scan a file for annotations and output numbered lines for each
-    def parse_file(filename)
-      name    = filename.gsub(Dir.pwd, '')
-      counter = 1
-      tasks   = []
-
-      begin
-        File.read(filename).each_line do |line|
-          if @options[:flags].any? { |flag| line =~ /#{flag}/i }
-            tasks << {
-              :line_num => counter,
-              :line     => line.strip
-            }
-          end
-          counter += 1
-        end
-      rescue
-        # Error occurred reading the file (ex. invalid byte sequence in UTF-8)
-        # Move on quietly
-      end
 
-      if !tasks.empty?
-        name.slice!(0) if name.start_with?("/")
-        puts "#{name}:"
-        tasks.each { |t| print_task(t) }
-        puts ""
-      end
+    def initialize(argv)
+      @options = Notes::Options.parse(argv)
     end
 
     # Read and parse all files as specified in the options
+    # Prints filenames along with all tasks found per file
+    # Only outputs to console; returns nothing
     def find_all
-      @options[:locations].each do |loc|
-        if File.directory?(loc)
-          Dir[ File.join(loc, "**/*") ].reject do |f|
-            File.directory?(f) || @options[:exclude].any? { |dir| File.dirname(f).include?(dir) }
-          end.each { |f| parse_file(f) }
-        else
-          parse_file(loc)
-        end
+      task_map = Notes::Tasks.all(@options).group_by(&:filename)
+
+      task_map.each do |filename, tasks|
+        puts "#{filename}:"
+        tasks.each { |task| puts '  ' + task.to_s }
+        puts ''
       end
     end
 

data/lib/notes-cli/{opts.rb → options.rb}

@@ -1,5 +1,8 @@
+# Internal options parser
+
 module Notes
-  module Opts
+  module Options
+    extend self
 
     DEFAULT_OPTIONS = {
       :flags     => %w(TODO FIXME OPTIMIZE),
@@ -12,17 +15,25 @@ module Notes
     EXCLUDE_FLAGS = ['-e', '--exclude']
     ALL_FLAGS     = FLAG_FLAGS + EXCLUDE_FLAGS
 
+    def default_excludes
+      if Notes.rails?
+        %w(tmp log)
+      else
+        []
+      end
+    end
+
     # Parse ARGV into a directory and list of argument groups
     # For example, given ['app/', -f', 'refactor', 'broken', '--exclude', 'tmp', 'log']:
     # => [ ['app/'], ['-f', 'refactor', 'broken'], ['--exclude', 'tmp', 'log'] ]
     #
-    def self.arg_groups(args)
+    def arg_groups(args)
       result = []
       buf    = []
 
-      # No dir was passed, use current dir
+      # No dir was passed, use default
       if args.empty? || args.first.start_with?('-')
-        result << [ Dir.pwd ]
+        result << [ Notes.root ]
       end
 
       args.each do |arg|
@@ -36,11 +47,12 @@ module Notes
       result << buf
     end
 
-    # Append any command line arguments to a default set of arguments
-    def self.parse(args)
+    # Append received command line arguments to a default set of arguments
+    # Returns Hash
+    def parse(args)
       arg_list = arg_groups(args)
-      options  = DEFAULT_OPTIONS
-
+      options  = DEFAULT_OPTIONS.dup
+      options[:exclude] += default_excludes
       options[:locations] = arg_list.shift
 
       arg_list.reject(&:empty?).each do |set|
@@ -48,8 +60,8 @@ module Notes
         args.map! { |arg| arg.delete("/") } # "log/" => "log"
 
         case flag
-        when '-f', '--flags'   then options[:flags].concat(args)
-        when '-e', '--exclude' then options[:exclude].concat(args)
+        when '-f', '--flags'   then options[:flags] += args
+        when '-e', '--exclude' then options[:exclude] += args
         else puts "Unknown argument: #{flag}"
         end
       end
@@ -57,5 +69,10 @@ module Notes
       options
     end
 
+    # Return the default set of flags and locations
+    def defaults
+      parse({})
+    end
+
   end
 end