archspec 0.1.0.pre1

data/lib/archspec/rules/dependency_rules.rb

@@ -0,0 +1,117 @@
+require "set"
+
+module ArchSpec
+  module Rules
+    class DependencyRule
+      attr_reader :source, :targets
+
+      def initialize(source, targets)
+        @source = source.to_sym
+        @targets = Array(targets).flatten.map(&:to_sym).to_set
+      end
+
+      def merge_key
+        [self.class, source]
+      end
+
+      def merge!(other)
+        targets.merge(other.targets)
+        self
+      end
+
+      private
+
+      def relevant_edges(graph)
+        graph.dependency_edges.select { |edge| graph.component_names_for_path(edge.from_path).include?(source) }
+      end
+
+      def target_components(graph, edge)
+        graph.target_components_for(edge)
+      end
+
+      def edge_target(edge)
+        edge.to
+      end
+    end
+
+    class AllowDependenciesRule < DependencyRule
+      def id
+        "dependencies.allow"
+      end
+
+      def evaluate(graph)
+        relevant_edges(graph).flat_map do |edge|
+          target_components(graph, edge).filter_map do |target|
+            next if target == source || targets.include?(target)
+
+            Diagnostic.new(
+              rule: id,
+              message: "#{source} may not depend on #{target}",
+              location: edge.location,
+              evidence: "#{edge.from_constant || edge.from_path} #{edge.type} #{edge_target(edge)}"
+            )
+          end
+        end
+      end
+    end
+
+    class ForbidDependenciesRule < DependencyRule
+      def id
+        "dependencies.forbid"
+      end
+
+      def evaluate(graph)
+        relevant_edges(graph).flat_map do |edge|
+          forbidden = target_components(graph, edge) & targets
+
+          forbidden.map do |target|
+            Diagnostic.new(
+              rule: id,
+              message: "#{source} must not depend on #{target}",
+              location: edge.location,
+              evidence: "#{edge.from_constant || edge.from_path} #{edge.type} #{edge_target(edge)}"
+            )
+          end
+        end
+      end
+    end
+
+    class CannotReferenceConstantsRule
+      attr_reader :source, :constants
+
+      def initialize(source, constants)
+        @source = source.to_sym
+        @constants = Array(constants).flatten.map { |constant| constant.to_s.sub(/\A::/, "") }
+      end
+
+      def merge_key
+        [self.class, source]
+      end
+
+      def merge!(other)
+        @constants |= other.constants
+        self
+      end
+
+      def id
+        "constants.forbid"
+      end
+
+      def evaluate(graph)
+        graph.dependency_edges.filter_map do |edge|
+          next unless graph.component_names_for_path(edge.from_path).include?(source)
+
+          referenced = graph.resolve_constant_reference(edge.to, edge.from_constant)
+          next unless constants.any? { |constant| referenced == constant || referenced.start_with?("#{constant}::") }
+
+          Diagnostic.new(
+            rule: id,
+            message: "#{source} must not reference #{referenced}",
+            location: edge.location,
+            evidence: "#{edge.from_constant || edge.from_path} #{edge.type} #{edge.to}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/archspec/rules/protocol_rules.rb

@@ -0,0 +1,186 @@
+module ArchSpec
+  module Rules
+    class CannotCallRule
+      attr_reader :source, :method_names
+
+      def initialize(source, methods)
+        @source = source.to_sym
+        @method_names = Array(methods).flatten.map(&:to_sym)
+      end
+
+      def merge_key
+        [self.class, source]
+      end
+
+      def merge!(other)
+        @method_names |= other.method_names
+        self
+      end
+
+      def id
+        "methods.forbid"
+      end
+
+      def evaluate(graph)
+        graph.edges.filter_map do |edge|
+          next unless edge.type == :calls_named_method
+          next unless method_names.include?(edge.to.to_sym)
+          next unless graph.component_names_for_path(edge.from_path).include?(source)
+
+          Diagnostic.new(
+            rule: id,
+            message: "#{source} must not call ##{edge.to}",
+            location: edge.location,
+            evidence: "#{edge.from_constant || edge.from_path} calls #{edge.to}"
+          )
+        end
+      end
+    end
+
+    class MustImplementRule
+      attr_reader :source, :method_name
+
+      def initialize(source, method_name)
+        @source = source.to_sym
+        @method_name = method_name.to_sym
+      end
+
+      def merge_key
+        [self.class, source, method_name]
+      end
+
+      def id
+        "protocol.must_implement"
+      end
+
+      def evaluate(graph)
+        constants_for(graph).filter_map do |constant|
+          next if constant.instance_methods.include?(method_name)
+
+          Diagnostic.new(
+            rule: id,
+            message: "#{constant.name} must implement ##{method_name}",
+            location: constant.location,
+            evidence: "#{constant.name} methods: #{constant.instance_methods.to_a.sort.join(", ")}"
+          )
+        end
+      end
+
+      private
+
+      def constants_for(graph)
+        graph.components.fetch(source).constants.flat_map { |name| graph.constants_named(name) }.select(&:class?)
+      rescue KeyError
+        []
+      end
+    end
+
+    class MustImplementOneOfRule
+      attr_reader :source, :method_names
+
+      def initialize(source, method_names)
+        @source = source.to_sym
+        @method_names = Array(method_names).flatten.map(&:to_sym)
+      end
+
+      def merge_key
+        [self.class, source]
+      end
+
+      def merge!(other)
+        @method_names |= other.method_names
+        self
+      end
+
+      def id
+        "protocol.must_implement_one_of"
+      end
+
+      def evaluate(graph)
+        constants_for(graph).filter_map do |constant|
+          next if method_names.any? { |method_name| constant.instance_methods.include?(method_name) }
+
+          Diagnostic.new(
+            rule: id,
+            message: "#{constant.name} must implement one of #{method_names.map { |name| "##{name}" }.join(", ")}",
+            location: constant.location,
+            evidence: "#{constant.name} methods: #{constant.instance_methods.to_a.sort.join(", ")}"
+          )
+        end
+      end
+
+      private
+
+      def constants_for(graph)
+        graph.components.fetch(source).constants.flat_map { |name| graph.constants_named(name) }.select(&:class?)
+      rescue KeyError
+        []
+      end
+    end
+
+    class CannotDefineMethodRule
+      attr_reader :source, :method_names
+
+      def initialize(source, methods)
+        @source = source.to_sym
+        @method_names = Array(methods).flatten.map(&:to_sym)
+      end
+
+      def merge_key
+        [self.class, source]
+      end
+
+      def merge!(other)
+        @method_names |= other.method_names
+        self
+      end
+
+      def id
+        "methods.define_forbid"
+      end
+
+      def evaluate(graph)
+        graph.method_definitions_for_component(source).filter_map do |method_definition|
+          next unless method_names.include?(method_definition.name)
+
+          Diagnostic.new(
+            rule: id,
+            message: "#{source} must not define ##{method_definition.name}",
+            location: method_definition.location,
+            evidence: "#{method_definition.owner} defines #{method_definition.scope} method #{method_definition.name}"
+          )
+        end
+      end
+    end
+
+    class CannotInstantiateAndInvokeRule
+      attr_reader :source
+
+      def initialize(source)
+        @source = source.to_sym
+      end
+
+      def merge_key
+        [self.class, source]
+      end
+
+      def id
+        "objects.instantiate_and_invoke_forbid"
+      end
+
+      def evaluate(graph)
+        graph.edges.filter_map do |edge|
+          next unless edge.type == :instantiates_and_invokes
+          next unless graph.component_names_for_path(edge.from_path).include?(source)
+
+          Diagnostic.new(
+            rule: id,
+            message: "#{source} must not instantiate and immediately invoke #{edge.to}",
+            location: edge.location,
+            evidence: "#{edge.from_constant || edge.from_path} uses #{edge.to}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/archspec/rules/zeitwerk_rule.rb

@@ -0,0 +1,25 @@
+module ArchSpec
+  module Rules
+    class ZeitwerkNamingRule
+      def id
+        "zeitwerk.naming"
+      end
+
+      def evaluate(graph)
+        graph.files.values.filter_map do |file|
+          next unless file.expected_constant
+
+          defined = graph.constants_for_path(file.path).map(&:name)
+          next if defined.include?(file.expected_constant)
+
+          Diagnostic.new(
+            rule: id,
+            message: "#{file.relative_path} should define #{file.expected_constant}",
+            location: SourceLocation.new(file.path, 1, 1),
+            evidence: "defined constants: #{defined.empty? ? "(none)" : defined.join(", ")}"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/archspec/source_location.rb

@@ -0,0 +1,15 @@
+require "pathname"
+
+module ArchSpec
+  SourceLocation = Data.define(:path, :line, :column) do
+    def self.from_prism(path, location)
+      new(path, location.start_line, location.start_column + 1)
+    end
+
+    def relative_path(root)
+      Pathname(path).relative_path_from(Pathname(root)).to_s
+    rescue ArgumentError
+      path
+    end
+  end
+end

data/lib/archspec/version.rb

@@ -0,0 +1,3 @@
+module ArchSpec
+  VERSION = "0.1.0.pre1"
+end

data/lib/archspec.rb

@@ -0,0 +1,34 @@
+require_relative "archspec/version"
+require_relative "archspec/source_location"
+require_relative "archspec/diagnostic"
+require_relative "archspec/component_spec"
+require_relative "archspec/model"
+require_relative "archspec/definition"
+require_relative "archspec/baseline"
+require_relative "archspec/dsl"
+require_relative "archspec/analyzer"
+require_relative "archspec/evaluator"
+require_relative "archspec/architectures"
+require_relative "archspec/presets"
+require_relative "archspec/rules/dependency_rules"
+require_relative "archspec/rules/protocol_rules"
+require_relative "archspec/rules/cycle_rule"
+require_relative "archspec/rules/zeitwerk_rule"
+require_relative "archspec/formatters/text"
+require_relative "archspec/formatters/json"
+require_relative "archspec/cli"
+
+module ArchSpec
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :last_definition
+
+    def define(name = "Architecture", &block)
+      definition = Definition.new(name)
+      definition.extend(DSL::Context)
+      definition.instance_eval(&block) if block
+      self.last_definition = definition
+    end
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: archspec
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre1
+platform: ruby
+authors:
+- Carmine Paolino
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-06-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.20'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Convention-aware architecture checks for Ruby and Rails codebases.
+email:
+- carmine@paolino.me
+executables:
+- archspec
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/archspec
+- lib/archspec.rb
+- lib/archspec/analyzer.rb
+- lib/archspec/architectures.rb
+- lib/archspec/baseline.rb
+- lib/archspec/cli.rb
+- lib/archspec/component_spec.rb
+- lib/archspec/definition.rb
+- lib/archspec/diagnostic.rb
+- lib/archspec/dsl.rb
+- lib/archspec/evaluator.rb
+- lib/archspec/formatters/json.rb
+- lib/archspec/formatters/text.rb
+- lib/archspec/model.rb
+- lib/archspec/presets.rb
+- lib/archspec/rules/cycle_rule.rb
+- lib/archspec/rules/dependency_rules.rb
+- lib/archspec/rules/protocol_rules.rb
+- lib/archspec/rules/zeitwerk_rule.rb
+- lib/archspec/source_location.rb
+- lib/archspec/version.rb
+homepage: https://crmne.github.io/archspec
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://crmne.github.io/archspec
+  source_code_uri: https://github.com/crmne/archspec
+  changelog_uri: https://github.com/crmne/archspec/releases
+  documentation_uri: https://crmne.github.io/archspec/getting-started/
+  bug_tracker_uri: https://github.com/crmne/archspec/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Architecture fitness functions for Ruby and Rails.
+test_files: []