enola 0.5.6 → 0.5.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9465910b66ac8c461af7a7169f074d55b8c64c7c228dfe4acb81bdf70980731
-  data.tar.gz: f5fcd1f86a3cde157a0dc4ae901b56577f08cb1f8735aa065110bec03ad2254e
+  metadata.gz: 9982dbf8dda074c423e5b0bb421d366085d18a18fa8a7be9c28dfa554c171a55
+  data.tar.gz: 01c9c4c40e9e490007bc83a7745e42a181f068f474b787cac1a117f9c9eb1a76
 SHA512:
-  metadata.gz: bf9acda456730768553a8489cde1f527989f0d8e35e425fbb74ff20eb265796a8c6d995ad5062dfcb92017017082610b950cc12b5f0d4d7ed919d8dc1f2aa629
-  data.tar.gz: 814dd495e17e04801536643b736143644adac776454e27a076256ae07daccdb1f45cd38b88fe7a10ae784f739ecfb1bcc465cd7a30e05d68c022b2a9455d3dcb
+  metadata.gz: 62e80fd23f020a2b19b0c07362a94bd6929c5525c451ec0ecf6c8ad5d29662fd996853b7da52896f53db32401bc5a4688cacd4210d774bac3b4f30b328cd9b57
+  data.tar.gz: 30979ac59baf52c32711ee8bc28d25206ca63592c2f2a12b9e32aede1c5eb974584c2c64bbc03aaef5c0e8d55159de3e2463b1c74008752b53f4630788314741

data/CHANGELOG.md

@@ -1,3 +1,67 @@
+## enola 0.5.7 and enola-rb 0.5.7 (2026-10-26)
+
+The enola and enola-rb gems drive upstream enola 0.4.35. Between 0.4.32 and
+here upstream locked the provider cache, which two Ruby providers running at
+once could corrupt or crash the engine on, and the gem's default config runs
+two (0.4.33); answered a `prism` entry with no `command` from the Rubydex
+index, so call edges no longer need Ruby on the machine (0.4.33); moved the
+Rubydex engine to 0.4.1 (0.4.33); removed false Ruby edges from methods
+declared in several modules and from namespace-opening modules, and followed
+calls through superclasses, included modules and Rails loading (0.4.33,
+0.4.34); keyed per-file provider cache entries by path as well as content
+(0.4.34); added a packwerk explainer and impact rolled up by pack (0.4.33);
+and added endpoint callers (0.4.35). `cacheVersion` moved from v390 to v465,
+so caches rebuild once and a pinned baseline can show a one-time change.
+
+The Rubydex pin the config writes moves from 0.4.0 to 0.4.1, the version
+0.4.35 fetches. The Rails installer now asks the binary it drives which
+Rubydex version it fetches (`providers list`) and writes that, rather than the
+gem's constant. `munola init` and `rails generate munola:install` wrote the
+enola gem's 0.4.0 while the munola channel fetches 0.4.1, so Rubydex was a
+silent skip there; munola picks the fix up through enola-rb with no release of
+its own. enola-rb now requires enola `~> 0.5.7` for it.
+
+The vendored Prism provider script is re-vendored from v0.4.35. Its body is
+unchanged since v0.4.19 and it still answers provider version 0.2.0. The gem
+keeps running the script rather than the built-in prism: upstream documents
+the built-in as close to the script, not identical.
+
+The Rails installer binds `layered` advisory. The binary's `constraints init`
+binds it on a Rails app with application on `app/jobs`, so its
+`presentation-reaches-application-only` rule read every controller that calls
+a model as a breach: 147 of Campfire's 178, and as a ratchet it failed
+`enola:check` on the next one, `@rooms = Room.all` in a new controller among
+them. Advisory, its rules report below the gate and never fail; a model
+reaching a controller still fails through the starter law
+`models-do-not-reach-controllers`. Only a `recipes.yaml` that init wrote during
+the install is touched, and the generator says what it did.
+
+`rake enola:explain` prints upstream's plain-language repository summary
+(`--explain --summary`, new in 0.4.33): what the app is, where to start
+reading, what is risky to change. It needs no config or baseline, and on a
+binary without `--summary`, such as munola's 0.4.32.1 channel, it prints the
+full `--explain` report instead.
+
+The README opens with what the gems catch, shown on 37signals' Campfire, then
+a Rails quick start, a GitHub Actions workflow that grades each pull request
+against its base and annotates the line, the agent setup and how enola sits
+next to RuboCop, Brakeman and Packwerk. The enola and enola-rb gemspecs lead
+with the same, and all three name the README and the issue tracker on
+rubygems.org. All three require Ruby 3.2, the oldest CI runs.
+
+## munola 0.6.4 (2026-10-20)
+
+munola drives channel release `0.4.32.1`, cut from the promoted current at
+upstream enola 0.4.32 and published on misabegovic/enola as
+`munola-v0.4.32.1` (five platforms with checksums and a `version.json`). Its
+notes name 32 differences from upstream 0.4.32, among them the recipe
+catalogue at enola-guides v0.3.1 and the init role binding, the member check,
+the providers mode, the built-in prism provider and the larger MCP surface.
+
+The Rubydex version the config writes moves from 0.4.0 to 0.4.1, the library
+the 0.4.32.1 channel fetches. A config naming 0.4.0 would have the binary skip
+the provider for a version mismatch, silently.
+
 ## enola 0.5.6 and enola-rb 0.5.6 (2026-10-20)
 
 The enola and enola-rb gems drive upstream enola 0.4.32. Between 0.4.19 and

data/README.md

@@ -1,19 +1,164 @@
 # enola-rb
 
-Four pure-Ruby gems, one repository, for running
-[enola](https://github.com/enola-labs/enola), the architecture-graph tool,
-from Ruby. None of them carries a binary or compiles anything.
+[![Gem Version](https://badge.fury.io/rb/enola-rb.svg)](https://rubygems.org/gems/enola-rb)
+[![CI](https://github.com/misabegovic/enola-rb/actions/workflows/ci.yml/badge.svg)](https://github.com/misabegovic/enola-rb/actions/workflows/ci.yml)
 
-Two channels. `enola` wraps the released upstream binary and `enola-rb` adds
-the Rails layer on it, split so a Rubyist can take the wrapper without Rails.
-`munola` is one gem for its own channel, wrapper and Rails layer together,
-because nobody installs it to avoid Rails. The Rails code is written once, in
-`enola-rb`, and munola adds only what is munola's own.
+Fail the build when a change breaks your Rails app's architecture: a model
+that starts calling a controller, a job that renders, a new dependency cycle.
+RuboCop reads one file at a time and your tests run the code; neither sees
+the edge a change adds between two parts of the app. These gems run
+[enola](https://github.com/enola-labs/enola) from Bundler. enola pins your
+app's dependency graph as a baseline and grades each change against it, so
+the hundreds of crossings an app already has stay out of the report and only
+what the change introduced can fail it.
+
+## What it catches
+
+[Campfire](https://github.com/basecamp/once-campfire), 37signals' Rails chat
+app, after `bin/rails generate enola:install` and a pinned baseline. One
+method added to a model:
+
+```ruby
+# app/models/boost.rb
+def render_preview
+  MessagesController.render(partial: "messages/boost", locals: { boost: self })
+end
+```
+
+```
+$ bin/rake enola:check
+FAIL — 1 structural regression introduced.
+
+Regressions (fail):
+  - [constraints] 1.00 — Constraint models-do-not-reach-controllers violated: Boost#render_preview -> MessagesController via calls
+      forbidden calls edge
+      app/models/boost.rb:7
+        def render_preview
+        ^^^^^^^^^^^^^^^^^^
+
+Policy: fail on new findings from [constraints] at confidence >= 1.00.
+
+New findings (advisory — below the failure policy):
+  - [constraints] 0.90 — Advisory constraint layered/domain-knows-no-presentation violated: rubydex-ref: Boost#render_preview -> MessagesController -> MessagesController via depends_on
+      forbidden depends_on edge
+      app/models/boost.rb:8
+          MessagesController.render(partial: "messages/boost", locals: { boost: self })
+```
+
+The tests pass and RuboCop is silent; the check exits 1. Campfire already
+carries 178 breaches of the bound rules, and none of them is in the report.
+A new controller that calls a model passes. Output trimmed: the full verdict
+goes on to list what the change resolved, the coupling it added and the
+package metrics that moved. `enola check --summary` writes the same verdict in
+plain words.
+
+## Quick start (Rails)
+
+```sh
+bundle add enola-rb --group "development, test"
+bin/rake enola:explain             # what the app is, where to start, what is risky
+bin/rails generate enola:install   # mcp-arch.yaml, enola/constraints/, .gitignore
+bin/rake enola:snapshot            # snapshot the app and pin it as the baseline
+# ...make a change...
+bin/rake enola:check               # exits 1 on a new breach of a declared law
+```
+
+The generator writes four starter laws a Rails team keeps, each with its
+reason (`models-do-not-reach-controllers`, `policies-only-answer`,
+`the-request-api-stays-in-controllers`,
+`background-jobs-never-invoke-controller-code`), and binds the enola recipes
+whose directories the app has. `layered` is bound advisory: Rails
+controllers call models by design, which that recipe reads as a breach, so
+it reports and never fails a check. The laws are plain Ruby files in
+`enola/constraints/`; edit them, delete them, add your own. Upstream's
+[Rails guide](https://github.com/enola-labs/enola/blob/main/docs/RAILS.md)
+walks the same loop with the binary alone, and
+[GATING.md](https://github.com/enola-labs/enola/blob/main/docs/GATING.md)
+says exactly what can fail a build.
+
+Not on Rails? `bundle add enola --group development` and every enola command
+runs as `bundle exec enola ...`; see [`enola`](#enola) below.
+
+## In CI
+
+Grade each pull request against its base branch. The base is snapshotted in
+a worktree beside the checkout, so the PR's `Gemfile.lock` stays in place,
+and a regression shows up as an annotation on the line that introduced it:
+
+```yaml
+# .github/workflows/architecture.yml
+name: Architecture
+on: pull_request
+jobs:
+  enola:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - name: Snapshot the base branch
+        run: |
+          git worktree add "$RUNNER_TEMP/base" "${{ github.event.pull_request.base.sha }}"
+          bundle exec enola --generate "$RUNNER_TEMP/base"
+      - name: Grade the pull request
+        run: >
+          bundle exec enola check --baseline "$RUNNER_TEMP/base/.enola"
+          --fail-on constraints --format annotations --host github .
+```
+
+`bundle exec enola` needs no database and does not boot the app. Merge what
+the generator wrote before turning the workflow on, so the base declares the
+same laws the pull request is graded by.
+
+## With a coding agent
+
+enola is also an MCP server: it gives Claude Code, Cursor and other agents a
+map of the app to query instead of grepping through it, and lets them check
+their own change before they report it done.
+
+```sh
+claude mcp add enola -- bundle exec enola   # serve the graph to Claude Code
+bundle exec enola install                   # write enola's instructions into the
+                                            # files your agents read; previews first
+```
+
+## How it compares
+
+| Tool | Reads | Fails on |
+|---|---|---|
+| RuboCop, Standard | one file at a time, against style rules | any offence in the tree |
+| Brakeman | data flow, for security | any warning in the tree |
+| Packwerk | constant references across declared packs | references the packs do not allow |
+| enola | the dependency graph across the app, against a pinned baseline | only what this change introduced, and only the rules you name |
+
+They are complements. enola reads Packwerk's `package.yml` files, rolls
+impact up by pack and has a packwerk explainer, so an app that already uses
+Packwerk keeps it.
+
+## The gems
+
+Three pure-Ruby gems in one repository. None carries a binary or compiles
+anything: the first command that needs enola downloads the release for your
+platform and verifies its checksum.
+
+| Gem | Use it for |
+|---|---|
+| `enola-rb` | Rails: the generator and the `enola:*` rake tasks. Depends on `enola`. |
+| `enola` | Any Ruby project: the `enola` command, wrapping the released binary. |
+| `munola` | A fork channel with its own recipe catalogue; see [`munola`](#munola). |
+
+`enola` and `enola-rb` are split so a Rubyist can take the wrapper without
+Rails. `munola` is one gem for its own channel, wrapper and Rails layer
+together, because nobody installs it to avoid Rails. The Rails code is written
+once, in `enola-rb`, and munola adds only what is munola's own.
 
 ## `enola`
 
 The wrapper of the released enola. The gem versions itself; the release it
-drives is `Enola::UPSTREAM_VERSION`, v0.4.32 as of `enola 0.5.6`, and every
+drives is `Enola::UPSTREAM_VERSION`, v0.4.35 as of `enola 0.5.7`, and every
 gemspec summary names it.
 
 ```ruby
@@ -29,7 +174,7 @@ bundle exec enola check .
 The first command that needs the binary downloads the release for your
 platform (linux, darwin, windows; amd64, arm64), verifies it against the
 sha256 file the same release publishes, and keeps it under
-`~/.cache/enola/upstream/0.4.32/` (`ENOLA_CACHE_DIR` moves the root). An
+`~/.cache/enola/upstream/0.4.35/` (`ENOLA_CACHE_DIR` moves the root). An
 `enola` already on your PATH is used only when it answers the pinned version;
 offline with an empty cache is a refusal that names the cache and the release
 rather than a fallback to whatever is installed. Nothing downloads at
@@ -56,6 +201,7 @@ gem "enola-rb"
 
 ```sh
 bin/rails generate enola:install
+bin/rake enola:explain
 bin/rake enola:snapshot
 bin/rake enola:check
 ```
@@ -64,9 +210,14 @@ The generator writes `enola/constraints/` from the guides' starter laws (four
 laws a Rails team keeps, each with its reason), asks the binary's own
 `constraints init` to bind the shipped recipes whose roles resolve in the app,
 writes every other shipped recipe as a commented binding to uncomment once the
-directories exist, and ignores `.enola/`. It reads what `init` wrote rather
+directories exist, and ignores `.enola/`. A `layered` binding the binary's
+init wrote is set to `mode: advisory`; a `recipes.yaml` the app already had
+is never touched. It reads what `init` wrote rather
 than its exit code, and when the binary cannot be fetched it still writes the
-laws and says so. `enola:snapshot` generates and pins the baseline;
+laws and says so. `enola:explain` needs no setup: it prints what the app is,
+where to start reading, what is risky to change and what is worth a look
+(the full statistics report on a binary without `--summary`).
+`enola:snapshot` generates and pins the baseline;
 `enola:check` grades the working tree against it and fails on a new breach of
 a declared law. A surface the pinned binary lacks is refused by name with the
 remedy.

data/lib/enola/config.rb

@@ -10,15 +10,17 @@ module Enola
       File.join(File.expand_path(root), FILE)
     end
 
-    def self.write_default(root, ruby: Providers.ruby)
+    # rubydex names the engine version the config pins; pass what the binary
+    # being driven lists, since a pin it does not fetch is a silent skip.
+    def self.write_default(root, ruby: Providers.ruby, rubydex: Providers::RUBYDEX_EXPECTED_VERSION)
       target = path(root)
       return nil if File.exist?(target)
 
-      File.write(target, render(ruby: ruby))
+      File.write(target, render(ruby: ruby, rubydex: rubydex))
       target
     end
 
-    def self.render(ruby: Providers.ruby)
+    def self.render(ruby: Providers.ruby, rubydex: Providers::RUBYDEX_EXPECTED_VERSION)
       <<~YAML
         # Written by the enola gem; edit freely. Both providers are on: Prism runs
         # under the Ruby that runs the gem, Rubydex is built into the binary and
@@ -33,7 +35,7 @@ module Enola
             command: [#{ruby.inspect}, #{Providers.prism_script.inspect}]
             expected_version: "#{Providers.prism_version || '0.1.0'}"
           - name: rubydex
-            expected_version: "#{Providers::RUBYDEX_EXPECTED_VERSION}"
+            expected_version: "#{rubydex}"
       YAML
     end
   end

data/lib/enola/providers/prism/enola_prism_provider.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
-# Vendored from enola-labs/enola examples/providers/ruby/prism/enola_prism_provider.rb at v0.4.32 (37d74c08a48dfa6092ae5e37cc15edb390f66ec7), Apache-2.0.
+# Vendored from enola-labs/enola examples/providers/ruby/prism/enola_prism_provider.rb at v0.4.35 (9fe636b68967d113292d90bfca4cc7ebaa2f2b94), Apache-2.0.
 
 # enola Prism reference provider.
 #

data/lib/enola/providers.rb

@@ -9,7 +9,7 @@ module Enola
   # script under the Ruby running this gem; Rubydex is built into the binary
   # and needs its engine library fetched once per binary version.
   module Providers
-    RUBYDEX_EXPECTED_VERSION = "0.4.0"
+    RUBYDEX_EXPECTED_VERSION = "0.4.1"
 
     def self.prism_script
       File.expand_path("providers/prism/enola_prism_provider.rb", __dir__)

data/lib/enola/version.rb

@@ -3,6 +3,6 @@
 module Enola
   # The gem versions itself. UPSTREAM_VERSION names the enola release it
   # fetches and drives.
-  UPSTREAM_VERSION = "0.4.32"
-  VERSION = "0.5.6"
+  UPSTREAM_VERSION = "0.4.35"
+  VERSION = "0.5.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: enola
 version: !ruby/object:Gem::Version
-  version: 0.5.6
+  version: 0.5.7
 platform: ruby
 authors:
 - Muhamed Isabegovic
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -25,9 +25,14 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.3'
 description: |
-  A pure-Ruby wrapper around enola, the architecture-graph tool by enola-labs.
+  Catch the architecture regressions a change introduces: a new dependency
+  cycle, a layer crossed the wrong way, coupling nobody asked for. enola pins
+  your codebase's dependency graph as a baseline and grades each change
+  against it, and serves the graph to coding agents over MCP. This gem is a
+  pure-Ruby wrapper around enola, the architecture-graph tool by enola-labs,
+  so it runs from Bundler as `bundle exec enola`; for Rails, use enola-rb.
   The gem versions itself; the enola release it drives is named in its
-  UPSTREAM_VERSION, 0.4.32 here. The binary is not in the
+  UPSTREAM_VERSION, 0.4.35 here. The binary is not in the
   gem: the first command that needs it downloads the release for your
   platform, verifies it against the checksum the release publishes, and keeps
   it in a per-user cache. Every command and exit code is forwarded unchanged.
@@ -61,7 +66,9 @@ licenses:
 - Apache-2.0
 metadata:
   source_code_uri: https://github.com/misabegovic/enola-rb
+  documentation_uri: https://github.com/misabegovic/enola-rb#readme
   changelog_uri: https://github.com/misabegovic/enola-rb/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/misabegovic/enola-rb/issues
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -70,7 +77,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -80,6 +87,6 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: 'Runs the released enola from Ruby: fetched on first use, verified, cached.
-  This release drives enola 0.4.32.'
+summary: 'Catch architecture regressions in Ruby code against a pinned baseline: runs
+  the released enola 0.4.35, fetched and verified on first use.'
 test_files: []