@growth-labs/conformance 0.1.0

package/src/schema.ts

@@ -0,0 +1,165 @@
+import { z } from 'zod'
+
+export const EVIDENCE_SCHEMA_VERSION = 'growth-labs.conformance.v1'
+
+export const REQUIRED_NEGATIVE_FIXTURE_CODES = {
+	'csp-unsafe-inline': 'security.csp.unsafe_inline',
+	'headers-static-only-while-ssr-missing': 'security.headers.static_only_for_ssr',
+	'undeclared-na': 'publication.na.undeclared',
+	'stringified-is-accessible-for-free': 'structured_data.is_accessible_for_free.stringified',
+	'video-object-date-only-upload-date': 'structured_data.video_object.upload_date.date_only',
+	'missing-image-dimensions': 'images.dimensions.missing',
+	'hero-under-1200px': 'images.hero.under_1200',
+	'missing-max-image-preview-large': 'metadata.robots.missing_max_image_preview_large',
+	'crawler-public-cache-key-collision': 'cache.crawler_public_key_collision',
+	'runtime-canonical-override-not-applied': 'metadata.canonical.runtime_override_not_applied',
+} as const
+
+export type RequiredNegativeFixtureId = keyof typeof REQUIRED_NEGATIVE_FIXTURE_CODES
+export type RequiredNegativeFindingCode =
+	(typeof REQUIRED_NEGATIVE_FIXTURE_CODES)[RequiredNegativeFixtureId]
+
+export const audienceSchema = z.enum([
+	'public',
+	'crawler',
+	'subscriber',
+	'member',
+	'admin',
+	'private',
+])
+export const renderModeSchema = z.enum(['ssr', 'static'])
+export const checkStatusSchema = z.enum(['pass', 'fail', 'na'])
+export const findingSeveritySchema = z.enum(['error', 'warning'])
+
+export const headerValueSchema = z.union([z.string(), z.array(z.string())])
+export const headerMapSchema = z.record(headerValueSchema)
+
+export const surfaceResponseSchema = z.object({
+	status: z.number().int().min(100).max(599).default(200),
+	url: z.string().url().optional(),
+	headers: headerMapSchema.default({}),
+	html: z.string().optional(),
+	body: z.string().optional(),
+})
+
+export const publicationSurfaceSchema = z.object({
+	name: z.string().min(1),
+	status: z.enum(['present', 'missing', 'na']),
+	url: z.string().url().optional(),
+	httpStatus: z.number().int().min(100).max(599).optional(),
+	contentType: z.string().min(1).optional(),
+	bodyBytes: z.number().int().nonnegative().optional(),
+	capabilityBoundary: z.string().min(1).optional(),
+	evidence: z.string().min(1).optional(),
+})
+
+export const cacheVariantSchema = z.object({
+	audience: audienceSchema,
+	cacheKey: z.string().min(1),
+	url: z.string().url().optional(),
+	contentClass: z.enum(['html', 'markdown', 'feed', 'asset']).default('html'),
+	vary: z.array(z.string().min(1)).default([]),
+	headers: headerMapSchema.default({}),
+})
+
+export const buildEvidenceSchema = z.object({
+	commitSha: z.string().min(7).optional(),
+	artifactId: z.string().min(1).optional(),
+	generatedAt: z.string().min(1).optional(),
+	packageVersions: z.record(z.string().min(1)).default({}),
+	staticHeaderPolicy: z.boolean().default(false),
+	ssrHeaderPolicy: z.boolean().default(false),
+})
+
+export const conformanceExpectedSchema = z.object({
+	canonicalUrl: z.string().url().optional(),
+	schemaTypes: z.array(z.string().min(1)).default([]),
+	discoverEligible: z.boolean().default(true),
+})
+
+export const conformanceFixtureSchema = z.object({
+	id: z.string().min(1),
+	site: z.string().min(1),
+	environment: z.string().min(1).default('production'),
+	url: z.string().url(),
+	renderMode: renderModeSchema,
+	audience: audienceSchema,
+	response: surfaceResponseSchema,
+	expected: conformanceExpectedSchema.default({}),
+	publicationSurfaces: z.array(publicationSurfaceSchema).default([]),
+	cacheVariants: z.array(cacheVariantSchema).default([]),
+	buildEvidence: buildEvidenceSchema.optional(),
+	expectedFailingCode: z.string().min(1).optional(),
+})
+
+export const conformanceFindingSchema = z.object({
+	code: z.string().min(1),
+	severity: findingSeveritySchema,
+	message: z.string().min(1),
+	path: z.string().min(1).optional(),
+	evidence: z.string().min(1).optional(),
+	remediation: z.string().min(1).optional(),
+})
+
+export const conformanceCheckReceiptSchema = z.object({
+	name: z.string().min(1),
+	status: checkStatusSchema,
+	findings: z.array(conformanceFindingSchema),
+})
+
+export const evidenceSummarySchema = z.object({
+	pass: z.number().int().nonnegative(),
+	fail: z.number().int().nonnegative(),
+	na: z.number().int().nonnegative(),
+	findings: z.number().int().nonnegative(),
+})
+
+export const siteEvidenceBundleSchema = z.object({
+	schemaVersion: z.literal(EVIDENCE_SCHEMA_VERSION),
+	generatedAt: z.string().min(1),
+	fixtureId: z.string().min(1),
+	site: z.string().min(1),
+	environment: z.string().min(1),
+	url: z.string().url(),
+	status: z.enum(['pass', 'fail']),
+	summary: evidenceSummarySchema,
+	checks: z.array(conformanceCheckReceiptSchema),
+	findings: z.array(conformanceFindingSchema),
+})
+
+export const fleetEvidenceBundleSchema = z.object({
+	schemaVersion: z.literal(EVIDENCE_SCHEMA_VERSION),
+	generatedAt: z.string().min(1),
+	status: z.enum(['pass', 'fail']),
+	summary: evidenceSummarySchema.extend({
+		sites: z.number().int().nonnegative(),
+	}),
+	sites: z.array(siteEvidenceBundleSchema),
+})
+
+export type Audience = z.infer<typeof audienceSchema>
+export type RenderMode = z.infer<typeof renderModeSchema>
+export type HeaderMap = z.infer<typeof headerMapSchema>
+export type SurfaceResponse = z.infer<typeof surfaceResponseSchema>
+export type PublicationSurfaceEvidence = z.infer<typeof publicationSurfaceSchema>
+export type CacheVariant = z.infer<typeof cacheVariantSchema>
+export type BuildEvidence = z.infer<typeof buildEvidenceSchema>
+export type ConformanceFixtureInput = z.input<typeof conformanceFixtureSchema>
+export type ConformanceFixture = z.infer<typeof conformanceFixtureSchema>
+export type ConformanceFinding = z.infer<typeof conformanceFindingSchema>
+export type ConformanceCheckReceipt = z.infer<typeof conformanceCheckReceiptSchema>
+export type EvidenceSummary = z.infer<typeof evidenceSummarySchema>
+export type SiteEvidenceBundle = z.infer<typeof siteEvidenceBundleSchema>
+export type FleetEvidenceBundle = z.infer<typeof fleetEvidenceBundleSchema>
+
+export function parseConformanceFixture(input: unknown): ConformanceFixture {
+	return conformanceFixtureSchema.parse(input)
+}
+
+export function validateSiteEvidenceBundle(input: unknown): SiteEvidenceBundle {
+	return siteEvidenceBundleSchema.parse(input)
+}
+
+export function validateFleetEvidenceBundle(input: unknown): FleetEvidenceBundle {
+	return fleetEvidenceBundleSchema.parse(input)
+}