Infrastructure/astro
0
Fork 0
mirror of https://github.com/withastro/astro.git synced 2025-02-17 22:44:24 -05:00
Code Issues Activity

[docs] fix some error message syntax and add some lint rules to help (#9651)

Browse source 
Co-authored-by: Princesseuh <3019731+Princesseuh@users.noreply.github.com>
This commit is contained in:
Sarah Rainsberger 2024-01-09 16:56:28 -04:00 • committed by GitHub
parent 243146de2a
commit a1b56ee1fa
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 74 additions and 57 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
.eslintrc.cjs
View file

@ -117,5 +117,13 @@ module.exports = {
'no-console': 'off',
},
},
{
files: ['packages/astro/src/core/errors/errors-data.ts'],
rules: {
// This file is used for docs generation, as such the code need to be in a certain format, we can somewhat ensure this with these rules
'object-shorthand': ['error', 'methods', { avoidExplicitReturnArrows: true }],
'arrow-body-style': ['error', 'never'],
},
},
],
};

2
packages/astro/src/core/errors/dev/utils.ts
View file

@ -214,7 +214,7 @@ function cleanErrorStack(stack: string) {
}
export function getDocsForError(err: ErrorWithMetadata): string | undefined {
if (err.name in AstroErrorData) {
if (err.name !== 'UnknownError' && err.name in AstroErrorData) {
return `https://docs.astro.build/en/reference/errors/${getKebabErrorName(err.name)}/`;
}

121
packages/astro/src/core/errors/errors-data.ts
View file

@ -16,6 +16,7 @@ export interface ErrorData {
* @kind heading
* @name Astro Errors
*/
// Astro Errors, most errors will go here!
/**
* @docs
* @message
@ -440,7 +441,7 @@ export const NoMatchingImport = {
export const InvalidPrerenderExport = {
name: 'InvalidPrerenderExport',
title: 'Invalid prerender export.',
message: (prefix: string, suffix: string, isHydridOuput: boolean) => {
message(prefix: string, suffix: string, isHydridOuput: boolean) {
const defaultExpectedValue = isHydridOuput ? 'false' : 'true';
let msg = `A \`prerender\` export has been detected, but its value cannot be statically analyzed.`;
if (prefix !== 'const') msg += `\nExpected \`const\` declaration but got \`${prefix}\`.`;
@ -987,12 +988,51 @@ export const FailedToFindPageMapSSR = {
message:
"Astro couldn't find the correct page to render, probably because it wasn't correctly mapped for SSR usage. This is an internal error. Please file an issue.",
} satisfies ErrorData;
/**
* @docs
* @description
* Astro can't find the requested locale. All supported locales must be configured in [i18n.locales](/en/reference/configuration-reference/#i18nlocales) and have corresponding directories within `src/pages/`.
*/
export const MissingLocale = {
name: 'MissingLocaleError',
title: 'The provided locale does not exist.',
message: (locale: string) =>
`The locale/path \`${locale}\` does not exist in the configured \`i18n.locales\`.`,
} satisfies ErrorData;
/**
* @docs
* @description
* Astro could not find an associated file with content while trying to render the route. This is an Astro error and not a user error. If restarting the dev server does not fix the problem, please file an issue.
*/
export const CantRenderPage = {
name: 'CantRenderPage',
title: "Astro can't render the route.",
message:
'Astro cannot find any content to render for this route. There is no file or redirect associated with this route.',
hint: 'If you expect to find a route here, this may be an Astro bug. Please file an issue/restart the dev server',
} satisfies ErrorData;
/**
* @docs
* @description
* Astro could not find any code to handle a rejected `Promise`. Make sure all your promises have an `await` or `.catch()` handler.
*/
export const UnhandledRejection = {
name: 'UnhandledRejection',
title: 'Unhandled rejection',
message: (stack: string) =>
`Astro detected an unhandled rejection. Here's the stack trace:\n${stack}`,
hint: 'Make sure your promises all have an `await` or a `.catch()` handler.',
} satisfies ErrorData;
/**
* @docs
* @kind heading
* @name CSS Errors
*/
// CSS Errors - 5xxx
// CSS Errors
/**
* @docs
* @see
@ -1022,7 +1062,7 @@ export const CSSSyntaxError = {
* @kind heading
* @name Markdown Errors
*/
// Markdown Errors - 6xxx
// Markdown Errors
/**
* @docs
* @description
@ -1121,7 +1161,7 @@ export const ConfigLegacyKey = {
* @kind heading
* @name CLI Errors
*/
// CLI Errors - 8xxx
// CLI Errors
/**
* @docs
* @description
@ -1152,7 +1192,7 @@ export const GenerateContentTypesError = {
* @kind heading
* @name Content Collection Errors
*/
// Content Collection Errors - 9xxx
// Content Collection Errors
/**
* @docs
* @description
@ -1181,7 +1221,7 @@ export const UnknownContentCollectionError = {
export const InvalidContentEntryFrontmatterError = {
name: 'InvalidContentEntryFrontmatterError',
title: 'Content entry frontmatter does not match schema.',
message: (collection: string, entryId: string, error: ZodError) => {
message(collection: string, entryId: string, error: ZodError) {
return [
`**${String(collection)} → ${String(
entryId
@ -1202,7 +1242,7 @@ export const InvalidContentEntryFrontmatterError = {
export const InvalidContentEntrySlugError = {
name: 'InvalidContentEntrySlugError',
title: 'Invalid content entry slug.',
message: (collection: string, entryId: string) => {
message(collection: string, entryId: string) {
return `${String(collection)} → ${String(
entryId
)} has an invalid slug. \`slug\` must be a string.`;
@ -1240,7 +1280,6 @@ export const CollectionDoesNotExistError = {
} satisfies ErrorData;
/**
* @docs
* @message `COLLECTION_NAME` contains a mix of content and data entries. All entries must be of the same type.
* @see
* - [Defining content collections](https://docs.astro.build/en/guides/content-collections/#defining-collections)
* @description
@ -1249,14 +1288,12 @@ export const CollectionDoesNotExistError = {
export const MixedContentDataCollectionError = {
name: 'MixedContentDataCollectionError',
title: 'Content and data cannot be in same collection.',
message: (collection: string) => {
return `**${collection}** contains a mix of content and data entries. All entries must be of the same type.`;
},
message: (collectionName: string) =>
`**${collectionName}** contains a mix of content and data entries. All entries must be of the same type.`,
hint: 'Store data entries in a new collection separate from your content collection.',
} satisfies ErrorData;
/**
* @docs
* @message `COLLECTION_NAME` contains entries of type `ACTUAL_TYPE`, but is configured as a `EXPECTED_TYPE` collection.
* @see
* - [Defining content collections](https://docs.astro.build/en/guides/content-collections/#defining-collections)
* @description
@ -1265,9 +1302,8 @@ export const MixedContentDataCollectionError = {
export const ContentCollectionTypeMismatchError = {
name: 'ContentCollectionTypeMismatchError',
title: 'Collection contains entries of a different type.',
message: (collection: string, expectedType: string, actualType: string) => {
return `${collection} contains ${expectedType} entries, but is configured as a ${actualType} collection.`;
},
message: (collection: string, expectedType: string, actualType: string) =>
`${collection} contains ${expectedType} entries, but is configured as a ${actualType} collection.`,
} satisfies ErrorData;
/**
* @docs
@ -1278,7 +1314,7 @@ export const ContentCollectionTypeMismatchError = {
export const DataCollectionEntryParseError = {
name: 'DataCollectionEntryParseError',
title: 'Data collection entry failed to parse.',
message: (entryId: string, errorMessage: string) => {
message(entryId: string, errorMessage: string) {
return `**${entryId}** failed to parse: ${errorMessage}`;
},
hint: 'Ensure your data entry is an object with valid JSON (for `.json` entries) or YAML (for `.yaml` entries).',
@ -1292,7 +1328,7 @@ export const DataCollectionEntryParseError = {
export const DuplicateContentEntrySlugError = {
name: 'DuplicateContentEntrySlugError',
title: 'Duplicate content entry slug.',
message: (collection: string, slug: string, preExisting: string, alsoFound: string) => {
message(collection: string, slug: string, preExisting: string, alsoFound: string) {
return (
`**${collection}** contains multiple entries with the same slug: \`${slug}\`. ` +
`Slugs must be unique.\n\n` +
@ -1318,45 +1354,18 @@ export const UnsupportedConfigTransformError = {
hint: 'See the devalue library for all supported types: https://github.com/rich-harris/devalue',
} satisfies ErrorData;
/**
* @docs
* @description
* Astro can't find the requested locale. All supported locales must be configured in [i18n.locales](en/reference/configuration-reference/#i18nlocales) and have corresponding directories within `src/pages/`.
*/
export const MissingLocale = {
name: 'MissingLocaleError',
title: 'The provided locale does not exist.',
message: (locale: string) => {
return `The locale/path \`${locale}\` does not exist in the configured \`i18n.locales\`.`;
},
} satisfies ErrorData;
/**
* @docs
* @description
* Astro could not find an associated file with content while trying to render the route. This is an Astro error and not a user error. If restarting the dev server does not fix the problem, please file an issue.
*/
export const CantRenderPage = {
name: 'CantRenderPage',
title: "Astro can't render the route.",
message:
'Astro cannot find any content to render for this route. There is no file or redirect associated with this route.',
hint: 'If you expect to find a route here, this may be an Astro bug. Please file an issue/restart the dev server',
} satisfies ErrorData;
// Generic catch-all - Only use this in extreme cases, like if there was a cosmic ray bit flip
// Generic catch-all - Only use this in extreme cases, like if there was a cosmic ray bit flip.
export const UnknownError = { name: 'UnknownError', title: 'Unknown Error.' } satisfies ErrorData;
/**
* @docs
* @description
* Astro could not find any code to handle a rejected `Promise`. Make sure all your promises have an `await` or `.catch()` handler.
/*
* Adding an error? Follow these steps:
* 1. Determine in which category it belongs (Astro, Vite, CSS, Content Collections etc.)
* 2. Add it at the bottom of the corresponding category above (see the @kind heading tags to see where they start), following the shape of the other errors.
* 4. If your message is dynamic, make sure the function shape is the following: `message: (something: type) => "my message"`, no `{}`, no `return` etc.
* - It has to be the simple shape, or the docs generator will not be able to parse it correctly.
* - If your message is fully dynamic (ex: lots of conditional logic), make `message` a proper function, like such: `message(parameters) { logic }`.
* Make sure to add a `@message` tag with a static example of the error message, the docs won't be able to parse it otherwise.
* - If your message is static, you can just use a string, `message: "my message"`.
* 5. Make sure to add a JSdoc comment with the `@docs` tag so that it shows up in the docs
* For more information, see the README in this folder!
*/
export const UnhandledRejection = {
name: 'UnhandledRejection',
title: 'Unhandled rejection',
message: (stack: string) => {
return `Astro detected an unhandled rejection. Here's the stack trace:\n${stack}`;
},
hint: 'Make sure your promises all have an `await` or a `.catch()` handler.',
} satisfies ErrorData;