@mintlify/cli 4.0.1813 → 4.1.1

package/src/validate/mdx.ts

@@ -1,290 +0,0 @@
-import {
-  coreRemark,
-  FRONTMATTER_RE,
-  getCodeRanges,
-  HEADING_ID_RE,
-  JSXParser,
-  pagePathToSlug,
-  replaceSlashIndex,
-  safeCleanHeadingId,
-  toPosixPath,
-} from '@mintlify/common';
-import { decorateGraphNodeFromPageContent, Node, PathType } from '@mintlify/link-rot';
-import type { Root } from 'mdast';
-
-import type { Edit } from './types.js';
-
-const HEADING_ID = new RegExp(HEADING_ID_RE.source, 'gm');
-const ESM_START = /^(?:import|export)(?=[\s{*])/;
-const JSX_TAG = /<[A-Za-z][\w.:-]*(?:"[^"]*"|'[^']*'|\{[^{}]*\}|[^<>"'{}])*>/g;
-const ATTR_VALUE = /"[^"]*"|'[^']*'|\{[^{}]*\}/g;
-
-export const hasCustomHeadingId = (line: string) => /\{\s*#[^}]+?\s*\}\s*$/.test(line);
-
-export const parseContent = (content: string): Root => {
-  const padded = content.replace(
-    HEADING_ID,
-    (match, indent: string, hashes: string, text: string) => {
-      const end = match.indexOf(text, indent.length + hashes.length) + text.length;
-      return match.slice(0, end).padEnd(match.length, ' ');
-    }
-  );
-  return coreRemark().parse(padded);
-};
-
-type Range = [number, number];
-
-const blankRanges = (content: string, ranges: Range[]) => {
-  let result = '';
-  let cursor = 0;
-  for (const [from, to] of [...ranges].sort((a, b) => a[0] - b[0])) {
-    const start = Math.max(from, cursor);
-    if (to <= start) continue;
-    result += content.slice(cursor, start) + content.slice(start, to).replace(/[^\n]/g, ' ');
-    cursor = to;
-  }
-  return result + content.slice(cursor);
-};
-
-const maskWith = (content: string, maskers: ((content: string) => Range[])[]) =>
-  maskers.reduce((text, ranges) => blankRanges(text, ranges(text)), content);
-
-const isCompleteEsm = (text: string) => {
-  try {
-    JSXParser.parse(text, { ecmaVersion: 'latest', sourceType: 'module' });
-    return true;
-  } catch (error) {
-    const pos = (error as { pos?: unknown }).pos;
-    return typeof pos !== 'number' || pos < text.trimEnd().length;
-  }
-};
-
-const frontmatterRanges = (content: string): Range[] => {
-  const match = FRONTMATTER_RE.exec(content);
-  return match ? [[match.index, match.index + match[0].length]] : [];
-};
-
-const esmRanges = (content: string, codeRanges: Range[]): Range[] => {
-  let esm: string[] | undefined;
-  let previousBlank = true;
-  const ranges: Range[] = [];
-  let offset = 0;
-  for (const line of content.split('\n')) {
-    const isBlank = line.trim() === '';
-    const wasBlank = previousBlank;
-    previousBlank = isBlank;
-    if (esm) {
-      if (isBlank && isCompleteEsm(esm.join('\n'))) esm = undefined;
-      else {
-        esm.push(line);
-        ranges.push([offset, offset + line.length]);
-      }
-    } else if (
-      wasBlank &&
-      ESM_START.test(line) &&
-      !codeRanges.some(([start, end]) => start <= offset && offset < end)
-    ) {
-      esm = [line];
-      ranges.push([offset, offset + line.length]);
-    }
-    offset += line.length + 1;
-  }
-  return ranges;
-};
-
-export const maskFrontmatter = (content: string): string =>
-  blankRanges(content, frontmatterRanges(content));
-
-export const maskCode = (content: string, { keepEsm = false } = {}): string => {
-  const codeRanges = getCodeRanges(content);
-  return blankRanges(content, [
-    ...frontmatterRanges(content),
-    ...codeRanges,
-    ...(keepEsm ? [] : esmRanges(content, codeRanges)),
-  ]);
-};
-
-const OPENS = new Set(['{', '${']);
-
-const maskExpression = (content: string, start: number): { ranges: Range[]; end: number } => {
-  const ranges: Range[] = [];
-  let depth = 0;
-  try {
-    const tokens = JSXParser.tokenizer(content.slice(start), {
-      ecmaVersion: 'latest',
-      onComment: (block, _text, from, to) =>
-        ranges.push([start + from + 2, start + to - (block ? 2 : 0)]),
-    });
-    for (const token of tokens) {
-      const label = token.type.label;
-      if (label === 'template') ranges.push([start + token.start, start + token.end]);
-      else if (label === 'string') ranges.push([start + token.start + 1, start + token.end - 1]);
-      else if (label === 'regexp') {
-        const raw = content.slice(start + token.start, start + token.end);
-        ranges.push([start + token.start + 1, start + token.start + raw.lastIndexOf('/')]);
-      } else if (OPENS.has(label)) depth++;
-      else if (label === '}' && depth-- === 0) return { ranges, end: start + token.end };
-    }
-  } catch (error) {
-    if (!(error instanceof SyntaxError && 'pos' in error && typeof error.pos === 'number')) {
-      return { ranges, end: content.length };
-    }
-    const pos = start + error.pos;
-    if (!error.message.startsWith('Unterminated string')) return { ranges, end: pos };
-    const lineEnd = content.indexOf('\n', pos);
-    ranges.push([pos + 1, lineEnd === -1 ? content.length : lineEnd]);
-  }
-  return { ranges, end: content.length };
-};
-
-const expressionRanges = (content: string): Range[] => {
-  const ranges: Range[] = [];
-  for (let index = 0; index < content.length; index++) {
-    const char = content[index];
-    if (char === '\\') index++;
-    else if (char === '{') {
-      const expression = maskExpression(content, index + 1);
-      ranges.push(...expression.ranges);
-      index = expression.end - 1;
-    }
-  }
-  return ranges;
-};
-
-const attributeRanges = (content: string): Range[] =>
-  [...content.matchAll(JSX_TAG)].flatMap(({ index, 0: tag }) =>
-    [...tag.matchAll(ATTR_VALUE)].map(
-      ({ index: at, 0: value }): Range => [index + at + 1, index + at + value.length - 1]
-    )
-  );
-
-const escapedTagRanges = (content: string): Range[] =>
-  [...content.matchAll(/\\[\s\S]/g)].flatMap(({ index, 0: escape }): Range[] =>
-    escape === '\\<' ? [[index + 1, index + 2]] : []
-  );
-
-export const maskNonMarkup = (content: string): string =>
-  maskWith(maskCode(content), [attributeRanges, escapedTagRanges, expressionRanges]);
-
-export const selectEdits = <T extends Edit>(edits: T[]): T[] => {
-  const ordered = edits
-    .map((edit, index) => ({ edit, index }))
-    .sort((a, b) => b.edit.start - a.edit.start || b.edit.end - a.edit.end || b.index - a.index);
-  const selected: T[] = [];
-  let floor = Infinity;
-  for (const { edit } of ordered) {
-    if (edit.end > floor) continue;
-    selected.push(edit);
-    floor = edit.start;
-  }
-  return selected;
-};
-
-export const applyEdits = (content: string, edits: Edit[]): string =>
-  selectEdits(edits).reduce(
-    (result, edit) => result.slice(0, edit.start) + edit.text + result.slice(edit.end),
-    content
-  );
-
-export const toOffset = (content: string, line: number, column = 1) => {
-  let offset = 0;
-  for (let current = 1; current < line; current++) {
-    const next = content.indexOf('\n', offset);
-    if (next === -1) break;
-    offset = next + 1;
-  }
-  return offset + column - 1;
-};
-
-export const toPosition = (content: string, offset: number) => {
-  const before = content.slice(0, offset).split('\n');
-  return { line: before.length, column: (before.pop()?.length ?? 0) + 1 };
-};
-
-const byStart = (a: Edit, b: Edit) => a.start - b.start;
-
-/** Maps an offset in edited content back to the content before the edits, or undefined inside an edit. */
-function toOriginal(edits: Edit[], offset: number, inside: 'snap'): number;
-function toOriginal(edits: Edit[], offset: number, inside: 'reject'): number | undefined;
-function toOriginal(edits: Edit[], offset: number, inside: 'snap' | 'reject') {
-  let delta = 0;
-  for (const edit of edits) {
-    const start = edit.start + delta;
-    if (inside === 'snap' ? offset < start : offset <= start) break;
-    if (offset < start + edit.text.length) return inside === 'snap' ? edit.start : undefined;
-    delta += edit.text.length - (edit.end - edit.start);
-  }
-  return offset - delta;
-}
-
-/** Maps an edit made against a later stage back to the original content, or undefined when it touches an earlier fix. */
-export const unmapEdit = (
-  stages: { content: string; edits: Edit[] }[],
-  index: number,
-  edit: Edit
-): Edit | undefined => {
-  let { start, end } = edit;
-  for (const { edits } of stages.slice(0, index).reverse()) {
-    const sorted = [...edits].sort(byStart);
-    const mappedStart = toOriginal(sorted, start, 'reject');
-    const mappedEnd = toOriginal(sorted, end, 'reject');
-    if (mappedStart === undefined || mappedEnd === undefined) return undefined;
-    if (sorted.some((earlier) => earlier.start < mappedEnd && earlier.end > mappedStart)) {
-      return undefined;
-    }
-    start = mappedStart;
-    end = mappedEnd;
-  }
-  return { start, end, text: edit.text };
-};
-
-export const relocate = (
-  stages: { content: string; edits: Edit[] }[],
-  index: number,
-  position: { line?: number; column?: number }
-) => {
-  const stage = stages[index];
-  const original = stages[0];
-  if (!stage || !original || position.line === undefined) return {};
-  const offset = stages
-    .slice(0, index)
-    .reduceRight(
-      (current, { edits }) => toOriginal([...edits].sort(byStart), current, 'snap'),
-      toOffset(stage.content, position.line, position.column)
-    );
-  const mapped = toPosition(original.content, offset);
-  return position.column === undefined ? { line: mapped.line } : mapped;
-};
-
-const pagePath = (file: string) => replaceSlashIndex(pagePathToSlug(file)).replace(/^\.$/, '');
-
-export const collectAnchorLinks = async (file: string, content: string): Promise<string[]> => {
-  const node = new Node(file);
-  try {
-    await decorateGraphNodeFromPageContent(node, content);
-  } catch {
-    return [];
-  }
-  return node.paths.flatMap((link) =>
-    link.pathType === PathType.INTERNAL && link.anchorLink
-      ? [
-          `${pagePath(toPosixPath(link.toString()))}#${safeCleanHeadingId(link.anchorLink.slice(1))}`,
-        ]
-      : []
-  );
-};
-
-export const linkedAnchor = (
-  links: ReadonlySet<string> | undefined,
-  file: string,
-  slug: string
-): string | undefined => {
-  const prefix = `${pagePath(file)}#`;
-  for (const link of links ?? []) {
-    if (!link.startsWith(prefix)) continue;
-    const anchor = link.slice(prefix.length);
-    const suffix = anchor.startsWith(`${slug}-`) && /^\d/.test(anchor.slice(slug.length + 1));
-    if (anchor === slug || suffix) return anchor;
-  }
-  return undefined;
-};

package/src/validate/output.tsx

@@ -1,76 +0,0 @@
-import { addLog, ErrorLog, InfoLog, SuccessLog } from '@mintlify/previewing';
-import { Box, Text } from 'ink';
-
-import type { Report } from './report.js';
-import type { Diagnostic } from './types.js';
-
-const preview = (value: string) => {
-  const text = JSON.stringify(value);
-  return text.length > 60 ? `${text.slice(0, 57)}..."` : text;
-};
-
-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 logReport = (report: Report) => {
-  for (const change of report.fixed ?? []) {
-    addLog(
-      <SuccessLog
-        message={`fixed ${change.file}${change.line ? `:${change.line}` : ''} ${change.rule}: ${preview(change.before)} → ${preview(change.after)}`}
-      />
-    );
-  }
-
-  const byFile = new Map<string, Diagnostic[]>();
-  for (const diagnostic of report.diagnostics) {
-    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 fixable = report.diagnostics.filter(({ fix }) => fix).length;
-  if (fixable > 0 && !report.fixed) {
-    addLog(<InfoLog message={`\`--fix\` would fix ${plural(fixable, 'issue')}.`} />);
-  }
-
-  const { build } = report;
-  if (build.ran && build.passed) addLog(<SuccessLog message="build passed" />);
-  else if (build.ran && report.passed)
-    addLog(<InfoLog message="build failed only on disabled rules" />);
-  else if (build.ran) addLog(<ErrorLog message="build failed" />);
-  else if (build.reason === 'errors found')
-    addLog(<InfoLog message="build skipped until the errors above are fixed" />);
-
-  const { errors, warnings } = report.summary;
-  const warned = plural(warnings, 'warning');
-  const passed = warnings > 0 ? `passed with ${warned}` : 'validation passed';
-  const failed = `${plural(errors, 'error')}${warnings > 0 ? `, ${warned}` : ''}`;
-  addLog(report.passed ? <SuccessLog message={passed} /> : <ErrorLog message={failed} />);
-};

package/src/validate/report.ts

@@ -1,40 +0,0 @@
-import type { Change, Diagnostic } from './types.js';
-
-export type BuildStatus =
-  | { ran: true; passed: boolean }
-  | { ran: false; reason: 'disabled' | 'errors found' | 'no build rules' };
-
-export type Report = {
-  passed: boolean;
-  summary: { errors: number; warnings: number; byRule: Record<string, number> };
-  diagnostics: Diagnostic[];
-  build: BuildStatus;
-  /** With --fix: the edits that were applied. */
-  fixed?: Change[];
-};
-
-export const toReport = (
-  diagnostics: Diagnostic[],
-  build: BuildStatus,
-  fixed?: Change[]
-): Report => {
-  const byRule: Record<string, number> = {};
-  for (const { rule } of diagnostics) byRule[rule] = (byRule[rule] ?? 0) + 1;
-  const errors = diagnostics.filter(({ severity }) => severity === 'error').length;
-  return {
-    passed: errors === 0,
-    summary: { errors, warnings: diagnostics.length - errors, byRule },
-    diagnostics: diagnostics.map(({ rule, group, severity, file, line, column, message, fix }) => ({
-      rule,
-      group,
-      severity,
-      file,
-      ...(line !== undefined && { line }),
-      ...(column !== undefined && { column }),
-      message,
-      ...(fix && { fix }),
-    })),
-    build,
-    ...(fixed && { fixed }),
-  };
-};

package/src/validate/rules/build.ts

@@ -1,146 +0,0 @@
-import { normalizeRelativePath, toPosixPath } from '@mintlify/common';
-import type { Warning } from '@mintlify/prebuild';
-import { stripVTControlCharacters } from 'node:util';
-
-import type { Finding, Group, Site, SiteRule } from '../types.js';
-
-const FILE = String.raw`[\w@.\\/-]+\.(?:mdx?|jsx?|tsx?|json|ya?ml)\b`;
-
-const FILE_IN_MESSAGE = new RegExp(FILE);
-
-const IMPORTERS = [
-  new RegExp(String.raw`\(in (${FILE}),`),
-  new RegExp(String.raw`(?:\bin|imported from) (${FILE})`),
-];
-
-const IMPORT_TYPES = new Set<Warning['type']>([
-  'missing-file',
-  'invalid-import-path',
-  'import-resolution-error',
-  'default-import-no-default-export',
-  'export-collision',
-  'undeclared-package',
-  'package-import-conflict',
-]);
-
-const POSITION = /^:(\d+)(?::(\d+))?/;
-
-const QUOTED = /"([^"]+)"/;
-
-const toFinding = (site: Site, warning: Warning): Finding => {
-  const clean = stripVTControlCharacters(warning.message).trim();
-  const importer =
-    warning.file == null && IMPORT_TYPES.has(warning.type)
-      ? IMPORTERS.map((pattern) => pattern.exec(clean)?.[1]).find(Boolean)
-      : undefined;
-  // Missing nav pages are always about the config, even when the page looks like a file
-  const match =
-    warning.file != null || importer || warning.type === 'missing-nav-page'
-      ? null
-      : FILE_IN_MESSAGE.exec(clean);
-  const found = importer ?? match?.[0];
-  const file =
-    warning.file ?? (found ? normalizeRelativePath(toPosixPath(found)) : site.configFile);
-  const position = match ? POSITION.exec(clean.slice(match.index + match[0].length)) : null;
-  // Config warnings quote the entry they're about, such as a navigation page
-  const quoted =
-    warning.file == null && file === site.configFile ? QUOTED.exec(clean)?.[0] : undefined;
-  const located =
-    warning.ref != null && warning.line == null
-      ? site.locate(file, JSON.stringify(warning.ref))
-      : quoted
-        ? site.locate(file, quoted)
-        : undefined;
-  return {
-    file,
-    ...(warning.line != null
-      ? { line: warning.line, ...(warning.column != null && { column: warning.column }) }
-      : position && {
-          line: Number(position[1]),
-          ...(position[2] && { column: Number(position[2]) }),
-        }),
-    ...located,
-    message: clean,
-  };
-};
-
-/** Warning types some rule turns into diagnostics, so a strict-build failure is explained. */
-const COVERED_TYPES = new Set<Warning['type']>(['parse-error']);
-
-const buildRule = (
-  id: string,
-  group: Group,
-  types: Warning['type'][],
-  description: string
-): SiteRule => {
-  for (const type of types) COVERED_TYPES.add(type);
-  return {
-    id,
-    group,
-    severity: 'error',
-    needsBuild: true,
-    scope: 'site',
-    description,
-    check: (site) =>
-      (site.build?.warnings ?? [])
-        .filter(({ type }) => types.includes(type))
-        .map((warning) => toFinding(site, warning)),
-  };
-};
-
-export const BUILD_RULES: SiteRule[] = [
-  buildRule(
-    'missing-nav-page',
-    'nav',
-    ['missing-nav-page'],
-    'pages in the navigation that have no file'
-  ),
-  buildRule('missing-file', 'content', ['missing-file'], "imported files that don't exist"),
-  buildRule(
-    'import-error',
-    'content',
-    [
-      'invalid-import-path',
-      'import-resolution-error',
-      'default-import-no-default-export',
-      'export-collision',
-    ],
-    "imports in pages and snippets that don't resolve"
-  ),
-  buildRule(
-    'package-import',
-    'config',
-    ['undeclared-package', 'package-import-conflict'],
-    'npm package imports that are undeclared or conflict'
-  ),
-  buildRule('openapi-build', 'openapi', ['openapi'], 'OpenAPI pages the build could not generate'),
-  {
-    id: 'build-failed',
-    group: 'config',
-    severity: 'error',
-    needsBuild: true,
-    scope: 'site',
-    description: 'the strict build failed for a reason no rule reports',
-    check: (site) => {
-      if (!site.build || site.build.passed) return [];
-      const unreported = (warning: Warning) =>
-        warning.type === 'parse-error' &&
-        site.selected !== undefined &&
-        !site.selected.has(toFinding(site, warning).file);
-      const uncovered = site.build.warnings.filter(
-        (warning) => !COVERED_TYPES.has(warning.type) || unreported(warning)
-      );
-      const findings = uncovered.map((warning) => toFinding(site, warning));
-      // Covered warnings are the selected rules' to report; disabled ones are meant to pass
-      return site.build.strict
-        ? findings
-        : [...findings, { file: site.configFile, message: site.build.error }];
-    },
-  },
-];
-
-/** Build warnings of one type, which the engine merges into the static rule that covers them. */
-export const buildFindings = (site: Site, type: Warning['type']): Finding[] =>
-  (site.build?.warnings ?? [])
-    .filter((warning) => warning.type === type)
-    .map((warning) => toFinding(site, warning));

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

@@ -1,78 +0,0 @@
-import {
-  AVOIDED_PAGE_MODES,
-  getTableOfContentsTitle,
-  safeCleanHeadingId,
-  slugify,
-} from '@mintlify/common';
-import type { Heading, Root } from 'mdast';
-import remarkSmartypants from 'remark-smartypants';
-import { unified } from 'unified';
-
-import { hasCustomHeadingId, linkedAnchor } from '../../mdx.js';
-import type { FileRule } from '../../types.js';
-
-const normalize = (value: string) => value.trim().replace(/\s+/g, ' ');
-
-const smartypants = unified().use(remarkSmartypants);
-
-const firstHeading = (tree: Root) =>
-  tree.children.find((node): node is Heading => node.type === 'heading');
-
-const renderedText = (heading: Heading) => {
-  const clone = structuredClone(heading);
-  const root: Root = { type: 'root', children: [clone] };
-  smartypants.runSync(root);
-  return getTableOfContentsTitle(clone);
-};
-
-export const duplicateH1: FileRule = {
-  id: 'duplicate-h1',
-  group: 'content',
-  severity: 'warning',
-  scope: 'file',
-  description: 'remove a first heading that repeats the frontmatter title',
-  pagesOnly: true,
-  needsAnchorLinks: true,
-  check: ({ tree, frontmatter, content, file, anchorLinks }) => {
-    const { title, mode } = frontmatter;
-    if (typeof title !== 'string' || AVOIDED_PAGE_MODES.includes(String(mode))) return [];
-    const first = firstHeading(tree);
-    if (!first || first.depth !== 1) return [];
-    if (normalize(getTableOfContentsTitle(first)) !== normalize(title)) return [];
-    const start = first.position?.start.offset ?? 0;
-    const end = first.position?.end.offset ?? start;
-    const location = {
-      line: first.position?.start.line,
-      column: first.position?.start.column,
-    };
-    const lineEnd = content.indexOf('\n', start);
-    if (hasCustomHeadingId(content.slice(start, lineEnd === -1 ? undefined : lineEnd))) {
-      return [
-        {
-          ...location,
-          message:
-            'first heading duplicates the frontmatter title; it has a custom {#id}, so remove it by hand and update links to it',
-        },
-      ];
-    }
-    const anchor = [renderedText(first), getTableOfContentsTitle(first)]
-      .map((text) => linkedAnchor(anchorLinks, file, safeCleanHeadingId(slugify(text))))
-      .find((linked) => linked !== undefined);
-    if (anchor !== undefined) {
-      return [
-        {
-          ...location,
-          message: `first heading duplicates the frontmatter title; links point to #${anchor}, so remove it by hand and update them`,
-        },
-      ];
-    }
-    const trailing = /^\n*/.exec(content.slice(end))?.[0].length ?? 0;
-    return [
-      {
-        ...location,
-        message: 'first heading duplicates the frontmatter title',
-        edit: { start, end: end + trailing, text: '' },
-      },
-    ];
-  },
-};