@nudojs/core 1.0.0 → 1.1.0

package/dist/hof-types-tAeoYvzY.d.ts

@@ -0,0 +1,368 @@
+import { Node } from '@babel/types';
+
+/** 项（Term）：抽象值的身份。字面量是项的特例。 */
+type LiteralValue = string | number | boolean | null | undefined;
+type Term = {
+    op: "lit";
+    value: LiteralValue;
+} | {
+    op: "var";
+    id: string;
+} | {
+    op: "app";
+    fn: string;
+    args: Term[];
+};
+declare const lit: (value: LiteralValue) => Term;
+declare const v: (id: string) => Term;
+declare const app: (fn: string, args: Term[]) => Term;
+declare function termEquals(a: Term, b: Term): boolean;
+declare function termToString(t: Term): string;
+/** 常量折叠 + 简单代数化简 */
+declare function simplifyTerm(t: Term): Term;
+
+/** 约束（Pred）：附着在项上的事实，可传播。 */
+
+type PrimName = "number" | "string" | "boolean" | "bigint" | "symbol";
+/** JS `typeof` 完整结果域（8 标签）。Pred 的 typeof 节点用此域。 */
+type TypeofName = "undefined" | "object" | "boolean" | "number" | "bigint" | "string" | "symbol" | "function";
+/** typeof 标签全集（否定展开用；顺序稳定） */
+declare const TYPEOF_NAMES: readonly TypeofName[];
+/** abs prim 标签 → typeof 标签（恒等嵌入）。abs prim 仍是 PrimName 子集。 */
+declare function primToTypeof(p: PrimName): TypeofName;
+type Pred = {
+    op: "true";
+} | {
+    op: "false";
+} | {
+    op: "eq";
+    a: Term;
+    b: Term;
+} | {
+    op: "ne";
+    a: Term;
+    b: Term;
+} | {
+    op: "lt";
+    a: Term;
+    b: Term;
+} | {
+    op: "le";
+    a: Term;
+    b: Term;
+} | {
+    op: "gt";
+    a: Term;
+    b: Term;
+} | {
+    op: "ge";
+    a: Term;
+    b: Term;
+} | {
+    op: "and";
+    args: Pred[];
+} | {
+    op: "or";
+    args: Pred[];
+} | {
+    op: "not";
+    arg: Pred;
+} | {
+    op: "typeof";
+    t: Term;
+    type: TypeofName;
+};
+declare const pTrue: Pred;
+declare const pFalse: Pred;
+declare const eq: (a: Term, b: Term) => Pred;
+declare const ne: (a: Term, b: Term) => Pred;
+declare const lt: (a: Term, b: Term) => Pred;
+declare const le: (a: Term, b: Term) => Pred;
+declare const gt: (a: Term, b: Term) => Pred;
+declare const ge: (a: Term, b: Term) => Pred;
+declare const ptypeof: (t: Term, type: TypeofName) => Pred;
+declare function and(...preds: Pred[]): Pred;
+declare function or(...preds: Pred[]): Pred;
+declare function not(p: Pred): Pred;
+/**
+ * 逻辑否定（De Morgan）：¬(A∧B)=¬A∨¬B；¬(A∨B)=¬A∧¬B；双重否定消去。
+ * typeof 否定展开为其余 TypeofName 标签的析取——8 标签域是 JS typeof 的
+ * 完整结果域，展开健全且相对完备。
+ */
+declare function negatePred(p: Pred): Pred;
+declare function predEquals(a: Pred, b: Pred): boolean;
+declare function predToString(p: Pred): string;
+/** 把 pred 里的 Term 用 subst 替换（用于 bound 变量重命名等） */
+declare function substPred(p: Pred, subst: (t: Term) => Term): Pred;
+/** 收集 pred 中出现的自由变量 */
+declare function predVars(p: Pred): Set<string>;
+/** 约束环境 Φ：Pred 的合取 */
+type Phi = Pred;
+declare const emptyPhi: Phi;
+declare const phiAnd: typeof and;
+/**
+ * 外部蕴含 oracle（可选 SMT 等）。内建判定证不出时调用。
+ * 返回 true=可证；false/undefined=仍不可证（保持 fail-closed）。
+ * 默认无 oracle——纯内建区间/线性判定，不引入 solver 依赖。
+ */
+type ImplicationOracle = (phi: Phi, pred: Pred) => boolean | undefined;
+declare function setImplicationOracle(fn: ImplicationOracle | undefined): void;
+declare function getImplicationOracle(): ImplicationOracle | undefined;
+/** 简单蕴含：在区间/线性/字面量/typeof 可判定范围内判断 Φ ⊢ pred */
+declare function implies(phi: Phi, pred: Pred): boolean;
+/** 便捷：数字下界 */
+declare function gtNum(term: Term, n: number): Pred;
+declare function geNum(term: Term, n: number): Pred;
+declare function ltNum(term: Term, n: number): Pred;
+declare function leNum(term: Term, n: number): Pred;
+
+/** 抽象值 Abs = 形状 × 项 × 约束 × 置信度 */
+
+type Confidence = "exact" | "path" | "widened" | "mock" | "partial" | "opaque";
+type Shape = {
+    k: "never";
+}
+/**
+ * any：JS 里可以是任意值（无约束参数）。
+ * 运算按真实 JS 语义取并集，不是「分析失败」。
+ */
+ | {
+    k: "any";
+}
+/** unknown：分析拿不到信息（求值失败/泄漏），不是「任意值」 */
+ | {
+    k: "unknown";
+} | {
+    k: "prim";
+    type: PrimName;
+} | {
+    k: "obj";
+    slots: Record<string, {
+        value: Abs;
+        optional?: boolean;
+        readonly?: boolean;
+    }>;
+    index?: {
+        key: Abs;
+        value: Abs;
+    };
+    open?: boolean;
+} | {
+    k: "arr";
+    element: Abs;
+} | {
+    k: "tuple";
+    elements: Abs[];
+    rest?: Abs;
+    /** 已删除下标（delete a[i] / 字面量空洞）：读值为 undefined，`in` 判定 false */
+    holes?: number[];
+} | {
+    k: "fn";
+    params: string[];
+    name?: string;
+    paramTypes?: Abs[];
+    returnType?: Abs;
+} | {
+    k: "brand";
+    name: string;
+    shape: Abs;
+} | {
+    k: "eff";
+    eff: "promise" | "generator";
+    inner: Abs;
+} | {
+    k: "sum";
+    members: Abs[];
+};
+type Abs = {
+    shape: Shape;
+    term?: Term;
+    pred?: Pred;
+    conf: Confidence;
+    /**
+     * C2.4：分支 join 可解释标注（如 `join(number | string)`）。
+     * 仅展示用：不进 leq / 指纹 / check 等价；formatAbs 读取。
+     */
+    pathNote?: string;
+};
+declare const never: Abs;
+/** 分析无信息 */
+declare const unknown: Abs;
+/**
+ * 无约束 JS 值（未标注入口参数 / 显式 any()）。
+ * ≠ unknown：unknown 表示引擎推导失败，any 表示开发者未写契约。
+ */
+declare const anyAbs: Abs;
+/** 带 term 的 any（generalize type-var） */
+declare function anyVar(id: string, conf?: Confidence): Abs;
+declare function num(): Abs;
+declare function str(): Abs;
+declare function bool(): Abs;
+declare function numLit(value: number): Abs;
+declare function strLit(value: string): Abs;
+declare function boolLit(value: boolean): Abs;
+declare function bigintLit(value: bigint): Abs;
+/** 带项的符号数，例如参数 x */
+declare function numVar(id: string, pred?: Pred, conf?: Confidence): Abs;
+declare function obj(slots: Record<string, {
+    value: Abs;
+    optional?: boolean;
+}>): Abs;
+declare function confJoin(a: Confidence, b: Confidence): Confidence;
+declare function absToString(a: Abs): string;
+declare function shapeToString(s: Shape): string;
+/** 从 term 反推 prim shape */
+declare function shapeOfTerm(t: Term): Shape;
+/** 构造带项的结果 Abs；pred 相对 term */
+declare function abs(shape: Shape, term: Term | undefined, pred: Pred | undefined, conf: Confidence): Abs;
+declare function isNumPrim(a: Abs): boolean;
+declare function isStrPrim(a: Abs): boolean;
+declare function isBigPrim(a: Abs): boolean;
+/** 置信度：字面量全确定 */
+declare function isExactLit(a: Abs): boolean;
+declare function litValue(a: Abs): LiteralValue | undefined;
+
+/**
+ * may-throw 效果收集（design-cli-semantics §3.3）。
+ * any/nullish 成员访问等危险操作记录 throws 域，不立刻 hard-fail 求值。
+ * Collector/tryFrames 经 AsyncLocalStorage 会话隔离，避免 LSP 并发串档。
+ */
+
+type MayThrowEffect = {
+    /** throws 类型名，如 TypeError */
+    kind: string;
+    /** 人类可读成因 */
+    cause: string;
+    /** 接收者展示：any / null / undefined / number… */
+    recv?: string;
+    /** 成员名 */
+    name?: string;
+    line?: number;
+    column?: number;
+};
+/** 隔离一次分析的 may-throw 收集（check / analyzer 入口包一层） */
+declare function runWithMayThrowSession<T>(body: () => T): T;
+declare function setMayThrowCollector(c: ((e: MayThrowEffect) => void) | null): void;
+declare function getMayThrowCollector(): ((e: MayThrowEffect) => void) | null;
+declare function pushMayThrowFrame(): void;
+/**
+ * 弹出 try 帧。discard=true（catch 消化）时返回空；否则返回帧内效果供上浮。
+ */
+declare function popMayThrowFrame(discard: boolean): MayThrowEffect[];
+/**
+ * 孤儿 soft 效果上浮：若仍有外层 try 帧则并入外层（nested try + outer catch）；
+ * 否则交给 collector。不得在栈非空时直接 flush，否则 outer catch 被旁路。
+ */
+declare function orphanMayThrowEffects(effects: MayThrowEffect[]): void;
+/** B-path：try 开始时压 soft 帧 */
+declare function $tryMarkSoft(): void;
+/** B-path catch 消化 try 内 soft may-throw */
+declare function $tryDigestSoft(): void;
+/** B-path 无 handler / 出口 / rethrow：上浮未消化 soft may-throw（外层 try 可再消化） */
+declare function $tryReleaseSoft(): MayThrowEffect[];
+declare function flushMayThrowEffects(effects: MayThrowEffect[]): void;
+declare function recordMayThrow(e: MayThrowEffect): void;
+/** throws 类型名 → Abs（brand Error 形态，formatShape 打出名字） */
+declare function errorTypeAbs(name: string): Abs;
+/** 效果集 → throws Abs（never = 无 may-throw） */
+declare function mayThrowEffectsToAbs(effects: MayThrowEffect[]): Abs;
+/**
+ * throws Abs → 展示名（TypeError / TypeError | RangeError）。
+ * 非 brand/sum 时按 Abs 形状给出可运行时名，不再一律 "Error"。
+ */
+declare function formatThrowsAbs(t: Abs | undefined): string | undefined;
+/** JS Error 家族：`@nudo:throws Error` 覆盖全部子类（与 instanceof 语义一致） */
+declare const ERROR_FAMILY: Set<string>;
+/** throws Abs → kind 名列表（sum 拆臂；绝不把 `"A | B"` 当单个 kind） */
+declare function throwAbsToKinds(t: Abs | undefined): string[];
+/** declared/ignore 条目是否盖住 kind（`Error` 盖 Error 家族；`*` 由调用方先判） */
+declare function throwsKindCovered(kind: string, names: readonly string[]): boolean;
+/** effects 是否被 ignore 列表吞掉（kind 或 Error 族） */
+declare function isThrowsIgnored(kind: string, ignore: readonly string[] | undefined): boolean;
+/**
+ * L2 throws 过滤（口径固定）：
+ * 1. **declare 优先**（@nudo:throws / case !! throws / sidecar fn.throws）——有意 fail-fast；
+ * 2. ignoreThrows 其次——迁移期全类放行，**不是**声明的替代品。
+ */
+declare function filterGateThrows(effects: MayThrowEffect[], declared: readonly string[] | "*" | undefined, ignore: readonly string[] | undefined): MayThrowEffect[];
+/** effects 过滤后的剩余（L2 --ignore-throws） */
+declare function filterIgnoredThrows(effects: MayThrowEffect[], ignore: readonly string[] | undefined): MayThrowEffect[];
+/**
+ * 申报式抛错过滤（@nudo:throws / case !! throws / sidecar fn.throws）。
+ * `*` = 全部申报，L2 清空；数组 = kind 或 Error 族覆盖。
+ * 申报 ≠ ignoreThrows：前者是「这是有意 fail-fast」，后者是「迁移期先别管」。
+ */
+declare function filterDeclaredThrows(effects: MayThrowEffect[], declared: readonly string[] | "*" | undefined): MayThrowEffect[];
+
+/**
+ * 共享纯类型结点（AstEnv / HofCollectCtx / HofSite / RelSource）。
+ *
+ * 这些类型曾形成 ast-env ↔ hof ↔ abs-fn 的类型环（ast-env 引 HofCollectCtx，
+ * hof/abs-fn 引 AstEnv）。抽到本叶模块（只依赖 abs/term/babel，不回指
+ * ast-env/hof/abs-fn）后，三个消费方都从这里取类型，环即断。
+ *
+ * 稳定导入路径不变：ast-env.ts 重导出 AstEnv，hof.ts 重导出 HOF 三类型。
+ */
+
+/**
+ * 关系来源标记：P4 豁免与 diagnostics 依赖它，禁止隐式猜。
+ * - promote：使用驱动提升（generalize symbolic / instantiate 局部）
+ * - refine：@nudo:contract 契约
+ * - relationFn：harvest/mock/测试直接写入 fnRels 时的预留来源（P4 error 路径）
+ */
+type RelSource = "promote" | "refine" | "relationFn";
+type HofSite = {
+    /** 形参名（函数形参） */
+    param: string;
+    /** 输入侧 term：实参的 term（element 的 var/lit/app）；map 1 个、reduce 2 个 */
+    argTerms: Term[];
+    /** 输出侧：归纳出的返回 Abs */
+    result: Abs;
+    /** 源位置，便于 diagnostics */
+    loc?: {
+        line: number;
+        column: number;
+    };
+};
+/**
+ * run 局部 collector（与 Phi 并列，不进 Φ 合并）。
+ * symbolic 一次跑：安装并沉淀到 PolyFn；instantiate 重跑：装 throwaway
+ * 副本——形状提升仍生效，结果不写回共享状态（见 generalize.ts run()）。
+ */
+type HofCollectCtx = {
+    /** 本次归纳的形参名集合（身份判定用） */
+    paramNames: ReadonlySet<string>;
+    /** 本次 typeParams 的 α id 集合（term 复用白名单） */
+    alphaIds: Set<string>;
+    /** fresh α 计数 */
+    freshSeq: {
+        n: number;
+    };
+    sites: HofSite[];
+    fnRels: Map<string, {
+        abs: Abs;
+        source: RelSource;
+    }>;
+    entryShapes: Map<string, {
+        abs: Abs;
+        source: RelSource;
+    }>;
+};
+type AstEnv = {
+    vars: Map<string, Abs>;
+    /** 用户函数：name → { params, body } */
+    fns: Map<string, {
+        params: string[];
+        body: Node;
+        async?: boolean;
+        kind?: string;
+    }>;
+    /** class 表（旁路，withVar 必须保留） */
+    classes?: Map<string, unknown>;
+    /** 当前正在求值的方法所属类名（super.x() 从它的父类派发） */
+    currentOwner?: string;
+    /** P2：generalize symbolic 跑的 HOF collector（run 局部，不进 Φ） */
+    hofCollect?: HofCollectCtx;
+};
+
+export { $tryDigestSoft as $, type Abs as A, absToString as B, type Confidence as C, and as D, ERROR_FAMILY as E, anyAbs as F, anyVar as G, type HofCollectCtx as H, type ImplicationOracle as I, app as J, bigintLit as K, type LiteralValue as L, type MayThrowEffect as M, bool as N, boolLit as O, type PrimName as P, confJoin as Q, type RelSource as R, type Shape as S, type Term as T, emptyPhi as U, eq as V, ge as W, geNum as X, getImplicationOracle as Y, gt as Z, gtNum as _, type Pred as a, implies as a0, isBigPrim as a1, isExactLit as a2, isNumPrim as a3, isStrPrim as a4, le as a5, leNum as a6, lit as a7, litValue as a8, lt as a9, termToString as aA, unknown as aB, v as aC, ltNum as aa, ne as ab, negatePred as ac, never as ad, not as ae, num as af, numLit as ag, numVar as ah, obj as ai, or as aj, pFalse as ak, pTrue as al, phiAnd as am, predEquals as an, predToString as ao, predVars as ap, primToTypeof as aq, ptypeof as ar, setImplicationOracle as as, shapeOfTerm as at, shapeToString as au, simplifyTerm as av, str as aw, strLit as ax, substPred as ay, termEquals as az, type Phi as b, type AstEnv as c, $tryMarkSoft as d, $tryReleaseSoft as e, errorTypeAbs as f, filterDeclaredThrows as g, filterGateThrows as h, filterIgnoredThrows as i, flushMayThrowEffects as j, formatThrowsAbs as k, getMayThrowCollector as l, isThrowsIgnored as m, mayThrowEffectsToAbs as n, orphanMayThrowEffects as o, popMayThrowFrame as p, pushMayThrowFrame as q, recordMayThrow as r, runWithMayThrowSession as s, setMayThrowCollector as t, throwAbsToKinds as u, throwsKindCovered as v, type HofSite as w, TYPEOF_NAMES as x, type TypeofName as y, abs as z };