docs: add CLAUDE.md, TODO.md, and FINDINGS.md for expert session
Co-Authored-By: Virgil <virgil@lethean.io>
This commit is contained in:
Snider
parent
66a9c71e93
commit
ab7ab92920
3 changed files with 109 additions and 0 deletions
54
CLAUDE.md
Normal file
54
CLAUDE.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
# CLAUDE.md
|
||||
|
||||
## Project
|
||||
|
||||
`go-html` is an HLCRF DOM compositor with grammar pipeline. Module path: `forge.lthn.ai/core/go-html`
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
go test ./... # Run all tests
|
||||
go test -run TestName ./... # Single test
|
||||
go test -bench . ./... # Benchmarks
|
||||
go vet ./... # Static analysis
|
||||
GOOS=js GOARCH=wasm go build -o gohtml.wasm ./cmd/wasm/ # WASM build
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
- **Node interface**: `Render(ctx *Context) string` — El, Text, Raw, If, Unless, Each[T], Switch, Entitled
|
||||
- **HLCRF Layout**: Header/Left/Content/Right/Footer compositor with ARIA roles and deterministic `data-block` IDs
|
||||
- **Responsive**: Multi-variant breakpoint wrapper (`data-variant` attributes)
|
||||
- **Pipeline**: Render → StripTags → go-i18n/reversal Tokenise → GrammarImprint
|
||||
- **Codegen**: Web Component classes with closed Shadow DOM
|
||||
- **WASM**: `cmd/wasm/` exports `renderToString()` and `registerComponents()` to JS
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `forge.lthn.ai/core/go-i18n` (replace directive → `../go-i18n`)
|
||||
- go-i18n must be present alongside this repo for builds
|
||||
|
||||
## Coding Standards
|
||||
|
||||
- UK English (colour, organisation, centre)
|
||||
- All types annotated
|
||||
- Tests use `testify` assert/require
|
||||
- Licence: EUPL-1.2
|
||||
- Safe-by-default: HTML escaping on Text nodes, void element handling, entitlement deny-by-default
|
||||
- Deterministic output: sorted attributes, reproducible paths
|
||||
|
||||
## Test Conventions
|
||||
|
||||
No specific suffix pattern — use table-driven subtests with `t.Run()`.
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `node.go` | All node types (El, Text, Raw, If, Unless, Each, Switch, Entitled) |
|
||||
| `layout.go` | HLCRF compositor |
|
||||
| `pipeline.go` | StripTags, Imprint, CompareVariants |
|
||||
| `responsive.go` | Multi-variant breakpoint wrapper |
|
||||
| `context.go` | Rendering context (Identity, Locale, Entitlements, i18n Service) |
|
||||
| `codegen/codegen.go` | Web Component class generation |
|
||||
| `cmd/wasm/main.go` | WASM entry point |
|
||||
35
FINDINGS.md
Normal file
35
FINDINGS.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
# Findings
|
||||
|
||||
## Code Quality
|
||||
|
||||
- **53 tests, 100% pass** — excellent coverage ratios across all packages
|
||||
- **Zero TODOs/FIXMEs** in codebase — clean
|
||||
- **`go vet` clean** — no static analysis warnings
|
||||
- **Safe-by-default design** — XSS prevention verified in render_test.go, HTML escaping on all Text nodes, void elements self-close, entitlements deny-by-default
|
||||
|
||||
## Architecture Strengths
|
||||
|
||||
- Clean minimal API: 9 public constructors + Node interface
|
||||
- Type-safe generics: `Each[T]` for iteration
|
||||
- Deterministic output: sorted attributes, reproducible block IDs
|
||||
- Fluent builder pattern: `NewLayout("HLCRF").H(node).C(node).F(node)`
|
||||
- Pipeline bridges rendering to privacy layer (GrammarImprint via go-i18n reversal)
|
||||
|
||||
## Known Issues
|
||||
|
||||
1. **WASM size blocker** — 6.0 MB raw / 1.58 MB gzip. Root cause: stdlib imports (json, encoding, text/template) bloat the WASM binary. Makefile rejects at 1 MB gzip threshold.
|
||||
2. **No WASM main_test.go** — cmd/wasm/ has register_test.go but no integration test for the JS exports.
|
||||
3. **Layout accepts invalid variants silently** — `NewLayout("XYZ")` renders nothing, no error returned.
|
||||
4. **Context.service is private** — Must use `NewContextWithService()`. Limits custom i18n adapter injection.
|
||||
5. **Responsive only accepts *Layout** — Cannot nest arbitrary nodes in variants, must wrap in Layout first.
|
||||
|
||||
## Coverage Gaps
|
||||
|
||||
| File | Lines | Tests |
|
||||
|------|-------|-------|
|
||||
| node.go | 254 | 206 lines of tests (81%) |
|
||||
| layout.go | 119 | 116 lines (97%) |
|
||||
| pipeline.go | 83 | 128 lines (154%) |
|
||||
| responsive.go | 39 | 89 lines (228%) |
|
||||
| codegen.go | 90 | 54 lines (60%) |
|
||||
| cmd/wasm/main.go | 78 | **0 lines (0%)** |
|
||||
20
TODO.md
Normal file
20
TODO.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
# TODO
|
||||
|
||||
## High Priority
|
||||
|
||||
- [ ] **Fix WASM binary size** — 1.58 MB gzip exceeds 1 MB limit. Move `buildComponentJS()` and JSON parsing to server-side. WASM should only expose `Render()`. Consider: pre-parsed slots, inline template execution, or TinyGo.
|
||||
- [ ] **Add WASM integration tests** — No `cmd/wasm/main_test.go`. Need JS↔Go round-trip verification.
|
||||
|
||||
## Medium Priority
|
||||
|
||||
- [ ] **Performance benchmarks** — Add `BenchmarkRender`, `BenchmarkImprint`, `BenchmarkCompareVariants`, `BenchmarkLayout` with varying tree depths.
|
||||
- [ ] **TypeScript type definitions** — Add `.d.ts` generation alongside `GenerateBundle()` for Web Component consumers.
|
||||
- [ ] **Accessibility helpers** — Layout has semantic HTML + ARIA roles but no `aria-label` builder, alt text helpers, or focus management nodes.
|
||||
- [ ] **Layout variant validation** — `NewLayout("XYZ")` silently produces empty output. Add warning or error for invalid slot characters.
|
||||
|
||||
## Low Priority
|
||||
|
||||
- [ ] **Unicode/RTL edge cases** — Test emoji, RTL text, zero-width characters in Text nodes.
|
||||
- [ ] **Deep nesting stress test** — Verify performance with deeply nested Layouts and large `Each[T]` lists.
|
||||
- [ ] **Browser polyfill documentation** — Document closed Shadow DOM support matrix.
|
||||
- [ ] **CSS scoping helper** — Optional utility for responsive variant CSS targeting.
|
||||
Loading…
Add table
Reference in a new issue