fix: close stable release verification gaps

Author: Cylop

.github/workflows/release.yml

@@ -59,6 +59,10 @@ jobs:
         run: npm run release:check -- --dry-run --output release-artifact
       - name: Run model benchmarks
         run: npm run benchmark
+      - name: Run model lifetime benchmark
+        run: npm run benchmark:memory
+      - name: Run browser benchmark
+        run: npm run benchmark:browser
       - name: Upload verified release artifact
         uses: actions/upload-artifact@v7
         with:
@@ -181,6 +185,7 @@ jobs:
         run: npm run build:website
         env:
           REQUIRE_NPM_PUBLICATION: 'true'
+          EXPECTED_NPM_VERSION: '1.0.0'
       - name: Deploy released website
         id: deploy
         run: node scripts/deploy-website.mjs

scripts/build-website.mjs

@@ -2,41 +2,18 @@ import { spawnSync } from 'node:child_process'
 import { mkdir, readFile, writeFile, copyFile, rm } from 'node:fs/promises'
 import { dirname, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
+import { resolvePublishedVersion } from './website-version.mjs'
 const requiredPublication = process.env.REQUIRE_NPM_PUBLICATION === 'true'
 const packageJson = JSON.parse(await readFile('package.json', 'utf8'))
 // Local and verification builds describe their source candidate. Deployment
-// builds resolve npm directly and refuse installation copy for an unpublished
-// version. The existing beta is a bridge only until the first stable publish.
-let version = requiredPublication ? '' : packageJson.version
-for (let attempt = 0; attempt < (requiredPublication ? 6 : 0); attempt++) {
-  for (const tag of ['latest', 'beta']) {
-    const response = await fetch(
-      `https://registry.npmjs.org/@nipe-solutions%2freact-data-inspector/${tag}`,
-      { signal: AbortSignal.timeout(20000) },
-    )
-    if (response.ok) {
-      const data = await response.json()
-      version = data.version
-      if (
-        typeof version !== 'string' ||
-        !/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(version)
-      )
-        throw Error('Registry returned no valid release version')
-      break
-    }
-    if (response.status !== 404)
-      throw Error(`Cannot verify npm publication: ${response.status}`)
-  }
-  if (version) break
-  if (requiredPublication && attempt < 5) {
-    console.log('Waiting for npm publication to become readable…')
-    await new Promise((resolve) => setTimeout(resolve, 10000))
-  }
-}
-if (requiredPublication && !version)
-  throw Error(
-    'Published package is not readable; refusing stale installation copy',
-  )
+// builds resolve npm directly. Release deployment additionally requires the
+// exact reviewed version on latest; the prerelease bridge is available only to
+// ordinary non-release deployments during the transition.
+const version = await resolvePublishedVersion({
+  sourceVersion: packageJson.version,
+  requirePublication: requiredPublication,
+  expectedVersion: process.env.EXPECTED_NPM_VERSION,
+})
 process.env.VITE_NPM_VERSION = version
 const run = (args) => {
   const result = spawnSync('npx', args, { stdio: 'inherit', env: process.env })

scripts/documentation-snippets.mjs

@@ -0,0 +1,27 @@
+import { readFile, readdir } from 'node:fs/promises'
+import path from 'node:path'
+
+const competitorImport =
+  /from ['"](?:react18-json-view|react-json-view-lite|@uiw\/react-json-view)['"]/
+
+export async function readDocumentationSnippets(repositoryRoot) {
+  const documentationDirectory = path.join(repositoryRoot, 'website/docs')
+  const snippets = []
+
+  for (const file of (await readdir(documentationDirectory)).sort()) {
+    const source = await readFile(
+      path.join(documentationDirectory, file),
+      'utf8',
+    )
+    let index = 0
+    for (const match of source.matchAll(/```tsx?\n([\s\S]*?)```/g)) {
+      if (competitorImport.test(match[1])) continue
+      snippets.push({
+        filename: `${file}-${index++}.tsx`,
+        code: match[1],
+      })
+    }
+  }
+
+  return snippets
+}

scripts/documentation-snippets.test.mjs

@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict'
+import path from 'node:path'
+import test from 'node:test'
+import { readDocumentationSnippets } from './documentation-snippets.mjs'
+
+const repositoryRoot = path.resolve(import.meta.dirname, '..')
+
+test('documentation snippets select every current package example', async () => {
+  const snippets = await readDocumentationSnippets(repositoryRoot)
+
+  assert.equal(snippets.length, 24)
+  assert.equal(new Set(snippets.map(({ filename }) => filename)).size, 24)
+  assert.ok(
+    snippets.every(
+      ({ code }) =>
+        !/from ['"](?:react18-json-view|react-json-view-lite|@uiw\/react-json-view)['"]/.test(
+          code,
+        ),
+    ),
+  )
+  assert.ok(
+    snippets.some(({ code }) =>
+      code.includes("from '@nipe-solutions/react-data-inspector'"),
+    ),
+  )
+})

scripts/validate-release.mjs

@@ -1,9 +1,10 @@
 import assert from 'node:assert/strict'
 import { execFile } from 'node:child_process'
 import console from 'node:console'
-import { createHash } from 'node:crypto'
+import { createHash, randomUUID } from 'node:crypto'
 import {
   appendFile,
+  link,
   mkdir,
   mkdtemp,
   readFile,
@@ -16,8 +17,9 @@ import process from 'node:process'
 import { pathToFileURL } from 'node:url'
 import { promisify } from 'node:util'
 import {
+  createNpmPaths,
   formatCommandError,
-  sanitizeNpmEnvironment,
+  runNpm,
   validatePackedFiles,
   verifyTarballConsumers,
 } from './verify-package.mjs'
@@ -225,8 +227,8 @@ export async function verifyRelease({ dryRun = false, outputDirectory } = {}) {
     const npmPaths = await createNpmPaths(workingRoot)
     await mkdir(packDirectory)
     const { stdout } = await runNpm(
-      ['pack', '--json', '--pack-destination', packDirectory],
-      repositoryRoot,
+      ['pack', repositoryRoot, '--json', '--pack-destination', packDirectory],
+      npmPaths.workspace,
       npmPaths,
     )
     const [pack] = JSON.parse(stdout)
@@ -270,15 +272,13 @@ export async function verifyRelease({ dryRun = false, outputDirectory } = {}) {
         release.channel,
         tarballPath,
       ],
-      repositoryRoot,
+      npmPaths.workspace,
       npmPaths,
     )
 
     const manifest = await createArtifactManifest(pack, tarballPath, release)
     const manifestPath = path.join(packDirectory, 'release-manifest.json')
-    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, {
-      flag: 'wx',
-    })
+    await writeArtifactManifest(manifestPath, manifest)
     if (outputDirectory) {
       await writeGitHubOutputs({ tarball: pack.filename })
       console.log(`Verified artifact preserved at ${tarballPath}`)
@@ -292,25 +292,23 @@ export async function verifyRelease({ dryRun = false, outputDirectory } = {}) {
   }
 }
 
-async function createNpmPaths(temporaryRoot) {
-  const paths = {
-    userConfig: path.join(temporaryRoot, 'user.npmrc'),
-    globalConfig: path.join(temporaryRoot, 'global.npmrc'),
-    cache: path.join(temporaryRoot, 'npm-cache'),
+export async function writeArtifactManifest(manifestPath, manifest) {
+  const temporaryPath = `${manifestPath}.${randomUUID()}.tmp`
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, {
+      flag: 'wx',
+    })
+    await link(temporaryPath, manifestPath)
+  } finally {
+    await rm(temporaryPath, { force: true })
   }
-  await Promise.all([
-    writeFile(paths.userConfig, ''),
-    writeFile(paths.globalConfig, ''),
-    mkdir(paths.cache),
-  ])
-  return paths
 }
 
 async function readRegistryVersion(name, version, npmPaths) {
   try {
     const { stdout } = await runNpm(
       ['view', `${name}@${version}`, 'version', '--json'],
-      repositoryRoot,
+      npmPaths.workspace,
       npmPaths,
     )
     const parsed = JSON.parse(stdout)
@@ -336,14 +334,6 @@ async function runVisibleNpm(args, cwd, npmPaths) {
   if (stderr) process.stderr.write(stderr)
 }
 
-function runNpm(args, cwd, npmPaths) {
-  return execFileAsync('npm', args, {
-    cwd,
-    env: sanitizeNpmEnvironment(process.env, npmPaths),
-    maxBuffer: 10 * 1024 * 1024,
-  })
-}
-
 function run(command, args) {
   return execFileAsync(command, args, {
     cwd: repositoryRoot,

scripts/validate-release.test.mjs

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict'
-import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 import test from 'node:test'
@@ -9,6 +9,7 @@ import {
   parseArguments,
   validateReleaseMetadata,
   validateRepositoryContext,
+  writeArtifactManifest,
 } from './validate-release.mjs'
 
 const repositoryRoot = path.resolve(import.meta.dirname, '..')
@@ -295,3 +296,26 @@ test('artifact manifest binds release metadata and inventory to the tarball', as
     await rm(directory, { recursive: true, force: true })
   }
 })
+
+test('artifact manifest installation is atomic and exclusive', async () => {
+  const temporaryRoot = await mkdtemp(
+    path.join(tmpdir(), 'react-data-inspector-manifest-write-'),
+  )
+  const manifestPath = path.join(temporaryRoot, 'release-manifest.json')
+  try {
+    await writeArtifactManifest(manifestPath, { version: '1.0.0' })
+    assert.deepEqual(JSON.parse(await readFile(manifestPath, 'utf8')), {
+      version: '1.0.0',
+    })
+    await assert.rejects(
+      () => writeArtifactManifest(manifestPath, { version: 'substituted' }),
+      /EEXIST/,
+    )
+    assert.deepEqual(JSON.parse(await readFile(manifestPath, 'utf8')), {
+      version: '1.0.0',
+    })
+    assert.deepEqual(await readdir(temporaryRoot), ['release-manifest.json'])
+  } finally {
+    await rm(temporaryRoot, { recursive: true, force: true })
+  }
+})

scripts/verify-package.mjs

@@ -9,6 +9,7 @@ import process from 'node:process'
 import { pathToFileURL } from 'node:url'
 import { promisify } from 'node:util'
 import { gzipSync } from 'node:zlib'
+import { readDocumentationSnippets } from './documentation-snippets.mjs'
 
 const execFileAsync = promisify(execFile)
 const repositoryRoot = path.resolve(import.meta.dirname, '..')
@@ -54,7 +55,14 @@ const lifecycleScripts = [
   'postinstall',
   'prepublish',
   'prepublishOnly',
+  'preprepare',
   'prepare',
+  'postprepare',
+  'dependencies',
+  'prepack',
+  'postpack',
+  'publish',
+  'postpublish',
 ]
 
 export function validatePackedFiles(actualFiles, expectedFiles) {
@@ -200,9 +208,10 @@ export async function verifyTarballConsumers(tarballPath) {
       await verifyModulesAndSsr(consumer)
       await verifyTypes(consumer)
       await verifyExamples(consumer)
+      await verifyDocumentationExamples(consumer)
       await verifyStylesAndManifest(consumer, sourceManifest)
       console.log(
-        `${lane.label}: ESM, CJS, types, CSS, examples, and SSR passed`,
+        `${lane.label}: ESM, CJS, types, CSS, examples, docs, and SSR passed`,
       )
     }
   } finally {
@@ -229,8 +238,8 @@ export async function verifyPackage() {
       await readFile(path.join(repositoryRoot, 'package.json'), 'utf8'),
     )
     const { stdout } = await runNpm(
-      ['pack', '--json', '--pack-destination', packDirectory],
-      repositoryRoot,
+      ['pack', repositoryRoot, '--json', '--pack-destination', packDirectory],
+      npmPaths.workspace,
       npmPaths,
     )
     const [pack] = JSON.parse(stdout)
@@ -430,6 +439,52 @@ async function verifyExamples(consumer) {
   )
 }
 
+async function verifyDocumentationExamples(consumer) {
+  const directory = path.join(consumer, 'documentation')
+  await mkdir(directory)
+  for (const { filename, code } of await readDocumentationSnippets(
+    repositoryRoot,
+  ))
+    await writeFile(path.join(directory, filename), code)
+  await writeFile(
+    path.join(directory, 'environment.d.ts'),
+    "declare module '*.css'\n",
+  )
+
+  await writeFile(
+    path.join(consumer, 'tsconfig.documentation.json'),
+    `${JSON.stringify(
+      {
+        compilerOptions: {
+          target: 'ES2022',
+          lib: ['ES2022', 'DOM', 'DOM.Iterable'],
+          module: 'ESNext',
+          moduleResolution: 'Bundler',
+          jsx: 'react-jsx',
+          strict: true,
+          exactOptionalPropertyTypes: true,
+          noUncheckedIndexedAccess: true,
+          noEmit: true,
+          skipLibCheck: false,
+          types: [],
+        },
+        include: ['documentation/**/*.tsx', 'documentation/**/*.d.ts'],
+      },
+      null,
+      2,
+    )}\n`,
+  )
+  await run(
+    process.execPath,
+    [
+      'node_modules/typescript/bin/tsc',
+      '--project',
+      'tsconfig.documentation.json',
+    ],
+    consumer,
+  )
+}
+
 async function verifyStylesAndManifest(consumer, sourceManifest) {
   const require = createRequire(path.join(consumer, 'package.json'))
   const stylesheetPath = require.resolve(`${packageName}/styles.css`)
@@ -446,21 +501,23 @@ async function verifyStylesAndManifest(consumer, sourceManifest) {
   })
 }
 
-async function createNpmPaths(temporaryRoot) {
+export async function createNpmPaths(temporaryRoot) {
   const paths = {
     userConfig: path.join(temporaryRoot, 'user.npmrc'),
     globalConfig: path.join(temporaryRoot, 'global.npmrc'),
     cache: path.join(temporaryRoot, 'npm-cache'),
+    workspace: path.join(temporaryRoot, 'npm-workspace'),
   }
   await Promise.all([
     writeFile(paths.userConfig, ''),
     writeFile(paths.globalConfig, ''),
     mkdir(paths.cache),
+    mkdir(paths.workspace),
   ])
   return paths
 }
 
-function runNpm(args, cwd, npmPaths) {
+export function runNpm(args, cwd, npmPaths) {
   return execFileAsync('npm', args, {
     cwd,
     env: sanitizeNpmEnvironment(process.env, npmPaths),