@jrpool/kilotest 46.1.0 → 47.0.1

package/api/{listViolators.test.js → listViolators.test.ts}

@@ -1,21 +1,20 @@
 /*
-  listViolators.test.js
-  Tests for api/listViolators.js using the fixture corpus, with emphasis on outcome handling.
+  listViolators.test.ts
+  Tests for api/listViolators.ts using the fixture corpus, with emphasis on outcome handling.
 */
 
 // IMPORTS
 
-const {test, before, after} = require('node:test');
-const assert = require('node:assert/strict');
-const path = require('node:path');
-const {response} = require('./listViolators');
+import {test, before, after} from 'node:test';
+import assert from 'node:assert/strict';
+import {response} from './listViolators.ts';
 
 // SETUP AND TEARDOWN
 
 const savedDBDir = process.env.DB_DIR;
 
-before(() => {
-  process.env.DB_DIR = path.join(__dirname, '..', 'test', 'fixtures', 'db');
+before(async () => {
+  process.env.DB_DIR = (await import('../test/dbFixture.ts')).fixtureDBDir;
 });
 
 after(() => {
@@ -31,7 +30,7 @@ after(() => {
 
 test('listViolators returns 1 violator for linkNoText in the mixed report, excluding cantTell', async () => {
   const body = await response(['linkNoText', '260101T0000', 'mix']);
-  const violators = body['response content']['basics about all elements exhibiting the issue'];
+  const violators = body['response content']['basics about all elements exhibiting the issue'] as any;
   assert.equal(violators.length, 1);
   assert.equal(violators[0].identifier, '0');
   assert.equal(violators[0]['tag name'], 'A');
@@ -41,40 +40,40 @@ test('listViolators returns 1 violator for linkNoText in the mixed report, exclu
 
 test('listViolators returns 0 violators for an issue when all instances are cantTell', async () => {
   const body = await response(['focusIndicationBad', '260101T0001', 'ct']);
-  const violators = body['response content']['basics about all elements exhibiting the issue'];
+  const violators = body['response content']['basics about all elements exhibiting the issue'] as any;
   assert.equal(violators.length, 0);
 });
 
 test('listViolators treats missing outcome as a violation', async () => {
   const body = await response(['linkNoText', '260101T0002', 'no']);
-  const violators = body['response content']['basics about all elements exhibiting the issue'];
+  const violators = body['response content']['basics about all elements exhibiting the issue'] as any;
   assert.equal(violators.length, 1);
   assert.equal(violators[0].identifier, '0');
 });
 
 test('listViolators returns an error for an unknown issue ID', async () => {
   const body = await response(['nonexistentIssue', '260101T0000', 'mix']);
-  const basics = body['response content']['basics about the issue'];
+  const basics = body['response content']['basics about the issue'] as any;
   assert.ok(basics.error);
 });
 
 test('listViolators returns an error for a nonexistent report', async () => {
   const body = await response(['linkNoText', '999999T9999', 'xyz']);
-  const basics = body['response content']['basics about the report'];
+  const basics = body['response content']['basics about the report'] as any;
   assert.ok(basics.error);
 });
 
 test('listViolators includes reporter facts for the issue', async () => {
   const body = await response(['linkNoText', '260101T0000', 'mix']);
-  const details = body['response content']['details about the issue'];
+  const details = body['response content']['details about the issue'] as any;
   const reporters = details['rule engines reporting violations belonging to the issue'];
-  const names = reporters.map(r => r.name).sort();
+  const names = reporters.map((r: any) => r.name).sort();
   assert.deepEqual(names, ['Alfa', 'Axe']);
 });
 
 test('listViolators sorts by catalogIndex when two violators have the same reporter count', async () => {
   const body = await response(['linkNoText', '260101T0008', 'mul']);
-  const violators = body['response content']['basics about all elements exhibiting the issue'];
+  const violators = body['response content']['basics about all elements exhibiting the issue'] as any;
   assert.equal(violators.length, 3);
   // The violator with 2 reporters (catalogIndex 2) sorts first.
   assert.equal(violators[0].identifier, '2');
@@ -88,14 +87,14 @@ test('listViolators sorts by catalogIndex when two violators have the same repor
 
 test('listViolators returns guideline layer for an issue with a short WCAG code', async () => {
   const body = await response(['duplicateID', '260101T0009', 'brd']);
-  const issueBasics = body['response content']['basics about the issue'];
+  const issueBasics = body['response content']['basics about the issue'] as any;
   assert.equal(issueBasics['related WCAG standard'].layer, 'guideline');
 });
 
 test('listViolators returns null tag name and text for a violator not in the catalog', async () => {
   const body = await response(['duplicateID', '260101T0009', 'brd']);
-  const violators = body['response content']['basics about all elements exhibiting the issue'];
-  const orphan = violators.find(v => v.identifier === '3');
+  const violators = body['response content']['basics about all elements exhibiting the issue'] as any;
+  const orphan = violators.find((v: any) => v.identifier === '3');
   assert.ok(orphan);
   assert.equal(orphan['tag name'], null);
   assert.equal(orphan['inner text'], null);
@@ -103,6 +102,6 @@ test('listViolators returns null tag name and text for a violator not in the cat
 
 test('listViolators returns an error for a falsy issue ID', async () => {
   const body = await response(['', '260101T0009', 'brd']);
-  const issueBasics = body['response content']['basics about the issue'];
+  const issueBasics = body['response content']['basics about the issue'] as any;
   assert.ok(issueBasics.error);
 });

package/api/{listViolators.js → listViolators.ts}

@@ -1,104 +1,79 @@
 /*
-  listViolators.js
+  listViolators.ts
   Returns details about one issue in one report and basics about all the violators of the issue.
 */
 
 // IMPORTS
 
-const {
+import {z} from 'zod';
+import {
   getIssueSpec,
   getReportBasics,
   getResponseMetadata,
   getRuleEnginesFacts,
   getToolsFacts,
-  thisHost
-} = require('./util');
-const {getReport} = require('../util');
+  getThisHost
+} from './util.ts';
+import {getReport, getTestActInstances, isReportError} from '../util.ts';
+import {listViolatorsResponseSchema} from './schemas.ts';
+
+// TYPES
+
+// The response content defined by the response schema.
+type ResponseContent = z.infer<typeof listViolatorsResponseSchema>['response content'];
 
 // FUNCTIONS
 
 // Returns the response body.
-exports.response = async args => {
+export const response = async (args: string[]) => {
   const [issueID = '', timeStamp = '', jobID = ''] = args;
+  const thisHost = getThisHost();
+  // Get the report.
+  const report = await getReport(timeStamp, jobID);
   // Initialize the response content.
-  const responseContent = {
-    'basics about the report': null,
-    'basics about the issue': null,
+  const responseContent: ResponseContent = {
+    'basics about the report': isReportError(report) ? report : await getReportBasics(timeStamp, jobID),
+    'basics about the issue': {
+      'error': 'No information about the specified issue is available'
+    },
     'details about the issue': null,
     'basics about all elements exhibiting the issue': null
   };
-  // Get the report.
-  const report = await getReport(timeStamp, jobID);
-  // If this failed:
-  if (report.error) {
-    // Add this to the response content.
-    responseContent['basics about the report'] = report;
-  }
-  // Otherwise, i.e. if it succeeded:
-  else {
-    // Get the basics about the report (which may be only an error message).
-    const reportBasics = await getReportBasics(timeStamp, jobID);
-    // Add them to the response content.
-    responseContent['basics about the report'] = reportBasics;
-  }
   // Get the specification of the issue.
   const issueSpec = issueID ? getIssueSpec(issueID) : null;
-  // If the issue is ignorable or not fully classified:
-  if (!issueSpec) {
-    // Add this to the response content.
-    responseContent['basics about the issue'] = {
-      'error': 'No information about the specified issue is available'
-    };
-  }
-  // Otherwise, i.e. if it is non-ignorable and fully classified:
-  else {
+  // If the issue is non-ignorable and fully classified:
+  if (issueSpec) {
     const {summary, wcag, weight, why} = issueSpec;
-    // Initialize the basics and details about it.
-    const issueBasics = {
+    // Add the basics about it to the response content.
+    responseContent['basics about the issue'] = {
       'identifier': issueID,
       summary,
       'impact on a user': why,
       'related WCAG standard': {
-        'layer': (wcag.length > 4 ? 'success criterion' : 'guideline'),
+        'layer': (wcag.length > 4 ? 'success criterion' : 'guideline') as 'success criterion' | 'guideline',
         'identifier': wcag
       },
-      priority: ['lowest', 'low', 'high', 'highest'][weight - 1]
+      priority: ['lowest', 'low', 'high', 'highest'][weight - 1] as 'lowest' | 'low' | 'high' | 'highest'
     };
-    // Add the basics about the issue to the response content.
-    responseContent['basics about the issue'] = issueBasics;
     // If the report is available:
-    if (!report.error) {
+    if (!isReportError(report)) {
       // Initialize data about the instances of the issue.
-      const reporterIDs = new Set();
-      const violators = {};
-      // For each act in the report:
-      report.acts.forEach(act => {
-        const {result, type, which} = act;
-        const instances = result?.standardResult?.instances || [];
-        // If the act is a test act with a specified rule engine:
-        if (type === 'test' && which) {
-          // For each standard instance of the act:
-          instances.forEach(instance => {
-            // If the instance has the issue ID:
-            if (instance.issueID === issueID) {
-              const {catalogIndex, outcome} = instance;
-              // If the instance reports a violation:
-              if (outcome !== 'cantTell') {
-                // Ensure the rule-engine ID is in the reporters data.
-                reporterIDs.add(which);
-                // If the instance has a catalog index:
-                if (catalogIndex) {
-                  // Ensure the catalog index is in the violators data.
-                  violators[catalogIndex] ??= {
-                    catalogIndex,
-                    reporters: new Set()
-                  };
-                  // Ensure the reporter ID is in the data about the violator.
-                  violators[catalogIndex].reporters.add(which);
-                }
-              }
-            }
-          });
+      const reporterIDs: Set<string> = new Set();
+      const violators: Record<string, {catalogIndex: string | number; reporters: Set<string>}> = {};
+      // For each violating standard instance of the issue in the report:
+      getTestActInstances(report, {violationsOnly: true, issueID}).forEach(({act, instance}) => {
+        const {catalogIndex} = instance;
+        // Ensure the rule-engine ID is in the reporters data.
+        reporterIDs.add(act.which!);
+        // If the instance has a catalog index:
+        if (catalogIndex) {
+          // Ensure the catalog index is in the violators data.
+          violators[catalogIndex] ??= {
+            catalogIndex,
+            reporters: new Set()
+          };
+          // Ensure the reporter ID is in the data about the violator.
+          violators[catalogIndex].reporters.add(act.which!);
         }
       });
       // Get details about the reporters of the issue.
@@ -131,7 +106,7 @@ exports.response = async args => {
           'count of rule engines reporting that the element exhibited the issue': reporters.size,
           'how to get details about the element': {
             URL: `${thisHost}/api/listDiagnoses/${catalogIndex}/${issueID}/${timeStamp}/${jobID}`,
-            'request method': 'GET'
+            'request method': 'GET' as const
           },
           'web users can get details about the element at': `${thisHost}/listDiagnoses.html/${issueID}/${timeStamp}/${jobID}/${catalogIndex}`
         };

package/api/requestFeature.test.ts

@@ -0,0 +1,54 @@
+/*
+  requestFeature.test.ts
+  Tests for api/requestFeature.ts with mocked side effects.
+*/
+
+// IMPORTS
+
+import {test, beforeEach, after} from 'node:test';
+import assert from 'node:assert/strict';
+
+// SETUP AND TEARDOWN
+
+let logged: any[] = [];
+const originalLog = console.log;
+
+// Capture console.log so the alert sendAlert emits can be observed. The alert
+// configuration is empty in tests, so sendAlert logs a WARNING instead of sending.
+beforeEach(() => {
+  logged = [];
+  console.log = (...args) => logged.push(args.join(' '));
+});
+
+import {response} from './requestFeature.ts';
+
+after(() => {
+  console.log = originalLog;
+});
+
+// TESTS
+
+test('requestFeature rejects an empty feature request', async () => {
+  const body = await response(['']);
+  const details = body['response content']['details about your request'] as any;
+  assert.ok(details.error);
+  assert.ok(!logged.some(line => line.startsWith('WARNING (MCP feature request received)')));
+});
+
+test('requestFeature accepts a non-empty feature request and notifies the manager', async () => {
+  const body = await response(['Add a dark mode toggle']);
+  const details = body['response content']['details about your request'] as any;
+  assert.equal(details.error, undefined);
+  assert.ok(details['date and time received']);
+  assert.equal(details.disposition, 'received and logged; manager notified');
+  assert.ok(logged.some(line =>
+    line.startsWith('WARNING (MCP feature request received)')
+    && line.includes('Add a dark mode toggle')
+  ));
+});
+
+test('requestFeature includes tool name and metadata', async () => {
+  const body = await response(['Some feature']);
+  assert.equal(body['tool name'], 'requestFeature');
+  assert.ok(body['response metadata'].identifier);
+});

package/api/{requestFeature.js → requestFeature.ts}

@@ -1,31 +1,34 @@
 /*
-  requestFeature.js
+  requestFeature.ts
   Processes a request to add or improve a feature and returns an acknowledgement.
 */
 
 // IMPORTS
 
-const {getResponseMetadata, getToolsFacts, thisHost} = require('./util');
-const {sendAlert} = require('../alerts');
+import {z} from 'zod';
+import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
+import {sendAlert} from '../alerts.ts';
+import {requestFeatureResponseSchema} from './schemas.ts';
+
+// TYPES
+
+// The response content defined by the response schema.
+type ResponseContent = z.infer<typeof requestFeatureResponseSchema>['response content'];
 
 // FUNCTIONS
 
 // Returns the response body.
-exports.response = async args => {
+export const response = async (args: string[]) => {
   const [feature = ''] = args;
+  const thisHost = getThisHost();
   // Initialize the response content.
-  const responseContent = {
-    'details about your request': null
-  };
-  // If the requested feature or improvement is empty:
-  if (!feature) {
-    // Add this to the response content.
-    responseContent['details about your request'] = {
+  const responseContent: ResponseContent = {
+    'details about your request': {
       error: 'request invalid: request is empty'
-    };
-  }
-  // Otherwise, i.e. if it exists:
-  else {
+    }
+  };
+  // If the requested feature or improvement exists:
+  if (feature) {
     // Notify the manager.
     await sendAlert('MCP feature request received', feature);
     // Add the disposition to the response content.

package/api/{requestRetest.test.js → requestRetest.test.ts}

@@ -1,37 +1,39 @@
 /*
-  requestRetest.test.js
-  Tests for api/requestRetest.js using the fixture corpus, with mocked side effects.
+  requestRetest.test.ts
+  Tests for api/requestRetest.ts using the fixture corpus.
 */
 
 // IMPORTS
 
-const {test, before, beforeEach, after} = require('node:test');
-const assert = require('node:assert/strict');
-const path = require('node:path');
-const apiUtil = require('./util');
+import {test, before, beforeEach, after} from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fixtureDBDir} from '../test/dbFixture.ts';
 
 // SETUP AND TEARDOWN
 
 const savedDBDir = process.env.DB_DIR;
-let processTestRequestCalls = [];
+const testRequestsPath = path.join(fixtureDBDir, 'jobs', 'testRequests.json');
+let logged: any[] = [];
+const originalLog = console.log;
 
 before(() => {
-  process.env.DB_DIR = path.join(__dirname, '..', 'test', 'fixtures', 'db');
-  // @ts-expect-error: Replacing the real function with a mock for testing.
-  apiUtil.processTestRequest = async (testType, what, url, reason) => {
-    processTestRequestCalls.push({testType, what, url, reason});
-  };
+  process.env.DB_DIR = fixtureDBDir;
 });
 
-// Reset the call log before each test, so tests do not depend on execution order.
-beforeEach(() => {
-  processTestRequestCalls = [];
+// Reset the test-requests file and capture console.log, so the alert that
+// processTestRequest emits can be observed and tests are order-independent.
+beforeEach(async () => {
+  await fs.writeFile(testRequestsPath, '{}\n');
+  logged = [];
+  console.log = (...args) => logged.push(args.join(' '));
 });
 
-// Require requestRetest after the mock is in place, so it captures the mocked processTestRequest.
-const {response} = require('./requestRetest');
+import {response} from './requestRetest.ts';
 
 after(() => {
+  console.log = originalLog;
   if (savedDBDir !== undefined) {
     process.env.DB_DIR = savedDBDir;
   }
@@ -44,37 +46,40 @@ after(() => {
 
 test('requestRetest rejects a nonexistent report', async () => {
   const body = await response(['999999T9999', 'xyz', 'A reason that is long enough.']);
-  assert.ok(body['response content']['details about your request'].error);
-  assert.equal(processTestRequestCalls.length, 0);
+  assert.ok((body['response content']['details about your request'] as any).error);
+  assert.ok(!logged.some(line => line.includes('request in the API')));
 });
 
 test('requestRetest rejects a superseded report', async () => {
   const body = await response(['260101T0000', 'mix', 'A reason that is long enough.']);
-  const details = body['response content']['details about your request'];
+  const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('later report'));
-  assert.equal(processTestRequestCalls.length, 0);
+  assert.ok(!logged.some(line => line.includes('request in the API')));
 });
 
 test('requestRetest rejects a reason shorter than 20 characters', async () => {
   const body = await response(['260101T0001', 'ct', 'short']);
-  const details = body['response content']['details about your request'];
+  const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('reason'));
-  assert.equal(processTestRequestCalls.length, 0);
+  assert.ok(!logged.some(line => line.includes('request in the API')));
 });
 
 test('requestRetest rejects a reason longer than 100 characters', async () => {
   const longReason = 'x'.repeat(101);
   const body = await response(['260101T0001', 'ct', longReason]);
-  const details = body['response content']['details about your request'];
+  const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('reason'));
-  assert.equal(processTestRequestCalls.length, 0);
+  assert.ok(!logged.some(line => line.includes('request in the API')));
 });
 
 test('requestRetest accepts a valid retest request for the latest report of a page', async () => {
   const body = await response(['260202T0000', 'new', 'A reason that is long enough.']);
-  const details = body['response content']['details about your request'];
+  const details = body['response content']['details about your request'] as any;
   assert.equal(details.error, undefined);
   assert.equal(details['page to be retested'].description, 'Mixed Outcomes Page');
-  assert.equal(processTestRequestCalls.length, 1);
-  assert.equal(processTestRequestCalls[0].testType, 'retest');
+  assert.ok(logged.some(line =>
+    line.startsWith('WARNING (Kilotest: new retest request in the API)')
+    && line.includes('Mixed Outcomes Page')
+    && line.includes('https://example.com/mixed')
+  ));
 });

package/api/{requestRetest.js → requestRetest.ts}

@@ -1,71 +1,78 @@
 /*
-  requestRetest.js
+  requestRetest.ts
   Processes a request to retest a page and returns an acknowledgement.
 */
 
 // IMPORTS
 
-const {getResponseMetadata, getToolsFacts, processTestRequest, thisHost} = require('./util');
-const {getLatestReportExtracts, getReportExtract} = require('../util');
+import {z} from 'zod';
+import {getResponseMetadata, getThisHost, getToolsFacts, processTestRequest} from './util.ts';
+import {getReportExtracts, getReportExtract} from '../util.ts';
+import {requestRetestResponseSchema} from './schemas.ts';
+
+// TYPES
+
+// The response content defined by the response schema.
+type ResponseContent = z.infer<typeof requestRetestResponseSchema>['response content'];
 
 // FUNCTIONS
 
 // Returns the response body.
-exports.response = async args => {
+export const response = async (args: string[]) => {
   const [timeStamp = '', jobID = '', reason = ''] = args;
-  // Initialize the response content.
-  const responseContent = {
-    'details about your request': {},
-    'disposition of your request': null
-  };
+  const thisHost = getThisHost();
   const reasonLength = reason.length;
   // Get data on the report.
   const reportExtract = await getReportExtract(timeStamp, jobID);
-  const {what, url} = reportExtract.error ? {} : reportExtract;
+  // Initialize the response-content properties.
+  let requestDetails: ResponseContent['details about your request'];
+  let requestDisposition: ResponseContent['disposition of your request'] = null;
   // If this failed:
-  if (reportExtract.error) {
-    // Add this to the response content.
-    responseContent['details about your request'] = {
+  if ('error' in reportExtract) {
+    requestDetails = {
       error: 'request invalid: the specified existing report is not an available report'
     };
   }
   // Otherwise, if the report has been superseded:
   else if (
-    (await getLatestReportExtracts())
+    (await getReportExtracts(true))
     .every(extract => extract.timeStamp !== timeStamp || extract.jobID !== jobID)
   ) {
-    // Add this to the response content.
-    responseContent['details about your request'] = {
+    requestDetails = {
       error: 'request invalid: a later report about the page exists'
     };
   }
   // Otherwise, if the encoded reason is too short or too long:
   else if (reasonLength < 20 || reasonLength > 100) {
-    // Add this to the response content.
-    responseContent['details about your request'] = {
+    requestDetails = {
       error: 'request invalid: your reason is not between 20 and 100 characters long'
     }
   }
   // Otherwise, i.e. if getting the report succeeded and the request is valid:
   else {
     // Process the request.
-    await processTestRequest('retest', what, url, reason);
-    // Add details about the request to the response content.
-    responseContent['details about your request'] = {
+    await processTestRequest('retest', reportExtract.description, reportExtract.url, reason);
+    // Add details about the request.
+    requestDetails = {
       'date and time received': new Date().toISOString(),
       'page to be retested': {
-        'description': what,
-        'URL': url
+        'description': reportExtract.description,
+        'URL': reportExtract.url
       },
       'reason why the page should be retested': reason
     };
-    // Add information about the disposition of the request to the response content.
-    responseContent['disposition of your request'] = {
+    // Add information about the disposition of the request.
+    requestDisposition = {
       'what happens next': 'Your request is likely to be approved and processed within 1 hour to 1 day.',
       'how you can check for completion': 'You can call the listReports tool to learn whether the page has been retested and a new report is available.',
       'how a web user can check for completion': `A web user can visit ${thisHost}/listReports.html to learn whether the page has been retested and a new report is available.`
     };
   }
+  // Create the response content.
+  const responseContent: ResponseContent = {
+    'details about your request': requestDetails,
+    'disposition of your request': requestDisposition
+  };
   // Create a response body.
   const body = {
     'tool collection': getToolsFacts(),