@nudojs/cli 0.2.0 → 0.2.1

package/dist/index.js

@@ -2,13 +2,13 @@ import {
   __commonJS,
   __require,
   __toESM,
-  evaluateFunction,
   evaluateFunctionFull,
   evaluateProgram,
   resetMemo,
+  resolveNpmNudo,
   setCurrentFileDir,
   setModuleResolver
-} from "./chunk-LGWVGEMB.js";
+} from "./chunk-3HCPXPEW.js";
 
 // ../../node_modules/.pnpm/commander@13.1.0/node_modules/commander/lib/error.js
 var require_error = __commonJS({
@@ -3312,7 +3312,7 @@ var require_commander = __commonJS({
 
 // src/index.ts
 import { readFileSync, existsSync, watch, readdirSync, statSync, writeFileSync } from "fs";
-import { resolve, dirname, relative, join } from "path";
+import { resolve, dirname, relative, join, basename } from "path";
 
 // ../../node_modules/.pnpm/commander@13.1.0/node_modules/commander/esm.mjs
 var import_index = __toESM(require_commander(), 1);
@@ -3333,20 +3333,42 @@ var {
 
 // src/index.ts
 import {
+  T,
   typeValueToString,
-  simplifyUnion,
   createEnvironment,
-  isSubtypeOf,
-  isTemplate,
-  getTemplateParts
+  mockHelperToTypeValue
 } from "@nudojs/core";
 import { parse, extractDirectives, parseTypeValueExpr } from "@nudojs/parser";
+import {
+  typeValueToZodSchema,
+  generateGuardFunction,
+  generateFunctionDtsLines,
+  analyzeFileAsync,
+  buildModuleGraph,
+  computeDirtySet,
+  topoSortDirty,
+  collectCallRecords,
+  stripGeneratedCaseDirectives,
+  insertGeneratedCaseDirectives,
+  unifiedDiff
+} from "@nudojs/service";
+import { harvestDts, emitEnvModule } from "@nudojs/harvester";
 var program2 = new Command();
 program2.name("nudo").description("Nudo type inference engine").version("0.0.1");
 function applyMocks(directives, env, filePath) {
   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.bind(d.name, sinonType);
+    } else if (d.expression) {
       env.bind(d.name, parseTypeValueExpr(d.expression));
     } else if (d.fromPath) {
       const mockPath = resolve(dirname(filePath), d.fromPath);
@@ -3359,156 +3381,152 @@ function applyMocks(directives, env, filePath) {
     }
   }
 }
+function createSinonTypeValue(sinonExpr) {
+  const body = { type: "BlockStatement", body: [] };
+  const fn = T.fn(["...args"], body, createEnvironment());
+  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;
+}
 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)) {
+      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 typeValueToTSType(tv) {
-  switch (tv.kind) {
-    case "literal": {
-      const v = tv.value;
-      if (v === null) return "null";
-      if (v === void 0) return "undefined";
-      if (typeof v === "string") return JSON.stringify(v);
-      return String(v);
-    }
-    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 "{}";
-      const inner = entries.map(([k, v]) => `${k}: ${typeValueToTSType(v)}`).join("; ");
-      return `{ ${inner} }`;
+async function reemitUpdate(filePath, source, callsites) {
+  const stripped = stripGeneratedCaseDirectives(source);
+  const result = await analyzeFileAsync(filePath, stripped.source, void 0, callsites);
+  const emitOut = insertGeneratedCaseDirectives(stripped.source, result);
+  return { result, emitOut, removed: stripped.removed };
+}
+function collectExternalRecords(sites) {
+  const records = [];
+  for (const site of sites) {
+    const sitePath = resolve(site);
+    if (!existsSync(sitePath)) {
+      console.error(`Callsite file not found: ${sitePath}`);
+      process.exitCode = 1;
+      continue;
     }
-    case "array": {
-      const el = typeValueToTSType(tv.element);
-      return tv.element.kind === "union" ? `(${el})[]` : `${el}[]`;
+    const siteFiles = statSync(sitePath).isDirectory() ? collectNudoFiles(sitePath) : [sitePath];
+    for (const sf of siteFiles) {
+      records.push(...collectCallRecords(sf, readFileSync(sf, "utf-8")));
     }
-    case "tuple":
-      return `[${tv.elements.map(typeValueToTSType).join(", ")}]`;
-    case "function":
-      return `(${tv.params.map((p) => `${p}: unknown`).join(", ")}) => unknown`;
-    case "promise":
-      return `Promise<${typeValueToTSType(tv.value)}>`;
-    case "instance":
-      return tv.className;
-    case "union":
-      return tv.members.map(typeValueToTSType).join(" | ");
-    case "never":
-      return "never";
-    case "unknown":
-      return "unknown";
   }
+  return records.length > 0 ? records : void 0;
 }
-function runInfer(file, options = {}) {
+async function runInfer(file, options = {}) {
   const filePath = resolve(file);
   const source = readFileSync(filePath, "utf-8");
-  const ast = parse(source);
-  const functions = extractDirectives(ast);
-  if (functions.length === 0) {
+  let result = await analyzeFileAsync(filePath, source, void 0, options.callsites);
+  let emitOut;
+  if (options.emit) {
+    if (options.emit.mode === "update") {
+      const re = await reemitUpdate(filePath, source, options.callsites);
+      result = re.result;
+      emitOut = re.emitOut;
+    } else {
+      emitOut = insertGeneratedCaseDirectives(source, result);
+    }
+  }
+  if (result.functions.length === 0 && !result.externalFunctions?.length) {
     console.log("No functions with @nudo:case directives found.");
     return;
   }
-  resetMemo();
-  setModuleResolver(resolveModule);
-  setCurrentFileDir(dirname(filePath));
-  const globalEnv = createEnvironment();
-  evaluateProgram(ast, globalEnv);
   const dtsLines = [];
-  for (const fn of functions) {
-    const loc = fn.node.loc;
-    const locStr = loc ? `${relative(process.cwd(), filePath)}:${loc.start.line}:${loc.start.column}` : relative(process.cwd(), filePath);
+  for (const fn of result.functions) {
+    const loc = fn.loc;
+    const locStr = `${relative(process.cwd(), filePath)}:${loc.start.line}:${loc.start.column}`;
     const header = options.showLoc ? `=== ${fn.name} (${locStr}) ===` : `=== ${fn.name} ===`;
     console.log(`${header}
 `);
-    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");
-    if (skipDirective && skipDirective.kind === "skip") {
-      if (skipDirective.returns) {
-        console.log(`Skipped (declared): ${typeValueToString(skipDirective.returns)}`);
-        if (options.dts) {
-          dtsLines.push(`export declare function ${fn.name}(...args: unknown[]): ${typeValueToTSType(skipDirective.returns)};`);
-        }
+    if (options.dts) {
+      dtsLines.push(...generateFunctionDtsLines(fn));
+    }
+    if (fn.skipped) {
+      if (fn.combined) {
+        console.log(`Skipped (declared): ${typeValueToString(fn.combined)}`);
       } else {
         console.log("Skipped (no return type declared)");
       }
       console.log();
       continue;
     }
-    if (isPure) {
-      const fnVal = globalEnv.has(fn.name) ? globalEnv.lookup(fn.name) : null;
-      if (fnVal && fnVal.kind === "function") {
-        fnVal._memoize = fn.name;
-      }
-    }
-    const caseDirectives = fn.directives.filter((d) => d.kind === "case");
-    const caseResults = [];
-    for (const directive of caseDirectives) {
-      const fullResult = evaluateFunctionFull(fn.node, directive.args, globalEnv);
-      const argsStr = directive.args.map(typeValueToString).join(", ");
-      const resultStr = typeValueToString(fullResult.value);
-      const throwsStr = fullResult.throws.kind !== "never" ? typeValueToString(fullResult.throws) : void 0;
-      caseResults.push({
-        name: directive.name,
-        args: directive.args,
-        argsStr,
-        result: resultStr,
-        resultTV: fullResult.value,
-        throws: throwsStr
-      });
-      let line = `Case "${directive.name}": (${argsStr}) => ${resultStr}`;
-      if (throwsStr) line += ` throws ${throwsStr}`;
+    for (const c of fn.cases) {
+      const argsStr = c.args.map(typeValueToString).join(", ");
+      let line = `Case "${c.name}": (${argsStr}) => ${typeValueToString(c.result)}`;
+      if (c.throws.kind !== "never") line += ` throws ${typeValueToString(c.throws)}`;
       console.log(line);
     }
-    if (caseResults.length > 1) {
-      const allResults = caseDirectives.map(
-        (d) => evaluateFunctionFull(fn.node, d.args, globalEnv)
-      );
-      const combined = simplifyUnion(allResults.map((r) => r.value));
+    if (fn.entryOnly) {
+      console.log("# no call sites found; parameters default to unknown");
+    }
+    if (fn.cases.length > 1 && fn.combined) {
       console.log(`
-Combined: ${typeValueToString(combined)}`);
+Combined: ${typeValueToString(fn.combined)}`);
     }
-    if (returnsDirective && returnsDirective.kind === "returns") {
-      for (const directive of caseDirectives) {
-        const result = evaluateFunction(fn.node, directive.args, globalEnv);
-        const matches = isSubtypeOf(result, returnsDirective.expected);
-        if (!matches) {
-          console.log(`
-\u26A0 @nudo:returns assertion failed for case "${directive.name}": expected ${typeValueToString(returnsDirective.expected)}, got ${typeValueToString(result)}`);
-        }
+    if (fn.assertionErrors && fn.assertionErrors.length > 0) {
+      for (const err of fn.assertionErrors) {
+        console.log(`
+\u26A0 ${err}`);
       }
     }
-    if (options.dts) {
-      if (caseResults.length === 1) {
-        const c = caseResults[0];
-        const params = c.args.map((a, i) => `arg${i}: ${typeValueToTSType(a)}`).join(", ");
-        dtsLines.push(`export declare function ${fn.name}(${params}): ${typeValueToTSType(c.resultTV)};`);
-      } else {
-        for (const c of caseResults) {
-          const params = c.args.map((a, i) => `arg${i}: ${typeValueToTSType(a)}`).join(", ");
-          dtsLines.push(`export declare function ${fn.name}(${params}): ${typeValueToTSType(c.resultTV)};`);
+    console.log();
+  }
+  if (result.externalFunctions && result.externalFunctions.length > 0) {
+    const byModule = /* @__PURE__ */ new Map();
+    for (const fn of result.externalFunctions) {
+      const mod = fn.fromModule ?? "";
+      const list = byModule.get(mod);
+      if (list) list.push(fn);
+      else byModule.set(mod, [fn]);
+    }
+    for (const [mod, fns] of byModule) {
+      const rel = relative(process.cwd(), mod) || mod;
+      console.log(`--- ${rel} (imported) ---
+`);
+      for (const fn of fns) {
+        console.log(`=== ${fn.name} ===
+`);
+        for (const c of fn.cases) {
+          const argsStr = c.args.map(typeValueToString).join(", ");
+          let line = `Case "${c.name}": (${argsStr}) => ${typeValueToString(c.result)}`;
+          if (c.throws.kind !== "never") line += ` throws ${typeValueToString(c.throws)}`;
+          console.log(line);
+        }
+        if (fn.cases.length > 1 && fn.combined) {
+          console.log(`
+Combined: ${typeValueToString(fn.combined)}`);
         }
+        console.log();
       }
     }
-    console.log();
   }
   if (options.dts && dtsLines.length > 0) {
     const dtsPath = filePath.replace(/\.js$/, ".d.ts");
@@ -3516,10 +3534,246 @@ Combined: ${typeValueToString(combined)}`);
     writeFileSync(dtsPath, dtsContent, "utf-8");
     console.log(`Generated: ${relative(process.cwd(), dtsPath)}`);
   }
-  setModuleResolver(null);
+  if (result.diagnostics.length > 0) {
+    console.log("Diagnostics:\n");
+    for (const d of result.diagnostics) {
+      const loc = `${relative(process.cwd(), filePath)}:${d.range.start.line}:${d.range.start.column}`;
+      console.log(`  [${d.severity}] ${loc} ${d.message}${d.code ? ` (${d.code})` : ""}`);
+      if (d.origin) {
+        console.log(`    \u2192 value originates at ${d.origin.line}:${d.origin.column}`);
+      }
+    }
+    console.log();
+  }
+  if (options.emit && emitOut) {
+    const relPath = relative(process.cwd(), filePath) || filePath;
+    const skippedLines = emitOut.skipped.map((s) => `  ${s.fn}: ${s.reason}${s.detail ? ` (${s.detail})` : ""}`);
+    if (emitOut.source === source) {
+      console.log("No changes.");
+      for (const line of skippedLines) console.log(line);
+      return;
+    }
+    if (options.emit.dryRun) {
+      console.log(`Would emit cases \u2192 ${relPath} (dry run)`);
+      for (const w of emitOut.written) console.log(`  ${w.fn}: ${w.cases.join(", ")}`);
+      for (const line of skippedLines) console.log(line);
+      console.log();
+      process.stdout.write(unifiedDiff(source, emitOut.source, relPath));
+      if (options.emit.exitOnDiff) process.exitCode = 1;
+      return;
+    }
+    writeFileSync(filePath, emitOut.source, "utf-8");
+    const directiveCount = emitOut.written.reduce((n, w) => n + w.cases.length, 0);
+    console.log(
+      `Emitted cases \u2192 ${relPath} (${directiveCount} directive(s) across ${emitOut.written.length} function(s))`
+    );
+    for (const w of emitOut.written) console.log(`  ${w.fn}: ${w.cases.join(", ")}`);
+    for (const line of skippedLines) console.log(line);
+  }
+}
+async function runInferJson(file, externalRecords) {
+  const filePath = resolve(file);
+  const source = readFileSync(filePath, "utf-8");
+  const result = await analyzeFileAsync(filePath, source, void 0, externalRecords);
+  const jsonOutput = {
+    functions: result.functions.map((f) => ({
+      name: f.name,
+      loc: f.loc,
+      cases: f.cases.map((c) => ({
+        name: c.name,
+        args: c.args.map(typeValueToString),
+        result: typeValueToString(c.result),
+        throws: c.throws.kind !== "never" ? typeValueToString(c.throws) : null,
+        source: c.source ?? null
+      })),
+      entryOnly: f.entryOnly ?? false,
+      assertionErrors: f.assertionErrors
+    })),
+    externalFunctions: result.externalFunctions?.map((f) => ({
+      name: f.name,
+      fromModule: f.fromModule,
+      cases: f.cases.map((c) => ({
+        name: c.name,
+        args: c.args.map(typeValueToString),
+        result: typeValueToString(c.result),
+        throws: c.throws.kind !== "never" ? typeValueToString(c.throws) : null,
+        source: c.source ?? null
+      }))
+    })),
+    diagnostics: result.diagnostics.map((d) => ({
+      range: d.range,
+      severity: d.severity,
+      message: d.message,
+      code: d.code,
+      suggestions: d.suggestions,
+      tags: d.tags,
+      origin: d.origin
+    }))
+  };
+  console.log(JSON.stringify(jsonOutput, null, 2));
+}
+program2.command("infer").description("Infer types from a JS file \u2014 functions with @nudo:case directives use them; all other functions are inferred from call sites (whole-program analysis)").argument("<file>", "Path to the JS file").option("--dts", "Generate .d.ts file").option("--loc", "Show source locations in output").option("--json", "Output as JSON").option("--callsites <paths...>", "Usage-site files (tests/apps) to harvest real call shapes from; their calls to this file's exports become synthesized cases").option("--emit-cases [mode]", "Write synthesized call-site cases back into the source as @nudo:case directives (call@ prefix); mode: update (default: add)").option("--dry-run", "With --emit-cases: print a unified diff instead of writing to disk").option("--exit-on-diff", "With --dry-run: exit with code 1 when the diff is non-empty").action(
+  async (file, opts) => {
+    let emit;
+    if (opts.emitCases !== void 0) {
+      let mode;
+      if (opts.emitCases === true) mode = "add";
+      else if (opts.emitCases === "update") mode = "update";
+      else {
+        console.error(`Invalid --emit-cases value: ${opts.emitCases} (expected: =update, or omit the value for add)`);
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.json) {
+        console.error("--emit-cases cannot be combined with --json");
+        process.exitCode = 1;
+        return;
+      }
+      emit = { mode, dryRun: opts.dryRun === true, exitOnDiff: opts.exitOnDiff === true };
+    }
+    if (opts.exitOnDiff && !opts.dryRun) {
+      console.error("--exit-on-diff requires --dry-run");
+      process.exitCode = 1;
+      return;
+    }
+    let externalRecords;
+    if (opts.callsites?.length) {
+      externalRecords = collectExternalRecords(opts.callsites);
+    }
+    if (opts.json) {
+      await runInferJson(file, externalRecords);
+    } else {
+      await runInfer(file, { dts: opts.dts, showLoc: opts.loc, callsites: externalRecords, emit });
+    }
+  }
+);
+async function runCheck(file) {
+  const filePath = resolve(file);
+  const source = readFileSync(filePath, "utf-8");
+  const result = await analyzeFileAsync(filePath, source);
+  if (result.diagnostics.length === 0) {
+    console.log("No issues found.");
+    return;
+  }
+  for (const d of result.diagnostics) {
+    const loc = `${relative(process.cwd(), filePath)}:${d.range.start.line}:${d.range.start.column}`;
+    console.log(`[${d.severity}] ${loc} ${d.message}${d.code ? ` (${d.code})` : ""}`);
+    if (d.origin) {
+      console.log(`    \u2192 value originates at ${d.origin.line}:${d.origin.column}`);
+    }
+  }
+  if (result.diagnostics.some((d) => d.severity === "error")) {
+    process.exitCode = 1;
+  }
 }
-program2.command("infer").description("Infer types from a JS file with @nudo: directives").argument("<file>", "Path to the JS file").option("--dts", "Generate .d.ts file").option("--loc", "Show source locations in output").action((file, opts) => {
-  runInfer(file, { dts: opts.dts, showLoc: opts.loc });
+program2.command("check").description("Check a JS file for type errors \u2014 exits with code 1 when errors are found").argument("<file>", "Path to the JS file").action(async (file) => {
+  await runCheck(file);
+});
+var displayPath = (p) => {
+  const rel = relative(process.cwd(), p);
+  return rel === "" || rel.startsWith("..") ? p : rel;
+};
+async function doctorFile(filePath, records) {
+  const report = { file: displayPath(filePath), functions: 0, entryOnly: 0, uncovered: [] };
+  let source;
+  try {
+    source = readFileSync(filePath, "utf-8");
+  } catch (err) {
+    report.error = err.message;
+    return report;
+  }
+  try {
+    const result = await analyzeFileAsync(filePath, source, void 0, records);
+    report.functions = result.functions.length;
+    report.entryOnly = result.functions.filter((fn) => fn.entryOnly).length;
+    report.uncovered = result.functions.filter((fn) => fn.cases.length === 0 && !fn.skipped && !fn.entryOnly).map((fn) => fn.name);
+    if (records) {
+      const { emitOut, removed } = await reemitUpdate(filePath, source, records);
+      if (emitOut.source !== source) {
+        report.drift = {
+          added: emitOut.written.reduce((n, w) => n + w.cases.length, 0),
+          removed: removed.length
+        };
+      }
+    }
+  } catch (err) {
+    report.error = err.message;
+  }
+  return report;
+}
+async function runDoctor(paths, opts) {
+  const targetPaths = paths.length > 0 ? paths : ["."];
+  const externalRecords = opts.callsites?.length ? collectExternalRecords(opts.callsites) : void 0;
+  const files = [];
+  const reports = [];
+  for (const p of targetPaths) {
+    const abs = resolve(p);
+    if (!existsSync(abs)) {
+      reports.push({ file: displayPath(abs), functions: 0, entryOnly: 0, uncovered: [], error: `File not found: ${abs}` });
+      continue;
+    }
+    files.push(...statSync(abs).isDirectory() ? collectNudoFiles(abs) : [abs]);
+  }
+  for (const filePath of files) {
+    reports.push(await doctorFile(filePath, externalRecords));
+  }
+  const driftCount = reports.filter((r) => r.drift).length;
+  const errorCount = reports.filter((r) => r.error).length;
+  const uncoveredTotal = reports.reduce((n, r) => n + r.uncovered.length, 0);
+  const failed = driftCount > 0 || errorCount > 0;
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          // ok 与退出码一致：drift/报错 → false；uncovered 仅为信息级不影响
+          ok: !failed,
+          files: reports.map((r) => ({
+            file: r.file,
+            functions: r.functions,
+            entryOnly: r.entryOnly,
+            uncovered: r.uncovered,
+            ...r.drift ? { drift: r.drift } : {},
+            ...r.error ? { error: r.error } : {}
+          })),
+          summary: { files: reports.length, drift: driftCount, errors: errorCount, uncovered: uncoveredTotal }
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    if (reports.length === 0) {
+      console.log("No files to check.");
+      return;
+    }
+    for (const r of reports) {
+      console.log(`${r.file}`);
+      if (r.error) {
+        console.log(`  \u2717 error: ${r.error}`);
+        continue;
+      }
+      const entryInfo = r.entryOnly > 0 ? `, ${r.entryOnly} entry-only` : "";
+      console.log(`  \xB7 ${r.functions} function(s)${entryInfo}`);
+      if (r.uncovered.length > 0) {
+        console.log(`  \u26A0 uncovered (no cases): ${r.uncovered.join(", ")}`);
+      }
+      if (r.drift) {
+        const refresh = `nudo infer ${r.file} --callsites ${(opts.callsites ?? []).join(" ")} --emit-cases=update`;
+        console.log(
+          `  \u2717 drift: ${r.drift.added + r.drift.removed} directive(s) changed (+${r.drift.added} new, -${r.drift.removed} removed) \u2014 refresh with: ${refresh.trim()}`
+        );
+      }
+    }
+    console.log(
+      `
+Summary: ${reports.length} file(s) \xB7 ${driftCount} drift \xB7 ${errorCount} error(s) \xB7 ${uncoveredTotal} uncovered function(s)`
+    );
+    console.log(failed ? "Result: FAIL (drift or errors found)" : "Result: OK (uncovered function(s) are informational only)");
+  }
+  if (failed) process.exitCode = 1;
+}
+program2.command("doctor").description("Health-check JS files: functions without cases, call-site solidification drift (--callsites), analysis errors \u2014 exits 1 on drift/errors").argument("[paths...]", "File(s) or directory(s) to check (default: current directory)").option("--callsites <paths...>", "Usage-site files (tests/apps): re-solidify per current call shapes and report drift when directives would change").option("--json", "Output as JSON").action(async (paths, opts) => {
+  await runDoctor(paths, opts);
 });
 program2.command("watch").description("Watch file(s) for changes and re-run inference").argument("<path>", "File or directory to watch").option("--dts", "Generate .d.ts files on each change").action((watchPath, opts) => {
   const resolved = resolve(watchPath);
@@ -3528,28 +3782,66 @@ program2.command("watch").description("Watch file(s) for changes and re-run infe
     if (!isDir) return [resolved];
     return collectNudoFiles(resolved);
   };
-  const runAll = () => {
+  let graph = buildModuleGraph(getFiles());
+  const runAll = async () => {
     console.clear();
     console.log(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString()}] Analyzing...
 `);
     for (const f of getFiles()) {
       try {
-        runInfer(f, { dts: opts.dts, showLoc: true });
+        await runInfer(f, { dts: opts.dts, showLoc: true });
+      } catch (err) {
+        console.error(`Error analyzing ${relative(process.cwd(), f)}:`, err.message);
+      }
+    }
+    graph = buildModuleGraph(getFiles());
+    console.log(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString()}] Watching for changes...`);
+  };
+  const runIncremental = async (changedFiles) => {
+    const files = getFiles();
+    const tracked = new Set(files);
+    const dirtyUnion = /* @__PURE__ */ new Set();
+    for (const cf of changedFiles) {
+      for (const d of computeDirtySet(graph.dependents, cf)) dirtyUnion.add(d);
+    }
+    const dirty = [...dirtyUnion].filter((f) => tracked.has(f));
+    if (dirty.length === 0) return;
+    const ordered = topoSortDirty(graph.imports, dirty);
+    console.clear();
+    console.log(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString()}] Analyzing (incremental)...
+`);
+    const t0 = performance.now();
+    resetMemo();
+    for (const f of ordered) {
+      try {
+        await runInfer(f, { dts: opts.dts, showLoc: true });
       } catch (err) {
         console.error(`Error analyzing ${relative(process.cwd(), f)}:`, err.message);
       }
     }
+    const elapsed = Math.round(performance.now() - t0);
+    console.log(`Incremental: re-analyzed ${ordered.length}, skipped ${files.length - ordered.length} (${elapsed}ms)`);
     console.log(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString()}] Watching for changes...`);
+    graph = buildModuleGraph(getFiles());
   };
-  runAll();
+  runAll().catch(() => {
+  });
   let debounceTimer = null;
   const watchTarget = isDir ? resolved : dirname(resolved);
+  const pendingChanged = /* @__PURE__ */ new Set();
   watch(watchTarget, { recursive: isDir }, (_event, filename) => {
     if (!filename) return;
     const fullPath = isDir ? join(watchTarget, filename) : resolved;
     if (!fullPath.endsWith(".js")) return;
+    if (!existsSync(fullPath)) return;
+    pendingChanged.add(fullPath);
     if (debounceTimer) clearTimeout(debounceTimer);
-    debounceTimer = setTimeout(runAll, 200);
+    debounceTimer = setTimeout(() => {
+      const changedFiles = [...pendingChanged];
+      pendingChanged.clear();
+      runIncremental(changedFiles).catch(() => {
+      });
+    }, 200);
   });
 });
 function collectNudoFiles(dir) {
@@ -3559,12 +3851,185 @@ function collectNudoFiles(dir) {
     if (entry.isDirectory() && entry.name !== "node_modules") {
       results.push(...collectNudoFiles(fullPath));
     } else if (entry.isFile() && entry.name.endsWith(".js")) {
-      const content = readFileSync(fullPath, "utf-8");
-      if (/@nudo:(case|mock|pure|skip|sample|returns)\b/.test(content)) {
-        results.push(fullPath);
-      }
+      results.push(fullPath);
     }
   }
   return results;
 }
-program2.parse();
+function nodeLoc(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 fnParamNames(node) {
+  const fn = node.type === "ExportDefaultDeclaration" ? node.declaration : node;
+  const paramListOf = (params) => 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 === "FunctionDeclaration" || fn.type === "FunctionExpression" || fn.type === "ArrowFunctionExpression") {
+    return paramListOf(fn.params);
+  }
+  if (fn.type === "VariableDeclaration") {
+    const init = fn.declarations[0].init;
+    if (init?.type === "FunctionExpression" || init?.type === "ArrowFunctionExpression") {
+      return paramListOf(init.params);
+    }
+  }
+  return [];
+}
+program2.command("generate").description("Generate runtime validators from inferred types").argument("<file>", "JavaScript file to analyze").option("--format <format>", "Output format: zod, guard, dts, all", "all").option("--output <dir>", "Output directory", ".").action((file, options) => {
+  const filePath = resolve(file);
+  const source = readFileSync(filePath, "utf-8");
+  const ast = parse(source);
+  const functions = extractDirectives(ast);
+  if (functions.length === 0) {
+    console.log("No functions with @nudo:case directives found.");
+    return;
+  }
+  resetMemo();
+  setModuleResolver(resolveModule);
+  setCurrentFileDir(dirname(filePath));
+  const globalEnv = createEnvironment();
+  evaluateProgram(ast, globalEnv);
+  for (const fn of functions) {
+    applyMocks(fn.directives, globalEnv, filePath);
+    const caseDirectives = fn.directives.filter((d) => d.kind === "case");
+    if (caseDirectives.length === 0) continue;
+    const caseResults = caseDirectives.map((directive) => {
+      const fullResult = evaluateFunctionFull(fn.node, directive.args, globalEnv);
+      return {
+        name: directive.name,
+        args: directive.args,
+        result: fullResult.value,
+        throws: fullResult.throws,
+        source: "directive"
+      };
+    });
+    const baseName = fn.name;
+    if (options.format === "zod" || options.format === "all") {
+      console.log(`
+// === ${baseName} Zod Schemas ===`);
+      for (const c of caseResults) {
+        const inputSchemas = c.args.map((a, i) => `arg${i}: ${typeValueToZodSchema(a)}`).join(", ");
+        const outputSchema = typeValueToZodSchema(c.result);
+        console.log(`// Case "${c.name}":`);
+        console.log(`// Input: { ${inputSchemas} }`);
+        console.log(`// Output: ${outputSchema}`);
+      }
+    }
+    if (options.format === "guard" || options.format === "all") {
+      console.log(`
+// === ${baseName} Type Guards ===`);
+      for (const c of caseResults) {
+        const guard = generateGuardFunction(`is${baseName}${c.name.charAt(0).toUpperCase() + c.name.slice(1)}Output`, c.result);
+        console.log(guard);
+      }
+    }
+    if (options.format === "dts" || options.format === "all") {
+      console.log(`
+// === ${baseName} TypeScript Declarations ===`);
+      const analysis = {
+        name: baseName,
+        loc: nodeLoc(fn.node),
+        paramNames: fnParamNames(fn.node),
+        cases: caseResults
+      };
+      for (const line of generateFunctionDtsLines(analysis)) {
+        console.log(line);
+      }
+    }
+  }
+  setModuleResolver(null);
+});
+var HARVEST_MAX_FILES = 200;
+var REFERENCE_PATH_REGEX = /<reference\s+path=["']([^"']+)["']\s*\/>/g;
+var RELATIVE_FROM_REGEX = /\bfrom\s+["'](\.[^"']+)["']/g;
+function collectDtsFiles(entry) {
+  const files = [];
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [entry];
+  while (queue.length > 0 && files.length < HARVEST_MAX_FILES) {
+    const current = queue.shift();
+    if (seen.has(current) || !existsSync(current)) continue;
+    seen.add(current);
+    if (!current.endsWith(".d.ts")) continue;
+    files.push(current);
+    let text;
+    try {
+      text = readFileSync(current, "utf-8");
+    } catch {
+      continue;
+    }
+    const dir = dirname(current);
+    for (const match of text.matchAll(REFERENCE_PATH_REGEX)) {
+      queue.push(resolve(dir, match[1]));
+    }
+    for (const match of text.matchAll(RELATIVE_FROM_REGEX)) {
+      const base = resolve(dir, match[1]);
+      for (const candidate of [`${base}.d.ts`, join(base, "index.d.ts")]) {
+        if (existsSync(candidate)) {
+          queue.push(candidate);
+          break;
+        }
+      }
+    }
+  }
+  return files;
+}
+function runHarvest(pkg, outOpt) {
+  const typesDir = resolve(process.cwd(), "node_modules", "@types", pkg);
+  if (!existsSync(typesDir)) {
+    console.error(`Error: ${relative(process.cwd(), typesDir)} not found.`);
+    console.error(`Install the package first, e.g. pnpm add -D @types/${pkg}`);
+    process.exitCode = 1;
+    return;
+  }
+  let entry = join(typesDir, "index.d.ts");
+  const pkgJsonPath = join(typesDir, "package.json");
+  if (existsSync(pkgJsonPath)) {
+    try {
+      const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+      const declared = pkgJson.types ?? pkgJson.typings;
+      if (typeof declared === "string") {
+        const candidate = resolve(typesDir, declared);
+        if (existsSync(candidate)) entry = candidate;
+      }
+    } catch {
+    }
+  }
+  if (!existsSync(entry)) {
+    console.error(`Error: no .d.ts entry found in ${relative(process.cwd(), typesDir)} (tried ${basename(entry)}).`);
+    process.exitCode = 1;
+    return;
+  }
+  const files = collectDtsFiles(entry);
+  if (files.length === 0) {
+    console.error(`Error: no .d.ts files collected from ${relative(process.cwd(), entry)}.`);
+    process.exitCode = 1;
+    return;
+  }
+  const env = harvestDts(files);
+  const code = emitEnvModule(env, `@types/${pkg}`);
+  const out = resolve(outOpt ?? `nudo-harvest-${pkg}.ts`);
+  writeFileSync(out, code, "utf-8");
+  console.log(`Harvested @types/${pkg} \u2192 ${relative(process.cwd(), out) || out}`);
+  console.log(`  files:    ${env.stats.files}`);
+  console.log(`  symbols:  ${env.stats.symbols}`);
+  console.log(`  skipped:  ${env.stats.skipped}`);
+  console.log(`
+Usage \u2014 add this directive at the top of your JS file:`);
+  const outDir = dirname(out);
+  const hintPath = resolve(process.cwd()) === outDir ? basename(out) : out;
+  console.log(`  /// @nudo:env ${hintPath}`);
+}
+program2.command("harvest").description("Convert @types/<pkg> .d.ts declarations into a Nudo env file (TS source using T.* constructors)").argument("<pkg>", "Package name under @types (e.g. node)").option("--out <file>", "Output .ts env file (default: ./nudo-harvest-<pkg>.ts)").action((pkg, opts) => {
+  runHarvest(pkg, opts.out);
+});
+program2.parseAsync(process.argv).catch((err) => {
+  console.error(err instanceof Error ? process.env.NUDO_DEBUG ? err.stack : err.message : err);
+  process.exitCode = 1;
+});