@colbymchenry/codegraph 0.9.9 → 1.0.0

package/dist/resolution/name-matcher.d.ts

@@ -9,6 +9,36 @@ import { UnresolvedRef, ResolvedRef, ResolutionContext } from './types';
  * by matching the filename against file nodes.
  */
 export declare function matchByFilePath(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
+export declare function sameLanguageFamily(a: string, b: string): boolean;
+/**
+ * True when `lang` belongs to a known multi-language family (jvm/apple/web/c).
+ * Languages not listed (php, python, go, ruby, rust, dart, …) and config
+ * formats (yaml/xml/blade) form their own singleton families and return
+ * `false` — used to leave config↔code framework bridges (whose config side is
+ * never a known programming-language family) out of the cross-family gate.
+ */
+export declare function isKnownLanguageFamily(lang: string): boolean;
+/**
+ * True when `a` and `b` are two DIFFERENT *known* language families — the
+ * signature of a coincidental cross-language name collision (a TS `import
+ * React` matching a Swift `import React`, a C++ `#include "X.h"` matching a
+ * same-named ObjC header on another platform). The both-*known* test is
+ * deliberately weaker than {@link sameLanguageFamily}'s negation: a
+ * single-file-component language that carries its own tag (`vue`/`svelte`)
+ * importing a `.ts` module, or any singleton-family language (php/go/ruby/…),
+ * returns `false` here and is left alone.
+ */
+export declare function crossesKnownFamily(a: string, b: string): boolean;
+/**
+ * Resolve a function-as-value reference (#756) — a function name used as a
+ * callback/function-pointer value (`register(handler)`, `o->cb = handler`,
+ * `{ .cb = handler }`, `signal(SIGINT, handler)`). The ONLY strategy allowed
+ * for `function_ref` refs: exact name, function/method targets only, same
+ * language family, same-file first, and cross-file only when the match is
+ * UNIQUE. No fuzzy fallback, no qualified-name walking — a wrong callback
+ * edge is worse than none.
+ */
+export declare function matchFunctionRef(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
 /**
  * Try to resolve a reference by exact name match
  */
@@ -17,6 +47,37 @@ export declare function matchByExactName(ref: UnresolvedRef, context: Resolution
  * Try to resolve by qualified name
  */
 export declare function matchByQualifiedName(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
+/**
+ * Resolve a C++ chained call whose receiver is itself a call — encoded by the
+ * extractor as `<innerCallee>().<method>` (#645). The receiver's type is what
+ * the inner call returns; the outer method is then resolved and VALIDATED on it
+ * (resolveMethodOnType requires `cls::method` to exist), so a wrong inference
+ * produces no edge rather than a wrong one.
+ */
+export declare function matchCppCallChain(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
+/**
+ * Resolve a `::`-scoped factory chain whose receiver is a scoped/static call —
+ * PHP `Cls::for($x)->method()` (#608, the per-credential Laravel client idiom) or
+ * Rust `Foo::new().bar()` (an associated-function call) — both encoded by the
+ * extractor as `Cls::factory().method`. The receiver's type is what `Cls::factory`
+ * returns: a `self` marker (PHP `: self`/`: static`, Rust `-> Self`) resolves to
+ * the factory's own type, a concrete return type to that type. The outer method is
+ * then resolved and VALIDATED on it (resolveMethodOnType requires the method to
+ * exist on the type or a supertype it conforms to), so a wrong inference yields no
+ * edge rather than a wrong one. Shared by the `::`-receiver languages (PHP, Rust).
+ */
+export declare function matchScopedCallChain(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
+/**
+ * Resolve a dotted chained call whose receiver is a static factory / fluent call —
+ * `Foo.getInstance().bar()`, encoded by the extractor as `Foo.getInstance().bar`
+ * (#645/#608 mechanism). The receiver's type is what `Foo.getInstance` returns
+ * (its declared return type); the outer method is then resolved and VALIDATED on
+ * it (resolveMethodOnType requires `Type::method` to exist), so a wrong inference
+ * yields no edge rather than a wrong one (e.g. a same-named `bar()` on an
+ * unrelated class is never matched). Shared by the dot-notation languages
+ * (Java, Kotlin, C#, Swift) — same receiver shape, same `Class::method` qualified names.
+ */
+export declare function matchDottedCallChain(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
 /**
  * Try to resolve by method name on a class/object
  */

package/dist/resolution/types.d.ts

@@ -3,7 +3,7 @@
  *
  * Types for the reference resolution system.
  */
-import { EdgeKind, Language, Node } from '../types';
+import { Language, Node, ReferenceKind } from '../types';
 /**
  * An unresolved reference from extraction
  */
@@ -13,7 +13,7 @@ export interface UnresolvedRef {
     /** The name being referenced */
     referenceName: string;
     /** Type of reference */
-    referenceKind: EdgeKind;
+    referenceKind: ReferenceKind;
     /** Line where reference occurs */
     line: number;
     /** Column where reference occurs */
@@ -36,7 +36,7 @@ export interface ResolvedRef {
     /** Confidence score (0-1) */
     confidence: number;
     /** How it was resolved */
-    resolvedBy: 'exact-match' | 'import' | 'qualified-name' | 'framework' | 'fuzzy' | 'instance-method' | 'file-path';
+    resolvedBy: 'exact-match' | 'import' | 'qualified-name' | 'framework' | 'fuzzy' | 'instance-method' | 'file-path' | 'function-ref';
 }
 /**
  * Result of resolution attempt
@@ -76,6 +76,23 @@ export interface ResolutionContext {
     getAllFiles(): string[];
     /** Get nodes by lowercase name (O(1) lookup for fuzzy matching) */
     getNodesByLowerName(lowerName: string): Node[];
+    /**
+     * Direct supertypes of the type named `typeName` (same language): the classes
+     * it extends and the interfaces / protocols / traits it implements/conforms to,
+     * by simple name. Backed by the resolved `implements`/`extends` edges, so it is
+     * EMPTY during the first resolution pass (edges aren't built yet) and populated
+     * afterward — the conformance pass uses it to resolve a chained method defined
+     * on a supertype the receiver type conforms to (e.g. a protocol-extension
+     * method). Optional so external/test contexts compile without it.
+     */
+    getSupertypes?(typeName: string, language: Language): string[];
+    /**
+     * Look up a node by its id. Lets matchers derive the FROM-symbol's
+     * enclosing-class scope (Swift implicit-self method scoping, `this.X`
+     * member resolution). Optional so external/test contexts compile
+     * without it.
+     */
+    getNodeById?(id: string): Node | null;
     /** Get cached import mappings for a file */
     getImportMappings(filePath: string, language: Language): ImportMapping[];
     /**
@@ -94,6 +111,13 @@ export interface ResolutionContext {
      * cross-package imports from third-party packages.
      */
     getGoModule?(): import('./go-module').GoModule | null;
+    /**
+     * Monorepo workspace member packages, keyed by declared package name.
+     * Returns `null` for single-package repos (no `workspaces` field).
+     * Lets the resolver treat `@scope/ui/sub` as a local import into the
+     * member's directory instead of an external npm package (#629).
+     */
+    getWorkspacePackages?(): import('./workspace-packages').WorkspacePackages | null;
     /**
      * Re-exports declared by a file (`export { x } from './other'`,
      * `export * from './other'`). Empty array when the file has none.

package/dist/resolution/workspace-packages.d.ts

@@ -0,0 +1,48 @@
+/**
+ * JS/TS workspace (monorepo) package resolution.
+ *
+ * npm / yarn / bun read member packages from the root `package.json`
+ * `workspaces` field; pnpm from `pnpm-workspace.yaml`. A cross-package
+ * import like `@scope/ui/widgets` is LOCAL to the monorepo, but to a
+ * single-package resolver it looks exactly like a third-party npm
+ * specifier — so `isExternalImport` flags it external and the
+ * consumer↔definition edge is never created. For component barrels
+ * (`export { default as X } from './x.svelte'`) that surfaces as a false
+ * `0 callers` on a live component (issue #629).
+ *
+ * This module maps each member package's declared `name` to its
+ * directory so the resolver can rewrite `@scope/ui/widgets` →
+ * `packages/ui/widgets` and then run normal extension/index resolution.
+ *
+ * Scope deliberately small for v1 (mirrors path-aliases.ts):
+ *   - reads `workspaces` (array OR `{ packages: [...] }`) from package.json,
+ *     plus a minimal `pnpm-workspace.yaml` `packages:` list
+ *   - expands one level of `*` / `**` globs (`packages/*`, `apps/*`)
+ *   - subpath resolution is directory-based (`@scope/ui/sub` → `<ui>/sub`);
+ *     it does NOT yet honour a member's `exports` map or `main` field
+ *   - returns null when the project declares no workspaces, so single-
+ *     package repos pay nothing and see no behaviour change.
+ */
+export interface WorkspacePackages {
+    /** Member package `name` → directory relative to projectRoot (posix). */
+    byName: Map<string, string>;
+}
+/**
+ * Load workspace member packages for `projectRoot`. Returns `null` when
+ * the project declares no workspaces (the common single-package case) —
+ * callers then skip all workspace logic.
+ *
+ * Cheap to call repeatedly only via the resolver's per-instance cache;
+ * this function itself touches the filesystem, so the resolver memoises it
+ * the same way it does {@link loadProjectAliases} / {@link loadGoModule}.
+ */
+export declare function loadWorkspacePackages(projectRoot: string): WorkspacePackages | null;
+/**
+ * Rewrite a bare workspace import to a path relative to projectRoot,
+ * WITHOUT an extension — the caller applies the language's extension/index
+ * resolution. `@scope/ui/widgets` → `packages/ui/widgets`; the bare package
+ * name `@scope/ui` → its directory. Returns `null` when no member package
+ * name matches.
+ */
+export declare function resolveWorkspaceImport(importPath: string, ws: WorkspacePackages): string | null;
+//# sourceMappingURL=workspace-packages.d.ts.map

package/dist/search/query-utils.d.ts

@@ -4,6 +4,22 @@
  * Shared module for search term extraction and scoring.
  */
 import { Node } from '../types';
+/** Normalize a name to a comparable token: lowercase, alphanumerics only. */
+export declare function normalizeNameToken(raw: string): string;
+/**
+ * Tokens that name the PROJECT as a whole — its `go.mod` module, `package.json`
+ * name, or repo root directory — rather than any specific symbol. A user
+ * naturally puts the project name in a query as context ("MyApp backend
+ * routes"), but it carries no discriminative signal: when it's also a substring
+ * of a symbol or path on one stack (a `MyAppFrontend/` dir, a `MyAppApp` class)
+ * it lexically inflates that stack and buries the rest (#720).
+ *
+ * Returned normalized (lowercase, alphanumerics only) so a query word can be
+ * compared by its normalized form. Only names ≥5 chars are kept — short ones
+ * (`api`, `app`, `core`, `web`) collide with real query terms too often to
+ * safely down-weight.
+ */
+export declare function deriveProjectNameTokens(projectRoot: string): Set<string>;
 /**
  * Common stop words to filter from search queries.
  * Includes generic English + code-specific noise words.
@@ -34,7 +50,7 @@ export declare function extractSearchTerms(query: string, options?: {
  * Score path relevance to a query
  * Higher score = more relevant path
  */
-export declare function scorePathRelevance(filePath: string, query: string): number;
+export declare function scorePathRelevance(filePath: string, query: string, projectNameTokens?: Set<string>): number;
 /**
  * Check if a file path looks like a test file
  */

package/dist/sync/watcher.d.ts

@@ -4,14 +4,31 @@
  * Watches the project directory for file changes and triggers debounced sync
  * operations to keep the code graph up-to-date.
  *
- * Uses chokidar, whose `ignored` callback filters directories BEFORE they are
- * watched — so we never register inotify watches on excluded trees like
- * node_modules/, dist/, .git/ (fixes #276: recursive fs.watch exhausted the
- * kernel watch budget on large repos). The ignore decision reuses the indexer's
- * `buildDefaultIgnore` (built-in default-ignore dirs + the project's .gitignore)
- * so the watcher watches exactly the set the indexer indexes — in particular,
- * node_modules/build/cache dirs are excluded even when the repo has no
- * .gitignore (#407), which a .gitignore-only filter would miss.
+ * Uses Node's built-in `fs.watch` directly (no third-party watcher, no native
+ * addon) with a per-platform strategy chosen to keep the open-descriptor /
+ * kernel-watch cost BOUNDED rather than growing with the number of files:
+ *
+ *   - macOS / Windows: a SINGLE recursive `fs.watch(root, {recursive:true})`.
+ *     libuv maps this to one FSEvents stream (macOS) / one
+ *     ReadDirectoryChangesW handle (Windows), so it costs O(1) descriptors no
+ *     matter how large the tree. This is the fix for the macOS file-table
+ *     exhaustion (#644 / #496 / #555 / #628): the previous watcher held one
+ *     open fd PER WATCHED FILE on macOS (tens of thousands of REG fds), which
+ *     exhausted `kern.maxfiles` and crashed unrelated processes system-wide.
+ *
+ *   - Linux: recursive `fs.watch` is unsupported, so we watch each (non-ignored)
+ *     DIRECTORY with one inotify watch — O(directories), NOT O(files). New
+ *     directories are picked up dynamically and an overall watch cap bounds
+ *     inotify usage on pathological monorepos (#579). A single inotify watch on
+ *     a directory already reports create/modify/delete for its children, so
+ *     per-file watches are never needed.
+ *
+ * Excluded trees (node_modules/, dist/, .git/, …) are filtered via the
+ * indexer's `buildScopeIgnore` (built-in default-ignore dirs + the project's
+ * .gitignore) — on Linux they're never descended into (so they cost no watch),
+ * and on macOS/Windows the single recursive stream still covers them but their
+ * events are dropped before any sync is scheduled. Either way the watcher's
+ * scope matches the indexer's (#276 / #407).
  */
 /**
  * Options for the file watcher
@@ -34,6 +51,15 @@ export interface WatchOptions {
      * Callback when a sync errors (for logging/diagnostics).
      */
     onSyncError?: (error: Error) => void;
+    /**
+     * Test-only. When true, `start()` installs NO OS-level fs.watch — the
+     * watcher is "inert" and only the {@link __emitWatchEventForTests} /
+     * {@link FileWatcher.ingestEventForTests} seam drives its pipeline. This
+     * restores the deterministic, OS-free behavior the unit tests need (real
+     * FSEvents/inotify delivery races under parallel vitest). Production never
+     * sets it.
+     */
+    inertForTests?: boolean;
 }
 /**
  * Thrown by a `syncFn` to signal that the underlying sync couldn't acquire
@@ -69,8 +95,9 @@ export interface PendingFile {
  * debounced sync operations via a provided callback.
  *
  * Design goals:
- * - Minimal resource usage (chokidar filters excluded directories before
- *   registering an inotify watch — see module docs / #276)
+ * - Bounded resource usage: O(1) descriptors on macOS/Windows (one recursive
+ *   watch), O(directories) inotify watches on Linux — never O(files), which
+ *   was the system-crashing fd leak on macOS (#644/#496/#555/#628).
  * - Debounced to avoid thrashing on rapid saves
  * - Filters to supported source files by extension
  * - Ignores .codegraph/ and .git/ regardless of .gitignore
@@ -78,11 +105,18 @@ export interface PendingFile {
  *   without blocking on a sync (issue #403)
  */
 export declare class FileWatcher {
-    private watcher;
+    /** macOS/Windows: the single recursive watcher. Null on Linux. */
+    private recursiveWatcher;
+    /** Linux: one watcher per watched directory (keyed by absolute path). */
+    private dirWatchers;
+    /** Set once the per-directory watch cap is hit, so we log only once. */
+    private dirCapWarned;
+    /** Test-only inert mode: started, but with no OS watcher installed. */
+    private inert;
     private debounceTimer;
     /**
      * Files seen by the watcher since the last successful sync — populated on
-     * every chokidar event, cleared at the start of a sync, and re-populated by
+     * every change event, cleared at the start of a sync, and re-populated by
      * events that arrive mid-sync (or restored on sync failure). Keyed by the
      * same project-relative POSIX path the rest of the codebase uses, so a
      * caller can intersect tool-response file paths against this map cheaply.
@@ -98,17 +132,18 @@ export declare class FileWatcher {
     private syncing;
     private stopped;
     /**
-     * False until chokidar fires its `ready` event. Gates `pendingFiles`
-     * insertion so the initial crawl's `add` events (one per pre-existing
-     * source file) don't pollute the per-file staleness signal. The events
-     * still flow into `scheduleSync()` to preserve the previous "initial
-     * scan triggers a reconciling sync" behavior.
+     * True once the initial watch set is established. Unlike the previous
+     * chokidar implementation there is no asynchronous initial "crawl" emitting
+     * an `add` per existing file — `fs.watch` only reports changes from the
+     * moment it's installed — so this flips to true synchronously at the end of
+     * `start()`. The startup reconcile against on-disk state is handled
+     * separately by the engine's catch-up sync, not by the watcher.
      */
-    private chokidarReady;
+    private ready;
     /**
-     * Callbacks that resolve when chokidar fires `ready`. Used by tests (and
-     * any production caller that cares about a clean baseline) to deterministically
-     * gate on the end of the initial scan instead of guessing at a sleep duration.
+     * Callbacks that resolve when the watch set is established. Used by tests
+     * (and any production caller that cares about a clean baseline) to
+     * deterministically gate on watcher readiness.
      */
     private readyWaiters;
     private ignoreMatcher;
@@ -117,6 +152,7 @@ export declare class FileWatcher {
     private readonly syncFn;
     private readonly onSyncComplete?;
     private readonly onSyncError?;
+    private readonly inertForTests;
     constructor(projectRoot: string, syncFn: () => Promise<{
         filesChanged: number;
         durationMs: number;
@@ -126,32 +162,79 @@ export declare class FileWatcher {
      * Returns true if watching started successfully, false otherwise.
      */
     start(): boolean;
+    /**
+     * macOS/Windows: one recursive watcher for the whole tree. O(1) descriptors.
+     * `filename` arrives relative to the project root (with subdirectories), so
+     * it maps straight to a project-relative path.
+     */
+    private startRecursive;
+    /**
+     * Linux: walk the (non-ignored) tree and watch each directory. One inotify
+     * watch per directory reports create/modify/delete for that directory's
+     * direct children, so we never watch individual files.
+     */
+    private startPerDirectory;
+    /**
+     * Add an inotify watch for `dir` and recurse into its non-ignored
+     * subdirectories. When `markExisting` is true (a directory that appeared
+     * AFTER startup), the source files already inside it are recorded as pending
+     * — this closes the `mkdir + write` race where files created before the new
+     * directory's watch is installed would otherwise be missed until the next
+     * full sync. The initial startup walk passes false (the engine's catch-up
+     * sync owns the baseline).
+     */
+    private watchTree;
+    /**
+     * Linux per-directory event handler. `filename` is relative to `dir`. A new
+     * sub-directory is picked up by extending the watch tree; everything else is
+     * routed through the shared change handler.
+     */
+    private handleDirEvent;
+    /**
+     * Shared change handler for both watch strategies. `rel` is a
+     * project-relative POSIX path. Applies the ignore + source-file filters and,
+     * for a real source change, records it as pending (#403) and schedules a
+     * debounced sync.
+     *
+     * The recursive (macOS/Windows) watcher reports events for ignored trees too
+     * (one stream covers the whole repo), so the ignore check here is load-bearing
+     * — it drops node_modules/dist/.git churn before any sync is scheduled.
+     */
+    private handleChange;
+    /** Close and forget the watch for a directory that errored/was removed. */
+    private unwatchDir;
     /** Our own dirs are always ignored, regardless of .gitignore. */
     private isAlwaysIgnored;
     /**
-     * chokidar `ignored` predicate — true for any path that should NOT be watched.
-     * Uses chokidar's provided `stats` to decide directory-vs-file so a dir-only
-     * rule like `build/` matches, without an extra `statSync` per path.
+     * True for any directory that should NOT be watched (used while building the
+     * Linux per-directory watch tree). Tests the directory form of the path so a
+     * dir-only ignore rule like `build/` matches.
      */
-    private shouldIgnore;
+    private shouldIgnoreDir;
     /**
      * Stop watching for file changes.
      */
     stop(): void;
+    /**
+     * @internal Test-only: feed a synthetic project-relative change through the
+     * same filter → pendingFiles → debounced-sync path a real fs.watch event
+     * takes. Lets the watcher / staleness-banner suites stay deterministic
+     * instead of racing on OS watch-delivery latency. See
+     * {@link __emitWatchEventForTests}.
+     */
+    ingestEventForTests(relPath: string): void;
     /**
      * Whether the watcher is currently active.
      */
     isActive(): boolean;
     /**
-     * Resolves once chokidar has fired its `ready` event (or immediately if
-     * it has already done so). Useful for tests that need a deterministic
-     * boundary before asserting on `pendingFiles` — guessing a sleep duration
-     * is flaky under load because chokidar can take longer than expected to
-     * finish its initial crawl on slow filesystems / parallel test runs.
+     * Resolves once the watch set has been installed (or immediately if it
+     * already has). Useful for tests that need a deterministic boundary before
+     * asserting on `pendingFiles`.
      *
      * Production callers don't need this: `pendingFiles` is read continuously,
-     * the staleness banner is always correct (empty or populated), and the
-     * initial-scan window is a small one-time startup cost.
+     * the staleness banner is always correct (empty or populated), and there is
+     * no asynchronous initial-scan window with `fs.watch`.
      */
     waitUntilReady(timeoutMs?: number): Promise<void>;
     /**
@@ -188,4 +271,13 @@ export declare class FileWatcher {
      */
     getPendingFiles(): PendingFile[];
 }
+/**
+ * Test-only: synthesize a source-file change for the live watcher running at
+ * `projectRoot`, exercising the real filter → pendingFiles → debounced-sync
+ * logic without depending on fs.watch delivery timing (which races under
+ * parallel vitest). `relPath` is project-relative POSIX (e.g. "src/foo.ts").
+ * Returns false if no live watcher is registered for that root (e.g. outside a
+ * test runtime, where the registry is intentionally not populated).
+ */
+export declare function __emitWatchEventForTests(projectRoot: string, relPath: string): boolean;
 //# sourceMappingURL=watcher.d.ts.map

package/dist/telemetry/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Anonymous usage telemetry — client side.
+ *
+ * The contract for what may be collected lives in docs/design/telemetry.md
+ * (and user-facing TELEMETRY.md); the ingest endpoint that enforces it is
+ * public at telemetry-worker/. This module honors four invariants:
+ *
+ * 1. Zero hot-path cost: recording is an in-memory increment. Disk writes are
+ *    a tiny synchronous append at process exit (works under `process.exit()`,
+ *    where `beforeExit` never fires); network sends happen opportunistically
+ *    (startup of long-running commands, daemon interval, bounded await at the
+ *    end of install/init) and are fire-and-forget everywhere else.
+ * 2. Zero stdout: stdio is the MCP protocol channel. Notices and debug output
+ *    go to stderr only.
+ * 3. Off is off: when disabled, nothing is recorded, nothing is sent, and no
+ *    socket is opened — there is no "opted out" ping. Turning telemetry off
+ *    also deletes any buffered, unsent data.
+ * 4. Fail silent: offline, endpoint down, disk full — every failure mode is
+ *    silence, never a retry loop, never an error surfaced to the user/agent.
+ *
+ * Usage counts aggregate locally into per-day rollups; only *completed* (UTC)
+ * days are sent, so volume scales with active machines, not with tool calls.
+ */
+export declare const TELEMETRY_ENDPOINT = "https://telemetry.getcodegraph.com/v1/events";
+export declare const TELEMETRY_DOCS = "https://github.com/colbymchenry/codegraph/blob/main/TELEMETRY.md";
+export type UsageKind = 'mcp_tool' | 'cli_command';
+export type LifecycleEvent = 'install' | 'index' | 'uninstall';
+/** Coarse buckets — exact counts are deliberately not collected. */
+export declare function bucketFileCount(n: number): '<100' | '100-1k' | '1k-10k' | '10k+';
+export declare function bucketDuration(ms: number): '<10s' | '10-60s' | '1-5m' | '5m+';
+/** Collapse a backend identifier (e.g. `node-sqlite`) to the schema's enum. */
+export declare function backendKind(backend: string): 'native' | 'wasm';
+/**
+ * Shared "a full index completed" event (CLI init/index + installer local
+ * init): language names and coarse buckets only — never paths, file names,
+ * or exact counts. Structurally typed so callers don't need engine imports.
+ */
+export declare function recordIndexEvent(cg: {
+    getStats(): {
+        filesByLanguage: Record<string, number>;
+    };
+    getBackend(): string;
+}, result: {
+    filesIndexed: number;
+    durationMs: number;
+}): void;
+export interface ClientInfo {
+    name?: string;
+    version?: string;
+}
+export interface TelemetryStatus {
+    enabled: boolean;
+    /** What decided the current state — mirrors the precedence order. */
+    decidedBy: 'DO_NOT_TRACK' | 'CODEGRAPH_TELEMETRY' | 'config' | 'default';
+    machineId: string | null;
+    configPath: string;
+}
+export interface TelemetryOptions {
+    /** Global state dir; defaults to ~/.codegraph. Tests inject a temp dir. */
+    dir?: string;
+    fetchImpl?: typeof globalThis.fetch;
+    now?: () => Date;
+    env?: NodeJS.ProcessEnv;
+    stderr?: (line: string) => void;
+    /** Tests opt out so short-lived instances don't pile onto process 'exit'. */
+    installExitHook?: boolean;
+}
+export declare class Telemetry {
+    private readonly dir;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly env;
+    private readonly writeStderr;
+    private counts;
+    private events;
+    private readonly installExitHook;
+    private exitHookInstalled;
+    private configCache;
+    private intervalHandle;
+    constructor(opts?: TelemetryOptions);
+    get configPath(): string;
+    get queuePath(): string;
+    /**
+     * Resolution order (first match wins) — keep in sync with TELEMETRY.md:
+     * DO_NOT_TRACK=1 > CODEGRAPH_TELEMETRY=0|1 > stored config > default on.
+     */
+    getStatus(): TelemetryStatus;
+    isEnabled(): boolean;
+    /**
+     * Persist an explicit user choice (installer toggle or `codegraph
+     * telemetry on|off`). Turning telemetry off also deletes any buffered,
+     * unsent data — off means off.
+     */
+    setEnabled(enabled: boolean, source: 'installer' | 'cli'): void;
+    /** True once any consent decision (or the first-run notice) is on disk. */
+    hasStoredChoice(): boolean;
+    /** In-memory increment — safe on the MCP tool-call hot path. */
+    recordUsage(kind: UsageKind, name: string, ok: boolean, client?: ClientInfo): void;
+    /** install / index / uninstall — buffered like everything else. */
+    recordLifecycle(event: LifecycleEvent, props: Record<string, unknown>): void;
+    /**
+     * Fire-and-forget send of everything sendable. Never throws, never logs
+     * above debug. Safe to call at startup of long-running commands.
+     */
+    maybeFlush(): void;
+    /**
+     * Drain in-memory state to the buffer, then send completed-day rollups and
+     * lifecycle events. Bounded by `timeoutMs`; leftovers stay buffered for the
+     * next process. Awaited only where latency is invisible (install/init).
+     */
+    flushNow(timeoutMs?: number): Promise<void>;
+    /**
+     * Periodic flush for long-lived processes (MCP daemon / serve). Unref'd so
+     * it never keeps the process alive.
+     */
+    startInterval(everyMs?: number): void;
+    stopInterval(): void;
+    private utcDay;
+    private readConfig;
+    private writeConfig;
+    /**
+     * Default-on consent is gated by a one-time stderr notice (interactive
+     * installs record their choice explicitly and never reach this).
+     */
+    private firstRunNotice;
+    /**
+     * Synchronous, tiny, exit-safe: drain in-memory deltas to the JSONL queue.
+     * Runs on `process.on('exit')`, so it must never be async or slow.
+     */
+    persistSync(): void;
+    private appendLines;
+    /**
+     * Atomically claim the queue for sending (rename). Concurrent processes
+     * can't double-send; a crash mid-send leaves a claim file that
+     * `recoverStaleClaims` merges back after an hour.
+     */
+    private claimQueue;
+    private recoverStaleClaims;
+    /** Returns the lines that did NOT make it out (to be re-queued). */
+    private send;
+    private packageVersion;
+    private ensureExitHook;
+    private debug;
+}
+export declare function getTelemetry(): Telemetry;
+//# sourceMappingURL=index.d.ts.map

package/dist/types.d.ts

@@ -20,7 +20,7 @@ export type EdgeKind = 'contains' | 'calls' | 'imports' | 'exports' | 'extends'
  * Supported programming languages. See NODE_KINDS for why this is a
  * runtime-iterable const array.
  */
-export declare const LANGUAGES: readonly ["typescript", "javascript", "tsx", "jsx", "python", "go", "rust", "java", "c", "cpp", "csharp", "php", "ruby", "swift", "kotlin", "dart", "svelte", "vue", "liquid", "pascal", "scala", "lua", "luau", "objc", "yaml", "twig", "xml", "properties", "unknown"];
+export declare const LANGUAGES: readonly ["typescript", "javascript", "tsx", "jsx", "python", "go", "rust", "java", "c", "cpp", "csharp", "razor", "php", "ruby", "swift", "kotlin", "dart", "svelte", "vue", "astro", "liquid", "pascal", "scala", "lua", "luau", "objc", "r", "yaml", "twig", "xml", "properties", "unknown"];
 export type Language = (typeof LANGUAGES)[number];
 /**
  * A node in the knowledge graph representing a code symbol
@@ -64,6 +64,14 @@ export interface Node {
     decorators?: string[];
     /** Generic type parameters */
     typeParameters?: string[];
+    /**
+     * Normalized return/result type name for a function/method (the bare class
+     * name, smart-pointer pointee unwrapped). Captured for C/C++ so resolution
+     * can infer a chained receiver's type from what the inner call returns —
+     * `Foo::instance().bar()` resolves `bar` on `Foo` (issue #645). Undefined for
+     * languages/symbols where it isn't captured.
+     */
+    returnType?: string;
     /** When the node was last updated */
     updatedAt: number;
 }
@@ -139,6 +147,13 @@ export interface ExtractionError {
     /** Error code for categorization */
     code?: string;
 }
+/**
+ * Kinds an unresolved reference can carry. `function_ref` is internal-only —
+ * a function name used as a VALUE (callback registration, #756). It never
+ * becomes an edge kind: resolution maps it to a `references` edge targeting
+ * function/method nodes only (see `matchFunctionRef`).
+ */
+export type ReferenceKind = EdgeKind | 'function_ref';
 /**
  * A reference that couldn't be resolved during extraction
  */
@@ -148,7 +163,7 @@ export interface UnresolvedReference {
     /** Name being referenced */
     referenceName: string;
     /** Type of reference (call, type, import, etc.) */
-    referenceKind: EdgeKind;
+    referenceKind: ReferenceKind;
     /** Location of the reference */
     line: number;
     column: number;