@patterkit/cli 0.5.4 → 0.6.0

package/README.md

@@ -128,6 +128,34 @@ patter play --scene scn_tavern --choices opt_work,opt_secret
 patter play --seed 42
 ```
 
+### `patter coverage [path]`
+
+Play the story many times with random choices and count how often each beat comes
+up, to find content no player can reach. The summary counts beats reached, never
+reached, and rarely reached (in fewer than 5% of runs), and says how the runs
+ended: reached the end, stalled at a choice with nothing to pick, or hit the step
+limit. The table gives each beat's **reached** (the share of runs that played it)
+and **played** (times it played in all runs), least reached first. Marks: `‼`
+never reached, `?` never reached but may just need an input driver, `~` rarely
+reached. Choices that ran dry (nothing to take and no fallback) are listed too.
+
+| Option | Values | Meaning |
+|--------|--------|---------|
+| `--runs <n>` | integer | How many playthroughs (default 5000). |
+| `--max-steps <n>` | integer | Steps before a run is stopped (default 200). |
+| `--seed <n>` | integer | The same seed gives the same result. |
+| `--scene <id>` / `--block <id>` | id | Start here instead of the project's start. |
+| `--order <o>` | `least` / `script` | Least reached first (default), or the script's order, scene by scene. |
+| `--fail-on-gap` | | Exit 1 if any beat is never reached (a CI gate). |
+| `--propose` | | Print suggested `@world` input drivers instead of running. |
+| `--json` | | The full report as JSON. |
+
+```sh
+patter coverage
+patter coverage --runs 10000 --seed 7 --order script
+patter coverage --fail-on-gap
+```
+
 ### `patter resolve <query> [path]`
 
 Look up an **id**, **handle**, or **name** and report what it is and where it

package/dist/cli.js

@@ -198055,6 +198055,10 @@ function mulberry32(seed) {
   const prng = makePrng(seed);
   return () => prng.next();
 }
+var RARE_REACH_PCT = 5;
+function leastReachedFirst(beats) {
+  return beats.map((b, i) => ({ b, i })).sort((x, y) => x.b.reachPct - y.b.reachPct || x.b.hits - y.b.hits || x.i - y.i).map(({ b }) => b);
+}
 function scanExpr(node, hostTokens, refs, proposals) {
   const refOf = (n) => n.kind === "scopedvar" && hostTokens.has(n.scope) ? `@${n.scope}.${n.name}` : void 0;
   const propose = (ref, v) => (proposals.get(ref) ?? proposals.set(ref, /* @__PURE__ */ new Set()).get(ref)).add(v);
@@ -198344,6 +198348,7 @@ function* sweep(loaded, options = {}, hooks = {}) {
       const blocked = blockedGates(id, analysis, drivenRefs, reachedRuns);
       if (blocked.length) blockedBy = blocked;
     }
+    const reachPct = executed ? reached / executed * 100 : 0;
     return {
       id,
       scene: m.scene,
@@ -198352,13 +198357,15 @@ function* sweep(loaded, options = {}, hooks = {}) {
       preview: m.preview,
       hits: hitCount.get(id),
       reachedRuns: reached,
-      reachPct: executed ? reached / executed * 100 : 0,
+      reachPct,
+      ...reached > 0 && reachPct < RARE_REACH_PCT ? { rare: true } : {},
       ...needsInput ? { needsInput } : {},
       ...blockedBy ? { blockedBy } : {}
     };
   });
   const neverHit = beats.filter((b) => b.reachedRuns === 0).length;
   const covered = beats.length - neverHit;
+  const rare = beats.filter((b) => b.rare).length;
   const dryChoices = [...dryRuns.entries()].map(([id, r]) => ({ id, scene: choiceScene.get(id) ?? "", runs: r })).sort((a, b) => b.runs - a.runs || a.id.localeCompare(b.id));
   return {
     runs: executed,
@@ -198366,7 +198373,8 @@ function* sweep(loaded, options = {}, hooks = {}) {
     seed,
     start,
     beats,
-    totals: { beats: beats.length, covered, neverHit, coveragePct: beats.length ? covered / beats.length * 100 : 100 },
+    totals: { beats: beats.length, covered, neverHit, rare, coveragePct: beats.length ? covered / beats.length * 100 : 100 },
+    rareThresholdPct: RARE_REACH_PCT,
     termination,
     drivers,
     unwrittenInputs: [...unwrittenInputs].sort(),
@@ -198380,14 +198388,19 @@ function runCoverage(loaded, options = {}, hooks = {}) {
   while (!step.done) step = it.next();
   return step.value;
 }
-function renderCoverageText(report, sceneName = (id) => id) {
+function renderCoverageText(report, sceneName = (id) => id, opts = {}) {
+  const order = opts.order ?? "least";
   const out = [];
   const t = report.totals;
   const pct = (n) => `${n.toFixed(0)}%`;
-  out.push(`coverage: ${t.covered}/${t.beats} beats reached (${pct(t.coveragePct)})${t.neverHit ? ` - ${t.neverHit} never reached` : ""}`);
+  const rareLimit = report.rareThresholdPct ?? RARE_REACH_PCT;
+  const rareCount = t.rare ?? report.beats.filter((b) => b.rare).length;
+  out.push(
+    `coverage: ${t.covered}/${t.beats} beats reached (${pct(t.coveragePct)})` + (t.neverHit ? ` - ${t.neverHit} never reached` : "") + (rareCount ? ` - ${rareCount} rarely reached (under ${rareLimit}% of runs)` : "")
+  );
   out.push(`${report.runs} run(s) - ${report.maxSteps} max steps - seed ${report.seed}${report.cancelled ? " - CANCELLED" : ""}`);
   const term = report.termination;
-  out.push(`runs ended: ${term.ended} reached the end, ${term.stalled} stalled, ${term.capped} hit the step cap, ${term.evalError} errored`);
+  out.push(`runs ended: ${term.ended} reached the end, ${term.stalled} stalled at a choice with nothing to pick, ${term.capped} hit the step limit, ${term.evalError} errored`);
   if (report.drivers.length) out.push(`input drivers: ${report.drivers.map((d) => d.ref).join(", ")}`);
   if (report.unwrittenInputs.length) {
     out.push(`? = gated on an input nothing writes/drives: ${report.unwrittenInputs.join(", ")} (add a coverage driver?)`);
@@ -198399,25 +198412,43 @@ function renderCoverageText(report, sceneName = (id) => id) {
       out.push(`  \u203C ${String(d.runs).padStart(6)} run(s)  ${sceneName(d.scene)}  choice '${d.id}'`);
     }
   }
+  if (!report.beats.length) return out;
+  const clip = (s, n = 48) => s.length > n ? `${s.slice(0, n - 1)}\u2026` : s;
+  const scenes = new Set(report.beats.map((b) => b.scene));
+  const heading = "     reached  played  beat";
+  const row = (b, withScene) => {
+    const mark = b.reachedRuns === 0 ? b.needsInput || b.blockedBy ? "? " : "\u203C " : b.rare ? "~ " : "  ";
+    const label = b.character ? `${b.character}: ${clip(b.preview)}` : clip(b.preview || `(${b.kind})`);
+    const where = withScene ? `[${sceneName(b.scene)}] ` : "";
+    out.push(`  ${mark}${pct(b.reachPct).padStart(6)}  ${String(b.hits).padStart(6)}  ${where}${label}`);
+    for (const bg of b.blockedBy ?? []) {
+      const names = bg.writers.map((w) => {
+        const target = report.beats.find((x) => x.id === w);
+        return target ? clip(target.preview || target.id, 28) : w;
+      });
+      out.push(`           gated on ${bg.ref}, written only by: ${names.join(", ")} (never played either)`);
+    }
+  };
+  out.push("");
+  out.push(`reached = share of runs that played the beat at least once; played = times it played in all runs`);
+  out.push(`\u203C never reached   ? never reached, may need an input   ~ rarely reached (under ${rareLimit}% of runs)`);
+  if (order === "least") {
+    out.push("");
+    out.push(`least reached first${scenes.size > 1 ? ", every scene" : ""}`);
+    out.push(heading);
+    for (const b of leastReachedFirst(report.beats)) row(b, scenes.size > 1);
+    return out;
+  }
   const byScene = /* @__PURE__ */ new Map();
   for (const b of report.beats) (byScene.get(b.scene) ?? byScene.set(b.scene, []).get(b.scene)).push(b);
-  const clip = (s, n = 48) => s.length > n ? `${s.slice(0, n - 1)}\u2026` : s;
   for (const [scene, beats] of byScene) {
     const dead = beats.filter((b) => b.reachedRuns === 0).length;
+    const rare = beats.filter((b) => b.rare).length;
+    const notes = [dead ? `${dead} never reached` : "", rare ? `${rare} rarely reached` : ""].filter(Boolean).join(", ");
     out.push("");
-    out.push(`${sceneName(scene)}${dead ? `  (${dead} never reached)` : ""}`);
-    for (const b of beats) {
-      const mark = b.reachedRuns === 0 ? b.needsInput || b.blockedBy ? "? " : "\u203C " : "  ";
-      const label = b.character ? `${b.character}: ${clip(b.preview)}` : clip(b.preview || `(${b.kind})`);
-      out.push(`  ${mark}${b.reachPct.toFixed(0).padStart(3)}%  ${String(b.hits).padStart(6)}  ${label}`);
-      for (const bg of b.blockedBy ?? []) {
-        const names = bg.writers.map((w) => {
-          const target = report.beats.find((x) => x.id === w);
-          return target ? clip(target.preview || target.id, 28) : w;
-        });
-        out.push(`         gated on ${bg.ref}, written only by: ${names.join(", ")} (never played either)`);
-      }
-    }
+    out.push(`${sceneName(scene)}${notes ? `  (${notes})` : ""}`);
+    out.push(heading);
+    for (const b of beats) row(b, false);
   }
   return out;
 }
@@ -241787,7 +241818,7 @@ function writeTextFiles(files, encoding = "utf8") {
 // package.json
 var package_default = {
   name: "@patterkit/cli",
-  version: "0.5.4",
+  version: "0.6.0",
   description: "The `patter` CLI: validate, format, export, and play a Patter project.",
   type: "module",
   license: "MIT",
@@ -241817,7 +241848,7 @@ var package_default = {
   },
   dependencies: {
     "@patterkit/core": "0.3.0",
-    "@patterkit/ops": "0.10.3",
+    "@patterkit/ops": "0.11.0",
     "@wildwinter/simple-vc-lib": "^0.4.1"
   }
 };
@@ -241857,6 +241888,7 @@ Usage:
                  [--scene id] [--block id] [--choices a,b,c] [--seed N]
   patter coverage [path]          Narrative coverage: random playthroughs, find never-reached content
                  [--runs N] [--max-steps M] [--seed S] [--scene id] [--block id]
+                 [--order least|script]   (least reached first, the default, or the script's own order)
                  [--json] [--fail-on-gap]   (--fail-on-gap exits 1 if any beat is never reached)
                  [--propose]   (print auto-proposed @world input drivers instead of running)
   patter resolve <query> [path]   Find a line by id, Game ID, or name: shows where it lives + what it says
@@ -241892,7 +241924,7 @@ var FLAGS = {
   export: { boolean: ["ids", "source-debug"], valued: ["o"] },
   "export-html": { boolean: [], valued: ["o"] },
   play: { boolean: [], valued: ["scene", "block", "choices", "seed"] },
-  coverage: { boolean: ["json", "fail-on-gap", "propose"], valued: ["runs", "max-steps", "seed", "scene", "block"] },
+  coverage: { boolean: ["json", "fail-on-gap", "propose"], valued: ["runs", "max-steps", "seed", "scene", "block", "order"] },
   resolve: { boolean: [], valued: [] },
   usage: { boolean: ["json"], valued: [] },
   report: { boolean: ["json"], valued: ["xlsx"] },
@@ -242150,6 +242182,11 @@ ${count} issue(s)${advisory}`);
         }
         numbers[flag] = n;
       }
+      const order = flags.order ?? "least";
+      if (order !== "least" && order !== "script") {
+        console.error(`coverage: --order '${order}' is not least or script`);
+        return 2;
+      }
       const loaded = loadProject(positionals[0] ?? ".");
       if (flags.propose === true) {
         const drivers = proposeCoverageDrivers(loaded);
@@ -242168,7 +242205,7 @@ ${count} issue(s)${advisory}`);
       if (flags.json === true) console.log(JSON.stringify(report));
       else {
         const nameOf = (id) => loaded.scenes.find((s) => s.id === id)?.name ?? id;
-        for (const line2 of renderCoverageText(report, nameOf)) console.log(line2);
+        for (const line2 of renderCoverageText(report, nameOf, { order })) console.log(line2);
       }
       return flags["fail-on-gap"] === true && report.totals.neverHit > 0 ? 1 : 0;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/cli",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "The `patter` CLI: validate, format, export, and play a Patter project.",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@patterkit/core": "0.3.0",
-    "@patterkit/ops": "0.10.3",
+    "@patterkit/ops": "0.11.0",
     "@wildwinter/simple-vc-lib": "^0.4.1"
   }
 }