Rule architecture changes - v4

[tombrunet]

For those of you that have been watching PRs over the last couple of weeks, you may have seen a fair amount of changes. The end result is some fairly major changes that you may not notice. A large chunk of the work is to make it easier to maintain the rules while not making any major changes to the rule logic itself nor how the engine works. However, we're also making it possible to run the tools off of open CDN's, rather than relying on our servers. The net is, if you're just using the tools, you may not even notice that we did anything. Updates to the tools to take advantage of all of this should be coming out in the next week or so. I'll try to outline the major bits here:

1. Rule information now in one file

The original architecture of the rules had separate files for help, message, and ruleset mappings, and the logic. This was frustrating to edit since changes would impact multiple files. It also caused conflicts when multiple people were working on separate rules. To fix that, all of the information has been reorganized so that each rule is its own file. For example HAAC_Aria_ImgAlt. You'll now find messages, help, and ACT mapping paired with the rule logic all in one place. Except for one exception that we may resolve later, files contain only one rule, so it should be easier to find them. With this reorg, we also fixed the help mappings so that, in the future, we may be able to provide more specific help using reasonId's.

2. The accessibility-checker-engine now has it's own NPM repository.

You'll now find our JavaScript engine at https://www.npmjs.com/package/accessibility-checker-engine. This is the engine that does all of the magic in our tools.

So how do the archives in the tools map to the versions in NPM? See https://cdn.jsdelivr.net/npm/accessibility-checker-engine@next/archives.json. In archives.json, you'll find an id, name, version and other fields. You should be able to use the version field and get the matching js file. For example, https://cdn.jsdelivr.net/npm/accessibility-checker-engine@3.1.24/ace.js

3. Help files

When we moved to Carbon, we wanted to maintain our help files in Markdown, so we ended up using Gatsby as a rendering engine. Gatsby is not optimal for this purpose, and we have to jump through various hoops to get it to render in the browser extension and such. Instead, we moved to a Web Component based framework that allows us to use Markdown, load individual HTML files with no separate build, and add all of the nice tokenization and contextual help that we like. You'll find the help files in this directory. So, with the rule results, you can now see the same contextual help that you see in the extension. For example, a rule that triggered may have this help

To do this yourself, it follows a format like: https://unpkg.com/accessibility-checker-engine@{archive Version}/help/en-US/{helpId from the rule help mapping}.html#{encodeURIComponent(JSON.stringify(minIssue))} where minIssue is:

{ message, snippet, value, reasonId, ruleId, msgArgs }

4. Rule listing

The design of this will change, but we have a fairly complete rule listing again:
https://unpkg.com/accessibility-checker-engine@3.1.25-rc.1/help/rules.html

You'll find a switcher by policy across the top, and then a list, broken down by checkpoint, rule, and reason codes.

ACT

You’ll also start to see some information about how our rules map to the ACT rules in an act field of the rule definitions. Our implementation report can be found at https://act-rules.github.io/implementation/equal-access-accessibility-checker . We’re working to include that report with the release archives, so that it will be easier to map the engine to the results at the time that the release occurred.