// SPDX-License-Identifier: CC-BY-SA-4.0
= rescript-ecosystem
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
:toc: macro
:toclevels: 3

Consolidation monorepo for hyperpolymath ReScript packages. The target
layout is 5 groups (core, web, bindings, FFI, tooling) plus standalone
top-level packages; consolidation is **in progress, not complete**.

toc::[]

== Overview

This monorepo is the destination for previously-separate hyperpolymath
ReScript repositories. Consolidation is a live, partial migration — *not*
a finished state:

* Some `packages/*` entries are populated (e.g. `core/poly-core`,
  `web/tea`, `tooling/evangeliser`); others are empty scaffolds
  (e.g. `web/full-stack`, `bindings/postgres`) awaiting their source.
* Several large packages currently live as top-level directories
  (`rescript/`, `idaptik-rescript13-staging/`, `cadre-router/`,
  `rescript-tea/`, …) and are *not yet* deduplicated into `packages/`.
  Note `rescript-tea` currently exists **both** top-level and as
  `packages/web/tea` — a known duplication pending reconciliation.
* The mechanism is **in-tree, history-preserving relocation** (not git
  submodules). Source repos are retired only *after* their content is
  merged and verified here (reversible until then).

For authoritative per-package origin, status, and outstanding
reconciliation work, see link:MIGRATION.adoc[MIGRATION.adoc]. For the
community/transfer position see link:TRANSFER.adoc[TRANSFER.adoc].

== Package Groups (target layout)

NOTE: The tables below describe the *target* organization. Presence here
does not imply the package is fully populated — consult
link:MIGRATION.adoc[MIGRATION.adoc] for actual state.

=== Core (`packages/core/`)

Foundation libraries used across the ecosystem.

[cols="1,2,1"]
|===
| Package | Description | Origin

| `poly-core`
| Core utilities and shared primitives for poly-rescript projects
| rescript-poly-core

| `env`
| Environment variable handling and configuration
| rescript-env

| `runtime-tools`
| Runtime debugging and development utilities
| rescript-runtime-tools

| `early-return`
| Early return control flow for ReScript
| rescript-early-return

| `compiler-source`
| ReScript compiler source analysis and tooling
| rescript-compiler-source
|===

=== Web (`packages/web/`)

Web frameworks, servers, and browser-side libraries.

[cols="1,2,1"]
|===
| Package | Description | Origin

| `tea`
| The Elm Architecture (TEA) for ReScript
| rescript-tea

| `dom-mounter`
| DOM mounting utilities for ReScript web apps
| rescript-dom-mounter

| `full-stack`
| Full-stack ReScript application framework
| rescript-full-stack

| `http-server`
| HTTP server bindings for ReScript
| rescript-http-server

| `websocket`
| WebSocket client/server bindings
| rescript-websocket

| `bridge-web`
| Web bridge for cross-platform ReScript apps
| bridge-web-rescript
|===

=== Bindings (`packages/bindings/`)

ReScript bindings to external services and libraries.

[cols="1,2,1"]
|===
| Package | Description | Origin

| `postgres`
| PostgreSQL client bindings
| rescript-postgres

| `redis`
| Redis client bindings
| rescript-redis

| `grpc`
| gRPC client/server bindings
| rescript-grpc

| `openapi`
| OpenAPI specification generation and consumption
| rescript-openapi

| `d3`
| D3.js data visualization bindings
| rescript-d3

| `tauri`
| Tauri 2.0 desktop/mobile app bindings
| rescript-tauri
|===

=== FFI (`packages/ffi/`)

Foreign Function Interface bridges for native code interop.

[cols="1,2,1"]
|===
| Package | Description | Origin

| `zig-ffi`
| Zig FFI bridge for ReScript via WASM/native
| rescript-zig-ffi

| `wasm-runtime`
| WebAssembly runtime for ReScript
| rescript-wasm-runtime

| `wasm-bridge`
| WASM-ReScript bridge utilities
| wasm-rescript-bridge

| `alib`
| Aggregate Library (ALib) FFI layer for ReScript
| rescript-alib
|===

=== Tooling (`packages/tooling/`)

Developer tools, code generators, and migration utilities.

[cols="1,2,1"]
|===
| Package | Description | Origin

| `evangeliser`
| ReScript adoption and migration assistant
| rescript-evangeliser

| `create-poly`
| Project scaffolding for poly-rescript apps
| create-rescript-poly

| `greasy-rescripter`
| Bulk ReScript codemod and transformation tool
| greasy-rescripter

| `alib-codemods`
| ALib-specific code transformations
| alib-codemods

| `alib-conformance`
| ALib conformance test suite
| alib-conformance-suite

| `alib-interop`
| ALib interoperability patterns and examples
| alib-interop-patterns

| `alib-for-rescript`
| ALib integration layer for ReScript
| alib-for-rescript
|===

== Excluded Repositories

The following ReScript-related repos are intentionally kept separate:

* **asdf-rescript-plugin** -- Must remain standalone due to asdf plugin registry constraints
* **zotero-rescript-templater** -- Belongs to the Zotero tooling cluster

== Usage

=== Prerequisites

* https://deno.com[Deno] (runtime and package management)
* https://rescript-lang.org[ReScript] compiler
* https://github.com/casey/just[just] (command runner)

=== Commands

[source,bash]
----
# List all available commands
just

# List all packages
just list-packages

# Show file statistics
just stats

# Build all packages
just build-all

# Build a specific package
just build core/poly-core

# Clean build artifacts
just clean-all
----

== License

SPDX-License-Identifier: CC-BY-SA-4.0

Copyright (C) 2024-2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>

This project is licensed under the Palimpsest License (PMPL-1.0-or-later).
See link:LICENSE[LICENSE] for the full text.
