mirror of https://github.com/giancarloerra/socraticode.git synced 2026-06-02 06:23:43 +02:00

Files

T

Giancarlo Erra 50d8853ea6 feat(visualize): add interactive HTML graph explorer; British-English doc sweep

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>

2026-04-23 16:04:41 +01:00

4.6 KiB

Raw Permalink Blame History

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). 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

git clone https://github.com/giancarloerra/socraticode.git
cd socraticode
npm install
npm run build

Running Tests

# 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 for architecture details, data flows, and how the test infrastructure works.

How to Contribute

Reporting Bugs

Use the Bug Report 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 issue template. Explain the problem you're trying to solve and your proposed approach.

Submitting Pull Requests

Fork the repository and create a branch from main
Make your changes — follow the existing code style and conventions
Add tests — new functionality needs test coverage; bug fixes should include a regression test
Update documentation — if your changes affect the public API, update README.md and/or DEVELOPER.md
Verify — run npm run lint && npx tsc --noEmit && npm run test:unit
Open a PR — fill out the pull request template

Commit Message Convention

We use Conventional Commits 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:

// 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 for the full architecture overview.

Review Process

All PRs are reviewed by a maintainer
CodeRabbit 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 for questions
Check the README and Developer Guide for existing documentation

Thank you for helping make SocratiCode better!

4.6 KiB Raw Permalink Blame History