chore: wip

Author: glennmichael123

packages/dtsx/README.md

@@ -8,11 +8,16 @@
 
 # dtsx
 
-> A library that helps you generate TypeScript declaration files from your project. Given we do not know the user's input ever, we need to never hardcode based results based from our examples, always create a dynamic solution.
+> A blazing-fast TypeScript declaration file (.d.ts) generator with advanced features like incremental builds, watch mode, bundling, and IDE integration.
 
 ## Features
 
 - ⚡ Extremely fast .d.ts generation
+- 🔄 Watch mode with incremental builds
+- 📦 Declaration bundling support
+- 🔌 Plugin system for custom transformations
+- 🧩 Monorepo/workspace support
+- 🛠️ IDE integration via LSP
 - ⚙️ Highly configurable
 - 🪶 Lightweight library
 - 🤖 Cross-platform binary
@@ -69,22 +74,41 @@ const options: DtsGenerationOptions = {
 await generate(options)
 ```
 
-_Available options:_
+### Configuration File
 
 Library usage can also be configured using a `dts.config.ts` _(or `dts.config.js`)_ file which is automatically loaded when running the `./dtsx` _(or `bunx dtsx`)_ command. It is also loaded when the `generate` function is called, unless custom options are provided.
 
 ```ts
 // dts.config.ts (or dts.config.js)
+import { defineConfig } from '@stacksjs/dtsx'
 
-export default {
+export default defineConfig({
   cwd: './',
   root: './src',
   entrypoints: ['**/*.ts'],
   outdir: './dist',
   keepComments: true,
   clean: true,
   verbose: true,
-}
+
+  // Advanced options
+  watch: false, // Enable watch mode
+  incremental: false, // Enable incremental builds
+  parallel: false, // Enable parallel processing
+  concurrency: 4, // Number of parallel workers
+
+  // Bundling
+  bundle: false, // Bundle all declarations into one file
+  bundleOutput: 'index.d.ts', // Output filename when bundling
+
+  // Output formatting
+  prettier: false, // Use Prettier for formatting
+  indentStyle: 'spaces', // 'spaces' or 'tabs'
+  indentSize: 2, // Number of spaces
+
+  // Plugins
+  plugins: [],
+})
 ```
 
 _You may also run:_
@@ -98,9 +122,11 @@ _You may also run:_
 
 ## CLI
 
-The `dtsx` CLI provides a simple way to generate TypeScript declaration files from your project. Here's how to use it:
+The `dtsx` CLI provides a comprehensive set of commands for generating and managing TypeScript declaration files.
 
-### Usage
+### Commands
+
+#### Generate Declarations
 
 Generate declaration files using the default options:
 
@@ -111,29 +137,228 @@ dtsx generate
 _Or use custom options:_
 
 ```bash
-# Generate declarations for specific entry points:
+# Generate declarations for specific entry points
 dtsx generate --entrypoints src/index.ts,src/utils.ts --outdir dist/types
 
-# Generate declarations with custom configuration:
+# Generate declarations with custom configuration
 dtsx generate --root ./lib --outdir ./types --clean
 
-dtsx --help
-dtsx --version
+# Enable incremental builds
+dtsx generate --incremental
+
+# Enable parallel processing
+dtsx generate --parallel --concurrency 8
+```
+
+#### Watch Mode
+
+Watch for file changes and automatically regenerate declarations:
+
+```bash
+dtsx watch
+
+# Watch with custom options
+dtsx watch --root ./src --outdir ./dist --debounce 300
+```
+
+#### Bundle Declarations
+
+Bundle multiple declaration files into a single file:
+
+```bash
+dtsx bundle --outdir ./dist --output bundle.d.ts
+```
+
+#### Workspace/Monorepo Support
+
+Generate declarations for all packages in a monorepo:
+
+```bash
+dtsx workspace
+
+# Specify packages directory
+dtsx workspace --packages ./packages
+```
+
+#### Type Checking
+
+Run type checking with isolated declarations support:
+
+```bash
+dtsx check
+
+# Check specific files
+dtsx check --files "src/**/*.ts"
+```
+
+#### Circular Dependency Detection
+
+Detect circular dependencies in your TypeScript files:
+
+```bash
+dtsx circular
+
+# Output as JSON or DOT (Graphviz) format
+dtsx circular --format json
+dtsx circular --format dot
+```
+
+#### Generate Documentation
+
+Generate API documentation from your TypeScript files:
+
+```bash
+dtsx docs
+
+# Specify output format
+dtsx docs --format markdown
+dtsx docs --format html
+dtsx docs --format json
+```
+
+#### Optimize Declarations
+
+Optimize and tree-shake declaration files:
+
+```bash
+dtsx optimize
+
+# Optimize specific files
+dtsx optimize --files "dist/**/*.d.ts"
+```
+
+#### Convert Types
+
+Convert TypeScript types to different schema formats:
+
+```bash
+dtsx convert --format zod
+dtsx convert --format json-schema
+dtsx convert --format valibot
+```
+
+#### LSP Server
+
+Start the Language Server Protocol server for IDE integration:
+
+```bash
+dtsx lsp
+```
+
+#### Read from Stdin
+
+Accept TypeScript code from stdin:
+
+```bash
+echo "export function foo(): string { return 'bar' }" | dtsx stdin
 ```
 
-_Available options:_
+### CLI Options
+
+#### Global Options
 
 - `--cwd <path>`: Set the current working directory _(default: current directory)_
+- `--verbose`: Enable verbose output _(default: false)_
+- `--help`: Show help information
+- `--version`: Show version number
+
+#### Generate Options
+
 - `--root <path>`: Specify the root directory of the project _(default: './src')_
 - `--entrypoints <files>`: Define entry point files _(comma-separated, default: '**/*.ts')_
 - `--outdir <path>`: Set the output directory for generated .d.ts files _(default: './dist')_
 - `--keep-comments`: Keep comments in generated .d.ts files _(default: true)_
 - `--clean`: Clean output directory before generation _(default: false)_
 - `--tsconfig <path>`: Specify the path to tsconfig.json _(default: 'tsconfig.json')_
-- `--verbose`: Enable verbose output _(default: false)_
+- `--incremental`: Enable incremental builds _(default: false)_
+- `--parallel`: Enable parallel processing _(default: false)_
+- `--concurrency <n>`: Number of parallel workers _(default: 4)_
+- `--dry-run`: Show what would be generated without writing files
+- `--diff`: Show differences from existing .d.ts files
+- `--validate`: Validate generated .d.ts against TypeScript compiler
+- `--stats`: Show generation statistics
+- `--progress`: Show progress during generation
+- `--output-format <format>`: Output format: 'text' or 'json' _(default: 'text')_
+
+#### Watch Options
+
+- `--debounce <ms>`: Debounce delay in milliseconds _(default: 100)_
+
+#### Bundle Options
+
+- `--output <file>`: Output filename _(default: 'index.d.ts')_
+- `--banner <text>`: Add banner comment to output
+- `--footer <text>`: Add footer comment to output
 
 To learn more, head over to the [documentation](https://dtsx.stacksjs.org/).
 
+## Build Tool Integration
+
+dtsx provides plugins for popular build tools:
+
+### Vite
+
+```ts
+// vite.config.ts
+import { dts } from '@stacksjs/dtsx/vite'
+
+export default {
+  plugins: [dts()],
+}
+```
+
+### esbuild
+
+```ts
+// build.ts
+import { dtsx } from '@stacksjs/dtsx/esbuild'
+
+await esbuild.build({
+  plugins: [dtsx()],
+})
+```
+
+### webpack
+
+```ts
+// webpack.config.js
+const { DtsxWebpackPlugin } = require('@stacksjs/dtsx/webpack')
+
+module.exports = {
+  plugins: [new DtsxWebpackPlugin()],
+}
+```
+
+### tsup
+
+```ts
+// tsup.config.ts
+import { dtsxPlugin } from '@stacksjs/dtsx/tsup'
+
+export default {
+  plugins: [dtsxPlugin()],
+}
+```
+
+### Bun
+
+```ts
+// build.ts
+import { dts } from '@stacksjs/dtsx/bun'
+
+await Bun.build({
+  plugins: [dts()],
+})
+```
+
+## Documentation
+
+- [Architecture Guide](../../ARCHITECTURE.md) - How dtsx works internally
+- [Contributing Guide](../../CONTRIBUTING.md) - How to contribute to dtsx
+- [Performance Guide](../../PERFORMANCE.md) - Tips for optimizing large codebases
+- [Migration Guide](../../MIGRATION.md) - Migrating from other tools
+- [Troubleshooting](../../TROUBLESHOOTING.md) - Common issues and solutions
+
 ## Testing
 
 ```bash
@@ -160,7 +385,7 @@ For casual chit-chat with others using this package:
 
 ## Postcardware
 
-“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where `dtsx` is being used! We showcase them on our website too.
+"Software that is free, but hopes for a postcard." We love receiving postcards from around the world showing where `dtsx` is being used! We showcase them on our website too.
 
 Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎
 

packages/dtsx/package.json

@@ -28,6 +28,30 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/src/index.js"
     },
+    "./vite": {
+      "types": "./dist/src/plugins/vite.d.ts",
+      "import": "./dist/src/plugins/vite.js"
+    },
+    "./bun": {
+      "types": "./dist/src/plugins/bun.d.ts",
+      "import": "./dist/src/plugins/bun.js"
+    },
+    "./esbuild": {
+      "types": "./dist/src/plugins/esbuild.d.ts",
+      "import": "./dist/src/plugins/esbuild.js"
+    },
+    "./tsup": {
+      "types": "./dist/src/plugins/tsup.d.ts",
+      "import": "./dist/src/plugins/tsup.js"
+    },
+    "./webpack": {
+      "types": "./dist/src/plugins/webpack.d.ts",
+      "import": "./dist/src/plugins/webpack.js"
+    },
+    "./plugins": {
+      "types": "./dist/src/plugins/index.d.ts",
+      "import": "./dist/src/plugins/index.js"
+    },
     "./*": {
       "types": "./dist/*.d.ts",
       "import": "./dist/*"