https://github.com/semgrep/semgrep-ocaml-visitors
A implementation of OCaml's `visitors`
https://github.com/semgrep/semgrep-ocaml-visitors
Last synced: 13 days ago
JSON representation
A implementation of OCaml's `visitors`
- Host: GitHub
- URL: https://github.com/semgrep/semgrep-ocaml-visitors
- Owner: semgrep
- Created: 2026-04-02T00:19:15.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-21T16:47:40.000Z (2 months ago)
- Last Synced: 2026-05-22T01:46:17.621Z (2 months ago)
- Language: OCaml
- Homepage:
- Size: 56.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# visitors-cleanroom
A drop-in replacement for the upstream
[visitors](https://gitlab.inria.fr/fpottier/visitors) OCaml package.
It provides:
1. **A clean-room runtime** (`visitors-cleanroom` library) -- an
independently-written `VisitorsRuntime` module, licensed LGPL-2.1
with the OCaml linking exception.
2. **The upstream PPX** (`visitors-cleanroom.ppx`) -- built from a git
submodule, configured to depend on our runtime instead of
`visitors.runtime`.
## Getting started
```sh
git clone --recurse-submodules https://github.com/semgrep/visitors-cleanroom.git
cd visitors-cleanroom
opam install ppxlib ppx_deriving result
dune build
```
If you already cloned without `--recurse-submodules`, run
`git submodule update --init`.
## Testing
Tests compare our runtime against the upstream `visitors.runtime` on
random inputs:
```sh
opam install visitors qcheck-core qcheck-alcotest alcotest
dune test
```
Passing tests produce no output. Use `dune test --force` to see
results unconditionally.
**Note:** The test suite links both our `VisitorsRuntime` and the
upstream `visitors.runtime` into the same executable for comparison.
These have different `.cmi` digests (our interface doesn't depend on
the `result` compat package). `dune test` handles this correctly
because each library is compiled in isolation, but `ocaml-lsp` may
report "inconsistent assumptions over interface VisitorsRuntime" in
the test files. This is expected and can be safely ignored.
## Benchmarks
```sh
opam install bechamel
dune exec bench/bench.exe # OO visitor benchmarks + stack depth conformance
dune exec bench/bench_functors.exe # functor-based visitor benchmarks
```
`bench_functors` compares PPX-generated OO visitors against hand-written
functor-based visitors on the same types, measuring the overhead of
virtual dispatch vs. static functor application.
## Usage
```dune
(library
(name my_lib)
(preprocess (pps visitors-cleanroom.ppx)))
```
The PPX automatically links our clean-room `VisitorsRuntime` via
`ppx_runtime_deps`.
## ppxlib compatibility
The upstream PPX submodule (`vendor/visitors/`, tag `20250212`) requires ppxlib
< 0.36.0. ppxlib 0.36.0 added `Ptyp_open` to its public AST. The upstream
visitors release `20251114` handles `Ptyp_open`, but requires ppxlib >= 0.36.0.
To upgrade, bump both together:
1. `cd vendor/visitors && git checkout 20251114`
2. Change the ppxlib constraint in `dune-project` to `(>= 0.36.0)`.
## License
The clean-room runtime (`lib/`) is licensed LGPL-2.1 with the OCaml
linking exception (Copyright 2026, Semgrep Inc.). The PPX
(`vendor/visitors/`) is the upstream source, licensed LGPL-2.1
(Copyright Francois Pottier / INRIA).