@suss/adapter-ruby 0.3.2-0

package/dist/index.d.cts

@@ -0,0 +1,256 @@
+import { Tree, Node } from 'web-tree-sitter';
+export { Node as RbNode, Tree as RbTree } from 'web-tree-sitter';
+import { RawCodeStructure } from '@suss/extractor';
+import { TypeShape, BehavioralSummary } from '@suss/behavioral-ir';
+import { Database } from '@suss/datalog';
+
+/**
+ * Finds the file behind a constant.
+ *
+ * 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.
+ */
+/** 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. */
+declare function resolveConstantFile(root: string, qualifiedName: string, convention: ConstantPathConvention): string | null;
+
+/**
+ * A new `Parser` for every call, so that parses running at the same time do
+ * not fight over one parser's mutable `language` field. The compiled `Language`
+ * is loaded once per process and shared.
+ */
+declare function parseRuby(source: string): Promise<Tree>;
+
+/**
+ * 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,
+ * 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.
+ *
+ * Ruby's own `Module.nesting` puts a newly opened class or module on the front
+ * of the chain already in effect, whether the name used to open it was bare or
+ * compound, because nesting follows the class and module keywords in the text
+ * and not the form of the name. So even when a class is opened with a compound
+ * name, as in `module Api; class Types::CampaignType; end; end`, Ruby still
+ * looks up through `Api` inside that body. That matters, because a bare
+ * reference in there is resolved by trying each level of the chain, and dropping
+ * `Api` would miss a class the file itself defines.
+ */
+
+/**
+ * Qualifies a name against the innermost level of `nesting` and no further. It
+ * returns null for a computed expression or a variable, which callers treat as
+ * unresolved. `shadowingClassFor` is the one place that walks every level.
+ */
+declare function qualifyConstantRef(node: Node, nesting: readonly string[]): string | null;
+interface ClassInfo {
+    node: Node;
+    /** Which keyword opened it. A module has no superclass and cannot be subclassed, but its methods are available to every class including it. */
+    kind: "class" | "module";
+    /** This class's own fully-qualified constant path. */
+    qualifiedName: string;
+    /** Null when it declares no superclass, or the expression is not a literal constant path. */
+    superclassQualifiedName: string | null;
+    /** `body_statement` node, or null for `class Foo; end`. */
+    bodyNode: Node | null;
+    /** `Module.nesting` in effect inside this class's own body, innermost first. */
+    bodyNesting: readonly string[];
+}
+/** Every `class` declaration reachable from `root` through direct module/class nesting, in source order. */
+declare function walkClasses(root: Node, visit: (info: ClassInfo) => void): void;
+/** The same walk including `module` declarations, for a lookup that has to reach a module's own methods. */
+declare function walkDefinitions(root: Node, visit: (info: ClassInfo) => void): void;
+/** A pack picks a derivation by name, and the code for each one lives here. */
+type GraphqlTypeNameConvention = "stripTypeSuffix";
+/** We never read a per-class name override, so this is always the name the convention derives. */
+declare function graphqlTypeNameFromQualified(qualifiedName: string, convention: GraphqlTypeNameConvention): string;
+
+/** One class or module body a walk reached, with the definitions its own file makes, since a bare constant is shadowed per file. */
+interface ReachedBody {
+    info: ClassInfo;
+    knownClasses: ReadonlySet<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 = {
+    type: "bodies";
+    name: string;
+    blocks: ReachedBody[];
+} | {
+    type: "unfollowed";
+    name: string;
+};
+/** A class and everything it inherits from, in Ruby's own method-lookup order. */
+type Ancestry = readonly AncestorEntry[];
+/** What a walk needs to reach a class it knows only by name. */
+interface AncestorLookup {
+    /** Directory the constant-to-path convention resolves an ancestor's name against. */
+    root: string;
+    pathConvention: ConstantPathConvention;
+    /**
+     * The library's own classes a project's chain ends at. Reaching one
+     * ends a walk with nothing left unfollowed.
+     */
+    ancestryRootClassNames: readonly string[];
+    parsedFile(absPath: string): Promise<Node | null>;
+}
+/**
+ * Every block a file defines under `qualifiedName`, or null when the
+ * constant-to-path convention points at no file, no file is there, or
+ * the file defines nothing by that name.
+ */
+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: "found";
+    method: Node;
+}
+/** `reason` completes "could be answered by a method ...". */
+ | {
+    type: "unsettled";
+    reason: string;
+} | {
+    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.
+ */
+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. */
+declare function inheritedStatements(ancestry: Ancestry): Array<{
+    block: ReachedBody;
+    statement: Node;
+}>;
+
+/**
+ * The Ruby adapter's own pattern-pack contract.
+ *
+ * Match shapes stay per-language until a second implementation shows what is
+ * actually shared, so this is Ruby's own and not the TypeScript or Python
+ * adapter's. Everything a library defines, meaning its call names, keywords,
+ * scalars, and conventions, arrives as pack data and is never hardcoded here.
+ */
+
+interface RubyPack {
+    name: string;
+    /** Wire protocol for the produced boundary bindings, e.g. "http-graphql". */
+    protocol: string;
+    discovery: RubyDiscoveryPattern[];
+}
+type RubyDiscoveryPattern = GraphqlObjectFields;
+/** A class whose `< ...` superclass is one of `baseClassNames` declares GraphQL fields through DSL calls in its own body. */
+interface GraphqlObjectFields {
+    type: "graphqlObjectFields";
+    /** The base class the library itself generates. A project's own intermediate base class is added through pack config. */
+    baseClassNames: string[];
+    /** 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;
+    /** 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. */
+    typeCallName: string;
+    argumentCallName: string;
+    /** Keywords whose value gives a class to read the declared contract from, one hop away. They are tried in the order listed. */
+    wiringKeywords: string[];
+    /** The method a wired class defines to resolve the field it is wired to. Library-defined. */
+    resolverMethodName: string;
+    /** The library's own classes that a project's class chain ends at. Library-defined. */
+    ancestryRootClassNames: string[];
+    /** Keyword on an argument call saying whether the argument is required. Library-defined. */
+    requiredKeyword: string;
+    /** What an argument means when it does not write the required keyword at all. */
+    requiredDefault: boolean;
+    /** The keyword that overrides `camelizeDefault` for a single name. */
+    camelizeKeyword: string;
+    /** Whether a symbol's snake_case name is exposed camelCased when the call itself does not say. */
+    camelizeDefault: boolean;
+    /** Only the names the library itself accepts in a type position belong here. */
+    scalars: Record<string, TypeShape>;
+    /** Module prefixes the same scalars can also be written under when someone spells out the full path. */
+    scalarNamePrefixes: string[];
+    typeNameConvention: GraphqlTypeNameConvention;
+}
+
+/** Parsed files by absolute path, so a class that several fields refer to is only parsed once. */
+interface FileCache {
+    get(absPath: string): Promise<Node | null>;
+}
+declare function createFileCache(parse: (source: string) => Promise<Node>, readFile: (absPath: string) => string | null): FileCache;
+interface DiscoveryOptions {
+    packs: RubyPack[];
+    /** Repo-relative or absolute path recorded on each summary's `location.file`. */
+    filePath: string;
+    cache: FileCache;
+}
+declare function discoverUnits(root: Node, options: DiscoveryOptions): Promise<RawCodeStructure[]>;
+
+/**
+ * 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
+ * alone would drop one of them.
+ */
+declare function unitKey(filePath: string, range: {
+    start: number;
+    end: number;
+}, name: string): string;
+declare function emitEntryFact(db: Database, filePath: string, range: {
+    start: number;
+    end: number;
+}, name: string): void;
+
+interface ExtractRubyOptions {
+    /** Absolute paths of the files to parse and extract. */
+    files: string[];
+    packs: RubyPack[];
+    /** When set, `location.file` on each summary is relativized against this. */
+    workspaceRoot?: string;
+}
+interface ExtractRubyResult {
+    summaries: BehavioralSummary[];
+    facts: Database;
+}
+declare function extractRubyProject(options: ExtractRubyOptions): Promise<ExtractRubyResult>;
+/** Every `.rb` file under `root`, depth-first, skipping the usual non-source directories. */
+declare function findRubyFiles(root: string): string[];
+
+/**
+ * Turns a Ruby DSL call's type argument into an IR type shape.
+ *
+ * The argument is only read when it is a literal constant, or a one-element
+ * array wrapping one. A type written as a lambda or a method call abstains
+ * rather than guessing at what it evaluates to.
+ */
+
+interface TypeReadContext {
+    /** The `Module.nesting` chain in effect, innermost first. */
+    nesting: readonly string[];
+    /** Every class the surrounding file defines, by qualified name, so we can tell when one shadows a scalar. */
+    knownClasses: ReadonlySet<string>;
+    scalars: Readonly<Record<string, TypeShape>>;
+    scalarNamePrefixes: readonly string[];
+    typeNameConvention: GraphqlTypeNameConvention;
+}
+/**
+ * Null means the field abstains. Callers must not fall back to `unknown`, which
+ * would read as a contract nobody actually declared.
+ *
+ * A bare `constant` is checked against `ctx.nesting` before the scalar table,
+ * because a project class at some level of `Module.nesting` is what Ruby itself
+ * finds first. A compound `scope_resolution` path is absolute and cannot be
+ * shadowed, so it skips that check.
+ */
+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 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 };

package/dist/index.d.ts

@@ -0,0 +1,256 @@
+import { Tree, Node } from 'web-tree-sitter';
+export { Node as RbNode, Tree as RbTree } from 'web-tree-sitter';
+import { RawCodeStructure } from '@suss/extractor';
+import { TypeShape, BehavioralSummary } from '@suss/behavioral-ir';
+import { Database } from '@suss/datalog';
+
+/**
+ * Finds the file behind a constant.
+ *
+ * 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.
+ */
+/** 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. */
+declare function resolveConstantFile(root: string, qualifiedName: string, convention: ConstantPathConvention): string | null;
+
+/**
+ * A new `Parser` for every call, so that parses running at the same time do
+ * not fight over one parser's mutable `language` field. The compiled `Language`
+ * is loaded once per process and shared.
+ */
+declare function parseRuby(source: string): Promise<Tree>;
+
+/**
+ * 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,
+ * 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.
+ *
+ * Ruby's own `Module.nesting` puts a newly opened class or module on the front
+ * of the chain already in effect, whether the name used to open it was bare or
+ * compound, because nesting follows the class and module keywords in the text
+ * and not the form of the name. So even when a class is opened with a compound
+ * name, as in `module Api; class Types::CampaignType; end; end`, Ruby still
+ * looks up through `Api` inside that body. That matters, because a bare
+ * reference in there is resolved by trying each level of the chain, and dropping
+ * `Api` would miss a class the file itself defines.
+ */
+
+/**
+ * Qualifies a name against the innermost level of `nesting` and no further. It
+ * returns null for a computed expression or a variable, which callers treat as
+ * unresolved. `shadowingClassFor` is the one place that walks every level.
+ */
+declare function qualifyConstantRef(node: Node, nesting: readonly string[]): string | null;
+interface ClassInfo {
+    node: Node;
+    /** Which keyword opened it. A module has no superclass and cannot be subclassed, but its methods are available to every class including it. */
+    kind: "class" | "module";
+    /** This class's own fully-qualified constant path. */
+    qualifiedName: string;
+    /** Null when it declares no superclass, or the expression is not a literal constant path. */
+    superclassQualifiedName: string | null;
+    /** `body_statement` node, or null for `class Foo; end`. */
+    bodyNode: Node | null;
+    /** `Module.nesting` in effect inside this class's own body, innermost first. */
+    bodyNesting: readonly string[];
+}
+/** Every `class` declaration reachable from `root` through direct module/class nesting, in source order. */
+declare function walkClasses(root: Node, visit: (info: ClassInfo) => void): void;
+/** The same walk including `module` declarations, for a lookup that has to reach a module's own methods. */
+declare function walkDefinitions(root: Node, visit: (info: ClassInfo) => void): void;
+/** A pack picks a derivation by name, and the code for each one lives here. */
+type GraphqlTypeNameConvention = "stripTypeSuffix";
+/** We never read a per-class name override, so this is always the name the convention derives. */
+declare function graphqlTypeNameFromQualified(qualifiedName: string, convention: GraphqlTypeNameConvention): string;
+
+/** One class or module body a walk reached, with the definitions its own file makes, since a bare constant is shadowed per file. */
+interface ReachedBody {
+    info: ClassInfo;
+    knownClasses: ReadonlySet<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 = {
+    type: "bodies";
+    name: string;
+    blocks: ReachedBody[];
+} | {
+    type: "unfollowed";
+    name: string;
+};
+/** A class and everything it inherits from, in Ruby's own method-lookup order. */
+type Ancestry = readonly AncestorEntry[];
+/** What a walk needs to reach a class it knows only by name. */
+interface AncestorLookup {
+    /** Directory the constant-to-path convention resolves an ancestor's name against. */
+    root: string;
+    pathConvention: ConstantPathConvention;
+    /**
+     * The library's own classes a project's chain ends at. Reaching one
+     * ends a walk with nothing left unfollowed.
+     */
+    ancestryRootClassNames: readonly string[];
+    parsedFile(absPath: string): Promise<Node | null>;
+}
+/**
+ * Every block a file defines under `qualifiedName`, or null when the
+ * constant-to-path convention points at no file, no file is there, or
+ * the file defines nothing by that name.
+ */
+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: "found";
+    method: Node;
+}
+/** `reason` completes "could be answered by a method ...". */
+ | {
+    type: "unsettled";
+    reason: string;
+} | {
+    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.
+ */
+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. */
+declare function inheritedStatements(ancestry: Ancestry): Array<{
+    block: ReachedBody;
+    statement: Node;
+}>;
+
+/**
+ * The Ruby adapter's own pattern-pack contract.
+ *
+ * Match shapes stay per-language until a second implementation shows what is
+ * actually shared, so this is Ruby's own and not the TypeScript or Python
+ * adapter's. Everything a library defines, meaning its call names, keywords,
+ * scalars, and conventions, arrives as pack data and is never hardcoded here.
+ */
+
+interface RubyPack {
+    name: string;
+    /** Wire protocol for the produced boundary bindings, e.g. "http-graphql". */
+    protocol: string;
+    discovery: RubyDiscoveryPattern[];
+}
+type RubyDiscoveryPattern = GraphqlObjectFields;
+/** A class whose `< ...` superclass is one of `baseClassNames` declares GraphQL fields through DSL calls in its own body. */
+interface GraphqlObjectFields {
+    type: "graphqlObjectFields";
+    /** The base class the library itself generates. A project's own intermediate base class is added through pack config. */
+    baseClassNames: string[];
+    /** 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;
+    /** 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. */
+    typeCallName: string;
+    argumentCallName: string;
+    /** Keywords whose value gives a class to read the declared contract from, one hop away. They are tried in the order listed. */
+    wiringKeywords: string[];
+    /** The method a wired class defines to resolve the field it is wired to. Library-defined. */
+    resolverMethodName: string;
+    /** The library's own classes that a project's class chain ends at. Library-defined. */
+    ancestryRootClassNames: string[];
+    /** Keyword on an argument call saying whether the argument is required. Library-defined. */
+    requiredKeyword: string;
+    /** What an argument means when it does not write the required keyword at all. */
+    requiredDefault: boolean;
+    /** The keyword that overrides `camelizeDefault` for a single name. */
+    camelizeKeyword: string;
+    /** Whether a symbol's snake_case name is exposed camelCased when the call itself does not say. */
+    camelizeDefault: boolean;
+    /** Only the names the library itself accepts in a type position belong here. */
+    scalars: Record<string, TypeShape>;
+    /** Module prefixes the same scalars can also be written under when someone spells out the full path. */
+    scalarNamePrefixes: string[];
+    typeNameConvention: GraphqlTypeNameConvention;
+}
+
+/** Parsed files by absolute path, so a class that several fields refer to is only parsed once. */
+interface FileCache {
+    get(absPath: string): Promise<Node | null>;
+}
+declare function createFileCache(parse: (source: string) => Promise<Node>, readFile: (absPath: string) => string | null): FileCache;
+interface DiscoveryOptions {
+    packs: RubyPack[];
+    /** Repo-relative or absolute path recorded on each summary's `location.file`. */
+    filePath: string;
+    cache: FileCache;
+}
+declare function discoverUnits(root: Node, options: DiscoveryOptions): Promise<RawCodeStructure[]>;
+
+/**
+ * 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
+ * alone would drop one of them.
+ */
+declare function unitKey(filePath: string, range: {
+    start: number;
+    end: number;
+}, name: string): string;
+declare function emitEntryFact(db: Database, filePath: string, range: {
+    start: number;
+    end: number;
+}, name: string): void;
+
+interface ExtractRubyOptions {
+    /** Absolute paths of the files to parse and extract. */
+    files: string[];
+    packs: RubyPack[];
+    /** When set, `location.file` on each summary is relativized against this. */
+    workspaceRoot?: string;
+}
+interface ExtractRubyResult {
+    summaries: BehavioralSummary[];
+    facts: Database;
+}
+declare function extractRubyProject(options: ExtractRubyOptions): Promise<ExtractRubyResult>;
+/** Every `.rb` file under `root`, depth-first, skipping the usual non-source directories. */
+declare function findRubyFiles(root: string): string[];
+
+/**
+ * Turns a Ruby DSL call's type argument into an IR type shape.
+ *
+ * The argument is only read when it is a literal constant, or a one-element
+ * array wrapping one. A type written as a lambda or a method call abstains
+ * rather than guessing at what it evaluates to.
+ */
+
+interface TypeReadContext {
+    /** The `Module.nesting` chain in effect, innermost first. */
+    nesting: readonly string[];
+    /** Every class the surrounding file defines, by qualified name, so we can tell when one shadows a scalar. */
+    knownClasses: ReadonlySet<string>;
+    scalars: Readonly<Record<string, TypeShape>>;
+    scalarNamePrefixes: readonly string[];
+    typeNameConvention: GraphqlTypeNameConvention;
+}
+/**
+ * Null means the field abstains. Callers must not fall back to `unknown`, which
+ * would read as a contract nobody actually declared.
+ *
+ * A bare `constant` is checked against `ctx.nesting` before the scalar table,
+ * because a project class at some level of `Module.nesting` is what Ruby itself
+ * finds first. A compound `scope_resolution` path is absolute and cannot be
+ * shadowed, so it skips that check.
+ */
+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 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 };