@heybox/hb-sdk 0.8.2-alpha.1 → 0.8.2-alpha.5

package/types/miniapp-manifest/schema.d.ts

@@ -1,7 +1,13 @@
 import { type MiniappPermissionDeclarations } from './permissions';
 import type { MiniappCompanionManifestDeclarations } from './companion-types';
 export declare const MINIAPP_TEMPLATE_VERSION = "0.0.0";
+/**
+ * `package.json#heybox.platforms` 接受的平台值，顺序同时是 Manifest 的规范化输出顺序。
+ *
+ * @remarks 项目仍应只声明实际完成适配并经过验收的平台；模板默认值不是自动兼容承诺。
+ */
 export declare const MINIAPP_PLATFORM_VALUES: readonly ["android", "ios", "ohos", "windows", "macos", "linux"];
+/** `package.json#heybox.platforms` 中单个平台标识。 */
 export type MiniappPlatform = (typeof MINIAPP_PLATFORM_VALUES)[number];
 /** 平台声明硬切点：产物 hb-sdk 版本达到该值时，必须显式声明非空 `platforms`。 */
 export declare const MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION = "0.9.0";
@@ -45,6 +51,9 @@ export declare const MINIAPP_DESKTOP_PLATFORM_VALUES: readonly ["windows", "maco
 export declare function hasMiniappDesktopPlatform(platforms: readonly MiniappPlatform[] | undefined): boolean;
 export interface MiniappManifest {
     [key: string]: unknown;
+    name?: string;
+    icon?: string;
+    coverImages?: string[];
     sdkVersion: string;
     version: string;
     platforms: readonly MiniappPlatform[];
@@ -57,6 +66,49 @@ export interface ParseMiniappManifestResult {
     manifest: MiniappManifest;
     hadBom: boolean;
 }
+/**
+ * 判断小程序版本是否符合公开 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}
+ */
 export declare function isValidMiniappManifestVersion(version: string): boolean;
 export declare function validateMiniappPackageVersionForBuild(version: string): string;
 export declare function validateMiniappManifestVersion(version: unknown, sourceLabel?: string): string;
@@ -69,46 +121,117 @@ export declare function validateMiniappManifestForDeploy(manifest: MiniappManife
     permissions?: Partial<Record<"userInfo" | "steamLibrary" | "share" | "storage" | "filesystem" | "clipboard" | "leaderboard" | "companion", import("./permissions").SimpleMiniappPermissionDeclaration> & {
         network: import("./permissions").NetworkMiniappPermissionDeclaration;
     }> | undefined;
+    platforms: readonly ("android" | "ios" | "ohos" | "windows" | "macos" | "linux")[];
+    name?: string | undefined;
+    icon?: string | undefined;
+    coverImages?: string[] | undefined;
     version: string;
     sdkVersion: string;
-    platforms: readonly ("android" | "ios" | "ohos" | "windows" | "macos" | "linux")[];
 };
 export declare function validateMiniappPlatforms(platforms: unknown, sourceLabel?: string): readonly MiniappPlatform[];
 export declare function areMiniappPlatformsEqual(left: readonly MiniappPlatform[], right: readonly MiniappPlatform[]): boolean;
-/** 平台解析策略：显式声明，或历史产物缺少声明时的移动端兼容。 */
+/**
+ * Manifest 平台解析所采用的策略。
+ *
+ * @remarks
+ * - `explicit`：Manifest 自身拥有合法、非空的 `platforms` 字段；无论 sdkVersion 是否低于
+ *   `0.9.0`，显式声明都优先且不会被兼容默认值覆盖。
+ * - `legacy_mobile_default`：Manifest 完全没有 `platforms` 字段，且 sdkVersion 缺失/空白或
+ *   SemVer precedence 低于 `0.9.0`；最终按 `android`、`ios`、`ohos` 历史集合兼容。
+ */
 export type MiniappPlatformPolicy = 'explicit' | 'legacy_mobile_default';
 /**
- * Manifest 平台解析结果，供 CLI、开放平台网页、后端与 Runtime 共用。
+ * Manifest 平台声明的规范化解析结果，供 CLI、开放平台网页、后端与 Runtime 共用。
  *
  * @remarks
- * `declared` 是规范化后的显式声明，历史兼容场景为空数组；`effective` 是用于展示与运行
- * 判断的最终平台集合。调用方不得自行比较 `0.9.0` 或补默认值，只能消费该结果。
+ * 返回对象通过 `Object.freeze()` 冻结，字段和数组在类型层也都是只读值。调用方应把其中
+ * 的数组视为不可变集合，不要修改、重新排序或自行合并 fallback。`platformsDeclared` 与
+ * `policy` 用于保留“显式三移动端”与“历史默认三移动端”的来源差异。
  */
 export interface MiniappPlatformResolution {
-    /** 规范化后的显式平台声明；历史兼容场景为空数组。 */
+    /**
+     * 规范化后的显式声明。`explicit` 时按固定顺序
+     * `android`、`ios`、`ohos`、`windows`、`macos`、`linux` 排列并只保留声明项；
+     * `legacy_mobile_default` 时是冻结的空数组，表示历史产物没有声明，而不是“不支持平台”。
+     */
     readonly declared: readonly MiniappPlatform[];
-    /** 最终生效的平台集合：显式声明原样使用，历史产物为移动端兼容集合。 */
+    /**
+     * 最终用于展示、校验和运行判断的平台集合。`explicit` 时与规范化后的 `declared` 相同；
+     * `legacy_mobile_default` 时固定为 `android`、`ios`、`ohos`。
+     */
     readonly effective: readonly MiniappPlatform[];
-    /** 是否显式声明了 `platforms`，用于区分显式移动端声明与历史移动端默认。 */
+    /**
+     * Manifest 是否拥有经过校验的显式 `platforms` 字段。显式声明三移动端时为 `true`，
+     * 历史 fallback 得到相同 effective 集合时仍为 `false`。
+     */
     readonly platformsDeclared: boolean;
-    /** 本次解析采用的策略。 */
+    /** 本次解析采用的来源策略；与 `platformsDeclared` 保持一致。 */
     readonly policy: MiniappPlatformPolicy;
 }
 /**
  * 解析 Manifest 平台声明，是 `0.9.0` 硬切规则的唯一实现。
  *
+ * @param sdkVersion - 产物写入 Manifest 的 hb-sdk 版本，不是小程序自身的发布 version。
+ * `undefined`、空字符串和纯空白按历史“缺失 sdkVersion”处理；其他字符串会先 trim，再按
+ * canonical strict SemVer 校验并参与 precedence 比较。
+ * @param manifest - 待解析的不可信 Manifest。必须是非 `null`、非数组的对象；函数只读取其
+ * 自有 `platforms` 字段，其他字段不参与平台解析。
+ * @returns 冻结的 {@link MiniappPlatformResolution}。显式声明返回规范排序后的 declared /
+ * effective；历史兼容返回空 declared 与 Android/iOS/OHOS effective。
+ * @throws `manifest` 不是对象时抛出；非空 sdkVersion 不完整、含 `v` 前缀或 build metadata、
+ * 不是 canonical SemVer 时抛出；sdkVersion precedence 达到 `0.9.0` 但缺少 platforms 时抛出；
+ * 显式 platforms 不是非空数组、包含未知/非字符串/重复平台时抛出。
+ *
  * @remarks
- * 规则与后端领域层保持一致：
- * - 无 `platforms` 字段：`sdkVersion` 缺失或 SemVer precedence 低于
- *   `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION` 时按历史移动端兼容；达到或高于硬切点即非法。
- * - 有 `platforms` 字段：复用 `validateMiniappPlatforms` 校验并规范化顺序；任何非法值
- *   （空数组、非数组、未知值、重复值）都不回退到历史兼容，即使 `sdkVersion < 0.9.0`。
- * - 任何非法的 `sdkVersion` 都会抛出，不做字符串比较。
- * @param sdkVersion - 产物 hb-sdk 版本；历史产物可能缺失。
- * @param manifest - 待解析的 Manifest（不可信输入）。
- * @returns 冻结的平台解析结果。
- * @throws Manifest 不是对象、`sdkVersion` 不是合法 SemVer、达到硬切点仍缺失 `platforms`，
- *   或 `platforms` 声明非法时抛出。
+ * 解析顺序与后端领域层保持一致：先校验 Manifest 对象，再处理 sdkVersion；只要非空
+ * sdkVersion 非法，即使存在合法 platforms 也会抛出，不会忽略版本。版本比较使用 SemVer
+ * precedence，不做字符串比较：`0.9.0-alpha.1 < 0.9.0`，而 `0.10.0 > 0.9.0`。
+ *
+ * Manifest 拥有 `platforms` 字段时总是走 `explicit`：字段必须是非空数组，每项必须属于
+ * `MINIAPP_PLATFORM_VALUES` 且不能重复；结果按固定平台词表排序，而不是保留输入顺序。
+ * 该规则与 sdkVersion 是否缺失、低于或达到硬切点无关。显式声明一旦非法绝不回退到
+ * legacy 默认值。
+ *
+ * Manifest 完全没有 `platforms` 字段时才判断硬切：sdkVersion 缺失/空白，或 precedence
+ * 低于 `MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION`（`0.9.0`）时返回
+ * `legacy_mobile_default`；`0.9.0` 稳定版及更高版本直接抛错。`0.9.0-*` prerelease 仍低于
+ * 稳定硬切点，因此可解析历史缺失声明。
+ *
+ * 返回对象被 `Object.freeze()`；显式声明数组和 legacy 的空 declared 数组也被冻结。所有
+ * 数组均以 readonly 合同暴露，调用方应直接消费 `effective`，不得再比较版本或补默认值。
+ *
+ * 当前 Vite 构建入口
+ * {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
+ * 会从 `package.json#heybox.platforms` 读取并写入显式声明；legacy 分支只用于解析缺少字段
+ * 的历史产物，不是新项目省略 platforms 的许可。
+ *
+ * {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/isValidVersion | isValidVersion}
+ * 判断的是小程序发布 `version`，并额外拒绝模板值 `0.0.0`；本函数的 sdkVersion 是 hb-sdk
+ * 版本，`0.0.0` 本身是可比较的 strict SemVer 并低于硬切点。两类版本不能互换校验。
+ *
+ * @example
+ * ```ts
+ * import { resolveMiniappManifestPlatforms } from '@heybox/hb-sdk/miniapp-publish'
+ *
+ * const explicit = resolveMiniappManifestPlatforms('0.9.0', {
+ *   platforms: ['linux', 'android', 'macos'],
+ * })
+ * console.log(explicit)
+ * // {
+ * //   declared: ['android', 'macos', 'linux'],
+ * //   effective: ['android', 'macos', 'linux'],
+ * //   platformsDeclared: true,
+ * //   policy: 'explicit'
+ * // }
+ *
+ * const legacy = resolveMiniappManifestPlatforms('0.9.0-alpha.1', {})
+ * console.log(legacy.effective) // ['android', 'ios', 'ohos']
+ * ```
+ *
+ * @see {@link MINIAPP_PLATFORM_HARD_CUT_SDK_VERSION}
+ * @see {@link MINIAPP_LEGACY_MOBILE_PLATFORM_VALUES}
+ * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/miniapp-publish/functions/isValidVersion | isValidVersion}
+ * @see {@link https://docs.xiaoheihe.cn/hb_sdk/reference/symbols/vite/functions/miniappManifest | miniappManifest}
  */
 export declare function resolveMiniappManifestPlatforms(sdkVersion: string | undefined, manifest: unknown): MiniappPlatformResolution;
 /**