archspec_diagram 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20f4bfd8162c8a22ed9b45f78d9034fc5723413d47eb4010b6918d97322aa44e
+  data.tar.gz: 171d64479ccb7cef9940e992cc43cbd5d1fd58728ed733eaaac77fde1eba8dda
+SHA512:
+  metadata.gz: 21c5f484f1f9abcfe3b63ad5092515163df873b311c7e86e4bce3ba6390316c5c9cf907200acffe71a6fc5ea58428c8634e385387b0a23b32638ed0819bae3df
+  data.tar.gz: a5762a84fe743b4858df0e7bc6b2daed24123e2861e30068f577c727f3d2b45343eabe9015779ae8f3739c687ce812da4e25a29bc648630486d72717e3203159

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 meganemura
+
+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,127 @@
+# archspec_diagram
+
+Draw an [Archspec](https://archspecrb.dev) `Archspec.rb` as a Mermaid flowchart: components as boxes, allowed and forbidden dependencies as arrows, the other rules as text inside the boxes. It reads the config the way `archspec check` does but never analyzes your code, so it is fast and needs no Rails boot.
+
+```sh
+gem install archspec_diagram
+```
+
+Requires Ruby 3.2 or later and archspec 1.1.x.
+
+## Usage
+
+```sh
+archspec_diagram                          # ./Archspec.rb -> Mermaid on stdout
+archspec_diagram path/to/app              # a directory works; uses its Archspec.rb
+archspec_diagram -f markdown -o ARCHITECTURE.md
+archspec_diagram -f html -o arch.html && open arch.html
+archspec_diagram --focus billing -d LR    # one component and its neighbours
+archspec_diagram --detail reasons         # names | rules (default) | reasons
+```
+
+Errors are one line on stderr, never a backtrace. Exit status is 0 on success, 1 for a config or I/O problem (`archspec_diagram: could not load Archspec.rb: undefined local variable or method 'modles'`), and 2 for a usage error (`archspec_diagram: unknown format: svg (expected mermaid, markdown or html)`).
+
+### Options
+
+| Option | Values | Default | Effect |
+| --- | --- | --- | --- |
+| `-f`, `--format` | `mermaid`, `markdown`, `html` | `mermaid` | `mermaid` is the bare diagram for pasting into GitHub, Notion or `mmdc`. `markdown` is a heading, a fenced block and a legend table. `html` is a standalone page that loads Mermaid 11.4.1 from jsdelivr. |
+| `-d`, `--direction` | `TB`, `BT`, `LR`, `RL` | `TB` | Layout direction. |
+| `--detail` | `names`, `rules`, `reasons` | `rules` | `names`: components and arrows. `rules`: plus selectors and rule lines. `reasons`: plus every `because:` text. |
+| `--focus` | a component name | none | Keep one component, every component it links to or from, and the project-wide rules. |
+| `-o`, `--output` | a file | stdout | Written to a temporary file and renamed, so a failed run leaves the previous diagram in place. |
+| `-v`, `--version`, `-h`, `--help` | | | |
+
+### From Ruby
+
+```ruby
+ArchspecDiagram.render("Archspec.rb", format: :markdown, direction: :LR, detail: :rules, focus: :billing)
+```
+
+`render` returns a String and raises `ArchspecDiagram::Error` (a subclass of `ArchSpec::Error`) with a one-line message for every user-caused failure: bad options, a missing, unreadable, broken or empty config, an unknown `focus`. A test that fails when a committed diagram is stale:
+
+```ruby
+assert_equal File.read("docs/architecture.mmd"), ArchspecDiagram.render("Archspec.rb")
+```
+
+Rendering is deterministic and follows declaration order, so an unchanged config produces an unchanged diagram.
+
+## What is drawn
+
+| In Archspec.rb | In the diagram |
+| --- | --- |
+| `component :x, in:, except:, namespace:, constants:, descendants_of:` | A box named `x` with its selectors as small text. Flat, never nested, because selectors overlap. |
+| `architecture :name` / `preset :name` | A labelled group around the components the call declared, plus a "project-wide" note for its project-wide rules. Two identical calls stay two groups. |
+| `can_only_use` | Green arrows to each allowed component and a "uses only: ..." line (or "uses no other component"). |
+| `cannot_use` | Red dashed arrows ending in a cross, labelled "cannot use". |
+| `can_only_be_used_by` | Thick blue arrows from each consumer, labelled "only consumer", and a "used only by: ..." line. When the same pair also has a `can_only_use` arrow, the two merge into one green arrow labelled "only consumer". |
+| `cannot_reference_constants` | A red hexagon per constant and a dashed red arrow to it, labelled "cannot reference". |
+| `must_be_empty` | A dashed, faded box with "must be empty". |
+| `no_cycles`, `method_names.matching(...)` without a component | A dashed "project rules" note (top level) or "project-wide" note (inside a preset group). |
+| `cannot_call`, `cannot_define`, `cannot_instantiate_and_invoke`, `cannot_reference_includers`, `must_implement`, `must_implement_one_of`, `public_api`, `method_names.matching(...)` on a component | One line of text in the component's box. |
+| `because:` | At `--detail reasons`, an italic line under the rule's text, or on the arrow for rules that only draw arrows. |
+| A component a rule names but nothing declares | A dashed box. |
+| Any rule object archspec_diagram does not know (`rule obj`) | A generic "rule <id>" line. |
+| `root`, `source`, `ignore`, `todo` | Not drawn. |
+
+The text of each rule lives in `lib/archspec_diagram/clauses.rb`, one decoder per archspec rule class; `test/rule_coverage_test.rb` fails when archspec ships a rule class without one. All Mermaid syntax (ids, escaping, arrows, styles) lives in `flowchart.rb`.
+
+## Example
+
+Rendered from `test/fixtures/kitchen_sink/Archspec.rb`, which uses every verb (`archspec_diagram test/fixtures/kitchen_sink`):
+
+```mermaid
+flowchart TB
+  subgraph g0["architecture :modular_monolith, components: {…}, allow: {…}, public: {…}"]
+    c0["<b>billing</b><br/><small>in: packs/billing/**/*.rb</small><br/>uses only: shared<br/>public API: packs/billing/app/public/**/*.rb; constants Billing::Api; namespace Billing::Public"]
+    c1["<b>catalog</b><br/><small>in: packs/catalog/**/*.rb</small><br/>uses only: shared"]
+    c2["<b>shared</b><br/><small>in: packs/shared/**/*.rb</small><br/>uses no other component<br/>used only by: billing, catalog, services"]
+    n_g0["<b>project-wide</b><br/>no cycles among: billing, catalog, shared"]:::note
+  end
+  c3["<b>my-engine</b><br/><small>in: engines/my-engine/**/*.rb</small>"]
+  c4["<b>controllers</b><br/><small>in: app/controllers/**/*.rb</small><br/>uses only: models, services"]
+  c5["<b>models</b><br/><small>in: app/models/**/*.rb</small><br/><small>except: app/models/legacy/**/*.rb</small><br/>cannot call find_by_sql on ActiveRecord::Base or its subclasses<br/>instance methods matching /\Awith_(?#lt;base#gt;.+)/: require without_%{base}<br/>class methods matching /\Aget_/: forbidden, except get_started"]
+  c6["<b>services</b><br/><small>in: app/services/**/*.rb</small><br/>cannot call render, redirect_to, params, session<br/>cannot call puts (bare calls only)<br/>cannot do Thing.new(...).call"]
+  c7["<b>records</b><br/><small>descendants of: ApplicationRecord</small><br/>cannot define call"]
+  c8["<b>commands</b><br/><small>namespace: Commands</small><br/>must implement #35;call (arity 1, keywords: actor)<br/>must implement one of .perform, .call"]
+  c9["<b>model_concerns</b><br/><small>in: app/models/concerns/**/*.rb</small><br/>cannot reference its includers"]
+  c10["<b>end</b><br/><small>in: app/end/**/*.rb</small><br/>must be empty"]:::empty
+  c11["<b>legacy</b><br/><small>constants: OldReport, OldExport</small><br/>instance methods matching /\Aold_(?#lt;x#gt;.+)/: require new_%{x} on models (class side)"]
+  c12["<b>ghost</b>"]:::undeclared
+  n_top["<b>project rules</b><br/>no cycles among: controllers, models, services"]:::note
+  subgraph g1["preset :ruby_conventions"]
+    n_g1["<b>project-wide</b><br/>instance methods matching /\A(get|set)_/: forbidden<br/>instance methods matching /\Ais_/: forbidden<br/>class methods matching /\A(get|set)_/: forbidden<br/>class methods matching /\Ais_/: forbidden"]:::note
+  end
+  k0{{"ActionController"}}:::constant
+  k1{{"ActionView"}}:::constant
+  c0 -->|"only consumer"| c2
+  c1 -->|"only consumer"| c2
+  c4 --> c5
+  c4 --> c6
+  c5 -.-x|"cannot use"| c4
+  c5 -.-x|"cannot reference"| k0
+  c5 -.-x|"cannot reference"| k1
+  c6 ==>|"only consumer"| c2
+  c11 -.-x|"cannot use"| c12
+  linkStyle 0,1,2,3 stroke:#2f9e44,stroke-width:2px
+  linkStyle 4,5,6,8 stroke:#e03131,stroke-width:1.5px,stroke-dasharray:5 4
+  linkStyle 7 stroke:#1971c2,stroke-width:2px
+  classDef note fill:none,stroke-dasharray:2 2
+  classDef empty stroke-dasharray:4 3,opacity:0.6
+  classDef undeclared stroke-dasharray:2 2,fill:none
+  classDef constant fill:none,stroke:#e03131,color:#e03131
+```
+
+## Development
+
+```sh
+ruby -Itest -e 'Dir["test/*_test.rb"].each { load _1 }'
+MMDC=path/to/mmdc ruby -Itest test/render_test.rb   # also checks the golden diagrams parse
+UPDATE_GOLDEN=1 ruby -Itest test/render_test.rb     # rewrite test/golden after an intended change
+```
+
+The golden diagrams in `test/golden` come from the Archspec.rb files of archspec itself, fizzy, mastodon, discourse and the rails_app fixture (vendored under `test/fixtures/upstream`), plus the kitchen sink.
+
+## License
+
+MIT.

data/exe/archspec_diagram

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+require_relative "../lib/archspec_diagram"
+exit ArchspecDiagram::CLI.start(ARGV)

data/lib/archspec_diagram/architecture.rb

@@ -0,0 +1,165 @@
+module ArchspecDiagram
+  class Architecture < Data.define(:title, :components, :clauses)
+    Origin = Data.define(:seq, :verb, :preset, :options) do
+      def label
+        args = options.map { |key, value| "#{key}: #{brief(value)}" }
+        ["#{verb} :#{preset}", *args].join(", ")
+      end
+
+      private
+
+      def brief(value)
+        case value
+        when Hash then "{…}"
+        when Array then "[…]"
+        when String, Symbol then value.inspect
+        else value.to_s
+        end
+      end
+    end
+
+    Component = Data.define(:name, :selectors, :origin, :declared)
+
+    Constant = Data.define(:name)
+
+    Link = Data.define(:from, :to, :kind)
+
+    Clause = Data.define(:subject, :summary, :links, :reason, :origin, :empty) do
+      def project_wide? = subject.nil?
+      def drawn_as_links_only? = summary.nil?
+    end
+
+    def self.load(path)
+      file = resolve(path)
+      source = read(file, path)
+      ledger = Ledger.new
+      definition = ArchSpec::Definition.new
+      definition.base_dir = File.dirname(file)
+      definition.extend(ArchSpec::DSL::Context)
+      definition.extend(ledger.tracking)
+      evaluate(definition, source, file, path)
+
+      clauses = definition.rules.map { Clauses.decode(_1, origin: ledger.rule_origin(_1)) }
+      components = definition.component_specs.to_h do |name, spec|
+        [name, Component.new(name:, selectors: selector_lines(spec), origin: ledger.component_origin(name), declared: true)]
+      end
+      add_undeclared(components, clauses)
+      new(title: File.basename(File.dirname(File.expand_path(file))), components:, clauses:)
+    end
+
+    def focus(name)
+      name = name.to_sym
+      unless components.key?(name)
+        raise Error, "unknown component #{name.inspect} (known: #{components.keys.join(', ')})"
+      end
+
+      links = clauses.flat_map(&:links)
+      keep = [name, *links.filter_map { _1.to if _1.from == name }, *links.filter_map { _1.from if _1.to == name }]
+        .grep(Symbol).uniq
+      kept_clauses = clauses.filter_map do |clause|
+        next clause if clause.project_wide?
+        next unless keep.include?(clause.subject)
+
+        inside = clause.links.select { keep.include?(_1.from) && (_1.to.is_a?(Constant) || keep.include?(_1.to)) }
+        next if inside.empty? && clause.drawn_as_links_only? && !clause.links.empty?
+
+        clause.with(links: inside)
+      end
+      with(components: components.slice(*keep), clauses: kept_clauses)
+    end
+
+    def self.resolve(path)
+      path = path.to_s
+      file = File.directory?(path) ? File.join(path, "Archspec.rb") : path
+      unless File.file?(file)
+        raise Error, "could not load #{path}: #{File.directory?(path) ? 'no Archspec.rb in that directory' : 'no such file'}"
+      end
+
+      file
+    end
+
+    def self.read(file, path)
+      File.read(file, encoding: "UTF-8")
+    rescue SystemCallError => e
+      raise Error, "could not load #{path}: #{SystemCallError.new(e.errno).message}"
+    end
+
+    def self.evaluate(definition, source, file, path)
+      definition.instance_eval(source, file)
+      return unless definition.component_specs.empty? && definition.rules.empty?
+
+      raise Error, "#{path} declares no components or rules"
+    rescue Error
+      raise
+    rescue ScriptError, StandardError => e
+      raise Error, "could not load #{path}: #{e.message.lines.map(&:strip).find { !_1.empty? } || e.class.name}"
+    end
+
+    def self.add_undeclared(components, clauses)
+      clauses.each do |clause|
+        names = [clause.subject, *clause.links.flat_map { [_1.from, _1.to] }].grep(Symbol)
+        names.each do |name|
+          components[name] ||= Component.new(name:, selectors: [], origin: clause.origin, declared: false)
+        end
+      end
+    end
+
+    def self.selector_lines(spec)
+      [
+        ["in", spec.file_patterns],
+        ["except", spec.exclude_patterns],
+        ["namespace", spec.namespaces],
+        ["constants", spec.constants],
+        ["descendants of", spec.ancestor_names]
+      ].reject { |_, values| values.empty? }.map { |label, values| "#{label}: #{values.join(', ')}" }
+    end
+
+    private_class_method :resolve, :read, :evaluate, :add_undeclared, :selector_lines
+
+    class Ledger
+      def initialize
+        @current = nil
+        @seq = 0
+        @rule_origins = {}.compare_by_identity
+        @component_origins = {}
+      end
+
+      # Both entry points need wrapping: Context aliases preset to the
+      # original architecture body, so overriding architecture alone misses
+      # `preset :ruby_conventions`.
+      def tracking
+        ledger = self
+        Module.new do
+          define_method(:architecture) do |name, **options|
+            ledger.within(:architecture, name, options) { super(name, **options) }
+          end
+          define_method(:preset) do |name, **options|
+            ledger.within(:preset, name, options) { super(name, **options) }
+          end
+          define_method(:add_rule) do |rule|
+            ledger.claim_rule(rule)
+            super(rule)
+          end
+          define_method(:add_component) do |spec|
+            ledger.claim_component(spec.name)
+            super(spec)
+          end
+        end
+      end
+
+      def within(verb, name, options)
+        outer = @current
+        @current = Origin.new(seq: @seq += 1, verb:, preset: name.to_sym, options:)
+        yield
+      ensure
+        @current = outer
+      end
+
+      def claim_rule(rule) = @rule_origins[rule] ||= @current
+      def claim_component(name) = @component_origins.key?(name) || (@component_origins[name] = @current)
+      def rule_origin(rule) = @rule_origins[rule]
+      def component_origin(name) = @component_origins[name]
+    end
+    private_constant :Ledger
+  end
+end

data/lib/archspec_diagram/clauses.rb

@@ -0,0 +1,101 @@
+module ArchspecDiagram
+  module Clauses
+    Link = Architecture::Link
+    Constant = Architecture::Constant
+
+    DECODERS = {
+      ArchSpec::Rules::AllowDependenciesRule => lambda do |rule|
+        {
+          subject: rule.source,
+          summary: rule.targets.empty? ? "uses no other component" : "uses only: #{list(rule.targets)}",
+          links: rule.targets.map { Link.new(from: rule.source, to: _1, kind: :allow) }
+        }
+      end,
+      ArchSpec::Rules::ForbidDependenciesRule => lambda do |rule|
+        { subject: rule.source, links: rule.targets.map { Link.new(from: rule.source, to: _1, kind: :forbid) } }
+      end,
+      ArchSpec::Rules::AllowedConsumersRule => lambda do |rule|
+        {
+          subject: rule.source,
+          summary: rule.consumers.empty? ? "used by no other component" : "used only by: #{list(rule.consumers)}",
+          links: rule.consumers.map { Link.new(from: _1, to: rule.source, kind: :consumer) }
+        }
+      end,
+      ArchSpec::Rules::CannotReferenceConstantsRule => lambda do |rule|
+        {
+          subject: rule.source,
+          links: rule.constants.map { Link.new(from: rule.source, to: Constant.new(_1), kind: :forbid_constant) }
+        }
+      end,
+      ArchSpec::Rules::NoCyclesRule => lambda do |rule|
+        { subject: nil, summary: rule.components.empty? ? "no cycles among all components" : "no cycles among: #{list(rule.components)}" }
+      end,
+      ArchSpec::Rules::MustBeEmptyRule => ->(rule) { { subject: rule.source, summary: "must be empty", empty: true } },
+      ArchSpec::Rules::ConcernIndependenceRule => ->(rule) { { subject: rule.source, summary: "cannot reference its includers" } },
+      ArchSpec::Rules::PublicApiRule => lambda do |rule|
+        parts = [
+          (list(rule.file_patterns) unless rule.file_patterns.empty?),
+          ("constants #{list(rule.constants)}" unless rule.constants.empty?),
+          ("namespace #{list(rule.namespaces)}" unless rule.namespaces.empty?)
+        ].compact
+        { subject: rule.source, summary: ["public API", parts.join("; ")].reject(&:empty?).join(": ") }
+      end,
+      ArchSpec::Rules::CannotCallRule => lambda do |rule|
+        receiver =
+          case rule.receiver
+          when :any then ""
+          when :none then " (bare calls only)"
+          else " on #{rule.receiver} or its subclasses"
+          end
+        { subject: rule.source, summary: "cannot call #{list(rule.method_names)}#{receiver}" }
+      end,
+      ArchSpec::Rules::MustImplementRule => lambda do |rule|
+        extras = []
+        extras << "arity #{rule.arity}" if rule.arity
+        extras << "keywords: #{list(rule.keywords)}" unless rule.keywords.empty?
+        summary = "must implement #{sigil(rule.scope)}#{rule.method_name}"
+        summary += " (#{extras.join(', ')})" unless extras.empty?
+        { subject: rule.source, summary: }
+      end,
+      ArchSpec::Rules::MustImplementOneOfRule => lambda do |rule|
+        names = rule.method_names.map { "#{sigil(rule.scope)}#{_1}" }
+        { subject: rule.source, summary: "must implement one of #{list(names)}" }
+      end,
+      ArchSpec::Rules::CannotDefineMethodRule => ->(rule) { { subject: rule.source, summary: "cannot define #{list(rule.method_names)}" } },
+      ArchSpec::Rules::CannotInstantiateAndInvokeRule => ->(rule) { { subject: rule.source, summary: "cannot do Thing.new(...).call" } },
+      ArchSpec::Rules::NamingRule => lambda do |rule|
+        constraint = rule.instance_variable_get(:@constraint)
+        phrase =
+          case constraint
+          when ArchSpec::Rules::Naming::Forbidden then "forbidden"
+          when ArchSpec::Rules::Naming::Requires
+            on = constraint.instance_variable_get(:@on)
+            side = constraint.instance_variable_get(:@target_scope) == :class ? " (class side)" : ""
+            "require #{constraint.instance_variable_get(:@template)}#{" on #{on}" if on}#{side}"
+          else constraint.respond_to?(:id) ? constraint.id : "naming rule"
+          end
+        except = rule.except.empty? ? "" : ", except #{list(rule.except)}"
+        {
+          subject: rule.source,
+          summary: "#{rule.scope} methods matching #{rule.selector.regex.inspect}: #{phrase}#{except}"
+        }
+      end
+    }.freeze
+
+    def self.decode(rule, origin:)
+      attrs = DECODERS.fetch(rule.class) { method(:custom) }.call(rule)
+      reason = rule.respond_to?(:archspec_because) ? rule.archspec_because : nil
+      Architecture::Clause.new(subject: nil, summary: nil, links: [], empty: false, **attrs, reason:, origin:)
+    end
+
+    def self.custom(rule)
+      {
+        subject: (rule.source.to_sym if rule.respond_to?(:source) && rule.source),
+        summary: "rule #{rule.respond_to?(:id) ? rule.id : rule.class.name}"
+      }
+    end
+
+    def self.list(names) = names.to_a.join(", ")
+    def self.sigil(scope) = scope == :class ? "." : "#"
+  end
+end

data/lib/archspec_diagram/cli.rb

@@ -0,0 +1,56 @@
+require "optparse"
+
+module ArchspecDiagram
+  # usage: archspec_diagram [options] [PATH]
+  # PATH is an Archspec.rb or a directory holding one (default ./Archspec.rb).
+  # Exit 0 on success, 1 for a config or I/O problem, 2 for a usage error.
+  # Every failure prints one line to stderr and never a backtrace.
+  module CLI
+    def self.start(argv, out: $stdout, err: $stderr)
+      options = {}
+      output = nil
+      parser = OptionParser.new do |o|
+        o.banner = "usage: archspec_diagram [options] [PATH]"
+        o.on("-f", "--format FORMAT", "mermaid (default), markdown, html") { options[:format] = _1 }
+        o.on("-d", "--direction DIR", "TB (default), BT, LR, RL") { options[:direction] = _1 }
+        o.on("--detail LEVEL", "names, rules (default), reasons") { options[:detail] = _1 }
+        o.on("--focus COMPONENT", "one component and its neighbours") { options[:focus] = _1 }
+        o.on("-o", "--output FILE", "write here instead of stdout") { output = _1 }
+        o.on("-v", "--version") { return out.puts(VERSION).then { 0 } }
+        o.on("-h", "--help") { return out.puts(o).then { 0 } }
+      end
+
+      paths = parser.parse(argv)
+      return usage_error(err, "expected one PATH") if paths.size > 1
+
+      begin
+        Options.new(**options)
+      rescue Error => e
+        return usage_error(err, e.message)
+      end
+
+      result = ArchspecDiagram.render(paths.first || "Archspec.rb", **options)
+      output ? write_atomically(output, result) : out.write(result)
+      0
+    rescue OptionParser::ParseError => e
+      usage_error(err, e.message)
+    rescue Error, SystemCallError => e
+      err.puts "archspec_diagram: #{e.message}"
+      1
+    end
+
+    def self.usage_error(err, message)
+      err.puts "archspec_diagram: #{message}"
+      2
+    end
+
+    def self.write_atomically(path, content)
+      temp = "#{path}.tmp-#{Process.pid}"
+      File.write(temp, content)
+      File.rename(temp, path)
+    ensure
+      File.delete(temp) if temp && File.exist?(temp)
+    end
+    private_class_method :usage_error, :write_atomically
+  end
+end

data/lib/archspec_diagram/document.rb

@@ -0,0 +1,69 @@
+require "cgi"
+
+module ArchspecDiagram
+  class Document
+    MERMAID_JS = "https://cdn.jsdelivr.net/npm/mermaid@11.4.1/dist/mermaid.esm.min.mjs"
+
+    def initialize(flowchart, options, title:)
+      @flowchart = flowchart
+      @options = options
+      @title = title
+    end
+
+    def to_s
+      case @options.format
+      when :mermaid then "#{diagram}\n"
+      when :markdown then markdown
+      when :html then html
+      end
+    end
+
+    private
+
+    def diagram = @flowchart.to_s
+
+    def markdown
+      fence = "`" * [3, longest_backtick_run + 1].max
+      lines = ["## #{@title.gsub(/\R/, ' ')} architecture", "", "#{fence}mermaid", diagram, fence]
+      unless legend.empty?
+        lines.push("", "| Arrow | Meaning |", "| --- | --- |")
+        lines.concat(legend.map { |look, meaning| "| #{look} | #{meaning} |" })
+      end
+      "#{lines.join("\n")}\n"
+    end
+
+    # Mermaid reads the element's textContent, so escaped tags come back as tags.
+    def html
+      items = legend.map { |look, meaning| "      <li><strong>#{CGI.escapeHTML(look)}</strong>: #{CGI.escapeHTML(meaning)}</li>" }
+      <<~HTML
+        <!doctype html>
+        <html lang="en">
+        <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <title>#{CGI.escapeHTML(@title)} architecture</title>
+          <style>
+            body { font-family: system-ui, sans-serif; margin: 2rem; }
+            ul { line-height: 1.6; }
+          </style>
+        </head>
+        <body>
+          <h1>#{CGI.escapeHTML(@title)} architecture</h1>
+          <pre class="mermaid">
+        #{CGI.escapeHTML(diagram)}
+          </pre>
+        #{items.empty? ? '' : "  <ul>\n#{items.join("\n")}\n  </ul>\n"}  <script type="module">
+            import mermaid from "#{MERMAID_JS}";
+            mermaid.initialize({ startOnLoad: false });
+            await mermaid.run();
+          </script>
+        </body>
+        </html>
+      HTML
+    end
+
+    def legend = @legend ||= @flowchart.legend
+
+    def longest_backtick_run = diagram.scan(/`+/).map(&:length).max || 0
+  end
+end

data/lib/archspec_diagram/flowchart.rb

@@ -0,0 +1,154 @@
+require "set"
+
+module ArchspecDiagram
+  class Flowchart
+    LINKS = {
+      allow:           { arrow: "-->", label: nil, style: "stroke:#2f9e44,stroke-width:2px",
+                         look: "green arrow",
+                         legend: "allowlist: the source may use only components it points to" },
+      consumer:        { arrow: "==>", label: "only consumer", style: "stroke:#1971c2,stroke-width:2px",
+                         look: "thick blue arrow",
+                         legend: "audience: only the sources pointing here may use the target" },
+      forbid:          { arrow: "-.-x", label: "cannot use", style: "stroke:#e03131,stroke-width:1.5px,stroke-dasharray:5 4",
+                         look: "dashed red arrow ending in a cross",
+                         legend: "the source must not use the target" },
+      forbid_constant: { arrow: "-.-x", label: "cannot reference", style: "stroke:#e03131,stroke-width:1.5px,stroke-dasharray:5 4",
+                         look: "dashed red arrow to a red hexagon",
+                         legend: "the source must not reference the constant" }
+    }.freeze
+
+    CLASS_DEFS = {
+      empty: "stroke-dasharray:4 3,opacity:0.6",
+      undeclared: "stroke-dasharray:2 2,fill:none",
+      constant: "fill:none,stroke:#e03131,color:#e03131",
+      note: "fill:none,stroke-dasharray:2 2"
+    }.freeze
+
+    Edge = Data.define(:from, :to, :kind, :label)
+    Constant = Architecture::Constant
+    private_constant :Edge, :Constant
+
+    def initialize(architecture, options)
+      @architecture = architecture
+      @options = options
+      @component_ids = architecture.components.keys.each_with_index.to_h { |name, index| [name, "c#{index}"] }
+      constants = architecture.clauses.flat_map(&:links).map(&:to).grep(Constant).uniq
+      @constant_ids = constants.each_with_index.to_h { |constant, index| [constant, "k#{index}"] }
+      @classes = Set.new
+    end
+
+    def to_s
+      @to_s ||= begin
+        edges = merged_edges
+        lines = ["flowchart #{@options.direction}"]
+        lines.concat(group_lines)
+        @classes << :constant unless @constant_ids.empty?
+        lines.concat(@constant_ids.map { |constant, id| "  #{id}{{\"#{text(constant.name)}\"}}:::constant" })
+        lines.concat(edges.map { edge_line(_1) })
+        lines.concat(link_style_lines(edges))
+        lines.concat(class_def_lines)
+        lines.join("\n")
+      end
+    end
+
+    def legend
+      present = @architecture.clauses.flat_map(&:links).map(&:kind).uniq
+      LINKS.slice(*present).values.map { [_1[:look], _1[:legend]] }
+    end
+
+    private
+
+    def group_lines
+      buckets = Hash.new { |hash, origin| hash[origin] = { components: [], notes: [] } }
+      @architecture.components.each_value { buckets[_1.origin][:components] << _1 }
+      @architecture.clauses.select(&:project_wide?).each { buckets[_1.origin][:notes] << _1 }
+
+      group_index = -1
+      buckets.flat_map do |origin, bucket|
+        group = "g#{group_index += 1}" if origin
+        notes = @options.detail_at_least?(:rules) ? bucket[:notes].reject(&:drawn_as_links_only?) : []
+        nodes = bucket[:components].map { |component| node(component) }
+        nodes << note_node(group, origin ? "project-wide" : "project rules", notes) unless notes.empty?
+        next [] if nodes.empty?
+        next nodes.map { "  #{_1}" } unless origin
+
+        ["  subgraph #{group}[\"#{text(origin.label)}\"]", *nodes.map { "    #{_1}" }, "  end"]
+      end
+    end
+
+    def node(component)
+      clauses = @architecture.clauses.select { _1.subject == component.name }
+      parts = ["<b>#{text(component.name)}</b>"]
+      if @options.detail_at_least?(:rules)
+        parts.concat(component.selectors.map { "<small>#{text(_1)}</small>" })
+        parts.concat(clauses.filter_map { clause_line(_1) })
+      end
+      klass = if !component.declared then :undeclared elsif clauses.any?(&:empty) then :empty end
+      @classes << klass if klass
+      "#{@component_ids.fetch(component.name)}[\"#{parts.join('<br/>')}\"]#{":::#{klass}" if klass}"
+    end
+
+    def note_node(group, title, clauses)
+      @classes << :note
+      parts = ["<b>#{title}</b>", *clauses.map { clause_line(_1) }]
+      "n_#{group || 'top'}[\"#{parts.join('<br/>')}\"]:::note"
+    end
+
+    def clause_line(clause)
+      return if clause.drawn_as_links_only?
+
+      line = text(clause.summary)
+      line += "<br/><i>because #{text(clause.reason)}</i>" if clause.reason && @options.detail_at_least?(:reasons)
+      line
+    end
+
+    def merged_edges
+      entries = @architecture.clauses.flat_map do |clause|
+        reason = clause.reason if clause.drawn_as_links_only? && @options.detail_at_least?(:reasons)
+        clause.links.map { |link| [link, reason] }
+      end
+
+      entries.group_by { |link, _| [link.from, link.to] }.flat_map do |(from, to), pair|
+        fold_consumer_into_allow(pair.group_by { |link, _| link.kind }).map do |kind, (group, base)|
+          reasons = group.filter_map(&:last).uniq.join("; ")
+          label = [base, (reasons unless reasons.empty?)].compact.join(": ")
+          Edge.new(from:, to:, kind:, label: label.empty? ? nil : label)
+        end
+      end
+    end
+
+    def fold_consumer_into_allow(by_kind)
+      consumer = by_kind.key?(:allow) && by_kind.delete(:consumer)
+      by_kind.to_h do |kind, group|
+        group += consumer if consumer && kind == :allow
+        base = consumer && kind == :allow ? LINKS.fetch(:consumer)[:label] : LINKS.fetch(kind)[:label]
+        [kind, [group, base]]
+      end
+    end
+
+    def edge_line(edge)
+      arrow = LINKS.fetch(edge.kind)[:arrow]
+      target = edge.to.is_a?(Constant) ? @constant_ids.fetch(edge.to) : @component_ids.fetch(edge.to)
+      label = "|\"#{text(edge.label)}\"|" if edge.label
+      "  #{@component_ids.fetch(edge.from)} #{arrow}#{label} #{target}"
+    end
+
+    def link_style_lines(edges)
+      edges.each_with_index.group_by { |edge, _| LINKS.fetch(edge.kind)[:style] }.map do |style, group|
+        "  linkStyle #{group.map(&:last).join(',')} #{style}"
+      end
+    end
+
+    def class_def_lines = CLASS_DEFS.slice(*@classes).map { |name, style| "  classDef #{name} #{style}" }
+
+    # Text inside ["…"] and edge labels: & < > " # ` become #amp; #lt; #gt;
+    # #quot; #35; #96;, and line breaks become a space. Backticks matter
+    # because a leading one turns the label into a Mermaid markdown string.
+    def text(string)
+      string.to_s.gsub(/\R/, " ").gsub(/[&<>"#`]/) { "##{ESCAPES.fetch(_1)};" }
+    end
+
+    ESCAPES = { "&" => "amp", "<" => "lt", ">" => "gt", '"' => "quot", "#" => "35", "`" => "96" }.freeze
+    private_constant :ESCAPES
+  end
+end

data/lib/archspec_diagram/version.rb

@@ -0,0 +1,3 @@
+module ArchspecDiagram
+  VERSION = "0.1.0"
+end

data/lib/archspec_diagram.rb

@@ -0,0 +1,57 @@
+require "archspec"
+require_relative "archspec_diagram/version"
+
+# The whole public surface: ArchspecDiagram.render, ArchspecDiagram::Error,
+# and ArchspecDiagram::CLI for the executable. Everything else is a private
+# constant, so callers cannot couple to the model or the Mermaid writer.
+module ArchspecDiagram
+  Error = Class.new(ArchSpec::Error)
+
+  class Options < Data.define(:format, :direction, :detail, :focus)
+    FORMATS = %i[mermaid markdown html].freeze
+    DIRECTIONS = %i[TB BT LR RL].freeze
+    DETAILS = %i[names rules reasons].freeze
+
+    def initialize(format: :mermaid, direction: :TB, detail: :rules, focus: nil)
+      super(
+        format: choose("format", format, FORMATS),
+        direction: choose("direction", direction, DIRECTIONS),
+        detail: choose("detail", detail, DETAILS),
+        focus: focus&.to_sym
+      )
+    end
+
+    def detail_at_least?(level) = DETAILS.index(detail) >= DETAILS.index(level)
+
+    private
+
+    def choose(label, value, allowed)
+      choice = allowed.find { _1.to_s.casecmp?(value.to_s) }
+      return choice if choice
+
+      expected = allowed.map(&:to_s)
+      raise Error, "unknown #{label}: #{value} (expected #{expected[..-2].join(', ')} or #{expected.last})"
+    end
+  end
+
+  # Reads the Archspec.rb at +path+ (or +path+/Archspec.rb for a directory)
+  # and returns the diagram as a String. Raises Error with a one-line message
+  # for every user-caused failure: bad options, unreadable or broken config,
+  # unknown focus component.
+  def self.render(path = "Archspec.rb", **options)
+    opts = Options.new(**options)
+    architecture = Architecture.load(path)
+    architecture = architecture.focus(opts.focus) if opts.focus
+    Document.new(Flowchart.new(architecture, opts), opts, title: architecture.title).to_s
+  end
+end
+
+require_relative "archspec_diagram/architecture"
+require_relative "archspec_diagram/clauses"
+require_relative "archspec_diagram/flowchart"
+require_relative "archspec_diagram/document"
+require_relative "archspec_diagram/cli"
+
+module ArchspecDiagram
+  private_constant :Options, :Architecture, :Clauses, :Flowchart, :Document
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: archspec_diagram
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- meganemura
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: archspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+executables:
+- archspec_diagram
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/archspec_diagram
+- lib/archspec_diagram.rb
+- lib/archspec_diagram/architecture.rb
+- lib/archspec_diagram/clauses.rb
+- lib/archspec_diagram/cli.rb
+- lib/archspec_diagram/document.rb
+- lib/archspec_diagram/flowchart.rb
+- lib/archspec_diagram/version.rb
+homepage: https://github.com/meganemura/archspec_diagram
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Draw an Archspec.rb as a Mermaid flowchart
+test_files: []