archspec 0.1.0.pre1

data/lib/archspec/architectures.rb

@@ -0,0 +1,196 @@
+module ArchSpec
+  module Architectures
+    extend self
+
+    DEFAULT_LAYERED = {
+      interface: "app/controllers/**/*.rb",
+      application: %w[app/services/**/*.rb app/jobs/**/*.rb app/mailers/**/*.rb],
+      domain: "app/models/**/*.rb"
+    }.freeze
+
+    DEFAULT_RAILS_MVC = {
+      controllers: "app/controllers/**/*.rb",
+      models: "app/models/**/*.rb",
+      helpers: "app/helpers/**/*.rb",
+      mailers: "app/mailers/**/*.rb",
+      jobs: "app/jobs/**/*.rb",
+      services: "app/services/**/*.rb"
+    }.freeze
+
+    DEFAULT_HEXAGONAL = {
+      application: %w[app/services/**/*.rb app/use_cases/**/*.rb],
+      domain: "app/domain/**/*.rb",
+      ports: "app/ports/**/*.rb",
+      adapters: %w[app/adapters/**/*.rb app/integrations/**/*.rb app/infrastructure/**/*.rb]
+    }.freeze
+
+    DEFAULT_CLEAN = {
+      frameworks: %w[app/controllers/**/*.rb app/jobs/**/*.rb app/mailers/**/*.rb],
+      interface_adapters: %w[app/adapters/**/*.rb app/presenters/**/*.rb app/serializers/**/*.rb],
+      use_cases: %w[app/use_cases/**/*.rb app/services/**/*.rb],
+      entities: %w[app/entities/**/*.rb app/domain/**/*.rb app/models/**/*.rb]
+    }.freeze
+
+    DEFAULT_CQRS = {
+      commands: "app/commands/**/*.rb",
+      queries: "app/queries/**/*.rb",
+      read_models: "app/read_models/**/*.rb"
+    }.freeze
+
+    DEFAULT_EVENT_DRIVEN = {
+      events: "app/events/**/*.rb",
+      publishers: "app/publishers/**/*.rb",
+      subscribers: "app/subscribers/**/*.rb"
+    }.freeze
+
+    CONTROLLER_METHODS = %i[render redirect_to params session cookies flash].freeze
+    MUTATING_METHODS = %i[
+      create create!
+      delete delete_all
+      destroy destroy!
+      insert insert!
+      save save!
+      update update! update_attribute update_attributes update_columns
+      upsert upsert!
+    ].freeze
+
+    def apply(name, dsl, **options)
+      case name.to_sym
+      when :rails_mvc, :rails_way
+        rails_mvc(dsl, components: options.fetch(:components, DEFAULT_RAILS_MVC))
+      when :layered
+        layered(dsl, layers: options.fetch(:layers, DEFAULT_LAYERED))
+      when :hexagonal
+        hexagonal(dsl, **with_defaults(DEFAULT_HEXAGONAL, options))
+      when :clean
+        clean(dsl, **with_defaults(DEFAULT_CLEAN, options))
+      when :modular_monolith, :bounded_contexts
+        modular_monolith(dsl, components: options.fetch(:components), allow: options.fetch(:allow, {}))
+      when :cqrs
+        cqrs(dsl, **with_defaults(DEFAULT_CQRS, options))
+      when :event_driven
+        event_driven(dsl, **with_defaults(DEFAULT_EVENT_DRIVEN, options))
+      else
+        raise Error, "Unknown ArchSpec architecture: #{name.inspect}"
+      end
+    end
+
+    def rails_mvc(dsl, components:)
+      components = normalize_map(components)
+      define_components(dsl, components)
+
+      proxy_for(dsl, :controllers).can_use(*components.keys & %i[models services helpers mailers jobs])
+      proxy_for(dsl, :models).cannot_use(*components.keys & %i[controllers helpers])
+      proxy_for(dsl, :services).cannot_use(*components.keys & %i[controllers helpers])
+      proxy_for(dsl, :models).cannot_call(*CONTROLLER_METHODS)
+      proxy_for(dsl, :services).cannot_call(*CONTROLLER_METHODS)
+    end
+
+    def layered(dsl, layers:)
+      ordered = normalize_map(layers)
+      define_components(dsl, ordered)
+      names = ordered.keys
+
+      names.each_with_index do |name, index|
+        allowed = names[(index + 1)..] || []
+        proxy_for(dsl, name).can_use(*allowed)
+      end
+
+      dsl.no_cycles!(among: names)
+    end
+
+    def hexagonal(dsl, application:, domain:, ports:, adapters:)
+      roles = normalize_map(
+        application: application,
+        domain: domain,
+        ports: ports,
+        adapters: adapters
+      )
+      define_components(dsl, roles)
+
+      proxy_for(dsl, :application).can_use :domain, :ports
+      proxy_for(dsl, :domain).cannot_use :adapters
+      proxy_for(dsl, :ports).cannot_use :adapters
+      proxy_for(dsl, :adapters).can_use :application, :domain, :ports
+      dsl.no_cycles!(among: roles.keys)
+    end
+
+    def clean(dsl, frameworks:, interface_adapters:, use_cases:, entities:)
+      layered(
+        dsl,
+        layers: {
+          frameworks: frameworks,
+          interface_adapters: interface_adapters,
+          use_cases: use_cases,
+          entities: entities
+        }
+      )
+    end
+
+    def modular_monolith(dsl, components:, allow: {})
+      components = normalize_map(components)
+      define_components(dsl, components)
+
+      components.each_key do |name|
+        allowed = Array(allow[name] || allow[name.to_s])
+        proxy_for(dsl, name).can_use(*allowed)
+      end
+
+      dsl.no_cycles!(among: components.keys)
+    end
+
+    def cqrs(dsl, commands:, queries:, read_models: nil, mutating_methods: MUTATING_METHODS)
+      components = normalize_map(commands: commands, queries: queries)
+      components[:read_models] = read_models if read_models
+      define_components(dsl, components)
+
+      proxy_for(dsl, :commands).cannot_use :queries
+      proxy_for(dsl, :queries).cannot_use :commands
+      proxy_for(dsl, :queries).cannot_call(*mutating_methods)
+      dsl.no_cycles!(among: components.keys)
+    end
+
+    def event_driven(dsl, events:, publishers:, subscribers:)
+      roles = normalize_map(events: events, publishers: publishers, subscribers: subscribers)
+      define_components(dsl, roles)
+
+      proxy_for(dsl, :events).cannot_use :publishers, :subscribers
+      proxy_for(dsl, :publishers).can_use :events
+      proxy_for(dsl, :subscribers).can_use :events
+      dsl.no_cycles!(among: roles.keys)
+    end
+
+    private
+
+    def with_defaults(defaults, options)
+      defaults.merge(options)
+    end
+
+    def normalize_map(map)
+      map.to_h.transform_keys(&:to_sym)
+    end
+
+    def define_components(dsl, components)
+      components.each do |name, selector|
+        define_component(dsl, name, selector)
+      end
+    end
+
+    def define_component(dsl, name, selector)
+      if selector.is_a?(Hash)
+        dsl.component(
+          name,
+          in: selector[:in] || selector[:files],
+          namespace: selector[:namespace],
+          constants: selector[:constants]
+        )
+      else
+        dsl.component(name, in: selector)
+      end
+    end
+
+    def proxy_for(dsl, name)
+      DSL::ComponentProxy.new(dsl, name)
+    end
+  end
+end

data/lib/archspec/baseline.rb

@@ -0,0 +1,50 @@
+require "set"
+require "yaml"
+
+module ArchSpec
+  class Baseline
+    def self.empty(root: nil)
+      new(Set.new, root: root)
+    end
+
+    def self.load(path, root:)
+      return empty(root: root) unless path && File.exist?(path)
+
+      document = YAML.safe_load_file(path, permitted_classes: [], aliases: false) || {}
+      ids = Array(document["violations"]).filter_map do |entry|
+        entry.is_a?(Hash) ? entry["id"] : entry
+      end
+
+      new(ids.to_set, root: root)
+    end
+
+    def self.write(path, diagnostics, root:)
+      payload = {
+        "violations" => diagnostics.map do |diagnostic|
+          {
+            "id" => diagnostic.fingerprint(root: root),
+            "rule" => diagnostic.rule,
+            "path" => diagnostic.location.relative_path(root),
+            "line" => diagnostic.location.line,
+            "message" => diagnostic.message
+          }
+        end
+      }
+
+      File.write(path, payload.to_yaml)
+    end
+
+    def initialize(ids, root:)
+      @ids = ids
+      @root = root
+    end
+
+    def include?(diagnostic)
+      ids.include?(diagnostic.fingerprint(root: root))
+    end
+
+    private
+
+    attr_reader :ids, :root
+  end
+end

data/lib/archspec/cli.rb

@@ -0,0 +1,213 @@
+require "optparse"
+
+module ArchSpec
+  module CLI
+    extend self
+
+    CONFIG_FILE = "Archspec.rb"
+    TEMPLATE = <<~RUBY
+      ArchSpec.define "Application architecture" do
+        root "."
+        preset :rails_way
+      end
+    RUBY
+
+    def run(argv, output: $stdout, error: $stderr)
+      argv = argv.dup
+      command = argv.shift || "check"
+
+      case command
+      when "init"
+        init(argv, output)
+      when "check"
+        check(argv, output)
+      when "explain"
+        explain(argv, output)
+      when "version", "--version", "-v"
+        output.puts ArchSpec::VERSION
+        0
+      else
+        error.puts "Unknown command: #{command}"
+        error.puts usage
+        64
+      end
+    rescue Error => exception
+      error.puts exception.message
+      1
+    end
+
+    private
+
+    def init(argv, output)
+      force = argv.delete("--force")
+      path = argv.shift || CONFIG_FILE
+
+      if File.exist?(path) && !force
+        raise Error, "#{path} already exists. Use --force to overwrite it."
+      end
+
+      File.write(path, TEMPLATE)
+      output.puts "Created #{path}"
+      0
+    end
+
+    def check(argv, output)
+      options = {
+        config: CONFIG_FILE,
+        format: "text",
+        update_baseline: false
+      }
+
+      parser = OptionParser.new do |parser|
+        parser.on("--config PATH") { |value| options[:config] = value }
+        parser.on("--format FORMAT") { |value| options[:format] = value }
+        parser.on("--update-baseline") { options[:update_baseline] = true }
+      end
+      parser.parse!(argv)
+
+      definition, root = load_definition(options[:config])
+      graph = Analyzer.analyze(definition, root: root)
+      baseline_path = baseline_path_for(definition, root)
+      baseline = options[:update_baseline] ? Baseline.empty(root: root) : Baseline.load(baseline_path, root: root)
+      diagnostics = Evaluator.evaluate(definition, graph, baseline: baseline)
+
+      if options[:update_baseline]
+        raise Error, "No baseline configured. Add `baseline \".archspec_todo.yml\"` to #{options[:config]}." unless baseline_path
+
+        Baseline.write(baseline_path, diagnostics, root: root)
+        output.puts "Updated #{Pathname(baseline_path).relative_path_from(Pathname(root))} with #{diagnostics.size} violations."
+        return 0
+      end
+
+      formatter_for(options[:format]).print(output, graph: graph, diagnostics: diagnostics)
+      diagnostics.empty? ? 0 : 1
+    end
+
+    def explain(argv, output)
+      options = { config: CONFIG_FILE }
+      parser = OptionParser.new do |parser|
+        parser.on("--config PATH") { |value| options[:config] = value }
+      end
+      parser.parse!(argv)
+
+      subject = argv.shift
+      raise Error, "Usage: archspec explain PATH_OR_CONSTANT" unless subject
+
+      definition, root = load_definition(options[:config])
+      graph = Analyzer.analyze(definition, root: root)
+      explain_subject(output, graph, subject)
+      0
+    end
+
+    def load_definition(config_path)
+      raise Error, "Missing #{config_path}. Run `archspec init` first." unless File.exist?(config_path)
+
+      ArchSpec.last_definition = nil
+      absolute_config = File.expand_path(config_path)
+      load absolute_config
+      definition = ArchSpec.last_definition
+      raise Error, "#{config_path} did not call ArchSpec.define." unless definition
+
+      [definition, definition.absolute_root(File.dirname(absolute_config))]
+    end
+
+    def baseline_path_for(definition, root)
+      return unless definition.baseline_path
+
+      File.expand_path(definition.baseline_path, root)
+    end
+
+    def formatter_for(name)
+      case name
+      when "text"
+        Formatters::Text
+      when "json"
+        Formatters::JSON
+      else
+        raise Error, "Unknown format: #{name.inspect}"
+      end
+    end
+
+    def explain_subject(output, graph, subject)
+      path = File.expand_path(subject, graph.root)
+
+      if graph.files.key?(path)
+        file = graph.files.fetch(path)
+        output.puts file.relative_path
+        output.puts "  expected constant: #{file.expected_constant || "(none)"}"
+        output.puts "  defined constants: #{graph.constants_for_path(path).map(&:name).join(", ")}"
+        output_parse_errors(output, file)
+        output_component_reasons(output, graph.component_assignment_reasons_for_path(path))
+        output_suppressions(output, file)
+        output.puts "  outgoing facts:"
+
+        graph.edges.select { |edge| edge.from_path == path }.each do |edge|
+          output.puts "    #{edge.type} #{edge.to} at #{edge.location.line}:#{edge.location.column}"
+        end
+      else
+        constants = graph.constants_named(subject)
+        raise Error, "No file or constant found for #{subject.inspect}" if constants.empty?
+
+        constants.each do |constant|
+          output.puts constant.name
+          output.puts "  kind: #{constant.kind}"
+          output.puts "  file: #{constant.location.relative_path(graph.root)}:#{constant.location.line}"
+          output_component_reasons(output, graph.component_assignment_reasons_for_constant(constant.name))
+          output.puts "  superclass: #{constant.superclass || "(none)"}"
+          output.puts "  instance methods: #{constant.instance_methods.to_a.sort.join(", ")}"
+          output.puts "  class methods: #{constant.class_methods.to_a.sort.join(", ")}"
+        end
+      end
+    end
+
+    def output_component_reasons(output, assignments)
+      if assignments.empty?
+        output.puts "  components: (none)"
+        return
+      end
+
+      output.puts "  components:"
+      assignments.sort_by { |name, _reasons| name.to_s }.each do |name, reasons|
+        output.puts "    #{name}: #{reasons.empty? ? "(no recorded reason)" : reasons.join("; ")}"
+      end
+    end
+
+    def output_suppressions(output, file)
+      return if file.suppressions.empty?
+
+      output.puts "  suppressions:"
+      file.suppressions.each do |suppression|
+        line_range =
+          if suppression.end_line == Float::INFINITY
+            "#{suppression.start_line}-EOF"
+          elsif suppression.start_line == suppression.end_line
+            suppression.start_line
+          else
+            "#{suppression.start_line}-#{suppression.end_line}"
+          end
+        rule = suppression.rule || "*"
+        reason = suppression.reason ? " -- #{suppression.reason}" : ""
+        output.puts "    #{rule} on line #{line_range}#{reason}"
+      end
+    end
+
+    def output_parse_errors(output, file)
+      return if file.parse_errors.empty?
+
+      output.puts "  parse errors:"
+      file.parse_errors.each do |parse_error|
+        output.puts "    #{parse_error.location.line}:#{parse_error.location.column} #{parse_error.message}"
+      end
+    end
+
+    def usage
+      <<~TEXT
+        Usage:
+          archspec init [PATH] [--force]
+          archspec check [--config PATH] [--format text|json] [--update-baseline]
+          archspec explain PATH_OR_CONSTANT [--config PATH]
+          archspec version
+      TEXT
+    end
+  end
+end

data/lib/archspec/component_spec.rb

@@ -0,0 +1,34 @@
+module ArchSpec
+  class ComponentSpec
+    attr_reader :name, :file_patterns, :namespaces, :constants
+
+    def initialize(name, files: [], namespace: nil, constants: nil)
+      @name = name.to_sym
+      @file_patterns = Array(files).compact.map(&:to_s)
+      @namespaces = Array(namespace).compact.map { |value| normalize_constant(value) }
+      @constants = Array(constants).compact.map { |value| normalize_constant(value) }
+    end
+
+    def merge!(other)
+      @file_patterns |= other.file_patterns
+      @namespaces |= other.namespaces
+      @constants |= other.constants
+      self
+    end
+
+    def matches_constant?(name)
+      normalized = normalize_constant(name)
+
+      constants.include?(normalized) ||
+        namespaces.any? do |namespace|
+          normalized == namespace || normalized.start_with?("#{namespace}::")
+        end
+    end
+
+    private
+
+    def normalize_constant(value)
+      value.to_s.sub(/\A::/, "")
+    end
+  end
+end

data/lib/archspec/definition.rb

@@ -0,0 +1,64 @@
+module ArchSpec
+  class Definition
+    DEFAULT_SOURCE_PATTERNS = [
+      "app/**/*.rb",
+      "lib/**/*.rb",
+      "packs/*/app/**/*.rb",
+      "engines/*/app/**/*.rb"
+    ].freeze
+
+    DEFAULT_IGNORE_PATTERNS = [
+      ".git/**/*",
+      ".bundle/**/*",
+      "node_modules/**/*",
+      "tmp/**/*",
+      "vendor/**/*"
+    ].freeze
+
+    attr_accessor :name, :root_path, :baseline_path
+    attr_reader :source_patterns, :ignore_patterns, :component_specs, :rules
+
+    def initialize(name)
+      @name = name
+      @root_path = "."
+      @baseline_path = nil
+      @source_patterns = []
+      @ignore_patterns = DEFAULT_IGNORE_PATTERNS.dup
+      @component_specs = {}
+      @rules = []
+    end
+
+    def add_source_patterns(patterns)
+      @source_patterns |= Array(patterns).flatten.compact.map(&:to_s)
+    end
+
+    def add_ignore_patterns(patterns)
+      @ignore_patterns |= Array(patterns).flatten.compact.map(&:to_s)
+    end
+
+    def add_component(spec)
+      if component_specs.key?(spec.name)
+        component_specs.fetch(spec.name).merge!(spec)
+      else
+        component_specs[spec.name] = spec
+      end
+    end
+
+    def component?(name)
+      component_specs.key?(name.to_sym)
+    end
+
+    def add_rule(rule)
+      rules << rule
+    end
+
+    def absolute_root(base_dir = Dir.pwd)
+      File.expand_path(root_path, base_dir)
+    end
+
+    def analysis_patterns
+      patterns = source_patterns.empty? ? DEFAULT_SOURCE_PATTERNS.dup : source_patterns.dup
+      patterns | component_specs.values.flat_map(&:file_patterns)
+    end
+  end
+end

data/lib/archspec/diagnostic.rb

@@ -0,0 +1,36 @@
+require "digest"
+
+module ArchSpec
+  class Diagnostic
+    attr_reader :rule, :message, :location, :evidence, :confidence
+
+    def initialize(rule:, message:, location:, evidence:, confidence: :high)
+      @rule = rule
+      @message = message
+      @location = location
+      @evidence = evidence
+      @confidence = confidence
+    end
+
+    def fingerprint(root: nil)
+      path = root ? location.relative_path(root) : location.path
+
+      Digest::SHA256.hexdigest(
+        [rule, message, path, location.line, evidence].join("\0")
+      )[0, 24]
+    end
+
+    def to_h(root:)
+      {
+        id: fingerprint(root: root),
+        rule: rule,
+        message: message,
+        path: location.relative_path(root),
+        line: location.line,
+        column: location.column,
+        evidence: evidence,
+        confidence: confidence.to_s
+      }
+    end
+  end
+end