twdeps 0.0.2

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.cache_rake_t

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+
+rvm:
+  - 1.9.3
+
+before_script:
+ - mkdir ~/.task
+ - echo data.location=~/.task > ~/.taskrc
+ - task count
+
+before_install:
+ - echo | sudo add-apt-repository ppa:ultrafredde/ppa
+ - sudo apt-get update
+ - sudo apt-get install task
+ - sudo apt-get install graphviz

data/Gemfile

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

data/Guardfile

@@ -0,0 +1,12 @@
+guard 'bundler' do
+  watch('Gemfile')
+  watch(/^.+\.gemspec/)
+end
+
+guard :test, :test_paths => ['test/unit', 'test/integration'] do
+  watch('lib/twdeps.rb'){"test"}
+  watch(%r{^lib/twdeps/(.+)\.rb$}){|m| "test/unit/test_#{m[1]}.rb"} 
+  watch(%r{^test/unit/test_(.+)\.rb$})
+  watch('test/test_helper.rb'){"test"}
+  watch('test/helpers/**/*'){"test"}
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Nicholas E. Rabenau
+
+MIT License
+
+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,56 @@
+# TaskWarrior Dependency Visualization
+
+Visualizes dependencies between TaskWarrior tasks.
+
+[![Build Status](https://secure.travis-ci.org/nerab/twdeps.png?branch=master)](http://travis-ci.org/nerab/twdeps)
+
+## Example
+
+Given a set of interdependent tasks described in the TaskWarrior [tutorial](http://taskwarrior.org/projects/taskwarrior/wiki/Tutorial2#DEPENDENCIES), the tasks are
+
+1. Exported from TaskWarrior as JSON, then
+1. Piped into `twdeps`, and finally
+1. The output is directed to a PNG file.
+
+Result:
+
+![party](/nerab/twdeps/raw/master/examples/party.png)
+
+## Installation
+
+    $ gem install twdeps
+
+## Usage
+
+    # Create a dependency graph as PNG and pipe it to a file
+    # See [Limitations](Limitations) below for why we need the extra task parms
+    task export rc.json.array=on rc.verbose=nothing | twdeps > deps.png
+  
+    # Same but spefify output format
+    task export | twdeps --format svg > deps.svg
+
+    # Create a graph from a previously exported file
+    task export > tasks.json
+    cat tasks.json | twdeps > deps.png
+  
+    # Display graph in browser without creating an intermediate file
+    # Requires bcat to be installed
+    task export | twdeps --format svg | bcat
+
+## Dependencies
+
+The graph is generated with [ruby-graphviz](https://github.com/glejeune/Ruby-Graphviz), which in turn requires a local [Graphviz](http://graphviz.org/) installation (e.g. `brew install graphviz`).
+
+[bcat](http://rtomayko.github.com/bcat/) is required for piping into a browser.
+
+## Limitations
+
+Due to [two](http://taskwarrior.org/issues/1017) [bugs](http://taskwarrior.org/issues/1013) in JSON export, TaskWarrior 2.0 needs the command line options `rc.json.array=on` and `rc.verbose=nothing`.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test' << 'test/helpers'
+  test.test_files = FileList['test/**/test_*.rb']
+end
+
+task :default => :test

data/bin/twdeps

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+
+require 'bundler'
+Bundler.require
+
+require 'trollop'
+
+def log(msg)
+  STDERR.puts "#{File.basename($0)}: #{msg}"
+end
+
+def die(msg = nil)
+  log(msg) unless msg.nil?
+  exit 1
+end
+
+opts = Trollop::options do
+  version "#{File.basename($0)} v#{TaskWarrior::Dependencies::VERSION} (c) 2012 Nicolas E. Rabenau"
+  banner <<-EOS
+Visualizes dependencies between TaskWarrior tasks.
+
+Usage:
+       #{File.basename($0)} [options]
+
+where [options] are:
+
+EOS
+  opt :format, "Specify output format", :default => 'svg'
+  opt :trace,  "Enable trace output", :default => false
+end
+
+include TaskWarrior
+include TaskWarrior::Dependencies
+
+Trollop::die :format, "must be one of #{Graph.formats.join(', ')}" unless Graph.formats.include?(opts[:format])
+
+begin
+  repo = Repository.new(ARGF.read)
+  master = Graph.new(File.basename($0)) # TODO Move this to a CommandlinePresenter
+
+  # Add all projects (will add their tasks and dependencies recursively)
+  repo.projects.each do |project|
+    master << project
+  end
+
+  # Add all project-less tasks as toplevel nodes
+  repo.tasks.reject{|t| t.project}.each do |task|
+    master << task
+  end
+
+  puts master.render(opts[:format])
+rescue
+  if opts[:trace]
+    log($!)
+    $@.each{|line| log(line)}
+  else
+    die($!)
+  end
+end

data/lib/twdeps/graph.rb

@@ -0,0 +1,111 @@
+module TaskWarrior
+  module Dependencies
+    class NullPresenter
+      def attributes
+        {:label => 'Unknown', :fontcolor => 'red'}
+      end
+
+      def id
+        'null'
+      end
+    end
+
+    # Builds a dependency graph
+    #
+    # +thing+ is added as node with all of its dependencies. A presenter is used to present the task as node label.
+    # +thing.id.to_s+ is called for the identifier. It must be unique within the graph and all of its dependencies.
+    #
+    # +thing.dependencies(thing)+ is called if +thing+ responds to it. It is expected to return a list
+    # of things the thing depends on. Each thing may have its own dependencies which will be resolved recursively.
+    #
+    # Design influenced by https://github.com/glejeune/Ruby-Graphviz/blob/852ee119e4e9850f682f0a0089285c36ee16280f/bin/gem2gv
+    #
+    class Graph
+      class << self
+        def formats
+          Constants::FORMATS
+        end
+      end
+
+      #
+      # Build a new Graph for +thing+
+      # # TODO Accept a presenter that would default to GlobalPresenter with {:rankdir => 'BT'}
+      def initialize(name = :G, attributes = [])
+        @graph = GraphViz::new(name, attributes)
+        @dependencies = []
+        @edges = []
+      end
+
+      def <<(task_or_project)
+        if task_or_project.respond_to?(:dependencies)
+          task = task_or_project
+          nodeA = find_or_create_node(task)
+          create_edges(nodeA, task.dependencies)
+
+          # resolve all dependencies we don't know yet
+          task.dependencies.each do |dependency|
+            unless @dependencies.include?(dependency)
+              @dependencies << dependency
+              self << dependency
+            end
+          end
+        else
+          # it's a project
+          project = task_or_project
+          cluster = Graph.new(presenter(project).id, presenter(project).attributes)
+
+          project.tasks.each do |task|
+            cluster << task
+          end
+
+          # add all nodes and edges from cluster as a subgraph to @graph
+          @graph.add_graph(cluster.graph)
+        end
+      end
+
+      def render(format)
+        @graph.output(format => String)
+      end
+
+    protected
+      attr_reader :graph
+
+    private
+      def create_edges(nodeA, nodes)
+        nodes.each do |node|
+          nodeB = find_or_create_node(node)
+          create_edge(nodeA, nodeB)
+        end
+      end
+
+      def find_or_create_node(thing)
+        @graph.get_node(presenter(thing).id) || create_node(thing)
+      end
+
+      def create_node(thing)
+        @graph.add_nodes(presenter(thing).id, presenter(thing).attributes)
+      end
+
+      def create_edge(nodeA, nodeB)
+        edge = [nodeA, nodeB]
+        unless @edges.include?(edge) # GraphViz lacks get_edge, so we need to track existing edges ourselfes
+          @edges << edge
+          @graph.add_edges(nodeA, nodeB)
+        end
+      end
+
+      def presenter(thing)
+        # TODO Will counter-caching the presenters improve performance?
+        if thing.nil?
+          NullPresenter.new
+        else
+          if thing.respond_to?(:dependencies)
+            TaskPresenter.new(thing)
+          else
+            ProjectPresenter.new(thing)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/twdeps/priority_mapper.rb

@@ -0,0 +1,9 @@
+module TaskWarrior
+  class PriorityMapper
+    class << self
+      def map(json)
+        {'H' => :high, 'M' => :medium, 'L' => :low}[json]
+      end
+    end
+  end
+end

data/lib/twdeps/project.rb

@@ -0,0 +1,33 @@
+require 'active_model'
+
+module TaskWarrior
+  class Project
+    attr_reader :name, :tasks
+
+    include ActiveModel::Validations
+    validates :name, :presence => true
+    validate :name_may_not_contain_spaces
+
+    def initialize(name, tasks = [])
+      @name = name
+      @tasks = tasks
+      @tasks.each{|t| t.project = self}
+    end
+
+    def <<(task)
+      @tasks << task
+      task.project = self
+    end
+
+    def to_s
+      "Project #{name} (#{@tasks.size} tasks)"
+    end
+
+    private
+    def name_may_not_contain_spaces
+      if !name.blank? and name[/\s/]
+        errors.add(:name, "may not contain spaces")
+      end
+    end
+  end
+end

data/lib/twdeps/project_presenter.rb

@@ -0,0 +1,20 @@
+module TaskWarrior
+  module Dependencies
+    #
+    # Presents a project's attributes suitable for a GraphViz cluster
+    #
+    class ProjectPresenter
+      def initialize(project)
+        @project = project
+      end
+      
+      def attributes
+        {:label => @project.name}
+      end
+      
+      def id
+        "cluster_#{@project.name}"
+      end
+    end
+  end
+end

data/lib/twdeps/tag.rb

@@ -0,0 +1,48 @@
+require 'active_model'
+
+module TaskWarrior
+  class Tag
+    attr_reader :name
+
+    include ActiveModel::Validations
+    validates :name, :presence => true
+    validate :name_may_not_contain_spaces
+
+    def initialize(tag_or_name, tasks = [])
+      if tag_or_name.respond_to?(:name)
+        @name = tag_or_name.name
+        @tasks = tag_or_name.tasks
+      else
+        @name = tag_or_name
+        @tasks = []
+      end
+
+      tasks.each{|task|
+        self << task
+      }
+    end
+
+    def <<(task)
+      @tasks << task unless @tasks.include?(task)
+    end
+
+    def tasks
+      @tasks #.dup
+    end
+
+    def to_s
+      "Tag: #{name} (#{@tasks.size} tasks)"
+    end
+
+    def ==(other)
+      name == other.name
+    end
+
+    private
+    def name_may_not_contain_spaces
+      if !name.blank? and name[/\s/]
+        errors.add(:name, "may not contain spaces")
+      end
+    end
+  end
+end

data/lib/twdeps/task.rb

@@ -0,0 +1,52 @@
+require 'active_model'
+
+module TaskWarrior
+  class Task
+    attr_accessor :description, :id, :entry, :status, :uuid, :project, :dependencies, :parent, :children, :priority
+
+    include ActiveModel::Validations
+    validates :description, :id, :entry, :status, :uuid, :presence => true
+
+    validates :id, :numericality => { :only_integer => true, :greater_than => 0}
+
+    validates :uuid, :format => {:with => /[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/,
+                                 :message => "'%{value}' does not match the expected format of a UUID"}
+
+    validates :status, :inclusion => {:in => [:pending, :waiting, :complete], :message => "%{value} is not a valid status"}
+
+    validates :priority, :inclusion => {
+      :in => [:high, :medium, :low],
+      :allow_nil => true,
+      :allow_blank => true,
+      :message => "%{value} is not a valid priority"
+    }
+
+    validate :entry_cannot_be_in_the_future
+
+    def initialize(description)
+      @description = description
+      @dependencies = []
+      @children = []
+      @tags = []
+    end
+
+    def tags
+      @tags
+    end
+
+    def to_s
+      "Task '#{description}'".tap{|result| result << " <#{uuid}>" if uuid}
+    end
+
+    private
+    def entry_cannot_be_in_the_future
+      begin
+        if !entry.blank? and entry > DateTime.now
+          errors.add(:entry, "can't be in the future")
+        end
+      rescue
+        errors.add(:entry, "must be comparable to DateTime")
+      end
+    end
+  end
+end

data/lib/twdeps/task_mapper.rb

@@ -0,0 +1,30 @@
+module TaskWarrior
+  #
+  # A DataMapper that makes new Tasks from a JSON representation
+  #
+  class TaskMapper
+    class << self
+      def map(json)
+        Task.new(json['description']).tap{|t|
+          t.id = json['id'].to_i
+          t.uuid = json['uuid']
+          t.entry = DateTime.parse(json['entry'])
+          t.status = json['status'].to_sym
+          t.project = json['project']
+
+          if json['depends']
+            if json['depends'].respond_to?(:split)
+              t.dependencies = json['depends'].split(',')
+            else
+              t.dependencies = json['depends']
+            end
+          end
+
+          t.parent = json['parent'] # Children will be cross-indexed in the repository
+          t.priority = PriorityMapper.map(json['priority'])
+          json['tags'].each{|tag| t.tags << tag} if json['tags']
+        }
+      end
+    end
+  end
+end

data/lib/twdeps/task_presenter.rb

@@ -0,0 +1,28 @@
+module TaskWarrior
+  module Dependencies
+    #
+    # Presents a task's attributes suitable for a GraphViz node
+    #
+    class TaskPresenter
+      def initialize(task)
+        @task = task
+      end
+      
+      def attributes
+        attrs = {:label => @task.description}
+        attrs.merge!({:tooltip => "Status: #{@task.status}"})
+
+        # TODO Once we see the urgency in the JSON export, we can color-code the nodes
+        # http://taskwarrior.org/issues/973
+        # attrs.merge!({:fillcolor => 'red', :style => 'filled'})
+
+        attrs.merge!({:fontcolor => 'gray', :color => 'gray'}) if :completed == @task.status
+        attrs
+      end
+      
+      def id
+        @task.uuid
+      end
+    end
+  end
+end

data/lib/twdeps/task_repository.rb

@@ -0,0 +1,77 @@
+require 'json'
+
+module TaskWarrior
+  class SimpleTag
+    attr_reader :name, :tasks
+
+    def initialize(name)
+      @name = name
+      @tasks = []
+    end
+
+    def <<(task)
+      @tasks << task unless @tasks.include?(task)
+    end
+  end
+
+  class Repository
+    def initialize(input)
+      @tasks = {}
+      @projects = Hash.new{|hash, key| hash[key] = Project.new(key)}
+      @tags = Hash.new{|hash, key| hash[key] = Tag.new(key)}
+
+      JSON.parse(input).each{|json|
+        task = TaskWarrior::TaskMapper.map(json)
+        @tasks[task.uuid] = task
+        @projects[task.project].tasks << task if task.project
+
+        # Create a new Tag object in @tags that is the value for each tag name
+        task.tags.each{|tag_name| @tags[tag_name] << task}
+      }
+
+      # Replace the uuid of each dependency with the real task
+      @tasks.each_value{|task| task.dependencies.map!{|uuid| @tasks[uuid]}}
+
+      # Replace the project property of each task with a proper Project object carrying a name and all of the project's tasks
+      @tasks.each_value{|task| task.project = @projects[task.project] if task.project}
+
+      # Add child tasks to their parent, but keep them in the global index
+      @tasks.each_value do |task|
+        if task.parent
+          parent = @tasks[task.parent]
+
+          if parent # we know the parent
+            parent.children << task
+            task.parent = parent
+          end
+        end
+      end
+    end
+
+    def tasks
+      # Do not expose child tasks directly
+      @tasks.values.reject{|t| t.parent}
+    end
+
+    # direct lookup by uuid
+    def [](uuid)
+      @tasks[uuid]
+    end
+
+    def projects
+      @projects.values
+    end
+
+    def project(name)
+      @projects[name] if @projects.has_key?(name)
+    end
+
+    def tags
+      @tags.values
+    end
+
+    def tag(name)
+      @tags[name] if @tags.has_key?(name)
+    end
+  end
+end

data/lib/twdeps/version.rb

@@ -0,0 +1,5 @@
+module TaskWarrior
+  module Dependencies
+    VERSION = "0.0.2"
+  end
+end

data/lib/twdeps.rb

@@ -0,0 +1,22 @@
+require "twdeps/version"
+
+require "twdeps/task"
+require "twdeps/project"
+require "twdeps/tag"
+
+require "twdeps/task_mapper"
+require "twdeps/priority_mapper"
+require "twdeps/task_repository"
+
+require "twdeps/graph"
+require "twdeps/task_presenter"
+require "twdeps/project_presenter"
+
+require "graphviz"
+require "json"
+
+module TaskWarrior
+  module Dependencies
+    # Your code goes here...
+  end
+end

data/test/fixtures/no_deps.json

@@ -0,0 +1,7 @@
+[{"id":1,"description":"Select a free weekend in November","entry":"20120629T191421Z","priority":"H","project":"party","status":"pending","uuid":"6fd0ba4a-ab67-49cd-ac69-64aa999aff8a","annotations":[{"entry":"20120629T191534Z","description":"the 13th looks good"}]},
+{"id":2,"description":"Select and book a venue","entry":"20120629T191634Z","priority":"H","project":"party","status":"pending","uuid":"c992448a-f1ea-4982-8461-47f0705ff509"},
+{"id":3,"description":"Mail invitations","entry":"20120629T191919Z","project":"party","status":"pending","uuid":"3b53178e-d5a4-45e0-afc2-1292db58a59a"},
+{"id":4,"description":"Select a caterer","entry":"20120629T191919Z","project":"party","status":"pending","uuid":"c590941b-eb10-4569-bdc9-0e339f79305e"},
+{"id":5,"description":"Design invitations","entry":"20120629T191919Z","priority":"H","project":"party","status":"pending","tags":["mall"],"uuid":"e5a867b7-0116-457d-ba43-9ac2bee6ad2a"},
+{"id":6,"description":"Print invitations","entry":"20120629T191920Z","project":"party","status":"pending","tags":["mall"],"uuid":"9f6f3738-1c08-4f45-8eb4-1e90864c7588"}
+]

data/test/fixtures/party.json

@@ -0,0 +1,7 @@
+[{"id":1,"description":"Select a free weekend in November","entry":"20120629T191421Z","priority":"H","project":"party","status":"pending","uuid":"6fd0ba4a-ab67-49cd-ac69-64aa999aff8a","annotations":[{"entry":"20120629T191534Z","description":"the 13th looks good"}]},
+{"id":2,"depends":"6fd0ba4a-ab67-49cd-ac69-64aa999aff8a","description":"Select and book a venue","entry":"20120629T191634Z","priority":"H","project":"party","status":"pending","uuid":"c992448a-f1ea-4982-8461-47f0705ff509"},
+{"id":3,"depends":"9f6f3738-1c08-4f45-8eb4-1e90864c7588","description":"Mail invitations","entry":"20120629T191919Z","project":"party","status":"pending","uuid":"3b53178e-d5a4-45e0-afc2-1292db58a59a"},
+{"id":4,"depends":"6fd0ba4a-ab67-49cd-ac69-64aa999aff8a,c992448a-f1ea-4982-8461-47f0705ff509","description":"Select a caterer","entry":"20120629T191919Z","project":"party","status":"pending","uuid":"c590941b-eb10-4569-bdc9-0e339f79305e"},
+{"id":5,"depends":"c992448a-f1ea-4982-8461-47f0705ff509","description":"Design invitations","entry":"20120629T191919Z","priority":"H","project":"party","status":"pending","tags":["mall"],"uuid":"e5a867b7-0116-457d-ba43-9ac2bee6ad2a"},
+{"id":6,"depends":"e5a867b7-0116-457d-ba43-9ac2bee6ad2a","description":"Print invitations","entry":"20120629T191920Z","project":"party","status":"pending","tags":["mall"],"uuid":"9f6f3738-1c08-4f45-8eb4-1e90864c7588"}
+]