@nudojs/core 0.1.0 → 0.3.0

package/src/algebra/__tests__/check-require-dep-memo.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { checkSource, resetCheckSourceMemo, pTrue } from "../index.ts";
+import { STD_NUDO_SRC } from "./nudo-constraints.ts";
+
+beforeEach(() => {
+  resetCheckSourceMemo();
+});
+
+describe("check memo covers regular require deps", () => {
+  it("misses when require target refine changes (parent source unchanged)", () => {
+    let dep = `
+/// @nudo:import { positive } from "./std.nudo.js"
+/**
+ * @nudo:refine x positive
+ */
+function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+module.exports = { needsPositive };
+`;
+    const loadModule = (spec: string) => {
+      if (spec.includes("std.nudo")) return STD_NUDO_SRC;
+      return dep;
+    };
+    const opts = { loadModule, fromFile: "/t/a.js" };
+    const src = `
+const { needsPositive } = require("./v.js");
+needsPositive(-1);
+`;
+    const r1 = checkSource("/t/a.js", src, pTrue, opts);
+    expect(r1.ok).toBe(false);
+    expect(r1.issues.some((i) => i.code === "nudo:constraint-violated")).toBe(true);
+
+    dep = `
+function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+module.exports = { needsPositive };
+`;
+    const r2 = checkSource("/t/a.js", src, pTrue, opts);
+    expect(r2.ok).toBe(true);
+  });
+});

package/src/algebra/__tests__/check-return-contract.test.ts

@@ -0,0 +1,90 @@
+/**
+ * @nudo:refine return 后置契约：推断返回值 ⊭ 声明。
+ * 与 @nudo:refine（前置）对偶；契约仍来自 *.nudo.js 模板。
+ */
+import { describe, it, expect } from "vitest";
+import { checkSource, pTrue } from "../index.ts";
+import { withStdImport, stdOpts } from "./nudo-constraints.ts";
+
+function issuesOf(src: string) {
+  return checkSource("/t/ret.js", withStdImport(src), pTrue, stdOpts);
+}
+
+describe("@nudo:refine return", () => {
+  it("ok: 返回值满足 positive", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine x positive
+ * @nudo:refine return positive
+ */
+function inc(x) {
+  return x + 1;
+}
+`);
+    expect(r.issues.filter((i) => i.severity === "error")).toEqual([]);
+  });
+
+  it("error: 字面量返回 ⊭ positive", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine return positive
+ */
+function bad() {
+  return 0;
+}
+`);
+    expect(r.ok).toBe(false);
+    const err = r.issues.find((i) => i.message.includes("@nudo:refine return"));
+    expect(err).toBeDefined();
+    expect(err!.expected).toContain(">");
+  });
+
+  it("error: 返回类型 ⊭ string", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine return notAString
+ */
+function n() {
+  return 1;
+}
+`);
+    // notAString 不在 std 里 → 无契约可查，不报
+    expect(r.issues.filter((i) => i.message.includes("@nudo:refine return"))).toEqual([]);
+  });
+
+  it("ok: 无 @nudo:refine return 不猜后置", () => {
+    const r = issuesOf(`
+function free() {
+  return -1;
+}
+`);
+    expect(r.issues.filter((i) => i.message.includes("@nudo:refine return"))).toEqual([]);
+  });
+
+  it("error: percent 上界", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine return percent
+ */
+function big() {
+  return 150;
+}
+`);
+    expect(r.ok).toBe(false);
+    expect(r.issues.some((i) => i.message.includes("@nudo:refine return"))).toBe(true);
+  });
+
+  it("ok: any/符号返回不误报", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine x positive
+ * @nudo:refine return positive
+ */
+function keep(x) {
+  return x;
+}
+`);
+    // 符号返回带 pred x>0，应满足
+    expect(r.issues.filter((i) => i.severity === "error")).toEqual([]);
+  });
+});

package/src/algebra/__tests__/check-shape-gold.test.ts

@@ -0,0 +1,303 @@
+/**
+ * shape 约束金标：契约规范 object 形状，无需 interface/type。
+ * 唯一 refine 形态：@nudo:refine <param> <shapeName>
+ */
+import { describe, it, expect } from "vitest";
+import { checkSource, pTrue } from "../index.ts";
+import {
+  shape,
+  number,
+  string,
+  isNudoConstraint,
+  instantiateConstraint,
+} from "../constraint.ts";
+import { predToString } from "../pred.ts";
+import { execNudoModule } from "../refine.ts";
+import { withStdImport, stdOpts } from "./nudo-constraints.ts";
+
+function issuesOf(src: string) {
+  return checkSource("/t/shape.js", withStdImport(src), pTrue, stdOpts);
+}
+
+function errorCodes(src: string): string[] {
+  return issuesOf(src)
+    .issues.filter((i) => i.severity === "error")
+    .map((i) => i.code);
+}
+
+describe("shape() constraint builder", () => {
+  it("builds field map from number()/string()", () => {
+    const c = shape({ id: number().gt(0), name: string() });
+    expect(isNudoConstraint(c)).toBe(true);
+    expect(Object.keys(c.fields ?? {}).sort()).toEqual(["id", "name"]);
+    expect(c.fields!.id!.constraint.prim).toBe("number");
+    expect(c.fields!.name!.constraint.prim).toBe("string");
+  });
+
+  it("instantiates to field-access Preds", () => {
+    const c = shape({ id: number().gt(0), name: string() });
+    const p = instantiateConstraint(c, "u");
+    const s = predToString(p);
+    expect(s).toContain("u.id");
+    expect(s).toContain(">");
+    expect(s).toContain("typeof u.name");
+  });
+
+  it("optional() marks field", () => {
+    const c = shape({ label: string().optional() });
+    expect(c.fields!.label!.optional).toBe(true);
+    expect(c.fields!.label!.constraint.isOptional).toBe(true);
+  });
+
+  it("executes shape in .nudo.js", () => {
+    const src = `
+export const user = shape({ id: number().gt(0), name: string() });
+`;
+    const exp = execNudoModule(src);
+    expect(isNudoConstraint(exp.user)).toBe(true);
+    expect(Object.keys((exp.user as { fields: object }).fields).sort()).toEqual([
+      "id",
+      "name",
+    ]);
+  });
+});
+
+describe("check: object literal ⊭ shape", () => {
+  it("ok: valid object", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine u userShape
+ */
+function register(u) {
+  return u.name;
+}
+register({ id: 1, name: "a" });
+`);
+    expect(r.ok).toBe(true);
+    expect(r.issues.filter((i) => i.severity === "error")).toEqual([]);
+  });
+
+  it("error: field bound violated (id > 0)", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine u userShape
+ */
+function register(u) {
+  return u.name;
+}
+register({ id: -1, name: "a" });
+`);
+    expect(r.ok).toBe(false);
+    const err = r.issues.find((i) => i.code === "nudo:constraint-violated");
+    expect(err).toBeDefined();
+    expect(err!.expected).toContain("u.id");
+    expect(err!.expected).toContain(">");
+  });
+
+  it("error: missing required field", () => {
+    // body 不访问 name，仅契约声明要求该字段
+    const r = issuesOf(`
+/**
+ * @nudo:refine u userShape
+ */
+function register(u) {
+  return u.id;
+}
+register({ id: 1 });
+`);
+    expect(r.ok).toBe(false);
+    const err = r.issues.find((i) => i.code === "nudo:constraint-violated");
+    expect(err).toBeDefined();
+    expect(err!.expected).toContain("missing");
+    expect(err!.expected).toContain("name");
+  });
+
+  it("error: field prim mismatch (name is number)", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine u userShape
+ */
+function register(u) {
+  return u.name;
+}
+register({ id: 1, name: 2 });
+`);
+    expect(r.ok).toBe(false);
+    const err = r.issues.find((i) => i.code === "nudo:constraint-violated");
+    expect(err).toBeDefined();
+    expect(err!.expected).toContain("string");
+  });
+
+  it("ok: optional field omitted", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine c configShape
+ */
+function setup(c) {
+  return c.retries;
+}
+setup({ retries: 3 });
+`);
+    expect(r.issues.filter((i) => i.severity === "error")).toEqual([]);
+  });
+
+  it("error: optional field present but wrong type", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine c configShape
+ */
+function setup(c) {
+  return c.retries;
+}
+setup({ retries: 3, label: 9 });
+`);
+    expect(r.ok).toBe(false);
+    expect(
+      r.issues.some(
+        (i) =>
+          i.code === "nudo:constraint-violated" &&
+          (i.expected ?? "").includes("string"),
+      ),
+    ).toBe(true);
+  });
+
+  it("error: numeric upper bound on shape field", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine c configShape
+ */
+function setup(c) {
+  return c.retries;
+}
+setup({ retries: 99 });
+`);
+    expect(r.ok).toBe(false);
+    const err = r.issues.find((i) => i.code === "nudo:constraint-violated");
+    expect(err).toBeDefined();
+    expect(err!.expected).toContain("≤");
+  });
+
+  it("ok: unknown identifier arg (no false positive)", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine u userShape
+ */
+function register(u) {
+  return u.name;
+}
+const payload = getPayload();
+register(payload);
+`);
+    expect(r.issues.filter((i) => i.severity === "error")).toEqual([]);
+  });
+
+  it("ok: no refine → no shape gate", () => {
+    const r = issuesOf(`
+function open(u) {
+  return u;
+}
+open({ id: -1 });
+`);
+    expect(r.issues.filter((i) => i.severity === "error")).toEqual([]);
+  });
+
+  it("ok: nested shape + array fields", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine o orderShape
+ */
+function place(o) {
+  return o.user.id;
+}
+place({ user: { id: 1, name: "a" }, tags: ["x"] });
+`);
+    expect(r.issues.filter((i) => i.severity === "error")).toEqual([]);
+  });
+
+  it("error: nested shape field bound", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine o orderShape
+ */
+function place(o) {
+  return o.user.id;
+}
+place({ user: { id: -1, name: "a" }, tags: ["x"] });
+`);
+    expect(r.ok).toBe(false);
+    expect(r.issues.some((i) => i.code === "nudo:constraint-violated")).toBe(true);
+  });
+
+  it("error: array element min length", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine o orderShape
+ */
+function place(o) {
+  return o.tags;
+}
+place({ user: { id: 1, name: "a" }, tags: [""] });
+`);
+    expect(r.ok).toBe(false);
+    expect(r.issues.some((i) => i.code === "nudo:constraint-violated")).toBe(true);
+  });
+
+  it("ok: int refine", () => {
+    const ok = issuesOf(`
+/**
+ * @nudo:refine n intId
+ */
+function take(n) { return n; }
+take(3);
+`);
+    expect(ok.issues.filter((i) => i.severity === "error")).toEqual([]);
+  });
+
+  it("error: int refine rejects non-integer", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine n intId
+ */
+function take(n) { return n; }
+take(1.5);
+`);
+    expect(r.ok).toBe(false);
+    expect(r.issues.some((i) => i.expected?.includes("int"))).toBe(true);
+  });
+
+  it("error: array refine rejects non-array", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine xs positives
+ */
+function take(xs) { return xs; }
+take(1);
+`);
+    expect(r.ok).toBe(false);
+    expect(r.issues.some((i) => i.expected?.includes("array"))).toBe(true);
+  });
+
+  it("error: array element bound", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine xs positives
+ */
+function take(xs) { return xs; }
+take([-1]);
+`);
+    expect(r.ok).toBe(false);
+    expect(r.issues.some((i) => i.code === "nudo:constraint-violated")).toBe(true);
+  });
+
+  it("error: string min length", () => {
+    const r = issuesOf(`
+/**
+ * @nudo:refine s shortName
+ */
+function take(s) { return s; }
+take("");
+`);
+    expect(r.ok).toBe(false);
+    expect(r.issues.some((i) => i.expected?.includes("length"))).toBe(true);
+  });
+});

package/src/algebra/__tests__/check-source-memo.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  checkSource,
+  resetCheckSourceMemo,
+  getCheckSourceMemoSize,
+  evictCheckSourceMemoForPaths,
+  resetGeneralizeMemo,
+  pTrue,
+} from "../index.ts";
+import { STD_NUDO_SRC, withStdImport } from "./nudo-constraints.ts";
+
+const SRC = `
+function add(a, b) {
+  return a + b;
+}
+function needsPositive(x) {
+  /** @nudo:refine x positive */
+  return x + 1;
+}
+`;
+
+beforeEach(() => {
+  resetCheckSourceMemo();
+  resetGeneralizeMemo();
+});
+
+describe("checkSource whole-file memo", () => {
+  it("hit returns equivalent report for same source", () => {
+    const a = checkSource("/t/a.js", SRC, pTrue, {});
+    const b = checkSource("/t/a.js", SRC, pTrue, {});
+    expect(getCheckSourceMemoSize()).toBe(1);
+    expect(b.ok).toBe(a.ok);
+    expect(b.signatures.map((s) => s.name)).toEqual(a.signatures.map((s) => s.name));
+    expect(b.issues.map((i) => i.code)).toEqual(a.issues.map((i) => i.code));
+    expect(b.summary).toEqual(a.summary);
+  });
+
+  it("hits when only trailing non-nudo comments change", () => {
+    checkSource("/t/a.js", SRC, pTrue, {});
+    checkSource("/t/a.js", SRC + "\n// touch\n", pTrue, {});
+    expect(getCheckSourceMemoSize()).toBe(1);
+  });
+
+  it("misses when source body changes", () => {
+    checkSource("/t/a.js", SRC, pTrue, {});
+    checkSource("/t/a.js", SRC + "\nconst zzz = 1;\n", pTrue, {});
+    expect(getCheckSourceMemoSize()).toBe(2);
+  });
+
+  it("misses when filePath changes", () => {
+    checkSource("/t/a.js", SRC, pTrue, {});
+    checkSource("/t/b.js", SRC, pTrue, {});
+    expect(getCheckSourceMemoSize()).toBe(2);
+  });
+
+  it("misses when loadModule identity changes", () => {
+    const l1 = () => undefined;
+    const l2 = () => undefined;
+    checkSource("/t/a.js", SRC, pTrue, { loadModule: l1, fromFile: "/t/a.js" });
+    checkSource("/t/a.js", SRC, pTrue, { loadModule: l2, fromFile: "/t/a.js" });
+    expect(getCheckSourceMemoSize()).toBe(2);
+  });
+
+  it("misses when dep content changes", () => {
+    let dep = "export const positive = number().gt(0);\n";
+    const loadModule = () => dep;
+    const opts = { loadModule, fromFile: "/t/a.js" };
+    const src = `
+/// @nudo:import { positive } from "./shapes.nudo.js"
+function needsPositive(x) {
+  /** @nudo:refine x positive */
+  return x + 1;
+}
+`;
+    checkSource("/t/a.js", src, pTrue, opts);
+    dep = "export const positive = number().ge(0);\n";
+    checkSource("/t/a.js", src, pTrue, opts);
+    expect(getCheckSourceMemoSize()).toBe(2);
+  });
+
+  it("evictCheckSourceMemoForPaths drops dependents of that dep", () => {
+    const loadModule = () => "export const positive = number().gt(0);\n";
+    const opts = { loadModule, fromFile: "/t/a.js" };
+    const src = `
+/// @nudo:import { positive } from "./shapes.nudo.js"
+function needsPositive(x) {
+  /** @nudo:refine x positive */
+  return x + 1;
+}
+`;
+    checkSource("/t/a.js", src, pTrue, opts);
+    checkSource("/t/b.js", SRC, pTrue, {});
+    const before = getCheckSourceMemoSize();
+    const n = evictCheckSourceMemoForPaths(["/t/shapes.nudo.js"]);
+    expect(n).toBeGreaterThan(0);
+    expect(getCheckSourceMemoSize()).toBeLessThan(before);
+    // 无关文件仍在
+    expect(getCheckSourceMemoSize()).toBe(1);
+  });
+
+  it("reset drops all entries", () => {
+    checkSource("/t/a.js", SRC, pTrue, {});
+    expect(getCheckSourceMemoSize()).toBeGreaterThan(0);
+    resetCheckSourceMemo();
+    expect(getCheckSourceMemoSize()).toBe(0);
+  });
+
+  it("mutating returned issues does not corrupt cache", () => {
+    const a = checkSource("/t/a.js", SRC, pTrue, {});
+    a.issues.push({
+      severity: "error",
+      code: "x",
+      message: "mutated",
+    });
+    a.signatures.length = 0;
+    const b = checkSource("/t/a.js", SRC, pTrue, {});
+    expect(b.issues.some((i) => i.message === "mutated")).toBe(false);
+    expect(b.signatures.length).toBeGreaterThan(0);
+  });
+
+  it("same loadModule identity hits memo (wrapper must not defeat key)", () => {
+    const loadModule = () => undefined;
+    const opts = { loadModule, fromFile: "/t/a.js" };
+    checkSource("/t/a.js", SRC, pTrue, opts);
+    const size1 = getCheckSourceMemoSize();
+    checkSource("/t/a.js", SRC, pTrue, opts);
+    checkSource("/t/a.js", SRC, pTrue, opts);
+    expect(size1).toBe(1);
+    expect(getCheckSourceMemoSize()).toBe(1);
+  });
+
+  it("hits when only trailing non-nudo comments change even with loadModule", () => {
+    const loadModule = () => undefined;
+    const opts = { loadModule, fromFile: "/t/a.js" };
+    checkSource("/t/a.js", SRC, pTrue, opts);
+    checkSource("/t/a.js", SRC + "\n// touch\n", pTrue, opts);
+    expect(getCheckSourceMemoSize()).toBe(1);
+  });
+
+  it("reports constraint violation for const-assigned literal call", () => {
+    const loadModule = (spec: string) =>
+      spec.includes("std") ? STD_NUDO_SRC : undefined;
+    const src = `${withStdImport(`
+/**
+ * @nudo:refine x positive
+ */
+function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+const bad = needsPositive(-1);
+`)}`;
+    const r = checkSource("/t/scan.js", src, pTrue, { loadModule, fromFile: "/t/scan.js" });
+    expect(r.issues.some((i) => i.code === "nudo:constraint-violated")).toBe(true);
+  });
+
+  it("reports constraint violation for if-condition literal call", () => {
+    const loadModule = (spec: string) =>
+      spec.includes("std") ? STD_NUDO_SRC : undefined;
+    const src = `${withStdImport(`
+/**
+ * @nudo:refine x positive
+ */
+function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+if (needsPositive(-1)) {}
+`)}`;
+    const r = checkSource("/t/scan-if.js", src, pTrue, { loadModule, fromFile: "/t/scan-if.js" });
+    expect(r.issues.some((i) => i.code === "nudo:constraint-violated")).toBe(true);
+  });
+
+  it("fingerprints transitive require deps (grandchild change misses)", () => {
+    const files: Record<string, string> = {
+      "/t/w.js": "module.exports = { n: 1 };\n",
+      "/t/v.js": 'const w = require("./w.js");\nmodule.exports = { fromW: w.n };\n',
+    };
+    const loadModule = (spec: string, fromFile: string) => {
+      if (spec === "./w.js") return files["/t/w.js"];
+      if (spec === "./v.js") return files["/t/v.js"];
+      if (spec === "./w.js" && fromFile.endsWith("v.js")) return files["/t/w.js"];
+      return undefined;
+    };
+    // resolve relative to the dep file when nested
+    const load = (spec: string, fromFile: string) => {
+      if (fromFile === "/t/a.js" && spec === "./v.js") return files["/t/v.js"];
+      if (fromFile === "/t/v.js" && spec === "./w.js") return files["/t/w.js"];
+      return loadModule(spec, fromFile);
+    };
+    const opts = { loadModule: load, fromFile: "/t/a.js" };
+    const src = `
+const v = require("./v.js");
+function id(x) { return x; }
+id(v.fromW);
+`;
+    checkSource("/t/a.js", src, pTrue, opts);
+    expect(getCheckSourceMemoSize()).toBe(1);
+    // grandchild content change, parent + child sources unchanged
+    files["/t/w.js"] = "module.exports = { n: 2 };\n";
+    checkSource("/t/a.js", src, pTrue, opts);
+    expect(getCheckSourceMemoSize()).toBe(2);
+  });
+});

package/src/algebra/__tests__/check.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from "vitest";
+import { checkSource, formatCheckReport, pTrue } from "../index.ts";
+import { withStdImport, stdOpts } from "./nudo-constraints.ts";
+
+describe("nudo check gate", () => {
+  it("literal call violating constraint is error", () => {
+    // @nudo:refine 声明契约；调用 -1 应报错
+    const src = `
+/**
+ * @nudo:refine x positive
+ */
+function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+const r = needsPositive(-1);
+`;
+    const report = checkSource("t.js", withStdImport(src), pTrue, stdOpts);
+    expect(report.ok).toBe(false);
+    const err = report.issues.find((i) => i.severity === "error");
+    expect(err).toBeDefined();
+    expect(err!.code).toBe("nudo:constraint-violated");
+  });
+
+  it("valid literal call is ok", () => {
+    const src = `
+/**
+ * @nudo:refine x positive
+ */
+function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+const r = needsPositive(5);
+`;
+    const report = checkSource("t.js", withStdImport(src), pTrue, stdOpts);
+    expect(report.ok).toBe(true);
+    expect(report.signatures.some((f) => f.name === "needsPositive")).toBe(true);
+  });
+
+  it("reports intensional signatures", () => {
+    const src = `
+function add(a, b) { return a + b; }
+function scale(x) { return add(x, 1); }
+`;
+    const report = checkSource("t.js", withStdImport(src), pTrue, stdOpts);
+    const scale = report.signatures.find((f) => f.name === "scale");
+    expect(scale!.display).toContain("A1");
+  });
+
+  it("formatCheckReport is Nudo-native (signatures + issues)", () => {
+    const bad = checkSource(
+      "t.js",
+      withStdImport(`/**
+ * @nudo:refine x positive
+ */
+function f(x){ if (x>0) return x; return 0; }
+f(-1);
+`),
+      pTrue,
+      stdOpts,
+    );
+    const text = formatCheckReport(bad);
+    expect(text).toContain("FAILED");
+    expect(text).toContain("signatures");
+    expect(text).toContain("actual:");
+    expect(text).toContain("expected:");
+  });
+});