feat: update v2 docs and support declaration.allowJs

.changeset/migrate-generate-types-for-js.md

@@ -0,0 +1,5 @@
+---
+'@ice/pkg': major
+---
+
+feat: migrate `generateTypesForJs` to `declaration.allowJs`

packages/pkg/src/config/schema.ts

@@ -59,7 +59,6 @@ export const userConfigSchema = z.object({
     .record(z.string(), z.union([z.string(), z.boolean(), z.number(), z.null(), z.record(z.string(), z.any())]))
     .optional(),
   sourceMaps: z.union([z.boolean(), z.enum(['inline'])]).optional(),
-  generateTypeForJs: z.boolean().optional(),
   jsxRuntime: z.enum(['classic', 'automatic']).optional(),
   plugins: z.any().array().optional(),
   helpers: z.enum(['external', 'inline']).optional(),
@@ -71,6 +70,7 @@ export const userConfigSchema = z.object({
     z.object({
       outputMode: z.enum(['multi', 'unique']).optional(),
       generator: z.enum(['tsc', 'oxc']).optional(),
+      allowJs: z.boolean().optional(),
     }),
   ]),
   server: z.union([z.boolean(), serverSchema]).optional(),

packages/pkg/src/config/userConfig.ts

@@ -24,10 +24,6 @@ function getUserConfig() {
       name: 'jsxRuntime',
       defaultValue: 'automatic',
     },
-    {
-      name: 'generateTypesForJs',
-      defaultValue: false,
-    },
     {
       name: 'declaration',
       defaultValue: true,

packages/pkg/src/core/init.ts

@@ -28,6 +28,7 @@ const defaultBundleUserConfig: BundleUserConfig = {
 const defaultDeclarationUserConfig = {
   outputMode: 'multi',
   generator: 'tsc',
+  allowJs: false,
 } satisfies DeclarationUserConfig;
 
 export function initContextTasks(ctx: Context) {
@@ -159,6 +160,7 @@ export function initDeclarationTask(buildTask: BuildTask, options: InitTaskOptio
   } else {
     config.outputMode ??= declarationConfig?.outputMode ?? defaultDeclarationUserConfig.outputMode;
     config.generator ??= declarationConfig?.generator ?? defaultDeclarationUserConfig.generator;
+    config.allowJs ??= declarationConfig?.allowJs ?? defaultDeclarationUserConfig.allowJs;
   }
 
   const allOutputDirs = allTasks

packages/pkg/src/helpers/dts.ts

@@ -47,6 +47,7 @@ export interface DtsCompileOptions {
   rootDir: string;
   outputDir: string;
   usingOxc: boolean;
+  allowJs?: boolean;
 }
 
 function formatAliasToTSPathsConfig(alias: TaskConfig['alias']) {
@@ -79,6 +80,7 @@ export async function dtsCompile({
   outputDir,
   alias,
   usingOxc,
+  allowJs = false,
 }: DtsCompileOptions): Promise<DtsInputFile[]> {
   if (!files.length) {
     return [];
@@ -88,7 +90,7 @@ export async function dtsCompile({
 
   const defaultTSConfig: TsConfigJson = {
     compilerOptions: {
-      allowJs: true,
+      allowJs,
       declaration: true,
       emitDeclarationOnly: true,
       incremental: true,

packages/pkg/src/tasks/declaration.ts

@@ -33,9 +33,12 @@ class DeclarationRunner extends Runner<OutputResult> {
         context.buildContext.rootDir,
         (context.buildTask.config.entry! as Record<string, string>) ?? {},
       );
+      const filePattern = (context.buildTask.config as DeclarationTaskConfig).allowJs
+        ? '**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'
+        : '**/*.{ts,tsx,mts,cts}';
       const result = await Promise.all(
         entryDirs.map((entry) =>
-          globby('**/*.{ts,tsx,mts,cts}', {
+          globby(filePattern, {
             cwd: entry,
             onlyFiles: true,
             ignore: ['**/*.d.{ts,mts,cts}'],
@@ -64,6 +67,7 @@ class DeclarationRunner extends Runner<OutputResult> {
         outputDir: buildConfig.outputDir!,
         alias: buildConfig.alias,
         usingOxc: buildConfig.generator === 'oxc',
+        allowJs: buildConfig.allowJs ?? false,
       },
     ]);
 

packages/pkg/src/types.ts

@@ -176,6 +176,13 @@ export interface DeclarationUserConfig {
    * @default 'tsc'
    */
   generator?: 'tsc' | 'oxc';
+
+  /**
+   * Whether to generate declaration files for JavaScript files.
+   * Useful when using JSDoc type annotations in JS files.
+   * @default false
+   */
+  allowJs?: boolean;
 }
 
 export interface PkgUserConfig
@@ -278,12 +285,6 @@ export interface UserConfig {
    * but not include it in the result object.
    */
   sourceMaps?: boolean | 'inline';
-  /**
-   * Whether or not to generate declaration files for Ecmascript
-   * @default false
-   */
-  generateTypesForJs?: boolean;
-
   /**
    * Generate .d.ts files from TypeScript files in your project.
    * @default true

website/docs/ai.md

@@ -0,0 +1,13 @@
+# 在 AI 中使用
+
+ICE PKG 遵循 [llmstxt.org](https://llmstxt.org/) 标准，提供两个文件帮助 AI 工具理解项目文档：
+
+| 文件          | 链接                               | 描述                                                   |
+| ------------- | ---------------------------------- | ------------------------------------------------------ |
+| llms.txt      | https://pkg.ice.work/llms.txt      | 包含所有文档页面的标题、链接和简要描述的结构化索引文件 |
+| llms-full.txt | https://pkg.ice.work/llms-full.txt | 将每个文档页面的完整内容合并到单个文件中               |
+
+## 如何选择
+
+- **llms.txt**：体积较小，消耗 token 少，适合 AI 按需获取特定页面内容的场景
+- **llms-full.txt**：包含完整文档内容，适合需要 AI 全面理解 ICE PKG 的场景，但会消耗更多 token，最适合支持大上下文窗口的 AI 工具

website/docs/cli.md

@@ -0,0 +1,31 @@
+# CLI
+
+## start
+
+启动本地调试服务，监听文件变更并自动重新编译。配置文件变更时会自动重启。
+
+```bash
+$ ice-pkg start [options]
+```
+
+|         选项          |   类型    | 说明                          |
+| :-------------------: | :-------: | ----------------------------- |
+|  `--config <config>`  | `string`  | 指定配置文件路径              |
+| `--rootDir <rootDir>` | `string`  | 指定应用运行的根目录          |
+|     `--analyzer`      | `boolean` | Bundle 模式下开启体积构建分析 |
+|    `--port <port>`    | `number`  | 覆盖预览服务端口号            |
+|    `--host <host>`    | `string`  | 覆盖预览服务 host             |
+
+## build
+
+执行编译或打包构建，输出构建产物。
+
+```bash
+$ ice-pkg build [options]
+```
+
+|         选项          |   类型    | 说明                          |
+| :-------------------: | :-------: | ----------------------------- |
+|  `--config <config>`  | `string`  | 指定配置文件路径              |
+| `--rootDir <rootDir>` | `string`  | 指定应用运行的根目录          |
+|     `--analyzer`      | `boolean` | Bundle 模式下开启体积构建分析 |

website/docs/config/alias.md

@@ -0,0 +1,20 @@
+# alias
+
+- 类型：`Record<string, string>`
+- 默认值：`{}`
+
+配置路径别名。
+
+比如，将 `@` 指向 `./src` 目录：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  alias: {
+    '@': './src',
+  },
+});
+```
+
+然后代码里 `import '@/foo'` 会被改成 `import '/path/to/your/project/foo'`。