@mintlify/cli 4.0.1743 → 4.0.1745

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

@@ -0,0 +1,130 @@
+import {
+  collectPatternNames,
+  collectExportedNames,
+  getAST,
+  isBuiltInComponent,
+  JSX_EXTENSIONS,
+  visitReferences,
+} from '@mintlify/common';
+import { visit } from 'unist-util-visit';
+
+import type { FileContext, FileRule, FileFinding } from '../../types.js';
+
+const getDeclared = (context: FileContext): Set<string> => {
+  const declared = new Set<string>();
+  visit(context.tree, 'mdxjsEsm', (node) => {
+    for (const statement of node.data?.estree?.body ?? []) {
+      if (statement.type === 'ImportDeclaration') {
+        for (const specifier of statement.specifiers) {
+          collectPatternNames(specifier.local, declared);
+        }
+      } else if (statement.type === 'ExportNamedDeclaration') {
+        const declaration = statement.declaration;
+        if (declaration?.type === 'VariableDeclaration') {
+          for (const declarator of declaration.declarations) {
+            collectPatternNames(declarator.id, declared);
+          }
+        } else if (declaration) {
+          collectPatternNames(declaration.id, declared);
+        }
+        for (const specifier of statement.specifiers) {
+          collectPatternNames(specifier.local, declared);
+          collectPatternNames(specifier.exported, declared);
+        }
+      } else if (statement.type === 'ExportDefaultDeclaration') {
+        const declaration = statement.declaration;
+        if (declaration.type === 'FunctionDeclaration' || declaration.type === 'ClassDeclaration') {
+          collectPatternNames(declaration.id, declared);
+        }
+      }
+    }
+  });
+  return declared;
+};
+
+const getImportPosition = (context: FileContext): number => {
+  const frontmatter = context.tree.children.find((child) => ['yaml', 'toml'].includes(child.type));
+  return frontmatter?.position?.end.offset ?? 0;
+};
+
+const getSpecifier = (snippet: string, file: string, name: string): string | undefined => {
+  let exported: Set<string>;
+  try {
+    exported = collectExportedNames(getAST(snippet, file));
+  } catch {
+    return undefined;
+  }
+  if (exported.has(name)) return `{ ${name} }`;
+  return exported.has('default') ? name : undefined;
+};
+
+export const unknownComponent: FileRule = {
+  id: 'unknown-component',
+  group: 'content',
+  severity: 'warning',
+  scope: 'file',
+  description: 'JSX components that are not built in, imported or exported',
+  pagesOnly: true,
+  check: (context) => {
+    const declared = getDeclared(context);
+    const reported = new Set<string>();
+    const issues: FileFinding[] = [];
+    const insertAt = getImportPosition(context);
+    const prefix = insertAt === 0 ? '' : '\n\n';
+    const following = /^\n*/.exec(context.content.slice(insertAt))?.[0].length ?? 0;
+    const suffix = '\n'.repeat(Math.max(0, 2 - following));
+
+    const check = (
+      tag: string | null | undefined,
+      position: { line?: number; column?: number } | undefined
+    ) => {
+      const name = tag?.split('.')[0];
+      if (!tag || !name || !/^[A-Z]/.test(name)) return;
+      if (declared.has(name) || reported.has(tag) || isBuiltInComponent(tag)) return;
+      reported.add(tag);
+
+      const file = JSX_EXTENSIONS.map((extension) => `snippets/${name}${extension}`).find(
+        (candidate) => context.readFile?.(candidate) !== undefined
+      );
+      const source = file && context.readFile?.(file);
+      const specifier =
+        file && source !== undefined && tag === name ? getSpecifier(source, file, name) : undefined;
+      issues.push({
+        line: position?.line,
+        column: position?.column,
+        message: `<${tag}> is not built in, imported or exported on this page`,
+        edit: specifier
+          ? {
+              start: insertAt,
+              end: insertAt,
+              text: `${prefix}import ${specifier} from "/${file}";${suffix}`,
+            }
+          : undefined,
+      });
+    };
+
+    const checkJsxInExpression = (estree: unknown, fallback?: { line?: number; column?: number }) =>
+      visitReferences(estree, new Set(), {
+        reference: (identifier) => {
+          if (identifier.type !== 'JSXIdentifier') return;
+          const loc = identifier.loc as { start?: { line: number; column: number } } | undefined;
+          check(String(identifier.name), loc?.start ?? fallback);
+        },
+      });
+
+    visit(context.tree, (node) => {
+      if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') {
+        check(node.name, node.position?.start);
+        for (const attribute of node.attributes) {
+          const value = attribute.type === 'mdxJsxAttribute' ? attribute.value : attribute;
+          if (value && typeof value === 'object') {
+            checkJsxInExpression(value.data?.estree, node.position?.start);
+          }
+        }
+      } else if (node.type === 'mdxFlowExpression' || node.type === 'mdxTextExpression') {
+        checkJsxInExpression(node.data?.estree, node.position?.start);
+      }
+    });
+    return issues;
+  },
+};

package/src/validate/rules/index.ts

@@ -1,7 +1,19 @@
 import type { Rule } from '../types.js';
 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 { unknownComponent } from './content/unknownComponent.js';
 import { voidTags } from './content/voidTags.js';
 import { openApiSpec } from './openapi.js';
 
 /** Every check mint validate runs, in report order. */
-export const RULES: Rule[] = [voidTags, openApiSpec, ...BUILD_RULES];
+export const RULES: Rule[] = [
+  voidTags,
+  duplicateH1,
+  unknownComponent,
+  katexRule,
+  foreignSyntax,
+  openApiSpec,
+  ...BUILD_RULES,
+];

package/src/validate/site.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
+import fs from 'node:fs';
 import path from 'node:path';
 
 import { readSiteFiles } from './files.js';
@@ -22,18 +22,18 @@ export const loadSite = async (
   { selected, localSchema }: { selected?: ReadonlySet<string>; localSchema: boolean }
 ): Promise<Site> => {
   const files = await readSiteFiles(baseDir);
-  const byPath = new Map<string, string>();
-  const configFile = existsSync(path.join(baseDir, 'docs.json')) ? 'docs.json' : 'mint.json';
+  const byPath = new Map<string, string | undefined>();
+  const configFile = fs.existsSync(path.join(baseDir, 'docs.json')) ? 'docs.json' : 'mint.json';
 
   const read = (file: string) => {
     if (!byPath.has(file)) {
       try {
-        byPath.set(file, readFileSync(path.join(baseDir, file), 'utf-8'));
+        byPath.set(file, fs.readFileSync(path.join(baseDir, file), 'utf-8'));
       } catch {
-        byPath.set(file, '');
+        byPath.set(file, undefined);
       }
     }
-    return byPath.get(file) ?? '';
+    return byPath.get(file);
   };
 
   return {
@@ -41,10 +41,11 @@ export const loadSite = async (
     files,
     selected,
     configFile,
-    variables: readVariables(read(configFile)),
+    variables: readVariables(read(configFile) ?? ''),
     localSchema,
+    read,
     locate: (file, text) => {
-      const content = read(file);
+      const content = read(file) ?? '';
       const offset = text ? content.indexOf(text) : -1;
       return offset === -1 ? {} : toPosition(content, offset);
     },

package/src/validate/types.ts

@@ -53,6 +53,8 @@ export type FileContext = {
   baseDir: string;
   frontmatter: Record<string, unknown>;
   tree: Root;
+  readFile?: (file: string) => string | undefined;
+  anchorLinks?: ReadonlySet<string>;
 };
 
 /** A finding in one file, with an optional edit against the content the rule saw. */
@@ -86,6 +88,7 @@ export type Site = {
   build?: BuildResult;
   /** The line and column of the first occurrence of text in a file. */
   locate: (file: string, text: string) => { line?: number; column?: number };
+  read: (file: string) => string | undefined;
   localSchema: boolean;
 };