|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +This is the interactive documentation site for purescript-analyzer. It provides a browser-based playground for exploring PureScript type checking, CST parsing, and package loading via a WASM-compiled version of the compiler core. |
| 8 | + |
| 9 | +## Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Install dependencies |
| 13 | +pnpm install |
| 14 | + |
| 15 | +# Development (builds WASM + starts Vite dev server with HMR) |
| 16 | +pnpm dev |
| 17 | + |
| 18 | +# Production build (optimized WASM + minified JS) |
| 19 | +pnpm build |
| 20 | + |
| 21 | +# Type checking |
| 22 | +pnpm typecheck |
| 23 | + |
| 24 | +# Format code |
| 25 | +pnpm format |
| 26 | + |
| 27 | +# Preview production build |
| 28 | +pnpm preview |
| 29 | +``` |
| 30 | + |
| 31 | +## Architecture |
| 32 | + |
| 33 | +``` |
| 34 | +User Input (MonacoEditor) |
| 35 | + ↓ |
| 36 | +App.tsx (state management) |
| 37 | + ↓ |
| 38 | +useDocsLib hook (Comlink worker proxy) |
| 39 | + ↓ |
| 40 | +worker/docs-lib.ts (Web Worker, isolated thread) |
| 41 | + ↓ |
| 42 | +WASM engine (src/wasm/src/lib.rs) |
| 43 | + ↓ |
| 44 | +Compiler Core crates (../compiler-core/*) |
| 45 | + ↓ |
| 46 | +Results → Panel components |
| 47 | +``` |
| 48 | + |
| 49 | +**Key architectural decisions:** |
| 50 | + |
| 51 | +- **Thread isolation**: All compiler operations run in a Web Worker via Comlink, preventing UI blocking |
| 52 | +- **WASM integration**: The `src/wasm/` crate compiles to WebAssembly and exposes `parse()`, `check()`, `register_module()`, and `clear_packages()` functions |
| 53 | +- **Package system**: Fetches from `packages.registry.purescript.org`, decompresses tar.gz with pako, caches in localStorage, resolves transitive dependencies topologically |
| 54 | + |
| 55 | +## Key Directories |
| 56 | + |
| 57 | +- `src/components/` - React UI components including Monaco editor integration |
| 58 | +- `src/components/Editor/purescript.ts` - PureScript language registration for Monaco |
| 59 | +- `src/hooks/` - Custom hooks (`useDocsLib` for WASM worker, `useDebounce`) |
| 60 | +- `src/lib/packages/` - Package fetching, caching, and dependency resolution |
| 61 | +- `src/worker/` - Comlink-exposed Web Worker that loads WASM |
| 62 | +- `src/wasm/` - Rust crate that compiles to WASM, links all compiler-core crates |
| 63 | + |
| 64 | +## Stack |
| 65 | + |
| 66 | +- React 18 + TypeScript + Vite |
| 67 | +- Tailwind CSS 4 with Catppuccin theme (Macchiato dark, Latte light) |
| 68 | +- Monaco Editor for code editing |
| 69 | +- Comlink for type-safe worker communication |
| 70 | +- wasm-pack for WASM compilation |
| 71 | + |
| 72 | +## WASM Crate |
| 73 | + |
| 74 | +The `src/wasm/` directory contains a Rust crate that: |
| 75 | +- Links to 13 compiler-core crates via relative paths |
| 76 | +- Exposes functions via `wasm-bindgen` |
| 77 | +- Uses `serde-wasm-bindgen` for JS interop |
| 78 | +- Tracks performance timing via `web-sys::Performance` |
| 79 | + |
| 80 | +Rebuild WASM manually: `cd src/wasm && wasm-pack build --target web` |
0 commit comments