@jrpool/kilotest 38.1.0 → 39.0.1

package/api/listViolators.js

@@ -0,0 +1,164 @@
+/*
+  listViolators.js
+  Returns details about one issue in one report and basics about all the violators of the issue.
+*/
+
+// IMPORTS
+
+const {
+  getIssueClassification,
+  getReportBasics,
+  getResponseMetadata,
+  getRuleEnginesFacts,
+  getToolsFacts,
+  thisHost
+} = require('./util');
+const {getReport} = require('../util');
+
+// FUNCTIONS
+
+// Returns the response body.
+exports.response = async args => {
+  const [issueID = '', timeStamp = '', jobID = ''] = args;
+  // Initialize the response content.
+  const responseContent = {
+    'basics about the report': null,
+    'basics about the issue': null,
+    'details about the issue': null,
+    'basics about all elements exhibiting the issue': null
+  };
+  // Get the report.
+  const report = await getReport(timeStamp, jobID);
+  // If this failed:
+  if (report.error) {
+    // Add this to the response content.
+    responseContent['basics about the report'] = report;
+  }
+  // Otherwise, i.e. if it succeeded:
+  else {
+    // Get the basics about the report (which may be only an error message).
+    const reportBasics = await getReportBasics(timeStamp, jobID);
+    // Add them to the response content.
+    responseContent['basics about the report'] = reportBasics;
+  }
+  // Get the classification of the issue.
+  const issueClassification = issueID ? getIssueClassification(issueID) : null;
+  // If the issue is ignorable or not fully classified:
+  if (!issueClassification) {
+    // Add this to the response content.
+    responseContent['basics about the issue'] = {
+      'error': 'No information about the specified issue is available'
+    };
+  }
+  // Otherwise, i.e. if it is non-ignorable and fully classified:
+  else {
+    const {summary, wcag, weight, why} = issueClassification;
+    // Initialize the basics and details about it.
+    const issueBasics = {
+      'identifier': issueID,
+      summary,
+      'impact on a user': why,
+      'related WCAG standard': {
+        'layer': (wcag.length > 4 ? 'success criterion' : 'guideline'),
+        'identifier': wcag
+      },
+      priority: ['lowest', 'low', 'high', 'highest'][weight - 1]
+    };
+    // Add the basics about the issue to the response content.
+    responseContent['basics about the issue'] = issueBasics;
+    // If the report is available:
+    if (!report.error) {
+      // Initialize data about the instances of the issue.
+      const reporterIDs = new Set();
+      const violators = {};
+      // For each act in the report:
+      report.acts.forEach(act => {
+        const {result, type, which} = act;
+        const instances = result?.standardResult?.instances || [];
+        // If the act is a test act with a specified rule engine:
+        if (type === 'test' && which) {
+          // For each standard instance of the act:
+          instances.forEach(instance => {
+            // If the instance has the issue ID:
+            if (instance.issueID === issueID) {
+              const {catalogIndex} = instance;
+              // Ensure the rule-engine ID is in the reporters data.
+              reporterIDs.add(which);
+              // If the instance has a catalog index:
+              if (catalogIndex) {
+                // Ensure the catalog index is in the violators data.
+                violators[catalogIndex] ??= {
+                  catalogIndex,
+                  reporters: new Set()
+                };
+                // Ensure the reporter ID is in the violator data.
+                violators[catalogIndex].reporters.add(which);
+              }
+            }
+          });
+        }
+      });
+      // Get details about the reporters of the issue.
+      const reportersFacts = getRuleEnginesFacts(reporterIDs);
+      // Add them to the facts about the issue.
+      const issueDetails = {
+        'rule engines reporting violations belonging to the issue': reportersFacts
+      };
+      // Add the details about the issue to the response content.
+      responseContent['details about the issue'] = issueDetails;
+      const {catalog} = report;
+      // Get a sorted array of data about the violators.
+      const sortedViolatorData = Object.values(violators).sort(
+        (a, b) => {
+          if (b.reporters.size === a.reporters.size) {
+            return Number(a.catalogIndex) - Number(b.catalogIndex);
+          }
+          return b.reporters.size - a.reporters.size;
+        }
+      );
+      // Get basics about the violators.
+      const violatorsBasics = sortedViolatorData
+      .map(violator => {
+        const {catalogIndex, reporters} = violator;
+        const catalogItem = catalog[catalogIndex];
+        return {
+          identifier: catalogIndex,
+          'tag name': catalogItem?.tagName || null,
+          '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}/${timeStamp}/${jobID}`,
+            'request method': 'GET'
+          },
+          'web users can get details about the element at': `${thisHost}/diagnoses.html/${issueID}/${timeStamp}/${jobID}/${catalogIndex}`
+        };
+      });
+      // Add basics about the violators to the response content.
+      responseContent['basics about all elements exhibiting the issue'] = violatorsBasics;
+    }
+  }
+  // Create a response body.
+  const body = {
+    'tool collection': getToolsFacts(),
+    'tool name': 'listViolators',
+    'this request': {
+      description: 'Provide details about one issue in one report, including basics about the elements of the tested page that exhibited the issue. The issueID, timeStamp, and jobID parameters identify the issue and report that I want details about. Those parameters were in the response to my earlier listIssues request.',
+      method: 'GET',
+      URL: `${thisHost}/api/listViolators/${issueID}/${timeStamp}/${jobID}`,
+      'closest ancestor request': {
+        'tool name': 'listIssues',
+        description: 'Provide details about one report, including basics about the issues reported in it.',
+        method: 'GET',
+        URL: `${thisHost}/api/listIssues/${timeStamp}/${jobID}`
+      }
+    },
+    'URLs of similar requests for web users': {
+      'this request': `${thisHost}/reportIssue.html/${issueID}/${timeStamp}/${jobID}`,
+      'closest ancestor request': `${thisHost}/reportIssues.html/${timeStamp}/${jobID}`
+    },
+    'response metadata': getResponseMetadata(),
+    'response content': responseContent
+  }
+  // Return it.
+  return body;
+};

package/api/requestFeature.js

@@ -0,0 +1,56 @@
+/*
+  requestFeature.js
+  Processes a request to add or improve a feature and returns an acknowledgement.
+*/
+
+// IMPORTS
+
+const {getResponseMetadata, getToolsFacts, thisHost} = require('./util');
+const {sendAlert} = require('../alerts');
+
+// FUNCTIONS
+
+// Returns the response body.
+exports.response = async args => {
+  const [request = ''] = args;
+  // Initialize the response content.
+  const responseContent = {
+    'details about your request': null
+  };
+  // If the request is empty:
+  if (!request) {
+    // Add this to the response content.
+    responseContent['details about your request'] = {
+      error: 'request invalid: request is empty'
+    };
+  }
+  // Otherwise, i.e. if it exists:
+  else {
+    // Notify the manager.
+    await sendAlert('MCP feature request received', request);
+    // Add the disposition to the response content.
+    responseContent['details about your request'] = {
+      'date and time received': new Date().toISOString(),
+      disposition: 'received and logged; manager notified'
+    };
+  }
+  // Create a response body.
+  const body = {
+    'tool collection': getToolsFacts(),
+    'tool name': 'requestFeature',
+    'this request': {
+      description: 'Process my request to add or improve a feature.',
+      method: 'POST',
+      URL: `${thisHost}/api/requestFeature`,
+      body: {
+        request
+      },
+      'closest ancestor request': null
+    },
+    'URLs of similar requests for web users': null,
+    'response metadata': getResponseMetadata(),
+    'response content': responseContent
+  };
+  // Return it.
+  return body;
+};

package/api/requestRetest.js

@@ -0,0 +1,102 @@
+/*
+  requestRetest.js
+  Processes a request to retest a page and returns an acknowledgement.
+*/
+
+// IMPORTS
+
+const {getResponseMetadata, getToolsFacts, processTestRequest, thisHost} = require('./util');
+const {getReportsExtract} = require('../util');
+
+// FUNCTIONS
+
+// Returns the response body.
+exports.response = async args => {
+  const [timeStamp = '', jobID = '', reason = ''] = args;
+  // Initialize the response content.
+  const responseContent = {
+    'details about your request': {},
+    'disposition of your request': null
+  };
+  const reasonLength = reason.length;
+  // Get data on the available reports.
+  const reportsExtract = await getReportsExtract();
+  // Get data on the report.
+  const reportExtract = Object
+  .values(reportsExtract)
+  .find(extract => extract.timeStamp === timeStamp && extract.jobID === jobID);
+  const {what, url} = reportExtract || {};
+  // If this failed:
+  if (!reportExtract) {
+    // Add this to the response content.
+    responseContent['details about your request'] = {
+      error: 'request invalid: the specified existing report is not an available report'
+    };
+  }
+  // Otherwise, if the report has been superseded:
+  else if (
+    Object
+    .values(reportsExtract)
+    .filter(extract => extract.what === what && extract.url === url)
+    .length > 1
+  ) {
+    // Add this to the response content.
+    responseContent['details about your request'] = {
+      error: 'request invalid: a later report about the page exists'
+    };
+  }
+  // Otherwise, if the encoded reason is too short or too long:
+  else if (reasonLength < 20 || reasonLength > 100) {
+    // Add this to the response content.
+    responseContent['details about your request'] = {
+      error: 'request invalid: your reason is not between 20 and 100 characters long'
+    }
+  }
+  // Otherwise, i.e. if getting the report succeeded and the request is valid:
+  else {
+    // Process the request.
+    await processTestRequest('retest', what, url, reason);
+    // Add details about the request to the response content.
+    responseContent['details about your request'] = {
+      'date and time received': new Date().toISOString(),
+      'page to be retested': {
+        'description': what,
+        'URL': url
+      },
+      'reason why the page should be retested': reason
+    };
+    // Add information about the disposition of the request to the response content.
+    responseContent['disposition of your request'] = {
+      'what happens next': 'Your request is likely to be approved and processed within 1 hour to 1 day.',
+      'how you can check for completion': 'You can call the listReports tool to learn whether the page has been retested and a new report is available.',
+      'how a web user can check for completion': `A web user can visit ${thisHost}/targets.html to learn whether the page has been retested and a new report is available.`
+    };
+  }
+  // Create a response body.
+  const body = {
+    'tool collection': getToolsFacts(),
+    'tool name': 'requestRetest',
+    'this request': {
+      description: 'Process my request to retest a page. The timeStamp and jobID parameters identify the latest available report about the page. Those parameters were in the response to my earlier listIssues request. The reason property of the request body is the reason why the page should be retested.',
+      method: 'POST',
+      URL: `${thisHost}/api/requestRetest/${timeStamp}/${jobID}`,
+      body: {
+        reason
+      },
+      'closest ancestor request': {
+        'tool name': 'listIssues',
+        description: 'Provide details about one report, including basics about the issues reported in it.',
+        method: 'GET',
+        URL: `${thisHost}/api/listIssues/${timeStamp}/${jobID}`
+      }
+    },
+    'URLs of similar requests for web users': {
+      'this request': `${thisHost}/retestRecForm.html/${timeStamp}/${jobID}`,
+      'closest ancestor request': `${thisHost}/reportIssues.html/${timeStamp}/${jobID}`
+    },
+    'response metadata': getResponseMetadata(),
+    'response content': responseContent
+  };
+  // Return it.
+  return body;
+};

package/api/requestTest.js

@@ -0,0 +1,106 @@
+/*
+  requestTest.js
+  Processes a request to test an untested page and returns an acknowledgement.
+*/
+
+// IMPORTS
+
+const {getResponseMetadata, getToolsFacts, processTestRequest, thisHost} = require('./util');
+const {getReportExtracts, isURL} = require('../util');
+
+// FUNCTIONS
+
+// Returns the response body.
+exports.response = async args => {
+  const [what = '', url = '', reason = ''] = args;
+  // Initialize the response content.
+  const responseContent = {
+    'details about your request': {},
+    'disposition of your request': null
+  };
+  const whatLength = what.length;
+  // If the description is empty or too long:
+  if (!whatLength || whatLength > 100) {
+    // Add this to the response content.
+    responseContent['details about your request'] = {
+      error: 'request invalid: your description of the page is not between 1 and 100 characters long'
+    };
+  }
+  // Otherwise, i.e. if the URL is too short or too long::
+  else if (url.length < 12 || url.length > 300) {
+    // Add this to the response content.
+    responseContent['details about your request'] = {
+      error: 'request invalid: you specified a URL for the page that is not between 12 and 300 characters long'
+    };
+  }
+  // Otherwise, i.e. if the URL is invalid:
+  else if (!isURL(url)) {
+    // Add this to the response content.
+    responseContent['details about your request'] = {
+      error: 'request invalid: you specified an invalid URL for the page'
+    };
+  }
+  // Otherwise, i.e. if the description and URL are valid:
+  else {
+    // Get an extract of the available reports.
+    const reportExtracts = await getReportExtracts();
+    // If any report is on a page with the specified description and URL:
+    if (
+      reportExtracts.some(extract => extract.what === what && extract.url === url)
+    ) {
+      // Add this to the response content.
+      responseContent['details about your request'] = {
+        error: 'request invalid: the page has already been tested and its report is available'
+      };
+    }
+    // Otherwise, i.e. if none is on the page:
+    else {
+      // Process the request.
+      await processTestRequest('test', what, url, reason);
+      // Add details about the request to the response content.
+      responseContent['details about your request'] = {
+        'date and time received': new Date().toISOString(),
+        'page to be tested': {
+          description: what,
+          URL: url
+        },
+        'reason why the page should be tested': reason
+      };
+      // Add information about the disposition of the request to the response content.
+      responseContent['disposition of your request'] = {
+        'what happens next': 'Your request is likely to be approved and processed within 1 hour to 1 day.',
+        'how you can check for completion': 'You can call the listReports tool to learn whether the page has been tested and a report is available.',
+        'how a web user can check for completion': `A web user can visit ${thisHost}/targets.html to learn whether the page has been tested and a report is available.`
+      };
+    }
+  }
+  // Create a response body.
+  const body = {
+    'tool collection': getToolsFacts(),
+    'tool name': 'requestTest',
+    'this request': {
+      description: 'Process my request to test a page about which no report is available yet. I have provided a description and the URL of the page and a reason why it should be tested.',
+      method: 'POST',
+      URL: `${thisHost}/api/requestTest`,
+      body: {
+        description: what,
+        URL: url,
+        reason
+      },
+      'closest ancestor request': {
+        'tool name': 'listReports',
+        description: 'Provide basics about all available reports.',
+        method: 'GET',
+        URL: `${thisHost}/api/listReports`
+      }
+    },
+    'URLs of similar requests for web users': {
+      'this request': `${thisHost}/testRecForm.html`,
+      'closest ancestor request': `${thisHost}/targets.html`
+    },
+    'response metadata': getResponseMetadata(),
+    'response content': responseContent
+  };
+  // Return it.
+  return body;
+};

package/api/routes.js

@@ -0,0 +1,97 @@
+/*
+  routes.js
+  Route metadata for OpenAPI generation. Pairs each Kilotest API operation with its HTTP method, path template, and the request/response schemas from schemas.js. This table supplies the facts that schemas.js cannot express on its own (method, path, path-vs-body placement), mirroring the manual dispatch in index.js and the // GET/POST comments in schemas.js.
+*/
+
+// IMPORTS
+
+const {z} = require('zod');
+const {
+  listIssuesSchema,
+  listViolatorsSchema,
+  listDiagnosesSchema,
+  getReportSchema,
+  requestTestSchema,
+  requestRetestSchema,
+  requestFeatureSchema,
+  listReportsResponseSchema,
+  listIssuesResponseSchema,
+  listViolatorsResponseSchema,
+  listDiagnosesResponseSchema,
+  getReportResponseSchema,
+  requestTestResponseSchema,
+  requestRetestResponseSchema,
+  requestFeatureResponseSchema
+} = require('./schemas');
+
+// ROUTES
+
+module.exports = [
+  {
+    operationId: 'listReports',
+    method: 'get',
+    path: '/api/listReports',
+    summary: 'List all available reports',
+    responseSchema: listReportsResponseSchema
+  },
+  {
+    operationId: 'listIssues',
+    method: 'get',
+    path: '/api/listIssues/{timeStamp}/{jobID}',
+    summary: 'List basics about the issues in one report',
+    pathParamsSchema: z.object(listIssuesSchema),
+    responseSchema: listIssuesResponseSchema
+  },
+  {
+    operationId: 'listViolators',
+    method: 'get',
+    path: '/api/listViolators/{issueID}/{timeStamp}/{jobID}',
+    summary: 'List elements reported as exhibiting one issue',
+    pathParamsSchema: z.object(listViolatorsSchema),
+    responseSchema: listViolatorsResponseSchema
+  },
+  {
+    operationId: 'listDiagnoses',
+    method: 'get',
+    path: '/api/listDiagnoses/{catalogIndex}/{issueID}/{timeStamp}/{jobID}',
+    summary: 'List diagnoses of how one element exhibited one issue',
+    pathParamsSchema: z.object(listDiagnosesSchema),
+    responseSchema: listDiagnosesResponseSchema
+  },
+  {
+    operationId: 'getReport',
+    method: 'get',
+    path: '/api/getReport/{timeStamp}/{jobID}',
+    summary: 'Get one full report in JSON',
+    pathParamsSchema: z.object(getReportSchema),
+    responseSchema: getReportResponseSchema
+  },
+  {
+    operationId: 'requestTest',
+    method: 'post',
+    path: '/api/requestTest',
+    summary: 'Request that a page be tested',
+    bodySchema: z.object(requestTestSchema),
+    responseSchema: requestTestResponseSchema
+  },
+  {
+    operationId: 'requestRetest',
+    method: 'post',
+    path: '/api/requestRetest/{timeStamp}/{jobID}',
+    summary: 'Request that a page be retested',
+    pathParamsSchema: z.object({
+      timeStamp: requestRetestSchema.timeStamp,
+      jobID: requestRetestSchema.jobID
+    }),
+    bodySchema: z.object({reason: requestRetestSchema.reason}),
+    responseSchema: requestRetestResponseSchema
+  },
+  {
+    operationId: 'requestFeature',
+    method: 'post',
+    path: '/api/requestFeature',
+    summary: 'Request a new feature or feature improvement',
+    bodySchema: z.object(requestFeatureSchema),
+    responseSchema: requestFeatureResponseSchema
+  }
+];