@fairfox/polly 0.82.1 → 0.83.0

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

@@ -3138,6 +3138,355 @@ var init_tla = __esm(() => {
   };
 });
 
+// tools/bdd/src/parse.ts
+import { AstBuilder, GherkinClassicTokenMatcher, Parser } from "@cucumber/gherkin";
+import { IdGenerator } from "@cucumber/messages";
+function newParser() {
+  return new Parser(new AstBuilder(IdGenerator.uuid()), new GherkinClassicTokenMatcher);
+}
+function normalizeKeyword(raw, prev) {
+  const k = raw.trim().toLowerCase();
+  if (k === "given")
+    return "given";
+  if (k === "when")
+    return "when";
+  if (k === "then")
+    return "then";
+  return prev ?? "given";
+}
+function normalizeSteps(rawSteps) {
+  const out = [];
+  let prev = null;
+  for (const s of rawSteps) {
+    const keyword = normalizeKeyword(s.keyword, prev);
+    prev = keyword;
+    out.push({
+      keyword,
+      rawKeyword: s.keyword.trim(),
+      text: s.text.trim(),
+      line: s.location?.line ?? 0
+    });
+  }
+  return out;
+}
+function tagNames(tags) {
+  return (tags ?? []).map((t) => t.name.replace(/^@/, ""));
+}
+function fillOutline(text, headers, cells) {
+  let filled = text;
+  headers.forEach((h, i) => {
+    filled = filled.split(`<${h}>`).join(cells[i] ?? "");
+  });
+  return filled;
+}
+function buildScenarios(sc) {
+  const baseSteps = sc.steps ?? [];
+  const tags = tagNames(sc.tags);
+  const examples = sc.examples ?? [];
+  if (examples.length === 0) {
+    return [
+      { name: sc.name, tags, steps: normalizeSteps(baseSteps), line: sc.location?.line ?? 0 }
+    ];
+  }
+  const out = [];
+  for (const ex of examples) {
+    const headers = (ex.tableHeader?.cells ?? []).map((c) => c.value);
+    for (const row of ex.tableBody ?? []) {
+      const cells = (row.cells ?? []).map((c) => c.value);
+      const rowSteps = baseSteps.map((s) => ({
+        keyword: s.keyword,
+        text: fillOutline(s.text, headers, cells),
+        location: s.location
+      }));
+      const label = headers.map((h, i) => `${h}=${cells[i] ?? ""}`).join(", ");
+      out.push({
+        name: `${sc.name} [${label}]`,
+        tags: [...tags, ...tagNames(ex.tags)],
+        steps: normalizeSteps(rowSteps),
+        line: row.location?.line ?? sc.location?.line ?? 0,
+        fromOutline: true
+      });
+    }
+  }
+  return out;
+}
+function parseFeatureText(text, file) {
+  const doc = newParser().parse(text);
+  const feature = doc.feature;
+  if (!feature) {
+    return { name: "", description: "", tags: [], background: [], scenarios: [], file };
+  }
+  let background = [];
+  const scenarios = [];
+  for (const child of feature.children ?? []) {
+    if (child.background) {
+      background = normalizeSteps(child.background.steps ?? []);
+    } else if (child.scenario) {
+      scenarios.push(...buildScenarios(child.scenario));
+    }
+  }
+  return {
+    name: feature.name,
+    description: (feature.description ?? "").trim(),
+    tags: tagNames(feature.tags),
+    background,
+    scenarios,
+    file
+  };
+}
+async function parseFeatureFile(path3) {
+  const text = await Bun.file(path3).text();
+  return parseFeatureText(text, path3);
+}
+var init_parse = () => {};
+
+// tools/bdd/src/steps.ts
+function state() {
+  globalThis.__pollyBddRegistry__ ??= { bindings: [], worldDef: null };
+  return globalThis.__pollyBddRegistry__;
+}
+function compilePattern(pattern) {
+  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const withGroups = escaped.replace(/\\\{string\\\}/g, `(?:"([^"]*)"|'([^']*)')`).replace(/\\\{int\\\}/g, "([-+]?\\d+)").replace(/\\\{float\\\}/g, "([-+]?\\d*\\.?\\d+)").replace(/\\\{word\\\}/g, "([^\\s]+)");
+  return new RegExp(`^${withGroups}$`);
+}
+function defineStep(binding) {
+  state().bindings.push({ binding, regex: compilePattern(binding.pattern) });
+}
+function defineWorld(def) {
+  state().worldDef = def;
+}
+function getWorldDef() {
+  return state().worldDef;
+}
+function resetRegistry() {
+  const s = state();
+  s.bindings.length = 0;
+  s.worldDef = null;
+}
+function matchStep(text, keyword) {
+  let textOnlyFallback = null;
+  for (const { binding, regex } of state().bindings) {
+    const m = regex.exec(text);
+    if (!m)
+      continue;
+    const args = m.slice(1).filter((g) => g !== undefined);
+    if (!keyword || binding[keyword])
+      return { binding, args };
+    textOnlyFallback ??= { binding, args };
+  }
+  return textOnlyFallback;
+}
+function registeredBindings() {
+  return state().bindings.map((c) => c.binding);
+}
+
+// tools/bdd/src/witness.ts
+var exports_witness = {};
+__export(exports_witness, {
+  extractWitnesses: () => extractWitnesses
+});
+async function loadStepModules(stepFiles) {
+  resetRegistry();
+  for (const file of stepFiles) {
+    await import(`${file}?t=${Bun.nanoseconds()}`);
+  }
+}
+function substituteArgs(expr, args) {
+  return expr.replace(/\{(\d+)\}/g, (whole, index) => args[Number(index)] ?? whole);
+}
+function fieldsIn(expr) {
+  const noStrings = expr.replace(/"[^"]*"|'[^']*'/g, "");
+  const ids = noStrings.match(/[a-zA-Z_$][\w$]*(?:\.[a-zA-Z_$][\w$]*)*/g) ?? [];
+  const ignore = new Set(["true", "false", "null", "undefined", "length", "value"]);
+  return ids.filter((id) => !ignore.has(id) && Number.isNaN(Number(id))).map((id) => id.replace(/\.length$/, ""));
+}
+function reduceScenario(feature, scenario) {
+  const thenSteps = [...feature.background, ...scenario.steps].filter((s) => s.keyword === "then");
+  const conjuncts = [];
+  const skipped = [];
+  for (const step of thenSteps) {
+    const match = matchStep(step.text, "then");
+    const expr = match?.binding.stateExpr;
+    if (!expr) {
+      skipped.push(step.text);
+      continue;
+    }
+    const resolved = substituteArgs(expr, match.args);
+    if (!COMPARISON.test(resolved)) {
+      skipped.push(step.text);
+      continue;
+    }
+    conjuncts.push(resolved);
+  }
+  const predicate = conjuncts.length > 0 ? conjuncts.join(" && ") : null;
+  const fields = [...new Set(conjuncts.flatMap(fieldsIn))];
+  return {
+    feature: feature.name,
+    scenario: scenario.name,
+    tags: [...feature.tags, ...scenario.tags],
+    file: feature.file,
+    predicate,
+    fields,
+    skipped
+  };
+}
+async function extractWitnesses(featureFiles, stepFiles) {
+  await loadStepModules(stepFiles);
+  const witnesses = [];
+  for (const file of featureFiles) {
+    const feature = await parseFeatureFile(file);
+    for (const scenario of feature.scenarios) {
+      witnesses.push(reduceScenario({
+        name: feature.name,
+        tags: feature.tags,
+        background: feature.background,
+        file: feature.file
+      }, scenario));
+    }
+  }
+  return witnesses;
+}
+var COMPARISON;
+var init_witness = __esm(() => {
+  init_parse();
+  COMPARISON = /===|!==|==|!=|<=|>=|<|>/;
+});
+
+// tools/verify/src/codegen/witness.ts
+var exports_witness2 = {};
+__export(exports_witness2, {
+  routeWitness: () => routeWitness,
+  buildWitnessModule: () => buildWitnessModule,
+  buildWitnessInvariant: () => buildWitnessInvariant,
+  buildWitnessCfg: () => buildWitnessCfg,
+  bddPredicateToTLA: () => bddPredicateToTLA,
+  WitnessTranslationError: () => WitnessTranslationError,
+  WITNESS_INVARIANT: () => WITNESS_INVARIANT
+});
+function flattenField(path3) {
+  return path3.split(".").join("_");
+}
+function translateOperand(raw) {
+  const op = raw.trim();
+  if (op === "true")
+    return "TRUE";
+  if (op === "false")
+    return "FALSE";
+  if (/^"[^"]*"$/.test(op))
+    return op;
+  if (/^'[^']*'$/.test(op))
+    return `"${op.slice(1, -1)}"`;
+  if (/^[-+]?\d+(?:\.\d+)?$/.test(op))
+    return op;
+  if (!/^[a-zA-Z_$][\w$]*(?:\.[a-zA-Z_$][\w$]*)*$/.test(op)) {
+    throw new WitnessTranslationError(`unsupported operand "${raw}" in witness predicate`);
+  }
+  if (op.endsWith(".length")) {
+    return `Len(contextStates[ctx].${flattenField(op.slice(0, -".length".length))})`;
+  }
+  return `contextStates[ctx].${flattenField(op)}`;
+}
+function translateConjunct(conjunct) {
+  const text = conjunct.trim();
+  for (const [js, tla] of COMPARATORS) {
+    const at = text.indexOf(js);
+    if (at === -1)
+      continue;
+    const lhs = text.slice(0, at);
+    const rhs = text.slice(at + js.length);
+    return `${translateOperand(lhs)} ${tla} ${translateOperand(rhs)}`;
+  }
+  throw new WitnessTranslationError(`no comparison operator in witness conjunct "${conjunct}"`);
+}
+function bddPredicateToTLA(predicate) {
+  const conjuncts = predicate.split("&&").map((c) => c.trim()).filter(Boolean);
+  if (conjuncts.length === 0) {
+    throw new WitnessTranslationError("empty witness predicate");
+  }
+  return conjuncts.map(translateConjunct).join(" /\\ ");
+}
+function buildWitnessInvariant(tlaPredicate) {
+  return `${WITNESS_INVARIANT} == ~(\\E ctx \\in Contexts : ${tlaPredicate})`;
+}
+function buildWitnessModule(moduleName, subsystemModule, tlaPredicate) {
+  return [
+    `---- MODULE ${moduleName} ----`,
+    `EXTENDS ${subsystemModule}`,
+    "",
+    buildWitnessInvariant(tlaPredicate),
+    "====",
+    ""
+  ].join(`
+`);
+}
+function sectionBody(cfg, header) {
+  const body = [];
+  let inSection = false;
+  for (const line of cfg.split(`
+`)) {
+    const headerMatch = /^([A-Z_]+)\b/.exec(line);
+    if (headerMatch) {
+      inSection = headerMatch[1] === header;
+      continue;
+    }
+    if (!inSection)
+      continue;
+    if (line.trim() === "" || line.trim().startsWith("\\*"))
+      continue;
+    body.push(line);
+  }
+  return body;
+}
+function headerLine(cfg, header) {
+  for (const line of cfg.split(`
+`)) {
+    const m = new RegExp(`^${header}\\b(.*)$`).exec(line);
+    if (m)
+      return line.trimEnd();
+  }
+  return null;
+}
+function buildWitnessCfg(baseCfg) {
+  const spec = headerLine(baseCfg, "SPECIFICATION") ?? "SPECIFICATION UserSpec";
+  const constants = sectionBody(baseCfg, "CONSTANTS");
+  const constraint = sectionBody(baseCfg, "CONSTRAINT");
+  const symmetry = sectionBody(baseCfg, "SYMMETRY");
+  const out = [spec, "", "CONSTANTS", ...constants, "", "INVARIANTS", `  ${WITNESS_INVARIANT}`];
+  if (constraint.length > 0)
+    out.push("", "CONSTRAINT", ...constraint);
+  if (symmetry.length > 0)
+    out.push("", "SYMMETRY", ...symmetry);
+  return `${out.join(`
+`)}
+`;
+}
+function covers(stateKeys, field) {
+  return stateKeys.some((k) => k === field || field.startsWith(`${k}.`) || k.startsWith(`${field}.`));
+}
+function routeWitness(fields, subsystems) {
+  if (fields.length === 0)
+    return null;
+  const owners = Object.entries(subsystems).filter(([, sub]) => fields.every((f) => covers(sub.state, f)));
+  const only = owners.length === 1 ? owners[0] : undefined;
+  return only ? only[0] : null;
+}
+var WITNESS_INVARIANT = "WitnessReachable", WitnessTranslationError, COMPARATORS;
+var init_witness2 = __esm(() => {
+  WitnessTranslationError = class WitnessTranslationError extends Error {
+  };
+  COMPARATORS = [
+    ["===", "="],
+    ["!==", "#"],
+    ["==", "="],
+    ["!=", "#"],
+    [">=", ">="],
+    ["<=", "<="],
+    [">", ">"],
+    ["<", "<"]
+  ];
+});
+
 // tools/verify/src/runner/docker.ts
 var exports_docker = {};
 __export(exports_docker, {
@@ -8090,6 +8439,9 @@ function displayMeshOrPeerSignalWarnings(analysis, declaredMeshDocs) {
 function isStrictMode() {
   return process.argv.includes("--strict") || process.env.POLLY_VERIFY_STRICT === "1";
 }
+function isWitnessMode() {
+  return process.argv.includes("--witness");
+}
 function displayModelCoverage(report) {
   const { unwrittenFields, unconstrainedMutators, fieldCoverage } = report;
   if (unwrittenFields.length === 0 && unconstrainedMutators.length === 0) {
@@ -8246,9 +8598,17 @@ async function runFullVerification(configPath) {
   await runModelCoverage(typedConfig, typedAnalysis, meshFindingCount);
   if (typedConfig.subsystems && Object.keys(typedConfig.subsystems).length > 0) {
     await runSubsystemVerification(typedConfig, typedAnalysis);
+    if (isWitnessMode()) {
+      await runWitnessVerification(typedConfig);
+    }
     return;
   }
   await runMonolithicVerification(config, analysis);
+  if (isWitnessMode()) {
+    console.log(color("\n⚠ --witness needs subsystem-scoped verification (a `subsystems` block in the config);", COLORS.yellow));
+    console.log(color(`  reachability witnesses route each scenario to its subsystem spec.
+`, COLORS.yellow));
+  }
 }
 async function runMonolithicVerification(config, analysis) {
   const { specPath, specDir } = await generateAndWriteTLASpecs(config, analysis);
@@ -8393,6 +8753,160 @@ async function runSubsystemVerification(config, analysis) {
   console.log();
   displayCompositionalReport(results, interference.valid);
 }
+var DEFAULT_WITNESS_TIMEOUT_MS = 180000;
+async function globAbsolute(cwd, pattern) {
+  const out = [];
+  for await (const f of new Bun.Glob(pattern).scan({ cwd, absolute: true, onlyFiles: true })) {
+    out.push(f);
+  }
+  return out.sort();
+}
+async function runWitnessVerification(config) {
+  console.log(color(`Reachability witnesses (--witness)
+`, COLORS.blue));
+  const cwd = process.cwd();
+  const featureFiles = await globAbsolute(cwd, "features/**/*.feature");
+  const stepFiles = [
+    ...new Set([
+      ...await globAbsolute(cwd, "features/**/*.steps.ts"),
+      ...await globAbsolute(cwd, "features/steps.ts")
+    ])
+  ];
+  if (featureFiles.length === 0 || stepFiles.length === 0) {
+    console.log(color(`  No .feature files / step modules found — nothing to witness.
+`, COLORS.gray));
+    return;
+  }
+  const { extractWitnesses: extractWitnesses2 } = await Promise.resolve().then(() => (init_witness(), exports_witness));
+  const {
+    bddPredicateToTLA: bddPredicateToTLA2,
+    buildWitnessCfg: buildWitnessCfg2,
+    buildWitnessModule: buildWitnessModule2,
+    routeWitness: routeWitness2,
+    WITNESS_INVARIANT: WITNESS_INVARIANT2
+  } = await Promise.resolve().then(() => (init_witness2(), exports_witness2));
+  const subsystems = config.subsystems;
+  const witnesses = await extractWitnesses2(featureFiles, stepFiles);
+  const docker = await setupDocker();
+  const timeoutSeconds = getTimeout(config);
+  const timeout = timeoutSeconds > 0 ? timeoutSeconds * 1000 : DEFAULT_WITNESS_TIMEOUT_MS;
+  const workers = getWorkers(config);
+  const results = [];
+  let idx = 0;
+  for (const w of witnesses) {
+    const id = `${w.feature} › ${w.scenario}`;
+    if (!w.predicate) {
+      results.push({ id, status: "skipped", note: "no state-observable Then to witness" });
+      continue;
+    }
+    const subsystem = routeWitness2(w.fields, subsystems);
+    if (!subsystem) {
+      results.push({
+        id,
+        status: "skipped",
+        note: `fields [${w.fields.join(", ")}] not owned by a single subsystem`
+      });
+      continue;
+    }
+    const specDir = path4.join(cwd, "specs", "tla", "generated", subsystem);
+    const subsystemCfg = path4.join(specDir, `UserApp_${subsystem}.cfg`);
+    if (!fs4.existsSync(path4.join(specDir, `UserApp_${subsystem}.tla`)) || !fs4.existsSync(subsystemCfg)) {
+      results.push({
+        id,
+        status: "error",
+        subsystem,
+        note: `subsystem spec missing: ${subsystem}`
+      });
+      continue;
+    }
+    let tlaPredicate;
+    try {
+      tlaPredicate = bddPredicateToTLA2(w.predicate);
+    } catch (err) {
+      results.push({
+        id,
+        status: "error",
+        subsystem,
+        note: err instanceof Error ? err.message : String(err)
+      });
+      continue;
+    }
+    const moduleName = `Witness_${subsystem}_${idx++}`;
+    const witnessTla = path4.join(specDir, `${moduleName}.tla`);
+    fs4.writeFileSync(witnessTla, buildWitnessModule2(moduleName, `UserApp_${subsystem}`, tlaPredicate));
+    fs4.writeFileSync(path4.join(specDir, `${moduleName}.cfg`), buildWitnessCfg2(fs4.readFileSync(subsystemCfg, "utf8")));
+    console.log(color(`⚙️  ${id}`, COLORS.blue));
+    console.log(color(`     ${subsystem} ⊨ ${w.predicate}`, COLORS.gray));
+    let tlc;
+    try {
+      tlc = await docker.runTLC(witnessTla, { workers, timeout });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      results.push({ id, status: "inconclusive", subsystem, predicate: w.predicate, note: msg });
+      console.log(color("     ⚠ inconclusive — TLC did not finish (raise the config timeout)", COLORS.yellow));
+      continue;
+    }
+    if (!tlc.success && tlc.violation?.name === WITNESS_INVARIANT2) {
+      results.push({ id, status: "reachable", subsystem, predicate: w.predicate });
+      console.log(color("     ✓ reachable — the model reaches this outcome", COLORS.green));
+    } else if (tlc.success) {
+      results.push({
+        id,
+        status: "unreachable",
+        subsystem,
+        predicate: w.predicate,
+        note: `${tlc.stats?.distinctStates ?? 0} distinct states, no path`
+      });
+      console.log(color("     ✗ UNREACHABLE — the model proves this outcome impossible (the scenario lies)", COLORS.red));
+      fs4.writeFileSync(path4.join(specDir, `${moduleName}.tlc-output.log`), tlc.output);
+    } else {
+      results.push({
+        id,
+        status: "error",
+        subsystem,
+        predicate: w.predicate,
+        note: tlc.error ?? tlc.violation?.name ?? "TLC error"
+      });
+      console.log(color(`     ! error — ${tlc.error ?? "see log"}`, COLORS.yellow));
+      fs4.writeFileSync(path4.join(specDir, `${moduleName}.tlc-output.log`), tlc.output);
+    }
+  }
+  displayWitnessReport(results);
+}
+function displayWitnessReport(results) {
+  const count = (s) => results.filter((r) => r.status === s).length;
+  const reachable = count("reachable");
+  const unreachable = count("unreachable");
+  const inconclusive = count("inconclusive");
+  const errors = count("error");
+  const skipped = count("skipped");
+  console.log();
+  console.log(color(`Witness results:
+`, COLORS.blue));
+  for (const r of results) {
+    const mark = {
+      reachable: color("✓", COLORS.green),
+      unreachable: color("✗", COLORS.red),
+      inconclusive: color("⚠", COLORS.yellow),
+      error: color("!", COLORS.yellow),
+      skipped: color("·", COLORS.gray)
+    }[r.status];
+    const note = r.note ? color(`  (${r.note})`, COLORS.gray) : "";
+    console.log(`  ${mark} ${r.status.padEnd(12)} ${r.id}${note}`);
+  }
+  console.log();
+  console.log(color(`  ${reachable} reachable, ${unreachable} unreachable, ${inconclusive} inconclusive, ${errors} error, ${skipped} skipped`, COLORS.gray));
+  console.log();
+  if (unreachable > 0 || errors > 0) {
+    console.log(color("Witness result: ✗ FAIL", COLORS.red));
+    console.log(color("  A scenario the exhaustive model cannot reach describes an impossible outcome.", COLORS.gray));
+    console.log();
+    process.exit(1);
+  }
+  console.log(color("Witness result: ✓ PASS", COLORS.green));
+  console.log(color("  Every witnessable scenario's outcome is reachable in the model.", COLORS.gray));
+  console.log();
+}
 function displayEnsuresSummary(results) {
   const totalEnsures = results.reduce((sum, r) => sum + r.ensuresCount, 0);
   if (totalEnsures === 0)
@@ -8630,6 +9144,12 @@ ${color("Commands:", COLORS.blue)}
     field no handler writes, or an unverified $meshState/$peerState predicate.
     Also via ${color("POLLY_VERIFY_STRICT=1", COLORS.yellow)}.
 
+  ${color("polly verify --witness", COLORS.green)}
+    After the invariant pass, check each BDD scenario's Then-outcome for
+    reachability: one TLC run per witnessable scenario over its subsystem spec.
+    A scenario the exhaustive model proves unreachable is one that lies, and
+    fails the run. Needs a ${color("subsystems", COLORS.blue)} block and ${color("features/", COLORS.blue)} (see polly bdd).
+
   ${color("polly verify --setup", COLORS.green)}
     Analyze codebase and generate configuration file
 
@@ -8693,4 +9213,4 @@ main().catch((error) => {
   process.exit(1);
 });
 
-//# debugId=EBD97C743E15B6D964756E2164756E21
+//# debugId=006B6ED4C6E5114F64756E2164756E21