@jrpool/kilotest 26.0.1 → 27.0.0

package/index.js

@@ -194,8 +194,16 @@ const requestHandler = async (request, response) => {
       response.setHeader('Access-Control-Allow-Origin', '*');
       response.end(homePage);
     }
+    // Otherwise, if it is for the the OpenAPI specification:
+    else if (pageName === 'openapi.yaml') {
+      const openapi = await fs.readFile('openapi.yaml', 'utf8');
+      response.setHeader('content-type', 'application/yaml; charset=utf-8');
+      response.setHeader('content-location', '/openapi.yaml');
+      response.setHeader('Access-Control-Allow-Origin', '*');
+      response.end(openapi);
+    }
     // Otherwise, if it is for a full report download:
-    else if (pageName === 'fullReport.html') {
+    else if (pageName === 'fullReport.json') {
       const [timeStamp, jobID] = pageArgs.split('/');
       // If the request is syntactically valid:
       if (isTimeStamp(timeStamp) && isJobID(jobID)) {

package/openapi.yaml

@@ -0,0 +1,400 @@
+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, 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/{agentId}
+    description: Kilotest production server
+    variables:
+      agentId:
+        description: >-
+          Identifier assigned to the requesting agent by the Kilotest
+          operator. Contact the operator via info@kilotest.com to
+          obtain an identifier and a password.
+        default: research-agent
+
+paths:
+  /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/TargetsResponse'
+
+  /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
+
+  /reportIssue/{issueID}/{timeStamp}/{jobID}:
+    post:
+      operationId: getReportIssue
+      summary: >-
+        Get element-level detail for a specific issue in a specific report
+      description: >-
+        Returns element-level detail for a single issue within a specific
+        report, including which HTML elements exhibit the issue and
+        diagnostic information from each tool that reported it. This is
+        the level at which tool-provided remediation guidance becomes
+        available. The issueID is available in the getReportIssues response.
+      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: Element-level detail for the specified issue
+          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
+
+    TargetsResponse:
+      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": "27.0.0",
   "description": "An ensemble testing service with a focus on accessibility",
   "main": "index.js",
   "scripts": {

package/reportIssues/api.js

@@ -21,11 +21,14 @@ const {
 // Gets facts about an issue.
 const getIssueFacts = (thisHost, agentID, 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,8 +36,8 @@ 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/${agentID}/reportIssue/${issueID}/${timeStamp}/${jobID}`,
+      'for humans': `${thisHost}/reportIssue.html/${issueID}/${timeStamp}/${jobID}`
     }
   };
 };
@@ -72,16 +75,21 @@ exports.response = async args => {
         identifier: 'reportIssues',
         description: 'What issues does the specified report describe?'
       },
+      URLs: {
+        'URL of your request': `${thisHost}/api/${agentID}/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/${agentID}/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}`,

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/targets/api.js

@@ -20,7 +20,8 @@ const thisHost = process.env.THIS_KILOTEST_HOST;
 // FUNCTIONS
 
 // Returns a response to a targets request.
-exports.response = async agentID => {
+exports.response = async args => {
+  const [agentID] = args;
   const availableReports = [];
   // Get the non-hidden logs.
   const targetLogs = await getLogs();
@@ -70,7 +71,7 @@ exports.response = async agentID => {
         'for you': `${thisHost}/api/${agentID}/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.
@@ -87,7 +88,7 @@ exports.response = async agentID => {
         description: 'Give me summary data about each available report.'
       },
       URLs: {
-        'URL of this request': `${thisHost}/api/${agentID}/targets`,
+        'URL of your request': `${thisHost}/api/${agentID}/targets`,
         'equivalent URL for humans': `${thisHost}/targets.html`
       }
     },

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 => {