@jrpool/kilotest 37.1.0 → 38.1.0

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;
-};