@kodalabs-io/eqo 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,445 @@
+import * as playwright from 'playwright';
+import * as _babel_types from '@babel/types';
+import { z } from 'zod';
+
+type AutomationLevel = "full" | "partial" | "manual";
+type CriterionStatus = "validated" | "invalidated" | "not-applicable" | "needs-review";
+type IssueSeverity = "error" | "warning" | "notice";
+type AnalysisPhase = "static" | "runtime";
+type WCAGLevel = "A" | "AA";
+type OutputFormat = "json" | "html" | "sarif" | "markdown" | "junit";
+type SupportedLocale = "en-US" | "fr-FR";
+interface TestDefinition {
+    id: string;
+    automated: boolean;
+}
+interface CriterionDefinition {
+    id: string;
+    theme: number;
+    level: WCAGLevel;
+    wcag: string[];
+    automationLevel: AutomationLevel;
+    tests: TestDefinition[];
+}
+interface ThemeDefinition {
+    id: number;
+    criteria: CriterionDefinition[];
+}
+interface RGAAIssue {
+    id: string;
+    criterionId: string;
+    testId: string;
+    phase: AnalysisPhase;
+    severity: IssueSeverity;
+    /** Serialized HTML snippet of the offending element */
+    element?: string;
+    /** Source file path (relative to project root) */
+    file?: string;
+    line?: number;
+    column?: number;
+    /** Page path where the issue was found (runtime phase) */
+    page?: string;
+    /** i18n message key */
+    messageKey: string;
+    /** i18n remediation key */
+    remediationKey: string;
+    /** Additional context for message interpolation */
+    messageContext?: Record<string, string>;
+    wcag?: string;
+}
+interface TestResult {
+    id: string;
+    status: "pass" | "fail" | "not-applicable" | "needs-review";
+}
+interface CriterionResult {
+    id: string;
+    status: CriterionStatus;
+    issueCount: number;
+    testResults: TestResult[];
+}
+interface ThemeResult {
+    id: number;
+    complianceRate: number;
+    criteriaResults: CriterionResult[];
+}
+interface PageResult {
+    url: string;
+    path: string;
+    title?: string;
+    issueCount: number;
+    /** Set when the page could not be analyzed (e.g. 404, timeout, network error) */
+    error?: string;
+}
+interface ReportSummary {
+    /** Total criteria in the RGAA (106) */
+    totalCriteria: number;
+    /** Criteria applicable on at least one page */
+    applicable: number;
+    /** Criteria validated on all pages */
+    validated: number;
+    /** Criteria invalidated on at least one page */
+    invalidated: number;
+    /** Criteria not applicable on any page */
+    notApplicable: number;
+    /** Criteria that could not be checked automatically */
+    needsReview: number;
+    /**
+     * validated / applicable
+     * Represents the fraction of auto-checkable criteria that passed.
+     */
+    complianceRate: number;
+}
+interface RGAAReport {
+    meta: {
+        rgaaVersion: "4.1.2";
+        toolVersion: string;
+        generatedAt: string;
+        projectName?: string;
+        analyzedPages: string[];
+        locale: SupportedLocale;
+    };
+    summary: ReportSummary;
+    themes: ThemeResult[];
+    pages: PageResult[];
+    issues: RGAAIssue[];
+}
+interface PageConfig {
+    path: string;
+    name?: string;
+}
+interface OutputConfig {
+    format: OutputFormat;
+    /** Output file path (relative to project root) */
+    path: string;
+    /** Minify output where applicable (JSON) */
+    minify?: boolean;
+}
+interface ThresholdConfig {
+    /**
+     * Minimum compliance rate (0–100).
+     * Set to 0 to disable CI blocking — the report is still generated.
+     */
+    complianceRate?: number;
+    /**
+     * Exit with code 1 on any issue of this severity or above.
+     * Defaults to "none" when complianceRate is 0.
+     */
+    failOn?: "error" | "threshold" | "none";
+}
+interface StaticConfig {
+    /** Glob patterns to include (default: src/**\/*.{tsx,jsx,ts,js}) */
+    include?: string[];
+    /** Glob patterns to exclude */
+    exclude?: string[];
+}
+interface ExemptionConfig {
+    /** RGAA criterion ID, e.g. "4.1" */
+    criterion: string;
+    /** Human-readable justification (required for traceability) */
+    reason: string;
+}
+interface KodaRGAAConfig {
+    /** Base URL of the NextJS app to analyze (runtime phase) */
+    baseUrl: string;
+    /** Pages to audit */
+    pages: PageConfig[];
+    /** One or more output formats */
+    output: OutputConfig[];
+    /** CI/CD blocking thresholds */
+    thresholds?: ThresholdConfig;
+    /** Criteria exempted from analysis */
+    exemptions?: ExemptionConfig[];
+    /** Report locale — defaults to "en-US" */
+    locale?: SupportedLocale;
+    /** Project name shown in reports */
+    projectName?: string;
+    /** Static analysis options */
+    static?: StaticConfig;
+}
+interface StaticRuleContext {
+    filePath: string;
+    /** Pre-parsed AST — populated by the worker to avoid re-parsing per rule */
+    ast?: _babel_types.File | null;
+}
+/** Result from a static rule check: issues found, or null if the rule could not run. */
+type RuleResult = RGAAIssue[] | null;
+interface StaticRule {
+    /** RGAA criterion IDs this rule maps to */
+    criteria: string[];
+    id: string;
+    check(context: StaticRuleContext): RuleResult;
+}
+interface RuntimeRuleContext {
+    page: playwright.Page;
+    pageUrl: string;
+    pagePath: string;
+}
+interface RuntimeRule {
+    criteria: string[];
+    id: string;
+    check(context: RuntimeRuleContext): Promise<RGAAIssue[]>;
+}
+
+/**
+ * Build a full RGAA report from collected issues.
+ */
+declare function buildReport(issues: RGAAIssue[], pages: RGAAReport["pages"], config: KodaRGAAConfig): RGAAReport;
+interface AnalysisOptions {
+    /** Skip the runtime (Playwright) analysis phase */
+    staticOnly?: boolean | undefined;
+    /** Skip the static (AST) analysis phase */
+    runtimeOnly?: boolean | undefined;
+    /** Project root directory */
+    projectRoot?: string | undefined;
+    /** AbortSignal to cancel in-progress runtime analysis (e.g. on SIGINT) */
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Run the full RGAA analysis and return a report.
+ */
+declare function analyze(config: KodaRGAAConfig, options?: AnalysisOptions): Promise<RGAAReport>;
+
+/**
+ * Prefix used for axe-originated test IDs (e.g. "axe/image-alt").
+ * Used to distinguish axe issues from static-analysis issues in reports.
+ */
+declare const AXE_TEST_ID_PREFIX = "axe/";
+/**
+ * Maps axe-core rule IDs to RGAA 4.1.2 criterion IDs.
+ *
+ * This mapping is the bridge between the WCAG-based axe-core results
+ * and the RGAA reference framework.
+ *
+ * Reference: https://www.w3.org/WAI/WCAG21/Techniques/
+ */
+declare const AXE_TO_RGAA: Readonly<Record<string, string[]>>;
+/**
+ * Returns the RGAA criterion IDs for a given axe-core rule ID.
+ * Returns an empty array if the rule has no direct RGAA mapping.
+ */
+declare function getRGAACriteria(axeRuleId: string): string[];
+/**
+ * Returns the axe-core rule IDs that map to a given RGAA criterion.
+ */
+declare function getAxeRulesForCriterion(criterionId: string): string[];
+
+interface RuntimeAnalysisResult {
+    issues: RGAAIssue[];
+    pages: PageResult[];
+    durationMs: number;
+}
+/**
+ * Analyze all configured pages using a pool of browser instances.
+ */
+declare function runRuntimeAnalysis(baseUrl: string, pages: PageConfig[], exemptions?: ExemptionConfig[], signal?: AbortSignal): Promise<RuntimeAnalysisResult>;
+
+interface StaticAnalysisResult {
+    issues: RGAAIssue[];
+    filesAnalyzed: number;
+    durationMs: number;
+    /** Number of files served from cache (0 when cache is disabled) */
+    cacheHits: number;
+}
+interface StaticAnalysisOptions {
+    /** Disable the incremental analysis cache */
+    noCache?: boolean | undefined;
+}
+declare function runStaticAnalysis(projectRoot: string, config?: StaticConfig, options?: StaticAnalysisOptions): Promise<StaticAnalysisResult>;
+
+declare const ALL_STATIC_RULES: StaticRule[];
+
+/**
+ * Resolve the configuration file path.
+ * Returns null if no config file is found.
+ */
+declare function resolveConfigPath(cwd: string, explicitPath?: string): string | null;
+/**
+ * Load and validate a eqo configuration file.
+ *
+ * Supports .ts, .js, .mjs (via dynamic import) and .json files.
+ */
+declare function loadConfig(cwd?: string, explicitPath?: string): Promise<KodaRGAAConfig>;
+/**
+ * Generate a default configuration file content.
+ */
+declare function generateDefaultConfig(options?: {
+    baseUrl?: string;
+    projectName?: string;
+    locale?: string;
+}): string;
+
+declare const KodaRGAAConfigSchema: z.ZodObject<{
+    baseUrl: z.ZodString;
+    pages: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    output: z.ZodArray<z.ZodObject<{
+        format: z.ZodEnum<{
+            json: "json";
+            html: "html";
+            sarif: "sarif";
+            markdown: "markdown";
+            junit: "junit";
+        }>;
+        path: z.ZodString;
+        minify: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, z.core.$strip>>;
+    thresholds: z.ZodOptional<z.ZodObject<{
+        complianceRate: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        failOn: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            threshold: "threshold";
+            none: "none";
+        }>>>;
+    }, z.core.$strip>>;
+    exemptions: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        criterion: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>>>;
+    locale: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    projectName: z.ZodOptional<z.ZodString>;
+    static: z.ZodOptional<z.ZodObject<{
+        include: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        exclude: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ValidatedConfig = z.infer<typeof KodaRGAAConfigSchema>;
+
+declare const THEMES: ThemeDefinition[];
+declare const ALL_CRITERIA: CriterionDefinition[];
+declare const CRITERIA_BY_ID: Readonly<Record<string, CriterionDefinition>>;
+declare const TOTAL_CRITERIA: number;
+
+/**
+ * Structured error types for programmatic API consumers.
+ */
+declare class ConfigError extends Error {
+    readonly code: "CONFIG_ERROR";
+    constructor(message: string);
+}
+declare class AnalysisError extends Error {
+    readonly code: "ANALYSIS_ERROR";
+    constructor(message: string);
+}
+declare class TimeoutError extends Error {
+    readonly code: "TIMEOUT_ERROR";
+    constructor(message: string);
+}
+
+interface Translations {
+    themes: Record<number, string>;
+    criteria: Record<string, string>;
+    tests: Record<string, string>;
+    issues: Record<string, string>;
+    remediation: Record<string, string>;
+    automationLevel: Record<string, string>;
+    criterionStatus: Record<string, string>;
+    severity: Record<string, string>;
+    report: {
+        title: string;
+        generated: string;
+        project: string;
+        pages: string;
+        summary: string;
+        totalCriteria: string;
+        applicable: string;
+        validated: string;
+        invalidated: string;
+        notApplicable: string;
+        needsReview: string;
+        complianceRate: string;
+        themes: string;
+        issues: string;
+        noIssues: string;
+        file: string;
+        line: string;
+        element: string;
+        page: string;
+        criterion: string;
+        test: string;
+        severity: string;
+        remediation: string;
+        automationDisclaimer: string;
+    };
+    cli: {
+        analyzing: string;
+        staticPhase: string;
+        runtimePhase: string;
+        reportWritten: string;
+        done: string;
+        failed: string;
+        thresholdExceeded: string;
+        noConfig: string;
+        configCreated: string;
+    };
+}
+
+/**
+ * Load translations for the given locale.
+ * Falls back to "en-US" if the locale is not found.
+ */
+declare function loadTranslations(locale: SupportedLocale): Promise<Translations>;
+/**
+ * Synchronously get cached translations.
+ * Must call loadTranslations() first.
+ */
+declare function getTranslations(locale: SupportedLocale): Translations;
+/**
+ * Interpolate a translation string with named placeholders.
+ *
+ * @example
+ * interpolate("Hello {name}!", { name: "World" }) // → "Hello World!"
+ */
+declare function interpolate(template: string, context?: Record<string, string>): string;
+/**
+ * Returns the list of supported locales.
+ */
+declare function getSupportedLocales(): SupportedLocale[];
+
+declare function printReport(report: RGAAReport): void;
+
+declare function writeHtmlReport(report: RGAAReport, outputConfig: OutputConfig): Promise<void>;
+
+declare function writeJsonReport(report: RGAAReport, outputConfig: OutputConfig): Promise<void>;
+
+declare function writeJunitReport(report: RGAAReport, outputConfig: OutputConfig): Promise<void>;
+
+declare function writeMarkdownReport(report: RGAAReport, outputConfig: OutputConfig): Promise<void>;
+
+declare function writeSarifReport(report: RGAAReport, outputConfig: OutputConfig): Promise<void>;
+
+/**
+ * Write all configured output formats for a report.
+ * Returns a list of written file paths.
+ */
+declare function writeReports(report: RGAAReport, outputs: OutputConfig[]): Promise<string[]>;
+
+/**
+ * kodalabs-io/eqo — RGAA v4.1.2 accessibility compliance analyzer
+ *
+ * Programmatic API for use as a library in your own scripts or tools.
+ *
+ * @example
+ * ```typescript
+ * import { analyze, loadConfig } from "@kodalabs-io/eqo";
+ *
+ * const config = await loadConfig();
+ * const report = await analyze(config);
+ * console.log(`Compliance: ${Math.round(report.summary.complianceRate * 100)}%`);
+ * ```
+ */
+
+/**
+ * Config helper for type-safe configuration files.
+ *
+ * @example
+ * ```typescript
+ * // rgaa.config.ts
+ * import { defineConfig } from "@kodalabs-io/eqo";
+ * export default defineConfig({ ... });
+ * ```
+ */
+declare function defineConfig(config: KodaRGAAConfig): KodaRGAAConfig;
+
+export { ALL_CRITERIA, ALL_STATIC_RULES, AXE_TEST_ID_PREFIX, AXE_TO_RGAA, AnalysisError, type AnalysisPhase, type AutomationLevel, CRITERIA_BY_ID, ConfigError, type CriterionDefinition, type CriterionResult, type CriterionStatus, type ExemptionConfig, type IssueSeverity, type KodaRGAAConfig, KodaRGAAConfigSchema, type OutputConfig, type OutputFormat, type PageConfig, type PageResult, type RGAAIssue, type RGAAReport, type ReportSummary, type RuleResult, type RuntimeRule, type RuntimeRuleContext, type StaticConfig, type StaticRule, type StaticRuleContext, type SupportedLocale, THEMES, TOTAL_CRITERIA, type TestDefinition, type ThemeDefinition, type ThemeResult, type ThresholdConfig, TimeoutError, type ValidatedConfig, type WCAGLevel, analyze, buildReport, defineConfig, generateDefaultConfig, getAxeRulesForCriterion, getRGAACriteria, getSupportedLocales, getTranslations, interpolate, loadConfig, loadTranslations, printReport, resolveConfigPath, runRuntimeAnalysis, runStaticAnalysis, writeHtmlReport, writeJsonReport, writeJunitReport, writeMarkdownReport, writeReports, writeSarifReport };