@writechoice/mint-cli 0.0.5 → 0.0.6

package/README.md

@@ -47,7 +47,7 @@ Check the installed version:
 ```bash
 writechoice --version
 # or
-writechoice -V
+writechoice -v
 ```
 
 ### Update to Latest Version
@@ -74,6 +74,23 @@ You can also omit the `https://` prefix:
 writechoice check links docs.example.com
 ```
 
+**Using a Validation Base URL**
+
+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:
+
+```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
+```
+
+The validation base URL is only used for online checks. Local file validation remains unchanged for optimal performance.
+
 ### Common Options
 
 ```bash
@@ -110,19 +127,20 @@ writechoice check links docs.example.com --fix-from-report custom_report.json
 
 ### Complete Options
 
-| Option                     | Alias | Description                                                              | Default             |
-| -------------------------- | ----- | ------------------------------------------------------------------------ | ------------------- |
-| `<baseUrl>`                | -     | Base URL for the documentation site (required, with or without https://) | -                   |
-| `--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` |
+| 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:** Detailed progress output is shown by default. Use `--quiet` to suppress terminal output.
 
@@ -138,15 +156,24 @@ The tool extracts internal links from MDX files in the following formats:
 4. **JSX Button components**: `<Button href="/path/to/page#anchor">Button Text</Button>`
 
 **Images are automatically ignored:**
+
 - Markdown images: `![Alt Text](./image.png)`
 - HTML images: `<img src="./image.png" />`
 
 ### Validation Process
 
 1. **Local Validation**: First checks if the target MDX file exists locally
-2. **Online Validation**: If local check fails, uses Playwright to navigate to the live URL
-3. **Anchor Validation**: For anchor links, verifies the heading exists and matches the anchor format
-4. **Kebab-case Checking**: Ensures anchors follow the correct kebab-case format
+   - 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, uses Playwright to navigate to the validation base URL
+   - For normal links: Verifies the page loads successfully
+   - For anchor links:
+     - Finds the heading on the page by text matching
+     - Clicks on the heading to trigger anchor generation
+     - Extracts the generated anchor from the URL or href attribute
+     - Compares the generated anchor with the expected anchor
+3. **Validation Base URL**: By default uses `http://localhost:3000` for online validation, or you can specify a custom URL (e.g., staging environment)
+4. **Auto-Fix**: When issues are found, can automatically update MDX files with the correct anchors
 
 ### Report Format
 

package/bin/cli.js

@@ -24,7 +24,7 @@ const check = program.command("check").description("Validation commands for docu
 
 // Validate links subcommand
 check
-  .command("links <baseUrl>")
+  .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")
@@ -36,10 +36,12 @@ check
   .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, options) => {
+  .action(async (baseUrl, validationBaseUrl, options) => {
     const { validateLinks } = await import("../src/commands/validate/links.js");
     // Verbose is now default (true unless --quiet is specified)
     options.verbose = !options.quiet;
+    // Set validation base URL to localhost:3000 if not provided
+    options.validationBaseUrl = validationBaseUrl || "http://localhost:3000";
     await validateLinks(baseUrl, options);
   });
 

package/package.json

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

package/src/commands/validate/links.js

@@ -377,7 +377,7 @@ function findMdxFiles(repoRoot, directory = null, file = null) {
 
 // Playwright Validation Functions
 
-async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, progress = "") {
+async function validateAnchor(page, link, baseUrl, validationBaseUrl, repoRoot, verbose = false, progress = "") {
   const startTime = Date.now();
 
   try {
@@ -385,7 +385,7 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
       console.log(`${progress}    Validating anchor: ${link.anchor}`);
     }
 
-    // OPTIMIZATION: Check if anchor exists in local MDX file first
+    // OPTIMIZATION: Check if anchor exists in local MDX file first (local validation)
     const mdxFilePath = urlToFilePath(link.basePath, baseUrl, repoRoot);
     if (mdxFilePath && existsSync(mdxFilePath)) {
       const mdxHeadings = extractMdxHeadings(mdxFilePath);
@@ -394,7 +394,7 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
       if (mdxHeadingsKebab.includes(link.anchor)) {
         const heading = mdxHeadings.find((h) => toKebabCase(h) === link.anchor);
         if (verbose) {
-          console.log(`                   ✓ Anchor validated locally in MDX file`);
+          console.log(`${progress}      ✓ Anchor validated locally in MDX file`);
         }
         return new ValidationResult(
           link.source,
@@ -410,21 +410,47 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
           Date.now() - startTime,
         );
       } else if (verbose) {
-        console.log(`                   Anchor not found in local MDX, checking online...`);
+        console.log(`${progress}      Anchor not found in local MDX, checking online...`);
       }
     }
 
-    // Navigate to base page
-    await page.goto(link.basePath, { waitUntil: "networkidle", timeout: DEFAULT_TIMEOUT });
+    // ONLINE VALIDATION: Use validation base URL to navigate and click on headings
+    // Convert the base path to use the validation base URL
+    const validationUrl = link.basePath.replace(baseUrl, validationBaseUrl);
 
-    // Try to find heading by anchor
-    let heading = await page.$(`#${link.anchor}`);
+    if (verbose) {
+      console.log(`${progress}      Navigating to: ${validationUrl}`);
+    }
+
+    // Navigate to validation page
+    await page.goto(validationUrl, { waitUntil: "networkidle", timeout: DEFAULT_TIMEOUT });
+
+    // Extract headings from the MDX file to find the matching heading text
+    let targetHeadingText = null;
+
+    if (mdxFilePath && existsSync(mdxFilePath)) {
+      const mdxHeadings = extractMdxHeadings(mdxFilePath);
+      const mdxHeadingsKebab = mdxHeadings.map((h) => toKebabCase(h));
+
+      // Find the heading that matches our anchor
+      const headingIndex = mdxHeadingsKebab.indexOf(link.anchor);
+      if (headingIndex !== -1) {
+        targetHeadingText = mdxHeadings[headingIndex];
+        if (verbose) {
+          console.log(`${progress}      Looking for heading: "${targetHeadingText}"`);
+        }
+      }
+    }
 
-    if (!heading) {
-      heading = await page.$(`[id="${link.anchor}"]`);
+    // If we couldn't find the heading text from MDX, try to find it by the link text
+    if (!targetHeadingText && link.source.linkText) {
+      targetHeadingText = link.source.linkText;
+      if (verbose) {
+        console.log(`${progress}      Using link text as heading: "${targetHeadingText}"`);
+      }
     }
 
-    if (!heading) {
+    if (!targetHeadingText) {
       return new ValidationResult(
         link.source,
         link.targetUrl,
@@ -435,84 +461,147 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
         null,
         null,
         null,
-        `Anchor #${link.anchor} not found on page`,
+        `Could not determine heading text to search for anchor #${link.anchor}`,
         Date.now() - startTime,
       );
     }
 
-    // Get heading text and clean it
-    const actualText = await heading.innerText();
-    const actualTextClean = cleanHeadingText(actualText);
-    const actualKebab = toKebabCase(actualTextClean);
+    // Find all headings on the page
+    const headings = await page.$$("h1, h2, h3, h4, h5, h6");
+    let matchedHeading = null;
+    let matchedHeadingText = null;
 
-    // Extract headings from the TARGET MDX file to verify
-    const mdxFilePath2 = urlToFilePath(link.basePath, baseUrl, repoRoot);
-    const mdxHeadings = mdxFilePath2 ? extractMdxHeadings(mdxFilePath2) : [];
-    const mdxHeadingsKebab = mdxHeadings.map((h) => toKebabCase(h));
+    // Try to find the heading by text matching
+    for (const heading of headings) {
+      const headingText = await heading.innerText();
+      const headingTextClean = cleanHeadingText(headingText);
 
-    const matchesMdx = mdxHeadingsKebab.includes(actualKebab);
+      // Try exact match first
+      if (headingTextClean.toLowerCase() === targetHeadingText.toLowerCase()) {
+        matchedHeading = heading;
+        matchedHeadingText = headingTextClean;
+        if (verbose) {
+          console.log(`${progress}      Found exact match: "${headingTextClean}"`);
+        }
+        break;
+      }
 
-    if (actualKebab === link.anchor) {
-      if (matchesMdx) {
-        return new ValidationResult(
-          link.source,
-          link.targetUrl,
-          link.basePath,
-          link.anchor,
-          link.expectedSlug,
-          "success",
-          link.basePath,
-          actualTextClean,
-          actualKebab,
-          null,
-          Date.now() - startTime,
-        );
-      } else {
-        return new ValidationResult(
-          link.source,
-          link.targetUrl,
-          link.basePath,
-          link.anchor,
-          link.expectedSlug,
-          "failure",
-          null,
-          actualTextClean,
-          actualKebab,
-          `Anchor "#${link.anchor}" matches page heading "${actualTextClean}" but this heading is not found in the MDX file`,
-          Date.now() - startTime,
-        );
+      // Try partial match
+      if (
+        headingTextClean.toLowerCase().includes(targetHeadingText.toLowerCase()) ||
+        targetHeadingText.toLowerCase().includes(headingTextClean.toLowerCase())
+      ) {
+        if (!matchedHeading) {
+          matchedHeading = heading;
+          matchedHeadingText = headingTextClean;
+          if (verbose) {
+            console.log(`${progress}      Found partial match: "${headingTextClean}"`);
+          }
+        }
       }
-    } else {
-      if (matchesMdx) {
-        return new ValidationResult(
-          link.source,
-          link.targetUrl,
-          link.basePath,
-          link.anchor,
-          link.expectedSlug,
-          "failure",
-          null,
-          actualTextClean,
-          actualKebab,
-          `Expected anchor "#${link.anchor}" but page heading "${actualTextClean}" should use "#${actualKebab}"`,
-          Date.now() - startTime,
-        );
-      } else {
-        return new ValidationResult(
-          link.source,
-          link.targetUrl,
-          link.basePath,
-          link.anchor,
-          link.expectedSlug,
-          "failure",
-          null,
-          actualTextClean,
-          actualKebab,
-          `Expected anchor "#${link.anchor}" but found heading "${actualTextClean}" (#${actualKebab}) which is not in the MDX file`,
-          Date.now() - startTime,
-        );
+    }
+
+    if (!matchedHeading) {
+      return new ValidationResult(
+        link.source,
+        link.targetUrl,
+        link.basePath,
+        link.anchor,
+        link.expectedSlug,
+        "failure",
+        null,
+        null,
+        null,
+        `Heading "${targetHeadingText}" not found on page`,
+        Date.now() - startTime,
+      );
+    }
+
+    // Click the heading to trigger anchor generation
+    if (verbose) {
+      console.log(`${progress}      Clicking heading to get generated anchor...`);
+    }
+
+    // Try to click on the heading element or a link inside it
+    let clickTarget = matchedHeading;
+    const linkInHeading = await matchedHeading.$("a");
+    if (linkInHeading) {
+      clickTarget = linkInHeading;
+    }
+
+    await clickTarget.click();
+
+    // Wait a bit for any JavaScript to update the URL
+    await page.waitForTimeout(500);
+
+    // Get the current URL to extract the anchor
+    const currentUrl = page.url();
+    let generatedAnchor = null;
+
+    if (currentUrl.includes("#")) {
+      generatedAnchor = currentUrl.split("#")[1];
+      if (verbose) {
+        console.log(`${progress}      Generated anchor from URL: #${generatedAnchor}`);
       }
     }
+
+    // If no anchor in URL, try to get it from the href attribute of the link
+    if (!generatedAnchor && linkInHeading) {
+      const href = await linkInHeading.getAttribute("href");
+      if (href && href.includes("#")) {
+        generatedAnchor = href.split("#")[1];
+        if (verbose) {
+          console.log(`${progress}      Generated anchor from href: #${generatedAnchor}`);
+        }
+      }
+    }
+
+    if (!generatedAnchor) {
+      return new ValidationResult(
+        link.source,
+        link.targetUrl,
+        link.basePath,
+        link.anchor,
+        link.expectedSlug,
+        "failure",
+        null,
+        matchedHeadingText,
+        null,
+        `Could not extract generated anchor after clicking heading "${matchedHeadingText}"`,
+        Date.now() - startTime,
+      );
+    }
+
+    // Compare the generated anchor with the expected anchor
+    if (generatedAnchor === link.anchor) {
+      return new ValidationResult(
+        link.source,
+        link.targetUrl,
+        link.basePath,
+        link.anchor,
+        link.expectedSlug,
+        "success",
+        link.basePath,
+        matchedHeadingText,
+        generatedAnchor,
+        null,
+        Date.now() - startTime,
+      );
+    } else {
+      return new ValidationResult(
+        link.source,
+        link.targetUrl,
+        link.basePath,
+        link.anchor,
+        link.expectedSlug,
+        "failure",
+        null,
+        matchedHeadingText,
+        generatedAnchor,
+        `Expected anchor "#${link.anchor}" but page generates "#${generatedAnchor}" for heading "${matchedHeadingText}"`,
+        Date.now() - startTime,
+      );
+    }
   } catch (error) {
     return new ValidationResult(
       link.source,
@@ -530,7 +619,7 @@ async function validateAnchor(page, link, baseUrl, repoRoot, verbose = false, pr
   }
 }
 
-async function validateNormalLink(page, link, baseUrl, repoRoot, verbose = false, progress = "") {
+async function validateNormalLink(page, link, baseUrl, validationBaseUrl, repoRoot, verbose = false, progress = "") {
   const startTime = Date.now();
 
   try {
@@ -561,8 +650,15 @@ async function validateNormalLink(page, link, baseUrl, repoRoot, verbose = false
       console.log(`                   File not found locally, checking online...`);
     }
 
-    // Navigate to the target URL
-    const response = await page.goto(link.targetUrl, { waitUntil: "networkidle", timeout: DEFAULT_TIMEOUT });
+    // Convert the target URL to use the validation base URL
+    const validationUrl = link.targetUrl.replace(baseUrl, validationBaseUrl);
+
+    if (verbose) {
+      console.log(`${progress}      Navigating to: ${validationUrl}`);
+    }
+
+    // Navigate to the validation URL
+    const response = await page.goto(validationUrl, { waitUntil: "networkidle", timeout: DEFAULT_TIMEOUT });
 
     if (!response) {
       return new ValidationResult(
@@ -628,15 +724,15 @@ async function validateNormalLink(page, link, baseUrl, repoRoot, verbose = false
   }
 }
 
-async function validateLink(page, link, baseUrl, repoRoot, verbose = false, progress = "") {
+async function validateLink(page, link, baseUrl, validationBaseUrl, repoRoot, verbose = false, progress = "") {
   if (link.anchor) {
-    return await validateAnchor(page, link, baseUrl, repoRoot, verbose, progress);
+    return await validateAnchor(page, link, baseUrl, validationBaseUrl, repoRoot, verbose, progress);
   } else {
-    return await validateNormalLink(page, link, baseUrl, repoRoot, verbose, progress);
+    return await validateNormalLink(page, link, baseUrl, validationBaseUrl, repoRoot, verbose, progress);
   }
 }
 
-async function validateLinksAsync(links, baseUrl, repoRoot, concurrency, headless, verbose) {
+async function validateLinksAsync(links, baseUrl, validationBaseUrl, repoRoot, concurrency, headless, verbose) {
   const results = [];
 
   let browser;
@@ -670,7 +766,7 @@ async function validateLinksAsync(links, baseUrl, repoRoot, concurrency, headles
     const page = await context.newPage();
 
     try {
-      const result = await validateLink(page, link, baseUrl, repoRoot, verbose, progress);
+      const result = await validateLink(page, link, baseUrl, validationBaseUrl, repoRoot, verbose, progress);
       return result;
     } finally {
       await context.close();
@@ -1081,9 +1177,22 @@ export async function validateLinks(baseUrl, options) {
     console.log("\nValidating links...");
   }
 
+  // Normalize validation base URL
+  let normalizedValidationBaseUrl = options.validationBaseUrl || "http://localhost:3000";
+  if (!normalizedValidationBaseUrl.startsWith("http://") && !normalizedValidationBaseUrl.startsWith("https://")) {
+    normalizedValidationBaseUrl = "https://" + normalizedValidationBaseUrl;
+  }
+  // Remove trailing slash
+  normalizedValidationBaseUrl = normalizedValidationBaseUrl.replace(/\/+$/, "");
+
+  if (!options.quiet) {
+    console.log(`\nUsing validation base URL: ${normalizedValidationBaseUrl}`);
+  }
+
   const results = await validateLinksAsync(
     allLinks,
     normalizedBaseUrl,
+    normalizedValidationBaseUrl,
     repoRoot,
     parseInt(options.concurrency) || DEFAULT_CONCURRENCY,
     options.headless !== false,