jsduck 4.10.4 → 5.0.0.beta01

data/lib/jsduck/js/esprima.rb

@@ -0,0 +1,39 @@
+require 'v8'
+require 'jsduck/util/json'
+require 'jsduck/util/singleton'
+
+module JsDuck
+  module Js
+
+    # Runs Esprima.js through V8.
+    #
+    # Initialized as singleton to avoid loading the esprima.js more
+    # than once - otherwise performace will severely suffer.
+    class Esprima
+      include Util::Singleton
+
+      def initialize
+        @v8 = V8::Context.new
+        esprima = File.dirname(File.expand_path(__FILE__))+"/esprima/esprima.js";
+
+        # Esprima attempts to assign to window.esprima, but our v8
+        # engine has no global window variable defined.  So define our
+        # own and then grab esprima out from it again.
+        @v8.eval("var window = {};")
+        @v8.load(esprima)
+        @v8.eval("var esprima = window.esprima;")
+      end
+
+      # Parses JavaScript source code using Esprima.js
+      #
+      # Returns the resulting AST
+      def parse(input)
+        @v8['js'] = input
+        json = @v8.eval("JSON.stringify(esprima.parse(js, {comment: true, range: true, raw: true}))")
+        return Util::Json.parse(json, :max_nesting => false)
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/js/evaluator.rb

@@ -0,0 +1,70 @@
+module JsDuck
+  module Js
+
+    # Evaluates Esprima AST node into Ruby object
+    class Evaluator
+
+      # Converts AST node into a value.
+      #
+      # - String literals become Ruby strings
+      # - Number literals become Ruby numbers
+      # - Regex literals become :regexp symbols
+      # - Array expressions become Ruby arrays
+      # - etc
+      #
+      # For anything it doesn't know how to evaluate (like a function
+      # expression) it throws exception.
+      #
+      def to_value(ast)
+        case ast["type"]
+        when "ArrayExpression"
+          ast["elements"].map {|e| to_value(e) }
+        when "ObjectExpression"
+          h = {}
+          ast["properties"].each do |p|
+            key = key_value(p["key"])
+            value = to_value(p["value"])
+            h[key] = value
+          end
+          h
+        when "BinaryExpression"
+          if ast["operator"] == "+"
+            to_value(ast["left"]) + to_value(ast["right"])
+          else
+            throw "Unable to handle operator: " + ast["operator"]
+          end
+        when "MemberExpression"
+          if base_css_prefix?(ast)
+            "x-"
+          else
+            throw "Unable to handle this MemberExpression"
+          end
+        when "Literal"
+          if ast["raw"] =~ /\A\//
+            :regexp
+          else
+            ast["value"]
+          end
+        else
+          throw "Unknown node type: " + ast["type"]
+        end
+      end
+
+      # Turns object property key into string value
+      def key_value(key)
+        key["type"] == "Identifier" ? key["name"] : key["value"]
+      end
+
+      # True when MemberExpression == Ext.baseCSSPrefix
+      def base_css_prefix?(ast)
+        ast["computed"] == false &&
+          ast["object"]["type"] == "Identifier" &&
+          ast["object"]["name"] == "Ext" &&
+          ast["property"]["type"] == "Identifier" &&
+          ast["property"]["name"] == "baseCSSPrefix"
+      end
+
+    end
+
+  end
+end

data/lib/jsduck/js/ext_patterns.rb

@@ -0,0 +1,70 @@
+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.
+      # Called when --ext-namespaces option is passed to JSDuck.
+      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/function.rb

@@ -0,0 +1,206 @@
+require "jsduck/util/singleton"
+
+module JsDuck
+  module Js
+
+    # Analyzes the AST of a FunctionDeclaration or FunctionExpression.
+    class Function
+      include Util::Singleton
+
+      # Detects possible return types of the given function.
+      #
+      # For now there are three possible detected return values:
+      #
+      # * :this - the code contins 'return this;'
+      #
+      # * "undefined" - the code finishes by returning undefined or
+      #   without explicitly returning anything
+      #
+      # * :other - some other value is returned.
+      #
+      def return_types(ast)
+        h = return_types_hash(ast["body"]["body"])
+
+        # Replace the special :void value that signifies possibility of
+        # exiting without explicitly returning anything
+        if h[:void]
+          h["undefined"] = true
+          h.delete(:void)
+        end
+
+        h.keys
+      end
+
+      private
+
+      def return_types_hash(body)
+        rvalues = {}
+        body.each do |ast|
+          if return?(ast)
+            type = value_type(ast["argument"])
+            rvalues[type] = true
+            return rvalues
+          elsif possibly_blocking?(ast)
+            extract_bodies(ast).each do |b|
+              rvalues.merge!(return_types_hash(b))
+            end
+            if !rvalues[:void]
+              return rvalues
+            else
+              rvalues.delete(:void)
+            end
+          elsif control_flow?(ast)
+            extract_bodies(ast).each do |b|
+              rvalues.merge!(return_types_hash(b))
+            end
+            rvalues.delete(:void)
+          end
+        end
+
+        rvalues[:void] = true
+        return rvalues
+      end
+
+      def return?(ast)
+        ast["type"] == "ReturnStatement"
+      end
+
+      def value_type(ast)
+        if !ast
+          :void
+        elsif undefined?(ast) || void?(ast)
+          "undefined"
+        elsif this?(ast)
+          :this
+        elsif boolean?(ast)
+          "Boolean"
+        elsif string?(ast)
+          "String"
+        elsif regexp?(ast)
+          "RegExp"
+        else
+          :other
+        end
+      end
+
+      def undefined?(ast)
+        ast["type"] == "Identifier" && ast["name"] == "undefined"
+      end
+
+      def void?(ast)
+        ast["type"] == "UnaryExpression" && ast["operator"] == "void"
+      end
+
+      def this?(ast)
+        ast["type"] == "ThisExpression"
+      end
+
+      def boolean?(ast)
+        if boolean_literal?(ast)
+          true
+        elsif ast["type"] == "UnaryExpression" || ast["type"] == "BinaryExpression"
+          !!BOOLEAN_RETURNING_OPERATORS[ast["operator"]]
+        elsif ast["type"] == "LogicalExpression"
+          boolean?(ast["left"]) && boolean?(ast["right"])
+        elsif ast["type"] == "ConditionalExpression"
+          boolean?(ast["consequent"]) && boolean?(ast["alternate"])
+        elsif ast["type"] == "AssignmentExpression" && ast["operator"] == "="
+          boolean?(ast["right"])
+        else
+          false
+        end
+      end
+
+      def boolean_literal?(ast)
+        ast["type"] == "Literal" && (ast["value"] == true || ast["value"] == false)
+      end
+
+      def string?(ast)
+        if string_literal?(ast)
+          true
+        elsif ast["type"] == "BinaryExpression" && ast["operator"] == "+"
+          string?(ast["left"]) || string?(ast["right"])
+        elsif ast["type"] == "UnaryExpression" && ast["operator"] == "typeof"
+          true
+        else
+          false
+        end
+      end
+
+      def string_literal?(ast)
+        ast["type"] == "Literal" && ast["value"].is_a?(String)
+      end
+
+      def regexp?(ast)
+        ast["type"] == "Literal" && ast["raw"] =~ /^\//
+      end
+
+      def control_flow?(ast)
+        CONTROL_FLOW[ast["type"]]
+      end
+
+      def extract_bodies(ast)
+        body = []
+        CONTROL_FLOW[ast["type"]].each do |name|
+          statements = ast[name]
+          if statements.is_a?(Hash)
+            body << [statements]
+          else
+            body << Array(statements)
+          end
+        end
+        body
+      end
+
+      # True if the node is a control structure which will block further
+      # program flow when all its branches finish with a return
+      # statement.
+      def possibly_blocking?(ast)
+        if POSSIBLY_BLOCKING[ast["type"]]
+          CONTROL_FLOW[ast["type"]].all? {|key| ast[key] }
+        else
+          false
+        end
+      end
+
+      BOOLEAN_RETURNING_OPERATORS = {
+        "!" => true,
+        ">" => true,
+        ">=" => true,
+        "<" => true,
+        "<=" => true,
+        "==" => true,
+        "!=" => true,
+        "===" => true,
+        "!==" => true,
+        "in" => true,
+        "instanceof" => true,
+        "delete" => true,
+      }
+
+      POSSIBLY_BLOCKING = {
+        "IfStatement" => true,
+        "DoWhileStatement" => true,
+        "WithStatement" => true,
+        "LabeledStatement" => true,
+        "BlockStatement" => true,
+      }
+
+      CONTROL_FLOW = {
+        "IfStatement" => ["consequent", "alternate"],
+        "SwitchStatement" => ["cases"],
+        "SwitchCase" => ["consequent"],
+        "ForStatement" => ["body"],
+        "ForInStatement" => ["body"],
+        "WhileStatement" => ["body"],
+        "DoWhileStatement" => ["body"],
+        "TryStatement" => ["block", "handlers", "finalizer"],
+        "CatchClause" => ["body"],
+        "WithStatement" => ["body"],
+        "LabeledStatement" => ["body"],
+        "BlockStatement" => ["body"],
+      }
+    end
+
+  end
+end

data/lib/jsduck/js/node.rb

@@ -0,0 +1,194 @@
+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
+
+      # 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 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 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