@reventlessdev/reventless-ppx 1.0.0-alpha.100

package/README.md

@@ -0,0 +1,81 @@
+[![npm](https://img.shields.io/npm/v/@reventlessdev/reventless-ppx.svg?label=npm)](https://www.npmjs.com/package/@reventlessdev/reventless-ppx)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Docs](https://img.shields.io/badge/docs-reventless.dev-blue)](https://docs.reventless.dev)
+
+# @reventlessdev/reventless-ppx
+
+> ⚠️ **Alpha.** APIs and on-disk formats can change without notice between releases.
+> Pin exact versions and expect breaking changes.
+
+The **ReScript PPX** for [Reventless](https://docs.reventless.dev) — a spec-driven,
+event-sourced CQRS framework written in [ReScript](https://rescript-lang.org). It
+is a compile-time preprocessor (native OCaml binary) that eliminates boilerplate
+from Reventless application code by deriving framework metadata and wiring
+directly from your component definitions.
+
+## What it provides
+
+A single PPX binary, invoked by the ReScript compiler, that runs a set of
+transforms over component source — among them: display-name and reference
+inference, DCB tag and read-consistency inference, GWT test inference,
+authorization injection, allowed-states annotations, and module-URL derivation.
+
+The package ships as a thin launcher that resolves a **prebuilt per-platform
+binary** installed as an optional dependency
+(`@reventlessdev/reventless-ppx-<platform>`), published for **macOS arm64** and
+**Linux x64** — so it installs automatically with no authentication. On platforms
+with no prebuilt binary (e.g. macOS x64, Linux arm64, Windows via WSL2), it is
+built from source with the OCaml toolchain (`opam` + `dune`).
+
+### The source reader
+
+The same package ships `reventless-ppx-read`, which prints one ReScript file's
+declarations as JSON, each with its span (byte offsets into the file) and source
+text: types with their cases, fields and attributes; top-level `let`s with a
+function's parameters and defaults; and the tests of a GWT file with their
+scenario-id markers and step values. It is for tools that edit source in place.
+
+```bash
+npx reventless-ppx-read [--bsc <path-to-bsc>] src/PlaceOrder.res
+```
+
+The file is parsed by the workspace's own ReScript compiler (found under
+`node_modules/@rescript`, or given with `--bsc`); nothing is built.
+
+## Where it fits
+
+This is build tooling shared across the framework and its example apps, not a
+runtime library. It is referenced from a package's `rescript.json` `ppx-flags`
+and runs only at compile time.
+
+## Install
+
+```bash
+pnpm add -D @reventlessdev/reventless-ppx
+```
+
+Register it in `rescript.json`:
+
+```json
+{
+  "ppx-flags": ["@reventlessdev/reventless-ppx/bin"]
+}
+```
+
+The matching platform binary is pulled in automatically via optional
+dependencies. On an unsupported platform, build from source (requires the OCaml
+toolchain):
+
+```bash
+cd src && opam exec -- dune build
+```
+
+## Links
+
+- 📚 Documentation — [docs.reventless.dev](https://docs.reventless.dev)
+- 📦 Repository — [ReventlessDev/reventless-core](https://github.com/ReventlessDev/reventless-core)
+- 📋 [Changelog](./CHANGELOG.md)
+
+## License
+
+[Apache-2.0](https://opensource.org/licenses/Apache-2.0)

package/bin

@@ -0,0 +1,52 @@
+#!/bin/sh
+# Resolve and exec the reventless-ppx native binary for the current platform.
+#
+# Resolution order:
+#   1. The matching per-platform package @reventlessdev/reventless-ppx-<platform>
+#      (declared as an optionalDependency; npm/pnpm install only the one whose
+#      os/cpu match). Three layouts covered:
+#        a. sibling in node_modules (npm flat / pnpm hoisted, same package dir)
+#        b. nested under this package's own node_modules (pnpm strict / per-pkg)
+#        c. hoisted to an ancestor node_modules (pnpm hoisted in a workspace —
+#           the per-platform pkg lands at the *workspace root* node_modules,
+#           not at the consumer's or this package's level)
+#   2. A locally-built or committed fallback binary in this directory — covers PPX
+#      development (`pnpm build:ppx`) and the pre-publish transition window.
+#
+# Windows is served via WSL2 (which presents as Linux-x86_64); there is no native
+# Windows binary.
+DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "$(uname -s)-$(uname -m)" in
+  Linux-x86_64)   PKG="linux-x64";    LOCAL="ppx-linux.exe" ;;
+  Linux-aarch64)  PKG="linux-arm64";  LOCAL="ppx-linux-arm.exe" ;;
+  Darwin-x86_64)  PKG="darwin-x64";   LOCAL="ppx-osx-x64.exe" ;;
+  Darwin-arm64)   PKG="darwin-arm64"; LOCAL="ppx-osx.exe" ;;
+  *) echo "reventless-ppx: unsupported platform $(uname -s)-$(uname -m)" >&2; exit 1 ;;
+esac
+
+# (1a) sibling in node_modules; (1b) nested under this package; (2) local fallback.
+for CAND in \
+  "$DIR/../reventless-ppx-$PKG/ppx.exe" \
+  "$DIR/node_modules/@reventlessdev/reventless-ppx-$PKG/ppx.exe" \
+  "$DIR/$LOCAL"; do
+  # `-f` (exists), not `-x`: npm/pnpm normalize file modes to 0644 when installing
+  # from a published tarball (only package.json `bin` targets are guaranteed +x),
+  # so the native binary often arrives non-executable. Restore +x, then exec.
+  if [ -f "$CAND" ]; then chmod u+x "$CAND" 2>/dev/null; exec "$CAND" "$@"; fi
+done
+
+# (1c) Walk up ancestor directories looking for a node_modules with the matching
+# per-platform package — covers pnpm's hoisted workspace layout, where the
+# optionalDep lands at the workspace root rather than at this package's level.
+ANCESTOR="$DIR"
+while [ "$ANCESTOR" != "/" ] && [ -n "$ANCESTOR" ]; do
+  ANCESTOR="$(dirname "$ANCESTOR")"
+  CAND="$ANCESTOR/node_modules/@reventlessdev/reventless-ppx-$PKG/ppx.exe"
+  if [ -f "$CAND" ]; then chmod u+x "$CAND" 2>/dev/null; exec "$CAND" "$@"; fi
+done
+
+echo "reventless-ppx: no binary found for $(uname -s)-$(uname -m)." >&2
+echo "  Expected package @reventlessdev/reventless-ppx-$PKG, or a local build at $DIR/$LOCAL." >&2
+echo "  For PPX development: (cd \"$DIR/src\" && opam exec -- dune build) && cp \"$DIR/src/_build/default/bin/bin.exe\" \"$DIR/$LOCAL\"" >&2
+exit 1

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@reventlessdev/reventless-ppx",
+  "version": "1.0.0-alpha.100",
+  "description": "ReScript PPX to eliminate boilerplate from Reventless application code",
+  "license": "Apache-2.0",
+  "files": [
+    "bin",
+    "read"
+  ],
+  "bin": {
+    "reventless-ppx": "bin",
+    "reventless-ppx-read": "read"
+  },
+  "scripts": {
+    "build:ppx": "cd src && opam exec -- dune build",
+    "clean:ppx": "cd src && opam exec -- dune clean",
+    "publish:platform": "node ../../scripts/publish-ppx-local.mjs",
+    "test": "./test/run.sh"
+  },
+  "optionalDependencies": {
+    "@reventlessdev/reventless-ppx-darwin-arm64": "1.0.0-alpha.100",
+    "@reventlessdev/reventless-ppx-linux-x64": "1.0.0-alpha.100"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ReventlessDev/reventless-core.git",
+    "directory": "packages/reventless-ppx"
+  }
+}

package/read

@@ -0,0 +1,41 @@
+#!/bin/sh
+# Resolve and exec reventless-ppx-read, the source reader, for the current platform.
+#
+#   reventless-ppx-read [--bsc <path-to-bsc>] <file.res>
+#
+# Prints the file's declarations with their spans as JSON
+# (docs/plans/done/source-reader-with-spans.md). The binary ships beside ppx.exe in the
+# per-platform package, and is found the way `bin` finds ppx.exe: sibling,
+# nested, or hoisted to an ancestor node_modules, then a local dune build.
+DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "$(uname -s)-$(uname -m)" in
+  Linux-x86_64)   PKG="linux-x64" ;;
+  Linux-aarch64)  PKG="linux-arm64" ;;
+  Darwin-x86_64)  PKG="darwin-x64" ;;
+  Darwin-arm64)   PKG="darwin-arm64" ;;
+  *) echo "reventless-ppx-read: unsupported platform $(uname -s)-$(uname -m)" >&2; exit 1 ;;
+esac
+
+# `-f`, then restore +x: installing from a tarball can drop the mode (see `bin`).
+for CAND in \
+  "$DIR/../reventless-ppx-$PKG/read.exe" \
+  "$DIR/node_modules/@reventlessdev/reventless-ppx-$PKG/read.exe"; do
+  if [ -f "$CAND" ]; then chmod u+x "$CAND" 2>/dev/null; exec "$CAND" "$@"; fi
+done
+
+ANCESTOR="$DIR"
+while [ "$ANCESTOR" != "/" ] && [ -n "$ANCESTOR" ]; do
+  ANCESTOR="$(dirname "$ANCESTOR")"
+  CAND="$ANCESTOR/node_modules/@reventlessdev/reventless-ppx-$PKG/read.exe"
+  if [ -f "$CAND" ]; then chmod u+x "$CAND" 2>/dev/null; exec "$CAND" "$@"; fi
+done
+
+# PPX development: the dune build in this package.
+CAND="$DIR/src/_build/default/read/read.exe"
+if [ -f "$CAND" ]; then exec "$CAND" "$@"; fi
+
+echo "reventless-ppx-read: no binary found for $(uname -s)-$(uname -m)." >&2
+echo "  Expected read.exe in @reventlessdev/reventless-ppx-$PKG," >&2
+echo "  or a local build at $DIR/src/_build/default/read/read.exe." >&2
+exit 1