@heybox/hb-sdk 0.8.1 → 0.8.2-alpha.2

package/dist/cli-chunks/{runtime-permission-env-C2S34ldj.cjs → runtime-permission-env-DiTeD75Q.cjs}

@@ -2,7 +2,7 @@
 
 var fs = require('node:fs');
 var path = require('node:path');
-var version = require('./version-0qwlEyZC.cjs');
+var version = require('./version-QiVEs76a.cjs');
 require('node:crypto');
 var node_async_hooks = require('node:async_hooks');
 
@@ -2791,7 +2791,58 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+/** 单个小程序版本最多声明的关联游戏数量。 */
 const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
+/**
+ * 校验并规范化小程序关联的游戏 App ID。
+ *
+ * @param value - 不可信声明。`undefined` 和 `[]` 均返回空绑定；其他值必须是最多 20 项的
+ * 字符串数组，不接受 `null`、单个字符串、number 数组或类数组对象。
+ * @param options - 可选诊断来源；`sourceLabel` 默认 `package.json#heybox.bindAppIds`，并原样
+ * 作为所有错误消息的前缀。
+ * @returns 新建、按 appid 数值升序排列且经 `Object.freeze` 冻结的 `readonly string[]`。
+ * 输入数组及其顺序不会被修改；空输入也返回新的冻结空数组。
+ * @throws `Error` `${sourceLabel} 必须是字符串数组`：`value` 不是数组。
+ * @throws `Error` `${sourceLabel} 最多包含 20 个游戏 appid`：输入数组超过 20 项；数量检查
+ * 先于逐项格式检查。
+ * @throws `Error` `${sourceLabel} 包含非法游戏 appid：<value>`：任一项不是 string，或不匹配
+ * `/^[1-9]\d*$/`。因此空串、首尾空白、`0`、前导零、正负号、小数、指数和非十进制字符
+ * 都不会被自动修正。
+ * @throws `Error` `${sourceLabel} 包含超出正 int32 范围的游戏 appid：<value>`：十进制值
+ * 大于 `2147483647` 或不能成为安全整数。
+ * @throws `Error` `${sourceLabel} 包含重复游戏 appid：<value>`：规范字符串在同一数组重复。
+ *
+ * @remarks
+ * 合法范围是闭区间 `1..2147483647`，每项在输出中仍保持十进制 string。排序按数值而不是
+ * 字典序执行，所以 `['3513350', '730', '10']` 输出为 `['10', '730', '3513350']`。
+ * 函数先复制后排序并冻结结果，不排序或冻结调用方传入的数组。
+ *
+ * 这是同步、纯离线的格式规范化函数，不访问网络，也不确认 appid 是否真实存在、可绑定或
+ * 属于当前开发者。`miniappManifest()` 用它校验 `package.json#heybox.bindAppIds` 并把非空结果
+ * 写入 Manifest；远端 deploy 预检和提审才校验游戏可用性。缺失和空数组在普通构建中都表示
+ * 无绑定，函数本身不处理 `remote deploy --from-version` 的历史快照继承语义。
+ *
+ * `bindAppIds` 是版本发布元数据，不是 Runtime 权限，也不会因调用
+ * [navigation.openAppPage](/reference/sdk/navigation/openAppPage) 而变化。后者的 `appId` 是一次
+ * 页面导航参数，允许 string 或 number、只要求字符串化后非空，不适用本函数的数组、int32、
+ * 前导零、去重、20 项或排序规则。
+ *
+ * @example
+ * ```ts
+ * import { parseMiniappBindAppIds } from '@heybox/hb-sdk/miniapp-publish'
+ *
+ * const declared = ['3513350', '730', '10']
+ * const appIds = parseMiniappBindAppIds(declared)
+ *
+ * console.log(appIds) // ['10', '730', '3513350']
+ * console.log(declared) // ['3513350', '730', '10']，输入顺序不变
+ * console.log(Object.isFrozen(appIds)) // true
+ * ```
+ *
+ * @see [miniappManifest](/reference/symbols/vite/functions/miniappManifest)
+ * @see [navigation.openAppPage](/reference/sdk/navigation/openAppPage)
+ * @see [CLI 与远端发布](/guide/cli#生产构建)
+ */
 function parseMiniappBindAppIds(value, options = {}) {
     const sourceLabel = options.sourceLabel ?? 'package.json#heybox.bindAppIds';
     if (value === undefined)
@@ -2820,6 +2871,13 @@ function parseMiniappBindAppIds(value, options = {}) {
     return Object.freeze(appIds);
 }
 
+/**
+ * 所有小程序 iframe bridge envelope 共用的固定 namespace。
+ *
+ * @remarks 该值用于排除无关 `postMessage` 数据，不负责验证消息来源；接收方仍须校验 source 和 nonce，
+ * 并在 origin 可以固定且协议模式要求时校验 origin。
+ */
+
 const MINI_PROGRAM_PERMISSION_KEYS = [
     'userInfo',
     'steamLibrary',
@@ -2969,9 +3027,134 @@ const MINI_PROGRAM_PERMISSION_CATALOG = [
 new Set(MINI_PROGRAM_PERMISSION_KEYS);
 
 const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(MINI_PROGRAM_PERMISSION_KEYS);
+/**
+ * 判断字符串是否是当前协议目录管理的 canonical runtime permission key。
+ *
+ * @param key - 已确认类型为 `string` 的候选权限 key；若输入来自 `unknown` 边界，调用方须先完成字符串检查。
+ * @returns 与 `MINI_PROGRAM_PERMISSION_KEYS` 中某项精确相等时返回 `true`，并将 TypeScript 类型收窄为
+ * `MiniProgramPermissionKey`；未知、历史或格式不同的字符串返回 `false`。
+ *
+ * @remarks
+ * 当前 canonical key 集合固定为：
+ *
+ * - `userInfo`
+ * - `steamLibrary`
+ * - `share`
+ * - `storage`
+ * - `filesystem`
+ * - `clipboard`
+ * - `leaderboard`
+ * - `network`
+ * - `companion`
+ *
+ * 匹配大小写敏感且按原字符串执行。该 guard 不 trim，因此 `' network '` 返回 `false`；历史权限 key
+ * `network.request` 也返回 `false`，即使同名 capability method 仍是公开 method。消费完整 schema v1 权限快照时
+ * 应使用 {@link parseMiniProgramRuntimePermissions}，由解析边界统一 trim，并把历史 `network.request` 归一为
+ * canonical `network`。未知的 future key 同样返回 `false`；本 guard 不负责 parser 的前向兼容忽略策略。
+ *
+ * 类型谓词只把字符串收窄为 `MiniProgramPermissionKey` union，不读取权限 entry、status 或 config，也不检查
+ * Manifest。返回 `true` 不表示权限已声明、平台已批准、Runtime snapshot 中存在、status 为 `enabled`、Host 支持，
+ * 或当前 capability 已获准执行。尤其 `network` 与 `companion` 还需要平台批准；其他 declaration 权限也继续受
+ * 各自适用的 Host、用户授权、可信手势、参数与业务策略约束。
+ *
+ * `MINI_PROGRAM_PERMISSION_CATALOG` 提供每个 key 的展示信息、access、风险、配置字段和 method 集合；具体 bridge
+ * method 是否要求某项权限应以 {@link MINI_PROGRAM_PROTOCOL_CAPABILITIES} 的 `requirement` 为准。`kind: 'none'`
+ * 的 method 不会因为某个 key 被本 guard 识别而新增权限要求。
+ *
+ * @example
+ * ```ts
+ * import { isManagedMiniProgramRuntimePermissionKey } from '@heybox/hb-sdk/protocol';
+ *
+ * function acceptPermissionKey(candidate: unknown) {
+ *   if (typeof candidate !== 'string') return undefined;
+ *   return isManagedMiniProgramRuntimePermissionKey(candidate) ? candidate : undefined;
+ * }
+ *
+ * acceptPermissionKey('filesystem'); // 'filesystem'
+ * acceptPermissionKey('network'); // 'network'
+ * acceptPermissionKey(' network '); // undefined：guard 不 trim
+ * acceptPermissionKey('network.request'); // undefined：legacy key 只由 snapshot parser 归一化
+ * ```
+ *
+ * @see [parseMiniProgramRuntimePermissions](/reference/symbols/protocol/functions/parseMiniProgramRuntimePermissions) 完整 snapshot 的 trim、legacy 归一化与 config 校验。
+ * @see [MINI_PROGRAM_PROTOCOL_CAPABILITIES](/reference/symbols/protocol/constants/MINI_PROGRAM_PROTOCOL_CAPABILITIES) method 到 permission requirement 的权威映射。
+ * @see [权限声明](/guide/permissions) Manifest 声明、平台批准与 Runtime 状态的完整流程。
+ */
 function isManagedMiniProgramRuntimePermissionKey(key) {
     return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
 }
+/**
+ * 将不可信的 schema v1 runtime permission snapshot 解析为独立的 canonical 权限映射。
+ *
+ * @param snapshot - Host、服务端、dev context 或持久化边界提供的普通反序列化数据；调用方不需要先做
+ * 类型断言。Proxy trap 或 getter 自身抛出的异常会原样传播。
+ * @returns {@link ParsedMiniProgramRuntimePermissions}。完整 snapshot 合法时返回
+ * `{ valid: true, permissions }`；顶层、entry、状态、重复 key 或已知 config 任一校验失败时统一
+ * 返回 `{ valid: false, permissions: {} }`，不会保留部分权限。
+ *
+ * @remarks
+ * 顶层必须是对象，`schema_version` 必须严格等于数字 `1`，`entries` 必须是数组。`revision`
+ * 可省略；存在时必须是大于或等于 `0` 的整数。revision 只参与输入校验，不会复制到返回值。
+ * 顶层与 entry 的其他字段会被忽略，以便 schema v1 内前向扩展。
+ *
+ * 每个 entry 必须是对象，`key` 必须是 trim 后非空的字符串，`status` 必须严格为
+ * `'enabled'` 或 `'disabled'`。解析器先 trim key，再把唯一的历史别名 `network.request`
+ * 归一为 canonical `network`；大小写不会转换。重复检查基于归一化后的所有 key，因此
+ * `network` 与 ` network.request ` 冲突，两个相同未知 future key 也会让整个 snapshot fail
+ * closed。
+ *
+ * 是否属于当前受管 key 由 {@link isManagedMiniProgramRuntimePermissionKey} 与权限目录决定。
+ * 为兼容较新服务端，非空、状态合法且不重复的未知 key 会被忽略；其 `config` 可以缺失、为
+ * `null`、数组或任意未来结构，均不会使已认识的权限失效。未知 entry 不会出现在返回映射中。
+ *
+ * 已知权限严格执行当前 schema：`network` 必须提供对象 config，且
+ * `useOfficialDomain` 必须是 boolean；其他额外 network config 字段会丢弃，返回值只复制该
+ * boolean。其余当前权限是无配置项权限，输入 config 可以缺失、为 `null` 或 `{}`，并统一输出
+ * `{}`；非空对象、数组或其他值会使整个 snapshot 无效。Runtime snapshot 必须显式包含
+ * network 的有效 boolean，即使 Manifest 目录把省略 `useOfficialDomain` 的开发者默认值定义为
+ * `false`。
+ *
+ * 返回的 canonical entry/config 都是新对象；修改原 snapshot、entry 或嵌套 network config
+ * 不会改变解析结果。`permissions` 是 Partial map：合法空 entries、只包含未知权限，或没有某个
+ * canonical key 时，解析仍可 `valid: true`，对应属性保持缺失。
+ *
+ * `valid: true` 只表示 snapshot 可安全消费，不代表 entry 已启用，更不代表某个 capability 已获
+ * 授权。Runtime consumer 应先查 {@link MINI_PROGRAM_PROTOCOL_CAPABILITIES} 中目标 method 的
+ * `requirement`：`kind: 'none'` 不读取权限；`kind: 'all'` 要求列出的每个 canonical entry 都存在
+ * 且 `status === 'enabled'`。之后仍需通过 Host capability、可信手势、用户授权、参数和业务
+ * policy。当前 Runtime 对 `valid: false` 按空权限表 fail closed，受保护 method 会得到
+ * `PERMISSION_NOT_DECLARED`，而不是沿用输入中的部分 enabled entry。
+ *
+ * @example
+ * ```ts
+ * import { parseMiniProgramRuntimePermissions } from '@heybox/hb-sdk/protocol';
+ *
+ * const parsed = parseMiniProgramRuntimePermissions({
+ *   schema_version: 1,
+ *   revision: 4,
+ *   entries: [
+ *     {
+ *       key: ' network.request ',
+ *       status: 'enabled',
+ *       config: { useOfficialDomain: false, futureField: 'discarded' },
+ *     },
+ *     { key: 'future.permission', status: 'disabled', config: null },
+ *   ],
+ * });
+ *
+ * // legacy key 已归一化；未知 future key 被忽略。
+ * if (parsed.valid && parsed.permissions.network?.status === 'enabled') {
+ *   console.log(parsed.permissions.network.config.useOfficialDomain); // false
+ *   // 继续执行 capability requirement、Host 与业务 policy 校验。
+ * }
+ * ```
+ *
+ * @see {@link ParsedMiniProgramRuntimePermissions}
+ * @see {@link MiniProgramRuntimePermissionsSnapshot}
+ * @see {@link isManagedMiniProgramRuntimePermissionKey}
+ * @see {@link MINI_PROGRAM_PROTOCOL_CAPABILITIES}
+ * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+ */
 function parseMiniProgramRuntimePermissions(snapshot) {
     if (!isRecord$4(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
         return { valid: false, permissions: {} };
@@ -3136,6 +3319,11 @@ function isRecord$3(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/**
+ * `package.json#heybox.platforms` 接受的平台值，顺序同时是 Manifest 的规范化输出顺序。
+ *
+ * @remarks 项目仍应只声明实际完成适配并经过验收的平台；模板默认值不是自动兼容承诺。
+ */
 const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', 'linux'];
 /** 窗口尺寸字段的脏值兜底上限；真正的上限是宿主侧显示器 workArea。 */
 const MINIAPP_WINDOW_SIZE_MAX = 16_384;
@@ -3154,6 +3342,49 @@ function hasMiniappDesktopPlatform(platforms) {
         return false;
     return MINIAPP_DESKTOP_PLATFORM_VALUES.some((platform) => platforms.includes(platform));
 }
+/**
+ * 判断小程序版本是否符合公开 Manifest 版本规则。
+ *
+ * @param version - 待判断的 `package.json.version` / Manifest 版本字符串；首尾空白会先被
+ * 移除，但函数不会把规范化后的字符串返回给调用方。
+ * @returns trim 后满足小程序严格版本规则时返回 `true`，否则返回 `false`。对类型声明允许的
+ * 字符串输入，该函数只返回布尔值，不抛出校验错误。
+ *
+ * @remarks
+ * 接受形式为 canonical SemVer `MAJOR.MINOR.PATCH[-PRERELEASE]`。trim 后的输入必须与
+ * `semver` 严格解析得到的 `version` 完全相同，因此不完整版本（如 `1.2`）、`v` / `=`
+ * 前缀、范围表达式、额外段，以及 major/minor/patch 或纯数字 prerelease 标识中的前导零
+ * 都返回 `false`。只有首尾空白会被忽略，内部空白不会被修复。
+ *
+ * 合法 prerelease（如 `1.2.3-alpha.1`、`0.0.1-rc.0`）可以使用。build metadata 即使符合
+ * 标准 SemVer（如 `1.2.3+build.1`）也被小程序发布合同显式禁止。模板占位 core
+ * `0.0.0` 同样禁止，包括 `0.0.0-alpha` 等 prerelease；至少应提升 patch/minor/major
+ * 之一，例如 `0.0.1-alpha.1`。
+ *
+ * 这是无 I/O、无状态修改的 predicate，适合表单即时判断。实际 Vite / `hb-sdk build`
+ * 流程会调用同规则的 package version validator：成功时返回 trim 后版本并写入 Manifest，
+ * 失败时抛出带 `package.json.version` 来源的错误；调用本函数为 `true` 不能跳过正式构建。
+ *
+ * {@link resolveMiniappManifestPlatforms} 处理的是 Manifest `sdkVersion` 对平台声明策略的
+ * SemVer precedence，不是当前小程序的发布 `version`。不要用本函数替代平台解析，也不要
+ * 把项目 version 当作 sdkVersion 传入。
+ *
+ * @example
+ * ```ts
+ * import { isValidVersion } from '@heybox/hb-sdk/miniapp-publish'
+ *
+ * isValidVersion(' 1.2.3 ') // true
+ * isValidVersion('1.2.3-alpha.1') // true
+ * isValidVersion('0.0.1-alpha.1') // true
+ * isValidVersion('1.2') // false
+ * isValidVersion('v1.2.3') // false
+ * isValidVersion('1.2.3+build.1') // false
+ * isValidVersion('0.0.0-alpha') // false
+ * ```
+ *
+ * @see {@link resolveMiniappManifestPlatforms}
+ * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
+ */
 function isValidMiniappManifestVersion(version) {
     return getMiniappManifestVersionError(version) === undefined;
 }
@@ -3392,33 +3623,59 @@ function formatReason$1(error) {
     return String(error);
 }
 
+/** CDN 上传接口使用的小程序产物业务 scope。 */
 const MINIAPP_UPLOAD_SCOPE = 'activity';
+/** 完整 CDN 上传 key 的默认长度上限；旧固定版本流程按字符计数，上传会话流程按 UTF-8 bytes 计数。 */
 const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
+/** 单次向 CDN 申请上传信息时包含的最大文件数；当前合同固定为 `50`。 */
 const MINIAPP_UPLOAD_BATCH_SIZE = 50;
+/** Web 构建产物的默认总大小上限，单位为 bytes；当前为 100 MiB。 */
 const MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES = 100 * 1024 * 1024;
-/** 与 Activity 上传后端合同一致的 Companion 归档总大小上限。 */
+/** Companion 归档的临时总大小上限，单位为 bytes；当前为 500 MiB。 */
 const MINIAPP_COMPANION_UPLOAD_TEMPORARY_SIZE_LIMIT_BYTES = 500 * 1024 * 1024;
+/** 查询当前开发者账号是否具备小程序访问资格的开放平台 API 路径。 */
 const USER_MINIPROGRAM_ACCESS_STATUS_API_PATH = '/mall/developer/user_miniprogram/access_status';
+/** 查询当前开发者可管理主体列表的开放平台 API 路径。 */
 const DEVELOPER_ENTITY_LIST_API_PATH = '/mall/developer/entity/list';
+/** 切换当前开发者主体的开放平台 API 路径。 */
 const DEVELOPER_ENTITY_SWITCH_API_PATH = '/mall/developer/entity/switch';
+/** 查询当前主体下小程序列表的开放平台 API 路径。 */
 const LIST_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/list';
+/** 创建小程序的开放平台 API 路径。 */
 const CREATE_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/create';
+/** 查询单个小程序详情的开放平台 API 路径。 */
 const DETAIL_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/detail';
+/** 创建本地开发启动凭据的开放平台 API 路径。 */
 const CREATE_USER_MINIPROGRAM_LOCAL_DEV_LAUNCH_TOKEN_API_PATH = '/mall/developer/user_miniprogram/local_dev_launch_token';
+/** 查询小程序预览白名单的开放平台 API 路径。 */
 const USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = '/mall/developer/user_miniprogram/preview_allowlist';
+/** 更新小程序预览白名单的开放平台 API 路径。 */
 const UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = '/mall/developer/user_miniprogram/preview_allowlist/update';
+/** 创建小程序云排行榜的开放平台 API 路径。 */
 const CREATE_USER_MINIPROGRAM_LEADERBOARD_API_PATH = '/mall/developer/user_miniprogram/leaderboard/create';
+/** 查询单个小程序云排行榜详情的开放平台 API 路径。 */
 const DETAIL_USER_MINIPROGRAM_LEADERBOARD_API_PATH = '/mall/developer/user_miniprogram/leaderboard/detail';
+/** 查询小程序云排行榜列表的开放平台 API 路径。 */
 const LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH = '/mall/developer/user_miniprogram/leaderboard/list';
+/** 删除小程序云排行榜的开放平台 API 路径。 */
 const DELETE_USER_MINIPROGRAM_LEADERBOARD_API_PATH = '/mall/developer/user_miniprogram/leaderboard/delete';
+/** 在上传或复用版本前执行发布预检的开放平台 API 路径。 */
 const PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH = '/mall/developer/user_miniprogram/version/precheck';
+/** 将小程序版本提交审核的开放平台 API 路径。 */
 const SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH = '/mall/developer/user_miniprogram/version/submit_audit';
+/** 查询小程序版本预览信息的开放平台 API 路径。 */
 const USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH = '/mall/developer/user_miniprogram/version/preview_info';
+/** 撤回待审核小程序版本的开放平台 API 路径。 */
 const WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH = '/mall/developer/user_miniprogram/version/withdraw';
+/** 发布审核通过的小程序版本的开放平台 API 路径。 */
 const RELEASE_USER_MINIPROGRAM_VERSION_API_PATH = '/mall/developer/user_miniprogram/version/release';
+/** 下架当前线上小程序的开放平台 API 路径。 */
 const TAKE_DOWN_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/take_down';
+/** 重新开放已下架小程序的开放平台 API 路径。 */
 const REOPEN_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/reopen';
+/** 更新小程序广场展示状态的开放平台 API 路径。 */
 const UPDATE_SQUARE_DISPLAY_API_PATH = '/mall/developer/user_miniprogram/square_display/update';
+/** 查询小程序历史版本列表的开放平台 API 路径。 */
 const LIST_USER_MINIPROGRAM_VERSION_API_PATH = '/mall/developer/user_miniprogram/version/list';
 const FNV_OFFSET = 0x811c9dc5;
 const FNV_PRIME = 0x01000193;
@@ -3426,17 +3683,114 @@ const MINIAPP_UPLOAD_SESSION_REF_LENGTH = 10;
 const MINIAPP_ARTIFACT_SIGNATURE_MAGIC = 'heybox-user-miniprogram-artifact\0v1\0';
 const UNPAIRED_SURROGATE_PATTERN = /[\ud800-\udbff](?![\udc00-\udfff])|(^|[^\ud800-\udbff])[\udc00-\udfff]/;
 const textEncoder = new TextEncoder();
+/**
+ * 将扫描到的相对路径转换为统一的 `/` 分隔形式。
+ *
+ * @param relativePath - 待整理的构建产物路径。TypeScript 入口声明为字符串；JavaScript 运行时会
+ * 先计算 `relativePath || ''`，再通过 `String(...)` 强制转换。
+ * @returns 仅统一分隔符形态的新字符串：所有 `\\` 转为 `/`，所有前导 `/` 被删除，其余连续
+ * `/` 合并为一个。空字符串以及运行时传入的 `undefined`、`null`、`false`、`0`、`NaN` 等
+ * falsy 值返回 `''`；truthy 非字符串按标准 `String(value)` 结果继续整理。
+ *
+ * @remarks
+ * 这是面向 build/deploy 文件扫描结果的**格式 helper**，不是路径安全校验或 canonical path
+ * parser。它不会 trim、URL decode、Unicode normalize、解析盘符，也不会拒绝或消解 `.` / `..`
+ * segment、控制字符、Windows drive prefix 或尾随 `/`。例如 `/etc/passwd` 会变成
+ * `etc/passwd`，`C:\\temp\\app.js` 会变成 `C:/temp/app.js`，`assets/../secret/` 仍保留点段
+ * 和尾随 slash；调用方不能根据返回值推断原输入是安全相对路径。
+ *
+ * SDK 的 build/deploy 流程会把扫描路径先用本函数统一分隔符，再分别使用
+ * {@link relativePathContainsNodeModulesSegment} 排除完整 `node_modules` 目录段、用
+ * {@link shouldUploadDistFile} 过滤根 `manifest.json` / `.DS_Store` / source map。`hb-sdk build`
+ * 随后校验大小预算；`hb-sdk remote deploy` 还会在签名和上传前通过
+ * `validateUploadPaths()`、`prepareMiniappArtifactFiles()` 或
+ * `validateMiniappUploadPathLengths()` 执行真正的空路径、点段、控制字符、重复和长度校验。
+ * 这些步骤不能由本函数单独替代；`shouldUploadDistFile()` 也不会自行检查 `node_modules`。
+ *
+ * 不要把本函数与 `@heybox/hb-sdk/protocol` 的 `isMiniProgramRelativePath()` 混用：协议 guard
+ * 不做转换，只接受已经规范的非空字符串，并拒绝前导/尾随 `/`、反斜杠、空 segment、`.`、
+ * `..` 与控制字符；本函数则会改写部分非法形态并保留其余不安全内容。
+ *
+ * @example
+ * ```ts
+ * import { normalizeRelativePath } from '@heybox/hb-sdk/miniapp-publish';
+ *
+ * normalizeRelativePath('///dist\\assets//app.js'); // 'dist/assets/app.js'
+ * normalizeRelativePath('assets/../secret///'); // 'assets/../secret/'，仍需安全校验
+ * normalizeRelativePath(123 as unknown as string); // '123'，JavaScript 运行时强制转换
+ * normalizeRelativePath(0 as unknown as string); // ''，falsy 值先回退为空串
+ * ```
+ *
+ * @see {@link relativePathContainsNodeModulesSegment}
+ * @see {@link shouldUploadDistFile}
+ * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/protocol/functions/isMiniProgramRelativePath | isMiniProgramRelativePath}
+ */
 function normalizeRelativePath(relativePath) {
     return String(relativePath || '')
         .replace(/\\/g, '/')
         .replace(/^\/+/, '')
         .replace(/\/+/g, '/');
 }
+/**
+ * 判断路径中是否包含大小写不敏感的完整 `node_modules` 目录段。
+ *
+ * @param relativePath - 待检查的构建产物路径。函数先通过 {@link normalizeRelativePath} 把
+ * 反斜杠改为 `/`、删除前导 `/` 并合并连续 `/`，再按 `/` 分段。
+ * @returns 至少一个非空段大小写不敏感地等于完整 `node_modules` 时返回 `true`；空路径、
+ * 空段及 `node_modules.txt`、`node_modules-old`、`@node_modules` 等相似名称返回 `false`。
+ *
+ * @remarks
+ * 比较使用每个非空 segment 的 `toLowerCase() === 'node_modules'`，因此根目录或任意深度的
+ * `node_modules`、`NODE_MODULES`、`Node_Modules` 都会命中。前导和重复 slash 会先被
+ * `normalizeRelativePath` 整理；尾随 slash 产生的空段会被忽略。
+ *
+ * 这是同步、无副作用的**单一 predicate**，只回答“规范化后的文本是否包含该完整段”。它
+ * 不 trim segment、不进行 URL/percent decode、Unicode normalize 或文件系统解析。例如
+ * `node_modules%2Fpkg/index.js`、`%6eode_modules/pkg.js` 和 `node_modules.txt` 都不会命中；调用方
+ * 不应传 URL，也不能把未命中解释为路径安全。
+ *
+ * 本函数不会拒绝或消解 `.` / `..`、绝对路径、Windows drive prefix、控制字符、空路径、
+ * symlink、重复路径或超长路径。`assets/../node_modules/pkg.js` 仍会命中，因为点段保持原样；
+ * 不含 `node_modules` 的危险路径则仍可能返回 `false`。签名或上传前必须继续执行对应的上传
+ * 路径规范、唯一性和长度校验。
+ *
+ * SDK build/deploy 会在文件扫描后用本函数拒绝整个 `node_modules` 树，再用
+ * {@link shouldUploadDistFile} 排除根 `manifest.json`、`.DS_Store` 和 source map。build 随后
+ * 校验大小预算；deploy 还会执行上传路径安全、唯一性、长度与签名校验。这些步骤互不替代：`shouldUploadDistFile()` 本身不检查
+ * `node_modules`，本函数也不决定普通文件是否应该上传。
+ *
+ * @example
+ * ```ts
+ * import { relativePathContainsNodeModulesSegment } from '@heybox/hb-sdk/miniapp-publish';
+ *
+ * relativePathContainsNodeModulesSegment('dist\\NODE_MODULES/pkg/index.js'); // true
+ * relativePathContainsNodeModulesSegment('dist//vendor///node_modules/'); // true
+ * relativePathContainsNodeModulesSegment('dist/node_modules.txt'); // false
+ * relativePathContainsNodeModulesSegment('dist/node_modules%2Fpkg.js'); // false，不做 URL decode
+ * relativePathContainsNodeModulesSegment('assets/../secret.js'); // false，但这不代表路径安全
+ * ```
+ *
+ * @see [normalizeRelativePath](/reference/symbols/miniapp-publish/functions/normalizeRelativePath)
+ * @see [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile)
+ * @see [miniapp-publish](/reference/miniapp-publish/)
+ */
 function relativePathContainsNodeModulesSegment(relativePath) {
     return normalizeRelativePath(relativePath)
         .split('/')
         .some((segment) => segment.length > 0 && segment.toLowerCase() === 'node_modules');
 }
+/**
+ * 为小程序 ID 计算稳定、紧凑的上传路径别名。
+ *
+ * @param miniProgramId - 小程序 ID。
+ * @returns 基于 32-bit FNV-1a 结果生成的 base36 字符串。
+ * @remarks 该别名只用于缩短上传 key，不是加密摘要，也不能用于鉴权或隐藏小程序身份。
+ * @example
+ * ```ts
+ * const alias = getMiniProgramUploadAlias('mp_example');
+ * console.log(/^[a-z0-9]+$/.test(alias)); // true
+ * ```
+ */
 function getMiniProgramUploadAlias(miniProgramId) {
     let hash = FNV_OFFSET;
     const input = String(miniProgramId || '');
@@ -3446,6 +3800,63 @@ function getMiniProgramUploadAlias(miniProgramId) {
     }
     return hash.toString(36);
 }
+/**
+ * 校验一组构建产物的总大小是否超过给定上限。
+ *
+ * @param items - 要累计的条目。函数按数组顺序读取每项 `size`，经 `Number(...)` 转换后仅
+ * 累加有限且大于 `0` 的值；不修改、过滤或排序输入数组，也不读取 `relativePath`。
+ * @param options - 可选 byte 上限；默认 `104857600` bytes（100 MiB）。自定义上限不会改变
+ * 固定错误文案。
+ * @returns 总和严格大于上限时返回唯一固定字符串
+ * `构建产物总大小超过 100MB，请删除未引用资源或压缩图片后重新 deploy`；总和小于或等于
+ * 上限时返回 `undefined`。函数不会因超限抛异常，调用方决定是否把返回文本转成 `Error`。
+ *
+ * @remarks
+ * 计算等价于把每项规范成 `Number.isFinite(Number(size)) && Number(size) > 0 ? Number(size) : 0`
+ * 后求和，不取整、不去重，也不设置单文件上限。因此一个文件可以占满全部预算，多个同路径
+ * 条目会重复计数，正小数会按 JavaScript number 原值加入；总和恰等 `limitBytes` 时通过，
+ * 多 1 byte 才返回错误。
+ *
+ * 在声明的 TypeScript 输入契约内，该函数以返回值报告预算结果，不为非有限/非正 size 抛错。
+ * 固定错误文本不包含首个文件、实际总量或自定义上限，即使测试/集成传了其他 `limitBytes`，
+ * 文案仍写 `100MB` 和 `重新 deploy`。`hb-sdk build` 的调用方会把末尾提示改成 `重新 build`。
+ *
+ * 该函数只校验一个未分组列表的总量，不读取文件系统，不执行 stat，也不校验路径、安全性、
+ * 文件数量、重复项、单文件大小或内容。调用方应先用
+ * [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile) 选择真正
+ * 上传的文件，并完成 `node_modules`、路径规范/唯一性/长度等校验；被提前过滤的 Manifest、
+ * `.DS_Store` 和 source map 才不会计入总量。
+ *
+ * Web 与 Companion 需要独立预算时使用 `validateMiniappUploadSizeBudgets()`：它按
+ * `relativePath` 的 `companions/` 前缀分组，Web 组复用本函数的默认 100 MiB 规则，Companion
+ * 组使用独立 500 MiB 上限。直接调用本函数不会识别或分开这些路径。
+ *
+ * @example
+ * ```ts
+ * import { validateUploadTotalSize } from '@heybox/hb-sdk/miniapp-publish';
+ *
+ * const atLimit = validateUploadTotalSize(
+ *   [
+ *     { relativePath: 'assets/app.js', size: 1_024 },
+ *     { relativePath: 'assets/ignored-negative.js', size: -1 },
+ *     { relativePath: 'assets/ignored-nan.js', size: Number.NaN },
+ *   ],
+ *   { limitBytes: 1_024 },
+ * )
+ * console.log(atLimit) // undefined，恰等上限
+ *
+ * const overLimit = validateUploadTotalSize(
+ *   [{ relativePath: 'assets/app.js', size: 1_025 }],
+ *   { limitBytes: 1_024 },
+ * )
+ * if (overLimit) throw new Error(overLimit)
+ * ```
+ *
+ * @see {@link UploadSizeItem}
+ * @see {@link ValidateUploadTotalSizeOptions}
+ * @see [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile)
+ * @see [miniapp-publish](/reference/miniapp-publish/)
+ */
 function validateUploadTotalSize(items, options = {}) {
     const limit = options.limitBytes ?? MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES;
     const total = items.reduce((sum, item) => {
@@ -3457,6 +3868,22 @@ function validateUploadTotalSize(items, options = {}) {
     }
     return undefined;
 }
+/**
+ * 分别校验 Web 构建产物与 Companion 归档的总大小预算。
+ *
+ * @param items - 全部待上传文件；规范化后以 `companions/` 开头的路径计入 Companion 预算，其余计入 Web 预算。
+ * @param options - 可选测试或集成覆盖项：`webLimitBytes` 为 Web 上限，`companionLimitBytes` 为 Companion 上限，单位均为 bytes。
+ * @returns Web 或 Companion 的第一个超限提示；两类总量均不超过各自上限时返回 `undefined`。
+ * @remarks Web 默认上限为 100 MiB，Companion 默认上限为 500 MiB；两类预算不会相互借用。
+ * @example
+ * ```ts
+ * const error = validateMiniappUploadSizeBudgets([
+ *   { relativePath: 'index.html', size: 1_024 },
+ *   { relativePath: 'companions/runner/windows-x64.zip', size: 8_192 },
+ * ]);
+ * if (error) throw new Error(error);
+ * ```
+ */
 function validateMiniappUploadSizeBudgets(items, options = {}) {
     const companionItems = items.filter((item) => normalizeRelativePath(item.relativePath).startsWith('companions/'));
     const webItems = items.filter((item) => !normalizeRelativePath(item.relativePath).startsWith('companions/'));
@@ -3469,6 +3896,59 @@ function validateMiniappUploadSizeBudgets(items, options = {}) {
         return 'Companion 归档总大小超过 500MiB 上限，请缩减归档后重新 deploy';
     return undefined;
 }
+/**
+ * 判断 `dist` 中的文件是否应作为版本产物上传。
+ *
+ * @param relativePath - `dist` 根目录下的文件路径。判断前先经 {@link normalizeRelativePath}
+ * 统一斜杠、删除前导 `/` 并合并连续 `/`；函数不读取文件系统或文件内容。
+ * @returns 以下规范化结果返回 `false`：空路径、精确等于根 `manifest.json`、精确 basename 为
+ * `.DS_Store` 的任意层级路径，以及以大小写不敏感 `.map` 结尾的路径。其他值返回 `true`。
+ *
+ * @remarks
+ * 过滤顺序以 `normalizeRelativePath(relativePath)` 的结果为准：
+ *
+ * - `''` 返回 `false`。
+ * - 只有精确根路径 `manifest.json` 返回 `false`；`/manifest.json` 规范化后也会命中。
+ *   `assets/manifest.json` 会保留，因为它不是根文件。匹配大小写敏感，所以
+ *   `Manifest.json` 不会作为生成 Manifest 被过滤。
+ * - 根或任意子目录中精确名为 `.DS_Store` 的最终 segment 返回 `false`，匹配大小写敏感；
+ *   `.ds_store`、`.DS_Store.bak` 会保留。
+ * - 整条规范化路径经 `toLowerCase()` 后以 `.map` 结尾即返回 `false`，因此 `.map`、
+ *   `app.js.map`、`app.js.MAP` 都会过滤，而 `app.js.map.txt` 会保留。
+ *
+ * 根 `manifest.json` 是发布流水线单独读取并上送后台的版本元数据，不作为 CDN 文件上传；
+ * 子目录同名文件仍被视为普通业务产物。该 predicate 只做上传集合选择，不验证输入确实是
+ * 文件，也不检查扩展名白名单、文件存在性或内容。
+ *
+ * `true` 不代表路径安全。本函数不会 URL decode，也不会拒绝 `node_modules`、symlink、绝对
+ * 路径、Windows drive prefix、`.` / `..`、空 segment、控制字符、重复路径或超长路径。
+ * build/deploy 必须另外使用 {@link relativePathContainsNodeModulesSegment} 拒绝依赖目录；deploy
+ * 还需在签名/上传前执行路径规范、唯一性和长度校验。
+ *
+ * build/deploy 会先扫描并完成上述独立边界，再以本函数过滤候选文件。build 对保留文件校验
+ * 上传大小预算；deploy 额外执行 artifact 排序/签名与路径长度校验。因此被过滤的根 Manifest、Finder
+ * 元数据和 source map 不计入上传文件数或大小；本函数自身不读取 `size`，也不能替代
+ * `validateUploadTotalSize()` / `validateMiniappUploadSizeBudgets()`。
+ *
+ * @example
+ * ```ts
+ * import { shouldUploadDistFile } from '@heybox/hb-sdk/miniapp-publish';
+ *
+ * shouldUploadDistFile('/manifest.json'); // false，规范化后是根 manifest.json
+ * shouldUploadDistFile('assets/manifest.json'); // true
+ * shouldUploadDistFile('assets/.DS_Store'); // false
+ * shouldUploadDistFile('assets/.ds_store'); // true，.DS_Store 区分大小写
+ * shouldUploadDistFile('assets/app.js.MAP'); // false，.map 后缀不区分大小写
+ * shouldUploadDistFile('assets/app.js.map.txt'); // true
+ * shouldUploadDistFile('node_modules/pkg/index.js'); // true，必须另做 node_modules 检查
+ * shouldUploadDistFile('assets/../secret.js'); // true，但这不代表路径安全
+ * ```
+ *
+ * @see [normalizeRelativePath](/reference/symbols/miniapp-publish/functions/normalizeRelativePath)
+ * @see [relativePathContainsNodeModulesSegment](/reference/symbols/miniapp-publish/functions/relativePathContainsNodeModulesSegment)
+ * @see [validateUploadTotalSize](/reference/symbols/miniapp-publish/functions/validateUploadTotalSize)
+ * @see [miniapp-publish](/reference/miniapp-publish/)
+ */
 function shouldUploadDistFile(relativePath) {
     const normalized = normalizeRelativePath(relativePath);
     if (!normalized) {
@@ -3486,11 +3966,22 @@ function shouldUploadDistFile(relativePath) {
     return true;
 }
 /**
- * 校验构建产物路径和大小，并按路径 UTF-8 字节序排序。
+ * 校验构建产物路径和大小，并按路径的 UTF-8 字节序稳定排序。
+ *
+ * @param files - 待处理的构建产物文件；允许携带 `absolutePath`、`sha256` 等附加字段。
+ * @returns 新建的有序文件列表；每个结果保留输入条目的附加字段，输入数组顺序不变。
+ * @throws `Error` 当文件数超过 uint32、路径为空或不规范、路径重复，或大小不是非负 safe integer 时抛出。
+ * @remarks 路径必须已经使用规范 `/` 分隔形式；此函数不会把反斜杠或点目录段自动改写为其他路径。
+ * @example
+ * ```ts
+ * const files = prepareMiniappArtifactFiles([
+ *   { relativePath: 'index.html', size: 15, absolutePath: '/tmp/dist/index.html' },
+ *   { relativePath: 'assets/app.js', size: 42, absolutePath: '/tmp/dist/assets/app.js' },
+ * ]);
  *
- * @param files - 待处理的构建产物文件。
- * @returns 保留输入附加字段的有序文件列表。
- * @throws 路径不规范、路径重复或文件大小非法时抛出错误。
+ * console.log(files.map((file) => file.relativePath));
+ * // ['assets/app.js', 'index.html']
+ * ```
  */
 function prepareMiniappArtifactFiles(files) {
     if (files.length > 0xffffffff) {
@@ -3511,9 +4002,19 @@ function prepareMiniappArtifactFiles(files) {
 /**
  * 按服务端 session key 前缀校验最终上传路径的 UTF-8 字节长度。
  *
- * @param files - 待上传的构建产物文件。
- * @param options - 小程序和长度限制配置。
+ * @param files - 待上传的构建产物文件；每个路径都必须是规范相对路径。
+ * @param options - `miniProgramId` 用于计算上传别名，`maxLength` 是完整 key 的最大 UTF-8 bytes，默认 {@link ACTIVITY_UPLOAD_KEY_MAX_LENGTH}。
  * @returns 第一个超长路径的错误提示；全部合法时返回 `undefined`。
+ * @throws `Error` 当任一文件路径为空或不符合构建产物路径规则时抛出。
+ * @remarks 会话引用按固定 10 个 ASCII 字符估算，因此该校验不依赖真实 session ID。
+ * @example
+ * ```ts
+ * const error = validateMiniappUploadPathLengths(
+ *   [{ relativePath: 'assets/app.js' }],
+ *   { miniProgramId: 'mp_example' },
+ * );
+ * if (error) throw new Error(error);
+ * ```
  */
 function validateMiniappUploadPathLengths(files, options) {
     const maxLength = options.maxLength ?? ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
@@ -3528,9 +4029,14 @@ function validateMiniappUploadPathLengths(files, options) {
 /**
  * 创建 v1 整包签名头。
  *
- * @param fileCount - 参与签名的文件数量。
- * @returns 包含协议标识和文件数量的字节数组。
- * @throws 文件数量超出协议范围时抛出错误。
+ * @param fileCount - 参与签名的文件数量；必须是 `0` 到 `0xffffffff` 的整数。
+ * @returns 新的字节数组，依次包含固定协议标识和 big-endian uint32 文件数。
+ * @throws `Error` 当文件数不是整数、为负数或超出 uint32 范围时抛出。
+ * @example
+ * ```ts
+ * const header = createMiniappArtifactSignatureHeader(2);
+ * // 将 header 写入 SHA-256，再按排序结果依次写入文件 header 和内容。
+ * ```
  */
 function createMiniappArtifactSignatureHeader(fileCount) {
     if (!Number.isInteger(fileCount) || fileCount < 0 || fileCount > 0xffffffff) {
@@ -3541,9 +4047,16 @@ function createMiniappArtifactSignatureHeader(fileCount) {
 /**
  * 创建单个文件的 v1 framing header。
  *
- * @param file - 已规范化或待校验的构建产物文件。
- * @returns 包含路径长度、路径和文件大小的字节数组。
- * @throws 文件路径或大小非法时抛出错误。
+ * @param file - 构建产物文件；路径必须规范，大小必须是非负 safe integer。
+ * @returns 新的字节数组，依次包含 big-endian uint32 路径字节数、UTF-8 路径和 big-endian uint64 文件大小。
+ * @throws `Error` 当路径为空或不规范，或大小不是非负 safe integer 时抛出。
+ * @example
+ * ```ts
+ * const header = createMiniappArtifactFileHeader({
+ *   relativePath: 'assets/app.js',
+ *   size: 42,
+ * });
+ * ```
  */
 function createMiniappArtifactFileHeader(file) {
     const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
@@ -3554,11 +4067,28 @@ function createMiniappArtifactFileHeader(file) {
 /**
  * 校验服务端 session 文件映射，并计算仍需上传的文件。
  *
- * @param localFiles - 本地构建产物文件。
- * @param serverFiles - 服务端签发的文件映射。
- * @param uploadedKeys - 服务端已确认上传成功的 key。
- * @returns 完整映射、待上传文件和已确认 key。
- * @throws 服务端映射与本地产物不一致时抛出错误。
+ * @param localFiles - 本地构建产物 receipt；除 `relativePath` 和 `size` 外，每项必须包含 64 位小写十六进制 `sha256`。
+ * @param serverFiles - 服务端签发的文件映射；数量、路径、大小和 SHA-256 必须与本地产物一一一致。
+ * @param uploadedKeys - 服务端已确认上传成功的 key；每个值都必须属于当前会话，重复值会被去重。
+ * @returns
+ * 包含三个字段的对象：`files` 是按路径 UTF-8 字节序排列的全部 `{ file, key }` 映射，
+ * `missingFiles` 是其中尚未确认上传的映射，`uploadedKeys` 是去重后的已上传 key。
+ * @throws `Error` 当本地产物不规范，服务端映射数量或字段无效、重复或不匹配，或已上传 key 不属于当前产物时抛出。
+ * @example
+ * ```ts
+ * const resolved = resolveMiniappUploadSessionFiles(
+ *   [{ relativePath: 'index.html', size: 15, sha256: 'a'.repeat(64) }],
+ *   [{
+ *     relative_path: 'index.html',
+ *     key: '/u/abc/sessionref/index.html',
+ *     size: 15,
+ *     sha256: 'a'.repeat(64),
+ *   }],
+ *   [],
+ * );
+ *
+ * console.log(resolved.missingFiles.length); // 1
+ * ```
  */
 function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys) {
     const preparedFiles = prepareMiniappArtifactFiles(localFiles);
@@ -3621,7 +4151,33 @@ function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys)
         uploadedKeys: [...completed],
     };
 }
-/** 校验 Manifest 中所有 Companion 归档都精确属于当前上传 receipt。 */
+/**
+ * 校验 Manifest 中所有 Companion 归档都精确属于当前上传 receipt。
+ *
+ * @param companions - `manifest.companions` 原始值；没有 Companion 时传 `undefined`。
+ * @param files - 当前版本的逐文件上传 receipt；只有 `companions/` 前缀文件参与本校验。
+ * @returns 校验成功时不返回值。
+ * @throws `Error` 当必要的 `targets`/artifact 字段缺失，引用不存在的归档、大小或 SHA-256 不一致，
+ * 或 receipt 中存在未被 Manifest 引用的 Companion 归档时抛出。
+ * @remarks 本函数只交叉校验 Companion 声明与上传 receipt，不替代完整 Manifest schema 校验。
+ * 非 Companion Web 文件会被忽略；`companions` 省略时 receipt 中也不能存在 Companion 归档。
+ * @example
+ * ```ts
+ * const receipt = [{
+ *   relativePath: 'companions/runner/windows-x64.zip',
+ *   size: 42,
+ *   sha256: 'a'.repeat(64),
+ * }];
+ *
+ * validateMiniappCompanionFileReceipts({
+ *   runner: {
+ *     targets: {
+ *       'windows-x64': { path: receipt[0].relativePath, size: 42, sha256: receipt[0].sha256 },
+ *     },
+ *   },
+ * }, receipt);
+ * ```
+ */
 function validateMiniappCompanionFileReceipts(companions, files) {
     const companionFiles = new Map(files.filter((file) => file.relativePath.startsWith('companions/')).map((file) => [file.relativePath, file]));
     if (companions === undefined) {