fact 0.1.1.a

data/.gitignore

@@ -0,0 +1 @@
+*~

data/Gemfile

@@ -0,0 +1,8 @@
+source :rubygems
+source "http://rubygems.org"
+source :rubyforge
+source "http://gems.rubyforge.org"
+source :gemcutter
+source "http://gemcutter.org"
+
+gem "highline"

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011, FireAphis (github.com/FireAphis). All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+  - Redistributions of source code must retain the above copyright notice, this
+    list of conditions and the following disclaimer.
+
+  - Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation 
+    and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS  PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS  "AS IS"  AND
+ANY EXPRESS OR  IMPLIED  WARRANTIES,  INCLUDING,  BUT NOT LIMITED TO,  THE IMPLIED 
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN  NO  EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS;  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING  IN  ANY  WAY  OUT  OF  THE  USE OF THIS SOFTWARE,  EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,63 @@
+Purpose and features
+====================
+
+FireAphisClearerTool (FACT) is a small project intended to make a life
+with ClearCase a little bit happier. The project tries to achieve the
+goal in two ways:
+
+1. Create an intuitive front end for IBM Rational ClearCase SCM.
+2. Create a library that simplifies the process of development of scripts
+   that interact with ClearCase.
+
+IBM Rational ClearCase comes bundled with two user interfaces: one 
+graphical and one command line based. Both, in my humble opinion, impact
+user productivity severely. The graphical interface requires unreasonable
+amount of mouse clicks for simple tasks, it doesn't support keyboard
+input, its output is obscure, it is inconsistent and it is ugly. The 
+command line tool tries to solve all the problems in the world thus having 
+a very complicated syntax and an enormous amount of commands and options.
+
+From my personal experience, I tend to perform same tasks over and over
+again. Each time I have to choose between tedious and cluttered GUI and
+looking through my notes for the correct combination of over sophisticated
+command line commands.
+
+This tool allows to perform the most common tasks in minimal amount of
+clicks and supplies only the necessary information in the most readable
+format, I could think of. Hope you will enjoy it too.
+
+
+CLI
+---
+
+By executing ```fact``` the user enters the CLI mode. This mode is designed
+to support common use cases. It is supposed to make the job done in minimum 
+key presses and without the need to remember numerous commands.
+
+Here's the current menus hierarchy of the CLI mode:
+
+```
+    Undelivered activities
+        |
+        --- Activity change set
+                |
+                --- File information
+                        |
+                        --- Change set predecessor diff
+```
+
+Dependencies
+============
+
+The tool requires Ruby, ClearCase cleartool (comes bundled with ClearCase) 
+and HighLine gem (http://highline.rubyforge.org/). Cleartool has to be on 
+your PATH.
+
+Tested with the following versions:
+
+- CentOS 5.3
+- Ruby 1.8.5 and 1.9.2
+- HighLine 1.6.1
+- IBM Rational ClearCase 7.0.1
+
+If you run it on different versions, let me know, so I can update the list.

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/bin/fact

@@ -0,0 +1,46 @@
+#!/usr/bin/ruby
+
+# FireAphisClearerTool (FACT) is a small project intended to make a life
+# with ClearCase a little bit happier. The project tries to achieve the
+# goal in two ways:
+#
+# 1. Create an intuitive front end for IBM Rational ClearCase SCM.
+# 2. Create a library that simplifies the process of development of scripts
+#    that interact with ClearCase.
+#
+# Execute +fact+ to enter the interactive mode. 
+# +fact+ is expected to be executed from a ClearCase view directory.
+# All the commands will be handled in respect to this view.
+#
+# It is possible to require +fact+ to access ClearCase from Ruby code.
+# Consult Fact::ClearCase for the list of the supported ClearCase operations.
+
+require "rubygems"
+require "fact"
+
+
+cc = Fact::ClearCase.new
+
+activity = Fact::Cli.choose_undelivered_activity
+
+unless activity.nil?
+  # Come back every time to showing the files in the activity
+  loop do
+    file_version = Fact::Cli.choose_file_from_activity(activity)
+
+    say("Fetching the file description... ")
+    version_info = cc.get_version_info(file_version)
+    say("Done")
+
+    puts ""
+    Fact::Cli.show_version_info(version_info)
+ 
+    puts ""
+    if version_info[:checkout] != "" and version_info[:checkout] != cc.get_current_view
+      say("The file is checked out in a different view. Check it in to diff.")
+    elsif agree("Compare with the change set predecessor?")
+      say("Graphical diff is being opened in an external application.")
+      cc.diff_other_version(file_version[:file], file_version[:version], version_info[:changeset_predecessor])
+    end
+  end
+end

data/fact.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "fact/version"
+
+Gem::Specification.new do |s|
+  s.name        = "fact"
+  s.version     = Fact::VERSION
+  s.authors     = ["FireAphis"]
+  s.email       = ["FireAphis@gmail.com"]
+  s.homepage    = "https://github.com/FireAphis/Fact"
+  s.summary     = %q{Interactive ClearCase CLI and ClearCase wrapper API.}
+  s.description = %q{A small project intended to make a life with ClearCase a little bit happier. It supplies an intuitive and interactive ClearCase CLI and ClearCase wrapper API.}
+
+  s.has_rdoc = true
+  s.extra_rdoc_files = ['bin/fact']
+  s.rdoc_options << '--main' << 'bin/fact' << '--include' << 'bin'
+
+  s.requirements << 'ClearCase ClearTool'
+  s.add_dependency('highline', '>= 1.6.0')
+
+  s.rubyforge_project = "fact"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/fact/activities_cli.rb

@@ -0,0 +1,96 @@
+
+# System libraries
+require "highline/import"
+
+# Local libraries
+require "fact/clearcase"
+require "fact/files_cli"
+
+
+module Fact
+
+class Cli
+
+  # Ask the user to choose from the list of all the undelivered activities
+  # in the current stream.
+  # Returns the name of the chosen activity.
+  #
+  def Cli.choose_undelivered_activity
+
+    cc = ClearCase.new
+
+    stream = cc.get_current_stream
+    return if stream==""
+
+    puts ""
+    say("The current stream is <%= color('#{stream}', BOLD) %>. Fetching the stream activities... ")
+    activities = cc.get_activities
+    say("Done.")
+
+    if activities.empty?
+      say("No undelivered activities.")
+    else
+      say("These are the undelivered activities in the current stream:")
+
+      return choose do |menu|
+        menu.prompt    = "Enter the activity number: "
+        menu.select_by = :index
+
+        # Add a menu entry for each activity
+        activities.each do |activity|
+          menu.choice(activity[:headline]) { activity[:name] }
+        end
+
+        # The last entry allows graceful exit
+        menu.choice("Exit") { exit(true) }
+
+      end
+    end
+
+  end
+
+
+  # Asks to choose from a list of files in the activity and returns the last version of
+  # the file in the activity in a hash with keys :file and :version.
+  #
+  def Cli.choose_file_from_activity(activity_name)
+
+    cc = ClearCase.new
+
+    puts ""
+    say("Fetching the change set for the activity <%= color('#{activity_name}', BOLD) %>... ")
+    changeset = cc.get_activity_change_set(activity_name)
+    say("Done.")
+
+    if changeset.empty?
+      say("The changeset is empty.")
+    else
+      say("The activity contains the following files:")
+
+      # The method will return the choice from the menu
+      return choose do |menu|
+        menu.prompt    = "Enter the file number: "
+        menu.select_by = :index
+
+        #  Add a menu entry for each file in the changeset
+        changeset.each do |file, versions|
+          # Suffix contains the versions count and the check-out indicator
+          suffix = "version#{"s" unless versions.size<2}) #{"<%= color('CHECKED-OUT!', :red) %>" if cc.checkout_version?(versions.last)}"
+          menu.choice("#{file} (#{versions.size} #{suffix}") { {:file => file, :version => versions.last} }
+        end
+
+        # The last entry allows graceful exit
+        menu.choice("Exit") { exit(true) }
+
+      end
+    end
+
+  end
+
+
+end
+
+end
+
+
+

data/lib/fact/clearcase.rb

@@ -0,0 +1,168 @@
+
+
+module Fact
+
+class ClearTool
+    def invoke(command_str)
+        return `cleartool #{command_str}`
+    end
+end
+
+class ClearCase
+
+  def initialize
+    @cleartool = ClearTool.new
+  end
+
+  # Get the name of the current stream.
+  #
+  def get_current_stream
+    return @cleartool.invoke("lsstream -s").rstrip
+  end
+
+  # Get the name of the current view.
+  #
+  def get_current_view
+    return @cleartool.invoke("lsview -s -cview").rstrip
+  end
+
+  # Get the previous version of the version specified in the arguments.
+  #
+  def get_previous_version(file, version)
+    return @cleartool.invoke("desc -pred -s #{create_cc_version(file,version)}").rstrip
+  end
+
+  # Get all the non-obsolete activities in the current view.
+  # Returns an array of hashes. Each hash represents an activity and contains 
+  # two keys: :name and :headline.
+  #
+  def get_activities
+    return parse_lsact_output(@cleartool.invoke('lsact -fmt "%[name]p,%[headline]p,"'))
+  end
+
+  # Get version information. The argument must be a hash with keys :file and :version.
+  # Returns a version info hash.
+  #
+  def get_version_info(file_version)
+
+    # Get the properties of the latest version of the file
+    version_str = create_cc_version(file_version[:file],file_version[:version])
+    format_str  = '"version=%Sn, activity=%[activity]p, date=%Sd, type=%m, predecessor=%PVn, user=%Fu, checkout=%Tf"'
+    curr_version_info = parse_describe_file(@cleartool.invoke("desc -fmt #{format_str} #{version_str}"))
+    return if curr_version_info.nil?
+
+    # Retreive all the change set to find the earliest version of the file in the change set
+    change_set = get_activity_change_set(curr_version_info[:activity])
+    return if change_set.nil?
+
+    # Get the file name component of the file version string
+    file = file_version[:file]
+
+    # Get versions array for the file
+    versions = change_set[file]
+
+    # Adding additional information to the existing hash
+    curr_version_info[:name] = file
+    curr_version_info[:changeset_predecessor] = get_previous_version(file, versions.first)
+    curr_version_info[:versions_count] = versions.size
+
+    return curr_version_info
+  end
+
+  # Returns the changes that were made as a part of the specified activity.
+  # Returns a hash where the key is a file names and the value is a list of versions of 
+  # that file. If there are no files in the activity, returns an empty hash.
+  #
+  def get_activity_change_set(activity_name)
+
+    # Get a string that is space separated list of all the versions in the activity
+    versions_dump = @cleartool.invoke("lsact -fmt \"%[versions]p\" #{activity_name}")
+
+    # Will convert the string into a hash of filenames and lists of version numbers
+    change_set = Hash.new { |hash,key| hash[key]=[] }
+
+    # Convert the string into a sorted array and iterate it
+    versions_dump.split(" ").sort.each do |version_str|
+      version = parse_cc_version(version_str)
+      change_set[version[:file]].push("#{version[:version]}")
+    end
+
+    return change_set
+  end
+
+  # Launches the default diff tool comparing two versions of a file.
+  # The first parameter is the name of an existing file. The second and the third 
+  # parameters are strings indicating versions of the same file.
+  # If one of the versions is checkedout then compared with the file as it appares
+  # currently on the disc. Beware that if the file is checked out from a different
+  # view, the diff will compare wrong files.
+  #
+  def diff_other_version(file, version1, version2)
+    ver1 = checkout_version?(version1) ? file : create_cc_version(file,version1)
+    ver2 = checkout_version?(version2) ? file : create_cc_version(file,version2)
+    #diff_process = fork { exec "cleartool diff -gra #{ver1} #{ver2}" }
+    #Process.detach(diff_process)
+    `cleartool diff -gra #{ver1} #{ver2}`
+  end
+
+  # Parses a string representing ClearCase element version and converts it into a hash
+  # with a key for each part of the version string.
+  #
+  # version_str is expected to be of the following form:
+  #
+  #       <file full path>@@<branch name>/{<version number>|CHECKEDOUT.<checkout number>}
+  #
+  # Returns a hash with the following keys: :file, :version.
+  #
+  def parse_cc_version(version_str)
+    if version_str =~ /(.*)@@(.+)\/(CHECKEDOUT\.)?(\d+)$/
+      return { :file => $1, :version => "#{$2}/#{$3}#{$4}" }
+    end
+  end
+
+  # Build a string that is a qualified ClearCase file version.
+  #
+  def create_cc_version(file, version)
+    return "#{file}@@#{version}"
+  end
+
+  # Parse the output of the cleartool describe command. The text is expected to be of a specific
+  # format and not the regular cleartool describe -long.
+  #
+  def parse_describe_file(describe_str)
+    if describe_str =~ /version=(.*), activity=(.*), date=(.*), type=(.*), predecessor=(.*), user=(.*), checkout=(.*)$/
+      return { :version=>$1, :activity=>$2, :date=>$3, :type=>$4, :predecessor=>$5, :user=>$6, :checkout=>$7 }
+    end
+  end
+
+  # Converts the textual result of the lsact command into an array of activities.
+  # The input string is expected to be of the following format:
+  #
+  #       (<activity name>,<activity headline>,)*
+  #
+  # Returns an array of hashes. Each hash has two keys: :name and :headline.
+  #
+  def parse_lsact_output(lsact)
+
+    activities = []
+
+    # Takes the string and convers it to an array of name-headline pairs
+    lsact.scan(/(.*?),(.*?),/).each do |pair|
+      activities += [{ :name => pair[0], :headline => pair[1] }]
+    end
+
+    return activities
+  end
+
+  def checkout_version?(version)
+    return version =~ /CHECKEDOUT/
+  end
+
+  def cleartool=(new_ct)
+    @cleartool = new_ct
+  end
+
+end
+
+end
+

data/lib/fact/files_cli.rb

@@ -0,0 +1,44 @@
+
+# System libraries
+require "highline/import"
+
+# Local libraries
+require "fact/clearcase"
+
+
+module Fact
+
+class Cli
+
+  # Format and print to stdout the specified information.
+  # The parameter must be a hash with the following keys:
+  #
+  #     :version, :name, :activity, :date, :user,
+  #     :versions_count, :changeset_predecessor
+  #
+  def Cli.show_version_info(info)
+
+    cc = ClearCase.new
+
+    if cc.checkout_version?(info[:version])
+      last_ver_text = "<%= color('CHECKED-OUT!', :red) %> in #{info[:checkout]}"
+    else
+      last_ver_text = "#{info[:version]}"
+    end
+
+    # Spliting the path and the name so the name can be shown in bold
+    path      = info[:name].scan(/.*\//)[0]
+    file_name = info[:name].scan(/\/[^\/]+$/)[0]
+    file_name.slice!(0) # Removing the leading slash
+
+    say("#{path}<%= color('#{file_name}', BOLD) %>")
+    say("    Last activity:")
+    say("        Activity name: #{info[:activity]}")
+    say("        Last version:  #{last_ver_text}")
+    say("                       created on #{info[:date]} by #{info[:user]}")
+    say("                       #{info[:versions_count]-1} more version#{"s" unless info[:versions_count]==2} in the activity")
+    say("    Activity predecessor: #{info[:changeset_predecessor]}")
+  end
+
+end
+end

data/lib/fact/version.rb

@@ -0,0 +1,3 @@
+module Fact
+  VERSION = "0.1.1.a"
+end

data/lib/fact.rb

@@ -0,0 +1,5 @@
+require "fact/version"
+require "fact/clearcase"
+require "fact/activities_cli"
+require "fact/files_cli"
+

data/test/tests.rb

@@ -0,0 +1,105 @@
+#!/usr/bin/ruby
+
+require "rubygems"
+require "test/unit"
+require "fact"
+
+class MockClearTool
+
+  def initialize
+    @invocations = []
+    @succeeded = true
+  end
+
+  def succeeded
+    @succeeded
+  end
+
+  def add_invocation(command, result)
+    @invocations.push( { :command => command,
+                         :result  => result   } )
+  end
+
+  def invoke(command)
+    next_invocation = @invocations.shift
+    err_msg = "Wrong invocation: expected '#{next_invocation[:command]}', actual '#{command}'"
+    if command != next_invocation[:command]
+      @succeeded = false
+      throw(:wrongInvocation, err_msg)
+    else
+      return next_invocation[:result]
+    end
+  end
+
+end
+
+class ClearCaseWrapperTests < Test::Unit::TestCase
+
+  def test_parse_cc_version
+    cc = Fact::ClearCase.new
+    result = cc.parse_cc_version("/home/FireAphis/views/fireaphis_fact_1.0/vobs/fact/test/test.cpp@@/main/fact_1.0_Integ/fireaphis_fact_1.0/12");
+    assert_not_nil(result)
+    assert_equal("/home/FireAphis/views/fireaphis_fact_1.0/vobs/fact/test/test.cpp", result[:file])
+    assert_equal("/main/fact_1.0_Integ/fireaphis_fact_1.0/12", result[:version])
+  end
+
+
+  def test_parse_lsact_output
+    cc = Fact::ClearCase.new
+
+    result = cc.parse_lsact_output("name_1,headline 1,")
+    expected = [ { :name => "name_1", :headline => "headline 1" } ]
+    assert_equal(expected, result)
+
+    result = cc.parse_lsact_output("name_1,headline 1,name_1,headline 1,name_1,headline 1,")
+    expected = [ { :name => "name_1", :headline => "headline 1" },
+                 { :name => "name_1", :headline => "headline 1" },
+                 { :name => "name_1", :headline => "headline 1" } ]
+    assert_equal(expected, result)
+
+    result = cc.parse_lsact_output("name_1,headline 1,name_2,headline 2,name_3,headline 3,")
+    expected = [ { :name => "name_1", :headline => "headline 1" },
+                 { :name => "name_2", :headline => "headline 2" },
+                 { :name => "name_3", :headline => "headline 3" } ]
+    assert_equal(expected, result)
+  end
+
+
+  def test_parse_describe_file
+    cc = Fact::ClearCase.new
+
+    result = cc.parse_describe_file("version=/main/fact_1.0_Integ/fireaphis_fact_1.0/8, activity=test_fact, date=2011-05-08, type=version, predecessor=/main/fact_1.0_Integ/fireaphis_fact_1.0/7, user=FireAphis, checkout=fireaphis_fact_1.0")
+    expected = { :version     => "/main/fact_1.0_Integ/fireaphis_fact_1.0/8", 
+                 :activity    => "test_fact",
+                 :date        => "2011-05-08",
+                 :type        => "version",
+                 :predecessor => "/main/fact_1.0_Integ/fireaphis_fact_1.0/7",
+                 :user        => "FireAphis",
+                 :checkout    => "fireaphis_fact_1.0"}
+    assert_equal(expected, result)
+  end
+
+
+  def test_get_activity_change_set
+    # Define the expected calls
+    ct = MockClearTool.new
+    ct.add_invocation('lsact -fmt "%[versions]p" test_fact', '/home/fa/c@@/main/stream/100 ' +
+                                                             '/home/fa/a@@/main/stream/CHECKEDOUT.1234 ' +
+                                                             '/home/fa/b@@/main/stream/100 ' +
+                                                             '/home/fa/c@@/main/stream/102 ' +
+                                                             '/home/fa/c@@/main/stream/101 ' +
+                                                             '/home/fa/a@@/main/stream/200' )
+    cc = Fact::ClearCase.new
+    cc.cleartool = ct
+
+    change_set = {}
+    err = catch(:wrongInvocation) { change_set = cc.get_activity_change_set("test_fact") }
+    assert(ct.succeeded, err)
+
+    expected = {"/home/fa/a"=>["/main/stream/200", "/main/stream/CHECKEDOUT.1234"],
+                "/home/fa/b"=>["/main/stream/100"],
+                "/home/fa/c"=>["/main/stream/100", "/main/stream/101", "/main/stream/102"]}
+    assert_equal(expected, change_set)
+  end
+
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: fact
+version: !ruby/object:Gem::Version
+  version: 0.1.1.a
+  prerelease: 6
+platform: ruby
+authors:
+- FireAphis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-05-31 00:00:00.000000000 +03:00
+default_executable: 
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: highline
+  requirement: &83707590 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *83707590
+description: A small project intended to make a life with ClearCase a little bit happier.
+  It supplies an intuitive and interactive ClearCase CLI and ClearCase wrapper API.
+email:
+- FireAphis@gmail.com
+executables:
+- fact
+extensions: []
+extra_rdoc_files:
+- bin/fact
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/fact
+- fact.gemspec
+- lib/fact.rb
+- lib/fact/activities_cli.rb
+- lib/fact/clearcase.rb
+- lib/fact/files_cli.rb
+- lib/fact/version.rb
+- test/tests.rb
+has_rdoc: true
+homepage: https://github.com/FireAphis/Fact
+licenses: []
+post_install_message: 
+rdoc_options:
+- --main
+- bin/fact
+- --include
+- bin
+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: 1.3.1
+requirements:
+- ClearCase ClearTool
+rubyforge_project: fact
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Interactive ClearCase CLI and ClearCase wrapper API.
+test_files:
+- test/tests.rb