A port of the nbb nrepl-server to basilisp (#723)

Hi,

could you please review patch to port
[nbb](https://github.com/babashka/nbb)'s build in nrepl-server to
basilisp contrib. It addresses #412.

`nbb` has the same EPL-1.0 license as `basilisp` so I believe using its
code as the base for this PR should not cause licensing issues.

The nbb `bencode` module which is a dependency was ported as well.
Extensive tests were written for both.

The server has been tested to work with both
[CIDER](https://github.com/clojure-emacs/cider) and
[Calva](https://github.com/BetterThanTomorrow/calva) in VS-Code.

The server can be invoked with `baslisp nrepl-server`:
```
$ poetry run basilisp nrepl-server -h
usage: basilisp.cmd nrepl-server [-h] [--host HOST] [--port PORT] [--port-filepath PORT_FILEPATH]

Start the nREPL server.

optional arguments:
  -h, --help            show this help message and exit
  --host HOST           the interface address to bind to, defaults to 127.0.0.1.
  --port PORT           the port to connect to, defaults to 0 (random available port).
  --port-filepath PORT_FILEPATH
                        the file path where the server port number is output to, defaults to ".nrepl-port".
```

Several fixes were required to make it work, which are included as
separate commits in this PR prior to the main bencode and nrepl-server
commits. They address the following issues

- ~~Fixed issue with sort-* fns returning an error on empty seqs
(#716)~~
- Fix issue with `ns` being unavail after `in-ns` during `eval` (#718)
- Fixed issue with import modules aliasing using ns eval (#719)
- Fixed issue with `ns-resolve` throwing error on macros (#720)

support for the `basilisp.stacktrace/print-cause-trace` is also added
because it is requested by CIDER when an exception is thrown to show to
the user, which is essential, it partially addresses #721.

In addition, two issues were observed while running the tests in CI
- ~~The 1.6.0 was released few days ago and complains for an additional
type error in the generator, which is now ignored with this patch~~

``` 
Traceback (most recent call last):
#...
py311-mypy: commands[0]> mypy --config-file=C:\src\basilisp/pyproject.toml -p basilisp
src\basilisp\lang\compiler\generator.py:3530: error: Argument 1 to "fields" has incompatible type "type[IType]"; expected an attrs class  [misc]
src\basilisp\lang\compiler\generator.py:3530: note: Error code "misc" not covered by "type: ignore" comment
``` 

- The nrepl-server tests which are using threads were failing due to
trying to release an rlock which has been already released whose essence
is captured in #722, and is fixed with this patch as described in the
ticket by using `with self._lock.gen_rlock()` instead of a single
instance of `with self._rlock()`. The error was
```
    File "/home/runner/work/basilisp/basilisp/.tox/py39/lib/python3.9/site-packages/basilisp/lang/runtime.py", line 706, in find
    return v
   File "/home/runner/work/basilisp/basilisp/.tox/py39/lib/python3.9/site-packages/readerwriterlock/rwlock.py", line 49, in __exit__
    self.release()
   File "/home/runner/work/basilisp/basilisp/.tox/py39/lib/python3.9/site-packages/readerwriterlock/rwlock.py", line 344, in release
    if not self.v_locked: raise RELEASE_ERR_CLS(RELEASE_ERR_MSG)
 RuntimeError: release unlocked lock
```

I understand this could be a lot to go through and there likely to be
multiple iterations while I update the code with your feedback, of which
I'm looking forward to.

I have not written a nrepl-server section for the manual yet. I plan to
do this after a successful review, and will also update the changelog.

Thanks

---------

Co-authored-by: ikappaki <[email protected]>
Co-authored-by: Chris Rink <[email protected]>

Author: ikappaki

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  * Added support for Python 3.12 (#734)
  * Added a default reader conditional for the current platform (`windows`, `darwin`, `linux`, etc.) (#692)
  * Added support for `bencode` binary encoding (part of #412)
+ * Ported nbb's nrepl-server module to basilisp (#412).
 
 ### Changed
  * Basilisp now supports PyTest 7.0+ (#660)

docs/api/contrib/nrepl-server.rst

@@ -0,0 +1,10 @@
+basilisp.contrib.nrepl-server
+=============================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+.. autonamespace:: basilisp.contrib.nrepl-server
+   :members:
+   :undoc-members:

docs/cli.rst

@@ -32,6 +32,30 @@ The builtin REPL supports basic code completion suggestions, syntax highlighting
 
    You can exit the REPL by entering an end-of-file ("EOF") character by pressing Ctrl+D at your keyboard.
 
+.. _start_an_nREPL_session:
+
+Start an nREPL Session
+----------------------
+
+Basilisp's CLI incorporates an nREPL server adapted from `nbb <https://github.com/babashka/nbb>`_.
+
+To start the server from the command line use the following command
+
+.. code-block:: bash
+
+   basilisp nrepl-server
+   # => nREPL server started on port 50407 on host 127.0.0.1 - nrepl://127.0.0.1:50407
+
+You can then establish a connection from your IDE to the server address.
+
+- from `Emacs`, using `CIDER <https://github.com/clojure-emacs/cider>`_
+
+  `M-x cider-connect-clj`
+
+- from `Visual Studio Code`, using `Calva <https://calva.io/>`_
+
+  `REPL` -> `Connect to a running REPL in your project` -> `Generic`
+
 .. _run_basilisp_code:
 
 Run Basilisp Code

docs/differencesfromclojure.rst

@@ -88,7 +88,6 @@ REPL
 ----
 
 Basilisp's REPL experience closely matches that of Clojure's.
-Basilisp does not currently support any programmatic REPL server such as `nREPL <https://nrepl.org/nrepl/index.html>`_ or pREPL, though support is planned (see `#412 <https://github.com/basilisp-lang/basilisp/issues/412>`_).
 
 .. _evaluation_differences:
 

docs/features.rst

@@ -20,8 +20,7 @@ Basilisp is still young and so lacks many features that more mature languages an
 There are many such planned features that will hopefully improve the ergonomics of the project for new developers.
 A few of those features include:
 
-* Built-in `nREPL <https://nrepl.org/nrepl/usage/server.html>`_ server
 * Project management tooling to facility dependency management/locking and packaging
 * Compatibility with the platform-agnostic components of Clojure
 
-See the GitHub `issues <https://github.com/basilisp-lang/basilisp/issues>`_ and `projects <https://github.com/basilisp-lang/basilisp/projects?type=beta>`_ pages for more details.
+See the GitHub `issues <https://github.com/basilisp-lang/basilisp/issues>`_ and `projects <https://github.com/basilisp-lang/basilisp/projects?type=beta>`_ pages for more details.

src/basilisp/cli.py

@@ -244,6 +244,56 @@ def _wrapped_subcommand(subparsers: "argparse._SubParsersAction"):
     return _wrap_add_subcommand
 
 
+def nrepl_server(
+    _,
+    args: argparse.Namespace,
+):
+    opts = compiler.compiler_opts()
+    basilisp.init(opts)
+
+    ctx = compiler.CompilerContext(filename=REPL_INPUT_FILE_PATH, opts=opts)
+    eof = object()
+
+    ns = runtime.Namespace.get_or_create(runtime.CORE_NS_SYM)
+    host = runtime.lrepr(args.host)
+    port = args.port
+    port_filepath = runtime.lrepr(args.port_filepath)
+    eval_str(
+        (
+            "(require '[basilisp.contrib.nrepl-server :as nr])"
+            f"(nr/start-server! {{:host {host} :port {port} :nrepl-port-file {port_filepath}}})"
+        ),
+        ctx,
+        ns,
+        eof,
+    )
+
+
+@_subcommand(
+    "nrepl-server",
+    help="start the nREPL server",
+    description="Start the nREPL server.",
+    handler=nrepl_server,
+)
+def _add_nrepl_server_subcommand(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="the interface address to bind to, defaults to 127.0.0.1.",
+    )
+    parser.add_argument(
+        "--port",
+        default=0,
+        type=int,
+        help="the port to connect to, defaults to 0 (random available port).",
+    )
+    parser.add_argument(
+        "--port-filepath",
+        default=".nrepl-port",
+        help='the file path where the server port number is output to, defaults to ".nrepl-port".',
+    )
+
+
 def repl(
     _,
     args: argparse.Namespace,
@@ -445,6 +495,7 @@ def invoke_cli(args: Optional[Sequence[str]] = None) -> None:
     )
 
     subparsers = parser.add_subparsers(help="sub-commands")
+    _add_nrepl_server_subcommand(subparsers)
     _add_repl_subcommand(subparsers)
     _add_run_subcommand(subparsers)
     _add_test_subcommand(subparsers)

src/basilisp/contrib/bencode.lpy

@@ -1,3 +1,5 @@
+;; Decoding logic adapted from
+;; https://github.com/babashka/nbb/blob/bca8b5017a06768eb35d02a2d6233ca9c6c2f692/src/nbb/impl/bencode.cljs
 (ns basilisp.contrib.bencode
   (:require
    [basilisp.string :as str]))