@companion-module/tools 2.7.2 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.9.0](https://github.com/bitfocus/companion-module-tools/compare/v2.8.0...v2.9.0) (2026-10-29)
+
+
+### Features
+
+* support node26 ([51caa8c](https://github.com/bitfocus/companion-module-tools/commit/51caa8c05b054537184677e74292c9631d0052c5))
+
+## [2.8.0](https://github.com/bitfocus/companion-module-tools/compare/v2.7.2...v2.8.0) (2026-08-28)
+
+
+### Features
+
+* backport license validator ([d26e43c](https://github.com/bitfocus/companion-module-tools/commit/d26e43cd581824f37f95099342bf015e6097b9f7))
+
+
 ## [2.7.2](https://github.com/bitfocus/companion-module-tools/compare/v2.7.1...v2.7.2) (2026-05-11)
 
 

package/README.md

@@ -14,6 +14,49 @@ More information on this command is available [on the wiki](https://github.com/b
 
 Generate the new format manifest from an old `package.json`.
 
+## Node.js versions
+
+Modules declare the Node.js version they run on with `runtime.type` in `companion/manifest.json`. New modules, and
+existing ones when convenient, are recommended to use `node26`.
+
+A matching TypeScript config is available for each version, and `node26` is the recommended one:
+
+```json
+{
+	"extends": "@companion-module/tools/tsconfig/node26/recommended.json"
+}
+```
+
+It uses `"module": "node20"`, so a file is compiled as ESM or CommonJS according to the `type` in its nearest
+`package.json`. It targets ES2025, which requires TypeScript 6 or later. The `node18` and `node22` configs remain
+available for modules that have not moved yet.
+
+## Licensing
+
+A module has two licenses, and they are not the same thing:
+
+- `license` in `package.json` is the license of the code you wrote. This must be `MIT`, so module source always stays
+  portable and can be reused anywhere.
+- `license` in `companion/manifest.json` is the license the packaged module is distributed under. A build bundles your
+  code together with its dependencies, so this has to be a license that whole blob can be shipped under.
+
+Your own code stays MIT even when a dependency is copyleft. If you bundle a GPL-3.0 dependency, your source stays MIT
+while the manifest declares `GPL-3.0-only`, because that is what the combined package must be distributed as. Anyone
+reusing your source on its own still gets it under MIT.
+
+The build and check commands validate your production dependencies against the manifest license. Supported values are
+`MIT` (recommended, it can use the most of npm), `GPL-2.0-only` and `GPL-3.0-only`. Dual licensing is not supported,
+and a module which declares no license in its manifest falls back to the one in `package.json`.
+
+Everything reachable through `dependencies` is checked, whether or not webpack ends up bundling it. `devDependencies`
+are never checked. A build also writes an aggregated `LICENSE` (and a `NOTICE`, where dependencies ship one) into the
+package, collected from the license files of everything it ships.
+
+Some older packages ship a license file but declare no license in their `package.json`, so there is nothing to check
+against. Those are listed in `scripts/lib/known-package-licenses.js` once their license has been confirmed from what
+they publish, so open a PR there if you hit one. A license a package declares itself always wins over that list.
+
+Pass `--ignore-license-rules` to report license problems as warnings instead of failing the command.
 
 ## Upgrading from v1.x to v2.0
 
@@ -21,8 +64,8 @@ v2.0 of this library includes some breaking changes to how eslint and prettier h
 
 This change was done for two reasons:
 
-1) Very few modules use eslint, making this extra weight for them for no gain.
-2) Recent versions of yarn do not expose these binaries in a way which is easily callable by modules, requiring tricks to be able to execute them.
+1. Very few modules use eslint, making this extra weight for them for no gain.
+2. Recent versions of yarn do not expose these binaries in a way which is easily callable by modules, requiring tricks to be able to execute them.
 
 To resolve this, you will need to do a `yarn add --dev eslint prettier` in your modules to install the dependencies, and update any scripts to remove the invocation hacks.
 
@@ -42,7 +85,7 @@ If using TypeScript, you should specify a `typescriptRoot`:
 import { generateEslintConfig } from '@companion-module/tools/eslint/config.mjs'
 
 export default generateEslintConfig({
-    enableTypescript: true,
+	enableTypescript: true,
 })
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@companion-module/tools",
-  "version": "2.7.2",
+  "version": "2.9.0",
   "type": "module",
   "main": "index.js",
   "license": "MIT",
@@ -15,8 +15,11 @@
     "companion-surface-build": "scripts/build-surface.js",
     "companion-surface-check": "scripts/check-surface.js"
   },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
   "engines": {
-    "node": "^18.18 || ^22.18"
+    "node": "^18.18 || ^22.18 || ^26"
   },
   "files": [
     "eslint",
@@ -35,6 +38,7 @@
     "find-up": "^7.0.0",
     "parse-author": "^2.0.0",
     "semver": "^7.7.4",
+    "spdx-expression-parse": "^5.0.0",
     "tar": "^7.5.9",
     "webpack": "^5.105.2",
     "webpack-cli": "^6.0.1",

package/scripts/build-connection.js

@@ -3,17 +3,20 @@
 import 'zx/globals'
 
 import { buildPackage } from './lib/build-util.js'
+import { LicensePolicyError } from './lib/license-warning-util.js'
+import { ignoreLicenseRules } from './lib/cli-options.js'
 
 if (process.platform === 'win32') {
 	usePowerShell() // to enable powershell
 }
 
 if (argv.help) {
-	console.log('Usage: companion-module-build [--dev] [--prerelease]')
+	console.log('Usage: companion-module-build [--dev] [--prerelease] [--ignore-license-rules]')
 	console.log('Builds the companion connection module')
 	console.log('  --dev: Build in development mode. This will not minify the code, making it easier to debug.')
 	console.log('  --prerelease: Build in prerelease mode. This gets added as metadata to the manifest')
 	console.log('  --output <filename>: Output to a specific filename, without a file extension')
+	console.log('  --ignore-license-rules: Report license policy issues as warnings instead of failing')
 	process.exit(0)
 }
 
@@ -24,4 +27,11 @@ if (!validateManifest) {
 	validateManifest = manifestPkg.validateManifest
 }
 
-await buildPackage('@companion-module/base', validateManifest, 'connection', '>=1.4.0 <3.0.0')
+try {
+	await buildPackage('@companion-module/base', validateManifest, 'connection', '>=1.4.0 <3.0.0', {
+		ignoreLicenseRules: ignoreLicenseRules(argv),
+	})
+} catch (e) {
+	if (e instanceof LicensePolicyError) process.exitCode = 1
+	else throw e
+}

package/scripts/build-surface.js

@@ -3,20 +3,30 @@
 import 'zx/globals'
 
 import { buildPackage } from './lib/build-util.js'
+import { LicensePolicyError } from './lib/license-warning-util.js'
+import { ignoreLicenseRules } from './lib/cli-options.js'
 
 if (process.platform === 'win32') {
 	usePowerShell() // to enable powershell
 }
 
 if (argv.help) {
-	console.log('Usage: companion-module-build [--dev] [--prerelease]')
+	console.log('Usage: companion-module-build [--dev] [--prerelease] [--ignore-license-rules]')
 	console.log('Builds the companion connection module')
 	console.log('  --dev: Build in development mode. This will not minify the code, making it easier to debug.')
 	console.log('  --prerelease: Build in prerelease mode. This gets added as metadata to the manifest')
 	console.log('  --output <filename>: Output to a specific filename, without a file extension')
+	console.log('  --ignore-license-rules: Report license policy issues as warnings instead of failing')
 	process.exit(0)
 }
 
 const { validateSurfaceManifest } = await import('@companion-surface/base')
 
-await buildPackage('@companion-surface/base', validateSurfaceManifest, 'surface', '>=1.0.0 <2.0.0')
+try {
+	await buildPackage('@companion-surface/base', validateSurfaceManifest, 'surface', '>=1.0.0 <2.0.0', {
+		ignoreLicenseRules: ignoreLicenseRules(argv),
+	})
+} catch (e) {
+	if (e instanceof LicensePolicyError) process.exitCode = 1
+	else throw e
+}

package/scripts/check-connection.js

@@ -7,11 +7,21 @@ import { fs } from 'zx'
 import { findUp } from 'find-up'
 import { validateManifest } from '@companion-module/base'
 import { createRequire } from 'module'
+import { checkPackage } from './lib/check-util.js'
+import { LicensePolicyError } from './lib/license-warning-util.js'
+import { ignoreLicenseRules } from './lib/cli-options.js'
 
 if (process.platform === 'win32') {
 	usePowerShell() // to enable powershell
 }
 
+if (argv.help) {
+	console.log('Usage: companion-module-check [--ignore-license-rules]')
+	console.log('Checks the companion connection module')
+	console.log('  --ignore-license-rules: Report license policy issues as warnings instead of failing')
+	process.exit(0)
+}
+
 const require = createRequire(import.meta.url)
 
 async function findModuleDir(cwd) {
@@ -30,11 +40,12 @@ console.log(`Checking for: ${process.cwd()}`)
 console.log(`Tools path: ${toolsDir}`)
 console.log(`Framework path: ${frameworkDir}`)
 
-const manifestJson = JSON.parse(await fs.readFile(path.resolve('./companion/manifest.json')))
-
 try {
-	validateManifest(manifestJson)
+	await checkPackage({ validateManifest, ignoreLicenseRules: ignoreLicenseRules(argv) })
 } catch (e) {
-	console.error('Manifest validation failed', e)
-	process.exit(1)
+	if (e instanceof LicensePolicyError) process.exitCode = 1
+	else {
+		console.error('Manifest validation failed', e)
+		process.exit(1)
+	}
 }

package/scripts/check-surface.js

@@ -7,11 +7,21 @@ import { fs } from 'zx'
 import { findUp } from 'find-up'
 import { validateSurfaceManifest } from '@companion-surface/base'
 import { createRequire } from 'module'
+import { checkPackage } from './lib/check-util.js'
+import { LicensePolicyError } from './lib/license-warning-util.js'
+import { ignoreLicenseRules } from './lib/cli-options.js'
 
 if (process.platform === 'win32') {
 	usePowerShell() // to enable powershell
 }
 
+if (argv.help) {
+	console.log('Usage: companion-surface-check [--ignore-license-rules]')
+	console.log('Checks the companion surface module')
+	console.log('  --ignore-license-rules: Report license policy issues as warnings instead of failing')
+	process.exit(0)
+}
+
 const require = createRequire(import.meta.url)
 
 async function findModuleDir(cwd) {
@@ -30,11 +40,15 @@ console.log(`Checking for: ${process.cwd()}`)
 console.log(`Tools path: ${toolsDir}`)
 console.log(`Framework path: ${frameworkDir}`)
 
-const manifestJson = JSON.parse(await fs.readFile(path.resolve('./companion/manifest.json')))
-
 try {
-	validateSurfaceManifest(manifestJson)
+	await checkPackage({
+		validateManifest: validateSurfaceManifest,
+		ignoreLicenseRules: ignoreLicenseRules(argv),
+	})
 } catch (e) {
-	console.error('Manifest validation failed', e)
-	process.exit(1)
+	if (e instanceof LicensePolicyError) process.exitCode = 1
+	else {
+		console.error('Manifest validation failed', e)
+		process.exit(1)
+	}
 }

package/scripts/lib/build-util.js

@@ -6,6 +6,13 @@ import { findUp } from 'find-up'
 import * as tar from 'tar'
 import { createRequire } from 'module'
 import * as semver from 'semver'
+import {
+	collectInstalledPackages,
+	collectProductionPackages,
+	createLegalInventory,
+	writeLegalArtifacts,
+} from './license-util.js'
+import { enforceLicensePolicy } from './license-warning-util.js'
 
 function toSanitizedDirname(name) {
 	return name.replace(/[^a-zA-Z0-9-\.]/g, '-').replace(/[-+]/g, '-')
@@ -21,7 +28,7 @@ async function findModuleDir(cwd) {
 	return path.dirname(pkgJsonPath)
 }
 
-export async function buildPackage(frameworkPackageName, validateManifest, moduleType, versionRange) {
+export async function buildPackage(frameworkPackageName, validateManifest, moduleType, versionRange, options = {}) {
 	// const toolsDir = path.join(__dirname, '..')
 	const moduleDir = process.cwd()
 	const toolsDir = await findModuleDir(require.resolve('@companion-module/tools'))
@@ -234,6 +241,19 @@ export async function buildPackage(frameworkPackageName, validateManifest, modul
 		}
 	}
 
+	// The externals the build just resolved are exactly the names the bundler kept out of main.js
+	const shippedPackages = await collectProductionPackages(moduleDir, Object.keys(packageJson.dependencies))
+	if (Object.keys(packageJson.dependencies).length) {
+		// The externals tree yarn just installed is the exact set which ships alongside the bundle
+		shippedPackages.packages.push(...(await collectInstalledPackages(path.join(packageBaseDir, 'node_modules'))))
+	}
+	const legalInventory = await createLegalInventory(shippedPackages.packages)
+	for (const diagnostic of [...shippedPackages.diagnostics, ...legalInventory.diagnostics]) {
+		console.warn(`License inventory: ${diagnostic}`)
+	}
+	await writeLegalArtifacts(packageBaseDir, legalInventory)
+	enforceLicensePolicy(legalInventory, { ignoreLicenseRules: options.ignoreLicenseRules })
+
 	// Create tgz of the build
 	let tgzFile = toSanitizedDirname(`${manifestJson.id}-${manifestJson.version}`)
 	if (typeof argv['output'] === 'string') {

package/scripts/lib/check-util.js

@@ -0,0 +1,23 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { enforceLicensePolicy } from './license-warning-util.js'
+import { analyzeShippedLegalInventory } from './license-util.js'
+
+/**
+ * @param {object} options
+ * @param {(manifest: any, looseChecks: boolean) => void} options.validateManifest
+ * @param {string} [options.cwd]
+ * @param {boolean} [options.ignoreLicenseRules]
+ * @param {Pick<NodeJS.WriteStream, 'write' | 'isTTY'>} [options.stderr]
+ * @returns {Promise<void>}
+ */
+export async function checkPackage(options) {
+	const cwd = options.cwd ?? process.cwd()
+	const manifest = JSON.parse(await readFile(path.join(cwd, 'companion', 'manifest.json'), 'utf8'))
+	options.validateManifest(manifest, false)
+	const inventory = await analyzeShippedLegalInventory(cwd)
+	enforceLicensePolicy(inventory, {
+		ignoreLicenseRules: options.ignoreLicenseRules,
+		stderr: options.stderr,
+	})
+}

package/scripts/lib/cli-options.js

@@ -0,0 +1,8 @@
+/**
+ * @param {Record<string, unknown>} argv
+ * @returns {boolean}
+ */
+export function ignoreLicenseRules(argv) {
+	const value = argv['ignore-license-rules']
+	return value === true || value === 'true'
+}

package/scripts/lib/known-package-licenses.js

@@ -0,0 +1,93 @@
+/**
+ * Packages which ship no license declaration in their package.json, but whose license has been confirmed by reading
+ * what they publish. Only add an entry after checking that version yourself, and record where the license was found.
+ *
+ * Keys are exact `name@version`, as a later release can change license. A declared license always wins over this list,
+ * so an entry can never hide what a package says about itself.
+ *
+ * @type {Record<string, string>}
+ */
+export const KNOWN_PACKAGE_LICENSES = {
+	// LICENSE.md, "The MIT License", https://github.com/bwindels/exif-parser
+	'exif-parser@0.1.12': 'MIT',
+	// Readme.md "## License" section in the published tarball, and a LICENSE added to
+	// https://github.com/component/indexof after this version was published
+	'indexof@0.0.1': 'MIT',
+	// Readme.md "## License" section in the published tarball, and a LICENSE added to
+	// https://github.com/component/inherit after this version was published
+	'component-inherit@0.0.3': 'MIT',
+	// Readme.md "## License" section in the published tarball, and a LICENSE added to
+	// https://github.com/component/bind after this version was published
+	'component-bind@1.0.0': 'MIT',
+	// COPYING in the published tarball is the Boost Software License 1.0 with the notice retention paragraph removed,
+	// so it imposes strictly less than BSL-1.0 and recording it as that can only ever overstate its obligations.
+	// https://github.com/russellmcc/node-binpack
+	'binpack@0.1.0': 'BSL-1.0',
+	// LICENSE in the published tarball is BSD-3-Clause, including the clause forbidding use of the copyright holder's
+	// name to endorse derived products, https://github.com/fairoakslabs/bufferpack
+	'bufferpack@0.0.6': 'BSD-3-Clause',
+	// LICENSE, "(The MIT License)", in the published tarball, npm metadata claims MIT but package.json declares
+	// nothing, https://github.com/vercel/ms
+	'ms@0.7.1': 'MIT',
+	// cycle.js in the published tarball carries "Public Domain." in its header comment, and the author has since
+	// added "license": "Public-Domain" to https://github.com/dscape/cycle
+	'cycle@1.0.3': 'Public-Domain',
+	// component.json and bower.json both declare "MIT" in the published tarball, only package.json omits it,
+	// https://github.com/component/emitter (1.1.2 republished from https://github.com/sindresorhus/component-emitter)
+	'emitter-component@1.1.1': 'MIT',
+	'emitter-component@1.1.2': 'MIT',
+	// LICENSE, "The MIT License (MIT)", in the published tarball, https://github.com/changchang/seq-queue
+	'seq-queue@0.0.5': 'MIT',
+	// license, "MIT License", in the published tarball, https://github.com/fabiospampinato/atomically
+	'atomically@2.0.3': 'MIT',
+	// license, "MIT License", in the published tarball, https://github.com/fabiospampinato/stubborn-fs
+	'stubborn-fs@1.2.5': 'MIT',
+}
+
+/**
+ * @param {string | undefined} name
+ * @param {string | undefined} version
+ * @returns {string | undefined}
+ */
+export function knownPackageLicense(name, version) {
+	if (!name || !version) return undefined
+	return KNOWN_PACKAGE_LICENSES[`${name}@${version}`]
+}
+
+/**
+ * Packages which declare a license that is not a valid SPDX expression, mapped to what the license text they publish
+ * actually is. Unlike KNOWN_PACKAGE_LICENSES this overrides what a package says about itself, so it is only consulted
+ * when the declaration cannot be parsed, and can never turn a real license into a more convenient one.
+ *
+ * Only add an entry after reading the license text shipped in that exact version, and record what identified it.
+ * Keys are exact `name@version`, so a later release declaring something different is unaffected.
+ *
+ * @type {Record<string, string>}
+ */
+export const CORRECTED_PACKAGE_LICENSES = {
+	// Declares "BSD". LICENSE is BSD-3-Clause: three conditions, the third forbidding use of the author's name to
+	// endorse derived products, which is exactly what separates it from BSD-2-Clause.
+	'url-template@2.0.8': 'BSD-3-Clause',
+	// Declares "MIT License", which is the name rather than the identifier. LICENSE is "The MIT License (MIT)".
+	'xml-escape@1.1.0': 'MIT',
+	// Declares "Apache 2.0" through the deprecated licenses array. LICENSE is the Apache License 2.0, followed by an
+	// MIT notice covering the QR library vendored into vendor/QRCode, whose text the inventory collects as well.
+	'qrcode-terminal@0.12.0': 'Apache-2.0',
+	// Declares "Apache2", which is neither the identifier nor the name. LICENSE is the verbatim Apache License 2.0
+	// including its appendix, with no NOTICE file to propagate, https://git.coolaj86.com/coolaj86/ssl-root-cas.js
+	'ssl-root-cas@1.3.1': 'Apache-2.0',
+	// Declares the pair through the deprecated licenses array as "AFLv2.1" and "BSD", each linking a line of the Dojo
+	// LICENSE the package is covered by. That file names its BSD half "BSD 3-Clause \"New\" License", including the
+	// clause forbidding use of the Dojo Foundation's name to endorse derived products, https://github.com/kriszyp/json-schema
+	'json-schema@0.2.3': '(AFL-2.1 OR BSD-3-Clause)',
+}
+
+/**
+ * @param {string | undefined} name
+ * @param {string | undefined} version
+ * @returns {string | undefined}
+ */
+export function correctedPackageLicense(name, version) {
+	if (!name || !version) return undefined
+	return CORRECTED_PACKAGE_LICENSES[`${name}@${version}`]
+}