@aroman22/codegraph-vba 1.5.2 → 1.6.0

package/dist/resolution/index.d.ts

@@ -6,6 +6,7 @@
 import { UnresolvedReference, Edge } from '../types';
 import { QueryBuilder } from '../db/queries';
 import { UnresolvedRef, ResolvedRef, ResolutionResult } from './types';
+import { type MaybeYield } from './cooperative-yield';
 export * from './types';
 /**
  * Reference Resolver
@@ -27,6 +28,9 @@ export declare class ReferenceResolver {
     private nameCache;
     private lowerNameCache;
     private qualifiedNameCache;
+    private fileLinesCache;
+    private methodMatchCache;
+    private nodesByKindCache;
     private knownNames;
     private knownFiles;
     private cachesWarmed;
@@ -54,10 +58,21 @@ export declare class ReferenceResolver {
      * We cache the set of known symbol names for fast pre-filtering.
      */
     warmCaches(): void;
+    /**
+     * warmCaches for the async resolution entry points: streams the distinct
+     * name set with periodic yields instead of one synchronous `.all()`. On a
+     * multi-million-node index the DISTINCT scan is a solid multi-second block
+     * (measured up to 28s inside `codegraph sync` on the Linux kernel index),
+     * long enough to matter to the #850 watchdog on slower hardware. Same
+     * result, same memory — only the event loop keeps turning.
+     */
+    warmCachesYielding(onYield: MaybeYield): Promise<void>;
     /**
      * Clear internal caches
      */
     clearCaches(): void;
+    /** `readFile` through the LRU content cache (null = read failed, also cached). */
+    private readFileCached;
     /**
      * Create the resolution context
      */
@@ -90,6 +105,16 @@ export declare class ReferenceResolver {
      * Resolve and persist edges to database
      */
     resolveAndPersist(unresolvedRefs: UnresolvedReference[], onProgress?: (current: number, total: number) => void): ResolutionResult;
+    /**
+     * Yielding counterpart of {@link resolveAndPersist} for a caller-supplied
+     * ref list — used by sync's failed-ref retry pass (#1240). Same persistence
+     * semantics: resolved refs become edges and their rows are deleted;
+     * still-unresolvable refs are (re-)marked failed (a no-op for rows already
+     * in that status). Yields per-ref because sync can run on the daemon's
+     * liveness-watchdog thread (#850/#1091) and a retry set is unbounded when
+     * a large edit lands many popular symbol names at once.
+     */
+    resolveAndPersistListYielding(refs: UnresolvedReference[]): Promise<ResolutionResult>;
     /**
      * Second resolution pass for chained static-factory / fluent calls whose
      * chained method is defined on a SUPERTYPE the receiver's type conforms to —
@@ -103,7 +128,21 @@ export declare class ReferenceResolver {
      * (re-resolving an already-resolved ref is a no-op since it's been deleted).
      * Returns the number of newly-created edges.
      */
-    resolveChainedCallsViaConformance(): number;
+    resolveChainedCallsViaConformance(): Promise<number>;
+    /**
+     * Resolve one batch with a yield checkpoint between EVERY ref so the #850
+     * liveness heartbeat can fire on a slow/dense batch (#1091). The checkpoint
+     * granularity is per-ref — not per-N-refs — because per-ref cost is unbounded
+     * in the worst case (a collision-heavy method name whose candidate set misses
+     * the LRU re-fetches tens of thousands of rows): any fixed N multiplies that
+     * worst case into the watchdog window, which is how v1.2.0 still got killed
+     * at "Resolving refs" on large Java monorepos (#1122). `maybeYield()` is a
+     * ~ns time check when under budget, so per-ref checkpoints cost nothing.
+     * Behaviourally identical to `resolveAll(batch)`: `warmCaches()` is
+     * idempotent (guarded) and `resolveOne` is independent per ref, so yielding
+     * between refs changes only timing, never which edges get created.
+     */
+    private resolveBatchYielding;
     /**
      * Resolve and persist in batches to keep memory bounded.
      * Processes unresolved references in chunks, persisting edges and cleaning
@@ -152,6 +191,29 @@ export declare class ReferenceResolver {
      * through to name-matching).
      */
     private resolveRazorUsing;
+    /**
+     * Resolve a CFML inheritance reference written as a component path (#1152).
+     * Two forms exist in real code:
+     *
+     * - Dotted: `extends="coldbox.system.web.Controller"` — dots are directory
+     *   separators from the webroot or a CFML mapping. Mappings live in server
+     *   config / Application.cfc, so the leading segments may not exist in the
+     *   repo at all (in the coldbox repo itself the path is `system/web/
+     *   Controller.cfc` — the `coldbox.` root IS the repo). Matched by final
+     *   segment (the class), corroborated right-to-left against the candidate's
+     *   parent directories.
+     * - Relative: `extends="../base"` / `extends="./base"` (the FW/1 style) —
+     *   resolved against the referencing file's own directory.
+     *
+     * Conservative by design: a candidate needs at least one corroborating
+     * directory segment (a dotted path whose only same-named class sits in an
+     * unrelated directory is almost always an out-of-repo library supertype —
+     * mxunit/testbox/coldbox-as-dependency), and a corroboration tie yields no
+     * edge. Directory comparison is case-insensitive (CFML path resolution is);
+     * the class segment itself is matched exactly, which real code satisfies —
+     * dotted paths are written to match the on-disk file name.
+     */
+    private resolveCfmlComponentPath;
     /**
      * Resolve a `this.<member>` function-as-value reference (#756/#808) to the
      * ENCLOSING CLASS's own member — never a same-named symbol elsewhere. The
@@ -172,7 +234,7 @@ export declare class ReferenceResolver {
      * Mirrors resolveChainedCallsViaConformance's lifecycle. Returns the number
      * of newly-created edges.
      */
-    resolveDeferredThisMemberRefs(): number;
+    resolveDeferredThisMemberRefs(): Promise<number>;
     /**
      * VBA #12b — post-extraction resolver pass (vba-graph-connectivity-fixes,
      * issue #12). Repoints qualified call-stub `calls` edges (tagged

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

@@ -3,6 +3,7 @@
  *
  * Handles symbol name matching for reference resolution.
  */
+import { Node } from '../types';
 import { UnresolvedRef, ResolvedRef, ResolutionContext } from './types';
 /**
  * Try to resolve a path-like reference (e.g., "snippets/drawer-menu.liquid")
@@ -47,6 +48,27 @@ export declare function matchByExactName(ref: UnresolvedRef, context: Resolution
  * Try to resolve by qualified name
  */
 export declare function matchByQualifiedName(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
+/**
+ * When a symbol name is ambiguous across files, prefer the candidate(s) declared
+ * in the call site's own file, keeping the rest in their original order (#1079).
+ * A same-file definition is the strongest language-agnostic signal for which of
+ * several same-named symbols a call means; without it, resolution collapses onto
+ * whichever was indexed first, so a call in `b/svc` wrongly targets `a/svc`.
+ * No-op when there are <2 candidates or none share the call site's file.
+ */
+export declare function preferCallSiteFile(nodes: Node[], callSiteFile: string): Node[];
+export declare function resolveMethodOnType(typeName: string, methodName: string, ref: UnresolvedRef, context: ResolutionContext, confidence: number, resolvedBy: ResolvedRef['resolvedBy'], 
+/**
+ * Optional FQN that identifies WHICH class declaration `typeName`
+ * refers to in the caller's file. When multiple candidates share
+ * the same qualifiedName (`FooConverter::convert` in both
+ * `dao/converter/` and `service/converter/`), the FQN's
+ * file-path-suffix picks the right one — the disambiguation
+ * signal Java imports carry but the call site doesn't (#314).
+ */
+preferredFqn?: string, 
+/** Recursion guard for the supertype/conformance walk. */
+depth?: number): 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
@@ -86,8 +108,5 @@ export declare function matchMethodCall(ref: UnresolvedRef, context: ResolutionC
  * Fuzzy match - last resort with lower confidence
  */
 export declare function matchFuzzy(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
-/**
- * Match all strategies in order of confidence
- */
 export declare function matchReference(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
 //# sourceMappingURL=name-matcher.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' | 'c' | 'cpp';
+export type CommentLang = 'python' | 'javascript' | 'typescript' | 'php' | 'ruby' | 'java' | 'csharp' | 'swift' | 'go' | 'rust' | 'c' | 'cpp' | 'erlang';
 export declare function stripCommentsForRegex(content: string, lang: CommentLang): string;
 //# sourceMappingURL=strip-comments.d.ts.map

package/dist/resolution/types.d.ts

@@ -66,10 +66,39 @@ export interface ResolutionContext {
     getNodesByQualifiedName(qualifiedName: string): Node[];
     /** Get all nodes of a kind */
     getNodesByKind(kind: Node['kind']): Node[];
+    /**
+     * Stream nodes of a kind one at a time instead of materializing (and, unlike
+     * `getNodesByKind`, without populating the resolver's per-kind array cache).
+     * For unbounded kinds (`function`, `method`, `struct`) on a symbol-dense
+     * project the full array is gigabytes — the dynamic-edge synthesizers must
+     * use this so their memory stays O(1) in node count (#610, #1212). Optional
+     * so minimal test contexts compile; callers fall back to getNodesByKind.
+     */
+    iterateNodesByKind?(kind: Node['kind']): IterableIterator<Node>;
     /** Check if a file exists */
     fileExists(filePath: string): boolean;
     /** Read file content */
     readFile(filePath: string): string | null;
+    /**
+     * `readFile(filePath)` split into lines, LRU-cached per file. Receiver-type
+     * inference scans source lines for EVERY `receiver.method()` ref; splitting
+     * the whole file per ref made that O(refs-in-file × file-size) — ~20% of
+     * total index CPU on a Java-heavy repo and a driver of the #1122 watchdog
+     * kill on large ones. Optional so external/test contexts compile without it;
+     * callers fall back to splitting `readFile` themselves.
+     */
+    getFileLines?(filePath: string): string[] | null;
+    /**
+     * The method-definition nodes matching `typeName::methodName` in `language` —
+     * exactly `resolveMethodOnType`'s kind/language/qualifiedName-suffix filter,
+     * LRU-cached per (language, type, method). The uncached path re-fetches every
+     * node sharing the METHOD name (unbounded — tens of thousands on a collision-
+     * heavy Java repo) and re-scans it per ref, the dominant term in the #1122
+     * watchdog kill. Cached entries hold only the small filtered result; per-ref
+     * disambiguation (import FQN, call-site file) stays in the caller so a cached
+     * entry is valid from any call site. Optional for external/test contexts.
+     */
+    getMethodMatches?(typeName: string, methodName: string, language: Language): Node[];
     /** Get project root */
     getProjectRoot(): string;
     /** Get all files */

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

@@ -26,6 +26,16 @@
 export interface WorkspacePackages {
     /** Member package `name` → directory relative to projectRoot (posix). */
     byName: Map<string, string>;
+    /**
+     * Member package `name` → its declared ENTRY FILE relative to projectRoot
+     * (posix), when the member's manifest names one (ohpm's oh-package.json5
+     * `"main": "Index.ets"`). Lets a bare `import { X } from "data"` resolve to
+     * the member's real barrel even when it doesn't follow an index-file
+     * convention — and independent of the CONSUMER's language (a `.ts` file
+     * importing an `.ets` barrel resolves without `.ets` in the TS candidate
+     * list). Absent for npm/pnpm members (their index conventions cover it).
+     */
+    entryByName?: Map<string, string>;
 }
 /**
  * Load workspace member packages for `projectRoot`. Returns `null` when

package/dist/search/identifier-segments.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Identifier-segment utilities for the prompt hook's graph-derived gate
+ * (name_segment_vocab): symbol names split into the words a human would use
+ * for them in prose, and prompt prose normalized into candidate words to look
+ * those segments up with.
+ *
+ * "OrderStateMachine" → order / state / machine — so the French prompt
+ * "comment marche la state machine des commandes ?" (or any language's prose
+ * naming the concept in Latin script) can be verified against the graph
+ * without a keyword list ever knowing the words. The FTS index can't serve
+ * this — its tokenizer keeps camelCase names as single tokens — which is why
+ * segments are materialized at index time instead (see schema.sql,
+ * name_segment_vocab).
+ */
+/**
+ * Split a symbol or file name into lowercase word segments.
+ *
+ * Handles camelCase / PascalCase (inner lower→Upper), acronym runs
+ * ("HTMLParser" → html/parser), snake_case / kebab-case / dotted file names
+ * (non-alphanumerics separate), and keeps digits glued to their word
+ * ("base64Encode" → base64/encode). Digit-only fragments are dropped.
+ */
+export declare function splitIdentifierSegments(name: string): string[];
+/**
+ * Normalize a prose word for segment lookup: lowercase + strip diacritics
+ * (NFD, drop combining marks), so "références" matches the segment
+ * "references" and "résolution" matches "resolution". Identifier segments are
+ * overwhelmingly ASCII, so this is what buys Latin-script languages their
+ * cross-lingual reach on loanwords.
+ */
+export declare function normalizeProseWord(word: string): string;
+/**
+ * Candidate words from a prompt for segment-vocabulary lookup, in order of
+ * appearance: Unicode letter/digit runs, normalized via
+ * {@link normalizeProseWord}, length-bounded, digit-only dropped,
+ * {@link ENGLISH_PROSE_STOPWORDS} dropped, deduped, capped. Everything that
+ * survives is judged per-repo by the rarity and co-occurrence rules in
+ * CodeGraph.getSegmentMatches — there is no domain-word list.
+ */
+export declare function extractProseCandidates(prompt: string): string[];
+/**
+ * Lookup variants for a prose word: the word itself plus light plural folding
+ * ("services" → service, "dependencies" → dependencie/dependency is NOT
+ * attempted — only a trailing s/es strip), so common plurals still hit their
+ * singular segment. Returned variants map back to the same original word.
+ *
+ * The strips are keyed on English plural spelling (#1145), in three classes:
+ * - UNAMBIGUOUS `-es` (after x/sh/ss/zz: boxes, hashes, classes, quizzes) —
+ *   strip 2 only. Stripping 1 minted a bogus sibling ("classes" → classe).
+ * - AMBIGUOUS endings (`-ches`/`-ses`/`-zes`/`-oes`): spelling alone can't
+ *   split patches(+es) from caches(+s), lenses from databases, heroes from
+ *   shoes — emit BOTH candidate keys and let the vocab lookup decide; a miss
+ *   is an ignored key, a wrong exclusive guess would LOSE the real match.
+ * - Everything else ending in `-s` — a bare `-s` plural (services, machines,
+ *   cookies): strip 1 only. Stripping 2 minted "services" → servic.
+ * A trailing `-ss` is a singular (class, process), not a plural: no strip —
+ * that used to mint "class" → clas.
+ */
+export declare function segmentLookupVariants(word: string): string[];
+//# sourceMappingURL=identifier-segments.d.ts.map

package/dist/sync/watcher.d.ts

@@ -63,8 +63,9 @@ export interface WatchOptions {
     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
+     * is disabled — OS watch-resource exhaustion (EMFILE/ENFILE), a write lock
+     * held past the retry budget, or a generic sync failure that persists past
+     * the retry budget (#1127). 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.
      */
@@ -139,12 +140,15 @@ export declare class FileWatcher {
     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().
+     * (watch-resource exhaustion, lock contention past the retry budget, or a
+     * persistent generic sync failure 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;
+    /** Consecutive generic (non-lock) sync failures; reset only by a clean sync. */
+    private syncFailureRetryCount;
     /** Test-only inert mode: started, but with no OS watcher installed. */
     private inert;
     private debounceTimer;
@@ -256,7 +260,8 @@ export declare class FileWatcher {
     private shouldIgnoreDir;
     /**
      * Permanently disable live watching after a terminal runtime failure
-     * (watch-resource exhaustion, or lock contention past the retry budget).
+     * (watch-resource exhaustion, lock contention past the retry budget, or a
+     * persistent generic sync failure past the retry budget).
      * Idempotent: logs one actionable warning, fires {@link WatchOptions.onDegraded}
      * once, and stops the watcher. A subsequent start() clears the latch.
      */

package/dist/sync/worktree.d.ts

@@ -25,6 +25,15 @@
  * is exactly the distinction this module relies on.
  */
 export declare function gitWorktreeRoot(dir: string): string | null;
+/**
+ * Absolute, symlink-resolved git **common** directory for `dir` — the shared
+ * `.git` that all worktrees of one repository point at. Linked worktrees of the
+ * same repo report the SAME common dir; a submodule or an embedded clone is a
+ * DIFFERENT repository and reports its own (`…/.git/modules/<name>` or its own
+ * `.git`). That distinction is what separates a genuine "borrowed worktree"
+ * from a nested repo the parent index already covers. Null when not a repo.
+ */
+export declare function gitCommonDir(dir: string): string | null;
 export interface WorktreeIndexMismatch {
     /** The git working tree the command was run from. */
     worktreeRoot: string;

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", "razor", "php", "ruby", "swift", "kotlin", "dart", "svelte", "vue", "astro", "liquid", "pascal", "scala", "lua", "luau", "objc", "r", "vba", "sql", "yaml", "twig", "xml", "properties", "unknown"];
+export declare const LANGUAGES: readonly ["typescript", "javascript", "tsx", "jsx", "arkts", "python", "go", "rust", "java", "c", "cpp", "csharp", "razor", "php", "ruby", "swift", "kotlin", "dart", "svelte", "vue", "astro", "liquid", "pascal", "scala", "lua", "luau", "objc", "r", "vba", "sql", "solidity", "nix", "yaml", "twig", "xml", "properties", "cfml", "cfscript", "cfquery", "cobol", "vbnet", "erlang", "terraform", "unknown"];
 export type Language = (typeof LANGUAGES)[number];
 /**
  * A node in the knowledge graph representing a code symbol
@@ -261,11 +261,34 @@ export interface SearchOptions {
 export interface SearchResult {
     /** Matching node */
     node: Node;
-    /** Relevance score (0-1) */
+    /**
+     * Relevance score for relative ranking only — higher is more relevant.
+     * NOT normalized and NOT a 0-1 fraction: the FTS path returns an unbounded
+     * BM25 magnitude (often in the tens or hundreds), while the fuzzy/exact
+     * paths return ~0-1. Use it to order results, not as an absolute percentage.
+     */
     score: number;
     /** Matched text snippets for highlighting */
     highlights?: string[];
 }
+/**
+ * A symbol whose name-segments match prose words from a prompt — the
+ * graph-derived signal behind the front-load hook's medium tier
+ * (CodeGraph.getSegmentMatches). Always verified to exist in `nodes` at the
+ * time it is returned.
+ */
+export interface SegmentMatch {
+    /** Symbol name as indexed (e.g. `OrderStateMachine`). */
+    name: string;
+    /** Kind of the representative definition. */
+    kind: NodeKind;
+    /** File of the representative definition. */
+    filePath: string;
+    /** 1-based start line of the representative definition. */
+    startLine: number;
+    /** The prompt words (normalized) that matched this name's segments. */
+    matchedWords: string[];
+}
 /**
  * Context information for code understanding
  */

package/dist/upgrade/index.d.ts

@@ -106,6 +106,11 @@ export interface UpgradeDeps {
     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;
+    /** Run a command capturing stdout (nothing reaches the terminal); null = spawn failed. */
+    capture: (cmd: string, args: string[]) => {
+        code: number;
+        stdout: string;
+    } | null;
     hasCommand: (cmd: string) => boolean;
     log: (msg: string) => void;
     warn: (msg: string) => void;
@@ -118,8 +123,30 @@ 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>;
+type VersionProbe = 'match' | 'mismatch' | 'inconclusive';
+/**
+ * Prove the upgrade actually took: spawn the `codegraph` this terminal's PATH
+ * resolves and compare its reported version to the target. Catches the silent
+ * failure mode where ANOTHER install shadows the one we just upgraded (issue
+ * #1071 — e.g. a stale `npm i -g` copy earlier on PATH than the bundle
+ * launcher): the upgrade "succeeds" but `codegraph -v` — in this terminal and
+ * every future one — keeps serving the old version. Exported for unit tests.
+ */
+export declare function verifyResolvedVersion(latest: string, deps: UpgradeDeps): VersionProbe;
 /** Build the in-place Windows upgrade script (exported for unit-testing). */
 export declare function buildWindowsUpgradeScript(bundleRoot: string, version: string, arch: string): string;
+/**
+ * How to invoke npm. On Windows npm is a .cmd batch file, which Node refuses
+ * to spawn without a shell (EINVAL since the CVE-2024-27980 hardening) — a
+ * direct `npm.cmd` spawn fails on every current Node, so route it through
+ * cmd.exe, the same way the surface-refresh step invokes the .cmd launcher.
+ * (Verified live on the Windows VM: `spawnSync('npm.cmd')` → EINVAL;
+ * `cmd.exe /d /s /c npm …` → works.)
+ */
+export declare function npmInvocation(platform: NodeJS.Platform, npmArgs: string[]): {
+    cmd: string;
+    args: 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
@@ -129,4 +156,9 @@ export declare function buildWindowsUpgradeScript(bundleRoot: string, version: s
  */
 export declare function hasCommand(cmd: string): boolean;
 export declare function defaultRun(cmd: string, args: string[], env?: NodeJS.ProcessEnv): number;
+export declare function defaultCapture(cmd: string, args: string[]): {
+    code: number;
+    stdout: string;
+} | null;
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/upgrade/remove-binary.d.ts

@@ -0,0 +1,87 @@
+/**
+ * CLI binary removal for `codegraph uninstall` (the #1071 shadow, uninstall
+ * edition).
+ *
+ * Before this module, three disconnected paths each removed PART of an
+ * installation and none removed it all: `codegraph uninstall` swept agent
+ * configs only, `install.sh --uninstall` deleted the bundle only, and npm's
+ * `preuninstall` hook cleaned configs when npm removed its own package. A
+ * user with more than one install method (the common drift: npm first, the
+ * bundle later — or vice versa) ran `codegraph uninstall` and still had a
+ * working `codegraph` on PATH.
+ *
+ * This module makes `codegraph uninstall` complete: PLAN every binary
+ * install present on the machine (bundle layout(s), the npm global package,
+ * the bin-dir shim), then EXECUTE the removals. Split planner/executor with
+ * injected side effects, same convention as the upgrade orchestrator.
+ *
+ * Safety rules:
+ *   - A source checkout is REPORTED, never deleted — a git repo is the
+ *     user's working tree, not an "install".
+ *   - A project-local npm install is left alone — the project's
+ *     package.json owns it, not the machine-level uninstaller.
+ *   - On unix the default install dir (`~/.codegraph`) doubles as the
+ *     machine-level state dir (telemetry choice, daemon records, the
+ *     update-check cache) — only the install ARTIFACTS (`versions/`,
+ *     `current`) are removed there, never the whole dir. A dedicated
+ *     install dir (Windows `%LOCALAPPDATA%\codegraph`, or a custom
+ *     `CODEGRAPH_INSTALL_DIR`) is removed wholesale.
+ *   - The bin-dir shim is removed only when it verifiably points into a
+ *     detected install dir — a user's unrelated `codegraph` file survives.
+ *   - Windows cannot DELETE a running exe but CAN rename it (the same
+ *     trick the in-place upgrade uses): a locked `node.exe` is renamed
+ *     aside and reported as a leftover for the user to delete after the
+ *     window closes, instead of failing the whole removal.
+ */
+export interface RemoveBinaryProbes {
+    /** `__filename` of the running CLI entry (dist/bin/codegraph.js). */
+    filename: string;
+    platform: NodeJS.Platform;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    homedir: string;
+    exists: (p: string) => boolean;
+    /** Symlink target (raw link text), or null when not a symlink / unreadable. */
+    readlink: (p: string) => string | null;
+    /** Run a command capturing stdout; null = spawn failed. */
+    capture: (cmd: string, args: string[]) => {
+        code: number;
+        stdout: string;
+    } | null;
+}
+export interface BinaryRemovalPlan {
+    /** Filesystem paths to delete (bundle dirs / artifacts, shim links). */
+    paths: string[];
+    /** The npm global package is installed and should be `npm uninstall -g`ed. */
+    npmGlobal: boolean;
+    /**
+     * npm's global node_modules root (for the Windows locked-exe dance — the
+     * vendored node.exe lives in the SIBLING per-platform package, so the
+     * whole root is the lock surface, not just the meta package's dir).
+     */
+    npmRoot: string | null;
+    /** Running from a git checkout — surfaced to the user, never deleted. */
+    sourceRoot: string | null;
+    /** One human line per planned removal, for the confirm prompt. */
+    summary: string[];
+}
+export declare function defaultProbes(filename: string): RemoveBinaryProbes;
+export declare function planBinaryRemoval(p: RemoveBinaryProbes): BinaryRemovalPlan;
+export interface RemoveBinaryDeps {
+    platform: NodeJS.Platform;
+    /** The running node binary — the file Windows will hold a lock on. */
+    execPath: string;
+    rm: (p: string) => void;
+    rename: (from: string, to: string) => void;
+    /** Run a command inheriting stdio; returns exit code (-1 = spawn failed). */
+    run: (cmd: string, args: string[]) => number;
+}
+export interface BinaryRemovalResult {
+    removed: string[];
+    /** Paths that could not be (fully) removed — surfaced with manual steps. */
+    leftovers: string[];
+    npm: 'removed' | 'failed' | 'skipped';
+}
+export declare function defaultRemoveDeps(): RemoveBinaryDeps;
+export declare function executeBinaryRemoval(plan: BinaryRemovalPlan, deps?: RemoveBinaryDeps): BinaryRemovalResult;
+//# sourceMappingURL=remove-binary.d.ts.map

package/dist/upgrade/update-check.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Background update-availability check for long-lived servers (#1243).
+ *
+ * The recommended MCP config launches the LOCAL `codegraph` binary, so the
+ * server (and the prompt hook alongside it) silently stays on whatever version
+ * was last manually upgraded — users discover the drift only when something
+ * breaks. This module gives the running server *visibility* without changing
+ * behavior: a non-blocking check against the latest GitHub release, surfaced
+ * as a one-line notice (stderr log, MCP initialize instructions, and
+ * `codegraph_status`) telling the user to run `codegraph upgrade`.
+ *
+ * Invariants (mirrors the telemetry module's contract):
+ *   - Never stdout — stdio is the MCP protocol channel.
+ *   - Never blocking: the network refresh is fire-and-forget; every reader
+ *     (`getUpdateNotice`) is a cheap synchronous cache read, so the #172
+ *     respond-fast handshake contract holds.
+ *   - Fail silent: offline / rate-limited / disk-full all degrade to "no
+ *     notice", never an error, never a retry loop.
+ *   - Off is off: `CODEGRAPH_NO_UPDATE_CHECK` (dedicated) or `DO_NOT_TRACK`
+ *     (broad don't-phone-home convention — set by e.g. the Pro container's
+ *     data plane) suppresses the network call AND the notice entirely.
+ *
+ * The check itself reuses `resolveLatestVersion` — the GitHub release-redirect
+ * trick with the API fallback — so version resolution can't drift from what
+ * `codegraph upgrade` installs. Results are cached in `~/.codegraph/` (the
+ * same global state dir telemetry and the daemon registry use) with a 24h TTL
+ * on success and a 1h backoff after failure, shared across every proxy /
+ * daemon process on the machine.
+ */
+/** Re-check the release feed after this long (successful checks). */
+export declare const UPDATE_CHECK_TTL_MS: number;
+/** Back off this long after a failed check (offline, rate-limited). */
+export declare const UPDATE_CHECK_FAILURE_BACKOFF_MS: number;
+export interface UpdateCheckCacheFile {
+    /** Last time a network check was attempted (ms epoch). */
+    lastAttemptAt: number;
+    /** Last time a network check succeeded (ms epoch). */
+    lastSuccessAt?: number;
+    /** Latest release tag from the last successful check (e.g. `v1.4.1`). */
+    latest?: string;
+}
+export interface UpdateCheckDeps {
+    /** Global state dir; defaults to ~/.codegraph. Tests inject a temp dir. */
+    dir?: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    resolveLatest?: () => Promise<string>;
+    currentVersion?: string;
+}
+/**
+ * True when the update check must not run at all — no network call, no
+ * notice. `DO_NOT_TRACK` uses the same truthiness the telemetry opt-out does.
+ */
+export declare function updateCheckDisabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function updateCheckCachePath(dir: string): string;
+export declare function readUpdateCheckCache(dir: string): UpdateCheckCacheFile | null;
+/**
+ * Rebuild a canonical `vX.Y.Z[-pre]` tag from the PARSED semver fields, or
+ * null when the input isn't version-shaped. The notice ends up inside the MCP
+ * initialize instructions — agent-visible, system-prompt-adjacent text — and
+ * the `latest` value arrives from a network redirect via an on-disk cache, so
+ * only a reconstructed canonical string may ever be interpolated, never the
+ * raw value. (`parseSemver`'s regex is not end-anchored: a value like
+ * `1.2.3-x <arbitrary text>` parses "valid" while the raw string would carry
+ * the trailing text straight into every session's instructions.)
+ */
+export declare function canonicalVersionTag(v: string): string | null;
+/** One user-facing sentence; every surface (stderr, instructions, status) shows this. */
+export declare function formatUpdateNotice(current: string, latest: string): string;
+/**
+ * Ensure the on-disk cache is fresh (hitting the network only past the TTL /
+ * backoff) and return the current notice, or null. Never throws.
+ */
+export declare function refreshUpdateCheck(deps?: UpdateCheckDeps): Promise<string | null>;
+/**
+ * The current update notice from the on-disk cache — synchronous and cheap
+ * (memoized disk read), safe on the initialize respond-fast path. When the
+ * cache has gone stale (e.g. a daemon that has been up for weeks), kicks a
+ * background refresh so the NEXT reader sees a current answer; this call
+ * still returns immediately from the stale cache.
+ */
+export declare function getUpdateNotice(deps?: UpdateCheckDeps): string | null;
+/** Test hook: clear the per-process memo. */
+export declare function resetUpdateNoticeMemo(): void;
+/**
+ * Fire-and-forget entry point for server startup: refresh the cache in the
+ * background and, if an update is available, emit ONE stderr line (stderr is
+ * the MCP-safe channel; hosts surface it in their server logs). Never throws,
+ * never blocks, never writes stdout.
+ */
+export declare function checkForUpdateInBackground(deps?: UpdateCheckDeps, log?: (line: string) => void): void;
+//# sourceMappingURL=update-check.d.ts.map