@writechoice/mint-cli 0.0.8 → 0.0.10

package/README.md

@@ -2,396 +2,256 @@
 
 CLI tool for Mintlify documentation validation and utilities.
 
-## Features
-
-- **Link Validation**: Validates internal links and anchors in MDX documentation files
-- **Browser Automation**: Uses Playwright to test links against live websites
-- **Auto-Fix**: Automatically fixes incorrect anchor links
-- **Detailed Reporting**: Generates JSON reports with validation results
-- **Concurrent Processing**: Validates multiple links simultaneously for better performance
+## Quick Start
 
-## Installation
-
-### Global Installation
+### Installation
 
 ```bash
 npm install -g @writechoice/mint-cli
+npx playwright install chromium
 ```
 
-### Local Development
+### Usage
 
 ```bash
-# Clone the repository
-git clone <repository-url>
-cd writechoice-mint-cli
-
-# Install dependencies
-npm install
-
-# Install Playwright browsers
-npx playwright install chromium
+# Check version
+writechoice --version
 
-# Make CLI executable
-chmod +x bin/cli.js
+# Update to latest
+writechoice update
 
-# Link for local development
-npm link
-```
+# Validate MDX parsing
+writechoice check parse
 
-## Usage
+# Validate links
+writechoice check links https://docs.example.com
 
-### Check Version
+# Validate with local development server
+writechoice check links docs.example.com http://localhost:3000
 
-Check the installed version:
+# Fix broken anchor links
+writechoice fix links
 
-```bash
-writechoice --version
-# or
-writechoice -v
+# Generate config.json template
+writechoice config
 ```
 
-### Update to Latest Version
+## Commands
+
+### `config`
 
-Update to the latest version from npm:
+Generates a config.json template file with all available options.
 
 ```bash
-writechoice update
+writechoice config                         # Create config.json
+writechoice config --force                 # Overwrite existing config.json
 ```
 
-The CLI also automatically checks for updates and displays a notification when a new version is available.
+**Output:** Creates `config.json` in the current directory with placeholder values.
 
-### Validate Links
+### `check parse`
 
-Validate all internal links and anchors in your MDX documentation:
+Validates MDX files for parsing errors.
 
 ```bash
-writechoice check links https://docs.example.com
+writechoice check parse                    # All files
+writechoice check parse -f file.mdx        # Single file
+writechoice check parse -d docs            # Specific directory
 ```
 
-You can also omit the `https://` prefix:
-
-```bash
-writechoice check links docs.example.com
-```
+**Output:** Both `mdx_errors_report.json` and `mdx_errors_report.md`
 
-**Using a Validation Base URL**
+### `check links`
 
-When validating anchor links online, the tool can use a different base URL (e.g., a local development server or staging environment) to click on headings and extract the generated anchors:
+Validates internal links and anchors using browser automation.
 
 ```bash
-# Use localhost:3000 for validation (default)
-writechoice check links docs.example.com
-
-# Use a custom validation URL
-writechoice check links docs.example.com http://localhost:3000
-
-# Use a staging environment
-writechoice check links docs.example.com https://staging.example.com
+writechoice check links <baseUrl> [validationBaseUrl]
 ```
 
-The validation base URL is only used for online checks. Local file validation remains unchanged for optimal performance.
-
-**How the two-step validation works:**
+**Common options:**
+- `-f, --file <path>` - Validate single file
+- `-d, --dir <path>` - Validate specific directory
+- `-o, --output <path>` - Base name for reports (default: `links_report`)
+- `-c, --concurrency <number>` - Concurrent browser tabs (default: 25)
+- `--quiet` - Suppress output
+- `--dry-run` - Extract links without validating
 
-For anchor links, the tool performs a smart validation:
+**Output:** Both `links_report.json` and `links_report.md`
 
-1. Navigates to your production docs (base URL) to find the actual heading the anchor points to
-2. Then navigates to your local dev server (validation URL) and clicks the same heading to see what anchor it generates
-3. Compares the two anchors to detect mismatches
+### `fix links`
 
-This is useful because:
-
-- Link text in MDX files may differ from actual heading text
-- Handles pages with duplicate headings correctly by matching position
-- Validates against your local development environment before deploying
-
-### Common Options
+Automatically fixes broken anchor links based on validation reports.
 
 ```bash
-# Validate links in a specific file
-writechoice check links docs.example.com -f path/to/file.mdx
-
-# Validate links in a specific directory
-writechoice check links docs.example.com -d path/to/docs
-
-# Dry run (extract links without validating)
-writechoice check links docs.example.com --dry-run
-
-# Quiet mode (suppress terminal output, only generate report)
-writechoice check links docs.example.com --quiet
-
-# Custom output path for report
-writechoice check links docs.example.com -o validation-report.json
-
-# Set concurrency level
-writechoice check links docs.example.com -c 50
-
-# Show browser window (for debugging)
-writechoice check links docs.example.com --no-headless
-
-# Auto-fix incorrect anchor links
-writechoice check links docs.example.com --fix
-
-# Fix links from the default report file (links_report.json)
-writechoice check links docs.example.com --fix-from-report
-
-# Fix links from a custom report file
-writechoice check links docs.example.com --fix-from-report custom_report.json
+writechoice fix links                      # Use default report
+writechoice fix links -r custom_report.json  # Use custom report
 ```
 
-### Complete Options
+**Common options:**
+- `-r, --report <path>` - Path to JSON report (default: `links_report.json`)
+- `--quiet` - Suppress output
 
-| Option                     | Alias | Description                                                               | Default                 |
-| -------------------------- | ----- | ------------------------------------------------------------------------- | ----------------------- |
-| `<baseUrl>`                | -     | Base URL for the documentation site (required, with or without https://)  | -                       |
-| `[validationBaseUrl]`      | -     | Base URL for online validation (optional, clicks headings to get anchors) | `http://localhost:3000` |
-| `--file <path>`            | `-f`  | Validate links in a single MDX file                                       | -                       |
-| `--dir <path>`             | `-d`  | Validate links in a specific directory                                    | -                       |
-| `--output <path>`          | `-o`  | Output path for JSON report                                               | `links_report.json`     |
-| `--dry-run`                | -     | Extract and show links without validating                                 | `false`                 |
-| `--quiet`                  | -     | Suppress terminal output (only generate report)                           | `false`                 |
-| `--concurrency <number>`   | `-c`  | Number of concurrent browser tabs                                         | `25`                    |
-| `--headless`               | -     | Run browser in headless mode                                              | `true`                  |
-| `--no-headless`            | -     | Show browser window (for debugging)                                       | -                       |
-| `--fix`                    | -     | Automatically fix anchor links in MDX files                               | `false`                 |
-| `--fix-from-report [path]` | -     | Fix anchor links from report file (optional path)                         | `links_report.json`     |
+**Note:** Requires JSON report from `check links` command.
 
-**Note:** Detailed progress output is shown by default. Use `--quiet` to suppress terminal output.
+### `update`
 
-## How It Works
+Update CLI to latest version.
 
-### Link Extraction
+```bash
+writechoice update
+```
 
-The tool extracts internal links from MDX files in the following formats:
+## Features
 
-1. **Markdown links**: `[Link Text](./path/to/page#anchor)`
-2. **HTML anchors**: `<a href="/path/to/page#anchor">Link Text</a>`
-3. **JSX Card components**: `<Card href="/path/to/page" title="Card Title" />`
-4. **JSX Button components**: `<Button href="/path/to/page#anchor">Button Text</Button>`
+- **MDX Parsing Validation** - Catch syntax errors before deployment
+- **Link Validation** - Test links against live websites with Playwright
+- **Two-Step Anchor Validation** - Compare production vs development anchors
+- **Auto-Fix** - Separate fix command to automatically correct broken anchor links
+- **Dual Report Formats** - Generates both JSON (for automation) and Markdown (for humans)
+- **Configuration File** - Optional config.json for default settings
+- **CI/CD Ready** - Exit codes for pipeline integration
 
-**Images are automatically ignored:**
+## How Two-Step Validation Works
 
-- Markdown images: `![Alt Text](./image.png)`
-- HTML images: `<img src="./image.png" />`
+For anchor links, the tool:
 
-### Validation Process
+1. **Finds the target** (Production): Navigates to production docs to identify which heading the anchor points to
+2. **Gets the anchor** (Validation): Navigates to your dev server (localhost:3000), clicks the heading, and extracts the generated anchor
+3. **Compares**: Checks if anchors match
 
-1. **Local Validation**: First checks if the target MDX file exists locally
-   - For normal links: Verifies the file exists in the repository
-   - For anchor links: Checks if the heading exists in the MDX file with matching kebab-case format
-2. **Online Validation**: If local check fails, performs a two-step validation process
-   - For normal links: Navigates to the validation base URL and verifies the page loads successfully
-   - For anchor links (two-step process):
-     1. **Step 1 - Find the target heading**: Navigates to the base URL (production docs) with the anchor to identify which heading the anchor points to and its position (handles duplicate headings)
-     2. **Step 2 - Get generated anchor**: Navigates to the validation base URL (e.g., localhost:3000), finds the same heading (by text and position), clicks it to trigger anchor generation, and extracts the generated anchor from the URL
-     3. Compares the generated anchor with the expected anchor from the MDX file
-3. **Validation Base URL**: By default uses `http://localhost:3000` for online validation, or you can specify a custom URL (e.g., staging environment). This allows testing against a local development server or staging environment while validating links meant for production.
-4. **Auto-Fix**: When issues are found, can automatically update MDX files with the correct anchors
+This ensures your local development environment matches production behavior.
 
-### Report Format
+## Configuration File
 
-The tool generates a JSON report with the following structure:
+Create an optional `config.json` in your project root to set default values:
 
 ```json
 {
-  "timestamp": "2024-01-15T10:30:00.000Z",
-  "configuration": {
-    "base_url": "https://docs.example.com",
-    "scanned_directories": ["."],
-    "excluded_directories": ["snippets"],
+  "source": "https://docs.example.com",
+  "target": "http://localhost:3000",
+  "links": {
     "concurrency": 25,
-    "execution_time_seconds": 45.23
+    "quiet": false
   },
-  "summary": {
-    "total_links": 250,
-    "success": 240,
-    "failure": 8,
-    "error": 2
-  },
-  "results_by_file": {
-    "docs/getting-started.mdx": [
-      {
-        "source": {
-          "filePath": "docs/getting-started.mdx",
-          "lineNumber": 42,
-          "linkText": "Installation Guide",
-          "rawHref": "./installation#setup",
-          "linkType": "markdown"
-        },
-        "targetUrl": "https://docs.example.com/docs/installation#setup",
-        "status": "failure",
-        "errorMessage": "Expected anchor \"#setup\" but page heading \"Setup Process\" should use \"#setup-process\""
-      }
-    ]
+  "parse": {
+    "quiet": false
   }
 }
 ```
 
-## Auto-Fix Feature
-
-The `--fix` option automatically corrects anchor links that don't match the heading text:
-
-**Before:**
-
-```markdown
-[Installation Guide](./installation#setup)
-```
-
-**After:**
-
-```markdown
-[Installation Guide](./installation#setup-process)
-```
-
-### Fix Workflow
-
-1. **Run validation**: `writechoice check links docs.example.com`
-2. **Review report**: Check the generated `links_report.json` for issues
-3. **Apply fixes**: `writechoice check links docs.example.com --fix-from-report`
-4. **Re-validate**: Run validation again to verify fixes
-
-Or use a custom report file:
+With config.json, you can run commands without arguments:
 
 ```bash
-# Generate custom report
-writechoice check links docs.example.com -o my_report.json
+# Uses source and target from config.json
+writechoice check links
 
-# Fix from custom report
-writechoice check links docs.example.com --fix-from-report my_report.json
+# CLI args override config.json values
+writechoice check links https://staging.example.com
 ```
 
-## Updates
-
-The CLI automatically checks for new versions and displays a notification when an update is available:
-
-```
-┌─────────────────────────────────────────────────┐
-│  Update available: 0.0.2 → 0.0.3                │
-│  Run: writechoice update                        │
-└─────────────────────────────────────────────────┘
-```
+See [config.example.json](config.example.json) for all available options.
 
-To update manually:
+## Examples
 
 ```bash
-# Using the built-in update command (recommended)
-writechoice update
-
-# Or using npm directly
-npm install -g @writechoice/mint-cli@latest
-```
-
-## Configuration
-
-### Excluded Directories
-
-By default, the following directories are excluded from scanning:
-
-- `snippets/`
+# Validate all MDX files for parsing errors
+writechoice check parse
 
-You can modify this in the source code at [src/commands/validate/links.js](src/commands/validate/links.js).
+# Validate all links (uses localhost:3000 by default)
+writechoice check links https://docs.example.com
 
-### Default Concurrency
+# Validate with staging environment
+writechoice check links docs.example.com https://staging.example.com
 
-The default concurrency is set to 25 concurrent browser tabs. Adjust this based on your system resources:
+# Validate specific directory only
+writechoice check links docs.example.com -d api
 
-- **Lower values** (5-10): Slower but less resource-intensive
-- **Higher values** (50-100): Faster but requires more memory and CPU
+# Run quietly (only generate reports)
+writechoice check links docs.example.com --quiet
 
-## Examples
+# Fix broken anchor links
+writechoice fix links
 
-### Validate all links (with progress output)
+# Fix from custom report
+writechoice fix links -r custom_report.json
 
-```bash
+# Full workflow: validate -> fix -> re-validate
+writechoice check links docs.example.com
+writechoice fix links
 writechoice check links docs.example.com
 ```
 
-### Validate quietly (suppress terminal output)
+## Documentation
 
-```bash
-writechoice check links docs.example.com --quiet
-```
+Detailed documentation is available in the [docs/](docs/) folder:
 
-### Validate and fix issues in one command
+- **Commands**
+  - [config](docs/commands/config.md) - Generate config.json template
+  - [check links](docs/commands/check-links.md) - Link validation
+  - [check parse](docs/commands/check-parse.md) - MDX parsing validation
+  - [fix links](docs/commands/fix-links.md) - Auto-fix broken links
+  - [update](docs/commands/update.md) - Update command
+- **Guides**
+  - [Configuration File](docs/config-file.md) - Using config.json
+  - [Configuration](docs/configuration.md) - Advanced configuration
+  - [Publishing](docs/publishing.md) - How to publish new versions
 
-```bash
-writechoice check links docs.example.com --fix
-```
+## Development
 
-### Two-step fix workflow
+### Local Setup
 
 ```bash
-# Step 1: Generate report
-writechoice check links docs.example.com -o issues.json
-
-# Step 2: Review and apply fixes
-writechoice check links docs.example.com --fix-from-report issues.json
-
-# Or fix from default report (links_report.json)
-writechoice check links docs.example.com --fix-from-report
+git clone <repository-url>
+cd writechoice-mint-cli
+npm install
+npx playwright install chromium
+chmod +x bin/cli.js
+npm link
 ```
 
-### Validate specific directory
+### Project Structure
 
-```bash
-writechoice check links docs.example.com -d docs/api
+```
+writechoice-mint-cli/
+├── bin/
+│   └── cli.js                 # CLI entry point
+├── src/
+│   ├── commands/
+│   │   ├── validate/
+│   │   │   ├── links.js       # Link validation
+│   │   │   └── mdx.js         # MDX parsing validation
+│   │   └── fix/
+│   │       └── links.js       # Link fixing
+│   └── utils/
+│       ├── helpers.js         # Utility functions
+│       └── reports.js         # Report generation
+├── docs/                      # Detailed documentation
+├── package.json
+└── README.md
 ```
 
 ## Troubleshooting
 
 ### Playwright Not Installed
 
-If you get an error about Playwright not being installed:
-
 ```bash
 npx playwright install chromium
 ```
 
 ### Memory Issues
 
-If you encounter memory issues with high concurrency:
-
 ```bash
 writechoice check links docs.example.com -c 10
 ```
 
-### Browser Launch Failed
-
-If the browser fails to launch in headless mode:
+### Permission Errors
 
 ```bash
-writechoice check links docs.example.com --no-headless
+sudo npm install -g @writechoice/mint-cli
 ```
 
-## Development
-
-### Project Structure
-
-```
-writechoice-mint-cli/
-├── bin/
-│   └── cli.js              # CLI entry point
-├── src/
-│   ├── commands/
-│   │   └── validate/
-│   │       └── links.js    # Link validation logic
-│   └── utils/
-│       └── helpers.js      # Helper functions
-├── package.json
-└── README.md
-```
-
-### Running Tests
-
-```bash
-npm test
-```
-
-### Adding New Commands
-
-1. Create a new command file in `src/commands/`
-2. Add the command to `bin/cli.js`
-3. Update this README with usage instructions
+Or use a node version manager like [nvm](https://github.com/nvm-sh/nvm).
 
 ## License
 
@@ -400,3 +260,9 @@ MIT
 ## Contributing
 
 Contributions are welcome! Please open an issue or submit a pull request.
+
+## Links
+
+- [npm package](https://www.npmjs.com/package/@writechoice/mint-cli)
+- [GitHub repository](https://github.com/writechoice/mint-cli)
+- [Issue tracker](https://github.com/writechoice/mint-cli/issues)

package/bin/cli.js

@@ -24,25 +24,86 @@ const check = program.command("check").description("Validation commands for docu
 
 // Validate links subcommand
 check
-  .command("links <baseUrl> [validationBaseUrl]")
+  .command("links [baseUrl] [validationBaseUrl]")
   .description("Validate internal links and anchors in MDX documentation files")
   .option("-f, --file <path>", "Validate links in a single MDX file")
   .option("-d, --dir <path>", "Validate links in a specific directory")
-  .option("-o, --output <path>", "Output path for JSON report", "links_report.json")
+  .option("-o, --output <path>", "Output path for report (without extension)", "links_report")
   .option("--dry-run", "Extract and show links without validating")
   .option("--quiet", "Suppress terminal output (only generate report)")
   .option("-c, --concurrency <number>", "Number of concurrent browser tabs", "25")
   .option("--headless", "Run browser in headless mode (default)", true)
   .option("--no-headless", "Show browser window (for debugging)")
-  .option("--fix", "Automatically fix anchor links in MDX files")
-  .option("--fix-from-report [path]", "Fix anchor links from report file (default: links_report.json)")
   .action(async (baseUrl, validationBaseUrl, options) => {
+    const { loadConfig, mergeLinksConfig, validateRequiredConfig } = await import("../src/utils/config.js");
     const { validateLinks } = await import("../src/commands/validate/links.js");
-    // Verbose is now default (true unless --quiet is specified)
+
+    // Load config.json if it exists
+    const config = loadConfig();
+
+    // Merge CLI args with config file (CLI takes precedence)
+    const merged = mergeLinksConfig(baseUrl, validationBaseUrl, options, config);
+
+    // Validate that baseUrl is provided (either via CLI or config)
+    try {
+      validateRequiredConfig(merged.baseUrl, "writechoice check links");
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
+    }
+
+    // Set defaults
+    merged.options.verbose = !merged.options.quiet;
+    merged.options.validationBaseUrl = merged.validationBaseUrl || "http://localhost:3000";
+
+    await validateLinks(merged.baseUrl, merged.options);
+  });
+
+// Validate MDX parsing subcommand
+check
+  .command("parse")
+  .description("Validate MDX files for parsing errors")
+  .option("-f, --file <path>", "Validate a single MDX file")
+  .option("-d, --dir <path>", "Validate MDX files in a specific directory")
+  .option("--quiet", "Suppress terminal output (only generate report)")
+  .action(async (options) => {
+    const { loadConfig, mergeParseConfig } = await import("../src/utils/config.js");
+    const { validateMdxFiles } = await import("../src/commands/validate/mdx.js");
+
+    // Load config.json if it exists
+    const config = loadConfig();
+
+    // Merge CLI args with config file (CLI takes precedence)
+    const mergedOptions = mergeParseConfig(options, config);
+
+    mergedOptions.verbose = !mergedOptions.quiet;
+    await validateMdxFiles(mergedOptions);
+  });
+
+// Fix command
+const fix = program.command("fix").description("Fix issues found in validation reports");
+
+// Fix links subcommand
+fix
+  .command("links")
+  .description("Fix broken anchor links from validation report")
+  .option("-r, --report <path>", "Path to validation report", "links_report.json")
+  .option("--quiet", "Suppress terminal output")
+  .action(async (options) => {
+    const { fixLinks } = await import("../src/commands/fix/links.js");
     options.verbose = !options.quiet;
-    // Set validation base URL to localhost:3000 if not provided
-    options.validationBaseUrl = validationBaseUrl || "http://localhost:3000";
-    await validateLinks(baseUrl, options);
+    await fixLinks(options);
+  });
+
+// Config command
+program
+  .command("config")
+  .description("Generate a config.json template file")
+  .option("--force", "Overwrite existing config.json file")
+  .option("--quiet", "Suppress terminal output")
+  .action(async (options) => {
+    const { generateConfig } = await import("../src/commands/config.js");
+    await generateConfig(options);
   });
 
 // Update command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writechoice/mint-cli",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "CLI tool for Mintlify documentation validation and utilities",
   "main": "src/index.js",
   "type": "module",
@@ -41,11 +41,12 @@
     "PUBLISH.md"
   ],
   "dependencies": {
+    "@mdx-js/mdx": "^3.1.1",
+    "chalk": "^5.3.0",
     "commander": "^12.0.0",
-    "playwright": "^1.40.0",
-    "chalk": "^5.3.0"
+    "playwright": "^1.40.0"
   },
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}