@takazudo/mdx-formatter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Takazudo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @takazudo/mdx-formatter
+
+AST-based markdown and MDX formatter with Japanese text support. Built on top of the unified ecosystem with remark plugins.
+
+## 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
+
+## Installation
+
+```bash
+npm install @takazudo/mdx-formatter
+```
+
+Or use directly with npx:
+
+```bash
+npx @takazudo/mdx-formatter --write "**/*.md"
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Check files (exit with error if formatting needed)
+mdx-formatter --check "**/*.{md,mdx}"
+
+# Format files in place
+mdx-formatter --write "**/*.{md,mdx}"
+```
+
+### API
+
+```javascript
+import { format } from '@takazudo/mdx-formatter';
+
+const formatted = await format('# Hello\nWorld');
+console.log(formatted); // '# Hello\n\nWorld'
+```
+
+## Documentation
+
+For full documentation including configuration, options reference, formatting rules, and API reference, visit the [documentation site](https://takazudo.github.io/mdx-formatter/).
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Run tests with coverage
+pnpm test:coverage
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import { readFileSync } from 'fs';
+import { program } from 'commander';
+import { glob } from 'glob';
+import chalk from 'chalk';
+import { formatFile, checkFile } from './index.js';
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+program
+    .name('mdx-formatter')
+    .description('AST-based markdown and MDX formatter')
+    .version(pkg.version)
+    .argument('[patterns...]', 'Glob patterns for files to format', ['**/*.{md,mdx}'])
+    .option('-w, --write', 'Write formatted files in place')
+    .option('-c, --check', 'Check if files need formatting')
+    .option('--config <path>', 'Path to config file (.mdx-formatter.json)')
+    .option('--ignore <patterns>', 'Comma-separated patterns to ignore', 'node_modules/**,dist/**,build/**,.git/**,worktrees/**')
+    .action(async (patterns, options) => {
+    try {
+        await main(patterns, options);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red('Error:'), message);
+        process.exit(1);
+    }
+});
+program.parse();
+/**
+ * Main CLI function
+ */
+async function main(patterns, options) {
+    const ignorePatterns = options.ignore.split(',').map((p) => p.trim());
+    // Build format options from CLI flags
+    const formatOptions = {};
+    if (options.config) {
+        formatOptions.config = options.config;
+    }
+    // Find all matching files
+    const files = [];
+    for (const pattern of patterns) {
+        const matches = await glob(pattern, {
+            ignore: ignorePatterns,
+            nodir: true,
+        });
+        files.push(...matches);
+    }
+    // Remove duplicates
+    const uniqueFiles = [...new Set(files)];
+    if (uniqueFiles.length === 0) {
+        console.log(chalk.yellow('No files found matching the patterns.'));
+        return;
+    }
+    console.log(chalk.blue(`Processing ${uniqueFiles.length} file(s)...`));
+    let changedCount = 0;
+    let errorCount = 0;
+    for (const file of uniqueFiles) {
+        try {
+            if (options.write) {
+                const changed = await formatFile(file, formatOptions);
+                if (changed) {
+                    changedCount++;
+                    console.log(chalk.green('✓'), chalk.gray(file), chalk.green('formatted'));
+                }
+                else {
+                    console.log(chalk.gray('○'), chalk.gray(file), chalk.gray('unchanged'));
+                }
+            }
+            else if (options.check) {
+                const needsFormatting = await checkFile(file, formatOptions);
+                if (needsFormatting) {
+                    changedCount++;
+                    console.log(chalk.yellow('⚠'), chalk.gray(file), chalk.yellow('needs formatting'));
+                }
+                else {
+                    console.log(chalk.green('✓'), chalk.gray(file), chalk.green('formatted correctly'));
+                }
+            }
+            else {
+                // Default: just show what would be done
+                const needsFormatting = await checkFile(file, formatOptions);
+                if (needsFormatting) {
+                    changedCount++;
+                    console.log(chalk.blue('→'), chalk.gray(file), chalk.blue('would be formatted'));
+                }
+                else {
+                    console.log(chalk.gray('○'), chalk.gray(file), chalk.gray('already formatted'));
+                }
+            }
+        }
+        catch (error) {
+            errorCount++;
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(chalk.red('✗'), chalk.gray(file), chalk.red(message));
+        }
+    }
+    // Summary
+    console.log();
+    if (options.write) {
+        if (changedCount > 0) {
+            console.log(chalk.green(`✓ Formatted ${changedCount} file(s)`));
+        }
+        else {
+            console.log(chalk.gray('All files are already formatted'));
+        }
+    }
+    else if (options.check) {
+        if (changedCount > 0) {
+            console.log(chalk.yellow(`⚠ ${changedCount} file(s) need formatting`));
+            process.exit(1); // Exit with error code for CI
+        }
+        else {
+            console.log(chalk.green('✓ All files are formatted correctly'));
+        }
+    }
+    else {
+        if (changedCount > 0) {
+            console.log(chalk.blue(`→ ${changedCount} file(s) would be formatted`));
+            console.log(chalk.gray('Use --write to apply changes'));
+        }
+        else {
+            console.log(chalk.gray('All files are already formatted'));
+        }
+    }
+    if (errorCount > 0) {
+        console.log(chalk.red(`✗ ${errorCount} error(s) occurred`));
+        process.exit(1);
+    }
+}

package/dist/html-block-formatter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * HTML Block Formatter
+ * Formats HTML blocks within MDX content using Prettier or built-in formatting
+ */
+import type { FormatHtmlBlocksInMdxSetting } from './types.js';
+export declare class HtmlBlockFormatter {
+    private settings;
+    private readonly htmlElements;
+    constructor(settings?: Partial<FormatHtmlBlocksInMdxSetting>);
+    /**
+     * Check if a tag name is an HTML element (not a JSX component)
+     */
+    isHtmlElement(tagName: string): boolean;
+    /**
+     * Format HTML content using Prettier
+     */
+    formatWithPrettier(html: string): Promise<string>;
+    /**
+     * Extract HTML block from position in original content
+     */
+    extractHtmlBlock(content: string, startPos: {
+        line: number;
+        column: number;
+    }, endPos: {
+        line: number;
+        column: number;
+    }): string;
+    /**
+     * Find matching closing tag for an opening tag
+     */
+    findMatchingClosingTag(content: string, startIndex: number, tagName: string): number;
+    /**
+     * Format MDX content with HTML block formatting
+     */
+    format(content: string): Promise<string>;
+    /**
+     * Replace HTML block in content with formatted version
+     */
+    replaceHtmlBlock(content: string, startPos: {
+        line: number;
+        column: number;
+    }, endPos: {
+        line: number;
+        column: number;
+    }, replacement: string): string;
+}

package/dist/html-block-formatter.js

@@ -0,0 +1,370 @@
+/**
+ * HTML Block Formatter
+ * Formats HTML blocks within MDX content using Prettier or built-in formatting
+ */
+import * as prettier from 'prettier';
+export class HtmlBlockFormatter {
+    settings;
+    htmlElements;
+    constructor(settings = {}) {
+        this.settings = {
+            enabled: true,
+            description: '',
+            formatterConfig: {
+                parser: 'html',
+                tabWidth: 2,
+                useTabs: false,
+            },
+            ...settings,
+        };
+        // List of HTML elements (not JSX components which start with uppercase)
+        this.htmlElements = new Set([
+            // Structure
+            'html',
+            'head',
+            'body',
+            'div',
+            'span',
+            'section',
+            'article',
+            'aside',
+            'header',
+            'footer',
+            'main',
+            'nav',
+            'figure',
+            'figcaption',
+            // Text
+            'p',
+            'h1',
+            'h2',
+            'h3',
+            'h4',
+            'h5',
+            'h6',
+            'blockquote',
+            'pre',
+            'code',
+            'em',
+            'strong',
+            'i',
+            'b',
+            'u',
+            's',
+            'mark',
+            'small',
+            'del',
+            'ins',
+            'sub',
+            'sup',
+            'cite',
+            'q',
+            'abbr',
+            'address',
+            'time',
+            // Lists
+            'ul',
+            'ol',
+            'li',
+            'dl',
+            'dt',
+            'dd',
+            // Tables
+            'table',
+            'thead',
+            'tbody',
+            'tfoot',
+            'tr',
+            'td',
+            'th',
+            'caption',
+            'colgroup',
+            'col',
+            // Forms
+            'form',
+            'input',
+            'textarea',
+            'button',
+            'select',
+            'option',
+            'optgroup',
+            'label',
+            'fieldset',
+            'legend',
+            'datalist',
+            'output',
+            'progress',
+            'meter',
+            // Media
+            'img',
+            'audio',
+            'video',
+            'source',
+            'track',
+            'picture',
+            'iframe',
+            'embed',
+            'object',
+            'param',
+            'canvas',
+            'svg',
+            // Other
+            'a',
+            'br',
+            'hr',
+            'details',
+            'summary',
+            'dialog',
+            'menu',
+            'menuitem',
+            'script',
+            'noscript',
+            'template',
+            'slot',
+        ]);
+    }
+    /**
+     * Check if a tag name is an HTML element (not a JSX component)
+     */
+    isHtmlElement(tagName) {
+        if (!tagName)
+            return false;
+        // HTML elements are lowercase or known HTML elements
+        return this.htmlElements.has(tagName.toLowerCase());
+    }
+    /**
+     * Format HTML content using Prettier
+     */
+    async formatWithPrettier(html) {
+        try {
+            // Preprocess: Remove newlines within dd and dt tags to keep them on single lines
+            // This is important for Japanese text readability in definition lists
+            const preprocessed = html
+                .replace(/<dd>([\s\S]*?)<\/dd>/g, (_match, content) => {
+                // Replace multiple whitespaces (including newlines) with single space
+                const cleaned = content.replace(/\s+/g, ' ').trim();
+                return `<dd>${cleaned}</dd>`;
+            })
+                .replace(/<dt>([\s\S]*?)<\/dt>/g, (_match, content) => {
+                // Same for dt tags
+                const cleaned = content.replace(/\s+/g, ' ').trim();
+                return `<dt>${cleaned}</dt>`;
+            });
+            const formatted = await prettier.format(preprocessed, {
+                parser: this.settings.formatterConfig.parser || 'html',
+                printWidth: 999999, // Never wrap lines
+                tabWidth: this.settings.formatterConfig.tabWidth || 2,
+                useTabs: this.settings.formatterConfig.useTabs || false,
+                htmlWhitespaceSensitivity: 'css', // Use CSS mode to handle whitespace better
+                bracketSameLine: true, // Keep closing bracket on same line to prevent broken tags
+                singleAttributePerLine: false,
+            });
+            // Remove trailing newline that prettier adds
+            let result = formatted.replace(/\n$/, '');
+            // Remove self-closing slashes from void elements if not present in original
+            // This maintains compatibility with existing MDX content
+            const voidElements = ['input', 'br', 'hr', 'img', 'meta', 'link'];
+            for (const elem of voidElements) {
+                const originalHasSelfClosing = new RegExp(`<${elem}[^>]*/>`, 'i').test(html);
+                if (!originalHasSelfClosing) {
+                    // Remove the self-closing slash that Prettier adds
+                    result = result.replace(new RegExp(`(<${elem}[^>]*?)\\s*/>`, 'gi'), '$1>');
+                }
+            }
+            // Special handling for dt/dd tags - trim content inside them
+            // This preserves the original formatting requirement for definition lists
+            result = result.replace(/<(dt|dd)>\s*(.*?)\s*<\/(dt|dd)>/g, '<$1>$2</$1>');
+            return result;
+        }
+        catch {
+            return html;
+        }
+    }
+    /**
+     * Extract HTML block from position in original content
+     */
+    extractHtmlBlock(content, startPos, endPos) {
+        const lines = content.split('\n');
+        const startLine = startPos.line - 1;
+        const endLine = endPos.line - 1;
+        const startCol = startPos.column - 1;
+        const endCol = endPos.column - 1;
+        if (startLine === endLine) {
+            // Single line
+            return lines[startLine].substring(startCol, endCol);
+        }
+        else {
+            // Multi-line
+            const extractedLines = [];
+            extractedLines.push(lines[startLine].substring(startCol));
+            for (let i = startLine + 1; i < endLine; i++) {
+                extractedLines.push(lines[i]);
+            }
+            extractedLines.push(lines[endLine].substring(0, endCol));
+            return extractedLines.join('\n');
+        }
+    }
+    /**
+     * Find matching closing tag for an opening tag
+     */
+    findMatchingClosingTag(content, startIndex, tagName) {
+        let depth = 1;
+        let index = startIndex;
+        const openPattern = new RegExp(`<${tagName}(?:\\s[^>]*)?>`, 'gi');
+        const closePattern = new RegExp(`<\\/${tagName}>`, 'gi');
+        while (depth > 0 && index < content.length) {
+            // Reset lastIndex for each search
+            openPattern.lastIndex = index;
+            closePattern.lastIndex = index;
+            const openMatch = openPattern.exec(content);
+            const closeMatch = closePattern.exec(content);
+            if (!closeMatch) {
+                // No closing tag found
+                return -1;
+            }
+            if (!openMatch || closeMatch.index < openMatch.index) {
+                // Found closing tag before next opening tag
+                depth--;
+                index = closeMatch.index + closeMatch[0].length;
+            }
+            else {
+                // Found opening tag before closing tag
+                depth++;
+                index = openMatch.index + openMatch[0].length;
+            }
+        }
+        return depth === 0 ? index : -1;
+    }
+    /**
+     * Format MDX content with HTML block formatting
+     */
+    async format(content) {
+        if (!this.settings.enabled) {
+            return content;
+        }
+        try {
+            // Find HTML blocks - handle nested tags properly
+            const blocks = [];
+            const processedRanges = [];
+            // First pass: find all opening tags
+            const openingTagPattern = /<(\w+)(?:\s[^>]*)?>(?!.*\/>)/g;
+            let match;
+            while ((match = openingTagPattern.exec(content)) !== null) {
+                const tagName = match[1];
+                if (this.isHtmlElement(tagName)) {
+                    const startIndex = match.index;
+                    const afterOpenTag = match.index + match[0].length;
+                    // Find the matching closing tag
+                    const endIndex = this.findMatchingClosingTag(content, afterOpenTag, tagName);
+                    if (endIndex !== -1) {
+                        // Check if this range overlaps with any processed range
+                        let overlaps = false;
+                        for (const range of processedRanges) {
+                            if ((startIndex >= range[0] && startIndex < range[1]) ||
+                                (endIndex > range[0] && endIndex <= range[1])) {
+                                overlaps = true;
+                                break;
+                            }
+                        }
+                        if (!overlaps) {
+                            blocks.push({
+                                start: startIndex,
+                                end: endIndex,
+                                content: content.substring(startIndex, endIndex),
+                                tagName: tagName,
+                            });
+                            processedRanges.push([startIndex, endIndex]);
+                        }
+                    }
+                }
+            }
+            // Also handle self-closing tags
+            const selfClosingPattern = /<(\w+)(?:\s[^>]*)?\/>/g;
+            while ((match = selfClosingPattern.exec(content)) !== null) {
+                const tagName = match[1];
+                if (this.isHtmlElement(tagName)) {
+                    const startIndex = match.index;
+                    const endIndex = match.index + match[0].length;
+                    // Check if this is within an already processed block
+                    let inBlock = false;
+                    for (const range of processedRanges) {
+                        if (startIndex >= range[0] && endIndex <= range[1]) {
+                            inBlock = true;
+                            break;
+                        }
+                    }
+                    if (!inBlock) {
+                        blocks.push({
+                            start: startIndex,
+                            end: endIndex,
+                            content: match[0],
+                            tagName: tagName,
+                        });
+                    }
+                }
+            }
+            // Sort blocks by position (reverse order to maintain positions)
+            blocks.sort((a, b) => b.start - a.start);
+            // Apply formatting to each HTML block
+            let result = content;
+            for (const block of blocks) {
+                // Always use Prettier for HTML formatting
+                const formatted = await this.formatWithPrettier(block.content);
+                // Replace the original HTML with formatted version
+                result = result.substring(0, block.start) + formatted + result.substring(block.end);
+            }
+            return result;
+        }
+        catch {
+            return content;
+        }
+    }
+    /**
+     * Replace HTML block in content with formatted version
+     */
+    replaceHtmlBlock(content, startPos, endPos, replacement) {
+        const lines = content.split('\n');
+        const startLine = startPos.line - 1;
+        const endLine = endPos.line - 1;
+        const startCol = startPos.column - 1;
+        const endCol = endPos.column - 1;
+        if (startLine === endLine) {
+            // Single line replacement
+            lines[startLine] =
+                lines[startLine].substring(0, startCol) + replacement + lines[startLine].substring(endCol);
+        }
+        else {
+            // Multi-line replacement
+            const replacementLines = replacement.split('\n');
+            // Create new line array
+            const newLines = [];
+            // Add lines before the block
+            for (let i = 0; i < startLine; i++) {
+                newLines.push(lines[i]);
+            }
+            // Add first line (partial) + first replacement line
+            if (replacementLines.length === 1) {
+                // Single line replacement for multi-line original
+                newLines.push(lines[startLine].substring(0, startCol) +
+                    replacementLines[0] +
+                    lines[endLine].substring(endCol));
+            }
+            else {
+                // Multi-line replacement
+                newLines.push(lines[startLine].substring(0, startCol) + replacementLines[0]);
+                // Add middle replacement lines
+                for (let i = 1; i < replacementLines.length - 1; i++) {
+                    newLines.push(replacementLines[i]);
+                }
+                // Add last replacement line + rest of last original line
+                newLines.push(replacementLines[replacementLines.length - 1] + lines[endLine].substring(endCol));
+            }
+            // Add lines after the block
+            for (let i = endLine + 1; i < lines.length; i++) {
+                newLines.push(lines[i]);
+            }
+            return newLines.join('\n');
+        }
+        return lines.join('\n');
+    }
+}