@aloma.io/integration-sdk 3.8.67 → 3.8.69

package/test/harness.test.mjs

@@ -0,0 +1,375 @@
+// Tests for the connector test harness (src/testing) and, through it, the SDK's
+// handshake, dispatch and result-return paths. No test reaches the network:
+// the only sockets are on 127.0.0.1 and vendor HTTP is mocked.
+import http from 'node:http';
+import {describe, it, afterEach} from 'mocha';
+import {expect} from 'chai';
+import {Transport} from '../build/internal/websocket/transport/index.mjs';
+import {Connector} from '../build/internal/connector/index.mjs';
+import Fetcher from '../build/internal/fetcher/fetcher.mjs';
+import {ConnectorHarness, FakeAloma, VendorMock} from '../build/testing/index.mjs';
+
+const VENDOR = 'https://api.vendor.example.test';
+
+// A tiny connector, wired the way the SDK wires a connector repo's controller.
+function exampleConnector(seen = {}) {
+  const connector = new Connector({id: 'example-connector', version: '1.2.3', name: 'Example Connector'});
+
+  connector
+    .configure()
+    .config({
+      fields: {
+        apiKey: {name: 'API Key', type: 'line'},
+        region: {name: 'Region', type: 'line', plain: true},
+      },
+    })
+    .types('type Query { echo: String }')
+    .resolvers({
+      echo: async (args) => args,
+      shout: async ({text}) => String(text).toUpperCase(),
+      whoami: async (_args, ctx) => ({ctx}),
+      nested: {deep: {method: async () => ({found: true})}},
+      getItem: async ({id}) => {
+        const client = seen.getClient({
+          baseUrl: VENDOR,
+          retry: 1,
+          customize: (o) => {
+            o.headers = {...o.headers, Authorization: `Bearer ${seen.config.apiKey}`};
+          },
+        });
+        return client.fetch(`/items/${id}`, {method: 'GET'});
+      },
+      createItem: async (body) => {
+        const client = seen.getClient({baseUrl: VENDOR, retry: 1});
+        return client.fetch('/items', {method: 'POST', body});
+      },
+      forgottenMock: async () => new Fetcher({retry: 1}).fetch('https://not-mocked.example.test/x'),
+      rawSocket: async () =>
+        new Promise((resolve, reject) => {
+          http.get('http://203.0.113.9/', () => resolve({reached: true})).on('error', reject);
+        }),
+      boom: async () => {
+        throw new Error('kaput');
+      },
+      makeBlob: async () => ({id: await seen.createBlob({name: 'a.txt'})}),
+    })
+    .main((arg) => {
+      seen.config = arg.config;
+      seen.getClient = arg.getClient;
+      seen.createBlob = arg.createBlob;
+      seen.starts = (seen.starts || 0) + 1;
+    });
+
+  return connector;
+}
+
+describe('connector test harness', function () {
+  this.timeout(15000);
+
+  let harness;
+  let seen;
+  const realFetch = globalThis.fetch;
+
+  const start = async (extra = {}) => {
+    seen = {};
+    harness = await ConnectorHarness.start({
+      connector: exampleConnector(seen),
+      config: {apiKey: 'fake-api-key-not-real', region: 'eu-test'},
+      ...extra,
+    });
+    return harness;
+  };
+
+  afterEach(async () => {
+    if (harness) await harness.stop({verify: false});
+    harness = undefined;
+  });
+
+  describe('handshake', () => {
+    it('registers, connects and opens the websocket', async () => {
+      await start();
+      const {aloma} = harness;
+
+      expect(aloma.connected).to.equal(true);
+      expect(aloma.registrations).to.have.length(1);
+      expect(aloma.protocolErrors).to.deep.equal([]);
+      // first connect has no token and is told to register (401), the second carries the issued token
+      expect(aloma.connects.map((c) => c.authorized)).to.deep.equal([false, true]);
+    });
+
+    it('registers id, version, name, a public key and the schema', async () => {
+      await start();
+      const body = harness.aloma.registration;
+
+      expect(body.id).to.equal('example-connector');
+      expect(body.version).to.equal('1.2.3');
+      expect(body.name).to.equal('Example Connector');
+      expect(body.publicKey).to.be.a('string').with.length.greaterThan(100);
+      expect(body.schema.configSchema.fields).to.have.keys('apiKey', 'region');
+      expect(body.schema.introspect).to.equal('type Query { echo: String }');
+      expect(harness.aloma.connects[1].headers['user-agent']).to.equal('example-connector/1.2.3');
+    });
+
+    it('delivers encrypted config decrypted and plain config as is, then runs main() once', async () => {
+      await start();
+
+      expect(seen.config).to.deep.equal({apiKey: 'fake-api-key-not-real', region: 'eu-test'});
+      expect(seen.starts).to.equal(1);
+    });
+
+    it('answers connector.introspect with the schema and types', async () => {
+      await start();
+      const answer = await harness.aloma.introspect();
+
+      expect(answer.introspect).to.equal('type Query { echo: String }');
+      expect(answer.configSchema.fields.apiKey.name).to.equal('API Key');
+    });
+
+    it('can be started and stopped repeatedly without leaking state', async () => {
+      for (let i = 0; i < 3; i++) {
+        await start();
+        expect(await harness.call('shout', {text: 'x'})).to.deep.equal({shout: 'X'});
+        await harness.stop();
+        harness = undefined;
+      }
+      expect(globalThis.fetch).to.equal(realFetch);
+    });
+  });
+
+  describe('method calls', () => {
+    it('round-trips an object result unchanged', async () => {
+      await start();
+      expect(await harness.call('echo', {a: 1, b: ['x']})).to.deep.equal({a: 1, b: ['x']});
+    });
+
+    it('wraps a non-object result under the method name', async () => {
+      await start();
+      expect(await harness.call('shout', {text: 'hello'})).to.deep.equal({shout: 'HELLO'});
+    });
+
+    it('resolves nested methods addressed by a path array', async () => {
+      await start();
+      expect(await harness.call(['nested', 'deep', 'method'])).to.deep.equal({found: true});
+    });
+
+    it('forwards taskId, namespace and sticky as ctx', async () => {
+      await start();
+      const answer = await harness.call('whoami', {}, {taskId: 't-1', namespace: 'ns', sticky: true});
+
+      expect(answer.ctx).to.deep.equal({taskId: 't-1', namespace: 'ns', sticky: true});
+    });
+
+    it('answers concurrent calls independently', async () => {
+      await start();
+      const results = await Promise.all([1, 2, 3, 4, 5].map((n) => harness.call('echo', {n})));
+
+      expect(results.map((r) => r.n)).to.deep.equal([1, 2, 3, 4, 5]);
+    });
+
+    it('serves connector-initiated requests through the fake endpoint (blobs)', async () => {
+      await start();
+      harness.aloma.handle('connector.blob.create', (args) => (args.name === 'a.txt' ? {id: 'blob-1'} : {error: 'bad'}));
+
+      expect(await harness.call('makeBlob')).to.deep.equal({id: 'blob-1'});
+    });
+  });
+
+  describe('vendor HTTP mock', () => {
+    it('answers the connector vendor call from a recorded response', async () => {
+      await start();
+      harness.vendor.get(`${VENDOR}/items/7`, {json: {id: 7, name: 'recorded'}});
+
+      expect(await harness.call('getItem', {id: 7})).to.deep.equal({id: 7, name: 'recorded'});
+      expect(harness.vendor.requests).to.have.length(1);
+      expect(harness.vendor.requests[0].headers.authorization).to.equal('Bearer fake-api-key-not-real');
+    });
+
+    it('lets a responder function see the request body and choose the reply', async () => {
+      await start();
+      harness.vendor.post(`${VENDOR}/items`, (req) => ({status: 201, json: {created: JSON.parse(req.body)}}));
+
+      expect(await harness.call('createItem', {name: 'new'})).to.deep.equal({created: {name: 'new'}});
+    });
+
+    it('records the url the Fetcher really sends', async () => {
+      await start();
+      harness.vendor.get(`${VENDOR}/items/1`, {json: {}});
+      await harness.call('getItem', {id: 1});
+
+      // PINS SUSPECT BEHAVIOUR: Fetcher joins baseUrl + path and then collapses every run of slashes with
+      // .replace(/\/\/+/g, '/'), so "https://host" becomes "https:/host". Node's URL parser repairs
+      // this for http(s), but the same replace would also damage a "//" inside a query value.
+      expect(harness.vendor.requests[0].url).to.equal('https://api.vendor.example.test/items/1');
+      expect(harness.vendor.requests[0].rawUrl).to.equal('https:/api.vendor.example.test/items/1');
+    });
+
+    it('turns a vendor error status into a method error', async () => {
+      await start();
+      harness.vendor.get(/\/items\/9$/, {status: 404, text: 'no such item'});
+
+      const answer = await harness.call('getItem', {id: 9});
+      expect(answer.error).to.match(/404 no such item/);
+    });
+
+    it('rejects an unmocked request, reports it to the connector and fails the test on stop()', async () => {
+      await start();
+      const answer = await harness.call('forgottenMock');
+
+      expect(answer.error).to.match(/UNMOCKED vendor request: GET https:\/\/not-mocked\.example\.test\/x/);
+      expect(harness.vendor.unmocked).to.have.length(1);
+
+      let failure;
+      try {
+        await harness.stop();
+      } catch (e) {
+        failure = e;
+      }
+      harness = undefined;
+      expect(failure, 'stop() must fail when an unmocked request happened').to.be.instanceOf(Error);
+      expect(failure.message).to.match(/UNMOCKED vendor requests/);
+    });
+
+    it('blocks raw sockets to non-loopback hosts even when fetch is bypassed', async () => {
+      await start();
+      const answer = await harness.call('rawSocket');
+
+      expect(answer.error).to.match(/NETWORK BLOCKED/);
+    });
+
+    it('restores fetch and the network guard on stop()', async () => {
+      await start();
+      expect(globalThis.fetch).to.not.equal(realFetch);
+      await harness.stop();
+      harness = undefined;
+
+      expect(globalThis.fetch).to.equal(realFetch);
+    });
+
+    it('limits a route with times and can assert every route was used', async () => {
+      const vendor = new VendorMock();
+      vendor.get('https://a.example.test/x', {json: {n: 1}}, {times: 1});
+      vendor.get('https://b.example.test/never', {json: {}});
+      vendor.install();
+      try {
+        const first = await globalThis.fetch('https://a.example.test/x');
+        expect(await first.json()).to.deep.equal({n: 1});
+
+        let failure;
+        try {
+          await globalThis.fetch('https://a.example.test/x');
+        } catch (e) {
+          failure = e;
+        }
+        expect(failure && failure.message).to.match(/UNMOCKED/);
+        expect(() => vendor.verifyAllRoutesUsed()).to.throw(/never called/);
+        expect(() => vendor.verify()).to.throw(/UNMOCKED/);
+      } finally {
+        vendor.uninstall();
+      }
+    });
+  });
+
+  describe('failing connectors', () => {
+    it('reports a throwing method as an error answer and keeps serving', async () => {
+      await start();
+
+      expect(await harness.call('boom')).to.deep.equal({error: 'Error: kaput'});
+      expect(await harness.call('shout', {text: 'still up'})).to.deep.equal({shout: 'STILL UP'});
+    });
+
+    it('reports an unknown method as an error answer', async () => {
+      await start();
+      const answer = await harness.call('doesNotExist');
+
+      expect(answer.error).to.match(/doesNotExist not found/);
+    });
+
+    it('callOk() throws when the connector answered with an error', async () => {
+      await start();
+      let failure;
+      try {
+        await harness.callOk('boom');
+      } catch (e) {
+        failure = e;
+      }
+      expect(failure.message).to.match(/boom failed: Error: kaput/);
+    });
+
+    it('fails start() with the cause when main() throws', async () => {
+      const connector = new Connector({id: 'broken-main', version: '0.0.1', name: 'Broken'});
+      connector
+        .configure()
+        .config({fields: {k: {name: 'K', type: 'line'}}})
+        .types('type Query { x: String }')
+        .resolvers({x: async () => 1})
+        .main(() => {
+          throw new Error('cannot start');
+        });
+
+      let failure;
+      try {
+        await ConnectorHarness.start({connector, config: {k: 'v'}});
+      } catch (e) {
+        failure = e;
+      }
+      expect(failure && failure.message).to.equal('cannot start');
+    });
+  });
+
+  describe('pinned SDK behaviour', () => {
+    it('Transport.close() never terminates the websocket', () => {
+      // PINS SUSPECT BEHAVIOUR: Transport.close() calls local.ws.terminate(), but `local` is not defined in
+      // close() (it is only defined in the other methods). The ReferenceError is swallowed by the try/catch,
+      // so close() clears its timers and flags but leaves the socket open. Today a closed connector relies on
+      // the server side (or process exit) to drop the connection.
+      const transport = new Transport({config: {}, onMessage() {}, onConnect() {}});
+      let terminated = false;
+      transport.ws = {terminate: () => (terminated = true)};
+
+      transport.close();
+
+      expect(transport.running).to.equal(false);
+      expect(transport.connected).to.equal(false);
+      expect(terminated).to.equal(false);
+    });
+  });
+
+  describe('fake ALOMA strictness', () => {
+    let aloma;
+    afterEach(async () => aloma && (await aloma.close()));
+
+    it('refuses registration with a wrong registration token and records it', async () => {
+      aloma = await FakeAloma.start();
+      const response = await fetch(`${aloma.url}register`, {
+        method: 'POST',
+        body: '{}',
+        headers: {Authorization: 'Connector wrong-token'},
+      });
+
+      expect(response.status).to.equal(401);
+      expect(aloma.protocolErrors.join()).to.match(/wrong registration token/);
+    });
+
+    it('answers /connect with 401 until a token was issued by registering', async () => {
+      aloma = await FakeAloma.start();
+      const response = await fetch(`${aloma.url}connect`, {
+        method: 'POST',
+        body: '{}',
+        headers: {Authorization: 'Connector null'},
+      });
+
+      expect(response.status).to.equal(401);
+    });
+
+    it('times out with a diagnostic when no connector connects', async () => {
+      aloma = await FakeAloma.start();
+      let failure;
+      try {
+        await aloma.waitForConnection(50);
+      } catch (e) {
+        failure = e;
+      }
+      expect(failure.message).to.match(/did not connect within 50ms/);
+    });
+  });
+});

package/test/openapi-to-connector.test.mts

@@ -141,7 +141,9 @@ paths:
     it('should reject invalid JSON/YAML', () => {
       expect(() => {
         OpenAPIToConnector.parseSpec('invalid json {');
-      }).to.throw('Failed to parse OpenAPI spec');
+      // PINS: expectation updated to today's output on 24 Oct; original expected 'Failed to parse OpenAPI spec'.
+      // 'invalid json {' is not JSON, but js-yaml loads it as a plain string, so it is rejected by the schema check.
+      }).to.throw('Invalid OpenAPI 3.x specification');
     });
   });
 
@@ -152,9 +154,12 @@ paths:
       
       expect(controllerCode).to.include('import {AbstractController}');
       expect(controllerCode).to.include('export default class Controller extends AbstractController');
-      expect(controllerCode).to.include('async getUsers(args: any)');
-      expect(controllerCode).to.include('async createUser(args: any)');
-      expect(controllerCode).to.include('async get_users_{id}(args: any)');
+      // PINS: expectation updated to today's output on 24 Oct; original expected 'async getUsers(args: any)',
+      // 'async createUser(args: any)' and 'async get_users_{id}(args: any)' (an older args-object signature; the
+      // third name never matched the spec's operationId getUserById, path params are now positional).
+      expect(controllerCode).to.include('async getUsers(options?: {headers?: Record<string, string>})');
+      expect(controllerCode).to.include('async createUser(options');
+      expect(controllerCode).to.include('async getUserById(id: string, options?: {headers?: Record<string, string>})');
     });
 
     it('should generate proper JSDoc comments', () => {
@@ -163,8 +168,20 @@ paths:
       
       expect(controllerCode).to.include('* Get all users');
       expect(controllerCode).to.include('* Retrieve a list of all users');
-      expect(controllerCode).to.include('* @param args.body - Request body');
-      expect(controllerCode).to.include('* @param args.id - User ID');
+      // PINS: expectation updated to today's output on 24 Oct; original expected '* @param args.body - Request body'
+      // and '* @param args.id - User ID' (older args-object JSDoc; the object body is now expanded into its properties).
+      expect(controllerCode).to.include('* @param {string} options.name (required)');
+      expect(controllerCode).to.include('* @param {string} id User ID');
+    });
+
+    it('should substitute path parameters into the url', () => {
+      // Added on 24 Oct with the entry-point fix: nothing asserted the generated path parameter handling before.
+      const generator = new OpenAPIToConnector(validOpenAPISpec, 'Test Connector');
+      const controllerCode = generator.generateController();
+
+      expect(controllerCode).to.include("let url = '/users/{id}';");
+      expect(controllerCode).to.include('if (id) {');
+      expect(controllerCode).to.include("url = url.replace('{id}', id);");
     });
 
     it('should handle operations without operationId', () => {
@@ -187,7 +204,8 @@ paths:
       const generator = new OpenAPIToConnector(specWithoutOperationId, 'Test Connector');
       const controllerCode = generator.generateController();
       
-      expect(controllerCode).to.include('async get_test(args: any)');
+      // PINS: expectation updated to today's output on 24 Oct; original expected 'async get_test(args: any)'.
+      expect(controllerCode).to.include('async get_test(options?: {headers?: Record<string, string>})');
     });
 
     it('should throw error for empty spec', () => {

package/test/scenarios.test.mts

@@ -44,8 +44,13 @@ describe('Scenario Tests - Full Code Generation', () => {
       const actualOutput = generator.generateController();
       
       // Verify methods without options don't have unnecessary code
-      expect(actualOutput).to.include('async getProducts() {'); // No options parameter
-      expect(actualOutput).to.not.include('options = options || {}'); // No options initialization for getProducts
+      // PINS: expectation updated to today's output on 24 Oct; original expected 'async getProducts() {'.
+      // Since the headers type fix (f2d55a0, Bug C) every method takes an optional options with headers.
+      expect(actualOutput).to.include('async getProducts(options?: {headers?: Record<string, string>}) {');
+      // PINS: expectation updated to today's output on 24 Oct; original asserted this on the whole output, which also
+      // contains createProduct's (legitimate) initialization, so it is now scoped to the getProducts method only.
+      const getProductsBody = actualOutput.slice(actualOutput.indexOf('async getProducts('), actualOutput.indexOf('async createProduct('));
+      expect(getProductsBody).to.not.include('options = options || {}'); // No options initialization for getProducts
       expect(actualOutput).to.include('async createProduct(options:'); // Has options parameter
       expect(actualOutput).to.include('options = options || {};'); // Has options initialization for createProduct
     });
@@ -163,13 +168,15 @@ describe('Scenario Tests - Full Code Generation', () => {
       const actualOutput = generator.generateResourceClass('OrdersResource');
       
       // Verify path parameters are handled correctly
-      expect(actualOutput).to.include('export function getOrder(this: any, orderId: string)');
+      // PINS: expectation updated to today's output on 24 Oct; original expected 'getOrder(this: any, orderId: string)'
+      // and 'cancelOrder(this: any, orderId: string)' with no trailing options (stale since the headers type fix, Bug C).
+      expect(actualOutput).to.include('export function getOrder(this: any, orderId: string, options?: {headers?: Record<string, string>})');
       expect(actualOutput).to.include('export function updateOrderStatus(this: any, orderId: string, options');
-      expect(actualOutput).to.include('export function cancelOrder(this: any, orderId: string)');
+      expect(actualOutput).to.include('export function cancelOrder(this: any, orderId: string, options?: {headers?: Record<string, string>})');
       
       // Verify methods without options don't have unnecessary code
-      expect(actualOutput).to.match(/export function getOrder\(this: any, orderId: string\) \{/);
-      expect(actualOutput).to.match(/export function cancelOrder\(this: any, orderId: string\) \{/);
+      expect(actualOutput).to.match(/export function getOrder\(this: any, orderId: string, options\?: \{headers\?: Record<string, string>\}\) \{/);
+      expect(actualOutput).to.match(/export function cancelOrder\(this: any, orderId: string, options\?: \{headers\?: Record<string, string>\}\) \{/);
     });
 
     it('should correctly expose resource methods in main controller', () => {
@@ -278,7 +285,8 @@ describe('Scenario Tests - Full Code Generation', () => {
       const output = generator.generateController();
       
       // Should not have options parameter or initialization
-      expect(output).to.include('async getSimple() {');
+      // PINS: expectation updated to today's output on 24 Oct; original expected 'async getSimple() {' (stale since Bug C).
+      expect(output).to.include('async getSimple(options?: {headers?: Record<string, string>}) {');
       expect(output).to.not.include('options = options || {}');
       expect(output).to.not.include('headers: options');
     });

package/test/transform.test.mjs

@@ -0,0 +1,68 @@
+// The transform reads a connector's controller source and returns the method declarations (`text`) and names
+// (`methods`) that `cli build` writes to build/.controller.json. It replaced @ts-ast-parser/core (engines stop at
+// Node 20), so most cases below are PARITY cases: expected.json was produced by the previous implementation (the
+// ts-ast-parser one, SDK 3.8.68) on the same source, and the new one must print exactly the same. The same check
+// ran on 58 real connector controllers (all of aloma-io/connector-*) with no difference.
+// Needs `yarn build` first. Offline.
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {describe, it} from 'mocha';
+import transform from '../build/transform/index.mjs';
+
+const fixtures = path.join(path.dirname(fileURLToPath(import.meta.url)), 'fixtures', 'transform');
+
+// the transform reads tsconfig.json from the working directory, as `cli build` runs it from the connector folder
+const run = async (name) => {
+  const before = process.cwd();
+  process.chdir(path.join(fixtures, name));
+  try {
+    return await transform('./src/controller/index.mts');
+  } finally {
+    process.chdir(before);
+  }
+};
+
+const expected = (name) => JSON.parse(fs.readFileSync(path.join(fixtures, name, 'expected.json'), 'utf8'));
+
+describe('transform (controller source to declarations)', function () {
+  this.timeout(60000);
+
+  for (const [name, what] of [
+    ['basic', 'JSDoc description, @param, @example, @namespace, defaults, return types'],
+    ['visibility', 'public, private, protected, static, underscore, quoted names, arrow property, getter, inherited'],
+    ['typed', 'typed object parameters, unions, arrays, tuples, optional'],
+    ['overloads', 'one declaration per overload signature'],
+    ['tdd-stub', 'the real connector-tdd-stub controller'],
+  ]) {
+    it(`prints exactly what the previous implementation printed: ${name} (${what})`, async () => {
+      assert.deepEqual(await run(name), expected(name));
+    });
+  }
+
+  it('lists the public methods the class declares or overrides, not inherited, private, static or underscore ones', async () => {
+    const {methods} = await run('visibility');
+    assert.deepEqual(methods, ['visible', 'quoted-name', 'arrow', 'inheritedPublic']);
+  });
+
+  it('lists the properties of a parameter typed with an interface (the previous implementation crashed)', async () => {
+    const {text, methods} = await run('interface-param');
+    assert.deepEqual(methods, ['viaInterface']);
+    assert.match(text, /declare function viaInterface\(\{id; n\}: \{/);
+    assert.match(text, /\n id: string; /);
+    assert.match(text, /\n n: number \| undefined\}\): \{ id: string; n: number \| undefined; \};/);
+  });
+
+  it('fails when the file exports more than the default class', async () => {
+    await assert.rejects(run('two-exports'), /connector file needs to export default class/);
+  });
+
+  it('fails with the TypeScript error text when the source does not compile (the previous one died on a circular JSON error)', async () => {
+    await assert.rejects(run('type-error'), (err) => {
+      assert.match(err.message, /has TypeScript errors/);
+      assert.match(err.message, /index\.mts\(5,5\).*TS2322.*'string' is not assignable to type 'number'/);
+      return true;
+    });
+  });
+});

package/tools/mutation-run-entry.mjs

@@ -0,0 +1,52 @@
+// Mutation check for the SDK tests that `yarn test` now runs (openapi-to-connector generator tests, scenarios).
+//
+//   yarn build && node tools/mutation-run-entry.mjs
+//
+// Applies each single-point bug to src/openapi-to-connector.mts, rebuilds, runs `yarn test` and expects it to FAIL.
+// The source file is restored after every mutant (and on exit). Prints a markdown table.
+import {spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const file = path.join(root, 'src/openapi-to-connector.mts');
+const original = fs.readFileSync(file, 'utf8');
+const restore = () => fs.writeFileSync(file, original);
+process.on('exit', restore);
+process.on('SIGINT', () => process.exit(130));
+
+// [id, exact text (must occur once), replacement, bug]
+const MUTANTS = [
+  ['E01', "method: method.toUpperCase(),\n          path,", "method: method.toLowerCase(),\n          path,", 'the HTTP verb is taken in lower case'],
+  ['E02', "lines.push(`    if (${paramName}) {`);\n        lines.push(`      url = url.replace('{${paramName}}', ${paramName});`);\n        lines.push(`    }`);\n      }", "lines.push(`    if (!${paramName}) {`);\n        lines.push(`      url = url.replace('{${paramName}}', ${paramName});`);\n        lines.push(`    }`);\n      }", 'path parameter substitution is guarded by the wrong condition'],
+  ['E03', "return `${methodPrefix}_${pathSuffix}`;", "return `${methodPrefix}${pathSuffix}`;", 'fallback method name drops the separator'],
+  ['E04', "const requiredText = propRequired ? '(required)' : '(optional)';", "const requiredText = propRequired ? '(optional)' : '(required)';", 'body properties are documented with the wrong required flag'],
+  ['E05', "    // Always include headers in options type (generated code references options.headers)\n    optionProps.push('headers?: Record<string, string>');", "    // Always include headers in options type (generated code references options.headers)", 'headers are dropped from the generated options type'],
+  ['E06', "lines.push(`    options = options || {};`);", "lines.push(`    // no options default`);", 'options is not defaulted in generated methods'],
+  ['E07', "if (criticalErrors.length > 0) {", "if (false) {", 'invalid specs are no longer rejected'],
+  ['E08', "const propRequired = (schema.required && schema.required.includes(propName)) || requestBody.required;", "const propRequired = (schema.required && schema.required.includes(propName)) && requestBody.required;", 'a property is required only if both the schema and the body say so'],
+];
+
+const sh = (args) => spawnSync('npx', ['--yes', 'yarn@1.22.22', '-s', ...args], {cwd: root, encoding: 'utf8'});
+const rows = [];
+let survived = 0;
+for (const [id, find, repl, bug] of MUTANTS) {
+  const n = original.split(find).length - 1;
+  if (n !== 1) { console.error(`${id}: pattern occurs ${n} times, expected 1`); process.exit(2); }
+  fs.writeFileSync(file, original.replace(find, repl));
+  const b = sh(['build']);
+  let result;
+  if (b.status !== 0) result = 'build failed (not counted)';
+  else {
+    const t = sh(['test']);
+    result = t.status !== 0 ? 'killed' : 'SURVIVED';
+    if (t.status === 0) survived++;
+  }
+  restore();
+  rows.push(`| ${id} | ${bug} | ${result} |`);
+  console.log(rows.at(-1));
+}
+sh(['build']);
+console.log(`\n${MUTANTS.length - survived}/${MUTANTS.length} killed`);
+process.exit(survived ? 1 : 0);