npm package: @idirdev/a11y-check
Description: Check HTML content for accessibility issues
Author: idirdev
Latest version: 1.0.0

# a11y-check

> **[EN]** Static HTML accessibility auditor — detect missing alt text, unlabeled inputs, broken heading order, empty links, and more — zero browser required.
> **[FR]** Auditeur d'accessibilité HTML statique — détectez les attributs alt manquants, les inputs sans label, les niveaux de titres incorrects, les liens vides et plus encore — aucun navigateur requis.

---

## Features / Fonctionnalités

**[EN]**
- Detects missing `alt` attributes on `<img>` elements (WCAG 1.1.1)
- Checks `<html>` element for missing `lang` attribute (WCAG 3.1.1)
- Audits `<input>` elements for associated `<label>` or `aria-label` (WCAG 1.3.1)
- Validates heading order (no skipping from h1 to h3, etc.) (WCAG 1.3.1)
- Finds anchor tags with no text content and no `aria-label`
- Warns on missing or restrictive `viewport` meta tag
- Flags potentially low-contrast inline color values
- Severity levels: `error`, `warn`, `info`
- `--json` flag for machine-readable output in CI pipelines
- Exits with code 1 if any `error`-severity issues are found

**[FR]**
- Détecte les attributs `alt` manquants sur les éléments `<img>` (WCAG 1.1.1)
- Vérifie l'attribut `lang` manquant sur l'élément `<html>` (WCAG 3.1.1)
- Audite les éléments `<input>` pour les `<label>` ou `aria-label` associés (WCAG 1.3.1)
- Valide l'ordre des titres (pas de saut de h1 à h3, etc.) (WCAG 1.3.1)
- Trouve les balises anchor sans texte et sans `aria-label`
- Avertit sur les balises `viewport` meta manquantes ou restrictives
- Signale les valeurs de couleur inline potentiellement à faible contraste
- Niveaux de sévérité : `error`, `warn`, `info`
- Flag `--json` pour une sortie lisible par machine dans les pipelines CI
- Quitte avec le code 1 si des problèmes de sévérité `error` sont trouvés

---

## Installation

```bash
npm install -g @idirdev/a11y-check
```

---

## CLI Usage / Utilisation CLI

```bash
# Audit a local HTML file
# Auditer un fichier HTML local
a11y-check index.html

# Audit a specific page
# Auditer une page spécifique
a11y-check ./dist/about.html

# Output JSON for CI tooling
# Retourner JSON pour les outils CI
a11y-check index.html --json

# Use in a CI pipeline — fails on errors
# Utiliser dans un pipeline CI — échoue sur les erreurs
a11y-check ./dist/index.html || exit 1

# Audit multiple files in a loop
# Auditer plusieurs fichiers en boucle
for f in dist/*.html; do a11y-check "$f"; done
```

### Example Output / Exemple de sortie

```
$ a11y-check index.html
5 issue(s):
[ERROR] img-alt: Image missing alt attribute
[ERROR] form-label: Input missing associated label
[ERROR] html-lang: html element missing lang attribute
[WARN] heading-order: Heading level skipped from h2 to h4
[WARN] link-text: Link has no text content

$ a11y-check clean.html
No accessibility issues found
```

---

## API (Programmatic) / API (Programmation)

```js
const { checkHtml, checkFile, formatResults, RULES } = require('@idirdev/a11y-check');

// Check an HTML string directly
// Vérifier une chaîne HTML directement
const html = `
  <html>
    <body>
      <img src="logo.png">
      <a href="/home"></a>
      <input type="text" id="username">
    </body>
  </html>
`;

const issues = checkHtml(html);
// => [
//   { rule: 'img-alt',   severity: 'error', tag: '<img src="logo.png">', msg: 'Image missing alt attribute' },
//   { rule: 'html-lang', severity: 'error', tag: '<html>',               msg: 'html element missing lang attribute' },
//   { rule: 'form-label',severity: 'error', tag: '<input type="text"...', msg: 'Input missing associated label' },
//   { rule: 'link-text', severity: 'warn',  tag: '<a href="/home"></a>',  msg: 'Link has no text content' }
// ]

// Check only specific rules
// Vérifier seulement des règles spécifiques
checkHtml(html, { rules: ['img-alt', 'html-lang'] });

// Check a file on disk
// Vérifier un fichier sur disque
const fileIssues = checkFile('./dist/index.html');

// Format results as human-readable lines
// Formater les résultats en lignes lisibles
console.log(formatResults(issues));
// [ERROR] img-alt: Image missing alt attribute
// [ERROR] html-lang: html element missing lang attribute
// [ERROR] form-label: Input missing associated label
// [WARN] link-text: Link has no text content

// Inspect available rules
// Inspecter les règles disponibles
RULES.forEach(r => console.log(r.id, '-', r.severity));
// img-alt - error
// html-lang - error
// form-label - error
// heading-order - warn
// link-text - warn
// meta-viewport - warn
// contrast-placeholder - info
```

---

## License

MIT © idirdev