Aller au contenu

Audit CLI & CI/CD

unschema-graph intègre un outil d’audit en ligne de commande pour contrôler vos dossiers de compilation statique (ex. dist/ ou build/) avant toute mise en production.


Après la génération de votre site, lancez la commande d’audit :

pnpm

Fenêtre de terminal
pnpm exec unschema-graph audit dist

npm / npx

Fenêtre de terminal
npx @unschema-graph/core audit dist

yarn

Fenêtre de terminal
yarn unschema-graph audit dist

bun

Fenêtre de terminal
bunx @unschema-graph/core audit dist

Vous pouvez cibler n’importe quel dossier de sortie :

Fenêtre de terminal
npx @unschema-graph/core audit ./build

Conservez la même séquence partout :

  • Contrôle local : compiler le site, puis auditer son dossier de sortie.
  • Build de production : lancer l’audit juste après le build et avant le déploiement.
  • CI : séparer les étapes de build et d’audit pour localiser rapidement un échec.

Options utiles :

Fenêtre de terminal
# Traite les avertissements d’ID dupliqué comme des échecs
npx @unschema-graph/core audit dist --strict
# Produit un rapport stable exploitable par une machine
npx @unschema-graph/core audit dist --format json

Dans le dépôt unschema-graph, les scripts racine séparent volontairement les deux modes :

  • pnpm run audit facilite le développement local : il signale les avertissements sans échouer.
  • pnpm run audit:strict est utilisé par la CI et pnpm run release:check : tout avertissement ou toute erreur bloque la vérification.

Le moteur d’audit effectue un contrôle structurel et d’intégrité de graphe sur tous les fichiers générés :

  1. Découverte récursive des fichiers HTML : Analyse l’ensemble des dossiers pour identifier chaque fichier .html.
  2. Détection des blocs de script : Détecte les balises <script type="application/ld+json"> dans les fichiers HTML découverts.
  3. Validation syntaxique JSON : Vérifie que chaque bloc est un JSON valide et complet sans erreur de parsing.
  4. Présence du contexte racine : Contrôle la présence de la propriété requise @context.
  5. Présence de @type sur les nœuds : Vérifie que les entités racine et les nœuds du tableau @graph déclarent une propriété @type.
  6. Intégrité de la structure de graphe : Détecte les structures de graphe malformées (ex. propriété @graph non-tableau).
  7. Résolution des références locales : Détecte les références locales cassées (#id ou URIs du même document).
  8. Détection des identifiants et conflits : Identifie les doublons d’identifiants (@id) et les valeurs conflictuelles pour un même ID.
  9. Rapports déterministes : Émet des diagnostics structurés avec chemins de fichiers exacts, codes d’erreur et niveaux de sévérité.
  10. Mode strict : Prend en charge un mode transformant les avertissements en erreurs (--strict) pour la CI et les contrôles de publication.

L’audit est intentionnellement centré sur la structure du JSON-LD et l’intégrité du graphe. Comme précisé dans la page Limites connues, l’audit ne garantit pas :

  • Une validation sémantique complète de tout le vocabulaire ou des types de propriétés Schema.org.
  • Une conformité syntaxique HTML complète ou un parsing DOM complet.
  • L’éligibilité aux Google Rich Results ou l’affichage dans les moteurs de recherche.
  • L’accessibilité réseau des URLs externes.

  • 0 (Succès) : Aucune erreur ; les avertissements restent autorisés sans --strict.
  • 1 (Échec d’audit) : JSON-LD invalide, référence cassée, conflit d’ID, absence de HTML/JSON-LD, ou avertissement avec --strict.
  • 2 (Erreur d’utilisation) : Option inconnue, format invalide ou argument positionnel en trop.

Une exécution réussie se termine par un récapitulatif des fichiers HTML, blocs JSON-LD et entités analysés, puis un message de succès. Les nombres exacts dépendent du site :

✓ 24 HTML files scanned
✓ 18 JSON-LD blocks parsed
✓ 7 local graph references resolved
✓ 42 Schema.org entities found

En cas d’échec, le rapport nomme le fichier concerné et décrit le bloc ou le graphe incorrect. Pour les scripts et la CI, le contrat stable est le code de sortie, pas le texte d’exemple ci-dessus.


Ajoutez un script post-build automatique :

package.json
{
"scripts": {
"build": "astro build",
"postbuild": "unschema-graph audit dist"
}
}

Intégrez la vérification dans votre pipeline d’intégration continue :

.github/workflows/ci.yml
name: CI & Audit Schema
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build-and-audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: 'pnpm'
- run: pnpm install --frozen-lockfile
- run: pnpm run build
- name: Audit Schema.org JSON-LD
run: npx @unschema-graph/core audit dist --strict