Skip to content

feat(SPEC-006): add web graph browser - #153

Merged
fgabelmannjr merged 20 commits into
mainfrom
006-web-ui-graph-browser
Jul 16, 2026
Merged

fgabelmannjr merged 20 commits into
mainfrom
006-web-ui-graph-browser

Conversation

@fgabelmannjr

@fgabelmannjr fgabelmannjr commented Jul 16, 2026 •

Copy link
Copy Markdown

SPEC-006 Review Packet

Review Order

  1. Package and server seams: package.json, scripts/copy-web-assets.mjs, src/server/static.ts, src/server/index.ts, src/server/chat.ts, src/server/openapi.yaml.
  2. Web foundation: web/index.html, web/src/app/, shared API clients, layout, and state components.
  3. User workflows: repository status, search, symbol detail, relationships, graph, impact, re-analysis, and chat.
  4. Validation and docs: Playwright specs, Vitest coverage, docs/web-server.md, README.md, CHANGELOG.md, and this packet.

Scope Budget

  • SPEC-006 was accepted as a one-spec split exception with three review slices: foundation/search/symbol, graph canvas, and impact/reindex/chat/package validation.
  • Runtime behavior remains local-first: no browser-side indexing, no Cypher backend, no hosted web service, and no browser provider secrets.
  • Packaged assets are copied into dist/web/; /api/* remains JSON-only and is not swallowed by SPA fallback.

Traceability

  • US1 repo/status: web/src/components/layout/RepositorySwitcher.tsx, RepositoryStatus.tsx, RepositoryOverview.tsx, web/src/tests/repository-status.spec.ts.
  • US2 search/symbol: web/src/routes/SearchRoute.tsx, SymbolDetailRoute.tsx, web/src/tests/search-symbol.test.tsx.
  • US3 relationships/flows/clusters: RelationshipPanels.tsx, FlowSections.tsx, catalog API tests.
  • US4 graph: GraphRoute.tsx, GraphCanvas.tsx, GraphToolbar.tsx, web/src/tests/graph-view.test.tsx, graph-uat.spec.ts.
  • US5 impact: ImpactRoute.tsx, ImpactTables.tsx, impact-route.test.tsx.
  • US6 re-analysis: ReindexRoute.tsx, ReindexProgress.tsx, server-reindex-jobs.test.ts, reindex-panel.test.tsx.
  • US7 chat: src/server/chat.ts, web/src/components/chat/ChatPanel.tsx, chat-network.spec.ts.

Verification Evidence

  • npm --prefix web run test: passed after the MCP UAT fix with 17 files and 19 tests.
  • npm --prefix web run test -- src/tests/reindex-panel.test.tsx: passed after the MCP UAT fix; 1 file, 2 tests.
  • npm --prefix web run typecheck: passed.
  • npm --prefix web run test:e2e: passed with 13 Playwright tests.
  • npm exec -- vitest run __tests__/server-chat-adapter.test.ts __tests__/server-openapi-contract.test.ts __tests__/package-web-assets.test.ts __tests__/server-reindex-jobs.test.ts: passed with 100 tests.
  • npm test: passed outside the sandbox with Node 24.11.1 and a temporary Git signing override for test fixtures: 233 files, 3,922 passed, 7 skipped.
  • npm run build: passed after final UI fixes. Vite reported a 967.87 kB minified JS chunk, below the SPEC-006 1.5 MB uncompressed runtime-asset threshold.

Playwright MCP UAT

Packaged server command:

node dist/bin/codegraph.js serve --web --port 0 --path .

Evidence:

  • Opened the packaged app through Playwright MCP at http://127.0.0.1:<port>.
  • Verified title CodeGraph, repo picker/status, and self-repo counts.
  • Opened /search?q=startWebServer; saw 17 matches and opened startWebServer.
  • Symbol detail rendered signature, callers, callees, execution flows, and clusters.
  • Graph route rendered toolbar and summary; Cytoscape canvas layer 2 had 356 nonblank sampled points out of 7,055.
  • Impact route rendered 20 affected symbols and 161 graph edges.
  • Chat route rendered dormant no-provider state with disabled submit.
  • Re-analysis route accepted incremental sync and rendered terminal done with Checked 712 files; 0 changed; updated 0 nodes.
  • Mobile check at 390x844 showed no horizontal overflow: scrollWidth=375, innerWidth=390.

The MCP pass found one real issue: quick terminal EventSource close left the UI on Disconnected even though GET /api/reindex/:repo had a terminal done snapshot. Fixed in ReindexRoute.tsx by polling the latest job on disconnect and covered in reindex-panel.test.tsx.

Known Gaps

  • Configured endpoint chat was not exercised with real provider credentials in this pass; dormant/no-provider and no-browser-secret boundaries were validated.
  • The Vite default chunk warning remains. The built JS asset is below the accepted SPEC-006 threshold, so no code splitting was added in this slice.
  • Full npm test requires the local Git signing override on this machine because inherited config signs temporary fixture commits; the suite passed with that override.

Rollback Notes

  • Disable the browser app by reverting copy-web-assets, the web/ workspace, and the static mount changes; /api/* contracts should remain independently reviewable.
  • Remove the chat adapter by reverting src/server/chat.ts, its route wiring, and the OpenAPI chat paths.
  • Re-analysis recovery is isolated to web/src/routes/ReindexRoute.tsx and web/src/components/reindex/ReindexProgress.tsx.

@fgabelmannjr fgabelmannjr self-assigned this Jul 16, 2026
@fgabelmannjr fgabelmannjr added the enhancement New feature or request label Jul 16, 2026
@fgabelmannjr
fgabelmannjr marked this pull request as ready for review July 16, 2026 01:23
Copilot AI review requested due to automatic review settings July 16, 2026 01:23

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a packaged, local-first Web UI “graph browser” for codegraph serve --web, wiring new server-side chat adapter routes and shipping built SPA assets in dist/web/ while preserving /api/* JSON behavior.

Changes:

  • Introduces a new web/ workspace (Vite + React + Tailwind) with routes for repo status, search, symbol detail, graph, impact, re-analysis, and chat.
  • Extends the server OpenAPI + route table with SPEC-006 chat endpoints and integrates them into the web server.
  • Updates build/docs/tests to package static assets and validate UX flows via Vitest + Playwright.

Reviewed changes

Copilot reviewed 158 out of 159 changed files in this pull request and generated 7 comments.

Show a summary per file
File Description
web/vitest.config.ts Adds Vitest config for web unit tests (jsdom, setup).
web/vite.config.ts Adds Vite config (React + Tailwind, @ alias).
web/tsconfig.node.json Adds TS config for node-side tooling configs in web workspace.
web/tsconfig.json Adds TS project references for app/node configs.
web/tsconfig.app.json Adds strict TS config for the SPA source.
web/src/tests/test-utils.tsx Test helpers to render App / components.
web/src/tests/symbol-api.test.ts Verifies node-id percent-encoding in symbol API client.
web/src/tests/setup.ts Vitest setup for EventSource + matchMedia mocks.
web/src/tests/search-symbol.test.tsx UI unit test for relationship panels rendering.
web/src/tests/search-api.test.ts Verifies search API client query construction.
web/src/tests/repository-status.spec.ts Playwright UAT covering repository status states.
web/src/tests/repository-shell.test.tsx Unit test for repository shell state panels.
web/src/tests/repository-api.test.ts Verifies repos + status API clients and status classification.
web/src/tests/relationships-panel.test.tsx Unit test for flow/cluster summaries rendering.
web/src/tests/relationships-api.test.ts Verifies callers/callees API clients.
web/src/tests/reindex-panel.test.tsx Unit test for reindex progress and disconnect recovery behavior.
web/src/tests/reindex-api.test.ts Verifies reindex API client start/read calls.
web/src/tests/performance.spec.ts Playwright performance evidence check for search render mark.
web/src/tests/package-offline.spec.ts Ensures packaged preview makes no external network requests.
web/src/tests/mobile-layout.spec.ts Mobile layout regression check (no horizontal overflow).
web/src/tests/impact-route.test.tsx Unit test for impact tables rendering.
web/src/tests/impact-api.test.ts Verifies impact API client URL encoding and defaults.
web/src/tests/graph-view.test.tsx Unit test for GraphCanvas renderer wiring (mocked cytoscape).
web/src/tests/graph-uat.spec.ts Playwright UAT for nonblank graph canvas + keyboard-reachable controls.
web/src/tests/graph-transform.test.ts Unit test for graph transform -> renderer elements and summary.
web/src/tests/chat-panel.test.tsx Unit test for dormant chat state and disabled submit.
web/src/tests/chat-network.spec.ts Playwright UAT verifying chat stays same-origin (/api/chat/* only).
web/src/tests/chat-api.test.ts Verifies chat API client URL construction + bundle redemption.
web/src/tests/catalog-api.test.ts Verifies flows/clusters catalog API clients.
web/src/tests/app-shell.test.tsx Unit test for base app shell rendering and status taxonomy.
web/src/tests/accessibility.spec.ts Playwright + axe-core automated WCAG checks for core views.
web/src/routes/SymbolDetailRoute.tsx SPA route for symbol detail + related panels and actions.
web/src/routes/SearchRoute.tsx SPA route wrapper for global search workflow.
web/src/routes/RepositoryOverview.tsx SPA overview route with repo summary and navigation actions.
web/src/routes/ReindexRoute.tsx SPA re-analysis route (start job, subscribe SSE, disconnect recovery).
web/src/routes/ImpactRoute.tsx SPA impact route (load graph result, show truncation/error).
web/src/routes/GraphRoute.tsx SPA graph route (load neighborhood by depth, toolbar controls).
web/src/routes/ChatRoute.tsx SPA chat route wrapper around chat panel.
web/src/main.tsx SPA entrypoint wiring theme/tooltips/toasts and App.
web/src/lib/utils.ts Adds cn() Tailwind class merge helper.
web/src/lib/perf/marks.ts Adds perf mark/measure helpers for UI evidence.
web/src/lib/graph/transform.ts Converts graph result to cytoscape elements + summaries.
web/src/lib/graph/cytoscape.ts Creates cytoscape renderer with styles and layout defaults.
web/src/lib/api/types.ts Defines web-facing API types used by clients/components.
web/src/lib/api/symbols.ts Symbol API client wrapper.
web/src/lib/api/search.ts Search API client wrapper.
web/src/lib/api/routes.ts URL builder helpers (query param filtering, repo scoping).
web/src/lib/api/repositories.ts Repos/status API clients and status classification.
web/src/lib/api/relationships.ts Callers/callees API client wrappers.
web/src/lib/api/reindex.ts Reindex API client + EventSource subscription wrapper.
web/src/lib/api/impact.ts Impact API client wrapper.
web/src/lib/api/graph.ts Graph neighborhood API client wrapper.
web/src/lib/api/client.ts Shared API client error/envelope parsing and fetch wrappers.
web/src/lib/api/chat.ts Chat API client wrapper (status/messages/bundles).
web/src/lib/api/catalogs.ts Flows/clusters catalog API client wrappers.
web/src/lib/a11y/status-announcer.ts Adds a11y announcement model for status messages.
web/src/hooks/use-mobile.ts Adds useIsMobile() hook using matchMedia.
web/src/components/ui/tooltip.tsx Base UI tooltip wrapper component styling.
web/src/components/ui/toggle.tsx Toggle primitive wrapper + variants.
web/src/components/ui/toggle-group.tsx Toggle-group wrapper for toolbar depth controls.
web/src/components/ui/textarea.tsx Styled textarea component.
web/src/components/ui/tabs.tsx Tabs primitives wrappers + variants.
web/src/components/ui/table.tsx Styled table primitives wrappers.
web/src/components/ui/sonner.tsx Toast/Toaster wrapper with theme integration.
web/src/components/ui/skeleton.tsx Skeleton loading component.
web/src/components/ui/sheet.tsx Sheet/dialog wrapper for overlays.
web/src/components/ui/separator.tsx Separator wrapper.
web/src/components/ui/scroll-area.tsx Scroll-area wrapper.
web/src/components/ui/resizable.tsx Resizable panels wrapper.
web/src/components/ui/progress.tsx Progress primitive wrapper.
web/src/components/ui/input.tsx Styled input wrapper.
web/src/components/ui/dialog.tsx Dialog wrapper + header/footer pieces.
web/src/components/ui/checkbox.tsx Checkbox wrapper.
web/src/components/ui/card.tsx Card wrapper pieces.
web/src/components/ui/button.tsx Button wrapper + variants.
web/src/components/ui/badge.tsx Badge wrapper + variants.
web/src/components/ui/alert.tsx Alert wrapper pieces.
web/src/components/symbol/RelationshipStates.tsx Symbol relationship state panels (empty/truncated/degraded).
web/src/components/symbol/RelationshipPanels.tsx Callers/callees table panels.
web/src/components/symbol/FlowSections.tsx Execution flows + cluster summaries panels.
web/src/components/search/GlobalSearch.tsx Main search UI with URL sync + perf evidence marks.
web/src/components/reindex/ReindexProgress.tsx Re-analysis progress display and messaging.
web/src/components/reindex/ReindexControls.tsx Re-analysis control buttons (sync/full).
web/src/components/layout/Toolbar.tsx Shared toolbar layout container.
web/src/components/layout/StatePanel.tsx Shared “loading/empty/degraded/error/unauthorized” panel.
web/src/components/layout/SelectedContextBar.tsx Shows selected symbol context + quick actions.
web/src/components/layout/RepositorySwitcher.tsx Repo switcher control based on app state.
web/src/components/layout/RepositoryStatus.tsx Repo status panel and counts.
web/src/components/layout/AppShell.tsx Sidebar shell + navigation + header search shortcut.
web/src/components/impact/ImpactTables.tsx Tables for affected symbols/files.
web/src/components/impact/ImpactState.tsx Impact truncation/error panels.
web/src/components/graph/GraphToolbar.tsx Graph depth/zoom/fit/reset controls.
web/src/components/graph/GraphSummary.tsx Graph summary sidebar and kind counts.
web/src/components/graph/GraphState.tsx Graph truncation/error panels.
web/src/components/graph/GraphCanvas.tsx Cytoscape mount + selection wiring, accessible region label.
web/src/components/chat/ChatPanel.tsx Chat UI (status load, submit, response rendering).
web/src/components/chat/ChatContextBoundary.tsx Displays repo/view/selected-node context boundary chips.
web/src/app/state.tsx App state container: repos/status selection + refresh helpers.
web/src/app/routes.tsx Route table for SPA navigation.
web/src/app/App.tsx App root with router + state + shell.
web/README.md Web workspace usage and local-first boundaries.
web/playwright.config.ts Playwright config for web E2E runs and preview server.
web/package.json Web workspace dependencies and scripts.
web/index.html SPA HTML shell (inline data URI favicon).
web/eslint.config.js Web workspace ESLint flat config.
web/components.json shadcn/ui component generator config and aliases.
web/.prettierrc Web workspace Prettier config (Tailwind plugin).
web/.prettierignore Web workspace Prettier ignore list.
web/.gitignore Web workspace ignore list.
src/server/openapi.yaml Adds SPEC-006 chat schemas and paths to OpenAPI.
src/server/index.ts Wires chat routes into server route table.
src/server/chat.ts Implements SPEC-006 same-origin chat adapter routes.
scripts/copy-web-assets.mjs Build helper to copy web/dist into dist/web for packaging.
package.json Adds web workspace + build/typecheck/test wiring for packaged web assets.
README.md Updates CLI docs text for serve --web to include Web UI.
docs/web-server.md Documents web UI behavior, static asset fallback, and chat routes.
docs/ai/specs/intelligence-platform-technical-roadmap.md Updates SPEC-006 roadmap status.
CHANGELOG.md Adds user-facing changelog entry for built-in graph browser UI.
tests/server-reindex-jobs.test.ts Adds SSE reconnection/terminal-snapshot coverage.
tests/server-openapi-contract.test.ts Extends OpenAPI contract checks to include chat routes.
tests/server-chat-adapter.test.ts Adds unit tests for chat adapter dormant/errors/validation.
tests/package-web-assets.test.ts Verifies build script wires web build + asset copy, and no-CDN HTML.
specs/006-web-ui-graph-browser/SPEC-MOC.md Adds SPEC-006 map-of-content scaffold.
specs/006-web-ui-graph-browser/review-packet.md Adds human review packet and evidence/log.
specs/006-web-ui-graph-browser/contracts/web-api-contract.md Documents web app API consumption contract.
specs/006-web-ui-graph-browser/contracts/static-package-contract.md Documents static packaging + SPA fallback contract.
specs/006-web-ui-graph-browser/contracts/chat-adapter-contract.md Documents chat adapter boundary and contract expectations.
specs/006-web-ui-graph-browser/code-review.md Records self-review findings and verifications.
specs/006-web-ui-graph-browser/checklists/ux.md Generated UX checklist evidence.
specs/006-web-ui-graph-browser/checklists/requirements.md Generated spec quality checklist evidence.
specs/006-web-ui-graph-browser/checklists/accessibility.md Generated accessibility checklist evidence.
specs/006-web-ui-graph-browser/.process/emission/uat-runbook-generation.md Records deferred UAT runbook generation outcome.
specs/006-web-ui-graph-browser/.process/emission/self-review.md Records self-review outputs and verification evidence.
specs/006-web-ui-graph-browser/.process/emission/reviewability-diff-gate.md Records reviewability assessment and review order guidance.
specs/006-web-ui-graph-browser/.process/emission/pr-packet-boundary.md Records PR packet helper boundary + manual recovery.
specs/006-web-ui-graph-browser/.process/emission/integration-suite.md Records integration test commands and results.
specs/006-web-ui-graph-browser/.process/emission/final-reviewability-backstop.md Records final reviewability backstop evidence.
.specify/feature.json Points active feature directory at SPEC-006.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread web/.prettierrc Resolved
Comment thread web/.prettierignore Resolved
Comment thread web/tsconfig.node.json Resolved
Comment thread web/src/lib/api/client.ts Resolved
Comment thread web/src/lib/api/types.ts Resolved
Comment thread web/src/lib/api/repositories.ts Resolved
@fgabelmannjr
fgabelmannjr merged commit 098e49e into main Jul 16, 2026
11 checks passed
@fgabelmannjr
fgabelmannjr deleted the 006-web-ui-graph-browser branch July 16, 2026 15:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants