@suss/adapter-ruby 0.34.0 → 0.35.0

package/dist/index.d.cts

@@ -40,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
@@ -131,8 +138,9 @@ declare function createConstantFileCache(): ConstantFileCache;
  * `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[], cache?: ConstantFileCache): string | null;
+declare function resolveConstantFile(root: string, qualifiedName: string, convention: ConstantPathConvention, acronyms?: readonly string[], cache?: ConstantFileCache, autoloadRoots?: readonly string[]): string | null;
 
 /**
  * The methods a class defines under a name the source computes.
@@ -142,11 +150,10 @@ declare function resolveConstantFile(root: string, qualifiedName: string, conven
  * Knowing the names lets a lookup for any other name continue up the
  * ancestry instead of stopping at the class.
  *
- * 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.
+ * The calls come in as `definesMethodFrom` facts, and the loops around
+ * them as `elementOf` and `positionOf`. The shared value evaluator reads
+ * each name once for each element of each loop. A name that settles
+ * only in part becomes a pattern the whole name has to match.
  */
 
 /** What the dynamic definitions in one class define. */
@@ -258,6 +265,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[];
@@ -277,9 +286,10 @@ 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>;
@@ -302,6 +312,8 @@ type MethodLookup =
     type: "unsettled";
     reason: string;
     cause: "unreadAncestor" | "dynamicDefine";
+    /** True when an ancestor past the unread one defines it in the project. */
+    definedLater?: boolean;
 } | {
     type: "none";
 };
@@ -618,6 +630,8 @@ 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 code declares no return types, so a call is matched by what its
@@ -663,6 +677,11 @@ interface RbStoragePattern {
     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, instead of building
@@ -797,12 +816,19 @@ interface RbLoaderSource {
     method: string;
 }
 type RubyDiscoveryPattern = GraphqlObjectFields | ControllerActions;
+/** 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. `routeFor` binds each action to the
- * method and path the project's routing gives it. An action `routeFor`
- * has no route for is still discovered, with no boundary binding.
+ * 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";
@@ -810,6 +836,15 @@ interface ControllerActions {
     baseClassNames: string[];
     /** 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. The path convention keeps each one as one word: `ActivityPub` becomes `activitypub`. */
     acronyms?: string[];
@@ -821,6 +856,8 @@ interface ControllerActions {
     responseStatusCalls?: RbStatusCall[];
     /** 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;
     /**
      * Methods every controller inherits from the library, which for Rails
      * are `params`, `render` and the rest of what `ActionController` mixes
@@ -830,11 +867,17 @@ interface ControllerActions {
     inheritedMethodNames?: string[];
     /** Absolute path of the routes file this pattern read, used in the gap `routingGaps` can report. */
     routesFile: string;
-    /** The method and path the project's routing gives one controller action, or null when it has none. */
-    routeFor: (controllerQualifiedName: string, actionName: string) => {
-        method: string;
-        path: string;
-    } | null;
+    /**
+     * 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 that run one of the controller's own methods around its actions, Rails' `before_action` and `rescue_from`. */
@@ -883,6 +926,33 @@ interface RbStatusCall {
      * 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 {
@@ -891,6 +961,8 @@ interface GraphqlObjectFields {
     baseClassNames: string[];
     /** 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. The path convention keeps each one as one word. */
     acronyms?: string[];
@@ -1328,7 +1400,7 @@ interface ExtractRubyOptions {
     onExtractionReport?: (report: ExtractionReport) => void;
     /** Called once with what the cache decided, for `suss extract --timing`. */
     onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
-    /** Absolute. `<projectRoot>/.suss/cache` by default; `null` turns it off. */
+    /** Absolute. `<projectRoot>/.suss/cache` by default, or under `SUSS_CACHE_DIR`; `null` turns it off. */
     cacheDir?: string | null;
     /** How to handle gaps. Composing a controller's filters into its actions can add one. */
     gapHandling?: ExtractorOptions["gapHandling"];
@@ -1435,4 +1507,4 @@ declare function typeShapeFromNode(node: Node, ctx: TypeReadContext): TypeShape
  */
 declare const ADAPTER_VERSION = "0.1.0";
 
-export { ADAPTER_VERSION, type AncestorEntry, type AncestorLookup, type Ancestry, type CallArgs, type ClassInfo, type ConstantFileCache, type ConstantPathConvention, type ControllerActions, type DiscoveryOptions, type EvaluatedFile, type ExtractRubyOptions, type ExtractRubyResult, type FileCache, type FileConstants, type FileFactsOptions, type GraphqlObjectFields, type GraphqlTypeNameConvention, type KeptRubyParses, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbAddressingCall, type RbArgumentPlace, type RbBodyBlock, type RbExpectations, type RbFactories, type RbFactoryBuilder, 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, 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 };
+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 };

package/dist/index.d.ts

@@ -40,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
@@ -131,8 +138,9 @@ declare function createConstantFileCache(): ConstantFileCache;
  * `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[], cache?: ConstantFileCache): string | null;
+declare function resolveConstantFile(root: string, qualifiedName: string, convention: ConstantPathConvention, acronyms?: readonly string[], cache?: ConstantFileCache, autoloadRoots?: readonly string[]): string | null;
 
 /**
  * The methods a class defines under a name the source computes.
@@ -142,11 +150,10 @@ declare function resolveConstantFile(root: string, qualifiedName: string, conven
  * Knowing the names lets a lookup for any other name continue up the
  * ancestry instead of stopping at the class.
  *
- * 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.
+ * The calls come in as `definesMethodFrom` facts, and the loops around
+ * them as `elementOf` and `positionOf`. The shared value evaluator reads
+ * each name once for each element of each loop. A name that settles
+ * only in part becomes a pattern the whole name has to match.
  */
 
 /** What the dynamic definitions in one class define. */
@@ -258,6 +265,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[];
@@ -277,9 +286,10 @@ 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>;
@@ -302,6 +312,8 @@ type MethodLookup =
     type: "unsettled";
     reason: string;
     cause: "unreadAncestor" | "dynamicDefine";
+    /** True when an ancestor past the unread one defines it in the project. */
+    definedLater?: boolean;
 } | {
     type: "none";
 };
@@ -618,6 +630,8 @@ 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 code declares no return types, so a call is matched by what its
@@ -663,6 +677,11 @@ interface RbStoragePattern {
     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, instead of building
@@ -797,12 +816,19 @@ interface RbLoaderSource {
     method: string;
 }
 type RubyDiscoveryPattern = GraphqlObjectFields | ControllerActions;
+/** 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. `routeFor` binds each action to the
- * method and path the project's routing gives it. An action `routeFor`
- * has no route for is still discovered, with no boundary binding.
+ * 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";
@@ -810,6 +836,15 @@ interface ControllerActions {
     baseClassNames: string[];
     /** 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. The path convention keeps each one as one word: `ActivityPub` becomes `activitypub`. */
     acronyms?: string[];
@@ -821,6 +856,8 @@ interface ControllerActions {
     responseStatusCalls?: RbStatusCall[];
     /** 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;
     /**
      * Methods every controller inherits from the library, which for Rails
      * are `params`, `render` and the rest of what `ActionController` mixes
@@ -830,11 +867,17 @@ interface ControllerActions {
     inheritedMethodNames?: string[];
     /** Absolute path of the routes file this pattern read, used in the gap `routingGaps` can report. */
     routesFile: string;
-    /** The method and path the project's routing gives one controller action, or null when it has none. */
-    routeFor: (controllerQualifiedName: string, actionName: string) => {
-        method: string;
-        path: string;
-    } | null;
+    /**
+     * 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 that run one of the controller's own methods around its actions, Rails' `before_action` and `rescue_from`. */
@@ -883,6 +926,33 @@ interface RbStatusCall {
      * 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 {
@@ -891,6 +961,8 @@ interface GraphqlObjectFields {
     baseClassNames: string[];
     /** 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. The path convention keeps each one as one word. */
     acronyms?: string[];
@@ -1328,7 +1400,7 @@ interface ExtractRubyOptions {
     onExtractionReport?: (report: ExtractionReport) => void;
     /** Called once with what the cache decided, for `suss extract --timing`. */
     onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
-    /** Absolute. `<projectRoot>/.suss/cache` by default; `null` turns it off. */
+    /** Absolute. `<projectRoot>/.suss/cache` by default, or under `SUSS_CACHE_DIR`; `null` turns it off. */
     cacheDir?: string | null;
     /** How to handle gaps. Composing a controller's filters into its actions can add one. */
     gapHandling?: ExtractorOptions["gapHandling"];
@@ -1435,4 +1507,4 @@ declare function typeShapeFromNode(node: Node, ctx: TypeReadContext): TypeShape
  */
 declare const ADAPTER_VERSION = "0.1.0";
 
-export { ADAPTER_VERSION, type AncestorEntry, type AncestorLookup, type Ancestry, type CallArgs, type ClassInfo, type ConstantFileCache, type ConstantPathConvention, type ControllerActions, type DiscoveryOptions, type EvaluatedFile, type ExtractRubyOptions, type ExtractRubyResult, type FileCache, type FileConstants, type FileFactsOptions, type GraphqlObjectFields, type GraphqlTypeNameConvention, type KeptRubyParses, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbAddressingCall, type RbArgumentPlace, type RbBodyBlock, type RbExpectations, type RbFactories, type RbFactoryBuilder, 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, 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 };
+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 };