@holmdigital/engine 1.2.0

package/LICENSE

@@ -0,0 +1,59 @@
+MIT License
+
+Copyright (c) 2025 Holm Digital AB
+
+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.
+
+================================================================================
+
+THIRD PARTY NOTICES
+
+This project includes code or libraries from third parties.
+
+1. axe-core
+   License: Mozilla Public License 2.0 (MPL-2.0)
+   Source: https://github.com/dequelabs/axe-core
+   
+   This software is used unmodified as a dependency.
+   The Source Code Form of axe-core is subject to the terms of the Mozilla Public License, v. 2.0.
+   If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+2. puppeteer
+   License: Apache License 2.0
+   Source: https://github.com/puppeteer/puppeteer
+   
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+   
+       http://www.apache.org/licenses/LICENSE-2.0
+   
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+3. React & ReactDOM
+   License: MIT
+   Source: https://github.com/facebook/react
+
+4. Vite
+   License: MIT
+   Source: https://github.com/vitejs/vite

package/README.md

@@ -0,0 +1,60 @@
+# @holmdigital/engine
+
+> Regulatory accessibility test engine with Virtual DOM and Shadow DOM support.
+
+This engine bridges the gap between technical accessibility scanning (using `axe-core`) and legal compliance reporting (EN 301 549). It provides prescriptive remediation advice and localized reporting.
+
+## Features
+
+- **Regulatory Mapping**: Maps technical failures to EU laws.
+- **HTML Structure Validation**: built-in `html-validate` checks for semantic correctness.
+- **Internationalization (i18n)**: Supports English (`en`), Swedish (`sv`), German (`de`), French (`fr`), and Spanish (`es`).
+- **Pseudo-Automation**: Generates Playwright test scripts for manual verification.
+- **PDF Reporting**: Generates beautiful, compliant PDF reports.
+
+## Installation
+
+```bash
+npm install @holmdigital/engine
+```
+
+## CLI Usage
+
+```bash
+npx hd-a11y-scan <url> [options]
+```
+
+**Options:**
+- `--lang <code>` - Language code (`en`, `sv`, `de`, `fr`, `es`)
+- `--ci` - Run in CI mode (exit code 1 on failure)
+- `--json` - Output results as JSON
+- `--pdf <path>` - Generate a PDF report
+- `--viewport <size>` - Set viewport size (e.g., "mobile", "desktop")
+- `--generate-tests` - Generate Pseudo-Automation tests
+- `--api-key <key>` - API Key for HolmDigital Cloud (sends results to dashboard)
+- `--cloud-url <url>` - Custom URL for HolmDigital Cloud API (optional)
+
+## Programmatic Usage
+
+```typescript
+import { RegulatoryScanner } from '@holmdigital/engine';
+import { setLanguage } from '@holmdigital/engine/dist/i18n';
+
+// Initialize Scanner
+const scanner = new RegulatoryScanner({
+  url: 'https://example.com',
+  failOnCritical: false
+});
+
+// Set Language context (optional, defaults to 'en')
+setLanguage('sv');
+
+// Run Scan
+const result = await scanner.scan();
+
+console.log(`Score: ${result.score}`);
+```
+
+## License
+
+MIT © Holm Digital AB

package/dist/chunk-MFACMI2F.mjs

@@ -0,0 +1,411 @@
+import {
+  __require
+} from "./chunk-Y6FXYEAI.mjs";
+
+// src/core/virtual-dom.ts
+var VirtualDOMBuilder = class {
+  page;
+  constructor(page) {
+    this.page = page;
+  }
+  /**
+   * Bygg ett virtuellt träd av hela sidan
+   */
+  async build(config = {}) {
+    return await this.page.evaluate((config2) => {
+      let nodeIdCounter = 0;
+      function generateId() {
+        return `vn-${++nodeIdCounter}`;
+      }
+      function getAttributes(element) {
+        const attrs = {};
+        for (let i = 0; i < element.attributes.length; i++) {
+          const attr = element.attributes[i];
+          attrs[attr.name] = attr.value;
+        }
+        return attrs;
+      }
+      function getRect(element) {
+        const r = element.getBoundingClientRect();
+        return {
+          x: r.x,
+          y: r.y,
+          width: r.width,
+          height: r.height
+        };
+      }
+      function traverse(node, parent, depth = 0) {
+        if (!node) return null;
+        if (config2.maxDepth && depth > config2.maxDepth) return null;
+        if (node.nodeType !== Node.ELEMENT_NODE && node.nodeType !== Node.DOCUMENT_FRAGMENT_NODE) return null;
+        const element = node;
+        const isShadowRoot = node.nodeType === Node.DOCUMENT_FRAGMENT_NODE;
+        const tagName = isShadowRoot ? "#shadow-root" : element.tagName.toLowerCase();
+        const attributes = !isShadowRoot ? getAttributes(element) : {};
+        let computedStyle;
+        if (!isShadowRoot && config2.includeComputedStyle) {
+          const style = window.getComputedStyle(element);
+          computedStyle = {};
+          config2.includeComputedStyle.forEach((prop) => {
+            computedStyle[prop] = style.getPropertyValue(prop);
+          });
+        }
+        const vNode = {
+          nodeId: generateId(),
+          tagName,
+          attributes,
+          children: [],
+          parentId: parent?.nodeId,
+          isShadowRoot,
+          rect: !isShadowRoot ? getRect(element) : { x: 0, y: 0, width: 0, height: 0 },
+          computedStyle,
+          textContent: node.textContent || void 0
+        };
+        if (isShadowRoot && node.mode) {
+          vNode.shadowMode = node.mode;
+        }
+        if (element.childNodes) {
+          Array.from(element.childNodes).forEach((child) => {
+            if (child.nodeType === Node.ELEMENT_NODE) {
+              const childVNode = traverse(child, vNode, depth + 1);
+              if (childVNode) vNode.children.push(childVNode);
+            }
+          });
+        }
+        if (!isShadowRoot && element.shadowRoot) {
+          const shadowVNode = traverse(element.shadowRoot, vNode, depth + 1);
+          if (shadowVNode) vNode.children.push(shadowVNode);
+        }
+        return vNode;
+      }
+      if (!document.body) {
+        return {
+          nodeId: "root-fallback",
+          tagName: "body",
+          attributes: {},
+          children: [],
+          rect: { x: 0, y: 0, width: 0, height: 0 }
+        };
+      }
+      return traverse(document.body);
+    }, config);
+  }
+};
+
+// src/core/regulatory-scanner.ts
+import puppeteer from "puppeteer";
+
+// src/core/html-validator.ts
+import { HtmlValidate } from "html-validate";
+var HtmlValidator = class {
+  validator;
+  constructor() {
+    const config = {
+      extends: ["html-validate:recommended"],
+      rules: {
+        "no-deprecated-attr": "off",
+        // Focus on structure, not deprecation
+        "prefer-native-element": "off",
+        "no-trailing-whitespace": "off",
+        "void-style": "off",
+        "no-inline-style": "off",
+        // Allowed for A11y overrides
+        "no-implicit-button-type": "off"
+        // Common in React
+      }
+    };
+    this.validator = new HtmlValidate(config);
+  }
+  async validate(html) {
+    const report = await this.validator.validateString(html);
+    return {
+      valid: report.valid,
+      errors: report.results.flatMap(
+        (result) => result.messages.map((msg) => ({
+          rule: msg.ruleId,
+          message: msg.message,
+          line: msg.line,
+          column: msg.column,
+          selector: msg.selector ?? void 0
+        }))
+      )
+    };
+  }
+};
+
+// src/core/regulatory-scanner.ts
+var RegulatoryScanner = class {
+  browser = null;
+  options;
+  htmlValidator;
+  constructor(options) {
+    this.options = {
+      headless: true,
+      standard: "dos-lagen",
+      // Default till striktaste
+      silent: false,
+      ...options
+    };
+    this.htmlValidator = new HtmlValidator();
+  }
+  /** Log only when not in silent mode */
+  log(message) {
+    if (!this.options.silent) {
+      console.log(message);
+    }
+  }
+  /**
+   * Kör en fullständig regulatorisk scan
+   */
+  async scan() {
+    try {
+      await this.initBrowser();
+      const page = await this.getPage();
+      if (this.options.viewport) {
+        await page.setViewport(this.options.viewport);
+      }
+      let retries = 3;
+      while (retries > 0) {
+        try {
+          await page.goto(this.options.url, {
+            waitUntil: "domcontentloaded",
+            timeout: 6e4
+          });
+          break;
+        } catch (e) {
+          retries--;
+          if (retries === 0) throw e;
+          this.log(`Navigation failed, retrying... (${retries} attempts left)`);
+          await new Promise((resolve) => setTimeout(resolve, 2e3));
+        }
+      }
+      try {
+        await page.waitForNetworkIdle({
+          idleTime: 500,
+          timeout: 1e4,
+          concurrency: 2
+        });
+      } catch (e) {
+        this.log("Network busy, proceeding with scan anyway...");
+      }
+      const pageContent = await page.content();
+      const htmlValidation = await this.htmlValidator.validate(pageContent);
+      if (!htmlValidation.valid) {
+        this.log(`HTML Validation: Found ${htmlValidation.errors.length} structural issues.`);
+      }
+      const vDomBuilder = new VirtualDOMBuilder(page);
+      await vDomBuilder.build({ includeComputedStyle: ["color", "background-color"] });
+      await this.injectAxe(page);
+      this.log("Axe injected. Running analysis...");
+      const axeResults = await page.evaluate(async () => {
+        if (!document || !document.documentElement) {
+          return { violations: [] };
+        }
+        return await window.axe.run(document, {
+          iframes: false
+          // Inaktivera iframe-scanning för att undvika kraschar på tunga annons-sajter
+          // Vi tar bort runOnly tillfälligt för att se ALLA fel
+          /*
+          runOnly: {
+              type: 'tag',
+              values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']
+          }
+          */
+        });
+      });
+      this.log(`Raw Axe Violations: ${axeResults.violations?.length || 0}`);
+      const regulatoryReports = await this.enrichResults(axeResults);
+      const result = this.generateResultPackage(regulatoryReports);
+      result.htmlValidation = htmlValidation;
+      return result;
+    } finally {
+      await this.close();
+    }
+  }
+  async initBrowser() {
+    this.browser = await puppeteer.launch({
+      headless: this.options.headless,
+      args: [
+        "--no-sandbox",
+        "--disable-setuid-sandbox",
+        "--disable-blink-features=AutomationControlled"
+        // Gömmer att det är en robot
+      ]
+    });
+  }
+  async getPage() {
+    if (!this.browser) throw new Error("Browser not initialized");
+    const page = await this.browser.newPage();
+    await page.setUserAgent("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36");
+    return page;
+  }
+  async injectAxe(page) {
+    const axeSource = __require("axe-core").source;
+    await page.evaluate(axeSource);
+  }
+  async enrichResults(axeResults) {
+    const reports = [];
+    const { searchRulesByTags, generateRegulatoryReport } = await import("@holmdigital/standards");
+    const { getCurrentLang } = await import("./i18n-FLJMYIKJ.mjs");
+    const lang = getCurrentLang();
+    for (const violation of axeResults.violations) {
+      let report = generateRegulatoryReport(violation.id, lang);
+      if (!report) {
+        const matchingRules = searchRulesByTags(violation.tags, lang);
+        if (matchingRules.length > 0) {
+          report = generateRegulatoryReport(matchingRules[0].ruleId, lang);
+        }
+      }
+      if (report) {
+        reports.push({
+          ...report,
+          holmdigitalInsight: {
+            ...report.holmdigitalInsight,
+            reasoning: violation.help
+            // Använd Axe's hjälptext som specifik anledning
+          },
+          // Attach extra debug info for the CLI
+          failingNodes: violation.nodes.map((node) => ({
+            html: node.html,
+            target: node.target.join(" "),
+            failureSummary: node.failureSummary
+          }))
+        });
+      } else {
+        reports.push({
+          ruleId: violation.id,
+          wcagCriteria: "Unknown",
+          en301549Criteria: "Unknown",
+          dosLagenReference: "Kr\xE4ver manuell bed\xF6mning",
+          diggRisk: "medium",
+          // Default risk
+          eaaImpact: "medium",
+          remediation: {
+            description: violation.help,
+            technicalGuidance: violation.description,
+            component: void 0
+          },
+          holmdigitalInsight: {
+            diggRisk: "medium",
+            eaaImpact: "medium",
+            swedishInterpretation: violation.help,
+            priorityRationale: "Detta fel uppt\xE4cktes av scannern men saknar specifik mappning i HolmDigital-databasen."
+          },
+          testability: {
+            automated: true,
+            requiresManualCheck: false,
+            pseudoAutomation: false,
+            complexity: "moderate"
+          }
+        });
+      }
+    }
+    return reports;
+  }
+  generateResultPackage(reports) {
+    const stats = {
+      critical: reports.filter((r) => r.holmdigitalInsight.diggRisk === "critical").length,
+      high: reports.filter((r) => r.holmdigitalInsight.diggRisk === "high").length,
+      medium: reports.filter((r) => r.holmdigitalInsight.diggRisk === "medium").length,
+      low: reports.filter((r) => r.holmdigitalInsight.diggRisk === "low").length,
+      total: reports.length
+    };
+    const weightedScore = stats.critical * 25 + // Critical violations are severe
+    stats.high * 15 + // High risk affects usability significantly
+    stats.medium * 5 + // Medium annoyance
+    stats.low * 1;
+    const score = Math.max(0, 100 - weightedScore);
+    const complianceStatus = stats.total === 0 ? "PASS" : "FAIL";
+    return {
+      url: this.options.url,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      reports,
+      stats,
+      score,
+      complianceStatus
+    };
+  }
+  /**
+   * Stänger webbläsaren och frigör resurser
+   */
+  async close() {
+    if (this.browser) {
+      await this.browser.close();
+      this.browser = null;
+    }
+  }
+};
+
+// src/automation/pseudo-automation.ts
+var PseudoAutomationEngine = class {
+  /**
+   * Generera ett Playwright-testskript baserat på en rapport
+   */
+  generateTestScript(report, url) {
+    if (!report.holmdigitalInsight.diggRisk) return "";
+    const testName = `Verify ${report.wcagCriteria} - ${report.ruleId}`;
+    return `
+import { test, expect } from '@playwright/test';
+
+/**
+ * GENERATED PSEUDO-AUTOMATION TEST
+ * Rule: ${report.ruleId}
+ * WCAG: ${report.wcagCriteria}
+ * EN 301 549: ${report.en301549Criteria}
+ * Risk: ${report.holmdigitalInsight.diggRisk}
+ * 
+ * Manual Verification Required:
+ * ${report.remediation.description}
+ */
+
+test('${testName}', async ({ page }) => {
+  // 1. Navigate to target
+  await page.goto('${url}');
+
+  // 2. Initial state verification
+  // TODO: Add specific selectors based on report details
+  
+  // 3. Interaction steps (Example for Keyboard Navigation)
+  if ('${report.ruleId}' === 'keyboard-accessible') {
+    console.log('Verifying tab order...');
+    await page.keyboard.press('Tab');
+    
+    // Assert focus state
+    const focused = await page.evaluate(() => document.activeElement?.tagName);
+    console.log('Focused element:', focused);
+    
+    // Add assertions here based on expected focus order
+  }
+  
+  // 4. Verification
+  // Manually verify that...
+});
+    `;
+  }
+  /**
+   * Generera en checklista för manuell testning i Markdown
+   */
+  generateManualChecklist(report) {
+    return `
+### \u{1F575}\uFE0F Manual Verification: ${report.ruleId}
+
+**Regulatory Context**
+- **WCAG**: ${report.wcagCriteria}
+- **DOS-lagen**: ${report.dosLagenReference}
+- **Risk**: ${report.holmdigitalInsight.diggRisk.toUpperCase()}
+
+**Instructions**
+1. [ ] ${report.remediation.description}
+2. [ ] Verify against technical guidance: ${report.remediation.technicalGuidance}
+
+**HolmDigital Insight**
+> ${report.holmdigitalInsight.swedishInterpretation}
+    `;
+  }
+};
+
+export {
+  VirtualDOMBuilder,
+  RegulatoryScanner,
+  PseudoAutomationEngine
+};