astro-a11y 0.0.0-stage → 0.2.0

package/LICENSE

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

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# astro-a11y
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CLI that scans a static build folder or a live URL with Playwright + axe-core, maps findings to RGAA 4.1.2 criteria and renders terminal, JSON, HTML or Markdown reports.
+
+```bash
+npx playwright install chromium
+npx astro-a11y check ./dist --mode balanced
+npx astro-a11y check https://example.com --mode paranoid --allowed-domains example.com
+```
+
+Modes, options and security guards: see the [main documentation](https://github.com/Stan69000/astro-a11y#readme) ([français](https://github.com/Stan69000/astro-a11y/blob/main/README.fr.md)).
+
+Backed by [Le Singe du Numérique](https://lesingedunumerique.fr). MIT licensed.

package/dist/bin.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import {
+  SUPPORTED_LANGS,
+  isSupportedLang,
+  applyBaseline,
+  createBaseline,
+  installChromium,
+  parseBaseline,
+  scanTarget,
+  SEVERITY_ORDER,
+  SCAN_MODES,
+  isSeverity,
+  isScanMode,
+  resolveFailThreshold,
+  hasIssuesAtOrAbove
+} from '@astro-a11y/core';
+import { renderByFormat } from '@astro-a11y/reporters';
+import { writeOutput } from './output-path.js';
+
+// Read from the published manifest so `--version` always matches the release.
+const { version } = createRequire(import.meta.url)('../package.json');
+
+function exitWithError(message) {
+  process.stderr.write(`Error: ${message}\n`);
+  process.exit(1);
+}
+
+const program = new Command();
+
+program
+  .name('astro-a11y')
+  .description('Accessibility guardrails for Astro projects.')
+  .version(version);
+
+program
+  .command('check')
+  .description('Scan a local directory or remote URL for accessibility issues')
+  .argument('<target>', 'Local directory path or remote URL')
+  .option('--mode <mode>', 'Scan mode: strict|balanced|learning|paranoid', 'balanced')
+  .option('-f, --format <format>', 'Output format: terminal|json|html|markdown|github', 'terminal')
+  .option('--output-format <format>', 'Alias for --format')
+  .option('-o, --output <path>', 'Output file path')
+  .option('--allow-unsafe-targets', 'Allow scanning localhost/private remote targets')
+  .option(
+    '--allowed-domains <domains>',
+    'Comma-separated domain allowlist for remote targets',
+    (val) =>
+      val
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+  )
+  .option('--max-redirects <count>', 'Maximum number of followed redirects for remote scans', '3')
+  .option('--block-sensitive-ports', 'Block remote targets using sensitive ports')
+  .option(
+    '--fail-on <severity>',
+    'Exit with code 1 when issues at or above this severity are found: critical|major|minor|info'
+  )
+  .option('--timeout <ms>', 'Page load timeout in milliseconds', '15000')
+  .option('--safe-report', 'Strip raw HTML snippets from rendered reports')
+  .option('--max-field-length <chars>', 'Maximum report field length before truncation', '5000')
+  .option('--report-url <url>', 'Link to the full report, shown by the github format')
+  .option('--progress', 'Show progress indicator for multi-page scans')
+  .option(
+    '--include-tags <tags>',
+    'Comma-separated axe tag names to include (e.g. wcag2a,wcag2aa)',
+    (val) =>
+      val
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+  )
+  .option('--exclude-rules <rules>', 'Comma-separated axe rule IDs to exclude', (val) =>
+    val
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+  )
+  .option(
+    '--baseline <file>',
+    'Known issues file: only issues missing from it count as new and can fail the run'
+  )
+  .option('--write-baseline <file>', 'Write the issues found by this scan to a baseline file')
+  .option(
+    '--sitemap [url]',
+    'For a URL target: scan the pages listed in the site sitemaps (robots.txt, /sitemap-index.xml, /sitemap.xml) or in the given sitemap'
+  )
+  .option('--max-pages <count>', 'Maximum number of pages scanned with --sitemap', '50')
+  .option('--lang <lang>', 'Language of issue texts and reports: en|fr', 'en')
+  .option('--no-keyboard', 'Skip the keyboard checks (focus visibility, keyboard traps, skip link)')
+  .action(async (target, options) => {
+    const mode = options.mode ?? 'balanced';
+    if (!isScanMode(mode)) {
+      exitWithError(`--mode must be one of ${SCAN_MODES.join('|')}, got: ${mode}`);
+    }
+    if (options.failOn !== undefined && !isSeverity(options.failOn)) {
+      exitWithError(`--fail-on must be one of ${SEVERITY_ORDER.join('|')}, got: ${options.failOn}`);
+    }
+    const paranoidMode = mode === 'paranoid';
+    const failThreshold = resolveFailThreshold({ mode, failOn: options.failOn });
+    const timeout = paranoidMode ? 8000 : parseInt(options.timeout, 10);
+    const maxRedirects = paranoidMode ? 0 : parseInt(options.maxRedirects, 10);
+    const maxFieldLength = parseInt(options.maxFieldLength, 10);
+    if (isNaN(timeout) || timeout <= 0) {
+      process.stderr.write(`Error: --timeout must be a positive number, got: ${options.timeout}\n`);
+      process.exit(1);
+    }
+    if (isNaN(maxRedirects) || maxRedirects < 0) {
+      process.stderr.write(
+        `Error: --max-redirects must be a non-negative number, got: ${options.maxRedirects}\n`
+      );
+      process.exit(1);
+    }
+    if (isNaN(maxFieldLength) || maxFieldLength <= 0) {
+      process.stderr.write(
+        `Error: --max-field-length must be a positive number, got: ${options.maxFieldLength}\n`
+      );
+      process.exit(1);
+    }
+    if (paranoidMode && options.allowUnsafeTargets) {
+      process.stderr.write('Error: --allow-unsafe-targets cannot be used with --mode paranoid\n');
+      process.exit(1);
+    }
+    const onProgress = options.progress
+      ? ({ current, total, route }) => {
+          process.stdout.write(`\rScanning ${current}/${total}: ${route}`);
+          if (current === total) process.stdout.write('\n');
+        }
+      : undefined;
+    if (!isSupportedLang(options.lang)) {
+      exitWithError(`--lang must be one of ${SUPPORTED_LANGS.join('|')}, got: ${options.lang}`);
+    }
+    const maxPages = parseInt(options.maxPages, 10);
+    if (isNaN(maxPages) || maxPages <= 0) {
+      exitWithError(`--max-pages must be a positive number, got: ${options.maxPages}`);
+    }
+    if (options.sitemap && !/^https?:\/\//i.test(target)) {
+      exitWithError(
+        '--sitemap only applies to URL targets; a build directory is crawled from its HTML files.'
+      );
+    }
+    let baseline;
+    if (options.baseline) {
+      try {
+        baseline = parseBaseline(await readFile(path.resolve(options.baseline), 'utf8'));
+      } catch (err) {
+        exitWithError(`could not read baseline ${options.baseline}: ${err.message}`);
+      }
+    }
+    const scanResult = await scanTarget(target, {
+      mode,
+      allowUnsafeTargets: paranoidMode ? false : options.allowUnsafeTargets,
+      allowedDomains: options.allowedDomains,
+      maxRedirects,
+      blockSensitivePorts: paranoidMode ? true : options.blockSensitivePorts,
+      enforceSandbox: paranoidMode,
+      timeout,
+      onProgress,
+      includeTags: options.includeTags,
+      excludeRules: options.excludeRules,
+      keyboard: options.keyboard,
+      lang: options.lang,
+      sitemap: Boolean(options.sitemap),
+      sitemapUrl: typeof options.sitemap === 'string' ? options.sitemap : undefined,
+      maxPages
+    });
+    const result = baseline ? applyBaseline(scanResult, baseline) : scanResult;
+    if (options.writeBaseline) {
+      await writeOutput(
+        options.writeBaseline,
+        JSON.stringify(createBaseline(scanResult), null, 2) + '\n'
+      );
+    }
+    const format = options.outputFormat ?? options.format;
+    const rendered = renderByFormat(result, format, {
+      safeReport: paranoidMode ? true : options.safeReport,
+      maxFieldLength,
+      reportUrl: options.reportUrl
+    });
+
+    if (options.output) {
+      await writeOutput(options.output, rendered);
+    } else {
+      process.stdout.write(rendered + '\n');
+    }
+
+    for (const pageError of result.pageErrors ?? []) {
+      process.stderr.write(`Warning: could not scan ${pageError.page}: ${pageError.message}\n`);
+    }
+    // A page that could not be scanned must not let a gated run pass silently.
+    if (failThreshold !== null && result.pageErrors?.length > 0) {
+      process.exit(1);
+    }
+    if (hasIssuesAtOrAbove(result.summary, failThreshold)) {
+      process.exit(1);
+    }
+  });
+
+program
+  .command('report')
+  .description('Generate a report from a previous scan JSON output')
+  .option('-i, --input <path>', 'Input JSON file path (required)')
+  .option('-f, --format <format>', 'Output format: terminal|json|html|markdown|github', 'html')
+  .option('--output-format <format>', 'Alias for --format')
+  .option('-o, --output <path>', 'Output file path')
+  .option('--safe-report', 'Strip raw HTML snippets from rendered reports')
+  .option('--max-field-length <chars>', 'Maximum report field length before truncation', '5000')
+  .option('--report-url <url>', 'Link to the full report, shown by the github format')
+  .action(async (options) => {
+    if (!options.input) {
+      process.stderr.write('Error: --input is required\n');
+      process.exit(1);
+    }
+    let result;
+    try {
+      result = JSON.parse(await readFile(path.resolve(options.input), 'utf8'));
+    } catch (err) {
+      process.stderr.write(`Error: could not parse input file: ${err.message}\n`);
+      process.exit(1);
+    }
+    const format = options.outputFormat ?? options.format;
+    const maxFieldLength = parseInt(options.maxFieldLength, 10);
+    if (isNaN(maxFieldLength) || maxFieldLength <= 0) {
+      process.stderr.write(
+        `Error: --max-field-length must be a positive number, got: ${options.maxFieldLength}\n`
+      );
+      process.exit(1);
+    }
+    const rendered = renderByFormat(result, format, {
+      safeReport: options.safeReport,
+      maxFieldLength,
+      reportUrl: options.reportUrl
+    });
+
+    if (options.output) {
+      await writeOutput(options.output, rendered);
+    } else {
+      process.stdout.write(rendered + '\n');
+    }
+  });
+
+program
+  .command('install-browser')
+  .description(
+    'Download the Chromium build used for scans (matches the bundled Playwright version)'
+  )
+  .option('--with-deps', 'Also install system dependencies (Linux, requires root)')
+  .action(async (options) => {
+    const code = await installChromium({ withDeps: options.withDeps === true });
+    process.exit(code);
+  });
+
+program.parse();

package/dist/output-path.js

@@ -0,0 +1,17 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export function resolveOutputPath(filePath, cwd = process.cwd()) {
+  const resolvedCwd = path.resolve(cwd);
+  const fullPath = path.resolve(resolvedCwd, filePath);
+  if (!fullPath.startsWith(resolvedCwd + path.sep) && fullPath !== resolvedCwd) {
+    throw new Error("Output path must be within current working directory.");
+  }
+  return fullPath;
+}
+
+export async function writeOutput(filePath, contents, cwd = process.cwd()) {
+  const fullPath = resolveOutputPath(filePath, cwd);
+  await mkdir(path.dirname(fullPath), { recursive: true });
+  await writeFile(fullPath, contents, "utf8");
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "astro-a11y",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Accessibility guardrails for Astro sites and static builds: axe-core scans with RGAA 4.1.2 mapping.",
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "rgaa",
+    "wcag",
+    "astro",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Stan Bouchet",
+  "homepage": "https://stan69000.github.io/astro-a11y/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Stan69000/astro-a11y.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/Stan69000/astro-a11y/issues"
+  },
+  "type": "module",
+  "main": "./dist/bin.js",
+  "bin": {
+    "astro-a11y": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "@astro-a11y/core": "0.2.0",
+    "@astro-a11y/reporters": "0.2.0"
+  },
+  "scripts": {
+    "build": "node ../../scripts/copy-package.js src dist"
+  }
 }