Reference: Custom Audit Rule Context Object Properties

13 Reference: Custom Audit Rule Context Object Properties

Use this reference to learn about the properties and functionality available to custom audit rules on passed in context objects. The context objects contain AST node data generated by the Oracle JAF audit engine in response to the audited file set.

Context Objects	Description
Context Object Members Passed to the Register Function	A rule's `register()` function receives a `Register` context object when it is invoked by the JAF audit engine during the audit startup.
Context Object Properties Available to Registered Listeners	A rule's registered listeners receive a `Rule` context object when the listener is triggered by the JAF audit engine for specific data in the target files of the audit.
Context Object Properties Available to CSS Rule Listeners	A CSS audit rule's registered listeners receive a `Rule` context object with information that is specific to CSS processing.
Context Object Properties Available to Markdown Rule Listeners	A Markdown audit rule's registered listeners receive a `Rule` context object with information that is specific to MArkdown processing.

Context Object Members Passed to the Register Function

A rule's register() function receives a Register context object when it is invoked by the JAF audit engine during the audit startup.

A Register context object is passed during JAF audit startup to the audit rules specified by your JAF configuration. The context object generated at JAF startup contains miscellaneous supporting data and functionality that is available to the register() function of all rule types.

Note:

You must not cache the Register context object. You may cache contained values, for example, like context.utils.msgLib.

Members	Description
rulePack	The rule pack manager instance. This provides methods to access rule pack data. For details, see RulePack Class Methods.
ruleOpts	A read-only copy of the rule options object from the rule pack's `rules.json` file, and any override in the configuration property ruleMods.
runMode	The run mode value will be cli to reflect the audit invocation from the command line. Other options may be supported in a future release.
config	The configuration object which is a read-only copy of the effective runtime configuration properties.
ojetConfig	The oraclejetconfig configuration object (if the Oracle JAF audit is run in the root of a project maintained by the Oracle JET Tooling). This property is only available in the startupRP and closedownRP phase of hook rules.
utils	Miscellaneous utility libraries. Refer to utils in Context Object Properties Available to Registered Listeners.
sysOpts	An object containing boolean properties verboseMode and debugMode reflecting the runtime options.
jsNodeTypes	An object containing JavaScript Abstract Syntax Tree (AST) enumerated node listener type strings (if the rule handles JavaScript). See also, Listener Types for JavaScript/TypeScript Rules.

Context Object Properties Available to Registered Listeners

A rule's registered listeners receive a Rule context object when the listener is triggered by the JAF audit engine for specific data in the target files of the audit.

The JAF audit engine passes a Rule context object to all rules with a listener that your rule registers to handle specific node types in the target file set. The generated context object contains the following miscellaneous supporting data and functionality available to the registered listener of any rule type.

Note:

You must not cache the Rule context object. You may cache contained values, for example, like context.utils.msgLib.

Property	Description
type	Designates the type of data passed in the arguments to a rule, or signals an event. For HTML, JSON, and CSS: refer to Listener Types for HTML and JSON Rules. For JavaScript/TypeScript: refer to Listener Types for JavaScript/TypeScript Rules. The registered type can also specify that the rule is a hook rule. Hook rules are effectively hooks into the audit engine, and are called at specific phases of an audit, as opposed to a response to parsed file data for a general node rule. For details, see About Hook Rule Invocation. The hook types are startup, closedown, startupRP, startaudit, closedownRP and file.
node	A node object containing details from the current node in the DOM, JavaScript/TypeScript (Abtract Syntax Tree - AST), JSON (AST), or selector trees.
tagNode	The current tag element node object containing details about the containing tag element. In the case of type `tag`, the node and tagNode properties are the same.
tag	The HTML element name, for example `div` or `oj-avatar`.
ojTag	`true` if the HTML element starts with `oj-` and is a defined Oracle JET element tag. Note that a `context.type` of `ojtag` reflects only that the element name starts with `oj-`.
ojNS	`true` if the element name is defined in the `OJ` namespace.
elemStack	For HTML pages, an array of node objects providing the positional context of the current element. The last entry (with the highest index) in the array is the current element.
sysOpts	Miscellaneous system options including the boolean options verboseMode and debugMode. Refer also to context property msgLib.
userDefs	The configuration file userDefs property (if defined). This property is not examined by Oracle JAF.
rulePack	The rule pack manager instance. This provides methods to access rule pack data. For a description of the available methods, see RulePack Class Methods.
Issue	The `Issue` class. Use this to create a new `Issue` object for each issue that is to be reported and query the Issue details. For a description of the available methods, see Rule Issue Class Methods.
reporter	The `Reporter` instance. Constructed `Issue` objects are passed to this instance by an audit rule for inclusion in the audit output. Use this to add the Issue object to a Reporter instance and query Reporter details. For a description of the available methods, see Rule Reporter Class Methods.
ruleName	The rule name.
filepath	The full file path to the file currently being processed. Note that for consistency, filepath always uses forward slashes, regardless of the platform. Audit rules are platform independent in this respect.
filetype	The file type (in lower case)
phase	If the rule is a hook rule, this string represents the phase in which it was invoked, including startup, closedown, startupRP, startaudit, closedownRP, or file.
utils	Contains Oracle JAF utility libraries: utils - miscellaneous non-file related utilities. Refer to Utils: General Non-File System Functions. fsUtils - miscellaneous file related utilities. Refer to FsUtils: File System Functions. DomUtils—a parsed DOM tree utility library. Provides methods to traverse and inspect the parsed tree of nodes. Available only when `context.filetype` is "`html`". Refer to DomUtils: Node Object Functions. semVerUtils—a utility library providing semantic versioning support. This is available when the `context.filetype` is `json`. Refer to SemVerUtils: Semantic Version Functions. AstUtils—miscellaneous JavaScript/TypeScript Abstract Syntax Tree (AST) methods. Available only when `context.filetype` is `js` or `ts/tsx`. Refer to AstUtils: JavaScript File Helper Functions. metaLib —an Oracle JAF audit metadata access library. Refer to MetaLib: JET Metadata Access Functions. jafLib —available only in phase auditstart. Provides the ability to dynamically define the file set to be audited. Refer to JafLib: JAF Core Access Methods. msgLib —miscellaneous message display routines. Refer to MsgLib: Message Display Functions. CssUtils—CSS rule processing functions. Refer to CssUtils: CSS Utility Functions. sevLib—rule severity level utility methods. Refer to SevLib: Severity Support Helper Functions. A library may be omitted depending on the registration type. For example, for type `html`, the AstUtils library (for JavaScript/TypeScript) will not be present. (See Utils: General Non-File System Functions.)
userDefs	The value defined (optionally) by the configuration userDefs property.
NodeTypes	A set of enumerated type definitions. For example, NodeTypes.TAG or NodeTypes.SCRIPT, and so on.

Context Object Properties Available to Markdown Rule Listeners

A Markdown rule's registered listeners receive a Rule context object with information that is specific to Markdown processing.

For Markdown processing, a rule can listen for file events (when a .md file is first read) or for specific Markdown events (when a particular type of markup is found). In either case, the JAF audit engine passes the Rule context object to rule listeners that your rule registers to handle specific node types of the Markdown files. The context object generated for Markdown files contains supporting data and functionality that are specific to Markdown processing.

To access summarized data, the context object’s supplementary data property suppData provides the following methods available on its utils object to obtain images, paragraphs, headings, code blocks, and so on. These are in addition to the base properties available on the context object for all rule types, as described in Context Object Properties Available to Registered Listeners.

Note:

You must not cache the Rule context object. You may cache contained values such as, for example, context.utils.msgLib.

The supplementary data property suppdata contains the following subproperties:

ast: the abstract syntax tree (AST)
utils: a utility object (methods in the table below)

Method	Arguments	Description
getLinks()	None	Scans the markup for URL references, and returns an array of `link` objects. The `link` object has the following properties: inline: a boolean, default true, which indicates a complete link including a URL link: the URL string text: a string containing the link text pos: an object containing location information, with the following properties: line: line number to reference key, relative to 1 col: column number to reference key, relative to 1 start: index number to start of reference key end: index number to end of reference key If the link declaration uses a reference link, the link object will have the property inline declared to be `false`, and the refKey property will replace the link property. The refKey property can be used to look up the associated URL via the reference links object. See getRefLinks() below.
getRefLinks()	None	Scans the markup for reference links. A non-inline link provides a reference to a link defined elsewhere in the markup. This method provides an object containing the referenced link objects by reference key. Consider the following markup text with an indirect reference to a URL: `Link to the [resource file](some ref key)` This resolves to the following reference link: `[some ref key]: www./some/url` This returns an object containing the referenced link objects, each named by their reference key (e.g., `some ref key`). Each referenced link object has the following properties: link: the URL string title: the title string, if specified in the MD construct pos: an object containing location information, with the following properties: line: line number to reference key, relative to 1 col: column number to reference key, relative to 1 start: index number to start of reference key end: index number to end of reference key
getImages()	None	Scans the markup for image declarations and returns an array of `image` objects. The `image` object has the following properties: inline: a boolean, default `true`, which indicates a complete link including a URL link: the image URL string text: a string containing the alt text pos: an object containing location information, with the following properties: line: line number to reference key, relative to 1 col: column number to reference key, relative to 1 start: index number to start of reference key end: index number to end of reference key If the image declaration uses a reference link, the image object will have the property inline declared to be `false`, and the refKey property will replace the link property.
getCode()	None	Scans the markup for fenced code blocks (using backticks or tildes) and returns an array of `code` objects. The `code` object has the following properties: code: a string containing the code block, with `/n` newline characters used as separators pos: an object containing two objects that hold the start and end location info, respectively, in the following format: line: starting line number, relative to 1 start: index number to start of code block, relative to 0 end: index number to end of line, relative to 0 line: ending line number, relative to 1 start: index number to start of line, relative to 0 end: index number to end of code block, relative to 0
getParas()	None	Scans the markup for paragraphs and headings. Returns an array of `para` objects. The `para` object has the following properties: text: a string with paragraph or heading text level: the number of the heading level pos: an object containing two objects that hold the paragraph/heading start and end location info, respectively, in the following format: line: starting line number, relative to 1 start: index number to start of line, relative to 0 end: index number to end of line, relative to 0 line: ending line number, relative to 1 start: index number to start of line, relative to 0 end: index number to end of line, relative to 0 Note: For standard paragraph text, level is 0. A value greater than zero represents the number of markup heading `#` characters (e.g., `##` represents a heading level h2, where level will be 2).
getLists()		Scans the markup for ordered and unordered lists and returns an array of objects. Each object has the following properties. The `list` object has the following properties: ordered: a boolean, with `false` used for unordered lists and `true` for ordered lists items: an array of list item objects, each with an item property referring to a string value pos: an array containing two objects that hold the list start and end location info, respectively, in the following format: line: starting line number, relative to 1 start: index number to start of line relative to 0 end: index number to end of line, relative to 0 line: ending line number, relative to 1 start: index number to start of line, relative to 0 end: index number to end of line, relative to 0 If a list entry represents a sub-list, the children property is used within the list item. It contains an array containing each object sub-list, each using the same formatting as the `list` object, with ordered, items, and pos properties.
testParas()	(regexp RegExp, [boolean firstmatch])	Takes a regular expression as an argument and applies it to each paragraph found in the markup. An optional second boolean argument specifies whether all matching paragraphs should be returned, or just the first matching paragraph (the default, if omitted. Returns an array of para objects. See getParas() above for para object properties. In the following example, paras will contain the matching paragraph objects: `var paras = utils.testParas(/Oracle/);`
getLineMap()	None	Returns a `Map` object with line numbers (relative to 1) as the map keys. The return value from `get()` on the map is an object with properties start and end, which represent the start and end indices (relative to 0) into the file for the line specified. In this example, the map variable stores the `Map` object, and pos stores the position info for line 3 (as an object with properties start and end) `var map = getLineMap(); var pos = map.get(3);`
getLine()	(number line)	Returns a line from the .md file, as a string. line is specified relative to 1. In this example, the map variable stores the `Map` object, and line stores line 3 as a string. `var map = getLineMap(); var line = getLine(3);`
getLineDisp()	(number line, [number col])	Returns the index number (relative to zero) to the start of the line specified. If optional col column number (relative to 1) is specified, the returned index will point to that column.

Context Object Properties Available to CSS Rule Listeners

A CSS rule's registered listeners receive a Rule context object with information that is specific to CSS processing.

The JAF audit engine passes a Rule context object to CSS rule listeners that your rule registers to handle specific node types of the target CSS files. The context object generated for CSS files contains the following supporting data and functionality, specific to CSS processing. This is in addition to the base properties available on the context object for all rule types, as describe in Context Object Properties Available to Registered Listeners.

Note:

You must not cache the Rule context object. You may cache contained values, for example, like context.utils.msgLib.

Property Type Description

Property	Type	Description
context.ast	node	The full AST for the stylesheet.
context.offset	Object	Contains the origin of the stylesheet relative to the containing file. If the stylesheet text is a standalone `.css` file, the values will be {row : 1, col: 1, index: 0}. However, if the stylesheet is an embedded HTML <style>, the row, col, and index values will reflect the position of the first character of the stylesheet in the containing file. This property can be used in conjunction with the loc property in a CSS node to reflect the true position of a particular property or value. (The loc position information is always relative to the start of the stylesheet.)
context.utils.CssUtils	Object	A utility library with miscellaneous functions available on the register context when the rule is invoked, as well as the rule context. Refer to CssUtils: CSS Utility Functions.

context.ast

node

The full AST for the stylesheet.

context.offset

Object

Contains the origin of the stylesheet relative to the containing file. If the stylesheet text is a standalone .css file, the values will be {row : 1, col: 1, index: 0}. However, if the stylesheet is an embedded HTML <style>, the row, col, and index values will reflect the position of the first character of the stylesheet in the containing file.

This property can be used in conjunction with the loc property in a CSS node to reflect the true position of a particular property or value. (The loc position information is always relative to the start of the stylesheet.)

context.utils.CssUtils Object A utility library with miscellaneous functions available on the register context when the rule is invoked, as well as the rule context. Refer to CssUtils: CSS Utility Functions.