track_relay 1.0.0

data/lib/track_relay/job_tracking.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module TrackRelay
+  # Job-side tracking helper.
+  #
+  # Host applications include this concern in `ApplicationJob` (or any
+  # job) to expose a `track(name, **params)` instance method that
+  # delegates to {TrackRelay.track}.
+  #
+  # Unlike {ControllerTracking}, this concern is intentionally minimal
+  # — it does NOT auto-populate {Current}. The reason is the Rails
+  # Executor: ActiveJob wraps every `perform` with the Executor, which
+  # calls `ActiveSupport::CurrentAttributes.clear_all` BEFORE the job
+  # runs. So any `Current.user` set in the request that enqueued the
+  # job is gone by the time `perform` runs — even under the inline /
+  # test queue adapter. Auto-populating from constructor args would be
+  # wrong: the args are serialized through the queue, but the in-memory
+  # context (visit, request, etc.) is not.
+  #
+  # Job authors are responsible for restoring whatever context they
+  # care about. The documented pattern is `Current.set(user: u, ...)
+  # { track :foo, ... }`. The block form binds attributes for the
+  # duration of the block, then unwinds — perfect for a single `track`
+  # call inside `perform`.
+  #
+  # @example Documented usage
+  #   class WelcomeEmailJob < ApplicationJob
+  #     include TrackRelay::JobTracking
+  #
+  #     def perform(user)
+  #       TrackRelay::Current.set(user: user, visitor_token: user.last_visitor_token) do
+  #         track :welcome_email_sent, template: "v3"
+  #       end
+  #     end
+  #   end
+  module JobTracking
+    extend ActiveSupport::Concern
+
+    # Delegate to {TrackRelay.track}. Sugar for in-job call sites.
+    #
+    # @param name [Symbol]
+    # @param params [Hash]
+    # @return [void]
+    def track(name, **params)
+      TrackRelay.track(name, **params)
+    end
+  end
+end

data/lib/track_relay/linter.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "json"
+require "track_relay/validators/ga4_constraints"
+
+module TrackRelay
+  # Audits the JSONL untyped-event sink written by
+  # {Subscribers::Logger} and produces a deduped report grouped by
+  # event name + sorted-param-name signature.
+  #
+  # ## Input contract (locked in Plan 05 / 01-CONTEXT.md)
+  #
+  # The JSONL sink contains one event per line. Each line is JSON with
+  # the canonical shape:
+  #
+  #   {"event":"...", "params":["a","b"], "controller":"...", "action":"...", "timestamp":"..."}
+  #
+  # `params` carries only sorted, stringified parameter NAMES — values
+  # are never written to the sink (privacy contract from
+  # 01-CONTEXT.md). The linter reads the same shape and dedupes only on
+  # `event` + sorted `params`; `controller`, `action`, and `timestamp`
+  # are accepted but ignored for grouping (they are useful breadcrumbs
+  # for the human reading the JSONL directly, not signal for dedup).
+  #
+  # ## Output
+  #
+  # - {#report} → Array of {Report} structs, sorted by total occurrences
+  #   descending. Each Report bundles every distinct param signature
+  #   seen for that event name.
+  # - {#print} → human-readable summary written to an IO.
+  # - {#to_json} → machine-readable JSON with stable keys
+  #   `{event, total, signatures: [{params, count}]}`. Plan 09's
+  #   CHANGELOG references this contract.
+  #
+  # ## Resilience
+  #
+  # - Missing files return an empty report (the JSONL may legitimately
+  #   not exist yet on a fresh app).
+  # - Lines that are not valid JSON are skipped and counted in
+  #   {#malformed_lines}.
+  # - Blank lines are silently skipped (not malformed).
+  class Linter
+    # One report entry per distinct event name.
+    #
+    # @!attribute [rw] event_name
+    #   The event name as it appeared in the JSONL `event` field.
+    # @!attribute [rw] signatures
+    #   Array of {Signature} structs, sorted by `count` descending.
+    # @!attribute [rw] total
+    #   Sum of all signature counts for this event.
+    Report = Struct.new(:event_name, :signatures, :total, keyword_init: true)
+
+    # One signature per distinct sorted-param-name shape under an event.
+    #
+    # @!attribute [rw] params
+    #   Sorted array of parameter NAMES (no values).
+    # @!attribute [rw] count
+    #   How many times this exact signature was seen.
+    Signature = Struct.new(:params, :count, keyword_init: true)
+
+    # @return [Integer] count of lines that failed JSON parsing
+    attr_reader :malformed_lines
+
+    def initialize(jsonl_path)
+      @jsonl_path = jsonl_path
+      @malformed_lines = 0
+    end
+
+    # Build the deduped report.
+    #
+    # @return [Array<Report>] sorted by total occurrences descending
+    def report
+      groups = Hash.new { |h, k| h[k] = Hash.new(0) }
+      read_lines do |entry|
+        event = entry["event"]
+        signature = Array(entry["params"]).sort
+        groups[event][signature] += 1
+      end
+
+      groups.map { |event, signatures|
+        sig_list = signatures.map { |params, count| Signature.new(params: params, count: count) }
+        total = sig_list.sum(&:count)
+        Report.new(
+          event_name: event,
+          signatures: sig_list.sort_by { |s| -s.count },
+          total: total
+        )
+      }.sort_by { |r| -r.total }
+    end
+
+    # Write a human-readable summary to `io`.
+    #
+    # @param io [IO] writer; defaults to `$stdout`
+    # @return [void]
+    def print(io = $stdout)
+      reports = report
+      io.puts "# track_relay untyped event audit"
+      io.puts "# source: #{@jsonl_path}"
+      io.puts "# events: #{reports.size}; total occurrences: #{reports.sum(&:total)}"
+      io.puts ""
+      reports.each do |r|
+        io.puts "event :#{r.event_name}  (#{r.total} total)"
+        r.signatures.each do |sig|
+          io.puts "  - params=[#{sig.params.join(", ")}]  count=#{sig.count}"
+        end
+        io.puts ""
+      end
+      io.puts "# #{@malformed_lines} malformed line(s) skipped" if @malformed_lines.positive?
+    end
+
+    # Emit machine-readable JSON.
+    #
+    # Keys (`event`, `total`, `signatures`, `params`, `count`) are
+    # stable — Plan 09's CHANGELOG references this contract.
+    #
+    # @return [String] JSON
+    def to_json(*)
+      JSON.generate(report.map { |r|
+        {
+          event: r.event_name,
+          total: r.total,
+          signatures: r.signatures.map { |s| {params: s.params, count: s.count} }
+        }
+      })
+    end
+
+    # One row in the GA4 lint report.
+    #
+    # @!attribute [rw] event_name
+    #   The event name as it appeared in the JSONL `event` field.
+    # @!attribute [rw] reason
+    #   Human-readable description of the GA4 rule that was violated.
+    # @!attribute [rw] count
+    #   How many JSONL lines contained this event name (regardless of
+    #   param signature — the GA4 lint groups purely by event name).
+    Ga4Violation = Struct.new(:event_name, :reason, :count, keyword_init: true)
+
+    # Audit each unique event name in the JSONL sink against
+    # {Validators::Ga4Constraints} (REQ-28, Plan 02-04 / Scout §8).
+    #
+    # Only the event-name shape is checked here:
+    #
+    #   - snake_case regex (`/\A[a-z][a-z0-9_]*\z/`)
+    #   - max 40 chars
+    #   - not in `GA4_RESERVED_NAMES`
+    #
+    # Param-name validation is intentionally OUT OF SCOPE for this
+    # method — `params` in the JSONL is a sorted-NAMES-only privacy
+    # snapshot, but param-name shape is a per-line fact (each occurrence
+    # could fail differently) and the linter's grouping model is built
+    # around event names. Use the call-time validation in
+    # {Subscribers::Ga4MeasurementProtocol#deliver} for per-payload
+    # checks; this method is the audit trail for "what event names did
+    # we ship that GA4 will silently drop?".
+    #
+    # @return [Array<Ga4Violation>] sorted by `count` descending. Empty
+    #   when every event name in the JSONL passes.
+    def ga4_violations
+      counts = Hash.new(0)
+      read_lines do |entry|
+        name = entry["event"]
+        next if name.nil? || name.empty?
+        counts[name] += 1
+      end
+
+      counts.map { |name, count|
+        begin
+          Validators::Ga4Constraints.validate_event_name!(name)
+          nil
+        rescue Ga4ConstraintError => e
+          Ga4Violation.new(event_name: name, reason: e.message, count: count)
+        end
+      }.compact.sort_by { |v| -v.count }
+    end
+
+    # Write the GA4 violation report to `io`.
+    #
+    # Returns `true` when there were no violations (rake task should
+    # exit 0), `false` otherwise (rake task exits non-zero).
+    #
+    # @param io [IO] writer; defaults to `$stdout`
+    # @return [Boolean] `true` ⇒ clean, `false` ⇒ violations found
+    def print_ga4(io = $stdout)
+      violations = ga4_violations
+      io.puts "# track_relay GA4 event-name audit"
+      io.puts "# source: #{@jsonl_path}"
+      io.puts "# violations: #{violations.size}"
+      io.puts ""
+
+      if violations.empty?
+        io.puts "# clean — every event name passes GA4 constraints"
+        return true
+      end
+
+      violations.each do |v|
+        io.puts "event :#{v.event_name}  (#{v.count} occurrence#{"s" unless v.count == 1})"
+        io.puts "  reason: #{v.reason}"
+        io.puts ""
+      end
+      false
+    end
+
+    private
+
+    def read_lines
+      return unless File.exist?(@jsonl_path.to_s)
+      File.foreach(@jsonl_path.to_s) do |line|
+        line = line.strip
+        next if line.empty?
+        begin
+          yield JSON.parse(line)
+        rescue JSON::ParserError
+          @malformed_lines += 1
+        end
+      end
+    end
+  end
+end

data/lib/track_relay/manifest.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+require "track_relay/version"
+require "track_relay/catalog"
+
+module TrackRelay
+  # Generate a typed JSON manifest of the loaded catalog for the
+  # `@track_relay/client` JS package (Plan 02-05) to fetch and validate
+  # events client-side. The on-disk artifact is written by either:
+  #
+  #   * `rake track_relay:manifest` (production / CI), or
+  #   * `config.to_prepare` in development (regenerated on every reload),
+  #
+  # both of which delegate to {.write!}. The generated shape is stable
+  # and consumed by the JS client:
+  #
+  #   {
+  #     "version": "<gem version>",
+  #     "generated_at": "<ISO8601 timestamp>",
+  #     "events": {
+  #       "<event_name>": {
+  #         "params":   {"<param>" => "<type>"},   # all 5 ParamSchema types
+  #         "required": ["<required_param_name>"]  # may be []
+  #       }
+  #     }
+  #   }
+  #
+  # Phase 2 ships `params` (types) + `required[]` only — richer
+  # constraints (max/in/format) land in Phase 4 alongside generators.
+  module Manifest
+    DEFAULT_FILENAME = "track_relay_catalog.json"
+
+    class << self
+      # Build the manifest Hash from a catalog-like object.
+      #
+      # @param catalog [#all] anything responding to `all` and returning
+      #   an Array of {EventDefinition}; defaults to {TrackRelay::Catalog}
+      # @return [Hash] frozen-shape manifest (NOT frozen — callers may
+      #   mutate before serialization if needed)
+      def generate(catalog: Catalog)
+        {
+          version: TrackRelay::VERSION,
+          generated_at: Time.now.utc.iso8601,
+          events: catalog.all.each_with_object({}) do |defn, h|
+            h[defn.name.to_s] = {
+              params: defn.params.transform_keys(&:to_s).transform_values { |s| s.type.to_s },
+              required: defn.params.select { |_, s| s.required }.keys.map(&:to_s)
+            }
+          end
+        }
+      end
+
+      # Write the manifest to `path` as pretty-printed JSON.
+      #
+      # `FileUtils.mkdir_p(File.dirname(path))` is called first so a fresh
+      # checkout (e.g. the Combustion dummy app at `test/internal/`, which
+      # has no `public/` directory) does NOT crash with `Errno::ENOENT` on
+      # the first call.
+      #
+      # @param path [String, Pathname] target file; defaults to
+      #   `Rails.root.join("public", "track_relay_catalog.json")` when
+      #   Rails is loaded
+      # @param catalog [#all] forwarded to {.generate}
+      # @return [String, Pathname] the path that was written
+      def write!(path: default_path, catalog: Catalog)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, JSON.pretty_generate(generate(catalog: catalog)))
+        path
+      end
+
+      private
+
+      def default_path
+        unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+          raise ArgumentError,
+            "TrackRelay::Manifest.write! requires a `path:` argument when Rails.root is unavailable"
+        end
+        Rails.root.join("public", DEFAULT_FILENAME)
+      end
+    end
+  end
+end

data/lib/track_relay/railtie.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require "track_relay/catalog"
+require "track_relay/dispatcher"
+# Direct require of Manifest (rather than going through `lib/track_relay.rb`)
+# keeps this plan file-disjoint with Plan 02-02 in the same wave —
+# Plan 02-02 owns the umbrella file's require list.
+require "track_relay/manifest"
+
+module TrackRelay
+  # Rails integration boundary for the gem.
+  #
+  # Three responsibilities, all wired in initializer blocks:
+  #
+  #   1. Tell Zeitwerk to ignore `Rails.root/config/track_relay` so that
+  #      DSL files in that directory (which call {TrackRelay.catalog}
+  #      rather than defining constants) don't trip Rails autoloading.
+  #
+  #   2. Register a `config.to_prepare` callback that calls
+  #      {Catalog.clear!} and then `Dir.glob/load`s every `*.rb` file
+  #      under `config/track_relay/`. {Catalog.clear!} runs FIRST so
+  #      editing a catalog file in dev produces a clean rebuild rather
+  #      than a duplicate-registration error from {Catalog#register}.
+  #      `to_prepare` runs once at boot in test/production and before
+  #      every request reload in development — exactly the hot-reload
+  #      contract this gem needs.
+  #
+  #   3. Call {Dispatcher.start!} exactly once via
+  #      `config.after_initialize` so the AS::Notifications fan-out
+  #      subscription is registered before the host app handles its
+  #      first request. {Dispatcher.start!} is idempotent so this is
+  #      safe even when the Railtie is loaded multiple times.
+  #
+  # The Railtie is required from `lib/track_relay.rb` only when
+  # `Rails::Railtie` is defined, so the gem still loads cleanly in
+  # non-Rails contexts (plain `require "track_relay"` from a script).
+  class Railtie < Rails::Railtie
+    initializer "track_relay.catalog_autoload" do |app|
+      catalog_dir = app.root.join("config", "track_relay")
+
+      # Conditional ignore avoids a Zeitwerk warning when the directory
+      # doesn't exist yet (host app hasn't created it).
+      Rails.autoloaders.main.ignore(catalog_dir) if catalog_dir.exist?
+
+      # Clear before reload so editing config/track_relay/foo.rb in dev
+      # produces a clean catalog rebuild rather than double-registration
+      # errors from Catalog.register's defensive duplicate guard.
+      #
+      # In development, regenerate `public/track_relay_catalog.json`
+      # after the catalog rebuild so the JS client picks up DSL changes
+      # without a server restart. The test env is excluded explicitly to
+      # avoid every-test churn — production builds the manifest via
+      # `assets:precompile` (see the next initializer).
+      app.config.to_prepare do
+        TrackRelay::Catalog.clear!
+        Dir.glob("#{catalog_dir}/**/*.rb").sort.each do |file|
+          load file
+        end
+
+        if Rails.env.development? && TrackRelay::Catalog.all.any?
+          TrackRelay::Manifest.write!
+        end
+      end
+    end
+
+    initializer "track_relay.start_dispatcher" do |app|
+      app.config.after_initialize do
+        TrackRelay::Dispatcher.start!
+      end
+    end
+
+    # Chain `track_relay:manifest` as a prerequisite of
+    # `assets:precompile` so production / CI builds always ship a fresh
+    # `public/track_relay_catalog.json`. The conditional avoids a
+    # Rake::Task-not-defined error in non-asset apps (API-only Rails
+    # without Sprockets/Propshaft). Mirrors cssbundling-rails /
+    # jsbundling-rails patterns.
+    initializer "track_relay.enhance_assets_precompile" do
+      # `defined?(Rake)` guards against API-only Rails apps that have
+      # never `require "rake"`-d at boot — the initializer is a no-op
+      # there. When Rake IS loaded, the `task_defined?` check then
+      # silently skips when the host app uses neither Sprockets nor
+      # Propshaft.
+      if defined?(Rake) && Rake::Task.task_defined?("assets:precompile")
+        Rake::Task["assets:precompile"].enhance(["track_relay:manifest"])
+      end
+    end
+
+    # Make `rake track_relay:lint` and `rake track_relay:lint:json`
+    # available in any consumer app. `__dir__` is `lib/track_relay`;
+    # `..` walks to `lib`; the rake file lives at `lib/tasks/track_relay.rake`.
+    rake_tasks do
+      load File.expand_path("../tasks/track_relay.rake", __dir__)
+    end
+  end
+end

data/lib/track_relay/subscribers/ahoy.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "track_relay/current"
+require "track_relay/subscribers/base"
+
+module TrackRelay
+  module Subscribers
+    # Server-side Ahoy subscriber (REQ-09).
+    #
+    # Routes catalog events through Ahoy's only public tracking surface
+    # — `controller.ahoy.track(name, properties)` — by reading
+    # {TrackRelay::Current.controller} on the synchronous request
+    # thread. When no controller is in scope (background job, rake
+    # task, console), or the host application does not include
+    # `Ahoy::Controller` in its `ApplicationController`, the subscriber
+    # logs a warning and skips delivery — it does NOT raise, does NOT
+    # enqueue a {DeliveryJob}, and does NOT touch any internal Ahoy
+    # API.
+    #
+    # ## Why synchronous (not async like GA4)
+    #
+    # `Ahoy::Tracker` is bound to the live request — it wraps the
+    # controller's cookie jar and visit lifecycle. By the time a
+    # {DeliveryJob} runs, `Rails.application.executor.wrap` has
+    # already cleared {ActiveSupport::CurrentAttributes}, so
+    # `Current.controller` is nil and the live tracker instance is
+    # unreachable. {.synchronous!} therefore opts the subscriber into
+    # inline delivery on the request thread — `#handle` calls
+    # `safe_deliver(payload)` directly instead of enqueueing a job.
+    #
+    # `tracker.track` is an in-process database write (it calls
+    # `@store.track_event(data)` which does `event_model.create!` or
+    # equivalent), not a network call, so synchronous delivery adds
+    # negligible request overhead and matches how Ahoy itself works
+    # (Ahoy::Trackable wires `track` as an inline before_action helper).
+    #
+    # ## Why no `require "ahoy"`
+    #
+    # The subscriber must load cleanly in non-Ahoy host applications
+    # (the gem ships with the file in `lib/track_relay.rb`'s require
+    # manifest unconditionally). Duck-typing via
+    # `controller.respond_to?(:ahoy, true)` handles the absent-Ahoy
+    # case without a top-level require — the same pattern used by
+    # {ClientId::AhoyVisitor}.
+    #
+    # ## Why no `Ahoy::Event.create!` / `Ahoy::Tracker.new`
+    #
+    # `Ahoy::Tracker` is the sole public tracking surface. Internal
+    # APIs (`Ahoy::Event.create!`, `Ahoy::Visit#track` — which does NOT
+    # exist on the visit model) are off-limits because they bypass
+    # Ahoy's bot-exclusion store, user-method config, and visit
+    # association logic. The subscriber dispatches via
+    # `controller.ahoy.track(name, properties)` only.
+    #
+    # ## Skip conditions
+    #
+    # All three skip paths log a `Rails.logger.warn` line of the form
+    # `[track_relay] Ahoy subscriber skipping delivery — <reason>` and
+    # `return` from {#deliver}. They MUST NOT raise — host applications
+    # that boot without Ahoy or call `TrackRelay.track` from a job
+    # must not crash.
+    #
+    # 1. `Current.controller` is nil — job, rake, or console context.
+    # 2. The controller does not `respond_to?(:ahoy, true)` —
+    #    `Ahoy::Controller` was never `include`d.
+    # 3. `controller.ahoy` returns nil — defensive coverage for a
+    #    controller that has the helper but no live tracker yet.
+    class Ahoy < Base
+      synchronous!
+
+      # Dispatch `payload` to `controller.ahoy.track` when a live
+      # controller with an Ahoy tracker is in scope. Skip-and-warn
+      # otherwise.
+      #
+      # @param payload [TrackRelay::EventPayload]
+      # @return [void]
+      def deliver(payload)
+        controller = TrackRelay::Current.controller
+
+        unless controller&.respond_to?(:ahoy, true)
+          log_skip("no controller or ahoy tracker in context")
+          return
+        end
+
+        tracker = controller.ahoy
+
+        unless tracker
+          log_skip("controller.ahoy returned nil")
+          return
+        end
+
+        tracker.track(payload.name.to_s, payload.params)
+      end
+
+      private
+
+      # Mirror of {Subscribers::Ga4MeasurementProtocol#warn_missing_credentials}
+      # — guarded `Rails.logger.warn` so the subscriber stays callable
+      # in non-Rails contexts (e.g. plain `require "track_relay"` from
+      # a script).
+      #
+      # @param reason [String]
+      # @return [void]
+      def log_skip(reason)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn("[track_relay] Ahoy subscriber skipping delivery — #{reason}")
+      end
+    end
+  end
+end