ghost 6.53.0 → 6.54.0

package/core/server/services/route-settings/route-settings-parser.ts

@@ -11,42 +11,62 @@ import type {
     TemplateRoute
 } from '@tryghost/adapter-base-route-settings';
 import {z} from 'zod';
-import errors from '@tryghost/errors';
 import tpl from '@tryghost/tpl';
+import type {PathSegment} from './validation-errors';
+import {describeValue, formatLocation, humanList, toValidationError, validationError} from './validation-errors';
 
 const messages = {
-    validationError: 'The following definition "{at}" is invalid: {reason}',
-    badDataError: 'Please wrap the data definition into a custom name.',
+    badDataError: '"{key}" is a reserved key. Please wrap the data definition into a custom name.',
     badDataHelp: 'Example:\n data:\n  my-tag:\n    resource: tags\n    ...\n',
-    authorDeprecatedError: 'Please choose a different name. We recommend not using author.'
+    authorDeprecatedError: '"author" is reserved. Please choose a different name. We recommend not using author.'
 };
 
-function validationError(at: string, reason: string, help?: string): errors.ValidationError {
-    return new errors.ValidationError({
-        message: tpl(messages.validationError, {at, reason}),
-        ...(help ? {help} : {})
-    });
-}
-
 const VALID_SHORTFORM_RESOURCES = ['tag', 'page', 'post', 'author'] as const;
 const VALID_LONGFORM_RESOURCES = ['tags', 'posts', 'pages', 'authors'] as const;
 const RESERVED_DATA_KEYS = ['resource', 'type', 'limit', 'order', 'include', 'filter', 'status', 'visibility', 'slug', 'redirect'];
 
-const DataShortFormSchema = z.string().superRefine((v, ctx) => {
-    if (!/^[a-zA-Z0-9_]+\.[a-zA-Z0-9_-]+$/.test(v)) {
-        ctx.addIssue({code: 'custom', message: tpl(messages.validationError, {at: v, reason: 'Incorrect Format. Please use e.g. tag.recipes'})});
-        return;
+// YAML parses a bare `filter:` as null and authors commonly quote numeric scalars
+// (`limit: "100"`); the legacy validator accepted both, so treat an explicitly empty
+// value as unset and coerce digit-only limit strings to numbers.
+const OptionalStringField = z.string().nullish().transform(v => v ?? undefined);
+const OptionalBooleanField = z.boolean().nullish().transform(v => v ?? undefined);
+const LimitField = z.union([z.number(), z.literal('all'), z.string().regex(/^\d+$/).transform(Number)])
+    .nullish().transform(v => v ?? undefined);
+
+const SHORTFORM_HELP = 'e.g. data: tag.recipes';
+
+/**
+ * Shorthand data definitions look like `tag.recipes` — resource, dot, slug.
+ *
+ * `%s` stands in for the slug: on channel routes and collections, fetch-data
+ * substitutes it with the request's `slug` param at query time, which is how a
+ * wildcard route such as `/author/:slug/` serves a different author per request.
+ * There is no static slug that could replace it, so rejecting it would break
+ * those routes.
+ */
+function validateDataShortForm(value: string, path: PathSegment[]): void {
+    if (!/^[a-zA-Z0-9_]+\.(?:%s|[a-zA-Z0-9_-]+)$/.test(value)) {
+        throw validationError(
+            formatLocation(path),
+            `"${value}" is not a valid data shorthand. Please use resource.slug, e.g. tag.recipes.`,
+            SHORTFORM_HELP
+        );
     }
-    const resource = v.split('.')[0];
+
+    const resource = value.split('.')[0];
     if (!(VALID_SHORTFORM_RESOURCES as readonly string[]).includes(resource)) {
-        ctx.addIssue({code: 'custom', message: tpl(messages.validationError, {at: v, reason: `${resource} not supported. Please use ${VALID_SHORTFORM_RESOURCES.join(', ')}.`})});
+        throw validationError(
+            formatLocation(path),
+            `resource "${resource}" is not supported. Please use ${humanList(VALID_SHORTFORM_RESOURCES)}.`,
+            SHORTFORM_HELP
+        );
     }
-});
+}
 
 const DataReadEntrySchema = z.object({
     type: z.literal('read'),
     resource: z.enum(VALID_LONGFORM_RESOURCES),
-    slug: z.string({message: 'slug is required for read data entries.'}).min(1, {message: 'slug is required for read data entries.'}),
+    slug: z.string().min(1),
     redirect: z.boolean().optional(),
     include: z.string().optional(),
     visibility: z.string().optional(),
@@ -56,90 +76,104 @@ const DataReadEntrySchema = z.object({
 const DataBrowseEntrySchema = z.object({
     type: z.literal('browse'),
     resource: z.enum(VALID_LONGFORM_RESOURCES),
-    filter: z.string().optional(),
-    limit: z.union([z.number(), z.literal('all')]).optional(),
-    order: z.string().optional(),
-    include: z.string().optional(),
-    fields: z.string().optional(),
-    visibility: z.string().optional(),
-    status: z.string().optional(),
+    filter: OptionalStringField,
+    limit: LimitField,
+    order: OptionalStringField,
+    include: OptionalStringField,
+    fields: OptionalStringField,
+    visibility: OptionalStringField,
+    status: OptionalStringField,
     page: z.number().optional()
 });
 
 const DataLongFormEntrySchema = z.discriminatedUnion('type', [DataReadEntrySchema, DataBrowseEntrySchema]);
 
-function parseDataEntry(key: string, value: unknown): DataEntry {
+const DATA_ENTRY_HELP = 'e.g.\n data:\n  my-tag:\n    resource: tags\n    type: read\n    slug: recipes\n';
+
+function parseDataEntry(value: unknown, path: PathSegment[]): DataEntry {
     if (typeof value === 'string') {
-        const result = DataShortFormSchema.safeParse(value);
-        if (!result.success) {
-            throw toValidationError(result.error);
-        }
+        validateDataShortForm(value, path);
         return value as DataShortForm;
     }
 
-    if (typeof value === 'object' && value !== null) {
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
         const result = DataLongFormEntrySchema.safeParse(value);
         if (!result.success) {
             const issue = result.error.issues[0];
-            if (issue.message.includes('discriminator')) {
-                const typeVal = (value as Record<string, unknown>).type;
-                if (typeVal === undefined) {
-                    throw validationError(JSON.stringify(value), 'type is required.');
+            const at = formatLocation(path);
+            const record = value as Record<string, unknown>;
+
+            // A failed `type` discriminator surfaces as a union issue on that
+            // key — matched on the code rather than the wording, which zod
+            // is free to change.
+            if (issue.code === 'invalid_union' && issue.path[0] === 'type') {
+                if (record.type === undefined) {
+                    throw validationError(at, 'type is required. Please use read or browse.', DATA_ENTRY_HELP);
                 }
-                throw validationError(JSON.stringify(value), `${typeVal} not supported. Please use read, browse.`);
+                throw validationError(at, `type "${record.type}" is not supported. Please use read or browse.`, DATA_ENTRY_HELP);
             }
-            if (issue.path?.includes('resource')) {
-                const resVal = (value as Record<string, unknown>).resource;
-                if (resVal === undefined) {
-                    throw validationError(JSON.stringify(value), 'resource is required.');
+            if (issue.path.includes('resource')) {
+                if (record.resource === undefined) {
+                    throw validationError(at, `resource is required. Please use ${humanList(VALID_LONGFORM_RESOURCES)}.`, DATA_ENTRY_HELP);
                 }
-                throw validationError(JSON.stringify(value), `${resVal} not supported. Please use ${VALID_LONGFORM_RESOURCES.join(', ')}.`);
+                throw validationError(at, `resource "${record.resource}" is not supported. Please use ${humanList(VALID_LONGFORM_RESOURCES)}.`, DATA_ENTRY_HELP);
+            }
+            if (issue.path.includes('slug') && !record.slug) {
+                throw validationError(at, 'slug is required for read data entries.', DATA_ENTRY_HELP);
+            }
+            throw toValidationError(result.error, path, value);
+        }
+        // Fields set to an explicitly empty value parse to undefined — drop the
+        // keys so "unset" means absent in the domain model and serialized output.
+        const entry: Record<string, unknown> = result.data;
+        for (const entryKey of Object.keys(entry)) {
+            if (entry[entryKey] === undefined) {
+                delete entry[entryKey];
             }
-            throw toValidationError(result.error);
         }
         return result.data;
     }
 
-    throw validationError(key, 'Incorrect Format. Please use e.g. tag.recipes');
+    throw validationError(
+        formatLocation(path),
+        `a data entry must be a shorthand like tag.recipes, or a map with type and resource, but ${describeValue(value)} was provided.`,
+        DATA_ENTRY_HELP
+    );
 }
 
-function parseRouteData(data: unknown): RouteData {
+function parseRouteData(data: unknown, path: PathSegment[]): RouteData {
     if (typeof data === 'string') {
-        const result = DataShortFormSchema.safeParse(data);
-        if (!result.success) {
-            throw toValidationError(result.error);
-        }
+        validateDataShortForm(data, path);
         return data as DataShortForm;
     }
 
-    if (typeof data !== 'object' || data === null) {
-        throw validationError(String(data), 'Incorrect Format. Please use e.g. tag.recipes');
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        throw validationError(
+            formatLocation(path),
+            `data must be a shorthand like tag.recipes, or a map of named data entries, but ${describeValue(data)} was provided.`,
+            DATA_ENTRY_HELP
+        );
     }
 
     const record = data as Record<string, unknown>;
 
     for (const key of Object.keys(record)) {
         if (RESERVED_DATA_KEYS.includes(key)) {
-            throw new errors.ValidationError({
-                message: tpl(messages.badDataError),
-                help: messages.badDataHelp
-            });
+            throw validationError(formatLocation([...path, key]), tpl(messages.badDataError, {key}), messages.badDataHelp);
         }
         if (key === 'author') {
-            throw new errors.ValidationError({
-                message: tpl(messages.authorDeprecatedError)
-            });
+            throw validationError(formatLocation([...path, key]), messages.authorDeprecatedError);
         }
     }
 
     const parsed: Record<string, DataEntry> = {};
     for (const [key, value] of Object.entries(record)) {
-        parsed[key] = parseDataEntry(key, value);
+        parsed[key] = parseDataEntry(value, [...path, key]);
     }
     return parsed;
 }
 
-const TemplateField = z.union([z.string(), z.array(z.string())]).optional().default([])
+const TemplateField = z.union([z.string(), z.array(z.string())]).nullish().default([])
     .transform(v => {
         if (!v || (Array.isArray(v) && v.length === 0)) {
             return [];
@@ -147,18 +181,20 @@ const TemplateField = z.union([z.string(), z.array(z.string())]).optional().defa
         return Array.isArray(v) ? v : [v];
     });
 
-const RouteObjectSchema = z.object({
+// The schemas are built per route/collection so that errors raised while
+// parsing nested `data` can name the exact path they came from.
+const routeObjectSchema = (path: PathSegment[]) => z.object({
     controller: z.literal('channel').optional(),
     template: TemplateField,
     data: z.unknown().optional(),
-    content_type: z.string().optional(),
-    filter: z.string().optional(),
-    order: z.string().optional(),
-    limit: z.union([z.number(), z.literal('all')]).optional(),
-    rss: z.boolean().optional()
+    content_type: OptionalStringField,
+    filter: OptionalStringField,
+    order: OptionalStringField,
+    limit: LimitField,
+    rss: OptionalBooleanField
 }).transform((val): Omit<Route, 'path'> => {
     const templates = val.template;
-    const data = val.data !== undefined ? parseRouteData(val.data) : undefined;
+    const data = val.data !== undefined ? parseRouteData(val.data, [...path, 'data']) : undefined;
 
     if (val.controller === 'channel') {
         const route: Omit<ChannelRoute, 'path'> = {
@@ -199,16 +235,16 @@ const RouteObjectSchema = z.object({
     return route;
 });
 
-const RawCollectionValueSchema = z.object({
-    permalink: z.string({message: 'Please define a permalink route.'}).optional(),
+const collectionValueSchema = (path: PathSegment[]) => z.object({
+    permalink: z.string().optional(),
     template: TemplateField,
     data: z.unknown().optional(),
-    filter: z.string().optional(),
-    order: z.string().optional(),
-    limit: z.union([z.number(), z.literal('all')]).optional(),
-    rss: z.boolean().optional()
+    filter: OptionalStringField,
+    order: OptionalStringField,
+    limit: LimitField,
+    rss: OptionalBooleanField
 }).transform((val): Omit<CollectionConfig, 'path'> => {
-    const data = val.data !== undefined ? parseRouteData(val.data) : undefined;
+    const data = val.data !== undefined ? parseRouteData(val.data, [...path, 'data']) : undefined;
     const collection: Omit<CollectionConfig, 'path'> = {
         permalink: val.permalink ?? '',
         templates: val.template
@@ -233,15 +269,35 @@ const RawCollectionValueSchema = z.object({
 
 const RouteSettingsSchema = z.object({
     routes: z.record(z.string(), z.unknown()).nullable().optional().default({}),
-    collections: z.record(z.string(), RawCollectionValueSchema).nullable().optional().default({}),
+    collections: z.record(z.string(), z.unknown()).nullable().optional().default({}),
     taxonomies: z.record(z.string(), z.string()).nullable().optional().default({})
 });
 
-function toValidationError(error: z.ZodError): errors.ValidationError {
-    const issue = error.issues[0];
-    return new errors.ValidationError({
-        message: issue.message
-    });
+/**
+ * Every path in routes.yaml — route paths, collection paths, permalinks and
+ * taxonomy permalinks — follows the same rules, so they share one message set.
+ *
+ * `allowParamNotation` is set for route and collection keys, which are mounted on
+ * Express verbatim: nothing rewrites `{param}` to `:param` for them the way it
+ * does for permalinks and taxonomies. So `/author/:slug/` is a working wildcard
+ * route on live sites and `/author/{slug}/` would be a dead literal path —
+ * rejecting :param there would break the former, and the suggested rewrite would
+ * silently produce the latter.
+ */
+function validatePath(value: string, path: PathSegment[], example: string, {allowParamNotation = false}: {allowParamNotation?: boolean} = {}): void {
+    const at = formatLocation(path);
+
+    if (!value.startsWith('/')) {
+        throw validationError(at, `"${value}" is missing a leading slash. Please use e.g. ${example}.`);
+    }
+    if (!value.endsWith('/')) {
+        throw validationError(at, `"${value}" is missing a trailing slash. Please use e.g. ${example}.`);
+    }
+    if (!allowParamNotation && /\/:\w+/.test(value)) {
+        // Suggest the same path in the notation Ghost expects, rather than a
+        // generic example the author then has to translate.
+        throw validationError(at, `"${value}" uses the :param notation. Please use "${value.replace(/\/:(\w+)/g, '/{$1}')}".`);
+    }
 }
 
 export function parseRouteSettings(raw: unknown, yamlSource: string): RouteSettings {
@@ -249,7 +305,7 @@ export function parseRouteSettings(raw: unknown, yamlSource: string): RouteSetti
 
     const parsed = RouteSettingsSchema.safeParse(obj);
     if (!parsed.success) {
-        throw toValidationError(parsed.error);
+        throw toValidationError(parsed.error, [], obj);
     }
 
     const {routes: rawRoutes, collections: rawCollections, taxonomies: rawTaxonomies} = parsed.data;
@@ -257,18 +313,11 @@ export function parseRouteSettings(raw: unknown, yamlSource: string): RouteSetti
     const routes: Route[] = [];
     if (rawRoutes) {
         for (const [path, value] of Object.entries(rawRoutes)) {
-            if (!path.startsWith('/')) {
-                throw validationError(path, 'A leading slash is required.');
-            }
-            if (!path.endsWith('/')) {
-                throw validationError(path, 'A trailing slash is required.');
-            }
-            if (/\/:\w+/.test(path)) {
-                throw validationError(path, 'Please use the following notation e.g. /{slug}/.');
-            }
+            const routeLocation: PathSegment[] = ['routes', path];
+            validatePath(path, routeLocation, '/about/', {allowParamNotation: true});
 
             if (value === null || value === undefined) {
-                throw validationError(path, 'Please define a template.', 'e.g. /about/: about');
+                throw validationError(formatLocation(routeLocation), 'Please define a template, e.g. /about/: about.');
             }
 
             if (typeof value === 'string') {
@@ -276,14 +325,14 @@ export function parseRouteSettings(raw: unknown, yamlSource: string): RouteSetti
                 continue;
             }
 
-            const routeResult = RouteObjectSchema.safeParse(value);
+            const routeResult = routeObjectSchema(routeLocation).safeParse(value);
             if (!routeResult.success) {
-                throw toValidationError(routeResult.error);
+                throw toValidationError(routeResult.error, routeLocation, value);
             }
 
             const route = routeResult.data;
             if (route.type === 'template' && (!route.templates || route.templates.length === 0) && !route.data && !(route as Omit<TemplateRoute, 'path'>).contentType) {
-                throw validationError(path, 'Please define a template.', 'e.g. /about/: about');
+                throw validationError(formatLocation(routeLocation), 'Please define a template, e.g. /about/: about.');
             }
 
             routes.push({...route, path} as Route);
@@ -293,49 +342,35 @@ export function parseRouteSettings(raw: unknown, yamlSource: string): RouteSetti
     const collections: CollectionConfig[] = [];
     if (rawCollections) {
         for (const [path, value] of Object.entries(rawCollections)) {
-            if (!path.startsWith('/')) {
-                throw validationError(path, 'A leading slash is required.');
-            }
-            if (!path.endsWith('/')) {
-                throw validationError(path, 'A trailing slash is required.');
-            }
-            if (/\/:\w+/.test(path)) {
-                throw validationError(path, 'Please use the following notation e.g. /{slug}/.');
-            }
-            if (!value.permalink) {
-                throw validationError(path, 'Please define a permalink route.', 'e.g. permalink: /{slug}/');
-            }
-            if (!value.permalink.startsWith('/')) {
-                throw validationError(value.permalink, 'A leading slash is required.');
-            }
-            if (!value.permalink.endsWith('/')) {
-                throw validationError(value.permalink, 'A trailing slash is required.');
+            const collectionLocation: PathSegment[] = ['collections', path];
+            validatePath(path, collectionLocation, '/blog/', {allowParamNotation: true});
+
+            const collectionResult = collectionValueSchema(collectionLocation).safeParse(value);
+            if (!collectionResult.success) {
+                throw toValidationError(collectionResult.error, collectionLocation, value);
             }
-            if (/\/:\w+/.test(value.permalink)) {
-                throw validationError(value.permalink, 'Please use the following notation e.g. /{slug}/.');
+
+            const collection = collectionResult.data;
+            if (!collection.permalink) {
+                throw validationError(formatLocation(collectionLocation), 'Please define a permalink route, e.g. permalink: /{slug}/.');
             }
-            collections.push({...value, path});
+            validatePath(collection.permalink, [...collectionLocation, 'permalink'], '/{slug}/');
+
+            collections.push({...collection, path});
         }
     }
 
     const taxonomies: TaxonomyConfig = {};
     if (rawTaxonomies) {
         for (const [key, value] of Object.entries(rawTaxonomies)) {
+            const taxonomyLocation: PathSegment[] = ['taxonomies', key];
             if (!['tag', 'author'].includes(key)) {
-                throw validationError(key, 'Unknown taxonomy.');
+                throw validationError(formatLocation(taxonomyLocation), 'Unknown taxonomy. Please use tag or author.');
             }
             if (!value) {
-                throw validationError(key, 'Please define a taxonomy permalink route.', 'e.g. tag: /tag/{slug}/');
-            }
-            if (!value.startsWith('/')) {
-                throw validationError(value, 'A leading slash is required.');
-            }
-            if (!value.endsWith('/')) {
-                throw validationError(value, 'A trailing slash is required.');
-            }
-            if (/\/:\w+/.test(value)) {
-                throw validationError(value, 'Please use the following notation e.g. /{slug}/.');
+                throw validationError(formatLocation(taxonomyLocation), `Please define a taxonomy permalink route, e.g. ${key}: /${key}/{slug}/.`);
             }
+            validatePath(value, taxonomyLocation, `/${key}/{slug}/`);
             if (key === 'tag') {
                 taxonomies.tag = value;
             }

package/core/server/services/route-settings/validation-errors.js

@@ -0,0 +1,178 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatLocation = formatLocation;
+exports.describeValue = describeValue;
+exports.humanList = humanList;
+exports.validationError = validationError;
+exports.toValidationError = toValidationError;
+const errors_1 = __importDefault(require("@tryghost/errors"));
+const tpl_1 = __importDefault(require("@tryghost/tpl"));
+const messages = {
+    validationError: 'The following definition "{at}" is invalid: {reason}'
+};
+const DOCS_URL = 'https://ghost.org/docs/themes/routing/';
+const MAX_SHOWN_LENGTH = 40;
+/**
+ * Renders the path to the offending value the way an author would find it in
+ * their file, e.g. `routes['/about/'].template[1]`.
+ */
+function formatLocation(path) {
+    if (path.length === 0) {
+        return 'routes.yaml';
+    }
+    return path.reduce((out, segment) => {
+        if (typeof segment === 'number') {
+            return `${out}[${segment}]`;
+        }
+        if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(segment)) {
+            return out ? `${out}.${segment}` : segment;
+        }
+        return `${out}['${segment.replace(/\\/g, '\\\\').replace(/'/g, '\\\'')}']`;
+    }, '');
+}
+/**
+ * Names what the author actually wrote, so the error can contrast it with what
+ * was expected. Reads as the "but <this> was provided" half of a message.
+ */
+function describeValue(value) {
+    if (value === null || value === undefined) {
+        return 'nothing';
+    }
+    if (Array.isArray(value)) {
+        return 'a list';
+    }
+    if (value instanceof Date) {
+        return 'a date';
+    }
+    if (typeof value === 'object') {
+        return 'a map';
+    }
+    if (typeof value === 'string') {
+        const shown = value.length > MAX_SHOWN_LENGTH ? `${value.slice(0, MAX_SHOWN_LENGTH)}…` : value;
+        return `the text "${shown}"`;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return 'an unsupported value';
+}
+/**
+ * Lists options the way a sentence would, e.g. "posts, pages or tags".
+ */
+function humanList(items) {
+    if (items.length < 2) {
+        return items.join('');
+    }
+    return `${items.slice(0, -1).join(', ')} or ${items[items.length - 1]}`;
+}
+/**
+ * What each key in routes.yaml accepts, phrased so the message reads
+ * "<key> must be <expectation>".
+ */
+const FIELD_EXPECTATIONS = {
+    routes: 'a map of route paths (e.g. /about/: about)',
+    collections: 'a map of collection paths (e.g. /blog/: {permalink: /{slug}/})',
+    taxonomies: 'a map of tag and/or author permalinks (e.g. tag: /tag/{slug}/)',
+    controller: 'channel, the only supported controller',
+    template: 'a template name, or a list of template names (e.g. template: index)',
+    permalink: 'a route with a leading and trailing slash (e.g. permalink: /{slug}/)',
+    content_type: 'a content type (e.g. content_type: text/xml)',
+    filter: 'a filter string (e.g. filter: featured:true)',
+    order: 'an order string (e.g. order: published_at desc)',
+    limit: 'a number or "all" (e.g. limit: 5)',
+    include: 'a comma-separated string (e.g. include: authors,tags)',
+    fields: 'a comma-separated string (e.g. fields: title,slug)',
+    visibility: 'a string (e.g. visibility: public)',
+    status: 'a string (e.g. status: published)',
+    slug: 'a slug (e.g. slug: welcome)',
+    page: 'a number (e.g. page: 2)',
+    rss: 'true or false',
+    redirect: 'true or false'
+};
+const CONTAINER_EXPECTATIONS = {
+    routes: { subject: 'a route', expectation: 'a template name, or a map of route options (e.g. template, controller, data)' },
+    collections: { subject: 'a collection', expectation: 'a map of collection options (e.g. permalink, template, filter)' }
+};
+/**
+ * Keys that accept a list: saying "a list was provided" would contradict the
+ * expectation, so the entries are blamed instead.
+ */
+const LIST_ENTRY_PROBLEMS = {
+    template: 'one or more of the entries is not a template name'
+};
+function lookup(table, key) {
+    return typeof key === 'string' && Object.prototype.hasOwnProperty.call(table, key) ? table[key] : undefined;
+}
+/**
+ * The key a failure belongs to — for a list entry that is the key holding the
+ * list, not the index.
+ */
+function fieldKey(path) {
+    const last = path[path.length - 1];
+    return typeof last === 'number' ? path[path.length - 2] : last;
+}
+/**
+ * Resolves the "<subject> must be <expectation>" half of a message for the
+ * value at `path`. Returns null when the key is unknown, in which case the
+ * caller falls back to the underlying schema message.
+ */
+function describeExpectation(path) {
+    if (path.length === 0) {
+        return { subject: 'the file', expectation: 'a map of routes, collections or taxonomies' };
+    }
+    const [section] = path;
+    // A whole section, e.g. `routes: hello`
+    if (path.length === 1) {
+        const expectation = lookup(FIELD_EXPECTATIONS, section);
+        return expectation ? { subject: String(section), expectation } : null;
+    }
+    // A single route or collection, e.g. `routes: {/about/: [a, b]}`
+    if (path.length === 2 && typeof section === 'string' && Object.prototype.hasOwnProperty.call(CONTAINER_EXPECTATIONS, section)) {
+        return CONTAINER_EXPECTATIONS[section];
+    }
+    // A taxonomy permalink, e.g. `taxonomies: {tag: 5}`
+    if (path.length === 2 && section === 'taxonomies') {
+        return { subject: `the ${String(path[1])} taxonomy`, expectation: `a permalink route (e.g. ${String(path[1])}: /${String(path[1])}/{slug}/)` };
+    }
+    const expectation = lookup(FIELD_EXPECTATIONS, fieldKey(path));
+    return expectation ? { subject: String(fieldKey(path)), expectation } : null;
+}
+function valueAtPath(value, path) {
+    return path.reduce((current, segment) => {
+        if (current === null || typeof current !== 'object') {
+            return undefined;
+        }
+        return current[segment];
+    }, value);
+}
+function validationError(at, reason, help) {
+    return new errors_1.default.ValidationError({
+        message: (0, tpl_1.default)(messages.validationError, { at, reason }),
+        ...(help ? { help } : {})
+    });
+}
+/**
+ * Turns a schema failure into an error that names the exact key in routes.yaml
+ * and says what that key accepts — schema messages on their own only say
+ * things like "Invalid input: expected string, received number".
+ *
+ * @param error  the schema failure
+ * @param basePath path of the value that was handed to the schema
+ * @param value  that same value, used to describe what the author wrote
+ */
+function toValidationError(error, basePath = [], value) {
+    const issue = error.issues[0];
+    const issuePath = issue.path;
+    const path = [...basePath, ...issuePath];
+    const expectation = describeExpectation(path);
+    if (!expectation) {
+        return validationError(formatLocation(path), issue.message, DOCS_URL);
+    }
+    const provided = valueAtPath(value, issuePath);
+    const listProblem = Array.isArray(provided) ? lookup(LIST_ENTRY_PROBLEMS, fieldKey(path)) : undefined;
+    const found = listProblem ?? `${describeValue(provided)} was provided`;
+    return validationError(formatLocation(path), `${expectation.subject} must be ${expectation.expectation}, but ${found}.`, DOCS_URL);
+}