HTML5/Javascript Analyser specificities

Note

This documentation applies to CAIP >= 8.3.x and com.castsoftware.html5 >= 2.1.1-funcrel.

HowTo

Create your own UA extension, then react to the “add_quality_rules” event received from HTML5/Javascript extension. With this event, you can send any interpreters of your choice, which will be used by HTML5/Javascript. These interpreters will have “start_XXX” and/or “end_XXX” methods where XXX is the ast node type you are interested in. They must have also a “finish” method.

Sample of UA extension code

import cast.analysers.ua
from cast import Event
from cast.analysers import log

from interpreter import Interpreter

class Html5Diag(cast.analysers.ua.Extension):

    @Event('com.castsoftware.html5', 'add_quality_rules')
    def add_quality_rules(self, externalQualityRules):

        interpreter = Interpreter()
        externalQualityRules.add_interpreter(interpreter, self.get_plugin())

Sample of interpreter code

class Interpreter:

    def __init__(self):
        pass

    def start_JsContent(self, ast):
        pass

    def end_JsContent(self, ast):
        pass

    def finish(self):
        pass

A complete sample can be found here : Starter kits.

Javascript ast nodes types

class javascript_parser.symbols.AstToken(token, parent, name=None)

Base class of all ast nodes

get_children()
Returns:ast node children
Return type:list[javascript_parser.symbols.AstToken]
get_name()
Returns:ast node name.
Return type:str
get_kb_object(recursiveInParents=False)
Parameters:recursiveInParents (Boolean) – True is kb object must be search in parents
Returns:CAST database object corresponding to the ast node
Return type:cast.analysers.CustomObject
get_first_kb_parent(skipJsFunctionCallFunctions=False)
Returns:the first ast node which will be saved in KB.
Return type:javascript_parser.symbols.AstToken
get_begin_line()
Returns:the ast node first line.
Return type:int
get_begin_column()
Returns:the ast node first column.
Return type:int
get_end_line()
Returns:the ast node last line.
Return type:int
get_end_column()
Returns:the ast node last column.
Return type:int
get_resolutions(recurse=False, level=0)
Parameters:recurse (Boolean) – True is the resolution must recurse until the last ast node possible. Default is False
Return type:list[javascript_parser.symbols.Resolution]
is_ast_token()
is_try_catch_block()
Returns:True is the ast node corresponds to javascript_parser.symbols.TryCatchBlock.
Return type:Boolean
is_var_declaration()
Returns:True is the ast node corresponds to javascript_parser.symbols.VarDeclaration.
Return type:Boolean
is_let_declaration()
Returns:True is the ast node corresponds to javascript_parser.symbols.VarDeclaration declared with let keyword.
Return type:Boolean
is_const_declaration()
Returns:True is the ast node corresponds to javascript_parser.symbols.VarDeclaration declared with const keyword.
Return type:Boolean
is_new_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with new keyword.
Return type:Boolean
is_export_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with export keyword.
Return type:Boolean
is_export_default_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with export default keywords.
Return type:Boolean
is_return_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with return keyword.
Return type:Boolean
is_return_new_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with return new keywords.
Return type:Boolean
is_continue_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with continue keyword.
Return type:Boolean
is_import_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.ImportStatement.
Return type:Boolean
is_break_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with break keyword.
Return type:Boolean
is_delete_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with delete keyword.
Return type:Boolean
is_new_expression()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyExpression starting with new keyword.
Return type:Boolean
is_loop()
Returns:True is the ast node corresponds to javascript_parser.symbols.LoopBlock or javascript_parser.symbols.FunctionCall considered as a loop.
Return type:Boolean
is_for_block()
Returns:True is the ast node corresponds to javascript_parser.symbols.ForBlock.
Return type:Boolean
is_for_in_block()
Returns:True is the ast node corresponds to javascript_parser.symbols.ForBlock with in keyword in expression.
Return type:Boolean
is_identifier()
Returns:True is the ast node corresponds to javascript_parser.symbols.Identifier.
Return type:Boolean
is_function()
Returns:True is the ast node corresponds to javascript_parser.symbols.Function.
Return type:Boolean
is_class()
Returns:True is the ast node corresponds to javascript_parser.symbols.Class.
Return type:Boolean
is_arrow_function()
Returns:True is the ast node corresponds to javascript_parser.symbols.ArrowFunction.
Return type:Boolean
is_js_content()
Returns:True is the ast node corresponds to javascript_parser.symbols.JsContent.
Return type:Boolean
is_function_call()
Returns:True is the ast node corresponds to javascript_parser.symbols.FunctionCall.
Return type:Boolean
is_js_function_call()
Returns:True is the ast node corresponds to javascript_parser.symbols.JSFunctionCall.
Return type:Boolean
is_function_call_part()
Returns:True is the ast node corresponds to javascript_parser.symbols.FunctionCallPart.
Return type:Boolean
is_list()
Returns:True is the ast node corresponds to javascript_parser.symbols.AstList.
Return type:Boolean
is_string()
Returns:True is the ast node corresponds to javascript_parser.symbols.AstString.
Return type:Boolean
is_assignment()
Returns:True is the ast node corresponds to javascript_parser.symbols.Assignment.
Return type:Boolean
is_object_value()
Returns:True is the ast node corresponds to javascript_parser.symbols.ObjectValue.
Return type:Boolean
is_operator()
Returns:True is the ast node corresponds to javascript_parser.symbols.AstOperator.
Return type:Boolean
is_binary_expression()
Returns:True is the ast node corresponds to javascript_parser.symbols.BinaryExpression.
Return type:Boolean
is_addition_expression()
Returns:True is the ast node corresponds to javascript_parser.symbols.AdditionExpression.
Return type:Boolean
is_or_expression()
Returns:True is the ast node corresponds to javascript_parser.symbols.OrExpression.
Return type:Boolean
is_in_expression()
Returns:True is the ast node corresponds to javascript_parser.symbols.InExpression.
Return type:Boolean
is_unary_expression()
Returns:True is the ast node corresponds to javascript_parser.symbols.UnaryExpression.
Return type:Boolean
is_jsx_expression()
Returns:True is the ast node corresponds to javascript_parser.symbols.JsxExpression.
Return type:Boolean
is_if_ternary_expression()
Returns:True is the ast node corresponds to javascript_parser.symbols.IfTernaryExpression.
Return type:Boolean
is_not_expression()
Returns:True is the ast node corresponds to javascript_parser.symbols.NotExpression.
Return type:Boolean
is_equality_expression()
Returns:True is the ast node corresponds to javascript_parser.symbols.EqualBinaryExpression or javascript_parser.symbols.NotEqualBinaryExpression.
Return type:Boolean
is_switch_block()
Returns:True is the ast node corresponds to javascript_parser.symbols.SwitchBlock.
Return type:Boolean
is_method()
Returns:True is the ast node corresponds to javascript_parser.symbols.Method.
Return type:Boolean
is_constructor()
Returns:True is the ast node corresponds to javascript_parser.symbols.Constructor.
Return type:Boolean

Statements

class javascript_parser.symbols.StatementList(token, parent)

Bases: javascript_parser.symbols.AstToken

get_statements()
Returns:statements list
Return type:list[javascript_parser.symbols.AstToken]
class javascript_parser.symbols.JsContent(token, parent, file=None, config=None, startRow=1, startCol=1)

Bases: javascript_parser.symbols.KbSymbol, javascript_parser.symbols.StatementList

get_file()
class javascript_parser.symbols.Identifier(parent=None, name=None, token=None)

Bases: javascript_parser.symbols.AstToken

A identifier a or a.b or a.b.c ...

get_prefix(evenIfExpr=False)
Parameters:evenIfExpr (Boolean) – If True, the prefix will be returned, event it is an expression instead of a string (default is False)
Return type:str if evenIfExpr is False or str or javascript_parser.symbols.AstToken if evenIfExpr is True
get_fullname()

Fullname of identifier.

Return type:str
class javascript_parser.symbols.AstOperator(token, parent, name=None)

Bases: javascript_parser.symbols.AstToken

class javascript_parser.symbols.AstString(token, parent, text)

Bases: javascript_parser.symbols.AstToken

class javascript_parser.symbols.IfStatement(token, parent)

Bases: javascript_parser.symbols.AstToken

Represents an If... Then...Else block.

get_if_block()
Returns:the if block
Return type:javascript_parser.symbols.IfBlock
get_else_if_blocks()
Returns:the else if blocks
Return type:list[javascript_parser.symbols.ElseIfBlock]
get_else_block()
Returns:the else block
Return type:javascript_parser.symbols.ElseBlock
class javascript_parser.symbols.IfBlock(token, parent)

Bases: javascript_parser.symbols.ExpressionBlock

Represents an If block (the If part of an If statement)

get_expression()
Returns:the block expression
Return type:javascript_parser.symbols.AstToken
class javascript_parser.symbols.ElseIfBlock(token, parent)

Bases: javascript_parser.symbols.ExpressionBlock

Represents an Else If block (the else if part of an If statement)

get_expression()
Returns:the block expression
Return type:javascript_parser.symbols.AstToken
class javascript_parser.symbols.ElseBlock(token, parent)

Bases: javascript_parser.symbols.Block

Represents an Else block (the else part of an If statement)

class javascript_parser.symbols.WhileBlock(token, parent)

Bases: javascript_parser.symbols.LoopBlock

get_expression()
Returns:the while expression
Return type:javascript_parser.symbols.AstToken
class javascript_parser.symbols.ForBlock(token, parent)

Bases: javascript_parser.symbols.LoopBlock

get_start_expressions()
Returns:the start expressions
Return type:list[javascript_parser.symbols.AstToken]
get_termination_expression()
Returns:the termination expression
Return type:javascript_parser.symbols.AstToken
get_forward_expression()
Returns:the forward expression
Return type:javascript_parser.symbols.AstToken
class javascript_parser.symbols.ForEachBlock(token, parent)

Bases: javascript_parser.symbols.LoopBlock

get_expression()
Returns:The block expression
Return type:javascript_parser.symbols.AstToken
class javascript_parser.symbols.DoBlock(token, parent)

Bases: javascript_parser.symbols.LoopBlock

get_expression()
Returns:The expression
Return type:javascript_parser.symbols.AstToken
class javascript_parser.symbols.SwitchStatement(token, parent)

Bases: javascript_parser.symbols.AstToken

get_expression()
Returns:The switch expression
Return type:javascript_parser.symbols.AstToken
get_case_blocks()
Returns:The case blocks
Return type:list[javascript_parser.symbols.SwitchCaseBlock]
get_default_block()
Returns:The default block
Return type:javascript_parser.symbols.SwitchDefaultBlock
class javascript_parser.symbols.SwitchCaseBlock(token, parent)

Bases: javascript_parser.symbols.ExpressionBlock

Represents a switch case block (the case part of an switch statement)

get_expression()
Returns:the block expression
Return type:javascript_parser.symbols.AstToken
class javascript_parser.symbols.SwitchDefaultBlock(token, parent)

Bases: javascript_parser.symbols.Block

Represents a switch default block (the default part of an switch statement)

class javascript_parser.symbols.AstBlock(token, parent)

Bases: javascript_parser.symbols.StatementList

class javascript_parser.symbols.TryCatchBlock(token, parent)

Bases: javascript_parser.symbols.AstToken

get_try_block()
Returns:The try block
Return type:javascript_parser.symbols.AstBlock
get_catch_blocks()
Returns:The catch blocks
Return type:list[javascript_parser.symbols.CatchBlock]
get_finally_block()
Returns:The finally block
Return type:javascript_parser.symbols.FinallyBlock
class javascript_parser.symbols.CatchBlock(token, parent)

Bases: javascript_parser.symbols.ExpressionBlock

get_expression()
Returns:the block expression
Return type:javascript_parser.symbols.AstToken
class javascript_parser.symbols.FinallyBlock(token, parent)

Bases: javascript_parser.symbols.Block

class javascript_parser.symbols.AstList(token, parent)

Bases: javascript_parser.symbols.AstToken

A bracketed list.

get_values()
Returns:list values
Return type:list[javascript_parser.symbols.AstToken]
class javascript_parser.symbols.ObjectValue(token, parent)

Bases: javascript_parser.symbols.AstToken

A curly bracketed block.

get_item(name, recurse=False)
Parameters:
  • name (str) – item name
  • recurse (Boolean) – True if the search must be recursive in the object value (default is False)
Returns:

the item with name in parameter
Return type:

javascript_parser.symbols.AstToken
class javascript_parser.symbols.Function(name, prefix, parent, token, file=None, isThis=False, emptyLines=None)

Bases: javascript_parser.symbols.KbSymbol, javascript_parser.symbols.StatementList

A function.

is_anonymous()
Returns:True if the function is anonymous (has no name)
Return type:Boolean
get_prefix()
Returns:The function name prefix
Return type:str
get_fullname()

Fullname of function.

Return type:str
get_parameters()
Returns:The function parameters
Return type:list[javascript_parser.symbols.AstToken]
class javascript_parser.symbols.ArrowFunction(name, prefix, parent, token, file=None, isThis=False, emptyLines=None)

Bases: javascript_parser.symbols.Function

A function.

class javascript_parser.symbols.FunctionCall(identifier, token, parent, isLoop=False)

Bases: javascript_parser.symbols.AstToken

A function call. f() or f().g() ...

get_function_call_parts()
Returns:List of function call parts
Return type:list[javascript_parser.symbols.FunctionCallPart]
class javascript_parser.symbols.FunctionCallPart(identifier, tokens)

Bases: javascript_parser.symbols.AstToken

Part of a FunctionCall. Ex: a().b() is composed of 2 FunctionCallPart

get_identifier()
Returns:The identifier of the function call part
Return type:javascript_parser.symbols.Identifier
get_parameters()
Returns:FunctionCallPart parameters
Return type:list[javascript_parser.symbols.AstToken]
get_fullname()

Fullname.

Return type:str
class javascript_parser.symbols.ImportStatement(token, parent, isType)

Bases: javascript_parser.symbols.AstStatement

import ‘react-select/dist/react-select.css’; import React from ‘react’; import { isGeneratedId } from “devtools-source-map”; import type { SymbolDeclaration, AstLocation } from ”../reducers/types”; import * as Actions from ‘./img-context-menu-actions’;

get_what()
Returns:list of tuples. For import a, b1 as b2 from ..., [(a, None), (b1, b2)]
Return type:list[(javascript_parser.symbols.Identifier, javascript_parser.symbols.Identifier or None)]
get_from()
Returns:The from ast node
Return type:javascript_parser.symbols.AstString
get_from_js_content()
Returns:The javascript source code corresponding to the from resolution.
Return type:javascript_parser.symbols.JsContent
class javascript_parser.symbols.AnyStatement(token, parent)

Bases: javascript_parser.symbols.AstStatement

statements which are not detailed

get_elements()
Returns:The ast node elements.
Return type:list[javascript_parser.symbols.AstToken]
is_return_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with return keyword.
Return type:Boolean
is_continue_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with continue keyword.
Return type:Boolean
is_export_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with export keyword.
Return type:Boolean
is_export_default_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with export default keywords.
Return type:Boolean
is_break_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with break keyword.
Return type:Boolean
is_return_new_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with return new keywords.
Return type:Boolean
is_delete_statement()
Returns:True is the ast node corresponds to javascript_parser.symbols.AnyStatement starting with delete keyword.
Return type:Boolean
class javascript_parser.symbols.VarDeclaration(token, parent, isLet=False, isConst=False)

Bases: javascript_parser.symbols.AstStatement

A var declaration. var a = 1, b, d = function() {};

get_elements()
Returns:Elements corresponding to different declarations/assignments.
Return type:list[javascript_parser.symbols.Assignment or javascript_parser.symbols.Identifier]
class javascript_parser.symbols.Assignment(token, parent, isVar=False, exported=False)

Bases: javascript_parser.symbols.AstStatement

An assignment.

is_var()
Returns:True if the assignment is part of a VarDeclaration
Return type:Boolean
is_exported()
Returns:True if the assignment is part of an exported VarDeclaration
Return type:Boolean
get_left_operand()
Returns:left operand of the assignment.
Return type:javascript_parser.symbols.AstToken
get_right_operand()
Returns:right operand of the assignment.
Return type:javascript_parser.symbols.AstToken
class javascript_parser.symbols.Class(name, prefix, parent, token, file=None, emptyLines=None)

Bases: javascript_parser.symbols.KbSymbol, javascript_parser.symbols.StatementList

A class.

get_fullname()

Fullname.

Return type:str
get_methods(name=None)
Parameters:name (str) – method name (default is None for all methods)
Returns:the methods with name in parameter.
Return type:javascript_parser.symbols.Function (may be a Method, Function or ArrowFunction)
get_method(name, static=False, includeInheritance=False)
Parameters:
  • name (str) – method name
  • static (Boolean) – True for the static method if several methods with same name (default is False)
  • includeInheritance (Boolean) – True if the method must be searched in mother classes (default is False)
Returns:

the method with name in parameter. The unicity is assured with the static parameter if several methods with same name are present.
Return type:

javascript_parser.symbols.Function (may be a Method, Function or ArrowFunction)
class javascript_parser.symbols.Method(name, parent, token, file, emptyLines, isConstructor)

Bases: javascript_parser.symbols.Function

A method.

is_static()
Returns:True if the method is static.
Return type:Boolean
is_constructor()
Returns:True if the method is a constructor.
Return type:Boolean
class javascript_parser.symbols.JSFunctionCall(token, func, parent)

Bases: javascript_parser.symbols.AstStatement

A JS function call. (function() {}).call(...)

get_function()
Returns:The function.
Return type:javascript_parser.symbols.Function

Expressions

class javascript_parser.symbols.AnyExpression(token, parent)

Bases: javascript_parser.symbols.AstToken

expression which is not detailed

get_elements()
Returns:List of elements
Return type:list[javascript_parser.symbols.AstToken]
is_new_expression()
Returns:True if the expression starts with new keyword
Return type:Boolean
class javascript_parser.symbols.UnaryExpression(token, parent)

Bases: javascript_parser.symbols.AstToken

A unary expression.

get_operand()
Returns:Expression operand.
Return type:javascript_parser.symbols.AstToken
class javascript_parser.symbols.BinaryExpression(token, parent)

Bases: javascript_parser.symbols.AstToken

A binary expression.

set_left_operand(operand)
set_right_operand(operand)
class javascript_parser.symbols.EqualBinaryExpression(token, parent)

Bases: javascript_parser.symbols.BinaryExpression

A == binary expression.

class javascript_parser.symbols.NotEqualBinaryExpression(token, parent)

Bases: javascript_parser.symbols.BinaryExpression

A != binary expression.

class javascript_parser.symbols.IfTernaryExpression(token, parent)

Bases: javascript_parser.symbols.AstToken

A If ternary expression.

get_if_operand()
Returns:If operand
Return type:javascript_parser.symbols.AstToken
get_then_operand()
Returns:Then operand
Return type:javascript_parser.symbols.AstToken
get_else_operand()
Returns:Else operand
Return type:javascript_parser.symbols.AstToken
class javascript_parser.symbols.AdditionExpression(token, parent, shortForm=False)

Bases: javascript_parser.symbols.BinaryExpression

An addition expression. self.shortForm = True if addition is of “+=” form (expression as a statement)

class javascript_parser.symbols.OrExpression(token, parent)

Bases: javascript_parser.symbols.BinaryExpression

An || expression.

class javascript_parser.symbols.InExpression(token, parent)

Bases: javascript_parser.symbols.BinaryExpression

A in expression.

class javascript_parser.symbols.NotExpression(token, parent)

Bases: javascript_parser.symbols.UnaryExpression

A not expression.

class javascript_parser.symbols.JsxExpression(token, parent)

Bases: javascript_parser.symbols.AstToken

A jsx expression <tag1 attr1=value1 attr2=value2>...</tag1>

get_tag()
Returns:jsx expression tag.
Return type:javascript_parser.symbols.HtmlTextWithPosition
get_attributes_values_full_ast()
Returns:values as full ast expressions by attribute name if values are expressions (between {})
Return type:collections.OrderedDict(str,javascript_parser.symbols.AstToken)
get_attributes_values()
Returns:values as tokens by attribute name
Return type:collections.OrderedDict(str,list[javascript_parser.light_parser.Token])
get_sub_expressions()
Returns:sub jsx expressions
Return type:list[javascript_parser.symbols.JsxExpression]

Writing tests

Sample of a test

import unittest
    import cast.analysers.test
    import cast.analysers.ua

class Test(unittest.TestCase):

    def test_ok1(self):

        analysis = cast.analysers.test.UATestAnalysis('HTML5')
        analysis.add_selection('test1')
        analysis.add_dependency(r'C:\ProgramData\CAST\CAST\Extensions\com.castsoftware.html5.2.1.1-funcrel')
        analysis.run()

        f = analysis.get_object_by_name('f', 'CAST_HTML5_JavaScript_Function')
        self.assertTrue(f)
        _value = f.get_value('CAST_Html5Diags_Metric_UseOfBreakInWhile.numberOfBreakInWhile')
        self.assertEqual('1', _value)


if __name__ == '__main__':
    unittest.main()

Note

You need to add a dependency to the folder containing com.castsoftware.html5, for example

analysis.add_dependency(r'C:\ProgramData\CAST\CAST\Extensions\com.castsoftware.html5.2.1.1-funcrel')

For that you need to have downloaded the extension through CAST ExtensionDowloader: see https://doc.castsoftware.com/display/EXTEND/CAST+Extension+Downloader

Categories and types for quality rules

For adding a quality rule on

  • Category CAST_HTML5_JavaScript_Metrics_Category

Quality rule scopes

Existing quality rule scopes are :

1020000 HTML5 artifacts (Javascript functions, methods, constructors, javascript source code, source code fragments)
1020001 Javascript functions, methods and constructors
1020005 HTML5 source code, JSP, ASP, ASPX, HTC contents, Jade source code
1020006 CSS source code, CSS source code fragments
1020007 Javascript class

HTML5 technologies

Values for technology to be used in IMPLTechnologies.xml for filter value

HTML5 1020000