@jrpool/kilotest 46.1.2 → 48.0.0

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.ts

@@ -0,0 +1,144 @@
+/*
+  requestRetest.test.ts
+  Tests for api/requestRetest.ts using the fixture corpus.
+*/
+
+// IMPORTS
+
+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;
+const testRequestsPath = path.join(fixtureDBDir, 'jobs', 'testRequests.json');
+let logged: any[] = [];
+const originalLog = console.log;
+
+before(() => {
+  process.env.DB_DIR = fixtureDBDir;
+});
+
+// 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(' '));
+});
+
+import {response} from './requestRetest.ts';
+
+after(() => {
+  console.log = originalLog;
+  if (savedDBDir !== undefined) {
+    process.env.DB_DIR = savedDBDir;
+  }
+  else {
+    delete process.env.DB_DIR;
+  }
+});
+
+// TESTS
+
+test('requestRetest rejects a nonexistent report', async () => {
+  const body = await response(['999999T9999', 'xyz', 'A reason that is long enough.']);
+  const details = body['response content']['details about your request'] as any;
+  assert.ok(details.error.includes('does not exist'));
+  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
+});
+
+test('requestRetest rejects a superseded report', async () => {
+  // 260101T0000-mix is an earlier report of "Mixed Outcomes Page" than 260202T0000-new,
+  // so it is superseded and processTestRequest returns 'superseded', reported via the
+  // disposition rather than details.error.
+  const body = await response(['260101T0000', 'mix', 'A reason that is long enough.']);
+  const details = body['response content']['details about your request'] as any;
+  assert.equal(details.error, undefined);
+  const disposition = body['response content']['disposition of your request'] as any;
+  assert.ok(
+    disposition['what happens next'].includes('a later report about a page with the same description is available.')
+  );
+  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
+});
+
+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'] as any;
+  assert.ok(details.error.includes('reason'));
+  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
+});
+
+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'] as any;
+  assert.ok(details.error.includes('reason'));
+  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
+});
+
+test('requestRetest rejects a report matching a claimed job by description', async () => {
+  // 260101T0001-ct is the "All CantTell Page" report.
+  const claimedPath = path.join(fixtureDBDir, 'jobs', 'claimed', 'clm.json');
+  await fs.writeFile(claimedPath, JSON.stringify({
+    target: {what: 'All CantTell Page', url: 'https://example.com/unrelated'}
+  }));
+  try {
+    const body = await response(['260101T0001', 'ct', 'A reason that is long enough.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.equal(details.error, undefined);
+    const disposition = body['response content']['disposition of your request'] as any;
+    assert.ok(
+      disposition['what happens next']
+      .includes('a request to test a page with the same description is already approved.')
+    );
+  }
+  finally {
+    await fs.unlink(claimedPath);
+  }
+});
+
+test('requestRetest rejects a report matching a queued job by URL', async () => {
+  // 260101T0001-ct's URL is https://example.com/canttell.
+  const queuedPath = path.join(fixtureDBDir, 'jobs', 'queue', 'que.json');
+  await fs.writeFile(queuedPath, JSON.stringify({
+    target: {what: 'Some Other Page', url: 'https://example.com/canttell'}
+  }));
+  try {
+    const body = await response(['260101T0001', 'ct', 'A reason that is long enough.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.equal(details.error, undefined);
+    const disposition = body['response content']['disposition of your request'] as any;
+    assert.ok(
+      disposition['what happens next']
+      .includes('a request to test a page with the same URL is already approved.')
+    );
+  }
+  finally {
+    await fs.unlink(queuedPath);
+  }
+});
+
+test('requestRetest rejects a duplicate request', async () => {
+  await response(['260101T0001', 'ct', 'A reason that is long enough.']);
+  const body = await response(['260101T0001', 'ct', 'A reason that is long enough.']);
+  const details = body['response content']['details about your request'] as any;
+  assert.equal(details.error, undefined);
+  const disposition = body['response content']['disposition of your request'] as any;
+  assert.ok(disposition['what happens next'].includes('an identical request is already awaiting approval.'));
+});
+
+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'] as any;
+  assert.equal(details.error, undefined);
+  assert.equal(details['page to be retested'].description, 'Mixed Outcomes Page');
+  assert.ok(logged.some(line =>
+    line.startsWith('WARNING (Kilotest: new retest request awaits approval)')
+    && line.includes('Mixed Outcomes Page')
+    && line.includes('https://example.com/mixed')
+  ));
+});

package/api/requestRetest.ts

@@ -0,0 +1,119 @@
+/*
+  requestRetest.ts
+  Processes a request to retest a page and returns an acknowledgement.
+*/
+
+// IMPORTS
+
+import {z} from 'zod';
+import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
+import {processTestRequest} 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.
+export const response = async (args: string[]) => {
+  const [timeStamp = '', jobID = '', reason = ''] = args;
+  const thisHost = getThisHost();
+  const reasonLength = reason.length;
+  // Initialize the response-content properties.
+  let requestDetails: ResponseContent['details about your request'];
+  let requestDisposition: ResponseContent['disposition of your request'] = null;
+  // If the encoded reason is too short or too long:
+  if (reasonLength < 20 || reasonLength > 100) {
+    requestDetails = {
+      error: 'request invalid: your reason is not between 20 and 100 characters long'
+    }
+  }
+  // Otherwise, i.e. if the request is facially valid:
+  else {
+    // Process the request. This resolves the cited report's description and URL itself.
+    const processResult = await processTestRequest(reason, {timeStamp, jobID});
+    // If the cited report does not exist:
+    if (processResult.result === 'nonreport') {
+      requestDetails = {
+        error: 'request invalid: the specified report does not exist'
+      };
+    }
+    // Otherwise, i.e. if the cited report was found:
+    else {
+      const {result: requestResult, description, url} = processResult;
+      // Add details about the request.
+      requestDetails = {
+        'date and time received': new Date().toISOString(),
+        'page to be retested': {
+          'description': description,
+          'URL': url
+        },
+        'reason why the page should be retested': reason
+      };
+      // Add information about the disposition of the request.
+      if (requestResult === 'ok') {
+        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.`
+        };
+      }
+      else {
+        const failureFact = 'Your request will not be processed, because ';
+        let failureReason: string;
+        if (requestResult === 'description') {
+          failureReason = 'a request to test a page with the same description is already approved.'
+        }
+        else if (requestResult === 'url') {
+          failureReason = 'a request to test a page with the same URL is already approved.'
+        }
+        else if (requestResult === 'superseded') {
+          failureReason = 'a later report about a page with the same description is available.'
+        }
+        else {
+          failureReason = 'an identical request is already awaiting approval.'
+        }
+        requestDisposition = {
+          'what happens next': `${failureFact}${failureReason}`,
+          'how you can check for completion': 'Not applicable.',
+          'how a web user can check for completion': 'Not applicable.'
+        }
+      }
+    }
+  }
+  // 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(),
+    'tool name': 'requestRetest',
+    'this request': {
+      description: 'Process my request to retest a page. The timeStamp and jobID parameters identify the latest available report about the page. Those parameters were in the response to my earlier listIssues request. The reason property of the request body is the reason why the page should be retested.',
+      method: 'POST',
+      URL: `${thisHost}/api/requestRetest/${timeStamp}/${jobID}`,
+      body: {
+        reason
+      },
+      'closest ancestor request': {
+        'tool name': 'listIssues',
+        description: 'Provide details about one report, including basics about the issues reported in it.',
+        method: 'GET',
+        URL: `${thisHost}/api/listIssues/${timeStamp}/${jobID}`
+      }
+    },
+    'URLs of similar requests for web users': {
+      'this request': `${thisHost}/requestRetestForm.html/${timeStamp}/${jobID}`,
+      'closest ancestor request': `${thisHost}/listIssues.html/${timeStamp}/${jobID}`
+    },
+    'response metadata': getResponseMetadata(),
+    'response content': responseContent
+  };
+  // Return it.
+  return body;
+};