@wix/agent-skills 1.18.2 → 1.19.1

package/skills/wix-app/references/editor-react-component/CSS-GUIDELINES.md

@@ -195,6 +195,12 @@ and do not expose a visual prop solely for that purpose.
 }
 ```
 
+The same override risk applies to paintable properties. A layout-only inner
+wrapper must stay visually transparent; if it isn't, promote it to its own
+named part instead of hardcoding an opaque style on an unexposed node, since
+that style would otherwise mask the parent part's own
+`background`/`border`/`box-shadow`.
+
 ## Interaction and Motion
 
 - Set `pointer-events: auto` on the root and each interactive element.
@@ -254,3 +260,6 @@ contract; the contrast relationship is.
 - [ ] Visual containers have deliberate hierarchy rather than bare scaffolding.
 - [ ] Every explicit foreground has a known contrasting background; transparent
       components inherit foregrounds from their host.
+- [ ] No unexposed descendant inside a named part paints its own opaque
+      `background`/`border`/`box-shadow`; a wrapper needing its own surface is
+      promoted to a named part instead.

package/skills/wix-app/references/editor-react-component/PARTS.md

@@ -24,14 +24,17 @@ would plausibly control independently in the editor. It receives:
 
 - one prefixed global class: `'<component-name>-<part-name>'`
 - one CSS Module class
-- one matching `elementProps` entry, spread onto the element
+- one matching `elementProps` entry, spread onto the element. Declare `a11y` on
+  the entry only when the part reads `ariaLabel`, and destructure it out before
+  spreading (see `ACCESSIBILITY.md`)
 
 Apply this filter to every candidate:
 
 - A state or variant (`selected`, `active`, `open`, `disabled`) is not a part.
   Implement it as a prefixed design-state modifier on the affected part.
 - A hidden and shown version of the same element is one part, not two.
-- A grouping or layout-only wrapper is not a part.
+- A grouping or layout-only wrapper is not a part. A wrapper that isn't
+  visually transparent is no longer layout-only — promote it to a named part.
 - A static child whose styling and data are fully owned by its parent is not a
   part. For example, an image whose source and appearance both belong to its
   carousel slide can remain module-class-only.

package/skills/wix-app/references/editor-react-component/REACT-GUIDELINES.md

@@ -86,4 +86,4 @@ export const ProfileCard: React.FC<ProfileCardProps> = (props) => {
 - [ ] Direction and accessibility contracts are wired to the correct elements.
 - [ ] Public handlers use supported SDK names; internal handlers stay internal.
 - [ ] CSS changed by the request keeps editable selectors flat and scoped.
-- [ ] The accessibility review runs after JSX edits.
+- [ ] The accessibility review command passes, or its remaining findings are triaged.

package/skills/wix-app/scripts/pkg-root.cjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Prints the install directory of a package — the folder holding its
+// package.json — resolved from the current working directory.
+//
+//   node pkg-root.cjs @wix/patterns
+//
+// Takes the package name as an argument and knows nothing about any particular
+// package, so it stays correct as the packages it is pointed at change.
+//
+// Three steps, because one is not enough in the repos this runs in:
+//   1. Activate Yarn PnP if a .pnp.cjs exists at or above cwd. A bare
+//      require.resolve throws in a Yarn Berry project even when the package is
+//      installed, and in a monorepo the .pnp.cjs sits at the repo root rather
+//      than beside the project being built.
+//   2. require.resolve, which handles npm, pnpm and workspace layouts.
+//   3. Failing that, walk up looking for node_modules/<pkg> directly, which
+//      covers a partially-installed tree where resolution fails but the files
+//      are on disk.
+const fs = require('fs');
+const path = require('path');
+
+const pkg = process.argv[2];
+if (!pkg) {
+  console.error('usage: pkg-root.cjs <package-name>');
+  process.exit(2);
+}
+
+function activatePnp() {
+  let dir = process.cwd();
+  for (;;) {
+    const pnp = path.join(dir, '.pnp.cjs');
+    if (fs.existsSync(pnp)) {
+      try {
+        require(pnp).setup();
+      } catch {
+        // An unusable .pnp.cjs is not fatal: the plain resolve below may still
+        // succeed against a node_modules tree.
+      }
+      return;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return;
+    dir = parent;
+  }
+}
+
+activatePnp();
+
+try {
+  console.log(
+    path.dirname(
+      require.resolve(`${pkg}/package.json`, { paths: [process.cwd()] }),
+    ),
+  );
+  process.exit(0);
+} catch {
+  // fall through to the directory walk
+}
+
+let dir = process.cwd();
+for (;;) {
+  const candidate = path.join(dir, 'node_modules', ...pkg.split('/'));
+  if (fs.existsSync(path.join(candidate, 'package.json'))) {
+    console.log(candidate);
+    process.exit(0);
+  }
+  const parent = path.dirname(dir);
+  if (parent === dir) {
+    console.error(`${pkg} not found from ${process.cwd()}`);
+    process.exit(1);
+  }
+  dir = parent;
+}

package/skills/wix-app/scripts/scan-a11y-code.cjs

@@ -157,6 +157,21 @@ const UNSUPPORTED_ARIA_ELEMENTS = new Set([
 ]);
 
 const FILE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];
+/** `A11y` fields a component may read. ZeroConfig turns each read into an editor control. */
+const A11Y_FIELDS = new Set(['ariaLabel']);
+const A11Y_FIELDS_LABEL = [...A11Y_FIELDS].join(', ');
+const A11Y_CONVERTER = 'convertA11yKeysToHtmlFormat';
+const HARDCODED_LABEL_ATTRIBUTES = new Set(['aria-label', 'aria-description']);
+const SUPPORTED_RULES = [
+  'alt-text',
+  'anchor-is-valid',
+  'aria-props',
+  'aria-role',
+  'aria-unsupported-elements',
+  'a11y-whole-object',
+  'a11y-disallowed-field',
+  'hardcoded-aria-label',
+];
 const parseCache = new Map();
 const resolutionWarnings = [];
 
@@ -189,12 +204,8 @@ function parseFile(filePath) {
         'optionalChaining',
         'nullishCoalescingOperator',
       ],
-      errorRecovery: true,
     });
-    const recoverableErrors = Array.isArray(ast.errors)
-      ? ast.errors.map((error) => error.message)
-      : [];
-    const parsed = { ok: true, ast, code, recoverableErrors };
+    const parsed = { ok: true, ast, code };
     parseCache.set(filePath, parsed);
     return parsed;
   } catch (error) {
@@ -557,6 +568,132 @@ function toRelative(filePath) {
   return path.relative(ROOT, filePath) || filePath;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Per-part a11y contract helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Peel type assertions, parentheses, and guards such as `a11y && x` or `x ?? {}`. */
+function unwrapExpression(node) {
+  let current = node;
+  for (let guard = 0; current && guard < 20; guard++) {
+    if (
+      t.isTSAsExpression(current) ||
+      t.isTSNonNullExpression(current) ||
+      t.isTSTypeAssertion(current) ||
+      t.isParenthesizedExpression(current) ||
+      (t.isTSSatisfiesExpression && t.isTSSatisfiesExpression(current))
+    ) {
+      current = current.expression;
+    } else if (t.isLogicalExpression(current)) {
+      current = current.operator === '&&' ? current.right : current.left;
+    } else {
+      break;
+    }
+  }
+  return current;
+}
+
+function isA11yIdentifierName(name) {
+  return name === 'a11y' || name.endsWith('A11y');
+}
+
+/** `a11y`, `toggleA11y`, `props.a11y`, `elementProps?.toggle?.a11y`. */
+function isA11yLike(node) {
+  const expr = unwrapExpression(node);
+  if (t.isIdentifier(expr)) return isA11yIdentifierName(expr.name);
+  if ((t.isMemberExpression(expr) || t.isOptionalMemberExpression(expr)) && !expr.computed) {
+    return t.isIdentifier(expr.property, { name: 'a11y' });
+  }
+  return false;
+}
+
+/** `props.elementProps?.toggle` → ['props', 'elementProps', 'toggle']; null for other shapes. */
+function memberChain(node) {
+  const expr = unwrapExpression(node);
+  if (t.isIdentifier(expr)) return [expr.name];
+  if ((t.isMemberExpression(expr) || t.isOptionalMemberExpression(expr)) && !expr.computed) {
+    const parent = memberChain(expr.object);
+    if (!parent || !t.isIdentifier(expr.property)) return null;
+    return [...parent, expr.property.name];
+  }
+  return null;
+}
+
+function isElementPropsPartChain(chain, partsWithA11y) {
+  if (!chain || chain.length < 2) return false;
+  const index = chain.indexOf('elementProps');
+  return index !== -1 && index === chain.length - 2 && partsWithA11y.has(chain[chain.length - 1]);
+}
+
+function typeLiteralHasMember(typeNode, memberName) {
+  return (
+    t.isTSTypeLiteral(typeNode) &&
+    typeNode.members.some(
+      (member) =>
+        t.isTSPropertySignature(member) &&
+        ((t.isIdentifier(member.key) && member.key.name === memberName) ||
+          (t.isStringLiteral(member.key) && member.key.value === memberName)),
+    )
+  );
+}
+
+/**
+ * Names of `elementProps` parts whose declared type carries an `a11y` field,
+ * keyed by folder so one component's contract never applies to another.
+ * Reads every `*.props.ts` next to the scanned files plus the files themselves.
+ */
+function collectPropsTypes(files) {
+  const partsByDir = new Map();
+  const candidates = new Set(files);
+  for (const file of files) {
+    const dir = path.dirname(file);
+    if (!partsByDir.has(dir)) partsByDir.set(dir, new Set());
+    if (!fs.existsSync(dir)) continue;
+    for (const name of fs.readdirSync(dir)) {
+      if (name.endsWith('.props.ts')) candidates.add(path.join(dir, name));
+    }
+  }
+
+  for (const file of candidates) {
+    const parsed = parseFile(file);
+    if (!parsed.ok) continue;
+    const partsWithA11y = partsByDir.get(path.dirname(file));
+    traverse(parsed.ast, {
+      TSPropertySignature(path) {
+        const { key, typeAnnotation } = path.node;
+        if (!t.isIdentifier(key, { name: 'elementProps' }) || !typeAnnotation) return;
+        const literal = typeAnnotation.typeAnnotation;
+        if (!t.isTSTypeLiteral(literal)) return;
+        for (const member of literal.members) {
+          if (!t.isTSPropertySignature(member) || !member.typeAnnotation) continue;
+          const partName = t.isIdentifier(member.key)
+            ? member.key.name
+            : t.isStringLiteral(member.key)
+              ? member.key.value
+              : null;
+          if (partName && typeLiteralHasMember(member.typeAnnotation.typeAnnotation, 'a11y')) {
+            partsWithA11y.add(partName);
+          }
+        }
+      },
+    });
+  }
+
+  return partsByDir;
+}
+
+function contractFinding(filePath, node, rule, confidence, message) {
+  return findingFromNode(filePath, node, {
+    rule,
+    confidence,
+    message,
+    componentName: null,
+    semanticType: 'a11y-contract',
+    evidence: 'Per-part accessibility contract (ACCESSIBILITY.md).',
+    sourceKind: 'contract',
+  });
+}
+
 function findingFromNode(filePath, node, data) {
   return {
     file: toRelative(filePath),
@@ -572,7 +709,7 @@ function findingFromNode(filePath, node, data) {
   };
 }
 
-function scanFile(filePath) {
+function scanFile(filePath, options = {}) {
   const parsed = parseFile(filePath);
   if (!parsed.ok) {
     return {
@@ -586,9 +723,124 @@ function scanFile(filePath) {
 
   const imports = getImportMap(parsed.ast);
   const findings = [];
-  const parseWarnings = parsed.recoverableErrors || [];
+  const partsWithA11y = options.partsWithA11y || new Set();
+
+  const reportDisallowedField = (node, fieldName) => {
+    findings.push(
+      contractFinding(
+        filePath,
+        node,
+        'a11y-disallowed-field',
+        'high',
+        `a11y.${fieldName} is read; only ${A11Y_FIELDS_LABEL} may be read. Keep roles, state, and structure in component code.`,
+      ),
+    );
+  };
 
   traverse(parsed.ast, {
+    JSXSpreadAttribute(path) {
+      const argument = unwrapExpression(path.node.argument);
+
+      if (isA11yLike(argument)) {
+        findings.push(
+          contractFinding(
+            filePath,
+            path.node,
+            'a11y-whole-object',
+            'high',
+            'The whole a11y object is spread onto an element; every field becomes an editor control.',
+          ),
+        );
+        return;
+      }
+
+      // A spread identifier may alias `a11y` or an `elementProps` part; follow its declaration.
+      let chain = memberChain(argument);
+      if (t.isIdentifier(argument)) {
+        const binding = path.scope.getBinding(argument.name);
+        const declarator = binding && binding.path && binding.path.node;
+        if (declarator && t.isVariableDeclarator(declarator) && t.isIdentifier(declarator.id)) {
+          if (declarator.init && isA11yLike(declarator.init)) {
+            findings.push(
+              contractFinding(
+                filePath,
+                path.node,
+                'a11y-whole-object',
+                'high',
+                `${argument.name} aliases the a11y object and is spread onto an element; read a11y.ariaLabel instead.`,
+              ),
+            );
+            return;
+          }
+          chain = memberChain(declarator.init);
+        }
+      }
+      if (isElementPropsPartChain(chain, partsWithA11y)) {
+        findings.push(
+          contractFinding(
+            filePath,
+            path.node,
+            'a11y-whole-object',
+            'medium',
+            `elementProps.${chain[chain.length - 1]} is spread although its type declares a11y; destructure a11y out first.`,
+          ),
+        );
+      }
+    },
+
+    CallExpression(path) {
+      const callee = path.node.callee;
+      const isConverter =
+        t.isIdentifier(callee, { name: A11Y_CONVERTER }) ||
+        ((t.isMemberExpression(callee) || t.isOptionalMemberExpression(callee)) &&
+          t.isIdentifier(callee.property, { name: A11Y_CONVERTER }));
+      if (isConverter) {
+        findings.push(
+          contractFinding(
+            filePath,
+            path.node,
+            'a11y-whole-object',
+            'high',
+            `${A11Y_CONVERTER} writes every a11y field to the DOM; read only the field the part needs.`,
+          ),
+        );
+      }
+    },
+
+    'MemberExpression|OptionalMemberExpression'(path) {
+      const { node } = path;
+      if (node.computed || !t.isIdentifier(node.property)) return;
+      if (!isA11yLike(node.object)) return;
+      if (A11Y_FIELDS.has(node.property.name)) return;
+      reportDisallowedField(node.property, node.property.name);
+    },
+
+    VariableDeclarator(path) {
+      const { id, init } = path.node;
+      if (!t.isObjectPattern(id) || !init || !isA11yLike(init)) return;
+      for (const property of id.properties) {
+        if (t.isRestElement(property)) {
+          findings.push(
+            contractFinding(
+              filePath,
+              property,
+              'a11y-whole-object',
+              'high',
+              'Rest-destructuring a11y keeps every field; pick the single field the part needs.',
+            ),
+          );
+          continue;
+        }
+        if (!t.isObjectProperty(property) || property.computed) continue;
+        const fieldName = t.isIdentifier(property.key)
+          ? property.key.name
+          : t.isStringLiteral(property.key)
+            ? property.key.value
+            : null;
+        if (fieldName && !A11Y_FIELDS.has(fieldName)) reportDisallowedField(property, fieldName);
+      }
+    },
+
     JSXOpeningElement(path) {
       const node = path.node;
       const name = getJsxName(node.name);
@@ -600,6 +852,23 @@ function scanFile(filePath) {
       );
       const roleAttr = getAttribute(node, 'role');
 
+      for (const attr of ariaAttrs) {
+        const attrName = getJsxName(attr.name);
+        if (!HARDCODED_LABEL_ATTRIBUTES.has(attrName)) continue;
+        const literal = getLiteralAttributeValue(attr);
+        if (typeof literal === 'string' && literal.trim() !== '') {
+          findings.push(
+            contractFinding(
+              filePath,
+              attr,
+              'hardcoded-aria-label',
+              'high',
+              `${attrName}="${literal}" is a hardcoded string; use visible text, a11y.ariaLabel, or a constants.ts label.`,
+            ),
+          );
+        }
+      }
+
       if (semantic.semanticType === 'img' && semantic.confidence !== 'low') {
         const altAttr = getAttribute(node, 'alt');
         if (!altAttr) {
@@ -714,35 +983,19 @@ function scanFile(filePath) {
     },
   });
 
-  return { parseError: null, findings, parseWarnings };
+  return { parseError: null, findings };
 }
 
-function main() {
-  const files = process.argv.slice(2);
-  if (files.length === 0) {
-    console.log(
-      JSON.stringify(
-        {
-          error: 'No files specified.',
-          usage: 'node <SKILL_ROOT>/scripts/scan-a11y-code.cjs <file1> [file2] ...',
-        },
-        null,
-        2,
-      ),
-    );
-    process.exit(1);
-  }
+/** Scan the given files. Any syntax error lands in `meta.parseErrors`; the review treats it as fatal. */
+function scan(files) {
+  const absoluteFiles = files.map((file) => path.resolve(file));
+  const partsByDir = collectPropsTypes(absoluteFiles);
 
   const meta = {
     filesScanned: files.length,
     parser: '@babel/parser',
-    supportedRules: [
-      'alt-text',
-      'anchor-is-valid',
-      'aria-props',
-      'aria-role',
-      'aria-unsupported-elements',
-    ],
+    supportedRules: SUPPORTED_RULES,
+    a11yFields: [...A11Y_FIELDS],
     confidenceModel: ['high', 'medium', 'low', 'unknown'],
     parseErrors: [],
     resolutionWarnings,
@@ -750,15 +1003,9 @@ function main() {
 
   const findings = [];
 
-  for (const file of files.map((file) => path.resolve(file))) {
-    const result = scanFile(file);
+  for (const file of absoluteFiles) {
+    const result = scanFile(file, { partsWithA11y: partsByDir.get(path.dirname(file)) });
     if (result.parseError) meta.parseErrors.push(result.parseError);
-    for (const warning of result.parseWarnings || []) {
-      meta.parseErrors.push({
-        file: toRelative(file),
-        message: warning,
-      });
-    }
     findings.push(...result.findings);
   }
 
@@ -771,7 +1018,30 @@ function main() {
     cleanFiles: files.length - new Set(findings.map((item) => item.file)).size,
   };
 
-  console.log(JSON.stringify({ meta, findings, summary }, null, 2));
+  return { meta, findings, summary };
 }
 
-main();
+function main() {
+  const files = process.argv.slice(2);
+  if (files.length === 0) {
+    console.log(
+      JSON.stringify(
+        {
+          error: 'No files specified.',
+          usage: 'node <SKILL_ROOT>/scripts/scan-a11y-code.cjs <file1> [file2] ...',
+        },
+        null,
+        2,
+      ),
+    );
+    process.exit(1);
+  }
+
+  console.log(JSON.stringify(scan(files), null, 2));
+}
+
+module.exports = { scan };
+
+if (require.main === module) {
+  main();
+}