perf-checks

A headless framework for nested checks on Scripture content, mainly in PERF.

Checks are performed using an instance of the perf-checks class. A checks specification is provided when the class is instantiated. Scripture content (typically PERF) can then be passed to the instance, via method calls. Those methods return a JSON report. That report can be localised and presented via any GUI.

Overview

Anatomy of a check

The following information is required for each check:

• a short name that serves as an id to identify the check
• a description that can be localised and presented to the end user
• a level (one of info, trivial, minor, major, critical and fatal) at which processing will be halted
• a source type (typically perf, but usfm, usx and usj may be useful for 'can we even parse this?'-type checks)
• the code that performs the check

Checking code

Checks are functions written in Javascript and should take as arguments

• the content to be checked
• the format of that content

Checking functions should return a JSON report including

• pass/fail flag
• list of issues, with location, issue code and, optionally, data related to the issue that may be shown to the user

In general, each checking function should test one thing. This helps with reusability and with code testing.

Check groups

Checks may be grouped. Each group may be given a name and a description.

Checking hierarchy

Both individual checks and check groups may have child checks and/or check groups. perf-checks runs the top-level checks before running children, appending any issues to the report as it goes.

Processing ends in all cases on the first fatal issue. In other cases, all checks at the top level will be run. Child checks will be run, recursively, if no issue with a level at least equal to that of the perf-checks instance has been encountered.

For example, if the perf-checks instance level is major, child checks will be run if no major or critical issues are encountered at the current level. If the perf-checks instance level is minor, a minor, major or critical issue will prevent execution of child processes.

The checks hierarchy is a tree, so the processing of child checks depends on the state of the parent of that check. For example, depending on the checks specification, child checks for chapter/verse progression might be skipped, due to an issue in the most basic chapter/verse checks, but child checks for punctuation could still execute if no serious issues were found in the parent of those checks.

Child checks attached to a checks group will only run if no issue for any of the checks in the group reaches the level of the ``perf-checks` instance.

Localisation

The reports use ids and issue codes. A library of helper functions can convert these reports into somewhat readable English. For issues that return issue-specific data, the helper functions use a placeholder mechanism to construct that English. These helper functions may be localised for other languages, which may include reworking the placeholders to respect localised language word order.