pkgbld 1.36.0 → 2.1.0

package/src/load-plugins.js

@@ -0,0 +1,37 @@
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * @typedef {import('type-fest').PackageJson} PackageJson
+ */
+
+import { isPluginPackageName } from './plugin-name.js';
+
+/**
+ * @param {PackageJson} pkg
+ * @param {Set<string>} loaded
+ * @param {string} packageJsonPath
+ */
+export async function loadPlugins(pkg, loaded, packageJsonPath) {
+    const resolveFromPackage = createRequire(packageJsonPath).resolve;
+    return await Promise.all(
+        [
+            ...new Set([
+                ...Object.keys(pkg.devDependencies || {}),
+                ...Object.keys(pkg.dependencies || {}),
+                ...Object.keys(pkg.peerDependencies || {}),
+            ]),
+        ]
+            .filter(packageName => isPluginPackageName(packageName) && !loaded.has(packageName))
+            .map(async packageName => {
+                loaded.add(packageName);
+                try {
+                    const pluginPath = resolveFromPackage(packageName);
+                    const pluginFactory = await import(pathToFileURL(pluginPath).href);
+                    return await pluginFactory.create();
+                } catch (cause) {
+                    throw new Error(`Failed to load Build plugin ${JSON.stringify(packageName)} from ${packageJsonPath}`, { cause });
+                }
+            })
+    );
+}

package/src/messages.js

@@ -0,0 +1,13 @@
+import { getTimeDiff } from './helpers.js';
+
+/**
+ * @param {string} sourceDir
+ * @param {string} dir
+ * @param {number} configsCount
+ * @param {number} startingTime
+ * @param {number} [finishedCount]
+ */
+export const mainLoggerText =
+    (sourceDir, dir, configsCount, startingTime, finishedCount = 0) =>
+    (final = false) =>
+        `${sourceDir} → ${dir} ${final ? configsCount : finishedCount++} / ${configsCount}${final ? ` in ${getTimeDiff(startingTime)}` : ''}`;

package/src/options/index.js

@@ -0,0 +1,277 @@
+/** @typedef {import('./types.js').PackageJson} PackageJson */
+
+/**
+ * @param {unknown} value
+ * @returns {value is PackageJson}
+ */
+export function isPackageJson(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const obj = /** @type {Record<string, unknown>} */ (value);
+    if (obj.private !== undefined && typeof obj.private !== 'boolean') return false;
+    if (obj.version !== undefined && typeof obj.version !== 'string') return false;
+    if (obj.name !== undefined && typeof obj.name !== 'string') return false;
+    if (obj.main !== undefined && typeof obj.main !== 'string') return false;
+    if (obj.license !== undefined && typeof obj.license !== 'string') return false;
+    if (obj.readme !== undefined && typeof obj.readme !== 'string') return false;
+    if (obj.description !== undefined && typeof obj.description !== 'string') return false;
+    if (obj.bugs !== undefined && typeof obj.bugs !== 'string') return false;
+    if (obj.homepage !== undefined && typeof obj.homepage !== 'string') return false;
+    if (obj.bin !== undefined && typeof obj.bin !== 'string' && (typeof obj.bin !== 'object' || obj.bin === null || Array.isArray(obj.bin)))
+        return false;
+    if (
+        obj.author !== undefined &&
+        typeof obj.author !== 'string' &&
+        (typeof obj.author !== 'object' || obj.author === null || Array.isArray(obj.author))
+    )
+        return false;
+    return true;
+}
+
+/**
+ * @param {string} value
+ * @returns {string[]}
+ */
+function CommaSeparatedString(value) {
+    if (value === '') return [];
+    return value.split(',').map((/** @type {string} */ arg) => arg.trim());
+}
+
+/**
+ * @param {string} value
+ * @returns {true | string[]}
+ */
+function CommaSeparatedStringOrBoolean(value) {
+    if (value === '') {
+        return true;
+    }
+    return CommaSeparatedString(value);
+}
+
+export const cliFlagsDefaults = {
+    formats: /** @type {string[]} */ (['es', 'cjs']),
+    umd: /** @type {string[]} */ ([]),
+    compress: /** @type {string[]} */ (['umd']),
+    sourcemaps: /** @type {string[]} */ (['umd']),
+    preprocess: /** @type {string[]} */ ([]),
+    dest: 'dist',
+    src: 'src',
+    bin: /** @type {string[] | undefined} */ (undefined),
+    includeExternals: /** @type {boolean | string[]} */ (false),
+    imports: false,
+    conditions: /** @type {string[]} */ ([]),
+    eject: false,
+    tsConfig: false,
+    updatePackageJson: true,
+    commonjsPattern: '[name].cjs',
+    esmPattern: '[name].mjs',
+    umdPattern: '[name].umd.js',
+    formatPackageJson: false,
+};
+
+/**
+ * @typedef {{
+ *   type: 'string' | 'boolean' | ((value: string) => unknown);
+ *   description: string;
+ *   default?: string | boolean | string[] | boolean[];
+ *   optionalValue?: boolean;
+ * }} CliFlag
+ */
+
+/** @type {Record<string, CliFlag>} */
+export const cliFlags = {
+    umd: {
+        type: /** @type {(value: string) => string[]} */ (CommaSeparatedString),
+        description: 'Package subpath exports in UMD format',
+    },
+    compress: {
+        type: /** @type {(value: string) => string[]} */ (CommaSeparatedString),
+        description: 'Compress formats using terser',
+    },
+    sourcemaps: {
+        type: /** @type {(value: string) => string[]} */ (CommaSeparatedString),
+        description: 'Emit sourcemaps for the specified formats',
+    },
+    formats: {
+        type: /** @type {(value: string) => string[]} */ (CommaSeparatedString),
+        description: 'Formats to emit',
+    },
+    preprocess: {
+        type: /** @type {(value: string) => string[]} */ (CommaSeparatedString),
+        description: 'Preprocess entry points / subpath exports',
+    },
+    dest: {
+        type: /** @type {'string'} */ ('string'),
+        description: 'Output directory',
+        default: cliFlagsDefaults.dest,
+    },
+    src: {
+        type: /** @type {'string'} */ ('string'),
+        description: 'Source directory',
+        default: cliFlagsDefaults.src,
+    },
+    bin: {
+        type: /** @type {(value: string) => string[]} */ (CommaSeparatedString),
+        description: 'Executable files',
+    },
+    includeExternals: {
+        type: /** @type {(value: string) => true | string[]} */ (CommaSeparatedStringOrBoolean),
+        description: 'Include all/specified externals into the result bundle(s)',
+        optionalValue: true,
+    },
+    imports: {
+        type: /** @type {'boolean'} */ ('boolean'),
+        description: 'Build and preserve package imports',
+        default: cliFlagsDefaults.imports,
+    },
+    conditions: {
+        type: /** @type {(value: string) => string[]} */ (CommaSeparatedString),
+        description: 'Additional conditions for resolving bundled dependencies',
+    },
+    eject: {
+        type: /** @type {'boolean'} */ ('boolean'),
+        description: 'Eject config',
+        default: cliFlagsDefaults.eject,
+    },
+    tsConfig: {
+        type: /** @type {'boolean'} */ ('boolean'),
+        description: 'Create / update tsconfig.json',
+        default: cliFlagsDefaults.tsConfig,
+    },
+    updatePackageJson: {
+        type: /** @type {'boolean'} */ ('boolean'),
+        description: 'Create / update package.json',
+        default: cliFlagsDefaults.updatePackageJson,
+    },
+    commonjsPattern: {
+        type: /** @type {'string'} */ ('string'),
+        description: 'CommonJS output file name pattern',
+        default: cliFlagsDefaults.commonjsPattern,
+    },
+    esmPattern: {
+        type: /** @type {'string'} */ ('string'),
+        description: 'ES output file name pattern',
+        default: cliFlagsDefaults.esmPattern,
+    },
+    umdPattern: {
+        type: /** @type {'string'} */ ('string'),
+        description: 'UMD output file name pattern',
+        default: cliFlagsDefaults.umdPattern,
+    },
+    formatPackageJson: {
+        type: /** @type {'boolean'} */ ('boolean'),
+        description: 'Format package.json',
+        default: cliFlagsDefaults.formatPackageJson,
+    },
+    pack: {
+        type: /** @type {'boolean'} */ ('boolean'),
+        description: 'Pack',
+        default: true,
+    },
+    exports: {
+        type: /** @type {'boolean'} */ ('boolean'),
+        description: 'Add exports field to package.json',
+        default: true,
+    },
+    clean: {
+        type: /** @type {'boolean'} */ ('boolean'),
+        description: 'Clean the output directory',
+        default: true,
+    },
+    bundle: {
+        type: /** @type {'boolean'} */ ('boolean'),
+        description: 'Bundle',
+        default: true,
+    },
+    removeLegalComments: {
+        type: /** @type {'boolean'} */ ('boolean'),
+        description: 'Remove legal comments',
+        default: false,
+    },
+};
+
+export const packageJsonFieldsOrder = new Set([
+    'private',
+    'type',
+    'version',
+    'name',
+    'scope', // custom
+    'description',
+    'license',
+    'author',
+    'contributors',
+    'funding',
+    'bin',
+    'main',
+    'browser',
+    'unpkg',
+    'module',
+    'svelte',
+    'exports',
+    'imports',
+    'types',
+    'typings',
+    'typesVersions', // non standard but required for typescript with resolution other than nodenext
+    'files',
+    'packageManager',
+    'sideEffects',
+    'engines',
+    'os',
+    'cpu',
+    'man',
+    'directories',
+    'repository',
+    'bugs',
+    'homepage',
+    'readme',
+    'keywords',
+    'scripts',
+    'config',
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'peerDependenciesMeta',
+    'bundleDependencies',
+    'bundledDependencies',
+    'optionalDependencies',
+    'overrides',
+    'publishConfig',
+    'workspaces',
+]);
+
+/**
+ * @param {PackageJson} pkg
+ * @param {(key: string) => boolean} needTreatment
+ * @param {(key: string) => unknown} treatKey
+ * @returns {PackageJson}
+ */
+export function processPackageJson(pkg, needTreatment, treatKey) {
+    /** @type {PackageJson} */
+    const newPkg = {};
+
+    for (const key of packageJsonFieldsOrder) {
+        if (needTreatment(key)) {
+            /** @type {Record<string, unknown>} */ (newPkg)[key] = treatKey(key);
+        }
+    }
+
+    for (const key in pkg) {
+        if (!packageJsonFieldsOrder.has(key)) {
+            /** @type {Record<string, unknown>} */ (newPkg)[key] = /** @type {Record<string, unknown>} */ (pkg)[key];
+        }
+    }
+
+    return newPkg;
+}
+
+/**
+ * @template {object | null | number | string | boolean} T
+ * @param {T} json
+ * @param {string | null} [current] Existing file contents used to detect indentation.
+ * @returns {string}
+ */
+export function toFormattedJson(json, current) {
+    const indent = current?.match(/^[ \t]+(?=\S)/m)?.[0] ?? 2;
+    return `${JSON.stringify(json, null, indent)}\n`;
+}

package/src/options/types.js

@@ -0,0 +1,24 @@
+/**
+ * @typedef {{
+ *   private?: boolean;
+ *   version?: string;
+ *   name?: string;
+ *   bin?: string | Record<string, string>;
+ *   main?: string;
+ *   license?: string;
+ *   readme?: string;
+ *   author?: string | { name?: string; email?: string; url?: string; };
+ *   description?: string;
+ *   scripts?: { [key: string]: string; };
+ *   repository?: { type?: string; url?: string; };
+ *   files?: string[];
+ *   bugs?: string;
+ *   homepage?: string;
+ *   dependencies?: Record<string, string>;
+ *   devDependencies?: Record<string, string>;
+ *   peerDependencies?: Record<string, string>;
+ *   exports?: Record<string, string | Record<string, string>>;
+ * }} PackageJson
+ */
+
+export {};

package/src/package-imports.js

@@ -0,0 +1,240 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { BuildEntryError, sourceFileExtensions } from './build-entries.js';
+
+/**
+ * @typedef {import('./types.js').BuildConfiguration} BuildConfiguration
+ * @typedef {import('./types.js').BuildEntryIssue} BuildEntryIssue
+ * @typedef {import('./types.js').ImportTarget} ImportTarget
+ * @typedef {import('./types.js').BuildFormat} BuildFormat
+ */
+
+const javascriptExtensions = new Set(['.js', '.mjs', '.cjs']);
+
+/**
+ * Find every local JavaScript leaf of an authored package imports map.
+ * Non-JavaScript and package-specifier leaves remain the responsibility of
+ * their runtime resolver or producer.
+ *
+ * @param {unknown} imports
+ * @param {BuildConfiguration} configuration
+ * @param {unknown} packageType
+ * @returns {Promise<ImportTarget[]>}
+ */
+export async function collectPackageImportTargets(imports, configuration, packageType) {
+    if (imports === undefined || !configuration.resolution.imports) return [];
+
+    /** @type {BuildEntryIssue[]} */
+    const issues = [];
+    /** @type {Map<string, ImportTarget>} */
+    const targets = new Map();
+    const leaves = parseImportMap(imports, issues);
+    for (const leaf of leaves) {
+        for (const target of await expandLocalTarget(leaf, configuration, packageType, issues)) {
+            if (!targets.has(target.outputPath)) targets.set(target.outputPath, target);
+        }
+    }
+
+    if (issues.length > 0) throw new BuildEntryError(issues);
+    return [...targets.values()];
+}
+
+/**
+ * Walk the authored map without selecting runtime conditions. Every local
+ * branch may need its own output, while package specifiers remain mappings.
+ * @param {unknown} imports
+ * @param {BuildEntryIssue[]} issues
+ */
+function parseImportMap(imports, issues) {
+    /** @type {{ value: string; issuePath: string; wildcardKey: boolean }[]} */
+    const leaves = [];
+    if (!isRecord(imports)) {
+        issues.push({ code: 'INVALID_IMPORT_MAP', path: 'package.imports', message: 'must be an object' });
+        return leaves;
+    }
+
+    for (const [key, value] of Object.entries(imports)) {
+        const issuePath = `package.imports[${JSON.stringify(key)}]`;
+        const stars = key.match(/\*/g)?.length ?? 0;
+        if (!key.startsWith('#') || key === '#' || key.endsWith('/') || stars > 1) {
+            issues.push({ code: 'INVALID_IMPORT_KEY', path: issuePath, message: `Invalid package import key ${JSON.stringify(key)}` });
+            continue;
+        }
+        visit(value, issuePath, stars > 0);
+    }
+    return leaves;
+
+    /** @param {unknown} value @param {string} issuePath @param {boolean} wildcardKey */
+    function visit(value, issuePath, wildcardKey) {
+        if (value === null) return;
+        if (Array.isArray(value)) {
+            for (const [index, leaf] of value.entries()) visit(leaf, `${issuePath}[${index}]`, wildcardKey);
+            return;
+        }
+        if (isRecord(value)) {
+            for (const [condition, leaf] of Object.entries(value)) {
+                if (isArrayIndex(condition)) {
+                    issues.push({
+                        code: 'INVALID_IMPORT_CONDITION',
+                        path: `${issuePath}.${condition}`,
+                        message: `Integer condition key ${JSON.stringify(condition)} is invalid in a package imports map`,
+                    });
+                } else {
+                    visit(leaf, `${issuePath}.${condition}`, wildcardKey);
+                }
+            }
+            return;
+        }
+        if (typeof value !== 'string') {
+            issues.push({ code: 'INVALID_IMPORT_TARGET', path: issuePath, message: 'must be a string, null, array, or condition object' });
+            return;
+        }
+        if (!value.startsWith('./')) {
+            if (value.startsWith('.') || value.startsWith('/') || value.includes('\\') || value.length === 0 || URL.canParse(value)) {
+                issues.push({
+                    code: 'INVALID_IMPORT_TARGET',
+                    path: issuePath,
+                    message: `Invalid package import target ${JSON.stringify(value)}`,
+                });
+            }
+            return;
+        }
+        leaves.push({ value, issuePath, wildcardKey });
+    }
+}
+
+/** @param {string} key */
+function isArrayIndex(key) {
+    return /^(0|[1-9]\d*)$/.test(key) && Number(key) < 2 ** 32 - 1;
+}
+
+/**
+ * Validate a local URL target, then expand its output pattern against source
+ * names. Final source-extension selection happens in resolveBuildEntries.
+ * @param {{ value: string; issuePath: string; wildcardKey: boolean }} leaf
+ * @param {BuildConfiguration} configuration
+ * @param {unknown} packageType
+ * @param {BuildEntryIssue[]} issues
+ * @returns {Promise<ImportTarget[]>}
+ */
+async function expandLocalTarget({ value, issuePath, wildcardKey }, configuration, packageType, issues) {
+    const pathPart = value.split(/[?#]/, 1)[0];
+    const rawSegments = pathPart.slice(2).split('/');
+    let outputPath;
+    try {
+        if (
+            pathPart.includes('\\') ||
+            rawSegments.some(segment => {
+                const decoded = decodeURIComponent(segment);
+                return (
+                    decoded === '' ||
+                    decoded === '.' ||
+                    decoded === '..' ||
+                    decoded.toLowerCase() === 'node_modules' ||
+                    decoded.includes('/') ||
+                    decoded.includes('\\')
+                );
+            })
+        ) {
+            throw new Error('invalid path segment');
+        }
+        outputPath = fileURLToPath(new URL(value, pathToFileURL(path.join(process.cwd(), 'package.json'))));
+    } catch {
+        issues.push({
+            code: 'INVALID_IMPORT_TARGET',
+            path: issuePath,
+            message: `Invalid local package import target ${JSON.stringify(value)}`,
+        });
+        return [];
+    }
+
+    const extension = path.extname(outputPath);
+    if (!javascriptExtensions.has(extension)) return [];
+
+    const outputDir = path.resolve(configuration.paths.outputDir);
+    if (!outputPath.startsWith(`${outputDir}${path.sep}`) || (pathPart.includes('*') && !wildcardKey)) {
+        issues.push({
+            code: 'INVALID_IMPORT_TARGET',
+            path: issuePath,
+            message: `Local JavaScript target ${JSON.stringify(value)} must be a safe path beneath ${configuration.paths.outputDir}`,
+        });
+        return [];
+    }
+
+    const format = /** @type {BuildFormat} */ (
+        extension === '.mjs' ? 'es' : extension === '.cjs' ? 'cjs' : packageType === 'module' ? 'es' : 'cjs'
+    );
+    if (!configuration.outputs.formats.includes(format)) {
+        issues.push({
+            code: 'EXCLUDED_IMPORT_FORMAT',
+            path: issuePath,
+            message: `Local target ${JSON.stringify(value)} requires ${format}, which is excluded by outputs.formats`,
+        });
+        return [];
+    }
+
+    const relativeOutput = path.relative(outputDir, outputPath).replaceAll('\\', '/');
+    const sourceName = relativeOutput.slice(0, -extension.length);
+    if (pathPart.includes('*')) {
+        const sourceNames = await findMatchingSourceNames(configuration.paths.sourceDir, sourceName);
+        if (sourceNames.length === 0) {
+            issues.push({
+                code: 'SOURCE_NOT_FOUND',
+                path: issuePath,
+                message: `Import target ${JSON.stringify(value)} has no supported source file`,
+            });
+        }
+        return sourceNames.map(matchedName => ({
+            sourceName: matchedName,
+            outputPath: `./${configuration.paths.outputDir}/${matchedName}${extension}`,
+            format,
+            issuePath,
+        }));
+    }
+    return [{ sourceName, outputPath: `./${configuration.paths.outputDir}/${relativeOutput}`, format, issuePath }];
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** @param {string} sourceDir @param {string} pattern */
+async function findMatchingSourceNames(sourceDir, pattern) {
+    const parts = pattern.split('*').map(part => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    const matcher = new RegExp(
+        `^${parts[0]}(.+?)${parts[1]}${parts
+            .slice(2)
+            .map(part => `\\1${part}`)
+            .join('')}$`
+    );
+    /** @type {Set<string>} */
+    const names = new Set();
+    await walk(sourceDir, '');
+    return [...names].sort();
+
+    /** @param {string} directory @param {string} relative */
+    async function walk(directory, relative) {
+        let entries;
+        try {
+            entries = await fs.readdir(directory, { withFileTypes: true });
+        } catch (error) {
+            if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT') return;
+            throw error;
+        }
+        for (const entry of entries) {
+            const nextRelative = relative ? `${relative}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await walk(path.join(directory, entry.name), nextRelative);
+            } else if (entry.isFile()) {
+                const extension = path.posix.extname(nextRelative).slice(1);
+                if (sourceFileExtensions.includes(/** @type {typeof sourceFileExtensions[number]} */ (extension))) {
+                    const name = nextRelative.slice(0, -(extension.length + 1));
+                    if (matcher.test(name)) names.add(name);
+                }
+            }
+        }
+    }
+}

package/src/plugin-name.js

@@ -0,0 +1,6 @@
+const PLUGIN_PACKAGE_RE = /^(?:@[^/]+\/)?pkgbld-plugin-/;
+
+/** @param {string} packageName */
+export function isPluginPackageName(packageName) {
+    return PLUGIN_PACKAGE_RE.test(packageName);
+}

package/src/priorities.js

@@ -0,0 +1,11 @@
+export const Priority = /** @type {const} */ ({
+    preprocess: 1000,
+    cleanup: 1000,
+    packageImports: 1500,
+    externals: 2000,
+    resolve: 3000,
+    commonjs: 4000,
+    transpile: 6000,
+    compress: 10000,
+    finalize: 20000,
+});