From 6f5998fa9b869232d2fafc613b3f3504cb39f23f Mon Sep 17 00:00:00 2001 From: Maanil Verma Date: Mon, 5 Oct 2026 21:06:19 +0530 Subject: [PATCH 1/8] test(website): enforce per-type structured-data rules in validate-jsonld --- apps/website/scripts/validate-jsonld.test.ts | 167 +++++++++ apps/website/scripts/validate-jsonld.ts | 350 +++++++++++++++---- 2 files changed, 447 insertions(+), 70 deletions(-) create mode 100644 apps/website/scripts/validate-jsonld.test.ts diff --git a/apps/website/scripts/validate-jsonld.test.ts b/apps/website/scripts/validate-jsonld.test.ts new file mode 100644 index 00000000000..66689ca0811 --- /dev/null +++ b/apps/website/scripts/validate-jsonld.test.ts @@ -0,0 +1,167 @@ +import { describe, expect, it } from 'vitest' + +import { validateHtml } from './validate-jsonld' + +const site = 'https://comfy.org' +const canonical = `${site}/example/` +const org = { + '@type': 'Organization', + '@id': `${site}/#organization`, + name: 'Comfy Org' +} +const webPage = { + '@type': 'WebPage', + '@id': `${canonical}#webpage`, + url: canonical, + name: 'Example' +} + +function html(nodes: object[], pageCanonical = canonical): string { + const graph = { '@context': 'https://schema.org', '@graph': nodes } + return `` +} + +function rulesHit(nodes: object[], pagePath = '/example/'): string[] { + return validateHtml(html([org, webPage, ...nodes]), pagePath).map( + ({ rule }) => rule + ) +} + +const offer = (price: unknown) => ({ + '@type': 'Offer', + price, + priceCurrency: 'USD' +}) +const product = { + '@type': 'Product', + '@id': `${canonical}#product`, + name: 'Comfy Cloud', + image: `${site}/og.webp`, + brand: { '@id': org['@id'] }, + offers: [offer('20')] +} +const video = { + '@type': 'VideoObject', + '@id': `${canonical}#video`, + name: 'Tutorial', + thumbnailUrl: `${site}/thumb.webp`, + uploadDate: '2026-07-16T00:00:00+00:00' +} +const crumbs = (items: object[]) => ({ + '@type': 'BreadcrumbList', + '@id': `${canonical}#breadcrumb`, + itemListElement: items +}) + +describe('validateHtml', () => { + it.for([ + { rule: 'honesty', bad: { '@type': 'AggregateRating', ratingValue: 5 } }, + { rule: 'honesty', bad: { ...product, review: [] } }, + { rule: 'offer', bad: offer('') }, + { rule: 'offer', bad: { '@type': 'Offer', price: '5' } }, + { rule: 'product', bad: { ...product, image: undefined } }, + { rule: 'product', bad: { ...product, brand: { name: 'Comfy' } } }, + { rule: 'video', bad: { ...video, uploadDate: '2026-07-16' } }, + { rule: 'video', bad: { ...video, uploadDate: undefined } }, + { rule: 'video', bad: { ...video, thumbnailUrl: undefined } }, + { + rule: 'event', + bad: { '@type': 'Event', name: 'Meetup', startDate: '2026-10-07T10:00' } + }, + { rule: 'imagesAreImages', bad: { ...product, image: `${site}/a.mp4` } }, + { + rule: 'imagesAreImages', + bad: { ...video, thumbnailUrl: `${site}/a.webm` } + }, + { + rule: 'imagesAreImages', + bad: { '@type': 'ImageObject', contentUrl: `${site}/a.mov?v=1` } + }, + { + rule: 'breadcrumb', + bad: crumbs([ + { '@type': 'ListItem', position: 1, name: 'Home', item: `${site}/` }, + { '@type': 'ListItem', position: 3, name: 'Page' } + ]) + }, + { + rule: 'breadcrumb', + bad: crumbs([ + { '@type': 'ListItem', position: 1, name: 'Home', item: '/' }, + { '@type': 'ListItem', position: 2, name: 'Page' } + ]) + }, + { + rule: 'itemList', + bad: { + '@type': 'ItemList', + numberOfItems: 2, + itemListElement: [{ '@type': 'ListItem', position: 1, url: canonical }] + } + }, + { rule: 'idsOnSite', bad: { ...video, '@id': '/example/#video' } }, + { rule: 'noPlaceholders', bad: { ...video, name: 'undefined' } }, + { rule: 'noPlaceholders', bad: { ...video, description: ' ' } }, + { + rule: 'idRefs', + bad: { ...video, isPartOf: { '@id': `${site}/#missing` } } + }, + { rule: 'duplicateIds', bad: { ...webPage, name: 'Again' } } + ])('flags $rule', ({ rule, bad }) => { + expect(rulesHit([bad])).toContain(rule) + }) + + it('passes a complete graph', () => { + expect( + rulesHit([ + product, + video, + { '@type': 'Event', name: 'All day', startDate: '2026-10-06' }, + { + '@type': 'Event', + name: 'Talk', + startDate: '2026-10-07T10:00:00-07:00' + }, + { '@type': 'ImageObject', url: `${site}/a.webp` }, + crumbs([ + { '@type': 'ListItem', position: 1, name: 'Home', item: `${site}/` }, + { '@type': 'ListItem', position: 2, name: 'Page' } + ]), + { + '@type': 'ItemList', + numberOfItems: 1, + itemListElement: [ + { '@type': 'ListItem', position: 1, url: canonical } + ] + } + ]) + ).toEqual([]) + }) + + it('accepts a typed Brand inline on a Product', () => { + expect( + rulesHit([{ ...product, brand: { '@type': 'Brand', name: 'Comfy' } }]) + ).toEqual([]) + }) + + it('allows a free Offer outside model pages but not on them', () => { + expect(rulesHit([offer(0)], '/download/')).toEqual([]) + expect(rulesHit([offer('0.00')], '/hub/models/luma-photon-flash/')).toEqual( + ['offer'] + ) + expect(rulesHit([offer('0.01')], '/hub/models/luma-photon-flash/')).toEqual( + [] + ) + }) + + it('flags a WebPage whose @id or url drifts from the canonical', () => { + const violations = validateHtml(html([org, webPage], `${site}/other/`), '/') + expect(violations.map(({ rule }) => rule)).toEqual(['webPage', 'webPage']) + }) + + it('reports unparseable JSON-LD', () => { + expect( + validateHtml('', '/') + ).toMatchObject([{ rule: 'json' }]) + }) +}) diff --git a/apps/website/scripts/validate-jsonld.ts b/apps/website/scripts/validate-jsonld.ts index 5dbdfa3c47e..d02ca02ad8a 100644 --- a/apps/website/scripts/validate-jsonld.ts +++ b/apps/website/scripts/validate-jsonld.ts @@ -1,25 +1,43 @@ import { readFileSync, readdirSync } from 'node:fs' -import { join } from 'node:path' +import { join, relative, sep } from 'node:path' import { collectGraphIds } from '@/utils/jsonLd' -const DIST_DIR = join(process.cwd(), 'dist') +import { isDirectExecution } from './script-entry-point' + +const SITE_ORIGIN = 'https://comfy.org' const JSON_LD_BLOCK = /]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi +const CANONICAL = /]*rel=["']canonical["'][^>]*href=["']([^"']+)["']/i +const FULL_DATE_TIME = + /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?([+-]\d{2}:\d{2}|Z)$/ +const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/ +const VIDEO_FILE = /\.(mp4|webm|mov)(\?|#|$)/i +const PLACEHOLDER = /^(undefined|null|NaN)$/ +const WEB_PAGE_TYPES = [ + 'WebPage', + 'AboutPage', + 'ContactPage', + 'CollectionPage', + 'ProfilePage' +] -interface Violation { - file: string - message: string +type JsonLdRecord = Record + +interface PageContext { + pagePath: string + canonical: string | undefined + nodesById: Map } -function htmlFiles(dir: string): string[] { - return readdirSync(dir, { recursive: true }) - .map(String) - .filter((entry) => entry.endsWith('.html')) - .map((entry) => join(dir, entry)) +export interface Violation { + rule: string + message: string } -function typesOf(node: Record): string[] { +type Rule = (node: JsonLdRecord, page: PageContext) => string[] + +function typesOf(node: JsonLdRecord): string[] { const type = node['@type'] if (typeof type === 'string') return [type] if (Array.isArray(type)) { @@ -28,95 +46,287 @@ function typesOf(node: Record): string[] { return [] } -function hasValidPrice(node: Record): boolean { - const price = node.price - const priceStr = price == null ? '' : String(price).trim() - return priceStr !== '' && !Number.isNaN(Number(priceStr)) +function isRecord(value: unknown): value is JsonLdRecord { + return Boolean(value) && typeof value === 'object' && !Array.isArray(value) } -function checkHonesty( - value: unknown, - file: string, - violations: Violation[] -): void { - const walk = (node: unknown): void => { - if (Array.isArray(node)) { - node.forEach(walk) - return - } - if (!node || typeof node !== 'object') return - const record = node as Record - const types = typesOf(record) - if (types.includes('Review') || types.includes('AggregateRating')) { - violations.push({ - file, - message: `dishonest node type ${types.join('/')}` - }) - } - if ('aggregateRating' in record || 'review' in record) { - violations.push({ - file, - message: 'node carries a review/aggregateRating' - }) +function asList(value: unknown): unknown[] { + if (value == null) return [] + return Array.isArray(value) ? value : [value] +} + +function isBlank(value: unknown): boolean { + return value == null || (typeof value === 'string' && value.trim() === '') +} + +function isAbsoluteHttpUrl(value: unknown): boolean { + return typeof value === 'string' && /^https?:\/\/[^/]/.test(value) +} + +function missing(node: JsonLdRecord, fields: string[]): string[] { + const type = typesOf(node).join('/') + return fields + .filter((field) => isBlank(node[field])) + .map((field) => `${type} missing ${field}`) +} + +function resolve(value: unknown, page: PageContext): JsonLdRecord | undefined { + if (!isRecord(value)) return undefined + const id = value['@id'] + if (typeof id === 'string' && Object.keys(value).length === 1) { + return page.nodesById.get(id) + } + return value +} + +function isModelPage(pagePath: string): boolean { + return /^\/(hub\/)?models\/[^/]+\//.test(pagePath) +} + +const honesty: Rule = (node) => { + const types = typesOf(node) + const problems: string[] = [] + if (types.includes('Review') || types.includes('AggregateRating')) { + problems.push(`dishonest node type ${types.join('/')}`) + } + if ('aggregateRating' in node || 'review' in node) { + problems.push('node carries a review/aggregateRating') + } + return problems +} + +const offer: Rule = (node, page) => { + if (!typesOf(node).includes('Offer')) return [] + const price = isBlank(node.price) ? NaN : Number(String(node.price).trim()) + if (Number.isNaN(price) || isBlank(node.priceCurrency)) { + return ['Offer missing priceCurrency or a concrete price'] + } + if (isModelPage(page.pagePath) && price <= 0) { + return [`model page Offer has a non-positive price ${String(node.price)}`] + } + return [] +} + +const product: Rule = (node, page) => { + if (!typesOf(node).includes('Product')) return [] + const problems = missing(node, ['name', 'image', 'offers']) + const brand = resolve(node.brand, page) + const brandTypes = brand ? typesOf(brand) : [] + if (!brandTypes.some((type) => type === 'Brand' || type === 'Organization')) { + problems.push('Product brand is not a Brand or Organization') + } + return problems +} + +const video: Rule = (node) => { + if (!typesOf(node).includes('VideoObject')) return [] + const problems = missing(node, ['name', 'thumbnailUrl', 'uploadDate']) + const { uploadDate } = node + if (!isBlank(uploadDate) && !FULL_DATE_TIME.test(String(uploadDate))) { + problems.push( + `VideoObject uploadDate ${String(uploadDate)} lacks a time and offset` + ) + } + return problems +} + +const event: Rule = (node) => { + if (!typesOf(node).includes('Event')) return [] + const startDate = String(node.startDate ?? '') + return DATE_ONLY.test(startDate) || FULL_DATE_TIME.test(startDate) + ? [] + : [ + `Event startDate ${startDate || '(missing)'} is not ISO 8601 with offset` + ] +} + +const imagesAreImages: Rule = (node) => { + const isImageObject = typesOf(node).includes('ImageObject') + const urls = [ + ...asList(node.image), + ...asList(node.thumbnailUrl), + ...(isImageObject ? [node.url, node.contentUrl] : []) + ].filter((url): url is string => typeof url === 'string') + return urls + .filter((url) => VIDEO_FILE.test(url)) + .map((url) => `video file used as an image: ${url}`) +} + +const breadcrumb: Rule = (node) => { + if (!typesOf(node).includes('BreadcrumbList')) return [] + const items = asList(node.itemListElement).filter(isRecord) + return items.flatMap((item, index) => { + const problems: string[] = [] + if (item.position !== index + 1) { + problems.push( + `BreadcrumbList item ${index + 1} has position ${String(item.position)}` + ) } - if ( - types.includes('Offer') && - (!hasValidPrice(record) || !record.priceCurrency) - ) { - violations.push({ - file, - message: 'Offer missing priceCurrency or a concrete price' - }) + const isLast = index === items.length - 1 + if (!isLast && !isAbsoluteHttpUrl(item.item)) { + problems.push(`BreadcrumbList item ${index + 1} has no absolute item URL`) } - Object.values(record).forEach(walk) + return problems + }) +} + +const itemList: Rule = (node) => { + if (!typesOf(node).includes('ItemList') || !('numberOfItems' in node)) { + return [] } - walk(value) + const count = asList(node.itemListElement).length + return node.numberOfItems === count + ? [] + : [ + `ItemList numberOfItems ${String(node.numberOfItems)} but ${count} listed` + ] } -function validateFile(file: string): Violation[] { - const html = readFileSync(file, 'utf8') - const violations: Violation[] = [] - const definedIds = new Set() - const referencedIds: string[] = [] +const webPage: Rule = (node, page) => { + const id = node['@id'] + const isPageNode = + typesOf(node).some((type) => WEB_PAGE_TYPES.includes(type)) && + typeof id === 'string' && + id.endsWith('#webpage') + if (!isPageNode || !page.canonical) return [] + const problems: string[] = [] + if (id !== `${page.canonical}#webpage`) { + problems.push(`WebPage @id ${id} does not match canonical`) + } + if (node.url !== page.canonical) { + problems.push(`WebPage url ${String(node.url)} does not match canonical`) + } + return problems +} + +const idsOnSite: Rule = (node) => { + const id = node['@id'] + if (typeof id !== 'string') return [] + return id.startsWith(`${SITE_ORIGIN}/`) + ? [] + : [`@id ${id} is not an absolute ${SITE_ORIGIN} URL`] +} + +const noPlaceholders: Rule = (node) => + Object.entries(node) + .filter( + ([, value]) => + typeof value === 'string' && + (value.trim() === '' || PLACEHOLDER.test(value.trim())) + ) + .map(([key, value]) => `${key} is ${JSON.stringify(value)}`) + +const RULES: Record = { + honesty, + offer, + product, + video, + event, + imagesAreImages, + breadcrumb, + itemList, + webPage, + idsOnSite, + noPlaceholders +} + +function eachNode(value: unknown, visit: (node: JsonLdRecord) => void): void { + if (Array.isArray(value)) { + value.forEach((item) => eachNode(item, visit)) + return + } + if (!isRecord(value)) return + visit(value) + Object.values(value).forEach((child) => eachNode(child, visit)) +} +export function validateHtml(html: string, pagePath: string): Violation[] { + const violations: Violation[] = [] + const blocks: unknown[] = [] for (const match of html.matchAll(JSON_LD_BLOCK)) { - let parsed: unknown try { - parsed = JSON.parse(match[1]) + blocks.push(JSON.parse(match[1])) } catch (error) { - violations.push({ file, message: `invalid JSON-LD: ${String(error)}` }) - continue + violations.push({ rule: 'json', message: `invalid JSON-LD: ${error}` }) } - checkHonesty(parsed, file, violations) - const { defined, references } = collectGraphIds(parsed) + } + + const definedIds = new Set() + const referencedIds: string[] = [] + const nodesById = new Map() + for (const block of blocks) { + const { defined, references } = collectGraphIds(block) defined.forEach((id) => definedIds.add(id)) referencedIds.push(...references) + eachNode(block, (node) => { + const id = node['@id'] + if (typeof id !== 'string' || Object.keys(node).length === 1) return + if (nodesById.has(id)) { + violations.push({ + rule: 'duplicateIds', + message: `@id ${id} defined twice` + }) + } + nodesById.set(id, node) + }) + } + + const page: PageContext = { + pagePath, + canonical: html.match(CANONICAL)?.[1], + nodesById + } + for (const block of blocks) { + eachNode(block, (node) => { + for (const [rule, check] of Object.entries(RULES)) { + for (const message of check(node, page)) { + violations.push({ rule, message }) + } + } + }) } for (const id of referencedIds) { if (!definedIds.has(id)) { - violations.push({ file, message: `unresolved @id reference: ${id}` }) + violations.push({ rule: 'idRefs', message: `unresolved @id: ${id}` }) } } - return violations } +function htmlFiles(dir: string): string[] { + return readdirSync(dir, { recursive: true }) + .map(String) + .filter((entry) => entry.endsWith('.html')) + .map((entry) => join(dir, entry)) +} + +function pagePathOf(distDir: string, file: string): string { + const rel = relative(distDir, file).split(sep).join('/') + return `/${rel.replace(/index\.html$/, '')}` +} + function main(): void { - const files = htmlFiles(DIST_DIR) + const distDir = join(process.cwd(), 'dist') + const files = htmlFiles(distDir) if (files.length === 0) { console.error( - `JSON-LD validation found no HTML in ${DIST_DIR} — build first.` + `JSON-LD validation found no HTML in ${distDir} — build first.` ) process.exit(1) } - const violations = files.flatMap(validateFile) - if (violations.length > 0) { - console.error(`JSON-LD validation failed (${violations.length} issue(s)):`) - for (const { file, message } of violations) { - console.error(` ${file.replace(DIST_DIR, 'dist')}: ${message}`) + const failures = files.flatMap((file) => { + const pagePath = pagePathOf(distDir, file) + return validateHtml(readFileSync(file, 'utf8'), pagePath).map( + (violation) => ({ pagePath, ...violation }) + ) + }) + if (failures.length > 0) { + console.error(`JSON-LD validation failed (${failures.length} issue(s)):`) + for (const { pagePath, rule, message } of failures) { + console.error(` ${pagePath} [${rule}]: ${message}`) } process.exit(1) } @@ -126,4 +336,4 @@ function main(): void { ) } -main() +if (isDirectExecution(process.argv[1], import.meta.filename)) main() From f2cddb84470432daba1fcdc948fa0b8aab6098b6 Mon Sep 17 00:00:00 2001 From: Maanil Verma Date: Mon, 5 Oct 2026 21:45:33 +0530 Subject: [PATCH 2/8] fix(website): accept fractional seconds in JSON-LD date-times --- apps/website/scripts/validate-jsonld.test.ts | 5 +++++ apps/website/scripts/validate-jsonld.ts | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/apps/website/scripts/validate-jsonld.test.ts b/apps/website/scripts/validate-jsonld.test.ts index 66689ca0811..1990d087831 100644 --- a/apps/website/scripts/validate-jsonld.test.ts +++ b/apps/website/scripts/validate-jsonld.test.ts @@ -122,6 +122,11 @@ describe('validateHtml', () => { name: 'Talk', startDate: '2026-10-07T10:00:00-07:00' }, + { + '@type': 'Event', + name: 'Launch', + startDate: '2026-10-07T17:00:00.000Z' + }, { '@type': 'ImageObject', url: `${site}/a.webp` }, crumbs([ { '@type': 'ListItem', position: 1, name: 'Home', item: `${site}/` }, diff --git a/apps/website/scripts/validate-jsonld.ts b/apps/website/scripts/validate-jsonld.ts index d02ca02ad8a..d901e847900 100644 --- a/apps/website/scripts/validate-jsonld.ts +++ b/apps/website/scripts/validate-jsonld.ts @@ -10,7 +10,7 @@ const JSON_LD_BLOCK = /]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi const CANONICAL = /]*rel=["']canonical["'][^>]*href=["']([^"']+)["']/i const FULL_DATE_TIME = - /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?([+-]\d{2}:\d{2}|Z)$/ + /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?([+-]\d{2}:\d{2}|Z)$/ const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/ const VIDEO_FILE = /\.(mp4|webm|mov)(\?|#|$)/i const PLACEHOLDER = /^(undefined|null|NaN)$/ From d6615f92a4dcd5bfcf4bf858700ced22ce17f335 Mon Sep 17 00:00:00 2001 From: Maanil Verma Date: Mon, 5 Oct 2026 22:04:09 +0530 Subject: [PATCH 3/8] fix(website): close blind spots in the JSON-LD rules --- apps/website/scripts/validate-jsonld.test.ts | 29 ++++++++++++++++- apps/website/scripts/validate-jsonld.ts | 33 ++++++++++++-------- 2 files changed, 48 insertions(+), 14 deletions(-) diff --git a/apps/website/scripts/validate-jsonld.test.ts b/apps/website/scripts/validate-jsonld.test.ts index 1990d087831..20b0a9b2715 100644 --- a/apps/website/scripts/validate-jsonld.test.ts +++ b/apps/website/scripts/validate-jsonld.test.ts @@ -47,7 +47,7 @@ const video = { thumbnailUrl: `${site}/thumb.webp`, uploadDate: '2026-07-16T00:00:00+00:00' } -const crumbs = (items: object[]) => ({ +const crumbs = (items: unknown[]) => ({ '@type': 'BreadcrumbList', '@id': `${canonical}#breadcrumb`, itemListElement: items @@ -59,7 +59,10 @@ describe('validateHtml', () => { { rule: 'honesty', bad: { ...product, review: [] } }, { rule: 'offer', bad: offer('') }, { rule: 'offer', bad: { '@type': 'Offer', price: '5' } }, + { rule: 'offer', bad: offer('-20') }, + { rule: 'offer', bad: offer('Infinity') }, { rule: 'product', bad: { ...product, image: undefined } }, + { rule: 'product', bad: { ...product, offers: [] } }, { rule: 'product', bad: { ...product, brand: { name: 'Comfy' } } }, { rule: 'video', bad: { ...video, uploadDate: '2026-07-16' } }, { rule: 'video', bad: { ...video, uploadDate: undefined } }, @@ -77,6 +80,10 @@ describe('validateHtml', () => { rule: 'imagesAreImages', bad: { '@type': 'ImageObject', contentUrl: `${site}/a.mov?v=1` } }, + { + rule: 'imagesAreImages', + bad: { '@type': 'ImageObject', contentUrl: [`${site}/a.mp4`] } + }, { rule: 'breadcrumb', bad: crumbs([ @@ -91,6 +98,14 @@ describe('validateHtml', () => { { '@type': 'ListItem', position: 2, name: 'Page' } ]) }, + { + rule: 'breadcrumb', + bad: crumbs([ + { '@type': 'ListItem', position: 1, name: 'Home', item: `${site}/` }, + null, + { '@type': 'ListItem', position: 2, name: 'Page' } + ]) + }, { rule: 'itemList', bad: { @@ -102,6 +117,7 @@ describe('validateHtml', () => { { rule: 'idsOnSite', bad: { ...video, '@id': '/example/#video' } }, { rule: 'noPlaceholders', bad: { ...video, name: 'undefined' } }, { rule: 'noPlaceholders', bad: { ...video, description: ' ' } }, + { rule: 'noPlaceholders', bad: { ...video, sameAs: ['undefined'] } }, { rule: 'idRefs', bad: { ...video, isPartOf: { '@id': `${site}/#missing` } } @@ -164,6 +180,17 @@ describe('validateHtml', () => { expect(violations.map(({ rule }) => rule)).toEqual(['webPage', 'webPage']) }) + it('reads the canonical whatever the attribute order', () => { + const page = html([org, webPage]).replace( + ``, + `` + ) + expect(validateHtml(page, '/').map(({ rule }) => rule)).toEqual([ + 'webPage', + 'webPage' + ]) + }) + it('reports unparseable JSON-LD', () => { expect( validateHtml('', '/') diff --git a/apps/website/scripts/validate-jsonld.ts b/apps/website/scripts/validate-jsonld.ts index d901e847900..ae0629a8c5d 100644 --- a/apps/website/scripts/validate-jsonld.ts +++ b/apps/website/scripts/validate-jsonld.ts @@ -1,4 +1,4 @@ -import { readFileSync, readdirSync } from 'node:fs' +import { existsSync, readFileSync, readdirSync } from 'node:fs' import { join, relative, sep } from 'node:path' import { collectGraphIds } from '@/utils/jsonLd' @@ -8,12 +8,14 @@ import { isDirectExecution } from './script-entry-point' const SITE_ORIGIN = 'https://comfy.org' const JSON_LD_BLOCK = /]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi -const CANONICAL = /]*rel=["']canonical["'][^>]*href=["']([^"']+)["']/i +const CANONICAL = + /]*\brel=["']canonical["'])[^>]*\bhref=["']([^"']+)["']/i const FULL_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?([+-]\d{2}:\d{2}|Z)$/ const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/ const VIDEO_FILE = /\.(mp4|webm|mov)(\?|#|$)/i const PLACEHOLDER = /^(undefined|null|NaN)$/ +const DECIMAL = /^\d+(\.\d+)?$/ const WEB_PAGE_TYPES = [ 'WebPage', 'AboutPage', @@ -56,6 +58,7 @@ function asList(value: unknown): unknown[] { } function isBlank(value: unknown): boolean { + if (Array.isArray(value)) return value.every(isBlank) return value == null || (typeof value === 'string' && value.trim() === '') } @@ -97,12 +100,12 @@ const honesty: Rule = (node) => { const offer: Rule = (node, page) => { if (!typesOf(node).includes('Offer')) return [] - const price = isBlank(node.price) ? NaN : Number(String(node.price).trim()) - if (Number.isNaN(price) || isBlank(node.priceCurrency)) { + const priceText = String(node.price ?? '').trim() + if (!DECIMAL.test(priceText) || isBlank(node.priceCurrency)) { return ['Offer missing priceCurrency or a concrete price'] } - if (isModelPage(page.pagePath) && price <= 0) { - return [`model page Offer has a non-positive price ${String(node.price)}`] + if (isModelPage(page.pagePath) && Number(priceText) === 0) { + return [`model page Offer has a zero price ${String(node.price)}`] } return [] } @@ -145,7 +148,7 @@ const imagesAreImages: Rule = (node) => { const urls = [ ...asList(node.image), ...asList(node.thumbnailUrl), - ...(isImageObject ? [node.url, node.contentUrl] : []) + ...(isImageObject ? [...asList(node.url), ...asList(node.contentUrl)] : []) ].filter((url): url is string => typeof url === 'string') return urls .filter((url) => VIDEO_FILE.test(url)) @@ -154,8 +157,11 @@ const imagesAreImages: Rule = (node) => { const breadcrumb: Rule = (node) => { if (!typesOf(node).includes('BreadcrumbList')) return [] - const items = asList(node.itemListElement).filter(isRecord) + const items = asList(node.itemListElement) return items.flatMap((item, index) => { + if (!isRecord(item)) { + return [`BreadcrumbList item ${index + 1} is not a ListItem`] + } const problems: string[] = [] if (item.position !== index + 1) { problems.push( @@ -207,13 +213,13 @@ const idsOnSite: Rule = (node) => { : [`@id ${id} is not an absolute ${SITE_ORIGIN} URL`] } +const isPlaceholder = (value: unknown): boolean => + typeof value === 'string' && + (value.trim() === '' || PLACEHOLDER.test(value.trim())) + const noPlaceholders: Rule = (node) => Object.entries(node) - .filter( - ([, value]) => - typeof value === 'string' && - (value.trim() === '' || PLACEHOLDER.test(value.trim())) - ) + .filter(([, value]) => asList(value).some(isPlaceholder)) .map(([key, value]) => `${key} is ${JSON.stringify(value)}`) const RULES: Record = { @@ -295,6 +301,7 @@ export function validateHtml(html: string, pagePath: string): Violation[] { } function htmlFiles(dir: string): string[] { + if (!existsSync(dir)) return [] return readdirSync(dir, { recursive: true }) .map(String) .filter((entry) => entry.endsWith('.html')) From e7d0e5f2f2af976f16a8ecc2b08421e5318330d2 Mon Sep 17 00:00:00 2001 From: Maanil Verma Date: Tue, 6 Oct 2026 11:44:37 +0530 Subject: [PATCH 4/8] fix(website): accept valid breadcrumb, brand, price and reference shapes in validate-jsonld Scope the zero-price rule to hosted model pages with locale prefixes and skip /hub/models/local/. Sort breadcrumbs by position, accept a Thing item with an @id and require a name. Drop the missing-brand failure. Read price from priceSpecification, require a string currency and accept finite numeric prices. Treat {@id, @type} as a reference. Name the node in each message and print values as JSON. Export main(distDir) returning an exit code. --- apps/website/scripts/validate-jsonld.ts | 130 ++++++++++++++++-------- apps/website/src/utils/jsonLd.ts | 10 +- 2 files changed, 95 insertions(+), 45 deletions(-) diff --git a/apps/website/scripts/validate-jsonld.ts b/apps/website/scripts/validate-jsonld.ts index ae0629a8c5d..d4dab8d2875 100644 --- a/apps/website/scripts/validate-jsonld.ts +++ b/apps/website/scripts/validate-jsonld.ts @@ -1,7 +1,8 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs' import { join, relative, sep } from 'node:path' -import { collectGraphIds } from '@/utils/jsonLd' +import { NON_DEFAULT_LOCALE_PREFIXES } from '@/config/locales' +import { collectGraphIds, isIdReference } from '@/utils/jsonLd' import { isDirectExecution } from './script-entry-point' @@ -16,6 +17,9 @@ const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/ const VIDEO_FILE = /\.(mp4|webm|mov)(\?|#|$)/i const PLACEHOLDER = /^(undefined|null|NaN)$/ const DECIMAL = /^\d+(\.\d+)?$/ +const MODEL_PAGE = new RegExp( + `^(?:${NON_DEFAULT_LOCALE_PREFIXES.join('|')})?/(?:hub/)?models/(?!local/)[^/]+/` +) const WEB_PAGE_TYPES = [ 'WebPage', 'AboutPage', @@ -66,6 +70,15 @@ function isAbsoluteHttpUrl(value: unknown): boolean { return typeof value === 'string' && /^https?:\/\/[^/]/.test(value) } +function show(value: unknown): string { + return value === undefined ? 'undefined' : JSON.stringify(value) +} + +function locatorOf(node: JsonLdRecord): string { + const id = node['@id'] + return typeof id === 'string' ? id : typesOf(node).join('/') || '(untyped)' +} + function missing(node: JsonLdRecord, fields: string[]): string[] { const type = typesOf(node).join('/') return fields @@ -76,14 +89,15 @@ function missing(node: JsonLdRecord, fields: string[]): string[] { function resolve(value: unknown, page: PageContext): JsonLdRecord | undefined { if (!isRecord(value)) return undefined const id = value['@id'] - if (typeof id === 'string' && Object.keys(value).length === 1) { - return page.nodesById.get(id) + if (isIdReference(value) && typeof id === 'string') { + return page.nodesById.get(id) ?? value } return value } -function isModelPage(pagePath: string): boolean { - return /^\/(hub\/)?models\/[^/]+\//.test(pagePath) +function isConcretePrice(price: unknown): boolean { + if (typeof price === 'number') return Number.isFinite(price) && price >= 0 + return typeof price === 'string' && DECIMAL.test(price.trim()) } const honesty: Rule = (node) => { @@ -100,12 +114,20 @@ const honesty: Rule = (node) => { const offer: Rule = (node, page) => { if (!typesOf(node).includes('Offer')) return [] - const priceText = String(node.price ?? '').trim() - if (!DECIMAL.test(priceText) || isBlank(node.priceCurrency)) { - return ['Offer missing priceCurrency or a concrete price'] + const specification = asList(node.priceSpecification).find(isRecord) + const price = node.price ?? specification?.price + const currency = node.priceCurrency ?? specification?.priceCurrency + if ( + !isConcretePrice(price) || + typeof currency !== 'string' || + isBlank(currency) + ) { + return [ + `Offer missing priceCurrency or a concrete price: price ${show(price)}, priceCurrency ${show(currency)}` + ] } - if (isModelPage(page.pagePath) && Number(priceText) === 0) { - return [`model page Offer has a zero price ${String(node.price)}`] + if (MODEL_PAGE.test(page.pagePath) && Number(price) === 0) { + return [`model page Offer has a zero price ${show(price)}`] } return [] } @@ -113,10 +135,13 @@ const offer: Rule = (node, page) => { const product: Rule = (node, page) => { if (!typesOf(node).includes('Product')) return [] const problems = missing(node, ['name', 'image', 'offers']) + if (isBlank(node.brand)) return problems const brand = resolve(node.brand, page) const brandTypes = brand ? typesOf(brand) : [] if (!brandTypes.some((type) => type === 'Brand' || type === 'Organization')) { - problems.push('Product brand is not a Brand or Organization') + problems.push( + `Product brand ${show(node.brand)} is not a Brand or Organization` + ) } return problems } @@ -127,7 +152,7 @@ const video: Rule = (node) => { const { uploadDate } = node if (!isBlank(uploadDate) && !FULL_DATE_TIME.test(String(uploadDate))) { problems.push( - `VideoObject uploadDate ${String(uploadDate)} lacks a time and offset` + `VideoObject uploadDate ${show(uploadDate)} lacks a time and offset` ) } return problems @@ -135,12 +160,13 @@ const video: Rule = (node) => { const event: Rule = (node) => { if (!typesOf(node).includes('Event')) return [] - const startDate = String(node.startDate ?? '') - return DATE_ONLY.test(startDate) || FULL_DATE_TIME.test(startDate) + const { startDate } = node + const isIsoDate = + typeof startDate === 'string' && + (DATE_ONLY.test(startDate) || FULL_DATE_TIME.test(startDate)) + return isIsoDate ? [] - : [ - `Event startDate ${startDate || '(missing)'} is not ISO 8601 with offset` - ] + : [`Event startDate ${show(startDate)} is not ISO 8601 with offset`] } const imagesAreImages: Rule = (node) => { @@ -155,25 +181,41 @@ const imagesAreImages: Rule = (node) => { .map((url) => `video file used as an image: ${url}`) } +function crumbUrl(item: unknown): unknown { + return isRecord(item) ? item['@id'] : item +} + +function crumbName(crumb: JsonLdRecord): unknown { + return crumb.name ?? (isRecord(crumb.item) ? crumb.item.name : undefined) +} + const breadcrumb: Rule = (node) => { if (!typesOf(node).includes('BreadcrumbList')) return [] const items = asList(node.itemListElement) - return items.flatMap((item, index) => { - if (!isRecord(item)) { - return [`BreadcrumbList item ${index + 1} is not a ListItem`] - } - const problems: string[] = [] - if (item.position !== index + 1) { - problems.push( - `BreadcrumbList item ${index + 1} has position ${String(item.position)}` - ) - } - const isLast = index === items.length - 1 - if (!isLast && !isAbsoluteHttpUrl(item.item)) { - problems.push(`BreadcrumbList item ${index + 1} has no absolute item URL`) - } - return problems - }) + const malformed = items.flatMap((item, index) => + isRecord(item) + ? [] + : [`BreadcrumbList entry ${index + 1} is not a ListItem`] + ) + const crumbs = items + .filter(isRecord) + .toSorted((a, b) => Number(a.position) - Number(b.position)) + return [ + ...malformed, + ...crumbs.flatMap((crumb, index) => { + const label = `BreadcrumbList item ${index + 1}` + const problems: string[] = [] + if (crumb.position !== index + 1) { + problems.push(`${label} has position ${show(crumb.position)}`) + } + if (isBlank(crumbName(crumb))) problems.push(`${label} has no name`) + const isLast = index === crumbs.length - 1 + if (!isLast && !isAbsoluteHttpUrl(crumbUrl(crumb.item))) { + problems.push(`${label} has no absolute item URL`) + } + return problems + }) + ] } const itemList: Rule = (node) => { @@ -183,9 +225,7 @@ const itemList: Rule = (node) => { const count = asList(node.itemListElement).length return node.numberOfItems === count ? [] - : [ - `ItemList numberOfItems ${String(node.numberOfItems)} but ${count} listed` - ] + : [`ItemList numberOfItems ${show(node.numberOfItems)} but ${count} listed`] } const webPage: Rule = (node, page) => { @@ -200,7 +240,7 @@ const webPage: Rule = (node, page) => { problems.push(`WebPage @id ${id} does not match canonical`) } if (node.url !== page.canonical) { - problems.push(`WebPage url ${String(node.url)} does not match canonical`) + problems.push(`WebPage url ${show(node.url)} does not match canonical`) } return problems } @@ -266,7 +306,7 @@ export function validateHtml(html: string, pagePath: string): Violation[] { referencedIds.push(...references) eachNode(block, (node) => { const id = node['@id'] - if (typeof id !== 'string' || Object.keys(node).length === 1) return + if (typeof id !== 'string' || isIdReference(node)) return if (nodesById.has(id)) { violations.push({ rule: 'duplicateIds', @@ -286,7 +326,7 @@ export function validateHtml(html: string, pagePath: string): Violation[] { eachNode(block, (node) => { for (const [rule, check] of Object.entries(RULES)) { for (const message of check(node, page)) { - violations.push({ rule, message }) + violations.push({ rule, message: `${locatorOf(node)}: ${message}` }) } } }) @@ -313,15 +353,14 @@ function pagePathOf(distDir: string, file: string): string { return `/${rel.replace(/index\.html$/, '')}` } -function main(): void { - const distDir = join(process.cwd(), 'dist') +export function main(distDir: string): number { const files = htmlFiles(distDir) if (files.length === 0) { console.error( `JSON-LD validation found no HTML in ${distDir} — build first.` ) - process.exit(1) + return 1 } const failures = files.flatMap((file) => { @@ -335,12 +374,15 @@ function main(): void { for (const { pagePath, rule, message } of failures) { console.error(` ${pagePath} [${rule}]: ${message}`) } - process.exit(1) + return 1 } process.stdout.write( `JSON-LD validation passed across ${files.length} page(s).\n` ) + return 0 } -if (isDirectExecution(process.argv[1], import.meta.filename)) main() +if (isDirectExecution(process.argv[1], import.meta.filename)) { + process.exitCode = main(join(process.cwd(), 'dist')) +} diff --git a/apps/website/src/utils/jsonLd.ts b/apps/website/src/utils/jsonLd.ts index 3b078e37d34..5d9c76785bf 100644 --- a/apps/website/src/utils/jsonLd.ts +++ b/apps/website/src/utils/jsonLd.ts @@ -515,6 +515,14 @@ export function buildPageGraph( ) } +export function isIdReference(record: Record): boolean { + const keys = Object.keys(record) + return ( + typeof record['@id'] === 'string' && + keys.every((key) => key === '@id' || key === '@type') + ) +} + export function collectGraphIds(value: unknown): { defined: Set references: string[] @@ -530,7 +538,7 @@ export function collectGraphIds(value: unknown): { const record = node as Record const id = record['@id'] if (typeof id === 'string') { - if (Object.keys(record).length === 1) references.push(id) + if (isIdReference(record)) references.push(id) else defined.add(id) } Object.values(record).forEach(walk) From 7b8516ccb06be01ae2120c9a7ddd168fcb4a29b3 Mon Sep 17 00:00:00 2001 From: Maanil Verma Date: Tue, 6 Oct 2026 11:48:46 +0530 Subject: [PATCH 5/8] test(website): cover validate-jsonld branches and the CLI exit code --- apps/website/scripts/validate-jsonld.test.ts | 249 +++++++++++++++---- 1 file changed, 207 insertions(+), 42 deletions(-) diff --git a/apps/website/scripts/validate-jsonld.test.ts b/apps/website/scripts/validate-jsonld.test.ts index 20b0a9b2715..eefe5da4aa3 100644 --- a/apps/website/scripts/validate-jsonld.test.ts +++ b/apps/website/scripts/validate-jsonld.test.ts @@ -1,6 +1,14 @@ -import { describe, expect, it } from 'vitest' +import { spawnSync } from 'node:child_process' +import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises' +import { createRequire } from 'node:module' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { pathToFileURL } from 'node:url' +import { describe, expect, it, onTestFinished, vi } from 'vitest' -import { validateHtml } from './validate-jsonld' +import { websiteRoot } from '@website/paths' + +import { main, validateHtml } from './validate-jsonld' const site = 'https://comfy.org' const canonical = `${site}/example/` @@ -16,9 +24,18 @@ const webPage = { name: 'Example' } -function html(nodes: object[], pageCanonical = canonical): string { +function html(nodes: object[], pageCanonical: string | null = canonical) { const graph = { '@context': 'https://schema.org', '@graph': nodes } - return `` + const link = pageCanonical + ? `` + : '' + return `${link}` +} + +function messages(nodes: object[], pagePath = '/example/'): string[] { + return validateHtml(html([org, webPage, ...nodes]), pagePath).map( + ({ message }) => message + ) } function rulesHit(nodes: object[], pagePath = '/example/'): string[] { @@ -27,10 +44,10 @@ function rulesHit(nodes: object[], pagePath = '/example/'): string[] { ) } -const offer = (price: unknown) => ({ +const offer = (price: unknown, priceCurrency: unknown = 'USD') => ({ '@type': 'Offer', price, - priceCurrency: 'USD' + priceCurrency }) const product = { '@type': 'Product', @@ -45,6 +62,7 @@ const video = { '@id': `${canonical}#video`, name: 'Tutorial', thumbnailUrl: `${site}/thumb.webp`, + contentUrl: `${site}/tutorial.mp4`, uploadDate: '2026-07-16T00:00:00+00:00' } const crumbs = (items: unknown[]) => ({ @@ -52,6 +70,13 @@ const crumbs = (items: unknown[]) => ({ '@id': `${canonical}#breadcrumb`, itemListElement: items }) +const home = { + '@type': 'ListItem', + position: 1, + name: 'Home', + item: `${site}/` +} +const page = { '@type': 'ListItem', position: 2, name: 'Page' } describe('validateHtml', () => { it.for([ @@ -60,10 +85,16 @@ describe('validateHtml', () => { { rule: 'offer', bad: offer('') }, { rule: 'offer', bad: { '@type': 'Offer', price: '5' } }, { rule: 'offer', bad: offer('-20') }, + { rule: 'offer', bad: offer(-20) }, { rule: 'offer', bad: offer('Infinity') }, + { rule: 'offer', bad: offer('1e3') }, + { rule: 'offer', bad: offer('20', 0) }, + { rule: 'product', bad: { ...product, name: undefined } }, + { rule: 'product', bad: { ...product, name: ' ' } }, { rule: 'product', bad: { ...product, image: undefined } }, { rule: 'product', bad: { ...product, offers: [] } }, { rule: 'product', bad: { ...product, brand: { name: 'Comfy' } } }, + { rule: 'video', bad: { ...video, name: undefined } }, { rule: 'video', bad: { ...video, uploadDate: '2026-07-16' } }, { rule: 'video', bad: { ...video, uploadDate: undefined } }, { rule: 'video', bad: { ...video, thumbnailUrl: undefined } }, @@ -71,41 +102,37 @@ describe('validateHtml', () => { rule: 'event', bad: { '@type': 'Event', name: 'Meetup', startDate: '2026-10-07T10:00' } }, + { rule: 'event', bad: { '@type': 'Event', name: 'Meetup' } }, { rule: 'imagesAreImages', bad: { ...product, image: `${site}/a.mp4` } }, + { rule: 'imagesAreImages', bad: { ...product, image: `${site}/a.MP4` } }, { rule: 'imagesAreImages', - bad: { ...video, thumbnailUrl: `${site}/a.webm` } + bad: { ...product, image: `${site}/a.mp4#t=1` } }, { rule: 'imagesAreImages', - bad: { '@type': 'ImageObject', contentUrl: `${site}/a.mov?v=1` } + bad: { ...video, thumbnailUrl: `${site}/a.webm` } }, { rule: 'imagesAreImages', - bad: { '@type': 'ImageObject', contentUrl: [`${site}/a.mp4`] } + bad: { '@type': 'ImageObject', url: `${site}/a.mp4` } }, { - rule: 'breadcrumb', - bad: crumbs([ - { '@type': 'ListItem', position: 1, name: 'Home', item: `${site}/` }, - { '@type': 'ListItem', position: 3, name: 'Page' } - ]) + rule: 'imagesAreImages', + bad: { '@type': 'ImageObject', contentUrl: `${site}/a.mov?v=1` } }, { - rule: 'breadcrumb', - bad: crumbs([ - { '@type': 'ListItem', position: 1, name: 'Home', item: '/' }, - { '@type': 'ListItem', position: 2, name: 'Page' } - ]) + rule: 'imagesAreImages', + bad: { '@type': 'ImageObject', contentUrl: [`${site}/a.mp4`] } }, + { rule: 'breadcrumb', bad: crumbs([home, { ...page, position: 3 }]) }, + { rule: 'breadcrumb', bad: crumbs([{ ...home, item: '/' }, page]) }, { rule: 'breadcrumb', - bad: crumbs([ - { '@type': 'ListItem', position: 1, name: 'Home', item: `${site}/` }, - null, - { '@type': 'ListItem', position: 2, name: 'Page' } - ]) + bad: crumbs([{ ...home, item: { '@id': '/' } }, page]) }, + { rule: 'breadcrumb', bad: crumbs([{ ...home, name: undefined }, page]) }, + { rule: 'breadcrumb', bad: crumbs([home, null, page]) }, { rule: 'itemList', bad: { @@ -115,13 +142,26 @@ describe('validateHtml', () => { } }, { rule: 'idsOnSite', bad: { ...video, '@id': '/example/#video' } }, + { + rule: 'idsOnSite', + bad: { ...video, '@id': 'https://comfy.org.evil.com/#video' } + }, { rule: 'noPlaceholders', bad: { ...video, name: 'undefined' } }, + { rule: 'noPlaceholders', bad: { ...video, name: 'null' } }, + { rule: 'noPlaceholders', bad: { ...video, name: 'NaN' } }, { rule: 'noPlaceholders', bad: { ...video, description: ' ' } }, { rule: 'noPlaceholders', bad: { ...video, sameAs: ['undefined'] } }, { rule: 'idRefs', bad: { ...video, isPartOf: { '@id': `${site}/#missing` } } }, + { + rule: 'idRefs', + bad: { + ...video, + isPartOf: { '@id': `${site}/#missing`, '@type': 'WebSite' } + } + }, { rule: 'duplicateIds', bad: { ...webPage, name: 'Again' } } ])('flags $rule', ({ rule, bad }) => { expect(rulesHit([bad])).toContain(rule) @@ -144,48 +184,119 @@ describe('validateHtml', () => { startDate: '2026-10-07T17:00:00.000Z' }, { '@type': 'ImageObject', url: `${site}/a.webp` }, - crumbs([ - { '@type': 'ListItem', position: 1, name: 'Home', item: `${site}/` }, - { '@type': 'ListItem', position: 2, name: 'Page' } - ]), + crumbs([home, page]), { '@type': 'ItemList', numberOfItems: 1, itemListElement: [ { '@type': 'ListItem', position: 1, url: canonical } ] + }, + { + '@type': 'ItemList', + itemListElement: [ + { '@type': 'ListItem', position: 1, url: canonical } + ] + }, + { + '@type': 'CollectionPage', + '@id': `${site}/other/#collection`, + url: `${site}/other/` + }, + { + '@type': 'WebSite', + '@id': `${site}/#website`, + publisher: { '@id': org['@id'], '@type': 'Organization' } } ]) ).toEqual([]) }) - it('accepts a typed Brand inline on a Product', () => { + it.for([ + { shape: 'a string item URL', list: [home, page] }, + { + shape: 'a Thing item with an @id', + list: [{ ...home, item: { '@id': `${site}/`, name: 'Home' } }, page] + }, + { shape: 'items out of array order', list: [page, home] } + ])('accepts a breadcrumb with $shape', ({ list }) => { + expect(rulesHit([crumbs(list)])).toEqual([]) + }) + + it.for([ + { shape: 'a typed inline Brand', brand: { '@type': 'Brand', name: 'C' } }, + { shape: 'no brand', brand: undefined } + ])('accepts a Product with $shape', ({ brand }) => { + expect(rulesHit([{ ...product, brand }])).toEqual([]) + }) + + it.for([ + { price: 1e21, rules: [] }, + { price: 1e-7, rules: [] }, + { price: Number.NaN, rules: ['offer'] } + ])('checks a numeric price of $price', ({ price, rules }) => { + expect(rulesHit([offer(price)])).toEqual(rules) + }) + + it('reads price and currency from priceSpecification', () => { expect( - rulesHit([{ ...product, brand: { '@type': 'Brand', name: 'Comfy' } }]) + rulesHit([ + { + '@type': 'Offer', + priceSpecification: { + '@type': 'UnitPriceSpecification', + price: 10, + priceCurrency: 'USD' + } + } + ]) ).toEqual([]) }) - it('allows a free Offer outside model pages but not on them', () => { - expect(rulesHit([offer(0)], '/download/')).toEqual([]) - expect(rulesHit([offer('0.00')], '/hub/models/luma-photon-flash/')).toEqual( - ['offer'] - ) - expect(rulesHit([offer('0.01')], '/hub/models/luma-photon-flash/')).toEqual( - [] - ) + it.for([ + { pagePath: '/download/', rules: [] }, + { pagePath: '/hub/models/local/flux-dev/', rules: [] }, + { pagePath: '/hub/models/luma-photon-flash/', rules: ['offer'] }, + { pagePath: '/models/luma-photon-flash/', rules: ['offer'] }, + { pagePath: '/zh-CN/hub/models/luma-photon-flash/', rules: ['offer'] }, + { pagePath: '/ja/models/luma-photon-flash/', rules: ['offer'] } + ])('checks a zero-price Offer on $pagePath', ({ pagePath, rules }) => { + expect(rulesHit([offer('0.00')], pagePath)).toEqual(rules) }) - it('flags a WebPage whose @id or url drifts from the canonical', () => { - const violations = validateHtml(html([org, webPage], `${site}/other/`), '/') + it('names the node and shows values as JSON in each message', () => { + expect( + messages([ + crumbs([home, null, { ...page, position: '2' }]), + { '@type': 'Offer', price: '5' } + ]) + ).toEqual([ + `${canonical}#breadcrumb: BreadcrumbList entry 2 is not a ListItem`, + `${canonical}#breadcrumb: BreadcrumbList item 2 has position "2"`, + 'Offer: Offer missing priceCurrency or a concrete price: price "5", priceCurrency undefined' + ]) + }) + + it('flags a page node whose @id or url drifts from the canonical', () => { + const aboutPage = { ...webPage, '@type': 'AboutPage' } + const violations = validateHtml( + html([org, aboutPage], `${site}/other/`), + '/' + ) expect(violations.map(({ rule }) => rule)).toEqual(['webPage', 'webPage']) }) + it('skips the WebPage check when the page has no canonical', () => { + const drifted = { ...webPage, url: `${site}/other/` } + expect(validateHtml(html([org, drifted], null), '/')).toEqual([]) + }) + it('reads the canonical whatever the attribute order', () => { - const page = html([org, webPage]).replace( + const markup = html([org, webPage]).replace( ``, `` ) - expect(validateHtml(page, '/').map(({ rule }) => rule)).toEqual([ + expect(validateHtml(markup, '/').map(({ rule }) => rule)).toEqual([ 'webPage', 'webPage' ]) @@ -197,3 +308,57 @@ describe('validateHtml', () => { ).toMatchObject([{ rule: 'json' }]) }) }) + +describe('main', () => { + async function siteWith(pages: Record): Promise { + const directory = await mkdtemp(join(tmpdir(), 'validate-jsonld-')) + onTestFinished(() => rm(directory, { recursive: true, force: true })) + for (const [route, content] of Object.entries(pages)) { + await mkdir(join(directory, 'dist', route), { recursive: true }) + await writeFile(join(directory, 'dist', route, 'index.html'), content) + } + return directory + } + + it.for<{ name: string; pages: Record; status: number }>([ + { name: 'an empty dist', pages: {}, status: 1 }, + { name: 'a valid page', pages: { a: html([org, webPage]) }, status: 0 }, + { + name: 'an invalid page', + pages: { a: html([org, webPage, { ...video, name: 'null' }]) }, + status: 1 + } + ])('returns $status for $name', async ({ pages, status }) => { + vi.spyOn(console, 'error').mockImplementation(() => {}) + vi.spyOn(process.stdout, 'write').mockImplementation(() => true) + const directory = await siteWith(pages) + expect(main(join(directory, 'dist'))).toBe(status) + }) + + it('returns 1 when dist does not exist', async () => { + vi.spyOn(console, 'error').mockImplementation(() => {}) + const directory = await siteWith({}) + expect(main(join(directory, 'missing'))).toBe(1) + }) + + it('fails the CLI when there is no built HTML', async () => { + const directory = await siteWith({}) + const loader = pathToFileURL( + createRequire(import.meta.url).resolve('tsx') + ).href + const result = spawnSync( + process.execPath, + ['--import', loader, join(import.meta.dirname, 'validate-jsonld.ts')], + { + cwd: directory, + env: { + ...process.env, + TSX_TSCONFIG_PATH: join(websiteRoot, 'tsconfig.json') + }, + encoding: 'utf8' + } + ) + expect(result.status).toBe(1) + expect(result.stderr).toContain('JSON-LD validation found no HTML') + }) +}) From f32b5c7cd1b1f7198631e7430e0bb8225b3ac943 Mon Sep 17 00:00:00 2001 From: Maanil Verma Date: Tue, 6 Oct 2026 11:56:22 +0530 Subject: [PATCH 6/8] test(website): accept a breadcrumb name carried on the Thing item --- apps/website/scripts/validate-jsonld.test.ts | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/apps/website/scripts/validate-jsonld.test.ts b/apps/website/scripts/validate-jsonld.test.ts index eefe5da4aa3..8ce316111eb 100644 --- a/apps/website/scripts/validate-jsonld.test.ts +++ b/apps/website/scripts/validate-jsonld.test.ts @@ -216,7 +216,14 @@ describe('validateHtml', () => { { shape: 'a string item URL', list: [home, page] }, { shape: 'a Thing item with an @id', - list: [{ ...home, item: { '@id': `${site}/`, name: 'Home' } }, page] + list: [ + { + '@type': 'ListItem', + position: 1, + item: { '@id': `${site}/`, name: 'Home' } + }, + page + ] }, { shape: 'items out of array order', list: [page, home] } ])('accepts a breadcrumb with $shape', ({ list }) => { From 23f77132f88f61636ffe607593795f1350d0d6a9 Mon Sep 17 00:00:00 2001 From: Maanil Verma Date: Tue, 6 Oct 2026 15:41:45 +0530 Subject: [PATCH 7/8] fix(website): close reference, date and fail-open gaps in validate-jsonld Treat a lone {@id, @type} node as a minimal definition and skip the content rules only when another node defines the same @id. Move isIdReference into the validator and restore collectGraphIds in jsonLd.ts to the main version. Reject impossible calendar dates, clock times and offsets. Flag "[object Object]". Allow external entity @ids without a fragment and report unresolved @ids only for on-site ids. Fail main() when no built page has a canonical link, and print how many pages carry JSON-LD. --- apps/website/scripts/validate-jsonld.test.ts | 95 +++++++++++++++- apps/website/scripts/validate-jsonld.ts | 112 ++++++++++++++----- apps/website/src/utils/jsonLd.ts | 10 +- 3 files changed, 175 insertions(+), 42 deletions(-) diff --git a/apps/website/scripts/validate-jsonld.test.ts b/apps/website/scripts/validate-jsonld.test.ts index 8ce316111eb..611aeeebfcd 100644 --- a/apps/website/scripts/validate-jsonld.test.ts +++ b/apps/website/scripts/validate-jsonld.test.ts @@ -89,6 +89,13 @@ describe('validateHtml', () => { { rule: 'offer', bad: offer('Infinity') }, { rule: 'offer', bad: offer('1e3') }, { rule: 'offer', bad: offer('20', 0) }, + { + rule: 'offer', + bad: { + '@type': 'Offer', + priceSpecification: { '@type': 'UnitPriceSpecification' } + } + }, { rule: 'product', bad: { ...product, name: undefined } }, { rule: 'product', bad: { ...product, name: ' ' } }, { rule: 'product', bad: { ...product, image: undefined } }, @@ -98,11 +105,27 @@ describe('validateHtml', () => { { rule: 'video', bad: { ...video, uploadDate: '2026-07-16' } }, { rule: 'video', bad: { ...video, uploadDate: undefined } }, { rule: 'video', bad: { ...video, thumbnailUrl: undefined } }, + ...[ + '2026-02-30T12:00:00.000Z', + '2026-02-29T12:00:00Z', + '2026-04-31T12:00:00Z', + '2026-13-01T12:00:00Z', + '2026-03-15T24:00:00Z', + '2026-03-15T23:60:00Z', + '2026-03-15T23:59:60Z', + '2026-03-15T12:00:00+15:00', + '2026-03-15T12:00:00+05:60' + ].map((uploadDate) => ({ rule: 'video', bad: { ...video, uploadDate } })), { rule: 'event', bad: { '@type': 'Event', name: 'Meetup', startDate: '2026-10-07T10:00' } }, { rule: 'event', bad: { '@type': 'Event', name: 'Meetup' } }, + { + rule: 'event', + bad: { '@type': 'Event', name: 'Meetup', startDate: '2026-02-30' } + }, + { rule: 'event', bad: { '@type': 'Event', '@id': `${canonical}#event` } }, { rule: 'imagesAreImages', bad: { ...product, image: `${site}/a.mp4` } }, { rule: 'imagesAreImages', bad: { ...product, image: `${site}/a.MP4` } }, { @@ -141,6 +164,14 @@ describe('validateHtml', () => { itemListElement: [{ '@type': 'ListItem', position: 1, url: canonical }] } }, + { + rule: 'itemList', + bad: { + '@type': 'ItemList', + numberOfItems: '1', + itemListElement: [{ '@type': 'ListItem', position: 1, url: canonical }] + } + }, { rule: 'idsOnSite', bad: { ...video, '@id': '/example/#video' } }, { rule: 'idsOnSite', @@ -152,15 +183,12 @@ describe('validateHtml', () => { { rule: 'noPlaceholders', bad: { ...video, description: ' ' } }, { rule: 'noPlaceholders', bad: { ...video, sameAs: ['undefined'] } }, { - rule: 'idRefs', - bad: { ...video, isPartOf: { '@id': `${site}/#missing` } } + rule: 'noPlaceholders', + bad: { ...video, description: '[object Object]' } }, { rule: 'idRefs', - bad: { - ...video, - isPartOf: { '@id': `${site}/#missing`, '@type': 'WebSite' } - } + bad: { ...video, isPartOf: { '@id': `${site}/#missing` } } }, { rule: 'duplicateIds', bad: { ...webPage, name: 'Again' } } ])('flags $rule', ({ rule, bad }) => { @@ -183,6 +211,16 @@ describe('validateHtml', () => { name: 'Launch', startDate: '2026-10-07T17:00:00.000Z' }, + { '@type': 'Event', name: 'Leap', startDate: '2024-02-29T12:00:00Z' }, + { + '@type': 'Event', + name: 'Late', + startDate: '2026-03-01T00:30:00+02:00' + }, + { '@type': 'Event', name: 'Close', startDate: '2026-03-15T23:59:59Z' }, + { '@type': 'Product', '@id': product['@id'] }, + { '@type': 'VideoObject', '@id': video['@id'] }, + { '@type': 'WebPage', '@id': webPage['@id'] }, { '@type': 'ImageObject', url: `${site}/a.webp` }, crumbs([home, page]), { @@ -212,6 +250,26 @@ describe('validateHtml', () => { ).toEqual([]) }) + it('treats a lone {@id, @type} node as a minimal definition', () => { + const brandId = `${site}/#brand` + expect( + rulesHit([ + { '@type': 'Organization', '@id': brandId }, + { ...product, brand: { '@id': brandId } } + ]) + ).toEqual([]) + }) + + it('accepts an external entity @id', () => { + const wikidata = 'https://www.wikidata.org/wiki/Q116391114' + expect( + rulesHit([ + { '@type': 'Organization', '@id': wikidata, name: 'Comfy' }, + { ...video, sameAs: { '@id': 'https://www.wikidata.org/entity/Q42' } } + ]) + ).toEqual([]) + }) + it.for([ { shape: 'a string item URL', list: [home, page] }, { @@ -271,6 +329,12 @@ describe('validateHtml', () => { expect(rulesHit([offer('0.00')], pagePath)).toEqual(rules) }) + it('leaves a positive price on a model page alone', () => { + expect(rulesHit([offer('0.01')], '/hub/models/luma-photon-flash/')).toEqual( + [] + ) + }) + it('names the node and shows values as JSON in each message', () => { expect( messages([ @@ -330,6 +394,11 @@ describe('main', () => { it.for<{ name: string; pages: Record; status: number }>([ { name: 'an empty dist', pages: {}, status: 1 }, { name: 'a valid page', pages: { a: html([org, webPage]) }, status: 0 }, + { + name: 'pages with no canonical', + pages: { a: html([org, webPage], null) }, + status: 1 + }, { name: 'an invalid page', pages: { a: html([org, webPage, { ...video, name: 'null' }]) }, @@ -342,6 +411,20 @@ describe('main', () => { expect(main(join(directory, 'dist'))).toBe(status) }) + it('counts the pages that carry JSON-LD', async () => { + const write = vi + .spyOn(process.stdout, 'write') + .mockImplementation(() => true) + const directory = await siteWith({ + a: html([org, webPage]), + b: '' + }) + expect(main(join(directory, 'dist'))).toBe(0) + expect(write).toHaveBeenCalledWith( + 'JSON-LD validation passed across 2 page(s), 1 with JSON-LD.\n' + ) + }) + it('returns 1 when dist does not exist', async () => { vi.spyOn(console, 'error').mockImplementation(() => {}) const directory = await siteWith({}) diff --git a/apps/website/scripts/validate-jsonld.ts b/apps/website/scripts/validate-jsonld.ts index d4dab8d2875..c71fc2c81ea 100644 --- a/apps/website/scripts/validate-jsonld.ts +++ b/apps/website/scripts/validate-jsonld.ts @@ -2,7 +2,7 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs' import { join, relative, sep } from 'node:path' import { NON_DEFAULT_LOCALE_PREFIXES } from '@/config/locales' -import { collectGraphIds, isIdReference } from '@/utils/jsonLd' +import { collectGraphIds } from '@/utils/jsonLd' import { isDirectExecution } from './script-entry-point' @@ -11,15 +11,17 @@ const JSON_LD_BLOCK = /]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi const CANONICAL = /]*\brel=["']canonical["'])[^>]*\bhref=["']([^"']+)["']/i -const FULL_DATE_TIME = - /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?([+-]\d{2}:\d{2}|Z)$/ -const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/ +const ISO_DATE = + /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?(?:Z|[+-](\d{2}):(\d{2})))?$/ +const MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31] +const MAX_OFFSET_MINUTES = 14 * 60 const VIDEO_FILE = /\.(mp4|webm|mov)(\?|#|$)/i -const PLACEHOLDER = /^(undefined|null|NaN)$/ +const PLACEHOLDER = /^(undefined|null|NaN|\[object Object\])$/ const DECIMAL = /^\d+(\.\d+)?$/ const MODEL_PAGE = new RegExp( `^(?:${NON_DEFAULT_LOCALE_PREFIXES.join('|')})?/(?:hub/)?models/(?!local/)[^/]+/` ) +const REFERENCE_RULES = new Set(['honesty', 'idsOnSite', 'noPlaceholders']) const WEB_PAGE_TYPES = [ 'WebPage', 'AboutPage', @@ -86,6 +88,21 @@ function missing(node: JsonLdRecord, fields: string[]): string[] { .map((field) => `${type} missing ${field}`) } +function isIdReference(node: JsonLdRecord): boolean { + return ( + typeof node['@id'] === 'string' && + Object.keys(node).every((key) => key === '@id' || key === '@type') + ) +} + +function isOnSite(id: string): boolean { + return id.startsWith(`${SITE_ORIGIN}/`) +} + +function pointsElsewhere(node: JsonLdRecord, page: PageContext): boolean { + return isIdReference(node) && page.nodesById.get(String(node['@id'])) !== node +} + function resolve(value: unknown, page: PageContext): JsonLdRecord | undefined { if (!isRecord(value)) return undefined const id = value['@id'] @@ -95,6 +112,28 @@ function resolve(value: unknown, page: PageContext): JsonLdRecord | undefined { return value } +function isLeapYear(year: number): boolean { + return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0 +} + +function isoDate(value: unknown): { hasTime: boolean } | undefined { + const match = typeof value === 'string' ? ISO_DATE.exec(value) : null + if (!match) return undefined + const [year, month, day, hour, minute, second, offsetHour, offsetMinute] = + match.slice(1).map((part: string | undefined) => Number(part ?? 0)) + if (month < 1 || month > 12) return undefined + const monthDays = month === 2 && isLeapYear(year) ? 29 : MONTH_DAYS[month - 1] + const isReal = + day >= 1 && + day <= monthDays && + hour <= 23 && + minute <= 59 && + second <= 59 && + offsetMinute <= 59 && + offsetHour * 60 + offsetMinute <= MAX_OFFSET_MINUTES + return isReal ? { hasTime: match[0].includes('T') } : undefined +} + function isConcretePrice(price: unknown): boolean { if (typeof price === 'number') return Number.isFinite(price) && price >= 0 return typeof price === 'string' && DECIMAL.test(price.trim()) @@ -150,9 +189,9 @@ const video: Rule = (node) => { if (!typesOf(node).includes('VideoObject')) return [] const problems = missing(node, ['name', 'thumbnailUrl', 'uploadDate']) const { uploadDate } = node - if (!isBlank(uploadDate) && !FULL_DATE_TIME.test(String(uploadDate))) { + if (!isBlank(uploadDate) && !isoDate(uploadDate)?.hasTime) { problems.push( - `VideoObject uploadDate ${show(uploadDate)} lacks a time and offset` + `VideoObject uploadDate ${show(uploadDate)} is not a real date-time with offset` ) } return problems @@ -161,12 +200,9 @@ const video: Rule = (node) => { const event: Rule = (node) => { if (!typesOf(node).includes('Event')) return [] const { startDate } = node - const isIsoDate = - typeof startDate === 'string' && - (DATE_ONLY.test(startDate) || FULL_DATE_TIME.test(startDate)) - return isIsoDate + return isoDate(startDate) ? [] - : [`Event startDate ${show(startDate)} is not ISO 8601 with offset`] + : [`Event startDate ${show(startDate)} is not a real ISO 8601 date`] } const imagesAreImages: Rule = (node) => { @@ -248,9 +284,10 @@ const webPage: Rule = (node, page) => { const idsOnSite: Rule = (node) => { const id = node['@id'] if (typeof id !== 'string') return [] - return id.startsWith(`${SITE_ORIGIN}/`) - ? [] - : [`@id ${id} is not an absolute ${SITE_ORIGIN} URL`] + if (id.includes('#') && !isOnSite(id)) { + return [`fragment @id ${id} is not on ${SITE_ORIGIN}`] + } + return isAbsoluteHttpUrl(id) ? [] : [`@id ${id} is not an absolute URL`] } const isPlaceholder = (value: unknown): boolean => @@ -299,32 +336,39 @@ export function validateHtml(html: string, pagePath: string): Violation[] { const definedIds = new Set() const referencedIds: string[] = [] - const nodesById = new Map() + const stubsById = new Map() + const definitionsById = new Map() for (const block of blocks) { const { defined, references } = collectGraphIds(block) defined.forEach((id) => definedIds.add(id)) referencedIds.push(...references) eachNode(block, (node) => { const id = node['@id'] - if (typeof id !== 'string' || isIdReference(node)) return - if (nodesById.has(id)) { + if (typeof id !== 'string') return + if (isIdReference(node)) { + if ('@type' in node && !stubsById.has(id)) stubsById.set(id, node) + return + } + if (definitionsById.has(id)) { violations.push({ rule: 'duplicateIds', message: `@id ${id} defined twice` }) } - nodesById.set(id, node) + definitionsById.set(id, node) }) } const page: PageContext = { pagePath, canonical: html.match(CANONICAL)?.[1], - nodesById + nodesById: new Map([...stubsById, ...definitionsById]) } for (const block of blocks) { eachNode(block, (node) => { + const isReference = pointsElsewhere(node, page) for (const [rule, check] of Object.entries(RULES)) { + if (isReference && !REFERENCE_RULES.has(rule)) continue for (const message of check(node, page)) { violations.push({ rule, message: `${locatorOf(node)}: ${message}` }) } @@ -333,7 +377,7 @@ export function validateHtml(html: string, pagePath: string): Violation[] { } for (const id of referencedIds) { - if (!definedIds.has(id)) { + if (!definedIds.has(id) && isOnSite(id)) { violations.push({ rule: 'idRefs', message: `unresolved @id: ${id}` }) } } @@ -363,12 +407,23 @@ export function main(distDir: string): number { return 1 } - const failures = files.flatMap((file) => { - const pagePath = pagePathOf(distDir, file) - return validateHtml(readFileSync(file, 'utf8'), pagePath).map( - (violation) => ({ pagePath, ...violation }) + const pages = files.map((file) => ({ + pagePath: pagePathOf(distDir, file), + html: readFileSync(file, 'utf8') + })) + if (!pages.some(({ html }) => CANONICAL.test(html))) { + console.error( + `JSON-LD validation found no canonical link in ${distDir}, so the WebPage check cannot run. Build with build:e2e.` ) - }) + return 1 + } + + const failures = pages.flatMap(({ pagePath, html }) => + validateHtml(html, pagePath).map((violation) => ({ + pagePath, + ...violation + })) + ) if (failures.length > 0) { console.error(`JSON-LD validation failed (${failures.length} issue(s)):`) for (const { pagePath, rule, message } of failures) { @@ -377,8 +432,11 @@ export function main(distDir: string): number { return 1 } + const withJsonLd = pages.filter(({ html }) => + html.includes('application/ld+json') + ).length process.stdout.write( - `JSON-LD validation passed across ${files.length} page(s).\n` + `JSON-LD validation passed across ${pages.length} page(s), ${withJsonLd} with JSON-LD.\n` ) return 0 } diff --git a/apps/website/src/utils/jsonLd.ts b/apps/website/src/utils/jsonLd.ts index 5d9c76785bf..3b078e37d34 100644 --- a/apps/website/src/utils/jsonLd.ts +++ b/apps/website/src/utils/jsonLd.ts @@ -515,14 +515,6 @@ export function buildPageGraph( ) } -export function isIdReference(record: Record): boolean { - const keys = Object.keys(record) - return ( - typeof record['@id'] === 'string' && - keys.every((key) => key === '@id' || key === '@type') - ) -} - export function collectGraphIds(value: unknown): { defined: Set references: string[] @@ -538,7 +530,7 @@ export function collectGraphIds(value: unknown): { const record = node as Record const id = record['@id'] if (typeof id === 'string') { - if (isIdReference(record)) references.push(id) + if (Object.keys(record).length === 1) references.push(id) else defined.add(id) } Object.values(record).forEach(walk) From f80cb8f59bf1c761192d316ade91af5fb54c0ab1 Mon Sep 17 00:00:00 2001 From: Maanil Verma Date: Tue, 6 Oct 2026 17:22:43 +0530 Subject: [PATCH 8/8] fix(website): reject unknown @type and non-schema.org @context in validate-jsonld A typo in @type switched off every rule for that node and the gate still passed. The validator now fails any @type outside KNOWN_TYPES, which lists the types the site emits, and any top-level block whose @context is not schema.org. --- apps/website/scripts/validate-jsonld.test.ts | 58 +++++++++++++++++++- apps/website/scripts/validate-jsonld.ts | 52 +++++++++++++++++- 2 files changed, 108 insertions(+), 2 deletions(-) diff --git a/apps/website/scripts/validate-jsonld.test.ts b/apps/website/scripts/validate-jsonld.test.ts index 611aeeebfcd..2bb230506f8 100644 --- a/apps/website/scripts/validate-jsonld.test.ts +++ b/apps/website/scripts/validate-jsonld.test.ts @@ -190,7 +190,22 @@ describe('validateHtml', () => { rule: 'idRefs', bad: { ...video, isPartOf: { '@id': `${site}/#missing` } } }, - { rule: 'duplicateIds', bad: { ...webPage, name: 'Again' } } + { rule: 'duplicateIds', bad: { ...webPage, name: 'Again' } }, + { rule: 'knownTypes', bad: { '@type': 'Frobnicator', banana: 'yes' } }, + { rule: 'knownTypes', bad: { ...product, '@type': 'Prodcut' } }, + { + rule: 'knownTypes', + bad: { + '@type': 'CollectionPaige', + '@id': `${site}/other/#webpage`, + url: `${site}/other/` + } + }, + { + rule: 'knownTypes', + bad: { ...product, '@type': ['Product', 'Prodcut'] } + }, + { rule: 'knownTypes', bad: { '@type': 'Prodcut', '@id': product['@id'] } } ])('flags $rule', ({ rule, bad }) => { expect(rulesHit([bad])).toContain(rule) }) @@ -373,6 +388,47 @@ describe('validateHtml', () => { ]) }) + it('names the unknown type and how to allow it', () => { + expect(messages([{ '@type': 'Prodcut', name: 'Comfy Cloud' }])).toEqual([ + 'Prodcut: unknown @type "Prodcut": add it to KNOWN_TYPES if intended' + ]) + }) + + function contextRules(context: unknown): string[] { + const block = { '@context': context, '@graph': [org, webPage] } + return validateHtml( + ``, + '/example/' + ).map(({ rule }) => rule) + } + + it.for([ + { context: undefined, rules: ['context'] }, + { context: 'http://example.com/', rules: ['context'] }, + { context: 'https://schema.org.evil.com', rules: ['context'] }, + { context: { '@vocab': 'https://schema.org/' }, rules: ['context'] }, + { context: 'https://schema.org', rules: [] }, + { context: 'http://schema.org', rules: [] }, + { context: 'https://schema.org/', rules: [] }, + { context: 'http://schema.org/', rules: [] } + ])('checks a top-level @context of $context', ({ context, rules }) => { + expect(contextRules(context)).toEqual(rules) + }) + + it('checks the @context of each node in a top-level array', () => { + const blocks = [ + { '@context': 'https://schema.org', ...org }, + { ...webPage } + ] + const markup = `` + expect(validateHtml(markup, '/example/')).toEqual([ + { + rule: 'context', + message: '@context undefined is not https://schema.org' + } + ]) + }) + it('reports unparseable JSON-LD', () => { expect( validateHtml('', '/') diff --git a/apps/website/scripts/validate-jsonld.ts b/apps/website/scripts/validate-jsonld.ts index c71fc2c81ea..7e646bafcd4 100644 --- a/apps/website/scripts/validate-jsonld.ts +++ b/apps/website/scripts/validate-jsonld.ts @@ -21,7 +21,13 @@ const DECIMAL = /^\d+(\.\d+)?$/ const MODEL_PAGE = new RegExp( `^(?:${NON_DEFAULT_LOCALE_PREFIXES.join('|')})?/(?:hub/)?models/(?!local/)[^/]+/` ) -const REFERENCE_RULES = new Set(['honesty', 'idsOnSite', 'noPlaceholders']) +const SCHEMA_ORG_CONTEXT = /^https?:\/\/schema\.org\/?$/ +const REFERENCE_RULES = new Set([ + 'honesty', + 'idsOnSite', + 'noPlaceholders', + 'knownTypes' +]) const WEB_PAGE_TYPES = [ 'WebPage', 'AboutPage', @@ -29,6 +35,32 @@ const WEB_PAGE_TYPES = [ 'CollectionPage', 'ProfilePage' ] +const KNOWN_TYPES = new Set([ + ...WEB_PAGE_TYPES, + 'Answer', + 'Article', + 'Brand', + 'BreadcrumbList', + 'ContactPoint', + 'Event', + 'FAQPage', + 'ImageObject', + 'ItemList', + 'LearningResource', + 'ListItem', + 'Offer', + 'Organization', + 'Person', + 'Place', + 'Product', + 'Question', + 'SoftwareApplication', + 'SoftwareSourceCode', + 'UnitPriceSpecification', + 'VideoObject', + 'VirtualLocation', + 'WebSite' +]) type JsonLdRecord = Record @@ -299,7 +331,15 @@ const noPlaceholders: Rule = (node) => .filter(([, value]) => asList(value).some(isPlaceholder)) .map(([key, value]) => `${key} is ${JSON.stringify(value)}`) +const knownTypes: Rule = (node) => + asList(node['@type']) + .filter((type) => typeof type !== 'string' || !KNOWN_TYPES.has(type)) + .map( + (type) => `unknown @type ${show(type)}: add it to KNOWN_TYPES if intended` + ) + const RULES: Record = { + knownTypes, honesty, offer, product, @@ -338,6 +378,16 @@ export function validateHtml(html: string, pagePath: string): Violation[] { const referencedIds: string[] = [] const stubsById = new Map() const definitionsById = new Map() + for (const topLevel of blocks.flat()) { + const context = isRecord(topLevel) ? topLevel['@context'] : undefined + if (typeof context !== 'string' || !SCHEMA_ORG_CONTEXT.test(context)) { + violations.push({ + rule: 'context', + message: `@context ${show(context)} is not https://schema.org` + }) + } + } + for (const block of blocks) { const { defined, references } = collectGraphIds(block) defined.forEach((id) => definedIds.add(id))