hemx/docs/diagnostics.md

# Diagnostics guide

hemx diagnostics should tell a Rust developer which template fact, generated
helper, or handler shape is wrong, and what to change next. They should not teach
raw ids, selector targeting, runtime opcodes, or Cargo internals in the normal
path. req: diagnostics/001 req: diagnostics/002 req: diagnostics/003

Use this guide as the v1 checklist for common mistakes in beginner and
production-shaped apps. Structured `hemx-build` diagnostics expose a file path,
directive, target, expected template fact, and repair action so an optional
editor overlay can share compiler authority without becoming a custom editor
framework.

## Where errors happen

- **Template/build diagnostics** come from `hemx_build::app().run()` while reading
  `.heml` files and CSS. Fix the template or generated-surface convention.
- **Derive/compile diagnostics** come from `#[hemx::surface]`, `#[hemx::form]`,
  `#[hemx::handler]`, `#[hemx::component]`, and `#[hemx::app]`. Fix Rust code so
  it matches the generated surface.
- **Runtime diagnostics** come from the tiny browser runtime when a deployed page
  and response are incompatible or a target cannot be applied. Fix deployment or
  recover with a full page response. req: failure/005

## Common mistakes and fixes

| Mistake | Diagnostic shape | Fix |
| --- | --- | --- |
| Handler has no matching template handle | `unknown hemx handle \`save\`; add \`data-hemx-handle="save"\`` | Add the handle to the template, rename the function, or put the handler in the matching component. |
| Component is missing a generated handler | `#[hemx::component] missing handler implementation(s): delete` | Add a `#[hemx::handler] fn delete(...)` in that component, or remove the template handle. |
| Handler name is ambiguous across components | `ambiguous generated handle name(s): save` | Scope the component with `#[hemx::component("todos")]` or rename handles so the generated path is unique. |
| Handler misses generated params | `hemx handler \`show\` is missing generated param argument(s): mode` | Add typed handler arguments for every `data-hemx-param-*` fact generated by the template. |
| Form handler omits the form argument | `handles a generated form and must accept a typed form argument` | Accept `Form<NewThing>`/`hemx::Form<NewThing>`/integration equivalent and derive `#[hemx::form("...")]` for the type. |
| Form struct misses a control | `hemx form \`new_todo\` is missing field \`title\`` | Add a Rust field matching the form control name, or rename the template control. |
| Required/multiple form control has wrong Rust shape | `required ... must not be Option<_>` or `accepts multiple values and must be Vec<_>` | Match HTML required/multiple semantics with `T`, `Option<T>`, or `Vec<T>` as appropriate. |
| Form field type cannot parse submitted values | compiler mentions `T: FormValue` / `T: hemx::FormValue` | Implement `FromStr`/the expected form value trait for the domain newtype, or use a parseable domain type. |
| Generated resources are unavailable | `could not find generated hemx module` / `could not find generated hemx symbols` plus `add hemx_build::app().run()? to build.rs` | Add or fix `build.rs`, then rerun `cargo check`; do not copy `$OUT_DIR` paths into app code. |
| Unknown `data-hemx-*` attribute | `unknown hemx attribute ... check the spelling or use a non-hemx data-* attribute` | Fix the spelling, use the supported hemx attribute, or rename app metadata to a non-hemx `data-*` attribute. |
| Selector-style targeting | ``data-hemx-target` is selector-style targeting; hemx uses generated resources` | Put `data-hemx-slot` on the local target and return a generated slot/page/form effect. |
| Generated target appears in a loop without a stable key | `inside an h-for without h-key; add a stable h-key="item.id"` | Add a stable `h-key` to the owning loop; use generated keyed helpers for row updates. |
| Page/SSE attributes are on the wrong element | `expected a real <a href=...>` / `expected placement on the same element as data-hemx-root` | Keep page navigation on anchors and put root-scoped runtime attributes on the root element. |
| Result handler error type is not mappable | compiler reports the error type does not satisfy `IntoHandlerFailure` | Implement `IntoHandlerFailure` for the app error, or keep expected validation as generated UI effects instead of `Err`. req: failure/004 |
| Old page talks to a new server/runtime | runtime refuses the partial update on fingerprint mismatch | Serve a self-consistent release or fall back to full page reload/navigation. See `docs/recipes/deploy-versioning.md`. req: abi/004 |
| Missing runtime target | runtime emits a missing-target diagnostic in development and fails/no-ops according to target kind | Fix the template/generated helper mismatch; do not retarget with selectors. req: failure/001 |

## What a good diagnostic should include

A v1-quality diagnostic should include:

- the user-facing name: handle, form, slot, key, param, class, event, or template
- the source area: template path, Rust item, or deployment/runtime boundary
- the concrete expected shape, not an internal representation
- one next action that preserves generated helpers and the tiny runtime

Avoid beginner-facing messages that suggest `ResourceId`, `ResourceRef`, raw
`Effect`, manual registries, selector strings, or runtime opcodes. If an advanced
escape hatch is genuinely required, say that it is advanced and name the safer
normal path first. req: public_api/002 req: public_api/005

## Editor overlay boundary

A `.heml` editor overlay is optional and subordinate to the compiler. It may read
`docs/hemplate-syntax.md`, run or reuse `hemx-build` diagnostics, and present
compiler-shaped diagnostics, completion, hover, and navigation for documented
syntax and generated targets. It must not define a second template language,
formatter, selector targeting model, JavaScript expression layer, or custom editor
framework. If editor feedback disagrees with `hemx-build`, `hemx-build` wins.
req: diagnostics/004

## Verification anchors

Current recurring checks cover the most common classes:

- `cargo test -p hemx-build` covers template/build diagnostics such as unknown
  hemx attributes, selector-style targeting, invalid runtime attribute values,
  missing keys, and invalid page/SSE placement.
- `cargo test -p hemx-derive --test compile_fail` covers derive/compile
  diagnostics for missing handlers, form mismatch, params, missing generated
  files, unknown scoped components, ambiguous handles, and generated resource
  lookup.
- `cargo test -p hemx-js` covers root-scoped runtime behavior, selectorless
  targeting, fingerprint mismatch refusal, SSE application, and recoverable
  runtime events.
- `cargo test -p hemx-test --test examples_contract` keeps public examples from
  teaching forbidden normal-path constructs.

Before claiming the diagnostics story is closed for v1, run those gates plus
`cargo run -p hemx-xtask -- test`, `cargo check --workspace`, and
`redgate refs` on a clean tree. The installed CLI's `health` mode additionally requires every historical row to use its newer prescriptive wording, which is not the elected compatibility gate for this corpus. req: test/003 req: test/004