@savvy-web/rslib-builder 0.3.0 → 0.4.0

package/README.md

@@ -4,9 +4,14 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D24.0.0-brightgreen)](https://nodejs.org)
 
-Build modern ESM Node.js libraries with zero configuration. Handles TypeScript
-declarations, package.json transformations, and PNPM workspace resolution
-automatically.
+Build modern ESM Node.js libraries with minimal configuration. Handles
+TypeScript declarations, package.json transformations, and PNPM workspace
+resolution automatically.
+
+Building TypeScript packages for npm involves repetitive setup: configuring
+bundlers, generating declarations, transforming package.json exports, and
+resolving workspace references. rslib-builder handles these tasks so you can
+focus on your code.
 
 ## Features
 
@@ -19,8 +24,10 @@ automatically.
   outputs
 - **PNPM Integration** - Automatically resolves `catalog:` and `workspace:`
   references
-- **Package.json Transform** - Converts `.ts` exports and bin entries to `.js`,
-  generates files array, removes dev-only fields
+- **Package.json Transform** - Converts `.ts` exports to `.js`, generates files
+  array, removes dev-only fields
+- **TSDoc Validation** - Pre-build TSDoc validation with automatic public API discovery
+- **API Model Generation** - Optional API model output for documentation tooling
 - **Extensible** - Add custom RSlib/Rsbuild plugins for advanced use cases
 
 ## Prerequisites
@@ -43,6 +50,12 @@ Install the required peer dependencies:
 pnpm add -D @rslib/core @microsoft/api-extractor @typescript/native-preview
 ```
 
+For TSDoc validation (optional):
+
+```bash
+pnpm add -D eslint @typescript-eslint/parser eslint-plugin-tsdoc
+```
+
 ## Quick Start
 
 Extend the provided tsconfig for optimal settings:
@@ -96,16 +109,32 @@ rslib build --env-mode dev
 rslib build --env-mode npm
 ```
 
+## API Overview
+
+The package exports a main builder and several plugins:
+
+| Export                       | Description                                   |
+| ---------------------------- | --------------------------------------------- |
+| `NodeLibraryBuilder`         | Main API for building Node.js libraries       |
+| `AutoEntryPlugin`            | Auto-extracts entry points from package.json  |
+| `DtsPlugin`                  | Generates TypeScript declarations with tsgo   |
+| `PackageJsonTransformPlugin` | Transforms package.json for distribution      |
+| `FilesArrayPlugin`           | Generates files array for npm publishing      |
+| `TsDocLintPlugin`            | Validates TSDoc comments before build         |
+| `TsDocConfigBuilder`         | Utility for TSDoc configuration               |
+| `ImportGraph`                | Traces TypeScript imports for file discovery  |
+
 See [Configuration](./docs/guides/configuration.md) for all options.
 
 ## Plugins
 
 The builder includes several built-in plugins:
 
-1. **AutoEntryPlugin** - Auto-extracts entry points from package.json exports
-2. **PackageJsonTransformPlugin** - Transforms package.json for targets
+1. **TsDocLintPlugin** - Validates TSDoc comments before build (optional)
+2. **AutoEntryPlugin** - Auto-extracts entry points from package.json exports
 3. **DtsPlugin** - Generates TypeScript declarations with tsgo/API Extractor
-4. **FilesArrayPlugin** - Generates files array, excludes source maps
+4. **PackageJsonTransformPlugin** - Transforms package.json for targets
+5. **FilesArrayPlugin** - Generates files array, excludes source maps
 
 ## How It Works
 
@@ -131,8 +160,31 @@ For detailed documentation, see the [docs/](./docs/) directory:
 
 ## Examples
 
-See the repository's own `rslib.config.ts` for a real-world example of the
-builder building itself.
+This package builds itself using its own `NodeLibraryBuilder`. See
+[`rslib.config.ts`](./rslib.config.ts) for a production example demonstrating:
+
+- API model generation for documentation tooling
+- External package configuration
+- Custom package.json transformations
+- Copy patterns for static files
+
+### Programmatic Usage
+
+Use `ImportGraph` to discover all files reachable from your package exports:
+
+```typescript
+import { ImportGraph } from '@savvy-web/rslib-builder';
+
+const result = ImportGraph.fromPackageExports('./package.json', {
+  rootDir: process.cwd(),
+});
+
+console.log('Public API files:', result.files);
+console.log('Entry points:', result.entries);
+```
+
+See [Configuration](./docs/guides/configuration.md#importgraph-utility) for more
+examples.
 
 ## Support
 
@@ -142,19 +194,19 @@ GitHub Issues, we cannot guarantee response times or resolution.
 
 For security vulnerabilities, please see [SECURITY.md](./SECURITY.md).
 
-## License
+## Links
 
-[MIT](./LICENSE)
+- [RSlib Documentation](https://rslib.dev/)
+- [Rsbuild Plugin API](https://rsbuild.dev/plugins/dev/core)
+- [API Extractor](https://api-extractor.com/)
+- [PNPM Workspace](https://pnpm.io/workspaces)
+- [PNPM Catalogs](https://pnpm.io/catalogs)
 
 ## Contributing
 
 Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup
 and guidelines.
 
-## Links
+## License
 
-- [RSlib Documentation](https://rslib.dev/)
-- [Rsbuild Plugin API](https://rsbuild.dev/plugins/dev/core)
-- [API Extractor](https://api-extractor.com/)
-- [PNPM Workspace](https://pnpm.io/workspaces)
-- [PNPM Catalogs](https://pnpm.io/catalogs)
+[MIT](./LICENSE)

package/index.d.ts

@@ -46,6 +46,7 @@ import type { RawCopyPattern } from '@rspack/binding';
 import type { RsbuildPlugin } from '@rsbuild/core';
 import type { RslibConfig } from '@rslib/core';
 import type { SourceConfig } from '@rsbuild/core';
+import ts from 'typescript';
 
 /**
  * Options for API model generation.
@@ -458,6 +459,374 @@ export declare interface FilesArrayPluginOptions<TTarget extends string = string
     target: TTarget;
 }
 
+/**
+ * Analyzes TypeScript import relationships to discover all files
+ * reachable from specified entry points.
+ *
+ * @remarks
+ * This class uses the TypeScript compiler API to trace import statements
+ * and discover all files that are part of the public API. It handles:
+ *
+ * - Static imports: `import { foo } from "./module"`
+ * - Dynamic imports: `import("./module")`
+ * - Re-exports: `export * from "./module"` and `export { foo } from "./module"`
+ * - Circular imports (via visited set tracking)
+ *
+ * The class automatically filters out:
+ * - Files in node_modules
+ * - Declaration files (.d.ts)
+ * - Test files (*.test.ts, *.spec.ts)
+ * - Files in __test__ directories
+ *
+ * ## Static Methods vs Instance Methods
+ *
+ * For simple one-off analysis, use the static convenience methods:
+ * - {@link ImportGraph.fromEntries} - Trace from explicit entry paths
+ * - {@link ImportGraph.fromPackageExports} - Trace from package.json exports
+ *
+ * For repeated analysis or custom configuration, create an instance
+ * and use the instance methods which reuse the TypeScript program.
+ *
+ * @example
+ * Using static methods (recommended for most cases):
+ * ```typescript
+ * import { ImportGraph } from '@savvy-web/rslib-builder';
+ *
+ * // Trace from explicit entries
+ * const result = ImportGraph.fromEntries(
+ *   ['./src/index.ts', './src/cli.ts'],
+ *   { rootDir: process.cwd() }
+ * );
+ *
+ * // Trace from package.json exports
+ * const result = ImportGraph.fromPackageExports(
+ *   './package.json',
+ *   { rootDir: process.cwd() }
+ * );
+ * ```
+ *
+ * @example
+ * Using instance methods (for repeated analysis):
+ * ```typescript
+ * import { ImportGraph } from '@savvy-web/rslib-builder';
+ *
+ * const graph = new ImportGraph({ rootDir: '/path/to/project' });
+ *
+ * // Reuses the TypeScript program across multiple calls
+ * const libResult = graph.traceFromEntries(['./src/index.ts']);
+ * const cliResult = graph.traceFromEntries(['./src/cli.ts']);
+ * ```
+ *
+ * @public
+ */
+export declare class ImportGraph {
+    private readonly options;
+    private readonly sys;
+    private program;
+    private compilerOptions;
+    private moduleResolutionCache;
+    constructor(options: ImportGraphOptions);
+    /**
+     * Trace all imports from the given entry points.
+     *
+     * @param entryPaths - Paths to entry files (relative to rootDir or absolute)
+     * @returns Deduplicated list of all reachable TypeScript files
+     */
+    traceFromEntries(entryPaths: string[]): ImportGraphResult;
+    /**
+     * Trace imports from package.json exports.
+     *
+     * @remarks
+     * Convenience method that extracts entry points from package.json
+     * using EntryExtractor, then traces all imports from those entries.
+     *
+     * @param packageJsonPath - Path to package.json (relative to rootDir or absolute)
+     * @returns Deduplicated list of all reachable TypeScript files
+     */
+    traceFromPackageExports(packageJsonPath: string): ImportGraphResult;
+    /**
+     * Initialize the TypeScript program for module resolution.
+     */
+    private initializeProgram;
+    /**
+     * Find tsconfig.json path.
+     */
+    private findTsConfig;
+    /**
+     * Resolve entry path to absolute path.
+     */
+    private resolveEntryPath;
+    /**
+     * Recursively trace imports from a source file.
+     */
+    private traceImports;
+    /**
+     * Extract all import/export module specifiers from a source file.
+     */
+    private extractImports;
+    /**
+     * Resolve a module specifier to an absolute file path.
+     */
+    private resolveImport;
+    /**
+     * Check if a path is an external module (node_modules).
+     */
+    private isExternalModule;
+    /**
+     * Check if a file should be included in results.
+     * Filters out test files and non-TypeScript files.
+     */
+    private isSourceFile;
+    /**
+     * Traces TypeScript imports from entry points.
+     *
+     * @remarks
+     * Static convenience method that creates an ImportGraph instance
+     * and traces imports in one call. For repeated analysis where you want
+     * to reuse the TypeScript program, create an instance and use
+     * {@link ImportGraph.traceFromEntries} instead.
+     *
+     * @param entryPaths - Paths to entry files (relative to rootDir or absolute)
+     * @param options - Import graph configuration options
+     * @returns All TypeScript files reachable from the entries
+     *
+     * @example
+     * ```typescript
+     * import { ImportGraph } from '@savvy-web/rslib-builder';
+     *
+     * const result = ImportGraph.fromEntries(
+     *   ['./src/index.ts', './src/cli.ts'],
+     *   { rootDir: process.cwd() }
+     * );
+     * console.log('Found files:', result.files);
+     * ```
+     */
+    static fromEntries(entryPaths: string[], options: ImportGraphOptions): ImportGraphResult;
+    /**
+     * Traces TypeScript imports from package.json exports.
+     *
+     * @remarks
+     * Static convenience method that extracts entry points from package.json exports
+     * and traces all imports to find public API files. For repeated analysis,
+     * create an instance and use {@link ImportGraph.traceFromPackageExports} instead.
+     *
+     * @param packageJsonPath - Path to package.json (relative to rootDir or absolute)
+     * @param options - Import graph configuration options
+     * @returns All TypeScript files reachable from the package exports
+     *
+     * @example
+     * ```typescript
+     * import { ImportGraph } from '@savvy-web/rslib-builder';
+     *
+     * const result = ImportGraph.fromPackageExports(
+     *   './package.json',
+     *   { rootDir: process.cwd() }
+     * );
+     * console.log('Public API files:', result.files);
+     * ```
+     */
+    static fromPackageExports(packageJsonPath: string, options: ImportGraphOptions): ImportGraphResult;
+}
+
+/**
+ * Structured error from import graph analysis.
+ *
+ * @remarks
+ * Provides detailed error information including the error type for
+ * programmatic handling, a human-readable message, and the relevant
+ * file path when applicable.
+ *
+ * @example
+ * ```typescript
+ * import type { ImportGraphError } from '@savvy-web/rslib-builder';
+ *
+ * function handleErrors(errors: ImportGraphError[]): void {
+ *   for (const error of errors) {
+ *     switch (error.type) {
+ *       case 'tsconfig_not_found':
+ *         console.warn('No tsconfig.json found, using defaults');
+ *         break;
+ *       case 'entry_not_found':
+ *         console.error(`Missing entry: ${error.path}`);
+ *         break;
+ *       default:
+ *         console.error(error.message);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare interface ImportGraphError {
+    /**
+     * The type of error that occurred.
+     *
+     * @remarks
+     * Use this field for programmatic error handling to distinguish
+     * between different failure modes.
+     */
+    type: ImportGraphErrorType;
+    /**
+     * Human-readable error message.
+     *
+     * @remarks
+     * Suitable for logging or displaying to users.
+     */
+    message: string;
+    /**
+     * The file path related to the error, if applicable.
+     *
+     * @remarks
+     * Present for errors related to specific files like missing entries
+     * or file read failures.
+     */
+    path?: string;
+}
+
+/**
+ * Types of errors that can occur during import graph analysis.
+ *
+ * @remarks
+ * These error types allow consumers to handle different failure modes
+ * appropriately. For example, a missing tsconfig might be handled differently
+ * than a missing entry file.
+ *
+ * @public
+ */
+export declare type ImportGraphErrorType = "tsconfig_not_found" | "tsconfig_read_error" | "tsconfig_parse_error" | "package_json_not_found" | "package_json_parse_error" | "entry_not_found" | "file_read_error";
+
+/**
+ * Options for configuring the ImportGraph analyzer.
+ *
+ * @remarks
+ * These options control how the ImportGraph traverses and resolves
+ * TypeScript module imports. The `rootDir` is required and serves as
+ * the base for resolving relative paths and finding the tsconfig.json.
+ *
+ * @example
+ * ```typescript
+ * import type { ImportGraphOptions } from '@savvy-web/rslib-builder';
+ *
+ * const options: ImportGraphOptions = {
+ *   rootDir: '/path/to/project',
+ *   tsconfigPath: './tsconfig.build.json',
+ * };
+ * ```
+ *
+ * @public
+ */
+export declare interface ImportGraphOptions {
+    /**
+     * The project root directory.
+     *
+     * @remarks
+     * All relative paths (entry points, tsconfig path) are resolved from this directory.
+     * This should typically be the package root containing your `package.json`.
+     */
+    rootDir: string;
+    /**
+     * Custom path to the TypeScript configuration file.
+     *
+     * @remarks
+     * If not provided, the analyzer searches for `tsconfig.json` starting from `rootDir`
+     * and walking up the directory tree. The tsconfig is used for module resolution
+     * settings including path aliases and module resolution strategy.
+     *
+     * @defaultValue Searches for tsconfig.json from rootDir
+     */
+    tsconfigPath?: string;
+    /**
+     * Custom TypeScript system for file operations.
+     *
+     * @remarks
+     * This is primarily used for testing to provide a mock filesystem.
+     * In production use, this defaults to `ts.sys` which uses the real filesystem.
+     *
+     * @defaultValue ts.sys
+     * @internal
+     */
+    sys?: ts.System;
+    /**
+     * Additional patterns to exclude from results.
+     *
+     * @remarks
+     * Patterns are matched against file paths using simple string inclusion.
+     * Use this to exclude files that don't match the default test file patterns.
+     *
+     * The default exclusions are always applied:
+     * - `.test.` and `.spec.` files
+     * - `__test__` and `__tests__` directories
+     * - `.d.ts` declaration files
+     *
+     * @example
+     * ```typescript
+     * const graph = new ImportGraph({
+     *   rootDir: process.cwd(),
+     *   excludePatterns: ['/fixtures/', '/mocks/', '.stories.'],
+     * });
+     * ```
+     *
+     * @defaultValue []
+     */
+    excludePatterns?: string[];
+}
+
+/**
+ * Result of import graph analysis.
+ *
+ * @remarks
+ * Contains the complete set of TypeScript source files discovered by tracing
+ * imports from entry points. The analysis is non-fatal: errors are collected
+ * and tracing continues for other paths even when some imports fail to resolve.
+ *
+ * @example
+ * ```typescript
+ * import type { ImportGraphResult } from '@savvy-web/rslib-builder';
+ *
+ * function processResult(result: ImportGraphResult): void {
+ *   if (result.errors.length > 0) {
+ *     console.warn('Some imports could not be resolved:', result.errors);
+ *   }
+ *   console.log(`Found ${result.files.length} files from ${result.entries.length} entries`);
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare interface ImportGraphResult {
+    /**
+     * All TypeScript source files reachable from the entry points.
+     *
+     * @remarks
+     * Paths are absolute, normalized, and sorted alphabetically.
+     * Test files (`.test.ts`, `.spec.ts`) and test directories (`__test__`, `__tests__`)
+     * are automatically filtered out from results.
+     */
+    files: string[];
+    /**
+     * The entry points that were traced.
+     *
+     * @remarks
+     * Paths are absolute and normalized. These are the starting points
+     * from which the import graph was traversed.
+     */
+    entries: string[];
+    /**
+     * Errors encountered during import graph analysis.
+     *
+     * @remarks
+     * These errors are non-fatal: tracing continues despite individual failures.
+     * Common errors include missing entry files, unresolvable imports,
+     * or tsconfig parsing failures.
+     *
+     * Each error includes a `type` field for programmatic handling and
+     * a human-readable `message`. Some errors also include a `path` field
+     * indicating the relevant file.
+     */
+    errors: ImportGraphError[];
+}
+
 /**
  * Builder for Node.js ESM libraries using RSlib.
  *
@@ -696,6 +1065,42 @@ export declare interface NodeLibraryBuilderOptions {
      * ```
      */
     apiModel?: ApiModelOptions | boolean;
+    /**
+     * Options for TSDoc lint validation.
+     * When enabled, validates TSDoc comments before the build starts.
+     *
+     * @remarks
+     * Uses ESLint with `eslint-plugin-tsdoc` to validate TSDoc syntax.
+     * By default, throws errors in CI environments and logs errors locally.
+     * The generated `tsdoc.json` config is persisted locally for IDE integration.
+     *
+     * @example
+     * Enable with defaults (throws in CI, errors locally):
+     * ```typescript
+     * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
+     *
+     * export default NodeLibraryBuilder.create({
+     *   tsdocLint: true,
+     * });
+     * ```
+     *
+     * @example
+     * Enable with custom configuration:
+     * ```typescript
+     * import { NodeLibraryBuilder } from '@savvy-web/rslib-builder';
+     *
+     * export default NodeLibraryBuilder.create({
+     *   tsdocLint: {
+     *     tsdoc: {
+     *       tagDefinitions: [{ tagName: '@error', syntaxKind: 'block' }],
+     *     },
+     *     onError: 'throw',
+     *     persistConfig: true,
+     *   },
+     * });
+     * ```
+     */
+    tsdocLint?: TsDocLintPluginOptions | boolean;
 }
 
 /**
@@ -1001,6 +1406,168 @@ export declare class TsDocConfigBuilder {
     private static syntaxKindToString;
 }
 
+/**
+ * Error behavior for TSDoc lint errors.
+ *
+ * @remarks
+ * - `"warn"`: Log warnings but continue the build
+ * - `"error"`: Log errors but continue the build
+ * - `"throw"`: Fail the build with an error
+ *
+ * @public
+ */
+export declare type TsDocLintErrorBehavior = "warn" | "error" | "throw";
+
+/**
+ * Creates a plugin to validate TSDoc comments before build using ESLint with eslint-plugin-tsdoc.
+ *
+ * @remarks
+ * This plugin runs TSDoc validation during the `onBeforeBuild` hook, ensuring that
+ * documentation errors are caught before compilation begins. It generates a virtual
+ * `tsdoc.json` configuration file that can be persisted for IDE and tool integration.
+ *
+ * ## Features
+ *
+ * - Programmatic ESLint execution with `eslint-plugin-tsdoc`
+ * - Configurable error handling (warn, error, throw)
+ * - Automatic CI detection for stricter defaults
+ * - Optional tsdoc.json persistence for tool integration
+ * - Automatic file discovery via import graph analysis
+ * - Customizable file patterns when needed
+ *
+ * ## Error Handling
+ *
+ * | Environment | Default Behavior | On Lint Errors |
+ * |-------------|------------------|----------------|
+ * | Local       | `"error"`        | Log and continue |
+ * | CI          | `"throw"`        | Fail the build |
+ *
+ * ## Required Dependencies
+ *
+ * This plugin requires the following optional peer dependencies:
+ * - `eslint`
+ * - `@typescript-eslint/parser`
+ * - `eslint-plugin-tsdoc`
+ *
+ * Install with: `pnpm add -D eslint @typescript-eslint/parser eslint-plugin-tsdoc`
+ *
+ * @param options - Plugin configuration options
+ * @returns An Rsbuild plugin that validates TSDoc comments before the build
+ *
+ * @example
+ * ```typescript
+ * import { TsDocLintPlugin } from '@savvy-web/rslib-builder';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     TsDocLintPlugin({
+ *       onError: 'throw',
+ *       persistConfig: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare const TsDocLintPlugin: (options?: TsDocLintPluginOptions) => RsbuildPlugin;
+
+/**
+ * Options for the TSDoc lint plugin.
+ *
+ * @remarks
+ * This plugin validates TSDoc comments in your source files before the build
+ * starts using ESLint with `eslint-plugin-tsdoc`. It helps catch documentation
+ * errors early in the development cycle.
+ *
+ * @example
+ * Enable with defaults (throws in CI, errors locally):
+ * ```typescript
+ * import { TsDocLintPlugin } from '@savvy-web/rslib-builder';
+ *
+ * export default defineConfig({
+ *   plugins: [TsDocLintPlugin()],
+ * });
+ * ```
+ *
+ * @example
+ * Custom configuration:
+ * ```typescript
+ * import { TsDocLintPlugin } from '@savvy-web/rslib-builder';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     TsDocLintPlugin({
+ *       tsdoc: {
+ *         tagDefinitions: [{ tagName: '@error', syntaxKind: 'block' }],
+ *       },
+ *       onError: 'throw',
+ *       persistConfig: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare interface TsDocLintPluginOptions {
+    /**
+     * Whether to enable TSDoc linting.
+     * @defaultValue true
+     */
+    enabled?: boolean;
+    /**
+     * TSDoc configuration for custom tag definitions.
+     * Uses the same options as the DtsPlugin's apiModel.tsdoc option.
+     *
+     * @remarks
+     * By default, all standard tag groups (core, extended, discretionary) are
+     * enabled. Custom tags defined in `tagDefinitions` are automatically
+     * supported.
+     */
+    tsdoc?: TsDocOptions;
+    /**
+     * Override automatic file discovery with explicit file paths or glob patterns.
+     *
+     * @remarks
+     * By default, TsDocLintPlugin uses import graph analysis to discover files
+     * from your package's exports. This ensures only public API files are linted.
+     *
+     * Use this option only when you need to lint specific files that aren't
+     * part of the export graph, or to override the automatic discovery.
+     *
+     * When specified as glob patterns, test files and `__test__` directories
+     * are still excluded unless explicitly included.
+     *
+     * @example
+     * ```typescript
+     * // Explicit patterns override automatic discovery
+     * TsDocLintPlugin({
+     *   include: ["src/**\/*.ts", "!**\/*.test.ts"],
+     * })
+     * ```
+     */
+    include?: string[];
+    /**
+     * How to handle TSDoc lint errors.
+     * - `"warn"`: Log warnings but continue the build
+     * - `"error"`: Log errors but continue the build
+     * - `"throw"`: Fail the build with an error
+     *
+     * @defaultValue `"throw"` in CI environments, `"error"` locally
+     */
+    onError?: TsDocLintErrorBehavior;
+    /**
+     * 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 linting
+     *
+     * @defaultValue `true` when not in CI, `false` in CI environments
+     */
+    persistConfig?: boolean | PathLike;
+}
+
 /**
  * Options for tsdoc-metadata.json generation.
  * @public

package/index.js

@@ -3,13 +3,14 @@ import * as __rspack_external_node_path_c5b9b54f from "node:path";
 import { __webpack_require__ } from "./rslib-runtime.js";
 import { constants, existsSync, writeFileSync } from "node:fs";
 import { defineConfig } from "@rslib/core";
-import { access, copyFile, mkdir, readFile, readdir, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { access, copyFile, mkdir, readFile, readdir, rm, stat, unlink as promises_unlink, writeFile } from "node:fs/promises";
 import { logger as core_logger } from "@rsbuild/core";
 import picocolors from "picocolors";
 import { getWorkspaceRoot } from "workspace-tools";
 import { spawn } from "node:child_process";
 import { StandardTags, Standardization, TSDocTagSyntaxKind } from "@microsoft/tsdoc";
-import { createCompilerHost, findConfigFile, formatDiagnostic, parseJsonConfigFileContent, readConfigFile, sys } from "typescript";
+import deep_equal from "deep-equal";
+import typescript, { createCompilerHost, findConfigFile, formatDiagnostic, parseJsonConfigFileContent, readConfigFile, sys } from "typescript";
 import { createRequire } from "node:module";
 import { inspect } from "node:util";
 import sort_package_json from "sort-package-json";
@@ -446,7 +447,14 @@ class TsDocConfigBuilder {
         if (tagDefinitions.length > 0) tsdocConfig.tagDefinitions = tagDefinitions;
         if (Object.keys(supportForTags).length > 0) tsdocConfig.supportForTags = supportForTags;
         const configPath = (0, external_node_path_.join)(outputDir, "tsdoc.json");
-        await writeFile(configPath, JSON.stringify(tsdocConfig, null, 2));
+        if (existsSync(configPath)) try {
+            const existingContent = await readFile(configPath, "utf-8");
+            const existingConfig = JSON.parse(existingContent);
+            if (deep_equal(existingConfig, tsdocConfig, {
+                strict: true
+            })) return configPath;
+        } catch  {}
+        await writeFile(configPath, `${JSON.stringify(tsdocConfig, null, "\t")}\n`);
         return configPath;
     }
     static syntaxKindToString(kind) {
@@ -630,7 +638,7 @@ async function bundleDtsFiles(options) {
     let persistedTsdocConfigPath;
     if (tsdocConfigPath) if (shouldPersist) persistedTsdocConfigPath = tsdocConfigPath;
     else try {
-        await unlink(tsdocConfigPath);
+        await promises_unlink(tsdocConfigPath);
     } catch  {}
     return {
         bundledFiles,
@@ -792,7 +800,7 @@ function runTsgo(options) {
                                 });
                                 await copyFile(file.path, newPath);
                                 log.global.info(`Renamed ${file.relativePath} -> ${originalDtsPath} (from temp api-extractor)`);
-                                await unlink(file.path);
+                                await promises_unlink(file.path);
                             }
                         }
                         allDtsFiles.length = 0;
@@ -1440,6 +1448,430 @@ const PackageJsonTransformPlugin = (options = {})=>{
         }
     };
 };
+class ImportGraph {
+    options;
+    sys;
+    program = null;
+    compilerOptions = null;
+    moduleResolutionCache = null;
+    constructor(options){
+        this.options = options;
+        this.sys = options.sys ?? typescript.sys;
+    }
+    traceFromEntries(entryPaths) {
+        const errors = [];
+        const visited = new Set();
+        const entries = [];
+        const initResult = this.initializeProgram();
+        if (!initResult.success) return {
+            files: [],
+            entries: [],
+            errors: [
+                initResult.error
+            ]
+        };
+        for (const entryPath of entryPaths){
+            const absolutePath = this.resolveEntryPath(entryPath);
+            if (!this.sys.fileExists(absolutePath)) {
+                errors.push({
+                    type: "entry_not_found",
+                    message: `Entry file not found: ${entryPath}`,
+                    path: absolutePath
+                });
+                continue;
+            }
+            entries.push(absolutePath);
+            this.traceImports(absolutePath, visited, errors);
+        }
+        const files = Array.from(visited).filter((file)=>this.isSourceFile(file));
+        return {
+            files: files.sort(),
+            entries,
+            errors
+        };
+    }
+    traceFromPackageExports(packageJsonPath) {
+        const absolutePath = this.resolveEntryPath(packageJsonPath);
+        let packageJson;
+        try {
+            const content = this.sys.readFile(absolutePath);
+            if (!content) return {
+                files: [],
+                entries: [],
+                errors: [
+                    {
+                        type: "package_json_not_found",
+                        message: `Failed to read package.json: File not found at ${absolutePath}`,
+                        path: absolutePath
+                    }
+                ]
+            };
+            packageJson = JSON.parse(content);
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                files: [],
+                entries: [],
+                errors: [
+                    {
+                        type: "package_json_parse_error",
+                        message: `Failed to parse package.json: ${message}`,
+                        path: absolutePath
+                    }
+                ]
+            };
+        }
+        const extractor = new EntryExtractor();
+        const { entries } = extractor.extract(packageJson);
+        const packageDir = (0, external_node_path_.dirname)(absolutePath);
+        const entryPaths = Object.values(entries).map((p)=>(0, external_node_path_.resolve)(packageDir, p));
+        return this.traceFromEntries(entryPaths);
+    }
+    initializeProgram() {
+        if (this.program) return {
+            success: true
+        };
+        const configPath = this.findTsConfig();
+        if (!configPath) return {
+            success: false,
+            error: {
+                type: "tsconfig_not_found",
+                message: `No tsconfig.json found in ${this.options.rootDir}`,
+                path: this.options.rootDir
+            }
+        };
+        const configFile = typescript.readConfigFile(configPath, (path)=>this.sys.readFile(path));
+        if (configFile.error) {
+            const message = typescript.flattenDiagnosticMessageText(configFile.error.messageText, "\n");
+            return {
+                success: false,
+                error: {
+                    type: "tsconfig_read_error",
+                    message: `Failed to read tsconfig.json: ${message}`,
+                    path: configPath
+                }
+            };
+        }
+        const parsed = typescript.parseJsonConfigFileContent(configFile.config, this.sys, (0, external_node_path_.dirname)(configPath));
+        if (parsed.errors.length > 0) {
+            const messages = parsed.errors.map((e)=>typescript.flattenDiagnosticMessageText(e.messageText, "\n")).join("\n");
+            return {
+                success: false,
+                error: {
+                    type: "tsconfig_parse_error",
+                    message: `Failed to parse tsconfig.json: ${messages}`,
+                    path: configPath
+                }
+            };
+        }
+        this.compilerOptions = parsed.options;
+        this.moduleResolutionCache = typescript.createModuleResolutionCache(this.options.rootDir, (fileName)=>fileName.toLowerCase(), this.compilerOptions);
+        const host = typescript.createCompilerHost(this.compilerOptions, true);
+        host.getCurrentDirectory = ()=>this.options.rootDir;
+        this.program = typescript.createProgram([], this.compilerOptions, host);
+        return {
+            success: true
+        };
+    }
+    findTsConfig() {
+        if (this.options.tsconfigPath) {
+            const customPath = (0, external_node_path_.isAbsolute)(this.options.tsconfigPath) ? this.options.tsconfigPath : (0, external_node_path_.resolve)(this.options.rootDir, this.options.tsconfigPath);
+            if (this.sys.fileExists(customPath)) return customPath;
+            return null;
+        }
+        const configPath = typescript.findConfigFile(this.options.rootDir, (path)=>this.sys.fileExists(path));
+        return configPath ?? null;
+    }
+    resolveEntryPath(entryPath) {
+        if ((0, external_node_path_.isAbsolute)(entryPath)) return (0, external_node_path_.normalize)(entryPath);
+        return (0, external_node_path_.normalize)((0, external_node_path_.resolve)(this.options.rootDir, entryPath));
+    }
+    traceImports(filePath, visited, errors) {
+        const normalizedPath = (0, external_node_path_.normalize)(filePath);
+        if (visited.has(normalizedPath)) return;
+        if (this.isExternalModule(normalizedPath)) return;
+        visited.add(normalizedPath);
+        const content = this.sys.readFile(normalizedPath);
+        if (!content) return void errors.push({
+            type: "file_read_error",
+            message: `Failed to read file: ${normalizedPath}`,
+            path: normalizedPath
+        });
+        const sourceFile = typescript.createSourceFile(normalizedPath, content, typescript.ScriptTarget.Latest, true);
+        const imports = this.extractImports(sourceFile);
+        for (const importPath of imports){
+            const resolved = this.resolveImport(importPath, normalizedPath);
+            if (resolved) this.traceImports(resolved, visited, errors);
+        }
+    }
+    extractImports(sourceFile) {
+        const imports = [];
+        const visit = (node)=>{
+            if (typescript.isImportDeclaration(node)) {
+                const specifier = node.moduleSpecifier;
+                if (typescript.isStringLiteral(specifier)) imports.push(specifier.text);
+            } else if (typescript.isExportDeclaration(node)) {
+                const specifier = node.moduleSpecifier;
+                if (specifier && typescript.isStringLiteral(specifier)) imports.push(specifier.text);
+            } else if (typescript.isCallExpression(node)) {
+                const expression = node.expression;
+                if (expression.kind === typescript.SyntaxKind.ImportKeyword && node.arguments.length > 0) {
+                    const arg = node.arguments[0];
+                    if (arg && typescript.isStringLiteral(arg)) imports.push(arg.text);
+                }
+            }
+            typescript.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+        return imports;
+    }
+    resolveImport(specifier, fromFile) {
+        if (!specifier.startsWith(".") && !specifier.startsWith("/")) {
+            if (!this.compilerOptions?.paths || !Object.keys(this.compilerOptions.paths).length) return null;
+        }
+        if (!this.compilerOptions || !this.moduleResolutionCache) return null;
+        const resolved = typescript.resolveModuleName(specifier, fromFile, this.compilerOptions, this.sys, this.moduleResolutionCache);
+        if (resolved.resolvedModule) {
+            const resolvedPath = resolved.resolvedModule.resolvedFileName;
+            if (resolved.resolvedModule.isExternalLibraryImport) return null;
+            if (resolvedPath.endsWith(".d.ts")) {
+                const sourcePath = resolvedPath.replace(/\.d\.ts$/, ".ts");
+                if (this.sys.fileExists(sourcePath)) return sourcePath;
+                return null;
+            }
+            return resolvedPath;
+        }
+        return null;
+    }
+    isExternalModule(filePath) {
+        return filePath.includes("/node_modules/") || filePath.includes("\\node_modules\\");
+    }
+    isSourceFile(filePath) {
+        if (!filePath.endsWith(".ts") && !filePath.endsWith(".tsx")) return false;
+        if (filePath.endsWith(".d.ts")) return false;
+        if (filePath.includes(".test.") || filePath.includes(".spec.")) return false;
+        if (filePath.includes("/__test__/") || filePath.includes("\\__test__\\")) return false;
+        if (filePath.includes("/__tests__/") || filePath.includes("\\__tests__\\")) return false;
+        const excludePatterns = this.options.excludePatterns ?? [];
+        for (const pattern of excludePatterns)if (filePath.includes(pattern)) return false;
+        return true;
+    }
+    static fromEntries(entryPaths, options) {
+        const graph = new ImportGraph(options);
+        return graph.traceFromEntries(entryPaths);
+    }
+    static fromPackageExports(packageJsonPath, options) {
+        const graph = new ImportGraph(options);
+        return graph.traceFromPackageExports(packageJsonPath);
+    }
+}
+function formatLintResults(results, cwd) {
+    if (0 === results.messages.length) return "";
+    const lines = [];
+    const messagesByFile = new Map();
+    for (const msg of results.messages){
+        const existing = messagesByFile.get(msg.filePath) ?? [];
+        existing.push(msg);
+        messagesByFile.set(msg.filePath, existing);
+    }
+    for (const [filePath, messages] of messagesByFile){
+        lines.push(picocolors.underline(picocolors.cyan((0, external_node_path_.relative)(cwd, filePath))));
+        for (const msg of messages){
+            const location = picocolors.dim(`${msg.line}:${msg.column}`);
+            const severityColor = 2 === msg.severity ? picocolors.red : picocolors.yellow;
+            const severityLabel = 2 === msg.severity ? "error" : "warning";
+            const rule = msg.ruleId ? picocolors.dim(`(${msg.ruleId})`) : "";
+            lines.push(`  ${location}  ${severityColor(severityLabel)}  ${msg.message} ${rule}`);
+        }
+        lines.push("");
+    }
+    const errorText = 1 === results.errorCount ? "error" : "errors";
+    const warningText = 1 === results.warningCount ? "warning" : "warnings";
+    const summary = results.errorCount > 0 ? picocolors.red(`${results.errorCount} ${errorText}`) : picocolors.yellow(`${results.warningCount} ${warningText}`);
+    lines.push(summary);
+    return lines.join("\n");
+}
+function discoverFilesToLint(options, cwd) {
+    if (options.include && options.include.length > 0) return {
+        files: options.include,
+        errors: [],
+        isGlobPattern: true
+    };
+    const graph = new ImportGraph({
+        rootDir: cwd
+    });
+    const packageJsonPath = (0, external_node_path_.join)(cwd, "package.json");
+    const result = graph.traceFromPackageExports(packageJsonPath);
+    return {
+        files: result.files,
+        errors: result.errors,
+        isGlobPattern: false
+    };
+}
+async function runTsDocLint(options, cwd) {
+    const tsdocOptions = options.tsdoc ?? {};
+    const persistConfig = options.persistConfig;
+    const shouldPersist = TsDocConfigBuilder.shouldPersist(persistConfig);
+    const tsdocConfigOutputPath = TsDocConfigBuilder.getConfigPath(persistConfig, cwd);
+    const tsdocConfigPath = await TsDocConfigBuilder.writeConfigFile(tsdocOptions, (0, external_node_path_.dirname)(tsdocConfigOutputPath));
+    let ESLint;
+    let tsParserModule;
+    let tsdocPluginModule;
+    const missingPackages = [];
+    try {
+        const eslintModule = await import("eslint");
+        ESLint = eslintModule.ESLint;
+    } catch  {
+        missingPackages.push("eslint");
+    }
+    try {
+        tsParserModule = await import("@typescript-eslint/parser");
+    } catch  {
+        missingPackages.push("@typescript-eslint/parser");
+    }
+    try {
+        tsdocPluginModule = await import("eslint-plugin-tsdoc");
+    } catch  {
+        missingPackages.push("eslint-plugin-tsdoc");
+    }
+    if (missingPackages.length > 0 || !ESLint) throw new Error(`TsDocLintPlugin requires: ${missingPackages.join(", ")}\nInstall with: pnpm add -D ${missingPackages.join(" ")}`);
+    const tsParser = tsParserModule.default ?? tsParserModule;
+    const tsdocPlugin = tsdocPluginModule.default ?? tsdocPluginModule;
+    const discovery = discoverFilesToLint(options, cwd);
+    if (0 === discovery.files.length) return {
+        results: {
+            errorCount: 0,
+            warningCount: 0,
+            messages: []
+        },
+        tsdocConfigPath: shouldPersist ? tsdocConfigPath : void 0,
+        discoveryErrors: discovery.errors
+    };
+    let eslintConfig;
+    let filesToLint;
+    if (discovery.isGlobPattern) {
+        const includePatterns = discovery.files;
+        filesToLint = includePatterns.filter((p)=>!p.startsWith("!"));
+        eslintConfig = [
+            {
+                ignores: [
+                    "**/node_modules/**",
+                    "**/dist/**",
+                    "**/coverage/**"
+                ]
+            },
+            {
+                files: filesToLint,
+                ignores: includePatterns.filter((p)=>p.startsWith("!")).map((p)=>p.slice(1)),
+                languageOptions: {
+                    parser: tsParser
+                },
+                plugins: {
+                    tsdoc: tsdocPlugin
+                },
+                rules: {
+                    "tsdoc/syntax": "error"
+                }
+            }
+        ];
+    } else {
+        filesToLint = discovery.files;
+        eslintConfig = [
+            {
+                ignores: [
+                    "**/node_modules/**",
+                    "**/dist/**",
+                    "**/coverage/**"
+                ]
+            },
+            {
+                files: [
+                    "**/*.ts",
+                    "**/*.tsx"
+                ],
+                languageOptions: {
+                    parser: tsParser
+                },
+                plugins: {
+                    tsdoc: tsdocPlugin
+                },
+                rules: {
+                    "tsdoc/syntax": "error"
+                }
+            }
+        ];
+    }
+    const eslint = new ESLint({
+        cwd,
+        overrideConfigFile: true,
+        overrideConfig: eslintConfig
+    });
+    const eslintResults = await eslint.lintFiles(filesToLint);
+    const messages = [];
+    let errorCount = 0;
+    let warningCount = 0;
+    for (const result of eslintResults)for (const msg of result.messages){
+        messages.push({
+            filePath: result.filePath,
+            line: msg.line,
+            column: msg.column,
+            message: msg.message,
+            ruleId: msg.ruleId,
+            severity: msg.severity
+        });
+        if (2 === msg.severity) errorCount++;
+        else warningCount++;
+    }
+    return {
+        results: {
+            errorCount,
+            warningCount,
+            messages
+        },
+        tsdocConfigPath: shouldPersist ? tsdocConfigPath : void 0,
+        discoveryErrors: discovery.errors.length > 0 ? discovery.errors : void 0
+    };
+}
+async function cleanupTsDocConfig(configPath) {
+    if (!configPath) return;
+    try {
+        const { unlink } = await import("node:fs/promises");
+        await unlink(configPath);
+    } catch  {}
+}
+const TsDocLintPlugin = (options = {})=>{
+    const { enabled = true } = options;
+    let tempTsDocConfigPath;
+    return {
+        name: "tsdoc-lint-plugin",
+        setup (api) {
+            if (!enabled) return;
+            api.onBeforeBuild(async ()=>{
+                const cwd = api.context.rootPath;
+                const isCI = TsDocConfigBuilder.isCI();
+                const onError = options.onError ?? (isCI ? "throw" : "error");
+                core_logger.info(`${picocolors.dim("[tsdoc-lint]")} Validating TSDoc comments...`);
+                try {
+                    const { results, tsdocConfigPath, discoveryErrors } = await runTsDocLint(options, cwd);
+                    if (discoveryErrors && discoveryErrors.length > 0) for (const error of discoveryErrors)core_logger.warn(`${picocolors.dim("[tsdoc-lint]")} ${error.message}`);
+                    if (!TsDocConfigBuilder.shouldPersist(options.persistConfig)) tempTsDocConfigPath = tsdocConfigPath;
+                    if (0 === results.errorCount && 0 === results.warningCount) return void core_logger.info(`${picocolors.dim("[tsdoc-lint]")} ${picocolors.green("All TSDoc comments are valid")}`);
+                    const formatted = formatLintResults(results, cwd);
+                    if (results.errorCount > 0) if ("throw" === onError) throw new Error(`TSDoc validation failed:\n${formatted}`);
+                    else if ("error" === onError) core_logger.error(`${picocolors.dim("[tsdoc-lint]")} TSDoc validation errors:\n${formatted}`);
+                    else core_logger.warn(`${picocolors.dim("[tsdoc-lint]")} TSDoc validation warnings:\n${formatted}`);
+                    else if (results.warningCount > 0) core_logger.warn(`${picocolors.dim("[tsdoc-lint]")} TSDoc validation warnings:\n${formatted}`);
+                } catch (error) {
+                    await cleanupTsDocConfig(tempTsDocConfigPath);
+                    throw error;
+                }
+            });
+            api.onCloseBuild(async ()=>{
+                await cleanupTsDocConfig(tempTsDocConfigPath);
+            });
+        }
+    };
+};
 /* v8 ignore next -- @preserve */ class NodeLibraryBuilder {
     static DEFAULT_OPTIONS = {
         entry: void 0,
@@ -1453,7 +1885,8 @@ const PackageJsonTransformPlugin = (options = {})=>{
         tsconfigPath: void 0,
         externals: [],
         dtsBundledPackages: void 0,
-        transformFiles: void 0
+        transformFiles: void 0,
+        tsdocLint: void 0
     };
     static mergeOptions(options = {}) {
         const merged = {
@@ -1487,6 +1920,11 @@ const PackageJsonTransformPlugin = (options = {})=>{
         const options = NodeLibraryBuilder.mergeOptions(opts);
         const VERSION = await packageJsonVersion();
         const plugins = [];
+        if (options.tsdocLint) {
+            const lintOptions = true === options.tsdocLint ? {} : options.tsdocLint;
+            if (!lintOptions.tsdoc && "object" == typeof options.apiModel && options.apiModel.tsdoc) lintOptions.tsdoc = options.apiModel.tsdoc;
+            plugins.push(TsDocLintPlugin(lintOptions));
+        }
         if ("dev" === target || "npm" === target) {
             if (!options.entry) plugins.push(AutoEntryPlugin({
                 exportsAsIndexes: options.exportsAsIndexes
@@ -1565,4 +2003,4 @@ const PackageJsonTransformPlugin = (options = {})=>{
         });
     }
 }
-export { AutoEntryPlugin, DtsPlugin, FilesArrayPlugin, NodeLibraryBuilder, PackageJsonTransformPlugin, TsDocConfigBuilder };
+export { AutoEntryPlugin, DtsPlugin, FilesArrayPlugin, ImportGraph, NodeLibraryBuilder, PackageJsonTransformPlugin, TsDocConfigBuilder, TsDocLintPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/rslib-builder",
-	"version": "0.3.0",
+	"version": "0.4.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",
@@ -27,6 +27,7 @@
 		"@microsoft/tsdoc": "^0.16.0",
 		"@microsoft/tsdoc-config": "^0.18.0",
 		"@pnpm/exportable-manifest": "^1000.3.1",
+		"deep-equal": "^2.2.3",
 		"glob": "^13.0.0",
 		"picocolors": "^1.1.1",
 		"sort-package-json": "^3.6.0",
@@ -38,7 +39,10 @@
 		"@microsoft/api-extractor": "^7.55.2",
 		"@rslib/core": "^0.19.2",
 		"@types/node": "^25.0.9",
+		"@typescript-eslint/parser": "^8.0.0",
 		"@typescript/native-preview": "^7.0.0-dev.20260120.1",
+		"eslint": "^9.0.0",
+		"eslint-plugin-tsdoc": "^0.5.0",
 		"typescript": "^5.9.3"
 	},
 	"peerDependenciesMeta": {
@@ -48,9 +52,18 @@
 		"@rslib/core": {
 			"optional": false
 		},
+		"@typescript-eslint/parser": {
+			"optional": true
+		},
 		"@typescript/native-preview": {
 			"optional": false
 		},
+		"eslint": {
+			"optional": true
+		},
+		"eslint-plugin-tsdoc": {
+			"optional": true
+		},
 		"typescript": {
 			"optional": false
 		}