OpenACR CLI

Introduction

The OpenACR command-line interface (CLI) is built in typescript. It takes an OpenACR and WCAG/508 (and other) criteria as YAML files as input and validates them using the OpenACR defined schemas and OpenACR catalog.

Requirements

You need the latest version of Node and NPM installed. There are multiple ways to download NPM but recommendations are to use NPM.

Install

Installing CLI

From version v0.3.6 onwards, the CLI can be installed from https://www.npmjs.com/package/@openacr/openacr using the command without needing the source and all dependencies:

npm install @openacr/openacr

Then you can use the openacr executable version to run the sames commands as listed below.

Installing source

Clone the GitHub repository and cd into that directory.

git clone https://github.com/GSA/openacr.git
cd openacr

Then install the dependencies with the following NPM command:

npm install

Source

Main application code is in the src directory.

Commands and examples

The OpenACR CLI can be executed without compiling using ts-node. Currently, the CLI can validate entered YAML and output it in markdown.

Help

Use --help to reveal the CLI instructions.

> npx ts-node src/openacr.ts --help
openacr.ts <command>

Commands:
  openacr.ts validate  Validate OpenACR content

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

> npx ts-node src/openacr.ts validate --help
openacr.ts validate

Validate OpenACR content

Options:
      --help         Show help                                         [boolean]
      --version      Show version number                               [boolean]
  -f, --file         Content filename                        [string] [required]
  -c, --catalogFile  Catalog filename                                   [string]
> npx ts-node src/openacr.ts output --help
openacr.ts output

Output OpenACR in markdown

Options:
      --help         Show help                                         [boolean]
      --version      Show version number                               [boolean]
  -f, --file         Content filename                        [string] [required]
  -c, --catalogFile  Catalog filename                                   [string]
  -o, --outputFile   Output filename                                    [string]
  -t, --templateFile  Handlebar template filename                       [string]

Examples

You can test the CLI with the following example commands:

# Only validate
npx ts-node src/openacr.ts validate -f tests/examples/valid.yaml # Output: Valid!
npx ts-node src/openacr.ts validate -f tests/examples/invalid-basic.yaml # Output: Invalid: ...
npx ts-node src/openacr.ts validate -f tests/examples/valid.yaml -c catalog/2.4-edition-wcag-2.0-508-en.yaml # Output: Valid!
npx ts-node src/openacr.ts validate -f openacr/drupal-9.yaml -c catalog/2.4-edition-wcag-2.1-508-en.yaml # Output: Valid!
npx ts-node src/openacr.ts validate -f tests/examples/invalid-criteria.yaml -c catalog/2.4-edition-wcag-2.0-508-en.yaml # Output: Invalid: ...
npx ts-node src/openacr.ts validate -f tests/examples/invalid-components.yaml -c catalog/2.4-edition-wcag-2.0-508-en.yaml # Output: Invalid: ...
npx ts-node src/openacr.ts validate -f tests/examples/invalid-components-criteria.yaml -c catalog/2.4-edition-wcag-2.0-508-en.yaml # Output: Invalid: ...
npx ts-node src/openacr.ts validate -f tests/examples/valid.yaml -c tests/examples/catalog-missing-components.yaml # Output: Valid!
npx ts-node src/openacr.ts validate -f tests/examples/valid.yaml -c tests/examples/catalog-missing-chapters.yaml # Output: Valid!
npx ts-node src/openacr.ts validate -f tests/examples/valid.yaml -c tests/examples/catalog-different-components.yaml # Output: Invalid: ...
# Validate and Output
npx ts-node src/openacr.ts output -f tests/examples/valid.yaml -c catalog/2.4-edition-wcag-2.0-508-en.yaml -o tests/examples/valid.markdown # Output: Valid ...
npx ts-node src/openacr.ts output -f openacr/drupal-9.yaml -c catalog/2.4-edition-wcag-2.1-508-en.yaml -o openacr/drupal-9.markdown # Output: Valid ...
# Use a different handlerbar template
npx ts-node src/openacr.ts output -f openacr/drupal-9.yaml -c catalog/2.4-edition-wcag-2.1-508-en.yaml -o openacr/drupal-9-simple.html -t templates/openacr-simple-html-0.1.0.handlebars # Output: Valid ...

Schemas

Located in the 'schema' folder:

openacr-0.1.0.json the OpenACR schema.
openacr-catalog-0.1.0.json the OpenACR catalog schema. Used to create catalogs defining the criteria and components for WCAG 2.0/2.1, 508, EU, and so on.

Catalogs

The catalogs are in catalog. They are generated using the librarian utility (see Librarian docs for more details).

The catalogs will be validated against a defined schema (openacr-catalog-0.1.0.json) when running the commands.

Catalogs:

2.4-edition-wcag-2.0-508-en.yaml the 508 catalog.

In the validate command, if the catalog file is missing the validate command will only check that the YAML file meets the basic schema defined.

Output

The output command can take an optional file path (default is output/openacr.markdown) and converts the validated YAML file to markdown (default) or HTML.

The command uses handlebars and the default templates defined in templates to render the output:

openacr-markdown-0.1.0.handlebars is the markdown template.
openacr-html-0.1.0.handlebars is the HTML template.

Examples

We checked in an examples of the markdown and HTML output in tests/examples and openacr. To regenerate the examples run the following commands and commit the changes:

npm run generate-example-output
npm run generate-drupal-output
npm run generate-example-html
npm run generate-drupal-html
npm run generate-drupal-simple
npm run generate-drupal-10-html
npm run generate-drupal-10-simple

We also have a GitHub action called 'Drupal 9 OpenACRs output' that will generate the markdown and HTML versions of the Drupal 9 OpenACRs. It is run on pull requests, and the output can be downloaded to double-check it is matching expectations.

The tests also generates output that is stored in the output directory but is not tracked by git.

USWDS Design System and stylesheets

The HTML output comes with and uses styles from the U.S. Web Design System (USWDS).

The output also includes two stylesheets that provide additional styling for the OpenACRs:

openacr.css has customization on top of the USWDS design system.
custom.css provided to add any additional customizations.

Use your own handlebar template

To use your own handlebar template the output command can take an optional template file path. We recommend copying the template openacr-simple-html-0.1.0.handlebars and modifying it with your CSS and HTML adjustments but keeping the majority of the structure and custom handlebar functions intact, so you get the ACR output that has all the details. The simple template includes CSS but no USWDS stylings but does rely on USWDS classes to keep the handlebar functions simple for now.

OpenACRs

Current example OpenACRs that are tracked in this repository are in the openacr directory. The directory includes a data table representation of all the OpenACRs with the ability to search them.

OpenACRs:

drupal-10-15.yaml: Drupal 10 OpenACR.
drupal-9.yaml: Drupal 9 OpenACR.
govready-0.9.yaml
Moodle-3.yaml
NVDA-2018.yaml
Plone-5.yaml

To regenerate the above OpenACR markdown and HTML reports run the following commands:

npx ts-node src/openacr.ts output -f openacr/drupal-10-15.yaml -c catalog/2.4-edition-wcag-2.1-en.yaml -o openacr/drupal-10-15.html
npx ts-node src/openacr.ts output -f openacr/drupal-9.yaml -c catalog/2.4-edition-wcag-2.1-508-en.yaml -o openacr/drupal-9.html
npx ts-node src/openacr.ts output -f openacr/drupal-9.yaml -c catalog/2.4-edition-wcag-2.1-508-en.yaml -o openacr/drupal-9.markdown
npx ts-node src/openacr.ts output -f openacr/govready-0.9.yaml -c catalog/2.4-edition-wcag-2.0-508-en.yaml -o openacr/govready-0.9.html
npx ts-node src/openacr.ts output -f openacr/govready-0.9.yaml -c catalog/2.4-edition-wcag-2.0-508-en.yaml -o openacr/govready-0.9.markdown
npx ts-node src/openacr.ts output -f openacr/Moodle-3.yaml -c catalog/2.4-edition-wcag-2.0-508-en.yaml -o openacr/Moodle-3.html
npx ts-node src/openacr.ts output -f openacr/Moodle-3.yaml -c catalog/2.4-edition-wcag-2.0-508-en.yaml -o openacr/Moodle-3.markdown
npx ts-node src/openacr.ts output -f openacr/NVDA-2018.yaml -c catalog/2.4-edition-wcag-2.0-508-en.yaml -o openacr/NVDA-2018.html
npx ts-node src/openacr.ts output -f openacr/NVDA-2018.yaml -c catalog/2.4-edition-wcag-2.0-508-en.yaml -o openacr/NVDA-2018.markdown
npx ts-node src/openacr.ts output -f openacr/Plone-5.yaml -c catalog/2.4-edition-wcag-2.0-508-en.yaml -o openacr/Plone-5.html
npx ts-node src/openacr.ts output -f openacr/Plone-5.yaml -c catalog/2.4-edition-wcag-2.0-508-en.yaml -o openacr/Plone-5.markdown

Tests

Tests can be run by executing the command:

npm test

The following files located in tests/examples are different types of versions of an OpenACR, catalog, markdown, and so on that are used for testing the application:

catalog-different-components.yaml: Has different components to test how a previous valid OpenACR is invalid and vice-versa.
catalog-missing-chapters.yaml: No chapters.
catalog-missing-components.yaml: No components.
every-example-of-keywords.yaml: Every example of terms.
invalid-basic.yaml: Very incorrect OpenACR example. Used for sanity checks.
invalid-components.yaml: Has incorrect components (E.g., includes 'none' in criteria '1.2.2').
invalid-components-criteria.yaml: Has incorrect components and criteria.
invalid-criteria.yaml: Has incorrect criteria (E.g., instead of '1.1.1' it has '100.100.100').
invalid-terms.yaml: Has incorrect terms (E.g., includes level 'does not support' in criteria '1.2.2').
valid.markdown: Is a custom output markdown file of the OpenACR after it has been validated.
valid.yaml: A valid OpenACR example (few chapters).
valid-missing-components.yaml: A valid OpenACR example with no components in criteria '1.2.2'.

Note: If there are CLI errors, the openacr-validate-cli.test.ts says tests have passed initially but after that you get the assertion error and error code 7.

Source code management

Linting

We use prettier and eslint to keep the code clean and matching common standards for typescript and javascript. The configurations are located in:

.eslintignore
.eslingrc
.prettierignore
.prettierrc.json

Caveat: since we are creating a new JSON scheme the typescript code does use 'any' for various function arguments.

pre-commit

We use pre-commit to run some checks and cleanup when you make a commit:

Remove trailing whitespace.
Fix end of file.
Adjust mixed line endings.
Remove byte order marker.
Check and fix YAML/JSON files.
Check for any large files.
Replace smart quotes with regular ones.
Run prettier.

Pre-commit is also run on pull requests and will add a commit with any changes automatically. To set it up locally install pre-commit and then run the following command in the repo folder:

pre-commit install

The configurations for pre-commit are located in the files:

.pre-commit-config.yaml
.pre-commit-search-and-replace.yaml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI.md

CLI.md

OpenACR CLI

Introduction

Requirements

Install

Installing CLI

Installing source

Source

Commands and examples

Help

Examples

Schemas

Catalogs

Output

Examples

USWDS Design System and stylesheets

Use your own handlebar template

OpenACRs

Tests

Source code management

Linting

pre-commit

Files

CLI.md

Latest commit

History

CLI.md

File metadata and controls

OpenACR CLI

Introduction

Requirements

Install

Installing CLI

Installing source

Source

Commands and examples

Help

Examples

Schemas

Catalogs

Output

Examples

USWDS Design System and stylesheets

Use your own handlebar template

OpenACRs

Tests

Source code management

Linting

pre-commit