@jrpool/kilotest 59.1.3 → 60.0.0

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 web standards, including HTML, CSS, ARIA, and WCAG). 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: 59.1.3
+  version: 59.1.4
   license:
     name: MIT
     identifier: MIT
@@ -81,7 +81,7 @@ paths:
                               properties:
                                 identifier:
                                   type: string
-                                  description: timeStamp-jobID identifier of the report.
+                                  description: 'Identifier of the report (example: 260503T0432-x9z).'
                                 completion date and time:
                                   type: string
                                 days since the report was completed:
@@ -165,25 +165,18 @@ paths:
                   - response metadata
                   - response content
                 additionalProperties: false
-  /api/listIssues/{timeStamp}/{jobID}:
+  /api/listIssues/{reportID}:
     get:
       operationId: listIssues
       summary: List basics about the issues in one report
       parameters:
         - in: path
-          name: timeStamp
+          name: reportID
           schema:
             type: string
-            description: 'Timestamp of the report in YYMMDDTHHmm format (example: 260503T0432)'
+            description: 'Identifier of the report (example: 260503T0432-x9z)'
           required: true
-          description: 'Timestamp of the report in YYMMDDTHHmm format (example: 260503T0432)'
-        - in: path
-          name: jobID
-          schema:
-            type: string
-            description: 'Job identifier of the report (example: x9z)'
-          required: true
-          description: 'Job identifier of the report (example: x9z)'
+          description: 'Identifier of the report (example: 260503T0432-x9z)'
       responses:
         '200':
           description: List basics about the issues in one report
@@ -233,7 +226,7 @@ paths:
                               properties:
                                 identifier:
                                   type: string
-                                  description: timeStamp-jobID identifier of the report.
+                                  description: 'Identifier of the report (example: 260503T0432-x9z).'
                                 completion date and time:
                                   type: string
                                 days since the report was completed:
@@ -493,7 +486,7 @@ paths:
                   - response metadata
                   - response content
                 additionalProperties: false
-  /api/listViolators/{issueID}/{timeStamp}/{jobID}:
+  /api/listViolators/{issueID}/{reportID}:
     get:
       operationId: listViolators
       summary: List elements reported as exhibiting one issue
@@ -506,19 +499,12 @@ paths:
           required: true
           description: 'Issue identifier (example: contrastPoor)'
         - in: path
-          name: timeStamp
+          name: reportID
           schema:
             type: string
-            description: 'Timestamp of the report in YYMMDDTHHmm format (example: 260503T0432)'
+            description: 'Identifier of the report (example: 260503T0432-x9z)'
           required: true
-          description: 'Timestamp of the report in YYMMDDTHHmm format (example: 260503T0432)'
-        - in: path
-          name: jobID
-          schema:
-            type: string
-            description: 'Job identifier of the report (example: x9z)'
-          required: true
-          description: 'Job identifier of the report (example: x9z)'
+          description: 'Identifier of the report (example: 260503T0432-x9z)'
       responses:
         '200':
           description: List elements reported as exhibiting one issue
@@ -628,7 +614,7 @@ paths:
                   - response metadata
                   - response content
                 additionalProperties: false
-  /api/listDiagnoses/{catalogIndex}/{issueID}/{timeStamp}/{jobID}:
+  /api/listDiagnoses/{catalogIndex}/{issueID}/{reportID}:
     get:
       operationId: listDiagnoses
       summary: List diagnoses of how one element exhibited one issue
@@ -648,19 +634,12 @@ paths:
           required: true
           description: 'Issue identifier (example: contrastPoor)'
         - in: path
-          name: timeStamp
-          schema:
-            type: string
-            description: 'Timestamp of the report in YYMMDDTHHmm format (example: 260503T0432)'
-          required: true
-          description: 'Timestamp of the report in YYMMDDTHHmm format (example: 260503T0432)'
-        - in: path
-          name: jobID
+          name: reportID
           schema:
             type: string
-            description: 'Job identifier of the report (example: x9z)'
+            description: 'Identifier of the report (example: 260503T0432-x9z)'
           required: true
-          description: 'Job identifier of the report (example: x9z)'
+          description: 'Identifier of the report (example: 260503T0432-x9z)'
       responses:
         '200':
           description: List diagnoses of how one element exhibited one issue
@@ -788,25 +767,18 @@ paths:
                   - response metadata
                   - response content
                 additionalProperties: false
-  /api/getReport/{timeStamp}/{jobID}:
+  /api/getReport/{reportID}:
     get:
       operationId: getReport
       summary: Get one full report in JSON
       parameters:
         - in: path
-          name: timeStamp
+          name: reportID
           schema:
             type: string
-            description: 'Timestamp of the report in YYMMDDTHHmm format (example: 260503T0432)'
+            description: 'Identifier of the report (example: 260503T0432-x9z)'
           required: true
-          description: 'Timestamp of the report in YYMMDDTHHmm format (example: 260503T0432)'
-        - in: path
-          name: jobID
-          schema:
-            type: string
-            description: 'Job identifier of the report (example: x9z)'
-          required: true
-          description: 'Job identifier of the report (example: x9z)'
+          description: 'Identifier of the report (example: 260503T0432-x9z)'
       responses:
         '200':
           description: Get one full report in JSON
@@ -1003,25 +975,18 @@ paths:
                   - response metadata
                   - response content
                 additionalProperties: false
-  /api/requestRetest/{timeStamp}/{jobID}:
+  /api/requestRetest/{reportID}:
     post:
       operationId: requestRetest
       summary: Request that a page be retested
       parameters:
         - in: path
-          name: timeStamp
+          name: reportID
           schema:
             type: string
-            description: 'Timestamp of the latest report about the page in YYMMDDTHHmm format (example: 260503T0432)'
+            description: 'Identifier of the latest report about the page (example: 260503T0432-x9z)'
           required: true
-          description: 'Timestamp of the latest report about the page in YYMMDDTHHmm format (example: 260503T0432)'
-        - in: path
-          name: jobID
-          schema:
-            type: string
-            description: 'Job identifier of the latest report about the page (example: x9z)'
-          required: true
-          description: 'Job identifier of the latest report about the page (example: x9z)'
+          description: 'Identifier of the latest report about the page (example: 260503T0432-x9z)'
       requestBody:
         content:
           application/json:
@@ -1365,7 +1330,8 @@ paths:
                                 type: string
                               report identifier:
                                 anyOf:
-                                  - $ref: '#/components/schemas/ReportIdentifier'
+                                  - type: string
+                                    description: 'Identifier of the report, to pass to listIssues once the report is ready (example: 260503T0432-x9z).'
                                   - type: 'null'
                               how you can check for completion:
                                 type: string
@@ -1390,25 +1356,18 @@ paths:
                   - response metadata
                   - response content
                 additionalProperties: false
-  /api/orderRetest/{timeStamp}/{jobID}:
+  /api/orderRetest/{reportID}:
     post:
       operationId: orderRetest
       summary: Order that a page be retested immediately, without manual approval
       parameters:
         - in: path
-          name: timeStamp
+          name: reportID
           schema:
             type: string
-            description: 'Timestamp of the latest report about the page in YYMMDDTHHmm format (example: 260503T0432)'
+            description: 'Identifier of the latest report about the page (example: 260503T0432-x9z)'
           required: true
-          description: 'Timestamp of the latest report about the page in YYMMDDTHHmm format (example: 260503T0432)'
-        - in: path
-          name: jobID
-          schema:
-            type: string
-            description: 'Job identifier of the latest report about the page (example: x9z)'
-          required: true
-          description: 'Job identifier of the latest report about the page (example: x9z)'
+          description: 'Identifier of the latest report about the page (example: 260503T0432-x9z)'
       requestBody:
         content:
           application/json:
@@ -1519,7 +1478,8 @@ paths:
                                 type: string
                               report identifier:
                                 anyOf:
-                                  - $ref: '#/components/schemas/ReportIdentifier'
+                                  - type: string
+                                    description: 'Identifier of the report, to pass to listIssues once the report is ready (example: 260503T0432-x9z).'
                                   - type: 'null'
                               how you can check for completion:
                                 type: string
@@ -1544,25 +1504,18 @@ paths:
                   - response metadata
                   - response content
                 additionalProperties: false
-  /api/awaitTest/{timeStamp}/{jobID}:
+  /api/awaitTest/{reportID}:
     post:
       operationId: awaitTest
       summary: Wait for a job ordered via orderNewTest or orderRetest to complete
       parameters:
         - in: path
-          name: timeStamp
+          name: reportID
           schema:
             type: string
-            description: 'Timestamp of the ordered job, from the report identifier returned by orderNewTest, in YYMMDDTHHmm format (example: 260503T0432)'
+            description: 'Report identifier returned by orderNewTest or orderRetest (example: 260503T0432-x9z)'
           required: true
-          description: 'Timestamp of the ordered job, from the report identifier returned by orderNewTest, in YYMMDDTHHmm format (example: 260503T0432)'
-        - in: path
-          name: jobID
-          schema:
-            type: string
-            description: 'Job identifier of the ordered job, from the report identifier returned by orderNewTest (example: x9z)'
-          required: true
-          description: 'Job identifier of the ordered job, from the report identifier returned by orderNewTest (example: x9z)'
+          description: 'Report identifier returned by orderNewTest or orderRetest (example: 260503T0432-x9z)'
       requestBody:
         content:
           application/json:
@@ -1631,7 +1584,8 @@ paths:
                           - type: object
                             properties:
                               report identifier:
-                                $ref: '#/components/schemas/ReportIdentifier'
+                                type: string
+                                description: 'Identifier of the report, to pass to listIssues once the report is ready (example: 260503T0432-x9z).'
                             required:
                               - report identifier
                             additionalProperties: false
@@ -1792,7 +1746,7 @@ components:
       properties:
         identifier:
           type: string
-          description: timeStamp-jobID identifier of the report.
+          description: 'Identifier of the report (example: 260503T0432-x9z).'
         completion date and time:
           type: string
         days since the report was completed:
@@ -1882,16 +1836,3 @@ components:
           required:
             - error
           additionalProperties: false
-    ReportIdentifier:
-      type: object
-      properties:
-        timeStamp:
-          type: string
-          description: Timestamp to pass to listIssues once the report is ready.
-        jobID:
-          type: string
-          description: Job identifier to pass to listIssues once the report is ready.
-      required:
-        - timeStamp
-        - jobID
-      additionalProperties: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "59.1.3",
+  "version": "60.0.0",
   "description": "Ensemble testing for front-end web quality",
   "type": "module",
   "main": "index.ts",
@@ -14,7 +14,13 @@
     "test": "c8 node --require ./test/setup.ts --experimental-test-module-mocks --test --test-concurrency=1 --test-randomize '**/*.test.ts'",
     "test:smoke": "node smokeTest.ts",
     "checkinfo": "node checkinfo.ts",
-    "generate": "node scripts/generate-openapi.ts && node scripts/update-versions.ts"
+    "generate": "node scripts/generate-openapi.ts && node scripts/update-versions.ts",
+    "version": "npm run generate",
+    "prepublishOnly": "test \"$(git branch --show-current)\" = main",
+    "postpublish": "npm run publish:lhm",
+    "publish:lhm": "npx -y @lobehub/market-cli plugin update --dir .",
+    "prePR": "node scripts/prePR.ts",
+    "postPR": "node scripts/postPR.ts"
   },
   "repository": {
     "type": "git",

package/routing.test.ts

@@ -68,7 +68,7 @@ test('GET /api/requestNewTest returns an error, not a test-request response', as
 });
 
 test('GET /api/requestRetest returns an error, not a retest-request response', async () => {
-  const result = await get('/api/requestRetest/260101T0001/ct');
+  const result = await get('/api/requestRetest/260101T0001-ct');
   assert.ok(result.body.includes('Invalid service request'));
 });
 

package/scripts/generate-openapi.ts

@@ -1,6 +1,6 @@
 /*
   generate-openapi.ts
-  Generates openapi.yaml from the Kilotest API route table (api/routes.ts) and Zod schemas (api/schemas.ts), keeping the OpenAPI document in sync with schemas.ts’s single source of truth.
+  Generates openapi.yaml from the Kilotest API route table (api/routes.ts) and Zod schemas (api/schemas.ts), keeping the OpenAPI document in sync with schemas.ts’s single source of truth. Also generates openapi-3.0.yaml, an OpenAPI 3.0.3 conversion for registries whose importers do not accept 3.1 documents (currently the RapidAPI Hub, which is updated via its Hub Listing > Definitions > CI/CD > Import OpenAPI upload).
 */
 
 // IMPORTS
@@ -17,6 +17,7 @@ import {version} from '../api/version.ts';
 
 const {license} = pkg;
 const outputPath = path.join(import.meta.dirname, '..', 'openapi.yaml');
+const output30Path = path.join(import.meta.dirname, '..', 'openapi-3.0.yaml');
 
 // FUNCTIONS
 
@@ -52,6 +53,84 @@ const buildPaths = () => {
   });
   return paths;
 };
+// Converts a generated OpenAPI 3.1 document in place to an OpenAPI 3.0.3
+// document: 'const' schemas become single-member 'enum's, type arrays lose
+// their 'null' members and gain 'nullable', 'null'-unioned schemas become
+// 'nullable', and 3.1-only info fields are removed. Nullable unions whose
+// branches cannot be merged into one typed schema gain an extra object-typed
+// nullable branch instead, because 3.0 validators require a 'type' wherever
+// 'nullable' appears.
+const downgrade30 = (document: any) => {
+  document.openapi = '3.0.3';
+  document.info.license = {
+    name: license,
+    url: 'https://github.com/jrpool/kilotest/blob/main/LICENSE'
+  };
+  const refType = (ref: string) => {
+    const match = /^#\/components\/schemas\/(.+)$/.exec(ref);
+    const target = match?.[1] && document.components?.schemas?.[match[1]];
+    return target && typeof target === 'object' ? target.type : null;
+  };
+  const walk = (node: any): void => {
+    if (Array.isArray(node)) {
+      node.forEach(walk);
+      return;
+    }
+    if (!node || typeof node !== 'object') {
+      return;
+    }
+    if ('const' in node) {
+      node.enum = [node.const];
+      delete node.const;
+    }
+    if (Array.isArray(node.type)) {
+      const types = node.type.filter((t: string) => t !== 'null');
+      const hasNull = types.length !== node.type.length;
+      if (types.length === 1) {
+        node.type = types[0];
+      }
+      else {
+        node.oneOf = types.map((t: string) => ({type: t}));
+        delete node.type;
+      }
+      if (hasNull) {
+        node.nullable = true;
+      }
+    }
+    else if (node.type === 'null') {
+      node.type = 'object';
+      node.nullable = true;
+    }
+    if (Array.isArray(node.anyOf)) {
+      const nullIndex = node.anyOf.findIndex(
+        (branch: any) => branch && typeof branch === 'object' && branch.type === 'null'
+      );
+      if (nullIndex !== -1) {
+        const others = node.anyOf.filter((_: any, i: number) => i !== nullIndex);
+        delete node.anyOf;
+        if (others.length === 1 && others[0].$ref) {
+          node.allOf = [others[0]];
+          const type = refType(others[0].$ref);
+          if (type) {
+            node.type = type;
+          }
+          node.nullable = true;
+        }
+        else if (others.length === 1 && others[0].type) {
+          Object.assign(node, others[0]);
+          node.nullable = true;
+        }
+        else {
+          node.anyOf = [...others, {type: 'object', nullable: true}];
+        }
+      }
+    }
+    for (const value of Object.values(node)) {
+      walk(value);
+    }
+  };
+  walk(document);
+};
 // Generates and writes the openapi.yaml file.
 const generate = () => {
   const document = createDocument({
@@ -78,6 +157,9 @@ const generate = () => {
   });
   fs.writeFileSync(outputPath, yaml.dump(document, {noRefs: true, lineWidth: -1}));
   console.log(`Wrote ${outputPath}`);
+  downgrade30(document);
+  fs.writeFileSync(output30Path, yaml.dump(document, {noRefs: true, lineWidth: -1}));
+  console.log(`Wrote ${output30Path}`);
 };
 
 // EXECUTION

package/scripts/postPR.ts

@@ -0,0 +1,89 @@
+/*
+  postPR.ts
+  Finalizes a release after the prePR pull request has been merged: checks out main, pulls, verifies that the merge landed, publishes to npm (the "postpublish" hook then updates the LobeHub listing), deletes the feature branch, and prunes remote-tracking branches. The feature-branch name is read from the marker file written by prePR.ts, or from an optional command-line argument.
+*/
+
+// IMPORTS
+
+import {spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// CONSTANTS
+
+const markerFile = 'kilotest-pr-branch';
+
+// FUNCTIONS
+
+// Runs a command with inherited stdio and throws on failure.
+const run = (command: string, args: string[]): void => {
+  if (spawnSync(command, args, {stdio: 'inherit'}).status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} failed`);
+  }
+};
+// Runs a command and returns its trimmed standard output.
+const capture = (command: string, args: string[]): string => {
+  const result = spawnSync(command, args, {encoding: 'utf8'});
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} failed`);
+  }
+  return result.stdout.trim();
+};
+// Returns the absolute path of a file inside the git directory.
+const gitPath = (name: string): string =>
+  path.join(capture('git', ['rev-parse', '--absolute-git-dir']), name);
+// Exits unless the working tree is clean.
+const requireCleanTree = (): void => {
+  const dirty = capture('git', ['status', '--porcelain']);
+  if (dirty) {
+    console.error(`Working tree is not clean. Commit or stash all changes first:\n${dirty}`);
+    process.exit(1);
+  }
+};
+// Returns the version field of package.json, either from the working tree or from a git ref.
+const versionOf = (ref?: string): string => {
+  const content = ref
+    ? capture('git', ['show', `${ref}:package.json`])
+    : fs.readFileSync('package.json', 'utf8');
+  return JSON.parse(content).version;
+};
+
+// EXECUTION
+
+const marker = gitPath(markerFile);
+const argBranch = process.argv[2] ?? '';
+const branch = argBranch ||
+  (fs.existsSync(marker) ? fs.readFileSync(marker, 'utf8').trim() : '');
+if (!branch) {
+  console.error('No feature branch recorded. Run prePR first, or pass the branch name: npm run postPR -- <branch>');
+  process.exit(1);
+}
+if (branch === 'main') {
+  console.error('Refusing to treat main as the feature branch');
+  process.exit(1);
+}
+if (!capture('git', ['branch', '--list', branch])) {
+  console.error(`Branch ${branch} does not exist locally; it may already have been deleted`);
+  process.exit(1);
+}
+requireCleanTree();
+run('git', ['checkout', 'main']);
+run('git', ['pull', '--ff-only']);
+// Aborts if the pull request has not been merged: under squash-merges the feature branch is never an ancestor of main, so version equality is the merge check.
+const branchVersion = versionOf(branch);
+const mainVersion = versionOf();
+if (branchVersion !== mainVersion) {
+  console.error(`main is at version ${mainVersion} but ${branch} is at ${branchVersion}; merge the pull request first`);
+  process.exit(1);
+}
+run('npm', ['publish']);
+// Branch cleanup is best-effort: deletion must precede pruning, because "git branch -d" checks mergedness against the upstream ref, which pruning would remove.
+const deleted = spawnSync('git', ['branch', '-d', branch], {stdio: 'inherit'});
+if (deleted.status !== 0) {
+  console.warn(`Could not delete ${branch}; delete it manually after confirming the merge`);
+}
+if (spawnSync('git', ['remote', 'prune', 'origin'], {stdio: 'inherit'}).status !== 0) {
+  console.warn('git remote prune origin failed');
+}
+fs.rmSync(marker, {force: true});
+console.log('Release complete');

package/scripts/prePR.ts

@@ -0,0 +1,64 @@
+/*
+  prePR.ts
+  Prepares a release pull request on the current feature branch: verifies a clean working tree, bumps the package version (the npm "version" hook regenerates openapi.yaml, server.json, and lhm.plugin.json), commits and pushes the result, records the branch name for postPR.ts, and prints the remaining manual steps.
+*/
+
+// IMPORTS
+
+import {spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// CONSTANTS
+
+const levels = ['major', 'minor', 'patch'];
+const usage = 'Usage: npm run prePR -- <major|minor|patch>';
+const markerFile = 'kilotest-pr-branch';
+
+// FUNCTIONS
+
+// Runs a command with inherited stdio and throws on failure.
+const run = (command: string, args: string[]): void => {
+  if (spawnSync(command, args, {stdio: 'inherit'}).status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} failed`);
+  }
+};
+// Runs a command and returns its trimmed standard output.
+const capture = (command: string, args: string[]): string => {
+  const result = spawnSync(command, args, {encoding: 'utf8'});
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} failed`);
+  }
+  return result.stdout.trim();
+};
+// Returns the absolute path of a file inside the git directory.
+const gitPath = (name: string): string =>
+  path.join(capture('git', ['rev-parse', '--absolute-git-dir']), name);
+// Exits unless the working tree is clean, so all substantive changes are committed before the version bump.
+const requireCleanTree = (): void => {
+  const dirty = capture('git', ['status', '--porcelain']);
+  if (dirty) {
+    console.error(`Working tree is not clean. Commit or stash all changes first:\n${dirty}`);
+    process.exit(1);
+  }
+};
+
+// EXECUTION
+
+const level = process.argv[2] ?? '';
+if (!levels.includes(level)) {
+  console.error(usage);
+  process.exit(1);
+}
+const branch = capture('git', ['branch', '--show-current']);
+if (!branch || branch === 'main') {
+  console.error('prePR must run on a feature branch, not on main');
+  process.exit(1);
+}
+requireCleanTree();
+run('npm', ['version', level, '--no-git-tag-version']);
+run('git', ['add', '-A']);
+run('git', ['commit', '-m', 'update version and generated files']);
+run('git', ['push', '-u', 'origin', branch]);
+fs.writeFileSync(gitPath(markerFile), `${branch}\n`);
+console.log('Submit a pull request, merge it to main, then run: npm run postPR');

package/server.json

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