uml-viewer 0.1.0

data/lib/uml/viewer/operations.rb

@@ -0,0 +1,105 @@
+require "prism"
+
+module Uml
+  module Viewer
+    class Operations
+      VISIBILITIES = %i[public private protected].freeze
+
+      def initialize(program, file)
+        @program = program
+        @file = file
+        @ops = []
+      end
+
+      def collect
+        scope(@program.statements.body, singleton: false)
+        @ops
+      end
+
+      private
+
+      def scope(statements, singleton:)
+        state = { visibility: "public", named: {}, private_singletons: [], added: [] }
+        statements.each { |node| visit(node, state, singleton) }
+        state[:added].each { |op, receiver| settle(op, receiver, state) }
+      end
+
+      def visit(node, state, singleton)
+        case node
+        when Prism::DefNode then state[:added] << add(node, state[:visibility], singleton)
+        when Prism::ClassNode, Prism::ModuleNode then scope(statements_of(node.body), singleton: false)
+        when Prism::SingletonClassNode then scope(statements_of(node.body), singleton: true)
+        when Prism::ConstantWriteNode, Prism::ConstantPathWriteNode then scope_block(node.value, singleton: false)
+        when Prism::CallNode then visit_call(node, state, singleton)
+        end
+      end
+
+      def visit_call(node, state, singleton)
+        arguments = node.arguments&.arguments
+        if node.receiver.nil? && VISIBILITIES.include?(node.name)
+          set_visibility(node.name.to_s, arguments, state, singleton)
+        elsif node.receiver.nil? && node.name == :private_class_method
+          arguments.to_a.each do |argument|
+            state[:added] << add(argument, "public", singleton) if argument.is_a?(Prism::DefNode)
+            name = argument.is_a?(Prism::DefNode) ? argument.name.to_s : literal(argument)
+            state[:private_singletons] << name if name
+          end
+        else
+          scope_block(node, singleton: node.name == :class_methods)
+        end
+      end
+
+      def set_visibility(visibility, arguments, state, singleton)
+        if arguments.nil?
+          state[:visibility] = visibility
+          return
+        end
+
+        arguments.each do |argument|
+          if argument.is_a?(Prism::DefNode)
+            state[:added] << add(argument, visibility, singleton)
+          elsif (name = literal(argument))
+            state[:named][name] = visibility
+          end
+        end
+      end
+
+      def settle(op, receiver, state)
+        name = op["name"].delete_prefix("self.")
+        if receiver
+          op["visibility"] = "private" if state[:private_singletons].include?(name)
+        elsif state[:named].key?(name)
+          op["visibility"] = state[:named][name]
+        end
+      end
+
+      def add(node, visibility, singleton)
+        receiver = !node.receiver.nil?
+        op = {
+          "name" => receiver || singleton ? "self.#{node.name}" : node.name.to_s,
+          "visibility" => receiver ? "public" : visibility,
+          "cc" => Complexity.of(node),
+          "file" => @file,
+          "line_start" => node.location.start_line,
+          "line_end" => node.location.end_line
+        }
+        @ops << op
+        [op, receiver]
+      end
+
+      def scope_block(node, singleton:)
+        return unless node.is_a?(Prism::CallNode) && node.block.is_a?(Prism::BlockNode)
+
+        scope(statements_of(node.block.body), singleton: singleton)
+      end
+
+      def statements_of(body)
+        body.is_a?(Prism::StatementsNode) ? body.body : []
+      end
+
+      def literal(node)
+        node.unescaped if node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
+      end
+    end
+  end
+end

data/lib/uml/viewer/overlay.rb

@@ -0,0 +1,165 @@
+module Uml
+  module Viewer
+    module Overlay
+      NO_COVERAGE = "no coverage: run your tests with SimpleCov".freeze
+      STALE = "coverage older than this file".freeze
+      NOT_LOADED = "not loaded by the tests".freeze
+      UNTESTED = "no test runs these methods".freeze
+      PARTIAL = "coverage looks partial: run the full suite".freeze
+      COUNTS = %w[killed survived uncovered].freeze
+
+      def self.apply(classes, coverage:, mtimes:, mutation:, cutoffs:, missing_note: NO_COVERAGE)
+        files = classes.flat_map { |entry| entry["files"] }.uniq
+        present = coverage ? files.count { |file| coverage["lines"].key?(file) } : 0
+        partial = !coverage.nil? && present < files.size / 2.0
+        states = files.to_h { |file| [file, file_state(file, coverage, mtimes, partial)] }
+        notes = { none: missing_note, stale: STALE, absent: NOT_LOADED, partial: PARTIAL }
+        graded = classes.map do |entry|
+          ops = entry["ops"].map { |op| with_metrics(op, states[op["file"]], coverage) }
+          crap = class_crap(ops, cutoffs)
+          counts = mutation_counts(entry["id"], ops, mutation)
+          tested = counts && mutation_grade(counts)
+          entry.merge(
+            "ops" => ops, "coverage_notes" => coverage_notes(entry["files"], states, notes, ops),
+            "crap" => crap, "mutation" => tested, "grade" => mean_grade(crap, tested)
+          )
+        end
+        { "classes" => graded, "coverage" => summary(coverage, present, files.size, partial) }
+      end
+
+      def self.coverage_notes(files, states, notes, ops)
+        listed = files.filter_map { |file| notes[states[file]] }.uniq
+        loaded = files.any? { |file| states[file] == :lines }
+        loaded && no_test_runs?(measured_ops(ops)) ? listed + [UNTESTED] : listed
+      end
+
+      def self.measured_ops(ops)
+        ops.reject { |op| op["coverage"].nil? }
+      end
+
+      def self.no_test_runs?(measured)
+        measured.any? && measured.all? { |op| op["coverage"].zero? }
+      end
+
+      def self.class_crap(ops, cutoffs)
+        measured = measured_ops(ops)
+        return nil if measured.empty?
+
+        untested(stats(measured.map { |op| op["crap"] }, cutoffs), measured)
+      end
+
+      def self.untested(crap, measured)
+        no_test_runs?(measured) ? crap.merge("grade" => 1) : crap
+      end
+
+      def self.file_state(file, coverage, mtimes, partial)
+        return :none if coverage.nil?
+        return :stale if mtimes[file].to_f > coverage["time"].to_f
+        return :lines if coverage["lines"].key?(file)
+
+        partial ? :partial : :absent
+      end
+
+      def self.with_metrics(op, state, coverage)
+        value = case state
+                when :absent then 0.0
+                when :lines then body_coverage(op, coverage["lines"][op["file"]])
+                end
+        op.merge("coverage" => value, "crap" => value && crap(op["cc"], value))
+      end
+
+      def self.body_coverage(op, hits)
+        body = ((op["line_start"] + 1)..(op["line_end"] - 1)).filter_map { |line| hits[line - 1] }
+        body.empty? ? nil : body.count(&:positive?).fdiv(body.size)
+      end
+
+      def self.crap(cc, coverage)
+        (cc**2) * ((1 - coverage)**3) + cc.to_f
+      end
+
+      def self.stats(values, cutoffs)
+        mu = values.sum.fdiv(values.size)
+        sigma = Math.sqrt(values.sum { |value| (value - mu)**2 }.fdiv(values.size))
+        { "mu" => mu, "sigma" => sigma, "grade" => grade(mu + sigma, cutoffs) }
+      end
+
+      def self.grade(value, cutoffs)
+        index = cutoffs.index { |cutoff| value <= cutoff }
+        index ? 10 - index : 1
+      end
+
+      def self.mutation_counts(class_id, ops, mutation)
+        return nil if mutation.nil?
+
+        found = ops.filter_map { |op| mutation[mutation_key(class_id, op["name"])] }
+        return nil if found.empty?
+
+        COUNTS.to_h { |key| [key, found.sum { |entry| entry[key].to_i }] }
+      end
+
+      def self.mutation_key(class_id, name)
+        name.start_with?("self.") ? "#{class_id}.#{name.delete_prefix('self.')}" : "#{class_id}##{name}"
+      end
+
+      def self.mutation_grade(counts)
+        total = counts.values.sum
+        return nil if total.zero?
+
+        score = counts["killed"].fdiv(total)
+        { "score" => score, "grade" => [1, (score * 10).ceil].max, "counts" => counts }
+      end
+
+      def self.mean_grade(crap, tested)
+        grades = [crap&.fetch("grade"), tested&.fetch("grade")].compact
+        grades.empty? ? nil : grades.sum.fdiv(grades.size)
+      end
+
+      def self.summary(coverage, present, scanned, partial)
+        return { "time" => nil, "files" => 0, "scanned" => scanned, "banner" => nil } if coverage.nil?
+
+        banner = partial ? "coverage looks partial: #{present} of #{scanned} files; run the full suite" : nil
+        { "time" => coverage["time"], "files" => present, "scanned" => scanned, "banner" => banner }
+      end
+
+      def self.boxes(views, classes, cutoffs)
+        by_id = classes.to_h { |entry| [entry["id"], entry] }
+        memo = {}
+        views.transform_values do |view|
+          view.merge("nodes" => view["nodes"].map { |node| node.merge(node_grades(node, views, by_id, cutoffs, memo)) })
+        end
+      end
+
+      def self.node_grades(node, views, by_id, cutoffs, memo)
+        return class_grades(by_id[node["id"]]) if node["type"] == "class"
+        return {} unless Views::BOXES.include?(node["type"])
+
+        entries = classes_under(node["id"], views, memo).filter_map { |id| by_id[id] }
+        pooled(entries, cutoffs)
+      end
+
+      def self.class_grades(entry)
+        return { "c_grade" => nil, "m_grade" => nil, "grade" => nil } if entry.nil?
+
+        { "c_grade" => entry["crap"]&.fetch("grade"), "m_grade" => entry["mutation"]&.fetch("grade"), "grade" => entry["grade"] }
+      end
+
+      def self.pooled(entries, cutoffs)
+        measured = entries.flat_map { |entry| measured_ops(entry["ops"]) }
+        counts = entries.filter_map { |entry| entry.dig("mutation", "counts") }
+        crap = measured.empty? ? nil : untested(stats(measured.map { |op| op["crap"] }, cutoffs), measured)
+        tested = counts.empty? ? nil : mutation_grade(COUNTS.to_h { |key| [key, counts.sum { |count| count[key] }] })
+        { "c_grade" => crap&.fetch("grade"), "m_grade" => tested&.fetch("grade"), "grade" => mean_grade(crap, tested) }
+      end
+
+      def self.classes_under(view_id, views, memo)
+        memo[view_id] ||= views[view_id]["nodes"].flat_map do |node|
+          case node["type"]
+          when "class" then [node["id"]]
+          when *Views::BOXES then classes_under(node["id"], views, memo)
+          else []
+          end
+        end
+      end
+    end
+  end
+end

data/lib/uml/viewer/policy.rb

@@ -0,0 +1,59 @@
+module Uml
+  module Viewer
+    module Policy
+      def self.apply(scan, policy)
+        omit = policy["omit"]
+        classes = scan["classes"].reject { |entry| omitted_by_name?(entry["id"], omit) }
+        namespaces = scan["namespaces"].select { |name| classes.any? { |entry| entry["id"].start_with?("#{name}::") } }
+        classes = classes.reject { |entry| omit.include?("folder:#{entry['kind_folder']}") && top_level?(entry, namespaces) }
+        levels = level_index(policy["levels"])
+        classes = classes.map { |entry| entry.merge("level" => levels[entry["kind_folder"]]) }
+        by_id = classes.to_h { |entry| [entry["id"], entry] }
+        edges = scan["edges"].select { |edge| by_id.key?(edge["from"]) && by_id.key?(edge["to"]) }
+        edges = adjust_edges(edges, policy["edge_kinds"], policy["omit_edges"])
+                .map { |edge| edge.merge("violating" => violating?(edge, by_id)) }
+        foreign_edges = scan["foreign_edges"].select { |edge| policy["foreign"].include?(edge["to"]) && by_id.key?(edge["from"]) }
+        proposals = Proposals.build(policy["proposals"], classes: classes, namespaces: namespaces, edges: edges, foreign_edges: foreign_edges)
+        {
+          "classes" => classes,
+          "edges" => edges,
+          "namespaces" => namespaces,
+          "views" => Views.build(classes, namespaces, edges, foreign_edges),
+          "foreign_edges" => foreign_edges,
+          "proposals" => proposals,
+          "warnings" => (policy["levels"].flatten.uniq - scan["folders"]).map { |name| "levels: unknown folder #{name}" } +
+                        proposals.flat_map { |proposal| proposal["warnings"] }
+        }
+      end
+
+      def self.omitted_by_name?(id, omit)
+        omit.any? { |name| id == name || id.start_with?("#{name}::") }
+      end
+
+      def self.top_level?(entry, namespaces)
+        !entry["id"].include?("::") && !namespaces.include?(entry["id"])
+      end
+
+      def self.adjust_edges(edges, edge_kinds, omit_edges)
+        edges.reject { |edge| omit_edges.include?(pair_key(edge)) }
+             .map { |edge| edge_kinds.key?(pair_key(edge)) ? edge.merge("kind" => edge_kinds[pair_key(edge)], "kinds" => [edge_kinds[pair_key(edge)]]) : edge }
+      end
+
+      def self.pair_key(edge)
+        "#{edge['from']} -> #{edge['to']}"
+      end
+
+      def self.level_index(levels)
+        levels.each_with_index.flat_map { |row, index| row.map { |folder| [folder, index] } }.to_h
+      end
+
+      def self.violating?(edge, by_id)
+        from = by_id[edge["from"]]["level"]
+        to = by_id[edge["to"]]["level"]
+        return false if from.nil? || to.nil? || from >= to
+
+        edge["kinds"].any? { |kind| kind != "association" }
+      end
+    end
+  end
+end

data/lib/uml/viewer/policy_file.rb

@@ -0,0 +1,124 @@
+require "yaml"
+
+module Uml
+  module Viewer
+    module PolicyFile
+      class Invalid < StandardError; end
+
+      DEFAULTS = {
+        "title" => "",
+        "sources" => %w[app lib],
+        "skip" => [],
+        "levels" => [],
+        "foreign" => [],
+        "omit" => [],
+        "edge_kinds" => {},
+        "omit_edges" => [],
+        "crap_cutoffs" => [5, 10, 15, 20, 30, 40, 60, 80, 120],
+        "proposals" => []
+      }.freeze
+
+      NAME_LISTS = %w[sources skip foreign omit omit_edges].freeze
+
+      def self.load(path)
+        defaults = Marshal.load(Marshal.dump(DEFAULTS))
+        return defaults unless File.exist?(path)
+
+        data = YAML.safe_load(File.read(path)) || {}
+        raise Invalid, "policy.yml: the file must hold a mapping" unless data.is_a?(Hash)
+
+        validate(defaults.merge(data) { |_key, default, given| given.nil? ? default : given })
+      rescue Psych::SyntaxError => error
+        raise Invalid, "policy.yml line #{error.line}: #{error.problem}"
+      rescue Psych::Exception => error
+        raise Invalid, "policy.yml: #{error.message}"
+      end
+
+      def self.validate(policy)
+        NAME_LISTS.each do |key|
+          next if policy[key].is_a?(Array) && policy[key].all?(String)
+
+          raise Invalid, "policy.yml: #{key} must be a list of names"
+        end
+        unless policy["levels"].is_a?(Array) && policy["levels"].all? { |row| row.is_a?(Array) && row.all?(String) }
+          raise Invalid, "policy.yml: levels must be a list of lists of folder names"
+        end
+        raise Invalid, "policy.yml: edge_kinds must be a mapping" unless policy["edge_kinds"].is_a?(Hash)
+        unless policy["edge_kinds"].all? { |pair, kind| pair.is_a?(String) && pair.match?(/\A\S+ -> \S+\z/) && Scanner::KINDS.include?(kind) }
+          raise Invalid, "policy.yml: edge_kinds maps \"From -> To\" to one of #{Scanner::KINDS.join(', ')}"
+        end
+        raise Invalid, "policy.yml: title must be text" unless policy["title"].is_a?(String)
+        policy["proposals"] = proposals(policy["proposals"])
+        cutoffs = policy["crap_cutoffs"]
+        unless cutoffs.is_a?(Array) && cutoffs.size == 9 && cutoffs.all?(Numeric) && cutoffs.each_cons(2).all? { |low, high| low < high }
+          raise Invalid, "policy.yml: crap_cutoffs must be 9 numbers in rising order"
+        end
+
+        policy
+      end
+
+      def self.proposals(list)
+        raise Invalid, "policy.yml: proposals must be a list" unless list.is_a?(Array)
+
+        seen = []
+        list.map do |proposal|
+          raise Invalid, "policy.yml: each proposal must be a mapping with an id" unless proposal.is_a?(Hash) && proposal.key?("id")
+          raise Invalid, "policy.yml: a proposal id must be text" unless text?(proposal["id"])
+
+          id = proposal["id"]
+          raise Invalid, "policy.yml: proposal ids must be unique: #{id}" if seen.include?(id)
+
+          seen << id
+          proposal(proposal)
+        end
+      end
+
+      def self.text?(value)
+        value.is_a?(String) && !value.empty?
+      end
+
+      def self.proposal(proposal)
+        id = proposal["id"]
+        name = proposal["name"] || id
+        raise Invalid, "policy.yml: proposal #{id}: name must be text" unless name.is_a?(String)
+
+        omit = proposal["omit"] || []
+        raise Invalid, "policy.yml: proposal #{id}: omit must be a list of names" unless omit.is_a?(Array) && omit.all?(String)
+
+        proposal.merge("name" => name, "components" => components(id, proposal["components"] || [], []), "omit" => omit)
+      end
+
+      def self.components(proposal_id, list, seen)
+        raise Invalid, "policy.yml: proposal #{proposal_id}: components must be a list" unless list.is_a?(Array)
+
+        list.map do |component|
+          raise Invalid, "policy.yml: proposal #{proposal_id}: each component must be a mapping with an id" unless component.is_a?(Hash) && component.key?("id")
+          raise Invalid, "policy.yml: proposal #{proposal_id}: a component id must be text" unless text?(component["id"])
+
+          id = component["id"]
+          raise Invalid, "policy.yml: proposal #{proposal_id}: component ids must be unique: #{id}" if seen.include?(id)
+
+          seen << id
+          component(proposal_id, component, seen)
+        end
+      end
+
+      def self.component(proposal_id, component, seen)
+        prefix = "policy.yml: proposal #{proposal_id}: component #{component['id']}"
+        label = component["label"] || component["id"]
+        raise Invalid, "#{prefix}: label must be text" unless label.is_a?(String)
+
+        members = component["members"] || []
+        raise Invalid, "#{prefix}: members must be a list" unless members.is_a?(Array)
+
+        members = members.map do |member|
+          next member if member.is_a?(String)
+          next components(proposal_id, [member], seen).first if member.is_a?(Hash)
+
+          raise Invalid, "#{prefix}: a member is a name or a component, not #{member.inspect}"
+        end
+        component.merge("label" => label, "members" => members)
+      end
+    end
+  end
+end

data/lib/uml/viewer/policy_init.rb

@@ -0,0 +1,51 @@
+require "yaml"
+
+module Uml
+  module Viewer
+    module PolicyInit
+      DEFAULT_LEVELS = [
+        %w[models],
+        %w[services queries policies lib uploaders validators inputs],
+        %w[jobs mailers channels presenters decorators serializers],
+        %w[controllers helpers components admin graphql]
+      ].freeze
+      SKIPPED_KINDS = %w[assets views javascript frontend].freeze
+      OMIT_CANDIDATES = %w[ApplicationRecord ApplicationController ApplicationJob ApplicationMailer].freeze
+
+      def self.folder_kinds(root)
+        kinds = Dir.glob("app/*/", base: root).map { |folder| File.basename(folder) } - SKIPPED_KINDS
+        kinds << "lib" if File.directory?(File.join(root, "lib"))
+        kinds.uniq.sort
+      end
+
+      def self.write(workspace, class_ids:)
+        return false if File.exist?(workspace.path("policy.yml"))
+
+        kinds = folder_kinds(workspace.root)
+        levels = DEFAULT_LEVELS.map { |row| row & kinds }.reject(&:empty?)
+        unlisted = kinds - DEFAULT_LEVELS.flatten
+        policy = {
+          "title" => File.basename(workspace.root),
+          "sources" => %w[app lib],
+          "skip" => [],
+          "levels" => levels,
+          "foreign" => [],
+          "omit" => OMIT_CANDIDATES & class_ids,
+          "edge_kinds" => {},
+          "omit_edges" => [],
+          "proposals" => []
+        }
+        workspace.write_atomic("policy.yml", with_unlisted_comment(YAML.dump(policy), unlisted))
+        true
+      end
+
+      def self.with_unlisted_comment(text, unlisted)
+        return text if unlisted.empty?
+
+        lines = text.lines
+        position = lines.index { |line| line.start_with?("levels:") }
+        lines.insert(position + 1, "# not compared: #{unlisted.join(', ')}\n").join
+      end
+    end
+  end
+end

data/lib/uml/viewer/proposals.rb

@@ -0,0 +1,78 @@
+module Uml
+  module Viewer
+    module Proposals
+      EXACT = 1_000
+
+      def self.build(proposals, classes:, namespaces:, edges:, foreign_edges:)
+        real_paths = Views.paths(classes, namespaces)
+        proposals.map { |proposal| view_of(proposal, classes, namespaces, edges, foreign_edges, real_paths) }
+      end
+
+      def self.view_of(proposal, classes, namespaces, edges, foreign_edges, real_paths)
+        members = members_of(proposal)
+        placed = classes.to_h { |entry| [entry["id"], place(entry, proposal["id"], members, namespaces, real_paths[entry["id"]])] }
+        kept = classes.reject { |entry| omitted?(entry, placed[entry["id"]][:path], proposal["omit"], namespaces) }
+                      .map { |entry| entry.merge("level" => placed[entry["id"]][:rank]) }
+        by_id = kept.to_h { |entry| [entry["id"], entry] }
+        kept_edges = edges.select { |edge| by_id.key?(edge["from"]) && by_id.key?(edge["to"]) }
+                          .map { |edge| edge.merge("violating" => Policy.violating?(edge, by_id)) }
+        {
+          "id" => proposal["id"],
+          "name" => proposal["name"],
+          "views" => Views.build(kept, namespaces, kept_edges, foreign_edges.select { |edge| by_id.key?(edge["from"]) },
+                                 paths: kept.to_h { |entry| [entry["id"], placed[entry["id"]][:path]] }),
+          "warnings" => unmatched(members, classes, namespaces).map { |name| "proposal #{proposal['id']}: member #{name} matches no class in the diagram (check the name and the policy omit)" }
+        }
+      end
+
+      def self.members_of(proposal)
+        list = []
+        walk = lambda do |components, chain, rank|
+          components.each_with_index do |component, index|
+            own_rank = rank || index
+            own_chain = chain + [["component", "component:#{proposal['id']}/#{component['id']}", component["label"]]]
+            component["members"].each do |member|
+              next walk.call([member], own_chain, own_rank) if member.is_a?(Hash)
+
+              list << { name: member, chain: own_chain, rank: own_rank, order: list.size }
+            end
+          end
+        end
+        walk.call(proposal["components"], [], nil)
+        list
+      end
+
+      def self.place(entry, proposal_id, members, namespaces, real_path)
+        best = members.filter_map { |member| (score = specificity(member[:name], entry, namespaces)) && [score, -member[:order], member] }
+                      .max_by { |score, order, _| [score, order] }
+        return { path: [["component", "unassigned:#{proposal_id}", "Unassigned"]] + real_path, rank: nil } if best.nil?
+
+        member = best.last
+        below = real_path.select { |type, id| type == "namespace" && id.start_with?("#{member[:name]}::") }
+        { path: member[:chain] + below + [real_path.last], rank: member[:rank] }
+      end
+
+      def self.specificity(name, entry, namespaces)
+        id = entry["id"]
+        return EXACT if name == id
+        return name.split("::").size if id.start_with?("#{name}::")
+        return 0 if name == "folder:#{entry['kind_folder']}" && Policy.top_level?(entry, namespaces)
+
+        nil
+      end
+
+      def self.omitted?(entry, path, omit, namespaces)
+        omit.any? do |name|
+          Policy.omitted_by_name?(entry["id"], [name]) ||
+            (name == "folder:#{entry['kind_folder']}" && Policy.top_level?(entry, namespaces)) ||
+            path.any? { |_, id| id == name }
+        end
+      end
+
+      def self.unmatched(members, classes, namespaces)
+        members.map { |member| member[:name] }.uniq
+               .reject { |name| classes.any? { |entry| specificity(name, entry, namespaces) } }
+      end
+    end
+  end
+end

data/lib/uml/viewer/rescanner.rb

@@ -0,0 +1,61 @@
+module Uml
+  module Viewer
+    class Rescanner
+      attr_reader :error, :scans
+
+      def initialize(scan:)
+        @scan = scan
+        @mutex = Mutex.new
+        @wake = ConditionVariable.new
+        @dirty = false
+        @running = false
+        @scans = 0
+        @error = nil
+      end
+
+      def start
+        @running = true
+        @thread = Thread.new { work }
+        self
+      end
+
+      def trigger
+        @mutex.synchronize do
+          @dirty = true
+          @wake.signal
+        end
+      end
+
+      def stop
+        @mutex.synchronize do
+          @running = false
+          @wake.signal
+        end
+        @thread&.join(2)
+      end
+
+      private
+
+      def work
+        loop do
+          @mutex.synchronize do
+            @wake.wait(@mutex) while @running && !@dirty
+            return unless @running
+
+            @dirty = false
+          end
+          run_once
+        end
+      end
+
+      def run_once
+        @scan.call
+        @error = nil
+      rescue StandardError, SystemStackError => failure
+        @error = failure.message
+      ensure
+        @scans += 1
+      end
+    end
+  end
+end