@nudojs/core 0.2.0 → 0.3.0

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

@@ -0,0 +1,290 @@
+import { describe, it, expect } from "vitest";
+import { checkSource, pTrue } from "../index.ts";
+import { withStdImport, stdOpts } from "./nudo-constraints.ts";
+
+/**
+ * nudo check 金标：多形态 JS 片段上的门禁行为。
+ * 每条：source + 期望 ok / 期望出现的 issue code。
+ */
+
+type Gold = {
+  name: string;
+  source: string;
+  expectOk: boolean;
+  expectCode?: string;
+};
+
+const golds: Gold[] = [
+  {
+    name: "valid positive call",
+    source: `
+/**
+ * @nudo:refine x positive
+ */
+function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+const r = needsPositive(5);
+`,
+    expectOk: true,
+  },
+  {
+    name: "negative call violates x>0",
+    source: `
+/**
+ * @nudo:refine x positive
+ */
+function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+const r = needsPositive(-1);
+`,
+    expectOk: false,
+    expectCode: "nudo:constraint-violated",
+  },
+  {
+    name: "range guard lo is clamp not violation",
+    source: `
+function clampId(id) {
+  if (id < 1) return 1;
+  if (id > 9999) return 9999;
+  return id;
+}
+clampId(0);
+`,
+    // `id < 1` 是回退守卫，不作为调用前置
+    expectOk: true,
+  },
+  {
+    name: "range guard valid mid",
+    source: `
+function clampId(id) {
+  if (id < 1) return 1;
+  if (id > 9999) return 9999;
+  return id;
+}
+clampId(50);
+`,
+    expectOk: true,
+  },
+  {
+    name: "pure arithmetic no constraints",
+    source: `
+function add(a, b) { return a + b; }
+const r = add(1, 2);
+`,
+    expectOk: true,
+  },
+  {
+    name: "ESM export function still listed",
+    source: `
+export function scale(x) { return x + 1; }
+`,
+    expectOk: true,
+  },
+  {
+    name: "async function listed",
+    source: `
+export async function load(id) { return id + 1; }
+`,
+    expectOk: true,
+  },
+  {
+    name: "class constructor listed",
+    source: `
+class Counter {
+  constructor(n) { this.n = n; }
+  get() { return this.n; }
+}
+export function main() { return new Counter(1).get(); }
+`,
+    expectOk: true,
+  },
+  // --- 真阳性：必须报 ---
+  {
+    name: "zero violates x>0",
+    source: `
+/**
+ * @nudo:refine x positive
+ */
+function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+needsPositive(0);
+`,
+    expectOk: false,
+    expectCode: "nudo:constraint-violated",
+  },
+  {
+    name: "unary negative call",
+    source: `
+/**
+ * @nudo:refine x positive
+ */
+function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+needsPositive(-3);
+`,
+    expectOk: false,
+    expectCode: "nudo:constraint-violated",
+  },
+  {
+    name: "x>=1 rejects 0",
+    source: `
+/**
+ * @nudo:refine i atLeast1
+ */
+function idx(i) {
+  if (i >= 1) return i;
+  return 1;
+}
+idx(0);
+`,
+    expectOk: false,
+    expectCode: "nudo:constraint-violated",
+  },
+  {
+    name: "upper bound x<10 rejects 10",
+    source: `
+/**
+ * @nudo:refine n small
+ */
+function small(n) {
+  if (n < 10) return n;
+  return 9;
+}
+small(10);
+`,
+    expectOk: false,
+    expectCode: "nudo:constraint-violated",
+  },
+  // --- 真阴性：不得误报（clamp / 无前置） ---
+  {
+    name: "clamp negative input is not violation",
+    source: `
+function clamp(n, lo, hi) {
+  if (n < lo) return lo;
+  if (n > hi) return hi;
+  return n;
+}
+clamp(-5, 0, 100);
+`,
+    expectOk: true,
+  },
+  {
+    name: "no guard no constraint",
+    source: `
+function double(n) { return n * 2; }
+double(-1);
+`,
+    expectOk: true,
+  },
+  {
+    name: "equality guard is not numeric precondition",
+    source: `
+function onlyZero(x) {
+  if (x === 0) return 0;
+  return 1;
+}
+onlyZero(5);
+`,
+    expectOk: true,
+  },
+  {
+    name: "min boundary valid",
+    source: `
+function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+needsPositive(1);
+`,
+    expectOk: true,
+  },
+  // --- 结构 ---
+  {
+    name: "arrow function constraint",
+    source: `
+/**
+ * @nudo:refine x positive
+ */
+const needsPositive = (x) => {
+  if (x > 0) return x;
+  return 0;
+};
+needsPositive(-2);
+`,
+    expectOk: false,
+    expectCode: "nudo:constraint-violated",
+  },
+  {
+    name: "export default function",
+    source: `
+/**
+ * @nudo:refine x positive
+ */
+export default function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+needsPositive(-1);
+`,
+    expectOk: false,
+    expectCode: "nudo:constraint-violated",
+  },
+  {
+    name: "both bounds mid valid",
+    source: `
+/**
+ * @nudo:refine n percent
+ */
+function pct(n) {
+  if (n >= 0 && n <= 100) return n;
+  return 0;
+}
+pct(50);
+`,
+    expectOk: true,
+  },
+  {
+    name: "both bounds high invalid",
+    source: `
+/**
+ * @nudo:refine n percent
+ */
+function pct(n) {
+  if (n >= 0 && n <= 100) return n;
+  return 0;
+}
+pct(150);
+`,
+    expectOk: false,
+    expectCode: "nudo:constraint-violated",
+  },
+];
+
+describe("nudo check gold standards", () => {
+  for (const g of golds) {
+    it(g.name, () => {
+      const report = checkSource("gold.js", withStdImport(g.source), pTrue, stdOpts);
+      expect(report.ok, formatIssues(report)).toBe(g.expectOk);
+      if (g.expectCode) {
+        expect(
+          report.issues.some((i) => i.code === g.expectCode),
+          formatIssues(report),
+        ).toBe(true);
+      }
+      // 每个 case 至少能列出函数或明确无函数
+      expect(Array.isArray(report.signatures)).toBe(true);
+    });
+  }
+});
+
+function formatIssues(r: { issues: Array<{ severity: string; code: string; message: string }> }): string {
+  return r.issues.map((i) => `${i.severity} ${i.code}: ${i.message}`).join("; ") || "(none)";
+}

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

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { checkSource, serializeCheckJson, pTrue } from "../index.ts";
+import { withStdImport, stdOpts } from "./nudo-constraints.ts";
+
+describe("CheckJson contract v1", () => {
+  const src = `
+/**
+ * @nudo:refine x positive
+ */
+function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+needsPositive(-1);
+`;
+
+  it("has stable top-level fields", () => {
+    const j = serializeCheckJson(checkSource("c.js", withStdImport(src), pTrue, stdOpts));
+    expect(j.version).toBe(1);
+    expect(j.file).toBe("c.js");
+    expect(j.ok).toBe(false);
+    expect(j.summary).toMatchObject({
+      errors: expect.any(Number),
+      warnings: expect.any(Number),
+      infos: expect.any(Number),
+      functions: expect.any(Number),
+    });
+    expect(Array.isArray(j.signatures)).toBe(true);
+    expect(Array.isArray(j.issues)).toBe(true);
+  });
+
+  it("signatures carry abs display + detail", () => {
+    const j = serializeCheckJson(checkSource("c.js", withStdImport(src), pTrue, stdOpts));
+    const sig = j.signatures.find((s) => s.name === "needsPositive");
+    expect(sig).toBeDefined();
+    expect(sig!.params).toEqual(["x"]);
+    expect(sig!.abs).toContain("#");
+    expect(typeof sig!.conf).toBe("string");
+  });
+
+  it("issues carry actual/expected for violations", () => {
+    const j = serializeCheckJson(checkSource("c.js", withStdImport(src), pTrue, stdOpts));
+    const err = j.issues.find((i) => i.code === "nudo:constraint-violated");
+    expect(err).toBeDefined();
+    expect(err!.actual).toBeDefined();
+    expect(err!.expected).toBeDefined();
+    expect(err!.line).toBeGreaterThan(0);
+  });
+
+  it("ok file has ok:true and empty error issues", () => {
+    const j = serializeCheckJson(
+      checkSource("ok.js", `function f(x){ return x+1; }\nf(1);\n`, pTrue, stdOpts),
+    );
+    expect(j.ok).toBe(true);
+    expect(j.issues.filter((i) => i.severity === "error")).toEqual([]);
+  });
+});

package/src/algebra/__tests__/check-mini-repo.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkSource, pTrue } from "../index.ts";
+import { withStdImport, stdOpts } from "./nudo-constraints.ts";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../../../../../");
+const mini = (f: string) => readFileSync(resolve(root, "docs/examples/mini-repo", f), "utf8");
+
+/**
+ * mini-repo 人工金标：文件级 check 期望。
+ * 这是「替换 tsc」的 recall 基线——新增违例模式时先补这里。
+ */
+describe("mini-repo check gold", () => {
+  it("validators.js: no false positives", () => {
+    const r = checkSource("validators.js", mini("validators.js"));
+    expect(r.ok, r.issues.map((i) => i.message).join("; ")).toBe(true);
+    expect(r.signatures.map((f) => f.name)).toContain("isPositive");
+    expect(r.signatures.map((f) => f.name)).toContain("clamp");
+  });
+
+  it("store.js: class methods listed", () => {
+    const r = checkSource("store.js", mini("store.js"));
+    expect(r.ok).toBe(true);
+  });
+
+  it("user-service.js: ok (no literal violating calls)", () => {
+    const r = checkSource("user-service.js", mini("user-service.js"));
+    expect(r.ok, r.issues.map((i) => `${i.severity} ${i.message}`).join("; ")).toBe(true);
+  });
+
+  it("inline violating snippet still caught (TP recall)", () => {
+    // isPositive 是谓词（无 if-return-param 前置）；真正门禁用 refine
+    const src = `
+/**
+ * @nudo:refine x positive
+ */
+function needsPositive(x) {
+  if (x > 0) return x;
+  return 0;
+}
+needsPositive(-1);
+`;
+    const r = checkSource("tp.js", withStdImport(src), pTrue, stdOpts);
+    expect(r.ok).toBe(false);
+    expect(r.issues.some((i) => i.code === "nudo:constraint-violated")).toBe(true);
+  });
+});

package/src/algebra/__tests__/check-real-commander.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkSource } from "../index.ts";
+
+/**
+ * 真实包精度门禁：commander（devDep）上不得出现任何 error 级误报。
+ * 包不存在时跳过（非 monorepo 环境）。
+ */
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../../../../..");
+const commanderLib = join(root, "node_modules/commander/lib");
+
+const ERROR_CODES = [
+  "nudo:constraint-violated",
+  "nudo:assign-mismatch",
+  "nudo:arg-structure",
+] as const;
+
+describe("real package precision (commander)", () => {
+  const hasPkg = existsSync(commanderLib);
+
+  it.runIf(hasPkg)("no false-positive errors (constraint / assign / arg-structure)", () => {
+    const files = readdirSync(commanderLib).filter((f) => f.endsWith(".js"));
+    expect(files.length).toBeGreaterThan(0);
+
+    const violations: string[] = [];
+    let scanned = 0;
+    for (const f of files) {
+      const source = readFileSync(join(commanderLib, f), "utf8");
+      const r = checkSource(`commander/${f}`, source);
+      scanned++;
+      for (const i of r.issues) {
+        if (i.severity === "error" && (ERROR_CODES as readonly string[]).includes(i.code)) {
+          violations.push(`commander/${f}:${i.line ?? "?"} [${i.code}] ${i.message}`);
+        }
+      }
+    }
+    expect(scanned).toBeGreaterThan(3);
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
+});

package/src/algebra/__tests__/check-real-packages.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { checkSource } from "../index.ts";
+
+/**
+ * 真实包精度门禁：error 级误报必须为 0。
+ * 包不存在时跳过（非 monorepo / 未装依赖）。
+ */
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "../../../../..");
+const require = createRequire(import.meta.url);
+
+const ERROR_CODES = [
+  "nudo:constraint-violated",
+  "nudo:assign-mismatch",
+  "nudo:arg-structure",
+  "nudo:case-inconsistency",
+] as const;
+
+function pkgJsFiles(pkgName: string): { label: string; source: string }[] {
+  let pkgRoot: string | undefined;
+  // 先试 package.json；exports 未暴露时从主入口反推
+  try {
+    pkgRoot = dirname(require.resolve(`${pkgName}/package.json`));
+  } catch {
+    try {
+      let p = require.resolve(pkgName);
+      // 主入口可能在 lib/ 或 src/；向上找到含 package.json 的目录
+      for (let i = 0; i < 4; i++) {
+        const parent = dirname(p);
+        if (existsSync(join(parent, "package.json"))) {
+          pkgRoot = parent;
+          break;
+        }
+        p = parent;
+      }
+    } catch {
+      return [];
+    }
+  }
+  if (!pkgRoot) return [];
+  const out: { label: string; source: string }[] = [];
+  const walk = (dir: string): void => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name === "node_modules" || e.name.startsWith(".") || e.name === "tests" || e.name === "typings") continue;
+      const p = join(dir, e.name);
+      if (e.isDirectory()) {
+        walk(p);
+      } else if (/\.(mjs|cjs)$/.test(e.name) || e.name.endsWith(".js")) {
+        try {
+          out.push({
+            label: `${pkgName}/${p.slice(pkgRoot!.length + 1)}`,
+            source: readFileSync(p, "utf8"),
+          });
+        } catch {
+          // skip
+        }
+      }
+    }
+  };
+  walk(pkgRoot);
+  return out;
+}
+
+function scanPackage(pkgName: string): { scanned: number; violations: string[] } {
+  const files = pkgJsFiles(pkgName);
+  const violations: string[] = [];
+  let scanned = 0;
+  for (const { label, source } of files) {
+    let r;
+    try {
+      r = checkSource(label, source);
+    } catch {
+      continue;
+    }
+    scanned++;
+    for (const i of r.issues) {
+      if (i.severity === "error" && (ERROR_CODES as readonly string[]).includes(i.code)) {
+        violations.push(`${label}:${i.line ?? "?"} [${i.code}] ${i.message}`);
+      }
+    }
+  }
+  return { scanned, violations };
+}
+
+describe("real package precision", () => {
+  it.runIf(existsSync(join(root, "node_modules/commander/lib")))(
+    "commander: no false-positive errors",
+    () => {
+      const { scanned, violations } = scanPackage("commander");
+      expect(scanned).toBeGreaterThan(3);
+      expect(violations, violations.join("\n")).toEqual([]);
+    },
+  );
+
+  it("escape-string-regexp: no false-positive errors", () => {
+    const { scanned, violations } = scanPackage("escape-string-regexp");
+    expect(scanned).toBeGreaterThan(0);
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
+
+  it("is-plain-obj: no false-positive errors", () => {
+    const { scanned, violations } = scanPackage("is-plain-obj");
+    expect(scanned).toBeGreaterThan(0);
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
+
+  it("debug: no false-positive errors", () => {
+    const { scanned, violations } = scanPackage("debug");
+    expect(scanned).toBeGreaterThan(0);
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
+
+  it("yocto-queue (class): no false-positive errors", () => {
+    const { scanned, violations } = scanPackage("yocto-queue");
+    expect(scanned).toBeGreaterThan(0);
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
+
+  it("p-limit: no false-positive errors", () => {
+    const { scanned, violations } = scanPackage("p-limit");
+    expect(scanned).toBeGreaterThan(0);
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
+
+  it("kleur: no false-positive errors", () => {
+    const { scanned, violations } = scanPackage("kleur");
+    expect(scanned).toBeGreaterThan(0);
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
+
+  it("eventemitter3: no false-positive errors", () => {
+    const { scanned, violations } = scanPackage("eventemitter3");
+    expect(scanned).toBeGreaterThan(0);
+    expect(violations, violations.join("\n")).toEqual([]);
+  });
+
+  it.runIf(existsSync(join(root, "node_modules/ms")))(
+    "ms: no false-positive errors",
+    () => {
+      const { scanned, violations } = scanPackage("ms");
+      expect(scanned).toBeGreaterThan(0);
+      expect(violations, violations.join("\n")).toEqual([]);
+    },
+  );
+
+  it.runIf(existsSync(join(root, "node_modules/lodash")))(
+    "lodash: no false-positive errors",
+    () => {
+      const { scanned, violations } = scanPackage("lodash");
+      // lodash 体积大：至少扫到一批入口文件
+      expect(scanned).toBeGreaterThan(5);
+      expect(violations, violations.join("\n").slice(0, 2000)).toEqual([]);
+    },
+  );
+});