testilo 6.1.7 → 7.0.1

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,56 @@ 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 {score} = require('testilo/score');
-score('sp25a', '756mr')
+const scoreReport = async (scoreProcID, rawReportID) => {
+  const fs = require('fs/promises');
+  const {score} = require('testilo/score');
+  const {scorer} = require(`${process.env.SCOREPROCDIR}/${scoreProcID}`);
+  const rawReportJSON = await fs.readFile(
+    `${process.env.REPORTDIR_RAW}/${rawReportID}.json`, 'utf8'
+  );
+  const rawReport = JSON.parse(rawReportJSON);
+  const scoredReport = score(scorer, rawReport);
+  await fs.writeFile(
+    `${process.env.REPORTDIR_SCORED}/${scoredReport.id}.json`, JSON.stringify(scoredReport, null, 2)
+  );
+  console.log(`Report ${scoredReport.id} scored`);
+};
+scoreReport('sp25a', '756mr-tp25-w3c');
+```
+
+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 {multiScore} = require('testilo/multiScore');
+multiScore('sp25a')
 .then(hostCount => {
   console.log(`Scoring complete. Count of reports scored: ${hostCount}`);
 });
@@ -118,40 +177,75 @@ 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 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 digestReport = async (digestProcID, scoredReportID) => {
+  const fs = require('fs/promises');
+  const {digest} = require('testilo/digest');
+  const {makeQuery} = require(`${process.env.DIGESTPROCDIR}/${digestProcID}/index`);
+  const digestTemplate = await fs.readFile(
+    `${process.env.DIGESTPROCDIR}/${digestProcID}/index.html`
+  );
+  const digestedReport = digest(digestTemplate, makeQuery, scoredReport);
+  const digestedReport = digest(makeQuery, scoredReport);
+  await fs.writeFile(`${process.env.REPORTDIR_DIGESTED}/${digestedReport.id}.html`, digestedReport);
+  console.log(`Report ${digestedReport.id} digested`);
+};
+digestReport('dp25a', '756mr-tp25-w3c');
+```
+
+Execution by a user:
+
+```bash
+node call digest sp25a
+node call digest sp25a 756mr
+```
 
-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.
+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 {digest} = require('testilo/digest');
-digest('dp25a', '756mr')
+const {multiDigest} = require('testilo/multiDigest');
+multiDigest('dp25a')
 .then(hostCount => {
-  console.log(`Digesting complete. Count of reports digested: ${hostCount}.`);
+  console.log(`Digesting complete. Count of reports digested: ${hostCount}`);
 });
 ```
 
 Execution by a user:
 
 ```bash
-node call digest sp25a 756mr
+node call multiDigest dp25a
 ```
 
-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.
+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 +263,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 = (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/call.js

@@ -6,13 +6,15 @@
     0. function to execute.
     1+. arguments to pass to the function.
   Usage examples:
-    node call aim script454 https://www.w3c.org/ 'World Wide Web Consortium' w3c
+    node call aim tp25 https://www.w3c.org/ 'World Wide Web Consortium' w3c developer@w3.org
     node call merge script454 webOrgs
-    node call score sp25a (to score all reports in REPORTDIR_RAW)
-    node call score sp25a 8ep9f- (same, but only if names start with 8ep9f-)
-    node call digest dp25a (to digest all reports in REPORTDIR_SCORED)
-    node call digest dp25a 8ep9f- (same, but only if names start with 8ep9f-)
-    node call compare cp25a weborgs (to write weborgs.html, comparing all reports in REPORTDIR_SCORED)
+    node call score sp25a (to score the first raw report)
+    node call score sp25a 8ep9f (to score the first raw report whose name starts with 8ep9f)
+    node call multiScore sp25a
+    node call digest dp25a (to digest the first scored report)
+    node call digest dp25a 8ep9f (to digest the first scored report whose name starts with 8ep9f)
+    node call multiDigest dp25a
+    node call compare cp25a weborgs (to write weborgs.html, comparing all scored reports)
 */
 
 // ########## IMPORTS
@@ -24,16 +26,24 @@ const fs = require('fs/promises');
 const {aim} = require('./aim');
 // Function to process a script-batch merger.
 const {merge} = require('./merge');
-// Function to score reports.
+// Function to score a report.
 const {score} = require('./score');
-// Function to digest reports.
+// Function to score multiple reports.
+const {multiScore} = require('./multiScore');
+// Function to digest a report.
 const {digest} = require('./digest');
+// Function to digest multiple reports.
+const {multiDigest} = require('./multiDigest');
 // Function to compare scores.
 const {compare} = require('./compare');
 
 // ########## CONSTANTS
 
+const scriptDir = process.env.SCRIPTDIR;
+const scoreProcDir = process.env.SCOREPROCDIR;
+const digestProcDir = process.env.DIGESTPROCDIR;
 const jobDir = process.env.JOBDIR;
+const rawDir = process.env.REPORTDIR_RAW;
 const scoredDir = process.env.REPORTDIR_SCORED;
 const digestedDir = process.env.REPORTDIR_DIGESTED;
 const comparisonDir = process.env.COMPARISONDIR;
@@ -43,15 +53,17 @@ const fnArgs = process.argv.slice(3);
 // ########## FUNCTIONS
 
 // Fulfills an aiming request.
-const callAim = async (scriptName, hostURL, hostName, hostID, notifyee) => {
-  const aimedScript = await aim(
-    scriptName,
+const callAim = async (scriptName, hostURL, hostName, hostID, requester) => {
+  const scriptJSON = await fs.readFile(`${scriptDir}/${scriptName}.json`, 'utf8');
+  const script = JSON.parse(scriptJSON);
+  const aimedScript = aim(
+    script,
     {
       id: hostID,
       which: hostURL,
       what: hostName
     }, 
-    notifyee
+    requester
   );
   const aimedScriptID = aimedScript.id;
   await fs.writeFile(`${jobDir}/${aimedScriptID}.json`, JSON.stringify(aimedScript, null, 2));
@@ -64,16 +76,148 @@ const callMerge = async (scriptName, batchName) => {
 };
 // Fulfills a scoring request.
 const callScore = async (scoreProcID, reportIDStart) => {
-  const reportCount = await score(scoreProcID, reportIDStart);
-  console.log(
-    `Scoring completed. Score proc: ${scoreProcID}. Report count: ${reportCount}. Directory: ${scoredDir}`
-  );
+  // Identify the raw reports.
+  const rawFileNames = await fs.readdir(rawDir);
+  const rawReportNames = rawFileNames.filter(fileName => fileName.endsWith('.json'));
+  // If any exist:
+  if (rawReportNames.length) {
+    // Identify the one to be scored.
+    let rawReportName = '';
+    if (reportIDStart) {
+      rawReportName = rawReportNames.find(reportName => reportName.startsWith(reportIDStart));
+    }
+    else {
+      rawReportName = rawReportNames[0];
+    }
+    // If it exists:
+    if (rawReportName) {
+      // Score it.
+      const rawReportJSON = await fs.readFile(`${rawDir}/${rawReportName}.json`);
+      const rawReport = JSON.parse(rawReportJSON);
+      const {scorer} = require(`${scoreProcDir}/${scoreProcID}.js`);
+      const scoredReport = score(scorer, rawReport);
+      // Save it, scored.
+      await fs.writeFile(
+        `${scoredDir}/${scoredReport.id}.json`, JSON.stringify(scoredReport, null, 2)
+      );
+      console.log(`Report ${rawReport.id} scored and saved in ${scoredDir}`);
+    }
+    // Otherwise, i.e. if it does not exist:
+    else {
+      // Report this.
+      console.log('ERROR: Specified raw report not found');
+    }
+  }
+  // Otherwise, i.e. if no raw report found:
+  else {
+    // Report this.
+    console.log('ERROR: No raw report found');
+  }
+};
+// Fulfills a multiple-report scoring request.
+const callMultiScore = async scoreProcID => {
+  // Identify all the raw reports.
+  const rawFileNames = await fs.readdir(rawDir);
+  const rawReportNames = rawFileNames.filter(fileName => fileName.endsWith('.json'));
+  // If any exist:
+  if (rawReportNames.length) {
+    // For each of them:
+    const {scorer} = require(`${scoreProcDir}/${scoreProcID}.js`);
+    for (const rawReportName of rawReportNames) {
+      // Score it.
+      const rawReportJSON = await fs.readFile(`${rawDir}/${rawReportName}.json`);
+      const rawReport = JSON.parse(rawReportJSON);
+      const scoredReport = score(scorer, rawReport);
+      // Save it, scored.
+      await fs.writeFile(
+        `${scoredDir}/${scoredReport.id}.json`, JSON.stringify(scoredReport, null, 2)
+      );
+      console.log(`Report ${rawReport.id} scored and saved in ${scoredDir}`);
+    }
+  }
+  // Otherwise, i.e. if no raw report exists:
+  else {
+    // Report this.
+    console.log('ERROR: No raw report found');
+  }
 };
+// Prepares to fulfill a digesting request.
+const digestPrep = async digestProcID => {
+  const {digest} = require('testilo/digest');
+  const {makeQuery} = require(`${digestProcDir}/${digestProcID}/index`);
+  const digestTemplate = await fs.readFile(`${digestProcDir}/${digestProcID}/index.html`, 'utf8');
+  // Identify the scored reports.
+  const scoredFileNames = await fs.readdir(scoredDir);
+  const scoredReportNames = scoredFileNames.filter(fileName => fileName.endsWith('.json'));
+  // Return the data required for the fulfillment of the request.
+  return {
+    anyScoredReports: scoredReportNames.length > 0,
+    digest,
+    makeQuery,
+    digestTemplate,
+    scoredReportNames
+  };
+}
 // Fulfills a digesting request.
 const callDigest = async (digestProcID, reportIDStart) => {
-  const reportCount = await digest(digestProcID, reportIDStart);
+  const prepData = await digestPrep(digestProcID);
+  // If any scored reports exist:
+  if (prepData.anyScoredReports) {
+    // Identify the one to be digested.
+    let scoredReportName = '';
+    if (reportIDStart) {
+      scoredReportName = prepData.scoredReportNames.find(
+        reportName => reportName.startsWith(reportIDStart)
+      );
+    }
+    else {
+      scoredReportName = prepData.scoredReportNames[0];
+    }
+    // If it exists:
+    if (scoredReportName) {
+      // Digest it.
+      const scoredReportJSON = await fs.readFile(`${scoredDir}/${scoredReportName}.json`, 'utf8');
+      const scoredReport = JSON.parse(scoredReportJSON);
+      const digestedReport = digest(prepData.digestTemplate, makeQuery, scoredReport);
+      // Save it, digested.
+      await fs.writeFile(`${digestedDir}/${digestedReport.id}.html`, digestedReport);
+      console.log(`Report ${scoredReport.id} digested and saved in ${digestedDir}`);
+    }
+    // Otherwise, i.e. if it does not exist:
+    else {
+      // Report this.
+      console.log('ERROR: Specified scored report not found');
+    }
+  }
+  // Otherwise, i.e. if no scored report exists:
+  else {
+    // Report this.
+    console.log('ERROR: No scored report found');
+  }
+};
+// Fulfills a multiple-report digesting request.
+const callMultiDigest = async digestProcID => {
+  const prepData = await digestPrep(digestProcID);
+  // If any scored reports exist:
+  if (prepData.anyScoredReports) {
+    // For each of them:
+    for (const scoredReportName of prepData.scoredReportNames) {
+      // Digest it.
+      const scoredReportJSON = await fs.readFile(`${scoredDir}/${scoredReportName}.json`, 'utf8');
+      const scoredReport = JSON.parse(scoredReportJSON);
+      const digestedReport = digest(prepData.digestTemplate, makeQuery, scoredReport);
+      // Save it, digested.
+      await fs.writeFile(`${digestedDir}/${digestedReport.id}.html`, digestedReport);
+      console.log(`Report ${scoredReport.id} digested and saved in ${digestedDir}`);
+    }
+  }
+  // Otherwise, i.e. if no raw report exists:
+  else {
+    // Report this.
+    console.log('ERROR: No raw report found');
+  }
   console.log(
-    `Digesting completed. Digest proc: ${digestProcID}. Report count: ${reportCount}. Directory: ${digestedDir}`
+    `Digesting completed. Digest proc: ${digestProcID}. Report count: ${prepData.scoredReportNames.length}. Directory: ${digestedDir}`
   );
 };
 // Fulfills a comparison request.

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.multiScore = 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.1",
   "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;
 };