@anov/cic-standard-sdk 0.0.20 → 0.0.21

package/dist/types/manifest/cic.manifest.d.ts

@@ -0,0 +1,476 @@
+/**
+ * @file cic.manifest.ts
+ * @description CIC 需求表（CICManifest）类型定义
+ *
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │  职责定位                                                            │
+ * │  本文件是"应用侧视角"的完整声明，描述一个 CIC 应用需要什么、          │
+ * │  如何消费、怎样注册组件。                                             │
+ * │                                                                     │
+ * │  对应关系：                                                          │
+ * │    CICManifest（需求表）  ←→  RuntimeManifest（供给表）              │
+ * │    两者由 resolveManifest() 完成匹配，产出 ResolvedManifest          │
+ * └─────────────────────────────────────────────────────────────────────┘
+ *
+ * 设计原则：
+ *   1. 应用只声明"要什么"，不关心"从哪里来"（由供给表决定）
+ *   2. strategy 是全局策略，单条 requires[].consume 可覆盖
+ *   3. 所有路径都是逻辑路径，由 alias / importMap 展开为物理路径
+ */
+/**
+ * 目标运行平台
+ *   web       —— 普通浏览器页面（主流场景）
+ *   electron  —— Electron 桌面应用，window 对象来自 BrowserWindow
+ *   miniapp   —— 小程序等受限环境，不支持动态 importMap
+ */
+export type EnginePlatform = 'web' | 'electron' | 'miniapp';
+/**
+ * JS 框架运行时
+ *   Adapter 层根据此字段选择对应实现（Vue3Adapter / ReactAdapter...）
+ */
+export type EngineRuntime = 'vue3' | 'vue2' | 'react' | 'svelte';
+/**
+ * 运行模式
+ *   development —— 开发模式，使用 binding.src（本地/开发服务器路径）
+ *   production  —— 生产模式，使用 binding.prodSrc（CDN / 部署路径）
+ *   staging     —— 预发布，行为同 production 但可开启额外日志
+ *
+ * ⚠️ RuntimeManifest.engine.mode 决定 Loader 选 src 还是 prodSrc，
+ *    此处是 CICManifest 对运行模式的"期望声明"，通常由构建工具注入。
+ */
+export type EngineMode = 'development' | 'production' | 'staging';
+/** semver 具体版本字符串，如 "3.4.21"（非范围） */
+export type SemverString = string;
+/**
+ * semver 版本范围，如 "^3.0.0" "~1.2.0" ">= 2.0.0"
+ * Loader 使用 checkVersion() 按以下规则校验：
+ *   ^x.y.z  —— 主版本相同且 >= base（兼容版本）
+ *   ~x.y.z  —— 主版本 + 次版本相同且 >= base（补丁兼容）
+ *   x.y.z   —— 精确匹配
+ */
+export type SemverRange = string;
+/** URL 路径，相对路径（./xxx）或绝对路径（/xxx 或 https://...） */
+export type UrlPath = string;
+/**
+ * window 对象属性路径，支持链式，如：
+ *   "Vue"           → window.Vue
+ *   "MyLib.Core"    → window.MyLib.Core
+ *   "NS.Sub.Plugin" → window.NS.Sub.Plugin
+ */
+export type WindowPath = string;
+/**
+ * ESM import specifier（模块标识符），如：
+ *   "vue"           → import { ref } from 'vue'
+ *   "@anov/core"    → import Core from '@anov/core'
+ *   "cdn/button"    → 通过 importMap cdn/ 前缀展开
+ */
+export type Specifier = string;
+/** 环境变量表：值只允许基本类型，禁止对象/数组（序列化安全） */
+export type EnvRecord = Record<string, string | number | boolean>;
+/**
+ * importMap scopes 结构：
+ *   key   —— 作用域 URL 前缀（如 "/pages/admin/"）
+ *   value —— 该作用域内的 specifier → URL 覆盖映射
+ *
+ * 典型用途：同一 specifier 在不同路径下解析到不同版本
+ *   "/legacy/" → { vue: "/vendor/vue2.esm.js" }  // 兼容组件用 Vue 2
+ */
+export type ScopesMap = Record<UrlPath, Record<Specifier, UrlPath>>;
+/**
+ * 标准 W3C importMap 结构
+ *
+ * 三层合并优先级（低 → 高）：
+ *   runtime.importMap（基础前缀）
+ *     ↑
+ *   resolveManifest 供需匹配生成（ESM 直连 + shimB data: URL）
+ *     ↑
+ *   alias 展开（cic.modules.alias → imports）
+ *     ↑
+ *   cic.modules.importMap（应用显式声明，最高优先级）
+ *
+ * scopes 深度合并（非 spread 整体覆盖）：
+ *   同 scope key 下的 imports 按 key 级覆盖（见 mergeScopes 实现）
+ */
+export interface ImportMap {
+    imports: Record<Specifier, UrlPath>;
+    /**
+     * 作用域映射，可选。
+     * 不支持的平台（如部分小程序）应忽略此字段。
+     * V2 中 resolveManifest 不向 scopes 写入供需生成的映射，仅做透传合并。
+     */
+    scopes?: ScopesMap;
+}
+/**
+ * 模块整体消费策略（cic.modules.strategy）
+ * 作为 requires[].consume 字段的默认值来源，单条可覆盖。
+ *
+ * 推导规则（defaultConsume 函数实现）：
+ *   'importmap' → consume 默认 'esm'
+ *     适用场景：纯 ESM 项目，所有依赖通过 import specifier 消费
+ *   'global'    → consume 默认 'global'
+ *     适用场景：遗留项目，所有依赖挂 window，通过 window.X 访问
+ *   'hybrid'    → consume 默认 'both'
+ *     适用场景：迁移期，同一依赖既要 window 兼容旧插件，又要 ESM 给新代码
+ *
+ * 优先级：requires[n].consume（显式）> strategy（默认推导）
+ */
+export type ModuleStrategy = 'importmap' | 'global' | 'hybrid';
+/**
+ * 单依赖的消费形态
+ *   'esm'    —— 只需要 import specifier，不需要 window 全局
+ *   'global' —— 只需要 window.X，不需要 importMap 映射
+ *   'both'   —— 两种都需要（过渡期最常见，旧插件 + 新模块并存）
+ *
+ * Loader 供需匹配矩阵（consume × 供给形态）：
+ *   供给\需求    esm            global         both
+ *   esm+global   direct-esm    direct-global   direct-esm + direct-global
+ *   只有 esm     direct-esm    shimA           direct-esm + shimA
+ *   只有 global  shimB         direct-global   shimB + direct-global
+ *   无供给        host-injected 检查 / skipped
+ */
+export type ConsumeMode = 'esm' | 'global' | 'both';
+/**
+ * 单条外部依赖的消费声明（cic.modules.requires[]）
+ *
+ * 最小声明示例（strategy:'importmap' 下，所有字段可推导）：
+ *   { id: 'vue', version: '^3.4.0' }
+ *   → consume 默认 'esm'（来自 strategy）
+ *   → specifier 默认 'vue'（来自 id）
+ *
+ * 完整声明示例（策略为 hybrid，显式覆盖所有字段）：
+ *   {
+ *     id: 'vue',
+ *     version: '^3.4.0',
+ *     required: true,
+ *     consume: 'both',
+ *     specifier: 'vue',
+ *     global: 'Vue',
+ *     dependencies: []
+ *   }
+ */
+export interface CICRequires {
+    /**
+     * 依赖标识符，与 RuntimeManifest.provides 的 key 对应。
+     * 通常与 npm 包名一致，如 'vue' '@anov/charts'。
+     */
+    id: string;
+    /**
+     * 版本范围约束（semver range）。
+     * Loader 用 checkVersion(provides[id].version, version) 校验。
+     * 未填则跳过版本校验（versionSatisfied → 'unknown'）。
+     */
+    version?: SemverRange;
+    /**
+     * 是否必需，默认 true。
+     *
+     * required=true（默认）：
+     *   - 版本不满足 → 抛出错误，中止 resolveManifest
+     *   - host-injected 检查失败（window 不存在）→ 抛出错误
+     *   - 供给表无记录 + window 不存在 → 抛出错误
+     *
+     * required=false：
+     *   - 版本不满足 → strategy='skipped'，记录 warning，继续
+     *   - host-injected 检查失败 → strategy='skipped'，记录 warning，继续
+     *   - 依赖加载失败 → 忽略，继续执行后续任务
+     */
+    required?: boolean;
+    /**
+     * 消费形态。未填时从 cic.modules.strategy 推导（见 ModuleStrategy 注释）。
+     * 显式声明优先级高于 strategy 推导。
+     */
+    consume?: ConsumeMode;
+    /**
+     * consume 包含 'esm' 时，注册到 importMap 的 import specifier。
+     * 未填时按以下优先级取值：
+     *   ext.specifier > provides[id].bindings.esm.specifier > ext.id
+     *
+     * 建议总是显式声明，避免依赖供给表的内部字段。
+     */
+    specifier?: Specifier;
+    /**
+     * consume 包含 'global' 时，期望挂载到 window 的属性路径。
+     * 未填时按以下优先级取值：
+     *   ext.global > provides[id].bindings.global.window > ext.id
+     *
+     * 支持链式路径，如 'MyLib.Core'（对应 window.MyLib.Core）。
+     */
+    global?: WindowPath;
+    /**
+     * 加载顺序约束（拓扑排序依赖列表）。
+     * 填写其他 requires[n].id，Loader 保证被依赖项先加载。
+     *
+     * 示例：vue-router 必须在 vue 加载完成后再加载
+     *   { id: 'vue-router', dependencies: ['vue'] }
+     *
+     * 循环依赖会被 topoSort 检测并抛出错误。
+     */
+    dependencies?: string[];
+}
+/**
+ * 组件装配覆盖规则（cic.components.adapters[]）
+ *
+ * 优先级：adapters（按 match 精确覆盖）> components.strategy（全局默认）
+ * 注册顺序：registry（静态，最先）→ adapters（动态匹配）→ strategy 兜底
+ *
+ * kind 决定注册路径：
+ *   plugin    —— 作为插件安装，调用 app.use(mod, options)
+ *   component —— 作为组件注册，调用 app.component(name, mod)
+ *   module    —— 调用模块的指定方法，如 mod.init(app, options)
+ *   global    —— 从 window.globalName 读取后注册（遗留/CDN 场景）
+ */
+export interface ComponentAdapter {
+    /**
+     * glob 匹配模式，匹配组件/库的标识符（通常是 import specifier 或包名）。
+     * 示例：
+     *   '*'                   —— 匹配所有（通配兜底）
+     *   '@arco-design/web-vue' —— 精确匹配
+     *   'cdn/**\/*.js'         —— 路径通配
+     */
+    match: string;
+    /**
+     * 装配种类，决定注册方式。详见上方注释。
+     */
+    kind: 'plugin' | 'component' | 'module' | 'global';
+    /**
+     * 注册配置（可选，kind 为 plugin/module 时常用）。
+     *   method  —— 调用的方法名（默认：plugin→'use'，module→'install'）
+     *   target  —— 注册目标（默认：当前 app 实例），如 'app' 'router'
+     *   options —— 传递给 method 的选项对象
+     */
+    register?: {
+        method?: string;
+        target?: string;
+        options?: Record<string, unknown>;
+    };
+    /**
+     * 是否必需，默认 true。
+     * false 时注册失败只记录 warning，不阻断挂载流程。
+     */
+    required?: boolean;
+    /** 加载顺序约束，填写其他 adapter.match 值 */
+    dependencies?: string[];
+    /**
+     * 是否异步注册（async: true）。
+     * true 时 Adapter 不等待注册完成直接继续，适合非阻塞的懒加载组件库。
+     * 注意：异步注册的组件在首次渲染时可能尚未就绪。
+     */
+    async?: boolean;
+    /**
+     * 实例初始化钩子（组件/插件挂载后执行额外初始化逻辑）。
+     *
+     * when    —— 触发时机：'mounted'（DOM 挂载后）或 'ready'（框架生命周期就绪后）
+     * method  —— 调用的实例方法名
+     * options —— 传递给方法的参数
+     * guard   —— 执行前提条件表达式（falsy 则跳过 instanceInit）
+     *
+     * 示例（图表库在挂载后调用 setTheme）：
+     *   instanceInit: { when: 'mounted', method: 'setTheme', options: { theme: 'dark' } }
+     */
+    instanceInit?: {
+        when?: 'mounted' | 'ready';
+        method: string;
+        options?: Record<string, unknown>;
+        guard?: string;
+    };
+    /**
+     * kind:'global' 时，从 window 读取的属性路径（WindowPath）。
+     * 未填时使用 match 字段值。
+     *
+     * 示例：match='echarts', globalName='echarts' → 读取 window.echarts
+     */
+    globalName?: string;
+}
+/**
+ * CIC 需求清单（应用侧，由 CIC 平台或构建工具生成）
+ *
+ * 字段分组：
+ *   engine     —— 应用对运行时环境的最低要求
+ *   modules    —— 模块解析策略与外部依赖声明
+ *   components —— 组件注册策略（仅影响 Adapter 层，不影响 Loader）
+ *   export     —— 应用向宿主暴露依赖时的排除声明
+ *   env        —— 应用侧环境变量覆盖（覆盖 runtime.env 同名字段）
+ *   extensions —— 业务扩展字段（Loader 不处理，原样透传）
+ *
+ * 注意：CICManifest 没有 entry 字段，应用入口由 RuntimeManifest.entry 指定，
+ *       或由 manifest-loader 从固定约定路径（./src/main.js）加载。
+ */
+export interface CICManifest {
+    /**
+     * 需求表格式版本（semver），用于 Loader 兼容性检测。
+     * 与 RuntimeManifest.version 独立，各自演进。
+     */
+    version: SemverString;
+    /**
+     * 应用对运行时环境的需求声明。
+     * Loader 会校验 runtime.engine 是否满足以下约束。
+     */
+    engine: {
+        platform: EnginePlatform;
+        runtime: EngineRuntime;
+        /**
+         * 期望的框架版本范围（semver range）。
+         * 用于与 RuntimeManifest.engine.version 进行校验。
+         * 未填则跳过版本校验。
+         */
+        version?: SemverRange;
+    };
+    /** 模块解析配置 */
+    modules: {
+        /**
+         * 模块消费整体策略，决定 requires[].consume 的默认值。
+         * 详见 ModuleStrategy 类型注释中的推导规则。
+         *
+         * 最佳实践：
+         *   纯新项目      → 'importmap'（最简，全部 ESM）
+         *   全遗留项目    → 'global'（全部 window 全局）
+         *   迁移期/混合   → 'hybrid'（逐条 requires 精细控制）
+         */
+        strategy: ModuleStrategy;
+        /**
+         * 应用显式声明的 importMap（合并优先级最高）。
+         * 典型用途：指定特定 specifier 使用应用自己打包的版本，
+         *           而不是宿主 runtime 提供的版本。
+         *
+         * ⚠️ 此字段会完全覆盖供需匹配生成的同名 specifier 映射。
+         *    谨慎填写，避免绕过版本校验。
+         */
+        importMap?: ImportMap;
+        /**
+         * 外部依赖需求列表（即"需求表的核心"）。
+         * 字段名用 requires（而非 externals）更直观表达"应用向宿主要求的依赖"。
+         * 每条声明对应供给表中的一个 ProvideEntry。
+         *
+         * 空列表或未填 → 跳过供需匹配，直接使用 runtime.importMap 和 cic.modules.importMap。
+         */
+        requires?: CICRequires[];
+        /**
+         * 模块路径基础 URL（路径前缀，不含文件名）。
+         * 用于将相对路径的模块 URL 转换为绝对路径。
+         *
+         * 区别于 RuntimeManifest.engine.devServerURL（开发服务器地址）。
+         * 此字段是应用自己的模块基础路径，devServerURL 是宿主运行时的服务地址。
+         */
+        baseURL?: string;
+        /**
+         * 路径别名（Loader 预处理阶段展开为 importMap.imports 条目）。
+         *
+         * 规则：
+         *   - prefix alias 必须以 '/' 结尾（如 '@/'、'cdn/'）
+         *   - 展开后进入 importMap.imports，优先级同 cic.modules.importMap
+         *   - Loader 校验格式（expandAlias 函数），非 '/' 结尾直接抛出错误
+         *   - 展开后的路径解析由浏览器 importMap 原生处理，Loader 不另实现匹配
+         *
+         * 示例：
+         *   alias: { '@/': '/src/', 'cdn/': '/anov-prod/mgt/ui/' }
+         *   → importMap.imports['@/'] = '/src/'
+         *   → importMap.imports['cdn/'] = '/anov-prod/mgt/ui/'
+         */
+        alias?: Record<string, string>;
+        /**
+         * 应用自身需要预加载的模块路径列表。
+         * 与 RuntimeManifest.preload 合并去重，在 importMap 注入后由 Loader 动态插入
+         * <link rel="modulepreload"> 标签。
+         *
+         * ⚠️ 不能写在 HTML 里：HTML 解析阶段触发 modulepreload 时 importMap 尚未注入，
+         *    module graph 解析失败。必须由 Loader 在 importMap 注入后动态插入。
+         */
+        preload?: UrlPath[];
+        /**
+         * 依赖加载失败的降级策略。
+         *   strategy: 'global' —— 降级读取 window 全局变量
+         *   strategy: 'cdn'    —— 从备用 CDN 重新加载
+         *   mapping            —— specifier → 降级目标的映射
+         *   cdnBase            —— 备用 CDN 基础 URL（strategy:'cdn' 时使用）
+         *
+         * ⚠️ V2 中 fallback 仅在 required=false 时生效，
+         *    required=true 的依赖加载失败直接报错，不走 fallback。
+         */
+        fallback?: {
+            strategy: 'global' | 'cdn';
+            mapping?: Record<string, string>;
+            cdnBase?: string;
+        };
+    };
+    /**
+     * 组件注册配置（仅影响 Adapter 层，Loader 不处理此字段）。
+     * Adapter 在 register 阶段读取此配置完成组件装配。
+     */
+    components?: {
+        /**
+         * 组件注册默认策略，作为 adapters[].kind 的兜底。
+         *   global —— 全局注册，所有页面可用（适合基础组件库）
+         *   local  —— 局部注册，仅在声明页面可用（适合业务组件）
+         *   lazy   —— 懒加载注册，首次使用时才加载（适合大型可选组件）
+         */
+        strategy?: 'global' | 'local' | 'lazy';
+        /**
+         * 按 match 精确覆盖注册方式，优先级高于 strategy。
+         * 注册执行顺序：按 dependencies 拓扑排序后顺序执行。
+         * 与 registry 冲突时：registry 优先（静态声明高于动态匹配），记录 warning。
+         */
+        adapters?: ComponentAdapter[];
+        /** 全局组件名称前缀，统一给注册的组件加前缀（如 'Cic' → CicButton） */
+        prefix?: string;
+        /**
+         * 组件命名规范，决定从文件名生成组件名的方式。
+         * 支持内置规范（PascalCase 最常用）和自定义字符串。
+         */
+        naming?: 'kebab-case' | 'PascalCase' | 'camelCase' | (string & {});
+        /**
+         * 静态组件注册表（key: 组件名，value: 模块路径）。
+         * 优先级高于 adapters 动态匹配。
+         *
+         * 与 requires 冲突（同一模块同时出现）时：
+         *   registry 的路径优先，记录 warning，不报错。
+         *
+         * 示例：
+         *   registry: { DataTable: '@/components/DataTable/index.ts' }
+         *   → Adapter 调用 import('@/components/DataTable/index.ts') 后注册为 DataTable
+         */
+        registry?: Record<string, string>;
+        /**
+         * 同名组件冲突处理策略，默认 'warn'。
+         *   'warn'    —— 记录 warning，后注册者覆盖先注册者（安全兜底）
+         *   'error'   —— 抛出错误，中止注册流程（严格模式）
+         *   'replace' —— 静默覆盖，不记录任何日志（性能优先）
+         */
+        conflictPolicy?: 'warn' | 'error' | 'replace';
+    };
+    /**
+     * 应用向宿主声明"哪些依赖由宿主统一注入、无需应用自带"。
+     * 构建工具（如 Vite）据此生成 rollupOptions.external，
+     * 避免把 vue/pinia 等打包进应用 bundle。
+     *
+     * 注意：这是构建阶段的声明，运行时 Loader 不读取此字段。
+     */
+    export?: {
+        /** 排除的依赖 id 列表（对应 rollupOptions.external） */
+        excludeDeps?: string[];
+        /** 排除原因（文档用途，供构建日志展示） */
+        reason?: string;
+    };
+    /**
+     * 应用侧环境变量，覆盖 RuntimeManifest.env 中的同名字段。
+     * 合并规则：{ ...runtime.env, ...cic.env }（cic 优先）
+     * 合并结果写入 window.__ENV__ 和 ResolvedManifest.env。
+     */
+    env?: EnvRecord;
+    /**
+     * 业务扩展字段，Loader 不处理，原样透传到 ResolvedManifest.cic.extensions。
+     * 适合存放多租户配置、国际化标识等平台特定数据。
+     *
+     * 示例：{ tenant: 'default', locale: 'zh-CN' }
+     */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * CICManifest 完整配置示例
+ *
+ * 场景说明：
+ *   - 使用 hybrid 策略（Vue 既要 ESM 又要 global，便于旧插件兼容）
+ *   - echarts 只需要 global（遗留图表插件通过 window.echarts 访问）
+ *   - @anov/charts 只需要 ESM（新模块，只有 import 访问）
+ *   - @arco-design/web-vue 作为插件全局安装
+ *   - DataTable / SmartForm 从本地路径静态注册
+ */
+export declare const CICManifestExample: CICManifest;