@nudojs/service 0.2.0 → 0.3.0

package/src/__tests__/diagnostics.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from "vitest";
+import { analyzeFile } from "../analyzer.ts";
+
+describe("Diagnostic error codes and suggestions", () => {
+  it("should include code for unreachable diagnostics", () => {
+    const source = `
+// @nudo:case "test" (1)
+function fn(x) {
+  return x;
+  return x + 1;
+}
+`;
+    const result = analyzeFile("test.js", source);
+    const unreachable = result.diagnostics.find(d => d.message.includes("unreachable"));
+    expect(unreachable).toBeDefined();
+    expect(unreachable!.code).toBe("nudo-unreachable");
+  });
+
+  it("should include suggestions for unreachable diagnostics", () => {
+    const source = `
+// @nudo:case "test" (1)
+function fn(x) {
+  return x;
+  return x + 1;
+}
+`;
+    const result = analyzeFile("test.js", source);
+    const unreachable = result.diagnostics.find(d => d.message.includes("unreachable"));
+    expect(unreachable!.suggestions).toBeDefined();
+    expect(unreachable!.suggestions!.length).toBeGreaterThan(0);
+  });
+
+  it("should generate nudo:builtin-unknown for uncovered APIs", () => {
+    const source = `
+// @nudo:case "test" ()
+function fn() {
+  return WeakRef;
+}
+`;
+    const result = analyzeFile("test.js", source);
+    const builtin = result.diagnostics.find(d => d.code === "nudo:builtin-unknown");
+    expect(builtin).toBeDefined();
+    expect(builtin!.suggestions).toBeDefined();
+    expect(builtin!.suggestions![0]).toContain("@nudo:mock");
+  });
+
+  it("should generate nudo:mock-invalid for unparseable mock expressions", () => {
+    const source = `
+// @nudo:mock handler = invalid!@#syntax()
+// @nudo:case "test" (1)
+function fn(x) {
+  return handler(x);
+}
+`;
+    const result = analyzeFile("test.js", source);
+    const mockDiag = result.diagnostics.find(d => d.code === "nudo:mock-invalid");
+    expect(mockDiag).toBeDefined();
+    expect(mockDiag!.suggestions).toBeDefined();
+  });
+});

package/src/__tests__/dts-generator.test.ts

@@ -75,9 +75,14 @@ function add(a, b) {
 `;
     const result = analyzeFile("/test/gen.js", source);
     const dts = generateDts(result);
-    expect(dts).toContain("export declare function add");
-    expect(dts).toContain("): 3;");
-    expect(dts).toContain("): number;");
+    // 行为已修复：不再按 case 生成字面量重载（`): 3;` 会拦截 safeSqrt(5)
+    // 这类合法调用），改为单一 widen 主签名，字面量精度保留在 JSDoc Case: 行
+    expect(dts).toContain("export declare function add(a: number, b: number): number;");
+    expect(dts.match(/export declare function add\b/g)).toHaveLength(1);
+    expect(dts).toContain("Case: concrete (1, 2) => 3");
+    // symbolic case 与主签名同形（无信息损失），不再重复罗列
+    expect(dts).not.toContain("): 3;");
+    expect(dts).not.toContain("Case: symbolic");
   });
 
   it("generates single overload for single case", () => {
@@ -91,8 +96,287 @@ function identity(x) {
 `;
     const result = analyzeFile("/test/single.js", source);
     const dts = generateDts(result);
-    const lines = dts.trim().split("\n");
-    expect(lines).toHaveLength(1);
-    expect(lines[0]).toContain("export declare function identity");
+    expect(dts).toContain("export declare function identity");
+    expect(dts).toContain("x: number");
+  });
+
+  it("uses actual parameter names from AST", () => {
+    const source = `
+/**
+ * @nudo:case "numbers" (T.number, T.number)
+ */
+function add(a, b) {
+  return a + b;
+}
+`;
+    const result = analyzeFile("/test/params.js", source);
+    const dts = generateDts(result);
+    expect(dts).toContain("a: number");
+    expect(dts).toContain("b: number");
+    expect(dts).not.toContain("arg0");
+    expect(dts).not.toContain("arg1");
+  });
+
+  it("generates JSDoc comments", () => {
+    const source = `
+/**
+ * @nudo:case "test" (T.string)
+ */
+function greet(name) {
+  return "hello " + name;
+}
+`;
+    const result = analyzeFile("/test/jsdoc.js", source);
+    const dts = generateDts(result);
+    expect(dts).toContain("/**");
+    expect(dts).toContain("* @param name - string");
+    expect(dts).toContain("* @returns");
+    expect(dts).toContain("*/");
+  });
+
+  it("generates JSDoc with case names for multiple overloads", () => {
+    const source = `
+/**
+ * @nudo:case "str" (T.string) => T.number
+ * @nudo:case "num" (T.number) => T.string
+ */
+function convert(x) {
+  return typeof x === "string" ? Number(x) : String(x);
+}
+`;
+    const result = analyzeFile("/test/multi.js", source);
+    const dts = generateDts(result);
+    expect(dts).toContain("Case: str");
+    expect(dts).toContain("Case: num");
+  });
+
+  it("handles rest parameters", () => {
+    const source = `
+/**
+ * @nudo:case "test" (T.array(T.number))
+ */
+function sum(...nums) {
+  return nums;
+}
+`;
+    const result = analyzeFile("/test/rest.js", source);
+    const dts = generateDts(result);
+    expect(dts).toContain("...nums");
+  });
+
+  it("widens literal params so widened calls compile (safeSqrt scenario)", () => {
+    const source = `
+/**
+ * @nudo:case "valid" (10)
+ * @nudo:case "negative" (-1)
+ */
+function safeSqrt(x) {
+  if (x < 0) {
+    throw new RangeError("negative input");
+  }
+  return x;
+}
+`;
+    const result = analyzeFile("/test/sqrt2.js", source);
+    const dts = generateDts(result);
+    // 单一 widen 主签名：参数联合 10 | -1 → number，返回 combined 同样 widen
+    expect(dts).toContain("export declare function safeSqrt(x: number): number;");
+    expect(dts.match(/export declare function safeSqrt\b/g)).toHaveLength(1);
+    // 字面量精度（含 throwing case 的 never）保留在 JSDoc
+    expect(dts).toContain("Case: valid (10) => 10");
+    expect(dts).toContain("Case: negative (-1) => never");
+  });
+
+  it("widens literal params for a single-case function too", () => {
+    const source = `
+/**
+ * @nudo:case "only" (42)
+ */
+function pass(x) {
+  return x;
+}
+`;
+    const result = analyzeFile("/test/single-literal.js", source);
+    const dts = generateDts(result);
+    expect(dts).toContain("export declare function pass(x: number): number;");
+    expect(dts.match(/export declare function pass\b/g)).toHaveLength(1);
+  });
+
+  it("widens string and boolean literal params to base types", () => {
+    const source = `
+/**
+ * @nudo:case "s" ("fast")
+ * @nudo:case "b" (true)
+ */
+function flag(x) {
+  return x;
+}
+`;
+    const result = analyzeFile("/test/flag.js", source);
+    const dts = generateDts(result);
+    expect(dts).toContain("export declare function flag(x: string | boolean): string | boolean;");
+    expect(dts).toContain('Case: s ("fast") => "fast"');
+  });
+
+  it("widens bigint literal params (hand-built analysis)", () => {
+    const fn = {
+      name: "big",
+      loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 9 } },
+      paramNames: ["n"],
+      cases: [
+        {
+          name: "c",
+          args: [T.literal(10n)],
+          result: T.literal(10n),
+          throws: T.never,
+        },
+      ],
+    };
+    const dts = generateDts({ functions: [fn] } as unknown as Parameters<typeof generateDts>[0]);
+    expect(dts).toContain("export declare function big(n: bigint): bigint;");
+  });
+
+  it("marks mixed-arity tail params optional", () => {
+    const source = `
+/**
+ * @nudo:case "one" (T.number)
+ * @nudo:case "two" (T.number, T.string)
+ */
+function either(x, y) {
+  return y === undefined ? x : y;
+}
+`;
+    const result = analyzeFile("/test/either.js", source);
+    const dts = generateDts(result);
+    expect(dts).toContain("either(x: number, y?: string)");
+    expect(dts.match(/export declare function either\b/g)).toHaveLength(1);
+  });
+
+  it("keeps the rest-args form for case-less combined functions", () => {
+    const fn = {
+      name: "entryOnly",
+      loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 9 } },
+      paramNames: ["x"],
+      cases: [],
+      combined: T.promise(T.number),
+    };
+    const dts = generateDts({ functions: [fn] } as unknown as Parameters<typeof generateDts>[0]);
+    expect(dts).toBe("export declare function entryOnly(...args: unknown[]): Promise<number>;\n");
+  });
+
+  it("widens homogeneous tuple params to arrays (reduceSum scenario)", () => {
+    const source = `
+// @nudo:case "t" ([1, 2, 3, 4, 5])
+function reduceSum(arr) {
+  return arr.reduce((a, b) => a + b, 0);
+}
+`;
+    const result = analyzeFile("/test/reduce.js", source);
+    const dts = generateDts(result);
+    // 行为已修复：定长 widened 元组 [number×5] 会拒收变长合法实参
+    // （tsc TS2345），字面量长度只是单次调用观察，不构成约束 → number[]
+    expect(dts).toContain("export declare function reduceSum(arr: number[]): number;");
+    expect(dts).toContain("Case: t ([1, 2, 3, 4, 5]) => 15");
+  });
+
+  it("widens heterogeneous tuple params positionally", () => {
+    const source = `
+// @nudo:case "t" ([1, "two"])
+function pair(p) {
+  return p;
+}
+`;
+    const result = analyzeFile("/test/pair.js", source);
+    const dts = generateDts(result);
+    // 异构元素保留 widened 定长元组：[number, string] 的位置语义真实，
+    // 且不拦截合法的按位调用；返回位（协变）保留字面量精度
+    expect(dts).toContain("export declare function pair(p: [number, string]): [1, \"two\"];");
+  });
+
+  it("widens object param property values (single case)", () => {
+    const source = `
+/**
+ * @nudo:case "concrete" ({ name: "Alice", age: 30 })
+ */
+function greet(person) {
+  return \`Hello, \${person.name}! You are \${person.age} years old.\`;
+}
+`;
+    const result = analyzeFile("/test/greet1.js", source);
+    const dts = generateDts(result);
+    // 单 case 对象参数：属性值递归 widen（否则 greet({ name: "Bob", age: 20 })
+    // 不匹配 { name: "Alice"; age: 30 }，同类拦截问题）
+    expect(dts).toContain("export declare function greet(person: { name: string; age: number }): string;");
+    expect(dts).toContain('Case: concrete ({ name: "Alice"; age: 30 })');
+  });
+
+  it("keeps return-position precision while widening params (contrast)", () => {
+    const source = `
+// @nudo:case "t" ([1, 2])
+function tupleEcho(arr) {
+  return arr;
+}
+`;
+    const result = analyzeFile("/test/echo.js", source);
+    const dts = generateDts(result);
+    // 参数位（逆变）递归 widen → number[]；返回位（协变）保留字面量精度
+    expect(dts).toContain("export declare function tupleEcho(arr: number[]): [1, 2];");
+  });
+
+  it("dedupes same-shaped widened object params across cases", () => {
+    const source = `
+/**
+ * @nudo:case "a" ({ id: 1 })
+ * @nudo:case "b" ({ id: 2 })
+ */
+function byId(q) {
+  return q.id;
+}
+`;
+    const result = analyzeFile("/test/byid.js", source);
+    const dts = generateDts(result);
+    // 两个同形对象 widen 后都成 { id: number }，按渲染串去重避免
+    // `{ id: number } | { id: number }` 重复成员
+    expect(dts).toContain("export declare function byId(q: { id: number }): number;");
+    expect(dts).not.toContain("{ id: number } | { id: number }");
+  });
+
+  it("dedupes extracted underscore names from destructured params", () => {
+    const fn = {
+      name: "pair",
+      loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 9 } },
+      // 两个解构参数在 AST 提取时都叫 "_"；重名会让 .d.ts 非法（TS2300）
+      paramNames: ["_", "_"],
+      cases: [
+        {
+          name: "c",
+          args: [T.object({ a: T.number }), T.object({ b: T.string })],
+          result: T.number,
+          throws: T.never,
+        },
+      ],
+    };
+    const dts = generateDts({ functions: [fn] } as unknown as Parameters<typeof generateDts>[0]);
+    expect(dts).toContain("export declare function pair(_: { a: number }, _2: { b: string }): number;");
+    expect(dts).toContain("@param _2 - { b: string }");
+  });
+
+  it("keeps nested literal precision inside Promise payloads", () => {
+    const fn = {
+      name: "fetchData",
+      loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 9 } },
+      paramNames: [],
+      cases: [
+        {
+          name: "test",
+          args: [],
+          result: T.promise(T.literal(42)),
+          throws: T.never,
+        },
+      ],
+    };
+    const dts = generateDts({ functions: [fn] } as unknown as Parameters<typeof generateDts>[0]);
+    // widen 只作用于顶层标量字面量；Promise 载荷精度保留（既有行为）
+    expect(dts).toContain("export declare function fetchData(): Promise<42>;");
   });
 });

package/src/__tests__/fn-cache-evict.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  evictFnAnalysisCacheForFiles,
+  clearFnAnalysisCache,
+  fnAnalysisCacheSet,
+  fnAnalysisCacheGet,
+  type CachedFnAnalysis,
+} from "../fn-analysis-cache.ts";
+
+function entry(name: string): CachedFnAnalysis {
+  return {
+    analysis: {
+      name,
+      loc: {
+        start: { line: 1, column: 0 },
+        end: { line: 1, column: 10 },
+      },
+      paramNames: [],
+      cases: [],
+    },
+    diagnostics: [],
+    caseHints: [],
+    callRecords: [],
+  };
+}
+
+const SEP = "\0";
+
+describe("evictFnAnalysisCacheForFiles", () => {
+  beforeEach(() => {
+    clearFnAnalysisCache();
+  });
+
+  it("drops every fn entry for the given entry file", () => {
+    const keyA1 = `/t/a.js${SEP}own1${SEP}deps1${SEP}0`;
+    const keyA2 = `/t/a.js${SEP}own2${SEP}deps2${SEP}0`;
+    const keyB = `/t/b.js${SEP}own1${SEP}deps1${SEP}0`;
+    fnAnalysisCacheSet(keyA1, entry("a"));
+    fnAnalysisCacheSet(keyA2, entry("b"));
+    fnAnalysisCacheSet(keyB, entry("c"));
+    const n = evictFnAnalysisCacheForFiles(["/t/a.js"]);
+    expect(n).toBe(2);
+    expect(fnAnalysisCacheGet(keyA1)).toBeUndefined();
+    expect(fnAnalysisCacheGet(keyB)).toBeDefined();
+  });
+
+  it("does not drop a different file with a shared path prefix", () => {
+    const keyA = `/t/a.js${SEP}x${SEP}y${SEP}0`;
+    const keyBak = `/t/a.js.bak${SEP}x${SEP}y${SEP}0`;
+    fnAnalysisCacheSet(keyA, entry("a"));
+    fnAnalysisCacheSet(keyBak, entry("bak"));
+    evictFnAnalysisCacheForFiles(["/t/a.js"]);
+    expect(fnAnalysisCacheGet(keyA)).toBeUndefined();
+    expect(fnAnalysisCacheGet(keyBak)).toBeDefined();
+  });
+});

package/src/__tests__/fn-sig-impl.test.ts

@@ -0,0 +1,247 @@
+import { describe, it, expect } from "vitest";
+import { typeValueToString } from "@nudojs/core";
+import { analyzeFile } from "../analyzer.ts";
+
+describe("fnSig impl: concrete args produce precise values", () => {
+  it("Math.floor with literal returns exact result", () => {
+    const source = `
+/// @nudo:env es
+
+/**
+ * @nudo:case "concrete" (3.7)
+ * @nudo:case "symbolic" (T.number)
+ */
+function floorIt(x) {
+  return Math.floor(x);
+}
+`;
+    const result = analyzeFile("/test/math.js", source);
+    const fn = result.functions[0];
+    expect(fn.cases[0].name).toBe("concrete");
+    expect(typeValueToString(fn.cases[0].result)).toBe("3");
+    expect(fn.cases[1].name).toBe("symbolic");
+    expect(typeValueToString(fn.cases[1].result)).toBe("number");
+  });
+
+  it("Math.max with literals returns exact result", () => {
+    const source = `
+/// @nudo:env es
+
+/**
+ * @nudo:case "test" (3, 7)
+ */
+function maxOf(a, b) {
+  return Math.max(a, b);
+}
+`;
+    const result = analyzeFile("/test/math.js", source);
+    expect(typeValueToString(result.functions[0].cases[0].result)).toBe("7");
+  });
+
+  it("JSON.stringify with literal returns exact string", () => {
+    const source = `
+/// @nudo:env es
+
+/**
+ * @nudo:case "test" (42)
+ */
+function toJson(x) {
+  return JSON.stringify(x);
+}
+`;
+    const result = analyzeFile("/test/json.js", source);
+    expect(typeValueToString(result.functions[0].cases[0].result)).toBe('"42"');
+  });
+
+  it("encodeURIComponent with literal returns exact string", () => {
+    const source = `
+/// @nudo:env es
+
+/**
+ * @nudo:case "test" ("hello world")
+ */
+function encode(s) {
+  return encodeURIComponent(s);
+}
+`;
+    const result = analyzeFile("/test/encode.js", source);
+    expect(typeValueToString(result.functions[0].cases[0].result)).toBe('"hello%20world"');
+  });
+
+  it("Number.isInteger with literal returns exact boolean", () => {
+    const source = `
+/// @nudo:env es
+
+/**
+ * @nudo:case "int" (5)
+ * @nudo:case "float" (5.5)
+ */
+function checkInt(x) {
+  return Number.isInteger(x);
+}
+`;
+    const result = analyzeFile("/test/num.js", source);
+    expect(typeValueToString(result.functions[0].cases[0].result)).toBe("true");
+    expect(typeValueToString(result.functions[0].cases[1].result)).toBe("false");
+  });
+
+  it("parseInt with literal returns exact number", () => {
+    const source = `
+/// @nudo:env es
+
+/**
+ * @nudo:case "test" ("42")
+ */
+function parseIt(s) {
+  return parseInt(s);
+}
+`;
+    const result = analyzeFile("/test/parse.js", source);
+    expect(typeValueToString(result.functions[0].cases[0].result)).toBe("42");
+  });
+
+  it("Promise.resolve preserves argument type", () => {
+    const source = `
+/// @nudo:env es
+
+/**
+ * @nudo:case "test" (42)
+ */
+async function wrap(x) {
+  return await Promise.resolve(x);
+}
+`;
+    const result = analyzeFile("/test/promise.js", source);
+    expect(typeValueToString(result.functions[0].cases[0].result)).toBe("Promise<42>");
+  });
+});
+
+describe("fnSig impl: URL constructor with concrete args", () => {
+  it("URL with literal string returns precise properties", () => {
+    const source = `
+/// @nudo:env web
+
+/**
+ * @nudo:case "test" ("https://example.com/path?q=hello#hash")
+ */
+function parseUrl(raw) {
+  const url = new URL(raw);
+  return {
+    host: url.hostname,
+    path: url.pathname,
+    query: url.search,
+    hash: url.hash,
+  };
+}
+`;
+    const result = analyzeFile("/test/url.js", source);
+    const res = typeValueToString(result.functions[0].cases[0].result);
+    expect(res).toContain('"example.com"');
+    expect(res).toContain('"/path"');
+    expect(res).toContain('"?q=hello"');
+    expect(res).toContain('"#hash"');
+  });
+
+  it("URL with symbolic string falls back to generic type", () => {
+    const source = `
+/// @nudo:env web
+
+/**
+ * @nudo:case "test" (T.string)
+ */
+function parseUrl(raw) {
+  const url = new URL(raw);
+  return url.hostname;
+}
+`;
+    const result = analyzeFile("/test/url.js", source);
+    expect(typeValueToString(result.functions[0].cases[0].result)).toBe("string");
+  });
+});
+
+describe("fnSig impl: Node.js path with concrete args", () => {
+  it("path.join with literals returns exact path", () => {
+    const source = `
+/// @nudo:env node
+
+import { join } from "node:path";
+
+/**
+ * @nudo:case "test" ("src", "utils", "index.js")
+ */
+function buildPath(a, b, c) {
+  return join(a, b, c);
+}
+`;
+    const result = analyzeFile("/test/path.js", source);
+    expect(typeValueToString(result.functions[0].cases[0].result)).toBe('"src/utils/index.js"');
+  });
+
+  it("path.extname with literal returns exact extension", () => {
+    const source = `
+/// @nudo:env node
+
+import { extname } from "node:path";
+
+/**
+ * @nudo:case "test" ("file.ts")
+ */
+function getExt(f) {
+  return extname(f);
+}
+`;
+    const result = analyzeFile("/test/path.js", source);
+    expect(typeValueToString(result.functions[0].cases[0].result)).toBe('".ts"');
+  });
+
+  it("path.basename with literal returns exact name", () => {
+    const source = `
+/// @nudo:env node
+
+import { basename } from "node:path";
+
+/**
+ * @nudo:case "test" ("/home/user/file.txt")
+ */
+function getName(p) {
+  return basename(p);
+}
+`;
+    const result = analyzeFile("/test/path.js", source);
+    expect(typeValueToString(result.functions[0].cases[0].result)).toBe('"file.txt"');
+  });
+
+  it("path.dirname with literal returns exact dir", () => {
+    const source = `
+/// @nudo:env node
+
+import { dirname } from "node:path";
+
+/**
+ * @nudo:case "test" ("/home/user/file.txt")
+ */
+function getDir(p) {
+  return dirname(p);
+}
+`;
+    const result = analyzeFile("/test/path.js", source);
+    expect(typeValueToString(result.functions[0].cases[0].result)).toBe('"/home/user"');
+  });
+
+  it("path.join with symbolic args falls back to string", () => {
+    const source = `
+/// @nudo:env node
+
+import { join } from "node:path";
+
+/**
+ * @nudo:case "test" (T.string, T.string)
+ */
+function buildPath(a, b) {
+  return join(a, b);
+}
+`;
+    const result = analyzeFile("/test/path.js", source);
+    expect(typeValueToString(result.functions[0].cases[0].result)).toBe("string");
+  });
+});

package/src/__tests__/guard-generator.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import { T } from "@nudojs/core";
+import { generateGuardFunction } from "../guard-generator.ts";
+
+describe("guard-generator", () => {
+  it("generates guard for string type", () => {
+    const guard = generateGuardFunction("isString", T.string);
+    expect(guard).toContain("typeof data === 'string'");
+  });
+
+  it("generates guard for object type", () => {
+    const obj = T.object({ name: T.string, age: T.number });
+    const guard = generateGuardFunction("isUser", obj);
+    expect(guard).toContain("typeof data === 'object'");
+    expect(guard).toContain("data.name");
+    expect(guard).toContain("data.age");
+  });
+
+  it("generates guard for union type", () => {
+    const union = T.union(T.string, T.number);
+    const guard = generateGuardFunction("isStringOrNumber", union);
+    expect(guard).toContain("||");
+  });
+
+  it("generates guard for array type", () => {
+    const guard = generateGuardFunction("isStringArray", T.array(T.string));
+    expect(guard).toContain("Array.isArray(data)");
+  });
+});