mudguard 0.1.8 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6db3d7377ad8b0b1d13e59c306bd937bcb39a2b68bee5d0539a4dff17d460243
-  data.tar.gz: b46919284fea9ad09e6db895025c50eeff3577fc0fe32bbc3b5ad7aec0e4833f
+  metadata.gz: 3a7b56ba51f10b0d6d32fcb120599bc145b275076b30786b6955285f5da26668
+  data.tar.gz: ca75c47ff5f80584407bb0da9d56b64f7c9e1e65cc8f7fc8b377ea0e8d83fefa
 SHA512:
-  metadata.gz: 68ed243c036a7bdbe9a5e3e5e5996c76006cbc7057f4f5aad78d43c011038a6de16496c61ce5bd9c88a63c678f6d501f53af17e18e931abb20d0bce351ce0585
-  data.tar.gz: 050fdc731cc7297f986f10ed1b39e95aa6e82bf2f36959d7fe6e322c9681b5322a8a0390b177ced26ecc5c09bea737e86b26645966e4d1b2612eee25d370a735
+  metadata.gz: e9bd40c81779ed70c331c0d445b735edb3e561967e65fce1dc228a62ad86fd9298dfaa990d3bded3faec6191b5821204466c9ed29cdf89d12e9eee1678884d81
+  data.tar.gz: 427d86d72d87f73d11dedfbb7a35d42ead0145919bf85e32dd5c9055bc977a2dadb9be668f76a081e61f54510a6ebb4aa66e7f4b11746da1a222efde3ad5b760

data/.gitignore

@@ -20,3 +20,4 @@
 
 # Following file is dynamically created while running tests
 /spec/lib/infrastructure/persistence/policy_file_project/.mudguard.yml
+/spec/test_projects/project_without_mudguard_file/.mudguard.yml

data/.mudguard.yml

@@ -0,0 +1,6 @@
+'./**/*.rb':
+  # uncomment following lines to allow all dependencies
+  # - .*
+
+  # all code can depend on modules or constants defined in same module
+  - ^(::.+)(::[^:]+)* -> \1(::[^:]+)*$

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    mudguard (0.1.8)
+    mudguard (0.2.0)
       parser (~> 2.7)
       rake (~> 13.0)
 

data/README.md

@@ -1,10 +1,16 @@
 # Mudguard
 
-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/mudguard`. To experiment with that code, run `bin/console` for an interactive prompt.
+**Mudguard** is a Ruby static code analyzer that investigates the coupling of modules in your source code. Mudguard
+prevents your code from becoming a [Big ball of mud](http://www.laputan.org/mud/) and helps implementing and
+maintaining an intended design.
 
-TODO: Delete this and the text above, and describe your gem
+Mudguard is inspired by
+* [Rubocop](https://github.com/rubocop-hq/rubocop)
+* Clean Architecture by Robert C. Martin (ISBN-13: 978-0-13-449416-6)
+* having seen many larger code bases in a sorrow state
+* my inability to efficiently break up application code into gems or rails engines
 
-## Installation
+# Installation
 
 Add this line to your application's Gemfile:
 
@@ -20,19 +26,66 @@ Or install it yourself as:
 
     $ gem install mudguard
 
-## Usage
+## Quickstart
+```
+$ cd my/cool/ruby/project
+$ mudguard
+```
+
+Mudguard creates on it's first run a file called **.mudguard.yml** which is used to configure **design policies** 
+governing your code. A .mudguard.yml could look like:
+```
+'./**/*.rb': # all code
+  # all code can depend on siblings in same module or class
+  - ^(::.+)(::[^:]+)* -> \1(::[^:]+)*$
+  # all code can depend on certain types
+  - .* -> ::(String|SecureRandom|Container|Time|Date|JSON|Object|Hash)$
+
+  # in all code module Application can depend on module Domain
+  - ^::Application(::[^:]+)* -> ::(Domain)(::[^:]+)*$
+  # in all code module Infrastructure can depend on module Application
+  - ^::Infrastructure(::[^:]+)* -> ::(Application)(::[^:]+)*$
+
+'spec/**/*.rb': # spec code
+  # Only in test code can we use RSpec, Timecop and Exception
+  - .* -> ::(RSpec|Timecop|Exception)$
+``` 
+
+## The .mudguard.yml
+The .mudguard.yml defines scopes and policies. A policy defines which dependencies are inside that scope permissible:
+```
+scope1:
+    - policy 1
+    - policy 2
+scope2:
+    - policy 3
+```
+The **scope** is a [glob-pattern](https://en.wikipedia.org/wiki/Glob_(programming)) and defines to which files a set
+of policies apply. For example a value `lib/docker/**/*.rb` defines a scope containing all Ruby files inside 
+folder lib/docker. 
 
-TODO: Write usage instructions here
+A **policy** is a [regular expression](https://ruby-doc.org/core-2.5.1/Regexp.html) matching one or a set of 
+dependencies that are permissible inside that scope. Mudguard represents a **dependency** as a symbol in form 
+of `X -> Y` meaning "X depends on Y". See following examples:
 
-## Development
+| Policy | matched Dependency|  Explanation |
+| --- | --- | --- |
+| `^::A -> ::B$` | `::A -> ::B` |Module A can depend on module or constant B |
+| `^::Infrastructure -> ::Rails$` | `::Infrastructure -> ::Rails` |Module Infrastructure can depend on Rails |
+| `^::Infrastructure(::[^:]+)* -> ::ActiveRecord$` | `::Infrastructure::Logger -> ::ActiveRecord` or `::Infrastructure::Persistence -> ::ActiveRecord`|Module Infrastructure and its submodules can depend on ActiveRecord |
+| `.*   -> ::Exception$` | `::Api::Gateway -> ::Exception` or `::Logger -> ::Gateway` |Any module can depend on class Exception | 
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Any dependency for which Mudguard doesn't find a matching policy is reported as an impermissible dependency.
 
-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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Outlook
+Using regular expressions as policies is very flexible but difficult to use. Furthermore certain patterns used in 
+the regular expressions do repeat. It might be useful to replace regular expressions in future with a specific language
+to describe permissible dependencies. Any thoughts on that?
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/mudguard. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/Enceradeira/mudguard.
+ This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 

data/lib/mudguard/infrastructure/persistence/.mudguard.template.yml

@@ -0,0 +1,6 @@
+'./**/*.rb':
+  # uncomment following lines to allow all dependencies
+  # - .*
+
+  # all code can depend on modules or constants defined in same module
+  - ^(::.+)(::[^:]+)* -> \1(::[^:]+)*$

data/lib/mudguard/infrastructure/persistence/policy_file.rb

@@ -15,7 +15,8 @@ module Mudguard
             policy_exists = File.exist?(policy_file)
 
             unless policy_exists
-              raise Mudguard::Domain::Error, "expected policy file #{policy_file} doesn't exists"
+              template_file = File.join(__dir__, ".mudguard.template.yml")
+              FileUtils.cp(template_file, policy_file)
             end
 
             read_yml(policy_file)

data/lib/mudguard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mudguard
-  VERSION = "0.1.8"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mudguard
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.2.0
 platform: ruby
 authors:
 - Jorg Jenni
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-06-07 00:00:00.000000000 Z
+date: 2020-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -174,6 +174,7 @@ extra_rdoc_files: []
 files:
 - ".envrc"
 - ".gitignore"
+- ".mudguard.yml"
 - ".rubocop.yml"
 - ".ruby-version"
 - CODE_OF_CONDUCT.md
@@ -200,6 +201,7 @@ files:
 - lib/mudguard/infrastructure/cli/controller.rb
 - lib/mudguard/infrastructure/cli/notification_adapter.rb
 - lib/mudguard/infrastructure/cli/view.rb
+- lib/mudguard/infrastructure/persistence/.mudguard.template.yml
 - lib/mudguard/infrastructure/persistence/policy_file.rb
 - lib/mudguard/infrastructure/persistence/project_repository.rb
 - lib/mudguard/infrastructure/persistence/ruby_files.rb