@wix/origami-transforms 0.1.27 → 0.1.29

package/dist/cssPlugins/componentPosition.d.ts

@@ -1,2 +1,6 @@
-/** @type {import('../transform/types.js').CssTransformPlugin} */
-export const componentPositionPlugin: import("../transform/types.js").CssTransformPlugin;
+/** @typedef {typeof checks[number]} Check */
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
+export const componentPositionPlugin: import("../transform/types.js").CssTransformPlugin<Check>;
+export type Check = (typeof checks)[number];
+declare const checks: readonly [];
+export {};

package/dist/cssPlugins/customEnums.d.ts

@@ -1,3 +1,6 @@
 export function removeCustomEnums(root: any): void;
-/** @type {import('../transform/types.js').CssTransformPlugin} */
-export const customEnumsPlugin: import("../transform/types.js").CssTransformPlugin;
+export const checks: readonly ["duplicate_enum", "non_literal_enum_value", "unknown_enum_value", "enum_parent_selector_list"];
+/** @typedef {typeof checks[number]} Check */
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
+export const customEnumsPlugin: import("../transform/types.js").CssTransformPlugin<Check>;
+export type Check = (typeof checks)[number];

package/dist/cssPlugins/customMedia.d.ts

@@ -1,2 +1,7 @@
-/** @type {import('../transform/types.js').CssTransformPlugin} */
-export const customMediaPlugin: import("../transform/types.js").CssTransformPlugin;
+export const checks: readonly ["unresolved_custom_media"];
+export function fail<E extends Error>(check: Check, error: E): E & {
+    check: "unresolved_custom_media";
+};
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
+export const customMediaPlugin: import("../transform/types.js").CssTransformPlugin<Check>;
+export type Check = (typeof checks)[number];

package/dist/cssPlugins/fonts.d.ts

@@ -1,2 +1,6 @@
-/** @type {import('../transform/types.js').CssTransformPlugin} */
-export const fontsPlugin: import("../transform/types.js").CssTransformPlugin;
+/** @typedef {typeof checks[number]} Check */
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
+export const fontsPlugin: import("../transform/types.js").CssTransformPlugin<Check>;
+export type Check = (typeof checks)[number];
+declare const checks: readonly [];
+export {};

package/dist/cssPlugins/index.d.ts

@@ -1,2 +1,2 @@
-/** @type {readonly import('../transform/types.js').CssTransformPlugin[]} */
-export const cssPlugins: readonly import("../transform/types.js").CssTransformPlugin[];
+/** @type {readonly import('../transform/types.js').CssTransformPlugin<string>[]} */
+export const cssPlugins: readonly import("../transform/types.js").CssTransformPlugin<string>[];

package/dist/cssPlugins/layout/index.d.ts

@@ -1,2 +1,7 @@
-/** @type {import('../../transform/types.js').CssTransformPlugin} */
-export const layoutPlugin: import("../../transform/types.js").CssTransformPlugin;
+export const checks: readonly ["unknown_target", "target_requires_component_id", "invalid_target_envelope", "target_not_site_layout", "duplicate_target", "target_requires_declarations", "duplicate_target_property", "property_wrong_target", "content_position_not_relative", "unsupported_overflow", "unsupported_content_alignment", "inconsistent_container_display", "duplicate_root_property", "property_requires_target"];
+export function fail<E extends Error>(check: Check, error: E): E & {
+    check: "unknown_target" | "target_requires_component_id" | "invalid_target_envelope" | "target_not_site_layout" | "duplicate_target" | "target_requires_declarations" | "duplicate_target_property" | "property_wrong_target" | "content_position_not_relative" | "unsupported_overflow" | "unsupported_content_alignment" | "inconsistent_container_display" | "duplicate_root_property" | "property_requires_target";
+};
+/** @type {import('../../transform/types.js').CssTransformPlugin<Check>} */
+export const layoutPlugin: import("../../transform/types.js").CssTransformPlugin<Check>;
+export type Check = (typeof checks)[number];

package/dist/cssPlugins/mixins.d.ts

@@ -1,2 +1,7 @@
-/** @type {import('../transform/types.js').CssTransformPlugin} */
-export const mixinsPlugin: import("../transform/types.js").CssTransformPlugin;
+export const checks: readonly ["missing_mixin", "cyclic_apply", "expansion_depth_exceeded", "cloned_node_budget_exceeded", "cloned_css_budget_exceeded"];
+export function fail<E extends Error>(check: Check, error: E): E & {
+    check: "missing_mixin" | "cyclic_apply" | "expansion_depth_exceeded" | "cloned_node_budget_exceeded" | "cloned_css_budget_exceeded";
+};
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
+export const mixinsPlugin: import("../transform/types.js").CssTransformPlugin<Check>;
+export type Check = (typeof checks)[number];

package/dist/cssPlugins/presets.d.ts

@@ -1,2 +1,6 @@
-/** @type {import('../transform/types.js').CssTransformPlugin} */
-export const presetsPlugin: import("../transform/types.js").CssTransformPlugin;
+/** @typedef {typeof checks[number]} Check */
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
+export const presetsPlugin: import("../transform/types.js").CssTransformPlugin<Check>;
+export type Check = (typeof checks)[number];
+declare const checks: readonly [];
+export {};

package/dist/cssPlugins/shapeDividers.d.ts

@@ -1,2 +1,6 @@
-/** @type {import('../transform/types.js').CssTransformPlugin} */
-export const shapeDividersPlugin: import("../transform/types.js").CssTransformPlugin;
+/** @typedef {typeof checks[number]} Check */
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
+export const shapeDividersPlugin: import("../transform/types.js").CssTransformPlugin<Check>;
+export type Check = (typeof checks)[number];
+declare const checks: readonly [];
+export {};

package/dist/cssPlugins/spx/index.d.ts

@@ -1,2 +1,7 @@
-/** @type {import('../../transform/types.js').CssTransformPlugin} */
-export const spxPlugin: import("../../transform/types.js").CssTransformPlugin;
+export const checks: readonly ["unsupported_spx_resolver", "invalid_spx_reference_width", "non_literal_spx_argument"];
+export function fail<E extends Error>(check: Check, error: E): E & {
+    check: "unsupported_spx_resolver" | "invalid_spx_reference_width" | "non_literal_spx_argument";
+};
+/** @type {import('../../transform/types.js').CssTransformPlugin<Check>} */
+export const spxPlugin: import("../../transform/types.js").CssTransformPlugin<Check>;
+export type Check = (typeof checks)[number];

package/dist/cssPlugins/stackChildren.d.ts

@@ -1,2 +1,5 @@
-/** @type {import('../transform/types.js').CssTransformPlugin} */
-export const stackChildrenPlugin: import("../transform/types.js").CssTransformPlugin;
+export const checks: readonly ["child_not_in_stack"];
+/** @typedef {typeof checks[number]} Check */
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
+export const stackChildrenPlugin: import("../transform/types.js").CssTransformPlugin<Check>;
+export type Check = (typeof checks)[number];

package/dist/cssPlugins/svg.d.ts

@@ -1,4 +1,7 @@
-export function loadSvgs(ids: any): Promise<undefined> | undefined;
+export function loadSvgs(ids: any): Promise<{
+    fetched: number;
+    failed: number;
+}> | undefined;
 export function loadedSvg(id: any): any;
 export function svgInfo(svg: any): {
     type: any;

package/dist/cssPlugins/wixVectorUrls.d.ts

@@ -1,2 +1,6 @@
-/** @type {import('../transform/types.js').CssTransformPlugin} */
-export const wixVectorUrlsPlugin: import("../transform/types.js").CssTransformPlugin;
+/** @typedef {typeof checks[number]} Check */
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
+export const wixVectorUrlsPlugin: import("../transform/types.js").CssTransformPlugin<Check>;
+export type Check = (typeof checks)[number];
+declare const checks: readonly [];
+export {};

package/dist/jsxPlugins/index.d.ts

@@ -1,2 +1,2 @@
-/** @type {readonly import('../transform/types.js').JsxTransformPlugin[]} */
-export const jsxPlugins: readonly import("../transform/types.js").JsxTransformPlugin[];
+/** @type {readonly import('../transform/types.js').JsxTransformPlugin<string>[]} */
+export const jsxPlugins: readonly import("../transform/types.js").JsxTransformPlugin<string>[];

package/dist/jsxPlugins/mediaValidation/index.d.ts

@@ -1,2 +1,5 @@
-/** @type {import('../../transform/types.js').JsxTransformPlugin} */
-export const mediaValidationPlugin: import("../../transform/types.js").JsxTransformPlugin;
+export const checks: readonly ["media_not_wix"];
+/** @typedef {typeof checks[number]} Check */
+/** @type {import('../../transform/types.js').JsxTransformPlugin<Check>} */
+export const mediaValidationPlugin: import("../../transform/types.js").JsxTransformPlugin<Check>;
+export type Check = (typeof checks)[number];

package/dist/jsxPlugins/origamiCompatibility/index.d.ts

@@ -1,2 +1,6 @@
-/** @type {import('../../transform/types.js').JsxTransformPlugin} */
-export const origamiCompatibilityPlugin: import("../../transform/types.js").JsxTransformPlugin;
+/** @typedef {typeof checks[number]} Check */
+/** @type {import('../../transform/types.js').JsxTransformPlugin<Check>} */
+export const origamiCompatibilityPlugin: import("../../transform/types.js").JsxTransformPlugin<Check>;
+export type Check = (typeof checks)[number];
+declare const checks: readonly [];
+export {};

package/dist/jsxPlugins/pageSlots.d.ts

@@ -1,6 +1,7 @@
-export namespace pageSlotsPlugin {
-    let name: string;
-    let order: number;
-    function appliesTo(context: any): boolean;
-    function transform(program: any): void;
-}
+/** @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: import("../transform/types.js").JsxTransformPlugin<Check>;
+export type Check = (typeof checks)[number];
+declare const checks: readonly [];
+export {};

package/dist/jsxPlugins/validation/checks.d.ts

@@ -1,12 +1,12 @@
 export function assertKnownConstraints(rules: any): void;
 export function constrainsChildren(rule: any): boolean;
-export function checkRule(rule: any, { node, componentOf, report }: {
+export function checkRule(rule: import("./rules.js").Rule, { node, componentOf, report }: {
     node: any;
-    componentOf: any;
-    report: any;
+    componentOf: (node: any) => string | undefined;
+    report: (check: import("./index.js").Check, message: string) => void;
 }): void;
-export function checkCreateElement(rule: any, { node, component, report }: {
+export function checkCreateElement(rule: import("./rules.js").Rule, { node, component, report }: {
     node: any;
-    component: any;
-    report: any;
-}): any;
+    component: string;
+    report: (check: import("./index.js").Check, message: string) => void;
+}): void;

package/dist/jsxPlugins/validation/index.d.ts

@@ -1,2 +1,5 @@
-/** @type {import('../../transform/types.js').JsxTransformPlugin} */
-export const layoutValidationPlugin: import("../../transform/types.js").JsxTransformPlugin;
+export const checks: readonly ["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: import("../../transform/types.js").JsxTransformPlugin<Check>;
+export type Check = (typeof checks)[number];

package/dist/jsxPlugins/validation/rules.d.ts

@@ -1,7 +1,32 @@
+/**
+ * @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: string;
+    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: string[];
     allowedChildren: string[];
     minChildren: number;
     maxChildren: number;
 }[];
+export type Rule = {
+    id: string;
+    components: string[];
+    allowedChildren: string[];
+    minChildren: number;
+    maxChildren: number;
+    checks: Record<"allowedChildren" | "minChildren" | "maxChildren" | "literal" | "createElement", import("./index.js").Check>;
+};

package/dist/transform/bi.d.ts

@@ -0,0 +1,13 @@
+/** Aggregate completed dev invocations; paths are only in this local set, never in rows. */
+export function countPlugin(context: any, duration: any): void;
+/** @param {'malformed_custom_enum' | 'unmappable_preset' | 'svg_not_loaded' | 'media_not_wix'} key */
+export function warn(key: "malformed_custom_enum" | "unmappable_preset" | "svg_not_loaded" | "media_not_wix"): void;
+/**
+ * @template {string} Check
+ * @param {import('./types.js').TransformPluginBase<Check>} plugin
+ * @param {unknown} cause
+ * @returns {Check | undefined}
+ */
+export function declaredCheck<Check extends string>(plugin: import("./types.js").TransformPluginBase<Check>, cause: unknown): Check | undefined;
+/** Finish a plugin failure, projecting only its declared keys into check children. */
+export function recordPluginFailure(plugin: any, cause: any, pageId: any): void;

package/dist/transform/context.d.ts

@@ -1,3 +1,4 @@
+export function pageIdFor(context: any): any;
 export function createContextFactory({ layout, command }: {
     layout: any;
     command: any;

package/dist/transform/css/runPlugins.d.ts

@@ -1,4 +1,7 @@
-export function pluginError(plugin: any, context: any, cause: any): Error;
+export function pluginError(plugin: any, context: any, cause: any): Error & {
+    error_name: import("@wix/origami-bi").ErrorName;
+    error_kind: import("@wix/origami-bi").ErrorKind;
+};
 export function runCssPlugins({ plugins, root, context }: {
     plugins: any;
     root: any;

package/dist/transform/layoutError.d.ts

@@ -1,16 +1,20 @@
-export class LayoutError extends Error {
+/** @template {string} Check */
+export class LayoutError<Check extends string> 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: readonly string[], location?: {
+    constructor(plugin: Pick<import("./types.js").TransformPluginBase<Check>, "checks">, violations: readonly import("./types.js").Violation<NoInfer<Check>>[], location?: {
         file?: string;
         line?: number;
         column?: number;
     });
+    error_name: string;
     stack: string;
-    violations: readonly string[];
+    plugin: Pick<import("./types.js").TransformPluginBase<Check>, "checks">;
+    violations: readonly import("./types.js").Violation<NoInfer<Check>>[];
     location: {
         file?: string;
         line?: number;

package/dist/transform/pipeline.d.ts

@@ -1,7 +1,7 @@
 export function createTransformPipeline({ layout, jsxPlugins, cssPlugins }: {
     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>[];
 }): {
     /** Whether any JSX transform selects this module (structure.jsx/.tsx by default).
      * @param {string} id
@@ -15,15 +15,10 @@ export function createTransformPipeline({ layout, jsxPlugins, cssPlugins }: {
      * @param {{ ssr?: boolean | undefined }} [contextOptions] */
     transformJsx: (code: string, id: string, { ssr }?: {
         ssr?: boolean | undefined;
-    }) => Promise<{
-        code: any;
-        map: any;
-    }>;
+    }) => Promise<any>;
     postcssPlugin: {
+        Once: (...args: any[]) => any;
         postcssPlugin: string;
-        Once(root: any, { result }: {
-            result: any;
-        }): void | Promise<void>;
     };
     babelOptionsFor: (id: any, { ssr }?: {
         ssr?: boolean | undefined;
@@ -43,5 +38,8 @@ export function createTransformPipeline({ layout, jsxPlugins, cssPlugins }: {
     };
     /** Whether a stylesheet whose last CSS run failed declared `file`, so an edit to it may fix the stylesheet. */
     failedStylesheetDependsOn: (file: any) => boolean;
+    close: () => any;
+    /** @param {string} file @param {() => void} reload */
+    handleHotUpdate: (file: string, reload: () => void) => any;
     setCommand: (value: any) => void;
 };

package/dist/transform/types.d.ts

@@ -32,15 +32,15 @@ export type TransformContext = {
      */
     ssr: boolean;
 };
-/**
- * The transform-plugin contract.
- *
- * Both stages have the same shape: an engine parses the file once, and each plugin is handed that
- * AST plus the file's context and does what it likes with it. Babel and PostCSS are engines here,
- * not plugin hosts — a plugin never has to know either one's own plugin protocol. Which stage a
- * plugin belongs to is decided by the list it is registered in, so no descriptor restates it.
- */
-export type TransformPluginBase = {
+export type Violation<Check extends string> = {
+    check: Check;
+    message: string;
+};
+export type CheckError<Check extends string> = Error & {
+    check: Check;
+};
+export type TransformPluginBase<Check extends string> = {
+    checks: readonly Check[];
     name: string;
     /**
      * Ascending. Ties break by registration order.
@@ -59,7 +59,7 @@ export type TransformPluginBase = {
  * `parserPlugins` are Babel parser plugins the file needs; they are unioned across selected plugins
  * and applied before any of them run.
  */
-export type JsxTransformPlugin = TransformPluginBase & {
+export type JsxTransformPlugin<Check extends string> = TransformPluginBase<Check> & {
     transform: (program: any, context: TransformContext) => void;
     parserPlugins?: readonly string[];
 };
@@ -68,8 +68,11 @@ export type JsxTransformPlugin = TransformPluginBase & {
  * 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.
  */
-export type CssTransformPlugin = TransformPluginBase & {
-    prepare?: (root: import("postcss").Root, context: CssTransformContext) => Promise<void> | void;
+export type CssTransformPlugin<Check extends string> = 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;
 };
@@ -80,5 +83,5 @@ export type CssTransformPlugin = TransformPluginBase & {
  */
 export type CssTransformContext = TransformContext & {
     addDependency?: (file: string) => void;
-    warn?: (node: import("postcss").Node, text: string) => void;
+    warn?: (node: import("postcss").Node, text: string, key?: "malformed_custom_enum" | "unmappable_preset" | "svg_not_loaded") => void;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/origami-transforms",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "Babel and PostCSS checks and transforms for Wix origami page files.",
   "main": "./src/index.js",
   "files": [
@@ -12,7 +12,8 @@
     "lint": "oxlint .",
     "test": "node --test test/*.spec.js",
     "test:browser": "node test/spx.browser.mjs && node test/semanticContainer.browser.mjs",
-    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.checks.json"
   },
   "dependencies": {
     "@babel/core": "^7.26.0",
@@ -21,7 +22,8 @@
     "@wix/origami-fonts": "1.0.4",
     "@wix/origami-system-components": "1.10.6",
     "postcss": "^8.5.3",
-    "postcss-custom-media": "^12.0.1"
+    "postcss-custom-media": "^12.0.1",
+    "@wix/origami-bi": "0.10.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -69,5 +71,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "falconPackageHash": "1c7523e78958c85b77bf2e3bdfc4a2a7b6842c08c8be0cebea118c68"
+  "falconPackageHash": "26f18af79b8f5dd98a7aba58e68be7f9dd09c52bdd522e0eb33180c4"
 }

package/src/cssPlugins/componentPosition.js

@@ -6,8 +6,12 @@ import { isLayoutSource } from './layout/parser.js'
 // One class or id: DM writes `.compId`, and layout.css still accepts `#compId` (see layout/parser.js).
 const SINGLE_CLASS_OR_ID = /^[.#][\w-]+$/
 
-/** @type {import('../transform/types.js').CssTransformPlugin} */
+const checks = /** @type {const} */ ([])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
 export const componentPositionPlugin = {
+    checks,
     name: 'component-position',
     order: 14,
     transform(root, context) {

package/src/cssPlugins/customEnums.js

@@ -222,8 +222,12 @@ export const removeCustomEnums = root => {
     for (const rule of emptied) if (rule?.type === 'rule' && rule.nodes.length === 0) rule.remove()
 }
 
-/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const checks = /** @type {const} */ (['duplicate_enum', 'non_literal_enum_value', 'unknown_enum_value', 'enum_parent_selector_list'])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
 export const customEnumsPlugin = {
+    checks,
     name: 'custom-enums',
     // After mixins copy their bodies in, before presets and layout move declarations out of the instance's rule.
     order: 11,
@@ -311,13 +315,13 @@ export const customEnumsPlugin = {
             const matching = enums.filter(item => item.key === declaration.prop && item.inline === nearest)
             if (matching.length === 0) return null
             const key = declaration.prop.slice(2)
-            if (matching.length > 1) return `the element has custom enum ${key} more than once, so it can't say which.`
+            if (matching.length > 1) return /** @satisfies {[Check, string]} */ (['duplicate_enum', `the element has custom enum ${key} more than once, so it can't say which.`])
             const [found] = matching
             const value = declaration.value.trim()
             const allowed = Object.keys(found.options).join(', ')
-            if (/\bvar\(/.test(value)) return `a custom enum's value must be literal, one of ${allowed}.`
+            if (/\bvar\(/.test(value)) return /** @satisfies {[Check, string]} */ (['non_literal_enum_value', `a custom enum's value must be literal, one of ${allowed}.`])
             const options = found.options[value]
-            if (options === undefined) return `"${value}" is not an option of ${key}; use one of ${allowed}.`
+            if (options === undefined) return /** @satisfies {[Check, string]} */ (['unknown_enum_value', `"${value}" is not an option of ${key}; use one of ${allowed}.`])
             return options
         }
 
@@ -331,12 +335,14 @@ export const customEnumsPlugin = {
                           `type, such as wixEditorElements.Button, in an element rule under the editor element's. That ` +
                           `element's enums are left as authored.`
                     : `custom-enums: @custom-enum ${block.params}${where(block)}: can't be read; it needs a --key, a ` +
-                          `default: that is one of its @option blocks, and an element rule around it. Its key is left as authored.`
+                          `default: that is one of its @option blocks, and an element rule around it. Its key is left as authored.`,
+                'malformed_custom_enum'
             )
         }
 
         // Every declaration is checked before any is rewritten: a failed run leaves the stylesheet as it was.
-        const violations = new Set()
+        /** @type {Map<string, import('../transform/types.js').Violation<Check>>} */
+        const violations = new Map()
         /** @type {any} The first violation's source, whose position the bundler prints. */
         let first
         // The rules with an enum that resolves, the only ones a selector list is split in.
@@ -347,17 +353,18 @@ export const customEnumsPlugin = {
                 const results = resolve(rule, own).map(selector => lookup(declaration, selector))
                 if (results.some(result => result !== null)) resolving.add(rule)
                 if (results.length > 1 && results.some(result => result !== null)) {
-                    return ['set a custom enum on one instance rule, not under a parent selector list.']
+                    return [/** @satisfies {[Check, string]} */ (['enum_parent_selector_list', 'set a custom enum on one instance rule, not under a parent selector list.'])]
                 }
-                return results.filter(result => typeof result === 'string')
+                return results.filter(result => Array.isArray(result))
             })
-            for (const problem of problems) {
+            for (const [check, problem] of problems) {
                 first ??= declaration.source
-                violations.add(`custom-enums: ${declaration.prop}: ${declaration.value}${where(declaration)}: ${problem}`)
+                const message = `custom-enums: ${declaration.prop}: ${declaration.value}${where(declaration)}: ${problem}`
+                violations.set(message, { check, message })
             }
         }
         if (violations.size) {
-            throw new LayoutError([...violations], {
+            throw new LayoutError(customEnumsPlugin, [...violations.values()], {
                 file: first?.input.file,
                 line: first?.start?.line,
                 column: first?.start?.column,
@@ -379,7 +386,7 @@ export const customEnumsPlugin = {
             const rule = ruleOf(declaration)
             if (rule === undefined) continue
             const [selector] = resolve(rule, rule.selector)
-            const options = /** @type {Exclude<ReturnType<typeof lookup>, string>} */ (lookup(declaration, selector))
+            const options = /** @type {Exclude<ReturnType<typeof lookup>, string[]>} */ (lookup(declaration, selector))
             if (options !== null) declaration.replaceWith(expansion(declaration, options))
         }
     },

package/src/cssPlugins/customMedia.js

@@ -27,8 +27,15 @@ const usesCustomMedia = root => {
     return used
 }
 
-/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const checks = /** @type {const} */ (['unresolved_custom_media'])
+/** @typedef {typeof checks[number]} Check */
+
+/** @template {Error} E @param {Check} check @param {E} error */
+export const fail = (check, error) => Object.assign(error, { check })
+
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
 export const customMediaPlugin = {
+    checks,
     name: 'custom-media',
     order: 0,
     transform(root, context) {
@@ -43,9 +50,9 @@ export const customMediaPlugin = {
         // disables the whole block.
         root.walkAtRules('media', atRule => {
             if (CUSTOM_MEDIA_QUERY.test(atRule.params)) {
-                throw new Error(
+                throw fail('unresolved_custom_media', new Error(
                     `@media ${atRule.params} has no usable @custom-media definition: it is missing or cyclic`
-                )
+                ))
             }
         })
     },

package/src/cssPlugins/fonts.js

@@ -49,8 +49,12 @@ const fontIdsOf = declaration => {
     return family.split(',').map(name => name.trim().replace(/^(['"])(.*)\1$/, '$2').toLowerCase())
 }
 
-/** @type {import('../transform/types.js').CssTransformPlugin} */
+const checks = /** @type {const} */ ([])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
 export const fontsPlugin = {
+    checks,
     name: 'fonts',
     // Reads the declarations as authored, before spx rewrites the sizes the family follows.
     order: 5,

package/src/cssPlugins/index.js

@@ -29,7 +29,7 @@ import { spxPlugin } from './spx/index.js'
 import { stackChildrenPlugin } from './stackChildren.js'
 import { wixVectorUrlsPlugin } from './wixVectorUrls.js'
 
-/** @type {readonly import('../transform/types.js').CssTransformPlugin[]} */
+/** @type {readonly import('../transform/types.js').CssTransformPlugin<string>[]} */
 export const cssPlugins = Object.freeze([
     customMediaPlugin,
     fontsPlugin,

package/src/cssPlugins/layout/index.js

@@ -1,8 +1,15 @@
 import { compileContainers } from './compiler.js'
 import { parseTargets } from './parser.js'
 
-/** @type {import('../../transform/types.js').CssTransformPlugin} */
+export const checks = /** @type {const} */ (['unknown_target', 'target_requires_component_id', 'invalid_target_envelope', 'target_not_site_layout', 'duplicate_target', 'target_requires_declarations', 'duplicate_target_property', 'property_wrong_target', 'content_position_not_relative', 'unsupported_overflow', 'unsupported_content_alignment', 'inconsistent_container_display', 'duplicate_root_property', 'property_requires_target'])
+/** @typedef {typeof checks[number]} Check */
+
+/** @template {Error} E @param {Check} check @param {E} error */
+export const fail = (check, error) => Object.assign(error, { check })
+
+/** @type {import('../../transform/types.js').CssTransformPlugin<Check>} */
 export const layoutPlugin = {
+    checks,
     name: 'layout',
     order: 15,
     validate: (root, context) => {