fix-md-tables 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JoobyPM
+
+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,168 @@
+# fix-md-tables
+
+Fix markdown table alignment for emoji using ideographic spaces (U+3000).
+
+## The Problem
+
+Emoji display as 2 columns in terminals but count as 1 character. When Prettier formats markdown tables, it aligns by character count, so headers (no emoji) appear shorter than data rows (with emoji):
+
+```markdown
+| Status | Description    | Comments |
+| ------ | -------------- | -------- |
+| ✅     | ✅ Complete    | ❌       |
+| 🚧     | 🚧 In Progress | ⚠️       |
+```
+
+Renders misaligned:
+
+```
+| Status | Description    | Comments |
+| ------ | -------------- | -------- |
+| ✅     | ✅ Complete    | ❌       |  ← emoji takes 2 cols but counts as 1 char
+| 🚧     | 🚧 In Progress | ⚠️       |
+```
+
+## The Solution
+
+Add ideographic spaces (U+3000) to cells with fewer emoji. Ideographic spaces also display as 2 columns, compensating for the width difference:
+
+```markdown
+| Status　 | Description　  | Comments　 |
+| -------- | -------------- | ---------- |
+| ✅       | ✅ Complete    | ❌         |
+| 🚧       | 🚧 In Progress | ⚠️         |
+```
+
+Now renders aligned:
+
+```
+| Status　 | Description　    | Comments　 |
+| ------　 | --------------　 | --------　 |
+| ✅       | ✅ Complete      | ❌         |
+| 🚧       | 🚧 In Progress   | ⚠️         |
+```
+
+## Installation
+
+```bash
+# One-off via npx (no install)
+npx fix-md-tables
+
+# Or with bun
+bunx fix-md-tables
+
+# Install globally
+npm install -g fix-md-tables
+fix-md-tables
+
+# As dev dependency in project
+npm install -D fix-md-tables
+pnpm add -D fix-md-tables
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Process default files (*.md, *.mdx in root + docs/)
+fix-md-tables
+
+# Process specific files
+fix-md-tables README.md docs/guide.mdx
+
+# Via npx
+npx fix-md-tables
+```
+
+### Programmatic
+
+```javascript
+import { fixTableAlignment } from "fix-md-tables";
+
+const markdown = `| Status | Description    | Comments |
+                  | ------ | -------------- | -------- |
+                  | ✅     | ✅ Complete    | ❌       |
+                  | 🚧     | 🚧 In Progress | ⚠️       |`;
+
+const fixed = fixTableAlignment(markdown);
+console.log(fixed);
+```
+
+### With Prettier (recommended)
+
+Run after Prettier to fix table alignment:
+
+```bash
+prettier --write "*.md" "docs/**/*.md" && npx fix-md-tables
+```
+
+Or in your `package.json`:
+
+```json
+{
+  "scripts": {
+    "format": "prettier --write . && fix-md-tables"
+  }
+}
+```
+
+Or in a Makefile:
+
+```makefile
+docs-format:
+	@prettier --write "*.md" "docs/**/*.md"
+	@npx fix-md-tables
+```
+
+## How It Works
+
+1. Finds all markdown tables in content
+2. For each table, calculates max emoji count per column (from data rows only)
+3. Adds ideographic spaces to compensate:
+   - Header cells: adds spaces after text
+   - Separator cells: removes dashes, adds ideographic spaces
+   - Data cells with fewer emoji: adds compensating spaces
+
+## API
+
+### `fixTableAlignment(content: string): string`
+
+Main function to fix table alignment in markdown content.
+
+### `countEmoji(str: string): number`
+
+Count emoji characters in a string.
+
+### `stripIdeographicSpaces(str: string): string`
+
+Remove all ideographic spaces from a string.
+
+### `processTable(tableRows: string[]): string[]`
+
+Process a complete table, applying emoji compensation to all rows.
+
+### `run(args?: string[]): number`
+
+CLI runner. Returns count of fixed files.
+
+## Supported Emoji Ranges
+
+- U+1F300-U+1F9FF (Miscellaneous Symbols and Pictographs, Emoticons, etc.)
+- U+2600-U+26FF (Miscellaneous Symbols)
+- U+2700-U+27BF (Dingbats)
+- U+231A-U+23FA (Miscellaneous Technical)
+- U+2B50-U+2B55 (Miscellaneous Symbols and Arrows)
+
+## File Types
+
+Supports `.md` and `.mdx` files.
+
+## Requirements
+
+- Node.js >= 18
+- Also works with Bun
+
+## License
+
+MIT

package/bin/fix-md-tables.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for fix-md-tables
+ *
+ * Usage: fix-md-tables [file.md|file.mdx...]
+ *        npx fix-md-tables
+ *        bunx fix-md-tables
+ */
+
+import { run } from "../lib/index.mjs";
+
+run(process.argv.slice(2));
+

package/lib/index.mjs

@@ -0,0 +1,300 @@
+/**
+ * Fix markdown/MDX table alignment for emoji by adding ideographic spaces (U+3000).
+ *
+ * Problem: Emoji display as 2 columns but count as 1 char. Prettier aligns by
+ * char count, so headers (no emoji) appear shorter than data rows (with emoji).
+ *
+ * Solution: Add ideographic spaces (U+3000, also 2 cols wide) to cells with
+ * fewer emoji to compensate. 1 ideographic space = 1 emoji worth of width.
+ *
+ * Compatible with Node.js and Bun. Supports both .md and .mdx files.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+// === Constants ===
+
+export const IDEOGRAPHIC_SPACE = "\u3000"; // Displays as 2 columns, like emoji
+export const EMOJI_REGEX = /[\u{1F300}-\u{1F9FF}]|[\u{2600}-\u{26FF}]|[\u{2700}-\u{27BF}]|[\u{231A}-\u{23FA}]|[\u{2B50}-\u{2B55}]/gu;
+export const SEPARATOR_REGEX = /^(\s*)(:*)(-+)(:*)(\s*)$/;
+export const TABLE_SEPARATOR_LINE_REGEX = /^\s*\|[\s:|\-\u3000]+\|\s*$/;
+export const MARKDOWN_EXTENSIONS = [".md", ".mdx"];
+
+// === Pure Helper Functions ===
+
+/** Count emoji characters in a string */
+export function countEmoji(str) {
+  return (str.match(EMOJI_REGEX) || []).length;
+}
+
+/** Remove all ideographic spaces from a string */
+export function stripIdeographicSpaces(str) {
+  return str.replaceAll("\u3000", "");
+}
+
+/** Check if a line is a markdown table separator */
+export function isTableSeparatorLine(line) {
+  return TABLE_SEPARATOR_LINE_REGEX.test(line);
+}
+
+/** Check if a line is a table row (starts and ends with |) */
+export function isTableRow(line) {
+  const trimmed = line.trim();
+  return trimmed.startsWith("|") && trimmed.endsWith("|");
+}
+
+/** Parse a table row into cells (preserving internal spacing) */
+export function parseTableRow(row) {
+  const trimmed = row.trim();
+  const inner = trimmed.slice(1, -1); // Remove outer |
+  return inner.split("|");
+}
+
+/** Calculate max emoji count per column from data rows */
+export function calculateMaxEmojiPerColumn(parsedRows, numCols) {
+  const maxEmojiPerCol = new Array(numCols).fill(0);
+
+  // Skip header (row 0) and separator (row 1), only look at data rows
+  for (let rowIdx = 2; rowIdx < parsedRows.length; rowIdx++) {
+    const row = parsedRows[rowIdx];
+    for (let col = 0; col < row.length; col++) {
+      const emojiCount = countEmoji(row[col] || "");
+      maxEmojiPerCol[col] = Math.max(maxEmojiPerCol[col], emojiCount);
+    }
+  }
+
+  return maxEmojiPerCol;
+}
+
+/** Compensate a separator cell by removing dashes and adding ideographic spaces */
+export function compensateSeparatorCell(cell, compensation) {
+  const match = cell.match(SEPARATOR_REGEX);
+  if (!match) {
+    return cell;
+  }
+
+  const [, leadingSpace, leftColon, dashes, rightColon, trailingSpace] = match;
+  // Remove 2 dashes per ideographic space (both are 2 cols visually)
+  const dashesToRemove = compensation * 2;
+  const newDashes = dashes.length > dashesToRemove ? dashes.slice(0, -dashesToRemove) : dashes;
+
+  return leadingSpace + leftColon + newDashes + IDEOGRAPHIC_SPACE.repeat(compensation) + rightColon + trailingSpace;
+}
+
+/** Split cell into [leadingSpace, content, trailingSpace] without regex (ReDoS-safe) */
+export function splitCellContent(cell) {
+  let leadingEnd = 0;
+  while (leadingEnd < cell.length && /\s/.test(cell[leadingEnd])) {
+    leadingEnd++;
+  }
+
+  let trailingStart = cell.length;
+  while (trailingStart > leadingEnd && /\s/.test(cell[trailingStart - 1])) {
+    trailingStart--;
+  }
+
+  return [cell.slice(0, leadingEnd), cell.slice(leadingEnd, trailingStart), cell.slice(trailingStart)];
+}
+
+/** Compensate a regular cell by adding ideographic spaces before trailing whitespace */
+export function compensateRegularCell(cell, compensation) {
+  const [leadingSpace, content, trailingSpace] = splitCellContent(cell);
+  return leadingSpace + content + IDEOGRAPHIC_SPACE.repeat(compensation) + trailingSpace;
+}
+
+/** Process a single cell, applying emoji compensation */
+export function processCell(cell, col, isSeparatorRow, maxEmojiPerCol) {
+  const maxEmoji = maxEmojiPerCol[col] || 0;
+  const cellEmoji = countEmoji(cell);
+  const compensation = maxEmoji - cellEmoji;
+
+  if (compensation <= 0) {
+    return cell;
+  }
+
+  return isSeparatorRow ? compensateSeparatorCell(cell, compensation) : compensateRegularCell(cell, compensation);
+}
+
+/** Build a table row string from cells */
+export function buildTableRow(cells) {
+  return "|" + cells.join("|") + "|";
+}
+
+/** Process a complete table, applying emoji compensation to all rows */
+export function processTable(tableRows) {
+  // Strip existing ideographic spaces to start fresh
+  const cleanedRows = tableRows.map(stripIdeographicSpaces);
+  const parsedRows = cleanedRows.map(parseTableRow);
+
+  // Check if table has any emoji
+  const hasEmoji = cleanedRows.some((row) => countEmoji(row) > 0);
+  if (!hasEmoji || parsedRows.length < 2) {
+    return cleanedRows;
+  }
+
+  const numCols = Math.max(...parsedRows.map((r) => r.length));
+  const maxEmojiPerCol = calculateMaxEmojiPerColumn(parsedRows, numCols);
+
+  // Rebuild all rows with compensation
+  return parsedRows.map((row, rowIdx) => {
+    const isSeparatorRow = rowIdx === 1;
+    const processedCells = row.map((cell, col) => processCell(cell, col, isSeparatorRow, maxEmojiPerCol));
+    return buildTableRow(processedCells);
+  });
+}
+
+/** Check if a line starts a fenced code block */
+function isCodeFenceStart(line) {
+  const trimmed = line.trim();
+  return trimmed.startsWith("```") || trimmed.startsWith("~~~");
+}
+
+/** Check if a line ends a fenced code block */
+function isCodeFenceEnd(line, fence) {
+  const trimmed = line.trim();
+  return trimmed === fence || trimmed.startsWith(fence);
+}
+
+/** Main function to fix table alignment in markdown content */
+export function fixTableAlignment(content) {
+  const lines = content.split("\n");
+  const result = [];
+  let i = 0;
+  let inCodeBlock = false;
+  let codeFence = "";
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    // Track fenced code blocks to skip tables inside them
+    if (!inCodeBlock && isCodeFenceStart(line)) {
+      inCodeBlock = true;
+      codeFence = line.trim().match(/^(`{3,}|~{3,})/)[1];
+      result.push(line);
+      i++;
+      continue;
+    }
+
+    if (inCodeBlock) {
+      result.push(line);
+      if (isCodeFenceEnd(line, codeFence)) {
+        inCodeBlock = false;
+        codeFence = "";
+      }
+      i++;
+      continue;
+    }
+
+    // Detect table start: line with | followed by separator line
+    if (line.includes("|") && i + 1 < lines.length && isTableSeparatorLine(lines[i + 1])) {
+      const tableRows = [];
+
+      // Collect all table rows
+      while (i < lines.length && isTableRow(lines[i])) {
+        tableRows.push(lines[i]);
+        i++;
+      }
+
+      result.push(...processTable(tableRows));
+    } else {
+      result.push(line);
+      i++;
+    }
+  }
+
+  return result.join("\n");
+}
+
+// === File System Functions ===
+
+/** Check if a filename has a markdown extension */
+export function isMarkdownFile(filename) {
+  return MARKDOWN_EXTENSIONS.some((ext) => filename.endsWith(ext));
+}
+
+/** Recursively find all markdown/MDX files in a directory */
+export function findMarkdownFiles(dir, files = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return files; // Directory not readable, skip silently
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+      findMarkdownFiles(fullPath, files);
+    } else if (entry.isFile() && isMarkdownFile(entry.name)) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/** Get default files to process (root .md/.mdx files + docs directory) */
+export function getDefaultFiles(cwd) {
+  const files = [];
+
+  // Root markdown/MDX files
+  let rootEntries;
+  try {
+    rootEntries = fs.readdirSync(cwd, { withFileTypes: true });
+  } catch {
+    return files; // Can't read cwd, return empty
+  }
+
+  for (const entry of rootEntries) {
+    if (entry.isFile() && isMarkdownFile(entry.name)) {
+      files.push(path.join(cwd, entry.name));
+    }
+  }
+
+  // Docs directory
+  const docsDir = path.join(cwd, "docs");
+  if (fs.existsSync(docsDir)) {
+    findMarkdownFiles(docsDir, files);
+  }
+
+  return files;
+}
+
+/** Process a single file, applying table alignment fixes */
+export function processFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf8");
+    const fixed = fixTableAlignment(content);
+
+    if (content !== fixed) {
+      fs.writeFileSync(filePath, fixed, "utf8");
+      console.log(`  ✓ Fixed: ${filePath}`);
+      return true;
+    }
+    return false;
+  } catch (err) {
+    console.error(`  ✗ Error processing ${filePath}: ${err.message}`);
+    return false;
+  }
+}
+
+/** Main CLI runner */
+export function run(args = []) {
+  const files = args.length > 0 ? args : getDefaultFiles(process.cwd());
+
+  console.log(`  Processing ${files.length} markdown/MDX file(s)...`);
+
+  let fixedCount = 0;
+  for (const file of files) {
+    if (processFile(file)) {
+      fixedCount++;
+    }
+  }
+
+  if (fixedCount > 0) {
+    console.log(`  Fixed ${fixedCount} file(s) with ideographic space compensation.`);
+  }
+
+  return fixedCount;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "fix-md-tables",
+  "version": "1.0.0",
+  "description": "Fix markdown table alignment for emoji using ideographic spaces",
+  "type": "module",
+  "bin": {
+    "fix-md-tables": "./bin/fix-md-tables.mjs"
+  },
+  "main": "./lib/index.mjs",
+  "exports": {
+    ".": "./lib/index.mjs"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "scripts": {
+    "check": "pnpm run format && pnpm run lint && pnpm run test",
+    "format": "prettier --write . && node bin/fix-md-tables.mjs",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "markdown",
+    "table",
+    "emoji",
+    "alignment",
+    "prettier",
+    "formatter"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourname/fix-md-tables"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "globals": "^16.5.0",
+    "prettier": "^3.4.2",
+    "vitest": "^4.0.16"
+  },
+  "packageManager": "pnpm@9.15.4"
+}