@lifeonlars/prime-yggdrasil 0.2.6 → 0.4.0

package/cli/rules/accessibility/missing-form-labels.js

@@ -0,0 +1,238 @@
+/**
+ * Accessibility Rule: Missing Form Labels
+ *
+ * Enforces proper label association for form inputs.
+ * WCAG 2.1 Level AA - Guideline 3.3 Input Assistance
+ *
+ * Phase 6 - Accessibility Agent
+ */
+
+export default {
+  name: 'accessibility/missing-form-labels',
+  description: 'Enforce proper labels on form inputs with htmlFor/id association',
+  category: 'accessibility',
+  severity: 'error',
+  documentation: 'https://github.com/lifeonlars/prime-yggdrasil/blob/master/.ai/agents/accessibility.md#33-input-assistance',
+
+  formComponents: [
+    'InputText',
+    'InputNumber',
+    'InputTextarea',
+    'Password',
+    'Dropdown',
+    'MultiSelect',
+    'Calendar',
+    'Checkbox',
+    'RadioButton',
+    'InputSwitch',
+    'Slider',
+    'Rating',
+    'ColorPicker',
+    'Chips',
+    'AutoComplete',
+  ],
+
+  validate(fileContent, filePath) {
+    const violations = [];
+
+    // Skip non-React/TSX files
+    if (!filePath.match(/\.(jsx|tsx|js|ts)$/)) {
+      return violations;
+    }
+
+    // Extract all form component instances with their IDs
+    const componentInstances = this.extractComponentInstances(fileContent);
+
+    // Extract all label elements with their htmlFor attributes
+    const labels = this.extractLabels(fileContent);
+
+    // Check each form component
+    componentInstances.forEach(instance => {
+      const line = this.getLineNumber(fileContent, instance.index);
+
+      // Check 1: Component has id attribute
+      if (!instance.id) {
+        violations.push({
+          line,
+          column: 1,
+          message: `${instance.component} missing id attribute. Required for label association.`,
+          severity: 'error',
+          rule: this.name,
+          suggestion: `Add id="${this.generateId(instance.component)}"`,
+        });
+        return;
+      }
+
+      // Check 2: Label exists with matching htmlFor
+      const hasLabel = labels.some(label => label.htmlFor === instance.id);
+      const hasAriaLabel = instance.tag.includes('aria-label=') || instance.tag.includes('ariaLabel=');
+      const hasPlaceholder = instance.tag.includes('placeholder=');
+
+      if (!hasLabel && !hasAriaLabel) {
+        violations.push({
+          line,
+          column: 1,
+          message: `${instance.component} with id="${instance.id}" missing associated label. Add <label htmlFor="${instance.id}">`,
+          severity: 'error',
+          rule: this.name,
+          suggestion: `<label htmlFor="${instance.id}">Label Text</label>`,
+        });
+      }
+
+      // Check 3: Placeholder should not replace label
+      if (!hasLabel && !hasAriaLabel && hasPlaceholder) {
+        violations.push({
+          line,
+          column: 1,
+          message: `${instance.component} uses placeholder but missing label. Placeholder is not a substitute for labels.`,
+          severity: 'error',
+          rule: this.name,
+          suggestion: 'Add proper <label> element in addition to placeholder.',
+        });
+      }
+    });
+
+    // Check for labels without matching inputs
+    labels.forEach(label => {
+      if (!label.htmlFor) {
+        const line = this.getLineNumber(fileContent, label.index);
+
+        violations.push({
+          line,
+          column: 1,
+          message: 'Label missing htmlFor attribute. Required for screen reader association.',
+          severity: 'warning',
+          rule: this.name,
+          suggestion: 'Add htmlFor="input-id" matching the input\'s id',
+        });
+        return;
+      }
+
+      const hasMatchingInput = componentInstances.some(instance => instance.id === label.htmlFor);
+
+      if (!hasMatchingInput) {
+        const line = this.getLineNumber(fileContent, label.index);
+
+        violations.push({
+          line,
+          column: 1,
+          message: `Label htmlFor="${label.htmlFor}" has no matching input with id="${label.htmlFor}".`,
+          severity: 'warning',
+          rule: this.name,
+          suggestion: `Add id="${label.htmlFor}" to the associated input`,
+        });
+      }
+    });
+
+    // Check for required field indicators
+    const requiredInputs = componentInstances.filter(instance =>
+      instance.tag.includes('required') || instance.tag.includes('aria-required')
+    );
+
+    requiredInputs.forEach(instance => {
+      const line = this.getLineNumber(fileContent, instance.index);
+      const label = labels.find(l => l.htmlFor === instance.id);
+
+      if (label) {
+        const labelContent = fileContent.substring(label.index, label.index + 200);
+
+        // Check if label indicates required status (*, required text, etc.)
+        const hasRequiredIndicator = /(\*|required|Required)/i.test(labelContent);
+
+        if (!hasRequiredIndicator) {
+          violations.push({
+            line,
+            column: 1,
+            message: `Required field "${instance.id}" should have visual indicator in label (e.g., asterisk).`,
+            severity: 'warning',
+            rule: this.name,
+            suggestion: '<span style={{ color: "var(--text-context-danger)" }}>*</span>',
+          });
+        }
+      }
+    });
+
+    return violations;
+  },
+
+  extractComponentInstances(fileContent) {
+    const instances = [];
+
+    this.formComponents.forEach(component => {
+      const regex = new RegExp(`<${component}([^>]*)>`, 'g');
+      let match;
+
+      while ((match = regex.exec(fileContent)) !== null) {
+        const tag = match[1];
+        const idMatch = tag.match(/id=["']([^"']+)["']/);
+
+        instances.push({
+          component,
+          tag,
+          id: idMatch ? idMatch[1] : null,
+          index: match.index,
+        });
+      }
+    });
+
+    return instances;
+  },
+
+  extractLabels(fileContent) {
+    const labels = [];
+    const labelRegex = /<label([^>]*)>/g;
+    let match;
+
+    while ((match = labelRegex.exec(fileContent)) !== null) {
+      const tag = match[1];
+      const htmlForMatch = tag.match(/htmlFor=["']([^"']+)["']/);
+
+      labels.push({
+        tag,
+        htmlFor: htmlForMatch ? htmlForMatch[1] : null,
+        index: match.index,
+      });
+    }
+
+    return labels;
+  },
+
+  generateId(component) {
+    const base = component.toLowerCase().replace('input', '');
+    return `${base}-${Date.now().toString(36)}`;
+  },
+
+  getLineNumber(content, index) {
+    return content.substring(0, index).split('\n').length;
+  },
+
+  autofix(fileContent, violation) {
+    if (violation.message.includes('missing id attribute')) {
+      const componentMatch = violation.message.match(/^(\w+) missing/);
+      if (!componentMatch) return { fixed: false };
+
+      const component = componentMatch[1];
+      const componentRegex = new RegExp(`(<${component}[^>]*)(>)`, 'g');
+      const match = componentRegex.exec(fileContent);
+
+      if (match && !match[1].includes(' id=')) {
+        const generatedId = this.generateId(component);
+        const fixedContent = fileContent.replace(
+          match[0],
+          `${match[1]} id="${generatedId}"${match[2]}`
+        );
+
+        return {
+          fixed: true,
+          content: fixedContent,
+          message: `Added id="${generatedId}" (add corresponding <label htmlFor="${generatedId}">)`,
+        };
+      }
+    }
+
+    return {
+      fixed: false,
+      message: 'Manual fix required. Add proper label/id association.',
+    };
+  },
+};

package/cli/rules/interaction-patterns/focus-management.js

@@ -0,0 +1,187 @@
+/**
+ * Interaction Patterns Rule: Focus Management
+ *
+ * Validates proper focus management in Dialogs, Modals, and form flows.
+ * Ensures keyboard navigation works correctly and focus is trapped/returned appropriately.
+ *
+ * Phase 6 - Interaction Patterns Agent
+ */
+
+export default {
+  name: 'interaction-patterns/focus-management',
+  description: 'Validate Dialog/Modal focus patterns and keyboard navigation',
+  category: 'interaction-patterns',
+  severity: 'warning',
+  documentation: 'https://github.com/lifeonlars/prime-yggdrasil/blob/master/.ai/agents/interaction-patterns.md#5-focus-management',
+
+  validate(fileContent, filePath) {
+    const violations = [];
+
+    // Skip non-React/TSX files
+    if (!filePath.match(/\.(jsx|tsx|js|ts)$/)) {
+      return violations;
+    }
+
+    // Pattern 1: Check Dialog components for focus management
+    const dialogRegex = /<Dialog[^>]*>/g;
+    let match;
+
+    while ((match = dialogRegex.exec(fileContent)) !== null) {
+      const dialogStart = match.index;
+      const dialogEnd = fileContent.indexOf('</Dialog>', dialogStart);
+
+      if (dialogEnd === -1) continue;
+
+      const dialogContent = fileContent.substring(dialogStart, dialogEnd);
+      const line = this.getLineNumber(fileContent, dialogStart);
+
+      // Check 1: Dialog should have modal prop (focus trap)
+      if (!dialogContent.includes('modal')) {
+        violations.push({
+          line,
+          column: 1,
+          message: 'Dialog missing modal prop. Add modal={true} to trap focus within dialog.',
+          severity: 'warning',
+          rule: this.name,
+          suggestion: '<Dialog visible={visible} onHide={onHide} modal>',
+        });
+      }
+
+      // Check 2: First interactive element should have autoFocus
+      const hasAutoFocus = /autoFocus/.test(dialogContent);
+      const hasInteractiveElement = /(<InputText|<Button|<Dropdown|<Calendar|<Checkbox)/.test(dialogContent);
+
+      if (hasInteractiveElement && !hasAutoFocus) {
+        violations.push({
+          line,
+          column: 1,
+          message: 'Dialog first interactive element should have autoFocus for keyboard navigation.',
+          severity: 'info',
+          rule: this.name,
+          suggestion: '<InputText autoFocus /> // First field in dialog',
+        });
+      }
+
+      // Check 3: Dialog should have onHide handler (ESC key support)
+      if (!dialogContent.includes('onHide')) {
+        violations.push({
+          line,
+          column: 1,
+          message: 'Dialog missing onHide handler. Required for ESC key support.',
+          severity: 'error',
+          rule: this.name,
+          suggestion: '<Dialog visible={visible} onHide={() => setVisible(false)}>',
+        });
+      }
+    }
+
+    // Pattern 2: Check for interactive divs without keyboard handlers
+    const interactiveDivRegex = /<div[^>]*onClick[^>]*>/g;
+
+    while ((match = interactiveDivRegex.exec(fileContent)) !== null) {
+      const divTag = match[0];
+      const line = this.getLineNumber(fileContent, match.index);
+
+      // Check if div has keyboard handlers
+      const hasKeyboard = divTag.includes('onKeyDown') || divTag.includes('onKeyPress');
+      const hasRole = divTag.includes('role="button"') || divTag.includes('role=\\"button\\"');
+      const hasTabIndex = divTag.includes('tabIndex');
+
+      if (!hasKeyboard || !hasRole || !hasTabIndex) {
+        violations.push({
+          line,
+          column: 1,
+          message: 'Interactive div must have role="button", tabIndex, and keyboard handlers (onKeyDown).',
+          severity: 'error',
+          rule: this.name,
+          suggestion: this.getKeyboardHandlerSuggestion(),
+        });
+      }
+    }
+
+    // Pattern 3: Check form fields for logical tab order
+    const formRegex = /<form[^>]*>/g;
+
+    while ((match = formRegex.exec(fileContent)) !== null) {
+      const formStart = match.index;
+      const formEnd = fileContent.indexOf('</form>', formStart);
+
+      if (formEnd === -1) continue;
+
+      const formContent = fileContent.substring(formStart, formEnd);
+      const line = this.getLineNumber(fileContent, formStart);
+
+      // Check for explicit tabIndex that might break natural order
+      const explicitTabIndex = /tabIndex=\{?(\d+)\}?/.exec(formContent);
+
+      if (explicitTabIndex && parseInt(explicitTabIndex[1]) > 0) {
+        violations.push({
+          line: line + this.getLineNumber(formContent, explicitTabIndex.index),
+          column: 1,
+          message: 'Avoid positive tabIndex values. Use natural DOM order or tabIndex={0} for custom elements.',
+          severity: 'warning',
+          rule: this.name,
+          suggestion: 'Remove tabIndex or use tabIndex={0} for same-level focus order.',
+        });
+      }
+    }
+
+    // Pattern 4: Check for custom focus styles
+    const hasFocusStyles = /:focus/.test(fileContent) || /focus-visible/.test(fileContent);
+    const hasInteractiveComponents = /<(Button|InputText|Dropdown|Calendar)/.test(fileContent);
+
+    if (hasInteractiveComponents && fileContent.includes('outline: none') && !hasFocusStyles) {
+      const line = this.getLineNumber(fileContent, fileContent.indexOf('outline: none'));
+
+      violations.push({
+        line,
+        column: 1,
+        message: 'Removing outline without custom focus styles breaks keyboard navigation visibility.',
+        severity: 'error',
+        rule: this.name,
+        suggestion: 'Replace with: boxShadow: "0 0 0 2px var(--border-state-focus)"',
+      });
+    }
+
+    return violations;
+  },
+
+  getKeyboardHandlerSuggestion() {
+    return `
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={e => (e.key === 'Enter' || e.key === ' ') && handleClick()}
+>
+  Click me
+</div>`;
+  },
+
+  getLineNumber(content, index) {
+    return content.substring(0, index).split('\n').length;
+  },
+
+  autofix(fileContent, violation) {
+    if (violation.message.includes('Dialog missing modal prop')) {
+      const dialogRegex = /<Dialog([^>]*)>/;
+      const match = dialogRegex.exec(fileContent);
+
+      if (match) {
+        const dialogTag = match[0];
+        const fixedTag = dialogTag.replace('<Dialog', '<Dialog modal');
+
+        return {
+          fixed: true,
+          content: fileContent.replace(dialogTag, fixedTag),
+          message: 'Added modal prop to Dialog',
+        };
+      }
+    }
+
+    return {
+      fixed: false,
+      message: 'Manual fix required. See suggestion in violation message.',
+    };
+  },
+};

package/cli/rules/interaction-patterns/generic-copy.js

@@ -0,0 +1,190 @@
+/**
+ * Interaction Patterns Rule: Generic Copy
+ *
+ * Enforces specific, action-oriented button labels and copy instead of generic terms.
+ * Aligns with AESTHETICS.md: "Be specific, be concise, be functional"
+ *
+ * Phase 6 - Interaction Patterns Agent
+ */
+
+export default {
+  name: 'interaction-patterns/generic-copy',
+  description: 'Enforce specific button labels over generic ones ("Save Changes" not "Submit")',
+  category: 'interaction-patterns',
+  severity: 'warning',
+  documentation: 'https://github.com/lifeonlars/prime-yggdrasil/blob/master/.ai/agents/interaction-patterns.md#7-copy-tone--content',
+
+  // Generic terms to avoid
+  genericTerms: {
+    // Button labels
+    'Submit': 'Use specific action like "Save Changes", "Create Account", "Send Message"',
+    'OK': 'Use specific action like "Confirm Delete", "Apply Settings", "Close"',
+    'Cancel': 'OK in most cases, but consider "Keep Editing", "Go Back" for clarity',
+    'Continue': 'Use specific action like "Next: Payment", "Proceed to Checkout"',
+    'Done': 'Use specific action like "Finish Setup", "Complete"',
+    'Click here': 'Use descriptive link text like "View documentation", "Learn more about tokens"',
+    'Click': 'Avoid instructional copy - buttons are self-evident',
+
+    // Messages
+    'Success!': 'Be specific: "Settings saved", "User created", "Email sent"',
+    'Error': 'Explain what failed: "Unable to save. Try again.", "Connection failed."',
+    'Warning': 'Be specific about the warning: "Unsaved changes will be lost"',
+    'Oops!': 'Avoid casual tone - be clear and pragmatic',
+    'Something went wrong': 'Explain the issue: "Unable to connect to server", "Invalid format"',
+    'Loading...': 'Be specific: "Loading users...", "Saving changes...", "Processing..."',
+  },
+
+  validate(fileContent, filePath) {
+    const violations = [];
+
+    // Skip non-React/TSX files
+    if (!filePath.match(/\.(jsx|tsx|js|ts)$/)) {
+      return violations;
+    }
+
+    // Pattern 1: Check Button component labels
+    const buttonLabelRegex = /<Button[^>]*label=["']([^"']+)["']/g;
+    let match;
+
+    while ((match = buttonLabelRegex.exec(fileContent)) !== null) {
+      const label = match[1];
+      const line = this.getLineNumber(fileContent, match.index);
+
+      if (this.genericTerms[label]) {
+        violations.push({
+          line,
+          column: 1,
+          message: `Generic button label "${label}". ${this.genericTerms[label]}`,
+          severity: 'warning',
+          rule: this.name,
+          suggestion: this.getSuggestion(label),
+        });
+      }
+    }
+
+    // Pattern 2: Check button element text content
+    const buttonTextRegex = /<button[^>]*>([^<]+)<\/button>/gi;
+
+    while ((match = buttonTextRegex.exec(fileContent)) !== null) {
+      const text = match[1].trim();
+      const line = this.getLineNumber(fileContent, match.index);
+
+      if (this.genericTerms[text]) {
+        violations.push({
+          line,
+          column: 1,
+          message: `Generic button text "${text}". ${this.genericTerms[text]}`,
+          severity: 'warning',
+          rule: this.name,
+          suggestion: this.getSuggestion(text),
+        });
+      }
+    }
+
+    // Pattern 3: Check Message/Toast content
+    const messagePatterns = [
+      /severity=["']success["'][^>]*text=["']([^"']+)["']/g,
+      /severity=["']error["'][^>]*text=["']([^"']+)["']/g,
+      /severity=["']warn["'][^>]*text=["']([^"']+)["']/g,
+      /summary=["']([^"']+)["']/g,
+    ];
+
+    messagePatterns.forEach(pattern => {
+      while ((match = pattern.exec(fileContent)) !== null) {
+        const text = match[1];
+        const line = this.getLineNumber(fileContent, match.index);
+
+        if (this.genericTerms[text]) {
+          violations.push({
+            line,
+            column: 1,
+            message: `Generic message "${text}". ${this.genericTerms[text]}`,
+            severity: 'warning',
+            rule: this.name,
+            suggestion: this.getSuggestion(text),
+          });
+        }
+
+        // Check for emoji/fluffy language
+        if (/[🎉😅❤️👍✨]/.test(text)) {
+          violations.push({
+            line,
+            column: 1,
+            message: `Avoid emoji in UI copy. Keep tone clear and pragmatic.`,
+            severity: 'warning',
+            rule: this.name,
+            suggestion: `Remove emoji from: "${text}"`,
+          });
+        }
+
+        // Check for casual/marketing language
+        const casualPhrases = [
+          /let's/i,
+          /awesome/i,
+          /amazing/i,
+          /yay/i,
+          /congrats/i,
+          /you're all set/i,
+        ];
+
+        casualPhrases.forEach(phrase => {
+          if (phrase.test(text)) {
+            violations.push({
+              line,
+              column: 1,
+              message: `Avoid casual/marketing language in UI copy: "${text}"`,
+              severity: 'warning',
+              rule: this.name,
+              suggestion: 'Use clear, functional copy. See docs/AESTHETICS.md for examples.',
+            });
+          }
+        });
+      }
+    });
+
+    // Pattern 4: Check link text
+    const linkTextRegex = /<a[^>]*>([^<]+)<\/a>/gi;
+
+    while ((match = linkTextRegex.exec(fileContent)) !== null) {
+      const text = match[1].trim();
+      const line = this.getLineNumber(fileContent, match.index);
+
+      if (this.genericTerms[text]) {
+        violations.push({
+          line,
+          column: 1,
+          message: `Generic link text "${text}". ${this.genericTerms[text]}`,
+          severity: 'warning',
+          rule: this.name,
+          suggestion: 'Use descriptive link text that explains the destination.',
+        });
+      }
+    }
+
+    return violations;
+  },
+
+  getSuggestion(genericTerm) {
+    const examples = {
+      'Submit': 'Examples: "Save Changes", "Create Project", "Send Email"',
+      'OK': 'Examples: "Confirm", "Apply", "Close Dialog"',
+      'Continue': 'Examples: "Next: Payment", "Proceed to Review"',
+      'Success!': 'Examples: "Settings saved", "User created successfully"',
+      'Error': 'Examples: "Unable to save. Try again.", "Invalid email format."',
+    };
+
+    return examples[genericTerm] || 'Use specific, action-oriented copy.';
+  },
+
+  getLineNumber(content, index) {
+    return content.substring(0, index).split('\n').length;
+  },
+
+  autofix(fileContent, violation) {
+    // No automatic fix for copy - requires human judgment
+    return {
+      fixed: false,
+      message: 'Manual fix required. Replace generic copy with specific, action-oriented text.',
+    };
+  },
+};

package/cli/rules/interaction-patterns/index.js

@@ -0,0 +1,17 @@
+/**
+ * Interaction Patterns Rules
+ *
+ * Phase 6 - Behavioral consistency enforcement
+ *
+ * All rules enforce patterns from .ai/agents/interaction-patterns.md
+ */
+
+import stateCompleteness from './state-completeness.js';
+import genericCopy from './generic-copy.js';
+import focusManagement from './focus-management.js';
+
+export default {
+  'interaction-patterns/state-completeness': stateCompleteness,
+  'interaction-patterns/generic-copy': genericCopy,
+  'interaction-patterns/focus-management': focusManagement,
+};