testilo 3.3.1 → 3.5.0

package/README.md

@@ -23,6 +23,8 @@ Testilo includes some score procs, digest procs, and comparison procs. You can a
 
 ### Scoring
 
+#### Process
+
 To score Testaro reports, execute the statement `node score abc xyz`. Replace (here and below) `abc` with the base of the name of the file containing the report, or the prefix of the file name. Replace `xyz` with the base of the name of the score proc.
 
 If you replace `abc` with the entire name base, Testilo will score one report. If you replace `abc` with a prefix (such as `35k1r-`), Testilo will score all the reports whose names begin with that prefix.
@@ -37,6 +39,44 @@ This procedure has some preconditions:
 
 When Testilo scores a report, Testilo saves the scored report in the directory whose relative path is the value of the `REPORTDIR_SCORED`. The scored report file has the same name as the original. The scored report has the same content as the original, plus a new property named `score`.
 
+#### Procedures
+
+Score proc `tsp09a` implements one possible algorithm for scoring results from Testaro sample script `tsp09`.
+
+Score proc `sp10a` implements an algorithm similar to `tsp09a`, except for Testaro sample script `tp10`, which, unlike `tsp09`, includes the Tenon package.
+
+Score proc `sp10b` likewise scores results from Testaro script `tp10`, but, unlike score proc `sp10a`, bases scores on _issues_ rather than tests. Here, an issue is a case of a fault or a suspected fault of a particular kind. For example, if there are 7 informative images without text alternatives, the count of issues of that kind is 7.
+
+Because packages differ in how they identify the locations of issues, score proc `sp10b` does not try to establish whether an issue discovered by one test is the same as an issue discovered by another test. Instead, its algorithm is based on the presumption that the issues of a kind discovered by different tests are typically, but not always, subsets or supersets of one another. For example, if test A discovers 4 issues of kind X and test B discovers 6 issues of kind X, it is likely that the 4 discovered by A are also among the 6 discovered by B.
+
+Reflecting this presumption, the contribution of any issue kind to a total score is based substantially on the largest count of issues of that kind discovered by any test. The first issue of a kind is weighted more heavily than each additional issue, because the existence of any issues of a particular kind, regardless of how many, tends to create usability barriers, remediation costs, and liability risks.
+
+To a smaller extent, the total score is also affected by the counts of issues of the same kind discovered by other tests. This is because, when multiple tests discover a kind of issue:
+- we can be more confident that there really are issues of that kind.
+- the issues discovered by different tests might not fully overlap.
+- there is less excuse for allowing issues of that kind to appear.
+- the website owner is more likely to receive complaints or claims about issues of that kind.
+
+Score proc `sp10b` uses the data in `scoring/data/testGroups.json` to identify _groups_ of tests, where the tests in any group are deemed to test for the same kind of issue.
+
+Some tests have not been grouped. The proper treatment of those tests may be:
+- to treat them as a group of 1, because they alone discover issues of some kind.
+- to insert them into an existing group.
+
+As long as they are not grouped, each issue discovered by one of those tests contributes a small amount to the total score.
+
+The contribution also depends on how serious each kind of issue is deemed to be. Score proc `sp10b` assigns a weight to each test group. Weighting could be even more granular: The Axe-core package attributes a seriousness to each issue, so that two issues of the same kind can differ in seriousness. But score proc `sp10b` ignores that Axe-core rating.
+
+#### Prevention
+
+Testaro reports an error when it is unable to perform a test on a host. A score proc can take such errors into account. Score procs `sp10a`, `sp10b`, and `sp10c` presume that a failure of Testaro to perform a test is caused by the host. Thus, it treats such a failure as a case of the host preventing Testaro from performing a test. These score procs add amounts for such presumed preventions to total scores, guessing the score contributions of the tests if they had not been prevented plus an amount representing the estimated impact on accessibility of the prevention _per se_.
+
+One motivation for penalizing prevention is the assumption that measurement of success is an essential contributor to success, so preventing measurement of accessibility interferes with the achievement of accessibility.
+
+A second motivation is the presumtion that assistive technologies are unpredictable, changing, and not fundamentally different from testing technologies. Therefore, a host that prevents a testing technology is at risk for preventing an assistive technology, too, and thereby interfering with accessibility.
+
+Users who prefer to disregard prevention in scoring can create score procs that do that. It is not obvious what it means to disregard a test that could not be performed. Treating it as contributing 0 to a score arguably is not neutral, but rather rewards prevention.
+
 ### Digesting
 
 To make scored Testaro reports more useful for humans, Testilo can create digests of scored reports. A digest is an HTML document (a web page) summarizing and explaining the findings, with the scored report appended to it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testilo",
-  "version": "3.3.1",
+  "version": "3.5.0",
   "description": "Client that scores and digests Testaro reports",
   "main": "index.js",
   "scripts": {

package/procs/compare/cp1/index.html

@@ -0,0 +1,46 @@
+<!DOCTYPE HTML>
+<html lang="en-US">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="author" content="Testilo">
+    <meta name="creator" content="Testilo">
+    <meta name="publisher" name="Testilo">
+    <meta name="description" content="comparison of accessibility scores">
+    <meta name="keywords" content="accessibility a11y web testing">
+    <title>Accessibility score comparison</title>
+    <link rel="icon" href="favicon.png">
+    <link rel="stylesheet" href="style.css">
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>Accessibility score comparison</h1>
+      </header>
+      <h2>Introduction</h2>
+      <p>The table below compares __pageCount__ web pages on <a href="https://www.w3.org/WAI/fundamentals/accessibility-intro/">accessibility</a>. The page names link to the pages on the web. The scores link to digests that explain in detail how the scores were computed.</p>
+      <p>The pages were:</p>
+      <div id="summary">
+        <p>Tested by <a href="https://www.npmjs.com/package/testaro">Testaro</a></p>
+        <p>Scored by <a href="https://www.npmjs.com/package/testilo">Testilo</a> with procedure <code>sp10c</code></p>
+        <p>Digested by Testilo with procedure <code>dp10c</code></p>
+        <p>Compared by Testilo with procedure <code>cp1</code></p>
+      </div>
+      <p>The Testaro procedure performs about 600 tests on each page. Of these, 16 tests are custom tests defined by Testaro, and the others belong to packages of tests created by others.</p>
+      <p>Tests and scoring formulae are fallible and subjective. The reported faults merit investigation as potential opportunities for improved accessibility. But some may not actually harm accessibility, and some other accessibility faults may have escaped detection. Different reasonable procedures could yield different test results and different scores. Testaro and Testilo can be customized to fit different definitions and weightings of types of accessibility.</p>
+      <h2>Comparison</h2>
+      <table class="allBorder">
+        <caption>Accessibility scores of web pages</caption>
+        <thead>
+          <tr><th scope="col">Page</th><th scope="col" colspan="2">Score (lower is better)</tr>
+        </thead>
+        <tbody class="linkSmaller secondCellRight">
+          __tableBody__
+        </tbody>
+      </table>
+      <footer>
+        <p class="date">Produced <time itemprop="datePublished" datetime="__dateISO__">__dateSlash__</time></p>
+      </footer>
+    </main>
+  </body>
+</html>

package/procs/compare/cp1/index.js

@@ -0,0 +1,71 @@
+/*
+  cp1.js
+  Returns a query for an HTML page including a bar-graph table.
+*/
+
+// ########## IMPORTS
+
+// Module to keep secrets local.
+require('dotenv').config();
+// Module to access files.
+const fs = require('fs/promises');
+
+// ########## CONSTANTS
+
+const reportDirScored = process.env.REPORTDIR_SCORED || 'reports/scored';
+const query = {};
+
+// ########## FUNCTIONS
+
+// Gets data on the hosts and their scores and adds query parameter.
+const getData = async () => {
+  const reportDirAbs = `${__dirname}/../../../${reportDirScored}`;
+  const reportFileNamesAll = await fs.readdir(reportDirAbs);
+  const reportFileNamesSource = reportFileNamesAll.filter(fileName => fileName.endsWith('.json'));
+  const pageCount = reportFileNamesSource.length;
+  const bodyData = [];
+  for (const fileName of reportFileNamesSource) {
+    const fileJSON = await fs.readFile(`${reportDirAbs}/${fileName}`, 'utf8');
+    const file = JSON.parse(fileJSON);
+    const {id, script, score} = file;
+    bodyData.push({
+      id,
+      org: script.what,
+      url: script.commands.find(command => command.type === 'url').which,
+      score: score.summary.total
+    });
+  };
+  return {
+    pageCount,
+    bodyData
+  }
+};
+// Gets the maximum score.
+const getMaxScore = tableData => tableData.reduce((max, item) => Math.max(max, item.score), 0);
+// Converts report data to a table body.
+const getTableBody = async bodyData => {
+  const maxScore = getMaxScore(bodyData);
+  const rows = bodyData
+  .sort((a, b) => a.score - b.score)
+  .map(item => {
+    const {id, org, url, score} = item;
+    const pageCell = `<th scope="row"><a href="${url}">${org}</a></th>`;
+    const numCell = `<td><a href="digests/${id}.html">${score}</a></td>`;
+    const barWidth = 100 * score / maxScore;
+    const bar = `<rect height="100%" width="${barWidth}%" fill="red"></rect>`;
+    const barCell = `<td aria-hidden="true"><svg width="100%" height="0.7em">${bar}</svg></td>`;
+    const row = `<tr>${pageCell}${numCell}${barCell}</tr>`;
+    return row;
+  });
+  return rows.join('\n          ');
+};
+// Returns a query for a comparative table.
+exports.getQuery = async () => {
+  const data = await getData();
+  query.pageCount = data.pageCount;
+  query.tableBody = await getTableBody(data.bodyData);
+  const date = new Date();
+  query.dateISO = date.toISOString().slice(0, 10);
+  query.dateSlash = query.dateISO.replace(/-/g, '/');
+  return query;
+};

package/procs/digest/dp10a/index.html

@@ -16,8 +16,8 @@
     <main>
       <header>
         <h1>Accessibility test digest</h1>
-        <h2>Summary</h2>
-        <div id="summary">
+        <h2>Synopsis</h2>
+        <div id="synopsis">
           <p>Page: __org__</p>
           <p>URL: __url__</p>
           <p>Score: __totalScore__</p>

package/procs/digest/dp10b/index.html

@@ -0,0 +1,74 @@
+<!DOCTYPE HTML>
+<html lang="en-US">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="author" content="Testilo">
+    <meta name="creator" content="Testilo">
+    <meta name="publisher" name="Testilo">
+    <meta name="description" content="report of accessibility testing of a web page">
+    <meta name="keywords" content="accessibility a11y web testing">
+    <title>Accessibility test digest</title>
+    <link rel="icon" href="favicon.png">
+    <link rel="stylesheet" href="style.css">
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>Accessibility test digest</h1>
+        <h2>Synopsis</h2>
+        <div id="synopsis">
+          <p>Page: __org__</p>
+          <p>URL: __url__</p>
+          <p>Score: __totalScore__</p>
+          <p>Tested by: Testaro, procedure <code>tp10</code></p>
+          <p>Scored by: Testilo, procedure <code>sp10b</code></p>
+          <p>Digested by: Testilo, procedure <code>dp10b</code></p>
+        </div>
+      </header>
+      <h2>Introduction</h2>
+      <p>The <a href="https://www.npmjs.com/package/testaro">Testaro</a> application used its <code>tp10</code> testing procedure to test the <a href="https://www.w3.org/WAI/fundamentals/accessibility-intro/"><dfn>accessibility</dfn></a> (barrier-free design and coding) of the __org__ web page at <a href="__url__">__url__</a> on __dateSlash__. The procedure performed 808 tests. Of these, 16 are custom tests defined by Testaro, and the others belong to six other packages of tests:</p>
+      <ul>
+        <li><a href="https://www.npmjs.com/package/aatt">AATT</a> by PayPal running <a href="https://marketplace.squiz.net/extensions/html-codesniffer">HTMLCodeSniffer</a> by Squiz</li>
+        <li><a href="https://github.com/Siteimprove/alfa">Alfa</a> by Siteimprove</li>
+        <li><a href="https://www.npmjs.com/package/axe-core">Axe-core</a> by Deque</li>
+        <li><a href="https://github.com/IBMa/equal-access">Equal Access</a> by IBM</li>
+        <li><a href="https://tenon.io/documentation/apiv2.php">Tenon</a> by Level Access</li>
+        <li><a href="https://wave.webaim.org/api/">WAVE</a> by WebAIM</li>
+      </ul>
+      <p>Testaro produced a report enumerating the test results.</p>
+      <p><a href="https://www.npmjs.com/package/testilo">Testilo</a> used its <code>sp10b</code> scoring procedure to compute partial and total scores for the page. The total score is __totalScore__ (where 0 is the best possible score). The scored report is appended below.</p>
+      <p>Finally, Testilo used procedure <code>dp10b</code> to produce this digest, explaining how <code>sp10b</code> computed the scores.</p>
+      <h2>Score summary</h2>
+      <table class="allBorder secondCellRight">
+        <caption>Score components</caption>
+        <tbody class="headersLeft">
+        __scoreRows__
+        </tbody>
+      </table>
+      <h2>Issue summary</h2>
+      <h3>Special issues</h3>
+      __specialSummary__
+      <h3>Classified issues</h3>
+      <p>The classified issues reported by tests are summarized below.</p>
+      __groupSummary__
+      <h2>Discussion</h2>
+      <p>Although there are widely accepted <a href="https://www.w3.org/WAI/standards-guidelines/">accessibility standards</a>, there is still no unanimity about how to define, test, and quantify accessibility. The failures reported in this digest merit investigation as <strong>potential</strong> opportunities for improved accessibility. But you may conclude that some of the failures do not actually harm accessibility, and some substantial accessibility faults can escape detection by any of these tests. Likewise, you may disagree with weightings and formulas of scoring procedure <code>sp10b</code>, or question whether it is appropriate even to assign accessibility scores to a web page. This digest describes only one interpretation of the page&rsquo;s accessibility. You can modify and extend Testaro and Testilo to fit other understandings.</p>
+      <p>Scoring procedure <code>sp10b</code> bases scores on:</p>
+      <ul>
+        <li>how many categories of issues were reported</li>
+        <li>how many issues were reported per category</li>
+        <li>the largest count of issues of a category reported by a single test</li>
+        <li>how many tests reported the issues</li>
+        <li>how important each issue is deemed to be</li>
+      </ul>
+      <p>Most issues are simply counted, but some are complex and get a <q>count</q> that is really the result of a formula. The exact rules for scoring are in the <a href="https://github.com/jrpool/testilo/blob/main/procs/score/sp10b.js"><code>sp10b.js</code> file</a> that performs the scoring.</p>
+      <p>Weights used in the calculations are contained in the appended report in the <code>score</code> block. The <code>groupWeights</code> block within it contains the weights applied to the classified issues, and the <code>countWeights</code> block within it contains the amounts those weights are multiplied by or added to. For example, if <code>roleBad</code> issues are reported, the <code>roleBad</code> score is the <code>absolute</code> amount (2), plus the largest count of those issues reported by any test multiplied by the <code>largest</code> amount (1), plus the total count of those issues reported by all other tests multiplied by the <code>smaller</code> amount (0.4), all multiplied by the <code>roleBad</code> weight (3).</p>
+      <h2>Report</h2>
+      <pre>__report__</pre>
+      <footer>
+        <p class="date">Produced <time itemprop="datePublished" datetime="__dateISO__">__dateSlash__</time></p>
+      </footer>
+    </main>
+  </body>
+</html>

package/procs/digest/dp10b/index.js

@@ -0,0 +1,130 @@
+/*
+  index: digester for scoring procedure sp10b.
+  Creator of parameters for substitution into index.html.
+  Usage example: node digest 35k1r-railpass dp10b
+  Arguments:
+    0. report. Scored report.
+    1. query. Object to which this module will add properties.
+*/
+
+// CONSTANTS
+
+  // Newlines with indentations.
+  const joiner = '\n      ';
+  const innerJoiner = '\n        ';
+  const specialMessages = {
+    log: 'This is based on the amount of browser logging during the tests. Browsers usually log messages only when pages contain erroneous code.',
+    preventions: 'This is based on tests that the page did not allow to be run. That impedes accessibility progress and risks interfering with tools that users with disabilities need.',
+    solos: 'This is based on issues reported by unclassified tests. Details are in the report.'
+  };
+
+// FUNCTIONS
+
+// Makes strings HTML-safe.
+const htmlEscape = textOrNumber => textOrNumber
+.toString()
+.replace(/&/g, '&')
+.replace(/</g, '&lt;');
+// Gets a row of the score-summary table.
+const getScoreRow = (component, score) => `<tr><th>${component}</th><td>${score}</td></tr>`;
+// Gets the start of a paragraph about a special score.
+const getSpecialPStart = (summary, scoreID) =>
+`<p><span class="componentID">${scoreID}</span>: Score ${summary[scoreID]}.`;
+// Adds parameters to a query for a digest.
+exports.makeQuery = (report, query) => {
+  // Add an HTML-safe copy of the host report to the query to be appended to the digest.
+  const {script, host, score} = report;
+  const reportJSON = JSON.stringify(report, null, 2);
+  const reportJSONSafe = htmlEscape(reportJSON);
+  query.report = reportJSONSafe;
+  // Add the job data to the query.
+  query.dateISO = report.endTime.slice(0, 10);
+  query.dateSlash = query.dateISO.replace(/-/g, '/');
+  if (host && host.what && host.which) {
+    query.org = host.what;
+    query.url = host.which;
+  }
+  else {
+    const firstURLCommand = script.commands.find(command => command.type === 'url');
+    if (firstURLCommand && firstURLCommand.what && firstURLCommand.which) {
+      query.org = firstURLCommand.what;
+      query.url = firstURLCommand.which;
+    }
+    else {
+      console.log('ERROR: host missing or invalid');
+      return;
+    }
+  }
+  const {groupDetails, summary} = score;
+  if (typeof summary.total === 'number') {
+    query.totalScore = summary.total;
+  }
+  else {
+    console.log('ERROR: missing or invalid total score');
+    return;
+  }
+  // Add the total and any special rows of the score-summary table to the query.
+  const scoreRows = [];
+  const specialComponentIDs = ['log', 'preventions', 'solos'];
+  ['total'].concat(specialComponentIDs).forEach(item => {
+    if (summary[item]) {
+      scoreRows.push(getScoreRow(item, summary[item]));
+    }
+  });
+  // Add the group rows of the score-summary table to the query.
+  const {groups} = summary;
+  const groupIDs = Object.keys(groups);
+  groupIDs.sort((a, b) => groups[b] - groups[a]);
+  groupIDs.forEach(groupID => {
+    scoreRows.push(getScoreRow(`${groupID}`, groups[groupID]));
+  });
+  query.scoreRows = scoreRows.join(innerJoiner);
+  // If the score has any special components:
+  const scoredSpecialIDs = specialComponentIDs.filter(item => summary[item]);
+  if (scoredSpecialIDs.length) {
+    // Add paragraphs about them for the issue summary to the query.
+    const specialPs = [];
+    scoredSpecialIDs.forEach(id => {
+      specialPs.push(`${getSpecialPStart(summary, id)} ${specialMessages[id]}`);
+    });
+    query.specialSummary = specialPs.join(joiner);
+  }
+  // Otherwise, i.e. if the score has no special components:
+  else {
+    // Add a paragraph stating this for the issue summary to the query.
+    query.specialSummary = '<p>No special issues contributed to the score.</p>'
+  }
+  // If the score has any classified issues as components:
+  if (groupIDs.length) {
+    // Add paragraphs about them for the special summary to the query.
+    const groupSummaryItems = [];
+    groupIDs.forEach(id => {
+      const groupP = `<p><span class="componentID">${id}</span>: Score ${summary.groups[id]}. Issues reported by tests in this category:</p>`;
+      const groupListItems = [];
+      const groupData = groupDetails.groups[id];
+      const packageIDs = Object.keys(groupData);
+      packageIDs.forEach(packageID => {
+        const testIDs = Object.keys(groupData[packageID]);
+        testIDs.forEach(testID => {
+          const testData = groupData[packageID][testID];
+          const {issueCount} = testData;
+          const issueNoun = issueCount !== 1 ? 'issues' : 'issue';
+          const listItem = `<li>${issueCount} ${issueNoun} reported by package <code>${packageID}</code>, test <code>${testID}</code> (${testData.what})</li>`;
+          groupListItems.push(listItem);
+        });
+      });
+      const groupList = [
+        '<ul>',
+        groupListItems.join('\n  '),
+        '</ul>'
+      ].join(joiner);
+      groupSummaryItems.push(groupP, groupList);
+    });
+    query.groupSummary = groupSummaryItems.join(joiner);
+  }
+  // Otherwise, i.e. if the score has no classified issues as components:
+  else {
+    // Add a paragraph stating this for the group summary to the query.
+    query.groupSummary = '<p>No classified issues contributed to the score.</p>'
+  }
+};

package/procs/digest/dp10c/index.html

@@ -0,0 +1,55 @@
+<!DOCTYPE HTML>
+<html lang="en-US">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="author" content="Testilo">
+    <meta name="creator" content="Testilo">
+    <meta name="publisher" name="Testilo">
+    <meta name="description" content="report of accessibility testing of a web page">
+    <meta name="keywords" content="accessibility a11y web testing">
+    <title>Accessibility test digest</title>
+    <link rel="icon" href="favicon.png">
+    <link rel="stylesheet" href="style.css">
+  </head>
+  <body>
+    <main>
+      <header>
+        <h1>Accessibility test digest</h1>
+        <h2>Synopsis</h2>
+        <div id="synopsis">
+          <p>Page: __org__</p>
+          <p>URL: __url__</p>
+          <p>Score: __totalScore__</p>
+          <p>Tested by: Testaro, script <code>__scriptID__</code></p>
+          <p>Scored by: Testilo, procedure <code>sp10c</code></p>
+          <p>Digested by: Testilo, procedure <code>dp10c</code></p>
+        </div>
+      </header>
+      <h2>Introduction</h2>
+      <p>The <code>__scriptID__</code> <a href="https://www.w3.org/WAI/fundamentals/accessibility-intro/">accessibility</a> testing script was executed by <a href="https://www.npmjs.com/package/testaro">Testaro</a> on the __org__ web page arrived at in a transaction that began at <a href="__url__">__url__</a>, on __dateSlash__. The procedure performed custom tests defined by Testaro and tests belonging to packages created by others. Testaro produced a report enumerating the test results.</p>
+      <p><a href="https://www.npmjs.com/package/testilo">Testilo</a> used its <code>sp10c</code> scoring procedure to compute partial and total scores for the page. The total score is __totalScore__ (where 0 is the best possible score). The scored report is appended below.</p>
+      <p>Finally, Testilo used procedure <code>dp10c</code> to produce this digest, explaining how <code>sp10c</code> computed the scores.</p>
+      <p>Disclaimer: Even though there are widely accepted accessibility standards, there is still no unanimity about how to define, test for, and quantify accessibility. The failures reported below merit investigation as <strong>potential</strong> opportunities for improved accessibility. But you may conclude that some of the failures do not actually harm accessibility, and some substantial accessibility faults can escape detection by any of these tests. Likewise, you may not agree with weightings and formulas of scoring procedure <code>sp10b</code>, or even question whether it is appropriate to assign accessibility scores to a web page. This digest describes only one interpretation of the page&rsquo;s accessibility.</p>
+      <h2>Score summary</h2>
+      <p>The total score and its components were:</p>
+      <table class="allBorder secondCellRight">
+        <caption>Score components</caption>
+        <tbody class="headersLeft">
+        __scoreRows__
+        </tbody>
+      </table>
+      <h2>Issue summary</h2>
+      <h3>Special issues</h3>
+      __specialSummary__
+      <h3>Classified issues</h3>
+      <p>The classified issues reported by tests are summarized below.</p>
+      __groupSummary__
+      <h2>Report</h2>
+      <pre>__report__</pre>
+      <footer>
+        <p class="date">Produced <time itemprop="datePublished" datetime="__dateISO__">__dateSlash__</time></p>
+      </footer>
+    </main>
+  </body>
+</html>

package/procs/digest/dp10c/index.js

@@ -0,0 +1,129 @@
+/*
+  index: digester for scoring procedure sp10b.
+  Creator of parameters for substitution into index.html.
+  Usage example: node digest 35k1r-railpass dp10b
+  Arguments:
+    0. report. Scored report.
+    1. query. Object to which this module will add properties.
+*/
+
+// CONSTANTS
+
+  // Newlines with indentations.
+  const joiner = '\n      ';
+  const innerJoiner = '\n        ';
+  const specialMessages = {
+    log: 'This is based on the amount of browser logging during the tests. Browsers usually log messages only when pages contain erroneous code.',
+    preventions: 'This is based on tests that the page did not allow to be run. That impedes accessibility progress and risks interfering with tools that users with disabilities need.',
+    solos: 'This is based on issues reported by unclassified tests. Details are in the report.'
+  };
+
+// FUNCTIONS
+
+// Makes strings HTML-safe.
+const htmlEscape = textOrNumber => textOrNumber
+.toString()
+.replace(/&/g, '&')
+.replace(/</g, '&lt;');
+// Gets a row of the score-summary table.
+const getScoreRow = (component, score) => `<tr><th>${component}</th><td>${score}</td></tr>`;
+// Gets the start of a paragraph about a special score.
+const getSpecialPStart
+= (summary, scoreID) => `<p><span class="componentID">log</span>: Score ${summary[scoreID]}.`;
+// Adds parameters to a query for a digest.
+exports.makeQuery = (report, query) => {
+  // Add an HTML-safe copy of the host report to the query to be appended to the digest.
+  const {script, host, score} = report;
+  const reportJSON = JSON.stringify(report, null, 2);
+  const reportJSONSafe = htmlEscape(reportJSON);
+  query.report = reportJSONSafe;
+  // Add the job data to the query.
+  query.dateISO = report.endTime.slice(0, 10);
+  query.dateSlash = query.dateISO.replace(/-/g, '/');
+  query.scriptID = script.id;
+  if (host && host.what && host.which) {
+    query.org = host.what;
+    query.url = host.which;
+  }
+  else {
+    const firstURLCommand = script.commands.find(command => command.type === 'url');
+    if (firstURLCommand && firstURLCommand.what && firstURLCommand.which) {
+      query.org = script.what;
+      query.url = firstURLCommand.which;
+    }
+    else {
+      console.log('ERROR: host missing or invalid');
+      return;
+    }
+  }
+  const {groupDetails, summary} = score;
+  if (typeof summary.total === 'number') {
+    query.totalScore = summary.total;
+  }
+  else {
+    console.log('ERROR: missing or invalid total score');
+    return;
+  }
+  // Add the total and any special rows of the score-summary table to the query.
+  const scoreRows = [];
+  const specialComponentIDs = ['log', 'preventions', 'solos'];
+  ['total'].concat(specialComponentIDs).forEach(item => {
+    if (summary[item]) {
+      scoreRows.push(getScoreRow(item, summary[item]));
+    }
+  });
+  // Add the group rows of the score-summary table to the query.
+  const {groups} = summary;
+  const groupIDs = Object.keys(groups);
+  groupIDs.sort((a, b) => groups[b] - groups[a]);
+  groupIDs.forEach(groupID => {
+    scoreRows.push(getScoreRow(`group ${groupID}`, groups[groupID]));
+  });
+  query.scoreRows = scoreRows.join(innerJoiner);
+  // If the score has any special components:
+  const scoredSpecialIDs = specialComponentIDs.filter(item => summary[item]);
+  if (scoredSpecialIDs.length) {
+    // Add paragraphs about them for the issue summary to the query.
+    const specialPs = [];
+    scoredSpecialIDs.forEach(id => {
+      specialPs.push(`${getSpecialPStart(summary, id)} ${specialMessages[id]}`);
+    });
+    query.specialSummary = specialPs.join(joiner);
+  }
+  // Otherwise, i.e. if the score has no special components:
+  else {
+    // Add a paragraph stating this for the issue summary to the query.
+    query.specialSummary = '<p>No special issues contributed to the score.</p>'
+  }
+  // If the score has any classified issues as components:
+  if (groupIDs.length) {
+    // Add paragraphs about them for the special summary to the query.
+    const groupSummaryItems = [];
+    groupIDs.forEach(id => {
+      const groupP = `<p><span class="componentID">${id}</span>: Score ${summary.groups[id]}. Issues reported by tests in this category:</p>`;
+      const groupListItems = [];
+      const groupData = groupDetails.groups[id];
+      const packageIDs = Object.keys(groupData);
+      packageIDs.forEach(packageID => {
+        const testIDs = Object.keys(groupData[packageID]);
+        testIDs.forEach(testID => {
+          const testData = groupData[packageID][testID];
+          const listItem = `<li>${testData.issueCount} issues reported by package ${packageID}, test ${testID} (${testData.what})</li>`;
+          groupListItems.push(listItem);
+        });
+      });
+      const groupList = [
+        '<ul>',
+        groupListItems.join('\n  '),
+        '</ul>'
+      ].join(joiner);
+      groupSummaryItems.push(groupP, groupList);
+    });
+    query.groupSummary = groupSummaryItems.join(joiner);
+  }
+  // Otherwise, i.e. if the score has no classified issues as components:
+  else {
+    // Add a paragraph stating this for the group summary to the query.
+    query.groupSummary = '<p>No classified issues contributed to the score.</p>'
+  }
+};