brief 0.0.1 → 0.0.2

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    MTdkMDJhN2M2MWY1NDAxYzVhZDZlMzZlOTJhZWJkY2IxMTQ4YzI5Mw==
-  data.tar.gz: !binary |-
-    OWU2NWMwZjRjZWJmMjgxMTM4ZjI3ZGYzMGFhMjI3ZDIyOGJkMWNjZA==
+SHA1:
+  metadata.gz: 7c6f64e7e55cb875b980ad06e7dbd5e66d0757d7
+  data.tar.gz: a285a1c7344f503d47c10cec106fe4e18f9a8443
 SHA512:
-  metadata.gz: !binary |-
-    ZDkxNzk3NGY2MTQxNmMxNjBlNGZjMjdlMjhiNGQyZGIyNjlkM2YxYjhkYWVl
-    YTg5NjE3OTczN2Q2NTQwMGFmMjNkYzYwYjA5ZGJmMDRmZjUzM2ZkNTRmMzUy
-    YWFiY2M5OTM1NWU3Y2RhMWM5NzRjZTFjMmJkNTE1NTdlOTZiOWY=
-  data.tar.gz: !binary |-
-    ZDEwYWIyZDk0ZTE3ODI1MzU1MTE0YWVhODAxNDRlYzYyNjM2MWNlYzdmNjQ4
-    NzI0ZGI2NGJjZDFkNDY0NDVjNmQxYTljMWZmNGNkZTc0MThjZGMyNGVjOGY2
-    N2U0NjQzOTU4NDk5MmU2ODRkYmUwNTU1Mjg2ZTVmNzg5ZDg5ZDI=
+  metadata.gz: a97e7f32844a0e7494e619a83ac5d8d08a775331ed97b4083b4833cd5117ad8568c2623048e72c702324ba81c59d508f4a63124b13b431bf4e96e4ef20fc2003
+  data.tar.gz: 3e5ee5019ef3cf20c4740b1957553b403772b0158b99bb896e449b9649b77b214ccba53fe3008c80f98abebb397397b50680bc395619baa2437b2ffacd8575b0

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,81 @@
+PATH
+  remote: .
+  specs:
+    brief (0.0.1)
+      active_support
+      colored
+      commander
+      hashie
+      i18n
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    active_support (3.0.0)
+      activesupport (= 3.0.0)
+    activesupport (3.0.0)
+    celluloid (0.15.2)
+      timers (~> 1.1.0)
+    coderay (1.1.0)
+    colored (1.2)
+    commander (4.2.0)
+      highline (~> 1.6.11)
+    diff-lcs (1.2.5)
+    ffi (1.9.3)
+    formatador (0.2.5)
+    guard (2.6.1)
+      formatador (>= 0.2.4)
+      listen (~> 2.7)
+      lumberjack (~> 1.0)
+      pry (>= 0.9.12)
+      thor (>= 0.18.1)
+    guard-rspec (4.2.10)
+      guard (~> 2.1)
+      rspec (>= 2.14, < 4.0)
+    hashie (2.1.2)
+    highline (1.6.21)
+    i18n (0.6.9)
+    listen (2.7.9)
+      celluloid (>= 0.15.2)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+    lumberjack (1.0.7)
+    method_source (0.8.2)
+    pry (0.9.12.6)
+      coderay (~> 1.0)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    pry-nav (0.2.3)
+      pry (~> 0.9.10)
+    rake (10.3.2)
+    rb-fsevent (0.9.4)
+    rb-inotify (0.9.5)
+      ffi (>= 0.5.0)
+    rspec (3.0.0)
+      rspec-core (~> 3.0.0)
+      rspec-expectations (~> 3.0.0)
+      rspec-mocks (~> 3.0.0)
+    rspec-core (3.0.2)
+      rspec-support (~> 3.0.0)
+    rspec-expectations (3.0.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.0.0)
+    rspec-mocks (3.0.2)
+      rspec-support (~> 3.0.0)
+    rspec-support (3.0.2)
+    slop (3.5.0)
+    thor (0.19.1)
+    timers (1.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  brief!
+  bundler (~> 1.3)
+  guard
+  guard-rspec
+  pry
+  pry-nav
+  rake
+  rspec

data/Guardfile

@@ -0,0 +1,5 @@
+guard 'rspec', :all_on_start => true do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec/" }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Jonathan Soeder
+
+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,71 @@
+# Brief
+
+Brief is a tool to make writing markdown more productive. You can think
+of it like a preprocessor for markdown.   
+
+Brief converts raw markdown into a nested structure which can be
+used to automate tasks and generate more specific content elements. 
+
+Based on which headings you use and how you nest them, brief 
+will allow you to define mappings to objects which can be used to
+automate other tasks.  
+
+I personally use the brief tool to allow me to take a single markdown
+file and create a project wiki page, with links to related milestones
+and github issues.
+
+Example:
+
+```markdown
+# Wiki Page Heading
+
+Content. Will go on a wiki page.  The content below here,
+and the subheadings, will be replaced with a roll-up / summary 
+of the elements.
+
+## Milestone Heading
+
+This content will go in the milestone body.  The wiki page
+that this belongs to, will include a different kind of view of this
+content.
+
+### An issue title
+
+This goes in the issue's body. The wiki page this belongs to will
+possibly have a link to the issue and a label for its status.
+
+### Another issue title
+
+This goes in this issue's body.  Same thing. It obviously belongs to the
+milestone.
+
+```
+
+Given the example above, I run:
+
+```
+brief publish project overview /path/to/markdown
+```
+
+This will create a Github Wiki entry in the repo that I specify, and
+this wiki entry will include links to the milestones and issues. 
+
+You can see a sample of this Wiki page here:
+(TODO INSERT LINK)
+
+### Publishing Briefs
+
+Publishing a brief allows you to run some publishing tasks using raw
+markdown input.  
+
+(TODO) show some examples of a publisher
+
+### Writing Briefs
+
+Writing a brief is as easy as running the brief command, with the name
+of the template you intend to use.  It will open up $EDITOR for you with
+some example input.
+
+```bash
+brief write project overview #=> Opens up $EDITOR with some example content in it
+```

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "bundler/setup"
+require "rspec/core/rake_task"
+
+Bundler::GemHelper.install_tasks
+
+RSpec::Core::RakeTask.new(:spec) do |rspec|
+  rspec.rspec_opts = ['--backtrace']
+end
+
+task :default => :spec

data/bin/brief

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+#
+lib = File.join(File.dirname(__FILE__), '../lib')
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+begin
+  require "rubygems"
+  require 'colored'
+  require "commander/import"
+  require "pry"
+  require "brief"
+end
+
+program :name, 'Brief'
+program :version, Brief::Version
+program :description, 'Brief CLI'
+
+command :inspect do |c|
+  c.syntax = 'brief inspect file [options]'
+  c.description = 'Debug the parsing of a brief'
+
+  c.action do |args, options|
+    path = Pathname(args.first)
+    path = path.relative? ? Brief.root.join(path) : path
+    doc  = Brief::Document.new(path)
+    
+    doc.elements do |el|
+      puts el.inspect
+    end
+  end
+end
+
+Pathname(lib).join("brief","cli","commands").children.each do |f|
+  require(File.expand_path(f)) if f.file?
+end

data/brief.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.name          = "brief"
+  spec.version       = '0.0.2' 
+  spec.authors       = ["Jonathan Soeder"]
+  spec.email         = ["jonathan.soeder@gmail.com"]
+  spec.description   = %q{Brief is a utility to make writing more productive for software architects. It allows you write to places like Github Wiki, The Github Issues API all from the command line and a single file.}
+  spec.summary       = %q{Brief is a utility to make writing more productive for software architects.}
+  spec.homepage      = "http://architects.io/brief"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+  
+  spec.add_dependency 'hashie'
+  spec.add_dependency 'commander'
+  spec.add_dependency 'colored'
+  spec.add_dependency 'active_support'
+  spec.add_dependency 'i18n'
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "pry-nav"
+  spec.add_development_dependency "guard"
+  spec.add_development_dependency "guard-rspec"
+end

data/examples/project_overview.md

@@ -0,0 +1,23 @@
+```settings
+status: proposed
+edited_by: jonathan soeder
+```
+
+# This is a project overview
+
+A body paragraph or two here will be the content for a cover page. You can supply whatever background
+info, domain knowledge requirements, processes, file dependencies and links, whatever.
+
+The content for the nested milestones and issues below will be transformed into raw markdown
+which will generate a status summary of the milestones and issues as they get created in the Github API.
+
+## This is a milestone heading
+
+A milestone is some logical way of grouping issues and attaching a date to them. You will write the body
+of the individual issues and optionally assign them or label them by writing them below. When this brief
+gets published, the issues will be created and added to the milestone.
+
+### This is an issue that belongs to the above milestone
+
+The content of your issue goes here. Normal github flavored markdown is supported.
+

data/lib/brief/cli/commands/config.rb

@@ -0,0 +1,40 @@
+command :config do |c|
+  c.syntax = 'brief config [options]'
+  c.description = 'manipulate brief configuration settings'
+
+  c.action do |args, options|
+    Brief::Configuration.initialize!
+
+    # Setting a value manually
+    if args.first == 'set'
+      args.slice(1, args.length).map(&:strip).each do |pair|
+        key, value = pair.split('=')
+        Brief.configuration.set(key, value, false)
+      end
+
+      Brief.configuration.save!
+    end
+
+    if args.empty? && !(Brief.config.github_username || Brief.config.github_token)
+      args.push "github"
+    end
+
+    if args.first == "github"
+      username = ask("What is your github username: ", String)
+
+      say "If you haven't generated a personal access token yet, do so here: https://github.com/settings/tokens/new"
+      access_token = ask("Enter your private access token: ")
+
+      if username
+        Brief.config.set "github_username", username
+      end
+
+      if access_token
+        # TODO
+        # We could validate the token for them.
+        Brief.config.set "github_token", access_token
+      end
+    end
+
+  end
+end

data/lib/brief/cli/commands/publish.rb

@@ -0,0 +1,27 @@
+command :publish do |c|
+  c.syntax = 'brief publish PUBLISHER [options]'
+  c.description = 'publish a brief file with whatever publisher template you want to use.'
+
+  c.option '--from FILE', 'Specify a file to read from. Otherwise we use $EDITOR'
+
+  c.action do |args, options|
+    path = case
+    when options.from
+      Pathname(options.from)
+    when (Pathname(args.last).exist? rescue false)
+      Pathname(args.pop)
+    end
+
+    document   = Brief::Document.new(path: path)
+
+    publisher = if path && path.exist? && args.empty?
+      guess = path.basename.to_s.gsub(/\.\w+$/,'')
+
+      Brief::Publisher.find(guess)
+    else
+      Brief::Publisher.find(args)
+    end
+
+    document.publish(publisher)
+  end
+end

data/lib/brief/cli/commands/write.rb

@@ -0,0 +1,26 @@
+command :write do |c|
+  c.syntax = 'brief write PUBLISHER [options]'
+
+  c.option '--file FILE', 'Specify a file to read from. Otherwise we use $EDITOR'
+
+  c.action do |args, options|
+    path = case
+           when options.file
+             Pathname(options.file)
+           when (Pathname(args.last).exist? rescue false)
+             Pathname(args.pop)
+           end
+
+
+    publisher       = Brief::Publisher.find(args)
+
+    content = ask_editor(publisher.sample)
+
+    if content == publisher.sample
+      say "Ignoring editor input, same as sample"
+    end
+
+    binding.pry
+  end
+end
+

data/lib/brief/configuration.rb

@@ -0,0 +1,134 @@
+require "singleton"
+require "json"
+
+module Brief
+  class Configuration
+    include Singleton
+
+    DefaultSettings = {
+      github_username: "",
+      github_api_token: ""
+    }
+
+    def self.method_missing meth, *args, &block
+      if instance.respond_to?(meth)
+        return instance.send meth, *args, &block
+      end
+
+      nil
+    end
+
+    def initialize!
+      FileUtils.mkdir_p home_config_path.dirname
+    end
+
+    def method_missing meth, *args, &block
+      if current.has_key?(meth.to_s)
+        return current.fetch(meth)
+      end
+
+      super
+    end
+
+    def current_github_repository
+      value = current.github_repository
+
+      return value if value
+
+      if value.nil?
+        if guess = Brief::Git.current_github_repository
+          set "github_repository", guess
+          return guess
+        end
+      end
+
+      current.github_repository
+    end
+
+    def current
+      @current ||= begin
+                     home_config.merge(cwd_config)
+                   end
+    end
+
+    def current_config
+      cwd_config_path.exist? ? cwd_config : home_config
+    end
+
+    def set setting, value, persist=true
+      current_config[setting] = value
+      save! if persist == true
+      value
+    end
+
+    def unset setting, persist=true
+      current_config.delete(setting)
+      save! if persist == true
+    end
+
+    def current
+      Hashie::Mash.new(home_config.merge(cwd_config).merge(applied_config))
+    end
+
+    def apply_config_from_path path
+      path = Pathname(path)
+      parsed = JSON.parse(path.read) rescue {}
+      applied_config.merge!(parsed)
+      nil
+    end
+
+    def save!
+      save_home_config
+      save_cwd_config
+    end
+
+    def save_cwd_config
+      return nil unless cwd_config_path.exist?
+
+      File.open(cwd_config_path,'w+') do |fh|
+        fh.write JSON.generate(cwd_config.to_hash)
+      end
+    end
+
+    def save_home_config
+      File.open(home_config_path,'w+') do |fh|
+        fh.write JSON.generate(home_config.to_hash)
+      end
+    end
+
+    # Applied config is configuration values passed in context
+    # usually from the cli, but also in the unit tests
+    def applied_config
+      @applied_config ||= {}
+    end
+
+    def cwd_config
+      @cwd_config ||= begin
+        (cwd_config_path.exist? rescue false) ? JSON.parse(cwd_config_path.read) : {}
+      rescue
+        {}
+      end
+    end
+
+    def home_config
+      @home_config ||= begin
+        (home_config_path.exist? rescue false) ? JSON.parse(home_config_path.read) : {}
+      rescue
+        {}
+      end
+    end
+
+    def home_folder
+      Pathname(ENV['HOME']).join('.brief')
+    end
+
+    def home_config_path
+      Pathname(ENV['HOME']).join('.brief','config.json')
+    end
+
+    def cwd_config_path
+      Pathname(Dir.pwd).join('.briefrc')
+    end
+  end
+end
+

data/lib/brief/document.rb

@@ -0,0 +1,68 @@
+
+module Brief
+  class Document
+    attr_reader :content, :options
+
+    def initialize(options)
+      @options = options
+
+      case
+      when options.is_a?(String)
+        @content = options
+      when options.is_a?(Pathname)
+        @content = options.read
+      when options.is_a?(Hash)
+        @content = options[:path].read
+      end
+    end
+
+    def write using
+      using.run_before_hooks(:write) do
+        write
+      end
+    end
+
+    def publish using=nil
+      using ||= publisher
+
+      document = self
+      using.run_before_hooks(:publish) do
+        process(document)
+      end
+    end
+
+    def publisher
+      @publisher ||= Brief::Publisher.find(options[:publisher] || "default")
+    end
+
+    def method_missing meth, *args, &block
+      if parser.respond_to?(meth)
+        return parser.send(meth, *args, &block)
+      end
+
+      super
+    end
+
+    def checksum
+      @checksum ||= Digest::MD5.hexdigest(content)
+    end
+
+    def parser
+      @parser ||= Brief::Parser.new(content, checksum: checksum)
+    end
+
+
+    def settings
+      parser.front_matter
+    end
+
+    def elements
+      parser.send(:elements)
+    end
+
+    def tree
+      parser.send(:tree)
+    end
+
+  end
+end

data/lib/brief/formatters/base.rb

@@ -0,0 +1,12 @@
+module Brief
+  module Formatters
+    class Base
+
+      attr_accessor :element
+
+      def initialize(element)
+        @element = element
+      end
+    end
+  end
+end

data/lib/brief/formatters/github_milestone_rollup.rb

@@ -0,0 +1,52 @@
+# The GithubMilestoneRollup formatter takes the raw input markdown
+# which specifies a relationship between the milestone and its child
+# issues with all of the necessary detail, and replaces it with a
+# bulleted list of links to the issues on github, with their titles,
+# assignee relationship, and current status
+#
+# So for example, given the raw input:
+#
+# --- BEGIN RAW INPUT
+#
+# ## Milestone Heading
+#
+# Content for the milestone description.
+#
+# ### Nested Issue One
+#
+# Detail for nested issue one.
+# Blah blah blah
+#
+# ### Nested Issue Two
+#
+# Detail for nested issue two
+#
+# --- END RAW INPUT ---
+#
+# We should get:
+#
+# --- BEGIN FORMATTED OUTPUT ---
+#
+# ## (Milestone Heading)[https://github.com/datapimp/brief/milestones/1]
+#
+# Content for milestone description
+#
+# ### (Nested Issue One)[https://github.com/datapimp/brief/issues/1]
+# Assigned To|Last Updated|Status
+# ---|---|---
+# datapimp|July 4, 2014|open
+#
+# ### (Nested Issue Two)[https://github.com/datapimp/brief/issues/2]
+# Assigned To|Last Updated|Status
+# ---|---|---
+# datapimp|July 4, 2014|open
+#
+# --- END FORMATTED OUTPUT ---
+#
+module Brief
+  module Formatters
+    class GithubMilestoneRollup < Base
+
+    end
+  end
+end