15 Reference: Custom Audit Rule Utility Libraries

Use this reference to obtain details about the utility libraries provided by Oracle JAF. These libraries provide miscellaneous helper functions that can be useful when you write custom audit rules.

Utility Library Description

DomUtils: Node Object Functions

DomUtils is a collection of Document Object Model (DOM) utility functions and helper functions.

MetaLib: JET Metadata Access Functions

MetaLib provides Oracle JAF audit metadata access functionality that can be used in a rule.

Utils: General Non-File System Functions

Utils is a collection of non-file system utility functions.

FsUtils: File System Functions

FsUtils is a collection of file system utility functions.

SemVerUtils: Semantic Version Functions

SemVerUtils is a collection of semantic version (SemVer) utility functions.

JafLib: JAF Core Access Methods

JafLib is a library of exposed core Oracle JAF lifecycle functions.

MsgLib: Message Display Functions

MsgLib is a namespace property providing access to Oracle JAF internal messaging routines.

CssUtils: CSS Utility Functions

CssUtils is a library of CSS rule processing functions.

AstUtils: JavaScript File Helper Functions

AstUtils is a collection of Abstract Syntax Tree (AST) helper functions.

SevLib: Severity Support Helper Functions

SevLib is a library of helper functions that support processing severities that have been remapped via the Oracle JAF configuration property sevMap.

TsxUtils: TSX Utility Functions

TsxUtils is a library of TSX rule processing functions.

MetaLib: JET Metadata Access Functions

MetaLib provides Oracle JAF audit metadata access functionality that can be used in a rule.

Access these Oracle JET audit metadata interface library functions through rule context object context.utils.metaLib. The methods in this library insulate your rules from changes to the format of Oracle JAF metadata. Use these methods when writing audit rules that require access to metadata.

Oracle JET Audit Metadata Interface Library Metadata Methods

The Oracle JET audit metadata interface library provides the following metadata methods.

Method Returns Description
getTagMetadata()(string tag)

Object | null

tag is the HTML element name.

Returns the component.json metadata as an object for the specified user-custom component.

getTagPropMetadata(string tag, string propName)

Object | null

tag is the HTML element name (specified with/without the surrounding chevrons). propName is the property/sub-property name.

Returns the user web component property metadata as an object from the component.json metadata for the specified component property. The property name may specify dot-separated sub-properties. For example:

metaLib.getTagAttrMetadata('component-name', 'prop.subprop1.subprop2') 

This is a convenience method to reduce the rule code required to check for the existence of the property.

getTagSlotMetadata(string tag, string slotName)

Object | null

Returns the 'slot' object from the component metadata

getAllCustomMetadata()

Object

Returns an object containing all user custom component metadata. The object keys are the component names:

{
 component_name : {
   folder : string, // the containing folder (in native platform format) of:
  	           // 1) the component.json, or
  		    // 2) the VComponent source from which the metadata was
  		    // compiled.
  json : object,    // the component.json as an object
  VCType: 'func' | 'class'  // if a VComponent  (JAF 8.9.0  or later)
    },
   . . .
}
getTagStatus(string tag, string statusType) Array<Object> | null

Returns an array of metadata status objects of the type specified by statusType.

tag is the web component name

statusType is an optional metadata status type. Possible values are deprecated, maintenance, antiPattern or supersedes. This parameter is optional - if omitted, all status objects at the component level are returned.

null is returned in all other cases if no status objects can be found, or tag or statusType are invalid.

getPropStatus(string tag, string prop, string statusType) Array<Object> | null

Returns an array of metadata status objects of the type specified by statusType.

tag is the web component name

prop is a component property name

statusType is an optional metadata status type. Possible values are deprecated, maintenance, antiPattern or supersedes. This parameter is optional - if omitted, all status objects at the component level are returned.

null is returned in all other cases if no status objects can be found, or tag or statusType are invalid.

isTagStatus(string tag, string statusType) boolean

Returns true if the component has the status type specified by statusType at the component level.

tag is the web component name

statusType is an optional metadata status type. Possible values are deprecated, maintenance, antiPattern or supersedes.

Oracle JET Audit Metadata Interface Library Tag Methods

The Oracle JET audit metadata interface library provides the following tag methods.

Method Returns Description
isWCTag(string tag) boolean

tag is the HTML element name (specified with/without the surrounding chevrons).

Returns true if an HTML tag element is a known JET or user-defined custom web component.

isJetTag(string tag) boolean

tag is the HTML element name (specified with/without the surrounding chevrons).

Returns true if an HTML tag element is a known JET element (such as <oj-avatar>).

isJetLegacyTag(string tag) boolean

tag is the HTML element name (specified with/without the surrounding chevrons).

Returns true if an HTML tag element is a known JET legacy element (oj-*).

isComponentTag(string tag) boolean

tag is the HTML element name (specified with/without the surrounding chevrons).

Returns true if an HTML element is a known user-defined, custom Web Component (also called a composite component). The component.json files found via the component property of the configuration file are examined. See also isWCTag() .

isTagDeprecated(string tag) string | null

tag is the HTML element name (specified with/without the surrounding chevrons).

Tests a JET component for deprecated status, and returns the suggested alternative from the JET JS Doc if it is. Returns null if the element is not deprecated.

isTagAttrDeprecated(string tag, string attrName)

Array.<Object> | null

Object | string | null

tag is the HTML element name. attrName is the attribute name.

Tests the web component attribute for deprecated status and returns information including a suggested alternative and the version when deprecated. Multiple entries might be returned, and each object's target property should be checked for relevance. Each object is of the component.json deprecated type status object format.

Prior to JAF 3.1.0: Tests the web component attribute for deprecated status, and returns the suggested alternative. If there is no alternative, the string is empty. Returns null if the attribute is not deprecated. If an object is returned, it will contain one or both of the properties since and description (both strings). Returns null if the attribute is not deprecated.

isTagAttr(string tag, string attrName) boolean

tag is the HTML element name (specified with/without the surrounding chevrons). attrName is the attribute name.

Returns true if the attribute is defined for the specified custom component, else false.

isTagAttrValue(string tag, string attrName, string value) boolean

tag is the HTML element name (specified with/without the surrounding chevrons). attrName is the attribute name. value is the attribute value.

Returns true if the attribute value is defined for the specified custom component name, else false.

hasTagAttrValues(string tag, string attrName) boolean

tag is the HTML element name (specified with/without the surrounding chevrons). attrName is the attribute name.

Returns true if the custom element attribute has at least one defined value, else false.
hasTagSlot(string tag) boolean

tag is the HTML element name (specified with/without the surrounding chevrons).

Returns true if the JET component supports the slot attribute.
hasTagDefaultSlot(string tag) boolean

tag is the HTML element name (specified with/without the surrounding chevrons).

Returns true if the JET component has a default slot.
hasTagDynamicSlot(string tag) boolean

tag is the HTML element name (specified with/without the surrounding chevrons).

Returns true if the JET legacy (oj-*), JET Core Pack (oj-c-*) or use-defined component supports dynamic slot.

isTagSlotName(string tag, string slotName) boolean

Returns true if the web component provides the specified slot name. Since JAF 6.1.7, "" may be used to represent the default slot for the slotName argument.

getPreferredSlotContent() Array<string> Returns the preferred content (interfaces) for a specified component tag and slot. slot may be defined as "" for the default slot.
getPreferredSlotContent("oj-chart","groupTemplate")   -->  ["ChartGroupElement"]
getTagAttrType(string tagName, string attrName) string | null

tagName is the web component name (specified without the surrounding chevrons). attrName is the name of the attribute.

Returns the web component element property type, for the specified attribute, from the component metadata for the property.

isTagSlotValue(string tag, string slotValue) boolean

Deprecated in JAF 3.1.0. Use isTagSlotName() instead.

isTagEvent(string tag, string attrName) boolean

tag is the HTML element name (specified with/without the surrounding chevrons). attrName is the attribute name.

Returns true if a custom component attribute is a defined event. For example: on-oj-action for that component.

isTagSupportedInTheme(string tag ) boolean

tag is the HTML element name (specified with/without the surrounding chevrons).

Returns true if the specified web component name is supported in the current theme.

isAttrSupportedInTheme(string tag, string attrName) boolean

tag is the HTML element name (specified with/without the surrounding chevrons). attrName is the attribute name.

Returns true if the specified attribute in the web component is supported in the current theme.

isTagStyleDeprecated(string tag, string styleName) string | null

tag is the HTML element name (specified with/without the surrounding chevrons). styleName is a class attribute style name.

Tests the JET component class attribute has deprecated status, and returns the suggested alternative. If there is no alternative, the string is empty. Returns null if the style is not deprecated.

isTagStyle(string tag, string styleName) string | null

tag is the HTML element name (specified with/without the surrounding chevrons). styleName is a class attribute style name.

Returns true if the specified CSS class style is defined for the specified JET element name.

isStyle(string styleName) boolean

styleName is a class attribute style name.

Returns true if the CSS style is a defined JET style, else false.

isGenStyle(string styleName) boolean

styleName is a class attribute style name.

Returns true if the CSS style is a generic JET (non-component specific) style, else false.

isClassStyle(string styleName) boolean

styleName is a class attribute style name.

Returns true if the CSS style is a known JET component style, else false.

isJetStylePrefix(string styleName) boolean

styleName is a class attribute style name.

Returns true if the CSS style begins with a known JET style prefix, else false.

Note that false can also be returned if the loaded metadata is for an older JET version and there is no prefix data available. In such cases hasJetStylePrefixes() can be used to determine if the false value is meaningful.

.
hasJetStylePrefixes() boolean

styleName is a class attribute style name.

Returns true if the loaded metadata contains JET style prefix information.

getTagsFromStyle(string styleName) string[] | null

styleName is a class attribute style name.

Returns the JET element names using the specified style name. For example, for the style oj-form-control-text-align-right, the returned value would be [ oj-input-number, oj-input-text ].

getClassesFromStyle(string styleName) string[] | null

styleName is a class attribute style name.

Returns the classes using the specified style name. For example, for the style oj-button-sm, the returned value would be [ oj.ojButton, oj.ojMenuButton].

getClassFromTag(string tagName) string | null

tagName is the HTML element name (specified with/without the surrounding chevrons).

Returns the class (e.g.,oj.ojTable) for a given JET element name (such as oj-table). Returns null if tagName is not a defined JET element name.

getTagFromClass(string className) string | null

className is a JET class name.

Returns the JET element name (e.g., oj-table) for a given class name (such as oj.ojTable). Returns null if className is not a known JET class.

getClassFromModule(string module) string | null

module is a specification such as ojs/arraydataprovider.

Returns the class (e.g., oj.ArrayDataProvider) for a given module path (such as ojs/arraydataprovider).

getTagPropType(string tagName, string propName) string | null

This method is deprecated as of JAF release 7.0.0. You should now use getTagAttrType().

tagName is the web component name (specified without the surrounding chevrons). propName is the name of the property specified in the component.json properties.

For web components that have been inspected by JAF during startup because they are defined in the Oracle JAF configuration property components.

Returns the property type (type sub-property) defined for a property in the Oracle JAF component.json file.

getTagPropertyFromEvent(string tagName, string eventAttrName) string | null

Returns a property name from a tag event attribute. For example:

getTagPropertyFromEvent('oj-pop-up', 'on-oj-before-close')   -->   'ojBeforeClose'
getTagPropertyFromEvent('oj-pop-up', 'onOjBeforeClose')      -->   'ojBeforeClose'
isBindingTag(string tag) boolean

tag is the HTML element name (specified with/without the surrounding chevrons).

Returns true if the element tag is defined with @ojbindingelement (such as oj-bind-if, or oj-bind-for-each).

isClass() boolean

Returns true if component/class is a JET class name (e.g., oj.ArrayDataProvider).

isClassRenamed(string className) Object | null

className is a JET class name (e.g., oj.ArrayDataProvider).

Returns an object with the new name and the JET version in which it was renamed. For example:

{  
  to : "new class name",
  since :  "x.y.z"
}

Returns null if the class is not renamed.

isClassDeleted(string className) string | null

className is a JET class name (e.g., oj.ojAccordian).

Test if a component/class (e.g., oj.RouterState or oj.ojTree) is deleted from a version, and if so returns the (semantic) version in which it was deleted. Returns null if not deleted.

isClassDeprecated(string className) string | null

className is a JET class name (e.g., oj.ojAccordian).

Test if a component/class (e.g., oj.RouterState or oj.ojTree) has deprecated status, and returns the suggested alternative if it is. The suggested alternative is a string supplied by the developer in the class's API doc. Returns null if not deprecated.

isClassMethodDeleted(string className, string methodName) string | null

className is a JET class name (e.g., oj.ojAccordian). methodName is a method of the class.

Test if a component/class (e.g., oj.RouterState or oj.ojTree) method is deleted from a version, and if so returns the version in which it was deleted. Returns null if the method is not deleted.

isClassMethodDeprecated(string className, string methodName)

Array.<Object> | null

string | null

className is a JET class (e.g., oj.ojAccordion). methodName is a method of the class.

Tests if a JET component/class (e.g., oj.ojDialog) method has deprecated status and returns information including a suggested alternative and the version when deprecated. Multiple entries might be returned, and each object's target property should be checked for relevance. Each object is of the component.json deprecated type status object format.

Prior to JAF 3.1.0: Tests if a component/class (e.g., oj.RouterState or oj.ojTree) method has deprecated status, and returns the suggested alternative if it is. The suggested alternative is a string supplied by the developer in the class's API doc. Returns null if the method is not deprecated.

isClassMemberDeleted(string className, string memName) string | null

className is a JET class name (e.g., oj.ojAccordian). memName is an attribute name.

Test if a component/class (e.g., oj.RouterState or oj.ojTree) member is deleted from a version, and if so returns the version in which it was deleted. Returns null if the member is not deleted.

isClassMemberDeprecated(string className, string memName)

Array.<Object> | null

string | null

className is a JET class (e.g., oj.ojAccordion). memName is an attribute name.

Tests if a JET component/class (e.g., oj.ojDialog) method has deprecated status and returns information including a suggested alternative and the version when deprecated. Multiple entries might be returned, and each object's target property should be checked for relevance. Each object is of the component.json deprecated type status object format.

Prior to JAF 3.1.0: Tests if a component/class (e.g., oj.RouterState or oj.ojTree) member has deprecated status, and returns the suggested alternative if it is. The suggested alternative is a string supplied by the developer in the class's API doc. Returns null if the member is not deprecated.

isClassFinal(string className) boolean

className is a JET class name (e.g., oj.Module).

Returns true if the class is final.

isClassMethodFinal(string className, string methodName) boolean | null

className is a JET class name (e.g., oj.Module). methodName is a method of the class.

Returns true if the method is static, else false. Returns null if the className or methodName is undefined.

getClassMethodScope(string className, string methodName) string | null

className is a JET class name (e.g., oj.Module). methodName is a method of the class.

Returns instance or static. Returns null if the className or methodName is undefined.
getDeletedMethodList() Object

Make a list of deleted methods as a rule helper.

Returns {Array.<Object>} with an object with method names as the properties. Each property value is an array of class names in which it was deleted, followed by the version in which it was deleted.

getDeletedMemberList() Object

Make a list of deleted members as a rule helper. Returns {Array.<Object>} with an object with member names as the properties. Each property value is an array of class names in which it was deleted, followed by the version in which it was deleted.

isRuleIgnored(string tag, string ruleName) boolean

tag is the HTML element name (specified with/without the surrounding chevrons). ruleName is the name of the rule to be tested for exclusion.

Tests if the rule is excluded for the component by its appearance in the component's optional extension metadata. For example:

{
   . . .
   "extension" : {
      "audit" : {
         "ignore" : [rulename1, rulename2, ...]
      }      
   }
   . . .
}

The method returns true if the rulename is declared in the component's metadata, else false.

getRenamedClassList() Object

Get a list of JET classes that have been renamed. The following object is returned:

{
   "old_classname": {                           // e.g.  "oj.ArrayDataProvider"
                      to    : "new_classname",  // e.g.  "ArrayDataProvider"
                      since : "a.b.c"           // e.g.  "8.2.0"
                    },
                    . . .
}
getRevisionInfo() Object

Returns an object with the following properties:

  • jetVersion - The JET version of the metadata. (string)
  • revision - The JET source revision info, currently from GIT. (string)
  • tag - The JET source GIT tag. (string)
getMetaVers() Object

Returns an object with the following properties:

  • versions - The JET version supported, and the build dates. (Object)
    {
      "6.2.2" : {
                  "date" : "ddddddd",
                  "time" : "ttttttt"
                },
      . . .
    }
  • default - The default JET version, if configuration property metaVer is omitted. (String)
getSubcomponentType() string Returns the component subcomponentType metadata property as a string (e.g., packPrivate, data, etc.).
isInterfaceImplemented() (string tagName, string interfaceName) Returns true if the specified interface name is implemented by the tagName component
getInterfaces() Array<string> Returns an array containing the names of the interface(s) implemented by the referenced component tagName (e.g., oj-button).
getImplementers() Array<string> Returns an array of the names of components implementing the specified interface.
hasJetWCInterfaces() boolean

Tests whether the selected JET metadata (via the config jetVer property) contains web component interface information.

hasWCInterfaces() boolean

Tests whether any web components known to JAF (JET or non-JET ) have implemented interfaces.

getWCInterfaces() Object
If any web component known to JAF declares an implemented interface, an object is returned of the form:
{
            interface_name_1 : [component_tag_1,  . . .],
            interface_name_2 : [component_tag_3,  . . .],
             . . .
            }
walkDomStackForOJTag(Object context [, boolean excludeBindIf]) string | null

context is the context object passed to the rule.

Convenience method. Walks back up the DOM from the current element to see if there is a containing JET parent element. If found, the name of the JET element is returned. Optional argument excludeBindIf can be used to ignore <oj-bind-*> elements during the walk.

getStyleOrigin() string Returns a code denoting if the style is a JET component style, a JET generic style class, or a non-JET user custom style.
isTagPackPrivate() boolean Returns true if the web component is marked as packPrivate in its metadata.

Utils: General Non-File System Functions

Utils is a collection of non-file system utility functions.

Access these non-file system utility functions through the rule context object property context.utils.utils as an instance of a library object. They may be helpful when writing audit rules.

Method Returns Description
hasAnyProps(Object object) boolean Returns true if the object has any non-inherited properties
isProperty(Object object, string name) boolean Returns true if the object has the named property. The property name can be a compound dot-separated name, such as extension.catalog.readme.
getProperty(Object object, string name) * Returns the object's named property value. The property name can be a compound dot-separated name, such as extension.catalog.readme.
getType(* varName) string Returns the type of a variable. This function returns a true type value. For example: the typeof operator returns object for an array, whereas this function returns array. The following values can be returned (all lower-case) : object, array, string, number, boolean, null, undefined.
isArrayContentsType( array[] array, string type) boolean Traverses an array, matching each element's type to the supplied (lower-case) type string. The type string can be one of the following : object, array, string, number, boolean, null, or undefined
eatWhitespace( string string, number startIndex) number Traverses a string, optionally starting at the startIndex index, and returns the index to the first non-whitespace character. Returns 1 if no non-whitespace is found. If startIndex is omitted or invalid, it defaults to zero.
getIndexToWhitespace(string string, number startIndex) number Traverses a string, optionally starting at the startIndex index, and returns the index to the first whitespace character. Returns -1 if no whitespace is found. If startIndex is omitted or invalid, it defaults to zero.
decommentJson() string

Replaces the // and /* */ sequences in a JSON string with blanks to preserve the relative line/column positions of the content tokens.

parseJson() * Parses a JSON string and returns the parsed object, or an error object containing a syntax error message together with supplemental position information that may be used to augment the message, if required.

FsUtils: File System Functions

FsUtils is a collection of file system utility functions.

Access these file system utility functions through the rule context object property context.utils.fsUtils as an instance of a library object. They may be helpful when writing audit rules.

Method Returns Description
getFileTypeSync(string filePath) string | Error

Checks the file at filePath and returns:

  • f - file
  • d - directory

If an error occurs, an Error exception object is returned. Note if the path is a symbolic link, the file type of the link target is returned (for example, "f" or "d"). Use isSymLink() to determine if the path represents a symlink.

getFileExtSync(string filePath) string Returns the file extension for the supplied path. If the path is a symbolic link, the file extension for the link's target file is returned. If the file path cannot be accessed, an empty string is returned.
isSymLinkSync(string filePath) boolean Returns true if the file path is a symbolic link, else false. In case there is an error processing the file path, false is returned.
pathExistsSync(string filePath) boolean Returns true if the file path exists.
fileExistsSync(string filePath [, boolean dir ] ) boolean Returns true if file/directory exists, else false.
readFileSync(string filePath [, boolean error | Function error(string message)] string | null

Reads a text file and returns the contents as a string, or null if unsuccessful.

If the file read is unsuccessful, the action taken depends on optional argument error:

  • If boolean true, an exception is thrown.

  • If boolean false, an error string is returned.

  • If omitted, the function returns null.

  • If a function is defined, it will be called with a string argument representing the error message, and the return value of readFileSync() will be null.

readFileBufSync(string filePath [, boolean error | Function error(string message)] Buffer | null

Reads a text file and returns the contents as a Buffer, or null if unsuccessful.

If the file read is unsuccessful, the action taken depends on optional argument error:

  • If boolean true, an exception is thrown.

  • If boolean false, an error string is returned.

  • If omitted, the function returns null.

  • If a function is defined, it will be called with a string argument representing the error message, and the return value of readFileBufSync() will be null.

readJsonSync(string filePath [, boolean comments [, boolean | Function error ]] ) Object | string | null

Reads a JSON file and returns the object.

If optional argument comments is set to true, comments are permitted in JSON.

Optional argument error can be used to indicate how errors should be handled:

  • If true, an exception is thrown.

  • If false, an error string is returned.

  • If omitted, the function returns null.

  • If a function is defined, it will be called with a string argument representing the error message, and the return value of readJsonSync() will be null.

Error strings are prefixed with SYNTAX: or NOFILE:.

writeJsonSync(Object obj, string filePath [, Object opts [, boolean | Function error ]] ) boolean | string

Writes an object to the specified file path as a JSON file, and returns true.

Optional object opts has the following optional properties:

  • spaces can be a number to indent each line, or a string to prefix each line.

  • replacer a JSON stringifer() replacer.

Optional argument error can be used to indicate how errors should be handled:

  • If true, no return value (error thrown)

  • If false, an error string is returned.

  • If a function is defined, it will be called with a message string argument, and writeJsonSync() returns false.

If error is omitted, false is returned.

readDirSync(string filePath) Array | null

Reads a directory and returns a hierarchical array of objects of the following form:

[
  {
    name : "filename1",       // for file in a folder
    isFile : true
  },
  {
    name : "directory1",      // for each sub-folder 
    isFile : false,
    files : [
              {
                name : "filename1",
                isFile : true
              },
              ...
            ]
  },
  ...
]
walkDirSync(string dirPath, Function cb, [boolean fwdSlash]) none

Recursively walk a directory tree invoking a callback function with the full path to the file or sub-directory.

dirPath is the initial directory path to walk.

cb is a callback function that receives the following args:

     (string fpath, string ftype)
        fpath is the full file or sub-directory path
        ftype = 'f' for a file, 'd' for a sub-directory, 'l' for a symbolic link.

Optional arg fwdSlash set to true forces the fpath string in the callback to use the forward slash in place of the Windows escaped "\\" if found.

Normally the callback function returns nothing - however it can optionally return

    "exit"      to terminate the walk,
    "direxit" to  terminate further walking of the current sub-directory

For example, to find all .JS files in a directory tree:

walkDirSync("some/path", (fpath, ftype) => {
 
         if (ftype === "f" && fpath.endsWith(".js")) {
             // do something
         }
}) ;

When reading the files in a directory, if a sub-directory is found, that sub-directory is examined next, and so on.

createFolderSync(string filePath) boolean
Create a folder. The file path can contain multiple folders that also need to be created. For example:
createFolder("./folder1/folder2/folder3") ;

Note: folder3, folder2 and folder1 are created if they don't exist.

deleteFolderSync(string filePath [, boolean deleteTarget]) none Deletes the contents (files/directories/sub-directories) of the directory specified by filePath. If optional argument deleteTarget is specified, and is true, the directory specified by filePath is also deleted.
getUniqueFilenameSync(string template) string
Returns a unique file name based on a template. All instances of the letter X are replaced. For example:
getUniqueFilename('@@users-XXXXXX.tmp')

could return @@users-wKFMN5.

SemVerUtils: Semantic Version Functions

SemVerUtils is a collection of semantic version (SemVer) utility functions.

Access these semantic version utility functions through the rule context object property context.utils.semVerUtils. They may be useful when writing audit rules. All method arguments are strings.

Method Returns Description
isValid(string semver) boolean

Returns true if the semver string is valid semantic version syntax.

isValidRange(string semver) boolean

Returns true if the semver string is a valid range of semver comparators.

satisfiesRange(string semver, string range) boolean

Returns true if semver satisfies the range.

minVersion( string range) string | null

Returns a major.minor.patch string representing the lowest version that can possibly match the given range. Null is returned if range is invalid.

For example: minVersion('>=1.0.0') returns '1.0.0'.

Requires JAF version 2.9.9 or later.

prerelease( string semver) Array | null

Returns an array of prerelease tags extracted from semver. If semver does not contain any prerelease tags (or semver is invalid), null is returned.

For example: prerelease('1.2.3-alpha.1') returns ['alpha', 1 ].

Requires JAF version 2.9.9 or later.

eq(string semver1, string semver2) boolean

Compares two semvers and returns true if they are logically equivalent, even if they are not exactly same string.

lt(string semver1, string semver2) boolean

Compares two semvers and returns true if semver1 is less than semver2.

lte(string semver1, string semver2) boolean

Compares two semvers and returns true if semver1 is less than or equal to semver2.

gt(string semver1, string semver2) boolean

Compares two semvers and returns true if semver1 is greater than semver2.

gte(string semver1, string semver2) boolean

Compares two semvers and returns true if semver1 is greater than or equal to semver2.

major(string semver) number

Returns the major version number from the semver.

minor(string semver) number

Returns the minor version number from the semver.

patch(string semver) number

Returns the patch version number from the semver.

parse(string semver) Object | null

Parses semver into an object. Null is returned if semver is invalid.

For example, parse('1.2.3-alpha.1') returns:

{
   "options" : {
      "loose" : false,
      "includePrerelease" : false
   },
   "loose" : false,
   "raw" : "1.2.3-alpha.1",
   "major" : 1,
   "minor" : 2,
   "patch" : 3,
   "prerelease" : [ "alpha", 1 ],
   "build" : [],
   "version" : "1.2.3-alpha.1"
}

Require JAF version 2.9.9 or later.

DomUtils: Node Object Functions

DomUtils is a collection of Document Object Model (DOM) utility functions and helper functions.

Access these DOM utility function through rule context object property context.utils.DomUtils. Most methods take a node object, which is found in context.node, and some methods require an attribute name or element name string.

Method Returns Description
getName(Object node) string Returns the element name of the supplied node.
getType(Object node) string Returns the type of the node (tag, directive, or comment).
getChildren(Object node) nodes[] Returns an array of child node objects for the supplied node.
getParent(Object node) node Returns the parent node object of the supplied node.
getSiblings(Object node) nodes[] Returns an array of sibling node objects of the supplied node.
getAttribs(Object node) Object Returns an object containing attribute name/value properties.
getAttribValue(Object node, string[] attrName) string Returns the specified attributes value.
hasAttrib(Object node, string attrName) boolean Returns true if the node has the named attribute, else false.
hasChildren(Object node) boolean Returns true if the node has children, else false.
hasNext(Object node) boolean Returns true if there is a next node, else false.
getNext(Object node) node Returns the next node, else null.
getFirst() node Returns the first (i.e top) node.
getFirstElem() node Returns the first (i.e. top) tag node.
getLast() node Returns the last node.
getElemsByName(string elemName) nodes[] Returns an array of node objects with the specified element name (such as div ).
getElemById(string id) node Returns the node for the element with specified id attribute value.
getBody() node Returns the <body> node (or null if not found).
getHead() node Returns the <head> node (or null if not found).
getLinks() node[] Returns an array of <link> tag nodes in the <head> section (or an empty array if none found).
getScripts() node[] Returns an array of <script> tag nodes in the <head> section (or an empty array if none found).
getElems() nodes[] Returns an array of node objects for all elements. (Nodes such as text, comments, directives, etc. are ignored.)

DomUtils also contains additional non-DOM tree helper functions that are useful when writing rules.

Method Returns Description
extractAttribsFromDataBind(string attrValue) Object | null Given a data-bind with an attr property, returns an object where each property is the name/value extracted from the data-bind string.
extractComponentFromDataBind(string attrValue) string | null Given a data-bind attribute value, returns the JET component name instantiated, or null if not found or not a JET component.
getAttribIndex(string data, Object node, string attrName) number Returns the position (relative to zero) in the data of the named attribute for the node.
getAttribPosition(string data, Object node, string attrName) Object

Returns the position of the named attribute for the node in the data. The object has the following members:

  • row : number
  • col: number
  • start: number // index (relative to zero) to the attribute's value in the file data
  • end: number // index to the last character of the attribute's value in the file data

This method is useful when a rule listens to tag node events but needs to report on the position of a particular tag attribute's value. This information can be applied to an Issue object via its setPosition() method.

getAttribValuePosition(string data, Object node, string attrName) Object

Returns the position of the named attribute's value in the data for the tag node. The object has the following members:

  • row: number
  • col: number
  • start: number // index (relative to zero) to the attribute into the file data
  • end: number // index to the last character of the attribute in the file data

This method is useful when a rule listens to tag or ojtag events, but needs to report on a particular attribute in the tag. This information can be applied to an Issue object via its setPosition() method.

getLineCol(string data, number index number) Object
Returns the line and column for a given index into file data. The object has the following members:
  • row: number
  • col: number
getComponentElems() nodes[] Returns an array of nodes for JET custom elements.
getDataBindAttrs(Object context) Object | null Checks the current node in context, and if it contains a data-bind attribute with a attr property, returns an object where each property is the name/value extracted from the data-bind string.
getDataBindComponent(Object context) string | null Checks the current node in context, and if it contains a data-bind attribute, extracts the JET component name if defined in the attribute value,
getElemById(string id [, boolean labelId]) Object | null Searches the DOM for a node with the specified id attribute value and returns the DOM tree node if found. If optional argument labelId is set to true, the search also includes the label-id attribute.
hasBody(Object context) boolean Returns true if the HTML page has a <body> element.
isChildOfElem(string elemName, Object node) boolean Returns true if the DOM tree node is a child of the element named elemName.
isCommonAttr(string attrName) boolean Returns true if the specified attribute is a standard defined xxx. (Note: if attrName is prefixed with ':', the prefix is ignored).
isCommonElem( string elemName) boolean Returns true if the specified element is a standard defined xxx.
isCommonEventAttr(string attrName) boolean Returns true if the specified attribute is a standard xxx defined xxx. (Note: if attrName is prefixed with ':', the prefix is ignored).
isHtml5ObsoleteElem(string elemName) boolean Returns true if the specified element is obsolete in HTML5
isHtml5ObsoleteAttr(string elemName, string attrName) boolean

Returns true if the attribute is obsolete in HTML5 for the specified element.

Note: the return value is unconditional. There may be additional exception conditions that need to be evaluated (for example, the border attribute on <img> ) - refer to xxx.

isJetPage(Object context) boolean Returns true if there is at least element with a name starting with oj-
isNamespaceTag(string tagName) boolean Given a Web Component element name starting with oj- (e.g. oj-ext-foo), this returns true , if the prefix (oj-ext in this example) is defined in the xxx.
isNamespacePrefix(string tagPrefix) boolean Given a Web Component name prefix starting with oj- (for example oj-ext), this returns true , if the prefix is defined in the xxx .
isNonFragmentJetPage(Object context) boolean Returns true if the HTML page has a <body> and also has at least one JET component element.
isSvgElem(string elemName) boolean Returns true if the element name is an SVG element
isValidJson(string json) boolean | string Checks a string to see if it is JSON, and if so, validates it. If the string is valid JSON, or is not JSON, true is returned. If it is JSON and is not well formed a message string is returned. (Note: the JSON can contain // and /* . . . */ style comments - these are ignored.)
isValidSvgPath(string svg) boolean If the string appears to be a valid SVG path, true is returned. Note this does not validate the path for being syntactically correct SVG.
isExpression(string ) boolean Returns true if the string has valid expression delimiters {{. . .}} and [[. . .]] and they are matched correctly.
getExpression(string ) string|null Returns the expression contained within the expression delimiters {{. . .}} and [[. . .]]. If not an expression or the expression is not validly delimited, null is returned.
camelCase(string prop) boolean Returns a camel-cased string from a kebab-cased property string.
kebabCase(string prop) boolean Returns a kebab-cased string from a camel-cased property string.
kebabCaseEvent(string prop) boolean Returns a kebab-cased string from a camel-cased event name.

JafLib: JAF Core Access Methods

JafLib is a library of exposed core Oracle JAF lifecycle methods.

Access these methods through the rule context object property context.utils.jafLib.

Method Returns Description

setFileset(Objectcontext, string[] fileset[, string[] exclude])

boolean

Sets the file set to audit. This is a dynamic replacement for the files and exclude properties of the configuration file. fileset and optional exclude specify an array of full file paths. Globs may be used. context is the rule context object.

Returns true if successful, else false.

This method may be useful when writing hook rules. The method can be used only during the startaudit phase of the audit lifecycle.

getFileset(Object context) Object

Returns the files and exclude configuration properties in an object with the same property names.

context is the rule context object.

Do not modify the object property values! To modify either files and/or exclude properties use setFileset().

Note that this can be used in conjunction with setFileset() to merge or remove entries.

This method may be useful when writing hook rules. The method can be used only during the startaudit phase of the audit lifecycle.

getConfig() Object

Returns an object with getter methods that return configuration property values. Refer to JafLib: Configuration Object Property Getter Methods.

getTsConfig() Object

Returns the tsconfig.json as an object.

getRunMode() string Returns a string representing the JAF run mode. Values are cli, api, or amd. Currently, running in CLI mode only is possible.
isCLI() boolean Returns true if running in CLI mode (the only mode currently available).
isAPI() boolean Currently returns false. Note that API mode is reserved for future support.
isAMD() boolean Currently returns false. Note that AMD mode is reserved for future support.
getJafVer() string Returns the JAF version semver, for example: 3.12.4.
getJetVer() string Returns the JET metadata version semver, for example: 9.2.3.

JafLib: Configuration Object Property Getter Methods

JafLib exposes the getConfig() method to access JAF configuration property values.

The configuration object returned by JafLib.getConfig() contains methods returning configuration property values. Note that due to configuration analysis during startup, property values returned do not necessarily reflect the same values. For example, if the configuration property theme is not defined, Config.getTheme() will return the default value alta and not undefined.

Method Configuration Property Returned
getComponents() components
getComponentsBase() componentsBase
getComponentsBaseUrl() componentsBaseUrl
getComponentOptions() componentOptions
getDisable() ruleMods.disable
getEcmaVer() cmaVer
getEnable() ruleMods.enable
getExclude() exclude
getFiles() files
getGroups() groups
getJetVer jetVer
getMessages() messages
getOptions() options
getOutPath() outPath
getRuleDescriptions() ruleDescriptions
getRuleMods() ruleMods
getRuleNames() ruleNames
getRulePacks() rulePacks
getTheme() theme
getTypescript() typescript
getTsConfig() typescript.tsconfig
getTsConfigObj() Returns the tsconfig.json found on the path defined by the typescript.tsconfig sub-property, as an object.
isBuiltinJetRules() builtinJetRules
isBuiltinJetWcRules() builtinJetWcRules
isBuiltinSpocRules() bultinSpocRules

MsgLib: Message Display Functions

MsgLib is a namespace property providing access to Oracle JAF internal messaging routines.

Access these internal messaging routines through the rule context object property context.utils.msgLib as an instance of a library object. They may be helpful when you need to provide the ability for an audit rule to write conditional and unconditional messages to the output. Refer also to the context property sysOpts.

Method Description
msg() Writes a general message string to the console. For example: msgLib.msg("this is a message").
info() Writes the message string to the console only if verbose mode is on. For example: msgLib.msg("this is only displayed in verbose mode"). The message is preceded by [info]:.
debug() Writes the message string to the console only if debug mode is on. For example:msgLib.debug("this is only displayed in debug mode"). The message is preceded by [debug]:.
error() Writes the message to the console. For example: msgLib.error("this is an error message"). The message is preceded by [error]:.
assert() Writes a message string to the console. For example: msgLib.assert("this is an assertion message"). The message is preceded by [ASSERT]:.

CssUtils: CSS Utility Functions

CssUtils is a library of CSS rule processing functions.

Access these functions through the context property context.utils.CssUtils on the register context object when the rule is invoked or on the rule context object passed to the registered listener. These functions may be useful when writing CSS rules.

Method Returns Description
isColorName(string name ) boolean

Returns true if the string is a CSS defined color (for example, "coral"). Accepts all color names to CSS Color Module Level 4.

isMarkerstyle(string style ) boolean

Returns true if the style string is an Oracle JET marker style.

getPosition(Object context, Object loc) Object

Converts a loc position node in the CSS Abstract Syntax Tree (AST) to a position object suitable to pass to Issue.setPosition(). The resulting position object is adjusted for the origin of the CSS text.

AstUtils: JavaScript File Helper Functions

AstUtils is a collection of Abstract Syntax Tree (AST) helper functions.

Access these functions through the rule context object property context.utils.AstUtils. They may be useful when writing audit rules for JavaScript files. For example:

var node = ruleContext.utils.AstUtils.getBody();  // get the array of program body nodes
Name Returns Description
getBlock(Object node) node Returns the block node in which the specified node resides. If node is not specified, the outer program block is returned.
getBody(Object node) Array[] Returns the body array of nodes containing the specified node. If node is not specified, the body of the program is returned.
getProgram() node Returns the Program node.
isFuncArg(Object node, string var) true if the variable is an argument to the function, else false. Tests if a variable found in an expression in any node in the body of a function is declared as an argument to that function.
isCommonDocApi(string methodName) true if the method is a common Document method. Tests if a method is a common Document method (for example, getElementById()).
parseDefine(Object node)

An an object with members of the form:

<function arg> : <module path>

Parses a KO define statement.
getNodeTypes()

An an object with members of the form:

<function arg> : <module path>

Returns an object mapping abbreviated node types for JavaScript. For details, see the list of node type constants in Listener Types for JavaScript/TypeScript Rules.

SevLib: Severity Support Helper Functions

SevLib is a collection of helper functions that provides support to process severity levels that have been remapped via the Oracle JAF configuration property sevMap.

Access these functions through the rule context object property context.utils.SevLib. They may be useful when writing audit.

Name Returns Description
map(string sev) string Maps a severity. If severity is not mapped, the unmapped severity is returned. For example, map("major") will return the mapped value, or major if not remapped.
unmap(string sev) Array.<string> Unmaps a severity. If the severity does not represent a mapped severity value, the supplied severity is returned. If there more than one severity has been unmapped, it returns all unmapped severity strings in an arrary. For example, given the following:
"sevMap" :{
    "sevSet" : {
        "blocker" :  "mustfix",
        "critical" : "mustfix", 
        "major" :    "mustfix",
        "minor" :    "warning",
        "info" :     "warning"
    }
}

Then context.utils.sevLib.unmap('mustfix') returns ["blocker","critical","major"].

isMapped(string sev) boolean Test if a severity is a remapped severity.
getList() Array.<string> Returns an array of JAF default severities. For example, blocker, critical, and so on in ascending order of priority.
getMap() Object Returns an object whose properties are the JAF default properties, and the corresponding values are the user mapped severities. If severities have not been remapped, null is returned.
getInvertedMap() Object Returns an inverted form of the object returned by getMap(), whose properties are the remapped properties, and the corresponding values are the JAF default properties. If severities have not been remapped, null is returned.
isSev(string sev) boolean Returns true if the supplied severity is a valid value. May be a core severity or a remapped value.
getMsgSev(string msgId) string | null Returns the severity for the msgId (for example, JET-2000), or null if the msgId is not defined.
matchSeverityLevel(string sev) boolean Tests if the supplied severity is matched by the JAF configuration property severity value/expression.
isBlocker(string sev) boolean Returns true if the severity (mapped or unmapped) represents blocker.
isCritical(string sev) boolean Returns true if the severity (mapped or unmapped) represents critical.
isMajor(string sev) boolean Returns true if the severity (mapped or unmapped) represents major.
isMinor(string sev) boolean Returns true if the severity (mapped or unmapped) represents minor.
isInfo(string sev) boolean Returns true if the severity (mapped or unmapped) represents info.

TsxUtils: TSX Utility Functions

TsxUtils is a utility library available through the rule and registration contexts as context.utils.tsxUtils.

Method Returns Description
extractTsxProperties( Object ruleCtx, Object TsxRenderComponent, Function callback ) nothing

Given a TsxRenderComponent object, the callback function is called for each tag attribute found in the TsxRenderComponent object.

( Object ruleCtx, Object TsxComponent, Object Prop )

where TsxComponent is a TsxComponent object, and Prop is a property object (a member of TsxComponent)

Note:

  1. When the extractTsxProperties() method has processed all properties (or iteration is terminated, see 2) below), it makes a final call to the callback method with a null value for argument Prop.
  2. For normal processing, the callback function does not need to return any value. If, however, it wishes to terminate the iteration before all properties have been processed, it can return one of two string codes:
    • Return value of end that terminates all futher iteration over the TsxRenderComponent.
    • Return value of next-comp that terminates all futher iteration over the TsxRenderComponent.

getExpressionObject(TsxProperty prop)

Object | null

Returns an object derived from a Preact object expression. For example, given the following snippet:

<xxx myProp={{prop1: 42, prop2: "foo"}}

Then using the TsxProperty object for myProp

     getExpressionObject(TsxProperty)  

returns the following object:

{
   prop1: 42,
   prop2: "foo"
}

The method returns null if the outer-braces of the property value do not contain an object expression.

isPropertyObjectExpr(TsxProperty | tsxComponent propOrComp, [string propName] )

boolean

Returns true if the property value of the TsxProperty, or the value of the TsxComponent with the named property, is an Object expression. For example:

   someProp={ { . . . } }

where argument propOrComp is a TsxProperty or a TsxComponent object.

If the first argument is a TsxComponent, the second argument, propName, is required. It is not used for a TsxProperty.

isPropertyPreactExpr(TsxProperty | TsxComponent propOrComp, [string propName] )

boolean

Returns true if the property value of the TsxProperty, or the value of the TsxComponent with the named property, is a Preact expression. For example:

someProp=(. . .)

where argument propOrComp is a TsxProperty or a TsxComponent object.

If the first argument is a TsxComponent, the second argument, propName, is required. It is not used for a TsxProperty.

isPropertyString(TsxProperty | TsxComponent propOrComp, [string propName] )

boolean

Returns true if the value of TsxProperty, or the value of a TsxComponent with the named property, is a string value

Where argument propOrComp is a TsxProperty or a TsxComponent object.

If the first argument is a TsxComponent, the second argument, propName, is required. It is not used for a TsxProperty.

setIssuePosition(Object issue, Object compOrProp)

nothing

Updates the supplied Issue instance, with the positional information in the supplied TsxComponent or TsxProperty object.

issue is the instantiated Issue object, and compOrProp is a TsxComponent or TsxProperty object.

setIssuePropValuePosition(Object issue, Object tsxProp)

nothing

Updates the supplied Issue instance, with the property value positional information in the supplied TsxProperty object.

issue is the instantiated Issue object, and tsxProp is a TsxProperty object.

getChildren(Object tsxComp) Object|null

Returns an array of child TsxComponent objects.

tsxComp is the TsxComponent whose children are required.

getAncestor(Object tsxComp [string compName] ) Object|null

Returns the first found named ancestor component of the supplied component.

where:

  1. tsxComp is the TsxComponent object whose ancestors are to be searched
  2. optional compName is the name of the ancestor component to be found. If omitted, the name of the tsxComp component is used.

Returns the found TsxComponent, or null if not found.

getDescendant(Object tsxComp [string compName] ) Object|null

Returns the first found named descendant component of the supplied component.

where:

  1. tsxComp is the TsxComponent object whose descendants are to be searched
  2. optional compName is the name of the descendant component to be found. If omitted, the name of the tsxComp component is used.

Returns the found TsxComponent, or null if not found.

getProperty(TsxProperty | TsxComponent propOrComp, string propName) Object| null Returns the TsxProperty object for the named property from a TsxComponent. If a TsxProperty object is supplied, the argument is returned (and the property name is ignored if supplied).
getPropertyValue(Object tsxComp, string propName) Object Returns the value node for the named property from a TsxComponent.
getPropertyRawValue(Object tsxComp, string propName, boolean stripDelims) string Returns the raw value of the named property from a TsxComponent. Note: if the property value is a string, this will include the delimiting quotes unless the optional stripDelims argument is set to true.
getPropertyStringValue(TsxProperty | TsxComponent propOrComp, [string propName] string | null | undefined

Returns the string value of the property if the property type is a string. If the property is empty and has no value (e.g. the HTML 'disabled' attribute) the returned value is undefined. If the value type is not a string or the property is not found, null is returned.

Argument propOrComp may be a TsxProperty or a TsxComponent object. If propOrComp is a TsxComponent, the second argument, propName, is required. It is not used for a TsxProperty.

getRawText( Object ruleCtx, Object tsxRC) string Returns the raw text used to create the TsxRenderComponent.
getSlotParent(Object ruleCtx, TsxProperty tsxProp, string slotName ) TsxComponent | null Returns the parent TsxComponent that resolves the specified slot name.

The following additional methods (normally exported by DomUtils for HTML rules) can also be found in TsxUtils, since DomUtils is not available in the rule/registration context for TSX rules.

Method Returns Description
isAriaAttr(string attrName) boolean Returns true if the specified attribute is a known ARIA attribute.
isCommonAttr(string attrName) boolean Returns true if the specified attribute is a standard defined xxx. (Note: if attrName is prefixed with ':', the prefix is ignored).
isCommonElem( string elemName) boolean Returns true if the specified element is a standard defined xxx.
isCommonEventAttr(string attrName) boolean Returns true if the specified attribute is a standard xxx defined xxx. (Note: if attrName is prefixed with ':', the prefix is ignored).
isHtml5ObsoleteElem(string elemName) boolean Returns true if the specified element is obsolete in HTML5
isHtml5ObsoleteAttr(string elemName, string attrName) boolean

Returns true if the attribute is obsolete in HTML5 for the specified element.

Note: the return value is unconditional. There may be additional exception conditions that need to be evaluated (for example, the border attribute on <img> ) - refer to xxx.

isNamespacePrefix(string tagPrefix) boolean Given a Web Component name prefix starting with oj- (for example oj-ext), this returns true , if the prefix is defined in the xxx .
isNamespaceTag(string tagName) boolean Given a Web Component element name starting with oj- (e.g. oj-ext-foo), this returns true , if the prefix (oj-ext in this example) is defined in the xxx.
isSelfClosingTag(string tagName) boolean Returns true if the tag is a self-closing tag (such as <br> or <hr>, and so on).
isSvgElem( string elemName) boolean Returns true if the element name is an SVG element.
isSvgPath(string svg ) boolean Returns true if the string appears to be a valid SVG path. Note: This method does not validate the path for being syntactically correct SVG.