@optave/codegraph 3.13.0 → 3.15.0

package/src/shared/paginate.ts

@@ -5,23 +5,9 @@
  * change between pages; offset/limit is simpler and maps directly to SQL.
  */
 
-export interface PaginationMeta {
-  total: number;
-  offset: number;
-  limit: number;
-  hasMore: boolean;
-  returned: number;
-}
-
-export interface PaginatedResult<T> {
-  items: T[];
-  pagination?: PaginationMeta;
-}
+import type { PaginatedItems, PaginationMeta, PaginationOpts } from '../types.js';
 
-export interface PaginateOpts {
-  limit?: number;
-  offset?: number;
-}
+export type { PaginatedItems as PaginatedResult, PaginationMeta, PaginationOpts as PaginateOpts };
 
 /** Default limits applied by MCP tool handlers (not by the programmatic API). */
 export const MCP_DEFAULTS: Record<string, number> = {
@@ -65,7 +51,7 @@ export const MCP_MAX_LIMIT = 1000;
  *
  * When `limit` is undefined the input is returned unchanged (no-op).
  */
-export function paginate<T>(items: T[], { limit, offset }: PaginateOpts = {}): PaginatedResult<T> {
+export function paginate<T>(items: T[], { limit, offset }: PaginationOpts = {}): PaginatedItems<T> {
   if (limit === undefined) {
     return { items };
   }
@@ -94,7 +80,7 @@ export function paginate<T>(items: T[], { limit, offset }: PaginateOpts = {}): P
 export function paginateResult<T extends Record<string, unknown>>(
   result: T,
   field: string,
-  { limit, offset }: PaginateOpts = {},
+  { limit, offset }: PaginationOpts = {},
 ): T & { _pagination?: PaginationMeta } {
   if (limit === undefined) {
     return result;

package/src/types.ts

@@ -52,7 +52,13 @@ export type CoreEdgeKind =
 export type StructuralEdgeKind = 'parameter_of' | 'receiver';
 
 /** Dataflow-specific edge kinds. */
-export type DataflowEdgeKind = 'flows_to' | 'returns' | 'mutates';
+export type DataflowEdgeKind =
+  | 'flows_to'
+  | 'returns'
+  | 'mutates'
+  | 'def_use'
+  | 'arg_in'
+  | 'return_out';
 
 /** All edge kinds that can appear in the graph. */
 export type EdgeKind = CoreEdgeKind | StructuralEdgeKind;
@@ -180,6 +186,7 @@ export interface EdgeRow {
   kind: EdgeKind;
   confidence: number | null;
   dynamic: 0 | 1;
+  dynamic_kind?: string | null;
 }
 
 /** Callee/caller node shape (from findCallees / findCallers). */
@@ -469,12 +476,27 @@ export interface LOCMetrics {
   commentLines: number;
 }
 
+/**
+ * Taxonomy for dynamic/computed call sites — distinguishes resolvable kinds
+ * (computed-literal, reflection) from flag-only kinds (eval, computed-key,
+ * unresolved-dynamic) that cannot be resolved statically.
+ */
+export type DynamicKind =
+  | 'computed-literal' // obj["foo"]()    — resolvable; already emitted as normal edge
+  | 'computed-key' // obj[k]()        — potentially resolvable via pts; else flagged
+  | 'reflection' // .call/.apply/.bind / Reflect.* / callable-ref — resolved when target is in codebase; sink edge emitted if unresolved
+  | 'eval' // eval() / new Function() — undecidable; always flagged
+  | 'unresolved-dynamic'; // any other detected dynamic pattern; flagged
+
 /** A function/method call detected by an extractor. */
 export interface Call {
   name: string;
   line: number;
   receiver?: string;
   dynamic?: boolean;
+  dynamicKind?: DynamicKind;
+  /** Raw key/arg text — used for diagnostics and future RES-1 const-string resolution. */
+  keyExpr?: string;
 }
 
 /** An import statement detected by an extractor. */
@@ -707,6 +729,14 @@ export interface ExtractorOutput {
    * `definePropertyReceivers.set("getter", "obj")`.
    */
   definePropertyReceivers?: Map<string, string>;
+  /**
+   * CJS require bindings from `const { X, Y } = require('./path')` patterns.
+   * Used by buildImportedNamesMap to classify X and Y as import artifacts so
+   * receiver-edge resolution falls back to the global class lookup rather than
+   * treating the destructured-binding function node as a local definition (#1661).
+   * Does NOT cause DB import edges — use `imports` for that.
+   */
+  cjsRequireBindings?: Array<{ names: string[]; source: string }>;
   /** WASM tree retained for downstream analysis (complexity, CFG, dataflow). */
   _tree?: TreeSitterTree;
   /** Language identifier. */
@@ -954,10 +984,14 @@ export interface CfgRulesConfig {
 export interface DataflowRulesConfig {
   functionNodes: Set<string>;
   nameField: string;
+  /** Override for languages with nested function name structures (e.g. C/C++). */
+  nameExtractor: ((node: TreeSitterNode) => string | null) | null;
   varAssignedFnParent: string | null;
   assignmentFnParent: string | null;
   pairFnParent: string | null;
   paramListField: string;
+  /** Override for languages where the param list is nested (e.g. C: function_definition → declarator → parameters). */
+  getParamListNode: ((funcNode: TreeSitterNode) => TreeSitterNode | null) | null;
   paramIdentifier: string;
   paramWrapperTypes: Set<string>;
   defaultParamType: string | null;
@@ -1018,6 +1052,20 @@ export interface CfgEdge {
   label?: string;
 }
 
+/**
+ * A dataflow vertex: an addressable data location within a function.
+ * Populated during extraction (P1+); persisted to `dataflow_vertices`.
+ */
+export interface DataflowVertex {
+  /** Name of the enclosing function (used to resolve func_id at insert time). */
+  funcName: string;
+  /** Vertex kind: 'param' | 'local' | 'return' | 'receiver'. */
+  kind: 'param' | 'local' | 'return' | 'receiver';
+  name?: string;
+  paramIndex?: number;
+  line?: number;
+}
+
 /** Dataflow extraction result. */
 export interface DataflowResult {
   parameters: DataflowParam[];
@@ -1311,6 +1359,8 @@ export interface CodegraphConfig {
   include: string[];
   exclude: string[];
   ignoreDirs: string[];
+  /** Additional directory names to ignore on top of the built-in IGNORE_DIRS set. */
+  ignoreAdditionalDirs: string[];
   extensions: string[];
   aliases: Record<string, unknown>;
 
@@ -1327,6 +1377,26 @@ export interface CodegraphConfig {
      * Default: false.
      */
     typescriptResolver: boolean;
+    /**
+     * Engine selection override. Values: `'auto'` (default), `'native'`, `'wasm'`.
+     *
+     * **Current wiring (partial):** This field is populated by `applyEnvOverrides`
+     * from `CODEGRAPH_ENGINE` env var — env var → `config.build.engine`. The
+     * `--engine` CLI flag is also forwarded. However, `connection.ts` and
+     * `pipeline.ts` still read `process.env.CODEGRAPH_ENGINE` / `ctx.opts.engine`
+     * directly, so a value set only in `.codegraphrc.json` (not via env var or CLI)
+     * is silently ignored by the pipeline.
+     *
+     * Full config-file wiring is tracked in issue #1596.
+     */
+    engine: 'auto' | 'native' | 'wasm';
+    /**
+     * Enable diagnostic logging for the native fast-skip pre-flight check.
+     * Equivalent to `CODEGRAPH_FAST_SKIP_DIAG=1`. When true, logs why the
+     * fast-skip gate was skipped (e.g. forceFullRebuild, engineName mismatch).
+     * Default: false.
+     */
+    fastSkipDiag: boolean;
   };
 
   query: {
@@ -1405,6 +1475,13 @@ export interface CodegraphConfig {
      * constant of 50.  See TODO in `src/infrastructure/config.ts`.
      */
     pointsToMaxIterations: number;
+    /**
+     * Confidence score for a return type inferred from `return new Constructor()`
+     * with no explicit TypeScript annotation.
+     * Mirrors `INFERRED_RETURN_TYPE_CONFIDENCE` in `src/extractors/javascript.ts`.
+     * @reserved — not yet wired; see TODO in `src/infrastructure/config.ts`.
+     */
+    typeInferenceConfidence: number;
   };
 
   community: {
@@ -2209,6 +2286,14 @@ export interface NativeAddon {
     filePath: string,
     langId?: string | null,
   ): DataflowResult | null;
+  /**
+   * Batch counterpart to {@link extractDataflowAnalysis}: read and analyse many
+   * files in parallel (rayon) in a single NAPI call. Results are positional —
+   * `null` where the file could not be read or has no dataflow rules. Optional:
+   * older published addons predate this export, so callers must feature-detect
+   * and fall back to per-file `extractDataflowAnalysis`.
+   */
+  extractDataflowAnalysisBatch?(filePaths: string[]): (DataflowResult | null)[];
   ParseTreeCache: new () => NativeParseTreeCache;
   NativeDatabase: {
     openReadWrite(dbPath: string): NativeDatabase;