@suss/adapter-ruby 0.26.0 → 0.28.0

package/dist/index.d.cts

@@ -31,6 +31,13 @@ interface Range {
 }
 declare function field(node: Node, name: string): Node | null;
 declare function bodyStatements(body: Node): Node[];
+/**
+ * Every statement written directly inside a branching statement's
+ * branches, across its `elsif`, `else`, `when`, `rescue` and `ensure`
+ * clauses. A statement inside a nested branching statement is not
+ * included; the caller descends into that one itself.
+ */
+declare function nestedStatements(stmt: Node): Node[];
 /** A call whose block is the thing being configured rather than a place statements run. */
 type BlockConfigures = (call: Node) => boolean;
 /**
@@ -68,8 +75,14 @@ declare function readCallArgs(argumentList: Node | null): CallArgs;
  */
 /** A pack picks a convention by name, and the code for each one lives here. */
 type ConstantPathConvention = "railsUnderscore";
-/** Ported from ActiveSupport's own `String#underscore`, which is what Rails autoloading runs a constant path through. */
-declare function underscoreConstantPath(qualifiedName: string): string;
+/**
+ * Ported from ActiveSupport's own `String#underscore`, which is what
+ * Rails autoloading runs a constant path through. An acronym the
+ * project registers with the inflector is one word to it, so with
+ * `ActivityPub` registered the path is `activitypub`, not
+ * `activity_pub`.
+ */
+declare function underscoreConstantPath(qualifiedName: string, acronyms?: readonly string[]): string;
 /**
  * Null when there is no file at that path. Rails autoloads from every
  * directory directly under `app`, so `ApplicationController` is
@@ -77,14 +90,14 @@ declare function underscoreConstantPath(qualifiedName: string): string;
  * `app/application_controller.rb`; those directories are tried after
  * the root itself, in name order, and no other spelling is tried.
  */
-declare function resolveConstantFile(root: string, qualifiedName: string, convention: ConstantPathConvention): string | null;
+declare function resolveConstantFile(root: string, qualifiedName: string, convention: ConstantPathConvention, acronyms?: readonly string[]): string | null;
 
 /**
  * Resolves Ruby constant paths against lexical nesting.
  *
- * A compound path written out, like `Data::Record`, means the same thing
- * wherever it appears, so its text is the qualified name. A bare name is
- * relative to the nesting it is written inside. `require` is never resolved,
+ * A compound path referenced, like `Data::Record`, is read as absolute. A
+ * bare name is relative to the nesting it is written inside, and so is a
+ * compound name `class` or `module` opens. `require` is never resolved,
  * because Rails autoloads by naming convention rather than through a load graph
  * a static reader could follow, so a constant that nesting alone cannot qualify
  * keeps whatever name the source wrote and callers treat it as unresolved.
@@ -141,7 +154,13 @@ interface ReachedBody {
     /** Absolute path of the file the block is written in. */
     file: string;
 }
-/** One ancestor: every block reopening its name, or the name alone when nothing reached it. Blocks stay together because Ruby treats a reopened class as one place in the chain. */
+/**
+ * One ancestor: every block reopening its name, the name alone when
+ * nothing reached it, or the library's own class the walk stopped at.
+ * Blocks stay together because Ruby treats a reopened class as one
+ * place in the chain. The root is kept by name so a caller can tell a
+ * chain that ended at the library from one that ended at nothing.
+ */
 type AncestorEntry = {
     type: "bodies";
     name: string;
@@ -149,6 +168,9 @@ type AncestorEntry = {
 } | {
     type: "unfollowed";
     name: string;
+} | {
+    type: "root";
+    name: string;
 };
 /** A class and everything it inherits from, in Ruby's own method-lookup order. */
 type Ancestry = readonly AncestorEntry[];
@@ -157,6 +179,8 @@ interface AncestorLookup {
     /** Directory the constant-to-path convention resolves an ancestor's name against. */
     root: string;
     pathConvention: ConstantPathConvention;
+    /** Acronyms the convention keeps as one word, `ActivityPub` to `activitypub`. */
+    acronyms?: readonly string[];
     /**
      * The library's own classes a project's chain ends at. Reaching one
      * ends a walk with nothing left unfollowed.
@@ -324,15 +348,17 @@ interface RbLoaderPattern {
     shortcuts: string[];
 }
 type RubyDiscoveryPattern = GraphqlObjectFields | ControllerActions;
-/** A class whose ancestry reaches one of `baseClassNames` is a controller, and every instance method it defines directly is one of its actions, bound by `routeFor` to the method and path a project's own routing gives it, or discovered with no boundary binding when `routeFor` finds none. */
+/** A class whose ancestry reaches one of `baseClassNames` or `ancestryRootClassNames` is a controller, and every instance method it defines directly is one of its actions, bound by `routeFor` to the method and path a project's own routing gives it, or discovered with no boundary binding when `routeFor` finds none. */
 interface ControllerActions {
     type: "controllerActions";
-    /** The library's own base a project's controllers extend, `ActionController::Base` say. */
+    /** A base a project's controllers extend, `ApplicationController` say. The base itself is not a controller. */
     baseClassNames: string[];
     /** The directory a bare superclass name is looked up under, the project's own layout. */
     root: string;
     pathConvention: ConstantPathConvention;
-    /** The library's own classes a project's controller chain ends at. */
+    /** Acronyms the project registers with the inflector, which the path convention keeps as one word: `ActivityPub` is `activitypub`, not `activity_pub`. */
+    acronyms?: string[];
+    /** The library's own classes a project's controller chain ends at. A class extending one directly is a controller too. */
     ancestryRootClassNames: string[];
     /** Status code a wire response gets when the action does not say otherwise. */
     defaultStatusCode: number;
@@ -412,6 +438,8 @@ interface GraphqlObjectFields {
     /** The directory a wiring keyword's referenced class is looked up under. That is the project's own layout, not the library's. */
     root: string;
     pathConvention: ConstantPathConvention;
+    /** Acronyms the project registers with the inflector, which the path convention keeps as one word. */
+    acronyms?: string[];
     /** The DSL call declaring one schema field in an object type's body. */
     fieldCallName: string;
     /** The DSL call declaring a referenced class's own return type. */
@@ -516,6 +544,8 @@ declare function discoverUnits(root: Node, options: DiscoveryOptions): Promise<R
 interface ConstantDefinition {
     readonly qualifiedName: string;
     readonly key: string;
+    /** `class`/`module` opens a constant every file may open again; `X = ...` sets one. */
+    readonly kind: "declaration" | "assignment";
 }
 /** A constant read somewhere, with the nesting it was read inside. */
 interface ConstantReference {
@@ -555,7 +585,7 @@ declare function nodeId(filePath: string, node: Node): string;
  * expression in hand and wants to ask the rules about it. `enclosing` is
  * the method the expression is written in, or null outside one.
  */
-declare function readKey(filePath: string, node: Node, enclosing: Node | null): string;
+declare function readKey(filePath: string, written: Node, enclosing: Node | null): string;
 /**
  * Walk a file and emit the value facts. A method is walked in its own right,
  * so a body's returns and calls belong to the method that wrote them.
@@ -754,10 +784,12 @@ interface ProjectNodes {
 }
 /** Register the parsed project, so reads through `db` can follow the facts back to nodes. */
 declare function bindEvaluator(db: Database, nodes: ProjectNodes): void;
+/** Strings to read for the parameters of the block or method `node` is written in, the way a caller would supply them. */
+type ParameterBindings = ReadonlyMap<string, string>;
 /** The abstract value `node` comes down to, through the facts when `db` was bound. */
-declare function evaluatedValue(node: Node, db?: Database): Value;
+declare function evaluatedValue(node: Node, db?: Database, bindings?: ParameterBindings): 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;
+declare function stringValueOf(node: Node, db?: Database, bindings?: ParameterBindings): string | null;
 /** Every method a file defines, keyed the way the facts key it, for `bindEvaluator`. */
 declare function methodDefinitionsIn(file: string, root: Node): Map<string, Node>;
 
@@ -771,4 +803,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 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 };
+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 };

package/dist/index.d.ts

@@ -31,6 +31,13 @@ interface Range {
 }
 declare function field(node: Node, name: string): Node | null;
 declare function bodyStatements(body: Node): Node[];
+/**
+ * Every statement written directly inside a branching statement's
+ * branches, across its `elsif`, `else`, `when`, `rescue` and `ensure`
+ * clauses. A statement inside a nested branching statement is not
+ * included; the caller descends into that one itself.
+ */
+declare function nestedStatements(stmt: Node): Node[];
 /** A call whose block is the thing being configured rather than a place statements run. */
 type BlockConfigures = (call: Node) => boolean;
 /**
@@ -68,8 +75,14 @@ declare function readCallArgs(argumentList: Node | null): CallArgs;
  */
 /** A pack picks a convention by name, and the code for each one lives here. */
 type ConstantPathConvention = "railsUnderscore";
-/** Ported from ActiveSupport's own `String#underscore`, which is what Rails autoloading runs a constant path through. */
-declare function underscoreConstantPath(qualifiedName: string): string;
+/**
+ * Ported from ActiveSupport's own `String#underscore`, which is what
+ * Rails autoloading runs a constant path through. An acronym the
+ * project registers with the inflector is one word to it, so with
+ * `ActivityPub` registered the path is `activitypub`, not
+ * `activity_pub`.
+ */
+declare function underscoreConstantPath(qualifiedName: string, acronyms?: readonly string[]): string;
 /**
  * Null when there is no file at that path. Rails autoloads from every
  * directory directly under `app`, so `ApplicationController` is
@@ -77,14 +90,14 @@ declare function underscoreConstantPath(qualifiedName: string): string;
  * `app/application_controller.rb`; those directories are tried after
  * the root itself, in name order, and no other spelling is tried.
  */
-declare function resolveConstantFile(root: string, qualifiedName: string, convention: ConstantPathConvention): string | null;
+declare function resolveConstantFile(root: string, qualifiedName: string, convention: ConstantPathConvention, acronyms?: readonly string[]): string | null;
 
 /**
  * Resolves Ruby constant paths against lexical nesting.
  *
- * A compound path written out, like `Data::Record`, means the same thing
- * wherever it appears, so its text is the qualified name. A bare name is
- * relative to the nesting it is written inside. `require` is never resolved,
+ * A compound path referenced, like `Data::Record`, is read as absolute. A
+ * bare name is relative to the nesting it is written inside, and so is a
+ * compound name `class` or `module` opens. `require` is never resolved,
  * because Rails autoloads by naming convention rather than through a load graph
  * a static reader could follow, so a constant that nesting alone cannot qualify
  * keeps whatever name the source wrote and callers treat it as unresolved.
@@ -141,7 +154,13 @@ interface ReachedBody {
     /** Absolute path of the file the block is written in. */
     file: string;
 }
-/** One ancestor: every block reopening its name, or the name alone when nothing reached it. Blocks stay together because Ruby treats a reopened class as one place in the chain. */
+/**
+ * One ancestor: every block reopening its name, the name alone when
+ * nothing reached it, or the library's own class the walk stopped at.
+ * Blocks stay together because Ruby treats a reopened class as one
+ * place in the chain. The root is kept by name so a caller can tell a
+ * chain that ended at the library from one that ended at nothing.
+ */
 type AncestorEntry = {
     type: "bodies";
     name: string;
@@ -149,6 +168,9 @@ type AncestorEntry = {
 } | {
     type: "unfollowed";
     name: string;
+} | {
+    type: "root";
+    name: string;
 };
 /** A class and everything it inherits from, in Ruby's own method-lookup order. */
 type Ancestry = readonly AncestorEntry[];
@@ -157,6 +179,8 @@ interface AncestorLookup {
     /** Directory the constant-to-path convention resolves an ancestor's name against. */
     root: string;
     pathConvention: ConstantPathConvention;
+    /** Acronyms the convention keeps as one word, `ActivityPub` to `activitypub`. */
+    acronyms?: readonly string[];
     /**
      * The library's own classes a project's chain ends at. Reaching one
      * ends a walk with nothing left unfollowed.
@@ -324,15 +348,17 @@ interface RbLoaderPattern {
     shortcuts: string[];
 }
 type RubyDiscoveryPattern = GraphqlObjectFields | ControllerActions;
-/** A class whose ancestry reaches one of `baseClassNames` is a controller, and every instance method it defines directly is one of its actions, bound by `routeFor` to the method and path a project's own routing gives it, or discovered with no boundary binding when `routeFor` finds none. */
+/** A class whose ancestry reaches one of `baseClassNames` or `ancestryRootClassNames` is a controller, and every instance method it defines directly is one of its actions, bound by `routeFor` to the method and path a project's own routing gives it, or discovered with no boundary binding when `routeFor` finds none. */
 interface ControllerActions {
     type: "controllerActions";
-    /** The library's own base a project's controllers extend, `ActionController::Base` say. */
+    /** A base a project's controllers extend, `ApplicationController` say. The base itself is not a controller. */
     baseClassNames: string[];
     /** The directory a bare superclass name is looked up under, the project's own layout. */
     root: string;
     pathConvention: ConstantPathConvention;
-    /** The library's own classes a project's controller chain ends at. */
+    /** Acronyms the project registers with the inflector, which the path convention keeps as one word: `ActivityPub` is `activitypub`, not `activity_pub`. */
+    acronyms?: string[];
+    /** The library's own classes a project's controller chain ends at. A class extending one directly is a controller too. */
     ancestryRootClassNames: string[];
     /** Status code a wire response gets when the action does not say otherwise. */
     defaultStatusCode: number;
@@ -412,6 +438,8 @@ interface GraphqlObjectFields {
     /** The directory a wiring keyword's referenced class is looked up under. That is the project's own layout, not the library's. */
     root: string;
     pathConvention: ConstantPathConvention;
+    /** Acronyms the project registers with the inflector, which the path convention keeps as one word. */
+    acronyms?: string[];
     /** The DSL call declaring one schema field in an object type's body. */
     fieldCallName: string;
     /** The DSL call declaring a referenced class's own return type. */
@@ -516,6 +544,8 @@ declare function discoverUnits(root: Node, options: DiscoveryOptions): Promise<R
 interface ConstantDefinition {
     readonly qualifiedName: string;
     readonly key: string;
+    /** `class`/`module` opens a constant every file may open again; `X = ...` sets one. */
+    readonly kind: "declaration" | "assignment";
 }
 /** A constant read somewhere, with the nesting it was read inside. */
 interface ConstantReference {
@@ -555,7 +585,7 @@ declare function nodeId(filePath: string, node: Node): string;
  * expression in hand and wants to ask the rules about it. `enclosing` is
  * the method the expression is written in, or null outside one.
  */
-declare function readKey(filePath: string, node: Node, enclosing: Node | null): string;
+declare function readKey(filePath: string, written: Node, enclosing: Node | null): string;
 /**
  * Walk a file and emit the value facts. A method is walked in its own right,
  * so a body's returns and calls belong to the method that wrote them.
@@ -754,10 +784,12 @@ interface ProjectNodes {
 }
 /** Register the parsed project, so reads through `db` can follow the facts back to nodes. */
 declare function bindEvaluator(db: Database, nodes: ProjectNodes): void;
+/** Strings to read for the parameters of the block or method `node` is written in, the way a caller would supply them. */
+type ParameterBindings = ReadonlyMap<string, string>;
 /** The abstract value `node` comes down to, through the facts when `db` was bound. */
-declare function evaluatedValue(node: Node, db?: Database): Value;
+declare function evaluatedValue(node: Node, db?: Database, bindings?: ParameterBindings): 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;
+declare function stringValueOf(node: Node, db?: Database, bindings?: ParameterBindings): string | null;
 /** Every method a file defines, keyed the way the facts key it, for `bindEvaluator`. */
 declare function methodDefinitionsIn(file: string, root: Node): Map<string, Node>;
 
@@ -771,4 +803,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 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 };
+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 };