@wix/agent-skills 1.19.0 → 1.19.2

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();
+}

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

@@ -3,6 +3,7 @@
 
 // oxlint-disable no-console preserve-caught-error
 
+const fs = require('fs');
 const path = require('path');
 const { createRequire } = require('module');
 
@@ -34,10 +35,11 @@ const RULE_CONFIG = {
   'jsx-a11y/no-aria-hidden-on-focusable': 'error',
   'jsx-a11y/no-autofocus': 'error',
   'jsx-a11y/no-distracting-elements': 'error',
-  'jsx-a11y/no-interactive-element-to-noninteractive-role': 'error',
+  'jsx-a11y/no-interactive-element-to-noninteractive-role': ['error', { canvas: ['img'] }],
   'jsx-a11y/no-noninteractive-element-interactions': 'error',
   'jsx-a11y/no-noninteractive-element-to-interactive-role': 'error',
-  'jsx-a11y/no-noninteractive-tabindex': 'error',
+  // A tabpanel with no focusable content takes tabIndex=0 (ARIA Authoring Practices).
+  'jsx-a11y/no-noninteractive-tabindex': ['error', { roles: ['tabpanel'] }],
   'jsx-a11y/no-redundant-roles': 'error',
   'jsx-a11y/no-static-element-interactions': 'error',
   'jsx-a11y/prefer-tag-over-role': 'error',
@@ -51,6 +53,86 @@ function toRelative(filePath) {
   return path.relative(ROOT, filePath) || filePath;
 }
 
+/** DOM handler → SDK prop it forwards (FUNCTION-HANDLERS.md). */
+const SDK_HANDLER_PROPS = {
+  onClick: 'onClick',
+  onDoubleClick: 'onDblClick',
+  onMouseEnter: 'onMouseIn',
+  onMouseLeave: 'onMouseOut',
+};
+const isSdkRoot = (tag) => /\bid=\{\s*(?:props\.)?id\s*\}/.test(tag);
+
+/** Every handler on the tag forwards its SDK prop, `onClick={onClick}` or `onMouseEnter={props.onMouseIn}`; anything else makes the root a control. */
+function forwardsOnlySdkHandlers(tag) {
+  const handlers = [...tag.matchAll(/\b(on[A-Z]\w*)=\{([^}]*)\}/g)];
+  return (
+    handlers.length > 0 &&
+    handlers.every(([, name, value]) => {
+      const sdkProp = SDK_HANDLER_PROPS[name];
+      return Boolean(sdkProp) && value.trim().replace(/^props\./, '') === sdkProp;
+    })
+  );
+}
+
+/** Roles whose native element cannot express a styled component. */
+const ROLES_WITHOUT_NATIVE_TAG = new Set(['img', 'presentation', 'none', 'group', 'status']);
+
+/**
+ * `role="img"` or `role={cond ? 'img' : undefined}`: every string literal in the role
+ * attribute must be an exempt role, so `role={cond ? 'button' : 'img'}` stays flagged.
+ */
+function roleHasNoNativeTag(tag) {
+  const attr = tag.match(/\brole=(?:"[^"]*"|'[^']*'|\{[^}]*\})/);
+  if (!attr) return false;
+  const literals = [...attr[0].slice(5).matchAll(/["']([^"']*)["']/g)].map((m) => m[1]);
+  return literals.length > 0 && literals.every((role) => ROLES_WITHOUT_NATIVE_TAG.has(role));
+}
+
+/**
+ * Editor React Component patterns that jsx-a11y reads as defects. A rule in
+ * `rules` is skipped when the opening tag of the reported element matches `tag`.
+ */
+const EXEMPTIONS = [
+  {
+    // SDK handlers (`onClick`, `onMouseIn`, ...) are forwarded on the root
+    // element, which carries `id={id}`; the root itself is not the control.
+    rules: new Set([
+      'jsx-a11y/click-events-have-key-events',
+      'jsx-a11y/mouse-events-have-key-events',
+      'jsx-a11y/no-noninteractive-element-interactions',
+      'jsx-a11y/no-static-element-interactions',
+    ]),
+    tag: (tag) => isSdkRoot(tag) && forwardsOnlySdkHandlers(tag),
+  },
+  {
+    // Roles whose native element cannot express a styled component: graphics
+    // (svg, canvas, star ratings), decorative wrappers, widget groups, live
+    // regions. axe still requires their names (`role-img-alt`).
+    rules: new Set(['jsx-a11y/prefer-tag-over-role']),
+    tag: roleHasNoNativeTag,
+  },
+];
+
+/** Text of the opening tag that contains the reported range. */
+function openingTag(source, msg) {
+  const lines = source.split('\n');
+  const offset =
+    lines.slice(0, msg.line - 1).reduce((n, line) => n + line.length + 1, 0) + msg.column - 1;
+  const start = source.lastIndexOf('<', offset);
+  if (start === -1) return '';
+  // The tag ends at the first `>` outside braces, so `=>` inside handlers does not count.
+  let depth = 0;
+  for (let i = start; i < source.length; i++) {
+    if (source[i] === '{') depth++;
+    else if (source[i] === '}') depth--;
+    else if (source[i] === '>' && depth === 0) return source.slice(start, i);
+  }
+  return '';
+}
+
+const isExempt = (source, msg) =>
+  EXEMPTIONS.some((x) => x.rules.has(msg.ruleId) && x.tag(openingTag(source, msg)));
+
 function severityLabel(severity) {
   if (severity === 2) return 'error';
   if (severity === 1) return 'warning';
@@ -117,22 +199,11 @@ function createEslint() {
   }
 }
 
-async 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-eslint.cjs <file1> [file2] ...',
-        },
-        null,
-        2,
-      ),
-    );
-    process.exit(1);
-  }
-
+/**
+ * Lint the given files with the jsx-a11y rule set.
+ * Returns the same report shape the CLI prints.
+ */
+async function scan(files) {
   const absoluteFiles = files.map((f) => path.resolve(f));
 
   const eslint = createEslint();
@@ -144,6 +215,7 @@ async function main() {
 
   for (const result of results) {
     const relFile = toRelative(result.filePath);
+    const source = () => result.source || fs.readFileSync(result.filePath, 'utf8');
 
     for (const msg of result.messages) {
       if (msg.fatal) {
@@ -157,6 +229,7 @@ async function main() {
       }
 
       if (!msg.ruleId || !msg.ruleId.startsWith('jsx-a11y/')) continue;
+      if (isExempt(source(), msg)) continue;
 
       findings.push({
         file: relFile,
@@ -176,7 +249,7 @@ async function main() {
     ruleBreakdown[f.rule] = (ruleBreakdown[f.rule] || 0) + 1;
   }
 
-  const output = {
+  return {
     meta: {
       filesScanned: files.length,
       engine: 'eslint + eslint-plugin-jsx-a11y',
@@ -191,11 +264,32 @@ async function main() {
       ruleBreakdown,
     },
   };
+}
+
+async 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-eslint.cjs <file1> [file2] ...',
+        },
+        null,
+        2,
+      ),
+    );
+    process.exit(1);
+  }
 
-  console.log(JSON.stringify(output, null, 2));
+  console.log(JSON.stringify(await scan(files), null, 2));
 }
 
-main().catch((err) => {
-  console.error(JSON.stringify({ error: err.message }, null, 2));
-  process.exit(1);
-});
+module.exports = { scan, RULE_CONFIG };
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(JSON.stringify({ error: err.message }, null, 2));
+    process.exit(1);
+  });
+}