@takazudo/mdx-formatter 0.5.0-next.2 → 1.0.0

package/README.md

@@ -1,18 +1,20 @@
 # @takazudo/mdx-formatter
 
-AST-based markdown and MDX formatter with Japanese text support. Built on top of the unified ecosystem with remark plugins.
+AST-based markdown and MDX formatter with Japanese text support. Powered by a Rust engine (via napi-rs) for fast, reliable formatting.
 
 ## Features
 
-- **AST-based formatting** - Uses remark's AST for reliable formatting
-- **MDX support** - Full support for MDX syntax including JSX components
-- **Japanese text formatting** - Special handling for Japanese punctuation and URLs
-- **Docusaurus support** - Preserves Docusaurus admonitions (:::note, :::tip, etc.)
-- **HTML block formatting** - Proper indentation for HTML blocks (dl, table, ul, div, etc.)
-- **GFM features** - Tables, strikethrough, task lists
-- **Frontmatter preservation** - YAML frontmatter support
-- **CLI and API** - Use as command-line tool or import as library
-- **Configurable** - Customize component lists and rules via config file or API
+- **Rust-powered** — Native Rust engine via napi-rs, 3-7x faster than pure JS
+- **Hybrid formatter** — Parses AST for analysis, applies edits to original source lines (no lossy round-trip)
+- **MDX support** — Full support for MDX syntax including JSX components, imports, exports
+- **Japanese text handling** — Preserves Japanese punctuation and text formatting
+- **Docusaurus admonitions** — Preserves `:::note`, `:::tip`, `:::warning` etc. syntax
+- **HTML block formatting** — Proper indentation for HTML blocks (dl, table, ul, div, etc.)
+- **GFM features** — Tables, strikethrough, task lists
+- **YAML frontmatter** — Formatting with safe value pre-processing
+- **CLI and API** — Use as command-line tool or import as library
+- **WASM support** — Browser-compatible WASM build available
+- **Configurable** — 10 independently toggleable rules via config file or API
 
 ## Installation
 
@@ -26,6 +28,12 @@ Or use directly with npx:
 npx @takazudo/mdx-formatter --write "**/*.md"
 ```
 
+### Prerelease (next)
+
+```bash
+npm install @takazudo/mdx-formatter@next
+```
+
 ## Usage
 
 ### CLI
@@ -36,6 +44,9 @@ mdx-formatter --check "**/*.{md,mdx}"
 
 # Format files in place
 mdx-formatter --write "**/*.{md,mdx}"
+
+# With config file
+mdx-formatter --config .mdx-formatter.json --write "**/*.mdx"
 ```
 
 ### API
@@ -47,24 +58,48 @@ const formatted = await format('# Hello\nWorld');
 console.log(formatted); // '# Hello\n\nWorld'
 ```
 
+### Browser / WebView
+
+```javascript
+import { format } from '@takazudo/mdx-formatter/browser';
+
+const formatted = await format('# Hello\nWorld');
+```
+
+The browser export avoids Node.js `fs`/`path` dependencies. See [Browser Usage](https://takazudomodular.com/pj/mdx-formatter/docs/overview/browser-usage) for details.
+
 ## Documentation
 
-For full documentation including configuration, options reference, formatting rules, and API reference, visit the [documentation site](https://takazudomodular.com/pj/mdx-formatter/).
+Full documentation at **[takazudomodular.com/pj/mdx-formatter](https://takazudomodular.com/pj/mdx-formatter/)**:
+
+- [Overview](https://takazudomodular.com/pj/mdx-formatter/docs/overview) — Installation, usage, API, configuration
+- [Formatting Rules](https://takazudomodular.com/pj/mdx-formatter/docs/formatting) — How the formatter handles each construct
+- [Options](https://takazudomodular.com/pj/mdx-formatter/docs/options) — Per-rule configuration reference
+- [Architecture](https://takazudomodular.com/pj/mdx-formatter/docs/architecture) — Hybrid formatter approach, Rust rewrite strategy
+- [Changelog](https://takazudomodular.com/pj/mdx-formatter/docs/changelog) — Release history
+
+## Architecture
+
+The formatting engine is written in Rust using [markdown-rs](https://github.com/wooorm/markdown-rs) and [napi-rs](https://napi.rs/). The npm package loads the native Rust module at runtime. A standalone CLI binary and WASM build for browsers are also available. See [Architecture](https://takazudomodular.com/pj/mdx-formatter/docs/architecture) for details.
 
 ## Development
 
 ```bash
-# Install dependencies
-pnpm install
-
-# Run tests
-pnpm test
+pnpm install        # Install dependencies
+pnpm build          # Compile TypeScript
+pnpm test           # Run tests (207 tests)
+pnpm test:watch     # Watch mode
+pnpm test:coverage  # Coverage report
+pnpm lint           # ESLint check
+pnpm check          # Prettier + ESLint check
+```
 
-# Run tests in watch mode
-pnpm test:watch
+### Doc Site
 
-# Run tests with coverage
-pnpm test:coverage
+```bash
+pnpm --dir doc dev           # Dev server on port 3518
+pnpm --dir doc dev:network   # Network accessible (0.0.0.0:3518)
+pnpm --dir doc build         # Production build
 ```
 
 ## License

package/dist/browser.d.ts

@@ -1,22 +1,12 @@
 /**
  * Browser-safe entry point for mdx-formatter.
  *
- * Unlike the main entry point (`index.ts`), this module does NOT import
- * `load-config.ts` and therefore avoids pulling in Node's `fs` and `path`.
- * Use this export (`@takazudo/mdx-formatter/browser`) when bundling for
- * Vite, webpack, or any browser environment.
+ * Note: In browser environments, use the WASM module directly instead.
+ * This export is kept for API compatibility but requires the napi native
+ * module to be available (Node.js only).
  *
- * By default, `formatHtmlBlocksInMdx` is **disabled** in browser mode because
- * that rule depends on prettier, which is a Node.js dependency. If the code
- * path is never reached, bundlers can tree-shake the prettier import away.
+ * For true browser usage, see the WASM package at
+ * `crates/mdx-formatter-wasm/` or the doc site playground.
  */
-import { detectMdx } from './detect-mdx.js';
-import type { FormatterSettings, DeepPartial } from './types.js';
-export { detectMdx };
-/**
- * Format markdown/MDX content in browser environments.
- *
- * Uses browser-safe defaults (formatHtmlBlocksInMdx disabled).
- * Pass an optional `settings` object to override individual rules.
- */
-export declare function format(content: string, settings?: DeepPartial<FormatterSettings>): Promise<string>;
+export { format, detectMdx } from './index.js';
+export type { FormatterSettings, DeepPartial } from './types.js';

package/dist/browser.js

@@ -1,49 +1,11 @@
 /**
  * Browser-safe entry point for mdx-formatter.
  *
- * Unlike the main entry point (`index.ts`), this module does NOT import
- * `load-config.ts` and therefore avoids pulling in Node's `fs` and `path`.
- * Use this export (`@takazudo/mdx-formatter/browser`) when bundling for
- * Vite, webpack, or any browser environment.
+ * Note: In browser environments, use the WASM module directly instead.
+ * This export is kept for API compatibility but requires the napi native
+ * module to be available (Node.js only).
  *
- * By default, `formatHtmlBlocksInMdx` is **disabled** in browser mode because
- * that rule depends on prettier, which is a Node.js dependency. If the code
- * path is never reached, bundlers can tree-shake the prettier import away.
+ * For true browser usage, see the WASM package at
+ * `crates/mdx-formatter-wasm/` or the doc site playground.
  */
-import { HybridFormatter } from './hybrid-formatter.js';
-import { detectMdx } from './detect-mdx.js';
-import { formatterSettings } from './settings.js';
-import { deepCloneSettings, deepMerge } from './utils.js';
-export { detectMdx };
-const MAX_ITERATIONS = 3;
-// Browser-safe defaults: disable formatHtmlBlocksInMdx (requires prettier/Node.js)
-const browserDefaults = {
-    ...formatterSettings,
-    formatHtmlBlocksInMdx: {
-        ...formatterSettings.formatHtmlBlocksInMdx,
-        enabled: false,
-    },
-};
-/**
- * Format markdown/MDX content in browser environments.
- *
- * Uses browser-safe defaults (formatHtmlBlocksInMdx disabled).
- * Pass an optional `settings` object to override individual rules.
- */
-export async function format(content, settings = {}) {
-    const merged = deepMerge(deepCloneSettings(browserDefaults), settings);
-    try {
-        let result = content;
-        for (let i = 0; i < MAX_ITERATIONS; i++) {
-            const formatter = new HybridFormatter(result, merged);
-            const formatted = await formatter.format();
-            if (formatted === result)
-                break;
-            result = formatted;
-        }
-        return result;
-    }
-    catch {
-        return content;
-    }
-}
+export { format, detectMdx } from './index.js';

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 /**
- * Main entry point for the markdown formatter
- * Uses HybridFormatter for AST-based formatting
+ * Main entry point for mdx-formatter.
+ * Uses the Rust napi formatter as the sole formatting engine.
  */
 import { detectMdx } from './detect-mdx.js';
 import type { FormatOptions } from './types.js';
 export { detectMdx };
 /**
- * Format markdown/MDX content using hybrid AST approach
+ * Format markdown/MDX content using the Rust formatter.
  */
 export declare function format(content: string, options?: FormatOptions): Promise<string>;
 /**

package/dist/index.js

@@ -1,37 +1,19 @@
 /**
- * Main entry point for the markdown formatter
- * Uses HybridFormatter for AST-based formatting
+ * Main entry point for mdx-formatter.
+ * Uses the Rust napi formatter as the sole formatting engine.
  */
 import { promises as fs } from 'fs';
-import { HybridFormatter } from './hybrid-formatter.js';
 import { loadConfig } from './load-config.js';
 import { detectMdx } from './detect-mdx.js';
+import { nativeFormat } from './rust-formatter.js';
 export { detectMdx };
 /**
- * Format markdown/MDX content using hybrid AST approach
+ * Format markdown/MDX content using the Rust formatter.
  */
 export async function format(content, options = {}) {
-    try {
-        const settings = loadConfig(options);
-        let result = content;
-        // Some rule interactions (e.g., list indent normalization + addEmptyLinesInBlockJsx)
-        // may require multiple passes to converge. 3 iterations is sufficient for all known
-        // cases (most files converge in 1, edge cases in 2).
-        const MAX_ITERATIONS = 3;
-        for (let i = 0; i < MAX_ITERATIONS; i++) {
-            const formatter = new HybridFormatter(result, settings);
-            const formatted = await formatter.format();
-            if (formatted === result)
-                break;
-            result = formatted;
-        }
-        return result;
-    }
-    catch {
-        // Silently return original content if formatting fails
-        // This is expected for files with certain JSX patterns that remark-mdx doesn't like
-        return content;
-    }
+    const settings = loadConfig(options);
+    const settingsJson = JSON.stringify(settings);
+    return nativeFormat(content, settingsJson);
 }
 /**
  * Format a file and write it back if changed
@@ -53,7 +35,6 @@ export async function checkFile(filePath, options = {}) {
     const formatted = await format(content, options);
     return content !== formatted;
 }
-// Export all functions
 export default {
     format,
     formatFile,

package/dist/load-config.js

@@ -25,7 +25,11 @@ function findConfigFile(configPath) {
     if (configPath) {
         try {
             const content = readFileSync(resolve(configPath), 'utf-8');
-            return JSON.parse(content);
+            const parsed = JSON.parse(content);
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                return null;
+            }
+            return parsed;
         }
         catch {
             return null;
@@ -34,7 +38,11 @@ function findConfigFile(configPath) {
     // Try .mdx-formatter.json in cwd
     try {
         const content = readFileSync(resolve('.mdx-formatter.json'), 'utf-8');
-        return JSON.parse(content);
+        const parsed = JSON.parse(content);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            return null;
+        }
+        return parsed;
     }
     catch {
         // Not found, try package.json

package/dist/rust-formatter.d.ts

@@ -1,15 +1,16 @@
 /**
- * Wrapper for the Rust napi formatter.
- * This module loads the native Rust formatter compiled via napi-rs
- * and exposes the same format() API as the TypeScript implementation.
+ * Rust napi formatter loader.
+ * Loads the native Rust formatter compiled via napi-rs.
+ * This is the sole formatting engine — no TypeScript fallback.
  */
-import type { FormatOptions } from './types.js';
+type NativeFormat = (content: string, settingsJson: string) => string;
 /**
- * Check if the Rust formatter is available
+ * The native format function. Loaded once at module init.
+ * Throws if the native module is not available.
  */
-export declare function isRustFormatterAvailable(): boolean;
+export declare const nativeFormat: NativeFormat;
 /**
- * Format markdown/MDX content using the Rust formatter
- * API-compatible with the TypeScript format() function
+ * Check if the Rust formatter is available
  */
-export declare function format(content: string, options?: FormatOptions): Promise<string>;
+export declare function isRustFormatterAvailable(): boolean;
+export {};

package/dist/rust-formatter.js

@@ -1,35 +1,57 @@
 /**
- * Wrapper for the Rust napi formatter.
- * This module loads the native Rust formatter compiled via napi-rs
- * and exposes the same format() API as the TypeScript implementation.
+ * Rust napi formatter loader.
+ * Loads the native Rust formatter compiled via napi-rs.
+ * This is the sole formatting engine — no TypeScript fallback.
  */
 import { createRequire } from 'module';
-import { loadConfig } from './load-config.js';
+import { platform, arch } from 'os';
 const require = createRequire(import.meta.url);
-// Try to load the native module
-let nativeFormat = null;
-try {
-    const native = require('../crates/mdx-formatter-napi/mdx-formatter-napi.node');
-    nativeFormat = native.format;
+function getPackageName() {
+    const platformName = platform();
+    const archName = arch();
+    const platformMap = {
+        darwin: {
+            arm64: '@takazudo/mdx-formatter-darwin-arm64',
+            x64: '@takazudo/mdx-formatter-darwin-x64',
+        },
+        linux: {
+            x64: '@takazudo/mdx-formatter-linux-x64-gnu',
+        },
+        win32: {
+            x64: '@takazudo/mdx-formatter-win32-x64-msvc',
+        },
+    };
+    return platformMap[platformName]?.[archName] ?? '';
 }
-catch {
-    // Native module not available - not built yet or wrong platform
+function loadNativeModule() {
+    // Try platform-specific npm package first
+    const packageName = getPackageName();
+    if (packageName) {
+        try {
+            const native = require(packageName);
+            return native.format;
+        }
+        catch {
+            // Platform package not installed, try local build
+        }
+    }
+    // Try local build
+    try {
+        const native = require('../crates/mdx-formatter-napi/mdx-formatter-napi.node');
+        return native.format;
+    }
+    catch {
+        throw new Error('Rust native module not available. Build it with: pnpm build:rust');
+    }
 }
 /**
- * Check if the Rust formatter is available
+ * The native format function. Loaded once at module init.
+ * Throws if the native module is not available.
  */
-export function isRustFormatterAvailable() {
-    return nativeFormat !== null;
-}
+export const nativeFormat = loadNativeModule();
 /**
- * Format markdown/MDX content using the Rust formatter
- * API-compatible with the TypeScript format() function
+ * Check if the Rust formatter is available
  */
-export async function format(content, options = {}) {
-    if (!nativeFormat) {
-        throw new Error('Rust formatter not available. Build it first with: cd crates/mdx-formatter-napi && cargo build');
-    }
-    const settings = loadConfig(options);
-    const settingsJson = JSON.stringify(settings);
-    return nativeFormat(content, settingsJson);
+export function isRustFormatterAvailable() {
+    return true; // If we got here, the module loaded successfully
 }

package/dist/settings.d.ts

@@ -4,4 +4,3 @@
  */
 import type { FormatterSettings } from './types.js';
 export declare const formatterSettings: FormatterSettings;
-export declare function getEnabledRules(): Partial<FormatterSettings>;

package/dist/settings.js

@@ -83,12 +83,3 @@ export const formatterSettings = {
         minConfidence: 0.7, // Minimum confidence score to use detected indentation
     },
 };
-// Export function to get only enabled rules
-export function getEnabledRules() {
-    return Object.entries(formatterSettings)
-        .filter(([_, config]) => config.enabled)
-        .reduce((acc, [key, config]) => {
-        acc[key] = config;
-        return acc;
-    }, {});
-}

package/dist/types.d.ts

@@ -1,68 +1,6 @@
 /**
  * Core type definitions for mdx-formatter
  */
-import type { Node, Parent, Position } from 'unist';
-import type { Root } from 'mdast';
-export type { Node, Parent, Position, Root };
-/**
- * Common AST node interfaces used across plugins
- */
-export interface ParentNode extends Node {
-    children: Node[];
-}
-export interface TextNode extends Node {
-    type: 'text';
-    value: string;
-}
-export interface HeadingNode extends Node {
-    type: 'heading';
-    children: Node[];
-}
-export interface HtmlNode extends Node {
-    value?: string;
-}
-export interface ListNode extends Node {
-    type: 'list';
-    ordered?: boolean;
-    start?: number | null;
-    spread?: boolean;
-    children: ListItemNode[];
-}
-export interface ListItemNode extends Node {
-    type: 'listItem';
-    spread?: boolean;
-    data?: Record<string, unknown>;
-}
-/**
- * MDX JSX attribute value expression node
- */
-export interface MdxJsxAttributeValueExpression {
-    type: 'mdxJsxAttributeValueExpression';
-    value?: string;
-    position?: Position;
-    data?: {
-        estree?: unknown;
-    };
-}
-/**
- * MDX JSX attribute node
- */
-export interface MdxJsxAttribute {
-    type: 'mdxJsxAttribute';
-    name: string;
-    value: string | MdxJsxAttributeValueExpression | null | undefined;
-}
-/**
- * MDX JSX element node (flow or text)
- */
-export interface MdxJsxElement extends Node {
-    type: 'mdxJsxFlowElement' | 'mdxJsxTextElement';
-    name: string | null;
-    attributes: MdxJsxAttribute[];
-    children: Node[];
-    selfClosing?: boolean;
-    data?: Record<string, unknown>;
-}
 /**
  * Individual formatter setting rule configurations
  */
@@ -157,72 +95,3 @@ export interface FormatOptions {
 export type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
 };
-/**
- * Formatter operation types used in HybridFormatter
- */
-export type FormatterOperation = {
-    type: 'insertLine';
-    startLine: number;
-    content: string;
-} | {
-    type: 'replaceLines';
-    startLine: number;
-    endLine: number;
-    lines: string[];
-} | {
-    type: 'indentLine';
-    startLine: number;
-    indent: string;
-} | {
-    type: 'fixListIndent';
-    startLine: number;
-    indent: string;
-} | {
-    type: 'replaceHtmlBlock';
-    startLine: number;
-    endLine: number;
-    content: string;
-};
-/**
- * Position map entry for line/character mapping
- */
-export interface PositionMapEntry {
-    line: number;
-    start: number;
-    end: number;
-}
-/**
- * Indent detector interface (for duck-typed fallback)
- */
-export interface IndentDetectorLike {
-    getIndentSize(): number;
-    getIndentType(): string;
-    getIndentString(): string;
-    getConfidence(): number;
-    formatWithIndent(text: string, level: number): string;
-}
-/**
- * Indent detection statistics
- */
-export interface IndentStats {
-    totalLines: number;
-    indentedLines: number;
-    patterns: Record<string, number>;
-    tabLines: number;
-    spaceLines: number;
-}
-/**
- * Indent pattern entry
- */
-export interface IndentPattern {
-    type: 'tab' | 'space';
-    size: number;
-}
-/**
- * JSX stack entry used in SpecificFormatter
- */
-export interface JsxStackEntry {
-    name: string;
-    isContainer: boolean;
-    hasContent: boolean;
-}

package/dist/utils.js

@@ -29,6 +29,9 @@ export function deepCloneSettings(obj) {
 export function deepMerge(target, source) {
     const result = deepCloneSettings(target);
     for (const key of Object.keys(source)) {
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+            continue;
+        }
         const sourceVal = source[key];
         const targetVal = result[key];
         if (sourceVal &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/mdx-formatter",
-  "version": "0.5.0-next.2",
+  "version": "1.0.0",
   "description": "AST-based markdown and MDX formatter with Japanese text support",
   "type": "module",
   "main": "dist/index.js",
@@ -38,8 +38,13 @@
     "check": "prettier --check . && eslint .",
     "check:fix": "prettier --write . && eslint --fix .",
     "test:rust": "vitest run --config vitest.rust.config.ts",
-    "build:rust": "cd crates/mdx-formatter-napi && cargo build",
-    "build:rust:release": "cd crates/mdx-formatter-napi && cargo build --release",
+    "test:rust-passthrough": "vitest run --config vitest.rust-passthrough.config.ts",
+    "build:rust": ". \"$HOME/.cargo/env\" && cargo build -p mdx-formatter-napi && cp target/debug/libmdx_formatter_napi.so crates/mdx-formatter-napi/mdx-formatter-napi.node",
+    "build:rust:release": ". \"$HOME/.cargo/env\" && cargo build -p mdx-formatter-napi --release && cp target/release/libmdx_formatter_napi.so crates/mdx-formatter-napi/mdx-formatter-napi.node",
+    "benchmark": "npx tsx benchmark/run.ts",
+    "build:wasm": ". \"$HOME/.cargo/env\" && wasm-pack build crates/mdx-formatter-wasm --target web --out-dir ../../wasm/pkg",
+    "build:wasm:bundler": ". \"$HOME/.cargo/env\" && wasm-pack build crates/mdx-formatter-wasm --target bundler --out-dir ../../wasm/pkg-bundler",
+    "build:wasm:doc": ". \"$HOME/.cargo/env\" && wasm-pack build crates/mdx-formatter-wasm --target web --out-dir ../../doc/src/wasm-pkg && mkdir -p doc/public/wasm && cp doc/src/wasm-pkg/mdx_formatter_wasm_bg.wasm doc/public/wasm/",
     "b4push": "./scripts/run-b4push.sh",
     "doc:start": "pnpm --dir doc start",
     "prepublishOnly": "tsc && vitest run"
@@ -70,33 +75,29 @@
     "chalk": "^5.3.0",
     "commander": "^14.0.3",
     "glob": "^13.0.1",
-    "js-yaml": "^4.1.1",
-    "prettier": "^3.8.0",
-    "remark": "^15.0.1",
-    "remark-directive": "^3.0.0",
-    "remark-frontmatter": "^5.0.0",
-    "remark-gfm": "^4.0.0",
-    "remark-mdx": "^3.0.0",
-    "remark-parse": "^11.0.0",
-    "remark-stringify": "^11.0.0",
-    "unified": "^11.0.4",
-    "unist-util-visit": "^5.0.0"
+    "js-yaml": "^4.1.1"
   },
   "devDependencies": {
-    "@types/hast": "^3.0.4",
     "@types/js-yaml": "^4.0.9",
-    "@types/mdast": "^4.0.4",
     "@types/node": "^25.2.1",
-    "@types/unist": "^3.0.3",
     "@vitest/coverage-v8": "^4.0.17",
     "eslint": "^9.39.2",
     "lefthook": "^2.1.4",
+    "prettier": "^3.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.54.0",
-    "vfile": "^6.0.3",
     "vitest": "^4.0.17"
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "napi": {
+    "binaryName": "mdx-formatter-napi",
+    "targets": [
+      "aarch64-apple-darwin",
+      "x86_64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "x86_64-pc-windows-msvc"
+    ]
   }
 }