Andy Dixon
d7318acede
README covers what CodeNavigator is, screenshots of each view, quick start, configuration, keyboard shortcuts and links to docs/: a city guide (what every visual means, getting around), architecture (indexer, sessions, GitHub, rendering passes, routing), the HTTP API, GitHub App setup including the alert permissions, deployment (Docker, systemd, nginx, limits, security notes) and development (tests, layout, conventions, design notes).
76 lines
3.3 KiB
Markdown
76 lines
3.3 KiB
Markdown
# Development
|
|
|
|
Requirements: Go 1.26+, git, and Node 20+ (only to run the frontend tests).
|
|
|
|
```bash
|
|
go run . # http://127.0.0.1:4177, frontend served from web/ via go:embed
|
|
SHOW_LOCAL=true go run . # also allow local folder uploads
|
|
```
|
|
|
|
The frontend is embedded at build time, so **restart `go run` after changing files in `web/`**.
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
go test -race ./... # server, indexer, GitHub flows (fake GitHub)
|
|
node --test webtest/*.test.mjs # frontend maths: camera, city, routing, signs, posters
|
|
go test -run x -bench Index # indexing benchmark on $CODENAV_BENCH_DIR (default: Go's stdlib)
|
|
```
|
|
|
|
What the suites cover:
|
|
|
|
- **Go:**
|
|
- Indexing: ignore rules, parsing and linking.
|
|
- Jobs: the local job lifecycle end to end (upload → SSE → scene → source release), session
|
|
isolation, expiry and eviction, the concurrency queue, SSE keep-alives, and the `SHOW_LOCAL` gate.
|
|
- GitHub: the sign-in flow including forged and reused state, clone token handling and timeouts,
|
|
security alert pagination and permissions.
|
|
- **Node:**
|
|
- Camera: parity with the original landscape projection.
|
|
- City: layout invariants (no overlaps, avenue widths), collision and movement, routing (detours,
|
|
enclosed buildings, a large-city time budget), ribbon lanes and mitred corners.
|
|
- Signs and walls: sign readability and placement, hazard tape, walls and posters, text fitting.
|
|
- Other: residents staying walkable, and place links rejecting untrusted input.
|
|
|
|
## Project layout
|
|
|
|
```
|
|
main.go HTTP server, sessions, jobs, snapshots, expiry
|
|
github.go GitHub App sign-in, clone command, security alerts
|
|
indexer.go Walking, parsing, linking, classification
|
|
*_test.go Go tests
|
|
web/
|
|
index.html Markup
|
|
styles.css All styling (see the design notes below)
|
|
app.js UI, input, overlays, city orchestration
|
|
renderer.js WebGL2 passes and shaders
|
|
city.js Pure city logic (layout, routing, signs, residents…)
|
|
camera.js Matrix maths
|
|
labels.js Sign atlas, poster atlas, text fitting
|
|
api.mjs fetch + SSE helpers
|
|
fonts/ Self-hosted Archivo Black, Atkinson Hyperlegible, Space Mono
|
|
webtest/ node:test suites for web/ modules
|
|
docs/ This documentation and screenshots
|
|
Dockerfile, build.sh
|
|
```
|
|
|
|
## Conventions
|
|
|
|
- **No dependencies:** the Go side uses only the standard library, and the frontend is plain ES
|
|
modules with no bundler.
|
|
- **Keep logic testable:** anything that can be pure maths or data goes in `city.js`, `camera.js`
|
|
or `labels.js`, with a `node:test` test. `app.js` wires it to the DOM and `renderer.js` draws it.
|
|
- **Commits** are small and describe why, not just what.
|
|
|
|
## Design notes
|
|
|
|
The interface is deliberately hand-made rather than polished:
|
|
|
|
- **Colour:** flat warm ink surfaces, hard 2px black edges, offset shadows instead of blur, and a
|
|
clashing lime/pink/sky/tangerine palette.
|
|
- **Type:** chunky Archivo Black headings, Atkinson Hyperlegible body text and Space Mono labels.
|
|
- **Personality:** small tilts, stickers and wiggles give it some energy. Everything animated
|
|
respects `prefers-reduced-motion`.
|
|
- **Tokens:** colours and fonts are CSS variables at the top of `styles.css`, and the city's
|
|
palette lives in the shaders in `renderer.js`.
|