@sboudrias/package 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2025 Simon Boudrias
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @sboudrias/package
+
+Package metadata tools for JavaScript packages and monorepos.
+
+# Installation
+
+<table>
+<tr>
+  <th>npm</th>
+  <th>yarn</th>
+  <th>pnpm</th>
+  <th>bun</th>
+</tr>
+<tr>
+<td>
+
+```sh
+npm install @sboudrias/package --save-dev
+```
+
+</td>
+<td>
+
+```sh
+yarn add @sboudrias/package --dev
+```
+
+</td>
+<td>
+
+```sh
+pnpm add @sboudrias/package --save-dev
+```
+
+</td>
+<td>
+
+```sh
+bun add @sboudrias/package --dev
+```
+
+</td>
+</tr>
+</table>
+
+# Usage
+
+```bash
+package lint
+```
+
+`package lint` validates public workspace packages and fixes safe package metadata issues in place.
+
+```bash
+package lint --check
+```
+
+`package lint --check` runs the same validation without writing files. It exits non-zero when any package needs a fix or has a manual conflict.
+
+# Lint Rules
+
+## Valid Peer Dependencies
+
+Runtime dependencies can declare their own peer dependencies. `package lint` makes those peer requirements visible on the package that uses the runtime dependency.
+
+It adds missing peers to `peerDependencies` and copies matching `peerDependenciesMeta` entries so optional peers stay optional.
+
+## Matching engines
+
+Packages should only advertise Node.js support that their runtime dependencies can also support.
+
+`package lint` sets missing, invalid, or out-of-root-range `engines.node` values to the root package `engines.node` range. It fails when a runtime dependency supports a narrower Node.js range than the package.
+
+That failure is intentional. Bumping a dependency can raise the minimum supported Node.js version and break dependants that still install the package under the previous `engines.node` range. In that case, manually narrow the package engine range or choose a compatible dependency version.
+
+## Ensure package.json is exposed
+
+Packages should expose their manifest for tools that inspect package metadata at runtime.
+
+`package lint` ensures public packages expose `"./package.json": "./package.json"` in `exports`.
+
+# Workspace Discovery
+
+The CLI discovers workspaces from `package.json` `workspaces` fields and `pnpm-workspace.yaml` files.
+
+If no workspaces are configured, the root `package.json` is linted as a single-package project.
+
+Private packages are ignored by default.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { type BaseContext } from 'clipanion';
+export declare function main(argv?: string[], context?: Partial<BaseContext>): Promise<number>;

package/dist/bin.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Builtins, Cli, Command, Option } from 'clipanion';
+import { lintPackages } from "./lint.js";
+class LintCommand extends Command {
+    static paths = [['lint']];
+    static usage = Command.Usage({
+        description: 'Validate and fix package metadata.',
+        examples: [
+            ['Fix package metadata', '$0 lint'],
+            ['Validate package metadata without writing files', '$0 lint --check'],
+        ],
+    });
+    check = Option.Boolean('--check', false, {
+        description: 'Validate package metadata without writing files.',
+    });
+    async execute() {
+        try {
+            const result = await lintPackages({ check: this.check });
+            for (const issue of result.issues) {
+                this.context.stderr.write(`[${issue.status}] ${issue.message} (${issue.packagePath})\n`);
+            }
+            return result.hasFailures ? 1 : 0;
+        }
+        catch (error) {
+            this.context.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+    }
+}
+const cli = Cli.from([LintCommand, Builtins.HelpCommand], {
+    binaryLabel: 'Package',
+    binaryName: 'package',
+    enableCapture: false,
+});
+export async function main(argv = process.argv.slice(2), context = {}) {
+    return cli.run(argv, {
+        ...Cli.defaultContext,
+        ...context,
+    });
+}
+if (process.argv[1] != null &&
+    path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    process.exitCode = await main();
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { lintPackages } from './lint.ts';

package/dist/index.js

@@ -0,0 +1 @@
+export { lintPackages } from "./lint.js";

package/dist/lint.d.ts

@@ -0,0 +1,11 @@
+export declare function lintPackages(options?: {
+    cwd?: string;
+    check?: boolean;
+}): Promise<{
+    issues: {
+        packagePath: string;
+        message: string;
+        status: "error" | "fixed" | "would fix";
+    }[];
+    hasFailures: boolean;
+}>;

package/dist/lint.js

@@ -0,0 +1,120 @@
+import path from 'node:path';
+import { subset, validRange } from 'semver';
+import { applyPeerDependencyHoists, getPeerDependencyHoists, } from "./peer-dependencies.js";
+import { resolveDependencyPackageJson, writePackageJsonFile } from "./package-json.js";
+import { readWorkspaceProject } from "./workspaces.js";
+function nodeEngine(pkg) {
+    const node = pkg.engines?.['node'];
+    return typeof node === 'string' ? node : undefined;
+}
+export async function lintPackages(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const check = options.check ?? false;
+    const { rootPackageJson, packages } = await readWorkspaceProject(cwd);
+    const rootNodeRange = nodeEngine(rootPackageJson);
+    if (rootNodeRange == null || validRange(rootNodeRange) == null) {
+        throw new Error('The root package.json must define a valid engines.node range.');
+    }
+    const publicPackages = packages.filter(({ packageJson }) => packageJson.private !== true);
+    const packagesByName = new Map(packages.flatMap(({ packageJson }) => packageJson.name == null ? [] : [[packageJson.name, packageJson]]));
+    const resolvePackageJson = (dependencyName, packageDir) => packagesByName.get(dependencyName) ??
+        resolveDependencyPackageJson(dependencyName, packageDir);
+    const originalPackages = new Map(publicPackages.map(({ packageJson, packagePath }) => [
+        packagePath,
+        JSON.stringify(packageJson),
+    ]));
+    const issues = [];
+    const report = (packagePath, message, fixable) => {
+        issues.push({
+            packagePath,
+            message,
+            status: fixable ? (check ? 'would fix' : 'fixed') : 'error',
+        });
+    };
+    for (const { packageDir, packageJson, packagePath } of publicPackages) {
+        const name = packageJson.name ?? packagePath;
+        const { hoists } = getPeerDependencyHoists(packageJson, packageDir, resolvePackageJson);
+        for (const hoist of hoists) {
+            report(packagePath, hoist.kind === 'peer-dependency'
+                ? `${name} must hoist ${hoist.peerName} from ${hoist.dependencyName}.`
+                : `${name} must copy peer dependency metadata for ${hoist.peerName} from ${hoist.dependencyName}.`, true);
+        }
+        if (!check)
+            applyPeerDependencyHoists(packageJson, hoists);
+        let packageRange = nodeEngine(packageJson);
+        if (packageRange == null ||
+            validRange(packageRange) == null ||
+            !subset(packageRange, rootNodeRange)) {
+            report(packagePath, `${name} must define an engines.node range within the root range "${rootNodeRange}".`, true);
+            if (check) {
+                packageRange = undefined;
+            }
+            else {
+                packageJson.engines ??= {};
+                packageJson.engines['node'] = rootNodeRange;
+                packageRange = rootNodeRange;
+            }
+        }
+        if (packageRange != null) {
+            for (const dependencyName of new Set([
+                ...Object.keys(packageJson.dependencies ?? {}),
+                ...Object.keys(packageJson.optionalDependencies ?? {}),
+            ])) {
+                const dependencyPackage = resolvePackageJson(dependencyName, packageDir);
+                if (dependencyPackage == null) {
+                    report(packagePath, `${name} depends on ${dependencyName}, but its package.json could not be resolved.`, false);
+                    continue;
+                }
+                const dependencyRange = nodeEngine(dependencyPackage);
+                if (dependencyRange == null)
+                    continue;
+                if (validRange(dependencyRange) == null) {
+                    report(packagePath, `${name} depends on ${dependencyName}, which has an invalid engines.node range: ${dependencyRange}`, false);
+                }
+                else if (!subset(packageRange, dependencyRange)) {
+                    report(packagePath, `${name} supports node "${packageRange}", but ${dependencyName} supports "${dependencyRange}".`, false);
+                }
+            }
+        }
+        const currentExports = packageJson.exports;
+        const currentExportsObject = currentExports != null &&
+            typeof currentExports === 'object' &&
+            !Array.isArray(currentExports)
+            ? currentExports
+            : undefined;
+        if (currentExportsObject != null &&
+            Reflect.get(currentExportsObject, './package.json') === './package.json') {
+            continue;
+        }
+        if (currentExports == null ||
+            typeof currentExports === 'string' ||
+            currentExportsObject != null) {
+            report(packagePath, `${name} must export ./package.json.`, true);
+            if (!check) {
+                if (currentExports == null) {
+                    packageJson.exports = { './package.json': './package.json' };
+                }
+                else if (typeof currentExports === 'string') {
+                    packageJson.exports = {
+                        '.': currentExports,
+                        './package.json': './package.json',
+                    };
+                }
+                else if (currentExportsObject != null) {
+                    Reflect.set(currentExportsObject, './package.json', './package.json');
+                }
+            }
+        }
+        else {
+            report(packagePath, `${name} uses an unsupported exports shape; add ./package.json manually.`, false);
+        }
+    }
+    const changedPackages = publicPackages.filter(({ packageJson, packagePath }) => JSON.stringify(packageJson) !== originalPackages.get(packagePath));
+    if (!check) {
+        await Promise.all(changedPackages.map(({ packageJson, packagePath }) => writePackageJsonFile(path.join(cwd, packagePath), packageJson)));
+    }
+    return {
+        issues,
+        hasFailures: issues.some((issue) => issue.status !== 'fixed'),
+    };
+}

package/dist/package-json.d.ts

@@ -0,0 +1,4 @@
+import type { PackageJson } from 'type-fest';
+export declare function readPackageJsonFile(filepath: string): PackageJson;
+export declare function writePackageJsonFile(filepath: string, packageJson: PackageJson): Promise<void>;
+export declare function resolveDependencyPackageJson(name: string, fromDirectory?: string): PackageJson | undefined;

package/dist/package-json.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import fsPromises from 'node:fs/promises';
+import Module from 'node:module';
+import path from 'node:path';
+import { parse as parseJsonc } from 'jsonc-parser';
+function asPackageJson(value, source) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError(`Expected ${source} to contain a package.json object`);
+    }
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    return value;
+}
+function errorCode(error) {
+    return error && typeof error === 'object' && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+function createRequireFrom(fromDirectory) {
+    return Module.createRequire(path.join(fromDirectory, 'package.json'));
+}
+function findPackageJson(fromDirectory) {
+    let directory = fromDirectory;
+    for (;;) {
+        const packageJsonPath = path.join(directory, 'package.json');
+        if (fs.existsSync(packageJsonPath)) {
+            return packageJsonPath;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            return undefined;
+        }
+        directory = parent;
+    }
+}
+function findNodeModulesPackageJson(name, fromDirectory) {
+    let directory = fromDirectory;
+    for (;;) {
+        const packageJsonPath = path.join(directory, 'node_modules', name, 'package.json');
+        if (fs.existsSync(packageJsonPath)) {
+            return packageJsonPath;
+        }
+        const parent = path.dirname(directory);
+        if (parent === directory) {
+            return undefined;
+        }
+        directory = parent;
+    }
+}
+export function readPackageJsonFile(filepath) {
+    return asPackageJson(parseJsonc(fs.readFileSync(filepath, 'utf8')), filepath);
+}
+export async function writePackageJsonFile(filepath, packageJson) {
+    await fsPromises.writeFile(filepath, JSON.stringify(packageJson, null, 2) + '\n');
+}
+export function resolveDependencyPackageJson(name, fromDirectory = process.cwd()) {
+    const requireFromDirectory = createRequireFrom(fromDirectory);
+    try {
+        const packageJson = requireFromDirectory(`${name}/package.json`);
+        return asPackageJson(packageJson, `${name}/package.json`);
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED' && code !== 'MODULE_NOT_FOUND') {
+            throw error;
+        }
+    }
+    try {
+        const entrypoint = requireFromDirectory.resolve(name);
+        const entrypointPackageJsonPath = findPackageJson(path.dirname(entrypoint));
+        if (entrypointPackageJsonPath != null) {
+            return readPackageJsonFile(entrypointPackageJsonPath);
+        }
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED' && code !== 'MODULE_NOT_FOUND') {
+            throw error;
+        }
+    }
+    const packageJsonPath = findNodeModulesPackageJson(name, fromDirectory);
+    if (packageJsonPath != null) {
+        return readPackageJsonFile(packageJsonPath);
+    }
+    return undefined;
+}

package/dist/peer-dependencies.d.ts

@@ -0,0 +1,20 @@
+import type { PackageJson } from 'type-fest';
+export type ResolvePackageJson = (dependencyName: string, fromDirectory: string) => PackageJson | undefined;
+export type PeerDependencyHoist = {
+    kind: 'peer-dependency';
+    dependencyName: string;
+    peerName: string;
+    peerVersion: string;
+} | {
+    kind: 'peer-dependency-meta';
+    dependencyName: string;
+    peerName: string;
+    peerMeta: NonNullable<PackageJson['peerDependenciesMeta']>[string];
+};
+export type PeerDependencyHoistResult = {
+    hoists: PeerDependencyHoist[];
+    missingDependencies: string[];
+};
+export declare function getPeerDependencyHoists(pkg: PackageJson, packageDir: string, resolvePackageJson?: ResolvePackageJson): PeerDependencyHoistResult;
+export declare function applyPeerDependencyHoists(pkg: PackageJson, hoists: PeerDependencyHoist[]): void;
+export declare function hoistPeerDependencies(pkg: PackageJson, packageDir: string, resolvePackageJson?: ResolvePackageJson): boolean;

package/dist/peer-dependencies.js

@@ -0,0 +1,66 @@
+import { resolveDependencyPackageJson } from "./package-json.js";
+function runtimeDependencyNames(pkg) {
+    return new Set([
+        ...Object.keys(pkg.dependencies ?? {}),
+        ...Object.keys(pkg.optionalDependencies ?? {}),
+    ]);
+}
+function hasRuntimeDependency(pkg, dependencyName) {
+    return (pkg.dependencies?.[dependencyName] != null ||
+        pkg.optionalDependencies?.[dependencyName] != null);
+}
+export function getPeerDependencyHoists(pkg, packageDir, resolvePackageJson = resolveDependencyPackageJson) {
+    const hoists = [];
+    const missingDependencies = [];
+    for (const dependencyName of runtimeDependencyNames(pkg)) {
+        const dependencyPackage = resolvePackageJson(dependencyName, packageDir);
+        if (dependencyPackage == null) {
+            missingDependencies.push(dependencyName);
+            continue;
+        }
+        for (const peerName of Object.keys(dependencyPackage.peerDependencies ?? {})) {
+            const peerVersion = dependencyPackage.peerDependencies?.[peerName];
+            if (typeof peerVersion !== 'string')
+                continue;
+            let packageShouldHavePeer = !hasRuntimeDependency(pkg, peerName) && pkg.peerDependencies?.[peerName] == null;
+            if (packageShouldHavePeer) {
+                hoists.push({
+                    kind: 'peer-dependency',
+                    dependencyName,
+                    peerName,
+                    peerVersion,
+                });
+            }
+            packageShouldHavePeer ||= pkg.peerDependencies?.[peerName] != null;
+            const peerMeta = dependencyPackage.peerDependenciesMeta?.[peerName];
+            if (packageShouldHavePeer &&
+                peerMeta != null &&
+                pkg.peerDependenciesMeta?.[peerName] == null) {
+                hoists.push({
+                    kind: 'peer-dependency-meta',
+                    dependencyName,
+                    peerName,
+                    peerMeta,
+                });
+            }
+        }
+    }
+    return { hoists, missingDependencies };
+}
+export function applyPeerDependencyHoists(pkg, hoists) {
+    for (const hoist of hoists) {
+        if (hoist.kind === 'peer-dependency') {
+            pkg.peerDependencies ??= {};
+            pkg.peerDependencies[hoist.peerName] = hoist.peerVersion;
+        }
+        else {
+            pkg.peerDependenciesMeta ??= {};
+            pkg.peerDependenciesMeta[hoist.peerName] = hoist.peerMeta;
+        }
+    }
+}
+export function hoistPeerDependencies(pkg, packageDir, resolvePackageJson) {
+    const { hoists } = getPeerDependencyHoists(pkg, packageDir, resolvePackageJson);
+    applyPeerDependencyHoists(pkg, hoists);
+    return hoists.length > 0;
+}

package/dist/workspaces.d.ts

@@ -0,0 +1,12 @@
+import type { PackageJson } from 'type-fest';
+export type WorkspacePackage = {
+    packageJson: PackageJson;
+    packagePath: string;
+    packageDir: string;
+};
+export type WorkspaceProject = {
+    rootPackageJson: PackageJson;
+    rootPackagePath: string;
+    packages: WorkspacePackage[];
+};
+export declare function readWorkspaceProject(cwd?: string): Promise<WorkspaceProject>;

package/dist/workspaces.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { globby } from 'globby';
+import { parse as parseYaml } from 'yaml';
+import { readPackageJsonFile } from "./package-json.js";
+function errorCode(error) {
+    return error && typeof error === 'object' && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+function workspacePackagePattern(pattern) {
+    const isNegated = pattern.startsWith('!');
+    const workspacePattern = isNegated ? pattern.slice(1) : pattern;
+    const packageJsonPattern = workspacePattern.endsWith('/package.json')
+        ? workspacePattern
+        : `${workspacePattern.replace(/\/$/, '')}/package.json`;
+    return isNegated ? `!${packageJsonPattern}` : packageJsonPattern;
+}
+function packageJsonWorkspacePatterns(rootPackageJson) {
+    const workspaces = rootPackageJson.workspaces;
+    if (Array.isArray(workspaces)) {
+        return workspaces.filter((workspace) => typeof workspace === 'string');
+    }
+    if (workspaces != null && typeof workspaces === 'object') {
+        const packages = 'packages' in workspaces ? workspaces.packages : undefined;
+        if (Array.isArray(packages)) {
+            return packages.filter((workspace) => typeof workspace === 'string');
+        }
+    }
+    return [];
+}
+function pnpmWorkspacePatternsFrom(value) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+        return [];
+    }
+    const packages = 'packages' in value ? value.packages : undefined;
+    if (!Array.isArray(packages)) {
+        return [];
+    }
+    return packages.filter((workspace) => typeof workspace === 'string');
+}
+async function readPnpmWorkspacePatterns(cwd) {
+    for (const filename of ['pnpm-workspace.yaml', 'pnpm-workspace.yml']) {
+        try {
+            const content = await fs.readFile(path.join(cwd, filename), 'utf8');
+            return pnpmWorkspacePatternsFrom(parseYaml(content));
+        }
+        catch (error) {
+            if (errorCode(error) !== 'ENOENT') {
+                throw error;
+            }
+        }
+    }
+    return [];
+}
+export async function readWorkspaceProject(cwd = process.cwd()) {
+    const rootPackagePath = path.join(cwd, 'package.json');
+    const rootPackageJson = readPackageJsonFile(rootPackagePath);
+    const workspacePatterns = [
+        ...packageJsonWorkspacePatterns(rootPackageJson),
+        ...(await readPnpmWorkspacePatterns(cwd)),
+    ];
+    if (workspacePatterns.length === 0) {
+        return {
+            rootPackageJson,
+            rootPackagePath,
+            packages: [
+                {
+                    packageJson: rootPackageJson,
+                    packagePath: 'package.json',
+                    packageDir: cwd,
+                },
+            ],
+        };
+    }
+    const packagePaths = await globby([...new Set(workspacePatterns.map(workspacePackagePattern)), '!**/node_modules'], { cwd });
+    const packages = packagePaths.toSorted().map((packagePath) => {
+        const absolutePackagePath = path.join(cwd, packagePath);
+        return {
+            packageJson: readPackageJsonFile(absolutePackagePath),
+            packagePath,
+            packageDir: path.dirname(absolutePackagePath),
+        };
+    });
+    return { rootPackageJson, rootPackagePath, packages };
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@sboudrias/package",
+  "version": "1.0.0",
+  "keywords": [
+    "cli",
+    "lint",
+    "monorepo",
+    "node",
+    "npm",
+    "package-json",
+    "pnpm",
+    "workspace",
+    "yarn"
+  ],
+  "homepage": "https://github.com/SBoudrias/Inquirer.js/blob/main/tools/package/README.md",
+  "license": "MIT",
+  "author": "Simon Boudrias <admin@simonboudrias.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SBoudrias/Inquirer.js.git"
+  },
+  "bin": "./dist/bin.js",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "tsc": "tsc && chmod +x ./dist/bin.js"
+  },
+  "dependencies": {
+    "clipanion": "^4.0.0-rc.4",
+    "globby": "^16.2.0",
+    "jsonc-parser": "^3.3.1",
+    "semver": "^7.7.4",
+    "typanion": "^3.14.0",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@repo/tsconfig": "workspace:*",
+    "@types/node": "^25.5.2",
+    "@types/semver": "^7.7.1",
+    "type-fest": "^5.5.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=23.5.0 || ^22.13.0 || ^20.17.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "gitHead": "bfd8710229e3d3c9784bef3bbfbd84c7bd09bb9e"
+}