@suss/adapter-ruby 0.3.2-0 → 0.5.0

package/README.md

@@ -32,6 +32,126 @@ What a body does still goes unread. Reading it needs the path engine: statements
 
 One thing the walk deliberately leaves out. A `field` declared on a base object type is not discovered on its subclasses. That would change which units exist rather than what each one says about itself, and it is a separate piece of work.
 
+## What a body lowers to
+
+The adapter lowers a method body into the statement form the shared path
+engine in `@suss/extractor` walks, the same engine the Python and TypeScript
+adapters use. It is generic over the language's own condition handle and never
+looks inside one, so the enumeration and the negation of an earlier arm are
+shared rather than written again here.
+
+| Ruby | Lowers to |
+| --- | --- |
+| `if` / `elsif` / `else`, `unless` | one `if` per test, with the elsif chain nested into the else arm |
+| `while`, `until`, `for` | `loop` |
+| a call with a `do` block, such as `items.each do \|i\|` | `loop`, because the block runs per iteration |
+| `begin` / `rescue` / `ensure` | `try` |
+| `case` / `when` / `else` | `switch`, with `else` as the default group |
+| `return`, `raise`, `break`, `next` | `exit` |
+| anything else | `opaque` |
+
+Three things read differently from Python, and each one is why this file
+exists rather than a shared lowering:
+
+- **`raise` is an ordinary method call**, not a keyword, so a throw is
+  recognised by the call's name rather than by a node type.
+- **A `return` inside a `do` block returns from the method**, so the scan
+  descends into one. A lambda captures its own return, so the scan stops
+  there.
+- **A method returns its last expression** with no `return` written, which
+  Python has no equivalent of.
+
+### Keying anything on a node
+
+tree-sitter hands back a fresh wrapper object every time a child is read, so
+two reads of one node are never `===` and a plain `Set` or `Map` keyed on a
+node matches nothing. Use `NodeSet` and `NodeMap`, which key on the node id.
+`npm run check:style` fails a build that keys either on a node.
+
+## Finding the definition behind a constant
+
+Ruby has no imports. A file says `require` to load another file, and after
+that every constant either one defines is reachable by name, so which file a
+name came from is settled by where the constant is defined rather than by
+anything written at the reading site. The other two adapters emit `imports`
+and this one binds a reference straight to its definition.
+
+Lookup follows Ruby's own rule. A name written inside `module Types; class
+Wrapper` is looked for as `Types::Wrapper::Order`, then `Types::Order`, then
+`Order`, and the first one that settles wins:
+
+```ruby
+module Types
+  class Order; end
+  class Wrapper
+    def build
+      Order      # Types::Order, not the top-level one
+    end
+  end
+end
+```
+
+A name two files define under the same nesting says nothing, because choosing
+between them would be a guess. Neither does a constant built at run time
+through `const_set` or `Object.const_get`, which nothing here reads.
+
+The definitions are collected per file and matched afterwards, since which
+file defines a constant is only settled once every file has been read.
+
+## What a class inherits
+
+A class says which class it extends, twice. `extends` points at whatever the
+superclass name binds to, so the shared rules find a method a base class
+declares on a subclass that never overrode it. `extendsNamed` keeps the name
+as written, because a base class the project does not declare, like
+`ActiveRecord::Base`, has no node in the run to point at:
+
+```ruby
+class Order < ApplicationRecord
+end
+```
+
+```
+extends       order.rb:0-31  order.rb#ApplicationRecord
+extendsNamed  order.rb:0-31  ApplicationRecord
+```
+
+A pack matching a library base class reads the second one, and follows the
+first to keep going up.
+
+## What a body does with the database
+
+Ruby writes no return type, so the Python adapter's trick of reading what a
+method says it gives back has no counterpart here. A pack says which base
+class the library gives a model instead:
+
+```ts
+storage: [
+  {
+    baseClasses: ["ActiveRecord::Base"],
+    writes: ["update", "destroy", "save", "create", "delete_all"],
+    storageSystem: "postgres",
+  },
+]
+```
+
+A call matches when the constant its receivers start at reaches one of those
+base classes. Rails puts its own class in between, and following `extends`
+through the project and matching `extendsNamed` at the library takes care of
+that:
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base; end
+class Order < ApplicationRecord; end
+
+Order.where(id: 1).first   # one read, against Order, picking rows by id
+```
+
+A chain is one thing the code does, so that counts once. The method the chain
+ends with tells a read from a write, and the keywords along it become the
+selector. `fields` comes back empty, and a call on anything that is not a
+constant says nothing, since there is no class to ask about.
+
 ## Where it fits in suss
 
 Depends on `@suss/extractor` (for `RawCodeStructure` / `assembleSummary`), `@suss/behavioral-ir`, `@suss/datalog` (for the fact database), and `web-tree-sitter`. Framework packs under `packages/framework/*` (starting with `@suss/framework-graphql-ruby`) consume its `RubyPack` contract; nothing in this package knows what any particular library's classes or DSL calls are named beyond graphql-ruby's own `field` / `argument` / `type` verbs, which the discovery logic reads structurally rather than through pack configuration.