tool-shed 0.0.5 → 0.0.7

data/README.md

@@ -3,46 +3,70 @@
 A collection of utility scripts to help working with ActionScript and Flex 
 projects. These scripts are under development, so **don't** expect reliability.
 
+All tools have help available on the command line, to view use:
+
+    as-tool-name -h
+
 ### as-docp
 
-The `as-docp` tool is a utility that can be used to generate a flex config file 
-from package level ASDoc files. For each package you want to document place your
-asdoc comments in a file with a .asdoc suffix. The `as-docp` tool can then be
-used to gather these together in a flex-config.xml file to pass to the asdoc 
-tool when building your documentation.
+The `as-docp` tool can be used to generate a `flex-config.xml` file from package
+level ASDoc files. This can then be used by the `asdoc` tool when generating
+ASDocs for your project.
+
+To document a package create a single file with a `.asdoc` suffix to contain
+your ASDoc comments.
+
+Example use:
+
+    as-docp -s src -o tmp/asdocp-config.xml
 
 ### as-manifest
 
 Scans a specified source tree for ActionScript and MXML files and for each one
 found creates a manifest entry. When complete writes the results to disk.
 
-### as-class-dector
+Example use:
+
+    as-manifest
+    as-manifest -s source/main -o project-manifest.xml
+    as-manifest -f 'org.helvector'
+
+### as-class-vacuum
 
-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.
+Compares a `mxmlc` generated `link-report.xml` against a `manifest.xml` file to
+identify files that are in a project source tree but are no longer compiled
+into the application.
 
-Before executing this script make sure the relevant link reports and manifest
-files have been generated.
+Example use:
 
-### as-style-dector
+    as-class-vacuum -s src/main -o report/vacuum/class.xml -l report/link/app-link-report.xml -m manifest.xml
 
-Detects styles that are not used in a Flex application.
+To generate a link report via mxmlc use `mxmlc -link-report=report.xml`
 
-### as-asset-dector
+### as-style-vacuum
 
-Under development. This script scans all ActionScript classes and CSS files in a
-project to identify assets, such as png files, that are in the project source
-tree but are no longer referenced by the application.
+Loads all styles defined in **css** files (mxml isn't included) and identifies
+styles that are not referenced in the source tree.
+
+Example use:
+
+    as-style-vacuum -c source/assets -s source/main -o report/vacuum/style.xml
+
+### as-asset-vacuum
+
+This script scans a source tree for assets of types `jpg, jpeg, png, otf, ttf, 
+swf, svg, mp3, gif` then searches all ActionScript, CSS and MXML files to 
+identify which assets are not referenced in the source files.
+
+Example use:
+    
+    as-asset-vacuum
+    as-asset-vacuum -s source/main -o report/vacuum/asset.xml
 
 ## Install
 
     gem install tool-shed
 
-## Using
-
-Examples will follow once the tools are in a stable state.
-  
 ## Authors
 
 [Simon Gregory](http://simongregory.com)
@@ -51,4 +75,3 @@ Examples will follow once the tools are in a stable state.
 
 Released under the MIT License. Please see the accompanying [LICENSE](LICENSE) document for
 details.
-

data/bin/{as-asset-detector → as-asset-vacuum}

@@ -6,8 +6,8 @@ require 'tool_shed'
 
 begin
 
-  opt = UnusedAssetOpts.parse(ARGV)
-  UnusedAsset.new(opt)
+  opt = AssetVacuumOpts.parse(ARGV)
+  AssetVacuum.new(opt)
 
 rescue OptionParser::ParseError => e
 

data/bin/{as-class-detector → as-class-vacuum}

@@ -6,8 +6,8 @@ require 'tool_shed'
 
 begin
 
-  opt = UnusedClassOpts.parse(ARGV)
-  UnusedClass.new(opt)
+  opt = ClassVacuumOpts.parse(ARGV)
+  ClassVacuum.new(opt)
 
 rescue OptionParser::ParseError => e
 

data/bin/{as-style-detector → as-style-vacuum}

@@ -6,8 +6,8 @@ require 'tool_shed'
 
 begin
 
-  opt = UnusedStyleOpts.parse(ARGV)
-  UnusedStyle.new(opt)
+  opt = StyleVacuumOpts.parse(ARGV)
+  StyleVacuum.new(opt)
 
 rescue OptionParser::ParseError => e
 

data/bin/as-vacuum

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.dirname(__FILE__) + '/../lib'
+
+require 'tool_shed'
+
+begin
+
+  opt = VacuumOpts.parse(ARGV)
+  Vacuum.new(opt)
+
+rescue OptionParser::ParseError => e
+
+  puts e
+
+end

data/lib/shed/asdoc_package.rb

@@ -23,16 +23,16 @@ class ASDocPackage < Tool
   #
   # Scan the given path and it's child directories for all .asdoc files.
   #
-  def scan(path)
-    puts "Scanning '#{path}' for asdoc files..."
+  def scan(dir)
+    puts "Scanning '#{dir}' for asdoc files..."
 
     found = []
 
-    Search.find_all(@asdoc,path,@excludes) do |p|
-      found << {:path => p, :package => ProjectTools.package(p)}
+    Search.find_all(@asdoc,dir,@excludes) do |path|
+      found << {:path => path, :package => ProjectTools.package(path)}
     end
 
-    found.each { |f| log("Adding #{f[:path]}") }
+    found.each { |file| log("Adding #{file[:path]}") }
 
     found
   end
@@ -46,8 +46,8 @@ class ASDocPackage < Tool
     if asdocs.empty?
       puts "No .asdoc files found."
     else
-      @xml = create_xml(asdocs)
-      to_disk(@xml)
+      create_xml(asdocs)
+      to_disk(xml)
     end
   end
 
@@ -56,9 +56,9 @@ class ASDocPackage < Tool
   # files.
   #
   def create_xml(asdocs)
-    x = @header
-    asdocs.each { |d| x << sprintf(@package, d[:package], IO.read(d[:path])) }
-    x << @footer
-    x
+    @xml = @header
+    asdocs.each { |asdoc| @xml << sprintf(@package, asdoc[:package], IO.read(asdoc[:path])) }
+    @xml << @footer
+    @xml
   end
 end

data/lib/shed/asset_vacuum.rb

@@ -0,0 +1,85 @@
+# 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 AssetVacuum < Tool
+  attr_reader :assets, :declared, :unused
+
+  def initialize(opt,out=STDOUT)
+    super(opt,out)
+
+    @src = opt[:src]
+    @assets, @src_files, @declared = [], [], []
+
+    unless valid_opts
+      @out.puts "#{INVALID_OPTS} The source directory does not exist."
+      return
+    end
+
+    detect
+
+    @report = describe
+
+    to_disk(@report)
+  end
+
+  #
+  # Valid if the specified project directory exists.
+  #
+  def valid_opts
+    File.exist?(@src) rescue false
+  end
+
+  def detect
+    puts "Scanning project for assets that are unused..."
+
+    Search.find_all(/\.(jpg|jpeg|png|otf|ttf|swf|svg|mp3|gif)$/,@src,@excludes) do |path|
+      @assets << path
+    end
+
+    src_dec = scan_dirs(/\.(as|mxml|css)$/, @src, /Embed\(source=['"]([\w._\-\/]+)['"]/)
+    css_dec = scan_dirs(/\.(css)$/, @src, /:\s*url\(\s*['"](.*)['"]/)
+    mxml_dec = scan_dirs(/\.(mxml)$/, @src, /@Embed\(['"]([\w._\-\/]+)['"]/)
+
+    @declared = src_dec + css_dec + mxml_dec
+    @unused = []
+
+    @assets.each { |ass| @unused << ass unless is_asset_used(ass) }
+
+    summarise
+  end
+
+  private
+
+  #
+  # Summarise the collected data.
+  #
+  def summarise
+    puts "Used assets: #{@declared.length.to_s}"
+    puts "Unused assets: #{@unused.length.to_s}"
+  end
+
+  #
+  # Returns a string detailing the findings of the style detection.
+  #
+  def describe
+    desc = "#{generated_at} by as-asset-vacuum"
+    desc << add_desc("Assets declared in src", @declared)
+    desc << add_desc("Assets found in project but not referenced in source", @unused)
+    desc
+  end
+
+  def is_asset_used(file)
+    used = false
+    @declared.each { |declaration|
+      if File.basename(declaration) == File.basename(file)
+        used = true
+      end
+    }
+    used
+  end
+
+end

data/lib/shed/{unused_class.rb → class_vacuum.rb}

@@ -8,7 +8,7 @@
 # Before executing this script make sure the relevant link reports and manifest
 # files have been generated.
 #
-class UnusedClass < Tool
+class ClassVacuum < Tool
   attr_reader :report,
               :empty_packages,
               :unused_classes
@@ -22,7 +22,7 @@ class UnusedClass < Tool
     @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."
+      @out.puts "#{INVALID_OPTS} The link report, manifest file, or source directory does not exist."
       return
     end
 
@@ -46,37 +46,36 @@ class UnusedClass < Tool
     @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}"
+    summarise
   end
 
   private
 
   #
-  # Scans the path for empty directories and lists them.
+  # Summarise the collected data.
   #
-  def empties(path)
-    e = []
-    Search.for_empties(path) { |p| e << p.sub( /^.*src\//, "") }
-    e
+  def summarise
+    puts "Unused classes: #{@unused_classes.length.to_s}"
+    puts "Empty packages: #{@empty_packages.length.to_s}"
   end
 
   #
-  # Returns a string detailing the findings of the unused class detection.
+  # Scans the path for empty directories and lists them.
   #
-  def describe
-    d = "as-class-vaccum Report. #{generated_at}\n\n"
-    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
+  def empties(path)
+    empties = []
+    Search.for_empties(path) { |path| empties << path.sub( /^.*src\//, "") }
+    empties
   end
 
   #
-  # Prints a description category.
+  # Returns a string detailing the findings of the class vacuumer.
   #
-  def add_desc(txt,list)
-    l = list.empty? ? '' : list.join("\n")
-    "#{list.length} #{txt}\n#{l}\n\n"
+  def describe
+    desc = "#{generated_at} by as-class-vacuum"
+    desc << add_desc("Classes in the manifest but not the link report", @unused_classes)
+    desc << add_desc("Packages appear to be empty", @empty_packages)
+    desc
   end
 
   #

data/lib/shed/manifest.rb

@@ -34,16 +34,16 @@ class Manifest < Tool
   # 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..."
+  def scan(dir)
+    puts "Scanning '#{dir}' for as and mxml files..."
 
     found = []
 
-    Search.find_all(@filetypes,path,@excludes) do |p|
-      ext = File.extname(p)
-      cn = File.basename(p, ext)
+    Search.find_all(@filetypes,dir,@excludes) do |path|
+      ext = File.extname(path)
+      name = File.basename(path, ext)
 
-      found << add(p, cn) if cn =~ /^[A-Z]/
+      found << add(path, name) if name =~ /^[A-Z]/
     end
 
     found = process(found) unless found.empty?
@@ -70,10 +70,10 @@ class Manifest < Tool
     if @components.empty?
       puts "No ActionScript or Mxml files found."
     else
-      @xml = create_xml(@components)
+      create_xml(@components)
 
       #Open/Create the manifest file and write the output to it.
-      to_disk(@xml)
+      to_disk(xml)
     end
   end
 
@@ -82,9 +82,8 @@ class Manifest < Tool
   # files.
   #
   def create_xml(comps)
-    x = "<?xml version='1.0'?>\n<componentPackage>\n"
-    comps.each { |c| x << "\t#{c[:xml]}\n" }
-    x << "</componentPackage>"
-    x
+    @xml = "<?xml version='1.0'?>\n<componentPackage>\n"
+    comps.each { |component| @xml << "\t#{component[:xml]}\n" }
+    @xml << "</componentPackage>"
   end
 end

data/lib/shed/opts/asdoc_package_opts.rb

@@ -15,7 +15,7 @@ class ASDocPackageOpts < ToolOpts
 
   def self.default_config
     dc = superclass.default_config
-    dc[:output] = 'package-asdoc.xml'
+    dc[:output] = 'asdoc-package-config.xml'
     dc
   end
 

data/lib/shed/opts/asset_vacuum_opts.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+
+#
+# Manages the command line interface for the assets vacuum tool.
+#
+class AssetVacuumOpts < ToolOpts
+
+  def self.name
+    "as-asset-vacuum"
+  end
+
+  def self.description
+    "ActionScript Asset Vacuum Tool"
+  end
+
+  def self.default_config
+    dc = superclass.default_config
+    dc[:output] = 'assets.txt'
+    dc
+  end
+
+end

data/lib/shed/opts/{unused_class_opts.rb → class_vacuum_opts.rb}

@@ -1,38 +1,35 @@
 # encoding: utf-8
 
 #
-# Manages the command line interface for the unused classes detection tool.
+# Manages the command line interface for the class vacuum tool.
 #
-class UnusedClassOpts < ToolOpts
+class ClassVacuumOpts < ToolOpts
 
   def self.name
-    "as-class-detector"
+    "as-class-vacuum"
   end
 
   def self.description
-    "ActionScript unused class detection tool"
+    "ActionScript Class Vacuum Tool"
   end
 
   def self.default_config
     dc = superclass.default_config
-    dc[:output] = 'class-vaccum.txt'
+    dc[:output] = 'class-vacuum.txt'
     dc[:manifest] = 'manifest.xml'
     dc[:link_report] = 'link-report.xml'
     dc
   end
 
-  #
-  # Add all mandatory arguments to the options parser.
-  #
   def self.add_mandatory(op,config)
     superclass.add_mandatory(op,config)
 
-    op.on("-m", "--manifest FILE", "Path to the source manifest file.") do |v|
-      config[:manifest] = v
+    op.on("-m", "--manifest FILE", "Path to the source manifest file.") do |value|
+      config[:manifest] = value
     end
 
-    op.on("-l", "--link-report FILE", "Path to the compiler link-report file.") do |v|
-      config[:link_report] = v
+    op.on("-l", "--link-report FILE", "Path to the compiler link-report file.") do |value|
+      config[:link_report] = value
     end
   end
 

data/lib/shed/opts/manifest_opts.rb

@@ -21,8 +21,8 @@ class ManifestOpts < ToolOpts
 
   def self.add_optional(op,config)
     superclass.add_optional(op,config)
-    op.on("-f", "--filter [STRING]", String, "Package filter, in the form of 'org.helvector', to include in the generated manifest.") do |v|
-      config[:filter] = v
+    op.on("-f", "--filter [STRING]", String, "Package filter, in the form of 'org.helvector', to include in the generated manifest.") do |value|
+      config[:filter] = value
     end
   end
 

data/lib/shed/opts/style_vacuum_opts.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+
+#
+# Manages the command line interface for the style vacuum tool.
+#
+class StyleVacuumOpts < ToolOpts
+
+  def self.name
+    "as-style-vacuum"
+  end
+
+  def self.description
+    "ActionScript Style Vacuum Tool"
+  end
+
+  def self.default_config
+    dc = superclass.default_config
+    dc[:output] = 'styles.txt'
+    dc[:css_dir] = 'style'
+    dc
+  end
+
+  def self.add_mandatory(op,config)
+    superclass.add_mandatory(op,config)
+
+    op.on("-c", "--css PATH", "Path to the directory containing css file/s.") do |value|
+      config[:css_dir] = value
+    end
+  end
+
+end

data/lib/shed/opts/tool_opts.rb

@@ -64,20 +64,20 @@ class ToolOpts
   # 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
+    op.on("-s", "--source [PATH]", String, "Path to source folder, defaults to current directory.") do |value|
+      config[:src] = value
     end
 
-    op.on("-o", "--output [FILE]", String, "Path to output file, defaults to #{config[:output]}.") do |v|
-      config[:output] = v
+    op.on("-o", "--output [FILE]", String, "Path to output file, defaults to #{config[:output]}.") do |value|
+      config[:output] = value
     end
 
-    op.on("-v", "--verbose", "Run verbosely.") do |v|
-      config[:verbose] = v
+    op.on("-v", "--verbose", "Run verbosely.") do |value|
+      config[:verbose] = value
     end
 
-    op.on("--silent", "Supress all output.") do |v|
-      config[:silent] = v
+    op.on("--silent", "Supress all output.") do |value|
+      config[:silent] = value
     end
   end
 

data/lib/shed/style_vacuum.rb

@@ -0,0 +1,92 @@
+# encoding: utf-8
+
+#
+# Detects styles that are not used in a Flex application.
+#
+# This needs to be provided with a source directory to search for used styles,
+# and a directory containing css files which will be loaded and parsed for
+# style definitions.
+#
+# NOTE: This tool needs further work before it can be considerd to cover all
+#       use cases.
+#
+class StyleVacuum < Tool
+  attr_reader :report,
+              :declared,
+              :used,
+              :unused,
+              :undeclared
+
+  def initialize(opt,out=STDOUT)
+    super(opt,out)
+
+    @css_dir = opt[:css_dir]
+
+    @style_regex = /styleName\s*=\s*["']\s*\{?\s*([\w.]+)\s*\}?\s*["']/
+    @declared_regex = /^\.(\w+)/
+
+    @declared, @used, @unused, @undeclared = [], [], [], []
+
+    unless valid_opts
+      @out.puts "#{INVALID_OPTS} The specified css directory does not exist, or does not contain css files."
+      return
+    end
+
+    detect
+
+    @report = describe
+
+    to_disk(@report)
+  end
+
+  #
+  # Valid if we can find .css files in the specifed css_dir.
+  #
+  def valid_opts
+    return false unless File.exist?(@css_dir)
+
+    found = Dir.chdir("#{@css_dir}") { Dir.glob('*.css') }
+
+    found.length > 0
+  end
+
+  def detect
+    puts "Scanning project for styles..."
+
+    @declared = scan_dirs(/\.(css)/, @css_dir, @declared_regex)
+    @used = scan_dirs(/\.(as|mxml)/, @src, @style_regex)
+
+    #Find any style names used in the source which haven't been declared.
+    @undeclared = @used-@declared
+
+    #Find any style names declared in the css but not used in the src.
+    @unused = @declared-@used
+
+    summarise
+  end
+
+  private
+
+  #
+  # Summarise the collected data.
+  #
+  def summarise
+    puts "Declared styles: #{@declared.length.to_s}"
+    puts "Undeclared styles: #{@undeclared.length.to_s}"
+    puts "Used styles: #{@used.length.to_s}"
+    puts "Unused styles: #{@unused.length.to_s}"
+  end
+
+  #
+  # Returns a string detailing the findings of the style detection.
+  #
+  def describe
+    desc = "#{generated_at} by as-style-vacuum"
+    desc << add_desc("Styles declared in CSS", @declared)
+    desc << add_desc("Styles used in MXML",@used)
+    desc << add_desc("Styles declared but not used (in a styleName property)",@unused)
+    desc << add_desc("Styles used but not declared",@undeclared)
+    desc
+  end
+
+end