@aishware/react-a11y 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aishwarya Sharma
+
+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,46 @@
+# @aishware/react-a11y
+
+A **static accessibility scanner** for React and React Native. It analyzes your
+TSX/JSX with the TypeScript compiler and reports WCAG 2.2 issues with
+`file:line` locations — no browser, no rendering, no configuration.
+
+The installed command is **`react-a11y`**.
+
+```sh
+# audit the current project (platform auto-detected from package.json)
+npx @aishware/react-a11y .
+
+# explicit platform
+npx @aishware/react-a11y apps/mobile --platform native
+
+# machine-readable output
+npx @aishware/react-a11y . --format json
+npx @aishware/react-a11y . --format sarif --output a11y.sarif   # GitHub code scanning
+
+# gate CI: exit 1 when serious or critical issues exist (default)
+npx @aishware/react-a11y . --fail-on serious
+
+# apply safe mechanical fixes (e.g. miscapitalized React Native accessibility props)
+npx @aishware/react-a11y . --fix
+
+# scan only files changed in git — fast PR checks
+npx @aishware/react-a11y . --changed
+
+# every rule with severity + WCAG mapping, or the coverage report
+npx @aishware/react-a11y --list-rules
+npx @aishware/react-a11y --coverage
+```
+
+Install globally to get the bare `react-a11y` command:
+
+```sh
+npm install -g @aishware/react-a11y
+react-a11y .
+```
+
+Full documentation, rule list and configuration:
+<https://github.com/1aishwaryasharma/react-a11y>
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+import { MANUAL_CHECKS, SEVERITY_ORDER, WCAG, WCAG22_A_AA, WCAG22_TOTALS, applyFixes, detectPlatform, loadConfig, readOwnPackageMeta, scanProject, toJson, toSarif, } from '@aishware/react-a11y-core';
+import { webProjectPasses, webRules, JSX_A11Y_COVERED_WCAG } from '@aishware/react-a11y-rules-web';
+import { nativeRules } from '@aishware/react-a11y-rules-native';
+import { printPretty } from './pretty.js';
+const PKG = readOwnPackageMeta(import.meta.url);
+const VERSION = PKG.version ?? '0.0.0';
+const HELP = `
+${pc.bold('react-a11y')} — accessibility scanner for React, Next.js and React Native
+
+${pc.bold('Usage')}
+  react-a11y [path] [options]
+
+${pc.bold('Options')}
+  --platform <web|native|auto>   Rule pack to run (default: auto-detect from package.json)
+  --format <pretty|json|sarif>   Output format (default: pretty)
+  --output <file>                Write report to a file instead of stdout
+  --fail-on <severity|none>      Exit 1 when issues at/above this severity exist (default: serious)
+  --fix                          Apply safe mechanical fixes, then report what remains
+  --changed                      Scan only files changed in git (vs HEAD, incl. untracked)
+  --list-rules                   Print every rule with severity and WCAG mapping (🔧 = fixable)
+  --coverage                     Show which WCAG 2.2 success criteria the rules cover
+  --version                      Print version
+  --help                         Show this help
+
+${pc.bold('Web a11y')}
+  The web pack runs only what eslint-plugin-jsx-a11y does NOT cover (WCAG 2.2
+  criteria, structure, focus visibility, project-wide checks). Run jsx-a11y in
+  your ESLint config for standard web a11y; react-a11y covers the gaps and the
+  React Native + conformance story.
+
+${pc.bold('Config')}
+  react-a11y.config.json / .react-a11yrc.json / package.json "react-a11y" key:
+  { "platform": "web", "ignore": ["**/*.stories.tsx"], "rules": { "no-autofocus": "off" } }
+`;
+function fail(msg) {
+    console.error(pc.red(`error: ${msg}`));
+    process.exit(2);
+}
+function parseArgs(argv) {
+    const args = {
+        root: process.cwd(), platform: 'auto', format: 'pretty', failOn: 'serious',
+        listRules: false, coverage: false, fix: false, changed: false,
+    };
+    const paths = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const next = () => argv[++i] ?? fail(`${arg} requires a value`);
+        switch (arg) {
+            case '--help':
+            case '-h':
+                console.log(HELP);
+                process.exit(0);
+            // eslint-disable-next-line no-fallthrough
+            case '--version':
+            case '-v':
+                console.log(VERSION);
+                process.exit(0);
+            case '--platform': {
+                const v = next();
+                if (v !== 'web' && v !== 'native' && v !== 'auto')
+                    fail(`invalid platform "${v}"`);
+                args.platform = v;
+                break;
+            }
+            case '--format': {
+                const v = next();
+                if (v !== 'pretty' && v !== 'json' && v !== 'sarif')
+                    fail(`invalid format "${v}"`);
+                args.format = v;
+                break;
+            }
+            case '--output':
+            case '-o':
+                args.output = next();
+                break;
+            case '--fail-on': {
+                const v = next();
+                if (v !== 'none' && !(v in SEVERITY_ORDER))
+                    fail(`invalid severity "${v}"`);
+                args.failOn = v;
+                break;
+            }
+            case '--list-rules':
+                args.listRules = true;
+                break;
+            case '--coverage':
+                args.coverage = true;
+                break;
+            case '--fix':
+                args.fix = true;
+                break;
+            case '--changed':
+                args.changed = true;
+                break;
+            default:
+                if (arg.startsWith('-'))
+                    fail(`unknown option "${arg}" (try --help)`);
+                paths.push(arg);
+        }
+    }
+    if (paths.length > 0)
+        args.root = path.resolve(paths[0]);
+    return args;
+}
+function listRules() {
+    const print = (title, rules) => {
+        console.log(pc.bold(`\n${title}`));
+        for (const r of rules) {
+            const fixable = r.meta.fixable ? '🔧' : '  ';
+            console.log(`  ${fixable} ${pc.cyan(r.meta.id.padEnd(34))} ${r.meta.severity.padEnd(9)} WCAG ${r.meta.wcag.join(', ').padEnd(16)} ${pc.dim(r.meta.description)}`);
+        }
+    };
+    print(`Web rules — complement eslint-plugin-jsx-a11y (${webRules.length})`, webRules);
+    print(`React Native rules (${nativeRules.length})`, nativeRules);
+}
+/** Files changed vs HEAD (staged, unstaged and untracked), for --changed. */
+function changedFiles(root) {
+    let out;
+    try {
+        out = execFileSync('git', ['-C', root, 'status', '--porcelain'], { encoding: 'utf8' });
+    }
+    catch {
+        fail('--changed requires a git repository (git status failed)');
+    }
+    const files = [];
+    for (const line of out.split('\n')) {
+        if (!line.trim())
+            continue;
+        const status = line.slice(0, 2);
+        if (status.includes('D'))
+            continue; // deleted files have nothing to scan
+        let file = line.slice(3);
+        const renameArrow = file.indexOf(' -> ');
+        if (renameArrow !== -1)
+            file = file.slice(renameArrow + 4);
+        files.push(file.replace(/^"|"$/g, ''));
+    }
+    return files;
+}
+/** Apply autofixes to disk; returns counts. Fixes come back from a scan. */
+function applyFixesToDisk(result) {
+    const byFile = new Map();
+    for (const d of result.diagnostics) {
+        if (!d.fix)
+            continue;
+        const list = byFile.get(d.file) ?? [];
+        list.push(d.fix);
+        byFile.set(d.file, list);
+    }
+    let fixed = 0;
+    for (const [file, fixes] of byFile) {
+        const full = path.join(result.root, file);
+        const source = fs.readFileSync(full, 'utf8');
+        const { output, applied } = applyFixes(source, fixes);
+        if (applied > 0) {
+            fs.writeFileSync(full, output);
+            fixed += applied;
+        }
+    }
+    return { fixed, files: byFile.size };
+}
+function printCoverage() {
+    const covered = new Map();
+    const count = (rules, platform) => {
+        for (const rule of rules) {
+            for (const sc of rule.meta.wcag) {
+                const entry = covered.get(sc) ?? { web: 0, native: 0, full: false };
+                entry[platform]++;
+                if (!rule.meta.partial)
+                    entry.full = true;
+                covered.set(sc, entry);
+            }
+        }
+    };
+    count(webRules, 'web');
+    count(nativeRules, 'native');
+    const refs = [...covered.keys()].map((sc) => WCAG[sc]).sort((a, b) => a.sc.localeCompare(b.sc, undefined, { numeric: true }));
+    console.log(pc.bold(`\nAutomated by react-a11y: WCAG 2.2 criteria with at least one rule (${webRules.length} web + ${nativeRules.length} native rules)\n`));
+    for (const ref of refs) {
+        const entry = covered.get(ref.sc);
+        const packs = [entry.web ? `${entry.web} web` : null, entry.native ? `${entry.native} native` : null]
+            .filter(Boolean)
+            .join(', ');
+        const partialBadge = entry.full ? '' : pc.yellow(' ~partial');
+        const newBadge = ref.version === '2.2' ? pc.cyan(' [new in 2.2]') : '';
+        console.log(`  ${ref.sc.padEnd(7)} ${ref.name.padEnd(46)} ${ref.level.padEnd(4)} ${pc.dim(packs)}${partialBadge}${newBadge}`);
+    }
+    // Criteria deferred to eslint-plugin-jsx-a11y (run it alongside react-a11y).
+    const deferred = JSX_A11Y_COVERED_WCAG.filter((sc) => !covered.has(sc) && WCAG22_A_AA.includes(sc));
+    console.log(pc.bold('\nCovered by eslint-plugin-jsx-a11y: run it in your ESLint config\n'));
+    for (const sc of deferred.sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))) {
+        const ref = WCAG[sc];
+        console.log(`  ${ref.sc.padEnd(7)} ${ref.name.padEnd(46)} ${ref.level}`);
+    }
+    const handled = new Set([...covered.keys(), ...deferred]);
+    const manual = WCAG22_A_AA.filter((sc) => !handled.has(sc));
+    console.log(pc.bold('\nManual: A+AA criteria static analysis cannot decide — guided checklist\n'));
+    for (const sc of manual) {
+        const ref = WCAG[sc];
+        console.log(`  ${ref.sc.padEnd(7)} ${ref.name.padEnd(46)} ${ref.level}`);
+        console.log(pc.dim(`          ${MANUAL_CHECKS[sc] ?? 'Verify manually.'}`));
+    }
+    const byLevel = { A: 0, AA: 0, AAA: 0 };
+    for (const ref of refs)
+        byLevel[ref.level]++;
+    const pct = (n, total) => `${Math.round((n / total) * 100)}%`;
+    const aPlusAa = byLevel.A + byLevel.AA;
+    const aPlusAaTotal = WCAG22_TOTALS.A + WCAG22_TOTALS.AA;
+    const withJsx = WCAG22_A_AA.filter((sc) => handled.has(sc)).length;
+    console.log(pc.bold('\nCoverage (Level A + AA)'));
+    console.log(`  Automated by react-a11y     ${aPlusAa}/${aPlusAaTotal}  (${pct(aPlusAa, aPlusAaTotal)})`);
+    console.log(`  + eslint-plugin-jsx-a11y    ${withJsx}/${aPlusAaTotal}  (${pct(withJsx, aPlusAaTotal)})  ← when run alongside`);
+    console.log(pc.yellow(`  Manual review needed        ${manual.length}/${aPlusAaTotal}         ← no static tool can decide these`));
+    console.log(pc.dim('\n  react-a11y covers the WCAG 2.2 / structure / RN / project-wide criteria;\n' +
+        '  eslint-plugin-jsx-a11y covers standard web a11y. The remaining criteria\n' +
+        '  are not automatable — each has a guided manual check listed above, but a\n' +
+        `  human must verify it. Run both linters and work the ${manual.length} manual items.`));
+}
+function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.listRules) {
+        listRules();
+        return;
+    }
+    if (args.coverage) {
+        printCoverage();
+        return;
+    }
+    if (!fs.existsSync(args.root))
+        fail(`path does not exist: ${args.root}`);
+    const config = loadConfig(args.root);
+    const platform = args.platform !== 'auto' ? args.platform : config.platform ?? detectPlatform(args.root);
+    const rules = platform === 'native' ? nativeRules : webRules;
+    const files = args.changed ? changedFiles(args.root) : undefined;
+    // Cross-file passes need the whole project; skip them on partial scans.
+    // Passes are stateful, so each scan gets fresh instances.
+    const makePasses = () => platform === 'web' && !args.changed ? webProjectPasses(config) : [];
+    const scan = () => scanProject({ root: args.root, rules, platform, config, projectPasses: makePasses(), files });
+    let result = scan();
+    if (args.fix) {
+        const { fixed, files: fixedFiles } = applyFixesToDisk(result);
+        if (fixed > 0) {
+            console.error(pc.green(`✔ fixed ${fixed} issue${fixed === 1 ? '' : 's'} in ${fixedFiles} file${fixedFiles === 1 ? '' : 's'}`));
+            result = scan(); // report what remains after the rewrite
+        }
+        else {
+            console.error(pc.dim('no autofixable issues found'));
+        }
+    }
+    let report = null;
+    if (args.format === 'json')
+        report = toJson(result);
+    else if (args.format === 'sarif') {
+        report = toSarif(result, rules, { name: PKG.name, version: PKG.version, informationUri: PKG.homepage });
+    }
+    if (report !== null) {
+        if (args.output) {
+            fs.writeFileSync(args.output, report);
+            console.error(`report written to ${args.output}`);
+        }
+        else {
+            console.log(report);
+        }
+    }
+    else {
+        printPretty(result, VERSION);
+    }
+    if (args.failOn !== 'none') {
+        const threshold = SEVERITY_ORDER[args.failOn];
+        if (result.diagnostics.some((d) => SEVERITY_ORDER[d.severity] >= threshold)) {
+            process.exit(1);
+        }
+    }
+}
+main();

package/dist/pretty.d.ts

@@ -0,0 +1,3 @@
+import type { ScanResult } from '@aishware/react-a11y-core';
+export declare function printPretty(result: ScanResult, version: string): void;
+//# sourceMappingURL=pretty.d.ts.map

package/dist/pretty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pretty.d.ts","sourceRoot":"","sources":["../src/pretty.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAc,UAAU,EAAY,MAAM,2BAA2B,CAAC;AAsBlF,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkDrE"}

package/dist/pretty.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+import { SEVERITY_ORDER } from '@aishware/react-a11y-core';
+const SEVERITY_COLOR = {
+    critical: (s) => pc.bold(pc.red(s)),
+    serious: (s) => pc.red(s),
+    moderate: (s) => pc.yellow(s),
+    minor: (s) => pc.blue(s),
+};
+function snippet(root, diag) {
+    try {
+        const lines = fs.readFileSync(path.join(root, diag.file), 'utf8').split('\n');
+        const line = lines[diag.line - 1];
+        if (line === undefined)
+            return null;
+        const trimmed = line.length > 120 ? `${line.slice(0, 117)}...` : line;
+        return `${pc.dim(`${String(diag.line).padStart(5)} |`)} ${trimmed}`;
+    }
+    catch {
+        return null;
+    }
+}
+export function printPretty(result, version) {
+    const { diagnostics } = result;
+    const out = [];
+    out.push(`${pc.bold('react-a11y')} ${pc.dim(`v${version}`)} — platform: ${pc.cyan(result.platform)} — ` +
+        `${result.filesScanned} files scanned in ${result.durationMs}ms`);
+    out.push('');
+    if (diagnostics.length === 0) {
+        out.push(pc.green('✔ No accessibility issues found.'));
+        console.log(out.join('\n'));
+        return;
+    }
+    const byFile = new Map();
+    for (const d of diagnostics) {
+        const list = byFile.get(d.file) ?? [];
+        list.push(d);
+        byFile.set(d.file, list);
+    }
+    for (const [file, diags] of byFile) {
+        out.push(pc.bold(pc.underline(file)));
+        for (const d of diags) {
+            const pos = pc.dim(`${d.line}:${d.column}`.padEnd(8));
+            const sev = SEVERITY_COLOR[d.severity](d.severity.padEnd(8));
+            out.push(`  ${pos} ${sev} ${pc.cyan(d.ruleId)}`);
+            out.push(`           ${d.message}`);
+            const snip = snippet(result.root, d);
+            if (snip)
+                out.push(`           ${snip}`);
+            const wcag = d.wcag
+                .map((w) => `${w.sc} ${w.name} (Level ${w.level}${w.version === '2.2' ? ', new in WCAG 2.2' : ''})`)
+                .join('; ');
+            out.push(`           ${pc.dim(`WCAG ${wcag}`)}`);
+        }
+        out.push('');
+    }
+    const counts = { critical: 0, serious: 0, moderate: 0, minor: 0 };
+    for (const d of diagnostics)
+        counts[d.severity]++;
+    const parts = Object.keys(SEVERITY_ORDER)
+        .sort((a, b) => SEVERITY_ORDER[b] - SEVERITY_ORDER[a])
+        .filter((s) => counts[s] > 0)
+        .map((s) => SEVERITY_COLOR[s](`${counts[s]} ${s}`));
+    out.push(pc.bold(`✖ ${diagnostics.length} issue${diagnostics.length === 1 ? '' : 's'}`) +
+        ` (${parts.join(', ')}) in ${byFile.size} file${byFile.size === 1 ? '' : 's'}`);
+    console.log(out.join('\n'));
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@aishware/react-a11y",
+  "version": "0.1.0",
+  "description": "Static accessibility scanner for React and React Native — reports WCAG 2.2 issues with file:line locations.",
+  "keywords": ["accessibility", "a11y", "wcag", "wcag-2.2", "react", "react-native", "expo", "linter", "cli", "sarif"],
+  "type": "module",
+  "bin": {
+    "react-a11y": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aishware/react-a11y-core": "^0.1.0",
+    "@aishware/react-a11y-rules-native": "^0.1.0",
+    "@aishware/react-a11y-rules-web": "^0.1.0",
+    "picocolors": "^1.1.0"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/1aishwaryasharma/react-a11y",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1aishwaryasharma/react-a11y.git",
+    "directory": "packages/cli"
+  }
+}