Moku6

Define, lint, and document business-level audit events.

moku6 is not another audit log storage library. It helps teams define what should be recorded as audit events, how each event should be shaped, which fields are required, whether personal data must be hidden, and whether the event can be shown to customers.

It is designed for SaaS teams that need consistent audit logs across multiple products.

Installation

Install the gem and add to the application's Gemfile by executing:

bundle add moku6

If bundler is not being used to manage dependencies, install the gem by executing:

gem install moku6

Usage

moku6 init        # Generate the catalog/ and .moku6.yml scaffold
moku6 lint        # Lint audit event definitions
moku6 generate docs

Commands

moku6 init                       # Generate the scaffold (catalog/ and config)
moku6 lint                       # Lint definitions
moku6 lint --format json         # Output results as JSON
moku6 lint --strict              # Treat warnings as errors
moku6 diff OLD NEW               # Detect breaking changes between two catalogs
moku6 diff OLD NEW --format markdown --out report.md  # Review-friendly diff report
moku6 generate docs              # Markdown overview
moku6 generate schema            # Runtime JSON Schema
moku6 generate typescript        # TypeScript types
moku6 generate ruby              # Ruby constants
moku6 generate bigquery          # BigQuery DDL
moku6 generate cloudevents       # CloudEvents JSON Schema
moku6 generate eventcatalog      # EventCatalog event docs
moku6 generate openapi           # OpenAPI 3.1 document
moku6 generate rails             # Ruby/Rails emitter SDK
moku6 generate outbox            # Sample Rails transactional outbox
moku6 generate examples          # Sample events
moku6 generate all               # All core artifacts
moku6 version                    # Show the version

Common options

Option	Default	Description
--catalog DIR	catalog	Definition directory
--config FILE	.moku6.yml	Config file
--out PATH	(per artifact)	Output path (file or directory)
`--format text\	json`	text

Exit codes

Code	Meaning
0	Success (no lint errors / generation succeeded)
1	Lint detected an error
2	Usage error (invalid arguments, missing file/directory, YAML parse failure)

Audit event definition example

action: employee.updated
label: Employee updated
description: Recorded when an employee's basic information is updated
category: employee
required: true
actor: { required: true }
target: { type: employee, required: true }
fields:
  employee_id: { type: string, required: true, description: ID of the updated employee }
  changed_fields: { type: array, required: true, description: List of changed field names }
privacy:
  contains_personal_data: true
  masked_fields: [before.email, after.email]
visibility: { customer_visible: true, internal_only: false }
retention: { years: 5 }

GitHub Actions example for consumers

An example of linting in the CI of each product repository that defines audit events.

name: moku6
on:
  pull_request:
jobs:
  lint-audit-events:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.3"
      - name: Install moku6
        run: gem install moku6
      - name: Lint audit event catalog
        run: moku6 lint

For Bundler-managed projects, add gem "moku6" to your Gemfile and run bundle exec moku6 lint.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/ydah/moku6.

License

The gem is available as open source under the terms of the MIT License.