@suss/adapter-ruby 0.3.2-0 → 0.4.0

package/README.md

@@ -32,6 +32,72 @@ 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.
+
 ## 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.