testilo 6.1.7 → 7.0.0

package/README.md

@@ -9,10 +9,20 @@ Testaro performs digital accessibility tests on web artifacts and creates report
 
 Because Testilo supports Testaro, this `README` file presumes that you have access to the Testaro `README` file and therefore does not repeat information provided there.
 
+## Branches
+
+The `writer` branch contains the state of Testilo as of 2022-11-07. In that branch, Testilo must read and write files when it aims, scores, or digests. That makes Testilo unusable as a dependency in applications that do not have permission to both read and write files.
+
+The `main` branch contains the state of Testilo starting on 2022-11-07. In that branch, Testilo does not need to read or write files when it aims, scores, or digests, so applications without write permission can still use Testilo as a dependency if they need only those functionalities.
+
+This `README.md` file documents the `main` branch.
+
 ## Dependencies
 
 The `dotenv` dependency lets you set environment variables in an untracked `.env` file. This prevents secret data, such as passwords, from being shared as part of this package.
 
+When Testilo is a dependency of another application, the `.env` file is not imported, because it is not tracked, so all needed environment variables must be provided by the importing application.
+
 ## Architecture
 
 Testilo is written in Node.js. Commands are given to Testilo in a command-line (terminal) interface or programmatically.
@@ -37,15 +47,23 @@ The `aim` function allows you to _aim_ a script at a host. That means modifying
 Execution by a module:
 
 ```javaScript
-const host = {
-  which: https://w3c.org/,
-  what: 'World Wide Web Consortium',
-  id: w3c
-};
-const fs = require('fs/promises');
-const {aim} = require('testilo/aim');
-const aimedScript = aim('tp25', host, 'developer@w3c.org');
-fs.writeFile(process.env.JOBDIR, JSON.stringify(aimedScript, null, 2));
+const aimScript = async () => {
+  const fs = require('fs/promises');
+  const host = {
+    which: https://w3c.org/,
+    what: 'World Wide Web Consortium',
+    id: w3c
+  };
+  const {aim} = require('testilo/aim');
+  const scriptJSON = await fs.readFile(`${process.env.SCRIPTDIR}/tp25.json`, 'utf8');
+  const script = JSON.parse(scriptJSON);
+  const aimedScript = aim(script, host, 'developer@w3c.org');
+  await fs.writeFile(
+    `${process.env.JOBDIR}/${aimedScript.id}.json`, JSON.stringify(aimedScript, null, 2)
+  );
+  console.log(`Script ${aimedScript.source.script} aimed at ${aimedScript.host.what}`);
+}
+aimScript();
 ```
 
 Execution by a user:
@@ -56,6 +74,8 @@ node call aim tp25 https://w3.org/ 'World Wide Web Consortium' w3c developer@w3c
 
 In these examples, a copy of the script file named `tp25.json` in the `SCRIPTDIR` directory is aimed at the World Wide Web Consortium and then saved in the `JOBDIR` directory.
 
+The `aim` function neither reads nor writes files. Its arguments are a script object, a host object, and a requester-email-address string, and it returns the script object, aimed at the host.
+
 ### `merge`
 
 The `merge` function is similar to the `aim` function, but it aims a script at multiple hosts, not only one. The hosts are identified in a _batch_, a file in the `BATCHDIR` directory. The output of `merge` is multiple script files, one per host, saved in the `JOBDIR` directory.
@@ -99,17 +119,57 @@ Execution by a user:
 node call merge tp25 weborgs
 ```
 
+In these examples, a copy of the script file named `tp25.json` in the `SCRIPTDIR` directory is aimed at all the hosts in the batch file named `weborgs.json` in the `BATCHDIR` directory, and the resulting host-specific scripts are saved in the `JOBDIR` directory.
+
 ### `score`
 
 Testaro performs tests and produces reports of test results. Testilo can add scores to those reports. In this way, each report can not only detail successes and failures of individual tests but also assign scores to those results and combine the partial scores into total scores.
 
-The `score` function performs scoring. It depends on _score procs_ to define the scoring rules. Some score procs are in the Testilo package (in the `procs/score` directory), and you can create more score procs to implement different rules.
+The `score` function performs scoring. It depends on a _score proc_ to define the scoring rules. Some score procs are in the Testilo package (in the `procs/score` directory), and you can create more score procs to implement different rules.
+
+Execution by a module:
+
+```javaScript
+const fs = require('fs/promises');
+const scoreReport = async rawReport => {
+  const {score} = require('testilo/score');
+  const procJSON = await fs.readFile(`${process.env.SCOREPROCDIR}/sp25a.json`, 'utf8');
+  const proc = JSON.parse(procJSON);
+  const scoredReport = score(proc, rawReport);
+  await fs.writeFile(
+    `${process.env.REPORTDIR_SCORED}/${scoredReport.id}.json`, JSON.stringify(scoredReport, null, 2)
+  );
+  console.log(`Report ${scoredReport.id} scored`);
+};
+fs.readFile(`${process.env.REPORTDIR_RAW}/756mr-tp25-w3c.json`, 'utf8')
+.then(rawReportJSON => {
+  const rawReport = JSON.parse(rawReportJSON);
+  scoreReport(rawReport);
+});
+```
+
+Execution by a user:
+
+```bash
+node call score sp25a
+node call score sp25a 756mr
+```
+
+In these examples, the `score` function applies a score proc named `sp25a`, of which a copy is in the file `sp25a.json` in the `SCOREPROCDIR` directory, to a raw report `756mr-tp25-w3c.json` in the `REPORTDIR_RAW` directory and returns the same report with score data added. The scored report is saved in the `REPORTDIR_SCORED` directory.
+
+The user statement can pass only 2 arguments to `call` if the first report in the `REPORTDIR_RAW` directory is the desired raw report. If there are multiple reports in that directory and the desired one is not the first, the user must pass 3 arguments to `call`, and the third argument must be a string, such that the first report in that directory that begins with that string is the desired report.
+
+The `score` function neither reads nor writes files. Its arguments are a score-proc string and a raw-report object, and it returns a scored-report object.
+
+### `multiScore`
+
+The `multiScore` function scores all the reports in the `REPORTDIR_RAW` directory and writes the scored reports in the `REPORTDIR_SCORED` directory.
 
 Execution by a module:
 
 ```javaScript
-const {score} = require('testilo/score');
-score('sp25a', '756mr')
+const {multiScore} = require('testilo/multiScore');
+multiScore('sp25a')
 .then(hostCount => {
   console.log(`Scoring complete. Count of reports scored: ${hostCount}`);
 });
@@ -118,40 +178,78 @@ score('sp25a', '756mr')
 Execution by a user:
 
 ```bash
-node call score sp25a 756mr
+node call multiScore sp25a
 ```
 
-The first argument to `score` names the score proc to be used. The second argument is optional. If it is present, then only reports whose names begin with the value of that argument will be scored. Otherwise all reports in the `REPORTDIR_RAW` directory will be scored. The scored reports will be written in the `REPORTDIR_SCORED` directory.
+The argument to `multiScore` names the score proc to be used. The `multiScore` function scores all the reports in the `REPORTDIR_RAW` directory and writes the scored reports in the `REPORTDIR_SCORED` directory.
 
 ### `digest`
 
-Testaro reports, both originally and after they are scored, are JSON files. That format is human-readable, but it is basically designed for machine tractability.
+Testaro reports, both originally and after they are scored, are JavaScript objects. When represented as JSON, they are human-readable, but basically designed for machine tractability.
 
-The `digest` function converts scored reports into HTML documents with explanatory content. Thus, it converts machine-oriented reports into human-oriented reports, called _digests_. It depends on _digest procs_ to define the digesting rules. Some digest procs are in the Testilo package (in the `procs/digest` directory), and you can create more digest procs to implement different rules.
+The `digest` function converts scored reports into HTML documents with explanatory content. Thus, it converts machine-oriented reports into human-oriented reports, called _digests_. It depends on a _digest proc_ to define the digesting rules. Some digest procs are in the Testilo package (in the `procs/digest` directory), and you can create more digest procs to implement different rules.
 
 Execution by a module:
 
 ```javaScript
-const {digest} = require('testilo/digest');
-digest('dp25a', '756mr')
-.then(hostCount => {
-  console.log(`Digesting complete. Count of reports digested: ${hostCount}.`);
+const fs = require('fs/promises');
+const digestReport = async scoredReport => {
+  const {digest} = require('testilo/digest');
+  const procJSON = await fs.readFile(`${process.env.DIGESTPROCDIR}/dp25a.json`, 'utf8');
+  const proc = JSON.parse(procJSON);
+  const digest = digest(proc, scoredReport);
+  await fs.writeFile(
+    `${process.env.REPORTDIR_DIGESTED}/${digest.id}.json`, JSON.stringify(digest, null, 2)
+  );
+  console.log(`Report ${digest.id} digested`);
+};
+fs.readFile(`${process.env.REPORTDIR_SCORED}/756mr-tp25-w3c.json`, 'utf8')
+.then(scoredReportJSON => {
+  const scoredReport = JSON.parse(scoredReportJSON);
+  digestReport(scoredReport);
 });
 ```
 
 Execution by a user:
 
 ```bash
+node call digest sp25a
 node call digest sp25a 756mr
 ```
 
-The first argument to `digest` names the digest proc to be used. The second argument is optional. If it is present, then only reports whose names begin with the value of that argument will be digested. Otherwise all reports in the `REPORTDIR_SCORED` directory will be digested. The digested reports will be written in the `REPORTDIR_DIGESTED` directory.
+In these examples, the `digest` function applies a digest proc named `dp25a`, of which a copy is in the file `dp25a.json` in the `DIGESTPROCDIR` directory, to a scored report `756mr-tp25-w3c.json` in the `REPORTDIR_SCORED` directory and returns an HTML digest for that same report. The digest is saved in the `REPORTDIR_DIGESTED` directory.
+
+The user statement can pass only 2 arguments to `call` if the first report in the `REPORTDIR_SCORED` directory is the desired scored report. If there are multiple reports in that directory and the desired one is not the first, the user must pass 3 arguments to `call`, and the third argument must be a string, such that the first report in that directory that begins with that string is the desired report.
+
+The `digest` function neither reads nor writes files. Its arguments are a digest-proc string and a scored-report object, and it returns a digest HTML string.
+
+### `multiDigest`
+
+The `multiDigest` function digests all the reports in the `REPORTDIR_SCORED` directory and writes the digests in the `REPORTDIR_DIGESTED` directory.
+
+Execution by a module:
+
+```javaScript
+const {multiDigest} = require('testilo/multiDigest');
+multiDigest('dp25a')
+.then(hostCount => {
+  console.log(`Digesting complete. Count of reports digested: ${hostCount}`);
+});
+```
+
+Execution by a user:
+
+```bash
+node call multiDigest dp25a
+```
+
+The argument to `multiDigest` or the second argument to `call` names the digest proc to be used. The `multiDigest` function digests all the reports in the `REPORTDIR_SCORED` directory and writes the digests in the `REPORTDIR_DIGESTED` directory.
 
 The digests created by `digest` are HTML files, and they expect a `style.css` file to exist in their directory. The `reports/digested/style.css` file in Testilo is an appropriate stylesheet to be copied into the `REPORTDIR_DIGESTED` directory.
 
 ### `compare`
 
-You can summarize the results of a multi-host job by producing a document comparing the scores received by the hosts. The `compare` function does this. It gathers scores from a set of scored reports and produces an HTML document comparing the scores. It depends on _comparison procs_ to define the rules for making and showing the comparative scores. Some compare procs are in the Testilo package (in the `procs/compare` directory), and you can create more compare procs to implement different rules.
+You can summarize multiple scored reports by producing a document comparing the scores. The `compare` function does this. It gathers scores from a set of scored reports and produces an HTML document comparing the scores. It depends on a _comparison proc_ to define the rules for making and showing the comparative scores. Some compare procs are in the Testilo package (in the `procs/compare` directory), and you can create more compare procs to implement different rules.
 
 Execution by a module:
 
@@ -169,6 +267,6 @@ Execution by a user:
 node call compare cp25a legislators
 ```
 
-The first argument to `compare` names the comparison proc to be used. The second argument specifies a base of the name of the comparative report that will be produced. The scores in all reports in the `REPORTDIR_SCORED` directory will be compared. The comparative report will be written in the `COMPARISONDIR` directory.
+The first argument to `compare`, or the second argument to `call`,  names the comparison proc to be used. The subsequent argument specifies a base of the name of the comparative report that will be produced. The scores in all reports in the `REPORTDIR_SCORED` directory will be compared. The comparative report will be written in the `COMPARISONDIR` directory.
 
-The digests created by `compare` are HTML files, and they expect a `style.css` file to exist in their directory. The `reports/comparative/style.css` file in Testilo is an appropriate stylesheet to be copied into the `COMPARISONDIR` directory.
+The comparison created by `compare` is an HTML file, and it expects a `style.css` file to exist in its directory. The `reports/comparative/style.css` file in Testilo is an appropriate stylesheet to be copied into the `COMPARISONDIR` directory.

package/aim.js

@@ -3,25 +3,11 @@
   Module for aiming a script at a host.
 */
 
-// ########## IMPORTS
-
-// Module to keep secrets.
-require('dotenv').config();
-// Module to read and write files.
-const fs = require('fs/promises');
-
-// ########## CONSTANTS
-
-const scriptDir = process.env.SCRIPTDIR || 'scripts';
-
 // ########## FUNCTIONS
 
 // Returns a script, aimed at a host.
-exports.aim = async (scriptName, host, requester) => {
-  // Copy the script.
-  const scriptFile = await fs.readFile(`${scriptDir}/${scriptName}.json`, 'utf8');
-  const script = JSON.parse(scriptFile);
-  // In the copy, make all url commands visit the host.
+exports.aim = async (script, host, requester) => {
+  // Make all url commands in the script visit the host.
   script.commands.forEach(command => {
     if (command.type === 'url') {
       command.id = host.id;
@@ -37,8 +23,8 @@ exports.aim = async (scriptName, host, requester) => {
   }
   // Create a job-creation time stamp.
   const timeStamp = Math.floor((Date.now() - Date.UTC(2022, 1)) / 2000).toString(36);
-  // Change the script id property to include the time stamp and the host ID.
-  script.id = `${timeStamp}-${script.id}-${host.id}`;
+  // Add a job-ID property to the script, including the time stamp, the script ID, and the host ID.
+  script.jobID = `${timeStamp}-${script.id}-${host.id}`;
   // Return the host-specific script.
   return script;
 };

package/digest.js

@@ -1,53 +1,25 @@
 /*
   digest.js
-  Creates digests from scored reports.
-  Reads reports in process.env.REPORTDIR_SCORED and outputs into process.env.REPORTDIR_DIGESTED.
+  Creates a digest from a scored report.
   Arguments:
-    0. Base of name of digest proc located in procs/digest.
-    1?. starting substring of names of reports in process.env.REPORTDIR_SCORED.
-  Usage examples:
-    node digest dp18a 35k1r (to digest all scored reports with names starting with 35k1r)
-    node digest dp18a (to digest all scored reports)
+    0. Digest template.
+    1. Digest proc.
+    2. Scored report.
 */
 
-// ########## IMPORTS
-
-// Module to keep secrets.
-require('dotenv').config();
-// Module to read and write files.
-const fs = require('fs/promises');
-
-// ########## CONSTANTS
-
-const reportDirScored = process.env.REPORTDIR_SCORED || 'reports/scored';
-const reportDirDigested = process.env.REPORTDIR_DIGESTED || 'reports/digested';
-const digestProcDir = process.env.DIGESTPROCDIR || `${__dirname}/procs/digest`;
-
 // ########## FUNCTIONS
 
 // Replaces the placeholders in content with eponymous query parameters.
 const replaceHolders = (content, query) => content
 .replace(/__([a-zA-Z]+)__/g, (ph, qp) => query[qp]);
-// Creates digests.
-exports.digest = async (digesterID, reportIDStart) => {
-  let reportFileNames = await fs.readdir(reportDirScored);
-  reportFileNames = reportFileNames.filter(fileName => fileName.endsWith('.json'));
-  if (reportIDStart) {
-    reportFileNames = reportFileNames
-    .filter(fileName => fileName.startsWith(reportIDStart));
-  }
-  const {makeQuery} = require(`${digestProcDir}/${digesterID}/index.js`);
-  for (const fileName of reportFileNames) {
-    const reportJSON = await fs.readFile(`${reportDirScored}/${fileName}`, 'utf8');
-    const report = JSON.parse(reportJSON);
-    const query = {};
-    makeQuery(report, query);
-    const template = await fs
-    .readFile(`${digestProcDir}/${digesterID}/index.html`, 'utf8');
-    const digest = replaceHolders(template, query);
-    const fileNameBase = fileName.slice(0, -5);
-    await fs.writeFile(`${reportDirDigested}/${fileNameBase}.html`, digest);
-    console.log(`Report ${fileNameBase} digested and saved`);
-  };
-  return reportFileNames.length;
+// Creates a digest.
+exports.digest = (digestTemplate, digestProc, scoredReport) => {
+  // Create a query.
+  const query = {};
+  digestProc(scoredReport, query);
+  // Use it to replace the placeholders in the template.
+  const digest = replaceHolders(digestTemplate, query);
+  // Return the digest.
+  console.log(`Report ${scoredReport.id} digested`);
+  return digest;
 };

package/multiDigest.js

@@ -0,0 +1,51 @@
+/*
+  multiDigest.js
+  Creates digests from scored reports.
+  Reads all reports in process.env.REPORTDIR_SCORED and outputs them, digested, into
+  process.env.REPORTDIR_DIGESTED.
+  Argument:
+    0. Base of name of digest proc located in process.env.DIGESTPROCDIR.
+  Usage example: node digest dp25a
+*/
+
+// ########## IMPORTS
+
+// Module to keep secrets.
+require('dotenv').config();
+// Module to read and write files.
+const fs = require('fs/promises');
+
+// ########## CONSTANTS
+
+const reportDirScored = process.env.REPORTDIR_SCORED || 'reports/scored';
+const reportDirDigested = process.env.REPORTDIR_DIGESTED || 'reports/digested';
+const digestProcDir = process.env.DIGESTPROCDIR || `${__dirname}/procs/digest`;
+
+// ########## FUNCTIONS
+
+// Replaces the placeholders in content with eponymous query parameters.
+const replaceHolders = (content, query) => content
+.replace(/__([a-zA-Z]+)__/g, (ph, qp) => query[qp]);
+// Creates digests.
+exports.multiDigest = async (digesterID, reportIDStart) => {
+  // Identify the reports to be digested.
+  let reportFileNames = await fs.readdir(reportDirScored);
+  reportFileNames = reportFileNames.filter(fileName => fileName.endsWith('.json'));
+  // For each report:
+  const {makeQuery} = require(`${digestProcDir}/${digesterID}/index.js`);
+  for (const fileName of reportFileNames) {
+    const reportJSON = await fs.readFile(`${reportDirScored}/${fileName}`, 'utf8');
+    const report = JSON.parse(reportJSON);
+    // Define its replacements for the placeholders in the digest template.
+    const query = {};
+    makeQuery(report, query);
+    // Replace the placeholders.
+    const template = await fs.readFile(`${digestProcDir}/${digesterID}/index.html`, 'utf8');
+    const digest = replaceHolders(template, query);
+    // Write its digest.
+    const fileNameBase = fileName.slice(0, -5);
+    await fs.writeFile(`${reportDirDigested}/${fileNameBase}.html`, digest);
+    console.log(`Report ${fileNameBase} digested and saved`);
+  };
+  return reportFileNames.length;
+};

package/multiScore.js

@@ -0,0 +1,45 @@
+/*
+  multiScore.js
+  Scores multiple Testaro reports.
+  Reads all reports in process.env.REPORTDIR_RAW and outputs them, scored, into
+  process.env.REPORTDIR_SCORED.
+  Arguments:
+    0. Base of name of score proc located in process.env.SCOREPROCDIR.
+  Usage example: node score sp18a
+*/
+
+// ########## IMPORTS
+
+// Module to keep secrets.
+require('dotenv').config();
+// Module to read and write files.
+const fs = require('fs/promises');
+
+// ########## CONSTANTS
+
+const reportDirRaw = process.env.REPORTDIR_RAW || 'reports/raw';
+const reportDirScored = process.env.REPORTDIR_SCORED || 'reports/scored';
+const scoreProcDir = process.env.SCOREPROCDIR || `${__dirname}/procs/score`;
+
+// ########## FUNCTIONS
+
+// Score the specified reports and return their count.
+exports.score = async scoreProcID => {
+  // Identify the reports to be scored.
+  let reportFileNames = await fs.readdir(reportDirRaw);
+  reportFileNames = reportFileNames.filter(fileName => fileName.endsWith('.json'));
+  // For each of them:
+  const {scorer} = require(`${scoreProcDir}/${scoreProcID}`);
+  for (const fileName of reportFileNames) {
+    // Score it.
+    const reportJSON = await fs.readFile(`${reportDirRaw}/${fileName}`, 'utf8');
+    const report = JSON.parse(reportJSON);
+    await scorer(report);
+    report.scoreProcID = scoreProcID;
+    // Write it to a file.
+    const scoredReportJSON = JSON.stringify(report, null, 2);
+    await fs.writeFile(`${reportDirScored}/${fileName}`, `${scoredReportJSON}\n`);
+    console.log(`Report ${fileName.slice(0, -5)} scored and saved`);
+  };
+  return reportFileNames.length;
+};

package/package.json

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

package/score.js

@@ -1,50 +1,19 @@
 /*
   score.js
-  Scores Testaro reports.
-  Reads reports in process.env.REPORTDIR_RAW and outputs into process.env.REPORTDIR_SCORED.
+  Scores a Testaro report.
   Arguments:
-    0. Base of name of score proc located in procs/score.
-    1?. Starting substring of names of reports in process.env.REPORTDIR_RAW.
-  Usage examples:
-    node score sp18a 35k1r (to score all reports with names starting with 35k1r)
-    node score sp18a (to score all reports)
+    0. Score proc.
+    1. Raw report.
 */
 
-// ########## IMPORTS
-
-// Module to keep secrets.
-require('dotenv').config();
-// Module to read and write files.
-const fs = require('fs/promises');
-
-// ########## CONSTANTS
-
-const reportDirRaw = process.env.REPORTDIR_RAW || 'reports/raw';
-const reportDirScored = process.env.REPORTDIR_SCORED || 'reports/scored';
-const scoreProcDir = process.env.SCOREPROCDIR || `${__dirname}/procs/score`;
-
 // ########## FUNCTIONS
 
-// Score the specified reports and return their count.
-exports.score = async (scoreProcID, reportIDStart) => {
-  // Identify the reports to be scored.
-  let reportFileNames = await fs.readdir(reportDirRaw);
-  reportFileNames = reportFileNames.filter(fileName => fileName.endsWith('.json'));
-  if (reportIDStart) {
-    reportFileNames = reportFileNames.filter(fileName => fileName.startsWith(reportIDStart));
-  }
-  // For each of them:
-  const {scorer} = require(`${scoreProcDir}/${scoreProcID}`);
-  for (const fileName of reportFileNames) {
-    // Score it.
-    const reportJSON = await fs.readFile(`${reportDirRaw}/${fileName}`, 'utf8');
-    const report = JSON.parse(reportJSON);
-    await scorer(report);
-    report.scoreProcID = scoreProcID;
-    // Write it to a file.
-    const scoredReportJSON = JSON.stringify(report, null, 2);
-    await fs.writeFile(`${reportDirScored}/${fileName}`, `${scoredReportJSON}\n`);
-    console.log(`Report ${fileName.slice(0, -5)} scored and saved`);
-  };
-  return reportFileNames.length;
+// Score the specified raw report and return it, scored.
+exports.score = async (scoreProc, rawReport) => {
+  // Initialize a scored report.
+  const scoredReport = JSON.parse(JSON.stringify(rawReport));
+  // Score it.
+  await scoreProc(scoredReport);
+  console.log(`Report ${rawReport.id} scored`);
+  return scoredReport;
 };