@nudojs/service 1.0.1 → 1.1.1

package/dist/emit/index.d.ts

@@ -0,0 +1,619 @@
+import { C as CallRecord } from '../call-record-CkyCFkT9.js';
+import { L as LoadModule } from '../what-if-mIo7I5Ii.js';
+export { T as TypeBinding, i as injectBindings, t as typeExprToDirective } from '../what-if-mIo7I5Ii.js';
+import { NudoConstraint, Abs } from '@nudojs/core';
+import { A as AnalysisResult, F as FunctionAnalysis, S as SourceLocation } from '../analyzer-types-CfBrPK9L.js';
+import '@babel/types';
+
+/**
+ * `nudo contract` 的打印数据源（design-refine-derivation §11 第 0 步）：
+ * 逐顶层函数展示有效契约分层——effectiveInterface 命中（手写契约 / 侧车
+ * 生成段）时 params/returns 用 formatConstraint 组合式显示；未命中走
+ * implicit：优先 CaseResult.argAbs / FunctionAnalysis.combinedAbs（无损
+ * Abs 源），展示用 formatShape（外延口径，不强求约束式、不带 conf）。
+ *
+ * autoBind 沿 package.json#nudo.contract（findProjectConfig → interfaceConfig）
+ * 下传，可用 opts 覆盖（测试 / CLI 显式开关）；读盘用 defaultLoadModule
+ * （与 check 的 refine 解析同一扩展名表）。
+ *
+ * B3 Phase B：`nudo.cache` / NUDO_CACHE_DIR 打开时，整文件 effectiveInterface
+ * 表（含 implicit 负缓存 null）落盘；二次冷启动跳过侧车 exec / 契约合并。
+ * 缓存只服务打印/表面，不加速 B-path 分析（design-persistent-cache §0）。
+ */
+
+type InterfaceSurfaceEntry = {
+    fn: string;
+    /** 本文件 named export（自动绑定边界口径：localNamedExports） */
+    kind: "export" | "local";
+    source: "handwritten" | "generated" | "implicit";
+    params: Array<{
+        name: string;
+        display: string;
+    }>;
+    returns?: string;
+};
+type InterfaceSurfaceOpts = {
+    /** 覆盖项目配置的 autoBind（默认 findProjectConfig → interfaceConfig） */
+    autoBind?: boolean;
+    /** 模块源码装载器（测试注入）；默认 defaultLoadModule 真实读盘 */
+    loadModule?: LoadModule;
+    /** 跨文件调用记录（--from 采集）：implicit 展示的实参域原料 */
+    records?: CallRecord[];
+    /** 打开 buffer 覆盖磁盘源码（E5：agent/LSP 与 hover 同口径） */
+    source?: string;
+};
+/** 单条 interface 打印行（CLI runInterface 与 LSP agent 面共用） */
+declare function formatInterfaceSurfaceLine(e: InterfaceSurfaceEntry): string;
+/**
+ * 单文件 interface 表面：analyzer 推断结果给出函数清单与 implicit 展示，
+ * effectiveInterface 给出契约命中（手写 > 生成段）。诊断 side-channel
+ * 在收尾时取走丢弃——打印命令不执法，interface-load 等错误留给 check 路径。
+ */
+declare function interfaceSurface(filePath: string, opts?: InterfaceSurfaceOpts): Promise<InterfaceSurfaceEntry[]>;
+
+/**
+ * `nudo contract --emit` 的写盘器（design-refine-derivation §5.4 / §7.3 / §11）：
+ * 把分析产出的调用点域投影（joinThenProject，先 Abs join 再投影）固化为侧车
+ * `*.nudo.js` / `*.nudo.ts` 的 `@generated` 段——`export const <fn> = fn({…}, …)`。
+ *
+ * - 生成段 = 三行：`@generated` 头注释 + `// source: <相对file>:<fn>` + export 行。
+ *   DSL 由 formatConstraint 产出，**写入前 round-trip 自检**（生成文本经
+ *   execNudoModule 求值、导出须 isNudoConstraint 且 fn 槽存在）：展示兜底形态
+ *   （`x?:` 可选字段、`.eq()` 伪链、`{谓词原文}`）不是合法 DSL，自检拦下 →
+ *   not-projectable 跳过，不写垃圾。
+ * - 手写导出永不覆盖：目标名已是侧车手写绑定 → 跳过写入并报
+ *   `nudo:interface-name-clash`（error，手写优先）。
+ * - mode=update：剥离全部生成段再重排（幂等；非目标的既有生成段原样保留，
+ *   不随 --fn 丢失）；mode=add：仅追加缺失段。
+ * - 目标过滤（§7.3）：--fn 白名单 > --all 全量 > 默认只刷新已有生成段
+ *   （「无根只处理已存在生成段」；Phase 1 无 root 闭包下行推导）。
+ * - autoBind=false 不影响 emit（显式动作，非 ambient 加载）。
+ */
+
+type EmitInterfaceSkipReason = "name-clash" | "not-projectable" | "not-an-export" | "no-change"
+/** package.json#nudo.contract.emit 白名单拒绝 */
+ | "emit-denied"
+/** 手工合并的多声明符 @generated 段：按段原子保留，不拆不重写 */
+ | "multi-declarator";
+type EmitInterfaceOpts = {
+    /** 目标导出名白名单（Phase 1：只过滤目标文件自身的导出；跨文件 root 闭包 emit 是 Phase 2 下行推导能力） */
+    fnNames?: string[];
+    /** update=剥离全部生成段再重排（幂等）；add=仅追加缺失段 */
+    mode: "add" | "update";
+    /** 全部顶层导出（显式 opt-in，CLI 侧文档警告勿默认） */
+    all?: boolean;
+    /** 不写盘，返回 unifiedDiff */
+    dryRun?: boolean;
+    /**
+     * 跨文件调用记录（--from 采集）：域根导出（本文件无调用点、仅有
+     * 外部使用现场记录）的投影原料；缺省时仅用本文件调用点证据。
+     */
+    records?: CallRecord[];
+    /** 缓冲源（E5：agent/LSP 与 validate 同源）；缺省读盘 */
+    source?: string;
+    /** 模块装载器（buffer-aware 侧车可见）；缺省 defaultLoadModule */
+    loadModule?: (spec: string, fromFile: string) => string | undefined;
+};
+type EmitInterfaceResult = {
+    written: string[];
+    skipped: Array<{
+        fn: string;
+        reason: EmitInterfaceSkipReason;
+    }>;
+    changed: boolean;
+    diff?: string;
+    issues: Array<{
+        code: string;
+        severity: "error" | "warning";
+        message: string;
+    }>;
+    /** 侧车绝对路径（新建或已有） */
+    sidecarPath: string;
+    /**
+     * 默认过滤（无 --fn/--all）且侧车无既有 @generated 段可刷 —— 调用方
+     * 用它把「no interface changes」解释成首次 emit 的用法提示，而非漂移。
+     */
+    emptyDefaultTargets?: boolean;
+};
+/**
+ * 单文件 emit：分析 → 逐目标投影/自检 → 组装侧车内容 →（非 dryRun）写盘。
+ * 诊断 side-channel（round-trip 自检触发的 refine/interface diags）收尾取走丢弃。
+ */
+declare function emitInterface(filePath: string, opts: EmitInterfaceOpts): Promise<EmitInterfaceResult>;
+/**
+ * emit 摘要行（CLI runInterfaceEmit 与 LSP agent 面共用；路径由调用方按
+ * 展示口径传入——CLI 传 cwd 相对、agent 传绝对路径）。
+ */
+declare function formatEmitSummary(sourcePath: string, sidecarRel: string, result: EmitInterfaceResult): string[];
+
+/**
+ * `nudo contract --draft`：从已有 JS **逻辑** 生成 contract 草稿。
+ *
+ * 产品位（代码优先 / 迁移）：先写实现，再反推可审阅的 `fn({…}, …)` 草稿；
+ * 人审后迁入 `*.nudo.js` 才成为契约。
+ *
+ * 证据分层（与 C0 一致：草稿 ≠ ambient 义务）：
+ * - callsite / directive case → joinThenProject 值域（迁移最可信）
+ * - body 触达（**仅草稿展示**）→ 参数上被读到的字段名建议；不进 check
+ * - generalize symbolic → 返回位兜底
+ * - 无证据 → 参数槽省略 + 注释 TODO（不发明义务）
+ * - 已有 handwritten 契约 → **跳过**（手写优先，不覆盖）
+ *
+ * 写盘：默认只打印；`--write` 写入 `<file>.nudo.draft.js`——**不会**被
+ * sidecar 自动绑定（loadModule 只认 `*.nudo.js`）。审阅后复制进正式侧车。
+ */
+
+/**
+ * DraftEvidence `body` = 仅来自函数体对形参的成员读取（草稿建议，非义务）。
+ * check / effectiveInterface **永不**消费该档。
+ */
+type DraftEvidence = "callsite" | "directive" | "symbolic" | "body" | "none";
+type InterfaceDraftEntry = {
+    fn: string;
+    /** 全部形参（含无证据槽，便于人读） */
+    params: Array<{
+        name: string;
+        constraint?: NudoConstraint;
+        display: string;
+        /** false = 无证据，DSL 对象里省略该槽 */
+        projected: boolean;
+        /** 函数体读到的字段名（草稿建议；与 projected 无关） */
+        bodyAccesses?: string[];
+    }>;
+    returns?: {
+        constraint?: NudoConstraint;
+        display: string;
+        projected: boolean;
+    };
+    paramEvidence: DraftEvidence;
+    returnEvidence: DraftEvidence;
+    skipped?: "handwritten" | "not-an-export";
+    /** 草稿 DSL：`fn({ … }, …)`；handwritten / 非导出时 undefined */
+    dsl?: string;
+};
+type InterfaceDraftOpts = {
+    fnNames?: string[];
+    records?: CallRecord[];
+    loadModule?: LoadModule;
+    /**
+     * Accepted for API compatibility; **ignored**. The handwritten-contract probe
+     * always uses `effectiveInterface(..., { autoBind: true })` so draft skips
+     * disk sidecars even when ambient autoBind is off (product: draft asks
+     * "does a contract already exist?", not "is ambient binding on?").
+     */
+    autoBind?: boolean;
+    /** 默认 true：收集 body 成员读取作草稿建议（永不进 check） */
+    bodyAccesses?: boolean;
+    /** 打开 buffer 源（E5：与 hover/interface 同口径） */
+    source?: string;
+};
+type InterfaceDraftResult = {
+    file: string;
+    entries: InterfaceDraftEntry[];
+    draftSource: string;
+    sidecarPath: string;
+};
+/**
+ * Draft-only：收集每个顶层函数形参上的成员读取键（`user.name` → name）。
+ * **不是** C0 禁止的 body→义务通道——只进草稿注释/建议，check 不读此表。
+ */
+declare function collectParamBodyAccesses(source: string): Map<string, Map<string, Set<string>>>;
+/**
+ * 为单文件顶层导出生成 interface 草稿（不写盘）。
+ * handwritten 跳过；已有 @generated 仍出草稿（便于对照）。
+ */
+declare function draftInterface(filePath: string, opts?: InterfaceDraftOpts): Promise<InterfaceDraftResult>;
+/** 草稿模块文本（人读 + 可复制到 *.nudo.js / *.nudo.ts） */
+declare function formatDraftModule(filePath: string, entries: InterfaceDraftEntry[], sidecarPath?: string): string;
+/** `lib.js|ts` → `lib.nudo.draft.js|ts`（不进 ambient sidecar 表） */
+declare function sidecarDraftPath(filePath: string): string;
+type WriteDraftResult = {
+    draftPath: string;
+    written: boolean;
+    changed: boolean;
+    draftable: boolean;
+    draftSource: string;
+};
+/** Parse-layer draftable: at least one entry has generated DSL and was not skipped */
+declare function isDraftableEntry(entries: ReadonlyArray<Pick<InterfaceDraftEntry, "dsl" | "skipped">>): boolean;
+/**
+ * 写入 `*.nudo.draft.js`（覆盖草稿文件本身；不碰正式 `*.nudo.js`）。
+ * 基础路径防护：拒绝 node_modules；拒绝 draft 路径与正式侧车重合；
+ * 拒绝 draft 路径落在源文件目录之外的穿越。
+ *
+ * `opts.entries` / `opts.draftable`：解析层判定（优先）。缺省时用 Unicode
+ * 感知 export 正则兜底——`\w` 会静默丢掉 `计算` 这类标识符。
+ */
+declare function writeInterfaceDraft(filePath: string, draftSource: string, opts?: {
+    dryRun?: boolean;
+    projectDir?: string;
+    entries?: ReadonlyArray<Pick<InterfaceDraftEntry, "dsl" | "skipped">>;
+    draftable?: boolean;
+}): WriteDraftResult;
+declare function formatDraftSummary(sourceRel: string, draftRel: string, result: InterfaceDraftResult, write?: WriteDraftResult): string[];
+
+/**
+ * Derivation slot projection（Abs → 组合式 DSL 投影缝）。
+ * 自 interface-derivation.ts 机械拆出；语义未改。
+ */
+
+type ConstraintSourceExpr = {
+    expr: string;
+    importFrom?: string;
+    importName?: string;
+};
+type DerivedParam = {
+    name: string;
+    constraint: NudoConstraint;
+    dsl: string;
+    prelude: string[];
+    imports: Array<{
+        name: string;
+        from: string;
+    }>;
+    /** 单链组合式投影时的推导图 root 节点 id（返回位相对锚定用） */
+    rootNodeId?: number;
+    /** 该参数位自 root 起消耗的 shift 步数（与 prelude 行数无关，读图） */
+    shiftCount?: number;
+};
+type DerivedExport = {
+    file: string;
+    fn: string;
+    paramNames: string[];
+    params: DerivedParam[];
+    returns?: {
+        constraint: NudoConstraint;
+        dsl: string;
+        prelude: string[];
+        imports: Array<{
+            name: string;
+            from: string;
+        }>;
+    };
+    /** `lib.js:add4` */
+    derivedFrom: string;
+    compositional: boolean;
+    underivable?: boolean;
+};
+type RootDeriveOpts = {
+    loadModule?: LoadModule;
+    autoBind?: boolean;
+    fnNames?: string[];
+    /**
+     * true：只刷新目标侧车里**已存在**的 @generated 段（CLI 无 --fn/--all 时
+     * 的默认行为——不发明新下游契约）。false/省略：闭包内全部可推导导出。
+     */
+    refreshExistingOnly?: boolean;
+};
+type RootDeriveResult = {
+    roots: string[];
+    derived: DerivedExport[];
+    hasRoot: boolean;
+};
+
+declare function extractFnConstraintSources(sidecarSrc: string, fnName: string): {
+    params: Record<string, ConstraintSourceExpr>;
+    returns?: ConstraintSourceExpr;
+};
+/**
+ * 入口：对 filePath 做 root 驱动下行推导。
+ */
+declare function deriveFromRoot(filePath: string, opts?: RootDeriveOpts): RootDeriveResult;
+
+/**
+ * 组装生成段（组合式 + import + prelude）。
+ * importFrom 相对 root 侧车解析，再相对 target 侧车写出。
+ *
+ * `takenNames`：侧车顶层已占用标识符（手写 / 既有生成段 / 本批先前段）。
+ * 同文件多导出时对 import local 与 prelude local 做避让改写，
+ * 保证拼出的侧车在模块作用域内无重复声明。
+ */
+declare function formatDerivedSection(row: DerivedExport, opts: {
+    rootSidecarDir: string;
+    targetSidecarDir: string;
+    takenNames?: Iterable<string>;
+}): {
+    text: string;
+    usedNames: string[];
+} | undefined;
+
+type EmitDerivedResult = {
+    /** 被写/将写的下游侧车（绝对路径） */
+    sidecars: Array<{
+        file: string;
+        sidecarPath: string;
+        fn: string;
+        written: boolean;
+        changed: boolean;
+        skipped?: "name-clash" | "not-projectable" | "underivable" | "no-change";
+        diff?: string;
+        issues: Array<{
+            code: string;
+            severity: "error" | "warning" | "info";
+            message: string;
+        }>;
+    }>;
+    hasRoot: boolean;
+    roots: string[];
+    /** 根在别处 / 无契约根且无已存在生成段 → info */
+    entryOnly?: boolean;
+};
+declare function emitDerivedFromRoot(rootFile: string, opts: {
+    fnNames?: string[];
+    mode: "add" | "update";
+    dryRun?: boolean;
+    loadModule?: LoadModule;
+    autoBind?: boolean;
+    /** 只刷新目标侧车里已存在的 @generated 段（不发明新下游契约） */
+    refreshExistingOnly?: boolean;
+}): EmitDerivedResult;
+
+/**
+ * Abs → TS 类型串。有损：pred / 非 lit term 落到 shape 基类型。
+ * `typeVars`：term var id → TS 类型参数名（HOF 泛型投影时传入；
+ * `any`+var 在此映射下渲染为该参数名，否则 `unknown`）。
+ */
+declare function absToTSType(a: Abs, typeVars?: Map<string, string>): string;
+/**
+ * 为单个函数生成 .d.ts 声明行（JSDoc + 单一 widen 主签名）。
+ * 有 hof 关系时优先泛型投影（C3.3）；否则 case-widen。
+ * service 的 generateDts 与 CLI `--dts`（infer/watch）共用本函数，
+ * 两条路径输出保持一致。
+ */
+declare function generateFunctionDtsLines(fn: FunctionAnalysis): string[];
+declare function generateDts(result: AnalysisResult): string;
+
+/**
+ * Abs → 生态 schema 投影（单向有损）。
+ *
+ * 优先走 core `absToConstraint`（与 interface/check 同一投影语义），
+ * 再转成中间层 SchemaNode；投影失败时退回 shape 尽力提取并记 dropped。
+ * Dialect 只负责 Node → 源码字符串；Abs 才是真理源。
+ */
+
+type SchemaDialect = "zod";
+type SchemaRefinement = {
+    kind: "numBound";
+    op: "gt" | "ge" | "lt" | "le";
+    n: number;
+} | {
+    kind: "int";
+} | {
+    kind: "strMin";
+    n: number;
+} | {
+    kind: "strMax";
+    n: number;
+};
+type SchemaNode = {
+    k: "lit";
+    value: string | number | boolean | null | undefined;
+} | {
+    k: "prim";
+    type: "number" | "string" | "boolean" | "bigint" | "symbol";
+    refinements: SchemaRefinement[];
+} | {
+    k: "obj";
+    slots: Array<{
+        key: string;
+        node: SchemaNode;
+        optional?: boolean;
+    }>;
+} | {
+    k: "arr";
+    element: SchemaNode;
+} | {
+    k: "tuple";
+    elements: SchemaNode[];
+} | {
+    k: "union";
+    members: SchemaNode[];
+} | {
+    k: "fn";
+} | {
+    k: "promise";
+    inner: SchemaNode;
+} | {
+    k: "brand";
+    name: string;
+} | {
+    k: "never";
+} | {
+    k: "unknown";
+};
+type SchemaProjection = {
+    source: string;
+    dialect: SchemaDialect;
+    dropped: string[];
+};
+/** NudoConstraint → SchemaNode（与 absToConstraint 投影语义对齐） */
+declare function constraintToSchemaNode(c: NudoConstraint): SchemaNode;
+/** Abs → SchemaNode + dropped（优先 core absToConstraint；失败则 shape 尽力） */
+declare function absToSchemaNode(a: Abs): {
+    node: SchemaNode;
+    dropped: string[];
+};
+declare function schemaNodeToZod(node: SchemaNode): string;
+declare function projectAbsToSchema(a: Abs, opts?: {
+    dialect?: SchemaDialect;
+}): SchemaProjection;
+declare function absToSchemaSource(a: Abs, opts?: {
+    dialect?: SchemaDialect;
+}): string;
+type ZodModuleProjection = {
+    source: string;
+    dialect: SchemaDialect;
+    dropped: string[];
+};
+/**
+ * Abs 导出表 → 可 import 的 zod JS 模块源码。
+ * 形如 `import { z } from "zod"; export const name = z...;`
+ */
+declare function absToZodSchemaModule(exports: Record<string, Abs>, opts?: {
+    banner?: string;
+}): ZodModuleProjection;
+
+/**
+ * Abs / SchemaNode → Standard Schema v1 运行时模块（单向有损投影）。
+ *
+ * 产物是零第三方依赖的 TS/JS 模块：每个导出实现 `~standard` Props
+ * （version=1, vendor="nudo", validate）。validate 对 SchemaNode 做
+ * 结构 + 可表达 refinement 执法；落不了的 pred 不在此假装精确。
+ *
+ * 协议：https://standardschema.dev —— 运行时互操作出口，不替代 nudo check。
+ */
+
+type StandardSchemaIssue = {
+    message: string;
+    path?: ReadonlyArray<PropertyKey>;
+};
+type StandardSchemaResult = {
+    value: unknown;
+    issues?: undefined;
+} | {
+    issues: ReadonlyArray<StandardSchemaIssue>;
+    value?: undefined;
+};
+/** SchemaNode 同步校验（生成模块与测试共用语义）。 */
+declare function validateSchemaNode(node: SchemaNode, value: unknown): StandardSchemaResult;
+type StandardSchemaModuleProjection = {
+    source: string;
+    dropped: string[];
+};
+/**
+ * Abs → Standard Schema v1 模块源码。
+ * `exports`：导出名 → Abs（通常是 output / 各参数）。
+ */
+declare function absToStandardSchemaModule(exports: Record<string, Abs>, opts?: {
+    banner?: string;
+}): StandardSchemaModuleProjection;
+/** 便捷：单个 Abs → 单导出模块（默认导出名 `schema`）。 */
+declare function absToStandardSchema(a: Abs, opts?: {
+    name?: string;
+}): StandardSchemaModuleProjection;
+
+/** Abs 指称守卫（设计 §2.7）：保留 pred */
+declare function generateGuardFunctionFromAbs(name: string, abs: Abs): string;
+/** 兼容别名：Abs 路径唯一 */
+declare function generateGuardFunction(name: string, abs: Abs): string;
+
+/**
+ * Case facts JSON（`nudo test --json` 序列化）。
+ *
+ * - args / result / throws / combined：formatShape 外延投影（有损）
+ *   入口无约束参数展示为 any；unknown 仅表示推导失败
+ * - intension.abs*：无损 Abs 展示（主线）
+ * - argsAbs / resultAbs：CaseResult 上的无损 Abs（formatAbs）；有则补齐
+ */
+
+type CaseJsonCase = {
+    name: string;
+    /** formatShape 外延投影（有损） */
+    args: string[];
+    result: string;
+    throws: string | null;
+    source: string | null;
+    aggregatedFrom?: number;
+    /** 无损参数 Abs 展示（与 args 对齐；缺失位省略） */
+    argsAbs?: string[];
+    /** 无损结果 Abs 展示 */
+    resultAbs?: string;
+    /** 无损内涵（Abs）；无则省略 */
+    intension?: {
+        display?: string;
+        abs?: string;
+        absMultiline?: string;
+        term?: string;
+        pred?: string;
+        conf?: string;
+    };
+};
+type CaseJsonFunction = {
+    name: string;
+    loc: SourceLocation;
+    entryOnly: boolean;
+    noDeclaration?: boolean;
+    cases: CaseJsonCase[];
+    combined?: string;
+    /** 无损 combined Abs 展示 */
+    combinedAbs?: string;
+};
+type CaseJson = {
+    version: 1;
+    file: string;
+    summary: {
+        functions: number;
+        externalFunctions: number;
+        cases: number;
+        diagnostics: number;
+    };
+    functions: CaseJsonFunction[];
+    externalFunctions?: Array<{
+        name: string;
+        fromModule?: string;
+        cases: CaseJsonCase[];
+    }>;
+    diagnostics: Array<{
+        range: SourceLocation;
+        severity: string;
+        message: string;
+        code?: string;
+        suggestions?: string[];
+        tags?: string[];
+        origin?: {
+            line: number;
+            column: number;
+        };
+    }>;
+};
+declare function serializeCaseJson(result: AnalysisResult, file: string): CaseJson;
+
+/** 单个 Abs → parseCaseArgExpr 可解析回去的表达式文本；不可表达返回 null */
+declare function serializeCaseArg(a: Abs): string | null;
+/**
+ * 组装单行 ` * @nudo:case "name" (a, b)` 指令文本（无尾换行）。
+ * 任一实参不可序列化、或名字含双引号/换行（名字正则 `"([^"]+)"` 承载不了）→ 整体 null。
+ */
+declare function buildCaseDirective(name: string, argsAbs: Abs[]): string | null;
+/**
+ * 从源码剥离所有本模块生成的 @nudo:case 指令（名字以 call@ 开头，整行删除）。
+ * 若所属 JSDoc 块因此只剩空 ` *` 行（无其他 @nudo:* 指令、无文字内容），
+ * 连块首 `/**` 行与块尾行整块删除。绝不碰非 case 指令与普通注释。
+ * 注意：手写但以 call@ 命名的 case 同样会被删——call@ 前缀保留为生成物标记。
+ * removed 返回被删指令名列表（按出现顺序）。
+ */
+declare function stripGeneratedCaseDirectives(source: string): {
+    source: string;
+    removed: string[];
+};
+type EmitSkipReason = "hand-written" | "already-generated" | "entry-only" | "no-serializable-cases" | "no-declaration" | "skipped";
+type EmitResult = {
+    source: string;
+    changed: boolean;
+    written: Array<{
+        fn: string;
+        cases: string[];
+    }>;
+    skipped: Array<{
+        fn: string;
+        reason: EmitSkipReason;
+        detail?: string;
+    }>;
+};
+/**
+ * 把 analysis 中的合成 case（source === "callsite"）固化为源码指令：
+ *
+ * 1. 源码已有任何非 call@ 命名的 case → skip "hand-written"；
+ *    已有 call@ case → skip "already-generated"。
+ * 2. fn.skipped / fn.noDeclaration / fn.entryOnly → 对应 skip。
+ * 3. 逐 case 序列化；个别不可序列化的丢弃并在 skipped 记
+ *    no-serializable-cases（函数整体仍写可序列化子集，全不可序列化才整函数跳过）。
+ * 4. 写入位置：函数声明行正上方——已有 JSDoc 块则插到 `/**` 行后，
+ *    无块则新建三行块。缩进取声明行的 loc.start.column（babel 0 基列）。
+ *    多函数编辑按行号从下往上应用，避免行号漂移。
+ */
+declare function insertGeneratedCaseDirectives(source: string, analysis: AnalysisResult): EmitResult;
+/** 行级 unified diff：`--- a/path` 头 + `@@` hunk + 上下文 3 行；相同返回 "" */
+declare function unifiedDiff(a: string, b: string, path: string): string;
+
+export { type CaseJson, type CaseJsonCase, type CaseJsonFunction, type ConstraintSourceExpr, type DerivedExport, type DerivedParam, type DraftEvidence, type EmitDerivedResult, type EmitInterfaceOpts, type EmitInterfaceResult, type EmitInterfaceSkipReason, type EmitResult, type EmitSkipReason, type InterfaceDraftEntry, type InterfaceDraftOpts, type InterfaceDraftResult, type InterfaceSurfaceEntry, type InterfaceSurfaceOpts, type RootDeriveOpts, type RootDeriveResult, type SchemaDialect, type SchemaNode, type SchemaProjection, type SchemaRefinement, type StandardSchemaIssue, type StandardSchemaModuleProjection, type StandardSchemaResult, type WriteDraftResult, type ZodModuleProjection, absToSchemaNode, absToSchemaSource, absToStandardSchema, absToStandardSchemaModule, absToTSType, absToZodSchemaModule, buildCaseDirective, collectParamBodyAccesses, constraintToSchemaNode, deriveFromRoot, draftInterface, emitDerivedFromRoot, emitInterface, extractFnConstraintSources, formatDerivedSection, formatDraftModule, formatDraftSummary, formatEmitSummary, formatInterfaceSurfaceLine, generateDts, generateFunctionDtsLines, generateGuardFunction, generateGuardFunctionFromAbs, insertGeneratedCaseDirectives, interfaceSurface, isDraftableEntry, projectAbsToSchema, schemaNodeToZod, serializeCaseArg, serializeCaseJson, sidecarDraftPath, stripGeneratedCaseDirectives, unifiedDiff, validateSchemaNode, writeInterfaceDraft };