@mintlify/cli 4.0.1477 → 4.0.1479

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1477",
+  "version": "4.0.1479",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -45,12 +45,12 @@
   },
   "dependencies": {
     "@inquirer/prompts": "7.9.0",
-    "@mintlify/common": "1.0.1130",
-    "@mintlify/link-rot": "3.0.1332",
-    "@mintlify/models": "0.0.352",
-    "@mintlify/prebuild": "1.0.1284",
-    "@mintlify/previewing": "4.0.1356",
-    "@mintlify/validation": "0.1.847",
+    "@mintlify/common": "1.0.1132",
+    "@mintlify/link-rot": "3.0.1334",
+    "@mintlify/models": "0.0.353",
+    "@mintlify/prebuild": "1.0.1286",
+    "@mintlify/previewing": "4.0.1358",
+    "@mintlify/validation": "0.1.849",
     "adm-zip": "0.6.0",
     "chalk": "5.2.0",
     "color": "4.2.3",
@@ -86,7 +86,7 @@
     "keytar": "7.9.0"
   },
   "devDependencies": {
-    "@mintlify/editor": "0.0.361",
+    "@mintlify/editor": "0.0.363",
     "@mintlify/ts-config": "2.0.2",
     "@tsconfig/recommended": "1.0.2",
     "@types/detect-port": "1.3.2",
@@ -105,5 +105,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "5af8270e14b6c226994968ae107b2513882b9729"
+  "gitHead": "64f3cb09194b3f7a7259c9a08c4e47b7454bf9e9"
 }

package/src/cli.tsx

@@ -45,7 +45,11 @@ import { logout } from './logout.js';
 import { mdxLinter } from './mdxLinter.js';
 import { createTelemetryMiddleware } from './middlewares/telemetryMiddleware.js';
 import { mintTestHandler } from './mintTest.js';
-import { checkOpenApiFile, getOpenApiFilenamesFromDocsConfig } from './openApiCheck.js';
+import {
+  buildOverlayRegistryForCheck,
+  checkOpenApiFile,
+  getOpenApiFilenamesFromDocsConfig,
+} from './openApiCheck.js';
 import { resolveExplicitFiles } from './resolveFiles.js';
 import { scoreHandler } from './score/index.js';
 import { signup } from './signup.js';
@@ -225,8 +229,18 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
               openApiFilenames = getOpenApiFilenamesFromDocsConfig(JSON.parse(docsJson));
             } catch {}
 
+            let overlayRegistry;
+            try {
+              overlayRegistry = await buildOverlayRegistryForCheck(argv['local-schema']);
+            } catch (error) {
+              addLog(<ErrorLog message={error instanceof Error ? error.message : String(error)} />);
+              await terminate(1);
+              return;
+            }
             const results = await Promise.all(
-              openApiFilenames.map((file) => checkOpenApiFile(file, argv['local-schema']))
+              openApiFilenames.map((file) =>
+                checkOpenApiFile(file, argv['local-schema'], overlayRegistry)
+              )
             );
 
             if (results.some((valid) => !valid)) {
@@ -308,7 +322,15 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
           addLog(
             <WarningLog message="openapi-check is deprecated, use `mintlify validate` instead" />
           );
-          const valid = await checkOpenApiFile(filename, localSchema);
+          let overlayRegistry;
+          try {
+            overlayRegistry = await buildOverlayRegistryForCheck(localSchema);
+          } catch (error) {
+            addLog(<ErrorLog message={error instanceof Error ? error.message : String(error)} />);
+            await terminate(1);
+            return;
+          }
+          const valid = await checkOpenApiFile(filename, localSchema, overlayRegistry);
           await terminate(valid ? 0 : 1);
         }
       )

package/src/openApiCheck.tsx

@@ -1,24 +1,75 @@
-import { validate, getOpenApiDocumentFromUrl, isAllowedLocalSchemaUrl } from '@mintlify/common';
+import {
+  applyOverlays,
+  createOverlayRegistry,
+  getOpenApiDocumentFromUrl,
+  isAllowedLocalSchemaUrl,
+  resolveOverlaysForSpec,
+  validate,
+  type OverlayRegistry,
+} from '@mintlify/common';
+import { discoverOverlayFiles, getMintIgnore, resolveFileRefs } from '@mintlify/prebuild';
 import { addLog, ErrorLog, SuccessLog, WarningLog } from '@mintlify/previewing';
-import type { DocsConfig } from '@mintlify/validation';
+import {
+  collectOpenApiOverlayConfig,
+  extractOpenApiEntries,
+  type DocsConfig,
+} from '@mintlify/validation';
+import { promises as fs } from 'fs';
+import path from 'path';
 
-import { readLocalOpenApiFile } from './helpers.js';
+import { CMD_EXEC_PATH, readLocalOpenApiFile } from './helpers.js';
 
 export const getOpenApiFilenamesFromDocsConfig = (config: Pick<DocsConfig, 'api'>): string[] => {
-  const openapi = config.api?.openapi;
-  if (openapi === undefined) return [];
-  if (typeof openapi === 'string') return [openapi];
-  if (Array.isArray(openapi)) return openapi;
-  return [openapi.source];
+  return extractOpenApiEntries(config.api?.openapi).map((entry) => entry.source);
+};
+
+/**
+ * Builds the overlay registry so checks validate specs with overlays applied.
+ * Throws when docs.json configures conflicting overlay lists, matching the build.
+ */
+export const buildOverlayRegistryForCheck = async (
+  localSchema?: boolean
+): Promise<OverlayRegistry | undefined> => {
+  // Discovery failures propagate and fail the check: silently skipping overlays would
+  // validate a different document than the one the build produces.
+  const mintIgnore = await getMintIgnore(CMD_EXEC_PATH);
+  const discovered = await discoverOverlayFiles(CMD_EXEC_PATH, mintIgnore);
+
+  let rawConfig: unknown;
+  try {
+    rawConfig = JSON.parse(await fs.readFile(path.join(CMD_EXEC_PATH, 'docs.json'), 'utf-8'));
+  } catch {
+    rawConfig = undefined;
+  }
+  if (rawConfig !== undefined) {
+    try {
+      rawConfig = (await resolveFileRefs(rawConfig, CMD_EXEC_PATH)).resolved;
+    } catch {
+      // Broken $refs are reported by regular config validation; collect from the root file.
+    }
+  }
+  const explicit = rawConfig == undefined ? undefined : collectOpenApiOverlayConfig(rawConfig);
+
+  if (explicit == undefined && discovered.length === 0) return undefined;
+
+  return createOverlayRegistry({
+    explicit,
+    discovered,
+    localSchema,
+    loadLocalDocument: (normalizedPath) => readLocalOpenApiFile(normalizedPath),
+  });
 };
 
 export const checkOpenApiFile = async (
   filename: string,
-  localSchema: boolean
+  localSchema: boolean,
+  overlayRegistry?: OverlayRegistry
 ): Promise<boolean> => {
   try {
+    const overlays = overlayRegistry ? await resolveOverlaysForSpec(overlayRegistry, filename) : [];
+
     if (isAllowedLocalSchemaUrl(filename, localSchema)) {
-      await getOpenApiDocumentFromUrl(filename);
+      await getOpenApiDocumentFromUrl(filename, { overlays });
       addLog(<SuccessLog message="OpenAPI definition is valid." />);
       return true;
     }
@@ -37,7 +88,11 @@ export const checkOpenApiFile = async (
         'failed to parse OpenAPI spec: could not parse file correctly, please check for any syntax errors.'
       );
     }
-    await validate(document);
+    const overlaid: unknown = overlays.length > 0 ? applyOverlays(document, overlays) : document;
+    if (overlaid == undefined || typeof overlaid !== 'object') {
+      throw new Error('applying overlays produced an invalid OpenAPI document.');
+    }
+    await validate(overlaid);
     addLog(<SuccessLog message="OpenAPI definition is valid." />);
     return true;
   } catch (err) {