@savvy-web/rslib-builder 0.16.0 → 0.18.0

package/index.d.ts

@@ -135,6 +135,32 @@ export declare interface ApiModelOptions {
      *               `"include"` otherwise
      */
     forgottenExports?: "include" | "error" | "ignore";
+    /**
+     * Declarative rules for suppressing specific API Extractor warning messages.
+     *
+     * @remarks
+     * Each rule matches on `messageId` (exact), `pattern` (RegExp with substring fallback),
+     * or both (AND logic). Suppression is evaluated before `forgottenExports` and TSDoc
+     * warning handling and takes priority over both.
+     *
+     * After each entry, the number of suppressed messages is logged at info level.
+     *
+     * @example
+     * ```typescript
+     * import type { ApiModelOptions } from '@savvy-web/rslib-builder';
+     *
+     * const apiModel: ApiModelOptions = {
+     *   forgottenExports: 'error',
+     *   suppressWarnings: [
+     *     // Suppress forgotten-export for Effect _base symbols
+     *     { messageId: 'ae-forgotten-export', pattern: '_base' },
+     *     // Suppress a specific TSDoc warning category
+     *     { messageId: 'tsdoc-param-tag-missing-hyphen' },
+     *   ],
+     * };
+     * ```
+     */
+    suppressWarnings?: WarningSuppressionRule[];
 }
 
 /**
@@ -646,8 +672,6 @@ export declare interface FilesArrayPluginOptions<TMode extends string = string>
         filesArray: Set<string>;
         /** Current build mode */
         mode: TMode;
-        /** The publish target for this build output, if configured */
-        target: PublishTarget | undefined;
     }) => void | Promise<void>;
     /**
      * Build mode identifier (e.g., "dev", "npm").
@@ -656,13 +680,6 @@ export declare interface FilesArrayPluginOptions<TMode extends string = string>
      * Passed to the `transformFiles` callback to allow mode-specific transformations.
      */
     mode: TMode;
-    /**
-     * The publish target for this build output, if configured.
-     *
-     * @remarks
-     * Passed to the `transformFiles` callback to allow target-specific transformations.
-     */
-    target?: PublishTarget;
     /**
      * Format directories to include in the files array.
      * Used in dual format builds so npm's `files` field includes
@@ -1477,8 +1494,6 @@ export declare interface NodeLibraryBuilderOptions {
         filesArray: Set<string>;
         /** Current build mode */
         mode: BuildMode;
-        /** The publish target for this build output, if configured */
-        target: PublishTarget | undefined;
     }) => void | Promise<void>;
     /**
      * Optional transform function to modify package.json before it's saved.
@@ -2215,15 +2230,15 @@ export declare interface PublishTarget {
  * Plugin to produce per-target output directories for multi-registry publishing.
  *
  * @remarks
- * Runs in `onCloseBuild` after the primary build completes. For each additional
- * publish target (beyond the primary):
+ * Runs in `onCloseBuild` after the main RSlib build completes. For each
+ * publish target:
  *
  * 1. Creates the target directory
- * 2. Copies all build output from the primary output directory
+ * 2. Copies all build output from the staging directory
  * 3. Reads the exposed `base-package-json` (after standard transforms, before user transform)
  * 4. Applies the user transform with the target-specific context
  * 5. Applies optional name override
- * 6. Copies the `files` array from the primary output's package.json
+ * 6. Copies the `files` array from the staging directory's package.json
  * 7. Writes the final package.json to the target directory
  *
  * @param options - Plugin configuration options
@@ -2239,37 +2254,37 @@ export declare const PublishTargetPlugin: (options: PublishTargetPluginOptions)
  */
 export declare interface PublishTargetPluginOptions {
     /**
-     * Additional publish targets to write output for (targets beyond the primary).
+     * Publish targets to write output for.
      *
      * @remarks
-     * Each target gets a copy of the primary build output with per-target
+     * Each target gets a copy of the build staging output with per-target
      * package.json transformations applied.
      */
-    additionalTargets: PublishTarget[];
+    targets: PublishTarget[];
     /**
-     * Absolute path to the primary output directory.
+     * Absolute path to the build staging directory (dist/&lt;mode&gt;).
      *
      * @remarks
-     * The primary build output is copied from this directory to each
-     * additional target's directory.
+     * Build artifacts are copied from this directory to each target's
+     * directory (when they differ).
      */
-    primaryOutdir: string;
+    stagingDir: string;
     /**
-     * Current build mode (e.g., "npm").
+     * Current build mode.
      */
-    mode: string;
+    mode: BuildMode;
     /**
      * Optional user transform function applied to each target's package.json.
      *
      * @remarks
-     * Called after copying the base package.json state for each additional target.
+     * Called after copying the base package.json state for each target.
      */
     transform?: TransformPackageJsonFn;
     /**
      * Optional package name override.
      *
      * @remarks
-     * When provided, overrides the `name` field in each additional target's package.json.
+     * When provided, overrides the `name` field in each target's package.json.
      */
     name?: string;
 }
@@ -3384,4 +3399,29 @@ export declare class TsconfigResolver {
         virtualEntryNames: Set<string>;
     }
 
+    /**
+     * A declarative rule for suppressing a specific API Extractor warning message.
+     *
+     * @remarks
+     * Both `messageId` and `pattern` must match when both are specified (AND logic).
+     * Specify at least one field per rule — a rule with neither field matches all messages.
+     *
+     * `pattern` is first tried as a RegExp. If the string is not a valid regular
+     * expression it falls back to substring matching.
+     *
+     * @public
+     */
+    export declare interface WarningSuppressionRule {
+        /**
+         * Exact match against the message's `messageId` property
+         * (e.g., `"ae-forgotten-export"`, `"tsdoc-param-tag-missing-hyphen"`).
+         */
+        messageId?: string;
+        /**
+         * Pattern matched against the message's `text` property.
+         * Tried as a RegExp first; falls back to case-sensitive substring match.
+         */
+        pattern?: string;
+    }
+
     export { }

package/index.js

@@ -597,6 +597,34 @@ const TSConfigs = {
         }
     }
 };
+function compileRule(rule) {
+    let regex = null;
+    let literal;
+    if (void 0 !== rule.pattern) try {
+        regex = new RegExp(rule.pattern);
+    } catch  {
+        literal = rule.pattern;
+    }
+    return {
+        messageId: rule.messageId,
+        regex,
+        literal
+    };
+}
+function matchesCompiled(rule, messageId, text) {
+    if (void 0 !== rule.messageId && messageId !== rule.messageId) return false;
+    if (null !== rule.regex) return rule.regex.test(text ?? "");
+    if (void 0 !== rule.literal) return (text ?? "").includes(rule.literal);
+    return true;
+}
+function createMessageSuppressor(rules) {
+    const compiled = rules.map(compileRule);
+    return {
+        matches (messageId, text) {
+            return compiled.some((rule)=>matchesCompiled(rule, messageId, text));
+        }
+    };
+}
 class TsconfigResolverError extends Error {
     option;
     value;
@@ -1120,6 +1148,8 @@ async function bundleDtsFiles(options) {
     const tsdocMetadataOption = "object" == typeof apiModel ? apiModel.tsdocMetadata : void 0;
     const tsdocWarnings = tsdocOptions?.warnings ?? (TsDocConfigBuilder.isCI() ? "fail" : "log");
     const forgottenExports = ("object" == typeof apiModel ? apiModel.forgottenExports : void 0) ?? (TsDocConfigBuilder.isCI() ? "error" : "include");
+    const suppressWarnings = "object" == typeof apiModel ? apiModel.suppressWarnings ?? [] : [];
+    const suppressor = createMessageSuppressor(suppressWarnings);
     const tsdocMetadataEnabled = apiModelEnabled && (void 0 === tsdocMetadataOption || true === tsdocMetadataOption || "object" == typeof tsdocMetadataOption && false !== tsdocMetadataOption.enabled);
     const tsdocMetadataFilename = resolveTsdocMetadataFilename(apiModel);
     getApiExtractorPath();
@@ -1196,10 +1226,16 @@ async function bundleDtsFiles(options) {
         const extractorConfig = ExtractorConfig.prepare(prepareOptions);
         const collectedTsdocWarnings = [];
         const collectedForgottenExports = [];
+        const suppressedMessages = [];
         const extractorResult = Extractor.invoke(extractorConfig, {
             localBuild: true,
             showVerboseMessages: false,
             messageCallback: (message)=>{
+                if (suppressor.matches(message.messageId, message.text)) {
+                    message.logLevel = ExtractorLogLevel.None;
+                    suppressedMessages.push(`[${message.messageId ?? "unknown"}] ${message.text ?? ""}`);
+                    return;
+                }
                 if (message.text?.includes("Analysis will use the bundled TypeScript version") || message.text?.includes("The target project appears to use TypeScript")) {
                     message.logLevel = ExtractorLogLevel.None;
                     return;
@@ -1244,6 +1280,10 @@ async function bundleDtsFiles(options) {
             }
         });
         if (!extractorResult.succeeded) throw new Error(`API Extractor failed for entry "${entryName}"`);
+        if (suppressedMessages.length > 0) {
+            const list = suppressedMessages.map((t)=>`  ${picocolors.dim(t)}`).join("\n");
+            core_logger.info(`Suppressed ${suppressedMessages.length} API Extractor message${1 === suppressedMessages.length ? "" : "s"} for entry "${entryName}":\n${list}`);
+        }
         const formatWarning = (warning)=>{
             const location = warning.sourceFilePath ? `${picocolors.cyan(relative(cwd, warning.sourceFilePath))}${warning.sourceFileLine ? `:${warning.sourceFileLine}` : ""}${warning.sourceFileColumn ? `:${warning.sourceFileColumn}` : ""}` : null;
             return location ? `${location}: ${picocolors.yellow(warning.text)}` : picocolors.yellow(warning.text);
@@ -1838,8 +1878,7 @@ const FilesArrayPlugin = (options)=>({
                 if (options?.transformFiles) await options.transformFiles({
                     compilation: context.compilation,
                     filesArray,
-                    mode: options.mode,
-                    target: options.target
+                    mode: options.mode
                 });
             });
             api.processAssets({
@@ -2358,30 +2397,30 @@ const PublishTargetPlugin = (options)=>({
         name: "publish-target-plugin",
         setup (api) {
             api.onCloseBuild(async ()=>{
-                const { additionalTargets, primaryOutdir, mode, transform, name } = options;
-                if (0 === additionalTargets.length) return;
+                const { targets, stagingDir, mode, transform, name } = options;
+                if (0 === targets.length) return;
                 const basePackageJson = api.useExposed("base-package-json");
                 if (!basePackageJson) return;
-                const primaryPkgPath = join(primaryOutdir, "package.json");
-                const primaryPkg = JSON.parse(readFileSync(primaryPkgPath, "utf-8"));
-                for (const target of additionalTargets){
-                    if (target.directory !== primaryOutdir) {
+                const stagingPkgPath = join(stagingDir, "package.json");
+                const stagingPkg = JSON.parse(readFileSync(stagingPkgPath, "utf-8"));
+                for (const target of targets){
+                    if (target.directory !== stagingDir) {
                         mkdirSync(target.directory, {
                             recursive: true
                         });
-                        cpSync(primaryOutdir, target.directory, {
+                        cpSync(stagingDir, target.directory, {
                             recursive: true
                         });
                     }
                     let targetPkg = JSON.parse(JSON.stringify(basePackageJson));
                     if (transform) targetPkg = transform({
-                        mode: mode,
+                        mode,
                         target,
                         pkg: targetPkg
                     });
                     if (name) targetPkg.name = name;
-                    if (primaryPkg.files) targetPkg.files = [
-                        ...primaryPkg.files
+                    if (stagingPkg.files) targetPkg.files = [
+                        ...stagingPkg.files
                     ];
                     writeFileSync(join(target.directory, "package.json"), `${JSON.stringify(targetPkg, null, 2)}\n`);
                 }
@@ -2881,11 +2920,11 @@ if (module.exports && module.exports.__esModule && 'default' in module.exports)
         const collapseIndex = bundle || !(options.exportsAsIndexes ?? false);
         const baseOutputDir = `dist/${mode}`;
         const publishTargets = "npm" === mode ? resolvePublishTargets(packageJson, cwd, external_node_path_resolve(cwd, baseOutputDir)) : [];
-        const primaryTarget = publishTargets[0];
+        const hasTargets = publishTargets.length > 0;
         const userTransform = options.transform;
-        const transformFn = userTransform ? (pkg)=>userTransform({
+        const transformFn = !hasTargets && userTransform ? (pkg)=>userTransform({
                 mode,
-                target: primaryTarget,
+                target: void 0,
                 pkg
             }) : void 0;
         const apiModelForMode = "npm" === mode ? options.apiModel : void 0;
@@ -2931,9 +2970,6 @@ if (module.exports && module.exports.__esModule && 'default' in module.exports)
         }));
         plugins.push(FilesArrayPlugin({
             mode,
-            ...primaryTarget && {
-                target: primaryTarget
-            },
             ...options.transformFiles && {
                 transformFiles: options.transformFiles
             },
@@ -3213,9 +3249,9 @@ if (module.exports && module.exports.__esModule && 'default' in module.exports)
                 });
             }
         }
-        if (publishTargets.length > 1) plugins.push(PublishTargetPlugin({
-            additionalTargets: publishTargets.slice(1),
-            primaryOutdir: external_node_path_resolve(cwd, baseOutputDir),
+        if (hasTargets) plugins.push(PublishTargetPlugin({
+            targets: publishTargets,
+            stagingDir: external_node_path_resolve(cwd, baseOutputDir),
             mode,
             ...userTransform && {
                 transform: userTransform

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@savvy-web/rslib-builder",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "private": false,
   "description": "RSlib-based build system for Node.js libraries with automatic package.json transformation, TypeScript declaration bundling, and multi-target support",
   "keywords": [