serverless-ircd 0.1.0 → 0.2.0

package/tools/ci-hardening/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@serverless-ircd/ci-hardening",
+  "version": "0.2.0",
+  "private": true,
+  "description": "CI hardening helpers: coverage-gate config validator + mutation-testing driver for irc-core",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "start": "node --enable-source-maps ./dist/main.js",
+    "clean": "rimraf dist coverage .tsbuildinfo .turbo"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0"
+  }
+}

package/tools/ci-hardening/src/index.ts

@@ -0,0 +1,6 @@
+export {
+  MUTATION_SCORE_THRESHOLD,
+  readCoverageThresholds,
+  readStrykerConfig,
+  readWorkflowJob,
+} from './validate.js';

package/tools/ci-hardening/src/validate.ts

@@ -0,0 +1,103 @@
+import { readFileSync } from 'node:fs';
+import { load } from 'js-yaml';
+
+/**
+ * Minimum mutation score (in percent) required for the Stryker
+ * spot-checks on `irc-core/protocol` and `irc-core/commands`.
+ *
+ * Exported so the test-suite and any future dashboards can
+ * import the canonical value instead of re-hard-coding it.
+ */
+export const MUTATION_SCORE_THRESHOLD = 80;
+
+export interface CoverageThresholds {
+  lines: number;
+  functions: number;
+  branches: number;
+  statements: number;
+}
+
+interface StrykerThresholds {
+  high?: number;
+  low?: number;
+  break?: number | null;
+}
+
+interface StrykerConfig {
+  mutate?: unknown;
+  thresholds?: StrykerThresholds;
+  coverageAnalysis?: string;
+  testRunner?: string;
+  [key: string]: unknown;
+}
+
+interface WorkflowJob {
+  steps: Array<{ name?: string; run?: string; [key: string]: unknown }>;
+  [key: string]: unknown;
+}
+
+interface ParsedWorkflow {
+  jobs?: Record<string, WorkflowJob>;
+}
+
+/**
+ * Extract the `coverage.thresholds` block from a vitest config file.
+ *
+ * Vitest configs are plain TypeScript modules; rather than pulling in
+ * the full TS toolchain to evaluate them, we parse the source as text
+ * and pull out the `thresholds: { ... }` object. This deliberately
+ * fails loud (returns NaN-bearing values) if the config shape drifts,
+ * so the test-suite notices immediately.
+ *
+ * @param configPath absolute path to a vitest.config.ts file.
+ */
+export function readCoverageThresholds(configPath: string): CoverageThresholds {
+  const src = readFileSync(configPath, 'utf8');
+  const match = src.match(/thresholds:\s*\{([^}]*)\}/);
+  if (match === null || match[1] === undefined) {
+    throw new Error(`No coverage.thresholds block found in ${configPath}`);
+  }
+  const block = match[1];
+  const grab = (key: string): number => {
+    const m = block.match(new RegExp(`${key}:\\s*(\\d+)`));
+    if (m === null || m[1] === undefined) {
+      throw new Error(`No ${key} threshold found in ${configPath}`);
+    }
+    return Number.parseInt(m[1], 10);
+  };
+  return {
+    lines: grab('lines'),
+    functions: grab('functions'),
+    branches: grab('branches'),
+    statements: grab('statements'),
+  };
+}
+
+/**
+ * Load and validate a Stryker JSON config file.
+ *
+ * @param configPath absolute path to a `stryker.*.conf.json` file.
+ */
+export function readStrykerConfig(configPath: string): StrykerConfig {
+  const raw = readFileSync(configPath, 'utf8');
+  const parsed = JSON.parse(raw) as StrykerConfig;
+  if (!Array.isArray(parsed.mutate)) {
+    throw new Error(`Stryker config at ${configPath} is missing mutate[]`);
+  }
+  return parsed;
+}
+
+/**
+ * Parse a GitHub Actions YAML file and return the named job.
+ *
+ * @param yamlText raw YAML source of a workflow file.
+ * @param jobName key under `jobs:`.
+ */
+export function readWorkflowJob(yamlText: string, jobName: string): WorkflowJob {
+  const parsed = load(yamlText) as ParsedWorkflow;
+  const job = parsed.jobs?.[jobName];
+  if (job === undefined) {
+    throw new Error(`Workflow has no job named "${jobName}"`);
+  }
+  return job;
+}

package/tools/ci-hardening/tests/__no_thresholds__.txt

@@ -0,0 +1,11 @@
+// Fixture: vitest config with no thresholds block at all.
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+    },
+  },
+});

package/tools/ci-hardening/tests/__partial_thresholds__.txt

@@ -0,0 +1,16 @@
+// Fixture: vitest config with only some threshold keys present.
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    coverage: {
+      provider: 'v8',
+      thresholds: {
+        functions: 100,
+        branches: 100,
+        statements: 100,
+      },
+    },
+  },
+});

package/tools/ci-hardening/tests/__stryker_bad__.json

@@ -0,0 +1,4 @@
+{
+  "_comment": "Fixture: Stryker config without a mutate[] array. Used by the validator test to confirm readStrykerConfig throws loud.",
+  "testRunner": "vitest"
+}

package/tools/ci-hardening/tests/validate.test.ts

@@ -0,0 +1,177 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import {
+  MUTATION_SCORE_THRESHOLD,
+  readCoverageThresholds,
+  readStrykerConfig,
+  readWorkflowJob,
+} from '../src/validate.js';
+
+const REPO_ROOT = resolve(import.meta.dirname, '..', '..', '..');
+
+function repoPath(rel: string): string {
+  return resolve(REPO_ROOT, rel);
+}
+
+function readText(rel: string): string {
+  return readFileSync(repoPath(rel), 'utf8');
+}
+
+describe('coverage gate', () => {
+  it('enforces 100% line/function/branch/statement coverage on irc-core', () => {
+    const thresholds = readCoverageThresholds(repoPath('packages/irc-core/vitest.config.ts'));
+    expect(thresholds).toEqual({
+      lines: 100,
+      functions: 100,
+      branches: 100,
+      statements: 100,
+    });
+  });
+
+  it('enforces ≥90% coverage on cf-adapter', () => {
+    const thresholds = readCoverageThresholds(repoPath('packages/cf-adapter/vitest.config.ts'));
+    expect(thresholds.lines).toBeGreaterThanOrEqual(90);
+    expect(thresholds.functions).toBeGreaterThanOrEqual(90);
+    expect(thresholds.branches).toBeGreaterThanOrEqual(90);
+    expect(thresholds.statements).toBeGreaterThanOrEqual(90);
+  });
+
+  it('enforces ≥90% coverage on irc-server', () => {
+    const thresholds = readCoverageThresholds(repoPath('packages/irc-server/vitest.config.ts'));
+    expect(thresholds.lines).toBeGreaterThanOrEqual(90);
+    expect(thresholds.functions).toBeGreaterThanOrEqual(90);
+    expect(thresholds.branches).toBeGreaterThanOrEqual(90);
+    expect(thresholds.statements).toBeGreaterThanOrEqual(90);
+  });
+
+  it('enforces ≥90% coverage on in-memory-runtime', () => {
+    const thresholds = readCoverageThresholds(
+      repoPath('packages/in-memory-runtime/vitest.config.ts'),
+    );
+    expect(thresholds.lines).toBeGreaterThanOrEqual(90);
+    expect(thresholds.functions).toBeGreaterThanOrEqual(90);
+    expect(thresholds.branches).toBeGreaterThanOrEqual(90);
+    expect(thresholds.statements).toBeGreaterThanOrEqual(90);
+  });
+});
+
+describe('contract tests on every PR', () => {
+  it('runs the integration contract suite on PRs via ci.yml', () => {
+    const ci = readText('.github/workflows/ci.yml');
+    // Pull request trigger must be present so contract suite runs on PRs.
+    expect(ci).toMatch(/pull_request:/);
+    // The integration contract suite must be invoked. It ships as
+    // packages/cf-adapter/tests/integration (the parametrized harness
+    // that runs against every runtime) and is exercised by the
+    // workspace-wide coverage task. The gate step must explicitly
+    // reference the integration suite so it cannot be silently dropped.
+    expect(ci).toMatch(/integration/);
+    // Coverage must run on PRs (not only on main pushes).
+    const job = readWorkflowJob(ci, 'verify');
+    const runSteps = job.steps
+      .filter((s: { run?: unknown }) => typeof s.run === 'string')
+      .map((s: { run?: string }) => s.run ?? '');
+    const runsCoverage = runSteps.some((r) => r.includes('pnpm coverage'));
+    expect(runsCoverage).toBe(true);
+  });
+
+  it('has an explicit coverage-gate step that fails the build on regressions', () => {
+    const ci = readText('.github/workflows/ci.yml');
+    // The gate step name must make the failure mode obvious in the
+    // GitHub Actions UI.
+    expect(ci).toMatch(/coverage gate/i);
+    // The gate step must surface an explicit failure marker rather than
+    // relying on vitest's implicit threshold exit code alone.
+    expect(ci).toMatch(/coverage-thresholds/);
+  });
+});
+
+describe('mutation testing spot-check', () => {
+  it('exports a documented mutation-score threshold of ≥80%', () => {
+    expect(MUTATION_SCORE_THRESHOLD).toBeGreaterThanOrEqual(80);
+  });
+
+  it('ships a Stryker config that targets irc-core/protocol', () => {
+    const config = readStrykerConfig(repoPath('packages/irc-core/stryker.protocol.conf.json'));
+    expect(config.mutate).toEqual(
+      expect.arrayContaining([expect.stringMatching(/protocol\/[^/]+\.ts$/)]),
+    );
+    expect(config.thresholds?.high).toBeGreaterThanOrEqual(MUTATION_SCORE_THRESHOLD);
+    expect(config.thresholds?.break).toBe(MUTATION_SCORE_THRESHOLD);
+    // The config must disable Stryker's own coverage runner and reuse
+    // vitest's so the per-package coverage gate stays the source of
+    // truth for line/function coverage.
+    expect(config.coverageAnalysis).toBe('off');
+    expect(config.testRunner).toBe('vitest');
+    // Under pnpm's symlinked node_modules the Stryker child process
+    // cannot auto-discover the vitest plugin, so it must be listed
+    // explicitly.
+    expect(config.plugins).toEqual(['@stryker-mutator/vitest-runner']);
+  });
+
+  it('ships a Stryker config that targets irc-core/commands', () => {
+    const config = readStrykerConfig(repoPath('packages/irc-core/stryker.commands.conf.json'));
+    expect(config.mutate).toEqual(
+      expect.arrayContaining([expect.stringMatching(/commands\/[^/]+\.ts$/)]),
+    );
+    expect(config.thresholds?.high).toBeGreaterThanOrEqual(MUTATION_SCORE_THRESHOLD);
+    expect(config.thresholds?.break).toBe(MUTATION_SCORE_THRESHOLD);
+    expect(config.coverageAnalysis).toBe('off');
+    expect(config.testRunner).toBe('vitest');
+    expect(config.plugins).toEqual(['@stryker-mutator/vitest-runner']);
+  });
+
+  it('exposes a workspace-level mutation script that runs both spot-checks', () => {
+    const root = JSON.parse(readText('package.json')) as { scripts: Record<string, string> };
+    // Root scripts delegate to the irc-core package's stryker scripts.
+    expect(root.scripts['mutation:protocol']).toMatch(
+      /--filter @serverless-ircd\/irc-core mutation:protocol/,
+    );
+    expect(root.scripts['mutation:commands']).toMatch(
+      /--filter @serverless-ircd\/irc-core mutation:commands/,
+    );
+    expect(root.scripts.mutation).toMatch(/mutation:protocol/);
+    expect(root.scripts.mutation).toMatch(/mutation:commands/);
+
+    // The irc-core package must actually invoke stryker.
+    const ircCore = JSON.parse(readText('packages/irc-core/package.json')) as {
+      scripts: Record<string, string>;
+    };
+    expect(ircCore.scripts['mutation:protocol']).toMatch(
+      /stryker run stryker\.protocol\.conf\.json/,
+    );
+    expect(ircCore.scripts['mutation:commands']).toMatch(
+      /stryker run stryker\.commands\.conf\.json/,
+    );
+  });
+
+  it('runs mutation spot-checks in CI on every PR', () => {
+    const ci = readText('.github/workflows/ci.yml');
+    expect(ci).toMatch(/mutation/i);
+    expect(ci).toMatch(/stryker/);
+  });
+});
+
+describe('validate.ts error paths', () => {
+  it('readCoverageThresholds throws when no thresholds block exists', () => {
+    const tmpPath = repoPath('tools/ci-hardening/tests/__no_thresholds__.txt');
+    expect(() => readCoverageThresholds(tmpPath)).toThrow(/no thresholds block|No coverage/i);
+  });
+
+  it('readCoverageThresholds throws when a threshold key is missing', () => {
+    const tmpPath = repoPath('tools/ci-hardening/tests/__partial_thresholds__.txt');
+    expect(() => readCoverageThresholds(tmpPath)).toThrow(/No lines threshold/i);
+  });
+
+  it('readStrykerConfig throws when mutate is missing', () => {
+    const tmpPath = repoPath('tools/ci-hardening/tests/__stryker_bad__.json');
+    expect(() => readStrykerConfig(tmpPath)).toThrow(/missing mutate/);
+  });
+
+  it('readWorkflowJob throws when the job does not exist', () => {
+    expect(() => readWorkflowJob('jobs:\n  other: {}\n', 'verify')).toThrow(
+      /no job named "verify"/,
+    );
+  });
+});

package/tools/ci-hardening/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "tsBuildInfoFile": "./.tsbuildinfo",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "tests", "**/*.test.ts"]
+}

package/tools/ci-hardening/tsconfig.test.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node"],
+    "composite": false
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"],
+  "exclude": ["dist"]
+}

package/tools/ci-hardening/vitest.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      all: false,
+      include: ['src/**/*.ts'],
+      exclude: ['src/index.ts'],
+      reporter: ['text', 'html', 'json-summary'],
+      thresholds: {
+        lines: 100,
+        functions: 100,
+        branches: 100,
+        statements: 100,
+      },
+    },
+  },
+});

package/tools/tcp-ws-forwarder/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/tcp-ws-forwarder",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "description": "Local TCP to ws/wss forwarder so standard IRC clients can reach the WebSocket-only ServerlessIRCd transport",
   "license": "BSD-3-Clause",

package/tools/tcp-ws-forwarder/src/forwarder.ts

@@ -29,6 +29,7 @@
 import { type Socket, createServer } from 'node:net';
 import { type RawData, WebSocket } from 'ws';
 import { LineScanner } from './line-scanner.js';
+import { ConsoleLogger, LogLevel, type Logger } from './logger.js';
 
 /** Options accepted by {@link startForwarder}. */
 export interface StartForwarderOptions {
@@ -41,6 +42,12 @@ export interface StartForwarderOptions {
    * `ws:` or `wss:` scheme; otherwise `startForwarder` throws synchronously.
    */
   targetUrl: string;
+  /**
+   * Minimum log severity to emit. `debug` traces every relayed line/frame;
+   * `info` (default) logs connection lifecycle; `warn`/`error` quiet the
+   * bridge to faults only. Mirrors the irc-core `LogLevel` ordering.
+   */
+  logLevel?: LogLevel;
 }
 
 /** A running forwarder. Call {@link Forwarder.close} to shut it down. */
@@ -87,6 +94,8 @@ export function startForwarder(opts: StartForwarderOptions): Promise<Forwarder>
   const target = parseTargetUrl(opts.targetUrl);
   const listenHost = opts.listenHost ?? '127.0.0.1';
   const targetHref = target.href;
+  const logger: Logger = new ConsoleLogger(undefined, opts.logLevel ?? LogLevel.Info);
+  let nextConnId = 1;
 
   const bridges = new Map<Socket, () => void>();
   const sockets = new Set<Socket>();
@@ -94,7 +103,7 @@ export function startForwarder(opts: StartForwarderOptions): Promise<Forwarder>
 
   const server = createServer((tcp) => {
     sockets.add(tcp);
-    bridges.set(tcp, bridgeConnection(tcp, targetHref, bridges, sockets));
+    bridges.set(tcp, bridgeConnection(tcp, targetHref, bridges, sockets, logger, nextConnId++));
   });
 
   const close = (): Promise<void> => {
@@ -132,6 +141,9 @@ export function startForwarder(opts: StartForwarderOptions): Promise<Forwarder>
   });
 }
 
+/** Why a bridge tore down. Surfaces in the `bridge.closed` log record. */
+type CloseReason = 'shutdown' | 'tcp-close' | 'tcp-error' | 'ws-close' | 'ws-error';
+
 /**
  * Wires one TCP socket to one fresh WebSocket. Returns a teardown closure
  * that closes both ends idempotently; the caller registers it in `bridges`
@@ -142,12 +154,17 @@ function bridgeConnection(
   targetHref: string,
   bridges: Map<Socket, () => void>,
   sockets: Set<Socket>,
+  logger: Logger,
+  connId: number,
 ): () => void {
   const ws = new WebSocket(targetHref);
   const outgoing = new LineScanner();
   const pending: string[] = [];
   let wsReady = false;
   let bridgeClosed = false;
+  const remote = `${tcp.remoteAddress ?? '?'}:${tcp.remotePort ?? '?'}`;
+
+  logger.info('bridge.accepted', { conn: connId, remote });
 
   const sendLine = (line: string): void => {
     if (wsReady) ws.send(line);
@@ -156,28 +173,35 @@ function bridgeConnection(
 
   tcp.on('data', (chunk: Buffer) => {
     for (const line of outgoing.push(chunk)) {
-      if (line.length > 0) sendLine(line);
+      if (line.length > 0) {
+        logger.debug('tcp.line', { conn: connId, line });
+        sendLine(line);
+      }
     }
   });
 
   ws.on('open', () => {
     wsReady = true;
+    const flushed = pending.length;
     for (const line of pending) ws.send(line);
     pending.length = 0;
+    logger.debug('ws.open', { conn: connId, flushed });
   });
 
   ws.on('message', (data: RawData) => {
     const text = toBuffer(data).toString('utf8');
+    logger.debug('ws.frame', { conn: connId, frame: text });
     for (const line of splitFrameLines(text)) {
       if (line.length > 0) tcp.write(`${line}\r\n`);
     }
   });
 
-  const teardown = (): void => {
+  const teardown = (reason: CloseReason): void => {
     if (bridgeClosed) return;
     bridgeClosed = true;
     bridges.delete(tcp);
     sockets.delete(tcp);
+    logger.info('bridge.closed', { conn: connId, reason });
     // ws.close() does not throw: on a CONNECTING socket it aborts the
     // handshake and emits an 'error' event, which our handler suppresses
     // via the `bridgeClosed` guard set above.
@@ -185,25 +209,25 @@ function bridgeConnection(
     tcp.destroy();
   };
 
-  tcp.on('close', teardown);
+  tcp.on('close', () => teardown('tcp-close'));
   tcp.on('error', (err) => {
     // Errors that arrive after we already tore this bridge down (e.g. an
     // RST echoing our own `destroy()`) are expected — don't log them.
     if (bridgeClosed) return;
-    logError('forwarder tcp socket error', err);
-    teardown();
+    logger.error('forwarder tcp socket error', { conn: connId, err });
+    teardown('tcp-error');
   });
-  ws.on('close', teardown);
+  ws.on('close', () => teardown('ws-close'));
   ws.on('error', (err) => {
     // Same suppression as above; also covers the benign "closed before the
     // connection was established" event ws emits when we close() a socket
     // that was still CONNECTING at shutdown time.
     if (bridgeClosed) return;
-    logError('forwarder upstream ws error', err);
-    teardown();
+    logger.error('forwarder upstream ws error', { conn: connId, err });
+    teardown('ws-error');
   });
 
-  return teardown;
+  return () => teardown('shutdown');
 }
 
 /**
@@ -229,16 +253,3 @@ export function toBuffer(data: RawData): Buffer {
   if (data instanceof ArrayBuffer) return Buffer.from(data);
   return Buffer.from(data as Uint8Array);
 }
-
-function logError(msg: string, err: unknown): void {
-  const payload = {
-    ts: new Date().toISOString(),
-    level: 'error',
-    msg,
-    err:
-      err instanceof Error
-        ? { name: err.name, message: err.message, stack: err.stack }
-        : String(err),
-  };
-  console.error(JSON.stringify(payload));
-}