@suss/adapter-ruby 0.22.4 → 0.24.0

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { Tree, Node } from 'web-tree-sitter';
 export { Node as RbNode, Tree as RbTree } from 'web-tree-sitter';
 import { Database } from '@suss/datalog';
 import { TypeShape, BehavioralSummary } from '@suss/behavioral-ir';
-import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic } from '@suss/extractor';
+import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions } from '@suss/extractor';
 import { WhyExplained } from '@suss/resolution';
 import { Value } from '@suss/values';
 
@@ -63,14 +63,20 @@ declare function readCallArgs(argumentList: Node | null): CallArgs;
  *
  * A Ruby codebase locates that file by a naming convention rather than through a
  * load graph a static reader could follow, so we build one path from the
- * constant's own name and check it once against the configured root. Nothing
- * here searches several roots or chooses between candidates.
+ * constant's own name and look for it under the configured root and the
+ * directories Rails autoloads from. No other spelling is tried.
  */
 /** 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;
-/** Null when there is no file at that path. We do not fall back to another root or another spelling. */
+/**
+ * Null when there is no file at that path. Rails autoloads from every
+ * directory directly under `app`, so `ApplicationController` is
+ * `app/controllers/application_controller.rb` and not
+ * `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;
 
 /**
@@ -234,9 +240,57 @@ interface RubyPack {
     /** Wire protocol for the produced boundary bindings, e.g. "http-graphql". */
     protocol: string;
     discovery: RubyDiscoveryPattern[];
+    /** The calls the library gives a project for making a request. */
+    clients?: RbClientCall[];
     /** What the library's own database calls look like. The README says how one is matched. */
     storage?: RbStoragePattern[];
 }
+/**
+ * The calls a library gives a project for making a request. A method
+ * that makes one is a client of the boundary that call states, and gets
+ * a unit bound to its method and path.
+ */
+interface RbClientCall {
+    /** The constant the calls hang on, as a project writes it: `Faraday`, `Net::HTTP`. */
+    constantName: string;
+    /** Method names that state the request method themselves: `get` means GET. */
+    verbMethodNames: Record<string, string>;
+    /** Where a call states the URL. */
+    url: {
+        position: number;
+        keyword?: string;
+    };
+    /** Methods on the constant that build a value taking the same calls, `new` for a Faraday connection. */
+    receiverBuilders?: string[];
+    /** The keyword such a builder takes the base URL under, which comes in front of the path of a call on it. */
+    builderUrlKeyword?: string;
+    /** What the response object gives a caller, so a test on it reads as a test on a status. */
+    response?: RbClientResponse;
+    /** A call that sends a request object built somewhere else, which is how Net::HTTP sends anything with a body. */
+    requestObject?: {
+        /** The method that takes the request object, `request`. */
+        attribute: string;
+        /** Each request class, as a project writes it, and the method it sends: `Net::HTTP::Get` sends GET. */
+        constructors: Record<string, string>;
+        /** Where the request class takes the URL. */
+        urlPosition: number;
+    };
+}
+/**
+ * The members a library's response object gives a caller. A caller that
+ * tests one of them is saying which statuses it handles, and the
+ * checker compares that against what the other side produces.
+ */
+interface RbClientResponse {
+    /** Members whose value is the status: `status` for Faraday, `code` for Net::HTTP. */
+    statusCode?: string[];
+    /** Members that say the request succeeded, meaning a status in 200 to 299: `success?`. */
+    success?: string[];
+    /** Members that give the body: `body`. */
+    body?: string[];
+    /** Whether a refused request comes back as a response or raises where it was made. */
+    failureDelivery?: "response" | "exception";
+}
 /**
  * Ruby writes no return type, so a call is matched by what its receiver
  * inherits from. A model is a class that reaches one of these base classes,
@@ -284,6 +338,33 @@ interface ControllerActions {
     } | null;
     /** 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[];
+    /** The class-level calls the library gives a controller for running one of its own methods around every action, Rails' `before_action` and `rescue_from`. */
+    filters?: RbControllerFilter[];
+}
+/**
+ * A call in a controller's class body naming a method the library runs
+ * around the action, and which actions that reaches. A class inherits
+ * what its ancestors declared, so a filter on `ApplicationController`
+ * reaches every action in the project.
+ */
+interface RbControllerFilter {
+    /** The call as a controller writes it, `before_action`. */
+    name: string;
+    /**
+     * Where the call names the method: `argument` for the leading symbol
+     * of `before_action :require_login`, `withKeyword` for the `with:` of
+     * `rescue_from ActiveRecord::RecordNotFound, with: :not_found`.
+     */
+    methodFrom: "argument" | "withKeyword";
+    /** Set when the library runs the method only for an action that raised, which is what `rescue_from` does. */
+    onThrow?: boolean;
+    /** The name of the call that takes a filter back off, `skip_before_action` for `before_action`. */
+    skippedBy?: string;
+    /** The keywords that narrow a filter to some of the actions, Rails' `only` and `except`. */
+    actionKeywords?: {
+        include: string;
+        exclude: string;
+    };
 }
 /**
  * One call an action writes to send a response, and where that call takes
@@ -385,6 +466,10 @@ interface DiscoveryOptions extends BodyReadOptions {
     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;
+    /** What a summary's `location.file` says for a file other than the one being read, which a controller's filters need when an ancestor defines them. */
+    displayPathOf?: (absolute: string) => string;
+    /** The run's own facts, which the value evaluator reads a name through. Absent in a test that builds one file by hand. */
+    facts?: Database;
     cache: FileCache;
     /** 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;
@@ -547,6 +632,8 @@ interface ExtractRubyOptions {
     onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
     /** Absolute. `<projectRoot>/.suss/cache` by default; `null` turns it off. */
     cacheDir?: string | null;
+    /** What to do with gaps, which composing a controller's filters can add one of. */
+    gapHandling?: ExtractorOptions["gapHandling"];
 }
 interface ExtractRubyResult {
     summaries: BehavioralSummary[];

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { Tree, Node } from 'web-tree-sitter';
 export { Node as RbNode, Tree as RbTree } from 'web-tree-sitter';
 import { Database } from '@suss/datalog';
 import { TypeShape, BehavioralSummary } from '@suss/behavioral-ir';
-import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic } from '@suss/extractor';
+import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions } from '@suss/extractor';
 import { WhyExplained } from '@suss/resolution';
 import { Value } from '@suss/values';
 
@@ -63,14 +63,20 @@ declare function readCallArgs(argumentList: Node | null): CallArgs;
  *
  * A Ruby codebase locates that file by a naming convention rather than through a
  * load graph a static reader could follow, so we build one path from the
- * constant's own name and check it once against the configured root. Nothing
- * here searches several roots or chooses between candidates.
+ * constant's own name and look for it under the configured root and the
+ * directories Rails autoloads from. No other spelling is tried.
  */
 /** 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;
-/** Null when there is no file at that path. We do not fall back to another root or another spelling. */
+/**
+ * Null when there is no file at that path. Rails autoloads from every
+ * directory directly under `app`, so `ApplicationController` is
+ * `app/controllers/application_controller.rb` and not
+ * `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;
 
 /**
@@ -234,9 +240,57 @@ interface RubyPack {
     /** Wire protocol for the produced boundary bindings, e.g. "http-graphql". */
     protocol: string;
     discovery: RubyDiscoveryPattern[];
+    /** The calls the library gives a project for making a request. */
+    clients?: RbClientCall[];
     /** What the library's own database calls look like. The README says how one is matched. */
     storage?: RbStoragePattern[];
 }
+/**
+ * The calls a library gives a project for making a request. A method
+ * that makes one is a client of the boundary that call states, and gets
+ * a unit bound to its method and path.
+ */
+interface RbClientCall {
+    /** The constant the calls hang on, as a project writes it: `Faraday`, `Net::HTTP`. */
+    constantName: string;
+    /** Method names that state the request method themselves: `get` means GET. */
+    verbMethodNames: Record<string, string>;
+    /** Where a call states the URL. */
+    url: {
+        position: number;
+        keyword?: string;
+    };
+    /** Methods on the constant that build a value taking the same calls, `new` for a Faraday connection. */
+    receiverBuilders?: string[];
+    /** The keyword such a builder takes the base URL under, which comes in front of the path of a call on it. */
+    builderUrlKeyword?: string;
+    /** What the response object gives a caller, so a test on it reads as a test on a status. */
+    response?: RbClientResponse;
+    /** A call that sends a request object built somewhere else, which is how Net::HTTP sends anything with a body. */
+    requestObject?: {
+        /** The method that takes the request object, `request`. */
+        attribute: string;
+        /** Each request class, as a project writes it, and the method it sends: `Net::HTTP::Get` sends GET. */
+        constructors: Record<string, string>;
+        /** Where the request class takes the URL. */
+        urlPosition: number;
+    };
+}
+/**
+ * The members a library's response object gives a caller. A caller that
+ * tests one of them is saying which statuses it handles, and the
+ * checker compares that against what the other side produces.
+ */
+interface RbClientResponse {
+    /** Members whose value is the status: `status` for Faraday, `code` for Net::HTTP. */
+    statusCode?: string[];
+    /** Members that say the request succeeded, meaning a status in 200 to 299: `success?`. */
+    success?: string[];
+    /** Members that give the body: `body`. */
+    body?: string[];
+    /** Whether a refused request comes back as a response or raises where it was made. */
+    failureDelivery?: "response" | "exception";
+}
 /**
  * Ruby writes no return type, so a call is matched by what its receiver
  * inherits from. A model is a class that reaches one of these base classes,
@@ -284,6 +338,33 @@ interface ControllerActions {
     } | null;
     /** 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[];
+    /** The class-level calls the library gives a controller for running one of its own methods around every action, Rails' `before_action` and `rescue_from`. */
+    filters?: RbControllerFilter[];
+}
+/**
+ * A call in a controller's class body naming a method the library runs
+ * around the action, and which actions that reaches. A class inherits
+ * what its ancestors declared, so a filter on `ApplicationController`
+ * reaches every action in the project.
+ */
+interface RbControllerFilter {
+    /** The call as a controller writes it, `before_action`. */
+    name: string;
+    /**
+     * Where the call names the method: `argument` for the leading symbol
+     * of `before_action :require_login`, `withKeyword` for the `with:` of
+     * `rescue_from ActiveRecord::RecordNotFound, with: :not_found`.
+     */
+    methodFrom: "argument" | "withKeyword";
+    /** Set when the library runs the method only for an action that raised, which is what `rescue_from` does. */
+    onThrow?: boolean;
+    /** The name of the call that takes a filter back off, `skip_before_action` for `before_action`. */
+    skippedBy?: string;
+    /** The keywords that narrow a filter to some of the actions, Rails' `only` and `except`. */
+    actionKeywords?: {
+        include: string;
+        exclude: string;
+    };
 }
 /**
  * One call an action writes to send a response, and where that call takes
@@ -385,6 +466,10 @@ interface DiscoveryOptions extends BodyReadOptions {
     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;
+    /** What a summary's `location.file` says for a file other than the one being read, which a controller's filters need when an ancestor defines them. */
+    displayPathOf?: (absolute: string) => string;
+    /** The run's own facts, which the value evaluator reads a name through. Absent in a test that builds one file by hand. */
+    facts?: Database;
     cache: FileCache;
     /** 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;
@@ -547,6 +632,8 @@ interface ExtractRubyOptions {
     onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
     /** Absolute. `<projectRoot>/.suss/cache` by default; `null` turns it off. */
     cacheDir?: string | null;
+    /** What to do with gaps, which composing a controller's filters can add one of. */
+    gapHandling?: ExtractorOptions["gapHandling"];
 }
 interface ExtractRubyResult {
     summaries: BehavioralSummary[];