@jrpool/kilotest 26.0.1 → 28.0.0

package/index.js

@@ -87,6 +87,9 @@ const serveError = async (error, response, isHumanUser = true) => {
     if (isHumanUser) {
       // Serve an HTML page containing the message property of the error.
       response.setHeader('content-type', 'text/html; charset=utf-8');
+      response.setHeader('content-location', '/error.html');
+      response.setHeader('Access-Control-Allow-Origin', '*');
+      response.setHeader('Cache-Control', 'public, max-age=300, stale-while-revalidate=3000');
       const errorTemplate = await fs.readFile('error.html', 'utf8');
       const errorPage = errorTemplate.replace(/__error__/, error.message || 'ERROR');
       response.end(errorPage);
@@ -168,11 +171,28 @@ const checkBalancesForAlerts = async report => {
 };
 // Handles a request.
 const requestHandler = async (request, response) => {
+  // Sets response headers.
+  const setHeaders = (contentType, location, volatility = 'high') => {
+    response.setHeader('content-type', `${contentType}; charset=utf-8`);
+    if (location) {
+      response.setHeader('content-location', location);
+    }
+    response.setHeader('Access-Control-Allow-Origin', '*');
+    const lives = {
+      high: [300, 3000],
+      medium: [1000, 10000],
+      low: [5000, 50000]
+    };
+    response.setHeader(
+      'Cache-Control',
+      `public, max-age=${lives[volatility][0]}, stale-while-revalidate=${lives[volatility][1]}`
+    );
+  };
   const {method, url} = request;
   const requestURL = new URL(url, 'https://localhost:3000');
   const {pathname, search} = requestURL;
   const pageName = pathname.split('/')[1];
-  const pageArgs = pathname.split('/').slice(2).join('/');
+  const pathTail = pathname.split('/').slice(2).join('/');
   // If the request is an OPTIONS request:
   if (method === 'OPTIONS') {
     // Serve response headers, including one allowing requests from other applications.
@@ -189,14 +209,30 @@ const requestHandler = async (request, response) => {
       // Get the home page.
       const homePage = await fs.readFile('index.html', 'utf8');
       // Serve it.
-      response.setHeader('content-type', 'text/html; charset=utf-8');
-      response.setHeader('content-location', '/index.html');
-      response.setHeader('Access-Control-Allow-Origin', '*');
+      setHeaders('text/html', '/index.html', 'medium');
       response.end(homePage);
     }
+    // Otherwise, if it is for the the crawler specification:
+    else if (pageName === 'robots.txt') {
+      const robots = await fs.readFile('robots.txt', 'utf8');
+      setHeaders('text/plain', '/robots.txt', 'low');
+      response.end(robots);
+    }
+    // Otherwise, if it is for the the OpenAPI specification:
+    else if (pageName === 'openapi.yaml') {
+      const openapi = await fs.readFile('openapi.yaml', 'utf8');
+      setHeaders('text/yaml', '/openapi.yaml', 'high');
+      response.end(openapi);
+    }
+    // Otherwise, if it is for the the large-language-model specification:
+    else if (pageName === 'llms.txt') {
+      const llms = await fs.readFile('llms.txt', 'utf8');
+      setHeaders('text/plain', '/llms.txt', 'high');
+      response.end(llms);
+    }
     // Otherwise, if it is for a full report download:
-    else if (pageName === 'fullReport.html') {
-      const [timeStamp, jobID] = pageArgs.split('/');
+    else if (pageName === 'fullReport.json') {
+      const [timeStamp, jobID] = pathTail.split('/');
       // If the request is syntactically valid:
       if (isTimeStamp(timeStamp) && isJobID(jobID)) {
         const reportHidden = await isHidden(timeStamp, jobID);
@@ -222,11 +258,10 @@ const requestHandler = async (request, response) => {
           // If it exists and is valid:
           if (typeof report === 'object') {
             // Serve response headers for a JSON download.
-            response.setHeader('content-type', 'application/json; charset=utf-8');
+            setHeaders('application/json', null, 'low');
             response.setHeader(
               'content-disposition', `attachment; filename="${timeStamp}-${jobID}.json"`,
             );
-            response.setHeader('Access-Control-Allow-Origin', '*');
             // Download the report.
             response.end(getJSON(report));
           }
@@ -248,11 +283,9 @@ const requestHandler = async (request, response) => {
       const topic = pageName.slice(0, -5);
       // If the page can be generated:
       if (answer[topic]) {
-        // Serve response headers, including one allowing requests from other applications.
-        response.setHeader('content-type', 'text/html; charset=utf-8');
-        response.setHeader('content-location', `${pathname}${search}`);
+        setHeaders('text/html', `${pathname}${search}`, 'medium');
         // Get the answer data.
-        const answerData = await answer[topic](pageArgs, search);
+        const answerData = await answer[topic](pathTail, search);
         // If they are valid:
         if (answerData.status === 'ok') {
           // Serve the answer page.
@@ -270,6 +303,47 @@ const requestHandler = async (request, response) => {
         await serveError({message: 'ERROR: Invalid request'}, response, true);
       }
     }
+    // Otherwise, if it is for an API service:
+    else if (pageName === 'api') {
+      const [service,  ... specs] = pathTail.split('/');
+      // If the service is provision of facts about the available reports:
+      if (service === 'targets') {
+        // Get the response (potentially error) data.
+        const responseData = await require(path.join(__dirname, 'targets', 'api')).response(specs);
+        // Send them.
+        setHeaders('application/json', null, 'high');
+        response.end(JSON.stringify(responseData));
+      }
+      // Otherwise, if the service is provision of issue statistics for a report:
+      else if (service === 'reportIssues') {
+        // Get the report identifiers from the path.
+        const [timeStamp, jobID] = specs;
+        const reportSpecsBad = await isHidden(timeStamp, jobID);
+        // If the report is nonexistent or hidden:
+        if (reportSpecsBad) {
+          // Report this.
+          await serveError(
+            {message: reportSpecsBad === true ? 'Report nonexistent or hidden' : reportSpecsBad},
+            response,
+            false
+          );
+        }
+        // Otherwise, i.e. if the report is available:
+        else {
+          // Get the response (potentially error) data.
+          const responseData = await require(path.join(__dirname, 'reportIssues', 'api'))
+          .response(specs);
+          // Send them.
+          setHeaders('application/json', null, 'high');
+          response.end(JSON.stringify(responseData));
+        }
+      }
+      // Otherwise, i.e. if the service is invalid:
+      else {
+        // Report this.
+        await serveError({message: 'ERROR: Invalid service request'}, response, false);
+      }
+    }
     // Otherwise, if it is for a tutorial image:
     else if (pathname.startsWith('/tutorial/images/')) {
       const imgFile = pathname.slice('/tutorial/images/'.length);
@@ -277,9 +351,15 @@ const requestHandler = async (request, response) => {
       try {
         const img = await fs.readFile(imgPath);
         const ext = path.extname(imgFile).toLowerCase();
-        const mimeTypes = {'.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml'};
-        response.setHeader('content-type', mimeTypes[ext] || 'application/octet-stream');
-        response.setHeader('cache-control', 'public, max-age=3600');
+        const mimeTypes = {
+          '.png': 'image/png',
+          '.jpg': 'image/jpeg',
+          '.jpeg': 'image/jpeg',
+          '.gif': 'image/gif',
+          '.webp': 'image/webp',
+          '.svg': 'image/svg+xml'
+        };
+        setHeaders(mimeTypes[ext] || 'application/octet-stream', null, 'low');
         response.end(img);
       }
       catch (_) {
@@ -291,7 +371,7 @@ const requestHandler = async (request, response) => {
       // Get the site icon.
       const icon = await fs.readFile(path.join(__dirname, 'favicon.ico'));
       // Serve it.
-      response.setHeader('content-type', 'image/x-icon');
+      setHeaders('image/x-icon', null, 'low');
       response.write(icon, 'binary');
       response.end('');
     }
@@ -300,10 +380,7 @@ const requestHandler = async (request, response) => {
       try {
         // Serve it.
         const styleSheet = await fs.readFile('style.css', 'utf8');
-        response.writeHead(200, {
-          'content-type': 'text/css; charset=utf-8',
-          'cache-control': 'public, max-age=600'
-        });
+        setHeaders('text/css', null, 'low');
         response.end(styleSheet);
       }
       catch (error) {
@@ -325,16 +402,14 @@ const requestHandler = async (request, response) => {
     // If the request is a retest recommendation:
     if (pageName === 'retestRec.html') {
       const {why} = postData;
-      const [timeStamp, jobID] = pageArgs.split('/');
+      const [timeStamp, jobID] = pathTail.split('/');
       // If the request is valid:
       if (isTimeStamp(timeStamp) && isJobID(jobID) && why) {
-        // Serve response headers, including one allowing requests from other applications.
-        response.setHeader('content-type', 'text/html; charset=utf-8');
-        response.setHeader('content-location', `${pathname}${search}`);
-        response.setHeader('Access-Control-Allow-Origin', '*');
+        // Serve response headers.
+        setHeaders('text/html', `${pathname}${search}`, 'high');
         // Get the answer data.
         const answerData = await require(path.join(__dirname, 'retestRec', 'index'))
-        .answer(pageArgs, why);
+        .answer(pathTail, why);
         // If they are valid:
         if (answerData.status === 'ok') {
           // Serve the answer page.
@@ -358,8 +433,7 @@ const requestHandler = async (request, response) => {
       // If the request is valid:
       if (what && url.startsWith('https://') && why) {
         // Serve headers for a response.
-        response.setHeader('content-type', 'text/html; charset=utf-8');
-        response.setHeader('content-location', `${pathname}${search}`);
+        setHeaders('text/html', `${pathname}${search}`, 'high');
         // Get the answer data.
         const answerData = await require(path.join(__dirname, 'testRec', 'index'))
         .answer(what, url, why);
@@ -386,11 +460,11 @@ const requestHandler = async (request, response) => {
       const [url, what] = target.split('\t');
       // If the request is valid:
       if (url.startsWith('https://') && authCode === process.env.AUTH_CODE) {
-        // Serve a content-type header for a response.
-        response.setHeader('content-type', 'text/html; charset=utf-8');
+        // Set the non-location headers for a response.
+        setHeaders('text/html', null, 'high');
         // If the request is an approval:
         if (what) {
-          // Serve a location header for a response.
+          // Set a location header for a response.
           response.setHeader('content-location', `${pathname}${search}`);
           // Get the answer data.
           const answerData = await require(path.join(__dirname, 'testOrder', 'index'))
@@ -414,7 +488,7 @@ const requestHandler = async (request, response) => {
           delete recs[url];
           // Save the revised recommendations.
           await fs.writeFile(path.join(__dirname, 'jobs', 'recs.json'), getJSON(recs));
-          // Serve a location header for a response.
+          // Set a location header for a response.
           response.setHeader('content-location', '/recActionForm.html');
           // Get the answer data.
           const answerData = await require(path.join(__dirname, 'recActionForm', 'index')).answer();
@@ -431,9 +505,8 @@ const requestHandler = async (request, response) => {
     // Otherwise, if it is a reannotation order:
     else if (pageName === 'reannotate.html') {
       const {authCode} = postData;
-      // Serve headers for a response.
-      response.setHeader('content-type', 'text/html; charset=utf-8');
-      response.setHeader('content-location', `${pathname}${search}`);
+      // Set headers for a response.
+      setHeaders('text/html', `${pathname}${search}`, 'high');
       // Get the answer data.
       const answerData = await require(path.join(__dirname, 'reannotate', 'index'))
       .answer(authCode);
@@ -451,9 +524,8 @@ const requestHandler = async (request, response) => {
     // Otherwise, if it is a WCAG map renewal:
     else if (pageName === 'wcagRenew.html') {
       const {authCode} = postData;
-      // Serve headers for a response.
-      response.setHeader('content-type', 'text/html; charset=utf-8');
-      response.setHeader('content-location', `${pathname}${search}`);
+      // Set headers for a response.
+      setHeaders('text/html', `${pathname}${search}`, 'low');
       // Get the answer data.
       const answerData = await require(path.join(__dirname, 'wcagRenew', 'index'))
       .answer(authCode);
@@ -470,10 +542,13 @@ const requestHandler = async (request, response) => {
     }
     // Otherwise, if it is a request from an agent:
     else if (pageName === 'api') {
-      // Get the agent ID, the service, and any service specifications from the path.
-      const [agentID, service, ... specs] = pageArgs.split('/');
-      // If the agent is the authorized Testaro instance and it is authenticated:
-      if (agentID === testaroAgent && postData.agentPW === testaroAgentPW) {
+      // Get the segments of the path after api.
+      const segments = pathTail.split('/');
+      // If the first segment is the ID of the Testaro agent and the agent is authenticated:
+      if (specs[0] === testaroAgent && postData.agentPW === testaroAgentPW) {
+        const agentID = specs[0];
+        // Get the requested service from the path.
+        const service = specs[1];
         // If the service is job assignment:
         if (service === 'job') {
           let clean = true;
@@ -580,58 +655,11 @@ const requestHandler = async (request, response) => {
           );
         }
       }
-      // Otherwise, if the agent is the authorized research agent and it is authenticated:
-      else if (agentID === researchAgent && postData.agentPW === researchAgentPW) {
-        // If the service is provision of facts about the available reports:
-        if (service === 'targets') {
-          // Get the agent ID from the path.
-          const args = [agentID];
-          // Get the response (potentially error) data.
-          const responseData = await require(path.join(__dirname, 'targets', 'api')).response(args);
-          // Send them.
-          response.end(JSON.stringify(responseData));
-        }
-        // Otherwise, if the service is provision of facts about issues in a report:
-        else if (service === 'reportIssues') {
-          // Get the agent ID and report identifiers from the path.
-          const [timeStamp, jobID] = specs;
-          const args = [agentID, timeStamp, jobID];
-          const reportSpecsBad = await isHidden(timeStamp, jobID);
-          // If the report is nonexistent or hidden:
-          if (reportSpecsBad) {
-            // Report this.
-            await serveError(
-              {message: reportSpecsBad === true ? 'Report nonexistent or hidden' : reportSpecsBad},
-              response,
-              false
-            );
-          }
-          // Otherwise, i.e. if the report is available:
-          else {
-            // Get the response (potentially error) data.
-            const responseData = await require(path.join(__dirname, 'reportIssues', 'api'))
-            .response(args);
-            // Send them.
-            response.end(JSON.stringify(responseData));
-          }
-        }
-        // Otherwise, i.e. if the service is invalid:
-        else {
-          // Report this.
-          await serveError({message: 'ERROR: Invalid service request from research agent'}, response, false);
-        }
-      }
-      // Otherwise, i.e. if the agent is not authorized or not authenticated:
-      else {
-        // Report this.
-        await serveError({message: 'ERROR: Invalid agent'}, response, false);
-      }
     }
     // Otherwise, if it is a tutorial comment:
     else if (pageName === 'tutorialComment.html') {
       const {content} = postData;
-      response.setHeader('content-type', 'application/json; charset=utf-8');
-      response.setHeader('Access-Control-Allow-Origin', '*');
+      setHeaders('application/json', null, 'low');
       const answerData = await require(path.join(__dirname, 'tutorial', 'index')).saveComment(content);
       if (answerData.status === 'ok') {
         response.end(JSON.stringify({status: 'ok'}));

package/llms.txt

@@ -0,0 +1,16 @@
+# Kilotest
+Kilotest helps AI agents give accurate and truthful answers when users ask how accessible, usable, or standard conformant web pages are. Kilotest integrates ten independent rule engines to provide comprehensive multipage, single-page, and element-level statistics and details via its API and web UI.
+
+## API
+- GET /api/targets: summarize test results for all tested pages
+- GET /api/reportIssues/{timeStamp}/{jobID}: statistics on issues reported in a job
+- GET /api/reportIssue/{issueID}/{timeStamp}/{jobID}: details on issues reported in a job
+- GET /api/issues: statistics on frequently reported issues across all tested pages
+- OpenAPI spec: https://kilotest.com/openapi.yaml
+
+## Web UI
+- https://kilotest.com/targets.html: summarize test results for all tested pages
+- https://kilotest.com/reportIssues.html/{timeStamp}/{jobID}: details on issues reported in a job
+- https://kilotest.com/reportIssue.html/{issueID}/{timeStamp}/{jobID}: details on issues reported in a job
+- https://kilotest.com/issues.html: statistics on frequently reported issues across all tested pages
+- https://kilotest.com/tutorial.html: tutorial, “Accessibility testing strategies”

package/openapi.yaml

@@ -0,0 +1,346 @@
+openapi: 3.1.0
+info:
+  title: Kilotest Agent API
+  description: Kilotest tests web pages for accessibility, usability, and standard conformity using an ensemble of ten independent tools that employ rule-based and machine-learning-based methods. This API enables AI agents to recommend web pages for testing (not yet implemented), discover available test reports, and retrieve data from reports at multiple levels of detail. For background on Kilotest and the advantages of ensemble testing, visit https://kilotest.com.
+  version: 1.0.0
+  contact:
+    url: https://kilotest.com
+    email: info@kilotest.com
+    repository: https://github.com/jrpool/kilotest
+
+servers:
+  - url: https://kilotest.com/api
+    description: Kilotest production server
+
+paths:
+  /api/targets:
+    post:
+      operationId: getReportSummaries
+      summary: Summarize all available reports
+      description: Returns summary data about every non-hidden report available from Kilotest, including the name and URL of the tested web page, when the testing was performed, how many issues were reported, and URLs for retrieving more detailed data from the report.
+      responses:
+        '200':
+          description: Summaries of available reports
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReportSummariesResponse'
+
+  /api/reportIssues/{timeStamp}/{jobID}:
+    post:
+      operationId: getReportIssues
+      summary: Get data on issues from a specific report
+      description: Returns data about the issues reported in a specific Kilotest report, grouped by priority. The data on each issue include the tools that reported it, the number of HTML elements exhibiting it, and URLs for retrieving element-level detail. The timeStamp and jobID components identify the report and are available in the getReportSummaries response.
+      parameters:
+        - name: timeStamp
+          in: path
+          required: true
+          description: timeStamp component of the report identifier, in the format YYMMDDTHHMM (e.g., 260503T0432).
+          schema:
+            type: string
+            pattern: '^\d{6}T\d{4}$'
+            example: '260503T0432'
+        - name: jobID
+          in: path
+          required: true
+          description: Job identifier component of the report identifier (e.g., xx0).
+          schema:
+            type: string
+            example: 'xx0'
+      responses:
+        '200':
+          description: Data on issues from the specified report
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReportIssuesResponse'
+        '404':
+          description: No report with the specified identifier is available
+
+  /api/reportIssue/{issueID}/{timeStamp}/{jobID}:
+    post:
+      operationId: getReportIssue
+      summary: Get details about a specific issue in a specific report
+      description: Returns details about a single issue within a specific report, including which HTML elements exhibit the issue and, for each such element, URLs for retrieving tool-by-tool diagnoses of the issue on the element.
+      parameters:
+        - name: issueID
+          in: path
+          required: true
+          description: Issue identifier (e.g., imageNoText). Available under "issues reported" > priority level > "identifier" in the getReportIssues response.
+          schema:
+            type: string
+            example: 'imageNoText'
+        - name: timeStamp
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: jobID
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Details about the specified issue in the specified report
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReportIssueResponse'
+        '404':
+          description: No report or issue found with the specified identifiers
+
+components:
+  schemas:
+
+    CommonResponseFields:
+      type: object
+      properties:
+        summary:
+          type: string
+          description: Natural-language description of this response and of Kilotest. Provides context for an agent encountering Kilotest for the first time.
+        tool name:
+          type: string
+          example: Kilotest
+        request:
+          type: object
+          properties:
+            requesting agent:
+              type: object
+              properties:
+                identifier:
+                  type: string
+                  example: research-agent
+                name:
+                  type: string
+                  example: Internal Research Agent
+            type of request:
+              type: object
+              properties:
+                identifier:
+                  type: string
+                description:
+                  type: string
+        response metadata:
+          type: object
+          properties:
+            identifier:
+              type: string
+              description: Unique identifier for this response instance.
+            date and time:
+              type: string
+              format: date-time
+
+    ToolInfo:
+      type: object
+      description: An accessibility testing tool in the Kilotest ensemble.
+      properties:
+        identifier:
+          type: string
+          description: Short programmatic identifier for the tool.
+          example: alfa
+        name:
+          type: string
+          description: Display name of the tool.
+          example: Alfa
+        sponsor:
+          type: string
+          description: Organization that created or sponsors the tool.
+          example: Siteimprove
+
+    ToolFailure:
+      type: object
+      description: A tool that was unable to complete testing of the page.
+      properties:
+        name:
+          type: string
+          example: WAVE
+        reason for failure:
+          type: string
+          example: Not enough credits.
+
+    ToolsSummary:
+      type: object
+      description: Count and names of a set of tools.
+      properties:
+        number:
+          type: integer
+        names:
+          type: array
+          items:
+            type: string
+
+    NextTierURLs:
+      type: object
+      description: URLs for retrieving the next level of detail.
+      properties:
+        for you:
+          type: string
+          format: uri
+          description: URL for an agent to request the next tier of detail.
+        for humans:
+          type: string
+          format: uri
+          description: URL for a human to view the next tier of detail.
+
+    ReportSummaryItem:
+      type: object
+      description: Summary data about a single available report.
+      properties:
+        identifier:
+          type: string
+          example: 260504T1659-029
+        creation date:
+          type: string
+          format: date-time
+        days since the creation date:
+          type: integer
+        tested web page:
+          type: object
+          properties:
+            description:
+              type: string
+            URL:
+              type: string
+              format: uri
+        whether a later report about the same page exists:
+          type: boolean
+          description: If true, a more recent report about this page is available. If you want the latest results, use that report instead.
+        number of issues reported:
+          type: integer
+        number of HTML elements reported as exhibiting issues:
+          type: integer
+        tools that tried to test the page:
+          $ref: '#/components/schemas/ToolsSummary'
+        tools that were unable to test the page:
+          $ref: '#/components/schemas/ToolsSummary'
+        tools that reported issues:
+          $ref: '#/components/schemas/ToolsSummary'
+        URLs for getting data on the reported issues:
+          $ref: '#/components/schemas/NextTierURLs'
+        URL for getting the full technical report as JSON:
+          type: string
+          format: uri
+
+    ReportSummariesResponse:
+      allOf:
+        - $ref: '#/components/schemas/CommonResponseFields'
+        - type: object
+          properties:
+            available reports:
+              type: array
+              description: One entry per available Kilotest report, in alphabetical order by page description and, in case of multiple reports per page, in order of creation date and time. Reports are matched by page description, not page URL, so, if only the URL of a page has changed between reports, the reports are treated as reports about the same page.
+              items:
+                $ref: '#/components/schemas/ReportSummaryItem'
+
+    IssueEntry:
+      type: object
+      description: Details about a specific accessibility issue found on a page.
+      properties:
+        identifier:
+          type: string
+          example: imageNoText
+        summary:
+          type: string
+          description: Brief natural-language label for the issue.
+          example: image not named
+        related WCAG 2.2 standard:
+          type: object
+          description: The WCAG 2.2 success criterion or guideline most closely related to this issue.
+          properties:
+            layer:
+              type: string
+              enum: [guideline, success criterion]
+            'numeric identifier':
+              type: string
+              pattern: '^\d\.\d(\.\d+)?$'
+              example: '1.1.1'
+        impact on a user:
+          type: string
+          description: How this issue is likely to affect users.
+        tools reporting the issue:
+          $ref: '#/components/schemas/ToolsSummary'
+        number of HTML elements reported as exhibiting the issue:
+          type: integer
+        URLs for details about the issue on the page:
+          $ref: '#/components/schemas/NextTierURLs'
+
+    IssuesByPriority:
+      type: object
+      properties:
+        highest priority:
+          type: array
+          items:
+            $ref: '#/components/schemas/IssueEntry'
+        high priority:
+          type: array
+          items:
+            $ref: '#/components/schemas/IssueEntry'
+        low priority:
+          type: array
+          items:
+            $ref: '#/components/schemas/IssueEntry'
+        lowest priority:
+          type: array
+          items:
+            $ref: '#/components/schemas/IssueEntry'
+
+    ReportIssuesResponse:
+      allOf:
+        - $ref: '#/components/schemas/CommonResponseFields'
+        - type: object
+          properties:
+            report:
+              type: object
+              properties:
+                identifier:
+                  type: string
+                creation date:
+                  type: string
+                  format: date-time
+                days since the creation date:
+                  type: integer
+            tested web page:
+              type: object
+              properties:
+                description:
+                  type: string
+                URL:
+                  type: string
+                  format: uri
+            tools that tried to test the page:
+              type: array
+              items:
+                $ref: '#/components/schemas/ToolInfo'
+            tools that were unable to test the page:
+              type: array
+              items:
+                $ref: '#/components/schemas/ToolFailure'
+            tools that reported issues:
+              $ref: '#/components/schemas/ToolsSummary'
+            number of issues reported:
+              type: object
+              properties:
+                total:
+                  type: integer
+                by priority:
+                  type: object
+                  properties:
+                    highest priority:
+                      type: integer
+                    high priority:
+                      type: integer
+                    low priority:
+                      type: integer
+                    lowest priority:
+                      type: integer
+            number of HTML elements reported as exhibiting issues:
+              type: integer
+            issues reported:
+              $ref: '#/components/schemas/IssuesByPriority'
+
+    ReportIssueResponse:
+      allOf:
+        - $ref: '#/components/schemas/CommonResponseFields'
+        - type: object
+          description: Element-level detail for a specific issue. Schema to be completed once the tier-3 service is implemented.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "26.0.1",
+  "version": "28.0.0",
   "description": "An ensemble testing service with a focus on accessibility",
   "main": "index.js",
   "scripts": {

package/reportIssues/api.js

@@ -12,20 +12,22 @@ const {
   getRandomString,
   getToolsFacts,
   isHidden,
-  researchAgents,
   tools
 } = require('../util');
 
 // FUNCTIONS
 
 // Gets facts about an issue.
-const getIssueFacts = (thisHost, agentID, timeStamp, jobID, issue) => {
+const getIssueFacts = (thisHost, timeStamp, jobID, issue) => {
   const {issueID, reporterCount, reporters, summary, violatorCount, wcag, why} = issue;
-  const wcagType = wcag.length === 3 ? 'principle' : 'success criterion';
+  const wcagType = wcag.length === 3 ? 'guideline' : 'success criterion';
   return {
     identifier: issueID,
     summary,
-    [`related WCAG ${wcagType}`]: wcag,
+    'related WCAG 2.2 standard': {
+      layer: wcagType,
+      'numeric identifier': wcag
+    },
     'impact on a user': why,
     'tools reporting the issue': {
       'number': reporterCount,
@@ -33,14 +35,14 @@ const getIssueFacts = (thisHost, agentID, timeStamp, jobID, issue) => {
     },
     'number of HTML elements reported as exhibiting the issue': violatorCount,
     'URLs for details about the issue on the page': {
-      'for you': `${thisHost}/api/${agentID}/reportIssue/${timeStamp}/${jobID}/${issueID}`,
-      'for humans': `${thisHost}/reportIssue/${timeStamp}/${jobID}/${issueID}`
+      'for you': `${thisHost}/api/reportIssue/${issueID}/${timeStamp}/${jobID}`,
+      'for humans': `${thisHost}/reportIssue.html/${issueID}/${timeStamp}/${jobID}`
     }
   };
 };
 // Returns a response to a target-issues request.
 exports.response = async args => {
-  const [agentID, timeStamp, jobID] = args;
+  const [timeStamp, jobID] = args;
   const reportIsHidden = await isHidden(timeStamp, jobID);
   // If the report is not available:
   if (reportIsHidden) {
@@ -64,24 +66,25 @@ exports.response = async args => {
     summary: `This document fulfills a request made by an agent to the Kilotest service. The agent requested data from a Kilotest report about the accessibility, usability, and standard-conformity of a web page. Kilotest, with the help of Testaro, Testilo, and an ensemble of ten testing tools, performs tests on web pages, using a combination of rule- and machine-learning-based methods, and produces reports. Kilotest exposes several API endpoints for agents and several web UI URLs for humans to obtain information from Kilotest reports. To learn more about Kilotest and the advangages of testing with an ensemble of tools, visit the deployed instance of Kilotest (${process.env.DEPLOYED_KILOTEST_HOST}), which contains an introduction on its home page and a tutorial.`,
     'tool name': 'Kilotest',
     request: {
-      'requesting agent': {
-        identifier: agentID,
-        name: researchAgents[agentID]
-      },
       'type of request': {
         identifier: 'reportIssues',
         description: 'What issues does the specified report describe?'
       },
+      URLs: {
+        'URL of your request': `${thisHost}/api/reportIssues/${timeStamp}/${jobID}`,
+        'equivalent URL for humans': `${thisHost}/reportIssues.html/${timeStamp}/${jobID}`
+      },
       'closest ancestor request': {
         description: 'Which web pages are reports available about, and what are the statistics about the issues reported for each page?',
-        'URL for you': `${thisHost}/api/${agentID}/targets.html`,
-        'URL for humans': `${thisHost}/targets.html`
+        URLs: {
+          'for you': `${thisHost}/api/targets.html`,
+          'for humans': `${thisHost}/targets.html`
+        }
       }
     },
     'response metadata': {
       identifier: `${getNowStamp()}-${getRandomString(3)}`,
-      'date and time': new Date().toISOString(),
-      'URL of the human-oriented equivalent of this response': `${thisHost}/reportIssues.html/${timeStamp}/${jobID}`
+      'date and time': new Date().toISOString()
     },
     report: {
       identifier: `${timeStamp}-${jobID}`,
@@ -110,13 +113,13 @@ exports.response = async args => {
     'number of HTML elements reported as exhibiting issues': violatorCount,
     'issues reported': {
       'highest priority': issues[4]
-      .map(issue => getIssueFacts(thisHost, agentID, timeStamp, jobID, issue)),
+      .map(issue => getIssueFacts(thisHost, timeStamp, jobID, issue)),
       'high priority': issues[3]
-      .map(issue => getIssueFacts(thisHost, agentID, timeStamp, jobID, issue)),
+      .map(issue => getIssueFacts(thisHost, timeStamp, jobID, issue)),
       'low priority': issues[2]
-      .map(issue => getIssueFacts(thisHost, agentID, timeStamp, jobID, issue)),
+      .map(issue => getIssueFacts(thisHost, timeStamp, jobID, issue)),
       'lowest priority': issues[1]
-      .map(issue => getIssueFacts(thisHost, agentID, timeStamp, jobID, issue))
+      .map(issue => getIssueFacts(thisHost, timeStamp, jobID, issue))
     }
   };
   return response;

package/reportIssues/index.html

@@ -25,7 +25,7 @@
       <p>__reporterCount__ reported issues (__reporters__)</p>
       <p>__issueCount__ reported (__highestCount__ highest, __highCount__ high, __lowCount__ low, __lowestCount__ lowest priority)</p>
       <p>__violatorCount__ reported</p>
-      <p>Download the <a href="/fullReport.html/__timeStamp__/__jobID__">full technical report</a></p>
+      <p>Download the <a href="/fullReport.json/__timeStamp__/__jobID__">full technical report</a></p>
       <h3>Details</h3>
       <details>
         <summary>Highest priority: __highestCount__</summary>

package/researchAgent.js

@@ -20,8 +20,6 @@ const httpsClient = require('https');
 
 // CONSTANTS
 
-const agent = process.env.RESEARCH_AGENT;
-const agentPW = process.env.RESEARCH_AGENT_PW;
 const kilotestHosts = [process.env.LOCAL_KILOTEST_HOST, process.env.DEPLOYED_KILOTEST_HOST];
 // Randomly chosen Kilotest host.
 const kilotestHost = kilotestHosts[Math.random() < 0.5 ? 0 : 1];
@@ -36,7 +34,7 @@ const port = hostParts[2] || (scheme === 'https' ? 443 : 80);
 const requestService = async () => {
   const client = scheme === 'https' ? httpsClient : httpClient;
   const getRequestOptions = path => ({
-    method: 'POST',
+    method: 'GET',
     host,
     port,
     path,
@@ -44,7 +42,7 @@ const requestService = async () => {
       'content-type': 'application/json; charset=utf-8'
     }
   });
-  const path = `/api/${agent}/targets`;
+  const path = `/api/targets`;
   console.log(`About to submit ${scheme} request as JSON on port ${port} to ${host}${path}`);
   // Submit a targets request.
   client.request(getRequestOptions(path), response => {
@@ -75,7 +73,7 @@ const requestService = async () => {
         const [timeStamp, jobID] = reportIDs[Math.floor(Math.random() * reportIDs.length)]
         .split('-');
         console.log('======================');
-        const path = `/api/${agent}/reportIssues/${timeStamp}/${jobID}`;
+        const path = `/api/reportIssues/${timeStamp}/${jobID}`;
         console.log(`About to submit ${scheme} request as JSON on port ${port} to ${host}${path}`);
         const requestOptions = getRequestOptions(path);
         // Submit an issues request for it.
@@ -109,9 +107,7 @@ const requestService = async () => {
           });
         })
         // Finish sending the issues request.
-        .end(JSON.stringify({
-          agentPW
-        }));
+        .end();
       }
       catch (error) {
         console.log(error.message);
@@ -120,9 +116,7 @@ const requestService = async () => {
     });
   })
   // Finish sending the targets request.
-  .end(JSON.stringify({
-    agentPW
-  }));
+  .end();
 };
 
 // EXECUTION

package/robots.txt

@@ -0,0 +1,4 @@
+# robots.txt
+User-agent: *
+Allow: /
+Sitemap: https://kilotest.com/sitemap.xml

package/sitemap.xml

@@ -0,0 +1,9 @@
+<!-- sitemap.xml -->
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url><loc>https://kilotest.com/</loc></url>
+  <url><loc>https://kilotest.com/targets.html</loc></url>
+  <url><loc>https://kilotest.com/issues.html</loc></url>
+  <url><loc>https://kilotest.com/tutorial.html</loc></url>
+  <url><loc>https://kilotest.com/openapi.yaml</loc></url>
+  <url><loc>https://kilotest.com/llms.txt</loc></url>
+</urlset>

package/targets/api.js

@@ -20,7 +20,7 @@ const thisHost = process.env.THIS_KILOTEST_HOST;
 // FUNCTIONS
 
 // Returns a response to a targets request.
-exports.response = async agentID => {
+exports.response = async () => {
   const availableReports = [];
   // Get the non-hidden logs.
   const targetLogs = await getLogs();
@@ -52,8 +52,6 @@ exports.response = async agentID => {
         URL: url
       },
       'whether a later report about the same page exists': !! superseded,
-      'number of issues reported': issueCount,
-      'number of HTML elements reported as exhibiting issues': violatorCount,
       'tools that tried to test the page': {
         number: toolCount,
         names: toolNames
@@ -66,28 +64,26 @@ exports.response = async agentID => {
         number: reporterCount,
         names: reporterNames
       },
-      'URLs for getting data on the reported issues': {
-        'for you': `${thisHost}/api/${agentID}/reportIssues/${timeStamp}/${jobID}`,
+      'number of issues reported': issueCount,
+      'number of HTML elements reported as exhibiting issues': violatorCount,
+      'URLs for getting data about the reported issues': {
+        'for you': `${thisHost}/api/reportIssues/${timeStamp}/${jobID}`,
         'for humans': `${thisHost}/reportIssues/${timeStamp}/${jobID}`
       },
-      'URL for getting the full technical report as JSON': `${thisHost}/fullReport.html/${timeStamp}/${jobID}`
+      'URL for getting the full technical report as JSON': `${thisHost}/fullReport.json/${timeStamp}/${jobID}`
     });
   }
   // Get a response.
-  const response = {
-    summary: `This document fulfills a request made by an agent to the Kilotest service. The agent requested data about the web pages that Kilotest had tested for accessibility, usability, and standard-conformity and statistics for each page on the results of the tests. Kilotest, with the help of Testaro, Testilo, and an ensemble of ten testing tools, performs tests on web pages, using a combination of rule- and machine-learning-based methods, and produces reports. Kilotest exposes API endpoints for agents and web UI URLs for humans to recommend web pages for testing and obtain information from Kilotest reports. To learn more about Kilotest and the advangages of testing with an ensemble of tools, visit the deployed instance of Kilotest (${process.env.DEPLOYED_KILOTEST_HOST}), whose home page contains an introduction and a link to a tutorial.`,
+  const content = {
+    summary: `This document fulfills a request made by an agent to the Kilotest service. The agent requested data about the web pages that Kilotest had tested for accessibility, usability, and standard-conformity and, for each page, statistics about the results of the tests. Kilotest, with the help of Testaro, Testilo, and an ensemble of ten testing tools, performs tests on web pages, using a combination of rule- and machine-learning-based methods, and produces reports. Kilotest exposes API endpoints for agents and web UI URLs for humans to recommend web pages for testing and to obtain information from Kilotest reports. To learn more about Kilotest and the advangages of testing with an ensemble of tools, visit the deployed instance of Kilotest (${process.env.DEPLOYED_KILOTEST_HOST}), whose home page contains an introduction and a link to a tutorial.`,
     'tool name': 'Kilotest',
     request: {
-      'requesting agent': {
-        identifier: agentID,
-        name: researchAgents[agentID]
-      },
       'type of request': {
         identifier: 'targets',
         description: 'Give me summary data about each available report.'
       },
       URLs: {
-        'URL of this request': `${thisHost}/api/${agentID}/targets`,
+        'URL of your request': `${thisHost}/api/targets`,
         'equivalent URL for humans': `${thisHost}/targets.html`
       }
     },
@@ -97,5 +93,5 @@ exports.response = async agentID => {
     },
     'available reports': availableReports
   };
-  return response;
+  return content;
 };

package/util.js

@@ -367,7 +367,7 @@ exports.getReportData = async (timeStamp, jobID) => {
     if (act.type === 'test') {
       const {result, which} = act;
       // Ensure that the tool is in the temporary data.
-      toolNameSet.add(which);
+      toolNameSet.add(tools[which][0]);
       const instances = result?.standardResult?.instances ?? [];
       // For each standard instance of the act:
       instances.forEach(instance => {