1 Get Started with the Oracle JET Audit Framework
The Oracle JET Audit Framework (JAF) is a command-line utility and supporting API that allows you to audit JET applications by using a rich set of built-in audit diagnostic rules. The API supports extending JAF with custom audit rules that you write to meet specific diagnostic requirements of your application.
About Auditing Oracle JET Applications
Oracle JET Audit Framework (JAF) is dynamic and performs an audit of Oracle JET project files based on runtime options it finds in a configuration file.
To get started with JAF, the initial creation of the configuration file is automated to help you get up and running quickly. After a default configuration file is created, you have many options to tailor the audit to your project needs.
With Oracle JAF installed, audits that you perform against your JET project run in a
command-line interface, similar to the Oracle JET CLI. The installation of JAF provides
a lint-style command-line utility named ojaf
that audits JET
application files (currently HTML, JS, TS, TSX, CSS, and JSON) by applying rules that
perform a static analysis from an Oracle JET perspective.
The audit diagnostic messages returned by invocation of the ojaf
utility result from built-in rule sets that are specific to the Oracle JET release version of the application. As new versions of Oracle JET are released, you can update JAF and keep current with the latest applicable audit rules. For this reason, you will want to update JAF regularly.
The audit rules that are specific to each version of Oracle JET are called the built-in rules. Additionally, you can configure the audit to run with custom, user-defined rules. Both the built-in rules and rules that you may write yourself, are logically and physically grouped together in a rule pack.
Like an Oracle JET installation, installation of Oracle JAF requires that Node.js is installed as a prerequisite. The ojaf
utility will report if the Node.js version does not meet the minimum node version requirement.
Before you run the audit, you use the JET tooling to initialize Oracle JAF and to scaffold a default JAF configuration file, oraclejafconfig.json
. You can customize the properties of the Oracle JAF configuration to control many aspects of both the rule set (the set of active rules) and the file set (the set of files to be audited) for a specific audit run:
-
Any rule may be disabled.
-
One or more rules may be designated by name to be run and all others excluded.
-
Rule groups may be specified (for example, only run rules related to HTML).
-
Rules may selected by severity of the issue they report.
-
All built-in rules may be suppressed (allowing only user-defined rules to run).
-
All rules specified in a defined rule pack may be disabled.
-
The target file set can be defined easily, including by using glob support for both inclusion and overriding exclusion.
-
Multiple configuration files can created for specific runtime criteria or projects. The configuration files are JSON format, but JavaScript/TypeScript style comments are permitted for documentation purposes. The configuration file to be used can be specified on the command-line.
If the built-in audit rules provided with the JAF installation do not meet all the diagnostic requirements of your application, you can write custom audit rules to extend JAF. You implement user-defined audit rules as JavaScript files. The JAF API allows you to register event listeners and handle the audit context created by JAF on the file set of your JET projects. Custom audit rules can be assembled into distributable rule packs and invoked by developers on any Oracle JET application.
Typical Workflow for Auditing an Oracle JET Application
Understand auditing options for Oracle JET web and hybrid mobile applications.
To audit the source files in an Oracle JET application, refer to the typical workflow described in the following table:
Task | Description | More Information |
---|---|---|
Initialize the Oracle JET Audit Framework (JAF) and perform an audit dry-run |
Create a default |
Initialize Oracle JAF and Run an Audit |
Configure JAF | Edit the oraclejafconfig.json file to limit the scope of the audit to the desired file set or rule severity level, for example.
|
Configure the JET Audit Framework |
Run an audit | Report the diagnostic messages discovered by the rule set for a specific Oracle JET version. | |
Fine-tune audit results | Hide diagnostic messages emitted by specified rules or comment source code with JAF comment commands to limit the scope. | Fine Tune the Audit |
Customize audit reports | Format the optional JSON output of the audit in a custom report. | Work with the Output of Audits |
Typical Workflow for Writing Custom Audit Rules
Understand how to interact with the Oracle JAF API and work the various utility libraries to create user-defined, custom audit rules that extend JAF.
To write custom audit rules and assemble your JavaScript implementation files as a rule pack that you can share with JET application developers, refer to the typical workflow described in the following table:
Task | Description | More Information |
---|---|---|
Understand the JAF concepts for writing custom rules |
Learn about the various JAF audit context events and the properties that you can access on the context object passed at runtime to your audit rules by the JAF audit engine. |
About the JAF Audit Engine |
Understand the custom audit rule implementation | Learn how you can handle the audit context object by registering a listener to respond to context events and learn about the miscellaneous helper functions provided by JAF utility libraries that you can access on the context object. |
Understand the Structure of Custom Audit Rules and |
Understand the requirements to create and to distribute custom rules | Set up a JET development environment to implement your custom rules before you distribute the rules as a rule pack. | |
Write custom rules that audit file data parsed by JAF | Review sample custom (node) rules that show how to audit for data nodes returned on your application's target file set, including HTML, JSON, JavaScript/TypeScript, and CSS files. | Implement Custom Node Rules |
Write custom rules that work with the phases of the JAF lifecycle | Review sample custom (hook) rules that show how you can invoke an audit at various stages of the JAF audit lifecycle, such as upon audit startup. | Implement Custom Hook Rules |
Initialize Oracle JAF and Run an Audit
If you have an Oracle JET application you created using the JET command-line interface, then you can auto-configure an audit for the application and run the audit in the command prompt window.
In the JET application, open a command prompt and, from the root directory, use the Oracle JET Audit Framework (JAF) command to initialize a default JAF configuration for the application.
ojaf --init
When you initialize Oracle JAF, the JET tooling scaffolds a default JAF configuration file named oraclejafconfig.json
. The tooling creates the JAF configuration file in the root directory and defines the default configuration settings based on the JET application configuration file oraclejetconfig.json
, also located in the application root directory.
Before you audit the application for the first time, you can confirm the default configuration for the application files that JAF will audit. This command is called a dry-run because it does not audit the application but confirms the files to be audited based on current JAF configuration settings.
ojaf --dryrun
To perform an audit of your application, enter the command to invoke the JAF audit utility.
ojaf
When you run the audit, Oracle JAF searches the directory in which you initiated the audit for the JAF configuration file oraclejafconfig.json
. If no configuration file is found there, then JAF processes only HTML files found in the current directory and will always use the default JAF configuration for the audit.
On subsequent invocations of ojaf
, a check is made to see if the Oracle JET configuration file (oraclejetconfig.json
) has changed since the last ojaf
invocation. If changes are detected, such as might occur when you migrate your application to a new JET version, then JAF updates certain settings in the JAF configuration file automatically. The configuration property settings that JAF monitors and updates based on JET configuration file changes are:
-
jetVer specifies the JET version to be audited against.
-
files specifies the file paths or URLs used to determine the input file set to be audited.
-
exclude specifies the files paths which should be excluded from the audit.
-
components specifies paths to folders where user-defined custom web component metadata (
component.json
) can be found. This provides the ability for rules to inspect the component metadata and to validate custom element attributes. -
theme specifies the Oracle theme (
redwood
,alta
,stable
, ornone
) and affects rules that are theme dependent. In particular, the attributelabel-edge
if not used will have a default value that is dependent on the theme. The Redwood theme is the default if the theme property is not specified, andstable
is considered a synonym forredwood
.
Note that you may freeze a JAF configuration and prevent further automatic updates by editing the oraclejafconfig.json
file and setting the property update as follows.
"ojet": { "update": false, ... }
All other configuration properties remain unchanged, however, you may customize your application audit, by updating the configuration file oraclejafconfig.json
in a text editor and adding or amending JAF properties. A full description of the configuration options are found in About the Oracle JAF Configuration File Properties.
Additionally, you can obtain a complete list of ojaf
command line flags by entering the following command.
ojaf --help
See also Configure the JET Audit Framework and Run Audits on Oracle JET Applications.