test: add library quality gates and package validation

.github/workflows/node.yml

@@ -46,14 +46,23 @@ jobs:
         env:
           CYPRESS_INSTALL_BINARY: 0
           PUPPETEER_SKIP_DOWNLOAD: true
-        run: npm i
+        run: npm ci
 
       - name: Lint
         run: npm run lint
 
+      - name: Type check
+        run: npm run typecheck
+
       - name: Build library
         run: npm run build
 
+      - name: Validate distribution
+        run: npm run validate:dist
+
+      - name: Test package
+        run: npm run test:package
+
       - name: Check build changes
         run: |
           bash -c "[[ ! \"`git status --porcelain `\" ]] || (echo 'Please recompile and commit the assets' && exit 1)"

.github/workflows/npm-publish.yml

@@ -47,7 +47,7 @@ jobs:
         env:
           CYPRESS_INSTALL_BINARY: 0
         run: |
-          npm i
+          npm ci
           npm run build
 
       - name: Publish to npm

.github/workflows/pages.yml

@@ -33,7 +33,7 @@ jobs:
 
       - name: Install & Build
         run: |
-          npm i
+          npm ci
           npm run build:demo
 
       - name: Deploy

.github/workflows/tests.yml

@@ -46,7 +46,7 @@ jobs:
         env:
           CYPRESS_INSTALL_BINARY: 0
           PUPPETEER_SKIP_DOWNLOAD: true
-        run: npm i
+        run: npm ci
 
       - name: Test
         run: npm run test

package.json

@@ -40,7 +40,9 @@
     "build:report": "vite build --mode report",
     "build:demo": "vite build --mode demo",
     "preview:demo": "vite preview --outDir dist-demo",
+    "typecheck": "vue-tsc --noEmit",
     "validate:dist": "node scripts/validate-pdfjs-dist.mjs",
+    "test:package": "node scripts/test-package.mjs",
     "prepack": "npm run build && npm run validate:dist",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -54,10 +56,12 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@nextcloud/browserslist-config": "^3.1.2",
+    "@types/node": "^24.13.3",
     "@typescript-eslint/eslint-plugin": "^8.58.0",
     "@typescript-eslint/parser": "^8.58.0",
     "@vitejs/plugin-vue": "^6.0.4",
     "@vitest/eslint-plugin": "^1.6.14",
+    "@vue/language-core": "^3.3.11",
     "@vue/test-utils": "^2.4.6",
     "eslint-plugin-vue": "^10.8.0",
     "eslint": "^10.1.0",

scripts/test-package.mjs

@@ -0,0 +1,138 @@
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import assert from 'node:assert/strict'
+import { execFile } from 'node:child_process'
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import process from 'node:process'
+import { promisify } from 'node:util'
+import { fileURLToPath } from 'node:url'
+
+const execFileAsync = promisify(execFile)
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const npmExecPath = process.env.npm_execpath
+
+if (!npmExecPath) {
+  throw new Error('Run this check through npm so the active npm executable can be reused.')
+}
+
+async function runNpm(args, cwd) {
+  return execFileAsync(process.execPath, [npmExecPath, ...args], {
+    cwd,
+    maxBuffer: 10 * 1024 * 1024,
+  })
+}
+
+function exportTargets(exports) {
+  if (typeof exports === 'string') {
+    return [exports]
+  }
+  if (!exports || typeof exports !== 'object') {
+    return []
+  }
+  return Object.values(exports).flatMap(exportTargets)
+}
+
+const tempRoot = await mkdtemp(path.join(tmpdir(), 'pdf-elements-package-'))
+
+try {
+  const packDir = path.join(tempRoot, 'pack')
+  const consumerDir = path.join(tempRoot, 'consumer')
+  await Promise.all([mkdir(packDir), mkdir(consumerDir)])
+
+  const { stdout } = await runNpm(
+    ['pack', '--json', '--ignore-scripts', '--pack-destination', packDir],
+    packageRoot
+  )
+  const [packResult] = JSON.parse(stdout)
+  assert(packResult?.filename, 'npm pack did not report a tarball filename')
+
+  const packedFiles = new Set(packResult.files.map(({ path: filePath }) => filePath))
+  const packageJson = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'))
+  const requiredFiles = ['COPYING', 'README.md', 'dist/index.css', 'dist/index.mjs', packageJson.types]
+
+  for (const target of exportTargets(packageJson.exports)) {
+    assert(target.startsWith('./'), `Package export must be relative: ${target}`)
+    requiredFiles.push(target.slice(2))
+  }
+
+  for (const filePath of new Set(requiredFiles)) {
+    assert(packedFiles.has(filePath), `Packed package is missing ${filePath}`)
+  }
+
+  await writeFile(
+    path.join(consumerDir, 'package.json'),
+    JSON.stringify({ name: 'pdf-elements-smoke-consumer', private: true, type: 'module' }),
+    'utf8'
+  )
+
+  const tarballPath = path.join(packDir, packResult.filename)
+  await runNpm(
+    ['install', '--ignore-scripts', '--no-audit', '--no-fund', '--no-package-lock', tarballPath],
+    consumerDir
+  )
+
+  await writeFile(
+    path.join(consumerDir, 'verify.mjs'),
+    `import assert from 'node:assert/strict'
+import PDFElements, { ensureWorkerReady } from '@libresign/pdf-elements'
+
+assert(PDFElements, 'The public entry point has no default export')
+assert.equal(typeof ensureWorkerReady, 'function')
+
+for (const specifier of ${JSON.stringify(Object.keys(packageJson.exports))}) {
+  const publicSpecifier = specifier === '.'
+    ? '@libresign/pdf-elements'
+    : \`@libresign/pdf-elements/\${specifier.slice(2)}\`
+  assert(import.meta.resolve(publicSpecifier), \`Unable to resolve \${publicSpecifier}\`)
+}
+`,
+    'utf8'
+  )
+
+  await execFileAsync(process.execPath, ['verify.mjs'], { cwd: consumerDir })
+
+  await writeFile(
+    path.join(consumerDir, 'index.ts'),
+    `import PDFElements, {
+  ensureWorkerReady,
+  type PDFDocumentEntry,
+} from '@libresign/pdf-elements'
+
+const component = PDFElements
+const prepareWorker: () => Promise<void> = ensureWorkerReady
+let document: PDFDocumentEntry | undefined
+
+void component
+void prepareWorker
+void document
+`,
+    'utf8'
+  )
+  await writeFile(
+    path.join(consumerDir, 'tsconfig.json'),
+    JSON.stringify({
+      compilerOptions: {
+        lib: ['ES2022', 'DOM'],
+        module: 'NodeNext',
+        moduleResolution: 'NodeNext',
+        noEmit: true,
+        strict: true,
+        target: 'ES2022',
+      },
+      include: ['index.ts'],
+    }),
+    'utf8'
+  )
+
+  const tscPath = path.join(packageRoot, 'node_modules', 'typescript', 'bin', 'tsc')
+  await execFileAsync(process.execPath, [tscPath, '--project', 'tsconfig.json'], {
+    cwd: consumerDir,
+  })
+
+  globalThis.console.log(`Validated packed package ${packResult.filename} from a clean consumer.`)
+} finally {
+  await rm(tempRoot, { recursive: true, force: true })
+}

tests/components/PDFPage.spec.ts

@@ -114,7 +114,7 @@ describe('PDFPage business rules', () => {
       },
     })
 
-    wrapper.vm.renderTask = { cancel }
+    wrapper.vm.renderTask = { cancel, promise: Promise.resolve() }
 
     await wrapper.vm.render()
 
@@ -129,7 +129,7 @@ describe('PDFPage business rules', () => {
     })
 
     const cancel = vi.fn()
-    wrapper.vm.renderTask = { cancel }
+    wrapper.vm.renderTask = { cancel, promise: Promise.resolve() }
     wrapper.unmount()
 
     expect(cancel).toHaveBeenCalled()

tsconfig.json

@@ -12,7 +12,7 @@
     "resolveJsonModule": true,
     "allowSyntheticDefaultImports": true,
     "esModuleInterop": true,
-    "types": ["vite/client", "vitest/globals"]
+    "types": ["node", "vite/client", "vitest/globals"]
   },
   "include": ["env.d.ts", "src", "examples", "tests"]
 }

vite.config.ts

@@ -18,6 +18,7 @@ export default defineConfig(async ({ command, mode }) => {
         insertTypesEntry: true,
         include: ['src'],
         exclude: ['examples', 'tests'],
+        processor: 'vue',
       })
     )
   }