@wix/origami-transforms 0.1.28 → 0.1.30

package/src/cssPlugins/spxThemeVariables/utils/writeUtils.js

@@ -0,0 +1,98 @@
+import postcss from 'postcss'
+import { DESKTOP } from './cssTreeUtils.js'
+import { groupSectionsByWrappingAtRules } from './wrappingAtRuleUtils.js'
+
+/** @typedef {import('./copyPlanUtils.js').ThemeCopies} ThemeCopies */
+/** @typedef {import('./wrappingAtRuleUtils.js').Section} Section */
+/** @typedef {import('./wrappingAtRuleUtils.js').SectionGroup} SectionGroup */
+
+/**
+ * @typedef {object} BreakpointCopies
+ * @property {string} breakpoint
+ * @property {import('postcss').Declaration[]} declarations
+ */
+
+export const THEME_COPIES_LAYER = 'origami-theme-copies'
+
+const LEADING_AT_RULES = new Set(['charset', 'import'])
+
+/**
+ * @param {ThemeCopies} themeCopies
+ * @returns {BreakpointCopies[]}
+ */
+const breakpointCopiesOf = themeCopies => {
+    const planned = [...themeCopies].map(([breakpoint, copies]) => ({ breakpoint, declarations: [...copies.values()] }))
+    return planned.filter(({ declarations }) => declarations.length > 0)
+}
+
+/**
+ * @param {string} selector
+ * @param {BreakpointCopies} breakpointCopies
+ * @returns {import('postcss').ChildNode}
+ */
+const breakpointBlockOf = (selector, { breakpoint, declarations }) => {
+    const nodes = declarations.map(declaration => declaration.clone({ important: false, raws: {} }))
+    const rule = postcss.rule({ selector, nodes })
+    if (breakpoint === DESKTOP) return rule
+    return postcss.atRule({ name: 'media', params: breakpoint, nodes: [rule] })
+}
+
+/**
+ * @param {import('postcss').ChildNode[]} nodes
+ * @param {import('postcss').AtRule} wrappingAtRule
+ * @returns {import('postcss').ChildNode[]}
+ */
+const wrapInAtRuleClone = (nodes, wrappingAtRule) => {
+    const clone = wrappingAtRule.clone({ nodes: [] })
+    clone.append(nodes)
+    return [clone]
+}
+
+/**
+ * @param {readonly BreakpointCopies[]} allBreakpointCopies
+ * @param {SectionGroup} group
+ * @returns {import('postcss').ChildNode[]}
+ */
+const groupBlocksOf = (allBreakpointCopies, { wrappingAtRules, selectors }) => {
+    const selector = `:where(${selectors.join(', ')})`
+    const blocks = allBreakpointCopies.map(breakpointCopies => breakpointBlockOf(selector, breakpointCopies))
+    return wrappingAtRules.reduceRight(wrapInAtRuleClone, blocks)
+}
+
+/**
+ * @param {readonly BreakpointCopies[]} allBreakpointCopies
+ * @param {readonly SectionGroup[]} groups
+ */
+const copyLayerOf = (allBreakpointCopies, groups) => {
+    const nodes = groups.flatMap(group => groupBlocksOf(allBreakpointCopies, group))
+    return postcss.atRule({ name: 'layer', params: THEME_COPIES_LAYER, nodes })
+}
+
+/** @param {import('postcss').ChildNode} node */
+const isLeadingAtRule = node => node.type === 'atrule' && LEADING_AT_RULES.has(node.name)
+
+/**
+ * @param {import('postcss').Root} root
+ * @param {import('postcss').AtRule} layer
+ */
+const prependAfterLeadingAtRules = (root, layer) => {
+    const firstOther = root.nodes.find(node => node.type !== 'comment' && !isLeadingAtRule(node))
+    if (firstOther === undefined) {
+        root.append(layer)
+        return
+    }
+    firstOther.before(layer)
+}
+
+/**
+ * @param {import('postcss').Root} root
+ * @param {ThemeCopies} themeCopies
+ * @param {readonly Section[]} sections
+ */
+export const writeCopies = (root, themeCopies, sections) => {
+    const allBreakpointCopies = breakpointCopiesOf(themeCopies)
+    if (allBreakpointCopies.length === 0 || sections.length === 0) return
+    const groups = groupSectionsByWrappingAtRules(sections)
+    const layer = copyLayerOf(allBreakpointCopies, groups)
+    prependAfterLeadingAtRules(root, layer)
+}

package/src/cssPlugins/stackChildren.js

@@ -157,8 +157,12 @@ const where = declaration => {
 
 const or = items => (items.length === 1 ? items[0] : `${items.slice(0, -1).join(', ')} or ${items.at(-1)}`)
 
-/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const checks = /** @type {const} */ (['child_not_in_stack'])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
 export const stackChildrenPlugin = {
+    checks,
     name: 'stack-children',
     // After mixins copy their bodies in, before spx rewrites --spx() calls away.
     order: 12,
@@ -199,7 +203,7 @@ export const stackChildrenPlugin = {
         }
 
         if (violations.size) {
-            throw new LayoutError([...violations], {
+            throw new LayoutError(stackChildrenPlugin, [...violations].map(message => ({ check: 'child_not_in_stack', message })), {
                 file: first?.input.file,
                 line: first?.start?.line,
                 column: first?.start?.column,

package/src/cssPlugins/wixVectorUrls.js

@@ -17,8 +17,12 @@ const idsIn = root => {
     return ids
 }
 
-/** @type {import('../transform/types.js').CssTransformPlugin} */
+const checks = /** @type {const} */ ([])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
 export const wixVectorUrlsPlugin = {
+    checks,
     name: 'wix-vector-urls',
     // Last, so a url a mixin or preset copies elsewhere is inlined wherever it ends up.
     order: 25,

package/src/jsxPlugins/index.js

@@ -7,5 +7,5 @@ import { origamiCompatibilityPlugin } from './origamiCompatibility/index.js'
 import { layoutValidationPlugin } from './validation/index.js'
 import { pageSlotsPlugin } from './pageSlots.js'
 
-/** @type {readonly import('../transform/types.js').JsxTransformPlugin[]} */
+/** @type {readonly import('../transform/types.js').JsxTransformPlugin<string>[]} */
 export const jsxPlugins = Object.freeze([layoutValidationPlugin, mediaValidationPlugin, origamiCompatibilityPlugin, pageSlotsPlugin])

package/src/jsxPlugins/mediaValidation/index.js

@@ -13,8 +13,12 @@ const STRUCTURE_FILES = new Set(['structure.tsx', 'structure.jsx'])
 // `117a96_1cff23187eeb4050a2a691bcdcad6502~mv2.jpg`: an account prefix, an underscore and a file name.
 const WIX_MEDIA_ID = /^[A-Za-z0-9]+_[A-Za-z0-9_~.-]+\.[A-Za-z0-9]+$/
 
-/** @type {import('../../transform/types.js').JsxTransformPlugin} */
+export const checks = /** @type {const} */ (['media_not_wix'])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../../transform/types.js').JsxTransformPlugin<Check>} */
 export const mediaValidationPlugin = {
+    checks,
     name: 'wix-import-media-validation',
     // Alongside the layout rules: before anything rewrites the tree.
     order: -100,
@@ -22,6 +26,7 @@ export const mediaValidationPlugin = {
 
     transform: (program, context) => {
         const file = context.relativePath ?? context.filePath
+        /** @type {import('../../transform/types.js').Violation<Check>[]} */
         const violations = []
         let first
         program.traverse({
@@ -34,9 +39,9 @@ export const mediaValidationPlugin = {
                 if (uri?.value.type !== 'StringLiteral' || WIX_MEDIA_ID.test(uri.value.value)) return
                 const id = attributes.find(attribute => attribute.name.name === 'id')?.value?.value
                 const line = uri.loc?.start.line
-                violations.push(
+                violations.push({ check: 'media_not_wix', message:
                     `${file}${line ? `:${line}` : ''} <Image${id ? ` id="${id}"` : ''}> image.uri "${uri.value.value}" is not a Wix media ID. Run \`wix origami upload-media\` to upload it.`
-                )
+                })
                 first ??= { file: context.filePath, line, column: uri.loc?.start.column }
             },
         })
@@ -44,10 +49,10 @@ export const mediaValidationPlugin = {
         if (context.command === 'serve') {
             for (const violation of violations) {
                 warn('media_not_wix')
-                console.warn(`[origami] ${violation}`)
+                console.warn(`[origami] ${violation.message}`)
             }
             return
         }
-        throw new LayoutError(violations, first)
+        throw new LayoutError(mediaValidationPlugin, violations, first)
     },
 }

package/src/jsxPlugins/origamiCompatibility/index.js

@@ -22,8 +22,12 @@ const RULES_BY_COMPONENT = new Map(
     ])
 )
 
-/** @type {import('../../transform/types.js').JsxTransformPlugin} */
+const checks = /** @type {const} */ ([])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../../transform/types.js').JsxTransformPlugin<Check>} */
 export const origamiCompatibilityPlugin = {
+    checks,
     name: 'wix-import-origami-compatibility',
     order: 0,
     appliesTo: context => basename(context.filePath) === STRUCTURE_FILE,

package/src/jsxPlugins/pageSlots.js

@@ -32,8 +32,13 @@ const slotFor = component => {
     return undefined
 }
 
-/** Transitional support for DM's literal Page children alongside authored slot props. */
+const checks = /** @type {const} */ ([])
+/** @typedef {typeof checks[number]} Check */
+
+/** Transitional support for DM's literal Page children alongside authored slot props.
+ * @type {import('../transform/types.js').JsxTransformPlugin<Check>} */
 export const pageSlotsPlugin = {
+    checks,
     name: 'wix-import-page-slots',
     order: 0,
     appliesTo: context => basename(context.filePath) === 'structure.jsx',

package/src/jsxPlugins/validation/checks.js

@@ -75,7 +75,7 @@ const CHECKS = {
 export const assertKnownConstraints = rules => {
     for (const rule of rules) {
         for (const key of Object.keys(rule)) {
-            if (key !== 'id' && key !== 'components' && !CHECKS[key]) {
+            if (key !== 'id' && key !== 'components' && key !== 'checks' && !CHECKS[key]) {
                 throw new Error(
                     `layout rules: unknown constraint "${key}" on ${rule.id}. Known: ${Object.keys(CHECKS).join(', ')}`
                 )
@@ -86,20 +86,27 @@ export const assertKnownConstraints = rules => {
 
 export const constrainsChildren = rule => CHILD_CONSTRAINTS.some(key => key in rule)
 
-/** Runs every constraint of `rule` on one element; `report` receives each full message. */
+/** Runs every constraint of `rule` on one element; `report` receives each full message.
+ * @param {import('./rules.js').Rule} rule
+ * @param {{ node: any, componentOf: (node: any) => string | undefined, report: (check: import('./index.js').Check, message: string) => void }} input
+ */
 export const checkRule = (rule, { node, componentOf, report }) => {
     const prefix = `${describe(node)} ${expectation(rule)}`
-    const fail = got => report(`${prefix}; found ${got}.`)
+    /** @param {import('./index.js').Check} check */
+    const fail = check => got => report(check, `${prefix}; found ${got}.`)
 
     const elements = node.children
         .filter(child => child.type === 'JSXElement')
         .map(element => ({ element, component: componentOf(element) }))
-    const context = { node, elements, fail }
+    const context = { node, elements }
 
-    if (constrainsChildren(rule)) checkLiteral(context)
-    for (const [key, value] of Object.entries(rule)) CHECKS[key]?.(value, context)
+    if (constrainsChildren(rule)) checkLiteral({ ...context, fail: fail(rule.checks.literal) })
+    for (const [key, value] of Object.entries(rule)) CHECKS[key]?.(value, { ...context, fail: fail(rule.checks[key]) })
 }
 
-/** `createElement(Section, …)` would hide a constrained component's children from the checks. */
+/** `createElement(Section, …)` would hide a constrained component's children from the checks.
+ * @param {import('./rules.js').Rule} rule
+ * @param {{ node: any, component: string, report: (check: import('./index.js').Check, message: string) => void }} input
+ */
 export const checkCreateElement = (rule, { node, component, report }) =>
-    report(`<${component}>${at(node)} ${expectation(rule)}; found createElement(${component}), write it as a JSX tag.`)
+    report(rule.checks.createElement, `<${component}>${at(node)} ${expectation(rule)}; found createElement(${component}), write it as a JSX tag.`)

package/src/jsxPlugins/validation/index.js

@@ -26,8 +26,12 @@ const isCreateElement = callee =>
     (callee.type === 'Identifier' && callee.name === 'createElement') ||
     (callee.type === 'MemberExpression' && !callee.computed && callee.property.name === 'createElement')
 
-/** @type {import('../../transform/types.js').JsxTransformPlugin} */
+export const checks = /** @type {const} */ (['section_wrong_child', 'section_too_few_children', 'section_too_many_children', 'section_non_literal_children', 'section_create_element'])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../../transform/types.js').JsxTransformPlugin<Check>} */
 export const layoutValidationPlugin = {
+    checks,
     name: 'wix-import-layout-validation',
     // Before any plugin that rewrites the tree, so the rules see it as authored.
     order: -100,
@@ -40,8 +44,10 @@ export const layoutValidationPlugin = {
             return name.type === 'JSXIdentifier' ? name.name : undefined
         }
 
+        /** @type {import('../../transform/types.js').Violation<Check>[]} */
         const violations = []
-        const report = message => violations.push(message)
+        /** @param {Check} check @param {string} message */
+        const report = (check, message) => violations.push({ check, message })
         program.traverse({
             JSXElement(path) {
                 const component = componentOf(path.node)
@@ -60,6 +66,6 @@ export const layoutValidationPlugin = {
             },
         })
 
-        if (violations.length) throw new LayoutError(violations)
+        if (violations.length) throw new LayoutError(layoutValidationPlugin, violations)
     },
 }

package/src/jsxPlugins/validation/rules.js

@@ -13,9 +13,23 @@
 
 const STANDARD_SECTIONS = ['Section', 'HeaderSection', 'FooterSection']
 
+/**
+ * @typedef {object} Rule
+ * @property {string} id
+ * @property {string[]} components
+ * @property {string[]} allowedChildren
+ * @property {number} minChildren
+ * @property {number} maxChildren
+ * @property {Record<'allowedChildren' | 'minChildren' | 'maxChildren' | 'literal' | 'createElement', import('./index.js').Check>} checks
+ */
+/** @satisfies {Rule[]} */
 export const RULES = [
     {
         id: 'S2-SECTION-001',
+        checks: {
+            allowedChildren: 'section_wrong_child', minChildren: 'section_too_few_children',
+            maxChildren: 'section_too_many_children', literal: 'section_non_literal_children', createElement: 'section_create_element',
+        },
         components: STANDARD_SECTIONS,
         allowedChildren: ['InternalContainer'],
         minChildren: 1,

package/src/transform/bi.js

@@ -1,4 +1,5 @@
 import { currentRow } from '@wix/origami-bi'
+import { LayoutError } from './layoutError.js'
 const summaries = new WeakMap()
 
 /** Aggregate completed dev invocations; paths are only in this local set, never in rows. */
@@ -32,3 +33,32 @@ export function warn(key) {
     const parent = current?.step_type === 'build_plugin' ? current.parent : current
     parent?.runInContext(() => parent.run.openRow('warning', key, { error_name: key }).end())
 }
+
+/**
+ * @template {string} Check
+ * @param {import('./types.js').TransformPluginBase<Check>} plugin
+ * @param {unknown} cause
+ * @returns {Check | undefined}
+ */
+export function declaredCheck(plugin, cause) {
+    return cause instanceof Error && 'check' in cause ? plugin.checks.find(check => check === cause.check) : undefined
+}
+
+/** Finish a plugin failure, projecting only its declared keys into check children. */
+export function recordPluginFailure(plugin, cause, pageId) {
+    const row = currentRow()
+    const check = declaredCheck(plugin, cause)
+    const violations = cause instanceof LayoutError ? cause.violations :
+        check !== undefined ? [{ check }] : []
+    const layout = cause instanceof LayoutError || violations.length > 0
+    row?.end(false, { error_name: layout ? 'layout_error' : 'plugin_error' }, {
+        outcome: layout ? 'layout_error' : 'plugin_error', violations: violations.length,
+    })
+    const counts = new Map()
+    for (const { check } of violations) {
+        if (plugin.checks.includes(check)) counts.set(check, (counts.get(check) ?? 0) + 1)
+    }
+    for (const [check, violations] of counts) row?.run.recordRow('build_plugin', plugin.name, {
+        ...(pageId ? { item_type: 'page', item_id: pageId } : {}), step_details: { check, violations },
+    }, { success: false, duration_ms: 0 }, row)
+}

package/src/transform/css/runPlugins.js

@@ -6,7 +6,7 @@
 // the author gets every plugin's violations in one error, at the first one's position, not one plugin's per build.
 
 import { currentRow, namedError } from '@wix/origami-bi'
-import { countPlugin } from '../bi.js'
+import { countPlugin, declaredCheck, recordPluginFailure } from '../bi.js'
 import { pageIdFor } from '../context.js'
 import { LayoutError } from '../layoutError.js'
 
@@ -16,12 +16,12 @@ const reason = cause => (cause instanceof Error ? cause.message : String(cause))
 export const pluginError = (plugin, context, cause) =>
     // Tooling such as Vite's error overlay prints only the message, so the reason goes in it as well. A
     // plugin may throw any value, so it is read without assuming an Error.
-    namedError('plugin_error', `CSS transform "${plugin.name}" failed for ${context.relativePath ?? context.filePath}: ${reason(cause)}`, {
+    namedError(declaredCheck(plugin, cause) !== undefined ? 'layout_error' : 'plugin_error', `CSS transform "${plugin.name}" failed for ${context.relativePath ?? context.filePath}: ${reason(cause)}`, {
         cause,
     })
 
 export const runCssPlugins = ({ plugins, root, context }) => {
-    /** @type {LayoutError[]} */
+    /** @type {LayoutError<string>[]} */
     const layoutErrors = []
     for (const phase of ['validate', 'transform']) {
         for (const plugin of plugins) {
@@ -38,10 +38,7 @@ export const runCssPlugins = ({ plugins, root, context }) => {
                 if (context.command === 'serve') row?.discard()
                 else row?.end()
             } catch (cause) {
-                const layout = cause instanceof LayoutError
-                row?.end(false, { error_name: layout ? 'layout_error' : 'plugin_error' }, {
-                    outcome: layout ? 'layout_error' : 'plugin_error', violations: layout ? cause.violations.length : 0,
-                })
+                if (row) row.runInContext(() => recordPluginFailure(plugin, cause, pageId))
                 if (cause instanceof LayoutError) {
                     layoutErrors.push(cause)
                     continue
@@ -58,6 +55,7 @@ export const runCssPlugins = ({ plugins, root, context }) => {
     if (layoutErrors.length === 1) throw layoutErrors[0]
     if (layoutErrors.length > 1) {
         throw new LayoutError(
+            { checks: layoutErrors.flatMap(error => error.plugin.checks) },
             layoutErrors.flatMap(error => error.violations),
             layoutErrors[0].location
         )

package/src/transform/jsx/runPlugins.js

@@ -3,7 +3,7 @@
 // plugin and the file that caused it. A LayoutError is the author's, so it passes through.
 
 import { currentRow, namedError } from '@wix/origami-bi'
-import { countPlugin } from '../bi.js'
+import { countPlugin, declaredCheck, recordPluginFailure } from '../bi.js'
 import { pageIdFor } from '../context.js'
 import { LayoutError } from '../layoutError.js'
 
@@ -23,14 +23,11 @@ export const runJsxPlugins = ({ plugins, program, context }) => {
             if (context.command === 'serve') row?.discard()
             else row?.end()
         } catch (cause) {
-            const layout = cause instanceof LayoutError
-            row?.end(false, { error_name: layout ? 'layout_error' : 'plugin_error' }, {
-                outcome: layout ? 'layout_error' : 'plugin_error', violations: layout ? cause.violations.length : 0,
-            })
+            if (row) row.runInContext(() => recordPluginFailure(plugin, cause, pageId))
             if (cause instanceof LayoutError) throw cause
             // Tooling such as Vite's error overlay prints only the message, so the reason goes in it as well. A
             // plugin may throw any value, so it is read without assuming an Error.
-            throw namedError('plugin_error',
+            throw namedError(declaredCheck(plugin, cause) !== undefined ? 'layout_error' : 'plugin_error',
                 `JSX transform "${plugin.name}" failed for ${context.relativePath ?? context.filePath}: ${reason(cause)}`,
                 { cause }
             )

package/src/transform/layoutError.js

@@ -2,17 +2,21 @@
 // without naming the plugin, and it carries no stack: the bundler already names the file, and the
 // messages say where in it.
 
+/** @template {string} Check */
 export class LayoutError extends Error {
     /**
-     * @param {readonly string[]} violations
+     * @param {Pick<import('./types.js').TransformPluginBase<Check>, 'checks'>} plugin
+     * @param {readonly import('./types.js').Violation<NoInfer<Check>>[]} violations
      * @param {{ file?: string, line?: number, column?: number }} [location] The first violation's, which the
      *     bundler prints as the error's position (Vite's CSS stage reads `file`, `line` and `column`).
      */
-    constructor(violations, location = {}) {
-        super(violations.length === 1 ? violations[0] : `\n  ${violations.join('\n  ')}`)
+    constructor(plugin, violations, location = {}) {
+        const messages = violations.map(violation => violation.message)
+        super(messages.length === 1 ? messages[0] : `\n  ${messages.join('\n  ')}`)
         this.name = 'LayoutError'
         this.error_name = 'layout_error'
         this.stack = ''
+        this.plugin = plugin
         this.violations = violations
         this.location = location
         Object.assign(this, location)

package/src/transform/pipeline.js

@@ -30,8 +30,8 @@ const createState = ({ layout, registries, command }) => {
 /**
  * @param {{
  *     layout: import('./types.js').SiteLayout,
- *     jsxPlugins?: readonly import('./types.js').JsxTransformPlugin[],
- *     cssPlugins?: readonly import('./types.js').CssTransformPlugin[],
+ *     jsxPlugins?: readonly import('./types.js').JsxTransformPlugin<string>[],
+ *     cssPlugins?: readonly import('./types.js').CssTransformPlugin<string>[],
  * }} options
  */
 export const createTransformPipeline = ({ layout, jsxPlugins = defaultJsxPlugins, cssPlugins = defaultCssPlugins }) => {

package/src/transform/types.js

@@ -18,15 +18,32 @@
  * @property {SiteLayout} layout
  * @property {'serve' | 'build'} command
  * @property {boolean} ssr Always false for the CSS stage, which PostCSS drives without an SSR signal.
- *
+ */
+
+/**
+ * @template {string} Check
+ * @typedef {{ check: Check, message: string }} Violation
+ */
+
+/**
+ * @template {string} Check
+ * @typedef {Error & { check: Check }} CheckError
+ */
+
+/**
+ * @template {string} Check
  * @typedef {object} TransformPluginBase
+ * @property {readonly Check[]} checks
  * @property {string} name
  * @property {number} order Ascending. Ties break by registration order.
  * @property {(context: TransformContext) => boolean} [appliesTo] Whether the plugin runs for this
  * file. Must depend only on the file's identity, not on anything that can change between transforms
  * of the same file: the pipeline memoizes the selection per file path.
- *
- * @typedef {TransformPluginBase & {
+ */
+
+/**
+ * @template {string} Check
+ * @typedef {TransformPluginBase<Check> & {
  *     transform: (program: any, context: TransformContext) => void,
  *     parserPlugins?: readonly string[]
  * }} JsxTransformPlugin
@@ -34,8 +51,11 @@
  * nothing walks it for you, so a plugin that can rule itself out cheaply should just return.
  * `parserPlugins` are Babel parser plugins the file needs; they are unioned across selected plugins
  * and applied before any of them run.
- *
- * @typedef {TransformPluginBase & {
+ */
+
+/**
+ * @template {string} Check
+ * @typedef {TransformPluginBase<Check> & {
  *     prepare?: (root: import('postcss').Root, context: CssTransformContext) => Promise<void | { fetched: number, failed: number }> | void,
  *     validate?: (root: import('postcss').Root, context: CssTransformContext) => void,
  *     transform: (root: import('postcss').Root, context: CssTransformContext) => void
@@ -43,7 +63,9 @@
  * `prepare` loads what the plugin needs that can't be read synchronously, such as a file from a CDN, before any
  * plugin's `validate` or `transform` runs. It returns a promise only when it has something to load, so a stylesheet
  * that needs nothing loaded stays synchronous for PostCSS.
- *
+ */
+
+/**
  * @typedef {TransformContext & {
  *     addDependency?: (file: string) => void,
  *     warn?: (node: import('postcss').Node, text: string, key?: 'malformed_custom_enum' | 'unmappable_preset' | 'svg_not_loaded') => void