@jrpool/kilotest 46.1.2 → 48.0.0

package/web/listDiagnoses/{index.js → index.ts}

@@ -1,56 +1,66 @@
 /*
-  index.js
+  index.ts
   Lists the diagnoses of a violator of an issue in a report.
 */
 
 // IMPORTS
 
-const {
+import {
   getPageDataStrings,
   getReport,
+  getTestActInstances,
   getTextFragmentHref,
   getWCAGLink,
   getWeightName,
   htmlSafe,
-  isHidden,
+  isReportError,
+  populateTemplate,
   ruleEngines
-} = require('../../util');
-const {issues: issueSpecs} = require('testaro-issues');
-const fs = require('fs/promises');
-const path = require('path');
+} from '../../util.ts';
+import {issues as issueSpecs} from 'testaro-issues';
 
 // FUNCTIONS
 
 // Adds parameters to a query for the answer page.
-const populateQuery = async (issueID, timeStamp, jobID, catalogIndex, pathID, query) => {
+const populateQuery = async (
+  issueID: string,
+  timeStamp: string,
+  jobID: string,
+  catalogIndex: string,
+  pathID: string | null,
+  query: Record<string, any>
+) => {
   // Get descriptions of the page facts.
   const pageDataStrings = await getPageDataStrings(timeStamp, jobID);
   // If this failed:
-  if (pageDataStrings.error) {
+  if (pageDataStrings.error !== undefined) {
     // Populate the query with the reason.
     query.error = pageDataStrings.error;
     // Stop populating the query.
     return;
   }
-  const {testInfo, url, urlLink, what} = pageDataStrings;
+  const {testInfo, url, urlLink, description} = pageDataStrings;
   // Otherwise, i.e. if it succeeded, get the report.
   const report = await getReport(timeStamp, jobID);
-  const {acts, catalog} = report;
   // If this failed:
-  if (report.error) {
+  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, get the catalog item of the specified violator.
-  const catalogItem = catalog[catalogIndex] ?? {};
-  const {boxID, startTag, tagName, text} = catalogItem;
+  const catalogItem = catalog[catalogIndex];
+  const boxID = catalogItem?.boxID;
+  const startTag = catalogItem?.startTag;
+  const tagName = catalogItem?.tagName;
+  const text = catalogItem?.text;
   query.catalogIndex = catalogIndex;
-  const lines = [];
+  const lines: string[] = [];
   const margin = ' '.repeat(6);
-  if (catalogIndex && catalogItem.textLinkable) {
-    const href = getTextFragmentHref(text, url);
+  if (catalogIndex && catalogItem?.textLinkable) {
+    const href = getTextFragmentHref(text as string, url);
     const label = `Take me to element ${catalogIndex} on the page (in a new tab)`;
     const link = `<a href="${href}" target="_blank" aria-label="${label}">Take me there</a>`;
     query.takeMeThere = `${margin}    <p>${link}</p>`;
@@ -59,7 +69,7 @@ const populateQuery = async (issueID, timeStamp, jobID, catalogIndex, pathID, qu
     query.takeMeThere = '';
   }
   // Add facts about the issue to the query.
-  query.target = what;
+  query.target = description;
   query.urlLink = urlLink;
   query.testInfo = testInfo;
   query.issue = issueSpecs[issueID]?.summary;
@@ -71,20 +81,20 @@ const populateQuery = async (issueID, timeStamp, jobID, catalogIndex, pathID, qu
     return;
   }
   // Otherwise, i.e. if it succeeded, get the issue details.
-  const issue = issueSpecs[issueID];
+  const issue = issueSpecs[issueID]!;
   const {wcag, weight, why} = issue;
   query.why = why;
   query.priority = getWeightName(weight);
   query.wcag = `<a href="${getWCAGLink(wcag)}">${wcag}</a>`;
   query.tagName = tagName || 'HTML';
-  if (text && !['HTML', 'BODY', 'HEAD', 'SCRIPT', 'STYLE', 'NOSCRIPT'].includes(tagName)) {
+  if (text && !['HTML', 'BODY', 'HEAD', 'SCRIPT', 'STYLE', 'NOSCRIPT'].includes(tagName as string)) {
     const textString = text.split('\n').join(' … ');
     query.text = `<q>${htmlSafe(textString)}</q>`;
   }
   else {
     query.text = '[not applicable]';
   }
-  query.startTag = htmlSafe(startTag) || '[not obtained]';
+  query.startTag = htmlSafe(startTag ?? '') || '[not obtained]';
   query.pathID = pathID || '[not obtained]';
   if (boxID) {
     const dims = boxID.split(':');
@@ -94,23 +104,15 @@ const populateQuery = async (issueID, timeStamp, jobID, catalogIndex, pathID, qu
     query.box = '[not obtained]';
   }
   // Initialize an array of diagnoses.
-  let diagnoses = [];
-  const testActs = acts.filter(act => act.type === 'test');
-  // For each test act:
-  testActs.forEach(act => {
-    const {result, which} = act;
-    const caseInstances = result?.standardResult?.instances?.filter(
-      instance => instance.issueID === issueID && instance.catalogIndex === catalogIndex
-    ) ?? [];
-    // For each standard instance that pertains to this combination of issue and violator:
-    caseInstances.forEach(instance => {
-      const {ruleID, what} = instance;
-      // Add lines for it to the array.
-      diagnoses.push({
-        engineID: which,
-        ruleID,
-        what
-      });
+  const diagnoses: any[] = [];
+  // For each violating standard instance that pertains to this combination of issue and violator:
+  getTestActInstances(report, {violationsOnly: true, issueID, catalogIndex}).forEach(({act, instance}) => {
+    const {ruleID, what} = instance;
+    // Add lines for it to the array.
+    diagnoses.push({
+      engineID: act.which,
+      ruleID,
+      what
     });
   });
   // For each diagnosis:
@@ -118,9 +120,9 @@ const populateQuery = async (issueID, timeStamp, jobID, catalogIndex, pathID, qu
     const {engineID, ruleID, what} = diagnosis;
     // Add lines.
     lines.push(`${margin}<li>${htmlSafe(what)}`);
-    lines.push(
-      `${margin}  <p>Rule engine: ${ruleEngines[engineID][0]} (${ruleEngines[engineID][1]})</p>`
-    );
+    // engineID is act.which, guaranteed by isUsableReport to be a key in ruleEngines.
+    const [engineName, engineOrg] = ruleEngines[engineID]!;
+    lines.push(`${margin}  <p>Rule engine: ${engineName} (${engineOrg})</p>`);
     if (ruleID !== what) {
       lines.push(`${margin}  <p>Rule: <code>${ruleID}</code></p>`);
     }
@@ -130,19 +132,11 @@ const populateQuery = async (issueID, timeStamp, jobID, catalogIndex, pathID, qu
   query.diagnoses = lines.join('\n');
 };
 // Returns a page answering the diagnoses question.
-exports.answer = async (pageArgs, search) => {
-  const [issueID, timeStamp, jobID, catalogIndex] = pageArgs.split('/');
-  const reportIsHidden = await isHidden(timeStamp, jobID);
-  // If the report is not available:
-  if (reportIsHidden) {
-    return {
-      status: 'error',
-      message: 'Report not available'
-    };
-  }
+export const answer = async (pageArgs: string, search: string) => {
+  const [issueID, timeStamp, jobID, catalogIndex] = pageArgs.split('/') as [string, string, string, string];
   const params = new URLSearchParams(search);
   const pathID = params.get('pathID');
-  const query = {};
+  const query: Record<string, any> = {};
   // Create a query to replace the placeholders.
   await populateQuery(issueID, timeStamp, jobID, catalogIndex, pathID, query);
   // If this failed:
@@ -155,12 +149,8 @@ exports.answer = async (pageArgs, search) => {
   }
   // Otherwise, if it succeeded and the report facts were obtained:
   if (query.testInfo) {
-    // Get the template.
-    let answerPage = await fs.readFile(path.join(__dirname, 'index.html'), 'utf8');
-    // Replace its placeholders.
-    Object.keys(query).forEach(param => {
-      answerPage = answerPage.replace(new RegExp(`__${param}__`, 'g'), query[param]);
-    });
+    // Get the populated template.
+    const answerPage = await populateTemplate(import.meta.dirname, query);
     // Return the populated page.
     return {
       status: 'ok',

package/web/listDiagnoses/{listDiagnoses.test.js → listDiagnoses.test.ts}

@@ -1,46 +1,49 @@
 /*
-  listDiagnoses.test.js
-  UI tests for web/listDiagnoses/index.js using the fixture corpus.
+  listDiagnoses.test.ts
+  UI tests for web/listDiagnoses/index.ts using the fixture corpus.
 */
 
 // 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 {parse} = require('node-html-parser');
-
-// Monkey-patch util functions before requiring index, so that index.js
-// destructures the patched versions.
-const util = require('../../util');
-const realGetReport = util.getReport;
-const realGetPageDataStrings = util.getPageDataStrings;
+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';
+
+// Mock the util functions called by index.ts before requiring 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;
-let pageDataStringsOverride = null;
-util.getReport = async (...args) => {
-  getReportCallCount++;
-  if (getReportCallCount === failGetReportOnCall) {
-    return {error: 'Report is invalid (test override)'};
-  }
-  return realGetReport(...args);
-};
-util.getPageDataStrings = async (...args) => {
-  if (pageDataStringsOverride !== null) {
-    return pageDataStringsOverride;
+let pageDataStringsOverride: any = null;
+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);
+    },
+    getPageDataStrings: async (...args: any[]) => {
+      if (pageDataStringsOverride !== null) {
+        return pageDataStringsOverride;
+      }
+      return (realUtil.getPageDataStrings as any)(...args);
+    }
   }
-  return realGetPageDataStrings(...args);
-};
+} as any);
 
-const {answer} = require('./index');
+const {answer} = await import('./index.ts') as any;
 
 // SETUP AND TEARDOWN
 
 const savedDBDir = process.env.DB_DIR;
 
-before(() => {
-  process.env.DB_DIR = path.join(__dirname, '..', '..', 'test', 'fixtures', 'db');
+before(async () => {
+  process.env.DB_DIR = (await import('../../test/dbFixture.ts')).fixtureDBDir;
 });
 
 after(() => {
@@ -77,11 +80,13 @@ test('listDiagnoses includes diagnosis descriptions from the rule engines', asyn
   assert.ok(result.answerPage.includes('The link does not have an accessible name'));
 });
 
-test('listDiagnoses returns an error status for a hidden report', async () => {
-  const result = await answer('linkNoText/260101T0007/hid/0');
-  assert.equal(result.status, 'error');
+test('listDiagnoses excludes cantTell instances from the diagnoses list', async () => {
+  const result = await answer('focusIndicationBad/260101T0000/mix/0');
+  assert.equal(result.status, 'ok');
+  assert.ok(!result.answerPage.includes('Focus Visible'));
 });
 
+
 test('listDiagnoses returns an error status for a nonexistent report', async () => {
   const result = await answer('linkNoText/999999T9999/xyz/0');
   assert.equal(result.status, 'error');
@@ -111,7 +116,7 @@ test('listDiagnoses returns an error when getReport fails after getPageDataStrin
 });
 
 test('listDiagnoses includes a take-me-there link for a text-linkable catalog item', async () => {
-  const dbDir = path.join(__dirname, '..', '..', 'test', 'fixtures', 'db');
+  const dbDir = (await import('../../test/dbFixture.ts')).fixtureDBDir;
   const reportsDir = path.join(dbDir, 'reports');
   const reportPath = path.join(reportsDir, '260101T0003-tlk.json');
   try {
@@ -193,7 +198,7 @@ test('listDiagnoses returns an error when report facts are not obtained', async
 
 test('listDiagnoses handles acts with no standardResult instances gracefully', async () => {
   // Create a temporary report where an act has no standardResult.
-  const dbDir = path.join(__dirname, '..', '..', 'test', 'fixtures', 'db');
+  const dbDir = (await import('../../test/dbFixture.ts')).fixtureDBDir;
   const reportPath = path.join(dbDir, 'reports', '260101T0004-nst.json');
   const report = {
     id: '260101T0004-nst',

package/web/listIssues/{index.js → index.ts}

@@ -1,48 +1,42 @@
 /*
-  index.js
+  index.ts
   List the issues in a report.
 */
 
 // IMPORTS
 
-const {
+import {
   getPageData,
   getPageDataStrings,
   getReport,
-  getEngineList,
+  getEngineNamesString,
+  getTestActInstances,
   getWCAGLink,
   getWeightName,
   htmlSafe,
-  isHidden,
-  isValidReport,
+  isUsableReport,
   objectSort,
+  populateTemplate,
   ruleEngines
-} = require('../../util');
-const {issues: issueSpecs} = require('testaro-issues');
-const fs = require('fs/promises');
-const path = require('path');
+} from '../../util.ts';
+import {issues as issueSpecs} from 'testaro-issues';
 
 // FUNCTIONS
 
 // Returns data on the issues reported by a report.
-const getIssuesData = async (timeStamp, jobID) => {
+const getIssuesData = async (timeStamp: string, jobID: string) => {
   // Get the report.
   const report = await getReport(timeStamp, jobID);
-  const reportIsHidden = await isHidden(timeStamp, jobID);
-  // If it exists and is hidden:
-  if (reportIsHidden) {
-    return {error: 'Report is not available'}
-  }
-  // Otherwise, if it exists and is valid:
-  if (isValidReport(report)) {
+  // If it exists and is valid:
+  if (isUsableReport(report)) {
     // Initialize the temporary data.
     const temp = {
-      issues: {},
-      reporters: new Set(),
-      violators: new Set()
+      issues: {} as Record<string, any>,
+      reporters: new Set<string>(),
+      violators: new Set<string>()
     };
     // Initialize the final data.
-    const final = {
+    const final: Record<string, any> = {
       reporters: [],
       reporterList: '',
       reporterCount: 0,
@@ -56,60 +50,53 @@ const getIssuesData = async (timeStamp, jobID) => {
       },
       issueCount: 0
     };
-    // For each act in the report:
-    report.acts.forEach(act => {
-      // If it is a test act:
-      if (act.type === 'test') {
-        const {result, which} = act;
-        const instances = result?.standardResult?.instances ?? [];
-        // For each of its standard instances:
-        instances.forEach(instance => {
-          const {catalogIndex, issueID, outcome} = instance;
-          // If the instance reports a violation and identifies a non-ignorable issue:
-          if (outcome !== 'cantTell' && issueID && issueID !== 'ignorable') {
-            const issueClassification = issueSpecs[issueID];
-            // If the issue has a current weighted classification:
-            if (issueClassification && [1, 2, 3, 4].includes(issueClassification.weight)) {
-              const {summary, wcag, weight, why} = issueClassification;
-              // Initialize the temporary data on the issue if necessary.
-              temp.issues[issueID] ??= {
-                issueID,
-                summary,
-                wcag,
-                why,
-                weight,
-                reporters: new Set(),
-                reporterList: '',
-                violators: new Set()
-              };
-              // Ensure the rule engine is in the temporary data.
-              temp.issues[issueID].reporters.add(which);
-              temp.reporters.add(which);
-              // If the instance has a catalog index:
-              if (catalogIndex) {
-                // Ensure the violator is in the temporary data.
-                temp.issues[issueID].violators.add(catalogIndex);
-                temp.violators.add(catalogIndex);
-              }
-            }
+    // For each violating standard instance of each test act:
+    getTestActInstances(report, {violationsOnly: true}).forEach(({act, instance}) => {
+      const {catalogIndex, issueID} = instance;
+      const which = act.which!;
+      // If it identifies a non-ignorable issue:
+      if (issueID && issueID !== 'ignorable') {
+        const issueClassification = issueSpecs[issueID];
+        // If the issue has a current weighted classification:
+        if (issueClassification && [1, 2, 3, 4].includes(issueClassification.weight)) {
+          const {summary, wcag, weight, why} = issueClassification;
+          // Initialize the temporary data on the issue if necessary.
+          temp.issues[issueID] ??= {
+            issueID,
+            summary,
+            wcag,
+            why,
+            weight,
+            reporters: new Set(),
+            reporterList: '',
+            violators: new Set()
+          };
+          // Ensure the rule engine is in the temporary data.
+          temp.issues[issueID].reporters.add(which);
+          temp.reporters.add(which);
+          // If the instance has a catalog index:
+          if (catalogIndex) {
+            // Ensure the violator is in the temporary data.
+            temp.issues[issueID].violators.add(catalogIndex);
+            temp.violators.add(String(catalogIndex));
           }
-        });
+        }
       }
     });
     // Finish populating the final data.
-    final.reporterList = getEngineList(temp.reporters);
+    final.reporterList = getEngineNamesString(temp.reporters);
     final.reporterCount = temp.reporters.size;
     final.violatorCount = temp.violators.size;
     Object.values(temp.issues).forEach(issue => {
       const {issueID, summary, wcag, why, weight} = issue;
-      const finalIssue = {
+      const finalIssue: Record<string, any> = {
         issueID,
         summary,
         wcag,
         why,
         weight
       };
-      finalIssue.reporterList = getEngineList(issue.reporters);
+      finalIssue.reporterList = getEngineNamesString(issue.reporters);
       finalIssue.reporterCount = issue.reporters.size;
       finalIssue.violatorCount = issue.violators.size;
       final.issues[issue.weight].push(finalIssue);
@@ -129,10 +116,10 @@ const getIssuesData = async (timeStamp, jobID) => {
   return {error: 'Report missing or invalid.'};
 };
 // Get page and issues data from a report.
-const getData = async (timeStamp, jobID) => {
+const getData = async (timeStamp: string, jobID: string) => {
   const pageData = await getPageData(timeStamp, jobID);
-  const issuesData = await getIssuesData(timeStamp, jobID);
-  const pageError = pageData.error || '';
+  const issuesData: any = await getIssuesData(timeStamp, jobID);
+  const pageError = ('error' in pageData ? pageData.error : '');
   const issuesError = issuesData.error || '';
   const errors = [pageError, issuesError].filter(Boolean).join('; ');
   // If the data of either type are missing or invalid:
@@ -147,9 +134,9 @@ const getData = async (timeStamp, jobID) => {
   };
 };
 // Adds parameters to a query for the answer page.
-const populateQuery = async (timeStamp, jobID, query) => {
+const populateQuery = async (timeStamp: string, jobID: string, query: Record<string, any>) => {
   // Get data on the target and its issues according to the report.
-  const data = await getData(timeStamp, jobID);
+  const data: any = await getData(timeStamp, jobID);
   const {pageData, issuesData} = data;
   // If this failed:
   if (data.error) {
@@ -160,16 +147,16 @@ const populateQuery = async (timeStamp, jobID, query) => {
   }
   // Otherwise, i.e. if it succeeded, get fact descriptions for the target.
   const pageInfo = await getPageDataStrings(timeStamp, jobID, pageData);
-  const {testInfo, urlLink, what} = pageInfo;
   // If this failed:
-  if (pageInfo.error) {
+  if (pageInfo.error !== undefined) {
     // Populate the query with the reason.
     query.error = pageInfo.error;
     // Stop populating the query.
     return;
   }
+  const {testInfo, urlLink, description} = pageInfo;
   // Otherwise, i.e. if it succeeded, add target data to the query.
-  query.target = what;
+  query.target = description;
   query.urlLink = urlLink;
   query.testInfo = testInfo;
   const {
@@ -181,11 +168,11 @@ const populateQuery = async (timeStamp, jobID, query) => {
     issues
   } = issuesData;
   // Initialize strings for the prevention notices query property.
-  const preventionStrings = [];
+  const preventionStrings: string[] = [];
   const margin = ' '.repeat(6);
   Object.keys(preventions).forEach(preventedEngineID => {
-    const engineName = ruleEngines[preventedEngineID];
-    const engineNameString = `${engineName[0]} (${engineName[1]})`;
+    const [engineName, engineSponsor] = ruleEngines[preventedEngineID] ?? [preventedEngineID, 'unknown sponsor'];
+    const engineNameString = `${engineName} (${engineSponsor})`;
     const causeString = htmlSafe(preventions[preventedEngineID]);
     const preventionString = `${margin}<li>Page not testable by ${engineNameString}: ${causeString}</li>`;
     preventionStrings.push(preventionString);
@@ -213,9 +200,9 @@ const populateQuery = async (timeStamp, jobID, query) => {
     // If any reported issues have the weight:
     if (weightIssues.length) {
       // Initialize lines for the weight details query property.
-      const detailsLines = [];
+      const detailsLines: string[] = [];
       // For each issue with the weight:
-      weightIssues.forEach(issueData => {
+      weightIssues.forEach((issueData: any) => {
         const weightIssueCount = weightIssues.length;
         // Add the issue count to the query.
         query[`${weightName}Count`] = weightIssueCount;
@@ -251,7 +238,7 @@ const populateQuery = async (timeStamp, jobID, query) => {
         // Add the start of a link list to the lines.
         detailsLines.push(`${margin}    <ul class="nav">`);
         const whereQuestionString = 'Where was the issue found?';
-        const labelString = `Where was the ${summary} issue found on the ${what} page?`;
+        const labelString = `Where was the ${summary} issue found on the ${description} page?`;
         const href = `href="/listViolators.html/${issueID}/${timeStamp}/${jobID}"`;
         const label = `aria-label="${labelString}"`;
         const whereLink = `<a ${href} ${label}>${whereQuestionString}</a>`;
@@ -272,17 +259,9 @@ const populateQuery = async (timeStamp, jobID, query) => {
   });
 };
 // Returns a page answering the target-issues question.
-exports.answer = async pageArgs => {
-  const [timeStamp, jobID] = pageArgs.split('/');
-  const reportIsHidden = await isHidden(timeStamp, jobID);
-  // If the report is not available:
-  if (reportIsHidden) {
-    return {
-      status: 'error',
-      message: 'Report not available'
-    };
-  }
-  const query = {};
+export const answer = async (pageArgs: string) => {
+  const [timeStamp, jobID] = pageArgs.split('/') as [string, string];
+  const query: Record<string, any> = {};
   // Create a query to replace the placeholders.
   await populateQuery(timeStamp, jobID, query);
   // If this failed:
@@ -295,12 +274,8 @@ exports.answer = async pageArgs => {
   }
   // Otherwise, if it succeeded and the report facts were obtained:
   if (query.testInfo) {
-    // Get the template.
-    let answerPage = await fs.readFile(path.join(__dirname, 'index.html'), 'utf8');
-    // Replace its placeholders.
-    Object.keys(query).forEach(param => {
-      answerPage = answerPage.replace(new RegExp(`__${param}__`, 'g'), query[param]);
-    });
+    // Get the populated template.
+    const answerPage = await populateTemplate(import.meta.dirname, query);
     // Return the populated page.
     return {
       status: 'ok',