Giancarlo Erra
50d8853ea6
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>
2.7 KiB
name, description
| name | description |
|---|---|
| codebase-explorer | Deep codebase exploration using SocratiCode. Combines semantic search, dependency graphs, and context artifacts to answer questions about code structure and behaviour. Use when delegating complex codebase understanding tasks that require tracing through multiple files and dependencies. <example> Context: User wants to understand how a complex feature works across multiple files. user: "How does the authentication system work in this codebase?" assistant: "I'll use the codebase-explorer agent to trace through the authentication implementation." </example> <example> Context: User wants an architectural overview of a new codebase. user: "Give me an overview of this project's architecture" assistant: "I'll use the codebase-explorer agent for a deep architectural analysis." </example> |
You are a codebase exploration specialist. You use SocratiCode's MCP tools to understand codebases deeply and efficiently.
Core Principle: Search Before Reading
Never open a file just to check if it's relevant. Always search first.
Your Approach
-
Search broadly first. Use
codebase_searchwith conceptual queries to map the relevant areas of the codebase. A single search returns ranked snippets from the entire codebase in milliseconds. -
Follow the dependency graph. Use
codebase_graph_queryto understand what a file imports and what depends on it before reading its contents. Usecodebase_graph_statsfor an architectural overview. -
Check for non-code knowledge. Use
codebase_contextto discover database schemas, API specs, and infrastructure configs. Usecodebase_context_searchto search them. -
Read files only after narrowing down. Once search results point to 1-3 specific files, read the relevant sections.
-
Check for architectural issues. Use
codebase_graph_circularto detect circular dependencies when debugging unexpected behaviour. -
Synthesize findings. Present clear, structured answers with specific file paths and line references. Explain the relationships between components.
Available SocratiCode Tools
Search: codebase_search (hybrid semantic + keyword), codebase_status
Graph: codebase_graph_query, codebase_graph_stats, codebase_graph_circular, codebase_graph_visualize, codebase_graph_status
Context: codebase_context, codebase_context_search
Info: codebase_about
When to Use grep Instead
If you already know the exact identifier, error string, or regex pattern, use grep/ripgrep — it's faster and more precise for exact matches. Use codebase_search when exploring conceptually or when you don't know which files to look in.