@jrpool/kilotest 60.9.1 → 62.0.0

package/.devin/config.local.json

@@ -41,7 +41,8 @@
       "Exec(npm update)",
       "Exec(npm ls)",
       "Exec(pkill)",
-      "Exec(python3)"
+      "Exec(python3)",
+      "Exec(npx)"
     ]
   }
 }

package/.markdownlint-cli2.jsonc

@@ -3,7 +3,6 @@
     "**/*.md"
   ],
   "ignores": [
-    "docs/IDEAS.md",
     "node_modules/**"
   ],
   "config": {

package/api/listDiagnoses.ts

@@ -94,14 +94,24 @@ export const response = async (args: string[]) => {
         const diagnoses: Diagnoses = [];
         // For each instance reporting a violation of the issue by the violator:
         getTestActInstances(report, {violationsOnly: true, issueID, catalogIndex})
-        .forEach(({instance}) => {
+        .forEach(({act, instance}) => {
           const {count, ordinalSeverity, ruleID, what} = instance;
           // Get the diagnosis.
-          const diagnosis = {
+          const diagnosis: Diagnoses[number] = {
+            'identifier of the rule engine': act.which!,
             'identifier of the violated rule': ruleID !== what ? ruleID : null,
             'description of the violation': what,
             'severity of the violation on a 0-to-3 scale': ordinalSeverity,
-            'count of violations of the rule by the element': count ?? 1
+            'count of violations of the rule by the element': count ?? 1,
+            'how to report that you disagree with this diagnosis': {
+              method: 'POST',
+              URL: `${thisHost}/api/reportDisagreement/${issueID}/${reportID}/${catalogIndex}`,
+              'request body': {
+                engineID: 'the identifier of the rule engine shown in this diagnosis',
+                ruleID: 'the identifier of the violated rule shown in this diagnosis, or, if it is null, the description of the violation',
+                reason: '20- to 1000-character explanation of why you disagree with this diagnosis'
+              }
+            }
           }
           diagnoses.push(diagnosis);
         });

package/api/listIssues.ts

@@ -31,6 +31,10 @@ import {listIssuesResponseSchema} from './schemas.ts';
 
 // The response content defined by the response schema.
 type ResponseContent = z.infer<typeof listIssuesResponseSchema>['response content'];
+// One entry of the history of reports about the page.
+type ReportHistoryEntry = NonNullable<ResponseContent['history of reports about the page']>[number];
+// The basics about one issue in the report.
+type IssueBasics = NonNullable<ResponseContent['basics about all issues reported in the report']>[number];
 
 // FUNCTIONS
 
@@ -67,7 +71,7 @@ export const response = async (args: string[]) => {
       const pageExtracts = await getPageReportExtracts(report.target.what);
       const lastIndex = pageExtracts.length - 1;
       // Add the history of reports about the page to the response content.
-      responseContent['history of reports about the page'] = pageExtracts.map((extract, index) => {
+      responseContent['history of reports about the page'] = pageExtracts.map((extract, index): ReportHistoryEntry => {
         const extractID = extract.id;
         return {
           identifier: extractID,
@@ -77,7 +81,7 @@ export const response = async (args: string[]) => {
           'whether it is the latest report about the page': index === lastIndex,
           'whether it is the report described in this response': extractID === reportID,
           'how to get details about the report': {
-            method: 'GET' as const,
+            method: 'GET',
             URL: `${thisHost}/api/listIssues/${extractID}`
           },
           'web users can get details about the report at': `${thisHost}/listIssues.html/${extractID}`
@@ -210,7 +214,7 @@ export const response = async (args: string[]) => {
       // Sort the data about issues by summary.
       const sortedIssuesData = objectSort(Object.values(issuesData), 'summary', 'alpha');
       // Get the basics about the issues.
-      const issuesBasics = sortedIssuesData.map(issueData => {
+      const issuesBasics = sortedIssuesData.map((issueData): IssueBasics => {
         const {id, summary, weight, why, reporterIDs} = issueData;
         return {
           identifier: id,
@@ -220,7 +224,7 @@ export const response = async (args: string[]) => {
           'rule engines with any violations belonging to the issue': getRuleEnginesFacts(reporterIDs)
           .map(ruleEnginesFact => ruleEnginesFact.name),
           'how to get details about the issue': {
-            method: 'GET' as const,
+            method: 'GET',
             URL: `${thisHost}/api/listViolators/${id}/${reportID}`
           },
           'web users can get details about the issue at': `${thisHost}/listViolators.html/${id}/${reportID}`

package/api/listPages.test.ts

@@ -31,7 +31,7 @@ after(() => {
 test('listPages returns one entry per tested page, sorted by page description', async () => {
   const body = await response();
   const pagesBasics = body['response content']['basics about all tested pages'];
-  const descriptions = pagesBasics.map(b => b['tested web page'].description);
+  const descriptions = pagesBasics.map(b => b.description);
   assert.deepEqual(
     descriptions,
     [
@@ -49,31 +49,32 @@ test('listPages returns one entry per tested page, sorted by page description',
 test('listPages does not include the page of the hidden report', async () => {
   const body = await response();
   const pagesBasics = body['response content']['basics about all tested pages'];
-  const ids = pagesBasics.map(b => b['basics about the latest report'].identifier);
+  const ids = pagesBasics.map(b => b.identifier);
   assert.ok(!ids.includes('260101T0007-hid'), 'hidden report must not appear in listPages');
 });
 
-test('listPages describes a multi-report page by its latest report and its report count', async () => {
+test('listPages identifies a multi-report page by its latest report', async () => {
   const body = await response();
   const pagesBasics = body['response content']['basics about all tested pages'];
-  const mixed = pagesBasics.find(b => b['tested web page'].description === 'Mixed Outcomes')!;
-  assert.equal(mixed['number of reports about the page'], 2);
-  const latest = mixed['basics about the latest report'];
-  assert.equal(latest.identifier, '260202T0000-new');
-  assert.equal(latest['completion date and time'], '2026-02-02T00:10:00.000Z');
-  assert.equal(typeof latest['days since the report was completed'], 'number');
-  assert.equal(mixed['how to get details about the latest report'].method, 'GET');
-  assert.ok(mixed['how to get details about the latest report'].URL.endsWith('/api/listIssues/260202T0000-new'));
-  assert.ok(mixed['web users can get details about the latest report at'].endsWith('/listIssues.html/260202T0000-new'));
+  const mixed = pagesBasics.find(b => b.description === 'Mixed Outcomes')!;
+  assert.equal(mixed.identifier, '260202T0000-new');
+  assert.equal(mixed.URL, 'https://example.com/mixed');
 });
 
 test('listPages describes a single-report page', async () => {
   const body = await response();
   const pagesBasics = body['response content']['basics about all tested pages'];
-  const canttell = pagesBasics.find(b => b['tested web page'].description === 'All CantTell Page')!;
-  assert.equal(canttell['number of reports about the page'], 1);
-  assert.equal(canttell['tested web page'].URL, 'https://example.com/canttell');
-  assert.equal(canttell['basics about the latest report'].identifier, '260101T0001-ct');
+  const canttell = pagesBasics.find(b => b.description === 'All CantTell Page')!;
+  assert.equal(canttell.URL, 'https://example.com/canttell');
+  assert.equal(canttell.identifier, '260101T0001-ct');
+});
+
+test('listPages includes result-retrieval instructions with an identifier placeholder', async () => {
+  const body = await response();
+  const content = body['response content'];
+  assert.equal(content['how to get test results about a page'].method, 'GET');
+  assert.ok(content['how to get test results about a page'].URL.endsWith('/api/listIssues/{identifier}'));
+  assert.ok(content['web users can get test results about a page at'].endsWith('/listIssues.html/{identifier}'));
 });
 
 test('listPages includes request-test instructions', async () => {

package/api/listPages.ts

@@ -7,7 +7,7 @@
 
 import {z} from 'zod';
 import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
-import {getAgoDays, getReportExtracts} from '../util.ts';
+import {getReportExtracts} from '../util.ts';
 import {listPagesResponseSchema} from './schemas.ts';
 
 // TYPES
@@ -20,42 +20,20 @@ type ResponseContent = z.infer<typeof listPagesResponseSchema>['response content
 // Returns the response body.
 export const response = async () => {
   const thisHost = getThisHost();
-  // Get extracts of all available reports, sorted by page description and completion time.
-  const reportExtracts = await getReportExtracts();
-  // Get the number of reports about each page.
-  const reportCounts = new Map<string, number>();
-  reportExtracts.forEach(({description}) => {
-    reportCounts.set(description, (reportCounts.get(description) ?? 0) + 1);
-  });
-  // Initialize an array of basics about the pages.
-  const pagesBasics: ResponseContent['basics about all tested pages'] = [];
-  // For each report:
-  reportExtracts.forEach(extract => {
-    const {description, id, reportTime, superseded, url} = extract;
-    // If it is the latest report about its page:
-    if (!superseded) {
-      // Add basics about the page, with instructions for getting details, to the array.
-      pagesBasics.push({
-        'tested web page': {
-          description,
-          URL: url
-        },
-        'number of reports about the page': reportCounts.get(description)!,
-        'basics about the latest report': {
-          identifier: id,
-          'completion date and time': reportTime,
-          'days since the report was completed': getAgoDays(new Date(reportTime))
-        },
-        'how to get details about the latest report': {
-          method: 'GET',
-          URL: `${thisHost}/api/listIssues/${id}`
-        },
-        'web users can get details about the latest report at': `${thisHost}/listIssues.html/${id}`
-      });
-    }
-  });
+  // Get extracts of the latest reports about all tested pages, sorted by page description.
+  const reportExtracts = await getReportExtracts(true);
+  // Get the basics about each tested page: its description, URL, and the identifier of
+  // its latest report, which the result-retrieval instructions below use as a placeholder.
+  const pagesBasics: ResponseContent['basics about all tested pages'] = reportExtracts.map(
+    ({description, id, url}) => ({description, URL: url, identifier: id})
+  );
   // Create the response content.
   const responseContent: ResponseContent = {
+    'how to get test results about a page': {
+      method: 'GET',
+      URL: `${thisHost}/api/listIssues/{identifier}`
+    },
+    'web users can get test results about a page at': `${thisHost}/listIssues.html/{identifier}`,
     'basics about all tested pages': pagesBasics,
     'how to request that a page with no report be tested': {
       method: 'POST',

package/api/listViolators.ts

@@ -21,6 +21,8 @@ import {listViolatorsResponseSchema} from './schemas.ts';
 
 // The response content defined by the response schema.
 type ResponseContent = z.infer<typeof listViolatorsResponseSchema>['response content'];
+// The basics about one element exhibiting the issue.
+type ViolatorBasics = NonNullable<ResponseContent['basics about all elements exhibiting the issue']>[number];
 
 // FUNCTIONS
 
@@ -96,7 +98,7 @@ export const response = async (args: string[]) => {
       );
       // Get basics about the violators.
       const violatorsBasics = sortedViolatorData
-      .map(violator => {
+      .map((violator): ViolatorBasics => {
         const {catalogIndex, reporters} = violator;
         const catalogItem = catalog[catalogIndex];
         return {
@@ -105,8 +107,8 @@ export const response = async (args: string[]) => {
           'inner text': catalogItem?.text ?? null,
           '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}/${reportID}`,
-            'request method': 'GET' as const
+            method: 'GET',
+            URL: `${thisHost}/api/listDiagnoses/${catalogIndex}/${issueID}/${reportID}`
           },
           'web users can get details about the element at': `${thisHost}/listDiagnoses.html/${issueID}/${reportID}/${catalogIndex}`
         };

package/api/reportDisagreement.test.ts

@@ -0,0 +1,208 @@
+/*
+  reportDisagreement.test.ts
+  Tests for api/reportDisagreement.ts using the fixture corpus, with mocked side effects.
+*/
+
+// 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';
+
+// Blank the alert configuration unconditionally, before ./reportDisagreement.ts (which
+// calls sendAlert) is ever imported below, so this file sends no real alert emails
+// even when run directly rather than via `npm test`.
+for (const key of ['MANAGER_EMAIL', 'ALERT_API_HOST', 'ALERT_API_PATH', 'ALERT_API_KEY', 'ALERT_FROM']) {
+  process.env[key] = '';
+}
+
+// ENVIRONMENT
+
+const testDir = path.join(import.meta.dirname, '../test/fixtures/disagreements');
+process.env.DISAGREEMENTS_PATH = path.join(testDir, 'disagreements.json');
+
+// SETUP AND TEARDOWN
+
+const savedDBDir = process.env.DB_DIR;
+let logged: any[] = [];
+const originalLog = console.log;
+
+before(async () => {
+  process.env.DB_DIR = (await import('../test/dbFixture.ts')).fixtureDBDir;
+});
+
+// Capture console.log so the alert sendAlert emits can be observed. The alert
+// configuration is blanked above, so sendAlert logs a WARNING instead of sending.
+beforeEach(async () => {
+  logged = [];
+  console.log = (...args) => logged.push(args.join(' '));
+  await fs.mkdir(testDir, {recursive: true});
+  await fs.writeFile(process.env.DISAGREEMENTS_PATH!, '[]\n');
+});
+
+import {response} from './reportDisagreement.ts';
+
+after(async () => {
+  console.log = originalLog;
+  if (savedDBDir !== undefined) {
+    process.env.DB_DIR = savedDBDir;
+  }
+  else {
+    delete process.env.DB_DIR;
+  }
+  await fs.rm(testDir, {recursive: true, force: true});
+});
+
+// TESTS
+
+test('reportDisagreement rejects a reason shorter than 20 characters', async () => {
+  const body = await response(['linkNoText', '260101T0000-mix', '0', 'axe', 'r11', 'Too short']);
+  const details = body['response content']['details about your request'] as any;
+  assert.ok(details.error.includes('reason'));
+  assert.ok(
+    !logged.some(line => line.startsWith('WARNING (Kilotest: diagnosis disagreement received)'))
+  );
+});
+
+test('reportDisagreement rejects a reason longer than 1000 characters', async () => {
+  const body = await response(['linkNoText', '260101T0000-mix', '0', 'axe', 'r11', 'x'.repeat(1001)]);
+  const details = body['response content']['details about your request'] as any;
+  assert.ok(details.error.includes('reason'));
+});
+
+test('reportDisagreement rejects a nonexistent report', async () => {
+  const body = await response(['linkNoText', '999999T9999-xyz', '0', 'axe', 'r11', 'This diagnosis is wrong, in my opinion']);
+  const details = body['response content']['details about your request'] as any;
+  assert.ok(details.error.includes('report'));
+});
+
+test('reportDisagreement rejects an element not in the report', async () => {
+  const body = await response(['linkNoText', '260101T0000-mix', '999', 'axe', 'r11', 'This diagnosis is wrong, in my opinion']);
+  const details = body['response content']['details about your request'] as any;
+  assert.ok(details.error.includes('element'));
+});
+
+test('reportDisagreement rejects a diagnosis no rule engine reported', async () => {
+  // The mixed report has axe and alfa diagnoses of rule r11 for element 0 and issue
+  // linkNoText, but no ibm diagnosis, so this engineID/ruleID pair matches nothing.
+  const body = await response(['linkNoText', '260101T0000-mix', '0', 'ibm', 'r11', 'This diagnosis is wrong, in my opinion']);
+  const details = body['response content']['details about your request'] as any;
+  assert.ok(details.error.includes('no such diagnosis'));
+});
+
+test('reportDisagreement rejects a rule ID reported only under a different issue', async () => {
+  const body = await response(['focusIndicationBad', '260101T0000-mix', '0', 'axe', 'r11', 'This diagnosis is wrong, in my opinion']);
+  const details = body['response content']['details about your request'] as any;
+  assert.ok(details.error.includes('no such diagnosis'));
+});
+
+test('reportDisagreement accepts a valid disagreement and notifies the manager', async () => {
+  const body = await response(['linkNoText', '260101T0000-mix', '0', 'axe', 'r11', 'The element does have an accessible name']);
+  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['diagnosis you disagree with']['identifier of the rule engine'], 'axe');
+  assert.equal(details['diagnosis you disagree with']['identifier of the violated rule'], 'r11');
+  assert.equal(details.disposition, 'received and logged; manager notified');
+  assert.ok(logged.some(line =>
+    line.startsWith('WARNING (Kilotest: diagnosis disagreement received)')
+    && line.includes('Disagreements now awaiting review: 1 of 20')
+  ));
+});
+
+test('reportDisagreement records a valid disagreement to the disagreements file', async () => {
+  await response(['linkNoText', '260101T0000-mix', '0', 'alfa', 'r11', 'The element does have an accessible name']);
+  const disagreements = JSON.parse(await fs.readFile(process.env.DISAGREEMENTS_PATH!, 'utf8'));
+  assert.equal(disagreements.length, 1);
+  assert.equal(disagreements[0].engineID, 'alfa');
+  assert.equal(disagreements[0].ruleID, 'r11');
+  assert.equal(disagreements[0].issueID, 'linkNoText');
+  assert.ok(disagreements[0].timeStamp);
+});
+
+test('reportDisagreement rejects a disagreement identical to one already on file', async () => {
+  const args = ['linkNoText', '260101T0000-mix', '0', 'axe', 'r11', 'The element does have an accessible name'];
+  const firstBody = await response(args);
+  const firstDetails = firstBody['response content']['details about your request'] as any;
+  assert.equal(firstDetails.error, undefined);
+  const secondBody = await response(args);
+  const secondDetails = secondBody['response content']['details about your request'] as any;
+  assert.ok(secondDetails.error.includes('identical to one already submitted'));
+  const disagreements = JSON.parse(await fs.readFile(process.env.DISAGREEMENTS_PATH!, 'utf8'));
+  // The duplicate was not recorded a second time.
+  assert.equal(disagreements.length, 1);
+});
+
+test('reportDisagreement accepts the same reason about a different diagnosis', async () => {
+  await response(['linkNoText', '260101T0000-mix', '0', 'axe', 'r11', 'The element does have an accessible name']);
+  const body = await response(['linkNoText', '260101T0000-mix', '0', 'alfa', 'r11', 'The element does have an accessible name']);
+  const details = body['response content']['details about your request'] as any;
+  assert.equal(details.error, undefined);
+  const disagreements = JSON.parse(await fs.readFile(process.env.DISAGREEMENTS_PATH!, 'utf8'));
+  assert.equal(disagreements.length, 2);
+});
+
+test('reportDisagreement creates the disagreements file when it does not exist', async () => {
+  await fs.unlink(process.env.DISAGREEMENTS_PATH!);
+  await response(['linkNoText', '260101T0000-mix', '0', 'axe', 'r11', 'The element does have an accessible name']);
+  const disagreements = JSON.parse(await fs.readFile(process.env.DISAGREEMENTS_PATH!, 'utf8'));
+  assert.equal(disagreements.length, 1);
+});
+
+test('reportDisagreement rejects a disagreement with a fallback channel when the inbox is full', async () => {
+  // Fill disagreements.json with 20 distinct disagreements, reaching the cap.
+  const filler = Array.from({length: 20}, (_, i) => ({
+    timeStamp: '260101T0000',
+    issueID: 'linkNoText',
+    reportID: '260101T0000-mix',
+    catalogIndex: '0',
+    engineID: 'axe',
+    ruleID: `r${i}`,
+    reason: `Filler disagreement number ${i}, long enough to pass the length check.`
+  }));
+  await fs.writeFile(process.env.DISAGREEMENTS_PATH!, JSON.stringify(filler));
+  const body = await response(['linkNoText', '260101T0000-mix', '0', 'axe', 'r11', 'The element does have an accessible name']);
+  const details = body['response content']['details about your request'] as any;
+  assert.ok(details.error.includes('too many disagreements are awaiting review right now.'));
+  assert.ok(details.error.includes('https://github.com/jrpool/kilotest/issues'));
+  assert.ok(details.error.includes('info@kilotest.com'));
+  const disagreements = JSON.parse(await fs.readFile(process.env.DISAGREEMENTS_PATH!, 'utf8'));
+  // The rejected disagreement was not recorded.
+  assert.equal(disagreements.length, 20);
+});
+
+test('reportDisagreement never rejects for a full inbox when DISAGREEMENTS_MAX is 0 (no limit)', async () => {
+  process.env.DISAGREEMENTS_MAX = '0';
+  try {
+    // Fill disagreements.json past the default cap.
+    const filler = Array.from({length: 25}, (_, i) => ({
+      timeStamp: '260101T0000',
+      issueID: 'linkNoText',
+      reportID: '260101T0000-mix',
+      catalogIndex: '0',
+      engineID: 'axe',
+      ruleID: `r${i}`,
+      reason: `Filler disagreement number ${i}, long enough to pass the length check.`
+    }));
+    await fs.writeFile(process.env.DISAGREEMENTS_PATH!, JSON.stringify(filler));
+    const body = await response(['linkNoText', '260101T0000-mix', '0', 'axe', 'r11', 'The element does have an accessible name']);
+    const details = body['response content']['details about your request'] as any;
+    assert.equal(details.error, undefined);
+  }
+  finally {
+    delete process.env.DISAGREEMENTS_MAX;
+  }
+});
+
+test('reportDisagreement does not record an invalid disagreement', async () => {
+  await response(['linkNoText', '260101T0000-mix', '0', 'axe', 'r11', 'short']);
+  const disagreements = JSON.parse(await fs.readFile(process.env.DISAGREEMENTS_PATH!, 'utf8'));
+  assert.equal(disagreements.length, 0);
+});
+
+test('reportDisagreement includes tool name and metadata', async () => {
+  const body = await response(['linkNoText', '260101T0000-mix', '0', 'axe', 'r11', 'The element does have an accessible name']);
+  assert.equal(body['tool name'], 'reportDisagreement');
+  assert.ok(body['response metadata'].identifier);
+});

package/api/reportDisagreement.ts

@@ -0,0 +1,208 @@
+/*
+  reportDisagreement.ts
+  Processes a report that the requester disagrees with a diagnosis and returns an acknowledgement.
+*/
+
+// IMPORTS
+
+import {z} from 'zod';
+import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
+import {sendAlert} from '../alerts.ts';
+import {
+  checkLength,
+  describeMax,
+  getEnvMax,
+  getJSON,
+  getNowStamp,
+  getReport,
+  getTestActInstances,
+  isReportError
+} from '../util.ts';
+import {reportDisagreementResponseSchema} from './schemas.ts';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// TYPES
+
+// The response content defined by the response schema.
+type ResponseContent = z.infer<typeof reportDisagreementResponseSchema>['response content'];
+
+// A stored disagreement with a diagnosis.
+type Disagreement = {
+  timeStamp: string;
+  issueID: string;
+  reportID: string;
+  catalogIndex: string;
+  engineID: string;
+  ruleID: string;
+  reason: string;
+};
+
+// FUNCTIONS (helpers)
+
+const getDisagreementsPath = () => process.env.DISAGREEMENTS_PATH || path.join(import.meta.dirname, '../db/disagreements.json');
+// Maximum number of diagnosis disagreements held at once. Once reached, a new, distinct
+// disagreement is rejected rather than stored, so the disagreements file and the manager
+// alert emails it generates cannot grow without bound (modeled on the feature-request
+// cap in requestFeature.ts). Configurable via DISAGREEMENTS_MAX; a value of 0 means no
+// limit.
+const getDisagreementsMax = () => getEnvMax('DISAGREEMENTS_MAX', 20);
+
+// FUNCTIONS
+
+// Returns the response body.
+export const response = async (args: string[]) => {
+  const [issueID = '', reportID = '', catalogIndex = '', engineID = '', ruleID = '', reason = ''] = args;
+  const thisHost = getThisHost();
+  const reasonCheck = checkLength(reason, 20, 1000, 'reason');
+  // Initialize the response content.
+  let responseContent: ResponseContent;
+  // If the reason is too short or too long:
+  if (reasonCheck.status === 'error') {
+    responseContent = {
+      'details about your request': {
+        error: `request invalid: your ${reasonCheck.message}`
+      }
+    };
+  }
+  // Otherwise, i.e. if it is valid:
+  else {
+    // Get the report.
+    const report = await getReport(reportID);
+    // If the report was not retrieved successfully:
+    if (isReportError(report)) {
+      responseContent = {
+        'details about your request': {
+          error: 'request invalid: the specified report does not exist or is not usable'
+        }
+      };
+    }
+    // Otherwise, if the element is not in the report's catalog:
+    else if (!report.catalog[catalogIndex]) {
+      responseContent = {
+        'details about your request': {
+          error: 'request invalid: the specified element is not in the report'
+        }
+      };
+    }
+    // Otherwise, i.e. if the report and element exist:
+    else {
+      // Get the reported diagnoses of the element for the issue matching the engine and
+      // rule (a ruleID is only unique within a rule engine: axe and alfa, for example,
+      // both report rules numbered like r11 for the same element and issue).
+      const matches = getTestActInstances(report, {violationsOnly: true, issueID, catalogIndex})
+      .filter(({act, instance}) => act.which === engineID && instance.ruleID === ruleID);
+      // If no reported diagnosis matches:
+      if (!matches.length) {
+        responseContent = {
+          'details about your request': {
+            error: 'request invalid: no such diagnosis was reported for the specified element and issue'
+          }
+        };
+      }
+      // Otherwise, i.e. if the diagnosis exists:
+      else {
+        // Get the disagreements already on file.
+        const disagreementsPath = getDisagreementsPath();
+        let disagreements: Disagreement[] = [];
+        try {
+          const existing = await fs.readFile(disagreementsPath, 'utf8');
+          disagreements = JSON.parse(existing);
+        }
+        catch {
+          // Initialize an empty disagreements array.
+        }
+        // If the disagreement is identical to one already on file:
+        if (disagreements.some(d =>
+          d.issueID === issueID
+          && d.reportID === reportID
+          && d.catalogIndex === catalogIndex
+          && d.engineID === engineID
+          && d.ruleID === ruleID
+          && d.reason === reason
+        )) {
+          responseContent = {
+            'details about your request': {
+              error: 'request invalid: your disagreement is identical to one already submitted, ' +
+                'but you are welcome to submit a different one'
+            }
+          };
+        }
+        // Otherwise, if the disagreements already on file have reached the cap (a cap of 0
+        // means no limit, so the queue is never full):
+        else if (getDisagreementsMax() > 0 && disagreements.length >= getDisagreementsMax()) {
+          responseContent = {
+            'details about your request': {
+              error: 'request invalid: too many disagreements are awaiting review right now. ' +
+                'Please try again later, or post your report at https://github.com/jrpool/kilotest/issues ' +
+                'or email info@kilotest.com.'
+            }
+          };
+        }
+        // Otherwise, i.e. if it is not a duplicate and the queue is not full:
+        else {
+          // Record the disagreement alongside the existing ones.
+          disagreements.push({
+            timeStamp: getNowStamp(),
+            issueID,
+            reportID,
+            catalogIndex,
+            engineID,
+            ruleID,
+            reason
+          });
+          await fs.mkdir(path.dirname(disagreementsPath), {recursive: true});
+          await fs.writeFile(disagreementsPath, getJSON(disagreements));
+          // Notify the manager, including the resulting count, so a maintainer who has been
+          // away sees at a glance how urgently the disagreements need review. The ruleID is
+          // truncated because some rule engines (nuVal, nuVnu) use entire validator messages
+          // as rule identifiers, which can be arbitrarily long.
+          await sendAlert(
+            'Kilotest: diagnosis disagreement received',
+            `Disputed diagnosis: ${engineID} rule ${ruleID.slice(0, 500)} classified as issue ${issueID} ` +
+            `on element ${catalogIndex} of report ${reportID}\nReason: ${reason}\n` +
+            `Disagreements now awaiting review: ${disagreements.length} of ${describeMax(getDisagreementsMax())}`
+          );
+          // Add the disposition to the response content.
+          responseContent = {
+            'details about your request': {
+              'date and time received': new Date().toISOString(),
+              'diagnosis you disagree with': {
+                'issue identifier': issueID,
+                'identifier of the rule engine': engineID,
+                'identifier of the violated rule': ruleID
+              },
+              disposition: 'received and logged; manager notified'
+            }
+          };
+        }
+      }
+    }
+  }
+  // Create a response body.
+  const body = {
+    'tool collection': getToolsFacts(),
+    'tool name': 'reportDisagreement',
+    'this request': {
+      description: 'Process my report that I disagree with a diagnosis. The issueID, reportID, and catalogIndex parameters identify the issue, report, and element of the diagnosis. They were in the response to my earlier listDiagnoses request. The engineID and ruleID properties of the request body identify which diagnosis I disagree with, and the reason property explains why I disagree with it.',
+      method: 'POST',
+      URL: `${thisHost}/api/reportDisagreement/${issueID}/${reportID}/${catalogIndex}`,
+      body: {
+        engineID,
+        ruleID,
+        reason
+      },
+      'closest ancestor request': {
+        'tool name': 'listDiagnoses',
+        description: 'Provide details about one element reported as exhibiting one issue in one report, including the diagnoses provided by rule engines about how the element exhibited the issue.',
+        method: 'GET',
+        URL: `${thisHost}/api/listDiagnoses/${catalogIndex}/${issueID}/${reportID}`
+      }
+    },
+    'URLs of similar requests for web users': null,
+    'response metadata': getResponseMetadata(),
+    'response content': responseContent
+  };
+  // Return it.
+  return body;
+};