build: a licence gate over every package in the lockfile
scripts/check-licenses.mjs reads package-lock.json, where npm records each package's own `license` field, and fails on anything outside two lists (docs/09 §3.2): - what the build compiles into the extension (svelte, clsx, wxt, @wxt-dev/browser) must be permissive and GPL-3.0-compatible; - everything else is build tooling that never ships, so file-level copyleft (MPL-2.0, lightningcss) is also accepted; AGPL, source-available terms and missing or custom licences are not. SPDX expressions are evaluated, nothing is installed or fetched, and the tests call the functions directly rather than spawning the script. It runs in `verify`, CI's quality job and the release build. The shipped list moves out of wxt.config.ts into scripts/credited-packages.mjs, so the build gate, the notices test and the licence gate read one list instead of two copies and a regex. legal/THIRD_PARTY_NOTICES.md said the tooling was all MIT/Apache-2.0/ISC; the lockfile also has BSD, 0BSD, MIT-0, BlueOak, CC0 and MPL-2.0. Corrected — a description of tooling that never ships, so no LEGAL_VERSION bump (14 §3.1). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
4b10749582
commit
11e7e50fe6
18 files changed
+518
-30
No files matched your search
@@ -45,6 +45,9 @@ jobs:
|
||||
- run: npm run knip
|
||||
- run: npm run coverage # vitest --coverage, thresholds per docs/11 §1
|
||||
- run: npm run guard # the zero-network / no-raw-HTML gate, docs/08 §3
|
||||
# Every licence in the lockfile, shipped packages held to the stricter
|
||||
# list (docs/09 §3.2). Reads package-lock.json only — no network.
|
||||
- run: npm run check:licenses
|
||||
|
||||
# Zero runtime dependencies is a public claim (README, docs/09 T5); this
|
||||
# is the check that keeps it true. Dev-only advisories are tracked by
|
||||
|
||||
@@ -44,6 +44,7 @@ jobs:
|
||||
- run: npm run knip
|
||||
- run: npm run coverage
|
||||
- run: npm run guard
|
||||
- run: npm run check:licenses
|
||||
- run: npm audit --omit=dev --audit-level=low
|
||||
|
||||
- run: npm run zip # wxt zip → .output/<name>-<version>-chrome.zip
|
||||
|
||||
+2
-1
@@ -86,7 +86,8 @@ which does not exist until it has run.
|
||||
Then `npm run dev` and load `.output/chrome-mv3` at `chrome://extensions` with
|
||||
Developer mode on.
|
||||
|
||||
`npm run verify` runs lint, type-check, knip, the grep gate and the tests. It
|
||||
`npm run verify` runs lint, type-check, knip, the grep gate, the licence gate
|
||||
(`npm run check:licenses`) and the tests. It
|
||||
must be green before every commit. For anything release-bearing use
|
||||
`npm run verify:full`, which additionally runs coverage, the build, and the gate
|
||||
that inspects the *built* manifest — `verify` alone is weaker than what CI and a
|
||||
|
||||
@@ -117,8 +117,8 @@ npm run dev
|
||||
```
|
||||
|
||||
`npm run verify` is the gate everything else answers to — lint, type-check
|
||||
(svelte-check on the TypeScript 6 API, then `tsc` 7), knip, the grep gate and
|
||||
the test suite, in that order. It must be green before every commit;
|
||||
(svelte-check on the TypeScript 6 API, then `tsc` 7), knip, the grep gate, the
|
||||
licence gate and the test suite, in that order. It must be green before every commit;
|
||||
`npm run verify:full` adds coverage, the build and the built-manifest check,
|
||||
and must be green before anything release-bearing.
|
||||
|
||||
|
||||
@@ -70,11 +70,12 @@
|
||||
"knip": "knip",
|
||||
"guard": "node scripts/guard.mjs", // the source gate, 08 §3
|
||||
"check:manifest": "node scripts/check-manifest.mjs", // the built-artifact gate, 08 §3
|
||||
"check:licenses": "node scripts/check-licenses.mjs", // every lockfile licence, 09 §3.2
|
||||
"icons": "node scripts/gen-icons.mjs", // regenerates the shipped icons (source of truth)
|
||||
"test": "vitest run",
|
||||
"test:watch": "vitest",
|
||||
"coverage": "vitest run --coverage",
|
||||
"verify": "npm run lint && npm run check && npm run knip && npm run guard && npm run test",
|
||||
"verify": "npm run lint && npm run check && npm run knip && npm run guard && npm run check:licenses && npm run test",
|
||||
"verify:full": "npm run verify && npm run coverage && npm run build && npm run check:manifest"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -139,6 +139,30 @@ How new advisories are kept out:
|
||||
- Dependabot *security* PRs bypass `cooldown`; one for a version younger than
|
||||
a week may fail to resolve until it ages. That is the intended trade-off.
|
||||
|
||||
### 3.2 Licence gate — `npm run check:licenses`
|
||||
|
||||
Added 2026-11-18. `scripts/check-licenses.mjs` reads every entry of
|
||||
`package-lock.json` (lockfile v3 records each package's `license` field, and every
|
||||
entry carries one) and fails the run on any licence outside two lists:
|
||||
|
||||
| Packages | Accepted | Why |
|
||||
|---|---|---|
|
||||
| What the build compiles into the extension — `CREDITED_PACKAGES` in `scripts/credited-packages.mjs`, the same list the build gate and the notices test read (`14 §5`) | `MIT`, `ISC`, `BSD-2-Clause`, `BSD-3-Clause`, `Apache-2.0`, `0BSD`, `MIT-0` | This code travels inside a GPL-3.0-or-later extension; only permissive licences that combine with it cleanly |
|
||||
| Everything else — all of it build and test tooling, since there are no runtime dependencies | the above, plus `MPL-2.0`, `BlueOak-1.0.0`, `CC0-1.0`, `CC-BY-4.0`, `Python-2.0`, `Unlicense`, `Zlib` | Tools never ship. File-level copyleft (MPL-2.0 — `lightningcss`, under Vite) is fine for a tool; network copyleft, source-available terms and missing or custom licences are not |
|
||||
|
||||
SPDX expressions are evaluated (`OR` needs either side, `AND` both). An entry
|
||||
with no `license`, `UNLICENSED` or `SEE LICENSE IN …` fails. A new licence
|
||||
enters the tree through a reviewed change to the lists — or one `EXCEPTIONS`
|
||||
entry with its reason and a `15` decision-log row — never unnoticed inside a
|
||||
Dependabot bump. The gate trusts each package's own declaration, as any
|
||||
lockfile-based check must, and needs neither `node_modules` nor the network.
|
||||
It runs in `verify`, in CI's `quality` job and in the release build.
|
||||
|
||||
Considered and not used: `actions/dependency-review-action`. It sees only
|
||||
what a pull request changes, reads licences from ClearlyDefined rather than
|
||||
the lockfile, checks only runtime-scoped packages unless told otherwise, and
|
||||
cannot run locally — a second, weaker opinion beside this one.
|
||||
|
||||
## 4. Permissions posture
|
||||
|
||||
`bookmarks` + `storage`, nothing else (justifications in `08 §2`). Any PR
|
||||
|
||||
+4
-1
@@ -260,7 +260,10 @@ them is tested where it lives:
|
||||
v1.1.0: `guard.test.ts` (`08 §3`), `check-manifest.test.ts` (a correct build
|
||||
passes, one without the CSP fails) and `sanitize-formats.test.ts` (the
|
||||
browser JSON formats and the audit's HTML leaks, beside the older
|
||||
`sanitize-bookmarks.test.ts` — `09 §6`).
|
||||
`sanitize-bookmarks.test.ts` — `09 §6`). New in Phase 10:
|
||||
`check-licenses.test.ts` (SPDX expressions, the shipped list held stricter
|
||||
than the toolchain's, a missing or custom licence refused, the repository's
|
||||
own lockfile passing — `09 §3.2`).
|
||||
|
||||
## 5. Manual QA checklist (run before every store submission)
|
||||
|
||||
|
||||
+2
-1
@@ -66,7 +66,8 @@ Three jobs. The two whose names branch protection requires (§5) are
|
||||
quality gates at all (§1). In order: `lint`, `check` (svelte-check on the
|
||||
TS 6 API — failing on warnings too since v1.2.1, which is what makes Svelte's
|
||||
`a11y_*` checks a gate, `10 §3` — then the TS 7 `tsc`), `knip`, `coverage` (`11 §1` thresholds),
|
||||
`guard` (`08 §3`), `npm audit --omit=dev --audit-level=low` (the
|
||||
`guard` (`08 §3`), `check:licenses` (every licence in the lockfile, `09 §3.2`),
|
||||
`npm audit --omit=dev --audit-level=low` (the
|
||||
zero-runtime-dependencies claim, `09 T5`), `build`, `check:manifest`. The last
|
||||
two exist because the unit test over `wxt.config.ts` proves what we *asked*
|
||||
for and only the built manifest proves what WXT *emitted* — a dev build of
|
||||
|
||||
@@ -117,7 +117,9 @@ same value in `package.json#license` (`01 §5`).
|
||||
MIT-licensed pieces into the package: the Svelte runtime, `clsx` (which the
|
||||
Svelte runtime imports) and WXT's one-line `browser` shim (`wxt` +
|
||||
`@wxt-dev/browser`). `wxt.config.ts` fails the build when any other package
|
||||
would ship (`CREDITED_PACKAGES`). Through v1.0.x the About tab said "None"
|
||||
would ship (`CREDITED_PACKAGES` — since 2026-11-18 in
|
||||
`scripts/credited-packages.mjs`, the one list the build gate, the notices
|
||||
test and the licence gate of `09 §3.2` all read). Through v1.0.x the About tab said "None"
|
||||
and THIRD_PARTY_NOTICES said "no third-party code" — both wrong, corrected in
|
||||
v1.1.0. The notices ship as `THIRD_PARTY_NOTICES.txt` (from `src/public/`),
|
||||
which `check:manifest` requires in every build; `legal/THIRD_PARTY_NOTICES.md`
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Third-Party Notices — BookmarkMagic
|
||||
|
||||
Last updated: 2026-10-29
|
||||
Last updated: 2026-11-18
|
||||
|
||||
**No runtime dependencies are installed** — `package.json` has an empty
|
||||
`dependencies` list (`docs/01 §4`). A few small MIT-licensed pieces are,
|
||||
@@ -14,14 +14,18 @@ notices travel with it in `THIRD_PARTY_NOTICES.txt` at the root of the package:
|
||||
| [wxt](https://github.com/wxt-dev/wxt) + [@wxt-dev/browser](https://github.com/wxt-dev/wxt) | The one-line `browser` export: `globalThis.browser` when it exists, else `globalThis.chrome` | MIT |
|
||||
|
||||
The build enforces this list: `wxt.config.ts` fails the build when code from any
|
||||
other npm package would ship (`CREDITED_PACKAGES`), and
|
||||
`tests/unit/third-party.test.ts` checks that this file and the shipped `.txt`
|
||||
name every package on it. None of these contains network code; the
|
||||
other npm package would ship (`CREDITED_PACKAGES`, kept in
|
||||
`scripts/credited-packages.mjs`), `tests/unit/third-party.test.ts` checks that
|
||||
this file and the shipped `.txt` name every package on it, and
|
||||
`npm run check:licenses` holds each of them to a permissive licence. None of these contains network code; the
|
||||
extension's Content-Security-Policy forbids it anyway (`docs/08 §3`).
|
||||
|
||||
Build-time tooling (WXT's CLI, Vite, TypeScript, Biome, Knip, Vitest,
|
||||
svelte-check) is not distributed with the extension and is not listed here.
|
||||
All of it is MIT/Apache-2.0/ISC licensed and compatible with GPL-3.0-or-later.
|
||||
svelte-check and what they depend on) is not distributed with the extension and
|
||||
is not listed here. Its licences are checked on every build by
|
||||
`npm run check:licenses`: permissive (MIT, Apache-2.0, ISC, BSD, 0BSD, MIT-0,
|
||||
BlueOak, CC0) or, for one CSS tool under Vite (`lightningcss`), the
|
||||
file-level copyleft MPL-2.0 — none of which reaches the extension.
|
||||
|
||||
Licensing questions: **copyright@poli0981.dev**.
|
||||
|
||||
|
||||
+2
-1
@@ -29,11 +29,12 @@
|
||||
"knip": "knip",
|
||||
"guard": "node scripts/guard.mjs",
|
||||
"check:manifest": "node scripts/check-manifest.mjs",
|
||||
"check:licenses": "node scripts/check-licenses.mjs",
|
||||
"icons": "node scripts/gen-icons.mjs",
|
||||
"test": "vitest run",
|
||||
"test:watch": "vitest",
|
||||
"coverage": "vitest run --coverage",
|
||||
"verify": "npm run lint && npm run check && npm run knip && npm run guard && npm run test",
|
||||
"verify": "npm run lint && npm run check && npm run knip && npm run guard && npm run check:licenses && npm run test",
|
||||
"verify:full": "npm run verify && npm run coverage && npm run build && npm run check:manifest"
|
||||
},
|
||||
"devDependencies": {
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
/**
|
||||
* Types for scripts/check-licenses.mjs, so its tests can call it directly.
|
||||
* The script itself is plain JavaScript checked with `// @ts-check`.
|
||||
*/
|
||||
export const SHIPPED_LICENSES: readonly string[];
|
||||
export const TOOLCHAIN_LICENSES: readonly string[];
|
||||
export const EXCEPTIONS: Readonly<Record<string, string>>;
|
||||
export function satisfies(expression: string, allowed: readonly string[]): boolean;
|
||||
export function packageNameOf(key: string): string;
|
||||
export function checkLockfile(lock: unknown): {
|
||||
problems: string[];
|
||||
checked: number;
|
||||
counts: Map<string, number>;
|
||||
};
|
||||
@@ -0,0 +1,227 @@
|
||||
// @ts-check
|
||||
/**
|
||||
* Licence gate — docs/09 §3.2, docs/12 §2.1.
|
||||
*
|
||||
* Reads `package-lock.json` (lockfile v3), where npm records each installed
|
||||
* package's `license` field, and checks every entry against one of two lists:
|
||||
*
|
||||
* - SHIPPED — the packages the build compiles into the extension
|
||||
* (`CREDITED_PACKAGES`, scripts/credited-packages.mjs). Their code travels
|
||||
* inside a GPL-3.0-or-later extension, so only permissive licences that
|
||||
* combine with it cleanly are accepted.
|
||||
* - TOOLCHAIN — everything else. The extension has no runtime dependencies,
|
||||
* so all of these are build and test tools that never ship. Permissive
|
||||
* licences and weak, file-level copyleft (MPL-2.0) are fine; network
|
||||
* copyleft (AGPL), source-available terms (SSPL, BUSL, Commons Clause),
|
||||
* a missing or custom licence (`UNLICENSED`, `SEE LICENSE IN …`) are not.
|
||||
*
|
||||
* Anything outside the lists fails the run until a person looks at it — the
|
||||
* point is that a new licence enters the tree through a reviewed change to
|
||||
* this file, never unnoticed through a Dependabot bump. `EXCEPTIONS` is that
|
||||
* reviewed change for one package, with its reason.
|
||||
*
|
||||
* The `license` value is self-declared by each package and copied verbatim by
|
||||
* npm; this gate trusts it, as every lockfile-based checker must. It needs no
|
||||
* `node_modules` and no network, so it runs before anything is installed.
|
||||
*
|
||||
* Usage: node scripts/check-licenses.mjs — reads <repo>/package-lock.json,
|
||||
* resolved from this file. Its tests call `checkLockfile(lock)` directly.
|
||||
*/
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { resolve } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { CREDITED_PACKAGES } from './credited-packages.mjs';
|
||||
|
||||
/** Permissive licences that may ship inside a GPL-3.0-or-later extension. */
|
||||
export const SHIPPED_LICENSES = Object.freeze([
|
||||
'0BSD',
|
||||
'Apache-2.0',
|
||||
'BSD-2-Clause',
|
||||
'BSD-3-Clause',
|
||||
'ISC',
|
||||
'MIT',
|
||||
'MIT-0',
|
||||
]);
|
||||
|
||||
/** Licences accepted for build and test tooling, which never ships. */
|
||||
export const TOOLCHAIN_LICENSES = Object.freeze([
|
||||
...SHIPPED_LICENSES,
|
||||
'BlueOak-1.0.0',
|
||||
'CC-BY-4.0',
|
||||
'CC0-1.0',
|
||||
'MPL-2.0',
|
||||
'Python-2.0',
|
||||
'Unlicense',
|
||||
'Zlib',
|
||||
]);
|
||||
|
||||
/**
|
||||
* Packages accepted despite the lists above: `name → reason`. Empty on
|
||||
* purpose; an entry is a decision, recorded in docs/15's decision log.
|
||||
* @type {Readonly<Record<string, string>>}
|
||||
*/
|
||||
export const EXCEPTIONS = Object.freeze({});
|
||||
|
||||
/**
|
||||
* Whether an SPDX licence expression is satisfied by the allowed identifiers.
|
||||
* `A OR B` needs either side, `A AND B` both; parentheses group; `A WITH X`
|
||||
* (a licence exception) is judged by `A`. Anything unparseable is refused.
|
||||
*
|
||||
* @param {string} expression
|
||||
* @param {readonly string[]} allowed
|
||||
* @returns {boolean}
|
||||
*/
|
||||
export function satisfies(expression, allowed) {
|
||||
const tokens = expression.match(/\(|\)|[^\s()]+/g) ?? [];
|
||||
let at = 0;
|
||||
|
||||
/** @returns {boolean} */
|
||||
const parseOr = () => {
|
||||
let ok = parseAnd();
|
||||
while (tokens[at] === 'OR') {
|
||||
at++;
|
||||
const right = parseAnd();
|
||||
ok = ok || right;
|
||||
}
|
||||
return ok;
|
||||
};
|
||||
/** @returns {boolean} */
|
||||
const parseAnd = () => {
|
||||
let ok = parseTerm();
|
||||
while (tokens[at] === 'AND') {
|
||||
at++;
|
||||
const right = parseTerm();
|
||||
ok = ok && right;
|
||||
}
|
||||
return ok;
|
||||
};
|
||||
/** @returns {boolean} */
|
||||
const parseTerm = () => {
|
||||
const token = tokens[at++];
|
||||
if (token === '(') {
|
||||
const ok = parseOr();
|
||||
if (tokens[at++] !== ')') throw new SyntaxError('unbalanced parentheses');
|
||||
return ok;
|
||||
}
|
||||
if (token === undefined || token === ')' || token === 'AND' || token === 'OR') {
|
||||
throw new SyntaxError('expected a licence identifier');
|
||||
}
|
||||
if (tokens[at] === 'WITH') at += 2;
|
||||
return allowed.includes(token);
|
||||
};
|
||||
|
||||
try {
|
||||
const ok = parseOr();
|
||||
return at === tokens.length && tokens.length > 0 && ok;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The package name a lockfile key installs: the part after the last
|
||||
* `node_modules/`, scope included.
|
||||
* @param {string} key
|
||||
*/
|
||||
export function packageNameOf(key) {
|
||||
const at = key.lastIndexOf('node_modules/');
|
||||
return at === -1 ? key : key.slice(at + 'node_modules/'.length);
|
||||
}
|
||||
|
||||
/**
|
||||
* Lockfile text is our own committed file, but it is still file content: keep
|
||||
* what reaches the log to the characters package names and SPDX ids use.
|
||||
* @param {unknown} value
|
||||
*/
|
||||
function printable(value) {
|
||||
return String(value)
|
||||
.replaceAll(/[^\w@/.+() -]/g, '?')
|
||||
.slice(0, 120);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check every installed package of a v2/v3 lockfile.
|
||||
*
|
||||
* @param {unknown} lock — the parsed `package-lock.json`
|
||||
* @returns {{ problems: string[], checked: number, counts: Map<string, number> }}
|
||||
*/
|
||||
export function checkLockfile(lock) {
|
||||
/** @type {string[]} */
|
||||
const problems = [];
|
||||
/** @type {Map<string, number>} */
|
||||
const counts = new Map();
|
||||
const packages =
|
||||
typeof lock === 'object' && lock !== null && 'packages' in lock ? lock.packages : undefined;
|
||||
if (typeof packages !== 'object' || packages === null) {
|
||||
return { problems: ['no "packages" map — lockfile v2 or v3 expected'], checked: 0, counts };
|
||||
}
|
||||
|
||||
const shippedSeen = new Set();
|
||||
let checked = 0;
|
||||
for (const [key, raw] of Object.entries(packages)) {
|
||||
// The root project (key "") and workspace links carry no install of their own.
|
||||
if (key === '' || !key.includes('node_modules/')) continue;
|
||||
if (typeof raw === 'object' && raw !== null && 'link' in raw && raw.link === true) continue;
|
||||
checked++;
|
||||
const name = packageNameOf(key);
|
||||
const license =
|
||||
typeof raw === 'object' && raw !== null && 'license' in raw ? raw.license : undefined;
|
||||
const label = typeof license === 'string' ? license : '(none)';
|
||||
counts.set(label, (counts.get(label) ?? 0) + 1);
|
||||
|
||||
const shipped = CREDITED_PACKAGES.includes(name);
|
||||
if (shipped) shippedSeen.add(name);
|
||||
if (Object.hasOwn(EXCEPTIONS, name)) continue;
|
||||
const allowed = shipped ? SHIPPED_LICENSES : TOOLCHAIN_LICENSES;
|
||||
if (typeof license !== 'string' || !satisfies(license, allowed)) {
|
||||
problems.push(
|
||||
`${printable(key)}: licence "${printable(label)}" is not accepted for ` +
|
||||
(shipped ? 'code that ships in the extension' : 'build tooling'),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
for (const name of CREDITED_PACKAGES) {
|
||||
if (!shippedSeen.has(name)) {
|
||||
problems.push(`${printable(name)}: credited as shipping, but not in the lockfile`);
|
||||
}
|
||||
}
|
||||
return { problems, checked, counts };
|
||||
}
|
||||
|
||||
/** @returns {number} exit code */
|
||||
function main() {
|
||||
const lockPath = resolve(fileURLToPath(import.meta.url), '..', '..', 'package-lock.json');
|
||||
/** @type {unknown} */
|
||||
let lock;
|
||||
try {
|
||||
lock = JSON.parse(readFileSync(lockPath, 'utf8'));
|
||||
} catch (cause) {
|
||||
console.error(`::error::check-licenses: cannot read package-lock.json (${String(cause)})`);
|
||||
return 1;
|
||||
}
|
||||
const { problems, checked, counts } = checkLockfile(lock);
|
||||
if (problems.length > 0) {
|
||||
for (const problem of problems) console.error(`::error::check-licenses: ${problem}`);
|
||||
console.error(
|
||||
'\nSee docs/09 §3.2: add the licence to a list, or an EXCEPTIONS entry, on purpose.',
|
||||
);
|
||||
return 1;
|
||||
}
|
||||
const summary = [...counts]
|
||||
.sort((a, b) => b[1] - a[1])
|
||||
.map(([license, n]) => `${printable(license)} ${n}`)
|
||||
.join(', ');
|
||||
console.warn(`check-licenses: clean — ${checked} packages (${summary}).`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
// Run only as the entry point (same guard as check-manifest.mjs).
|
||||
const isEntry =
|
||||
import.meta.url.startsWith('file:') &&
|
||||
process.argv[1] !== undefined &&
|
||||
resolve(process.argv[1]) === fileURLToPath(import.meta.url);
|
||||
if (isEntry) {
|
||||
// exitCode, not exit(): exit() can cut off piped stderr before CI reads it.
|
||||
process.exitCode = main();
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
/**
|
||||
* Types for scripts/credited-packages.mjs, so `wxt.config.ts` and the tests can
|
||||
* import the list. The script itself is plain JavaScript checked with `// @ts-check`.
|
||||
*/
|
||||
export const CREDITED_PACKAGES: readonly string[];
|
||||
@@ -0,0 +1,17 @@
|
||||
// @ts-check
|
||||
/**
|
||||
* The npm packages whose code the build compiles into the extension — docs/14 §5.
|
||||
*
|
||||
* One list behind three gates, so none of them can drift from the others:
|
||||
* - `wxt.config.ts` fails the build when code from any other package ships;
|
||||
* - `tests/unit/third-party.test.ts` requires both notices files to credit
|
||||
* every package named here;
|
||||
* - `scripts/check-licenses.mjs` holds each of them to the licences that may
|
||||
* travel inside a GPL-3.0-or-later extension.
|
||||
*
|
||||
* Through v1.0.x the notices said "none" while three of these shipped. Adding
|
||||
* a name here is the first step of shipping a new package, never the last:
|
||||
* its licence text goes into `legal/THIRD_PARTY_NOTICES.md` and
|
||||
* `src/public/THIRD_PARTY_NOTICES.txt` in the same pull request.
|
||||
*/
|
||||
export const CREDITED_PACKAGES = Object.freeze(['svelte', 'clsx', '@wxt-dev/browser', 'wxt']);
|
||||
@@ -0,0 +1,181 @@
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import {
|
||||
checkLockfile,
|
||||
EXCEPTIONS,
|
||||
packageNameOf,
|
||||
SHIPPED_LICENSES,
|
||||
satisfies,
|
||||
TOOLCHAIN_LICENSES,
|
||||
} from '../../../scripts/check-licenses.mjs';
|
||||
|
||||
/**
|
||||
* scripts/check-licenses.mjs — the licence gate (docs/09 §3.2).
|
||||
*
|
||||
* Called as functions, never spawned: the process-spawning script tests are
|
||||
* the ones that time out under load on Windows (CLAUDE.md, Phase 8).
|
||||
*/
|
||||
|
||||
/** A lockfile with the four shipped packages plus whatever a case adds. */
|
||||
function lockWith(extra: Record<string, object> = {}): object {
|
||||
return {
|
||||
lockfileVersion: 3,
|
||||
packages: {
|
||||
'': { name: 'bookmarkmagic', license: 'GPL-3.0-or-later' },
|
||||
'node_modules/svelte': { version: '5.0.0', license: 'MIT', dev: true },
|
||||
'node_modules/clsx': { version: '2.0.0', license: 'MIT', dev: true },
|
||||
'node_modules/wxt': { version: '0.21.5', license: 'MIT', dev: true },
|
||||
'node_modules/@wxt-dev/browser': { version: '0.1.0', license: 'MIT', dev: true },
|
||||
...extra,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describe('satisfies — SPDX expressions', () => {
|
||||
const allowed = ['MIT', 'Apache-2.0', 'ISC'];
|
||||
|
||||
it.each([
|
||||
['MIT', true],
|
||||
['GPL-3.0-only', false],
|
||||
['MIT OR GPL-3.0-only', true],
|
||||
['GPL-3.0-only OR MIT', true],
|
||||
['MIT AND ISC', true],
|
||||
['MIT AND GPL-3.0-only', false],
|
||||
['(MIT OR GPL-3.0-only) AND ISC', true],
|
||||
['(MIT AND GPL-3.0-only) OR Apache-2.0', true],
|
||||
['(MIT AND GPL-3.0-only) OR AGPL-3.0-only', false],
|
||||
['Apache-2.0 WITH LLVM-exception', true],
|
||||
])('%s → %s', (expression, expected) => {
|
||||
expect(satisfies(expression, allowed)).toBe(expected);
|
||||
});
|
||||
|
||||
it.each([
|
||||
'',
|
||||
'UNLICENSED',
|
||||
'SEE LICENSE IN LICENSE.md',
|
||||
'(MIT',
|
||||
'MIT)',
|
||||
'MIT OR',
|
||||
'AND MIT',
|
||||
'MIT WITH',
|
||||
'Apache 2.0',
|
||||
])('refuses %j', (expression) => {
|
||||
expect(satisfies(expression, allowed)).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe('packageNameOf', () => {
|
||||
it.each([
|
||||
['node_modules/vite', 'vite'],
|
||||
['node_modules/@wxt-dev/browser', '@wxt-dev/browser'],
|
||||
['node_modules/a/node_modules/@scope/b', '@scope/b'],
|
||||
['node_modules/a/node_modules/picomatch', 'picomatch'],
|
||||
])('%s → %s', (key, name) => {
|
||||
expect(packageNameOf(key)).toBe(name);
|
||||
});
|
||||
});
|
||||
|
||||
describe('checkLockfile', () => {
|
||||
it('passes a tree of accepted licences and counts them', () => {
|
||||
const result = checkLockfile(
|
||||
lockWith({
|
||||
'node_modules/lightningcss': { license: 'MPL-2.0', dev: true },
|
||||
'node_modules/x/node_modules/y': { license: 'MIT OR Apache-2.0', dev: true },
|
||||
}),
|
||||
);
|
||||
expect(result.problems).toEqual([]);
|
||||
expect(result.checked).toBe(6);
|
||||
expect(result.counts.get('MIT')).toBe(4);
|
||||
expect(result.counts.get('MPL-2.0')).toBe(1);
|
||||
});
|
||||
|
||||
it('holds shipped packages to the stricter list', () => {
|
||||
// MPL-2.0 is fine for a build tool and not for code inside the extension.
|
||||
const lock = lockWith({ 'node_modules/svelte': { license: 'MPL-2.0', dev: true } });
|
||||
const { problems } = checkLockfile(lock);
|
||||
expect(problems).toHaveLength(1);
|
||||
expect(problems[0]).toContain('node_modules/svelte');
|
||||
expect(problems[0]).toContain('ships in the extension');
|
||||
});
|
||||
|
||||
it('applies the shipped list to a nested copy of a shipped package too', () => {
|
||||
const lock = lockWith({ 'node_modules/a/node_modules/clsx': { license: 'CC0-1.0' } });
|
||||
expect(checkLockfile(lock).problems).toHaveLength(1);
|
||||
});
|
||||
|
||||
it.each([
|
||||
['AGPL-3.0-only'],
|
||||
['SSPL-1.0'],
|
||||
['BUSL-1.1'],
|
||||
['UNLICENSED'],
|
||||
['SEE LICENSE IN EULA.txt'],
|
||||
])('fails a toolchain package licensed %s', (license) => {
|
||||
const { problems } = checkLockfile(lockWith({ 'node_modules/bad': { license } }));
|
||||
expect(problems).toHaveLength(1);
|
||||
expect(problems[0]).toContain('build tooling');
|
||||
});
|
||||
|
||||
it('fails a package with no licence field at all', () => {
|
||||
const { problems, counts } = checkLockfile(
|
||||
lockWith({ 'node_modules/bare': { version: '1.0.0' } }),
|
||||
);
|
||||
expect(problems).toHaveLength(1);
|
||||
expect(problems[0]).toContain('(none)');
|
||||
expect(counts.get('(none)')).toBe(1);
|
||||
});
|
||||
|
||||
it('fails when a credited package is missing from the lockfile', () => {
|
||||
const { 'node_modules/clsx': _gone, ...rest } = (lockWith() as { packages: object })
|
||||
.packages as Record<string, object>;
|
||||
const lock = { lockfileVersion: 3, packages: rest };
|
||||
expect(checkLockfile(lock).problems).toEqual([
|
||||
'clsx: credited as shipping, but not in the lockfile',
|
||||
]);
|
||||
});
|
||||
|
||||
it('skips the root project and workspace links', () => {
|
||||
const lock = lockWith({
|
||||
'packages/local': { link: true },
|
||||
'node_modules/local': { link: true },
|
||||
});
|
||||
expect(checkLockfile(lock).problems).toEqual([]);
|
||||
});
|
||||
|
||||
it('refuses something that is not a v2/v3 lockfile', () => {
|
||||
expect(checkLockfile({ lockfileVersion: 1, dependencies: {} }).problems).toHaveLength(1);
|
||||
expect(checkLockfile(null).problems).toHaveLength(1);
|
||||
});
|
||||
|
||||
it('keeps log output to safe characters', () => {
|
||||
const { problems } = checkLockfile(
|
||||
lockWith({ 'node_modules/evil': { license: 'MIT\n::error::injected' } }),
|
||||
);
|
||||
expect(problems).toHaveLength(1);
|
||||
expect(problems[0]).not.toContain('\n');
|
||||
expect(problems[0]).not.toContain('::error::injected');
|
||||
});
|
||||
});
|
||||
|
||||
describe('the policy itself', () => {
|
||||
it('ships nothing under a copyleft licence', () => {
|
||||
for (const id of SHIPPED_LICENSES) expect(id).not.toMatch(/GPL|MPL|EPL|CDDL|SSPL|BUSL/);
|
||||
});
|
||||
|
||||
it('accepts everything shipped for tooling too', () => {
|
||||
for (const id of SHIPPED_LICENSES) expect(TOOLCHAIN_LICENSES).toContain(id);
|
||||
});
|
||||
|
||||
it('starts with no exceptions — each one is a recorded decision', () => {
|
||||
expect(Object.keys(EXCEPTIONS)).toEqual([]);
|
||||
});
|
||||
|
||||
it('passes the repository lockfile', () => {
|
||||
const lock: unknown = JSON.parse(
|
||||
readFileSync(join(process.cwd(), 'package-lock.json'), 'utf8'),
|
||||
);
|
||||
const { problems, checked } = checkLockfile(lock);
|
||||
expect(problems).toEqual([]);
|
||||
expect(checked).toBeGreaterThan(100);
|
||||
});
|
||||
});
|
||||
@@ -1,6 +1,7 @@
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { CREDITED_PACKAGES } from '../../scripts/credited-packages.mjs';
|
||||
|
||||
/**
|
||||
* Every package the build may compile in is credited — docs/14 §5.
|
||||
@@ -11,16 +12,22 @@ import { describe, expect, it } from 'vitest';
|
||||
* "none" while three packages shipped.
|
||||
*/
|
||||
const read = (path: string): string => readFileSync(join(process.cwd(), path), 'utf8');
|
||||
const CONFIG = read('wxt.config.ts');
|
||||
const credited = [
|
||||
...(/const CREDITED_PACKAGES = \[([^\]]*)\]/.exec(CONFIG)?.[1] ?? '').matchAll(/'([^']+)'/g),
|
||||
].map((m) => m[1] ?? '');
|
||||
const credited = [...CREDITED_PACKAGES];
|
||||
|
||||
describe('third-party notices', () => {
|
||||
it('reads a non-empty credited list from wxt.config.ts', () => {
|
||||
it('reads a non-empty credited list', () => {
|
||||
expect(credited).toEqual(expect.arrayContaining(['svelte', 'clsx']));
|
||||
});
|
||||
|
||||
it('is the list the build gate in wxt.config.ts enforces', () => {
|
||||
// A second, local list in the config would let the build gate and this
|
||||
// test disagree about what ships — the shape this file used to guard by
|
||||
// parsing the config's own source.
|
||||
const config = read('wxt.config.ts');
|
||||
expect(config).toContain("from './scripts/credited-packages.mjs'");
|
||||
expect(config).not.toMatch(/const CREDITED_PACKAGES\s*=/);
|
||||
});
|
||||
|
||||
it.each(['legal/THIRD_PARTY_NOTICES.md', 'src/public/THIRD_PARTY_NOTICES.txt'])(
|
||||
'%s names every credited package and carries an MIT notice for it',
|
||||
(path) => {
|
||||
|
||||
+7
-11
@@ -1,4 +1,5 @@
|
||||
import { defineConfig } from 'wxt';
|
||||
import { CREDITED_PACKAGES } from './scripts/credited-packages.mjs';
|
||||
|
||||
/**
|
||||
* WXT configuration.
|
||||
@@ -51,15 +52,6 @@ const EXTENSION_PAGE_CSP = [
|
||||
"base-uri 'none'",
|
||||
].join('; ');
|
||||
|
||||
/**
|
||||
* Every npm package the build compiles into the extension, each credited in
|
||||
* `legal/THIRD_PARTY_NOTICES.md` and the shipped `THIRD_PARTY_NOTICES.txt`
|
||||
* (docs/14 §5). `tests/unit/third-party.test.ts` checks both files name each
|
||||
* one. Until v1.1.0 the notices said "none" while Svelte's runtime, its `clsx`
|
||||
* dependency and WXT's browser shim all shipped — nothing could notice.
|
||||
*/
|
||||
const CREDITED_PACKAGES = ['svelte', 'clsx', '@wxt-dev/browser', 'wxt'];
|
||||
|
||||
/** The npm package a module id lives in, or undefined for our own code. */
|
||||
function packageOf(id: string): string | undefined {
|
||||
const at = id.lastIndexOf('node_modules');
|
||||
@@ -76,7 +68,10 @@ interface BundleLike {
|
||||
/**
|
||||
* Fail the build when code from an uncredited package ships. Only modules that
|
||||
* actually render count — a package imported and then tree-shaken away is not
|
||||
* in the extension and needs no notice.
|
||||
* in the extension and needs no notice. The list is `CREDITED_PACKAGES` in
|
||||
* `scripts/credited-packages.mjs`, shared with the notices test and the licence
|
||||
* gate (docs/14 §5). Until v1.1.0 the notices said "none" while Svelte's
|
||||
* runtime, its `clsx` dependency and WXT's browser shim all shipped.
|
||||
*/
|
||||
const thirdPartyGate = {
|
||||
name: 'bookmarkmagic:third-party-gate',
|
||||
@@ -97,7 +92,8 @@ const thirdPartyGate = {
|
||||
if (uncredited.length > 0) {
|
||||
this.error(
|
||||
`third-party code ships without a notice: ${uncredited.join(', ')} — add it to ` +
|
||||
'CREDITED_PACKAGES, legal/THIRD_PARTY_NOTICES.md and src/public/THIRD_PARTY_NOTICES.txt',
|
||||
'CREDITED_PACKAGES (scripts/credited-packages.mjs), legal/THIRD_PARTY_NOTICES.md ' +
|
||||
'and src/public/THIRD_PARTY_NOTICES.txt',
|
||||
);
|
||||
}
|
||||
},
|
||||
|
||||
Reference in new issue
Block a user