From 27c68d15325dfa1959e9b02706483afb0041ef9c Mon Sep 17 00:00:00 2001 From: Afzal Ahmad Date: Mon, 16 Nov 2026 16:06:49 +0100 Subject: [PATCH] OPS-11: runtime-dependency guard in CI; examples/node declares typescript scripts/check-deps.mjs (shared with the other three repos) fails CI when the published package gains a runtime or peer dependency outside the allowlist, any optional or bundled dependency, or a tarball file other than dist/, package.json, README, LICENSE and CHANGELOG. javascript-excel's allowlist is empty. examples/node runs tsc, so it now declares the typescript it used through hoisting (same 7.0.2; the lockfile keeps 245 packages). --- .github/workflows/ci.yml | 5 ++ examples/node/package.json | 3 +- package-lock.json | 3 +- scripts/check-deps.mjs | 101 ++++++++++++++++++++++++++++++++++++ scripts/check-deps.test.mjs | 56 ++++++++++++++++++++ 5 files changed, 166 insertions(+), 2 deletions(-) create mode 100644 scripts/check-deps.mjs create mode 100644 scripts/check-deps.test.mjs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 95d31af..abfdb0d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -37,6 +37,11 @@ jobs: - run: npm test - run: npm run build - run: npm run lint + # OPS-11: javascript-excel has no runtime dependencies, and only dist/ + + # README + LICENSE + package.json are published. A new runtime + # dependency means changing this allowlist in the same pull request. + - name: Dependency guard (runtime allowlist, tarball contents) + run: node scripts/check-deps.mjs --package packages/javascript-excel --allow '' --pack - name: Packed-tarball smoke test run: npm run smoke diff --git a/examples/node/package.json b/examples/node/package.json index fec8381..840be32 100644 --- a/examples/node/package.json +++ b/examples/node/package.json @@ -11,6 +11,7 @@ "javascript-excel": "2.0.0-alpha.3" }, "devDependencies": { - "@types/node": "22.20.5" + "@types/node": "22.20.5", + "typescript": "7.0.2" } } diff --git a/package-lock.json b/package-lock.json index f01bd75..791580f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -38,7 +38,8 @@ "javascript-excel": "2.0.0-alpha.3" }, "devDependencies": { - "@types/node": "22.20.5" + "@types/node": "22.20.5", + "typescript": "7.0.2" } }, "examples/react": { diff --git a/scripts/check-deps.mjs b/scripts/check-deps.mjs new file mode 100644 index 0000000..a29e71d --- /dev/null +++ b/scripts/check-deps.mjs @@ -0,0 +1,101 @@ +#!/usr/bin/env node +// Dependency guard for the published package (OPS-11). +// +// Fails (exit 1) when the package at --package: +// - declares a runtime `dependencies` entry that is not in --allow, +// - declares a `peerDependencies` entry that is not in --peer, +// - declares any `optionalDependencies` or `bundleDependencies`, or +// - with --pack: would publish anything other than package.json, README.md, +// LICENSE, CHANGELOG.md and dist/** (`npm pack --dry-run`), so private +// workspaces, sources, tests and fixtures never leak into the tarball. +// +// Usage (in CI, after the package is built): +// node scripts/check-deps.mjs --package --allow [--peer ] [--pack] +// +// Adding a runtime dependency is a decision: change the allowlist in CI in the +// same pull request, so it's reviewed. +// +// Node built-ins only. Shared verbatim by the javascript-excel, +// react-data-export, react-data-import and react-xlsx-viewer repositories; +// change it in all four or not at all. + +import { execFileSync } from "node:child_process"; +import { appendFileSync, readFileSync } from "node:fs"; +import { join } from "node:path"; +import { pathToFileURL } from "node:url"; + +/** Files a published package may contain, besides dist/**. */ +export const ALLOWED_FILES = ["package.json", "README.md", "LICENSE", "CHANGELOG.md"]; + +const list = (s) => (s ?? "").split(",").map((x) => x.trim()).filter(Boolean); + +/** Problems with the manifest's dependency fields, as messages; [] when it passes. */ +export function checkManifest(manifest, { allow = [], peer = [] } = {}) { + const problems = []; + const keys = (field) => Object.keys(manifest[field] ?? {}); + for (const name of keys("dependencies")) { + if (!allow.includes(name)) problems.push(`dependencies: "${name}" is not in the allowlist (${allow.length ? allow.join(", ") : "none"})`); + } + for (const name of keys("peerDependencies")) { + if (!peer.includes(name)) problems.push(`peerDependencies: "${name}" is not in the allowlist (${peer.length ? peer.join(", ") : "none"})`); + } + for (const name of keys("optionalDependencies")) problems.push(`optionalDependencies: "${name}" (none are allowed)`); + for (const field of ["bundleDependencies", "bundledDependencies"]) { + const v = manifest[field]; + if (v === true || (Array.isArray(v) && v.length) || (v && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length)) { + problems.push(`${field}: bundled dependencies are not allowed`); + } + } + return problems; +} + +/** Problems with the tarball's file list (paths relative to the package); [] when it passes. */ +export function checkFiles(files) { + const problems = []; + if (!files.includes("package.json")) problems.push("the tarball has no package.json"); + if (!files.some((f) => f.startsWith("dist/"))) problems.push("the tarball has no dist/ files (build first)"); + for (const f of files) { + if (!ALLOWED_FILES.includes(f) && !f.startsWith("dist/")) problems.push(`unexpected file in the tarball: ${f}`); + } + return problems; +} + +export function parseArgs(argv) { + const args = { package: undefined, allow: undefined, peer: [], pack: false }; + for (let i = 0; i < argv.length; i++) { + const a = argv[i]; + if (a === "--pack") args.pack = true; + else if (a === "--package" || a === "--allow" || a === "--peer") { + const v = argv[++i]; + if (v === undefined) throw new Error(`${a} needs a value`); + if (a === "--package") args.package = v; + else args[a.slice(2)] = list(v); + } else throw new Error(`unknown argument ${a}`); + } + if (!args.package) throw new Error("--package is required"); + if (args.allow === undefined) throw new Error("--allow is required (use --allow '' for none)"); + return args; +} + +function main() { + const args = parseArgs(process.argv.slice(2)); + const manifest = JSON.parse(readFileSync(join(args.package, "package.json"), "utf8")); + const problems = checkManifest(manifest, args); + let files = []; + if (args.pack) { + const out = execFileSync("npm", ["pack", "--dry-run", "--json", "--ignore-scripts"], { cwd: args.package, encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] }); + files = JSON.parse(out)[0].files.map((f) => f.path); + problems.push(...checkFiles(files)); + } + const deps = Object.keys(manifest.dependencies ?? {}); + const peers = Object.keys(manifest.peerDependencies ?? {}); + const summary = `${manifest.name}: dependencies [${deps.join(", ") || "none"}], peers [${peers.join(", ") || "none"}]${args.pack ? `, ${files.length} files in the tarball` : ""}`; + if (process.env.GITHUB_STEP_SUMMARY) appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${problems.length ? "dependency guard FAILED" : "dependency guard ok"}: ${summary}\n`); + if (problems.length) { + for (const p of problems) console.error(`check-deps: ${p}`); + process.exit(1); + } + console.log(`check-deps ok: ${summary}`); +} + +if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) main(); diff --git a/scripts/check-deps.test.mjs b/scripts/check-deps.test.mjs new file mode 100644 index 0000000..59f1210 --- /dev/null +++ b/scripts/check-deps.test.mjs @@ -0,0 +1,56 @@ +// Unit tests for check-deps.mjs. Run with `node --test "scripts/*.test.mjs"`. +// Shared verbatim across the four repositories, like check-deps.mjs. + +import assert from "node:assert/strict"; +import { describe, it } from "node:test"; +import { checkFiles, checkManifest, parseArgs } from "./check-deps.mjs"; + +describe("checkManifest", () => { + it("passes when every runtime and peer dependency is allowed", () => { + assert.deepEqual(checkManifest({ dependencies: { "javascript-excel": "^2" }, peerDependencies: { react: ">=17" } }, { allow: ["javascript-excel"], peer: ["react"] }), []); + assert.deepEqual(checkManifest({}, { allow: [] }), []); + assert.deepEqual(checkManifest({ dependencies: {} }, { allow: [] }), []); + }); + + it("fails on a runtime or peer dependency outside the allowlist", () => { + assert.deepEqual(checkManifest({ dependencies: { "left-pad": "1" } }, { allow: [] }), ['dependencies: "left-pad" is not in the allowlist (none)']); + assert.deepEqual(checkManifest({ dependencies: { a: "1", b: "1" } }, { allow: ["a"] }), ['dependencies: "b" is not in the allowlist (a)']); + assert.deepEqual(checkManifest({ peerDependencies: { "react-dom": "*" } }, { allow: [], peer: ["react"] }), ['peerDependencies: "react-dom" is not in the allowlist (react)']); + }); + + it("fails on optional and bundled dependencies", () => { + assert.equal(checkManifest({ optionalDependencies: { fsevents: "2" } }, { allow: [] }).length, 1); + assert.equal(checkManifest({ bundleDependencies: ["x"] }, { allow: [] }).length, 1); + assert.equal(checkManifest({ bundledDependencies: true }, { allow: [] }).length, 1); + assert.deepEqual(checkManifest({ bundleDependencies: [] }, { allow: [] }), []); + }); +}); + +describe("checkFiles", () => { + it("allows package.json, README, LICENSE, CHANGELOG and dist/**", () => { + assert.deepEqual(checkFiles(["package.json", "README.md", "LICENSE", "CHANGELOG.md", "dist/index.js", "dist/a/b.d.ts"]), []); + }); + + it("fails on anything else, and on a tarball without package.json or dist", () => { + assert.deepEqual(checkFiles(["package.json", "dist/index.js", "src/index.ts", "apps/playground/index.html"]), [ + "unexpected file in the tarball: src/index.ts", + "unexpected file in the tarball: apps/playground/index.html", + ]); + assert.deepEqual(checkFiles(["package.json", "README.md"]), ["the tarball has no dist/ files (build first)"]); + assert.deepEqual(checkFiles(["dist/index.js"]), ["the tarball has no package.json"]); + }); +}); + +describe("parseArgs", () => { + it("parses the allowlists; an empty --allow means none", () => { + assert.deepEqual(parseArgs(["--package", "p", "--allow", "", "--pack"]), { package: "p", allow: [], peer: [], pack: true }); + assert.deepEqual(parseArgs(["--package", "p", "--allow", "javascript-excel", "--peer", "react, react-dom"]), { package: "p", allow: ["javascript-excel"], peer: ["react", "react-dom"], pack: false }); + }); + + it("requires --package and --allow, and rejects unknown arguments", () => { + assert.throws(() => parseArgs(["--allow", ""]), /--package/); + assert.throws(() => parseArgs(["--package", "p"]), /--allow/); + assert.throws(() => parseArgs(["--package", "p", "--allow", "", "--nope"]), /unknown/); + assert.throws(() => parseArgs(["--package"]), /needs a value/); + }); +});