rapydscript-ng 0.7.24 → 0.8.1

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+version 0.8.1
+=======================
+
+  * Fix concatenation of mixed string and f-string literal
+  * fmt and lsp now by default read format related settings from pyproject.toml, overridden via command line
+  * fmt command reports unfixable long lines in normal mode as well
+  * Fix newlines inside tuples not being allowed
+  * Miscellaneous improvements for the code auto formatter
+
+version 0.8.0
+=======================
+
+  * Implement generation of source maps via the --source-map option
+  * Implement dead code removal via the --tree-shaking option
+  * Add support for async and await
+  * Implement a ``fmt`` command for code formatting and an ``lsp`` command for a Language Server
+  * Implement a tree sitter grammar so that robust syntax highlighting is potentially available in all editors
+  * Implement a neovim plugin that enables treesitter based syntax highlighting and LSP server for ``.pyj`` files
+  * Implement support for importing user modules in the embedded compiler
+  * Double the compilation speed, especially useful for large projects
+  * Drop support for ES5
+  * List objects are now unmodified JS Arrays for greater performance. Python
+    list methods continue to work.
+  * Change the cache format to cache only the AST and not final output so that
+    the cache can be re-used regardless of output and tree shaking options
+  * Make the compiler internally use async IO. This means the embedded compiler
+    functions are also async.
+ 
 version 0.7.24
 =======================
 

package/README.md

@@ -42,11 +42,13 @@ backwards compatible) features. For more on the forking, [see the bottom of this
   - [Method Binding](#method-binding)
 - [Iterators](#iterators)
 - [Generators](#generators)
+- [Asnyc and Await](#async-and-await)
 - [Modules](#modules)
 - [Exception Handling](#exception-handling)
 - [Scope Control](#scope-control)
 - [Available Libraries](#available-libraries)
 - [Linter](#linter)
+- [Language Server (LSP)](#language-server-lsp)
 - [Making RapydScript even more pythonic](#making-rapydscript-even-more-pythonic)
 - [Advanced Usage Topics](#advanced-usage-topics)
     - [Browser Compatibility](#browser-compatibility)
@@ -102,6 +104,14 @@ Installation
 
 [Try RapydScript-ng live via an in-browser REPL!](https://sw.kovidgoyal.net/rapydscript/repl/)
 
+If you just want the standalone rapydscript binary, you can install it from
+PyPI, with::
+
+    pip install rapydscript-ng
+
+If you want the full package, needed to use the ``web-repl-export`` command, or
+integrate with a node project, you can instead install using npm.
+
 First make sure you have installed the latest version of [node.js](https://nodejs.org/) (You may need to restart your computer after this step). 
 
 From NPM for use as a command line app:
@@ -1254,9 +1264,12 @@ syntax.
 Generators create JavaScript iterator objects. For differences between python
 and JavaScript iterators, see the section on iterators above. 
 
-Currently, generators are down-converted to ES 5 switch statements. In the
-future, when ES 6 support is widespread, they will be converted to native
-JavaScript ES 6 generators.
+Async and Await
+------------------
+
+Python's ``async`` and ``await`` keywords are supported, but note that async
+functions return JavaScript Promise objects not co-routines. This is so that
+they interoperate with the JS ecosystem and browser APIs in particular.
 
 Modules
 -------
@@ -1427,6 +1440,41 @@ that the linter will not raise undefined errors for. You can turn off
 individual checks that you do not find useful. See ``rapydscript lint -h`` for
 details.
 
+Language Server (LSP)
+-----------------------
+
+RapydScript ships with a Language Server Protocol server so that editors can
+offer rich language support for ``.pyj`` files. Start it with:
+
+	rapydscript lsp
+
+The server talks the standard LSP JSON-RPC protocol over stdin/stdout, so it is
+meant to be launched by an editor/LSP client rather than run interactively. It
+provides:
+
+- **Code completion** — in-scope symbols, builtins and keywords, plus member
+  completion for imported modules (``mod.<complete>``).
+- **Diagnostics** — the same checks as the ``lint`` sub-command, plus warnings
+  for imports that cannot be resolved in the import path. The parser recovers
+  from syntax errors, so a file that is being edited is still analysed (and
+  multiple errors can be reported at once).
+- **Hover** — the kind, origin and docstring of the symbol under the cursor.
+- **Code actions** — quick fixes such as removing an unused import/local,
+  silencing a check with a ``# noqa`` comment, and formatting the document.
+- **Document formatting** — the same formatter as the ``fmt`` sub-command,
+  controlled by ``--line-length`` and ``--preferred-quote``.
+- **Go to definition** — including jumping into imported modules.
+- **Find all references** — resolved across files through the import graph.
+- **Rename** — renames a symbol everywhere it is used across the workspace.
+
+Imports are resolved with the same ``--import-path`` (``-p``) option as the
+``compile`` sub-command, so point it at your project's import directories. For
+example:
+
+	rapydscript lsp --import-path src:vendor --line-length 100
+
+See ``rapydscript lsp -h`` for the full list of options.
+
 Making RapydScript even more pythonic
 ---------------------------------------
 
@@ -1454,11 +1502,9 @@ Advanced Usage Topics
 
 #### Browser Compatibility
 
-RapydScript compiles your code such that it will work on browsers that are
-compatible with the ES 5 JavaScript standard. The compiler has a 
-``--js-version`` option that can also be used to output ES 6 only code. This
-code is smaller and faster than the ES 5 version, but is not as widely
-compatible.
+RapydScript compiles your code to ES 6 compatible JavaScript. Any modern
+browser or Node.js version that supports ES 6 will run the output. The
+``--js-version`` option only accepts ``6``.
 
 #### Tabs vs Spaces
 
@@ -1491,9 +1537,9 @@ To do so, simply include the [embeddable rapydscript compiler](https://sw.kovidg
 in your page, and use it to compile arbitrary RapydScript code. 
 
 You create the compiler by calling: `RapydScript.create_embedded_compiler()` and compile
-code with `compiler.compile(code)`. You can execute the resulting JavaScript
-using the standard `eval()` function. See the sample
-HTML below for an example.
+code with `await compiler.compile(code)`. Both calls return Promises, so you must use
+`async`/`await` (or `.then()`) to get the results. You can execute the resulting JavaScript
+using the standard `eval()` function. See the sample HTML below for an example.
 
 ```html
 <!DOCTYPE html>
@@ -1503,9 +1549,9 @@ HTML below for an example.
         <title>Test embedded RapydScript</title>
         <script charset="UTF-8" src="https://sw.kovidgoyal.net/rapydscript/repl/rapydscript.js"></script>
         <script>
-var compiler = RapydScript.create_embedded_compiler();
-var js = compiler.compile("def hello_world():\n a='RapydScript is cool!'\n print(a)\n alert(a)");
-window.onload = function() {
+window.onload = async function() {
+    var compiler = await RapydScript.create_embedded_compiler();
+    var js = await compiler.compile("def hello_world():\n a='RapydScript is cool!'\n print(a)\n alert(a)");
     document.body.textContent = js;
     eval(js);
     eval('hello_world()');
@@ -1519,20 +1565,28 @@ window.onload = function() {
 There are a couple of caveats when using the embedded compiler:
 
 * It only works when run in a modern browser (one that supports ES6) so no
-  Internet Explorer. You can have it work in an ES 5 runtime by passing
-  an option to the compile() method, like this:
-  ```
-  compiler.compile(code, {js_version:5})
-  ```
-  Note that doing this means that you cannot use generators and the
-  yield keyword in your RapydScript code.
+  Internet Explorer.
 
-* Importing of modules only works with the standard library modules. There is
-  currently no way to make your own modules importable.
+* To implement importing of modules you need to create a virtual file system
+  like this, before calling ``create_embedded_compiler()``:
 
-* To generate the embedded compiler yourself (rapydscript.js) from a source
-  checkout of rapydscript, follow the instructions above for installing from
-  source, then run `bin/web-repl-export /path/to/export/directory`
+  ```
+  RapydScript.virtual_file_system = {
+    read_file: my_read_file,
+    write_file: my_write_file,
+    stat_file: my_stat_file
+  }
+  ```
+  These functions should have the same signature and semantics as the 
+  ``fs.promises.readFile, fs.promises.writeFile and fs.promises.statFile``
+  functions from Node. Currently only the ``mtimeMs`` field from the stat
+  result is needed. They will be passed file paths starting with ``__vfs__/``
+  and should read/write/stat them as needed.
+
+* To generate the embedded compiler yourself (rapydscript.js) 
+  run `rapydscript web-repl-export /path/to/export/directory`.
+  Then you can simply open the ``index.html`` file in that directory in a browser
+  to see the web REPL in action.
 
 Internationalization
 -------------------------

package/bin/build.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env bun
+// vim:ft=typescript:ts=4:et
+/*
+ * Generates bin/rapydscript.mjs — the bun compilation entry point — by scanning
+ * the filesystem for embeddable assets and prepending their import declarations
+ * and the __rapydscript_embedded__ global setup to the contents of bin/rapydscript.
+ *
+ * Usage:
+ *   bun bin/build.ts                         # generate bin/rapydscript.mjs only
+ *   bun bin/build.ts --compile --outfile foo  # generate + run: bun build bin/rapydscript.mjs --compile --outfile foo
+ */
+
+import path from 'path';
+import fs from 'fs';
+
+const repo_root = path.dirname(path.dirname(Bun.main));
+const dev_dir = path.join(repo_root, 'dev');
+const src_lib_dir = path.join(repo_root, 'src', 'lib');
+const bin_dir = path.join(repo_root, 'bin');
+const out_path = path.join(bin_dir, 'rapydscript.mjs');
+
+async function exists(p: string): Promise<boolean> {
+    try { await fs.promises.access(p); return true; } catch { return false; }
+}
+
+// --- Scan assets ---
+
+const DEV_TEXT_ASSETS = ['compiler.js', 'baselib-plain-pretty.js', 'baselib-plain-ugly.js'];
+const DEV_JSON_ASSETS = ['stdlib_modules.json'];
+
+const found_dev_text: string[] = [];
+for (const a of DEV_TEXT_ASSETS) {
+    if (await exists(path.join(dev_dir, a))) found_dev_text.push(a);
+}
+
+const found_dev_json: string[] = [];
+for (const a of DEV_JSON_ASSETS) {
+    if (await exists(path.join(dev_dir, a))) found_dev_json.push(a);
+}
+
+const stdlib_files: string[] = (await fs.promises.readdir(src_lib_dir))
+    .filter(f => f.endsWith('.pyj'))
+    .sort();
+
+// --- Build the generated asset section ---
+
+function var_name(prefix: string, filename: string): string {
+    return prefix + filename.replace(/[^a-zA-Z0-9]/g, '_');
+}
+
+const lines: string[] = [];
+
+lines.push('// Generated by bin/build.ts — do not edit manually');
+lines.push('// vim:ft=javascript:ts=4:et');
+lines.push('');
+lines.push('// === Embedded assets (generated by bin/build.ts) ===');
+
+for (const a of found_dev_text) {
+    lines.push(`import ${var_name('_dev_', a)} from '../dev/${a}' with { type: 'text' };`);
+}
+for (const a of found_dev_json) {
+    lines.push(`import ${var_name('_dev_', a)} from '../dev/${a}' with { type: 'json' };`);
+}
+for (const f of stdlib_files) {
+    lines.push(`import ${var_name('_stdlib_', f)} from '../src/lib/${f}' with { type: 'text' };`);
+}
+
+lines.push('');
+lines.push('globalThis.__rapydscript_embedded__ = {');
+
+for (const a of found_dev_text) {
+    lines.push(`    '${a}': ${var_name('_dev_', a)},`);
+}
+for (const a of found_dev_json) {
+    // strip extension for the key so consumers use e.g. embedded.stdlib_modules
+    const key = a.replace(/\.json$/, '').replace(/-/g, '_');
+    lines.push(`    ${key}: ${var_name('_dev_', a)},`);
+}
+lines.push('    stdlib: {');
+for (const f of stdlib_files) {
+    lines.push(`        '${f}': ${var_name('_stdlib_', f)},`);
+}
+lines.push('    },');
+lines.push('};');
+lines.push('');
+lines.push('// === Entry point (from bin/rapydscript) ===');
+lines.push('');
+
+// --- Append bin/rapydscript content (strip the shebang line) ---
+
+const entry_src = await fs.promises.readFile(path.join(bin_dir, 'rapydscript'), 'utf-8');
+const entry_lines = entry_src.split('\n');
+// Drop the first line if it's the shebang, and the vim modeline comment right after
+let start = 0;
+if (entry_lines[0].startsWith('#!')) start = 1;
+if (start < entry_lines.length && entry_lines[start].trim().startsWith('// vim:')) start++;
+
+lines.push(...entry_lines.slice(start));
+
+// Ensure the file ends with a newline
+const content = lines.join('\n');
+const final_content = content.endsWith('\n') ? content : content + '\n';
+
+await fs.promises.writeFile(out_path, final_content, 'utf-8');
+console.log(`Written ${path.relative(repo_root, out_path)}`);
+console.log(`  ${found_dev_text.length} dev text assets, ${found_dev_json.length} dev json assets, ${stdlib_files.length} stdlib files`);
+
+// --- Optionally run bun build with passed-through args ---
+
+const extra_args = process.argv.slice(2);
+if (extra_args.length > 0) {
+    const cmd_args = ['build', out_path, ...extra_args];
+    console.log(`Running: bun ${cmd_args.join(' ')}`);
+    const proc = Bun.spawn(['bun', ...cmd_args], { stdout: 'inherit', stderr: 'inherit', stdin: 'inherit' });
+    const code = await proc.exited;
+    process.exit(code);
+}

package/bin/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/bin/rapydscript

@@ -1,70 +1,73 @@
-#!/usr/bin/env node 
+#!/usr/bin/env node
 // vim:ft=javascript:ts=4:et
 
-"use strict";
+import { fileURLToPath } from 'url';
+import path from 'path';
+import { spawn } from 'child_process';
+import * as utils from '../tools/utils.mjs';
+import { create_compiler } from '../tools/compiler.mjs';
 
-function load(mod) {
-    return require('../tools/' + mod);
-}
+const __filename = fileURLToPath(import.meta.url);
+
+var start_time = new Date().getTime();
+
+var { argv } = await import('../tools/cli.mjs');
+
+var base_path = path.normalize(path.join(path.dirname(__filename), ".."));
+var src_path = path.join(base_path, 'src');
+var lib_path = path.join(base_path, 'dev');
+if (!(await utils.path_exists(path.join(lib_path, 'compiler.js')))) lib_path = path.join(base_path, 'release');
 
-var utils = load('utils');
+// Create compiler instance once, then expose it synchronously via the global
+// so bundled modules (repl, gettext, etc.) can call create_rapydscript_compiler() synchronously.
+const _compiler_instance = await create_compiler();
+globalThis.create_rapydscript_compiler = () => _compiler_instance;
 
-// We need ES 6 generators so relaunch with the --harmony flag
-if (!utils.generators_available()) {
-    if (process.execArgv.indexOf('--harmony') != -1) {
-        console.error('RapydScript needs ES 6 generators, update your version of nodejs');
-        process.exit(1);
+if (argv.mode === 'self') {
+    if (argv.files.length > 0) {
+        console.error("WARN: Ignoring input files since --self was passed");
     }
-    var args = ['--harmony', module.filename].concat(process.argv.slice(2));
-    require('child_process').spawn(process.execPath, args, {stdio:'inherit'}).on('exit', function(code, signal) {
-        process.exit(code);
-    });
-} else {
-
-    var start_time = new Date().getTime();
-    var path = require('path');
-
-    var argv = load('cli').argv;
-
-    var base_path = path.normalize(path.join(path.dirname(module.filename), ".."));
-    var src_path = path.join(base_path, 'src');
-    var lib_path = path.join(base_path, 'dev');
-    if (!utils.path_exists(path.join(lib_path, 'compiler.js'))) lib_path = path.join(base_path, 'release');
-
-    if (argv.mode === 'self') {
-        if (argv.files.length > 0) {
-            console.error("WARN: Ignoring input files since --self was passed");
-        }
-        load('self')(base_path, src_path, lib_path, argv.complete, argv.profile);
-        if (argv.test) {
-            console.log('\nRunning test suite...\n');
-            argv.files = [];  // Ensure all tests are run
-            load('test')(argv, base_path, src_path, path.join(base_path, 'dev'));
-        }
-        process.exit(0);
-    } else 
-
-    if (argv.mode === 'test') {
-        load('test')(argv, base_path, src_path, lib_path);
-    } else 
-
-    if (argv.mode === 'lint') {
-        load('lint').cli(argv, base_path, src_path, lib_path);
-    } else
-
-    if (argv.mode === 'repl') {
-        load('repl')({'lib_path':lib_path, 'imp_path':path.join(src_path, 'lib'), show_js:!argv.no_js});
-    } else 
-    
-    if (argv.mode === 'gettext') {
-        load('gettext').cli(argv, base_path, src_path, lib_path);
-    } else
-    
-    if (argv.mode === 'msgfmt') {
-        load('msgfmt').cli(argv, base_path, src_path, lib_path);
-    } else
-    
-    {
-        load('compile')(start_time, argv, base_path, src_path, lib_path);
+    await (await import('../tools/self.mjs')).default(base_path, src_path, lib_path, argv.complete, argv.profile);
+    if (argv.test) {
+        console.log('\nRunning test suite...\n');
+        argv.files = [];  // Ensure all tests are run
+        await (await import('../tools/test.mjs')).default(argv, base_path, src_path, path.join(base_path, 'dev'));
     }
+    process.exit(0);
+} else
+
+if (argv.mode === 'test') {
+    await (await import('../tools/test.mjs')).default(argv, base_path, src_path, lib_path);
+} else
+
+if (argv.mode === 'lint') {
+    await (await import('../tools/lint.mjs')).cli(argv, base_path, src_path, lib_path);
+} else
+
+if (argv.mode === 'fmt') {
+    await (await import('../tools/fmt.mjs')).cli(argv, base_path, src_path, lib_path);
+} else
+
+if (argv.mode === 'lsp') {
+    await (await import('../tools/lsp.mjs')).cli(argv, base_path, src_path, lib_path);
+} else
+
+if (argv.mode === 'repl') {
+    await (await import('../tools/repl.mjs')).default({'lib_path':lib_path, 'imp_path':path.join(src_path, 'lib'), show_js:!argv.no_js});
+} else
+
+if (argv.mode === 'gettext') {
+    await (await import('../tools/gettext.mjs')).cli(argv, base_path, src_path, lib_path);
+} else
+
+if (argv.mode === 'msgfmt') {
+    (await import('../tools/msgfmt.mjs')).cli(argv, base_path, src_path, lib_path);
+} else
+
+if (argv.mode === 'web-repl-export') {
+    await (await import('../tools/web_repl_export.mjs')).default(base_path, lib_path, argv);
+} else
+
+{
+    await (await import('../tools/compile.mjs')).default(start_time, argv, base_path, src_path, lib_path);
 }

package/build_wheels.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+# vim:fileencoding=utf-8
+
+import os
+import sys
+import json
+import shutil
+import tempfile
+import subprocess
+import re
+
+BASE = os.path.dirname(os.path.abspath(__file__))
+
+# Maps (bun_target, wheel_platform_tag, binary_name)
+PLATFORMS = [
+    ("bun-linux-x64", "manylinux_2_17_x86_64", "rapydscript"),
+    ("bun-linux-arm64", "manylinux_2_17_aarch64", "rapydscript"),
+    ("bun-linux-x64-musl", "musllinux_1_2_x86_64", "rapydscript"),
+    ("bun-linux-arm64-musl", "musllinux_1_2_aarch64", "rapydscript"),
+    ("bun-darwin-x64", "macosx_10_9_x86_64", "rapydscript"),
+    ("bun-darwin-arm64", "macosx_11_0_arm64", "rapydscript"),
+    ("bun-windows-x64", "win_amd64", "rapydscript.exe"),
+]
+
+
+def normalize_name(name):
+    return re.sub(r"[-_.]+", "_", name).lower()
+
+
+def load_metadata():
+    with open(os.path.join(BASE, "package.json"), "rb") as f:
+        return json.load(f)
+
+
+def build_binary(bun_target, outfile):
+    cmd = [
+        "bun",
+        "bin/build.ts",
+        "--compile",
+        f"--outfile={outfile}",
+        f"--target={bun_target}",
+    ]
+    print(f"  Building {bun_target} ...")
+    subprocess.check_call(cmd, cwd=BASE)
+
+
+def write_wheel_metadata(dist_info_dir, meta, wheel_platform):
+    maintainers = meta.get("maintainers", [])
+    author = maintainers[0].get("name", "") if maintainers else ""
+    author_email = maintainers[0].get("email", "") if maintainers else ""
+    repo_url = meta.get("repository", {}).get("url", "")
+
+    with open(os.path.join(dist_info_dir, "WHEEL"), "w") as f:
+        f.write("Wheel-Version: 1.0\n")
+        f.write("Generator: wheel.py\n")
+        f.write("Root-Is-Purelib: false\n")
+        f.write(f"Tag: py3-none-{wheel_platform}\n")
+
+    with open(os.path.join(dist_info_dir, "METADATA"), "w") as f:
+        f.write("Metadata-Version: 2.1\n")
+        f.write(f"Name: {meta['name']}\n")
+        f.write(f"Version: {meta['version']}\n")
+        f.write(f"Summary: {meta.get('description', '')}\n")
+        if meta.get("homepage"):
+            f.write(f"Home-page: {meta['homepage']}\n")
+        if author:
+            f.write(f"Author: {author}\n")
+        if author_email:
+            f.write(f"Author-email: {author_email}\n")
+        if meta.get("license"):
+            f.write(f"License: {meta['license']}\n")
+        if meta.get("keywords"):
+            f.write(f"Keywords: {', '.join(meta['keywords'])}\n")
+        if repo_url:
+            f.write(f"Project-URL: Source Code, {repo_url}\n")
+        f.write("Description-Content-Type: text/markdown")
+        print(file=f)
+        with open("README.md") as s:
+            f.write(s.read())
+
+
+def build_wheel(meta, bun_target, wheel_platform, binary_name, dest_dir, tmpdir):
+    norm_name = normalize_name(meta["name"])
+    version = meta["version"]
+
+    suffix = ".exe" if binary_name.endswith(".exe") else ""
+    binary_outfile = os.path.join(tmpdir, f"rapydscript-{bun_target}{suffix}")
+    build_binary(bun_target, binary_outfile)
+
+    # Assemble unpacked wheel layout
+    wheel_dir = os.path.join(tmpdir, f"{norm_name}-{version}-{wheel_platform}")
+    dist_info_dir = os.path.join(wheel_dir, f"{norm_name}-{version}.dist-info")
+    scripts_dir = os.path.join(wheel_dir, f"{norm_name}-{version}.data", "scripts")
+    os.makedirs(dist_info_dir)
+    os.makedirs(scripts_dir)
+
+    dest_binary = os.path.join(scripts_dir, binary_name)
+    shutil.copy2(binary_outfile, dest_binary)
+    os.chmod(dest_binary, 0o755)
+
+    write_wheel_metadata(dist_info_dir, meta, wheel_platform)
+
+    print("  Packing wheel ...")
+    subprocess.check_call(
+        [sys.executable, "-m", "wheel", "pack", wheel_dir, "--dest-dir", dest_dir],
+        cwd=tmpdir,
+    )
+
+    return f"{norm_name}-{version}-py3-none-{wheel_platform}.whl"
+
+
+def main():
+    meta = load_metadata()
+    dest_dir = os.path.join(BASE, "dist")
+    os.makedirs(dest_dir, exist_ok=True)
+    for x in os.listdir(dest_dir):
+        os.remove(os.path.join(dest_dir, x))
+
+    wheels = []
+    with tempfile.TemporaryDirectory(prefix="rapydscript-wheel-") as tmpdir:
+        for bun_target, wheel_platform, binary_name in PLATFORMS:
+            print(f"\n[{bun_target}]")
+            whl = build_wheel(
+                meta, bun_target, wheel_platform, binary_name, dest_dir, tmpdir
+            )
+            wheels.append(whl)
+            print(f"  -> dist/{whl}")
+
+    print(f"\nBuilt {len(wheels)} wheels in dist/")
+
+
+if __name__ == "__main__":
+    main()

package/editor-plugins/README.md

@@ -0,0 +1,80 @@
+# Plugins to integrate with editors
+
+Wires up the RapydScript LSP server (`rapydscript lsp`) as a
+LSP client for various editors (currently only Neovim).
+It also enables treesitter based syntax highlighting.
+
+## Features
+
+Provided by the LSP server — no extra plugins required:
+
+- **Completions** — in-scope symbols, builtins, keywords, and member completion (`mod.<TAB>`)
+- **Diagnostics** — lint checks and unresolved import warnings, updated as you type
+- **Hover** (`K`) — kind, origin, and docstring of the symbol under the cursor
+- **Go to definition** (`gd`) — including jumping into imported modules
+- **Find references** (`gr`) — resolved across files through the import graph
+- **Rename** (`<leader>rn`) — renames everywhere across the workspace
+- **Code actions** (`<leader>ca`) — remove unused import/local, add `# noqa`, format document
+- **Document formatting** (`<leader>f`) — same as `rapydscript fmt`
+- **Document symbols** — outline view via any symbols picker
+
+## Requirements
+
+- `node` (from nodejs) on your `$PATH` 
+
+- **Syntax highlighting only**: a C compiler on your `$PATH` is required to compile the
+  tree-sitter parser the first time the plugin loads.  On Linux/macOS any `cc`-compatible
+  compiler works (gcc, clang, etc.).  On Windows, `cl` (MSVC) or `clang-cl` must be
+  available. LSP features work regardless of whether compilation
+  succeeds.
+
+## Neovim Installation
+
+Needs Neovim >= 0.12. Just add the following to your ``~/.config/nvim/init.lua``, changing the
+options to suit yourself:
+
+```lua
+vim.pack.add({ { src = "https://github.com/kovidgoyal/rapydscript-ng", name = "rapydscript" } }, {
+    load = function(plug_data)
+        vim.cmd.packadd(plug_data.spec.name)
+        for _, pack in ipairs(vim.pack.get({ plug_data.spec.name })) do
+            vim.opt.rtp:append(pack.path .. "/editor-plugins/nvim/rapydscript")
+            dofile(pack.path .. '/editor-plugins/nvim.lua').setup({
+                -- options you should customize
+                line_length = 80,
+                preferred_quote = "single",
+            })
+        end
+    end
+})
+```
+
+Or if you want to load it manually for older versions of Neovim:
+
+```lua
+dofile("/path/to/rapydscript/editor-plugins/nvim.lua").setup()
+```
+
+## Configuration reference
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `cmd` | `string[]` | `{"rapydscript","lsp"}` | Command used to start the server |
+| `import_path_patterns` | `string[]` | `{".", "src", "src/pyj"}` | Glob patterns relative to the project root; matching directories that contain `.pyj` files are passed automatically as `--import-path` |
+| `line_length` | `number\|nil` | `nil` | Max line length for the formatter, passed as `--line-length` |
+| `preferred_quote` | `string\|nil` | `nil` | `"single"` or `"double"`, passed as `--preferred-quote` |
+| `join_lines` | `boolean\|nil` | `nil` | When `true`, multi-line statements that fit within `line_length` are joined onto one line, passed as `--join-lines`. Disabled by default. |
+| `filetypes` | `string[]` | `{"rapydscript"}` | Filetypes that trigger server attachment |
+| `root_markers` | `string[]` | `{".git","package.json","rapydscript.json"}` | Files/dirs used to detect the project root |
+
+### Automatic import path detection
+
+When a project root is found (via `root_markers`), the plugin expands each pattern in
+`import_path_patterns` as a glob relative to that root.  Any matching directory that
+contains at least one `.pyj` file is added to the server's import search path
+automatically — no manual configuration needed for standard project layouts.
+
+If no project root is detected the setting has no effect.
+
+To add custom search locations alongside the defaults, use
+``import_path_patterns``.