tool-shed 0.0.4

data/lib/shed/manifest.rb

@@ -0,0 +1,82 @@
+# encoding: utf-8
+
+#
+# Scans a specified source tree for ActionScript and MXML files and for each one
+# found creates a manifest entry. When complete writes the resulting manfiest
+# file to disk.
+#
+class Manifest < Tool
+  attr_reader :components,
+              :xml
+
+  def initialize(opt,out=STDOUT)
+    super(opt,out)
+
+    @filetypes = /\.(as|mxml)$/
+
+    build
+  end
+
+  #
+  # Generates a hash containing id and xml vales. The xml can be to be inserted
+  # into the manifest for the specified class.
+  #
+  def add(path, id)
+    log("Adding '#{path}'")
+
+    cp = ProjectTools.import(path)
+
+    { :key => id, :xml => "<component id=\"#{id}\" class=\"#{cp}\" />" }
+  end
+
+  #
+  # Search the provided path for as and mxml documents and return those found as
+  # a list.
+  #
+  def scan(path)
+    puts "Scanning '#{path}' for as and mxml files..."
+
+    found = []
+
+    Search.find_all(@filetypes,path,@excludes) do |p|
+      ext = File.extname(p)
+      cn = File.basename(p, ext)
+
+      found << add(p, cn) if cn =~ /^[A-Z]/
+    end
+
+    found.uniq! unless found.empty?
+
+    found
+  end
+
+  #
+  # Build the manifest file and save it to disk.
+  #
+  def build
+    @components = scan(@src)
+
+    if @components.empty?
+      puts "No ActionScript or Mxml files found."
+    else
+
+      @components.sort! {|a,b| a[:xml] <=> b[:xml] }
+
+      @xml = create_xml(@components)
+
+      #Open/Create the manifest file and write the output to it.
+      to_disk(@xml)
+    end
+  end
+
+  #
+  # Constructs the flex complier config file when given a list of paths to asdoc
+  # files.
+  #
+  def create_xml(comps)
+    x = "<?xml version='1.0'?>\n<componentPackage>\n"
+    comps.each { |c| x << "\t#{c[:xml]}\n" }
+    x << "</componentPackage>"
+    x
+  end
+end

data/lib/shed/opts/asdoc_package_opts.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+
+#
+# Manages the command line interface for the ASDoc Package File tool.
+#
+class ASDocPackageOpts < ToolOpts
+
+  def self.name
+    'as-docp'
+  end
+
+  def self.description
+    'ASDoc Package Builder'
+  end
+
+  def self.default_config
+    dc = superclass.default_config
+    dc[:output] = 'package-asdoc.xml'
+    dc
+  end
+
+end

data/lib/shed/opts/manifest_opts.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+
+#
+# Manages the command line interface for the AS3 Manifest File generation tool.
+#
+class ManifestOpts < ToolOpts
+
+  def self.description
+    "ActionScript Manifest Generator Tool"
+  end
+
+  def self.name
+    "as-manifest"
+  end
+
+  def self.default_config
+    dc = superclass.default_config
+    dc[:output] = "manifest.xml"
+    dc
+  end
+
+end

data/lib/shed/opts/tool_opts.rb

@@ -0,0 +1,114 @@
+# encoding: utf-8
+
+require 'optparse'
+
+#
+# Abstract layer for the tool shed options parsers. This sets the basic
+# paramaters the tools respond to via the command line.
+#
+class ToolOpts
+
+  #
+  # The name of the tool, as invoked on the command line.
+  #
+  def self.name
+    ToolShed::NAME
+  end
+
+  #
+  # A basic description of the tools use.
+  #
+  def self.description
+    'Tool'
+  end
+
+  #
+  # A version string to describe the version of the tool these options are
+  # designed to invoke.
+  #
+  def self.version
+    ToolShed::VERSION::STRING
+  end
+
+  #
+  # Default configuration hash.
+  #
+  def self.default_config
+    {
+      :src => ".",
+      :output => 'output.xml',
+      :verbose => false,
+      :silent => false
+    }
+  end
+
+  #
+  # Create and return the options parser with the default header.
+  #
+  def self.create_parser
+    op = OptionParser.new
+    op.banner = "Usage: #{name} [options]"
+
+    op.separator ""
+    op.separator "Options:"
+    op
+  end
+
+  #
+  # Add all mandatory arguments to the options parser.
+  #
+  def self.add_mandatory(op,config)
+  end
+
+  #
+  # Add all optional arguments to the options parser.
+  #
+  def self.add_optional(op,config)
+    op.on("-s", "--source [PATH]", String, "Path to source folder, defaults to current directory.") do |v|
+      config[:src] = v
+    end
+
+    op.on("-o", "--output [FILE PATH]", String, "Path to output file, defaults to #{config[:output]}") do |v|
+      config[:output] = v
+    end
+
+    op.on("-v", "--verbose", "Run verbosely") do |v|
+      config[:verbose] = v
+    end
+
+    op.on("--silent", "Supress all output.") do |v|
+      config[:silent] = v
+    end
+  end
+
+  def self.add_tail(op,out)
+    op.on_tail("-h", "--help", "Show this help message") do
+      out.puts op
+      exit
+    end
+
+    op.on_tail("--version", "Show version") do
+      out.puts "#{description} version #{version}"
+      exit
+    end
+  end
+
+  #
+  # Parse the arugments and return a config hash.
+  #
+  def self.parse(args,out=STDOUT)
+
+    config = default_config()
+    options = create_parser()
+
+    add_mandatory(options,config)
+    add_optional(options,config)
+
+    add_tail(options,out)
+
+    options.parse!(args)
+
+    config
+  end
+
+end

data/lib/shed/opts/unused_asset_opts.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+#
+# Manages the command line interface for the unused assets detection tool.
+#
+class UnusedAssetOpts < ToolOpts
+
+  def self.name
+    "as-asset-detector"
+  end
+
+  def self.description
+    " ActionScript Unused Asset Detection Tool"
+  end
+
+  def self.default_config
+    dc = superclass.default_config
+    dc[:output] = 'assets.txt'
+    dc[:manifest] = 'manifest.xml'
+    dc[:link_report] = 'link-report.xml'
+    dc
+  end
+
+end

data/lib/shed/opts/unused_class_opts.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+#
+# Manages the command line interface for the unused classes detection tool.
+#
+class UnusedClassOpts < ToolOpts
+
+  def self.name
+    "as-class-detector"
+  end
+
+  def self.description
+    "ActionScript unused class detection tool"
+  end
+
+  def self.default_config
+    dc = superclass.default_config
+    dc[:output] = 'classes.txt'
+    dc[:manifest] = 'manifest.xml'
+    dc[:link_report] = 'link-report.xml'
+    dc
+  end
+
+end

data/lib/shed/opts/unused_style_opts.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+
+#
+# Manages the command line interface for the unused style detection tool.
+#
+class UnusedStyleOpts < ToolOpts
+
+  def self.name
+    "as-style-detector"
+  end
+
+  def self.description
+    " ActionScript Unused Style Detection Tool"
+  end
+
+  def self.default_config
+    dc = superclass.default_config
+    dc[:output] = 'styles.txt'
+    dc[:css_dir] = 'style'
+    dc
+  end
+
+end

data/lib/shed/project_tools.rb

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+#
+# A collection of utility methods to help working with ActionScript source.
+#
+class ProjectTools
+
+  #
+  # Returns an array of directory names that are commonly used
+  # as the root directory for source files.
+  #
+  def self.common_src_dirs
+    ['src','source','test','lib']
+  end
+
+  #
+  # Takes a file path and truncates it to the last matching conventionally named
+  # source directory.
+  #
+  def self.truncate_to_src(path)
+    common_src_dirs.each do |remove|
+      path = path.gsub(/^.*\b#{remove}\b(\/|$)/, '');
+    end
+    path
+  end
+
+  #
+  # Removes any relative prefixes found in the provided path.
+  #
+  def self.remove_relative_prefix(path)
+    path.sub(/^\W+\b/, '')
+  end
+
+  #
+  # Takes a file path and converts it to a package path using conventionally
+  # named source folders as the root marker.
+  #
+  def self.package(path)
+    path = remove_relative_prefix(path)
+    path = File.dirname(path) if path =~ flex_file_regx
+    truncate_to_src(path).gsub('/','.')
+  end
+
+  #
+  # Takes a file path and converts it to a import path using conventionally
+  # named source folders as the root marker.
+  #
+  def self.import(path)
+    truncate_to_src(path).gsub('/','.').sub(flex_file_regx,'')
+  end
+
+  #
+  # Regular expression to match files we expect to find in a ActionScript/Flex
+  # project.
+  #
+  def self.flex_file_regx
+    /\.(as|mxml|asdoc)$/
+  end
+
+end

data/lib/shed/search.rb

@@ -0,0 +1,50 @@
+# encoding: utf-8
+
+#
+# Collection of methods for searching directories.
+#
+module Search
+
+  require 'find'
+
+  #
+  # Searches a directory and it's child directories for all the files whose
+  # names match the specified regular expression.
+  #
+  def self.find_all(files_of_type,dir,excluding=[])
+
+    Find.find(dir) do |path|
+      if FileTest.directory?(path)
+
+        if excluding.include?(File.basename(path))
+          Find.prune
+        else
+          next
+        end
+
+      elsif File.extname(path) =~ files_of_type
+        yield path
+      end
+    end
+  end
+
+  #
+  # Scans the path and its children for empty directories.
+  #
+  def self.for_empties(path,excluding=[])
+
+    Find.find(path) do |p|
+
+      if FileTest.directory?(p)
+        if excluding.include?(File.basename(p))
+          Find.prune
+        else
+          # Any dir that only contains ., .., and .svn or .git are empty.
+          yield p if Dir.entries(p).join =~ /^\.\.\.(\.(svn|git))?$/
+        end
+      end
+
+    end
+
+  end
+end

data/lib/shed/stripper.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+module Stripper
+
+  class << self
+
+    #
+    # Strips xml comments from the document.
+    #
+    def xml_comments(str)
+      str.gsub!(/<!--(?:.|([\r\n]))*?-->/,'')
+      str.gsub(/<!--.*-->/,'')
+      str
+    end
+
+    #
+    # Strips comments from the document.
+    #
+    def ecma_comments(str)
+
+      str.gsub!(/\/\*(?:.|([\r\n]))*?\*\//,'')
+
+      # This is designed to leave whitespace in
+      # place so the caret position remains correct.
+      #do |s|
+      #  if $1
+      #    a = s.split("\n")
+      #    r = "\n" * (a.length-1) if a.length > 1
+      #    r
+      #  end
+      #end
+
+      str.gsub!(/\/\/.*$/,'')
+      str
+
+    end
+
+    #
+    # Strips both xml and ecma script comments.
+    #
+    def comments(str)
+      str = xml_comments(str)
+      str = ecma_comments(str)
+      str
+    end
+
+  end
+
+end

data/lib/shed/tool.rb

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+#
+# Abstract base class for tools. Provides basic default settings, and allows
+# control over the level of logging to standard out.
+#
+class Tool
+
+  INVALID_OPTS = "Warning Invalid Options."
+
+  def initialize(opt,out=STDOUT)
+    @src      = opt[:src] || '.'
+    @output   = opt[:output] || 'tool-shed.txt'
+    @verbose  = opt[:verbose] || false
+    @silent   = opt[:silent] || false
+    @excludes = opt[:excludes] || ['.svn','.git']
+    @out      = out
+  end
+
+  #
+  # Puts the message unless we are in silent mode.
+  #
+  def puts(msg)
+    @out.puts msg unless @silent
+  end
+
+  #
+  # Puts the message if we are in verbose mode (but not in silent mode).
+  #
+  def log(msg)
+    puts msg if @verbose
+  end
+
+  #
+  # Validates the opts the tool has been invoked with.
+  #
+  def valid_opts
+    true
+  end
+
+  #
+  # Write the requested string to the output file.
+  #
+  def to_disk(str)
+    f = File.open(@output, "w")
+    f.puts str
+    f.flush
+    f.close
+
+    puts "Saved result to #{File.expand_path(@output)}."
+  end
+
+  #
+  # Generate a timestamp to include in reports.
+  #
+  def generated_at
+    "Generated at" + Time.now.strftime(" [%m/%d/%Y %H:%M:%S] ")
+  end
+
+end

data/lib/shed/unused_asset.rb

@@ -0,0 +1,68 @@
+# encoding: utf-8
+
+#
+# This script scans all Actionscript classes and CSS files in a project to
+# identify assets, like PNG files, that are in the project source tree but are
+# no longer used by the application.
+#
+class UnusedAsset < Tool
+  def initialize(opt,out=STDOUT)
+    super(opt,out)
+
+    @link_report = opt[:link_report]
+    @manifest = opt[:manifest]
+
+    unless valid_opts
+      @out.puts "#{INVALID_OPTS} One or all of specified link report, manifest file, and source directories does not exist."
+      return
+    end
+
+    @declared_regex = /^TODO/
+
+    detect
+
+    @report = describe
+
+    to_disk(@report)
+  end
+
+  def valid_opts
+    File.exist?(@link_report) && File.exist?(@manifest) && File.exist?(@src) rescue false
+  end
+
+  def detect
+    @declared = scan_dirs(/\.(css|as|mxml)/, @src, @declared_regex)
+  end
+
+  private
+
+  #
+  # Scans directories for all files that match the file extension regex, and
+  # for each match goes on to scan that document for items matching the syntax
+  # regex.
+  #
+  def scan_dirs(extension_regex,path,syntax_regex)
+    d = []
+
+    Search.find_all(extension_regex,path,@excludes) do |path|
+      d << scan_doc(path,syntax_regex)
+    end
+
+    d.flatten!.sort!.uniq! unless d.empty?
+    d
+  end
+
+  #
+  # Opens the document specified by path and returns a list of all first capture
+  # group matches, after stripping comments.
+  #
+  def scan_doc(path,regex)
+    n = []
+    f = File.open(path,"r").read.strip
+    f = Stripper.comments(f)
+    f.scan(regex) do |style_name|
+      n << $1
+    end
+    n
+  end
+end

data/lib/shed/unused_class.rb

@@ -0,0 +1,102 @@
+# encoding: utf-8
+
+#
+# This tool compares a mxmlc generated link-report against a manifest file
+# created by the as-manifest tool to identify files that are in the project
+# source tree but are no longer used by the application.
+#
+# Before executing this script make sure the relevant link reports and manifest
+# files have been generated.
+#
+class UnusedClass < Tool
+  attr_reader :report,
+              :empty_packages,
+              :unused_classes
+
+  def initialize(opt,out=STDOUT)
+    super(opt,out)
+
+    @link_report = opt[:link_report]
+    @manifest = opt[:manifest]
+    @link_regex = /<script name=".*\/(\w+)\.(as|mxml)/
+    @manifest_regex = /<component id="(\w+)"/
+
+    unless valid_opts
+      @out.puts "#{INVALID_OPTS} One or all of the specified link report, manifest file, or source directory does not exist."
+      return
+    end
+
+    detect
+
+    @report = describe
+
+    to_disk(@report)
+  end
+
+  def valid_opts
+    File.exist?(@link_report) && File.exist?(@manifest) && File.exist?(@src) rescue false
+  end
+
+  def detect
+    puts "Scanning project for classes that are uncompiled..."
+
+    @manifest_classes = linked(@manifest, @manifest_regex, 'manifest')
+    @link_classes = linked(@link_report, @link_regex, 'link-report')
+
+    @unused_classes = @manifest_classes-@link_classes
+    @empty_packages = empties(@src)
+
+    puts "Unused classes: #{@unused_classes.length.to_s}"
+    puts "Empty packages: #{@empty_packages.length.to_s}"
+  end
+
+  private
+
+  #
+  # Scans the path for empty directories and lists them.
+  #
+  def empties(path)
+    e = []
+    Search.for_empties(path) { |p| e << p.sub( /^.*src\//, "") }
+    e
+  end
+
+  #
+  # Returns a string detailing the findings of the unused class detection.
+  #
+  def describe
+    d = generated_at
+    d << add_desc(" classes are in the manifest but not in the link report:", @unused_classes)
+    d << add_desc(" packages appear to be empty:", @empty_packages)
+    d
+  end
+
+  #
+  # Prints a description category.
+  #
+  def add_desc(txt,list)
+    l = list.empty? ? '' : list.join("\n")
+    "#{list.length} #{txt}\n#{l}"
+  end
+
+  #
+  # Collects all the lines in the specified link file matching the regular
+  # expression and returns them in a list.
+  #
+  def linked(link,rgx,desc)
+    log("Loading #{desc}: #{File.expand_path(link)}")
+
+    classes = []
+
+    return classes unless !link.nil? && File.exists?(link)
+
+    IO.readlines(link).each { |line|
+      if line =~ rgx
+          classes << $1.to_s
+      end
+    }
+
+    classes
+  end
+
+end