@suss/adapter-ruby 0.32.0 → 0.33.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 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, BehavioralSummary } from '@suss/behavioral-ir';
+import { TypeShape, Effect, BehavioralSummary } from '@suss/behavioral-ir';
 import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions } from '@suss/extractor';
 import { WhyExplained } from '@suss/resolution';
 import { Value } from '@suss/values';
@@ -316,6 +316,8 @@ interface RubyPack {
     clients?: RbClientCall[];
     /** What the library's own database calls look like. The README says how one is matched. */
     storage?: RbStoragePattern[];
+    /** The calls the library gives a project for handing the store a statement it wrote itself. */
+    rawSql?: RbRawSqlPattern[];
     /** Calls the library gives a project for reading a model through a batching loader, rather than on the model itself. */
     loaders?: RbLoaderPattern[];
     /** Calls the library gives a class or module body whose block runs as part of that body. */
@@ -417,6 +419,17 @@ interface RbStoragePattern {
     reads: string[];
     /** Methods whose result is the model again: one record, or a relation a later read narrows to one. */
     givesBack: string[];
+    /**
+     * Methods on the model that take a statement the project wrote itself,
+     * and where each one takes it. The tables come from the statement, so
+     * one of these says nothing about the model's own container, and the
+     * statement is read in the dialect of `storageSystem`.
+     */
+    statements?: Record<string, RbArgumentPlace>;
+    /** The token the library writes where a bind value goes, ActiveRecord's `?`. */
+    bindPlaceholder?: string;
+    /** The methods the library runs of its own accord when a write happens, `after_commit :sync_search`. */
+    callbacks?: RbModelCallbacks;
     /** Methods that pick rows by the primary key when they are given a positional argument, and the column that is. */
     byPrimaryKey?: RbPrimaryKeyLookup;
     /** Read methods whose symbol arguments are the columns they ask for. */
@@ -426,7 +439,88 @@ interface RbStoragePattern {
     /** Which database is behind the connection, which the project settles. */
     storageSystem: "postgresql" | "mysql" | "sqlite";
 }
+/**
+ * A library whose calls take SQL the project wrote, rather than
+ * building it from a model. Ruby writes no types, so the receiver is
+ * typed by following it back to the library call that produced it: the
+ * chain starts at `constantName`, one of `clientBuilders` gives back a
+ * client, and `addressing` calls narrow that client to a part of the
+ * store before the statement or the row call arrives.
+ */
+interface RbRawSqlPattern {
+    /** The constant the library's calls start at, `PG` or `Google::Cloud::Bigquery`. */
+    constantName: string;
+    /**
+     * Base classes whose subclasses hand a client out the same way the
+     * constant does, `ActiveRecord::Base` for Rails. A project writes
+     * `Account.connection` and a bare `connection` inside the model as
+     * readily as the base class itself, and all three reach one store.
+     */
+    baseClasses?: string[];
+    /** Methods on that constant that give back a client, `connect` for the pg gem. */
+    clientBuilders: string[];
+    /** Calls that narrow a client to part of the store and give back something the rest of the calls can be made on. */
+    addressing?: Record<string, RbAddressingCall>;
+    /** Calls that take a statement, and where each one takes it. */
+    statements?: Record<string, RbArgumentPlace>;
+    /** The token the library writes where a bind value goes, when it is not the one the dialect itself reads. */
+    bindPlaceholder?: string;
+    /** Calls that read or write rows of an addressed container with no statement, `insert` on a BigQuery table. */
+    rowCalls?: Record<string, RbRowCall>;
+    /** Which store is behind the calls, in the words OpenTelemetry's semantic conventions use: `postgresql`, `gcp.bigquery`. */
+    storageSystem: string;
+    /**
+     * Which dialect the statements are written in, which is a separate
+     * answer from the store: BigQuery's store is `gcp.bigquery` and its
+     * statements are `bigquery`, and a default here would read the wrong
+     * tables without saying so.
+     */
+    dialect: string;
+    /** Which namespace the calls reach when neither the chain nor the table name says. Defaults to "default". */
+    scope?: string;
+}
+/** A call that says which part of the store the calls after it reach, `bigquery.dataset("core")`. */
+interface RbAddressingCall extends RbArgumentPlace {
+    /** Which part of the address this call states. */
+    says: "scope" | "container";
+}
+/** A call that reads or writes rows without a statement. */
+interface RbRowCall {
+    kind: "read" | "write";
+    /**
+     * Where the call may say which container, for a library that gives
+     * the same call on the container and one level above it: BigQuery's
+     * `table.insert(rows)` and `dataset.insert("accounts", rows)`. The
+     * chain's own container is used when this argument settles on no
+     * string, which is what a row argument does.
+     */
+    container?: RbArgumentPlace;
+}
+/** Where a call writes one of its arguments. A call that takes it both ways is matched on the keyword first. */
+interface RbArgumentPlace {
+    /** The index of the positional argument. */
+    at: number;
+    /** The keyword the argument may travel under instead. */
+    keyword?: string;
+}
 /** Which methods take the primary key positionally, and what that column is called. */
+/**
+ * The methods a model registers in its own class body for the library
+ * to run when a write happens. A body that writes through the model
+ * runs them too, so their effects belong to that body.
+ *
+ * `events` is the library's own vocabulary for what a write is, and
+ * both halves of this are keyed by it: a write method says which events
+ * it runs, and a registering call says which events it covers.
+ */
+interface RbModelCallbacks {
+    /** Each write method the pattern declares, and the events it runs. */
+    eventOf: Record<string, string[]>;
+    /** Each class-body call that registers a callback, and the events it covers when the call narrows to none. */
+    registeredBy: Record<string, string[]>;
+    /** The keyword that narrows one registration to some of those events, `on`. */
+    eventKeyword: string;
+}
 interface RbPrimaryKeyLookup {
     methods: string[];
     /** The column the library uses unless a model says another. */
@@ -463,6 +557,19 @@ interface RbLoaderPattern {
     reads: string[];
     /** Receiverless calls that pick and read in one, whose arguments include the model, `dataload` and `dataload_record`. */
     shortcuts: string[];
+    /**
+     * Where `pick` takes the project's own source class, and the method
+     * the library runs on it. The read happens in that method, so what it
+     * reaches belongs to every body that loads through it.
+     */
+    source?: RbLoaderSource;
+}
+/** The source class a loader is given, and the method the library runs on it. */
+interface RbLoaderSource {
+    /** The position `pick` takes the source class at, 0 for `dataloader.with(Source, ...)`. */
+    at: number;
+    /** The method the library runs on the source, `fetch`. */
+    method: string;
 }
 type RubyDiscoveryPattern = GraphqlObjectFields | ControllerActions;
 /** 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. */
@@ -610,16 +717,31 @@ interface GraphqlObjectFields {
  * defines, and every other call is left to the reach walk. The README says
  * why ancestry.
  *
- * The class behind the receiver comes from the constant bindings for a chain
- * written from a constant and from the resolution rules otherwise. A loader
- * pattern adds calls given the model as an argument, tested the same way.
+ * The class behind the receiver comes from the constant bindings, or from the
+ * resolution rules. A loader pattern adds calls given the model, and a raw
+ * SQL pattern adds calls handed a statement, both reported through here.
  */
 
 interface RbStorageOptions {
     readonly facts: Database;
     readonly patterns: readonly RbStoragePattern[];
     readonly loaders?: readonly RbLoaderPattern[];
+    /** What a pack says about calls that take SQL the project wrote itself. */
+    readonly rawSql?: readonly RbRawSqlPattern[];
 }
+/**
+ * Whether the recognizer records this call as database work, so a walk
+ * need not report it as a gap. `enclosing` is the method the call is
+ * written in, which is what tells one body's locals from the next.
+ */
+declare function storageClaims(call: Node, file: string, options: RbStorageOptions, enclosing?: Node | null): boolean;
+/**
+ * The database work a body does, one effect per chain. A chain is one thing
+ * the code does, so `Order.where(id: 1).first` counts once. `file` is the
+ * absolute path the calls were read from, which the constant bindings key on.
+ * `enclosing` is the method the calls were read from, or null outside one.
+ */
+declare function storageEffects(calls: readonly Node[], file: string, options: RbStorageOptions, enclosing?: Node | null): Effect[];
 
 /** 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>;
@@ -985,4 +1107,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 FileFactsOptions, type GraphqlObjectFields, type GraphqlTypeNameConvention, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbBodyBlock, type RbInflections, 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, factsForFile, 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 };
+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 FileFactsOptions, type GraphqlObjectFields, type GraphqlTypeNameConvention, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbAddressingCall, type RbArgumentPlace, type RbBodyBlock, type RbInflections, type RbRawSqlPattern, type RbRowCall, type RbStatusCall, type RbStorageOptions, 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, factsForFile, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, methodDefinitionsIn, methodInAncestry, nestedStatements, nodeId, parseRuby, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, storageClaims, storageEffects, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, unitKey, walkClasses, walkDefinitions };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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, BehavioralSummary } from '@suss/behavioral-ir';
+import { TypeShape, Effect, BehavioralSummary } from '@suss/behavioral-ir';
 import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic, ExtractorOptions } from '@suss/extractor';
 import { WhyExplained } from '@suss/resolution';
 import { Value } from '@suss/values';
@@ -316,6 +316,8 @@ interface RubyPack {
     clients?: RbClientCall[];
     /** What the library's own database calls look like. The README says how one is matched. */
     storage?: RbStoragePattern[];
+    /** The calls the library gives a project for handing the store a statement it wrote itself. */
+    rawSql?: RbRawSqlPattern[];
     /** Calls the library gives a project for reading a model through a batching loader, rather than on the model itself. */
     loaders?: RbLoaderPattern[];
     /** Calls the library gives a class or module body whose block runs as part of that body. */
@@ -417,6 +419,17 @@ interface RbStoragePattern {
     reads: string[];
     /** Methods whose result is the model again: one record, or a relation a later read narrows to one. */
     givesBack: string[];
+    /**
+     * Methods on the model that take a statement the project wrote itself,
+     * and where each one takes it. The tables come from the statement, so
+     * one of these says nothing about the model's own container, and the
+     * statement is read in the dialect of `storageSystem`.
+     */
+    statements?: Record<string, RbArgumentPlace>;
+    /** The token the library writes where a bind value goes, ActiveRecord's `?`. */
+    bindPlaceholder?: string;
+    /** The methods the library runs of its own accord when a write happens, `after_commit :sync_search`. */
+    callbacks?: RbModelCallbacks;
     /** Methods that pick rows by the primary key when they are given a positional argument, and the column that is. */
     byPrimaryKey?: RbPrimaryKeyLookup;
     /** Read methods whose symbol arguments are the columns they ask for. */
@@ -426,7 +439,88 @@ interface RbStoragePattern {
     /** Which database is behind the connection, which the project settles. */
     storageSystem: "postgresql" | "mysql" | "sqlite";
 }
+/**
+ * A library whose calls take SQL the project wrote, rather than
+ * building it from a model. Ruby writes no types, so the receiver is
+ * typed by following it back to the library call that produced it: the
+ * chain starts at `constantName`, one of `clientBuilders` gives back a
+ * client, and `addressing` calls narrow that client to a part of the
+ * store before the statement or the row call arrives.
+ */
+interface RbRawSqlPattern {
+    /** The constant the library's calls start at, `PG` or `Google::Cloud::Bigquery`. */
+    constantName: string;
+    /**
+     * Base classes whose subclasses hand a client out the same way the
+     * constant does, `ActiveRecord::Base` for Rails. A project writes
+     * `Account.connection` and a bare `connection` inside the model as
+     * readily as the base class itself, and all three reach one store.
+     */
+    baseClasses?: string[];
+    /** Methods on that constant that give back a client, `connect` for the pg gem. */
+    clientBuilders: string[];
+    /** Calls that narrow a client to part of the store and give back something the rest of the calls can be made on. */
+    addressing?: Record<string, RbAddressingCall>;
+    /** Calls that take a statement, and where each one takes it. */
+    statements?: Record<string, RbArgumentPlace>;
+    /** The token the library writes where a bind value goes, when it is not the one the dialect itself reads. */
+    bindPlaceholder?: string;
+    /** Calls that read or write rows of an addressed container with no statement, `insert` on a BigQuery table. */
+    rowCalls?: Record<string, RbRowCall>;
+    /** Which store is behind the calls, in the words OpenTelemetry's semantic conventions use: `postgresql`, `gcp.bigquery`. */
+    storageSystem: string;
+    /**
+     * Which dialect the statements are written in, which is a separate
+     * answer from the store: BigQuery's store is `gcp.bigquery` and its
+     * statements are `bigquery`, and a default here would read the wrong
+     * tables without saying so.
+     */
+    dialect: string;
+    /** Which namespace the calls reach when neither the chain nor the table name says. Defaults to "default". */
+    scope?: string;
+}
+/** A call that says which part of the store the calls after it reach, `bigquery.dataset("core")`. */
+interface RbAddressingCall extends RbArgumentPlace {
+    /** Which part of the address this call states. */
+    says: "scope" | "container";
+}
+/** A call that reads or writes rows without a statement. */
+interface RbRowCall {
+    kind: "read" | "write";
+    /**
+     * Where the call may say which container, for a library that gives
+     * the same call on the container and one level above it: BigQuery's
+     * `table.insert(rows)` and `dataset.insert("accounts", rows)`. The
+     * chain's own container is used when this argument settles on no
+     * string, which is what a row argument does.
+     */
+    container?: RbArgumentPlace;
+}
+/** Where a call writes one of its arguments. A call that takes it both ways is matched on the keyword first. */
+interface RbArgumentPlace {
+    /** The index of the positional argument. */
+    at: number;
+    /** The keyword the argument may travel under instead. */
+    keyword?: string;
+}
 /** Which methods take the primary key positionally, and what that column is called. */
+/**
+ * The methods a model registers in its own class body for the library
+ * to run when a write happens. A body that writes through the model
+ * runs them too, so their effects belong to that body.
+ *
+ * `events` is the library's own vocabulary for what a write is, and
+ * both halves of this are keyed by it: a write method says which events
+ * it runs, and a registering call says which events it covers.
+ */
+interface RbModelCallbacks {
+    /** Each write method the pattern declares, and the events it runs. */
+    eventOf: Record<string, string[]>;
+    /** Each class-body call that registers a callback, and the events it covers when the call narrows to none. */
+    registeredBy: Record<string, string[]>;
+    /** The keyword that narrows one registration to some of those events, `on`. */
+    eventKeyword: string;
+}
 interface RbPrimaryKeyLookup {
     methods: string[];
     /** The column the library uses unless a model says another. */
@@ -463,6 +557,19 @@ interface RbLoaderPattern {
     reads: string[];
     /** Receiverless calls that pick and read in one, whose arguments include the model, `dataload` and `dataload_record`. */
     shortcuts: string[];
+    /**
+     * Where `pick` takes the project's own source class, and the method
+     * the library runs on it. The read happens in that method, so what it
+     * reaches belongs to every body that loads through it.
+     */
+    source?: RbLoaderSource;
+}
+/** The source class a loader is given, and the method the library runs on it. */
+interface RbLoaderSource {
+    /** The position `pick` takes the source class at, 0 for `dataloader.with(Source, ...)`. */
+    at: number;
+    /** The method the library runs on the source, `fetch`. */
+    method: string;
 }
 type RubyDiscoveryPattern = GraphqlObjectFields | ControllerActions;
 /** 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. */
@@ -610,16 +717,31 @@ interface GraphqlObjectFields {
  * defines, and every other call is left to the reach walk. The README says
  * why ancestry.
  *
- * The class behind the receiver comes from the constant bindings for a chain
- * written from a constant and from the resolution rules otherwise. A loader
- * pattern adds calls given the model as an argument, tested the same way.
+ * The class behind the receiver comes from the constant bindings, or from the
+ * resolution rules. A loader pattern adds calls given the model, and a raw
+ * SQL pattern adds calls handed a statement, both reported through here.
  */
 
 interface RbStorageOptions {
     readonly facts: Database;
     readonly patterns: readonly RbStoragePattern[];
     readonly loaders?: readonly RbLoaderPattern[];
+    /** What a pack says about calls that take SQL the project wrote itself. */
+    readonly rawSql?: readonly RbRawSqlPattern[];
 }
+/**
+ * Whether the recognizer records this call as database work, so a walk
+ * need not report it as a gap. `enclosing` is the method the call is
+ * written in, which is what tells one body's locals from the next.
+ */
+declare function storageClaims(call: Node, file: string, options: RbStorageOptions, enclosing?: Node | null): boolean;
+/**
+ * The database work a body does, one effect per chain. A chain is one thing
+ * the code does, so `Order.where(id: 1).first` counts once. `file` is the
+ * absolute path the calls were read from, which the constant bindings key on.
+ * `enclosing` is the method the calls were read from, or null outside one.
+ */
+declare function storageEffects(calls: readonly Node[], file: string, options: RbStorageOptions, enclosing?: Node | null): Effect[];
 
 /** 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>;
@@ -985,4 +1107,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 FileFactsOptions, type GraphqlObjectFields, type GraphqlTypeNameConvention, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbBodyBlock, type RbInflections, 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, factsForFile, 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 };
+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 FileFactsOptions, type GraphqlObjectFields, type GraphqlTypeNameConvention, type MethodLookup, type ParameterBindings, type ProjectNodes, type Range, type RbAddressingCall, type RbArgumentPlace, type RbBodyBlock, type RbInflections, type RbRawSqlPattern, type RbRowCall, type RbStatusCall, type RbStorageOptions, 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, factsForFile, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, methodDefinitionsIn, methodInAncestry, nestedStatements, nodeId, parseRuby, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, storageClaims, storageEffects, stringLiteralValue, stringValueOf, symbolValue, typeShapeFromNode, underscoreConstantPath, unitKey, walkClasses, walkDefinitions };