Programmatic Audit API
In addition to the CLI, @unschema-graph/core/audit exposes a Node.js-based programmatic API for auditing HTML strings and directories.
Installation & Import
Section titled “Installation & Import”import { auditHtmlContent, auditHtmlDirectory, getHtmlFiles, type AuditContentResult, type AuditDiagnostic, type AuditDiagnosticCode, type AuditError, type AuditResult,} from '@unschema-graph/core/audit';Auditing a Directory
Section titled “Auditing a Directory”Use auditHtmlDirectory to scan an entire build directory:
import { auditHtmlDirectory } from '@unschema-graph/core/audit';
const report = auditHtmlDirectory('./dist');
console.log(`Scanned ${report.scannedFiles} HTML files.`);console.log(`Found ${report.totalBlocks} JSON-LD blocks.`);console.log(`Resolved ${report.resolvedLocalReferences} local graph references.`);console.log(`Found ${report.totalEntities} entities.`);
for (const warning of report.warnings) { console.warn(warning.code, warning.message);}
for (const error of report.errors) { console.error(error.code, error.message);}
if (!report.passed) { process.exit(1);}Result Semantics (passed vs --strict)
Section titled “Result Semantics (passed vs --strict)”- In the programmatic API,
report.passedistruewhen there are zero errors (errors.length === 0). Warnings do not causereport.passedto befalse. - In the CLI, the
--strictflag additionally treats warnings as failures (exiting with code1).
When a page contains a canonical link element, the audit uses its href URL to validate
fragment and absolute same-document @id references. An absolute reference to another path on
the same origin is treated as external to the current graph.
Without a canonical URL, only a fragment-only reference such as #organization can be proven to
target the current document. Path references such as /about#organization, ./page#thing, and
../page#thing are therefore not reported as locally broken.
Auditing Raw HTML Strings
Section titled “Auditing Raw HTML Strings”Use auditHtmlContent to validate an HTML string directly in unit tests or Vitest:
import { auditHtmlContent } from '@unschema-graph/core/audit';import { describe, expect, it } from 'vitest';
describe('Server-rendered HTML', () => { it('contains valid Schema.org JSON-LD', () => { const html = ` <!DOCTYPE html> <html> <head> <script type="application/ld+json"> { "@context": "https://schema.org", "@type": "Article", "headline": "Test article" } </script> </head> <body></body> </html> `;
const result = auditHtmlContent(html, 'virtual-test.html'); expect(result.entities).toBe(1); expect(result.blocks).toBe(1); expect(result.resolvedLocalReferences).toBe(0); expect(result.errors).toHaveLength(0); expect(result.warnings).toHaveLength(0); });});TypeScript Interfaces
Section titled “TypeScript Interfaces”The following types and interfaces are exported by @unschema-graph/core/audit:
export type AuditDiagnosticCode = | 'empty-script' | 'invalid-json' | 'invalid-root' | 'missing-context' | 'invalid-graph' | 'missing-type' | 'broken-reference' | 'duplicate-id' | 'duplicate-conflict' | 'no-html' | 'no-jsonld';
export interface AuditDiagnostic { code: AuditDiagnosticCode; severity: 'warning' | 'error'; file: string; message: string; path?: string; id?: string;}
export type AuditError = AuditDiagnostic;
export interface AuditResult { scannedFiles: number; totalBlocks: number; totalEntities: number; resolvedLocalReferences: number; errors: AuditError[]; warnings: AuditDiagnostic[]; passed: boolean;}
export interface AuditContentResult { blocks: number; entities: number; resolvedLocalReferences: number; errors: AuditError[]; warnings: AuditDiagnostic[];}