@nudojs/service 0.1.0 → 0.2.1

package/dist/index.js

@@ -1,42 +1,229 @@
 // src/analyzer.ts
-import { readFileSync, existsSync } from "fs";
+import { readFileSync, existsSync, statSync, realpathSync } from "fs";
 import { resolve, dirname } from "path";
 import traverse from "@babel/traverse";
 import {
   T,
   typeValueToString,
   simplifyUnion,
+  widenLiteral,
+  collapseLiteralUnion,
   createEnvironment,
-  isSubtypeOf
+  isSubtypeOf,
+  mockHelperToTypeValue
 } from "@nudojs/core";
-import { parse, extractDirectives, parseTypeValueExpr } from "@nudojs/parser";
+import { parse, extractDirectives, extractFileDirectives, parseTypeValueExpr } from "@nudojs/parser";
 import {
   evaluateFunction,
   evaluateFunctionFull,
+  memberMayExistOn,
+  setUsageSiteTag,
+  USAGE_SITE_MODULE,
   evaluateProgram,
   setModuleResolver,
   setCurrentFileDir,
   resetMemo,
   getUnreachableRanges,
   resetUnreachableRanges,
-  setNodeTypeCollector
+  setNodeTypeCollector,
+  setCallCollector,
+  setUnknownCollector,
+  setProvenanceTracking,
+  setSampleCount,
+  setUnknownBuiltinHandler,
+  setEnvModules,
+  resetEnvModules,
+  setMockModules,
+  resetMockModules,
+  setCurrentSource,
+  loadEnvs,
+  preloadPathEnvs,
+  findProjectConfig,
+  resolveNpmNudo
 } from "@nudojs/cli/evaluator";
 function resolveModule(source, fromDir) {
   const extensions = [".js", ".ts", ".mjs"];
+  const nudoPath = resolveNpmNudo(source, fromDir);
+  if (nudoPath) {
+    const src = readFileSync(nudoPath, "utf-8");
+    return { ast: parse(src), filePath: nudoPath };
+  }
   const basePath = resolve(fromDir, source);
   for (const ext of ["", ...extensions]) {
     const candidate = basePath + ext;
-    if (existsSync(candidate)) {
-      const src = readFileSync(candidate, "utf-8");
-      return { ast: parse(src), filePath: candidate };
+    if (!existsSync(candidate)) continue;
+    if (statSync(candidate).isDirectory()) {
+      let entry = null;
+      const pkgPath = resolve(candidate, "package.json");
+      if (existsSync(pkgPath)) {
+        try {
+          const main = JSON.parse(readFileSync(pkgPath, "utf-8")).main;
+          if (typeof main === "string") {
+            for (const e of ["", ...extensions]) {
+              const p = resolve(candidate, main + e);
+              if (existsSync(p) && statSync(p).isFile()) {
+                entry = p;
+                break;
+              }
+            }
+          }
+        } catch {
+        }
+      }
+      if (!entry) {
+        for (const e of ["", ...extensions]) {
+          const p = resolve(candidate, "index" + e);
+          if (existsSync(p) && statSync(p).isFile()) {
+            entry = p;
+            break;
+          }
+        }
+      }
+      if (!entry) return null;
+      const src2 = readFileSync(entry, "utf-8");
+      return { ast: parse(src2), filePath: entry };
+    }
+    if (candidate.endsWith(".json")) {
+      try {
+        return { ast: parse("module.exports = undefined;"), filePath: candidate, json: JSON.parse(readFileSync(candidate, "utf-8")) };
+      } catch {
+        return null;
+      }
     }
+    const src = readFileSync(candidate, "utf-8");
+    return { ast: parse(src), filePath: candidate };
+  }
+  return null;
+}
+function resolveImportPath(specifier, fromDir) {
+  const basePath = resolve(fromDir, specifier);
+  for (const ext of ["", ".js", ".ts", ".mjs"]) {
+    const candidate = basePath + ext;
+    if (existsSync(candidate)) return candidate;
   }
   return null;
 }
-function applyMocks(directives, env, filePath) {
+function buildModuleGraph(files, cache) {
+  const imports = /* @__PURE__ */ new Map();
+  const dependents = /* @__PURE__ */ new Map();
+  const edge = (from, to) => {
+    if (!imports.has(from)) imports.set(from, /* @__PURE__ */ new Set());
+    if (!dependents.has(to)) dependents.set(to, /* @__PURE__ */ new Set());
+    imports.get(from).add(to);
+    dependents.get(to).add(from);
+  };
+  for (const file of files) {
+    if (!imports.has(file)) imports.set(file, /* @__PURE__ */ new Set());
+    if (!dependents.has(file)) dependents.set(file, /* @__PURE__ */ new Set());
+    let edges;
+    if (cache) {
+      let stat = null;
+      try {
+        stat = statSync(file);
+      } catch {
+      }
+      const cached = stat ? cache.get(file) : void 0;
+      if (stat && cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+        edges = cached.edges;
+      } else {
+        edges = extractImportEdges(file);
+        if (stat) cache.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, edges });
+      }
+    } else {
+      edges = extractImportEdges(file);
+    }
+    for (const to of edges) edge(file, to);
+  }
+  return { imports, dependents };
+}
+function extractImportEdges(file) {
+  const edges = [];
+  let ast;
+  try {
+    ast = parse(readFileSync(file, "utf-8"));
+  } catch {
+    return edges;
+  }
+  for (const stmt of ast.program.body) {
+    if (stmt.type !== "ImportDeclaration") continue;
+    const specifier = stmt.source.value;
+    if (!specifier.startsWith(".") && !specifier.startsWith("/")) continue;
+    const resolved = resolveImportPath(specifier, dirname(file));
+    if (resolved) edges.push(resolved);
+  }
+  return edges;
+}
+function computeDirtySet(dependents, changedFile) {
+  const dirty = [];
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [changedFile];
+  while (queue.length > 0) {
+    const file = queue.shift();
+    if (visited.has(file)) continue;
+    visited.add(file);
+    dirty.push(file);
+    for (const dep of dependents.get(file) ?? []) {
+      if (!visited.has(dep)) queue.push(dep);
+    }
+  }
+  return dirty;
+}
+function topoSortDirty(imports, dirty) {
+  const inSet = new Set(dirty);
+  const pending = /* @__PURE__ */ new Map();
+  for (const file of dirty) {
+    let count = 0;
+    for (const dep of imports.get(file) ?? []) {
+      if (inSet.has(dep)) count++;
+    }
+    pending.set(file, count);
+  }
+  const ordered = [];
+  const ready = dirty.filter((f) => pending.get(f) === 0);
+  while (ready.length > 0) {
+    const file = ready.shift();
+    ordered.push(file);
+    for (const other of dirty) {
+      if (pending.get(other) === void 0) continue;
+      if ((imports.get(other) ?? /* @__PURE__ */ new Set()).has(file)) {
+        const next = pending.get(other) - 1;
+        pending.set(other, next);
+        if (next === 0) ready.push(other);
+      }
+    }
+  }
+  for (const file of dirty) {
+    if (pending.has(file) && pending.get(file) > 0) ordered.push(file);
+  }
+  return ordered;
+}
+function applyMocks(directives, env, filePath, diagnostics) {
   for (const d of directives) {
     if (d.kind !== "mock") continue;
-    if (d.expression) {
+    if (d.arrowFn) {
+      const fnType = T.fn(d.arrowFn.params, d.arrowFn.body, env);
+      fnType._paramPatterns = d.arrowFn.paramPatterns;
+      env.bind(d.name, fnType);
+    } else if (d.nudoMock) {
+      const typeVal = mockHelperToTypeValue(d.nudoMock, env);
+      env.bind(d.name, typeVal);
+    } else if (d.sinonExpr) {
+      const sinonType = createSinonTypeValue(d.sinonExpr, env);
+      env.bind(d.name, sinonType);
+    } else if (d.expression) {
+      const expr = d.expression.trim();
+      if (expr.includes("(") && expr.includes(")") && !expr.startsWith("T.")) {
+        diagnostics.push({
+          range: { start: { line: 0, column: 0 }, end: { line: 0, column: 0 } },
+          severity: "warning",
+          message: `Mock expression "${expr}" could not be parsed as a known pattern`,
+          code: "nudo:mock-invalid",
+          suggestions: [
+            "Supported formats: stub(), stub().returns(value), spy(), mock()",
+            "Arrow functions: (args) => expression or (args) => { statements; return value; }"
+          ]
+        });
+      }
       env.bind(d.name, parseTypeValueExpr(d.expression));
     } else if (d.fromPath) {
       const mockPath = resolve(dirname(filePath), d.fromPath);
@@ -49,13 +236,480 @@ function applyMocks(directives, env, filePath) {
     }
   }
 }
+function createSinonTypeValue(sinonExpr, env) {
+  if (sinonExpr.type === "stub" || sinonExpr.type === "spy") {
+    const body = { type: "BlockStatement", body: [] };
+    const fn = T.fn(["...args"], body, env);
+    if (sinonExpr.returnValue) {
+      fn._directReturn = sinonExpr.returnValue;
+    } else if (sinonExpr.resolvedValue) {
+      fn._directReturn = T.promise(sinonExpr.resolvedValue);
+    } else if (sinonExpr.rejectedValue) {
+      fn._directReturn = T.never;
+    } else {
+      fn._directReturn = T.unknown;
+    }
+    return fn;
+  }
+  return T.unknown;
+}
 function locFromNode(node) {
   return {
     start: { line: node.loc?.start.line ?? 1, column: node.loc?.start.column ?? 0 },
     end: { line: node.loc?.end.line ?? 1, column: node.loc?.end.column ?? 0 }
   };
 }
-function analyzeFile(filePath, source, activeCases) {
+function extractParamNames(node) {
+  const fn = node.type === "ExportDefaultDeclaration" ? node.declaration : node;
+  if (fn.type === "FunctionDeclaration" || fn.type === "FunctionExpression" || fn.type === "ArrowFunctionExpression") {
+    return fn.params.map((p) => {
+      if (p.type === "Identifier") return p.name;
+      if (p.type === "AssignmentPattern" && p.left.type === "Identifier") return p.left.name;
+      if (p.type === "RestElement" && p.argument.type === "Identifier") return `...${p.argument.name}`;
+      return "_";
+    });
+  }
+  if (fn.type === "VariableDeclaration") {
+    const decl = fn.declarations[0];
+    if (decl.init?.type === "FunctionExpression" || decl.init?.type === "ArrowFunctionExpression") {
+      return decl.init.params.map((p) => {
+        if (p.type === "Identifier") return p.name;
+        if (p.type === "AssignmentPattern" && p.left.type === "Identifier") return p.left.name;
+        if (p.type === "RestElement" && p.argument.type === "Identifier") return `...${p.argument.name}`;
+        return "_";
+      });
+    }
+  }
+  return [];
+}
+function resolveFunctionNode(node) {
+  if (node.type === "ExportNamedDeclaration" && node.declaration) return resolveFunctionNode(node.declaration);
+  if (node.type === "ExportDefaultDeclaration") return resolveFunctionNode(node.declaration);
+  if (node.type === "VariableDeclaration") {
+    const init = node.declarations[0]?.init;
+    if (init && (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression")) return init;
+  }
+  return node;
+}
+function isFnExprValue(node) {
+  return !!node && (node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression");
+}
+function namedFnExprId(node) {
+  return node.type === "FunctionExpression" && node.id ? node.id.name : null;
+}
+function isModuleExportsTarget(node) {
+  return node.type === "MemberExpression" && !node.computed && node.object?.type === "Identifier" && node.object.name === "module" && node.property?.type === "Identifier" && node.property.name === "exports";
+}
+function memberPropertyKey(member) {
+  if (member.type !== "MemberExpression" || member.computed) return null;
+  const prop = member.property;
+  if (prop?.type === "Identifier") return prop.name;
+  if (prop?.type === "StringLiteral") return String(prop.value);
+  return null;
+}
+function deepestAssignValue(expr) {
+  let cur = expr;
+  while (cur?.type === "AssignmentExpression") cur = cur.right;
+  return cur ?? null;
+}
+function assignmentChainName(expr) {
+  let cur = expr;
+  while (cur?.type === "AssignmentExpression") {
+    const target = cur.left;
+    if (target.type === "Identifier") return target.name;
+    if (target.type === "MemberExpression") {
+      if (isModuleExportsTarget(target)) {
+        cur = cur.right;
+        continue;
+      }
+      return memberPropertyKey(target);
+    }
+    return null;
+  }
+  return null;
+}
+function collectTopLevelFunctions(ast) {
+  const results = [];
+  if (ast.type !== "File") return results;
+  for (const stmt of ast.program.body) {
+    const decl = resolveFunctionNode(stmt);
+    if (decl.type === "FunctionDeclaration" && decl.id) {
+      results.push({ name: decl.id.name, node: decl, stmt, noDeclaration: false });
+      continue;
+    }
+    if (stmt.type === "VariableDeclaration") {
+      for (const declarator of stmt.declarations) {
+        if (declarator.id?.type === "Identifier" && isFnExprValue(declarator.init)) {
+          results.push({ name: declarator.id.name, node: declarator.init, stmt, noDeclaration: true });
+        }
+      }
+      continue;
+    }
+    if (stmt.type === "ExpressionStatement" && stmt.expression?.type === "AssignmentExpression") {
+      const expr = stmt.expression;
+      const fn = deepestAssignValue(expr);
+      if (isFnExprValue(fn)) {
+        const name = namedFnExprId(fn) ?? assignmentChainName(expr) ?? "default";
+        results.push({ name, node: fn, stmt, noDeclaration: true });
+      }
+    }
+  }
+  return results;
+}
+function findSingleModuleExportsFunction(ast) {
+  if (ast.type !== "File") return null;
+  let found = null;
+  for (const stmt of ast.program.body) {
+    if (stmt.type !== "ExpressionStatement") continue;
+    const expr = stmt.expression;
+    if (expr?.type !== "AssignmentExpression") continue;
+    const fn = deepestAssignValue(expr);
+    if (!isFnExprValue(fn)) continue;
+    let targetsModuleExports = false;
+    let cur = expr;
+    while (cur?.type === "AssignmentExpression") {
+      if (isModuleExportsTarget(cur.left)) {
+        targetsModuleExports = true;
+        break;
+      }
+      cur = cur.right;
+    }
+    if (!targetsModuleExports) continue;
+    if (found) return null;
+    found = fn;
+  }
+  return found;
+}
+function typeStructureKey(tv) {
+  return typeStructureKeyUncached(tv, /* @__PURE__ */ new Set());
+}
+function typeStructureKeyUncached(tv, seen) {
+  const enter = (inner) => {
+    if (inner && typeof inner === "object") {
+      if (seen.has(inner)) return "\xABcycle\xBB";
+      seen.add(inner);
+      const out = typeStructureKeyUncached(inner, seen);
+      seen.delete(inner);
+      return out;
+    }
+    return typeStructureKeyUncached(inner, seen);
+  };
+  switch (tv.kind) {
+    case "literal":
+      return `lit(${typeof tv.value}:${String(tv.value)})`;
+    case "primitive":
+      return `prim(${tv.type})`;
+    case "array":
+      return `arr(${enter(tv.element)})`;
+    case "tuple":
+      return `tup(${tv.elements.map(enter).join(",")})`;
+    case "object":
+      return `obj(${Object.keys(tv.properties).sort().map((k) => `${k}:${enter(tv.properties[k])}`).join(",")})`;
+    case "function":
+      return `fn(${tv.params.join(",")})`;
+    case "promise":
+      return `prom(${enter(tv.value)})`;
+    case "instance":
+      return `inst(${tv.className})`;
+    case "refined":
+      return `ref(${enter(tv.base)})`;
+    case "union":
+      return `uni(${tv.members.map(enter).sort().join("|")})`;
+    default:
+      return tv.kind;
+  }
+}
+var MAX_PRECISE_CALLSITE_CASES = 3;
+var COLLAPSE_LITERAL_THRESHOLD = 4;
+function widenType(tv) {
+  if (tv.kind === "union") return simplifyUnion(tv.members.map(widenLiteral));
+  return widenLiteral(tv);
+}
+function dedupeCallRecords(records) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const rec of records) {
+    if (isOversizedRecord(rec)) continue;
+    const key = rec.argTypes.map(typeStructureKey).join(",") + "=>" + typeStructureKey(rec.resultType) + "!" + typeStructureKey(rec.throws);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(rec);
+  }
+  return out;
+}
+var MAX_RECORD_TYPE_NODES = 2e3;
+function typeNodeCount(tv, seen) {
+  if (tv === null || typeof tv !== "object") return 1;
+  if (seen.has(tv)) return 0;
+  seen.add(tv);
+  switch (tv.kind) {
+    case "array":
+      return 1 + typeNodeCount(tv.element, seen);
+    case "tuple":
+      return 1 + tv.elements.reduce((acc, e) => acc + typeNodeCount(e, seen), 0);
+    case "object": {
+      let n = 1;
+      for (const v of Object.values(tv.properties)) n += typeNodeCount(v, seen);
+      return n;
+    }
+    case "promise":
+      return 1 + typeNodeCount(tv.value, seen);
+    case "union":
+      return 1 + tv.members.reduce((acc, e) => acc + typeNodeCount(e, seen), 0);
+    case "refined":
+      return 1 + typeNodeCount(tv.base, seen);
+    default:
+      return 1;
+  }
+}
+function isOversizedRecord(rec) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const a of rec.argTypes) {
+    if (typeNodeCount(a, seen) > MAX_RECORD_TYPE_NODES) return true;
+  }
+  return typeNodeCount(rec.resultType, seen) > MAX_RECORD_TYPE_NODES;
+}
+function locFromCallLoc(loc) {
+  const p = loc ?? { line: 0, column: 0 };
+  return { start: { line: p.line, column: p.column }, end: { line: p.line, column: p.column } };
+}
+function synthesizeExternalFunctions(records, currentFile) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const rec of records) {
+    if (!rec.targetModule || !rec.targetExport) continue;
+    if (rec.targetModule === currentFile) continue;
+    const key = `${rec.targetModule}\0${rec.targetExport}`;
+    let group = groups.get(key);
+    if (!group) {
+      group = { module: rec.targetModule, exportName: rec.targetExport, records: [] };
+      groups.set(key, group);
+    }
+    group.records.push(rec);
+  }
+  const out = [];
+  for (const { module, exportName, records: records2 } of groups.values()) {
+    const deduped = dedupeCallRecords(records2);
+    const arity = Math.max(...deduped.map((r) => r.argTypes.length));
+    const analysis = {
+      name: exportName,
+      loc: locFromCallLoc(deduped[0].callLoc),
+      paramNames: Array.from({ length: arity }, (_, i) => `arg${i}`),
+      cases: [],
+      fromModule: module
+    };
+    const precise = deduped.slice(0, MAX_PRECISE_CALLSITE_CASES);
+    for (const rec of precise) {
+      analysis.cases.push({
+        name: `call@L${rec.callLoc?.line ?? 0}`,
+        args: rec.argTypes,
+        result: rec.resultType,
+        throws: rec.throws,
+        source: "callsite"
+      });
+    }
+    const remaining = deduped.slice(MAX_PRECISE_CALLSITE_CASES);
+    if (remaining.length > 0) {
+      analysis.cases.push({
+        name: "call@symbolic",
+        args: Array.from(
+          { length: arity },
+          (_, i) => (
+            // 缺参按真实 JS 语义 widen 成 undefined 而非 unknown——可选参守卫
+            // （target || [] 等）对 unknown 全塌，对 undefined 正常走默认分支
+            widenType(simplifyUnion(remaining.map((rec) => rec.argTypes[i] ?? T.undefined)))
+          )
+        ),
+        result: collapseLiteralUnion(simplifyUnion(remaining.map((r) => r.resultType)), COLLAPSE_LITERAL_THRESHOLD),
+        throws: simplifyUnion(remaining.map((r) => r.throws)),
+        source: "callsite",
+        aggregatedFrom: remaining.length
+      });
+    }
+    if (deduped.length > 1) {
+      analysis.combined = collapseLiteralUnion(
+        simplifyUnion(deduped.map((r) => r.resultType)),
+        COLLAPSE_LITERAL_THRESHOLD
+      );
+    } else {
+      analysis.combined = deduped[0].resultType;
+    }
+    out.push(analysis);
+  }
+  return out;
+}
+function receiverTypeToDisplay(tv) {
+  switch (tv.kind) {
+    case "literal": {
+      const v = tv.value;
+      if (v === null) return "null";
+      if (v === void 0) return "undefined";
+      return typeof v;
+    }
+    case "union":
+      return tv.members.map(receiverTypeToDisplay).join(" | ");
+    default:
+      return typeValueToString(tv);
+  }
+}
+function receiverIsConcrete(tv) {
+  if (tv.kind === "unknown") return false;
+  if (tv.kind === "union") return tv.members.every((m) => m.kind !== "unknown");
+  return true;
+}
+function unknownRecordsToDiagnostics(records) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const r of records) {
+    const line = r.loc?.line ?? 0;
+    const column = r.loc?.column ?? 0;
+    const key = `${line}:${column}:${r.name}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const range = {
+      start: { line, column },
+      end: { line, column: column + r.name.length }
+    };
+    if (r.kind === "global") {
+      if (r.name.startsWith("recursion:")) {
+        out.push({
+          range,
+          severity: "warning",
+          message: `Recursive evaluation of '${r.name.slice("recursion:".length)}' was truncated (depth/size budget); result widened to unknown`,
+          code: "nudo:recursion-truncated"
+        });
+        continue;
+      }
+      if (r.name.startsWith("module-cycle:")) {
+        out.push({
+          range,
+          severity: "warning",
+          message: r.reason ?? "Circular module load detected",
+          code: "nudo:module-cycle"
+        });
+        continue;
+      }
+      if (r.name.startsWith("module-depth:")) {
+        out.push({
+          range,
+          severity: "warning",
+          message: r.reason ?? "Module load chain too deep",
+          code: "nudo:module-depth"
+        });
+        continue;
+      }
+      if (r.name.startsWith("module-missing:")) {
+        out.push({
+          range,
+          severity: "error",
+          message: r.reason ?? "Module file not found",
+          code: "nudo:module-missing"
+        });
+        continue;
+      }
+      out.push({
+        range,
+        severity: "warning",
+        message: `Unknown global identifier '${r.name}'`,
+        code: "nudo:unknown-global"
+      });
+      continue;
+    }
+    const receiver = r.receiverType;
+    if (receiver && receiverIsConcrete(receiver)) {
+      const isApprox = (() => {
+        const members = receiver.kind === "union" ? receiver.members : [receiver];
+        return members.some(
+          (m) => m.kind === "instance" || m.kind === "function" || m.kind === "tuple" || m.kind === "array" || m.kind === "object" || m.kind === "refined" || // wrapper/instance 近似表上可能持有该成员（'x'.charCodeAt 于
+          // number|string：string 侧存在，number 侧缺失 → 不确定 → warning）
+          memberMayExistOn(m, r.name)
+        );
+      })();
+      const kindLabel = r.kind === "method" ? "Method" : "Property";
+      out.push({
+        range,
+        severity: isApprox ? "warning" : "error",
+        message: `${kindLabel} '${r.name}' does not exist on type '${receiverTypeToDisplay(receiver)}'`,
+        code: "nudo:no-method",
+        ...r.origin ? { origin: r.origin } : {}
+      });
+    } else {
+      out.push({
+        range,
+        severity: "warning",
+        message: `Cannot resolve '${r.name}' on unknown value`,
+        code: "nudo:unknown-recv",
+        ...r.origin ? { origin: r.origin } : {}
+      });
+    }
+  }
+  return out;
+}
+function collectEnvNames(filePath, source, includeProject) {
+  const ast = parse(source);
+  const fileDirectives = extractFileDirectives(ast);
+  const fileEnvNames = fileDirectives.filter((d) => d.kind === "env").flatMap((d) => d.envs);
+  if (!includeProject) return fileEnvNames;
+  const projectConfig = findProjectConfig(dirname(filePath));
+  const projectEnvNames = projectConfig?.config.env ?? [];
+  return [.../* @__PURE__ */ new Set([...projectEnvNames, ...fileEnvNames])];
+}
+async function analyzeFileAsync(filePath, source, activeCases, externalCallRecords) {
+  const envNames = collectEnvNames(filePath, source, true);
+  if (envNames.length > 0) {
+    await preloadPathEnvs(envNames, dirname(filePath));
+  }
+  return analyzeFile(filePath, source, activeCases, externalCallRecords);
+}
+function collectCallRecords(filePath, source) {
+  const records = [];
+  const ast = parse(source, { errorRecovery: true });
+  resetMemo();
+  resetUnreachableRanges();
+  resetEnvModules();
+  resetMockModules();
+  setModuleResolver(resolveModule);
+  setCurrentFileDir(dirname(filePath));
+  setCurrentSource(source);
+  setCallCollector((record) => records.push(record));
+  try {
+    const env = createEnvironment();
+    evaluateProgram(ast, env);
+    const runCallbacks = (statements) => {
+      for (const stmt of statements) {
+        if (stmt.type !== "ExpressionStatement" || !("expression" in stmt)) continue;
+        const expr = stmt.expression;
+        if (expr.type !== "CallExpression") continue;
+        const callee = expr.callee;
+        if (callee.type !== "MemberExpression" && callee.type !== "Identifier") continue;
+        const name = callee.type === "Identifier" ? callee.name : callee.property.type === "Identifier" ? callee.property.name : null;
+        if (!name || !TEST_CALLBACK_NAMES.has(name)) continue;
+        const args = expr.arguments;
+        const cb = args.find((a) => a.type === "ArrowFunctionExpression" || a.type === "FunctionExpression");
+        if (!cb) continue;
+        try {
+          const params = cb.params ?? [];
+          evaluateFunction(cb, params.map(() => T.unknown), env);
+        } catch {
+        }
+        if (name === "describe" && cb.body.type === "BlockStatement") {
+          runCallbacks(cb.body.body);
+        }
+      }
+    };
+    runCallbacks(ast.program.body);
+  } catch {
+  } finally {
+    setCallCollector(null);
+    setModuleResolver(null);
+    setUnknownBuiltinHandler(null);
+  }
+  return records;
+}
+var TEST_CALLBACK_NAMES = /* @__PURE__ */ new Set(["it", "test", "describe"]);
+function analyzeFile(filePath, source, activeCases, externalCallRecords) {
+  for (const rec of externalCallRecords ?? []) {
+    for (const a of rec.argTypes) setUsageSiteTag(a);
+  }
   const ast = parse(source);
   const functions = extractDirectives(ast);
   const diagnostics = [];
@@ -65,28 +719,77 @@ function analyzeFile(filePath, source, activeCases) {
   const caseHints = [];
   resetMemo();
   resetUnreachableRanges();
+  resetEnvModules();
+  resetMockModules();
   setModuleResolver(resolveModule);
   setCurrentFileDir(dirname(filePath));
+  setCurrentSource(source);
+  const fileDirectives = extractFileDirectives(ast);
+  const fileEnvNames = fileDirectives.filter((d) => d.kind === "env").flatMap((d) => d.envs);
+  const projectConfig = findProjectConfig(dirname(filePath));
+  const projectEnvNames = projectConfig?.config.env ?? [];
+  const envNames = [.../* @__PURE__ */ new Set([...projectEnvNames, ...fileEnvNames])];
+  setUnknownBuiltinHandler((name, loc) => {
+    diagnostics.push({
+      range: loc ? { start: loc.start, end: loc.end } : { start: { line: 0, column: 0 }, end: { line: 0, column: 0 } },
+      severity: "warning",
+      message: `Built-in API "${name}" is not covered by Nudo's type inference`,
+      code: "nudo:builtin-unknown",
+      suggestions: [
+        `Use @nudo:mock to define the type: @nudo:mock ${name} = stub().returns(...)`,
+        `Or use @nudo:returns to declare the expected return type`
+      ]
+    });
+  });
   const globalEnv = createEnvironment();
+  if (envNames.length > 0) {
+    const loaded = loadEnvs(envNames, globalEnv);
+    setEnvModules(loaded.modules);
+  }
+  const mocks = /* @__PURE__ */ new Map();
+  if (projectConfig?.config.mocks) {
+    for (const [source2, mockPath] of Object.entries(projectConfig.config.mocks)) {
+      mocks.set(source2, { fromPath: resolve(projectConfig.projectDir, mockPath) });
+    }
+  }
+  const mockModuleDirectives = fileDirectives.filter((d) => d.kind === "mock-module");
+  for (const d of mockModuleDirectives) {
+    mocks.set(d.source, { fromPath: d.fromPath, names: d.names });
+  }
+  if (mocks.size > 0) {
+    setMockModules(mocks);
+  }
+  const callRecords = [];
+  setCallCollector((record) => callRecords.push(record));
+  const unknownRecords = [];
+  setUnknownCollector((r) => unknownRecords.push(r));
+  setProvenanceTracking(true);
+  for (const fn of functions) {
+    applyMocks(fn.directives, globalEnv, filePath, diagnostics);
+  }
   evaluateProgram(ast, globalEnv);
   const unreachableRanges = getUnreachableRanges();
   for (const ur of unreachableRanges) {
     diagnostics.push({
       range: ur,
       severity: "info",
-      message: "Unreachable code",
-      tags: ["unnecessary"]
+      message: "Code after return/throw statement is unreachable",
+      tags: ["unnecessary"],
+      code: "nudo-unreachable",
+      suggestions: ["Remove the unreachable code after the return/throw statement"]
     });
   }
   collectBindings(ast, globalEnv, bindings);
+  const synthCandidates = [];
   for (const fn of functions) {
-    applyMocks(fn.directives, globalEnv, filePath);
     const isPure = fn.directives.some((d) => d.kind === "pure");
     const skipDirective = fn.directives.find((d) => d.kind === "skip");
     const returnsDirective = fn.directives.find((d) => d.kind === "returns");
     const fnLoc = locFromNode(fn.node);
-    const analysis = { name: fn.name, loc: fnLoc, cases: [] };
+    const paramNames = extractParamNames(fn.node);
+    const analysis = { name: fn.name, loc: fnLoc, paramNames, cases: [] };
     if (skipDirective && skipDirective.kind === "skip") {
+      analysis.skipped = true;
       if (skipDirective.returns) {
         analysis.combined = skipDirective.returns;
       }
@@ -99,8 +802,17 @@ function analyzeFile(filePath, source, activeCases) {
         fnVal._memoize = fn.name;
       }
     }
+    const sampleDirective = fn.directives.find((d) => d.kind === "sample");
+    if (sampleDirective && sampleDirective.kind === "sample") {
+      setSampleCount(sampleDirective.count);
+    } else {
+      setSampleCount(3);
+    }
     const caseDirectives = fn.directives.filter((d) => d.kind === "case");
     const activeCaseIdx = activeCases?.get(fn.name) ?? 0;
+    if (caseDirectives.length === 0) {
+      synthCandidates.push({ name: fn.name, node: fn.node, analysis });
+    }
     for (let ci = 0; ci < caseDirectives.length; ci++) {
       const directive = caseDirectives[ci];
       resetUnreachableRanges();
@@ -126,7 +838,7 @@ function analyzeFile(filePath, source, activeCases) {
             diagnostics.push({
               range: { start: { line: directive.commentLine, column: 0 }, end: { line: directive.commentLine, column: 999 } },
               severity: "error",
-              message: `Case "${directive.name}": expected ${typeValueToString(directive.expected)}, got ${typeValueToString(fullResult.value)}`
+              message: `Case "${directive.name}": expected ${typeValueToString(directive.expected)}, got ${typeValueToString(fullResult.value)}. The inferred return type does not match the expected type declared in the @nudo:case directive`
             });
           }
         }
@@ -139,21 +851,24 @@ function analyzeFile(filePath, source, activeCases) {
           diagnostics.push({
             range: throwRange,
             severity: "warning",
-            message: `Function "${fn.name}" case "${directive.name}" may throw: ${typeValueToString(fullResult.throws)}`
+            message: `Function "${fn.name}" case "${directive.name}" may throw: ${typeValueToString(fullResult.throws)}. Consider adding a try-catch block or using @nudo:returns to declare expected behavior`,
+            code: "nudo-may-throw"
           });
         }
         for (const ur of caseUnreachable) {
           diagnostics.push({
             range: ur,
             severity: "info",
-            message: "Unreachable code",
-            tags: ["unnecessary"]
+            message: "Code after return/throw statement is unreachable",
+            tags: ["unnecessary"],
+            code: "nudo-unreachable",
+            suggestions: ["Remove the unreachable code after the return/throw statement"]
           });
         }
       }
     }
     if (analysis.cases.length > 1) {
-      analysis.combined = simplifyUnion(analysis.cases.map((c) => c.result));
+      analysis.combined = collapseLiteralUnion(simplifyUnion(analysis.cases.map((c) => c.result)), COLLAPSE_LITERAL_THRESHOLD);
     } else if (analysis.cases.length === 1) {
       analysis.combined = analysis.cases[0].result;
     }
@@ -163,26 +878,150 @@ function analyzeFile(filePath, source, activeCases) {
         const result = evaluateFunction(fn.node, directive.args, globalEnv);
         const matches = isSubtypeOf(result, returnsDirective.expected);
         if (!matches) {
-          const msg = `@nudo:returns assertion failed for case "${directive.name}": expected ${typeValueToString(returnsDirective.expected)}, got ${typeValueToString(result)}`;
+          const msg = `@nudo:returns assertion failed for case "${directive.name}": expected ${typeValueToString(returnsDirective.expected)}, got ${typeValueToString(result)}. Update the @nudo:returns directive to match the inferred type, or fix the function implementation`;
           analysis.assertionErrors.push(msg);
           diagnostics.push({
             range: fnLoc,
             severity: "error",
-            message: msg
+            message: msg,
+            code: "nudo-assertion-failed",
+            suggestions: [
+              "Update @nudo:returns to match the inferred type",
+              "Fix the function to return the expected type"
+            ]
           });
         }
       }
     }
     functionResults.push(analysis);
   }
+  const directiveFnNames = new Set(functions.map((f) => f.name));
+  const directiveFnStmts = new Set(functions.map((f) => f.node));
+  for (const { name, node, stmt, noDeclaration } of collectTopLevelFunctions(ast)) {
+    if (directiveFnNames.has(name)) continue;
+    if (directiveFnStmts.has(stmt)) continue;
+    const analysis = { name, loc: locFromNode(node), paramNames: extractParamNames(node), cases: [] };
+    if (noDeclaration) analysis.noDeclaration = true;
+    functionResults.push(analysis);
+    synthCandidates.push({ name, node, analysis });
+  }
+  const modulePathCache = /* @__PURE__ */ new Map();
+  const normalizeModulePath = (p) => {
+    let n = modulePathCache.get(p);
+    if (n === void 0) {
+      try {
+        n = realpathSync(p);
+      } catch {
+        n = p;
+      }
+      modulePathCache.set(p, n);
+    }
+    return n;
+  };
+  const currentModulePath = normalizeModulePath(resolve(filePath));
+  const singleExportFn = findSingleModuleExportsFunction(ast);
+  for (const candidate of synthCandidates) {
+    const singleExportHit = singleExportFn !== null && candidate.node === singleExportFn;
+    const nameRoutes = (r) => r.fnName === candidate.name || r.targetExport === candidate.name || (r.targetAliases?.includes(candidate.name) ?? false) || singleExportHit && (r.fnModule !== void 0 || r.targetModule !== void 0);
+    const matchingLocal = (r) => {
+      const targetsThisFile = r.targetModule === void 0 || normalizeModulePath(r.targetModule) === currentModulePath;
+      if (!targetsThisFile) return false;
+      return nameRoutes(r);
+    };
+    const matchingExternal = (r) => {
+      const attributed = r.fnModule !== void 0 && normalizeModulePath(r.fnModule) === currentModulePath || r.targetModule !== void 0 && normalizeModulePath(r.targetModule) === currentModulePath;
+      if (!attributed) return false;
+      return nameRoutes(r);
+    };
+    const records = dedupeCallRecords(
+      [
+        ...callRecords.filter(matchingLocal),
+        ...(externalCallRecords ?? []).filter(matchingExternal)
+      ].filter((r) => !(r.resultType.kind === "never" && r.throws.kind === "never"))
+    );
+    if (records.length > 0) {
+      const informativeness = (r) => {
+        if (r.resultType.kind === "unknown") return 2;
+        if (r.resultType.kind === "never") return 1;
+        return 0;
+      };
+      const ordered = records.map((r, i) => ({ r, i })).sort((a, b) => informativeness(a.r) - informativeness(b.r) || a.i - b.i).map(({ r }) => r);
+      const precise = ordered.slice(0, MAX_PRECISE_CALLSITE_CASES);
+      for (const rec of precise) {
+        candidate.analysis.cases.push({
+          name: `call@L${rec.callLoc?.line ?? candidate.analysis.loc.start.line}`,
+          args: rec.argTypes,
+          result: rec.resultType,
+          throws: rec.throws,
+          source: "callsite"
+        });
+      }
+      const remaining = ordered.slice(MAX_PRECISE_CALLSITE_CASES).filter((rec) => !rec.argTypes.some((a) => a.kind === "unknown"));
+      if (remaining.length > 0) {
+        const fnNode2 = resolveFunctionNode(candidate.node);
+        const paramCount = extractParamNames(fnNode2).length;
+        const widenedArgs = Array.from(
+          { length: paramCount },
+          (_, i) => (
+            // 缺参按真实 JS 语义 widen 成 undefined 而非 unknown——可选参守卫
+            // （target || [] 等）对 unknown 全塌，对 undefined 正常走默认分支
+            widenType(simplifyUnion(remaining.map((rec) => rec.argTypes[i] ?? T.undefined)))
+          )
+        );
+        const full2 = evaluateFunctionFull(fnNode2, widenedArgs, globalEnv);
+        candidate.analysis.cases.push({
+          name: "call@symbolic",
+          args: widenedArgs,
+          result: full2.value,
+          throws: full2.throws,
+          throwLoc: full2.throwLoc,
+          source: "callsite",
+          aggregatedFrom: remaining.length
+        });
+      }
+      candidate.analysis.combined = collapseLiteralUnion(
+        simplifyUnion(records.map((r) => r.resultType)),
+        COLLAPSE_LITERAL_THRESHOLD
+      );
+      continue;
+    }
+    const fnNode = resolveFunctionNode(candidate.node);
+    const args = extractParamNames(fnNode).map(() => T.unknown);
+    const full = evaluateFunctionFull(fnNode, args, globalEnv);
+    candidate.analysis.cases.push({
+      name: `entry@L${candidate.analysis.loc.start.line}`,
+      args,
+      result: full.value,
+      throws: full.throws,
+      throwLoc: full.throwLoc
+    });
+    candidate.analysis.entryOnly = true;
+    candidate.analysis.combined = collapseLiteralUnion(full.value, COLLAPSE_LITERAL_THRESHOLD);
+  }
   buildNodeTypeMap(ast, globalEnv, nodeTypeMap);
+  setUnknownBuiltinHandler(null);
+  setCallCollector(null);
+  setUnknownCollector(null);
+  setProvenanceTracking(false);
   setModuleResolver(null);
+  resetEnvModules();
+  resetMockModules();
+  const maxLine = source.split("\n").length;
+  diagnostics.push(
+    ...unknownRecordsToDiagnostics(
+      unknownRecords.filter(
+        (r) => (r.loc?.line ?? 0) <= maxLine && r.originModule !== USAGE_SITE_MODULE
+      )
+    )
+  );
+  const externalFunctions = synthesizeExternalFunctions(callRecords, filePath);
   return {
     functions: functionResults,
     diagnostics,
     bindings,
     nodeTypeMap,
-    caseHints
+    caseHints,
+    ...externalFunctions.length > 0 ? { externalFunctions } : {}
   };
 }
 function collectBindings(ast, env, bindings) {
@@ -248,12 +1087,27 @@ function getCasesForFile(filePath, source) {
     return { functionName: fn.name, cases, loc: locFromNode(fn.node) };
   });
 }
+async function getTypeAtPositionAsync(filePath, source, line, column, activeCases) {
+  const envNames = collectEnvNames(filePath, source, false);
+  if (envNames.length > 0) {
+    await preloadPathEnvs(envNames, dirname(filePath));
+  }
+  return getTypeAtPosition(filePath, source, line, column, activeCases);
+}
 function getTypeAtPosition(filePath, source, line, column, activeCases) {
   const ast = parse(source);
   resetMemo();
+  resetEnvModules();
   setModuleResolver(resolveModule);
   setCurrentFileDir(dirname(filePath));
+  setCurrentSource(source);
+  const fileDirectives = extractFileDirectives(ast);
+  const envNames = fileDirectives.filter((d) => d.kind === "env").flatMap((d) => d.envs);
   const globalEnv = createEnvironment();
+  if (envNames.length > 0) {
+    const loaded = loadEnvs(envNames, globalEnv);
+    setEnvModules(loaded.modules);
+  }
   evaluateProgram(ast, globalEnv);
   const nodeTypeMap = /* @__PURE__ */ new Map();
   buildNodeTypeMap(ast, globalEnv, nodeTypeMap);
@@ -274,6 +1128,8 @@ function getTypeAtPosition(filePath, source, line, column, activeCases) {
     }
   }
   setModuleResolver(null);
+  resetEnvModules();
+  resetMockModules();
   return findBestTypeAtPosition(nodeTypeMap, globalEnv, ast, line, column);
 }
 function findEnclosingFunction(functions, line) {
@@ -446,6 +1302,7 @@ function getCompletionsForType(tv) {
 }
 
 // src/dts-generator.ts
+import { T as T2, isTemplate, getTemplateParts, simplifyUnion as simplifyUnion2, typeValueEquals } from "@nudojs/core";
 function typeValueToTSType(tv) {
   switch (tv.kind) {
     case "literal": {
@@ -458,6 +1315,14 @@ function typeValueToTSType(tv) {
     }
     case "primitive":
       return tv.type;
+    case "refined": {
+      if (isTemplate(tv)) {
+        const parts = getTemplateParts(tv);
+        const inner = parts.map((p) => p.kind === "literal" && typeof p.value === "string" ? p.value : `\${${typeValueToTSType(p)}}`).join("");
+        return `\`${inner}\``;
+      }
+      return typeValueToTSType(tv.base);
+    }
     case "object": {
       const entries = Object.entries(tv.properties);
       if (entries.length === 0) return "{}";
@@ -471,8 +1336,10 @@ function typeValueToTSType(tv) {
       return `[${inner}]`;
     }
     case "function": {
-      const params = tv.params.map((p, i) => `${p}: unknown`).join(", ");
-      return `(${params}) => unknown`;
+      const params = tv.params.map((p) => `${p}: unknown`).join(", ");
+      const returnType = tv._returnType;
+      const retStr = returnType ? typeValueToTSType(returnType) : "unknown";
+      return `(${params}) => ${retStr}`;
     }
     case "promise":
       return `Promise<${typeValueToTSType(tv.value)}>`;
@@ -491,33 +1358,608 @@ function wrapComplexType(tv) {
   if (tv.kind === "union") return `(${ts})`;
   return ts;
 }
+function getParamName(fn, index) {
+  if (fn.paramNames && fn.paramNames[index]) {
+    return fn.paramNames[index];
+  }
+  return `arg${index}`;
+}
+function widenLiteralToBase(tv) {
+  if (tv.kind !== "literal") return tv;
+  const v = tv.value;
+  if (typeof v === "number") return T2.number;
+  if (typeof v === "string") return T2.string;
+  if (typeof v === "boolean") return T2.boolean;
+  if (typeof v === "bigint") return T2.bigint;
+  return tv;
+}
+function widenTopLevel(tv) {
+  if (tv.kind !== "union") return widenLiteralToBase(tv);
+  return simplifyUnion2(tv.members.map(widenLiteralToBase));
+}
+function widenProperties(properties) {
+  const out = {};
+  for (const [k, v] of Object.entries(properties)) out[k] = widenParamType(v);
+  return out;
+}
+function widenParamType(tv) {
+  switch (tv.kind) {
+    case "literal":
+      return widenLiteralToBase(tv);
+    case "union":
+      return simplifyUnion2(tv.members.map(widenParamType));
+    case "tuple": {
+      const widened = tv.elements.map(widenParamType);
+      const first = widened[0];
+      if (first && widened.every((el) => typeValueEquals(el, first))) {
+        return T2.array(first);
+      }
+      return T2.tuple(widened);
+    }
+    case "array":
+      return T2.array(widenParamType(tv.element));
+    case "object":
+      return T2.object(widenProperties(tv.properties));
+    case "promise":
+      return T2.promise(widenParamType(tv.value));
+    case "instance":
+      return T2.instanceOf(tv.className, widenProperties(tv.properties));
+    case "refined":
+      return widenParamType(tv.base);
+    default:
+      return tv;
+  }
+}
+function widenedUnion(members) {
+  const flat = [];
+  const collect = (tv) => {
+    if (tv.kind === "union") {
+      tv.members.forEach(collect);
+      return;
+    }
+    flat.push(tv);
+  };
+  members.forEach(collect);
+  const widened = flat.map(widenParamType);
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = widened.filter((tv) => {
+    const key = typeValueToTSType(tv);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  return simplifyUnion2(deduped);
+}
+function computeMainSignature(fn) {
+  const arity = Math.max(...fn.cases.map((c) => c.args.length));
+  const minArity = Math.min(...fn.cases.map((c) => c.args.length));
+  const params = [];
+  const paramNames = [];
+  const paramTypes = [];
+  const usedNames = /* @__PURE__ */ new Set();
+  for (let i = 0; i < arity; i++) {
+    const members = fn.cases.filter((c) => i < c.args.length).map((c) => c.args[i]);
+    const typeStr = typeValueToTSType(widenedUnion(members));
+    let name = getParamName(fn, i);
+    if (usedNames.has(name)) {
+      let n = 2;
+      while (usedNames.has(`${name}${n}`)) n++;
+      name = `${name}${n}`;
+    }
+    usedNames.add(name);
+    const optional = i >= minArity && !name.startsWith("...");
+    params.push(optional ? `${name}?: ${typeStr}` : `${name}: ${typeStr}`);
+    paramNames.push(name);
+    paramTypes.push(typeStr);
+  }
+  const combined = fn.combined ?? simplifyUnion2(fn.cases.map((c) => c.result));
+  const returnType = typeValueToTSType(widenTopLevel(combined));
+  return { params, paramNames, paramTypes, returnType };
+}
+function generateJSDoc(fn, sig) {
+  if (fn.cases.length === 0) return "";
+  const lines = ["/**"];
+  for (const c of fn.cases) {
+    const preciseDiffers = c.args.length !== sig.paramTypes.length || c.args.some((a, i) => typeValueToTSType(a) !== sig.paramTypes[i]) || typeValueToTSType(c.result) !== sig.returnType;
+    if (!preciseDiffers) continue;
+    const argsStr = c.args.map(typeValueToTSType).join(", ");
+    lines.push(` * Case: ${c.name} (${argsStr}) => ${typeValueToTSType(c.result)}`);
+  }
+  for (let i = 0; i < sig.paramTypes.length; i++) {
+    lines.push(` * @param ${sig.paramNames[i]} - ${sig.paramTypes[i]}`);
+  }
+  lines.push(` * @returns ${sig.returnType}`);
+  lines.push(" */");
+  return lines.join("\n");
+}
+function generateFunctionDtsLines(fn) {
+  if (fn.noDeclaration) return [];
+  if (fn.cases.length === 0) {
+    if (fn.combined) {
+      return [
+        `export declare function ${fn.name}(...args: unknown[]): ${typeValueToTSType(fn.combined)};`
+      ];
+    }
+    return [];
+  }
+  const sig = computeMainSignature(fn);
+  const jsdoc = generateJSDoc(fn, sig);
+  const lines = [];
+  if (jsdoc) lines.push(jsdoc);
+  lines.push(`export declare function ${fn.name}(${sig.params.join(", ")}): ${sig.returnType};`);
+  return lines;
+}
 function generateDts(result) {
   const lines = [];
   for (const fn of result.functions) {
-    if (fn.cases.length === 0 && fn.combined) {
-      lines.push(`export declare function ${fn.name}(...args: unknown[]): ${typeValueToTSType(fn.combined)};`);
+    lines.push(...generateFunctionDtsLines(fn));
+  }
+  return lines.join("\n") + "\n";
+}
+
+// src/schema-generator.ts
+function typeValueToZodSchema(tv) {
+  switch (tv.kind) {
+    case "literal": {
+      if (tv.value === null) return "z.null()";
+      if (tv.value === void 0) return "z.undefined()";
+      if (typeof tv.value === "string") return `z.literal(${JSON.stringify(tv.value)})`;
+      if (typeof tv.value === "boolean") return `z.literal(${tv.value})`;
+      return `z.literal(${tv.value})`;
+    }
+    case "primitive":
+      return `z.${tv.type}()`;
+    case "refined":
+      return typeValueToZodSchema(tv.base);
+    case "object": {
+      const entries = Object.entries(tv.properties).map(([k, v]) => `${k}: ${typeValueToZodSchema(v)}`).join(", ");
+      return `z.object({ ${entries} })`;
+    }
+    case "array":
+      return `z.array(${typeValueToZodSchema(tv.element)})`;
+    case "tuple": {
+      const inner = tv.elements.map(typeValueToZodSchema).join(", ");
+      return `z.tuple([${inner}])`;
+    }
+    case "function":
+      return "z.function()";
+    case "promise":
+      return `z.promise(${typeValueToZodSchema(tv.value)})`;
+    case "instance":
+      return `z.instanceof(${tv.className})`;
+    case "union": {
+      const members = tv.members.map(typeValueToZodSchema).join(", ");
+      return `z.union([${members}])`;
+    }
+    case "never":
+      return "z.never()";
+    case "unknown":
+      return "z.unknown()";
+  }
+}
+
+// src/guard-generator.ts
+function generateGuardFunction(name, tv) {
+  const body = generateGuardBody(tv, "data");
+  return `export function ${name}(data) {
+  return ${body};
+}`;
+}
+function generateGuardBody(tv, varName) {
+  switch (tv.kind) {
+    case "literal": {
+      if (tv.value === null) return `${varName} === null`;
+      if (tv.value === void 0) return `${varName} === undefined`;
+      return `${varName} === ${JSON.stringify(tv.value)}`;
+    }
+    case "primitive":
+      return `typeof ${varName} === '${tv.type}'`;
+    case "refined":
+      return generateGuardBody(tv.base, varName);
+    case "object": {
+      const checks = [`typeof ${varName} === 'object'`, `${varName} !== null`];
+      for (const [key, val] of Object.entries(tv.properties)) {
+        checks.push(generateGuardBody(val, `${varName}.${key}`));
+      }
+      return checks.join(" && ");
+    }
+    case "array":
+      return `Array.isArray(${varName}) && ${varName}.every(item => ${generateGuardBody(tv.element, "item")})`;
+    case "tuple": {
+      const checks = [`Array.isArray(${varName})`, `${varName}.length === ${tv.elements.length}`];
+      tv.elements.forEach((el, i) => {
+        checks.push(generateGuardBody(el, `${varName}[${i}]`));
+      });
+      return checks.join(" && ");
+    }
+    case "union": {
+      const members = tv.members.map((m) => generateGuardBody(m, varName));
+      return `(${members.join(" || ")})`;
+    }
+    case "never":
+      return "false";
+    case "unknown":
+      return "true";
+    case "function":
+      return `typeof ${varName} === 'function'`;
+    case "promise":
+      return `${varName} instanceof Promise`;
+    case "instance":
+      return `${varName} instanceof ${tv.className}`;
+  }
+}
+
+// src/case-emitter.ts
+import { parse as parse2, extractDirectives as extractDirectives2 } from "@nudojs/parser";
+var GENERATED_PREFIX = "call@";
+var GENERATED_CASE_LINE_REGEX = /^\s*\*?\s*@nudo:case\s+"(call@[^"]*)"/;
+var IDENT_KEY_REGEX = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+var NUMBER_LITERAL_REGEX = /^-?\d+(\.\d+)?$/;
+var UNSAFE_STRING_CHARS = /[,()[\]{}]/;
+var UNSAFE_KEY_CHARS = /[,()[\]{}:]/;
+var CONTROL_CHARS = /[\x00-\x1f\x7f]/;
+function serializeStringLiteral(value) {
+  if (CONTROL_CHARS.test(value)) return null;
+  if (value.includes("*/")) return null;
+  if (UNSAFE_STRING_CHARS.test(value)) return null;
+  const hasDbl = value.includes('"');
+  const hasSgl = value.includes("'");
+  if (hasDbl && hasSgl) return null;
+  return hasDbl ? `'${value}'` : `"${value}"`;
+}
+function serializeObjectKey(key) {
+  if (IDENT_KEY_REGEX.test(key)) return key;
+  if (CONTROL_CHARS.test(key)) return null;
+  if (key.includes('"')) return null;
+  if (UNSAFE_KEY_CHARS.test(key) || key.includes("*/")) return null;
+  if (/^['"]|['"]$/.test(key)) return null;
+  return `"${key}"`;
+}
+function serializeCaseArg(tv) {
+  switch (tv.kind) {
+    case "primitive":
+      if (tv.type === "number" || tv.type === "string" || tv.type === "boolean") {
+        return `T.${tv.type}`;
+      }
+      return null;
+    case "unknown":
+      return "T.unknown";
+    case "never":
+      return "T.never";
+    case "literal": {
+      const v = tv.value;
+      if (typeof v === "number") {
+        if (!Number.isFinite(v)) return null;
+        const s = String(v);
+        return NUMBER_LITERAL_REGEX.test(s) ? s : null;
+      }
+      if (typeof v === "boolean") return v ? "true" : "false";
+      if (v === null) return "null";
+      if (v === void 0) return "undefined";
+      return serializeStringLiteral(v);
+    }
+    case "union": {
+      const parts = [];
+      for (const member of tv.members) {
+        const s = serializeCaseArg(member);
+        if (s === null) return null;
+        parts.push(s);
+      }
+      return `T.union(${parts.join(", ")})`;
+    }
+    case "array": {
+      const el = serializeCaseArg(tv.element);
+      return el === null ? null : `T.array(${el})`;
+    }
+    case "tuple": {
+      const parts = [];
+      for (const el of tv.elements) {
+        const s = serializeCaseArg(el);
+        if (s === null) return null;
+        parts.push(s);
+      }
+      return `[${parts.join(", ")}]`;
+    }
+    case "object": {
+      const parts = [];
+      for (const [key, value] of Object.entries(tv.properties)) {
+        const vs = serializeCaseArg(value);
+        if (vs === null) return null;
+        const ks = serializeObjectKey(key);
+        if (ks === null) return null;
+        parts.push(`${ks}: ${vs}`);
+      }
+      return parts.length === 0 ? "{}" : `{ ${parts.join(", ")} }`;
+    }
+    default:
+      return null;
+  }
+}
+function buildCaseDirective(name, args) {
+  if (name.includes('"') || /[\r\n]/.test(name)) return null;
+  const parts = [];
+  for (const arg of args) {
+    const s = serializeCaseArg(arg);
+    if (s === null) return null;
+    parts.push(s);
+  }
+  return ` * @nudo:case "${name}" (${parts.join(", ")})`;
+}
+function stripGeneratedCaseDirectives(source) {
+  const lines = source.split("\n");
+  const removed = [];
+  const drop = new Array(lines.length).fill(false);
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(GENERATED_CASE_LINE_REGEX);
+    if (m) {
+      drop[i] = true;
+      removed.push(m[1]);
+    }
+  }
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^\s*\/\*\*\s*$/.test(lines[i])) continue;
+    let j = i + 1;
+    let clean = true;
+    while (j < lines.length) {
+      if (/\*\//.test(lines[j])) break;
+      if (/\/\*/.test(lines[j])) {
+        clean = false;
+        break;
+      }
+      j++;
+    }
+    if (!clean || j >= lines.length) continue;
+    if (!/^\s*\*\/\s*$/.test(lines[j])) continue;
+    let onlyFiller = true;
+    for (let k = i + 1; k < j; k++) {
+      if (drop[k]) continue;
+      const t = lines[k].trim();
+      if (t !== "" && !/^\*{1,2}$/.test(t)) {
+        onlyFiller = false;
+        break;
+      }
+    }
+    if (onlyFiller) {
+      for (let k = i; k <= j; k++) drop[k] = true;
+    }
+  }
+  return {
+    source: lines.filter((_, i) => !drop[i]).join("\n"),
+    removed
+  };
+}
+function collectExistingCases(source) {
+  const byName = /* @__PURE__ */ new Map();
+  let ast;
+  try {
+    ast = parse2(source, { errorRecovery: true });
+  } catch {
+    return byName;
+  }
+  for (const { name, directives } of extractDirectives2(ast)) {
+    for (const d of directives) {
+      if (d.kind !== "case") continue;
+      const list = byName.get(name);
+      if (list) list.push(d);
+      else byName.set(name, [d]);
+    }
+  }
+  return byName;
+}
+function insertGeneratedCaseDirectives(source, analysis) {
+  const written = [];
+  const skipped = [];
+  const existing = collectExistingCases(source);
+  const edits = [];
+  for (const fn of analysis.functions) {
+    const existingCases = existing.get(fn.name) ?? [];
+    if (existingCases.some((c) => !c.name.startsWith(GENERATED_PREFIX))) {
+      skipped.push({ fn: fn.name, reason: "hand-written" });
       continue;
     }
-    if (fn.cases.length === 1) {
-      const c = fn.cases[0];
-      const params = c.args.map((a, i) => `arg${i}: ${typeValueToTSType(a)}`).join(", ");
-      const ret = typeValueToTSType(c.result);
-      lines.push(`export declare function ${fn.name}(${params}): ${ret};`);
+    if (existingCases.length > 0) {
+      skipped.push({ fn: fn.name, reason: "already-generated" });
       continue;
     }
-    for (const c of fn.cases) {
-      const params = c.args.map((a, i) => `arg${i}: ${typeValueToTSType(a)}`).join(", ");
-      const ret = typeValueToTSType(c.result);
-      lines.push(`export declare function ${fn.name}(${params}): ${ret};`);
+    if (fn.skipped) {
+      skipped.push({ fn: fn.name, reason: "skipped" });
+      continue;
+    }
+    if (fn.noDeclaration) {
+      skipped.push({ fn: fn.name, reason: "no-declaration" });
+      continue;
     }
+    if (fn.entryOnly) {
+      skipped.push({ fn: fn.name, reason: "entry-only" });
+      continue;
+    }
+    const callsiteCases = fn.cases.filter((c) => c.source === "callsite");
+    if (callsiteCases.length === 0) {
+      skipped.push({ fn: fn.name, reason: "no-serializable-cases", detail: "no callsite cases" });
+      continue;
+    }
+    const built = [];
+    const names = [];
+    for (const c of callsiteCases) {
+      const directive = buildCaseDirective(c.name, c.args);
+      if (directive === null) {
+        skipped.push({ fn: fn.name, reason: "no-serializable-cases", detail: `case ${c.name} not serializable` });
+      } else {
+        built.push(directive);
+        names.push(c.name);
+      }
+    }
+    if (built.length === 0) continue;
+    edits.push({ line: fn.loc.start.line, column: fn.loc.start.column, directives: built, fn: fn.name });
+    written.push({ fn: fn.name, cases: names });
   }
-  return lines.join("\n") + "\n";
+  edits.sort((a, b) => b.line - a.line);
+  const lines = source.split("\n");
+  for (const edit of edits) {
+    const declIdx = edit.line - 1;
+    const indent = " ".repeat(edit.column);
+    let insertIdx = -1;
+    let blockIndent = "";
+    const aboveIdx = declIdx - 1;
+    if (aboveIdx >= 0 && /^\s*\*\/\s*$/.test(lines[aboveIdx])) {
+      let s = aboveIdx - 1;
+      while (s >= 0) {
+        const t = lines[s];
+        if (/^\s*\/\*\*/.test(t)) {
+          insertIdx = s + 1;
+          blockIndent = t.match(/^\s*/)?.[0] ?? "";
+          break;
+        }
+        if (/^\s*\*/.test(t) || t.trim() === "") {
+          s--;
+          continue;
+        }
+        break;
+      }
+    }
+    if (insertIdx >= 0) {
+      lines.splice(insertIdx, 0, ...edit.directives.map((d) => blockIndent + d));
+    } else {
+      lines.splice(declIdx, 0, `${indent}/**`, ...edit.directives.map((d) => indent + d), `${indent} */`);
+    }
+  }
+  return {
+    source: lines.join("\n"),
+    changed: written.length > 0,
+    written,
+    skipped
+  };
+}
+function diffOps(a, b) {
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start++;
+  let endA = a.length;
+  let endB = b.length;
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+    endA--;
+    endB--;
+  }
+  const midA = a.slice(start, endA);
+  const midB = b.slice(start, endB);
+  const n = midA.length;
+  const m = midB.length;
+  const dp = new Int32Array((n + 1) * (m + 1));
+  for (let i2 = n - 1; i2 >= 0; i2--) {
+    for (let j2 = m - 1; j2 >= 0; j2--) {
+      dp[i2 * (m + 1) + j2] = midA[i2] === midB[j2] ? dp[(i2 + 1) * (m + 1) + (j2 + 1)] + 1 : Math.max(dp[(i2 + 1) * (m + 1) + j2], dp[i2 * (m + 1) + (j2 + 1)]);
+    }
+  }
+  const ops = [];
+  for (let k = 0; k < start; k++) ops.push({ type: "equal", text: a[k] });
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (midA[i] === midB[j]) {
+      ops.push({ type: "equal", text: midA[i] });
+      i++;
+      j++;
+    } else if (dp[(i + 1) * (m + 1) + j] >= dp[i * (m + 1) + (j + 1)]) {
+      ops.push({ type: "delete", text: midA[i] });
+      i++;
+    } else {
+      ops.push({ type: "insert", text: midB[j] });
+      j++;
+    }
+  }
+  while (i < n) ops.push({ type: "delete", text: midA[i++] });
+  while (j < m) ops.push({ type: "insert", text: midB[j++] });
+  for (let k = endA; k < a.length; k++) ops.push({ type: "equal", text: a[k] });
+  return ops;
+}
+var DIFF_CONTEXT = 3;
+function formatRange(start, count) {
+  const s = count === 0 ? start - 1 : start;
+  return count === 1 ? `${s}` : `${s},${count}`;
+}
+function unifiedDiff(a, b, path) {
+  if (a === b) return "";
+  const ops = diffOps(a.split("\n"), b.split("\n"));
+  const hunks = [];
+  let idx = 0;
+  while (idx < ops.length) {
+    if (ops[idx].type === "equal") {
+      idx++;
+      continue;
+    }
+    let start = idx;
+    let ctx = 0;
+    while (start > 0 && ops[start - 1].type === "equal" && ctx < DIFF_CONTEXT) {
+      start--;
+      ctx++;
+    }
+    let j = idx;
+    let equalRun = 0;
+    let lastChange = idx;
+    while (j < ops.length) {
+      if (ops[j].type === "equal") {
+        equalRun++;
+        if (equalRun > DIFF_CONTEXT * 2) break;
+      } else {
+        equalRun = 0;
+        lastChange = j;
+      }
+      j++;
+    }
+    let end = lastChange + 1;
+    ctx = 0;
+    while (end < ops.length && ops[end].type === "equal" && ctx < DIFF_CONTEXT) {
+      end++;
+      ctx++;
+    }
+    hunks.push({ start, ops: ops.slice(start, end) });
+    idx = end;
+  }
+  const out = [`--- a/${path}`, `+++ b/${path}`];
+  for (let h = 0; h < hunks.length; h++) {
+    const { start, ops: hunkOps } = hunks[h];
+    let oldCount = 0;
+    let newCount = 0;
+    for (let k = 0; k < start; k++) {
+      if (ops[k].type !== "insert") oldCount++;
+      if (ops[k].type !== "delete") newCount++;
+    }
+    let dels = 0;
+    let ins = 0;
+    for (const op of hunkOps) {
+      if (op.type === "delete") dels++;
+      else if (op.type === "insert") ins++;
+      else {
+        dels++;
+        ins++;
+      }
+    }
+    out.push(`@@ -${formatRange(oldCount + 1, dels)} +${formatRange(newCount + 1, ins)} @@`);
+    for (const op of hunkOps) {
+      const prefix = op.type === "equal" ? " " : op.type === "delete" ? "-" : "+";
+      out.push(prefix + op.text);
+    }
+  }
+  return out.join("\n") + "\n";
 }
 export {
   analyzeFile,
+  analyzeFileAsync,
+  buildCaseDirective,
+  buildModuleGraph,
+  collectCallRecords,
+  computeDirtySet,
   generateDts,
+  generateFunctionDtsLines,
+  generateGuardFunction,
   getCasesForFile,
   getCompletionsAtPosition,
   getTypeAtPosition,
-  typeValueToTSType
+  getTypeAtPositionAsync,
+  insertGeneratedCaseDirectives,
+  serializeCaseArg,
+  stripGeneratedCaseDirectives,
+  topoSortDirty,
+  typeValueToTSType,
+  typeValueToZodSchema,
+  unifiedDiff
 };