@mintlify/cli 4.0.1338 → 4.0.1340

package/__test__/brokenLinks.test.ts

@@ -1,9 +1,11 @@
 import { buildGraph, getBrokenExternalLinks } from '@mintlify/link-rot';
 import { MdxPath } from '@mintlify/link-rot/dist/graph.js';
 import { addLog, clearLogs } from '@mintlify/previewing';
+import path from 'node:path';
 import { mockProcessExit } from 'vitest-mock-process';
 
-import { checkForMintJson } from '../src/helpers.js';
+import { resolveExplicitFiles } from '../src/deslop/resolveFiles.js';
+import { checkForMintJson, CMD_EXEC_PATH } from '../src/helpers.js';
 import { runCommand } from './utils.js';
 
 vi.mock('@mintlify/previewing', async (importOriginal) => {
@@ -19,6 +21,11 @@ vi.mock('../src/helpers.js', async (importOriginal) => {
   };
 });
 
+vi.mock('../src/deslop/resolveFiles.js', () => ({
+  resolveChangedFiles: vi.fn(),
+  resolveExplicitFiles: vi.fn(),
+}));
+
 const mockGraph = {
   precomputeFileResolutions: vi.fn(),
   getBrokenInternalLinks: vi.fn().mockReturnValue([]),
@@ -42,6 +49,7 @@ describe('brokenLinks', () => {
   beforeEach(() => {
     vi.clearAllMocks();
     vi.mocked(buildGraph).mockResolvedValue(mockGraph as never);
+    vi.mocked(resolveExplicitFiles).mockResolvedValue([]);
     mockGraph.getBrokenInternalLinks.mockReturnValue([]);
   });
 
@@ -94,6 +102,42 @@ describe('brokenLinks', () => {
     expect(processExitMock).toHaveBeenCalledWith(1);
   });
 
+  it('checks only files matching the provided option', async () => {
+    vi.mocked(checkForMintJson).mockResolvedValueOnce(true);
+    vi.mocked(resolveExplicitFiles).mockResolvedValueOnce(['guides/selected.mdx']);
+    mockGraph.getBrokenInternalLinks.mockReturnValue([
+      {
+        relativeDir: 'guides',
+        filename: 'selected.mdx',
+        originalPath: '/api/selected-invalid',
+        pathType: 'internal',
+      } as MdxPath,
+      {
+        relativeDir: 'guides',
+        filename: 'other.mdx',
+        originalPath: '/api/other-invalid',
+        pathType: 'internal',
+      } as MdxPath,
+    ]);
+
+    await runCommand('broken-links', '--files', 'guides/selected.mdx', 'guides/**/*.mdx');
+
+    expect(resolveExplicitFiles).toHaveBeenCalledWith(CMD_EXEC_PATH, [
+      'guides/selected.mdx',
+      'guides/**/*.mdx',
+    ]);
+    expect(addLogSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        props: {
+          brokenLinksByFile: {
+            [path.join('guides', 'selected.mdx')]: ['/api/selected-invalid'],
+          },
+        },
+      })
+    );
+    expect(processExitMock).toHaveBeenCalledWith(1);
+  });
+
   it('fails when checking throws error', async () => {
     vi.mocked(checkForMintJson).mockResolvedValueOnce(true);
     vi.mocked(buildGraph).mockRejectedValueOnce(new Error('some error'));
@@ -118,6 +162,7 @@ describe('brokenLinks --check-external', () => {
   beforeEach(() => {
     vi.clearAllMocks();
     vi.mocked(buildGraph).mockResolvedValue(mockGraph as never);
+    vi.mocked(resolveExplicitFiles).mockResolvedValue([]);
     mockGraph.getBrokenInternalLinks.mockReturnValue([]);
   });
 
@@ -160,6 +205,19 @@ describe('brokenLinks --check-external', () => {
     expect(processExitMock).toHaveBeenCalledWith(1);
   });
 
+  it('checks external links only from matching files', async () => {
+    vi.mocked(checkForMintJson).mockResolvedValueOnce(true);
+    vi.mocked(resolveExplicitFiles).mockResolvedValueOnce(['selected.mdx']);
+    vi.mocked(getBrokenExternalLinks).mockResolvedValueOnce([]);
+
+    await runCommand('broken-links', '--files', 'selected.mdx', '--check-external');
+
+    expect(getBrokenExternalLinks).toHaveBeenCalledWith(mockGraph, {
+      sourceFiles: new Set(['selected.mdx']),
+    });
+    expect(processExitMock).toHaveBeenCalledWith(0);
+  });
+
   it('fails when external link checking throws error', async () => {
     vi.mocked(checkForMintJson).mockResolvedValueOnce(true);
     vi.mocked(getBrokenExternalLinks).mockRejectedValueOnce(new Error('network error'));

package/bin/cli.js

@@ -21,6 +21,8 @@ import { setTelemetryEnabled } from './config.js';
 import { getConfigValue, setConfigValue, clearConfigValue } from './config.js';
 import { API_URL } from './constants.js';
 import { deslopHandler } from './deslop/index.js';
+import { resolveExplicitFiles } from './deslop/resolveFiles.js';
+import { formatHandler } from './format.js';
 import { CMD_EXEC_PATH, checkPort, checkNodeVersion, autoUpgradeIfNeeded, getVersions, isAI, suppressConsoleWarnings, terminate, } from './helpers.js';
 import { init } from './init.js';
 import { getAccessToken } from './keyring.js';
@@ -232,6 +234,11 @@ export const cli = ({ packageName = 'mint' }) => {
         yield terminate(valid ? 0 : 1);
     }))
         .command('broken-links', 'Check for broken links', (yargs) => yargs
+        .option('files', {
+        type: 'string',
+        array: true,
+        description: 'Files or globs to check (defaults to the whole site)',
+    })
         .option('check-anchors', {
         type: 'boolean',
         default: false,
@@ -251,17 +258,26 @@ export const cli = ({ packageName = 'mint' }) => {
         type: 'boolean',
         default: false,
         description: 'also check that docs.json redirect destinations resolve to valid paths',
-    }), (argv) => __awaiter(void 0, void 0, void 0, function* () {
+    })
+        .example('mint broken-links --files introduction.mdx', 'Check a specific page')
+        .example('mint broken-links --files "guides/**/*.mdx"', 'Check pages matching a glob'), (argv) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a;
         yield autoUpgradeIfNeeded();
         addLog(_jsx(SpinnerLog, { message: "checking for broken links..." }));
         try {
+            const fileArgs = ((_a = argv.files) !== null && _a !== void 0 ? _a : []).map(String).filter(Boolean);
+            const sourceFiles = fileArgs.length > 0
+                ? new Set((yield resolveExplicitFiles(CMD_EXEC_PATH, fileArgs)).map((file) => path.normalize(file)))
+                : undefined;
             const graph = yield buildGraph(undefined, {
                 checkSnippets: argv['check-snippets'],
             });
             graph.precomputeFileResolutions();
-            const brokenInternalLinks = graph.getBrokenInternalLinks({
+            const brokenInternalLinks = graph
+                .getBrokenInternalLinks({
                 checkAnchors: argv['check-anchors'],
-            });
+            })
+                .filter(({ relativeDir, filename }) => !sourceFiles || sourceFiles.has(path.join(relativeDir, filename)));
             const brokenLinksByFile = {};
             brokenInternalLinks.forEach((mdxPath) => {
                 const filename = path.join(mdxPath.relativeDir, mdxPath.filename);
@@ -274,7 +290,7 @@ export const cli = ({ packageName = 'mint' }) => {
                 }
             });
             if (argv['check-external']) {
-                const brokenExternalLinks = yield getBrokenExternalLinks(graph);
+                const brokenExternalLinks = yield getBrokenExternalLinks(graph, sourceFiles ? { sourceFiles } : undefined);
                 for (const result of brokenExternalLinks) {
                     for (const source of result.sources) {
                         const label = result.status
@@ -522,6 +538,9 @@ export const cli = ({ packageName = 'mint' }) => {
         .example('mint deslop', 'Check git-changed pages for AI-sounding prose')
         .example('mint deslop docs/guide.mdx', 'Check a specific page')
         .example('mint deslop "docs/**/*.mdx" --format json', 'Check pages by glob with agent-friendly JSON output'), deslopHandler)
+        .command('format', 'Format MDX files in the current directory', (yargs) => yargs
+        .usage('usage: mint format')
+        .example('mint format', 'format all MDX files in the current directory'), formatHandler)
         // Coming soon commands — visible in help, tracked via telemetry to gauge interest.
         .command('ai', '[Coming soon] AI-powered documentation (run mint ai to vote)', () => undefined, comingSoon('ai', packageName))
         .command('test', '[Coming soon] Test your documentation (run mint test to vote)', () => undefined, comingSoon('test', packageName))

package/bin/format.js

@@ -0,0 +1,110 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __asyncDelegator = (this && this.__asyncDelegator) || function (o) {
+    var i, p;
+    return i = {}, verb("next"), verb("throw", function (e) { throw e; }), verb("return"), i[Symbol.iterator] = function () { return this; }, i;
+    function verb(n, f) { i[n] = o[n] ? function (v) { return (p = !p) ? { value: __await(o[n](v)), done: false } : f ? f(v) : v; } : f; }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+import { jsx as _jsx } from "react/jsx-runtime";
+import { isMintIgnored, processMintIgnoreString } from '@mintlify/common';
+import { getMintIgnore } from '@mintlify/prebuild';
+import { addLog, ErrorLog, SuccessLog } from '@mintlify/previewing';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { CMD_EXEC_PATH, terminate } from './helpers.js';
+function getGitIgnore() {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const content = yield fs.readFile(path.join(CMD_EXEC_PATH, '.gitignore'), 'utf-8');
+            return processMintIgnoreString(content);
+        }
+        catch (_a) {
+            return [];
+        }
+    });
+}
+function walk(dir, ignores) {
+    return __asyncGenerator(this, arguments, function* walk_1() {
+        const entries = yield __await(fs.readdir(dir, { withFileTypes: true }));
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            const relative = path.relative(CMD_EXEC_PATH, full).split(path.sep).join('/');
+            if (entry.isDirectory()) {
+                if (isMintIgnored(`${relative}/`, ignores))
+                    continue;
+                yield __await(yield* __asyncDelegator(__asyncValues(walk(full, ignores))));
+            }
+            else if (entry.name.endsWith('.mdx')) {
+                if (isMintIgnored(relative, ignores))
+                    continue;
+                yield yield __await(full);
+            }
+        }
+    });
+}
+export const formatHandler = () => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, e_1, _b, _c;
+    const { mdxToPm, pmToMdx } = yield import('./vendor/converter.js');
+    const ignores = [...(yield getGitIgnore()), ...(yield getMintIgnore(CMD_EXEC_PATH))];
+    let total = 0;
+    let changed = 0;
+    let failed = 0;
+    try {
+        for (var _d = true, _e = __asyncValues(walk(CMD_EXEC_PATH, ignores)), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
+            _c = _f.value;
+            _d = false;
+            const file = _c;
+            total++;
+            const relative = path.relative(CMD_EXEC_PATH, file);
+            try {
+                const raw = yield fs.readFile(file, 'utf-8');
+                const { doc, frontmatter } = mdxToPm(raw, { singleDollarTextMath: false });
+                const formatted = `${pmToMdx(doc, { frontmatter })}\n`;
+                if (formatted !== raw) {
+                    yield fs.writeFile(file, formatted);
+                    changed++;
+                }
+            }
+            catch (error) {
+                failed++;
+                addLog(_jsx(ErrorLog, { message: `${relative}: ${error instanceof Error ? error.message : 'unknown error'}` }));
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (!_d && !_a && (_b = _e.return)) yield _b.call(_e);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    addLog(_jsx(SuccessLog, { message: `formatted ${changed} of ${total} mdx file${total === 1 ? '' : 's'}${failed > 0 ? ` (${failed} failed)` : ''}` }));
+    yield terminate(failed > 0 ? 1 : 0);
+});