@mintlify/cli 4.0.1732 → 4.0.1734

package/src/cli.tsx

@@ -56,6 +56,7 @@ import { sendPublishPrompt, signup } from './signup.js';
 import { status, getCliSubdomains } from './status.js';
 import { trackTelemetryPreferenceChange } from './telemetry/track.js';
 import { update } from './update.js';
+import { runLintStep, splitList } from './validate/command.js';
 import { renderWelcome } from './welcome.js';
 import { workflowsBuilder } from './workflows/index.js';
 
@@ -379,9 +380,32 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
               default: false,
               description: 'Disable OpenAPI file generation',
             })
+            .option('files', {
+              type: 'string',
+              array: true,
+              description:
+                'Limit page checks to these files or globs; site-wide checks and the build still cover the whole site',
+            })
+            .option('enable', {
+              type: 'string',
+              array: true,
+              coerce: splitList,
+              description:
+                'Turn on rules or groups (comma-separated), for example after --disable all',
+            })
+            .option('disable', {
+              type: 'string',
+              array: true,
+              coerce: splitList,
+              description:
+                'Turn off rules or groups (comma-separated), or all; parse errors are still reported',
+            })
             .usage('usage: mintlify validate [options]')
             .example('mintlify validate', 'validate the build'),
         async (argv) => {
+          const lintPassed = await runLintStep(argv);
+          if (!lintPassed) return;
+
           if (!argv['disable-openapi']) {
             let openApiFilenames: string[] = [];
 

package/src/resolveFiles.ts

@@ -66,6 +66,8 @@ async function walk(baseDir: string, dir = ''): Promise<string[]> {
   return files;
 }
 
+export class NoMatchingFilesError extends Error {}
+
 export async function resolveExplicitFiles(baseDir: string, args: string[]): Promise<string[]> {
   let allFiles: string[] | null = null;
   const matched: string[] = [];
@@ -90,7 +92,7 @@ export async function resolveExplicitFiles(baseDir: string, args: string[]): Pro
   }
 
   if (unmatched.length > 0) {
-    throw new Error(
+    throw new NoMatchingFilesError(
       `No matching files for: ${unmatched.join(', ')} (globs match .md and .mdx files)`
     );
   }

package/src/validate/command.tsx

@@ -0,0 +1,71 @@
+import { addLog, clearLogs, ErrorLog, SpinnerLog } from '@mintlify/previewing';
+import path from 'node:path';
+
+import { CMD_EXEC_PATH, terminate } from '../helpers.js';
+import { NoMatchingFilesError, resolveExplicitFiles } from '../resolveFiles.js';
+import { checkSite, selectRules, UsageError } from './engine.js';
+import { logDiagnostics } from './output.js';
+
+export type ValidateArgs = {
+  'local-schema': boolean;
+  'client-version'?: string;
+  groups?: (string | number)[];
+  files?: (string | number)[];
+  enable?: string[];
+  disable?: string[];
+};
+
+export const EXIT = { passed: 0, failed: 1, crashed: 2 } as const;
+
+export const splitList = (values: string[]) =>
+  values.flatMap((value) =>
+    value
+      .split(',')
+      .map((item) => item.trim())
+      .filter(Boolean)
+  );
+
+const errorMessage = (error: unknown) => (error instanceof Error ? error.message : String(error));
+
+const resolveSelection = async (baseDir: string, values: (string | number)[] | undefined) => {
+  const args = (values ?? []).map(String).filter(Boolean);
+  if (args.length === 0) return undefined;
+  const files = await resolveExplicitFiles(CMD_EXEC_PATH, args);
+  return new Set(
+    files.map((file) =>
+      path.relative(baseDir, path.resolve(CMD_EXEC_PATH, file)).split(path.sep).join('/')
+    )
+  );
+};
+
+export const runLintStep = async (
+  argv: ValidateArgs,
+  baseDir = CMD_EXEC_PATH
+): Promise<boolean> => {
+  try {
+    const rules = selectRules({
+      enable: argv.enable,
+      disable: argv.disable ?? [],
+    });
+    const selected = await resolveSelection(baseDir, argv.files);
+    addLog(<SpinnerLog message="validating..." />);
+
+    const { diagnostics } = await checkSite(baseDir, rules, {
+      selected,
+      localSchema: argv['local-schema'],
+    });
+    clearLogs();
+    const failed = logDiagnostics(diagnostics);
+    if (failed) {
+      await terminate(EXIT.failed);
+      return false;
+    }
+    return true;
+  } catch (error) {
+    const usage = error instanceof UsageError || error instanceof NoMatchingFilesError;
+    clearLogs();
+    addLog(<ErrorLog message={errorMessage(error)} />);
+    await terminate(usage ? EXIT.failed : EXIT.crashed);
+    return false;
+  }
+};

package/src/validate/engine.ts

@@ -0,0 +1,93 @@
+import { checkFiles } from './files.js';
+import { RULES } from './rules/index.js';
+import { PARSE_ERROR } from './rules/parseError.js';
+import { loadSite } from './site.js';
+import {
+  GROUPS,
+  type Diagnostic,
+  type DiagnosticSource,
+  type FileRule,
+  type Finding,
+  type Rule,
+  type Site,
+} from './types.js';
+
+export class UsageError extends Error {}
+
+const ruleList = () => RULES.map(({ id }) => id).join(', ');
+
+const matchToken = (token: string): Rule[] => {
+  if (token === 'all') return RULES;
+  const rule = RULES.find(({ id }) => id === token);
+  if (rule) return [rule];
+  if ((GROUPS as string[]).includes(token)) {
+    return RULES.filter(({ group }) => group === token);
+  }
+  throw new UsageError(
+    `unknown rule or group "${token}". Groups: all, ${GROUPS.join(', ')}. Rules: ${ruleList()}`
+  );
+};
+
+/** Every rule, minus --disable, plus --enable. parse-error is the engine's own, not selectable. */
+export const selectRules = ({
+  enable = [],
+  disable = [],
+}: {
+  enable?: string[];
+  disable?: string[];
+}): Rule[] => {
+  if ([...disable, ...enable].includes(PARSE_ERROR.id)) {
+    throw new UsageError(`${PARSE_ERROR.id} always runs and can't be disabled`);
+  }
+  const selected = new Set(RULES);
+  for (const token of disable) for (const rule of matchToken(token)) selected.delete(rule);
+  for (const token of enable) for (const rule of matchToken(token)) selected.add(rule);
+  return RULES.filter((rule) => selected.has(rule));
+};
+
+const toDiagnostic = (source: DiagnosticSource, finding: Finding): Diagnostic => ({
+  ...finding,
+  rule: source.id,
+  group: source.group,
+  severity: finding.severity ?? source.severity,
+});
+
+const RULE_ORDER = new Map(RULES.map(({ id }, index) => [id, index]));
+
+const sortDiagnostics = (diagnostics: Diagnostic[]) =>
+  diagnostics.sort(
+    (a, b) =>
+      (a.file < b.file ? -1 : a.file > b.file ? 1 : 0) ||
+      (a.line ?? 0) - (b.line ?? 0) ||
+      (a.column ?? 0) - (b.column ?? 0) ||
+      (RULE_ORDER.get(a.rule) ?? 0) - (RULE_ORDER.get(b.rule) ?? 0)
+  );
+
+/** Runs every selected rule that doesn't need the build. */
+export const runChecks = async (site: Site, rules: Rule[]) => {
+  const fileRules = rules.filter((rule): rule is FileRule => rule.scope === 'file');
+  const diagnostics = await checkFiles(site, fileRules);
+
+  for (const rule of rules) {
+    if (rule.scope !== 'site' || rule.needsBuild) continue;
+    for (const finding of await rule.check(site)) diagnostics.push(toDiagnostic(rule, finding));
+  }
+  return sortDiagnostics(diagnostics);
+};
+
+/** Loads the site and runs the selected rules. */
+export const checkSite = async (
+  baseDir: string,
+  rules: Rule[],
+  options: { selected?: ReadonlySet<string>; localSchema: boolean }
+) => {
+  const site = await loadSite(baseDir, options);
+  const { selected } = options;
+  if (selected && !site.files.some(({ file }) => selected.has(file))) {
+    throw new UsageError(
+      `none of the given files are pages or snippets of this site: ${[...selected].join(', ')}`
+    );
+  }
+  const diagnostics = await runChecks(site, rules);
+  return { site, diagnostics };
+};

package/src/validate/files.ts

@@ -0,0 +1,212 @@
+import { getAST, getFileCategory, parseFrontmatter, replaceVariables } from '@mintlify/common';
+import {
+  categorizeMdxFiles,
+  getErrorPosition,
+  getMintIgnore,
+  listContentFiles,
+} from '@mintlify/prebuild';
+import type { Root } from 'mdast';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { applyEdits, parseContent, relocate, selectEdits, unmapEdit } from './mdx.js';
+import { PARSE_ERROR } from './rules/parseError.js';
+import type {
+  Diagnostic,
+  Edit,
+  FileContext,
+  FileFinding,
+  FileKind,
+  FileRule,
+  Site,
+  SiteFile,
+} from './types.js';
+
+const CONCURRENCY = 16;
+
+const mapLimit = async <T, R>(items: T[], task: (item: T) => Promise<R>): Promise<R[]> => {
+  const results = new Array<R>(items.length);
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(CONCURRENCY, items.length) }, async () => {
+      while (next < items.length) {
+        const index = next++;
+        results[index] = await task(items[index] as T);
+      }
+    })
+  );
+  return results;
+};
+
+const CHECKED_CATEGORIES = new Set<string | null>(['page', 'snippet', 'snippet-v2']);
+
+export const readSiteFiles = async (baseDir: string): Promise<SiteFile[]> => {
+  const { mdxCandidates: candidates } = await listContentFiles(
+    baseDir,
+    await getMintIgnore(baseDir)
+  );
+  const { snippets, snippetsV2 } = await categorizeMdxFiles(baseDir, candidates);
+  const snippetFiles = new Set([...snippets, ...snippetsV2]);
+  return candidates
+    .filter((name) => /\.mdx?$/.test(name) && CHECKED_CATEGORIES.has(getFileCategory(name)))
+    .map((name) => ({
+      file: name.replace(/^\//, ''),
+      kind: (snippetFiles.has(name) ? 'snippet' : 'page') as FileKind,
+    }));
+};
+
+const readFrontmatter = (content: string): Record<string, unknown> => {
+  try {
+    const { attributes } = parseFrontmatter<unknown>(content);
+    return attributes && typeof attributes === 'object' ? { ...attributes } : {};
+  } catch {
+    return {};
+  }
+};
+
+type ParseError = { line?: number; column?: number; message: string };
+
+const REASON_POSITION = /\s*\(\d+:\d+(?:-\d+:\d+)?\)$/;
+
+export const toParseError = (error: unknown): ParseError => {
+  const reason = (error as { reason?: unknown } | null)?.reason;
+  const fallback = error instanceof Error ? error.message : 'could not parse this file';
+  const text = typeof reason === 'string' ? reason : fallback;
+  const position = error && typeof error === 'object' ? getErrorPosition(error) : null;
+  return {
+    ...(position?.line != null && { line: position.line }),
+    ...(position?.column != null && { column: position.column }),
+    message: text.replace(REASON_POSITION, ''),
+  };
+};
+
+const parseErrorDiagnostic = (file: string, error: ParseError): Diagnostic => ({
+  ...error,
+  rule: PARSE_ERROR.id,
+  group: PARSE_ERROR.group,
+  severity: PARSE_ERROR.severity,
+  file,
+  message: `${error.message} (other checks were skipped for this file)`,
+});
+
+type Parsed = { context: FileContext; approximate: boolean } | { error: ParseError };
+
+const tryParseContent = (content: string): Root | undefined => {
+  try {
+    return parseContent(content);
+  } catch {
+    return undefined;
+  }
+};
+
+const parseFile = (file: string, content: string, baseDir: string): Parsed => {
+  const context = { file, content, baseDir, frontmatter: readFrontmatter(content) };
+  const tree = tryParseContent(content);
+  if (tree) return { context: { ...context, tree }, approximate: false };
+  try {
+    return { context: { ...context, tree: getAST(content, file) }, approximate: true };
+  } catch (error) {
+    return { error: toParseError(error) };
+  }
+};
+
+const EMPTY_TREE = { type: 'root' as const, children: [] };
+
+const SOURCE_STAGE = 1;
+const AFTER_RAW_STAGE = 2;
+
+type Stage = { content: string; edits: Edit[] };
+
+const VARIABLE = /\{\{\s*([\w.\-]+)\s*\}\}/g;
+
+const variableEdits = (content: string, variables: Record<string, string> = {}): Edit[] =>
+  [...content.matchAll(VARIABLE)]
+    .filter((match) => match[1] !== undefined && variables[match[1]] !== undefined)
+    .map((match) => ({
+      start: match.index,
+      end: match.index + match[0].length,
+      text: replaceVariables(match[0], variables),
+    }));
+
+const toDiagnostic = (
+  rule: FileRule,
+  file: string,
+  { edit, ...finding }: FileFinding,
+  stages: Stage[],
+  stage: number
+): Diagnostic => {
+  const original = edit && unmapEdit(stages, stage, edit);
+  return {
+    ...finding,
+    ...relocate(stages, stage, finding),
+    rule: rule.id,
+    group: rule.group,
+    severity: rule.severity,
+    file,
+    ...(original && { fix: { file, ...original } }),
+  };
+};
+
+const checkFile = (
+  allRules: FileRule[],
+  { file, kind }: SiteFile,
+  content: string,
+  baseDir: string,
+  variables?: Record<string, string>
+): Diagnostic[] => {
+  const rules = kind === 'snippet' ? allRules.filter((rule) => !rule.pagesOnly) : allRules;
+  const raw = rules.filter((rule) => rule.raw);
+  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 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);
+  const stages: Stage[] = [
+    { content, edits: varEdits },
+    { content: source, edits: rawEdits },
+    { content: afterRaw, edits: [] },
+  ];
+  const diagnostics = rawFound.map(({ rule, finding }) =>
+    toDiagnostic(rule, file, finding, stages, SOURCE_STAGE)
+  );
+
+  const parsed = parseFile(file, afterRaw, baseDir);
+  if ('error' in parsed) {
+    diagnostics.unshift(
+      parseErrorDiagnostic(file, {
+        ...parsed.error,
+        ...relocate(stages, AFTER_RAW_STAGE, parsed.error),
+      })
+    );
+    return diagnostics;
+  }
+  for (const rule of treeRules) {
+    for (const finding of rule.check(parsed.context)) {
+      const found = parsed.approximate ? { ...finding, edit: undefined } : finding;
+      diagnostics.push(toDiagnostic(rule, file, found, stages, AFTER_RAW_STAGE));
+    }
+  }
+  return diagnostics;
+};
+
+export const checkFiles = async (site: Site, rules: FileRule[]): Promise<Diagnostic[]> => {
+  const targets = site.files.filter(({ file }) => !site.selected || site.selected.has(file));
+  const results = await mapLimit(targets, async (entry) => {
+    let content: string;
+    try {
+      content = await fs.readFile(path.join(site.baseDir, entry.file), 'utf-8');
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'could not read this file';
+      return [parseErrorDiagnostic(entry.file, { message })];
+    }
+    return checkFile(rules, entry, content, site.baseDir, site.variables);
+  });
+  return results.flat();
+};

package/src/validate/mdx.ts

@@ -0,0 +1,252 @@
+import {
+  coreRemark,
+  FRONTMATTER_RE,
+  getCodeRanges,
+  HEADING_ID_RE,
+  JSXParser,
+} from '@mintlify/common';
+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
+  );
+
+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;
+};