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.
1. Exécuter l’audit
Section intitulée « 1. Exécuter l’audit »Après la génération de votre site, lancez la commande d’audit :
pnpm
pnpm exec unschema-graph audit distnpm / npx
npx @unschema-graph/core audit distyarn
yarn unschema-graph audit distbun
bunx @unschema-graph/core audit distVous pouvez cibler n’importe quel dossier de sortie :
npx @unschema-graph/core audit ./buildConservez 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 :
# Traite les avertissements d’ID dupliqué comme des échecsnpx @unschema-graph/core audit dist --strict
# Produit un rapport stable exploitable par une machinenpx @unschema-graph/core audit dist --format jsonDans le dépôt unschema-graph, les scripts racine séparent volontairement les deux modes :
pnpm run auditfacilite le développement local : il signale les avertissements sans échouer.pnpm run audit:strictest utilisé par la CI etpnpm run release:check: tout avertissement ou toute erreur bloque la vérification.
2. Vérifications effectuées
Section intitulée « 2. Vérifications effectuées »Le moteur d’audit effectue un contrôle structurel et d’intégrité de graphe sur tous les fichiers générés :
- Découverte récursive des fichiers HTML : Analyse l’ensemble des dossiers pour identifier chaque fichier
.html. - Détection des blocs de script : Détecte les balises
<script type="application/ld+json">dans les fichiers HTML découverts. - Validation syntaxique JSON : Vérifie que chaque bloc est un JSON valide et complet sans erreur de parsing.
- Présence du contexte racine : Contrôle la présence de la propriété requise
@context. - Présence de @type sur les nœuds : Vérifie que les entités racine et les nœuds du tableau
@graphdéclarent une propriété@type. - Intégrité de la structure de graphe : Détecte les structures de graphe malformées (ex. propriété
@graphnon-tableau). - Résolution des références locales : Détecte les références locales cassées (
#idou URIs du même document). - Détection des identifiants et conflits : Identifie les doublons d’identifiants (
@id) et les valeurs conflictuelles pour un même ID. - Rapports déterministes : Émet des diagnostics structurés avec chemins de fichiers exacts, codes d’erreur et niveaux de sévérité.
- Mode strict : Prend en charge un mode transformant les avertissements en erreurs (
--strict) pour la CI et les contrôles de publication.
Limites et non-objectifs explicites
Section intitulée « Limites et non-objectifs explicites »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.
3. Codes de sortie
Section intitulée « 3. Codes de sortie »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.
Sortie attendue
Section intitulée « Sortie attendue »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 foundEn 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.
4. Intégration continue (CI/CD)
Section intitulée « 4. Intégration continue (CI/CD) »Dans package.json
Section intitulée « Dans package.json »Ajoutez un script post-build automatique :
{ "scripts": { "build": "astro build", "postbuild": "unschema-graph audit dist" }}Workflow GitHub Actions
Section intitulée « Workflow GitHub Actions »Intégrez la vérification dans votre pipeline d’intégration continue :
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