@astrojs/starlight 0.41.11 → 0.42.0

package/utils/createTranslationSystem.ts

@@ -1,137 +0,0 @@
-import i18next, { type ExistsFunction, type TFunction } from 'i18next';
-import type { i18nSchemaOutput } from '../schemas/i18n';
-import builtinTranslations from '../translations/index';
-import { BuiltInDefaultLocale } from './i18n';
-import type { StarlightConfig } from './user-config';
-import type { UserI18nKeys, UserI18nSchema } from './translations';
-
-/**
- * The namespace for i18next resources used by Starlight.
- * All translations handled by Starlight are stored in the same namespace and Starlight always use
- * a new instance of i18next configured for this namespace.
- */
-export const I18nextNamespace = 'starlight' as const;
-
-export async function createTranslationSystem<T extends i18nSchemaOutput>(
-	config: Pick<StarlightConfig, 'defaultLocale' | 'locales'>,
-	userTranslations: Record<string, T>,
-	pluginTranslations: Record<string, T> = {}
-) {
-	const defaultLocale =
-		config.defaultLocale.lang || config.defaultLocale?.locale || BuiltInDefaultLocale.lang;
-
-	const translations = {
-		[defaultLocale]: buildResources(
-			builtinTranslations[defaultLocale] || builtinTranslations[stripLangRegion(defaultLocale)],
-			pluginTranslations[defaultLocale],
-			userTranslations[defaultLocale]
-		),
-	};
-
-	if (config.locales) {
-		for (const locale in config.locales) {
-			const lang = localeToLang(locale, config.locales, config.defaultLocale);
-
-			translations[lang] = buildResources(
-				builtinTranslations[lang] || builtinTranslations[stripLangRegion(lang)],
-				pluginTranslations[lang],
-				userTranslations[lang]
-			);
-		}
-	}
-
-	const i18n = i18next.createInstance();
-	await i18n.init({
-		resources: translations,
-		fallbackLng:
-			config.defaultLocale.lang || config.defaultLocale?.locale || BuiltInDefaultLocale.lang,
-	});
-
-	/**
-	 * Generate a utility function that returns UI strings for the given language.
-	 *
-	 * Also includes a few utility methods:
-	 * - `all()` method for getting the entire dictionary.
-	 * - `exists()` method for checking if a key exists in the dictionary.
-	 * - `dir()` method for getting the text direction of the locale.
-	 *
-	 * @param {string | undefined} [lang]
-	 * @example
-	 * const t = useTranslations('en');
-	 * const label = t('search.label');
-	 * // => 'Search'
-	 * const dictionary = t.all();
-	 * // => { 'skipLink.label': 'Skip to content', 'search.label': 'Search', ... }
-	 * const exists = t.exists('search.label');
-	 * // => true
-	 * const dir = t.dir();
-	 * // => 'ltr'
-	 */
-	return (lang: string | undefined) => {
-		lang ??= config.defaultLocale?.lang || BuiltInDefaultLocale.lang;
-
-		const t = i18n.getFixedT(lang, I18nextNamespace) as I18nT;
-		t.all = () => i18n.getResourceBundle(lang, I18nextNamespace) as ReturnType<I18nT['all']>;
-		// Since i18next 25.10.4 the `ExistsFunction` type has a signature including a predicate that
-		// TS cannot preserve when composing a new function to add default options.
-		// See: https://github.com/i18next/i18next/issues/2425
-		t.exists = ((key, options) =>
-			i18n.exists(key, { lng: lang, ns: I18nextNamespace, ...options })) as ExistsFunction;
-		t.dir = (dirLang = lang) => i18n.dir(dirLang);
-
-		return t;
-	};
-}
-
-/**
- * Strips the region subtag from a BCP-47 lang string.
- * @param {string} [lang]
- * @example
- * const lang = stripLangRegion('en-GB'); // => 'en'
- */
-function stripLangRegion(lang: string) {
-	return lang.replace(/-[a-zA-Z]{2}/, '');
-}
-
-/**
- * Get the BCP-47 language tag for the given locale.
- * @param locale Locale string or `undefined` for the root locale.
- */
-function localeToLang(
-	locale: string | undefined,
-	locales: StarlightConfig['locales'],
-	defaultLocale: StarlightConfig['defaultLocale']
-): string {
-	const lang = locale ? locales?.[locale]?.lang : locales?.root?.lang;
-	const defaultLang = defaultLocale?.lang || defaultLocale?.locale;
-	return lang || defaultLang || BuiltInDefaultLocale.lang;
-}
-
-type BuiltInStrings = (typeof builtinTranslations)['en'];
-
-/** Build an i18next resources dictionary by layering preferred translation sources. */
-function buildResources<T extends i18nSchemaOutput>(
-	...dictionaries: (T | BuiltInStrings | undefined)[]
-): { [I18nextNamespace]: BuiltInStrings & T } {
-	const dictionary: Partial<BuiltInStrings> = {};
-	// Iterate over alternate dictionaries to avoid overwriting preceding values with `undefined`.
-	for (const dict of dictionaries) {
-		for (const key in dict) {
-			const value = dict[key as keyof typeof dict];
-			if (value) dictionary[key as keyof typeof dictionary] = value;
-		}
-	}
-	return { [I18nextNamespace]: dictionary as BuiltInStrings & T };
-}
-
-// `keyof BuiltInStrings` and `UserI18nKeys` may contain some identical keys, e.g. the built-in UI
-// strings. We let TypeScript merge them into a single union type so that plugins with a TypeScript
-// configuration preventing `UserI18nKeys` to be properly inferred can still get auto-completion
-// for built-in UI strings.
-export type I18nKeys = keyof BuiltInStrings | UserI18nKeys | keyof StarlightApp.I18n;
-
-export type I18nT = TFunction<'starlight', undefined> & {
-	all: () => UserI18nSchema;
-	exists: ExistsFunction;
-	dir: (lang?: string) => 'ltr' | 'rtl';
-};

package/utils/error-map.ts

@@ -1,222 +0,0 @@
-/**
- * This is a modified version of Astro's error map.
- * source: https://github.com/withastro/astro/blob/main/packages/astro/src/content/error-map.ts
- */
-
-import { AstroError } from 'astro/errors';
-import { z, locales } from 'astro/zod';
-
-// The default Zod error map that we use to retrieve default error messages.
-const zodErrorMap = locales.en().localeError;
-
-type TypeErrByPathEntry = {
-	code: 'invalid_type';
-	received: unknown;
-	expected: unknown[];
-	message: string | undefined;
-};
-
-/**
- * Parse data with a Zod schema and throw a nicely formatted error if it is invalid.
- *
- * @param schema The Zod schema to use to parse the input.
- * @param input Input data that should match the schema.
- * @param message Error message preamble to use if the input fails to parse.
- * @returns Validated data parsed by Zod.
- */
-export function parseWithFriendlyErrors<T extends z.ZodType>(
-	schema: T,
-	input: z.input<T>,
-	message: string
-): z.output<T> {
-	return processParsedData<T>(
-		schema.safeParse(input, { error: errorMap, reportInput: true }),
-		message
-	);
-}
-
-/**
- * Asynchronously parse data with a Zod schema that contains asynchronous refinements or transforms
- * and throw a nicely formatted error if it is invalid.
- *
- * @param schema The Zod schema to use to parse the input.
- * @param input Input data that should match the schema.
- * @param message Error message preamble to use if the input fails to parse.
- * @returns Validated data parsed by Zod.
- */
-export async function parseAsyncWithFriendlyErrors<T extends z.ZodType>(
-	schema: T,
-	input: z.input<T>,
-	message: string
-): Promise<z.output<T>> {
-	return processParsedData<T>(
-		await schema.safeParseAsync(input, { error: errorMap, reportInput: true }),
-		message
-	);
-}
-
-function processParsedData<T extends z.ZodType>(
-	parsedData: z.ZodSafeParseResult<z.output<T>>,
-	message: string
-) {
-	if (!parsedData.success) {
-		throw new AstroError(message, parsedData.error.issues.map((i) => i.message).join('\n'));
-	}
-	return parsedData.data;
-}
-
-const errorMap: z.core.$ZodErrorMap = (issue) => {
-	const baseErrorPath = flattenErrorPath(issue.path ?? []);
-	if (issue.code === 'invalid_union') {
-		// Optimization: Combine type and literal errors for keys that are common across ALL union types
-		// Ex. a union between `{ key: z.literal('tutorial') }` and `{ key: z.literal('blog') }` will
-		// raise a single error when `key` does not match:
-		// > Did not match union.
-		// > key: Expected `'tutorial' | 'blog'`, received 'foo'
-		const unionErrors = issue.errors.flat();
-		const typeOrLiteralErrByPath: Map<string, TypeErrByPathEntry> = new Map();
-		for (const unionError of unionErrors) {
-			if (unionError.code === 'invalid_type') {
-				const flattenedErrorPath = flattenErrorPath([baseErrorPath, ...unionError.path]);
-				if (typeOrLiteralErrByPath.has(flattenedErrorPath)) {
-					typeOrLiteralErrByPath.get(flattenedErrorPath)!.expected.push(unionError.expected);
-				} else {
-					typeOrLiteralErrByPath.set(flattenedErrorPath, {
-						code: unionError.code,
-						received: parsedType(issue.input),
-						expected: [unionError.expected],
-						message: unionError.message,
-					});
-				}
-			}
-		}
-		const messages: string[] = [prefix(baseErrorPath, 'Did not match union.')];
-		const details: string[] = [...typeOrLiteralErrByPath.entries()]
-			// If type or literal error isn't common to ALL union types,
-			// filter it out. Can lead to confusing noise.
-			.filter(([, error]) => error.expected.length === unionErrors.length)
-			.map(([key, error]) =>
-				key === baseErrorPath
-					? // Avoid printing the key again if it's a base error
-						`> ${getTypeErrMsg(error)}`
-					: `> ${prefix(key, getTypeErrMsg(error))}`
-			);
-
-		if (details.length === 0) {
-			const expectedShapes: string[] = [];
-			for (const unionError of issue.errors) {
-				const expectedShape: string[] = [];
-				for (const issue of unionError) {
-					// We sometimes use `z.NEVER` to explicitly error on certain property combinations in
-					// non-discriminated unions to make it easier for users to identify invalid config, e.g.
-					// autogenerated groups in the sidebar no longer being supported. Having these properties
-					// show up in the error message with an expected type of `never` is noisy and not helpful
-					// so we skip them here.
-					if (issue.code === 'invalid_type' && issue.expected === 'never') continue;
-					// If the issue is a nested union error, show the associated error message instead of the
-					// base error message.
-					if (issue.code === 'invalid_union') {
-						return errorMap({ ...issue, input: issue.input, path: [baseErrorPath, ...issue.path] });
-					}
-					const relativePath = flattenErrorPath(issue.path)
-						.replace(baseErrorPath, '')
-						.replace(leadingPeriod, '');
-					if (issue.code === 'invalid_type') {
-						expectedShape.push(
-							relativePath ? `${relativePath}: ${issue.expected}` : issue.expected
-						);
-					} else if (issue.code === 'custom') {
-						expectedShape.push(relativePath);
-					}
-				}
-				if (expectedShape.length === 1 && !expectedShape[0]?.includes(':')) {
-					// In this case the expected shape is not an object, but probably a literal type, e.g. `['string']`.
-					expectedShapes.push(expectedShape.join(''));
-				} else if (expectedShape.length > 0) {
-					expectedShapes.push(`{ ${expectedShape.join('; ')} }`);
-				}
-			}
-			if (expectedShapes.length) {
-				details.push('> Expected type `' + expectedShapes.join(' | ') + '`');
-				details.push('> Received `' + stringify(issue.input) + '`');
-			}
-		}
-
-		return messages.concat(details).join('\n');
-	} else if (issue.code === 'invalid_type') {
-		return prefix(
-			baseErrorPath,
-			getTypeErrMsg({
-				code: issue.code,
-				received: parsedType(issue.input),
-				expected: [issue.expected],
-				message: issue.message,
-			})
-		);
-	} else if (issue.message) {
-		return prefix(baseErrorPath, issue.message);
-	} else {
-		// By design, the default Zod error may not be provided in Zod 4 error maps. Instead, error
-		// maps are supposed to return `undefined` in order to yield control to the next error map in
-		// the precedence chain. Unfortunately, this prevents us from prefixing all errors with their
-		// paths so we have to manually invoke the default Zod error map here.
-		const defaultError = zodErrorMap(issue);
-		if (!defaultError) return;
-
-		return prefix(
-			baseErrorPath,
-			typeof defaultError === 'string' ? defaultError : defaultError.message
-		);
-	}
-};
-
-const getTypeErrMsg = (error: TypeErrByPathEntry): string => {
-	// received could be `undefined` or the string `'undefined'`
-	if (typeof error.received === 'undefined' || error.received === 'undefined')
-		return error.message ?? 'Required';
-	const expectedDeduped = new Set(error.expected);
-	return `Expected type \`${unionExpectedVals(expectedDeduped)}\`, received \`${stringify(
-		error.received
-	)}\``;
-};
-
-const prefix = (key: string, msg: string) => (key.length ? `**${key}**: ${msg}` : msg);
-
-const unionExpectedVals = (expectedVals: Set<unknown>) =>
-	[...expectedVals].map((expectedVal) => stringify(expectedVal)).join(' | ');
-
-const flattenErrorPath = (errorPath: PropertyKey[]) => errorPath.join('.');
-
-/** `JSON.stringify()` a value with spaces around object/array entries. */
-const stringify = (val: unknown) =>
-	JSON.stringify(val, null, 1).split(newlinePlusWhitespace).join(' ');
-const newlinePlusWhitespace = /\n\s*/;
-const leadingPeriod = /^\./;
-
-/**
- * In Zod 4, we don't necessarily get a human-readable representation of input data types. For such
- * cases, we use the same logic as Zod's own `parsedType()` function.
- * @see https://github.com/colinhacks/zod/blob/73b071d7d08825dedb6b48b78718739118ee1308/packages/zod/src/v4/locales/en.ts#L5
- */
-const parsedType = (data: unknown): string => {
-	const t = typeof data;
-
-	switch (t) {
-		case 'number': {
-			return Number.isNaN(data) ? 'NaN' : 'number';
-		}
-		case 'object': {
-			if (Array.isArray(data)) {
-				return 'array';
-			}
-			if (data === null) {
-				return 'null';
-			}
-
-			if (data && Object.getPrototypeOf(data) !== Object.prototype && data.constructor) {
-				return data.constructor.name;
-			}
-		}
-	}
-	return t;
-};

package/utils/format-path.ts

@@ -1,7 +0,0 @@
-import project from 'virtual:starlight/project-context';
-import { createPathFormatter } from './createPathFormatter';
-
-export const formatPath = createPathFormatter({
-	format: project.build.format,
-	trailingSlash: project.trailingSlash,
-});

package/utils/generateToC.ts

@@ -1,33 +0,0 @@
-import type { MarkdownHeading } from 'astro';
-import { PAGE_TITLE_ID } from '../constants';
-
-export interface TocItem extends MarkdownHeading {
-	children: TocItem[];
-}
-
-interface TocOpts {
-	minHeadingLevel: number;
-	maxHeadingLevel: number;
-	title: string;
-}
-
-/** Convert the flat headings array generated by Astro into a nested tree structure. */
-export function generateToC(
-	headings: MarkdownHeading[],
-	{ minHeadingLevel, maxHeadingLevel, title }: TocOpts
-) {
-	headings = headings.filter(({ depth }) => depth >= minHeadingLevel && depth <= maxHeadingLevel);
-	const toc: Array<TocItem> = [{ depth: 2, slug: PAGE_TITLE_ID, text: title, children: [] }];
-	for (const heading of headings) injectChild(toc, { ...heading, children: [] });
-	return toc;
-}
-
-/** Inject a ToC entry as deep in the tree as its `depth` property requires. */
-function injectChild(items: TocItem[], item: TocItem): void {
-	const lastItem = items.at(-1);
-	if (!lastItem || lastItem.depth >= item.depth) {
-		items.push(item);
-	} else {
-		return injectChild(lastItem.children, item);
-	}
-}

package/utils/git.ts

@@ -1,121 +0,0 @@
-/**
- * Git module to be used from the dev server and from the integration.
- */
-
-import { basename, dirname, relative, resolve } from 'node:path';
-import { realpathSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
-
-export type GitAPI = {
-	getNewestCommitDate: (file: string) => Date;
-};
-
-export const makeAPI = (directory: string): GitAPI => {
-	return {
-		getNewestCommitDate: (file) => getNewestCommitDate(resolve(directory, file)),
-	};
-};
-
-export function getNewestCommitDate(file: string): Date {
-	const result = spawnSync('git', ['log', '--format=%ct', '--max-count=1', basename(file)], {
-		cwd: dirname(file),
-		encoding: 'utf-8',
-	});
-
-	if (result.error) {
-		throw new Error(`Failed to retrieve the git history for file "${file}"`);
-	}
-	const output = result.stdout.trim();
-	const regex = /^(?<timestamp>\d+)$/;
-	const match = output.match(regex);
-
-	if (!match?.groups?.timestamp) {
-		throw new Error(`Failed to validate the timestamp for file "${file}"`);
-	}
-
-	const timestamp = Number(match.groups.timestamp);
-	const date = new Date(timestamp * 1000);
-	return date;
-}
-
-function getRepoRoot(directory: string): string {
-	const result = spawnSync('git', ['rev-parse', '--show-toplevel'], {
-		cwd: directory,
-		encoding: 'utf-8',
-	});
-
-	if (result.error) {
-		return directory;
-	}
-
-	try {
-		return realpathSync(result.stdout.trim());
-	} catch {
-		return directory;
-	}
-}
-
-export function getAllNewestCommitDate(rootPath: string, docsPath: string): [string, number][] {
-	const repoRoot = getRepoRoot(docsPath);
-
-	const gitLog = spawnSync(
-		'git',
-		[
-			'log',
-			// Format each history entry as t:<seconds since epoch>
-			'--format=t:%ct',
-			// In each entry include the name and status for each modified file
-			'--name-status',
-			'--',
-			docsPath,
-		],
-		{
-			cwd: repoRoot,
-			encoding: 'utf-8',
-			// The default `maxBuffer` for `spawnSync` is 1024 * 1024 bytes, a.k.a 1 MB. In big projects,
-			// the full git history can be larger than this, so we increase this to ~10 MB. For example,
-			// Cloudflare passed 1 MB with ~4,800 pages and ~17,000 commits. If we get reports of others
-			// hitting ENOBUFS errors here in the future, we may want to switch to streaming the git log
-			// with `spawn` instead.
-			// See https://github.com/withastro/starlight/issues/3154
-			maxBuffer: 10 * 1024 * 1024,
-		}
-	);
-
-	if (gitLog.error) {
-		return [];
-	}
-
-	let runningDate = Date.now();
-	const latestDates = new Map<string, number>();
-
-	for (const logLine of gitLog.stdout.split('\n')) {
-		if (logLine.startsWith('t:')) {
-			// t:<seconds since epoch>
-			runningDate = Number.parseInt(logLine.slice(2)) * 1000;
-		}
-
-		// - Added files take the format `A\t<file>`
-		// - Modified files take the format `M\t<file>`
-		// - Deleted files take the format `D\t<file>`
-		// - Renamed files take the format `R<count>\t<old>\t<new>`
-		// - Copied files take the format `C<count>\t<old>\t<new>`
-		// The name of the file as of the commit being processed is always
-		// the last part of the log line.
-		const tabSplit = logLine.lastIndexOf('\t');
-		if (tabSplit === -1) continue;
-		const fileName = logLine.slice(tabSplit + 1);
-
-		const currentLatest = latestDates.get(fileName) || 0;
-		latestDates.set(fileName, Math.max(currentLatest, runningDate));
-	}
-
-	return Array.from(latestDates.entries()).map(([file, date]) => {
-		const fileFullPath = resolve(repoRoot, file);
-		let fileInDirectory = relative(rootPath, fileFullPath);
-		// Format path to unix style path.
-		fileInDirectory = fileInDirectory?.replace(/\\/g, '/');
-
-		return [fileInDirectory, date];
-	});
-}

package/utils/gitInlined.ts

@@ -1,20 +0,0 @@
-/**
- * Git module to be used on production build results.
- * The API is based on inlined git information.
- */
-
-import type { GitAPI, getAllNewestCommitDate } from './git';
-
-type InlinedData = ReturnType<typeof getAllNewestCommitDate>;
-
-export const makeAPI = (data: InlinedData): GitAPI => {
-	const trackedDocsFiles = new Map(data);
-
-	return {
-		getNewestCommitDate: (file) => {
-			const timestamp = trackedDocsFiles.get(file);
-			if (!timestamp) throw new Error(`Failed to retrieve the git history for file "${file}"`);
-			return new Date(timestamp);
-		},
-	};
-};