pkgbld 1.35.1 → 2.0.0

package/src/build-entries.js

@@ -0,0 +1,214 @@
+import path from 'node:path';
+
+import { isExists } from './helpers.js';
+
+/**
+ * @typedef {import('./types.js').BuildConfiguration} BuildConfiguration
+ * @typedef {import('./types.js').BuildEntries} BuildEntries
+ * @typedef {import('./types.js').BuildEntry} BuildEntry
+ * @typedef {import('./types.js').BuildEntryContribution} BuildEntryContribution
+ * @typedef {import('./types.js').BuildEntryContributions} BuildEntryContributions
+ * @typedef {import('./types.js').BuildEntryIssue} BuildEntryIssue
+ * @typedef {import('./types.js').BuildFormat} BuildFormat
+ */
+
+const sourceFileExtensions = /** @type {const} */ (['ts', 'tsx', 'js', 'jsx', 'cjs', 'mjs']);
+
+export class BuildEntryError extends Error {
+    /** @param {BuildEntryIssue[]} issues */
+    constructor(issues) {
+        super(issues.map(issue => `${issue.path}: ${issue.message}`).join('\n'));
+        this.name = 'BuildEntryError';
+        this.issues = issues;
+    }
+}
+
+/**
+ * Resolve package-declared and Build plugin-contributed entry specifications into
+ * one immutable catalog.
+ *
+ * @param {readonly string[]} packageEntryNames
+ * @param {BuildConfiguration} configuration
+ * @param {(contributions: BuildEntryContributions) => void} contribute
+ * @returns {Promise<BuildEntries>}
+ */
+export async function resolveBuildEntries(packageEntryNames, configuration, contribute) {
+    /** @type {(BuildEntryContribution & { issuePath: string })[]} */
+    const specifications = packageEntryNames.map((name, index) => ({ name, issuePath: `package.entries[${index}]` }));
+    let contributionIndex = 0;
+    const contributions = {
+        /** @param {BuildEntryContribution} contribution */
+        add(contribution) {
+            specifications.push({ ...contribution, issuePath: `plugins.entries[${contributionIndex}]` });
+            contributionIndex += 1;
+        },
+    };
+    contribute(contributions);
+
+    /** @type {BuildEntryIssue[]} */
+    const issues = [];
+    /** @type {BuildEntry[]} */
+    const values = [];
+    /** @type {Map<string, BuildEntry>} */
+    const byName = new Map();
+
+    for (const specification of specifications) {
+        const { issuePath } = specification;
+        const name = normalizeName(specification.name, issuePath, issues);
+        if (!name) continue;
+        if (byName.has(name)) {
+            issues.push({
+                code: 'DUPLICATE_BUILD_ENTRY',
+                path: issuePath,
+                name,
+                message: `Build entry ${JSON.stringify(name)} is declared more than once`,
+            });
+            continue;
+        }
+
+        const source = await resolveSource(name, specification.sourcePath, configuration.paths.sourceDir);
+        if (!source) {
+            issues.push({
+                code: 'SOURCE_NOT_FOUND',
+                path: issuePath,
+                name,
+                message: `Build entry ${JSON.stringify(name)} has no supported source file`,
+            });
+            continue;
+        }
+
+        /** @type {Partial<Record<BuildFormat, string>>} */
+        const outputPaths = {};
+        for (const format of configuration.outputs.formats) {
+            if (format !== 'umd' || configuration.outputs.umdEntries.includes(name)) {
+                outputPaths[format] =
+                    `./${configuration.paths.outputDir}/${configuration.outputs.patterns[format].replace('[name]', name)}`;
+            }
+        }
+        const entry = Object.freeze({
+            name,
+            sourcePath: source.sourcePath,
+            extension: source.extension,
+            outputPaths: Object.freeze(outputPaths),
+        });
+        values.push(entry);
+        byName.set(name, entry);
+    }
+
+    validateSelections(byName, configuration.outputs.umdEntries, 'outputs.umdEntries', issues);
+    validateSelections(byName, configuration.transforms.preprocess, 'transforms.preprocess', issues);
+    validateOutputPaths(values, issues);
+
+    if (issues.length > 0) throw new BuildEntryError(issues);
+
+    const frozenValues = Object.freeze(values);
+    return Object.freeze({
+        values: frozenValues,
+        /** @param {string} name */
+        require(name) {
+            const entry = byName.get(name);
+            if (!entry) {
+                throw new BuildEntryError([
+                    {
+                        code: 'SELECTED_BUILD_ENTRY_NOT_FOUND',
+                        path: 'entries',
+                        name,
+                        message: `Build entry ${JSON.stringify(name)} was not discovered; available entries: ${values.map(entry => entry.name).join(', ')}`,
+                    },
+                ]);
+            }
+            return entry;
+        },
+    });
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} issuePath
+ * @param {BuildEntryIssue[]} issues
+ */
+function normalizeName(value, issuePath, issues) {
+    if (typeof value !== 'string') {
+        issues.push({ code: 'INVALID_BUILD_ENTRY_NAME', path: issuePath, message: 'Build entry name must be a string' });
+        return;
+    }
+    const name = value.replaceAll('\\', '/');
+    const segments = name.split('/');
+    if (
+        name.length === 0 ||
+        name.startsWith('/') ||
+        name.startsWith('./') ||
+        path.isAbsolute(name) ||
+        segments.some(segment => segment === '' || segment === '.' || segment === '..')
+    ) {
+        issues.push({
+            code: 'INVALID_BUILD_ENTRY_NAME',
+            path: issuePath,
+            name,
+            message: `Invalid Build entry name ${JSON.stringify(value)}`,
+        });
+        return;
+    }
+    return name;
+}
+
+/**
+ * @param {string} name
+ * @param {string | undefined} providedPath
+ * @param {string} sourceDir
+ * @returns {Promise<{ sourcePath: string; extension: import('./types.js').BuildEntryExtension } | undefined>}
+ */
+async function resolveSource(name, providedPath, sourceDir) {
+    if (providedPath != null) {
+        if (!(await isExists(providedPath))) return;
+        const extension = path.extname(providedPath).slice(1);
+        if (!sourceFileExtensions.includes(/** @type {typeof sourceFileExtensions[number]} */ (extension))) return;
+        return { sourcePath: providedPath, extension: /** @type {import('./types.js').BuildEntryExtension} */ (extension) };
+    }
+    for (const extension of sourceFileExtensions) {
+        const sourcePath = `./${sourceDir}/${name}.${extension}`;
+        if (await isExists(sourcePath)) return { sourcePath, extension };
+    }
+}
+
+/**
+ * @param {Map<string, BuildEntry>} byName
+ * @param {readonly string[]} names
+ * @param {string} selectionPath
+ * @param {BuildEntryIssue[]} issues
+ */
+function validateSelections(byName, names, selectionPath, issues) {
+    for (const [index, name] of names.entries()) {
+        if (!byName.has(name)) {
+            issues.push({
+                code: 'SELECTED_BUILD_ENTRY_NOT_FOUND',
+                path: `${selectionPath}[${index}]`,
+                name,
+                message: `Build entry ${JSON.stringify(name)} was selected but not discovered`,
+            });
+        }
+    }
+}
+
+/**
+ * @param {BuildEntry[]} entries
+ * @param {BuildEntryIssue[]} issues
+ */
+function validateOutputPaths(entries, issues) {
+    const owners = new Map();
+    for (const entry of entries) {
+        for (const [format, outputPath] of Object.entries(entry.outputPaths)) {
+            const owner = owners.get(outputPath);
+            if (owner) {
+                issues.push({
+                    code: 'OUTPUT_PATH_COLLISION',
+                    path: `entries.${entry.name}.outputPaths.${format}`,
+                    name: entry.name,
+                    message: `Output path ${JSON.stringify(outputPath)} is also produced by Build entry ${JSON.stringify(owner)}`,
+                });
+            } else {
+                owners.set(outputPath, entry.name);
+            }
+        }
+    }
+}

package/src/build-plugin-lifecycle.js

@@ -0,0 +1,100 @@
+/**
+ * @typedef {import('rollup').InternalModuleFormat} InternalModuleFormat
+ * @typedef {import('rollup').OutputOptions} OutputOptions
+ * @typedef {import('type-fest').JsonObject} JsonObject
+ * @typedef {import('type-fest').PackageJson} PackageJson
+ * @typedef {import('./types.js').BuildConfiguration} BuildConfiguration
+ * @typedef {import('./types.js').BuildConfigurationDraft} BuildConfigurationDraft
+ * @typedef {import('./types.js').BuildConfigurationSources} BuildConfigurationSources
+ * @typedef {import('./types.js').BuildEntries} BuildEntries
+ * @typedef {import('./types.js').BuildEntryContributions} BuildEntryContributions
+ * @typedef {import('./types.js').PackageProcessingResult} PackageProcessingResult
+ * @typedef {import('./types.js').PkgbldPlugin} PkgbldPlugin
+ * @typedef {import('./types.js').PluginSharedState} PluginSharedState
+ * @typedef {import('./types.js').Provider} Provider
+ */
+
+/**
+ * Owns Build plugin invocation and shared state for one build.
+ *
+ * The lifecycle preserves phase boundaries, but does not guarantee plugin order
+ * within a phase. Asynchronous hooks in the same phase run concurrently.
+ * Build plugins must not rely on same-phase shared-state reads and writes.
+ *
+ * @param {Partial<PkgbldPlugin>[]} plugins
+ */
+export function createBuildPluginLifecycle(plugins) {
+    /** @type {PluginSharedState} */
+    const shared = new Map();
+
+    return {
+        /**
+         * @param {BuildConfigurationDraft} draft
+         * @param {BuildConfigurationSources} sources
+         */
+        configure(draft, sources) {
+            for (const plugin of plugins) {
+                plugin.configure?.({ draft, sources, shared });
+            }
+        },
+
+        /**
+         * @param {BuildEntryContributions} entries
+         * @param {BuildConfiguration} configuration
+         */
+        contributeEntries(entries, configuration) {
+            for (const plugin of plugins) {
+                plugin.contributeEntries?.({ entries, configuration, shared });
+            }
+        },
+
+        /**
+         * @param {JsonObject} config
+         * @param {BuildConfiguration} configuration
+         */
+        processTsConfig(config, configuration) {
+            for (const plugin of plugins) {
+                plugin.processTsConfig?.({ config, configuration, shared });
+            }
+        },
+
+        /**
+         * @param {PackageJson} packageJson
+         * @param {BuildEntries} entries
+         * @param {BuildConfiguration} configuration
+         */
+        processPackageJson(packageJson, entries, configuration) {
+            for (const plugin of plugins) {
+                plugin.processPackageJson?.({ packageJson, entries, configuration, shared });
+            }
+        },
+
+        /**
+         * @param {Provider} provider
+         * @param {BuildConfiguration} configuration
+         * @param {PackageProcessingResult} packageResult
+         */
+        async provideRollupPlugins(provider, configuration, packageResult) {
+            await Promise.all(plugins.map(plugin => plugin.providePlugins?.({ provider, configuration, packageResult, shared })));
+        },
+
+        /**
+         * @param {Partial<OutputOptions>} settings
+         * @param {InternalModuleFormat} format
+         * @param {string[]} inputs
+         * @param {BuildConfiguration} configuration
+         */
+        extendOutputSettings(settings, format, inputs, configuration) {
+            for (const plugin of plugins) {
+                if (plugin.getExtraOutputSettings) {
+                    Object.assign(settings, plugin.getExtraOutputSettings({ format, inputs, configuration, shared }));
+                }
+            }
+        },
+
+        /** @param {BuildConfiguration} configuration */
+        async buildEnd(configuration) {
+            await Promise.all(plugins.map(plugin => plugin.buildEnd?.({ configuration, shared })));
+        },
+    };
+}

package/src/builtin-plugins/binify.js

@@ -0,0 +1,31 @@
+import { Priority } from '../priorities.js';
+
+/**
+ * @typedef {import('rollup').OutputChunk} OutputChunk
+ * @typedef {import('../types.js').BuildConfiguration} BuildConfiguration
+ * @typedef {import('../types.js').PackageProcessingResult} PackageProcessingResult
+ * @typedef {import('../types.js').Provider} Provider
+ */
+
+/**
+ * @param {Provider} provider
+ * @param {BuildConfiguration} configuration
+ * @param {PackageProcessingResult} packageResult
+ */
+export default async function (provider, configuration, packageResult) {
+    if (packageResult.executableOutputs.length > 0) {
+        const pluginBinify = await provider.import('@rollup-extras/plugin-binify');
+
+        provider.provide(
+            () =>
+                pluginBinify({
+                    filter: (/** @type {OutputChunk} */ item) =>
+                        item.type === 'chunk' &&
+                        item.isEntry &&
+                        packageResult.executableOutputs.some(input => input === `./${configuration.paths.outputDir}/${item.fileName}`),
+                }),
+            Priority.finalize,
+            { outputPlugin: true, format: 'cjs' }
+        );
+    }
+}

package/src/builtin-plugins/clean.js

@@ -0,0 +1,30 @@
+import { Priority } from '../priorities.js';
+
+/**
+ * @typedef {import('../types.js').BuildConfiguration} BuildConfiguration
+ * @typedef {import('../types.js').Provider} Provider
+ */
+
+/**
+ * @param {Provider} provider
+ * @param {BuildConfiguration} configuration
+ */
+export default async function (provider, configuration) {
+    if (!configuration.execution.clean) {
+        return;
+    }
+
+    const pluginClean = await provider.import('@rollup-extras/plugin-clean');
+
+    const pluginInstance = pluginClean();
+
+    provider.provide(pluginFactory, Priority.cleanup, { outputPlugin: true });
+
+    let firstPluginInstance = true;
+
+    function pluginFactory() {
+        const result = firstPluginInstance ? pluginInstance : pluginInstance.api.addInstance();
+        firstPluginInstance = false;
+        return result;
+    }
+}

package/src/builtin-plugins/commonjs.js

@@ -0,0 +1,14 @@
+import { Priority } from '../priorities.js';
+
+/**
+ * @typedef {import('../types.js').Provider} Provider
+ */
+
+/**
+ * @param {Provider} provider
+ */
+export default async function (provider) {
+    const pluginCommonjs = await provider.import('@rollup/plugin-commonjs');
+
+    provider.provide(() => pluginCommonjs(), Priority.commonjs);
+}

package/src/builtin-plugins/externals.js

@@ -0,0 +1,107 @@
+import path from 'node:path';
+
+import { Priority } from '../priorities.js';
+
+/**
+ * @param {(...args: any[]) => any} fn
+ * @param {any[]} args
+ * @returns {any}
+ */
+export function curry(fn, ...args) {
+    return args.length >= fn.length
+        ? fn(...args)
+        : /** @type {(...nextArgs: any[]) => any} */ ((...nextArgs) => curry(fn, ...args, ...nextArgs));
+}
+
+/**
+ * @typedef {import('rollup').InternalModuleFormat} InternalModuleFormat
+ * @typedef {import('../types.js').BuildConfiguration} BuildConfiguration
+ * @typedef {import('../types.js').PackageProcessingResult} PackageProcessingResult
+ * @typedef {import('../types.js').Provider} Provider
+ */
+
+/**
+ * @param {Provider} provider
+ * @param {BuildConfiguration} configuration
+ * @param {PackageProcessingResult} packageResult
+ */
+export default async function (provider, configuration, packageResult) {
+    const inputs = packageResult.entries.values.map(entry => entry.sourcePath);
+    if (configuration.transforms.includeExternals === true) {
+        return;
+    }
+
+    const pluginExternals = await provider.import('@rollup-extras/plugin-externals');
+
+    const allowGenericUmd = configuration.outputs.umdEntries.length === 1 && inputs.length === 1;
+
+    if (configuration.outputs.formats.length > 0) {
+        const format = /** @type {InternalModuleFormat[]} */ (
+            allowGenericUmd ? undefined : configuration.outputs.formats.filter(format => format !== 'umd')
+        );
+        provider.provide(
+            () =>
+                pluginExternals(
+                    configuration.transforms.includeExternals === false
+                        ? {}
+                        : (/** @type {string} */ id, /** @type {boolean} */ external, /** @type {string} */ importer) =>
+                              includeExternals(importer, external, id, configuration)
+                ),
+            Priority.externals,
+            { format }
+        );
+        provider.globalImport('path', 'path');
+        provider.globalSetup(includeExternals);
+    }
+
+    if (!allowGenericUmd && configuration.outputs.umdEntries.length > 0) {
+        const curryForConfig = /** @type {typeof curry} */ (provider.globalSetup(curry) ?? curry);
+        for (const entryName of configuration.outputs.umdEntries) {
+            const currentInput = packageResult.entries.require(entryName).sourcePath;
+            const isExternal = curryForConfig(
+                (
+                    /** @type {string} */ currentInput,
+                    /** @type {string} */ id,
+                    /** @type {boolean} */ external,
+                    /** @type {string} */ importer
+                ) => includeExternals(importer, external, id, configuration) || isExternalInput(currentInput, inputs, id)
+            )(currentInput);
+            provider.provide(() => pluginExternals(isExternal), Priority.externals, {
+                format: 'umd',
+                inputs: [currentInput],
+            });
+        }
+        if (configuration.outputs.formats.length === 0) {
+            provider.globalImport('path', 'path');
+            provider.globalSetup(includeExternals);
+        }
+        provider.globalSetup(isExternalInput);
+    }
+}
+
+/**
+ * @param {string} _importer
+ * @param {boolean} external
+ * @param {string} id
+ * @param {BuildConfiguration} configuration
+ */
+function includeExternals(_importer, external, id, configuration) {
+    if (configuration.transforms.includeExternals === false) return external;
+    if (!external) return false;
+    const internals = /** @type {readonly string[]} */ (configuration.transforms.includeExternals);
+    if (internals.includes(id) || internals.some(internal => id.includes(internal))) {
+        return false;
+    }
+    return true;
+}
+
+/**
+ * @param {string} currentInput
+ * @param {string | readonly string[]} inputs
+ * @param {string} id
+ */
+function isExternalInput(currentInput, inputs, id) {
+    const normalizedPath = path.isAbsolute(currentInput) ? `./${path.relative(process.cwd(), currentInput)}` : currentInput;
+    const normalizedId = path.isAbsolute(id) ? `./${path.relative(process.cwd(), id)}` : id;
+    return normalizedPath !== normalizedId && inputs.includes(normalizedPath);
+}

package/src/builtin-plugins/json.js

@@ -0,0 +1,14 @@
+import { Priority } from '../priorities.js';
+
+/**
+ * @typedef {import('../types.js').Provider} Provider
+ */
+
+/**
+ * @param {Provider} provider
+ */
+export default async function (provider) {
+    const pluginJson = await provider.import('@rollup/plugin-json');
+
+    provider.provide(() => pluginJson(), Priority.preprocess);
+}

package/src/builtin-plugins/preprocess.js

@@ -0,0 +1,37 @@
+import { Priority } from '../priorities.js';
+
+/**
+ * @typedef {import('rollup').InternalModuleFormat} InternalModuleFormat
+ * @typedef {import('../types.js').BuildConfiguration} BuildConfiguration
+ * @typedef {import('../types.js').PackageProcessingResult} PackageProcessingResult
+ * @typedef {import('../types.js').Provider} Provider
+ */
+
+/**
+ * @param {Provider} provider
+ * @param {BuildConfiguration} configuration
+ * @param {PackageProcessingResult} packageResult
+ */
+export default async function (provider, configuration, packageResult) {
+    if (configuration.transforms.preprocess.length > 0) {
+        const pluginPreprocess = /** @type {typeof import('rollup-plugin-preprocess')} */ (
+            await provider.import('rollup-plugin-preprocess')
+        );
+
+        const include = configuration.transforms.preprocess.map(name => packageResult.entries.require(name).sourcePath);
+
+        for (const format of /** @type {readonly InternalModuleFormat[]} */ (configuration.outputs.formats)) {
+            if (format !== 'umd') {
+                provider.provide(() => pluginPreprocess.default({ include, context: { [format]: true } }), Priority.preprocess, { format });
+            } else {
+                for (const entryName of configuration.outputs.umdEntries) {
+                    const currentInput = packageResult.entries.require(entryName).sourcePath;
+                    provider.provide(() => pluginPreprocess.default({ include, context: { umd: true } }), Priority.preprocess, {
+                        format,
+                        inputs: [currentInput],
+                    });
+                }
+            }
+        }
+    }
+}

package/src/builtin-plugins/resolve.js

@@ -0,0 +1,14 @@
+import { Priority } from '../priorities.js';
+
+/**
+ * @typedef {import('../types.js').Provider} Provider
+ */
+
+/**
+ * @param {Provider} provider
+ */
+export default async function (provider) {
+    const pluginResolve = await provider.import('@rollup/plugin-node-resolve');
+
+    provider.provide(() => pluginResolve(), Priority.resolve);
+}

package/src/builtin-plugins/terser.js

@@ -0,0 +1,50 @@
+import { Priority } from '../priorities.js';
+
+/**
+ * @typedef {import('rollup').InternalModuleFormat} InternalModuleFormat
+ * @typedef {import('../types.js').BuildConfiguration} BuildConfiguration
+ * @typedef {import('../types.js').PackageProcessingResult} PackageProcessingResult
+ * @typedef {import('../types.js').Provider} Provider
+ */
+
+/**
+ * @param {Provider} provider
+ * @param {BuildConfiguration} configuration
+ * @param {PackageProcessingResult} packageResult
+ */
+export default async function (provider, configuration, packageResult) {
+    const filteredFormats = configuration.transforms.compress.filter(format => configuration.outputs.formats.includes(format));
+
+    if (filteredFormats.length > 0) {
+        const pluginTerser = await provider.import('@rollup/plugin-terser');
+
+        const options = {
+            mangle: {
+                properties: {
+                    regex: /_$/,
+                },
+            },
+        };
+
+        if (configuration.transforms.removeLegalComments) {
+            /** @type {any} */ (options).output = {
+                comments: false,
+            };
+        }
+
+        for (const format of /** @type {InternalModuleFormat[]} */ (filteredFormats)) {
+            if (format !== 'umd') {
+                provider.provide(() => pluginTerser(options), Priority.compress, { format, outputPlugin: true });
+            } else {
+                for (const entryName of configuration.outputs.umdEntries) {
+                    const currentInput = packageResult.entries.require(entryName).sourcePath;
+                    provider.provide(() => pluginTerser(options), Priority.compress, {
+                        format,
+                        outputPlugin: true,
+                        inputs: [currentInput],
+                    });
+                }
+            }
+        }
+    }
+}