semantica11y 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Semantica11y Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+<img src="./Semantically-logo.png" alt="Semantica11y logo" width="500" height="350">
+
+# Semantica11y
+
+A JavaScript analysis engine for checking webpages (HTML) for non-semantic HTML elements with ARIA using intelligent suggestions for semantic improvements. 
+
+## 🎯 Purpose
+
+Using semantic and native HTML elements is the foundation to building an accessible webpage. Semantica11y is here to help ensure that when you build your web applications, it is build semantically first, for better accessibility and long term code sustainability!
+
+## 📦 Installation
+
+```bash
+npm install semantica11y
+```
+
+## 🚀 Quick Start
+
+```javascript
+import { Analyzer } from 'semantica11y';
+
+const analyzer = new Analyzer();
+
+const html = `
+  <html>
+    <body>
+      <div role="banner">Header</div>
+      <img src="logo.png" />
+      <form>
+        <input type="text" id="name" />
+      </form>
+    </body>
+  </html>
+`;
+
+const results = await analyzer.analyzeHTML(html);
+console.log(analyzer.formatResults(results));
+```
+
+## 📖 Usage
+
+### Basic Analysis
+
+```javascript
+import { Analyzer } from 'semantica11y';
+
+const analyzer = new Analyzer();
+
+// Analyze HTML string
+const results = await analyzer.analyzeHTML(htmlString, 'https://example.com');
+
+// Get formatted output
+console.log(analyzer.formatResults(results));
+```
+
+### Reports
+
+```javascript
+import { Analyzer, exportTextReport, formatConsoleReport } from 'semantica11y';
+
+const analyzer = new Analyzer();
+const results = await analyzer.analyzeHTML(html);
+
+console.log(formatConsoleReport(results));
+await exportTextReport(results, './semantica11y-report.txt');
+```
+
+### Custom Rules
+
+```javascript
+const customRules = [
+  {
+    id: 'custom-rule',
+    name: 'My Custom Rule',
+    enabled: true,
+    description: 'Custom accessibility check',
+    check(document) {
+      const issues = [];
+      // Your custom check logic
+      return issues;
+    }
+  }
+];
+
+const analyzer = new Analyzer({ rules: customRules });
+```
+
+## 📋 Default Rules
+
+Semantica11y ships with 11 default rules that check semantic HTML, ARIA usage, headings, landmarks, forms, images, disclosure controls, modal dialogs, and native label conflicts.
+
+For the full rule-by-rule reference, see [src/engine/rules/README.md](./src/engine/rules/README.md).
+
+## 🧪 Testing
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+Run tests in watch mode:
+
+```bash
+npm run test:watch
+```
+
+Run the Playwright example against `https://example.com`:
+
+```bash
+node examples/basic.js
+```
+
+Analyze a different page:
+
+```bash
+node examples/basic.js https://www.statefarm.com
+```
+
+## 📦 Build Package
+
+Create a clean package directory:
+
+```bash
+npm run build
+```
+
+Create a tarball from the build output:
+
+```bash
+npm pack ./dist
+```
+
+## 🏗️ Project Structure
+
+```
+semantica11y/
+├── src/
+│   ├── index.js           # Main export
+│   ├── analyzer.js        # Core analyzer class
+│   └── engine/
+│       ├── index.js       # RuleEngine class
+│       ├── definitions.js # Default rule registry
+│       ├── reporter/      # Report formatting and exporting
+│       ├── rules/         # Individual rule definitions
+│       ├── semantic-role-mappings.js
+│       └── utils.js
+├── examples/
+│   └── basic.js          # Usage example
+├── test/
+│   ├── analyzer.test.js  # Analyzer tests
+│   └── rules.test.js     # RuleEngine tests
+├── package.json
+└── README.md
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+MIT
+
+## 🔗 Resources
+
+- [WCAG Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
+- [Semantic HTML](https://developer.mozilla.org/en-US/docs/Glossary/Semantic_HTML)
+- [Web Accessibility](https://www.w3.org/WAI/)
+
+## 📞 Support
+
+For issues, questions, or suggestions, please create an issue in the repository.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "semantica11y",
+  "version": "1.0.0",
+  "description": "A JavaScript engine to check webpages for ARIA and non-semantic HTML elements with suggestions for improvements",
+  "type": "module",
+  "main": "./src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "Semantically-logo.png"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./analyzer": "./src/analyzer.js",
+    "./rules": "./src/engine/index.js",
+    "./engine": "./src/engine/index.js",
+    "./reporter": "./src/engine/reporter/index.js"
+  },
+  "scripts": {
+    "build": "node scripts/build-package.js",
+    "pack:dist": "npm run build && npm pack ./dist",
+    "test": "node --test test/**/*.test.js",
+    "test:watch": "node --test test/**/*.test.js --watch",
+    "lint": "echo 'Add eslint configuration'",
+    "example": "node examples/basic.js"
+  },
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "ARIA",
+    "semantic",
+    "HTML",
+    "web-standards",
+    "analyzer"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "jsdom": "^24.0.0"
+  },
+  "devDependencies": {
+    "playwright": "^1.60.0"
+  }
+}

package/src/analyzer.js

@@ -0,0 +1,84 @@
+/**
+ * HTML Analyzer - Core analysis engine for semantic and ARIA compliance
+ */
+
+import { JSDOM } from 'jsdom';
+import { RuleEngine } from './engine/index.js';
+import { formatConsoleReport } from './engine/reporter/index.js';
+
+export class Analyzer {
+  /**
+   * Creates a new Analyzer instance
+   * @param {Object} options - Configuration options
+   * @param {Array} options.rules - Custom rules to apply (uses defaults if not provided)
+   * @param {boolean} options.includeWarnings - Include warning-level issues (default: true)
+   */
+  constructor(options = {}) {
+    this.options = {
+      includeWarnings: true,
+      ...options,
+    };
+    this.ruleEngine = new RuleEngine(options.rules);
+    this.results = null;
+  }
+
+  /**
+   * Analyze HTML content for semantic and ARIA issues
+   * @param {string} html - HTML content to analyze
+   * @param {string} url - Optional URL for context
+   * @returns {Promise<Object>} Analysis results with issues and suggestions
+   */
+  async analyzeHTML(html, url = '') {
+    try {
+      const dom = new JSDOM(html, url ? { url } : undefined);
+      const document = dom.window.document;
+
+      this.results = {
+        url,
+        timestamp: new Date().toISOString(),
+        summary: {
+          total: 0,
+          errors: 0,
+          warnings: 0,
+          suggestions: 0,
+        },
+        issues: [],
+      };
+
+      // Analyze the document with all rules
+      await this.ruleEngine.analyze(document, this.results);
+
+      return this.results;
+    } catch (error) {
+      throw new Error(`Failed to analyze HTML: ${error.message}`);
+    }
+  }
+
+  /**
+   * Analyze HTML from a file
+   * @param {string} filePath - Path to HTML file
+   * @returns {Promise<Object>} Analysis results
+   */
+  async analyzeFile(filePath) {
+    const fs = await import('fs').then((m) => m.promises);
+    const html = await fs.readFile(filePath, 'utf-8');
+    return this.analyzeHTML(html, `file://${filePath}`);
+  }
+
+  /**
+   * Get results from the last analysis
+   * @returns {Object|null} Last analysis results or null if no analysis performed
+   */
+  getResults() {
+    return this.results;
+  }
+
+  /**
+   * Format results for display
+   * @param {Object} results - Analysis results
+   * @returns {string} Formatted output
+   */
+  formatResults(results = this.results) {
+    return formatConsoleReport(results);
+  }
+}

package/src/engine/aria-structure-role-mappings.js

@@ -0,0 +1,131 @@
+function tagName(element) {
+  return element.tagName.toLowerCase();
+}
+
+export const ARIA_STRUCTURE_ROLE_MAPPINGS = [
+  {
+    role: 'article',
+    semanticElement: '<article>',
+    isSemanticMatch: (element) => tagName(element) === 'article',
+  },
+  {
+    role: 'blockquote',
+    semanticElement: '<blockquote>',
+    isSemanticMatch: (element) => tagName(element) === 'blockquote',
+  },
+  {
+    role: 'caption',
+    semanticElement: '<caption>',
+    isSemanticMatch: (element) => tagName(element) === 'caption',
+  },
+  {
+    role: 'cell',
+    semanticElement: '<td>',
+    isSemanticMatch: (element) => tagName(element) === 'td',
+  },
+  {
+    role: 'code',
+    semanticElement: '<code>',
+    isSemanticMatch: (element) => tagName(element) === 'code',
+  },
+  {
+    role: 'columnheader',
+    semanticElement: '<th scope="col">',
+    isSemanticMatch: (element) => tagName(element) === 'th',
+  },
+  {
+    role: 'definition',
+    semanticElement: '<dfn>',
+    isSemanticMatch: (element) => tagName(element) === 'dfn',
+  },
+  {
+    role: 'deletion',
+    semanticElement: '<del>',
+    isSemanticMatch: (element) => tagName(element) === 'del',
+  },
+  {
+    role: 'emphasis',
+    semanticElement: '<em>',
+    isSemanticMatch: (element) => tagName(element) === 'em',
+  },
+  {
+    role: 'figure',
+    semanticElement: '<figure>',
+    isSemanticMatch: (element) => tagName(element) === 'figure',
+  },
+  {
+    role: 'generic',
+    semanticElement: 'a more specific semantic element or remove role="generic"',
+    isSemanticMatch: () => false,
+  },
+  {
+    role: 'heading',
+    semanticElement: '<h1> through <h6>',
+    isSemanticMatch: (element) => /^h[1-6]$/i.test(element.tagName),
+  },
+  {
+    role: 'list',
+    semanticElement: '<ul> or <ol>',
+    isSemanticMatch: (element) => ['ul', 'ol'].includes(tagName(element)),
+  },
+  {
+    role: 'listitem',
+    semanticElement: '<li>',
+    isSemanticMatch: (element) => tagName(element) === 'li',
+  },
+  {
+    role: 'paragraph',
+    semanticElement: '<p>',
+    isSemanticMatch: (element) => tagName(element) === 'p',
+  },
+  {
+    role: 'row',
+    semanticElement: '<tr>',
+    isSemanticMatch: (element) => tagName(element) === 'tr',
+  },
+  {
+    role: 'rowgroup',
+    semanticElement: '<thead>, <tbody>, or <tfoot>',
+    isSemanticMatch: (element) => ['thead', 'tbody', 'tfoot'].includes(tagName(element)),
+  },
+  {
+    role: 'rowheader',
+    semanticElement: '<th scope="row">',
+    isSemanticMatch: (element) => tagName(element) === 'th',
+  },
+  {
+    role: 'separator',
+    semanticElement: '<hr>',
+    isSemanticMatch: (element) => tagName(element) === 'hr',
+  },
+  {
+    role: 'strong',
+    semanticElement: '<strong>',
+    isSemanticMatch: (element) => tagName(element) === 'strong',
+  },
+  {
+    role: 'subscript',
+    semanticElement: '<sub>',
+    isSemanticMatch: (element) => tagName(element) === 'sub',
+  },
+  {
+    role: 'superscript',
+    semanticElement: '<sup>',
+    isSemanticMatch: (element) => tagName(element) === 'sup',
+  },
+  {
+    role: 'table',
+    semanticElement: '<table>',
+    isSemanticMatch: (element) => tagName(element) === 'table',
+  },
+  {
+    role: 'term',
+    semanticElement: '<dt>',
+    isSemanticMatch: (element) => tagName(element) === 'dt',
+  },
+  {
+    role: 'time',
+    semanticElement: '<time>',
+    isSemanticMatch: (element) => tagName(element) === 'time',
+  },
+];

package/src/engine/definitions.js

@@ -0,0 +1,37 @@
+/**
+ * Rule Definitions - Semantic and ARIA compliance rules
+ */
+
+import { ariaActionsRule } from './rules/aria-actions.js';
+import { ariaExpandedRule } from './rules/aria-expanded.js';
+import { ariaModalRule } from './rules/aria-modal.js';
+import { ariaStructureRule } from './rules/aria-structure.js';
+import { headingHierarchyRule } from './rules/heading-hierarchy.js';
+import { imageAltRule } from './rules/image-alt.js';
+import { missingFormLabelsRule } from './rules/missing-form-labels.js';
+import { missingKeyLandmarkRule } from './rules/missing-key-landmark.js';
+import { missingRoleActionRule } from './rules/missing-role-action.js';
+import { nativeLabelRule } from './rules/native-label.js';
+import { ariaLandmarksRule } from './rules/aria-landmarks.js';
+
+/**
+ * Default set of rules for semantic HTML and ARIA analysis
+ */
+export const DEFAULT_RULES = [
+  ariaLandmarksRule,
+  missingFormLabelsRule,
+  headingHierarchyRule,
+  ariaActionsRule,
+  ariaExpandedRule,
+  ariaModalRule,
+  ariaStructureRule,
+  missingRoleActionRule,
+  imageAltRule,
+  nativeLabelRule,
+  missingKeyLandmarkRule,
+];
+
+/**
+ * Placeholder for custom rules users might define
+ */
+export const CUSTOM_RULES = [];

package/src/engine/index.js

@@ -0,0 +1,83 @@
+/**
+ * Rule Engine - Core logic for semantic and ARIA analysis rules
+ */
+
+import { DEFAULT_RULES } from './definitions.js';
+
+export class RuleEngine {
+  /**
+   * Creates a new RuleEngine instance
+   * @param {Array} customRules - Optional custom rules to extend/override defaults
+   */
+  constructor(customRules = []) {
+    this.rules = [...DEFAULT_RULES, ...customRules];
+  }
+
+  /**
+   * Add a custom rule
+   * @param {Object} rule - Rule definition
+   */
+  addRule(rule) {
+    this.rules.push(rule);
+  }
+
+  /**
+   * Analyze a document against all rules
+   * @param {Document} document - DOM document to analyze
+   * @param {Object} results - Results object to populate
+   */
+  async analyze(document, results) {
+    for (const rule of this.rules) {
+      if (!rule.enabled) continue;
+
+      try {
+        const issues = rule.check(document);
+        this.addIssuesToResults(results, issues);
+      } catch (error) {
+        console.error(`Error running rule "${rule.id}":`, error);
+      }
+    }
+
+    // Update summary
+    results.summary.total = results.issues.length;
+  }
+
+  /**
+   * Add issues from a rule to results
+   * @param {Object} results - Results object
+   * @param {Array} issues - Issues array from rule
+   */
+  addIssuesToResults(results, issues) {
+    issues.forEach((issue) => {
+      results.issues.push(issue);
+
+      // Update summary counts
+      if (issue.severity === 'error') {
+        results.summary.errors++;
+      } else if (issue.severity === 'warning') {
+        results.summary.warnings++;
+      } else if (issue.severity === 'suggestion') {
+        results.summary.suggestions++;
+      }
+    });
+  }
+
+  /**
+   * Get all active rules
+   * @returns {Array} Active rules
+   */
+  getActiveRules() {
+    return this.rules.filter((r) => r.enabled);
+  }
+
+  /**
+   * Get rule by ID
+   * @param {string} id - Rule ID
+   * @returns {Object|undefined} Rule definition or undefined
+   */
+  getRule(id) {
+    return this.rules.find((r) => r.id === id);
+  }
+}
+
+export { DEFAULT_RULES };

package/src/engine/reporter/index.js

@@ -0,0 +1,127 @@
+import { writeFile } from 'fs/promises';
+
+const COLORS = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  bold: '\x1b[1m',
+};
+
+const ISSUE_SECTIONS = [
+  {
+    severity: 'error',
+    title: 'Errors',
+    color: COLORS.red,
+  },
+  {
+    severity: 'warning',
+    title: 'Warnings',
+    color: COLORS.yellow,
+  },
+  {
+    severity: 'suggestion',
+    title: 'Suggestions',
+    color: COLORS.cyan,
+  },
+];
+
+function colorize(text, color, useColors) {
+  return useColors ? `${color}${text}${COLORS.reset}` : text;
+}
+
+function groupIssues(issues) {
+  const groups = new Map();
+
+  issues.forEach((issue) => {
+    const key = JSON.stringify({
+      rule: issue.rule,
+      message: issue.message,
+      suggestion: issue.suggestion || '',
+    });
+
+    if (!groups.has(key)) {
+      groups.set(key, {
+        rule: issue.rule,
+        message: issue.message,
+        suggestion: issue.suggestion,
+        elements: [],
+      });
+    }
+
+    groups.get(key).elements.push(issue.element);
+  });
+
+  return Array.from(groups.values());
+}
+
+function formatIssueGroup(group, index) {
+  const instanceLabel = group.elements.length === 1 ? 'instance' : 'instances';
+  let output = `\n${index + 1}. Rule: ${group.rule} (${group.elements.length} ${instanceLabel})\n`;
+  output += `   Message: ${group.message}\n`;
+
+  if (group.suggestion) {
+    output += `   Suggestion: ${group.suggestion}\n`;
+  }
+
+  output += '   Elements:\n';
+  group.elements.forEach((element) => {
+    output += `     - ${element}\n`;
+  });
+
+  return output;
+}
+
+export function formatConsoleReport(results, options = {}) {
+  if (!results) return '';
+
+  const { colors = true } = options;
+  let output = `\nSemantica11y Analysis Report\n`;
+  output += `URL: ${results.url}\n`;
+  output += `Time: ${results.timestamp}\n`;
+  output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
+  output += `Total Findings: ${results.summary.total}\n`;
+  output += `  Errors: ${results.summary.errors}\n`;
+  output += `  Warnings: ${results.summary.warnings}\n`;
+  output += `  Suggestions: ${results.summary.suggestions}\n`;
+  output += `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;
+
+  if (results.issues.length > 0) {
+    output += `\n${colorize('Findings By Category', COLORS.bold, colors)}\n`;
+
+    ISSUE_SECTIONS.forEach(({ severity, title, color }) => {
+      const issues = results.issues.filter((issue) => issue.severity === severity);
+
+      output += `\n${colorize(`${title} (${issues.length})`, color, colors)}\n`;
+      output += `${'─'.repeat(28)}\n`;
+
+      if (issues.length === 0) {
+        output += `No ${title.toLowerCase()} found.\n`;
+        return;
+      }
+
+      groupIssues(issues).forEach((group, index) => {
+        output += formatIssueGroup(group, index);
+      });
+    });
+  } else {
+    output += `\nNo issues found!\n`;
+  }
+
+  return output;
+}
+
+export function printConsoleReport(results, options = {}) {
+  const report = formatConsoleReport(results, options);
+  console.log(report);
+  return report;
+}
+
+export async function exportTextReport(results, filePath, options = {}) {
+  const { colors = false } = options;
+  const report = formatConsoleReport(results, { colors });
+
+  await writeFile(filePath, report, 'utf8');
+
+  return filePath;
+}