@mintlify/cli 4.0.1800 → 4.0.1801

package/bin/validate/files.js

@@ -106,7 +106,14 @@ const checkFile = (allRules, { file, kind }, content, baseDir, extras, variables
     const treeRules = rules.filter((rule) => !rule.raw);
     const varEdits = kind === 'snippet' ? variableEdits(content, variables) : [];
     const source = applyEdits(content, varEdits);
-    const rawContext = { file, content: source, baseDir, frontmatter: {}, tree: EMPTY_TREE };
+    const rawContext = {
+        file,
+        content: source,
+        baseDir,
+        frontmatter: {},
+        tree: EMPTY_TREE,
+        variables,
+    };
     const rawFound = raw.flatMap((rule) => rule.check(rawContext).map((finding) => ({ rule, finding })));
     const rawEdits = selectEdits(rawFound.flatMap(({ finding }) => (finding.edit ? [finding.edit] : [])));
     const afterRaw = applyEdits(source, rawEdits);
@@ -116,7 +123,7 @@ const checkFile = (allRules, { file, kind }, content, baseDir, extras, variables
         { content: afterRaw, edits: [] },
     ];
     const diagnostics = rawFound.map(({ rule, finding }) => toDiagnostic(rule, file, finding, stages, SOURCE_STAGE));
-    const parsed = parseFile(file, afterRaw, baseDir, extras);
+    const parsed = parseFile(file, afterRaw, baseDir, Object.assign(Object.assign({}, extras), { variables }));
     if ('error' in parsed) {
         diagnostics.unshift(parseErrorDiagnostic(file, Object.assign(Object.assign({}, parsed.error), relocate(stages, AFTER_RAW_STAGE, parsed.error))));
         return diagnostics;

package/bin/validate/rules/content/missingSnippet.js

@@ -0,0 +1,34 @@
+import { replaceVariables } from '@mintlify/common';
+import { visit } from 'unist-util-visit';
+const exists = (file, readFile) => !file.startsWith('/') &&
+    (readFile(`_snippets/${file}`) !== undefined ||
+        (file.startsWith('snippets/') && readFile(file) !== undefined));
+export const missingSnippet = {
+    id: 'missing-snippet',
+    group: 'content',
+    severity: 'error',
+    scope: 'file',
+    description: '<Snippet file> tags whose file the build cannot find',
+    check: ({ tree, readFile, variables }) => {
+        if (!readFile)
+            return [];
+        const issues = [];
+        visit(tree, 'mdxJsxFlowElement', (node) => {
+            var _a, _b, _c;
+            if (node.name !== 'Snippet')
+                return;
+            const value = (_a = node.attributes.find((attribute) => attribute.type === 'mdxJsxAttribute' && attribute.name === 'file')) === null || _a === void 0 ? void 0 : _a.value;
+            if (typeof value !== 'string')
+                return;
+            const file = replaceVariables(value, variables);
+            if (exists(file, readFile))
+                return;
+            issues.push({
+                line: (_b = node.position) === null || _b === void 0 ? void 0 : _b.start.line,
+                column: (_c = node.position) === null || _c === void 0 ? void 0 : _c.start.column,
+                message: `<Snippet file="${value}"> renders nothing: no snippet matches "${file}"`,
+            });
+        });
+        return issues;
+    },
+};

package/bin/validate/rules/content/undefinedVariable.js

@@ -0,0 +1,13 @@
+import { maskCode, toPosition } from '../../mdx.js';
+const VARIABLE = /(?<!=\s*)\{\{\s*([\w.\-]+)\s*\}\}/g;
+export const undefinedVariable = {
+    id: 'undefined-variable',
+    group: 'content',
+    severity: 'error',
+    scope: 'file',
+    description: '{{variables}} that docs.json does not define',
+    raw: true,
+    check: ({ content, variables = {} }) => [...maskCode(content).matchAll(VARIABLE)]
+        .filter(([, name]) => name !== undefined && variables[name] === undefined)
+        .map((match) => (Object.assign(Object.assign({}, toPosition(content, match.index)), { message: `{{${match[1]}}} is not defined in the variables of docs.json` }))),
+};

package/bin/validate/rules/content/unknownComponent.js

@@ -55,7 +55,7 @@ const getSpecifier = (snippet, file, name) => {
 export const unknownComponent = {
     id: 'unknown-component',
     group: 'content',
-    severity: 'warning',
+    severity: 'error',
     scope: 'file',
     description: 'JSX components that are not built in, imported or exported',
     pagesOnly: true,

package/bin/validate/rules/index.js

@@ -2,6 +2,8 @@ import { BUILD_RULES } from './build.js';
 import { duplicateH1 } from './content/duplicateH1.js';
 import { foreignSyntax } from './content/foreignSyntax.js';
 import { katexRule } from './content/katex.js';
+import { missingSnippet } from './content/missingSnippet.js';
+import { undefinedVariable } from './content/undefinedVariable.js';
 import { unknownComponent } from './content/unknownComponent.js';
 import { voidTags } from './content/voidTags.js';
 import { openApiSpec } from './openapi.js';
@@ -10,6 +12,8 @@ export const RULES = [
     voidTags,
     duplicateH1,
     unknownComponent,
+    undefinedVariable,
+    missingSnippet,
     katexRule,
     foreignSyntax,
     openApiSpec,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.1800",
+  "version": "4.0.1801",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -106,5 +106,5 @@
     "vitest": "2.1.9",
     "vitest-mock-process": "1.0.4"
   },
-  "gitHead": "36ff9bdfc06d97ff1bc0d958a8119db486ff46ae"
+  "gitHead": "a0659a2c5d82fe76a703396ea3f4c51d25526599"
 }

package/src/validate/files.ts

@@ -89,7 +89,7 @@ export const toParseError = (error: unknown, content = ''): ParseError => {
   };
 };
 
-type Extras = Pick<FileContext, 'readFile' | 'anchorLinks'>;
+type Extras = Pick<FileContext, 'readFile' | 'anchorLinks' | 'variables'>;
 
 const parseErrorDiagnostic = (file: string, error: ParseError): Diagnostic => ({
   ...error,
@@ -176,7 +176,14 @@ const checkFile = (
   const treeRules = rules.filter((rule) => !rule.raw);
   const varEdits = kind === 'snippet' ? variableEdits(content, variables) : [];
   const source = applyEdits(content, varEdits);
-  const rawContext = { file, content: source, baseDir, frontmatter: {}, tree: EMPTY_TREE };
+  const rawContext = {
+    file,
+    content: source,
+    baseDir,
+    frontmatter: {},
+    tree: EMPTY_TREE,
+    variables,
+  };
 
   const rawFound = raw.flatMap((rule) =>
     rule.check(rawContext).map((finding) => ({ rule, finding }))
@@ -194,7 +201,7 @@ const checkFile = (
     toDiagnostic(rule, file, finding, stages, SOURCE_STAGE)
   );
 
-  const parsed = parseFile(file, afterRaw, baseDir, extras);
+  const parsed = parseFile(file, afterRaw, baseDir, { ...extras, variables });
   if ('error' in parsed) {
     diagnostics.unshift(
       parseErrorDiagnostic(file, {

package/src/validate/rules/content/missingSnippet.ts

@@ -0,0 +1,36 @@
+import { replaceVariables } from '@mintlify/common';
+import { visit } from 'unist-util-visit';
+
+import type { FileFinding, FileRule } from '../../types.js';
+
+const exists = (file: string, readFile: (file: string) => string | undefined) =>
+  !file.startsWith('/') &&
+  (readFile(`_snippets/${file}`) !== undefined ||
+    (file.startsWith('snippets/') && readFile(file) !== undefined));
+
+export const missingSnippet: FileRule = {
+  id: 'missing-snippet',
+  group: 'content',
+  severity: 'error',
+  scope: 'file',
+  description: '<Snippet file> tags whose file the build cannot find',
+  check: ({ tree, readFile, variables }) => {
+    if (!readFile) return [];
+    const issues: FileFinding[] = [];
+    visit(tree, 'mdxJsxFlowElement', (node) => {
+      if (node.name !== 'Snippet') return;
+      const value = node.attributes.find(
+        (attribute) => attribute.type === 'mdxJsxAttribute' && attribute.name === 'file'
+      )?.value;
+      if (typeof value !== 'string') return;
+      const file = replaceVariables(value, variables);
+      if (exists(file, readFile)) return;
+      issues.push({
+        line: node.position?.start.line,
+        column: node.position?.start.column,
+        message: `<Snippet file="${value}"> renders nothing: no snippet matches "${file}"`,
+      });
+    });
+    return issues;
+  },
+};

package/src/validate/rules/content/undefinedVariable.ts

@@ -0,0 +1,20 @@
+import { maskCode, toPosition } from '../../mdx.js';
+import type { FileRule } from '../../types.js';
+
+const VARIABLE = /(?<!=\s*)\{\{\s*([\w.\-]+)\s*\}\}/g;
+
+export const undefinedVariable: FileRule = {
+  id: 'undefined-variable',
+  group: 'content',
+  severity: 'error',
+  scope: 'file',
+  description: '{{variables}} that docs.json does not define',
+  raw: true,
+  check: ({ content, variables = {} }) =>
+    [...maskCode(content).matchAll(VARIABLE)]
+      .filter(([, name]) => name !== undefined && variables[name] === undefined)
+      .map((match) => ({
+        ...toPosition(content, match.index),
+        message: `{{${match[1]}}} is not defined in the variables of docs.json`,
+      })),
+};

package/src/validate/rules/content/unknownComponent.ts

@@ -61,7 +61,7 @@ const getSpecifier = (snippet: string, file: string, name: string): string | und
 export const unknownComponent: FileRule = {
   id: 'unknown-component',
   group: 'content',
-  severity: 'warning',
+  severity: 'error',
   scope: 'file',
   description: 'JSX components that are not built in, imported or exported',
   pagesOnly: true,

package/src/validate/rules/index.ts

@@ -3,6 +3,8 @@ import { BUILD_RULES } from './build.js';
 import { duplicateH1 } from './content/duplicateH1.js';
 import { foreignSyntax } from './content/foreignSyntax.js';
 import { katexRule } from './content/katex.js';
+import { missingSnippet } from './content/missingSnippet.js';
+import { undefinedVariable } from './content/undefinedVariable.js';
 import { unknownComponent } from './content/unknownComponent.js';
 import { voidTags } from './content/voidTags.js';
 import { openApiSpec } from './openapi.js';
@@ -12,6 +14,8 @@ export const RULES: Rule[] = [
   voidTags,
   duplicateH1,
   unknownComponent,
+  undefinedVariable,
+  missingSnippet,
   katexRule,
   foreignSyntax,
   openApiSpec,

package/src/validate/types.ts

@@ -55,6 +55,7 @@ export type FileContext = {
   tree: Root;
   readFile?: (file: string) => string | undefined;
   anchorLinks?: ReadonlySet<string>;
+  variables?: Record<string, string>;
 };
 
 /** A finding in one file, with an optional edit against the content the rule saw. */