@patterkit/ops 0.10.4 → 0.11.0

package/dist/index.d.ts

@@ -375,6 +375,10 @@ interface CoverageBeat {
     reachedRuns: number;
     /** reachedRuns / runs-executed * 100; 0 iff never reached. */
     reachPct: number;
+    /** Reached, but in fewer than {@link RARE_REACH_PCT}% of runs: content that CAN play but hangs on an
+     *  unlikely route or a condition that is nearly always false. Worth a look, not necessarily a fault
+     *  (one of several random picks is rare by design). Absent on a never-reached beat. */
+    rare?: true;
     /** Set on a never-reached beat that is gated on a host-scope ref (`@world.x`) nothing writes and no
      *  driver provides, i.e. it may just need an input, not be truly dead. Lists the offending refs. */
     needsInput?: string[];
@@ -414,12 +418,16 @@ interface CoverageReport {
         block?: string;
     };
     beats: CoverageBeat[];
+    /** `rare` counts beats reached in fewer than `rareThresholdPct`% of runs (and not never). */
     totals: {
         beats: number;
         covered: number;
         neverHit: number;
+        rare: number;
         coveragePct: number;
     };
+    /** The reach % below which a reached beat counts as rare ({@link RARE_REACH_PCT}). */
+    rareThresholdPct: number;
     /** How each run ended, for the summary header. */
     termination: {
         ended: number;
@@ -437,6 +445,15 @@ interface CoverageReport {
     dryChoices: DryChoice[];
     cancelled: boolean;
 }
+/** Below this share of runs, a beat that WAS reached is flagged rare. Coverage used to flag only the never
+ *  reached, so a beat that played in 0.5% of runs looked as healthy as one that played in all of them. */
+declare const RARE_REACH_PCT = 5;
+/**
+ * The beats least reached first: never-reached at the top, then by reach %, then by times played, with
+ * script order kept among equals. The order both Patterpad's Coverage window and `patter coverage` lead
+ * with, because the beats a sweep reaches least are the ones worth a look.
+ */
+declare function leastReachedFirst(beats: readonly CoverageBeat[]): CoverageBeat[];
 /**
  * Auto-propose coverage drivers by scanning the project's conditions for host-scope refs (`@world.x`)
  * and the literals they are compared against. Each proposed driver is `recurring`/`sometimes` and offers
@@ -466,9 +483,14 @@ interface CoverageAsyncHooks extends CoverageHooks {
  * it for a full sample.
  */
 declare function runCoverageAsync(loaded: LoadedProject, options?: CoverageOptions, hooks?: CoverageAsyncHooks): Promise<CoverageReport>;
-/** Render a coverage report as the CLI's readable text: a summary, then a per-scene beat table with
- *  never-reached (0%) rows marked. */
-declare function renderCoverageText(report: CoverageReport, sceneName?: (id: string) => string): string[];
+/** Which order the beat table is in: least reached first (the default: the rows worth a look lead), or
+ *  the script's own order, scene by scene. */
+type CoverageOrder = "least" | "script";
+/** Render a coverage report as the CLI's readable text: a summary, then the beat table with never-reached
+ *  and rarely reached rows marked, least reached first unless `order` says script order. */
+declare function renderCoverageText(report: CoverageReport, sceneName?: (id: string) => string, opts?: {
+    order?: CoverageOrder;
+}): string[];
 
 /** Resolve where a flow starts: an explicit override, else the project's authored `start`, else `{}`
  *  (the runtime's first-scene default). Shared by `runPlay` and `runCoverage`. */
@@ -1114,4 +1136,4 @@ declare function classesForChannel(classes: DocumentationClass[], channel: strin
  */
 declare function resolveDocumentation(loaded: LoadedProject, channel: string): Map<string, DocLine[]>;
 
-export { AUTHORING_HANDLED, type ApplyStats, type BundlePosture, CONFLICT_SIDECAR, type CharacterReport, type Conflict, type ConflictKind, type CoverageAsyncHooks, type CoverageBeat, type CoverageHooks, type CoverageOptions, type CoverageReport, type DocumentManifest, type FormatResult, GAME_SCOPES_OWNER, type GameScopes, type GameScopesIssue, type HygieneIssue, type InitOptions, type InitResult, type InitVcs, type LoadedProject, type LocCatalog, type LocEntry, type LocaleReport, type MergeFileType, type MergeResult, type MergedShard, PATTER_SCOPES_FILE, PATTER_SCOPES_OWNER, type PinPlan, type PinnedName, type PlannedWrite, type PlayEvent, type PlayOptions, type PlayOutcome, type PlayResult, type ProvenanceCheck, type ReplaceHit, type ReplaceOptions, type ReplacePlan, type ReportData, type ReportTotals, type ResolveEntry, SHARD_EXTENSIONS, type SceneReport, type ScriptDoc, type ScriptElement, type SearchFocus, type UnpackMergeResult, type UnpackResult, UnsafeEntryError, UnsupportedMergeError, type ValidateResult, type VoiceLine, type VoiceScript, type VoicedCounts, type WebExport, type WrittenCounts, applyLoc, applySceneOrder, applyWrites, bundleOutputPath, catalogToJson, catalogToPo, catalogToXlsx, classesForChannel, defaultGameScopesDir, detectMergeType, discoverGameScopes, drivableScopes, extractLoc, findProjectFile, gameScopeTokens, gameScopesCatalogue, gameScopesSnapshot, hostScopeTokens, jsonToCatalog, listProjectTags, loadProject, loadProjectLanding, patterScopesFile, patterScopesStale, patterScopesWrite, planPins, planReturnedWorld, planShareScopes, planWorldSave, poToCatalog, previewRegistry, proposeCoverageDrivers, reachabilityIssues, readGameScopes, renderCoverageText, renderPlay, renderReportText, resolveDocumentation, resolveStart, runCoverage, runCoverageAsync, runExport, runExportFull, runExportHtml, runExportWeb, runFormat, runInit, runMerge, runPack, runPlay, runPropertyUsage, runReplace, runReport, runReportXlsx, runResolve, runScriptDoc, runSearch, runStatusBrowse, runTagBrowse, runUnpack, runUnpackMerge, runValidate, runVoiceScript, scanAudioStatus, sceneIdForShard, scriptToDocx, scriptToPdf, sidecarIssues, vcsConfigWrites, voiceScriptToXlsx, worldSettingsScopes, xlsxToCatalog };
+export { AUTHORING_HANDLED, type ApplyStats, type BundlePosture, CONFLICT_SIDECAR, type CharacterReport, type Conflict, type ConflictKind, type CoverageAsyncHooks, type CoverageBeat, type CoverageHooks, type CoverageOptions, type CoverageOrder, type CoverageReport, type DocumentManifest, type FormatResult, GAME_SCOPES_OWNER, type GameScopes, type GameScopesIssue, type HygieneIssue, type InitOptions, type InitResult, type InitVcs, type LoadedProject, type LocCatalog, type LocEntry, type LocaleReport, type MergeFileType, type MergeResult, type MergedShard, PATTER_SCOPES_FILE, PATTER_SCOPES_OWNER, type PinPlan, type PinnedName, type PlannedWrite, type PlayEvent, type PlayOptions, type PlayOutcome, type PlayResult, type ProvenanceCheck, RARE_REACH_PCT, type ReplaceHit, type ReplaceOptions, type ReplacePlan, type ReportData, type ReportTotals, type ResolveEntry, SHARD_EXTENSIONS, type SceneReport, type ScriptDoc, type ScriptElement, type SearchFocus, type UnpackMergeResult, type UnpackResult, UnsafeEntryError, UnsupportedMergeError, type ValidateResult, type VoiceLine, type VoiceScript, type VoicedCounts, type WebExport, type WrittenCounts, applyLoc, applySceneOrder, applyWrites, bundleOutputPath, catalogToJson, catalogToPo, catalogToXlsx, classesForChannel, defaultGameScopesDir, detectMergeType, discoverGameScopes, drivableScopes, extractLoc, findProjectFile, gameScopeTokens, gameScopesCatalogue, gameScopesSnapshot, hostScopeTokens, jsonToCatalog, leastReachedFirst, listProjectTags, loadProject, loadProjectLanding, patterScopesFile, patterScopesStale, patterScopesWrite, planPins, planReturnedWorld, planShareScopes, planWorldSave, poToCatalog, previewRegistry, proposeCoverageDrivers, reachabilityIssues, readGameScopes, renderCoverageText, renderPlay, renderReportText, resolveDocumentation, resolveStart, runCoverage, runCoverageAsync, runExport, runExportFull, runExportHtml, runExportWeb, runFormat, runInit, runMerge, runPack, runPlay, runPropertyUsage, runReplace, runReport, runReportXlsx, runResolve, runScriptDoc, runSearch, runStatusBrowse, runTagBrowse, runUnpack, runUnpackMerge, runValidate, runVoiceScript, scanAudioStatus, sceneIdForShard, scriptToDocx, scriptToPdf, sidecarIssues, vcsConfigWrites, voiceScriptToXlsx, worldSettingsScopes, xlsxToCatalog };

package/dist/index.js

@@ -1591,6 +1591,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);
@@ -1880,6 +1884,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,
@@ -1888,13 +1893,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,
@@ -1902,7 +1909,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(),
@@ -1926,14 +1934,19 @@ async function runCoverageAsync(loaded, options = {}, hooks = {}) {
   }
   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?)`);
@@ -1945,25 +1958,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;
 }
@@ -4076,6 +4107,7 @@ export {
   GAME_SCOPES_OWNER,
   PATTER_SCOPES_FILE,
   PATTER_SCOPES_OWNER,
+  RARE_REACH_PCT,
   SHARD_EXTENSIONS,
   UnsafeEntryError,
   UnsupportedMergeError,
@@ -4099,6 +4131,7 @@ export {
   hostScopeTokens,
   isUnsafeEntry2 as isUnsafeEntry,
   jsonToCatalog,
+  leastReachedFirst,
   listProjectTags,
   loadProject,
   loadProjectLanding,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patterkit/ops",
-  "version": "0.10.4",
+  "version": "0.11.0",
   "description": "The shared operations layer: every project operation (load, validate, export, format, play, ...) as a pure function, consumed by the patter CLI and Patterpad alike.",
   "type": "module",
   "license": "MIT",