@nudojs/core 1.13.0 → 1.14.1

package/dist/{chunk-V2XC3V72.js → chunk-4GZPH6YL.js}

@@ -47,7 +47,7 @@ import {
   withEvalBudgetOverride,
   withExecPhi,
   withFnBudgetOverride
-} from "./chunk-A2PLG2QV.js";
+} from "./chunk-JMOQEJTD.js";
 
 // src/algebra/directive-scan.ts
 function cleanDirectiveLine(raw, kind) {
@@ -622,6 +622,14 @@ function scanAssumeSegments(lines) {
   }
   return out;
 }
+function scanInvariantSegments(lines) {
+  const out = [];
+  for (const line of lines) {
+    const m = line.match(/^@nudo:invariant\s+(.+)$/);
+    if (m) out.push(m[1].trim().replace(/\*\/$/, "").trim());
+  }
+  return out;
+}
 function scanThrowsDecl(lines) {
   const kinds = /* @__PURE__ */ new Set();
   let any = false;
@@ -1516,6 +1524,35 @@ function extractAssumeSegs(source, fnName) {
   }
   return out;
 }
+var INVARIANT_SEG_REGEX = /^([A-Za-z_$][\w$]*)((?:\[\*\]|\.[A-Za-z_$][\w$]*)*)\s*(>=|<=|>|<)\s*(-?\d+(?:\.\d+)?)$/;
+function extractInvariantSegs(source, fnName) {
+  if (!stripStringsKeepComments(source).includes("@nudo:invariant")) return [];
+  const out = [];
+  for (const seg of scanInvariantSegments(fnDirectiveCommentLines(source, fnName))) {
+    const m = seg.match(INVARIANT_SEG_REGEX);
+    if (!m) {
+      out.push({ kind: "bad", raw: seg });
+      continue;
+    }
+    const pathStr = m[2] ?? "";
+    const path = [];
+    for (const pm of pathStr.matchAll(/\[\*\]|\.[A-Za-z_$][\w$]*/g)) {
+      const t = pm[0];
+      if (t === "[*]") path.push({ k: "idx" });
+      else path.push({ k: "prop", name: t.slice(1) });
+    }
+    const relTxt = m[3];
+    out.push({
+      kind: "ok",
+      name: m[1],
+      path,
+      rel: relTxt === ">=" ? "ge" : relTxt === "<=" ? "le" : relTxt === ">" ? "gt" : "lt",
+      value: Number(m[4]),
+      display: `${m[1]}${pathStr} ${relTxt} ${m[4]}`
+    });
+  }
+  return out;
+}
 function fnTopLevelLocalNames(body) {
   const block = body;
   if (!block || block.type !== "BlockStatement" || !Array.isArray(block.body)) return [];
@@ -5533,6 +5570,395 @@ function scanLiteralCalls(source, knownFns, phi, opts) {
   return out;
 }
 
+// src/algebra/check-report.ts
+function actionsForIssue(i) {
+  const draft = {
+    kind: "draft",
+    command: "nudo contract --draft",
+    label: "emit a sidecar draft you can edit"
+  };
+  switch (i.code) {
+    case "nudo:constraint-violated":
+      return [
+        {
+          kind: "callsite",
+          label: "use a value satisfying the constraint",
+          ...i.expected ? { hint: i.expected } : {}
+        },
+        {
+          kind: "relax",
+          label: "relax the precondition (edit *.nudo.js / @nudo:contract)",
+          ...i.expected ? { hint: i.expected } : {}
+        },
+        draft
+      ];
+    case "nudo:assign-mismatch":
+      return [
+        {
+          kind: "callsite",
+          label: "align the assigned value with the existing shape",
+          ...i.expected ? { hint: i.expected } : {}
+        },
+        draft
+      ];
+    case "nudo:entry-may-throw":
+      return [
+        {
+          kind: "draft",
+          command: "nudo contract --draft",
+          label: "narrow the entry with a sidecar fn({ \u2026 }) param contract \u2014 most honest fix for helpers (also tightens the signature)",
+          ...i.fn ? { hint: i.fn } : {}
+        },
+        {
+          kind: "relax",
+          label: "declare intentional fail-fast: @nudo:throws Error (or case `!! throws`)",
+          ...i.fn ? { hint: i.fn } : {}
+        },
+        {
+          kind: "info",
+          label: "or refine / guard / try-catch the entry so it is total"
+        },
+        {
+          kind: "ignore-throws",
+          command: "nudo check --ignore-throws TypeError",
+          label: "migration switch: ignore this throw class on L2"
+        }
+      ];
+    case "nudo:unproven-return":
+      return [
+        {
+          kind: "relax",
+          label: `relax the return contract${i.fn ? ` of ${i.fn}` : ""} to the inferred surface (review the diff \u2014 not a silent green)`,
+          ...i.expected ? { hint: i.expected } : {}
+        },
+        draft,
+        {
+          kind: "info",
+          label: "or narrow the return expression / add a precondition so the bound is implied"
+        }
+      ];
+    case "nudo:unknown-inference":
+    case "nudo:opaque-result":
+      return [
+        { kind: "mock", label: "pin the native/unknown face with @nudo:mock" },
+        { kind: "assume", command: "nudo check --assume", label: "state preconditions via --assume" },
+        { kind: "info", label: "or add a call site / @nudo:case for evidence" }
+      ];
+    case "nudo:arg-opaque":
+    case "nudo:constraint-unproven":
+      return [
+        { kind: "assume", command: "nudo check --assume", label: "state preconditions via --assume" },
+        { kind: "info", label: "add a call site or @nudo:case" }
+      ];
+    case "nudo:fork-truncated":
+    case "nudo:promise-micro-truncated":
+    case "nudo:promise-micro-error":
+      return [
+        {
+          kind: "info",
+          label: "results widened to unknown \u2014 raise budget (@nudo:budget forks/calls/depth on the function) or narrow control flow"
+        }
+      ];
+    case "nudo:loop-truncated":
+      return [
+        {
+          kind: "info",
+          label: "loop state widened \u2014 the exit condition stayed concrete-true past the iteration cap; make the bound data-dependent (abstract) or pin the result with @nudo:case / @nudo:contract"
+        }
+      ];
+    case "nudo:recursion-truncated":
+      return [
+        {
+          kind: "info",
+          label: i.reason === "cycle" ? "call cycle: same abstract arguments already on the stack \u2014 raising @nudo:budget cannot lift it; make the arguments vary per recursion level or declare @nudo:contract" : i.reason === "depth" || i.reason === "calls" || i.reason === "budget" ? `results widened to unknown \u2014 raise budget (@nudo:budget ${i.reason === "depth" ? "depth" : i.reason === "calls" ? "calls" : "calls/depth"} on the function) or narrow the recursion` : "results widened to unknown \u2014 raise budget (@nudo:budget calls/depth on the function) or narrow control flow"
+        }
+      ];
+    case "nudo:host-effect-blocked":
+      return [
+        { kind: "mock", label: "pin the host API with @nudo:mock / @nudo:env" },
+        { kind: "info", label: "results widened to unknown \u2014 or feed the value in from a call site" }
+      ];
+    case "nudo:interface-drift":
+      return [
+        {
+          kind: "emit",
+          command: "nudo contract --emit",
+          label: "refresh the @generated segment"
+        }
+      ];
+    case "nudo:dual-entry":
+      return [
+        {
+          kind: "info",
+          label: "browser/node records do not cross files \u2014 analyze the entry you ship; mock or skip the other variant"
+        }
+      ];
+    default:
+      return i.suggestion ? [{ kind: "info", label: i.suggestion }] : [];
+  }
+}
+function serializeCheckJson(r) {
+  return {
+    version: 1,
+    file: r.file,
+    ok: r.ok,
+    summary: { ...r.summary },
+    signatures: r.signatures.map((s) => ({
+      name: s.name,
+      params: [...s.params],
+      ...s.paramTypes ? { paramTypes: [...s.paramTypes] } : {},
+      display: s.display,
+      detail: s.detail,
+      conf: s.conf,
+      abs: formatAbs(s.abs),
+      ...s.throws ? { throws: s.throws } : {},
+      ...s.entry ? { entry: true } : {}
+    })),
+    issues: r.issues.map((i) => {
+      const acts = i.actions ?? actionsForIssue(i);
+      return {
+        severity: i.severity,
+        code: i.code,
+        message: i.message,
+        ...i.fn !== void 0 ? { fn: i.fn } : {},
+        ...i.line !== void 0 ? { line: i.line } : {},
+        ...i.column !== void 0 ? { column: i.column } : {},
+        ...i.actual !== void 0 ? { actual: i.actual } : {},
+        ...i.expected !== void 0 ? { expected: i.expected } : {},
+        ...i.suggestion !== void 0 ? { suggestion: i.suggestion } : {},
+        ...i.reason !== void 0 ? { reason: i.reason } : {},
+        ...acts.length > 0 ? { actions: acts } : {}
+      };
+    }),
+    ...r.budget ? { budget: { ...r.budget } } : {}
+  };
+}
+function serializeCheckJsonMulti(reports) {
+  const summary = {
+    errors: 0,
+    warnings: 0,
+    infos: 0,
+    functions: 0,
+    files: reports.length
+  };
+  let calls = 0;
+  let forks = 0;
+  let maxCalls = 0;
+  let maxForks = 0;
+  let callTruncated = false;
+  let forkTruncated = false;
+  let evalCalls = 0;
+  let maxEvalCalls = 0;
+  let evalCallTruncated = false;
+  let cycleTruncated = false;
+  let loopTruncated = false;
+  const callReasons = /* @__PURE__ */ new Set();
+  const evalReasons = /* @__PURE__ */ new Set();
+  let depth = 0;
+  let maxDepth = 0;
+  let evalDepth = 0;
+  let maxEvalDepth = 0;
+  const reasons = /* @__PURE__ */ new Set();
+  for (const r of reports) {
+    summary.errors += r.summary.errors;
+    summary.warnings += r.summary.warnings;
+    summary.infos += r.summary.infos;
+    summary.functions += r.summary.functions;
+    if (r.budget) {
+      calls += r.budget.calls;
+      forks += r.budget.forks;
+      maxCalls = Math.max(maxCalls, r.budget.maxCalls);
+      maxForks = Math.max(maxForks, r.budget.maxForks);
+      callTruncated = callTruncated || r.budget.callTruncated;
+      forkTruncated = forkTruncated || r.budget.forkTruncated;
+      evalCalls += r.budget.evalCalls ?? 0;
+      maxEvalCalls = Math.max(maxEvalCalls, r.budget.maxEvalCalls ?? 0);
+      evalCallTruncated = evalCallTruncated || (r.budget.evalCallTruncated ?? false);
+      cycleTruncated = cycleTruncated || (r.budget.cycleTruncated ?? false);
+      loopTruncated = loopTruncated || (r.budget.loopTruncated ?? false);
+      for (const x of r.budget.callReasons ?? []) callReasons.add(x);
+      for (const x of r.budget.evalReasons ?? []) evalReasons.add(x);
+      depth = Math.max(depth, r.budget.depth ?? 0);
+      maxDepth = Math.max(maxDepth, r.budget.maxDepth ?? 0);
+      evalDepth = Math.max(evalDepth, r.budget.evalDepth ?? 0);
+      maxEvalDepth = Math.max(maxEvalDepth, r.budget.maxEvalDepth ?? 0);
+      for (const x of r.budget.reasons ?? []) reasons.add(x);
+    }
+  }
+  const budgetTruncated = callTruncated || evalCallTruncated || forkTruncated || loopTruncated;
+  return {
+    version: 1,
+    kind: "multi",
+    ok: reports.every((r) => r.ok),
+    summary: {
+      ...summary,
+      ...budgetTruncated ? { budgetTruncated: true } : {}
+    },
+    ...budgetTruncated || reports.some((r) => r.budget) ? {
+      budget: {
+        truncated: budgetTruncated,
+        callTruncated,
+        forkTruncated,
+        calls,
+        maxCalls,
+        forks,
+        maxForks,
+        evalCalls,
+        maxEvalCalls,
+        evalCallTruncated,
+        cycleTruncated,
+        loopTruncated,
+        callReasons: [...callReasons].sort(),
+        depth,
+        maxDepth,
+        evalReasons: [...evalReasons].sort(),
+        evalDepth,
+        maxEvalDepth,
+        reasons: [...reasons].sort()
+      }
+    } : {},
+    reports
+  };
+}
+var CONTRACT_FIX_CODES = /* @__PURE__ */ new Set([
+  "nudo:constraint-violated",
+  "nudo:assign-mismatch",
+  "nudo:arg-structure",
+  "nudo:interface-domain-exceeds",
+  "nudo:entry-may-throw",
+  "nudo:missing-slot"
+]);
+function budgetAttributionSegs(b) {
+  const segs = [];
+  if ((b.callReasons ?? []).includes("calls")) segs.push(`calls ${b.calls}/${b.maxCalls}`);
+  if ((b.callReasons ?? []).includes("depth")) segs.push(`call depth ${b.depth}/${b.maxDepth}`);
+  if ((b.evalReasons ?? []).includes("calls")) {
+    segs.push(`eval calls ${b.evalCalls}/${b.maxEvalCalls}`);
+  }
+  if ((b.evalReasons ?? []).includes("depth")) {
+    segs.push(`eval depth ${b.evalDepth}/${b.maxEvalDepth}`);
+  }
+  if (b.forkTruncated) segs.push(`forks ${b.forks}/${b.maxForks}`);
+  if (b.loopTruncated) segs.push("loop iterations");
+  const cycleOnly = segs.length === 0;
+  if (cycleOnly) segs.push("call cycle \u2014 not a budget limit");
+  return { segs, cycleOnly };
+}
+function formatCheckReport(r, opts = {}) {
+  const lines = [];
+  lines.push(`nudo check  ${r.file}`);
+  lines.push(r.ok ? "OK" : "FAILED");
+  lines.push(
+    `  ${r.summary.errors} error \xB7 ${r.summary.warnings} warning \xB7 ${r.summary.infos} info \xB7 ${r.summary.functions} fn`
+  );
+  if (r.budget?.truncated) {
+    const b = r.budget;
+    const onlyLoop = b.loopTruncated && !b.callTruncated && !b.evalCallTruncated && !b.forkTruncated;
+    const { segs } = budgetAttributionSegs(b);
+    lines.push("");
+    lines.push("budget");
+    lines.push(`  truncated  ${segs.join(" \xB7 ")}`);
+    lines.push(
+      r.budget.cycleTruncated ? `  \u2192 some results widened to unknown (not a contract failure) \u2014 includes call cycles (same abstract args; a budget cannot lift them)` : onlyLoop ? `  \u2192 loop state widened (iteration budget, not a contract failure) \u2014 @nudo:budget does not apply; make the bound data-dependent or pin with @nudo:case / @nudo:contract` : `  \u2192 some results widened to unknown (not a contract failure) \u2014 raise @nudo:budget / nudo.analysis.maxForks or simplify recursion`
+    );
+  }
+  if (r.signatures.length > 0) {
+    lines.push("");
+    lines.push("signatures");
+    for (const s of r.signatures) {
+      const paramStr = s.paramTypes && s.paramTypes.length > 0 ? s.params.map((p, i) => `${p}: ${s.paramTypes[i] ?? "any"}`).join(", ") : s.params.join(", ");
+      const throwsStr = s.throws ? `  throws ${s.throws}` : "";
+      const displayBase = s.display.replace(/\s+throws\s+[\s\S]+$/, "").trim();
+      const shapeK = s.abs?.shape?.k;
+      const looksLikeFakeAny = shapeK === "any" && displayBase.length > 0 && !/^any(\b|$)/.test(displayBase);
+      const retStr = !looksLikeFakeAny && shapeK ? formatShape(s.abs) || displayBase.replace(/\s+#\w+$/, "").trim() : displayBase.replace(/\s+#\w+$/, "").trim();
+      lines.push(`  ${s.name}(${paramStr}) => ${retStr}${throwsStr}`);
+      if (opts.verbose) {
+        for (const ln of s.detail.split("\n").slice(1)) {
+          lines.push(`  ${ln}`);
+        }
+      }
+    }
+  }
+  if (r.issues.length === 0) {
+    lines.push("");
+    lines.push("(no issues)");
+  } else {
+    lines.push("");
+    lines.push("issues");
+    for (const i of r.issues) {
+      const loc = i.line != null ? `L${i.line}` : "";
+      const head = [i.severity.toUpperCase(), loc, i.fn].filter(Boolean).join(" ");
+      lines.push(`  [${head}] ${i.message}  (${i.code})`);
+      const showDetail = i.severity === "error" || opts.verbose;
+      if (showDetail && i.actual) lines.push(`      actual:   ${i.actual}`);
+      if (showDetail && i.expected) lines.push(`      expected: ${i.expected}`);
+      if (i.suggestion) {
+        lines.push(`      \u2192 ${i.suggestion}`);
+      } else if (CONTRACT_FIX_CODES.has(i.code)) {
+        lines.push(`      \u2192 add a refine / sidecar contract, or fix the call-site value`);
+      }
+      if (CONTRACT_FIX_CODES.has(i.code)) {
+        lines.push(`      fix:  nudo contract --draft  (emit a sidecar draft you can edit)`);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function escapeGhaData(s) {
+  return s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function escapeGhaProp(s) {
+  return escapeGhaData(s).replace(/:/g, "%3A").replace(/,/g, "%2C");
+}
+function formatGithubAnnotations(r, opts = {}) {
+  const lines = [];
+  let file = r.file;
+  if (opts.workspaceRoot && file.startsWith(opts.workspaceRoot)) {
+    file = file.slice(opts.workspaceRoot.length).replace(/^[/\\]/, "");
+  }
+  for (const i of r.issues) {
+    const level = i.severity === "error" ? "error" : i.severity === "warning" ? "warning" : "notice";
+    const line = i.line ?? 1;
+    const col = (i.column ?? 0) + 1;
+    const title = escapeGhaProp(i.code);
+    const msgBits = [i.message];
+    if (i.actual && i.expected) msgBits.push(`${i.actual} \u22AD ${i.expected}`);
+    else if (i.suggestion) msgBits.push(i.suggestion);
+    if (CONTRACT_FIX_CODES.has(i.code)) {
+      msgBits.push(`fix: nudo contract --draft`);
+    }
+    const msg = escapeGhaData(msgBits.join(" \xB7 "));
+    const props = [
+      `file=${escapeGhaProp(file)}`,
+      `line=${line}`,
+      `col=${col}`,
+      `title=${title}`
+    ].join(",");
+    lines.push(`::${level} ${props}::${msg}`);
+  }
+  return lines.join("\n");
+}
+function formatGitlabCodeQuality(r, opts = {}) {
+  let file = r.file;
+  if (opts.workspaceRoot && file.startsWith(opts.workspaceRoot)) {
+    file = file.slice(opts.workspaceRoot.length).replace(/^[/\\]/, "");
+  }
+  return r.issues.map((i) => {
+    const begin = i.line ?? 1;
+    const severity = i.severity === "error" ? "major" : i.severity === "warning" ? "minor" : "info";
+    const description = i.actual && i.expected ? `${i.message} (${i.actual} \u22AD ${i.expected})` : i.message;
+    const fingerprint = `${file}:${i.code}:${begin}:${i.message}`;
+    return {
+      description,
+      check_name: i.code,
+      fingerprint,
+      severity,
+      location: { path: file, lines: { begin } }
+    };
+  });
+}
+
 export {
   listFnDirectiveScopes,
   findFnDirectiveScope,
@@ -5568,6 +5994,7 @@ export {
   execNudoModule,
   resetNudoModuleExecCache,
   extractAssumeSegs,
+  extractInvariantSegs,
   fnTopLevelLocalNames,
   extractRefinesFromSource,
   refineToIndexedFull,
@@ -5610,5 +6037,12 @@ export {
   stableAnalyzeKeySource,
   listTopFunctions,
   scanLiteralCalls,
-  checkInjectedDomainEvidence
+  checkInjectedDomainEvidence,
+  actionsForIssue,
+  serializeCheckJson,
+  serializeCheckJsonMulti,
+  budgetAttributionSegs,
+  formatCheckReport,
+  formatGithubAnnotations,
+  formatGitlabCodeQuality
 };