Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
3 changes: 2 additions & 1 deletion examples/node/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
3 changes: 2 additions & 1 deletion package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

101 changes: 101 additions & 0 deletions scripts/check-deps.mjs
Original file line number Diff line number Diff line change
@@ -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 <dir> --allow <a,b|''> [--peer <x,y>] [--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();
56 changes: 56 additions & 0 deletions scripts/check-deps.test.mjs
Original file line number Diff line number Diff line change
@@ -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/);
});
});
Loading