@jrpool/kilotest 57.3.0 → 58.2.0

package/web/listViolators/index.ts

@@ -8,18 +8,17 @@
 import {
   getReport,
   getTestActInstances,
-  htmlSafe,
   isReportError,
   populateTemplate
 } from '../../util.ts';
 import {
+  getIssueFactsLines,
   getPageDataStrings,
+  getPageFactsLines,
   getPathID,
-  getEngineNamesString,
+  getReportData,
   getTextFragmentHref,
-  getWCAGLink,
-  getWeightName,
-  makeBreakable
+  getViolatorFactsLines
 } from '../util.ts';
 import {issues as issueSpecs} from 'testaro-issues';
 
@@ -32,8 +31,17 @@ const populateQuery = async (
   jobID: string,
   query: Record<string, any>
 ) => {
-  // Get descriptions of the page facts.
-  const pageDataStrings = await getPageDataStrings(timeStamp, jobID);
+  // Get the report.
+  const report = await getReport(timeStamp, jobID);
+  // If this failed:
+  if (isReportError(report)) {
+    // Populate the query with the reason.
+    query.error = report.error;
+    // Stop populating the query.
+    return;
+  }
+  // Otherwise, i.e. if it succeeded, get descriptions of the page facts.
+  const pageDataStrings = getPageDataStrings(report);
   // If this failed:
   if (pageDataStrings.error !== undefined) {
     // Populate the query with the reason.
@@ -50,58 +58,28 @@ const populateQuery = async (
     // Stop populating the query.
     return;
   }
-  const {testInfo, url, urlLink, description} = pageDataStrings;
+  const {testInfo, url, description} = pageDataStrings;
   // Add page facts to the query.
   query.target = description;
-  query.urlLink = urlLink;
   query.testInfo = testInfo;
-  const issue = issueSpecs[issueID]!;
-  const {wcag, weight, why} = issue;
-  query.why = why;
-  query.priority = getWeightName(weight);
-  query.wcag = `<a href="${getWCAGLink(wcag)}">${wcag}</a>`;
-  // Initialize those whose values depend on instance inspection.
-  query.count = 0;
-  query.reporters = new Set();
+  query.pageFacts = getPageFactsLines(
+    pageDataStrings, getReportData(report), ' '.repeat(6)
+  ).join('\n');
+  // Add the issue facts to the query.
+  query.issueFacts = getIssueFactsLines(report, issueID, ' '.repeat(6)).join('\n');
+  // Initialize the violator data.
   let violators: any = {};
-  // Get the report.
-  const report = await getReport(timeStamp, jobID);
-  // If this failed:
-  if (isReportError(report)) {
-    // Populate the query with the reason.
-    query.error = report.error;
-    // Stop populating the query.
-    return;
-  }
   const {catalog} = report;
-  // Otherwise, i.e. if it succeeded, for each violating standard instance of the issue:
-  getTestActInstances(report, {violationsOnly: true, issueID}).forEach(({act, instance}) => {
+  const testActInstances = getTestActInstances(report, {violationsOnly: true, issueID});
+  // For each violating standard instance of the issue:
+  testActInstances.forEach(({instance}) => {
     const pathID = instance.pathID || '/html';
     const catalogIndex = String(instance.catalogIndex || '0');
-    const tagName = catalog[catalogIndex]?.tagName
-    ?? pathID.split('/').pop()!.replace(/\[.+$/, '').toUpperCase();
+    // Initialize the violator data if necessary.
     violators[catalogIndex] ??= {
-      pathID: getPathID(catalog, catalogIndex, pathID),
-      tagName,
-      text: catalog[catalogIndex]?.text ?? '',
-      reporters: new Set()
+      pathID: getPathID(catalog, catalogIndex, pathID)
     };
-    // Ensure that the rule engine is in the sets of reporters of the violator and the issue.
-    violators[catalogIndex].reporters.add(act.which);
-    query.reporters.add(act.which);
   });
-  // Populate the violator count.
-  const violatorCount = Object.keys(violators).length;
-  query.violatorCount = violatorCount === 1 ? '1 violator was' : `${violatorCount} violators were`;
-  // For each violator:
-  Object.values(violators).forEach((violatorData: any) => {
-    // Convert the set of its reporters to a string.
-    violatorData.reporters = getEngineNamesString(violatorData.reporters);
-  });
-  const reporterCount = query.reporters.size;
-  query.reporterCount = reporterCount === 1 ? '1 rule engine' : `${reporterCount} rule engines`;
-  // Convert the set of issue reporters to a string.
-  query.reporters = getEngineNamesString(query.reporters);
   // Convert the violator data to an array.
   violators = Object.entries(violators).map((entry: [string, any]) => ({
     catalogIndex: entry[0],
@@ -115,23 +93,11 @@ const populateQuery = async (
   let takeMeAdviceNeeded = false;
   // For each violator:
   violators.forEach((violator: any, index: number) => {
-    const {catalogIndex, pathID, reporters, tagName, text} = violator;
+    const {catalogIndex, pathID} = violator;
     // Add a heading to the lines.
     lines.push(`${margin}<li><h3>Element ${catalogIndex}</h3>`);
-    lines.push(`${margin}  <ul class="pseudoTopLevel">`);
-    // Add properties of the violator to the lines.
-    if (pathID) {
-      lines.push(`${margin}    <li>XPath: <code>${makeBreakable(pathID)}</code></li>`);
-    }
-    if (tagName) {
-      lines.push(`${margin}    <li>Tag name: <code>${tagName}</code></li>`);
-    }
-    if (text && !['HTML', 'HEAD', 'BODY', 'MAIN', 'NOSCRIPT'].includes(tagName)) {
-      const textString = text.split('\n').join(' … ');
-      lines.push(`${margin}    <li>Text: <q>${htmlSafe(textString)}</q></li>`);
-    }
-    lines.push(`${margin}    <li>Reported by ${reporters}</li>`);
-    lines.push(`${margin}  </ul>`);
+    // Add the violator facts to the lines.
+    lines.push(...getViolatorFactsLines(report, issueID, catalogIndex, pathID, `${margin}  `, 'pseudoTopLevel'));
     lines.push(`${margin}  <ul class="nav">`);
     if (catalogIndex) {
       const catalogItem = catalog[catalogIndex];

package/web/listViolators/listViolators.test.ts

@@ -33,7 +33,7 @@ mock.module('../../util.ts', {
 mock.module('../util.ts', {
   exports: {
     ...realWebUtil,
-    getPageDataStrings: async (...args: any[]) => {
+    getPageDataStrings: (...args: any[]) => {
       if (pageDataStringsOverride !== null) {
         return pageDataStringsOverride;
       }
@@ -86,7 +86,7 @@ test('listViolators includes links to listDiagnoses for violators', async () =>
 test('listViolators excludes cantTell instances from the violator count', async () => {
   const result = await answer('focusIndicationBad/260101T0000/mix');
   assert.equal(result.status, 'ok');
-  assert.ok(result.answerPage.includes('0 violators were'));
+  assert.ok(result.answerPage.includes('<li>Violators: 0</li>'));
   assert.ok(!result.answerPage.includes('<h3>Element'));
 });
 
@@ -101,7 +101,7 @@ test('listViolators returns an error status for an unknown issue', async () => {
   assert.equal(result.status, 'error');
 });
 
-test('listViolators returns an error when getReport fails after getPageDataStrings succeeds', async () => {
+test('listViolators returns an error when getReport fails', async () => {
   getReportCallCount = 0;
   failGetReportOnCall = 1;
   try {
@@ -114,6 +114,18 @@ test('listViolators returns an error when getReport fails after getPageDataStrin
   }
 });
 
+test('listViolators returns an error when getPageDataStrings fails after getReport succeeds', async () => {
+  pageDataStringsOverride = {error: 'Page data strings error'};
+  try {
+    const result = await answer('linkNoText/260101T0000/mix');
+    assert.equal(result.status, 'error');
+    assert.equal(result.message, 'Page data strings error');
+  }
+  finally {
+    pageDataStringsOverride = null;
+  }
+});
+
 test('listViolators includes take-me-there links for text-linkable violators', async () => {
   const dbDir = (await import('../../test/dbFixture.ts')).fixtureDBDir;
   const reportsDir = path.join(dbDir, 'reports');
@@ -260,7 +272,7 @@ test('listViolators handles instances with missing catalogIndex and acts with no
     const result = await answer('linkNoText/260101T0004/nvi');
     assert.equal(result.status, 'ok');
     // Should show plural violator count.
-    assert.ok(result.answerPage.includes('2 violators were'));
+    assert.ok(result.answerPage.includes('<li>Violators: 2</li>'));
   }
   finally {
     await fs.unlink(reportPath).catch(() => {});

package/web/reportDeletion.ts

@@ -7,6 +7,8 @@
 
 import {
   errorMessage,
+  getReport,
+  isReportError,
   isValidAuthCode,
   objectSort,
   populateTemplate,
@@ -90,16 +92,18 @@ export const reportDeletionForm = async (
   // For each report:
   for (const reportName of reportNames) {
     const [timeStamp, jobID] = reportName.slice(0, -5).split('-') as [string, string];
-    // Get a summary of it.
-    const reportFacts = await getReportData(timeStamp, jobID);
+    // Get the report.
+    const report = await getReport(timeStamp, jobID);
     // If this failed:
-    if (reportFacts.error !== undefined) {
+    if (isReportError(report)) {
       // Return why.
       return {
         status: 'error',
-        message: reportFacts.error
+        message: report.error
       };
     }
+    // Otherwise, i.e. if it succeeded, get a summary of it.
+    const reportFacts = getReportData(report);
     const {issueCount, preventedEngineCount, url} = reportFacts;
     // Otherwise, i.e. if it succeeded, add the summary to the array.
     reportSpecs.push({

package/web/requestNewTest/index.ts

@@ -33,12 +33,12 @@ export const answer = async (description: string, url: string, reason: string) =
       message: 'Test request duplicates an already submitted request'
     };
   }
-  // Otherwise, if a report is available about a page with the same description and URL:
+  // Otherwise, if a report is available about a page with the same description or URL:
   else if (result === 'reportExists') {
     // Report this.
     return {
       status: 'error',
-      message: 'A report about the page is already available'
+      message: 'A report about a page with the same description or URL is already available'
     }
   }
   // Otherwise, if the queue of requests awaiting approval is full:

package/web/requestNewTest/requestNewTest.test.ts

@@ -126,7 +126,7 @@ test('answer returns an error when a report already exists for the page', {timeo
     'Mixed Outcomes Page', 'https://example.com/mixed', 'Because accessibility'
   );
   assert.equal(result.status, 'error');
-  assert.equal(result.message, 'A report about the page is already available');
+  assert.equal(result.message, 'A report about a page with the same description or URL is already available');
 });
 
 test('answer returns an error with a fallback channel when the request queue is full', {timeout: 500}, async () => {

package/web/tutorialAI/index.html

@@ -15,7 +15,7 @@
     <main>
       <h1><a href="/">Kilotest</a>: Connect an AI Platform</h1>
       <h2>Purpose</h2>
-      <p>This tutorial shows you how to make Kilotest available to AI assistants. Suppose:</p>
+      <p>This tutorial shows you how to make Kilotest available to assistants powered by artificial intelligence. Suppose:</p>
       <ul>
         <li>You use an AI platform, like Claude, Mistral Vibe, or Perplexity Pro.</li>
         <li>You want to audit the quality of a web page.</li>
@@ -26,6 +26,7 @@
         <li><a href="#claude">Claude.ai in a browser or Claude Desktop</a></li>
         <li><a href="#vibe">Mistral Vibe</a></li>
         <li><a href="#perplexity">Perplexity Pro in a browser</a></li>
+        <li><a href="#other">Other platforms</a></li>
       </ul>
       <h2 id="claude"><a href="https://claude.ai">Claude.ai in a browser</a> or <a href="https://downloads.claude.com">Claude Desktop</a></h2>
       <ol>
@@ -52,7 +53,7 @@
         <li>Click the <q>Add connector</q> button.</li>
         <li>Toggle the <q>Ask/Allow</q> buttons to show <q>Allow</q>.</li>
       </ol>
-      <h2 id="perplexity">Perplexity Pro in a browser</h2>
+      <h2 id="perplexity"><a href="https://www.perplexity.ai/">Perplexity</a> Pro in a browser</h2>
       <ol>
         <li>After signing in, click the <q>Customize</q> button in the left sidebar.</li>
         <li>Click the <q>+ Custom connector</q> menu button.</li>
@@ -65,10 +66,9 @@
         <li>Click the <q>Add</q> button.</li>
       </ol>
       <p>Once you add Kilotest, it <strong>may</strong> become available in the Perplexity app on your computer or mobile device, too.</p>
-      <h2>Other AI platforms</h2>
-      <p>You can connect Kilotest to some other AI platforms, too. The instructions above are limited to platforms that are either free or relatively inexpensive (US$20 per month or less). If you discover an AI platform that should be added to this page, please submit a comment below.</p>
-      <h2>Trouble?</h2>
-      <p>What if this did not work? Use the comment form below to tell us about it.</p>
+      <h2 id="other">Other AI platforms</h2>
+      <p>You can connect Kilotest to some other AI platforms, too. The instructions above are limited to consumer platforms that are either free or relatively inexpensive (US$20 per month or less). Business platforms such as ChatGPT Business, and developer platforms such as Devin Desktop, also permit you to enable Kilotest.</p>
+      <p>Feel free to submit a comment below about empowering any AI platform to use Kilotest.</p>
       <p>You can also submit an issue on the <a href="https://github.com/jrpool/kilotest/issues">Kilotest GitHub repository</a>.</p>
       <section id="suggest-improvement" class="main">
         <h2>Suggest improvements</h2>

package/web/util.test.ts

@@ -9,15 +9,17 @@ 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 {reportsPath} from '../util.ts';
+import {getReport, isReportError, reportsPath} from '../util.ts';
 import {
   checkCommentLength,
   getAgoString,
   getCountString,
+  getEngineIDs,
   getEngineNamesString,
   getMultiReportWhats,
   getPageData,
   getPageDataStrings,
+  getPageFactsLines,
   getTextFragmentHref,
   getWCAGLink,
   getWeightName,
@@ -115,65 +117,79 @@ test('makeBreakable inserts wbr before non-initial slashes', () => {
   assert.equal(makeBreakable('/api/listReports'), '/api<wbr>/listReports');
 });
 
+// Returns a fixture report, failing the test if it is not usable.
+const getFixtureReport = async (timeStamp: string, jobID: string) => {
+  const report = await getReport(timeStamp, jobID);
+  if (isReportError(report)) {
+    assert.fail(report.error);
+  }
+  return report;
+};
+
 test('getPageData returns page data for a valid report', async () => {
-  const data = await getPageData('260101T0000', 'mix') as any;
+  const data = getPageData(await getFixtureReport('260101T0000', 'mix'));
   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') as any;
-  assert.ok(data.error);
+test('getReport returns an error for a nonexistent report', async () => {
+  const report = await getReport('999999T9999', 'xxx');
+  assert.ok(isReportError(report));
 });
 
 test('getPageDataStrings returns HTML strings for a valid report', async () => {
-  const strings = await getPageDataStrings('260101T0000', 'mix') as any;
+  const strings = getPageDataStrings(await getFixtureReport('260101T0000', 'mix'));
   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>'));
+  assert.ok(strings.testInfo.includes('by job <code>260101T0000-mix</code>'));
   assert.ok(strings.testInfo.includes('2026-01-01 at 00:00'));
 });
 
 test('getPageDataStrings returns different testInfo for a different timeStamp', async () => {
-  const strings = await getPageDataStrings('260101T0001', 'ct') as any;
+  const strings = getPageDataStrings(await getFixtureReport('260101T0001', 'ct'));
   assert.equal(strings.description, 'All CantTell Page');
-  assert.ok(strings.testInfo.includes('by job <code>ct</code>'));
+  assert.ok(strings.testInfo.includes('by job <code>260101T0001-ct</code>'));
   assert.ok(strings.testInfo.includes('2026-01-01 at 00:01'));
 });
 
-test('getPageDataStrings returns an error for a nonexistent report', async () => {
-  const strings = await getPageDataStrings('999999T9999', 'xxx');
-  assert.ok(strings.error);
+test('getPageDataStrings derives the strings from the report object', async () => {
+  const report = await getFixtureReport('260101T0000', 'mix');
+  report.target.what = 'Custom Page';
+  const strings = getPageDataStrings(report);
+  assert.equal(strings.description, 'Custom Page');
 });
 
-test('getPageDataStrings uses provided pageData instead of reading the report', async () => {
-  const strings = await getPageDataStrings('260101T0000', 'mix', {
-    description: 'Custom Page',
-    url: 'https://custom.com',
-    daysAgo: 1
-  }) as any;
-  assert.equal(strings.description, 'Custom Page');
-  assert.equal(strings.url, 'https://custom.com');
+test('getPageDataStrings reports a 1-day-old report as tested 1 day ago', () => {
+  // Construct an end time 1 day and 1 hour ago, so Math.round gives exactly 1.
+  const date = new Date(Date.now() - (86400000 + 3600000));
+  const endTime = date.toISOString().slice(2, 16);
+  const report = {
+    id: '260101T0000-mix',
+    target: {what: 'Some Page', url: 'https://example.com'},
+    jobData: {endTime}
+  } as any;
+  const strings = getPageDataStrings(report);
   assert.ok(strings.testInfo.includes('1 day ago'));
 });
 
-test('getReportData returns an error for a nonexistent report', async () => {
+test('getReportData returns data for a valid report', async () => {
   const {getReportData} = await import('./util.ts');
-  const result: any = await getReportData('990101T0000', 'xxx');
-  assert.ok(result.error);
+  const result = getReportData(await getFixtureReport('260101T0000', 'mix'));
+  assert.equal(result.url, 'https://example.com/mixed');
+  assert.equal(result.jobName, '260101T0000-mix');
 });
 
 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 reportJSON = JSON.parse(prvJSON);
+  reportJSON.jobData.preventions.unknownEngine = 'mystery failure';
   const reportPath = path.join(reportsPath(), '260103T0000-unk.json');
-  await fs.writeFile(reportPath, JSON.stringify(report));
+  await fs.writeFile(reportPath, JSON.stringify(reportJSON));
   try {
-    const result: any = await getReportData('260103T0000', 'unk');
+    const result = getReportData(await getFixtureReport('260103T0000', 'unk'));
     assert.ok(result.preventedEngineNames.includes('unknownEngine'));
   }
   finally {
@@ -181,6 +197,44 @@ test('getReportData falls back to the engine ID for an unknown prevented engine'
   }
 });
 
+test('getPageFactsLines returns the about-page list lines for a report', async () => {
+  const {getReportData} = await import('./util.ts');
+  const report = await getFixtureReport('260101T0000', 'mix');
+  const lines = getPageFactsLines(getPageDataStrings(report), getReportData(report), '  ');
+  const html = lines.join('\n');
+  assert.ok(html.includes('<li>URL: <a href="https://example.com/mixed">'));
+  assert.ok(html.includes('<li>Summary of results:'));
+  assert.ok(html.includes('<li>Called: 2</li>'));
+  assert.ok(html.includes('<li>Violations: 3</li>'));
+  assert.ok(html.includes('<li>Issues: 2</li>'));
+});
+
+test('getIssueFactsLines returns the about-issue list lines for a report', async () => {
+  const {getIssueFactsLines} = await import('./util.ts');
+  const report = await getFixtureReport('260101T0000', 'mix');
+  const lines = getIssueFactsLines(report, 'linkNoText', '  ');
+  const html = lines.join('\n');
+  assert.ok(html.includes('<li>Why it matters:'));
+  assert.ok(html.includes('<li>Priority:'));
+  assert.ok(html.includes('<li>Related WCAG standard: <a href='));
+  assert.ok(html.includes('<li>Reported by'));
+  assert.ok(html.includes('<li>Violations:'));
+  assert.ok(html.includes('<li>Violators:'));
+});
+
+test('getViolatorFactsLines returns the about-violator list lines for a report', async () => {
+  const {getViolatorFactsLines} = await import('./util.ts');
+  const report = await getFixtureReport('260101T0000', 'mix');
+  const lines = getViolatorFactsLines(report, 'linkNoText', '0', null, '  ');
+  const html = lines.join('\n');
+  assert.ok(html.includes('<li>Tag name: <code>'));
+  assert.ok(html.includes('<li>Text:'));
+  assert.ok(html.includes('<li>Start tag: <code>'));
+  assert.ok(html.includes('<li>XPath: <code>'));
+  assert.ok(html.includes('<li>Bounding box:'));
+  assert.ok(html.includes('<li>Reported by'));
+});
+
 test('getAgoString returns "1 day" for exactly 1 day ago', () => {
   // Construct a time stamp 1 day and 1 hour ago, so Math.round gives exactly 1.
   const date = new Date(Date.now() - (86400000 + 3600000));
@@ -238,3 +292,45 @@ test('getMultiReportWhats returns descriptions that have multiple reports', asyn
   const whats = await getMultiReportWhats();
   assert.ok(whats.includes('Mixed Outcomes Page'));
 });
+
+// Returns a minimal report for testing rule-engine identification.
+const makeEngineReport = (whiches: string[], preventions: Record<string, string>) => ({
+  acts: whiches.map(which => ({type: 'test', which})),
+  jobData: {preventions}
+});
+
+test('getEngineIDs counts a prevented engine, which has an act, once', () => {
+  const ids = getEngineIDs(makeEngineReport(['axe', 'wave'], {wave: 'failed'}));
+  assert.deepEqual(ids.calledIDs.sort(), ['axe', 'wave']);
+  assert.deepEqual(ids.preventedIDs, ['wave']);
+});
+
+test('getEngineIDs counts a prevented engine that has no act', () => {
+  const ids = getEngineIDs(makeEngineReport(['axe'], {alfa: 'failed'}));
+  assert.deepEqual(ids.calledIDs.sort(), ['alfa', 'axe']);
+  assert.deepEqual(ids.preventedIDs, ['alfa']);
+});
+
+test('getEngineIDs counts nuVal and nuVnu as one engine when nuVal succeeds', () => {
+  const ids = getEngineIDs(makeEngineReport(['nuVal', 'nuVnu'], {}));
+  assert.deepEqual(ids.calledIDs, ['nuVal']);
+  assert.deepEqual(ids.preventedIDs, []);
+});
+
+test('getEngineIDs ignores a nuVal prevention when nuVnu succeeds', () => {
+  const ids = getEngineIDs(makeEngineReport(['nuVal', 'nuVnu'], {nuVal: 'failed'}));
+  assert.deepEqual(ids.calledIDs, ['nuVal']);
+  assert.deepEqual(ids.preventedIDs, []);
+});
+
+test('getEngineIDs counts one prevention when both nuVal and nuVnu are prevented', () => {
+  const ids = getEngineIDs(makeEngineReport(['nuVal', 'nuVnu'], {nuVal: 'failed', nuVnu: 'failed'}));
+  assert.deepEqual(ids.calledIDs, ['nuVal']);
+  assert.deepEqual(ids.preventedIDs, ['nuVal']);
+});
+
+test('getEngineIDs counts a nuVal prevention when nuVnu was not called', () => {
+  const ids = getEngineIDs(makeEngineReport(['nuVal'], {nuVal: 'failed'}));
+  assert.deepEqual(ids.calledIDs, ['nuVal']);
+  assert.deepEqual(ids.preventedIDs, ['nuVal']);
+});