Include all events in the reference guide

Responds to zmb3 feedback.

When we add a new event, we need to edit the formatters in
`makeEvent.ts` so the event appears in the Web UI. For any event
formatter with no test fixture, include the event, type, code, and
description in the reference guide using data from the formatter, but
don't include an example. Also remove any test fixtures from the guide
that don't correspond to a formatter.

Also log events with no examples when running the generator so we can
add test fixtures later on.

Author: ptgott

docs/gen-event-reference/.gitignore

@@ -0,0 +1 @@
+dist/*

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

@@ -1,6 +1,8 @@
 import path from 'node:path';
+
 import { defineConfig } from 'vite';
 import tsconfigPaths from 'vite-tsconfig-paths';
+
 const outputDirectory = path.resolve(__dirname, 'build');
 
 function tsconfigPathsPlugin() {
@@ -14,10 +16,17 @@ export default defineConfig(() => ({
   build: {
     lib: {
       name: 'event-fixtures',
-      entry: path.resolve(__dirname, '../../web/packages/teleport/src/Audit/fixtures/index.ts'),
-      fileName: 'event-fixtures',
-      formats: ['es' as const],
+      entry: {
+        fixtures: path.resolve(
+          __dirname,
+          '../../web/packages/teleport/src/Audit/fixtures/index.ts'
+        ),
+        formatters: path.resolve(
+          __dirname,
+          '../../web/packages/teleport/src/services/audit/makeEvent.ts'
+        ),
+      },
+      formats: ['es'],
     },
-    outDir: path.resolve(outputDirectory, 'events'),
   },
 }));

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

@@ -1,17 +1,83 @@
+// The functions in this package rely on the following packages in the Teleport
+// Web UI source:
+// 
+// - The events array in web/packages/teleport/src/Audit/fixtures/index.ts
+// - The formatters array in web/packages/teleport/src/services/audit/makeEvent.ts
+
+// eventsWithoutExamples returns an array of event objects based on the
+// elements in formatters that do not have corresponding examples in fixtures.
+export function eventsWithoutExamples(fixtures, formatters) {
+  const fixtureMap = new Map();
+  let result = [];
+  fixtures.forEach(f => {
+    fixtureMap.set(f.code, true);
+  });
+  Object.keys(formatters).forEach(k => {
+    if (fixtureMap.has(k)) {
+      return;
+    }
+    result.push({
+      codeDesc: formatters[k].desc,
+      code: k,
+      raw: {
+        event: formatters[k].type,
+      },
+    });
+  });
+  return result;
+}
+
+// codeDesc returns the description of the given event, depending on whether the
+// description is a function or a string.
+function codeDesc(event) {
+  if (typeof event.codeDesc == 'function') {
+    return event.codeDesc({ code: event.code, event: event.raw.event });
+  }
+  return event.codeDesc;
+}
+
+// removeUnknowns removes any event fixtures in the fixtures array that do not
+// have a formatter.
+export function removeUnknowns(fixtures, formatters) {
+  let result = [];
+  fixtures.forEach(r => {
+    const formatter = formatters[r.code];
+    if (!formatter) {
+      return;
+    }
+    result.push(r);
+  });
+  return result;
+}
+
+// exampleOrAttributes returns a string to include in a reference entry for an
+// audit event that describes the event's attributes.
+//
+// The generator expects all event objects to include a raw.event attribute, and
+// events with full examples include additional fields in the raw object. If
+// there is an example available for the event, we include the example,
+// formatted as JSON. Otherwise, we print only the event code and type.
+export function exampleOrAttributes(event) {
+  if (Object.keys(event.raw).length > 1) {
+    return `Example:
+
+\`\`\`json
+${JSON.stringify(event.raw, null, 2)}
+\`\`\``;
+  }
+  return `Code: \`${event.code}\`
+
+Event: \`${event.raw.event}\``;
+}
+
 // 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)}
-\`\`\`
+${codeDesc(event) + '\n'}
+${exampleOrAttributes(event)}
 `;
 }
 
@@ -28,13 +94,10 @@ export function createMultipleEventsSection(events) {
       return (
         accum +
         '\n' +
-        `### ${event.raw.code}
-${event.codeDesc == 'Unknown' ? '' : '\n' + event.codeDesc + '\n'}
-Example:
+        `### ${event.code}
 
-\`\`\`json
-${JSON.stringify(event.raw, null, 2)}
-\`\`\`
+${codeDesc(event) + '\n'}
+${exampleOrAttributes(event)}
 `
       );
     },
@@ -66,11 +129,11 @@ export function createReferencePage(jsonEvents, introParagraph) {
   });
   const events = new Map();
   result.forEach(e => {
-    if (codeSet.has(e.raw.code)) {
+    if (codeSet.has(e.code)) {
       return;
     }
     const codeData = events.get(e.raw.event);
-    codeSet.add(e.raw.code);
+    codeSet.add(e.code);
     if (!codeData) {
       events.set(e.raw.event, [e]);
       return;