@jrpool/kilotest 59.0.2 → 59.0.4

package/index.ts

@@ -31,7 +31,8 @@ import {
   jobsPath,
   metricsExclusionCookieName,
   recordMetric,
-  reportsPath
+  reportsPath,
+  unusableReportsPath
 } from './util.ts';
 import {sendAlert} from './alerts.ts';
 import {checkBalancesForAlerts} from './balances.ts';
@@ -1387,7 +1388,9 @@ export {requestHandler};
 
 const serve = async (protocolModule: typeof http | typeof https, options: {key?: string; cert?: string}) => {
   // Create any missing directories.
-  for (const path of [queuePath(), claimedPath(), failedPath(), hiddenReportsPath(), reportsPath()]) {
+  for (const path of [
+    queuePath(), claimedPath(), failedPath(), hiddenReportsPath(), reportsPath(), unusableReportsPath()
+  ]) {
     await fs.mkdir(path, {recursive: true});
   }
   const server = protocolModule === https

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "59.0.2",
+  "version": "59.0.4",
   "description": "Ensemble testing for front-end web quality",
   "type": "module",
   "main": "index.ts",

package/test/dbFixture.ts

@@ -24,6 +24,7 @@ fs.cpSync(path.join(import.meta.dirname, 'fixtures', 'db'), fixtureDBDir, {recur
 for (const category of ['queue', 'claimed', 'failed']) {
   fs.mkdirSync(path.join(fixtureDBDir, 'jobs', category), {recursive: true});
 }
+fs.mkdirSync(path.join(fixtureDBDir, 'unusableReports'), {recursive: true});
 
 // Remove the copy when the process exits.
 process.on('exit', () => fs.rmSync(fixtureDBDir, {recursive: true, force: true}));

package/test/fixtures/buildFixtures.ts

@@ -114,6 +114,7 @@ const main = async () => {
   await fs.mkdir(path.join(targetDir, 'jobs', 'claimed'), {recursive: true});
   await fs.mkdir(path.join(targetDir, 'jobs', 'failed'), {recursive: true});
   await fs.mkdir(path.join(targetDir, 'hiddenReports'), {recursive: true});
+  await fs.mkdir(path.join(targetDir, 'unusableReports'), {recursive: true});
 
   // Fixture 1: mixedOutcomes. Two rule engines, four instances: two failed (same issue, same violator, two engines), one cantTell (excluded from counts), one failed (different issue, different violator). Two distinct issues (linkNoText weight 4, allCaps weight 1) and two distinct violator catalog indexes (0 and 1).
   const mixedCatalog = {

package/util.test.ts

@@ -24,6 +24,7 @@ import {
   awaitJob,
   checkCommentDuplicate,
   checkLength,
+  quarantineReport,
   createLock,
   dbPath,
   describeMax,
@@ -61,7 +62,8 @@ import {
   processTestRequest,
   testRequestsLock,
   testRequestsPath,
-  reportsPath
+  reportsPath,
+  unusableReportsPath
 } from './util.ts';
 
 // TESTS
@@ -142,7 +144,7 @@ test('dbPath honors DB_DIR when it is set', () => {
   }
 });
 
-test('jobsPath, testRequestsPath, reportsPath, and hiddenReportsPath derive from DB_DIR', () => {
+test('jobsPath, testRequestsPath, reportsPath, hiddenReportsPath, and unusableReportsPath derive from DB_DIR', () => {
   const saved = process.env.DB_DIR;
   process.env.DB_DIR = '/tmp/kilotest-fixtures';
   try {
@@ -150,6 +152,7 @@ test('jobsPath, testRequestsPath, reportsPath, and hiddenReportsPath derive from
     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'));
+    assert.equal(unusableReportsPath(), path.join('/tmp/kilotest-fixtures', 'unusableReports'));
   }
   finally {
     if (saved !== undefined) {
@@ -1445,6 +1448,177 @@ test('getReportExtract returns an error for a nonexistent report', async () => {
   assert.ok(extract.error);
 });
 
+test('getReportExtract returns an error for an unusable report', async () => {
+  const os = await import('node:os');
+  const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kilotest-extract-bad-'));
+  const tmpReportsDir = path.join(tmpRoot, 'db', 'reports');
+  await fs.mkdir(tmpReportsDir, {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = path.join(tmpRoot, 'db');
+  try {
+    // A report with a target and a completion time but no usable acts or catalog is
+    // defective, so it must produce no extract rather than be exposed in listings.
+    await fs.writeFile(
+      path.join(tmpReportsDir, '260101T0000-bad.json'),
+      JSON.stringify({
+        target: {what: 'Defective Page', url: 'https://example.com/defective'},
+        jobData: {endTime: '26-01-01T00:00'}
+      })
+    );
+    const extract = await getReportExtract('260101T0000', 'bad') as any;
+    assert.ok(extract.error);
+  }
+  finally {
+    if (savedDbDir !== undefined) {
+      process.env.DB_DIR = savedDbDir;
+    }
+    else {
+      delete process.env.DB_DIR;
+    }
+    await fs.rm(tmpRoot, {recursive: true, force: true});
+  }
+});
+
+test('quarantineReport ignores a missing report', async () => {
+  const os = await import('node:os');
+  const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kilotest-quarantine-missing-'));
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = path.join(tmpRoot, 'db');
+  try {
+    await quarantineReport('999999T9999', 'xxx', 'not usable');
+    // Nothing was created or moved.
+    assert.deepEqual(await fs.readdir(tmpRoot), []);
+  }
+  finally {
+    if (savedDbDir !== undefined) {
+      process.env.DB_DIR = savedDbDir;
+    }
+    else {
+      delete process.env.DB_DIR;
+    }
+    await fs.rm(tmpRoot, {recursive: true, force: true});
+  }
+});
+
+test('quarantineReport leaves a recently modified report in place', async () => {
+  const os = await import('node:os');
+  const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kilotest-quarantine-young-'));
+  const tmpReportsDir = path.join(tmpRoot, 'db', 'reports');
+  await fs.mkdir(tmpReportsDir, {recursive: true});
+  const filePath = path.join(tmpReportsDir, '260101T0000-bad.json');
+  await fs.writeFile(filePath, '{}');
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = path.join(tmpRoot, 'db');
+  try {
+    await quarantineReport('260101T0000', 'bad', 'not usable');
+    // The fresh file may still be mid-write, so it was not moved.
+    await fs.access(filePath);
+  }
+  finally {
+    if (savedDbDir !== undefined) {
+      process.env.DB_DIR = savedDbDir;
+    }
+    else {
+      delete process.env.DB_DIR;
+    }
+    await fs.rm(tmpRoot, {recursive: true, force: true});
+  }
+});
+
+test('quarantineReport quarantines a report old enough to be quarantined', async () => {
+  const os = await import('node:os');
+  const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kilotest-quarantine-old-'));
+  const tmpReportsDir = path.join(tmpRoot, 'db', 'reports');
+  await fs.mkdir(tmpReportsDir, {recursive: true});
+  const filePath = path.join(tmpReportsDir, '260101T0000-bad.json');
+  await fs.writeFile(filePath, '{}');
+  // Age the file beyond the quarantine threshold.
+  const longAgo = new Date(Date.now() - 120000);
+  await fs.utimes(filePath, longAgo, longAgo);
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = path.join(tmpRoot, 'db');
+  try {
+    await quarantineReport('260101T0000', 'bad', 'not usable');
+    // The file was moved to the unusable-reports directory.
+    await fs.access(filePath).then(
+      () => {throw new Error('Report should have been quarantined');},
+      () => {}
+    );
+    const quarantined = await fs.readdir(path.join(tmpRoot, 'db', 'unusableReports'));
+    assert.deepEqual(quarantined, ['260101T0000-bad.json']);
+  }
+  finally {
+    if (savedDbDir !== undefined) {
+      process.env.DB_DIR = savedDbDir;
+    }
+    else {
+      delete process.env.DB_DIR;
+    }
+    await fs.rm(tmpRoot, {recursive: true, force: true});
+  }
+});
+
+test('quarantineReport leaves the file and logs when the move fails', async () => {
+  const os = await import('node:os');
+  const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kilotest-quarantine-blocked-'));
+  const tmpReportsDir = path.join(tmpRoot, 'db', 'reports');
+  await fs.mkdir(tmpReportsDir, {recursive: true});
+  const filePath = path.join(tmpReportsDir, '260101T0000-bad.json');
+  await fs.writeFile(filePath, '{}');
+  // Age the file beyond the quarantine threshold.
+  const longAgo = new Date(Date.now() - 120000);
+  await fs.utimes(filePath, longAgo, longAgo);
+  // A directory already occupying the destination path makes the rename fail.
+  await fs.mkdir(path.join(tmpRoot, 'db', 'unusableReports', '260101T0000-bad.json'), {recursive: true});
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = path.join(tmpRoot, 'db');
+  try {
+    await quarantineReport('260101T0000', 'bad', 'not usable');
+    // The report stays where it was.
+    await fs.access(filePath);
+  }
+  finally {
+    if (savedDbDir !== undefined) {
+      process.env.DB_DIR = savedDbDir;
+    }
+    else {
+      delete process.env.DB_DIR;
+    }
+    await fs.rm(tmpRoot, {recursive: true, force: true});
+  }
+});
+
+test('getReport quarantines a malformed report file old enough to be quarantined', async () => {
+  const os = await import('node:os');
+  const tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'kilotest-getreport-bad-'));
+  const tmpReportsDir = path.join(tmpRoot, 'db', 'reports');
+  await fs.mkdir(tmpReportsDir, {recursive: true});
+  const filePath = path.join(tmpReportsDir, '260101T0000-bad.json');
+  await fs.writeFile(filePath, 'not JSON');
+  // Age the file beyond the quarantine threshold.
+  const longAgo = new Date(Date.now() - 120000);
+  await fs.utimes(filePath, longAgo, longAgo);
+  const savedDbDir = process.env.DB_DIR;
+  process.env.DB_DIR = path.join(tmpRoot, 'db');
+  try {
+    const {getReport} = await import('./util.ts');
+    const result = await getReport('260101T0000', 'bad') as any;
+    assert.ok(result.error);
+    // The malformed file was quarantined.
+    const quarantined = await fs.readdir(path.join(tmpRoot, 'db', 'unusableReports'));
+    assert.deepEqual(quarantined, ['260101T0000-bad.json']);
+  }
+  finally {
+    if (savedDbDir !== undefined) {
+      process.env.DB_DIR = savedDbDir;
+    }
+    else {
+      delete process.env.DB_DIR;
+    }
+    await fs.rm(tmpRoot, {recursive: true, force: true});
+  }
+});
+
 test('getReportExtracts returns extracts of all available reports', async () => {
   const extracts = await getReportExtracts();
   assert.ok(extracts.length >= 8);

package/util.ts

@@ -32,6 +32,9 @@ export const testRequestsPath = (): string => path.join(jobsPath(), 'testRequest
 export const reportsPath = (): string => path.join(dbPath(), 'reports');
 // Path of the hidden-reports directory.
 export const hiddenReportsPath = (): string => path.join(dbPath(), 'hiddenReports');
+// Path of the unusable-reports directory, where reports that fail the usability
+// checks are quarantined for a manager to repair or delete.
+export const unusableReportsPath = (): string => path.join(dbPath(), 'unusableReports');
 // Path of the usage-metrics file.
 export const metricsPath = (): string => path.join(dbPath(), 'metrics.json');
 // IDs, names, and sponsors of Testaro rule engines.
@@ -692,7 +695,49 @@ export const isUsableReport = (report: unknown): report is UsableReport => {
   && !isNaN(getReportEndTime(r).getTime())
   && typeof r.catalog === 'object';
 };
-// Returns a report.
+// Minimum age, in milliseconds, of the last modification of a report file for the
+// file to be quarantined. A more recently modified file may still be being written
+// by a worker or a reannotation, so quarantining it could mistake an incomplete write
+// for a defect. Read at call time so tests can shrink it via REPORT_QUARANTINE_MIN_AGE_MS;
+// a value of 0 disables the age check.
+const quarantineMinAgeMs = () => getEnvMax('REPORT_QUARANTINE_MIN_AGE_MS', 60000);
+// Moves a report file from the reports directory to the unusable-reports directory
+// and alerts a manager, if the file exists and is old enough that it can no longer
+// plausibly be mid-write. Called by getReport whenever a report proves defective, so
+// that a defective report is quarantined rather than merely hidden from whichever
+// listing encountered it. Never throws: a failure here must not displace the error
+// that getReport is already reporting.
+export const quarantineReport = async (timeStamp: string, jobID: string, defect: string): Promise<void> => {
+  const jobName = `${timeStamp}-${jobID}`;
+  // Get the modification time of the report file. A missing file needs no move.
+  const stat = await fs.stat(getReportPath(timeStamp, jobID)).catch(() => null);
+  if (!stat) {
+    return;
+  }
+  // Leave a recently modified file alone, since it may still be being written.
+  if (Date.now() - stat.mtimeMs < quarantineMinAgeMs()) {
+    return;
+  }
+  try {
+    await fs.mkdir(unusableReportsPath(), {recursive: true});
+    await fs.rename(
+      getReportPath(timeStamp, jobID), path.join(unusableReportsPath(), `${jobName}.json`)
+    );
+  }
+  catch (error: unknown) {
+    // The report stays excluded regardless, so a failed move is only logged.
+    console.error(`ERROR: Failed to quarantine report ${jobName} (${errorMessage(error)})`);
+    return;
+  }
+  // Alert a manager, who can repair the report in place or delete it.
+  await sendAlert(
+    'Kilotest: unusable report',
+    `Report ${jobName} is ${defect}. It was moved to the unusableReports directory, where a manager can repair or delete it.`
+  );
+};
+// Returns a report, or an error object if it is missing, unreadable, unparsable, or
+// unusable. A report that exists but cannot be read or is unusable is defective, so
+// it is quarantined rather than merely rejected by whichever read encountered it.
 export const getReport = async (timeStamp: string, jobID: string): Promise<UsableReport | {error: string}> => {
   try {
     const reportJSON = await fs.readFile(getReportPath(timeStamp, jobID), 'utf8');
@@ -702,11 +747,15 @@ export const getReport = async (timeStamp: string, jobID: string): Promise<Usabl
       // Return it.
       return report;
     }
-    // Otherwise, i.e. if it is unusable, return this.
-    return {error: `Report ${timeStamp}-${jobID} is not usable`};
   } catch (error: unknown) {
+    // The file exists but cannot be read or parsed, or is already missing.
+    // quarantineReport ignores a missing file, so no existence check is needed here.
+    await quarantineReport(timeStamp, jobID, 'unreadable or not JSON');
     return {error: `Report ${timeStamp}-${jobID} is missing, unreadable, or not JSON (${errorMessage(error)})`};
   }
+  // The report was read but is not usable, so quarantine it.
+  await quarantineReport(timeStamp, jobID, 'not usable');
+  return {error: `Report ${timeStamp}-${jobID} is not usable`};
 };
 // Returns whether a getReport result is an error (rather than a usable report).
 // A type predicate is used instead of `if (report.error)` because UsableReport
@@ -773,30 +822,27 @@ export const getReportEndTime = (report: {jobData?: {endTime?: string}}): Date =
   `20${report.jobData?.endTime}Z`
 );
 
-// Returns an extract of an available report, or an error object if it cannot be read or parsed.
+// Returns an extract of an available report, or an error object if the report cannot
+// be used. An extract exists to expose a report in listings, so it shares getReport's
+// usability bar: a report too defective to expose must produce no extract.
 export const getReportExtract = async (timeStamp: string, jobID: string): Promise<ReportExtract | {error: string}> => {
-  try {
-    // Get the report.
-    const reportJSON = await fs.readFile(
-      path.join(reportsPath(), `${timeStamp}-${jobID}.json`), 'utf8'
-    );
-    const report = JSON.parse(reportJSON);
-    const {target, jobData} = report;
-    const {what: description, url} = target;
-    // Return an extract of it.
-    return {
-      timeStamp,
-      jobID,
-      description,
-      url,
-      reportTime: getReportEndTime({jobData}).toISOString()
-    };
-  }
-  catch {
-    return {
-      error: `No report ${timeStamp}-${jobID} is available`
-    };
+  const report = await getReport(timeStamp, jobID);
+  // If the report is not usable:
+  if (isReportError(report)) {
+    // Return the reason.
+    return report;
   }
+  const {target, jobData} = report;
+  const {what: description, url} = target;
+  // Return an extract of it. Usability has already guaranteed these properties,
+  // including a valid completion time.
+  return {
+    timeStamp,
+    jobID,
+    description,
+    url,
+    reportTime: getReportEndTime({jobData}).toISOString()
+  };
 };
 // Cache of report extracts, keyed by report file path. Each entry records the modification
 // time and size of the file when it was extracted, so an entry is reused only while the file
@@ -804,7 +850,7 @@ export const getReportExtract = async (timeStamp: string, jobID: string): Promis
 // written, hidden, or deleted by any process, so the cache is validated against the files
 // before every use rather than invalidated by the code that changes them.
 const reportExtractCache = new Map<string, {mtimeMs: number, size: number, extract: ReportExtract}>();
-// Returns extracts of all available reports.
+// Returns extracts of all available reports, ordered by page description and completion time.
 export const getReportExtracts = async (onlyLatest: boolean = false): Promise<ReportExtract[]> => {
   const reportsDir = reportsPath();
   // Get the names and paths of the available report files.
@@ -866,8 +912,7 @@ export const getReportExtracts = async (onlyLatest: boolean = false): Promise<Re
   // Return the array, excluding extracts of superseded reports if so specified.
   return onlyLatest ? extracts.filter(extract => !extract.superseded) : extracts;
 };
-// Returns extracts of all available reports about the page with a description, from oldest
-// to latest.
+// Returns extracts of all available reports about a page, from oldest to latest.
 export const getPageReportExtracts = async (description: string): Promise<ReportExtract[]> => {
   const reportExtracts = await getReportExtracts();
   return reportExtracts.filter(extract => extract.description === description);

package/web/listIssues/index.html

@@ -13,7 +13,7 @@
   <body>
     <main>
       <h1><a href="/">Kilotest</a>: Issues reported for __target__</h1>
-
+      __oldWarn__
       <h2>About the tests</h2>
 __pageFacts__
       <h2>History</h2>

package/web/listIssues/index.ts

@@ -123,46 +123,62 @@ const getIssuesData = (report: UsableReport): ResultsSummary & Record<string, an
   // Return the data.
   return final;
 };
-// Returns the lines of the history of the reports about the page of a report.
-const getHistoryLines = async (
-  timeStamp: string, jobID: string, description: string, margin: string
-): Promise<string[]> => {
+// Returns data and HTML lines about the history of the reports about the page of a report.
+const getHistory = async (
+  timeStamp: string, jobID: string, description: string, margin: string = ''
+): Promise<{isLatest: boolean, lines: string[]}> => {
   // Get extracts of all reports about the page, from oldest to latest.
   const pageExtracts = await getPageReportExtracts(description);
-  const lastIndex = pageExtracts.length - 1;
-  // Initialize the list items and whether the report is the latest about the page.
-  const itemLines: string[] = [];
-  let isLatest = false;
-  // For each report about the page:
+  // The report's own extract may be absent if the report was quarantined between the
+  // report read and the extract listing, so an empty list means "not latest".
+  const lastExtract = pageExtracts[pageExtracts.length - 1];
+  const isLatest = lastExtract !== undefined
+  && lastExtract.timeStamp === timeStamp && lastExtract.jobID === jobID;
+  // Initialize the history.
+  const history = {
+    isLatest,
+    lines: [] as string[]
+  };
+  // For each report about the page, from oldest to latest:
   pageExtracts.forEach((extract, index) => {
+    // Get whether it is this report.
     const isThis = extract.timeStamp === timeStamp && extract.jobID === jobID;
-    isLatest ||= isThis && index === lastIndex;
     // Get the tags that identify its position and whether it is this report.
     const tags = [
       index === 0 ? 'oldest' : '',
-      index === lastIndex ? 'latest' : '',
+      index === pageExtracts.length - 1 ? 'latest' : '',
       isThis ? 'this report' : ''
     ]
     .filter(tag => tag);
+    // Get a string containing the applicable tags.
     const tagString = tags.length ? ` (${tags.join('; ')})` : '';
     const label = `${getAgoString(new Date(extract.reportTime))} ago${tagString}`;
-    // Add a list item describing it, linked unless it is this report, to the items.
-    const href = `/listIssues.html/${extract.timeStamp}/${extract.jobID}`;
-    const content = isThis ? label : `<a href="${href}">${label}</a>`;
-    itemLines.push(`${margin}  <li>${content}</li>`);
+    let content;
+    if (isThis) {
+      content = label;
+    }
+    else {
+      const href = `/listIssues.html/${extract.timeStamp}/${extract.jobID}`;
+      content = `<a href="${href}">${label}</a>`;
+    }
+    // Add a list item describing the report, linked if not this report, to the history.
+    history.lines.push(`${margin}<li>${content}</li>`);
   });
   // Initialize the lines with a list of the reports, or a statement that there is only one.
-  const lines = itemLines.length > 1
-  ? [`${margin}<ol>`, ...itemLines, `${margin}</ol>`]
-  : [`${margin}<p>This is the only report about the page.</p>`];
-  // If the report is the latest about the page:
+  const lines = history.lines.length > 1
+  ? [`${margin}<ol>`, ...history.lines, `${margin}</ol>`]
+  : [`${margin}<p>This is the only available report about the page.</p>`];
+  // If this report is the latest about the page:
   if (isLatest) {
     // Add a link to the form for requesting a retest to the lines.
-    const href = `/requestRetestForm.html/${timeStamp}/${jobID}`;
-    lines.push(`${margin}<p><a href="${href}">Should Kilotest retest the page?</a></p>`);
+    lines.push(
+      `${margin}<p><a href="/requestRetestForm.html/${timeStamp}/${jobID}">Request a retest</a></p>`
+    );
   }
-  // Return the lines.
-  return lines;
+  // Replace the bare list items with the assembled section lines.
+  history.lines = lines;
+  // Return the history.
+  return history;
 };
 // Adds parameters to a query for the answer page.
 const populateQuery = async (timeStamp: string, jobID: string, query: Record<string, any>) => {
@@ -191,10 +207,15 @@ const populateQuery = async (timeStamp: string, jobID: string, query: Record<str
   query.target = description;
   query.testInfo = testInfo;
   const margin = ' '.repeat(6);
+  const history = await getHistory(timeStamp, jobID, description, ' '.repeat(8));
+  // Add a warning if the report is not the latest about the page.
+  query.oldWarn = history.isLatest
+  ? ''
+  : '<p><strong>Warning: This report is not the latest about the page.</strong> See history below.</p>';
   // Add the page-facts list to the query.
   query.pageFacts = getPageFactsLines(pageInfo, issuesData, margin).join('\n');
   // Add the history of reports about the page to the query.
-  query.history = (await getHistoryLines(timeStamp, jobID, description, margin)).join('\n');
+  query.history = history.lines.join('\n');
   const {issues} = issuesData;
   // Add a summary of the issues to the query.
   query.highestCount = issues[4].length;

package/web/listIssues/listIssues.test.ts

@@ -231,7 +231,7 @@ test('listIssues History of an older report lists all reports, with this one unl
   assert.equal(items[0]!.href, null);
   assert.match(items[1]!.text, /^\d+ days? ago \(latest\)$/);
   assert.equal(items[1]!.href, '/listIssues.html/260202T0000/new');
-  assert.ok(!result.answerPage.includes('Should Kilotest retest the page?'));
+  assert.ok(!result.answerPage.includes('Request a retest'));
 });
 
 test('listIssues History of the latest report ends with the retest question', async () => {
@@ -244,7 +244,7 @@ test('listIssues History of the latest report ends with the retest question', as
   assert.match(items[1]!.text, /^\d+ days? ago \(latest; this report\)$/);
   assert.equal(items[1]!.href, null);
   const retestLink = history.querySelector('ol + p > a');
-  assert.equal(retestLink?.text, 'Should Kilotest retest the page?');
+  assert.equal(retestLink?.text, 'Request a retest');
   assert.equal(retestLink?.getAttribute('href'), '/requestRetestForm.html/260202T0000/new');
 });
 
@@ -253,7 +253,7 @@ test('listIssues History of the only report about a page says so and asks about
   const history = getHistory(result.answerPage);
   assert.equal(getHistoryItems(history).length, 0);
   const paragraphs = history.querySelectorAll('p');
-  assert.equal(paragraphs[0]?.text, 'This is the only report about the page.');
+  assert.equal(paragraphs[0]?.text, 'This is the only available report about the page.');
   assert.equal(paragraphs[1]?.querySelector('a')?.getAttribute('href'), '/requestRetestForm.html/260101T0001/ct');
 });
 

package/web/listPages/listPages.test.ts

@@ -149,12 +149,12 @@ test('listPages shows queued and claimed jobs when they exist', async () => {
   }
 });
 
-test('listPages lists a page whose report is not usable', {timeout: 500}, async () => {
+test('listPages omits a page whose report is not usable', {timeout: 500}, async () => {
   const dbDir = (await import('../../test/dbFixture.ts')).fixtureDBDir;
   const reportsDir = path.join(dbDir, 'reports');
   const invalidReportPath = path.join(reportsDir, '260101T9999-bad.json');
   try {
-    // Valid for getReportExtract (has target and jobData.endTime) but not usable by isUsableReport (no acts or catalog).
+    // Not usable by isUsableReport (no acts or catalog), so it must not be exposed.
     const invalidReport = {
       target: {what: 'Invalid Report', url: 'https://example.com/invalid'},
       jobData: {endTime: '26-01-01T00:10'}
@@ -163,7 +163,7 @@ test('listPages lists a page whose report is not usable', {timeout: 500}, async
     const result: any = await answer();
     assert.equal(result.status, 'ok');
     const links = getPageLinks(result.answerPage);
-    assert.ok(links.some(a => a.text === 'Invalid Report'));
+    assert.ok(!links.some(a => a.text === 'Invalid Report'));
   }
   finally {
     await fs.unlink(invalidReportPath).catch(() => {});

package/web/listTopIssues/listTopIssues.test.ts

@@ -5,12 +5,31 @@
 
 // IMPORTS
 
-import {test, before, after} from 'node:test';
+import {test, before, after, mock} from 'node:test';
 import assert from 'node:assert/strict';
 import path from 'node:path';
 import fs from 'node:fs/promises';
 import {parse} from 'node-html-parser';
-import {answer} from './index.ts';
+
+// Mock the util functions called by index.ts before importing it, so that
+// it imports the mocked versions. Other exports delegate to the real module.
+import * as realUtil from '../../util.ts';
+let getReportCallCount = 0;
+let failGetReportOnCall = -1;
+mock.module('../../util.ts', {
+  exports: {
+    ...realUtil,
+    getReport: async (...args: any[]) => {
+      getReportCallCount++;
+      if (getReportCallCount === failGetReportOnCall) {
+        return {error: 'Report is invalid (test override)'};
+      }
+      return (realUtil.getReport as any)(...args);
+    }
+  }
+} as any);
+
+const {answer} = await import('./index.ts') as any;
 
 // SETUP AND TEARDOWN
 
@@ -54,23 +73,36 @@ test('listTopIssues excludes cantTell instances from issue counts', async () =>
   assert.ok(!result.answerPage.includes('focus indication poor'));
 });
 
-test('listTopIssues returns an error when a report file is invalid', async () => {
+test('listTopIssues omits a report that is not usable', async () => {
   const dbDir = (await import('../../test/dbFixture.ts')).fixtureDBDir;
   const reportsDir = path.join(dbDir, 'reports');
   const invalidReportPath = path.join(reportsDir, '260101T9999-bad.json');
   try {
-    // Valid for getReportExtract (has target and jobData.endTime) but not usable by isUsableReport (no acts or catalog).
+    // Not usable by isUsableReport (no acts or catalog), so it produces no extract
+    // and contributes nothing to the summary.
     const invalidReport = {
       target: {what: 'Invalid TopIssues Report', url: 'https://example.com/invalidtop'},
       jobData: {endTime: '26-01-01T00:10'}
     };
     await fs.writeFile(invalidReportPath, JSON.stringify(invalidReport, null, 2));
+    const result: any = await answer();
+    assert.equal(result.status, 'ok');
+  }
+  finally {
+    await fs.unlink(invalidReportPath).catch(() => {});
+  }
+});
+
+test('listTopIssues returns an error when a report read fails', async () => {
+  getReportCallCount = 0;
+  failGetReportOnCall = 1;
+  try {
     const result: any = await answer();
     assert.equal(result.status, 'error');
     assert.ok(result.message);
   }
   finally {
-    await fs.unlink(invalidReportPath).catch(() => {});
+    failGetReportOnCall = -1;
   }
 });
 

package/web/reannotate/reannotate.test.ts

@@ -90,8 +90,8 @@ test('answer returns an error when a report fails annotation', {timeout: 2000},
   // Back up all fixture reports, because reannotation modifies good reports
   // in place before it reaches the bad one and returns an error.
   const backups = await backupReports();
-  // Create a temporary report file that passes getReportExtract but fails
-  // getReport validation (acts is not an array).
+  // Create a temporary report file that fails getReport validation
+  // (acts is not an array). It is too fresh to be quarantined, so it stays put.
   const badReportName = '990101T0000-bad.json';
   const badReportPath = path.join(reportsDir, badReportName);
   const badReport = {

package/web/reannotateForm/reannotateForm.test.ts

@@ -6,13 +6,31 @@
 
 // IMPORTS
 
-import {test, before, after, beforeEach} from 'node:test';
+import {test, before, after, beforeEach, mock} from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import {parse} from 'node-html-parser';
 
+// Mock the util functions called by index.ts before it is ever imported, so that
+// it imports the mocked versions. Other exports delegate to the real module.
+import * as realUtil from '../../util.ts';
+let getReportCallCount = 0;
+let failGetReportOnCall = -1;
+mock.module('../../util.ts', {
+  exports: {
+    ...realUtil,
+    getReport: async (...args: any[]) => {
+      getReportCallCount++;
+      if (getReportCallCount === failGetReportOnCall) {
+        return {error: 'Report is invalid (test override)'};
+      }
+      return (realUtil.getReport as any)(...args);
+    }
+  }
+} as any);
+
 // CONSTANTS
 
 import {fixtureDBDir} from '../../test/dbFixture.ts';
@@ -101,9 +119,9 @@ test('answer returns ok with no-reclassified message when reports have no violat
   }
 });
 
-test('answer returns an error when a report fails to load', async () => {
-  // Create a temporary report file that passes getReportExtract but fails
-  // getReport validation (acts is not an array).
+test('answer ignores a report that is not usable', async () => {
+  // A report that fails getReport validation (acts is not an array) produces no
+  // extract, so it is ignored rather than causing an error.
   const badReportName = '990101T0000-bad.json';
   const badReportPath = path.join(reportsDir, badReportName);
   const badReport = {
@@ -117,8 +135,7 @@ test('answer returns an error when a report fails to load', async () => {
   try {
     const {answer} = await import('./index.ts');
     const result = await answer();
-    assert.equal(result.status, 'error');
-    assert.ok(result.message.includes('not usable'), `Expected message about unusable report, got: ${result.message}`);
+    assert.equal(result.status, 'ok');
   }
   finally {
     try {
@@ -129,3 +146,17 @@ test('answer returns an error when a report fails to load', async () => {
     }
   }
 });
+
+test('answer returns an error when a report read fails', async () => {
+  getReportCallCount = 0;
+  failGetReportOnCall = 1;
+  try {
+    const {answer} = await import('./index.ts');
+    const result = await answer();
+    assert.equal(result.status, 'error');
+    assert.ok(result.message);
+  }
+  finally {
+    failGetReportOnCall = -1;
+  }
+});