@savvy-web/rslib-builder 0.5.0 → 0.6.0

package/index.d.ts

@@ -119,6 +119,18 @@ export declare interface ApiModelOptions {
      * @defaultValue true (enabled when apiModel is enabled)
      */
     tsdocMetadata?: TsDocMetadataOptions | boolean;
+    /**
+     * Controls handling of API Extractor's "forgotten export" messages.
+     * A forgotten export occurs when a public API references a declaration
+     * that isn't exported from the entry point.
+     *
+     * - `"include"` (default): Log a warning, include in the API model
+     * - `"error"`: Fail the build with details about the forgotten exports
+     * - `"ignore"`: Turn off detection — suppress all messages
+     *
+     * @defaultValue "include"
+     */
+    forgottenExports?: "include" | "error" | "ignore";
 }
 
 /**
@@ -934,7 +946,7 @@ export declare type JsonValue = JsonPrimitive | JsonObject | JsonArray;
  *
  * @public
  */
-declare type LiteralUnion<LiteralType, BaseType extends Primitive> = LiteralType | (BaseType & Record<never, never>);
+export declare type LiteralUnion<LiteralType, BaseType extends Primitive> = LiteralType | (BaseType & Record<never, never>);
 
 /**
  * Builder for Node.js ESM libraries using RSlib.
@@ -1797,13 +1809,13 @@ export declare interface PackageJsonTransformPluginOptions {
  *
  * @public
  */
-declare type Primitive = null | undefined | string | number | boolean | symbol | bigint;
+export declare type Primitive = null | undefined | string | number | boolean | symbol | bigint;
 
 /**
  * Async RSLib configuration function type.
  * @public
  */
-declare type RslibConfigAsyncFn = (env: ConfigParams) => Promise<RslibConfig>;
+export declare type RslibConfigAsyncFn = (env: ConfigParams) => Promise<RslibConfig>;
 
 /**
  * Function to transform package.json during the build process.

package/index.js

@@ -528,6 +528,7 @@ async function bundleDtsFiles(options) {
     const tsdocOptions = "object" == typeof apiModel ? apiModel.tsdoc : void 0;
     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) ?? "include";
     const tsdocMetadataEnabled = apiModelEnabled && (void 0 === tsdocMetadataOption || true === tsdocMetadataOption || "object" == typeof tsdocMetadataOption && false !== tsdocMetadataOption.enabled);
     const tsdocMetadataFilename = "object" == typeof tsdocMetadataOption && tsdocMetadataOption.filename ? tsdocMetadataOption.filename : "tsdoc-metadata.json";
     getApiExtractorPath();
@@ -568,6 +569,7 @@ async function bundleDtsFiles(options) {
             configObject: {
                 projectFolder: cwd,
                 mainEntryPointFilePath: tempDtsPath,
+                enumMemberOrder: "preserve",
                 compiler: {
                     tsconfigFilePath: tsconfigPath
                 },
@@ -590,6 +592,7 @@ async function bundleDtsFiles(options) {
             tsdocConfigFile: tsdocConfigFile
         });
         const collectedTsdocWarnings = [];
+        const collectedForgottenExports = [];
         const extractorResult = Extractor.invoke(extractorConfig, {
             localBuild: true,
             showVerboseMessages: false,
@@ -613,17 +616,27 @@ async function bundleDtsFiles(options) {
                     });
                     message.logLevel = "none";
                 }
+                if ("ae-forgotten-export" === message.messageId && message.text) if ("ignore" === forgottenExports) message.logLevel = "none";
+                else {
+                    collectedForgottenExports.push({
+                        text: message.text,
+                        sourceFilePath: message.sourceFilePath,
+                        sourceFileLine: message.sourceFileLine,
+                        sourceFileColumn: message.sourceFileColumn
+                    });
+                    message.logLevel = "none";
+                }
             }
         });
         if (!extractorResult.succeeded) throw new Error(`API Extractor failed for entry "${entryName}"`);
+        const formatWarning = (warning)=>{
+            const location = warning.sourceFilePath ? `${picocolors.cyan((0, external_node_path_.relative)(cwd, warning.sourceFilePath))}${warning.sourceFileLine ? `:${warning.sourceFileLine}` : ""}${warning.sourceFileColumn ? `:${warning.sourceFileColumn}` : ""}` : null;
+            return location ? `${location}: ${picocolors.yellow(warning.text)}` : picocolors.yellow(warning.text);
+        };
         if (collectedTsdocWarnings.length > 0) {
             const isThirdParty = (warning)=>warning.sourceFilePath?.includes("node_modules/") ?? false;
             const firstPartyWarnings = collectedTsdocWarnings.filter((w)=>!isThirdParty(w));
             const thirdPartyWarnings = collectedTsdocWarnings.filter(isThirdParty);
-            const formatWarning = (warning)=>{
-                const location = warning.sourceFilePath ? `${picocolors.cyan((0, external_node_path_.relative)(cwd, warning.sourceFilePath))}${warning.sourceFileLine ? `:${warning.sourceFileLine}` : ""}${warning.sourceFileColumn ? `:${warning.sourceFileColumn}` : ""}` : null;
-                return location ? `${location}: ${picocolors.yellow(warning.text)}` : picocolors.yellow(warning.text);
-            };
             if (thirdPartyWarnings.length > 0) {
                 const thirdPartyMessages = thirdPartyWarnings.map(formatWarning).join("\n  ");
                 core_logger.warn(`TSDoc warnings from dependencies for entry "${entryName}" (cannot be fixed, bundled types may have documentation issues):\n  ${thirdPartyMessages}`);
@@ -634,6 +647,11 @@ async function bundleDtsFiles(options) {
                 if ("log" === tsdocWarnings) core_logger.warn(`TSDoc warnings for entry "${entryName}":\n  ${firstPartyMessages}`);
             }
         }
+        if (collectedForgottenExports.length > 0) {
+            const forgottenMessages = collectedForgottenExports.map(formatWarning).join("\n  ");
+            if ("error" === forgottenExports) throw new Error(`Forgotten exports detected for entry "${entryName}":\n  ${forgottenMessages}`);
+            if ("include" === forgottenExports) core_logger.warn(`Forgotten exports for entry "${entryName}":\n  ${forgottenMessages}`);
+        }
         if (generateApiModel && tempApiModelPath) apiModelPath = tempApiModelPath;
         if (generateTsdocMetadata && tempTsdocMetadataPath) tsdocMetadataPath = tempTsdocMetadataPath;
         if (banner || footer) {
@@ -885,7 +903,7 @@ function runTsgo(options) {
                             if (apiModelPath) {
                                 const defaultApiModelFilename = packageJson.name ? `${getUnscopedPackageName(packageJson.name)}.api.json` : "api.json";
                                 const apiModelFilename = "object" == typeof options.apiModel && options.apiModel.filename ? options.apiModel.filename : defaultApiModelFilename;
-                                const apiModelContent = await readFile(apiModelPath, "utf-8");
+                                const apiModelContent = (await readFile(apiModelPath, "utf-8")).replaceAll("\r\n", "\n");
                                 const apiModelSource = new context.sources.OriginalSource(apiModelContent, apiModelFilename);
                                 context.compilation.emitAsset(apiModelFilename, apiModelSource);
                                 if (filesArray) filesArray.add(`!${apiModelFilename}`);
@@ -908,14 +926,14 @@ function runTsgo(options) {
                             if (tsdocMetadataPath) {
                                 const tsdocMetadataOption = "object" == typeof options.apiModel ? options.apiModel.tsdocMetadata : void 0;
                                 const tsdocMetadataFilename = "object" == typeof tsdocMetadataOption && tsdocMetadataOption.filename ? tsdocMetadataOption.filename : "tsdoc-metadata.json";
-                                const tsdocMetadataContent = await readFile(tsdocMetadataPath, "utf-8");
+                                const tsdocMetadataContent = (await readFile(tsdocMetadataPath, "utf-8")).replaceAll("\r\n", "\n");
                                 const tsdocMetadataSource = new context.sources.OriginalSource(tsdocMetadataContent, tsdocMetadataFilename);
                                 context.compilation.emitAsset(tsdocMetadataFilename, tsdocMetadataSource);
                                 if (filesArray) filesArray.add(tsdocMetadataFilename);
                                 core_logger.info(`${picocolors.dim(`[${envId}]`)} Emitted TSDoc metadata: ${tsdocMetadataFilename}`);
                             }
                             if (tsdocConfigPath) {
-                                const tsdocConfigContent = await readFile(tsdocConfigPath, "utf-8");
+                                const tsdocConfigContent = (await readFile(tsdocConfigPath, "utf-8")).replaceAll("\r\n", "\n");
                                 const tsdocConfigSource = new context.sources.OriginalSource(tsdocConfigContent, "tsdoc.json");
                                 context.compilation.emitAsset("tsdoc.json", tsdocConfigSource);
                                 if (filesArray) filesArray.add("!tsdoc.json");

package/package.json

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

package/tsdoc-metadata.json

@@ -1,11 +1,11 @@
-// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
-// It should be published with your NPM package.  It should not be tracked by Git.
-{
-  "tsdocVersion": "0.12",
-  "toolPackages": [
-    {
-      "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.55.2"
-    }
-  ]
-}
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.55.2"
+    }
+  ]
+}