base-themes 0.1.2 → 0.1.3

package/scripts/verify-launch-readiness.mjs

@@ -0,0 +1,415 @@
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import packageJson from '../package.json' with { type: 'json' }
+
+const requiredScripts = [
+  'registry:check',
+  'tokens:check',
+  'seo:check',
+  'analytics:check',
+  'community:check',
+  'community:issues',
+  'release:announce',
+  'telemetry:collect',
+  'telemetry:check',
+  'telemetry:fixtures',
+  'package:smoke',
+  'bundle:report',
+  'launch:status',
+  'launch:actions',
+  'launch:campaign',
+]
+
+const requiredReleaseLinks = {
+  repo: 'https://github.com/markbang/base-themes',
+  docs: 'https://base-themes.bangwu.me',
+  registry: 'https://base-themes.bangwu.me/registry/registry.json',
+  cli: 'https://base-themes.bangwu.me/docs/cli',
+  blocks: 'https://base-themes.bangwu.me/blocks',
+  llms: 'https://base-themes.bangwu.me/llms.txt',
+  llmsFull: 'https://base-themes.bangwu.me/llms-full.txt',
+  fork: 'https://github.com/markbang/base-themes/fork',
+  showAndTell: 'https://github.com/markbang/base-themes/discussions/new?category=show-and-tell',
+  featureRequest: 'https://github.com/markbang/base-themes/issues/new?template=feature_request.yml',
+  gallerySubmission: 'https://github.com/markbang/base-themes/issues/new?template=gallery_submission.yml',
+  goodFirstIssues: 'https://github.com/markbang/base-themes/issues?q=is%3Aissue+state%3Aopen+label%3A%22type%3A+good+first+issue%22',
+}
+
+function fail(message, details = []) {
+  console.error(`Launch readiness invalid: ${message}`)
+  for (const detail of details) console.error(`- ${detail}`)
+  process.exit(1)
+}
+
+const missingScripts = requiredScripts.filter((script) => !packageJson.scripts?.[script])
+if (missingScripts.length > 0) {
+  fail('package.json is missing required release/adoption scripts', missingScripts)
+}
+
+const releaseChecklist = readFileSync('RELEASE.md', 'utf8')
+const releaseKit = readFileSync('docs/release-announcement-kit.md', 'utf8')
+const adoptionDashboard = readFileSync('docs/adoption-dashboard.md', 'utf8')
+
+const requiredReleaseChecklistPhrases = [
+  'npm run launch:check',
+  'npm run release:announce -- --json',
+  'npm run community:issues -- --json',
+  'npm run telemetry:collect',
+  'npm run telemetry:check',
+  'npm run telemetry:check -- --live',
+  'npm run telemetry:fixtures',
+  'npm run launch:status',
+  'npm run launch:status -- --live',
+  'npm run launch:actions',
+  'npm run launch:actions -- --live',
+  'npm run launch:campaign',
+  'public adoption gate',
+]
+const missingReleaseChecklistPhrases = requiredReleaseChecklistPhrases.filter((phrase) => !releaseChecklist.includes(phrase))
+if (missingReleaseChecklistPhrases.length > 0) {
+  fail('RELEASE.md is missing launch/adoption checklist coverage', missingReleaseChecklistPhrases)
+}
+
+const requiredReleaseKitPhrases = [
+  'npm run launch:check',
+  'npm run launch:actions',
+  'npm run launch:campaign',
+  'at least three external channels',
+  'star the repo',
+  'fork it',
+  'Show and tell Discussion',
+  'community gallery issue template',
+  '24 hours, 7 days, and 30 days',
+  'T+1 day',
+  'T+7 days',
+  'T+30 days',
+  'shareAssets',
+  'signalTrends',
+  'refuses to overwrite',
+  '--force',
+  'refuses to save a campaign pack when telemetry is incomplete',
+  '--allow-incomplete',
+]
+const missingReleaseKitPhrases = requiredReleaseKitPhrases.filter((phrase) => !releaseKit.includes(phrase))
+if (missingReleaseKitPhrases.length > 0) {
+  fail('release announcement kit is missing launch/adoption guidance', missingReleaseKitPhrases)
+}
+
+const requiredForkWorkflowPhrases = [
+  'Fork-To-First-Change',
+  'Fork-to-first-change',
+  'npm run example:theme-customization:build',
+  'npm run example:registry-copy -- plan button select block:dashboard-shell theme:enterprise --json',
+]
+const readme = readFileSync('README.md', 'utf8')
+const staticDocs = readFileSync('src/docs/StaticDocsPages.tsx', 'utf8')
+const missingForkWorkflowPhrases = requiredForkWorkflowPhrases.filter((phrase) => ![readme, staticDocs, releaseKit].some((source) => source.includes(phrase)))
+if (missingForkWorkflowPhrases.length > 0) {
+  fail('fork-to-first-change workflow must be documented before asking users for forks', missingForkWorkflowPhrases)
+}
+
+const requiredGatePhrases = [
+  'Current public adoption score: **1/4**',
+  'at least three of the four public signals pass',
+  'Do not mark the strategy complete while the adoption score is below `3/4`',
+  'generated under `research/`',
+  'intentionally not required for CI or release-readiness checks',
+  'record fields for external post URLs plus T+1, T+7, and T+30 telemetry evidence',
+]
+const missingGatePhrases = requiredGatePhrases.filter((phrase) => !adoptionDashboard.includes(phrase))
+if (missingGatePhrases.length > 0) {
+  fail('adoption dashboard is missing explicit non-completion gate language', missingGatePhrases)
+}
+
+const requiredDashboardReleaseChecks = [
+  'npm run registry:check',
+  'npm run lint',
+  'npm run test',
+  'npm run build',
+  'npm run seo:check',
+  'npm run bundle:report',
+  'npm run analytics:check',
+  'npm run community:check',
+  'npm run telemetry:check',
+  'npm run telemetry:check -- --live',
+  'npm run telemetry:fixtures',
+  'npm run launch:check',
+  'npm run launch:status',
+  'npm run launch:status -- --live',
+  'npm run launch:actions',
+  'npm run launch:actions -- --live',
+  'npm run launch:campaign',
+  'npm run package:smoke',
+  'npm pack --dry-run',
+]
+const missingDashboardReleaseChecks = requiredDashboardReleaseChecks.filter((check) => !adoptionDashboard.includes(check))
+if (missingDashboardReleaseChecks.length > 0) {
+  fail('adoption dashboard release-readiness commands are not aligned with the current launch gate', missingDashboardReleaseChecks)
+}
+
+let announcement
+try {
+  announcement = JSON.parse(execFileSync('node', ['scripts/render-release-announcement.mjs', '--json'], { encoding: 'utf8' }))
+} catch (error) {
+  fail('release announcement must render valid JSON', [error.message])
+}
+
+let launchStatus
+try {
+  launchStatus = JSON.parse(execFileSync('node', ['scripts/render-launch-status.mjs', '--json'], { encoding: 'utf8' }))
+} catch (error) {
+  fail('launch status must render valid JSON from the latest telemetry report', [error.message])
+}
+
+let launchActions
+try {
+  launchActions = JSON.parse(execFileSync('node', ['scripts/render-launch-actions.mjs', '--json'], { encoding: 'utf8' }))
+} catch (error) {
+  fail('launch actions must render valid JSON from the latest telemetry and announcement data', [error.message])
+}
+
+if (launchStatus.completionThreshold !== 3 || launchStatus.signalCount !== 4) {
+  fail('launch status must preserve the public adoption gate shape', [`got ${launchStatus.completionThreshold}/${launchStatus.signalCount}`])
+}
+
+if (typeof launchStatus.externallyValidated !== 'boolean' || typeof launchStatus.publicTelemetryComplete !== 'boolean' || !Array.isArray(launchStatus.telemetryErrors) || !Array.isArray(launchStatus.missingSignals) || !Array.isArray(launchStatus.signalTrends)) {
+  fail('launch status JSON must include externallyValidated, publicTelemetryComplete, telemetryErrors, missingSignals, and signalTrends fields')
+}
+
+if (launchActions.completionThreshold !== 3 || launchActions.signalCount !== 4 || typeof launchActions.publicTelemetryComplete !== 'boolean' || !Array.isArray(launchActions.telemetryErrors) || !Array.isArray(launchActions.actions) || !Array.isArray(launchActions.signalTrends)) {
+  fail('launch actions JSON must preserve the public adoption gate and expose telemetry completeness, signal trends, plus an action list')
+}
+
+if (!Array.isArray(launchActions.shareAssets) || launchActions.shareAssets.length < 4) {
+  fail('launch actions JSON must include share assets from the release announcement pack')
+}
+
+if (!Array.isArray(launchActions.channelChecklist) || launchActions.channelChecklist.length < 4) {
+  fail('launch actions JSON must include the release channel checklist')
+}
+
+if (!Array.isArray(launchActions.promotionWave) || launchActions.promotionWave.length < 4) {
+  fail('launch actions JSON must include a channel promotion wave')
+}
+
+if (!Array.isArray(launchActions.campaignChecklist) || launchActions.campaignChecklist.length < 7) {
+  fail('launch actions JSON must include a campaign execution checklist')
+}
+
+const launchActionShareAssetIds = new Set(launchActions.shareAssets.map((asset) => asset.id))
+const launchActionChannelsMissingShareAssets = launchActions.channelChecklist.filter((item) => !Array.isArray(item.shareAssetIds) || item.shareAssetIds.length === 0)
+if (launchActionChannelsMissingShareAssets.length > 0) {
+  fail('launch action channel checklist entries must include shareAssetIds', launchActionChannelsMissingShareAssets.map((item) => item.channel ?? '(unknown channel)'))
+}
+
+const incompletePromotionWave = launchActions.promotionWave.filter((item) => !item.channel || !item.copy || !item.primaryLink || !item.action || !item.measure || !Array.isArray(item.targetSignals) || item.targetSignals.length === 0 || !Array.isArray(item.shareAssets) || item.shareAssets.length === 0)
+if (incompletePromotionWave.length > 0) {
+  fail('launch action promotion wave entries must include copy, target signals, primary links, share assets, actions, and measures', incompletePromotionWave.map((item) => item.channel ?? '(unknown channel)'))
+}
+
+const unknownLaunchActionShareAssetIds = launchActions.channelChecklist.flatMap((item) => item.shareAssetIds ?? []).filter((id) => !launchActionShareAssetIds.has(id))
+if (unknownLaunchActionShareAssetIds.length > 0) {
+  fail('launch action channel checklist references unknown share asset ids', unknownLaunchActionShareAssetIds)
+}
+
+const unknownPromotionWaveShareAssetIds = launchActions.promotionWave.flatMap((item) => item.shareAssetIds ?? []).filter((id) => !launchActionShareAssetIds.has(id))
+if (unknownPromotionWaveShareAssetIds.length > 0) {
+  fail('launch action promotion wave references unknown share asset ids', unknownPromotionWaveShareAssetIds)
+}
+
+const incompleteCampaignChecklist = launchActions.campaignChecklist.filter((item) => !item.phase || !item.task || !item.evidence || !Array.isArray(item.recordFields) || item.recordFields.length === 0)
+if (incompleteCampaignChecklist.length > 0) {
+  fail('launch action campaign checklist entries must include phase, task, evidence, and record fields', incompleteCampaignChecklist.map((item) => item.phase ?? '(unknown phase)'))
+}
+
+const missingCampaignChannels = launchActions.promotionWave.map((item) => item.channel).filter((channel) => !launchActions.campaignChecklist.some((item) => item.channel === channel))
+if (missingCampaignChannels.length > 0) {
+  fail('launch action campaign checklist must include every promotion wave channel', missingCampaignChannels)
+}
+
+const campaignCommandText = launchActions.campaignChecklist.flatMap((item) => item.commands ?? []).join('\n')
+const missingCampaignCommands = ['npm run launch:check', 'npm run launch:status -- --live', 'npm run telemetry:collect', 'npm run launch:actions'].filter((command) => !campaignCommandText.includes(command))
+if (missingCampaignCommands.length > 0) {
+  fail('launch action campaign checklist is missing required launch and measurement commands', missingCampaignCommands)
+}
+
+const missingLaunchActionIds = launchStatus.missingSignals
+  .map((signal) => signal.id)
+  .filter((id) => !launchActions.actions.some((action) => action.signalId === id))
+if (missingLaunchActionIds.length > 0) {
+  fail('launch actions must include one actionable block for each missing public signal', missingLaunchActionIds)
+}
+
+const forkAction = launchActions.actions.find((action) => action.signalId === 'forks')
+if (forkAction && !forkAction.commands?.includes('npm run example:theme-customization:build')) {
+  fail('launch actions must route the missing fork signal to the Fork-to-first-change workflow')
+}
+
+const missingAnnouncementLinks = Object.entries(requiredReleaseLinks)
+  .filter(([key, value]) => announcement.links?.[key] !== value)
+  .map(([key]) => key)
+if (missingAnnouncementLinks.length > 0) {
+  fail('release announcement JSON is missing direct launch/adoption links', missingAnnouncementLinks)
+}
+
+const announcementText = [
+  announcement.githubRelease,
+  announcement.social,
+  announcement.forum,
+  announcement.directory,
+  ...(announcement.callsToAction ?? []),
+].join('\n')
+const missingAnnouncementText = Object.values(requiredReleaseLinks).filter((link) => !announcementText.includes(link))
+if (missingAnnouncementText.length > 0) {
+  fail('release announcement copy is missing direct launch/adoption URLs', missingAnnouncementText)
+}
+
+const requiredAnnouncementWorkflowText = [
+  'Fork-to-first-change',
+  'npm run example:theme-customization:build',
+  'npm run example:registry-copy -- plan button select block:dashboard-shell theme:enterprise --json',
+  'Good-first issues to publish with this release',
+]
+const missingAnnouncementWorkflowText = requiredAnnouncementWorkflowText.filter((text) => !announcementText.includes(text))
+if (missingAnnouncementWorkflowText.length > 0) {
+  fail('release announcement copy must turn fork asks into a verifiable first-change workflow', missingAnnouncementWorkflowText)
+}
+
+const requiredCommands = [
+  'npm install base-themes @base-ui/react react react-dom',
+  'npx base-themes plan button select block:dashboard-shell theme:enterprise --json',
+  'npx base-themes add button select block:dashboard-shell theme:enterprise --target . --dry-run --json',
+  'npx base-themes doctor . --json',
+]
+const missingCommands = requiredCommands.filter((command) => !announcement.commands?.includes(command))
+if (missingCommands.length > 0) {
+  fail('release announcement commands are missing install, source-copy, or doctor actions', missingCommands)
+}
+
+const requiredChannels = ['GitHub Release', 'X / Bluesky', 'Hacker News / Reddit', 'Product / devtool directories']
+const missingChannels = requiredChannels.filter((channel) => !announcement.channelChecklist?.some((item) => item.channel === channel))
+if (missingChannels.length > 0) {
+  fail('release announcement JSON is missing channel tracking checklist entries', missingChannels)
+}
+
+const incompleteChannels = announcement.channelChecklist.filter((item) => !item.action || !item.measure || !item.primaryLink)
+if (incompleteChannels.length > 0) {
+  fail('release channel checklist entries must include action, measure, and primaryLink', incompleteChannels.map((item) => item.channel ?? '(unknown channel)'))
+}
+
+const channelsMissingShareAssets = announcement.channelChecklist.filter((item) => !Array.isArray(item.shareAssetIds) || item.shareAssetIds.length === 0)
+if (channelsMissingShareAssets.length > 0) {
+  fail('release channel checklist entries must include shareAssetIds for execution-ready promotion', channelsMissingShareAssets.map((item) => item.channel ?? '(unknown channel)'))
+}
+
+const unattributedChannels = announcement.channelChecklist.filter((item) => !['utm_campaign', 'utm_source', 'utm_medium', 'utm_content'].every((param) => item.primaryLink.includes(`${param}=`)))
+if (unattributedChannels.length > 0) {
+  fail('release channel checklist primary links must include launch attribution parameters', unattributedChannels.map((item) => item.channel ?? '(unknown channel)'))
+}
+
+const channelCopyByName = {
+  'GitHub Release': announcement.githubRelease,
+  'X / Bluesky': announcement.social,
+  'Hacker News / Reddit': announcement.forum,
+  'Product / devtool directories': announcement.directory,
+}
+const channelsMissingAttributedCopy = announcement.channelChecklist.filter((item) => !channelCopyByName[item.channel]?.includes(item.primaryLink))
+if (channelsMissingAttributedCopy.length > 0) {
+  fail('release channel copy must include its attributed primaryLink, not only the checklist', channelsMissingAttributedCopy.map((item) => item.channel ?? '(unknown channel)'))
+}
+
+const channelsMissingStarAsk = announcement.channelChecklist.filter((item) => !/star (the )?repo/i.test(channelCopyByName[item.channel] ?? ''))
+if (channelsMissingStarAsk.length > 0) {
+  fail('release channel copy must ask for a repo star after trying the package', channelsMissingStarAsk.map((item) => item.channel ?? '(unknown channel)'))
+}
+
+if (!announcement.attribution?.campaign || !announcement.attribution?.parameters?.includes('utm_campaign')) {
+  fail('release announcement JSON must expose launch attribution metadata')
+}
+
+if (!Array.isArray(announcement.shareAssets) || announcement.shareAssets.length < 4) {
+  fail('release announcement JSON must include share assets for screenshots, block routes, and docs routes')
+}
+
+const invalidShareAssets = announcement.shareAssets.filter((asset) => !asset.id || !asset.title || !asset.type || !asset.url?.includes('utm_campaign=') || !asset.imageUrl?.startsWith('https://base-themes.bangwu.me/previews/') || !asset.use)
+if (invalidShareAssets.length > 0) {
+  fail('release share assets must include id, type, attributed URL, preview image URL, and usage guidance', invalidShareAssets.map((asset) => asset.id ?? asset.title ?? '(untitled)'))
+}
+
+const requiredShareAssetIds = ['dashboard-shell-block', 'enterprise-theme-preview', 'base-ui-vs-shadcn', 'cli-doctor-workflow']
+const missingShareAssets = requiredShareAssetIds.filter((id) => !announcement.shareAssets.some((asset) => asset.id === id))
+if (missingShareAssets.length > 0) {
+  fail('release share assets must cover block, theme, forum, and directory launch surfaces', missingShareAssets)
+}
+
+const shareAssetIds = new Set(announcement.shareAssets.map((asset) => asset.id))
+const unknownChecklistShareAssets = announcement.channelChecklist.flatMap((item) => item.shareAssetIds ?? []).filter((id) => !shareAssetIds.has(id))
+if (unknownChecklistShareAssets.length > 0) {
+  fail('release channel checklist references unknown share asset ids', unknownChecklistShareAssets)
+}
+
+const requiredChannelMeasures = ['stars', 'forks', 'issues', 'registry', 'npm']
+const channelMeasureText = announcement.channelChecklist.map((item) => item.measure).join('\n').toLowerCase()
+const missingChannelMeasures = requiredChannelMeasures.filter((measure) => !channelMeasureText.includes(measure))
+if (missingChannelMeasures.length > 0) {
+  fail('release channel checklist must map posts back to public adoption and registry signals', missingChannelMeasures)
+}
+
+let seedIssues
+try {
+  seedIssues = JSON.parse(execFileSync('node', ['scripts/render-contributor-issues.mjs', '--json'], { encoding: 'utf8' }))
+} catch (error) {
+  fail('contributor seed issues must render valid JSON', [error.message])
+}
+
+if (!Array.isArray(seedIssues) || seedIssues.length < 6) {
+  fail('launch should have at least six contributor seed issues ready', [`got ${Array.isArray(seedIssues) ? seedIssues.length : 'non-array output'}`])
+}
+
+const goodFirstIssues = seedIssues.filter((issue) => issue.labels?.includes('type: good first issue'))
+if (goodFirstIssues.length < 4) {
+  fail('launch should have several good-first issue URLs ready before asking for contributors', [`got ${goodFirstIssues.length}`])
+}
+
+if (!Array.isArray(announcement.recommendedGoodFirstIssues) || announcement.recommendedGoodFirstIssues.length < 2) {
+  fail('release announcement JSON must include at least two recommended good-first issues to publish')
+}
+
+const invalidRecommendedIssues = announcement.recommendedGoodFirstIssues.filter((issue) => !issue.title || !issue.url?.startsWith('https://github.com/markbang/base-themes/issues/new?') || !issue.labels?.includes('type: good first issue'))
+if (invalidRecommendedIssues.length > 0) {
+  fail('recommended good-first issues must include title, prefilled URL, and good-first label', invalidRecommendedIssues.map((issue) => issue.title ?? '(untitled)'))
+}
+
+const missingRecommendedIssueCopy = announcement.recommendedGoodFirstIssues.filter((issue) => !announcement.githubRelease.includes(issue.url))
+if (missingRecommendedIssueCopy.length > 0) {
+  fail('GitHub release copy must include recommended good-first issue URLs', missingRecommendedIssueCopy.map((issue) => issue.title))
+}
+
+const githubReleaseChannel = announcement.channelChecklist.find((item) => item.channel === 'GitHub Release')
+const missingRecommendedIssueChecklistUrls = announcement.recommendedGoodFirstIssues.filter((issue) => !githubReleaseChannel?.recommendedIssueUrls?.includes(issue.url))
+if (missingRecommendedIssueChecklistUrls.length > 0) {
+  fail('GitHub Release channel checklist must include recommended good-first issue URLs', missingRecommendedIssueChecklistUrls.map((issue) => issue.title))
+}
+
+const externalIssueAction = launchActions.actions.find((action) => action.signalId === 'external-human-issue-or-pr')
+const missingRecommendedLaunchActionUrls = announcement.recommendedGoodFirstIssues.filter((issue) => !externalIssueAction?.links?.includes(issue.url))
+if (missingRecommendedLaunchActionUrls.length > 0) {
+  fail('launch actions must include recommended good-first issue URLs for the missing external issue/PR signal', missingRecommendedLaunchActionUrls.map((issue) => issue.title))
+}
+
+if (!externalIssueAction?.commands?.some((command) => command.includes('gh issue create --repo markbang/base-themes'))) {
+  fail('launch actions must include GitHub CLI commands for recommended good-first issues')
+}
+
+const externalIssueStatus = launchStatus.missingSignals.find((signal) => signal.id === 'external-human-issue-or-pr')
+const missingRecommendedStatusUrls = announcement.recommendedGoodFirstIssues.filter((issue) => !externalIssueStatus?.recommendedGoodFirstIssues?.some((statusIssue) => statusIssue.url === issue.url))
+if (missingRecommendedStatusUrls.length > 0) {
+  fail('launch status must include recommended good-first issue URLs for the missing external issue/PR signal', missingRecommendedStatusUrls.map((issue) => issue.title))
+}
+
+const invalidSeedUrls = seedIssues.filter((issue) => !issue.url?.startsWith('https://github.com/markbang/base-themes/issues/new?'))
+if (invalidSeedUrls.length > 0) {
+  fail('contributor seed issues must include prefilled GitHub issue URLs', invalidSeedUrls.map((issue) => issue.title ?? '(untitled)'))
+}
+
+console.log(`Launch readiness valid: ${Object.keys(requiredReleaseLinks).length} adoption links, ${seedIssues.length} seed issues, ${goodFirstIssues.length} good-first issues`)

package/scripts/verify-telemetry-fixtures.mjs

@@ -0,0 +1,85 @@
+import { execFileSync } from 'node:child_process'
+import { resolve } from 'node:path'
+
+const fixtureEnv = {
+  SEARCH_CONSOLE_EXPORT: resolve('research/telemetry-fixtures/search-console-export.csv'),
+  ANALYTICS_EXPORT: resolve('research/telemetry-fixtures/analytics-events.jsonl'),
+  REGISTRY_ACCESS_EXPORT: resolve('research/telemetry-fixtures/registry-access.jsonl'),
+  COMMUNITY_PROOF_EXPORT: resolve('research/telemetry-fixtures/community-proof.csv'),
+  BUNDLE_REPORT_EXPORT: resolve('research/telemetry-fixtures/bundle-report.json'),
+}
+
+function fail(message, details = []) {
+  console.error(`Telemetry fixture import invalid: ${message}`)
+  for (const detail of details) console.error(`- ${detail}`)
+  process.exit(1)
+}
+
+let payload
+try {
+  payload = JSON.parse(execFileSync('node', ['scripts/collect-telemetry.mjs', '--json', '--no-write'], {
+    encoding: 'utf8',
+    env: { ...process.env, ...fixtureEnv },
+    maxBuffer: 20 * 1024 * 1024,
+  }))
+} catch (error) {
+  fail('collect-telemetry --json must import fixture exports and emit valid JSON', [error.message])
+}
+
+function expectEqual(label, actual, expected) {
+  if (actual !== expected) fail(`${label} should be ${expected}`, [`got ${actual}`])
+}
+
+expectEqual('Search Console row count', payload.searchConsole?.rowCount, 3)
+expectEqual('Search Console clicks', payload.searchConsole?.clicks, 23)
+expectEqual('Search Console impressions', payload.searchConsole?.impressions, 490)
+expectEqual('Website analytics event count', payload.analytics?.eventCount, 9)
+expectEqual('Website analytics install command copies', payload.analytics?.installCopies, 1)
+expectEqual('Website analytics GitHub outbound clicks', payload.analytics?.githubOutboundClicks, 4)
+expectEqual('Website analytics theme snippet copies', payload.analytics?.themeSnippetCopies, 1)
+expectEqual('Website analytics top campaigns', payload.analytics?.topCampaigns?.[0]?.value, 'launch-0-1-2')
+expectEqual('Website analytics top sources', payload.analytics?.topSources?.[0]?.value, 'github-release')
+expectEqual('Website analytics top mediums', payload.analytics?.topMediums?.[0]?.value, 'release-notes')
+expectEqual('Website analytics top GitHub click sources', payload.analytics?.topGithubClickSources?.[0]?.value, 'github-release')
+expectEqual('Website analytics top install-copy sources', payload.analytics?.topInstallCopySources?.[0]?.value, 'github-release')
+expectEqual('Website analytics campaign funnel value', payload.analytics?.campaignFunnels?.[0]?.value, 'launch-0-1-2')
+expectEqual('Website analytics campaign funnel route views', payload.analytics?.campaignFunnels?.[0]?.routeViews, 1)
+expectEqual('Website analytics campaign funnel install copies', payload.analytics?.campaignFunnels?.[0]?.installCopies, 1)
+expectEqual('Website analytics campaign funnel GitHub clicks', payload.analytics?.campaignFunnels?.[0]?.githubClicks, 4)
+expectEqual('Website analytics source funnel value', payload.analytics?.sourceFunnels?.[0]?.value, 'github-release')
+expectEqual('Website analytics source funnel install copies', payload.analytics?.sourceFunnels?.[0]?.installCopies, 1)
+expectEqual('Website analytics source funnel GitHub clicks', payload.analytics?.sourceFunnels?.[0]?.githubClicks, 4)
+expectEqual('Registry access imported rows', payload.registryAccess?.rowCount, 10)
+expectEqual('Registry access matched requests', payload.registryAccess?.matchedRequests, 9)
+expectEqual('Registry access component item requests', payload.registryAccess?.componentItemRequests, 1)
+expectEqual('Registry access block item requests', payload.registryAccess?.blockItemRequests, 1)
+expectEqual('Registry access theme item requests', payload.registryAccess?.themeItemRequests, 1)
+expectEqual('Community proof signals', payload.communityProof?.signalCount, 4)
+expectEqual('Community proof discussions', payload.communityProof?.discussions, 1)
+expectEqual('Community proof permissioned gallery', payload.communityProof?.permissionedGallery, 2)
+expectEqual('Community proof external repos', payload.communityProof?.externalRepos, 1)
+expectEqual('Community proof external URLs', payload.communityProof?.externalUrls, 1)
+expectEqual('Bundle report budget status', payload.bundleReport?.ok, true)
+expectEqual('Bundle report app JS gzip bytes', payload.bundleReport?.appJs?.gzipBytes, 21000)
+expectEqual('Bundle report largest JS bytes', payload.bundleReport?.largestJs?.bytes, 350000)
+expectEqual('Bundle report budget check count', payload.bundleReport?.budgetChecks?.length, 3)
+
+if (!payload.bundleReport?.budgetChecks?.every((check) => check.passed)) {
+  fail('Bundle report fixture budget checks should all pass')
+}
+
+const githubTargets = payload.analytics?.topGithubClickTargets?.map((row) => row.value) ?? []
+for (const target of ['repo-star', 'repo-fork', 'feature-request', 'good-first-issues']) {
+  if (!githubTargets.includes(target)) fail('GitHub outbound click fixture targets were not summarized', [target])
+}
+
+const topRegistryItems = payload.registryAccess?.topRegistryItems?.map((row) => row.value) ?? []
+for (const itemPath of ['/registry/items/button.json', '/registry/items/block-dashboard-shell.json', '/registry/items/theme-enterprise.json']) {
+  if (!topRegistryItems.includes(itemPath)) fail('Registry item fixture paths were not summarized', [itemPath])
+}
+
+if (payload.adoption?.completionThreshold !== 3 || payload.adoption?.signalCount !== 4) {
+  fail('fixture import must preserve the public adoption gate shape')
+}
+
+console.log('Telemetry fixture import valid: search, analytics, registry, community, and bundle exports summarized correctly')

package/scripts/verify-telemetry-report.mjs

@@ -0,0 +1,89 @@
+import { execFileSync } from 'node:child_process'
+import { readdirSync, readFileSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+
+function fail(message, details = []) {
+  console.error(`Telemetry report invalid: ${message}`)
+  for (const detail of details) console.error(`- ${detail}`)
+  process.exit(1)
+}
+
+function latestTelemetryPath() {
+  const files = readdirSync(resolve('research'))
+    .filter((file) => /^telemetry-\d{4}-\d{2}-\d{2}\.json$/.test(file))
+    .sort()
+
+  return files.length ? resolve('research', files.at(-1)) : undefined
+}
+
+function loadTelemetryReport() {
+  if (process.argv.includes('--live')) {
+    try {
+      return {
+        source: 'live collect-telemetry',
+        payload: JSON.parse(execFileSync('node', ['scripts/collect-telemetry.mjs', '--json', '--no-write'], {
+          encoding: 'utf8',
+          maxBuffer: 20 * 1024 * 1024,
+        })),
+      }
+    } catch (error) {
+      fail('collect-telemetry --json must emit valid JSON', [error.message])
+    }
+  }
+
+  const source = latestTelemetryPath()
+  if (!source) fail('no research/telemetry-YYYY-MM-DD.json report exists', ['Run npm run telemetry:collect first, or use --live.'])
+
+  try {
+    return {
+      source: basename(source),
+      payload: JSON.parse(readFileSync(source, 'utf8')),
+    }
+  } catch (error) {
+    fail('latest telemetry JSON could not be parsed', [`${source}: ${error.message}`])
+  }
+}
+
+const { source, payload } = loadTelemetryReport()
+const telemetryErrors = Array.isArray(payload.errors) ? payload.errors : []
+if (telemetryErrors.length > 0) {
+  fail('telemetry collection errors must be resolved before treating the report as valid', telemetryErrors)
+}
+
+const requiredSignalIds = ['npm-weekly-downloads', 'github-stars', 'external-human-issue-or-pr', 'forks']
+const signalIds = payload.adoption?.signals?.map((signal) => signal.id) ?? []
+const missingSignalIds = requiredSignalIds.filter((id) => !signalIds.includes(id))
+if (missingSignalIds.length > 0) {
+  fail('adoption JSON is missing required public signal ids', missingSignalIds)
+}
+
+if (payload.adoption?.completionThreshold !== 3) {
+  fail('completion threshold must stay at three public signals', [`got ${payload.adoption?.completionThreshold}`])
+}
+
+if (payload.adoption?.signalCount !== 4 || payload.adoption?.signals?.length !== 4) {
+  fail('adoption JSON must track exactly four public completion signals', [`got ${payload.adoption?.signalCount ?? 'missing'} / ${payload.adoption?.signals?.length ?? 'missing'}`])
+}
+
+if (payload.adoption?.passedSignals !== payload.adoption.signals.filter((signal) => signal.passed).length) {
+  fail('passedSignals must equal the number of passed signal entries')
+}
+
+if (payload.adoption?.score !== `${payload.adoption.passedSignals}/${payload.adoption.signalCount}`) {
+  fail('adoption score string must match passedSignals/signalCount', [`got ${payload.adoption?.score}`])
+}
+
+if (payload.adoption?.externallyValidated !== (payload.adoption.passedSignals >= payload.adoption.completionThreshold)) {
+  fail('externallyValidated must be derived from passedSignals and completionThreshold')
+}
+
+const missingCurrentValues = payload.adoption.signals.filter((signal) => !('current' in signal) || !('passed' in signal) || !signal.threshold)
+if (missingCurrentValues.length > 0) {
+  fail('every adoption signal must include current, passed, and threshold fields', missingCurrentValues.map((signal) => signal.id))
+}
+
+if (payload.adoption.externallyValidated) {
+  console.log(`Telemetry report valid (${source}): adoption externally validated at ${payload.adoption.score}`)
+} else {
+  console.log(`Telemetry report valid (${source}): adoption not externally validated at ${payload.adoption.score}`)
+}