diff --git a/apps/website/scripts/validate-jsonld.test.ts b/apps/website/scripts/validate-jsonld.test.ts new file mode 100644 index 00000000000..2bb230506f8 --- /dev/null +++ b/apps/website/scripts/validate-jsonld.test.ts @@ -0,0 +1,510 @@ +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 { websiteRoot } from '@website/paths' + +import { main, 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: string | null = canonical) { + const graph = { '@context': 'https://schema.org', '@graph': nodes } + 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[] { + return validateHtml(html([org, webPage, ...nodes]), pagePath).map( + ({ rule }) => rule + ) +} + +const offer = (price: unknown, priceCurrency: unknown = 'USD') => ({ + '@type': 'Offer', + price, + priceCurrency +}) +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`, + contentUrl: `${site}/tutorial.mp4`, + uploadDate: '2026-07-16T00:00:00+00:00' +} +const crumbs = (items: unknown[]) => ({ + '@type': 'BreadcrumbList', + '@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([ + { rule: 'honesty', bad: { '@type': 'AggregateRating', ratingValue: 5 } }, + { 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(-20) }, + { 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 } }, + { 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 } }, + ...[ + '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` } }, + { + rule: 'imagesAreImages', + bad: { ...product, image: `${site}/a.mp4#t=1` } + }, + { + rule: 'imagesAreImages', + bad: { ...video, thumbnailUrl: `${site}/a.webm` } + }, + { + rule: 'imagesAreImages', + bad: { '@type': 'ImageObject', url: `${site}/a.mp4` } + }, + { + rule: 'imagesAreImages', + bad: { '@type': 'ImageObject', contentUrl: `${site}/a.mov?v=1` } + }, + { + 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([{ ...home, item: { '@id': '/' } }, page]) + }, + { rule: 'breadcrumb', bad: crumbs([{ ...home, name: undefined }, page]) }, + { rule: 'breadcrumb', bad: crumbs([home, null, page]) }, + { + rule: 'itemList', + bad: { + '@type': 'ItemList', + numberOfItems: 2, + 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', + 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: 'noPlaceholders', + bad: { ...video, description: '[object Object]' } + }, + { + rule: 'idRefs', + bad: { ...video, isPartOf: { '@id': `${site}/#missing` } } + }, + { 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) + }) + + 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': 'Event', + 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]), + { + '@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('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] }, + { + shape: 'a Thing item with an @id', + 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 }) => { + 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([ + { + '@type': 'Offer', + priceSpecification: { + '@type': 'UnitPriceSpecification', + price: 10, + priceCurrency: 'USD' + } + } + ]) + ).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('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([ + 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 markup = html([org, webPage]).replace( + ``, + `` + ) + expect(validateHtml(markup, '/').map(({ rule }) => rule)).toEqual([ + 'webPage', + 'webPage' + ]) + }) + + 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('', '/') + ).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: 'pages with no canonical', + pages: { a: html([org, webPage], null) }, + status: 1 + }, + { + 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('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({}) + 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') + }) +}) diff --git a/apps/website/scripts/validate-jsonld.ts b/apps/website/scripts/validate-jsonld.ts index 5dbdfa3c47e..7e646bafcd4 100644 --- a/apps/website/scripts/validate-jsonld.ts +++ b/apps/website/scripts/validate-jsonld.ts @@ -1,25 +1,83 @@ -import { readFileSync, readdirSync } from 'node:fs' -import { join } from 'node:path' +import { existsSync, readFileSync, readdirSync } from 'node:fs' +import { join, relative, sep } from 'node:path' +import { NON_DEFAULT_LOCALE_PREFIXES } from '@/config/locales' 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 = + /]*\brel=["']canonical["'])[^>]*\bhref=["']([^"']+)["']/i +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|\[object Object\])$/ +const DECIMAL = /^\d+(\.\d+)?$/ +const MODEL_PAGE = new RegExp( + `^(?:${NON_DEFAULT_LOCALE_PREFIXES.join('|')})?/(?:hub/)?models/(?!local/)[^/]+/` +) +const SCHEMA_ORG_CONTEXT = /^https?:\/\/schema\.org\/?$/ +const REFERENCE_RULES = new Set([ + 'honesty', + 'idsOnSite', + 'noPlaceholders', + 'knownTypes' +]) +const WEB_PAGE_TYPES = [ + 'WebPage', + 'AboutPage', + 'ContactPage', + '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' +]) -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,102 +86,411 @@ 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' - }) - } - if ( - types.includes('Offer') && - (!hasValidPrice(record) || !record.priceCurrency) - ) { - violations.push({ - file, - message: 'Offer missing priceCurrency or a concrete price' - }) - } - Object.values(record).forEach(walk) +function asList(value: unknown): unknown[] { + if (value == null) return [] + return Array.isArray(value) ? value : [value] +} + +function isBlank(value: unknown): boolean { + if (Array.isArray(value)) return value.every(isBlank) + return value == null || (typeof value === 'string' && value.trim() === '') +} + +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 + .filter((field) => isBlank(node[field])) + .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'] + if (isIdReference(value) && typeof id === 'string') { + return page.nodesById.get(id) ?? value } - walk(value) + return value } -function validateFile(file: string): Violation[] { - const html = readFileSync(file, 'utf8') - const violations: Violation[] = [] - const definedIds = new Set() - const referencedIds: string[] = [] +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()) +} +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 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 (MODEL_PAGE.test(page.pagePath) && Number(price) === 0) { + return [`model page Offer has a zero price ${show(price)}`] + } + return [] +} + +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 ${show(node.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) && !isoDate(uploadDate)?.hasTime) { + problems.push( + `VideoObject uploadDate ${show(uploadDate)} is not a real date-time with offset` + ) + } + return problems +} + +const event: Rule = (node) => { + if (!typesOf(node).includes('Event')) return [] + const { startDate } = node + return isoDate(startDate) + ? [] + : [`Event startDate ${show(startDate)} is not a real ISO 8601 date`] +} + +const imagesAreImages: Rule = (node) => { + const isImageObject = typesOf(node).includes('ImageObject') + const urls = [ + ...asList(node.image), + ...asList(node.thumbnailUrl), + ...(isImageObject ? [...asList(node.url), ...asList(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}`) +} + +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) + 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) => { + if (!typesOf(node).includes('ItemList') || !('numberOfItems' in node)) { + return [] + } + const count = asList(node.itemListElement).length + return node.numberOfItems === count + ? [] + : [`ItemList numberOfItems ${show(node.numberOfItems)} but ${count} listed`] +} + +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 ${show(node.url)} does not match canonical`) + } + return problems +} + +const idsOnSite: Rule = (node) => { + const id = node['@id'] + if (typeof id !== 'string') return [] + 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 => + typeof value === 'string' && + (value.trim() === '' || PLACEHOLDER.test(value.trim())) + +const noPlaceholders: Rule = (node) => + Object.entries(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, + 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 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)) referencedIds.push(...references) + eachNode(block, (node) => { + const id = node['@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` + }) + } + definitionsById.set(id, node) + }) + } + + const page: PageContext = { + pagePath, + canonical: html.match(CANONICAL)?.[1], + 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}` }) + } + } + }) } for (const id of referencedIds) { - if (!definedIds.has(id)) { - violations.push({ file, message: `unresolved @id reference: ${id}` }) + if (!definedIds.has(id) && isOnSite(id)) { + violations.push({ rule: 'idRefs', message: `unresolved @id: ${id}` }) } } - return violations } -function main(): void { - const files = htmlFiles(DIST_DIR) +function htmlFiles(dir: string): string[] { + if (!existsSync(dir)) return [] + 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$/, '')}` +} + +export function main(distDir: string): number { + 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) + return 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 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) { + console.error(` ${pagePath} [${rule}]: ${message}`) } - process.exit(1) + 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 } -main() +if (isDirectExecution(process.argv[1], import.meta.filename)) { + process.exitCode = main(join(process.cwd(), 'dist')) +}