Add an audit event reference generator (#60290)

* Add an audit event reference generator

Closes #5044
Closes #10350

This change adds a generator for audit event reference documentation
based on Web UI audit event formatters and, if available, test fixtures.

Previous attempts to generate an audit event reference drew from the
Teleport source using `AuditEvent` declarations (#13615) and naming
conventions (#38344), but inconsistencies within the source meant that
the resulting generator was inadequate. The Web UI source files
represent the most complete set of source data we have on audit event
schemas.

Implementation details:

- If an event includes a fixture, use that as an example of its schema.
  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.
- 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.

Co-authored-by: Rafał Cieślak <[email protected]>

* Get rid of `any` in types

The events map did not define what types it stores, so TypeScript
defaulted it to Map<any, any>. After adjusting this type, it turned out
that there were many functions with worked on Event but were actually
given ReferencePageEventData, so I changed their signatures too.

Types usually start with upper case, hence ReferencePageEventData and
not referencePageEventData.

The `as` in `Object.keys(formatters) as Array<keyof Formatters>` was
not necessary, as TypeScript correctly infers the type here.

* Add more context to the README

* Add shorthand command to build and gen reference

* Check audit event reference docs in CI

Add Make targets for running and checking the audit event reference
docs. Add a step to the GitHub Actions job that runs Web UI linters to
check the audit event reference docs.

---------

Co-authored-by: Rafał Cieślak <[email protected]>

Author: ptgott

.github/workflows/lint.yaml

@@ -334,3 +334,8 @@ jobs:
       - name: Check icons
         # We have to add the current directory as a safe directory or else git commands will not work as expected.
         run: git config --global --add safe.directory $(realpath .) && make icons-up-to-date
+
+      - name: Check audit event reference docs
+        # We have to add the current directory as a safe directory or else git commands will not work as expected.
+        run: git config --global --add safe.directory $(realpath .) && make audit-event-reference-up-to-date
+

Makefile

@@ -1982,8 +1982,24 @@ cli-docs-tsh:
 	$(BUILDDIR)/tshdocs help 2>docs/pages/reference/cli/tsh.mdx && \
 	rm $(BUILDDIR)/tshdocs
 
+# audit-event-reference generates audit event reference docs using the Web UI
+# source.
+.PHONY: audit-event-reference
+audit-event-reference:
+	pnpm run -C ./web/packages/teleport event-reference
+
+# audit-event-reference-up-to-date ensures the audit event reference
+# documentation reflects the Web UI source.
+.PHONY: audit-event-reference-up-to-date
+audit-event-reference-up-to-date: must-start-clean/host audit-event-reference
+	@if ! git diff --quiet; then \
+		./build.assets/please-run.sh "audit event reference docs" "make audit-event-reference"; \
+		exit 1; \
+	fi
+
 .PHONY: gen-docs
 gen-docs:
 	$(MAKE) -C integrations/terraform docs
 	$(MAKE) -C integrations/operator crd-docs
 	$(MAKE) -C examples/chart render-chart-ref
+	$(MAKE) audit-event-reference