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 |
---|---|
A rule's |
|
A rule's registered listeners receive a |
|
A CSS audit rule's registered listeners receive a |
|
Context Object Properties Available to Markdown Rule Listeners |
A Markdown audit rule's registered listeners receive a |
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:
A library may be omitted depending on the registration type. For example, for type
|
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
.
- 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 The
If the link declaration uses a reference link, the link object will have the property inline declared to be 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:
This resolves to the following reference link:
This returns an object containing the referenced link objects, each named by their reference key (e.g.,
|
getImages() | None |
Scans the markup for image declarations and returns an array of The
If the image declaration uses a reference link, the image object will have the property inline declared to be |
getCode() | None |
Scans the markup for fenced code blocks (using backticks or tildes) and returns an array of The
|
getParas() | None |
Scans the markup for paragraphs and headings. Returns an array of The
Note: For standard paragraph text, level is 0. A value greater than zero represents the number of markup heading |
getLists() |
Scans the markup for ordered and unordered lists and returns an array of objects. Each object has the following properties. The
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 |
|
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:
|
getLineMap() | None |
Returns a In this example, the map variable stores the
|
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
|
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 |
---|---|---|
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 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. |