serverless-ircd 0.1.0

package/packages/irc-core/tests/message-tags.test.ts

@@ -0,0 +1,182 @@
+import fc from 'fast-check';
+import { describe, expect, it } from 'vitest';
+import type { RawLine } from '../src/effects';
+import { applyServerTime, filterClientTags } from '../src/protocol/outbound';
+import { parse, unescapeTagValue } from '../src/protocol/parser';
+import { escapeTagValue, serialize } from '../src/protocol/serializer';
+
+const L = (text: string): RawLine => ({ text });
+const NOW = 1_705_329_296_789; // 2024-01-15T14:34:56.789Z
+
+// ============================================================================
+// filterClientTags — IRCv3 message-tags client-tag gating
+// ============================================================================
+
+describe('filterClientTags — cap gating', () => {
+  it('returns the line unchanged for a message-tags client', () => {
+    const line = L('@+typing=1 :alice PRIVMSG #foo :hi');
+    expect(filterClientTags(line, new Set<string>(['message-tags']))).toBe(line);
+  });
+
+  it('strips a single valued client tag (+) for a non-message-tags client', () => {
+    const line = L('@+typing=1 :alice PRIVMSG #foo :hi');
+    const out = filterClientTags(line, new Set<string>());
+    expect(out.text).toBe(':alice PRIVMSG #foo :hi');
+  });
+
+  it('drops the entire tag section when only client tags were present', () => {
+    const line = L('@+away :alice PRIVMSG #foo :hi');
+    const out = filterClientTags(line, new Set<string>());
+    expect(out.text).toBe(':alice PRIVMSG #foo :hi');
+    expect(out.text.startsWith('@')).toBe(false);
+  });
+
+  it('keeps server tags but removes client tags for a legacy client', () => {
+    const line = L('@account=alice;+typing=1 :alice PRIVMSG #foo :hi');
+    const out = filterClientTags(line, new Set<string>());
+    expect(out.text).toBe('@account=alice :alice PRIVMSG #foo :hi');
+  });
+
+  it('keeps the equals-less form of a server tag and drops a valueless client tag', () => {
+    const line = L('@+away;msgid=abc :alice PRIVMSG #foo :hi');
+    const out = filterClientTags(line, new Set<string>());
+    expect(out.text).toBe('@msgid=abc :alice PRIVMSG #foo :hi');
+  });
+
+  it('returns the same object reference when there are no client tags to strip', () => {
+    const line = L('@account=alice :alice PRIVMSG #foo :hi');
+    expect(filterClientTags(line, new Set<string>())).toBe(line);
+  });
+
+  it('returns the line unchanged when it has no tag section', () => {
+    const line = L(':alice PRIVMSG #foo :hi');
+    expect(filterClientTags(line, new Set<string>())).toBe(line);
+  });
+
+  it('returns a malformed @-prefixed line with no body unchanged', () => {
+    const line = L('@+typing');
+    expect(filterClientTags(line, new Set<string>())).toBe(line);
+  });
+
+  it('does not mutate the input RawLine', () => {
+    const line = L('@+typing=1 :alice PRIVMSG #foo :hi');
+    const snapshot = line.text;
+    filterClientTags(line, new Set<string>());
+    expect(line.text).toBe(snapshot);
+  });
+
+  it('preserves server and client tags together for a message-tags client', () => {
+    const line = L('@account=alice;+typing=1 :alice PRIVMSG #foo :hi');
+    const out = filterClientTags(line, new Set<string>(['message-tags']));
+    expect(out.text).toBe('@account=alice;+typing=1 :alice PRIVMSG #foo :hi');
+  });
+
+  it('preserves an escaped value within a kept server tag verbatim', () => {
+    const line = L('@label=a\\sb;+typing=1 :alice PRIVMSG #foo :hi');
+    const out = filterClientTags(line, new Set<string>());
+    expect(out.text).toBe('@label=a\\sb :alice PRIVMSG #foo :hi');
+  });
+});
+
+// ============================================================================
+// filterClientTags + applyServerTime composition (dispatch-layer ordering)
+// ============================================================================
+
+describe('filterClientTags + applyServerTime composition', () => {
+  const base = L('@+typing=1 :alice PRIVMSG #foo :hi');
+
+  it('keeps @time and client tags for a server-time + message-tags recipient', () => {
+    const caps = new Set<string>(['server-time', 'message-tags']);
+    const out = filterClientTags(applyServerTime(base, caps, NOW), caps);
+    expect(out.text).toBe('@time=2024-01-15T14:34:56.789Z;+typing=1 :alice PRIVMSG #foo :hi');
+  });
+
+  it('keeps @time but strips client tags for a server-time-only recipient', () => {
+    const caps = new Set<string>(['server-time']);
+    const out = filterClientTags(applyServerTime(base, caps, NOW), caps);
+    expect(out.text).toBe('@time=2024-01-15T14:34:56.789Z :alice PRIVMSG #foo :hi');
+  });
+
+  it('drops the client tag and tag section for a cap-less recipient (no server-time added)', () => {
+    const caps = new Set<string>();
+    const out = filterClientTags(applyServerTime(base, caps, NOW), caps);
+    expect(out.text).toBe(':alice PRIVMSG #foo :hi');
+  });
+});
+
+// ============================================================================
+// escapeTagValue / unescapeTagValue codec round-trip
+// ============================================================================
+
+describe('escapeTagValue — spec escapes', () => {
+  it('escapes semicolon as \\:', () => {
+    expect(escapeTagValue(';')).toBe('\\:');
+  });
+
+  it('escapes space as \\s', () => {
+    expect(escapeTagValue(' ')).toBe('\\s');
+  });
+
+  it('escapes backslash as \\\\', () => {
+    expect(escapeTagValue('\\')).toBe('\\\\');
+  });
+
+  it('escapes CR as \\r', () => {
+    expect(escapeTagValue('\r')).toBe('\\r');
+  });
+
+  it('escapes LF as \\n', () => {
+    expect(escapeTagValue('\n')).toBe('\\n');
+  });
+
+  it('leaves ordinary characters untouched', () => {
+    expect(escapeTagValue('abc123_.-+/')).toBe('abc123_.-+/');
+  });
+});
+
+describe('unescapeTagValue — spec unescapes', () => {
+  it('unescapes \\: to ;', () => {
+    expect(unescapeTagValue('\\:')).toBe(';');
+  });
+
+  it('unescapes \\s to space', () => {
+    expect(unescapeTagValue('\\s')).toBe(' ');
+  });
+
+  it('unescapes \\\\ to \\', () => {
+    expect(unescapeTagValue('\\\\')).toBe('\\');
+  });
+
+  it('unescapes \\r to CR', () => {
+    expect(unescapeTagValue('\\r')).toBe('\r');
+  });
+
+  it('unescapes \\n to LF', () => {
+    expect(unescapeTagValue('\\n')).toBe('\n');
+  });
+});
+
+describe('escapeTagValue / unescapeTagValue round-trip', () => {
+  it('round-trips a string containing every special character', () => {
+    const original = 'a b;c\\d\re\nf';
+    expect(unescapeTagValue(escapeTagValue(original))).toBe(original);
+  });
+
+  it('round-trips arbitrary strings over the special-character alphabet', () => {
+    const arb = fc.stringOf(fc.constantFrom('\\', ';', ' ', 's', 'r', 'n', ':', 'a', 'b', '1'), {
+      maxLength: 32,
+    });
+    fc.assert(
+      fc.property(arb, (s) => {
+        expect(unescapeTagValue(escapeTagValue(s))).toBe(s);
+      }),
+      { numRuns: 500 },
+    );
+  });
+
+  it('serializer escape then parser unescape yields the original value', () => {
+    const value = 'hi ; there \\ done';
+    const wire = serialize({ tags: { k: value }, command: 'PING', params: [] });
+    expect(parse(wire).tags.k).toBe(value);
+  });
+});

package/packages/irc-core/tests/numerics.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest';
+import type { NumericCode } from '../src/protocol/numerics';
+import { Numerics, formatNumeric, isNumericCommand, numericToName } from '../src/protocol/numerics';
+
+describe('Numerics registry', () => {
+  it('maps RPL_WELCOME to 1', () => {
+    expect(Numerics.RPL_WELCOME).toBe(1);
+  });
+
+  it('maps RPL_ISUPPORT to 5', () => {
+    expect(Numerics.RPL_ISUPPORT).toBe(5);
+  });
+
+  it('maps RPL_ENDOFMOTD to 376', () => {
+    expect(Numerics.RPL_ENDOFMOTD).toBe(376);
+  });
+
+  it('maps ERR_NOSUCHNICK to 401', () => {
+    expect(Numerics.ERR_NOSUCHNICK).toBe(401);
+  });
+
+  it('maps ERR_NEEDMOREPARAMS to 461', () => {
+    expect(Numerics.ERR_NEEDMOREPARAMS).toBe(461);
+  });
+
+  it('maps ERR_NICKNAMEINUSE to 433', () => {
+    expect(Numerics.ERR_NICKNAMEINUSE).toBe(433);
+  });
+
+  it('maps ERR_CHANOPRIVSNEEDED to 482', () => {
+    expect(Numerics.ERR_CHANOPRIVSNEEDED).toBe(482);
+  });
+
+  it('keeps every code within the 3-digit range [1,999]', () => {
+    for (const code of Object.values(Numerics)) {
+      expect(code).toBeGreaterThanOrEqual(1);
+      expect(code).toBeLessThanOrEqual(999);
+      expect(Number.isInteger(code)).toBe(true);
+    }
+  });
+
+  it('uses unique codes across all names (no aliases collide)', () => {
+    const codes = Object.values(Numerics);
+    expect(new Set(codes).size).toBe(codes.length);
+  });
+
+  it('uses SCREAMING_SNAKE_CASE names only', () => {
+    for (const name of Object.keys(Numerics)) {
+      expect(name).toMatch(/^[A-Z][A-Z0-9_]*$/);
+    }
+  });
+
+  it('keeps NumericCode assignable to keys of Numerics', () => {
+    const name: NumericCode = 'ERR_NICKNAMEINUSE';
+    expect(Numerics[name]).toBe(433);
+  });
+});
+
+describe('numericToName', () => {
+  it('reverses ERR_NICKNAMEINUSE', () => {
+    expect(numericToName.get(433)).toBe('ERR_NICKNAMEINUSE');
+  });
+
+  it('reverses RPL_WELCOME', () => {
+    expect(numericToName.get(1)).toBe('RPL_WELCOME');
+  });
+
+  it('returns undefined for an unregistered code', () => {
+    expect(numericToName.get(600)).toBeUndefined();
+  });
+});
+
+describe('isNumericCommand', () => {
+  it.each(['001', '005', '433', '999'])('treats %s as a numeric command', (code) => {
+    expect(isNumericCommand(code)).toBe(true);
+  });
+
+  it.each(['PRIVMSG', 'privmsg', 'nick', '', '1', '01', '0001', '1234', 'PING '])(
+    'treats %j as a non-numeric command',
+    (code) => {
+      expect(isNumericCommand(code)).toBe(false);
+    },
+  );
+});
+
+describe('formatNumeric', () => {
+  it('zero-pads a single digit to three places', () => {
+    expect(formatNumeric('RPL_WELCOME')).toBe('001');
+  });
+
+  it('formats a three-digit code unchanged', () => {
+    expect(formatNumeric('ERR_NICKNAMEINUSE')).toBe('433');
+  });
+
+  it('zero-pads RPL_ISUPPORT', () => {
+    expect(formatNumeric('RPL_ISUPPORT')).toBe('005');
+  });
+});

package/packages/irc-core/tests/outbound.test.ts

@@ -0,0 +1,232 @@
+import fc from 'fast-check';
+import { describe, expect, it } from 'vitest';
+import type { RawLine } from '../src/effects';
+import {
+  MAX_LINE_BYTES,
+  applyServerTime,
+  enforceLineLimit,
+  formatServerTime,
+} from '../src/protocol/outbound';
+import { parse } from '../src/protocol/parser';
+import { serialize } from '../src/protocol/serializer';
+
+const L = (text: string): RawLine => ({ text });
+
+// ============================================================================
+// formatServerTime — ISO-8601 with milliseconds
+// ============================================================================
+
+describe('formatServerTime', () => {
+  it('formats epoch ms as ISO-8601 with millisecond precision and a Z suffix', () => {
+    // 2024-01-15T14:34:56.789Z
+    expect(formatServerTime(1_705_329_296_789)).toBe('2024-01-15T14:34:56.789Z');
+  });
+
+  it('zero-pads month, day, hour, minute, second, and millisecond fields', () => {
+    // 2023-01-01T00:00:00.000Z
+    expect(formatServerTime(1_672_531_200_000)).toBe('2023-01-01T00:00:00.000Z');
+  });
+
+  it('always emits exactly three millisecond digits', () => {
+    expect(formatServerTime(1_672_531_200_000)).toMatch(/\.\d{3}Z$/u);
+    expect(formatServerTime(1_672_531_200_500)).toMatch(/\.\d{3}Z$/u);
+    expect(formatServerTime(1_672_531_200_999)).toMatch(/\.\d{3}Z$/u);
+  });
+
+  it('rounds/truncates consistently with Date#toISOString', () => {
+    const now = 1_705_329_296_789;
+    expect(formatServerTime(now)).toBe(new Date(now).toISOString());
+  });
+});
+
+// ============================================================================
+// applyServerTime — per-recipient @time=... prepending
+// ============================================================================
+
+describe('applyServerTime', () => {
+  const PRIVMSG_LINE: RawLine = L(':alice!alice@example.com PRIVMSG #foo :hello');
+
+  it('prepends @time=<iso> when the recipient negotiated server-time', () => {
+    const caps = new Set<string>(['server-time']);
+    const out = applyServerTime(PRIVMSG_LINE, caps, 1_705_329_296_789);
+    expect(out.text).toBe(
+      '@time=2024-01-15T14:34:56.789Z :alice!alice@example.com PRIVMSG #foo :hello',
+    );
+  });
+
+  it('returns the line unchanged when the recipient lacks the server-time cap', () => {
+    const caps = new Set<string>(['multi-prefix', 'echo-message']);
+    const out = applyServerTime(PRIVMSG_LINE, caps, 1_705_329_296_789);
+    expect(out).toBe(PRIVMSG_LINE);
+    expect(out.text).toBe(':alice!alice@example.com PRIVMSG #foo :hello');
+  });
+
+  it('returns the line unchanged when the recipient has no caps at all', () => {
+    const caps = new Set<string>();
+    const out = applyServerTime(PRIVMSG_LINE, caps, 1_705_329_296_789);
+    expect(out.text).toBe(':alice!alice@example.com PRIVMSG #foo :hello');
+  });
+
+  it('prepends to numeric replies too (server-time applies to all outbound messages)', () => {
+    const caps = new Set<string>(['server-time']);
+    const numeric: RawLine = L(':irc.example.com 001 alice :Welcome to the network');
+    const out = applyServerTime(numeric, caps, 1_672_531_200_000);
+    expect(out.text).toBe(
+      '@time=2023-01-01T00:00:00.000Z :irc.example.com 001 alice :Welcome to the network',
+    );
+  });
+
+  it('does not mutate the input RawLine', () => {
+    const caps = new Set<string>(['server-time']);
+    const original: RawLine = { text: ':alice PRIVMSG #foo :hi' };
+    const snapshot = original.text;
+    applyServerTime(original, caps, 1_705_329_296_789);
+    expect(original.text).toBe(snapshot);
+  });
+
+  it('merges into an existing tag section instead of emitting two @ prefixes', () => {
+    // A line that already carries an account tag (e.g. from a message-tags
+    // enabled reducer) must get its `time` tag merged in after the `@`.
+    const caps = new Set<string>(['server-time']);
+    const tagged: RawLine = L('@account=alice :alice PRIVMSG #foo :hi');
+    const out = applyServerTime(tagged, caps, 1_705_329_296_789);
+    expect(out.text).toBe('@time=2024-01-15T14:34:56.789Z;account=alice :alice PRIVMSG #foo :hi');
+  });
+});
+
+// ============================================================================
+// enforceLineLimit — 512-byte wire limit including tags
+// ============================================================================
+
+describe('enforceLineLimit', () => {
+  // MAX_LINE_BYTES (512) is the wire budget INCLUDING the trailing CR-LF the
+  // wire layer appends. enforceLineLimit operates on RawLine.text (no CRLF),
+  // so the in-memory text budget is MAX_LINE_BYTES - 2 = 510 bytes.
+  const TEXT_BUDGET = MAX_LINE_BYTES - 2;
+
+  it('passes a short line through unchanged for a legacy client', () => {
+    const line: RawLine = L(':alice PRIVMSG #foo :hi');
+    const out = enforceLineLimit(line, new Set<string>());
+    expect(out).toBe(line);
+  });
+
+  it('passes a short line through unchanged for a message-tags client', () => {
+    const line: RawLine = L('@time=2024-01-15T12:34:56.789Z :alice PRIVMSG #foo :hi');
+    const out = enforceLineLimit(line, new Set<string>(['message-tags']));
+    expect(out).toBe(line);
+  });
+
+  it('truncates a body-only line that exceeds the wire budget for a legacy client', () => {
+    const prefix = ':alice PRIVMSG #foo :';
+    const padding = 'x'.repeat(TEXT_BUDGET - prefix.length);
+    const exact: RawLine = L(`${prefix}${padding}`);
+    expect(exact.text.length).toBe(TEXT_BUDGET);
+    expect(enforceLineLimit(exact, new Set<string>()).text.length).toBe(TEXT_BUDGET);
+
+    const tooLong: RawLine = L(`${prefix}${padding}YYYYY`);
+    const out = enforceLineLimit(tooLong, new Set<string>());
+    expect(out.text.length).toBe(TEXT_BUDGET);
+  });
+
+  it('counts the tag section toward the wire budget for message-tags clients', () => {
+    const tagPrefix = '@time=2024-01-15T12:34:56.789Z '; // 31 bytes incl trailing space
+    const body = `:alice PRIVMSG #foo :${'x'.repeat(490)}`; // prefix(21) + 490 = 511
+    const line: RawLine = L(`${tagPrefix}${body}`);
+    expect(line.text.length).toBeGreaterThan(TEXT_BUDGET);
+
+    const out = enforceLineLimit(line, new Set<string>(['message-tags']));
+    expect(out.text.length).toBe(TEXT_BUDGET);
+    expect(out.text.startsWith(tagPrefix)).toBe(true);
+  });
+
+  it('preserves the tag section verbatim while truncating only the trailing body', () => {
+    const tagPrefix = '@time=2024-01-15T12:34:56.789Z ';
+    const body = `:alice PRIVMSG #foo :${'x'.repeat(500)}`;
+    const line: RawLine = L(`${tagPrefix}${body}`);
+    const out = enforceLineLimit(line, new Set<string>(['message-tags']));
+    expect(out.text.length).toBe(TEXT_BUDGET);
+    expect(out.text.startsWith(tagPrefix)).toBe(true);
+    expect(out.text.endsWith('xxx')).toBe(true);
+  });
+
+  it('does not strip tags from a message-tags client even when the line is very long', () => {
+    const tagPrefix = '@time=2024-01-15T12:34:56.789Z ';
+    const body = `:alice PRIVMSG #foo :${'x'.repeat(1000)}`;
+    const line: RawLine = L(`${tagPrefix}${body}`);
+    const out = enforceLineLimit(line, new Set<string>(['message-tags']));
+    expect(out.text.startsWith(tagPrefix)).toBe(true);
+    expect(out.text.length).toBe(TEXT_BUDGET);
+  });
+
+  it('handles a legacy client line that already has tags (defensive — never delivered)', () => {
+    // The runtime should never deliver a tagged line to a legacy client, but
+    // enforceLineLimit must still keep its output within the budget.
+    const line: RawLine = L(`@a=b ${'x'.repeat(600)}`);
+    const out = enforceLineLimit(line, new Set<string>());
+    expect(out.text.length).toBe(TEXT_BUDGET);
+  });
+
+  it('truncates from the right when a message-tags client sends a body with no @ prefix', () => {
+    // Defensive: caps says message-tags but the line never got decorated.
+    // We fall through to the legacy truncation path.
+    const line: RawLine = L(`:alice PRIVMSG #foo :${'x'.repeat(600)}`);
+    const out = enforceLineLimit(line, new Set<string>(['message-tags']));
+    expect(out.text.length).toBe(TEXT_BUDGET);
+    expect(out.text.startsWith(':alice')).toBe(true);
+  });
+
+  it('truncates from the right when a message-tags line has no space after the tag section', () => {
+    // Malformed wire input; defensive truncation.
+    const line: RawLine = L(`@a=b${'x'.repeat(600)}`);
+    const out = enforceLineLimit(line, new Set<string>(['message-tags']));
+    expect(out.text.length).toBe(TEXT_BUDGET);
+  });
+
+  it('truncates the tag section itself when it alone exceeds the budget', () => {
+    // Pathological: the tag section is so large that no body would fit. The
+    // contract (output ≤ budget bytes) must still hold.
+    const giantTag = `@${'a'.repeat(700)}`;
+    const line: RawLine = L(`${giantTag} :alice PRIVMSG #foo :hi`);
+    const out = enforceLineLimit(line, new Set<string>(['message-tags']));
+    expect(out.text.length).toBe(TEXT_BUDGET);
+  });
+});
+
+// ============================================================================
+// Round-trip through serialize -> applyServerTime -> parse
+// ============================================================================
+
+describe('server-time + tag escaping round-trip (property test)', () => {
+  const tagValue = fc.oneof(fc.constant(''), fc.stringMatching(/^[A-Za-z0-9 :;\\]{0,32}$/));
+  const tagKey = fc.stringMatching(/^[a-z][a-z0-9/+\\-]{0,14}$/);
+
+  it('parse(serialize(msg)) preserves the time tag across all generated values', () => {
+    fc.assert(
+      fc.property(fc.tuple(tagKey, tagValue), ([key, value]) => {
+        const msg = {
+          tags: value === '' ? { [key]: '' } : { [key]: value },
+          command: 'PRIVMSG' as const,
+          params: ['#foo', 'hello'],
+        };
+        const wire = serialize(msg);
+        const reParsed = parse(wire);
+        expect(reParsed.tags).toEqual(msg.tags);
+      }),
+      { numRuns: 200 },
+    );
+  });
+
+  it('applyServerTime produces a line parseable back into the time tag', () => {
+    const base: RawLine = L(':alice PRIVMSG #foo :hi');
+    fc.assert(
+      fc.property(fc.integer({ min: 0, max: 4_000_000_000_000 }), (now) => {
+        const caps = new Set<string>(['server-time']);
+        const decorated = applyServerTime(base, caps, now);
+        // The decorated line must be parseable and contain the time tag we put there.
+        const parsed = parse(decorated.text);
+        expect(parsed.tags.time).toBe(formatServerTime(now));
+      }),
+      { numRuns: 100 },
+    );
+  });
+});

package/packages/irc-core/tests/parser.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+import type { IrcMessage } from '../src/protocol/messages';
+import { IrcParseError, parse } from '../src/protocol/parser';
+
+describe('parse — golden vectors', () => {
+  it('parses a simple command with a channel and trailing text', () => {
+    expect(parse('PRIVMSG #foo :hello world')).toEqual<IrcMessage>({
+      tags: {},
+      command: 'PRIVMSG',
+      params: ['#foo', 'hello world'],
+    });
+  });
+
+  it('parses a nick!user@host source', () => {
+    expect(parse(':nick!user@host PRIVMSG #foo :hi')).toEqual<IrcMessage>({
+      tags: {},
+      source: { name: 'nick', user: 'user', host: 'host' },
+      command: 'PRIVMSG',
+      params: ['#foo', 'hi'],
+    });
+  });
+
+  it('parses PING with a trailing token', () => {
+    expect(parse('PING :tok')).toEqual<IrcMessage>({
+      tags: {},
+      command: 'PING',
+      params: ['tok'],
+    });
+  });
+
+  it('parses a command with no parameters', () => {
+    expect(parse('PONG')).toEqual<IrcMessage>({ tags: {}, command: 'PONG', params: [] });
+  });
+
+  it('parses a numeric reply with a server source', () => {
+    expect(parse(':irc.example.com 001 nick :Welcome')).toEqual<IrcMessage>({
+      tags: {},
+      source: { name: 'irc.example.com' },
+      command: '001',
+      params: ['nick', 'Welcome'],
+    });
+  });
+
+  it('normalizes a lower-case command to upper-case', () => {
+    expect(parse('privmsg #foo :hi').command).toBe('PRIVMSG');
+  });
+
+  it('parses multiple middle parameters', () => {
+    expect(parse(':nick JOIN #a #b key').params).toEqual(['#a', '#b', 'key']);
+  });
+
+  it('parses an empty trailing parameter', () => {
+    expect(parse(':nick TOPIC #foo :')).toEqual<IrcMessage>({
+      tags: {},
+      source: { name: 'nick' },
+      command: 'TOPIC',
+      params: ['#foo', ''],
+    });
+  });
+
+  it('parses a server source without user or host', () => {
+    expect(parse(':irc.example.com NOTICE * :hi').source).toEqual({ name: 'irc.example.com' });
+  });
+
+  it('keeps a colon mid-parameter non-trailing', () => {
+    expect(parse('PRIVMSG #foo a:b c').params).toEqual(['#foo', 'a:b', 'c']);
+  });
+
+  it('treats everything after the first space-colon as trailing (literal colons)', () => {
+    expect(parse('TOPIC #foo :topic with :colons').params).toEqual(['#foo', 'topic with :colons']);
+  });
+
+  it('parses up to 14 middle params plus a trailing param (15 total)', () => {
+    const middles = Array.from({ length: 14 }, (_, i) => `p${i}`);
+    const line = `PRIVMSG ${middles.join(' ')} :trailing`;
+    const parsed = parse(line);
+    expect(parsed.params).toEqual([...middles, 'trailing']);
+    expect(parsed.params).toHaveLength(15);
+  });
+});
+
+describe('parse — message-tags (IRCv3)', () => {
+  it('parses two valued tags', () => {
+    expect(parse('@time=2024-01-01T00:00:00Z;account=foo PRIVMSG #foo :hi').tags).toEqual({
+      time: '2024-01-01T00:00:00Z',
+      account: 'foo',
+    });
+  });
+
+  it('parses a vendor-prefixed tag', () => {
+    expect(parse('@+draft/typing=1 PRIVMSG #foo :hi').tags).toEqual({ '+draft/typing': '1' });
+  });
+
+  it('parses a valueless tag as the empty string', () => {
+    expect(parse('@+away PRIVMSG #foo :hi').tags).toEqual({ '+away': '' });
+  });
+
+  it('decodes the ":" escape to a semicolon', () => {
+    expect(parse('@a=foo\\:bar PRIVMSG #foo :hi').tags).toEqual({ a: 'foo;bar' });
+  });
+
+  it('decodes the "s" escape to a space', () => {
+    expect(parse('@a=foo\\sbar PRIVMSG #foo :hi').tags).toEqual({ a: 'foo bar' });
+  });
+
+  it('decodes the "\\\\" escape to a single backslash', () => {
+    expect(parse('@a=a\\\\b PRIVMSG #foo :hi').tags).toEqual({ a: 'a\\b' });
+  });
+
+  it('keeps an unknown escape sequence as the literal character', () => {
+    expect(parse('@a=x\\qy PRIVMSG #foo :hi').tags).toEqual({ a: 'xqy' });
+  });
+
+  it('skips empty tag entries produced by doubled semicolons', () => {
+    expect(parse('@a=b;;c=d PRIVMSG #foo :hi').tags).toEqual({ a: 'b', c: 'd' });
+  });
+
+  it('parses tags together with a source', () => {
+    expect(parse('@account=foo :nick!u@h PRIVMSG #foo :hi')).toEqual<IrcMessage>({
+      tags: { account: 'foo' },
+      source: { name: 'nick', user: 'u', host: 'h' },
+      command: 'PRIVMSG',
+      params: ['#foo', 'hi'],
+    });
+  });
+});
+
+describe('parse — framing tolerance', () => {
+  it('strips a trailing CR LF', () => {
+    expect(parse('PING :tok\r\n').params).toEqual(['tok']);
+  });
+
+  it('strips a lone trailing LF', () => {
+    expect(parse('PING :tok\n').params).toEqual(['tok']);
+  });
+});
+
+describe('parse — malformed input', () => {
+  it('throws IrcParseError on empty input', () => {
+    expect(() => parse('')).toThrow(IrcParseError);
+  });
+
+  it('throws IrcParseError on whitespace-only input', () => {
+    expect(() => parse('   ')).toThrow(IrcParseError);
+  });
+
+  it('throws IrcParseError when only a source prefix is present', () => {
+    expect(() => parse(':nick!user@host')).toThrow(IrcParseError);
+  });
+
+  it('throws IrcParseError when a source is followed by no command', () => {
+    expect(() => parse(':irc.example.com   ')).toThrow(IrcParseError);
+  });
+
+  it('throws IrcParseError when a tag section has no body', () => {
+    expect(() => parse('@time=now')).toThrow(IrcParseError);
+  });
+
+  it('throws IrcParseError on an invalid command token', () => {
+    expect(() => parse('12 hi')).toThrow(IrcParseError);
+  });
+});