@jrpool/kilotest 58.2.0 → 59.0.0

package/linkValidation.test.ts

@@ -41,7 +41,7 @@ const htmlRoutes = [
   '/tutorialAI.html',
   '/tutorialWebComment.html',
   '/tutorialAIComment.html',
-  '/listReports.html',
+  '/listPages.html',
   '/listTopIssues.html',
   '/listIssues.html',
   '/listDiagnoses.html',
@@ -178,7 +178,7 @@ test('Internal links in index.html resolve to expected paths', () => {
   const expectedLinks = [
     '/tutorialWeb.html',
     '/tutorialAI.html',
-    '/listReports.html',
+    '/listPages.html',
     '/listTopIssues.html',
     '/manage.html',
     '/mcp',

package/llms-full.txt

@@ -59,8 +59,8 @@ In the marketplace for MCP servers that test for front-end quality, all servers
 Kilotest offers a comprehensive suite of capabilities to users via its web UI:
 
 - [Home page](https://kilotest.com/)
-- [Get summary test results for all tested pages](https://kilotest.com/listReports.html)
-- Get statistics about issues reported in one report: `https://kilotest.com/listIssues.html/{timeStamp}/{jobID}`
+- [Get a list of all tested pages, each linked to its latest report](https://kilotest.com/listPages.html)
+- Get statistics about issues reported in one report, and a history of all reports about the same page: `https://kilotest.com/listIssues.html/{timeStamp}/{jobID}`
 - Get details about one issue reported in one report: `https://kilotest.com/listViolators.html/{issueID}/{timeStamp}/{jobID}`
 - Get diagnoses by rule engines of rule violations for one HTML element exhibiting one issue in one report: `https://kilotest.com/listDiagnoses.html/{issueID}/{timeStamp}/{jobID}/{catalogIndex}`
 - [Recommend the testing of a not-yet-tested page](https://kilotest.com/requestNewTestForm.html)
@@ -76,19 +76,19 @@ In the specifications below, the term `report` refers to the records of one sess
 
 Kilotest offers these tools:
 
-- `listReports`
+- `listPages`
   - method: `GET`
-  - purpose: list all available reports
-  - path: `/api/listReports`
+  - purpose: list all tested pages, each with its latest report and its number of reports
+  - path: `/api/listPages`
   - caveat: Cached results are likely to be stale and should not be used
 - `listIssues`
   - method: `GET`
-  - purpose: list all issues in one report
+  - purpose: list all issues in one report, and all reports about the same page, from oldest to latest
   - path: `/api/listIssues/{timeStamp}/{jobID}`
   - parameters
     - `timeStamp`: initial segment of report identifier
     - `jobID`: final segment of report identifier
-  - source of parameters: response to a `listReports` request
+  - source of parameters: response to a `listPages` request, or the history of reports about the page in the response to a `listIssues` request
 - `listViolators`
   - method: `GET`
   - purpose: list all elements exhibiting one issue in one report
@@ -173,8 +173,8 @@ When you request a test or a retest:
   - approval followed by the requested testing
   - rejection
 - how to confirm approval
-  - check test completion by calling `listReports` and looking for the page and completion date in the list
-  - you advise the user to check in approximately 1 day for the test results on the Kilotest website, starting at `https://kilotest.com/listReports.html`
+  - check test completion by calling `listPages` and looking for the page and the completion date of its latest report in the list
+  - you advise the user to check in approximately 1 day for the test results on the Kilotest website, starting at `https://kilotest.com/listPages.html`
 
 For immediate testing without waiting for manual approval, use `orderNewTest` or `orderRetest` instead of `requestNewTest` or `requestRetest`. Each enqueues the job right away and returns a report identifier along with a question about whether to wait for completion. To wait, call `awaitTest` with that identifier; it blocks until the report is ready, the job fails, or a maximum wait time elapses. To check later instead, call `listIssues` with the same identifier.
 

package/llms.txt

@@ -4,8 +4,8 @@ Kilotest helps language models and AI platforms to give thorough, accurate and t
 
 ## API
 
-- [List all available reports](/api/listReports) (`GET`)
-- List all issues in one report: `/api/listIssues/{timeStamp}/{jobID}` (`GET`)
+- [List all tested pages, each with its latest report](/api/listPages) (`GET`)
+- List all issues in one report, and all reports about the same page: `/api/listIssues/{timeStamp}/{jobID}` (`GET`)
 - List all elements exhibiting one issue in one report: `/api/listViolators/{issueID}/{timeStamp}/{jobID}` (`GET`)
 - List all diagnoses of one element exhibiting one issue in one report: `/api/listDiagnoses/{catalogIndex}/{issueID}/{timeStamp}/{jobID}` (`GET`)
 - Get one full report in JSON: `/api/getReport/{timeStamp}/{jobID}` (`GET`)
@@ -22,8 +22,8 @@ Kilotest helps language models and AI platforms to give thorough, accurate and t
 
 ## Web UI
 
-- [List all available reports](https://kilotest.com/listReports.html)
-- List all issues in one report: `https://kilotest.com/listIssues.html/{timeStamp}/{jobID}`
+- [List all tested pages, each linked to its latest report](https://kilotest.com/listPages.html)
+- List all issues in one report, and all reports about the same page: `https://kilotest.com/listIssues.html/{timeStamp}/{jobID}`
 - List all elements exhibiting one issue in one report: `https://kilotest.com/listViolators.html/{issueID}/{timeStamp}/{jobID}`
 - List all diagnoses of one element exhibiting one issue in one report: `https://kilotest.com/listDiagnoses.html/{issueID}/{timeStamp}/{jobID}/{catalogIndex}`
 - Get one full report in JSON: `https://kilotest.com/fullReport.json/{timeStamp}/{jobID}`

package/mcp.test.ts

@@ -43,7 +43,7 @@ test('createMCPServer registers all 12 tools', () => {
   assert.equal(toolNames.length, 12);
   assert.deepEqual(toolNames, [
     'getKilotestOverview',
-    'listReports',
+    'listPages',
     'listIssues',
     'listViolators',
     'listDiagnoses',
@@ -97,14 +97,14 @@ test('client receives instructions, server description, and the overview resourc
   await server.close();
 });
 
-test('listReports handler returns content and structuredContent', async () => {
+test('listPages handler returns content and structuredContent', async () => {
   const server = createMCPServer();
-  const countBefore = getToolCallCount('listReports');
-  const result = await (server as any)._registeredTools.listReports.handler({});
+  const countBefore = getToolCallCount('listPages');
+  const result = await (server as any)._registeredTools.listPages.handler({});
   assert.ok(result.content);
   assert.equal(result.content[0].type, 'text');
   assert.ok(result.structuredContent);
-  assert.equal(getToolCallCount('listReports'), countBefore + 1);
+  assert.equal(getToolCallCount('listPages'), countBefore + 1);
 });
 
 test('listIssues handler returns content and structuredContent for a valid report', async () => {
@@ -369,7 +369,7 @@ test('handleMCP lists all 12 tools via tools/list', async () => {
     assert.equal(toolNames.length, 12);
     assert.deepEqual(toolNames, [
       'getKilotestOverview',
-      'listReports',
+      'listPages',
       'listIssues',
       'listViolators',
       'listDiagnoses',
@@ -387,12 +387,12 @@ test('handleMCP lists all 12 tools via tools/list', async () => {
   }
 });
 
-test('handleMCP executes listReports tool via tools/call', async () => {
+test('handleMCP executes listPages tool via tools/call', async () => {
   const server = await startMCPServer();
   try {
     const port = server.address().port;
     const res = await sendMCPRequest(port, 'tools/call', {
-      name: 'listReports',
+      name: 'listPages',
       arguments: {}
     }, 3);
     assert.equal(res.statusCode, 200);

package/mcp.ts

@@ -9,7 +9,7 @@ import type {IncomingMessage, ServerResponse} from 'node:http';
 import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
 import {StreamableHTTPServerTransport} from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import * as getReportAPI from './api/getReport.ts';
-import * as listReportsAPI from './api/listReports.ts';
+import * as listPagesAPI from './api/listPages.ts';
 import * as listIssuesAPI from './api/listIssues.ts';
 import * as listViolatorsAPI from './api/listViolators.ts';
 import * as listDiagnosesAPI from './api/listDiagnoses.ts';
@@ -33,7 +33,7 @@ import {
   orderNewTestSchema,
   orderRetestSchema,
   awaitTestSchema,
-  listReportsResponseSchema,
+  listPagesResponseSchema,
   listIssuesResponseSchema,
   listViolatorsResponseSchema,
   listDiagnosesResponseSchema,
@@ -54,15 +54,15 @@ export const mcpPath = '/mcp';
 // description, in the server instructions, and in the getKilotestOverview tool description,
 // because some MCP clients do not propagate server-level instructions or the server
 // description to their models.
-const sharedContext = 'Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as report, then issue, then violator element, then diagnosis.';
+const sharedContext = 'Kilotest tests web pages for front-end quality (accessibility, usability, and standards conformity); results are organized as tested page, then report, then issue, then violator element, then diagnosis.';
 
 // Detailed overview of the Kilotest domain, data hierarchy, and tool workflow, returned by
 // the getKilotestOverview tool and served as the docs://kilotest/overview resource.
 const kilotestOverview = [
   'Kilotest tests web pages for front-end quality: accessibility, usability, and standards conformity.',
   'Kilotest integrates an ensemble of twelve independent rule engines to test a web page and stores the results as a structured report.',
-  'Results are organized as a hierarchy. A report contains issues. An issue has violators: elements of the tested page reported as exhibiting the issue. A violator has diagnoses: explanations from rule engines of how the element exhibited the issue.',
-  'Typical workflow: call the listReports tool to learn whether a report about the page already exists. If it does, drill down with the listIssues, listViolators, and listDiagnoses tools, or retrieve the entire report with the getReport tool. If no report exists, request a test with the requestNewTest tool. If the latest report is obsolete, request a retest with the requestRetest tool.',
+  'Results are organized as a hierarchy. A tested page has one or more reports, from oldest to latest. A report contains issues. An issue has violators: elements of the tested page reported as exhibiting the issue. A violator has diagnoses: explanations from rule engines of how the element exhibited the issue.',
+  'Typical workflow: call the listPages tool to learn whether the page has been tested. If it has, drill down from its latest report with the listIssues, listViolators, and listDiagnoses tools, or retrieve the entire report with the getReport tool. The listIssues output also lists all reports about the same page, so you can examine earlier reports. If the page has not been tested, request a test with the requestNewTest tool. If the latest report is obsolete, request a retest with the requestRetest tool.',
   'For immediate, automatically approved testing, use the orderNewTest tool (for a new page) or the orderRetest tool (for a page with an obsolete report) instead of requestNewTest or requestRetest. Each enqueues the job right away, with no manual approval step, and returns a report identifier along with a question about whether to wait for completion. To wait, call the awaitTest tool with that identifier; it blocks until the report is ready, the job fails, or a maximum wait time elapses. To check later instead, call the listIssues tool with the same identifier.',
   'More documentation is available at https://kilotest.com/llms.txt and https://kilotest.com/llms-full.txt.'
 ].join('\n\n');
@@ -81,7 +81,7 @@ export const createMCPServer = (): McpServer => {
     description: 'Tools that test web pages for front-end quality (accessibility, usability, and standards conformity) and make test results available'
   },
   {
-    instructions: `${sharedContext} Use the listReports tool to start. If it shows that there is a report available about the page you want facts about, drill down with the listIssues, listViolators, and listDiagnoses tools. If not, use the requestNewTest tool to request that the page be tested, or the orderNewTest tool for immediate, automatically approved testing. If the latest report about the page is obsolete, use the requestRetest tool to request that the page be retested, or the orderRetest tool for immediate, automatically approved retesting. For detailed documentation, call the getKilotestOverview tool.`
+    instructions: `${sharedContext} Use the listPages tool to start. If it shows that the page you want facts about has been tested, drill down from its latest report with the listIssues, listViolators, and listDiagnoses tools. If not, use the requestNewTest tool to request that the page be tested, or the orderNewTest tool for immediate, automatically approved testing. If the latest report about the page is obsolete, use the requestRetest tool to request that the page be retested, or the orderRetest tool for immediate, automatically approved retesting. For detailed documentation, call the getKilotestOverview tool.`
   });
   server.registerTool(
     'getKilotestOverview',
@@ -102,13 +102,13 @@ export const createMCPServer = (): McpServer => {
     }
   );
   server.registerTool(
-    'listReports',
+    'listPages',
     {
-      description: toolDoc('Provide basics about all available reports.'),
+      description: toolDoc('Provide basics about all tested pages, including how to get details about the latest report about each.'),
       inputSchema: {},
-      outputSchema: listReportsResponseSchema,
+      outputSchema: listPagesResponseSchema,
       annotations: {
-        title: toolDoc('Provide basics about all available reports.'),
+        title: toolDoc('Provide basics about all tested pages, including how to get details about the latest report about each.'),
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,
@@ -116,19 +116,19 @@ export const createMCPServer = (): McpServer => {
       }
     },
     async () => {
-      const result = await listReportsAPI.response();
-      await recordMetric('mcpToolCalls', 'listReports');
+      const result = await listPagesAPI.response();
+      await recordMetric('mcpToolCalls', 'listPages');
       return {content: [{type: 'text', text: JSON.stringify(result)}], structuredContent: result};
     }
   );
   server.registerTool(
     'listIssues',
     {
-      description: toolDoc('Provide details about one report, including basics about the issues reported in it.'),
+      description: toolDoc('Provide details about one report, including basics about the issues reported in it and the history of all reports about the same page.'),
       inputSchema: listIssuesSchema,
       outputSchema: listIssuesResponseSchema,
       annotations: {
-        title: toolDoc('Provide details about one report, including basics about the issues reported in it.'),
+        title: toolDoc('Provide details about one report, including basics about the issues reported in it and the history of all reports about the same page.'),
         readOnlyHint: true,
         idempotentHint: true,
         destructiveHint: false,

package/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 info:
   title: Kilotest API
   description: 'Kilotest is an ensemble testing and reporting service for front-end web quality. It uses an ensemble of 12 rule engines to test web pages for front-end quality (accessibility, usability, and standards conformity). Kilotest acts as a web server for human users, an MCP server for AI platforms, and an API for programmatic access. With this API you can request that a page be tested or retested, discover available reports, incrementally retrieve facts from a report: from what reports are available, to what issues were reported in one report, to what elements violated one issue, to what diagnoses rule engines gave for one violation.'
-  version: 57.2.0
+  version: 58.2.7
   license:
     name: MIT
     identifier: MIT
@@ -15,13 +15,13 @@ servers:
     description: Kilotest production server
 security: []
 paths:
-  /api/listReports:
+  /api/listPages:
     get:
-      operationId: listReports
-      summary: List all available reports
+      operationId: listPages
+      summary: List all tested pages
       responses:
         '200':
-          description: List all available reports
+          description: List all tested pages
           content:
             application/json:
               schema:
@@ -58,20 +58,11 @@ paths:
                   response content:
                     type: object
                     properties:
-                      basics about all available reports:
+                      basics about all tested pages:
                         type: array
                         items:
                           type: object
                           properties:
-                            identifier:
-                              type: string
-                              description: timeStamp-jobID identifier of the report.
-                            completion date and time:
-                              type: string
-                            days since the report was completed:
-                              type:
-                                - number
-                                - 'null'
                             tested web page:
                               type: object
                               properties:
@@ -83,9 +74,26 @@ paths:
                                 - description
                                 - URL
                               additionalProperties: false
-                            whether a later report about the same page exists:
-                              type: boolean
-                            how to get details about the report:
+                            number of reports about the page:
+                              type: number
+                            basics about the latest report:
+                              type: object
+                              properties:
+                                identifier:
+                                  type: string
+                                  description: timeStamp-jobID identifier of the report.
+                                completion date and time:
+                                  type: string
+                                days since the report was completed:
+                                  type:
+                                    - number
+                                    - 'null'
+                              required:
+                                - identifier
+                                - completion date and time
+                                - days since the report was completed
+                              additionalProperties: false
+                            how to get details about the latest report:
                               type: object
                               properties:
                                 method:
@@ -97,16 +105,14 @@ paths:
                                 - method
                                 - URL
                               additionalProperties: false
-                            web users can get details about the report at:
+                            web users can get details about the latest report at:
                               type: string
                           required:
-                            - identifier
-                            - completion date and time
-                            - days since the report was completed
                             - tested web page
-                            - whether a later report about the same page exists
-                            - how to get details about the report
-                            - web users can get details about the report at
+                            - number of reports about the page
+                            - basics about the latest report
+                            - how to get details about the latest report
+                            - web users can get details about the latest report at
                           additionalProperties: false
                       how to request that a page with no report be tested:
                         type: object
@@ -147,7 +153,7 @@ paths:
                           - URL
                         additionalProperties: false
                     required:
-                      - basics about all available reports
+                      - basics about all tested pages
                       - how to request that a page with no report be tested
                       - how a web user can request that the page be tested
                     additionalProperties: false
@@ -219,6 +225,53 @@ paths:
                     properties:
                       basics about the report:
                         $ref: '#/components/schemas/ReportBasicsOrError'
+                      history of reports about the page:
+                        anyOf:
+                          - type: array
+                            items:
+                              type: object
+                              properties:
+                                identifier:
+                                  type: string
+                                  description: timeStamp-jobID identifier of the report.
+                                completion date and time:
+                                  type: string
+                                days since the report was completed:
+                                  type:
+                                    - number
+                                    - 'null'
+                                whether it is the oldest report about the page:
+                                  type: boolean
+                                whether it is the latest report about the page:
+                                  type: boolean
+                                whether it is the report described in this response:
+                                  type: boolean
+                                how to get details about the report:
+                                  type: object
+                                  properties:
+                                    method:
+                                      type: string
+                                      const: GET
+                                    URL:
+                                      type: string
+                                  required:
+                                    - method
+                                    - URL
+                                  additionalProperties: false
+                                web users can get details about the report at:
+                                  type: string
+                              required:
+                                - identifier
+                                - completion date and time
+                                - days since the report was completed
+                                - whether it is the oldest report about the page
+                                - whether it is the latest report about the page
+                                - whether it is the report described in this response
+                                - how to get details about the report
+                                - web users can get details about the report at
+                              additionalProperties: false
+                          - type: 'null'
+                        description: All reports about the same page, from oldest to latest, or null if the report is unavailable.
                       details about the report:
                         anyOf:
                           - type: object
@@ -424,6 +477,7 @@ paths:
                           - type: 'null'
                     required:
                       - basics about the report
+                      - history of reports about the page
                       - details about the report
                       - how to request that the page be retested
                       - how a web user can request that the page be retested
@@ -822,7 +876,7 @@ paths:
               properties:
                 description:
                   type: string
-                  description: 1- to 100-character description of the page conforming to the naming convention used in the listReports output
+                  description: 1- to 100-character description of the page conforming to the naming convention used in the listPages output
                 URL:
                   type: string
                   description: 12- to 300-character URL of the page, including the https:// scheme and any query
@@ -860,7 +914,7 @@ paths:
                         properties:
                           description:
                             type: string
-                            description: 1- to 100-character description of the page conforming to the naming convention used in the listReports output
+                            description: 1- to 100-character description of the page conforming to the naming convention used in the listPages output
                           URL:
                             type: string
                             description: 12- to 300-character URL of the page, including the https:// scheme and any query
@@ -1193,7 +1247,7 @@ paths:
               properties:
                 description:
                   type: string
-                  description: 1- to 100-character description of the page conforming to the naming convention used in the listReports output
+                  description: 1- to 100-character description of the page conforming to the naming convention used in the listPages output
                 URL:
                   type: string
                   description: 12- to 300-character URL of the page, including the https:// scheme and any query
@@ -1231,7 +1285,7 @@ paths:
                         properties:
                           description:
                             type: string
-                            description: 1- to 100-character description of the page conforming to the naming convention used in the listReports output
+                            description: 1- to 100-character description of the page conforming to the naming convention used in the listPages output
                           URL:
                             type: string
                             description: 12- to 300-character URL of the page, including the https:// scheme and any query

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "58.2.0",
+  "version": "59.0.0",
   "description": "Ensemble testing for front-end web quality",
   "type": "module",
   "main": "index.ts",

package/routing.test.ts

@@ -77,10 +77,10 @@ test('GET /api/requestFeature returns an error, not a feature-request response',
   assert.ok(result.body.includes('Invalid service request'));
 });
 
-test('GET /api/listReports returns a valid JSON response', async () => {
-  const result = await get('/api/listReports');
+test('GET /api/listPages returns a valid JSON response', async () => {
+  const result = await get('/api/listPages');
   const body = JSON.parse(result.body);
-  assert.equal(body['tool name'], 'listReports');
-  const reports = body['response content']['basics about all available reports'];
-  assert.equal(reports.length, 8);
+  assert.equal(body['tool name'], 'listPages');
+  const pages = body['response content']['basics about all tested pages'];
+  assert.equal(pages.length, 7);
 });

package/server.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/jrpool/kilotest",
     "source": "github"
   },
-  "version": "57.0.0",
+  "version": "59.0.0",
   "remotes": [
     {
       "type": "streamable-http",

package/sitemap.xml

@@ -1,7 +1,7 @@
 <!-- sitemap.xml -->
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url><loc>https://kilotest.com/</loc></url>
-  <url><loc>https://kilotest.com/listReports.html</loc></url>
+  <url><loc>https://kilotest.com/listPages.html</loc></url>
   <url><loc>https://kilotest.com/listTopIssues.html</loc></url>
   <url><loc>https://kilotest.com/requestNewTestForm.html</loc></url>
   <url><loc>https://kilotest.com/manage.html</loc></url>

package/smokeTest.ts

@@ -14,10 +14,10 @@ import {mcpPath} from './mcp.ts';
 // Concrete paths matching each wildcard pattern in the routes table, for smoke testing.
 const concretePaths: Record<string, Record<string, string>> = {
   GET: {
-    '*.html*': '/listReports.html',
+    '*.html*': '/listPages.html',
     '/': '/',
     '/api-docs': '/api-docs',
-    '/api/*': '/api/listReports',
+    '/api/*': '/api/listPages',
     '/capability.md': '/capability.md',
     '/favicon.*': '/favicon.ico',
     '/fullReport.json/*': '/fullReport.json/260101T0000/mix',

package/style.css

@@ -180,21 +180,21 @@ ul {
 ul.pseudoTopLevel {
   list-style: disc;
 }
-ul.nav {
-  padding-inline-start: 0.25rem;
-}
-ul.nav li, ul.headed li {
-  list-style: none;
-}
-ul.nav li > a {
+ul.links li > a, ul.nav li > a {
   display: block;
   box-sizing: border-box;
   min-height: 44px;
   min-width: 44px;
   margin-right: 1rem;
-  padding-left: 1rem;
+  padding-left: 0.25rem;
   padding-top: 0.5rem;
 }
+ul.nav {
+  padding-inline-start: 0.25rem;
+}
+ul.nav li, ul.headed li {
+  list-style: none;
+}
 ul.whereList {
   margin-left: 2rem;
   padding-left: 0;

package/test/fixtures/buildFixtures.ts

@@ -226,7 +226,7 @@ const main = async () => {
     preventedReport
   );
 
-  // Fixture 7: hidden. A report placed in hiddenReports/ instead of reports/, so it must not appear in listReports, listIssues, listViolators, listDiagnoses, or getReport API responses.
+  // Fixture 7: hidden. A report placed in hiddenReports/ instead of reports/, so it must not appear in listPages, listIssues, listViolators, listDiagnoses, or getReport API responses.
   const hiddenCatalog = {
     '0': catalogItem('A', 'Secret link', '/html/body/a[1]', '5:10:60:20')
   };