mikser-io 10.7.0 → 10.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "10.7.0",
+  "version": "10.9.0",
   "files": [
     "app.js",
     "index.js",

package/src/logger.js

@@ -498,10 +498,21 @@ onLoad(() => {
 //
 // A minimum TOTAL would fix the count and get the other half wrong: four PDFs
 // through Chrome is a small phase and a slow one, and it is exactly the phase
-// worth narrating. Elapsed time is what "long" means, it needs no per-phase
-// tuning, and it applies to the drawn path too — `finished: 5 0s` is the same
-// non-information in a terminal, and its own `0s` says so.
-export const PROGRESS_MIN_MS = 1000
+// worth narrating. Elapsed time is what "long" means and it needs no
+// per-phase tuning.
+//
+// It is an INTERVAL rather than a threshold, and quartiles are gone with it.
+// A quartile is a fraction of the WORK, so it says nothing about how often a
+// line appears: four records land in three seconds on a fast phase and four
+// records cover an hour on a slow one. Time is the axis a reader cares about,
+// so one line per interval, however much work passed in between.
+//
+// This gates the RUNNING commentary only. `progress-finished` is not behind
+// it: every phase says that it ran and what it cost, whatever the duration.
+// Gated, a short phase produced no record at all and a build could not say
+// what it had done — and off a TTY that line is the only place phase timings
+// come from.
+export const PROGRESS_INTERVAL_MS = 30_000
 
 // Which item, not just how far. A phase name alone says a build is doing
 // something; the thing a stuck build needs to say is WHAT it is stuck on.
@@ -519,6 +530,23 @@ function progressDetail(detail) {
     return relative.startsWith('..') ? text : relative
 }
 
+// A duration rounded away to nothing is not a measurement.
+//
+// `finished: 5 0s` was the first version of this and `0s` said nothing;
+// millisecond resolution moved the same defect one order of magnitude down,
+// where nine of a plain build's thirteen phases still printed `0ms`. The
+// clock is the cause rather than the format — Date.now() cannot resolve
+// below a millisecond — so phases are timed with performance.now(), and each
+// band is printed at the resolution it actually has. The floor exists
+// because even a monotonic clock can report two identical readings, and
+// `0.00ms` would be the same lie a third time.
+export function formatDuration(ms) {
+    if (ms >= 1000) return `${(ms / 1000).toFixed(1)}s`
+    if (ms >= 1) return `${Math.round(ms)}ms`
+    if (ms >= 0.01) return `${ms.toFixed(2)}ms`
+    return '<0.01ms'
+}
+
 function emitProgress({ name, total, value, detail }) {
     const at = progressDetail(detail)
     const fields = { code: 'progress', phase: name, total, value }
@@ -551,7 +579,8 @@ export function trackProgress(name, total) {
     // --json would have extended that to every machine reading the output.
     // Losing the graphics is the point; losing the information is not.
     const drawn = !carriesDocument && Boolean(process.stdout.isTTY) && Boolean(runtime.options.info)
-    currentBar = { name, total, value: 0, started: Date.now(), drawn, milestone: 0, detail: null }
+    const now = performance.now()
+    currentBar = { name, total, value: 0, started: now, drawn, lastReport: now, detail: null }
     if (drawn) ensureGauge().show({ section: name, subsection: `0/${total}` }, 0)
 }
 
@@ -567,17 +596,15 @@ export function updateProgress(detail) {
     if (drawn) {
         gauge?.show({ section: name, subsection: `${value}/${total}` }, value / total)
     } else {
-        // Quartiles, not every item: a bar redraws in place and costs one
-        // line, a log record does not. 800 documents is 800 lines of noise if
-        // this counts the way the bar does.
-        //
-        // The milestone advances whether or not the record is emitted. Held
-        // back, every quartile the phase passed under the threshold would fire
-        // in a burst the moment it crossed.
-        const reached = Math.floor((value / total) * 4)
-        if (reached > currentBar.milestone && value < total) {
-            currentBar.milestone = reached
-            if (Date.now() - currentBar.started >= PROGRESS_MIN_MS) emitProgress(currentBar)
+        // One line per interval, not per item and not per quartile: a bar
+        // redraws in place and costs one line, a log record does not, so 800
+        // documents is 800 lines of noise if this counts the way the bar does.
+        // A phase that finishes inside the interval says nothing at all while
+        // it runs — its finished line covers it.
+        const now = performance.now()
+        if (now - currentBar.lastReport >= PROGRESS_INTERVAL_MS && value < total) {
+            currentBar.lastReport = now
+            emitProgress(currentBar)
         }
     }
     if (value >= total) stopProgress()
@@ -587,19 +614,33 @@ export function stopProgress() {
     if (!currentBar) return
     const logger = useLogger()
     const { name, total, value, started } = currentBar
-    const ms = Date.now() - started
+    // Rounded so the field carries real sub-millisecond precision without
+    // float noise; the message formats it separately.
+    const ms = Math.round((performance.now() - started) * 1000) / 1000
     gauge?.hide()
     // Structured either way, so a machine reading --json's stderr gets the
     // same facts a person reads off the bar.
     //
-    // A phase that did not finish is worth a line at any duration — it is a
-    // warning, not progress, and the whole point is that it is unexpected.
+    // This line has to stand alone. With the running commentary on an
+    // interval it is the ONLY record most phases produce, and `Documents
+    // import finished: 5 0s` said neither what the five were nor how long it
+    // took — a count with no subject and a duration rounded away to nothing.
+    //
+    // The subject is the PHASE, not an item. The last entity a phase happened
+    // to walk is not what the phase was about: seven journal phases in a row
+    // reported the same `/layouts/page.hbs` because that is where the walk
+    // ended, and `Files import finished: 3, last .../social-fb.svg` put a
+    // filename into the build log that nothing had anything to say about — it
+    // broke a test asserting that file is never mentioned, which is exactly
+    // the misreading it invites. `Files import finished: 3 in 3ms` already
+    // says what finished, how much of it, and what it cost. The running
+    // records keep the item, because there it shows MOVEMENT.
     if (value < total) {
         logger.warn({ code: 'progress-unfinished', phase: name, total, value, missing: total - value },
-            '%s unfinished: %d', name, total - value)
-    } else if (ms >= PROGRESS_MIN_MS) {
+            '%s unfinished: %d of %d after %s', name, total - value, total, formatDuration(ms))
+    } else {
         logger.info({ code: 'progress-finished', phase: name, total, ms },
-            '%s finished: %d %ds', name, total, Math.round(ms / 1000))
+            '%s finished: %d in %s', name, total, formatDuration(ms))
     }
     currentBar = null
 }