uml-viewer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 43940d01f25e1e7ac319450763c3c3498654a77ac60de6a5ca1bf5dcc8ded444
+  data.tar.gz: 00cd3efb4a8ede7ffc031b56b8d4f3f16caf4fed27746e4723682d786343b411
+SHA512:
+  metadata.gz: 03a181720c4fd021b9f7bc13dc5b3a414c9ad2b146d2197f51c0e6a5e6e198d3a46a8accfdffbc3b660cc5d6d9fbec86aabef1914fad90e73642b79d4c6dcaa3
+  data.tar.gz: 69bee8c7b56e6f0c6ec3a1b4f532ea67a43649d2f76f2483270af913afd366b0786e45b9823f087738fa2e4ad723f32d8648e214fc96fd7a4d730fc175b0961c

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-23
+
+### Added
+- `uml-viewer <project>` scans a Ruby or Rails project with Prism and opens a live UML diagram in the browser. You drill down from folder and namespace boxes to classes and to source lines.
+- Levels come from `policy.yml`. A dependency from an inner level to an outer level is a red arrow. Associations are never red.
+- Box colors show CRAP from `coverage/.resultset.json` (SimpleCov) and M grades from an optional `mutation.json`. Grey means no data.
+- Proposals regroup the code into ranked components without a change to the code.
+- Declutter cycles through five modes on the `d` key.
+- A right-click sends Explain or Omit to a Claude Code session through a mailbox. `uml-viewer install-skill` installs the skill, and `uml-viewer watch` wakes the session through the Monitor tool.
+- State lives in `~/.uml-viewer/projects/`. Nothing is written into the viewed project.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Hopman
+
+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,58 @@
+# uml-viewer
+
+A live UML diagram of a Ruby or Rails project in the browser. Red arrows break the Dependency Rule. A Claude Code session handles your clicks.
+
+> Based on the ideas of [unclebob/uml-viewer](https://github.com/unclebob/uml-viewer) by Robert C. Martin (Uncle Bob), a Clojure tool. This gem reuses its ideas and its observed behavior for Ruby and Rails. No code is copied.
+
+## Install
+
+```sh
+gem install uml-viewer
+uml-viewer install-skill
+uml-viewer path/to/project
+```
+
+`install-skill` installs the Claude Code skill that handles the clicks from the diagram. Nothing is written into the viewed project. State lives in `~/.uml-viewer/projects/`.
+
+## Navigate
+
+- Double-click a box to open it. Press `Esc` to go back.
+- Double-click a class to open its card. Click an operation to see its source.
+- Hover an arrow to see the class pairs behind it.
+- Right-click a box or a class to send **Explain** or **Omit** to Claude.
+
+## Test quality
+
+Box colors show test quality: green is a good grade, red is a poor grade, and grey dots mean no data. The class card says why.
+
+- **Coverage and CRAP:** run your tests with [SimpleCov](https://github.com/simplecov-ruby/simplecov). The viewer reads `coverage/.resultset.json` in the project.
+- **Mutation grades:** put a mutation snapshot as `mutation.json` in the state folder. `uml-viewer path` prints that folder.
+
+## Proposals
+
+Proposals regroup the code without a change to the code.
+
+1. Press **New proposal**, or ask Claude for one. Claude writes it into `policy.yml`.
+2. A proposal lists components in rank order. The first component is level 0.
+3. A member is a class id, a namespace, or a folder box such as `folder:models`.
+4. Choose the proposal in the diagram list. The diagram shows the code in its components, with red arrows by the ranks of the proposal.
+
+Classes in no component wait in **Unassigned**.
+
+## Declutter
+
+Press `d` or the declutter button to cycle through five modes: one arrow per pair, triangles, hide members, hide classes, none.
+
+## Check the skill
+
+```sh
+bundle exec rake eval:skill
+```
+
+This runs the skill with `claude -p` on a copy of the fixture project and checks what it changed. It needs a logged-in `claude` and costs a few cents per run. `EVAL_MODEL`, `EVAL_BUDGET` and `EVAL_TIMEOUT` tune it.
+
+## Credits and licence
+
+- The ideas come from [unclebob/uml-viewer](https://github.com/unclebob/uml-viewer) by Robert C. Martin. No code is copied.
+- [elkjs](https://github.com/kieler/elkjs) (EPL-2.0) does the layout. It is vendored in `lib/uml/viewer/web/`.
+- uml-viewer is released under the [MIT licence](LICENSE).

data/exe/uml-viewer

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require "uml/viewer"
+
+exit Uml::Viewer::CLI.new(ARGV).run

data/lib/uml/viewer/cli.rb

@@ -0,0 +1,133 @@
+require "json"
+require "optparse"
+
+module Uml
+  module Viewer
+    class CLI
+      COMMANDS = %w[scan inbox done watch path init install-skill].freeze
+      USAGE = "usage: uml-viewer [path] | scan|inbox|watch|path|init [path] | done <id> [path] [--failed reason] | install-skill"
+
+      def initialize(argv, out: $stdout, err: $stderr)
+        @argv = argv.dup
+        @out = out
+        @err = err
+      end
+
+      def run
+        command = COMMANDS.include?(@argv.first) ? @argv.shift : "open"
+        send("run_#{command.tr('-', '_')}")
+      rescue Interrupt
+        130
+      rescue Workspace::MissingProject, PolicyFile::Invalid => error
+        @err.puts error.message
+        1
+      end
+
+      private
+
+      def workspace
+        @workspace ||= Workspace.new(@argv.first || ".")
+      end
+
+      def run_path
+        @out.puts workspace.dir
+        0
+      end
+
+      def run_init
+        policy = workspace.path("policy.yml")
+        if File.exist?(policy)
+          @out.puts "policy.yml exists: #{policy}"
+        else
+          Graph.prepare(workspace)
+          @out.puts "wrote #{policy}"
+        end
+        0
+      end
+
+      def run_scan
+        Graph.prepare(workspace)
+        graph = Graph.build(workspace)
+        summary = graph["summary"]
+        violating = graph["edges"].count { |edge| edge["violating"] }
+        @out.puts "#{graph['classes'].size} classes, #{graph['edges'].size} edges, #{violating} violating, " \
+                  "skipped #{summary['skipped'].size} files, no constant"
+        @out.puts "#{summary['unresolved']} unresolved associations, #{summary['polymorphic']} polymorphic associations (no target)"
+        @out.puts "unlisted foreign: #{summary['foreign'].map { |name, count| "#{name} (#{count})" }.join(', ')}"
+        @out.puts Graph.coverage_line(summary["coverage"])
+        summary["warnings"] += [summary["coverage"]["banner"]].compact
+        summary["warnings"].each { |warning| @out.puts "warning: #{warning}" }
+        0
+      end
+
+      def run_inbox
+        command = Mailbox.new(workspace).peek
+        @out.puts JSON.generate(command) if command
+        0
+      end
+
+      def run_done
+        id, failed = parse_done_arguments
+        return usage unless id
+
+        if Mailbox.new(workspace).done(id, failed: failed)
+          0
+        else
+          @err.puts "no command with id #{id}"
+          1
+        end
+      end
+
+      def parse_done_arguments
+        failed = nil
+        OptionParser.new { |opts| opts.on("--failed REASON") { |reason| failed = reason } }.parse!(@argv)
+        [Integer(@argv.shift, 10), failed]
+      rescue OptionParser::ParseError, ArgumentError, TypeError
+        nil
+      end
+
+      def usage
+        @err.puts USAGE
+        2
+      end
+
+      def run_watch
+        Watcher.new(workspace).run
+      end
+
+      def run_install_skill
+        installer = SkillInstaller.new(executable: File.expand_path($PROGRAM_NAME))
+        @out.puts "wrote #{installer.install}"
+        installer.allowed_tools.each { |rule| @out.puts "  #{rule}" }
+        0
+      end
+
+      def run_open
+        if workspace.server_alive?
+          info = workspace.server_info
+          url = "http://127.0.0.1:#{info['port']}/?token=#{info['token']}"
+          @out.puts "already running at #{url}"
+          open_browser(url)
+          return 0
+        end
+        Graph.prepare(workspace)
+        Graph.build(workspace)
+        server = Server.new(workspace).start
+        @out.puts "uml-viewer: #{server.url}"
+        open_browser(server.url)
+        trap("INT") { Thread.new { server.shutdown } }
+        trap("TERM") { Thread.new { server.shutdown } }
+        begin
+          server.run
+        ensure
+          server.shutdown
+        end
+        0
+      end
+
+      def open_browser(url)
+        system("open", url) unless ENV["UML_VIEWER_NO_BROWSER"] == "1"
+      end
+    end
+  end
+end

data/lib/uml/viewer/commands.rb

@@ -0,0 +1,51 @@
+module Uml
+  module Viewer
+    module Commands
+      TARGET_KEYS = {
+        "explain" => %w[id kind proposal_id],
+        "omit" => %w[id kind proposal_id],
+        "context" => %w[proposal_id],
+        "propose" => nil
+      }.freeze
+
+      def self.validate(body, ids:, proposal_ids:)
+        return refuse("body must be a JSON object") unless body.is_a?(Hash)
+
+        extra = (body.keys - %w[op target]).first
+        return refuse("unknown key: #{extra}") if extra
+
+        op = body["op"]
+        return refuse("unknown op: #{op}") unless TARGET_KEYS.key?(op)
+
+        keys = TARGET_KEYS[op]
+        return refuse("#{op} takes no target") if keys.nil? && body.key?("target")
+        return [op, nil, nil] if keys.nil?
+
+        target = body["target"]
+        return refuse("#{op} needs a target") unless target.is_a?(Hash)
+
+        extra = (target.keys - keys).first
+        return refuse("unknown key in target: #{extra}") if extra
+        return refuse("target needs #{(keys - target.keys).join(', ')}") unless (keys - target.keys).empty?
+
+        reason = check_target(target, ids, proposal_ids)
+        reason ? refuse(reason) : [op, target, nil]
+      end
+
+      def self.check_target(target, ids, proposal_ids)
+        proposal = target["proposal_id"]
+        return "unknown proposal: #{proposal}" unless proposal.nil? || proposal_ids.include?(proposal)
+        return nil unless target.key?("id")
+        return "target kind must be class or box" unless %w[class box].include?(target["kind"])
+        known = target["kind"] == "box" && proposal ? ids.fetch("proposal_boxes", {}).fetch(proposal, Set.new) : ids.fetch(target["kind"])
+        return "unknown target: #{target['id']}" unless known.include?(target["id"])
+
+        nil
+      end
+
+      def self.refuse(reason)
+        [nil, nil, reason]
+      end
+    end
+  end
+end

data/lib/uml/viewer/complexity.rb

@@ -0,0 +1,28 @@
+require "prism"
+
+module Uml
+  module Viewer
+    module Complexity
+      BRANCHES = [
+        Prism::IfNode, Prism::UnlessNode, Prism::WhileNode, Prism::UntilNode, Prism::ForNode, Prism::WhenNode,
+        Prism::InNode, Prism::RescueNode, Prism::RescueModifierNode, Prism::AndNode, Prism::OrNode
+      ].freeze
+      SHORT_CIRCUIT_WRITES = Prism.constants.grep(/(And|Or)WriteNode\z/).map { |name| Prism.const_get(name) }.freeze
+
+      def self.of(definition)
+        1 + count(definition.body)
+      end
+
+      def self.count(node)
+        return 0 if node.nil?
+
+        (branch?(node) ? 1 : 0) + node.compact_child_nodes.sum { |child| count(child) }
+      end
+
+      def self.branch?(node)
+        BRANCHES.include?(node.class) || SHORT_CIRCUIT_WRITES.include?(node.class) ||
+          (node.respond_to?(:safe_navigation?) && node.safe_navigation?)
+      end
+    end
+  end
+end

data/lib/uml/viewer/coverage.rb

@@ -0,0 +1,67 @@
+require "json"
+require "set"
+
+module Uml
+  module Viewer
+    module Coverage
+      class Unreadable < StandardError; end
+
+      def self.load(root, scanned_files)
+        path = File.join(root, "coverage", ".resultset.json")
+        return nil unless File.exist?(path)
+
+        resultset = JSON.parse(File.read(path))
+        raise Unreadable, "coverage file unreadable: #{path}" unless suites?(resultset)
+
+        parse(resultset, scanned_files)
+      rescue JSON::ParserError, SystemCallError
+        raise Unreadable, "coverage file unreadable: #{path}"
+      end
+
+      def self.suites?(resultset)
+        resultset.is_a?(Hash) && !resultset.empty? && resultset.values.all? do |suite|
+          suite.is_a?(Hash) && suite["timestamp"].is_a?(Numeric) && suite["coverage"].is_a?(Hash) &&
+            suite["coverage"].values.all? { |entry| hits?(entry.is_a?(Hash) ? entry["lines"] : entry) }
+        end
+      end
+
+      def self.hits?(hits)
+        hits.is_a?(Array) && hits.all? { |hit| hit.nil? || hit.is_a?(Integer) }
+      end
+
+      def self.parse(resultset, scanned_files)
+        wanted = scanned_files.to_set
+        lines = {}
+        resultset.each_value do |suite|
+          root = root_of(suite["coverage"].keys, scanned_files)
+          suite["coverage"].each do |absolute, value|
+            file = root && absolute.start_with?("#{root}/") ? absolute.delete_prefix("#{root}/") : nil
+            next unless wanted.include?(file)
+
+            lines[file] = add(lines[file], value.is_a?(Hash) ? value["lines"] : value)
+          end
+        end
+        { "time" => resultset.values.filter_map { |suite| suite["timestamp"] }.max, "lines" => lines }
+      end
+
+      def self.root_of(paths, scanned_files)
+        by_name = scanned_files.group_by { |file| File.basename(file) }
+        candidates = paths.filter_map do |absolute|
+          file = by_name.fetch(File.basename(absolute), []).select { |name| absolute.end_with?("/#{name}") }.max_by(&:size)
+          file && absolute.delete_suffix("/#{file}")
+        end
+        candidates.tally.max_by { |_, count| count }&.first
+      end
+
+      def self.add(sum, hits)
+        return hits.dup if sum.nil?
+
+        Array.new([sum.size, hits.size].max) do |index|
+          left = sum[index]
+          right = hits[index]
+          left.nil? && right.nil? ? nil : left.to_i + right.to_i
+        end
+      end
+    end
+  end
+end

data/lib/uml/viewer/graph.rb

@@ -0,0 +1,113 @@
+require "json"
+require "set"
+require "time"
+
+module Uml
+  module Viewer
+    module Graph
+      def self.prepare(workspace)
+        return if File.exist?(workspace.path("policy.yml"))
+
+        scan = Scanner.new(workspace.root).scan
+        PolicyInit.write(workspace, class_ids: scan["classes"].map { |entry| entry["id"] })
+      end
+
+      def self.build(workspace)
+        policy = PolicyFile.load(workspace.path("policy.yml"))
+        scan = Scanner.new(workspace.root, sources: policy["sources"], skip: policy["skip"]).scan
+        applied = Policy.apply(scan, policy)
+        files = applied["classes"].flat_map { |entry| entry["files"] }.uniq
+        coverage, coverage_error = load_coverage(workspace, files)
+        mutation, mutation_error = load_mutation(workspace)
+        overlay = Overlay.apply(applied["classes"], coverage: coverage, mutation: mutation, cutoffs: policy["crap_cutoffs"],
+                                                    mtimes: files.to_h { |file| [file, mtime(File.join(workspace.root, file))] },
+                                                    missing_note: coverage_error || Overlay::NO_COVERAGE)
+        summary = summary(scan, applied, policy)
+        summary["coverage"] = overlay["coverage"].merge("banner" => coverage_error || overlay["coverage"]["banner"])
+        summary["warnings"] += [mutation_error].compact
+        graph = {
+          "version" => 3,
+          "title" => policy["title"].empty? ? File.basename(workspace.root) : policy["title"],
+          "proposals" => applied["proposals"].map do |proposal|
+            proposal.slice("id", "name").merge("views" => Overlay.boxes(proposal["views"], overlay["classes"], policy["crap_cutoffs"]))
+          end,
+          "summary" => summary,
+          "namespaces" => applied["namespaces"],
+          "classes" => overlay["classes"],
+          "edges" => applied["edges"],
+          "views" => Overlay.boxes(applied["views"], overlay["classes"], policy["crap_cutoffs"])
+        }
+        workspace.write_atomic("graph.json", JSON.generate(graph))
+        graph
+      end
+
+      def self.load_coverage(workspace, files)
+        [Coverage.load(workspace.root, files), nil]
+      rescue Coverage::Unreadable => error
+        [nil, error.message]
+      end
+
+      def self.load_mutation(workspace)
+        path = workspace.path("mutation.json")
+        return [nil, nil] unless File.exist?(path)
+
+        data = JSON.parse(File.read(path))
+        mutation_snapshot?(data) ? [data, nil] : [nil, "mutation snapshot unreadable: #{path}"]
+      rescue JSON::ParserError, SystemCallError
+        [nil, "mutation snapshot unreadable: #{path}"]
+      end
+
+      def self.mutation_snapshot?(data)
+        data.is_a?(Hash) && data.values.all? do |entry|
+          entry.is_a?(Hash) && Overlay::COUNTS.all? { |key| !entry.key?(key) || (entry[key].is_a?(Integer) && entry[key] >= 0) }
+        end
+      end
+
+      def self.coverage_line(coverage)
+        return "coverage: none" if coverage["time"].nil?
+
+        "coverage: #{coverage['files']} of #{coverage['scanned']} files from #{Time.at(coverage['time']).utc.iso8601}"
+      end
+
+      def self.summary(scan, applied, policy)
+        {
+          "classes" => applied["classes"].size,
+          "skipped" => scan["skipped"],
+          "foreign" => scan["foreign"].reject { |name, _| policy["foreign"].include?(name) }.first(20),
+          "unresolved" => scan["unresolved"],
+          "polymorphic" => scan["polymorphic"],
+          "warnings" => applied["warnings"] + scan["unreadable"].map { |file| "unreadable file: #{file}" }
+        }
+      end
+
+      def self.ids(graph)
+        {
+          "class" => Set.new(graph["classes"].map { |entry| entry["id"] }),
+          "box" => box_ids(graph["views"]),
+          "proposal_boxes" => graph.fetch("proposals", []).to_h { |proposal| [proposal["id"], box_ids(proposal["views"])] }
+        }
+      end
+
+      def self.box_ids(views)
+        Set.new(views.values.flat_map { |view| view["nodes"] }.select { |node| Views::BOXES.include?(node["type"]) }.map { |node| node["id"] })
+      end
+
+      def self.inputs(workspace)
+        sources = begin
+          PolicyFile.load(workspace.path("policy.yml"))["sources"]
+        rescue PolicyFile::Invalid
+          PolicyFile::DEFAULTS["sources"]
+        end
+        files = sources.flat_map { |source| Dir.glob("#{source}/**/*.rb", base: workspace.root) }
+        extra = [File.join(workspace.root, "coverage", ".resultset.json"), workspace.path("mutation.json")]
+        ([workspace.path("policy.yml")] + extra + files.map { |file| File.join(workspace.root, file) }).to_h { |path| [path, mtime(path)] }
+      end
+
+      def self.mtime(path)
+        File.mtime(path).to_f
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+  end
+end

data/lib/uml/viewer/inflector.rb

@@ -0,0 +1,19 @@
+module Uml
+  module Viewer
+    module Inflector
+      SINGULAR = [
+        [/people\z/, "person"], [/children\z/, "child"], [/ies\z/, "y"], [/sses\z/, "ss"], [/xes\z/, "x"],
+        [/ches\z/, "ch"], [/shes\z/, "sh"], [/ses\z/, "s"], [/s\z/, ""]
+      ].freeze
+
+      def self.singularize(word)
+        pattern, replacement = SINGULAR.find { |rule, _| word.match?(rule) }
+        pattern ? word.sub(pattern, replacement) : word
+      end
+
+      def self.camelize(word)
+        word.split("_").map(&:capitalize).join
+      end
+    end
+  end
+end

data/lib/uml/viewer/mailbox.rb

@@ -0,0 +1,79 @@
+require "json"
+require "time"
+
+module Uml
+  module Viewer
+    class Mailbox
+      class QueueFull < StandardError; end
+
+      CAP = 100
+
+      def initialize(workspace)
+        @workspace = workspace
+      end
+
+      def append(op:, target: nil)
+        locked do |state|
+          raise QueueFull, "queue full: start Claude or clear the queue" if state["queue"].size >= self.class::CAP
+
+          id = state["next_id"]
+          command = { "id" => id, "op" => op }
+          command["target"] = target unless target.nil?
+          command["at"] = Time.now.utc.iso8601
+          state["queue"] << command
+          state["next_id"] = id + 1
+          id
+        end
+      end
+
+      def peek
+        queue.first
+      end
+
+      def queue
+        read_state["queue"]
+      end
+
+      def size
+        queue.size
+      end
+
+      def done(id, failed: nil)
+        locked do |state|
+          command = state["queue"].find { |entry| entry["id"] == id }
+          if command
+            state["queue"].delete(command)
+            log_failure(command, failed) if failed
+          end
+          command
+        end
+      end
+
+      def last_failed
+        @workspace.read_json("failed.json", []).last
+      end
+
+      private
+
+      def read_state
+        @workspace.read_json("to-agent.json", { "next_id" => 1, "queue" => [] })
+      end
+
+      def locked
+        File.open(@workspace.path("to-agent.lock"), File::RDWR | File::CREAT, 0o600) do |lock|
+          lock.flock(File::LOCK_EX)
+          state = read_state
+          result = yield(state)
+          @workspace.write_atomic("to-agent.json", JSON.generate(state))
+          result
+        end
+      end
+
+      def log_failure(command, reason)
+        failures = @workspace.read_json("failed.json", [])
+        failures << { "id" => command["id"], "op" => command["op"], "reason" => reason, "at" => Time.now.utc.iso8601 }
+        @workspace.write_atomic("failed.json", JSON.generate(failures))
+      end
+    end
+  end
+end