@jrpool/kilotest 38.0.0 → 39.0.0

package/researchAgent.js

@@ -1,206 +0,0 @@
-/*
-  © 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
-  Simulates a research agent.
-*/
-
-// IMPORTS
-
-require('dotenv').config();
-const httpClient = require('http');
-const httpsClient = require('https');
-
-// CONSTANTS
-
-const kilotestHosts = [
-  process.env.LOCAL_KILOTEST_HOST || 'http://localhost:3000',
-  process.env.DEPLOYED_KILOTEST_HOST || 'https://kilotest.com'
-];
-// Kilotest host specified by the argument.
-const kilotestHost = kilotestHosts[process.argv[2] === 'pub' ? 1 : 0];
-const hostParts = kilotestHost.split(/:\/*/);
-const scheme = hostParts[0] === 'https' ? 'https' : 'http';
-const client = scheme === 'https' ? httpsClient : httpClient;
-const host = hostParts[1] || 'localhost';
-const port = hostParts[2] || (scheme === 'https' ? 443 : 80);
-
-// FUNCTIONS
-
-// Gets and outputs the content or error message from a response.
-const getContent = async response => {
-  const content = await new Promise(resolve => {
-    // Initialize an array of data from the response.
-    const chunks = [];
-    response
-    // If the response throws an error:
-    .on('error', error => {
-      const {message} = error;
-      // Report and return the error message.
-      console.log(message);
-      resolve({error: message});
-    })
-    // Whenever the response delivers data:
-    .on('data', chunk => {
-      // Add them to the array.
-      chunks.push(chunk);
-    })
-    // When the response is completed:
-    .on('end', () => {
-      const contentString = chunks.join('');
-      try {
-        const content = JSON.parse(contentString);
-        // Return the response content as an object.
-        resolve(content);
-      }
-      // If it is not JSON:
-      catch {
-        // Return this.
-        resolve({message: `Response content not JSON (${contentString})`});
-      }
-    });
-  });
-  console.log(JSON.stringify(content, null, 2));
-  return content;
-};
-const getRequestOptions = (path, method = 'GET') => ({
-  method,
-  host,
-  port,
-  path,
-  headers: {
-    'content-type': 'application/json; charset=utf-8'
-  }
-});
-// Submits a request, returns the response content, and increments the results.
-const submitRequest = async (path, method, body = null) => new Promise(resolve => {
-  console.log(`Making ${scheme} ${method} request on port ${port} to ${host}${path}`);
-  client.request(getRequestOptions(path, method), async response => {
-    const responseContent = await getContent(response);
-    resolve(responseContent);
-  })
-  .on('error', error => {
-    console.log(`ERROR submitting request (${JSON.stringify(error, null, 2)})`);
-    resolve({error});
-  })
-  .end(body ? JSON.stringify(body) : '');
-});
-// Submits requests to a random Kilotest host.
-const requestService = async () => {
-  let method;
-  let path;
-  let content;
-  let reports;
-  let report;
-  let timeStamp;
-  let jobID;
-  let description;
-  let url;
-  console.log('======================\nRequest: Summarize nonexistent reports');
-  method = 'POST';
-  path = '/api/target';
-  content = await submitRequest(path, method, {
-    description: 'oesntuhaesouht',
-    hostname: 'osentuhaoesuht.aoesntuh'
-  });
-  if (content.error) {
-    return;
-  }
-  console.log('======================\nRequest: List all available reports');
-  method = 'GET';
-  path = '/api/reportList';
-  content = await submitRequest(path, method);
-  reports = content?.['response content'] ?? [];
-  if (content.error || ! Array.isArray(reports) || ! reports.length) {
-    return;
-  }
-  console.log('======================\nRequest: Summarize matching reports');
-  // Choose one available report at random.
-  report = reports[Math.floor(Math.random() * reports.length)];
-  ({description, URL: url} = report?.['tested web page'] ?? ['', '']);
-  if (! (description && url)) {
-    return;
-  }
-  method = 'POST';
-  path = '/api/target';
-  content = await submitRequest(path, method, {
-    description,
-    hostname: new URL(url).hostname ?? ''
-  });
-  if (content.error) {
-    return;
-  }
-  console.log('======================\nRequest: Summarize one nonexistent report');
-  [timeStamp, jobID] = ['111111T1111', 'abc'];
-  method = 'GET';
-  path = `/api/reportSummary/${timeStamp}/${jobID}`;
-  content = await submitRequest(path, method);
-  if (! content.message) {
-    return;
-  }
-  console.log('======================\nRequest: Summarize one report');
-  [timeStamp, jobID] = report.identifier?.split('-') ?? ['', ''];
-  if (! (timeStamp && jobID)) {
-    return;
-  }
-  method = 'GET';
-  path = `/api/reportSummary/${timeStamp}/${jobID}`;
-  content = await submitRequest(path, method);
-  if (content.message || ! content.summary) {
-    return;
-  }
-  console.log('======================\nRequest: Describe one issue from one report');
-  if (content['response content']['number of elements reported as violators'] === 0) {
-    console.log('reportIssue request cannot be submitted, because no issues were reported');
-  }
-  else {
-    // Get the issue IDs.
-    const issueIDs = Object
-    .values(content['response content']['issues revealed'])
-    .map(issue => issue.identifier);
-    // Choose one at random.
-    const issueID = issueIDs[Math.floor(Math.random() * issueIDs.length)];
-    method = 'GET';
-    path = `/api/reportIssue/${issueID}/${timeStamp}/${jobID}`;
-    content = await submitRequest(path, method);
-    if (content.message) {
-      return;
-    }
-  }
-  console.log('======================\nRequest: Make a permitted test recommendation');
-  method = 'POST';
-  path = '/api/testRecForm';
-  content = await submitRequest(path, method, {
-    'description of the web page': 'aoseeou',
-    'URL of the web page': 'https://oaaestuh.osneth',
-    'reason for testing the web page': 'Just testing'
-  });
-  if (content.message) {
-    return;
-  }
-  console.log('======================\nRequest: Make an illicit test recommendation');
-  content = await submitRequest(path, method, {
-    'description of the web page': description,
-    'URL of the web page': url,
-    'reason for testing the web page': 'Just testing'
-  });
-  if (! content.message) {
-    return;
-  }
-  console.log('======================\nRequest: Results');
-  console.log('All tests succeeded');
-};
-
-// EXECUTION
-
-// Execute the research agent.
-(async () => {
-  await requestService();
-})();

package/target/api.js

@@ -1,126 +0,0 @@
-/*
-  api.js
-  Responds to the target request.
-*/
-
-// IMPORTS
-
-const {
-  getLogs,
-  getNowStamp,
-  getRandomString,
-  getReportData,
-  minifyURL
-} = require('../util');
-
-// CONSTANTS
-
-const thisHost = process.env.THIS_KILOTEST_HOST;
-
-// FUNCTIONS
-
-// Returns a response to a target request.
-exports.response = async args => {
-  const [description = '', hostname = ''] = args;
-  const hostLC = hostname.toLowerCase();
-  const whatLC = description.toLowerCase();
-  // Initialize an array of summaries of matching reports.
-  const matchingReports = [];
-  // Get the non-hidden logs.
-  const targetLogs = await getLogs();
-  // For each log:
-  for (const targetLog of targetLogs) {
-    const {jobName} = targetLog;
-    const [timeStamp, jobID] = jobName.split('-');
-    const {superseded, url: reportURL, what: reportWhat} = targetLog;
-    const reportHost = new URL(minifyURL(reportURL)).hostname;
-    const reportWhatLC = reportWhat.toLowerCase();
-    // If its description or hostname fragment matches the requested page:
-    if (
-      hostLC && (reportHost.includes(hostLC) || hostLC.includes(reportHost))
-      || whatLC && (reportWhatLC.includes(whatLC) || whatLC.includes(reportWhatLC))
-    ) {
-      // Get data about its report.
-      const data = await getReportData(timeStamp, jobID);
-      const {
-        error,
-        creationDate,
-        daysAgo,
-        issueCount,
-        toolNames,
-        toolCount,
-        reporterNames,
-        reporterCount,
-        violatorCount,
-        preventedToolNames,
-        preventedToolCount
-      } = data;
-      // 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.
-  const content = {
-    summary: `This document fulfills a request made by a language model to the Kilotest API. The model asked whether Kilotest had tested a specified web page for front-end quality (i.e. accessibility, usability, and standards conformity) and had made a report of the test results available. The response provides summary information about all and only the available reports of pages that match at least one of the provided fragments, where matching means either including or being included by the provided fragment, case-insensitively. 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 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}), whose home page contains an introduction and a link to a tutorial.`,
-    'tool collection name': 'Kilotest',
-    'tool name': 'summarizeQualityOfMatchingWebPages',
-    request: {
-      'type of request': {
-        identifier: 'target',
-        description: 'Summarize the quality of matching web pages.'
-      },
-      method: 'POST',
-      payload: {
-        description,
-        hostname
-      },
-      URLs: {
-        'for you': `${thisHost}/api/target`,
-        'for humans': 'none'
-      },
-      'closest ancestor request': null
-    },
-    'response metadata': {
-      identifier: `${getNowStamp()}-${getRandomString(3)}`,
-      'date and time': new Date().toISOString(),
-    },
-    'matching reports': matchingReports
-  };
-  return content;
-};

package/testRecForm/api.js

@@ -1,55 +0,0 @@
-/*
-  api.js
-  Responds to the test-recommendation request.
-*/
-
-// IMPORTS
-
-const {sendAlert} = require('../alerts')
-const {
-  getNowStamp,
-  getRandomString,
-  updateRecs
-} = require('../util');
-
-// FUNCTIONS
-
-// Returns a response to a test-recommendation request.
-exports.response = async (what, url, why) => {
-  const thisHost = process.env.THIS_KILOTEST_HOST;
-  // Record the recommendation.
-  await updateRecs(what, url, why);
-  // Alert a manager about it.
-  await sendAlert(
-    `Kilotest: new test recommendation in the API`,
-    `Target: ${what}\nURL: ${url}\nReason: ${why}`
-  );
-  // Get a response.
-  const content = {
-    summary: `This response acknowledges a request made by a language model to a Kilotest tool. The model recommended that Kilotest test, for the first time, the ${what} web page at ${url} for front-end quality (i.e. accessibility, usability, and standards conformity). A Kilotest manager usually approves a recommendation within a day. When the recommendation is approved, the testing will be performed and results will become available. You can check for the availability of the results at ${thisHost}/api/reportList. Kilotest performs its testing with the help of Testaro, Testilo, and an ensemble of ten rule engines, using a combination of rule- and machine-learning-based methods. Kilotest exposes several API endpoints and several web UI URLs 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': 'recommendQualityTestingOfOneWebPage',
-    request: {
-      'type of request': {
-        identifier: 'testRecForm',
-        description: 'Recommend quality testing of one web page.'
-      },
-      method: 'POST',
-      payload: {
-        'description of the web page': what,
-        'URL of the web page': url,
-        'reason for testing the web page': why
-      },
-      URLs: {
-        'for you': `${thisHost}/api/testRecForm`,
-        'for humans': `${thisHost}/testRecForm.html`
-      },
-      'closest ancestor request': null
-    },
-    'response metadata': {
-      identifier: `${getNowStamp()}-${getRandomString(3)}`,
-      'date and time': new Date().toISOString()
-    }
-  };
-  return content;
-};