@colbymchenry/codegraph 1.0.0 → 1.1.0

package/dist/reasoning/config.d.ts

@@ -0,0 +1,45 @@
+/** Managed tier ("CodeGraph AI") — the metered gateway used when logged in. */
+export declare const MANAGED_DEFAULT_URL = "https://ai.getcodegraph.com/v1";
+/** The gateway's public model id (it translates this to the upstream provider id). */
+export declare const MANAGED_DEFAULT_MODEL = "openai/gpt-oss-120b";
+export interface OffloadConfig {
+    /** Managed tier: route through CodeGraph AI (metered) with the logged-in org token. */
+    managed?: boolean;
+    /** OpenAI-compatible base URL ending in `/v1` (e.g. https://api.cerebras.ai/v1). */
+    url?: string;
+    /** Model id to request (default `gpt-oss-120b` BYO, `openai/gpt-oss-120b` managed). */
+    model?: string;
+    /** Name of the env var holding the provider API key (never persisted). BYO only. */
+    keyEnv?: string;
+    /** reasoning_effort: low | medium | high (default `low`). */
+    effort?: string;
+    /** Output style: plain | report (default `plain`). */
+    style?: string;
+}
+export interface ResolvedOffload {
+    /** True when the offload is usable (endpoint present; for managed, a token too). */
+    enabled: boolean;
+    /** Managed tier (CodeGraph AI, metered) vs BYO endpoint. */
+    managed: boolean;
+    url?: string;
+    model: string;
+    /** Resolved API key / org token (from env, the configured `keyEnv`, or login), if any. */
+    apiKey?: string;
+    /** Where the key/token came from (for `status` display) — never the secret itself. */
+    keySource?: string;
+    effort: string;
+    style: string;
+    timeoutMs: number;
+    maxTokens: number;
+    strip: boolean;
+    debug: boolean;
+    /** Where the endpoint came from — drives `codegraph offload status`. */
+    origin: 'env' | 'config' | 'none';
+}
+/** The persisted offload block (empty object if none). */
+export declare function readOffloadConfig(): OffloadConfig;
+/** Persist (or, with `null`, clear) the offload block, leaving other config keys intact. */
+export declare function writeOffloadConfig(offload: OffloadConfig | null): void;
+/** Merge the persisted config with `CODEGRAPH_OFFLOAD_*` env overrides (env wins). */
+export declare function resolveOffload(env?: NodeJS.ProcessEnv): ResolvedOffload;
+//# sourceMappingURL=config.d.ts.map

package/dist/reasoning/credentials.d.ts

@@ -0,0 +1,5 @@
+/** The stored managed-offload org token, if the machine is logged in. */
+export declare function readOffloadToken(): string | undefined;
+/** Persist (or, with `null`, clear) the managed-offload org token at `0600`. */
+export declare function writeOffloadToken(token: string | null): void;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/reasoning/login.d.ts

@@ -0,0 +1,21 @@
+/** Dashboard base for the device-login endpoints; override for testing via CODEGRAPH_LOGIN_URL. */
+export declare function loginBaseUrl(): string;
+/** The dashboard's response to a device-authorization start request. */
+export interface DeviceStart {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    /** Same URL with the code prefilled, for one-click open. */
+    verification_uri_complete?: string;
+    /** Seconds the CLI should wait between polls. */
+    interval?: number;
+    /** Seconds until the request expires. */
+    expires_in?: number;
+}
+/** Begin a device-authorization request. */
+export declare function startDeviceLogin(): Promise<DeviceStart>;
+/** Poll until the user approves in the browser; resolves with the org token. */
+export declare function pollForToken(deviceCode: string, intervalSec: number, expiresInSec: number): Promise<string>;
+/** Best-effort: open a URL in the default browser. Never throws — the URL is also printed. */
+export declare function openBrowser(url: string): Promise<void>;
+//# sourceMappingURL=login.d.ts.map

package/dist/reasoning/reasoner.d.ts

@@ -0,0 +1,43 @@
+interface SynthArgs {
+    query: string;
+    context: string;
+}
+/** True when a reasoning offload endpoint is configured (env or `~/.codegraph/config.json`). */
+export declare function isOffloadEnabled(): boolean;
+export interface OffloadUsage {
+    plan?: string;
+    allowance?: number;
+    used?: number;
+    overage?: number;
+    remaining?: number;
+    periodEnd?: number;
+    unlimited?: boolean;
+    banned?: boolean;
+    tokensLast30?: number;
+    callsLast30?: number;
+    creditsLast30?: number;
+    models?: string[];
+}
+/**
+ * GET `/v1/usage` from the configured (managed) endpoint → the org's credit
+ * balance/usage, or null on any failure. Drives `codegraph offload status`.
+ */
+export declare function fetchUsage(): Promise<OffloadUsage | null>;
+/**
+ * Strip sections of the explore output addressed to the AGENT (not useful to a
+ * reasoning model): the "Not shown above" pointer list, the completeness signal,
+ * the explore-budget note, the trimmed/truncation notices, and the redundant
+ * "## Exploration:/Found N symbols" header (the query is sent separately). Left
+ * in, some models regurgitate them ("We have 2 explore calls. Let's explore…")
+ * and they add noise. Source code, blast radius, relationships, and flow stay.
+ * Opt-in (`CODEGRAPH_OFFLOAD_STRIP=1`) — default off (it also removes the "Not
+ * shown above" pointers, which can be useful navigation).
+ */
+export declare function stripAgentDirectives(context: string): string;
+/**
+ * Offload reasoning over the retrieved `context` to the configured model and
+ * return its synthesized answer, or null to signal "fall back to local source".
+ */
+export declare function synthesizeOffload({ query, context }: SynthArgs): Promise<string | null>;
+export {};
+//# sourceMappingURL=reasoner.d.ts.map

package/dist/resolution/c-fnptr-synthesizer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * C/C++ function-pointer dispatch synthesis (#932).
+ *
+ * C/C++ polymorphism is the function pointer: a struct carries a fn-pointer
+ * field (`int (*fn)(int)`, or a fn-pointer-typedef field `hook_func func`),
+ * concrete functions are *registered* into it through a table
+ * (`static struct cmd cmds[] = {{"add", cmd_add}, …}`, a designated
+ * `.fn = cmd_add`, or `x->fn = cmd_add`), and the dispatcher calls through it
+ * indirectly (`p->fn(argv)`). Static extraction captures neither the
+ * registration→field binding nor the indirect call, so the dispatcher→handler
+ * edge is missing and `git`'s `run_builtin` looks like it calls nothing, the
+ * hooks in `hook_demo.c` are unreachable, etc.
+ *
+ * This bridges it, keyed by **(struct type, fn-pointer field)**:
+ *   • registrations — a function bound to `S.field` via a positional
+ *     initializer (matched by field index), a designated `.field = fn`, or a
+ *     direct `x.field = fn` / `x->field = fn` assignment;
+ *   • dispatch — `recv->field(…)` / `recv.field(…)` where `recv` resolves to a
+ *     value of struct type `S` (from the enclosing function's params / locals),
+ *     falling back to the field name when it is unique to one struct;
+ *   • field←field propagation — `a->f = b->g` merges `B.g`'s handlers into
+ *     `A.f`, so a generic single-slot hook that is reassigned from a registry
+ *     (the `hook_demo.c` shape: `h->func = found->fn`) still resolves.
+ *
+ * Whole-graph pass after base resolution; all edges are `provenance:'heuristic'`
+ * (`synthesizedBy:'fn-pointer-dispatch'`). High precision via the (type, field)
+ * key + a real-function gate; a project with no fn-pointer dispatch is a no-op.
+ */
+import type { Edge } from '../types';
+import type { QueryBuilder } from '../db/queries';
+import type { ResolutionContext } from './types';
+export declare function cFnPointerDispatchEdges(queries: QueryBuilder, ctx: ResolutionContext): Edge[];
+//# sourceMappingURL=c-fnptr-synthesizer.d.ts.map

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

@@ -3,7 +3,12 @@ import type { ResolutionContext } from './types';
 /**
  * Synthesize dispatcher→callback edges (field observers + EventEmitters +
  * React re-render + JSX children + Vue templates + SvelteKit load + RN event
- * channel + Fabric native-impl + MyBatis Java↔XML + Gin middleware chain).
+ * channel + Fabric native-impl + MyBatis Java↔XML + Gin middleware chain +
+ * Redux-thunk dispatch chain + object-literal registry dispatch + RTK Query
+ * generated-hook → endpoint + Pinia useStore().action() + Vuex string dispatch +
+ * Celery task .delay()/.apply_async() → task body + Spring publishEvent → @EventListener +
+ * MediatR Send/Publish → IRequestHandler/INotificationHandler +
+ * Sidekiq Worker.perform_async → #perform + Laravel event(new X) → listener handle).
  * Returns the count added. Never throws into indexing — callers wrap in try/catch.
  */
 export declare function synthesizeCallbackEdges(queries: QueryBuilder, ctx: ResolutionContext): number;

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

@@ -0,0 +1,41 @@
+/**
+ * GoFrame Framework Resolver (route metadata) — issue #747.
+ *
+ * GoFrame's "standard router" binds routes reflectively, so there is no literal
+ * path string at a `.GET("/x", handler)` call site and no static edge from a
+ * route to the controller method that serves it. The structural facts live in
+ * two places, joined only at runtime by GoFrame:
+ *
+ *   // api/user/v1/user_sign_in.go — the route lives in a struct tag on the request type
+ *   type SignInReq struct {
+ *       g.Meta `path:"/user/sign-in" method:"post" tags:"UserService" summary:"…"`
+ *       …
+ *   }
+ *   // internal/controller/user/user_v1_sign_in.go — the handler takes *that* request type
+ *   func (c *ControllerV1) SignIn(ctx context.Context, req *v1.SignInReq) (res *v1.SignInRes, err error)
+ *   // internal/cmd/cmd.go — reflective binding (no path, no handler name)
+ *   group.Bind(user.NewV1())
+ *
+ * This resolver handles the FIRST half: it reads the `g.Meta` struct tag on a
+ * request type into a `route` node (`POST /user/sign-in`). The route → handler
+ * EDGE is the genuinely reflective part — the method name is NOT derivable from
+ * the request type (`DeptSearchReq` is served by `List`, `DeptAddReq` by `Add`),
+ * so the only reliable join is the request type appearing in the method's
+ * parameter signature. That whole-graph join is done by the companion
+ * `goframeRouteEdges` synthesizer, which reads the request type back out of the
+ * route node's qualifiedName.
+ *
+ * Honesty note: the route node carries the `g.Meta` path verbatim. The group
+ * prefix from `s.Group("/api", …)` / nested `group.Group("/v1", …)` is applied
+ * by reflective `Bind` at runtime and is deliberately NOT reconstructed here —
+ * the discriminating, structural part is the per-route path + method.
+ */
+import { FrameworkResolver } from '../types';
+/** Marker embedded in a route node's qualifiedName so the synthesizer can read
+ *  back the request type to join on. The value after it is the package-qualified
+ *  request type (`cash.ListReq`) — the package disambiguates the many identical
+ *  bare names (`ListReq`, `GetReq`) a large app defines, one per module. Falls
+ *  back to the bare type when no `package` declaration is found. */
+export declare const GOFRAME_ROUTE_MARKER = "::goframe-route:";
+export declare const goframeResolver: FrameworkResolver;
+//# sourceMappingURL=goframe.d.ts.map

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

@@ -39,6 +39,7 @@ export { railsResolver } from './ruby';
 export { springResolver } from './java';
 export { playResolver } from './play';
 export { goResolver } from './go';
+export { goframeResolver } from './goframe';
 export { rustResolver } from './rust';
 export { aspnetResolver } from './csharp';
 export { swiftUIResolver, uikitResolver, vaporResolver } from './swift';

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

@@ -0,0 +1,28 @@
+/**
+ * GoFrame route → controller-method dispatch synthesis (#747).
+ *
+ * GoFrame binds routes reflectively (`group.Bind(user.NewV1())`), so the route
+ * declared in a request type's `g.Meta` tag has no static edge to the method
+ * that serves it. The `goframeResolver` extract pass turns each `g.Meta` into a
+ * `route` node carrying its request type in the qualifiedName; this whole-graph
+ * pass closes the loop by joining each route to its handler.
+ *
+ * The join key is the REQUEST TYPE, not the method name — GoFrame method names
+ * are free (`DeptSearchReq` is served by `List`, `DeptAddReq` by `Add`), so the
+ * only reliable link is the request type appearing in the handler's parameter
+ * signature:
+ *
+ *   func (c *sysDeptController) Add(ctx context.Context, req *system.DeptAddReq) (…)
+ *                                                              ^^^^^^^^^^^^^^^^  the join
+ *
+ * Go method nodes already carry that signature, so no source re-read is needed.
+ * Each synthesized edge is `kind:'calls'`, `provenance:'heuristic'`,
+ * `metadata.synthesizedBy:'goframe-route'` — a reflective-dispatch bridge, so
+ * `codegraph_explore` surfaces it as a dynamic hop rather than a literal call,
+ * and the handler's callers list the route that reaches it. A project with no
+ * GoFrame routes is a no-op.
+ */
+import type { Edge } from '../types';
+import type { ResolutionContext } from './types';
+export declare function goframeRouteEdges(ctx: ResolutionContext): Edge[];
+//# sourceMappingURL=goframe-synthesizer.d.ts.map

package/dist/resolution/strip-comments.d.ts

@@ -22,6 +22,6 @@
  * `path(...)`, `Route::get(...)`, `app.get(...)` style patterns that
  * framework extractors scan for.
  */
-export type CommentLang = 'python' | 'javascript' | 'typescript' | 'php' | 'ruby' | 'java' | 'csharp' | 'swift' | 'go' | 'rust';
+export type CommentLang = 'python' | 'javascript' | 'typescript' | 'php' | 'ruby' | 'java' | 'csharp' | 'swift' | 'go' | 'rust' | 'c' | 'cpp';
 export declare function stripCommentsForRegex(content: string, lang: CommentLang): string;
 //# sourceMappingURL=strip-comments.d.ts.map

package/dist/sync/watcher.d.ts

@@ -30,6 +30,16 @@
  * events are dropped before any sync is scheduled. Either way the watcher's
  * scope matches the indexer's (#276 / #407).
  */
+import * as fs from 'fs';
+/**
+ * Indirection over `fs.watch` so tests can inject a fake that throws or emits
+ * `EMFILE`/`ENFILE` deterministically (real watch-resource exhaustion can't be
+ * provoked reliably, and `fs.watch` is a non-configurable property so it can't
+ * be spied). Production always uses the real `fs.watch`.
+ */
+type WatchFn = typeof fs.watch;
+/** @internal Test-only seam to inject a fake fs.watch implementation. */
+export declare function __setFsWatchForTests(fn: WatchFn | null): void;
 /**
  * Options for the file watcher
  */
@@ -51,6 +61,14 @@ export interface WatchOptions {
      * Callback when a sync errors (for logging/diagnostics).
      */
     onSyncError?: (error: Error) => void;
+    /**
+     * Callback fired ONCE when live watching degrades permanently and auto-sync
+     * is disabled — OS watch-resource exhaustion (EMFILE/ENFILE), or a write lock
+     * held past the retry budget. The string is an actionable, human-readable
+     * reason. Lets a host (MCP server, daemon, CLI) tell the user that the index
+     * will no longer auto-update instead of silently serving stale results.
+     */
+    onDegraded?: (reason: string) => void;
     /**
      * Test-only. When true, `start()` installs NO OS-level fs.watch — the
      * watcher is "inert" and only the {@link __emitWatchEventForTests} /
@@ -111,6 +129,22 @@ export declare class FileWatcher {
     private dirWatchers;
     /** Set once the per-directory watch cap is hit, so we log only once. */
     private dirCapWarned;
+    /**
+     * Set once the Linux inotify watch limit (ENOSPC) is hit. Double duty: we
+     * warn only once, AND we stop attempting new directory watches for the rest
+     * of the session — once the kernel budget is exhausted every further
+     * `inotify_add_watch` fails too, so trying the rest of the tree is pure
+     * waste. NON-fatal (does not degrade): installed watches keep working.
+     */
+    private inotifyLimitWarned;
+    /**
+     * One-way latch: the reason live watching was permanently disabled at runtime
+     * (watch-resource exhaustion, or lock contention past the retry budget), or
+     * null while healthy. Set by {@link degrade}; cleared only by a fresh start().
+     */
+    private degradedReason;
+    /** Consecutive lock-contention retries for watcher-triggered syncs. */
+    private lockRetryCount;
     /** Test-only inert mode: started, but with no OS watcher installed. */
     private inert;
     private debounceTimer;
@@ -152,6 +186,7 @@ export declare class FileWatcher {
     private readonly syncFn;
     private readonly onSyncComplete?;
     private readonly onSyncError?;
+    private readonly onDegraded?;
     private readonly inertForTests;
     constructor(projectRoot: string, syncFn: () => Promise<{
         filesChanged: number;
@@ -211,6 +246,31 @@ export declare class FileWatcher {
      * dir-only ignore rule like `build/` matches.
      */
     private shouldIgnoreDir;
+    /**
+     * Permanently disable live watching after a terminal runtime failure
+     * (watch-resource exhaustion, or lock contention past the retry budget).
+     * Idempotent: logs one actionable warning, fires {@link WatchOptions.onDegraded}
+     * once, and stops the watcher. A subsequent start() clears the latch.
+     */
+    private degrade;
+    /**
+     * Warn ONCE that the Linux inotify watch budget is exhausted (ENOSPC), and
+     * stop adding new watches for the rest of this session — every further
+     * `inotify_add_watch` would fail too, so walking the rest of the tree is
+     * waste. Unlike {@link degrade} this is NON-fatal: the watches already
+     * installed keep firing, and `codegraph sync` covers the unwatched remainder.
+     * The message names the kernel knob to raise (`fs.inotify.max_user_watches`).
+     */
+    private warnInotifyLimit;
+    /**
+     * Whether live watching has degraded permanently (until the next start()).
+     * Distinct from {@link isActive}: a degraded watcher is inactive, but an
+     * inactive watcher is not necessarily degraded (it may simply be stopped or
+     * never started). Hosts use this to tell the user auto-sync is off.
+     */
+    isDegraded(): boolean;
+    /** The reason live watching degraded, or null if it is healthy. */
+    getDegradedReason(): string | null;
     /**
      * Stop watching for file changes.
      */
@@ -238,9 +298,15 @@ export declare class FileWatcher {
      */
     waitUntilReady(timeoutMs?: number): Promise<void>;
     /**
-     * Schedule a debounced sync.
+     * Schedule a normal debounced sync after a source edit.
      */
     private scheduleSync;
+    /**
+     * Schedule a retry after a recoverable sync failure (lock contention). Kept
+     * separate from {@link scheduleSync} so prolonged contention backs off
+     * exponentially instead of hammering the lock every debounce cycle.
+     */
+    private scheduleRetrySync;
     /**
      * Flush pending changes by running sync.
      *
@@ -280,4 +346,5 @@ export declare class FileWatcher {
  * test runtime, where the registry is intentionally not populated).
  */
 export declare function __emitWatchEventForTests(projectRoot: string, relPath: string): boolean;
+export {};
 //# sourceMappingURL=watcher.d.ts.map

package/dist/telemetry/index.d.ts

@@ -28,8 +28,6 @@ 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,
@@ -39,7 +37,6 @@ export declare function recordIndexEvent(cg: {
     getStats(): {
         filesByLanguage: Record<string, number>;
     };
-    getBackend(): string;
 }, result: {
     filesIndexed: number;
     durationMs: number;

package/dist/utils.d.ts

@@ -57,12 +57,25 @@ export declare function isConfigLeafNode(node: {
  * (codegraph_node `includeCode`, codegraph_explore source) go through here, so
  * this is the chokepoint that keeps out-of-root file contents from leaking.
  *
+ * `allowSymlinkEscape` waives **only** the realpath-escape rejection (the
+ * lexical `../` guard still applies) for the INDEXING read path. The directory
+ * walk deliberately descends into in-root symlinks whose targets live outside
+ * the root (e.g. a `game/` symlink in a Dota custom-game tree, #935); discovery
+ * and the reader must agree, or every file the walk enumerated fails to index.
+ * Indexing only reads paths it just discovered, into a local index — it never
+ * serves them to an agent, so this does not widen the #527 leak surface. The
+ * content-serving sinks must never pass this flag.
+ *
  * @param projectRoot - The project root directory
  * @param filePath - The (relative or absolute) file path to validate
+ * @param options.allowSymlinkEscape - Follow in-root symlinks out of the root
+ *   (indexing read path only); defaults to the strict, leak-safe behavior.
  * @returns The resolved absolute path (realpath when it exists), or null if it
  *   escapes the root
  */
-export declare function validatePathWithinRoot(projectRoot: string, filePath: string): string | null;
+export declare function validatePathWithinRoot(projectRoot: string, filePath: string, options?: {
+    allowSymlinkEscape?: boolean;
+}): string | null;
 /**
  * Validate that a path is a safe project root directory.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colbymchenry/codegraph",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Local-first code intelligence for AI agents (MCP). Self-contained — bundles its own runtime.",
   "bin": {
     "codegraph": "npm-shim.js"
@@ -15,12 +15,12 @@
     "./package.json": "./package.json"
   },
   "optionalDependencies": {
-    "@colbymchenry/codegraph-darwin-arm64": "1.0.0",
-    "@colbymchenry/codegraph-darwin-x64": "1.0.0",
-    "@colbymchenry/codegraph-linux-arm64": "1.0.0",
-    "@colbymchenry/codegraph-linux-x64": "1.0.0",
-    "@colbymchenry/codegraph-win32-arm64": "1.0.0",
-    "@colbymchenry/codegraph-win32-x64": "1.0.0"
+    "@colbymchenry/codegraph-darwin-arm64": "1.1.0",
+    "@colbymchenry/codegraph-darwin-x64": "1.1.0",
+    "@colbymchenry/codegraph-linux-arm64": "1.1.0",
+    "@colbymchenry/codegraph-linux-x64": "1.1.0",
+    "@colbymchenry/codegraph-win32-arm64": "1.1.0",
+    "@colbymchenry/codegraph-win32-x64": "1.1.0"
   },
   "files": [
     "npm-shim.js",