@jrpool/kilotest 46.1.2 → 48.0.0

package/api/{util.js → util.ts}

@@ -1,38 +1,45 @@
 /*
-  util.js
+  util.ts
   Utilities for API requests.
 */
 
 // IMPORTS
 
-const {sendAlert} = require('../alerts');
-const {
+import {
   getAgoDays,
-  getLatestReportExtracts,
+  getReportExtracts,
   getNowStamp,
-  getPlainText,
   getRandomString,
   getReportExtract,
   getReportStats,
   objectSort,
-  ruleEngines,
-  updateRecs
-} = require('../util');
-const {issues: issueSpecs} = require('testaro-issues');
+  ruleEngines
+} from '../util.ts';
+import type {ReportExtract} from '../util.ts';
+import {issues as issueSpecs} from 'testaro-issues';
 
-// CONSTANTS
+// TYPES
 
-const thisHost = exports.thisHost = process.env.THIS_KILOTEST_HOST;
+// The basics about a report, as returned by getReportBasics.
+export type ReportBasics = {
+  identifier: string;
+  'completion date and time': string;
+  'days since the report was completed': number | null;
+  'tested web page': {description: string; URL: string};
+  'whether a later report about the same page exists': boolean;
+};
 
 // FUNCTIONS
 
+// Returns the base URL of this Kilotest host.
+export const getThisHost = () => process.env.THIS_KILOTEST_HOST;
 // Returns uniform metadata for every response.
-exports.getResponseMetadata = () => ({
+export const getResponseMetadata = () => ({
   identifier: `${getNowStamp()}-${getRandomString(3)}`,
   'date and time': new Date().toISOString()
 });
 // Returns facts about the tool collection (Kilotest).
-exports.getToolsFacts = () => ({
+export const getToolsFacts = () => ({
   'name': 'Kilotest',
   'description': {
     'what Kilotest does': 'Kilotest tools generate and make available findings about the front-end quality (i.e. accessibility, usability, and standards conformity) of web pages. A Kilotest job generates findings by using Testaro to test a page against about 1300 rules defined by an ensemble of twelve rule engines. Testaro produces a report of the job. The report describes violations of the rules. Kilotest uses Testilo to enhance the report with a classification of the rule violations into about 380 issues. Kilotest makes facts about the issues and the violations retrievable at four levels of granularity.',
@@ -49,11 +56,11 @@ exports.getToolsFacts = () => ({
       'confirmation': 'Use the listReports tool to determine whether a requested new report exists. There is currently no process for notification of the outcome of requests.'
     }
   },
-  'URL': `${thisHost}/mcp`,
-  'web users can obtain similar functionalities at': thisHost
+  'URL': `${getThisHost()}/mcp`,
+  'web users can obtain similar functionalities at': getThisHost()
 });
 // Returns the facts about a rule engine.
-const getRuleEngineFacts = exports.getRuleEngineFacts = ruleEngineID => {
+export const getRuleEngineFacts = (ruleEngineID: string) => {
   const ruleEngineData = ruleEngines[ruleEngineID] || [null, null];
   return {
     identifier: ruleEngineID,
@@ -62,15 +69,28 @@ const getRuleEngineFacts = exports.getRuleEngineFacts = ruleEngineID => {
   };
 };
 // Returns the facts about rule engines.
-exports.getRuleEnginesFacts = ruleEngineIDSet => {
+export const getRuleEnginesFacts = (ruleEngineIDSet: Iterable<string>) => {
   const ruleEnginesFacts = Array.from(ruleEngineIDSet).map(id => getRuleEngineFacts(id));
   objectSort(ruleEnginesFacts, 'name', 'alpha');
   return ruleEnginesFacts;
 };
 // Returns the basics about a report.
-// Accepts optional precomputed extract and latestReportExtracts to avoid redundant
-// reads when called in a loop over all reports (e.g. by listReports).
-exports.getReportBasics = async (timeStamp, jobID, extract = null, latestReportExtracts = null) => {
+// Accepts an optional precomputed extract to avoid redundant reads when called
+// in a loop over all reports (e.g. by listReports). When the extract comes from
+// getReportExtracts, it carries a superseded flag; otherwise the flag is computed.
+// With an extract provided, failure is impossible, so the return type narrows
+// to ReportBasics; without one, an error object may be returned.
+// XXX Why are these overloads necessary? Can't we just have one function?
+export function getReportBasics(
+  timeStamp: string, jobID: string, extract: ReportExtract
+): Promise<ReportBasics>;
+export function getReportBasics(
+  timeStamp: string, jobID: string, extract?: ReportExtract | null
+): Promise<ReportBasics | {error: string}>;
+export async function getReportBasics(
+  timeStamp: string, jobID: string, extract: ReportExtract | null = null
+): Promise<ReportBasics | {error: string}> {
+  const extractProvided = !!extract;
   // If an extract was not provided, verify the report exists and read it.
   if (!extract) {
     // Get the creation time of the report.
@@ -84,32 +104,35 @@ exports.getReportBasics = async (timeStamp, jobID, extract = null, latestReportE
       };
     }
     // Otherwise, i.e. if it exists, get an extract of the report.
-    extract = await getReportExtract(timeStamp, jobID);
-  }
-  const {url, what, reportTime} = extract;
-  // If the latest report extracts were not provided, compute them.
-  if (!latestReportExtracts) {
-    latestReportExtracts = await getLatestReportExtracts();
+    const fetchedExtract = await getReportExtract(timeStamp, jobID);
+    // If this failed, return why.
+    if ('error' in fetchedExtract) {
+      return fetchedExtract;
+    }
+    extract = fetchedExtract;
   }
+  const {url, description, reportTime} = extract;
   // Get whether this report has been superseded.
-  const isSuperseded = latestReportExtracts
-  .every(ex => ex.timeStamp !== timeStamp || ex.jobID !== jobID);
+  const isSuperseded = extractProvided
+    ? extract.superseded === true
+    : (await getReportExtracts(true))
+      .every(ex => ex.timeStamp !== timeStamp || ex.jobID !== jobID);
   // Get the basics about the report.
   const basics = {
     identifier: `${timeStamp}-${jobID}`,
     'completion date and time': reportTime,
     'days since the report was completed': getAgoDays(new Date(reportTime)),
     'tested web page': {
-      description: what,
+      description,
       URL: url
     },
     'whether a later report about the same page exists': isSuperseded
   };
   // Return them.
   return basics;
-};
+}
 // Returns the specification of an issue.
-exports.getIssueSpec = issueID => {
+export const getIssueSpec = (issueID: string) => {
   // Get the issue specification.
   const issueSpec = issueSpecs[issueID];
   // If it exists:
@@ -126,23 +149,3 @@ exports.getIssueSpec = issueID => {
   // Otherwise, i.e. if it does not exist, return this.
   return null;
 };
-// Processes a test or retest request.
-exports.processTestRequest = async (testType, what, url, why) => {
-  // Get an email-safe version of the reason.
-  const plainWhy = getPlainText(why);
-  // Update the waiting recommendations as a transaction.
-  const updateResult = await updateRecs(what, url, plainWhy);
-  // If the recommendation was a duplicate:
-  if (updateResult.error === 'duplicate') {
-    // Return this.
-    return {
-      status: 'error',
-      message: 'Duplicate request'
-    };
-  }
-  // Otherwise, i.e. if it was not a duplicate, alert a manager about it.
-  await sendAlert(
-    `Kilotest: new ${testType} recommendation in the API`,
-    `Target: ${what}\nURL: ${url}\nReason: ${plainWhy}`
-  );
-};

package/api/version.ts

@@ -0,0 +1,8 @@
+/*
+  version.ts
+  Single source of truth for the version of the Kilotest API and MCP tool contract, consumed by mcp.ts and scripts/generate-openapi.ts.
+*/
+
+// CONSTANTS
+
+export const version = '2.1.0';

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

@@ -1,15 +1,14 @@
 /*
-  apiIntegration.test.js
+  apiIntegration.test.ts
   Minimal HTTP integration tests verifying routing, body parsing, and JSON serialization, using the fixture corpus and a temporary in-process server.
 */
 
 // 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 = 3998;
 // 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,8 +48,8 @@ after(async () => {
 // HELPERS
 
 // Sends an HTTP request and returns the parsed JSON response body.
-const request = (method, requestPath, body = null) => new Promise((resolve, reject) => {
-  const options = {method, host: 'localhost', port, path: requestPath};
+const request = (method: string, requestPath: string, body: any = null): Promise<any> => new Promise((resolve, reject) => {
+  const options: any = {method, host: 'localhost', port, path: requestPath};
   if (body) {
     const bodyJSON = JSON.stringify(body);
     options.headers = {
@@ -59,7 +58,7 @@ const request = (method, requestPath, body = null) => new Promise((resolve, reje
     };
   }
   const req = http.request(options, response => {
-    const chunks = [];
+    const chunks: any[] = [];
     response.on('data', chunk => chunks.push(chunk));
     response.on('end', () => {
       const bodyString = chunks.join('');

package/balances.ts

@@ -0,0 +1,87 @@
+/*
+  balances.ts
+  Manages monetary balances and sends alerts when they near exhaustion.
+*/
+
+// IMPORTS
+
+import {sendAlert} from './alerts.ts';
+import {errorMessage, getJSON} from './util.ts';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type {Act, Report} from 'testaro';
+
+// CONSTANTS
+
+// The path of the file recording the AI service 0 balance.
+export const balancePath = path.join(import.meta.dirname, 'ai0Balance.json');
+
+// FUNCTIONS
+
+// Checks a report for balances nearing exhaustion.
+export const checkBalancesForAlerts = async (report: Report): Promise<void> => {
+  // Get the alert thresholds and prices from the environment.
+  const WAVE_THRESHOLD = Number(process.env.WAVE_BALANCE_THRESHOLD);
+  const AI_SERVICE0_THRESHOLD = Number(process.env.AI_SERVICE0_BALANCE_THRESHOLD);
+  const AI_MODEL0_INPUT_PRICE = Number(process.env.AI_MODEL0_INPUT_PRICE);
+  const AI_MODEL0_OUTPUT_PRICE = Number(process.env.AI_MODEL0_OUTPUT_PRICE);
+  // If the variables to be monitored for alerts are defined:
+  if (WAVE_THRESHOLD && AI_SERVICE0_THRESHOLD && AI_MODEL0_INPUT_PRICE && AI_MODEL0_OUTPUT_PRICE) {
+    // WAVE.
+    const waveAct = report.acts.find((act: Act) => act.type === 'test' && act.which === 'wave');
+    const creditsRemaining = waveAct?.data?.creditsRemaining;
+    // If a WAVE balance nearing exhaustion is reported:
+    if (typeof creditsRemaining === 'number' && creditsRemaining < WAVE_THRESHOLD) {
+      // Alert a manager.
+      await sendAlert(
+        'Kilotest: WAVE balance low',
+        `Only ${creditsRemaining} WAVE credits remain (3 used per job)`
+      );
+    }
+    const testaroAct = report.acts.find((act: Act) => act.type === 'test' && act.which === 'testaro');
+    // Get the AI model token usage for the testaro allCaps test.
+    const usage = (testaroAct?.data?.ruleData as {
+      allCaps?: {aiModelUsage?: {inputTokens: number; outputTokens: number}}
+    } | undefined)?.allCaps?.aiModelUsage;
+    let balanceJSON = null;
+    try {
+      // Get the recorded AI service 0 balance.
+      balanceJSON = await fs.readFile(balancePath, 'utf8');
+    }
+    catch {
+      console.error('ERROR: AI service 0 balance file missing');
+    }
+    // If the variables required for an AI service 0 balance alert are defined:
+    if (usage && AI_MODEL0_INPUT_PRICE && AI_MODEL0_OUTPUT_PRICE && balanceJSON) {
+      const inputCost = AI_MODEL0_INPUT_PRICE * usage.inputTokens;
+      const outputCost = AI_MODEL0_OUTPUT_PRICE * usage.outputTokens;
+      const cost = inputCost + outputCost;
+      // If any cost was incurred:
+      if (cost > 0) {
+        // Warn about this.
+        console.log(
+          'This job has made the production AI service 0 balance record wrong. Update it.'
+        );
+      }
+      try {
+        const balanceData = JSON.parse(balanceJSON);
+        // Get an estimate of the balance after this job.
+        const newBalance = balanceData.balance - cost;
+        // Update the recorded balance.
+        await fs.writeFile(balancePath, getJSON({balance: newBalance}));
+        console.log(`Estimated new AI Service 0 balance: $${newBalance.toFixed(2)}`);
+        // If it is nearing exhaustion:
+        if (newBalance < AI_SERVICE0_THRESHOLD) {
+          // Alert a manager.
+          await sendAlert(
+            'Kilotest: AI service 0 balance low',
+            `Balance of AI service 0 account (https://console.anthropic.com) only about $${newBalance.toFixed(2)} (about $0.01 used per job)`
+          );
+        }
+      }
+      catch (error) {
+        console.log(`ERROR managing AI service 0 balance: ${errorMessage(error)}`);
+      }
+    }
+  }
+};

package/{checkinfo.js → checkinfo.ts}

@@ -1,24 +1,25 @@
 /*
-  checkinfo.js
+  checkinfo.ts
   Summarizes the validation scope of the lint, test, and test:smoke scripts by deriving file and test-case counts from their actual configurations, so the summary stays accurate as the codebase changes.
 */
 
 // IMPORTS
 
-const fs = require('fs');
-const path = require('path');
-const {execSync} = require('child_process');
+import fs from 'node:fs';
+import path from 'node:path';
+import {execSync} from 'node:child_process';
+import {routes} from './index.ts';
 
 // CONSTANTS
 
-const rootDir = __dirname;
+const rootDir = import.meta.dirname;
 const excludeDirs = new Set(['node_modules', '.git', 'coverage']);
 
 // FUNCTIONS
 
 // Recursively collects all files under a directory, skipping excluded directories.
-const collectFiles = dir => {
-  const results = [];
+const collectFiles = (dir: string): string[] => {
+  const results: string[] = [];
   for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
@@ -35,7 +36,7 @@ const collectFiles = dir => {
 
 // Converts a glob pattern to a RegExp for matching relative paths.
 // Supports * (non-segment), ** (any), and literal characters.
-const globToRegExp = pattern => {
+const globToRegExp = (pattern: string): RegExp => {
   const escaped = pattern
     .replace(/[.+^${}()|[\]\\]/g, '\\$&')
     .replace(/\*\*/g, '\x00')
@@ -45,33 +46,34 @@ const globToRegExp = pattern => {
 };
 
 // Returns whether a relative path matches any pattern in a list.
-const matchesAny = (relPath, patterns) => patterns.some(p => globToRegExp(p).test(relPath));
+const matchesAny = (relPath: string, patterns: string[]) =>
+  patterns.some(p => globToRegExp(p).test(relPath));
 
 // Extracts the top-level ignores array from eslint.config.mjs.
-const getEslintIgnores = () => {
+const getEslintIgnores = (): string[] => {
   const content = fs.readFileSync(path.join(rootDir, 'eslint.config.mjs'), 'utf8');
   const match = content.match(/ignores:\s*\[([\s\S]*?)\]/);
   if (!match) {
     return [];
   }
-  return [...match[1].matchAll(/"([^"]+)"/g)].map(m => m[1]);
+  return [...match[1]!.matchAll(/"([^"]+)"/g)].map(m => m[1]!);
 };
 
 // Parses .markdownlint-cli2.jsonc and returns its ignores array.
-const getMarkdownlintIgnores = () => {
+const getMarkdownlintIgnores = (): string[] => {
   const content = fs.readFileSync(path.join(rootDir, '.markdownlint-cli2.jsonc'), 'utf8');
   const stripped = content.replace(/\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '');
   const match = stripped.match(/"ignores"\s*:\s*\[([\s\S]*?)\]/);
   if (!match) {
     return [];
   }
-  return [...match[1].matchAll(/"([^"]+)"/g)].map(m => m[1]);
+  return [...match[1]!.matchAll(/"([^"]+)"/g)].map(m => m[1]!);
 };
 
 // Runs the Node test runner with the TAP reporter and parses the test count, so dynamically generated tests (e.g., from for-loops) are counted accurately.
 const getTestCaseCount = () => {
   const output = execSync(
-    'node --require ./test/setup.cjs --test --test-concurrency=1 --test-timeout=100 --test-reporter=tap',
+    "node --require ./test/setup.ts --experimental-test-module-mocks --test --test-concurrency=1 --test-timeout=100 --test-reporter=tap '**/*.test.ts'",
     {cwd: rootDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe']}
   );
   const match = output.match(/^# tests (\d+)$/m);
@@ -87,7 +89,7 @@ const eslintIgnores = getEslintIgnores();
 const markdownlintIgnores = getMarkdownlintIgnores();
 
 // ESLint file counts by extension, excluding ignored files.
-const eslintExts = {js: 0, json: 0, md: 0, css: 0};
+const eslintExts = {js: 0, ts: 0, json: 0, md: 0, css: 0};
 for (const rel of relFiles) {
   if (matchesAny(rel, eslintIgnores)) {
     continue;
@@ -95,6 +97,9 @@ for (const rel of relFiles) {
   if (/\.(js|mjs|cjs)$/.test(rel)) {
     eslintExts.js++;
   }
+  else if (/\.ts$/.test(rel)) {
+    eslintExts.ts++;
+  }
   else if (/\.json$/.test(rel)) {
     eslintExts.json++;
   }
@@ -113,20 +118,19 @@ const markdownlintCount = relFiles.filter(
 ).length;
 
 // Test file and test-case counts.
-const testFiles = relFiles.filter(rel => /\.test\.js$/.test(rel));
+const testFiles = relFiles.filter(rel => /\.test\.ts$/.test(rel));
 const testCaseCount = getTestCaseCount();
 
-// Smoke-test path counts from the routes table in index.js.
-const {routes} = require('./index');
+// Smoke-test path counts from the routes table in index.ts.
 const smokeGetCount = routes.GET.length;
 const smokePostCount = routes.POST.length;
 const smokeTotal = smokeGetCount + smokePostCount;
 
 // OUTPUT
 
-const parts = [
+const parts: [string, string[]][] = [
   ['lint', [
-    `ESLint: ${eslintTotal} files (${eslintExts.js} JS, ${eslintExts.json} JSON, ${eslintExts.md} MD, ${eslintExts.css} CSS)`,
+    `ESLint: ${eslintTotal} files (${eslintExts.js} JS, ${eslintExts.ts} TS, ${eslintExts.json} JSON, ${eslintExts.md} MD, ${eslintExts.css} CSS)`,
     `markdownlint: ${markdownlintCount} files`
   ]],
   ['test', [

package/docs/AI-TOOLS.md

@@ -26,14 +26,14 @@ The internal features that make Kilotest a collection of tools for language mode
 - An `llms.txt` file and an `llms-full.txt` file, documenting the use of Kilotest by language models, conforming to the [llms-txt](https://llmstxt.org/) specification.
 - A generated `openapi.yaml` file, documenting the Kilotest API, conforming to the [OpenAPI specification](https://spec.openapis.org/oas/v3.1.0).
 - An `mcp.js` file, providing an MCP server for Kilotest.
-- A `server.json` file, conforming to the [MCP server schema](https://modelcontextprotocol.io/), and a GitHub Actions workflow (`publish-mcp.yml`) that authenticates via GitHub OIDC and publishes that file to the official MCP Registry whenever `server.json` or `api/version.js` changes on the `main` branch.
+- A `server.json` file, conforming to the [MCP server schema](https://modelcontextprotocol.io/), and a GitHub Actions workflow (`publish-mcp.yml`) that authenticates via GitHub OIDC and publishes that file to the official MCP Registry whenever `server.json` or `api/version.ts` changes on the `main` branch.
 - A `capability.md` file with a URL, summarizing what Kilotest tools can do.
 - `mcp`, `mcp-server`, and `modelcontextprotocol` keywords in `package.json`, supporting discovery of the `@jrpool/kilotest` npm package by tools and humans searching the npm registry for MCP servers.
 - An `lhm.plugin.json` file, conforming to the [LobeHub plugin manifest format](https://market.lobehub.com/s/publish-mcp/references/manifest), declaring Kilotest as a plugin in the [LobeHub MCP Market](https://lobehub.com/mcp). Publishing and updating are non-automated (`lhm plugin publish`/`update`), because LobeHub requires browser-based OAuth and does not support machine-to-machine publishing.
 - A `sitemap.xml` file.
 - Documentation in the `README.md` file.
 - This `AI-TOOLS.md` file.
-- A [tutorial on authorizing language models to use Kilotest](https://kilotest.com/qai/).
+- A [tutorial on authorizing language models to use Kilotest](https://kilotest.com/tutorialAI.html).
 
 ## External features
 
@@ -44,7 +44,7 @@ The external features that support the use of Kilotest as a collection of AI too
 - A [pull request](https://github.com/w3c/wai-evaluation-tools-list/pull/1153) to add Kilotest to the WAI evaluation tools list.
 - Registration of Kilotest as an active server in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=kilotest) (`io.github.jrpool/kilotest`), maintained by the [Model Context Protocol](https://modelcontextprotocol.io/) project. The [PulseMCP](https://www.pulsemcp.com/servers) directory and the VS Code MCP gallery both crawl this registry, so Kilotest is discoverable through them with no separate submission.
 - Registration of Kilotest with the [Smithery](https://smithery.ai/servers/pool/kilotest) MCP server registry.
-- Registration of Kilotest with the [Glama](https://glama.ai/mcp/connectors/com.kilotest/kilotest) MCP server registry.
+- Registration of Kilotest with the [Glama](https://glama.ai/mcp/connectors/com.kilotest/kilotest) MCP server registry, including a claim of ownership of the MCP connector by the maintainer via a `TXT` DNS record for `_glama-claim.kilotest.com`, with the value `glama_claim_gVV4HrPdcXr9TEfj1p3icEUBJ3_OVJGX`.
 - Registration of Kilotest with [Awesome MCP Servers](https://www.tensorblock.co/mcp/servers/github-jrpool-kilotest-f518ba36).
 - Registration of Kilotest with the [RapidAPI](https://rapidapi.com/jrpool/api/kilotest/playground/apiendpoint_0f03577a-ff9a-472a-a0ed-533bd198981a) Hub.
 - Registration of Kilotest with the [LobeHub MCP Market](https://lobehub.com/mcp) (identifier: `jrpool-kilotest`), enabled with an `lhm.plugin.json` file.
@@ -61,7 +61,7 @@ The external features that support the use of Kilotest as a collection of AI too
 
 ## Required maintenance
 
-Whenever the `/api/version.js` file is updated:
+Whenever the `/api/version.ts` file is updated:
 
 - Update the `server.json` file (version field).
 - Update the `lhm.plugin.json` file (version field).