@atlaskit/ads-mcp 0.2.5 → 0.4.0

package/dist/esm/tools/analyze-accessibility/index.js

@@ -0,0 +1,476 @@
+import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
+import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+import _regeneratorRuntime from "@babel/runtime/regenerator";
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+import { AxePuppeteer } from '@axe-core/puppeteer';
+import axe from 'axe-core';
+import puppeteer from 'puppeteer';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+var inputSchema = z.object({
+  code: z.string().describe('React component code to analyze for accessibility'),
+  componentName: z.string().optional().describe('Name of the component being analyzed'),
+  context: z.string().optional().describe('Additional context about the component usage'),
+  includePatternAnalysis: z.boolean().optional().default(true).describe('Include pattern-based analysis in addition to axe-core')
+});
+export var listAnalyzeAccessibilityTool = {
+  name: 'analyze_accessibility',
+  description: "Analyze React component code for accessibility violations using axe-core and intelligently generate Atlassian Design System specific suggestions. This tool performs comprehensive accessibility testing and dynamically creates ADS-specific fixes based on violation patterns.\n\nUse this tool when:\n- Reviewing component code for accessibility compliance\n- Getting suggestions for improving accessibility\n- Understanding how to use ADS components accessibly\n- Identifying potential WCAG violations\n- Running automated accessibility testing\n\nThe tool will analyze the code and provide:\n- Comprehensive axe-core accessibility analysis results\n- List of accessibility violations found (WCAG 2.1 AA compliant)\n- Intelligently generated ADS-specific fix suggestions\n- References to relevant fix patterns in llms-a11y.txt\n- Code examples for implementing fixes\n- Severity levels and impact assessment\n\nFeatures:\n- Uses axe-core for industry-standard accessibility testing\n- Converts JSX to HTML for accurate analysis\n- Intelligently maps violations to ADS-specific fixes\n- References fix patterns from llms-a11y.txt documentation\n- Includes fallback pattern analysis if axe-core fails\n- Provides detailed violation descriptions and help text\n- Dynamically generates fix suggestions based on violation type",
+  annotations: {
+    title: 'Analyze Accessibility',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: zodToJsonSchema(inputSchema)
+};
+var urlInputSchema = z.object({
+  url: z.string().describe('The URL to analyze for accessibility (e.g. http://localhost:9000)'),
+  componentName: z.string().optional().describe('Name of the component being analyzed'),
+  context: z.string().optional().describe('Additional context about the component usage'),
+  selector: z.string().optional().describe('CSS selector to target a specific element for analysis (e.g. "#my-form", ".component-class")')
+});
+export var listAnalyzeLocalhostAccessibilityTool = {
+  name: 'analyze_localhost_accessibility',
+  description: "Analyze a live web page (e.g. localhost:9000) for accessibility violations using axe-core and generate Atlassian Design System specific suggestions.\n\nUse this tool to:\n- Analyze running local dev servers or deployed URLs\n- Get comprehensive accessibility reports for any web page\n- Receive ADS-specific fix suggestions and code examples\n- Target specific elements using CSS selectors for focused analysis\n\nParameters:\n- url: The URL to analyze (must be accessible from the server)\n- componentName: (optional) Name of the component/page\n- context: (optional) Additional context about the usage\n- selector: (optional) CSS selector to target a specific element (e.g. \"#my-form\", \".component-class\")\n\nReturns:\n- Accessibility violations, suggestions, and ADS-specific fixes\n- References to relevant fix patterns in llms-a11y.txt\n- Code examples for implementing fixes\n- Severity levels and impact assessment\n",
+  annotations: {
+    title: 'Analyze Localhost Accessibility',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  },
+  inputSchema: zodToJsonSchema(urlInputSchema)
+};
+
+// Common accessibility patterns to detect in code
+var accessibilityPatterns = [{
+  pattern: /<button[^>]*>(?!.*aria-label|.*>.*<\/button>)/g,
+  violation: 'Button without accessible text',
+  severity: 'error',
+  suggestion: 'Use the suggest-accessibility-fixes tool for ADS Button solutions. Describe the issue as "button missing label", "empty button", or "button needs text".'
+}, {
+  pattern: /<img[^>]*>(?!.*alt=)/g,
+  violation: 'Image without alt text',
+  severity: 'error',
+  suggestion: 'Use the suggest-accessibility-fixes tool for ADS Image solutions. Describe the issue as "image missing alt", "missing alt text", or "image accessibility".'
+}, {
+  pattern: /<div[^>]*onClick[^>]*>/g,
+  violation: 'Clickable div without accessibility',
+  severity: 'warning',
+  suggestion: 'Use the suggest-accessibility-fixes tool for ADS solutions. Describe the issue as "clickable div", "interactive div", or "div with click handler".'
+}, {
+  pattern: /color:\s*['"]#[0-9a-fA-F]{3,6}['"]/g,
+  violation: 'Hardcoded color values',
+  severity: 'warning',
+  suggestion: 'Use the suggest-accessibility-fixes tool for design token solutions. Describe the issue as "hardcoded colors", "hex colors", or "design tokens".'
+}, {
+  pattern: /<input[^>]*>(?!.*id=)/g,
+  violation: 'Input without associated label',
+  severity: 'error',
+  suggestion: 'Use the suggest-accessibility-fixes tool for ADS form solutions. Describe the issue as "input missing label", "form field without label", or "unlabeled input".'
+}, {
+  pattern: /<div[^>]*role="button"[^>]*>/g,
+  violation: 'Custom button without full accessibility',
+  severity: 'warning',
+  suggestion: 'Use the suggest-accessibility-fixes tool for ADS Button/Focusable solutions. Describe the issue as "custom button", "div with button role", or "interactive element".'
+}, {
+  pattern: /style=\{[^}]*color[^}]*\}/g,
+  violation: 'Inline color styles',
+  severity: 'warning',
+  suggestion: 'Use the suggest-accessibility-fixes tool for design token solutions. Describe the issue as "inline styles", "hardcoded colors", or "color tokens".'
+}];
+
+// ADS accessibility guidelines reference
+var adsGuidelines = {
+  buttons: {
+    title: 'Button Accessibility',
+    guidelines: ['Always provide accessible labels for buttons', 'Use Button component for standard interactions', 'Use Focusable component for custom interactive elements', 'Avoid disabled buttons with tooltips', 'Ensure focus indicators are visible']
+  },
+  forms: {
+    title: 'Form Accessibility',
+    guidelines: ['Use TextField component for consistent labeling', 'Associate labels with inputs using id and htmlFor', 'Provide clear error messages with aria-describedby', 'Use MessageWrapper for form validation announcements']
+  },
+  images: {
+    title: 'Image Accessibility',
+    guidelines: ['Use Image component with proper alt text', 'Keep alt text under 125 characters', 'Leave alt="" for decorative images', 'Describe the purpose, not just the content']
+  },
+  colors: {
+    title: 'Color and Contrast',
+    guidelines: ['Use design tokens for consistent contrast ratios', 'Never rely on color alone for information', 'Use color.text tokens for proper contrast', 'Test with high contrast mode']
+  }
+};
+
+// Helper function to map axe-core violations to ADS-specific fixes
+function mapAxeViolationsToADSFixes(violations) {
+  return violations.map(function (violation) {
+    var adsFix = generateADSFixForViolation(violation);
+    return _objectSpread(_objectSpread({}, violation), {}, {
+      type: adsFix.title,
+      // Use the specific fix key that matches fixes.ts
+      adsFix: adsFix,
+      severity: violation.impact === 'critical' || violation.impact === 'serious' ? 'error' : 'warning'
+    });
+  });
+}
+
+// Helper function to provide ADS-specific guidance for axe-core violations
+function generateADSFixForViolation(violation) {
+  var id = violation.id,
+    description = violation.description,
+    help = violation.help,
+    tags = violation.tags;
+
+  // Provide general guidance without trying to map to specific fixes.ts keys
+  var adsFix = "Use the suggest-accessibility-fixes tool to get specific ADS component solutions. Describe the issue using the violation details: \"".concat(help, "\" or in your own words (e.g., \"button has no text\", \"missing alt text\", \"form field needs label\").");
+  return {
+    title: help,
+    // Use axe-core's human-readable description
+    description: description,
+    adsFix: adsFix,
+    example: 'The suggest-accessibility-fixes tool provides detailed code examples and ADS component solutions',
+    violationId: id,
+    axeHelp: help,
+    tags: tags,
+    wcagTags: tags.filter(function (tag) {
+      return tag.startsWith('wcag');
+    }),
+    // Extract WCAG compliance info
+    reference: "https://atlassian.design/llms-a11y.txt",
+    recommendations: ['Use ADS components for better accessibility out of the box', 'Reference the suggest-accessibility-fixes tool for specific solutions', 'Test with keyboard navigation and screen readers', 'Use automated accessibility testing tools']
+  };
+}
+export var analyzeAccessibilityTool = /*#__PURE__*/function () {
+  var _ref = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(params) {
+    var code, componentName, context, _params$includePatter, includePatternAnalysis, violations, suggestions, axeResults, _axeResults$violation, _axeResults$passes, _axeResults$incomplet, results, adsViolations, relevantGuidelines, summary;
+    return _regeneratorRuntime.wrap(function _callee$(_context) {
+      while (1) switch (_context.prev = _context.next) {
+        case 0:
+          code = params.code, componentName = params.componentName, context = params.context, _params$includePatter = params.includePatternAnalysis, includePatternAnalysis = _params$includePatter === void 0 ? true : _params$includePatter;
+          violations = [];
+          suggestions = [];
+          axeResults = {};
+          _context.prev = 4;
+          _context.next = 7;
+          return axe.run({
+            fromFrames: ['iframe', 'html']
+          });
+        case 7:
+          results = _context.sent;
+          // Process axe-core results
+          if (results.violations && results.violations.length > 0) {
+            adsViolations = mapAxeViolationsToADSFixes(results.violations);
+            violations.push.apply(violations, _toConsumableArray(adsViolations));
+            axeResults.violations = results.violations;
+            axeResults.passes = results.passes;
+            axeResults.incomplete = results.incomplete;
+          }
+
+          // Include pattern-based analysis if requested
+          if (includePatternAnalysis) {
+            accessibilityPatterns.forEach(function (pattern) {
+              var matches = code.match(pattern.pattern);
+              if (matches) {
+                violations.push({
+                  type: pattern.violation,
+                  severity: pattern.severity,
+                  count: matches.length,
+                  suggestion: pattern.suggestion,
+                  adsFix: 'Use the suggest-accessibility-fixes tool for specific ADS component solutions',
+                  example: 'The suggest-accessibility-fixes tool provides detailed code examples',
+                  source: 'pattern-analysis'
+                });
+              }
+            });
+          }
+
+          // Generate ADS-specific suggestions
+          if (violations.length > 0) {
+            suggestions.push({
+              title: 'Accessibility Improvements Needed',
+              description: "Found ".concat(violations.length, " accessibility issues in your code."),
+              violations: violations,
+              nextSteps: ['Review each violation and apply the suggested fixes', 'Use ADS components instead of custom implementations', 'Test with screen readers and keyboard navigation', 'Run automated accessibility tests']
+            });
+          }
+
+          // Provide relevant ADS guidelines
+          relevantGuidelines = [];
+          if (code.includes('button') || code.includes('onClick')) {
+            relevantGuidelines.push(adsGuidelines.buttons);
+          }
+          if (code.includes('input') || code.includes('form')) {
+            relevantGuidelines.push(adsGuidelines.forms);
+          }
+          if (code.includes('img') || code.includes('image')) {
+            relevantGuidelines.push(adsGuidelines.images);
+          }
+          if (code.includes('color') || code.includes('style')) {
+            relevantGuidelines.push(adsGuidelines.colors);
+          }
+
+          // Generate summary
+          summary = {
+            componentName: componentName || 'Unknown component',
+            totalViolations: violations.length,
+            severityBreakdown: {
+              error: violations.filter(function (v) {
+                return v.severity === 'error';
+              }).length,
+              warning: violations.filter(function (v) {
+                return v.severity === 'warning';
+              }).length
+            },
+            context: context || 'No additional context provided',
+            axeResults: {
+              violations: ((_axeResults$violation = axeResults.violations) === null || _axeResults$violation === void 0 ? void 0 : _axeResults$violation.length) || 0,
+              passes: ((_axeResults$passes = axeResults.passes) === null || _axeResults$passes === void 0 ? void 0 : _axeResults$passes.length) || 0,
+              incomplete: ((_axeResults$incomplet = axeResults.incomplete) === null || _axeResults$incomplet === void 0 ? void 0 : _axeResults$incomplet.length) || 0
+            }
+          };
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                summary: summary,
+                violations: violations,
+                suggestions: suggestions,
+                relevantGuidelines: relevantGuidelines,
+                axeResults: axeResults,
+                recommendations: ['Use ADS components for better accessibility out of the box', 'Reference https://atlassian.design/llms-a11y.txt for detailed guidelines', 'Test with keyboard navigation and screen readers', 'Use automated accessibility testing tools']
+              }, null, 2)
+            }]
+          });
+        case 20:
+          _context.prev = 20;
+          _context.t0 = _context["catch"](4);
+          // Fallback to pattern-based analysis if axe-core fails
+          // console.warn('Axe-core analysis failed, falling back to pattern analysis:', error);
+
+          // Run pattern analysis as fallback
+          accessibilityPatterns.forEach(function (pattern) {
+            var matches = code.match(pattern.pattern);
+            if (matches) {
+              violations.push({
+                type: pattern.violation,
+                severity: pattern.severity,
+                count: matches.length,
+                suggestion: pattern.suggestion,
+                adsFix: 'Use the suggest-accessibility-fixes tool for specific ADS component solutions',
+                example: 'The suggest-accessibility-fixes tool provides detailed code examples',
+                source: 'pattern-analysis-fallback'
+              });
+            }
+          });
+          return _context.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                summary: {
+                  componentName: componentName || 'Unknown component',
+                  totalViolations: violations.length,
+                  severityBreakdown: {
+                    error: violations.filter(function (v) {
+                      return v.severity === 'error';
+                    }).length,
+                    warning: violations.filter(function (v) {
+                      return v.severity === 'warning';
+                    }).length
+                  },
+                  context: context || 'No additional context provided',
+                  note: 'Analysis completed using pattern matching (axe-core analysis failed)'
+                },
+                violations: violations,
+                suggestions: violations.length > 0 ? [{
+                  title: 'Accessibility Improvements Needed',
+                  description: "Found ".concat(violations.length, " accessibility issues in your code."),
+                  violations: violations,
+                  nextSteps: ['Review each violation and apply the suggested fixes', 'Use ADS components instead of custom implementations', 'Test with screen readers and keyboard navigation', 'Run automated accessibility tests']
+                }] : [],
+                error: 'Axe-core analysis failed, used pattern-based analysis as fallback',
+                recommendations: ['Use ADS components for better accessibility out of the box', 'Reference https://atlassian.design/llms-a11y.txt for detailed guidelines', 'Test with keyboard navigation and screen readers', 'Use automated accessibility testing tools']
+              }, null, 2)
+            }]
+          });
+        case 24:
+        case "end":
+          return _context.stop();
+      }
+    }, _callee, null, [[4, 20]]);
+  }));
+  return function analyzeAccessibilityTool(_x) {
+    return _ref.apply(this, arguments);
+  };
+}();
+export var analyzeLocalhostAccessibilityTool = /*#__PURE__*/function () {
+  var _ref2 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee2(params) {
+    var url, componentName, context, selector, violations, suggestions, axeResults, browser, page, _axeResults$violation2, _axeResults$passes2, _axeResults$incomplet2, elementExists, availableElements, axePuppeteer, results, adsViolations, relevantGuidelines, summary;
+    return _regeneratorRuntime.wrap(function _callee2$(_context2) {
+      while (1) switch (_context2.prev = _context2.next) {
+        case 0:
+          url = params.url, componentName = params.componentName, context = params.context, selector = params.selector;
+          violations = [];
+          suggestions = [];
+          axeResults = {};
+          _context2.next = 6;
+          return puppeteer.launch();
+        case 6:
+          browser = _context2.sent;
+          _context2.next = 9;
+          return browser.newPage();
+        case 9:
+          page = _context2.sent;
+          _context2.prev = 10;
+          _context2.next = 13;
+          return page.goto(url, {
+            waitUntil: 'networkidle0'
+          });
+        case 13:
+          if (!selector) {
+            _context2.next = 22;
+            break;
+          }
+          _context2.next = 16;
+          return page.$(selector);
+        case 16:
+          elementExists = _context2.sent;
+          if (elementExists) {
+            _context2.next = 22;
+            break;
+          }
+          _context2.next = 20;
+          return page.evaluate(function () {
+            var elements = Array.from(document.querySelectorAll('[id]'));
+            return elements.map(function (el) {
+              return "#".concat(el.id);
+            });
+          });
+        case 20:
+          availableElements = _context2.sent;
+          throw new Error("Element with selector \"".concat(selector, "\" not found on the page after waiting. Available elements: ").concat(availableElements.join(', ')));
+        case 22:
+          // Run axe-core accessibility analysis
+          axePuppeteer = new AxePuppeteer(page); // If selector is provided, analyze only that element
+          if (selector) {
+            axePuppeteer.include(selector);
+          }
+          _context2.next = 26;
+          return axePuppeteer.analyze();
+        case 26:
+          results = _context2.sent;
+          if (results.violations && results.violations.length > 0) {
+            adsViolations = mapAxeViolationsToADSFixes(results.violations);
+            violations.push.apply(violations, _toConsumableArray(adsViolations));
+            axeResults.violations = results.violations;
+            axeResults.passes = results.passes;
+            axeResults.incomplete = results.incomplete;
+          }
+
+          // Generate ADS-specific suggestions
+          if (violations.length > 0) {
+            suggestions.push({
+              title: 'Accessibility Improvements Needed',
+              description: "Found ".concat(violations.length, " accessibility issues in your code."),
+              violations: violations,
+              nextSteps: ['Review each violation and apply the suggested fixes', 'Use ADS components instead of custom implementations', 'Test with screen readers and keyboard navigation', 'Run automated accessibility tests']
+            });
+          }
+
+          // Provide relevant ADS guidelines
+          relevantGuidelines = [];
+          if (url.includes('button') || url.includes('onClick')) {
+            relevantGuidelines.push(adsGuidelines.buttons);
+          }
+          if (url.includes('input') || url.includes('form')) {
+            relevantGuidelines.push(adsGuidelines.forms);
+          }
+          if (url.includes('img') || url.includes('image')) {
+            relevantGuidelines.push(adsGuidelines.images);
+          }
+          if (url.includes('color') || url.includes('style')) {
+            relevantGuidelines.push(adsGuidelines.colors);
+          }
+
+          // Generate summary
+          summary = {
+            url: url,
+            selector: selector || 'Entire page analyzed',
+            componentName: componentName || 'Unknown component',
+            totalViolations: violations.length,
+            severityBreakdown: {
+              error: violations.filter(function (v) {
+                return v.severity === 'error';
+              }).length,
+              warning: violations.filter(function (v) {
+                return v.severity === 'warning';
+              }).length
+            },
+            context: context || 'No additional context provided',
+            axeResults: {
+              violations: ((_axeResults$violation2 = axeResults.violations) === null || _axeResults$violation2 === void 0 ? void 0 : _axeResults$violation2.length) || 0,
+              passes: ((_axeResults$passes2 = axeResults.passes) === null || _axeResults$passes2 === void 0 ? void 0 : _axeResults$passes2.length) || 0,
+              incomplete: ((_axeResults$incomplet2 = axeResults.incomplete) === null || _axeResults$incomplet2 === void 0 ? void 0 : _axeResults$incomplet2.length) || 0
+            }
+          };
+          _context2.next = 37;
+          return browser.close();
+        case 37:
+          return _context2.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                summary: summary,
+                violations: violations,
+                suggestions: suggestions,
+                relevantGuidelines: relevantGuidelines,
+                axeResults: axeResults,
+                recommendations: ['Use ADS components for better accessibility out of the box', 'Reference https://atlassian.design/llms-a11y.txt for detailed guidelines', 'Test with keyboard navigation and screen readers', 'Use automated accessibility testing tools']
+              }, null, 2)
+            }]
+          });
+        case 40:
+          _context2.prev = 40;
+          _context2.t0 = _context2["catch"](10);
+          _context2.next = 44;
+          return browser.close();
+        case 44:
+          return _context2.abrupt("return", {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                summary: {
+                  url: url,
+                  selector: selector || 'Entire page analyzed',
+                  componentName: componentName || 'Unknown component',
+                  totalViolations: violations.length,
+                  severityBreakdown: {
+                    error: violations.filter(function (v) {
+                      return v.severity === 'error';
+                    }).length,
+                    warning: violations.filter(function (v) {
+                      return v.severity === 'warning';
+                    }).length
+                  },
+                  context: context || 'No additional context provided',
+                  note: 'Analysis failed to run on the provided URL'
+                },
+                violations: violations,
+                suggestions: [],
+                error: String(_context2.t0),
+                recommendations: ['Use ADS components for better accessibility out of the box', 'Reference https://atlassian.design/llms-a11y.txt for detailed guidelines', 'Test with keyboard navigation and screen readers', 'Use automated accessibility testing tools']
+              }, null, 2)
+            }]
+          });
+        case 45:
+        case "end":
+          return _context2.stop();
+      }
+    }, _callee2, null, [[10, 40]]);
+  }));
+  return function analyzeLocalhostAccessibilityTool(_x2) {
+    return _ref2.apply(this, arguments);
+  };
+}();