rn-update-cli 1.0.0

package/lib/utils/hermes-base.d.ts

@@ -0,0 +1,227 @@
+/**
+ * [INPUT]: 依赖 Node 子进程/文件流/HTTP Range、Pakta CLI 临时目录与 ZIP 读取原语
+ * [OUTPUT]: 对外提供 Hermes base 选择、缓存、二进制字面量/指令等价校验、下载、清理及发布元数据能力
+ * [POS]: CLI Hermes delta 优化边界，所有失败降级到普通编译，不阻塞发布流程
+ */
+import { LiteralResolver } from './hermes-literals';
+export type HermesBaseOption = 'auto' | 'none' | string;
+/**
+ * The base cannot be obtained whatever the transport or how often it is
+ * retried (wrong content on the server, no bundle in the package, ...).
+ */
+export declare class PermanentBaseError extends Error {
+}
+/** The fetched bundle's sha256 differs from what the server recorded. */
+export declare class BundleHashMismatchError extends PermanentBaseError {
+    constructor(actual: string, expected: string);
+}
+export interface HermesBaseSelection {
+    /** path of the bundle (HBC) handed to hermesc as -base-bytecode */
+    path: string;
+    bytecodeVersion: number;
+    bundleHash: string;
+    /** server version id when the base came from the server */
+    versionId?: number;
+    /** server object key of the base artifact when known */
+    hash?: string;
+    source: 'cache' | 'download' | 'local' | 'latest-version' | 'native-package';
+}
+/**
+ * What became of the base for this build, as reported to the server:
+ * - `used`: compiled with -base-bytecode (and, when verification was on,
+ *   the disassembly matched a plain compile)
+ * - `rejected`: the disassembly differed from a plain compile; base dropped
+ * - `dump-failed`: the check could not run (dump or plain compile failed);
+ *   base dropped
+ * - `none`: no base (none selected, disabled, or the base compile failed)
+ */
+export type HermesBaseOutcome = 'used' | 'rejected' | 'dump-failed' | 'none';
+/** the server column is VARCHAR(500); it truncates too, this just saves bytes */
+export declare const HERMES_BASE_DETAIL_MAX_CHARS = 500;
+/** Metadata attached to version/create so the server can track the chain. */
+export interface HermesBaseMeta {
+    bytecodeVersion: number | null;
+    baseVersionId: number | null;
+    baseHash: string | null;
+    /** absent (never null) when the bundle step did not run hermesc */
+    hermesBaseOutcome?: HermesBaseOutcome;
+    /** first difference / failure reason; absent when there is none */
+    hermesBaseDetail?: string;
+}
+/**
+ * Hermes V1 (static_h) builds before 2025-07-11 carried a delta-mode bug when a
+ * delta-produced base is reused; every released `hermes-compiler` is newer, and
+ * classic hermesc (HBC ≤96, react-native/sdks or hermes-engine) upgrades kinds
+ * in place and was never affected. Anything else is refused.
+ */
+export declare const MIN_HERMES_COMPILER_BUILD = 250829098;
+export declare const MIN_HERMES_COMPILER_COMMITLY_DATE = 20250901;
+export declare function classifyHermesCommand(hermesCommand: string): {
+    allowed: boolean;
+    kind: 'classic' | 'hermes-compiler' | 'unknown';
+    version?: string;
+    reason?: string;
+};
+export declare function sha256Hex(data: Buffer): string;
+/** sha256 of a file, streamed (a cached base can be tens of MB) */
+export declare function sha256File(file: string): Promise<string>;
+/** HBC version from the first bytes of a file, without reading the rest */
+export declare function readFileHbcVersion(file: string): Promise<number | null>;
+/**
+ * Which HBC version this hermesc emits. The answer is remembered per binary
+ * (path, size, mtime) in the cache dir so only the first run of a given
+ * hermesc pays for the empty-file compile.
+ */
+export declare function probeHbcVersion(hermesCommand: string): number | null;
+export declare const BUNDLE_ENTRY_NAMES: string[];
+export type BaseArtifactType = 'ppk' | 'apk' | 'ipa' | 'app';
+/** Which zip entry holds the JS/HBC bundle in each kind of artifact. */
+export declare function bundleEntryMatcher(artifactType: BaseArtifactType): (name: string) => boolean;
+/**
+ * Extract the JS/HBC bundle from a local artifact: a raw bundle file, a ppk,
+ * or a native package (apk / ipa / harmony app). Returns null when not found.
+ */
+export declare function extractBundleFromArchive(filePath: string): Promise<Buffer | null>;
+export declare const DEFAULT_CACHE_MAX_BYTES: number;
+export declare const DEFAULT_CACHE_MAX_FILES = 20;
+export declare function cacheDir(): string;
+export declare function tmpDir(): string;
+export declare function cacheLimits(overrideMaxMb?: number): {
+    maxBytes: number;
+    maxFiles: number;
+};
+/** Returns the cached bundle path when present and its sha256 still matches. */
+export declare function cacheLookup(bundleHash: string): Promise<string | null>;
+/** Store a bundle under its sha256 (LRU-evicting to the configured limits). */
+export declare function cachePut(bundle: Buffer, maxMb?: number, knownHash?: string): Promise<{
+    path: string;
+    bundleHash: string;
+}>;
+export declare function enforceCacheLimits(maxMb?: number, keep?: string): Promise<void>;
+/** Remove every cached bundle (and staging leftovers); returns the bundle count. */
+export declare function cleanCache(): Promise<number>;
+export declare function cacheStats(): Promise<{
+    dir: string;
+    files: number;
+    bytes: number;
+}>;
+/** Remove leftovers of interrupted runs (older than 24h) from the tmp dir. */
+export declare function cleanStaleTmp(maxAgeMs?: number): Promise<void>;
+export declare function downloadToFile(url: string, destination: string): Promise<void>;
+export interface HermesBaseServerRecord {
+    versionId?: number | null;
+    hash: string;
+    artifactType?: BaseArtifactType;
+    bundleHash?: string | null;
+    bytecodeVersion?: number | null;
+    url: string;
+    /**
+     * Location of the bundle's compressed bytes inside the ppk, reported by the
+     * publishing CLI; lets the base be fetched with a single HTTP Range request.
+     */
+    bundleOffset?: number | null;
+    bundleCompressedSize?: number | null;
+    /** zip compression method: 0 stored, 8 deflate */
+    bundleCompression?: number | null;
+}
+interface FetchedBaseBundle {
+    bundle: Buffer;
+    /** sha256 of `bundle`, computed once here */
+    bundleHash: string;
+    /** how the bytes were obtained, for the log line */
+    transport: 'range-entry' | 'range-zip' | 'full';
+    fetchedBytes?: number;
+    totalBytes?: number;
+}
+/**
+ * Obtain the base bundle with as little traffic as possible, in order:
+ *  1. one Range request for the bundle's compressed bytes when the server
+ *     knows their location (ppk / apk / ipa published by a CLI that
+ *     reported it);
+ *  2. the archive's central directory over Range, then just the bundle
+ *     entry (any zip: ppk, apk, ipa — harmony .app nests a second zip and
+ *     is skipped);
+ *  3. the whole archive, as before.
+ * A server that ignores Range (HTTP 200) streams the full archive into
+ * `archive` without a second request. Every result is verified against
+ * `record.bundleHash`. A mismatch of the located bytes (1) may only mean the
+ * recorded location is stale, so the directory transport (2) still runs; a
+ * mismatch of the entry itself (2, 3) is final — the same bytes would come
+ * back however they are fetched — and raises BundleHashMismatchError.
+ */
+export declare function fetchBaseBundle(record: HermesBaseServerRecord, artifactType: BaseArtifactType, archive: string, log?: (message: string) => void): Promise<FetchedBaseBundle>;
+export interface ResolveHermesBaseParams {
+    option: HermesBaseOption;
+    hermesCommand: string;
+    bytecodeVersion: number;
+    appId?: string;
+    cacheMaxMb?: number;
+    /**
+     * server lookup; returns null when the app has no usable base. The server
+     * itself falls back to the newest legacy version, then the newest native
+     * package (bytecodeVersion is null and verified here after download).
+     */
+    fetchBase: (appId: string, bytecodeVersion: number) => Promise<HermesBaseServerRecord | null>;
+    log?: (message: string) => void;
+}
+/**
+ * Pick and materialize the base bundle for this compile. Returns null (with
+ * the reason logged) whenever a base cannot be used; callers then compile
+ * without one.
+ */
+export declare function resolveHermesBase(params: ResolveHermesBaseParams): Promise<HermesBaseSelection | null>;
+export declare function hermescArgsWithBase(baseArgs: string[], basePath: string | null): string[];
+export declare function hermesBaseMeta(selection: HermesBaseSelection | null, bytecodeVersion: number | null, check?: {
+    outcome: HermesBaseOutcome;
+    detail?: string;
+}): HermesBaseMeta;
+/** one line, at most HERMES_BASE_DETAIL_MAX_CHARS code points; '' when empty */
+export declare function truncateHermesBaseDetail(detail: string | undefined): string;
+/**
+ * Normalize one disassembly line so that a delta-mode compile and a plain
+ * compile of the same source compare equal: string IDs are renumbered, literal
+ * buffers are laid out differently (offsets, short/long variants), and jump
+ * distances follow instruction widths. Everything else must match exactly.
+ */
+/** separates rendered literal entries inside one normalized line */
+export declare const LITERAL_SEPARATOR = "\u001F";
+export declare function normalizeDisassemblyLine(line: string, strings: Map<number, string>, literals?: LiteralResolver): string | null;
+/** How an equivalence check ended. */
+export type HermesEquivalenceStatus = 'equivalent' | 'different' | 'dump-failed';
+export interface HermesEquivalenceResult {
+    status: HermesEquivalenceStatus;
+    /**
+     * one line for the log: where the first difference is (function, line,
+     * both sides) or why a dump could not be read
+     */
+    detail?: string;
+    /** functions compared on both sides */
+    functions: number;
+    /**
+     * `instruction`: literals decoded from the binary buffers at each
+     * New*WithBuffer instruction (HBC v87–96 and v98); `buffer`: the dumped
+     * buffers compared as a whole (unknown layout)
+     */
+    literals?: 'instruction' | 'buffer';
+}
+export interface HermesEquivalenceOptions {
+    /** write each side's raw disassembly here (bug reports) */
+    dumpTo?: {
+        withBase: string;
+        plain: string;
+    };
+}
+/**
+ * Compare two HBC files by disassembly (see normalizeDisassemblyLine): the
+ * literal buffers by content, then function by function. `-b` forces hermesc
+ * to treat inputs as bytecode whatever their extension. Both dumps are
+ * consumed as streams so the ~100 MB of text never touches the disk (unless
+ * `dumpTo` asks for it). A dump process that fails or ends early is reported
+ * as `dump-failed`, never as a difference: the two cases need different
+ * follow-ups. The detail names the first difference so a rejected base can be
+ * turned into a normalization rule or a bug report.
+ */
+export declare function compareHermesBytecode(hermesCommand: string, withBase: string, plain: string, options?: HermesEquivalenceOptions): Promise<HermesEquivalenceResult>;
+/** Resolves true when equivalent; see compareHermesBytecode for the details. */
+export declare function verifyHermesBaseEquivalence(hermesCommand: string, withBase: string, plain: string): Promise<boolean>;
+export {};