semantica11y 1.0.0 → 1.1.1

package/README.md

@@ -1,4 +1,4 @@
-<img src="./Semantically-logo.png" alt="Semantica11y logo" width="500" height="350">
+<img src="https://media.licdn.com/dms/image/v2/D5622AQGesCZdmU6big/feedshare-shrink_800/B56Z5fRmg6KcAc-/0/1779714910497?e=2147483647&v=beta&t=WrvuX6KsIjAy6aVgzPf3C9K27W5CL3CiR4ngtqHKvJc" alt="Semantica11y logo" width="500" height="350">
 
 # Semantica11y
 
@@ -53,6 +53,51 @@ const results = await analyzer.analyzeHTML(htmlString, 'https://example.com');
 console.log(analyzer.formatResults(results));
 ```
 
+### Configuration (1.1.1)
+
+Configure shared defaults once before creating analyzers:
+
+```javascript
+import { Analyzer, configure, resetConfig } from 'semantica11y';
+
+configure({
+  severities: ['error'], // Report errors only
+  enabledRules: ['image-alt', 'missing-form-labels'],
+  experimental: false,
+});
+
+const analyzer = new Analyzer();
+const results = await analyzer.analyzeHTML(htmlString);
+
+// Instance options override shared defaults.
+const disclosures = new Analyzer({
+  enabledRules: ['aria-expanded'],
+  severities: ['warning'],
+  experimental: true,
+});
+
+resetConfig(); // Restore defaults for future instances
+```
+
+| Option | Default | Behavior |
+| --- | --- | --- |
+| `severities` | `['error', 'warning', 'suggestion']` | Include only these finding severities; `[]` returns no findings. |
+| `enabledRules` | `null` | Run all eligible rules, or only the listed rule IDs; `[]` runs none. |
+| `experimental` | `false` | Opt into experimental rules, currently `aria-expanded`. |
+| `includeWarnings` | `true` | Set to `false` to exclude warnings while retaining selected errors and suggestions. |
+
+Rule selection controls which checks execute. Severity filtering applies to the
+findings because a single rule can produce multiple severities. Summary counts
+and reports reflect the filtered findings. Experimental rules require
+`experimental: true` even when listed in `enabledRules`; rules with
+`enabled: false` remain disabled. Unknown rule IDs match no rules.
+
+Shared settings are copied when an instance is created; later configuration
+changes do not affect existing instances. Custom rules continue to be appended
+using `rules` and follow the same filters; mark a custom rule with
+`experimental: true` to require opt-in. Direct engine users can pass options as
+`new RuleEngine(customRules, options)`; engines also inherit shared defaults.
+
 ### Reports
 
 ```javascript
@@ -87,9 +132,9 @@ 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.
+Semantica11y ships with 11 built-in rules (10 enabled by default and one experimental rule) 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).
+For the full rule-by-rule reference, see [src/engine/rules/README.md](https://github.com/Steady5063/Semantica11y/tree/main/src/engine/rules).
 
 ## 🧪 Testing
 
@@ -111,11 +156,6 @@ Run the Playwright example against `https://example.com`:
 node examples/basic.js
 ```
 
-Analyze a different page:
-
-```bash
-node examples/basic.js https://www.statefarm.com
-```
 
 ## 📦 Build Package
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semantica11y",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "A JavaScript engine to check webpages for ARIA and non-semantic HTML elements with suggestions for improvements",
   "type": "module",
   "main": "./src/index.js",
@@ -18,12 +18,7 @@
     "./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"
+    "test": "node --test test/**/*.test.js"
   },
   "keywords": [
     "accessibility",
@@ -37,9 +32,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "jsdom": "^24.0.0"
-  },
-  "devDependencies": {
-    "playwright": "^1.60.0"
+    "jsdom": "^24.0.0",
+    "semantica11y": "^1.0.0"
   }
 }

package/src/analyzer.js

@@ -10,15 +10,15 @@ 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 {Array} options.rules - Custom rules to append to defaults
+   * @param {string[]} options.severities - Issue severities to include
+   * @param {string[]|null} options.enabledRules - Rule IDs to run (null runs all eligible rules)
+   * @param {boolean} options.experimental - Enable experimental rules (default: false)
    * @param {boolean} options.includeWarnings - Include warning-level issues (default: true)
    */
   constructor(options = {}) {
-    this.options = {
-      includeWarnings: true,
-      ...options,
-    };
-    this.ruleEngine = new RuleEngine(options.rules);
+    this.ruleEngine = new RuleEngine(options.rules, options);
+    this.options = this.ruleEngine.options;
     this.results = null;
   }
 

package/src/config.js

@@ -0,0 +1,49 @@
+/** Shared defaults for newly created analyzers and rule engines. */
+const DEFAULT_CONFIG = {
+  severities: ['error', 'warning', 'suggestion'],
+  enabledRules: null,
+  experimental: false,
+  includeWarnings: true,
+};
+let globalConfig = { ...DEFAULT_CONFIG };
+
+function copyConfig(config) {
+  return {
+    ...config,
+    severities: [...config.severities],
+    enabledRules: config.enabledRules === null ? null : [...config.enabledRules],
+  };
+}
+
+export function resolveConfig(options = {}) {
+  const config = { ...globalConfig, ...options };
+  if (!Array.isArray(config.severities) ||
+      config.severities.some((value) => !DEFAULT_CONFIG.severities.includes(value))) {
+    throw new TypeError('severities must be an array of error, warning, or suggestion');
+  }
+  if (config.enabledRules !== null &&
+      (!Array.isArray(config.enabledRules) ||
+       config.enabledRules.some((id) => typeof id !== 'string' || !id))) {
+    throw new TypeError('enabledRules must be null or an array of rule IDs');
+  }
+  for (const key of ['experimental', 'includeWarnings']) {
+    if (typeof config[key] !== 'boolean') {
+      throw new TypeError(`${key} must be a boolean`);
+    }
+  }
+  return copyConfig(config);
+}
+
+/** Update shared defaults. Instance options take precedence. */
+export function configure(options = {}) {
+  const config = resolveConfig(options);
+  globalConfig = Object.fromEntries(
+    Object.keys(DEFAULT_CONFIG).map((key) => [key, config[key]])
+  );
+  return copyConfig(globalConfig);
+}
+
+/** Restore the built-in defaults for future instances. */
+export function resetConfig() {
+  globalConfig = copyConfig(DEFAULT_CONFIG);
+}

package/src/engine/index.js

@@ -3,13 +3,16 @@
  */
 
 import { DEFAULT_RULES } from './definitions.js';
+import { resolveConfig } from '../config.js';
 
 export class RuleEngine {
   /**
    * Creates a new RuleEngine instance
-   * @param {Array} customRules - Optional custom rules to extend/override defaults
+   * @param {Array} customRules - Optional custom rules to append to defaults
+   * @param {Object} options - Shared configuration overrides
    */
-  constructor(customRules = []) {
+  constructor(customRules = [], options = {}) {
+    this.options = resolveConfig(options);
     this.rules = [...DEFAULT_RULES, ...customRules];
   }
 
@@ -27,8 +30,7 @@ export class RuleEngine {
    * @param {Object} results - Results object to populate
    */
   async analyze(document, results) {
-    for (const rule of this.rules) {
-      if (!rule.enabled) continue;
+    for (const rule of this.getActiveRules()) {
 
       try {
         const issues = rule.check(document);
@@ -49,6 +51,8 @@ export class RuleEngine {
    */
   addIssuesToResults(results, issues) {
     issues.forEach((issue) => {
+      if (!this.options.severities.includes(issue.severity)) return;
+      if (!this.options.includeWarnings && issue.severity === 'warning') return;
       results.issues.push(issue);
 
       // Update summary counts
@@ -67,7 +71,11 @@ export class RuleEngine {
    * @returns {Array} Active rules
    */
   getActiveRules() {
-    return this.rules.filter((r) => r.enabled);
+    return this.rules.filter((rule) =>
+      rule.enabled &&
+      (!rule.experimental || this.options.experimental) &&
+      (this.options.enabledRules === null || this.options.enabledRules.includes(rule.id))
+    );
   }
 
   /**

package/src/engine/rules/README.md

@@ -84,6 +84,8 @@ Exports: `ariaExpandedRule`
 Rule id: `aria-expanded`
 Severity: `warning`
 
+Experimental: disabled by default. Enable with `experimental: true`.
+
 Checks elements with `aria-expanded="true"` or `aria-expanded="false"`.
 
 Individual checks:
@@ -180,13 +182,19 @@ Checks `img` elements for `alt` usage and conflicting ARIA labels.
 
 Individual checks:
 - Missing `alt`: reports an `error` when an image has no `alt` attribute.
+- `aria-hidden="true"` or `role="presentation"` without `alt=""`: reports a
+  `warning` recommending native decorative markup. Missing `alt` still reports
+  an `error`; these attributes do not exempt an image from this semantic check.
+  With meaningful alt text, review whether the image is decorative or informative.
+  Using both attributes produces one combined warning.
 - `aria-label` without `alt`: reports a `warning`.
 - `aria-label` with `alt=""`: reports a `warning`.
 - `aria-label` overriding `alt`: reports a `warning` when normalized
   `aria-label` text differs from normalized `alt` text.
 
-Passes when an image has `alt` and no conflicting `aria-label`, or when
-`aria-label` exactly matches the `alt` text.
+The new decorative-image checks pass with `alt=""` (including bare `alt`).
+Existing `aria-label` conflict checks still apply. Otherwise, images pass with
+`alt` and no conflicting `aria-label`, or matching normalized label text.
 
 ## `native-label.js`
 

package/src/engine/rules/aria-expanded.js

@@ -6,6 +6,7 @@ export const ariaExpandedRule = {
   id: 'aria-expanded',
   name: 'ARIA expanded disclosure',
   enabled: true,
+  experimental: true,
   description: 'Detects aria-expanded usage that could use native disclosure elements',
   check(document) {
     const issues = [];

package/src/engine/rules/image-alt.js

@@ -32,6 +32,24 @@ export const imageAltRule = {
         });
       }
 
+      const decorativeAttributes = [];
+      if (image.getAttribute('aria-hidden')?.trim().toLowerCase() === 'true') {
+        decorativeAttributes.push('aria-hidden="true"');
+      }
+      if (image.getAttribute('role')?.trim().toLowerCase() === 'presentation') {
+        decorativeAttributes.push('role="presentation"');
+      }
+      if (decorativeAttributes.length && (!hasAltAttribute || altText !== '')) {
+        issues.push({
+          severity: 'warning',
+          rule: 'image-alt',
+          element: getElementSignature(image),
+          message: `Image uses ${decorativeAttributes.join(' and ')} without alt=""`,
+          suggestion: 'Use alt="" for decorative images. If the image conveys information, keep meaningful alt text and remove the attributes that hide its semantics',
+          line: getLineNumber(image),
+        });
+      }
+
       if (!hasAriaLabel) {
         return;
       }

package/src/engine/rules/missing-role-action.js

@@ -35,7 +35,7 @@ function createIssue(element, message) {
     rule: 'missing-role-action',
     element: getElementSignature(element),
     message,
-    suggestion: 'Use a native action element such as <button> or <a>, or add an appropriate action role',
+    suggestion: 'Use a native action element such as <button> or <a>',
     line: getLineNumber(element),
   };
 }

package/src/index.js

@@ -12,3 +12,5 @@ export {
   formatConsoleReport,
   printConsoleReport,
 } from './engine/reporter/index.js';
+
+export { configure, resetConfig } from './config.js';