@monosmith/plugin-sdk 0.0.0-stage → 0.2.0

package/codec/schema-lookup.algorithm.js

@@ -0,0 +1,56 @@
+/** Follows `$ref` to the definition it names. */
+export function resolveNode(schema, node) {
+    let current = node;
+    for (let hops = 0; current.$ref !== undefined; hops++) {
+        const name = current.$ref.slice('#/$defs/'.length);
+        const target = schema.$defs[name];
+        if (target === undefined || hops > 16)
+            throw new Error(`the schema has no definition ${current.$ref}`);
+        current = target;
+    }
+    return current;
+}
+/** Whether `null` is a value of the node: `["integer", "null"]`, or an `anyOf` with null. */
+export function isNullable(node) {
+    return Array.isArray(node.type) ? node.type.includes('null') : node.anyOf?.some(branch => branch.type === 'null') ?? false;
+}
+/** The node without its `null` alternative. */
+export function withoutNull(schema, node) {
+    if (Array.isArray(node.type)) {
+        const types = node.type.filter(t => t !== 'null');
+        return { ...node, type: types.length === 1 ? types[0] : types };
+    }
+    const branches = node.anyOf?.filter(branch => branch.type !== 'null');
+    return branches !== undefined && branches.length === 1 ? resolveNode(schema, branches[0]) : node;
+}
+/** The kind of value a node describes, after `$ref` and null are set aside. */
+export function kindOf(schema, node) {
+    const base = resolveNode(schema, withoutNull(schema, node));
+    switch (base.type) {
+        case 'string': {
+            return 'string';
+        }
+        case 'integer': {
+            return 'integer';
+        }
+        case 'number': {
+            return 'number';
+        }
+        case 'boolean': {
+            return 'boolean';
+        }
+        case 'array': {
+            return 'array';
+        }
+        case 'object': {
+            return base.properties === undefined ? 'map' : 'struct';
+        }
+        default: {
+            return 'any';
+        }
+    }
+}
+/** The node as the codec walks it: nullability removed, references followed. */
+export function baseNode(schema, node) {
+    return resolveNode(schema, withoutNull(schema, node));
+}

package/codec/wire-message.mapper.d.ts

@@ -0,0 +1,27 @@
+/** A request or notification as it was received. `id` is `null` for a notification. */
+export interface ReceivedRequest {
+    id: number | null;
+    method: string;
+    params: unknown;
+}
+/** A response as it was received. */
+export interface ReceivedResponse {
+    id: number | null;
+    result: unknown;
+    error: {
+        code: number;
+        message: string;
+    } | null;
+}
+/** A request as the Go SDK writes it: `jsonrpc`, `id`, `method`, `params`, the params left out when there are none. */
+export declare function writeRequest(id: number, method: string, paramsJson: string | undefined): string;
+/** A notification as the Go SDK writes it: a request with no `id`, which gets no response. */
+export declare function writeNotification(method: string, paramsJson: string): string;
+/** A successful response:`id` is `null` only when the request could not be read. */
+export declare function writeResult(id: number | null, resultJson: string): string;
+/** An error response. */
+export declare function writeFailure(id: number | null, code: number, message: string): string;
+/** Reads a request frame. A `null` or missing id makes it a notification. */
+export declare function parseRequest(body: string): ReceivedRequest;
+/** Reads a response frame. */
+export declare function parseResponse(body: string): ReceivedResponse;

package/codec/wire-message.mapper.js

@@ -0,0 +1,62 @@
+import { encodeJsonString } from './encode-json-value.algorithm.js';
+import { MessageParseError } from './message-parse.error.js';
+/** A request as the Go SDK writes it: `jsonrpc`, `id`, `method`, `params`, the params left out when there are none. */
+export function writeRequest(id, method, paramsJson) {
+    const params = paramsJson === undefined ? '' : `,"params":${paramsJson}`;
+    return `{"jsonrpc":"2.0","id":${id},"method":${encodeJsonString(method)}${params}}`;
+}
+/** A notification as the Go SDK writes it: a request with no `id`, which gets no response. */
+export function writeNotification(method, paramsJson) {
+    return `{"jsonrpc":"2.0","method":${encodeJsonString(method)},"params":${paramsJson}}`;
+}
+/** A successful response:`id` is `null` only when the request could not be read. */
+export function writeResult(id, resultJson) {
+    return `{"jsonrpc":"2.0","id":${id === null ? 'null' : id},"result":${resultJson}}`;
+}
+/** An error response. */
+export function writeFailure(id, code, message) {
+    return `{"jsonrpc":"2.0","id":${id === null ? 'null' : id},"error":{"code":${code},"message":${encodeJsonString(message)}}}`;
+}
+function parseObject(body) {
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch (error) {
+        throw new MessageParseError(error instanceof Error ? error.message : String(error));
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new MessageParseError('a message is a JSON object');
+    return value;
+}
+function readId(message) {
+    const id = message.id;
+    if (id === undefined || id === null)
+        return null;
+    if (typeof id !== 'number' || !Number.isSafeInteger(id))
+        throw new MessageParseError('id must be an integer');
+    return id;
+}
+/** Reads a request frame. A `null` or missing id makes it a notification. */
+export function parseRequest(body) {
+    const message = parseObject(body);
+    const id = readId(message);
+    const method = message.method ?? '';
+    if (typeof method !== 'string')
+        throw new MessageParseError('method must be a string');
+    return { id, method, params: message.params };
+}
+/** Reads a response frame. */
+export function parseResponse(body) {
+    const message = parseObject(body);
+    const id = readId(message);
+    const error = message.error;
+    if (error === undefined || error === null)
+        return { id, result: message.result, error: null };
+    if (typeof error !== 'object' || Array.isArray(error))
+        throw new MessageParseError('error must be an object');
+    const { code, message: text } = error;
+    if (typeof code !== 'number' || typeof text !== 'string')
+        throw new MessageParseError('error needs a numeric code and a message');
+    return { id, result: undefined, error: { code, message: text } };
+}

package/concurrency/concurrency.policy.d.ts

@@ -0,0 +1,21 @@
+/** The `concurrency` value that leaves the number of simultaneous requests to the host. */
+export declare const CONCURRENCY_UNLIMITED = -1;
+/** How many requests the host keeps in flight to a plugin that declared unlimited concurrency. */
+export declare const UNLIMITED_IN_FLIGHT = 32;
+/** The most workers a plugin that declared unlimited concurrency runs: the host decides, but the pool stays bounded. */
+export declare const UNLIMITED_WORKERS = 1024;
+/** Whether a declared concurrency is one the protocol defines: absent (0), a count (1 and above) or unlimited (-1). */
+export declare function isValidConcurrency(declared: number): boolean;
+/**
+ * Reads a declared concurrency: how many requests may be in flight at once,
+ * or `unlimited`. An absent, zero or invalid value is 1, the default of every
+ * plugin that says nothing.
+ */
+export declare function concurrencyLimit(declared: number | undefined): {
+    limit: number;
+    unlimited: boolean;
+};
+/** How many requests the host keeps in flight to a plugin that declared `declared`. */
+export declare function inFlightLimit(declared: number | undefined): number;
+/** How many requests a plugin that declared `declared` works on at once (its pool size). */
+export declare function workerLimit(declared: number | undefined): number;

package/concurrency/concurrency.policy.js

@@ -0,0 +1,30 @@
+/** The `concurrency` value that leaves the number of simultaneous requests to the host. */
+export const CONCURRENCY_UNLIMITED = -1;
+/** How many requests the host keeps in flight to a plugin that declared unlimited concurrency. */
+export const UNLIMITED_IN_FLIGHT = 32;
+/** The most workers a plugin that declared unlimited concurrency runs: the host decides, but the pool stays bounded. */
+export const UNLIMITED_WORKERS = 1024;
+/** Whether a declared concurrency is one the protocol defines: absent (0), a count (1 and above) or unlimited (-1). */
+export function isValidConcurrency(declared) {
+    return Number.isSafeInteger(declared) && declared >= CONCURRENCY_UNLIMITED;
+}
+/**
+ * Reads a declared concurrency: how many requests may be in flight at once,
+ * or `unlimited`. An absent, zero or invalid value is 1, the default of every
+ * plugin that says nothing.
+ */
+export function concurrencyLimit(declared) {
+    if (declared === CONCURRENCY_UNLIMITED)
+        return { limit: 0, unlimited: true };
+    return { limit: declared === undefined || !Number.isSafeInteger(declared) || declared < 1 ? 1 : declared, unlimited: false };
+}
+/** How many requests the host keeps in flight to a plugin that declared `declared`. */
+export function inFlightLimit(declared) {
+    const { limit, unlimited } = concurrencyLimit(declared);
+    return unlimited ? UNLIMITED_IN_FLIGHT : limit;
+}
+/** How many requests a plugin that declared `declared` works on at once (its pool size). */
+export function workerLimit(declared) {
+    const { limit, unlimited } = concurrencyLimit(declared);
+    return unlimited ? UNLIMITED_WORKERS : limit;
+}

package/concurrency/index.d.ts

@@ -0,0 +1 @@
+export { CONCURRENCY_UNLIMITED, UNLIMITED_IN_FLIGHT, UNLIMITED_WORKERS, concurrencyLimit, inFlightLimit, isValidConcurrency, workerLimit } from './concurrency.policy.ts';

package/concurrency/index.js

@@ -0,0 +1 @@
+export { CONCURRENCY_UNLIMITED, UNLIMITED_IN_FLIGHT, UNLIMITED_WORKERS, concurrencyLimit, inFlightLimit, isValidConcurrency, workerLimit } from './concurrency.policy.js';

package/conformance/check-generation.use-case.d.ts

@@ -0,0 +1,12 @@
+import type { PluginClient } from '../host/index.ts';
+import type { ConformanceReport } from './conformance-report.model.ts';
+/** The stack name generated projects are asked to record. */
+export declare const CONFORMANCE_STACK = "conformance";
+/**
+ * Asks the plugin for one project of each kind, checks the files it reports
+ * exist, and, for a language plugin, that its own `discover` returns what it
+ * made, with the kind and the stack it was asked for, tasks with commands, and
+ * that the dry runs of `version/write`, `remove`, `publish` and `published`
+ * answer.
+ */
+export declare function checkGeneration(client: PluginClient, workspace: string, report: ConformanceReport): Promise<void>;

package/conformance/check-generation.use-case.js

@@ -0,0 +1,91 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { effectiveRoles } from '../plugin-roles/index.js';
+import { projectKindDirectory } from '../projects/index.js';
+import { findManifests } from './find-manifests.algorithm.js';
+import { goList, goQuote } from './go-list.mapper.js';
+/** The stack name generated projects are asked to record. */
+export const CONFORMANCE_STACK = 'conformance';
+const LONG_MS = 20 * 60 * 1000;
+function article(kind) {
+    return kind === 'app' ? 'an app' : `a ${kind}`;
+}
+/**
+ * Asks the plugin for one project of each kind, checks the files it reports
+ * exist, and, for a language plugin, that its own `discover` returns what it
+ * made, with the kind and the stack it was asked for, tasks with commands, and
+ * that the dry runs of `version/write`, `remove`, `publish` and `published`
+ * answer.
+ */
+export async function checkGeneration(client, workspace, report) {
+    const language = effectiveRoles(client.info).includes('language');
+    const made = [];
+    for (const kind of ['app', 'lib', 'package']) {
+        const name = `c${kind}`;
+        const params = {
+            kind,
+            name,
+            directory: `${projectKindDirectory(kind)}/${name}`,
+            stack: CONFORMANCE_STACK,
+            workspace: { name: 'conformance', scope: '@conformance', modulePrefix: 'example.com/conformance' },
+        };
+        let files;
+        try {
+            const generated = await client.call('generate', params, { timeoutMs: LONG_MS });
+            files = generated.files;
+        }
+        catch (error) {
+            report.add(`generates ${article(kind)}`, false, messageOf(error));
+            continue;
+        }
+        const missing = files.filter(file => !existsSync(join(workspace, ...file.split('/'))));
+        report.add(`generates ${article(kind)}`, files.length > 0 && missing.length === 0, `files reported but not written: ${goList(missing)} (of ${goList(files)})`);
+        made.push(params);
+    }
+    if (!language || made.length === 0)
+        return;
+    let projects;
+    try {
+        const discovered = await client.call('discover', { manifests: findManifests(workspace, client.info.manifests ?? []) }, { timeoutMs: LONG_MS });
+        projects = discovered.projects;
+    }
+    catch (error) {
+        report.add('discovers what it generated', false, messageOf(error));
+        return;
+    }
+    const found = new Map(projects.map(project => [project.root, project]));
+    for (const params of made) {
+        const project = found.get(params.directory);
+        report.add(`discovers the generated ${params.kind}`, project !== undefined, `no project at ${params.directory} among ${projects.length} discovered`);
+        if (project === undefined)
+            continue;
+        report.add(`the generated ${params.kind} keeps its kind`, project.kind === params.kind, `discovered as ${goQuote(project.kind)}`);
+        report.add(`the generated ${params.kind} records its stack`, project.stack === CONFORMANCE_STACK, `discovered with stack ${goQuote(project.stack ?? '')}; generate must record params.stack in the manifest`);
+        const empty = Object.entries(project.tasks ?? {}).filter(([, task]) => task.command.length === 0).map(([name]) => name).sort((a, b) => a.localeCompare(b));
+        report.add(`the generated ${params.kind}'s tasks have commands`, empty.length === 0, `tasks without a command: ${goList(empty)}`);
+        if (client.supports('version/write')) {
+            await attempt(report, `writes the ${params.kind}'s version (dry run)`, () => client.call('version/write', { project, version: '1.2.3', dryRun: true }, { timeoutMs: 60_000 }));
+        }
+        if (client.supports('remove')) {
+            await attempt(report, `would remove the ${params.kind} (dry run)`, () => client.call('remove', { project, dryRun: true }, { timeoutMs: 60_000 }));
+        }
+        if (params.kind === 'package' && client.supports('publish')) {
+            await attempt(report, 'publishes the package (dry run)', () => client.call('publish', { project, version: '1.2.3', dryRun: true }, { timeoutMs: 5 * 60_000 }));
+        }
+        if (params.kind === 'package' && client.supports('published')) {
+            await attempt(report, 'says what the registry has of the package', () => client.call('published', { project }, { timeoutMs: 60_000 }), ' (an unreachable registry is a result, not an error)');
+        }
+    }
+}
+async function attempt(report, check, call, hint = '') {
+    try {
+        await call();
+        report.add(check, true, '');
+    }
+    catch (error) {
+        report.add(check, false, `${messageOf(error)}${hint}`);
+    }
+}
+function messageOf(thrown) {
+    return thrown instanceof Error ? thrown.message : String(thrown);
+}

package/conformance/check-plugin.use-case.d.ts

@@ -0,0 +1,25 @@
+import type { PluginClient } from '../host/index.ts';
+import { ConformanceReport } from './conformance-report.model.ts';
+/** Options of {@link checkPlugin}. */
+export interface CheckOptions {
+    /**
+     * An empty directory the plugin was started in (its `workspaceRoot`). When
+     * set, a plugin that generates projects is asked to generate an app, a lib
+     * and a package there, which a language plugin must then discover as
+     * generated. Generation may install dependencies, so it is opt-in.
+     */
+    workspace?: string;
+}
+/**
+ * Runs the checks of `smith plugin check` against a connected plugin: it names
+ * itself, has a known kind and known roles, its roles match what it
+ * implements, it names the slots it fills, its references and stacks are
+ * well-formed, every advertised method answers a request with nothing in it,
+ * requests sent together are answered as the declared `concurrency` allows, a
+ * plugin that advertises `cancel` stops a cancelled request, and, with `workspace`, the projects it generates are found again by its own
+ * `discover`. A port of the Go SDK's `conformance.Check`, with the same checks
+ * under the same names. (`smith plugin check` adds one more, "shuts down when
+ * asked", after closing the plugin: call {@link PluginClient.close} and add it
+ * to the report if you want it.)
+ */
+export declare function checkPlugin(client: PluginClient, options?: CheckOptions): Promise<ConformanceReport>;

package/conformance/check-plugin.use-case.js

@@ -0,0 +1,81 @@
+import { describeRef, isEmptyRef } from '../plugin-refs/index.js';
+import { ROLES, effectiveRoles, isKnownRole } from '../plugin-roles/index.js';
+import { checkGeneration } from './check-generation.use-case.js';
+import { checkScheduling } from './check-scheduling.use-case.js';
+import { ConformanceReport } from './conformance-report.model.js';
+import { goList, goQuote } from './go-list.mapper.js';
+const CALL_TIMEOUT_MS = 20 * 60 * 1000;
+/**
+ * Runs the checks of `smith plugin check` against a connected plugin: it names
+ * itself, has a known kind and known roles, its roles match what it
+ * implements, it names the slots it fills, its references and stacks are
+ * well-formed, every advertised method answers a request with nothing in it,
+ * requests sent together are answered as the declared `concurrency` allows, a
+ * plugin that advertises `cancel` stops a cancelled request, and, with `workspace`, the projects it generates are found again by its own
+ * `discover`. A port of the Go SDK's `conformance.Check`, with the same checks
+ * under the same names. (`smith plugin check` adds one more, "shuts down when
+ * asked", after closing the plugin: call {@link PluginClient.close} and add it
+ * to the report if you want it.)
+ */
+export async function checkPlugin(client, options = {}) {
+    const info = client.info;
+    const report = new ConformanceReport(info.plugin);
+    report.add('names itself', info.plugin.name !== '' && info.plugin.version !== '', `initialize returned name ${goQuote(info.plugin.name)}, version ${goQuote(info.plugin.version)}; both are required`);
+    report.add('has a known kind', info.kind === 'language' || info.kind === 'convention', `kind ${goQuote(info.kind)} is neither language nor convention`);
+    const roles = effectiveRoles(info);
+    for (const role of roles)
+        report.add(`plays a known role: ${role}`, isKnownRole(role), `roles are ${goList(ROLES)}`);
+    const caps = info.capabilities;
+    if (roles.includes('language')) {
+        report.add('a language plugin discovers projects', caps.discover === true && (info.manifests ?? []).length > 0, 'it must implement discover and name its manifest files');
+    }
+    if (roles.includes('scaffold'))
+        report.add('a scaffold generates projects', caps.generate === true, 'it must implement generate');
+    for (const role of ['toolchain', 'structure', 'deploy']) {
+        if (roles.includes(role) && !roles.includes('language')) {
+            report.add(`a ${role} plugin does something`, caps.contribute === true || caps.generate === true || caps.ci === true || caps.doctor === true, 'it implements none of contribute, generate, ci and doctor');
+        }
+    }
+    const provides = info.provides ?? [];
+    if (provides.length > 0)
+        report.add('only a toolchain provides tasks', roles.includes('toolchain'), `it provides ${goList(provides)} without the toolchain role`);
+    if (info.kind === 'convention' && roles.includes('toolchain'))
+        report.add('a toolchain names the slots it fills', provides.length > 0, 'a toolchain plugin must list the tasks it provides');
+    const requires = info.requires ?? [];
+    const conflicts = info.conflicts ?? [];
+    const stacks = info.stacks ?? [];
+    for (const ref of requires)
+        report.add(`requires ${describeRef(ref)}: a known reference`, isValidRef(ref), 'a reference sets a known level, a name or a slot');
+    for (const ref of conflicts) {
+        report.add(`conflicts with ${describeRef(ref)}: a known reference`, isValidRef(ref) && ref.name !== info.plugin.name, 'a reference sets a known level, a name or a slot, and is not the plugin itself');
+    }
+    const names = new Set();
+    for (const stack of stacks) {
+        report.add(`stack ${stack.name} is complete`, stack.name !== '' && stack.language !== '' && !names.has(stack.name), 'a stack needs a unique name and a language plugin');
+        names.add(stack.name);
+    }
+    await checkScheduling(client, report);
+    const answers = async (check, method, params) => {
+        if (!client.supports(method))
+            return;
+        try {
+            await client.call(method, params, { timeoutMs: CALL_TIMEOUT_MS });
+            report.add(check, true, '');
+        }
+        catch (error) {
+            report.add(check, false, error instanceof Error ? error.message : String(error));
+        }
+    };
+    await answers('discover answers with no manifests', 'discover', { manifests: [] });
+    await answers('contribute answers with no projects', 'contribute', { projects: [] });
+    await answers('ci answers with no projects', 'ci', { projects: [] });
+    await answers('doctor answers with no projects', 'doctor', { projects: [] });
+    if (options.workspace !== undefined && caps.generate === true)
+        await checkGeneration(client, options.workspace, report);
+    return report;
+}
+/** Whether a reference names something: a known level, a name or a slot. */
+function isValidRef(ref) {
+    const level = ref.level ?? '';
+    return !isEmptyRef(ref) && (level === '' || isKnownRole(level));
+}

package/conformance/check-scheduling.use-case.d.ts

@@ -0,0 +1,11 @@
+import type { PluginClient } from '../host/index.ts';
+import type { ConformanceReport } from './conformance-report.model.ts';
+/** How long a plugin that advertised cancel has to answer a request the host cancelled. */
+export declare const CANCEL_BOUND_MS = 10000;
+/**
+ * Checks what a plugin says about how it is called: the concurrency it
+ * declares must be one the protocol defines and be accepted, and the cancel it
+ * advertises must stop a request within a bound and leave the plugin serving.
+ * The same checks, under the same names, as the Go SDK's.
+ */
+export declare function checkScheduling(client: PluginClient, report: ConformanceReport, cancelBoundMs?: number): Promise<void>;

package/conformance/check-scheduling.use-case.js

@@ -0,0 +1,98 @@
+import { CallInterruptedError } from '../host/index.js';
+import { ERROR_CODES } from '../protocol/index.js';
+import { inFlightLimit, isValidConcurrency } from '../concurrency/index.js';
+/** How long a plugin that advertised cancel has to answer a request the host cancelled. */
+export const CANCEL_BOUND_MS = 10_000;
+/** An id no request ever had. */
+const UNKNOWN_REQUEST = 2 ** 40;
+/** The cheapest call the plugin answers without doing work: a method that takes a list of projects or manifests, asked about none. */
+function probeOf(client) {
+    const timeoutMs = 2 * 60 * 1000;
+    if (client.supports('discover'))
+        return signal => client.call('discover', { manifests: [] }, { timeoutMs, signal });
+    if (client.supports('contribute'))
+        return signal => client.call('contribute', { projects: [] }, { timeoutMs, signal });
+    if (client.supports('ci'))
+        return signal => client.call('ci', { projects: [] }, { timeoutMs, signal });
+    return client.supports('doctor') ? signal => client.call('doctor', { projects: [] }, { timeoutMs, signal }) : undefined;
+}
+function messageOf(thrown) {
+    return thrown instanceof Error ? thrown.message : String(thrown);
+}
+/**
+ * Checks what a plugin says about how it is called: the concurrency it
+ * declares must be one the protocol defines and be accepted, and the cancel it
+ * advertises must stop a request within a bound and leave the plugin serving.
+ * The same checks, under the same names, as the Go SDK's.
+ */
+export async function checkScheduling(client, report, cancelBoundMs = CANCEL_BOUND_MS) {
+    const info = client.info;
+    report.add('declares a concurrency the protocol defines', isValidConcurrency(info.concurrency ?? 0), `concurrency ${info.concurrency} is below -1; it must be absent, 1 or more, or -1 for unlimited`);
+    const probe = probeOf(client);
+    if (probe === undefined)
+        return;
+    await checkConcurrency(client, probe, report);
+    if (info.capabilities.cancel === true)
+        await checkCancel(client, probe, report, cancelBoundMs);
+}
+/**
+ * Sends requests together. A plugin that declares nothing is sent them one at
+ * a time and must answer them all; one that declares a concurrency is sent that
+ * many at once (at most four, to keep the check cheap) and must answer them all.
+ */
+async function checkConcurrency(client, probe, report) {
+    const limit = inFlightLimit(client.info.concurrency);
+    let together = Math.min(limit, 4);
+    let name = `accepts ${together} requests at the same time`;
+    if (limit === 1) {
+        together = 3;
+        name = 'answers 3 requests sent together, one at a time';
+    }
+    const settled = await Promise.allSettled(Array.from({ length: together }, async () => await probe()));
+    const failed = settled.find((result) => result.status === 'rejected');
+    const peak = client.peakInFlight;
+    report.add(name, failed === undefined && peak <= limit, `${failed === undefined ? '<nil>' : messageOf(failed.reason)} (the host had ${peak} in flight, the plugin declared ${limit})`);
+}
+/** How a promise ended: with the error it rejected with, if any. */
+async function settle(promise) {
+    try {
+        await promise;
+        return {};
+    }
+    catch (error) {
+        return { error };
+    }
+}
+/** Cancels a request, then a request that does not exist. */
+async function checkCancel(client, probe, report, cancelBoundMs) {
+    const controller = new AbortController();
+    const began = Date.now();
+    const request = settle(probe(controller.signal));
+    await new Promise(resolve => setTimeout(resolve, 5)); // let the request leave; a cancel that wins the race is just as good an answer
+    controller.abort();
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => { resolve('late'); }, cancelBoundMs + client.cancelGraceMs);
+    });
+    const outcome = await Promise.race([request, late]);
+    clearTimeout(timer);
+    const error = outcome === 'late' ? new Error(`no answer within ${cancelBoundMs}ms of the cancel`) : outcome.error;
+    const stopped = outcome !== 'late' && (error === undefined || (error instanceof CallInterruptedError && !error.killed));
+    const detail = `${error === undefined ? '<nil>' : messageOf(error)} (a plugin that advertised cancel answers the request, with ${ERROR_CODES.RequestCancelled} if it stopped, within ${cancelBoundMs}ms)`;
+    report.add('answers a cancelled request with its result or the cancelled error', stopped && Date.now() - began < cancelBoundMs, detail);
+    let notifyError;
+    let followUp;
+    try {
+        await client.notify('cancel', { id: UNKNOWN_REQUEST });
+    }
+    catch (error_) {
+        notifyError = error_;
+    }
+    try {
+        await probe();
+    }
+    catch (error_) {
+        followUp = error_;
+    }
+    report.add('ignores a cancel for a request it does not know', notifyError === undefined && followUp === undefined, `${notifyError === undefined ? '<nil>' : messageOf(notifyError)}, then ${followUp === undefined ? '<nil>' : messageOf(followUp)}`);
+}

package/conformance/conformance-report.model.d.ts

@@ -0,0 +1,22 @@
+import type { Peer } from '../protocol/index.ts';
+/** One check: its name, whether it held, and, when it did not, what is wrong. */
+export interface CheckResult {
+    check: string;
+    ok: boolean;
+    detail?: string;
+}
+/**
+ * Every check run against one plugin. `JSON.stringify(report)` gives the shape
+ * `smith plugin check --json` prints: `{ plugin, results }`.
+ */
+export declare class ConformanceReport {
+    readonly plugin: Peer;
+    readonly results: CheckResult[];
+    constructor(plugin: Peer);
+    /** Whether every check passed. */
+    get ok(): boolean;
+    /** The failed checks, one per line: `check: detail`. */
+    failures(): string;
+    /** Records a check. The detail is kept only for a check that failed. */
+    add(check: string, ok: boolean, detail: string): void;
+}

package/conformance/conformance-report.model.js

@@ -0,0 +1,23 @@
+/**
+ * Every check run against one plugin. `JSON.stringify(report)` gives the shape
+ * `smith plugin check --json` prints: `{ plugin, results }`.
+ */
+export class ConformanceReport {
+    plugin;
+    results = [];
+    constructor(plugin) {
+        this.plugin = plugin;
+    }
+    /** Whether every check passed. */
+    get ok() {
+        return this.results.every(result => result.ok);
+    }
+    /** The failed checks, one per line: `check: detail`. */
+    failures() {
+        return this.results.filter(result => !result.ok).map(result => `${result.check}: ${result.detail ?? ''}`).join('\n');
+    }
+    /** Records a check. The detail is kept only for a check that failed. */
+    add(check, ok, detail) {
+        this.results.push(ok ? { check, ok } : { check, ok, detail });
+    }
+}

package/conformance/find-manifests.algorithm.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The manifests of a plugin below a workspace, workspace-relative with forward
+ * slashes: files named like `names` (see isManifest), skipping dot-folders and
+ * dependency folders, and files at the root itself, as the Go conformance
+ * suite does.
+ */
+export declare function findManifests(workspace: string, names: readonly string[]): string[];

package/conformance/find-manifests.algorithm.js

@@ -0,0 +1,34 @@
+import { readdirSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { isManifest } from '../projects/index.js';
+const SKIPPED_FOLDERS = new Set(['node_modules', '__pycache__']);
+/**
+ * The manifests of a plugin below a workspace, workspace-relative with forward
+ * slashes: files named like `names` (see isManifest), skipping dot-folders and
+ * dependency folders, and files at the root itself, as the Go conformance
+ * suite does.
+ */
+export function findManifests(workspace, names) {
+    const found = [];
+    const walk = (relative) => {
+        const folder = join(workspace, ...relative.split('/').filter(part => part !== ''));
+        const entries = readdirSync(folder, { withFileTypes: true });
+        for (const entry of entries) {
+            const path = relative === '' ? entry.name : `${relative}/${entry.name}`;
+            if (entry.isDirectory()) {
+                if (!entry.name.startsWith('.') && !SKIPPED_FOLDERS.has(entry.name))
+                    walk(path);
+            }
+            else if (isManifest(names, entry.name) && posix.dirname(path) !== '.') {
+                found.push(path);
+            }
+        }
+    };
+    try {
+        walk('');
+    }
+    catch {
+        // An unreadable folder ends the walk; what was found stays.
+    }
+    return found;
+}

package/conformance/go-list.mapper.d.ts

@@ -0,0 +1,4 @@
+/** A list as Go's `%v` writes it, `[a b]`, which the details of the Go checks use; the TypeScript checks keep their text the same. */
+export declare function goList(items: readonly unknown[]): string;
+/** A string as Go's `%q` writes it. */
+export declare function goQuote(text: string): string;

package/conformance/go-list.mapper.js

@@ -0,0 +1,8 @@
+/** A list as Go's `%v` writes it, `[a b]`, which the details of the Go checks use; the TypeScript checks keep their text the same. */
+export function goList(items) {
+    return `[${items.map(String).join(' ')}]`;
+}
+/** A string as Go's `%q` writes it. */
+export function goQuote(text) {
+    return JSON.stringify(text);
+}

package/conformance/index.d.ts

@@ -0,0 +1,5 @@
+export { checkPlugin } from './check-plugin.use-case.ts';
+export type { CheckOptions } from './check-plugin.use-case.ts';
+export { CONFORMANCE_STACK } from './check-generation.use-case.ts';
+export { ConformanceReport } from './conformance-report.model.ts';
+export type { CheckResult } from './conformance-report.model.ts';

package/conformance/index.js

@@ -0,0 +1,3 @@
+export { checkPlugin } from './check-plugin.use-case.js';
+export { CONFORMANCE_STACK } from './check-generation.use-case.js';
+export { ConformanceReport } from './conformance-report.model.js';