@suss/adapter-ruby 0.22.4 → 0.23.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;
 
 /**
@@ -284,6 +290,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 +418,8 @@ 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;
     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 +582,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;
 
 /**
@@ -284,6 +290,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 +418,8 @@ 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;
     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 +582,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[];