stellwerk 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a59c8761699131fdfb30f5a83782ba2b71a1bcc12bd59fed46f071a9306aba7
-  data.tar.gz: 1e7c0b76429f09eb9139493bf0e2b0a2b2f22599ed9e7d2b9ad6c5176ec571df
+  metadata.gz: f5bc717030b6f075aebb0615a37ee45cf32aafe5cc7d5e9e7d5bbf50350f6cfa
+  data.tar.gz: 6d03317e06b5d44b174b734424a72543943f5f62a39ff4d3cba9a6b1a64a9b0d
 SHA512:
-  metadata.gz: acfa6f9020aaf20e6ecc94b91cef9ac5331ab70b32f64113a0ebe6baa8ef5cb1f13dc2638cbd98a820bdf946d3598546abbafa550f710080f1f69086f213a8b7
-  data.tar.gz: d32d3de5760a3c9f01992cb0c24472b249220d13c859c07fd189e3b85876a8678b3ac0b7b0e52be4028d7da1699525aa758e01bfec2a908bedea8a2d3af36094
+  metadata.gz: a87d9aa67acfa4a3c5df1119d6c8aaa1e1f4ea98c8a923445cd970c1b783e3a25db0bae5f5b12950d61fc975ed75c6a1423ecf62ff5b31c3a81d16e9ce76428e
+  data.tar.gz: 11a17aa329b2194b587e66d5e316e978c026dd2114795ce7dda1c95434e9bb037b981972625db420679de2df5eff66f6ccc26186891fb0b48d9facecdf7857b9

data/AGENTS.md

@@ -0,0 +1,9 @@
+# Agent Instructions
+
+## Keep it simple
+
+We're in pre-alpha. Don't overengineer, don't overdocument, don't put too much emphasis on UX. We want to prove the basics first.
+
+## Usage Expectations
+
+This gem can only be used with Rails applications for now. In theory we can support any Ruby codebase using zeitwerk, but that's not a priority at this point.

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.0.2] - 2026-02-15
+
+- MVP: Basic architecture enforcement with layered architecture support
+- **breaking:** invoke stellwerk via rake task (`rails stellwerk:check`), the executable is removed
+- pull actual autoloaders from application, or use faked autoloaders to omit app startup via `rails stellwerk:check_simple`
+
 ## [0.0.1] - 2025-12-10
 
-- Initial release
+- Initial release without any functionality. Essentially, name squatting.

data/IMPLEMENTATION.md

@@ -63,8 +63,13 @@ Considerations:
   jobs should probably live in the business logic layer
 - what about lib?
 
-## TODO
+## Todos
+
+- [ ] Implement VSCode integration (lots of things TBD)
+
+## Ideas
 
 - Shortcuts
   - for CLI command, use a CLI library instead of hand-rolling it
     - probably, `optparse` built into the stdlib
+- Support non-rails applications using Zeitwerk, probably by adding an executable

data/README.md

@@ -1,62 +1,47 @@
 # Stellwerk
 
-TODO: Delete this and the text below, and describe your gem
+Stellwerk is a Ruby gem that helps you enforce architectural rules in your Ruby on Rails application. It analyzes your codebase and identifies violations of architectural constraints you specify.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/stellwerk`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Name
 
-## Installation
+The name "Stellwerk" is derived from the German word for "signal station" in a railway context. It keeps your Rails on track!
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add stellwerk
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install stellwerk
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Publishing to RubyGems
+Run the check task in your Rails app:
 
-1. Update the version in `lib/stellwerk/version.rb`. Push / merge to main.
-2. Build the gem:
-
-   ```bash
-   gem build stellwerk.gemspec
-   ```
+```bash
+bin/rails stellwerk:check
+```
 
-   This should produce `stellwerk-<version>.gem`.
-3. Sign in to RubyGems (only needed once):
+Run a simpler check without booting `:environment` (uses statically defined Zeitwerk loaders for `app/*` and `lib`) and will probably miss stuff in more complex Rails apps:
 
-   ```bash
-   gem signin
-   ```
+```bash
+bin/rails stellwerk:check_simple
+```
 
-4. Push the built gem:
+## Development
 
-   ```bash
-   gem push stellwerk-<version>.gem
-   ```
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-5. Tag the release:
+## Publishing to RubyGems
 
-   ```bash
-   git tag v<version> && git push origin v<version>
-   ```
+1. Update the version in [`lib/stellwerk/version.rb`](lib/stellwerk/version.rb). Push / merge to main.
+2. `rake release`
 
 ## Contributing
 

data/lib/stellwerk/commands/check.rb

@@ -0,0 +1,58 @@
+require "pathname"
+require "reference_extractor"
+require "zeitwerk"
+require "parallel"
+
+require "stellwerk/config"
+require "stellwerk/printer"
+
+module Stellwerk
+  module Commands
+    class Check
+      def initialize(root_path, autoloaders: nil)
+        @root_path = Pathname.new(root_path)
+        @autoloaders = autoloaders || fake_autoloaders
+      end
+
+      def run
+        puts "running check..."
+        config = Stellwerk::Config.new(@root_path.join("stellwerk.yml"))
+
+        # build graph using reference_extractor
+        extractor = ReferenceExtractor::Extractor.new(
+          autoloaders: @autoloaders,
+          root_path: @root_path
+        )
+
+        all_files = @root_path.find
+          .select { |path| path.to_s.end_with?(".rb") }
+          .reject { |path| path.relative_path_from(@root_path).to_s.start_with?("db/") }
+        puts "collected #{all_files.length} files"
+
+        before = Time.now
+        edgelist = Parallel.flat_map(all_files, in_processes: Parallel.processor_count - 1) do |file|
+          extractor.references_from_file(file)
+        end
+        puts "extracted #{edgelist.length} references in #{(Time.now - before).round(2)} seconds"
+
+        # check rules against graph, collect violations
+        puts "checking rules..."
+        violations = config.rules.flat_map do |rule|
+          rule.find_violations(edgelist)
+        end
+
+        Stellwerk::Printer.new(violations).print
+      end
+
+      private
+
+      def fake_autoloaders
+        loader = Zeitwerk::Loader.new
+        @root_path.join("app").each_child { |child| loader.push_dir(child) }
+        loader.push_dir(@root_path.join("lib"))
+        loader.setup
+        [loader]
+      end
+    end
+  end
+end

data/lib/stellwerk/config.rb

@@ -0,0 +1,28 @@
+require "active_support/core_ext/string"
+
+module Stellwerk
+  class Config
+    class UnknownRule < StandardError; end
+
+    attr_reader :rules
+
+    def initialize(filepath)
+      config = YAML.load_file(filepath)
+
+      @rules = initialize_rules(config["rules"])
+    end
+
+    def initialize_rules(rules_config)
+      rules_config.map do |rule_name, rule_config|
+        begin
+          require "stellwerk/rules/#{rule_name}"
+          rule_class = ("Stellwerk::Rules::" + rule_name.camelize).constantize
+        rescue LoadError, NameError
+          raise(UnknownRule, "Unknown rule: #{rule_name}")
+        end
+
+        rule_class.new(rule_config)
+      end
+    end
+  end
+end

data/lib/stellwerk/printer.rb

@@ -0,0 +1,26 @@
+module Stellwerk
+  class Printer
+    def initialize(violations)
+      @violations = violations
+    end
+
+    def print
+      puts "\nFound #{@violations.length} violations."
+
+      @violations.group_by { |violation| violation.rule }.each do |rule, violations|
+        puts "#{rule.name.titleize} rule violations:"
+        violations.each do |violation|
+          puts "  " + format_reference(violation.reference)
+        end
+      end
+    end
+
+    private
+
+    def format_reference(reference)
+      source = "#{reference.relative_path}:#{reference.source_location.line}"
+      target = "#{reference.constant.name}, defined in #{reference.constant.location}"
+      "#{source} refers to #{target}"
+    end
+  end
+end

data/lib/stellwerk/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Stellwerk
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("../tasks/stellwerk.rake", __dir__)
+    end
+  end
+end

data/lib/stellwerk/rules/layers.rb

@@ -0,0 +1,58 @@
+require "pathname"
+
+require "stellwerk/violation"
+
+module Stellwerk
+  module Rules
+    class Layers
+      class InvalidLayersSpec < RuntimeError; end
+
+      def initialize(rule_spec)
+        @layers = rule_spec.map { |layer| Array(layer).map { |path_string| Pathname.new(path_string) } }
+        validate_layers!
+      end
+
+      def find_violations(reference_graph)
+        relevant_graph = filter_graph(reference_graph)
+
+        relevant_graph.map do |reference|
+          # TO DO: violations should include some rule specific violation context
+          # e.g. from layer and to layer
+          if layer_index(reference.relative_path) > layer_index(reference.constant.location)
+            Violation.new(:layers, reference)
+          end
+        end.compact
+      end
+
+      def filter_graph(reference_graph)
+        reference_graph.select do |reference|
+          all_components.any? { |component| path_in_component?(reference.relative_path, component) } &&
+            all_components.any? { |component| path_in_component?(reference.constant.location, component) }
+        end
+      end
+
+      def all_components
+        @layers.flatten
+      end
+
+      def path_in_component?(path, component)
+        # TO DO: Find out whether we can use Pathname methods to determine whether one path contains another
+        component_dirname = component.to_s
+        component_dirname += "/" unless component.to_s.end_with?("/")
+        path.to_s.start_with?(component_dirname)
+      end
+
+      def layer_index(file_path)
+        @layers.index do |components|
+          components.any? { |component| path_in_component?(file_path, component) }
+        end
+      end
+
+      def validate_layers!
+        raise InvalidLayersSpec, "Overlapping layers" if all_components.count != all_components.uniq.count
+        raise InvalidLayersSpec, "No layers exist" if @layers.empty?
+        raise InvalidLayersSpec, "Empty layers exist" if @layers.any?(&:empty?)
+      end
+    end
+  end
+end

data/lib/stellwerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stellwerk
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/stellwerk/violation.rb

@@ -0,0 +1,3 @@
+module Stellwerk
+  Violation = Struct.new(:rule, :reference)
+end

data/lib/stellwerk.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "stellwerk/version"
+require_relative "stellwerk/commands/check"
+
+require "rails/railtie"
+require_relative "stellwerk/railtie"
 
 module Stellwerk
   class Error < StandardError; end
-  # Your code goes here...
 end

data/lib/tasks/stellwerk.rake

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+namespace :stellwerk do
+  task check: :environment do
+    autoloaders = [Rails.autoloaders.main, Rails.autoloaders.once].compact
+
+    Stellwerk::Commands::Check.new(Rails.root, autoloaders: autoloaders).run
+  end
+
+  task :check_simple do
+    Stellwerk::Commands::Check.new(Dir.pwd).run
+  end
+end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: stellwerk
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Philip Theus
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -37,24 +37,57 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: parallel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 email:
 - philip@simplexity.quest
-executables:
-- stellwerk
+executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - ".tool-versions"
+- AGENTS.md
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - IMPLEMENTATION.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- exe/stellwerk
 - lib/stellwerk.rb
-- lib/stellwerk/command.rb
+- lib/stellwerk/commands/check.rb
+- lib/stellwerk/config.rb
+- lib/stellwerk/printer.rb
+- lib/stellwerk/railtie.rb
+- lib/stellwerk/rules/layers.rb
 - lib/stellwerk/version.rb
+- lib/stellwerk/violation.rb
+- lib/tasks/stellwerk.rake
 homepage: https://github.com/exterm/stellwerk
 licenses:
 - MIT

data/exe/stellwerk

@@ -1,3 +0,0 @@
-#!/usr/bin/env ruby
-
-require "stellwerk/command"

data/lib/stellwerk/command.rb

@@ -1,3 +0,0 @@
-require "stellwerk"
-
-