solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/options/processor.rb

@@ -0,0 +1,47 @@
+require 'jsduck/options/parser'
+require 'jsduck/options/input_files'
+require 'jsduck/logger'
+require 'jsduck/util/json'
+require 'jsduck/util/io'
+require 'jsduck/util/parallel'
+require 'jsduck/tag_registry'
+require 'jsduck/js/ext_patterns'
+
+module JsDuck
+  module Options
+
+    # A facade for all the command line options processing.
+    class Processor
+      # Takes a list of command line options, parses it to an
+      # Options::Record object, validates the options, applies it to
+      # various singleton classes and returns the Options::Record.
+      def self.process(args)
+        # HACK! First establish warnings defaults.
+        Logger.configure_defaults
+
+        opts = Options::Parser.new.parse(args)
+
+        # Expand list of input files
+        Options::InputFiles.new(opts).expand!
+
+        # Validate the options.
+        # Exit program when there's an error.
+        if err = opts.validate!
+          Array(err).each {|line| Logger.fatal(line) }
+          exit(1)
+        end
+
+        # Configure various objects with these options
+        Logger.configure(opts)
+        Util::Parallel.configure(opts)
+        TagRegistry.configure(opts)
+        Js::ExtPatterns.configure(opts)
+        Util::Json.configure(opts)
+        Util::IO.configure(opts)
+
+        opts
+      end
+    end
+
+  end
+end

data/lib/jsduck/options/record.rb

@@ -0,0 +1,51 @@
+module JsDuck
+  module Options
+
+    # Stores values of command line options.
+    #
+    # All options are initially defined with an #attribute method, which
+    # ensures that accessing an unexisting option will result in an
+    # error.
+    class Record
+      def initialize
+        @validators = {}
+      end
+
+      # Defines accessor for an option,
+      # and assigns a default value for it.
+      def attribute(name, default=nil)
+        instance_variable_set("@#{name}", default)
+        # Use `send` to invoke private attr_accessor method.  As we only
+        # expect a single OptionsRecord to exist for the lifetime of the
+        # app, it should be safe to define a method on a class.
+        self.class.send(:attr_accessor, name)
+      end
+
+      # Defines a validator function that gets run after all the
+      # options have been parsed.  When validation fails, the function
+      # should return an error message string (or an array of string
+      # for multi-line error message) otherwise nil, to signify
+      # success.
+      def validator(name, &block)
+        @validators[name] = block
+      end
+
+      # Runs all the validators.  Returns an error message string from
+      # the first failed validation or nil when everything is OK.
+      #
+      # Alternatively runs just one validator by name. Used in testing.
+      def validate!(name=nil)
+        validators = name ? [@validators[name]] : @validators.values
+
+        validators.each do |block|
+          if err = block.call()
+            return err
+          end
+        end
+        return nil
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/output_dir.rb

@@ -0,0 +1,29 @@
+require 'fileutils'
+
+module JsDuck
+  # Cleans up the output dir from previous JSDuck run.  If the output
+  # dir contains a .cache directory (and this dir is currently used
+  # for caching), it gets preserved, otherwise just an empty output
+  # dir is created.
+  class OutputDir
+
+    # Initializes empty output directory (with optional .cache inside).
+    def self.clean(opts)
+      if opts.cache && cache_dir_needs_preserving(opts)
+        # Remove all files inside <output-dir> except .cache/
+        Dir[opts.output + "/*"].each do |file|
+          FileUtils.rm_rf(file) unless file =~ /\/.cache\z/
+        end
+      else
+        # Remove and recreate the entire <output-dir>
+        FileUtils.rm_rf(opts.output)
+        FileUtils.mkdir(opts.output)
+      end
+    end
+
+    def self.cache_dir_needs_preserving(opts)
+      opts.cache_dir == opts.output + "/.cache" && File.exists?(opts.cache_dir)
+    end
+
+  end
+end

data/lib/jsduck/params_merger.rb

@@ -0,0 +1,47 @@
+require "jsduck/logger"
+require "jsduck/merger"
+
+module JsDuck
+  # Performs the merging of :params field.
+  # Used by Method, Event and CssMixin members.
+  class ParamsMerger
+    # Ensures the existance of params array.
+    # Defaults type of each parameter to "Object".
+    # Logs warnings for inconsistencies between params in code and in docs.
+    def self.merge(h, docs, code)
+      h[:params] = [] unless h[:params]
+
+      h[:params].each do |p|
+        p[:type] = "Object" unless p[:type]
+      end
+
+      check_consistency(docs, code, h[:files].first)
+    end
+
+    def self.check_consistency(docs, code, file)
+      explicit = docs[:params] || []
+      implicit = JsDuck::Merger.can_be_autodetected?(docs, code) ? (code[:params] || []) : []
+      ex_len = explicit.length
+      im_len = implicit.length
+
+      if ex_len == 0 || im_len == 0
+        # Skip when either no implicit or explicit params
+      elsif ex_len != im_len && explicit.last[:type] =~ /\.\.\.$/
+        # Skip when vararg params are in play.
+      elsif ex_len < im_len
+        # Warn when less parameters documented than found from code.
+        JsDuck::Logger.warn(:param_count, "Detected #{im_len} params, but only #{ex_len} documented.", file)
+      elsif ex_len > im_len
+        # Warn when more parameters documented than found from code.
+        JsDuck::Logger.warn(:param_count, "Detected #{im_len} params, but #{ex_len} documented.", file)
+      elsif implicit.map {|p| p[:name] } != explicit.map {|p| p[:name] }
+        # Warn when parameter names don't match up.
+        ex_names = explicit.map {|p| p[:name] }
+        im_names = implicit.map {|p| p[:name] }
+        str = ex_names.zip(im_names).map {|p| ex, im = p; ex == im ? ex : (ex||"")+"/"+(im||"") }.join(", ")
+        JsDuck::Logger.warn(:param_count, "Documented and auto-detected params don't match: #{str}", file)
+      end
+    end
+
+  end
+end

data/lib/jsduck/parser.rb

@@ -0,0 +1,76 @@
+require 'jsduck/js/parser'
+require 'jsduck/js/ast'
+require 'jsduck/css/parser'
+require 'jsduck/doc/parser'
+require 'jsduck/doc/processor'
+require 'jsduck/doc/map'
+require 'jsduck/merger'
+require 'jsduck/base_type'
+require 'jsduck/class_doc_expander'
+
+module JsDuck
+  # Performs the actual parsing of SCSS or JS source.
+  #
+  # This is the class that brings together all the different steps of
+  # parsing the source.
+  class Parser
+
+    def initialize
+      @doc_parser = Doc::Parser.new
+      @class_doc_expander = ClassDocExpander.new
+      @doc_processor = Doc::Processor.new
+      @merger = Merger.new
+      @filename = ""
+    end
+
+    # Parses file into final docset that can be fed into Aggregator
+    def parse(contents, filename="", options={})
+      @doc_processor.filename = @filename = filename
+
+      parse_js_or_scss(contents, filename, options).map do |docset|
+        expand(docset)
+      end.flatten.map do |docset|
+        merge(docset)
+      end
+    end
+
+    private
+
+    # Parses the file depending on filename as JS or SCSS
+    def parse_js_or_scss(contents, filename, options)
+      if filename =~ /\.scss$/
+        docs = Css::Parser.new(contents, options).parse
+      else
+        docs = Js::Parser.new(contents, options).parse
+        docs = Js::Ast.new(docs).detect_all!
+      end
+    end
+
+    # Parses the docs, detects tagname and expands class docset
+    def expand(docset)
+      docset[:comment] = @doc_parser.parse(docset[:comment], @filename, docset[:linenr])
+      docset[:doc_map] = Doc::Map.build(docset[:comment])
+      docset[:tagname] = BaseType.detect(docset[:doc_map], docset[:code])
+
+      if docset[:tagname] == :class
+        # expand class into several docsets, and rebuild doc-maps for all of them.
+        @class_doc_expander.expand(docset).map do |ds|
+          ds[:doc_map] = Doc::Map.build(ds[:comment])
+          ds
+        end
+      else
+        docset
+      end
+    end
+
+    # Merges comment and code parts of docset
+    def merge(docset)
+      @doc_processor.linenr = docset[:linenr]
+      docset[:comment] = @doc_processor.process(docset[:tagname], docset[:doc_map])
+      docset.delete(:doc_map)
+
+      @merger.merge(docset, @filename, docset[:linenr])
+    end
+  end
+
+end

data/lib/jsduck/process/accessors.rb

@@ -0,0 +1,152 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    # Expands accessors.
+    #
+    # Looks up configs with @accessor tag (or configs defined inside
+    # config: {} or eventedConfig: {} block).
+    #
+    # For such config "foo" it generates:
+    #
+    # - getter "getFoo"
+    # - setter "setFoo"
+    # - event "foochange" (when tagged with @evented)
+    #
+    class Accessors
+      def initialize(classes)
+        @classes = classes
+      end
+
+      # Generates accessors in all classes.
+      def process_all!
+        @classes.each_value {|cls| process(cls) }
+      end
+
+      private
+
+      # Given a class, generates accessor methods to configs with
+      # @accessor tag.  Modifies the class by adding these methods.
+      # When class already contains a getter or setter, the method is
+      # not added.
+      def process(cls)
+        # Grab all configs tagged as @accessor
+        accessors = cls[:members].find_all {|m| m[:tagname] == :cfg && m[:accessor] }
+
+        # Build lookup tables of method and event names
+        methods = build_lookup_table(cls[:members], :method)
+        events = build_lookup_table(cls[:members], :event)
+
+        accessors.each do |cfg|
+          # add getter if no method with same name exists
+          get = create_getter(cfg)
+          if !methods[get[:name]]
+            cls[:members] << get
+          end
+          # add setter if no method with same name exists
+          set = create_setter(cfg)
+          if !methods[set[:name]]
+            cls[:members] << set
+          end
+          # for evented accessors
+          if cfg[:evented]
+            # add event if no event with same name exists
+            ev = create_event(cfg)
+            if !events[ev[:name]]
+              cls[:members] << ev
+            end
+          end
+        end
+      end
+
+      def build_lookup_table(members, tagname)
+        map = {}
+        members.each do |m|
+          map[m[:name]] = m if m[:tagname] == tagname
+        end
+        map
+      end
+
+      def create_getter(cfg)
+        name = "get" + upcase_first(cfg[:name])
+        return add_shared({
+            :tagname => :method,
+            :name => name,
+            :doc => "Returns the value of {@link #cfg-#{cfg[:name]}}.",
+            :params => [],
+            :return => {
+              :type => cfg[:type],
+              :doc => "",
+            },
+            :id => "method-" + name,
+          }, cfg)
+      end
+
+      def create_setter(cfg)
+        name = "set" + upcase_first(cfg[:name]);
+        return add_shared({
+            :tagname => :method,
+            :name => name,
+            :doc => "Sets the value of {@link #cfg-#{cfg[:name]}}.",
+            :params => [{
+                :type => cfg[:type],
+                :name => cfg[:name],
+                :doc => "The new value.",
+              }],
+            :id => "method-" + name,
+          }, cfg)
+      end
+
+      def create_event(cfg)
+        name = cfg[:name].downcase + "change"
+        setter_name = "set" + upcase_first(cfg[:name]);
+        return add_shared({
+            :tagname => :event,
+            :name => name,
+            :doc => "Fires when the {@link ##{cfg[:id]}} configuration is changed by {@link #method-#{setter_name}}.",
+            :params => [
+              {
+                :name => "this",
+                :type => cfg[:owner],
+                :doc => "The #{cfg[:owner]} instance."
+              },
+              {
+                :name => "value",
+                :type => cfg[:type],
+                :doc => "The new value being set."
+              },
+              {
+                :name => "oldValue",
+                :type => cfg[:type],
+                :doc => "The existing value."
+              },
+            ],
+            :id => "event-" + name,
+          }, cfg)
+      end
+
+      # Copy over from @cfg all the fields that aren't already present.
+      def add_shared(hash, cfg)
+        ignored_fields = [
+          # These don't make sense for methods and events.
+          :type, :default,
+          # It's the config that's tagged with these, don't propagate them to methods/events.
+          :accessor, :evented,
+          # The :doc field get auto-created and we don't want any other docs.
+          :inheritdoc, :localdoc,
+        ]
+
+        cfg.each_pair do |key, value|
+          hash[key] = value unless ignored_fields.include?(key) || hash[key]
+        end
+        hash
+      end
+
+      def upcase_first(str)
+        str[0,1].upcase + str[1..-1]
+      end
+    end
+
+  end
+end

data/lib/jsduck/process/circular_deps.rb

@@ -0,0 +1,58 @@
+require 'jsduck/logger'
+
+module JsDuck
+  module Process
+
+    # Checks for circular dependencies
+    class CircularDeps
+      def initialize(classes)
+        @classes = classes
+      end
+
+      # Checks all classes for circular dependencies.
+      #
+      # When found, exits with a fatal error message.
+      def process_all!
+        @classes.each do |cls|
+          if chain = check(cls)
+            Logger.fatal("Class #{cls[:name]} has a circular dependency: #{chain}")
+            exit 1
+          end
+        end
+      end
+
+      # Checks class for circular dependencies.
+      #
+      # When all OK, returns false.
+      #
+      # When circular dependencies found returns a string describing the
+      # problematic dependency chain e.g. "Foo extends Bar mixins Foo".
+      def check(cls, names = [])
+        names += [cls[:name]]
+
+        if cls.parent && chain = track_circular(" extends ", cls.parent, names)
+          return chain
+        end
+
+        cls.mixins.each do |mixin|
+          if chain = track_circular(" mixins ", mixin, names)
+            return chain
+          end
+        end
+
+        false
+      end
+
+      def track_circular(type, cls, names)
+        names += [type]
+        if names.include?(cls[:name])
+          (names + [cls[:name]]).join("")
+        else
+          check(cls, names)
+        end
+      end
+
+    end
+
+  end
+end