daisy / ace Goto Github PK

Installing globally [email protected] installs the ace command but not ace-http.

To be investigated. Some leads:

• in any case, add a node shebang at the top of the CLI implementation
• make the file executable? (I don't think this is needed, to be verified)
• make sure multiple binaries are supported (AFAIK it is)

Ace should accept as input one or more standalone HTML files. It should produce the same kind of report as it does for a full EPUB, but with the EPUB-specific rules filtered out.

Is https://github.com/daisy/ace-core/milestones still current, or is there a more updated location for this information?

Not sure what to make of this:

info:    - xhtml/p10.xhtml
verbose: Converting aXe results to ace for xhtml/p10.xhtml
info:    - 2 issues found
debug:   Error when running nightmare: {}
error:   Unexpected error: Failed to check HTML content
debug:   Error: Failed to check HTML content
    at nightmare.goto.inject.inject.inject.inject.wait.axe.then.catch (C:\Users\mattg_000\AppData\Roaming\npm\node_modules\ace-core\dist\checker\checker-nightmare.js:86:13)
    at <anonymous>
    at process._tickCallback (internal/process/next_tick.js:188:7)

I was trying to validate the cc-shared-culture book from the epub3 samples repo, which previously worked fine. I assume it's coming from p20.xhtml, but epubcheck doesn't report any problems in any case.

I don't see anything unique about those files that aren't in other epubs that I can validate.

If possible, add more descriptive explanations on the command line for when a file fails to pass through the Ace analysis. About half of the ePubs I have been testing fail with the error

Unexpected error: TypeError: Cannot read property 'tocHTML' of undefined

I will continue to diagnose this error as much as I can, but so far have few leads to go on. I originally thought this was an issue in ePubs with an NCX nav file, but some NCX-based ePubs pass through Ace fine.

When I tried the following report
ace -o Anesthesia 9780323508902_epub.epub
A Anesthesia directory was created which I was expecting but at the same directory level there was an IMAGES folder created
-rw-r--r--@ 1 charlesl domain users 220724885 Aug 21 13:00 9780323508902_epub.epub
drwxr-xr-x 8 charlesl domain users 272 Aug 21 13:53 Anesthesia
drwxr-xr-x 44 charlesl domain users 1496 Aug 21 13:53 IMAGES

2014-B-032:Elsevier charlesl$ cd Anesthesia/
2014-B-032:Anesthesia charlesl$ ls -l
total 5472
drwxr-xr-x 4 charlesl domain users 136 Aug 21 13:53 IMAGES
-rw-r--r-- 1 charlesl domain users 2785868 Aug 21 13:53 ace.json
drwxr-xr-x 104 charlesl domain users 3536 Aug 21 13:53 data
drwxr-xr-x 4 charlesl domain users 136 Aug 21 13:53 js
-rw-r--r-- 1 charlesl domain users 8991 Aug 21 13:53 report.html

BTW there was no IMAGES directory under data like I saw in another report, so I am confused on where these files are going

I wasn't expecting the IMAGES folder outside of the output folder I specified. Other EPUBs I have tested with didn't have this behavior.

in terms of tailoring the wcag assessment criteria, reporting the following in the data section will really help:

• videos - file, id if present, controls enabled, tracks
• audio - same as video
• forms - file and id
• scripts - file

The next level down would be to know about the presence of:

• iframe
• embed
• object
• canvas
• map

I expect those will be in small enough numbers that it won't bloat the report, and are useful to point out for a few SCs.

A report of whether mathml is present would be useful for metadata generation, but I don't want a listing of every equation. Same for whether pagebreaks/pagelist were found.

The other manual difficulty will be in determining compliance to 1.3.1 (info and relationships), but I don't think we need anything for this. It requires someone to go over the markup.

That's everything I've been able to think of for now.

We could add options to:

• override existing files or not
• clean the entire output directory, or resources sub directories

• Winston is probably a good option.
• Add some logging statements throughout the code

Right now the resolved module dependency tree is described in both .yarn-lock (when building with Yarn) and .package-lock (when building with npm).

Can both be synchronized? How to make sure these are kept up-to-date?

See GitHub's doc:

• What is a code of conduct?
• Writing contributing guidelines

Possibly a CLA too.

• compatible with JSON-LD
• see if we can use EARL (as used in the ACT TF)

Keeping the log file in the module creates permissions issues in some setups.

We should:

• place the log file somewhere in the user's config directory
• allow to customize the log file location via configuration

It would be easier to visually compare the various outlines if they could be rendered side-by-side.

This can be implemented in the report's CSS.

Some defensive logic needs to be added to make sure that files are not created outside the output directory (to make sure that a maliciously forged EPUB can do no harm).

• Extract basic EPUB metadata (title, author, version)
• Extract a11y-specific metadata
• Add metadata to the report

A feature request for later, but it would nice to be able to run ace on an unzipped directory.

From @larsvoigt

It w/b nice to have an option for Ace to report a list of all the rules that can be checked.

The table displaying the violations in the HTML report could probably be improved here and there, for instance:

• the _Impact _ column's size can be reduced, the label could use an icon and color code
• in the Target column, we need to specify when the selectors are a CSS selector or a CFI selectors
• the Description and KB Link columns could be merged to save horizontal space
• the Engine info could be merged in the Rule table

• list the images appearing in the EPUB
• add some contextual info on alternative text + description
• present the result in the output report

Reported by Nick Williamson:

ace --version

produced (with the directory path before npm replaced by an ellipsis)

...\npm\node_modules\ace-core\dist\report\repor```
t-builders.js:89
 ) {
 ^
SyntaxError: Unexpected token )
  at createScript (vm.js:56:10)
  at Object.runInThisContext (vm.js:97:10)
  at Module._compile (module.js:542:28)
  at Object.Module._extensions..js (module.js:579:10)
  at Module.load (module.js:487:32)
  at tryModuleLoad (module.js:446:12)
  at Function.Module._load (module.js:438:3)
  at Module.require (module.js:497:17)
  at require (internal/module.js:20:19)
...\npm\node_modules
\ace-core\dist\report\axe2ace.js:5:18)

Right now, Ace summarizes what's present/missing regarding the accessibility metadata in the package document. There are two ways to improve upon this:

• include what's in the content documents (perhaps as a part of content analysis -- see this example of embedded video metadata: https://idpf.github.io/a11y-guidelines/content/meta/schema.org.html#meta010-ex02)
• suggest values for missing metadata

Ace -v: 0.3.0
Node -v: 8.6.0
NPM -v: 5.3.0

Running Ace 0.3.0 on books previously validated by 0.2.0 gives the following error:

BOML105215:~ games$ ace -o /Users/games/Documents/daisy-ace /Users/games/Downloads/9781351946841.epub
info: Processing /Users/games/Downloads/9781351946841.epub
events.js:182
throw er; // Unhandled 'error' event
^
Error: EACCES: permission denied, open '/usr/local/lib/node_modules/ace-core/dist/ace.log'

When I navigate to the directory specified, there is no ace.log to check.

Running the command with sudo and --verbose completes but does not generate a report. Instead the following error appears:

info: Saving JSON report
info: Saving HTML report
error: Unexpected error: this.json.data.images.forEach is not a function
debug: TypeError: this.json.data.images.forEach is not a function
at fs.pathExists.then.then (/usr/local/lib/node_modules/ace-core/dist/report/report.js:88:35)
at <anonymous>

No report is output at the specified directory. log file attached.
ace.log

When reporting the metadata at the top of the report, I'd love to have it notate missing required items. I ran it on a test file, and (of course) it does not have any of the accessibility metadata to report:

  },
  "dct:date": "8/7/2017, 11:52:29 AM",
  "dct:title": "ACE Report",
  "dct:description": "Accessibility Checker Report",
  "earl:testSubject": {
    "url": "/Users/nbrown1/Downloads/hack-epub.epub",
    "dct:title": "Hack Education: Top Ed-Tech Trends of 2016",
    "dct:identifier": "urn:isbn:hack-education",
    "metadata": {
      "dc:title": "Hack Education: Top Ed-Tech Trends of 2016",
      "dc:creator": "Audrey Watters",
      "dc:language": "en",
      "dc:identifier": "urn:isbn:hack-education",
      "dcterms:modified": "2016-12-28T21:26:35Z"
    }

I would like to see it report that these items (and others?) are missing, or empty:
accessMode
accessibilityFeature
accessibilityHazard
accessibilitySummary
accessModeSufficient
accessibilityAPI
accessibilityControl
a11y:certifiedBy

The javascript source uses several ES6 constructs that may be incompatible with previous versions of Node.

We should transpile the code at build time to make it more portable.

• Write a Travis config
• Enable Travis CI

Some books cause the processing to file with a file already exists error. For example:

Unexpected error: Error: EEXIST: file already exists, mkdir '/Users/charlesl/Documents/Consulting/Macmillan/Updated Files/worldS/file!var!folders!fx!7s517m5s7k5gf65z4gqvt6040000gp!T!tmp-13177VFBRbslHsE6L!OEBPS!xhtml!mck_978145769'

Hi,
I have got some errors if I try to generate an ace report of this ebook samplebook_v1.1_epub3_04142014.zip.

Error: ENOENT: no such file or directory, lstat '/tmp/tmp-14428ie8o0bumJkuI/EPUB/images/logo.jpg'
Error: ENOENT: no such file or directory, lstat '/tmp/tmp-14428ie8o0bumJkuI/EPUB/images/map-daisy-long-small.jpg'
Error: ENOENT: no such file or directory, lstat '/tmp/tmp-14428ie8o0bumJkuI/EPUB/images/map.jpg'
Error: ENOENT: no such file or directory, lstat '/tmp/tmp-14428ie8o0bumJkuI/EPUB/images/soc-small.jpg'
Error: ENOENT: no such file or directory, lstat '/tmp/tmp-14428ie8o0bumJkuI/EPUB/images/barchart-small.jpg'
etc ...

And also I got an error for this file pg11-images.zip

Unexpected error: TypeError: Cannot read property 'tocHTML' of undefined

Thanks a lot Lars

Updating Ace with the npm update command doesn't work:

npm update -g ace-core

This seems to be an ongoing issue with NPM (see npm/npm#13458, npm/npm#17209, npm/npm#17975 and others

The current recommended way to update is via npm install:

npm install -g ace-core

Was reported by Nick, Matt, and Gary.
I could reproduce, will be fixed before Beta 1.

• extract the headings outline
• extract the HTML outline
• extract the Nav Doc toc outline
• add the outlines to the report

From @mattgarrish

Is there no way to get line and column? Without help, those locators might mentally tax a lot of people

The checks are run against the DOM, so getting line and colum info looks difficult. We can still try harder to see if the info can be retrieved or computed somehow.

Currently violations have an "impact" information, which comes from aXe and can be either "minor", "moderate", "serious", or "critical".

Should we keep this info as-is? Its meaning would at least need to be described (in user guide, but possibly also in a short help text in the report).

title + identifier just need to appear once

"earl:testSubject": {
"url": "/Users/marisa/dev/sample-content/epubs/moby-dick-mo-20120214.epub",
"dct:title": "Moby-Dick",
"dct:identifier": "urn:isbn:9780316000000",
"metadata": {
"dc:title": "Moby-Dick",
"dc:creator": "Herman Melville",
"dc:identifier": "urn:isbn:9780316000000",

The HTML report can be pretty big. The violation table is already paginated, but more could be done to improve the navigability and readability.

For instance:

• add a ToC
• make sections collapsible

• Add a testing framework
• Implement some initial tests

In a 0.20 report a link to
https://daisy.github.io/a11y-kb/docs/scripting/aria.html
is invalid.
Looks like it has been renamed to
https://daisy.github.io/a11y-kb/docs/script/aria.html

CFI and CSS selectors are reversed in the JSON report (the CFI selector is associated to the member named "css" and vice versa).

Some rules have multiple possible infractions listed in the description. For example, image-alt has six possible reasons why the image was flagged.

• Element does not have an alt attribute
• aria-label attribute does not exist or is empty
• aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty or not visible
• Element has no title attribute or the title attribute is empty
• Element's default semantics were not overridden with role="presentation"
• Element's default semantics were not overridden with role="none"

Having the Ace tool detect the specific cause of the error and display only that in the description, rather than the 6 possible causes, would go a long way towards being able to hand the Ace report off to a client as their instructions to fix their file.

Chrome can now be run headless. We can try some experiments to replace NightmareJS by e.g. Chromeless or a similar library.

The KB link in the Ace report for the issue "bypass" links to

https://daisy.github.io/a11y-kb/undefined

Support EPUB 2.0.1 should not be terribly costly. It requires:

• minor tweaks to the OPF parsing logic
• adding a way to retrieve the NCX and convert it to an outline

• add progress report
• add colors
• improve the CLI output of check results

It would have been nice to know which role was in error.
In this case the role was "decorative" instead of "presentation"

but it took a bit of detective work to find out that, would have been nice to have that called out in the report where it said invalid aria role (why not just say what it found)

From @clapierre

I am getting the following error running ACE

info:    Processing Art_&_Language_International.epub
info:    Parsing EPUB
info:    Analyzing accessibility metadata
info:    Checking package...
error:   Unexpected error: title.trim is not a function

Following a suggestion from @clapierre, the HTML report could include a summary incliding:

• the number of issues, and detailed number per severity
• the number of issues per rule-set (e.g. WCAG A, WCAG AA, EPUB-specific).