@jrpool/kilotest 46.1.0 → 47.0.1

package/{util.test.js → util.test.ts}

@@ -1,16 +1,18 @@
 /*
-  util.test.js
-  Tests for util.js data-path injection (Phase 1) and utility functions.
+  util.test.ts
+  Tests for util.ts data-path injection (Phase 1) and utility functions.
 */
 
 // IMPORTS
 
-const {test, before, after} = require('node:test');
-const assert = require('node:assert/strict');
-const path = require('node:path');
-const fs = require('node:fs/promises');
-const {
-  annotateReport,
+import {test, before, after} from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import {
+  annotateReportObject,
+  checkCommentDuplicate,
+  checkCommentLength,
   createLock,
   dbPath,
   getAgoDays,
@@ -18,10 +20,10 @@ const {
   getCountString,
   getDateString,
   getDateTime,
-  getEngineList,
+  getEngineNamesString,
   getIssue,
+  errorMessage,
   getJSON,
-  getLatestReportExtracts,
   getMultiReportWhats,
   getNowStamp,
   getObject,
@@ -39,7 +41,6 @@ const {
   getWeightName,
   hiddenReportsPath,
   htmlSafe,
-  isHidden,
   isJobID,
   isReportAvailable,
   isTimeStamp,
@@ -49,19 +50,74 @@ const {
   minifyURL,
   objectSort,
   processTestRequest,
-  recsLock,
-  recsPath,
+  testRequestsLock,
+  testRequestsPath,
   reportsPath,
-  updateRecs
-} = require('./util');
+  addTestRequest
+} from './util.ts';
 
 // TESTS
 
+test('checkCommentLength accepts a comment of exactly 20 characters', () => {
+  const result = checkCommentLength('a'.repeat(20));
+  assert.deepEqual(result, {status: 'ok'});
+});
+
+test('checkCommentLength accepts a comment of exactly 1000 characters', () => {
+  const result = checkCommentLength('a'.repeat(1000));
+  assert.deepEqual(result, {status: 'ok'});
+});
+
+test('checkCommentLength rejects a comment shorter than 20 characters', () => {
+  const result = checkCommentLength('a'.repeat(19));
+  assert.deepEqual(result, {
+    status: 'error',
+    message: 'Your comment was shorter than 20 characters'
+  });
+});
+
+test('checkCommentLength rejects a comment longer than 1000 characters', () => {
+  const result = checkCommentLength('a'.repeat(1001));
+  assert.deepEqual(result, {
+    status: 'error',
+    message: 'Your comment was longer than 1000 characters'
+  });
+});
+
+test('checkCommentDuplicate accepts a comment with no existing comments', () => {
+  const result = checkCommentDuplicate([], 'a'.repeat(20));
+  assert.deepEqual(result, {status: 'ok'});
+});
+
+test('checkCommentDuplicate rejects a comment repeating one submitted within the last 1000 seconds', () => {
+  const content = 'a'.repeat(20);
+  const comments = [{timeStamp: getNowStamp(), content}];
+  const result = checkCommentDuplicate(comments, content);
+  assert.deepEqual(result, {
+    status: 'error',
+    message: 'Your comment repeats a recently submitted one, but you are welcome to submit a different comment'
+  });
+});
+
+test('checkCommentDuplicate accepts a comment repeating one submitted more than 1000 seconds ago', () => {
+  const content = 'a'.repeat(20);
+  const oldTimeStamp = getTimeStamp(new Date(Date.now() - 2000000));
+  const comments = [{timeStamp: oldTimeStamp, content}];
+  const result = checkCommentDuplicate(comments, content);
+  assert.deepEqual(result, {status: 'ok'});
+});
+
+test('checkCommentDuplicate accepts a comment that differs from a recent one', () => {
+  const comments = [{timeStamp: getNowStamp(), content: 'a'.repeat(20)}];
+  const result = checkCommentDuplicate(comments, 'b'.repeat(20));
+  assert.deepEqual(result, {status: 'ok'});
+});
+
 test('dbPath defaults to the project db directory when DB_DIR is unset', () => {
   const saved = process.env.DB_DIR;
   delete process.env.DB_DIR;
   try {
-    assert.equal(dbPath(), path.join(__dirname, 'db'));
+    assert.equal(dbPath(), path.join(import.meta.dirname, 'db'));
   }
   finally {
     if (saved !== undefined) {
@@ -86,12 +142,12 @@ test('dbPath honors DB_DIR when it is set', () => {
   }
 });
 
-test('jobsPath, recsPath, reportsPath, and hiddenReportsPath derive from DB_DIR', () => {
+test('jobsPath, testRequestsPath, reportsPath, and hiddenReportsPath derive from DB_DIR', () => {
   const saved = process.env.DB_DIR;
   process.env.DB_DIR = '/tmp/kilotest-fixtures';
   try {
     assert.equal(jobsPath(), path.join('/tmp/kilotest-fixtures', 'jobs'));
-    assert.equal(recsPath(), path.join('/tmp/kilotest-fixtures', 'jobs', 'recs.json'));
+    assert.equal(testRequestsPath(), path.join('/tmp/kilotest-fixtures', 'jobs', 'testRequests.json'));
     assert.equal(reportsPath(), path.join('/tmp/kilotest-fixtures', 'reports'));
     assert.equal(hiddenReportsPath(), path.join('/tmp/kilotest-fixtures', 'hiddenReports'));
   }
@@ -134,7 +190,7 @@ test('getAgoDays returns null for an invalid string', () => {
 });
 
 test('getAgoDays returns null for a non-string non-Date argument', () => {
-  assert.equal(getAgoDays(42), null);
+  assert.equal(getAgoDays(42 as any), null);
 });
 
 test('getAgoDays returns 0 for the current time', () => {
@@ -190,20 +246,26 @@ test('getIssue returns null for an unknown engine', () => {
   assert.equal(getIssue('nonexistentEngine', 'anyRule'), null);
 });
 
+test('errorMessage returns the message of an Error instance', () => {
+  assert.equal(errorMessage(new Error('something went wrong')), 'something went wrong');
+});
+
+test('errorMessage returns the string representation of a non-Error value', () => {
+  assert.equal(errorMessage('bare string'), 'bare string');
+});
+
 test('getJSON returns a JSON string with a trailing newline', () => {
   assert.equal(getJSON({a: 1}), '{\n  "a": 1\n}\n');
 });
 
 test('getObject returns the parsed object for a valid JSON file', async () => {
-  const result = await getObject(path.join(__dirname, 'package.json'));
-  assert.ok(typeof result === 'object');
-  assert.equal(result.name, '@jrpool/kilotest');
+  const result = await getObject(path.join(import.meta.dirname, 'package.json'));
+  assert.ok(typeof result === 'object' && result !== null);
+  assert.equal((result as {name: unknown}).name, '@jrpool/kilotest');
 });
 
-test('getObject returns an error string for a nonexistent file', async () => {
-  const result = await getObject('/tmp/nonexistent-file.json');
-  assert.equal(typeof result, 'string');
-  assert.ok(result.startsWith('ERROR'));
+test('getObject throws for a nonexistent file', async () => {
+  await assert.rejects(getObject('/tmp/nonexistent-file.json'), /not readable/);
 });
 
 test('getNowStamp returns an 11-character time stamp', () => {
@@ -264,10 +326,8 @@ test('isTimeStamp returns false for an invalid time stamp', () => {
   assert.equal(isTimeStamp('invalid'), false);
 });
 
-test('isURL returns a URL object for a valid HTTPS URL', () => {
-  const result = isURL('https://example.com/page');
-  assert.ok(result instanceof URL);
-  assert.equal(result.hostname, 'example.com');
+test('isURL returns true for a valid HTTPS URL', () => {
+  assert.equal(isURL('https://example.com/page'), true);
 });
 
 test('isURL returns false for a non-HTTPS URL', () => {
@@ -304,11 +364,11 @@ test('objectSort sorts objects numerically descending', () => {
   assert.deepEqual(sorted.map(i => i.count), [3, 2, 1]);
 });
 
-// TESTS FOR processTestRequest, annotateReport, AND isReportAvailable
+// TESTS FOR processTestRequest AND isReportAvailable
 
 // These tests use the fixture database directory and the real web/requestTest template.
-const fixtureDbDir = path.join(__dirname, 'test', 'fixtures', 'db');
-const requestTestDir = path.join(__dirname, 'web', 'requestTest');
+import {fixtureDBDir as fixtureDbDir} from './test/dbFixture.ts';
+const requestTestDir = path.join(import.meta.dirname, 'web', 'requestTest');
 const savedDbDir = process.env.DB_DIR;
 
 before(() => {
@@ -325,20 +385,20 @@ after(() => {
 });
 
 test('getPageData returns page data for a valid report', async () => {
-  const data = await getPageData('260101T0000', 'mix');
-  assert.equal(data.what, 'Mixed Outcomes Page');
+  const data = await getPageData('260101T0000', 'mix') as any;
+  assert.equal(data.description, 'Mixed Outcomes Page');
   assert.equal(data.url, 'https://example.com/mixed');
   assert.equal(typeof data.daysAgo, 'number');
 });
 
 test('getPageData returns an error for a nonexistent report', async () => {
-  const data = await getPageData('999999T9999', 'xxx');
+  const data = await getPageData('999999T9999', 'xxx') as any;
   assert.ok(data.error);
 });
 
 test('getPageDataStrings returns HTML strings for a valid report', async () => {
-  const strings = await getPageDataStrings('260101T0000', 'mix');
-  assert.equal(strings.what, 'Mixed Outcomes Page');
+  const strings = await getPageDataStrings('260101T0000', 'mix') as any;
+  assert.equal(strings.description, 'Mixed Outcomes Page');
   assert.equal(strings.url, 'https://example.com/mixed');
   assert.equal(strings.urlLink, '<a href="https://example.com/mixed">https://example.com/mixed</a>');
   assert.ok(strings.testInfo.includes('by job <code>mix</code>'));
@@ -346,8 +406,8 @@ test('getPageDataStrings returns HTML strings for a valid report', async () => {
 });
 
 test('getPageDataStrings returns different testInfo for a different timeStamp', async () => {
-  const strings = await getPageDataStrings('260101T0001', 'ct');
-  assert.equal(strings.what, 'All CantTell Page');
+  const strings = await getPageDataStrings('260101T0001', 'ct') as any;
+  assert.equal(strings.description, 'All CantTell Page');
   assert.ok(strings.testInfo.includes('by job <code>ct</code>'));
   assert.ok(strings.testInfo.includes('2026-01-01 at 00:01'));
 });
@@ -359,84 +419,128 @@ test('getPageDataStrings returns an error for a nonexistent report', async () =>
 
 test('getPageDataStrings uses provided pageData instead of reading the report', async () => {
   const strings = await getPageDataStrings('260101T0000', 'mix', {
-    what: 'Custom Page',
+    description: 'Custom Page',
     url: 'https://custom.com',
     daysAgo: 1
-  });
-  assert.equal(strings.what, 'Custom Page');
+  }) as any;
+  assert.equal(strings.description, 'Custom Page');
   assert.equal(strings.url, 'https://custom.com');
   assert.ok(strings.testInfo.includes('1 day ago'));
 });
 
 test('processTestRequest returns an error for an invalid test type', async () => {
-  const result = await processTestRequest('invalid', requestTestDir, 'Page', 'https://example.com', 'because');
+  const result: any = await processTestRequest('invalid', requestTestDir, 'Page', 'https://example.com', 'because');
   assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Invalid recommendation');
+  assert.equal(result.message, 'Invalid request');
 });
 
 test('processTestRequest returns an error for an invalid URL', async () => {
-  const result = await processTestRequest('test', requestTestDir, 'Page', 'not-a-url', 'because');
+  const result: any = await processTestRequest('test', requestTestDir, 'Page', 'not-a-url', 'because');
   assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Invalid recommendation');
+  assert.equal(result.message, 'Invalid request');
 });
 
 test('processTestRequest returns an error for a short reason', async () => {
-  const result = await processTestRequest('test', requestTestDir, 'Page', 'https://example.com', 'abc');
+  const result: any = await processTestRequest('test', requestTestDir, 'Page', 'https://example.com', 'abc');
   assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Invalid recommendation');
+  assert.equal(result.message, 'Invalid request');
 });
 
 test('processTestRequest returns an error for a missing description', async () => {
-  const result = await processTestRequest('test', requestTestDir, '', 'https://example.com', 'because');
+  const result: any = await processTestRequest('test', requestTestDir, '', 'https://example.com', 'because');
   assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Invalid recommendation');
+  assert.equal(result.message, 'Invalid request');
 });
 
 test('processTestRequest returns an error for a mismatched directory name', async () => {
-  const result = await processTestRequest('test', '/tmp/wrongDir', 'Page', 'https://example.com', 'because');
+  const result: any = await processTestRequest('test', '/tmp/wrongDir', 'Page', 'https://example.com', 'because');
   assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Invalid recommendation');
+  assert.equal(result.message, 'Invalid request');
 });
 
+
 test('processTestRequest succeeds and populates the template for a valid request', {timeout: 500}, async () => {
-  // Reset recs.json to empty before the test.
-  await fs.writeFile(recsPath(), '{}\n');
-  const result = await processTestRequest('test', requestTestDir, 'Example Page', 'https://example.com', 'because accessibility');
+  // Reset testRequests.json to empty before the test.
+  await fs.writeFile(testRequestsPath(), '{}\n');
+  const result: any = await processTestRequest('test', requestTestDir, 'Example Page', 'https://example.com', 'because accessibility');
   assert.equal(result.status, 'ok');
   assert.ok(result.answerPage.includes('Example Page'));
   assert.ok(result.answerPage.includes('because accessibility'));
-  // Clean up recs.json.
-  await fs.writeFile(recsPath(), '{}\n');
+  // Clean up testRequests.json.
+  await fs.writeFile(testRequestsPath(), '{}\n');
 });
 
 test('processTestRequest returns a duplicate error for a repeated request', {timeout: 500}, async () => {
-  // Reset recs.json to empty, then make a successful request.
-  await fs.writeFile(recsPath(), '{}\n');
+  // Reset testRequests.json to empty, then make a successful request.
+  await fs.writeFile(testRequestsPath(), '{}\n');
   await processTestRequest('test', requestTestDir, 'Example Page', 'https://example.com', 'because accessibility');
   // Repeat the same request.
-  const result = await processTestRequest('test', requestTestDir, 'Example Page', 'https://example.com', 'another reason');
+  const result: any = await processTestRequest('test', requestTestDir, 'Example Page', 'https://example.com', 'another reason');
   assert.equal(result.status, 'error');
-  assert.equal(result.message, 'Duplicate recommendation');
-  // Clean up recs.json.
-  await fs.writeFile(recsPath(), '{}\n');
+  assert.equal(result.message, 'Duplicate request');
+  // Clean up testRequests.json.
+  await fs.writeFile(testRequestsPath(), '{}\n');
 });
 
-test('annotateReport returns an error for a nonexistent report', async () => {
-  const result = await annotateReport('990101T0000', 'xxx');
-  assert.ok(typeof result === 'string');
-  assert.ok(result.includes('missing'));
+test('annotateReportObject annotates a report object in place without reading or writing a file', async () => {
+  // A report object that was never written to disk (e.g. one just received from a worker,
+  // as in index.ts's worker/report handler, which annotates before the first write).
+  const report: any = {
+    id: '990101T0099-obj',
+    target: {what: 'Object Page', url: 'https://example.com/object'},
+    acts: [
+      {
+        type: 'test',
+        which: 'alfa',
+        result: {
+          standardResult: {
+            instances: [
+              // A classifiable rule.
+              {ruleID: 'r11', what: 'The link does not have an accessible name', outcome: 'failed', catalogIndex: '0'},
+              // An unclassifiable rule.
+              {ruleID: 'unknownRule123', what: 'Unknown', outcome: 'failed', catalogIndex: '0'}
+            ]
+          }
+        }
+      }
+    ],
+    jobData: {endTime: '26-01-01T00:00'},
+    catalog: {}
+  };
+  await annotateReportObject(report);
+  const instances = report.acts[0].result.standardResult.instances;
+  assert.equal(instances[0].issueID, 'linkNoText');
+  assert.equal(instances[1].issueID, undefined);
+  assert.deepEqual(report.jobData.issuelessRules, ['alfa:unknownRule123']);
 });
 
-test('annotateReport annotates a valid report and returns an empty string', async () => {
-  const reportPath = path.join(fixtureDbDir, 'reports', '260101T0000-mix.json');
-  const original = await fs.readFile(reportPath, 'utf8');
-  try {
-    const result = await annotateReport('260101T0000', 'mix');
-    assert.equal(result, '');
-  }
-  finally {
-    await fs.writeFile(reportPath, original);
-  }
+test('annotateReportObject handles a test act with no standardResult instances', async () => {
+  const report: any = {
+    id: '990101T0098-ni',
+    target: {what: 'Test', url: 'https://example.com'},
+    acts: [
+      {type: 'test', which: 'axe', result: {standardResult: {instances: []}}},
+      {type: 'other'}
+    ],
+    jobData: {endTime: '26-01-01T00:00'},
+    catalog: {}
+  };
+  await annotateReportObject(report);
+  assert.deepEqual(report.jobData.issuelessRules, []);
+});
+
+test('annotateReportObject handles a test act with no standardResult', async () => {
+  const report: any = {
+    id: '990101T0097-ns',
+    target: {what: 'Test', url: 'https://example.com'},
+    acts: [
+      {type: 'test', which: 'axe', result: {}}
+    ],
+    jobData: {endTime: '26-01-01T00:00'},
+    catalog: {}
+  };
+  await annotateReportObject(report);
+  assert.deepEqual(report.jobData.issuelessRules, []);
 });
 
 test('isReportAvailable returns true for a known page description', async () => {
@@ -457,18 +561,19 @@ test('isReportAvailable returns false for an unknown page and URL', async () =>
 // TESTS FOR REMAINING BRANCH COVERAGE
 
 test('getJobNames creates missing job directories and returns empty arrays', async () => {
-  const os = require('node:os');
+  const os = await import('node:os');
   const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kilotest-jobnames-'));
   const tmpDbDir = path.join(tmpRoot, 'db');
   const savedDbDir = process.env.DB_DIR;
   process.env.DB_DIR = tmpDbDir;
   try {
-    const {getJobNames} = require('./util');
+    const {getJobNames} = await import('./util.ts');
     const result = await getJobNames();
-    assert.equal(typeof result, 'object');
-    assert.deepEqual(result.queue, []);
-    assert.deepEqual(result.claimed, []);
-    assert.deepEqual(result.failed, []);
+    assert.ok(typeof result === 'object' && result !== null);
+    const jobNames = result as Record<string, string[]>;
+    assert.deepEqual(jobNames.queue, []);
+    assert.deepEqual(jobNames.claimed, []);
+    assert.deepEqual(jobNames.failed, []);
     // Verify the directories were created.
     for (const category of ['queue', 'claimed', 'failed']) {
       const stat = await fs.stat(path.join(tmpDbDir, 'jobs', category));
@@ -481,8 +586,8 @@ test('getJobNames creates missing job directories and returns empty arrays', asy
   }
 });
 
-test('getJobNames returns an error when a job directory is a file, not a directory', async () => {
-  const os = require('node:os');
+test('getJobNames throws when a job directory is a file, not a directory', async () => {
+  const os = await import('node:os');
   const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kilotest-jobnames-err-'));
   const tmpJobsDir = path.join(tmpRoot, 'db', 'jobs');
   await fs.mkdir(tmpJobsDir, {recursive: true});
@@ -491,10 +596,8 @@ test('getJobNames returns an error when a job directory is a file, not a directo
   const savedDbDir = process.env.DB_DIR;
   process.env.DB_DIR = path.join(tmpRoot, 'db');
   try {
-    const {getJobNames} = require('./util');
-    const result = await getJobNames();
-    assert.equal(typeof result, 'string');
-    assert.ok(result.startsWith('ERROR'));
+    const {getJobNames} = await import('./util.ts');
+    await assert.rejects(getJobNames(), /not readable/);
   }
   finally {
     process.env.DB_DIR = savedDbDir;
@@ -502,28 +605,46 @@ test('getJobNames returns an error when a job directory is a file, not a directo
   }
 });
 
-test('getObject returns an error for a file that is not valid JSON', async () => {
-  const tmpFile = path.join(require('node:os').tmpdir(), 'kilotest-test-invalid.json');
-  require('node:fs').writeFileSync(tmpFile, 'not json');
-  const result = await getObject(tmpFile);
-  assert.equal(typeof result, 'string');
-  assert.ok(result.startsWith('ERROR'));
-  require('node:fs').unlinkSync(tmpFile);
+test('getObject throws for a file that is not valid JSON', async () => {
+  const tmpFile = path.join((await import('node:os')).tmpdir(), 'kilotest-test-invalid.json');
+  (await import('node:fs')).writeFileSync(tmpFile, 'not json');
+  try {
+    await assert.rejects(getObject(tmpFile), /not JSON/);
+  }
+  finally {
+    (await import('node:fs')).unlinkSync(tmpFile);
+  }
 });
 
-test('getRecs creates an empty recommendations file and returns an error when it is missing', async () => {
-  const tmpDir = require('node:os').tmpdir() + '/kilotest-missing-recs-test';
-  const fsSync = require('node:fs');
+test('getTestRequests creates and returns an empty test-requests object when the file is missing', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-missing-testrequests-test';
+  const fsSync = await import('node:fs');
   fsSync.mkdirSync(tmpDir + '/jobs', {recursive: true});
   const savedDbDir = process.env.DB_DIR;
   process.env.DB_DIR = tmpDir;
   try {
-    const {getRecs} = require('./util');
-    const result = await getRecs();
-    assert.equal(typeof result, 'string');
-    assert.ok(result.startsWith('ERROR'));
+    const {getTestRequests} = await import('./util.ts');
+    const result = await getTestRequests();
+    assert.deepEqual(result, {});
     // Verify the empty file was created.
-    assert.ok(fsSync.existsSync(tmpDir + '/jobs/recs.json'));
+    assert.ok(fsSync.existsSync(tmpDir + '/jobs/testRequests.json'));
+  }
+  finally {
+    process.env.DB_DIR = savedDbDir;
+    fsSync.rmSync(tmpDir, {recursive: true});
+  }
+});
+
+test('getTestRequests throws when the test-requests file is not readable for a reason other than being missing', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-testrequests-unreadable-test';
+  const fsSync = await import('node:fs');
+  // Create a directory where the test-requests file should be, causing EISDIR rather than ENOENT.
+  fsSync.mkdirSync(tmpDir + '/jobs/testRequests.json', {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = tmpDir;
+  try {
+    const {getTestRequests} = await import('./util.ts');
+    await assert.rejects(getTestRequests(), /not readable/);
   }
   finally {
     process.env.DB_DIR = savedDbDir;
@@ -531,27 +652,25 @@ test('getRecs creates an empty recommendations file and returns an error when it
   }
 });
 
-test('getRecs returns an error when the recommendations file is not JSON', async () => {
-  const tmpDir = require('node:os').tmpdir() + '/kilotest-recs-test';
-  require('node:fs').mkdirSync(tmpDir + '/jobs', {recursive: true});
-  require('node:fs').writeFileSync(tmpDir + '/jobs/recs.json', 'not json');
+test('getTestRequests throws when the test-requests file is not JSON', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-testrequests-test';
+  (await import('node:fs')).mkdirSync(tmpDir + '/jobs', {recursive: true});
+  (await import('node:fs')).writeFileSync(tmpDir + '/jobs/testRequests.json', 'not json');
   const savedDbDir = process.env.DB_DIR;
   process.env.DB_DIR = tmpDir;
   try {
-    const {getRecs} = require('./util');
-    const result = await getRecs();
-    assert.equal(typeof result, 'string');
-    assert.ok(result.startsWith('ERROR'));
+    const {getTestRequests} = await import('./util.ts');
+    await assert.rejects(getTestRequests(), /not JSON/);
   }
   finally {
     process.env.DB_DIR = savedDbDir;
-    require('node:fs').rmSync(tmpDir, {recursive: true});
+    (await import('node:fs')).rmSync(tmpDir, {recursive: true});
   }
 });
 
 test('getPOSTData resolves with parsed query for form-urlencoded requests', async () => {
-  const {Readable} = require('node:stream');
-  const {getPOSTData} = require('./util');
+  const {Readable} = await import('node:stream');
+  const {getPOSTData} = await import('./util.ts');
   const body = 'target=Page&why=Because';
   const req = Object.assign(new Readable({
     read() {
@@ -559,14 +678,14 @@ test('getPOSTData resolves with parsed query for form-urlencoded requests', asyn
       this.push(null);
     }
   }), {headers: {'content-type': 'application/x-www-form-urlencoded'}});
-  const result = await getPOSTData(req);
+  const result: any = await getPOSTData(req as any);
   assert.equal(result.target, 'Page');
   assert.equal(result.why, 'Because');
 });
 
-test('isRecommendable returns "claimed" for a URL in a claimed job', async () => {
-  const tmpDir = require('node:os').tmpdir() + '/kilotest-recommendable-test';
-  const fsSync = require('node:fs');
+test('getRequestability returns "claimed" for a URL in a claimed job', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-requestability-test';
+  const fsSync = await import('node:fs');
   fsSync.mkdirSync(tmpDir + '/jobs/claimed', {recursive: true});
   fsSync.mkdirSync(tmpDir + '/jobs/queue', {recursive: true});
   fsSync.mkdirSync(tmpDir + '/jobs/failed', {recursive: true});
@@ -576,8 +695,8 @@ test('isRecommendable returns "claimed" for a URL in a claimed job', async () =>
   const savedDbDir = process.env.DB_DIR;
   process.env.DB_DIR = tmpDir;
   try {
-    const {isRecommendable} = require('./util');
-    const result = await isRecommendable('https://example.com/test');
+    const {getRequestability} = await import('./util.ts');
+    const result = await getRequestability('https://example.com/test');
     assert.equal(result, 'claimed');
   }
   finally {
@@ -586,9 +705,9 @@ test('isRecommendable returns "claimed" for a URL in a claimed job', async () =>
   }
 });
 
-test('isRecommendable returns "queued" for a URL in a queued job', async () => {
-  const tmpDir = require('node:os').tmpdir() + '/kilotest-recommendable-test';
-  const fsSync = require('node:fs');
+test('getRequestability returns "queued" for a URL in a queued job', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-requestability-test';
+  const fsSync = await import('node:fs');
   fsSync.mkdirSync(tmpDir + '/jobs/claimed', {recursive: true});
   fsSync.mkdirSync(tmpDir + '/jobs/queue', {recursive: true});
   fsSync.mkdirSync(tmpDir + '/jobs/failed', {recursive: true});
@@ -598,8 +717,8 @@ test('isRecommendable returns "queued" for a URL in a queued job', async () => {
   const savedDbDir = process.env.DB_DIR;
   process.env.DB_DIR = tmpDir;
   try {
-    const {isRecommendable} = require('./util');
-    const result = await isRecommendable('https://example.com/test');
+    const {getRequestability} = await import('./util.ts');
+    const result = await getRequestability('https://example.com/test');
     assert.equal(result, 'queued');
   }
   finally {
@@ -608,17 +727,17 @@ test('isRecommendable returns "queued" for a URL in a queued job', async () => {
   }
 });
 
-test('isRecommendable returns empty string for a URL with no matching jobs', async () => {
-  const tmpDir = require('node:os').tmpdir() + '/kilotest-recommendable-test';
-  const fsSync = require('node:fs');
+test('getRequestability returns empty string for a URL with no matching jobs', async () => {
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-requestability-test';
+  const fsSync = await import('node:fs');
   fsSync.mkdirSync(tmpDir + '/jobs/claimed', {recursive: true});
   fsSync.mkdirSync(tmpDir + '/jobs/queue', {recursive: true});
   fsSync.mkdirSync(tmpDir + '/jobs/failed', {recursive: true});
   const savedDbDir = process.env.DB_DIR;
   process.env.DB_DIR = tmpDir;
   try {
-    const {isRecommendable} = require('./util');
-    const result = await isRecommendable('https://example.com/no-match');
+    const {getRequestability} = await import('./util.ts');
+    const result = await getRequestability('https://example.com/no-match');
     assert.equal(result, '');
   }
   finally {
@@ -633,22 +752,22 @@ test('isURL returns false for a malformed URL', () => {
 
 test('objectSort returns 0 for an unknown sort type', () => {
   const items = [{name: 'a'}, {name: 'b'}];
-  const sorted = objectSort(items, 'name', 'unknownType');
+  const sorted = objectSort(items, 'name', 'unknownType' as any);
   assert.equal(sorted.length, 2);
 });
 
 test('getReport returns an error for an invalid report', async () => {
-  const tmpDir = require('node:os').tmpdir() + '/kilotest-invalid-report-test';
-  const fsSync = require('node:fs');
+  const tmpDir = (await import('node:os')).tmpdir() + '/kilotest-invalid-report-test';
+  const fsSync = await import('node:fs');
   fsSync.mkdirSync(tmpDir + '/reports', {recursive: true});
   fsSync.writeFileSync(tmpDir + '/reports/260101T0000-bad.json', JSON.stringify({notValid: true}));
   const savedDbDir = process.env.DB_DIR;
   process.env.DB_DIR = tmpDir;
   try {
-    const {getReport} = require('./util');
-    const result = await getReport('260101T0000', 'bad');
+    const {getReport} = await import('./util.ts');
+    const result = await getReport('260101T0000', 'bad') as any;
     assert.ok(result.error);
-    assert.ok(result.error.includes('invalid'));
+    assert.ok(result.error.includes('not usable'));
   }
   finally {
     process.env.DB_DIR = savedDbDir;
@@ -657,11 +776,27 @@ test('getReport returns an error for an invalid report', async () => {
 });
 
 test('getReportData returns an error for a nonexistent report', async () => {
-  const {getReportData} = require('./util');
-  const result = await getReportData('990101T0000', 'xxx');
+  const {getReportData} = await import('./util.ts');
+  const result: any = await getReportData('990101T0000', 'xxx');
   assert.ok(result.error);
 });
 
+test('getReportData falls back to the engine ID for an unknown prevented engine', async () => {
+  const {getReportData} = await import('./util.ts');
+  const prvJSON = await fs.readFile(path.join(reportsPath(), '260101T0006-prv.json'), 'utf8');
+  const report = JSON.parse(prvJSON);
+  report.jobData.preventions.unknownEngine = 'mystery failure';
+  const reportPath = path.join(reportsPath(), '260103T0000-unk.json');
+  await fs.writeFile(reportPath, JSON.stringify(report));
+  try {
+    const result: any = await getReportData('260103T0000', 'unk');
+    assert.ok(result.preventedEngineNames.includes('unknownEngine'));
+  }
+  finally {
+    await fs.unlink(reportPath);
+  }
+});
+
 // TESTS FOR REMAINING BRANCH COVERAGE IN util.js
 
 test('getAgoDays returns null for an invalid Date object', () => {
@@ -685,15 +820,15 @@ test('getIssue returns an issue ID for a variable rule pattern match', () => {
   assert.equal(result, 'duplicateAttribute');
 });
 
-test('getTimeString returns null for an invalid time portion', () => {
-  const {getDateTimeString} = require('./util');
+test('getDateTimeString describes an invalid time stamp as unknown', async () => {
+  const {getDateTimeString} = await import('./util.ts');
   const result = getDateTimeString('999999T9999');
-  assert.ok(result.includes('null'));
+  assert.equal(result, 'an unknown date at an unknown time');
 });
 
 test('getPOSTData resolves with parsed JSON for application/json requests', async () => {
-  const {Readable} = require('node:stream');
-  const {getPOSTData} = require('./util');
+  const {Readable} = await import('node:stream');
+  const {getPOSTData} = await import('./util.ts');
   const body = JSON.stringify({target: 'Page', why: 'Because'});
   const req = Object.assign(new Readable({
     read() {
@@ -701,13 +836,13 @@ test('getPOSTData resolves with parsed JSON for application/json requests', asyn
       this.push(null);
     }
   }), {headers: {'content-type': 'application/json'}});
-  const result = await getPOSTData(req);
+  const result: any = await getPOSTData(req as any);
   assert.equal(result.target, 'Page');
 });
 
 test('getPOSTData resolves with parsed query for body-type form-urlencoded requests', async () => {
-  const {Readable} = require('node:stream');
-  const {getPOSTData} = require('./util');
+  const {Readable} = await import('node:stream');
+  const {getPOSTData} = await import('./util.ts');
   const body = 'target=Page&why=Because';
   const req = Object.assign(new Readable({
     read() {
@@ -715,131 +850,93 @@ test('getPOSTData resolves with parsed query for body-type form-urlencoded reque
       this.push(null);
     }
   }), {headers: {'body-type': 'application/x-www-form-urlencoded'}});
-  const result = await getPOSTData(req);
+  const result: any = await getPOSTData(req as any);
   assert.equal(result.target, 'Page');
   assert.equal(result.why, 'Because');
 });
 
 test('getPOSTData resolves with null for an unknown content type', async () => {
-  const {Readable} = require('node:stream');
-  const {getPOSTData} = require('./util');
+  const {Readable} = await import('node:stream');
+  const {getPOSTData} = await import('./util.ts');
   const req = Object.assign(new Readable({
     read() {
       this.push(Buffer.from('data'));
       this.push(null);
     }
   }), {headers: {}});
-  const result = await getPOSTData(req);
+  const result: any = await getPOSTData(req as any);
+  assert.equal(result, null);
+});
+
+test('getPOSTData resolves with null for a malformed JSON body', async () => {
+  const {Readable} = await import('node:stream');
+  const {getPOSTData} = await import('./util.ts');
+  const req = Object.assign(new Readable({
+    read() {
+      this.push(Buffer.from('{not valid json'));
+      this.push(null);
+    }
+  }), {headers: {'content-type': 'application/json'}});
+  const result: any = await getPOSTData(req as any);
   assert.equal(result, null);
 });
 
-test('getEngineNamesString falls back to the engine ID for an unknown engine', () => {
-  const {getEngineNamesString} = require('./util');
+test('getEngineNamesString falls back to the engine ID for an unknown engine', async () => {
+  const {getEngineNamesString} = await import('./util.ts');
   const result = getEngineNamesString(new Set(['unknownEngine']));
   assert.equal(result, 'unknownEngine');
 });
 
-test('getPathID returns the catalog pathID when catalogIndex is truthy', () => {
-  const {getPathID} = require('./util');
-  const catalog = {'0': {pathID: '/html/body/div'}};
+test('getPathID returns the catalog pathID when catalogIndex is truthy', async () => {
+  const {getPathID} = await import('./util.ts');
+  const catalog = {'0': {tagName: 'div', pathID: '/html/body/div'}};
   assert.equal(getPathID(catalog, '0', '/fallback'), '/html/body/div');
 });
 
-test('getPathID returns the fallback pathID when catalogIndex is truthy but catalogItem has no pathID', () => {
-  const {getPathID} = require('./util');
-  const catalog = {'0': {tagName: 'div'}};
+test('getPathID returns the fallback pathID when catalogIndex is truthy but catalogItem has no pathID', async () => {
+  const {getPathID} = await import('./util.ts');
+  const catalog = {'0': {tagName: 'div', pathID: ''}};
   assert.equal(getPathID(catalog, '0', '/fallback'), '/fallback');
 });
 
-test('getPathID returns /html when catalogIndex is truthy but catalogItem and pathID are both missing', () => {
-  const {getPathID} = require('./util');
+test('getPathID returns /html when catalogIndex is truthy but catalogItem and pathID are both missing', async () => {
+  const {getPathID} = await import('./util.ts');
   const catalog = {};
-  assert.equal(getPathID(catalog, '0', null), '/html');
+  assert.equal(getPathID(catalog, '0', null as any), '/html');
 });
 
-test('getPathID returns /html when catalogIndex is falsy and pathID is null', () => {
-  const {getPathID} = require('./util');
-  assert.equal(getPathID({}, null, null), '/html');
+test('getPathID returns /html when catalogIndex is falsy and pathID is null', async () => {
+  const {getPathID} = await import('./util.ts');
+  assert.equal(getPathID({}, null as any, null as any), '/html');
 });
 
-test('isValidReport returns false for a report with a test act using an unknown engine', () => {
-  const {isValidReport} = require('./util');
+test('isUsableReport returns false for a report with a test act using an unknown engine', async () => {
+  const {isUsableReport} = await import('./util.ts');
   const report = {
     target: {what: 'Test', url: 'https://example.com'},
     acts: [{type: 'test', which: 'unknownEngine'}],
     jobData: {endTime: '26-01-01T00:00'},
     catalog: {}
   };
-  assert.equal(isValidReport(report), false);
+  assert.equal(isUsableReport(report), false);
 });
 
-test('isValidReport returns true for a report with a non-test act', () => {
-  const {isValidReport} = require('./util');
+test('isUsableReport returns true for a report with a non-test act', async () => {
+  const {isUsableReport} = await import('./util.ts');
   const report = {
     target: {what: 'Test', url: 'https://example.com'},
     acts: [{type: 'other'}],
     jobData: {endTime: '26-01-01T00:00'},
     catalog: {}
   };
-  assert.equal(isValidReport(report), true);
-});
-
-test('annotateReport handles a test act with no standardResult instances', async () => {
-  const tmpDir = require('node:os').tmpdir() + '/kilotest-no-instances-test';
-  const fsSync = require('node:fs');
-  fsSync.mkdirSync(tmpDir + '/reports', {recursive: true});
-  const report = {
-    target: {what: 'Test', url: 'https://example.com'},
-    acts: [
-      {type: 'test', which: 'axe', result: {standardResult: {instances: []}}},
-      {type: 'other'}
-    ],
-    jobData: {endTime: '26-01-01T00:00'},
-    catalog: {}
-  };
-  fsSync.writeFileSync(tmpDir + '/reports/260101T0000-ni.json', JSON.stringify(report));
-  const savedDbDir = process.env.DB_DIR;
-  process.env.DB_DIR = tmpDir;
-  try {
-    const result = await annotateReport('260101T0000', 'ni');
-    assert.equal(result, '');
-  }
-  finally {
-    process.env.DB_DIR = savedDbDir;
-    fsSync.rmSync(tmpDir, {recursive: true});
-  }
-});
-
-test('annotateReport handles a test act with no standardResult', async () => {
-  const tmpDir = require('node:os').tmpdir() + '/kilotest-no-standard-test';
-  const fsSync = require('node:fs');
-  fsSync.mkdirSync(tmpDir + '/reports', {recursive: true});
-  const report = {
-    target: {what: 'Test', url: 'https://example.com'},
-    acts: [
-      {type: 'test', which: 'axe', result: {}}
-    ],
-    jobData: {endTime: '26-01-01T00:00'},
-    catalog: {}
-  };
-  fsSync.writeFileSync(tmpDir + '/reports/260101T0000-ns.json', JSON.stringify(report));
-  const savedDbDir = process.env.DB_DIR;
-  process.env.DB_DIR = tmpDir;
-  try {
-    const result = await annotateReport('260101T0000', 'ns');
-    assert.equal(result, '');
-  }
-  finally {
-    process.env.DB_DIR = savedDbDir;
-    fsSync.rmSync(tmpDir, {recursive: true});
-  }
+  assert.equal(isUsableReport(report), true);
 });
 
 // UNIT TESTS FOR PREVIOUSLY UNTESTED EXPORTED FUNCTIONS
 
 test('createLock returns a function that runs tasks sequentially', async () => {
   const lock = createLock();
-  const order = [];
+  const order: string[] = [];
   const p1 = lock(async () => {
     order.push('start 1');
     await new Promise(r => setTimeout(r, 10));
@@ -876,34 +973,38 @@ test('getTimeStamp returns an 11-character stamp from a Date', () => {
   assert.equal(stamp.slice(7), '1430');
 });
 
-test('getEngineList returns a sorted +-delimited list of engine names', () => {
-  const result = getEngineList(new Set(['axe', 'wave', 'nuVal']));
+test('getEngineNamesString returns a sorted +-delimited list of engine names', () => {
+  const result = getEngineNamesString(new Set(['axe', 'wave', 'nuVal']));
   const names = result.split(' + ');
   assert.ok(names.length === 3);
   assert.ok(names.includes('WAVE'));
 });
 
-test('recsLock is a function (the lock returned by createLock)', () => {
-  assert.equal(typeof recsLock, 'function');
+test('getEngineNamesString falls back to the ID for an unknown engine', () => {
+  assert.equal(getEngineNamesString(new Set(['unknownEngine'])), 'unknownEngine');
+});
+
+test('testRequestsLock is a function (the lock returned by createLock)', () => {
+  assert.equal(typeof testRequestsLock, 'function');
 });
 
-test('updateRecs adds a recommendation and returns success', async () => {
-  await fs.writeFile(recsPath(), '{}\n');
-  const result = await updateRecs('Test Page', 'https://example.com/test', 'because');
+test('addTestRequest adds a request and returns success', async () => {
+  await fs.writeFile(testRequestsPath(), '{}\n');
+  const result = await addTestRequest('Test Page', 'https://example.com/test', 'because');
   assert.equal(result.error, undefined);
-  const recs = JSON.parse(await fs.readFile(recsPath(), 'utf8'));
-  assert.ok(recs['https://example.com/test']);
-  assert.equal(recs['https://example.com/test'].length, 1);
-  assert.equal(recs['https://example.com/test'][0].what, 'Test Page');
-  await fs.writeFile(recsPath(), '{}\n');
+  const testRequests = JSON.parse(await fs.readFile(testRequestsPath(), 'utf8'));
+  assert.ok(testRequests['https://example.com/test']);
+  assert.equal(testRequests['https://example.com/test'].length, 1);
+  assert.equal(testRequests['https://example.com/test'][0].description, 'Test Page');
+  await fs.writeFile(testRequestsPath(), '{}\n');
 });
 
-test('updateRecs returns a duplicate error for a repeated recommendation', async () => {
-  await fs.writeFile(recsPath(), '{}\n');
-  await updateRecs('Test Page', 'https://example.com/test', 'because');
-  const result = await updateRecs('Test Page', 'https://example.com/test', 'another reason');
+test('addTestRequest returns a duplicate error for a repeated request', async () => {
+  await fs.writeFile(testRequestsPath(), '{}\n');
+  await addTestRequest('Test Page', 'https://example.com/test', 'because');
+  const result = await addTestRequest('Test Page', 'https://example.com/test', 'another reason');
   assert.equal(result.error, 'duplicate');
-  await fs.writeFile(recsPath(), '{}\n');
+  await fs.writeFile(testRequestsPath(), '{}\n');
 });
 
 test('getReportPath returns the path of a report file', () => {
@@ -913,6 +1014,7 @@ test('getReportPath returns the path of a report file', () => {
 
 test('getReportStats returns reportTime and reportSize for a valid report', async () => {
   const stats = await getReportStats('260101T0000', 'mix');
+  assert.ok(stats);
   assert.ok(stats.reportTime instanceof Date);
   assert.equal(typeof stats.reportSize, 'number');
   assert.ok(stats.reportSize > 0);
@@ -923,27 +1025,18 @@ test('getReportStats returns null for a nonexistent report', async () => {
   assert.equal(stats, null);
 });
 
-test('isHidden returns false for a non-hidden report', async () => {
-  const result = await isHidden('260101T0000', 'mix');
-  assert.equal(result, false);
-});
-
-test('isHidden returns true for a hidden report', async () => {
-  const result = await isHidden('260101T0007', 'hid');
-  assert.equal(result, true);
-});
 
 test('getReportExtract returns an extract for a valid report', async () => {
-  const extract = await getReportExtract('260101T0000', 'mix');
+  const extract = await getReportExtract('260101T0000', 'mix') as any;
   assert.equal(extract.timeStamp, '260101T0000');
   assert.equal(extract.jobID, 'mix');
-  assert.equal(extract.what, 'Mixed Outcomes Page');
+  assert.equal(extract.description, 'Mixed Outcomes Page');
   assert.equal(extract.url, 'https://example.com/mixed');
   assert.ok(extract.reportTime);
 });
 
 test('getReportExtract returns an error for a nonexistent report', async () => {
-  const extract = await getReportExtract('999999T9999', 'xxx');
+  const extract = await getReportExtract('999999T9999', 'xxx') as any;
   assert.ok(extract.error);
 });
 
@@ -955,11 +1048,11 @@ test('getReportExtracts returns extracts of all available reports', async () =>
   assert.ok(ids.includes('260101T0001-ct'));
 });
 
-test('getLatestReportExtracts returns only the latest report for each page', async () => {
-  const latest = await getLatestReportExtracts();
-  const mixReports = latest.filter(e => e.what === 'Mixed Outcomes Page');
+test('getReportExtracts with onlyLatest returns only the latest report for each page', async () => {
+  const latest = await getReportExtracts(true);
+  const mixReports = latest.filter(e => e.description === 'Mixed Outcomes Page');
   assert.equal(mixReports.length, 1);
-  assert.equal(mixReports[0].timeStamp, '260202T0000');
+  assert.equal(mixReports[0]!.timeStamp, '260202T0000');
 });
 
 test('getMultiReportWhats returns descriptions that have multiple reports', async () => {