enola-guides 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76f0a1325c41c7ff90c0e6a2b2952cd597ed7496103df0e6756ad197855da705
-  data.tar.gz: 2bb8581b18beb14dec24dc2b61df053768ee8dea9378bf7d10fa43e5b74000c8
+  metadata.gz: 4da894ee2a8bbae62bfd0c91d741184cb544ab52c7daa172cc4d29d6760b0e88
+  data.tar.gz: 57a1e3127acc18cfae45d00e8d68d980ca5884dea25c0edd616fff96816b4c02
 SHA512:
-  metadata.gz: 845c312c4126618fa265248d19b3a515c47d854c830616d03d1254c9f42df4a6ce1b263fa77b431b1eaa6d64a58e8a7684dbc98d79a8fe590c5c3d20bde366d2
-  data.tar.gz: 6de47b842e40351d514f84b3af1d4b2bd4e5e2145f1f9c329521e251bc9a36842cdde9f41b1c1edbff306b231777b91c5d189ea5b79098453a45de0dde1c639e
+  metadata.gz: 30fbd5e723192833b38e5e7108cdfab7dc48c8604a614c58a07c1d3c39c8fef2c3f4c941667fd67011fa93865d75891d0804479cbf79b909d3d42cad41c014c4
+  data.tar.gz: 8cb01c56994da025c7493b7c8e7ecfa9197b5f19a331c4722cbe9776e2a32d713514251ce1d6d0cae437b24707bf38b901682e0db101f20222281693833d5ba6

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 (2026-08-22)
+
+First content. Eight guides (start here, a Rails application, an Ember
+application, writing laws, constraints in CI, hooks and agents,
+providers, beyond one repository), two worked examples (a Rails shop in
+the Ruby DSL with Prism and Rubydex as providers; an Ember app bound to
+the conventions recipe), four agent skills (enola, enola-laws,
+enola-grade-before-push, enola-intent-first), the CI check template with
+its renderer, a cluster configuration, a constraints starter, and two
+recipes. Written against the release of enola that carries the
+constraints vocabulary (enola-labs/enola#247).
+
+## 0.0.0
+
+Placeholder to claim the name.

data/README.md

@@ -1,12 +1,61 @@
 # enola-guides
 
-Guides, presets and onboarding material for
-[enola](https://github.com/enola-labs/enola), the architecture-graph tool,
-written for Ruby and Rails developers first.
+How to use what is landing in [enola](https://github.com/enola-labs/enola)
+([enola-labs/enola#247](https://github.com/enola-labs/enola/pull/247)): a
+Ruby DSL for writing architecture constraints, Prism and Rubydex as
+providers that run together with enola's own extractors, recipes a team
+reviews, laws that read the whole graph, and an MCP your agent uses during
+a session. Guides, worked examples, skills and templates, packaged as a
+gem so a team can pin the guidance it adopted. Rubyists first; consumed by
+[enola-rb](https://github.com/misabegovic/enola-rb), the gem that runs
+enola. Expanding as the practice does.
 
-Ready-to-use templates, presets, skills and instructions: how to use enola on
-a Rails app, on Ember, as a constraints gate in CI, and through hooks and
-agent skills. Consumed by [enola-rb](https://github.com/misabegovic/enola-rb),
-the gem that runs enola.
+```bash
+gem install enola-guides
+gem contents enola-guides
+```
 
-Placeholder release. No content yet.
+## 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
+"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
+the conventions recipe in one block.
+
+## Guides
+
+1. [Start here](guides/01-start-here.md): install, snapshot, baseline, a
+   graded change, the hooks, a first law. Ten minutes.
+2. [A Rails application](guides/02-rails.md): what enola measures, the
+   Prism and Rubydex providers, the recipe, the laws a Rails team writes.
+3. [An Ember application](guides/03-ember.md): the Ember facts, the
+   conventions as a recipe, an app inside a larger repository.
+4. [Writing laws](guides/04-writing-laws.md): parts, the twenty-one
+   sentences, modes, dates, exemptions, what a refusal means.
+5. [Constraints in CI](guides/05-constraints-in-ci.md): the check step.
+6. [Hooks and agents](guides/06-hooks-and-agents.md): the session hooks,
+   the MCP tools, the skills.
+7. [Providers](guides/07-providers.md): the seam, the Ruby pair, the
+   census, the runtime capture.
+8. [Beyond one repository](guides/08-beyond-one-repo.md): the cluster, the
+   seams, the laws across them, the history.
+
+## Skills
+
+The skills under [`templates/skills/`](templates/skills) are the ones used
+day to day with enola's MCP in an agent session: `enola` (ask the graph
+before grepping, grade after changing), `enola-laws` (write a law as a
+sentence with a reason, lint it, read what it verdicts),
+`enola-grade-before-push` (the delta is the deliverable, a declined grade
+is not a pass), `enola-intent-first` (read the governing decision before
+the file moves). Copy a directory into your agent's skills folder.
+
+## Templates and recipes
+
+[`templates/`](templates): the CI check script and its comment renderer,
+a cluster configuration, a constraints starter. [`recipes/`](recipes/README.md):
+recipes a repository copies into its own `enola/recipes/` and binds in one
+line, starting with the Ember conventions and a house-recipe template;
+starting points the team reviews, never defaults the tool applies.

data/examples/ember-app/enola/constraints/ember.yaml

@@ -0,0 +1,10 @@
+# The Ember conventions bound in one block. The recipe is copied from
+# enola-guides' recipes/ into this repository's enola/recipes/, where the
+# team reviews it; the two optional roles are bound to this app's helpers.
+use_recipe:
+  - recipe: ember-conventions
+    as: app
+    mode: ratchet
+    bind:
+      task-factories: { match: ["app/utils/**"], name_pattern: "*.trackedFunction" }
+      fixture-setup: { match: ["tests/helpers/**"] }

data/examples/ember-app/enola/recipes/ember-conventions.yaml

@@ -0,0 +1,83 @@
+recipe: ember-conventions
+roles:
+  - name: components
+    match: ["app/components/**"]
+  - name: integration-tests
+    kind: test_ref
+    match: ["tests/integration/**"]
+  - name: actions
+    kind: symbol
+    where: { decorators: action }
+  - name: framework-controllers
+    kind: symbol
+    where: { superclass_module: "@ember/controller" }
+  - name: constructors
+    match: ["app/**"]
+    name_pattern: "*.constructor"
+  - name: fetchers
+    match: ["app/services/**"]
+  - name: legacy-accessor
+    match: ["app/utils/**"]
+    name_pattern: "*.get"
+  - name: argument-mutators
+    kind: symbol
+    where: { fields_written: args }
+  - name: element-modifiers
+    kind: symbol
+    match: ["app/components/**", "app/modifiers/**"]
+  - name: state-writing-members
+    kind: symbol
+    where: { fields_written: "<any>" }
+  - name: task-factories
+    optional: true
+  - name: fixture-setup
+    optional: true
+rules:
+  - id: no-action-decorator
+    forbid_fact: actions
+    because: "An arrow function binds lexically and needs no decorator; the decorator predates it and the convention says to stop writing it."
+
+  - id: no-framework-controllers
+    forbid_fact: framework-controllers
+    because: "A route component replaces the controller and its template. Controllers are quirky and carry surprising singleton state, and the convention is to stop adding them."
+
+  - id: components-import-no-render-modifiers
+    forbid: components
+    to_name: ["@ember/render-modifiers*", "ember-render-helpers*"]
+    via: imports
+    because: "The render-helper form fires on a lifecycle rather than attaching to the element it acts on, and it has been discouraged for years. A named modifier attaches to the element and says what it acts on."
+
+  - id: constructors-do-not-fetch
+    forbid: constructors
+    to: fetchers
+    via: calls
+    because: "Rendering pulls data in as it is needed. A constructor that fetches is eager, runs before anything asks, and cannot be re-run when the arguments change."
+
+  - id: no-legacy-property-accessor
+    forbid: components
+    to: legacy-accessor
+    via: calls
+    because: "The proxy accessor reads through a layer that no longer exists on a resolved value, and it defeats type checking. Reach for the property."
+
+  - id: arguments-are-not-mutated
+    forbid_fact: argument-mutators
+    because: "Data flows down and actions flow up. A component that writes through its own arguments changes state it does not own, and the owner never learns of it. Pass a callback and let the owner make the change."
+
+  - id: a-modifier-takes-its-element
+    require: element-modifiers
+    when_edge_to: ["*.modifier"]
+    via: calls
+    must_prop_contain: { prop: takes_parameters, value: "yes" }
+    because: "A modifier is handed the element it is attached to. One that declares no parameter is not modifying anything; it is a side effect fired by render, and a getter or a tracked task says that honestly."
+
+  - id: derivations-do-not-write
+    forbid: state-writing-members
+    to: task-factories
+    via: calls
+    because: "A task is derived state and runs inside the render cycle. Writing the component's own state from one schedules another render off the render it is running in. Return the data and read it through the task's value instead."
+
+  - id: component-tests-carry-no-fixtures
+    forbid: integration-tests
+    to: fixture-setup
+    via: calls
+    because: "A fixture library sets up back-end state and has no place in a component test: if the component makes no request, build a front-end record, and if it does, let the acceptance layer answer it."

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

@@ -0,0 +1,93 @@
+# 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/examples/rails-shop/enola.yaml

@@ -0,0 +1,9 @@
+# Providers run beside enola's own extractors at snapshot time and their
+# facts land in the same graph. Prism needs a Ruby 3.3+ on PATH; Rubydex
+# runs inside the binary after `enola providers fetch rubydex`.
+providers:
+  - name: prism
+    command: ["ruby", "examples/providers/ruby/prism/enola_prism_provider.rb"]
+    expected_version: "0.1.0"
+  - name: rubydex
+    expected_version: "0.4.0"

data/guides/01-start-here.md

@@ -0,0 +1,136 @@
+# Start here: the first useful answer in ten minutes
+
+enola answers one question no linter can: **what did this change do to the
+architecture?** It builds a graph of your code (modules, symbols, routes,
+tables, and how they depend on each other), keeps that graph as a snapshot,
+and grades a change by comparing the snapshot before it with the snapshot
+after it. A dependency cycle that spans four files, a job that started
+calling a controller, a table a second part began writing to: those are
+invisible to tools that look at one file at a time, and they are what enola
+reports.
+
+This guide takes you from nothing to a graded change. Everything here is
+written for the release that carries the constraints vocabulary (the one
+this repository's recipes and templates target); if your `enola --version`
+is older, upgrade first.
+
+## 1. Install
+
+No Go toolchain, no compiler, one binary:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/enola-labs/enola/main/install.sh | sh
+enola --version
+```
+
+If your application is Ruby, fetch the Rubydex engine once so enola can
+resolve constants and ancestry through Ruby's own rules (more in
+[providers](07-providers.md)):
+
+```bash
+enola providers fetch rubydex
+enola providers list
+```
+
+## 2. Look before you configure
+
+One read-only command, nothing written:
+
+```bash
+enola --explain .
+```
+
+It prints the architecture it detected (pattern, cycles, layer
+violations), the coupling hotspots with their blast radius, and the code
+health findings. Nothing here is a setting: enola detects every language
+in the tree and indexes all of them into one graph.
+
+## 3. Take the first snapshot
+
+```bash
+enola --generate .
+```
+
+This writes `.enola/` in the repository (add it to `.gitignore`): the
+facts, the findings the explainers computed, and a receipt saying which
+extractors and providers ran and what they skipped. Read the receipt's
+census when something looks missing: a file enola did not parse is named
+there, never silently dropped.
+
+## 4. Pin a baseline, change something, grade it
+
+```bash
+enola baseline pin .
+# ... edit code ...
+enola --generate .
+enola check .
+```
+
+`check` compares the current snapshot with the pinned one and prints what
+the change did: findings introduced, findings resolved, edges added. It
+exits 0 unless you tell it what fails the build:
+
+```bash
+enola check -fail-on constraints,cycles,layers .
+```
+
+Two outcomes are not verdicts, and the output says so: **DECLINED** means
+the two snapshots are not comparable (a different enola version, a
+provider that ran on one side only, changed ignore globs), so re-pin the
+baseline rather than reading it as a pass; **unevaluable** on a rule means
+the snapshot could not answer that rule (no resolved ancestry, no runtime
+capture, one repository where two are needed), named with its cause.
+
+## 5. Tell your agents
+
+```bash
+enola install --hooks
+enola doctor
+```
+
+`install` writes enola's instructions into the files your coding agents
+already read and, with `--hooks`, adds a session-start hook that restores
+the snapshot and a session-end hook that grades the session's delta. It
+previews every change and asks before writing; `enola uninstall` reverses
+it byte for byte. `doctor` reports whether the hooks actually fired, which
+version you run, and whether the Rubydex library is in place. Your agent
+gets a map it can query instead of grepping; the [hooks and agents
+guide](06-hooks-and-agents.md) says what to put in its skill.
+
+## 6. Declare your first law
+
+```bash
+enola constraints init .
+enola constraints lint .
+```
+
+`init` writes a starter declaration bound to the recipes whose roles your
+tree has (controllers, models, jobs for a Rails app) and refuses to
+overwrite one that exists. `lint` shows what each part resolved to. Then
+write one law of your own in Ruby, in `enola/constraints/`:
+
+```ruby
+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
+```
+
+`ratchet` reports what already breaks the law and fails only what a
+change adds, which is the mode to start every law in. The [writing laws
+guide](04-writing-laws.md) has the whole vocabulary.
+
+## Where next
+
+- [A Rails application](02-rails.md): what enola measures in one, the
+  providers that sharpen it, the recipe that names its parts.
+- [An Ember application](03-ember.md): the same for the front end.
+- [Constraints in CI](05-constraints-in-ci.md): the check step, with a
+  template you copy.
+- [Beyond one repository](08-beyond-one-repo.md): the cluster, and the laws
+  that only make sense across it.

data/guides/02-rails.md

@@ -0,0 +1,168 @@
+# A Rails application
+
+What enola sees in a Rails app, what the two Ruby providers add, and how
+to go from the first snapshot to laws the team wrote.
+
+## What the snapshot holds
+
+From the Ruby extractor alone:
+
+- **Symbols** for every class, module and method, with their calls,
+  constant references and one-level superclass.
+- **Routes** from `config/routes.rb` and every engine's route file,
+  `resources` expanded, each route carrying its method and path and a
+  `handled_by` edge to the controller action that serves it.
+- **Storage** facts for every `ApplicationRecord` descendant: the model,
+  its table (declared or derived), its columns and foreign keys when the
+  schema is present.
+- **Associations** with their macro, target and whether the target was
+  declared (`class_name:`) or derived from the name.
+- **Module edges** between directories, weighted by the symbol edges
+  behind them, which is what cycle detection reads.
+
+Run `enola --explain .` and then `enola --generate .`; the receipt in
+`.enola/receipt.json` lists what each extractor parsed and skipped.
+
+## The two providers
+
+Two things the extractor does not settle are settled by providers, which
+enola runs at snapshot time beside its own extraction:
+
+- **Prism** reads every file with Ruby's own parser and adds the call edges
+  a lexical walk can see. It needs a Ruby 3.3 or newer on PATH (Prism is a
+  default gem), nothing else:
+
+  ```yaml
+  providers:
+    - name: prism
+      command: ["ruby", "/path/to/enola_prism_provider.rb"]
+      expected_version: "0.1.0"
+  ```
+
+- **Rubydex** resolves constants through nesting and inheritance, types the
+  receiver of a call, and linearises every class's ancestry with mixins in
+  order. It runs inside the enola binary against an engine library fetched
+  once, with no Ruby involved, and reads your bundle's gem paths when
+  `bundle` is on PATH so `ApplicationRecord` and `ViewComponent::Base`
+  resolve:
+
+  ```bash
+  enola providers fetch rubydex
+  ```
+
+  ```yaml
+  providers:
+    - name: rubydex
+      expected_version: "0.4.0"
+  ```
+
+The configuration lives in `enola.yaml` (or `mcp-arch.yaml`) at the
+repository root. With both providers a law can say "every class under
+`ApplicationRecord`" and mean the resolved chain, not the text after `<`.
+The [providers guide](07-providers.md) covers the census, the named skips,
+and the runtime capture.
+
+## Name the parts
+
+`enola constraints init .` writes `enola/constraints/init.yaml` binding the
+recipes whose roles your tree has. For a Rails app that is
+`rails-conventions`:
+
+```yaml
+use_recipe:
+  - recipe: rails-conventions
+    as: rails
+    mode: ratchet
+    bind:
+      controllers: { match: ["app/controllers/**"] }
+      jobs: { match: ["app/jobs/**"] }
+      models: { match: ["app/models/**"] }
+      mailers: { match: ["app/mailers/**"] }
+      policies: { match: ["app/policies/**"] }
+      serializers: { match: ["app/serializers/**"] }
+      view-components: { match: ["app/components/**"] }
+```
+
+Two roles are optional and off until you bind them: `helpers` and
+`services`. Binding them brings three more laws (services and models
+never reach helpers; the controller's request API stays out of models and
+services). `rails-strict` is the same set with the concerns law added and
+nothing advisory. `vanilla-rails` is for an app that keeps Rails plain and
+wants its extra directories to stay empty with a stated reason each.
+
+`enola constraints lint .` shows every part with what it resolved to and
+every rule a binding left unexpanded, which is how you check the tree
+before the first verdict.
+
+## The laws a Rails team writes
+
+The recipe's laws, each with the reason it carries:
+
+- jobs do not reach controllers (advisory, because the sanctioned path
+  through `ApplicationController.renderer` reads as a crossing);
+- models do not reach controllers;
+- policies only answer, never enqueue;
+- mailers do not enqueue;
+- serializers do not reach controllers;
+- view components do not enqueue and do not reach controllers;
+- maintenance tasks do not reach controllers;
+- with `helpers` bound: services and models never reach helpers;
+- with `services` bound: the request API (`params`, `session`, `render`,
+  `redirect_to`, `cookies`, `flash`) stays in controllers, stated as
+  receiver-less calls so `request.params` on a typed receiver is not a
+  breach.
+
+Write your own beside them in Ruby, in any file under `enola/constraints/`:
+
+```ruby
+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/**"]
+
+  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 "a mutating action is authorized" do
+    part :mutating_actions, files: "app/controllers/**",
+                            handles: [:post, :put, :patch, :delete]
+    mutating_actions.must_reach :policies
+    why "every write passes a policy before it touches a record"
+    mode :ratchet
+  end
+end
+```
+
+The first law reads the storage facts: a member of `billing` reaching
+`Order` is a breach that names the table `orders`, and the suggested cut
+names the `orders` part's public member that already uses the model. The
+second selects the code behind POST, PUT, PATCH and DELETE routes through
+the `handled_by` edges and demands a call into the policies, so the law
+follows the routes rather than a list of actions.
+
+## Read a verdict
+
+```bash
+enola baseline pin .
+# change something
+enola --generate . && enola check .
+```
+
+A constraint breach names the rule, the member, the edge and the reason,
+leads its suggested actions with the smallest change the graph can see,
+and says whether it is a decided-rule breach (exact membership over a
+measured edge) or an advisory. `enola constraints explain app/jobs/x.rb`
+answers what a file is a member of, by which selector, and which edges it
+makes, which is the question to ask before arguing with a verdict.
+
+## When the answer is "cannot evaluate"
+
+A law over resolved ancestry without the Rubydex provider, a budget
+without a runtime capture, a law across repositories in a one-repository
+snapshot: each is reported as unevaluable with its cause and emits no
+verdict. That is the design. A law nobody could measure must not read as
+kept.