@colbymchenry/codegraph 0.9.9 → 1.0.1

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;

package/dist/upgrade/index.d.ts

@@ -0,0 +1,132 @@
+/**
+ * `codegraph upgrade`
+ *
+ * Self-update for the CLI, whatever way it was installed:
+ *
+ *   - **bundle** — the self-contained runtime+app installed by `install.sh`
+ *     (Linux/macOS) or `install.ps1` (Windows). Upgrading re-runs the SAME
+ *     canonical installer script (single source of truth) so the download /
+ *     version-resolution / PATH logic never drifts between first-install and
+ *     upgrade.
+ *   - **npm** — installed via `npm i -g @colbymchenry/codegraph`. Upgrading
+ *     shells out to npm.
+ *   - **npx** — ephemeral; nothing to upgrade (next `npx` fetches latest).
+ *   - **source** — a git checkout running its own `dist/`; `git pull` + rebuild.
+ *
+ * Detection is structural (see `detectInstallMethod`): a bundle carries a
+ * vendored `node` binary and a `bin/codegraph` launcher next to its `lib/`, so
+ * we can recognize it from the running file's path without a marker file.
+ *
+ * Windows wrinkle: a running `node.exe` is locked and can't be deleted, so the
+ * bundle's `current\` dir can't be overwritten in place by the process doing
+ * the upgrade. We therefore spawn a DETACHED helper that waits for this
+ * process to exit (releasing the lock), then runs `install.ps1`. This is the
+ * conventional Windows self-update dance (rustup/nvm-windows do the same).
+ */
+export declare const REPO = "colbymchenry/codegraph";
+export declare const NPM_PACKAGE = "@colbymchenry/codegraph";
+export declare const INSTALL_SH_URL = "https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh";
+export type InstallMethod = {
+    kind: 'bundle';
+    os: 'unix' | 'windows';
+    bundleRoot: string;
+    installDir: string | null;
+} | {
+    kind: 'npm';
+    scope: 'global' | 'local';
+} | {
+    kind: 'npx';
+} | {
+    kind: 'source';
+    root: string;
+} | {
+    kind: 'unknown';
+    reason: string;
+};
+export interface DetectInput {
+    /** `__filename` of the running CLI module — `<…>/dist/bin/codegraph.js`. */
+    filename: string;
+    platform: NodeJS.Platform;
+    cwd: string;
+    /** Injectable existence probe (defaults to fs.existsSync) — for tests. */
+    exists?: (p: string) => boolean;
+}
+/**
+ * Where the bundle installer keeps its install root, derived from the bundle
+ * dir so an upgrade reuses a custom `CODEGRAPH_INSTALL_DIR`. Returns null when
+ * the layout isn't the one the installer creates (then the installer falls
+ * back to its own default).
+ *
+ *   unix:    <installDir>/versions/<vX.Y.Z>   (bundleRoot)  → <installDir>
+ *   windows: <installDir>\current             (bundleRoot)  → <installDir>
+ */
+export declare function deriveInstallDir(bundleRoot: string, os: 'unix' | 'windows', exists: (p: string) => boolean): string | null;
+export declare function detectInstallMethod(input: DetectInput): InstallMethod;
+export interface Semver {
+    major: number;
+    minor: number;
+    patch: number;
+    pre: string | null;
+}
+export declare function parseSemver(version: string): Semver | null;
+/** Returns >0 if a>b, <0 if a<b, 0 if equal. Throws on unparseable input. */
+export declare function compareVersions(a: string, b: string): number;
+export declare function isUpdateAvailable(current: string, latest: string): boolean;
+/** `0.9.9` / `v0.9.9` → `v0.9.9` (release tags are v-prefixed). */
+export declare function normalizeVersion(v: string): string;
+/** Strip a leading `v`: `v0.9.9` → `0.9.9`. */
+export declare function stripV(v: string): string;
+/**
+ * Parse the release tag out of the `Location` header GitHub returns for
+ * `/releases/latest` → `…/releases/tag/v0.9.9`. Pure so it's unit-tested.
+ */
+export declare function parseLatestTagFromLocation(location: string | undefined): string | null;
+/**
+ * Resolve the latest release tag (e.g. `v0.9.9`).
+ *
+ * Primary: read the redirect `Location` from `github.com/<repo>/releases/latest`
+ * — same trick install.sh uses, because the unauthenticated GitHub API is
+ * rate-limited to 60 req/h/IP and 403s on shared/cloud hosts (issue #325). The
+ * redirect has no such limit. Fall back to the API only if the redirect can't
+ * be read.
+ */
+export declare function resolveLatestVersion(repo?: string, timeoutMs?: number): Promise<string>;
+export interface UpgradeOptions {
+    /** Pin a specific version (positional arg or CODEGRAPH_VERSION). */
+    version?: string;
+    /** Report current vs latest, don't change anything. */
+    check?: boolean;
+    /** Reinstall even if already on the resolved version. */
+    force?: boolean;
+}
+/** Injectable side-effects so the orchestrator stays unit-testable. */
+export interface UpgradeDeps {
+    currentVersion: string;
+    method: InstallMethod;
+    resolveLatest: (pin?: string) => Promise<string>;
+    /** Run a command inheriting stdio; returns its exit code (-1 = spawn failed). */
+    run: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => number;
+    hasCommand: (cmd: string) => boolean;
+    log: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    platform: NodeJS.Platform;
+}
+/** The honest, additive re-index reminder shown after a successful upgrade. */
+export declare function reindexAdvisory(): string;
+/**
+ * Returns the process exit code (0 = success / nothing to do, 1 = failure).
+ */
+export declare function runUpgrade(opts: UpgradeOptions, deps: UpgradeDeps): Promise<number>;
+/** Build the in-place Windows upgrade script (exported for unit-testing). */
+export declare function buildWindowsUpgradeScript(bundleRoot: string, version: string, arch: string): string;
+/**
+ * True if `cmd` resolves to an executable on PATH. A pure-Node PATH scan — NOT
+ * a spawned `command -v`/`which`: `command` is a shell builtin (no standalone
+ * binary on Debian, though macOS ships one), and `which` isn't guaranteed
+ * present on minimal images, so spawning either is unreliable. Scanning PATH
+ * ourselves behaves identically on every platform.
+ */
+export declare function hasCommand(cmd: string): boolean;
+export declare function defaultRun(cmd: string, args: string[], env?: NodeJS.ProcessEnv): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/utils.d.ts

@@ -29,12 +29,38 @@
  * ```
  */
 /**
- * Validate that a resolved file path stays within the project root.
- * Prevents path traversal attacks (e.g. node.filePath = "../../etc/passwd").
+ * Config "languages" whose nodes are pure key/value DATA lifted from a config
+ * file (e.g. Spring `application.{yml,properties}`), not source code.
+ */
+export declare const CONFIG_LEAF_LANGUAGES: ReadonlySet<string>;
+/**
+ * A config-leaf node is a single key lifted out of a pure config/data file —
+ * `kind: 'constant'` in a {@link CONFIG_LEAF_LANGUAGES} language. Its on-disk
+ * line is `key = <value>`, and that value is routinely a secret (DB password,
+ * API key, JDBC URL with embedded creds). CodeGraph must surface the KEY only
+ * and never read/return the value, or it pushes secrets into agent context
+ * unbidden — the value isn't needed for resolution, and an agent that genuinely
+ * needs it can read the file directly. (#383)
+ */
+export declare function isConfigLeafNode(node: {
+    kind: string;
+    language?: string;
+}): boolean;
+/**
+ * Validate that a file path stays within the project root, resolving symlinks.
+ *
+ * Two layers: a cheap lexical check that catches `../` traversal, then a
+ * realpath check that catches symlink escapes — an in-repo symlink whose
+ * logical path is inside the root but whose real target points outside it
+ * (issue #527). A symlink that stays within the root is still allowed, so
+ * legitimate in-tree symlinks keep working. Both content-serving read sinks
+ * (codegraph_node `includeCode`, codegraph_explore source) go through here, so
+ * this is the chokepoint that keeps out-of-root file contents from leaking.
  *
  * @param projectRoot - The project root directory
- * @param filePath - The relative file path to validate
- * @returns The resolved absolute path, or null if it escapes the root
+ * @param filePath - The (relative or absolute) file path to validate
+ * @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;
 /**
@@ -48,26 +74,6 @@ export declare function validatePathWithinRoot(projectRoot: string, filePath: st
  * @returns An error message if invalid, or null if valid
  */
 export declare function validateProjectPath(dirPath: string): string | null;
-/**
- * Check if a file path resolves to a location within the given root directory.
- *
- * Prevents path traversal attacks by ensuring the resolved absolute path
- * starts with the resolved root path. Handles '..' sequences, symlink-like
- * relative paths, and platform-specific separators.
- *
- * @param filePath - The path to check (can be relative or absolute)
- * @param rootDir - The root directory that filePath must stay within
- * @returns true if filePath resolves to a location within rootDir
- */
-export declare function isPathWithinRoot(filePath: string, rootDir: string): boolean;
-/**
- * Like isPathWithinRoot but also resolves symlinks via fs.realpathSync.
- *
- * This catches symlink escapes where the logical path appears to be within
- * root but the real path on disk points elsewhere. Falls back to logical
- * path checking if realpath resolution fails (e.g. broken symlink).
- */
-export declare function isPathWithinRootReal(filePath: string, rootDir: string): boolean;
 /**
  * Safely parse JSON with a fallback value.
  * Prevents crashes from corrupted database metadata.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colbymchenry/codegraph",
-  "version": "0.9.9",
+  "version": "1.0.1",
   "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": "0.9.9",
-    "@colbymchenry/codegraph-darwin-x64": "0.9.9",
-    "@colbymchenry/codegraph-linux-arm64": "0.9.9",
-    "@colbymchenry/codegraph-linux-x64": "0.9.9",
-    "@colbymchenry/codegraph-win32-arm64": "0.9.9",
-    "@colbymchenry/codegraph-win32-x64": "0.9.9"
+    "@colbymchenry/codegraph-darwin-arm64": "1.0.1",
+    "@colbymchenry/codegraph-darwin-x64": "1.0.1",
+    "@colbymchenry/codegraph-linux-arm64": "1.0.1",
+    "@colbymchenry/codegraph-linux-x64": "1.0.1",
+    "@colbymchenry/codegraph-win32-arm64": "1.0.1",
+    "@colbymchenry/codegraph-win32-x64": "1.0.1"
   },
   "files": [
     "npm-shim.js",