import fs from 'node:fs/promises'; import { glob } from 'tinyglobby'; /** * Recursively collects all .mdx files in the given docs directory. */ export async function getMdxFiles(docsDir: string): Promise { return glob(['**/*.mdx'], { cwd: docsDir, absolute: true }); } /** * Reads a file and returns an array of its lines. */ export async function readFileLines(filePath: string): Promise { const content = await fs.readFile(filePath, 'utf8'); return content.split(/\r?\n/); } /** * Converts a heading text to a URL-friendly slug. * Matches the behavior of typical MDX/rehype-slug processors. */ export function slugify(text: string): string { return text .toLowerCase() .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1') // Strip markdown links, keep text .replace(/[`*~\\]/g, '') // Strip inline formatting and MDX escape chars .replace(/(^|\s)_+|_+(?=\s|$)/g, '$1') // Strip `_emphasis_` delimiters but keep `SNAKE_CASE` .replace(/[<>]/g, '') // Remove angle brackets but keep their content .trim() .replace(/[^\w\s-]/g, '') // Remove non-word chars (except spaces and hyphens) .replace(/\s+/g, '-') // Replace spaces with hyphens .replace(/-+/g, '-') // Collapse multiple hyphens .replace(/^-|-$/g, ''); // Trim leading/trailing hyphens } export type LineContext = 'frontmatter' | 'codeblock' | 'content'; /** * Returns a per-line context array indicating whether each line is inside * frontmatter, a fenced code block, or normal content. */ export function getLineContexts(lines: string[]): LineContext[] { const contexts: LineContext[] = []; let inFrontmatter = false; let frontmatterSeen = false; let inCodeBlock = false; let openFenceLen = 0; let openFenceChar = ''; for (let i = 0; i < lines.length; i++) { const line = lines[i]; if (!frontmatterSeen && !inFrontmatter && i === 0 && line.trim() === '---') { inFrontmatter = true; contexts.push('frontmatter'); continue; } if (inFrontmatter) { if (line.trim() === '---') { inFrontmatter = false; frontmatterSeen = true; } contexts.push('frontmatter'); continue; } const fenceMatch = line.match(/^(`{3,}|~{3,})/); if (fenceMatch) { if (!inCodeBlock) { inCodeBlock = true; openFenceLen = fenceMatch[1].length; openFenceChar = fenceMatch[1][0]; contexts.push('codeblock'); continue; } else if ( fenceMatch[1][0] === openFenceChar && fenceMatch[1].length >= openFenceLen && line.trim() === fenceMatch[1] ) { inCodeBlock = false; contexts.push('codeblock'); continue; } } if (inCodeBlock) { contexts.push('codeblock'); continue; } contexts.push('content'); } return contexts; } /** * Extracts all heading slugs from an MDX file. * Returns a Set of slug strings (without the leading #). */ export async function getHeadingSlugs(filePath: string): Promise> { const lines = await readFileLines(filePath); const contexts = getLineContexts(lines); const slugs = new Set(); const counts = new Map(); const headingRegex = /^(#{1,6})\s+(.+)$/; for (let i = 0; i < lines.length; i++) { if (contexts[i] !== 'content') continue; const match = headingRegex.exec(lines[i]); if (match) { // Like rehype-slug, repeated headings get `-1`, `-2`, and so on const slug = slugify(match[2]); const count = counts.get(slug) ?? 0; slugs.add(count === 0 ? slug : `${slug}-${count}`); counts.set(slug, count + 1); } } return slugs; } /** * Collects all .md snippet files in the docs `_snippets` directory. */ export async function getSnippetFiles(docsDir: string): Promise { return glob(['_snippets/**/*.md'], { cwd: docsDir, absolute: true }); } export interface SnippetSegment { /** First line of the segment, including any HTML comments attached above the fence */ start: number; /** Line of the opening fence */ fenceLine: number; /** Line of the closing fence */ end: number; /** Language name after the opening fence, such as `ts` or `svelte` */ syntax: string; attributes: Record; } /** * Splits a snippet file into segments: one per fenced code block, plus the HTML comments * directly above it (blank lines between them are allowed). Comments such as * `` belong to the block that follows, so they move with it. */ export function getSnippetSegments(lines: string[]): SnippetSegment[] { const segments: SnippetSegment[] = []; for (let i = 0; i < lines.length; i++) { const openMatch = lines[i].match(/^(`{3,}|~{3,})/); if (!openMatch) continue; const fence = openMatch[1]; const fenceLine = i; const isClosingFence = (line: string) => { const closeMatch = line.trim().match(/^(`{3,}|~{3,})$/); return closeMatch?.[1][0] === fence[0] && closeMatch[1].length >= fence.length; }; let end = i + 1; while (end < lines.length - 1 && !isClosingFence(lines[end])) { end++; } const lowerBound = segments.length ? segments[segments.length - 1].end + 1 : 0; let start = fenceLine; let cursor = fenceLine - 1; while (cursor >= lowerBound) { if (lines[cursor].trim() === '') { cursor--; continue; } if (!lines[cursor].trim().endsWith('-->')) break; let commentStart = cursor; while (commentStart >= lowerBound && !lines[commentStart].trim().startsWith('`; if (syntax === 'mdx') return `{/* ${CSF3_DEPRECATION_MESSAGE} */}`; return `// ${CSF3_DEPRECATION_MESSAGE}`; } export function getCsf3SegmentsWithoutDeprecation(lines: string[]): SnippetSegment[] { return getCsfSegments(getSnippetSegments(lines)) .filter(({ version }) => version === 'csf3') .map(({ segment }) => segment) .filter( (segment) => lines[segment.fenceLine + 1] !== getCsf3DeprecationComment(segment.syntax) ); } // Returns `undefined` when every CSF 3 segment already has the comment export function addCsf3Deprecation(lines: string[]): string[] | undefined { const segments = getCsf3SegmentsWithoutDeprecation(lines); if (segments.length === 0) return undefined; const result = [...lines]; for (const segment of segments.reverse()) { result.splice(segment.fenceLine + 1, 0, getCsf3DeprecationComment(segment.syntax)); } return result; }