Parsing errors on saving any file inside snippets/ folder

[equinusocio]

Bug description

When saving any file inside snippets/ during mint dev, the terminal fills with MDX parsing errors from files inside node_modules. Despite node_modules being listed in DEFAULT_MINT_IGNORES and in .mintignore, the errors still appear on every file save.

Steps to reproduce

1. Create a Mintlify project with node_modules present (standard setup)
2. Add any .jsx file to snippets/, e.g. snippets/MyComponent.jsx
3. Run mint dev
4. Save snippets/MyComponent.jsx
5. Observe parsing errors for files in node_modules printed to the terminal

Expected behavior

No errors from node_modules — those files should be ignored, as documented in .mintignore and DEFAULT_MINT_IGNORES.

Actual behavior

On every save of a snippet file, dozens of errors like:

parsing error ./node_modules/.pnpm/@biomejs+biome@2.4.3/node_modules/@biomejs/biome/README.es.md:28:2 - Unexpected character `!` (U+0021) before name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a comment in MDX, use `{/* text */}`)
parsing error ./node_modules/.pnpm/acorn@8.15.0/node_modules/acorn/CHANGELOG.md:49:71 - Unexpected character `8` ...

Root cause

The issue is in @mintlify/previewing. Several functions use getFileListSync from @mintlify/prebuild, which recursively scans all files without applying any ignore patterns.

packages/previewing/src/local-preview/listener/generatePagesWithImports.ts (triggered on every snippet save):

const pageFilenames = getFileListSync(CMD_EXEC_PATH).filter((file) => {
  if (!isSnippetExtension(getFileExtension(file))) return false;
  const category = getFileCategory(file, { importedFiles });
  return category === 'page'; // ← node_modules/*.md files pass this check
});

getFileListSync has no awareness of .mintignore or DEFAULT_MINT_IGNORES:

// @mintlify/prebuild - fs/index.ts
export const getFileListSync = (dirName: string, og = dirName): string[] => {
  const files: string[] = [];
  const items = readdirSync(dirName, { withFileTypes: true });
  for (const item of items) {
    const fullPath = path.join(dirName, item.name);
    if (item.isDirectory()) {
      files.push(...getFileListSync(fullPath, og)); // ← recurses into node_modules
    } else {
      files.push(toPosixPath(path.relative(og, fullPath)));
    }
  }
  return files;
};

By contrast, the async getFileList correctly applies isMintIgnored:

export async function* getFileList(dirName, og = dirName, mintIgnore = []) {
  const items = await readdir(dirName, { withFileTypes: true });
  for (const item of items) {
    const relativePath = toPosixPath(path.relative(og, fullPath));
    if (isMintIgnored(relativePath, mintIgnore)) continue; // ✅ filters node_modules
    // ...
  }
}

The same issue exists in getSnippets.ts and importCache.ts (fallback path).

Suggested fix

getFileListSync should accept an optional mintIgnore parameter and apply isMintIgnored, mirroring the async getFileList:

export const getFileListSync = (
  dirName: string,
  og = dirName,
  mintIgnore: string[] = []
): string[] => {
  const files: string[] = [];
  const items = readdirSync(dirName, { withFileTypes: true });
  for (const item of items) {
    const fullPath = path.join(dirName, item.name);
    const relativePath = toPosixPath(path.relative(og, fullPath));
    if (isMintIgnored(relativePath, mintIgnore)) continue; // ← add this
    if (item.isDirectory()) {
      files.push(...getFileListSync(fullPath, og, mintIgnore));
    } else {
      files.push(relativePath);
    }
  }
  return files;
};

All callers (generatePagesWithImports, getSnippets, importCache) would then need to pass the result of getMintIgnoreGlobs().

Environment

• mint version: 4.2.367
• Package manager: pnpm (with .pnpm virtual store layout)

[equinusocio]

Any feedback or consideration about this fix?

[aquariuslt]

Adding a version comparison for the same synchronous scanner, including a stack overflow caused by large ignored directories.

Observed on mint 4.2.788

Environment: macOS, Node.js 24.11.1, mint 4.2.788, @mintlify/cli 4.0.1391, and @mintlify/prebuild 1.0.1231.

mint broken-links --check-redirects failed with:

RangeError: Maximum call stack size exceeded
    at getFileListSync (.../@mintlify/prebuild/dist/fs/index.js:11:19)
    at getLinkPaths (.../@mintlify/link-rot/dist/prebuild.js:40:54)

The checkout contained nested Git worktrees and their pnpm dependencies. The .worktrees subtree produced 445,790 leaf entries. The failure occurred when the parent scanner expanded that whole list into files.push(...getFileListSync(fullPath, og)), before ignore filtering. Hiding only .worktrees from the diagnostic directory listing made the unchanged project's internal-link and redirect checks pass.

A small synthetic fs.readdirSync fixture also reproduced the failure without copying the worktrees: one shallow directory with 110,000 irrelevant .bin entries passed, while 130,000 failed, even when that directory was listed in .mintignore. These counts are observations on this runtime, not a universal limit.

Verified with mint 4.2.1047

I installed mint 4.2.1047 separately, with @mintlify/cli 4.0.1650, @mintlify/prebuild 1.0.1412, and @mintlify/link-rot 3.0.1468.

The same 130,000-entry fixture passed both with and without .mintignore. With the ignore rule, the synthetic directory was not enumerated at all. The installed scanner uses a loop instead of spreading the nested array, and link-rot forwards the ignore patterns into the scanner.

This confirms that the tested broken-links failure is fixed in 4.2.1047. I have not determined the first fixed release or retested the full preview flow. A custom directory such as .worktrees still needs its own .mintignore rule to avoid checking historical worktree content; .gitignore alone does not provide that exclusion.