Work with the Output of Audits

5 Work with the Output of Audits

You can customize the Oracle JAF configuration to tailor the output for your needs.

About Audit Output

Apart from specifying the scope of the audit by using Oracle JAF configuration properties such as files, excludes, severity, groups, ruleNames, ruleMods, you can also customize the format of the output.

Oracle JAF provides these ways to customize the output of the audit report:

The format of reported issues can be customized by using the proseFormat configuration property. You can also add a custom report title by using the title configuration property.
You can specify that the output format be JSON by using the format and outPath configuration properties, and then you can process this JSON to create any desired output. For example, HTML could be generated for web use, or perhaps other information could be injected into the output and the resulting file distributed in email.

Display Details About a Rule

You can use the rule name or rule message ID from the audit results to obtain a description of the rule.

By default the JAF configuration file format property is set to prose and the rule name will display with the audit message. The rule name is appended to the prose output after the message ID:

[71, 41]  <oj-list-view> attribute 'selection' is deprecated! 
Use selected attribute instead. [JET-0080 : oj-html-ojattr-deprecated]

With the rule name, you can obtain a description of the rule by using ojaf --help.

ojaf --help oj-html-ojattr-deprecated

Rule: oj-html-ojattr-deprecated  Severity: major
JET component deprecated attributes should not be used.

Alternatively, if you know the message ID, you can obtain the rule name and rule description:

ojaf --help JET-0080

Rule: oj-html-ojattr-deprecated  Severity: major
JET component deprecated attributes should not be used.

Note:

To get rule help, you must run ojaf --help from the directory that contains your application's oraclejafconfig.json file. By default this is the root of the application.

For more information about enabling rule names to display in audit results, see Display Rule Names with Audit Messages.

Toggle the Default Format of Audit Messages

Use the optional Oracle JAF configuration file property format to specify the default display format for audit messages.

You can set the JAF configuration file format property to prose or to line to toggle the default presentation of audit messages between these two styles. The prose format displays audit messages in a report style, while the line format flattens out audit messages into single lines.

You can also customize the presentation for audit messages in either style by applying custom templates that you create, as describe in Customize the Presentation of the Audit Messages.

To toggle the default display style:

To enable the display of audit messages in the report presentation, edit the oraclejafconfig.json file format property.
```
"format" : "prose"
```
To enable the display of audit messages as single lines, edit the oraclejafconfig.json file format property.
```
"format" : "line"
```
Note that for certain environments, like Microsoft Visual Studio Code, line format supports hyperlinks on the file paths displayed within Oracle JAF audit messages.

Display Rule Names with Audit Messages

You can enable Oracle JAF to append the corresponding rule name to reported audit messages and you can use the rule name to return a description of the rule.

If the JAF configuration file format property is set to prose (the default), the rule name displays with the audit message. The rule name will be appended to the prose output after the message ID:

[71, 41]  <oj-list-view> attribute 'selection' is deprecated! 
Use selected attribute instead. [JET-0080 : oj-html-ojattr-deprecated]

With the rule name, you can obtain a description of the rule by using ojaf --help.

ojaf --help oj-html-ojattr-deprecated

Rule: oj-html-ojattr-deprecated  Severity: major
JET component deprecated attributes should not be used.

Alternatively, if you know the message ID, you can view the rule name with the rule description:

ojaf --help JET-0080

Rule: oj-html-ojattr-deprecated  Severity: major
JET component deprecated attributes should not be used.

Note:

To get rule help, you must run ojaf --help from the directory that contains your application's oraclejafconfig.json file. By default this is the root of the application.

To configure rule names to display with audit messages:

To enable support for appending rule names, edit the oraclejafconfig.json file format property to ensure that either prose has been specified or that the property has been omitted (which specifies prose output is the default).
```
"format" : "prose"
```
Note that if the configuration file output format is set to json, the rule name is always included in the output, and configuration options are not required. For more information, see Output Audit Messages in JSON Format.
To enable appending the rule name for a specific rule, edit the oraclejafconfig.json file options.ruleName property.
```
"options" : {
              "ruleName" : true,
              ...
            }
```
Alternatively, to enable appending the rule name for all rules, edit the oraclejafconfig.json file options.verbose property to enable verbose output mode.
```
"options" : {
              "verbose" : true,
              ...
            }
```
You can also enable verbose output each time your run the audit from the command line.
```
ojaf -e ...
```

Customize the Presentation of the Audit Messages

Use the optional Oracle JAF configuration file properties proseFormat and lineFormat to define templates to redefine the presentation of reported audit issues.

If the JAF configuration file format property is set to prose or to line, you can use the respective properties proseFormat and lineFormat to define a custom presentation template to format the displayed audit issues.

A prose-formatted audit message begins with the text Audit for.

Description of the illustration audit_lineformat.png

Here is a line-formatted audit message with different template.

Description of the illustration audit_proseformat.png

If you omit proseFormat, Oracle JAF uses the default template, "%pos1 %s : %m", which displays as follows:

Description of the illustration audit_proseformat_default.png

Specify the template for the properties as a string, containing any of the following tokens in any order. JAF replaces the tokens in the audit message output at runtime.

Audit Message Tokens	Replacement Value
%l	The line number only.
%c	The column number only.
%pos1	The comma-separated line and column number with square brackets. For example: `[46, 25]`
%pos2	The comma-separated line and column number with parens. For example: `(46, 25)`
%s	The severity level of the processed rule.
%m	The entire audit issue message.
%mid	The full audit message ID. For example, `JET-1234`
%p	The prefix of the rule set. For example, `JET` for the built-in JET rule set.
%n	The audit message number only. For example, `1234`
%r	The rule name.
%f	The file path.

To define a custom presentation template:

To enable support for customizing the presentation of audit message, edit the oraclejafconfig.json file format property to ensure that either prose or line has been specified. Note that if the format property has been omitted, the default specifies prose output.
```
"format" : "prose"
```
or
```
"format" : "line"
```
If the output format has been specified as prose, edit the oraclejafconfig.json file proseFormat property to define a custom presentation template to format displayed audit issues. The value of proseFormat is a string containing tokens shown in the table above.
```
"proseFormat" : "%pos1 %s : %m [%mid]"
```
In the sample, the tokens specify the first four replacement values for the audit message: including the line/column number format followed by the processed rule's severity level, and then a colon followed by the audit issue message and the full audit message ID within square brackets.
Output based on this template looks similar to this audit message:
```
** Audit for D:/myapp/public_html/content/demo.html
[46,25] blocker : <oj-bind-if> 'test' attribute : read-only '[[...]]' expression expected [JET-0163]
```
If the output format has been specified as line, edit the oraclejafconfig.json file lineFormat property to define a custom presentation template to format displayed audit issues. The value of lineFormat is a string containing tokens shown in the table above.
```
"lineFormat" : "%s  :  %m [%mid]\n → %f: %l:%c"
```
In the sample, the tokens specify the first four replacement values for the audit message: including the processed rule's severity level followed by the audit issue message, a line break, and then an right arrow character, the file path, and then the line and column numbers.
Output based on this template looks similar to this audit message:
```
blocker : <oj-bind-if> 'test' attribute : read-only '[[...]]' expression expected [JET-0163]
-> D:/myapp/public_html/content/demo.html: 46, 25
```

Format a Title for the Audit Report

You can use the optional Oracle JAF configuration title property create a title for audit reports.

If the JAF configuration file format property is set to prose (the default), you can use the title property to format a title header to display with the audit output. The title definition may include tokens to insert values, such as the Oracle JET version into the title.

Audit Title Tokens	Replacement Values
$jafdate	The current date, like "Friday Feb 14, 2020".
$jaftime	The current time, like "8:05am EDT".
$jetver	The Oracle JET version, like "8.1.0".
%jafver	The Oracle JAF version, like "2.4.0".
%jafconfig	The file path for the Oracle JAF configuration file used in the audit, like "D:\myproject\oraclejafconfig.json".

To configure a title:

To format a title for audit reports, edit the oraclejafconfig.json file format property to ensure that either prose has been specified or that the property has been omitted (which specifies prose output is the default).
```
"format" : "prose"
```
Note that if the configuration file output format is set to json, the report title is also included in the output. For more information, see Output Audit Messages in JSON Format.

To format the report title, edit the oraclejafconfig.json file title property. Macros are available to insert values such as the Oracle JET version, or date and time into the title strings.

"title" : [
           "+-----------------------------------------------------------+",
           "|                  Some Title for the Audit                 |",
           "+-----------------------------------------------------------+",
           "JET : $jetver  ($jafdate, $jaftime)\n"
          ]

This sample specifies the audit report will exclude the message with ID JET-3020 and exclude the set of messages with IDs like JET-2000, JET-2010, JET-2020 and so on.

+-----------------------------------------------------------+
|                   Some Title for the Audit                |
+-----------------------------------------------------------+
JET : 8.1.0  (Friday Feb 14, 2020, 8:05am EDT)

Output Audit Messages in JSON Format

Use the optional Oracle JAF configuration file property format to specify that the output format of the audit to be a JSON document. You can then process the JSON to create any desired output.

If the JAF configuration file property format is set to json, you can generate the output of the audit in JSON format. You can direct JAF to output the JSON document to the desired directory by defining the JAF configuration property outPath.

The output of the JSON is structured as follows.

JSON Section	Description
reported	An array object for each audited file containing an array of reported issue objects.
summary	An object containing summary data such as the number of issues found or the number of files processed, for example.
run	An object containing run data such as run date/time and JET version number.
descriptions	An optional object containing rule descriptions for the issues in the reported section. Must be configured by using the JAF configuration property ruleDescriptions, as described below.
fileset	An optional object containing the file set processed by the audit. Must be configured by using the JAF configuration property addFileList, as described below.

This is an abbreviated sample of typical JSON output for reported issue.

{
  "reported": [
                {
                  "file": "/tests/rules/oj-html-binding-attr/binding-foreach_FAIL_2.html",
                  "issues": [
                              {
                                "severity": "minor",
                                "msg": "Use of attribute 'id' is meaningless for binding element <oj-bind-for-each>",
                                "msgId": "JET-0015",
                                "position": {
                                              "row": 14,
                                              "col": 12,
                                              "start": 467,
                                              "end": 482
                                            },
                                "rule": "oj-html-binding-attr"
                              }
                           ]
                },
                . . .
              ],
  "summary":  {
                "severities": {
                               "blocker": 0,
                               "severity": 0,
                               "major": 0,
                               "minor": 0,
                               "info": 1
                             },
                "issues": 1,
                "issueFiles": 1,
                "errorFiles": 0,
                "parseErrors": 0,
                "errors": 0,
                "warnings": 1,
                "asserts": 0,
                "files": 1,
                "urls": 0,
                "rulesActive": 64,
                "rulesFired": 41,
                "hooksFired": 15
              },
  "run": {
           "date": "Tues, 14 April 2020 15:52:39 GMT",
           "jetversion": "8.1.0",
           "title" : "Testing",
           "config": "d:\\runAudit\\testing_config.json"
         }
}

To specify JSON as the output format:

To format a title for audit reports, edit the oraclejafconfig.json file format property to specify json.
```
"format" : "json"
```
Optionally, to include custom rule descriptions in the JSON output, edit the oraclejafconfig.json file ruleDescription property and set the value to short or to long.
```
"descriptions": {
      "JET-0290": {
                    "long": "...a rule long description.",
                  },
      "JET-3172": {
                    "long": "...a rule long description.",
                  },
      . . .
      }
```
This property takes the following values : none, all, short, or long and causes an additional descriptions section to appear in the output JSON document.

Optionally, to format a title to include in the JSON document, edit the oraclejafconfig.json file title property.

"title" : [
           "+-----------------------------------------------------------+",
           "|                  Some Title for the Audit                 |",
           "+-----------------------------------------------------------+",
           "JET : $jetver  ($jafdate, $jaftime)\n"
          ]

Macros are available to insert values such as the Oracle JET version, or date and time into the title strings. For more information, see Format a Title for the Audit Report.

Optionally, to specify the output path for the JSON document, edit the oraclejafconfig.json file outPath property.
```
"outPath" : "myfolder/myreport.json"
```
Note that alternatively you can omit outPath and redirect the output to a file. This will also redirect other information that was written to stdout by JAF.
Optionally, to append the file set list to the JSON document, edit the oraclejafconfig.json file addFileList property.
```
"addFileList" : true
```
This optional property causes an additional JSON section fileset to appear in the JSON document as an array of full path name strings. This can be useful when creating custom reports from the output JSON, since it allows access to the full file set that was audited.