npm - a11yscan - Versions diffs - 0.1.0 - Mend

a11yscan 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Emmanuel
+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 ADDED Viewed

@@ -0,0 +1,114 @@
+# a11yscan
+Like `git status` for accessibility. Run `a11yscan .` and see which files need fixing.
+[![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![npm version](https://img.shields.io/npm/v/a11yscan)](https://www.npmjs.com/package/a11yscan)
+---
+## Install
+```bash
+npm install -g a11yscan
+```
+```bash
+npx a11yscan .
+```
+---
+## Usage
+```bash
+a11yscan .                     # scan current directory
+a11yscan ./src                 # scan a specific folder
+a11yscan ./src/Button.jsx      # scan a single file
+```
+---
+## Output
+```
+Scanning 6 files...
+src/components/Navbar.jsx
+  ❌  line 14    img missing alt attribute           [critical]
+  ❌  line 27    button has no accessible name       [critical]
+src/pages/Home.jsx
+  ⚠️   line 8     heading order skipped (h1 → h3)    [moderate]
+public/index.html
+  ❌  line 3     <html> missing lang attribute       [serious]
+✅  src/components/Button.jsx
+✅  src/pages/About.jsx
+✅  public/404.html
+─────────────────────────────────────────────────────────
+3 critical · 1 serious · 1 moderate · 0 minor
+5 issues across 3 files
+```
+When everything is clean:
+```
+Scanning 3 files...
+✅  src/components/Button.jsx
+✅  src/pages/About.jsx
+✅  public/404.html
+─────────────────────────────────────────────────────────
+0 critical · 0 serious · 0 moderate · 0 minor
+✅  All clear. No accessibility issues found.
+```
+---
+## Flags
+| Flag | Description |
+|------|-------------|
+| `--format json` | Output as JSON instead of terminal display |
+| `--ignore <rule>` | Ignore a rule by name (repeatable) |
+| `--quiet` | Show summary only, no per-file details |
+| `--version` | Show version number |
+---
+## Config
+Create a `.a11yscanrc` file in your project root:
+```json
+{
+  "ignore": ["color-contrast", "label"],
+  "ignoreFiles": ["src/legacy/**", "**/*.stories.jsx"]
+}
+```
+---
+## CI
+```yaml
+- name: Check accessibility
+  run: npx a11yscan ./src
+```
+Exits with code `1` if any violations are found, `0` if clean.
+---
+## License
+© 2026 Emmanuel Oyeyipo

package/bin/cli.js ADDED Viewed

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+'use strict';
+const path = require('path');
+const { Command } = require('commander');
+const { cosmiconfig } = require('cosmiconfig');
+const { findFiles } = require('../src/scanner');
+const { runFile } = require('../src/runner');
+const { report } = require('../src/reporter');
+const { sanitizePath, isWithinCwd, pathExists, validateConfig } = require('../src/utils');
+const chalk = require('chalk');
+const pkg = require('../package.json');
+async function main() {
+  const program = new Command();
+  program
+    .name('a11yscan')
+    .description('Detect accessibility (a11y) violations in HTML, JSX, TSX, and Vue files')
+    .version(pkg.version, '-v, --version', 'Output the current version')
+    .argument('[path]', 'File or directory to scan', '.')
+    .option('--format <type>', 'Output format: terminal or json', 'terminal')
+    .option('--ignore <rules...>', 'Ignore specific rules by name (repeatable)')
+    .option('--quiet', 'Only show the summary, not individual file violations')
+    .helpOption('-h, --help', 'Display help for command')
+    .parse(process.argv);
+  const opts = program.opts();
+  const [targetArg = '.'] = program.args;
+  // ── Load config from .a11yscanrc / cosmiconfig ────────────────────────────
+  let fileConfig = {};
+  try {
+    const explorer = cosmiconfig('a11yscan');
+    const result = await explorer.search();
+    if (result && result.config) {
+      // [SECURITY] Validate config shape and reject prototype pollution attempts
+      const validation = validateConfig(result.config);
+      if (!validation.valid) {
+        process.stderr.write(
+          chalk.red(`Error: invalid config in ${result.filepath}: ${validation.reason}\n`)
+        );
+        process.exit(1);
+      }
+      fileConfig = validation.config;
+    }
+  } catch (err) {
+    process.stderr.write(`Warning: could not load config file: ${err.message}\n`);
+  }
+  // Merge config: CLI flags take priority over file config
+  const ignore = [
+    ...(fileConfig.ignore || []),
+    ...(opts.ignore || []),
+  ];
+  // ── Validate and resolve target path ──────────────────────────────────────
+  const resolvedPath = sanitizePath(targetArg, process.cwd());
+  if (!resolvedPath) {
+    process.stderr.write(chalk.red(`Error: invalid path: ${targetArg}\n`));
+    process.exit(1);
+  }
+  // [SECURITY] Reject paths that escape the current working directory.
+  // This prevents directory traversal (e.g. ../../etc/passwd).
+  if (!isWithinCwd(resolvedPath)) {
+    process.stderr.write(
+      chalk.red(`Error: path is outside the current working directory: ${targetArg}\n`) +
+      chalk.yellow(`  Tip: cd into the target directory and run a11yscan . from there.\n`)
+    );
+    process.exit(1);
+  }
+  if (!pathExists(resolvedPath)) {
+    process.stderr.write(chalk.red(`Error: path does not exist: ${resolvedPath}\n`));
+    process.exit(1);
+  }
+  // ── Discover files ────────────────────────────────────────────────────────
+  let files;
+  try {
+    files = await findFiles(resolvedPath, fileConfig);
+  } catch (err) {
+    process.stderr.write(chalk.red(`Error: could not scan path: ${err.message}\n`));
+    process.exit(1);
+  }
+  if (files.length === 0) {
+    process.stdout.write(
+      chalk.yellow('No supported files found (*.html, *.jsx, *.tsx, *.vue).\n')
+    );
+    process.exit(0);
+  }
+  process.stdout.write(`Scanning ${chalk.bold(files.length)} file${files.length !== 1 ? 's' : ''}...\n`);
+  // ── Run scanners ──────────────────────────────────────────────────────────
+  const allViolations = [];
+  const resultsByFile = new Map(); // file → violations[]
+  const runOptions = { ignore };
+  for (const file of files) {
+    let violations;
+    try {
+      violations = await runFile(file, runOptions);
+    } catch (err) {
+      process.stderr.write(`Warning: unexpected error scanning ${file}: ${err.message}\n`);
+      violations = [];
+    }
+    resultsByFile.set(file, violations);
+    allViolations.push(...violations);
+  }
+  // ── Report results ────────────────────────────────────────────────────────
+  const exitCode = report(allViolations, {
+    format: opts.format,
+    quiet: opts.quiet,
+    resultsByFile,
+  });
+  process.exit(exitCode);
+}
+main().catch((err) => {
+  process.stderr.write(chalk.red(`Fatal: ${err.message}\n`));
+  if (process.env.DEBUG) process.stderr.write(err.stack + '\n');
+  process.exit(1);
+});

package/package.json ADDED Viewed

@@ -0,0 +1,44 @@
+{
+  "name": "a11yscan",
+  "version": "0.1.0",
+  "description": "A fast, zero-config CLI tool for detecting accessibility (a11y) violations in HTML, JSX, TSX, and Vue files",
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "cli",
+    "linter",
+    "wcag",
+    "jsx",
+    "html",
+    "vue"
+  ],
+  "author": "Emmanuel",
+  "license": "MIT",
+  "main": "src/runner.js",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "a11yscan": "bin/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test tests/runner.test.js"
+  },
+  "dependencies": {
+    "@typescript-eslint/parser": "^7.18.0",
+    "axe-core": "^4.9.1",
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0",
+    "cosmiconfig": "^8.3.6",
+    "eslint": "^8.57.1",
+    "eslint-plugin-jsx-a11y": "^6.9.0",
+    "glob": "^10.4.5",
+    "jsdom": "^24.1.3"
+  }
+}

package/src/reporter.js ADDED Viewed

@@ -0,0 +1,186 @@
+'use strict';
+const chalk = require('chalk');
+const { severityEmoji, SEVERITY_ORDER } = require('./utils');
+// ─── Colour helpers ───────────────────────────────────────────────────────────
+function colourSeverity(text, severity) {
+  switch (severity) {
+    case 'critical': return chalk.red.bold(text);
+    case 'serious':  return chalk.red(text);
+    case 'moderate': return chalk.yellow(text);
+    case 'minor':    return chalk.cyan(text);
+    default:         return text;
+  }
+}
+function colourBracket(severity) {
+  return colourSeverity(`[${severity}]`, severity);
+}
+// ─── Grouping ─────────────────────────────────────────────────────────────────
+/**
+ * Group violations by file path.
+ * @param {Array} violations
+ * @returns {Map<string, Array>}
+ */
+function groupByFile(violations) {
+  const map = new Map();
+  for (const v of violations) {
+    if (!map.has(v.file)) map.set(v.file, []);
+    map.get(v.file).push(v);
+  }
+  return map;
+}
+/**
+ * Compute severity counts from a list of violations.
+ */
+function computeSummary(violations) {
+  const counts = { critical: 0, serious: 0, moderate: 0, minor: 0 };
+  for (const v of violations) {
+    if (v.severity in counts) counts[v.severity]++;
+  }
+  return counts;
+}
+// ─── Terminal (pretty) output ─────────────────────────────────────────────────
+function printTerminal(groupedByFile, summary, violations, options = {}) {
+  const { quiet = false, resultsByFile = new Map() } = options;
+  if (!quiet) {
+    // Iterate all scanned files in order so clean files appear alongside bad ones
+    for (const [file, fileViolations] of resultsByFile) {
+      if (fileViolations.length === 0) {
+        // Clean file — one line with a checkmark, blank line after (consistent with violation blocks)
+        process.stdout.write(`${chalk.underline.bold(file)}\n ${chalk.green('✅  All clear. No accessibility issues found.\n')}`);
+        continue;
+      }
+      // Print filename as a header
+      process.stdout.write(chalk.underline.bold(file) + '\n');
+      // Sort by line number within the file
+      const sorted = [...fileViolations].sort((a, b) => (a.line || 0) - (b.line || 0));
+      for (const v of sorted) {
+        const emoji    = severityEmoji(v.severity);
+        const lineStr  = String(v.line || '?').padEnd(4);
+        const msgStr   = v.message.padEnd(44);
+        const bracket  = colourBracket(v.severity);
+        process.stdout.write(
+          `  ${emoji}  line ${lineStr}  ${msgStr}  ${bracket}\n`
+        );
+      }
+      process.stdout.write('\n');
+    }
+  }
+  // Summary line
+  const divider = chalk.gray('─'.repeat(57));
+  process.stdout.write(divider + '\n');
+  const summaryText = chalk.bold('Summary📝')
+  process.stdout.write(summaryText + '\n')
+  const parts = [
+    chalk.red.bold(`${summary.critical} critical`),
+    chalk.red(`${summary.serious} serious`),
+    chalk.yellow(`${summary.moderate} moderate`),
+    chalk.cyan(`${summary.minor} minor`),
+  ];
+  process.stdout.write(parts.join(' · ') + '\n');
+  const total = violations.length;
+  const fileCount = groupedByFile.size;
+  if (total === 0) {
+    process.stdout.write(chalk.green('✅All clear. No accessibility issues found.\n'));
+  } else {
+    process.stdout.write(
+      chalk.bold(`${total} issue${total !== 1 ? 's' : ''} across ${fileCount} file${fileCount !== 1 ? 's' : ''}`) + '\n'
+    );
+  }
+}
+// ─── JSON output ──────────────────────────────────────────────────────────────
+function printJson(groupedByFile, summary, violations) {
+  const files = [];
+  for (const [file, fileViolations] of groupedByFile) {
+    files.push({
+      path: file,
+      violations: fileViolations.map((v) => ({
+        line: v.line || 1,
+        message: v.message,
+        rule: v.rule,
+        severity: v.severity,
+      })),
+    });
+  }
+  const output = {
+    files,
+    summary: {
+      ...summary,
+      total: violations.length,
+      filesWithIssues: groupedByFile.size,
+    },
+  };
+  process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Report violations to stdout in the requested format.
+ *
+ * @param {Array}  violations  - Flat array of violation objects
+ * @param {object} options     - { format: 'terminal'|'json', quiet: boolean }
+ * @returns {number}           - Exit code (0 = clean, 1 = issues found)
+ */
+function report(violations, options = {}) {
+  const { format = 'terminal', quiet = false, resultsByFile = new Map() } = options;
+  if (violations.length === 0) {
+    if (format === 'json') {
+      printJson(new Map(), { critical: 0, serious: 0, moderate: 0, minor: 0 }, []);
+    } else {
+      // Still show per-file ✅ lines even when everything is clean
+      if (!quiet) {
+        for (const file of resultsByFile.keys()) {
+          process.stdout.write(`${chalk.green('✅')}  ${chalk.dim(file)}\n`);
+        }
+      }
+      process.stdout.write('\n' + chalk.green('✅  All clear. No accessibility issues found.\n'));
+    }
+    return 0;
+  }
+  // Sort violations: by file, then by severity, then by line
+  const sorted = [...violations].sort((a, b) => {
+    if (a.file !== b.file) return a.file.localeCompare(b.file);
+    const sevDiff = (SEVERITY_ORDER[a.severity] ?? 99) - (SEVERITY_ORDER[b.severity] ?? 99);
+    if (sevDiff !== 0) return sevDiff;
+    return (a.line || 0) - (b.line || 0);
+  });
+  const grouped = groupByFile(sorted);
+  const summary = computeSummary(sorted);
+  if (format === 'json') {
+    printJson(grouped, summary, sorted);
+  } else {
+    printTerminal(grouped, summary, sorted, { quiet, resultsByFile });
+  }
+  return 1;
+}
+module.exports = { report, computeSummary };

package/src/runner.js ADDED Viewed

@@ -0,0 +1,311 @@
+'use strict';
+const path = require('path');
+const { JSDOM, VirtualConsole } = require('jsdom');
+const axe = require('axe-core');
+// Rules that require browser APIs unavailable in jsdom (e.g. Canvas for color-contrast)
+const AXE_JSDOM_UNSUPPORTED_RULES = ['color-contrast', 'color-contrast-enhanced'];
+const { ESLint } = require('eslint');
+const jsxA11yPlugin = require('eslint-plugin-jsx-a11y');
+const { safeReadFile, getFileType } = require('./utils');
+// ─── Severity mapping ────────────────────────────────────────────────────────
+function mapAxeImpact(impact) {
+  const map = { critical: 'critical', serious: 'serious', moderate: 'moderate', minor: 'minor' };
+  return map[impact] || 'minor';
+}
+function mapEslintSeverity(severity) {
+  // ESLint severity: 2 = error, 1 = warn
+  return severity === 2 ? 'critical' : 'moderate';
+}
+// ─── Line-number helpers ─────────────────────────────────────────────────────
+/**
+ * Best-effort search for the source line of a DOM element.
+ * axe-core gives us the outer HTML of the violating node; we search the source
+ * for a distinctive substring to determine the approximate line number.
+ */
+function findLineInSource(sourceLines, nodeHtml) {
+  if (!nodeHtml) return 1;
+  const tagMatch = nodeHtml.match(/^<([a-zA-Z][a-zA-Z0-9-]*)/);
+  if (!tagMatch) return 1;
+  const tagName = tagMatch[1].toLowerCase();
+  // Prefer matching on a unique attribute so we pinpoint the right element
+  const idMatch    = nodeHtml.match(/\sid="([^"]+)"/i);
+  const nameMatch  = nodeHtml.match(/\sname="([^"]+)"/i);
+  const ariaMatch  = nodeHtml.match(/\s(aria-\w+)="([^"]+)"/i);
+  const srcMatch   = nodeHtml.match(/\s(?:src|href)="([^"]+)"/i);
+  const classMatch = nodeHtml.match(/\sclass="([^"]+)"/i);
+  for (let i = 0; i < sourceLines.length; i++) {
+    const line = sourceLines[i];
+    if (!line.toLowerCase().includes(`<${tagName}`)) continue;
+    if (idMatch    && line.includes(idMatch[1]))                           return i + 1;
+    if (nameMatch  && line.includes(nameMatch[1]))                         return i + 1;
+    if (ariaMatch  && line.toLowerCase().includes(ariaMatch[2]))           return i + 1;
+    if (srcMatch   && line.includes(srcMatch[1].substring(0, 30)))         return i + 1;
+    if (classMatch && line.includes(classMatch[1].split(' ')[0]))          return i + 1;
+    // No distinguishing attribute — return first tag occurrence
+    return i + 1;
+  }
+  return 1;
+}
+// ─── HTML scanner (axe-core + jsdom) ─────────────────────────────────────────
+async function scanHtml(filePath, content, options = {}) {
+  const violations = [];
+  // [SECURITY] Remove <script> tags so user JavaScript is never evaluated.
+  // runScripts: 'outside-only' is set below as a second layer, but stripping
+  // is defense-in-depth — the content never reaches the JS engine at all.
+  const safeContent = content.replace(
+    /<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi,
+    '<!-- script removed -->'
+  );
+  const absolutePath = path.resolve(filePath);
+  // file:/// URL required by jsdom; normalise Windows back-slashes
+  const fileUrl = `file:///${absolutePath.replace(/\\/g, '/')}`;
+  // Silence jsdom's "Not implemented" messages (e.g. canvas) — they are not errors
+  const virtualConsole = new VirtualConsole();
+  // [SECURITY] Wrap JSDOM construction — a malformed file should never crash the process
+  let dom;
+  try {
+    dom = new JSDOM(safeContent, {
+      runScripts: 'outside-only', // prevents HTML's own scripts; allows our eval below
+      url: fileUrl,
+      virtualConsole,
+    });
+  } catch (err) {
+    process.stderr.write(`Warning: could not parse HTML in ${filePath}: ${err.message}\n`);
+    return [];
+  }
+  // [SECURITY] Inject axe-core from our trusted npm bundle — NOT from user content.
+  // axe.source is a pre-built string shipped with the axe-core package.
+  // runScripts: 'outside-only' means only this explicit eval() is permitted;
+  // any scripts embedded in the user's HTML file are inert.
+  try {
+    dom.window.eval(axe.source);
+  } catch (err) {
+    process.stderr.write(`Warning: could not inject axe-core for ${filePath}: ${err.message}\n`);
+    return [];
+  }
+  const axeOptions = { resultTypes: ['violations'] };
+  // Always disable rules that require browser Canvas (not available in jsdom)
+  axeOptions.rules = {};
+  AXE_JSDOM_UNSUPPORTED_RULES.forEach((rule) => {
+    axeOptions.rules[rule] = { enabled: false };
+  });
+  if (options.ignore && options.ignore.length > 0) {
+    options.ignore.forEach((rule) => {
+      axeOptions.rules[rule] = { enabled: false };
+    });
+  }
+  let results;
+  try {
+    results = await dom.window.axe.run(dom.window.document, axeOptions);
+  } catch (err) {
+    process.stderr.write(`Warning: axe-core failed on ${filePath}: ${err.message}\n`);
+    return [];
+  }
+  const sourceLines = content.split('\n');
+  for (const violation of results.violations) {
+    const severity = mapAxeImpact(violation.impact);
+    const message  = violation.help || violation.description;
+    for (const node of violation.nodes) {
+      const line = findLineInSource(sourceLines, node.html);
+      violations.push({
+        file: filePath,
+        line,
+        message,
+        rule: violation.id,
+        severity,
+      });
+    }
+  }
+  return violations;
+}
+// ─── JSX/TSX scanner (eslint-plugin-jsx-a11y) ────────────────────────────────
+/**
+ * Build the rule set from eslint-plugin-jsx-a11y recommended config,
+ * then supplement with any remaining rules as warnings.
+ */
+function buildJsxRules(ignoreRules = []) {
+  const recommended = jsxA11yPlugin.configs.recommended.rules || {};
+  const rules = {};
+  // Start from recommended
+  Object.entries(recommended).forEach(([rule, value]) => {
+    if (value !== 'off' && value !== 0) {
+      rules[rule] = value;
+    }
+  });
+  // Add remaining plugin rules not covered by recommended
+  Object.keys(jsxA11yPlugin.rules).forEach((ruleName) => {
+    const fullRule = `jsx-a11y/${ruleName}`;
+    if (!(fullRule in rules)) {
+      rules[fullRule] = 'warn';
+    }
+  });
+  // Apply caller-supplied ignores
+  ignoreRules.forEach((rule) => {
+    const fullRule = rule.includes('/') ? rule : `jsx-a11y/${rule}`;
+    if (fullRule in rules) rules[fullRule] = 'off';
+  });
+  return rules;
+}
+async function scanJsx(filePath, content, options = {}) {
+  const violations = [];
+  const isTypescript = filePath.endsWith('.tsx');
+  const overrideConfig = {
+    plugins: ['jsx-a11y'],
+    rules: buildJsxRules(options.ignore || []),
+    parserOptions: {
+      ecmaVersion: 2022,
+      ecmaFeatures: { jsx: true },
+      sourceType: 'module',
+    },
+    env: { browser: true, es2022: true },
+  };
+  if (isTypescript) {
+    try {
+      require.resolve('@typescript-eslint/parser');
+      overrideConfig.parser = '@typescript-eslint/parser';
+      overrideConfig.parserOptions.project = false; // disable type-checking
+    } catch {
+      process.stderr.write(`Warning: @typescript-eslint/parser not found; skipping ${filePath}\n`);
+      return [];
+    }
+  }
+  let eslint;
+  try {
+    eslint = new ESLint({
+      useEslintrc: false,
+      allowInlineConfig: false,
+      // Resolve plugins relative to this package so they're always found,
+      // regardless of where the user runs the command.
+      resolvePluginsRelativeTo: path.join(__dirname, '..'),
+      overrideConfig,
+    });
+  } catch (err) {
+    process.stderr.write(`Warning: ESLint init failed for ${filePath}: ${err.message}\n`);
+    return [];
+  }
+  let results;
+  try {
+    // [SECURITY] lintText() treats `content` as plain source text — it is parsed
+    // by ESLint's parser into an AST; the text itself is never eval'd or executed.
+    results = await eslint.lintText(content, { filePath });
+  } catch (err) {
+    process.stderr.write(`Warning: ESLint parse error in ${filePath}: ${err.message}\n`);
+    return [];
+  }
+  for (const result of results) {
+    for (const msg of result.messages) {
+      if (!msg.ruleId || !msg.ruleId.startsWith('jsx-a11y/')) continue;
+      violations.push({
+        file: filePath,
+        line: msg.line || 1,
+        message: msg.message,
+        rule: msg.ruleId,
+        severity: mapEslintSeverity(msg.severity),
+      });
+    }
+  }
+  return violations;
+}
+// ─── Vue scanner (extract <template>, run through axe) ───────────────────────
+async function scanVue(filePath, content, options = {}) {
+  // [SECURITY] Only the <template> block is extracted; <script> and <style>
+  // blocks in Vue SFCs are never read or evaluated.
+  let templateMatch;
+  try {
+    templateMatch = content.match(/<template[^>]*>([\s\S]*?)<\/template>/i);
+  } catch (err) {
+    process.stderr.write(`Warning: could not extract template from ${filePath}: ${err.message}\n`);
+    return [];
+  }
+  if (!templateMatch) return [];
+  const templateContent = templateMatch[1];
+  const templateStartLine =
+    content.substring(0, content.indexOf(templateMatch[0])).split('\n').length;
+  // Wrap the extracted template in a minimal HTML document for axe scanning
+  const htmlWrapper = `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>Vue Template</title></head><body>${templateContent}</body></html>`;
+  const violations = await scanHtml(filePath, htmlWrapper, options);
+  // Shift line numbers back to the Vue SFC coordinate space
+  return violations.map((v) => ({
+    ...v,
+    line: Math.max(1, (v.line || 1) + templateStartLine - 1),
+  }));
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Run the appropriate a11y scanner for a single file.
+ * Returns an array of violation objects, or [] on error.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @param {object} options  - { ignore: string[] }
+ * @returns {Promise<Array<{file, line, message, rule, severity}>>}
+ */
+async function runFile(filePath, options = {}) {
+  // [SECURITY] safeReadFile checks: symlink → skip, >500KB → skip, unreadable → warn+skip
+  const content = safeReadFile(filePath);
+  if (content === null) return [];
+  const type = getFileType(filePath);
+  // [SECURITY] All branches below treat `content` as plain text only.
+  // axe-core / ESLint parse it into an AST; nothing is eval'd or executed.
+  switch (type) {
+    case 'html': return scanHtml(filePath, content, options);
+    case 'jsx':  return scanJsx(filePath, content, options);
+    case 'vue':  return scanVue(filePath, content, options);
+    default:     return [];
+  }
+}
+module.exports = { runFile, scanHtml, scanJsx, scanVue };

package/src/scanner.js ADDED Viewed

@@ -0,0 +1,73 @@
+'use strict';
+const path = require('path');
+const fs = require('fs');
+const { glob } = require('glob');
+const { SUPPORTED_EXTENSIONS } = require('./utils');
+const SUPPORTED_GLOB = '**/*.{html,jsx,tsx,vue}';
+// Directories that should always be excluded from scanning
+const DEFAULT_IGNORE = [
+  '**/node_modules/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.git/**',
+  '**/coverage/**',
+  '**/.next/**',
+  '**/.nuxt/**',
+  '**/out/**',
+  '**/.cache/**',
+];
+/**
+ * Find all supported files under the given directory path.
+ * For a single file path, validates it directly.
+ *
+ * @param {string} targetPath - Absolute path to scan
+ * @param {object} config     - Loaded cosmiconfig options
+ * @returns {Promise<string[]>} Sorted list of absolute file paths
+ */
+async function findFiles(targetPath, config = {}) {
+  // [SECURITY] Use lstatSync (not statSync) so symlinked directories are detected
+  // and not silently followed into unknown parts of the filesystem.
+  let stat;
+  try {
+    stat = fs.lstatSync(targetPath);
+  } catch (err) {
+    throw new Error(`Cannot stat path "${targetPath}": ${err.message}`);
+  }
+  // [SECURITY] Reject symlinks outright — they may point outside cwd
+  if (stat.isSymbolicLink()) {
+    process.stderr.write(`Warning: skipping symlink: ${targetPath}\n`);
+    return [];
+  }
+  // Single file mode
+  if (stat.isFile()) {
+    const ext = path.extname(targetPath).toLowerCase();
+    if (!SUPPORTED_EXTENSIONS.has(ext)) {
+      return [];
+    }
+    return [targetPath];
+  }
+  // Directory mode — use glob
+  const ignorePatterns = [
+    ...DEFAULT_IGNORE,
+    ...(Array.isArray(config.ignoreFiles) ? config.ignoreFiles : []),
+  ];
+  const matches = await glob(SUPPORTED_GLOB, {
+    cwd: targetPath,
+    absolute: true,
+    ignore: ignorePatterns,
+    nodir: true,
+    follow: false, // [SECURITY] Never follow symlinks during recursive scan
+  });
+  return matches.sort();
+}
+module.exports = { findFiles };

package/src/utils.js ADDED Viewed

@@ -0,0 +1,191 @@
+'use strict';
+const path = require('path');
+const fs = require('fs');
+const SUPPORTED_EXTENSIONS = new Set(['.html', '.jsx', '.tsx', '.vue']);
+const SEVERITY_ORDER = { critical: 0, serious: 1, moderate: 2, minor: 3 };
+// 500 KB — files larger than this are skipped to prevent ReDoS / parser crashes
+const MAX_FILE_SIZE_BYTES = 500 * 1024;
+// Keys that indicate a prototype pollution attempt in config objects
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * Sanitize a file path to prevent directory traversal attacks.
+ * Returns the resolved absolute path, or null if the path is unsafe.
+ */
+function sanitizePath(inputPath, basePath) {
+  if (typeof inputPath !== 'string' || inputPath.trim() === '') {
+    return null;
+  }
+  // Resolve relative to provided base or CWD
+  const base = basePath ? path.resolve(basePath) : process.cwd();
+  const resolved = path.resolve(base, inputPath);
+  // Reject null bytes
+  if (resolved.includes('\0')) {
+    return null;
+  }
+  return resolved;
+}
+/**
+ * Enforce that a resolved path stays within the current working directory.
+ * Returns true if safe, false if the path escapes cwd.
+ */
+function isWithinCwd(resolvedPath) {
+  const cwd = process.cwd();
+  // Allow exact match (scanning cwd itself) or a child path
+  return resolvedPath === cwd || resolvedPath.startsWith(cwd + path.sep);
+}
+/**
+ * Check that a path exists and is accessible.
+ */
+function pathExists(targetPath) {
+  try {
+    fs.accessSync(targetPath, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+/**
+ * Determine the scanner type based on file extension.
+ * Returns 'html', 'jsx', or 'vue', or null if unsupported.
+ */
+function getFileType(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (!SUPPORTED_EXTENSIONS.has(ext)) return null;
+  if (ext === '.html') return 'html';
+  if (ext === '.vue') return 'vue';
+  return 'jsx'; // covers .jsx and .tsx
+}
+/**
+ * Safely read a file, returning null and logging a warning if it fails.
+ *
+ * Security checks applied before reading:
+ *   1. lstat — reject symlinks silently
+ *   2. size  — reject files > 500 KB with a warning
+ */
+function safeReadFile(filePath) {
+  try {
+    // [SECURITY] Check for symlinks — do not follow them
+    const lstat = fs.lstatSync(filePath);
+    if (lstat.isSymbolicLink()) {
+      // Skip silently; symlinks could point anywhere on the filesystem
+      return null;
+    }
+    // [SECURITY] Enforce file size limit to prevent ReDoS / parser crashes
+    if (lstat.size > MAX_FILE_SIZE_BYTES) {
+      process.stderr.write(
+        `Warning: skipping ${filePath} — file exceeds 500 KB (${Math.round(lstat.size / 1024)} KB)\n`
+      );
+      return null;
+    }
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch (err) {
+    if (err.code === 'EACCES') {
+      process.stderr.write(`Warning: permission denied reading ${filePath}\n`);
+    } else if (err.code === 'ENOENT') {
+      process.stderr.write(`Warning: file not found ${filePath}\n`);
+    } else {
+      process.stderr.write(`Warning: could not read ${filePath}: ${err.message}\n`);
+    }
+    return null;
+  }
+}
+/**
+ * Validate a config object loaded from cosmiconfig.
+ * Guards against prototype pollution via __proto__, constructor, or prototype keys.
+ * Also ensures the expected fields are the correct types.
+ *
+ * Returns { valid: true, config } on success, or { valid: false, reason } on failure.
+ */
+function validateConfig(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { valid: false, reason: 'config must be a plain object' };
+  }
+  // [SECURITY] Reject prototype pollution keys at the top level and nested
+  for (const key of Object.keys(raw)) {
+    if (DANGEROUS_KEYS.has(key)) {
+      return { valid: false, reason: `config contains forbidden key: "${key}"` };
+    }
+  }
+  // Validate "ignore" — must be an array of strings if present
+  if ('ignore' in raw) {
+    if (!Array.isArray(raw.ignore) || !raw.ignore.every((v) => typeof v === 'string')) {
+      return { valid: false, reason: '"ignore" must be an array of strings' };
+    }
+    // Check nested values for dangerous patterns
+    for (const v of raw.ignore) {
+      if (DANGEROUS_KEYS.has(v)) {
+        return { valid: false, reason: `forbidden value in "ignore": "${v}"` };
+      }
+    }
+  }
+  // Validate "ignoreFiles" — must be an array of strings if present
+  if ('ignoreFiles' in raw) {
+    if (!Array.isArray(raw.ignoreFiles) || !raw.ignoreFiles.every((v) => typeof v === 'string')) {
+      return { valid: false, reason: '"ignoreFiles" must be an array of strings' };
+    }
+  }
+  // Build a clean config with only the known safe keys
+  const config = Object.create(null);
+  if (raw.ignore)      config.ignore      = raw.ignore.slice();
+  if (raw.ignoreFiles) config.ignoreFiles = raw.ignoreFiles.slice();
+  return { valid: true, config };
+}
+/**
+ * Compare two severity values, returns negative if a < b (a is more severe).
+ */
+function compareSeverity(a, b) {
+  return (SEVERITY_ORDER[a] ?? 99) - (SEVERITY_ORDER[b] ?? 99);
+}
+/**
+ * Return an emoji for a given severity level.
+ */
+function severityEmoji(severity) {
+  if (severity === 'critical' || severity === 'serious') return '❌';
+  if (severity === 'moderate') return '⚠️';
+  return 'ℹ️';
+}
+/**
+ * Strip ANSI escape codes from a string (for JSON output).
+ */
+function stripAnsi(str) {
+  return str.replace(/\x1B\[[0-9;]*m/g, '');
+}
+module.exports = {
+  sanitizePath,
+  isWithinCwd,
+  pathExists,
+  getFileType,
+  safeReadFile,
+  validateConfig,
+  compareSeverity,
+  severityEmoji,
+  stripAnsi,
+  SUPPORTED_EXTENSIONS,
+  SEVERITY_ORDER,
+  MAX_FILE_SIZE_BYTES,
+};