Add documentation for available audit event types

Create a rake task to auto generate documentation for all the available
audit event types.

config/audit_events/types/manually_trigger_housekeeping.yml

 ---
 name: manually_trigger_housekeeping
-description: Triggered when manually triggering housekeeping via api or admin UI
+description: Triggered when manually triggering housekeeping via API or admin UI
 introduced_by_issue: https://gitlab.com/gitlab-org/gitlab/-/issues/390761
 introduced_by_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/112095
 feature_category: source_code_management

ee/config/audit_events/types/allow_merge_on_skipped_pipeline_updated.yml

 ---
 name: allow_merge_on_skipped_pipeline_updated
-description: There is a project setting which toggles the ability to merge when a pipeline is skipped. This audit event tracks changes to that setting. This MR adds a setting to allow this (like previous Gitlab versions).
+description: There is a project setting which toggles the ability to merge when a pipeline is skipped. This audit event tracks changes to that setting. This MR adds a setting to allow this (like previous GitLab versions).
 introduced_by_issue: https://gitlab.com/gitlab-org/gitlab/-/issues/301124
 introduced_by_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83922
 milestone: '14.10'

ee/config/audit_events/types/google_cloud_logging_configuration_created.yml

 ---
 name: google_cloud_logging_configuration_created
-description: Triggered when google cloud logging configuration is created
+description: Triggered when Google Cloud Logging configuration is created
 introduced_by_issue: https://gitlab.com/gitlab-org/gitlab/-/issues/409422
 introduced_by_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122025
 milestone: '16.1'

ee/config/audit_events/types/google_cloud_logging_configuration_deleted.yml

 ---
 name: google_cloud_logging_configuration_deleted
-description: Triggered when google cloud logging configuration is deleted
+description: Triggered when Google Cloud Logging configuration is deleted
 introduced_by_issue: https://gitlab.com/gitlab-org/gitlab/-/issues/409422
 introduced_by_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122025
 milestone: '16.1'

ee/config/audit_events/types/google_cloud_logging_configuration_updated.yml

 ---
 name: google_cloud_logging_configuration_updated
-description: Triggered when google cloud logging configuration is updated
+description: Triggered when Google Cloud Logging configuration is updated
 introduced_by_issue: https://gitlab.com/gitlab-org/gitlab/-/issues/409422
 introduced_by_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/122025
 milestone: '16.1'

ee/config/audit_events/types/group_push_rules_reject_deny_delete_tag_updated.yml

 ---
 name: group_push_rules_reject_deny_delete_tag_updated
-description: Triggered when group push rule setting is updated to deny deletion of tags using git push.
+description: Triggered when group push rule setting is updated to deny deletion of tags using Git push.
 introduced_by_issue: https://gitlab.com/gitlab-org/gitlab/-/issues/227629
 introduced_by_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/86046
 feature_category: source_code_management

ee/config/audit_events/types/remove_ssh_key.yml

 ---
 name: remove_ssh_key
-description: Audit event triggered when a ssh key is removed
+description: Audit event triggered when a SSH key is removed
 introduced_by_issue: https://gitlab.com/gitlab-org/gitlab/-/issues/220127
 introduced_by_mr: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/65615
 milestone: '14.1'

lefthook.yml

@@ -98,6 +98,11 @@ pre-push:
       tags: backend bundler
       glob: 'Gemfile.lock'
       run: bundle exec bundler-checksum lint
+    audit_event_types_docs:
+      tags: documentation
+      files: git diff --name-only --diff-filter=d $(git merge-base origin/master HEAD)..HEAD
+      glob: '{config/audit_events/types/*.yml,ee/config/audit_events/types/*yml}'
+      run: bundle exec rake gitlab:audit_event_types:check_docs
 
   scripts:
     "merge_conflicts":

lib/tasks/gitlab/audit_event_types/audit_event_types.rake

+# frozen_string_literal: true
+
+return if Rails.env.production?
+
+namespace :gitlab do
+  namespace :audit_event_types do
+    event_types_dir = Rails.root.join("doc/administration/audit_event_streaming")
+    event_types_doc_file = Rails.root.join(event_types_dir, 'audit_event_types.md')
+    template_directory = 'tooling/audit_events/docs/templates/'
+    template_erb_file_path = Rails.root.join(template_directory, 'audit_event_types.md.erb')
+
+    desc 'GitLab | Audit event types | Generate audit event types docs'
+    task compile_docs: :environment do
+      require_relative './compile_docs_task'
+
+      Tasks::Gitlab::AuditEventTypes::CompileDocsTask
+        .new(event_types_dir, event_types_doc_file, template_erb_file_path).run
+    end
+
+    desc 'GitLab | Audit event types | Check if Audit event types docs are up to date'
+    task check_docs: :environment do
+      require_relative './check_docs_task'
+
+      Tasks::Gitlab::AuditEventTypes::CheckDocsTask
+        .new(event_types_dir, event_types_doc_file, template_erb_file_path).run
+    end
+  end
+end

lib/tasks/gitlab/audit_event_types/check_docs_task.rb

+# frozen_string_literal: true
+
+module Tasks
+  module Gitlab
+    module AuditEventTypes
+      class CheckDocsTask
+        def initialize(docs_dir, docs_path, template_erb_path)
+          @event_types_dir = docs_dir
+          @audit_event_types_doc_file = docs_path
+          @event_type_erb_template = ERB.new(File.read(template_erb_path), trim_mode: '<>')
+        end
+
+        def run
+          doc = File.read(@audit_event_types_doc_file)
+
+          if doc == @event_type_erb_template.result
+            puts "Audit event types documentation is up to date."
+          else
+            error_message = "Audit event types documentation is outdated! Please update it by running " \
+                            "`bundle exec rake gitlab:audit_event_types:compile_docs`."
+            heading = '#' * 10
+            puts heading
+            puts '#'
+            puts "# #{error_message}"
+            puts '#'
+            puts heading
+
+            abort
+          end
+        end
+      end
+    end
+  end
+end

lib/tasks/gitlab/audit_event_types/compile_docs_task.rb

+# frozen_string_literal: true
+
+module Tasks
+  module Gitlab
+    module AuditEventTypes
+      class CompileDocsTask
+        def initialize(docs_dir, docs_path, template_erb_path)
+          @event_types_dir = docs_dir
+          @audit_event_types_doc_file = docs_path
+          @event_type_erb_template = ERB.new(File.read(template_erb_path), trim_mode: '<>')
+        end
+
+        def run
+          FileUtils.mkdir_p(@event_types_dir)
+          File.write(@audit_event_types_doc_file, @event_type_erb_template.result)
+
+          puts "Documentation compiled."
+        end
+      end
+    end
+  end
+end

spec/tasks/gitlab/audit_event_types/audit_event_types_rake_spec.rb

+# frozen_string_literal: true
+
+require 'rake_helper'
+require_relative '../../../../lib/tasks/gitlab/audit_event_types/check_docs_task'
+require_relative '../../../../lib/tasks/gitlab/audit_event_types/compile_docs_task'
+
+RSpec.describe 'gitlab:audit_event_types rake tasks', :silence_stdout, feature_category: :audit_events do
+  before do
+    Rake.application.rake_require('tasks/gitlab/audit_event_types/audit_event_types')
+    stub_env('VERBOSE' => 'true')
+    Gitlab::Audit::Type::Definition.clear_memoization(:definitions)
+  end
+
+  describe 'compile_docs' do
+    it 'invokes Gitlab::AuditEventTypes::CompileDocsTask with correct arguments' do
+      compile_docs_task = instance_double(Tasks::Gitlab::AuditEventTypes::CompileDocsTask)
+
+      expect(Tasks::Gitlab::AuditEventTypes::CompileDocsTask).to receive(:new).with(
+        Rails.root.join("doc/administration/audit_event_streaming"),
+        Rails.root.join("doc/administration/audit_event_streaming/audit_event_types.md"),
+        Rails.root.join("tooling/audit_events/docs/templates/audit_event_types.md.erb")).and_return(compile_docs_task)
+
+      expect(compile_docs_task).to receive(:run)
+
+      run_rake_task('gitlab:audit_event_types:compile_docs')
+    end
+  end
+
+  describe 'check_docs' do
+    it 'invokes Gitlab::AuditEventTypes::CheckDocsTask with correct arguments' do
+      check_docs_task = instance_double(Tasks::Gitlab::AuditEventTypes::CheckDocsTask)
+
+      expect(Tasks::Gitlab::AuditEventTypes::CheckDocsTask).to receive(:new).with(
+        Rails.root.join("doc/administration/audit_event_streaming"),
+        Rails.root.join("doc/administration/audit_event_streaming/audit_event_types.md"),
+        Rails.root.join("tooling/audit_events/docs/templates/audit_event_types.md.erb")).and_return(check_docs_task)
+
+      expect(check_docs_task).to receive(:run)
+
+      run_rake_task('gitlab:audit_event_types:check_docs')
+    end
+  end
+end

spec/tasks/gitlab/audit_event_types/check_docs_task_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+require_relative '../../../../lib/tasks/gitlab/audit_event_types/check_docs_task'
+require_relative '../../../../lib/tasks/gitlab/audit_event_types/compile_docs_task'
+
+RSpec.describe Tasks::Gitlab::AuditEventTypes::CheckDocsTask, feature_category: :audit_events do
+  let_it_be(:docs_dir) { Rails.root.join("tmp/tests/doc/administration/audit_event_streaming") }
+  let_it_be(:docs_path) { Rails.root.join(docs_dir, 'audit_event_types.md') }
+  let_it_be(:template_erb_path) { Rails.root.join("tooling/audit_events/docs/templates/audit_event_types.md.erb") }
+
+  subject(:check_docs_task) { described_class.new(docs_dir, docs_path, template_erb_path) }
+
+  describe '#run' do
+    before do
+      Gitlab::Audit::Type::Definition.clear_memoization(:definitions)
+      Tasks::Gitlab::AuditEventTypes::CompileDocsTask.new(docs_dir, docs_path, template_erb_path).run
+    end
+
+    context 'when audit_event_types.md is up to date' do
+      it 'outputs success message after checking the documentation' do
+        expect { subject.run }.to output("Audit event types documentation is up to date.\n").to_stdout
+      end
+    end
+
+    context 'when audit_event_types.md is updated manually' do
+      before do
+        File.write(docs_path, "Manually adding this line at the end of the audit_event_types.md", mode: 'a+')
+      end
+
+      it 'raises an error' do
+        expected_output = "Audit event types documentation is outdated! Please update it " \
+                          "by running `bundle exec rake gitlab:audit_event_types:compile_docs`"
+
+        expect { subject.run }.to raise_error(SystemExit).and output(/#{expected_output}/).to_stdout
+      end
+    end
+
+    context 'when an existing audit event type is removed' do
+      let_it_be(:updated_definition) { Gitlab::Audit::Type::Definition.definitions.except(:feature_flag_created) }
+
+      it 'raises an error' do
+        expect(Gitlab::Audit::Type::Definition).to receive(:definitions).and_return(updated_definition)
+
+        expected_output = "Audit event types documentation is outdated! Please update it " \
+                          "by running `bundle exec rake gitlab:audit_event_types:compile_docs`"
+
+        expect { subject.run }.to raise_error(SystemExit).and output(/#{expected_output}/).to_stdout
+      end
+    end
+
+    context 'when an existing audit event type is updated' do
+      let_it_be(:updated_definition) { Gitlab::Audit::Type::Definition.definitions }
+
+      it 'raises an error' do
+        updated_definition[:feature_flag_created].attributes[:streamed] = false
+
+        expect(Gitlab::Audit::Type::Definition).to receive(:definitions).and_return(updated_definition)
+
+        expected_output = "Audit event types documentation is outdated! Please update it " \
+                          "by running `bundle exec rake gitlab:audit_event_types:compile_docs`"
+
+        expect { subject.run }.to raise_error(SystemExit).and output(/#{expected_output}/).to_stdout
+      end
+    end
+  end
+end

spec/tasks/gitlab/audit_event_types/compile_docs_task_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+require_relative '../../../../lib/tasks/gitlab/audit_event_types/compile_docs_task'
+
+RSpec.describe Tasks::Gitlab::AuditEventTypes::CompileDocsTask, feature_category: :audit_events do
+  let_it_be(:docs_dir) { Rails.root.join("tmp/tests/doc/administration/audit_event_streaming") }
+  let_it_be(:docs_path) { Rails.root.join(docs_dir, 'audit_event_types.md') }
+  let_it_be(:template_erb_path) { Rails.root.join("tooling/audit_events/docs/templates/audit_event_types.md.erb") }
+
+  subject(:compile_docs_task) { described_class.new(docs_dir, docs_path, template_erb_path) }
+
+  describe '#run' do
+    it 'outputs message after compiling the documentation' do
+      expect { subject.run }.to output("Documentation compiled.\n").to_stdout
+    end
+
+    it 'creates audit_event_types.md', :aggregate_failures do
+      FileUtils.rm_f(docs_path)
+
+      expect { File.read(docs_path) }.to raise_error(Errno::ENOENT)
+
+      subject.run
+
+      expect(File.read(docs_path).size).not_to eq(0)
+      expect(File.read(docs_path)).to match(/This documentation is auto generated by a Rake task/)
+    end
+  end
+end

tooling/audit_events/docs/templates/audit_event_types.md.erb

+<% all_audit_event_types = Gitlab::Audit::Type::Definition.definitions.map(&:last) %>
+<% def boolean_to_docs(boolean) %>
+<%   if boolean %>
+<%     "**{check-circle}** Yes" %>
+<%   else %>
+<%     "**{dotted-circle}** No" %>
+<%   end %>
+<% end %>
+---
+stage: Govern
+group: Compliance
+info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments-to-development-guidelines"
+---
+
+<!---
+  This documentation is auto generated by a Rake task.
+
+  Please do not edit this file directly, check compile_docs task on lib/tasks/gitlab/audit_event_types.rake.
+--->
+
+# Available audit event types  **(ULTIMATE)**
+
+Audit event types are used to [filter streamed audit events](index.md#update-event-filters).
+
+| Name | Description | Saved to database | Streamed | Feature category | Milestone |
+|----------|-------------------------------------|----|----|----------------|------|
+<% all_audit_event_types.each do |event_type| %>| <%= "[`#{event_type.name}`](#{event_type.introduced_by_mr})" %> | <%= event_type.description %> | <%= boolean_to_docs(event_type.saved_to_database) %> | <%= boolean_to_docs(event_type.streamed) %> | <%= "`#{event_type.feature_category}`" %> | <%= "[#{event_type.milestone}](#{event_type.introduced_by_issue})" %> |
+<% end %>