markdown-table-formatter 1.7.0 → 2.0.1-202611010112.0

package/README.md

@@ -13,7 +13,11 @@
 [![License](https://img.shields.io/npm/l/markdown-table-formatter.svg)](https://github.com/nvuillam/markdown-table-formatter/blob/master/LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
 
-Format markdown tables in files, using embedded [markdown-table-prettify](https://www.npmjs.com/package/markdown-table-prettify)
+Format markdown tables in files, with a fast formatting engine written in Rust and embedded as WebAssembly.
+
+No dependencies, the same npm package works on every platform (Windows, macOS, Linux, x64 and arm64) with Node.js 22.17+.
+
+The formatting rules come from [markdown-table-prettify](https://github.com/darkriszty/MarkdownTablePrettify-VSCodeExt) 4.x, plus some fixes: tables in code blocks are left untouched and column widths follow the Unicode display width (CJK, kana, hangul, emoji...).
 
 [![Banner](https://raw.githubusercontent.com/nvuillam/markdown-table-formatter/master/docs/assets/images/banner.jpg)](https://github.com/nvuillam/markdown-table-formatter#readme)
 
@@ -26,7 +30,9 @@ Format markdown tables in files, using embedded [markdown-table-prettify](https:
   - [Options](#options)
 - [Examples](#examples)
 - [Continuous Integration](#continuous-integration)
+- [pre-commit hook](#pre-commit-hook)
 - [Ignoring Code Blocks](#ignoring-code-blocks)
+- [Debug](#debug)
 - [Contribute](#contribute)
 - [Release notes](#release-notes)
 
@@ -52,12 +58,13 @@ markdown-table-formatter [OPTIONS] (file(s) or glob expression)
 
 ### Options
 
-| Parameter      | Description                       | Default value |
-|----------------|-----------------------------------|---------------|
-| -c<br/>--check | Check only, does not update files | `false`       |
-| -p<br/>--columnpadding   | Override column padding number of spaces |
-| -h<br/>--help    | Displays help                     | <!-- -->      |
-| -v<br/>--version | Displays version                  | <!-- -->      |
+| Parameter              | Description                              | Default value |
+|------------------------|------------------------------------------|---------------|
+| -c<br/>--check         | Check only, does not update files        | `false`       |
+| -p<br/>--columnpadding | Override column padding number of spaces | `0`           |
+| -z<br/>--verbose       | Verbose mode                             | `false`       |
+| -h<br/>--help          | Displays help                            | <!-- -->      |
+| -v<br/>--version       | Displays version                         | <!-- -->      |
 
 ## Examples
 
@@ -103,12 +110,32 @@ You can see **more examples in** [**test methods**](https://github.com/nvuillam/
 
 You can automatically check markdown tables formatting and fix it using [MegaLinter](https://github.com/oxsecurity/megalinter/), that embeds markdown-table-formatter out of the box
 
+## pre-commit hook
+
+Format markdown tables of committed files with [pre-commit](https://pre-commit.com), by adding to `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/nvuillam/markdown-table-formatter
+    rev: v2.0.0
+    hooks:
+      - id: markdown-table-formatter
+```
+
+The hook formats tables of staged markdown files in place: the commit stops when a file was updated, so you can review and stage the changes.
+
 ## Ignoring Code Blocks
 
 You may wish to ignore specific markdown content, especially when using with [Megalinter](https://github.com/oxsecurity/megalinter) or [terraform-docs](https://github.com/terraform-docs/terraform-docs)
 
 To achieve this, place tags `<!-- markdown-table-prettify-ignore-start -->` and `<!-- markdown-table-prettify-ignore-end -->` around the content you want markdown-table-formatter to ignore.
 
+Tables inside fenced code blocks (` ``` ` or `~~~`) and indented code blocks are never formatted.
+
+## Debug
+
+Set environment variable `NODE_DEBUG=markdown-table-formatter` to display debug logs.
+
 ## Contribute
 
 Contributions are very welcome !

package/lib/cli.js

@@ -1,7 +1,26 @@
 #! /usr/bin/env node
 const { MarkdownTableFormatter } = require("./markdown-table-formatter");
 const optionsDefinition = require("./options");
-const glob = require("glob");
+const fs = require("fs");
+const path = require("path");
+
+const EXCLUDED_DIRS = new Set(["node_modules", ".git"]);
+
+/**
+ * Lists files matching a glob pattern, skipping node_modules and .git folders
+ * @param {string} pattern - Glob pattern
+ * @return {string[]} - Sorted file paths
+ */
+function findFiles(pattern) {
+  const exclude = (entry) =>
+    EXCLUDED_DIRS.has(
+      path.basename(typeof entry === "string" ? entry : entry.name),
+    );
+  return fs
+    .globSync(pattern, { exclude })
+    .filter((file) => fs.statSync(file).isFile())
+    .sort();
+}
 
 class MarkdownTableFormatterCli {
   "use strict";
@@ -13,16 +32,7 @@ class MarkdownTableFormatterCli {
 
     // Show version
     if (this.options.version) {
-      let version = process.env.npm_package_version;
-      if (!version) {
-        try {
-          const FindPackageJson = require("find-package-json");
-          const finder = FindPackageJson(__dirname);
-          version = finder.next().value.version;
-        } catch {
-          version = "error";
-        }
-      }
+      const version = require("../package.json").version;
       const message = `markdown-table-formatter version ${version}`;
       console.log(message);
       return { stdout: message };
@@ -47,16 +57,16 @@ class MarkdownTableFormatterCli {
     let files = this.options._;
     if (files.length === 0) {
       // use default glob expression **/*.md
-      files = glob.sync("**/*.md", {});
+      files = findFiles("**/*.md");
     } else if (files.length === 1 && files[0].includes("*")) {
       // use sent glob expression
-      files = glob.sync(files[0], {});
+      files = findFiles(files[0]);
     }
     const { status, updates } = await formatter.run(files, this.options);
     // Manage result
     if (status === 0 && updates.length === 0) {
       console.log("No markdown table formatting has been applied.");
-    } else if (status === 0 && updates > 0) {
+    } else if (status === 0 && updates.length > 0) {
       console.log(
         `Formatted markdown tables in ${
           updates.length
@@ -74,4 +84,4 @@ class MarkdownTableFormatterCli {
   }
 }
 
-module.exports = { MarkdownTableFormatterCli };
+module.exports = { MarkdownTableFormatterCli, findFiles };

package/lib/engine.js

@@ -0,0 +1,44 @@
+"use strict";
+// Loads the Rust formatting engine compiled to WebAssembly (lib/wasm, built by `npm run build:wasm`)
+const fs = require("fs");
+const path = require("path");
+
+const WASM_FILE = path.join(__dirname, "wasm", "markdown_table_formatter.wasm");
+
+let wasm = null;
+
+function getWasm() {
+  if (wasm === null) {
+    if (!fs.existsSync(WASM_FILE)) {
+      throw new Error(`${WASM_FILE} not found: run "npm run build:wasm"`);
+    }
+    const module = new WebAssembly.Module(fs.readFileSync(WASM_FILE));
+    wasm = new WebAssembly.Instance(module, {}).exports;
+  }
+  return wasm;
+}
+
+/**
+ * Formats all markdown tables found in a markdown string
+ * @param {string} text - Markdown content
+ * @param {number} [columnPadding] - Number of spaces around cell values
+ * @return {string} - Formatted markdown content
+ */
+function formatTables(text, columnPadding = 0) {
+  const engine = getWasm();
+  const input = Buffer.from(text, "utf8");
+  const inputPtr = engine.mtf_alloc(input.length);
+  new Uint8Array(engine.memory.buffer, inputPtr, input.length).set(input);
+  // mtf_format frees the input buffer
+  const outputPtr = engine.mtf_format(inputPtr, input.length, columnPadding);
+  const outputLength = engine.mtf_result_len();
+  const output = Buffer.from(
+    engine.memory.buffer,
+    outputPtr,
+    outputLength,
+  ).toString("utf8");
+  engine.mtf_free_result();
+  return output;
+}
+
+module.exports = { formatTables };

package/lib/index.js

@@ -10,7 +10,12 @@ const runningAsScript = !module.parent;
 // Run asynchronously to use the returned status for process.exit
 if (runningAsScript) {
   (async () => {
-    await new MarkdownTableFormatterCli().run(process.argv);
+    try {
+      await new MarkdownTableFormatterCli().run(process.argv);
+    } catch (error) {
+      console.error(`markdown-table-formatter: ${error.message}`);
+      process.exitCode = 1;
+    }
   })();
 }
 

package/lib/markdown-table-formatter.js

@@ -1,7 +1,7 @@
 #! /usr/bin/env node
-const debug = require("debug")("markdown-table-formatter");
-const fse = require("fs-extra");
-const { CliPrettify } = require("markdown-table-prettify");
+const fs = require("fs/promises");
+const debug = require("util").debuglog("markdown-table-formatter");
+const { formatTables } = require("./engine");
 
 class MarkdownTableFormatter {
   "use strict";
@@ -15,6 +15,17 @@ class MarkdownTableFormatter {
     this.checkOnly = opts.check;
   }
 
+  /**
+   * Formats all markdown tables found in a markdown string
+   * @param {string} markdownString - Markdown content
+   * @param {object} [options] - Format options
+   * @param {number} [options.columnpadding] - Number of spaces around cell values
+   * @return {string} - Formatted markdown content
+   */
+  static formatText(markdownString, options = {}) {
+    return formatTables(markdownString, options.columnpadding || 0);
+  }
+
   /**
    * Runs markdown table formatter
    * @param {string[]} [files] - List of files to format
@@ -33,23 +44,19 @@ class MarkdownTableFormatter {
       if (debug.enabled) {
         debug(`[file] ${file}`);
       }
-      const markdown = await fse.readFile(file);
+      const markdown = await fs.readFile(file);
       const markdownString = markdown.toString();
       if (debug.enabled) {
         debug(`[file before]\n${markdownString}`);
       }
-      const prettifyOptions = {};
-      if (options.columnpadding) {
-        prettifyOptions.columnPadding = options.columnpadding;
-      }
-      const markdownStringPrettified = CliPrettify.prettify(
+      const markdownStringPrettified = MarkdownTableFormatter.formatText(
         markdownString,
-        prettifyOptions,
+        options,
       );
       const updated = markdownStringPrettified !== markdownString;
       // Update file if necessary
       if (updated && !this.checkOnly) {
-        await fse.writeFile(file, markdownStringPrettified);
+        await fs.writeFile(file, markdownStringPrettified);
         debug(`[updated] ${file} with:\n${markdownStringPrettified}`);
         if (options.verbose) {
           console.info(`- Updated file ${file}`);

package/lib/options.js

@@ -1,59 +1,184 @@
 /**
- * @fileoverview Options configuration for optionator.
+ * @fileoverview Command line options parsing (same behavior and messages as optionator, without dependency)
  * @author Nicolas Vuillamy
  */
 
 "use strict";
 
-//------------------------------------------------------------------------------
-// Requirements
-//------------------------------------------------------------------------------
+const PREPEND = "markdown-table-formatter [options]";
 
-const optionator = require("optionator");
+const OPTIONS = [
+  {
+    option: "check",
+    alias: "c",
+    type: "Boolean",
+    description:
+      "Check only (exits 1 if wrongly formatted markdown tables are found)",
+  },
+  {
+    option: "columnpadding",
+    alias: "p",
+    type: "Int",
+    description: "Override table columns padding number of spaces",
+  },
+  { option: "help", alias: "h", type: "Boolean", description: "Show help" },
+  {
+    option: "version",
+    alias: "v",
+    type: "Boolean",
+    description: "Show version",
+  },
+  {
+    option: "verbose",
+    alias: "z",
+    type: "Boolean",
+    description: "Verbose mode",
+  },
+];
 
-//------------------------------------------------------------------------------
-// Initialization and Public Interface
-//------------------------------------------------------------------------------
+const MUTUALLY_EXCLUSIVE = [["check", "help", "version"]];
 
-// exports "parse(args)", "generateHelp()", and "generateHelpForOption(optionName)"
-module.exports = optionator({
-  prepend: "markdown-table-formatter [options]",
-  defaults: {
-    concatRepeatedArrays: true,
-    mergeRepeatedObjects: true,
-  },
-  options: [
-    {
-      option: "check",
-      alias: "c",
-      type: "Boolean",
-      description:
-        "Check only (exits 1 if wrongly formatted markdown tables are found)",
-    },
-    {
-      option: "columnpadding",
-      alias: "p",
-      type: "Int",
-      description: "Override table columns padding number of spaces",
-    },
-    {
-      option: "help",
-      alias: "h",
-      type: "Boolean",
-      description: "Show help",
-    },
-    {
-      option: "version",
-      alias: "v",
-      type: "Boolean",
-      description: "Show version",
-    },
-    {
-      option: "verbose",
-      alias: "z",
-      type: "Boolean",
-      description: "Verbose mode",
-    },
-  ],
-  mutuallyExclusive: [["check", "help", "version"]],
-});
+const byName = (name) =>
+  OPTIONS.find((opt) => opt.option === name || opt.alias === name);
+const flag = (name) => (name.length === 1 ? `-${name}` : `--${name}`);
+const label = (opt) =>
+  `-${opt.alias}, --${opt.option}${opt.type === "Boolean" ? "" : ` ${opt.type}`}`;
+
+function levenshtein(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      current[j] = Math.min(
+        previous[j] + 1,
+        current[j - 1] + 1,
+        previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    previous = current;
+  }
+  return previous[b.length];
+}
+
+function invalidOption(name) {
+  const candidates = OPTIONS.flatMap((opt) => [opt.option, opt.alias]);
+  const closest = candidates.reduce((best, candidate) =>
+    levenshtein(name, candidate) < levenshtein(name, best) ? candidate : best,
+  );
+  return new Error(
+    `Invalid option '${flag(name)}' - perhaps you meant '${flag(closest)}'?`,
+  );
+}
+
+function convert(opt, value) {
+  if (opt.type === "Int") {
+    if (value === undefined) {
+      throw new Error(`Value for '${opt.option}' of type 'Int' required.`);
+    }
+    if (!/^\d+$/.test(value)) {
+      throw new Error(
+        `Invalid value for option '${opt.option}' - expected type Int, received value: ${value}.`,
+      );
+    }
+    return parseInt(value, 10);
+  }
+  if (value === undefined || value === "true") {
+    return true;
+  }
+  if (value === "false") {
+    return false;
+  }
+  throw new Error(
+    `Invalid value for option '${opt.option}' - expected type Boolean, received value: ${value}.`,
+  );
+}
+
+/**
+ * Parses command line arguments
+ * @param {string[]} input - process.argv-like array (the first 2 items are ignored)
+ * @return {object} - Option values, and positional arguments in `_`
+ */
+function parse(input) {
+  const args = input.slice(2);
+  const result = {};
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = String(args[i]);
+    if (arg === "--") {
+      positional.push(...args.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const [rawName, ...valueParts] = arg.slice(2).split("=");
+      let value = valueParts.length > 0 ? valueParts.join("=") : undefined;
+      let opt = byName(rawName);
+      if (
+        !opt &&
+        rawName.startsWith("no-") &&
+        byName(rawName.slice(3))?.type === "Boolean" &&
+        value === undefined
+      ) {
+        opt = byName(rawName.slice(3));
+        value = "false";
+      }
+      if (!opt || opt.option !== rawName.replace(/^no-/, "")) {
+        throw invalidOption(rawName);
+      }
+      if (opt.type !== "Boolean" && value === undefined) {
+        value = args[++i];
+      }
+      result[opt.option] = convert(opt, value);
+    } else if (arg.startsWith("-") && arg.length > 1) {
+      const names = arg.slice(1).split("");
+      names.forEach((name, index) => {
+        const opt = byName(name);
+        if (!opt || opt.alias !== name) {
+          throw /\d/.test(name)
+            ? new Error(`No -NUM option defined.`)
+            : invalidOption(name);
+        }
+        if (opt.type !== "Boolean") {
+          if (index !== names.length - 1) {
+            throw new Error(
+              `Can't set argument '${name}' when not last flag in a group of short flags.`,
+            );
+          }
+          result[opt.option] = convert(opt, args[++i]);
+        } else {
+          result[opt.option] = true;
+        }
+      });
+    } else {
+      positional.push(arg);
+    }
+  }
+  for (const group of MUTUALLY_EXCLUSIVE) {
+    const used = group.filter((name) => name in result);
+    if (used.length > 1) {
+      throw new Error(
+        `The options ${used.map((name) => `--${name}`).join(" and ")} are mutually exclusive - you cannot use them at the same time.`,
+      );
+    }
+  }
+  result._ = positional;
+  return result;
+}
+
+function generateHelp() {
+  const width = Math.max(...OPTIONS.map((opt) => label(opt).length));
+  const lines = OPTIONS.map(
+    (opt) => `  ${label(opt).padEnd(width)}  ${opt.description}`,
+  );
+  return `${PREPEND}\n\n${lines.join("\n")}`;
+}
+
+function generateHelpForOption(name) {
+  const opt = byName(name);
+  if (!opt) {
+    return invalidOption(name).message;
+  }
+  const title = label(opt);
+  return `${title}\n${"=".repeat(title.length)}\ndescription: ${opt.description}.`;
+}
+
+module.exports = { parse, generateHelp, generateHelpForOption };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "markdown-table-formatter",
-  "version": "1.7.0",
-  "description": "Format markdown tables in files",
+  "version": "2.0.1-202611010112.0",
+  "description": "Format markdown tables in files (Rust engine compiled to WebAssembly, no dependencies)",
   "main": "./lib/index.js",
   "files": [
     "lib/"
@@ -10,10 +10,15 @@
     "markdown-table-formatter": "lib/index.js"
   },
   "scripts": {
-    "lint:fix": "eslint **/*.js --fix && prettier --write \"./lib/**/*.{js,jsx,json}\" --tab-width 4 --print-width 150",
-    "test": "mocha \"test/**/*.test.js\"",
-    "test:coverage": "nyc npm run test",
-    "test:debug": "env DEBUG=markdown-table-formatter mocha --reporter spec \"test/**/*.test.js\""
+    "build:wasm": "node scripts/build-wasm.js",
+    "lint:fix": "eslint --fix && prettier --write \"./lib/**/*.{js,jsx,json}\" --tab-width 4 --print-width 150",
+    "prepack": "node scripts/build-wasm.js --if-needed",
+    "pretest": "npm run build:wasm",
+    "test": "node --test --test-timeout=300000 \"test/**/*.test.js\"",
+    "pretest:coverage": "npm run build:wasm",
+    "test:coverage": "node --test --test-timeout=300000 --experimental-test-coverage --test-coverage-include=\"lib/**\" \"test/**/*.test.js\"",
+    "test:rust": "cargo test --manifest-path rust/Cargo.toml",
+    "test:debug": "env NODE_DEBUG=markdown-table-formatter node --test --test-timeout=300000 --test-reporter=spec \"test/**/*.test.js\""
   },
   "repository": {
     "type": "git",
@@ -32,46 +37,13 @@
     "url": "https://github.com/nvuillam/markdown-table-formatter/issues"
   },
   "homepage": "https://github.com/nvuillam/markdown-table-formatter#readme",
-  "dependencies": {
-    "debug": "^4.3.4",
-    "find-package-json": "^1.2.0",
-    "fs-extra": "^11.1.1",
-    "glob": "^13.0.0",
-    "markdown-table-prettify": "^3.6.0",
-    "optionator": "^0.9.4"
-  },
   "devDependencies": {
-    "@babel/eslint-parser": "^7.23.3",
-    "eslint": "^9.0.0",
-    "mega-linter-runner": "^9.0.0",
-    "mocha": "^11.0.0",
-    "nyc": "^17.0.0",
-    "which": "^6.0.0"
+    "eslint": "^10.14.0"
   },
   "engines": {
-    "node": ">=18.0.0"
-  },
-  "mocha": {
-    "require": [
-      "test/helpers/init.js"
-    ],
-    "watch-extensions": [
-      "js"
-    ],
-    "recursive": true,
-    "reporter": "spec",
-    "timeout": "300000"
+    "node": ">=22.17.0"
   },
-  "nyc": {
-    "include": [
-      "lib/**"
-    ],
-    "extension": [
-      ".js"
-    ],
-    "reporter": [
-      "html"
-    ],
-    "all": true
+  "overrides": {
+    "minimatch": "^11.0.1"
   }
 }