@suss/adapter-ruby 0.33.1 → 0.34.1

package/dist/index.d.cts

@@ -1,15 +1,25 @@
 import { Database } from '@suss/datalog';
 import { Tree, Node } from 'web-tree-sitter';
 export { Node as RbNode, Tree as RbTree } from 'web-tree-sitter';
-import { TypeShape, Effect, BehavioralSummary } from '@suss/behavioral-ir';
-import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions } from '@suss/extractor';
-import { WhyExplained } from '@suss/resolution';
+import { TypeShape, RequestSpellingMetadata, Effect, BehavioralSummary } from '@suss/behavioral-ir';
+import { UnwrapsByName, WhyExplained } from '@suss/resolution';
+import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions, DeclaredModule, KeptParses } from '@suss/extractor';
 import { Value } from '@suss/values';
 
 /**
- * A new `Parser` for every call, so that parses running at the same time do
- * not fight over one parser's mutable `language` field. The compiled `Language`
- * is loaded once per process and shared.
+ * Loads the Ruby grammar into web-tree-sitter and parses source with it.
+ *
+ * tree-sitter runs as WASM, so the package needs no native build step.
+ * The rest of the adapter never imports `web-tree-sitter` directly. It
+ * goes through `parseRuby` and the node helpers, so moving to a different
+ * Ruby grammar would change only this module. The Python adapter's
+ * parser works the same way.
+ */
+
+/**
+ * Uses a new `Parser` for every call, so two parses running at once never
+ * share one parser's mutable `language` field. The compiled `Language` is
+ * loaded once per process and shared.
  */
 declare function parseRuby(source: string): Promise<Tree>;
 /**
@@ -30,6 +40,13 @@ interface Range {
     end: number;
 }
 declare function field(node: Node, name: string): Node | null;
+/**
+ * A node's named children, and nothing for an absent node. Every read of
+ * children in this adapter goes through here or `allChildren`, because the
+ * library's `namedChildren` and `children` getters keep the array on the
+ * node, and the run keeps every root to the end.
+ */
+declare function children(node: Node | null | undefined): Node[];
 declare function bodyStatements(body: Node): Node[];
 /**
  * Every statement written directly inside a branching statement's
@@ -38,40 +55,44 @@ declare function bodyStatements(body: Node): Node[];
  * included; the caller descends into that one itself.
  */
 declare function nestedStatements(stmt: Node): Node[];
-/** What a pack says about one call whose block runs as part of the body around it, with the fields it left out settled. */
+/** A pack's declaration of one body-block call, with its optional flags defaulted. */
 interface BodyBlockKind {
-    /** Whether the library only gives the call to a module, so a class writing the same name means something else. */
+    /** Whether the library offers the call only to modules. In a class, a call of the same name is something else. */
     readonly moduleOnly: boolean;
-    /** Whether a `def` in the block declares a method on the class itself rather than on an instance. */
+    /** Whether a `def` in the block defines a method on the class itself instead of on an instance. */
     readonly definesClassMethods: boolean;
 }
 /**
- * The calls a run's packs say run their block as part of the class or
- * module body it is written in, by the name a project writes. Ruby
- * defines no such call, so this is empty until a pack declares one.
+ * The calls whose block runs as part of the surrounding class or module
+ * body, keyed by the call's name as a project writes it. Ruby has no such
+ * call of its own, so this is empty unless a pack declares one.
  */
 type BodyBlocks = ReadonlyMap<string, BodyBlockKind>;
-/** A call whose block is the thing being configured rather than a place statements run. */
+/** Whether a call's block configures the call itself, so its statements are not part of the body. */
 type BlockConfigures = (call: Node) => boolean;
 /**
  * Every statement a body runs, in source order. Ruby runs a class body
- * like any other code, so a declaration can sit inside an `if`, a
- * `.each` block, a `begin` or a `class_eval`, and taking the body's own
- * child list finds the first spelling and loses the rest in silence.
+ * like any other code, so a declaration can be inside an `if`, an `.each`
+ * block, a `begin` or a `class_eval`. Reading only the body's direct
+ * children would miss those without any sign.
  *
- * `blockConfigures` says which calls keep their block to themselves.
- * `field :x, String do argument :q, String end` declares an argument on
- * the field, not on the class, so that block is not part of the body.
+ * `blockConfigures` picks out the calls whose block is not part of the
+ * body. `field :x, String do argument :q, String end` declares an
+ * argument on the field, so that block is skipped.
  */
 declare function runStatements(body: Node, blockConfigures?: BlockConfigures): Node[];
 /** The text inside a plain string node, with the quotes removed. A string with interpolation returns null. */
 declare function stringLiteralValue(node: Node): string | null;
-/** tree-sitter-ruby leaves the leading colon in a `simple_symbol`'s text, but not in a `hash_key_symbol`'s. */
+/** A `simple_symbol`'s name without its leading colon, or null for any other node. */
 declare function symbolValue(node: Node): string | null;
-/** A `pair` node's key, when it is written as the bare `key:` shorthand. Null for a pair keyed by a string or an expression. */
+/** A `pair` key's name when it is written as `key:`, or null for a key written as a string or an expression. */
 declare function hashKeySymbolName(node: Node): string | null;
 declare function booleanLiteralValue(node: Node): boolean | null;
-/** Keyword arguments turn up as `pair` nodes directly among the argument list's children, rather than wrapped in a hash node. */
+/**
+ * A call's arguments, split into positional and keyword. tree-sitter puts
+ * keyword arguments in the argument list as `pair` nodes, with no hash
+ * node around them. Only keys written as `key:` are read.
+ */
 interface CallArgs {
     positional: Node[];
     keyword: Record<string, Node>;
@@ -79,83 +100,96 @@ interface CallArgs {
 declare function readCallArgs(argumentList: Node | null): CallArgs;
 
 /**
- * Finds the file behind a constant.
+ * Finds the file that defines a constant.
  *
- * A Ruby codebase locates that file by a naming convention rather than through a
- * load graph a static reader could follow, so we build one path from the
- * constant's own name and look for it under the configured root and the
+ * A Ruby codebase finds that file by a naming convention, with no load
+ * graph a static reader could follow. So the adapter builds one path from
+ * the constant's name and looks for it under the configured root and the
  * directories Rails autoloads from. No other spelling is tried.
  */
-/** A pack picks a convention by name, and the code for each one lives here. */
+/** A pack picks a convention by name, and `PATH_CONVENTIONS` maps each name to its code. */
 type ConstantPathConvention = "railsUnderscore";
 /**
- * Ported from ActiveSupport's own `String#underscore`, which is what
- * Rails autoloading runs a constant path through. An acronym the
- * project registers with the inflector is one word to it, so with
- * `ActivityPub` registered the path is `activitypub`, not
- * `activity_pub`.
+ * A port of ActiveSupport's `String#underscore`, which Rails autoloading
+ * runs a constant path through. The inflector treats an acronym the
+ * project registers as one word, so with `ActivityPub` registered the
+ * path is `activitypub` and never `activity_pub`.
  */
 declare function underscoreConstantPath(qualifiedName: string, acronyms?: readonly string[]): string;
 /**
- * Null when there is no file at that path. Rails autoloads from every
- * directory directly under `app`, so `ApplicationController` is
- * `app/controllers/application_controller.rb` and not
- * `app/application_controller.rb`; those directories are tried after
- * the root itself, in name order, and no other spelling is tried.
+ * What constant lookups have read from the disk during one run. A run
+ * looks the same names up many times, and files do not change while it
+ * reads them, so each directory list and each answer is read once. Each
+ * run makes its own, so the MCP server and watch mode see a file added
+ * since the last run.
+ */
+interface ConstantFileCache {
+    /** The directories a constant is looked for in under each root, in the order they are tried. */
+    readonly autoloadDirectories: Map<string, readonly string[]>;
+    /** The file each root and relative path resolved to, or null. */
+    readonly resolved: Map<string, string | null>;
+}
+declare function createConstantFileCache(): ConstantFileCache;
+/**
+ * The file that defines a constant under `root`, or null when there is
+ * none. Rails autoloads from every directory directly under `app`, and
+ * from each `concerns` directory under those, so `ApplicationController`
+ * is `app/controllers/application_controller.rb` and `Archivable` can be
+ * `app/models/concerns/archivable.rb`. The root is tried first, then the
+ * directories under it in name order, then their `concerns` directories
+ * in the same order. Rails' own autoload glob lists them in that order.
+ * Paths a project adds, such as `lib`, come last.
  */
-declare function resolveConstantFile(root: string, qualifiedName: string, convention: ConstantPathConvention, acronyms?: readonly string[]): string | null;
+declare function resolveConstantFile(root: string, qualifiedName: string, convention: ConstantPathConvention, acronyms?: readonly string[], cache?: ConstantFileCache, autoloadRoots?: readonly string[]): string | null;
 
 /**
- * The method names a class gets under a name the source computes.
+ * The methods a class defines under a name the source computes.
  *
  * `KEYS.each { |key| define_method(key) { ... } }` defines one method
  * per element of `KEYS`, and a reader of `def` nodes sees none of them.
- * Reading the names lets a lookup for a name none of them defines carry
- * on up the ancestry instead of stopping at the class.
+ * Knowing the names lets a lookup for any other name continue up the
+ * ancestry instead of stopping at the class.
  *
- * Which calls those are, and what each name is written as, arrive as
- * `definesMethodFrom` and `nameTurnsOn`, so this reads no source of its
- * own. Each name goes through the shared value evaluator, which follows
- * names and constants across the whole run. A name read only in part
+ * The calls and their name expressions come in as `definesMethodFrom`
+ * and `nameTurnsOn` facts, so this module never reads source itself. Each
+ * name goes through the shared value evaluator, which follows names and
+ * constants across the whole run. A name that settles only in part
  * becomes a pattern the whole name has to match.
  */
 
 /** What the dynamic definitions in one class define. */
 interface DefinedNames {
-    /** Every name this reader read one as defining. */
+    /** Every name a dynamic definition settled on. */
     readonly names: ReadonlySet<string>;
-    /** What a name read only in part has to match for the class to be defining it. */
+    /** One pattern per name that settled only in part. A name matching one may be defined by the class. */
     readonly patterns: readonly RegExp[];
-    /** Whether one of them was given a name this reader could not read. */
+    /** Whether any definition's name settled on nothing at all. */
     readonly unreadable: boolean;
 }
-/** Every class's reading, by the key the value facts give the class node. */
+/** What each class defines dynamically, keyed by the class node's value fact key. */
 type DynamicNames = ReadonlyMap<string, DefinedNames>;
 
 /**
  * Resolves Ruby constant paths against lexical nesting.
  *
- * A compound path referenced, like `Data::Record`, is read as absolute. A
- * bare name is relative to the nesting it is written inside, and so is a
- * compound name `class` or `module` opens. `require` is never resolved,
- * because Rails autoloads by naming convention rather than through a load graph
- * a static reader could follow, so a constant that nesting alone cannot qualify
- * keeps whatever name the source wrote and callers treat it as unresolved.
+ * A compound reference such as `Data::Record` is read as absolute. A bare
+ * name is relative to the nesting it is written inside, and so is a
+ * compound name that `class` or `module` opens. `require` is never
+ * resolved, because Rails autoloads by naming convention. A constant that
+ * nesting alone cannot qualify keeps the name the source wrote.
  *
- * Ruby's own `Module.nesting` puts a newly opened class or module on the front
- * of the chain already in effect, whether the name used to open it was bare or
- * compound, because nesting follows the class and module keywords in the text
- * and not the form of the name. So even when a class is opened with a compound
- * name, as in `module Api; class Types::CampaignType; end; end`, Ruby still
- * looks up through `Api` inside that body. That matters, because a bare
- * reference in there is resolved by trying each level of the chain, and dropping
- * `Api` would miss a class the file itself defines.
+ * Ruby's `Module.nesting` puts each newly opened class or module on the
+ * front of the chain, whether its name was bare or compound. Inside
+ * `module Api; class Types::CampaignType`, a bare reference is still
+ * looked up through `Api`.
  */
 
 /**
- * Qualifies a name against the innermost level of `nesting` and no further. It
- * returns null for a computed expression or a variable, which callers treat as
- * unresolved. `shadowingClassFor` is the one place that walks every level.
+ * Qualifies a name against the innermost level of `nesting` only, which
+ * gives the name a `class` or `module` keyword defines. Returns null for
+ * a computed expression or a variable, which callers treat as
+ * unresolved. To find the class a reference refers to, use
+ * `constantRefCandidates`.
  */
 declare function qualifyConstantRef(node: Node, nesting: readonly string[]): string | null;
 interface ClassInfo {
@@ -182,11 +216,18 @@ interface ClassInfo {
 declare function walkClasses(root: Node, visit: (info: ClassInfo) => void): void;
 /** The same walk including `module` declarations, for a lookup that has to reach a module's own methods. */
 declare function walkDefinitions(root: Node, visit: (info: ClassInfo) => void): void;
-/** A pack picks a derivation by name, and the code for each one lives here. */
+/** A pack picks a convention by name, and `TYPE_NAME_CONVENTIONS` maps each name to its code. */
 type GraphqlTypeNameConvention = "stripTypeSuffix";
-/** We never read a per-class name override, so this is always the name the convention derives. */
+/** The GraphQL type name the convention derives from a class name. A name a class sets for itself is not read. */
 declare function graphqlTypeNameFromQualified(qualifiedName: string, convention: GraphqlTypeNameConvention): string;
 
+/**
+ * The ancestor chain a lookup walks to find the method behind a class,
+ * in the order Ruby's `Module#ancestors` gives. A reopened class is one
+ * place in the chain, an included module's own chain goes in as a unit,
+ * and an ancestor already in the chain is not added again.
+ */
+
 /** One class or module body a walk reached, with the definitions its own file makes, since a bare constant is shadowed per file. */
 interface ReachedBody {
     info: ClassInfo;
@@ -214,7 +255,7 @@ type AncestorEntry = {
 };
 /** A class and everything it inherits from, in Ruby's own method-lookup order. */
 type Ancestry = readonly AncestorEntry[];
-/** What reading a class body takes beyond the body: the run's facts, and what its packs declare about a block written in one. */
+/** What reading a class body needs besides the body: the run's facts, and what the packs declare about blocks written in one. */
 interface BodyReading {
     readonly facts?: Database | undefined;
     readonly bodyBlocks?: BodyBlocks | undefined;
@@ -225,6 +266,8 @@ interface BodyReading {
 interface AncestorLookup {
     /** Directory the constant-to-path convention resolves an ancestor's name against. */
     root: string;
+    /** Further directories tried after `root`, each as the top of the namespace. */
+    autoloadRoots?: readonly string[];
     pathConvention: ConstantPathConvention;
     /** Acronyms the convention keeps as one word, `ActivityPub` to `activitypub`. */
     acronyms?: readonly string[];
@@ -233,6 +276,8 @@ interface AncestorLookup {
      * ends a walk with nothing left unfollowed.
      */
     ancestryRootClassNames: readonly string[];
+    /** What this run's constant lookups have already read from the disk. */
+    constantFiles: ConstantFileCache;
     parsedFile(absPath: string): Promise<Node | null>;
     /**
      * The blocks the file being read defines under a name, consulted
@@ -242,32 +287,34 @@ interface AncestorLookup {
     localDefinition?(qualifiedName: string): ReachedBody[] | null;
 }
 /**
- * Every block a file defines under `qualifiedName`, or null when the
- * constant-to-path convention points at no file, no file is there, or
- * the file defines nothing by that name.
+ * Every block a file defines under `qualifiedName`, or null when no file
+ * the constant-to-path convention points at defines it. A class nested
+ * in its namespace's own file, `Order::NotPaid` written inside
+ * `order.rb`, is found there, since loading `Order` defines it.
  */
 declare function reachDefinition(qualifiedName: string, lookup: AncestorLookup): Promise<ReachedBody[] | null>;
 declare function ancestryOf(name: string, blocks: readonly ReachedBody[], lookup: AncestorLookup): Promise<Ancestry>;
 /** What searching an ancestry for one method name came to. */
 type MethodLookup = 
-/** `block` is which ancestor's own body the method is written in, so a caller that needs its file can get there. */
+/** `block` is the ancestor body the method is written in, which gives a caller its file. */
 {
     type: "found";
     method: Node;
     block: ReachedBody;
 }
 /**
- * `reason` completes "could be answered by a method ...".
- * `cause` says why the search stopped, since a caller deciding
- * whether to look further needs more than the sentence: `unreadAncestor`
- * is a base whose file this run could not open, and `dynamicDefine`
- * is a `define_method` call that defines this name, or one whose own
- * name this reader could not read.
+ * `reason` finishes the sentence "could be answered by a method ...".
+ * `cause` gives the reason as a value, for a caller deciding whether
+ * to look further. `unreadAncestor` is a base whose file the run could
+ * not open, and `dynamicDefine` is a `define_method` call that defines
+ * this name or whose own name did not settle.
  */
  | {
     type: "unsettled";
     reason: string;
     cause: "unreadAncestor" | "dynamicDefine";
+    /** True when an ancestor past the unread one defines it in the project. */
+    definedLater?: boolean;
 } | {
     type: "none";
 };
@@ -283,56 +330,240 @@ declare function inheritedStatements(ancestry: Ancestry, blockConfigures?: Block
 }>;
 
 /**
- * The Ruby adapter's own pattern-pack contract.
+ * The contract a Ruby pack implements.
  *
- * Match shapes stay per-language until a second implementation shows what is
- * actually shared, so this is Ruby's own and not the TypeScript or Python
- * adapter's. Everything a library defines, meaning its call names, keywords,
- * scalars, and conventions, arrives as pack data and is never hardcoded here.
+ * Each language adapter keeps its own pack contract until a second
+ * implementation shows which parts can be shared. Anything a library
+ * defines, such as its call names, keywords and scalars, comes in as pack
+ * data. This package hardcodes none of it.
  */
 
 interface RubyPack {
     name: string;
     /**
-     * Pack version stamp, which feeds the cache invalidation key. Bump on
-     * any change that affects discovered units or extracted summaries.
-     * The CLI folds a hash of the loaded pack file and its config into
-     * this stamp on top, so a pack run through the CLI invalidates on an
-     * edit whether or not it declares a version of its own.
+     * Part of the cache key. Bump it on any change that affects discovered
+     * units or extracted summaries. The CLI also adds a hash of the loaded
+     * pack file and its config to the key, so a pack run through the CLI
+     * re-extracts after an edit even when it declares no version.
      */
     version?: string;
     /**
-     * Files under the project this pack reads that are not among the
-     * `.rb` files a run walks, given the files the run is about to walk.
-     * Their content feeds the same cache key the pack's own config does,
-     * so an edit to one of them re-extracts instead of handing back the
-     * previous answer.
+     * Files outside the walked `.rb` set whose content this pack reads,
+     * given the files the run is about to walk. Their content goes into the
+     * cache key, so editing one of them forces a re-extract.
      */
     discoveryInputs?: (files: readonly string[]) => string[];
-    /** Wire protocol for the produced boundary bindings, e.g. "http-graphql". */
+    /** Wire protocol for the boundary bindings the pack produces, e.g. "http-graphql". */
     protocol: string;
     discovery: RubyDiscoveryPattern[];
-    /** The calls the library gives a project for making a request. */
+    /** The calls the library offers a project for making a request. */
     clients?: RbClientCall[];
-    /** What the library's own database calls look like. The README says how one is matched. */
+    /** The library's model calls that read or write the database. */
     storage?: RbStoragePattern[];
-    /** The calls the library gives a project for handing the store a statement it wrote itself. */
+    /** The calls the library offers for sending the store a statement the project wrote itself. */
     rawSql?: RbRawSqlPattern[];
-    /** Calls the library gives a project for reading a model through a batching loader, rather than on the model itself. */
+    /**
+     * The methods an action calls with no receiver to read the request,
+     * such as Rails' `params` and `request`. An action is handed no
+     * parameter for the request, so without these a value read off one is
+     * not known to come from the request.
+     */
+    requestAccessors?: string[];
+    /** Where an action reads each part of the request, recorded on every action the pack finds. */
+    requestSpelling?: RequestSpellingMetadata;
+    /** Calls that read a model through a batching loader, where the model is an argument instead of the receiver. */
     loaders?: RbLoaderPattern[];
-    /** Calls the library gives a class or module body whose block runs as part of that body. */
+    /** Calls in a class or module body whose block runs as part of that body. */
     bodyBlocks?: RbBodyBlock[];
-    /** What the project taught the library's inflector, which comes ahead of the adapter's own defaults. */
+    /** Words and rules the project added to the library's inflector. They are tried before the adapter's defaults. */
     inflections?: RbInflections;
+    /** Methods the library offers that hand back the argument at `argument`, keyed on the module the callee comes from. */
+    transparentWrappers?: UnwrapsByName[];
+    /** How the library builds test records from named factories. */
+    factories?: RbFactories[];
+    /** How a class-based test runner declares tests, as Minitest does. */
+    testClasses?: RbTestClasses[];
+    /** How the library writes a test, so each one becomes a `test` unit a PRD scenario can list under `coveredBy`. */
+    tests?: RbTestCases[];
+}
+/**
+ * Tests written as nested blocks, the way RSpec writes them:
+ * `describe Order do; it "cancels" do ... end; end`. Each example is a
+ * `test` unit whose name is its group titles and its own. Every call
+ * listed here is one the library defines; the adapter reads the nesting.
+ */
+interface RbTestCases {
+    /** Base names of the files the runner loads, where `*` matches any run of characters: `*_spec.rb`. */
+    filePatterns: string[];
+    /** The constant a top-level group may be opened on, `RSpec` in `RSpec.describe`. */
+    receiver: string;
+    /** Calls that open a group of examples: `describe`, `context`. */
+    groupNames: string[];
+    /** Calls that open a group whose examples do not run: `xdescribe`, `xcontext`. */
+    skippedGroupNames: string[];
+    /** Calls that open a group other groups include by name, whose examples belong to whoever includes them: `shared_examples`. */
+    sharedGroupNames: string[];
+    /** Calls that include a shared group by name into the group they are written in: `it_behaves_like`, `include_context`. */
+    sharedIncludes: RbSharedInclude[];
+    /** Calls that declare one example: `it`, `specify`. */
+    exampleNames: string[];
+    /** Calls that declare an example that does not run: `xit`, `skip`. */
+    skippedExampleNames: string[];
+    /** Calls that, written as a statement in an example or a `before` block, mark the example as not run: `skip`, `pending`. */
+    skipStatements: string[];
+    /** Metadata keys that mark a group or an example as not run, written `:skip` or `skip: true`. */
+    skipMetadata: string[];
+    /** Hooks whose block runs before every example in the group: `before`. */
+    beforeHooks: string[];
+    /** Calls that define a value an example reads by name, run when it is first read: `let`. */
+    lazyValues: string[];
+    /** The same, run before every example whether it reads the value or not: `let!`. */
+    eagerValues: string[];
+    /** Calls that define the group's subject, lazily and eagerly: `subject`, `subject!`. */
+    subjectNames: {
+        lazy: string[];
+        eager: string[];
+    };
+    /** Calls an example makes on itself to read the subject: `subject`, `is_expected`. */
+    subjectReads: string[];
+    /** The one of those that gives back the subject itself: `subject`. A group given a class has that class's `new` as its subject unless it says otherwise. */
+    subjectValue: string;
+    /** The call that gives back the class the nearest group around was given: `described_class`. */
+    describedClass: string;
+    /**
+     * Methods the library gives an example to call on itself to check or
+     * set something up, such as `expect`, `eq` and `allow`. A call made
+     * through one is no call into project code.
+     */
+    runnerMethods: string[];
+    /** The matchers the library makes up from a predicate method, as `be_cancelled` calls `cancelled?` on what the expectation is about. */
+    predicateMatchers: RbPredicateMatcher[];
+    /** How an example states an expectation, which a predicate matcher is given to. */
+    expectations: RbExpectations;
+    /** How the library replaces something for the length of an example. */
+    mocks: RbTestMocks;
+    /** Read only these files, matched on whole path segments from the end. Left out, every file matching `filePatterns` is read. */
+    files?: string[];
+}
+/**
+ * Tests written as a class, the way Minitest and Rails' test cases write
+ * them: a class that extends one of `baseClassNames`, with a method per
+ * test or a `test "..." do` block per test. Each becomes a `test` unit
+ * named by the class and then the test's method name.
+ */
+interface RbTestClasses {
+    /** Base names of the files the runner loads, where `*` matches any run of characters: `*_test.rb`. */
+    filePatterns: string[];
+    /** The library's test case classes, as a project writes them: `Minitest::Test`, `ActiveSupport::TestCase`. */
+    baseClassNames: string[];
+    /** What a test method's name starts with: `test_`. */
+    testMethodPrefix: string;
+    /** Calls that declare a test as a block, given its description: `test`. */
+    testBlockMethods: string[];
+    /** How the library turns a block test's description into the method it defines: `test_` in front, each run of spaces as `_`. */
+    blockTestName: {
+        prefix: string;
+        spacesAs: string;
+    };
+    /** Calls whose block runs before each test: `setup`. */
+    setupBlockMethods: string[];
+    /** Methods the runner calls before each test: `setup`. */
+    setupMethodNames: string[];
+    /** Calls that, written as a statement in a test, mark it as not run: `skip`. */
+    skipStatements: string[];
+    /** Prefixes of the checks the runner gives a test, which call no project code: `assert`, `refute`. */
+    assertionPrefixes: string[];
+    /** Calls that replace a method on the object they are called on, given its name first: `stub`, `stubs`, `expects`. */
+    stubMethods: string[];
+    /** Read only these files, matched on whole path segments from the end. */
+    files?: string[];
+}
+/**
+ * How a test data library builds a record from a factory it looks up by
+ * name, so a value a test builds with `create(:order)` or
+ * `Fabricate(:order)` is known to be one of the factory's class. The
+ * adapter reads the definitions wherever the run finds them, and the
+ * builds in the files it reads as tests.
+ */
+interface RbFactories {
+    /** Calls that define a factory, given its name first: `factory`, `Fabricator`. */
+    definitionMethods: string[];
+    /** Keywords a definition gives its class under, as a constant or a string: `class`, `class_name`. */
+    classKeywords: string[];
+    /** Keywords a definition gives the factory it builds on under: `parent`, `from`. A name no factory has is read as a class. */
+    parentKeywords: string[];
+    /** Whether a definition written in another's block builds on it, as a nested FactoryBot factory does. */
+    nestedDefinitionsInherit: boolean;
+    /** Calls that build one record from the factory their first argument names. */
+    builders: RbFactoryBuilder[];
+}
+/** One build call: `create`, or `Fabricate.build` with `receiver` set. */
+interface RbFactoryBuilder {
+    method: string;
+    /** The constant the call is made on, when it is made on one. */
+    receiver?: string;
+}
+/**
+ * A matcher the library makes up from a predicate method: a matcher
+ * written `prefix` and a name calls `methodPrefix`, that name and
+ * `methodSuffix` on the value the expectation is about, so `be_local`
+ * calls `local?` and `have_key` calls `has_key?`.
+ */
+interface RbPredicateMatcher {
+    prefix: string;
+    methodPrefix: string;
+    methodSuffix: string;
 }
 /**
- * The words and rules a project registered with its library's
- * inflector. The library says where a project writes them and how; what
- * arrives here is the reading, so the adapter applies them without
- * knowing any of that.
+ * How an example states an expectation: `expect(order).to be_open`, on
+ * the argument of a `starts` call, or `is_expected.to be_open`, on the
+ * subject through `onSubject`. `runs` are the calls given the matcher.
+ */
+interface RbExpectations {
+    starts: string[];
+    onSubject: string;
+    runs: string[];
+}
+/**
+ * One way a group includes a shared group. With `nestedTitle`, the shared
+ * examples run in a group of their own titled that and then the shared
+ * group's name, as `it_behaves_like "x"` runs them under "behaves like x".
+ * Without it they run in the including group itself.
+ */
+interface RbSharedInclude {
+    method: string;
+    nestedTitle?: string;
+}
+/**
+ * The library's mock spellings. `allow(Order).to receive(:cancel)`
+ * replaces one method: `targets` opens it, `expectations` joins it, and
+ * `messages` says which method. `stub_const("Order", ...)` replaces a
+ * whole constant. A double is a fake object the test hands over, and it
+ * replaces nothing the test would otherwise reach unless the test makes
+ * it the constant with `constantDoubleMethod`.
+ */
+interface RbTestMocks {
+    /** `allow`, `expect`, `allow_any_instance_of`. */
+    targets: string[];
+    /** `to`. */
+    expectations: string[];
+    /** `receive`, `receive_messages`. */
+    messages: string[];
+    /** `stub_const`. */
+    constantStubs: string[];
+    /** `instance_double`, `class_double`. */
+    doubles: string[];
+    /** `as_stubbed_const`, which makes a double the constant it stands in for. */
+    constantDoubleMethod: string;
+}
+/**
+ * The words and rules a project registered with its library's inflector.
+ * Where a project writes them depends on the library, so the pack reads
+ * them and passes the result here. The adapter applies them the same way
+ * for every library.
  */
 interface RbInflections {
-    /** Words a constant name keeps whole: `API` gives `APIToken` rather than `ApiToken`. */
+    /** Words a constant name keeps in capitals: with `API`, `api_token` becomes `APIToken`. */
     acronyms?: string[];
     /** A plural and the singular it comes from: `["people", "person"]`. */
     irregular?: Array<[plural: string, singular: string]>;
@@ -342,26 +573,26 @@ interface RbInflections {
     singular?: Array<[rule: string, replacement: string]>;
 }
 /**
- * A receiverless call a library gives a class or module body, whose
- * block runs as part of that body rather than keeping what it declares
- * to itself. Ruby has no such call of its own, so a run whose packs
- * declare nothing here never opens a block out into the body.
+ * A receiverless call in a class or module body whose block runs as part
+ * of that body, so what the block declares belongs to the class. Ruby has
+ * no such call of its own. When no pack declares one, every block is read
+ * as an ordinary block.
  */
 interface RbBodyBlock {
     /** The call as a project writes it, `included`. */
     name: string;
-    /** Set when the library only gives the call to a module, as a concern's own `included` is. */
+    /** Set when the library offers the call only to modules, as with a concern's `included`. */
     moduleOnly?: boolean;
-    /** Set when a `def` in the block declares a method on the class itself rather than on an instance. */
+    /** Set when a `def` in the block defines a method on the class itself instead of on an instance. */
     definesClassMethods?: boolean;
 }
 /**
- * The calls a library gives a project for making a request. A method
- * that makes one is a client of the boundary that call states, and gets
- * a unit bound to its method and path.
+ * The calls a library offers a project for making a request. A method
+ * that makes one becomes a client unit, bound to the request method and
+ * path of the call.
  */
 interface RbClientCall {
-    /** The constant the calls hang on, as a project writes it: `Faraday`, `Net::HTTP`. */
+    /** The constant the calls are made on, as a project writes it: `Faraday`, `Net::HTTP`. */
     constantName: string;
     /** Method names that state the request method themselves: `get` means GET. */
     verbMethodNames: Record<string, string>;
@@ -372,11 +603,11 @@ interface RbClientCall {
     };
     /** Methods on the constant that build a value taking the same calls, `new` for a Faraday connection. */
     receiverBuilders?: string[];
-    /** The keyword such a builder takes the base URL under, which comes in front of the path of a call on it. */
+    /** The keyword a builder takes its base URL under. The base URL goes in front of the path of each call on the built value. */
     builderUrlKeyword?: string;
-    /** What the response object gives a caller, so a test on one of its members counts as a test on a status. */
+    /** The members of the response object, so a test on one of them counts as a test on the status. */
     response?: RbClientResponse;
-    /** A call that sends a request object built somewhere else, which is how Net::HTTP sends anything with a body. */
+    /** A call that sends a request object built separately. Net::HTTP sends any request with a body this way. */
     requestObject?: {
         /** The method that takes the request object, `request`. */
         attribute: string;
@@ -387,9 +618,9 @@ interface RbClientCall {
     };
 }
 /**
- * The members a library's response object gives a caller. A caller that
- * tests one of them is saying which statuses it handles, and the
- * checker compares that against what the other side produces.
+ * The members of a library's response object. A test on one of them shows
+ * which statuses the caller handles, and the checker compares that with
+ * what the provider sends.
  */
 interface RbClientResponse {
     /** Members whose value is the status: `status` for Faraday, `code` for Net::HTTP. */
@@ -400,18 +631,21 @@ interface RbClientResponse {
     body?: string[];
     /** Whether a refused request comes back as a response or raises where it was made. */
     failureDelivery?: "response" | "exception";
+    /** Whether the client follows a redirect itself or hands the 3xx back. */
+    redirectDelivery?: "followed" | "response";
 }
 /**
- * Ruby writes no return type, so a call is matched by what its receiver
- * inherits from. A model is a class that reaches one of these base classes,
- * whether the project declares an intermediate one or not.
+ * Ruby code declares no return types, so a call is matched by what its
+ * receiver inherits from. A model is any class whose ancestry reaches one
+ * of `baseClasses`, including through a base class the project declares
+ * in between.
  *
- * `reads` and `writes` are the whole of what the library does to the
- * database. A method in neither list is the project's own or the
- * language's, and the reach walk follows it instead.
+ * `reads` and `writes` list every database call the library makes. A
+ * method in neither list belongs to the project or the language, and the
+ * reach walk follows it.
  */
 interface RbStoragePattern {
-    /** Base classes the library gives a model, `ActiveRecord::Base` for Rails. */
+    /** Base classes the library provides for models, `ActiveRecord::Base` for Rails. */
     baseClasses: string[];
     /** Methods the library defines that change what is stored. */
     writes: string[];
@@ -421,146 +655,157 @@ interface RbStoragePattern {
     givesBack: string[];
     /**
      * Methods on the model that take a statement the project wrote itself,
-     * and where each one takes it. The tables come from the statement, so
-     * one of these says nothing about the model's own container, and the
-     * statement is read in the dialect of `storageSystem`.
+     * and where each one takes it. The tables come from the statement
+     * instead of the model's own container, and the statement is read in
+     * the dialect of `storageSystem`.
      */
     statements?: Record<string, RbArgumentPlace>;
     /** The token the library writes where a bind value goes, ActiveRecord's `?`. */
     bindPlaceholder?: string;
-    /** The methods the library runs of its own accord when a write happens, `after_commit :sync_search`. */
+    /** The methods the library runs by itself around a write, as registered by `after_commit :sync_search`. */
     callbacks?: RbModelCallbacks;
-    /** Methods that pick rows by the primary key when they are given a positional argument, and the column that is. */
+    /** Methods that pick rows by the primary key when given a positional argument, and that key's column. */
     byPrimaryKey?: RbPrimaryKeyLookup;
     /** Read methods whose symbol arguments are the columns they ask for. */
     columnArguments?: string[];
-    /** How the library declares that one model reaches another, when it has such a thing. */
+    /** The calls a model uses to declare an association with another model, when the library has them. */
     associations?: RbAssociationCalls;
-    /** Which database is behind the connection, which the project settles. */
+    /**
+     * The calls a model body makes to define a class method from a lambda,
+     * as `scope :recent, -> { order(:created_at) }` defines `recent`. The
+     * first argument is the method's name and the lambda after it runs.
+     */
+    scopes?: string[];
+    /** Which database is behind the connection. The project decides this, so the pack passes it in. */
     storageSystem: "postgresql" | "mysql" | "sqlite";
+    /** The exception each of these methods raises when the row is missing or does not save, ActiveRecord's `RecordNotFound` from `find`. */
+    raises?: Array<{
+        exception: string;
+        methods: string[];
+    }>;
 }
 /**
- * A library whose calls take SQL the project wrote, rather than
- * building it from a model. Ruby writes no types, so the receiver is
- * typed by following it back to the library call that produced it: the
- * chain starts at `constantName`, one of `clientBuilders` gives back a
- * client, and `addressing` calls narrow that client to a part of the
- * store before the statement or the row call arrives.
+ * A library whose calls take SQL the project wrote, instead of building
+ * it from a model. Ruby code declares no types, so the adapter finds the
+ * receiver's type by following it back to the library call that produced
+ * it. The chain starts at `constantName`, one of `clientBuilders` returns
+ * a client, and `addressing` calls narrow that client to part of the store
+ * before the statement or row call.
  */
 interface RbRawSqlPattern {
     /** The constant the library's calls start at, `PG` or `Google::Cloud::Bigquery`. */
     constantName: string;
     /**
-     * Base classes whose subclasses hand a client out the same way the
-     * constant does, `ActiveRecord::Base` for Rails. A project writes
-     * `Account.connection` and a bare `connection` inside the model as
-     * readily as the base class itself, and all three reach one store.
+     * Base classes whose subclasses return a client the same way the
+     * constant does, `ActiveRecord::Base` for Rails. `Account.connection`
+     * and a bare `connection` inside the model reach the same store as the
+     * base class itself.
      */
     baseClasses?: string[];
-    /** Methods on that constant that give back a client, `connect` for the pg gem. */
+    /** Methods on that constant that return a client, `connect` for the pg gem. */
     clientBuilders: string[];
-    /** Calls that narrow a client to part of the store and give back something the rest of the calls can be made on. */
+    /** Calls that narrow a client to part of the store and return a value the later calls are made on. */
     addressing?: Record<string, RbAddressingCall>;
     /** Calls that take a statement, and where each one takes it. */
     statements?: Record<string, RbArgumentPlace>;
-    /** The token the library writes where a bind value goes, when it is not the one the dialect itself reads. */
+    /** The token the library writes where a bind value goes, when the dialect's parser does not read it. */
     bindPlaceholder?: string;
     /** Calls that read or write rows of an addressed container with no statement, `insert` on a BigQuery table. */
     rowCalls?: Record<string, RbRowCall>;
-    /** Which store is behind the calls, in the words OpenTelemetry's semantic conventions use: `postgresql`, `gcp.bigquery`. */
+    /** Which store is behind the calls, in OpenTelemetry's semantic convention names: `postgresql`, `gcp.bigquery`. */
     storageSystem: string;
     /**
-     * Which dialect the statements are written in, which is a separate
-     * answer from the store: BigQuery's store is `gcp.bigquery` and its
-     * statements are `bigquery`, and a default here would read the wrong
-     * tables without saying so.
+     * Which dialect the statements are written in. This can differ from the
+     * store: BigQuery's store is `gcp.bigquery` and its dialect is
+     * `bigquery`. There is no default, because a wrong dialect would read
+     * the wrong tables without any warning.
      */
     dialect: string;
-    /** Which namespace the calls reach when neither the chain nor the table name says. Defaults to "default". */
+    /** The namespace the calls reach when neither the chain nor the table name gives one. Defaults to "default". */
     scope?: string;
 }
-/** A call that says which part of the store the calls after it reach, `bigquery.dataset("core")`. */
+/** A call that selects which part of the store the later calls reach, `bigquery.dataset("core")`. */
 interface RbAddressingCall extends RbArgumentPlace {
-    /** Which part of the address this call states. */
+    /** Which part of the address this call gives. */
     says: "scope" | "container";
 }
 /** A call that reads or writes rows without a statement. */
 interface RbRowCall {
     kind: "read" | "write";
     /**
-     * Where the call may say which container, for a library that gives
-     * the same call on the container and one level above it: BigQuery's
-     * `table.insert(rows)` and `dataset.insert("accounts", rows)`. The
-     * chain's own container is used when this argument settles on no
-     * string, which is what a row argument does.
+     * Where the call can take the container, for a library that offers the
+     * same call on the container and one level above it: BigQuery's
+     * `table.insert(rows)` and `dataset.insert("accounts", rows)`. When this
+     * argument does not settle on a string, as with a rows argument, the
+     * chain's own container is used.
      */
     container?: RbArgumentPlace;
 }
-/** Where a call writes one of its arguments. A call that takes it both ways is matched on the keyword first. */
+/** Where a call takes one of its arguments. When a call passes it both ways, the keyword wins. */
 interface RbArgumentPlace {
     /** The index of the positional argument. */
     at: number;
-    /** The keyword the argument may travel under instead. */
+    /** The keyword the argument can be passed under instead. */
     keyword?: string;
 }
-/** Which methods take the primary key positionally, and what that column is called. */
 /**
- * The methods a model registers in its own class body for the library
- * to run when a write happens. A body that writes through the model
- * runs them too, so their effects belong to that body.
+ * The methods a model registers in its class body for the library to
+ * run when a write happens. A body that writes through the model runs
+ * them too, so their effects belong to that body.
  *
- * `events` is the library's own vocabulary for what a write is, and
- * both halves of this are keyed by it: a write method says which events
- * it runs, and a registering call says which events it covers.
+ * Both tables are keyed by the library's own event names: a write method
+ * lists the events it fires, and a registering call lists the events it
+ * covers.
  */
 interface RbModelCallbacks {
-    /** Each write method the pattern declares, and the events it runs. */
+    /** Each write method the pattern declares, and the events it fires. */
     eventOf: Record<string, string[]>;
-    /** Each class-body call that registers a callback, and the events it covers when the call narrows to none. */
+    /** Each class-body call that registers a callback, and the events it covers when the call does not narrow them. */
     registeredBy: Record<string, string[]>;
     /** The keyword that narrows one registration to some of those events, `on`. */
     eventKeyword: string;
 }
+/** Which methods take the primary key positionally, and what that column is called. */
 interface RbPrimaryKeyLookup {
     methods: string[];
-    /** The column the library uses unless a model says another. */
+    /** The column the library uses unless a model sets another. */
     column: string;
 }
 /**
- * The class-body calls a library gives a model for declaring an
- * association, and where one says which class it reaches. The two lists
- * are apart because the target's name is the association's singularised
- * for a plural call and the association's as written for a singular one,
- * and only the library knows which of its calls is which.
+ * The class-body calls a model uses to declare an association, and the
+ * keyword that gives the target class. The calls are split into two
+ * lists because a plural call's target is the singularised association
+ * name, and a singular call's target is the name as written. Only the
+ * library knows which of its calls is which.
  */
 interface RbAssociationCalls {
     /** Calls written in the singular, `belongs_to :account` and `has_one :profile`. */
     singular: string[];
     /** Calls written in the plural, `has_many :statuses`. */
     plural: string[];
-    /** The keyword whose value is the target class's name instead, `class_name`. */
+    /** The keyword that gives the target class's name explicitly, `class_name`. */
     classNameKeyword: string;
 }
 /**
- * A loader that batches reads of a model on the caller's behalf, graphql-ruby's
- * dataloader for one. The call that picks what to load is given the model as
- * a constant argument, so the read is recorded against that model the same
- * way a call on the model itself would be, and a storage pattern from another
- * pack in the run says whether the constant is a model at all.
+ * A loader that batches reads of a model for the caller, such as
+ * graphql-ruby's dataloader. The call that picks what to load gets the
+ * model as a constant argument, so the read is recorded against that
+ * model as if the call were made on it. A storage pattern from another
+ * pack in the run decides whether the constant is a model at all.
  */
 interface RbLoaderPattern {
-    /** The receiverless call that gives the loader, `dataloader`. */
+    /** The receiverless call that returns the loader, `dataloader`. */
     loader: string;
     /** The method on the loader that picks a source and its arguments, `with`. */
     pick: string;
     /** The methods on a picked source that perform the read, `load` and `load_all`. */
     reads: string[];
-    /** Receiverless calls that pick and read in one, whose arguments include the model, `dataload` and `dataload_record`. */
+    /** Receiverless calls that pick and read in one call, with the model among the arguments: `dataload` and `dataload_record`. */
     shortcuts: string[];
     /**
      * Where `pick` takes the project's own source class, and the method
-     * the library runs on it. The read happens in that method, so what it
-     * reaches belongs to every body that loads through it.
+     * the library runs on it. The read happens in that method, so whatever
+     * it reaches is reported on every body that loads through it.
      */
     source?: RbLoaderSource;
 }
@@ -572,73 +817,102 @@ interface RbLoaderSource {
     method: string;
 }
 type RubyDiscoveryPattern = GraphqlObjectFields | ControllerActions;
-/** A class whose ancestry reaches one of `baseClassNames` or `ancestryRootClassNames` is a controller, and every instance method it defines directly is one of its actions, bound by `routeFor` to the method and path a project's own routing gives it, or discovered with no boundary binding when `routeFor` finds none. */
+/** One route to a controller action. */
+interface ControllerRoute {
+    method: string;
+    path: string;
+    /** True for a route served with no `.{format}` in a framework that adds one; see `ControllerActions.optionalFormat`. */
+    formatless?: true;
+}
+/**
+ * A class whose ancestry reaches one of `baseClassNames` or
+ * `ancestryRootClassNames` is a controller, and every instance method it
+ * defines directly is an action. `routesFor` binds each action to the
+ * methods and paths the project's routing gives it, one unit per route.
+ * An action with no route is still discovered, with no boundary binding.
+ */
 interface ControllerActions {
     type: "controllerActions";
-    /** A base a project's controllers extend, `ApplicationController` say. The base itself is not a controller. */
+    /** Bases a project's controllers extend, such as `ApplicationController`. A base is not itself a controller. */
     baseClassNames: string[];
-    /** The directory a bare superclass name is looked up under, the project's own layout. */
+    /** The directory a bare superclass name is looked up under, which depends on the project's layout. */
     root: string;
+    /** Other directories the project autoloads constants from, each read as the top of the namespace, after `root`. */
+    autoloadRoots?: string[];
+    /**
+     * The library's own exception classes, with the classes each one
+     * inherits from, so a handler for a base class counts. `status` is
+     * what the library sends when an action raises one and no handler
+     * rescues it, Rails' `rescue_responses`.
+     */
+    libraryExceptions?: Record<string, LibraryException>;
     pathConvention: ConstantPathConvention;
-    /** Acronyms the project registers with the inflector, which the path convention keeps as one word: `ActivityPub` is `activitypub`, not `activity_pub`. */
+    /** Acronyms the project registers with the inflector. The path convention keeps each one as one word: `ActivityPub` becomes `activitypub`. */
     acronyms?: string[];
     /** The library's own classes a project's controller chain ends at. A class extending one directly is a controller too. */
     ancestryRootClassNames: string[];
-    /** Status code a wire response gets when the action does not say otherwise. */
+    /** The status a response gets when the action does not set one. */
     defaultStatusCode: number;
-    /** The receiverless calls the library gives an action for writing a wire status. Leave it out and every action reports the default. */
+    /** The receiverless calls an action uses to send a status. Without them, every action reports the default. */
     responseStatusCalls?: RbStatusCall[];
-    /** The number behind each name the library accepts where a status number could go, Rack's own symbol table for Rails. */
+    /** The number for each status name the library accepts in place of a number. For Rails this is Rack's symbol table. */
     statusCodeNames?: Record<string, number>;
+    /** The call whose block responds differently for each format the request asks for, Rails' `respond_to`. */
+    formatSwitch?: RbFormatSwitch;
     /**
-     * The methods every controller gets without defining them, which for
-     * Rails is `params`, `render` and the rest of what `ActionController`
-     * mixes in. An action's effect list is there to show what the action
-     * reaches in the project, and nothing in the project defines these,
-     * so a receiverless call to one of them is left off that list.
+     * Methods every controller inherits from the library, which for Rails
+     * are `params`, `render` and the rest of what `ActionController` mixes
+     * in. Nothing in the project defines them, so a receiverless call to
+     * one is left off the action's effect list.
      */
     inheritedMethodNames?: string[];
-    /** Absolute path of the file this pattern's own routing came from, for the one gap `routingGaps` may report. */
+    /** Absolute path of the routes file this pattern read, used in the gap `routingGaps` can report. */
     routesFile: string;
-    /** The method and path a project's own routing gives one controller's action, or null when that action has none. */
-    routeFor: (controllerQualifiedName: string, actionName: string) => {
-        method: string;
-        path: string;
-    } | null;
-    /** One message per routing declaration kind this pattern's reading left uncovered. A pure read: calling it again gives the same list. */
+    /**
+     * Every method and path the project's routing gives one controller
+     * action, in the order they are declared, or none.
+     */
+    routesFor: (controllerQualifiedName: string, actionName: string) => readonly ControllerRoute[];
+    /**
+     * Whether the framework also serves a route with `.{format}` after its
+     * path, as Rails serves `/search.json` from `get "search"`. A route
+     * marked `formatless`, and one whose path ends in a slash, get none.
+     */
+    optionalFormat?: boolean;
+    /** One message for each kind of routing declaration the pattern could not read. Calling it again returns the same list. */
     routingGaps?: () => readonly string[];
-    /** The class-level calls the library gives a controller for running one of its own methods around every action, Rails' `before_action` and `rescue_from`. */
+    /** The class-level calls that run one of the controller's own methods around its actions, Rails' `before_action` and `rescue_from`. */
     filters?: RbControllerFilter[];
 }
 /**
- * A call in a controller's class body naming a method the library runs
- * around the action, and which actions that reaches. A class inherits
- * what its ancestors declared, so a filter on `ApplicationController`
- * reaches every action in the project.
+ * A class-body call that registers a method for the library to run around
+ * a controller's actions. A class inherits what its ancestors register, so
+ * a filter on `ApplicationController` applies to every action in the
+ * project.
  */
 interface RbControllerFilter {
     /** The call as a controller writes it, `before_action`. */
     name: string;
     /**
-     * Where the call names the method: `argument` for the leading symbol
+     * Where the call takes the method: `argument` for the leading symbol
      * of `before_action :require_login`, `withKeyword` for the `with:` of
      * `rescue_from ActiveRecord::RecordNotFound, with: :not_found`.
      */
     methodFrom: "argument" | "withKeyword";
     /** Set when the library runs the method only for an action that raised, as `rescue_from` does. */
     onThrow?: boolean;
-    /** The name of the call that takes a filter back off, `skip_before_action` for `before_action`. */
+    /** The call that removes the filter again, `skip_before_action` for `before_action`. */
     skippedBy?: string;
-    /** The keywords that narrow a filter to some of the actions, Rails' `only` and `except`. */
+    /** The keywords that limit a filter to some of the actions, Rails' `only` and `except`. */
     actionKeywords?: {
         include: string;
         exclude: string;
     };
 }
 /**
- * One call an action writes to send a response, and where that call takes
- * the status. A call may take it both ways, and then the keyword wins,
- * as it does in Rails for `head :ok, status: :created`.
+ * A call an action makes to send a response, and where that call takes
+ * the status. When a call passes the status both ways the keyword wins,
+ * as in Rails for `head :ok, status: :created`.
  */
 interface RbStatusCall {
     /** The call's own name as an action writes it, `render` for Rails. */
@@ -648,54 +922,83 @@ interface RbStatusCall {
     /** The index of the positional argument giving the status, 0 for Rails' `head :no_content`. */
     statusArgument?: number;
     /**
-     * The status this call sends when the action writes none. Rails'
-     * `redirect_to` sends 302 where its `render` sends the controller's own
-     * default, so a default declared here wins over `defaultStatusCode`.
+     * The status this call sends when the action passes none. Rails'
+     * `redirect_to` sends 302, while `render` sends the controller default,
+     * so a default declared here takes precedence over `defaultStatusCode`.
      */
     defaultStatusCode?: number;
+    /** The keyword whose value the library sends as a JSON body, `json` for Rails' `render json:`. */
+    bodyKeyword?: string;
+    /**
+     * Methods that turn the value they are called on into that same JSON,
+     * so `render json: { ok: true }.to_json` sends the hash. Only a call
+     * with no arguments counts, since `as_json(only: ...)` drops keys.
+     */
+    bodySerializers?: string[];
+}
+/** One of a library's exception classes. */
+interface LibraryException {
+    /** Every class it inherits from, nearest first, up to `Exception`. */
+    ancestors: string[];
+    /** The status the library responds with when nothing rescues it. */
+    status?: number;
+}
+/**
+ * A receiverless call whose block responds one way per format the request
+ * asks for. Each call on the block's parameter, `format.json { ... }`, is
+ * one branch, and the request runs the first one whose format it accepts.
+ * When none does, the library raises.
+ */
+interface RbFormatSwitch {
+    /** The call's own name, `respond_to` for Rails. */
+    name: string;
+    /** The format that accepts every request, `any` for Rails. */
+    matchesEvery?: string;
 }
 /** A class or module whose ancestry reaches one of `baseClassNames` declares GraphQL fields through DSL calls in its own body. */
 interface GraphqlObjectFields {
     type: "graphqlObjectFields";
-    /** The base classes the library itself generates. The walk crosses a project's own intermediate bases on its own, so config only has to add a base with another name. */
+    /** The base classes the library's generator writes. The walk follows a project's own intermediate bases, so config only needs to add a base with a different name. */
     baseClassNames: string[];
-    /** The directory a wiring keyword's referenced class is looked up under. That is the project's own layout, not the library's. */
+    /** The directory a wiring keyword's referenced class is looked up under, which depends on the project's layout. */
     root: string;
+    /** Other directories the project autoloads constants from, each read as the top of the namespace, after `root`. */
+    autoloadRoots?: string[];
     pathConvention: ConstantPathConvention;
-    /** Acronyms the project registers with the inflector, which the path convention keeps as one word. */
+    /** Acronyms the project registers with the inflector. The path convention keeps each one as one word. */
     acronyms?: string[];
     /** The DSL call declaring one schema field in an object type's body. */
     fieldCallName: string;
     /** The DSL call declaring a referenced class's own return type. */
     typeCallName: string;
     argumentCallName: string;
-    /** Keywords whose value gives a class to read the declared contract from, one hop away. They are tried in the order listed. */
+    /** Keywords whose value is a class to read the declared contract from, one hop away. They are tried in the order listed. */
     wiringKeywords: string[];
-    /** The method a wired class defines to resolve the field it is wired to. Library-defined. */
+    /** The method a wired class defines to resolve the field it is wired to. */
     resolverMethodName: string;
-    /** The library's own classes that a project's class chain ends at. Library-defined. */
+    /** The library's own classes that a project's class chain ends at. */
     ancestryRootClassNames: string[];
-    /** Keyword on an argument call saying whether the argument is required. Library-defined. */
+    /** The keyword on an argument call that says whether the argument is required. */
     requiredKeyword: string;
-    /** What an argument means when it does not write the required keyword at all. */
+    /** Whether an argument is required when its call does not pass the required keyword. */
     requiredDefault: boolean;
     /** The keyword that overrides `camelizeDefault` for a single name. */
     camelizeKeyword: string;
-    /** Whether a symbol's snake_case name is exposed camelCased when the call itself does not say. */
+    /** Whether a snake_case symbol is exposed in camelCase when the call does not say. */
     camelizeDefault: boolean;
-    /** Only the names the library itself accepts in a type position belong here. */
+    /** The scalar names the library accepts in a type position, and the shape of each. List only the library's own. */
     scalars: Record<string, TypeShape>;
-    /** Module prefixes the same scalars can also be written under when someone spells out the full path. */
+    /** Module prefixes a project can write in front of those scalar names when it spells out the full path. */
     scalarNamePrefixes: string[];
     typeNameConvention: GraphqlTypeNameConvention;
     /**
      * A base class that changes a mutation's wire contract. When a wired
-     * class's ancestry reaches `ancestorClassName`, the library wraps
-     * every declared argument into one input-object argument called
+     * class's ancestry reaches `ancestorClassName`, the library wraps every
+     * declared argument into one input-object argument called
      * `argumentName` and adds `extraFields` to it. graphql-ruby's
-     * RelayClassicMutation is the class this describes: on the wire the
-     * mutation takes a single required `input`, whose fields are the
-     * declared arguments plus an optional `clientMutationId`.
+     * RelayClassicMutation does this: on the wire the mutation takes a
+     * single required `input`, whose fields are the declared arguments plus
+     * an optional `clientMutationId`.
      */
     argumentWrapping?: {
         ancestorClassName: string;
@@ -708,79 +1011,166 @@ interface GraphqlObjectFields {
 }
 
 /**
- * storage.ts: which calls in a body talk to the database, for Ruby.
+ * Finds the calls in a Ruby body that read or write the database.
  *
- * One rule covers both ways a call is written. It is database work when the
- * pack lists its method as a read or a write, the class behind its receiver
- * reaches a base class the pack lists, and the project does not declare that
- * method itself. A chain counts once, at the outermost call the library
- * defines, and every other call is left to the reach walk. The README says
- * why ancestry.
+ * A call is database work when the pack lists its method as a read or a
+ * write, the class behind its receiver reaches a base class the pack
+ * lists, and the project does not declare that method itself. A chain
+ * counts once, at the outermost call the library defines. Every other
+ * call is left to the reach walk.
  *
- * The class behind the receiver comes from the constant bindings, or from the
- * resolution rules. A loader pattern adds calls given the model, and a raw
- * SQL pattern adds calls handed a statement, both reported through here.
+ * The receiver's class comes from the constant bindings when the chain
+ * starts at a constant, and from the resolution rules otherwise. Loader
+ * calls and raw SQL calls are reported through here as well.
  */
 
 interface RbStorageOptions {
     readonly facts: Database;
     readonly patterns: readonly RbStoragePattern[];
     readonly loaders?: readonly RbLoaderPattern[];
-    /** What a pack says about calls that take SQL the project wrote itself. */
+    /** The pack declarations for calls that take SQL the project wrote itself. */
     readonly rawSql?: readonly RbRawSqlPattern[];
+    /** Told the value each effect's columns are given, when somebody listens. */
+    readonly statesSlots?: (effect: Effect, slots: readonly SlotValue[]) => void;
+}
+/** A column a storage effect writes or picks rows by, and the value passed for it. */
+interface SlotValue {
+    slot: "field" | "selector";
+    name: string;
+    value: Node;
 }
 /**
  * Whether the recognizer records this call as database work, so a walk
- * need not report it as a gap. `enclosing` is the method the call is
- * written in, which is what tells one body's locals from the next.
+ * does not need to report it as a gap. `enclosing` is the method the call
+ * is written in, which keeps one method's locals apart from another's.
  */
 declare function storageClaims(call: Node, file: string, options: RbStorageOptions, enclosing?: Node | null): boolean;
 /**
- * The database work a body does, one effect per chain. A chain is one thing
- * the code does, so `Order.where(id: 1).first` counts once. `file` is the
- * absolute path the calls were read from, which the constant bindings key on.
- * `enclosing` is the method the calls were read from, or null outside one.
+ * The database work a body does, one effect per chain, so
+ * `Order.where(id: 1).first` counts once. `file` is the absolute path the
+ * calls were read from, which the constant bindings are keyed on.
+ * `enclosing` is the method the calls are in, or null outside one.
  */
 declare function storageEffects(calls: readonly Node[], file: string, options: RbStorageOptions, enclosing?: Node | null): Effect[];
 
-/** The methods a pack declared the library defines itself, so a receiverless call to one of them is not work the project does. */
+/**
+ * The calls a body makes, as invocation effects. A call written under an
+ * `if` records that test as a precondition, and the IR treats a call
+ * with preconditions as one that does not always run.
+ */
+
+/** Methods the pack says the library defines, so a receiverless call to one of them is not project work. */
 type InheritedMethods = ReadonlySet<string>;
 
-/** Parsed files by absolute path, so a class that several fields refer to is only parsed once. */
+/**
+ * The shared groups a run's test files define, and where each one is
+ * included. RSpec's `shared_examples "x"` is written once, often in a
+ * support file, and `it_behaves_like "x"` in a spec runs its examples
+ * there. An include finds its shared group by name, in its own file
+ * first and then anywhere in the run.
+ *
+ * A name read inside a shared group that the group does not define
+ * comes from whoever includes it. The value facts key such a name on
+ * the shared group, and `emitSharedGroupBinds` binds it to what each
+ * include site has under that name. Two includers that give it two
+ * values leave it unsettled, since which one ran is not known.
+ */
+
+interface SharedDefinition {
+    readonly file: string;
+    readonly call: Node;
+    readonly name: string;
+}
+interface IncludeSite {
+    readonly file: string;
+    readonly call: Node;
+    /** The groups around the include, outermost first. */
+    readonly groups: readonly Node[];
+    /** Whether the shared examples run in a group of their own, as `it_behaves_like` runs them. */
+    readonly nested: boolean;
+    readonly definition: SharedDefinition;
+}
+/** A test file and the pattern that reads it. */
+interface PatternedFile {
+    readonly file: string;
+    readonly root: Node;
+    readonly pattern: RbTestCases;
+}
+declare class SharedGroupIndex {
+    private readonly db;
+    private readonly definitions;
+    private readonly definitionsByNode;
+    private readonly sitesByNode;
+    private readonly sitesByDefinition;
+    private readonly filesByTree;
+    constructor(db: Database, files: readonly PatternedFile[]);
+    /** The include this call makes, or null when it makes none or names no shared group the run defines. */
+    includedAt(call: Node): IncludeSite | null;
+    /** The shared group this call defines, or null. */
+    definitionAt(call: Node): SharedDefinition | null;
+    includersOf(definition: SharedDefinition): readonly IncludeSite[];
+    /** The file a node from a test or support file is written in. */
+    fileOf(node: Node): string | null;
+    private recordIncludes;
+    private recordInclude;
+    private nameOf;
+    private noteRead;
+}
+
+/**
+ * Discovers the units a Ruby file defines: GraphQL fields declared through
+ * a class DSL, controller actions, and client calls.
+ *
+ * A field's boundary binding and declared contract come from the
+ * arguments of its own DSL call. A field written with one of the pack's
+ * wiring keywords declares no type of its own, so its contract and the
+ * method behind it are read from the class the keyword points at, one hop
+ * away. DESIGN.md describes what a field's summary says about the method
+ * behind it and where the reading stops.
+ */
+
+/**
+ * What one run has read from the disk: parsed files by absolute path, so
+ * a class that several fields refer to is only parsed once, and what its
+ * constant lookups have found.
+ */
 interface FileCache {
     get(absPath: string): Promise<Node | null>;
+    readonly constantFiles: ConstantFileCache;
 }
-declare function createFileCache(parse: (source: string) => Promise<Node>, readFile: (absPath: string) => string | null): FileCache;
+declare function createFileCache(parse: (source: string, absPath: string) => Promise<Node>, readFile: (absPath: string) => string | null): FileCache;
 /**
- * What the run's packs said that reading a method body needs. An
- * options object that already declares both fields, `DiscoveryOptions`
- * among them, is one of these and can be passed straight through.
+ * What reading a method body needs from the run's packs. Any options
+ * object that has these fields, `DiscoveryOptions` among them, can be
+ * passed straight through.
  */
 interface BodyReadOptions {
-    /** The run's own facts, which the value evaluator reads a name through. Absent in a test that builds one file by hand. */
+    /** The run's facts, which the value evaluator reads names through. Absent in a test that builds one file by hand. */
     readonly facts?: Database | undefined;
-    /** What a pack needs to say a call talks to the database. Absent when no pack does. */
+    /** The storage patterns that decide whether a call reads or writes the database. Absent when no pack declares any. */
     readonly storage?: RbStorageOptions | undefined;
-    /** The methods every pack in the run said its own library defines, which are left off an effect list. */
+    /** The methods the run's packs declare their libraries define. Calls to them are left off an effect list. */
     readonly inheritedMethods?: InheritedMethods | undefined;
-    /** The calls every pack in the run said run their block as part of the body around it. */
+    /** The calls whose block the run's packs declare runs as part of the surrounding body. */
     readonly bodyBlocks?: BodyBlocks | undefined;
-    /** What each class defines under a name the source computes, by class key. */
+    /** The methods each class defines under a name computed at run time, by class key. */
     readonly dynamicNames?: DynamicNames | undefined;
 }
 interface DiscoveryOptions extends BodyReadOptions {
     packs: RubyPack[];
     /** Repo-relative or absolute path recorded on each summary's `location.file`. */
     filePath: string;
-    /** Absolute path of the file being read, for a block's own `ReachedBody.file`. Falls back to `filePath` when nothing was written to disk. */
+    /** Absolute path of the file being read, used for `ReachedBody.file`. Falls back to `filePath` for a source that is not on disk. */
     absoluteFile?: string;
-    /** What a summary's `location.file` says for a file other than the one being read, which a controller's filters need when an ancestor defines them. */
+    /** The `location.file` to record for another file, needed when a controller's filters come from an ancestor in another file. */
     displayPathOf?: (absolute: string) => string;
     cache: FileCache;
-    /** Called once per discovered unit whose own body is a method this run can follow calls out of, so the reach walk has a place to start. */
+    /** Called once for each discovered unit whose body is a method, so the reach walk can start from it. */
     onReachSeed?: (raw: RawCodeStructure, seed: ReachSeed) => void;
+    /** The shared groups the run's test files define, when a pack reads tests. */
+    sharedGroups?: SharedGroupIndex | undefined;
 }
-/** The method behind a discovered unit's own body, and where it lives, so the reach walk can start there the way it starts at a `def` it found directly. */
+/** The method behind a discovered unit, and where it is, so the reach walk can start there as it does at any `def`. */
 interface ReachSeed {
     readonly file: string;
     readonly node: Node;
@@ -790,16 +1180,16 @@ interface ReachSeed {
 declare function discoverUnits(root: Node, options: DiscoveryOptions): Promise<RawCodeStructure[]>;
 
 /**
- * associations.ts: reading `has_many :statuses` out of a model's body.
+ * Reads association declarations such as `has_many :statuses` out of a
+ * model's body.
  *
- * A pack says which calls declare an association. The target is the
- * class the `class_name:` keyword gives, or the association's own name
- * put through ActiveSupport's default inflections when the declaration
- * gives none. That inflected name is written nowhere in the source, so
- * the declaration comes with a constant reference of its own and the
- * constant bindings settle it from the nesting the model is written in:
- * a `has_many :statuses` inside `Admin::Account` reaches `Admin::Status`
- * before it reaches `Status`.
+ * A pack says which calls declare an association. The target is the class
+ * `class_name:` gives, or the association's name put through the
+ * inflections when the call gives none. The source never writes that
+ * inflected name, so each declaration gets a constant reference of its
+ * own, and the constant bindings settle it from the model's nesting. A
+ * `has_many :statuses` inside `Admin::Account` reaches `Admin::Status`
+ * before `Status`.
  */
 
 /** One association a class or module body declares. */
@@ -812,11 +1202,17 @@ interface AssociationDeclaration {
     readonly target: ConstantReference;
 }
 
-/** A definition every file in the run can see, under the name it is written as. */
+/**
+ * Binds each Ruby constant reference to the definition behind it. Ruby
+ * has no imports, so there is no `imports` fact to follow, and a
+ * reference is bound directly to its definition.
+ */
+
+/** A constant definition, which every file in the run can see, under its qualified name. */
 interface ConstantDefinition {
     readonly qualifiedName: string;
     readonly key: string;
-    /** `class`/`module` opens a constant every file may open again; `X = ...` sets one. */
+    /** A `class` or `module` declaration, which any file may reopen, or an `X = ...` assignment. */
     readonly kind: "declaration" | "assignment";
 }
 /** A constant read somewhere, with the nesting it was read inside. */
@@ -831,69 +1227,79 @@ interface FileConstants {
     readonly filePath: string;
     readonly definitions: readonly ConstantDefinition[];
     readonly references: readonly ConstantReference[];
-    /** Empty unless a pack in the run said what an association declaration looks like. */
+    /** Empty unless a pack in the run declares association calls. */
     readonly associations: readonly AssociationDeclaration[];
 }
 /**
- * Every constant this file defines and every one it reads. One walk, because
- * the nesting a reference is written inside is what the walk already knows.
- * An association's target is read here too: the name it inflects to has no
- * node in the source, and the nesting is what settles which class it means.
+ * Every constant this file defines and every one it reads, in one walk
+ * that tracks the nesting as it goes. An association's target is
+ * collected here too, because the inflected name has no node in the
+ * source and only the nesting says which class it means.
  */
 declare function collectFileConstants(filePath: string, root: Node, associationCalls?: readonly RbAssociationCalls[], inflections?: RbInflections): FileConstants;
 /**
- * Link every constant read anywhere in the run to the definition behind it,
- * looking outwards from the nesting it was read inside the way Ruby does.
+ * Binds every constant read anywhere in the run to its definition,
+ * looking outwards from the nesting it was read inside, the way Ruby
+ * does.
  *
- * `binds(refKey, defKey)` is the link itself. `rbConstantFrom(from, to)`
- * is the same link at file level, which is the closest thing to an
- * import graph a language without imports has.
+ * `binds(refKey, defKey)` records the binding. `importsFile(from, to)`
+ * records the same link between the two files, since reading a constant
+ * another file defines is the nearest thing Ruby has to an import.
  *
- * `declaresAssociation` is emitted here as well, because an association's
- * target is one of those references and the shared rules read the pair
- * together.
+ * `declaresAssociation` is emitted here too, because an association's
+ * target is one of these references and the shared rules join the two.
  */
 declare function emitConstantBindings(db: Database, perFile: Iterable<FileConstants>): void;
 
 /**
- * A node's identity across the whole run. The end is part of it because a
+ * Emits the value facts that the rules in `@suss/resolution` join, for a
+ * Ruby file. The relations and their columns are defined by that package.
+ * The package DESIGN.md describes where Ruby differs from the other
+ * adapters: names keyed on their scope, a bare name that runs a method,
+ * mixins recorded as `extends`, and instance variables as class properties.
+ */
+
+/**
+ * A node's key across the whole run. It includes the end offset because a
  * call and its receiver start at the same offset.
  */
 declare function nodeId(filePath: string, node: Node): string;
 /**
- * The key a read of this expression joins on, for a caller that has an
- * expression in hand and wants to ask the rules about it. `enclosing` is
- * the method the expression is written in, or null outside one.
+ * The key to ask the rules about when reading this expression. `enclosing`
+ * is the method the expression is written in, or null outside one.
+ * `parent` is the node the expression is written in, when the caller has
+ * it, since reading a node's parent off the tree costs a walk from the root.
  *
- * Two Ruby spellings are keyed on a node rather than on a name. Ruby
- * gives `receiver.method` no node of its own, so the method name is
- * where the callee is keyed, and a name Ruby runs as a method is the
- * call itself.
+ * Two kinds of name are keyed on their node instead of on the name. The
+ * tree has no node for the `receiver.method` part of a call, so the
+ * callee is keyed on the method name's node. A bare name that Ruby runs
+ * as a method is the call itself.
  */
-declare function readKey(filePath: string, written: Node, enclosing: Node | null): string;
+declare function readKey(filePath: string, written: Node, enclosing: Node | null, parent?: Node | null): string;
 /**
- * Walk a file and emit the value facts. A method is walked in its own right,
- * so a body's returns and calls belong to the method that wrote them.
+ * Walks a file and emits its value facts. Each method is walked on its
+ * own, so the returns and calls in a body are recorded against the method
+ * they are written in.
  */
-declare function emitValueFacts(db: Database, filePath: string, root: Node, bodyBlocks?: BodyBlocks): void;
+declare function emitValueFacts(db: Database, filePath: string, root: Node, bodyBlocks?: BodyBlocks, scopeCalls?: ReadonlySet<string>): void;
 
 /**
- * The session behind `suss ask why` on a Ruby project: a tree-sitter
- * parse of the asked-about source, a way to point at the expression
- * somebody spelled, and the witness proof of what it resolved to,
- * rendered through `@suss/resolution`'s phrases.
+ * The session behind `suss ask why` on a Ruby project. It parses every
+ * file under the root with tree-sitter, finds the expression a question
+ * points at, and renders the witness proof of what that expression
+ * resolved to through `@suss/resolution`'s phrases.
  *
- * It parses every file under the root and emits the same value and
- * constant facts `extractRubyProject` does, keeping a location for
- * every fact key so a proof's atoms can point back at source. A
- * handle this session hands back pairs a tree-sitter node with the
- * file it came from, since a node alone does not say which file
- * parsed it.
+ * It emits its facts through the same `RunFacts` an extraction over the
+ * same packs uses, and keeps a location for every fact key so each atom
+ * of a proof can point back at source. A handle pairs a tree-sitter node
+ * with its file, since a node alone does not say which file it came from.
  */
 
 interface RubyWhySessionOptions {
-    /** The project root, which paths in every answer come out relative to. */
+    /** The project root. Paths in every answer are relative to it. */
     dir: string;
+    /** The packs the extraction ran with. A hop only a pack declares, such as `Account.find` giving back an Account, is explained only when that pack is here. */
+    packs?: readonly RubyPack[];
 }
 /** A found node, paired with the file it was parsed from. */
 interface RubyValueHandle {
@@ -918,8 +1324,8 @@ declare class RubyWhySession {
     findCallee(file: string, startLine: number, endLine: number, calleeText: string): RubyValueHandle | null;
     /**
      * Why `value` resolves to what it does: the witness proof, flattened
-     * to the chain and rendered. Null when the value does not resolve,
-     * which the caller says in its own words.
+     * to the chain and rendered. Null when the value does not resolve, and
+     * the caller reports that itself.
      */
     explain(value: RubyValueHandle, options?: {
         maxDepth?: number;
@@ -927,38 +1333,59 @@ declare class RubyWhySession {
     private locate;
     private rootOf;
     private pathOf;
-    /** A file path said relative to the root, or as given when it is outside the root. */
+    /** A file path relative to the root, or unchanged when it is outside the root. */
     private displayPath;
 }
 
 /**
- * facts.ts: what discovery hands to the shared fact store.
- *
- * This is the Layer 1 contract: discover units, emit summaries, emit
- * these facts.
- *
- * `entry` reuses the existing relation name and shape, where the unit
- * is a pack-discovered entry point, so a Ruby-discovered field is an
- * entry the same way a Python route or a TypeScript handler is.
+ * One evaluator per project, over the parsed files and the resolution
+ * facts. A reader passes in a node and gets back the abstract value it
+ * comes down to. A route path or a prefix is then built from that value,
+ * so every way of writing it gives the same result.
  *
- * `rbRequires(from, to)` records a `require_relative` whose target is a
- * file in the run. A plain `require` goes through the load path, which
- * this run does not know, so it records nothing.
+ * The facts key a node by file and span, so the evaluator keeps every
+ * file's root to find the node a fact refers to. Without facts, as in a
+ * unit test or when a routes file is read on its own, the evaluator
+ * still follows names within the file through the engine's own scope
+ * walk.
  */
 
+interface EvaluatedFile {
+    readonly file: string;
+    readonly root: Node;
+}
+interface ProjectNodes {
+    readonly files: readonly EvaluatedFile[];
+    /** Every method definition by its node key, for a resolved callee. */
+    readonly definitions: ReadonlyMap<string, Node>;
+}
+/** Registers the parsed project, so reads through `db` can follow the facts back to nodes. */
+declare function bindEvaluator(db: Database, nodes: ProjectNodes): void;
+/** Values to use for the parameters of the block or method around `node`, as a caller would supply them. */
+type ParameterBindings = ReadonlyMap<string, string>;
 /**
- * The name is part of the key because the range is measured in lines, two
- * units can start on the same line, and `entry` is a set, so keying on the range
- * alone would drop one of them.
+ * The abstract value `node` comes down to, through the facts when `db`
+ * was bound. With a site, the value when its receiver is the instance
+ * that site made. That evaluation is not memoized.
+ */
+declare function evaluatedValue(node: Node, db?: Database, bindings?: ParameterBindings, site?: string): Value;
+/** The one string `node` comes down to, or null when it does not settle on one. */
+declare function stringValueOf(node: Node, db?: Database, bindings?: ParameterBindings): string | null;
+/** Every method a file defines, keyed the way the facts key it, for `bindEvaluator`. */
+declare function methodDefinitionsIn(file: string, root: Node): Map<string, Node>;
+
+/**
+ * Runs the Ruby adapter over a project: discovers units, emits summaries
+ * in the shared IR, and emits facts.
+ *
+ * It parses every file it is given, emits the run's facts into one
+ * shared `Database`, runs discovery over each file, walks what each unit
+ * reaches, and hands every unit to `assembleSummary` from
+ * `@suss/extractor`. The Python and TypeScript adapters use the same
+ * assembly step, so gap detection is shared across all three languages.
+ * With a cache, a run after an edit replays the files and methods whose
+ * inputs did not change, through the records in `reuse.ts`.
  */
-declare function unitKey(filePath: string, range: {
-    start: number;
-    end: number;
-}, name: string): string;
-declare function emitEntryFact(db: Database, filePath: string, range: {
-    start: number;
-    end: number;
-}, name: string): void;
 
 interface ExtractRubyOptions {
     /** Absolute paths of the files to parse and extract. */
@@ -976,9 +1403,22 @@ interface ExtractRubyOptions {
     onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
     /** Absolute. `<projectRoot>/.suss/cache` by default; `null` turns it off. */
     cacheDir?: string | null;
-    /** What to do with gaps, which composing a controller's filters can add one of. */
+    /** How to handle gaps. Composing a controller's filters into its actions can add one. */
     gapHandling?: ExtractorOptions["gapHandling"];
+    /** The modules the project lists in `suss.json`, with absolute paths. */
+    modules?: readonly DeclaredModule[];
+    /** Parses an earlier run in this process left, for a file whose text is unchanged. */
+    keptParses?: KeptRubyParses;
 }
+type KeptRubyParses = KeptParses<Node>;
+/** A holder for parses between runs, which frees each tree it lets go of. */
+declare function keptRubyParses(): KeptRubyParses;
+/**
+ * Parses these files into `kept` before any run needs them. A run served
+ * whole from the cache parses nothing, so a process that keeps parses
+ * calls this while nobody is waiting.
+ */
+declare function parseRubyAhead(files: readonly string[], kept: KeptRubyParses): Promise<void>;
 interface ExtractRubyResult {
     summaries: BehavioralSummary[];
     facts: Database;
@@ -991,25 +1431,24 @@ interface FileFactsOptions {
 }
 /**
  * The facts for a single parsed file, with the evaluator bound to them,
- * for a caller that has one file and no project. A pack's own tests need
- * these: what built a receiver is an answer the rules give, and without
- * facts they have nothing to give it from. A project run emits the same
- * facts across every file at once, so a name written in another file
- * resolves there and never here.
+ * for a caller with one file and no project, such as a pack's tests. The
+ * rules need facts to work out what built a receiver. A project run emits
+ * the same facts for every file at once, so a name defined in another
+ * file resolves there but not here.
  */
 declare function factsForFile(options: FileFactsOptions): Database;
 declare function extractRubyProject(options: ExtractRubyOptions): Promise<ExtractRubyResult>;
-/** Every `.rb` file under `root`, depth-first, skipping the usual non-source directories. */
+/** Every `.rb` file under `root`, sorted, skipping vendored, temporary and VCS directories. */
 declare function findRubyFiles(root: string): string[];
 
 /**
  * Evidence for drafting a graphql-ruby `extends-base` dependency stub:
- * every `require`/`require_relative` of the asked package, and every
- * project class whose superclass is spelled from it. Discovery
- * only recognizes a class through `baseClassNames`' literal names (see
- * discovery.ts's `reachesConfiguredBase`), so a project's own base
- * under a renamed namespace, or one that extends the library's own
- * class directly, has to state the exact name.
+ * every `require` or `require_relative` of the requested package, and
+ * every project class whose superclass name is spelled from it.
+ * Discovery only recognizes a class by the literal names in
+ * `baseClassNames`, so a project's own base under a renamed namespace,
+ * or a class that extends the library's class directly, has to be
+ * listed by its exact name.
  */
 interface RubyRequireSite {
     target: string;
@@ -1043,68 +1482,30 @@ declare function rubyStubEvidence(options: RubyStubEvidenceOptions): Promise<Rub
 interface TypeReadContext {
     /** The `Module.nesting` chain in effect, innermost first. */
     nesting: readonly string[];
-    /** Every class the surrounding file defines, by qualified name, so we can tell when one shadows a scalar. */
+    /** Every class the surrounding file defines, by qualified name. A project class shadows a scalar with the same name. */
     knownClasses: ReadonlySet<string>;
     scalars: Readonly<Record<string, TypeShape>>;
     scalarNamePrefixes: readonly string[];
     typeNameConvention: GraphqlTypeNameConvention;
 }
 /**
- * Null means the field abstains. Callers must not fall back to `unknown`, which
- * would read as a contract nobody actually declared.
+ * Returns null when the type cannot be read, and the field then abstains.
+ * A caller must not fall back to `unknown`, because that would report a
+ * contract nobody declared.
  *
- * A bare `constant` is checked against `ctx.nesting` before the scalar table,
- * because a project class at some level of `Module.nesting` is what Ruby itself
- * finds first. A compound `scope_resolution` path is absolute and cannot be
- * shadowed, so it skips that check.
+ * A bare `constant` is checked against `ctx.nesting` before the scalar
+ * table, because Ruby finds a project class at any level of
+ * `Module.nesting` first. A compound `scope_resolution` path is absolute
+ * and cannot be shadowed, so it skips that check.
  */
 declare function typeShapeFromNode(node: Node, ctx: TypeReadContext): TypeShape | null;
 
 /**
- * One evaluator per project, over the parsed files and the resolution
- * facts. A reader hands in a node and gets back the abstract value it
- * comes down to; a route path or a prefix is then spelled from that
- * value rather than read off one syntax shape.
- *
- * The facts key a node by file and span, so the evaluator keeps every
- * file's root to find the node a fact refers to. Without facts,
- * which is how a unit test or a routes file on its own runs, the
- * evaluator still follows names within the file through the engine's
- * own scope walk.
- */
-
-interface EvaluatedFile {
-    readonly file: string;
-    readonly root: Node;
-}
-interface ProjectNodes {
-    readonly files: readonly EvaluatedFile[];
-    /** Every method definition by its node key, for a resolved callee. */
-    readonly definitions: ReadonlyMap<string, Node>;
-}
-/** Register the parsed project, so reads through `db` can follow the facts back to nodes. */
-declare function bindEvaluator(db: Database, nodes: ProjectNodes): void;
-/** Strings to read for the parameters of the block or method `node` is written in, the way a caller would supply them. */
-type ParameterBindings = ReadonlyMap<string, string>;
-/**
- * The abstract value `node` comes down to, through the facts when `db`
- * was bound. With a site, what it comes down to when the receiver
- * behind it is the instance that site made; that run is not memoized.
- */
-declare function evaluatedValue(node: Node, db?: Database, bindings?: ParameterBindings, site?: string): Value;
-/** The one string `node` comes down to, or null when it does not settle on one. */
-declare function stringValueOf(node: Node, db?: Database, bindings?: ParameterBindings): string | null;
-/** Every method a file defines, keyed the way the facts key it, for `bindEvaluator`. */
-declare function methodDefinitionsIn(file: string, root: Node): Map<string, Node>;
-
-/**
- * version.ts: this adapter's own half of the cache key.
- *
- * `ADAPTER_VERSION` is the hand-bumped semver. Bump it on any change
- * that affects extraction output: IR shape, discovery semantics,
- * terminal classification, anything that would invalidate previously
- * cached summaries.
+ * The adapter's part of the cache key. Bump `ADAPTER_VERSION` by hand on
+ * any change to extraction output, such as a change to the IR, to which
+ * units are discovered, or to how a terminal is classified. A summary
+ * cached under the old version is then thrown away.
  */
 declare const ADAPTER_VERSION = "0.1.0";
 
-export { ADAPTER_VERSION, type AncestorEntry, type AncestorLookup, type Ancestry, type CallArgs, type ClassInfo, type ConstantPathConvention, type ControllerActions, type DiscoveryOptions, type EvaluatedFile, type ExtractRubyOptions, type ExtractRubyResult, type FileCache, type FileConstants, type FileFactsOptions, type GraphqlObjectFields, type GraphqlTypeNameConvention, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbAddressingCall, type RbArgumentPlace, type RbBodyBlock, type RbInflections, type RbRawSqlPattern, type RbRowCall, type RbStatusCall, type RbStorageOptions, type RbStoragePattern, type ReachedBody, type RubyDiscoveryPattern, type RubyExtendsSite, type RubyPack, type RubyRequireSite, type RubyStubEvidence, type RubyStubEvidenceOptions, type RubyValueHandle, RubyWhySession, type RubyWhySessionOptions, type TypeReadContext, ancestryOf, bindEvaluator, bodyStatements, booleanLiteralValue, collectFileConstants, createFileCache, discoverUnits, emitConstantBindings, emitEntryFact, emitValueFacts, evaluatedValue, extractRubyProject, factsForFile, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, methodDefinitionsIn, methodInAncestry, nestedStatements, nodeId, parseRuby, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, storageClaims, storageEffects, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, unitKey, walkClasses, walkDefinitions };
+export { ADAPTER_VERSION, type AncestorEntry, type AncestorLookup, type Ancestry, type CallArgs, type ClassInfo, type ConstantFileCache, type ConstantPathConvention, type ControllerActions, type ControllerRoute, type DiscoveryOptions, type EvaluatedFile, type ExtractRubyOptions, type ExtractRubyResult, type FileCache, type FileConstants, type FileFactsOptions, type GraphqlObjectFields, type GraphqlTypeNameConvention, type KeptRubyParses, type LibraryException, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbAddressingCall, type RbArgumentPlace, type RbBodyBlock, type RbExpectations, type RbFactories, type RbFactoryBuilder, type RbFormatSwitch, type RbInflections, type RbPredicateMatcher, type RbRawSqlPattern, type RbRowCall, type RbSharedInclude, type RbStatusCall, type RbStorageOptions, type RbStoragePattern, type RbTestCases, type RbTestClasses, type RbTestMocks, type ReachedBody, type RubyDiscoveryPattern, type RubyExtendsSite, type RubyPack, type RubyRequireSite, type RubyStubEvidence, type RubyStubEvidenceOptions, type RubyValueHandle, RubyWhySession, type RubyWhySessionOptions, type TypeReadContext, ancestryOf, bindEvaluator, bodyStatements, booleanLiteralValue, children, collectFileConstants, createConstantFileCache, createFileCache, discoverUnits, emitConstantBindings, emitValueFacts, evaluatedValue, extractRubyProject, factsForFile, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, keptRubyParses, methodDefinitionsIn, methodInAncestry, nestedStatements, nodeId, parseRuby, parseRubyAhead, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, storageClaims, storageEffects, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, walkClasses, walkDefinitions };