@suss/adapter-ruby 0.28.0 → 0.30.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
+import { Database } from '@suss/datalog';
 import { Tree, Node } from 'web-tree-sitter';
 export { Node as RbNode, Tree as RbTree } from 'web-tree-sitter';
-import { Database } from '@suss/datalog';
 import { TypeShape, BehavioralSummary } from '@suss/behavioral-ir';
 import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions } from '@suss/extractor';
 import { WhyExplained } from '@suss/resolution';
@@ -38,6 +38,19 @@ 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. */
+interface BodyBlockKind {
+    /** Whether the library only gives the call to a module, so a class writing the same name means something else. */
+    readonly moduleOnly: boolean;
+    /** Whether a `def` in the block declares a method on the class itself rather than 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.
+ */
+type BodyBlocks = ReadonlyMap<string, BodyBlockKind>;
 /** A call whose block is the thing being configured rather than a place statements run. */
 type BlockConfigures = (call: Node) => boolean;
 /**
@@ -92,6 +105,33 @@ declare function underscoreConstantPath(qualifiedName: string, acronyms?: readon
  */
 declare function resolveConstantFile(root: string, qualifiedName: string, convention: ConstantPathConvention, acronyms?: readonly string[]): string | null;
 
+/**
+ * The method names a class gets 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.
+ *
+ * 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
+ * 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. */
+    readonly names: ReadonlySet<string>;
+    /** What a name read only in part has to match for the class to be defining it. */
+    readonly patterns: readonly RegExp[];
+    /** Whether one of them was given a name this reader could not read. */
+    readonly unreadable: boolean;
+}
+/** Every class's reading, by the key the value facts give the class node. */
+type DynamicNames = ReadonlyMap<string, DefinedNames>;
+
 /**
  * Resolves Ruby constant paths against lexical nesting.
  *
@@ -174,6 +214,13 @@ 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. */
+interface BodyReading {
+    readonly facts?: Database | undefined;
+    readonly bodyBlocks?: BodyBlocks | undefined;
+    /** What each class defines under a name the source computes, by class key. */
+    readonly dynamicNames?: DynamicNames | undefined;
+}
 /** What a walk needs to reach a class it knows only by name. */
 interface AncestorLookup {
     /** Directory the constant-to-path convention resolves an ancestor's name against. */
@@ -214,7 +261,8 @@ type MethodLookup =
  * `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 body that calls `define_method`.
+ * is a `define_method` call that defines this name, or one whose own
+ * name this reader could not read.
  */
  | {
     type: "unsettled";
@@ -227,7 +275,7 @@ type MethodLookup =
  * The method `name` resolves to. An unread ancestor nearer than any
  * definition stops the search, since Ruby would have called that one first.
  */
-declare function methodInAncestry(ancestry: Ancestry, name: string): MethodLookup;
+declare function methodInAncestry(ancestry: Ancestry, name: string, read?: BodyReading): MethodLookup;
 /** Every statement of every body reached, most distant ancestor first, so a nearer declaration overwrites what it inherits. */
 declare function inheritedStatements(ancestry: Ancestry, blockConfigures?: BlockConfigures): Array<{
     block: ReachedBody;
@@ -270,6 +318,40 @@ interface RubyPack {
     storage?: RbStoragePattern[];
     /** Calls the library gives a project for reading a model through a batching loader, rather than on the model itself. */
     loaders?: RbLoaderPattern[];
+    /** Calls the library gives 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. */
+    inflections?: RbInflections;
+}
+/**
+ * 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.
+ */
+interface RbInflections {
+    /** Words a constant name keeps whole: `API` gives `APIToken` rather than `ApiToken`. */
+    acronyms?: string[];
+    /** A plural and the singular it comes from: `["people", "person"]`. */
+    irregular?: Array<[plural: string, singular: string]>;
+    /** Words spelled the same in both numbers. */
+    uncountable?: string[];
+    /** A rule turning a word singular, and what the part it matched becomes. A rule written `/body/flags` is a pattern; anything else is the text to replace. */
+    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.
+ */
+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. */
+    moduleOnly?: boolean;
+    /** Set when a `def` in the block declares a method on the class itself rather than on an instance. */
+    definesClassMethods?: boolean;
 }
 /**
  * The calls a library gives a project for making a request. A method
@@ -321,15 +403,50 @@ interface RbClientResponse {
  * 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.
+ *
+ * `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.
  */
 interface RbStoragePattern {
     /** Base classes the library gives a model, `ActiveRecord::Base` for Rails. */
     baseClasses: string[];
-    /** Methods that change what is stored. Anything else reads. */
+    /** Methods the library defines that change what is stored. */
     writes: string[];
+    /** Methods the library defines that run a query. */
+    reads: string[];
+    /** Methods whose result is the model again: one record, or a relation a later read narrows to one. */
+    givesBack: string[];
+    /** Methods that pick rows by the primary key when they are given a positional argument, and the column that is. */
+    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. */
+    associations?: RbAssociationCalls;
     /** Which database is behind the connection, which the project settles. */
     storageSystem: "postgresql" | "mysql" | "sqlite";
 }
+/** 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. */
+    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.
+ */
+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`. */
+    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
@@ -486,10 +603,16 @@ interface GraphqlObjectFields {
 /**
  * storage.ts: which calls in a body talk to the database, for Ruby.
  *
- * A pack says which base class the library gives a model, and a call on a
- * class that reaches that base is a database call. The README says why
- * ancestry. A loader pattern from another pack adds calls that are given
- * the model as an argument instead, and those go through the same test.
+ * 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.
+ *
+ * The class behind the receiver comes from the constant bindings for a chain
+ * written from a constant and from the resolution rules otherwise. A loader
+ * pattern adds calls given the model as an argument, tested the same way.
  */
 
 interface RbStorageOptions {
@@ -516,6 +639,10 @@ interface BodyReadOptions {
     readonly storage?: RbStorageOptions | undefined;
     /** The methods every pack in the run said its own library defines, which 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. */
+    readonly bodyBlocks?: BodyBlocks | undefined;
+    /** What each class defines under a name the source computes, by class key. */
+    readonly dynamicNames?: DynamicNames | undefined;
 }
 interface DiscoveryOptions extends BodyReadOptions {
     packs: RubyPack[];
@@ -540,6 +667,29 @@ interface ReachSeed {
 }
 declare function discoverUnits(root: Node, options: DiscoveryOptions): Promise<RawCodeStructure[]>;
 
+/**
+ * associations.ts: reading `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`.
+ */
+
+/** One association a class or module body declares. */
+interface AssociationDeclaration {
+    /** The class or module whose body declares it, keyed the way a class is. */
+    readonly classKey: string;
+    /** The association's name, as the call writes it. */
+    readonly name: string;
+    /** The class it reaches, as a reference the constant bindings settle. */
+    readonly target: ConstantReference;
+}
+
 /** A definition every file in the run can see, under the name it is written as. */
 interface ConstantDefinition {
     readonly qualifiedName: string;
@@ -559,12 +709,16 @@ 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. */
+    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.
  */
-declare function collectFileConstants(filePath: string, root: Node): FileConstants;
+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.
@@ -572,6 +726,10 @@ declare function collectFileConstants(filePath: string, root: Node): FileConstan
  * `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.
+ *
+ * `declaresAssociation` is emitted here as well, because an association's
+ * target is one of those references and the shared rules read the pair
+ * together.
  */
 declare function emitConstantBindings(db: Database, perFile: Iterable<FileConstants>): void;
 
@@ -590,7 +748,7 @@ declare function readKey(filePath: string, written: Node, enclosing: Node | null
  * 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.
  */
-declare function emitValueFacts(db: Database, filePath: string, root: Node): void;
+declare function emitValueFacts(db: Database, filePath: string, root: Node, bodyBlocks?: BodyBlocks): void;
 
 /**
  * The session behind `suss ask why` on a Ruby project: a tree-sitter
@@ -803,4 +961,4 @@ declare function methodDefinitionsIn(file: string, root: Node): Map<string, Node
  */
 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 GraphqlObjectFields, type GraphqlTypeNameConvention, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbStatusCall, 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, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, methodDefinitionsIn, methodInAncestry, nestedStatements, nodeId, parseRuby, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, unitKey, walkClasses, walkDefinitions };
+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 GraphqlObjectFields, type GraphqlTypeNameConvention, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbBodyBlock, type RbInflections, type RbStatusCall, 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, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, methodDefinitionsIn, methodInAncestry, nestedStatements, nodeId, parseRuby, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, unitKey, walkClasses, walkDefinitions };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
+import { Database } from '@suss/datalog';
 import { Tree, Node } from 'web-tree-sitter';
 export { Node as RbNode, Tree as RbTree } from 'web-tree-sitter';
-import { Database } from '@suss/datalog';
 import { TypeShape, BehavioralSummary } from '@suss/behavioral-ir';
 import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions } from '@suss/extractor';
 import { WhyExplained } from '@suss/resolution';
@@ -38,6 +38,19 @@ 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. */
+interface BodyBlockKind {
+    /** Whether the library only gives the call to a module, so a class writing the same name means something else. */
+    readonly moduleOnly: boolean;
+    /** Whether a `def` in the block declares a method on the class itself rather than 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.
+ */
+type BodyBlocks = ReadonlyMap<string, BodyBlockKind>;
 /** A call whose block is the thing being configured rather than a place statements run. */
 type BlockConfigures = (call: Node) => boolean;
 /**
@@ -92,6 +105,33 @@ declare function underscoreConstantPath(qualifiedName: string, acronyms?: readon
  */
 declare function resolveConstantFile(root: string, qualifiedName: string, convention: ConstantPathConvention, acronyms?: readonly string[]): string | null;
 
+/**
+ * The method names a class gets 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.
+ *
+ * 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
+ * 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. */
+    readonly names: ReadonlySet<string>;
+    /** What a name read only in part has to match for the class to be defining it. */
+    readonly patterns: readonly RegExp[];
+    /** Whether one of them was given a name this reader could not read. */
+    readonly unreadable: boolean;
+}
+/** Every class's reading, by the key the value facts give the class node. */
+type DynamicNames = ReadonlyMap<string, DefinedNames>;
+
 /**
  * Resolves Ruby constant paths against lexical nesting.
  *
@@ -174,6 +214,13 @@ 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. */
+interface BodyReading {
+    readonly facts?: Database | undefined;
+    readonly bodyBlocks?: BodyBlocks | undefined;
+    /** What each class defines under a name the source computes, by class key. */
+    readonly dynamicNames?: DynamicNames | undefined;
+}
 /** What a walk needs to reach a class it knows only by name. */
 interface AncestorLookup {
     /** Directory the constant-to-path convention resolves an ancestor's name against. */
@@ -214,7 +261,8 @@ type MethodLookup =
  * `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 body that calls `define_method`.
+ * is a `define_method` call that defines this name, or one whose own
+ * name this reader could not read.
  */
  | {
     type: "unsettled";
@@ -227,7 +275,7 @@ type MethodLookup =
  * The method `name` resolves to. An unread ancestor nearer than any
  * definition stops the search, since Ruby would have called that one first.
  */
-declare function methodInAncestry(ancestry: Ancestry, name: string): MethodLookup;
+declare function methodInAncestry(ancestry: Ancestry, name: string, read?: BodyReading): MethodLookup;
 /** Every statement of every body reached, most distant ancestor first, so a nearer declaration overwrites what it inherits. */
 declare function inheritedStatements(ancestry: Ancestry, blockConfigures?: BlockConfigures): Array<{
     block: ReachedBody;
@@ -270,6 +318,40 @@ interface RubyPack {
     storage?: RbStoragePattern[];
     /** Calls the library gives a project for reading a model through a batching loader, rather than on the model itself. */
     loaders?: RbLoaderPattern[];
+    /** Calls the library gives 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. */
+    inflections?: RbInflections;
+}
+/**
+ * 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.
+ */
+interface RbInflections {
+    /** Words a constant name keeps whole: `API` gives `APIToken` rather than `ApiToken`. */
+    acronyms?: string[];
+    /** A plural and the singular it comes from: `["people", "person"]`. */
+    irregular?: Array<[plural: string, singular: string]>;
+    /** Words spelled the same in both numbers. */
+    uncountable?: string[];
+    /** A rule turning a word singular, and what the part it matched becomes. A rule written `/body/flags` is a pattern; anything else is the text to replace. */
+    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.
+ */
+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. */
+    moduleOnly?: boolean;
+    /** Set when a `def` in the block declares a method on the class itself rather than on an instance. */
+    definesClassMethods?: boolean;
 }
 /**
  * The calls a library gives a project for making a request. A method
@@ -321,15 +403,50 @@ interface RbClientResponse {
  * 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.
+ *
+ * `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.
  */
 interface RbStoragePattern {
     /** Base classes the library gives a model, `ActiveRecord::Base` for Rails. */
     baseClasses: string[];
-    /** Methods that change what is stored. Anything else reads. */
+    /** Methods the library defines that change what is stored. */
     writes: string[];
+    /** Methods the library defines that run a query. */
+    reads: string[];
+    /** Methods whose result is the model again: one record, or a relation a later read narrows to one. */
+    givesBack: string[];
+    /** Methods that pick rows by the primary key when they are given a positional argument, and the column that is. */
+    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. */
+    associations?: RbAssociationCalls;
     /** Which database is behind the connection, which the project settles. */
     storageSystem: "postgresql" | "mysql" | "sqlite";
 }
+/** 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. */
+    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.
+ */
+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`. */
+    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
@@ -486,10 +603,16 @@ interface GraphqlObjectFields {
 /**
  * storage.ts: which calls in a body talk to the database, for Ruby.
  *
- * A pack says which base class the library gives a model, and a call on a
- * class that reaches that base is a database call. The README says why
- * ancestry. A loader pattern from another pack adds calls that are given
- * the model as an argument instead, and those go through the same test.
+ * 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.
+ *
+ * The class behind the receiver comes from the constant bindings for a chain
+ * written from a constant and from the resolution rules otherwise. A loader
+ * pattern adds calls given the model as an argument, tested the same way.
  */
 
 interface RbStorageOptions {
@@ -516,6 +639,10 @@ interface BodyReadOptions {
     readonly storage?: RbStorageOptions | undefined;
     /** The methods every pack in the run said its own library defines, which 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. */
+    readonly bodyBlocks?: BodyBlocks | undefined;
+    /** What each class defines under a name the source computes, by class key. */
+    readonly dynamicNames?: DynamicNames | undefined;
 }
 interface DiscoveryOptions extends BodyReadOptions {
     packs: RubyPack[];
@@ -540,6 +667,29 @@ interface ReachSeed {
 }
 declare function discoverUnits(root: Node, options: DiscoveryOptions): Promise<RawCodeStructure[]>;
 
+/**
+ * associations.ts: reading `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`.
+ */
+
+/** One association a class or module body declares. */
+interface AssociationDeclaration {
+    /** The class or module whose body declares it, keyed the way a class is. */
+    readonly classKey: string;
+    /** The association's name, as the call writes it. */
+    readonly name: string;
+    /** The class it reaches, as a reference the constant bindings settle. */
+    readonly target: ConstantReference;
+}
+
 /** A definition every file in the run can see, under the name it is written as. */
 interface ConstantDefinition {
     readonly qualifiedName: string;
@@ -559,12 +709,16 @@ 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. */
+    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.
  */
-declare function collectFileConstants(filePath: string, root: Node): FileConstants;
+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.
@@ -572,6 +726,10 @@ declare function collectFileConstants(filePath: string, root: Node): FileConstan
  * `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.
+ *
+ * `declaresAssociation` is emitted here as well, because an association's
+ * target is one of those references and the shared rules read the pair
+ * together.
  */
 declare function emitConstantBindings(db: Database, perFile: Iterable<FileConstants>): void;
 
@@ -590,7 +748,7 @@ declare function readKey(filePath: string, written: Node, enclosing: Node | null
  * 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.
  */
-declare function emitValueFacts(db: Database, filePath: string, root: Node): void;
+declare function emitValueFacts(db: Database, filePath: string, root: Node, bodyBlocks?: BodyBlocks): void;
 
 /**
  * The session behind `suss ask why` on a Ruby project: a tree-sitter
@@ -803,4 +961,4 @@ declare function methodDefinitionsIn(file: string, root: Node): Map<string, Node
  */
 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 GraphqlObjectFields, type GraphqlTypeNameConvention, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbStatusCall, 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, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, methodDefinitionsIn, methodInAncestry, nestedStatements, nodeId, parseRuby, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, unitKey, walkClasses, walkDefinitions };
+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 GraphqlObjectFields, type GraphqlTypeNameConvention, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbBodyBlock, type RbInflections, type RbStatusCall, 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, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, methodDefinitionsIn, methodInAncestry, nestedStatements, nodeId, parseRuby, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, unitKey, walkClasses, walkDefinitions };