serverless-ircd 0.8.0 → 0.10.0

package/apps/web/tests/render-docs.test.ts

@@ -0,0 +1,198 @@
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { buildDocs, renderMarkdown, rewriteDocLinks } from '../src/render-docs';
+
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const docsSrc = path.resolve(pkgRoot, '..', '..', 'docs');
+
+// ============================================================================
+// renderMarkdown — GFM rendering of markdown source
+// ============================================================================
+describe('renderMarkdown', () => {
+  it('renders an ATX H1 heading as <h1>', () => {
+    const html = renderMarkdown('# Title');
+    expect(html).toMatch(/<h1[^>]*>\s*Title\s*<\/h1>/);
+  });
+
+  it('renders a fenced code block as <pre><code>', () => {
+    const md = ['```ts', 'const x = 1;', '```'].join('\n');
+    const html = renderMarkdown(md);
+    expect(html).toMatch(/<pre[^>]*><code[^>]*>/);
+  });
+
+  it('renders GFM tables', () => {
+    const md = ['| a | b |', '| --- | --- |', '| 1 | 2 |'].join('\n');
+    const html = renderMarkdown(md);
+    expect(html).toContain('<table>');
+    expect(html).toContain('<th');
+  });
+
+  it('renders inline code', () => {
+    const html = renderMarkdown('Use `npm` to install.');
+    expect(html).toContain('<code>npm</code>');
+  });
+});
+
+// ============================================================================
+// rewriteDocLinks — intra-docs link rewriting
+// ============================================================================
+describe('rewriteDocLinks', () => {
+  const known = new Set([
+    'Services',
+    'Home',
+    'ADR-Index',
+    'ADR-001-pure-reducers-and-effect-system',
+  ]);
+
+  it('rewrites a relative OtherDoc.md href to OtherDoc.html', () => {
+    const input = '<a href="./Services.md">Services</a>';
+    const out = rewriteDocLinks(input, known);
+    expect(out).toContain('href="Services.html"');
+    expect(out).not.toContain('Services.md');
+  });
+
+  it('rewrites a bare wikilink-style href (no extension) when the slug is a known doc', () => {
+    const input = '<a href="Services">Services</a>';
+    const out = rewriteDocLinks(input, known);
+    expect(out).toContain('href="Services.html"');
+  });
+
+  it('leaves unknown bare hrefs alone (could be an external path)', () => {
+    const input = '<a href="SomeUnknownPage">x</a>';
+    const out = rewriteDocLinks(input, new Set(['Services']));
+    expect(out).toContain('href="SomeUnknownPage"');
+  });
+
+  it('preserves an anchor fragment when rewriting', () => {
+    const input = '<a href="./Services.md#section">link</a>';
+    const out = rewriteDocLinks(input, known);
+    expect(out).toContain('href="Services.html#section"');
+  });
+
+  it('does not touch external (http/https) links', () => {
+    const input = '<a href="https://example.com/foo.md">external</a>';
+    const out = rewriteDocLinks(input, known);
+    expect(out).toContain('href="https://example.com/foo.md"');
+  });
+
+  it('does not touch pure-anchor (#section) links', () => {
+    const input = '<a href="#section">anchor</a>';
+    const out = rewriteDocLinks(input, known);
+    expect(out).toContain('href="#section"');
+  });
+
+  it('handles a trailing anchor on a bare wikilink-style href', () => {
+    const input = '<a href="Home#pages">Home</a>';
+    const out = rewriteDocLinks(input, known);
+    expect(out).toContain('href="Home.html#pages"');
+  });
+});
+
+// ============================================================================
+// buildDocs — end-to-end render pipeline (against the real docs/ submodule)
+// ============================================================================
+describe('buildDocs against docs/ submodule', () => {
+  let outDir: string;
+
+  beforeEach(() => {
+    outDir = mkdtempSync(path.join(os.tmpdir(), 'render-docs-'));
+  });
+
+  afterEach(() => {
+    rmSync(outDir, { recursive: true, force: true });
+  });
+
+  it('throws a clear error when the docs source directory is missing', async () => {
+    await expect(buildDocs({ srcDir: path.join(outDir, 'nope'), outDir })).rejects.toThrow(
+      /docs.*missing|missing.*docs|submodule/iu,
+    );
+  });
+
+  it('throws a clear error when the docs source directory is present but empty', async () => {
+    // Mirrors the build-script guard: an empty `docs/` checkout (submodule
+    // init'd but not populated) must fail loudly with the recovery command,
+    // not silently produce a docs section with zero pages.
+    const empty = mkdirSync(path.join(outDir, 'empty-docs'), { recursive: true });
+    if (empty === undefined) {
+      throw new Error('test setup failed: could not create empty-docs dir');
+    }
+    await expect(buildDocs({ srcDir: empty, outDir })).rejects.toThrow(/empty|submodule/iu);
+  });
+
+  it('emits an index.html under the output directory', async () => {
+    await buildDocs({ srcDir: docsSrc, outDir });
+    const idx = path.join(outDir, 'index.html');
+    expect(existsSync(idx)).toBe(true);
+    expect(statSync(idx).size).toBeGreaterThan(0);
+  });
+
+  it('emits one HTML file per markdown source (non-empty output directory)', async () => {
+    const result = await buildDocs({ srcDir: docsSrc, outDir });
+    expect(result.emitted.length).toBeGreaterThanOrEqual(20);
+    for (const f of result.emitted) {
+      expect(f.endsWith('.html')).toBe(true);
+      expect(existsSync(path.join(outDir, f))).toBe(true);
+    }
+    expect(readdirSync(outDir).filter((f) => f.endsWith('.html')).length).toBe(
+      result.emitted.length,
+    );
+  });
+
+  it('renders Services.html with an <h1> and at least one <code> block', async () => {
+    await buildDocs({ srcDir: docsSrc, outDir });
+    const html = readFileSync(path.join(outDir, 'Services.html'), 'utf8');
+    expect(html).toMatch(/<h1[^>]*>/);
+    expect(html).toMatch(/<pre[^>]*><code/);
+    // The raw markdown marker should not survive rendering.
+    expect(html).not.toMatch(/^# IRC Services Reference/m);
+  });
+
+  it('emits Home as the index (index.html)', async () => {
+    await buildDocs({ srcDir: docsSrc, outDir });
+    const html = readFileSync(path.join(outDir, 'index.html'), 'utf8');
+    // Home.md's "Welcome to the Wiki." lead-in should be present.
+    expect(html).toMatch(/Welcome to the Wiki/i);
+  });
+
+  it('rewrites intra-docs links to .html in the rendered output (no .md hrefs remain)', async () => {
+    await buildDocs({ srcDir: docsSrc, outDir });
+    const files = readdirSync(outDir).filter((f) => f.endsWith('.html'));
+    expect(files.length).toBeGreaterThan(0);
+    for (const f of files) {
+      const html = readFileSync(path.join(outDir, f), 'utf8');
+      // No intra-docs .md href may remain. (External https://…/foo.md is fine.)
+      const intraMd = html.match(/href="(?!https?:|mailto:|#)[^"]*\.md[^"]*"/g) ?? [];
+      expect(intraMd).toEqual([]);
+    }
+  });
+
+  it('emits a shared stylesheet (referenced by every page)', async () => {
+    await buildDocs({ srcDir: docsSrc, outDir });
+    const files = readdirSync(outDir).filter((f) => f.endsWith('.html'));
+    // Every page links the same stylesheet.
+    for (const f of files) {
+      const html = readFileSync(path.join(outDir, f), 'utf8');
+      expect(html).toMatch(/<link[^>]+rel=["']stylesheet["']/);
+    }
+    // And the stylesheet actually exists in the output.
+    const css = readdirSync(outDir).filter((f) => f.endsWith('.css'));
+    expect(css.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('emits an ADR-Index page that links each ADR via a rewritten .html href', async () => {
+    await buildDocs({ srcDir: docsSrc, outDir });
+    const html = readFileSync(path.join(outDir, 'ADR-Index.html'), 'utf8');
+    expect(html).toMatch(/ADR-001-pure-reducers-and-effect-system\.html/);
+  });
+});

package/docs/AWS-Adapter-Architecture.md

@@ -373,8 +373,9 @@ scheme (post-v1).
         │
         │  all-or-nothing → races structurally impossible
         │
-        ▼
-   dispatch Broadcast(JOIN), 353 NAMES, 366 END-NAMES
+         ▼
+   dispatch Broadcast(JOIN), 353 NAMES, 366 END-NAMES,
+           and when a topic is set: 332 RPL_TOPIC, 333 RPL_TOPICWHOTIME
 ```
 
 A `CancellationException` from `TransactWriteItems` maps to the