@jrpool/kilotest 46.1.0 → 47.0.1

package/openapi.yaml

@@ -69,7 +69,9 @@ paths:
                             completion date and time:
                               type: string
                             days since the report was completed:
-                              type: number
+                              type:
+                                - number
+                                - 'null'
                             tested web page:
                               type: object
                               properties:
@@ -372,50 +374,54 @@ paths:
                             additionalProperties: false
                           - type: 'null'
                       basics about all issues reported in the report:
-                        type: array
-                        items:
-                          type: object
-                          properties:
-                            identifier:
-                              type: string
-                            summary:
-                              type: string
-                            impact on a user:
-                              type: string
-                            priority:
-                              type: string
-                              enum:
-                                - lowest
-                                - low
-                                - high
-                                - highest
-                            rule engines with any violations belonging to the issue:
-                              type: array
-                              items:
-                                type: string
-                            how to get details about the issue:
+                        anyOf:
+                          - type: array
+                            items:
                               type: object
                               properties:
-                                method:
+                                identifier:
                                   type: string
-                                  const: GET
-                                URL:
+                                summary:
+                                  type: string
+                                impact on a user:
+                                  type: string
+                                priority:
+                                  type: string
+                                  enum:
+                                    - lowest
+                                    - low
+                                    - high
+                                    - highest
+                                rule engines with any violations belonging to the issue:
+                                  type: array
+                                  items:
+                                    type:
+                                      - string
+                                      - 'null'
+                                how to get details about the issue:
+                                  type: object
+                                  properties:
+                                    method:
+                                      type: string
+                                      const: GET
+                                    URL:
+                                      type: string
+                                  required:
+                                    - method
+                                    - URL
+                                  additionalProperties: false
+                                web users can get details about the issue at:
                                   type: string
                               required:
-                                - method
-                                - URL
+                                - identifier
+                                - summary
+                                - impact on a user
+                                - priority
+                                - rule engines with any violations belonging to the issue
+                                - how to get details about the issue
+                                - web users can get details about the issue at
                               additionalProperties: false
-                            web users can get details about the issue at:
-                              type: string
-                          required:
-                            - identifier
-                            - summary
-                            - impact on a user
-                            - priority
-                            - rule engines with any violations belonging to the issue
-                            - how to get details about the issue
-                            - web users can get details about the issue at
-                          additionalProperties: false
+                          - type: 'null'
                     required:
                       - basics about the report
                       - details about the report
@@ -514,14 +520,17 @@ paths:
                               - rule engines reporting violations belonging to the issue
                             additionalProperties: false
                           - type: 'null'
-                      basics about all elements reported as exhibiting the issue:
+                      basics about all elements exhibiting the issue:
                         anyOf:
                           - type: array
                             items:
                               type: object
                               properties:
                                 identifier:
-                                  type: string
+                                  description: Catalog index of the element in the report; a string or number, copied verbatim.
+                                  type:
+                                    - string
+                                    - number
                                 tag name:
                                   description: Copied from the report catalog entry; type not guaranteed.
                                 inner text:
@@ -555,7 +564,7 @@ paths:
                       - basics about the report
                       - basics about the issue
                       - details about the issue
-                      - basics about all elements reported as exhibiting the issue
+                      - basics about all elements exhibiting the issue
                     additionalProperties: false
                 required:
                   - tool collection
@@ -683,31 +692,33 @@ paths:
                           - type: 'null'
                       diagnoses of how the element exhibited the issue:
                         anyOf:
-                          - type: array
-                            items:
-                              type: object
-                              properties:
-                                identifier of the violated rule:
-                                  description: Copied from the report instance (ruleID); type not guaranteed.
-                                description of the violation:
-                                  description: Copied from the report instance (what); type not guaranteed.
-                                severity of the violation on a 0-to-3 scale:
-                                  description: Copied from the report instance (ordinalSeverity); type not guaranteed.
-                                count of violations of the rule by the element:
-                                  type: number
-                              required:
-                                - identifier of the violated rule
-                                - description of the violation
-                                - severity of the violation on a 0-to-3 scale
-                                - count of violations of the rule by the element
-                              additionalProperties: false
-                          - type: object
-                            properties:
-                              error:
-                                type: string
-                            required:
-                              - error
-                            additionalProperties: false
+                          - anyOf:
+                              - type: array
+                                items:
+                                  type: object
+                                  properties:
+                                    identifier of the violated rule:
+                                      description: Copied from the report instance (ruleID); type not guaranteed.
+                                    description of the violation:
+                                      description: Copied from the report instance (what); type not guaranteed.
+                                    severity of the violation on a 0-to-3 scale:
+                                      description: Copied from the report instance (ordinalSeverity); type not guaranteed.
+                                    count of violations of the rule by the element:
+                                      type: number
+                                  required:
+                                    - identifier of the violated rule
+                                    - description of the violation
+                                    - severity of the violation on a 0-to-3 scale
+                                    - count of violations of the rule by the element
+                                  additionalProperties: false
+                              - type: object
+                                properties:
+                                  error:
+                                    type: string
+                                required:
+                                  - error
+                                additionalProperties: false
+                          - type: 'null'
                     required:
                       - basics about the report
                       - basics about the issue
@@ -910,8 +921,25 @@ paths:
                               - page to be tested
                               - reason why the page should be tested
                             additionalProperties: false
+                      disposition of your request:
+                        anyOf:
+                          - type: object
+                            properties:
+                              what happens next:
+                                type: string
+                              how you can check for completion:
+                                type: string
+                              how a web user can check for completion:
+                                type: string
+                            required:
+                              - what happens next
+                              - how you can check for completion
+                              - how a web user can check for completion
+                            additionalProperties: false
+                          - type: 'null'
                     required:
                       - details about your request
+                      - disposition of your request
                     additionalProperties: false
                 required:
                   - tool collection
@@ -1031,8 +1059,25 @@ paths:
                               - page to be retested
                               - reason why the page should be retested
                             additionalProperties: false
+                      disposition of your request:
+                        anyOf:
+                          - type: object
+                            properties:
+                              what happens next:
+                                type: string
+                              how you can check for completion:
+                                type: string
+                              how a web user can check for completion:
+                                type: string
+                            required:
+                              - what happens next
+                              - how you can check for completion
+                              - how a web user can check for completion
+                            additionalProperties: false
+                          - type: 'null'
                     required:
                       - details about your request
+                      - disposition of your request
                     additionalProperties: false
                 required:
                   - tool collection
@@ -1263,7 +1308,9 @@ components:
         completion date and time:
           type: string
         days since the report was completed:
-          type: number
+          type:
+            - number
+            - 'null'
         tested web page:
           type: object
           properties:

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "46.1.0",
+  "version": "47.0.1",
   "description": "Ensemble testing for front-end web quality",
-  "main": "index.js",
+  "type": "module",
+  "main": "index.ts",
   "engines": {
     "node": ">=24.16.0"
   },
   "scripts": {
-    "start": "node index",
+    "start": "node index.ts",
+    "typecheck": "tsc --noEmit",
     "lint": "npx eslint && out=$(npx markdownlint-cli2 2>&1); code=$?; if [ $code -ne 0 ]; then echo \"$out\"; exit $code; fi",
-    "test": "c8 node --require ./test/setup.cjs --test --test-concurrency=1 --test-timeout=100 --test-randomize",
-    "test:smoke": "node smokeTest",
-    "checkinfo": "node checkinfo",
-    "generate:openapi": "node scripts/generate-openapi"
+    "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:openapi": "node scripts/generate-openapi.ts"
   },
   "repository": {
     "type": "git",
@@ -45,12 +47,16 @@
     "@eslint/json": "*",
     "@eslint/markdown": "*",
     "@redocly/cli": "*",
+    "@types/node": "*",
     "c8": "*",
     "eslint": "*",
     "globals": "*",
     "js-yaml": "*",
-    "markdownlint-cli2": "*",
+    "markdownlint-cli2": "^0.23.2",
     "node-html-parser": "*",
+    "testaro": "*",
+    "typescript": "*",
+    "typescript-eslint": "*",
     "zod-openapi": "*"
   },
   "allowScripts": {
@@ -58,23 +64,34 @@
   },
   "c8": {
     "all": true,
+    "extension": [
+      ".js",
+      ".cjs",
+      ".mjs",
+      ".ts",
+      ".tsx",
+      ".jsx",
+      ".cts",
+      ".mts"
+    ],
     "reporter": [
       "text",
       "html"
     ],
     "include": [
-      "index.js",
-      "mcp.js",
-      "alerts.js",
-      "util.js",
-      "api/**/*.js",
-      "web/**/*.js"
+      "index.ts",
+      "mcp.ts",
+      "alerts.ts",
+      "balances.ts",
+      "util.ts",
+      "api/**/*.{js,ts,cts}",
+      "web/**/*.{js,ts,cts}"
     ],
     "exclude": [
       "coverage/**",
       "test{,s}/**",
       "test{,-*}.{js,cjs,mjs}",
-      "**/*{.,-}test.{js,cjs,mjs}",
+      "**/*{.,-}test.{js,cjs,mjs,ts}",
       "**/__tests__/**",
       "scripts/**"
     ],
@@ -83,5 +100,8 @@
     "statements": 100,
     "functions": 100,
     "branches": 100
+  },
+  "overrides": {
+    "smol-toml": "^1.8.0"
   }
 }

package/pm2.config.cjs

@@ -0,0 +1,29 @@
+/*
+  pm2.config.cjs
+  PM2 process configuration for Kilotest. The .cjs extension is required: PM2
+  loads configuration files with require() (Common.parseConfig in pm2's
+  lib/Common.js), which cannot load ES modules. A .js or .mjs name would fail
+  with ERR_REQUIRE_ESM in this type:module package.
+*/
+module.exports = {
+  apps: [
+    {
+      name: 'kilotest',
+      // index.ts cannot be the PM2 script: its autostart guard (import.meta.main) is
+      // false inside PM2's process container, so the server would never start.
+      script: 'serve.ts',
+      // PM2 maps the .ts extension to the bun interpreter, so node must be specified explicitly.
+      interpreter: 'node',
+      instances: 1,
+      autorestart: true,
+      watch: false,
+      max_memory_restart: '500M',
+      time: true,
+      env: {
+        NODE_ENV: 'production',
+        BASE_PATH: '/',
+        DEMO_SSE_DELAY_MS: '100'
+      }
+    }
+  ]
+};

package/{routes.test.js → routes.test.ts}

@@ -1,13 +1,13 @@
 /*
-  routes.test.js
+  routes.test.ts
   Tests for the centralized routes table exported from index.js.
 */
 
 // IMPORTS
 
-const {test} = require('node:test');
-const assert = require('node:assert/strict');
-const {routes} = require('./index');
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {routes} from './index.ts';
 
 // TESTS
 
@@ -43,12 +43,12 @@ test('routes POST includes all known POST paths', () => {
   const required = [
     '/mcp',
     '/requestTest.html',
-    '/recAction.html',
+    '/requestAction.html',
     '/reannotate.html',
     '/renewWCAG.html',
     '/worker/job',
     '/worker/report',
-    '/tutorialComment.html'
+    '/tutorialWebComment.html'
   ];
   for (const path of required) {
     assert.ok(routes.POST.includes(path), `routes.POST missing ${path}`);
@@ -58,7 +58,8 @@ test('routes POST includes all known POST paths', () => {
 test('routes GET includes wildcard patterns for dynamic paths', () => {
   assert.ok(routes.GET.some(p => p.includes('fullReport.json')));
   assert.ok(routes.GET.some(p => p.includes('/api/')));
-  assert.ok(routes.GET.some(p => p.includes('tutorial/images')));
+  assert.ok(routes.GET.some(p => p.includes('tutorialWeb/images')));
+  assert.ok(routes.GET.some(p => p.includes('tutorialAI/images')));
   assert.ok(routes.GET.some(p => p.includes('favicon')));
   assert.ok(routes.GET.some(p => p.includes('.html')));
 });

package/{routing.test.js → routing.test.ts}

@@ -1,15 +1,14 @@
 /*
-  routing.test.js
+  routing.test.ts
   Integration tests for HTTP routing in index.js, verifying that POST-only API services reject GET requests.
 */
 
 // IMPORTS
 
-const {test, before, after} = require('node:test');
-const assert = require('node:assert/strict');
-const path = require('node:path');
-const http = require('node:http');
-const {requestHandler} = require('./index');
+import {test, before, after} from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import {requestHandler} from './index.ts';
 
 // CONSTANTS
 
@@ -18,12 +17,12 @@ const port = 3999;
 // SETUP AND TEARDOWN
 
 const savedDBDir = process.env.DB_DIR;
-let server;
+let server: http.Server;
 
 before(async () => {
-  process.env.DB_DIR = path.join(__dirname, 'test', 'fixtures', 'db');
+  process.env.DB_DIR = (await import('./test/dbFixture.ts')).fixtureDBDir;
   server = http.createServer(requestHandler);
-  await new Promise(resolve => server.listen(port, () => resolve()));
+  await new Promise<void>(resolve => server.listen(port, () => resolve()));
 });
 
 after(async () => {
@@ -34,7 +33,7 @@ after(async () => {
     delete process.env.DB_DIR;
   }
   server.closeAllConnections?.();
-  await new Promise(resolve => {
+  await new Promise<void>(resolve => {
     const timer = setTimeout(() => {
       server.closeAllConnections?.();
       resolve();
@@ -49,9 +48,9 @@ after(async () => {
 // HELPERS
 
 // Sends a GET request and returns the response body as a string.
-const get = requestPath => new Promise((resolve, reject) => {
+const get = (requestPath: string): Promise<any> => new Promise((resolve, reject) => {
   http.request({method: 'GET', host: 'localhost', port, path: requestPath}, response => {
-    const chunks = [];
+    const chunks: any[] = [];
     response.on('data', chunk => chunks.push(chunk));
     response.on('end', () => {
       resolve({statusCode: response.statusCode, body: chunks.join('')});

package/scripts/{generate-openapi.js → generate-openapi.ts}

@@ -1,34 +1,34 @@
 /*
-  generate-openapi.js
-  Generates openapi.yaml from the Kilotest API route table (api/routes.js) and Zod schemas (api/schemas.js), keeping the OpenAPI document in sync with schemas.js’s single source of truth.
+  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.
 */
 
 // IMPORTS
 
-const fs = require('fs');
-const path = require('path');
-const yaml = require('js-yaml');
-const {createDocument} = require('zod-openapi');
-const {license} = require('../package.json');
-const routes = require('../api/routes');
-const {version} = require('../api/version');
+import fs from 'node:fs';
+import path from 'node:path';
+import * as yaml from 'js-yaml';
+import {createDocument} from 'zod-openapi';
+import pkg from '../package.json' with {type: 'json'};
+import {routes} from '../api/routes.ts';
+import {version} from '../api/version.ts';
 
 // CONSTANTS
 
-const outputPath = path.join(__dirname, '..', 'openapi.yaml');
+const {license} = pkg;
+const outputPath = path.join(import.meta.dirname, '..', 'openapi.yaml');
 
 // FUNCTIONS
 
 // Builds the paths object for createDocument from the route table.
 const buildPaths = () => {
-  /** @type {import('zod-openapi').ZodOpenApiPathsObject} */
-  const paths = {};
+  const paths: Record<string, any> = {};
   routes.forEach(route => {
     const {method, path: routePath, summary, pathParamsSchema, bodySchema, responseSchema} = route;
     if (!paths[routePath]) {
       paths[routePath] = {};
     }
-    const operation = {
+    const operation: any = {
       operationId: route.operationId,
       summary,
       responses: {

package/serve.ts

@@ -0,0 +1,15 @@
+/*
+  serve.ts
+  Entry point for the Kilotest service under PM2. index.ts starts the server only when
+  it is the program entry point (import.meta.main), which is false inside PM2's process
+  container, so PM2 loads this file, which starts the server unconditionally.
+*/
+
+// IMPORTS
+
+import {errorMessage} from './util.ts';
+import {startServer} from './index.ts';
+
+// EXECUTION
+
+startServer().catch(error => console.log(errorMessage(error)));