@jrpool/kilotest 38.1.0 → 39.0.1

package/reportsPruneForm/index.js

@@ -5,7 +5,7 @@
 
 // IMPORTS
 
-const {getReportData, logsPath, reportsPath} = require('../util');
+const {getReportData, makeReportsExtract, reportsPath} = require('../util');
 const fs = require('fs/promises');
 const path = require('path');
 
@@ -16,21 +16,31 @@ exports.answer = async (_, search) => {
   const searchParams = new URLSearchParams(search);
   const authCode = searchParams?.get('authCode');
   const jobNames = searchParams?.getAll('report');
-  // If the form has been displayed by itself after a submission and any reports are to be deleted:
+  // If the form has displayed itself after a submission and any reports are to be deleted:
   if (jobNames?.length) {
     // If the authorization code is valid:
     if (authCode === process.env.AUTH_CODE) {
-      // For each report to be deleted:
-      for (const jobName of jobNames) {
-        // Delete it.
-        await fs.unlink(path.join(reportsPath, `${jobName}.json`));
-        // Delete its log.
-        await fs.unlink(path.join(logsPath, `${jobName}.json`));
+      try {
+        // For each report to be deleted:
+        for (const jobName of jobNames) {
+          // Delete it.
+          await fs.unlink(path.join(reportsPath, `${jobName}.json`));
+        }
+        // Update the extract of the available reports.
+        await makeReportsExtract();
+      }
+      // If this failed:
+      catch (error) {
+        // Return why.
+        return {
+          status: 'error',
+          message: `Deleting superseded reports failed (${error.message})`
+        }
       }
     }
     // Otherwise, i.e. if the authorization code is invalid:
     else {
-      // Report the error.
+      // Return this.
       return {
         status: 'error',
         message: 'Invalid authorization code'
@@ -44,14 +54,14 @@ exports.answer = async (_, search) => {
   for (const reportName of reportNames) {
     const [timeStamp, jobID] = reportName.slice(0, -5).split('-');
     // Get a summary of it.
-    const reportSummary = await getReportData(timeStamp, jobID);
-    const {error, issueCount, preventedToolCount, url} = reportSummary;
+    const reportFacts = await getReportData(timeStamp, jobID);
+    const {error, issueCount, preventedToolCount, url} = reportFacts;
     // If this failed:
     if (error) {
       // Return why.
       return {
         status: 'error',
-        message: error
+        message: error.message
       }
     }
     // Otherwise, i.e. if it succeeded, add the summary to the array.

package/reportsRewindForm/index.js

@@ -5,7 +5,7 @@
 
 // IMPORTS
 
-const {getReportData, logsPath, reportsPath} = require('../util');
+const {getReportData, reportsPath} = require('../util');
 const fs = require('fs/promises');
 const path = require('path');
 
@@ -20,12 +20,20 @@ exports.answer = async (_, search) => {
   if (jobNames?.length) {
     // If the authorization code is valid:
     if (authCode === process.env.AUTH_CODE) {
-      // For each report to be deleted:
-      for (const jobName of jobNames) {
-        // Delete it.
-        await fs.unlink(path.join(reportsPath, `${jobName}.json`));
-        // Delete its log.
-        await fs.unlink(path.join(logsPath, `${jobName}.json`));
+      try {
+        // For each report to be deleted:
+        for (const jobName of jobNames) {
+          // Delete it.
+          await fs.unlink(path.join(reportsPath, `${jobName}.json`));
+        }
+      }
+      // If this failed:
+      catch (error) {
+        // Return why.
+        return {
+          status: 'error',
+          message: `Deleting latest superseding reports failed (${error.message})`
+        }
       }
     }
     // Otherwise, i.e. if the authorization code is invalid:
@@ -43,8 +51,8 @@ exports.answer = async (_, search) => {
   for (const reportName of reportNames) {
     const [timeStamp, jobID] = reportName.slice(0, -5).split('-');
     // Get a summary of it.
-    const reportSummary = await getReportData(timeStamp, jobID);
-    const {error, issueCount, preventedToolCount, url} = reportSummary;
+    const reportFacts = await getReportData(timeStamp, jobID);
+    const {error, issueCount, preventedToolCount, url} = reportFacts;
     // If this failed:
     if (error) {
       // Return why.

package/retestRec/index.js

@@ -5,16 +5,20 @@
 
 // IMPORTS
 
-const {getLog, processRec} = require('../util');
+const {getLatestReportExtracts, processRec} = require('../util');
 
 // FUNCTIONS
 
 // Records a retest recommendation and returns an acknowledgement page.
 exports.answer = async (pageArgs, why) => {
   const [timeStamp, jobID] = pageArgs.split('/');
-  // Get the log of the specified report.
-  const log = await getLog(timeStamp, jobID);
-  const {error, url, what} = log;
+  // Get data on the latest available reports.
+  const reportExtracts = await getLatestReportExtracts();
+  // Get data on the report whose page is to be retested.
+  const reportExtract = reportExtracts.find(
+    reportExtract => reportExtract.timeStamp === timeStamp && reportExtract.jobID === jobID
+  );
+  const {error, url, what} = reportExtract;
   // If this failed:
   if (error) {
     // Return why.

package/retestRecForm/index.js

@@ -5,7 +5,7 @@
 
 // IMPORTS
 
-const {getAgoString, getDateTimeString, getLog} = require('../util');
+const {getAgoString, getDateTimeString, getLatestReportExtracts} = require('../util');
 const fs = require('fs/promises');
 const path = require('path');
 
@@ -14,14 +14,26 @@ const path = require('path');
 // Returns a retest recommendation form.
 exports.answer = async pageArgs => {
   const [timeStamp, jobID] = pageArgs.split('/');
-  const log = await getLog(timeStamp, jobID);
-  // If this failed:
-  if (log.error) {
+  // Get data on the latest available reports.
+  const reportExtracts = await getLatestReportExtracts();
+  // Get data on the report whose page is to be retested.
+  const reportExtract = reportExtracts.find(
+    reportExtract => reportExtract.timeStamp === timeStamp && reportExtract.jobID === jobID
+  );
+  // Initialize the page description.
+  let target;
+  // If getting the data succeeded:
+  if (reportExtract) {
+    // Update the page description.
+    target = reportExtract.what;
+  }
+  // Otherwise, i.e. if it failed:
+  else {
     // Make the form report the failure.
-    log.what = 'The specified page is not available for retesting';
+    target = 'The specified page is not available for retesting';
   }
   const query = {
-    target: log.what,
+    target,
     timeStamp,
     jobID,
     ago: getAgoString(timeStamp),

package/scripts/generate-openapi.js

@@ -0,0 +1,83 @@
+/*
+  generate-openapi.js
+  Generates openapi.yaml from the Kilotest API route table (api/routes.js) and Zod schemas (api/schemas.js), keeping the OpenAPI document in sync with schemas.js’s single source of truth.
+*/
+
+// IMPORTS
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const {createDocument} = require('zod-openapi');
+const {license, version} = require('../package.json');
+const routes = require('../api/routes');
+
+// CONSTANTS
+
+const outputPath = path.join(__dirname, '..', 'openapi.yaml');
+
+// FUNCTIONS
+
+// Builds the paths object for createDocument from the route table.
+const buildPaths = () => {
+  const paths = {};
+  routes.forEach(route => {
+    const {method, path: routePath, summary, pathParamsSchema, bodySchema, responseSchema} = route;
+    if (!paths[routePath]) {
+      paths[routePath] = {};
+    }
+    const operation = {
+      operationId: route.operationId,
+      summary,
+      responses: {
+        '200': {
+          description: summary,
+          content: {
+            'application/json': {schema: responseSchema}
+          }
+        }
+      }
+    };
+    if (pathParamsSchema) {
+      operation.requestParams = {path: pathParamsSchema};
+    }
+    if (bodySchema) {
+      operation.requestBody = {
+        content: {'application/json': {schema: bodySchema}}
+      };
+    }
+    paths[routePath][method] = operation;
+  });
+  return paths;
+};
+// Generates and writes the openapi.yaml file.
+const generate = () => {
+  const document = createDocument({
+    openapi: '3.1.0',
+    info: {
+      title: 'Kilotest API',
+      description: 'Kilotest is an ensemble testing and reporting service for front-end web quality. It uses an ensemble of 10 rule engines to test public web pages for front-end quality (accessibility, usability, and standards conformity). Kilotest acts as a web server for human users, an MCP server for AI platforms, and an API for programmatic access. With this API you can request that a page be tested or retested, discover available reports, incrementally retrieve facts from a report: from what reports are available, to what issues were reported in one report, to what elements violated one issue, to what diagnoses rule engines gave for one violation.',
+      version,
+      license: {
+        name: license,
+        identifier: license
+      },
+      contact: {
+        name: 'Kilotest',
+        url: 'https://github.com/jrpool/kilotest',
+        email: 'info@kilotest.com'
+      }
+    },
+    servers: [
+      {url: 'https://kilotest.com', description: 'Kilotest production server'}
+    ],
+    security: [],
+    paths: buildPaths()
+  });
+  fs.writeFileSync(outputPath, yaml.dump(document, {noRefs: true, lineWidth: -1}));
+  console.log(`Wrote ${outputPath}`);
+};
+
+// EXECUTION
+
+generate();

package/targets/index.js

@@ -9,13 +9,15 @@ const {
   getAgoDays,
   getCountString,
   getJobNames,
+  getMultiReportWhats,
   getObject,
   getPageDataStrings,
   getRecs,
-  getLogs,
   getReportData,
+  getReportExtracts,
   isRecommendable,
-  jobsPath
+  jobsPath,
+  objectSort
 } = require('../util');
 const fs = require('fs/promises');
 const path = require('path');
@@ -69,18 +71,21 @@ const populateQuery = async query => {
   query.noQueued = lines.queue.length ? '' : 'No pages are queued for testing.';
   // Add a no-claimed message, if applicable, to the query.
   query.noClaimed = lines.claimed.length ? '' : 'No pages are being tested now.';
-  // Get the logs of the non-hidden reports.
-  const targetLogs = await getLogs();
-  query.which = targetLogs.length ? 'the following' : 'no';
-  query.some = (targetLogs.length || jobFileNames.queue.length || jobFileNames.claimed.length)
+  // Get extracts of all available reports.
+  const reportExtracts = await getReportExtracts();
+  const reportCount = reportExtracts.length;
+  query.which = reportCount ? 'the following' : 'no';
+  query.some = (reportCount || jobFileNames.queue.length || jobFileNames.claimed.length)
   ? 'another'
   : 'a';
-  const multiReportTargets = new Set(targetLogs.filter(log => log.superseded).map(log => log.what));
-  // For each log:
-  for (const targetLog of targetLogs) {
-    const {jobName, url, what} = targetLog;
-    const [timeStamp, jobID] = jobName.split('-');
-    // Get data about its report.
+  const multiReportWhats = await getMultiReportWhats();
+  // Sort them primarily by page description and secondarily by completion time.
+  let sortedExtracts = objectSort(reportExtracts, 'reportTime', 'alpha');
+  sortedExtracts = objectSort(sortedExtracts, 'what', 'alpha');
+  // For each report:
+  for (const extract of sortedExtracts) {
+    const {jobID, timeStamp, url, what} = extract;
+    // Get data about it.
     const reportData = await getReportData(timeStamp, jobID);
     const {
       error,
@@ -104,7 +109,7 @@ const populateQuery = async query => {
     const daysAgo = getAgoDays(timeStamp);
     const pageDataStrings = await getPageDataStrings(timeStamp, jobID, {what, url, daysAgo});
     const {urlLink, testInfo} = pageDataStrings;
-    const testText = multiReportTargets.has(what) ? ` (${testInfo.toLowerCase()})` : '';
+    const testText = multiReportWhats.includes(what) ? ` (${testInfo.toLowerCase()})` : '';
     lines.tested.push(`${margin}  <summary>${what}${testText}</summary>`);
     lines.tested.push(`${margin}  <ul>`);
     // Add the URL of the target to the lines.

package/testOrder/index.js

@@ -5,7 +5,7 @@
 
 // IMPORTS
 
-const {getJSON, getNowStamp, getRandomString, getRecs, isURL} = require('../util');
+const {getJSON, getNowStamp, getRandomString, getRecs, isURL, jobsPath, recsLock} = require('../util');
 const fs = require('fs/promises');
 const path = require('path');
 
@@ -33,15 +33,18 @@ exports.answer = async (url, what, authCode) => {
     };
     // Save the job in the queue.
     await fs.writeFile(
-      path.join(__dirname, '..', 'jobs', 'queue', `${jobName}.json`), getJSON(job)
+      path.join(jobsPath, 'queue', `${jobName}.json`), getJSON(job)
     );
     console.log(`Retest queued for ${what} as job ${jobName}`);
-    // Get the recommendations.
-    const recs = await getRecs();
-    // Delete the recommendations to retest the target.
-    delete recs[url];
-    // Save the revised recommendations.
-    await fs.writeFile(path.join(__dirname, '..', 'jobs', 'recs.json'), getJSON(recs));
+    // Isolate this revision.
+    await recsLock(async () => {
+      // Get the recommendations.
+      const recs = await getRecs();
+      // Delete the recommendations to retest the target.
+      delete recs[url];
+      // Save the revised recommendations.
+      await fs.writeFile(path.join(jobsPath, 'recs.json'), getJSON(recs));
+    });
     // Get the answer template.
     let answerPage = await fs.readFile(path.join(__dirname, 'index.html'), 'utf8');
     // Replace its placeholders.

package/tutorial/index.html

@@ -141,23 +141,23 @@
       }
       @media print {
         /* ── Layout ── */
-        body { font-size: 11pt; }
-        main { max-width: none; padding: 0; }
+        body {font-size: 11pt;}
+        main {max-width: none; padding: 0;}
 
         /* ── Hide elements that serve no purpose on a printed page ── */
         .skip-link,
         .tutorial-nav,
         #comment-form,
         #comment-diagnosis,
-        #lesson1-quiz button { display: none; }
+        #lesson1-quiz button {display: none;}
 
         /* ── Page breaks: start each h2 section, h3 section, and h4 subsection on a new page ── */
-        section.tutorial-section { break-before: page; }
-        section.tutorial-section > section { break-before: page; }
-        h3, h4 { break-before: page; }
+        section.tutorial-section {break-before: page;}
+        section.tutorial-section > section {break-before: page;}
+        h3, h4 {break-before: page;}
 
         /* ── Keep headings attached to the content that follows them ── */
-        h2, h3, h4 { break-after: avoid; }
+        h2, h3, h4 {break-after: avoid;}
 
         /* ── Avoid splitting self-contained blocks across pages ── */
         pre,
@@ -165,15 +165,15 @@
         .ai-output,
         .note,
         dl.compare,
-        .knowledge-check { break-inside: avoid; }
+        .knowledge-check {break-inside: avoid;}
 
         /* ── Force all details elements open so their content prints ── */
-        details { display: block; }
-        details > * { display: block; }
-        details > summary::marker { content: ''; }
+        details {display: block;}
+        details > * {display: block;}
+        details > summary::marker {content: '';}
 
         /* ── Print the href after external links as a reference ── */
-        a[href^="http"]::after { content: ' (' attr(href) ')'; font-size: 0.8em; }
+        a[href^="http"]::after {content: ' (' attr(href) ')'; font-size: 0.8em;}
       }
     </style>
   </head>