@jrpool/kilotest 37.0.0 → 38.0.0

package/target/api.js

@@ -21,9 +21,10 @@ const thisHost = process.env.THIS_KILOTEST_HOST;
 
 // Returns a response to a target request.
 exports.response = async args => {
-  const [what = '', hostname = ''] = args;
+  const [description = '', hostname = ''] = args;
   const hostLC = hostname.toLowerCase();
-  const whatLC = what.toLowerCase();
+  const whatLC = description.toLowerCase();
+  // Initialize an array of summaries of matching reports.
   const matchingReports = [];
   // Get the non-hidden logs.
   const targetLogs = await getLogs();
@@ -42,6 +43,7 @@ exports.response = async args => {
       // Get data about its report.
       const data = await getReportData(timeStamp, jobID);
       const {
+        error,
         creationDate,
         daysAgo,
         issueCount,
@@ -53,35 +55,44 @@ exports.response = async args => {
         preventedToolNames,
         preventedToolCount
       } = data;
-      matchingReports.push({
-        identifier: jobName,
-        'creation date': creationDate,
-        'days since the creation date': daysAgo,
-        'tested web page': {
-          description: reportWhat,
-          URL: reportURL
-        },
-        'whether a later report about the same page exists': !! superseded,
-        'rule engines that tried to test the page': {
-          number: toolCount,
-          names: toolNames
-        },
-        'rule engines that were unable to test the page': {
-          number: preventedToolCount,
-          names: preventedToolNames
-        },
-        'rule engines that reported issues': {
-          number: reporterCount,
-          names: reporterNames
-        },
-        'number of issues reported': issueCount,
-        'number of HTML elements reported as exhibiting issues': violatorCount,
-        'URLs for getting data about the reported issues': {
-          'for you': `${thisHost}/api/reportIssues/${timeStamp}/${jobID}`,
-          'for humans': `${thisHost}/reportIssues.html/${timeStamp}/${jobID}`
-        },
-        'URL for getting the full technical report as JSON': `${thisHost}/fullReport.json/${timeStamp}/${jobID}`
-      });
+      // If this failed:
+      if (error) {
+        // Report why.
+        console.error(error);
+      }
+      // Otherwise, i.e. if it succeeded:
+      else {
+        // Add a report summary to the array.
+        matchingReports.push({
+          identifier: jobName,
+          'creation date': creationDate,
+          'days since the creation date': daysAgo,
+          'tested web page': {
+            description: reportWhat,
+            URL: reportURL
+          },
+          'whether a later report about the same page exists': !! superseded,
+          'rule engines that tried to test the page': {
+            number: toolCount,
+            names: toolNames
+          },
+          'rule engines that were unable to test the page': {
+            number: preventedToolCount,
+            names: preventedToolNames
+          },
+          'rule engines that reported issues': {
+            number: reporterCount,
+            names: reporterNames
+          },
+          'number of issues reported': issueCount,
+          'number of HTML elements reported as exhibiting issues': violatorCount,
+          'URLs for getting data about the reported issues': {
+            'for you': `${thisHost}/api/reportSummary/${timeStamp}/${jobID}`,
+            'for humans': `${thisHost}/reportIssues.html/${timeStamp}/${jobID}`
+          },
+          'URL for getting the full technical report as JSON': `${thisHost}/fullReport.json/${timeStamp}/${jobID}`
+        });
+      }
     }
   }
   // Get a response.
@@ -96,12 +107,12 @@ exports.response = async args => {
       },
       method: 'POST',
       payload: {
-        'all or part of a description of the web page': what,
-        'all or part of the hostname of the URL of the web page': hostname
+        description,
+        hostname
       },
       URLs: {
-        'URL of your request': `${thisHost}/api/target`,
-        'equivalent URL for humans': 'none'
+        'for you': `${thisHost}/api/target`,
+        'for humans': 'none'
       },
       'closest ancestor request': null
     },

package/targets/index.js

@@ -80,8 +80,10 @@ const populateQuery = async query => {
   for (const targetLog of targetLogs) {
     const {jobName, url, what} = targetLog;
     const [timeStamp, jobID] = jobName.split('-');
+    // Get data about its report.
     const reportData = await getReportData(timeStamp, jobID);
     const {
+      error,
       issueCount,
       preventedToolCount,
       preventedToolNames,
@@ -89,6 +91,15 @@ const populateQuery = async query => {
       reporterCount,
       violatorCount
     } = reportData;
+    // If this failed:
+    if (error) {
+      console.error(error);
+      // Populate the query with the reason.
+      query.error = error;
+      // Stop populating the query.
+      return;
+    }
+    // Otherwise, i.e. if it succeeded, add lines about the report.
     lines.tested.push(`${margin}<details>`);
     const daysAgo = getAgoDays(timeStamp);
     const pageDataStrings = await getPageDataStrings(timeStamp, jobID, {what, url, daysAgo});
@@ -155,7 +166,15 @@ exports.answer = async () => {
   const query = {};
   // Create a query to replace placeholders.
   await populateQuery(query);
-  // Get the template.
+  // If the query reports an error:
+  if (query.error) {
+    // Return it.
+    return {
+      status: 'error',
+      message: query.error
+    };
+  }
+  // Otherwise, i.e. if it does not report an error, get the template.
   let answerPage = await fs.readFile(path.join(__dirname, 'index.html'), 'utf8');
   // Replace its placeholders.
   Object.keys(query).forEach(param => {

package/testRecForm/api.js

@@ -41,8 +41,8 @@ exports.response = async (what, url, why) => {
         'reason for testing the web page': why
       },
       URLs: {
-        'URL of your request': `${thisHost}/api/testRecForm`,
-        'equivalent URL for humans': `${thisHost}/testRecForm.html`
+        'for you': `${thisHost}/api/testRecForm`,
+        'for humans': `${thisHost}/testRecForm.html`
       },
       'closest ancestor request': null
     },

package/tutorial/index.js

@@ -5,7 +5,8 @@
 
 // IMPORTS
 
-const {getJSON} = require('../util');
+const {sendAlert} = require('../alerts');
+const {getJSON, getNowStamp} = require('../util');
 const fs = require('fs/promises');
 const path = require('path');
 
@@ -31,7 +32,7 @@ exports.answer = async () => {
   };
 };
 // Sanitizes and saves a tutorial comment to comments.json.
-exports.saveComment = async content => {
+exports.handleComment = async content => {
   if (!content || typeof content !== 'string') {
     return {status: 'error', message: 'No content provided'};
   }
@@ -41,13 +42,22 @@ exports.saveComment = async content => {
   }
   let comments = [];
   try {
+    // Get the existing comments.
     const existing = await fs.readFile(commentsPath, 'utf8');
     comments = JSON.parse(existing);
   }
-  catch (_) {
-    // File absent or unparsable; start a fresh array.
+  // If there are none:
+  catch {
+    // Initialize a comments array.
   }
-  comments.push({timeStamp: new Date().toISOString(), content: sanitized});
+  // Add the comment to the existing ones.
+  comments.push({
+    timeStamp: getNowStamp(),
+    content: sanitized
+  });
+  // Save the revised comments.
   await fs.writeFile(commentsPath, getJSON(comments));
+  // Send an alert to the manager.
+  await sendAlert('New tutorial comment received', 'A new tutorial comment has been received.');
   return {status: 'ok'};
 };

package/util.js

@@ -37,6 +37,7 @@ const tools = exports.tools = {
   wave: ['WAVE', 'Utah State University'],
   wax: ['WallyAX', 'Wally']
 };
+exports.ruleEngines = tools;
 exports.researchAgents = {
   'research-agent': 'Internal Research Agent'
 }
@@ -83,7 +84,7 @@ const getRecordPath = exports.getRecordPath = (recordType, timeStamp, jobID) =>
     return null;
   }
 };
-// Returns a log or report or an error message.
+// Returns a log or report.
 const getRecord = exports.getRecord = async (recordType, timeStamp, jobID) => {
   const recordPath = getRecordPath(recordType, timeStamp, jobID);
   let recordJSON, record;
@@ -92,18 +93,18 @@ const getRecord = exports.getRecord = async (recordType, timeStamp, jobID) => {
   }
   catch(error) {
     console.log(error.message);
-    return `ERROR: Requested ${recordType} ${timeStamp}-${jobID} not found`;
+    recordJSON = JSON.stringify({error: `Requested ${recordType} ${timeStamp}-${jobID} not found`});
   }
   try {
     record = JSON.parse(recordJSON);
   }
   catch (error) {
     console.log(error.message);
-    return `ERROR: Requested ${recordType} ${timeStamp}-${jobID} not JSON`;
+    record = {error: `Requested ${recordType} ${timeStamp}-${jobID} not JSON`};
   }
   return record;
 };
-// Returns a report or an error message.
+// Returns a report.
 const getReport = exports.getReport = async (timeStamp, jobID) => await getRecord(
   'report', timeStamp, jobID
 );
@@ -246,13 +247,13 @@ const getIssue = exports.getIssue = (ruleIDs, toolID, ruleID) => {
 // 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 reportOrError = await getReport(timeStamp, jobID);
+  const report = await getReport(timeStamp, jobID);
   // If this failed:
-  if (typeof reportOrError === 'string') {
-    // Return this.
-    return reportOrError;
+  if (report.error) {
+    // Return why.
+    return report.error;
   }
-  const report = reportOrError;
+  // Otherwise, i.e. if it succeeded:
   const unclassifiableRules = new Set();
   // For each of its acts:
   for (const act of report.acts) {
@@ -293,36 +294,35 @@ const annotateReport = exports.annotateReport = async (ruleIDs, timeStamp, jobID
   // Save the annotated report.
   await fs.writeFile(getReportPath(timeStamp, jobID), getJSON(report));
   // Get a copy of the log of the report.
-  const logOrError = await getLog(timeStamp, jobID, false);
+  const log = await getLog(timeStamp, jobID, false);
   // If this failed:
-  if (typeof logOrError === 'string') {
-    // Return this.
-    return logOrError;
+  if (log.error) {
+    // Return why.
+    return log.error;
   }
   // Otherwise, i.e. if it succeeded:
   else {
-    const log = logOrError;
     // Mark the report as annotated in the log.
     log.annotated = true;
     // Save the revised log.
     await fs.writeFile(getLogPath(timeStamp, jobID), getJSON(log));
-    // Return without an error message.
+    // Return success.
+    return '';
   }
 };
-// Returns a report log after conditionally annotating it or an error message.
+// 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 (typeof log === 'object' && annotate && ! log.annotated) {
-    annotateReport(ruleIDs, timeStamp, jobID);
+  if (annotate && ! (log.error || log.annotated)) {
+    await annotateReport(ruleIDs, timeStamp, jobID);
   }
   return log;
 };
-// Returns whether a report is hidden or an error message.
+// Returns whether a report is hidden.
 exports.isHidden = async (timeStamp, jobID) => {
+  // Get the log of the report.
   const log = await getLog(timeStamp, jobID, false);
-  if (typeof log === 'string') {
-    return log;
-  }
+  // Return whether the log exists and its report is hidden.
   return !! log.hidden;
 };
 // Returns summary data on a report.
@@ -330,9 +330,9 @@ exports.getReportData = async (timeStamp, jobID) => {
   // Validate the report and annotate it if necessary.
   const log = await getLog(timeStamp, jobID, true);
   // If this failed:
-  if (typeof log === 'string') {
-    // Return this.
-    return log;
+  if (log.error) {
+    // Return why.
+    return {error: log.error};
   }
   // Initialize the data.
   const data = {
@@ -357,9 +357,9 @@ exports.getReportData = async (timeStamp, jobID) => {
   // Get the report.
   const report = await getReport(timeStamp, jobID);
   // If this failed:
-  if (typeof report === 'string') {
-    // Return this.
-    return report;
+  if (report.error) {
+    // Return why.
+    return {error: report.error};
   }
   // For each act of the report:
   report.acts.forEach(act => {
@@ -526,30 +526,31 @@ const getLogs = exports.getLogs = async () => {
   try {
     logFileNames = await fs.readdir(logsPath);
   }
-  catch(error) {
-    return `ERROR: logs directory not readable (${error.message})`;
+  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 logOrError = await getLog(timeStamp, jobID);
+    const log = await getLog(timeStamp, jobID);
     // If this failed:
-    if (typeof logOrError === 'string') {
-      // Return this.
-      return logOrError;
+    if (log.error) {
+      // Report why.
+      console.error(log.error);
     }
-    const log = logOrError;
-    // If the report is hidden:
-    if (log.hidden) {
-      // Disregard it.
-      continue;
+    // 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);
+      }
     }
-    // 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) => {
@@ -692,12 +693,12 @@ const getPageData = exports.getPageData = async (timeStamp, jobID) => {
   // Get the log of the report.
   const log = await getLog(timeStamp, jobID, false);
   // If this failed:
-  if (typeof log === 'string') {
-    // Return the error.
+  if (log.error) {
+    // Return why.
     return log;
   }
   const {url, what} = log;
-  // Get the elapsed time in days since the test.
+  // Otherwise, i.e. if it succeeded, get the elapsed time in days since the test.
   const daysAgo = getAgoDays(timeStamp);
   // Return the data.
   return {
@@ -713,7 +714,15 @@ exports.getPageDataStrings = async (timeStamp, jobID, pageData) => {
     // Get them.
     pageData = await getPageData(timeStamp, jobID);
   }
-  const {what, url, daysAgo} = pageData;
+  const {daysAgo, error, url, what} = pageData;
+  // If the page data are invalid:
+  if (error) {
+    // Return why.
+    return {
+      error
+    };
+  }
+  // Otherwise, i.e. if they are valid, get a description of the timestamp.
   const when = getDateTimeString(timeStamp);
   // Return the HTML strings.
   return {
@@ -766,7 +775,13 @@ exports.isReportAvailable = async (what, url) => {
 };
 // Returns the size of a report.
 exports.getReportSize = async (timeStamp, jobID) => {
-  const reportStat = await fs.stat(path.join(reportsPath, `${timeStamp}-${jobID}.json`));
+  const reportStat = await fs.stat(
+    path.join(reportsPath, `${timeStamp}-${jobID}.json`),
+    {throwIfNoEntry: false}
+  );
+  if (! reportStat) {
+    return 0;
+  }
   const reportSize = reportStat.size;
   return reportSize;
 };

package/reportIssues/api.js

@@ -1,129 +0,0 @@
-/*
-  api.js
-  Responds to the report-issues request.
-*/
-
-// IMPORTS
-
-const {getData} = require('./util');
-const {
-  getDateTime,
-  getNowStamp,
-  getRandomString,
-  getToolsFacts,
-  isHidden,
-  tools
-} = require('../util');
-
-// FUNCTIONS
-
-// Gets facts about an issue.
-const getIssueFacts = (thisHost, timeStamp, jobID, issue) => {
-  const {issueID, reporterCount, reporters, summary, violatorCount, wcag, why} = issue;
-  const wcagType = wcag.length === 3 ? 'guideline' : 'success criterion';
-  return {
-    identifier: issueID,
-    summary,
-    'related WCAG 2.2 standard': {
-      layer: wcagType,
-      'numeric identifier': wcag
-    },
-    'impact on a user': why,
-    'rule engines reporting the issue': {
-      'number': reporterCount,
-      'names': reporters.map(tool => tool.toolName)
-    },
-    'number of HTML elements reported as exhibiting the issue': violatorCount,
-    'URLs for details about the issue on the page': {
-      'for you': `${thisHost}/api/reportIssue/${issueID}/${timeStamp}/${jobID}`,
-      'for humans': `${thisHost}/reportIssue.html/${issueID}/${timeStamp}/${jobID}`
-    }
-  };
-};
-// Returns a response to a report-issues request.
-exports.response = async args => {
-  const [timeStamp, jobID] = args;
-  const reportIsHidden = await isHidden(timeStamp, jobID);
-  // If the report is not available:
-  if (reportIsHidden) {
-    return {
-      status: 'error',
-      message: 'Report not available'
-    };
-  }
-  // Otherwise, i.e. if the report is available, get data on the target and issues.
-  const data = await getData(timeStamp, jobID);
-  const {pageData, issuesData} = data;
-  const {what, url, daysAgo} = pageData;
-  const {issueCount, issues, preventions, reporterCount, reporters, violatorCount} = issuesData;
-  const preventedTools = Object.entries(preventions).map(prevention => ({
-    name: tools[prevention[0]][0],
-    'reason for failure': prevention[1]
-  }));
-  const thisHost = process.env.THIS_KILOTEST_HOST;
-  // Get a response.
-  const content = {
-    summary: `This document fulfills a request made by a language model to a Kilotest tool. The model requested data from a Kilotest report about the front-end quality (i.e. accessibility, usability, and standards conformity) of a web page. Kilotest, with the help of Testaro, Testilo, and an ensemble of ten rule engines, performs tests on web pages, using a combination of rule- and machine-learning-based methods, and produces reports. Kilotest exposes several API endpoints to recommend web pages for testing and to obtain information from Kilotest reports. To learn more about Kilotest and the advantages of testing with an ensemble of rule engines, visit the deployed instance of Kilotest (${process.env.DEPLOYED_KILOTEST_HOST}), which contains an introduction on its home page and a tutorial.`,
-    'tool collection name': 'Kilotest',
-    'tool name': 'describeQualityOfOneWebPage',
-    request: {
-      'type of request': {
-        identifier: 'reportIssues',
-        description: 'Describe the quality of one web page.'
-      },
-      method: 'GET',
-      URLs: {
-        'URL of your request': `${thisHost}/api/reportIssues/${timeStamp}/${jobID}`,
-        'equivalent URL for humans': `${thisHost}/reportIssues.html/${timeStamp}/${jobID}`
-      },
-      'closest ancestor request': {
-        identifier: 'getListOfAllAvailableReports',
-        description: 'Get a list of all available reports.',
-        URLs: {
-          'for you': `${thisHost}/api/reportList`,
-          'for humans': `${thisHost}/targets.html`
-        }
-      }
-    },
-    'response metadata': {
-      identifier: `${getNowStamp()}-${getRandomString(3)}`,
-      'date and time': new Date().toISOString()
-    },
-    report: {
-      identifier: `${timeStamp}-${jobID}`,
-      'creation date': getDateTime(timeStamp),
-      'days since the creation date': daysAgo
-    },
-    'tested web page': {
-      description: what,
-      URL: url
-    },
-    'rule engines that tried to test the page': getToolsFacts(Object.keys(tools)),
-    'rule engines that were unable to test the page': preventedTools,
-    'rule engines that reported issues': {
-      number: reporterCount,
-      names: reporters.map(tool => tool.toolName)
-    },
-    'number of issues reported': {
-      total: issueCount,
-      'by priority': {
-        'highest priority': issues[4].length,
-        'high priority': issues[3].length,
-        'low priority': issues[2].length,
-        'lowest priority': issues[1].length
-      }
-    },
-    'number of HTML elements reported as exhibiting issues': violatorCount,
-    'issues reported': {
-      'highest priority': issues[4]
-      .map(issue => getIssueFacts(thisHost, timeStamp, jobID, issue)),
-      'high priority': issues[3]
-      .map(issue => getIssueFacts(thisHost, timeStamp, jobID, issue)),
-      'low priority': issues[2]
-      .map(issue => getIssueFacts(thisHost, timeStamp, jobID, issue)),
-      'lowest priority': issues[1]
-      .map(issue => getIssueFacts(thisHost, timeStamp, jobID, issue))
-    }
-  };
-  return content;
-};