tps_reporter 0.0.2

data/HISTORY.md

@@ -0,0 +1,4 @@
+v0.0.2 - Feb 04, 2012
+---------------------
+
+Initial.

data/README.md

@@ -0,0 +1,86 @@
+# Task progress sheet reporter
+
+![TPS report](https://img.skitch.com/20120203-nr24dn9u7euchmqa516718unpe.png)
+
+We often need to make regular reports of things done for our projects at work. I
+hate doing these by hand. This tool lets us build these reports from YAML files.
+
+Get started
+-----------
+
+Install TPS (Ruby):
+
+    $ gem install tps_reporter
+
+...then generate a sample file. (or create `tasks.yml` based on [this][s]
+sample.)
+
+    $ tps sample
+
+Edit it, then generate the report:
+
+    $ tps open
+
+[s]: https://github.com/rstacruz/tps_reporter/blob/master/data/sample.yml
+
+Format
+------
+
+The tasks file, usually `tasks.yml`, is in YAML format.
+
+Tasks are always keys (ie, they all end in `:`). They can be nested as far
+as you like.
+
+``` yaml
+Edit users:
+  Register and signup:
+  Login and logout:
+```
+
+To define task metadata for *leaf* tasks, add it as an array inside the task:
+
+``` yaml
+Manage employees: [done]
+```
+
+Or for *branch* tasks, add it under the `_` task:
+
+``` yaml
+Manage employees:
+  _: [done]
+  Creating employees:
+  Editing employees:
+```
+
+The metadata is just a simple YAML array that you can conveniently define using
+`[tag1, tag2, etc]`.  Allowed metadata are:
+
+ - `done`
+ - `in progress`
+ - `pt/2839478` *(Pivotal tracker ID. Links to a Pivotal tracker story.)*
+ - `0pt` *(points; influences percentage. needs to end in __pt__ or __pts__.)*
+ - `10%` *(task progress. implies __in progress__.)*
+
+Example:
+
+``` yaml
+  Creating employees: [40%]
+  Editing employees: [done, 2pts]
+```
+
+Exporting to PDF or image
+-------------------------
+
+If you're on a Mac, install [Paparazzi](http://derailer.org/paparazzi)
+and use the `tps paparazzi` command. This will open the report in Paparazzi
+where you can save or copy it as an image, or PDF.
+
+Command line
+------------
+
+There's also a command line reporter that you can access via `tps print`. It
+looks like this:
+
+![Comamnd line reporter][cli]
+
+[cli]: https://img.skitch.com/20120204-ccb2guerhrjmj3rht3e4ies4ur.png

data/Rakefile

@@ -0,0 +1,14 @@
+desc "Invokes the test suite in multiple RVM environments"
+task :'test!' do
+  # Override this by adding RVM_TEST_ENVS=".." in .rvmrc
+  envs = ENV['RVM_TEST_ENVS'] || '1.9.2@sinatra,1.8.7@sinatra'
+  puts "* Testing in the following RVM environments: #{envs.gsub(',', ', ')}"
+  system "rvm #{envs} rake test" or abort
+end
+
+desc "Runs tests"
+task :test do
+  Dir['test/*_test.rb'].each { |f| load f }
+end
+
+task :default => :test

data/bin/tps

@@ -0,0 +1,145 @@
+#!/usr/bin/env ruby
+$:.unshift File.expand_path('../../lib', __FILE__)
+require 'tps'
+
+module Params
+  def extract(what)   i = index(what) and slice!(i, 2)[1] end;
+  def first_is(what)  shift  if first == what; end
+end
+
+ARGV.extend Params
+
+module TPS::Command
+  extend self
+
+  def help
+    puts "Usage: tps <command> [-f filename] [-o output]"
+    puts ""
+    puts "Commands:"
+    puts "   html                 Builds HTML"
+    puts "   open                 Builds HTML and opens it in the browser"
+    puts "   paparazzi            Builds HTML and opens it in Paparazzi (Mac)"
+    puts "   print                Prints the report to the console."
+    puts ""
+    puts "Options (optional):"
+    puts "  -f FILE               Specifies the input file. Defaults to tasks.yml."
+    puts "  -o/--output OUTPUT    Specifies the output HTML file."
+    puts ""
+  end
+
+  def html
+    t = get_tasks
+    path = output { |file| file.write t.to_html }
+    info "Wrote to '#{path}'."
+
+    path
+  end
+
+  def sample
+    require 'fileutils'
+    fn = tasks_filename
+
+    if File.exists?(fn)
+      err "Error: #{fn} already exists."
+      exit 130
+    end
+
+    FileUtils.cp TPS.root('data', 'sample.yml'), fn
+    info "Created '#{fn}'."
+    info "Edit it, then use `tps html` to generate HTML from it."
+  end
+
+  def open
+    fn = html
+    open_file fn
+  end
+
+  def paparazzi
+    fn = html
+    open_file "paparazzi:(minwidth=1,minheight=1)#{fn}"
+  end
+
+  def print
+    t = get_tasks
+    reporter = TPS::CliReporter.new(t)
+    reporter.print
+  end
+
+private
+  def err(str)
+    $stdout << "#{str}\n"
+  end
+
+  def info(str)
+    puts str
+  end
+
+  def tasks_filename
+    ARGV.extract('-f') ||
+    ENV['TPS_FILE'] ||
+    Dir['./{Tasksfile,tasks.yml}'].first ||
+    "tasks.yml"
+  end
+
+  def output(&blk)
+    fn = ARGV.extract('--output') || ARGV.extract('-o') || get_temp_filename
+
+    File.open(fn, 'w', &blk)
+    fn
+  end
+
+  def get_tasks
+    fn = tasks_filename
+    if !File.exists?(fn)
+      err "No tasks file found."
+      err "Create a sample using `tsp sample`."
+      exit 256
+    end
+
+    begin
+      TPS::TaskList.new yaml: fn
+    rescue => e
+      err "Parse error: #{e.message}"
+      exit 256
+    end
+  end
+
+  def opener
+    program = %w[open xdg-open start].detect { |cmd| `which #{cmd}` }
+    unless program
+      err "No opener found."
+      exit 256
+    end
+
+    program
+  end
+
+  def open_file(file)
+    require 'shellwords'
+    system "#{opener} #{file.shellescape}"
+  end
+
+  def get_temp_filename
+    require 'tmpdir'
+    File.join Dir.tmpdir, "tasks-#{'%x' % [rand * 2**48]}.html"
+  end
+end
+
+if ARGV.first_is('html')
+  TPS::Command.html
+
+elsif ARGV.first_is('open')
+  TPS::Command.open
+
+elsif ARGV.first_is('sample')
+  TPS::Command.sample
+
+elsif ARGV.first_is('print')
+  TPS::Command.print
+
+elsif ARGV.first_is('paparazzi')
+  TPS::Command.paparazzi
+
+else
+  TPS::Command.help
+end

data/data/index.haml

@@ -0,0 +1,182 @@
+!!! 5
+%html
+  %head
+    %script{src: "http://cdnjs.cloudflare.com/ajax/libs/jquery/1.7/jquery.min.js"}
+
+    :javascript
+      $("td").live('click', function() {
+        $(this).closest('tr').toggleClass('highlight');
+      });
+
+    %style
+      :plain
+        body {
+          padding: 0;
+          margin: 0; }
+
+        body, td {
+          font-family: pt sans, sans-serif;
+          color: #333;
+          line-height: 13.5pt;
+          font-size: 9pt; }
+
+        table {
+          border: solid 2px #aaa;
+          padding: 2px;
+
+          background: #fafafa;
+          margin: 0;
+          width: 600px;
+          border-collapse: collapse; }
+
+        table td, table th {
+          padding: 5px 10px;
+          border-top: solid 1px #eee; }
+
+        /* Columns */
+        tr>.task { width: 50%; text-align: left; }
+        tr>.points { width: 9%; }
+        tr>.progress { width: 18%; }
+        tr>.owner { display: none; }
+
+        /* Indentation */
+        .level-1 .task { padding-left: 25px; }
+        .level-2 .task { padding-left: 50px; }
+        .level-3 .task { padding-left: 75px; }
+        .level-4 .task { padding-left: 100px; }
+
+        /* Overrides for parents */
+        .milestone td.task,
+        .feature td.task {
+          font-weight: bold;
+          font-size: 1.1em; }
+
+        tr.milestone td,
+        tr.feature td {
+          border-top: solid 1px #888; }
+
+        tr .progress .bar {
+          display: none; }
+
+        tr.milestone .progress .bar,
+        tr.feature .progress .bar {
+          display: block; }
+
+        tr td.points>* {
+          display: none; }
+
+        tr.milestone td.points>*,
+        tr.feature td.points>* {
+          display: inline; }
+
+        /* Header */
+        thead {
+          display: none; }
+
+        th {
+          color: #888; }
+
+        /* Zebra */
+        tr td,
+        tr {
+          background: #ffffff; }
+
+        tr:nth-child(odd) td,
+        tr:nth-child(odd) {
+          background: #fafafa; }
+
+        tr.highlight,
+        tr.highlight td {
+          background: #fafae0; }
+
+        /* Status box */
+        span.status {
+          display: inline-block;
+          width: 12px;
+          height: 12px;
+          margin: 0 5px 0 0;
+
+          border-radius: 2px;
+
+          position: relative;
+          top: 2px;
+          background: #ddd; }
+
+        span.status.in_progress {
+          background: #ea3; }
+
+        span.status.done {
+          background: #393; }
+
+        /* Progress */
+        .progress .number {
+          display: none; }
+
+        .progress .bar {
+          height: 10px;
+          border-radius: 5px;
+          background: #ddd; }
+
+        .progress .bar span {
+          display: block;
+          height: 10px;
+          border-radius: 5px;
+          background: #888; }
+
+        a.meta {
+          font-size: 0.9em;
+          text-decoration: none;
+
+          background: #ddd;
+          padding: 1px 3px;
+          border-radius: 2px;
+          border-bottom: solid 1px #ccc;
+
+          margin: 0 5px;
+          color: #777; }
+
+        /* Progress */
+        td.points {
+          text-align: left;
+          font-size: 0.9em; }
+
+        td.points .points.done {
+          font-weight: bold; }
+
+        td.points .of,
+        td.points .points.total {
+          color: #888; }
+
+  %body
+
+    %table
+      %thead
+        %tr
+          %th.task Task
+          %th.owner Owner
+          %th.progress Progress
+          %th.points Points
+
+      - list.walk do |task, recurse|
+
+        %tr{class: "level-#{task.level} #{task.tasks? ? 'parent' : 'leaf'} #{'root' if task.root?} #{'feature' if task.feature?} #{'milestone' if task.milestone?}"}
+          %td.task
+            %span.status{class: "#{task.status}"}
+            = task
+            - if task.pivotal_id
+              %a.meta{href: task.pivotal_url}= "Pivotal: #{task.pivotal_id}"
+
+          %td.owner
+            = task.owner
+
+          %td.progress
+            .bar
+              %span{style: "width: #{(task.percent*95+5).to_i}%"}
+            %span.number= "#{(task.percent*100).to_i}%"
+
+          %td.points
+            %span.points.done= task.points_done.round(1).to_s.gsub(/\.0+$/,'')
+            %span.of of
+            %span.points.total= task.points.round(1).to_s.gsub(/\.0+$/,'')
+
+        - recurse.call  if recurse

data/data/sample.yml

@@ -0,0 +1,18 @@
+Version 1:
+
+  User signup:
+    Register for an account:
+    Log in: [done]
+    Forget password:
+
+  Manage users:
+    _: [in progress]
+    Create users: [in progress]
+    Delete users:
+    User profile page:
+
+  Blog:
+    Creating new posts: [done]
+    Comments: [done]
+    Moderating comments: [done]
+

data/lib/tps/cli_reporter.rb

@@ -0,0 +1,76 @@
+module TPS
+  class CliReporter
+    attr_reader :task
+
+    def initialize(task)
+      @task = task
+    end
+
+    def print
+      puts report
+    end
+
+    def report
+      re = ""
+      task.walk do |t, recurse|
+        re += CliReporter.new(t).report_task
+        recurse.call  if recurse
+      end
+      re
+    end
+
+    def report_task
+      indent = ' ' * (4 * task.level)
+
+      # Columns
+      c1 = "%s %s %s" % [ indent, status, task.name ]
+      c2 = if task.feature? || task.milestone?
+             progress
+          else
+            ' '*12
+          end
+
+      pref = c("-"*80, 30)+"\n"  if task.feature?
+
+      # Put together
+      "#{pref}" + "%-95s%s\n" % [ c1, c2 ]
+    end
+
+    def color
+      if task.done?
+        32
+      elsif task.in_progress?
+        34
+      else
+        30
+      end
+    end
+
+    def status
+      l = c("(", 30)
+      r = c(")", 30)
+      if task.done?
+         l + c('##', color) + r
+      elsif task.in_progress?
+        l + c('--', color) + r
+      else
+        l + c('  ', color) + r
+      end
+    end
+
+    def progress
+      max = 12
+      len = (task.percent * max).to_i
+
+      prog = ("%-#{max}s" % ["="*len])
+      prog = c("|"*len, color) + c("."*(max-len), 30)
+
+      prog
+    end
+
+  private
+    def c(str, c=nil)
+      c ? "\033[#{c}m#{str}\033[0m" : str
+    end
+  end
+end

data/lib/tps/task.rb

@@ -0,0 +1,166 @@
+require 'yaml'
+require 'tilt'
+
+module TPS
+  class Task
+    attr_reader :name     # "Create metrics"
+    attr_reader :tasks    # Array of Tasks
+    attr_reader :owner
+    attr_reader :pivotal_id
+    attr_reader :parent
+
+    def initialize(parent, name, data=nil)
+      @name   = name
+      @tasks  = Array.new
+      @parent = parent
+
+      if data.is_a?(Array)
+        tags = data
+        tasks = nil
+      elsif data.is_a?(Hash) && data['_']
+        tags = data.delete('_')
+        tasks = data
+      else
+        tags = Array.new
+        tasks = data
+      end
+
+      # Parse tags.
+      tags.each do |t|
+        # [done]
+        if ['done', 'ok'].include?(t)
+          @status = :done
+        elsif ['in progress', '...'].include?(t)
+          @status = :in_progress
+        # [@rstacruz]
+        elsif t =~ /^@/
+          @owner = t[1..-1]
+        # [pt/28394] -- Pivotal tracker
+        elsif t =~ /^pt\/(.*)$/i
+          @pivotal_id = $1.strip
+        # [50%] -- percentage
+        elsif t =~ /^([\d\.]+)%$/
+          @status = :in_progress
+          @percent = $1.strip.to_f / 100
+        # [0pt] -- points
+        elsif t =~ /^([\d\.]+)pts?/i
+          @points = $1.strip.to_f
+        end
+      end
+
+      @tasks = tasks.map { |task, data| Task.new self, task, data }  if tasks
+
+      n = @name.to_s.downcase
+      @milestone = root? && (n.include?('milestone') || n.include?('version'))
+    end
+
+    def status
+      # If no status is given, infer the status based on tasks.
+      if !@status && tasks?
+        if all_tasks_done?
+          return :done
+        elsif has_started_tasks?
+          return :in_progress
+        end
+      end
+
+      @status or :unstarted
+    end
+
+    def points
+      if @points
+        @points
+      elsif tasks?
+        tasks.inject(0.0) { |pts, task| pts + task.points }
+      else
+        1.0
+      end
+    end
+
+    def points_done
+      points * percent
+    end
+
+    def all_tasks_done?
+      tasks? and !tasks.any? { |t| ! t.done? }
+    end
+
+    def has_started_tasks?
+      tasks? and tasks.any? { |t| t.in_progress? or t.done? }
+    end
+
+    def to_s
+      name
+    end
+
+    def done?
+      status == :done
+    end
+
+    def in_progress?
+      status == :in_progress
+    end
+
+    def unstarted?
+      status == :unstarted
+    end
+
+    def tasks?
+      tasks.any?
+    end
+
+    def pivotal_url
+      "https://www.pivotaltracker.com/story/show/#{pivotal_id}"  if pivotal_id
+    end
+
+    def percent
+      if done?
+        1.0
+      elsif @percent
+        @percent
+      elsif tasks?
+        total = tasks.inject(0.0) { |pts, task| pts + task.points }
+        tasks.inject(0) { |i, task| i + task.points_done } / total
+      else
+        in_progress? ? 0.5 : 0
+      end
+    end
+
+    def level
+      parent ? parent.level + 1 : 0
+    end
+
+    def root?
+      ! parent
+    end
+
+    def feature?
+      root? or parent.milestone?
+    end
+
+    def milestone?
+      !! @milestone
+    end
+
+    # - list.walk do |task, recurse|
+    #   %ul
+    #     %li
+    #       = task
+    #       - recurse.call  if recurse
+    def walk(&blk)
+      tasks.each do |task|
+        yield task, lambda {
+          task.walk { |t, recurse| blk.call t, recurse }
+        }
+      end
+    end
+
+    def to_html(template=nil)
+      require 'tilt'
+      template ||= TPS.root('data', 'index.haml')
+
+      tpl = Tilt.new(template)
+      tpl.evaluate({}, list: self)
+    end
+  end
+end

data/lib/tps/task_list.rb

@@ -0,0 +1,17 @@
+module TPS
+  class TaskList < Task
+    def initialize(options)
+      super nil, nil
+
+      data = if options[:yaml]
+               YAML::load_file options[:yaml]
+             elsif options[:data]
+               options[:data]
+             else
+              options
+             end
+
+      @tasks = data.map { |task, data| Task.new nil, task, data }
+    end
+  end
+end

data/lib/tps/version.rb

@@ -0,0 +1,5 @@
+module TPS
+  def self.version
+    "0.0.2"
+  end
+end

data/lib/tps.rb

@@ -0,0 +1,34 @@
+require 'yaml'
+require 'tilt'
+
+# Common usage:
+#
+#     list = TPS::TaskList.new data: yaml_data
+#     list = TPS::TaskList.new yaml: filename
+#
+#     # Returns an array of tasks.
+#     task.tasks
+#
+#     # Metadata:
+#     task.name
+#     task.owner
+#     task.status
+#
+#     task.done?
+#     task.in_progress?
+#
+#     list.to_html
+#
+module TPS
+  ROOT = File.expand_path('../../', __FILE__)
+
+  autoload :Task,        'tps/task'
+  autoload :TaskList,    'tps/task_list'
+  autoload :CliReporter, 'tps/cli_reporter'
+
+  require 'tps/version'
+
+  def self.root(*a)
+    File.join ROOT, *a
+  end
+end

data/test/hello.yml

@@ -0,0 +1,42 @@
+Milestone 1:
+  First task: [25%] #0
+
+  User login: #1
+    Login:
+    Signup:
+
+  Overridden percent: #2
+    _: [50%]
+    one: [done]
+    two: [done]
+    three: [done]
+
+  Explicit points: #3
+    _: [15pt]
+    one: [done]
+    two: [done]
+    three: [done]
+    four:
+
+  Compound points: #4
+    one:
+    two:
+    three:
+      sub1: [3pts, done]
+      sub2:
+
+  Point rescaling: #5
+    # Has 6 sub points, but will be rescaled to 8.
+    # That is, the done "3" point task is actually worth 4 points.
+    one:
+      _: [8pts]
+      sub1: [3pts, done]
+      sub2: [1pt]
+      sub3: [1pt]
+      sub4: [1pt]
+
+  In progress: #6
+    one:
+    two: [in progress]
+
+Milestone 2:

data/test/test_helper.rb

@@ -0,0 +1,13 @@
+$:.unshift File.expand_path('../../lib', __FILE__)
+require 'contest'
+require 'tps'
+
+class UnitTest < Test::Unit::TestCase
+  def f(*a)
+    File.join fixture_root, *a
+  end
+
+  def fixture_root
+    File.expand_path('../', __FILE__)
+  end
+end

data/test/tps_test.rb

@@ -0,0 +1,71 @@
+require File.expand_path('../test_helper', __FILE__)
+
+class MyTest < UnitTest
+  setup do
+    @list = TPS::TaskList.new yaml: f('hello.yml')
+    @milestone = @list.tasks.first
+  end
+
+  test "Has tasks" do
+    assert @list.tasks?
+    assert @list.tasks.size == 2
+    assert @list.tasks.first.tasks.size >= 2
+  end
+
+  test "Explicit percent" do
+    task = @milestone.tasks[0]
+    assert task.in_progress?
+    assert task.status == :in_progress
+    assert task.percent == 0.25
+  end
+
+  test "Overriding percent" do
+    task = @milestone.tasks[2]
+    assert task.name == "Overridden percent"
+    assert task.in_progress?
+    assert task.status == :in_progress
+    assert task.percent == 0.5
+  end
+
+  test "Points" do
+    task = @milestone.tasks[1]
+    assert task.points == 2.0
+  end
+
+  test "Explicit points" do
+    task = @milestone.tasks[3]
+    assert task.points == 15
+    assert task.percent == 0.75
+    assert task.points_done == 11.25
+  end
+
+  test "Compound points" do
+    task = @milestone.tasks[4]
+    assert task.points == 6
+    assert task.percent == 0.50
+  end
+
+  test "Point rescaling" do
+    task = @milestone.tasks[5]
+    assert task.points == 8
+    assert task.points_done == 4.0
+    assert task.percent == 0.5
+  end
+
+  test "In progress" do
+    task = @milestone.tasks[6]
+    assert_equal 2, task.tasks.size
+    assert task.tasks[1].in_progress?
+    assert_equal 0.5, task.tasks[1].percent
+    assert_equal 0.5, task.tasks[1].points_done
+    assert_equal 0.25, task.percent
+  end
+
+  test "Milestone" do
+    assert @milestone.milestone?
+  end
+
+  test "HTML works" do
+    assert @list.to_html
+  end
+end

data/tps_reporter.gemspec

@@ -0,0 +1,16 @@
+require './lib/tps/version'
+
+Gem::Specification.new do |s|
+  s.name = "tps_reporter"
+  s.version = TPS.version
+  s.summary = %{Task progress sheet reporter.}
+  s.description = %Q{A YAML-powered, simple command-line task report builder.}
+  s.authors = ["Rico Sta. Cruz"]
+  s.email = ["rico@sinefunc.com"]
+  s.homepage = "http://github.com/rstacruz/tps_reporter"
+  s.files = `git ls-files`.strip.split("\n")
+  s.executables = Dir["bin/*"].map { |f| File.basename(f) }
+
+  s.add_dependency "tilt"
+  s.add_development_dependency "contest"
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: tps_reporter
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Rico Sta. Cruz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-04 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: tilt
+  requirement: &2152658640 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *2152658640
+- !ruby/object:Gem::Dependency
+  name: contest
+  requirement: &2152658200 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *2152658200
+description: A YAML-powered, simple command-line task report builder.
+email:
+- rico@sinefunc.com
+executables:
+- tps
+extensions: []
+extra_rdoc_files: []
+files:
+- HISTORY.md
+- README.md
+- Rakefile
+- bin/tps
+- data/index.haml
+- data/sample.yml
+- lib/tps.rb
+- lib/tps/cli_reporter.rb
+- lib/tps/task.rb
+- lib/tps/task_list.rb
+- lib/tps/version.rb
+- test/hello.yml
+- test/test_helper.rb
+- test/tps_test.rb
+- tps_reporter.gemspec
+homepage: http://github.com/rstacruz/tps_reporter
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Task progress sheet reporter.
+test_files: []