Repository navigation
feat(SPEC-006): add web graph browser - #153
Merged
Merged
Conversation
There was a problem hiding this comment.
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.
# Conflicts: # .specify/feature.json # docs/ai/specs/.process/autopilot-state.json # package.json
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
SPEC-006 Review Packet
Review Order
package.json,scripts/copy-web-assets.mjs,src/server/static.ts,src/server/index.ts,src/server/chat.ts,src/server/openapi.yaml.web/index.html,web/src/app/, shared API clients, layout, and state components.docs/web-server.md,README.md,CHANGELOG.md, and this packet.Scope Budget
dist/web/;/api/*remains JSON-only and is not swallowed by SPA fallback.Traceability
web/src/components/layout/RepositorySwitcher.tsx,RepositoryStatus.tsx,RepositoryOverview.tsx,web/src/tests/repository-status.spec.ts.web/src/routes/SearchRoute.tsx,SymbolDetailRoute.tsx,web/src/tests/search-symbol.test.tsx.RelationshipPanels.tsx,FlowSections.tsx, catalog API tests.GraphRoute.tsx,GraphCanvas.tsx,GraphToolbar.tsx,web/src/tests/graph-view.test.tsx,graph-uat.spec.ts.ImpactRoute.tsx,ImpactTables.tsx,impact-route.test.tsx.ReindexRoute.tsx,ReindexProgress.tsx,server-reindex-jobs.test.ts,reindex-panel.test.tsx.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:
http://127.0.0.1:<port>.CodeGraph, repo picker/status, and self-repo counts./search?q=startWebServer; saw 17 matches and openedstartWebServer.donewithChecked 712 files; 0 changed; updated 0 nodes.scrollWidth=375,innerWidth=390.The MCP pass found one real issue: quick terminal EventSource close left the UI on
Disconnectedeven thoughGET /api/reindex/:repohad a terminaldonesnapshot. Fixed inReindexRoute.tsxby polling the latest job on disconnect and covered inreindex-panel.test.tsx.Known Gaps
npm testrequires the local Git signing override on this machine because inherited config signs temporary fixture commits; the suite passed with that override.Rollback Notes
copy-web-assets, theweb/workspace, and the static mount changes;/api/*contracts should remain independently reviewable.src/server/chat.ts, its route wiring, and the OpenAPI chat paths.web/src/routes/ReindexRoute.tsxandweb/src/components/reindex/ReindexProgress.tsx.