@sboudrias/package 1.0.2 → 1.0.3

package/README.md

@@ -43,7 +43,17 @@ bun add @sboudrias/package --dev
 </tr>
 </table>
 
-# Usage
+# Commands
+
+| Command                                               | Description                                                   |
+| ----------------------------------------------------- | ------------------------------------------------------------- |
+| [`package lint`](#package-lint)                       | Validate and fix package metadata.                            |
+| [`package normalize`](#package-normalize)             | Fix workspace manifests so they are valid for npm publishing. |
+| [`package pin <dependency>`](#package-pin-dependency) | Pin exact versions of a workspace dependency.                 |
+
+All commands operate on public workspace packages (see [Workspace Discovery](#workspace-discovery)) and write manifests in place.
+
+## package lint
 
 ```bash
 package lint
@@ -57,15 +67,13 @@ 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
+### 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
+### Matching engines
 
 Packages should only advertise Node.js support that their runtime dependencies can also support.
 
@@ -73,16 +81,40 @@ Packages should only advertise Node.js support that their runtime dependencies c
 
 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
+### 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`.
 
+## package normalize
+
+```bash
+package normalize
+```
+
+`package normalize` applies every manifest fixup required to make public workspace packages valid for npm publishing, in place.
+
+Currently it removes dev dependencies declared with the `workspace:*` protocol: those specs only resolve inside the workspace and are invalid once the package is published, so they must be stripped from the manifest before it is packed. Dev dependencies with other specs are left untouched.
+
+As new npm-validity issues are identified, their fixups join this command instead of the calling pipeline. The Inquirer.js release pipeline runs it at `prepack` time, right before packing the tarballs.
+
+## package pin <dependency>
+
+```bash
+package pin <dependency>
+```
+
+`package pin <dependency>` rewrites semver ranges (`^1.2.3`, `~1.2.3`) of the given dependency to exact versions (`1.2.3`) across all public workspace packages, in place.
+
+Exact specs, `workspace:` protocols, and dev dependencies are left untouched. It exits non-zero when a range cannot be resolved to a single exact version (e.g. `>=1.0.0`, `1.x`); such ranges must be fixed manually.
+
+The Inquirer.js release pipeline uses this at `prepack` time to pin `@inquirer/type` exactly in published manifests: type-only dependencies leak into consumers' `.d.ts` compilation, so an uncontrolled range can break downstream TypeScript builds even when the runtime behavior is unchanged.
+
 # 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.
+If no workspaces are configured, the root `package.json` is treated as a single-package project.
 
 Private packages are ignored by default.

package/dist/bin.js

@@ -1,33 +1,9 @@
 #!/usr/bin/env node
-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], {
+import { Builtins, Cli } from 'clipanion';
+import { LintCommand } from "./lint/command.js";
+import { NormalizeCommand } from "./normalize/command.js";
+import { PinCommand } from "./pin/command.js";
+const cli = Cli.from([LintCommand, NormalizeCommand, PinCommand, Builtins.HelpCommand], {
     binaryLabel: 'Package',
     binaryName: 'package',
     enableCapture: false,

package/dist/index.d.ts

@@ -1 +1,3 @@
-export { lintPackages } from './lint.ts';
+export { lintPackages } from './lint/index.ts';
+export { normalizeManifests } from './normalize/index.ts';
+export { pinDependencies } from './pin/index.ts';

package/dist/index.js

@@ -1 +1,3 @@
-export { lintPackages } from "./lint.js";
+export { lintPackages } from "./lint/index.js";
+export { normalizeManifests } from "./normalize/index.js";
+export { pinDependencies } from "./pin/index.js";

package/dist/lint/command.d.ts

@@ -0,0 +1,7 @@
+import { Command } from 'clipanion';
+export declare class LintCommand extends Command {
+    static paths: string[][];
+    static usage: import("clipanion").Usage;
+    check: boolean;
+    execute(): Promise<0 | 1>;
+}

package/dist/lint/command.js

@@ -0,0 +1,28 @@
+import { Command, Option } from 'clipanion';
+import { lintPackages } from "./index.js";
+export 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;
+        }
+    }
+}

package/dist/{lint.js → lint/index.js}

@@ -1,8 +1,8 @@
 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";
+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;

package/dist/normalize/command.d.ts

@@ -0,0 +1,6 @@
+import { Command } from 'clipanion';
+export declare class NormalizeCommand extends Command {
+    static paths: string[][];
+    static usage: import("clipanion").Usage;
+    execute(): Promise<0 | 1>;
+}

package/dist/normalize/command.js

@@ -0,0 +1,22 @@
+import { Command } from 'clipanion';
+import { normalizeManifests } from "./index.js";
+export class NormalizeCommand extends Command {
+    static paths = [['normalize']];
+    static usage = Command.Usage({
+        description: 'Fix workspace manifests so they are valid for npm publishing.',
+        examples: [['Fix manifests before packing tarballs', '$0 normalize']],
+    });
+    async execute() {
+        try {
+            const fixups = await normalizeManifests();
+            for (const fixup of fixups) {
+                this.context.stdout.write(`[fixed] ${fixup.name}: removed workspace dev dependency ${fixup.dependencyName}.\n`);
+            }
+            return 0;
+        }
+        catch (error) {
+            this.context.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+    }
+}

package/dist/normalize/index.d.ts

@@ -0,0 +1,13 @@
+export type ManifestFixup = {
+    kind: 'remove-workspace-dev-dependency';
+    packagePath: string;
+    name: string;
+    dependencyName: string;
+};
+/**
+ * Applies every manifest fixup required to make public workspace packages
+ * valid for npm publishing. Run before packing tarballs.
+ */
+export declare function normalizeManifests(options?: {
+    cwd?: string;
+}): Promise<ManifestFixup[]>;

package/dist/normalize/index.js

@@ -0,0 +1,48 @@
+import path from 'node:path';
+import { writePackageJsonFile } from "../package-json.js";
+import { readWorkspaceProject } from "../workspaces.js";
+/**
+ * Removes dev dependencies declared with the `workspace:*` protocol. Those
+ * specs only resolve inside the workspace and are invalid once the package is
+ * published, so they must be stripped from the manifest before it is packed
+ * into the tarball. Dev dependencies with other specs are left untouched.
+ */
+function fixWorkspaceDevDependencies(pkg) {
+    const { packageJson, packagePath } = pkg;
+    if (packageJson.private === true)
+        return [];
+    const name = packageJson.name ?? packagePath;
+    const devDependencies = packageJson.devDependencies;
+    if (devDependencies == null)
+        return [];
+    const entries = Object.entries(devDependencies);
+    const kept = entries.filter(([, spec]) => spec !== 'workspace:*');
+    if (kept.length === entries.length)
+        return [];
+    packageJson.devDependencies = Object.fromEntries(kept);
+    return entries.flatMap(([dependencyName, spec]) => spec === 'workspace:*'
+        ? [
+            {
+                kind: 'remove-workspace-dev-dependency',
+                packagePath,
+                name,
+                dependencyName,
+            },
+        ]
+        : []);
+}
+const FIXUPS = [fixWorkspaceDevDependencies];
+/**
+ * Applies every manifest fixup required to make public workspace packages
+ * valid for npm publishing. Run before packing tarballs.
+ */
+export async function normalizeManifests(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const { packages } = await readWorkspaceProject(cwd);
+    const fixups = packages.flatMap((pkg) => FIXUPS.flatMap((fixup) => fixup(pkg)));
+    const changedPackagePaths = new Set(fixups.map((fixup) => fixup.packagePath));
+    await Promise.all(packages
+        .filter(({ packagePath }) => changedPackagePaths.has(packagePath))
+        .map(({ packageJson, packagePath }) => writePackageJsonFile(path.join(cwd, packagePath), packageJson)));
+    return fixups;
+}

package/dist/pin/command.d.ts

@@ -0,0 +1,7 @@
+import { Command } from 'clipanion';
+export declare class PinCommand extends Command {
+    static paths: string[][];
+    static usage: import("clipanion").Usage;
+    dependencyName: string;
+    execute(): Promise<0 | 1>;
+}

package/dist/pin/command.js

@@ -0,0 +1,28 @@
+import { Command, Option } from 'clipanion';
+import { pinDependencies } from "./index.js";
+export class PinCommand extends Command {
+    static paths = [['pin']];
+    static usage = Command.Usage({
+        description: 'Pin exact versions of workspace dependencies.',
+        examples: [['Pin a dependency across all public packages', '$0 pin @inquirer/type']],
+    });
+    dependencyName = Option.String({ required: true });
+    async execute() {
+        try {
+            const result = await pinDependencies({
+                dependencyNames: [this.dependencyName],
+            });
+            for (const pin of result.pinned) {
+                this.context.stdout.write(`[fixed] ${pin.name}: pinned ${pin.dependencyName} from "${pin.range}" to "${pin.exact}".\n`);
+            }
+            for (const unpinnable of result.unpinnable) {
+                this.context.stderr.write(`[error] ${unpinnable.name} declares ${unpinnable.dependencyName} with an unsupported range "${unpinnable.range}" (${unpinnable.packagePath})\n`);
+            }
+            return result.unpinnable.length > 0 ? 1 : 0;
+        }
+        catch (error) {
+            this.context.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
+    }
+}

package/dist/pin/index.d.ts

@@ -0,0 +1,29 @@
+export type PinnedDependency = {
+    packagePath: string;
+    name: string;
+    dependencyName: string;
+    range: string;
+    exact: string;
+};
+export type UnpinnableDependency = {
+    packagePath: string;
+    name: string;
+    dependencyName: string;
+    range: string;
+};
+export type PinDependenciesResult = {
+    pinned: PinnedDependency[];
+    unpinnable: UnpinnableDependency[];
+};
+/**
+ * Rewrites semver ranges (`^1.2.3`, `~1.2.3`) of the given dependencies to
+ * exact versions (`1.2.3`) across all public workspace packages.
+ *
+ * Exact specs and `workspace:` protocols are left untouched. Ranges that
+ * cannot be resolved to a single exact version (e.g. `>=1.0.0`, `1.x`) are
+ * reported as unpinnable and must be fixed manually.
+ */
+export declare function pinDependencies(options: {
+    cwd?: string;
+    dependencyNames: string[];
+}): Promise<PinDependenciesResult>;

package/dist/pin/index.js

@@ -0,0 +1,54 @@
+import path from 'node:path';
+import { valid as validVersion } from 'semver';
+import { writePackageJsonFile } from "../package-json.js";
+import { readWorkspaceProject } from "../workspaces.js";
+const DEPENDENCY_FIELDS = ['dependencies', 'optionalDependencies'];
+/**
+ * Rewrites semver ranges (`^1.2.3`, `~1.2.3`) of the given dependencies to
+ * exact versions (`1.2.3`) across all public workspace packages.
+ *
+ * Exact specs and `workspace:` protocols are left untouched. Ranges that
+ * cannot be resolved to a single exact version (e.g. `>=1.0.0`, `1.x`) are
+ * reported as unpinnable and must be fixed manually.
+ */
+export async function pinDependencies(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const dependencyNames = [...new Set(options.dependencyNames)];
+    const { packages } = await readWorkspaceProject(cwd);
+    const pinned = [];
+    const unpinnable = [];
+    for (const { packageJson, packagePath } of packages) {
+        if (packageJson.private === true)
+            continue;
+        const name = packageJson.name ?? packagePath;
+        for (const field of DEPENDENCY_FIELDS) {
+            const dependencies = packageJson[field];
+            if (dependencies == null)
+                continue;
+            for (const dependencyName of dependencyNames) {
+                const range = dependencies[dependencyName];
+                if (typeof range !== 'string' || range.startsWith('workspace:')) {
+                    continue;
+                }
+                if (!/^[~^]/.test(range)) {
+                    if (validVersion(range) == null) {
+                        unpinnable.push({ packagePath, name, dependencyName, range });
+                    }
+                    continue;
+                }
+                const exact = range.slice(1);
+                if (validVersion(exact) == null) {
+                    unpinnable.push({ packagePath, name, dependencyName, range });
+                    continue;
+                }
+                dependencies[dependencyName] = exact;
+                pinned.push({ packagePath, name, dependencyName, range, exact });
+            }
+        }
+    }
+    const changedPackagePaths = new Set(pinned.map((pin) => pin.packagePath));
+    await Promise.all(packages
+        .filter(({ packagePath }) => changedPackagePaths.has(packagePath))
+        .map(({ packageJson, packagePath }) => writePackageJsonFile(path.join(cwd, packagePath), packageJson)));
+    return { pinned, unpinnable };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sboudrias/package",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "keywords": [
     "cli",
     "lint",
@@ -59,5 +59,5 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "gitHead": "2073546b459fd91d71f4f778ddf7b4c5417bb8b5"
+  "gitHead": "5748bd9966b5e175ddf5995ee4cdce6f60c4272e"
 }