@colbymchenry/codegraph 0.9.9 → 1.0.1

package/dist/mcp/tools.d.ts

@@ -5,6 +5,25 @@
  */
 import type CodeGraph from '../index';
 import type { PendingFile } from '../sync';
+/**
+ * An expected, recoverable "codegraph can't serve this" condition — most
+ * importantly a project with no index. The dispatch catch converts these to
+ * SUCCESS-shaped responses (guidance text, NO isError): an `isError: true`
+ * early in a session teaches the agent the toolset is broken and it stops
+ * calling codegraph entirely (observed repeatedly), which is exactly wrong
+ * for conditions the agent can simply work around (use built-in tools for
+ * that codebase / pass projectPath). isError is reserved for "stop trying"
+ * cases: security refusals ({@link PathRefusalError}) and genuine
+ * malfunctions.
+ */
+export declare class NotIndexedError extends Error {
+}
+/**
+ * A security refusal (sensitive system path). Stays `isError: true` WITHOUT
+ * retry guidance — abandoning this path is the desired agent reaction.
+ */
+export declare class PathRefusalError extends Error {
+}
 /**
  * Calculate the recommended number of codegraph_explore calls based on project size.
  * Larger codebases need more exploration calls to cover their surface area,
@@ -241,6 +260,16 @@ export declare class ToolHandler {
      * Handle codegraph_search
      */
     private handleSearch;
+    /**
+     * Group symbol matches into DISTINCT DEFINITIONS — one group per
+     * (filePath, qualifiedName), so same-file overloads stay together while
+     * unrelated same-named classes across a monorepo's apps (#764: one
+     * `UserService` per NestJS app) are kept apart. Optionally narrowed by a
+     * `file` path/suffix first.
+     */
+    private groupDefinitions;
+    /** Section heading for one distinct definition in grouped output. */
+    private definitionHeading;
     /**
      * Handle codegraph_callers
      */
@@ -275,6 +304,27 @@ export declare class ToolHandler {
      * dropping unrelated `OmsOrderService::list`.
      */
     private buildFlowFromNamedSymbols;
+    /**
+     * Dynamic-boundary surfacing (#687): when the flow among the agent's named
+     * symbols does not fully connect, scan the disconnected symbols' bodies for
+     * dynamic-dispatch sites (computed member calls, getattr, reflection, typed
+     * message buses, runtime-keyed emits) and ANNOUNCE the boundary — the exact
+     * site, the form, and (when a key is statically visible) candidate targets —
+     * instead of guessing edges. The answer to "how does A reach B" when no
+     * static path exists IS the dispatch site: that's where the flow continues
+     * at runtime. Query-time, deterministic, zero graph mutation; a fully
+     * connected flow never reaches this method.
+     */
+    private buildDynamicBoundaries;
+    /**
+     * Shortlist candidate runtime targets for a dispatch key surfaced by
+     * {@link buildDynamicBoundaries}. Exact conventional names first (`save` →
+     * `onSave`/`handleSave`; `CreateCmd` → `CreateCmdHandler`), then FTS, with a
+     * normalized-containment post-filter (FTS camel-splitting is fuzzier than a
+     * candidate list should be). Symbols the agent already named sort first and
+     * are marked — that's the "you were right, here's the wiring" case.
+     */
+    private boundaryCandidates;
     /**
      * Compact "blast radius" for the entry symbols of an explore result: who
      * depends on each (callers) and which test files cover it — LOCATIONS ONLY,
@@ -317,6 +367,20 @@ export declare class ToolHandler {
      * Handle codegraph_node
      */
     private handleNode;
+    /**
+     * FILE READ MODE: resolve `fileArg` (path or basename) to an indexed file and
+     * read it like the Read tool — its current on-disk source with line numbers,
+     * narrowable with `offset`/`limit` exactly as Read's are — preceded by a
+     * one-line blast-radius header (which files depend on it). `symbolsOnly`
+     * returns just the structural map (symbols + dependents) instead of source.
+     *
+     * Parity goal: the numbered source block is byte-for-byte the shape Read
+     * returns (`<n>\t<line>`, no padding), so the agent treats it as a Read — only
+     * faster (served from the index) and with the blast radius attached. Security:
+     * yaml/properties files are summarized by key, never dumped (#383); reads go
+     * through validatePathWithinRoot (#527).
+     */
+    private handleFileView;
     /** Render one symbol: details + (optional) body/outline + its caller/callee trail. */
     private renderNodeSection;
     /**
@@ -396,6 +460,13 @@ export declare class ToolHandler {
     private truncateOutput;
     private formatSearchResults;
     private formatNodeList;
+    /**
+     * Relationship label for a non-`calls` edge in callers/callees lists. A
+     * function-as-value edge (#756) is the high-signal one: `callers(cb)`
+     * showing "via callback registration" tells the agent this is where the
+     * callback is WIRED, not where it's invoked.
+     */
+    private edgeLabel;
     private formatImpact;
     /**
      * Build a compact structural outline of a container symbol from its

package/dist/resolution/callback-synthesizer.d.ts

@@ -2,9 +2,9 @@ import type { QueryBuilder } from '../db/queries';
 import type { ResolutionContext } from './types';
 /**
  * Synthesize dispatcher→callback edges (field observers + EventEmitters +
- * React re-render + JSX children + Vue templates + RN event channel +
- * Fabric native-impl + MyBatis Java↔XML + Gin middleware chain). Returns the
- * count added. Never throws into indexing — callers wrap in try/catch.
+ * React re-render + JSX children + Vue templates + SvelteKit load + RN event
+ * channel + Fabric native-impl + MyBatis Java↔XML + Gin middleware chain).
+ * Returns the count added. Never throws into indexing — callers wrap in try/catch.
  */
 export declare function synthesizeCallbackEdges(queries: QueryBuilder, ctx: ResolutionContext): number;
 //# sourceMappingURL=callback-synthesizer.d.ts.map

package/dist/resolution/frameworks/astro.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Astro Framework Resolver
+ *
+ * Handles Astro component references, the `Astro` global, `astro:*` virtual
+ * module imports, and Astro's `src/pages/` file-based routing.
+ */
+import { FrameworkResolver } from '../types';
+export declare const astroResolver: FrameworkResolver;
+//# sourceMappingURL=astro.d.ts.map

package/dist/resolution/frameworks/index.d.ts

@@ -33,6 +33,7 @@ export { nestjsResolver } from './nestjs';
 export { reactResolver } from './react';
 export { svelteResolver } from './svelte';
 export { vueResolver } from './vue';
+export { astroResolver } from './astro';
 export { djangoResolver, flaskResolver, fastapiResolver } from './python';
 export { railsResolver } from './ruby';
 export { springResolver } from './java';

package/dist/resolution/import-resolver.d.ts

@@ -27,6 +27,16 @@ export declare function clearCppIncludeDirCache(): void;
  * Returns paths relative to projectRoot.
  */
 export declare function loadCppIncludeDirs(projectRoot: string): string[];
+/**
+ * Is this reference a PHP include/require PATH (vs a namespace `use` symbol)?
+ *
+ * include/require emit a file path ("lib.php", "inc/db.php", "../x.php"),
+ * whereas namespace use is an FQN (App\Foo\Bar) or a bare class symbol
+ * (Closure). PHP identifiers contain neither '/' nor '.', so a slash or dot
+ * marks a path-shaped include. Such references resolve to files only — never
+ * to a same-named symbol — so callers must not fall back to the name-matcher.
+ */
+export declare function isPhpIncludePathRef(ref: UnresolvedRef): boolean;
 /**
  * Extract import mappings from a file
  */

package/dist/resolution/index.d.ts

@@ -17,6 +17,9 @@ export declare class ReferenceResolver {
     private queries;
     private context;
     private frameworks;
+    private deferredChainRefs;
+    private deferredThisMemberRefs;
+    private razorUsingsCache;
     private nodeCache;
     private fileCache;
     private importMappingCache;
@@ -29,6 +32,7 @@ export declare class ReferenceResolver {
     private cachesWarmed;
     private projectAliases;
     private goModule;
+    private workspacePackages;
     constructor(projectRoot: string, queries: QueryBuilder);
     /**
      * Initialize the resolver (detect frameworks, etc.)
@@ -86,6 +90,20 @@ export declare class ReferenceResolver {
      * Resolve and persist edges to database
      */
     resolveAndPersist(unresolvedRefs: UnresolvedReference[], onProgress?: (current: number, total: number) => void): ResolutionResult;
+    /**
+     * Second resolution pass for chained static-factory / fluent calls whose
+     * chained method is defined on a SUPERTYPE the receiver's type conforms to —
+     * a protocol-extension / inherited / default-interface method (#750). The
+     * first pass can't resolve these because `implements`/`extends` edges aren't
+     * built yet; this runs AFTER edges are persisted, so `context.getSupertypes`
+     * (and the conformance fallback in resolveMethodOnType) can walk them.
+     *
+     * Operates only on the leftover unresolved refs that have the `inner().method`
+     * chain shape, for the dotted-chain languages — a small set — and is idempotent
+     * (re-resolving an already-resolved ref is a no-op since it's been deleted).
+     * Returns the number of newly-created edges.
+     */
+    resolveChainedCallsViaConformance(): number;
     /**
      * Resolve and persist in batches to keep memory bounded.
      * Processes unresolved references in chunks, persisting edges and cleaning
@@ -108,6 +126,68 @@ export declare class ReferenceResolver {
      * Get language from node ID
      */
     private getLanguageFromNodeId;
+    /**
+     * Drop an import/name-strategy resolution that crosses a language family.
+     * Two regimes (mirrors `applyLanguageGate`'s candidate filter):
+     *  - `references` (type usage): STRICT — a `Type.member` static read names a
+     *    same-family type, never a coincidentally same-named symbol in another
+     *    language. Drops any non-same-family target.
+     *  - `imports` (import binding / `#include`): both-known — a C++ `#include
+     *    "X.h"` must not resolve to a same-named ObjC header on another platform
+     *    (basename collision), but a singleton-family / SFC language (`vue` →
+     *    `.ts`) importing across is left alone.
+     * Applies to the import (strategy 2) + name-match (strategy 3) results.
+     */
+    /**
+     * Collect the `@using` namespaces in scope for a `.razor`/`.cshtml` file: its
+     * own `@using` directives plus every `_Imports.razor` from the file's folder up
+     * to the project root (Razor `_Imports` cascade). Cached per file.
+     */
+    private getRazorUsings;
+    /**
+     * Resolve a Razor/Blazor simple type ref through the file's `@using`
+     * namespaces: `CatalogBrand` + `@using BlazorShared.Models` → the node whose
+     * qualified name is `BlazorShared.Models::CatalogBrand`. Only resolves when the
+     * `@using` set yields exactly ONE type (otherwise it stays ambiguous and falls
+     * through to name-matching).
+     */
+    private resolveRazorUsing;
+    /**
+     * Resolve a `this.<member>` function-as-value reference (#756/#808) to the
+     * ENCLOSING CLASS's own member — never a same-named symbol elsewhere. The
+     * registration idiom (`btn.on('click', this.handleClick)`) names a member
+     * of the class being defined, so the only valid target shares the
+     * from-symbol's qualified-name scope. Function/method targets only — a
+     * property (a data field, post-#808 classification) yields no edge — same
+     * file required, no fallback of any kind.
+     */
+    private resolveThisMemberFnRef;
+    /**
+     * Second pass for `this.<member>` refs whose member wasn't on the enclosing
+     * class itself (#808): once implements/extends edges exist, walk the
+     * class's supertypes (transitively, depth-capped) and resolve the member on
+     * the nearest one that declares it — `this.handleSubmit` registered in a
+     * subclass resolves to `FormBase::handleSubmit`. Validated targets only
+     * (function/method kind, same language family); no match → no edge.
+     * Mirrors resolveChainedCallsViaConformance's lifecycle. Returns the number
+     * of newly-created edges.
+     */
+    resolveDeferredThisMemberRefs(): number;
+    private gateLanguage;
+    /**
+     * Drop a FRAMEWORK-strategy resolution that crosses two *known* language
+     * families for a type-usage (`references`) or import-binding (`imports`)
+     * edge. The framework strategy is intentionally ungated for cross-language
+     * bridges, but those legitimate bridges are either `calls` edges (RN/Expo
+     * JS → native) or config↔code edges whose config side (`yaml`/`blade`/…) is
+     * not a known programming-language family. A `references`/`imports` edge
+     * between two *known* families is always a coincidental name collision — the
+     * React/Svelte/Vue PascalCase component resolvers name-match `getNodesByName`
+     * without a language check, so a TS `<TestRunner>` ref happily matched a
+     * Kotlin `class TestRunner`. Gating only the both-known-cross-family case
+     * lets config bridges and `calls` bridges through untouched.
+     */
+    private gateFrameworkLanguage;
 }
 /**
  * Create a reference resolver instance

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
  */