mikser-io 9.97.0 → 9.99.0

package/docs/diagnostics.md

@@ -385,9 +385,21 @@ the content: an upgraded renderer, a changed helper, a dependency that shifted
 under the build.
 
 Only entities that actually rendered can drift, so an ordinary build reports
-on what moved. Under `--force` everything re-renders with unchanged inputs,
-which makes it a full sweep — **`mikser --force` after a package upgrade is
-the regression check**.
+on what moved. Under `--force` every ENTITY re-renders with unchanged inputs,
+which makes it the check for a renderer, helper or dependency that shifted —
+**`mikser --force` after a package upgrade is the regression check for
+rendered output**.
+
+It is not a full sweep, and calling it one was wrong. Derivatives are outside
+it: an asset is re-derived when its source changes or its preset's `revision`
+moves, and `--force` is neither — so on a site with image presets, `--force`
+re-renders the documents and touches no derivative at all. A sharp upgrade,
+which is exactly the kind of dependency shift this paragraph promises to
+catch, is invisible to it.
+
+Use `--render-presets` for that half, and `--fingerprint` before and after to
+compare both halves at once — it hashes the derivatives too, which is the
+thing `find out -type f` cannot do.
 
 ### The rest, briefly
 

package/package.json

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

package/src/engine.js

@@ -579,11 +579,16 @@ Which check answers which question:
                             with themselves.
 
   Did an upgrade change what a render produces?
-      --force               re-renders everything and reports output-drift:
+      --force               re-renders every ENTITY and reports output-drift:
                             same inputs, different bytes. This is the one that
                             catches a renderer, helper or dependency moving
                             under the build. It also reconciles deletions.
 
+                            NOT derivatives. Assets are re-derived on a preset
+                            revision or a source change, and --force is
+                            neither — so a sharp upgrade is invisible to it.
+                            Use --render-presets for that half.
+
   Do the URLs in the output point at anything?
       (runs every build)    reads the emitted html and css and resolves each
                             reference the way a browser would. Reports what
@@ -610,6 +615,15 @@ Which check answers which question:
                             tree, stable across runs. Take it before and after
                             an upgrade and compare.
 
+  Is this build one a person is waiting on?
+      (automatic)           runtime.options.requested is true for a build a
+                            client asked for — including one forwarded to a
+                            running instance — and false for a watcher's own
+                            cycle. An expensive check reads it to stand down in
+                            the dev loop without standing down forever: an
+                            instance is ALWAYS in watch mode, so watch alone
+                            answers the wrong question.
+
   What did this build do, and cost?
       --json                the whole report as one document on stdout, with
                             every warning carrying a stable code, and per-phase
@@ -1473,10 +1487,10 @@ The full version, with what each code means: docs/diagnostics.md`)
         const brokenTargets = await reportBrokenReferences(useLogger())
         await reportMissingAssets(useLogger(), brokenTargets)
 
-        // After the cycle, and only under --json. stdout has been kept clear
-        // for exactly this (the logger writes to stderr under --json), so the
-        // document is the only thing on it and can be piped to jq.
-        emitReport()
+        // The report is NOT emitted here any more. This hook is registered
+        // when the engine is imported, so it runs first among finalized hooks
+        // and every plugin's findings would land after the document was
+        // written. runtime.finalize() emits it once every hook has run.
 
         // Non-zero for a one-shot build, so `mikser && mikser --audit-output` cannot
         // pass with every page in the site stale. `exitCode` rather than

package/src/instance.js

@@ -399,7 +399,20 @@ function refuseStale(socket, movedFile) {
 // not put the instance into json mode for everyone.
 async function withRequestOutput(request, run) {
     const prior = {}
-    for (const key of ['json', 'tool', 'tools']) {
+    // `requested` is not a flag the client sent — it is the fact that a client
+    // sent anything at all.
+    //
+    // An instance is always in watch or server mode, so a plugin asking "am I
+    // in the dev loop" gets `yes` for a build a PERSON just typed and is
+    // waiting on. An expensive check that stands down in the dev loop then
+    // stands down forever on a project whose documented model is a watcher
+    // always up — it never runs, and says nothing, which is the failure this
+    // whole surface exists to remove.
+    //
+    // Set for the duration of the request and restored with the rest, so a
+    // watcher's own cycle before or after is unaffected.
+    request = { ...request, requested: true }
+    for (const key of ['json', 'tool', 'tools', 'requested']) {
         prior[key] = runtime.options[key]
         if (request[key]) runtime.options[key] = request[key]
     }

package/src/report.js

@@ -133,6 +133,10 @@ export function resetReport() {
 // an import here would close the cycle.
 runtime.resetReport = resetReport
 
+// And so it can emit the report AFTER every finalized hook, for the same
+// reason and by the same route. See runtime.finalize().
+runtime.emitReport = emitReport
+
 // End of a cycle: stamp it, file it, and wake anyone waiting on it.
 export function finishCycle() {
     if (!runtime.state?.cycle || runtime.state.cycle.finishedAt) return

package/src/runtime.js

@@ -213,6 +213,23 @@ const runtime = {
     async finalize(signal) {
         await this.callHooks(this.hooks.finalize, signal, 'finalize')
         await this.callHooks(this.hooks.finalized, signal, 'finalized')
+
+        // The report is the LAST thing that happens, after every hook that
+        // could still add to it.
+        //
+        // It used to be emitted from the engine's own onFinalized — which is
+        // registered when the engine module is imported, so it ran FIRST among
+        // finalized hooks and every plugin's findings landed after the
+        // document was already written. A plugin could print a warning to the
+        // console and have it absent from --json, with nothing to suggest the
+        // two disagreed.
+        //
+        // That is not a lint bug or a schemas bug; it is one ordering bug that
+        // every plugin inherits, which is why it is fixed here rather than in
+        // each of them. A finding raised through logger.warn reaches the
+        // report because the report is a VIEW of that stream — and a view has
+        // to be taken after the writing stops.
+        await this.emitReport?.()
     },
 
     async sync(operation) {