moku6 0.1.0

data/lib/moku6/linter.rb

@@ -0,0 +1,60 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  class Linter
+    EVENT_RULES = [
+      Rules::SchemaRule,
+      Rules::ActionNamingRule,
+      Rules::LabelDescriptionRule,
+      Rules::PrivacyMaskingRule,
+      Rules::VisibilityRule,
+      Rules::RetentionRule,
+      Rules::ExampleConsistencyRule,
+      Rules::PiiFieldNameHeuristicRule
+    ].freeze #: Array[singleton(Rules::BaseRule)]
+
+    CATALOG_RULES = [
+      Rules::UniquenessRule
+    ].freeze #: Array[singleton(Rules::BaseRule)]
+
+    # @rbs @catalog: Catalog
+    # @rbs @config: Config
+
+    class << self
+      # Extension points for consumers to register custom rules (design section 13).
+
+      #: (singleton(Rules::BaseRule) klass) -> Array[singleton(Rules::BaseRule)]
+      def register_event_rule(klass) = custom_event_rules << klass
+
+      #: (singleton(Rules::BaseRule) klass) -> Array[singleton(Rules::BaseRule)]
+      def register_catalog_rule(klass) = custom_catalog_rules << klass
+
+      #: () -> Array[singleton(Rules::BaseRule)]
+      def custom_event_rules = @custom_event_rules ||= []
+
+      #: () -> Array[singleton(Rules::BaseRule)]
+      def custom_catalog_rules = @custom_catalog_rules ||= []
+    end
+
+    #: (Catalog catalog, Config config) -> void
+    def initialize(catalog, config)
+      @catalog = catalog
+      @config = config
+    end
+
+    #: () -> Result
+    def run
+      offenses = []
+      (CATALOG_RULES + self.class.custom_catalog_rules).each do |rule_class|
+        offenses.concat(rule_class.new(@config).check_catalog(@catalog)) # steep:ignore NoMethod
+      end
+      @catalog.events.each do |event|
+        (EVENT_RULES + self.class.custom_event_rules).each do |rule_class|
+          offenses.concat(rule_class.new(@config).check(event))
+        end
+      end
+      Result.new(offenses)
+    end
+  end
+end

data/lib/moku6/loader.rb

@@ -0,0 +1,31 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  class Loader
+    PERMITTED_CLASSES = [Symbol].freeze #: Array[Class]
+
+    # @rbs @catalog_dir: String
+
+    #: (String catalog_dir) -> void
+    def initialize(catalog_dir) = @catalog_dir = catalog_dir
+
+    #: () -> Catalog
+    def load
+      unless Dir.exist?(@catalog_dir)
+        raise UsageError, "catalog directory not found: #{@catalog_dir}"
+      end
+
+      paths = Dir.glob(File.join(@catalog_dir, "**", "*.{yml,yaml}")).sort
+      events = paths.map do |path|
+        data = begin
+          YAML.safe_load_file(path, permitted_classes: PERMITTED_CLASSES)
+        rescue Psych::SyntaxError => e
+          raise UsageError, "failed to parse YAML (#{path}): #{e.message}"
+        end
+        Event.new(data, source_path: path)
+      end
+      Catalog.new(events)
+    end
+  end
+end

data/lib/moku6/offense.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Moku6
+  # keyword_init is required on Ruby 3.1 (required_ruby_version >= 3.1.0).
+  Offense = Struct.new(
+    :rule,      # String  rule id
+    :severity,  # Symbol  :error | :warning
+    :action,    # String  target action (nil if unknown)
+    :file,      # String  source file path
+    :message,   # String  human-readable message
+    keyword_init: true # standard:disable Style/RedundantStructKeywordInit
+  )
+end

data/lib/moku6/reporter.rb

@@ -0,0 +1,71 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Reporter
+    #: (String? format) -> untyped
+    def self.for(format)
+      case format
+      when "json" then Json
+      when "markdown" then Markdown
+      else Text
+      end
+    end
+
+    module Text
+      #: (Result result) -> void
+      def self.report(result)
+        result.offenses.each do |o|
+          tag = (o.severity == :error) ? "ERROR" : "WARN "
+          puts "#{tag}  #{o.file}  #{o.action}  #{o.message}"
+        end
+        e = result.errors.size
+        w = result.warnings.size
+        puts "\n#{e} error#{"s" if e != 1}, #{w} warning#{"s" if w != 1}"
+      end
+    end
+
+    module Json
+      #: (Result result) -> void
+      def self.report(result)
+        puts JSON.pretty_generate(
+          summary: {errors: result.errors.size, warnings: result.warnings.size},
+          offenses: result.offenses.map(&:to_h)
+        )
+      end
+    end
+
+    # Review-friendly Markdown report (e.g. for posting as a PR comment).
+    module Markdown
+      #: (Result result) -> void
+      def self.report(result) = puts render(result)
+
+      #: (Result result) -> String
+      def self.render(result)
+        errors = result.errors
+        warnings = result.warnings
+        out = ["# Audit catalog report", ""]
+        if result.empty?
+          out << "No issues detected. ✅"
+          return out.join("\n") + "\n"
+        end
+        out << "**#{errors.size} error#{"s" if errors.size != 1}, " \
+               "#{warnings.size} warning#{"s" if warnings.size != 1}** detected."
+        out.concat(section("❌ Errors", errors))
+        out.concat(section("⚠️ Warnings", warnings))
+        out.join("\n") + "\n"
+      end
+
+      #: (String title, Array[Offense] offenses) -> Array[String]
+      def self.section(title, offenses)
+        return [] if offenses.empty?
+
+        lines = ["", "## #{title}", ""]
+        offenses.each do |o|
+          lines << "- `#{o.action}` — #{o.message} (`#{o.file}`)"
+        end
+        lines
+      end
+    end
+  end
+end

data/lib/moku6/result.rb

@@ -0,0 +1,23 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  class Result
+    attr_reader :offenses #: Array[Offense]
+
+    #: (Array[Offense] offenses) -> void
+    def initialize(offenses) = @offenses = offenses
+
+    #: () -> Array[Offense]
+    def errors = offenses.select { |o| o.severity == :error }
+
+    #: () -> Array[Offense]
+    def warnings = offenses.select { |o| o.severity == :warning }
+
+    #: () -> bool
+    def errors? = errors.any?
+
+    #: () -> bool
+    def empty? = offenses.empty?
+  end
+end

data/lib/moku6/rules/action_naming_rule.rb

@@ -0,0 +1,18 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Rules
+    class ActionNamingRule < BaseRule
+      #: (Event event) -> Array[Offense]
+      def check(event)
+        pattern = Regexp.new(@config.naming_pattern.to_s)
+        return [] if event.action.to_s.match?(pattern)
+
+        [offense(event, :error,
+          "action '#{event.action}' violates the naming convention " \
+          "(expected: namespace.verb form, lowercase, dot-separated).")]
+      end
+    end
+  end
+end

data/lib/moku6/rules/base_rule.rb

@@ -0,0 +1,37 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Rules
+    class BaseRule
+      # @rbs @config: Config
+
+      #: (Config config) -> void
+      def initialize(config) = @config = config
+
+      #: (Event event) -> Array[Offense]
+      def check(_event) = raise NotImplementedError
+
+      private
+
+      #: (Event event, Symbol severity, String message, ?rule: String) -> Offense
+      def offense(event, severity, message, rule: rule_id)
+        Offense.new(
+          rule: rule,
+          severity: severity,
+          action: event.action,
+          file: event.source_path,
+          message: message
+        )
+      end
+
+      #: () -> String
+      def rule_id
+        self.class.name.split("::").last
+          .gsub(/Rule\z/, "")
+          .gsub(/([a-z])([A-Z])/, '\1_\2')
+          .downcase
+      end
+    end
+  end
+end

data/lib/moku6/rules/example_consistency_rule.rb

@@ -0,0 +1,53 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "senko"
+
+module Moku6
+  module Rules
+    class ExampleConsistencyRule < BaseRule
+      #: (Event event) -> Array[Offense]
+      def check(event)
+        examples = collect_examples(event)
+        return [] if examples.empty?
+
+        schemer = Senko.compile(EnvelopeSchema.for(event))
+        examples.each_with_index.flat_map do |example, idx|
+          result = schemer.validate(example)
+          next [] if result.valid?
+
+          result.errors.map do |err|
+            h = err.to_h
+            location = h["instanceLocation"].to_s
+            pointer = location.empty? ? "(root)" : location
+            keyword = h["keywordLocation"].to_s.split("/").last
+            offense(event, :error,
+              "examples[#{idx}] does not match the definition #{pointer}: #{keyword}",
+              rule: "example_consistency")
+          end
+        end
+      end
+
+      private
+
+      #: (Event event) -> Array[untyped]
+      def collect_examples(event)
+        inline = event.examples
+        return inline if inline.is_a?(Array) && !inline.empty?
+
+        path = external_path(event)
+        return [] unless path && File.exist?(path)
+
+        data = JSON.parse(File.read(path))
+        data.is_a?(Array) ? data : [data]
+      end
+
+      #: (Event event) -> String?
+      def external_path(event)
+        return nil unless event.action
+
+        File.join(@config.examples_dir, "#{event.action}.json")
+      end
+    end
+  end
+end

data/lib/moku6/rules/label_description_rule.rb

@@ -0,0 +1,21 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Rules
+    class LabelDescriptionRule < BaseRule
+      #: (Event event) -> Array[Offense]
+      def check(event)
+        offenses = []
+        offenses << offense(event, :error, "label is missing.") if blank?(event.label)
+        offenses << offense(event, :error, "description is missing.") if blank?(event.description)
+        offenses
+      end
+
+      private
+
+      #: (untyped value) -> bool
+      def blank?(value) = value.nil? || value.to_s.strip.empty?
+    end
+  end
+end

data/lib/moku6/rules/pii_field_name_heuristic_rule.rb

@@ -0,0 +1,45 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Rules
+    # Warns when a field name looks like PII (email/phone/ssn, ...) but is not
+    # covered by privacy.masked_fields (design section 10.1, v0.2).
+    class PiiFieldNameHeuristicRule < BaseRule
+      PII_PATTERN = /
+        email | phone | tel | mobile | fax |
+        ssn | mynumber | my_number | passport | license |
+        credit_?card | card_?number | cvv |
+        address | postal | zip |
+        birth | dob | password | secret
+      /xi #: Regexp
+
+      #: (Event event) -> Array[Offense]
+      def check(event)
+        return [] unless @config.warn_pii_field_names?
+
+        masked = masked_field_tokens(event)
+        event.fields.filter_map do |name, _f|
+          next unless name.to_s.match?(PII_PATTERN)
+          next if masked.include?(name.to_s)
+
+          offense(event, :warning,
+            "field '#{name}' looks like personal data but is not listed in privacy.masked_fields.",
+            rule: "pii_field_name_heuristic")
+        end
+      end
+
+      private
+
+      # Tokens that count a field as masked: the full masked path and each of its
+      # dot-separated segments (e.g. "before.email" covers "email").
+      #: (Event event) -> Array[String]
+      def masked_field_tokens(event)
+        list = (event.privacy.is_a?(Hash) ? event.privacy["masked_fields"] : nil) #: Array[untyped]?
+        return [] unless list.is_a?(Array)
+
+        list.flat_map { |path| [path.to_s] + path.to_s.split(".") }
+      end
+    end
+  end
+end

data/lib/moku6/rules/privacy_masking_rule.rb

@@ -0,0 +1,21 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Rules
+    class PrivacyMaskingRule < BaseRule
+      #: (Event event) -> Array[Offense]
+      def check(event)
+        privacy = event.privacy
+        return [] unless privacy && privacy["contains_personal_data"]
+
+        masked = privacy["masked_fields"]
+        return [] if masked.is_a?(Array) && masked.any?
+
+        [offense(event, :error,
+          "contains personal data (contains_personal_data: true) but masked_fields is not set. " \
+          "List the fields to mask under privacy.masked_fields.")]
+      end
+    end
+  end
+end

data/lib/moku6/rules/retention_rule.rb

@@ -0,0 +1,19 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Rules
+    class RetentionRule < BaseRule
+      #: (Event event) -> Array[Offense]
+      def check(event)
+        retention = event.retention
+        years = retention.is_a?(Hash) ? retention["years"] : nil
+        return [] if years.is_a?(Integer) && years >= 1
+
+        [offense(event, :error,
+          "retention.years must be a positive integer.",
+          rule: "retention_present")]
+      end
+    end
+  end
+end

data/lib/moku6/rules/schema_rule.rb

@@ -0,0 +1,31 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "senko"
+
+module Moku6
+  module Rules
+    class SchemaRule < BaseRule
+      SCHEMA_PATH = File.expand_path("../../../schemas/audit-event.schema.json", __dir__.to_s) #: String
+
+      #: () -> untyped
+      def self.schemer
+        @schemer ||= Senko.compile(JSON.parse(File.read(SCHEMA_PATH)))
+      end
+
+      #: (Event event) -> Array[Offense]
+      def check(event)
+        result = self.class.schemer.validate(event.to_h)
+        return [] if result.valid?
+
+        result.errors.map do |err|
+          h = err.to_h
+          location = h["instanceLocation"].to_s
+          pointer = location.empty? ? "(root)" : location
+          keyword = h["keywordLocation"].to_s.split("/").last
+          offense(event, :error, "schema violation #{pointer}: #{keyword} (#{h["error"] || "invalid"})")
+        end
+      end
+    end
+  end
+end

data/lib/moku6/rules/uniqueness_rule.rb

@@ -0,0 +1,22 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Rules
+    class UniquenessRule < BaseRule
+      # catalog-level rule
+      #: (Catalog catalog) -> Array[Offense]
+      def check_catalog(catalog)
+        dupes = catalog.actions.compact.tally.select { |_, n| n > 1 }.keys
+        dupes.map do |action|
+          files = catalog.events.select { |e| e.action == action }.map(&:source_path)
+          Offense.new(
+            rule: "uniqueness", severity: :error, action: action,
+            file: files.join(", "),
+            message: "action '#{action}' is duplicated."
+          )
+        end
+      end
+    end
+  end
+end

data/lib/moku6/rules/visibility_rule.rb

@@ -0,0 +1,27 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  module Rules
+    class VisibilityRule < BaseRule
+      #: (Event event) -> Array[Offense]
+      def check(event)
+        visibility = event.visibility
+        unless visibility.is_a?(Hash) &&
+            visibility.key?("customer_visible") && visibility.key?("internal_only")
+          return [offense(event, :error,
+            "customer_visible / internal_only must be set explicitly.",
+            rule: "visibility_explicit")]
+        end
+
+        if visibility["customer_visible"] && visibility["internal_only"]
+          return [offense(event, :warning,
+            "customer_visible and internal_only are contradictory.",
+            rule: "visibility_consistency")]
+        end
+
+        []
+      end
+    end
+  end
+end

data/lib/moku6/version.rb

@@ -0,0 +1,6 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Moku6
+  VERSION = "0.1.0" #: String
+end

data/lib/moku6.rb

@@ -0,0 +1,55 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+require "yaml"
+require "json"
+
+require_relative "moku6/version"
+
+module Moku6
+  class Error < StandardError; end
+
+  class UsageError < Error; end # mapped to exit code 2
+end
+
+require_relative "moku6/config"
+require_relative "moku6/event"
+require_relative "moku6/catalog"
+require_relative "moku6/loader"
+require_relative "moku6/offense"
+require_relative "moku6/result"
+require_relative "moku6/reporter"
+require_relative "moku6/envelope_schema"
+
+# rules
+require_relative "moku6/rules/base_rule"
+require_relative "moku6/rules/schema_rule"
+require_relative "moku6/rules/action_naming_rule"
+require_relative "moku6/rules/label_description_rule"
+require_relative "moku6/rules/uniqueness_rule"
+require_relative "moku6/rules/privacy_masking_rule"
+require_relative "moku6/rules/visibility_rule"
+require_relative "moku6/rules/retention_rule"
+require_relative "moku6/rules/example_consistency_rule"
+require_relative "moku6/rules/pii_field_name_heuristic_rule"
+require_relative "moku6/linter"
+require_relative "moku6/differ"
+
+# generators
+require_relative "moku6/generators/base_generator"
+require_relative "moku6/generators/docs_generator"
+require_relative "moku6/generators/json_schema_generator"
+require_relative "moku6/generators/typescript_generator"
+require_relative "moku6/generators/ruby_generator"
+require_relative "moku6/generators/bigquery_generator"
+require_relative "moku6/generators/cloud_events_generator"
+require_relative "moku6/generators/event_catalog_generator"
+require_relative "moku6/generators/open_api_generator"
+require_relative "moku6/generators/rails_generator"
+require_relative "moku6/generators/outbox_generator"
+require_relative "moku6/generators/example_generator"
+require_relative "moku6/generators"
+
+require_relative "moku6/initializer"
+require_relative "moku6/generate"
+require_relative "moku6/cli"

data/schemas/audit-event.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://moku6/schemas/audit-event.schema.json",
+  "title": "Audit Event Definition",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["action", "label", "description", "category", "actor", "target", "privacy", "visibility", "retention"],
+  "properties": {
+    "action": {
+      "type": "string",
+      "pattern": "^[a-z0-9_]+(\\.[a-z0-9_]+)+$"
+    },
+    "label": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "category": { "type": "string", "minLength": 1 },
+    "required": { "type": "boolean" },
+    "actor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["required"],
+      "properties": {
+        "required": { "type": "boolean" },
+        "type": { "type": "string" }
+      }
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "required"],
+      "properties": {
+        "type": { "type": "string" },
+        "required": { "type": "boolean" }
+      }
+    },
+    "fields": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["type", "required"],
+        "properties": {
+          "type": {
+            "enum": ["string", "integer", "number", "boolean", "array", "object", "timestamp"]
+          },
+          "required": { "type": "boolean" },
+          "description": { "type": "string" },
+          "items": { "type": "object" }
+        }
+      }
+    },
+    "privacy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["contains_personal_data"],
+      "properties": {
+        "contains_personal_data": { "type": "boolean" },
+        "masked_fields": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "visibility": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["customer_visible", "internal_only"],
+      "properties": {
+        "customer_visible": { "type": "boolean" },
+        "internal_only": { "type": "boolean" }
+      }
+    },
+    "retention": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["years"],
+      "properties": {
+        "years": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "examples": {
+      "type": "array",
+      "items": { "type": "object" }
+    }
+  }
+}

data/sig/generated/moku6/catalog.rbs

@@ -0,0 +1,22 @@
+# Generated from lib/moku6/catalog.rb with RBS::Inline
+
+module Moku6
+  class Catalog
+    attr_reader events: Array[Event]
+
+    # : (Array[Event] events) -> void
+    def initialize: (Array[Event] events) -> void
+
+    # : () -> Array[String?]
+    def actions: () -> Array[String?]
+
+    # : () -> Array[Event]
+    def sorted: () -> Array[Event]
+
+    # : (String? action) -> Event?
+    def find: (String? action) -> Event?
+
+    # : () -> bool
+    def empty?: () -> bool
+  end
+end