@suss/adapter-ruby 0.22.1 → 0.22.3

package/dist/index.d.cts

@@ -4,6 +4,7 @@ import { Database } from '@suss/datalog';
 import { TypeShape, BehavioralSummary } from '@suss/behavioral-ir';
 import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic } from '@suss/extractor';
 import { WhyExplained } from '@suss/resolution';
+import { Value } from '@suss/values';
 
 /**
  * A new `Parser` for every call, so that parses running at the same time do
@@ -106,6 +107,13 @@ interface ClassInfo {
     qualifiedName: string;
     /** Null when it declares no superclass, or the expression is not a literal constant path. */
     superclassQualifiedName: string | null;
+    /**
+     * Every name the superclass expression can resolve to, in the order Ruby
+     * tries them: each level of the enclosing nesting innermost first, then the
+     * bare name at top level. A compound path is one entry. Empty when there is
+     * no readable superclass.
+     */
+    superclassCandidates: readonly string[];
     /** `body_statement` node, or null for `class Foo; end`. */
     bodyNode: Node | null;
     /** `Module.nesting` in effect inside this class's own body, innermost first. */
@@ -255,6 +263,18 @@ interface ControllerActions {
     ancestryRootClassNames: string[];
     /** Status code a wire response gets when the action does not say otherwise. */
     defaultStatusCode: number;
+    /** The receiverless calls the library gives an action for writing a wire status. Leave it out and 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. */
+    statusCodeNames?: Record<string, number>;
+    /**
+     * 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.
+     */
+    inheritedMethodNames?: string[];
     /** Absolute path of the file this pattern's own routing came from, for the one gap `routingGaps` may report. */
     routesFile: string;
     /** The method and path a project's own routing gives one controller's action, or null when that action has none. */
@@ -265,6 +285,25 @@ interface ControllerActions {
     /** One message per routing declaration kind this pattern's reading left uncovered. A pure read: calling it again gives the same list. */
     routingGaps?: () => readonly 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,
+ * which is what Rails does with `head :ok, status: :created`.
+ */
+interface RbStatusCall {
+    /** The call's own name as an action writes it, `render` for Rails. */
+    name: string;
+    /** The keyword whose value gives the status, `status` for Rails. */
+    statusKeyword?: string;
+    /** 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`.
+     */
+    defaultStatusCode?: number;
+}
 /** A class or module whose ancestry reaches one of `baseClassNames` declares GraphQL fields through DSL calls in its own body. */
 interface GraphqlObjectFields {
     type: "graphqlObjectFields";
@@ -321,20 +360,32 @@ interface RbStorageOptions {
     readonly patterns: readonly RbStoragePattern[];
 }
 
+/** The methods a pack declared the library defines itself, so a receiverless call to one of them is not work the project does. */
+type InheritedMethods = ReadonlySet<string>;
+
 /** Parsed files by absolute path, so a class that several fields refer to is only parsed once. */
 interface FileCache {
     get(absPath: string): Promise<Node | null>;
 }
 declare function createFileCache(parse: (source: string) => Promise<Node>, readFile: (absPath: string) => string | null): FileCache;
-interface DiscoveryOptions {
+/**
+ * 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.
+ */
+interface BodyReadOptions {
+    /** What a pack needs to say a call talks to the database. Absent when no pack does. */
+    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;
+}
+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. */
     absoluteFile?: string;
     cache: FileCache;
-    /** What a pack needs to say a call talks to the database. Absent when no pack does. */
-    storage?: RbStorageOptions | undefined;
     /** 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. */
     onReachSeed?: (raw: RawCodeStructure, seed: ReachSeed) => void;
 }
@@ -563,6 +614,37 @@ interface TypeReadContext {
  */
 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;
+/** The abstract value `node` comes down to, through the facts when `db` was bound. */
+declare function evaluatedValue(node: Node, db?: Database): Value;
+/** The one string `node` comes down to, or null when it does not settle on one. */
+declare function stringValueOf(node: Node, db?: Database): 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.
  *
@@ -573,4 +655,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 ConstantPathConvention, type ControllerActions, type DiscoveryOptions, type ExtractRubyOptions, type ExtractRubyResult, type FileCache, type FileConstants, type GraphqlObjectFields, type GraphqlTypeNameConvention, type MethodLookup, type Range, type RbStoragePattern, type ReachedBody, type RubyDiscoveryPattern, type RubyExtendsSite, type RubyPack, type RubyRequireSite, type RubyStubEvidence, type RubyStubEvidenceOptions, type RubyValueHandle, RubyWhySession, type RubyWhySessionOptions, type TypeReadContext, ancestryOf, bodyStatements, booleanLiteralValue, collectFileConstants, createFileCache, discoverUnits, emitConstantBindings, emitEntryFact, emitValueFacts, extractRubyProject, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, methodInAncestry, nodeId, parseRuby, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, stringLiteralValue, 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 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, nodeId, parseRuby, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, unitKey, walkClasses, walkDefinitions };

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { Database } from '@suss/datalog';
 import { TypeShape, BehavioralSummary } from '@suss/behavioral-ir';
 import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic } from '@suss/extractor';
 import { WhyExplained } from '@suss/resolution';
+import { Value } from '@suss/values';
 
 /**
  * A new `Parser` for every call, so that parses running at the same time do
@@ -106,6 +107,13 @@ interface ClassInfo {
     qualifiedName: string;
     /** Null when it declares no superclass, or the expression is not a literal constant path. */
     superclassQualifiedName: string | null;
+    /**
+     * Every name the superclass expression can resolve to, in the order Ruby
+     * tries them: each level of the enclosing nesting innermost first, then the
+     * bare name at top level. A compound path is one entry. Empty when there is
+     * no readable superclass.
+     */
+    superclassCandidates: readonly string[];
     /** `body_statement` node, or null for `class Foo; end`. */
     bodyNode: Node | null;
     /** `Module.nesting` in effect inside this class's own body, innermost first. */
@@ -255,6 +263,18 @@ interface ControllerActions {
     ancestryRootClassNames: string[];
     /** Status code a wire response gets when the action does not say otherwise. */
     defaultStatusCode: number;
+    /** The receiverless calls the library gives an action for writing a wire status. Leave it out and 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. */
+    statusCodeNames?: Record<string, number>;
+    /**
+     * 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.
+     */
+    inheritedMethodNames?: string[];
     /** Absolute path of the file this pattern's own routing came from, for the one gap `routingGaps` may report. */
     routesFile: string;
     /** The method and path a project's own routing gives one controller's action, or null when that action has none. */
@@ -265,6 +285,25 @@ interface ControllerActions {
     /** One message per routing declaration kind this pattern's reading left uncovered. A pure read: calling it again gives the same list. */
     routingGaps?: () => readonly 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,
+ * which is what Rails does with `head :ok, status: :created`.
+ */
+interface RbStatusCall {
+    /** The call's own name as an action writes it, `render` for Rails. */
+    name: string;
+    /** The keyword whose value gives the status, `status` for Rails. */
+    statusKeyword?: string;
+    /** 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`.
+     */
+    defaultStatusCode?: number;
+}
 /** A class or module whose ancestry reaches one of `baseClassNames` declares GraphQL fields through DSL calls in its own body. */
 interface GraphqlObjectFields {
     type: "graphqlObjectFields";
@@ -321,20 +360,32 @@ interface RbStorageOptions {
     readonly patterns: readonly RbStoragePattern[];
 }
 
+/** The methods a pack declared the library defines itself, so a receiverless call to one of them is not work the project does. */
+type InheritedMethods = ReadonlySet<string>;
+
 /** Parsed files by absolute path, so a class that several fields refer to is only parsed once. */
 interface FileCache {
     get(absPath: string): Promise<Node | null>;
 }
 declare function createFileCache(parse: (source: string) => Promise<Node>, readFile: (absPath: string) => string | null): FileCache;
-interface DiscoveryOptions {
+/**
+ * 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.
+ */
+interface BodyReadOptions {
+    /** What a pack needs to say a call talks to the database. Absent when no pack does. */
+    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;
+}
+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. */
     absoluteFile?: string;
     cache: FileCache;
-    /** What a pack needs to say a call talks to the database. Absent when no pack does. */
-    storage?: RbStorageOptions | undefined;
     /** 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. */
     onReachSeed?: (raw: RawCodeStructure, seed: ReachSeed) => void;
 }
@@ -563,6 +614,37 @@ interface TypeReadContext {
  */
 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;
+/** The abstract value `node` comes down to, through the facts when `db` was bound. */
+declare function evaluatedValue(node: Node, db?: Database): Value;
+/** The one string `node` comes down to, or null when it does not settle on one. */
+declare function stringValueOf(node: Node, db?: Database): 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.
  *
@@ -573,4 +655,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 ConstantPathConvention, type ControllerActions, type DiscoveryOptions, type ExtractRubyOptions, type ExtractRubyResult, type FileCache, type FileConstants, type GraphqlObjectFields, type GraphqlTypeNameConvention, type MethodLookup, type Range, type RbStoragePattern, type ReachedBody, type RubyDiscoveryPattern, type RubyExtendsSite, type RubyPack, type RubyRequireSite, type RubyStubEvidence, type RubyStubEvidenceOptions, type RubyValueHandle, RubyWhySession, type RubyWhySessionOptions, type TypeReadContext, ancestryOf, bodyStatements, booleanLiteralValue, collectFileConstants, createFileCache, discoverUnits, emitConstantBindings, emitEntryFact, emitValueFacts, extractRubyProject, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, methodInAncestry, nodeId, parseRuby, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, stringLiteralValue, 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 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, nodeId, parseRuby, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, unitKey, walkClasses, walkDefinitions };