mirror of https://github.com/giancarloerra/socraticode.git synced 2026-06-01 22:18:57 +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

2.0 KiB

Raw Permalink Blame History

Security Policy

Reporting a Vulnerability

If you discover a security vulnerability in SocratiCode, please report it responsibly.

Do NOT open a public GitHub issue for security vulnerabilities.

Instead, email giancarlo@altaire.com with:

A description of the vulnerability
Steps to reproduce
Potential impact
Any suggested fixes (optional)

You will receive an acknowledgement within 48 hours and a detailed response within 7 days indicating next steps.

Scope

This policy applies to the SocratiCode codebase and its managed Docker infrastructure (Qdrant and Ollama containers). It does not cover third-party services you may connect to (cloud Qdrant, OpenAI API, Google Gemini API).

Security Model

SocratiCode is designed to run locally by default:

No data exfiltration — In the default configuration (Ollama + Docker Qdrant), all data stays on your machine. No external API calls are made.
No network listeners — The MCP server communicates over stdio only. It does not open any HTTP endpoints.
Docker isolation — Qdrant and Ollama run in Docker containers with only the necessary ports exposed on localhost.
No credentials stored — API keys (OpenAI, Google, Qdrant) are passed via environment variables at runtime, never written to disk.

When cloud providers are used

If you configure EMBEDDING_PROVIDER=openai or EMBEDDING_PROVIDER=google, code chunks are sent to the respective cloud API for embedding generation. This is an explicit opt-in. The default configuration never contacts external services.

Supported Versions

Only the latest release is supported with security updates.

Version	Supported
Latest	Yes
Older	No

Disclosure Policy

Vulnerabilities will be patched and released as soon as practical
A security advisory will be published on GitHub after the fix is available
Credit will be given to reporters unless they prefer to remain anonymous

2.0 KiB Raw Permalink Blame History