@suss/adapter-ruby 0.35.1 → 0.36.0

package/dist/index.d.cts

@@ -2,8 +2,8 @@ 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, RequestSpellingMetadata, Effect, BehavioralSummary } from '@suss/behavioral-ir';
+import { DeclaredEntryPoint, RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions, DeclaredModule, KeptParses } from '@suss/extractor';
 import { UnwrapsByName, WhyExplained } from '@suss/resolution';
-import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions, DeclaredModule, KeptParses } from '@suss/extractor';
 import { Value } from '@suss/values';
 
 /**
@@ -284,6 +284,12 @@ interface AncestorLookup {
      * file is visible without a file of its own.
      */
     localDefinition?(qualifiedName: string): ReachedBody[] | null;
+    /**
+     * The blocks any file in the run defines under a name, consulted after
+     * `localDefinition` and before the path convention. The path convention
+     * then only finds a class the run did not read.
+     */
+    definedInRun?(qualifiedName: string): Promise<ReachedBody[] | null>;
 }
 /**
  * Every block a file defines under `qualifiedName`, or null when no file
@@ -352,9 +358,22 @@ interface RubyPack {
      * cache key, so editing one of them forces a re-extract.
      */
     discoveryInputs?: (files: readonly string[]) => string[];
+    /**
+     * Files the library renders through ERB when the app boots, such as
+     * Rails' `config/database.yml`, as absolute paths. The adapter reads
+     * each one as the Ruby in its tags, run when the app loads, so a read of
+     * `ENV` there goes on a load-time unit for the file.
+     */
+    bootTemplates?: () => string[];
     /** Wire protocol for the boundary bindings the pack produces, e.g. "http-graphql". */
     protocol: string;
     discovery: RubyDiscoveryPattern[];
+    /**
+     * The methods a deploy manifest says the platform calls in a file,
+     * given the file's absolute path. The adapter builds the units on each
+     * method it finds by name, and the call walk starts there.
+     */
+    entryPoints?: (file: string) => DeclaredEntryPoint[];
     /** The calls the library offers a project for making a request. */
     clients?: RbClientCall[];
     /** The library's model calls that read or write the database. */
@@ -954,6 +973,23 @@ interface RbFormatSwitch {
     /** The format that accepts every request, `any` for Rails. */
     matchesEvery?: string;
 }
+/**
+ * The methods a library runs on a wired class before the one that
+ * resolves the field. A hook that raises ends the field with that
+ * exception. A hook whose value is false or nil stops the field, and the
+ * resolver never runs. Any other value lets the field go on to the next
+ * hook, then to the resolver.
+ */
+interface RbResolverHooks {
+    /** The hook methods, in the order the library runs them. */
+    methods: string[];
+    /**
+     * True when the library takes a list's first element as the hook's
+     * answer, so `return false, payload` stops the field and returns the
+     * payload in its place.
+     */
+    answerIsListHead?: boolean;
+}
 /** A class or module whose ancestry reaches one of `baseClassNames` declares GraphQL fields through DSL calls in its own body. */
 interface GraphqlObjectFields {
     type: "graphqlObjectFields";
@@ -975,6 +1011,10 @@ interface GraphqlObjectFields {
     wiringKeywords: string[];
     /** The method a wired class defines to resolve the field it is wired to. */
     resolverMethodName: string;
+    /** The keyword on a field call that says which of the type's own methods resolves it, in place of the method with the field's name. */
+    resolverMethodKeyword?: string;
+    /** The methods the library runs on a wired class before `resolverMethodName`, any of which can stop the field. */
+    resolverHooks?: RbResolverHooks;
     /** The library's own classes that a project's class chain ends at. */
     ancestryRootClassNames: string[];
     /** The keyword on an argument call that says whether the argument is required. */
@@ -1009,6 +1049,20 @@ interface GraphqlObjectFields {
     };
 }
 
+/**
+ * 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>;
+/** An effect a reader built from the source, and the node it built it from. */
+interface EffectAt {
+    effect: Effect;
+    at: Node;
+}
+
 /**
  * Finds the calls in a Ruby body that read or write the database.
  *
@@ -1050,16 +1104,7 @@ declare function storageClaims(call: Node, file: string, options: RbStorageOptio
  * 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 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>;
+declare function storageEffects(calls: readonly Node[], file: string, options: RbStorageOptions, enclosing?: Node | null): EffectAt[];
 
 /**
  * The shared groups a run's test files define, and where each one is
@@ -1507,4 +1552,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 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 };
+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 RbResolverHooks, 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

@@ -2,8 +2,8 @@ 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, RequestSpellingMetadata, Effect, BehavioralSummary } from '@suss/behavioral-ir';
+import { DeclaredEntryPoint, RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions, DeclaredModule, KeptParses } from '@suss/extractor';
 import { UnwrapsByName, WhyExplained } from '@suss/resolution';
-import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions, DeclaredModule, KeptParses } from '@suss/extractor';
 import { Value } from '@suss/values';
 
 /**
@@ -284,6 +284,12 @@ interface AncestorLookup {
      * file is visible without a file of its own.
      */
     localDefinition?(qualifiedName: string): ReachedBody[] | null;
+    /**
+     * The blocks any file in the run defines under a name, consulted after
+     * `localDefinition` and before the path convention. The path convention
+     * then only finds a class the run did not read.
+     */
+    definedInRun?(qualifiedName: string): Promise<ReachedBody[] | null>;
 }
 /**
  * Every block a file defines under `qualifiedName`, or null when no file
@@ -352,9 +358,22 @@ interface RubyPack {
      * cache key, so editing one of them forces a re-extract.
      */
     discoveryInputs?: (files: readonly string[]) => string[];
+    /**
+     * Files the library renders through ERB when the app boots, such as
+     * Rails' `config/database.yml`, as absolute paths. The adapter reads
+     * each one as the Ruby in its tags, run when the app loads, so a read of
+     * `ENV` there goes on a load-time unit for the file.
+     */
+    bootTemplates?: () => string[];
     /** Wire protocol for the boundary bindings the pack produces, e.g. "http-graphql". */
     protocol: string;
     discovery: RubyDiscoveryPattern[];
+    /**
+     * The methods a deploy manifest says the platform calls in a file,
+     * given the file's absolute path. The adapter builds the units on each
+     * method it finds by name, and the call walk starts there.
+     */
+    entryPoints?: (file: string) => DeclaredEntryPoint[];
     /** The calls the library offers a project for making a request. */
     clients?: RbClientCall[];
     /** The library's model calls that read or write the database. */
@@ -954,6 +973,23 @@ interface RbFormatSwitch {
     /** The format that accepts every request, `any` for Rails. */
     matchesEvery?: string;
 }
+/**
+ * The methods a library runs on a wired class before the one that
+ * resolves the field. A hook that raises ends the field with that
+ * exception. A hook whose value is false or nil stops the field, and the
+ * resolver never runs. Any other value lets the field go on to the next
+ * hook, then to the resolver.
+ */
+interface RbResolverHooks {
+    /** The hook methods, in the order the library runs them. */
+    methods: string[];
+    /**
+     * True when the library takes a list's first element as the hook's
+     * answer, so `return false, payload` stops the field and returns the
+     * payload in its place.
+     */
+    answerIsListHead?: boolean;
+}
 /** A class or module whose ancestry reaches one of `baseClassNames` declares GraphQL fields through DSL calls in its own body. */
 interface GraphqlObjectFields {
     type: "graphqlObjectFields";
@@ -975,6 +1011,10 @@ interface GraphqlObjectFields {
     wiringKeywords: string[];
     /** The method a wired class defines to resolve the field it is wired to. */
     resolverMethodName: string;
+    /** The keyword on a field call that says which of the type's own methods resolves it, in place of the method with the field's name. */
+    resolverMethodKeyword?: string;
+    /** The methods the library runs on a wired class before `resolverMethodName`, any of which can stop the field. */
+    resolverHooks?: RbResolverHooks;
     /** The library's own classes that a project's class chain ends at. */
     ancestryRootClassNames: string[];
     /** The keyword on an argument call that says whether the argument is required. */
@@ -1009,6 +1049,20 @@ interface GraphqlObjectFields {
     };
 }
 
+/**
+ * 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>;
+/** An effect a reader built from the source, and the node it built it from. */
+interface EffectAt {
+    effect: Effect;
+    at: Node;
+}
+
 /**
  * Finds the calls in a Ruby body that read or write the database.
  *
@@ -1050,16 +1104,7 @@ declare function storageClaims(call: Node, file: string, options: RbStorageOptio
  * 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 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>;
+declare function storageEffects(calls: readonly Node[], file: string, options: RbStorageOptions, enclosing?: Node | null): EffectAt[];
 
 /**
  * The shared groups a run's test files define, and where each one is
@@ -1507,4 +1552,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 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 };
+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 RbResolverHooks, 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 };