A pass over the extension surface to address review feedback:
Safety / hardening:
- `graphPanel.ts`: validate `m.path` from the webview before opening
files. Reject absolute paths and any path that escapes the workspace
root (`..`, `/foo`, `C:/...`). Validate the line number is a positive
integer before constructing a `Range`. Surface failures via the output
channel rather than letting the rejection bubble up.
- `mcpProvider.ts`: defensively check that
`vscode.lm.registerMcpServerDefinitionProvider` exists before calling
it. The `engines.vscode: ^1.99.0` field already enforces this on
install, but some VS Code-derived editors mis-report their engine
version. The extension now degrades gracefully (sidebar, commands,
status bar still work) instead of failing activation.
- `commands.ts` and `graphPanel.ts`: wrap `workbench.action.chat.open`
in try/catch. Not every VS Code-compatible editor exposes that
command; falling back to the output channel avoids unhandled
rejections after the user clicked "Open chat".
- `extension.ts`: persist the first-run walkthrough flag only after the
walkthrough command resolves successfully, so a transient failure
doesn't silently skip the onboarding forever.
CI gates:
- `extension-ci.yml` and `extension-release.yml`: run `npm test` between
typecheck and build, so manifest-level smoke regressions can't slip
through to either the PR artefact or the marketplace publishes.
Settings copy:
- `socraticode.env` description: explicitly call out that the setting
is for non-secret config only. Recommend OS environment variables /
local `.env` files for API keys, since workspace settings can sync
via Settings Sync and end up in committed `.vscode/settings.json`.
Quality of life:
- `sidebar.ts` `formatRelative`: clamp the computed seconds to zero so
a file mtime slightly ahead of the local clock doesn't render
"-5s ago".
- `walkthroughs/first-index.md`: corrected the embedding model name
(`nomic-embed-text`, not `mxbai-embed-large`) to match the engine
default in `src/constants.ts`.
Lint / docs:
- `extension/README.md`: hyphenate "Eclipse Theia-based editors".
- `DEVELOPER.md`: add `text` language hint to the directory-tree code
fence (markdownlint MD040). Updated the inline comment for
`settings.ts` to reflect its current shape.
- `README.md`: reflow the "extension vs plugin" callout into a single
blockquote (markdownlint MD028).
Lint, typecheck, manifest tests and build all clean. Engine unit tests
unaffected (706/706 still pass).
README updates:
- Plugins table now includes a row for the VS Code / Open VSX extension,
with a list of every editor that pulls from one of the two registries
(Cursor, VSCodium, Gitpod, code-server, Theia, Antigravity, Particle
Workbench).
- Cursor Marketplace listing mentioned alongside the existing
`/add-plugin` URL install.
- A short "extension vs plugin" callout explaining when to install
which: the extension auto-registers MCP and adds native UI, the
plugin formats add skills + agent rules. Both can coexist.
DEVELOPER.md updates:
- New "VS Code / Open VSX Extension" section covering layout, local
development (F5 to launch an Extension Development Host), build /
lint / test / package commands, publishing flow, and versioning
policy (extension tracks the engine version via the bump script).
- Explicit list of what the extension is NOT (no re-implementation of
search, no shipped engine, no language-server features). Keeps scope
honest and prevents future feature creep.
- Added the new section to the table of contents.
Address CodeRabbit findings on PR #36:
1. The previous patch attached `QDRANT_API_KEY` as an `api-key` header
regardless of URL scheme, which would leak the secret on the wire if
a user configured an authenticated Qdrant over plain HTTP. Add a
guard that rejects the combination and throws a specific error,
placed before the readiness probe so its message is not masked by
the generic "Cannot reach external Qdrant" handler. Loopback URLs
(`localhost`, `127.0.0.1`, `[::1]`) are accepted on `http://` so
local-dev workflows where users run authenticated Qdrant on plain
HTTP keep working. The URL is parsed (rather than checked with
startsWith) so hostnames like `http://localhost.evil.com` are not
mistaken for loopback.
2. The "omits api-key header when QDRANT_API_KEY is not set" test
relied on the spread of the real `constants.js` module, which means
it would flake to a header-attached state on any developer machine
with `QDRANT_API_KEY` exported in the shell. Pass
`QDRANT_API_KEY: undefined` explicitly so the override always wins.
3. Add two tests covering the new guard: one asserting the rejection
on plain HTTP for non-loopback hosts, and one asserting that the
localhost exception still attaches the api-key header.
4. Document the HTTPS requirement (and localhost exception) in the
`QDRANT_API_KEY` row of the README configuration table.
- Add "Portable, AI- and host-agnostic" paragraph in the intro that
bundles two claims: the codebase context lives with the code (works
with any assistant / IDE / CLI, any combination), and pre-computed
reasoning (blast radius, call-flow, dependency traversal) lets
smaller / cheaper models hold their own on architectural questions.
- Add three rows to the "Built-in Code Search vs SocratiCode"
comparison table: symbol-level impact / blast radius, call-flow
tracing, interactive visual graph explorer.
- Plugins section: chain Claude Code's two install commands with &&
so the row is a single copy-paste — the install step was missing.
Interactive Viewer (primary)
────────────────────────────
codebase_graph_visualize now accepts mode="mermaid" (default, existing
behaviour — text Mermaid diagram) or mode="interactive". Interactive
mode generates a self-contained HTML page and opens it in the user's
default browser via the `open` npm package (cross-platform: macOS,
Linux, Windows). Cytoscape.js 3.30.2 + Dagre 0.8.5 + cytoscape-dagre
2.5.0 are vendored under src/assets/ — no CDN, works offline.
Features:
- File view — every source file as a node, imports as edges, language
colour-coded, circular deps highlighted in red.
- Symbol view toggle — functions/classes/methods as nodes with call
edges (confidence-styled). Embedded when the symbol graph fits under
20k symbols / 60k call edges; above that threshold the file view
remains usable and a banner directs users to codebase_impact /
codebase_symbols for symbol-level queries.
- Sidebar on node click — imports, dependents, per-file symbol list
(first 30 + link to codebase_symbols), action buttons for blast
radius and call flow.
- Right-click any node → blast radius overlay (reverse-transitive
closure). Call-flow button on the sidebar for forward traversal.
- Live search across files and symbols, six Cytoscape layouts
(Dagre / force / concentric / breadth-first / grid / circle),
PNG export (filename sanitised for cross-platform safety).
- `open: false` parameter skips auto-launch and just returns the file
path — useful in headless environments.
Viewer is XSS-safe by construction: all DOM built with createElement
+ textContent (no innerHTML anywhere); embedded JSON escapes every
"<" as \u003c so a stray </script> in a file path or symbol name
cannot break out of the script-type="application/json" container.
New files:
- src/assets/{cytoscape.min.js,dagre.min.js,cytoscape-dagre.js,
viewer-template.html,viewer-styles.css,viewer-app.js}
- scripts/copy-assets.mjs — postbuild copier (tsc does not handle
non-TS files); wired into npm run build and prepublishOnly
- src/services/graph-visualize-html.ts — HTML builder with scale-cap
logic (MAX_SYMBOLS / MAX_EDGES / MAX_SYMS_PER_FILE) and parallel
per-file Qdrant payload loading
- src/services/graph-visualize-browser.ts — temp-file write +
cross-platform open wrapper
- tests/unit/graph-visualize-html.test.ts — 5 tests (self-contained,
escape-safety, symbolMode omitted/capped, cycle marking)
- tests/unit/graph-visualize-browser.test.ts — 4 tests (deterministic
path, overwrite, success + failure paths)
New runtime dependency: open@^10.2.0 (Sindre Sorhus, zero transitive
deps, cross-platform).
British-English doc sweep (secondary)
─────────────────────────────────────
Switched all project docs to British English spelling:
behavior → behaviour organized → organised
color-coded → colour-coded initialization → initialisation
visualization → visualisation customization → customisation
recognized → recognised optimized → optimised
acknowledgment → acknowledgement finalize → finalise
analyzing → analysing apologizing → apologising
sexualized → sexualised
Affected files: README, DEVELOPER, AGENTS, CLAUDE, GEMINI, SECURITY,
CONTRIBUTING, CODE_OF_CONDUCT, agents/codebase-explorer.md,
skills/codebase-exploration/{SKILL.md,references/tool-reference.md},
skills/codebase-management/references/tool-reference.md.
Also surfaced Impact Analysis in the top-level README paragraph.
Docs
────
- README: "Interactive graph explorer" subsection under Impact Analysis,
tool-table row updated.
- DEVELOPER.md: architecture section under codebase_graph_visualize
covering asset layout, data flow, cap logic, XSS-safety invariants.
- AGENTS.md / CLAUDE.md / GEMINI.md: new "User asks for a visual /
interactive / shareable graph" row in the tool-routing table.
- skills/codebase-exploration/: SKILL.md bullet + tool-reference.md
full mode description.
- CHANGELOG.md: "Interactive Graph Explorer" section under Unreleased.
Quality gates (all green)
─────────────────────────
- Biome lint: clean
- TypeScript (tsc): clean
- Unit tests: 685/685
- Integration tests: 154/154 (real Qdrant + Ollama)
- CodeRabbit: No findings (1 fix applied — filename sanitisation)
- Snyk code test: 0 issues
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- 4 new unit test files (22 tests) for graph-symbols, graph-symbol-resolution,
graph-entrypoints, symbol-graph-cache. All 799 tests pass.
- README/AGENTS/CLAUDE/GEMINI: document codebase_impact, codebase_flow,
codebase_symbol, codebase_symbols and updated workflow guidance.
- DEVELOPER.md: new architectural section for symbol-level call graph,
including sharded storage layout and resolution confidence levels.
- CHANGELOG: Unreleased section for the impact-analysis feature.
- Apply CodeRabbit fixes: dedupe in-flight cache loads, set ImpactResult.truncated
when frontier extends beyond depth limit, drop redundant String() around Lang enum.
- Switch reverse-shard hash from SHA1 to SHA256 (Snyk hardening; non-cryptographic use).
- README: new Features entries, full sections with config examples
- README: new env vars SOCRATICODE_BRANCH_AWARE, SOCRATICODE_LINKED_PROJECTS
- README: updated codebase_search tool description for includeLinked
- DEVELOPER.md: updated config.ts description, branch-aware and linked projects sections
- Move Svelte/Vue from "Indexing Only" to "Full Support" in README
- Move SASS/LESS to "Code Graph via Regex" in README
- Add graph-aliases.ts to DEVELOPER.md service file listing
- Update DEVELOPER.md data flow with CSS @import, path alias, and SCSS
partial resolution steps
- Add .claude-plugin/plugin.json with MCP server reference and hooks
- Add codebase-exploration skill with search-before-reading workflow
- Add codebase-management skill with indexing and troubleshooting guides
- Add codebase-explorer delegatable subagent for deep analysis
- Add SessionStart hook for duplicate MCP detection
- Add .mcp.json for plugin-bundled MCP server config
- Update package.json files array to include plugin assets in npm package
- Add release-it after:bump hook to sync plugin.json version
- Update README with plugin install badge, instructions, and guidance
Claude Code resolves git worktree links back to the main repo path for
config lookup, so MCP config only needs to be set once on the main
checkout. All worktrees inherit it automatically. Separate clones are
unaffected. Documents both the auto-detection path and the manual
.mcp.json fallback for other MCP hosts.
When working with git worktrees (or any setup where the same codebase lives
in multiple directories), each path currently gets its own Qdrant collection.
This means the same codebase is indexed multiple times.
This change adds a SOCRATICODE_PROJECT_ID environment variable that, when set,
overrides the path-based project ID generation. All directories sharing the
same SOCRATICODE_PROJECT_ID will use the same Qdrant collections (codebase,
codegraph, context), eliminating redundant indexing.
The value must match [a-zA-Z0-9_-]+ to remain Qdrant-friendly. An error is
thrown at startup if the value contains invalid characters.
Highlight that multiple AI agents can share a single index on the same
codebase with automatic coordination. Added to the intro paragraph,
Why SocratiCode, Features list, and FAQ.
Giancarlo Erra