@mintlify/cli 4.0.1732 → 4.0.1734

package/src/validate/output.tsx

@@ -0,0 +1,56 @@
+import { addLog, ErrorLog } from '@mintlify/previewing';
+import { Box, Text } from 'ink';
+
+import type { Diagnostic } from './types.js';
+
+const location = ({ line, column }: Pick<Diagnostic, 'line' | 'column'>) =>
+  line ? `${line}${column ? `:${column}` : ''}` : '';
+
+const DiagnosticLine = ({ diagnostic }: { diagnostic: Diagnostic }) => {
+  const at = location(diagnostic);
+  return (
+    <Text>
+      {'  '}
+      {diagnostic.severity === 'error' ? (
+        <Text color="red">✗</Text>
+      ) : (
+        <Text color="yellow">!</Text>
+      )}{' '}
+      {at && <Text dimColor>{at} </Text>}
+      <Text dimColor>{diagnostic.rule}</Text> {diagnostic.message}
+      {diagnostic.fix && <Text dimColor> (fixable)</Text>}
+    </Text>
+  );
+};
+
+const plural = (count: number, word: string) => `${count} ${word}${count === 1 ? '' : 's'}`;
+
+export const logDiagnostics = (all: Diagnostic[]) => {
+  const byFile = new Map<string, Diagnostic[]>();
+  for (const diagnostic of all) {
+    byFile.get(diagnostic.file)?.push(diagnostic) ?? byFile.set(diagnostic.file, [diagnostic]);
+  }
+  for (const [file, diagnostics] of byFile) {
+    addLog(
+      <Box flexDirection="column">
+        <Text bold>{file}</Text>
+        {diagnostics.map((diagnostic, index) => (
+          <DiagnosticLine key={index} diagnostic={diagnostic} />
+        ))}
+      </Box>
+    );
+  }
+
+  const errors = all.filter(({ severity }) => severity === 'error').length;
+  const warnings = all.length - errors;
+  if (errors > 0) {
+    addLog(
+      <ErrorLog
+        message={`${plural(errors, 'error')}${warnings > 0 ? `, ${plural(warnings, 'warning')}` : ''}`}
+      />
+    );
+  } else if (warnings > 0) {
+    addLog(<Text dimColor>{plural(warnings, 'warning')}</Text>);
+  }
+  return errors > 0;
+};

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

@@ -0,0 +1,35 @@
+import { maskNonMarkup } from '../../mdx.js';
+import type { FileRule, FileFinding } from '../../types.js';
+
+const VOID_TAG = /<(br|hr|img)(?=[\s/>])((?:"[^"]*"|'[^']*'|\{[^{}]*\}|[^<>"'{}])*?)(\/?)>/g;
+
+export const voidTags: FileRule = {
+  id: 'void-tags',
+  group: 'content',
+  severity: 'error',
+  scope: 'file',
+  description: "self-close void HTML tags (<br>, <hr>, <img>); MDX can't parse them unclosed",
+  raw: true,
+  check: ({ content }) => {
+    const masked = maskNonMarkup(content);
+    const issues: FileFinding[] = [];
+    for (const match of masked.matchAll(VOID_TAG)) {
+      if (match[3]) continue;
+      const start = match.index;
+      const end = start + match[0].length;
+      if (new RegExp(`^\\s*</${match[1]}\\s*>`).test(masked.slice(end))) continue;
+      const before = content.slice(0, start).split('\n');
+      issues.push({
+        line: before.length,
+        column: (before.pop()?.length ?? 0) + 1,
+        message: `<${match[1]}> must be self-closed`,
+        edit: {
+          start,
+          end,
+          text: `${content.slice(start, end - 1).trimEnd()} />`,
+        },
+      });
+    }
+    return issues;
+  },
+};

package/src/validate/rules/index.ts

@@ -0,0 +1,5 @@
+import type { Rule } from '../types.js';
+import { voidTags } from './content/voidTags.js';
+
+/** Every check mint validate runs, in report order. */
+export const RULES: Rule[] = [voidTags];

package/src/validate/rules/parseError.ts

@@ -0,0 +1,9 @@
+import type { DiagnosticSource } from '../types.js';
+
+/** The engine's built-in diagnostic for files neither parser can parse; not a selectable rule. */
+export const PARSE_ERROR: DiagnosticSource = {
+  id: 'parse-error',
+  group: 'content',
+  severity: 'error',
+  description: "files MDX can't parse; other checks skip them",
+};

package/src/validate/site.ts

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { readSiteFiles } from './files.js';
+import { toPosition } from './mdx.js';
+import type { Site } from './types.js';
+
+const readVariables = (config: string): Record<string, string> | undefined => {
+  try {
+    const { variables } = JSON.parse(config) as { variables?: unknown };
+    return variables && typeof variables === 'object'
+      ? (variables as Record<string, string>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/** Lists the site's pages and snippets; locate reads files from disk on demand. */
+export const loadSite = async (
+  baseDir: string,
+  { 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 read = (file: string) => {
+    if (!byPath.has(file)) {
+      try {
+        byPath.set(file, readFileSync(path.join(baseDir, file), 'utf-8'));
+      } catch {
+        byPath.set(file, '');
+      }
+    }
+    return byPath.get(file) ?? '';
+  };
+
+  return {
+    baseDir,
+    files,
+    selected,
+    configFile,
+    variables: readVariables(read(configFile)),
+    localSchema,
+    locate: (file, text) => {
+      const content = read(file);
+      const offset = text ? content.indexOf(text) : -1;
+      return offset === -1 ? {} : toPosition(content, offset);
+    },
+  };
+};

package/src/validate/types.ts

@@ -0,0 +1,88 @@
+import type { BuildValidationResult } from '@mintlify/previewing';
+import type { Root } from 'mdast';
+
+export type Group = 'content' | 'nav' | 'config' | 'openapi';
+
+export const GROUPS: Group[] = ['content', 'nav', 'config', 'openapi'];
+
+export type Severity = 'error' | 'warning';
+
+export type Edit = { start: number; end: number; text: string };
+
+export type FileEdit = Edit & { file: string };
+
+export type Diagnostic = {
+  rule: string;
+  group: Group;
+  severity: Severity;
+  file: string;
+  line?: number;
+  column?: number;
+  message: string;
+  fix?: FileEdit;
+};
+
+/** What a rule reports; the engine adds its id and group, and its severity unless overridden. */
+export type Finding = Omit<Diagnostic, 'rule' | 'group' | 'severity'> & { severity?: Severity };
+
+type RuleMeta = {
+  id: string;
+  group: Group;
+  severity: Severity;
+  needsBuild?: boolean;
+  description: string;
+};
+
+export type DiagnosticSource = Pick<RuleMeta, 'id' | 'group' | 'severity' | 'description'>;
+
+export type FileKind = 'page' | 'snippet';
+
+export type FileContext = {
+  file: string;
+  content: string;
+  baseDir: string;
+  frontmatter: Record<string, unknown>;
+  tree: Root;
+};
+
+/** A finding in one file, with an optional edit against the content the rule saw. */
+export type FileFinding = {
+  line?: number;
+  column?: number;
+  message: string;
+  edit?: Edit;
+};
+
+/** Checks one page or snippet at a time. Raw rules read text; the rest also get the MDX tree. */
+export type FileRule = RuleMeta & {
+  scope: 'file';
+  raw?: boolean;
+  pagesOnly?: boolean;
+  needsAnchorLinks?: boolean;
+  check: (context: FileContext) => FileFinding[];
+};
+
+export type SiteFile = { file: string; kind: FileKind };
+
+export type BuildResult = BuildValidationResult;
+
+export type Site = {
+  baseDir: string;
+  files: SiteFile[];
+  /** Set with --files: rules report on these files only. */
+  selected?: ReadonlySet<string>;
+  configFile: string;
+  variables?: Record<string, string>;
+  build?: BuildResult;
+  /** The line and column of the first occurrence of text in a file. */
+  locate: (file: string, text: string) => { line?: number; column?: number };
+  localSchema: boolean;
+};
+
+/** Checks the site as a whole. */
+export type SiteRule = RuleMeta & {
+  scope: 'site';
+  check: (site: Site) => Finding[] | Promise<Finding[]>;
+};
+
+export type Rule = FileRule | SiteRule;