moku6 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cecdef76990b4c77ed9961c59f114e6729bfe2f459bbf150d5c04f9717169ea4
+  data.tar.gz: 144a332287dcd00a9e02461ad6c569b4b75483bcc8466d63b6f241521ac34929
+SHA512:
+  metadata.gz: 77dec0db7f88e103190e89b745a10f8ca78d170ae9bd5aa285b3c87261e40f8e9e48b84d012e48fe10b09dec21fbbf76d651e02ec3ea5915d2fc822e7acaca37
+  data.tar.gz: 5662ce82ce050b334f1b97d1bc43fc5750d103035331a771db60c30e793d0d0bfcbe998da5e3f2917fc6d052629f4dda8b9d961e09225b9f7da85688e52f00f4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,131 @@
+# 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:
+
+```bash
+bundle add moku6
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install moku6
+```
+
+## Usage
+
+```bash
+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` | Output format for `lint` |
+
+### 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
+
+```yaml
+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.
+
+```yaml
+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](https://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](https://opensource.org/licenses/MIT).

data/exe/moku6

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "moku6"
+
+Moku6::CLI.start(ARGV)

data/lib/moku6/catalog.rb

@@ -0,0 +1,23 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  class Catalog
+    attr_reader :events #: Array[Event]
+
+    #: (Array[Event] events) -> void
+    def initialize(events) = @events = events
+
+    #: () -> Array[String?]
+    def actions = events.map(&:action)
+
+    #: () -> Array[Event]
+    def sorted = events.sort_by { |e| e.action.to_s }
+
+    #: (String? action) -> Event?
+    def find(action) = events.find { |e| e.action == action }
+
+    #: () -> bool
+    def empty? = events.empty?
+  end
+end

data/lib/moku6/cli.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Moku6
+  class CLI
+    BANNER = <<~TEXT
+      Usage: moku6 COMMAND [options]
+
+      Commands:
+        version            Show the version
+        init               Generate a catalog scaffold
+        lint               Lint audit event definitions
+        diff OLD NEW       Detect breaking changes between two catalog directories
+        generate SUB       Generate output artifacts (see: moku6 generate --help)
+
+      Global options:
+        --catalog DIR      Catalog directory (default: catalog)
+        --config FILE      Config file (default: .moku6.yml)
+    TEXT
+
+    def self.start(argv) = new.start(argv)
+
+    def start(argv)
+      argv = Array(argv).dup
+      command = argv.shift
+      case command
+      when "version" then cmd_version
+      when "init" then cmd_init(argv)
+      when "lint" then cmd_lint(argv)
+      when "diff" then cmd_diff(argv)
+      when "generate" then Generate.new.start(argv)
+      when nil, "help", "-h", "--help" then puts BANNER
+      else
+        warn "Unknown command: #{command}"
+        warn BANNER
+        exit 2
+      end
+    end
+
+    private
+
+    def cmd_version
+      puts "moku6 #{Moku6::VERSION}"
+    end
+
+    def cmd_init(argv)
+      options = {}
+      parse(argv, "init") { |o| global_options(o, options) }
+      Initializer.new(options).run
+    end
+
+    def cmd_lint(argv)
+      options = {format: "text"}
+      parse(argv, "lint [options]") do |o|
+        global_options(o, options)
+        o.on("--format FORMAT", %w[text json], "Output format (text, json)") { |v| options[:format] = v }
+        o.on("--strict", "Treat warnings as errors (exit 1)") { options[:strict] = true }
+      end
+      config = Config.load(options)
+      catalog = Loader.new(config.catalog_dir).load
+      if catalog.empty?
+        warn "Warning: no event definitions found in catalog: #{config.catalog_dir}"
+      end
+      result = Linter.new(catalog, config).run
+      Reporter.for(options[:format]).report(result)
+      failed = result.errors? || (config.strict? && result.warnings.any?)
+      exit(failed ? 1 : 0)
+    rescue Moku6::UsageError => e
+      warn "Error: #{e.message}"
+      exit 2
+    end
+
+    def cmd_diff(argv)
+      options = {format: "text"}
+      rest = parse(argv, "diff OLD NEW [options]") do |o|
+        global_options(o, options)
+        o.on("--format FORMAT", %w[text json markdown], "Output format (text, json, markdown)") { |v| options[:format] = v }
+        o.on("--out PATH", "Write the report to a file instead of stdout") { |v| options[:out] = v }
+      end
+      old_dir, new_dir = rest
+      unless old_dir && new_dir
+        warn "Error: diff requires OLD and NEW catalog directories"
+        exit 2
+      end
+      old_catalog = Loader.new(old_dir).load
+      new_catalog = Loader.new(new_dir).load
+      result = Differ.new(old_catalog, new_catalog).run
+      if options[:out] && options[:format] == "markdown"
+        require "fileutils"
+        FileUtils.mkdir_p(File.dirname(options[:out]))
+        File.write(options[:out], Reporter::Markdown.render(result))
+        puts "Wrote report: #{options[:out]}"
+      else
+        Reporter.for(options[:format]).report(result)
+      end
+      exit(result.errors? ? 1 : 0)
+    rescue Moku6::UsageError => e
+      warn "Error: #{e.message}"
+      exit 2
+    end
+
+    def global_options(o, options)
+      o.on("--catalog DIR", "Catalog directory (default: catalog)") { |v| options[:catalog] = v }
+      o.on("--config FILE", "Config file (default: .moku6.yml)") { |v| options[:config] = v }
+    end
+
+    def parse(argv, usage)
+      parser = OptionParser.new
+      parser.banner = "Usage: moku6 #{usage}"
+      yield parser
+      parser.parse(argv)
+    rescue OptionParser::ParseError => e
+      warn "Error: #{e.message}"
+      exit 2
+    end
+  end
+end

data/lib/moku6/config.rb

@@ -0,0 +1,61 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "yaml"
+
+module Moku6
+  class Config
+    DEFAULTS = {
+      "catalog_dir" => "catalog",
+      "output_dir" => "generated",
+      "naming" => {"pattern" => '^[a-z0-9_]+(\.[a-z0-9_]+)+$'},
+      "rules" => {"strict" => false, "warn_pii_field_names" => true}
+    }.freeze #: Hash[String, untyped]
+
+    DEFAULT_CONFIG_PATH = ".moku6.yml" #: String
+
+    #: (?Hash[Symbol, untyped] options) -> Config
+    def self.load(options = {})
+      path = options[:config] || DEFAULT_CONFIG_PATH
+      file = File.exist?(path) ? (YAML.safe_load_file(path) || {}) : {}
+      new(deep_merge(DEFAULTS, file), options)
+    end
+
+    #: (Hash[String, untyped] base, Hash[String, untyped] override) -> Hash[String, untyped]
+    def self.deep_merge(base, override)
+      base.merge(override) do |_key, b, o|
+        (b.is_a?(Hash) && o.is_a?(Hash)) ? deep_merge(b, o) : o
+      end
+    end
+
+    attr_reader :data #: Hash[String, untyped]
+    attr_reader :options #: Hash[Symbol, untyped]
+
+    #: (Hash[String, untyped] data, ?Hash[Symbol, untyped] options) -> void
+    def initialize(data, options = {})
+      @data = data
+      @options = options
+    end
+
+    #: () -> String?
+    def catalog_dir = options[:catalog] || data["catalog_dir"]
+
+    #: () -> String?
+    def output_dir = data["output_dir"]
+
+    #: () -> String?
+    def naming_pattern = data.dig("naming", "pattern")
+
+    #: () -> bool
+    def strict? = options.fetch(:strict) { !!data.dig("rules", "strict") }
+
+    #: () -> bool
+    def warn_pii_field_names? = !!data.dig("rules", "warn_pii_field_names")
+
+    #: () -> String
+    def examples_dir = data["examples_dir"] || "examples/valid"
+
+    #: (String | Symbol name) -> String?
+    def generator_out(name) = data.dig("generators", name.to_s, "out")
+  end
+end

data/lib/moku6/differ.rb

@@ -0,0 +1,74 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  # Detects breaking changes between two catalogs (design sections 13 / 16).
+  # Breaking changes (error): action removed, required field added, field type changed.
+  class Differ
+    # @rbs @old: Catalog
+    # @rbs @new: Catalog
+
+    #: (Catalog old_catalog, Catalog new_catalog) -> void
+    def initialize(old_catalog, new_catalog)
+      @old = old_catalog
+      @new = new_catalog
+    end
+
+    #: () -> Result
+    def run
+      offenses = removed_actions
+      @new.events.each do |new_event|
+        old_event = @old.find(new_event.action)
+        next unless old_event
+
+        offenses.concat(field_changes(old_event, new_event))
+      end
+      Result.new(offenses)
+    end
+
+    private
+
+    #: () -> Array[Offense]
+    def removed_actions
+      new_actions = @new.actions
+      @old.events.reject { |e| new_actions.include?(e.action) }.map do |e|
+        breaking(e, "action '#{e.action}' was removed (breaking change).", "diff_action_removed")
+      end
+    end
+
+    #: (Event old_event, Event new_event) -> Array[Offense]
+    def field_changes(old_event, new_event)
+      old_fields = old_event.fields
+      offenses = []
+      new_event.fields.each do |name, nf|
+        of = old_fields[name]
+        if of.nil?
+          if nf["required"]
+            offenses << breaking(new_event,
+              "required field '#{name}' was added (breaking change).",
+              "diff_required_field_added")
+          end
+          next
+        end
+
+        if !of["required"] && nf["required"]
+          offenses << breaking(new_event,
+            "field '#{name}' became required (breaking change).",
+            "diff_required_field_added")
+        end
+        if of["type"] != nf["type"]
+          offenses << breaking(new_event,
+            "field '#{name}' type changed from #{of["type"]} to #{nf["type"]} (breaking change).",
+            "diff_field_type_changed")
+        end
+      end
+      offenses
+    end
+
+    #: (Event event, String message, String rule) -> Offense
+    def breaking(event, message, rule)
+      Offense.new(rule: rule, severity: :error, action: event.action,
+        file: event.source_path, message: message)
+    end
+  end
+end

data/lib/moku6/envelope_schema.rb

@@ -0,0 +1,56 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  # Builds the runtime event (envelope) validation JSON Schema from a definition.
+  # Shared by JsonSchemaGenerator and ExampleConsistencyRule (see design sections 8 / 12.2).
+  module EnvelopeSchema
+    TYPE_MAP = {
+      "string" => {"type" => "string"},
+      "integer" => {"type" => "integer"},
+      "number" => {"type" => "number"},
+      "boolean" => {"type" => "boolean"},
+      "object" => {"type" => "object"},
+      "timestamp" => {"type" => "string", "format" => "date-time"}
+    }.freeze #: Hash[String, Hash[String, String]]
+
+    module_function
+
+    #: (Event event) -> Hash[String, untyped]
+    def for(event)
+      {
+        "$schema" => "https://json-schema.org/draft/2020-12/schema",
+        "title" => event.action,
+        "type" => "object",
+        "required" => %w[event_id action occurred_at actor target metadata],
+        "properties" => {
+          "action" => {"const" => event.action},
+          "event_id" => {"type" => "string"},
+          "occurred_at" => {"type" => "string", "format" => "date-time"},
+          "actor" => {"type" => "object"},
+          "target" => {"type" => "object"},
+          "metadata" => metadata_schema(event)
+        }
+      }
+    end
+
+    # The schema for the `metadata` object (the definition's fields).
+    #: (Event event) -> Hash[String, untyped]
+    def metadata_schema(event)
+      required_meta = event.fields.select { |_, f| f["required"] }.keys
+      {
+        "type" => "object",
+        "required" => required_meta,
+        "properties" => event.fields.transform_values { |f| field_type(f) }
+      }
+    end
+
+    #: (Hash[String, untyped] f) -> Hash[String, untyped]
+    def field_type(f)
+      return {"type" => "array", "items" => {}} if f["type"] == "array"
+
+      # dup so each occurrence is an independent object (avoids YAML anchors/aliases).
+      TYPE_MAP.fetch(f["type"], {"type" => "string"}).dup
+    end
+  end
+end

data/lib/moku6/event.rb

@@ -0,0 +1,54 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  class Event
+    attr_reader :data #: Hash[String, untyped]
+    attr_reader :source_path #: String
+
+    #: (Hash[String, untyped]? data, source_path: String) -> void
+    def initialize(data, source_path:)
+      @data = data || {}
+      @source_path = source_path
+    end
+
+    #: () -> String?
+    def action = data["action"]
+
+    #: () -> String?
+    def label = data["label"]
+
+    #: () -> String?
+    def description = data["description"]
+
+    #: () -> String?
+    def category = data["category"]
+
+    #: () -> bool
+    def required? = !!data["required"]
+
+    #: () -> untyped
+    def actor = data["actor"]
+
+    #: () -> untyped
+    def target = data["target"]
+
+    #: () -> Hash[String, untyped]
+    def fields = data["fields"] || {}
+
+    #: () -> untyped
+    def privacy = data["privacy"]
+
+    #: () -> untyped
+    def visibility = data["visibility"]
+
+    #: () -> untyped
+    def retention = data["retention"]
+
+    #: () -> Array[untyped]
+    def examples = data["examples"] || []
+
+    #: () -> Hash[String, untyped]
+    def to_h = data
+  end
+end

data/lib/moku6/generate.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Moku6
+  class Generate
+    # subcommand => [generator name, default output path]
+    GENERATORS = {
+      "docs" => [:docs, "generated/docs/audit-events.md"],
+      "schema" => [:json_schema, "generated/schema"],
+      "typescript" => [:typescript, "generated/typescript/audit-events.ts"],
+      "ruby" => [:ruby, "generated/ruby/audit_events.rb"],
+      "bigquery" => [:bigquery, "generated/bigquery/audit_events.sql"],
+      "cloudevents" => [:cloudevents, "generated/cloudevents"],
+      "eventcatalog" => [:eventcatalog, "generated/eventcatalog"],
+      "openapi" => [:openapi, "generated/openapi/audit-events.yaml"],
+      "rails" => [:rails, "generated/rails/audit_events.rb"],
+      "outbox" => [:outbox, "generated/outbox"],
+      "examples" => [:example, "examples/generated"]
+    }.freeze
+
+    ALL = %w[docs schema typescript ruby bigquery examples].freeze
+
+    BANNER = <<~TEXT
+      Usage: moku6 generate SUBCOMMAND [options]
+
+      Subcommands:
+        docs               Generate Markdown documentation
+        schema             Generate runtime JSON Schema
+        typescript         Generate TypeScript types
+        ruby               Generate Ruby constants
+        bigquery           Generate BigQuery DDL
+        cloudevents        Generate CloudEvents JSON Schema
+        eventcatalog       Generate EventCatalog event docs
+        openapi            Generate an OpenAPI 3.1 document
+        rails              Generate a Ruby/Rails emitter SDK
+        outbox             Generate a sample Rails outbox
+        examples           Generate sample events
+        all                Generate all artifacts (#{ALL.join(", ")})
+
+      Options:
+        --out PATH         Output path
+        --catalog DIR      Catalog directory (default: catalog)
+        --config FILE      Config file (default: .moku6.yml)
+    TEXT
+
+    def start(argv)
+      argv = argv.dup
+      sub = argv.shift
+      case sub
+      when nil, "help", "-h", "--help"
+        puts BANNER
+      when "all"
+        options = parse_options(argv, "generate all")
+        ALL.each { |name| run(name, options) }
+      else
+        unless GENERATORS.key?(sub)
+          warn "Unknown generate subcommand: #{sub}"
+          warn BANNER
+          exit 2
+        end
+        options = parse_options(argv, "generate #{sub}")
+        run(sub, options)
+      end
+    end
+
+    private
+
+    def run(sub, options)
+      name, default_out = GENERATORS.fetch(sub)
+      config = Config.load(options)
+      catalog = Loader.new(config.catalog_dir).load
+      out = options[:out] || config.generator_out(name) || default_out
+      Generators.build(name, catalog, config).write(out)
+      puts "Generated: #{out}"
+    rescue Moku6::UsageError => e
+      warn "Error: #{e.message}"
+      exit 2
+    end
+
+    def parse_options(argv, usage)
+      options = {}
+      parser = OptionParser.new
+      parser.banner = "Usage: moku6 #{usage} [options]"
+      parser.on("--out PATH", "Output path") { |v| options[:out] = v }
+      parser.on("--catalog DIR", "Catalog directory (default: catalog)") { |v| options[:catalog] = v }
+      parser.on("--config FILE", "Config file (default: .moku6.yml)") { |v| options[:config] = v }
+      parser.parse(argv)
+      options
+    rescue OptionParser::ParseError => e
+      warn "Error: #{e.message}"
+      exit 2
+    end
+  end
+end

data/lib/moku6/generators/base_generator.rb

@@ -0,0 +1,31 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Moku6
+  module Generators
+    class BaseGenerator
+      AUTOGEN_NOTE = "AUTO-GENERATED by moku6. DO NOT EDIT." #: String
+
+      # @rbs @catalog: Catalog
+      # @rbs @config: Config
+
+      #: (Catalog catalog, Config config) -> void
+      def initialize(catalog, config)
+        @catalog = catalog
+        @config = config
+      end
+
+      #: () -> String
+      def render = raise NotImplementedError
+
+      #: (String path) -> String
+      def write(path)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, render)
+        path
+      end
+    end
+  end
+end