topicz 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a22e7da57e83490f3607152af595bec565270200
+  data.tar.gz: 52a68b28cf5a622b7444ee0170ae45db753610ff
+SHA512:
+  metadata.gz: 1ad1e9d6067d868e516c681c35cdf68c60ee00933b59ebbf1eb03a4df6154ba05a2200ed85e4450edd4d199f366d17ad183e31bc01e90bd1fb0c2606e3c4756f
+  data.tar.gz: 22716d00ed11955671a772d47d76871b5f99bf7fd46ebfbbb792b6a4c569daa991a06150a5391a91fc42b6c5ae1b8b036b04d89e288fbb50e3a4e60115e15c1f

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.idea/
+*.iml
+/bundle

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.1.2
+before_install: gem install bundler -v 1.10.6

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright (c) 2016 Vincent Oostindië
+
+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,109 @@
+# Topicz
+
+Topicz is a simple topic repository administration tool, where the repository is a regular filesystem.
+
+## Installation
+
+Install it as:
+
+    $ gem install topicz
+
+See below (*Development*) in case you’re working with a Git clone directly.
+
+## Usage
+
+    $ topicz —help
+    Usage: topicz [options] <command> [options]
+        -c, --config FILE  Uses FILE as the configuration file
+
+    Where <command> is one of: 
+
+      init   : Initializes a new topic repository
+      create : Creates a new topic
+      path   : Prints the full path to a topic
+      journal: Opens a (new) weekly journal entry for a topic
+      note   : Opens a new note for a topic
+      alfred : Searches in Alfred Script Filter format
+      report : Generates a weekly report of all topics
+      help   : Shows help about a command
+
+## Background
+
+In my daily work I have to deal with a lot of different topics. New topics pop up often and existing topics are in varying degree of completeness. Sometimes nothing happens to a topic for weeks. Sometimes topics are short-lived, sometimes they stick around for years. All in all, keeping track of all the topics I work on is a big challenge for me.
+
+The way my mind works: if I can’t find a structure to organize my work in, I feel stressed. But like everybody else I prefer to be relaxed. Also I don’t like proprietary formats or tools that force me in a specific way of working.
+
+So I created my own structure, completely filesystem based, and scripts on top of it to integrate it with the other tools I use on my Mac, like [Alfred](http://www.alfredapp.com). Topicz collects all those scripts into a consistent, single command-line interface that I can easily change and extend whenever I need.
+
+## The topic repository
+
+A topic repository is nothing more than a directory on disk. This directory has subdirectories, one for each topic. The name of the subdirectory is what you like it to be. A topic, in turn, holds a number of directories. Here’s a basic layout:
+
+    . (topic root)
+    ├── Topic 1
+    │   ├── topic.yaml
+    │   ├── Documents
+    │   ├── Journal
+    │   ├── Logs
+    │   └── Reference Material
+    ├── Topic 2
+    ├── Topic …
+    └── Topic n
+
+The `topic.yaml` file is entirely optional. More information on that later.
+
+A topic can certainly have other subdirectories than the ones shown above. These four are the ones I always use. Where needed I add more. For example when I go to a conference, I typically add the directories `Travel` and `Bills`. 
+
+### Documents and Reference Material
+
+The `Documents` and `Reference Material` directories speak for themselves. The first is for stuff I create, the second for stuff that others create. There are no rules as to the files and subdirectories in these directories, although I tend to prefix each filename with the date I created or received the file in `YYYY-mm-DD` format. But that’s just my way of keeping things organized.
+
+### Journal
+
+The `Journal` directory is more interesting. It contains Markdown files only, and each filename follows the pattern `<year>-week-<week>.md`. If there was some kind of progress on a topic in a certain week, I describe it here. Every week I send a progress report to my colleagues about all the topics I worked on. Topicz’s `report` command creates this report for me automatically from the separate journal entries. And of course Topicz also helps me creating and opening the right journal files, depending on the topic I work on. 
+
+### Notes
+
+The `Notes` directory is for meeting notes, scratchpads, reminders, whatever. Every note is a Markdown file and each filename follows the pattern `<YYYY-mm-DD> <subject>.md`. Again Topicz helps me to quickly create and open notes for the topic I’m working on.
+
+## Repository configuration
+
+Topicz needs to know just one thing: where your repository is. You stick this into a configuration file, and tell Topicz about this file using the `-c` flag. If you have one topic repository, you can also store this file as `~/.topiczrc`. Then you don’t need to specify it when using the CLI.
+
+The first time you use Topicz, just do this:
+
+    $ topics init /path/to/my/topic/repository
+
+Topicz will do two things. First it will create an empty directory at the location you specified. Secondly it will write this location into `~/.topiczrc`.
+
+Some commands call an external text editor, for example to edit journals and notes. By default Topicz will use the `EDITOR` environment variable. You can override it on a per-repository basis by defining an `editor` property in the configuration file.
+
+## Topic configuration
+
+Each topic directory can have a `topic.yaml` file in it, which holds a YAML file describing that topic. It looks as follows:
+
+    title: <topic title>
+    id: <topic ID>
+
+If the YAML file is missing, or a field in the file is missing, then Topicz falls back on sensible defaults: the title is set to the name of the topic directory, and the ID is generated from this name by lowercasing it, replacing whitespace with hyphens, and removing strange characters.
+
+> This file is where I’m planning to add lots of functionality to. For example to store topic relationships, or to store metadata. See *Plans* below.
+
+You’re free to edit this file at any time, although Topicz also provides commands to help you do this. You never actually need to edit these YAML files themselves, if you don’t want to.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Plans
+
+* Allow topics to be archived when no longer relevant.
+* Allow relationships between topics to be defined in the YAML files, and use these to generate graphs for Graphviz: `depends-on`, `part-of`, `relates-to`. The CLI will help to guarantee correctness, for example when archiving a topic, or when renaming one’s title and/or ID.
+* Allow metadata to be defined for each topic, like main stakeholders, categories and topic goals.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/voostindie/topicz.
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "topicz"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/topicz

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require 'topicz/application'
+
+begin
+  Topicz::Application.new.run
+rescue Exception => e
+  if e.message != 'exit' # There's probably a better way to do this...
+    puts e.message
+    exit -1
+  end
+end

data/lib/topicz/application.rb

@@ -0,0 +1,44 @@
+require 'topicz/version'
+require 'topicz/command_factory'
+require 'optparse'
+require 'yaml'
+
+module Topicz
+
+  class Application
+
+    attr_reader :command
+
+    def initialize(arguments = ARGV, factory = CommandFactory.new)
+      config_file = nil
+      OptionParser.new do |options|
+        options.banner = 'Usage: topicz [options] <command> [options]'
+        options.program_name = 'topicz'
+        options.version = Topicz::VERSION
+        options.on('-c', '--config FILE', 'Uses FILE as the configuration file') do |file|
+          config_file = file
+        end
+        options.separator ''
+        options.separator 'Where <command> is one of: '
+        options.separator ''
+        options.separator Topicz::COMMANDS.to_s
+      end.order! arguments
+
+      unless arguments.empty?
+        command = arguments.shift
+        if Topicz::COMMANDS.has_key? command
+          @command = factory.create_command(command, config_file, arguments)
+        end
+      end
+    end
+
+    def run
+      if @command != nil
+        @command.execute
+      else
+        raise 'Invalid command. Try topicz --help'
+      end
+    end
+
+  end
+end

data/lib/topicz/command_factory.rb

@@ -0,0 +1,21 @@
+require 'topicz/commands/_index'
+
+module Topicz
+
+  class CommandFactory
+
+    def load_command(name)
+      unless COMMANDS.has_key?name
+        raise "Unsupported command: #{name}"
+      end
+      require "topicz/commands/#{name}_command"
+      Object.const_get("Topicz::Commands::#{name.capitalize}Command")
+    end
+
+    def create_command(name, config_file = nil, arguments = [])
+      load_command(name).new(config_file, arguments)
+    end
+
+  end
+
+end

data/lib/topicz/commands/_index.rb

@@ -0,0 +1,18 @@
+module Topicz
+
+  COMMANDS = {
+      'init'    => 'Initializes a new topic repository',
+      'create'  => 'Creates a new topic',
+      'path'    => 'Prints the full path to a topic',
+      'journal' => 'Opens a (new) weekly journal entry for a topic',
+      'note'    => 'Opens a new note for a topic',
+      'alfred'  => 'Searches in Alfred Script Filter format',
+      'report'  => 'Generates a weekly report of all topics',
+      'help'    => 'Shows help about a command',
+  }
+
+  def COMMANDS.to_s
+    COMMANDS.collect { |command, description| "  #{command.ljust(7)}: #{description}" }.join("\n")
+  end
+
+end

data/lib/topicz/commands/alfred_command.rb

@@ -0,0 +1,95 @@
+require_relative 'repository_command'
+require 'json'
+
+module Topicz::Commands
+
+  class AlfredCommand < RepositoryCommand
+
+    def initialize(config_file = nil, arguments = [])
+      super(config_file)
+      @identifiers = false
+      @mode = :browse
+      option_parser.order! arguments
+      @filter = arguments.join ' '
+    end
+
+    def option_parser
+      OptionParser.new do |options|
+        options.banner = 'Usage: alfred <filter>'
+        options.on('-m', '--mode MODE', 'Set the output mode') do |mode|
+          case mode.strip.downcase
+            when 'browse' then
+              @mode = :browse
+              @identifiers = false
+            when 'journal' then
+              @mode = :journal
+              @identifiers = true
+            when 'note' then
+              @mode = :note
+              @identifiers = true
+            else
+              raise "Invalid mode: '#{mode}'"
+          end
+        end
+        options.separator ''
+        options.separator 'Searches for topics and produces the result in JSON for Alfred\'s Script Filter'
+        options.separator ''
+        options.separator 'The filter specifies the text to search on. The text is matched against the topic\'s: '
+        options.separator '- path on the filesystem'
+        options.separator '- id, if specified in the topic\'s topic.yaml file'
+        options.separator '- title, if specified in the topic\'s topic.yaml file'
+        options.separator '- aliases, if specified in the topic\'s topic.yaml file'
+        options.separator ''
+        options.separator 'Supported modes are:'
+        options.separator '  browse  : For browsing through topics'
+        options.separator '  journal : For creating journal entries'
+        options.separator '  note    : For creating notes'
+        options.separator ''
+        options.separator 'Alfred automatically orders the items in its UI based on your usage.'
+      end
+    end
+
+    def execute
+      topics = @repository.find_all @filter
+      items = []
+      topics.each do |topic|
+        item = {
+            # https://www.alfredapp.com/help/workflows/inputs/script-filter/json/
+            uid: topic.id, # Affects the ordering in Alfred, based on learning
+            type: 'file',
+            title: topic.title,
+            subtitle: create_subtitle(topic),
+            arg: @identifiers ? topic.id : topic.fullpath,
+            icon: {
+                type: 'fileicon',
+                path: topic.fullpath
+            }
+        }
+        if @mode == :browse
+          item['mods'] = {
+              cmd: {
+                  subtitle: "Open topic '#{topic.title}' in Finder"
+              },
+              alt: {
+                  subtitle: "Open topic '#{topic.title}' in editor"
+              }
+          }
+        end
+        items << item
+      end
+      puts ({items: items}.to_json)
+    end
+
+    def create_subtitle(topic)
+      case @mode
+        when :browse then
+          "Browse topic '#{topic.title}' in Alfred Browser"
+        when :journal then
+          "Open this weeks journal entry for topic '#{topic.title}'"
+        when :note then
+          "Create a new note for topic '#{topic.title}'"
+      end
+    end
+
+  end
+end

data/lib/topicz/commands/create_command.rb

@@ -0,0 +1,48 @@
+require_relative 'repository_command'
+require 'topicz/defaults'
+require 'json'
+require 'zaru'
+require 'fileutils'
+
+module Topicz::Commands
+
+  class CreateCommand < RepositoryCommand
+
+    def initialize(config_file = nil, arguments = [])
+      super(config_file)
+      @title = arguments.join(' ').strip
+    end
+
+    def option_parser
+      OptionParser.new do |options|
+        options.banner = 'Usage: create <name>'
+        options.separator ''
+        options.separator 'Creates a new topic with the specified name'
+        options.separator ''
+        options.separator 'Basically all this command does is create a new directory structure to hold a topic.'
+        options.separator ''
+        options.separator 'It is an error if a topic with the specified name already exists.'
+      end
+    end
+
+    def execute
+      if @repository.exist_title?(@title)
+        raise "Topic already exists: '#{@title}'."
+      end
+      path = Zaru.sanitize! @title
+      fullpath = File.join(@repository.root, path)
+      if File.exist?(fullpath)
+        raise "Directory already exists: '#{path}'."
+      end
+      FileUtils.mkdir fullpath
+      Topicz::DIRECTORIES.each { |dir| FileUtils.mkdir(File.join(fullpath, dir)) }
+      if path != @title
+        File.open(File.join(fullpath, Topicz::TOPIC_FILE), 'w') do | file |
+          file.write(YAML.dump({'title' => @title}))
+        end
+      end
+      puts "Created topic '#{@title}'"
+    end
+
+  end
+end

data/lib/topicz/commands/editor_command.rb

@@ -0,0 +1,14 @@
+require_relative 'repository_command'
+
+module Topicz::Commands
+
+  class EditorCommand < RepositoryCommand
+
+    def editor
+      @config['editor'] ||
+          ENV['EDITOR'] ||
+          raise('No editor configured. Set one in the topicz configuraton file, or in the EDITOR environment variable.')
+    end
+
+  end
+end

data/lib/topicz/commands/help_command.rb

@@ -0,0 +1,31 @@
+require 'topicz/command_factory'
+
+module Topicz::Commands
+
+  class HelpCommand
+
+    def initialize(config_file = nil, arguments = [])
+      option_parser.order! arguments
+      @help =
+          if arguments == nil || arguments.empty?
+            self
+          else
+            Topicz::CommandFactory.new.load_command(arguments.shift).new
+          end.option_parser
+    end
+
+    def option_parser
+      OptionParser.new do |options|
+        options.banner = 'Usage: help <command>'
+        options.separator ''
+        options.separator 'Shows help about a specific command. Valid commands are:'
+        options.separator ''
+        options.separator Topicz::COMMANDS.to_s
+      end
+    end
+
+    def execute
+      puts @help.help
+    end
+  end
+end

data/lib/topicz/commands/init_command.rb

@@ -0,0 +1,61 @@
+require 'topicz/defaults'
+require 'fileutils'
+require 'optparse'
+require 'yaml'
+
+module Topicz::Commands
+
+  class InitCommand
+
+    def initialize(config_file = nil, arguments = [])
+      @config_file = Topicz::DEFAULT_CONFIG_LOCATION
+      option_parser.order! arguments
+      unless arguments.empty?
+        @directory = arguments.shift
+      end
+    end
+
+    def option_parser
+      OptionParser.new do |options|
+        options.banner = 'Usage: init [options] <directory>'
+        options.on('-c', '--config FILE') do |file|
+          @config_file = file
+        end
+        options.separator ''
+        options.separator 'Initializes a new topic repository. This creates a directory and writes its
+location into a configuration file.'
+        options.separator ''
+        options.separator 'If the directory already exists, this command fails.'
+        options.separator ''
+        options.separator 'If a configuration file already exists, it will not be overwritten.'
+      end
+    end
+
+    def execute
+      unless @directory
+        raise 'Pass the location of the new repository as an argument.'
+      end
+      if File.exist? @directory
+        raise "A file or directory already exists at this location: #{@directory}."
+      end
+      create_repository
+      create_configuration
+    end
+
+    def create_repository
+      FileUtils.mkdir_p(@directory)
+      puts "New topic repository created at: #{@directory}."
+    end
+
+    def create_configuration
+      if File.exist? @config_file
+        puts "Skipping creation of configuration file; one already exists at #{@config_file}."
+      else
+        File.open(@config_file, 'w') do |file|
+          file.write(YAML.dump({'repository' => @directory}))
+        end
+        puts "Configuration file saved to: #{@config_file}."
+      end
+    end
+  end
+end

data/lib/topicz/commands/journal_command.rb

@@ -0,0 +1,64 @@
+require_relative 'editor_command'
+require 'topicz/defaults'
+require 'json'
+require 'fileutils'
+
+module Topicz::Commands
+
+  class JournalCommand < EditorCommand
+
+    def initialize(config_file = nil, arguments = [], kernel = Kernel)
+      super(config_file)
+      @kernel = kernel
+      @strict = false
+      @week = Date.today.cweek
+      @year = Date.today.cwyear
+      option_parser.order! arguments
+      @filter = arguments.join ' '
+    end
+
+    def option_parser
+      OptionParser.new do |options|
+        options.banner = 'Usage: journal <filter>'
+        options.on('-s', '--strict', 'Do a full strict match on topic IDs only') do
+          @strict = true
+        end
+        options.on('-w', '--week WEEK', 'Use week WEEK instead of the current week') do |week|
+          @week = week.to_i
+        end
+        options.on('-y', '--year YEAR', 'Use year YEAR instead of the current year') do |year|
+          @year = year.to_i
+        end
+        options.separator ''
+        options.separator 'Opens the weekly journal for the specified topic.'
+        options.separator ''
+        options.separator 'The filter specifies the text to search on. The text is matched against the topic\'s: '
+        options.separator '- path on the filesystem'
+        options.separator '- id, if specified in the topic\'s topic.yaml file'
+        options.separator '- title, if specified in the topic\'s topic.yaml file'
+        options.separator '- aliases, if specified in the topic\'s topic.yaml file'
+        options.separator ''
+        options.separator 'The filter must return precisely one topic. Zero or more matches give an error.'
+      end
+    end
+
+    def execute
+      topic = find_exactly_one_topic(@filter, @strict)
+      path = File.join(topic.fullpath, Topicz::DIR_JOURNAL)
+      FileUtils.mkdir(path) unless Dir.exist? path
+
+      year = @year.to_s
+      week = @week.to_s.rjust(2, '0')
+      path = File.join(path, "#{year}-week-#{week}.md")
+
+      unless File.exists? path
+        File.open(path, 'w') do |file|
+          file.puts("# #{topic.title} - Week #{week}, #{year}")
+        end
+      end
+
+      @kernel.exec "#{editor} \"#{path}\""
+    end
+
+  end
+end

data/lib/topicz/commands/note_command.rb

@@ -0,0 +1,68 @@
+require_relative 'editor_command'
+require 'topicz/defaults'
+require 'json'
+require 'fileutils'
+require 'zaru'
+
+module Topicz::Commands
+
+  class NoteCommand < EditorCommand
+
+    def initialize(config_file = nil, arguments = [], kernel = Kernel)
+      super(config_file)
+      @kernel = kernel
+      @strict = false
+      option_parser.order! arguments
+      @filter = arguments.shift
+      @title = arguments.empty? ? nil : arguments.join(' ')
+    end
+
+    def option_parser
+      OptionParser.new do |options|
+        options.banner = 'Usage: note <filter> [<title>]'
+        options.on('-s', '--strict', 'Do a full strict match on topic IDs only') do
+          @strict = true
+        end
+        options.separator ''
+        options.separator 'Creates a new note for the specified topic.'
+        options.separator ''
+        options.separator 'The filter specifies the text to search on. The text is matched against the topic\'s: '
+        options.separator '- path on the filesystem'
+        options.separator '- id, if specified in the topic\'s topic.yaml file'
+        options.separator '- title, if specified in the topic\'s topic.yaml file'
+        options.separator '- aliases, if specified in the topic\'s topic.yaml file'
+        options.separator ''
+        options.separator 'The filter must return precisely one topic. Zero or more matches give an error.'
+        options.separator ''
+        options.separator 'The note title is optional. If omitted the title will be \'Unnamed note\'.'
+      end
+    end
+
+    def execute
+      topic = find_exactly_one_topic(@filter, @strict)
+      path = File.join(topic.fullpath, Topicz::DIR_NOTES)
+      FileUtils.mkdir(path) unless Dir.exist? path
+
+      if @title
+        date = DateTime.now.strftime('%Y-%m-%d')
+        title = @title
+        filename = Zaru.sanitize! "#{date} #{title}.md"
+      else
+        date = DateTime.now.strftime('%Y-%m-%d %H%M')
+        title = 'Unnamed note'
+        filename = "#{date}.md"
+      end
+
+      path = File.join(path, filename)
+
+      unless File.exists? path
+        File.open(path, 'w') do | file |
+          file.puts("# #{topic.title} - #{title}")
+        end
+      end
+
+      @kernel.exec "#{editor} \"#{path}\""
+    end
+
+  end
+end

data/lib/topicz/commands/path_command.rb

@@ -0,0 +1,39 @@
+require_relative 'repository_command'
+require 'json'
+
+module Topicz::Commands
+
+  class PathCommand < RepositoryCommand
+
+    def initialize(config_file = nil, arguments = [])
+      super(config_file)
+      @strict = false
+      option_parser.order! arguments
+      @filter = arguments.join ' '
+    end
+
+    def option_parser
+      OptionParser.new do |options|
+        options.banner = 'Usage: path <filter>'
+        options.on('-s', '--strict', 'Do a full strict match on topic IDs only') do
+          @strict = true
+        end
+        options.separator ''
+        options.separator 'Prints the absolute path to the topic that matches <filter>.'
+        options.separator ''
+        options.separator 'The filter specifies the text to search on. The text is matched against the topic\'s: '
+        options.separator '- path on the filesystem'
+        options.separator '- id, if specified in the topic\'s topic.yaml file'
+        options.separator '- title, if specified in the topic\'s topic.yaml file'
+        options.separator '- aliases, if specified in the topic\'s topic.yaml file'
+        options.separator ''
+        options.separator 'The filter must return precisely one topic. Zero or more matches give an error.'
+      end
+    end
+
+    def execute
+      print find_exactly_one_topic(@filter, @strict).fullpath
+    end
+
+  end
+end

data/lib/topicz/commands/report_command.rb

@@ -0,0 +1,50 @@
+require_relative 'repository_command'
+require 'json'
+
+module Topicz::Commands
+
+  class ReportCommand < RepositoryCommand
+
+    def initialize(config_file = nil, arguments = [])
+      super(config_file)
+      @week = Date.today.cweek
+      @year = Date.today.cwyear
+      option_parser.order! arguments
+      @filter = arguments.join ' '
+    end
+
+    def option_parser
+      OptionParser.new do |options|
+        options.banner = 'Usage: report'
+        options.on('-w', '--week WEEK', 'Use week WEEK instead of the current week') do |week|
+          @week = week.to_i
+        end
+        options.on('-y', '--year YEAR', 'Use year YEAR instead of the current year') do |year|
+          @year = year.to_i
+        end
+        options.separator ''
+        options.separator 'Generates a weekly report from all journals across all topics.'
+      end
+    end
+
+    def execute
+      year = @year.to_s
+      week = @week.to_s.rjust(2, '0')
+      path = File.join(Topicz::DIR_JOURNAL, "#{year}-week-#{week}.md")
+
+      @repository.topics.each do |topic|
+        journal = File.join(topic.fullpath, path)
+        next unless File.exist? journal
+
+        puts "## #{topic.title}"
+        puts
+        puts File.readlines(journal)
+                 .drop(2).join()          # Drop first 2 lines: title (week) and empty line
+                 .gsub(/^#(.*)/, '##\1')  # Add an extra '#' in front of every title
+                 .strip                   # Remove leading and ending whitespace
+        puts
+      end
+    end
+
+  end
+end

data/lib/topicz/commands/repository_command.rb

@@ -0,0 +1,61 @@
+require 'topicz/defaults'
+require 'topicz/repository'
+require 'yaml'
+
+module Topicz::Commands
+
+  class RepositoryCommand
+
+    def initialize(config_file = nil)
+      @config = load_config(config_file)
+      @repository = load_repository
+    end
+
+    def load_config(config_file)
+      file = config_file != nil ? config_file : Topicz::DEFAULT_CONFIG_LOCATION
+      unless File.exist? file
+        raise "File doesn't exist: #{file}."
+      end
+      unless File.readable? file
+        raise "File isn't readable: #{file}."
+      end
+      begin
+        config = YAML.load_file(file)
+      rescue
+        raise "Not a valid YAML file: #{file}."
+      end
+      unless config.has_key?('repository')
+        raise "Missing required property 'repository' in configuration file: #{file}."
+      end
+      config
+    end
+
+    def load_repository
+      directory = @config['repository']
+      unless Dir.exist? directory
+        raise "Repository directory doesn't exist: #{directory}."
+      end
+      Topicz::Repository.new(directory)
+    end
+
+    def find_exactly_one_topic(filter, strict)
+      if strict
+        topic = @repository[filter]
+        if topic == nil
+          raise "No topic found with ID: '#{filter}'"
+        end
+        topic
+      else
+        topics = @repository.find_all filter
+        if topics.length == 0
+          raise "No topics found matching the search filter: '#{filter}'"
+        end
+        if topics.length > 1
+          matches = topics.map { |t| t.title }.join("\n")
+          raise "Multiple topics match the search filter: '#{filter}'. Matches:\n#{matches}"
+        end
+        topics[0]
+      end
+    end
+  end
+end

data/lib/topicz/defaults.rb

@@ -0,0 +1,12 @@
+module Topicz
+  DEFAULT_CONFIG_LOCATION = File.join(Dir.home, '.topiczrc')
+
+  TOPIC_FILE = 'topic.yaml'
+
+  DIR_NOTES = 'Notes'
+  DIR_JOURNAL = 'Journal'
+  DIR_REFERENCE = 'Reference'
+  DIR_DOCUMENTS = 'Documents'
+
+  DIRECTORIES = [DIR_NOTES, DIR_JOURNAL, DIR_REFERENCE, DIR_DOCUMENTS]
+end

data/lib/topicz/repository.rb

@@ -0,0 +1,123 @@
+require 'yaml'
+
+module Topicz
+
+  class Repository
+
+    attr_reader :root
+
+    def initialize(root)
+      @root = root
+      @topics = {}
+      errors = []
+      Dir.foreach(root) do |path|
+        next if path.start_with?('.')
+        next unless File.directory?(File.join(root, path))
+        topic = Topic.new(root, path)
+        if @topics.has_key?(topic.id)
+          errors << "Error in topic '#{topic.title}': ID '#{topic.id}' is already in use."
+        end
+        @topics[topic.id] = topic
+      end
+      @topics.each_value do |topic|
+        topic.references.each do |ref|
+          unless @topics.has_key?(ref)
+            errors << "Error in topic '#{topic.title}': Reference to non-existing topic ID '#{ref}'."
+          end
+        end
+      end
+      unless errors.empty?
+        raise errors
+      end
+    end
+
+    def [](id)
+      @topics[id]
+    end
+
+    def exist_title?(title)
+      @topics.values.any? { |t| t.title == title }
+    end
+
+    def topics
+      @topics.values
+    end
+
+    def find_all(filter = nil)
+      @topics.values.select { |t| t.matches(filter) }
+    end
+
+  end
+
+  class Topic
+
+    attr_reader :id, :path, :title, :category, :aliases, :metadata
+
+    def initialize(root, path)
+      @root = root
+      @path = path
+
+      descriptor = File.join(@root, @path, 'topic.yaml')
+      yaml = if File.exist?(descriptor)
+               YAML.load_file(descriptor)
+             else
+               {}
+             end
+
+      @id = yaml['id'] || create_id(path)
+      @category = yaml['category'] || 'none'
+      @title = yaml['title'] || @path
+      @aliases = yaml['aliases'] || []
+      @parents = yaml['depends on'] || {}
+      @relations = yaml['relates to'] || {}
+      @metadata = yaml['metadata'] || {}
+    end
+
+    # Checks whether this topic's title or one of its aliases matches the filter
+    # The filter may be `nil`, in which case it is said to match.
+    def matches(filter)
+      return true unless filter
+      filter = filter.downcase
+      @title.downcase.include?(filter) ||
+          @id.downcase.include?(filter) ||
+          !(@aliases.select { |a| a.downcase.include?(filter) }.empty?) ||
+          @path.downcase.include?(filter)
+    end
+
+    # Full path to this topic on disk
+    def fullpath
+      File.join(@root, @path)
+    end
+
+    # List of unique topic IDs that this topic refers to.
+    def references
+      @parents.keys
+    end
+
+    def parents
+      @parents.keys
+    end
+
+    def relations
+      @relations.keys
+    end
+
+    def to_s
+      <<-EOS
+Topic '#{@id}' {
+  title: '#{@title}',
+  aliases: '#{@aliases}',
+  category: '#{@category}',
+  parents: #{@parents},
+  relations: #{@relations}
+}
+      EOS
+    end
+
+    private
+    def create_id(path)
+      path.downcase.gsub(/[\_,;\.\&]/, '').gsub(/[ ]/, '-').gsub(/\-\-/, '-')
+    end
+  end
+
+end

data/lib/topicz/version.rb

@@ -0,0 +1,3 @@
+module Topicz
+  VERSION = "0.1.0"
+end

data/topicz.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'topicz/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "topicz"
+  spec.version       = Topicz::VERSION
+  spec.authors       = ["Vincent Oostindië"]
+  spec.email         = ["vincent@ulso.nl"]
+
+  spec.summary       = %q{Filesystem based topic administration tool}
+  spec.description   = %q{Topicz is a filesystem based topic administration tool. All it does is manipulate files and directories. But it does so in a structured way, helping you to keep track of your own documents, reference material, and topic relationships.}
+  spec.homepage      = "https://github.com/voostindie/topicz"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'zaru', '~> 0.1.0'
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.3.0" # this one works with the IntelliJ Rake Runner plugin
+  spec.add_development_dependency "simplecov", "~> 0.11.2"
+  spec.add_development_dependency "fakefs", "~> 0.8.1"
+end

metadata

@@ -0,0 +1,170 @@
+--- !ruby/object:Gem::Specification
+name: topicz
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vincent Oostindië
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-06-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zaru
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.3.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.11.2
+- !ruby/object:Gem::Dependency
+  name: fakefs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.1
+description: Topicz is a filesystem based topic administration tool. All it does is
+  manipulate files and directories. But it does so in a structured way, helping you
+  to keep track of your own documents, reference material, and topic relationships.
+email:
+- vincent@ulso.nl
+executables:
+- topicz
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- exe/topicz
+- lib/topicz/application.rb
+- lib/topicz/command_factory.rb
+- lib/topicz/commands/_index.rb
+- lib/topicz/commands/alfred_command.rb
+- lib/topicz/commands/create_command.rb
+- lib/topicz/commands/editor_command.rb
+- lib/topicz/commands/help_command.rb
+- lib/topicz/commands/init_command.rb
+- lib/topicz/commands/journal_command.rb
+- lib/topicz/commands/note_command.rb
+- lib/topicz/commands/path_command.rb
+- lib/topicz/commands/report_command.rb
+- lib/topicz/commands/repository_command.rb
+- lib/topicz/defaults.rb
+- lib/topicz/repository.rb
+- lib/topicz/version.rb
+- topicz.gemspec
+- vendor/cache/diff-lcs-1.2.5.gem
+- vendor/cache/docile-1.1.5.gem
+- vendor/cache/fakefs-0.8.1.gem
+- vendor/cache/json-1.8.3.gem
+- vendor/cache/rake-10.5.0.gem
+- vendor/cache/rspec-3.3.0.gem
+- vendor/cache/rspec-core-3.3.2.gem
+- vendor/cache/rspec-expectations-3.3.1.gem
+- vendor/cache/rspec-mocks-3.3.2.gem
+- vendor/cache/rspec-support-3.3.0.gem
+- vendor/cache/simplecov-0.11.2.gem
+- vendor/cache/simplecov-html-0.10.0.gem
+- vendor/cache/zaru-0.1.0.gem
+homepage: https://github.com/voostindie/topicz
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.6
+signing_key: 
+specification_version: 4
+summary: Filesystem based topic administration tool
+test_files: []