@d-zero/a11y-check-core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 D-ZERO Co., Ltd.
+
+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 @@
+# `@d-zero/a11y-check-core`

package/dist/clean-results.d.ts

@@ -0,0 +1,2 @@
+import type { Violation } from './types.js';
+export declare function cleanResults(results: readonly Violation[]): Violation[];

package/dist/clean-results.js

@@ -0,0 +1,29 @@
+import { hash } from '@d-zero/shared/hash';
+import { pathComparator } from '@d-zero/shared/sort/path';
+import { scNumberComparator } from './sc-number-comparator.js';
+export function cleanResults(results) {
+    const hashMap = new Map();
+    for (const result of results) {
+        const content = [
+            result.url,
+            result.component ?? '',
+            result.targetNode.value,
+            result.targetNode.note ?? '',
+        ].join('');
+        const name = hash(content);
+        if (hashMap.has(name)) {
+            const existing = hashMap.get(name);
+            if (!existing.environment.includes(result.environment)) {
+                hashMap.set(name, {
+                    ...existing,
+                    environment: existing.environment + '\n' + result.environment,
+                });
+            }
+            continue;
+        }
+        hashMap.set(name, result);
+    }
+    return [...hashMap.values()]
+        .toSorted((a, b) => scNumberComparator(a.scNumber, b.scNumber))
+        .toSorted((a, b) => pathComparator(a.url, b.url));
+}

package/dist/color-contrast.d.ts

@@ -0,0 +1,8 @@
+import type { ColorContrast, Style } from './types.js';
+export declare enum ColorContrastError {
+    DOES_NOT_DETERMINE_FOREGROUND = 0,
+    DOES_NOT_DETERMINE_BACKGROUND = 1,
+    FOREGROUND_COLOR_HAS_ALPHA = 2,
+    BACKGROUND_COLOR_HAS_ALPHA = 3
+}
+export declare function colorContrastCheck(style: Style): ColorContrastError | ColorContrast;

package/dist/color-contrast.js

@@ -0,0 +1,40 @@
+// @ts-ignore
+import ColorContrastChecker from 'color-contrast-checker';
+import { colorFnToHex } from './color.js';
+const ccc = new ColorContrastChecker();
+export var ColorContrastError;
+(function (ColorContrastError) {
+    ColorContrastError[ColorContrastError["DOES_NOT_DETERMINE_FOREGROUND"] = 0] = "DOES_NOT_DETERMINE_FOREGROUND";
+    ColorContrastError[ColorContrastError["DOES_NOT_DETERMINE_BACKGROUND"] = 1] = "DOES_NOT_DETERMINE_BACKGROUND";
+    ColorContrastError[ColorContrastError["FOREGROUND_COLOR_HAS_ALPHA"] = 2] = "FOREGROUND_COLOR_HAS_ALPHA";
+    ColorContrastError[ColorContrastError["BACKGROUND_COLOR_HAS_ALPHA"] = 3] = "BACKGROUND_COLOR_HAS_ALPHA";
+})(ColorContrastError || (ColorContrastError = {}));
+export function colorContrastCheck(style) {
+    const foreground = colorFnToHex(style.color);
+    if (!foreground) {
+        return ColorContrastError.DOES_NOT_DETERMINE_FOREGROUND;
+    }
+    if (foreground.a < 1) {
+        return ColorContrastError.FOREGROUND_COLOR_HAS_ALPHA;
+    }
+    const background = colorFnToHex(style.backgroundColor) ?? colorFnToHex(style.closestBackgroundColor);
+    if (!background) {
+        return ColorContrastError.DOES_NOT_DETERMINE_BACKGROUND;
+    }
+    if (background.a < 1) {
+        return ColorContrastError.BACKGROUND_COLOR_HAS_ALPHA;
+    }
+    const fL = ccc.hexToLuminance(foreground.hex);
+    const bL = ccc.hexToLuminance(background.hex);
+    const ratio = ccc.getContrastRatio(fL, bL);
+    const ratioText = `${ratio.toFixed(2).replace(/\.0+$/, '')}:1`;
+    const wcag = ccc.verifyContrastRatio(ratio);
+    return {
+        foreground,
+        background,
+        ratio,
+        ratioText,
+        AA: wcag.WCAG_AA,
+        AAA: wcag.WCAG_AAA,
+    };
+}

package/dist/color-contrast.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/color-contrast.spec.js

@@ -0,0 +1,41 @@
+import { test, expect } from 'vitest';
+import { colorContrastCheck, ColorContrastError } from './color-contrast.js';
+test('#000 vs #FFF', () => {
+    expect(colorContrastCheck({
+        color: 'rgb(0, 0, 0)',
+        backgroundColor: 'rgb(255, 255, 255)',
+        backgroundImage: '',
+        closestBackgroundColor: null,
+        closestBackgroundImage: null,
+    })).toStrictEqual({
+        foreground: {
+            a: 1,
+            b: 0,
+            g: 0,
+            hex: '#000000',
+            hexA: '#000000FF',
+            r: 0,
+        },
+        background: {
+            a: 1,
+            b: 255,
+            g: 255,
+            hex: '#FFFFFF',
+            hexA: '#FFFFFFFF',
+            r: 255,
+        },
+        ratio: 21,
+        ratioText: '21:1',
+        AA: true,
+        AAA: true,
+    });
+});
+test('has alpha channel', () => {
+    expect(colorContrastCheck({
+        color: 'rgba(0, 0, 0, 0.5)',
+        backgroundColor: 'rgb(255, 255, 255)',
+        backgroundImage: '',
+        closestBackgroundColor: null,
+        closestBackgroundImage: null,
+    })).toBe(ColorContrastError.FOREGROUND_COLOR_HAS_ALPHA);
+});

package/dist/color.d.ts

@@ -0,0 +1,2 @@
+import type { Color } from './types.js';
+export declare function colorFnToHex(colorFn: string | null): Color | null;

package/dist/color.js

@@ -0,0 +1,32 @@
+export function colorFnToHex(colorFn) {
+    if (!colorFn) {
+        return null;
+    }
+    const match = colorFn.match(/rgba?\s*\(\s*(?<r>\d+)\s*,\s*(?<g>\d+)\s*,\s*(?<b>\d+)(?:\s*,\s*(?<a>\d*(?:\.\d+)?))?\)/);
+    if (!match) {
+        return null;
+    }
+    const r = Number.parseInt(match.groups?.r ?? '0');
+    const g = Number.parseInt(match.groups?.g ?? '0');
+    const b = Number.parseInt(match.groups?.b ?? '0');
+    const a = Number.parseFloat(match.groups?.a ?? '1');
+    if (a === 0) {
+        // Fully transparent
+        return null;
+    }
+    const R = r.toString(16).padStart(2, '0').toUpperCase();
+    const G = g.toString(16).padStart(2, '0').toUpperCase();
+    const B = b.toString(16).padStart(2, '0').toUpperCase();
+    const A = Math.round(a * 255)
+        .toString(16)
+        .padStart(2, '0')
+        .toUpperCase();
+    return {
+        r,
+        g,
+        b,
+        a,
+        hex: `#${R}${G}${B}`,
+        hexA: `#${R}${G}${B}${A}`,
+    };
+}

package/dist/create-scenario.d.ts

@@ -0,0 +1,2 @@
+import type { ScenarioCreator } from './types.js';
+export declare function createScenario<O>(creator: ScenarioCreator<O>): ScenarioCreator<O>;

package/dist/create-scenario.js

@@ -0,0 +1,3 @@
+export function createScenario(creator) {
+    return creator;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { colorContrastCheck, ColorContrastError } from './color-contrast.js';
+export { colorFnToHex } from './color.js';
+export { createScenario } from './create-scenario.js';
+export { scNumberComparator } from './sc-number-comparator.js';
+export { scenarioRunner } from './scenario-runner.js';
+export * from './types.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { colorContrastCheck, ColorContrastError } from './color-contrast.js';
+export { colorFnToHex } from './color.js';
+export { createScenario } from './create-scenario.js';
+export { scNumberComparator } from './sc-number-comparator.js';
+export { scenarioRunner } from './scenario-runner.js';
+export * from './types.js';

package/dist/sc-number-comparator.d.ts

@@ -0,0 +1 @@
+export declare function scNumberComparator(a: string | null, b: string | null): number;

package/dist/sc-number-comparator.js

@@ -0,0 +1,20 @@
+export function scNumberComparator(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    if (a === null) {
+        return 1;
+    }
+    if (b === null) {
+        return -1;
+    }
+    const _a = a.split('.').map((n) => Number.parseInt(n));
+    const _b = b.split('.').map((n) => Number.parseInt(n));
+    if (_a[0] !== _b[0]) {
+        return (_a[0] ?? 0) - (_b[0] ?? 0);
+    }
+    if (_a[1] !== _b[1]) {
+        return (_a[1] ?? 0) - (_b[1] ?? 0);
+    }
+    return (_a[2] ?? 0) - (_b[2] ?? 0);
+}

package/dist/sc-number-comparator.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sc-number-comparator.spec.js

@@ -0,0 +1,21 @@
+import { test, expect } from 'vitest';
+import { scNumberComparator } from './sc-number-comparator.js';
+test('scNumberComparator', () => {
+    expect([
+        //
+        '1.2.3',
+        '1.1.1',
+        '1.2.1',
+        '1.1.2',
+        null,
+        '1.1.3',
+    ].toSorted(scNumberComparator)).toStrictEqual([
+        //
+        '1.1.1',
+        '1.1.2',
+        '1.1.3',
+        '1.2.1',
+        '1.2.3',
+        null,
+    ]);
+});

package/dist/scenario-runner.d.ts

@@ -0,0 +1,5 @@
+import type { CoreOptions, Result, Scenario, ScenarioRunnerOptions } from './types.js';
+export declare function scenarioRunner<O>(urlList: readonly (string | {
+    id: string | null;
+    url: string;
+})[], scenarios: readonly Scenario[], options?: O & CoreOptions & ScenarioRunnerOptions): Promise<Result>;

package/dist/scenario-runner.js

@@ -0,0 +1,91 @@
+import { deal } from '@d-zero/puppeteer-dealer';
+import { beforePageScan, defaultSizes, pageScanListener, } from '@d-zero/puppeteer-page-scan';
+import { Cache } from '@d-zero/shared/cache';
+import { delay } from '@d-zero/shared/delay';
+import c from 'ansi-colors';
+import { cleanResults } from './clean-results.js';
+export async function scenarioRunner(urlList, scenarios, options) {
+    const cache = new Cache('a11y-check/run-puppeteer', options?.cacheDir);
+    const hooks = options?.hooks;
+    const sizes = {
+        desktop: defaultSizes.desktop,
+        mobile: defaultSizes.mobile,
+    };
+    const needAnalysis = [];
+    const passed = [];
+    const violations = [];
+    await deal(urlList.map((url) => {
+        if (typeof url === 'string') {
+            return { id: null, url };
+        }
+        return url;
+    }), (_, done, total) => {
+        return `${c.bold.magenta('🧿 A11y checking%dots%')} ${done}/${total}`;
+    }, {
+        async beforeOpenPage(_, url, logger) {
+            if (options?.cache === false) {
+                logger('Clearing cache');
+                await cache.clear();
+            }
+            logger('Restoring cache');
+            const cached = await cache.load(url, (key, value) => {
+                if (key === 'timestamp') {
+                    return new Date(Date.parse(value));
+                }
+                return value;
+            });
+            if (cached) {
+                logger('Hit cache, skipping page scan');
+                await delay(600);
+                needAnalysis.push(...cached.needAnalysis);
+                passed.push(...cached.passed);
+                violations.push(...cached.violations);
+                return false;
+            }
+            return true;
+        },
+        async deal(page, _, url, logger) {
+            const urlNeedAnalysis = [];
+            const urlPassed = [];
+            const urlViolations = [];
+            for (const [name, size] of Object.entries(sizes)) {
+                const sizeLabel = c.bgMagenta(` ${name} `);
+                for (const scenario of scenarios) {
+                    await beforePageScan(page, url, {
+                        name,
+                        ...size,
+                        hooks,
+                        listener: pageScanListener(logger),
+                    });
+                    const scenarioResult = await scenario.exec(page, name, (log) => logger(`${sizeLabel} ${log}`));
+                    urlNeedAnalysis.push(...(scenarioResult.needAnalysis ?? []));
+                    urlPassed.push(...(scenarioResult.passed ?? []));
+                    urlViolations.push(...(scenarioResult.violations ?? []));
+                }
+            }
+            const urlResults = {
+                needAnalysis: urlNeedAnalysis,
+                passed: urlPassed,
+                violations: urlViolations,
+            };
+            await cache.store(url, urlResults);
+            needAnalysis.push(...urlNeedAnalysis);
+            passed.push(...urlPassed);
+            violations.push(...urlViolations);
+        },
+    }, options);
+    const cleanedViolations = cleanResults(violations);
+    process.stdout.write(`📊 Found ${cleanedViolations.length} violations\n`);
+    for (const scenario of scenarios) {
+        const targets = needAnalysis.filter((result) => result.scenarioId === scenario.id);
+        if (targets.length === 0) {
+            continue;
+        }
+        await scenario.analyze?.(targets, (log) => process.stdout.write(`${log}\n`));
+    }
+    return {
+        needAnalysis: needAnalysis,
+        passed: passed,
+        violations: cleanedViolations,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+import type { DealOptions } from '@d-zero/dealer';
+import type { Page } from '@d-zero/puppeteer-page';
+import type { PageHook } from '@d-zero/puppeteer-page-scan';
+export type CoreOptions = {
+    readonly screenshot?: boolean;
+    readonly cache?: boolean;
+    readonly cacheDir?: string;
+};
+export type ScenarioRunnerOptions = DealOptions & {
+    readonly locale?: string;
+    readonly hooks?: readonly PageHook[];
+};
+export type ScenarioCreator<O> = (options?: O) => Scenario;
+export type Scenario = {
+    id: string;
+    config?: {};
+    exec: ScenarioExecutor;
+    analyze?: ScenarioAnalyzer;
+};
+export type ScenarioExecutor = (page: Page, sizeName: string, log: (log: string) => void) => Promise<Partial<Result>>;
+export type ScenarioAnalyzer = (results: NeedAnalysis[], log: (log: string) => void) => Promise<void | Partial<Result>> | void | Partial<Result>;
+export type Result = {
+    readonly needAnalysis: readonly NeedAnalysis[];
+    readonly passed: readonly Passed[];
+    readonly violations: readonly Violation[];
+};
+export type ResultData = {
+    readonly id: string;
+    readonly url: string;
+    readonly tool: string | null;
+    readonly timestamp: Date;
+    readonly component: string | null;
+    readonly environment: string;
+};
+export type Passed = ResultData & {};
+export type NeedAnalysis = ResultData & {
+    readonly scenarioId: string;
+    readonly subKey?: string;
+    readonly data: string;
+};
+export type Violation = ResultData & {
+    readonly targetNode: Details;
+    readonly asIs: Details;
+    readonly toBe: Details;
+    readonly explanation: Details;
+    readonly wcagVersion: string | null;
+    readonly scNumber: string | null;
+    readonly level: 'A' | 'AA' | 'AAA' | null;
+    readonly screenshot: string | null;
+};
+export type Details = {
+    readonly value: string;
+    readonly note?: string;
+};
+export type Style = {
+    readonly color: string;
+    readonly backgroundColor: string;
+    readonly backgroundImage: string;
+    readonly closestBackgroundColor: string | null;
+    readonly closestBackgroundImage: string | null;
+};
+export type Color = {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+    readonly hex: string;
+    readonly hexA: string;
+};
+export type ColorContrast = {
+    readonly foreground: Color;
+    readonly background: Color;
+    readonly ratio: number;
+    readonly ratioText: `${number}:1`;
+    readonly AA: boolean;
+    readonly AAA: boolean;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@d-zero/a11y-check-core",
+	"version": "0.2.0",
+	"description": "Accessibility Checker (Core Module)",
+	"author": "D-ZERO",
+	"license": "MIT",
+	"private": false,
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc",
+		"watch": "tsc --watch",
+		"clean": "tsc --build --clean"
+	},
+	"dependencies": {
+		"@d-zero/puppeteer-dealer": "0.2.0",
+		"@d-zero/shared": "0.6.0",
+		"ansi-colors": "4.1.3",
+		"color-contrast-checker": "2.1.0"
+	},
+	"devDependencies": {
+		"@d-zero/dealer": "1.2.0",
+		"@d-zero/puppeteer-page": "0.2.0",
+		"@d-zero/puppeteer-page-scan": "2.0.0"
+	},
+	"gitHead": "1eb1c03400580040119121e11ffb33acd876fe1b"
+}