@suss/adapter-ruby 0.21.0 → 0.22.0

package/dist/index.d.ts

@@ -2,7 +2,8 @@ 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 } from '@suss/extractor';
+import { RawCodeStructure, TimingReport, ExtractionReport, CacheDiagnostic } from '@suss/extractor';
+import { WhyExplained } from '@suss/resolution';
 
 /**
  * A new `Parser` for every call, so that parses running at the same time do
@@ -10,9 +11,51 @@ import { RawCodeStructure } from '@suss/extractor';
  * is loaded once per process and shared.
  */
 declare function parseRuby(source: string): Promise<Tree>;
+/**
+ * Load the grammar ahead of time, for a caller whose own entry point is
+ * async but whose parsing happens later through `parseRubySync`. Loading
+ * the WASM grammar is the only async part; parsing a tree from it is not.
+ */
+declare function preloadRubyGrammar(): Promise<void>;
+/**
+ * `parseRuby` without the await, for a caller that cannot itself be
+ * async. Throws if `preloadRubyGrammar` (or `parseRuby`) has not already
+ * loaded the grammar in this process.
+ */
+declare function parseRubySync(source: string): Tree;
 
+interface Range {
+    start: number;
+    end: number;
+}
+declare function field(node: Node, name: string): Node | null;
+declare function bodyStatements(body: Node): Node[];
 /** A call whose block is the thing being configured rather than a place statements run. */
 type BlockConfigures = (call: Node) => boolean;
+/**
+ * Every statement a body runs, in source order. Ruby runs a class body
+ * like any other code, so a declaration can sit inside an `if`, a
+ * `.each` block, a `begin` or a `class_eval`, and taking the body's own
+ * child list finds the first spelling and loses the rest in silence.
+ *
+ * `blockConfigures` says which calls keep their block to themselves.
+ * `field :x, String do argument :q, String end` declares an argument on
+ * the field, not on the class, so that block is not part of the body.
+ */
+declare function runStatements(body: Node, blockConfigures?: BlockConfigures): Node[];
+/** The text inside a plain string node, with the quotes removed. A string with interpolation returns null. */
+declare function stringLiteralValue(node: Node): string | null;
+/** tree-sitter-ruby leaves the leading colon in a `simple_symbol`'s text, but not in a `hash_key_symbol`'s. */
+declare function symbolValue(node: Node): string | null;
+/** A `pair` node's key, when it is written as the bare `key:` shorthand. Null for a pair keyed by a string or an expression. */
+declare function hashKeySymbolName(node: Node): string | null;
+declare function booleanLiteralValue(node: Node): boolean | null;
+/** Keyword arguments turn up as `pair` nodes directly among the argument list's children, rather than wrapped in a hash node. */
+interface CallArgs {
+    positional: Node[];
+    keyword: Record<string, Node>;
+}
+declare function readCallArgs(argumentList: Node | null): CallArgs;
 
 /**
  * Finds the file behind a constant.
@@ -81,6 +124,8 @@ declare function graphqlTypeNameFromQualified(qualifiedName: string, convention:
 interface ReachedBody {
     info: ClassInfo;
     knownClasses: ReadonlySet<string>;
+    /** 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. */
 type AncestorEntry = {
@@ -119,21 +164,30 @@ interface AncestorLookup {
 declare function reachDefinition(qualifiedName: string, lookup: AncestorLookup): Promise<ReachedBody[] | null>;
 declare function ancestryOf(name: string, blocks: readonly ReachedBody[], lookup: AncestorLookup): Promise<Ancestry>;
 /** What searching an ancestry for one method name came to. */
-type MethodLookup = {
+type MethodLookup = 
+/** `block` is which ancestor's own body the method is written in, so a caller that needs its file can get there. */
+{
     type: "found";
     method: Node;
+    block: ReachedBody;
 }
-/** `reason` completes "could be answered by a method ...". */
+/**
+ * `reason` completes "could be answered by a method ...".
+ * `cause` says why the search stopped, since a caller deciding
+ * whether to look further needs more than the sentence: `unreadAncestor`
+ * is a base whose file this run could not open, and `dynamicDefine`
+ * is a body that calls `define_method`.
+ */
  | {
     type: "unsettled";
     reason: string;
+    cause: "unreadAncestor" | "dynamicDefine";
 } | {
     type: "none";
 };
 /**
- * The method `name` resolves to. An ancestor nearer than any definition
- * that nothing could read stops the search: whatever sits further along
- * is not what Ruby would have called.
+ * The method `name` resolves to. An unread ancestor nearer than any
+ * definition stops the search, since Ruby would have called that one first.
  */
 declare function methodInAncestry(ancestry: Ancestry, name: string): MethodLookup;
 /** Every statement of every body reached, most distant ancestor first, so a nearer declaration overwrites what it inherits. */
@@ -153,6 +207,22 @@ declare function inheritedStatements(ancestry: Ancestry, blockConfigures?: Block
 
 interface RubyPack {
     name: string;
+    /**
+     * Pack version stamp, which feeds the cache invalidation key. Bump on
+     * any change that affects discovered units or extracted summaries.
+     * The CLI folds a hash of the loaded pack file and its config into
+     * this stamp on top, so a pack run through the CLI invalidates on an
+     * edit whether or not it declares a version of its own.
+     */
+    version?: string;
+    /**
+     * Files under the project this pack reads that are not among the
+     * `.rb` files a run walks, given the files the run is about to walk.
+     * Their content feeds the same cache key the pack's own config does,
+     * so an edit to one of them re-extracts instead of handing back the
+     * previous answer.
+     */
+    discoveryInputs?: (files: readonly string[]) => string[];
     /** Wire protocol for the produced boundary bindings, e.g. "http-graphql". */
     protocol: string;
     discovery: RubyDiscoveryPattern[];
@@ -172,7 +242,29 @@ interface RbStoragePattern {
     /** Which database is behind the connection, which the project settles. */
     storageSystem: "postgresql" | "mysql" | "sqlite";
 }
-type RubyDiscoveryPattern = GraphqlObjectFields;
+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. */
+interface ControllerActions {
+    type: "controllerActions";
+    /** The library's own base a project's controllers extend, `ActionController::Base` say. */
+    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. */
+    ancestryRootClassNames: string[];
+    /** Status code a wire response gets when the action does not say otherwise. */
+    defaultStatusCode: number;
+    /** Absolute path of the file this pattern's own routing came from, for the one gap `routingGaps` may report. */
+    routesFile: string;
+    /** The method and path a project's own routing gives one controller's action, or null when that action has none. */
+    routeFor: (controllerQualifiedName: string, actionName: string) => {
+        method: string;
+        path: string;
+    } | 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[];
+}
 /** A class or module whose ancestry reaches one of `baseClassNames` declares GraphQL fields through DSL calls in its own body. */
 interface GraphqlObjectFields {
     type: "graphqlObjectFields";
@@ -238,12 +330,142 @@ interface DiscoveryOptions {
     packs: RubyPack[];
     /** Repo-relative or absolute path recorded on each summary's `location.file`. */
     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;
     cache: FileCache;
     /** What a pack needs to say a call talks to the database. Absent when no pack does. */
     storage?: RbStorageOptions | undefined;
+    /** 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;
+}
+/** The method behind a discovered unit's own body, and where it lives, so the reach walk can start there the way it starts at a `def` it found directly. */
+interface ReachSeed {
+    readonly file: string;
+    readonly node: Node;
+    /** The class the method is written in, or null for one written outside any class. */
+    readonly enclosingQualifiedName: string | null;
 }
 declare function discoverUnits(root: Node, options: DiscoveryOptions): Promise<RawCodeStructure[]>;
 
+/** A definition every file in the run can see, under the name it is written as. */
+interface ConstantDefinition {
+    readonly qualifiedName: string;
+    readonly key: string;
+}
+/** A constant read somewhere, with the nesting it was read inside. */
+interface ConstantReference {
+    readonly key: string;
+    /** The name as written, `Order` or `Types::Order`. */
+    readonly written: string;
+    /** The enclosing module and class names, outermost first. */
+    readonly nesting: readonly string[];
+}
+interface FileConstants {
+    readonly filePath: string;
+    readonly definitions: readonly ConstantDefinition[];
+    readonly references: readonly ConstantReference[];
+}
+/**
+ * Every constant this file defines and every one it reads. One walk, because
+ * the nesting a reference is written inside is what the walk already knows.
+ */
+declare function collectFileConstants(filePath: string, root: Node): FileConstants;
+/**
+ * Link every constant read anywhere in the run to the definition behind it,
+ * looking outwards from the nesting it was read inside the way Ruby does.
+ *
+ * `binds(refKey, defKey)` is the link itself. `rbConstantFrom(from, to)`
+ * is the same link at file level, which is the closest thing to an
+ * import graph a language without imports has.
+ */
+declare function emitConstantBindings(db: Database, perFile: Iterable<FileConstants>): void;
+
+/**
+ * A node's identity across the whole run. The end is part of it because a
+ * call and its receiver start at the same offset.
+ */
+declare function nodeId(filePath: string, node: Node): string;
+/**
+ * The key a read of this expression joins on, for a caller that has an
+ * 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;
+/**
+ * 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.
+ */
+declare function emitValueFacts(db: Database, filePath: string, root: Node): void;
+
+/**
+ * The session behind `suss ask why` on a Ruby project: a tree-sitter
+ * parse of the asked-about source, a way to point at the expression
+ * somebody spelled, and the witness proof of what it resolved to,
+ * rendered through `@suss/resolution`'s phrases.
+ *
+ * It parses every file under the root and emits the same value and
+ * constant facts `extractRubyProject` does, keeping a location for
+ * every fact key so a proof's atoms can point back at source. A
+ * handle this session hands back pairs a tree-sitter node with the
+ * file it came from, since a node alone does not say which file
+ * parsed it.
+ */
+
+interface RubyWhySessionOptions {
+    /** The project root, which paths in every answer come out relative to. */
+    dir: string;
+}
+/** A found node, paired with the file it was parsed from. */
+interface RubyValueHandle {
+    file: string;
+    node: Node;
+}
+declare class RubyWhySession {
+    private readonly root;
+    private readonly db;
+    private readonly locations;
+    private readonly trees;
+    constructor(options: RubyWhySessionOptions);
+    /**
+     * The smallest expression on `line` of `file` whose text is exactly
+     * `text`, or null.
+     */
+    findExpression(file: string, line: number, text: string): RubyValueHandle | null;
+    /**
+     * The callee of the call written as `calleeText` between `startLine`
+     * and `endLine` of `file`, or null.
+     */
+    findCallee(file: string, startLine: number, endLine: number, calleeText: string): RubyValueHandle | null;
+    /**
+     * Why `value` resolves to what it does: the witness proof, flattened
+     * to the chain and rendered. Null when the value does not resolve,
+     * which the caller says in its own words.
+     */
+    explain(value: RubyValueHandle, options?: {
+        maxDepth?: number;
+    }): WhyExplained | null;
+    private locate;
+    private rootOf;
+    private pathOf;
+    /** A file path said relative to the root, or as given when it is outside the root. */
+    private displayPath;
+}
+
+/**
+ * facts.ts: what discovery hands to the shared fact store.
+ *
+ * This is the Layer 1 contract: discover units, emit summaries, emit
+ * these facts.
+ *
+ * `entry` reuses the existing relation name and shape, where the unit
+ * is a pack-discovered entry point, so a Ruby-discovered field is an
+ * entry the same way a Python route or a TypeScript handler is.
+ *
+ * `rbRequires(from, to)` records a `require_relative` whose target is a
+ * file in the run. A plain `require` goes through the load path, which
+ * this run does not know, so it records nothing.
+ */
+
 /**
  * The name is part of the key because the range is measured in lines, two
  * units can start on the same line, and `entry` is a set, so keying on the range
@@ -264,6 +486,16 @@ interface ExtractRubyOptions {
     packs: RubyPack[];
     /** When set, `location.file` on each summary is relativized against this. */
     workspaceRoot?: string;
+    /** The directory a summary's id measures its file from, when that differs from `workspaceRoot`. */
+    projectRoot?: string;
+    /** Called once with the run's per-phase wall time, for `suss extract --timing`. */
+    onTiming?: (report: TimingReport) => void;
+    /** Called once with the file-by-file funnel, for `suss extract --explain`. */
+    onExtractionReport?: (report: ExtractionReport) => void;
+    /** Called once with what the cache decided, for `suss extract --timing`. */
+    onCacheDiagnostic?: (diagnostic: CacheDiagnostic) => void;
+    /** Absolute. `<projectRoot>/.suss/cache` by default; `null` turns it off. */
+    cacheDir?: string | null;
 }
 interface ExtractRubyResult {
     summaries: BehavioralSummary[];
@@ -273,6 +505,36 @@ declare function extractRubyProject(options: ExtractRubyOptions): Promise<Extrac
 /** Every `.rb` file under `root`, depth-first, skipping the usual non-source directories. */
 declare function findRubyFiles(root: string): string[];
 
+/**
+ * Evidence for drafting a graphql-ruby `extends-base` dependency stub:
+ * every `require`/`require_relative` of the asked package, and every
+ * project class whose superclass is spelled from it. Discovery
+ * only recognizes a class through `baseClassNames`' literal names (see
+ * discovery.ts's `reachesConfiguredBase`), so a project's own base
+ * under a renamed namespace, or one that extends the library's own
+ * class directly, has to state the exact name.
+ */
+interface RubyRequireSite {
+    target: string;
+    file: string;
+    line: number;
+}
+interface RubyExtendsSite {
+    className: string;
+    superclassName: string;
+    file: string;
+    line: number;
+}
+interface RubyStubEvidence {
+    requires: RubyRequireSite[];
+    extendsSites: RubyExtendsSite[];
+}
+interface RubyStubEvidenceOptions {
+    packageName: string;
+    directory: string;
+}
+declare function rubyStubEvidence(options: RubyStubEvidenceOptions): Promise<RubyStubEvidence>;
+
 /**
  * Turns a Ruby DSL call's type argument into an IR type shape.
  *
@@ -301,4 +563,14 @@ interface TypeReadContext {
  */
 declare function typeShapeFromNode(node: Node, ctx: TypeReadContext): TypeShape | null;
 
-export { type AncestorEntry, type AncestorLookup, type Ancestry, type ClassInfo, type ConstantPathConvention, type DiscoveryOptions, type ExtractRubyOptions, type ExtractRubyResult, type FileCache, type GraphqlObjectFields, type GraphqlTypeNameConvention, type MethodLookup, type RbStoragePattern, type ReachedBody, type RubyDiscoveryPattern, type RubyPack, type TypeReadContext, ancestryOf, createFileCache, discoverUnits, emitEntryFact, extractRubyProject, findRubyFiles, graphqlTypeNameFromQualified, inheritedStatements, methodInAncestry, parseRuby, qualifyConstantRef, reachDefinition, resolveConstantFile, typeShapeFromNode, underscoreConstantPath, unitKey, walkClasses, walkDefinitions };
+/**
+ * version.ts: this adapter's own half of the cache key.
+ *
+ * `ADAPTER_VERSION` is the hand-bumped semver. Bump it on any change
+ * that affects extraction output: IR shape, discovery semantics,
+ * terminal classification, anything that would invalidate previously
+ * cached summaries.
+ */
+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 ExtractRubyOptions, type ExtractRubyResult, type FileCache, type FileConstants, type GraphqlObjectFields, type GraphqlTypeNameConvention, type MethodLookup, type Range, type RbStoragePattern, type ReachedBody, type RubyDiscoveryPattern, type RubyExtendsSite, type RubyPack, type RubyRequireSite, type RubyStubEvidence, type RubyStubEvidenceOptions, type RubyValueHandle, RubyWhySession, type RubyWhySessionOptions, type TypeReadContext, ancestryOf, bodyStatements, booleanLiteralValue, collectFileConstants, createFileCache, discoverUnits, emitConstantBindings, emitEntryFact, emitValueFacts, extractRubyProject, field, findRubyFiles, graphqlTypeNameFromQualified, hashKeySymbolName, inheritedStatements, methodInAncestry, nodeId, parseRuby, parseRubySync, preloadRubyGrammar, qualifyConstantRef, reachDefinition, readCallArgs, readKey, resolveConstantFile, rubyStubEvidence, runStatements, stringLiteralValue, symbolValue, typeShapeFromNode, underscoreConstantPath, unitKey, walkClasses, walkDefinitions };