API programmatique d'Audit

En complément de la commande CLI, le point d’entrée @unschema-graph/core/audit exporte une API programmatique Node.js permettant d’auditer des chaînes de caractères HTML ou des dossiers de fichiers.

Importation

import {
  auditHtmlContent,
  auditHtmlDirectory,
  getHtmlFiles,
  type AuditResult,
  type AuditError,
} from '@unschema-graph/core/audit';

Auditer un dossier de build

La méthode auditHtmlDirectory permet d’inspecter l’intégralité d’un dossier de sortie :

import { auditHtmlDirectory } from '@unschema-graph/core/audit';

const result = auditHtmlDirectory('./dist');

console.log(`${result.scannedFiles} fichiers HTML scannés.`);
console.log(`${result.totalBlocks} blocs JSON-LD trouvés.`);
console.log(`${result.totalEntities} entités validées.`);

if (!result.passed) {
  console.error('Échec de l’audit avec les erreurs suivantes :');
  for (const error of result.errors) {
    console.error(`- [${error.file}] ${error.message}`);
  }
  process.exit(1);
}

Auditer des chaînes HTML brutes

La méthode auditHtmlContent est idéale pour valider le code HTML produit par vos composants dans des tests unitaires ou des suites Vitest :

import { auditHtmlContent } from '@unschema-graph/core/audit';
import { describe, expect, it } from 'vitest';

describe('Rendu HTML serveur', () => {
  it('contient un JSON-LD Schema.org conforme', () => {
    const html = `
      <!DOCTYPE html>
      <html>
        <head>
          <script type="application/ld+json">
            {
              "@context": "https://schema.org",
              "@type": "Article",
              "headline": "Mon article de test"
            }
          </script>
        </head>
        <body></body>
      </html>
    `;

    const result = auditHtmlContent(html, 'test-virtuel.html');
    expect(result.passed).toBe(true);
    expect(result.totalEntities).toBe(1);
    expect(result.errors).toHaveLength(0);
  });
});

Interfaces TypeScript

export interface AuditError {
  file: string;
  message: string;
}

export interface AuditResult {
  scannedFiles: number;
  totalBlocks: number;
  totalEntities: number;
  errors: AuditError[];
  passed: boolean;
}