# Documentation site

This directory is a static, dependency-free documentation site for the
`datalog-dafsa` engine. It is served by GitHub Pages directly from this
`docs/` folder on the `main` branch.

## Pages

- `index.html` — overview, quickstart, feature summary.
- `language.html` — the complete Datalog Language Reference.
- `cli.html` — the 8 `dl` CLI subcommands.
- `api.html` — the full `dl.h` C API surface.
- `architecture.html` — storage thesis, lifecycle, join & evaluation strategies.
- `order-statistics.html` — rank / select / range_count / count, bound + perm
  variants, pull-iterator + merge-join, lazy range generator.
- `time-travel.html` — versioned snapshots, as-of queries, retention.
- `playground.html` — an interactive in-browser evaluator (WebAssembly).
- `playground-ui.js` — the committed page glue + wasm bridge (loaded by
  `playground.html` after the factory).
- `playground.js` / `playground.wasm` — the compiled emscripten bundle
  (generated by `make wasm`, committed; no build step at deploy time).
- `style.css` — the shared theme (plus the playground's controls).

All navigation is plain relative links; there is no build step.

## The playground

`playground.html` runs the real C engine — compiled to WebAssembly — entirely
in the browser. It uses a **CodeMirror editor**: type facts + rules, pick a
goal relation, and press **Run**; the engine evaluates the program in memory
and streams the result. As you type, the editor shows **live diagnostics** and
**hover** from the real LSP server compiled to WebAssembly (`docs/dl-lsp.js`),
so syntax and compile errors are underlined inline. The supported subset is the
in-memory feature set (facts, rules/recursion, stratified negation, aggregates,
arithmetic, comparisons, strings, lists, the range predicate, regex walks);
disk-backed features (publish/snapshot, time-travel, variadic relations, the
WAL/incremental-maintenance API) are not available in the browser. See the
"Supported subset" section on the page for the honest list, including the
int-vs-symbol rendering caveat.

To rebuild the WebAssembly bundle from source:

```sh
make wasm        # runs scripts/build-wasm.sh then the wasm smoke tests
```

`scripts/build-wasm.sh` compiles `src/playground-wasm.c` (evaluation) and
`src/lsp.c` (the LSP server) with the full engine core via emscripten and emits
`docs/playground.js`/`.wasm` + `docs/dl-lsp.js`/`.wasm`. It requires emscripten
+ node on the host (see the script header). The generated files are committed
to `docs/`, so the Pages site itself needs no build toolchain.
`tests/wasm-smoke.js` asserts the playground produces byte-identical output to
the native engine; `tests/lsp-wasm-smoke.js` drives the wasm LSP
(initialize/didOpen/didChange/hover/completion).

## Language Server (IDE support)

A native LSP server for the Datalog language ships as `dl-lsp` (build with
`make lsp`). It speaks LSP (JSON-RPC 2.0 over stdio with Content-Length
framing) and reuses the real parser/compiler, so its diagnostics are exactly
what the engine rejects. Supported: diagnostics-as-you-type, hover (predicate
arity + IDB/EDB, variables, builtins), and completion (relations + builtins +
bound variables).

```sh
make lsp           # build ./dl-lsp
make test-lsp      # run the end-to-end LSP test harness (tests/lsp.sh)
```

To use it in an editor, point the editor's Datalog language server at
`./dl-lsp` (e.g. for Neovim's LSP config: `cmd = { "/abs/path/dl-lsp" }`).
`tests/lsp.sh` shows a complete JSON-RPC conversation you can replay against any
client.

## Enabling GitHub Pages

1. In the repository on GitHub, open **Settings**.
2. In the left sidebar, under **Code and automation**, select **Pages**.
3. Under **Build and deployment → Source**, choose **GitHub Actions**
   (this repo ships a `.github/workflows/pages.yml` that deploys `docs/` on
   every push to `main`).
4. Once the workflow has run, the site is published at
   `https://<user>.github.io/<repository>/` (rendering `docs/index.html`
   automatically). The exact URL depends on the repository owner and name.

## Notes

- Every syntax example is a real construct the parser and compiler accept;
  see the test suite under `../tests/` for the source of most examples.
- The content is deliberately conservative: no performance numbers are quoted
  (see `../tests/bench.c` for the benchmark harness).