oracular 0.12.0 → 0.12.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.12.1
+
+### Patch Changes
+
+- [#64](https://github.com/Yuribenjamin/oracular/pull/64) [`c108ca9`](https://github.com/Yuribenjamin/oracular/commit/c108ca92b4b66b90749664379bc676a230462726) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **`replay` shows the reveals it could not score.** A reveal whose window runs past the end of the log is not scored for precision, since its verdict is not in yet, but an outcome it preceded still counts for recall, so a short log printed `reveals 0` beside `recall 100.0% of 1`, and `--json` showed `reveals: 0, caught: 1, censored: 1`. Both numbers were right and the table did not say why. The text table now shows such reveals in the row (`0 (+1 censored)`) with a footnote that says what recall still counts, and a log shorter than an intent's scoring window, in which every reveal and point is censored, gets a warning on stderr that points at `--window`. The `--json` report is unchanged: `censored` was already there. Found by the second production integration on a one-minute log with the default one-hour window.
+
 ## 0.12.0
 
 ### Minor Changes

package/dist/cli.js

@@ -363,7 +363,7 @@ function formatIntent(intent) {
       ["threshold", "reveals", "per user", "precision", "recall", "median lead time"],
       intent.thresholds.map((t) => [
         `${t.threshold}${t.configured ? " *" : ""}`,
-        String(t.reveals),
+        t.censored > 0 ? `${t.reveals} (+${t.censored} censored)` : String(t.reveals),
         num(t.revealsPerUser, 2),
         pct(t.precision),
         `${pct(t.recall)} of ${t.outcomes}`,
@@ -371,9 +371,9 @@ function formatIntent(intent) {
       ])
     )
   );
-  const censored = intent.thresholds.reduce((acc, t) => Math.max(acc, t.censored), 0);
+  const censored = intent.thresholds.some((t) => t.censored > 0);
   out.push(
-    `* the threshold your config resolves for this intent.${censored > 0 ? ` Reveals whose window runs past the end of the log are not scored (up to ${censored} per threshold).` : ""}`
+    `* the threshold your config resolves for this intent.${censored ? " A reveal whose window runs past the end of the log (the +n) is not scored for precision, since its verdict is not in yet; an outcome it preceded still counts as caught for recall." : ""}`
   );
   out.push("");
   out.push(
@@ -1310,9 +1310,22 @@ async function replayCommand(argv, io) {
     if (error instanceof RangeError) throw new UsageError(error.message);
     throw error;
   }
+  warnShortLog(report, io);
   io.stdout(args.json ? formatJson(report) : formatText(report));
   return 0;
 }
+function warnShortLog(report, io) {
+  if (report.start === null || report.end === null) return;
+  const span = report.end - report.start;
+  for (const intent of report.intents) {
+    if (span < intent.window) {
+      io.stderr(
+        `oracular: warning: ${intent.intent}: the log spans ${formatDuration(span)}, less than its ${formatDuration(intent.window)} scoring window, so every reveal and point is censored and only recall can be counted. Pass --window with a duration shorter than the log, or record for longer than the window.
+`
+      );
+    }
+  }
+}
 async function tuneCommand(argv, io) {
   const args = parseTuneArgs(argv);
   if (args.help) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oracular",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "On-device intent engine. Your app learns when the user is ready. Nothing leaves the device.",
   "keywords": [
     "oracular",