@wix/agent-skills 1.19.0 → 1.19.2

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

@@ -0,0 +1,551 @@
+#!/usr/bin/env node
+'use strict';
+
+// oxlint-disable no-console preserve-caught-error no-underscore-dangle
+
+/**
+ * Render audit for one Editor React Component folder.
+ *
+ * Renders the component with its default props in plain Node (an SSR check),
+ * loads the markup into jsdom together with the component's CSS Modules, and
+ * runs axe-core against the rendered root. Prints one JSON line.
+ *
+ * Spawned by `scan-a11y-review.cjs`; also usable standalone:
+ *
+ *   node <SKILL_ROOT>/scripts/scan-a11y-render.cjs <component-dir>
+ */
+
+const fs = require('fs');
+const path = require('path');
+const Module = require('module');
+const { createRequire } = require('module');
+const { pathToFileURL } = require('url');
+
+const ROOT = process.cwd();
+const LOCAL_REQUIRE = createRequire(__filename);
+const ROOT_REQUIRE = createRequire(path.join(ROOT, 'package.json'));
+
+const RCU_SPECIFIER = '@wix/react-component-utils';
+/** Scanner-owned wrapper around the rendered component; axe audits this, never the component's own `id`. */
+const AUDIT_ROOT_ATTR = 'data-a11y-audit-root';
+const COMPONENT_ID = 'component';
+const SOURCE_EXTENSIONS = ['.tsx', '.ts', '.jsx'];
+/** Everything else a relative import points at (svg, png, mp4, lottie, scss, ...) is served as its file name. */
+const LOADABLE_EXTENSIONS = new Set([
+  '.js',
+  '.cjs',
+  '.mjs',
+  '.json',
+  '.node',
+  '.css',
+  ...SOURCE_EXTENSIONS,
+]);
+const HTML_SNIPPET_LENGTH = 200;
+const PLACEHOLDER_TEXT = 'No content to display yet';
+/** Test hook: comma-separated tooling packages to treat as missing. */
+const SIMULATE_MISSING = new Set(
+  (process.env.A11Y_SIMULATE_MISSING || '').split(',').filter(Boolean),
+);
+
+/** Rules that only make sense for a whole page, never for a component fragment. */
+const PAGE_RULES = [
+  'region',
+  'landmark-one-main',
+  'landmark-banner-is-top-level',
+  'landmark-complementary-is-top-level',
+  'landmark-contentinfo-is-top-level',
+  'landmark-main-is-top-level',
+  'landmark-no-duplicate-banner',
+  'landmark-no-duplicate-contentinfo',
+  'landmark-no-duplicate-main',
+  'landmark-unique',
+  'page-has-heading-one',
+  'document-title',
+  'html-has-lang',
+  'html-lang-valid',
+  'html-xml-lang-mismatch',
+  'bypass',
+  'meta-viewport',
+  'meta-viewport-large',
+  'meta-refresh',
+  'meta-refresh-no-exceptions',
+  // `frame-title` stays on: an unnamed iframe inside a component is the component's defect.
+  'frame-title-unique',
+  'frame-tested',
+  'frame-focusable-content',
+  // Deprecated in axe 4.x and noisy; `duplicate-id-aria` stays on.
+  'duplicate-id',
+  'duplicate-id-active',
+];
+
+/** Rules that need a layout engine. Disabled on jsdom; a browser engine would enable them. */
+const LAYOUT_RULES = [
+  'color-contrast',
+  'color-contrast-enhanced',
+  'target-size',
+  'scrollable-region-focusable',
+  'link-in-text-block',
+  'p-as-heading',
+];
+
+const NOT_CHECKED_BY_JSDOM = [
+  ...LAYOUT_RULES,
+  '--display-driven visibility',
+  'keyboard interaction',
+];
+
+const SITE_URL = 'https://example.wixsite.com/site';
+const HOME_PAGE = { id: 'home', title: 'Home', path: '/', popup: false };
+
+/** Plain-object stand-ins for the site services `@wix/react-component-utils` hooks read. */
+const SERVICES = {
+  // `useIsEditMode()` returns `!previewMode`; audit live-equivalent output.
+  '@wix/site-service-editor-context': { previewMode: true },
+  '@wix/site-service-device-info': { deviceType: 'Desktop', reducedMotion: false },
+  '@wix/site-service-locale': { language: 'en', direction: 'ltr' },
+  '@wix/site-service-pages': {
+    pages: { [HOME_PAGE.id]: { title: HOME_PAGE.title, path: HOME_PAGE.path, popup: false } },
+    mainPage: HOME_PAGE,
+    currentPage: HOME_PAGE,
+  },
+  '@wix/site-service-url': {
+    currentUrl: SITE_URL,
+    siteUrl: SITE_URL,
+    pages: [],
+    pageIdToPrefix: {},
+  },
+};
+
+const IMPACT_SEVERITY = { critical: 'high', serious: 'high', moderate: 'medium', minor: 'low' };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Dependencies and entry discovery
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Tooling resolves from the consumer project first, then next to this script. */
+function loadTooling(names) {
+  const modules = {};
+  const missing = [];
+  for (const name of names) {
+    if (SIMULATE_MISSING.has(name)) {
+      missing.push(name);
+      continue;
+    }
+    try {
+      modules[name] = ROOT_REQUIRE(name);
+    } catch {
+      try {
+        modules[name] = LOCAL_REQUIRE(name);
+      } catch {
+        missing.push(name);
+      }
+    }
+  }
+  return { modules, missing };
+}
+
+function listFiles(dir, predicate, acc = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== 'node_modules') listFiles(full, predicate, acc);
+    } else if (entry.isFile() && predicate(entry.name)) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+function resolveEntry(componentDir) {
+  const basename = path.basename(componentDir);
+  const existing = (name) =>
+    fs.existsSync(path.join(componentDir, name)) ? path.join(componentDir, name) : null;
+  const tsxFiles = listFiles(componentDir, (name) => name.endsWith('.tsx'));
+  const impl =
+    existing(`${basename}.tsx`) ||
+    tsxFiles.find(
+      (file) =>
+        path.dirname(file) === componentDir && !path.basename(file).startsWith('component.'),
+    ) ||
+    null;
+
+  return {
+    live: existing('component.tsx'),
+    preview: existing('component.preview.tsx'),
+    impl,
+    props: existing(`${basename}.props.ts`),
+    cssFiles: listFiles(componentDir, (name) => name.endsWith('.module.css')),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Compile hooks and runtime
+// ─────────────────────────────────────────────────────────────────────────────
+
+function installCompileHooks(ts) {
+  const compile = (module, filename) => {
+    const { outputText } = ts.transpileModule(fs.readFileSync(filename, 'utf8'), {
+      fileName: filename,
+      compilerOptions: {
+        module: ts.ModuleKind.CommonJS,
+        target: ts.ScriptTarget.ES2020,
+        jsx: ts.JsxEmit.ReactJSX,
+        esModuleInterop: true,
+        allowJs: true,
+        isolatedModules: true,
+      },
+    });
+    module._compile(outputText, filename);
+  };
+  for (const ext of SOURCE_EXTENSIONS) require.extensions[ext] = compile;
+
+  // CSS Modules map every class to its own name so the markup keeps the
+  // module class names the component CSS targets.
+  const cssProxy = new Proxy(
+    {},
+    {
+      get(_target, prop) {
+        if (prop === '__esModule') return true;
+        if (prop === 'default') return cssProxy;
+        return typeof prop === 'symbol' ? undefined : String(prop);
+      },
+    },
+  );
+  require.extensions['.css'] = (module) => {
+    module.exports = cssProxy;
+  };
+}
+
+/**
+ * Load React and `@wix/react-component-utils` from the component's own
+ * dependency tree so hooks and context share one React instance. The utils
+ * package is ESM-only, so it is imported once and served to the transpiled
+ * CommonJS component code through `Module._load`.
+ */
+async function loadRuntime(entryFile) {
+  const entryRequire = createRequire(entryFile);
+  const React = entryRequire('react');
+  const { renderToStaticMarkup } = entryRequire('react-dom/server');
+
+  const rcuDir = (entryRequire.resolve.paths(RCU_SPECIFIER) || [])
+    .map((dir) => path.join(dir, RCU_SPECIFIER))
+    .find((dir) => fs.existsSync(path.join(dir, 'package.json')));
+  if (!rcuDir) {
+    throw new Error(`Cannot resolve ${RCU_SPECIFIER} from ${path.relative(ROOT, entryFile)}.`);
+  }
+
+  const manifest = JSON.parse(fs.readFileSync(path.join(rcuDir, 'package.json'), 'utf8'));
+  const root = manifest.exports && manifest.exports['.'];
+  const entry =
+    (typeof root === 'string' ? root : root && (root.import || root.default)) || manifest.main;
+  const rcu = { __esModule: true, ...(await import(pathToFileURL(path.join(rcuDir, entry)).href)) };
+
+  const originalLoad = Module._load;
+  Module._load = function patchedLoad(request, parent, ...rest) {
+    if (request === RCU_SPECIFIER) return rcu;
+    const query = request.indexOf('?');
+    const bare = query === -1 ? request : request.slice(0, query);
+    // Packages load as-is; only the component's own relative imports get the asset treatment.
+    if (query === -1 && !/^[./]/.test(bare))
+      return originalLoad.call(this, request, parent, ...rest);
+    // Throws MODULE_NOT_FOUND for a missing file, which the audit reports as a loader limit.
+    const file = Module._resolveFilename(bare, parent);
+    if (query === -1 && LOADABLE_EXTENSIONS.has(path.extname(file).toLowerCase())) {
+      return originalLoad.call(this, request, parent, ...rest);
+    }
+    // Vite resource queries: `?raw` is the file text, `?url`/`?inline` its name. A bare asset
+    // import (mp4, lottie, scss, ...) is its name too; Node would otherwise parse it as JS.
+    const raw = query !== -1 && /(^|&)raw(&|$)/.test(request.slice(query + 1));
+    return { __esModule: true, default: raw ? fs.readFileSync(file, 'utf8') : path.basename(file) };
+  };
+
+  if (!globalThis.WixReactContext) globalThis.WixReactContext = React.createContext(undefined);
+  return { React, renderToStaticMarkup, rcu, WixContext: globalThis.WixReactContext };
+}
+
+function createServicesProvider(React, WixContext) {
+  const manager = {
+    getService(definition) {
+      const id = String(definition);
+      if (!(id in SERVICES)) {
+        throw new Error(`Unknown site service "${id}" requested during render.`);
+      }
+      return SERVICES[id];
+    },
+    hasService(definition) {
+      return String(definition) in SERVICES;
+    },
+  };
+  return ({ children }) => React.createElement(WixContext.Provider, { value: manager }, children);
+}
+
+const interopDefault = (loaded) =>
+  loaded && loaded.__esModule && loaded.default !== undefined ? loaded.default : loaded;
+
+function loadComponent(entry, runtime) {
+  if (entry.live) {
+    return { Component: interopDefault(require(entry.live)), source: 'component.tsx' };
+  }
+  if (!entry.impl) throw new Error('No component.tsx or implementation .tsx found.');
+  const Impl = interopDefault(require(entry.impl));
+  const defaultProps = entry.props ? require(entry.props).defaultProps || {} : {};
+  return {
+    Component: runtime.rcu.withDefaults(Impl, defaultProps),
+    source: path.basename(entry.impl),
+  };
+}
+
+/** The wrapper is the audit boundary, so a component that forwards `id` to an inner element still gets all of its output audited. */
+function render(runtime, Provider, Component) {
+  const { React, renderToStaticMarkup } = runtime;
+  return renderToStaticMarkup(
+    React.createElement(
+      Provider,
+      null,
+      React.createElement(
+        'div',
+        { [AUDIT_ROOT_ATTR]: '' },
+        React.createElement(Component, { id: COMPONENT_ID }),
+      ),
+    ),
+  );
+}
+
+const LOADER_ERROR_CODES = new Set([
+  'MODULE_NOT_FOUND',
+  'ERR_REQUIRE_ESM',
+  'ERR_REQUIRE_ASYNC_MODULE',
+  'ERR_UNKNOWN_FILE_EXTENSION',
+]);
+
+/** The component could not be loaded at all: a scanner limitation, never a finding. */
+const isLoaderError = (error) =>
+  Boolean(error) &&
+  (LOADER_ERROR_CODES.has(error.code) || /Cannot find module/.test(error.message || ''));
+
+function classifyRenderError(error) {
+  const message = error && error.message ? error.message : String(error);
+  if (/No ServiceManagerProvider|Unknown site service/.test(message)) {
+    return {
+      rule: 'render-unsupported-hook',
+      severity: 'low',
+      confidence: 'low',
+      message: `The component reads a site service the audit cannot provide: ${message}`,
+    };
+  }
+  const browserGlobal =
+    /\b(window|document|navigator|localStorage|sessionStorage|matchMedia)\b.*is not defined/.test(
+      message,
+    );
+  return {
+    rule: 'render-failed',
+    severity: 'high',
+    confidence: 'high',
+    message: browserGlobal
+      ? `The first render touches a browser global: ${message}`
+      : `Rendering with defaultProps threw: ${message}`,
+  };
+}
+
+const checkPreviewPlaceholder = (html) =>
+  html.includes(PLACEHOLDER_TEXT) || /class="[^"]*_placeholder_/.test(html);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// jsdom + axe
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Strip CSS Modules syntax jsdom cannot parse; keep every declaration. */
+function normalizeModuleCss(css) {
+  return css
+    .replace(/@value[^;]*;/g, '')
+    .replace(/\bcomposes\s*:[^;{}]*;/g, '')
+    .replace(/:global\(([^)]*)\)/g, '$1')
+    .replace(/:local\(([^)]*)\)/g, '$1')
+    .replace(/:global\s+/g, '');
+}
+
+function truncate(text, length) {
+  const compact = String(text || '').replace(/\s+/g, ' ');
+  return compact.length > length ? `${compact.slice(0, length - 1)}…` : compact;
+}
+
+async function runAxe(jsdom, axe, html, css) {
+  const dom = new jsdom.JSDOM(
+    `<!doctype html><html lang="en"><head><style>${css}</style></head><body>${html}</body></html>`,
+    { virtualConsole: new jsdom.VirtualConsole() },
+  );
+
+  const { window } = dom;
+  const previous = { window: globalThis.window, document: globalThis.document };
+  globalThis.window = window;
+  globalThis.document = window.document;
+  try {
+    const known = new Set(axe.getRules().map((rule) => rule.ruleId));
+    const rules = {};
+    for (const ruleId of [...PAGE_RULES, ...LAYOUT_RULES]) {
+      if (known.has(ruleId)) rules[ruleId] = { enabled: false };
+    }
+    const root = window.document.querySelector(`[${AUDIT_ROOT_ATTR}]`) || window.document.body;
+    const results = await axe.run(root, { rules, resultTypes: ['violations'], elementRef: false });
+
+    const findings = [];
+    for (const violation of results.violations) {
+      for (const node of violation.nodes) {
+        findings.push({
+          rule: violation.id,
+          source: 'render',
+          severity: IMPACT_SEVERITY[violation.impact] || 'medium',
+          confidence: 'high',
+          message: violation.help,
+          detail: truncate(node.failureSummary, 240),
+          target: node.target.join(' '),
+          html: truncate(node.html, HTML_SNIPPET_LENGTH),
+          helpUrl: violation.helpUrl,
+        });
+      }
+    }
+    return { findings, rulesRun: known.size - Object.keys(rules).length };
+  } finally {
+    globalThis.window = previous.window;
+    globalThis.document = previous.document;
+    if (previous.window === undefined) delete globalThis.window;
+    if (previous.document === undefined) delete globalThis.document;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function audit(componentDir) {
+  const report = {
+    ok: false,
+    engine: 'jsdom',
+    componentDir: path.relative(ROOT, componentDir) || '.',
+    entry: null,
+    preview: null,
+    ssr: null,
+    axe: null,
+    findings: [],
+    notChecked: [...NOT_CHECKED_BY_JSDOM],
+  };
+
+  if (!fs.existsSync(componentDir) || !fs.statSync(componentDir).isDirectory()) {
+    report.error = `Component directory not found: ${componentDir}`;
+    return report;
+  }
+
+  const { modules, missing } = loadTooling(['typescript', 'jsdom', 'axe-core']);
+  if (missing.length > 0) {
+    report.reason = 'missing-deps';
+    report.missing = missing;
+    report.error = `Missing render dependencies: ${missing.join(', ')}. Install them (SKILL.md step 2) and rerun.`;
+    return report;
+  }
+
+  const entry = resolveEntry(componentDir);
+  if (!entry.live && !entry.impl) {
+    report.error = 'No component.tsx or implementation .tsx found.';
+    return report;
+  }
+
+  installCompileHooks(modules.typescript);
+  const runtime = await loadRuntime(entry.live || entry.impl);
+  const Provider = createServicesProvider(runtime.React, runtime.WixContext);
+
+  // Live render: the markup visitors get.
+  let liveHtml = null;
+  try {
+    const { Component, source } = loadComponent(entry, runtime);
+    report.entry = source;
+    liveHtml = render(runtime, Provider, Component);
+    report.ssr = { ok: true, bytes: liveHtml.length };
+  } catch (error) {
+    if (isLoaderError(error)) {
+      report.reason = 'loader';
+      report.error = truncate(error.stack || error.message, 600);
+      return report;
+    }
+    report.ssr = { ok: false, error: truncate(error && error.stack ? error.stack : error, 600) };
+    report.findings.push({ ...classifyRenderError(error), source: 'render' });
+  }
+
+  // Preview render: must not fall back to the placeholder with default props.
+  if (entry.preview) {
+    try {
+      const Preview = interopDefault(require(entry.preview));
+      const placeholder = checkPreviewPlaceholder(render(runtime, Provider, Preview));
+      report.preview = placeholder ? 'placeholder' : 'ok';
+      if (placeholder) {
+        report.findings.push({
+          rule: 'preview-placeholder',
+          source: 'render',
+          severity: 'high',
+          confidence: 'high',
+          message:
+            'component.preview.tsx renders the fallback placeholder with defaultProps, so the editor shows an empty box.',
+        });
+      }
+    } catch (error) {
+      if (isLoaderError(error)) {
+        report.reason = 'loader';
+        report.error = truncate(error.stack || error.message, 600);
+        return report;
+      }
+      report.preview = 'failed';
+      report.findings.push({
+        rule: 'preview-render-failed',
+        source: 'render',
+        severity: 'medium',
+        confidence: 'high',
+        message: `component.preview.tsx threw with defaultProps: ${truncate(error && error.message, 200)}`,
+      });
+    }
+  }
+
+  if (liveHtml !== null) {
+    const css = entry.cssFiles
+      .map((file) => normalizeModuleCss(fs.readFileSync(file, 'utf8')))
+      .join('\n');
+    const result = await runAxe(modules.jsdom, modules['axe-core'], liveHtml, css);
+    report.axe = { rulesRun: result.rulesRun };
+    report.findings.push(...result.findings);
+  }
+
+  report.ok = true;
+  return report;
+}
+
+async function main() {
+  const componentDir = process.argv.slice(2).find((arg) => !arg.startsWith('--'));
+  if (!componentDir) {
+    console.log(
+      JSON.stringify({
+        ok: false,
+        usage: 'node <SKILL_ROOT>/scripts/scan-a11y-render.cjs <component-dir>',
+      }),
+    );
+    process.exit(2);
+  }
+  try {
+    console.log(JSON.stringify(await audit(path.resolve(componentDir))));
+  } catch (error) {
+    console.log(
+      JSON.stringify({
+        ok: false,
+        error: truncate(error && error.stack ? error.stack : error, 800),
+      }),
+    );
+    process.exit(2);
+  }
+}
+
+module.exports = {
+  PAGE_RULES,
+  LAYOUT_RULES,
+  normalizeModuleCss,
+  classifyRenderError,
+  checkPreviewPlaceholder,
+};
+
+if (require.main === module) main();