@nudojs/core 1.0.0 → 1.1.0

package/dist/check-report-AtnAfY9U.d.ts

@@ -0,0 +1,661 @@
+import { File } from '@babel/types';
+import { T as Term, A as Abs, P as PrimName, a as Pred, b as Phi, C as Confidence } from './hof-types-tAeoYvzY.js';
+
+declare function resetParseSourceCache(): void;
+declare function getParseSourceCacheSize(): number;
+declare function parseSource(source: string, opts?: {
+    errorRecovery?: boolean;
+    keepTs?: boolean;
+}): File;
+
+/**
+ * 项（Term）防爆炸：深度/宽度阈值 → leak 为新鲜 var + 等式约束。
+ */
+
+type LeakBudget = {
+    maxDepth: number;
+    maxNodes: number;
+};
+declare const defaultLeakBudget: LeakBudget;
+declare function termDepth(t: Term): number;
+declare function termNodes(t: Term): number;
+declare function exceedsBudget(t: Term, budget?: LeakBudget): boolean;
+declare function resetLeakCounter(): void;
+/**
+ * 若项超预算，替换为新鲜变量，并返回附加等式 pred：fresh = originalTerm。
+ * 未超预算则原样返回。
+ */
+declare function maybeLeak(a: Abs, budget?: LeakBudget, label?: string): Abs;
+/**
+ * 批量：在算术结果上应用 leak。
+ */
+declare function leakIfNeeded(a: Abs, budget?: LeakBudget, label?: string): Abs;
+
+/**
+ * 侧车/依赖路径纯函数（leaf 模块：零依赖，供 load-deps-fp / interface /
+ * refine / LSP 共享单一定义——历史上三份内联拷贝已各自漂移过）。
+ */
+declare function normPath(p: string): string;
+/** core 不引 path：相对 spec 纯字符串拼接（与 LSP resolve 对齐时双方 norm） */
+declare function resolveDepPath(fromFile: string, spec: string): string;
+/**
+ * 是否落在 node_modules 下（相对/绝对/盘符形态统一）。
+ * autoBind 永不 ambient 加载 node_modules 侧车（§2.2）——必须在 normPath
+ * 之后判定，否则 `node_modules/pkg/x.js`（无前导 `/`）会绕过守卫。
+ */
+declare function isNodeModulesPath(p: string): boolean;
+/**
+ * 源文件的旁路侧车路径：.js/.mjs → 同名 .nudo.js；.ts/.mts → 同名 .nudo.ts。
+ * 其他扩展名（.cjs/.jsx/无扩展名…）不做替换，直接追加 .nudo.js——侧车约定
+ * 只覆盖四类入口；host loadModule 对不存在的路径返回 miss，自然无侧车来源。
+ */
+declare function sidecarPathOf(file: string): string;
+
+/**
+ * 约束模板构建器（参数无关）。
+ *
+ *   number().gt(0)                    → 占位项 self 上的 Pred
+ *   number().int().ge(0)              → 整数 + 下界
+ *   string().min(1)                   → 非空串（长度）
+ *   array(number().gt(0))             → 元素约束
+ *   shape({ id: number().gt(0) })     → object 形状约束
+ *   lit(42)                           → 字面量（prim + eq(self, 42)）
+ *   union(number().gt(0), lit(0))     → 成员析取（or / joinAbs）
+ *   fn({ x: number().gt(0) }, number()) → 一等函数约束
+ *   number().gt(0).shift(1)           → 界平移（x>0 ⇒ x+n>1）
+ *   instantiate("ms")                 → Pred ms > 0 / u.id > 0 ∧ …
+ *
+ * 在 *.nudo.js 里执行；不是 zod 绑定，是我们自己的运行时 API。
+ * 不需要 interface/type 语法——契约用 JS 表达式声明。
+ * 命名：litC/andC 与 term.ts 的 lit、pred.ts 的 and 消歧（桶导出不再冲突）。
+ * 侧车注入表仍以 `lit`/`and` 为键名（*.nudo.js 用户写法不变）。
+ */
+
+/** 模板占位项；instantiate 时换成真实参数名 */
+declare const SELF = "__nudo_self__";
+/** 字段访问项：u.id */
+declare function getTerm(obj: Term, key: string): Term;
+/** 长度项：length(u) */
+declare function lenTerm(t: Term): Term;
+type NudoField = {
+    constraint: NudoConstraint;
+    optional?: boolean;
+};
+type NudoConstraint = {
+    readonly __nudoConstraint: true;
+    readonly prim?: PrimName;
+    readonly preds: Pred[];
+    /** object 形状：字段名 → 嵌套约束 */
+    readonly fields?: Record<string, NudoField>;
+    /** array 元素约束 */
+    readonly element?: NudoConstraint;
+    /** 整数（number 链式 .int()） */
+    readonly int?: boolean;
+    /** 该约束整体可选（shape 字段用；不用 optional 以免与链式方法撞名） */
+    readonly isOptional?: boolean;
+    /** union 成员（析取）：instantiate 为 or(...)，entry Abs 为成员 join */
+    readonly members?: NudoConstraint[];
+    /** 一等函数约束（fn() 构建器产出） */
+    readonly fn?: NudoFnConstraint;
+};
+/** fn(params, returns?, { throws? }) 的一等函数约束形态 */
+type NudoFnConstraint = {
+    params: Record<string, NudoConstraint>;
+    returns?: NudoConstraint;
+    throws?: NudoConstraint;
+};
+declare function isNudoConstraint(x: unknown): x is NudoConstraint;
+/** 链式约束：不可变，每次 .gt() 返回新对象 */
+type ConstraintBuilder = NudoConstraint & {
+    gt(n: number): ConstraintBuilder;
+    ge(n: number): ConstraintBuilder;
+    lt(n: number): ConstraintBuilder;
+    le(n: number): ConstraintBuilder;
+    /** number：要求整数 */
+    int(): ConstraintBuilder;
+    /** string：长度下界 */
+    min(n: number): ConstraintBuilder;
+    /** string：长度上界 */
+    max(n: number): ConstraintBuilder;
+    /** string：精确长度 */
+    length(n: number): ConstraintBuilder;
+    /**
+     * 界平移：term 平移 n 后重写常数界（x>0 ⇒ x+n>n）。
+     * 仅数值标量界链合法；length 界 / shape / array / union / fn → throw。
+     */
+    shift(n: number): ConstraintBuilder;
+    /** 字段可选（仅在 shape 内有意义） */
+    optional(): ConstraintBuilder;
+};
+/**
+ * builder 与纯数据形态统一的 int 标志读取：纯数据看 `int === true`，
+ * builder（int 是链式方法）查 WeakSet。toPlainConstraint 归一化后只剩前者。
+ */
+declare function isIntFlag(c: NudoConstraint): boolean;
+/** number() —— 约束 number 原语 + 后续链式界 */
+declare function number(): ConstraintBuilder;
+declare function string(): ConstraintBuilder;
+declare function boolean(): ConstraintBuilder;
+/** any() —— 无约束；formatConstraint / draft import 与显示同源 */
+declare function any(): ConstraintBuilder;
+/** array(item) —— 数组，元素满足 item；item 亦可为具体字面量（指令文法） */
+declare function array(item: NudoConstraint | ConstraintBuilder | number | string | boolean | null | undefined): ConstraintBuilder;
+/**
+ * object 形状约束（契约规范形状，无需 interface）：
+ *
+ *   shape({ id: number().gt(0), name: string() })
+ *
+ * 字段值亦可为具体字面量（指令文法）。
+ */
+declare function shape(fields: Record<string, NudoConstraint | ConstraintBuilder | number | string | boolean | null | undefined>): ConstraintBuilder;
+/** litC(v)：字面量契约——prim 按 v 类型、eq(self, v) pred 编码（不开新字段） */
+declare function litC(v: number | string | boolean | null | undefined): ConstraintBuilder;
+/** union(...cs)：成员析取；instantiate 为 or(...)，entry Abs 为成员 joinAbs。空参 throw */
+declare function union(...cs: (NudoConstraint | ConstraintBuilder | number | string | boolean | null | undefined)[]): ConstraintBuilder;
+/**
+ * fn(params, returns?, { throws? })：一等函数约束。
+ * Phase 1 只展示不执法：参数位 instantiate 恒真（pTrue），
+ * 逐参约束经 fnConstraintToEntryReqs 消费。
+ */
+declare function fn(params: Record<string, NudoConstraint | ConstraintBuilder | number | string | boolean | null | undefined>, returns?: NudoConstraint | ConstraintBuilder | number | string | boolean | null | undefined, opts?: {
+    throws?: NudoConstraint | ConstraintBuilder | number | string | boolean | null | undefined;
+}): ConstraintBuilder;
+/**
+ * andC(...cs)：标量合取（Phase 1 最小实现）。
+ * prim 一致（缺省 prim 视为无 prim 约束、可与任意 prim 合并）→ preds 拼接；
+ * prim 不一致或任一含 fields/element/members/fn → throw。
+ */
+declare function andC(...cs: (NudoConstraint | ConstraintBuilder)[]): ConstraintBuilder;
+/** partial(c)：shape 全字段变可选；非 shape throw */
+declare function partial(c: NudoConstraint | ConstraintBuilder): ConstraintBuilder;
+/** pick(c, keys)：shape 子形状（不存在的 key 忽略）；非 shape throw */
+declare function pick(c: NudoConstraint | ConstraintBuilder, keys: string[]): ConstraintBuilder;
+/** omit(c, keys)：shape 去字段；非 shape throw */
+declare function omit(c: NudoConstraint | ConstraintBuilder, keys: string[]): ConstraintBuilder;
+/** 把模板绑定到参数名：self → paramName；shape 展开为字段访问 Pred */
+declare function instantiateConstraint(c: NudoConstraint, paramName: string): Pred;
+/**
+ * 契约 → 函数入口 param Abs（infer/hover 用）。
+ * 标量：prim + pred；shape：obj slots 递归；union：成员 joinAbs；
+ * fn 形态：一等 fn shape（paramTypes/returnType），供 refine→error / 展示。
+ */
+declare function constraintToEntryAbs(c: NudoConstraint, paramName: string): Abs;
+/**
+ * fn 约束 → 逐参约束表（interface 推导 / 入口签名消费）。
+ * 非 fn() 形态 throw——调用方应先判 c.fn。
+ */
+declare function fnConstraintToEntryReqs(c: NudoConstraint): Array<{
+    param: string;
+    constraint: NudoConstraint;
+}>;
+/**
+ * fn(..., { throws }) / throws 约束 → 申报的 throws 类型名。
+ * `"Error"` / `lit("Error")` / brand / union 成员 / `*` 全收。
+ */
+declare function throwConstraintToKinds(c: NudoConstraint | undefined): string[] | "*" | undefined;
+
+/**
+ * 源内契约解析：唯一形态
+ *
+ *   @nudo:contract <param> <constraint>    参数契约（挂入口 Abs，参与运算）
+ *   @nudo:contract return <constraint>     返回契约（推断返回值 ⊭ 时红）
+ *
+ * 不叫 requires：那只是「校验挡板」。
+ * contract 表示约束是类型的一部分——Abs = shape × term × **pred** × conf，
+ * pred 会流入代数（x>0 ⇒ x+1>1），不只是调用点挡一下。
+ *
+ * constraint 来自 *.nudo.js 导出的模板（number().gt(0) 等），
+ * 由 /// @nudo:import { delay } from "./delay.nudo.js" 引入。
+ * 不支持写 `x > 0`（绑死参数名）。
+ * 不用 JSDoc @param/@return：那是类型注解语法。
+ *
+ * 侧车加载：Babel 语句级改写（多行 import / 注释与字符串里的同形文本不误伤）、
+ * 相对 .nudo.js/.nudo.ts 经 loadModule 递归求值、环检测、执行失败改诊断
+ * （nudo:interface-load / nudo:interface-cycle，不再静默吞错）。
+ */
+
+/** `/// @nudo:import { delay, percent } from "./delay.nudo.js"` */
+type NamedImport = {
+    names: string[];
+    spec: string;
+};
+declare function extractNudoImports(source: string): NamedImport[];
+/** refine 侧车加载诊断（severity 由消费方按 code 定档，形状对齐 Issue 子集） */
+type RefineDiag = {
+    code: string;
+    message: string;
+    file?: string;
+};
+/** 设置诊断观察者（null 清除）；缓冲照常累积，takeRefineDiags 取走 */
+declare function setRefineDiagCollector(fn: ((d: RefineDiag) => void) | null): void;
+/** 当前诊断累计序号（since 锚） */
+declare function refineDiagCount(): number;
+/** 取走已收集的诊断（收集即清空） */
+declare function takeRefineDiags(): RefineDiag[];
+/** 只取走 seq > since 的增量（工具面防窃取在途诊断；全量 take 的 since 版） */
+declare function takeRefineDiagsSince(since: number): RefineDiag[];
+/** 侧车模块错误：code ∈ nudo:interface-cycle | nudo:interface-load */
+declare class NudoSidecarError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * 执行 *.nudo.js（真实 JS + 我们的构建器）。import/export 由 Babel 语句级
+ * 改写：多行 named import、注释/字符串里的同形文本不误伤；相对 .nudo 递归
+ * 求值；环 → throw NudoSidecarError。结果进 exec 缓存（依赖闭包内容指纹键）。
+ */
+declare function execNudoModule(src: string, opts?: RefineResolveOpts): Record<string, unknown>;
+type RefineResolveOpts = {
+    loadModule?: (spec: string, fromFile: string) => string | undefined;
+    /** 侧车自身的路径（相对 spec 解析基准 + 环检测链起点） */
+    fromFile?: string;
+};
+declare function resetNudoModuleExecCache(): void;
+/**
+ * 解析 `ms delay` / `n percent` → [param, Pred]
+ * 多条用 && 或换行连接。
+ * 同时保留原始 NudoConstraint（shape 字段检查用）。
+ */
+type RefineEntry = {
+    param: string;
+    pred: Pred;
+    constraint: NudoConstraint;
+};
+declare function extractRefinesFromSource(source: string, fnName: string, opts?: RefineResolveOpts): RefineEntry[];
+/** refine 参数 → 带约束模板的下标表（shape 检查用） */
+declare function refineToIndexedFull(source: string, fnName: string, paramNames: string[], opts?: RefineResolveOpts): Array<[number, RefineEntry]>;
+/**
+ * 解析 `@nudo:contract return positive` → 返回契约。
+ * 返回 undefined = 无声明（不猜后置）。
+ */
+declare function extractRefineReturnFromSource(source: string, fnName: string, opts?: RefineResolveOpts): {
+    name: string;
+    constraint: NudoConstraint;
+} | undefined;
+/**
+ * 申报式抛错（declare throws — L2 豁免）：
+ *   @nudo:throws Error
+ *   @nudo:throws Error, TypeError
+ *   @nudo:throws *
+ *   @nudo:case "neg" (0) !! throws          → 申报任意 throw
+ *   @nudo:case "neg" (0) !! throws Error    → 申报 Error
+ *
+ * 与 refine 同扫函数前注释块。返回 `*` = 申报任意；数组 = 按名申报；
+ * undefined = 无申报（L2 照常执法）。
+ */
+declare function extractDeclaredThrows(source: string, fnName: string): string[] | "*" | undefined;
+
+/**
+ * Interface 分层推导（design-refine-derivation §2.1/§2.2/§11 第 0 步）：
+ *
+ *   effectiveInterface(source, fnName) —— 手写 ∪ 侧车同名绑定 ∪ 生成段的
+ *   唯一读取口，来源标注（handwritten / generated / implicit）随值返回。
+ *
+ * 来源三层（合并序 handwritten > generated > implicit，§4/§11）：
+ * - handwritten：源码 `@nudo:contract`/`@nudo:contract` 行（复用 refine.ts 的
+ *   extractRefinesFromSource / extractRefineReturnFromSource）∪ 侧车同名**手写**
+ *   fn() 绑定。同名同参取合取 and()（§2.1：侧车 x>0 + 源码 x>1 → 有效契约
+ *   取合取）；常数界交叉矛盾（x>0 ∧ x<0）→ conflict 标记，由调用方报
+ *   nudo:interface-conflict——本函数不 throw。
+ * - generated：侧车同名导出且声明上方注释块含 @generated 标记（emit 产物）。
+ *   与手写并存时整体降级忽略（手写为准；混排由 nudo:interface-name-clash /
+ *   drift 在 emit/check 侧处理）。
+ * - implicit：无任何契约 → 返回 undefined（隐式推断是调用方的事）。
+ *
+ * 自动绑定边界（§2.2）：只绑源文件**本地 named export**（re-export /
+ * export default / 私有名不绑）；opts.autoBind === false 或侧车路径含
+ * /node_modules/ → 不 ambient 加载（只看源码 refine）。opts.projectDir
+ * 提供时，树外侧车不 ambient 绑定（host 从 findProjectConfig 下传）。
+ *
+ * 侧车绑定 Phase 1 只承诺 fn() 形态：非 fn 的标量/shape 绑定不消费，收集
+ * nudo:interface-load 诊断（后续 Phase 再放开单参形态）。
+ *
+ * 诊断走本文件独立 side-channel（先例 refine.ts 的 setRefineDiagCollector）：
+ * 侧车加载/执行失败 → nudo:interface-cycle / nudo:interface-load。
+ */
+
+/** interface 推导诊断（severity 由消费方按 code 定档，形状对齐 Issue 子集） */
+type InterfaceDiag = {
+    code: string;
+    message: string;
+    file?: string;
+};
+/** 设置诊断观察者（null 清除）；缓冲照常累积，takeInterfaceDiags 取走 */
+declare function setInterfaceDiagCollector(fn: ((d: InterfaceDiag) => void) | null): void;
+/** 当前诊断累计序号（since 锚：工具面只排干自身探测产生的增量） */
+declare function interfaceDiagCount(): number;
+/** 取走已收集的诊断（收集即清空） */
+declare function takeInterfaceDiags(): InterfaceDiag[];
+/**
+ * 只取走 seq > since 的诊断（清空仅限增量）——LSP 长驻进程里 lens/打印/
+ * emit 工具用它排干**自身探测**产生的诊断，不窃取在途 validateText 待消费
+ * 的接口诊断（全量 take 曾在 await 窗口偷走 checkSource 的待收诊断）。
+ */
+declare function takeInterfaceDiagsSince(since: number): InterfaceDiag[];
+/** 有效契约来源：手写（源码 refine ∪ 侧车手写绑定）> 生成段 > 隐式 */
+type InterfaceSource = "handwritten" | "generated" | "implicit";
+/**
+ * 源文件本地导出名表（侧车自动绑定边界）：
+ * - ESM：`export function/const/let/var/class` 与本地 `export { x }` /
+ *   `export { local as exported }`（按**导出名**绑定）；
+ * - `export default function add` / `const add = …; export default add`：
+ *   按**本地名** `add` 绑定（侧车可 `export const add = fn(…)`）；
+ *   同时登记 `"default"`，供侧车 `export default fn(…)` 对齐；
+ * - CJS（C4.3）：`module.exports = { a, b }`、`module.exports.a = …`、
+ *   `exports.a = …`、`module.exports = localFn`（登记 localFn 名）。
+ * 排除 re-export（`export {x} from` / `export *`）。
+ */
+declare function localNamedExports(source: string): Set<string>;
+/**
+ * 侧车源码的生成段导出名：export 之前（跳过紧邻的 import/const 链）的注释
+ * 行含 `@generated` → 该名为 generated。组合式下行段（§5.3）形态为
+ * `import` + `@generated 头` + prelude + export；callsite 段则是头紧贴
+ * export。隔了其他代码行 / 无标记 / re-export 列表均不算。
+ */
+declare function generatedExportNames(sidecarSrc: string): Set<string>;
+type EffectiveInterfaceOpts = RefineResolveOpts & {
+    /** false（或谓词返回 false）→ 不 ambient 加载侧车；默认 true */
+    autoBind?: boolean | ((sidecarPath: string) => boolean);
+    /**
+     * 项目根（host 从 findProjectConfig 下传）。提供时 ambient 绑定仅接受
+     * 树内侧车；树外 → 不加载。undefined = 不限（测试/脚本；node_modules 仍拦）。
+     */
+    projectDir?: string;
+};
+type EffectiveInterface = {
+    fnName: string;
+    params: Array<{
+        param: string;
+        constraint: NudoConstraint;
+    }>;
+    returns?: {
+        constraint: NudoConstraint;
+    };
+    /** 申报式抛错（@nudo:throws / case !! throws / sidecar fn.throws） */
+    throws?: {
+        kinds: string[] | "*";
+    };
+    source: InterfaceSource;
+    /**
+     * 合取不可满足标记：params = 常数界交叉矛盾（或 prim 矛盾等 and() 不可
+     * 合取形态）的参数名；returns = 返回位同样不可满足。调用方报
+     * nudo:interface-conflict 并跳过对应位执法。
+     */
+    conflict?: {
+        params: string[];
+        returns?: boolean;
+    };
+};
+/**
+ * 单点读取口：手写 ∪ 侧车同名 ∪ 生成段 → 有效契约（含来源标注）。
+ * 无任何契约 → undefined（implicit 由调用方处理）。
+ */
+declare function effectiveInterface(source: string, fnName: string, opts?: EffectiveInterfaceOpts): EffectiveInterface | undefined;
+/**
+ * 侧车及递归 .nudo 依赖闭包的内容指纹：`${hashSource(侧车)}|路径=hash,…`。
+ * 无 loadModule / autoBind 关闭 / node_modules / loadModule miss → undefined
+ * （无侧车影响即无需指纹）。闭包截断 → `trunc:` 前缀，键不可信，调用方
+ * fail-open（参照 loadModuleDepsFingerprint 的 truncated 契约）。
+ */
+declare function sidecarClosureFingerprint(fromFile: string, opts: EffectiveInterfaceOpts): string | undefined;
+/** 组合式显示：重建构建器调用形态（number().gt(0) / union(…) / fn(…)） */
+declare function formatConstraint(c: NudoConstraint): string;
+/** EffectiveInterface → 契约展示串（与 CLI interface 打印同口径，不含函数名） */
+declare function formatEffectiveInterfaceDisplay(eff: EffectiveInterface): string;
+/** CodeLens / hover 首行标题（design-refine-derivation §8）：`● interface / <source>` */
+declare function formatInterfaceTierLine(source: InterfaceSource): string;
+type InterfaceTierInfo = {
+    source: InterfaceSource;
+    /** handwritten/generated 时的契约展示；implicit 为 undefined */
+    display?: string;
+};
+type InterfaceTierOpts = EffectiveInterfaceOpts;
+/**
+ * interface 档单一读取口（A7）：CodeLens `● interface`、hover、inlay、
+ * semantic tokens 共用本函数，保证「同源」。
+ *
+ * 与 computeInterfaceLenses 同口径：仅源文件 **本地 named export** 进档；
+ * 私有名 / 非导出 → undefined（不进 interface 档，不假装 implicit 契约）。
+ */
+declare function interfaceTierOf(source: string, fnName: string, fromFile: string, opts?: InterfaceTierOpts): InterfaceTierInfo | undefined;
+/** interfaceTierOf 的来源投影；非导出 → undefined */
+declare function interfaceSourceOf(source: string, fnName: string, fromFile: string, opts?: InterfaceTierOpts): InterfaceSource | undefined;
+
+type LoadDepsFingerprint = {
+    fp: string;
+    paths: string[];
+    /**
+     * path + loadModule-resolved content（miss → null）。调用方（磁盘缓存键）
+     * 必须优先用这里的 content，不得回读磁盘——否则 buffer-aware loadModule
+     * 与磁盘不一致时键会分叉。
+     */
+    contents: Array<{
+        path: string;
+        content: string | null;
+    }>;
+    /** BFS 撞到节点上限：剩余 dep 未进指纹，键不可信 */
+    truncated: boolean;
+};
+/**
+ * All string module specs that analysis may resolve through loadModule.
+ * Regex over-approximates (may hit comments) — extra dep fingerprint is safe
+ * (more misses, never a stale hit).
+ */
+declare function extractAllLoadSpecs(source: string): string[];
+/**
+ * 源里指向其他侧车的相对 spec（`.nudo.js`/`.nudo.ts`）。regex 过近似安全：
+ * 多算的 dep 只带来额外 miss，绝不产生陈旧命中。LSP 隐式依赖登记共用。
+ */
+declare function sidecarSpecsOf(source: string): string[];
+/**
+ * Fingerprint every loadModule-reachable dep (not only `*.nudo.js`), including
+ * one hop of transitive specs from each dep source — plus the autoBind 侧车
+ * 闭包（`sidecar:` 前缀条目）。
+ *
+ * 侧车吸收范围 = fromFile 自身 **与每一个成功加载的依赖文件**的旁路侧车及其
+ * 递归 .nudo 依赖：跨文件被调（scan.ts checkExternalCall）会按定义文件路径
+ * ambient 绑定其侧车，依赖侧车内容影响调用方报告——不进指纹则编辑后 memo
+ * 陈旧命中（错诊断）。侧车 loadModule miss（无侧车文件）→ 不加任何条目。
+ *
+ * 注意：本扩展对 autoBind=false 与 /node_modules/ 均**不** gate（刻意过近似，
+ * 只过度失效、绝不陈旧命中——安全方向）；ambient 生效边界由
+ * interface.ts 的 sidecarClosureFingerprint 负责，两者职责不同。
+ */
+declare function loadModuleDepsFingerprint(source: string, loadModule: (spec: string, fromFile: string) => string | undefined, fromFile: string): LoadDepsFingerprint;
+
+/**
+ * 约束诊断：检查调用点实参是否满足函数的前置约束 / 参数 shape。
+ * 输出可行动的建议，而不是 TS 式「类型不匹配」。
+ */
+
+type Diagnostic = {
+    severity: "error" | "warning" | "info";
+    code: string;
+    message: string;
+    suggestion?: string;
+    fn?: string;
+    argIndex?: number;
+};
+/**
+ * 检查实参是否满足「期望约束」。
+ * expect: 相对参数 term 的 pred，例如 term > 0
+ * arg: 实际实参 Abs
+ */
+declare function checkArg(arg: Abs, expect: Pred | undefined, phi?: Phi): Diagnostic | undefined;
+/**
+ * 对一次函数调用做诊断：实参 shape + 约束。
+ */
+declare function checkCall(source: string, fnName: string, args: Abs[], phi?: Phi): Diagnostic[];
+declare function formatDiagnostics(diags: Diagnostic[]): string;
+
+/**
+ * check 报告面：数据模型 + 渲染/序列化。
+ *
+ * 分析在 check.ts（Abs 优先的 Nudo 原生诊断），这里只投影：
+ * - formatCheckReport → 人类可读文本
+ * - serializeCheckJson → `nudo check --json` 稳定契约（CI / Agent，v1）
+ * - formatGithubAnnotations → PR 行内 `::error` / `::warning`（GHA）
+ * - formatGitlabCodeQuality → GitLab Code Quality JSON 数组
+ */
+
+/** 无损函数签名（类型即计算） */
+type NudoSig = {
+    name: string;
+    params: string[];
+    /** 形参类型展示（入口无约束 = any） */
+    paramTypes?: string[];
+    /** 符号 Abs 本体 */
+    abs: Abs;
+    /** formatAbs 单行 */
+    display: string;
+    /** formatAbsMultiline */
+    detail: string;
+    conf: Confidence;
+    /** throws 域展示（如 TypeError）；省略 = 无 may-throw */
+    throws?: string;
+    /** 模块边界入口（export / default / CJS exports） */
+    entry?: boolean;
+};
+type CheckIssue = Diagnostic & {
+    fn?: string;
+    line?: number;
+    column?: number;
+    /** 实参 / 实际值的 Abs 展示 */
+    actual?: string;
+    /** 期望约束（Pred 或 Abs 展示） */
+    expected?: string;
+    /**
+     * AI1：结构化下一步（additive）。agent 优先消费 `actions`，
+     * 不必解析 `suggestion` 散文；`command` 可直接执行。
+     */
+    actions?: CheckAction[];
+};
+/** 结构化修复动作（AI1；稳定枚举，只增不改语义） */
+type CheckAction = {
+    /** draft=生成侧车草稿 · relax=放宽契约 · callsite=改实参 · assume/mock/emit/ignore=辅助 */
+    kind: "draft" | "relax" | "callsite" | "assume" | "mock" | "emit" | "ignore-throws" | "info";
+    /** agent 可执行命令（无则只读 label/hint） */
+    command?: string;
+    /** 一行说明（与 suggestion 同源或更短） */
+    label: string;
+    /** 可选：目标 Pred / 字段名等，供程序化改写 */
+    hint?: string;
+};
+type CheckReport = {
+    file: string;
+    issues: CheckIssue[];
+    /** 有 error 则 CI 应失败 */
+    ok: boolean;
+    /** Abs 优先的签名表（替代 TS 式 display-only） */
+    signatures: NudoSig[];
+    summary: {
+        errors: number;
+        warnings: number;
+        infos: number;
+        functions: number;
+    };
+    /**
+     * A2 预算/截断可观测（additive）。`truncated=true` 时部分结果可能已
+     * widen 成 unknown——不是契约失败，是引擎预算。
+     */
+    budget?: {
+        truncated: boolean;
+        callTruncated: boolean;
+        forkTruncated: boolean;
+        calls: number;
+        maxCalls: number;
+        forks: number;
+        maxForks: number;
+    };
+};
+/**
+ * `nudo check --json` 稳定契约（供 CI / Agent）。
+ * 字段只增不改语义；Abs 以 formatAbs 字符串给出，不序列化内部 shape 图。
+ */
+type CheckJson = {
+    version: 1;
+    file: string;
+    ok: boolean;
+    summary: CheckReport["summary"];
+    signatures: Array<{
+        name: string;
+        params: string[];
+        paramTypes?: string[];
+        display: string;
+        detail: string;
+        conf: string;
+        abs: string;
+        throws?: string;
+        entry?: boolean;
+    }>;
+    issues: Array<{
+        severity: string;
+        code: string;
+        message: string;
+        fn?: string;
+        line?: number;
+        column?: number;
+        actual?: string;
+        expected?: string;
+        suggestion?: string;
+        /** AI1：结构化 next-action（只增字段） */
+        actions?: CheckAction[];
+    }>;
+    /** A2：预算用量 / 是否截断（additive） */
+    budget?: CheckReport["budget"];
+};
+/** 诊断码 → 结构化动作（AI1）；未知码给 info 提示 */
+declare function actionsForIssue(i: {
+    code: string;
+    expected?: string;
+    suggestion?: string;
+    fn?: string;
+}): CheckAction[];
+/** 多文件 `check --json` 信封（CI / monorepo）。单文件仍输出裸 CheckJson。 */
+type CheckJsonMulti = {
+    version: 1;
+    kind: "multi";
+    ok: boolean;
+    summary: CheckReport["summary"] & {
+        files: number;
+        budgetTruncated?: boolean;
+    };
+    budget?: CheckReport["budget"];
+    reports: CheckJson[];
+};
+declare function serializeCheckJson(r: CheckReport): CheckJson;
+/** 多文件信封：汇总 summary，`ok` = 全部文件 ok。 */
+declare function serializeCheckJsonMulti(reports: CheckJson[]): CheckJsonMulti;
+/**
+ * Nudo 原生报告：Abs 签名表 + actual ⊭ expected。
+ * 不是 tsc 输出的换皮。
+ */
+declare function formatCheckReport(r: CheckReport, opts?: {
+    verbose?: boolean;
+}): string;
+/**
+ * GitHub Actions 行内注解（PR Files changed 红/黄标）。
+ * 协议：`::error file=…,line=…,col=…,title=…::message`
+ * 详见 https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+ */
+declare function formatGithubAnnotations(r: CheckReport, opts?: {
+    workspaceRoot?: string;
+}): string;
+type GitlabCodeQualityIssue = {
+    description: string;
+    check_name: string;
+    fingerprint: string;
+    severity: "major" | "minor" | "info" | "blocker" | "critical";
+    location: {
+        path: string;
+        lines: {
+            begin: number;
+        };
+    };
+};
+/** GitLab Code Quality 报告数组（`--gitlab`；可写 gl-code-quality-report.json） */
+declare function formatGitlabCodeQuality(r: CheckReport, opts?: {
+    workspaceRoot?: string;
+}): GitlabCodeQualityIssue[];
+
+export { fn as $, NudoSidecarError as A, type NudoSig as B, type CheckIssue as C, type Diagnostic as D, type EffectiveInterfaceOpts as E, type RefineEntry as F, type GitlabCodeQualityIssue as G, type RefineResolveOpts as H, type InterfaceSource as I, actionsForIssue as J, andC as K, type LeakBudget as L, any as M, type NudoConstraint as N, array as O, boolean as P, checkArg as Q, type RefineDiag as R, SELF as S, checkCall as T, constraintToEntryAbs as U, effectiveInterface as V, execNudoModule as W, extractDeclaredThrows as X, extractNudoImports as Y, extractRefineReturnFromSource as Z, extractRefinesFromSource as _, type InterfaceTierOpts as a, fnConstraintToEntryReqs as a0, formatCheckReport as a1, formatConstraint as a2, formatDiagnostics as a3, formatEffectiveInterfaceDisplay as a4, formatGithubAnnotations as a5, formatGitlabCodeQuality as a6, formatInterfaceTierLine as a7, generatedExportNames as a8, getParseSourceCacheSize as a9, string as aA, takeInterfaceDiags as aB, takeInterfaceDiagsSince as aC, takeRefineDiags as aD, takeRefineDiagsSince as aE, throwConstraintToKinds as aF, union as aG, getTerm as aa, instantiateConstraint as ab, interfaceDiagCount as ac, interfaceSourceOf as ad, interfaceTierOf as ae, isIntFlag as af, isNodeModulesPath as ag, isNudoConstraint as ah, lenTerm as ai, litC as aj, localNamedExports as ak, number as al, omit as am, partial as an, pick as ao, refineDiagCount as ap, refineToIndexedFull as aq, resetNudoModuleExecCache as ar, resetParseSourceCache as as, serializeCheckJson as at, serializeCheckJsonMulti as au, setInterfaceDiagCollector as av, setRefineDiagCollector as aw, shape as ax, sidecarClosureFingerprint as ay, sidecarPathOf as az, type LoadDepsFingerprint as b, extractAllLoadSpecs as c, defaultLeakBudget as d, exceedsBudget as e, loadModuleDepsFingerprint as f, resolveDepPath as g, termNodes as h, type CheckReport as i, type CheckAction as j, type CheckJson as k, leakIfNeeded as l, maybeLeak as m, normPath as n, type CheckJsonMulti as o, parseSource as p, type ConstraintBuilder as q, resetLeakCounter as r, sidecarSpecsOf as s, termDepth as t, type EffectiveInterface as u, type InterfaceDiag as v, type InterfaceTierInfo as w, type NamedImport as x, type NudoField as y, type NudoFnConstraint as z };