@jrpool/kilotest 58.2.4 → 59.0.2

package/web/util.ts

@@ -12,8 +12,7 @@ import {
   alphaCompare,
   getAgoDays,
   getDateString,
-  getDateTime,
-  getReportExtracts,
+  getReportEndTime,
   getTestActInstances,
   getTestActs,
   htmlSafe,
@@ -21,7 +20,7 @@ import {
 } from '../util.ts';
 import {issues as issueSpecs} from 'testaro-issues';
 import type {Catalog} from 'testaro';
-import type {ReportExtract, UsableReport} from '../util.ts';
+import type {UsableReport} from '../util.ts';
 /* c8 ignore stop */
 import wcagMap from '../wcagMap.json' with {type: 'json'};
 
@@ -40,6 +39,7 @@ export type PageDataStrings = {
   url: string;
   urlLink: string;
   testInfo: string;
+  fullReportLink: string;
   error?: never;
 };
 // Counts summarizing the results of an available report.
@@ -56,8 +56,6 @@ export type ReportData = {
   description: string;
   url: string;
   jobName: unknown;
-  creationDate: Date | null;
-  daysAgo: number | null;
   issueCount: number;
   engineNames: string[];
   engineCount: number;
@@ -95,9 +93,9 @@ export const checkCommentLength = (
 const fragmentEncode = (string: string) => {
   return encodeURIComponent(string).replace(/-/g, '%2D');
 };
-// Returns a string describing the time in days since a time stamp.
-export const getAgoString = (timeStamp: string): string => {
-  const agoDays = getAgoDays(timeStamp);
+// Returns a string describing the time in days since a time stamp or date.
+export const getAgoString = (timeArg: string | Date): string => {
+  const agoDays = getAgoDays(timeArg);
   if (agoDays === null) {
     return 'an unknown number of days';
   }
@@ -111,8 +109,20 @@ const getTimeString = (timeStamp: string) => {
   // Return the time string if valid, or null if not.
   return (!isNaN(Date.parse(`2000-01-01T${timeString}Z`))) ? timeString : null;
 };
-// Returns a date-and-time string.
-export const getDateTimeString = (timeStamp: string): string => {
+// Returns a date-and-time string from a time stamp or date.
+export const getDateTimeString = (timeArg: string | Date): string => {
+  let timeStamp: string;
+  // If the argument is a date:
+  if (timeArg instanceof Date) {
+    // Convert it to a time stamp, or to an invalid one if the date is invalid.
+    timeStamp = isNaN(timeArg.getTime())
+      ? ''
+      : timeArg.toISOString().slice(2, 16).replace(/[-:]/g, '');
+  }
+  // Otherwise, i.e. if it is a time stamp:
+  else {
+    timeStamp = timeArg;
+  }
   const dateString = getDateString(timeStamp) || 'an unknown date';
   const timeString = getTimeString(timeStamp) || 'an unknown time';
   const dateTimeString = `${dateString} at ${timeString}`;
@@ -178,15 +188,11 @@ export const getEngineIDs = (report: any) => {
 };
 // Returns basics about an available report.
 export const getReportData = (report: UsableReport): ReportData => {
-  // Identify the report by the time stamp at the start of its job name.
-  const timeStamp = report.id.slice(0, 11);
   // Initialize the data.
   const data = {
     description: report.target.what,
     url: report.target.url,
     jobName: report.id,
-    creationDate: getDateTime(timeStamp),
-    daysAgo: getAgoDays(timeStamp),
     issueCount: 0,
     engineNames: [] as string[],
     engineCount: 0,
@@ -245,9 +251,8 @@ export const getReportData = (report: UsableReport): ReportData => {
 // Returns page data from an available report.
 export const getPageData = (report: UsableReport): PageData => {
   const {what: description, url} = report.target;
-  // Get the elapsed time in days since the report was completed, using the
-  // report content rather than the file system birth time.
-  const daysAgo = getAgoDays(new Date(`20${report.jobData.endTime}Z`));
+  // Get the elapsed time in days since the report was completed.
+  const daysAgo = getAgoDays(getReportEndTime(report));
   // Return the data.
   return {
     description,
@@ -258,14 +263,15 @@ export const getPageData = (report: UsableReport): PageData => {
 // Gets HTML strings for page data from a report.
 export const getPageDataStrings = (report: UsableReport): PageDataStrings => {
   const {daysAgo, url, description} = getPageData(report);
-  // Get a description of the time stamp at the start of the job name.
-  const when = getDateTimeString(report.id.slice(0, 11));
+  // Get a description of the completion time of the report.
+  const when = getDateTimeString(getReportEndTime(report));
   // Return the HTML strings.
   return {
     description,
     url,
     urlLink: `<a href="${url}">${url}</a>`,
-    testInfo: `Tested ${daysAgo === 1 ? '1 day' : `${daysAgo} days`} ago on ${when} by job <code>${report.id}</code>`
+    testInfo: `Tested ${daysAgo === 1 ? '1 day' : `${daysAgo} days`} ago on ${when} by job <code>${report.id}</code>`,
+    fullReportLink: `<a href="/fullReport.json/${report.id.replace('-', '/')}">Download the full technical report</a> (JSON)`
   };
 };
 // Returns the lines of a list of facts about the page of an available report.
@@ -291,6 +297,7 @@ export const getPageFactsLines = (
   `${margin}      <li>Issues: ${summary.issueCount}</li>`,
   `${margin}    </ul>`,
   `${margin}  </li>`,
+  `${margin}  <li>${strings.fullReportLink}</li>`,
   `${margin}</ul>`
 ];
 // Returns the lines of a list of facts about an issue in an available report.
@@ -372,14 +379,3 @@ export const getViolatorFactsLines = (
   lines.push(`${margin}</ul>`);
   return lines;
 };
-// Gets the descriptions of multi-report pages, from extracts already obtained, if provided.
-export const getMultiReportWhats = async (
-  reportExtracts?: ReportExtract[]
-): Promise<string[]> => {
-  reportExtracts ??= await getReportExtracts();
-  const sortedDescriptions = reportExtracts.map(extract => extract.description).sort();
-  const multiReportDescriptions = sortedDescriptions.filter(
-    (description, index) => description !== sortedDescriptions[index - 1] && description === sortedDescriptions[index + 1]
-  );
-  return multiReportDescriptions;
-};

package/api/listReports.test.ts

@@ -1,109 +0,0 @@
-/*
-  listReports.test.ts
-  Tests for api/listReports.ts using the fixture corpus.
-*/
-
-// IMPORTS
-
-import {test, before, after} from 'node:test';
-import assert from 'node:assert/strict';
-import {response} from './listReports.ts';
-
-// CONSTANTS
-
-// Fixture report identifiers in the reports/ directory (excluding the hidden one).
-const fixtureIds = [
-  ['260101T0000', 'mix'],
-  ['260101T0001', 'ct'],
-  ['260101T0002', 'no'],
-  ['260101T0005', 'emp'],
-  ['260101T0006', 'prv'],
-  ['260101T0008', 'mul'],
-  ['260101T0009', 'brd'],
-  ['260202T0000', 'new']
-];
-
-// SETUP AND TEARDOWN
-
-const savedDBDir = process.env.DB_DIR;
-
-before(async () => {
-  process.env.DB_DIR = (await import('../test/dbFixture.ts')).fixtureDBDir;
-});
-
-after(() => {
-  if (savedDBDir !== undefined) {
-    process.env.DB_DIR = savedDBDir;
-  }
-  else {
-    delete process.env.DB_DIR;
-  }
-});
-
-// TESTS
-
-test('listReports returns basics about all 8 non-hidden reports', async () => {
-  const body = await response();
-  const reportsBasics = body['response content']['basics about all available reports'];
-  assert.equal(reportsBasics.length, 8);
-  const ids = reportsBasics.map((b: any) => b.identifier).sort();
-  const expectedIds = fixtureIds.map(([ts, jid]) => `${ts}-${jid}`).sort();
-  assert.deepEqual(ids, expectedIds);
-});
-
-test('listReports does not include the hidden report', async () => {
-  const body = await response();
-  const reportsBasics = body['response content']['basics about all available reports'];
-  const ids = reportsBasics.map((b: any) => b.identifier);
-  assert.ok(!ids.includes('260101T0007-hid'), 'hidden report must not appear in listReports');
-});
-
-test('listReports sorts reports by page description and then by completion time', async () => {
-  const body = await response();
-  const reportsBasics = body['response content']['basics about all available reports'];
-  const descriptions = reportsBasics.map((b: any) => b['tested web page'].description);
-  // All CantTell Page, Empty Results Page, Mixed Outcomes Page, Mixed Outcomes Page, No Outcomes Page, Prevented Page.
-  assert.deepEqual(
-    descriptions,
-    [
-      'All CantTell Page',
-      'Branch Coverage Page',
-      'Empty Results Page',
-      'Mixed Outcomes Page',
-      'Mixed Outcomes Page',
-      'Multi Violator Page',
-      'No Outcomes Page',
-      'Prevented Page'
-    ]
-  );
-  // The two Mixed Outcomes Page reports should be sorted by completion time (older first).
-  const mixedReports = reportsBasics.filter((b: any) => b['tested web page'].description === 'Mixed Outcomes Page');
-  assert.equal(mixedReports[0]!.identifier, '260101T0000-mix');
-  assert.equal(mixedReports[1]!.identifier, '260202T0000-new');
-});
-
-test('listReports marks the superseded report correctly', async () => {
-  const body = await response();
-  const reportsBasics = body['response content']['basics about all available reports'];
-  const mix = reportsBasics.find((b: any) => b.identifier === '260101T0000-mix');
-  const newer = reportsBasics.find((b: any) => b.identifier === '260202T0000-new');
-  assert.ok(mix);
-  assert.ok(newer);
-  assert.equal(mix['whether a later report about the same page exists'], true);
-  assert.equal(newer['whether a later report about the same page exists'], false);
-});
-
-test('listReports includes request-test instructions', async () => {
-  const body = await response();
-  const content = body['response content'];
-  assert.ok(content['how to request that a page with no report be tested']);
-  assert.ok(content['how a web user can request that the page be tested']);
-  assert.equal(content['how to request that a page with no report be tested'].method, 'POST');
-});
-
-test('listReports includes tool name and metadata', async () => {
-  const body = await response();
-  assert.equal(body['tool name'], 'listReports');
-  assert.ok(body['response metadata'].identifier);
-  assert.ok(body['response metadata']['date and time']);
-});

package/api/listReports.ts

@@ -1,87 +0,0 @@
-/*
-  listReports.ts
-  Returns basics about all the available reports.
-*/
-
-// IMPORTS
-
-import {z} from 'zod';
-import {getReportBasics, getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
-import {getReportExtracts} from '../util.ts';
-import {listReportsResponseSchema} from './schemas.ts';
-
-// TYPES
-
-// The response content defined by the response schema.
-type ResponseContent = z.infer<typeof listReportsResponseSchema>['response content'];
-
-// FUNCTIONS
-
-// Returns the response body.
-export const response = async () => {
-  const thisHost = getThisHost();
-  // Initialize an array of basics about the reports.
-  const reportsBasics: ResponseContent['basics about all available reports'] = [];
-  // Get extracts of all available reports.
-  const reportExtracts = await getReportExtracts();
-  // For each report:
-  for (const extract of reportExtracts) {
-    const {jobID, timeStamp} = extract;
-    // Get the basics about it.
-    const reportBasics = await getReportBasics(timeStamp, jobID, extract);
-    // Add the basics, with instructions for getting details, to the array.
-    reportsBasics.push({
-      ...reportBasics,
-      'how to get details about the report': {
-        method: 'GET',
-        URL: `${thisHost}/api/listIssues/${timeStamp}/${jobID}`
-      },
-      'web users can get details about the report at': `${thisHost}/listIssues.html/${timeStamp}/${jobID}`
-    });
-  }
-  // Sort the array by page description and secondarily by completion recency.
-  reportsBasics.sort((a, b) => {
-    if (a['tested web page'].description !== b['tested web page'].description) {
-      return a['tested web page']
-      .description
-      .localeCompare(b['tested web page'].description, 'en', {sensitivity: 'base'});
-    }
-    return a['completion date and time'].localeCompare(b['completion date and time']);
-  });
-  // Create the response content.
-  const responseContent: ResponseContent = {
-    'basics about all available reports': reportsBasics,
-    'how to request that a page with no report be tested': {
-      method: 'POST',
-      URL: `${thisHost}/api/requestNewTest`,
-      'request body': {
-        description: '10- to 100-character description of the page conforming to the naming convention used in this list of reports',
-        URL: '12- to 300-character URL of the page, including the https:// scheme and any query',
-        reason: '20- to 100-character reason why the page should be tested'
-      },
-      'how to check whether the request has been fulfilled': 'use this listReports tool to determine whether a report about the page has become available (typical wait time: 1 hour to 1 day)'
-    },
-    'how a web user can request that the page be tested': {
-      URL: `${thisHost}/requestNewTestForm.html`
-    }
-  };
-  // Create a response body.
-  const body = {
-    'tool collection': getToolsFacts(),
-    'tool name': 'listReports',
-    'this request': {
-      description: 'Provide basics about all available reports.',
-      method: 'GET',
-      URL: `${thisHost}/api/listReports`,
-      'closest ancestor request': null
-    },
-    'URLs of similar requests for web users': {
-      'this request': `${thisHost}/listReports.html`,
-      'closest ancestor request': null
-    },
-    'response metadata': getResponseMetadata(),
-    'response content': responseContent
-  };
-  // Return it.
-  return body;
-};

package/web/listReports/index.ts

@@ -1,182 +0,0 @@
-/*
-  index.ts
-  Lists all available reports.
-*/
-
-// IMPORTS
-
-import {
-  getJobNames,
-  getObject,
-  getReport,
-  getReportExtracts,
-  getTestRequests,
-  isReportError,
-  jobsPath,
-  objectSort,
-  populateTemplate
-} from '../../util.ts';
-import {
-  getMultiReportWhats,
-  getPageDataStrings,
-  getPageFactsLines,
-  getReportData
-} from '../util.ts';
-import path from 'node:path';
-
-// FUNCTIONS
-
-// Adds parameters to a query for the answer page.
-const populateQuery = async (query: Record<string, any>) => {
-  const margin = ' '.repeat(8);
-  // Initialize the classes of lines.
-  const lines: {requests: string[], queue: string[], claimed: string[], tested: string[]} = {
-    requests: [],
-    queue: [],
-    claimed: [],
-    tested: []
-  };
-  // Get the test requests.
-  const testRequests = await getTestRequests();
-  // For each requested URL:
-  Object.keys(testRequests).forEach(url => {
-    // For each of its requests:
-    testRequests[url]!.forEach((req: any) => {
-      const {description, reason} = req;
-      // Add a line.
-      lines.requests.push(`${margin}<li><code>${url}</code> (${description}): ${reason}</li>`);
-    });
-  });
-  // Sort the lines in alphabetical order by URL and secondarily by proposed name.
-  lines.requests.sort();
-  // Add the lines to the query.
-  query.requests = lines.requests.join('\n');
-  // Add a no-requests message, if applicable, to the query.
-  query.noRequests = lines.requests.length
-  ? 'Kilotest managers can <a href="enqueueForm.html">approve or reject a request</a>.'
-  : 'No requests await approval now.';
-  // Get the file names of all queued and claimed jobs.
-  const jobFileNames = await getJobNames();
-  // Initialize sets of the page descriptions and URLs of jobs in both categories.
-  const jobsData = {
-    queue: {
-      descriptions: new Set(),
-      urls: new Set()
-    },
-    claimed: {
-      descriptions: new Set(),
-      urls: new Set()
-    }
-  };
-  // For each job category:
-  for (const category of ['queue', 'claimed'] as const) {
-    // For each job in the category:
-    for (const fileName of jobFileNames[category]) {
-      // Get the job.
-      const job = await getObject(path.join(jobsPath(), category, fileName)) as {target: {url: string, what: string}};
-      // Get the description and URL of its page.
-      const {target} = job;
-      const {what, url} = target;
-      // Ensure they are in the sets of properties of the category.
-      jobsData[category].descriptions.add(what);
-      jobsData[category].urls.add(url);
-      // Add a line.
-      lines[category].push(`${margin}<li><code>${job.target.url}</code> (${job.target.what})</li>`);
-    }
-    // Add the lines to the query.
-    query[category] = lines[category].join('\n');
-  }
-  // Add a no-queued message, if applicable, to the query.
-  query.noQueued = lines.queue.length ? '' : 'No pages are queued for testing.';
-  // Add a no-claimed message, if applicable, to the query.
-  query.noClaimed = lines.claimed.length ? '' : 'No pages are being tested now.';
-  // Get extracts of all available reports.
-  const reportExtracts = await getReportExtracts();
-  const reportCount = reportExtracts.length;
-  query.which = reportCount ? 'the following' : 'no';
-  query.some = (reportCount || jobFileNames.queue.length || jobFileNames.claimed.length)
-  ? 'another'
-  : 'a';
-  const multiReportWhats = await getMultiReportWhats(reportExtracts);
-  // Sort them primarily by page description and secondarily by completion time.
-  let sortedExtracts = objectSort(reportExtracts, 'reportTime', 'alpha');
-  sortedExtracts = objectSort(sortedExtracts, 'description', 'alpha');
-  // For each report:
-  for (const extract of sortedExtracts) {
-    const {jobID, timeStamp, url, description, superseded} = extract;
-    // Get the report.
-    const report = await getReport(timeStamp, jobID);
-    // If this failed:
-    if (isReportError(report)) {
-      console.error(report.error);
-      // Populate the query with the reason.
-      query.error = report.error;
-      // Stop populating the query.
-      return;
-    }
-    // Otherwise, i.e. if it succeeded, get data about the report.
-    const reportData = getReportData(report);
-    const pageDataStrings = getPageDataStrings(report);
-    const {issueCount} = reportData;
-    const {testInfo} = pageDataStrings;
-    // Add lines about the report.
-    lines.tested.push(`${margin}<details>`);
-    const testText = multiReportWhats.includes(description) ? ` (${testInfo.toLowerCase()})` : '';
-    lines.tested.push(`${margin}  <summary>${description}${testText}</summary>`);
-    // Add the page facts to the lines.
-    lines.tested.push(...getPageFactsLines(pageDataStrings, reportData, `${margin}  `));
-    lines.tested.push(`${margin}  <ul class="nav">`);
-    // If any issues were reported:
-    if (issueCount) {
-      // Add a link to issue details to the lines.
-      const href = `href="listIssues.html/${timeStamp}/${jobID}"`;
-      const label = `aria-label="issue details for the ${description} page"`;
-      const link = `<a ${href} ${label}>Issue details</a>`;
-      lines.tested.push(`${margin}    <li>${link}</li>`);
-    }
-    let retestString: string = '';
-    // If a page with the same description or URL is being tested:
-    if (jobsData.claimed.descriptions.has(description) || jobsData.claimed.urls.has(url)) {
-      // Report this.
-      retestString = 'Currently being retested';
-    }
-    // Otherwise, if such a page is queued:
-    else if (jobsData.queue.descriptions.has(description) || jobsData.queue.urls.has(url)) {
-      retestString = 'Currently in the queue for retesting';
-    }
-    // Otherwise, if no such page is being tested or queued and the report is not superseded:
-    else if (!superseded) {
-      // Make the page available for retesting.
-      const href = `/requestRetestForm.html/${timeStamp}/${jobID}`;
-      const retestContent = 'Should Kilotest retest the page?';
-      retestString = `<a href="${href}">${retestContent}</a>`;
-    }
-    if (retestString) {
-      lines.tested.push(`${margin}    <li>${retestString}</li>`);
-    }
-    lines.tested.push(`${margin}  </ul>`);
-    lines.tested.push(`${margin}</details>`);
-  }
-  query.testedPages = lines.tested.join('\n');
-};
-// Returns a page answering the targets question.
-export const answer = async () => {
-  const query: Record<string, any> = {};
-  // Create a query to replace placeholders.
-  await populateQuery(query);
-  // If the query reports an error:
-  if (query.error) {
-    // Return it.
-    return {
-      status: 'error',
-      message: query.error
-    };
-  }
-  // Otherwise, i.e. if it does not report an error, get the template.
-  const answerPage = await populateTemplate(import.meta.dirname, query);
-  // Return the populated page.
-  return {
-    status: 'ok',
-    answerPage
-  };
-};