mikser-io 10.5.0 → 10.6.0

package/package.json

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

package/src/engine.js

@@ -25,8 +25,8 @@ import Queue from 'p-queue'
 import packageInfo from '../package.json' with { type: 'json' }
 import { attachServerCliOptions, setupServer } from './server.js'
 import {
-    createMikserLogger, setLogLevel, rememberBaseLevel, installLogLevel, resetLogLevel,
-    applyInstalledLogLevel, installedLogLevel, LOG_LEVELS, INSTALLED_LOG_TTL_MS,
+    createMikserLogger, rememberBaseLevel, applyLogRequest,
+    LOG_LEVELS, INSTALLED_LOG_TTL_MS,
 } from './logger.js'
 import { inputHashOf } from './utils.js'
 import { createTrack, mergeTrack } from './track.js'
@@ -685,14 +685,14 @@ The full version, with what each code means: docs/diagnostics.md`)
         // logger — the whole reason --debug did nothing.
         runtime.options.info = true
         const asked = runtime.options.log
-        if (asked) {
-            if (!LOG_LEVELS.includes(asked)) {
-                throw new Error(`--log ${asked}: no such level. Levels: ${LOG_LEVELS.join(', ')}`)
-            }
-            setLogLevel(asked)
-            // A bar on top of debug output is noise, and silent means silent.
-            if (asked === 'trace' || asked === 'debug' || asked === 'silent') runtime.options.info = false
-        }
+        // The same call the instance makes for a forwarded request — see
+        // applyLogRequest. Two implementations drifted within one commit.
+        const logRefusal = applyLogRequest({
+            log: asked,
+            logInstall: runtime.options.logInstall,
+            logReset: runtime.options.logReset,
+        })
+        if (logRefusal) throw new Error(logRefusal)
         rememberBaseLevel(asked && LOG_LEVELS.includes(asked) ? asked : 'info')
 
         // Resolve folders inside onInitialize so journal.js and

package/src/instance.js

@@ -38,7 +38,7 @@ import { onLoaded } from './lifecycle.js'
 import { renderErrorCount } from './report.js'
 import { runReportOnly } from './engine.js'
 import {
-    setLogLevel, installLogLevel, resetLogLevel, restingLogLevel,
+    setLogLevel, restingLogLevel, applyLogRequest, LOG_LEVELS,
 } from './logger.js'
 import { emitReport } from './report.js'
 import { pluginOptionsFrom } from './cli.js'
@@ -240,6 +240,17 @@ function captureOutput(onChunk) {
 // than by content hash — the hash would require the client to import its
 // config, which is most of the startup forwarding exists to skip, and it is
 // not what tells the two apart. Different configs are different files.
+// Does this request name a level that does not exist? Pure, so the refusal
+// can be decided before anything is applied.
+function logRequestRefusal(request) {
+    for (const [flag, level] of [['--log', request?.log], ['--log-install', request?.logInstall]]) {
+        if (level !== undefined && level !== null && !LOG_LEVELS.includes(level)) {
+            return `${flag} ${level}: no such level. Levels: ${LOG_LEVELS.join(', ')}`
+        }
+    }
+    return null
+}
+
 function configMismatch(theirs) {
     if (!theirs) return null
     const mine = path.resolve(runtime.options.config ?? 'mikser.config.js')
@@ -369,6 +380,26 @@ function refuseClear(socket, request) {
     return true
 }
 
+// A level the instance cannot use.
+//
+// Validated where the request ARRIVES rather than where it is applied, because
+// applying it is exactly what a bad level cannot do: setLogLevel returns false
+// and, before this, nobody read it — so `--log chatty` exited 1 locally and
+// built normally with a watcher up. The refusal frame is how the instance says
+// no to everything else, and a client that mistypes a level deserves the same
+// answer whether or not something happens to be listening.
+function refuseLogLevel(socket, request) {
+    const refusal = logRequestRefusal(request)
+    if (!refusal) return false
+    frame(socket, {
+        type: 'refused',
+        reason: refusal,
+        detail: 'The instance would otherwise have built normally and said nothing, which is the '
+            + 'forwarded-versus-local split this surface exists to remove.',
+    })
+    return true
+}
+
 // Which process to restart.
 //
 // "Restart it" is only actionable if you know which `it` — and the machine
@@ -428,15 +459,25 @@ async function withRequestOutput(request, run) {
     // a watcher's own cycle before or after keeps the level it was running at.
     // An installed level is different and deliberately not touched here — it
     // outlives the request, which is its whole point.
-    if (request.logReset) resetLogLevel()
-    if (request.logInstall) installLogLevel(request.logInstall)
-    if (request.log) setLogLevel(request.log)
-
-    for (const key of ['json', 'tool', 'tools', 'requested']) {
+    // Captured BEFORE applyLogRequest, which writes `info`.
+    //
+    // `info` is here because --log silent turns the progress bar off through
+    // it, and without a restore one silent request left the instance with no
+    // bar for the rest of its life. Capturing after the call would have
+    // recorded the value the call just wrote and restored nothing — the same
+    // shape of mistake, one line further on.
+    for (const key of ['json', 'tool', 'tools', 'requested', 'info']) {
         prior[key] = runtime.options[key]
         if (request[key]) runtime.options[key] = request[key]
     }
 
+    // The same call the argv path makes — see applyLogRequest. The level was
+    // validated at arrival by refuseLogLevel, so a refusal here is impossible;
+    // it is asserted rather than ignored, because "cannot happen" is how the
+    // first version of this silently accepted a bad level.
+    const refusal = applyLogRequest(request)
+    if (refusal) throw new Error(refusal)
+
     // Whatever the client's argv said about a PLUGIN's options.
     //
     // The instance parsed its own argv and never saw the client's, so a flag a
@@ -558,6 +599,7 @@ export function serveInstance() {
                     // writes anything.
                     if (refuseUnknownFlags(socket, request)) return
                     if (refuseClear(socket, request)) return
+                    if (refuseLogLevel(socket, request)) return
                     const wrongConfig = configMismatch(request.config)
                     if (wrongConfig) return refuseConfig(socket, request, wrongConfig)
                     const movedFile = await configStale()

package/src/logger.js

@@ -491,16 +491,49 @@ export function trackProgress(name, total) {
     if (!name || !total) return
     const logger = useLogger()
     logger.debug('%s started: %d', name, total)
-    if (!process.stdout.isTTY || !runtime.options.info) return
-    currentBar = { name, total, value: 0, started: Date.now() }
-    ensureGauge().show({ section: name, subsection: `0/${total}` }, 0)
+    // The bar writes to stdout, and stdout is where --json and --tool put
+    // their DOCUMENT. Forwarded, those writes are captured and framed to the
+    // client, so the gauge landed inside the JSON:
+    // `^[[?25lDocuments import: >416/800` at byte 0, and JSON.parse threw —
+    // 4 runs in 10 at the default level on an 800-document corpus.
+    //
+    // Checked HERE rather than through runtime.options.info, because this is
+    // the actual invariant and info is a preference. A preference can be
+    // forgotten on a path; an invariant stated at the one place a bar starts
+    // cannot.
+    const carriesDocument = runtime.options?.json || runtime.options?.tool || runtime.options?.tools
+
+    // TRACKED always, DRAWN only where a bar belongs.
+    //
+    // The two used to be one decision, so anything that could not draw also
+    // stopped counting — and `stopProgress` returns early without a bar, which
+    // is where the "finished: N in Ns" line comes from. A piped build
+    // therefore reported no phase timings at all, and suppressing the bar for
+    // --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 }
+    if (drawn) ensureGauge().show({ section: name, subsection: `0/${total}` }, 0)
+    else logger.info({ code: 'progress', phase: name, total, value: 0 }, '%s: 0/%d', name, total)
 }
 
 export function updateProgress() {
     if (!currentBar) return
     currentBar.value++
-    const { name, total, value } = currentBar
-    gauge?.show({ section: name, subsection: `${value}/${total}` }, value / total)
+    const { name, total, value, drawn } = currentBar
+    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.
+        const reached = Math.floor((value / total) * 4)
+        if (reached > currentBar.milestone && value < total) {
+            currentBar.milestone = reached
+            useLogger()?.info({ code: 'progress', phase: name, total, value },
+                '%s: %d/%d', name, value, total)
+        }
+    }
     if (value >= total) stopProgress()
 }
 
@@ -509,11 +542,15 @@ export function stopProgress() {
     const logger = useLogger()
     const { name, total, value, started } = currentBar
     gauge?.hide()
+    // Structured either way, so a machine reading --json's stderr gets the
+    // same facts a person reads off the bar.
     if (value < total) {
-        logger.warn('%s unfinished: %d', name, total - value)
+        logger.warn({ code: 'progress-unfinished', phase: name, total, value, missing: total - value },
+            '%s unfinished: %d', name, total - value)
     } else {
-        const elapsed = Math.round((Date.now() - started) / 1000)
-        logger.info('%s finished: %d %ds', name, total, elapsed)
+        const ms = Date.now() - started
+        logger.info({ code: 'progress-finished', phase: name, total, ms },
+            '%s finished: %d %ds', name, total, Math.round(ms / 1000))
     }
     currentBar = null
 }
@@ -528,6 +565,38 @@ export function updateProgressDetails(details) {
     )
 }
 
+// What a caller asked for about logging, applied the same way from argv and
+// from a forwarded request.
+//
+// It was written twice and the copies drifted immediately: the argv path threw
+// on an unknown level and set `info`, the forwarded path called setLogLevel and
+// ignored the false it returns. So `--log chatty` exited 1 locally and built
+// normally with a watcher up, and `--log silent` left the progress bar running
+// on an instance. The same forwarded/local split --json and --force each had,
+// and this feature's own argument against itself: a flag that lies is worse
+// than a flag that is missing.
+//
+// Returns an error STRING rather than throwing, because the two callers need
+// different things from a failure — argv throws, the instance refuses over the
+// socket — and a shared implementation should not decide that for them.
+export function applyLogRequest({ log, logInstall, logReset } = {}) {
+    for (const [flag, level] of [['--log', log], ['--log-install', logInstall]]) {
+        if (level !== undefined && level !== null && !LOG_LEVELS.includes(level)) {
+            return `${flag} ${level}: no such level. Levels: ${LOG_LEVELS.join(', ')}`
+        }
+    }
+    if (logReset) resetLogLevel()
+    if (logInstall) installLogLevel(logInstall)
+    if (log) setLogLevel(log)
+
+    // A bar on top of debug output is noise, and silent means silent.
+    const level = log || logInstall
+    if (level === 'trace' || level === 'debug' || level === 'silent') {
+        runtime.options.info = false
+    }
+    return null
+}
+
 // An installed level, disclosed and expired, once per cycle.
 //
 // Disclosed for the reason an installed command is: it is state left on a live