@fairfox/polly 0.90.0 → 0.91.0

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

@@ -246,6 +246,21 @@ var init_expression_validator = __esm(() => {
 });
 
 // tools/verify/src/codegen/model-constants.ts
+function sanitizeContextName(name) {
+  return name.replace(/[^A-Za-z0-9_]/g, "_");
+}
+function hasDeclaredContexts(config) {
+  const declared = config?.contexts;
+  return Array.isArray(declared) && declared.length > 0;
+}
+function resolveContexts(config) {
+  if (!hasDeclaredContexts(config))
+    return [...DEFAULT_CONTEXTS];
+  return (config?.contexts).map(sanitizeContextName);
+}
+function targetSetCount(contexts) {
+  return 2 ** contexts.length - 1;
+}
 function hasProjectConstant(messages) {
   return messages.maxWorkers !== undefined || messages.maxRenderers !== undefined || messages.maxContexts !== undefined || messages.maxClients !== undefined;
 }
@@ -262,14 +277,13 @@ function generatedTabValues(messages) {
 function generatedTabCount(messages) {
   return generatedTabValues(messages).length;
 }
-function sendBranchingFactor(handlerCount, tabCount) {
-  return CONTEXT_COUNT * TARGET_SET_COUNT * tabCount * handlerCount;
+function sendBranchingFactor(handlerCount, tabCount, contexts) {
+  return contexts.length * targetSetCount(contexts) * tabCount * handlerCount;
 }
-var GENERATED_CONTEXTS, CONTEXT_COUNT, TARGET_SET_COUNT;
+var DEFAULT_CONTEXTS, CONTEXT_NAME_PATTERN;
 var init_model_constants = __esm(() => {
-  GENERATED_CONTEXTS = ["background", "content", "popup"];
-  CONTEXT_COUNT = GENERATED_CONTEXTS.length;
-  TARGET_SET_COUNT = 2 ** CONTEXT_COUNT - 1;
+  DEFAULT_CONTEXTS = ["background", "content", "popup"];
+  CONTEXT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 });
 
 // tools/verify/src/runner/memory.ts
@@ -1041,7 +1055,7 @@ var init_tla = __esm(() => {
       lines.push("CONSTANTS");
     }
     addBasicConstants(lines, config) {
-      lines.push(`  Contexts = {${GENERATED_CONTEXTS.join(", ")}}`);
+      lines.push(`  Contexts = {${resolveContexts(config).join(", ")}}`);
       lines.push(`  MaxMessages = ${config.messages.maxInFlight || 3}`);
       lines.push("  NULL = NULL");
       if (config.messages.perMessageBounds) {
@@ -1062,7 +1076,6 @@ var init_tla = __esm(() => {
         hasProjectConstant = true;
       }
       if ("maxContexts" in messages && messages.maxContexts !== undefined) {
-        lines.push(`  MaxContexts = ${messages.maxContexts}`);
         hasProjectConstant = true;
       }
       if ("maxClients" in messages && messages.maxClients !== undefined && !hasProjectConstant) {
@@ -3965,6 +3978,9 @@ function getTabSetInput(config) {
   }
   return {};
 }
+function getContextSetInput(config) {
+  return config;
+}
 function getFeasibility(states) {
   if (states < 1e5)
     return "trivial";
@@ -3989,7 +4005,7 @@ function feasibilityLabel(f) {
 var OMITTED_VARIABLES = "ports, status, deliveredTo, time and payload";
 function dominantTerm(e) {
   const log10 = (n) => n > 0 ? Math.log10(n) : 0;
-  const topology = e.contextCount * TARGET_SET_COUNT * e.tabCount;
+  const topology = e.contextCount * e.targetSets * e.tabCount;
   const terms = [
     {
       label: `state fields (${e.fieldProduct} combinations across ${e.contextCount} contexts)`,
@@ -4000,7 +4016,7 @@ function dominantTerm(e) {
       decades: e.maxInFlight * log10(e.handlerCount)
     },
     {
-      label: `send topology (${e.contextCount} sources x ${TARGET_SET_COUNT} target sets x ${e.tabCount} tabs)`,
+      label: `send topology (${e.contextCount} sources x ${e.targetSets} target sets x ${e.tabCount} tabs)`,
       decades: e.maxInFlight * log10(topology)
     }
   ];
@@ -4027,9 +4043,12 @@ function estimateForScope(config, scope) {
   const { handlerCount, maxInFlight } = scope;
   const tabSetInput = getTabSetInput(config);
   const tabCount = generatedTabCount(tabSetInput);
-  const contextCount = CONTEXT_COUNT;
+  const contextSetInput = getContextSetInput(config);
+  const contexts = resolveContexts(contextSetInput);
+  const contextsDeclared = hasDeclaredContexts(contextSetInput);
+  const contextCount = contexts.length;
   const totalStateSpace = fieldProduct ** contextCount;
-  const sendBranching = sendBranchingFactor(handlerCount, tabCount);
+  const sendBranching = sendBranchingFactor(handlerCount, tabCount, contexts);
   const interleavingFactor = sendBranching ** maxInFlight;
   const estimatedStates = totalStateSpace * interleavingFactor;
   const feasibility = getFeasibility(estimatedStates);
@@ -4041,6 +4060,7 @@ function estimateForScope(config, scope) {
     fieldProduct,
     handlerCount,
     contextCount,
+    targetSets: targetSetCount(contexts),
     tabCount,
     maxInFlight
   });
@@ -4048,6 +4068,9 @@ function estimateForScope(config, scope) {
   if (maxInFlight > 1) {
     suggestions.push(`maxInFlight ${maxInFlight} → ${maxInFlight - 1} divides the estimate by ${sendBranching.toLocaleString()}x (one fewer send to branch over)`);
   }
+  if (!contextsDeclared) {
+    suggestions.push(`Contexts is the default {${contexts.join(", ")}} — no \`contexts\` key is declared. ` + `Declaring the ones this project has divides state replication by fieldProduct^(${contextCount} - n) ` + "and send branching by the drop in |Contexts| * (2^|Contexts| - 1) (polly#185)");
+  }
   if (handlerCount > 15) {
     suggestions.push(`${handlerCount} handlers enter the estimate as ${handlerCount}^${maxInFlight} — splitting into subsystems is the cheapest cut`);
   }
@@ -4063,6 +4086,8 @@ function estimateForScope(config, scope) {
     handlerCount,
     maxInFlight,
     contextCount,
+    contexts,
+    contextsDeclared,
     tabCount,
     sendBranching,
     totalStateSpace,
@@ -4104,6 +4129,7 @@ class ConfigGenerator {
     this.addHeader();
     this.addImports();
     this.addExport();
+    this.addContextsConfig(analysis);
     this.addStateConfig(analysis.fields, analysis.resources);
     this.addMessagesConfig();
     this.addBehaviorConfig();
@@ -4339,6 +4365,53 @@ class ConfigGenerator {
     }
     return "{ min: /* CONFIGURE */ null, max: /* CONFIGURE */ null }";
   }
+  addContextsConfig(analysis) {
+    const inferred = [];
+    for (const handler of analysis.handlers ?? []) {
+      const node = handler.node;
+      if (node === undefined || node === "unknown")
+        continue;
+      if (!inferred.includes(node))
+        inferred.push(node);
+    }
+    this.line("// ─────────────────────────────────────────────────────────");
+    this.line("// Contexts — the processes/actors messages are routed between");
+    this.line("// ─────────────────────────────────────────────────────────");
+    this.line("// This is the cheapest term in the state space to cut. The model");
+    this.line("// replicates state across the set and quantifies every send over");
+    this.line("// |Contexts| x (2^|Contexts| - 1) source/target pairs.");
+    this.line("//");
+    this.line("// Measured on a two-handler model, one message in flight, one tab:");
+    this.line("//   • 3 contexts: 38,464 distinct states");
+    this.line("//   • 2 contexts:  4,896 distinct states");
+    this.line("//   • 1 context:     368 distinct states");
+    this.line("//");
+    const source = inferred.length > 0 ? inferred : this.projectTypeContexts();
+    if (source.length > 0) {
+      this.line(inferred.length > 0 ? "// ✓ Auto-configured from the file paths of the handlers" : `// ✓ Auto-configured from the project type (${this.projectType})`);
+      this.line(`contexts: /* REVIEW */ [${source.map((c) => `'${c}'`).join(", ")}],`);
+    } else {
+      this.line("// No context could be inferred from the handler file paths.");
+      this.line("// Omitting the key models the browser-extension default:");
+      this.line("//   ['background', 'content', 'popup']");
+      this.line("// contexts: /* CONFIGURE */ ['server'],");
+    }
+    this.line("");
+  }
+  projectTypeContexts() {
+    switch (this.projectType) {
+      case "websocket-app":
+        return ["server", "client"];
+      case "pwa":
+        return ["ServiceWorker", "Window"];
+      case "electron":
+        return ["main", "renderer"];
+      case "chrome-extension":
+        return ["background", "content", "popup"];
+      default:
+        return [];
+    }
+  }
   addMessagesConfig() {
     this.line("messages: {");
     this.indent++;
@@ -4408,13 +4481,6 @@ class ConfigGenerator {
         this.line("maxTabs: 1,");
         break;
       case "generic":
-        this.line("// Maximum contexts/actors to model.");
-        this.line("//");
-        this.line("// Recommended:");
-        this.line("//   • 2-3: Simple message passing");
-        this.line("//   • 4-5: Complex coordination");
-        this.line("//");
-        this.line("maxContexts: 3,");
         break;
     }
     this.line("");
@@ -4546,7 +4612,11 @@ function generateConfig(analysis, projectType = "chrome-extension") {
   return generator.generate(analysis, projectType);
 }
 
+// tools/verify/src/cli.ts
+init_model_constants();
+
 // tools/verify/src/config/parser.ts
+init_model_constants();
 init_memory();
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -4629,6 +4699,45 @@ function validateCoupledFields(coupledFields, stateConfig) {
 }
 
 // tools/verify/src/config/parser.ts
+var RESERVED_CONTEXT_NAMES = new Set([
+  "Contexts",
+  "MaxMessages",
+  "NULL",
+  "Tabs",
+  "TimeoutLimit",
+  "MaxWorkers",
+  "MaxRenderers",
+  "MaxClients",
+  "NoTarget",
+  "MeshDocs",
+  "ASSUME",
+  "BOOLEAN",
+  "CASE",
+  "CHOOSE",
+  "CONSTANT",
+  "CONSTANTS",
+  "DOMAIN",
+  "ELSE",
+  "ENABLED",
+  "EXCEPT",
+  "EXTENDS",
+  "FALSE",
+  "IF",
+  "IN",
+  "INSTANCE",
+  "LET",
+  "MODULE",
+  "OTHER",
+  "SUBSET",
+  "THEN",
+  "TRUE",
+  "UNCHANGED",
+  "UNION",
+  "VARIABLE",
+  "VARIABLES",
+  "WITH"
+]);
+
 class ConfigValidator {
   issues = [];
   validate(configPath) {
@@ -4742,6 +4851,7 @@ class ConfigValidator {
     this.findNullPlaceholders(config.messages, "messages");
     this.validateBounds(config);
     this.validateTier1Optimizations(config.messages);
+    this.validateContexts(config);
     if (config.verification) {
       this.validateVerificationOptions(config.verification);
     }
@@ -5023,6 +5133,115 @@ class ConfigValidator {
     }
     this.validateMemory(verification.memory);
   }
+  validateContexts(config) {
+    this.warnOnDeadMaxContexts(config);
+    const contexts = config.contexts;
+    if (contexts === undefined)
+      return;
+    if (!Array.isArray(contexts)) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "contexts",
+        message: "contexts must be an array of context names",
+        suggestion: `Use an array, e.g. ["server"], or omit the key for the default {${DEFAULT_CONTEXTS.join(", ")}}`
+      });
+      return;
+    }
+    if (contexts.length === 0) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "contexts",
+        message: "contexts is empty; the model needs at least one context",
+        suggestion: `Name at least one context, e.g. ["server"], or omit the key for the default {${DEFAULT_CONTEXTS.join(", ")}}`
+      });
+      return;
+    }
+    const seen = new Map;
+    for (const name of contexts) {
+      this.validateContextName(name, seen);
+    }
+    this.warnOnSingleContextMesh(config, contexts.length);
+  }
+  validateContextName(name, seen) {
+    if (typeof name !== "string") {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "contexts",
+        message: `Context name ${JSON.stringify(name)} is not a string`,
+        suggestion: "Every entry must be a string naming one context"
+      });
+      return;
+    }
+    const emitted = sanitizeContextName(name);
+    if (!CONTEXT_NAME_PATTERN.test(emitted)) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "contexts",
+        message: `Context "${name}" is not a TLA+ model value (emits as "${emitted}")`,
+        suggestion: "Start with a letter or underscore, then letters, digits or underscores"
+      });
+      return;
+    }
+    if (RESERVED_CONTEXT_NAMES.has(emitted)) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "contexts",
+        message: `Context "${name}" collides with a TLA+ keyword or a constant the .cfg already declares`,
+        suggestion: `Pick a name outside {${[...RESERVED_CONTEXT_NAMES].sort().join(", ")}}`
+      });
+      return;
+    }
+    const collidesWith = seen.get(emitted);
+    if (collidesWith !== undefined) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        field: "contexts",
+        message: collidesWith === name ? `Context "${name}" is declared twice` : `Contexts "${collidesWith}" and "${name}" both emit as "${emitted}"`,
+        suggestion: "Each context must emit a distinct TLA+ model value"
+      });
+      return;
+    }
+    seen.set(emitted, name);
+    if (emitted !== name) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "warning",
+        field: "contexts",
+        message: `Context "${name}" is emitted as the model value "${emitted}"`,
+        suggestion: "Name it that way in the config so the spec and the config read alike"
+      });
+    }
+  }
+  warnOnDeadMaxContexts(config) {
+    if (config.messages?.maxContexts === undefined)
+      return;
+    this.issues.push({
+      type: "invalid_value",
+      severity: "warning",
+      field: "messages.maxContexts",
+      message: "messages.maxContexts does not size the Contexts set and never did",
+      suggestion: 'Declare the set instead, e.g. contexts: ["server", "client"]'
+    });
+  }
+  warnOnSingleContextMesh(config, contextCount) {
+    if (contextCount > 1)
+      return;
+    if (!config.mesh || Object.keys(config.mesh).length === 0)
+      return;
+    this.issues.push({
+      type: "invalid_value",
+      severity: "warning",
+      field: "contexts",
+      message: "one context with a `mesh` block: PropagateMeshOp needs two distinct contexts, so mesh propagation is never enabled",
+      suggestion: "Declare at least two contexts, or drop the mesh block from this model"
+    });
+  }
   validateMemory(memory) {
     if (memory === undefined)
       return;
@@ -8822,7 +9041,8 @@ function displayEstimate(estimate) {
   console.log(`  Field combinations:     ${color(String(estimate.fieldProduct), COLORS.green)}`);
   console.log(`  Handlers:               ${estimate.handlerCount}`);
   console.log(`  Max in-flight:          ${estimate.maxInFlight}`);
-  console.log(`  Contexts:               ${estimate.contextCount} (fixed by the generated .cfg)`);
+  const contextSource = estimate.contextsDeclared ? "declared" : "the default — no `contexts` key";
+  console.log(`  Contexts:               ${estimate.contextCount} — ${estimate.contexts.join(", ")} (${contextSource})`);
   console.log(`  Tabs:                   ${estimate.tabCount}`);
   console.log(`  State across contexts:  ${estimate.fieldProduct}^${estimate.contextCount} = ${estimate.totalStateSpace.toLocaleString()}`);
   console.log(`  Send branching:         ${estimate.sendBranching.toLocaleString()} per message (^${estimate.maxInFlight} = ${estimate.interleavingFactor.toLocaleString()})`);
@@ -9086,6 +9306,55 @@ async function runCoupledFieldsLint(config, analysis) {
   console.log(color("   the relationship with a `capabilities` invariant.", COLORS.yellow));
   console.log();
 }
+function describeContextSet(config) {
+  const contexts = resolveContexts(config);
+  const source = hasDeclaredContexts(config) ? "declared" : "default";
+  return `${contexts.join(", ")} (${contexts.length}, ${source})`;
+}
+function inferredContexts(analysis) {
+  const seen = [];
+  for (const handler of analysis.handlers) {
+    const node = handler.node;
+    if (node === undefined || node === "unknown")
+      continue;
+    if (!seen.includes(node))
+      seen.push(node);
+  }
+  return seen;
+}
+function displayContextDiagnostics(config, analysis) {
+  const declared = hasDeclaredContexts(config);
+  const contexts = new Set(resolveContexts(config));
+  const inferred = inferredContexts(analysis);
+  if (!declared) {
+    console.log(color(`ℹ️  No \`contexts\` key — modelling the default {${DEFAULT_CONTEXTS.join(", ")}}`, COLORS.gray));
+    if (inferred.length > 0) {
+      console.log(color(`   polly infers from the handler paths: ${inferred.join(", ")}`, COLORS.gray));
+      console.log(color(`   Declaring \`contexts: [${inferred.map((c) => `"${c}"`).join(", ")}]\` shrinks the model to the contexts you have.`, COLORS.gray));
+    }
+    console.log();
+    return;
+  }
+  const outside = analysis.handlers.filter((h) => {
+    const node = h.node;
+    return node !== undefined && node !== "unknown" && !contexts.has(sanitizeContextName(node));
+  });
+  if (outside.length === 0)
+    return;
+  console.log(color(`⚠️  ${outside.length} handler(s) run in a context \`contexts\` does not declare:`, COLORS.yellow));
+  for (const h of outside.slice(0, 10)) {
+    const node = h.node;
+    console.log(color(`   • ${h.messageType} → ${node} (${h.location.file})`, COLORS.yellow));
+  }
+  if (outside.length > 10) {
+    console.log(color(`   ... and ${outside.length - 10} more`, COLORS.yellow));
+  }
+  console.log();
+  console.log(color(`   The model quantifies sends over {${[...contexts].join(", ")}} only, so these handlers`, COLORS.yellow));
+  console.log(color("   are modelled from a source they are not in. Add the missing contexts, or correct the", COLORS.yellow));
+  console.log(color("   file paths polly infers them from.", COLORS.yellow));
+  console.log();
+}
 async function runFullVerification(configPath) {
   const config = await loadVerificationConfig(configPath);
   const analysis = await runCodebaseAnalysis();
@@ -9100,6 +9369,7 @@ async function runFullVerification(configPath) {
   const meshFindingCount = displayMeshOrPeerSignalWarnings(typedAnalysis, declaredMeshDocs);
   await runCoupledFieldsLint(typedConfig, typedAnalysis);
   await runModelCoverage(typedConfig, typedAnalysis, meshFindingCount);
+  displayContextDiagnostics(typedConfig, typedAnalysis);
   if (typedConfig.subsystems && Object.keys(typedConfig.subsystems).length > 0) {
     await runSubsystemVerification(typedConfig, typedAnalysis);
     if (isWitnessMode()) {
@@ -9138,6 +9408,7 @@ async function runMonolithicVerification(config, analysis) {
     console.log(color(`   Max depth: ${maxDepth}`, COLORS.gray));
   }
   console.log(color(`   Memory: ${memory ?? DEFAULT_TLC_MEMORY}`, COLORS.gray));
+  console.log(color(`   Contexts: ${describeContextSet(typedConfig)}`, COLORS.gray));
   console.log();
   const result = await docker.runTLC(specPath, {
     workers,
@@ -9213,6 +9484,8 @@ async function runSubsystemVerification(config, analysis) {
   const workers = getWorkers(config);
   const maxDepth = getMaxDepth(config);
   const memory = getMemory(config);
+  console.log(color(`⚙️  Contexts: ${describeContextSet(config)}`, COLORS.gray));
+  console.log();
   await Promise.resolve().then(() => init_tla());
   const results = [];
   const customTLAPaths = getCustomTLAPaths(config);
@@ -9832,4 +10105,4 @@ main().catch((error) => {
   process.exit(1);
 });
 
-//# debugId=10A3CEC0EDCA40C864756E2164756E21
+//# debugId=3AB21B8DB351312E64756E2164756E21