chore: markdown warnings (#11302)

* rename warnings.js to warnings-tmp.js

* start porting warnings

* centralise stuff

* finish porting warnings

* tidy up

* get messages into JSDoc annotations

* prettier

* lint

Author: Rich-Harris

.prettierignore

@@ -4,6 +4,7 @@ packages/**/npm/**/*
 packages/**/config/*.js
 packages/svelte/messages/**/*.md
 packages/svelte/src/compiler/errors.js
+packages/svelte/src/compiler/warnings.js
 packages/svelte/tests/**/*.svelte
 packages/svelte/tests/**/_expected*
 packages/svelte/tests/**/_actual*

packages/svelte/messages/compile-warnings/a11y.md

@@ -0,0 +1,171 @@
+## a11y_aria_attributes
+
+<%name%> should not have aria-* attributes
+
+## a11y_unknown_aria_attribute
+
+Unknown aria attribute 'aria-%attribute%'
+
+## a11y_unknown_aria_attribute_suggestion
+
+Unknown aria attribute 'aria-%attribute%'. Did you mean '%suggestion%'?
+
+## a11y_hidden
+
+<%name%> element should not be hidden
+
+## a11y_incorrect_aria_attribute_type_boolean
+
+The value of '%attribute%' must be either 'true' or 'false'
+
+## a11y_incorrect_aria_attribute_type_integer
+
+The value of '%attribute%' must be an integer
+
+## a11y_incorrect_aria_attribute_type_id
+
+The value of '%attribute%' must be a string that represents a DOM element ID
+
+## a11y_incorrect_aria_attribute_type_idlist
+
+The value of '%attribute%' must be a space-separated list of strings that represent DOM element IDs
+
+## a11y_incorrect_aria_attribute_type_tristate
+
+The value of '%attribute%' must be exactly one of true, false, or mixed
+
+## a11y_incorrect_aria_attribute_type_token
+
+The value of '%attribute%' must be exactly one of %values%
+
+## a11y_incorrect_aria_attribute_type_tokenlist
+
+The value of '%attribute%' must be a space-separated list of one or more of %values%
+
+## a11y_incorrect_aria_attribute_type
+
+The value of '%attribute%' must be of type %type%
+
+## a11y_aria_activedescendant_has_tabindex
+
+Elements with attribute aria-activedescendant should have tabindex value
+
+## a11y_misplaced_role
+
+<%name%> should not have role attribute
+
+## a11y_no_abstract_role
+
+Abstract role '%role%' is forbidden
+
+## a11y_unknown_role
+
+Unknown role '%role%'
+
+## a11y_unknown_role_suggestion
+
+Unknown role '%role%'. Did you mean '%suggestion%'?
+
+## a11y_no_redundant_roles
+
+Redundant role '%role%'
+
+## a11y_role_has_required_aria_props
+
+Elements with the ARIA role "%role%" must have the following attributes defined: %props%
+
+## a11y_interactive_supports_focus
+
+Elements with the '%role%' interactive role must have a tabindex value.
+
+## a11y_no_interactive_element_to_noninteractive_role
+
+<%element%> cannot have role '%role%'
+
+## a11y_no_noninteractive_element_to_interactive_role
+
+Non-interactive element <%element%> cannot have interactive role '%role%'
+
+## a11y_accesskey
+
+Avoid using accesskey
+
+## a11y_autofocus
+
+Avoid using autofocus
+
+## a11y_misplaced_scope
+
+The scope attribute should only be used with <th> elements
+
+## a11y_positive_tabindex
+
+Avoid tabindex values above zero
+
+## a11y_click_events_have_key_events
+
+Visible, non-interactive elements with a click event must be accompanied by a keyboard event handler. Consider whether an interactive element such as <button type="button"> or <a> might be more appropriate. See https://svelte.dev/docs/accessibility-warnings#a11y-click-events-have-key-events for more details.
+
+## a11y_no_noninteractive_tabindex
+
+noninteractive element cannot have nonnegative tabIndex value
+
+## a11y_role_supports_aria_props
+
+The attribute '%attribute%' is not supported by the role '%role%'
+
+## a11y_role_supports_aria_props_implicit
+
+The attribute '%attribute%' is not supported by the role '%role%'. This role is implicit on the element <%name%>
+
+## a11y_no_noninteractive_element_interactions
+
+Non-interactive element <%element%> should not be assigned mouse or keyboard event listeners.
+
+## a11y_no_static_element_interactions
+
+<%element%> with a %handler% handler must have an ARIA role
+
+## a11y_invalid_attribute
+
+'%href_value%' is not a valid %href_attribute% attribute
+
+## a11y_missing_attribute
+
+<%name%> element should have %article% %sequence% attribute
+
+## a11y_autocomplete_valid
+
+The value '%value%' is not supported by the attribute 'autocomplete' on element <input type="%type%">
+
+## a11y_img_redundant_alt
+
+Screenreaders already announce <img> elements as an image.
+
+## a11y_label_has_associated_control
+
+A form label must be associated with a control.
+
+## a11y_media_has_caption
+
+<video> elements must have a <track kind="captions">
+
+## a11y_distracting_elements
+
+Avoid <%name%> elements
+
+## a11y_figcaption_parent
+
+`<figcaption>` must be an immediate child of `<figure>`
+
+## a11y_figcaption_index
+
+`<figcaption>` must be first or last child of `<figure>`
+
+## a11y_mouse_events_have_key_events
+
+'%event%' event must be accompanied by '%accompanied_by%' event
+
+## a11y_missing_content
+
+<%name%> element should have child content

packages/svelte/messages/compile-warnings/attributes.md

@@ -0,0 +1,15 @@
+## avoid_is
+
+The "is" attribute is not supported cross-browser and should be avoided
+
+## global_event_reference
+
+You are referencing globalThis.%name%. Did you forget to declare a variable with that name?
+
+## illegal_attribute_character
+
+Attributes should not contain ':' characters to prevent ambiguity with Svelte directives
+
+## invalid_html_attribute
+
+'%wrong%' is not a valid HTML attribute. Did you mean '%right%'?

packages/svelte/messages/compile-warnings/block.md

@@ -0,0 +1,3 @@
+## empty_block
+
+Empty block

packages/svelte/messages/compile-warnings/components.md

@@ -0,0 +1,3 @@
+## component_name_lowercase
+
+<%name%> will be treated as an HTML element unless it begins with a capital letter

packages/svelte/messages/compile-warnings/css.md

@@ -0,0 +1,3 @@
+## css_unused_selector
+
+Unused CSS selector "%name%"

packages/svelte/messages/compile-warnings/legacy.md

@@ -0,0 +1,19 @@
+## no_reactive_declaration
+
+Reactive declarations only exist at the top level of the instance script
+
+## module_script_reactive_declaration
+
+All dependencies of the reactive declaration are declared in a module script and will not be reactive
+
+## unused_export_let
+
+Component has unused export property '%name%'. If it is for external reference only, please consider using `export const %name%`
+
+## deprecated_slot_element
+
+Using <slot> to render parent content is deprecated. Use {@render ...} tags instead.
+
+## deprecated_event_handler
+
+Using on:%name% to listen to the %name% event is is deprecated. Use the event attribute on%name% instead.

packages/svelte/messages/compile-warnings/misc.md

@@ -0,0 +1,3 @@
+## invalid_self_closing_tag
+
+Self-closing HTML tags for non-void elements are ambiguous — use <%name% ...></%name%> rather than <%name% ... />

packages/svelte/messages/compile-warnings/options.md

@@ -0,0 +1,3 @@
+## missing_custom_element_compile_option
+
+The 'customElement' option is used when generating a custom element. Did you forget the 'customElement: true' compile option?

packages/svelte/messages/compile-warnings/performance.md

@@ -0,0 +1,7 @@
+## avoid_inline_class
+
+Avoid 'new class' — instead, declare the class at the top level scope
+
+## avoid_nested_class
+
+Avoid declaring classes below the top level scope

packages/svelte/messages/compile-warnings/runes.md

@@ -0,0 +1,19 @@
+## store_with_rune_name
+
+It looks like you're using the `$%name%` rune, but there is a local binding called `%name%`. Referencing a local variable with a `$` prefix will create a store subscription. Please rename `%name%` to avoid the ambiguity
+
+## non_state_reference
+
+`%name%` is updated, but is not declared with `$state(...)`. Changing its value will not correctly trigger updates
+
+## derived_iife
+
+Use `$derived.by(() => {...})` instead of `$derived((() => {...})())`
+
+## invalid_props_declaration
+
+Component properties are declared using `$props()` in runes mode. Did you forget to call the function?
+
+## invalid_bindable_declaration
+
+Bindable component properties are declared using `$bindable()` in runes mode. Did you forget to call the function?

packages/svelte/messages/compile-warnings/state.md

@@ -0,0 +1,7 @@
+## static_state_reference
+
+State referenced in its own scope will never update. Did you mean to reference it inside a closure?
+
+## invalid_rest_eachblock_binding
+
+The rest operator (...) will create a new object and binding '%name%' with the original object will not work

packages/svelte/package.json

@@ -99,8 +99,8 @@
     "templating"
   ],
   "scripts": {
-    "build": "rollup -c && pnpm generate:types && node scripts/check-treeshakeability.js",
-    "dev": "rollup -cw",
+    "build": "node scripts/process-messages && rollup -c && pnpm generate:types && node scripts/check-treeshakeability.js",
+    "dev": "node scripts/process-messages && rollup -cw",
     "check": "tsc && cd ./tests/types && tsc",
     "check:watch": "tsc --watch",
     "generate:version": "node ./scripts/generate-version.js",

packages/svelte/scripts/process-messages/index.js

@@ -111,12 +111,20 @@ function transform(name, dest) {
 				const value = node.value
 					.split('\n')
 					.map((line) => {
+						if (line === ' * MESSAGE') {
+							return message
+								.split('\n')
+								.map((line) => ` * ${line}`)
+								.join('\n');
+						}
+
 						if (line.includes('PARAMETER')) {
 							return vars.map((name) => ` * @param {string} ${name}`).join('\n');
 						}
 
 						return line;
 					})
+					.filter((x) => x !== '')
 					.join('\n');
 
 				if (value !== node.value) {
@@ -168,7 +176,7 @@ function transform(name, dest) {
 					for (let i = 0; i < parts.length; i += 1) {
 						const part = parts[i];
 						if (i % 2 === 0) {
-							const str = part.replace(/(`|\$)/g, '\\$1');
+							const str = part.replace(/(`|\${)/g, '\\$1');
 							quasis.push({
 								type: 'TemplateElement',
 								value: { raw: str, cooked: str },
@@ -211,3 +219,4 @@ function transform(name, dest) {
 }
 
 transform('compile-errors', 'src/compiler/errors.js');
+transform('compile-warnings', 'src/compiler/warnings.js');

packages/svelte/scripts/process-messages/templates/compile-errors.js

@@ -47,7 +47,6 @@ export class CompileError extends Error {
 }
 
 /**
- *
  * @param {null | number | NodeLike} node
  * @param {string} code
  * @param {string} message
@@ -65,6 +64,7 @@ function e(node, code, message) {
 }
 
 /**
+ * MESSAGE
  * @param {null | number | NodeLike} node
  * @param {string} PARAMETER
  * @returns {never}

packages/svelte/scripts/process-messages/templates/compile-warnings.js

@@ -0,0 +1,52 @@
+import { getLocator } from 'locate-character';
+
+/** @typedef {{ start?: number, end?: number }} NodeLike */
+
+/** @type {import('#compiler').Warning[]} */
+let warnings = [];
+
+/** @type {string | undefined} */
+let filename;
+
+let locator = getLocator('', { offsetLine: 1 });
+
+/**
+ * @param {{
+ *   source: string;
+ *   filename: string | undefined;
+ * }} options
+ * @returns {import('#compiler').Warning[]}
+ */
+export function reset_warnings(options) {
+	filename = options.filename;
+	locator = getLocator(options.source, { offsetLine: 1 });
+
+	return (warnings = []);
+}
+
+/**
+ * @param {null | NodeLike} node
+ * @param {string} code
+ * @param {string} message
+ */
+function w(node, code, message) {
+	// @ts-expect-error
+	if (node.ignores?.has(code)) return;
+
+	warnings.push({
+		code,
+		message,
+		filename,
+		start: node?.start !== undefined ? locator(node.start) : undefined,
+		end: node?.end !== undefined ? locator(node.end) : undefined
+	});
+}
+
+/**
+ * MESSAGE
+ * @param {null | NodeLike} node
+ * @param {string} PARAMETER
+ */
+export function CODE(node, PARAMETER) {
+	w(node, 'CODE', MESSAGE);
+}