clast-ai 0.1.2 → 0.2.0

package/dist/query/resolve.d.ts

@@ -0,0 +1,265 @@
+import type { ClastDb } from '../db/index.js';
+import { type SymbolKind, type SymbolRow } from '../types.js';
+export declare function langFamily(lang: string): string;
+export declare const KIND_WEIGHT: Record<SymbolKind, number>;
+export interface SymbolRef {
+    name: string;
+    /** Container segments before the name (`Foo.Bar.baz` -> [Foo, Bar]). */
+    container: string[];
+    path?: string;
+    line?: number;
+}
+/**
+ * Parse the ways an agent may refer to a symbol:
+ * `name`, `Class.method`, `Class::method`, `Class#method`,
+ * `path/file.ts:name`, `path/file.ts:123` (symbol at line).
+ */
+export declare function parseSymbolRef(ref: string): SymbolRef;
+export declare function pathMatches(path: string, filter: string): boolean;
+/** Static desirability of a symbol as "the" definition of its name. */
+export declare function definitionScore(s: SymbolRow): number;
+/**
+ * Resolve a symbol reference to definitions, best first. Falls back to
+ * case-insensitive matching when nothing matches exactly.
+ */
+export declare function findSymbols(db: ClastDb, ref: string | SymbolRef, opts?: {
+    path?: string;
+    kind?: string;
+    exact?: boolean;
+}): SymbolRow[];
+/** Drop overloads / re-declarations of `chosen` (same qualified name in the same file). */
+export declare function otherDefinitions(chosen: SymbolRow, all: SymbolRow[], family?: Set<number>): {
+    others: SymbolRow[];
+    overloads: number;
+};
+/** Names of all supertypes (transitive, bounded) of the containers called `name`. */
+export declare function ancestorNames(db: ClastDb, name: string): Set<string>;
+export interface FileHit {
+    id: number;
+    path: string;
+    lang: string;
+    line_count: number;
+    symbol_count: number;
+}
+/** Resolve a (possibly partial) file path: exact, suffix, then substring. */
+export declare function findFiles(db: ClastDb, query: string, limit?: number): FileHit[];
+export interface CallSite {
+    fileId: number;
+    path: string;
+    lang: string;
+    /** Receiver text, COMPLEX ('?') for expression receivers, null for bare calls. */
+    receiver: string | null;
+    /** Declared type of the receiver, when the extractor could determine it. */
+    rtype?: string | null;
+    /**
+     * Row id of the call that produces this call's receiver (`a.b().c()`:
+     * for c, the call to b). The receiver type is then b's return type.
+     */
+    via?: number | null;
+    /** Symbol the call is made from, if known. */
+    caller?: SymbolRow | null;
+    /** Go: directory of the package the receiver type is qualified with (set by the resolver). */
+    rtypeDir?: string;
+    /** Number of arguments at the call site (-1 / undefined = unknown). */
+    argc?: number | null;
+}
+export interface Resolution {
+    /** Candidates, best first, with scores. */
+    candidates: Array<{
+        sym: SymbolRow;
+        score: number;
+    }>;
+    /** True when the best candidate is clearly better than the rest. */
+    confident: boolean;
+}
+/** A C / C++ function with internal linkage: visible only in its own translation unit. */
+export declare function isFileLocal(s: SymbolRow): boolean;
+/**
+ * C / C++: a prototype and its definition (or two declarations of one function) are one target.
+ * Two full definitions in different source files are different functions, as is anything `static`.
+ */
+export declare function cTwins(a: SymbolRow, b: SymbolRow): boolean;
+/**
+ * Resolves call sites to definitions. Holds per-request caches (imports of a
+ * file, candidate definitions of a name, class ancestry); create a new
+ * instance whenever the index changes.
+ */
+export declare class Resolver {
+    private readonly db;
+    private goPackages;
+    private goImportCache;
+    /** Go: project directory an import path names, or null when it is outside the project. */
+    private goPackageDir;
+    /** Go: package names a file imports -> project directory (null = external package). */
+    private goImports;
+    /**
+     * Go: a receiver type written `pkg.Type`. Returns the site with the bare type name and
+     * the package directory, or null when the package is not part of this project.
+     */
+    private goQualified;
+    private importCache;
+    private importNameCache;
+    private candidateCache;
+    private ancestorCache;
+    private rubyAncestorCache;
+    private relatedCache;
+    private familyCache;
+    private familyCountCache;
+    private parentCache;
+    private mentionCache;
+    private projectTypeCache;
+    constructor(db: ClastDb);
+    /** File ids imported (directly) by a file. */
+    importsOf(fileId: number): Set<number>;
+    /**
+     * True when the name `type`, as seen from the calling file, is a class defined in that file or in
+     * the file it is imported from, and `cand` is a member of a same-named class somewhere else.
+     */
+    private otherTypeInScope;
+    private arityCache;
+    /**
+     * Can a call with the site's argument count be a call of `sym`? True when either side is
+     * unknown. Tells overloads apart and rejects same-named methods with another shape.
+     */
+    arityFits(sym: SymbolRow, site: CallSite): boolean;
+    private filePathCache;
+    private filePath;
+    private instanceTypeCache;
+    /**
+     * Type of a module-level variable `name` defined in file `fileId`, read from its declaration:
+     * `pre_save = ModelSignal(...)`, `export const logger = new Logger()`, `export const x: Foo = ...`.
+     */
+    private instanceType;
+    /** Go: does the file import the package in directory `dir`? */
+    private importsGoDir;
+    /** Names a file imports, mapped to the file they come from (null = not in this project). */
+    private importedNames;
+    private defaultExportCache;
+    /** Name of the symbol a file exports as its default / `module.exports`, if any. */
+    private defaultExportOf;
+    /** Can code in `fileId` plausibly refer to `target`: same file, imports its file, or names its class? */
+    canSee(fileId: number, target: SymbolRow): boolean;
+    /**
+     * A call at `rawSite` was bound to `bound`, a declaration of the same member on a supertype of
+     * `target`'s class. Can it run `target`? Not when the receiver is statically a class unrelated to
+     * the target's (a sibling subclass), and not for `super.m()`, which names one implementation.
+     */
+    reaches(target: SymbolRow, bound: SymbolRow, rawSite: CallSite): boolean;
+    private aliasUseCache;
+    /**
+     * Local names under which other files refer to `sym`: import aliases
+     * (`import { X as Y }`) and default-import / require bindings of a file
+     * whose default export is `sym`.
+     */
+    aliasesOf(sym: SymbolRow): Array<{
+        fileId: number;
+        alias: string;
+    }>;
+    candidates(name: string): SymbolRow[];
+    private parentOf;
+    /** Nearest enclosing class-like symbol of `sym` (lexical), or its container by qualified name. */
+    private enclosingContainer;
+    private findEnclosingContainer;
+    private stdNameCache;
+    /** Rust: names a file imports from the standard library (`use std::task::{Context, Wake}`). */
+    private stdNames;
+    /**
+     * A supertype written in file `fileId` that cannot be a project type even though the project
+     * defines one of that name: a Go type of an external package (`io.Closer`), a Rust trait the
+     * file imports from the standard library (`use std::task::Wake`).
+     */
+    externalSupertype(name: string, qualifier: string | null, fileId: number, lang: string): boolean;
+    /**
+     * Ruby constants are looked up lexically: `Base` written inside `Rails::Generators::NamedBase` is
+     * `Rails::Generators::Base`, never `ActiveRecord::Base`, and `Thor::Group` is not some other
+     * `Group`. Returns every part of the (possibly reopened) class or module, or nothing when no
+     * enclosing scope defines it (a gem).
+     */
+    private rubyConstant;
+    /**
+     * Qualified names of the Ruby ancestors (superclasses and mixins) of a class or module, found
+     * by lexical constant lookup. All parts of a reopened class contribute their own heritage.
+     */
+    rubyAncestors(containerId: number): Set<string>;
+    /** Names of the classes a container extends/implements, transitively (bounded). */
+    ancestorsOf(containerId: number): Set<string>;
+    /** Ancestor and descendant type names of every container called `name`. */
+    relatedTo(name: string): {
+        anc: Set<string>;
+        desc: Set<string>;
+    };
+    private containerName;
+    /** Does the file's code mention this identifier at all? */
+    private fileMentions;
+    /** Is `name` a class-like type defined in this project? */
+    private isProjectType;
+    /**
+     * Symbols that are "the same target" as `sym` for call-graph purposes:
+     * overloads (same qualified name in the same file), C/C++ prototypes and
+     * their definitions, and same-named methods in containers related by
+     * inheritance (interface method <-> implementation, base <-> override).
+     * A call resolved to any member counts for all.
+     */
+    familyOf(sym: SymbolRow): Set<number>;
+    /**
+     * True when `other` overrides `target` in a subtype and `target` has a body of its own:
+     * a call bound to the override never runs `target` (the reverse is not true: a call bound
+     * to the base method may dispatch to the override).
+     */
+    overriddenBelow(target: SymbolRow, other: SymbolRow): boolean;
+    /** How many genuinely different definitions (families) share this name. */
+    private familyCount;
+    /**
+     * Evidence that a member call on a receiver of unknown type targets `cand`
+     * (a method of `container`). Zero evidence means "not linked".
+     */
+    private memberEvidence;
+    private receiverOtherCache;
+    /** Does the receiver's name match the class of a different definition of `name`? */
+    private receiverNamesOther;
+    /** Score how plausible it is that a call at `site` targets `cand`; null = impossible. */
+    private score;
+    /**
+     * Small bonus for the definition of type `typeName` that the calling file
+     * can actually see (same file, imported by name, or nearest in the tree).
+     * Decides between identical copies of a class (vendored forks, monorepo
+     * packages).
+     */
+    private typeVisibility;
+    private fieldTypeCache;
+    /** Declared type of `container.field` (also looking at supertypes), or null if unknown / ambiguous. */
+    private fieldType;
+    /**
+     * Fill in the receiver type from class field declarations when the
+     * extractor could not (the class is declared in another file: C++ headers,
+     * partial classes, Go structs elsewhere in the package).
+     */
+    private withFieldType;
+    private nameIndexCache;
+    private tieCache;
+    private containerCache;
+    /** Candidates of a name grouped for fast pre-selection (only built for crowded names). */
+    private nameIndex;
+    /**
+     * Candidates that can possibly score for this call site. Purely an
+     * optimisation for names with hundreds of definitions (`run`, `add`,
+     * `get`): it must return a superset of what score() accepts.
+     */
+    private preselect;
+    /**
+     * True when a member call's receiver gives no usable type information: an
+     * expression (`a.b().foo()`) or an untyped variable that is neither
+     * this/self, a runtime global, nor an external module. Such call sites
+     * cannot be attributed to any one definition of a common method name.
+     */
+    isOpaqueReceiver(rawSite: CallSite): boolean;
+    private chainTypeCache;
+    /**
+     * Type of an expression receiver that is itself a call: the return type of
+     * that call's target (or the class, for constructor calls). Follows up to
+     * four links of a chain.
+     */
+    private chainType;
+    /** Rank the definitions a call to `name` at `site` may refer to. */
+    resolve(name: string, rawSite: CallSite, depth?: number, typesOnly?: boolean): Resolution;
+}