@jsdevtools/npm-publish 2.0.0 → 2.1.0

package/src/compare-and-publish/compare-and-publish.ts

@@ -0,0 +1,75 @@
+import type { PackageManifest } from "../read-manifest.js";
+import type { NormalizedOptions } from "../normalize-options.js";
+import {
+  VIEW,
+  PUBLISH,
+  E404,
+  EPUBLISHCONFLICT,
+  callNpmCli,
+  type NpmCliEnvironment,
+} from "../npm/index.js";
+import { compareVersions, type VersionComparison } from "./compare-versions.js";
+import { getViewArguments, getPublishArguments } from "./get-arguments.js";
+
+export interface PublishResult extends VersionComparison {
+  id: string | undefined;
+  files: PublishFile[];
+}
+
+export interface PublishFile {
+  path: string;
+  size: number;
+}
+
+/**
+ * Get the currently published versions of a package and publish if needed.
+ *
+ * @param manifest The package to potentially publish.
+ * @param options Configuration options.
+ * @param environment Environment variables for the npm cli.
+ * @returns Information about the publish, including if it occurred.
+ */
+export async function compareAndPublish(
+  manifest: PackageManifest,
+  options: NormalizedOptions,
+  environment: NpmCliEnvironment
+): Promise<PublishResult> {
+  const { name, version, packageSpec } = manifest;
+  const cliOptions = { environment, logger: options.logger };
+
+  const viewArguments = getViewArguments(name, options);
+  const publishArguments = getPublishArguments(packageSpec, options);
+  let viewCall = await callNpmCli(VIEW, viewArguments, cliOptions);
+
+  // `npm view` will succeed with no output the package exists in the registry
+  // with no `latest` tag. This is only possible with third-party registries.
+  // https://github.com/npm/cli/issues/6408
+  if (!viewCall.successData && !viewCall.error) {
+    // Retry the call to `npm view` with the configured publish tag,
+    // to at least try to get something.
+    const viewWithTagArguments = getViewArguments(name, options, true);
+    viewCall = await callNpmCli(VIEW, viewWithTagArguments, cliOptions);
+  }
+
+  if (viewCall.error && viewCall.errorCode !== E404) {
+    throw viewCall.error;
+  }
+
+  const comparison = compareVersions(version, viewCall.successData, options);
+  const publishCall = comparison.type
+    ? await callNpmCli(PUBLISH, publishArguments, cliOptions)
+    : { successData: undefined, errorCode: undefined, error: undefined };
+
+  if (publishCall.error && publishCall.errorCode !== EPUBLISHCONFLICT) {
+    throw publishCall.error;
+  }
+
+  const { successData: publishData } = publishCall;
+
+  return {
+    id: publishData?.id,
+    files: publishData?.files ?? [],
+    type: publishData ? comparison.type : undefined,
+    oldVersion: comparison.oldVersion,
+  };
+}

package/src/compare-and-publish/compare-versions.ts

@@ -0,0 +1,48 @@
+import semverDifference from "semver/functions/diff.js";
+import semverGreaterThan from "semver/functions/gt.js";
+import semverValid from "semver/functions/valid.js";
+
+import { STRATEGY_ALL } from "../options.js";
+import type { NormalizedOptions } from "../normalize-options.js";
+import type { ReleaseType } from "../results.js";
+import type { NpmViewData } from "../npm/index.js";
+
+export interface VersionComparison {
+  type: ReleaseType | undefined;
+  oldVersion: string | undefined;
+}
+
+const INITIAL = "initial";
+const DIFFERENT = "different";
+
+/**
+ * Compare previously published versions with the package's current version.
+ *
+ * @param currentVersion The current package version.
+ * @param publishedVersions The versions that have already been published.
+ * @param options Configuration options
+ * @returns The release type and previous version.
+ */
+export function compareVersions(
+  currentVersion: string,
+  publishedVersions: NpmViewData | undefined,
+  options: NormalizedOptions
+): VersionComparison {
+  const { versions, "dist-tags": tags } = publishedVersions ?? {};
+  const { strategy, tag: publishTag } = options;
+  const oldVersion = semverValid(tags?.[publishTag.value]) ?? undefined;
+  const isUnique = !versions?.includes(currentVersion);
+  let type: ReleaseType | undefined;
+
+  if (isUnique) {
+    if (!oldVersion) {
+      type = INITIAL;
+    } else if (semverGreaterThan(currentVersion, oldVersion)) {
+      type = semverDifference(currentVersion, oldVersion) ?? DIFFERENT;
+    } else if (strategy.value === STRATEGY_ALL) {
+      type = DIFFERENT;
+    }
+  }
+
+  return { type, oldVersion };
+}

package/src/compare-and-publish/get-arguments.ts

@@ -0,0 +1,61 @@
+import type { NormalizedOptions } from "../normalize-options.js";
+
+/**
+ * Given a package name and publish configuration, get the NPM CLI view
+ * arguments.
+ *
+ * @param packageName Package name.
+ * @param options Publish configuration.
+ * @param retryWithTag Include a non-latest tag in the package spec for a rety
+ *   attempt.
+ * @returns Arguments to pass to the NPM CLI. If `retryWithTag` is true, but the
+ *   publish config is using the `latest` tag, will return `undefined`.
+ */
+export function getViewArguments(
+  packageName: string,
+  options: NormalizedOptions,
+  retryWithTag = false
+): string[] {
+  const packageSpec = retryWithTag
+    ? `${packageName}@${options.tag.value}`
+    : packageName;
+
+  return [packageSpec, "dist-tags", "versions"];
+}
+
+/**
+ * Given a publish configuration, get the NPM CLI publish arguments.
+ *
+ * @param packageSpec Package specification path.
+ * @param options Publish configuration.
+ * @returns Arguments to pass to the NPM CLI.
+ */
+export function getPublishArguments(
+  packageSpec: string,
+  options: NormalizedOptions
+): string[] {
+  const { tag, access, dryRun, provenance } = options;
+  const publishArguments = [];
+
+  if (packageSpec.length > 0) {
+    publishArguments.push(packageSpec);
+  }
+
+  if (!tag.isDefault) {
+    publishArguments.push("--tag", tag.value);
+  }
+
+  if (!access.isDefault && access.value) {
+    publishArguments.push("--access", access.value);
+  }
+
+  if (!provenance.isDefault && provenance.value) {
+    publishArguments.push("--provenance");
+  }
+
+  if (!dryRun.isDefault && dryRun.value) {
+    publishArguments.push("--dry-run");
+  }
+
+  return publishArguments;
+}

package/src/compare-and-publish/index.ts

@@ -0,0 +1 @@
+export * from "./compare-and-publish.js";

package/src/errors.ts

@@ -95,6 +95,13 @@ export class InvalidTokenError extends TypeError {
   }
 }
 
+export class InvalidTagError extends TypeError {
+  public constructor(value: unknown) {
+    super(`Tag must be a non-empty string, got "${String(value)}".`);
+    this.name = "InvalidTagError";
+  }
+}
+
 export class InvalidAccessError extends TypeError {
   public constructor(value: unknown) {
     super(

package/src/format-publish-result.ts

@@ -1,6 +1,6 @@
 import os from "node:os";
 
-import type { PublishResult } from "./npm/index.js";
+import type { PublishResult } from "./compare-and-publish/index.js";
 import type { PackageManifest } from "./read-manifest.js";
 import type { NormalizedOptions } from "./normalize-options.js";
 
@@ -9,22 +9,22 @@ import type { NormalizedOptions } from "./normalize-options.js";
  *
  * @param manifest Package manifest
  * @param options Configuration options.
- * @param results Results from running npm publish.
+ * @param result Results from running npm publish.
  * @returns Formatted string.
  */
 export function formatPublishResult(
   manifest: PackageManifest,
   options: NormalizedOptions,
-  results?: PublishResult
+  result: PublishResult
 ): string {
-  if (results === undefined) {
+  if (result.id === undefined) {
     return `🙅‍♀️ ${manifest.name}@${manifest.version} publish skipped.`;
   }
 
   return [
-    `📦 ${results.id}${options.dryRun.value ? " (DRY RUN)" : ""}`,
+    `📦 ${result.id}${options.dryRun.value ? " (DRY RUN)" : ""}`,
     "=== Contents ===",
-    ...results.files.map(({ path, size }) => `${formatSize(size)}\t${path}`),
+    ...result.files.map(({ path, size }) => `${formatSize(size)}\t${path}`),
   ].join(os.EOL);
 }
 

package/src/normalize-options.ts

@@ -13,8 +13,8 @@ import {
   type Logger,
 } from "./options.js";
 
-const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
-const DEFAULT_TAG = "latest";
+const REGISTRY_NPM = "https://registry.npmjs.org/";
+export const TAG_LATEST = "latest";
 
 /** Normalized and sanitized auth, publish, and runtime configurations. */
 export interface NormalizedOptions {
@@ -22,6 +22,7 @@ export interface NormalizedOptions {
   token: string;
   tag: ConfigValue<string>;
   access: ConfigValue<Access | undefined>;
+  provenance: ConfigValue<boolean>;
   dryRun: ConfigValue<boolean>;
   strategy: ConfigValue<Strategy>;
   logger: Logger | undefined;
@@ -37,28 +38,31 @@ export interface ConfigValue<TValue> {
 /**
  * Normalizes and sanitizes options, and fills-in any default values.
  *
- * @param options User-input options.
  * @param manifest Package metadata from package.json.
+ * @param options User-input options.
  * @returns Validated auth and publish configuration.
  */
 export function normalizeOptions(
-  options: Options,
-  manifest: PackageManifest
+  manifest: PackageManifest,
+  options: Options
 ): NormalizedOptions {
-  const defaultTag = manifest.publishConfig?.tag ?? DEFAULT_TAG;
+  const defaultTag = manifest.publishConfig?.tag ?? TAG_LATEST;
 
-  const defaultRegistry = manifest.publishConfig?.registry ?? DEFAULT_REGISTRY;
+  const defaultRegistry = manifest.publishConfig?.registry ?? REGISTRY_NPM;
 
   const defaultAccess =
     manifest.publishConfig?.access ??
     (manifest.scope === undefined ? ACCESS_PUBLIC : undefined);
 
+  const defaultProvenance = manifest.publishConfig?.provenance ?? false;
+
   return {
     token: validateToken(options.token),
     registry: validateRegistry(options.registry ?? defaultRegistry),
     tag: setValue(options.tag, defaultTag, validateTag),
     access: setValue(options.access, defaultAccess, validateAccess),
-    dryRun: setValue(options.dryRun, false, validateDryRun),
+    provenance: setValue(options.provenance, defaultProvenance, Boolean),
+    dryRun: setValue(options.dryRun, false, Boolean),
     strategy: setValue(options.strategy, STRATEGY_ALL, validateStrategy),
     logger: options.logger,
     temporaryDirectory: options.temporaryDirectory ?? os.tmpdir(),
@@ -91,11 +95,11 @@ const validateRegistry = (value: unknown): URL => {
 };
 
 const validateTag = (value: unknown): string => {
-  return value as string;
-};
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
 
-const validateDryRun = (value: unknown): boolean => {
-  return value as boolean;
+  throw new errors.InvalidTagError(value);
 };
 
 const validateAccess = (value: unknown): Access | undefined => {

package/src/npm/call-npm-cli.ts

@@ -5,20 +5,93 @@ import * as errors from "../errors.js";
 import type { Logger } from "../options.js";
 import type { NpmCliEnvironment } from "./use-npm-environment.js";
 
-export interface NpmCliOptions<TReturn> {
-  environment?: NpmCliEnvironment;
-  ifError?: Record<string, TReturn>;
+export interface NpmCliOptions {
+  environment: NpmCliEnvironment;
   logger?: Logger | undefined;
 }
 
+export interface NpmCallResult<CommandT extends Command> {
+  successData: SuccessData<CommandT> | undefined;
+  errorCode: string | undefined;
+  error: Error | undefined;
+}
+
+type SuccessData<T extends Command> = T extends typeof VIEW
+  ? NpmViewData
+  : T extends typeof PUBLISH
+  ? NpmPublishData
+  : unknown;
+
+export interface NpmViewData {
+  "dist-tags": Record<string, string>;
+  versions: string[];
+}
+export interface NpmPublishData {
+  id: string;
+  files: { path: string; size: number }[];
+}
+
+export type Command = typeof VIEW | typeof PUBLISH | string;
+export const VIEW = "view";
+export const PUBLISH = "publish";
+
+export const E404 = "E404";
+export const EPUBLISHCONFLICT = "EPUBLISHCONFLICT";
+
 const NPM = os.platform() === "win32" ? "npm.cmd" : "npm";
 const JSON_MATCH_RE = /(\{[\s\S]*\})/mu;
 
-const execNpm = (
+/**
+ * Call the NPM CLI in JSON mode.
+ *
+ * @param command The command of the NPM CLI to call
+ * @param cliArguments Any arguments to send to the command
+ * @param options Customize environment variables or add an error handler.
+ * @returns The parsed JSON, or stdout if unparsable.
+ */
+export async function callNpmCli<CommandT extends Command>(
+  command: CommandT,
+  cliArguments: string[],
+  options: NpmCliOptions
+): Promise<NpmCallResult<CommandT>> {
+  const { stdout, stderr, exitCode } = await execNpm(
+    [command, "--ignore-scripts", "--json", ...cliArguments],
+    options.environment,
+    options.logger
+  );
+
+  let successData;
+  let errorCode;
+  let error;
+
+  if (exitCode === 0) {
+    successData = parseJson<SuccessData<CommandT>>(stdout);
+  } else {
+    const errorPayload = parseJson<{ error?: { code?: string | null } }>(
+      stdout,
+      stderr
+    );
+
+    errorCode = errorPayload?.error?.code?.toUpperCase();
+    error = new errors.NpmCallError(command, exitCode, stderr);
+  }
+
+  return { successData, errorCode, error };
+}
+
+/**
+ * Execute the npm CLI.
+ *
+ * @param commandArguments Npm subcommand and arguments.
+ * @param environment Environment variables.
+ * @param logger Optional logger.
+ * @returns Stdout, stderr, and the exit code.
+ */
+async function execNpm(
   commandArguments: string[],
-  environment: Record<string, string> = {},
+  environment: Record<string, string>,
   logger?: Logger
-): Promise<{ stdout: string; stderr: string; exitCode: number }> => {
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
   logger?.debug?.(`Running command: ${NPM} ${commandArguments.join(" ")}`);
 
   return new Promise((resolve) => {
@@ -39,9 +112,18 @@ const execNpm = (
       });
     });
   });
-};
+}
 
-const parseJson = <TParsed>(...values: string[]): TParsed | undefined => {
+/**
+ * Parse CLI outputs for JSON data.
+ *
+ * Certain versions of the npm CLI may intersperse JSON with human-readable
+ * output, which this function accounts for.
+ *
+ * @param values CLI outputs to check
+ * @returns Parsed JSON, if able to parse.
+ */
+function parseJson<TParsed>(...values: string[]): TParsed | undefined {
   for (const value of values) {
     const jsonValue = JSON_MATCH_RE.exec(value)?.[1];
 
@@ -55,44 +137,4 @@ const parseJson = <TParsed>(...values: string[]): TParsed | undefined => {
   }
 
   return undefined;
-};
-
-/**
- * Call the NPM CLI in JSON mode.
- *
- * @param command The command of the NPM CLI to call
- * @param cliArguments Any arguments to send to the command
- * @param options Customize environment variables or add an error handler.
- * @returns The parsed JSON, or stdout if unparsable.
- */
-export async function callNpmCli<TReturn = string>(
-  command: string,
-  cliArguments: string[],
-  options: NpmCliOptions<TReturn> = {}
-): Promise<TReturn> {
-  const { stdout, stderr, exitCode } = await execNpm(
-    [command, "--ignore-scripts", "--json", ...cliArguments],
-    options.environment,
-    options.logger
-  );
-
-  if (exitCode !== 0) {
-    const errorPayload = parseJson<{ error?: { code?: string | null } }>(
-      stdout,
-      stderr
-    );
-    const errorCode = errorPayload?.error?.code?.toLowerCase();
-
-    if (
-      typeof errorCode === "string" &&
-      options.ifError &&
-      errorCode in options.ifError
-    ) {
-      return options.ifError[errorCode] as TReturn;
-    }
-
-    throw new errors.NpmCallError(command, exitCode, stderr);
-  }
-
-  return parseJson(stdout) ?? (stdout as unknown as TReturn);
 }

package/src/npm/index.ts

@@ -1,64 +1,2 @@
-import type { NormalizedOptions } from "../normalize-options.js";
-import { useNpmEnvironment } from "./use-npm-environment.js";
-import { callNpmCli } from "./call-npm-cli.js";
-import { getPublishArguments } from "./get-publish-arguments.js";
-
-export interface PublishedVersions {
-  "dist-tags": Record<string, string>;
-  versions: string[];
-}
-
-export interface PublishFile {
-  path: string;
-  size: number;
-}
-
-export interface PublishResult {
-  id: string;
-  files: PublishFile[];
-}
-
-/**
- * Get a package's published versions.
- *
- * @param packageName The name of the package to get published versions for.
- * @param options Configuration options.
- * @returns All published versions and tags.
- */
-export async function getVersions(
-  packageName: string,
-  options: NormalizedOptions
-): Promise<PublishedVersions> {
-  return useNpmEnvironment(options, (environment) => {
-    return callNpmCli<PublishedVersions>(
-      "view",
-      [packageName, "dist-tags", "versions"],
-      {
-        logger: options.logger,
-        environment,
-        ifError: { e404: { "dist-tags": {}, versions: [] } },
-      }
-    );
-  });
-}
-
-/**
- * Publish a package.
- *
- * @param packageSpec Package specification to pass to npm.
- * @param options Configuration options.
- * @returns Release metadata.
- */
-export async function publish(
-  packageSpec: string,
-  options: NormalizedOptions
-): Promise<PublishResult> {
-  const publishArguments = getPublishArguments(packageSpec, options);
-
-  return useNpmEnvironment(options, (environment) => {
-    return callNpmCli<PublishResult>("publish", publishArguments, {
-      logger: options.logger,
-      environment,
-    });
-  });
-}
+export * from "./call-npm-cli.js";
+export * from "./use-npm-environment.js";

package/src/npm/use-npm-environment.ts

@@ -2,11 +2,14 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
+import type { PackageManifest } from "../read-manifest.js";
 import type { NormalizedOptions } from "../normalize-options.js";
 
 export type NpmCliEnvironment = Record<string, string>;
 
 export type NpmCliTask<TReturn> = (
+  manifest: PackageManifest,
+  options: NormalizedOptions,
   environment: NpmCliEnvironment
 ) => Promise<TReturn>;
 
@@ -14,12 +17,14 @@ export type NpmCliTask<TReturn> = (
  * Create a temporary .npmrc file with the given auth token, and call a task
  * with env vars set to use that .npmrc.
  *
+ * @param manifest Pacakge metadata.
  * @param options Configuration options.
  * @param task A function called with the configured environment. After the
  *   function resolves, the temporary .npmrc file will be removed.
  * @returns The resolved value of `task`
  */
 export async function useNpmEnvironment<TReturn>(
+  manifest: PackageManifest,
   options: NormalizedOptions,
   task: NpmCliTask<TReturn>
 ): Promise<TReturn> {
@@ -28,6 +33,10 @@ export async function useNpmEnvironment<TReturn>(
     path.join(temporaryDirectory, "npm-publish-")
   );
   const npmrc = path.join(npmrcDirectory, ".npmrc");
+  const environment = {
+    NODE_AUTH_TOKEN: token,
+    npm_config_userconfig: npmrc,
+  };
 
   const config = [
     "; created by jsdevtools/npm-publish",
@@ -41,10 +50,7 @@ export async function useNpmEnvironment<TReturn>(
   logger?.debug?.(`Temporary .npmrc created at ${npmrc}\n${config}`);
 
   try {
-    return await task({
-      NODE_AUTH_TOKEN: token,
-      npm_config_userconfig: npmrc,
-    });
+    return await task(manifest, options, environment);
   } finally {
     await fs.rm(npmrcDirectory, { force: true, recursive: true });
   }

package/src/npm-publish.ts

@@ -1,7 +1,7 @@
 import { readManifest } from "./read-manifest.js";
 import { normalizeOptions } from "./normalize-options.js";
-import { getVersions, publish } from "./npm/index.js";
-import { compareVersions } from "./compare-versions.js";
+import { useNpmEnvironment } from "./npm/index.js";
+import { compareAndPublish } from "./compare-and-publish/index.js";
 import { formatPublishResult } from "./format-publish-result.js";
 import type { Options } from "./options.js";
 import type { Results } from "./results.js";
@@ -13,31 +13,24 @@ import type { Results } from "./results.js";
  * @returns Release metadata.
  */
 export async function npmPublish(options: Options): Promise<Results> {
-  const { packageSpec, manifest } = await readManifest(options.package);
-  const normalizedOptions = normalizeOptions(options, manifest);
-  const publishedVersions = await getVersions(manifest.name, normalizedOptions);
-  const versionComparison = compareVersions(
-    manifest.version,
-    publishedVersions,
-    normalizedOptions
+  const manifest = await readManifest(options.package);
+  const normalizedOptions = normalizeOptions(manifest, options);
+  const publishResult = await useNpmEnvironment(
+    manifest,
+    normalizedOptions,
+    compareAndPublish
   );
 
-  let publishResult;
-
-  if (versionComparison.type !== undefined) {
-    publishResult = await publish(packageSpec, normalizedOptions);
-  }
-
   normalizedOptions.logger?.info?.(
     formatPublishResult(manifest, normalizedOptions, publishResult)
   );
 
   return {
-    id: publishResult?.id,
+    id: publishResult.id,
+    type: publishResult.type,
+    oldVersion: publishResult.oldVersion,
     name: manifest.name,
     version: manifest.version,
-    type: versionComparison.type,
-    oldVersion: versionComparison.oldVersion,
     registry: normalizedOptions.registry,
     tag: normalizedOptions.tag.value,
     access: normalizedOptions.access.value,

package/src/options.ts

@@ -39,7 +39,7 @@ export interface Options {
    *
    * Defaults to "https://registry.npmjs.org/".
    *
-   * Can be overridden by the package.json's `publishConfig` field.
+   * Can be set by the package.json's `publishConfig` field.
    */
   registry?: string | URL | undefined;
 
@@ -48,7 +48,7 @@ export interface Options {
    *
    * Defaults to "latest".
    *
-   * Can be overridden by the package.json's `publishConfig` field.
+   * Can be set by the package.json's `publishConfig` field.
    */
   tag?: string | undefined;
 
@@ -62,10 +62,22 @@ export interface Options {
    * Defaults to "restricted" for scoped packages, unless that package has been
    * previously published as `public`
    *
-   * Can be overridden by the package.json's `publishConfig` field.
+   * Can be set by the package.json's `publishConfig` field.
    */
   access?: Access | undefined;
 
+  /**
+   * Generate provenance statements.
+   *
+   * Publish must be run from a supported CI provider to succeed. When run from
+   * GitHub Actions, requires `id-token: write` permission.
+   *
+   * Defaults to `false`.
+   *
+   * Can be set by the package.json's `publishConfig` field.
+   */
+  provenance?: boolean | undefined;
+
   /**
    * Version check strategy.
    *