@writechoice/mint-cli 0.0.7 → 0.0.9

package/src/commands/validate/mdx.js

@@ -0,0 +1,213 @@
+/**
+ * MDX File Validation Tool
+ *
+ * Validates MDX files for parsing errors using the official @mdx-js/mdx compiler.
+ * Catches syntax errors, invalid JSX, mismatched tags, and other MDX parsing issues.
+ */
+
+import { existsSync, readdirSync, statSync, readFileSync } from "fs";
+import { join, relative, resolve } from "path";
+import { compile } from "@mdx-js/mdx";
+import chalk from "chalk";
+import { writeBothFormats, generateMdxParseMarkdown } from "../../utils/reports.js";
+
+// Configuration
+const EXCLUDED_DIRS = ["snippets", "node_modules", ".git"];
+const MDX_DIRS = ["."];
+
+// Data Structures
+class ValidationResult {
+  constructor(filePath, status, error = null) {
+    this.filePath = filePath;
+    this.status = status; // "valid" or "error"
+    this.error = error ? {
+      message: error.message,
+      line: error.line || null,
+      column: error.column || null,
+      position: error.position || null,
+      reason: error.reason || null,
+    } : null;
+  }
+}
+
+// Utility Functions
+
+function findMdxFiles(repoRoot, directory = null, file = null) {
+  if (file) {
+    const fullPath = resolve(repoRoot, file);
+    return existsSync(fullPath) ? [fullPath] : [];
+  }
+
+  const searchDirs = directory ? [resolve(repoRoot, directory)] : MDX_DIRS.map((d) => join(repoRoot, d));
+
+  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();
+}
+
+async function validateMdxFile(filePath, verbose = false) {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+
+    if (verbose) {
+      console.log(`  Validating: ${filePath}`);
+    }
+
+    // Attempt to compile the MDX file
+    await compile(content, {
+      development: false,
+    });
+
+    return new ValidationResult(filePath, "valid");
+  } catch (error) {
+    if (verbose) {
+      console.log(chalk.red(`  ✗ Error in: ${filePath}`));
+      console.log(chalk.red(`    ${error.message}`));
+    }
+
+    return new ValidationResult(filePath, "error", error);
+  }
+}
+
+async function validateAllMdxFiles(files, verbose = false) {
+  const results = [];
+
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
+    const progress = `[${i + 1}/${files.length}]`;
+
+    if (verbose) {
+      console.log(`${progress} Validating ${file}...`);
+    }
+
+    const result = await validateMdxFile(file, verbose);
+    results.push(result);
+  }
+
+  return results;
+}
+
+function generateReport(results, repoRoot) {
+  const summary = {
+    total: results.length,
+    valid: results.filter((r) => r.status === "valid").length,
+    errors: results.filter((r) => r.status === "error").length,
+  };
+
+  const errors = results
+    .filter((r) => r.status === "error")
+    .map((r) => ({
+      filePath: relative(repoRoot, r.filePath),
+      error: r.error,
+    }));
+
+  const valid = results
+    .filter((r) => r.status === "valid")
+    .map((r) => relative(repoRoot, r.filePath));
+
+  return {
+    summary,
+    errors,
+    valid,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+// Main CLI Function
+
+export async function validateMdxFiles(options) {
+  const repoRoot = process.cwd();
+
+  if (!options.quiet) {
+    console.log(chalk.bold("\n📝 MDX File Validation\n"));
+  }
+
+  if (options.verbose && !options.quiet) {
+    console.log("Finding MDX files...");
+  }
+
+  const mdxFiles = findMdxFiles(repoRoot, options.dir, options.file);
+
+  if (mdxFiles.length === 0) {
+    console.error("No MDX files found.");
+    process.exit(1);
+  }
+
+  if (!options.quiet) {
+    console.log(`Found ${mdxFiles.length} MDX files\n`);
+  }
+
+  if (options.verbose && !options.quiet) {
+    console.log("Validating MDX files...\n");
+  }
+
+  const startTime = Date.now();
+  const results = await validateAllMdxFiles(mdxFiles, options.verbose);
+  const duration = ((Date.now() - startTime) / 1000).toFixed(2);
+
+  // Generate report
+  const report = generateReport(results, repoRoot);
+
+  // Always generate markdown content for the MD report
+  report.markdownContent = generateMdxParseMarkdown(report);
+
+  // Write both JSON and MD reports
+  const { jsonPath, mdPath } = writeBothFormats(report, "mdx_errors_report", repoRoot);
+
+  // Display summary
+  if (!options.quiet) {
+    console.log(chalk.bold(`\n✓ Validation complete in ${duration}s\n`));
+    console.log(chalk.bold("Summary:"));
+    console.log(`  Total files:  ${report.summary.total}`);
+    console.log(chalk.green(`  Valid files:  ${report.summary.valid}`));
+    console.log(chalk.red(`  Files with errors: ${report.summary.errors}`));
+    console.log(`\nReports saved to:`);
+    console.log(`  JSON: ${chalk.cyan(jsonPath)}`);
+    console.log(`  MD:   ${chalk.cyan(mdPath)}`);
+
+    if (report.summary.errors > 0) {
+      console.log(chalk.yellow(`\n⚠️  Found ${report.summary.errors} file(s) with parsing errors`));
+      console.log("\nFiles with errors:");
+      report.errors.forEach((err) => {
+        console.log(chalk.red(`  ✗ ${err.filePath}`));
+        console.log(`    ${err.error.message}`);
+        if (err.error.line) {
+          console.log(`    Line ${err.error.line}${err.error.column ? `, Column ${err.error.column}` : ''}`);
+        }
+      });
+      process.exit(1);
+    } else {
+      console.log(chalk.green("\n✓ All MDX files are valid!"));
+    }
+  }
+}

package/src/utils/config.js

@@ -0,0 +1,115 @@
+/**
+ * Configuration File Loader
+ *
+ * Loads optional config.json from the project root and merges with CLI arguments.
+ * CLI arguments take precedence over config file values.
+ */
+
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+
+/**
+ * Loads config.json from the current working directory if it exists
+ * @returns {Object|null} Configuration object or null if not found
+ */
+export function loadConfig() {
+  const configPath = join(process.cwd(), "config.json");
+
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const configContent = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(configContent);
+    return config;
+  } catch (error) {
+    console.error(`Error reading config.json: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Merges config file with CLI options for the links command
+ * CLI options take precedence over config file
+ *
+ * @param {string|undefined} baseUrl - Base URL from CLI
+ * @param {string|undefined} validationBaseUrl - Validation base URL from CLI
+ * @param {Object} options - CLI options
+ * @param {Object|null} config - Loaded config object
+ * @returns {Object} Merged configuration with baseUrl, validationBaseUrl, and options
+ */
+export function mergeLinksConfig(baseUrl, validationBaseUrl, options, config) {
+  if (!config) {
+    return { baseUrl, validationBaseUrl, options };
+  }
+
+  // Get base URLs from config if not provided via CLI
+  const finalBaseUrl = baseUrl || config.source;
+  const finalValidationBaseUrl = validationBaseUrl || config.target;
+
+  // Get links-specific config
+  const linksConfig = config.links || {};
+
+  // Merge options: CLI > links config > global config > defaults
+  const mergedOptions = {
+    ...options,
+    // Only use config values if CLI option wasn't provided
+    file: options.file || linksConfig.file,
+    dir: options.dir || linksConfig.dir,
+    output: options.output || linksConfig.output,
+    dryRun: options.dryRun !== undefined ? options.dryRun : linksConfig["dry-run"],
+    quiet: options.quiet !== undefined ? options.quiet : linksConfig.quiet,
+    concurrency: options.concurrency || linksConfig.concurrency,
+    headless: options.headless !== undefined ? options.headless :
+              (linksConfig.headless !== undefined ? linksConfig.headless : true),
+  };
+
+  return {
+    baseUrl: finalBaseUrl,
+    validationBaseUrl: finalValidationBaseUrl,
+    options: mergedOptions,
+  };
+}
+
+/**
+ * Merges config file with CLI options for the parse 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 mergeParseConfig(options, config) {
+  if (!config) {
+    return options;
+  }
+
+  // Get parse-specific config
+  const parseConfig = config.parse || {};
+
+  // Merge options: CLI > parse config > global config > defaults
+  return {
+    ...options,
+    file: options.file || parseConfig.file,
+    dir: options.dir || parseConfig.dir,
+    quiet: options.quiet !== undefined ? options.quiet : parseConfig.quiet,
+  };
+}
+
+/**
+ * Validates that required fields are present
+ * @param {string|undefined} baseUrl - Base URL
+ * @param {string} commandName - Name of the command for error messages
+ * @throws {Error} If required fields are missing
+ */
+export function validateRequiredConfig(baseUrl, commandName) {
+  if (!baseUrl) {
+    throw new Error(
+      `Missing required configuration: baseUrl must be provided either via CLI argument or in config.json (as "source")\n\n` +
+      `Usage:\n` +
+      `  CLI:        ${commandName} <baseUrl>\n` +
+      `  config.json: { "source": "https://docs.example.com" }`
+    );
+  }
+}

package/src/utils/reports.js

@@ -0,0 +1,182 @@
+/**
+ * Report Generation Utilities
+ *
+ * Shared utilities for generating validation reports in different formats (JSON, Markdown).
+ * Used by both links and parse validation commands.
+ */
+
+import { writeFileSync } from "fs";
+import { join } from "path";
+
+/**
+ * Writes a report to a file in the specified format
+ * @param {Object} reportData - The report data object
+ * @param {string} format - Output format: 'json' or 'md'
+ * @param {string} baseFileName - Base name for the report file (without extension)
+ * @param {string} repoRoot - Repository root directory
+ * @returns {string} Path to the written file
+ */
+export function writeReport(reportData, format, baseFileName, repoRoot) {
+  let content;
+  let extension;
+
+  if (format === "md" || format === "markdown") {
+    content = reportData.markdownContent || generateMarkdownFromJson(reportData);
+    extension = ".md";
+  } else {
+    content = JSON.stringify(reportData, null, 2);
+    extension = ".json";
+  }
+
+  const outputPath = join(repoRoot, `${baseFileName}${extension}`);
+  writeFileSync(outputPath, content, "utf-8");
+
+  return outputPath;
+}
+
+/**
+ * Fallback: Generates basic markdown from JSON structure
+ * @param {Object} data - Report data
+ * @returns {string} Markdown content
+ */
+function generateMarkdownFromJson(data) {
+  let markdown = "# Validation Report\n\n";
+  markdown += "```json\n";
+  markdown += JSON.stringify(data, null, 2);
+  markdown += "\n```\n";
+  return markdown;
+}
+
+/**
+ * Generates markdown report for MDX parsing validation
+ * @param {Object} report - Report object with summary, errors, valid, timestamp
+ * @returns {string} Markdown content
+ */
+export function generateMdxParseMarkdown(report) {
+  let markdown = "# MDX Validation Report\n\n";
+
+  // Summary
+  markdown += `## Summary\n\n`;
+  markdown += `- **Total files**: ${report.summary.total}\n`;
+  markdown += `- **Valid files**: ${report.summary.valid}\n`;
+  markdown += `- **Files with errors**: ${report.summary.errors}\n`;
+  markdown += `- **Generated**: ${report.timestamp}\n\n`;
+
+  // Files with errors
+  if (report.errors.length > 0) {
+    markdown += `## Files with Errors\n\n`;
+
+    report.errors.forEach((err) => {
+      markdown += `### [${err.filePath}](${err.filePath})\n\n`;
+      markdown += `- **Line ${err.error.line || "unknown"}**: ${err.error.message}\n`;
+
+      if (err.error.column) {
+        markdown += `  - Column: ${err.error.column}\n`;
+      }
+
+      markdown += `\n`;
+    });
+  }
+
+  return markdown;
+}
+
+/**
+ * Generates markdown report for links validation
+ * @param {Object} report - Report object with summary, configuration, results_by_file, timestamp
+ * @returns {string} Markdown content
+ */
+export function generateLinksMarkdown(report) {
+  let markdown = "# Links Validation Report\n\n";
+
+  // Summary
+  markdown += `## Summary\n\n`;
+  markdown += `- **Total links**: ${report.summary.total_links}\n`;
+  markdown += `- **Success**: ${report.summary.success}\n`;
+  markdown += `- **Failure**: ${report.summary.failure}\n`;
+  markdown += `- **Error**: ${report.summary.error}\n`;
+  markdown += `- **Generated**: ${report.timestamp}\n`;
+  markdown += `- **Execution time**: ${report.configuration.execution_time_seconds}s\n\n`;
+
+  // Configuration
+  markdown += `## Configuration\n\n`;
+  markdown += `- **Base URL**: ${report.configuration.base_url}\n`;
+  markdown += `- **Concurrency**: ${report.configuration.concurrency}\n`;
+  markdown += `- **Scanned directories**: ${report.configuration.scanned_directories.join(", ")}\n`;
+  markdown += `- **Excluded directories**: ${report.configuration.excluded_directories.join(", ")}\n\n`;
+
+  // Results by file
+  const failedResults = [];
+  const errorResults = [];
+
+  Object.entries(report.results_by_file).forEach(([filePath, results]) => {
+    results.forEach((result) => {
+      if (result.status === "failure") {
+        failedResults.push({ filePath, result });
+      } else if (result.status === "error") {
+        errorResults.push({ filePath, result });
+      }
+    });
+  });
+
+  // Failed links
+  if (failedResults.length > 0) {
+    markdown += `## Failed Links\n\n`;
+
+    failedResults.forEach(({ filePath, result }) => {
+      markdown += `### [${filePath}:${result.source.lineNumber}](${filePath}#L${result.source.lineNumber})\n\n`;
+      markdown += `- **Link text**: "${result.source.linkText}"\n`;
+      markdown += `- **Raw href**: \`${result.source.rawHref}\`\n`;
+      markdown += `- **Source URL**: ${result.sourceUrl}\n`;
+      markdown += `- **Target URL**: ${result.targetUrl}\n`;
+      markdown += `- **Error**: ${result.errorMessage}\n\n`;
+    });
+  }
+
+  // Error links
+  if (errorResults.length > 0) {
+    markdown += `## Links with Errors\n\n`;
+
+    errorResults.forEach(({ filePath, result }) => {
+      markdown += `### [${filePath}:${result.source.lineNumber}](${filePath}#L${result.source.lineNumber})\n\n`;
+      markdown += `- **Link text**: "${result.source.linkText}"\n`;
+      markdown += `- **Raw href**: \`${result.source.rawHref}\`\n`;
+      markdown += `- **Target URL**: ${result.targetUrl}\n`;
+      markdown += `- **Error**: ${result.errorMessage}\n\n`;
+    });
+  }
+
+  // Success message
+  if (failedResults.length === 0 && errorResults.length === 0) {
+    markdown += `## ✓ All Links Valid\n\n`;
+    markdown += `All ${report.summary.total_links} links validated successfully!\n`;
+  }
+
+  return markdown;
+}
+
+/**
+ * Writes a report in both JSON and Markdown formats
+ * Always generates both files regardless of user preference
+ * @param {Object} reportData - The report data object
+ * @param {string} baseFileName - Base name for the report file (without extension)
+ * @param {string} repoRoot - Repository root directory
+ * @returns {Object} Object with jsonPath and mdPath
+ */
+export function writeBothFormats(reportData, baseFileName, repoRoot) {
+  const jsonPath = writeReport(reportData, "json", baseFileName, repoRoot);
+  const mdPath = writeReport(reportData, "md", baseFileName, repoRoot);
+
+  return { jsonPath, mdPath };
+}
+
+/**
+ * Normalizes format string to lowercase and handles variations
+ * @param {string|undefined} format - Format string
+ * @returns {string} Normalized format ('json' or 'md')
+ */
+export function normalizeFormat(format) {
+  if (!format) return "json";
+  const normalized = format.toLowerCase();
+  return normalized === "markdown" ? "md" : normalized;
+}