enola-guides 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 103217d2be760b0b582027a9119e6acc6fae874ffc1171f8e59df35ac5ffb09b
-  data.tar.gz: 65f13f8cd1c54cafec16aca3f50a80710dcc77df8f6e66077c54fb346afeaf3a
+  metadata.gz: df9b7b5b2b3fc6589f9353c4f2198b08283fe80fafd2dacda91dea2d66c5a2fb
+  data.tar.gz: 20172bf3167db5fb3d690d401f3313d38861d10f86f7010607c4ccae98353b68
 SHA512:
-  metadata.gz: 9cac7aed45a1041aeaeb66c46040f165dfa4156b05d5c2c088890dd18912930b6924059b5f0b1bcc00c4379b7574e524ab8794a43c936a5e5915a4afccf7572c
-  data.tar.gz: fe230a7e9daac6c8c88662bdcce76f1be1ff8019992c48f57a95afb469fc4bad58bd02e6171d62603e796b80cd31938826d59a5c8010adada9fa116d5a16e13d
+  metadata.gz: f705dc88218a61a94d6261b624e6744d8fd14212e6524b062f2f9f9520751013968f4a208382861516265ac4ca41db11ca483e09acf52792120aa704f01251a0
+  data.tar.gz: 65b0c4c5cd94ca30b85d3528737489c83c0ff73b8a7b3402dd2d39c45742af8ca679cfaef2ec04ea8837e3ac5d92a1881960b2a7429df198e758ef7b7d8c8435

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.2 (2026-08-22)
+
+One law per file: the Rails shop, the cluster laws, the maintenance-task laws
+and the starter each put every law in a file of its own that declares the parts it
+speaks about, so a reader finds a law by its name and a reviewer sees one
+law per diff.
+
 ## 0.1.1 (2026-08-22)
 
 The laws catalogue: `examples/laws/`, twenty-six complete declarations one

data/README.md

@@ -18,7 +18,7 @@ gem contents enola-guides
 ## Start with an example
 
 [`examples/rails-shop`](examples/rails-shop): a Rails application declaring
-thirteen laws in the Ruby DSL, from "jobs never invoke controller code" to
+thirteen laws in the Ruby DSL, one file each, from "jobs never invoke controller code" to
 "billing keeps to its own tables" and "a mutating action is authorized",
 with Prism and Rubydex configured as providers beside the extractors.
 [`examples/ember-app`](examples/ember-app): an Ember application bound to

data/examples/laws/cluster-laws/README.md

@@ -5,5 +5,5 @@ repositories, mutating actions selected through the routes they handle, and
 routes no loaded client calls. Each refuses by name in a single-repository
 snapshot rather than reporting silence as compliance.
 
-Declaration under `enola/constraints/`. Copy it, run `enola constraints lint .`,
+One file per law under `enola/constraints/`, each file declaring the parts it speaks about. Copy it, run `enola constraints lint .`,
 then `enola --generate . && enola check .`.

data/examples/laws/cluster-laws/enola/constraints/a-mutating-action-is-authorized.rb

@@ -0,0 +1,10 @@
+Enola.architecture "platform" do
+  part :mutating_actions, service: :backend, files: "app/controllers/**", handles: [:post, :put, :patch, :delete]
+  part :policies, service: :backend, files: "app/policies/**"
+
+  law "a mutating action is authorized" do
+    mutating_actions.must_reach :policies
+    why "an action behind a POST, PUT, PATCH or DELETE route changes state, and the policy call is the one place the change is authorized"
+    mode :advisory
+  end
+end

data/examples/laws/cluster-laws/enola/constraints/every-api-route-has-a-consumer.rb

@@ -0,0 +1,9 @@
+Enola.architecture "platform" do
+  part :api, service: :backend, files: "config/**", kind: :route
+
+  law "every api route has a consumer" do
+    api.must_have_consumer
+    why "a route nobody calls is a surface nobody maintains"
+    mode :advisory
+  end
+end

data/examples/laws/cluster-laws/enola/constraints/one-owner-per-table.rb

@@ -0,0 +1,9 @@
+Enola.architecture "platform" do
+  part :tables, files: "app/models/**", kind: :storage
+
+  law "one owner per table" do
+    tables.must_be_unique_across by: :table
+    why "a table two repositories both model is written by two codebases that never see each other's validations or callbacks"
+    mode :advisory
+  end
+end

data/examples/laws/maintenance-tasks/README.md

@@ -5,5 +5,5 @@ depends on, and a boundary against controller code that has no request to
 read. Both were mined from a codebase where they already held, which is the
 right moment to declare a law.
 
-Declaration under `enola/constraints/`. Copy it, run `enola constraints lint .`,
+One file per law under `enola/constraints/`, each file declaring the parts it speaks about. Copy it, run `enola constraints lint .`,
 then `enola --generate . && enola check .`.

data/examples/laws/maintenance-tasks/enola/constraints/a-maintenance-task-never-invokes-controller-code.rb

@@ -0,0 +1,9 @@
+Enola.architecture "app" do
+  part :tasks, files: "app/tasks/**"
+  part :controllers, files: "app/controllers/**"
+
+  law "a maintenance task never invokes controller code" do
+    tasks.must_not_call controllers
+    why "a task runs from the runner or the console with no request around it, so controller code reached from one has nothing to read"
+  end
+end

data/examples/laws/maintenance-tasks/enola/constraints/{maintenance-tasks.rb → every-maintenance-task-lives-in-the-maintenance-namespace.rb}

@@ -1,15 +1,8 @@
 Enola.architecture "app" do
   part :maintenance_tasks, files: "app/tasks/**", kind: :symbol, where: { symbol_kind: "class" }
-  part :tasks, files: "app/tasks/**"
-  part :controllers, files: "app/controllers/**"
 
   law "every maintenance task lives in the Maintenance namespace" do
     maintenance_tasks.names_must_match "Maintenance::*"
     why "the task runner resolves task constants from that namespace, so a task declared outside it never appears in the runner and cannot be run by anyone"
   end
-
-  law "a maintenance task never invokes controller code" do
-    tasks.must_not_call controllers
-    why "a task runs from the runner or the console with no request around it, so controller code reached from one has nothing to read"
-  end
 end

data/examples/rails-shop/enola/constraints/a-concern-never-reaches-the-class-that-includes-it.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  rails
+
+  law "a concern never reaches the class that includes it" do
+    concerns.must_not_reach_includers
+    why "a mixin that knows its includer is half a class in hiding"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/a-mutating-action-is-authorized.rb

@@ -0,0 +1,10 @@
+Enola.architecture "shop" do
+  rails
+  part :mutating_actions, files: "app/controllers/**", handles: [:post, :put, :patch, :delete]
+
+  law "a mutating action is authorized" do
+    mutating_actions.must_reach :policies
+    why "every write passes a policy before it touches a record"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/a-service-answers-to-call.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  part :service_objects, files: "app/services/**", kind: :symbol, where: { symbol_kind: "class" }, owns: :methods
+
+  law "a service answers to call" do
+    service_objects.must_define :call
+    why "one door per service, so a caller never reads it to find the verb"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/background-jobs-never-invoke-controller-code.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  rails
+
+  law "background jobs never invoke controller code" do
+    jobs.must_not_call controllers
+    why "rendering from a job goes through ApplicationController.renderer"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/billing-is-documented.rb

@@ -0,0 +1,10 @@
+Enola.architecture "shop" do
+  part :billing, files: ["app/billing/**", "app/models/invoice.rb"]
+
+  law "billing is documented" do
+    billing.must_be_governed
+    since "2026-09-01"
+    why "code under a decision needs the page that decided it"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/billing-keeps-to-its-own-tables.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  part :billing, files: ["app/billing/**", "app/models/invoice.rb"]
+
+  law "billing keeps to its own tables" do
+    billing.storage_must_stay_home
+    why "a part that writes another part's table owns a bug it cannot see"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/frames-keep-their-query-budget.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  rails
+
+  law "frames keep their query budget" do
+    controllers.must_keep_budget metric: :queries, max: 20
+    why "a frame past twenty queries is a page that will not scale; refused by name until a capture exists"
+    mode :advisory
+  end
+end

data/examples/rails-shop/enola/constraints/jobs-models-and-mailers-never-depend-on-each-other-in-a-circle.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  rails
+
+  law "jobs, models and mailers never depend on each other in a circle" do
+    jobs.must_not_cycle_with :models, :mailers
+    why "parts that reach each other in a circle cannot be taken apart"
+    mode :advisory
+  end
+end

data/examples/rails-shop/enola/constraints/orders-are-reached-through-their-public-surface.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  part :orders, files: ["app/orders/**", "app/models/order.rb"], public: ["app/orders/public/**"]
+
+  law "orders are reached through their public surface" do
+    orders.stays_inside
+    why "the public directory is the contract; everything else may change"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/reach-for-an-existing-service.rb

@@ -0,0 +1,8 @@
+Enola.architecture "shop" do
+  part :service_objects, files: "app/services/**", kind: :symbol, where: { symbol_kind: "class" }, owns: :methods
+
+  law "reach for an existing service" do
+    service_objects.advises "look in app/services before writing a new one"
+    why "duplication is a judgement no fact answers; advice where the edit happens is what can be offered honestly"
+  end
+end

data/examples/rails-shop/enola/constraints/scopes-come-in-pairs.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  part :records, ancestor: "ApplicationRecord"
+
+  law "scopes come in pairs" do
+    records.names_must_match "with_*", requires: "without_*"
+    why "every with_ scope has a without_ sibling, or the query reads half a thought"
+    mode :advisory
+  end
+end

data/examples/rails-shop/enola/constraints/the-public-api-stays-small.rb

@@ -0,0 +1,10 @@
+Enola.architecture "shop" do
+  part :api, files: "config/**", kind: :route
+
+  law "the public api stays small" do
+    api.at_most 120
+    growth 5
+    why "a route is a promise; the count may grow, but only on purpose"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/the-request-api-stays-in-controllers.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  rails
+
+  law "the request api stays in controllers" do
+    models.must_not_call "params", receiver: :none
+    why "params without a receiver is the controller's; a model reading it only works inside a request"
+    mode :ratchet
+  end
+end

data/lib/enola-guides.rb

@@ -2,6 +2,6 @@
 
 module Enola
   module Guides
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

data/templates/constraints-starter/background-jobs-never-invoke-controller-code.rb

@@ -0,0 +1,9 @@
+Enola.architecture "app" do
+  rails
+
+  law "background jobs never invoke controller code" do
+    jobs.must_not_call controllers
+    why "rendering from a job goes through ApplicationController.renderer"
+    mode :ratchet
+  end
+end

data/templates/constraints-starter/models-do-not-reach-controllers.rb

@@ -0,0 +1,9 @@
+Enola.architecture "app" do
+  rails
+
+  law "models do not reach controllers" do
+    models.must_not_call controllers
+    why "a model that knows the request cannot be used off the request"
+    mode :ratchet
+  end
+end

data/templates/constraints-starter/policies-only-answer.rb

@@ -0,0 +1,9 @@
+Enola.architecture "app" do
+  rails
+
+  law "policies only answer" do
+    policies.must_not_call jobs
+    why "authorization is asked many times per request and sometimes speculatively"
+    mode :ratchet
+  end
+end

data/templates/constraints-starter/the-request-api-stays-in-controllers.rb

@@ -0,0 +1,9 @@
+Enola.architecture "app" do
+  rails
+
+  law "the request api stays in controllers" do
+    models.must_not_call "params", receiver: :none
+    why "params without a receiver is the controller's; a model reading it only works inside a request"
+    mode :ratchet
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: enola-guides
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Muhamed Isabegovic
@@ -29,7 +29,9 @@ files:
 - examples/laws/clean-rings/README.md
 - examples/laws/clean-rings/enola/constraints/clean.yaml
 - examples/laws/cluster-laws/README.md
-- examples/laws/cluster-laws/enola/constraints/cluster.rb
+- examples/laws/cluster-laws/enola/constraints/a-mutating-action-is-authorized.rb
+- examples/laws/cluster-laws/enola/constraints/every-api-route-has-a-consumer.rb
+- examples/laws/cluster-laws/enola/constraints/one-owner-per-table.rb
 - examples/laws/cqrs-queries-never-write/README.md
 - examples/laws/cqrs-queries-never-write/enola/constraints/cqrs.yaml
 - examples/laws/foreign-keys/README.md
@@ -39,7 +41,8 @@ files:
 - examples/laws/instantiation/README.md
 - examples/laws/instantiation/enola/constraints/ceremony.yaml
 - examples/laws/maintenance-tasks/README.md
-- examples/laws/maintenance-tasks/enola/constraints/maintenance-tasks.rb
+- examples/laws/maintenance-tasks/enola/constraints/a-maintenance-task-never-invokes-controller-code.rb
+- examples/laws/maintenance-tasks/enola/constraints/every-maintenance-task-lives-in-the-maintenance-namespace.rb
 - examples/laws/mixins-stay-independent/README.md
 - examples/laws/mixins-stay-independent/enola/constraints/concerns.yaml
 - examples/laws/naming-conventions/README.md
@@ -79,7 +82,19 @@ files:
 - examples/laws/vanilla-rails-stays-empty/README.md
 - examples/laws/vanilla-rails-stays-empty/enola/constraints/vanilla.yaml
 - examples/rails-shop/enola.yaml
-- examples/rails-shop/enola/constraints/laws.rb
+- examples/rails-shop/enola/constraints/a-concern-never-reaches-the-class-that-includes-it.rb
+- examples/rails-shop/enola/constraints/a-mutating-action-is-authorized.rb
+- examples/rails-shop/enola/constraints/a-service-answers-to-call.rb
+- examples/rails-shop/enola/constraints/background-jobs-never-invoke-controller-code.rb
+- examples/rails-shop/enola/constraints/billing-is-documented.rb
+- examples/rails-shop/enola/constraints/billing-keeps-to-its-own-tables.rb
+- examples/rails-shop/enola/constraints/frames-keep-their-query-budget.rb
+- examples/rails-shop/enola/constraints/jobs-models-and-mailers-never-depend-on-each-other-in-a-circle.rb
+- examples/rails-shop/enola/constraints/orders-are-reached-through-their-public-surface.rb
+- examples/rails-shop/enola/constraints/reach-for-an-existing-service.rb
+- examples/rails-shop/enola/constraints/scopes-come-in-pairs.rb
+- examples/rails-shop/enola/constraints/the-public-api-stays-small.rb
+- examples/rails-shop/enola/constraints/the-request-api-stays-in-controllers.rb
 - guides/01-start-here.md
 - guides/02-rails.md
 - guides/03-ember.md
@@ -92,7 +107,10 @@ files:
 - recipes/README.md
 - recipes/ember-conventions.yaml
 - recipes/house-recipe-template.yaml
-- templates/constraints-starter.rb
+- templates/constraints-starter/background-jobs-never-invoke-controller-code.rb
+- templates/constraints-starter/models-do-not-reach-controllers.rb
+- templates/constraints-starter/policies-only-answer.rb
+- templates/constraints-starter/the-request-api-stays-in-controllers.rb
 - templates/enola-check.sh
 - templates/enola-cluster.yaml
 - templates/enola-findings.rb

data/examples/laws/cluster-laws/enola/constraints/cluster.rb

@@ -1,24 +0,0 @@
-Enola.architecture "platform" do
-  part :tables, files: "app/models/**", kind: :storage
-  part :mutating_actions, service: :backend, files: "app/controllers/**", handles: [:post, :put, :patch, :delete]
-  part :policies, service: :backend, files: "app/policies/**"
-  part :api, service: :backend, files: "config/**", kind: :route
-
-  law "one owner per table" do
-    tables.must_be_unique_across by: :table
-    why "a table two repositories both model is written by two codebases that never see each other's validations or callbacks"
-    mode :advisory
-  end
-
-  law "a mutating action is authorized" do
-    mutating_actions.must_reach :policies
-    why "an action behind a POST, PUT, PATCH or DELETE route changes state, and the policy call is the one place the change is authorized"
-    mode :advisory
-  end
-
-  law "every api route has a consumer" do
-    api.must_have_consumer
-    why "a route nobody calls is a surface nobody maintains"
-    mode :advisory
-  end
-end

data/examples/rails-shop/enola/constraints/laws.rb

@@ -1,93 +0,0 @@
-# The Ruby DSL, end to end, for a Rails shop. Parsed by enola, never
-# executed. Every sentence below compiles to a rule form the YAML also
-# accepts; `enola constraints lint .` shows what each part resolved to.
-Enola.architecture "shop" do
-  rails
-
-  part :billing, files: ["app/billing/**", "app/models/invoice.rb"]
-  part :orders, files: ["app/orders/**", "app/models/order.rb"], public: ["app/orders/public/**"]
-  part :records, ancestor: "ApplicationRecord"
-  part :mutating_actions, files: "app/controllers/**", handles: [:post, :put, :patch, :delete]
-  part :service_objects, files: "app/services/**", kind: :symbol, where: { symbol_kind: "class" }, owns: :methods
-  part :api, files: "config/**", kind: :route
-  part :tables, files: "app/models/**", kind: :storage
-
-  law "background jobs never invoke controller code" do
-    jobs.must_not_call controllers
-    why "rendering from a job goes through ApplicationController.renderer"
-    mode :ratchet
-  end
-
-  law "the request api stays in controllers" do
-    models.must_not_call "params", receiver: :none
-    why "params without a receiver is the controller's; a model reading it only works inside a request"
-    mode :ratchet
-  end
-
-  law "billing keeps to its own tables" do
-    billing.storage_must_stay_home
-    why "a part that writes another part's table owns a bug it cannot see"
-    mode :ratchet
-  end
-
-  law "orders are reached through their public surface" do
-    orders.stays_inside
-    why "the public directory is the contract; everything else may change"
-    mode :ratchet
-  end
-
-  law "a mutating action is authorized" do
-    mutating_actions.must_reach :policies
-    why "every write passes a policy before it touches a record"
-    mode :ratchet
-  end
-
-  law "a concern never reaches the class that includes it" do
-    concerns.must_not_reach_includers
-    why "a mixin that knows its includer is half a class in hiding"
-    mode :ratchet
-  end
-
-  law "jobs, models and mailers never depend on each other in a circle" do
-    jobs.must_not_cycle_with :models, :mailers
-    why "parts that reach each other in a circle cannot be taken apart"
-    mode :advisory
-  end
-
-  law "a service answers to call" do
-    service_objects.must_define :call
-    why "one door per service, so a caller never reads it to find the verb"
-    mode :ratchet
-  end
-
-  law "scopes come in pairs" do
-    records.names_must_match "with_*", requires: "without_*"
-    why "every with_ scope has a without_ sibling, or the query reads half a thought"
-    mode :advisory
-  end
-
-  law "the public api stays small" do
-    api.at_most 120
-    growth 5
-    why "a route is a promise; the count may grow, but only on purpose"
-    mode :ratchet
-  end
-
-  law "frames keep their query budget" do
-    controllers.must_keep_budget metric: :queries, max: 20
-    why "a frame past twenty queries is a page that will not scale; refused by name until a capture exists"
-    mode :advisory
-  end
-
-  law "billing is documented" do
-    billing.must_be_governed
-    since "2026-09-01"
-    why "code under a decision needs the page that decided it"
-    mode :ratchet
-  end
-
-  law "reach for an existing service" do
-    service_objects.advises "look in app/services before writing a new one"
-    why "duplication is a judgement no fact answers; advice where the edit happens is what can be offered honestly"
-  end
-end

data/templates/constraints-starter.rb

@@ -1,30 +0,0 @@
-# A first declaration for a Rails application. Copy to enola/constraints/
-# and keep the laws you agree with; every law carries its reason, and
-# ratchet mode fails only what a change adds.
-Enola.architecture "app" do
-  rails
-
-  law "background jobs never invoke controller code" do
-    jobs.must_not_call controllers
-    why "rendering from a job goes through ApplicationController.renderer"
-    mode :ratchet
-  end
-
-  law "models do not reach controllers" do
-    models.must_not_call controllers
-    why "a model that knows the request cannot be used off the request"
-    mode :ratchet
-  end
-
-  law "policies only answer" do
-    policies.must_not_call jobs
-    why "authorization is asked many times per request and sometimes speculatively"
-    mode :ratchet
-  end
-
-  law "the request api stays in controllers" do
-    models.must_not_call "params", receiver: :none
-    why "params without a receiver is the controller's; a model reading it only works inside a request"
-    mode :ratchet
-  end
-end