rumdl-wasm 0.2.56 → 0.2.58

package/README.md

@@ -80,6 +80,73 @@ const rules = JSON.parse(get_available_rules());
 // [{ name: "MD001", description: "Heading levels should only increment by one level at a time" }, ...]
 ```
 
+## Configuration
+
+`lint_markdown` and `apply_all_fixes` use rumdl's defaults. For configured
+linting, create a `Linter` with an options object that mirrors the `[global]`
+section of `.rumdl.toml` plus per-rule tables:
+
+```javascript
+import init, { Linter } from 'rumdl-wasm';
+
+await init();
+
+const linter = new Linter({
+  disable: ['MD041'],
+  'line-length': 120,
+  flavor: 'mkdocs',            // "standard" (default), "mkdocs", "obsidian", ...
+  MD013: { 'line-length': 100 },
+});
+
+const warnings = JSON.parse(linter.check(content, 'docs/guide.md'));  // path is optional
+const fixed = linter.fix(content, 'docs/guide.md');
+
+JSON.parse(linter.get_config());           // the effective configuration
+JSON.parse(linter.get_config_warnings());  // e.g. unknown rule options
+```
+
+Passing a path lets `exclude` and `per-file-ignores` patterns apply.
+
+### Loading `.rumdl.toml` files, including `extends`
+
+A flat options object cannot follow `extends`, so `new Linter(...)` reports an
+`extends` key as a config warning and ignores it. To load config files the way
+the CLI does (same parsing, `extends` resolution, and merge order), hand rumdl
+the file contents and let it tell you which file it needs next. This works
+from any host that can read files, including ones that can only do so
+asynchronously:
+
+```javascript
+import init, { Linter, resolve_config_chain } from 'rumdl-wasm';
+import { readFile } from 'fs/promises';
+
+await init();
+
+const root = '.rumdl.toml';
+const files = { [root]: await readFile(root, 'utf-8') };
+const request = () => ({ root, files, env: process.env, home: process.env.HOME });
+
+for (;;) {
+  const r = JSON.parse(resolve_config_chain(request()));
+  if (r.status === 'need-file') {
+    // r.path is resolved already: relative to the declaring file's directory,
+    // with `$VAR` expanded from `env` and `~/` from `home`. Store null for a
+    // file that does not exist.
+    files[r.path] = await readFile(r.path, 'utf-8').catch(() => null);
+  } else if (r.status === 'error') {
+    throw new Error(r.message);   // parse error, missing target, cycle, ...
+  } else {
+    console.log('config chain:', r.files);   // root first
+    break;
+  }
+}
+
+const linter = Linter.from_config_files({ ...request(), 'default-flavor': 'mkdocs' });
+```
+
+`root` may also be a `pyproject.toml` (its `[tool.rumdl]` table is used).
+`default-flavor` applies only when no file in the chain sets a flavor.
+
 ## Warning Format
 
 Each warning object contains:

package/package.json

@@ -5,7 +5,7 @@
     "Ruben J. Jongejan <ruben.jongejan@gmail.com>"
   ],
   "description": "Fast markdown linter with 60+ rules - WebAssembly build",
-  "version": "0.2.56",
+  "version": "0.2.58",
   "license": "MIT",
   "repository": {
     "type": "git",

package/rumdl_lib.d.ts

@@ -41,6 +41,21 @@ export class Linter {
      * Uses the same fix coordinator as the CLI for consistent behavior.
      */
     fix(content: string, path?: string | null): string;
+    /**
+     * Create a Linter from config file contents, following `extends`.
+     *
+     * Takes the same request object as [`resolve_config_chain`], which must
+     * already report the chain complete: every file the chain reaches has to
+     * be in `files`. The files are parsed, merged and validated exactly as the
+     * rumdl CLI does it (`[global]` section, rule sections and aliases,
+     * `extends` precedence, per-rule `enabled`), so a `.rumdl.toml` means the
+     * same thing in an embedding as on the command line. Validation warnings
+     * are available from `get_config_warnings()`.
+     *
+     * Fails with a message when a file is missing from `files` or the chain
+     * has a config error; `resolve_config_chain` reports both beforehand.
+     */
+    static from_config_files(request: any): Linter;
     /**
      * Get the current configuration as JSON
      *
@@ -94,6 +109,34 @@ export function get_version(): string;
  */
 export function init(): void;
 
+/**
+ * Find out which config files a chain needs before building a `Linter` from it.
+ *
+ * Embedders that can only read files asynchronously call this in a loop: start
+ * with the root file's contents, add whatever path the result asks for, and
+ * repeat until the chain is complete. Returns a JSON object with `status`:
+ *
+ * - `{"status": "need-file", "path": "base/.rumdl.toml"}`: read this path
+ *   (relative paths are relative to wherever `root` is relative to), add it to
+ *   `files` (or `null` if it does not exist), and call again.
+ * - `{"status": "complete", "files": [".rumdl.toml", "base/.rumdl.toml"]}`:
+ *   every file is present; `files` lists the chain root first.
+ * - `{"status": "error", "message": "..."}`: the chain cannot be loaded
+ *   (parse error, missing `extends` target, cycle, undefined `$VAR`, ...).
+ *
+ * ```javascript
+ * const files = { [root]: await read(root) };
+ * for (;;) {
+ *   const r = JSON.parse(resolve_config_chain({ root, files }));
+ *   if (r.status === "need-file") { files[r.path] = await readOrNull(r.path); continue; }
+ *   if (r.status === "error") throw new Error(r.message);
+ *   break;
+ * }
+ * const linter = Linter.from_config_files({ root, files });
+ * ```
+ */
+export function resolve_config_chain(request: any): string;
+
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
@@ -103,9 +146,11 @@ export interface InitOutput {
     readonly get_version: (a: number) => void;
     readonly linter_check: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
     readonly linter_fix: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly linter_from_config_files: (a: number, b: number) => void;
     readonly linter_get_config: (a: number, b: number) => void;
     readonly linter_get_config_warnings: (a: number, b: number) => void;
     readonly linter_new: (a: number, b: number) => void;
+    readonly resolve_config_chain: (a: number, b: number) => void;
     readonly init: () => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;

package/rumdl_lib.js

@@ -7,6 +7,13 @@
  * `check()` to lint content and `fix()` to auto-fix issues.
  */
 export class Linter {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(Linter.prototype);
+        obj.__wbg_ptr = ptr;
+        LinterFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
     __destroy_into_raw() {
         const ptr = this.__wbg_ptr;
         this.__wbg_ptr = 0;
@@ -92,6 +99,37 @@ export class Linter {
             wasm.__wbindgen_export4(deferred3_0, deferred3_1, 1);
         }
     }
+    /**
+     * Create a Linter from config file contents, following `extends`.
+     *
+     * Takes the same request object as [`resolve_config_chain`], which must
+     * already report the chain complete: every file the chain reaches has to
+     * be in `files`. The files are parsed, merged and validated exactly as the
+     * rumdl CLI does it (`[global]` section, rule sections and aliases,
+     * `extends` precedence, per-rule `enabled`), so a `.rumdl.toml` means the
+     * same thing in an embedding as on the command line. Validation warnings
+     * are available from `get_config_warnings()`.
+     *
+     * Fails with a message when a file is missing from `files` or the chain
+     * has a config error; `resolve_config_chain` reports both beforehand.
+     * @param {any} request
+     * @returns {Linter}
+     */
+    static from_config_files(request) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.linter_from_config_files(retptr, addHeapObject(request));
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return Linter.__wrap(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Get the current configuration as JSON
      *
@@ -228,6 +266,59 @@ export function get_version() {
 export function init() {
     wasm.init();
 }
+
+/**
+ * Find out which config files a chain needs before building a `Linter` from it.
+ *
+ * Embedders that can only read files asynchronously call this in a loop: start
+ * with the root file's contents, add whatever path the result asks for, and
+ * repeat until the chain is complete. Returns a JSON object with `status`:
+ *
+ * - `{"status": "need-file", "path": "base/.rumdl.toml"}`: read this path
+ *   (relative paths are relative to wherever `root` is relative to), add it to
+ *   `files` (or `null` if it does not exist), and call again.
+ * - `{"status": "complete", "files": [".rumdl.toml", "base/.rumdl.toml"]}`:
+ *   every file is present; `files` lists the chain root first.
+ * - `{"status": "error", "message": "..."}`: the chain cannot be loaded
+ *   (parse error, missing `extends` target, cycle, undefined `$VAR`, ...).
+ *
+ * ```javascript
+ * const files = { [root]: await read(root) };
+ * for (;;) {
+ *   const r = JSON.parse(resolve_config_chain({ root, files }));
+ *   if (r.status === "need-file") { files[r.path] = await readOrNull(r.path); continue; }
+ *   if (r.status === "error") throw new Error(r.message);
+ *   break;
+ * }
+ * const linter = Linter.from_config_files({ root, files });
+ * ```
+ * @param {any} request
+ * @returns {string}
+ */
+export function resolve_config_chain(request) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.resolve_config_chain(retptr, addHeapObject(request));
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr1 = r0;
+        var len1 = r1;
+        if (r3) {
+            ptr1 = 0; len1 = 0;
+            throw takeObject(r2);
+        }
+        deferred2_0 = ptr1;
+        deferred2_1 = len1;
+        return getStringFromWasm0(ptr1, len1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export4(deferred2_0, deferred2_1, 1);
+    }
+}
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
@@ -349,6 +440,10 @@ function __wbg_get_imports() {
             const ret = getObject(arg0)[arg1 >>> 0];
             return addHeapObject(ret);
         },
+        __wbg_get_with_ref_key_6412cf3094599694: function(arg0, arg1) {
+            const ret = getObject(arg0)[getObject(arg1)];
+            return addHeapObject(ret);
+        },
         __wbg_instanceof_ArrayBuffer_7c8433c6ed14ffe3: function(arg0) {
             let result;
             try {
@@ -444,6 +539,10 @@ function __wbg_get_imports() {
             const ret = BigInt.asUintN(64, arg0);
             return addHeapObject(ret);
         },
+        __wbindgen_object_clone_ref: function(arg0) {
+            const ret = getObject(arg0);
+            return addHeapObject(ret);
+        },
         __wbindgen_object_drop_ref: function(arg0) {
             takeObject(arg0);
         },