@fulgurjs/federation 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 2.0.2（2026-09-22）
+
+### 修复（D6：双向宿主 devSharedSelf 开启后 prod 构建产物 chunk 循环崩溃）
+
+- **缺陷**：双向联邦宿主（既 expose 又消费 remote）按文档口径设置 `devSharedSelf: true` 后，
+  `vite build` 成功但 prod 运行时崩溃——`SyntaxError: Unexpected token '<'`（chunk 被 SPA 回退）
+  + `TypeError: _e is not a function`（协商函数未初始化）。仅在「宿主 + 用户 manualChunks 强制
+  分组（对象/函数形式）」组合下触发（实测 mes-zc admin：vue-vendor ⇄ antd-vue-vendor 环）。
+- **根因**：`devSharedSelf` 使 node_modules 参与门面化，被 manualChunks 强制分组的包
+  （如 vue-vendor 组内 vue-router）内部的 shared 导入被改写为协商门面；门面为静态
+  `import` 运行时的 TLA 模块，被 rollup 按消费方归组拖入其他强制组 → 跨组静态环 →
+  门面 TLA 求值顺序错位。
+- **修复 1（门面形态参数化，virtual.ts）**：`genSharedFacade` / `genSharedNsFacade` /
+  `genBindingFacade` / `genRemoteBindingFacade` 新增 dynamic 形态——门面对运行时与 shared
+  本体的依赖全部改为 TLA 内 `await import(...)`，命名空间门面以 `{ ...ns }` 复制阻断 rollup
+  透传内联——门面 chunk 对外零静态依赖（"汇"形态），与任何 manualChunks 分组正交，不可能成环。
+  **dynamic 仅在 devSharedSelf 宿主（build）启用；其余一切场景（纯 remote、dev serve）保持
+  2.0.0 静态形态，产物与行为零变化**（硬约束；纯 remote 若启用动态化会在自动分包下出现
+  「门面 TLA → 动态 import 本体 chunk ← 静态 import 门面」死锁，实测确认）。
+- **修复 2（shared 闭包静态化，transform.ts + index.ts）**：devSharedSelf 宿主（build）下，
+  provide 键本体闭包内的模块（如 vue-router 包、vue-demi 转发层——经 shared 本体文件解析
+  传递依赖）对 shared 键的导入**不做门面化**（同一 provide 闭包天然同实例）——斩断
+  「fallback 动态 import 本体 chunk ← 本体消费方静态 import 门面」的 TLA 混合环（实机死锁：
+  页面停在骨架屏、零报错）。别名转发层的 `export * from <key>` 因此保持静态、不再触发
+  ESM 门面化硬报错。纯 remote 不启用，行为零变化（硬约束）。
+- **修复 3（manualChunks 包装注入，index.ts）**：devSharedSelf 宿主 + 用户配置了
+  manualChunks 时，插件包装注入归组函数——运行时隔离进 `fulgurjs-runtime` 组、协商门面按
+  shareKey 隔离进 `fulgurjs-shared-<key>` 组、远程绑定门面进 `fulgurjs-remote-facades-*` 组。
+  对象形式的 specifier 解析延迟到 buildStart（走完整解析管线含 alias），解析失败丢组并告警。
+- **修复 4（post 阶段 auto-import 兜底，index.ts）**：build 下 post.transform 不再跳过非
+  `.vue` 文件——unplugin-auto-import 等后置插件注入的 `import { ref } from 'vue'` 发生在
+  pre.transform 之后，此前会绕过门面化、静态绑定本地 vue 副本，与协商实例形成**双响应性
+  系统**（实测：同一组件内 A ref 的赋值不触发渲染、B ref 的赋值正常；jsdelivr 级表现即
+  「弹窗 model 置 true 却不渲染」）。pre 已改写过的文件由 `isPluginProcessedModule` 守卫
+  拦下，不会双重改写。
+- **新增诊断**：`BLD-006`——output 为数组形态时无法自动注入，三段式提示手工加隔离分支。
+- **集成器**：宿主为双向（有 exposes 且有 remotes）时 vite.config 模板产出
+  `devSharedSelf: true`（落实 README 口径；须配合本版插件使用）。
+- **测试**：+10（门面 dynamic/static 双形态断言 ×6、真实 vite build 产物形态用例 ×1——
+  覆盖「宿主 + devSharedSelf + manualChunks 对象形式」这条此前零覆盖的路径，断言产物无环、
+  门面隔离、"汇"形态、node_modules 门面化指向隔离 chunk；post 兜底源码契约 ×3）。
+
+### 已知边界
+
+- devSharedSelf 宿主的协商门面 chunk 集中在插件专属组：与「门面分散在各业务 chunk」的
+  旧形态相比，首屏会多下载所属 shareKey 的门面 chunk（未压缩量级 = 门面行数，gzip 后显著
+  缩小）；这是换取「与 manualChunks 共存」的结构性代价。
+- 入口文件（index.html 直引的模块）内的 remote 导入在 build 下不参与改写（入口只内联 init
+  即短路返回，既有边界）：remote 导入请放在非入口模块。
+
+## 2.0.1（2026-09-22）
+
+### 变更（文档与包面，零运行时变化）
+
+- **README 补全公开类型/函数名**（对齐「README 写全所有 API」）：`FederationOptions`、
+  `PageRouteLike` / `PagesOptions` / `PageViolation` / `RemoteSchemaEntry`、
+  `RepoConfig` / `UserConfig` / `AppConfig` / `HostConfig` / `RemoteConfig` / `DeployConfig` /
+  `PageEntry` / `RemoteAddress`、`loadRepoConfig`；§1 与 §4 的 import 示例带上类型。
+- **peer 下限对齐实测值**：`vite` `>=5.0.0` → `>=5.1.0`（历史兼容矩阵实测下限为 5.1.4）。
+- **发布物收窄**：移出内部草稿 `docs/vite-upstream-issue-irregexp.md`（仅存档性质，非用户文档）。
+- **仓库公开面整理**：8 个内部工作文档（已执行的 0.9.0 任务书、Trusted Publishing 迁移清单、
+  改进项评估、三个设计方案、qiankun 调研、上述草稿）移入 `docs/_workspace/`（本地工作区、不入库），
+  `docs/` 只保留面向用户的四个文档；相关代码注释与 CHANGELOG 引用同步修正，全仓零失效引用。
+- 两处过时文档元数据修正：webpack-mf 对照文档的版本戳、vite-upstream 草稿的断链引用与失效 commit 号。
+
 ## 2.0.0（2026-09-22）
 
 ### 破坏性变更（公开 API 去掉冗余品牌前缀，无兼容别名）
@@ -72,7 +137,7 @@
 - **`dts: { mode: 'source' | 'shim' }`**（默认 `source`，行为不变）：`shim` 形态的类型声明不引用跨工程源文件（宽松占位），根治 VSCode/Volar 打开 `types/*.d.ts` 时的跨工程诊断红波浪线；取舍为无源码级补全/跳转（README §9.1.5）。
 - **`fulgurjs.config.ts` 新增 `host.prefetch: 'all' | string[] | false`**（默认 `'all'`，行为不变）：空闲预载名单成为正式配置面，init 生成 bridge.ts 时注入 `PREFETCH_REMOTES` 常量（README §9.1.3）。
 - **`npm run typecheck:latest`**：用最新 TypeScript + vue-tsc 对 `tests/types-repro/` 典型消费形态做类型回归——根治"工程内旧 TS 绿、用户 IDE（新 TS）红"的盲区（0.8.2 的 EP locale ts2345 即由此暴露）。
-- **CI 流水线**：`.github/workflows/ci.yml`（push/PR：单测 + 双口径 typecheck + build/gzip 门禁）与 `.github/workflows/publish.yml`（GitHub Release 触发 `npm publish --provenance`，Trusted Publishing 迁移见 docs/trusted-publishing-迁移清单.md）。
+- **CI 流水线**：`.github/workflows/ci.yml`（push/PR：单测 + 双口径 typecheck + build/gzip 门禁）与 `.github/workflows/publish.yml`（GitHub Release 触发 `npm publish --provenance`，Trusted Publishing 迁移已完成）。
 
 ### 变更
 
@@ -133,7 +198,7 @@
 
 ## 0.8.0（2026-09-20）
 
-### 新增（跨应用传值与方法引用收编 + 乾坤功能融合，设计文档 docs/跨应用传值与方法引用设计方案-2026-09-20.md 定稿实施）
+### 新增（跨应用传值与方法引用收编 + 乾坤功能融合，设计文档定稿后实施）
 
 - **`@fulgurjs/federation/context` 新子路径（~2KB 独立文件，与 `./vue` 同模式）**：
   - `provideFulgurjsAppContext(config)`——宿主桥一次性写入跨应用上下文（merge 语义，幂等可多次，后写覆盖）；
@@ -148,7 +213,7 @@
 ### 文档（乾坤功能融合配套，全部宿主/模板侧，插件 runtime 零改动）
 
 - README 特性声明新增「CSP 友好（原生 ESM 无 eval）」；新增 §9 AppContext API 参考（字段表/时序契约/方法模块规范）；迁移指南新增「跨应用传值」节与「页面卸载清理清单」节（乾坤 unmount 强制清理的联邦等价物：`onUnmounted` 摘除 window 级监听/定时器/context.events 反向注册）。
-- 乾坤功能融合三件套（保活 keep-alive 白名单 / 页面加载骨架屏 / 空闲预载编排）与联邦诊断面板均为**集成器模板/宿主项目侧**能力，用法见迁移指南与 `fulgurjs.config.ts` 模板注释；调研依据见 docs/qiankun功能融合调研-2026-09-20.md（16 项逐项对照：9 项已有、4 项与架构哲学冲突不搬、3 项值得搬 + inspector 概念轻量化落地）。
+- 乾坤功能融合三件套（保活 keep-alive 白名单 / 页面加载骨架屏 / 空闲预载编排）与联邦诊断面板均为**集成器模板/宿主项目侧**能力，用法见迁移指南与 `fulgurjs.config.ts` 模板注释；调研依据：16 项逐项对照（：9 项已有、4 项与架构哲学冲突不搬、3 项值得搬 + inspector 概念轻量化落地）。
 
 ## 0.7.1（2026-09-20）
 
@@ -159,7 +224,7 @@
 
 ## 0.7.0（2026-09-20）
 
-### 新增（Vue 直渲染 API，设计文档 docs/远程组件直渲染API设计方案-2026-09-20.md 定稿实施）
+### 新增（Vue 直渲染 API，设计文档定稿后实施）
 
 - **`remoteComponent(spec, opts)`（`@fulgurjs/federation/vue` 子路径）**：远程组件直渲染的标准封装——`defineAsyncComponent({ loader: () => loadRemote(spec, opts).then(m => m.default ?? m) })`。选项：`loadingComponent` / `errorComponent`（不传时内置错误占位：错误码+根因+修法三段式）/ `retries`（透传 loadRemote）/ `delay` / `timeout`。H3 零兜底：加载失败显式进错误态，`fulgurjs:error` 事件照常发出；模块去重沿用 loadRemote Promise 缓存；`vue` 为可选 peerDependency。
 - **架构边界**：runtime.js 保持框架无关（不 import vue），gzip 红线零增量——Vue 封装独立子路径文件、按需引入。

package/README.md

@@ -152,9 +152,11 @@ npx fulgurjs doctor --base http://localhost:5173 --apps app-a --dev
 ### 1. `federation(options)` — Vite 插件（宿主/远程同一份 API）
 
 ```ts
-import { federation } from '@fulgurjs/federation'
+import { federation, type FederationOptions } from '@fulgurjs/federation'
 ```
 
+插件选项类型为 `FederationOptions`（下表即其字段全集）。
+
 #### 全部选项
 
 | 选项 | 类型 | 默认 | 说明 |
@@ -172,7 +174,7 @@ import { federation } from '@fulgurjs/federation'
 | `manifest` | `boolean` | `true` | prod 构建生成 `fulgurjs-manifest.json`（preloadRemote 依赖它） |
 | `runtimePlugins` | `string[]` | `[]` | 运行时插件模块路径列表（写法见「运行时插件」） |
 | `dts` | `boolean \| { dir?: string; mode?: 'source' \| 'shim' }` | `true` | dev 下拉取远程 manifest 生成类型声明——宿主写 `import X from 'remote-a/X'` 获得类型。**产物写入 `src/fulgurjs/types/`（联邦产物集中一个文件夹；无 src 布局回退 `.fulgurjs/types`）**，src 布局项目 tsconfig 零配置即生效；`{ dir }` 自定义位置；`mode: 'source'`（默认）跨工程源码直连（补全/跳转直达远程源码，VSCode 打开生成物可能显示工程外文件诊断）；`mode: 'shim'` 宽松占位（不引用源文件，IDE 全程干净，无源码级补全——见 §9.1.5） |
-| `devSharedSelf` | `boolean` | 纯远程 `true`；有 `remotes` 的宿主 `false` | dev 下自身源码（含依赖）是否参与 shared 协商改写。**双向联邦**（既 expose 又消费 remote）的宿主/远程需显式 `true`，否则 prod 双 vue 实例 |
+| `devSharedSelf` | `boolean` | 纯远程 `true`；有 `remotes` 的宿主 `false` | dev 下自身源码（含依赖）是否参与 shared 协商改写。**双向联邦**（既 expose 又消费 remote）的宿主/远程**必设 `true`**，否则 prod 双 vue 实例（症状：被消费页面渲染上下文错乱 / `'ce'` / renderSlot null）。2.0.1 起 build 下该路径的协商门面自动隔离进插件专属 chunk（`fulgurjs-runtime` + `fulgurjs-shared-<key>`），与用户 `manualChunks` 强制分组正交、不再产生 chunk 循环依赖（D6 修复，症状曾是 `SyntaxError: Unexpected token '<'` + `TypeError: _e is not a function`） |
 | `automaticAsyncBoundary` | — | 恒为 `true` | 接受任意值：TLA 自动异步边界，无需手工 bootstrap |
 | `dataPrefetch` | — | 恒为 `true` | 接受任意值：`preloadRemote` 始终可用 |
 | `usedExports` / `ignoreUnusedSharedExports` | — | no-op | 接受并忽略（Rollup/Rolldown 原生 tree-shaking 已覆盖） |
@@ -326,6 +328,8 @@ export const PAGES = definePages(
 
 `validatePages(pages, options)` 为独立导出：返回违例清单不抛错，便于自测。
 
+同子路径的类型：`PageRouteLike`（路由条目形状）、`PagesOptions`（校验选项，含 `deriveSpec` / `remotes` / `schema` / `strict`）、`PageViolation`（`validatePages` 的返回条目，含 `level` 与说明）、`RemoteSchemaEntry`（`schema` 里每个远程的条目形状）。
+
 ### 4. `fulgurjs.config.ts` — CLI 单配置文件（`@fulgurjs/federation/config`）
 
 ```ts
@@ -356,6 +360,11 @@ export default defineRepoConfig({
 })
 ```
 
+程序化加载：`loadRepoConfig(configPath): Promise<RepoConfig>` —— 读 `fulgurjs.config.ts` / `.js` / `.json` 并做 CFG 段校验（CLI 内部同款；配置文件里 `@fulgurjs/federation/config` 的导入会被重写为包内绝对路径，故在工程依赖装好之前也能加载）。
+
+同子路径的类型：`RepoConfig`（整个配置文件）／`UserConfig`（`defineRepoConfig` 的入参形状，字段全可选）／`AppConfig`（`apps[]` 的一个应用）／`HostConfig`（应用的 `host` 段，宿主角色）／`RemoteConfig`（应用的 `remote` 段，远程角色）／`DeployConfig`（`deploy` 段）／`PageEntry`（`host.pages[]` 的一条页面）／`RemoteAddress`（`remotes` 值的 `{ dev, prod, external }` 形态）。
+```
+
 ### 5. CLI 命令参考
 
 | 命令 | 说明 |
@@ -364,7 +373,7 @@ export default defineRepoConfig({
 | `fulgurjs init --config <path>` | 校验配置（CFG 三段式报错）+ 输出各应用 `federation()` 粘贴块、NGINX no-cache 站点模板、8 条通用核对清单 |
 | `fulgurjs doctor --base <URL> --apps <a,b,c>` | 部署体检：remoteEntry/manifest/index.html 的 200/no-cache/JS 形态、CORS、chunk 抽样可达、版本 skew 预演。`--dev` 检查 dev 容器入口；`--json` 输出 JSON（CI 断言）；`--chunk-sample N` 控制抽样数（默认 16）。**退出码：有 FAIL 即 1**，可直接做 CI 门禁 |
 
-### 6. 错误码总表（30 个）
+### 6. 错误码总表（31 个）
 
 | 段 | 码 | 含义 |
 |---|---|---|
@@ -386,6 +395,7 @@ export default defineRepoConfig({
 | BLD 构建期 | `BLD-001` | expose 源文件解析失败 |
 | | `BLD-002` | 构建目标低于 es2022（TLA 需要） |
 | | `BLD-003` | expose 目标组件含必填 props（文档化核对项） |
+| | `BLD-006` | output 数组形态下无法自动注入协商门面 chunk 隔离（需手工加分支） |
 | MFU 运行时 | `MFU-001` | 远程容器/模块加载失败（网络/超时/重试耗尽/熔断） |
 | | `MFU-002` | remoteEntry 自报名与配置名不一致 |
 | | `MFU-003` | strictVersion 版本不满足 |
@@ -688,7 +698,7 @@ const Panel = await loadRemote('shop/Panel', {
 
 运行时加载失败同样给排查指引（remote dev server 未启动 / 地址配错 / CORS / NGINX 回退），并携带统一错误码：
 
-统一错误码体系（CFG/DEV/BLD/MFU 四段共 30 个）——**完整总表见上方 [API 参考 §6](#6-错误码总表30-个)**；报错文案一律「现象 → 根因 → 修法」三段式。
+统一错误码体系（CFG/DEV/BLD/MFU 四段共 31 个）——**完整总表见上方 [API 参考 §6](#6-错误码总表31-个)**；报错文案一律「现象 → 根因 → 修法」三段式。
 
 调试出口：`window.__FULGURJS_SCOPE__`（share 协商实时结果）、`window.__FULGURJS_INFO__`（remote 状态/耗时/错误）。
 

package/client.d.ts

@@ -59,8 +59,8 @@ declare module 'virtual:fulgurjs-runtime' {
   }
 
   /**
-   * 跨应用上下文标准字段表（0.8.0，docs/跨应用传值与方法引用设计方案-2026-09-20.md §4.3；
-   * 0.8.2 精简：token 快照 / formUrl / baseUrl 移出默认 provide，用 getToken 拉取、扩展位自定）。
+   * 跨应用上下文标准字段表见 README §9。token 快照 / formUrl / baseUrl 不在默认 provide 内——
+   * 取 token 用 getToken()（拉取式不过期），其余按项目需要经扩展位自定。
    * 值 API 在 '@fulgurjs/federation/context' 子路径（runtime.js 不导出 context 函数，
    * 此处仅类型随虚拟模块声明供 type-only import）；读写约定：宿主桥先写标准字段，
    * 远程 boot 只增不改宿主键；嵌套对象（如 events）引用共享。

package/dist/{chunk-5GZKZWP2.js → chunk-UDLQALHC.js}

@@ -1,5 +1,5 @@
 // src/version.ts
-var RUNTIME_VERSION = "2.0.0";
+var RUNTIME_VERSION = "2.0.2";
 
 export {
   RUNTIME_VERSION