@writechoice/mint-cli 0.0.12 → 0.0.14

package/bin/cli.js

@@ -16,7 +16,9 @@ const program = new Command();
 
 program
   .name("writechoice")
-  .description("CLI tool for Mintlify documentation validation and utilities")
+  .description(
+    "@writechoice/mint-cli@" + packageJson.version + "\n\nCLI tool for Mintlify documentation validation and utilities",
+  )
   .version(packageJson.version, "-v, --version", "Output the current version");
 
 // Validate command
@@ -109,6 +111,30 @@ fix
     await fixParse(options);
   });
 
+// Fix codeblocks subcommand
+fix
+  .command("codeblocks")
+  .description("Fix code block flags (expandable, lines, wrap) in MDX files")
+  .option("-f, --file <path>", "Fix a single MDX file directly")
+  .option("-d, --dir <path>", "Fix MDX files in a specific directory")
+  .option("-t, --threshold <number>", "Line count threshold for expandable (default: 15)")
+  .option("--no-expandable", "Skip expandable threshold processing")
+  .option("--lines", "Add 'lines' to all code blocks that lack it")
+  .option("--remove-lines", "Remove 'lines' from all code blocks that have it")
+  .option("--wrap", "Add 'wrap' to all code blocks that lack it")
+  .option("--remove-wrap", "Remove 'wrap' from all code blocks that have it")
+  .option("--dry-run", "Preview changes without writing files")
+  .option("--quiet", "Suppress terminal output")
+  .action(async (options) => {
+    const { loadConfig, mergeCodeblocksConfig } = await import("../src/utils/config.js");
+    const { fixCodeblocks } = await import("../src/commands/fix/codeblocks.js");
+
+    const config = loadConfig();
+    const mergedOptions = mergeCodeblocksConfig(options, config);
+    mergedOptions.verbose = !mergedOptions.quiet;
+    await fixCodeblocks(mergedOptions);
+  });
+
 // Config command
 program
   .command("config")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writechoice/mint-cli",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "CLI tool for Mintlify documentation validation and utilities",
   "main": "src/index.js",
   "type": "module",

package/src/commands/fix/codeblocks.js

@@ -0,0 +1,252 @@
+/**
+ * Code Block Fix Tool
+ *
+ * Fixes code block flags in MDX documentation files:
+ * - expandable: adds when line count > threshold, removes when < threshold
+ * - lines:      adds to all code blocks (--lines) or removes from all (--remove-lines)
+ * - wrap:       adds to all code blocks (--wrap) or removes from all (--remove-wrap)
+ */
+
+import { existsSync, readdirSync, statSync, readFileSync, writeFileSync } from "fs";
+import { join, relative, resolve } from "path";
+import chalk from "chalk";
+
+const DEFAULT_THRESHOLD = 15;
+const EXCLUDED_DIRS = ["node_modules", ".git"];
+
+/**
+ * Finds MDX files to process
+ */
+function findMdxFiles(repoRoot, directory = null, file = null) {
+  if (file) {
+    const fullPath = resolve(repoRoot, file);
+    return existsSync(fullPath) ? [fullPath] : [];
+  }
+
+  const searchDirs = directory ? [resolve(repoRoot, directory)] : [repoRoot];
+  const mdxFiles = [];
+
+  function walkDirectory(dir) {
+    const dirName = dir.split("/").pop();
+    if (EXCLUDED_DIRS.includes(dirName)) return;
+
+    try {
+      const entries = readdirSync(dir);
+      for (const entry of entries) {
+        const fullPath = join(dir, entry);
+        const stat = statSync(fullPath);
+        if (stat.isDirectory()) {
+          walkDirectory(fullPath);
+        } else if (stat.isFile() && entry.endsWith(".mdx")) {
+          mdxFiles.push(fullPath);
+        }
+      }
+    } catch (error) {
+      console.error(`Error reading directory ${dir}: ${error.message}`);
+    }
+  }
+
+  for (const dir of searchDirs) {
+    if (existsSync(dir)) walkDirectory(dir);
+  }
+
+  return mdxFiles.sort();
+}
+
+/**
+ * Splits content into lines preserving original line endings.
+ */
+function splitLines(content) {
+  const lines = [];
+  let pos = 0;
+  while (pos < content.length) {
+    const nlPos = content.indexOf("\n", pos);
+    if (nlPos === -1) {
+      lines.push(content.slice(pos));
+      break;
+    }
+    lines.push(content.slice(pos, nlPos + 1));
+    pos = nlPos + 1;
+  }
+  return lines;
+}
+
+/**
+ * Processes the token list for a single code block's info string.
+ * Returns { newTokens, changes }.
+ */
+function processInfoTokens(tokens, lineCount, lineNum, options) {
+  const changes = [];
+  let newTokens = [...tokens];
+
+  const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+
+  // expandable: threshold-based (unless disabled via --no-expandable)
+  if (options.expandable !== false) {
+    const hasExpandable = newTokens.includes("expandable");
+    if (hasExpandable && lineCount < threshold) {
+      newTokens = newTokens.filter((t) => t !== "expandable");
+      changes.push(`line ${lineNum}: removed 'expandable' (${lineCount} lines < ${threshold})`);
+    } else if (!hasExpandable && lineCount > threshold) {
+      newTokens.push("expandable");
+      changes.push(`line ${lineNum}: added 'expandable' (${lineCount} lines > ${threshold})`);
+    }
+  }
+
+  // lines: add or remove
+  const hasLines = newTokens.includes("lines");
+  if (options.lines && !hasLines) {
+    newTokens.push("lines");
+    changes.push(`line ${lineNum}: added 'lines'`);
+  } else if (options.removeLines && hasLines) {
+    newTokens = newTokens.filter((t) => t !== "lines");
+    changes.push(`line ${lineNum}: removed 'lines'`);
+  }
+
+  // wrap: add or remove
+  const hasWrap = newTokens.includes("wrap");
+  if (options.wrap && !hasWrap) {
+    newTokens.push("wrap");
+    changes.push(`line ${lineNum}: added 'wrap'`);
+  } else if (options.removeWrap && hasWrap) {
+    newTokens = newTokens.filter((t) => t !== "wrap");
+    changes.push(`line ${lineNum}: removed 'wrap'`);
+  }
+
+  return { newTokens, changes };
+}
+
+/**
+ * Scans MDX content for fenced code blocks and applies flag fixes.
+ * Returns { newContent, changes }.
+ */
+function processContent(content, options) {
+  const lines = splitLines(content);
+  const result = [];
+  const changes = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+    // Strip trailing newline for matching, preserving it for output
+    const stripped = line.replace(/\r?\n$/, "");
+
+    // Detect a fenced code block opener: optional indent + 3+ backticks + info string
+    const openMatch = stripped.match(/^([ \t]*)(`{3,})(.*)$/);
+
+    if (openMatch) {
+      const indent = openMatch[1];
+      const fence = openMatch[2];
+      const info = openMatch[3];
+      const fenceLen = fence.length;
+
+      // Find the matching closing fence
+      let j = i + 1;
+      while (j < lines.length) {
+        const closeStripped = lines[j].replace(/\r?\n$/, "");
+        const closeMatch = closeStripped.match(/^[ \t]*(`{3,})[ \t]*$/);
+        if (closeMatch && closeMatch[1].length >= fenceLen) {
+          break;
+        }
+        j++;
+      }
+
+      const bodyLines = lines.slice(i + 1, j);
+      const lineCount = bodyLines.length;
+
+      // Parse info string tokens
+      const infoStripped = info.trim();
+      const tokens = infoStripped ? infoStripped.split(/\s+/) : [];
+
+      const { newTokens, changes: blockChanges } = processInfoTokens(tokens, lineCount, i + 1, options);
+      changes.push(...blockChanges);
+
+      // Reconstruct the opening fence line with original line ending
+      const lineEnding = line.slice(stripped.length);
+      const newInfo = newTokens.join(" ");
+      result.push(`${indent}${fence}${newInfo}${lineEnding}`);
+      result.push(...bodyLines);
+
+      if (j < lines.length) {
+        result.push(lines[j]); // closing fence
+        i = j + 1;
+      } else {
+        // Unterminated block — leave as-is
+        i = j;
+      }
+    } else {
+      result.push(line);
+      i++;
+    }
+  }
+
+  return { newContent: result.join(""), changes };
+}
+
+/**
+ * Main exported function for the fix codeblocks command.
+ */
+export async function fixCodeblocks(options) {
+  const repoRoot = process.cwd();
+
+  if (!options.quiet) {
+    console.log(chalk.bold("\n🔧 Code Block Fixer\n"));
+  }
+
+  const files = findMdxFiles(repoRoot, options.dir, options.file);
+
+  if (files.length === 0) {
+    console.error(chalk.red("✗ No MDX files found."));
+    process.exit(1);
+  }
+
+  if (!options.quiet) {
+    console.log(`Found ${files.length} MDX file(s) to process\n`);
+    if (options.dryRun) {
+      console.log(chalk.yellow("Dry run — no files will be written\n"));
+    }
+  }
+
+  const results = {};
+  let totalChanges = 0;
+
+  for (const filePath of files) {
+    const content = readFileSync(filePath, "utf-8");
+    const { newContent, changes } = processContent(content, options);
+
+    if (changes.length > 0) {
+      const relPath = relative(repoRoot, filePath);
+      results[relPath] = changes;
+      totalChanges += changes.length;
+
+      if (options.verbose) {
+        console.log(`${chalk.cyan(relPath)}: ${changes.length} change(s)`);
+        for (const change of changes) {
+          console.log(`  ${change}`);
+        }
+      }
+
+      if (!options.dryRun) {
+        writeFileSync(filePath, newContent, "utf-8");
+      }
+    }
+  }
+
+  // Summary
+  if (!options.quiet) {
+    const fileCount = Object.keys(results).length;
+
+    if (fileCount > 0) {
+      const verb = options.dryRun ? "Would make" : "Made";
+      console.log(chalk.green(`\n✓ ${verb} ${totalChanges} change(s) in ${fileCount} file(s)`));
+
+      if (!options.verbose) {
+        for (const [filePath, changes] of Object.entries(results)) {
+          console.log(`  ${chalk.cyan(filePath)}: ${changes.length} change(s)`);
+        }
+      }
+    } else {
+      console.log(chalk.yellow("⚠️  No changes needed."));
+    }
+  }
+}

package/src/utils/config.js

@@ -97,6 +97,50 @@ export function mergeParseConfig(options, config) {
   };
 }
 
+/**
+ * Merges config file with CLI options for the codeblocks command
+ * CLI options take precedence over config file
+ *
+ * @param {Object} options - CLI options
+ * @param {Object|null} config - Loaded config object
+ * @returns {Object} Merged options
+ */
+export function mergeCodeblocksConfig(options, config) {
+  const cbConfig = config?.codeblocks || {};
+
+  // Resolve lines/wrap from config: "add" | true → add, "remove" | false → remove
+  const configLines = cbConfig.lines;
+  const configWrap = cbConfig.wrap;
+
+  const addLinesFromConfig = configLines === "add" || configLines === true;
+  const removeLinesFromConfig = configLines === "remove" || configLines === false;
+  const addWrapFromConfig = configWrap === "add" || configWrap === true;
+  const removeWrapFromConfig = configWrap === "remove" || configWrap === false;
+
+  const threshold = options.threshold != null
+    ? parseInt(options.threshold, 10)
+    : (cbConfig.threshold ?? 15);
+
+  // expandable: Commander sets options.expandable=false when --no-expandable is passed
+  const expandable = options.expandable !== false
+    ? (cbConfig.expandable !== false)
+    : false;
+
+  return {
+    file: options.file || cbConfig.file || null,
+    dir: options.dir || cbConfig.dir || null,
+    dryRun: options.dryRun !== undefined ? options.dryRun : (cbConfig["dry-run"] ?? false),
+    quiet: options.quiet !== undefined ? options.quiet : (cbConfig.quiet ?? false),
+    threshold,
+    expandable,
+    // CLI flags take precedence over config
+    lines: options.lines || addLinesFromConfig,
+    removeLines: options.removeLines || removeLinesFromConfig,
+    wrap: options.wrap || addWrapFromConfig,
+    removeWrap: options.removeWrap || removeWrapFromConfig,
+  };
+}
+
 /**
  * Validates that required fields are present
  * @param {string|undefined} baseUrl - Base URL