@bingine/cemem 0.0.0-stage → 0.1.1

package/dist/types/addresslist/memory-record.d.ts

@@ -0,0 +1,218 @@
+/**
+ * 地址表与内存记录 —— 对齐 Cheat Engine `MemoryRecordUnit.pas` / `addresslist.pas`。
+ *
+ * CE 的地址表（Cheat Table）是一棵树 + 一组带类型的条目：
+ *   - 每个条目有：描述、地址表达式、变量类型、当前值、偏移链、是否锁定（frozen）
+ *   - 条目可以互相引用（`Address` 写 `+8` 表示"上一项的地址 +8"），
+ *     也可以引用其它条目的描述作为基址
+ *   - "锁定"条目会由后台定时器不断写回固定值（CE 的 freeze）
+ *
+ * 本模块提供纯数据模型 + 求值 + 读写，定时锁定由宿主调用 `tickFrozen()` 驱动
+ * （不在这里起定时器，避免与宿主的生命周期纠缠）。
+ */
+import { EvalContext } from '../addr/expression';
+import { Process } from '../win/process';
+import { RoundingType, ScanOption, VariableType } from '../types';
+/** 一个地址表条目 */
+export interface MemoryRecordData {
+    /** 稳定 id（保存/加载表时用来还原引用关系） */
+    id: number;
+    description: string;
+    /** 地址表达式，例如 `"game.exe"+12AB34`、`[[base]+10]+8`、`+8`（相对上级） */
+    address: string;
+    variableType: VariableType;
+    /** 写入用的值（字符串形式，便于精确保留用户输入） */
+    value?: string;
+    /** 指针偏移链（CE 表里 <Offsets> 的等价物）；给出时 address 视为基址表达式 */
+    offsets?: number[];
+    /** 是否锁定（持续写回 value） */
+    frozen?: boolean;
+    /** 是否启用（未启用的条目不求值也不显示） */
+    active?: boolean;
+    /** 备注/注释 */
+    comment?: string;
+    /** 是否按十六进制显示 */
+    hexadecimal?: boolean;
+    /** 布尔显示（CE 的 "Show as binary"） */
+    binary?: boolean;
+    /** 显示用的字符编码（字符串类型） */
+    codePage?: number;
+    /** 字符串长度（字符数） */
+    stringLength?: number;
+    /**
+     * 解析地址失败时是否忽略该条目（CE 表里常见 "address failed" 的容错）。
+     * 默认 true：求值失败时不抛错，返回 null。
+     */
+    tolerant?: boolean;
+    /** 子条目（CE 的树形结构） */
+    children?: MemoryRecordData[];
+    /** 来源文件（表里的 <FileOffset> 之类，保留原字段以便往返不丢信息） */
+    extra?: Record<string, string>;
+}
+/** 求值结果 */
+export interface RecordEvaluation {
+    /** 最终地址（解引用、加偏移之后） */
+    address: bigint | null;
+    /** 求值失败原因 */
+    error?: string;
+}
+/**
+ * 归一化 CE 风格的带引号地址。
+ *
+ * 关键语义区分（早期实现搞错了，会破坏模块相对地址）：
+ *   - `"生命值"` —— 引号是**外层包裹**，内容才是真正的地址表达式；要剥掉引号。
+ *   - `"node.exe"+0` —— 引号是**表达式内部的模块名定界符**，是地址的一部分；
+ *     绝不能剥掉，否则表达式变成 `node.exe"+0` 直接解析失败。
+ *
+ * 另外 CE 里还有 `"a"+"b"` 这种拼接，所以剥引号前要求"去掉首尾后内部不再有引号"。
+ */
+export declare function normalizeAddressExpression(s: string): string;
+/**
+ * 一个内存记录（运行时对象）。对应 CE 的 TMemoryRecord。
+ */
+export declare class MemoryRecord {
+    private readonly list;
+    readonly id: number;
+    description: string;
+    /** 地址表达式（内部始终保存去引号形式） */
+    address: string;
+    variableType: VariableType;
+    offsets: number[];
+    frozen: boolean;
+    active: boolean;
+    comment: string;
+    hexadecimal: boolean;
+    binary: boolean;
+    codePage: number;
+    stringLength: number;
+    tolerant: boolean;
+    children: MemoryRecord[];
+    parent: MemoryRecord | null;
+    extra: Record<string, string>;
+    /** 用户设定的值（字符串） */
+    private userValue;
+    /** 最近一次解析出的地址 */
+    private cachedAddress;
+    /** 最近一次读取到的原始字节 */
+    private cachedBytes;
+    /** 最近一次错误 */
+    private lastError;
+    private readonly compiled;
+    constructor(data: MemoryRecordData, list: AddressList);
+    /** 编译期语法错误（null 表示语法正确） */
+    get parseError(): Error | null;
+    /** 本记录占用的字节数；变长类型返回显式长度或 0 */
+    get byteWidth(): number;
+    /**
+     * 解析最终地址（缓存到下次 invalidate）。
+     *
+     * 容错语义（重要）：
+     *   - `tolerant` 只针对**基址表达式**（例如引用了当前进程里不存在的模块名）——
+     *     这种失败在加载别人的表时很常见，返回 null 让调用方跳过即可。
+     *   - **偏移链解引用失败必须抛错**：链断了意味着地址是错的，
+     *     如果也静默返回 null/原地址，就会得到一个"看起来对其实错"的地址，
+     *     进而写坏目标进程的内存。CE 在偏移链失败时同样不会给出地址。
+     */
+    resolve(): RecordEvaluation;
+    /** 最近一次解析结果（不重新求值） */
+    get resolvedAddress(): bigint | null;
+    /** 最近一次错误 */
+    get error(): string | null;
+    /** 强制下次 resolve 重新求值 */
+    invalidate(): void;
+    /** 读取当前值（返回字符串形式，便于显示） */
+    read(): string | null;
+    /** 把原始字节格式化成显示字符串 */
+    formatBytes(buf: Buffer): string;
+    private formatInt;
+    /** 读取原始值（数值类型返回 number | bigint；字符串返回 string） */
+    readValue(): number | bigint | string | null;
+    /** 写入值（字符串形式，按变量类型解析）。返回是否成功。 */
+    write(value?: string): boolean;
+    /** 把字符串值编码成对应类型的字节 */
+    encodeValue(v: string): Buffer | null;
+    private intBuffer;
+    /** 用户设定的值 */
+    get value(): string;
+    set value(v: string);
+    /** 是否锁定且在本次 tick 中成功写回 */
+    tickFrozen(): boolean;
+    /** 转回纯数据（用于保存）。地址已在内部归一化为去引号形式。 */
+    toData(): MemoryRecordData;
+}
+/**
+ * 地址表 —— 对齐 CE 的 TAddressList + 表级设置。
+ */
+export declare class AddressList {
+    private records;
+    private nextId;
+    private processRef;
+    /** 已注册符号（供地址表达式引用） */
+    readonly symbols: Map<string, bigint>;
+    /** 模块列表缓存；为 null 时按需重新枚举 */
+    private moduleCache;
+    /** 表级注释 */
+    comment: string;
+    /** 表版本（CE 的 <CheatTable> 根节点属性） */
+    version: number;
+    constructor(process?: Process | null);
+    get process(): Process | null;
+    /** 绑定/切换目标进程（会清空模块缓存与所有记录的地址缓存）。 */
+    attachProcess(process: Process | null): void;
+    get count(): number;
+    /** 按索引取记录（CE 的 getMemoryRecord(i)，0 基） */
+    get(index: number): MemoryRecord | undefined;
+    /** 按 id 取记录 */
+    getById(id: number): MemoryRecord | undefined;
+    /** 按描述取记录（CE 的 getRecordWithDescription） */
+    getByDescription(description: string): MemoryRecord | undefined;
+    /** 全部记录（返回浅拷贝数组） */
+    all(): MemoryRecord[];
+    /** 追加一个条目 */
+    add(data: Partial<MemoryRecordData> & {
+        address: string;
+        variableType: VariableType;
+    }): MemoryRecord;
+    /** 删除记录（含子记录） */
+    remove(record: MemoryRecord | number): boolean;
+    /** 清空 */
+    clear(): void;
+    /** 求值上下文（供地址表达式使用） */
+    evalContext(): EvalContext;
+    /** 预加载模块列表缓存（可选，避免每条记录都枚举一次模块） */
+    preloadModules(): void;
+    /** 注册符号 */
+    registerSymbol(name: string, address: bigint): void;
+    /** 注销符号 */
+    unregisterSymbol(name: string): void;
+    /** 解析一个地址表达式（会用到符号表与模块列表）。 */
+    resolveExpression(expression: string): bigint;
+    /** 驱动一次"锁定写回"；返回成功写回的条目数。宿主自行决定调用频率。 */
+    tickFrozen(): number;
+    /** 读取全部记录的当前值，返回便于展示的快照 */
+    snapshot(): Array<{
+        id: number;
+        description: string;
+        address: bigint | null;
+        addressText: string;
+        type: VariableType;
+        value: string | null;
+        frozen: boolean;
+        active: boolean;
+        error: string | null;
+    }>;
+    /** 转成纯数据（用于保存） */
+    toData(): MemoryRecordData[];
+    /** 从纯数据恢复 */
+    static fromData(data: MemoryRecordData[], process?: Process | null): AddressList;
+}
+/**
+ * 把扫描结果导入地址表 —— 对齐 CE「把扫描结果加入地址表」。
+ */
+export declare function addScanResults(list: AddressList, addresses: readonly bigint[], variableType: VariableType, description?: string): MemoryRecord[];
+/**
+ * 用一次扫描结果构建地址表条目，并把当前值填入 value —— 便于导出成可用的表。
+ */
+export declare function buildRecordsFromScan(list: AddressList, addresses: readonly bigint[], variableType: VariableType, descriptionPrefix?: string): MemoryRecord[];
+export { RoundingType, ScanOption, VariableType };
+//# sourceMappingURL=memory-record.d.ts.map

package/dist/types/addresslist/memory-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-record.d.ts","sourceRoot":"","sources":["../../../src/addresslist/memory-record.ts"],"names":[],"mappings":"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"}

package/dist/types/asm/assembler.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 汇编器 —— 文本汇编 → 机器码，对齐 Cheat Engine `Assemblerunit.pas` 的对外行为。
+ *
+ * 后端是 Keystone（见 `backend.ts` 的说明：CE 在 Windows 上也是调 binutils 的 `as`）。
+ * 本文件负责 Keystone 之外的那一层，也就是 CE 汇编器真正做的事：
+ *
+ *   1. **符号解析**：`jmp someLabel` 里的未定义符号要在编码前解析成地址。
+ *      Keystone 支持通过符号回调注册，本模块提供 `symbols` 选项。
+ *   2. **`nop` 与对齐**：CE 的 `nop` 可带数量（`nop 5` 表示填充 5 字节的 nop）。
+ *   3. **CE 的强制宽度写法**：`mov [rax],1` 在 CE 里需要显式宽度，
+ *      本模块会把 CE 风格的 `mov dword ptr [rax],1` 原样交给 Keystone，
+ *      同时兼容省略写法（Keystone/NASM 语法自己会报错，错误信息里指明）。
+ *   4. **`int 3` 特例**：Keystone 会把 `int 3` 编成 `CD 03`（两字节），
+ *      而 x86 惯例与 CE 都用单字节 `CC`。这里做修正。
+ *   5. **逐行模式**：CE 的 `assemble` 是`逐行`语义（每行一条指令），
+ *      本模块提供 `assembleLines` 返回每行的字节边界，便于 Auto Assembler
+ *      把脚本按行映射回地址。
+ *
+ * ## 与 CE 的差异
+ *   - CE 支持 `E8 ?? ?? ?? ??` 这种"带通配的模板"，那属于 Auto Assembler 层
+ *     （见 `autoassembler.ts`），不在汇编器里。
+ *   - CE 的汇编器有大量针对旧语法的兼容分支（`$` 前缀十六进制、`offset` 关键字等），
+ *     本模块只保留主流写法，遇到不支持时会给出明确的汇编错误。
+ */
+import { AsmBackendError, type AsmArchitecture, type AsmBitness, type AsmEndianness } from './backend';
+/** 汇编选项 */
+export interface AssembleOptions {
+    /** 代码将放置的地址。**必需**：相对跳转/相对寻址的编码取决于它 */
+    address: bigint;
+    /**
+     * 架构，默认 `x64`。
+     * 支持 `x86` / `x64` / `arm`（A32）/ `thumb`（Thumb-2）/ `arm64`（AArch64）。
+     */
+    arch?: AsmArchitecture;
+    /** 兼容旧写法：位数（32/64）。`arch` 优先 */
+    bitness?: AsmBitness;
+    /** 字节序，默认 little（ARM 目标可能用大端） */
+    endianness?: AsmEndianness;
+    /**
+     * 符号表：名字 → 地址。
+     * 用于解析 `jmp label` 这类引用（Auto Assembler 的 label/define/aobscan 结果）。
+     */
+    symbols?: Record<string, bigint> | Map<string, bigint>;
+    /** x86 语法，默认 Intel（CE 用 Intel 语法）；ARM 只有一种语法，此选项无效 */
+    syntax?: 'intel' | 'att' | 'nasm' | 'masm' | 'gas';
+    /**
+     * 是否自动为未定义符号抛出更友好的错误。
+     * 默认 true：把 Keystone 的 "Cannot find a symbol" 换成"符号 X 未定义"。
+     */
+    friendlyErrors?: boolean;
+}
+/** 单行汇编的结果（`assembleLines` 用） */
+export interface AssembledLine {
+    /** 源文本（已 trim，注释已剥离） */
+    source: string;
+    /** 该行对应的字节 */
+    bytes: Buffer;
+    /** 该行在输出中的起始地址 */
+    address: bigint;
+    /** 该行是否为空行/纯注释（此时 bytes 为空） */
+    empty: boolean;
+}
+/** 汇编结果 */
+export interface AssembleResult {
+    /** 完整机器码 */
+    bytes: Buffer;
+    /** 起始地址 */
+    address: bigint;
+    /** 编码结束后的下一个地址 */
+    endAddress: bigint;
+    /** 逐行结果（`assembleLines` 时填充；`assemble` 只有一行整体） */
+    lines: AssembledLine[];
+    /** 本次汇编用到的符号（诊断用） */
+    usedSymbols: Record<string, string>;
+}
+/** 汇编失败 */
+export declare class AssemblerError extends Error {
+    readonly line?: string | undefined;
+    readonly lineNumber?: number | undefined;
+    constructor(message: string, line?: string | undefined, lineNumber?: number | undefined);
+}
+/**
+ * 汇编一段文本（可多行）。
+ *
+ * ```ts
+ * const r = assemble('mov rax, 1\nret', { address: 0x1000n });
+ * r.bytes; // <Buffer b8 01 00 00 00 c3>
+ * ```
+ */
+export declare function assemble(source: string, options: AssembleOptions): AssembleResult;
+/**
+ * 逐行汇编，返回每行的字节与地址。
+ *
+ * CE 的 Auto Assembler 需要"脚本行 → 地址"的映射
+ * （`label`/`alloc` 之后要把行号换算成地址），所以逐行编码是必要的。
+ *
+ * 注意：逐行编码无法处理"跨行的局部标签"（`jmp short_label` 后紧跟标号定义）。
+ * 调用方应先用 `assemble()` 传完整文本处理标签，或用 `symbols` 预解析。
+ */
+export declare function assembleLines(source: string, options: AssembleOptions): AssembleResult;
+/**
+ * 便捷函数：只拿字节。
+ */
+export declare function assembleToBytes(source: string, options: AssembleOptions): Buffer;
+export { AsmBackendError };
+//# sourceMappingURL=assembler.d.ts.map

package/dist/types/asm/assembler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assembler.d.ts","sourceRoot":"","sources":["../../../src/asm/assembler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EACL,eAAe,EAIf,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,aAAa,EACnB,MAAM,WAAW,CAAC;AAMnB,WAAW;AACX,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,gCAAgC;IAChC,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,iCAAiC;IACjC,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;IACnD;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc;IACd,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,WAAW;AACX,MAAM,WAAW,cAAc;IAC7B,YAAY;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,qBAAqB;IACrB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,WAAW;AACX,qBAAa,cAAe,SAAQ,KAAK;IAGrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM;gBAF5B,OAAO,EAAE,MAAM,EACN,IAAI,CAAC,EAAE,MAAM,YAAA,EACb,UAAU,CAAC,EAAE,MAAM,YAAA;CAS/B;AAqBD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CAyCjF;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CAmEtF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAEhF;AAyMD,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/types/asm/autoassembler-directives.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Auto Assembler 的「汇编器级」指令实现。
+ *
+ * Cheat Engine 里这些指令**不在** autoassembler.pas，而在 `Assemblerunit.pas`
+ * 的 `Assemble()` 里（见该文件 4930~5100 行的 `case tokens[0][1] of`）：
+ *
+ *   - `db/dw/dd/dq` —— 数据定义（Assemblerunit 的 `DB`/`DW`/`DD`/`DQ` 分支）
+ *   - `nop N`       —— 多字节 NOP 填充（Assemblerunit 的 `NOP HEXVALUE` 分支）
+ *   - `align N[,b]` —— 对齐填充（Assemblerunit 的 `ALIGN` 分支）
+ *
+ * 本移植的汇编后端是 Keystone，它**只认指令**，不认这些伪指令
+ * （`db`/`align` 会直接报错，`nop 5` 会被当成 `nop` 的操作数）。
+ * 因此这一层必须在 Auto Assembler 里自己做，且要**逐字节对齐 CE 的产出**。
+ *
+ * ## 数字字面量的进制（最容易静默出错的地方）
+ *
+ * CE 的 `Assemblerunit` 对 `db/dw/dd/dq/nop/align` 的参数统一走
+ * `HexStrToInt`（`parsers.pas` 的 `ConvertHexStrToRealStr`），规则是：
+ *
+ *   - **裸数字按十六进制解释**（`db 89 01 00 00 00` 是 0x89 0x01 ...，不是十进制 89）
+ *   - `#123` 才是十进制（`#` 前缀）
+ *   - `-` / `+` 前缀保留符号
+ *
+ * 这一条**必须**保持 CE 语义：真实 CE 脚本的 `[DISABLE]` 段几乎都是
+ * `db 89 01 00 00 00` 这种写法，若按十进制解析会得到完全错误的字节（89 → 0x59）。
+ *
+ * 作为超集，本模块额外接受 `0x` 与 `$` 前缀（CE 的 HexStrToInt 其实不接受，
+ * 会返回空串然后抛异常）。
+ */
+/** 数据定义伪指令 */
+export type DataDirectiveKind = 'db' | 'dw' | 'dd' | 'dq';
+/** 本模块能编码的伪指令 */
+export type PseudoDirectiveKind = DataDirectiveKind | 'nop' | 'align';
+/** 伪指令编码上下文 */
+export interface DirectiveContext {
+    /** 该行将要放置的地址（`align` 需要它） */
+    address: bigint;
+    /**
+     * 读取目标进程 1 字节（`db ??` / `db +1` 需要）。
+     * 没有目标进程时返回 null —— `db ??` 会退化成 0 并记一条警告。
+     */
+    readByte?: (address: bigint) => number | null;
+    /** 裸数字是否按十六进制解释，默认 true（CE 行为） */
+    hexDefault?: boolean;
+}
+/** 编码结果 */
+export interface DirectiveEncodeResult {
+    bytes: Buffer;
+    /** 非致命问题（例如 `db ??` 在没有目标进程时按 0 处理） */
+    warnings: string[];
+}
+/**
+ * 按 CE 的 `HexStrToInt` 语义解析整数（裸数字 = 十六进制）。
+ *
+ * 支持 `#123`（十进制）、`0x1F`、`$1F`、裸 `1F`，以及 `-`/`+` 前缀。
+ * 无法解析时返回 null（调用方负责给出带行号的中文错误）。
+ */
+export declare function parseCeInteger(text: string, hexDefault?: boolean): bigint | null;
+/**
+ * 把伪指令的参数串切成 token。
+ *
+ * 对齐 CE 的 `tokenize`（autoassembler.pas 383 行）的实用子集：
+ *   - 分隔符：逗号、空格、制表符
+ *   - 引号内的内容**不切分**（`db 'a b'` 是一个 token）
+ *   - 保留引号本身（后续按字符串处理）
+ */
+export declare function splitDirectiveArguments(text: string): string[];
+/**
+ * 编码 `db/dw/dd/dq`。
+ *
+ * 对齐 `Assemblerunit.pas` 4964~5048 行：
+ *   - `db 'abc'`  → latin1 字节（**不**反转，`AddString` 是按序拷贝）
+ *   - `dw 'abc'`  → UTF-16LE（`AddWideString` 直接 copy 宽字符内存）
+ *   - `db ??` / `db **` / `db *` → **读目标进程当前字节**（保持原样）
+ *   - `db +1` / `db -1`        → 读目标进程当前字节后加/减
+ *   - 其它 → 数字，按 CE 的十六进制语义
+ *
+ * 注意 `dd 'str'` / `dq 'str'` 在 CE 里会走 `HexStrToInt` 的字符分支（行为很怪），
+ * 本移植直接报错，避免产生难以察觉的错误字节。
+ */
+export declare function encodeDataDirective(kind: DataDirectiveKind, args: string, ctx: DirectiveContext): DirectiveEncodeResult;
+/** 生成 `count` 字节的 NOP 填充（count<=0 返回空） */
+export declare function encodeNop(count: number): Buffer;
+/**
+ * 计算对齐填充。对齐 `Assemblerunit.pas` 4938~4959 行：
+ *
+ * ```pascal
+ * k := i - (address mod i);
+ * if k = i then exit;          // 已对齐，不填
+ * for ... do Add(bytes, b);    // b 默认 0
+ * ```
+ *
+ * 注意 CE 的填充字节**默认是 0x00**（不是 0x90），第二个参数才是填充值：
+ * `align 10, 90` 表示对齐到 16 字节边界并用 0x90 填充。
+ */
+export declare function encodeAlign(address: bigint, alignment: bigint, fillByte?: number): Buffer;
+/** 识别出的伪指令 */
+export interface ParsedPseudoDirective {
+    kind: PseudoDirectiveKind;
+    /** 伪指令名之后的参数原文 */
+    args: string;
+}
+/**
+ * 判断一行是否是 `db/dw/dd/dq/nop/align` 伪指令。
+ *
+ * 返回 null 表示不是伪指令（交给 Keystone 汇编）。
+ * 注意 `nop`（不带参数）**不算**伪指令 —— Keystone 自己能编成 0x90，
+ * 保持与 `assembler.ts` 的行为一致。
+ */
+export declare function parsePseudoDirective(line: string): ParsedPseudoDirective | null;
+/**
+ * 把 AOB 字符串转成伪指令用的 `db` 参数串（`aobscan` 回填原字节时用）。
+ * 通配位被替换为 `??`，保留「读取原字节」语义。
+ */
+export declare function patternToDbArguments(patternText: string): string;
+/** 把一段内存按 `db` 参数串格式化（`readmem` 用） */
+export declare function bytesToDbArguments(bytes: Buffer): string;
+//# sourceMappingURL=autoassembler-directives.d.ts.map

package/dist/types/asm/autoassembler-directives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoassembler-directives.d.ts","sourceRoot":"","sources":["../../../src/asm/autoassembler-directives.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,cAAc;AACd,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE1D,iBAAiB;AACjB,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,GAAG,KAAK,GAAG,OAAO,CAAC;AAEtE,eAAe;AACf,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC9C,kCAAkC;IAClC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,WAAW;AACX,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,UAAO,GAAG,MAAM,GAAG,IAAI,CA2C7E;AAMD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAiC9D;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,gBAAgB,GACpB,qBAAqB,CA8DvB;AA8DD,0CAA0C;AAC1C,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAU/C;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,SAAI,GACX,MAAM,CASR;AAMD,cAAc;AACd,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI,CAoB/E;AASD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAUhE;AAED,sCAAsC;AACtC,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD"}