@wix/origami-transforms 0.1.28 → 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/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

@@ -2,3 +2,12 @@
 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/layoutError.d.ts

@@ -1,17 +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

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,7 +68,7 @@ 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 & {
+export type CssTransformPlugin<Check extends string> = TransformPluginBase<Check> & {
     prepare?: (root: import("postcss").Root, context: CssTransformContext) => Promise<void | {
         fetched: number;
         failed: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/origami-transforms",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "Babel and PostCSS checks and transforms for Wix origami page files.",
   "main": "./src/index.js",
   "files": [
@@ -13,7 +13,7 @@
     "test": "node --test test/*.spec.js",
     "test:browser": "node test/spx.browser.mjs && node test/semanticContainer.browser.mjs",
     "clean": "rm -rf dist tsconfig.tsbuildinfo",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.checks.json"
   },
   "dependencies": {
     "@babel/core": "^7.26.0",
@@ -71,5 +71,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "falconPackageHash": "1fbeabb662063771eaf3dbbb2b84d3ea8ba71598556ee82a91d545fa"
+  "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
         }
 
@@ -337,7 +341,8 @@ export const customEnumsPlugin = {
         }
 
         // 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.
@@ -348,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,
@@ -380,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) => {

package/src/cssPlugins/layout/parser.js

@@ -1,3 +1,4 @@
+import { fail } from './index.js'
 import { basename } from 'node:path'
 import { isValidContainerId } from '@wix/origami-system-components/layout-contract'
 import { relativeToSite } from '../../transform/relativeToSite.js'
@@ -20,7 +21,7 @@ export const parseTargets = (root, context) => {
     const owners = new Map()
     root.walkAtRules('origami-target', target => {
         const name = target.params.trim()
-        if (!Object.hasOwn(targets, name)) throw target.error(`Unknown @origami-target ${name}`)
+        if (!Object.hasOwn(targets, name)) throw fail('unknown_target', target.error(`Unknown @origami-target ${name}`))
         const owner = target.parent
         // DM writes component rules as .compId; #compId is still accepted.
         if (
@@ -28,34 +29,34 @@ export const parseTargets = (root, context) => {
             !['.', '#'].includes(owner.selector[0]) ||
             !isValidContainerId(owner.selector.slice(1))
         ) {
-            throw target.error('@origami-target requires a single component ID rule')
+            throw fail('target_requires_component_id', target.error('@origami-target requires a single component ID rule'))
         }
         for (let ancestor = owner.parent; ancestor && ancestor.type !== 'root'; ancestor = ancestor.parent) {
             if (
                 ancestor.type !== 'atrule' ||
                 !['scope', 'media', 'layer', 'supports', 'container'].includes(ancestor.name)
             ) {
-                throw target.error('@origami-target is only allowed inside layout rule envelopes')
+                throw fail('invalid_target_envelope', target.error('@origami-target is only allowed inside layout rule envelopes'))
             }
         }
         if (!isLayoutSource(target, context))
-            throw target.error('@origami-target must originate in site-owned layout.css')
+            throw fail('target_not_site_layout', target.error('@origami-target must originate in site-owned layout.css'))
         const siblings = owners.get(owner) ?? []
-        if (siblings.some(sibling => sibling.params.trim() === name)) throw target.error(`Duplicate target ${name}`)
+        if (siblings.some(sibling => sibling.params.trim() === name)) throw fail('duplicate_target', target.error(`Duplicate target ${name}`))
         const seen = new Set()
         for (const node of target.nodes ?? []) {
             if (node.type === 'comment') continue
-            if (node.type !== 'decl') throw node.error('Target bodies must contain declarations only')
-            if (seen.has(node.prop)) throw node.error(`Duplicate target property ${node.prop}`)
+            if (node.type !== 'decl') throw fail('target_requires_declarations', node.error('Target bodies must contain declarations only'))
+            if (seen.has(node.prop)) throw fail('duplicate_target_property', node.error(`Duplicate target property ${node.prop}`))
             seen.add(node.prop)
-            if (!targets[name].has(node.prop)) throw node.error(`${node.prop} does not belong to ${name}`)
+            if (!targets[name].has(node.prop)) throw fail('property_wrong_target', node.error(`${node.prop} does not belong to ${name}`))
             if (node.prop === 'position' && node.value !== 'relative')
-                throw node.error('Content position must be relative')
+                throw fail('content_position_not_relative', node.error('Content position must be relative'))
             if (name === OVERFLOW && !['auto', 'scroll', 'hidden', 'visible', 'clip'].includes(node.value)) {
-                throw node.error(`Unsupported overflow value ${node.value}`)
+                throw fail('unsupported_overflow', node.error(`Unsupported overflow value ${node.value}`))
             }
             if (node.prop === '--content-max-width-align' && !['left', 'center', 'right'].includes(node.value)) {
-                throw node.error(`Unsupported content alignment ${node.value}`)
+                throw fail('unsupported_content_alignment', node.error(`Unsupported content alignment ${node.value}`))
             }
             if (node.prop === 'display') {
                 const type = owner.nodes.find(item => item.type === 'decl' && item.prop === '--container-layout-type')
@@ -64,7 +65,7 @@ export const parseTargets = (root, context) => {
                     (type?.type === 'decl' &&
                         (!Object.hasOwn(displays, type.value) || displays[type.value] !== node.value))
                 ) {
-                    throw node.error('Container type and content display are inconsistent')
+                    throw fail('inconsistent_container_display', node.error('Container type and content display are inconsistent'))
                 }
             }
         }
@@ -75,10 +76,10 @@ export const parseTargets = (root, context) => {
         const seen = new Set()
         for (const node of owner.nodes) {
             if (node.type !== 'decl') continue
-            if (seen.has(node.prop)) throw node.error(`Duplicate root property ${node.prop}`)
+            if (seen.has(node.prop)) throw fail('duplicate_root_property', node.error(`Duplicate root property ${node.prop}`))
             seen.add(node.prop)
             if ((targets[CONTENT].has(node.prop) && node.prop !== 'position') || targets[OVERFLOW].has(node.prop)) {
-                throw node.error(`${node.prop} belongs inside @origami-target`)
+                throw fail('property_requires_target', node.error(`${node.prop} belongs inside @origami-target`))
             }
         }
     }

package/src/cssPlugins/mixins.js

@@ -7,8 +7,15 @@ const MAX_CLONED_BYTES = 10 * 1024 * 1024
 /** @param {import('postcss').AtRule} atRule */
 const mixinName = atRule => atRule.params.trim().replace(/\(\)$/, '')
 
-/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const checks = /** @type {const} */ (['missing_mixin', 'cyclic_apply', 'expansion_depth_exceeded', 'cloned_node_budget_exceeded', 'cloned_css_budget_exceeded'])
+/** @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 mixinsPlugin = {
+    checks,
     name: 'mixins',
     order: 10,
     transform(root) {
@@ -30,16 +37,16 @@ export const mixinsPlugin = {
             container.walkAtRules('apply', atRule => {
                 const name = mixinName(atRule)
                 const body = bodies.get(name)
-                if (!body) throw new Error(`@apply ${atRule.params} has no @mixin definition`)
-                if (stack.includes(name)) throw new Error(`Cyclic @apply: ${[...stack, name].join(' -> ')}`)
+                if (!body) throw fail('missing_mixin', new Error(`@apply ${atRule.params} has no @mixin definition`))
+                if (stack.includes(name)) throw fail('cyclic_apply', new Error(`Cyclic @apply: ${[...stack, name].join(' -> ')}`))
                 if (stack.length >= MAX_EXPANSION_DEPTH) {
-                    throw new Error(`@apply ${name} exceeds maximum expansion depth (${MAX_EXPANSION_DEPTH})`)
+                    throw fail('expansion_depth_exceeded', new Error(`@apply ${name} exceeds maximum expansion depth (${MAX_EXPANSION_DEPTH})`))
                 }
                 const pending = [...body]
                 while (pending.length) {
                     const node = pending.pop()
                     if (++clonedNodes > MAX_CLONED_NODES) {
-                        throw new Error(`@apply ${name} exceeds stylesheet cloned-node budget (${MAX_CLONED_NODES})`)
+                        throw fail('cloned_node_budget_exceeded', new Error(`@apply ${name} exceeds stylesheet cloned-node budget (${MAX_CLONED_NODES})`))
                     }
                     if (node && 'nodes' in node && node.nodes) {
                         for (const child of node.nodes) pending.push(child)
@@ -48,7 +55,7 @@ export const mixinsPlugin = {
                 for (const node of body) {
                     clonedBytes += Buffer.byteLength((node.raws.before ?? '') + node.toString(), 'utf8')
                     if (clonedBytes > MAX_CLONED_BYTES) {
-                        throw new Error(`@apply ${name} exceeds stylesheet cloned-CSS byte budget (${MAX_CLONED_BYTES})`)
+                        throw fail('cloned_css_budget_exceeded', new Error(`@apply ${name} exceeds stylesheet cloned-CSS byte budget (${MAX_CLONED_BYTES})`))
                     }
                 }
                 // PostCSS does not revisit nodes inserted in place of the current at-rule.

package/src/cssPlugins/presets.js

@@ -23,8 +23,12 @@ const target = (selector, key) => {
     return selector === first ? `.${id}${WRAPPER}` : null
 }
 
-/** @type {import('../transform/types.js').CssTransformPlugin} */
+const checks = /** @type {const} */ ([])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
 export const presetsPlugin = {
+    checks,
     name: 'presets',
     order: 13,
     transform(root, context) {

package/src/cssPlugins/shapeDividers.js

@@ -101,8 +101,12 @@ const layerDeclarations = (compId, vars) => {
     }
 }
 
-/** @type {import('../transform/types.js').CssTransformPlugin} */
+const checks = /** @type {const} */ ([])
+/** @typedef {typeof checks[number]} Check */
+
+/** @type {import('../transform/types.js').CssTransformPlugin<Check>} */
 export const shapeDividersPlugin = {
+    checks,
     name: 'shape-dividers',
     // Last, with wix-vector-urls: it only adds rules, which no other plugin needs to see, and it reads only `--height` as
     // `var(--height)`, so spx converts that var's `--spx()` where it is declared.

package/src/cssPlugins/spx/calls.js

@@ -1,3 +1,4 @@
+import { fail } from './index.js'
 const CALL = /--spx\(\s*(-?(?:\d+\.?\d*|\.\d+))\s*\)/g
 
 /** Replace literal SPX calls, reporting unsupported arguments at their declaration.
@@ -8,5 +9,5 @@ const CALL = /--spx\(\s*(-?(?:\d+\.?\d*|\.\d+))\s*\)/g
 export const lowerCalls = (declaration, resolve, invalidCall) => {
     if (!declaration.value.includes('--spx(')) return
     declaration.value = declaration.value.replace(CALL, (_, literal) => resolve(Number(literal)))
-    if (declaration.value.includes('--spx(')) throw invalidCall()
+    if (declaration.value.includes('--spx(')) throw fail('non_literal_spx_argument', invalidCall())
 }

package/src/cssPlugins/spx/cascade.js

@@ -1,3 +1,4 @@
+import { fail } from './index.js'
 import { lowerCalls } from './calls.js'
 
 // Keep arithmetic at the call site: an inherited derived custom property would already
@@ -16,7 +17,7 @@ const UNCAPPED_UNIT = unitCappedAt('99999px')
 export const compileCascadeDeclaration = declaration => {
     if (declaration.prop === '--spx-resolver-type') {
         const resolver = declaration.value.trim()
-        if (!['scale', 'fixed'].includes(resolver)) throw declaration.error('Unsupported SPX resolver')
+        if (!['scale', 'fixed'].includes(resolver)) throw fail('unsupported_spx_resolver', declaration.error('Unsupported SPX resolver'))
         const value = resolver === 'scale' ? '1' : '0'
         const previous = declaration.prev()
         if (
@@ -32,7 +33,7 @@ export const compileCascadeDeclaration = declaration => {
         declaration.prop === '--spx-ref-width' &&
         (!Number.isFinite(Number(declaration.value)) || Number(declaration.value) <= 0)
     ) {
-        throw declaration.error('SPX reference width must be positive')
+        throw fail('invalid_spx_reference_width', declaration.error('SPX reference width must be positive'))
     }
     const unit = declaration.prop === '--content-max-width' ? UNCAPPED_UNIT : UNIT
     lowerCalls(

package/src/cssPlugins/spx/index.js

@@ -1,7 +1,14 @@
 import { compileCascadeDeclaration } from './cascade.js'
 
-/** @type {import('../../transform/types.js').CssTransformPlugin} */
+export const checks = /** @type {const} */ (['unsupported_spx_resolver', 'invalid_spx_reference_width', 'non_literal_spx_argument'])
+/** @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 spxPlugin = {
+    checks,
     name: 'spx',
     order: 20,
     transform(root) {

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