pkgbld 1.35.1 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # pkgbld
 
-*Build your libraries with ease*
+_Build your libraries with ease_
 
 Rollup-based build tool for building libraries based on package.json config and simple CLI options.
 
@@ -15,6 +15,7 @@ It is created to easily build libraries that contain multiple subpath exports (e
 ## Installation
 
 Using npm:
+
 ```
 npm install --save-dev pkgbld
 ```
@@ -23,7 +24,7 @@ npm install --save-dev pkgbld
 
 1. Start by creating package.json using `npm init`
 2. Add pkgbld `npm install --save-dev pkgbld`
-3. Create `src/index.ts`
+3. Create `src/index.js`
 4. Add pkgbld in the 'scripts' field of your package.json like:
 
 ```json
@@ -34,6 +35,10 @@ npm install --save-dev pkgbld
 
 Run `npm run build`.
 
+For TypeScript or TSX sources, also install
+[`pkgbld-plugin-swc`](https://github.com/kshutkin/package-build/tree/main/pkgbld-plugin-swc).
+`pkgbld` discovers the plugin from your project dependencies and uses SWC to strip types.
+
 ## package.json
 
 `pkgbld` expects the name field to be filled in the package.json file. `exports` field defines what entries/outputs should be built for this package.
@@ -194,76 +199,36 @@ pkgbld --no-exports
 
 Do not add exports field in package.json.
 
-### prune (command)
-
-```
-pkgbld prune
-```
-
-prune devDependencies and redundant scripts from package.json
-
-### prune --profile=<profile>
-
-There are two profiles: `library` and `app`. `library` is default.
-
-Right now it only affects how `prune` command removes entries in the `scripts` field.
-
-For `library` profile it retains: 'preinstall', 'install', 'postinstall', 'prepublish', 'preprepare', 'prepare', 'postprepare'.
-
-For `app` profile it retains in addition: 'prestart', 'start', 'poststart', 'prerestart', 'restart', 'postrestart', 'prestop', 'stop', 'poststop', 'pretest', 'test',        'posttest'.
-
-### flatten
-
-```
-pkgbld prune --flatten=<directory>
-```
-
-Flattens file structure by moving all files from `dist` or other directory to the root directory and updating package.json.
+This also disables entry-point discovery from an existing `exports` field. Only the top-level `src/index` entry point is built
+unless a plugin provides additional inputs.
 
-If the directory is not specified it is guessed from package.json.
+## Build plugin interface
 
-If files cannot be copied because of name conflicts the command will fail.
-
-### removeSourcemaps
-
-```
-pkgbld prune --remove-sourcemaps
-```
-
-Removes all sourcemaps from the package. The logic is very simple and removes all files with `.map` extension and references in format `//# sourceMappingURL=<mapFile>`.
-
-### optimizeFiles (default)
-
-```
-pkgbld prune --optimize-files=false
-```
-
-Optimizes files by removing all files that are not required for pack at the given moment.
-
-You might want to disable this option in some edge cases.
-
-### removeLegalComments
-
-```
-pkgbld prune --remove-legal-comments --compress=es,cjs
-```
+`pkgbld` loads plugins named `pkgbld-plugin-*` or `@scope/pkgbld-plugin-*` from
+`dependencies`, `devDependencies`, and `peerDependencies`. The package name after
+the optional scope must start with `pkgbld-plugin-`.
 
-Removes all legal comments from the package. Only works with compress.
+Plugins implement one or more lifecycle methods on the object returned by the plugin module's `create()` function.
 
-## Plugin API
+Build configuration is resolved from defaults, package metadata, and explicit CLI options before `configure` runs. Plugins receive the effective mutable draft and have final authority. After all `configure` hooks finish, `pkgbld` normalizes, validates, and deeply freezes the configuration; every later hook receives that frozen value.
 
-`pkgbld` reads all installed packages named `pkgbld-plugin-*` and assumes they are plugins
+Build entries are resolved after configuration. A plugin that needs to add a source module does so during `contributeEntries`; later phases receive immutable entries containing the canonical name, concrete source path, source extension, and enabled output paths. Configured UMD and preprocessing selections must resolve to discovered Build entries.
 
-Plugins suppose to implement one or more of the following interface methods on an object that returned by `create()` function exported by the plugin module.
+`shared` is mutable state scoped to one build for coordination between plugins. Lifecycle phase boundaries are preserved, but plugin order within one phase is not guaranteed and asynchronous hooks in that phase may run in parallel. Plugins must not depend on the order of same-phase reads and writes. State owned by one plugin should remain in the closure created by `create()`.
 
 ```typescript
 interface PkgbldPlugin {
-    options(parsedArgs: {[key: string]: string | number}, options: ReturnType<typeof getCliOptions>): void;
-    processPackageJson(packageJson: PackageJson, inputs: string[], logger: Logger): void;
-    processTsConfig(config: Json): void;
-    providePlugins(provider: Provider, config: Record<string, string | string[] | boolean>, inputs: string[]): Promise<void>;
-    getExtraOutputSettings(format: InternalModuleFormat, inputs: string[]): Partial<OutputOptions>;
-    buildEnd(): Promise<void>;
+  configure(context: {
+    draft: BuildConfigurationDraft;
+    sources: BuildConfigurationSources;
+    shared: Map<unknown, unknown>;
+  }): void;
+  contributeEntries(context: PluginContributeEntriesContext): void;
+  processPackageJson(context: PluginPackageContext): void;
+  processTsConfig(context: PluginTsConfigContext): void;
+  providePlugins(context: PluginRollupContext): Promise<void>;
+  getExtraOutputSettings(context: PluginOutputContext): Partial<OutputOptions>;
+  buildEnd(context: PluginBuildEndContext): Promise<void>;
 }
 ```
 

package/index.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-'use strict';
-import('./dist/index.mjs');
+
+import('./src/index.js');

package/package.json

@@ -1,15 +1,23 @@
 {
-  "version": "1.35.1",
+  "version": "2.0.0",
   "name": "pkgbld",
   "license": "MIT",
   "author": "Konstantin Shutkin",
   "bin": "./index.js",
   "type": "module",
-  "main": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./options": {
+      "types": "./types/index.d.ts",
+      "default": "./src/options/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "engines": {
     "node": ">=20"
   },
@@ -28,28 +36,24 @@
     "rollup"
   ],
   "dependencies": {
-    "@niceties/logger": "^1.1.13",
-    "@niceties/draftlog-appender": "^1.3.3",
-    "lodash": "^4.17.21",
-    "rollup": "^4.34.7",
-    "rollup-plugin-typescript2": "^0.36.0",
+    "@niceties/logger": "^2.1.1",
+    "@niceties/draftlog-appender": "^2.1.1",
+    "fast-is-equal": "^1.3.3",
+    "type-fest": "^5.9.0",
+    "rollup": "^4.63.1",
     "rollup-plugin-preprocess": "^0.0.4",
-    "@rollup/plugin-commonjs": "^28.0.2",
-    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-commonjs": "^29.0.3",
+    "@rollup/plugin-terser": "^1.0.0",
     "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^16.0.0",
-    "@rollup-extras/plugin-clean": "^1.3.9",
-    "@rollup-extras/plugin-binify": "^1.1.10",
-    "@rollup-extras/plugin-externals": "^1.2.2",
-    "@slimlib/refine-partition": "^1.0.3",
-    "@slimlib/smart-mock": "^0.1.6",
-    "is-builtin-module": "^3.2.1",
-    "terser": "^5.39.0",
-    "kleur": "^4.1.5",
-    "cleye": "^1.3.4",
-    "jsonata": "^2.0.6"
-  },
-  "peerDependencies": {
-    "typescript": ">=5.3.3"
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup-extras/plugin-clean": "^2.0.1",
+    "@rollup-extras/plugin-binify": "^2.0.0",
+    "@rollup-extras/plugin-externals": "^2.0.0",
+    "@slimlib/refine-partition": "^2.0.2",
+    "@slimlib/smart-mock": "^1.0.2",
+    "is-builtin-module": "^5.0.0",
+    "terser": "^5.51.2",
+    "@niceties/ansi": "^1.1.2",
+    "@niceties/node-parseargs-plus": "^0.6.0"
   }
 }

package/src/build-configuration.js

@@ -0,0 +1,395 @@
+import { parseArgsPlus } from '@niceties/node-parseargs-plus';
+import { camelCase } from '@niceties/node-parseargs-plus/camel-case';
+import { customValue } from '@niceties/node-parseargs-plus/custom-value';
+import { help } from '@niceties/node-parseargs-plus/help';
+
+import { cliFlags, cliFlagsDefaults as defaults } from './options/index.js';
+
+/**
+ * @typedef {import('type-fest').PackageJson} PackageJson
+ * @typedef {import('./types.js').BuildFormat} BuildFormat
+ * @typedef {import('./types.js').BuildConfiguration} BuildConfiguration
+ * @typedef {import('./types.js').BuildConfigurationDraft} BuildConfigurationDraft
+ * @typedef {import('./types.js').ParsedOptions} ParsedOptions
+ * @typedef {ReturnType<typeof import('./build-plugin-lifecycle.js').createBuildPluginLifecycle>} BuildPluginLifecycle
+ */
+
+const formats = new Set(['es', 'cjs', 'umd']);
+
+export class BuildConfigurationError extends Error {
+    /**
+     * @param {{ code: string; path: string; message: string; value?: unknown }[]} issues
+     * @param {{ cause?: unknown }} [options]
+     */
+    constructor(issues, options) {
+        super(`Invalid Build configuration:\n${issues.map(issue => `- ${issue.path}: ${issue.message}`).join('\n')}`, options);
+        this.name = 'BuildConfigurationError';
+        this.issues = issues;
+    }
+}
+
+/**
+ * Resolves the immutable Build configuration for one build.
+ *
+ * @param {{
+ *   argv?: readonly string[];
+ *   packageJson: PackageJson;
+ *   pluginLifecycle: BuildPluginLifecycle;
+ * }} input
+ * @returns {BuildConfiguration}
+ */
+export function resolveBuildConfiguration({ argv = process.argv.slice(2), packageJson, pluginLifecycle }) {
+    const draft = createDefaultDraft();
+    const defaultSource = deepFreeze(structuredClone(draft));
+    applyPackageMetadata(draft, packageJson);
+
+    const cli = parseCli(argv, packageJson);
+    applyCli(draft, cli.values, cli.provided);
+
+    const sources = deepFreeze({
+        defaults: defaultSource,
+        package: structuredClone(packageJson),
+        cli: {
+            values: structuredClone(cli.values),
+            provided: { ...cli.provided },
+        },
+    });
+
+    try {
+        pluginLifecycle.configure(draft, sources);
+    } catch (cause) {
+        throw new BuildConfigurationError(
+            [{ code: 'PLUGIN_CONFIGURATION_FAILED', path: 'plugins', message: 'Build plugin configuration failed' }],
+            { cause }
+        );
+    }
+
+    const structuralIssues = validateStructure(createDefaultDraft(), draft);
+    if (structuralIssues.length > 0) {
+        throw new BuildConfigurationError(structuralIssues);
+    }
+
+    normalize(draft);
+    const issues = validate(draft, packageJson);
+    if (issues.length > 0) {
+        throw new BuildConfigurationError(issues);
+    }
+
+    return /** @type {BuildConfiguration} */ (deepFreeze(draft));
+}
+
+/** @returns {BuildConfigurationDraft} */
+function createDefaultDraft() {
+    return {
+        paths: {
+            sourceDir: defaults.src,
+            outputDir: defaults.dest,
+        },
+        outputs: {
+            formats: /** @type {BuildFormat[]} */ ([...defaults.formats]),
+            patterns: {
+                es: defaults.esmPattern,
+                cjs: defaults.commonjsPattern,
+                umd: defaults.umdPattern,
+            },
+            umdEntries: [...defaults.umd],
+            sourcemaps: /** @type {BuildFormat[]} */ ([...defaults.sourcemaps]),
+        },
+        transforms: {
+            compress: /** @type {BuildFormat[]} */ ([...defaults.compress]),
+            preprocess: [...defaults.preprocess],
+            includeExternals: defaults.includeExternals,
+            removeLegalComments: false,
+        },
+        packageJson: {
+            update: true,
+            format: defaults.formatPackageJson,
+            exports: true,
+            pack: true,
+            executables: { mode: 'infer', values: [] },
+        },
+        typescript: {
+            updateConfig: defaults.tsConfig,
+        },
+        execution: {
+            clean: true,
+            bundle: true,
+            eject: defaults.eject,
+        },
+    };
+}
+
+/**
+ * @param {BuildConfigurationDraft} draft
+ * @param {PackageJson} packageJson
+ */
+function applyPackageMetadata(draft, packageJson) {
+    if (typeof packageJson.umd === 'string') {
+        draft.outputs.umdEntries.push('index');
+        draft.outputs.formats.push('umd');
+    }
+}
+
+/**
+ * @param {readonly string[]} argv
+ * @param {PackageJson} packageJson
+ */
+function parseCli(argv, packageJson) {
+    const result = parseArgsPlus(
+        {
+            args: [...argv],
+            name: 'pkgbld',
+            version: packageJson.version ?? '<unknown>',
+            options: /** @type {any} */ (cliFlags),
+            allowNegative: true,
+            tokens: true,
+        },
+        [help, camelCase, customValue]
+    );
+    /** @type {Record<string, boolean>} */
+    const provided = {};
+    for (const token of result.tokens ?? []) {
+        if (token.kind === 'option') {
+            provided[toCamelCase(token.name)] = true;
+        }
+    }
+    return { values: /** @type {ParsedOptions} */ (result.values), provided };
+}
+
+/**
+ * @param {BuildConfigurationDraft} draft
+ * @param {ParsedOptions} flags
+ * @param {Record<string, boolean>} provided
+ */
+function applyCli(draft, flags, provided) {
+    if (provided.formats) {
+        draft.outputs.formats = [.../** @type {BuildFormat[]} */ (flags.formats)];
+        if (!draft.outputs.formats.includes('umd') && !provided.umd) {
+            draft.outputs.umdEntries = [];
+        }
+    }
+    if (provided.umd) {
+        draft.outputs.umdEntries = [.../** @type {string[]} */ (flags.umd)];
+        if (draft.outputs.umdEntries.length === 0 && !provided.formats) {
+            draft.outputs.formats = draft.outputs.formats.filter(format => format !== 'umd');
+        }
+    }
+    if (provided.compress) draft.transforms.compress = [.../** @type {BuildFormat[]} */ (flags.compress)];
+    if (provided.sourcemaps) draft.outputs.sourcemaps = [.../** @type {BuildFormat[]} */ (flags.sourcemaps)];
+    if (provided.preprocess) draft.transforms.preprocess = [.../** @type {string[]} */ (flags.preprocess)];
+    if (provided.dest) draft.paths.outputDir = /** @type {string} */ (flags.dest);
+    if (provided.src) draft.paths.sourceDir = /** @type {string} */ (flags.src);
+    if (provided.bin) {
+        const values = /** @type {string[]} */ (flags.bin);
+        draft.packageJson.executables = { mode: values.length > 0 ? 'explicit' : 'disabled', values: [...values] };
+    }
+    if (provided.includeExternals) {
+        draft.transforms.includeExternals = /** @type {boolean | string[]} */ (flags.includeExternals);
+    }
+    if (provided.eject) draft.execution.eject = /** @type {boolean} */ (flags.eject);
+    if (provided.tsConfig) draft.typescript.updateConfig = /** @type {boolean} */ (flags.tsConfig);
+    if (provided.updatePackageJson) draft.packageJson.update = /** @type {boolean} */ (flags.updatePackageJson);
+    if (provided.commonjsPattern) draft.outputs.patterns.cjs = /** @type {string} */ (flags.commonjsPattern);
+    if (provided.esmPattern) draft.outputs.patterns.es = /** @type {string} */ (flags.esmPattern);
+    if (provided.umdPattern) draft.outputs.patterns.umd = /** @type {string} */ (flags.umdPattern);
+    if (provided.formatPackageJson) draft.packageJson.format = /** @type {boolean} */ (flags.formatPackageJson);
+    if (provided.pack) draft.packageJson.pack = /** @type {boolean} */ (flags.pack);
+    if (provided.exports) draft.packageJson.exports = /** @type {boolean} */ (flags.exports);
+    if (provided.clean) draft.execution.clean = /** @type {boolean} */ (flags.clean);
+    if (provided.bundle) draft.execution.bundle = /** @type {boolean} */ (flags.bundle);
+    if (provided.removeLegalComments) {
+        draft.transforms.removeLegalComments = /** @type {boolean} */ (flags.removeLegalComments);
+    }
+}
+
+/** @param {BuildConfigurationDraft} draft */
+function normalize(draft) {
+    if (Array.isArray(draft.outputs?.formats)) draft.outputs.formats = unique(draft.outputs.formats);
+    if (Array.isArray(draft.outputs?.umdEntries)) draft.outputs.umdEntries = unique(draft.outputs.umdEntries);
+    if (Array.isArray(draft.outputs?.sourcemaps)) draft.outputs.sourcemaps = unique(draft.outputs.sourcemaps);
+    if (Array.isArray(draft.transforms?.compress)) draft.transforms.compress = unique(draft.transforms.compress);
+    if (Array.isArray(draft.transforms?.preprocess)) draft.transforms.preprocess = unique(draft.transforms.preprocess);
+    if (Array.isArray(draft.transforms.includeExternals)) {
+        draft.transforms.includeExternals = unique(draft.transforms.includeExternals);
+    }
+    if (Array.isArray(draft.packageJson?.executables?.values)) {
+        draft.packageJson.executables.values = unique(draft.packageJson.executables.values.filter(Boolean));
+        if (draft.packageJson.executables.mode === 'explicit' && draft.packageJson.executables.values.length === 0) {
+            draft.packageJson.executables.mode = 'disabled';
+        }
+    }
+    if (
+        Array.isArray(draft.outputs?.umdEntries) &&
+        Array.isArray(draft.outputs?.formats) &&
+        draft.outputs.umdEntries.length > 0 &&
+        !draft.outputs.formats.includes('umd')
+    ) {
+        draft.outputs.formats.push('umd');
+    }
+}
+
+/**
+ * @param {BuildConfigurationDraft} draft
+ * @param {PackageJson} packageJson
+ */
+function validate(draft, packageJson) {
+    /** @type {{ code: string; path: string; message: string; value?: unknown }[]} */
+    const issues = [];
+    validateFormats(draft.outputs.formats, 'outputs.formats', issues);
+    validateFormats(draft.outputs.sourcemaps, 'outputs.sourcemaps', issues);
+    validateFormats(draft.transforms.compress, 'transforms.compress', issues);
+    validateStrings(draft.outputs.umdEntries, 'outputs.umdEntries', issues);
+    validateStrings(draft.transforms.preprocess, 'transforms.preprocess', issues);
+    if (draft.outputs.umdEntries.length > 0 && typeof packageJson.name !== 'string') {
+        issues.push({ code: 'PACKAGE_NAME_REQUIRED', path: 'package.name', message: 'a package name is required for UMD entries' });
+    }
+    for (const [format, pattern] of Object.entries(draft.outputs.patterns)) {
+        if (typeof pattern !== 'string' || !pattern.includes('[name]')) {
+            issues.push({
+                code: 'INVALID_FILE_NAME_PATTERN',
+                path: `outputs.patterns.${format}`,
+                message: 'must contain [name]',
+                value: pattern,
+            });
+        }
+    }
+    for (const [path, value] of [
+        ['paths.sourceDir', draft.paths.sourceDir],
+        ['paths.outputDir', draft.paths.outputDir],
+    ]) {
+        if (typeof value !== 'string' || value.length === 0) {
+            issues.push({ code: 'INVALID_PATH', path, message: 'must be a non-empty string', value });
+        }
+    }
+    if (
+        typeof draft.transforms.includeExternals !== 'boolean' &&
+        (!Array.isArray(draft.transforms.includeExternals) ||
+            draft.transforms.includeExternals.some(value => typeof value !== 'string' || value.length === 0))
+    ) {
+        issues.push({
+            code: 'INVALID_EXTERNALS',
+            path: 'transforms.includeExternals',
+            message: 'must be a boolean or an array of non-empty strings',
+            value: draft.transforms.includeExternals,
+        });
+    }
+    if (!['infer', 'disabled', 'explicit'].includes(draft.packageJson.executables.mode)) {
+        issues.push({
+            code: 'INVALID_EXECUTABLE_MODE',
+            path: 'packageJson.executables.mode',
+            message: 'must be infer, disabled, or explicit',
+            value: draft.packageJson.executables.mode,
+        });
+    }
+    validateStrings(draft.packageJson.executables.values, 'packageJson.executables.values', issues);
+    return issues;
+}
+
+/**
+ * @param {object} expected
+ * @param {unknown} actual
+ * @returns {{ code: string; path: string; message: string; value?: unknown }[]}
+ */
+function validateStructure(expected, actual) {
+    /** @type {{ code: string; path: string; message: string; value?: unknown }[]} */
+    const issues = [];
+    visit(expected, actual, '');
+    return issues;
+
+    /**
+     * @param {unknown} expected
+     * @param {unknown} actual
+     * @param {string} path
+     */
+    function visit(expected, actual, path) {
+        if (Array.isArray(expected)) {
+            if (!Array.isArray(actual)) {
+                issues.push({ code: 'INVALID_CONFIGURATION_SHAPE', path, message: 'must be an array', value: actual });
+            }
+            return;
+        }
+        if (typeof expected !== 'object' || expected == null) {
+            const isExternalList = path === 'transforms.includeExternals' && Array.isArray(actual);
+            if (!isExternalList && typeof actual !== typeof expected) {
+                issues.push({
+                    code: 'INVALID_CONFIGURATION_SHAPE',
+                    path,
+                    message: `must be ${typeof expected}`,
+                    value: actual,
+                });
+            }
+            return;
+        }
+        if (typeof actual !== 'object' || actual == null || Array.isArray(actual)) {
+            issues.push({ code: 'INVALID_CONFIGURATION_SHAPE', path, message: 'must be an object', value: actual });
+            return;
+        }
+        for (const key of Object.keys(actual)) {
+            const keyPath = path ? `${path}.${key}` : key;
+            if (!(key in expected)) {
+                issues.push({ code: 'UNKNOWN_CONFIGURATION_KEY', path: keyPath, message: 'is not a recognized configuration key' });
+            }
+        }
+        for (const key of Object.keys(expected)) {
+            const keyPath = path ? `${path}.${key}` : key;
+            if (!(key in actual)) {
+                issues.push({ code: 'MISSING_CONFIGURATION_KEY', path: keyPath, message: 'is required' });
+                continue;
+            }
+            visit(/** @type {Record<string, unknown>} */ (expected)[key], /** @type {Record<string, unknown>} */ (actual)[key], keyPath);
+        }
+    }
+}
+
+/**
+ * @param {unknown} values
+ * @param {string} path
+ * @param {{ code: string; path: string; message: string; value?: unknown }[]} issues
+ */
+function validateFormats(values, path, issues) {
+    if (!Array.isArray(values)) {
+        issues.push({ code: 'INVALID_FORMATS', path, message: 'must be an array', value: values });
+        return;
+    }
+    for (const value of values) {
+        if (!formats.has(value)) {
+            issues.push({ code: 'UNSUPPORTED_FORMAT', path, message: `unsupported format ${JSON.stringify(value)}`, value });
+        }
+    }
+}
+
+/**
+ * @param {unknown} values
+ * @param {string} path
+ * @param {{ code: string; path: string; message: string; value?: unknown }[]} issues
+ */
+function validateStrings(values, path, issues) {
+    if (!Array.isArray(values)) {
+        issues.push({ code: 'INVALID_LIST', path, message: 'must be an array', value: values });
+        return;
+    }
+    for (const value of values) {
+        if (typeof value !== 'string' || value.length === 0) {
+            issues.push({ code: 'INVALID_LIST_VALUE', path, message: 'must contain non-empty strings', value });
+        }
+    }
+}
+
+/** @template T @param {T[]} values @returns {T[]} */
+function unique(values) {
+    return [...new Set(values)];
+}
+
+/** @param {string} value */
+function toCamelCase(value) {
+    return value.replace(/-([a-z])/g, (_, character) => character.toUpperCase());
+}
+
+/** @template T @param {T} value @returns {T} */
+function deepFreeze(value) {
+    if (typeof value !== 'object' || value == null || Object.isFrozen(value)) return value;
+    for (const nested of Object.values(value)) {
+        deepFreeze(nested);
+    }
+    return Object.freeze(value);
+}