@sanity/pkg-utils 6.4.1 → 6.6.0

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import type {Plugin as RollupPlugin} from 'rollup'
 import {RollupWatcherEvent} from 'rollup'
 import type {TreeshakingOptions} from 'rollup'
 import ts from 'typescript'
+import {z} from 'zod'
 
 /**
  * Build the distribution files of a npm package.
@@ -145,6 +146,11 @@ export declare function getExtractMessagesConfig(options: {
   rules: NonNullable<PkgConfigOptions['extract']>['rules']
 }): IExtractorMessagesConfig
 
+/**
+ * @public
+ */
+export declare type InferredStrictOptions = z.infer<typeof strictOptions>
+
 /** @public */
 export declare function init(options: {cwd: string; path: string}): Promise<void>
 
@@ -260,7 +266,9 @@ export declare interface PackageJSON {
 export declare function parseExports(options: {
   pkg: PackageJSON
   strict: boolean
+  strictOptions: InferredStrictOptions
   legacyExports: boolean
+  logger: Logger
 }): (PkgExport & {
   _path: string
 })[]
@@ -365,6 +373,10 @@ export declare interface PkgConfigOptions {
    */
   src?: string
   tsconfig?: string
+  /**
+   * Configure what checks are made when running `--strict` builds and checks
+   */
+  strictOptions?: StrictOptions
 }
 
 /** @public */
@@ -535,6 +547,90 @@ export declare interface RollupWatchTask {
 /** @internal */
 export declare const rollupWatchTask: TaskHandler<RollupWatchTask, RollupWatcherEvent>
 
+/**
+ * @public
+ */
+export declare interface StrictOptions {
+  /**
+   * Disallows a top level `typings` field in `package.json` if it is equal to `exports['.'].source`.
+   * @defaultValue 'error'
+   */
+  noPackageJsonTypings?: ToggleType
+  /**
+   * Requires specifying `sideEffects` in `package.json`.
+   * @defaultValue 'warn'
+   */
+  noImplicitSideEffects?: ToggleType
+  /**
+   * Requires specifying `browserslist` in `package.json`, instead of relying on it implicitly being:
+   * @example
+   * ```
+   * "browserslist": "extends @sanity/browserslist-config"
+   * ```
+   * @defaultValue 'warn'
+   */
+  noImplicitBrowsersList?: ToggleType
+  /**
+   * If typescript is used then `types` in `package.json` should be specified for npm listings to show the TS icon.
+   * @defaultValue 'error'
+   */
+  alwaysPackageJsonTypes?: ToggleType
+  /**
+   * A lot of analysis tooling requiers the `main` field to work (like bundlephobia) and so it's best practice to always include it
+   * @defaultValue 'error'
+   */
+  alwaysPackageJsonMain?: ToggleType
+  /**
+   * Using `.npmignore` is error prone, it's best practice to always declare `files` instead
+   * @defaultValue 'error'
+   */
+  alwaysPackageJsonFiles?: ToggleType
+}
+
+/**
+ * @public
+ */
+export declare const strictOptions: z.ZodObject<
+  {
+    noPackageJsonTypings: z.ZodDefault<
+      z.ZodUnion<[z.ZodLiteral<'error'>, z.ZodLiteral<'warn'>, z.ZodLiteral<'off'>]>
+    >
+    noImplicitSideEffects: z.ZodDefault<
+      z.ZodUnion<[z.ZodLiteral<'error'>, z.ZodLiteral<'warn'>, z.ZodLiteral<'off'>]>
+    >
+    noImplicitBrowsersList: z.ZodDefault<
+      z.ZodUnion<[z.ZodLiteral<'error'>, z.ZodLiteral<'warn'>, z.ZodLiteral<'off'>]>
+    >
+    alwaysPackageJsonTypes: z.ZodDefault<
+      z.ZodUnion<[z.ZodLiteral<'error'>, z.ZodLiteral<'warn'>, z.ZodLiteral<'off'>]>
+    >
+    alwaysPackageJsonMain: z.ZodDefault<
+      z.ZodUnion<[z.ZodLiteral<'error'>, z.ZodLiteral<'warn'>, z.ZodLiteral<'off'>]>
+    >
+    alwaysPackageJsonFiles: z.ZodDefault<
+      z.ZodUnion<[z.ZodLiteral<'error'>, z.ZodLiteral<'warn'>, z.ZodLiteral<'off'>]>
+    >
+  },
+  'strict',
+  z.ZodTypeAny,
+  {
+    noPackageJsonTypings: 'error' | 'warn' | 'off'
+    noImplicitSideEffects: 'error' | 'warn' | 'off'
+    noImplicitBrowsersList: 'error' | 'warn' | 'off'
+    alwaysPackageJsonTypes: 'error' | 'warn' | 'off'
+    alwaysPackageJsonMain: 'error' | 'warn' | 'off'
+    alwaysPackageJsonFiles: 'error' | 'warn' | 'off'
+  },
+  {
+    noPackageJsonTypings?: 'error' | 'warn' | 'off' | undefined
+    noImplicitSideEffects?: 'error' | 'warn' | 'off' | undefined
+    noImplicitBrowsersList?: 'error' | 'warn' | 'off' | undefined
+    alwaysPackageJsonTypes?: 'error' | 'warn' | 'off' | undefined
+    alwaysPackageJsonMain?: 'error' | 'warn' | 'off' | undefined
+    alwaysPackageJsonFiles?: 'error' | 'warn' | 'off' | undefined
+  }
+>
+
 /** @internal */
 export declare type TaskHandler<Task, Result = void> = {
   name: (ctx: BuildContext, task: Task) => string
@@ -543,6 +639,18 @@ export declare type TaskHandler<Task, Result = void> = {
   error: (ctx: BuildContext, task: Task, error: unknown) => void
 }
 
+/**
+ * @public
+ */
+export declare const toggle: z.ZodUnion<
+  [z.ZodLiteral<'error'>, z.ZodLiteral<'warn'>, z.ZodLiteral<'off'>]
+>
+
+/**
+ * @public
+ */
+export declare type ToggleType = z.infer<typeof toggle>
+
 /** @public */
 export declare interface TSDocCustomTag {
   name: string

package/dist/index.js

@@ -10,6 +10,7 @@ import fs, { writeFile, readFile, readdir, lstat } from "node:fs/promises";
 import browserslist from "browserslist";
 import config from "@sanity/browserslist-config";
 import ts from "typescript";
+import { errorMap } from "zod-validation-error";
 import { Observable, switchMap } from "rxjs";
 import { ExtractorConfig, Extractor } from "@microsoft/api-extractor";
 import { mkdirp } from "mkdirp";
@@ -269,8 +270,13 @@ function validateExports(_exports, options2) {
   return errors;
 }
 function parseExports(options2) {
-  const { pkg, strict, legacyExports } = options2, type = pkg.type || "commonjs", errors = [];
-  if (pkg.source) {
+  const { pkg, strict, strictOptions: strictOptions2, legacyExports, logger } = options2, type = pkg.type || "commonjs", errors = [], report = (kind, message) => {
+    kind === "warn" ? logger.warn(message) : errors.push(message);
+  };
+  if (!pkg.main && strict && strictOptions2.alwaysPackageJsonMain !== "off" && report(strictOptions2.alwaysPackageJsonMain, "package.json: `main` must be declared"), !Array.isArray(pkg.files) && strict && strictOptions2.alwaysPackageJsonFiles !== "off" && report(
+    strictOptions2.alwaysPackageJsonFiles,
+    "package.json: `files` should be used over `.npmignore`"
+  ), pkg.source) {
     if (strict && pkg.exports?.["."] && typeof pkg.exports["."] == "object" && "source" in pkg.exports["."] && pkg.exports["."].source === pkg.source)
       errors.push(
         'package.json: the "source" property can be removed, as it is equal to exports["."].source.'
@@ -345,7 +351,8 @@ function parseExports(options2) {
 - `)
     );
   const _exports = [];
-  strict && "typings" in pkg && errors.push("package.json: `typings` should be `types`"), strict && !pkg.types && pkg.source?.endsWith(".ts") && errors.push(
+  strict && strictOptions2.noPackageJsonTypings !== "off" && "typings" in pkg && report(strictOptions2.noPackageJsonTypings, "package.json: `typings` should be `types`"), strict && strictOptions2.alwaysPackageJsonTypes !== "off" && !pkg.types && typeof pkg.exports?.["."] == "object" && "source" in pkg.exports["."] && pkg.exports["."].source?.endsWith(".ts") && report(
+    strictOptions2.alwaysPackageJsonTypes,
     "package.json: `types` must be declared for the npm listing to show as a TypeScript module."
   ), strict && !pkg.exports["./package.json"] && errors.push('package.json: `exports["./package.json"] must be declared.');
   for (const [exportPath, exportEntry] of Object.entries(pkg.exports))
@@ -520,6 +527,19 @@ function resolveNodeTarget(versions) {
   if (target.length !== 0)
     return target;
 }
+const toggle = z.union([z.literal("error"), z.literal("warn"), z.literal("off")]), strictOptions = z.object({
+  noPackageJsonTypings: toggle.default("error"),
+  noImplicitSideEffects: toggle.default("warn"),
+  noImplicitBrowsersList: toggle.default("warn"),
+  alwaysPackageJsonTypes: toggle.default("error"),
+  alwaysPackageJsonMain: toggle.default("error"),
+  alwaysPackageJsonFiles: toggle.default("error")
+}).strict(), validationSchema = z.object({
+  strictOptions: strictOptions.default({})
+});
+function parseStrictOptions(input) {
+  return validationSchema.parse({ strictOptions: input }, { errorMap }).strictOptions;
+}
 async function resolveBuildContext(options2) {
   const {
     config: config2,
@@ -529,15 +549,27 @@ async function resolveBuildContext(options2) {
     pkg,
     strict,
     tsconfig: tsconfigPath
-  } = options2, tsconfig = await loadTSConfig({ cwd, tsconfigPath });
+  } = options2, tsconfig = await loadTSConfig({ cwd, tsconfigPath }), strictOptions2 = parseStrictOptions(config2?.strictOptions ?? {});
   let browserslist2 = pkg.browserslist;
-  browserslist2 || (strict && logger.warn(
-    'Could not detect a `browserslist` property in `package.json`, using default configuration. Add `"browserslist": "extends @sanity/browserslist-config"` to silence this warning.'
-  ), browserslist2 = DEFAULT_BROWSERSLIST_QUERY);
+  if (!browserslist2) {
+    if (strict && strictOptions2.noImplicitBrowsersList !== "off") {
+      if (strictOptions2.noImplicitBrowsersList === "error")
+        throw new Error(
+          '\n- package.json: "browserslist" is missing, set it to `"browserslist": "extends @sanity/browserslist-config"`'
+        );
+      logger.warn(
+        'Could not detect a `browserslist` property in `package.json`, using default configuration. Add `"browserslist": "extends @sanity/browserslist-config"` to silence this warning.'
+      );
+    }
+    browserslist2 = DEFAULT_BROWSERSLIST_QUERY;
+  }
   const targetVersions = browserslistToEsbuild(browserslist2);
-  strict && typeof pkg.sideEffects > "u" && logger.error(
-    'No `sideEffects` field in `package.json`, assuming all files are side-effectful. Add `"sideEffects": true` to silence this warning. See https://webpack.js.org/guides/tree-shaking/#clarifying-tree-shaking-and-sideeffects for how to define `sideEffects`.'
-  );
+  if (strict && strictOptions2.noImplicitSideEffects !== "off" && typeof pkg.sideEffects > "u") {
+    const msg = "package.json: `sideEffects` is missing, see https://webpack.js.org/guides/tree-shaking/#clarifying-tree-shaking-and-sideeffects for how to define `sideEffects`";
+    if (strictOptions2.noImplicitSideEffects === "error")
+      throw new Error(msg);
+    logger.warn(msg);
+  }
   const nodeTarget = resolveNodeTarget(targetVersions), webTarget = resolveBrowserTarget(targetVersions);
   if (!nodeTarget)
     throw new Error("no matching `node` target");
@@ -550,7 +582,9 @@ async function resolveBuildContext(options2) {
   }, parsedExports = parseExports({
     pkg,
     strict,
-    legacyExports: config2?.legacyExports ?? !1
+    legacyExports: config2?.legacyExports ?? !1,
+    strictOptions: strictOptions2,
+    logger
   }).reduce((acc, x) => {
     const { _path: exportPath, ...exportEntry } = x;
     return { ...acc, [exportPath]: exportEntry };
@@ -21585,6 +21619,8 @@ export {
   rollupLegacyTask,
   rollupTask,
   rollupWatchTask,
+  strictOptions,
+  toggle,
   watch,
   watchTaskHandlers
 };