@jrpool/kilotest 38.1.0 → 39.0.1

package/util.js

@@ -6,7 +6,9 @@
 // IMPORTS
 
 const {sendAlert} = require('./alerts');
-const issuesClassification = require('testilo/procs/score/tic').issues;
+const issuesClassification
+= exports.issuesClassification
+= require('testilo/procs/score/tic').issues;
 const fs = require('fs/promises');
 const path = require('path');
 const querystring = require('querystring');
@@ -14,14 +16,18 @@ const wcagMap = require('./wcagMap.json');
 
 // CONSTANTS
 
+// Path of the data directory.
+const dbPath = exports.dbPath = path.join(__dirname, 'db');
 // Path of the jobs directory.
-const jobsPath = exports.jobsPath = path.join(__dirname, 'jobs');
-// Path of the logs directory.
-const logsPath = exports.logsPath = path.join(__dirname, 'logs');
+const jobsPath = exports.jobsPath = path.join(dbPath, 'jobs');
 // Path of the recommendations file.
-const recsPath = exports.recsPath = path.join(__dirname, 'jobs', 'recs.json');
+const recsPath = exports.recsPath = path.join(jobsPath, 'recs.json');
 // Path of the reports directory.
-const reportsPath = exports.reportsPath = path.join(__dirname, 'reports');
+const reportsPath = exports.reportsPath = path.join(dbPath, 'reports');
+// Path of the hidden-reports directory.
+const hiddenReportsPath = exports.hiddenReportsPath = path.join(dbPath, 'hiddenReports');
+// Path of the reports data file.
+const reportsExtractPath = exports.reportsExtractPath = path.join(dbPath, 'reportsExtract.json');
 // IDs, names, and sponsors of Testaro rule engines.
 const tools = exports.tools = {
   alfa: ['Alfa', 'Siteimprove'],
@@ -42,74 +48,59 @@ exports.researchAgents = {
   'research-agent': 'Internal Research Agent'
 }
 
-// FUNCTIONS
+// MISCELLANEOUS FUNCTIONS
 
-// Returns a random string.
-exports.getRandomString = length => {
-  return Math.random().toString(36).slice(2, length + 2);
-};
-// Returns whether a report is valid.
-exports.isValidReport = report => {
-  // Return whether it has the type and properties required by Kilotest:
-  return typeof report === 'object'
-  && typeof report.target?.what === 'string'
-  && typeof report.target?.url === 'string'
-  && Array.isArray(report.acts)
-  && report.acts.every(act =>
-    typeof act === 'object'
-    && typeof act.type === 'string'
-    && act.type === 'test' ? typeof act.which === 'string' && act.which : true
-  )
-  && typeof report.jobData === 'object';
+// Compares strings alphabetically and case-insensitively.
+const alphaCompare = (a, b) => a.localeCompare(b, 'en', {sensitivity: 'base'});
+// Sorts strings alphabetically and case-insensitively.
+const alphaSort = strings => strings.sort((a, b) => alphaCompare(a, b));
+// Returns a function that executes a function sequentially.
+/** @returns {<T>(fn: () => T | Promise<T>) => Promise<T>} */
+const createLock = exports.createLock = () => {
+  let queue = Promise.resolve();
+  return fn => {
+    const result = queue.then(fn, fn);
+    queue = result.then(() => {}, () => {});
+    return result;
+  };
 };
-// Encodes a string for use as a URL fragment.
+// Returns a string encoded for use as a URL fragment.
 const fragmentEncode = string => {
   return encodeURIComponent(string).replace(/-/g, '%2D');
 };
-// Returns the path of a log file.
-const getLogPath = exports.getLogPath
-= (timeStamp, jobID) => path.join(logsPath, `${timeStamp}-${jobID}.json`);
-// Returns the path of a report file.
-const getReportPath = exports.getReportPath
-= (timeStamp, jobID) => path.join(reportsPath, `${timeStamp}-${jobID}.json`);
-// Returns the path of a log or report file.
-const getRecordPath = exports.getRecordPath = (recordType, timeStamp, jobID) => {
-  if (recordType === 'log') {
-    return getLogPath(timeStamp, jobID);
+// Returns the time in days since a Date or time stamp, or null if the argument is invalid.
+const getAgoDays = exports.getAgoDays = timeArg => {
+  let dateTime;
+  // If the argument is a string:
+  if (typeof timeArg === 'string') {
+    // Convert it from a time stamp to a Date, or null if invalid.
+    dateTime = getDateTime(timeArg);
   }
-  else if (recordType === 'report') {
-    return getReportPath(timeStamp, jobID);
+  // Otherwise, if it is a Date:
+  else if (timeArg instanceof Date) {
+    // Convert it to null if it is invalid.
+    dateTime = timeArg.toString() === 'Invalid Date' ? null : timeArg;
   }
+  // Otherwise, i.e. if the argument is not a string or a Date:
   else {
+    // Return this.
     return null;
   }
-};
-// Returns a log or report.
-const getRecord = exports.getRecord = async (recordType, timeStamp, jobID) => {
-  const recordPath = getRecordPath(recordType, timeStamp, jobID);
-  let recordJSON, record;
-  try {
-    recordJSON = await fs.readFile(recordPath, 'utf8');
-  }
-  catch(error) {
-    console.log(error.message);
-    recordJSON = JSON.stringify({error: `Requested ${recordType} ${timeStamp}-${jobID} not found`});
-  }
-  try {
-    record = JSON.parse(recordJSON);
-  }
-  catch (error) {
-    console.log(error.message);
-    record = {error: `Requested ${recordType} ${timeStamp}-${jobID} not JSON`};
+  // If the argument is invalid:
+  if (!dateTime) {
+    // Return this.
+    return null;
   }
-  return record;
+  // Otherwise, i.e. if it is valid, return the elapsed days since then.
+  return Math.round((Date.now() - dateTime.getTime()) / (1000 * 60 * 60 * 24));
 };
-// Returns a report.
-const getReport = exports.getReport = async (timeStamp, jobID) => await getRecord(
-  'report', timeStamp, jobID
-);
-// Returns the JSON stringification of an object, with a final newline.
-const getJSON = exports.getJSON = object => `${JSON.stringify(object, null, 2)}\n`;
+// Returns a string describing the time in days since a time stamp.
+exports.getAgoString = timeStamp => {
+  const agoDays = getAgoDays(timeStamp);
+  return agoDays === 1 ? '1 day' : `${agoDays} days`;
+};
+// Returns a string describing a count.
+exports.getCountString = (count, singular, plural) => count === 1 ? `1 ${singular}` : `${count} ${plural}`;
 // Returns a date string from a time stamp.
 const getDateString = exports.getDateString = timeStamp => {
   const dateString = `20${timeStamp.slice(0, 2)}-${timeStamp.slice(2, 4)}-${timeStamp.slice(4,6)}`;
@@ -126,48 +117,68 @@ const getDateTime = exports.getDateTime = timeStamp => {
   const dateString
   = `20${timeStamp.slice(0, 2)}-${timeStamp.slice(2, 4)}-${timeStamp.slice(4,6)}T${timeStamp.slice(7,9)}:${timeStamp.slice(9,11)}Z`;
   const dateTime = new Date(dateString);
-  return dateTime;
+  return dateTime.toString() === 'Invalid Date' ? null : dateTime;
 };
-// Returns the time in days since a time stamp.
-const getAgoDays = exports.getAgoDays = timeStamp => Math.round(
-  (Date.now() - getDateTime(timeStamp)) / (1000 * 60 * 60 * 24)
-);
-// Returns a time string from a time stamp.
-const getTimeString = timeStamp => {
-  const timeString = `${timeStamp.slice(7, 9)}:${timeStamp.slice(9, 11)}`;
-  // If the time part of the time stamp is valid:
-  if (Date.parse(`2000-01-01T${timeString}`)) {
-    // Return a time string from it.
-    return timeString;
+// Returns the issue that a rule belongs to, or null if none.
+const getIssue = exports.getIssue = (ruleIDs, toolID, ruleID) => {
+  const {invariant, variable} = ruleIDs;
+  // Initialize the issue ID of the rule as if the rule ID is invariant.
+  let issueID = invariant[toolID]?.[ruleID];
+  // If the initialization succeeded:
+  if (issueID) {
+    // Return it.
+    return issueID;
   }
-  // Otherwise, return a failure.
-  return '';
+  // Otherwise, change the rule ID to the first matching variable rule ID of the tool.
+  ruleID = Object
+  .keys(variable[toolID] ?? {})
+  .find(variableRuleID => new RegExp(variableRuleID).test(ruleID));
+  // If the change succeeded:
+  if (ruleID) {
+    // Return the issue ID.
+    return variable[toolID][ruleID];
+  }
+  // Otherwise, i.e. if no issue was found, return a failure result.
+  return null;
 };
-// Compares strings alphabetically and case-insensitively.
-const alphaCompare = (a, b) => a.localeCompare(b, 'en', {sensitivity: 'base'});
-// Sorts strings alphabetically and case-insensitively.
-const alphaSort = strings => strings.sort((a, b) => alphaCompare(a, b));
-// Sorts objects by a property value.
-const objectSort = exports.objectSort = (objects, property, sortType) => objects
-.sort((a, b) => {
-  // If the property values are numbers to be sorted in increasing order:
-  if (sortType === 'numericUp') {
-    // Sort by increasing numeric value.
-    return a[property] - b[property];
+// Gets the names and categories of the job files.
+const getJobNames = exports.getJobNames = async () => {
+  const jobNames = {};
+  let fileNames;
+  for (const category of ['queue', 'claimed', 'failed']) {
+    try {
+      fileNames = await fs.readdir(path.join(jobsPath, category));
+    }
+    catch(error) {
+      return `ERROR: Job directory ${category} not readable (${error.message})`;
+    }
+    jobNames[category] = fileNames;
   }
-  // Otherwise, if they are numbers to be sorted in decreasing order:
-  else if (sortType === 'numericDown') {
-    // Sort by decreasing numeric value.
-    return b[property] - a[property];
+  return jobNames;
+}
+// Returns the JSON stringification of an object, with a final newline.
+const getJSON = exports.getJSON = object => `${JSON.stringify(object, null, 2)}\n`;
+// Returns an object from a JSON file.
+const getObject = exports.getObject = async filePath => {
+  let fileContent, object;
+  try {
+    fileContent = await fs.readFile(filePath, 'utf8');
   }
-  // Otherwise, if they are strings to be sorted alphabetically:
-  else if (sortType === 'alpha') {
-    // Sort alphabetically.
-    return alphaCompare(a[property], b[property]);
+  catch(error) {
+    return `ERROR: File ${filePath} not readable (${error.message})`;
   }
-  // Otherwise, do not sort.
-  return 0;
-});
+  try {
+    object = JSON.parse(fileContent);
+  }
+  catch(error) {
+    return `ERROR: File ${filePath} not JSON (${error.message})`;
+  }
+  return object;
+};
+// Returns a random string.
+exports.getRandomString = length => {
+  return Math.random().toString(36).slice(2, length + 2);
+};
 // Compiles a directory of the issue classifications of invariant and variable rules.
 const getRuleIDs = exports.getRuleIDs = () => {
   // Initialize data on invariant and variable rule IDs.
@@ -220,354 +231,93 @@ const getRuleIDs = exports.getRuleIDs = () => {
     variable
   };
 };
-// Variable and invariant rules.
-const ruleIDs = exports.ruleIDs = getRuleIDs();
-// Returns the issue that a rule belongs to, or null if none.
-const getIssue = exports.getIssue = (ruleIDs, toolID, ruleID) => {
-  const {invariant, variable} = ruleIDs;
-  // Initialize the issue ID of the rule as if the rule ID is invariant.
-  let issueID = invariant[toolID]?.[ruleID];
-  // If the initialization succeeded:
-  if (issueID) {
-    // Return it.
-    return issueID;
-  }
-  // Otherwise, change the rule ID to the first matching variable rule ID of the tool.
-  ruleID = Object
-  .keys(variable[toolID] ?? {})
-  .find(variableRuleID => new RegExp(variableRuleID).test(ruleID));
-  // If the change succeeded:
-  if (ruleID) {
-    // Return the issue ID.
-    return variable[toolID][ruleID];
-  }
-  // Otherwise, i.e. if no issue was found, return a failure result.
-  return null;
+// Returns a time stamp from a date.
+const getTimeStamp = exports.getTimeStamp = date => {
+  const timeStamp = date.toISOString().slice(2).replace(/[-:]/g, '').slice(0, 11);
+  return timeStamp;
 };
-// Adds issue IDs to the standard instances of a report.
-const annotateReport = exports.annotateReport = async (ruleIDs, timeStamp, jobID) => {
-  // Get a copy of the report.
-  const report = await getReport(timeStamp, jobID);
-  // If this failed:
-  if (report.error) {
-    // Return why.
-    return report.error;
-  }
-  // Otherwise, i.e. if it succeeded:
-  const unclassifiableRules = new Set();
-  // For each of its acts:
-  for (const act of report.acts) {
-    const {result, type, which} = act;
-    // If it is a test act:
-    if (type === 'test') {
-      // For each standard instance of the result:
-      for (const instance of result?.standardResult?.instances ?? []) {
-        const {ruleID} = instance;
-        // Classify its rule.
-        const issueID = getIssue(ruleIDs, which, ruleID);
-        // If the rule was classifiable:
-        if (issueID) {
-          // Add the issue ID to the instance.
-          instance.issueID = issueID;
-        }
-        // Otherwise, i.e. if it was not classifiable:
-        else {
-          // Add it to the set of unclassifiable rules.
-          unclassifiableRules.add(`${which}:${ruleID}`);
-          // Remove any existing issue ID from the instance.
-          delete instance.issueID;
-        }
-      }
+// Returns a time stamp for now.
+const getNowStamp = exports.getNowStamp = () => {
+  return getTimeStamp(new Date());
+};
+// Returns a time string from a time stamp.
+const getTimeString = timeStamp => {
+  const timeString = `${timeStamp.slice(7, 9)}:${timeStamp.slice(9, 11)}`;
+  // Return a time string from it.
+  return (Date.parse(`2000-01-01T${timeString}Z`)) ? timeString : null;
+};
+// Returns a date-and-time string.
+const getDateTimeString = exports.getDateTimeString = timeStamp => {
+  const dateString = getDateString(timeStamp);
+  const timeString = getTimeString(timeStamp);
+  const dateTimeString = `${dateString} at ${timeString}`;
+  return dateTimeString;
+}
+// Converts a string to a plain-text 1-line ASCII string.
+const getPlainText = exports.getPlainText = string => string
+.replace(/&/g, '+')
+.replace(/[<>"'&]/g, ' ');
+// Returns the data from a POST request.
+exports.getPOSTData = request => new Promise(resolve => {
+  const bodyParts = [];
+  request.on('data', chunk => {
+    bodyParts.push(chunk);
+  });
+  request.on('end', () => {
+    const {headers} = request;
+    const contentType = headers['content-type'] || headers['body-type'] || '';
+    if (contentType.startsWith('application/json')) {
+      const bodyJSON = bodyParts.join('');
+      const body = JSON.parse(bodyJSON);
+      resolve(body);
     }
+    else if (contentType.startsWith('application/x-www-form-urlencoded')) {
+      const body = bodyParts.join('');
+      const query = querystring.parse(body);
+      resolve(query);
+    }
+  });
+});
+// Returns the waiting test and retest recommendations.
+const getRecs = exports.getRecs = async () => {
+  let recs;
+  let recsJSON;
+  try {
+    recsJSON = await fs.readFile(recsPath, 'utf8');
   }
-  const issuelessRules = Array.from(unclassifiableRules).sort();
-  // Update the issueless rules in the report.
-  report.jobData.issuelessRules = issuelessRules;
-  // If any rules were unclassifiable:
-  if (issuelessRules.length) {
-    // Alert a manager about them.
-    await sendAlert(
-      'Kilotest: unclassified rules violated',
-      `Job ${timeStamp}-${jobID}: Violated rules in no issues:\n${issuelessRules.join('\n')}`
-    );
-  }
-  // Save the annotated report.
-  await fs.writeFile(getReportPath(timeStamp, jobID), getJSON(report));
-  // Get a copy of the log of the report.
-  const log = await getLog(timeStamp, jobID, false);
-  // If this failed:
-  if (log.error) {
-    // Return why.
-    return log.error;
+  catch(error) {
+    await fs.writeFile(recsPath, '{}\n');
+    return `ERROR: recommendations file not readable, so created an empty one (${error.message})`;
   }
-  // Otherwise, i.e. if it succeeded:
-  else {
-    // Mark the report as annotated in the log.
-    log.annotated = true;
-    // Save the revised log.
-    await fs.writeFile(getLogPath(timeStamp, jobID), getJSON(log));
-    // Return success.
-    return '';
+  try {
+    recs = JSON.parse(recsJSON);
   }
-};
-// Returns a report log after conditionally annotating it.
-const getLog = exports.getLog = async (timeStamp, jobID, annotate = false) => {
-  const log = await getRecord('log', timeStamp, jobID);
-  if (annotate && ! (log.error || log.annotated)) {
-    await annotateReport(ruleIDs, timeStamp, jobID);
+  catch(error) {
+    return `ERROR: recommendations file not JSON (${error.message})`;
   }
-  return log;
+  return recs;
 };
-// Returns whether a report is hidden.
-exports.isHidden = async (timeStamp, jobID) => {
-  // Get the log of the report.
-  const log = await getLog(timeStamp, jobID, false);
-  // Return whether the log exists and its report is hidden.
-  return !! log.hidden;
-};
-// Returns summary data on a report.
-exports.getReportData = async (timeStamp, jobID) => {
-  // Validate the report and annotate it if necessary.
-  const log = await getLog(timeStamp, jobID, true);
-  // If this failed:
-  if (log.error) {
-    // Return why.
-    return {error: log.error};
-  }
-  // Initialize the data.
-  const data = {
-    what: log.what,
-    url: log.url,
-    jobName: `${timeStamp}-${jobID}`,
-    creationDate: getDateTime(timeStamp),
-    daysAgo: getAgoDays(timeStamp),
-    issueCount: 0,
-    toolNames: [],
-    toolCount: 0,
-    reporterNames: [],
-    reporterCount: 0,
-    violatorCount: 0,
-    preventedToolNames: [],
-    preventedToolCount: 0
-  };
-  const issueIDSet = new Set();
-  const toolNameSet = new Set();
-  const reporterIDSet = new Set();
-  const violatorIndexSet = new Set();
-  // Get the report.
-  const report = await getReport(timeStamp, jobID);
-  // If this failed:
-  if (report.error) {
-    // Return why.
-    return {error: report.error};
-  }
-  // For each act of the report:
-  report.acts.forEach(act => {
-    // If it is a test act:
-    if (act.type === 'test') {
-      const {result, which} = act;
-      // Ensure that the tool is in the temporary data.
-      toolNameSet.add(tools[which][0]);
-      const instances = result?.standardResult?.instances ?? [];
-      // For each standard instance of the act:
-      instances.forEach(instance => {
-        const {catalogIndex, issueID} = instance;
-        // If it has a non-ignorable classified issue ID:
-        if (issueID && issuesClassification[issueID] && issueID !== 'ignorable') {
-          // Ensure that the tool is in the temporary data.
-          reporterIDSet.add(which);
-          // Ensure that the issue is in the temporary data.
-          issueIDSet.add(issueID);
-          // If the violator has a catalog index:
-          if (catalogIndex) {
-            // Ensure that the violator is in the temporary data.
-            violatorIndexSet.add(catalogIndex);
-          }
-        }
-      });
-    }
-  });
-  // Populate the data with the act data.
-  data.issueCount = issueIDSet.size;
-  data.toolNames = Array
-  .from(toolNameSet)
-  .sort((a, b) => a.localeCompare(b, 'en', {sensitivity: 'base'}));
-  data.toolCount = toolNameSet.size;
-  data.reporterNames = Array
-  .from(reporterIDSet)
-  .map(id => tools[id][0])
-  .sort((a, b) => a.localeCompare(b, 'en', {sensitivity: 'base'}));
-  data.reporterCount = data.reporterNames.length;
-  data.violatorCount = violatorIndexSet.size;
-  // Add the names of any prevented rule engines to the data.
-  data.preventedToolNames = Object.keys(report.jobData?.preventions || {})
-  .map(toolID => tools[toolID][0])
-  .sort((a, b) => a.localeCompare(b, 'en', {sensitivity: 'base'}));
-  data.preventedToolCount = data.preventedToolNames.length;
-  // Return the data.
-  return data;
-}
-// Returns a time stamp from a date.
-const getTimeStamp = exports.getTimeStamp = date => {
-  const timeStamp = date.toISOString().slice(2).replace(/[-:]/g, '').slice(0, 11);
-  return timeStamp;
-};
-// Gets the names and categories of the job files.
-const getJobNames = exports.getJobNames = async () => {
-  const jobNames = {};
-  let fileNames;
-  for (const category of ['queue', 'claimed', 'failed']) {
-    try {
-      fileNames = await fs.readdir(path.join(jobsPath, category));
-    }
-    catch(error) {
-      return `ERROR: Job directory ${category} not readable (${error.message})`;
-    }
-    jobNames[category] = fileNames;
-  }
-  return jobNames;
-}
-// Returns an object from a JSON file.
-const getObject = exports.getObject = async filePath => {
-  let fileContent, object;
-  try {
-    fileContent = await fs.readFile(filePath, 'utf8');
-  }
-  catch(error) {
-    return `ERROR: File ${filePath} not readable (${error.message})`;
-  }
-  try {
-    object = JSON.parse(fileContent);
-  }
-  catch(error) {
-    return `ERROR: File ${filePath} not JSON (${error.message})`;
-  }
-  return object;
-};
-// Returns a string describing the time in days since a time stamp.
-exports.getAgoString = timeStamp => {
-  const agoDays = getAgoDays(timeStamp);
-  return agoDays === 1 ? '1 day' : `${agoDays} days`;
-};
-// Returns a date-and-time string.
-const getDateTimeString = exports.getDateTimeString = timeStamp => {
-  const dateString = getDateString(timeStamp);
-  const timeString = getTimeString(timeStamp);
-  const dateTimeString = `${dateString} at ${timeString}`;
-  return dateTimeString;
-}
-// Returns the path ID of the element of a standard instance.
-exports.getPathID = (catalog, catalogIndex, pathID) => {
-  if (catalogIndex) {
-    const catalogItem = catalog[catalogIndex] || {};
-    if (catalogItem.pathID) {
-      return catalogItem.pathID;
-    }
-    return pathID ?? '/html';
-  }
-  return pathID ?? '/html';
-};
-// Returns the data from a POST request.
-exports.getPOSTData = request => new Promise(resolve => {
-  const bodyParts = [];
-  request.on('data', chunk => {
-    bodyParts.push(chunk);
-  });
-  request.on('end', () => {
-    const contentType = request.headers['content-type'];
-    if (contentType.startsWith('application/json')) {
-      const bodyJSON = bodyParts.join('');
-      const body = JSON.parse(bodyJSON);
-      resolve(body);
-    }
-    else if (contentType.startsWith('application/x-www-form-urlencoded')) {
-      const body = bodyParts.join('');
-      const query = querystring.parse(body);
-      resolve(query);
-    }
-  });
-});
-// Returns the waiting test and retest recommendations.
-const getRecs = exports.getRecs = async () => {
-  let recs;
-  let recsJSON;
-  try {
-    recsJSON = await fs.readFile(recsPath, 'utf8');
-  }
-  catch(error) {
-    await fs.writeFile(recsPath, '{}\n');
-    return `ERROR: recommendations file not readable, so created an empty one (${error.message})`;
-  }
-  try {
-    recs = JSON.parse(recsJSON);
-  }
-  catch(error) {
-    return `ERROR: recommendations file not JSON (${error.message})`;
-  }
-  return recs;
+// Converts a catalog item text to a text-fragment link destination.
+exports.getTextFragmentHref = (text, url) => {
+  const fragmentList = text
+  .split('\n')
+  .map(fragment => fragmentEncode(fragment))
+  .join(',');
+  // Return a text-fragment link.
+  return `${url}#:~:text=${fragmentList}`;
 };
+// Returns a +-delimited list of sorted names of rule engines.
+exports.getToolList = toolIDs => Array.from(toolIDs)
+.map(toolID => tools[toolID][0])
+.sort((a, b) => a.localeCompare(b, 'en', {sensitivity: 'base'}))
+.join(' + ');
 // Returns a string of names of rule engines.
 exports.getToolNamesString = toolIDSet =>
   alphaSort(Array.from(toolIDSet).map(toolID => tools[toolID]?.[0] || toolID)).join(' + ');
-// Converts a catalog item text to a text-fragment link destination.
-exports.getTextFragmentHref = (text, url) => {
-  const fragmentList = text
-  .split('\n')
-  .map(fragment => fragmentEncode(fragment))
-  .join(',');
-  // Return a text-fragment link.
-  return `${url}#:~:text=${fragmentList}`;
-};
-// Returns a sorted array of the logs, with job names added, of the non-hidden reports.
-const getLogs = exports.getLogs = async () => {
-  // Initialize data on the tested targets.
-  const logs = [];
-  let logFileNames;
-  try {
-    logFileNames = await fs.readdir(logsPath);
-  }
-  catch {
-    console.error('Logs directory not readable');
-    logFileNames = [];
-  }
-  // For each log:
-  for (const fileName of logFileNames) {
-    const logName = fileName.slice(0, -5);
-    const [timeStamp, jobID] = logName.split('-');
-    // Get it.
-    const log = await getLog(timeStamp, jobID);
-    // If this failed:
-    if (log.error) {
-      // Report why.
-      console.error(log.error);
-    }
-    // Otherwise, i.e. if it succeeded:
-    else {
-      // If the report is not hidden:
-      if (! log.hidden) {
-        // Add the job name to the log.
-        log.jobName = logName;
-        // Add the log to the logs.
-        logs.push(log);
-      }
-    }
-  }
-  // Sort the logs by target name and secondarily by test time.
-  logs.sort((a, b) => {
-    // During the sort, if the jobs tested the same target:
-    if (b.what === a.what) {
-      // Add to the earlier log the fact that its report has been superseded.
-      if (a.jobName < b.jobName) {
-        a.superseded = true;
-        return 1;
-      }
-      b.superseded = true;
-      return -1;
-    }
-    return a.what.localeCompare(b.what, {}, {sensitivity: 'base'});
-  });
-  // Return them.
-  return logs;
+// Gets the WCAG Understanding link for a numeric WCAG standard identifier.
+exports.getWCAGLink = numericID => {
+  // Return the link.
+  return `https://www.w3.org/WAI/WCAG22/Understanding/${wcagMap[numericID]}`;
 };
 // Gets the name of an issue weight.
 exports.getWeightName = weight => ['lowest', 'low', 'high', 'highest'][weight - 1] ?? 'unknown';
@@ -609,7 +359,7 @@ exports.isRecommendable = async url => {
 };
 // Returns whether a string is a time stamp.
 exports.isTimeStamp = string => {
-  return !! getDateString(string);
+  return !!getDateString(string);
 };
 // Returns whether a string is a URL.
 const isURL = exports.isURL = string => {
@@ -621,26 +371,29 @@ const isURL = exports.isURL = string => {
 };
 // Makes a string breakable before non-initial slashes.
 exports.makeBreakable = string => string.replace(/\//g, '<wbr>/').replace(/^<wbr>/, '');
-// Converts a string to a plain-text 1-line ASCII string.
-const getPlainText = string => string.replace(/&/g, '+').replace(/[<>"'&]/g, ' ');
-// Returns a time stamp for now.
-const getNowStamp = exports.getNowStamp = () => {
-  return getTimeStamp(new Date());
-};
-// Updates the test recommendations.
-const updateRecs = exports.updateRecs = async (what, url, why) => {
-  // Get the data on waiting recommendations.
-  const recs = await getRecs();
-  recs[url] ??= [];
-  // Add the recommendation to those for the target.
-  recs[url].push({
-    timeStamp: getNowStamp(),
-    what,
-    why
-  });
-  // Save the revised recommendations.
-  await fs.writeFile(recsPath, getJSON(recs));
-};
+// Minifies a URL for duplicate detection.
+const minifyURL = exports.minifyURL = url => url.replace(/www\.|\/$/g, '').toLowerCase();
+// Sorts objects by a property value and returns the sorted array.
+const objectSort = exports.objectSort = (objects, property, sortType) => objects
+.sort((a, b) => {
+  // If the property values are numbers to be sorted in increasing order:
+  if (sortType === 'numericUp') {
+    // Sort by increasing numeric value.
+    return a[property] - b[property];
+  }
+  // Otherwise, if they are numbers to be sorted in decreasing order:
+  else if (sortType === 'numericDown') {
+    // Sort by decreasing numeric value.
+    return b[property] - a[property];
+  }
+  // Otherwise, if they are strings to be sorted alphabetically:
+  else if (sortType === 'alpha') {
+    // Sort alphabetically.
+    return alphaCompare(a[property], b[property]);
+  }
+  // Otherwise, do not sort.
+  return 0;
+});
 // Processes a test or retest recommendation in the UI.
 exports.processRec = async (testType, dirName, what, url, why) => {
   // If the recommendation is valid:
@@ -653,53 +406,264 @@ exports.processRec = async (testType, dirName, what, url, why) => {
   ) {
     // Make the reason display-safe.
     const plainWhy = getPlainText(why);
-    // Update the waiting recommendations.
-    await updateRecs(what, url, plainWhy);
-    // Log the recommendation.
-    console.log(`Test recommendation received for ${what}: ${plainWhy}`);
-    // Alert a manager about it.
-    await sendAlert(
-      `Kilotest: new ${testType} recommendation in the UI`,
-      `Target: ${what}\nURL: ${url}\nReason: ${plainWhy}`
-    );
-    // Get the template.
-    let answerPage = await fs.readFile(path.join(dirName, 'index.html'), 'utf8');
-    const query = {
-      target: what,
-      why: plainWhy
-    };
-    // Replace its placeholders.
-    Object.keys(query).forEach(param => {
-      answerPage = answerPage.replace(new RegExp(`__${param}__`, 'g'), query[param]);
-    });
-    // Return the populated page.
-    return {
-      status: 'ok',
-      answerPage
-    };
+    // Update the waiting recommendations as a transaction.
+    const updateResult = await updateRecs(what, url, plainWhy);
+    // If the recommendation was a duplicate:
+    if (updateResult.error === 'duplicate') {
+      // Return this.
+      return {
+        status: 'error',
+        message: 'Duplicate recommendation'
+      };
+    }
+    // Otherwise, i.e. if it was not a duplicate:
+    else {
+      // Log the recommendation.
+      console.log(`Test recommendation received for ${what}: ${plainWhy}`);
+      // Alert a manager about it.
+      await sendAlert(
+        `Kilotest: new ${testType} recommendation in the UI`,
+        `Target: ${what}\nURL: ${url}\nReason: ${plainWhy}`
+      );
+      // Get the template.
+      let answerPage = await fs.readFile(path.join(dirName, 'index.html'), 'utf8');
+      const query = {
+        target: what,
+        why: plainWhy
+      };
+      // Replace its placeholders.
+      Object.keys(query).forEach(param => {
+        answerPage = answerPage.replace(new RegExp(`__${param}__`, 'g'), query[param]);
+      });
+      // Return the populated page.
+      return {
+        status: 'ok',
+        answerPage
+      };
+    }
   }
   return {
     status: 'error',
     message: 'Invalid recommendation'
   };
 };
-// Gets the WCAG Understanding link for a numeric WCAG standard identifier.
-exports.getWCAGLink = numericID => {
-  // Return the link.
-  return `https://www.w3.org/WAI/WCAG22/Understanding/${wcagMap[numericID]}`;
+// Concurrency lock for the `recs.json` file.
+const recsLock = exports.recsLock = createLock();
+// Variable and invariant rules.
+exports.ruleIDs = getRuleIDs();
+// Updates the test recommendations as a transaction.
+const updateRecs = exports.updateRecs = (what, url, why) => recsLock(async () => {
+  // Get the data on waiting recommendations.
+  const recs = await getRecs();
+  recs[url] ??= [];
+  // If any recommendation has the same description and URL:
+  if (recs[url].some(rec => rec.what === what)) {
+    // Return this.
+    return {
+      error: 'duplicate'
+    };
+  }
+  // Otherwise, i.e. if the recommendation is not a duplicate, add it to those for the target.
+  recs[url].push({
+    timeStamp: getNowStamp(),
+    what,
+    why
+  });
+  // Save the revised recommendations.
+  await fs.writeFile(recsPath, getJSON(recs));
+  // Return success.
+  return {};
+});
+
+// REPORT FUNCTIONS
+
+// Returns the path ID of the element of a standard instance.
+exports.getPathID = (catalog, catalogIndex, pathID) => {
+  if (catalogIndex) {
+    const catalogItem = catalog[catalogIndex] || {};
+    if (catalogItem.pathID) {
+      return catalogItem.pathID;
+    }
+    return pathID ?? '/html';
+  }
+  return pathID ?? '/html';
+};
+// Returns the path of an available report file.
+const getReportPath = exports.getReportPath = (timeStamp, jobID) => path
+.join(reportsPath, `${timeStamp}-${jobID}.json`);
+// Returns whether a report is valid.
+const isValidReport = exports.isValidReport = report => {
+  // Return whether it has the type and properties required by Kilotest:
+  return typeof report === 'object'
+  && typeof report.target?.what === 'string'
+  && typeof report.target?.url === 'string'
+  && Array.isArray(report.acts)
+  && report.acts.every(act =>
+    typeof act === 'object'
+    && typeof act.type === 'string'
+    && act.type === 'test' ? Object.keys(tools).includes(act.which) : true
+  )
+  && typeof report.jobData === 'object'
+  && report.jobData.endTime
+  && !isNaN(new Date(`20${report.jobData.endTime}Z`).getTime())
+  && typeof report.catalog === 'object';
+};
+// Returns a report.
+const getReport = exports.getReport = async (timeStamp, jobID) => {
+  try {
+    const reportJSON = await fs.readFile(getReportPath(timeStamp, jobID), 'utf8');
+    const report = JSON.parse(reportJSON);
+    // If it is valid:
+    if (isValidReport(report)) {
+      // Return it.
+      return report;
+    }
+    // Otherwise, i.e. if it is invalid, return this.
+    return {error: `Report ${timeStamp}-${jobID} is invalid`};
+  } catch (error) {
+    return {error: `Report ${timeStamp}-${jobID} is missing, unreadable, or not JSON (${error.message})`};
+  }
+};
+// Adds issue IDs to the standard instances of a report.
+exports.annotateReport = async (ruleIDs, timeStamp, jobID) => {
+  // Get a copy of the report.
+  const report = await getReport(timeStamp, jobID);
+  // If this failed:
+  if (report.error) {
+    // Return why.
+    return report.error;
+  }
+  // Otherwise, i.e. if it succeeded:
+  const unclassifiableRules = new Set();
+  // For each of its acts:
+  for (const act of report.acts) {
+    const {result, type, which} = act;
+    // If it is a test act:
+    if (type === 'test') {
+      // For each standard instance of the result:
+      for (const instance of result?.standardResult?.instances ?? []) {
+        const {ruleID} = instance;
+        // Classify its rule.
+        const issueID = getIssue(ruleIDs, which, ruleID);
+        // If the rule was classifiable:
+        if (issueID) {
+          // Add the issue ID to the instance.
+          instance.issueID = issueID;
+        }
+        // Otherwise, i.e. if it was not classifiable:
+        else {
+          // Add it to the set of unclassifiable rules.
+          unclassifiableRules.add(`${which}:${ruleID}`);
+          // Remove any existing issue ID from the instance.
+          delete instance.issueID;
+        }
+      }
+    }
+  }
+  const issuelessRules = Array.from(unclassifiableRules).sort();
+  // Update the issueless rules in the report.
+  report.jobData.issuelessRules = issuelessRules;
+  // If any rules were unclassifiable:
+  if (issuelessRules.length) {
+    // Alert a manager about them.
+    await sendAlert(
+      'Kilotest: unclassified rules violated',
+      `Job ${timeStamp}-${jobID}: Violated rules in no issues:\n${issuelessRules.join('\n')}`
+    );
+  }
+  // Save the annotated report.
+  await fs.writeFile(getReportPath(timeStamp, jobID), getJSON(report));
+  // Return success.
+  return '';
 };
-// Returns page data from a report.
+// Returns summary data on an available report.
+exports.getReportData = async (timeStamp, jobID) => {
+  // Get the report.
+  const report = await getReport(timeStamp, jobID);
+  // If this failed:
+  if (report.error) {
+    // Return why.
+    return {error: report.error};
+  }
+  // Otherwise, i.e. if it succeeded, initialize the data.
+  const data = {
+    what: report.target.what,
+    url: report.target.url,
+    jobName: report.id,
+    creationDate: getDateTime(timeStamp),
+    daysAgo: getAgoDays(timeStamp),
+    issueCount: 0,
+    toolNames: [],
+    toolCount: 0,
+    reporterNames: [],
+    reporterCount: 0,
+    violatorCount: 0,
+    preventedToolNames: [],
+    preventedToolCount: 0
+  };
+  const issueIDSet = new Set();
+  const toolNameSet = new Set();
+  const reporterIDSet = new Set();
+  const violatorIndexSet = new Set();
+  // For each act of the report:
+  report.acts.forEach(act => {
+    // If it is a test act:
+    if (act.type === 'test') {
+      const {result, which} = act;
+      // Ensure that the tool is in the temporary data.
+      toolNameSet.add(tools[which][0]);
+      const instances = result?.standardResult?.instances ?? [];
+      // For each standard instance of the act:
+      instances.forEach(instance => {
+        const {catalogIndex, issueID} = instance;
+        // If it has a non-ignorable classified issue ID:
+        if (issueID && issuesClassification[issueID] && issueID !== 'ignorable') {
+          // Ensure that the tool is in the temporary data.
+          reporterIDSet.add(which);
+          // Ensure that the issue is in the temporary data.
+          issueIDSet.add(issueID);
+          // If the violator has a catalog index:
+          if (catalogIndex) {
+            // Ensure that the violator is in the temporary data.
+            violatorIndexSet.add(catalogIndex);
+          }
+        }
+      });
+    }
+  });
+  // Populate the data with the act data.
+  data.issueCount = issueIDSet.size;
+  data.toolNames = Array
+  .from(toolNameSet)
+  .sort((a, b) => a.localeCompare(b, 'en', {sensitivity: 'base'}));
+  data.toolCount = toolNameSet.size;
+  data.reporterNames = Array
+  .from(reporterIDSet)
+  .map(id => tools[id][0])
+  .sort((a, b) => a.localeCompare(b, 'en', {sensitivity: 'base'}));
+  data.reporterCount = data.reporterNames.length;
+  data.violatorCount = violatorIndexSet.size;
+  // Add the names of any prevented rule engines to the data.
+  data.preventedToolNames = Object.keys(report.jobData?.preventions || {})
+  .map(toolID => tools[toolID][0])
+  .sort((a, b) => a.localeCompare(b, 'en', {sensitivity: 'base'}));
+  data.preventedToolCount = data.preventedToolNames.length;
+  // Return the data.
+  return data;
+}
+// Returns page data from an available report.
 const getPageData = exports.getPageData = async (timeStamp, jobID) => {
-  // Get the log of the report.
-  const log = await getLog(timeStamp, jobID, false);
+  // Get the report.
+  const report = await getReport(timeStamp, jobID);
   // If this failed:
-  if (log.error) {
+  if (report.error) {
     // Return why.
-    return log;
+    return report;
   }
-  const {url, what} = log;
-  // Otherwise, i.e. if it succeeded, get the elapsed time in days since the test.
-  const daysAgo = getAgoDays(timeStamp);
+  const {url, what} = report.target;
+  const reportStats = await getReportStats(timeStamp, jobID)
+  // Otherwise, i.e. if it succeeded, get the elapsed time in days since the report was created.
+  const daysAgo = getAgoDays(reportStats.reportTime);
   // Return the data.
   return {
     what,
@@ -710,7 +674,7 @@ const getPageData = exports.getPageData = async (timeStamp, jobID) => {
 // Gets HTML strings for page data from a report.
 exports.getPageDataStrings = async (timeStamp, jobID, pageData) => {
   // If the page data were not specified:
-  if (! pageData) {
+  if (!pageData) {
     // Get them.
     pageData = await getPageData(timeStamp, jobID);
   }
@@ -732,56 +696,134 @@ exports.getPageDataStrings = async (timeStamp, jobID, pageData) => {
     testInfo: `Tested ${daysAgo} days ago by job <code>${jobID}</code> on ${when}`
   };
 };
-// Returns data about rule engines sorted by their names.
-const getToolsData = exports.getToolsData = toolIDs => objectSort(
-  Array.from(toolIDs).map(toolID => {
-    const toolData = tools[toolID];
-    return {
-      toolID,
-      toolName: toolData[0],
-      toolMaker: toolData[1]
-    }
-  }),
-  'toolName',
-  'alpha'
-);
-// Returns a +-delimited list of sorted names of rule engines.
-exports.getToolList = toolIDs => Array.from(toolIDs)
-.map(toolID => tools[toolID][0])
-.sort((a, b) => a.localeCompare(b, 'en', {sensitivity: 'base'}))
-.join(' + ');
-// Returns facts about rule engines.
-exports.getToolsFacts = toolIDs => {
-  const crypticData = getToolsData(toolIDs);
-  return crypticData.map(tool => {
-    const {toolID, toolName, toolMaker} = tool;
-    return {
-      identifier: toolID,
-      name: toolName,
-      sponsor: toolMaker
-    };
-  });
-};
-// Returns a string describing a count.
-exports.getCountString = (count, singular, plural) => count === 1 ? `1 ${singular}` : `${count} ${plural}`;
-// Minifies a URL for duplicate detection.
-const minifyURL = exports.minifyURL = url => url.replace(/www\.|\/$/g, '').toLowerCase();
-// Returns whether a report about the specified page is already available.
-exports.isReportAvailable = async (what, url) => {
-  const logs = await getLogs();
-  const whats = logs.map(log => log.what);
-  const miniURLs = logs.map(log => minifyURL(log.url));
-  return whats.includes(what) || miniURLs.includes(minifyURL(url));
-};
-// Returns the size of a report.
-exports.getReportSize = async (timeStamp, jobID) => {
+// Returns the creation time and size of a report.
+const getReportStats = exports.getReportStats = async (timeStamp, jobID) => {
   const reportStat = await fs.stat(
     path.join(reportsPath, `${timeStamp}-${jobID}.json`),
     {throwIfNoEntry: false}
   );
-  if (! reportStat) {
-    return 0;
+  if (!reportStat) {
+    return null;
   }
+  const reportTime = reportStat.birthtime;
   const reportSize = reportStat.size;
-  return reportSize;
+  return {reportTime, reportSize};
+};
+// Returns whether a report is hidden.
+exports.isHidden = async (timeStamp, jobID) => {
+  await fs.mkdir(hiddenReportsPath, {recursive: true});
+  // Get the names of the hidden report files.
+  const hiddenReportFileNames = await fs.readdir(hiddenReportsPath);
+  // Return whether the report is among them.
+  return hiddenReportFileNames.includes(`${timeStamp}-${jobID}.json`);
+};
+// Creates, saves, and returns an extract of all available reports.
+const makeReportsExtract = exports.makeReportsExtract = async () => {
+  // Initialize the reports data.
+  const reportsExtract = {};
+  // Get the names of all report files.
+  const reportFileNames = await fs.readdir(reportsPath);
+  // For each of them:
+  for (const reportFileName of reportFileNames) {
+    // Get its content.
+    const reportJSON = await fs.readFile(path.join(reportsPath, reportFileName), 'utf8');
+    // Get the object that it represents.
+    const report = JSON.parse(reportJSON);
+    const {target, jobData} = report;
+    const jobName = reportFileName.slice(0, -5);
+    const [timeStamp, jobID] = jobName.split('-');
+    const {what, url} = target;
+    // Get an extract from it.
+    const reportExtract = {
+      timeStamp,
+      jobID,
+      what,
+      url,
+      reportTime: new Date(`20${jobData.endTime}Z`).toISOString()
+    };
+    // Add the report extract to the reports extract.
+    reportsExtract[jobName] = reportExtract;
+  }
+  // Ensure the data directory exists.
+  await fs.mkdir(dbPath, {recursive: true});
+  // Save the extract of the reports.
+  await fs.writeFile(reportsExtractPath, getJSON(reportsExtract));
+  // Return it.
+  return reportsExtract;
+};
+// Gets an extract of all available reports.
+const getReportsExtract = exports.getReportsExtract = async () => {
+  let reportsExtract;
+  try {
+    // Get the reports extract file.
+    const reportsExtractJSON = await fs.readFile(reportsExtractPath, 'utf8');
+    // Get its data.
+    reportsExtract = JSON.parse(reportsExtractJSON);
+    // If it is empty:
+    if (!Object.keys(reportsExtract).length) {
+      // Throw an error.
+      throw new Error('Reports extract file is empty');
+    }
+  }
+  // If this fails:
+  catch {
+    // Create or recreate and get the reports extract.
+    reportsExtract = await makeReportsExtract();
+  }
+  // Return the extract.
+  return reportsExtract;
+};
+// Returns extracts of all available reports.
+const getReportExtracts = exports.getReportExtracts = async () => {
+  const reportsExtract = await getReportsExtract();
+  return Object.values(reportsExtract);
+};
+// Returns whether a report is available on a page with a description or URL.
+exports.isReportAvailable = async (what, url) => {
+  const reportExtracts = await getReportExtracts();
+  const whats = reportExtracts.map(reportExtract => reportExtract.what);
+  const miniURLs = reportExtracts.map(reportExtract => minifyURL(reportExtract.url));
+  return whats.includes(what) || miniURLs.includes(minifyURL(url));
+};
+// Gets extracts of the latest available reports for all page descriptions.
+exports.getLatestReportExtracts = async () => {
+  // Get extracts of all available reports.
+  const reportExtracts = await getReportExtracts();
+  // Sort them primarily by page description and secondarily by completion time.
+  objectSort(reportExtracts, 'reportTime', 'alpha');
+  objectSort(reportExtracts, 'what', 'alpha');
+  // Get the latest ones for all page descriptions.
+  const latestReportExtracts = reportExtracts
+  .filter((extract, index) => extract.what !== reportExtracts[index + 1]?.what);
+  // Return them.
+  return latestReportExtracts;
+};
+// Returns an extract of an available report.
+exports.getReportExtract = async (timeStamp, jobID) => {
+  // Get the extract of all available reports.
+  const reportsExtract = await getReportsExtract();
+  // Get the extract of the report from it.
+  const reportExtract = reportsExtract[`${timeStamp}-${jobID}`];
+  // If it exists:
+  if (reportExtract) {
+    // Return it.
+    return reportExtract;
+  }
+  // Otherwise, i.e. if it does not exist, return this.
+  return {
+    error: `No report ${timeStamp}-${jobID} is available`
+  };
+};
+// Gets the descriptions of multi-report pages.
+exports.getMultiReportWhats = async () => {
+  // Get extracts of all available reports.
+  const reportExtracts = await getReportExtracts();
+  // Get their sorted page descriptions.
+  const sortedWhats = reportExtracts.map(extract => extract.what).sort();
+  // Get those that at least 2 reports have.
+  const multiReportWhats = sortedWhats.filter(
+    (what, index) => what !== sortedWhats[index - 1] && what === sortedWhats[index + 1]
+  );
+  // Return an array of descriptions of multi-report pages.
+  return multiReportWhats;
 };