archspec 0.1.0.pre1

data/lib/archspec/dsl.rb

@@ -0,0 +1,132 @@
+module ArchSpec
+  module DSL
+    module Context
+      def root(path = nil)
+        return root_path unless path
+
+        self.root_path = path.to_s
+      end
+
+      def source(*patterns)
+        add_source_patterns(patterns)
+      end
+
+      def ignore(*patterns)
+        add_ignore_patterns(patterns)
+      end
+
+      def baseline(path = ".archspec_todo.yml")
+        self.baseline_path = path.to_s
+      end
+
+      def component(name, in: nil, namespace: nil, constants: nil)
+        add_component(
+          ComponentSpec.new(name, files: binding.local_variable_get(:in), namespace: namespace, constants: constants)
+        )
+        ComponentProxy.new(self, name)
+      end
+
+      alias layer component
+      alias role component
+
+      def preset(name, **options)
+        Presets.apply(name, self, **options)
+      end
+
+      def architecture(name, **options)
+        Architectures.apply(name, self, **options)
+      end
+
+      def no_cycles!(among: nil)
+        add_rule(Rules::NoCyclesRule.new(among: among))
+      end
+
+      def verify_zeitwerk_names!
+        add_rule(Rules::ZeitwerkNamingRule.new)
+      end
+
+      def rule(rule)
+        add_rule(rule)
+      end
+
+      def method_missing(name, ...)
+        return ComponentProxy.new(self, name) if component?(name)
+
+        super
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        component?(name) || super
+      end
+    end
+
+    class ComponentProxy
+      attr_reader :definition, :name
+
+      def initialize(definition, name)
+        @definition = definition
+        @name = name.to_sym
+      end
+
+      def can_use(*targets)
+        add_rule(Rules::AllowDependenciesRule.new(name, targets))
+        self
+      end
+
+      alias only_depend_on can_use
+      alias must_only_depend_on can_use
+
+      def cannot_use(*targets)
+        add_rule(Rules::ForbidDependenciesRule.new(name, targets))
+        self
+      end
+
+      def cannot_call(*methods)
+        add_rule(Rules::CannotCallRule.new(name, methods))
+        self
+      end
+
+      def cannot_define(*methods)
+        add_rule(Rules::CannotDefineMethodRule.new(name, methods))
+        self
+      end
+
+      def cannot_instantiate_and_invoke
+        add_rule(Rules::CannotInstantiateAndInvokeRule.new(name))
+        self
+      end
+
+      def cannot_reference_constants(*constants)
+        add_rule(Rules::CannotReferenceConstantsRule.new(name, constants))
+        self
+      end
+
+      def must_implement(*methods)
+        methods.each do |method_name|
+          add_rule(Rules::MustImplementRule.new(name, method_name))
+        end
+        self
+      end
+
+      def must_implement_one_of(*methods)
+        add_rule(Rules::MustImplementOneOfRule.new(name, methods))
+        self
+      end
+
+      private
+
+      def add_rule(rule)
+        if rule.respond_to?(:merge_key)
+          existing = definition.rules.find do |candidate|
+            candidate.respond_to?(:merge_key) && candidate.merge_key == rule.merge_key
+          end
+
+          return existing.merge!(rule) if existing&.respond_to?(:merge!)
+          return existing if existing
+        end
+
+        definition.add_rule(rule)
+      end
+    end
+  end
+end

data/lib/archspec/evaluator.rb

@@ -0,0 +1,28 @@
+module ArchSpec
+  module Evaluator
+    extend self
+
+    def evaluate(definition, graph, baseline: Baseline.empty)
+      (parser_diagnostics(graph) + definition.rules.flat_map { |rule| rule.evaluate(graph) })
+        .reject { |diagnostic| graph.suppressed?(diagnostic) }
+        .reject { |diagnostic| baseline.include?(diagnostic) }
+        .sort_by { |diagnostic| [diagnostic.location.path, diagnostic.location.line, diagnostic.rule, diagnostic.message] }
+    end
+
+    private
+
+    def parser_diagnostics(graph)
+      graph.files.values.flat_map do |file|
+        file.parse_errors.map do |parse_error|
+          Diagnostic.new(
+            rule: "parser.syntax",
+            message: parse_error.message,
+            location: parse_error.location,
+            evidence: file.relative_path,
+            confidence: :high
+          )
+        end
+      end
+    end
+  end
+end

data/lib/archspec/formatters/json.rb

@@ -0,0 +1,18 @@
+require "json"
+
+module ArchSpec
+  module Formatters
+    module JSON
+      extend self
+
+      def print(output = $stdout, graph:, diagnostics:)
+        output.puts ::JSON.pretty_generate(
+          files: graph.files.size,
+          constants: graph.constants.size,
+          facts: graph.edges.size,
+          violations: diagnostics.map { |diagnostic| diagnostic.to_h(root: graph.root) }
+        )
+      end
+    end
+  end
+end

data/lib/archspec/formatters/text.rb

@@ -0,0 +1,26 @@
+module ArchSpec
+  module Formatters
+    module Text
+      extend self
+
+      def print(output = $stdout, graph:, diagnostics:)
+        if diagnostics.empty?
+          output.puts "ArchSpec passed: #{graph.files.size} files, #{graph.constants.size} constants, #{graph.edges.size} facts checked."
+          return
+        end
+
+        output.puts "#{diagnostics.size} architecture #{diagnostics.size == 1 ? "violation" : "violations"}"
+        output.puts
+
+        diagnostics.each do |diagnostic|
+          output.puts "[#{diagnostic.rule}] #{diagnostic.location.relative_path(graph.root)}:#{diagnostic.location.line}:#{diagnostic.location.column}"
+          output.puts "  #{diagnostic.message}"
+          output.puts "  evidence: #{diagnostic.evidence}"
+          output.puts "  confidence: #{diagnostic.confidence}"
+          output.puts "  id: #{diagnostic.fingerprint(root: graph.root)}"
+          output.puts
+        end
+      end
+    end
+  end
+end

data/lib/archspec/model.rb

@@ -0,0 +1,278 @@
+require "pathname"
+require "set"
+
+module ArchSpec
+  ParseError = Data.define(:message, :location)
+  MethodDefinition = Data.define(:owner, :name, :scope, :location)
+
+  Suppression = Data.define(:rule, :start_line, :end_line, :reason) do
+    def matches?(diagnostic)
+      (rule.nil? || rule == diagnostic.rule) &&
+        diagnostic.location.line >= start_line &&
+        diagnostic.location.line <= end_line
+    end
+  end
+
+  class SourceFile
+    attr_reader :path, :relative_path, :expected_constant, :parse_errors, :suppressions
+
+    def initialize(root:, path:, expected_constant:, parse_errors:, suppressions:)
+      @path = path
+      @relative_path = Pathname(path).relative_path_from(Pathname(root)).to_s
+      @expected_constant = expected_constant
+      @parse_errors = parse_errors
+      @suppressions = suppressions
+    end
+  end
+
+  class ConstantNode
+    attr_reader :name, :kind, :path, :location, :instance_methods, :class_methods, :method_definitions, :mixins
+    attr_accessor :superclass
+
+    def initialize(name:, kind:, path:, location:)
+      @name = name
+      @kind = kind
+      @path = path
+      @location = location
+      @instance_methods = Set.new
+      @class_methods = Set.new
+      @method_definitions = []
+      @mixins = {
+        include: Set.new,
+        prepend: Set.new,
+        extend: Set.new
+      }
+    end
+
+    def class?
+      kind == :class
+    end
+
+    def module?
+      kind == :module
+    end
+
+    def add_instance_method(name, location:)
+      instance_methods.add(name.to_sym)
+      method_definitions << MethodDefinition.new(self.name, name.to_sym, :instance, location)
+    end
+
+    def add_class_method(name, location:)
+      class_methods.add(name.to_sym)
+      method_definitions << MethodDefinition.new(self.name, name.to_sym, :class, location)
+    end
+
+    def add_mixin(kind, name)
+      mixins.fetch(kind).add(name)
+    end
+  end
+
+  Edge = Data.define(:type, :from_path, :from_constant, :to, :location, :confidence)
+
+  class Component
+    attr_reader :name, :files, :constants, :file_reasons, :constant_reasons
+
+    def initialize(name)
+      @name = name.to_sym
+      @files = Set.new
+      @constants = Set.new
+      @file_reasons = Hash.new { |hash, key| hash[key] = Set.new }
+      @constant_reasons = Hash.new { |hash, key| hash[key] = Set.new }
+    end
+
+    def add_file(path, reason: nil)
+      files.add(path)
+      file_reasons[path].add(reason) if reason
+    end
+
+    def add_constant(name, reason: nil)
+      constants.add(name)
+      constant_reasons[name].add(reason) if reason
+    end
+  end
+
+  class Graph
+    DEPENDENCY_EDGE_TYPES = %i[
+      references_constant
+      inherits_from
+      includes
+      prepends
+      extends
+    ].freeze
+
+    attr_reader :root, :files, :constants, :edges, :components
+
+    def initialize(root)
+      @root = File.expand_path(root)
+      @files = {}
+      @constants = []
+      @constants_by_name = Hash.new { |hash, key| hash[key] = [] }
+      @edges = []
+      @components = {}
+    end
+
+    def add_file(path:, expected_constant:, parse_errors:, suppressions: [])
+      files[path] = SourceFile.new(
+        root: root,
+        path: path,
+        expected_constant: expected_constant,
+        parse_errors: parse_errors,
+        suppressions: suppressions
+      )
+    end
+
+    def add_constant(name:, kind:, path:, location:)
+      normalized = normalize_constant(name)
+      existing = @constants_by_name[normalized].find { |constant| constant.path == path && constant.kind == kind }
+      return existing if existing
+
+      constant = ConstantNode.new(name: normalized, kind: kind, path: path, location: location)
+      constants << constant
+      @constants_by_name[normalized] << constant
+      constant
+    end
+
+    def add_edge(type:, from_path:, from_constant:, to:, location:, confidence: :high)
+      edges << Edge.new(type, from_path, from_constant, normalize_constant(to), location, confidence)
+    end
+
+    def constants_named(name)
+      @constants_by_name[normalize_constant(name)]
+    end
+
+    def constants_for_path(path)
+      constants.select { |constant| constant.path == path }
+    end
+
+    def method_definitions_for_component(name)
+      component = components.fetch(name.to_sym)
+      component.constants.flat_map { |constant_name| constants_named(constant_name) }.flat_map(&:method_definitions)
+    rescue KeyError
+      []
+    end
+
+    def assign_components(component_specs)
+      @components = {}
+
+      component_specs.each do |spec|
+        component = Component.new(spec.name)
+
+        spec.file_patterns.each do |pattern|
+          each_matching_file(pattern) { |path| component.add_file(path, reason: "matched file pattern #{pattern}") }
+        end
+
+        constants.each do |constant|
+          matched_file = component.files.include?(constant.path)
+          matched_constant = spec.matches_constant?(constant.name)
+          next unless matched_file || matched_constant
+
+          component.add_file(constant.path, reason: "defines #{constant.name}") if matched_constant
+          component.add_constant(constant.name, reason: matched_file ? "defined in matched file" : "matched namespace/constant selector")
+        end
+
+        @components[component.name] = component
+      end
+    end
+
+    def component_names_for_path(path)
+      components.values.each_with_object(Set.new) do |component, names|
+        names.add(component.name) if component.files.include?(path)
+      end
+    end
+
+    def component_names_for_constant(name)
+      normalized = normalize_constant(name)
+
+      components.values.each_with_object(Set.new) do |component, names|
+        names.add(component.name) if component.constants.include?(normalized)
+      end
+    end
+
+    def dependency_edges
+      edges.select { |edge| DEPENDENCY_EDGE_TYPES.include?(edge.type) }
+    end
+
+    def target_components_for(edge)
+      return Set.new unless DEPENDENCY_EDGE_TYPES.include?(edge.type)
+
+      resolved = resolve_constant_reference(edge.to, edge.from_constant)
+      constants_named(resolved).each_with_object(Set.new) do |constant, names|
+        names.merge(component_names_for_path(constant.path))
+        names.merge(component_names_for_constant(constant.name))
+      end
+    end
+
+    def resolve_constant_reference(name, from_constant)
+      normalized = normalize_constant(name)
+      candidates = []
+
+      if from_constant
+        namespace = normalize_constant(from_constant).split("::")
+        namespace.pop
+
+        until namespace.empty?
+          candidates << "#{namespace.join("::")}::#{normalized}"
+          namespace.pop
+        end
+      end
+
+      candidates << normalized
+      candidates.find { |candidate| constants_named(candidate).any? } || normalized
+    end
+
+    def component_dependency_pairs(only: nil)
+      allowed_sources = Array(only).compact.map(&:to_sym).to_set
+      pairs = Set.new
+
+      dependency_edges.each do |edge|
+        source_components = component_names_for_path(edge.from_path)
+        source_components &= allowed_sources unless allowed_sources.empty?
+        next if source_components.empty?
+
+        target_components_for(edge).each do |target|
+          source_components.each do |source|
+            pairs.add([source, target]) unless source == target
+          end
+        end
+      end
+
+      pairs
+    end
+
+    def component_assignment_reasons_for_path(path)
+      components.values.each_with_object({}) do |component, reasons|
+        next unless component.files.include?(path)
+
+        reasons[component.name] = component.file_reasons[path].to_a.sort
+      end
+    end
+
+    def component_assignment_reasons_for_constant(name)
+      normalized = normalize_constant(name)
+
+      components.values.each_with_object({}) do |component, reasons|
+        next unless component.constants.include?(normalized)
+
+        reasons[component.name] = component.constant_reasons[normalized].to_a.sort
+      end
+    end
+
+    def suppressed?(diagnostic)
+      files[diagnostic.location.path]&.suppressions&.any? { |suppression| suppression.matches?(diagnostic) }
+    end
+
+    private
+
+    def each_matching_file(pattern)
+      glob = File.absolute_path(pattern, root)
+      Dir.glob(glob).sort.each do |path|
+        expanded = File.expand_path(path)
+        yield expanded if files.key?(expanded)
+      end
+    end
+
+    def normalize_constant(value)
+      value.to_s.sub(/\A::/, "")
+    end
+  end
+end

data/lib/archspec/presets.rb

@@ -0,0 +1,56 @@
+module ArchSpec
+  module Presets
+    module_function
+
+    def apply(name, dsl, **options)
+      case name.to_sym
+      when :rails_way, :rails_mvc
+        rails_way(dsl, **options)
+      when :rails_strict
+        rails_strict(dsl, **options)
+      when :rails_layered
+        rails_layered(dsl, **options)
+      when :rails_hexagonal
+        rails_hexagonal(dsl, **options)
+      when :rails_clean
+        rails_clean(dsl, **options)
+      when :rails_cqrs
+        rails_cqrs(dsl, **options)
+      when :rails_event_driven
+        rails_event_driven(dsl, **options)
+      else
+        raise Error, "Unknown ArchSpec preset: #{name.inspect}"
+      end
+    end
+
+    def rails_way(dsl, **options)
+      Architectures.apply(:rails_mvc, dsl, **options)
+    end
+
+    def rails_strict(dsl, **options)
+      rails_way(dsl, **options)
+      dsl.verify_zeitwerk_names!
+      dsl.no_cycles!(among: %i[controllers models helpers mailers jobs services])
+    end
+
+    def rails_layered(dsl, **options)
+      Architectures.apply(:layered, dsl, **options)
+    end
+
+    def rails_hexagonal(dsl, **options)
+      Architectures.apply(:hexagonal, dsl, **options)
+    end
+
+    def rails_clean(dsl, **options)
+      Architectures.apply(:clean, dsl, **options)
+    end
+
+    def rails_cqrs(dsl, **options)
+      Architectures.apply(:cqrs, dsl, **options)
+    end
+
+    def rails_event_driven(dsl, **options)
+      Architectures.apply(:event_driven, dsl, **options)
+    end
+  end
+end

data/lib/archspec/rules/cycle_rule.rb

@@ -0,0 +1,79 @@
+module ArchSpec
+  module Rules
+    class NoCyclesRule
+      attr_reader :components
+
+      def initialize(among: nil)
+        @components = Array(among).compact.map(&:to_sym)
+      end
+
+      def id
+        "dependencies.no_cycles"
+      end
+
+      def evaluate(graph)
+        cycles(graph).map do |cycle|
+          location = first_location_for_cycle(graph, cycle) || SourceLocation.new(graph.root, 1, 1)
+          Diagnostic.new(
+            rule: id,
+            message: "component dependency cycle: #{cycle.join(" -> ")}",
+            location: location,
+            evidence: cycle.join(" -> ")
+          )
+        end
+      end
+
+      private
+
+      def cycles(graph)
+        adjacency = Hash.new { |hash, key| hash[key] = Set.new }
+        graph.component_dependency_pairs(only: components).each do |source, target|
+          next if source == target
+
+          adjacency[source].add(target)
+        end
+
+        found = Set.new
+        result = []
+
+        adjacency.keys.each do |start|
+          walk(adjacency, start, start, [], found, result)
+        end
+
+        result
+      end
+
+      def walk(adjacency, start, node, path, found, result)
+        next_path = path + [node]
+
+        adjacency[node].each do |target|
+          if target == start
+            cycle = canonical_cycle(next_path + [start])
+            key = cycle.join("\0")
+            next if found.include?(key)
+
+            found.add(key)
+            result << cycle
+          elsif !path.include?(target)
+            walk(adjacency, start, target, next_path, found, result)
+          end
+        end
+      end
+
+      def canonical_cycle(cycle)
+        body = cycle[0...-1]
+        rotations = body.each_index.map { |index| body.rotate(index) }
+        canonical = rotations.min_by { |rotation| rotation.map(&:to_s) }
+        canonical + [canonical.first]
+      end
+
+      def first_location_for_cycle(graph, cycle)
+        source, target = cycle
+        graph.dependency_edges.find do |edge|
+          graph.component_names_for_path(edge.from_path).include?(source) &&
+            graph.target_components_for(edge).include?(target)
+        end&.location
+      end
+    end
+  end
+end