Split mldoc library, CLI, JS and benchmark opam packages

.github/workflows/ci.yml

@@ -17,6 +17,7 @@ jobs:
       fail-fast: false
       matrix:
         ocaml-compiler: ["4.14.x", "5.3.x"]
+        package: [mldoc, mldoc-cli, mldoc-js, mldoc-bench]
     steps:
       - uses: actions/checkout@v4
 
@@ -27,10 +28,22 @@ jobs:
           dune-cache: true
 
       - name: Install dependencies
-        run: opam install . --deps-only --with-doc --with-test
+        run: |
+          opam pin add -yn mldoc .
+          if [ "${{ matrix.package }}" = mldoc ]; then
+            opam install ./mldoc.opam --with-doc --with-test
+          else
+            opam install ./${{ matrix.package }}.opam
+          fi
 
-      - name: Build
-        run: opam exec -- dune build @install @JS @main
+      - uses: actions/setup-node@v4
+        if: matrix.package == 'mldoc-js'
+        with:
+          node-version: '22'
+
+      - name: Test installed package
+        run: opam exec -- sh test/package_smoke.sh ${{ matrix.package }} "$(opam var prefix)"
 
       - name: Test
-        run: opam exec -- dune runtest
+        if: matrix.package == 'mldoc'
+        run: opam exec -- dune runtest -p mldoc

bench/dune

@@ -1,15 +1,28 @@
 (executable
  (name bench)
+ (public_name mldoc-bench)
+ (package mldoc-bench)
  (libraries angstrom mldoc core core_bench core_unix.command_unix))
 
 (executable
  (name time_parse)
+ (public_name mldoc-time-parse)
+ (package mldoc-bench)
  (libraries unix mldoc))
 
 (executable
  (name time_graph)
+ (public_name mldoc-time-graph)
+ (package mldoc-bench)
  (libraries unix mldoc))
 
 (alias
  (name bench)
  (deps bench.exe time_parse.exe time_graph.exe))
+
+(install
+ (package mldoc-bench)
+ (section share)
+ (files
+  (../examples/doc.org as examples/doc.org)
+  (../examples/syntax.md as examples/syntax.md)))

bin/dune

@@ -1,6 +1,7 @@
 (executable
  (name main)
  (public_name mldoc)
+ (package mldoc-cli)
  (libraries angstrom mldoc cmdliner lwt.unix))
 
 (alias

deploy-npm-package

@@ -1,6 +1,7 @@
 #!/bin/sh
 
-make
+set -e
+make js
 
 cp _build/default/js/lib.bc.js ./js/package/index.js
 cd ./js/package && npm publish

js/dune

@@ -7,6 +7,11 @@
  (js_of_ocaml (flags --target-env browser))
  (libraries angstrom js_of_ocaml mldoc))
 
+(install
+ (package mldoc-js)
+ (section share)
+ (files (lib.bc.js as index.js)))
+
 (alias
  (name JS)
  (deps lib.bc.js))

makefile

@@ -1,24 +1,39 @@
 DUNE ?= dune
+OPAM ?= opam
+.DEFAULT_GOAL := core
 
 all:
-	opam install --deps-only .
-	$(DUNE) build --profile=release @install @JS @main @bench
+	$(OPAM) install --working-dir --deps-only ./mldoc.opam ./mldoc-cli.opam ./mldoc-js.opam ./mldoc-bench.opam
+	$(DUNE) build -p mldoc,mldoc-cli,mldoc-js,mldoc-bench @install @JS @main @bench
 
-check: tests
+core:
+	$(OPAM) install --working-dir --deps-only ./mldoc.opam
+	$(DUNE) build -p mldoc @install
+
+cli:
+	$(OPAM) install --working-dir --deps-only ./mldoc.opam ./mldoc-cli.opam
+	$(DUNE) build -p mldoc,mldoc-cli @install @main
+
+js:
+	$(OPAM) install --working-dir --deps-only ./mldoc.opam ./mldoc-js.opam
+	$(DUNE) build -p mldoc,mldoc-js @install @JS
+
+check: test
 
 test:
-	opam install --deps-only -t .
-	$(DUNE) runtest
+	$(OPAM) install --working-dir --deps-only -t ./mldoc.opam
+	$(DUNE) runtest -p mldoc
 
 clean:
 	dune clean
-run:
+run: cli
 	$(DUNE) exec ./bin/main.exe
 
 bench:
-	$(DUNE) exec ./bench/bench.exe
+	$(OPAM) install --working-dir --deps-only ./mldoc.opam ./mldoc-bench.opam
+	$(DUNE) build -p mldoc,mldoc-bench @install @bench
 
 fmt:
 	dune build @fmt --auto-promote
 
-.PHONY: pin test all clean check bench fmt
+.PHONY: core cli js test all clean check run bench fmt

mldoc-bench.opam

@@ -0,0 +1,20 @@
+opam-version: "2.0"
+synopsis: "Benchmark and timing tools for Mldoc"
+maintainer: ["logseq team"]
+authors: ["tiensonqin <tiensonqin@gmail.com>" "RCmerci <rcmerci@gmail.com>"]
+license: "AGPL-3.0-only"
+homepage: "https://github.com/logseq/mldoc"
+bug-reports: "https://github.com/logseq/mldoc/issues"
+available: os != "win32"
+depends: [
+  "dune" {>= "3.5"}
+  "ocaml" {>= "4.14.0"}
+  "mldoc" {= version}
+  "core"
+  "core_bench"
+  "core_unix"
+]
+build: [
+  ["dune" "subst"] {dev}
+  ["dune" "build" "-p" name "-j" jobs "@install"]
+]

mldoc-cli.opam

@@ -0,0 +1,18 @@
+opam-version: "2.0"
+synopsis: "Native command-line converter for Mldoc"
+maintainer: ["logseq team"]
+authors: ["tiensonqin <tiensonqin@gmail.com>" "RCmerci <rcmerci@gmail.com>"]
+license: "AGPL-3.0-only"
+homepage: "https://github.com/logseq/mldoc"
+bug-reports: "https://github.com/logseq/mldoc/issues"
+depends: [
+  "dune" {>= "3.5"}
+  "ocaml" {>= "4.14.0"}
+  "mldoc" {= version}
+  "cmdliner" {>= "1.1.0"}
+  "lwt"
+]
+build: [
+  ["dune" "subst"] {dev}
+  ["dune" "build" "-p" name "-j" jobs "@install"]
+]

mldoc-js.opam

@@ -0,0 +1,18 @@
+opam-version: "2.0"
+synopsis: "JavaScript export of Mldoc"
+maintainer: ["logseq team"]
+authors: ["tiensonqin <tiensonqin@gmail.com>" "RCmerci <rcmerci@gmail.com>"]
+license: "AGPL-3.0-only"
+homepage: "https://github.com/logseq/mldoc"
+bug-reports: "https://github.com/logseq/mldoc/issues"
+depends: [
+  "dune" {>= "3.5"}
+  "ocaml" {>= "4.14.0"}
+  "mldoc" {= version}
+  "js_of_ocaml" {>= "5.2.0"}
+  "js_of_ocaml-ppx" {build}
+]
+build: [
+  ["dune" "subst"] {dev}
+  ["dune" "build" "-p" name "-j" jobs "@install"]
+]

mldoc.opam

@@ -5,22 +5,17 @@ description:
   "Another Org-mode and Markdown parser implemented using OCaml and Angstrom."
 maintainer: ["logseq team"]
 authors: ["tiensonqin <tiensonqin@gmail.com>" "RCmerci <rcmerci@gmail.com>"]
+license: "AGPL-3.0-only"
 homepage: "https://github.com/logseq/mldoc"
 bug-reports: "https://github.com/logseq/mldoc/issues"
 depends: [
   "dune" {>= "3.5"}
   "ocaml" {>= "4.14.0"}
   "angstrom" {= "dev"}
-  "cmdliner" {>= "1.1.0"}
-  "core" {os != "win32"}
-  "core_bench" {os != "win32"}
-  "core_unix" {os != "win32"}
-  "js_of_ocaml" {>= "5.2.0"}
-  "js_of_ocaml-ppx"
+  "bigstringaf"
   "ppx_deriving_yojson"
   "uri"
   "yojson"
-  "lwt"
   "xmlm" {= "dev"}
   "odoc" {with-doc}
   "alcotest" {with-test}
@@ -42,6 +37,6 @@ build: [
   ]
 ]
 pin-depends: [
-  [ "angstrom.dev" "git+https://github.com/logseq/angstrom#fork" ]
+  [ "angstrom.dev" "git+https://github.com/logseq/angstrom#3be9b966dc2bc9ccf9948d17a7b0df1cb526de15" ]
   [ "xmlm.dev" "git+https://github.com/logseq/xmlm#eb469d536e98c98f2754c0ff8813c92b3a17fe9f" ]
 ]

readme.org

@@ -6,12 +6,64 @@
    - [[https://logseq.com][Logseq]], a local-first notes app (In development)
 
 ** Build
+   The OCaml library remains named =mldoc=, with the same public modules and
+   parsing/export interfaces. Tools are installed through separate opam packages:
+
+   | Package       | Purpose and installed artifacts                                      |
+   |---------------+----------------------------------------------------------------------|
+   | =mldoc=       | OCaml library; no CLI, JS toolchain, or Core benchmark dependencies    |
+   | =mldoc-cli=   | Native =mldoc= command; adds Cmdliner and Lwt                          |
+   | =mldoc-js=    | =$(opam var mldoc-js:share)/index.js=; adds js_of_ocaml and its PPX     |
+   | =mldoc-bench= | =mldoc-bench=, =mldoc-time-parse=, =mldoc-time-graph=; adds Core packages |
+
+   Companion packages require the matching version of the core library.
+   Core keeps the Angstrom lookahead/continuation fork and Xmlm attribute-newline
+   fork, both pinned to commits. Only the benchmark package is unavailable on
+   Windows because it depends on Jane Street's native benchmark tools.
+
    #+begin_src sh
-     # compile
+     # default: build only the library
      make
 
-     # run test
+     # independently build optional targets
+     make cli
+     make js
+     make bench
+
+     # all targets (includes native benchmarks)
+     make all
+
+     # existing library regression tests
      make test
+
+     # install the library from this checkout
+     opam install ./mldoc.opam
+
+     # register this checkout's core, then install one matching companion
+     opam pin add -yn --kind=path mldoc .
+     opam install ./mldoc-cli.opam
+     # or: ./mldoc-js.opam / ./mldoc-bench.opam
+   #+end_src
+
+   Use an explicit manifest for a single package. =opam install .= selects all
+   packages in the checkout. Make's optional targets build the local core and
+   selected tool together; a companion's opam build uses the installed library.
+
+   The JS opam package provides the existing =Mldoc= JavaScript export; it does
+   not install the npm command wrapper. The npm package and its Node CLI remain
+   available as before. =deploy-npm-package= builds only the JS target.
+
+   Installed benchmarks include their example inputs. Run fixture-generating
+   timing tools in a writable scratch directory, and pass an explicit synthetic
+   or intended graph directory to =mldoc-time-graph=:
+
+   #+begin_src sh
+     bench_dir=$(mktemp -d)
+     cp -R "$(opam var mldoc-bench:share)/examples" "$bench_dir/"
+     cd "$bench_dir"
+     mldoc-bench -help
+     mldoc-time-parse
+     mldoc-time-graph /path/to/benchmark-fixture
    #+end_src
 
 ** Run utop
@@ -35,8 +87,8 @@
 
 *** For OCaml users
     #+BEGIN_SRC sh
-      # compile
-      make
+      # compile the native CLI
+      make cli
 
       # convert org file to html
       _build/default/bin/main.exe ./test.org -o ./test.html

test/package_js_smoke.js

@@ -0,0 +1,29 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const vm = require('node:vm');
+const artifact = process.argv[2];
+const config = JSON.stringify({ format: 'Markdown', keep_line_break: false });
+
+function check(mldoc) {
+  assert.ok(mldoc, 'existing Mldoc export');
+  for (const input of ['', '- Package smoke λ with [[page]]\r\n']) {
+    const ast = JSON.parse(mldoc.parseJson(input, config));
+    assert.ok(Array.isArray(ast));
+    if (input) assert.ok(ast.length > 0);
+  }
+  assert.ok(Array.isArray(JSON.parse(mldoc.parseInlineJson('[[page]] λ', config))));
+  const opml = JSON.parse(mldoc.parseOPML(
+    '<opml version="2.0"><head><title>smoke</title></head>' +
+    '<body><outline text="Package smoke" _note="line1&#10;line2"/></body></opml>'
+  ));
+  assert.ok(JSON.stringify(opml).includes('line1\\nline2'), 'OPML attribute newline');
+  assert.ok(mldoc.export('markdown', '- Package smoke λ\n', config, '{}').includes('Package smoke'));
+}
+
+check(require(artifact).Mldoc);
+const browser = vm.createContext({ console, setTimeout, clearTimeout, TextEncoder, TextDecoder });
+vm.runInContext(fs.readFileSync(artifact, 'utf8'), browser, { filename: artifact });
+check(browser.Mldoc);
+console.log('installed JS export (Node and browser context): OK');