mirror of
https://github.com/giancarloerra/socraticode.git
synced 2026-06-02 06:23:43 +02:00
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>
136 lines
4.6 KiB
Markdown
136 lines
4.6 KiB
Markdown
# Contributing to SocratiCode
|
|
|
|
Thank you for your interest in contributing to SocratiCode! This document explains the process for contributing and what to expect.
|
|
|
|
## Contributor License Agreement
|
|
|
|
By submitting a pull request, you agree to the [Contributor License Agreement (CLA)](CLA.md). This is necessary because SocratiCode is dual-licensed (AGPL-3.0 + commercial). The CLA allows us to offer commercial licenses that include community contributions.
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 18+
|
|
- Docker (for integration and E2E tests)
|
|
- Git
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
git clone https://github.com/giancarloerra/socraticode.git
|
|
cd socraticode
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Unit tests (no Docker needed)
|
|
npm run test:unit
|
|
|
|
# Integration tests (requires Docker)
|
|
npm run test:integration
|
|
|
|
# End-to-end tests (requires Docker)
|
|
npm run test:e2e
|
|
|
|
# All tests
|
|
npm test
|
|
|
|
# Type checking
|
|
npx tsc --noEmit
|
|
```
|
|
|
|
See the [Developer Guide](DEVELOPER.md) for architecture details, data flows, and how the test infrastructure works.
|
|
|
|
## How to Contribute
|
|
|
|
### Reporting Bugs
|
|
|
|
Use the [Bug Report](https://github.com/giancarloerra/socraticode/issues/new?template=bug_report.yml) issue template. Include:
|
|
|
|
- Steps to reproduce
|
|
- Expected vs actual behaviour
|
|
- Your environment (OS, Node.js version, embedding provider, MCP host)
|
|
- Log output if available (set `SOCRATICODE_LOG_LEVEL=debug`)
|
|
|
|
### Suggesting Features
|
|
|
|
Use the [Feature Request](https://github.com/giancarloerra/socraticode/issues/new?template=feature_request.yml) issue template. Explain the problem you're trying to solve and your proposed approach.
|
|
|
|
### Submitting Pull Requests
|
|
|
|
1. **Fork** the repository and create a branch from `main`
|
|
2. **Make your changes** — follow the existing code style and conventions
|
|
3. **Add tests** — new functionality needs test coverage; bug fixes should include a regression test
|
|
4. **Update documentation** — if your changes affect the public API, update README.md and/or DEVELOPER.md
|
|
5. **Verify** — run `npm run lint && npx tsc --noEmit && npm run test:unit`
|
|
6. **Open a PR** — fill out the pull request template
|
|
|
|
### Commit Message Convention
|
|
|
|
We use [Conventional Commits](https://www.conventionalcommits.org/) to auto-generate the changelog:
|
|
|
|
```
|
|
feat: add fuzzy search support
|
|
fix: resolve race condition in watcher
|
|
docs: update quickstart guide
|
|
refactor: simplify provider factory
|
|
test: add watcher edge-case tests
|
|
chore: update dependencies
|
|
```
|
|
|
|
Prefix with the type, then a short imperative description. Use `feat:` for new features, `fix:` for bug fixes, and `chore:` for maintenance that doesn't need a changelog entry.
|
|
|
|
### What Makes a Good PR
|
|
|
|
- **Focused** — one logical change per PR
|
|
- **Tested** — unit tests at minimum; integration tests for infrastructure changes
|
|
- **Documented** — JSDoc comments on public functions, README/DEVELOPER.md updates where needed
|
|
- **Clean history** — squash fixup commits before requesting review
|
|
- **Conventional commits** — use the format above so the changelog generates correctly
|
|
|
|
## Code Style
|
|
|
|
- **TypeScript** with strict mode enabled
|
|
- **ESM** (ES modules) — use `.js` extensions in imports
|
|
- **Functional style** — prefer pure functions, avoid classes where unnecessary
|
|
- **Structured logging** — use `logger.info/warn/error/debug` with context objects, not `console.log`
|
|
- **Error messages** — user-friendly, actionable, include troubleshooting hints
|
|
- **JSDoc** on all exported functions
|
|
- **SPDX license header** on all source files:
|
|
```typescript
|
|
// SPDX-License-Identifier: AGPL-3.0-only
|
|
// Copyright (C) 2026 Giancarlo Erra - Altaire Limited
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/services/ — Core business logic (docker, indexer, embeddings, etc.)
|
|
src/tools/ — MCP tool handlers (one file per tool group)
|
|
src/config.ts — Project ID and collection naming
|
|
src/constants.ts — All configurable constants
|
|
tests/unit/ — Unit tests (no Docker)
|
|
tests/integration/ — Integration tests (Docker required)
|
|
tests/e2e/ — End-to-end tests (Docker required)
|
|
```
|
|
|
|
See [DEVELOPER.md](DEVELOPER.md) for the full architecture overview.
|
|
|
|
## Review Process
|
|
|
|
- All PRs are reviewed by a maintainer
|
|
- [CodeRabbit](https://coderabbit.ai) automatically reviews every PR — address or resolve all comments before requesting human review
|
|
- CI must pass (tests + type checking)
|
|
- One approval required to merge
|
|
- Maintainers may request changes or suggest alternatives
|
|
|
|
## Questions?
|
|
|
|
- Open a [Discussion](https://github.com/giancarloerra/socraticode/discussions) for questions
|
|
- Check the [README](README.md) and [Developer Guide](DEVELOPER.md) for existing documentation
|
|
|
|
Thank you for helping make SocratiCode better!
|