@savvy-web/rslib-builder 0.1.1 → 0.2.0

package/index.d.ts

@@ -12,7 +12,7 @@
  * - **Package.json Transformation**: Automatic path updates, PNPM catalog resolution
  * - **TypeScript Declaration Bundling**: Using tsgo and API Extractor
  * - **File Array Generation**: Automatic files array creation for package.json
- * - **API Model Generation**: Optional api.model.json for documentation tooling
+ * - **API Model Generation**: Optional `<packageName>.api.json` for documentation tooling
  *
  * @example
  * Basic usage in rslib.config.ts:
@@ -41,6 +41,7 @@
 
 import type { ConfigParams } from '@rslib/core';
 import type { PackageJson } from 'type-fest';
+import type { PathLike } from 'node:fs';
 import type { RawCopyPattern } from '@rspack/binding';
 import type { RsbuildPlugin } from '@rsbuild/core';
 import type { RslibConfig } from '@rslib/core';
@@ -48,7 +49,7 @@ import type { SourceConfig } from '@rsbuild/core';
 
 /**
  * Options for API model generation.
- * When enabled, generates an api.model.json file using API Extractor.
+ * When enabled, generates an `<unscopedPackageName>.api.json` file using API Extractor.
  *
  * @remarks
  * API models are only generated for the main "index" entry point (the "." export).
@@ -66,15 +67,9 @@ export declare interface ApiModelOptions {
     enabled?: boolean;
     /**
      * Filename for the generated API model file.
-     * @defaultValue "api.model.json"
+     * @defaultValue `<unscopedPackageName>.api.json` (e.g., `rslib-builder.api.json`)
      */
     filename?: string;
-    /**
-     * Whether to add a .npmignore file that excludes the API model file.
-     * This is useful when the API model is for internal tooling only.
-     * @defaultValue true
-     */
-    npmIgnore?: boolean;
     /**
      * Local paths to copy the API model and package.json to.
      * Used for local testing with documentation systems.
@@ -82,7 +77,10 @@ export declare interface ApiModelOptions {
      * @remarks
      * Each path must be a directory. The parent directory must exist,
      * but the final directory will be created if it doesn't exist.
-     * Both api.model.json and the processed package.json will be copied.
+     * Both the API model and the processed package.json will be copied.
+     *
+     * The API model file is emitted to dist but excluded from npm publish
+     * (added as negated pattern `!<filename>` in the `files` array).
      *
      * @example
      * ```typescript
@@ -93,13 +91,38 @@ export declare interface ApiModelOptions {
      * ```
      */
     localPaths?: string[];
+    /**
+     * TSDoc configuration for custom tag definitions.
+     * Passed to API Extractor for documentation processing.
+     *
+     * @remarks
+     * By default, all standard tag groups (core, extended, discretionary) are
+     * enabled. Custom tags defined in `tagDefinitions` are automatically
+     * supported. Use `supportForTags` only to disable specific tags.
+     *
+     * @example
+     * ```typescript
+     * apiModel: {
+     *   enabled: true,
+     *   tsdoc: {
+     *     tagDefinitions: [{ tagName: "@error", syntaxKind: "inline" }]
+     *   }
+     * }
+     * ```
+     */
+    tsdoc?: TsDocOptions;
+    /**
+     * Options for tsdoc-metadata.json generation.
+     * @defaultValue true (enabled when apiModel is enabled)
+     */
+    tsdocMetadata?: TsDocMetadataOptions | boolean;
 }
 
 /**
  * Plugin to read package.json and configure entry points based on exports.
  *
- * @param options - Plugin configuration options
- * @param options.exportsAsIndexes - When true, export paths create index files in nested directories
+ * @param options - Plugin configuration options with properties:
+ *   - `exportsAsIndexes`: When true, export paths create index files in nested directories
  * @public
  */
 export declare const AutoEntryPlugin: (options?: {
@@ -125,7 +148,7 @@ export declare function collectDtsFiles(dir: string, baseDir?: string): Promise<
  * Plugin to generate TypeScript declaration files using tsgo and emit them through Rslib's asset pipeline.
  *
  * @remarks
- * This plugin uses tsgo (@typescript/native-preview) for faster declaration file generation
+ * This plugin uses tsgo (`\@typescript/native-preview`) for faster declaration file generation
  * and integrates with Rslib's build system by emitting generated files as compilation assets.
  *
  * ## Features
@@ -208,7 +231,7 @@ export declare interface DtsPluginOptions {
     /**
      * Packages whose types should be bundled (inlined) into the output .d.ts files.
      * Only applies when bundle is true.
-     * Supports glob patterns (e.g., '@commitlint/*', 'type-fest')
+     * Supports glob patterns (e.g., '\@commitlint/*', 'type-fest')
      * @defaultValue []
      */
     bundledPackages?: string[];
@@ -229,8 +252,10 @@ export declare interface DtsPluginOptions {
     buildTarget?: "dev" | "npm";
     /**
      * Options for API model generation.
-     * When enabled, generates an api.model.json file in the dist directory.
+     * When enabled, generates an `<unscopedPackageName>.api.json` file in the dist directory.
      * Only applies when bundle is true.
+     *
+     * The API model is excluded from npm publish (not added to `files` array).
      */
     apiModel?: ApiModelOptions | boolean;
 }
@@ -251,7 +276,7 @@ export declare function ensureTempDeclarationDir(cwd: string, name: string): Pro
  * TypeScript source files.
  *
  * **Export Path Mapping:**
- * - Converts export keys to entry names (e.g., "./utils" -> "utils")
+ * - Converts export keys to entry names (e.g., "./utils" becomes "utils")
  * - Maps the root export "." to "index" entry
  * - Replaces path separators with hyphens for nested exports (default)
  * - When `exportsAsIndexes` is true, preserves path structure
@@ -414,6 +439,14 @@ export declare function generateTsgoArgs(options: {
  */
 export declare function getTsgoBinPath(): string;
 
+/**
+ * Extracts the unscoped package name from a potentially scoped package name.
+ * @param name - The package name (e.g., `@scope/package` or `package`)
+ * @returns The unscoped name (e.g., `package`)
+ * @internal
+ */
+export declare function getUnscopedPackageName(name: string): string;
+
 /**
  * @public
  * Node library builder class
@@ -499,7 +532,7 @@ export declare interface NodeLibraryBuilderOptions {
      * specify which packages (including transitive dependencies) should have their types bundled.
      * This is particularly useful for ensuring devDependencies are fully inlined without external imports.
      *
-     * Supports minimatch patterns (e.g., '@pnpm/**', 'picocolors')
+     * Supports minimatch patterns (e.g., '\@pnpm/**', 'picocolors')
      *
      * @example
      * ```typescript
@@ -513,10 +546,10 @@ export declare interface NodeLibraryBuilderOptions {
      * Optional callback to transform files after they're built but before the files array is finalized.
      * Useful for copying/renaming files or adding additional files to the build output.
      *
-     * @param context - Transform context containing compilation context and files set
-     * @param context.compilation - Rspack compilation object with assets
-     * @param context.filesArray - Set of files that will be included in package.json files field
-     * @param context.target - Current build target (dev/npm/jsr)
+     * @param context - Transform context with properties:
+     *   - `compilation`: Rspack compilation object with assets
+     *   - `filesArray`: Set of files that will be included in package.json files field
+     *   - `target`: Current build target (dev/npm/jsr)
      *
      * @example
      * ```typescript
@@ -564,13 +597,13 @@ export declare interface NodeLibraryBuilderOptions {
     transform?: TransformPackageJsonFn;
     /**
      * Options for API model generation.
-     * When enabled, generates an api.model.json file in the dist directory.
+     * When enabled, generates an `<unscopedPackageName>.api.json` file in the dist directory.
      * Only applies when target is "npm".
      *
      * @remarks
-     * The generated api.model.json file contains the full API documentation
+     * The generated API model file contains the full API documentation
      * in a machine-readable format for use by documentation generators.
-     * A .npmignore file is also generated to exclude the API model from npm publish.
+     * The file is emitted to dist but excluded from npm publish (added as negated pattern in `files` array).
      *
      * @example
      * ```typescript
@@ -596,7 +629,7 @@ export declare interface NodeLibraryBuilderOptions {
  *
  * @remarks
  * This class consolidates all package.json transformation logic including:
- * - Path transformations (src/ -> dist/, .ts -> .js)
+ * - Path transformations (src/ to dist/, .ts to .js)
  * - Export conditions generation (types, import, require)
  * - Bin field transformations
  * - PNPM catalog and workspace resolution
@@ -673,9 +706,9 @@ export declare class PackageJsonTransformer {
      * Performs the complete package.json transformation.
      *
      * @param packageJson - The source package.json
-     * @param context - Transform context
-     * @param context.isProduction - Whether this is a production build
-     * @param context.customTransform - Optional custom transform function
+     * @param context - Transform context with properties:
+     *   - `isProduction`: Whether this is a production build
+     *   - `customTransform`: Optional custom transform function
      * @returns The transformed package.json
      */
     transform(packageJson: PackageJson, context?: {
@@ -716,7 +749,7 @@ export declare interface PackageJsonTransformOptions {
      */
     processTSExports?: boolean;
     /**
-     * Whether to collapse index files (./foo/index.ts -> ./foo.js).
+     * Whether to collapse index files (./foo/index.ts becomes ./foo.js).
      * This is typically true for bundled builds.
      * @defaultValue false
      */
@@ -809,7 +842,7 @@ export declare class PnpmCatalog {
      * @param dir - The directory containing the package (defaults to cwd)
      * @returns The resolved package.json
      *
-     * @throws {Error} When resolution fails for critical dependencies
+     * @throws When resolution fails for critical dependencies
      */
     resolvePackageJson(packageJson: PackageJson, dir?: string): Promise<PackageJson>;
     /**
@@ -852,4 +885,203 @@ export declare type TransformPackageJsonFn = (context: {
     pkg: PackageJson;
 }) => PackageJson;
 
+/**
+ * Builder for TSDoc configuration files.
+ * Handles tag group expansion, config generation, and file persistence.
+ * @public
+ */
+export declare class TsDocConfigBuilder {
+    /** All available TSDoc tag groups. */
+    static readonly ALL_GROUPS: TsDocTagGroup[];
+    /** Maps group names to TSDoc Standardization enum values. */
+    private static readonly GROUP_TO_STANDARDIZATION;
+    /**
+     * Standard TSDoc tag definitions organized by standardization group.
+     * Lazily computed from `\@microsoft/tsdoc` StandardTags.
+     */
+    static readonly TAG_GROUPS: Record<TsDocTagGroup, TsDocTagDefinition[]>;
+    /**
+     * Detects if running in a CI environment.
+     * @returns true if CI or GITHUB_ACTIONS environment variable is "true"
+     */
+    static isCI(): boolean;
+    /**
+     * Gets standard TSDoc tag definitions for a specific group.
+     * Uses StandardTags from `\@microsoft/tsdoc` package.
+     */
+    static getTagsForGroup(group: TsDocTagGroup): TsDocTagDefinition[];
+    /**
+     * Determines if the TSDoc config should be persisted to disk.
+     * @param persistConfig - The persistConfig option value
+     * @returns true if the config should be persisted
+     */
+    static shouldPersist(persistConfig: boolean | PathLike | undefined): boolean;
+    /**
+     * Gets the output path for the tsdoc.json file.
+     * @param persistConfig - The persistConfig option value
+     * @param cwd - The current working directory
+     * @returns The absolute path where tsdoc.json should be written
+     */
+    static getConfigPath(persistConfig: boolean | PathLike | undefined, cwd: string): string;
+    /**
+     * Builds the complete TSDoc configuration from options.
+     *
+     * @remarks
+     * When all groups are enabled (default), returns `useStandardTags: true` to signal
+     * that the generated config should use `noStandardTags: false` and let TSDoc
+     * automatically load all standard tags. However, `supportForTags` is still populated
+     * because API Extractor requires explicit support declarations for each tag.
+     *
+     * When a subset of groups is specified, returns `useStandardTags: false` to signal
+     * that we must explicitly define which tags to include via `noStandardTags: true`.
+     */
+    static build(options?: TsDocOptions): {
+        tagDefinitions: TsDocTagDefinition[];
+        supportForTags: Record<string, boolean>;
+        useStandardTags: boolean;
+    };
+    /**
+     * Generates a tsdoc.json file from options.
+     *
+     * @remarks
+     * When all groups are enabled (default), generates a minimal config with
+     * `noStandardTags: false` so TSDoc automatically loads all standard tags.
+     * Only custom tags need to be defined in this case.
+     *
+     * When a subset of groups is specified, generates a config with
+     * `noStandardTags: true` and explicitly defines only the tags from
+     * the enabled groups.
+     */
+    static writeConfigFile(options: TsDocOptions | undefined, outputDir: string): Promise<string>;
+    /** Converts TSDocTagSyntaxKind enum to string format. */
+    private static syntaxKindToString;
+}
+
+/**
+ * Options for tsdoc-metadata.json generation.
+ * @public
+ */
+export declare interface TsDocMetadataOptions {
+    /**
+     * Whether to generate tsdoc-metadata.json.
+     * @defaultValue true (when apiModel is enabled)
+     */
+    enabled?: boolean;
+    /**
+     * Custom filename for the TSDoc metadata file.
+     * @defaultValue "tsdoc-metadata.json"
+     */
+    filename?: string;
+}
+
+/**
+ * TSDoc configuration options for API Extractor.
+ * @remarks
+ * Provides ergonomic defaults - standard tags are auto-enabled via `groups`,
+ * custom tags are auto-supported, and `supportForTags` is only needed to
+ * disable specific tags.
+ *
+ * **Config optimization:** When all groups are enabled (default), the generated
+ * `tsdoc.json` uses `noStandardTags: false` to let TSDoc automatically load
+ * all standard tags, producing a minimal config file. When a subset of groups
+ * is specified, `noStandardTags: true` is used and only the enabled groups'
+ * tags are explicitly defined.
+ *
+ * @public
+ */
+export declare interface TsDocOptions {
+    /**
+     * TSDoc tag groups to enable. Each group includes predefined standard tags
+     * from the official `\@microsoft/tsdoc` package.
+     * - "core": Essential TSDoc tags (\@param, \@returns, \@remarks, \@deprecated, etc.)
+     * - "extended": Additional tags (\@example, \@defaultValue, \@see, \@throws, etc.)
+     * - "discretionary": Release stage tags (\@alpha, \@beta, \@public, \@internal)
+     *
+     * @remarks
+     * When all groups are enabled (the default), the generated config uses
+     * `noStandardTags: false` and TSDoc loads standard tags automatically.
+     * When a subset is specified, `noStandardTags: true` is used and only
+     * the tags from enabled groups are defined.
+     *
+     * @defaultValue ["core", "extended", "discretionary"]
+     */
+    groups?: TsDocTagGroup[];
+    /**
+     * Custom TSDoc tag definitions beyond the standard groups.
+     * These are automatically added to supportForTags (no need to declare twice).
+     *
+     * @example
+     * ```typescript
+     * tagDefinitions: [
+     *   { tagName: "@error", syntaxKind: "inline" },
+     *   { tagName: "@category", syntaxKind: "block", allowMultiple: false }
+     * ]
+     * ```
+     */
+    tagDefinitions?: TsDocTagDefinition[];
+    /**
+     * Override support for specific tags. Only needed to DISABLE tags.
+     * Tags from enabled groups and custom tagDefinitions are auto-supported.
+     *
+     * @example
+     * ```typescript
+     * // Disable @beta even though "extended" group is enabled
+     * supportForTags: { "@beta": false }
+     * ```
+     */
+    supportForTags?: Record<string, boolean>;
+    /**
+     * Persist tsdoc.json to disk for tool integration (ESLint, IDEs).
+     * - `true`: Write to project root as "tsdoc.json"
+     * - `PathLike`: Write to specified path
+     * - `false`: Clean up after API Extractor
+     *
+     * @defaultValue `true` when `CI` and `GITHUB_ACTIONS` env vars are not "true",
+     *               `false` otherwise (CI environments)
+     */
+    persistConfig?: boolean | PathLike;
+    /**
+     * How to handle TSDoc validation warnings from API Extractor.
+     * - `"log"`: Show warnings in the console but continue the build
+     * - `"fail"`: Show warnings and fail the build if any are found
+     * - `"none"`: Suppress TSDoc warnings entirely
+     *
+     * @remarks
+     * TSDoc warnings include unknown tags, malformed syntax, and other
+     * documentation issues detected by API Extractor during processing.
+     *
+     * @example
+     * ```typescript
+     * // Fail build on any TSDoc issues (CI default)
+     * warnings: "fail"
+     *
+     * // Show warnings but continue build (local default)
+     * warnings: "log"
+     * ```
+     *
+     * @defaultValue `"fail"` in CI environments (`CI` or `GITHUB_ACTIONS` env vars),
+     *               `"log"` otherwise
+     */
+    warnings?: "log" | "fail" | "none";
+}
+
+/**
+ * TSDoc tag definition for custom documentation tags.
+ * @public
+ */
+export declare interface TsDocTagDefinition {
+    /** The tag name including the at-sign prefix (e.g., `\@error`, `\@category`) */
+    tagName: string;
+    /** How the tag is parsed: "block" | "inline" | "modifier" */
+    syntaxKind: "block" | "inline" | "modifier";
+    /** Whether the tag can appear multiple times on a declaration */
+    allowMultiple?: boolean;
+}
+
+/**
+ * TSDoc standardization groups for predefined tag sets.
+ * @public
+ */
+export declare type TsDocTagGroup = "core" | "extended" | "discretionary";
+
 export { }