@jrpool/kilotest 24.1.1 → 25.0.1

package/env.example

@@ -1,12 +1,23 @@
-# For a local development/test host, ENVIRONMENT=test.
-ENVIRONMENT=production
-# PROTOCOL must be http if a local dev/test host or reverse-proxied server, or otherwise https.
+# ENVIRONMENT=test for a dev/test host, =production for a deployed host.
+ENVIRONMENT=__placeholder__
+# PROTOCOL=http for a local dev/test host or reverse-proxied server, otherwise =https.
 PROTOCOL=__placeholder__
-# AUTH_CODE must be 3 characters long.
+# AUTH_CODE for manager operations; must be 3 characters long.
 AUTH_CODE=__placeholder__
+# Name of Testaro agent.
 TESTARO_AGENT=testaro-agent
-# TESTARO_AGENT_PW must be identical to NETWATCH_AUTH in the Testaro .env.
+# Testaro agent password (same as NETWATCH_AUTH in the Testaro .env.
 TESTARO_AGENT_PW=__placeholder__
+# Name of research agent (AI agent calling Kilotest as a tool).
+RESEARCH_AGENT=research-agent
+# Research agent password.
+RESEARCH_AGENT_PW=__placeholder__
+# URL of this Kilotest host.
+THIS_KILOTEST_HOST=__placeholder__
+# URL of a dev/test Kilotest host.
+LOCAL_KILOTEST_HOST=http://localhost:3000
+# URL of the deployed Kilotest host.
+DEPLOYED_KILOTEST_HOST=https://kilotest.com
 # Alert email configuration:
 MANAGER_EMAIL=__placeholder__
 ALERT_API_HOST=api.resend.com

package/index.js

@@ -67,6 +67,8 @@ const claimedPath = path.join(jobsPath, 'claimed');
 const failedPath = path.join(jobsPath, 'failed');
 const testaroAgent = process.env.TESTARO_AGENT;
 const testaroAgentPW = process.env.TESTARO_AGENT_PW;
+const researchAgent = process.env.RESEARCH_AGENT;
+const researchAgentPW = process.env.RESEARCH_AGENT_PW;
 // Values that may require alerts.
 const balancePath = path.join(__dirname, 'aiService0Balance.json');
 const WAVE_THRESHOLD = Number(process.env.WAVE_BALANCE_THRESHOLD);
@@ -76,21 +78,29 @@ const AI_MODEL0_OUTPUT_PRICE = Number(process.env.AI_MODEL0_OUTPUT_PRICE);
 
 // FUNCTIONS
 
-// Serves an error message.
+// Serves or sends an error message.
 const serveError = async (error, response, isHumanUser = true) => {
-  console.log(error.message);
+  console.log(error.message || 'ERROR');
   if (! response.writableEnded) {
     response.statusCode = 400;
+    // If the request is from a human user:
     if (isHumanUser) {
+      // Serve an HTML page containing the message property of the error.
       response.setHeader('content-type', 'text/html; charset=utf-8');
       const errorTemplate = await fs.readFile('error.html', 'utf8');
-      const errorPage = errorTemplate.replace(/__error__/, error.message);
+      const errorPage = errorTemplate.replace(/__error__/, error.message || 'ERROR');
       response.end(errorPage);
-    } else {
+    }
+    // Otherwise, i.e. if it is from an agent:
+    else {
+      // Send a JSON response containing the entire error.
       response.setHeader('content-type', 'application/json; charset=utf-8');
-      response.end(JSON.stringify({error: error.message}));
+      response.end(JSON.stringify({error}));
     }
   }
+  else {
+    console.log('Cannot send error response because the response has ended.');
+  }
 };
 // Checks a report for balances nearing exhaustion.
 const checkBalancesForAlerts = async report => {
@@ -107,7 +117,6 @@ const checkBalancesForAlerts = async report => {
         `Only ${creditsRemaining} WAVE credits remain (3 used per job)`
       );
     }
-    // AI service 0.
     const testaroAct = report.acts.find(act => act.type === 'test' && act.which === 'testaro');
     // Get the AI model token usage for the testaro allCaps test.
     const usage = testaroAct?.data?.ruleData?.allCaps?.aiModelUsage;
@@ -231,7 +240,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, i.e. if the request is syntactically invalid:
       else {
         // Report the error.
-        await serveError({message: 'Invalid report request'}, response, true);
+        await serveError({message: 'ERROR: Invalid report request'}, response, true);
       }
     }
     // Otherwise, if it is for an HTML page other than the home page:
@@ -258,7 +267,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, i.e. if the answer cannot be generated:
       else {
         // Report the error.
-        await serveError({message: 'Invalid request'}, response, true);
+        await serveError({message: 'ERROR: Invalid request'}, response, true);
       }
     }
     // Otherwise, if it is for a tutorial image:
@@ -274,7 +283,7 @@ const requestHandler = async (request, response) => {
         response.end(img);
       }
       catch (_) {
-        await serveError({message: 'Image not found'}, response, true);
+        await serveError({message: 'ERROR: Image not found'}, response, true);
       }
     }
     // Otherwise, if it is for the application icon:
@@ -340,7 +349,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, i.e. if the request is invalid:
       else {
         // Report the error.
-        await serveError({message: 'Invalid retest recommendation'}, response, true);
+        await serveError({message: 'ERROR: Invalid retest recommendation'}, response, true);
       }
     }
     // Otherwise, if it is a test recommendation:
@@ -368,7 +377,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, i.e. if the request is invalid:
       else {
         // Report the error.
-        await serveError({message: 'Invalid test recommendation'}, response, true);
+        await serveError({message: 'ERROR: Invalid test recommendation'}, response, true);
       }
     }
     // Otherwise, if it is an action on a test or retest recommendation:
@@ -416,7 +425,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, i.e. if the request is invalid:
       else {
         // Report the error.
-        await serveError({message: 'Invalid test order'}, response, true);
+        await serveError({message: 'ERROR: Invalid test order'}, response, true);
       }
     }
     // Otherwise, if it is a reannotation order:
@@ -459,10 +468,11 @@ const requestHandler = async (request, response) => {
         await serveError({message: answerData.error}, response, true);
       }
     }
-    // Otherwise, if it is a request from a Testaro agent:
+    // Otherwise, if it is a request from an agent:
     else if (pageName === 'api') {
-      const [agentID, service] = pageArgs.split('/');
-      // If the agent is authorized:
+      // Get the agent ID, the service, and any service specifications from the path.
+      const [agentID, service, ... specs] = pageArgs.split('/');
+      // If the agent is the authorized Testaro instance and it is authenticated:
       if (agentID === testaroAgent && postData.agentPW === testaroAgentPW) {
         // If the service is job assignment:
         if (service === 'job') {
@@ -570,9 +580,42 @@ const requestHandler = async (request, response) => {
           );
         }
       }
-      // Otherwise, i.e. if the agent is not authorized:
+      // Otherwise, if the agent is the authorized research agent and it is authenticated:
+      else if (agentID === researchAgent && postData.agentPW === researchAgentPW) {
+        // If the service is provision of facts about issues in a report:
+        if (service === 'reportIssues') {
+          // Get the report identifiers from the path.
+          const [timeStamp, jobID] = specs;
+          const args = [agentID, timeStamp, jobID];
+          const reportSpecsBad = await isHidden(timeStamp, jobID);
+          // If the report is nonexistent or hidden:
+          if (reportSpecsBad) {
+            // Report this.
+            await serveError(
+              {message: reportSpecsBad === true ? 'Report nonexistent or hidden' : reportSpecsBad},
+              response,
+              false
+            );
+          }
+          // Otherwise, i.e. if the report is available:
+          else {
+            // Get the response (potentially error) data.
+            const responseData = await require(path.join(__dirname, 'reportIssues', 'api'))
+            .response(args);
+            // Send them.
+            response.end(JSON.stringify(responseData));
+          }
+        }
+        // Otherwise, i.e. if the service is invalid:
+        else {
+          // Report this.
+          await serveError({message: 'ERROR: Invalid service request'}, response, false);
+        }
+      }
+      // Otherwise, i.e. if the agent is not authorized or not authenticated:
       else {
-        await serveError({message: 'ERROR: Invalid Testaro agent'}, response, false);
+        // Report this.
+        await serveError({message: 'ERROR: Invalid agent'}, response, false);
       }
     }
     // Otherwise, if it is a tutorial comment:
@@ -617,6 +660,9 @@ const serve = async (protocolModule, options) => {
     console.log(`Kilotest server listening at ${protocol}://localhost:${port}.`);
   });
 };
+
+// EXECUTION
+
 if (protocol === 'http') {
   console.log('Starting HTTP server');
   serve(http, {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "24.1.1",
+  "version": "25.0.1",
   "description": "An ensemble testing service with a focus on accessibility",
   "main": "index.js",
   "scripts": {

package/reportIssues/api.js

@@ -1,231 +1,57 @@
 /*
-  index.js
-  Answers the report-issues question.
+  api.js
+  Responds to the report-issues request.
 */
 
 // IMPORTS
 
+const {getData, getToolData} = require('./util');
 const {
-  getPageDataStrings,
-  getReport,
-  getToolNamesString,
-  getWCAGLink,
-  getWeightName,
-  htmlSafe,
+  getDateTime,
+  getNowStamp,
+  getRandomString,
   isHidden,
-  isValidReport,
-  objectSort,
+  researchAgents,
   tools
 } = require('../util');
-const {issues} = require('testilo/procs/score/tic');
-const fs = require('fs/promises');
-const path = require('path');
 
 // FUNCTIONS
 
-// Gets data on the issues reported in a report.
-const getIssuesData = async (timeStamp, jobID) => {
-  // Get the report.
-  const report = await getReport(timeStamp, jobID);
-  // If it is valid:
-  if (typeof report === 'object' && isValidReport(report)) {
-    const issuesData = {
-      reporters: new Set(),
-      reporterCount: 0,
-      reportersString: '',
-      violators: new Set(),
-      violatorCount: 0,
-      preventions: {},
-      issuesObject: {},
-      issueCount: 0,
-      issues: []
+// Gets facts about tools.
+const getToolFacts = toolIDs => {
+  const crypticData = getToolData(toolIDs);
+  return crypticData.map(tool => {
+    const {toolID, toolName, toolMaker} = tool;
+    return {
+      identifier: toolID,
+      name: toolName,
+      sponsor: toolMaker
     };
-    const {issuesObject, reporters, violators} = issuesData;
-    // For each act in it:
-    report.acts.forEach(act => {
-      // If it is a test act:
-      if (act.type === 'test') {
-        const {result, which} = act;
-        const instances = result?.standardResult?.instances ?? [];
-        // For each of its standard instances:
-        instances.forEach(instance => {
-          const {issueID} = instance;
-          // If the instance has a non-ignorable classified issue:
-          if (issueID && issues[issueID] && issueID !== 'ignorable') {
-            // Ensure that the issues data include data on the issue.
-            issuesObject[issueID] ??= {
-              issueID,
-              weight: issues[issueID].weight ?? 0,
-              reporters: new Set(),
-              reporterCount: 0,
-              reportersString: '',
-              violators: new Set(),
-              violatorCount: 0
-            };
-            // Ensure that the tool is in the issues data.
-            reporters.add(which);
-            // Ensure that it is in the issue data.
-            issuesObject[issueID].reporters.add(which);
-            const {catalogIndex} = instance;
-            // If the instance has a catalog index:
-            if (catalogIndex) {
-              // Ensure that the violator is in the issues data.
-              violators.add(catalogIndex);
-              // Ensure that it is in the issue data.
-              issuesObject[issueID].violators.add(catalogIndex);
-            }
-          }
-        });
-      }
-    });
-    // Populate the unpopulated subproperties of the issues data.
-    issuesData.reporterCount = issuesData.reporters.size;
-    issuesData.reportersString = getToolNamesString(issuesData.reporters);
-    issuesData.violatorCount = issuesData.violators.size;
-    issuesData.preventions = report.jobData.preventions;
-    issuesData.issueCount = Object.keys(issuesData.issuesObject).length;
-    issuesData.issues = Object.values(issuesData.issuesObject);
-    // For each issue in the issues data:
-    issuesData.issues.forEach(issue => {
-      // Populate its unpopulated properties.
-      issue.reporterCount = issue.reporters.size;
-      issue.reportersString = getToolNamesString(issue.reporters);
-      issue.violatorCount = issue.violators.size;
-    });
-    // Sort the issues alphabetically by reporters string.
-    objectSort(issuesData.issues, 'reportersString', 'alpha');
-    // Sort the issues again in descending reporter-count order, making this the primary order.
-    objectSort(issuesData.issues, 'reporterCount', 'numericDown');
-    // Return the issues data.
-    return issuesData;
-  }
-};
-// Adds parameters to a query for the answer page.
-const populateQuery = async (timeStamp, jobID, query) => {
-  // Get fact descriptions for the report.
-  const pageDataStrings = await getPageDataStrings(timeStamp, jobID);
-  const {what, urlLink, testInfo} = pageDataStrings;
-  const issuesData = await getIssuesData(timeStamp, jobID);
-  // If this failed:
-  if (typeof issuesData === 'string') {
-    // Return this.
-    return issuesData;
-  }
-  const {
-    issueCount,
-    preventions,
-    reporterCount,
-    reportersString,
-    violatorCount
-  } = issuesData;
-  // Add an issue count description to the query.
-  query.issueCount = issueCount === 1 ? '1 issue was' : `${issueCount} issues were`;
-  query.reporterCount = reporterCount === 1 ? '1 tool' : `${reporterCount} tools`;
-  // Add a reporter count and list to the query.
-  query.reporters = reportersString;
-  // Add a violator count to the query.
-  query.violatorCount = violatorCount === 1 ? '1 violator was' : `${violatorCount} violators were`;
-  // Add page data to the query.
-  query.target = what;
-  query.urlLink = urlLink;
-  query.testInfo = testInfo;
-  query.timeStamp = timeStamp;
-  query.jobID = jobID;
-  const preventionStrings = [];
-  const margin = ' '.repeat(6);
-  Object.keys(preventions).forEach(preventedToolID => {
-    const toolName = tools[preventedToolID];
-    const toolNameString = `${toolName[0]} (${toolName[1]})`;
-    const causeString = htmlSafe(preventions[preventedToolID]);
-    const preventionString = `${margin}<li>Page not testable by ${toolNameString}: ${causeString}</li>`;
-    preventionStrings.push(preventionString);
   });
-  query.preventions = preventionStrings.join('\n');
-  // For each weight:
-  [4, 3, 2, 1].forEach(weight => {
-    // Initialize data on issues having the weight.
-    const weightData = [];
-    // Initialize the lines for the weight.
-    const weightLines = [];
-    // For each issue:
-    issuesData.issues.forEach(issueData => {
-      const {
-        issueID, reporterCount, reportersString, violatorCount, weight: issueWeight
-      } = issueData;
-      // If it has the weight:
-      if (issueWeight === weight) {
-        const issue = issues[issueID];
-        const {wcag, why} = issue;
-        const wcagLink = `<a href="${getWCAGLink(wcag)}">${wcag}</a>`;
-        // Add data on it to the weight data.
-        weightData.push({
-          issueID,
-          summary: issue.summary,
-          why,
-          wcag: wcagLink,
-          reporterCount,
-          reportersString,
-          violatorCount
-        });
-      }
-    });
-    const weightName = getWeightName(weight);
-    // Add the issue count to the query.
-    query[`${weightName}Count`] = weightData.length;
-    // If any reported issues have the weight:
-    if (weightData.length) {
-      // Add the start of a list of the issues with the weight to the lines.
-      weightLines.push(`${margin}<ul class="headed">`);
-      // For each issue with the weight:
-      weightData.forEach(weightIssue => {
-        const {issueID, reporterCount, reportersString, violatorCount, wcag, why} = weightIssue;
-        // Add the start of a list item to the lines.
-        weightLines.push(`${margin}  <li>`);
-        // Add a heading summarizing the issue to the lines.
-        weightLines.push(`${margin}    <h5>${weightIssue.summary}</h5>`);
-        // Add the start of alist of facts about the issue to the lines.
-        weightLines.push(`${margin}    <ul class="pseudoTopLevel">`);
-        // Add the issue facts to the lines.
-        weightLines.push(`${margin}      <li>Why it matters: ${why}`);
-        weightLines.push(`${margin}      <li>Related WCAG standard: ${wcag}`);
-        const reporterCountString = reporterCount === 1 ? '1 tool' : `${reporterCount} tools`;
-        weightLines.push(
-          `${margin}      <li>Reported by ${reporterCountString} (${reportersString})</li>`
-        );
-        const violatorCountString = violatorCount === 1
-        ? '1 violator was'
-        : `${violatorCount} violators were`;
-        weightLines.push(`${margin}      <li>${violatorCountString} reported</li>`);
-        // Add the end of the fact list to the lines.
-        weightLines.push(`${margin}    </ul>`);
-        // Add the start of a link list to the lines.
-        weightLines.push(`${margin}    <ul class="nav">`);
-        const whereQuestionString = 'Where was the issue found?';
-        const labelString = `Where was the ${weightIssue.summary} issue found on the ${what} page?`;
-        const href = `href="/reportIssue.html/${issueID}/${timeStamp}/${jobID}"`;
-        const label = `aria-label="${labelString}"`;
-        const whereLink = `<a ${href} ${label}>${whereQuestionString}</a>`;
-        // Add a violations link to the lines.
-        weightLines.push(`${margin}      <li>${whereLink}</li>`);
-        // Add the end of the link list to the lines.
-        weightLines.push(`${margin}    </ul>`);
-        // Add the end of the list item to the lines.
-        weightLines.push(`${margin}  </li>`);
-      });
-      // Add the end of the list of issues with the weight to the lines.
-      weightLines.push(`${margin}</ul>`);
-      // Add the lines documenting the issues with the weight to the query.
-      query[`${weightName}Details`] = weightLines.join('\n');
-    }
-    // Otherwise, i.e. if no reported issues have the weight:
-    else {
-      query[`${weightName}Details`] = `${margin}  <p>None</p>`;
+};
+// Gets facts about an issue.
+const getIssueFacts = (thisHost, agentID, timeStamp, jobID, issue) => {
+  const {issueID, reporterCount, reporters, summary, violatorCount, wcag, why} = issue;
+  const wcagType = wcag.length === 3 ? 'principle' : 'success criterion';
+  return {
+    identifier: issueID,
+    summary,
+    [`related WCAG ${wcagType}`]: wcag,
+    'impact on a user': why,
+    'tools 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/${agentID}/reportIssue/${timeStamp}/${jobID}/${issueID}`,
+      'for humans': `${thisHost}/reportIssue/${timeStamp}/${jobID}/${issueID}`
     }
-  });
+  };
 };
-// Returns a page answering the target-issues question.
-exports.answer = async pageArgs => {
-  const [timeStamp, jobID] = pageArgs.split('/');
+// Returns a response to a target-issues request.
+exports.response = async args => {
+  const [agentID, timeStamp, jobID] = args;
   const reportIsHidden = await isHidden(timeStamp, jobID);
   // If the report is not available:
   if (reportIsHidden) {
@@ -234,26 +60,75 @@ exports.answer = async pageArgs => {
       message: 'Report not available'
     };
   }
-  const query = {};
-  // Create a query to replace the placeholders.
-  await populateQuery(timeStamp, jobID, query);
-  // If the report facts were obtained:
-  if (query.testInfo) {
-    // Get the template.
-    let answerPage = await fs.readFile(path.join(__dirname, 'index.html'), 'utf8');
-    // 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
-    };
-  }
-  // Otherwise, i.e. if they were not obtained, report this.
-  return {
-    status: 'error',
-    error: 'Report processing failed'
+  // 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 response = {
+    summary: `This document fulfills a request made by an agent to the Kilotest service. The agent requested data from a Kilotest report about the accessibility, usability, and standard-conformity of a web page. Kilotest, with the help of Testaro, Testilo, and an ensemble of ten testing tools, performs tests on web pages, using a combination of rule- and machine-learning-based methods, and produces reports. Kilotest exposes several API endpoints for agents and several web UI URLs for humans to obtain information from Kilotest reports. To learn more about Kilotest and the advangages of testing with an ensemble of tools, visit the deployed instance of Kilotest (${process.env.DEPLOYED_KILOTEST_HOST}), which contains an introduction on its home page and a tutorial.`,
+    'tool name': 'Kilotest',
+    request: {
+      'requesting agent': {
+        identifier: agentID,
+        name: researchAgents[agentID]
+      },
+      'type of request': {
+        identifier: 'reportIssues',
+        description: 'What issues does the specified report describe?'
+      },
+      'closest ancestor request': {
+        description: 'Which web pages are reports available about, and what are the statistics about the issues reported for each page?',
+        'URL for you': `${thisHost}/api/${agentID}/targets.html`,
+        'URL for humans': `${thisHost}/targets.html`
+      }
+    },
+    'response metadata': {
+      identifier: `${getNowStamp()}-${getRandomString(3)}`,
+      'date and time': new Date().toISOString(),
+      'URL of the human-oriented equivalent of this response': `${thisHost}/reportIssues.html/${timeStamp}/${jobID}`
+    },
+    report: {
+      identifier: `${timeStamp}-${jobID}`,
+      'creation date': getDateTime(timeStamp),
+      'days since the creation date': daysAgo
+    },
+    'tested web page': {
+      description: what,
+      URL: url
+    },
+    'tools that tried to test the page': getToolFacts(Object.keys(tools)),
+    'tools that were unable to test the page': preventedTools,
+    'tools 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, agentID, timeStamp, jobID, issue)),
+      'high priority': issues[3]
+      .map(issue => getIssueFacts(thisHost, agentID, timeStamp, jobID, issue)),
+      'low priority': issues[2]
+      .map(issue => getIssueFacts(thisHost, agentID, timeStamp, jobID, issue)),
+      'lowest priority': issues[1]
+      .map(issue => getIssueFacts(thisHost, agentID, timeStamp, jobID, issue))
+    }
   };
+  return response;
 };

package/reportIssues/index.js

@@ -14,7 +14,6 @@ const {
   isHidden,
   tools
 } = require('../util');
-const {issues} = require('testilo/procs/score/tic');
 const fs = require('fs/promises');
 const path = require('path');
 
@@ -22,7 +21,7 @@ const path = require('path');
 
 // Adds parameters to a query for the answer page.
 const populateQuery = async (timeStamp, jobID, query) => {
-  // Get data on the page and its issues according to the report.
+  // Get data on the target and its issues according to the report.
   const data = await getData(timeStamp, jobID);
   const {pageData, issuesData} = data;
   // If the page data are invalid:
@@ -35,10 +34,10 @@ const populateQuery = async (timeStamp, jobID, query) => {
     // Return this.
     return issuesData;
   }
-  // Otherwise, get fact descriptions for the page.
+  // Otherwise, get fact descriptions for the target.
   const pageInfo = await getPageDataStrings(timeStamp, jobID, pageData);
   const {what, urlLink, testInfo} = pageInfo;
-  // Add page data to the query.
+  // Add target data to the query.
   query.target = what;
   query.urlLink = urlLink;
   query.testInfo = testInfo;

package/reportIssues/util.js

@@ -11,7 +11,7 @@ const issuesClassification = require('testilo/procs/score/tic').issues;
 // FUNCTIONS
 
 // Converts tool IDs to tool data sorted by tool name.
-const getToolData = toolIDs => objectSort(
+const getToolData = exports.getToolData = toolIDs => objectSort(
   Array.from(toolIDs).map(toolID => {
     const toolData = tools[toolID];
     return {
@@ -47,12 +47,6 @@ const getIssuesData = async (timeStamp, jobID) => {
       reporterCount: 0,
       violatorCount: 0,
       preventions: report.jobData.preventions,
-      priorityNames: {
-        4: 'highest',
-        3: 'high',
-        2: 'low',
-        1: 'lowest'
-      },
       issues: {
         4: [],
         3: [],

package/researchAgent.js

@@ -0,0 +1,95 @@
+/*
+  © 2026 Jonathan Robert Pool.
+
+  Licensed under the MIT License. See LICENSE file at the project root or
+  https://opensource.org/license/mit/ for details.
+
+  SPDX-License-Identifier: MIT
+*/
+
+/*
+  researchAgent.js
+  Module for simulating a research agent.
+*/
+
+// IMPORTS
+
+const {getLogs} = require('./util');
+require('dotenv').config();
+const httpClient = require('http');
+const httpsClient = require('https');
+
+// CONSTANTS
+
+const agent = process.env.RESEARCH_AGENT;
+const agentPW = process.env.RESEARCH_AGENT_PW;
+const kilotestHosts = [process.env.LOCAL_KILOTEST_HOST, process.env.DEPLOYED_KILOTEST_HOST];
+// Randomly chosen Kilotest host.
+const kilotestHost = kilotestHosts[Math.random() < 0.5 ? 0 : 1];
+const hostParts = kilotestHost.split(/:\/*/);
+const scheme = hostParts[0];
+const host = hostParts[1];
+const port = hostParts[2] || (scheme === 'https' ? 443 : 80);
+const services = ['reportIssues'];
+// Randomly chosen service.
+const service = services[Math.floor(services.length * Math.random())];
+
+// FUNCTIONS
+
+// Submits a random research request to a random Kilotest host.
+const requestService = async () => {
+  const logs = await getLogs();
+  // Randomly chosen log.
+  const log = logs[Math.floor(logs.length * Math.random())];
+  const specs = log.jobName.split('-').join('/');
+  const path = `/api/${agent}/${service}/${specs}`;
+  const client = scheme === 'https' ? httpsClient : httpClient;
+  // Use its job name in the request path.
+  const requestOptions = {
+    method: 'POST',
+    host,
+    port,
+    path,
+    headers: {
+      'content-type': 'application/json; charset=utf-8'
+    }
+  };
+  console.log(`About to submit ${scheme} request as JSON on port ${port} to ${host}${path}`);
+  // Submit a request.
+  client.request(requestOptions, response => {
+    // Initialize a collection of data from the response.
+    const chunks = [];
+    response
+    // If the response throws an error:
+    .on('error', async error => {
+      // Report it.
+      console.log(error.message);
+    })
+    // If the response delivers data:
+    .on('data', chunk => {
+      // Add them to the collection.
+      chunks.push(chunk);
+    })
+    // When the response is completed:
+    .on('end', async () => {
+      const content = chunks.join('');
+      // Output it.
+      try {
+        console.log(JSON.stringify(JSON.parse(content), null, 2));
+      }
+      catch (error) {
+        console.log(error.message);
+        console.log(`Response content: ${content || 'No content'}`);
+      }
+    });
+  })
+  // Finish sending the job request.
+  .end(JSON.stringify({
+    agentPW
+  }));
+};
+
+// EXECUTION
+
+// Execute the research agent.
+requestService();

package/testOrder/index.js

@@ -5,7 +5,7 @@
 
 // IMPORTS
 
-const {getJSON, getNowStamp, getRecs, isURL} = require('../util');
+const {getJSON, getNowStamp, getRandomString, getRecs, isURL} = require('../util');
 const fs = require('fs/promises');
 const path = require('path');
 
@@ -20,7 +20,7 @@ exports.answer = async (url, what, authCode) => {
     const job = JSON.parse(jobTemplateJSON);
     const nowStamp = getNowStamp();
     // Populate the template with job properties.
-    const jobIDSuffix = Date.now().toString(36).slice(5);
+    const jobIDSuffix = getRandomString(3);
     const jobName = `${nowStamp}-${jobIDSuffix}`;
     job.id = jobName;
     job.creationTimeStamp = nowStamp;

package/util.js

@@ -34,12 +34,18 @@ const tools = exports.tools = {
   nuVnu: ['Html Checker', 'World Wide Web Consortium'],
   qualWeb: ['QualWeb', 'University of Lisbon'],
   testaro: ['Testaro', 'CVS Health'],
-  wax: ['WallyAX', 'Wally'],
   wave: ['WAVE', 'Utah State University'],
 };
+exports.researchAgents = {
+  'research-agent': 'Internal Research Agent'
+}
 
 // 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:
@@ -114,7 +120,7 @@ const getDateString = exports.getDateString = timeStamp => {
   return '';
 };
 // Returns the date and time represented by a time stamp.
-const getDateTime = timeStamp => {
+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);
@@ -484,7 +490,7 @@ exports.getTextFragmentHref = (text, url) => {
   // Return a text-fragment link.
   return `${url}#:~:text=${fragmentList}`;
 };
-// Returns an array of the logs of the public reports on the tested targets.
+// Returns an array of the logs, with job names added, of the non-hidden reports.
 exports.getLogs = async () => {
   // Initialize data on the tested targets.
   const logs = [];