@takazudo/mdx-formatter 1.0.4 → 1.2.0

package/README.md

@@ -58,6 +58,37 @@ const formatted = await format('# Hello\nWorld');
 console.log(formatted); // '# Hello\n\nWorld'
 ```
 
+### List Normalize
+
+Five rules clean up AI-authored list-item content. They are exposed as flat
+top-level kebab-case keys (not nested objects):
+
+| Key                                   | Default       | Purpose                                                                           |
+| ------------------------------------- | ------------- | --------------------------------------------------------------------------------- |
+| `tighten-list-continuations`          | `"heuristic"` | Collapse blank gaps inside list items whose children are continuation paragraphs. |
+| `tighten-list-item-spacing`           | `"heuristic"` | Collapse single blank gaps between adjacent sibling list items when safe.         |
+| `recover-escaped-code-in-lists`       | `"safe"`      | Re-indent fenced code blocks that escaped to column 0 between list items.         |
+| `recover-escaped-tables-in-lists`     | `"safe"`      | Re-indent GFM tables that escaped to column 0 between list items.                 |
+| `recover-escaped-paragraphs-in-lists` | `"off"`       | Re-indent continuation paragraphs that escaped to column 0 (opt-in).              |
+
+Each accepts `"off"` to disable, its default middle value (`"heuristic"` or
+`"safe"`) for the conservative trigger, or `"aggressive"` to drop the
+structural safeguards. See the
+[List Normalize options docs](https://takazudomodular.com/pj/mdx-formatter/docs/options/#list-normalize)
+for per-rule before/after examples.
+
+### Preview with `--dry-run`
+
+```bash
+mdx-formatter --dry-run "**/*.{md,mdx}"
+```
+
+Writes every rule-level change to **stderr** without touching the files.
+Useful for auditing what the list-normalize rules (or any other rule) would
+change before committing. Exits 0 whether or not there was anything to
+report; conflicts with `--write` / `--check`. The same report is available
+programmatically via the `dryRunReport()` API.
+
 ### Browser (WASM)
 
 ```bash

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { readFileSync } from 'fs';
+import { promises as fs } from 'fs';
 import { program } from 'commander';
 import { glob } from 'glob';
 import chalk from 'chalk';
-import { formatFile, checkFile } from './index.js';
+import { formatFile, checkFile, dryRunReport } from './index.js';
 import { loadFullConfig } from './load-config.js';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
 program
@@ -13,10 +14,23 @@ program
     .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('--dry-run', [
+    'Preview every change on stderr without touching files or stdout.',
+    'Each entry is: `<path>:<start>-<end> [<rule>]`, followed by indented',
+    '`- <before>` / `+ <after>` lines (≤3 each, truncated with `…`).',
+    'Exits 0 whether or not there was anything to report.',
+].join(' '))
     .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 {
+        // commander does not natively encode "conflicts with" rules; enforce
+        // the same constraint the Rust CLI uses so the two stay in lockstep.
+        const mutuallyExclusive = [options.write, options.check, options.dryRun].filter(Boolean).length;
+        if (mutuallyExclusive > 1) {
+            console.error(chalk.red('Error:'), '--dry-run cannot be combined with --write or --check');
+            process.exit(1);
+        }
         await main(patterns, options);
     }
     catch (error) {
@@ -47,7 +61,16 @@ async function main(patterns, options) {
     // Remove duplicates
     const uniqueFiles = [...new Set(files)];
     if (uniqueFiles.length === 0) {
-        console.log(chalk.yellow('No files found matching the patterns.'));
+        if (options.dryRun) {
+            console.error(chalk.yellow('No files found matching the patterns.'));
+        }
+        else {
+            console.log(chalk.yellow('No files found matching the patterns.'));
+        }
+        return;
+    }
+    if (options.dryRun) {
+        await runDryRun(uniqueFiles, formatOptions);
         return;
     }
     console.log(chalk.blue(`Processing ${uniqueFiles.length} file(s)...`));
@@ -126,3 +149,70 @@ async function main(patterns, options) {
         process.exit(1);
     }
 }
+/**
+ * `--dry-run` handler. Mirrors the Rust CLI: writes every report entry +
+ * summary to stderr, never touches stdout or disk, and always exits 0 — even
+ * when an individual file fails to parse. The report format is identical to
+ * the Rust CLI's so tooling can consume either.
+ */
+async function runDryRun(files, formatOptions) {
+    let totalEntries = 0;
+    let filesWithChanges = 0;
+    for (const file of files) {
+        let content;
+        try {
+            content = await fs.readFile(file, 'utf-8');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`${file}: read error: ${message}\n`);
+            continue;
+        }
+        let entries;
+        try {
+            entries = dryRunReport(content, formatOptions);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`${file}: parse error: ${message}\n`);
+            continue;
+        }
+        if (entries.length === 0)
+            continue;
+        filesWithChanges += 1;
+        for (const entry of entries) {
+            totalEntries += 1;
+            writeReportEntry(file, entry);
+        }
+    }
+    const entryWord = totalEntries === 1 ? 'entry' : 'entries';
+    const fileWord = filesWithChanges === 1 ? 'file' : 'files';
+    process.stderr.write(`\n${totalEntries} ${entryWord} across ${filesWithChanges} ${fileWord} ` +
+        `(dry-run; no files were modified).\n`);
+}
+/** Render one report entry to stderr in the format shared with the Rust CLI. */
+function writeReportEntry(path, entry) {
+    const start1 = entry.startLine + 1;
+    const end1 = entry.endLine + 1;
+    process.stderr.write(`${path}:${start1}-${end1} [${entry.rule}]\n`);
+    writeSnippet(entry.before, '-');
+    writeSnippet(entry.after, '+');
+}
+/**
+ * Write up to 3 lines of a before/after snippet, truncating the rest with
+ * `…`. Empty snippets render as `(no lines)` so a delete-only change is
+ * still visible to the user.
+ */
+function writeSnippet(snippet, prefix) {
+    if (snippet.length === 0) {
+        process.stderr.write(`  ${prefix} (no lines)\n`);
+        return;
+    }
+    const MAX = 3;
+    for (const line of snippet.slice(0, MAX)) {
+        process.stderr.write(`  ${prefix} ${line}\n`);
+    }
+    if (snippet.length > MAX) {
+        process.stderr.write(`  ${prefix} …\n`);
+    }
+}

package/dist/index.d.ts

@@ -3,8 +3,10 @@
  * Uses the Rust napi formatter as the sole formatting engine.
  */
 import { detectMdx } from './detect-mdx.js';
+import type { DryRunReportEntry } from './rust-formatter.js';
 import type { FormatOptions } from './types.js';
 export { detectMdx };
+export type { DryRunReportEntry };
 /**
  * Format markdown/MDX content using the Rust formatter.
  */
@@ -23,11 +25,21 @@ export declare function formatFile(filePath: string, options?: FormatOptions): P
  * Check if a file needs formatting
  */
 export declare function checkFile(filePath: string, options?: FormatOptions): Promise<boolean>;
+/**
+ * Compute the dry-run report for `content` without modifying it.
+ *
+ * Entries describe every change the formatter's rules would make, with
+ * 0-indexed line ranges and `before`/`after` snippets. Used by the CLI
+ * `--dry-run` flag and exposed here so library consumers can audit a corpus
+ * programmatically.
+ */
+export declare function dryRunReport(content: string, options?: FormatOptions): DryRunReportEntry[];
 declare const _default: {
     format: typeof format;
     formatSync: typeof formatSync;
     formatFile: typeof formatFile;
     checkFile: typeof checkFile;
+    dryRunReport: typeof dryRunReport;
     detectMdx: typeof detectMdx;
 };
 export default _default;

package/dist/index.js

@@ -5,7 +5,7 @@
 import { promises as fs } from 'fs';
 import { loadConfig } from './load-config.js';
 import { detectMdx } from './detect-mdx.js';
-import { nativeFormat } from './rust-formatter.js';
+import { nativeFormat, nativeDryRunReport } from './rust-formatter.js';
 import { formatterSettings } from './settings.js';
 export { detectMdx };
 /**
@@ -44,10 +44,23 @@ export async function checkFile(filePath, options = {}) {
     const formatted = await format(content, options);
     return content !== formatted;
 }
+/**
+ * Compute the dry-run report for `content` without modifying it.
+ *
+ * Entries describe every change the formatter's rules would make, with
+ * 0-indexed line ranges and `before`/`after` snippets. Used by the CLI
+ * `--dry-run` flag and exposed here so library consumers can audit a corpus
+ * programmatically.
+ */
+export function dryRunReport(content, options = {}) {
+    const settings = loadConfig(options);
+    return nativeDryRunReport(content, JSON.stringify(settings));
+}
 export default {
     format,
     formatSync,
     formatFile,
     checkFile,
+    dryRunReport,
     detectMdx,
 };

package/dist/rust-formatter.d.ts

@@ -4,11 +4,30 @@
  * This is the sole formatting engine — no TypeScript fallback.
  */
 type NativeFormat = (content: string, settingsJson: string) => string;
+/**
+ * One dry-run report entry, as produced by the Rust `ReportSink` and
+ * serialized through the napi `dry_run_report` / `dryRunReport` export.
+ * Line numbers are 0-indexed; the TS CLI converts them to 1-based when
+ * printing.
+ */
+export interface DryRunReportEntry {
+    rule: string;
+    startLine: number;
+    endLine: number;
+    before: string[];
+    after: string[];
+}
 /**
  * The native format function. Loaded once at module init.
  * Throws if the native module is not available.
  */
 export declare const nativeFormat: NativeFormat;
+/**
+ * Compute the dry-run report for `content`. Returns a parsed array of
+ * `DryRunReportEntry`. Throws if the binary is older than this TS build and
+ * does not yet export `dryRunReport` (see `build:rust`).
+ */
+export declare function nativeDryRunReport(content: string, settingsJson: string): DryRunReportEntry[];
 /**
  * Check if the Rust formatter is available
  */

package/dist/rust-formatter.js

@@ -28,7 +28,7 @@ function loadNativeModule() {
     // the code from the current checkout instead of the last published binary.
     try {
         const native = require('../crates/mdx-formatter-napi/mdx-formatter-napi.node');
-        return native.format;
+        return native;
     }
     catch {
         // Local build not present, fall back to platform-specific npm package.
@@ -37,7 +37,7 @@ function loadNativeModule() {
     if (packageName) {
         try {
             const native = require(packageName);
-            return native.format;
+            return native;
         }
         catch {
             // Platform package not installed, surface a build hint below.
@@ -45,11 +45,25 @@ function loadNativeModule() {
     }
     throw new Error('Rust native module not available. Build it with: pnpm build:rust');
 }
+const nativeModule = loadNativeModule();
 /**
  * The native format function. Loaded once at module init.
  * Throws if the native module is not available.
  */
-export const nativeFormat = loadNativeModule();
+export const nativeFormat = nativeModule.format;
+/**
+ * Compute the dry-run report for `content`. Returns a parsed array of
+ * `DryRunReportEntry`. Throws if the binary is older than this TS build and
+ * does not yet export `dryRunReport` (see `build:rust`).
+ */
+export function nativeDryRunReport(content, settingsJson) {
+    if (typeof nativeModule.dryRunReport !== 'function') {
+        throw new Error('The loaded Rust native module does not export `dryRunReport`. ' +
+            'Rebuild it with: pnpm build:rust');
+    }
+    const json = nativeModule.dryRunReport(content, settingsJson);
+    return JSON.parse(json);
+}
 /**
  * Check if the Rust formatter is available
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/mdx-formatter",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "description": "AST-based markdown and MDX formatter with Japanese text support",
   "type": "module",
   "main": "dist/index.js",