solvas-jsduck 6.0.0.beta.1888

data/lib/jsduck/js/ext_patterns.rb

@@ -0,0 +1,75 @@
+require "jsduck/util/singleton"
+
+module JsDuck
+  module Js
+
+    # Identifies Ext JS builtins like Ext.define and Ext.extend, taking
+    # also into account the possibility of aliasing the Ext namespace.
+    #
+    # For example when the following command line option is used:
+    #
+    #     --ext-namespaces=Ext,MyApp
+    #
+    # we need to identify both Ext.define and MyApp.define, but
+    # Ext.define is additionally aliased withing ExtJS as
+    # Ext.ClassManager.create, so we also need to recognize
+    # Ext.ClassManager.create and MyApp.ClassManager.create.
+    #
+    # The matches? method will take care of identifying all these four
+    # cases:
+    #
+    #     ExtPatterns.set(["Ext", "MyApp"])
+    #     ExtPatterns.matches?("Ext.define", "MyApp.define") --> true
+    #
+    class ExtPatterns
+      include Util::Singleton
+
+      def initialize
+        set(["Ext"])
+      end
+
+      # True when string matches the given pattern type.
+      #
+      # Pattern type is one of: "Ext.define", "Ext.extend",
+      # "Ext.override", "Ext.emptyFn"
+      def matches?(pattern, string)
+        @patterns[pattern].include?(string)
+      end
+
+      # Reconfigures ExtPatterns with different set of namespaces from
+      # command line options.
+      def configure(opts)
+        set(opts.ext_namespaces) if opts.ext_namespaces
+      end
+
+      # Reconfigures patterns with given set of namespaces.
+      def set(namespaces)
+        @patterns = {
+          "Ext.define" => build_patterns(namespaces, [".define", ".ClassManager.create"]),
+          "Ext.extend" => build_patterns(namespaces, [".extend"]),
+          "Ext.override" => build_patterns(namespaces, [".override"]),
+          "Ext.emptyFn" => build_patterns(namespaces, [".emptyFn"]),
+        }
+      end
+
+      private
+
+      # Given Array of alternate Ext namespaces builds list of patterns
+      # for detecting Ext.define or some other construct:
+      #
+      # build_patterns(["Ext", "Foo"], [".define"]) --> ["Ext.define", "Foo.define"]
+      #
+      def build_patterns(namespaces, suffixes)
+        patterns = []
+        namespaces.each do |ns|
+          suffixes.each do |suffix|
+            patterns << ns + suffix
+          end
+        end
+        patterns
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/js/fires.rb

@@ -0,0 +1,42 @@
+require "jsduck/util/singleton"
+require "jsduck/js/scoped_traverser"
+
+module JsDuck
+  module Js
+
+    # Looks the AST of a FunctionDeclaration or FunctionExpression for
+    # uses of this.fireEvent().
+    class Fires
+      include Util::Singleton
+
+      # Returns array of event names fired by the given function.
+      # When no events fired, empty array is returned.
+      def detect(function_node)
+        @traverser = Js::ScopedTraverser.new
+
+        events = []
+        @traverser.traverse(function_node["body"]) do |node|
+          if fire_event?(node)
+            events << node["arguments"][0].to_value
+          end
+        end
+
+        events.sort.uniq
+      end
+
+      private
+
+      # True when node is this.fireEvent("name") call.
+      # Also true for me.fireEvent() when me == this.
+      def fire_event?(node)
+        node.call_expression? &&
+          node["callee"].member_expression? &&
+          @traverser.this?(node["callee"]["object"].to_s) &&
+          node["callee"]["property"].to_s == "fireEvent" &&
+          node["arguments"].length > 0 &&
+          node["arguments"][0].value_type == "String"
+      end
+
+    end
+  end
+end

data/lib/jsduck/js/listener.rb

@@ -0,0 +1,35 @@
+require "jsduck/util/singleton"
+
+module JsDuck
+  module Js
+
+    # Auto-detection of listeners.
+    class Listener
+      include Util::Singleton
+
+      # Checks if AST node is a listener, and if so, returns doc-hash
+      # with listener name and various auto-detected properties.
+      # When not an listener returns nil.
+	  # Note: currently this is not implemented.  Needs to check for methods under the "listeners:" item
+      def detect(ast)
+        exp = ast.expression_statement? ? ast["expression"] : nil
+
+        # this.fireEvent("foo", ...)
+        if exp && 1==2
+          make(exp["arguments"][0].to_value)
+        else
+          nil
+        end
+      end
+
+      # Produces a doc-hash for an listener.
+      def make(name)
+        return {
+          :tagname => :listener,
+          :name => name,
+        }
+      end
+
+    end
+  end
+end

data/lib/jsduck/js/method.rb

@@ -0,0 +1,99 @@
+require "jsduck/util/singleton"
+require "jsduck/js/returns"
+require "jsduck/js/fires"
+require "jsduck/js/method_calls"
+
+module JsDuck
+  module Js
+
+    # Auto-detection of methods.
+    class Method
+      include Util::Singleton
+
+      # Checks if AST node is a method, and if so, returns doc-hash
+      # with method name and various auto-detected properties.
+      # When not a method returns nil.
+      def detect(ast)
+        exp = ast.expression_statement? ? ast["expression"] : nil
+        var = ast.variable_declaration? ? ast["declarations"][0] : nil
+
+        # function foo() {}
+        if ast.function?
+          make(ast["id"].to_s || "", ast)
+
+          # foo = function() {}
+        elsif exp && exp.assignment_expression? && exp["right"].function?
+          make(exp["left"].to_s, exp["right"])
+
+          # var foo = function() {}
+        elsif var && var["init"] && var["init"].function?
+          make(var["id"].to_s, var["init"])
+
+          # (function() {})
+        elsif exp && exp.function?
+          make(exp["id"].to_s || "", exp)
+
+          # foo: function() {}
+        elsif ast.property? && ast.raw["kind"] == "init" && ast["value"].function?
+          make(ast["key"].key_value, ast["value"])
+
+          # Object.defineProperty(obj, "prop", {value: function() {} })
+        elsif exp && (value = exp.object_descriptor("value")) && detect(value)
+          name = exp["arguments"][1].to_value
+          make(name, value)
+
+        else
+          nil
+        end
+      end
+
+      # Performs the auto-detection on function AST node and produces
+      # a doc-hash.
+      def make(name, ast)
+        if proper_function?(ast)
+          return {
+            :tagname => :method,
+            :name => name,
+            :params => arr_to_nil(params(ast)),
+            :chainable => chainable?(ast) && name != "constructor",
+            :fires => arr_to_nil(fires(ast)),
+            :method_calls => arr_to_nil(method_calls(ast)),
+          }
+        else
+          return {
+            :tagname => :method,
+            :name => name,
+          }
+        end
+      end
+
+      private
+
+      def proper_function?(ast)
+        ast.function? && !ast.ext_empty_fn?
+      end
+
+      # replaces empty array with nil
+      def arr_to_nil(arr)
+        arr.length == 0 ? nil : arr
+      end
+
+      def params(ast)
+        ast["params"].map {|p| {:name => p.to_s} }
+      end
+
+      def chainable?(ast)
+        Js::Returns.chainable?(ast.raw)
+      end
+
+      def fires(ast)
+        Js::Fires.detect(ast)
+      end
+
+      def method_calls(ast)
+        Js::MethodCalls.detect(ast)
+      end
+
+    end
+  end
+end

data/lib/jsduck/js/method_calls.rb

@@ -0,0 +1,40 @@
+require "jsduck/util/singleton"
+require "jsduck/js/scoped_traverser"
+
+module JsDuck
+  module Js
+
+    # Looks the AST of a FunctionDeclaration or FunctionExpression for
+    # calls to methods of the owner class.
+    class MethodCalls
+      include Util::Singleton
+
+      # Returns array of method names called by the given function.
+      # When no methods called, empty array is returned.
+      def detect(function_node)
+        @traverser = Js::ScopedTraverser.new
+
+        methods = []
+        @traverser.traverse(function_node["body"]) do |node|
+          if method_call?(node)
+            methods << node["callee"]["property"].to_s
+          end
+        end
+
+        methods.sort.uniq
+      end
+
+      private
+
+      # True when node is this.someMethod() call.
+      # Also true for me.someMethod() when me == this.
+      def method_call?(node)
+        node.call_expression? &&
+          node["callee"].member_expression? &&
+          node["callee"].raw["computed"] == false &&
+          @traverser.this?(node["callee"]["object"].to_s)
+      end
+
+    end
+  end
+end

data/lib/jsduck/js/node.rb

@@ -0,0 +1,267 @@
+require "jsduck/js/serializer"
+require "jsduck/js/evaluator"
+require "jsduck/js/ext_patterns"
+require "jsduck/js/node_array"
+
+module JsDuck
+  module Js
+
+    # Wraps around AST node returned from Esprima, providing methods for
+    # investigating it.
+    class Node
+      # Factor method that creates either Node or NodeArray.
+      def self.create(node)
+        if node.is_a? Array
+          Js::NodeArray.new(node)
+        else
+          Js::Node.new(node)
+        end
+      end
+
+      # Initialized with a AST Hash from Esprima.
+      def initialize(node)
+        @node = node || {}
+      end
+
+      # Returns a child AST node as Node class.
+      def child(name)
+        Js::Node.create(@node[name])
+      end
+      # Shorthand for #child method
+      def [](name)
+        child(name)
+      end
+
+      # Returns the raw Exprima AST node this class wraps.
+      def raw
+        @node
+      end
+
+      # Serializes the node into string
+      def to_s
+        begin
+          Js::Serializer.new.to_s(@node)
+        rescue
+          nil
+        end
+      end
+
+      # Evaluates the node into basic JavaScript value.
+      def to_value
+        begin
+          Js::Evaluator.new.to_value(@node)
+        rescue
+          nil
+        end
+      end
+
+      # Converts object expression property key to string value
+      def key_value
+        Js::Evaluator.new.key_value(@node)
+      end
+
+      # Returns the type of node value.
+      def value_type
+        v = to_value
+        if v.is_a?(String)
+          "String"
+        elsif v.is_a?(Numeric)
+          "Number"
+        elsif v.is_a?(TrueClass) || v.is_a?(FalseClass)
+          "Boolean"
+        elsif v.is_a?(Array)
+          "Array"
+        elsif v.is_a?(Hash)
+          "Object"
+        elsif v == :regexp
+          "RegExp"
+        else
+          nil
+        end
+      end
+
+      # Returns the type of node.
+      def type
+        @node["type"]
+      end
+
+      # Extracts all sub-statements and sub-expressions from AST node.
+      # Without looking at the type of node, we just take all the
+      # sub-hashes and -arrays.
+      #
+      # A downside of this simple algorithm is that the statements can
+      # end up in different order than they are in source code.  For
+      # example the IfStatement has three parts in the following
+      # order: "test", "consequent", "alternate": But because we're
+      # looping over a hash, they might end up in a totally different
+      # order.
+      def body
+        body = []
+        @node.each_pair do |key, value|
+          if key == "type" || key == "range"
+            # ignore
+          elsif value.is_a?(Array)
+            body.concat(value.map {|v| Js::Node.create(v) })
+          elsif value.is_a?(Hash)
+            body << Js::Node.create(value)
+          end
+        end
+        body
+      end
+
+      # Iterates over keys and values in ObjectExpression.  The keys
+      # are turned into strings, but values are left as is for further
+      # processing.
+      def each_property
+        return unless object_expression?
+
+        child("properties").each do |ast|
+          yield(ast["key"].key_value, ast["value"], ast)
+        end
+      end
+
+      # Returns value of a given field from Object.defineProperty call
+      # descriptor object.
+      def object_descriptor(descriptor_key)
+        return unless define_property?
+
+        descriptor = child("arguments")[2]
+        descriptor.each_property do |key, value, prop|
+          return value if key == descriptor_key
+        end
+
+        return nil
+      end
+
+      # Returns the return statement's expression for the current function
+      # expression.
+      def return_statement_expression
+        return unless function_expression?
+
+        node = child("body")
+        if node.block_statement?
+          node["body"].each do |node|
+            if node.return_statement?
+              node = node["argument"]
+              return node.object_expression? ? node : nil
+            end
+          end
+        end 
+
+        return nil
+      end
+
+
+      def block_statement?
+        @node["type"] == "BlockStatement"
+      end
+
+      def return_statement?
+        @node["type"] == "ReturnStatement"
+      end
+
+      # Returns line number in parsed source where the Node resides.
+      def linenr
+        # Get line number from third place at range array.
+        # This third item exists in forked EsprimaJS at
+        # https://github.com/nene/esprima/tree/linenr-in-range
+        @node["range"][2]
+      end
+
+      # Tests for higher level types which don't correspond directly to
+      # Esprima AST types.
+
+      def function?
+        function_declaration? || function_expression? || ext_empty_fn?
+      end
+
+      def fire_event?
+        call_expression? && child("callee").to_s == "this.fireEvent"
+      end
+
+      def define_property?
+        call_expression? && child("callee").to_s == "Object.defineProperty"
+      end
+
+      def string?
+        literal? && @node["value"].is_a?(String)
+      end
+
+      # Checks dependent on Ext namespace,
+      # which may not always be "Ext" but also something user-defined.
+
+      def ext_empty_fn?
+        member_expression? && ext_pattern?("Ext.emptyFn")
+      end
+
+      def ext_define?
+        call_expression? && child("callee").ext_pattern?("Ext.define")
+      end
+
+      def ext_extend?
+        call_expression? && child("callee").ext_pattern?("Ext.extend")
+      end
+
+      def ext_override?
+        call_expression? && child("callee").ext_pattern?("Ext.override")
+      end
+
+      def ext_pattern?(pattern)
+        Js::ExtPatterns.matches?(pattern, to_s)
+      end
+
+      # Simple shorthands for testing the type of node
+      # These have one-to-one mapping to Esprima node types.
+
+      def call_expression?
+        @node["type"] == "CallExpression"
+      end
+
+      def assignment_expression?
+        @node["type"] == "AssignmentExpression"
+      end
+
+      def object_expression?
+        @node["type"] == "ObjectExpression"
+      end
+
+      def array_expression?
+        @node["type"] == "ArrayExpression"
+      end
+
+      def function_expression?
+        @node["type"] == "FunctionExpression"
+      end
+
+      def member_expression?
+        @node["type"] == "MemberExpression"
+      end
+
+      def expression_statement?
+        @node["type"] == "ExpressionStatement"
+      end
+
+      def variable_declaration?
+        @node["type"] == "VariableDeclaration"
+      end
+
+      def function_declaration?
+        @node["type"] == "FunctionDeclaration"
+      end
+
+      def property?
+        @node["type"] == "Property"
+      end
+
+      def identifier?
+        @node["type"] == "Identifier"
+      end
+
+      def literal?
+        @node["type"] == "Literal"
+      end
+
+    end
+
+  end
+end