Add an audit event reference generator

Closes #5044
Closes #10350

One source of Teleport audit event data is the fixtures file we use for
testing the audit event view within the Web UI. We usually update our
test fixtures when we add an audit event, since we need to display new
audit events as expected within the Web UI. This change adds a generator
for the audit event reference documentation based on the test fixtures.

Previous attempts to generate an audit event reference drew from the
Teleport source, rather than test fixtures, using `AuditEvent`
declarations (#13615) and naming conventions (#38344), but
inconsistencies within the source meant that the resulting generator was
inadequate.

Implementation details:

- Use vite to transpile the test fixture into a library that we can
  import into a short script.
- Alphabetize reference sections by event type.
- Ignore "Unknown" event descriptions, leaving these blank.
- If one event type includes multiple possible codes, document each code
  in an H3 section.
- Ignore instances of the same code beyond the first occurrence.

Author: ptgott

docs/gen-event-reference/README.md

@@ -0,0 +1,13 @@
+# Audit event reference generator
+
+Build the event fixtures:
+
+```bash
+$ pnpm build
+```
+
+Generate the reference docs:
+
+```bash
+$ pnpm gen-docs
+```

docs/gen-event-reference/events.vite.config.mts

@@ -0,0 +1,23 @@
+import path from 'node:path';
+import { defineConfig } from 'vite';
+import tsconfigPaths from 'vite-tsconfig-paths';
+const outputDirectory = path.resolve(__dirname, 'build');
+
+function tsconfigPathsPlugin() {
+  return tsconfigPaths({
+    root: path.resolve(import.meta.dirname, '../..'),
+  });
+}
+
+export default defineConfig(() => ({
+  plugins: [tsconfigPathsPlugin()],
+  build: {
+    lib: {
+      name: 'event-fixtures',
+      entry: path.resolve(__dirname, '../../web/packages/teleport/src/Audit/fixtures/index.ts'),
+      fileName: 'event-fixtures',
+      formats: ['es' as const],
+    },
+    outDir: path.resolve(outputDirectory, 'events'),
+  },
+}));

docs/gen-event-reference/gen-event-reference.js

@@ -0,0 +1,99 @@
+// createEventSection takes a JSON document that defines an audit event test
+// fixture and returns a string that contains an H2-level section to describe
+// the event.
+//
+// See web/packages/teleport/src/Audit/fixtures/index.ts for the
+// structure of an audit event test fixture.
+export function createEventSection(event) {
+  return `## ${event.raw.event}
+${event.codeDesc == 'Unknown' ? '' : '\n' + event.codeDesc + '\n'}
+Example:
+
+\`\`\`json
+${JSON.stringify(event.raw, null, 2)}
+\`\`\`
+`;
+}
+
+// createMultipleEventsSection takes an array of JSON documents that define an
+// audit event test fixture and returns a string that contains an H2-level
+// section to describe the event. It includes a separate H3 section for each
+// event code.
+//
+// See web/packages/teleport/src/Audit/fixtures/index.ts for the structure of an
+// audit event test fixture.
+export function createMultipleEventsSection(events) {
+  return events.reduce(
+    (accum, event) => {
+      return (
+        accum +
+        '\n' +
+        `### ${event.raw.code}
+${event.codeDesc == 'Unknown' ? '' : '\n' + event.codeDesc + '\n'}
+Example:
+
+\`\`\`json
+${JSON.stringify(event.raw, null, 2)}
+\`\`\`
+`
+      );
+    },
+    `## ${events[0].raw.event}
+
+There are multiple events with the \`${events[0].raw.event}\` type.
+`
+  );
+}
+
+// createReferencePage takes an array of JSON documents that define an audit
+// event test fixture and returns a string that contains the text of an audit
+// event reference guide.
+//
+// introParagraph contains the text of the introductory paragraph to include in
+// the guide.
+//
+// See web/packages/teleport/src/Audit/fixtures/index.ts for the structure of an
+// audit event test fixture.
+export function createReferencePage(jsonEvents, introParagraph) {
+  const codeSet = new Set();
+  let result = jsonEvents;
+  result.sort((a, b) => {
+    if (a.raw.event < b.raw.event) {
+      return -1;
+    } else {
+      return 1;
+    }
+  });
+  const events = new Map();
+  result.forEach(e => {
+    if (codeSet.has(e.raw.code)) {
+      return;
+    }
+    const codeData = events.get(e.raw.event);
+    codeSet.add(e.raw.code);
+    if (!codeData) {
+      events.set(e.raw.event, [e]);
+      return;
+    }
+    codeData.push(e);
+  });
+
+  return events.keys().reduce(
+    (accum, current) => {
+      const codes = events.get(current);
+      if (codes.length == 1) {
+        return accum + '\n' + createEventSection(codes[0]);
+      }
+      return accum + '\n' + createMultipleEventsSection(codes);
+    },
+    `---
+title: "Audit Event Reference"
+description: "Provides a comprehensive list of Teleport audit events and their fields."
+---
+{/* Generated file. Do not edit. */}
+{/* To regenerate, navigate to docs/gen-event-reference and run pnpm gen-docs */}
+
+${introParagraph}
+`
+  );
+}