@fairfox/polly 0.76.0 → 0.77.1

package/dist/tools/verify/src/stryker/index.d.ts

@@ -0,0 +1,32 @@
+import type { Ignorer, NodePath } from "@stryker-mutator/api/ignore";
+import { PluginKind } from "@stryker-mutator/api/plugin";
+/**
+ * The polly verify primitives whose argument expressions are runtime no-ops.
+ * A mutation anywhere inside a call to one of these cannot be killed by a test,
+ * so its mutants are excluded from scoring.
+ */
+export declare const VERIFY_PRIMITIVES: ReadonlySet<string>;
+/** The Stryker plugin name consumers reference in `ignorers`. */
+export declare const POLLY_VERIFY_IGNORER_NAME = "polly-verify";
+/**
+ * A Stryker `Ignore` plugin. Stryker calls `shouldIgnore` on entering each AST
+ * node; returning a message marks that node — and every descendant, until the
+ * node is left — as ignored. So matching the verify `CallExpression` itself
+ * covers its condition and message arguments in one shot.
+ */
+export declare class PollyVerifyIgnorer implements Ignorer {
+    private readonly primitives;
+    constructor(primitives?: ReadonlySet<string>);
+    shouldIgnore(path: NodePath): string | undefined;
+}
+/** The plugin array Stryker reads when this module is listed in `plugins`. */
+export declare const strykerPlugins: import("@stryker-mutator/api/plugin").FactoryPlugin<PluginKind.Ignore, ["options"]>[];
+/**
+ * A partial Stryker config that wires up the ignorer. Spread it into a
+ * `stryker.conf.mjs` default export, or replicate its two keys in JSON.
+ */
+export declare const pollyStrykerPreset: {
+    readonly plugins: readonly ["@fairfox/polly/stryker"];
+    readonly ignorers: readonly ["polly-verify"];
+};
+export default pollyStrykerPreset;

package/dist/tools/verify/src/stryker/index.js

@@ -0,0 +1,95 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// tools/verify/src/stryker/index.ts
+import {
+  commonTokens,
+  declareFactoryPlugin,
+  PluginKind,
+  tokens
+} from "@stryker-mutator/api/plugin";
+var VERIFY_PRIMITIVES = new Set([
+  "requires",
+  "ensures",
+  "invariant",
+  "stateConstraint",
+  "forAllPeers",
+  "somePeer"
+]);
+var POLLY_VERIFY_IGNORER_NAME = "polly-verify";
+function calleeName(callee) {
+  if (!callee)
+    return;
+  if (callee.type === "Identifier") {
+    return callee.name;
+  }
+  if (callee.type === "MemberExpression") {
+    const member = callee;
+    if (!member.computed && member.property.type === "Identifier") {
+      return member.property.name;
+    }
+  }
+  return;
+}
+
+class PollyVerifyIgnorer {
+  primitives;
+  constructor(primitives = VERIFY_PRIMITIVES) {
+    this.primitives = primitives;
+  }
+  shouldIgnore(path) {
+    const callPath = path;
+    if (typeof callPath.isCallExpression !== "function" || !callPath.isCallExpression()) {
+      return;
+    }
+    const name = calleeName(callPath.node.callee);
+    if (name && this.primitives.has(name)) {
+      return `Inside polly's ${name}(...) — a runtime no-op (compiled away in production, ` + `translated to a TLA+ assertion in verification). No test can observe or kill ` + `mutations here, so they are excluded from the score (polly#143).`;
+    }
+    return;
+  }
+}
+function isEnabled(options) {
+  const polly = options.polly;
+  return polly?.excludeVerifyCallsites !== false;
+}
+var NOOP_IGNORER = { shouldIgnore: () => {
+  return;
+} };
+function pollyVerifyIgnorerFactory(options) {
+  return isEnabled(options) ? new PollyVerifyIgnorer : NOOP_IGNORER;
+}
+pollyVerifyIgnorerFactory.inject = tokens(commonTokens.options);
+var strykerPlugins = [
+  declareFactoryPlugin(PluginKind.Ignore, POLLY_VERIFY_IGNORER_NAME, pollyVerifyIgnorerFactory)
+];
+var pollyStrykerPreset = {
+  plugins: ["@fairfox/polly/stryker"],
+  ignorers: [POLLY_VERIFY_IGNORER_NAME]
+};
+var stryker_default = pollyStrykerPreset;
+export {
+  strykerPlugins,
+  pollyStrykerPreset,
+  stryker_default as default,
+  VERIFY_PRIMITIVES,
+  PollyVerifyIgnorer,
+  POLLY_VERIFY_IGNORER_NAME
+};
+
+//# debugId=D1E2AADE2B7A729B64756E2164756E21

package/dist/tools/verify/src/stryker/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../tools/verify/src/stryker/index.ts"],
+  "sourcesContent": [
+    "// Stryker mutation-testing ignorer for polly's verify primitives (polly#143).\n//\n// `requires`, `ensures`, `invariant`, `stateConstraint`, `forAllPeers`, and\n// `somePeer` are runtime no-ops: in production they compile away, in\n// verification they translate to TLA+ assertions. Nothing observes their\n// condition or message argument at test runtime, so EVERY mutation inside one\n// of these callsites is guaranteed to survive — a string-literal flip in an\n// `ensures(...)` message, an `===` → equality mutation in a `requires(...)`\n// condition. On a downstream project mutating six state-machine specs this\n// dragged the mutation score down to 21%, all of it noise rather than real\n// test-coverage gaps.\n//\n// Polly is the right place to ship this knowledge: it knows which of its\n// primitives are no-ops. This module is a Stryker `Ignore` plugin that marks\n// every mutant inside a verify callsite as ignored, plus a small config preset\n// consumers can spread into their `stryker.conf.*`.\n//\n// Usage (stryker.conf.json):\n//\n//   {\n//     \"plugins\": [\"@fairfox/polly/stryker\"],\n//     \"ignorers\": [\"polly-verify\"]\n//   }\n//\n// Or, in stryker.conf.mjs:\n//\n//   import pollyStrykerPreset from \"@fairfox/polly/stryker\";\n//   export default { ...pollyStrykerPreset, mutate: [\"src/**/*.ts\"] };\n//\n// Set `\"polly\": { \"excludeVerifyCallsites\": false }` to keep the plugin listed\n// but disable the ignoring (e.g. in a shared base config).\n\nimport type { StrykerOptions } from \"@stryker-mutator/api/core\";\nimport type { Ignorer, NodePath } from \"@stryker-mutator/api/ignore\";\nimport {\n  commonTokens,\n  declareFactoryPlugin,\n  PluginKind,\n  tokens,\n} from \"@stryker-mutator/api/plugin\";\n\n/**\n * The polly verify primitives whose argument expressions are runtime no-ops.\n * A mutation anywhere inside a call to one of these cannot be killed by a test,\n * so its mutants are excluded from scoring.\n */\nexport const VERIFY_PRIMITIVES: ReadonlySet<string> = new Set([\n  \"requires\",\n  \"ensures\",\n  \"invariant\",\n  \"stateConstraint\",\n  \"forAllPeers\",\n  \"somePeer\",\n]);\n\n/** The Stryker plugin name consumers reference in `ignorers`. */\nexport const POLLY_VERIFY_IGNORER_NAME = \"polly-verify\";\n\n// The Stryker API types `NodePath` as an empty interface; at runtime it is a\n// Babel NodePath. We narrow only the surface we touch — `isCallExpression()`\n// and `node.callee` — without pulling in @babel/types as a dependency.\ninterface BabelIdentifier {\n  type: \"Identifier\";\n  name: string;\n}\ninterface BabelMemberExpression {\n  type: \"MemberExpression\";\n  computed: boolean;\n  property: { type: string; name?: string };\n}\ntype BabelCallee = BabelIdentifier | BabelMemberExpression | { type: string };\ninterface CallExpressionPath extends NodePath {\n  isCallExpression(): boolean;\n  node: { callee?: BabelCallee };\n}\n\n/**\n * Resolve the simple name of a call's callee, covering both a bare call\n * (`ensures(...)`) and a member call (`verify.ensures(...)` / `polly.ensures(...)`).\n * Computed member access (`obj[\"ensures\"](...)`) is intentionally not matched —\n * it cannot be resolved statically and is not a pattern polly emits.\n */\nfunction calleeName(callee: BabelCallee | undefined): string | undefined {\n  if (!callee) return undefined;\n  if (callee.type === \"Identifier\") {\n    return (callee as BabelIdentifier).name;\n  }\n  if (callee.type === \"MemberExpression\") {\n    const member = callee as BabelMemberExpression;\n    if (!member.computed && member.property.type === \"Identifier\") {\n      return member.property.name;\n    }\n  }\n  return undefined;\n}\n\n/**\n * A Stryker `Ignore` plugin. Stryker calls `shouldIgnore` on entering each AST\n * node; returning a message marks that node — and every descendant, until the\n * node is left — as ignored. So matching the verify `CallExpression` itself\n * covers its condition and message arguments in one shot.\n */\nexport class PollyVerifyIgnorer implements Ignorer {\n  constructor(private readonly primitives: ReadonlySet<string> = VERIFY_PRIMITIVES) {}\n\n  shouldIgnore(path: NodePath): string | undefined {\n    const callPath = path as CallExpressionPath;\n    if (typeof callPath.isCallExpression !== \"function\" || !callPath.isCallExpression()) {\n      return undefined;\n    }\n    const name = calleeName(callPath.node.callee);\n    if (name && this.primitives.has(name)) {\n      return (\n        `Inside polly's ${name}(...) — a runtime no-op (compiled away in production, ` +\n        `translated to a TLA+ assertion in verification). No test can observe or kill ` +\n        `mutations here, so they are excluded from the score (polly#143).`\n      );\n    }\n    return undefined;\n  }\n}\n\n/** Reads `polly.excludeVerifyCallsites` (default: enabled) off Stryker options. */\nfunction isEnabled(options: StrykerOptions): boolean {\n  const polly = (options as { polly?: { excludeVerifyCallsites?: boolean } }).polly;\n  return polly?.excludeVerifyCallsites !== false;\n}\n\n// When disabled the plugin still loads but ignores nothing, so a shared config\n// can list it unconditionally and individual projects opt out via options.\nconst NOOP_IGNORER: Ignorer = { shouldIgnore: () => undefined };\n\nfunction pollyVerifyIgnorerFactory(options: StrykerOptions): Ignorer {\n  return isEnabled(options) ? new PollyVerifyIgnorer() : NOOP_IGNORER;\n}\npollyVerifyIgnorerFactory.inject = tokens(commonTokens.options);\n\n/** The plugin array Stryker reads when this module is listed in `plugins`. */\nexport const strykerPlugins = [\n  declareFactoryPlugin(PluginKind.Ignore, POLLY_VERIFY_IGNORER_NAME, pollyVerifyIgnorerFactory),\n];\n\n/**\n * A partial Stryker config that wires up the ignorer. Spread it into a\n * `stryker.conf.mjs` default export, or replicate its two keys in JSON.\n */\nexport const pollyStrykerPreset = {\n  plugins: [\"@fairfox/polly/stryker\"],\n  ignorers: [POLLY_VERIFY_IGNORER_NAME],\n} as const;\n\n// biome-ignore lint/style/noDefaultExport: ergonomic `import preset from \"@fairfox/polly/stryker\"`\nexport default pollyStrykerPreset;\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;;;AAkCA;AAAA;AAAA;AAAA;AAAA;AAAA;AAYO,IAAM,oBAAyC,IAAI,IAAI;AAAA,EAC5D;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAGM,IAAM,4BAA4B;AA0BzC,SAAS,UAAU,CAAC,QAAqD;AAAA,EACvE,IAAI,CAAC;AAAA,IAAQ;AAAA,EACb,IAAI,OAAO,SAAS,cAAc;AAAA,IAChC,OAAQ,OAA2B;AAAA,EACrC;AAAA,EACA,IAAI,OAAO,SAAS,oBAAoB;AAAA,IACtC,MAAM,SAAS;AAAA,IACf,IAAI,CAAC,OAAO,YAAY,OAAO,SAAS,SAAS,cAAc;AAAA,MAC7D,OAAO,OAAO,SAAS;AAAA,IACzB;AAAA,EACF;AAAA,EACA;AAAA;AAAA;AASK,MAAM,mBAAsC;AAAA,EACpB;AAAA,EAA7B,WAAW,CAAkB,aAAkC,mBAAmB;AAAA,IAArD;AAAA;AAAA,EAE7B,YAAY,CAAC,MAAoC;AAAA,IAC/C,MAAM,WAAW;AAAA,IACjB,IAAI,OAAO,SAAS,qBAAqB,cAAc,CAAC,SAAS,iBAAiB,GAAG;AAAA,MACnF;AAAA,IACF;AAAA,IACA,MAAM,OAAO,WAAW,SAAS,KAAK,MAAM;AAAA,IAC5C,IAAI,QAAQ,KAAK,WAAW,IAAI,IAAI,GAAG;AAAA,MACrC,OACE,kBAAkB,+DAClB,kFACA;AAAA,IAEJ;AAAA,IACA;AAAA;AAEJ;AAGA,SAAS,SAAS,CAAC,SAAkC;AAAA,EACnD,MAAM,QAAS,QAA6D;AAAA,EAC5E,OAAO,OAAO,2BAA2B;AAAA;AAK3C,IAAM,eAAwB,EAAE,cAAc,MAAG;AAAA,EAAG;AAAA,EAAU;AAE9D,SAAS,yBAAyB,CAAC,SAAkC;AAAA,EACnE,OAAO,UAAU,OAAO,IAAI,IAAI,qBAAuB;AAAA;AAEzD,0BAA0B,SAAS,OAAO,aAAa,OAAO;AAGvD,IAAM,iBAAiB;AAAA,EAC5B,qBAAqB,WAAW,QAAQ,2BAA2B,yBAAyB;AAC9F;AAMO,IAAM,qBAAqB;AAAA,EAChC,SAAS,CAAC,wBAAwB;AAAA,EAClC,UAAU,CAAC,yBAAyB;AACtC;AAGA,IAAe;",
+  "debugId": "D1E2AADE2B7A729B64756E2164756E21",
+  "names": []
+}

package/dist/tools/visualize/src/cli.js

@@ -1810,7 +1810,7 @@ class HandlerExtractor {
           const exists = handlers.some((h) => h.messageType === handler.messageType && h.location.file === handler.location.file);
           if (!exists) {
             handlers.push(handler);
-            if (this.isValidTLAIdentifier(handler.messageType)) {
+            if (this.canRepresentAsTLAAction(handler.messageType)) {
               messageTypes.add(handler.messageType);
             } else {
               invalidMessageTypes.add(handler.messageType);
@@ -1920,7 +1920,7 @@ class HandlerExtractor {
       const syntheticHandlers = this.createResourceHandlers(resource, context);
       for (const handler of syntheticHandlers) {
         handlers.push(handler);
-        if (this.isValidTLAIdentifier(handler.messageType)) {
+        if (this.canRepresentAsTLAAction(handler.messageType)) {
           messageTypes.add(handler.messageType);
         } else {
           invalidMessageTypes.add(handler.messageType);
@@ -1982,7 +1982,7 @@ class HandlerExtractor {
   }
   categorizeHandlerMessageTypes(handlers, messageTypes, invalidMessageTypes) {
     for (const handler of handlers) {
-      if (this.isValidTLAIdentifier(handler.messageType)) {
+      if (this.canRepresentAsTLAAction(handler.messageType)) {
         messageTypes.add(handler.messageType);
       } else {
         invalidMessageTypes.add(handler.messageType);
@@ -1997,11 +1997,8 @@ class HandlerExtractor {
       console.log(`[DEBUG] Filtered ${invalidCount} invalid message type(s) from handlers`);
     }
   }
-  isValidTLAIdentifier(s) {
-    if (!s || s.length === 0) {
-      return false;
-    }
-    return /^[a-zA-Z][a-zA-Z0-9_]*$/.test(s);
+  canRepresentAsTLAAction(s) {
+    return typeof s === "string" && /[a-zA-Z]/.test(s) && !/[{}();<>=]/.test(s);
   }
   extractFromFile(sourceFile) {
     const handlers = [];
@@ -2684,8 +2681,20 @@ class HandlerExtractor {
     const paramName = this.extractPayloadPropertyParam(initializer);
     if (paramName !== null) {
       assignments.push({ field, value: `param:${paramName}` });
+      return;
+    }
+    if (this.isTranslatableInitializer(initializer)) {
+      assignments.push({ field, value: `EXPR:${initializer.getText()}` });
+      return;
+    }
+    if (process.env["POLLY_DEBUG"]) {
+      const on = signalName ? ` on ${signalName}.value` : "";
+      console.log(`[WARN] dropped object-literal property '${name}'${on} — initializer kind ${initializer.getKindName()} is not translatable to TLA+`);
     }
   }
+  isTranslatableInitializer(node) {
+    return Node4.isBinaryExpression(node) || Node4.isPropertyAccessExpression(node) || Node4.isElementAccessExpression(node) || Node4.isPrefixUnaryExpression(node) || Node4.isPostfixUnaryExpression(node) || Node4.isParenthesizedExpression(node);
+  }
   extractPayloadPropertyParam(initializer) {
     if (!Node4.isPropertyAccessExpression(initializer))
       return null;
@@ -6810,4 +6819,4 @@ main().catch((_error) => {
   process.exit(1);
 });
 
-//# debugId=4CFC761842CDF97B64756E2164756E21
+//# debugId=1DBE75DC4C8D1D6864756E2164756E21