fix(install): warn when another codegraph on PATH shadows the new install (#1071) (#1072)

The standalone installers report installing the latest version while
`codegraph --version` can keep printing an old one. This is not a packaging
bug: the released bundle's version is correct, but a *different* codegraph
earlier on PATH runs instead — most often a stale
`npm i -g @colbymchenry/codegraph`, whose shim execs its own version-pinned
per-platform bundle, so it reports that old version forever and shadows the
freshly-installed standalone bundle.

install.sh and install.ps1 now detect this at install time and point at the
shadowing copy with how to fix it (remove the other install, or reorder PATH).
install.ps1 checks both the persisted PATH a fresh shell sees (Machine + User)
and the live session PATH, to catch dirs a shell profile injects (conda/npm).

Validated end-to-end on real substrate: install.sh in Docker (linux-arm64,
dash + `set -eu`) and install.ps1 on a Windows 11 PowerShell 5.1 VM
(win32-arm64) — each really downloads the bundle, wires PATH, and fires the
warning, with PATH-resolved `--version` showing the old shadow while the fresh
bundle reports the new version.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -16,6 +16,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - C++ classes annotated with an export or visibility macro are now indexed as real classes. This is the `class MYMODULE_API UMyComponent : public UActorComponent` style used throughout Unreal Engine — where an `XXX_API` macro sits between `class`/`struct` and the type name — as well as the equivalent `*_EXPORT` / `*_ABI` macros common in Qt, Boost, LLVM, and many other libraries. Previously that macro made the parser misread the whole declaration as a function, so the class was dropped entirely: it never appeared in the graph and its base class went unrecorded, which made "find subclasses", type-hierarchy, and impact-through-inheritance queries come back empty for effectively every gameplay class in an Unreal Engine project. The class, its members, and its inheritance link are now all captured. Thanks @luoyxy for the detailed report and proposed fix. (#1061)
 - `codegraph_explore` now surfaces the options/config type behind a function when you ask, in plain language, what to change to add a parameter to it. A question like "what do I need to change to add a new parameter to X" shares no words with the file that actually defines X's options — for example a functional-options struct and its `With…` builders living in a separate `options.go`, reachable only through X's signature — so that file scored near-zero on every text and connectivity signal and got dropped: explore returned X itself but not the file you'd edit, and the agent fell back to grep. Explore now follows a named function's parameter and return types and pulls in the file that defines them when ranking would otherwise bury it, so the options/config file shows up with its fields. Well-connected types that already rank are left untouched, so ordinary "how does X work" flow questions are unchanged. (The separate tools `codegraph_search`/`codegraph_impact`/`codegraph_node` remain available via `CODEGRAPH_MCP_TOOLS` for anyone who prefers driving each step explicitly.) Thanks @wauxhall for the detailed investigation. (#1064)
+- The standalone installers (`install.sh` / `install.ps1`) now warn when a different `codegraph` earlier on your PATH will run instead of the one they just installed. The usual cause is a leftover `npm i -g @colbymchenry/codegraph` from an earlier version, whose launcher keeps running its own pinned version — so the installer reports installing the latest while `codegraph --version` keeps printing the old one, with no hint as to why. The installer now points at the shadowing copy and tells you how to resolve it (remove the other install, or put the new one first on PATH). Thanks @SpringYear for the report. (#1071)
 
 ## [1.1.4] - 2026-06-29
 

install.ps1

@@ -56,4 +56,36 @@ if (($userPath -split ';') -notcontains $binDir) {
 }
 
 Write-Host "Installed to $dest"
+
+# 5. Warn if a different codegraph earlier on PATH will shadow this install.
+# Most often a stale `npm i -g @colbymchenry/codegraph`, whose launcher keeps
+# running its own version-pinned bundle — so `codegraph --version` disagrees
+# with what we just installed (issue #1071). Check both the persisted PATH a
+# fresh shell sees (Machine + User) and this session's PATH (catches dirs a
+# shell profile injects, e.g. conda / npm).
+$expected = Join-Path $binDir 'codegraph.cmd'
+function Find-FirstCodegraph([string]$pathStr) {
+  foreach ($dir in ($pathStr -split ';')) {
+    if (-not $dir) { continue }
+    foreach ($leaf in @('codegraph.cmd', 'codegraph.exe', 'codegraph.bat', 'codegraph.ps1')) {
+      $cand = Join-Path $dir $leaf
+      if (Test-Path -LiteralPath $cand) { return $cand }
+    }
+  }
+  return $null
+}
+$machinePath = [Environment]::GetEnvironmentVariable('Path', 'Machine')
+$freshPath = ((@($machinePath, [Environment]::GetEnvironmentVariable('Path', 'User')) | Where-Object { $_ }) -join ';')
+$shadow = $null
+foreach ($winner in @((Find-FirstCodegraph $env:Path), (Find-FirstCodegraph $freshPath))) {
+  if ($winner -and ($winner -ne $expected)) { $shadow = $winner; break }
+}
+if ($shadow) {
+  Write-Warning "Another codegraph is earlier on your PATH and will run instead of this install:"
+  Write-Warning "  $shadow"
+  Write-Warning "  (this install: $expected)"
+  Write-Warning "If 'codegraph --version' shows an unexpected version, remove the other copy"
+  Write-Warning "(e.g. 'npm rm -g @colbymchenry/codegraph') or put '$binDir' first on your PATH."
+}
+
 Write-Host "Run: codegraph --help"

install.sh

@@ -83,13 +83,38 @@ ln -sfn "$dest" "$INSTALL_DIR/current"
 
 echo "Installed to $dest"
 echo "Linked     $BIN_DIR/codegraph"
-case ":$PATH:" in
-  *":$BIN_DIR:"*) ;;
-  *)
-    echo ""
-    echo "$BIN_DIR is not on your PATH. Add it:"
-    echo "  export PATH=\"$BIN_DIR:\$PATH\""
-    ;;
-esac
+
+# 5. PATH sanity. Two ways this install can fail to be the codegraph that runs:
+#   1. $BIN_DIR isn't on PATH at all.
+#   2. A *different* codegraph sits earlier on PATH and shadows ours — most
+#      often a stale `npm i -g @colbymchenry/codegraph`, whose launcher keeps
+#      running its own version-pinned bundle, so `codegraph --version` disagrees
+#      with what we just installed (issue #1071).
+# Walk PATH once: note whether $BIN_DIR is present and which codegraph wins.
+on_path=0
+winner=""
+oldifs="$IFS"; IFS=:
+for dir in $PATH; do
+  [ -n "$dir" ] || continue
+  if [ "$dir" = "$BIN_DIR" ]; then on_path=1; fi
+  if [ -z "$winner" ] && [ -x "$dir/codegraph" ] && [ ! -d "$dir/codegraph" ]; then
+    winner="$dir/codegraph"
+  fi
+done
+IFS="$oldifs"
+
+if [ "$on_path" -eq 0 ]; then
+  echo ""
+  echo "$BIN_DIR is not on your PATH. Add it:"
+  echo "  export PATH=\"$BIN_DIR:\$PATH\""
+elif [ -n "$winner" ] && [ "$winner" != "$BIN_DIR/codegraph" ]; then
+  echo ""
+  echo "Warning: another codegraph is earlier on your PATH and will run instead:"
+  echo "  $winner"
+  echo "  (this install: $BIN_DIR/codegraph)"
+  echo "If 'codegraph --version' shows an unexpected version, remove the other copy"
+  echo "(e.g. 'npm rm -g @colbymchenry/codegraph') or put $BIN_DIR first on PATH."
+fi
+
 echo ""
 echo "Done. Run: codegraph --help"