whodunit-chronicles 0.3.0 → 0.4.0

data/CODE_OF_CONDUCT.md

@@ -1,132 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
-identity and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment for our
-community include:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
-  and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
-  community
-
-Examples of unacceptable behavior include:
-
-* The use of sexualized language or imagery, and sexual attention or advances of
-  any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
-  without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-Examples of representing our community include using an official email address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-[INSERT CONTACT METHOD].
-All complaints will be reviewed and investigated promptly and fairly.
-
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
-
-## Enforcement Guidelines
-
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
-
-### 1. Correction
-
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
-
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
-
-### 2. Warning
-
-**Community Impact**: A violation through a single incident or series of
-actions.
-
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or permanent
-ban.
-
-### 3. Temporary Ban
-
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
-
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
-Violating these terms may lead to a permanent ban.
-
-### 4. Permanent Ban
-
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
-
-**Consequence**: A permanent ban from any sort of public interaction within the
-community.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.1, available at
-[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
-
-Community Impact Guidelines were inspired by
-[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
-
-For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
-[https://www.contributor-covenant.org/translations][translations].
-
-[homepage]: https://www.contributor-covenant.org
-[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
-[Mozilla CoC]: https://github.com/mozilla/diversity
-[FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations

data/CONTRIBUTING.md

@@ -1,186 +0,0 @@
-# Contributing to Whodunit Chronicles
-
-Thank you for your interest in contributing! This document walks you through getting a working development environment set up, running the test suite, and submitting a pull request.
-
----
-
-## Table of Contents
-
-1. [Prerequisites](#prerequisites)
-2. [Setting Up Your Environment](#setting-up-your-environment)
-3. [Database Setup](#database-setup)
-4. [Running the Tests](#running-the-tests)
-5. [Code Style](#code-style)
-6. [Opening a Pull Request](#opening-a-pull-request)
-7. [Contributing Custom Processors](#contributing-custom-processors)
-
----
-
-## Prerequisites
-
-| Tool | Minimum Version | Notes |
-|------|----------------|-------|
-| Ruby | 3.1.0 | `rbenv` or `asdf` recommended |
-| Docker | 24+ | For running test databases |
-| Docker Compose | v2 plugin | Bundled with Docker Desktop |
-| Git | Any recent | |
-
----
-
-## Setting Up Your Environment
-
-```bash
-git clone https://github.com/kanutocd/whodunit-chronicles.git
-cd whodunit-chronicles
-
-# Install dependencies
-bundle install
-
-# Verify the console works
-bundle exec bin/console
-```
-
----
-
-## Database Setup
-
-Chronicles streams directly from PostgreSQL logical replication and MySQL/MariaDB binary logs. The test suite needs real database processes — no SQLite or in-memory substitute.
-
-**Start all test databases with Docker Compose:**
-
-```bash
-docker compose up -d
-```
-
-This starts:
-
-| Service | Port | Purpose |
-|---------|------|---------|
-| PostgreSQL 16 (wal_level=logical) | 5432 | Source DB for pg tests |
-| PostgreSQL 16 (audit store) | 5433 | Audit DB for pg tests |
-| MySQL 8.0 (binlog ROW format) | 3306 | Source DB for MySQL tests |
-| MySQL 8.0 (audit store) | 3307 | Audit DB for MySQL tests |
-| MariaDB 11 (binlog ROW format) | 3308 | Source DB for MariaDB tests |
-
-Wait for all services to be healthy before running tests:
-
-```bash
-docker compose ps   # all should show "(healthy)"
-```
-
-### PostgreSQL — enabling logical replication
-
-The Docker image is pre-configured (`wal_level=logical`). If you're using a system Postgres instead, add to `postgresql.conf`:
-
-```
-wal_level = logical
-max_replication_slots = 10
-max_wal_senders = 10
-```
-
-Then restart Postgres and grant the replication role to your user:
-
-```sql
-ALTER ROLE your_user WITH REPLICATION;
-```
-
-### MySQL — enabling binary logging
-
-The Docker image launches with `--binlog-format=ROW --binlog-row-image=FULL`. If using a system MySQL, add to `my.cnf`:
-
-```ini
-[mysqld]
-server-id       = 1
-log-bin         = mysql-bin
-binlog-format   = ROW
-binlog-row-image = FULL
-```
-
----
-
-## Running the Tests
-
-```bash
-# Full suite
-bundle exec rake test
-
-# Single file
-bundle exec ruby test/whodunit/chronicles/composite_processor_test.rb
-
-# With coverage report
-bundle exec rake test
-open coverage/index.html
-
-# Code style
-bundle exec rubocop
-
-# Security scan
-bundle exec bundler-audit check --update
-bundle exec brakeman
-```
-
-### Environment variables for test databases
-
-The test suite reads these environment variables (defaults match the Docker Compose setup):
-
-| Variable | Default |
-|----------|---------|
-| `CHRONICLES_PG_URL` | `postgresql://chronicles:chronicles@localhost/chronicles_test` |
-| `CHRONICLES_PG_AUDIT_URL` | `postgresql://chronicles:chronicles@localhost:5433/chronicles_audit_test` |
-| `CHRONICLES_MYSQL_URL` | `mysql://chronicles:chronicles@localhost:3306/chronicles_test` |
-| `CHRONICLES_MYSQL_AUDIT_URL` | `mysql://chronicles:chronicles@localhost:3307/chronicles_audit_test` |
-
----
-
-## Code Style
-
-- All files must have `# frozen_string_literal: true`
-- Public methods require YARD documentation
-- Follow the existing RuboCop configuration (`.rubocop.yml`)
-- Tests live in `test/` and use Minitest
-
----
-
-## Opening a Pull Request
-
-1. Fork the repository and create a feature branch:
-   ```bash
-   git checkout -b feature/my-improvement
-   ```
-
-2. Make your changes with tests. Coverage should not drop below 90%.
-
-3. Run the full quality check before pushing:
-   ```bash
-   bundle exec rake test
-   bundle exec rubocop
-   bundle exec bundler-audit check --update
-   ```
-
-4. Push and open a PR with:
-   - A clear description of what changed and why
-   - Any migration steps if you changed configuration
-   - A note on which databases you tested against
-
----
-
-## Contributing Custom Processors
-
-The best contributions are custom processors for real-world domains. Here are domains we'd love to see:
-
-- **E-commerce** — order tracking, inventory changes, cart events
-- **Financial services** — transaction monitoring, compliance audit trails
-- **Healthcare** — patient record changes, HIPAA-relevant audit events
-- **SaaS** — feature flag changes, subscription events, seat management
-- **Education** — student progress, grade changes, enrollment events
-
-A good processor contribution includes:
-
-1. The processor class in `lib/whodunit/chronicles/processors/`
-2. Tests in `test/whodunit/chronicles/processors/`
-3. A usage example in `examples/`
-4. An entry in `CHANGELOG.md`
-
----
-
-Questions? Open an issue or start a discussion on GitHub.

data/Rakefile

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-require 'bundler/gem_tasks'
-require 'rake/testtask'
-require 'rubocop/rake_task'
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'test'
-  t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb']
-end
-
-RuboCop::RakeTask.new
-
-desc 'Run all checks (rubocop, tests)'
-task check: %i[rubocop test]
-
-task default: :check

data/docker/mysql/init.sql

@@ -1,33 +0,0 @@
--- docker/mysql/init.sql
--- Run once when the MySQL/MariaDB container is first created.
-
-USE chronicles_test;
-
-CREATE TABLE IF NOT EXISTS users (
-  id         INT AUTO_INCREMENT PRIMARY KEY,
-  name       VARCHAR(255) NOT NULL,
-  email      VARCHAR(255) NOT NULL UNIQUE,
-  creator_id INT          DEFAULT NULL,
-  updater_id INT          DEFAULT NULL,
-  deleter_id INT          DEFAULT NULL,
-  created_at DATETIME(6)  NOT NULL DEFAULT NOW(6),
-  updated_at DATETIME(6)  NOT NULL DEFAULT NOW(6) ON UPDATE NOW(6)
-);
-
-CREATE TABLE IF NOT EXISTS posts (
-  id         INT AUTO_INCREMENT PRIMARY KEY,
-  user_id    INT          NOT NULL,
-  title      VARCHAR(500) NOT NULL,
-  body       TEXT,
-  status     VARCHAR(50)  DEFAULT 'draft',
-  creator_id INT          DEFAULT NULL,
-  updater_id INT          DEFAULT NULL,
-  deleter_id INT          DEFAULT NULL,
-  created_at DATETIME(6)  NOT NULL DEFAULT NOW(6),
-  updated_at DATETIME(6)  NOT NULL DEFAULT NOW(6) ON UPDATE NOW(6),
-  FOREIGN KEY (user_id) REFERENCES users (id)
-);
-
--- Grant replication privileges to the chronicles user
-GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'chronicles'@'%';
-FLUSH PRIVILEGES;

data/docker/postgres/init.sql

@@ -1,40 +0,0 @@
--- docker/postgres/init.sql
--- Run once when the container is first created.
--- Sets up the replication role and test tables used by the test suite.
-
--- Allow the chronicles user to create replication slots and use logical replication
-ALTER ROLE chronicles WITH REPLICATION;
-
--- Grant superuser for test convenience (never do this in production)
--- Remove this line and grant only necessary permissions for a tighter setup.
-ALTER ROLE chronicles WITH SUPERUSER;
-
--- Create the test tables Chronicles will stream from
-\c chronicles_test
-
-CREATE TABLE IF NOT EXISTS users (
-  id           SERIAL PRIMARY KEY,
-  name         VARCHAR(255) NOT NULL,
-  email        VARCHAR(255) NOT NULL UNIQUE,
-  creator_id   INTEGER,
-  updater_id   INTEGER,
-  deleter_id   INTEGER,
-  created_at   TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-  updated_at   TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-);
-
-CREATE TABLE IF NOT EXISTS posts (
-  id           SERIAL PRIMARY KEY,
-  user_id      INTEGER NOT NULL REFERENCES users(id),
-  title        VARCHAR(500) NOT NULL,
-  body         TEXT,
-  status       VARCHAR(50) DEFAULT 'draft',
-  creator_id   INTEGER,
-  updater_id   INTEGER,
-  deleter_id   INTEGER,
-  created_at   TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-  updated_at   TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-);
-
--- Publication used by the Chronicles PostgreSQL adapter
-CREATE PUBLICATION chronicles_test_pub FOR TABLE users, posts;

data/docker-compose.yml

@@ -1,138 +0,0 @@
-name: whodunit-chronicles
-
-# ──────────────────────────────────────────────────────────────────────────────
-# Local development + CI test databases
-#
-# Quickstart:
-#   docker compose up -d
-#   bundle exec rake test
-#
-# Stop + wipe volumes:
-#   docker compose down -v
-# ──────────────────────────────────────────────────────────────────────────────
-
-services:
-  # ── PostgreSQL (logical replication enabled) ─────────────────────────────
-  postgres:
-    image: postgres:16-alpine
-    environment:
-      POSTGRES_USER:     chronicles
-      POSTGRES_PASSWORD: chronicles
-      POSTGRES_DB:       chronicles_test
-    ports:
-      - "${POSTGRES_PORT:-5432}:5432"
-    command: >
-      postgres
-        -c wal_level=logical
-        -c max_replication_slots=10
-        -c max_wal_senders=10
-        -c log_replication_commands=on
-    volumes:
-      - pg_data:/var/lib/postgresql/data
-      - ./docker/postgres/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U chronicles -d chronicles_test"]
-      interval: 5s
-      timeout: 5s
-      retries: 10
-      start_period: 10s
-
-  # Separate audit database (mirrors production split)
-  postgres_audit:
-    image: postgres:16-alpine
-    environment:
-      POSTGRES_USER:     chronicles
-      POSTGRES_PASSWORD: chronicles
-      POSTGRES_DB:       chronicles_audit_test
-    ports:
-      - "${POSTGRES_AUDIT_PORT:-5433}:5432"
-    volumes:
-      - pg_audit_data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U chronicles -d chronicles_audit_test"]
-      interval: 5s
-      timeout: 5s
-      retries: 10
-      start_period: 10s
-
-  # ── MySQL (binary logging enabled) ───────────────────────────────────────
-  mysql:
-    image: mysql:8.0
-    environment:
-      MYSQL_ROOT_PASSWORD: chronicles_root
-      MYSQL_USER:          chronicles
-      MYSQL_PASSWORD:      chronicles
-      MYSQL_DATABASE:      chronicles_test
-    ports:
-      - "3306:3306"
-    command: >
-      mysqld
-        --server-id=1
-        --log-bin=mysql-bin
-        --binlog-format=ROW
-        --binlog-row-image=FULL
-        --expire-logs-days=1
-        --gtid-mode=ON
-        --enforce-gtid-consistency=ON
-    volumes:
-      - mysql_data:/var/lib/mysql
-      - ./docker/mysql/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
-    healthcheck:
-      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "chronicles", "-pchronicles"]
-      interval: 5s
-      timeout: 5s
-      retries: 15
-      start_period: 30s
-
-  # Separate audit database for MySQL
-  mysql_audit:
-    image: mysql:8.0
-    environment:
-      MYSQL_ROOT_PASSWORD: chronicles_root
-      MYSQL_USER:          chronicles
-      MYSQL_PASSWORD:      chronicles
-      MYSQL_DATABASE:      chronicles_audit_test
-    ports:
-      - "3307:3306"
-    volumes:
-      - mysql_audit_data:/var/lib/mysql
-    healthcheck:
-      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "chronicles", "-pchronicles"]
-      interval: 5s
-      timeout: 5s
-      retries: 15
-      start_period: 30s
-
-  # ── MariaDB (binary logging enabled) ─────────────────────────────────────
-  mariadb:
-    image: mariadb:11
-    environment:
-      MARIADB_ROOT_PASSWORD: chronicles_root
-      MARIADB_USER:          chronicles
-      MARIADB_PASSWORD:      chronicles
-      MARIADB_DATABASE:      chronicles_test
-    ports:
-      - "3308:3306"
-    command: >
-      mariadbd
-        --server-id=2
-        --log-bin=mariadb-bin
-        --binlog-format=ROW
-        --binlog-row-image=FULL
-        --expire-logs-days=1
-    volumes:
-      - mariadb_data:/var/lib/mysql
-      - ./docker/mysql/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
-    healthcheck:
-      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
-      interval: 5s
-      timeout: 5s
-      retries: 15
-      start_period: 30s
-
-volumes:
-  pg_data:
-  pg_audit_data:
-  mysql_data:
-  mysql_audit_data:
-  mariadb_data:

data/lib/whodunit/chronicles/adapter_loader.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-module Whodunit
-  module Chronicles
-    # Lazily loads the correct database adapter gem at runtime.
-    #
-    # This avoids forcing all users to install both `pg` and `trilogy`
-    # regardless of which database they actually use.
-    #
-    # @example
-    #   adapter = AdapterLoader.load(:postgresql)
-    #   adapter = AdapterLoader.load(:mysql)
-    #   adapter = AdapterLoader.load(:mariadb)
-    module AdapterLoader
-      # Map of adapter type symbols to their required gem and class path.
-      ADAPTER_REGISTRY = {
-        postgresql: {
-          gem: 'pg',
-          require: 'whodunit/chronicles/adapters/postgresql',
-          class: 'Whodunit::Chronicles::Adapters::PostgreSQL',
-          hint: "Add `gem 'pg', '~> 1.5'` to your Gemfile.",
-        },
-        mysql: {
-          gem: 'trilogy',
-          require: 'whodunit/chronicles/adapters/mysql',
-          class: 'Whodunit::Chronicles::Adapters::MySQL',
-          hint: "Add `gem 'trilogy', '~> 2.9'` to your Gemfile.",
-        },
-        mariadb: {
-          gem: 'trilogy',
-          require: 'whodunit/chronicles/adapters/mysql',
-          class: 'Whodunit::Chronicles::Adapters::MySQL',
-          hint: "Add `gem 'trilogy', '~> 2.9'` to your Gemfile.",
-        },
-      }.freeze
-
-      # Load and instantiate an adapter by type.
-      #
-      # @param type [Symbol] one of :postgresql, :mysql, :mariadb
-      # @param options [Hash] options forwarded to the adapter constructor
-      # @return [Adapters::Base] the instantiated adapter
-      # @raise [Whodunit::Chronicles::ConfigurationError] for unknown adapter types
-      # @raise [Whodunit::Chronicles::AdapterLoadError] when the required gem is missing
-      def self.load(type, **)
-        config = ADAPTER_REGISTRY[type.to_sym]
-
-        unless config
-          known = ADAPTER_REGISTRY.keys.map(&:inspect).join(', ')
-          raise ConfigurationError,
-            "Unknown adapter type #{type.inspect}. Known adapters: #{known}"
-        end
-
-        load_gem!(config)
-        require config[:require]
-        Object.const_get(config[:class]).new(**)
-      rescue LoadError => e
-        raise AdapterLoadError,
-          "Could not load the '#{config[:gem]}' gem required for the " \
-          "#{type} adapter.\n#{config[:hint]}\nOriginal error: #{e.message}"
-      end
-
-      # @api private
-      def self.load_gem!(config)
-        require config[:gem]
-      end
-      private_class_method :load_gem!
-    end
-  end
-end