mikser-io 9.88.0 → 9.93.0

package/docs/diagnostics.md

@@ -133,8 +133,65 @@ anything.
 Add `--json` for the whole report as a machine-readable object. Exits `3`
 when the entity cannot be found.
 
+Every coded warning and fault prints its code on the console, in brackets
+before the sentence:
+
+```
+🟡 [output-drift] Output changed with unchanged inputs: /documents/index.html → /index.html
+🟡 [reference-wrong-base] Points at the wrong place: ...
+```
+
+The code is added, not substituted: the sentence is what a person reads and the
+code is what a script matches. Both come from the same field on the same
+record, so the console and the report cannot drift apart — which they had. The
+report called it `output-drift` and the console said "produced different bytes
+from the same inputs", so anything watching the build had to match prose, the
+half that is free to be reworded, while the stable identifier appeared only in
+this document.
+
+`--audit-output --json` writes its verdict as a document — `verdict`,
+`snapshots`, a `summary` of the five counts, and the entries behind each. It
+reported through the log and wrote nothing to stdout before, which made the
+check a deploy script most wants the one it could not read. Exit codes are
+unchanged: 2 for FAIL.
+
 ### `--json`
 
+The report carries `timings`: what each phase COST, in milliseconds, for the
+cycle being reported.
+
+```
+"timings": {
+  "total": 114,              // the phases below, summed — this cycle
+  "processUptime": 415.5,    // how long THIS PROCESS has been alive
+  "phases": [
+    { "phase": "load",   "ms": 80.5, "calls": 1 },
+    { "phase": "import", "ms": 17.5, "calls": 1 }
+  ]
+}
+```
+
+Ordered slowest first, so a diff between two versions leads with what moved.
+This exists because the report said what was *done* and never what it *took*: a
+preset fan-out that scanned the whole catalog every cycle shipped and ran for
+four releases, with byte-identical output and every check passing, while the
+build was twice as slow. An upgrade check could prove no bytes moved and could
+not prove the speed had not halved.
+
+`finishedAt - startedAt` is not this — it spans the processing cycle only,
+measured at 12ms of a 443ms run, leaving boot, the config graph, the plugin
+load and the import scan with no number anywhere.
+
+`processUptime` is deliberately not called "elapsed". For a one-shot it is the
+whole run, and subtracting `total` gives what the phases do not cover — module
+loading and engine construction, which happen before any hook. For a build
+forwarded to a watcher it is the *instance's* age, which says nothing about the
+build.
+
+Milliseconds because the console's progress lines round to whole seconds, so a
+phase that doubled from 400ms to 800ms prints `0s` both times — and they are
+suppressed off a TTY, which is every CI run and every `--json` invocation.
+
 A build report on stdout, as JSON. Logs and the banner move to stderr
 under this flag, so stdout parses whole.
 
@@ -948,6 +1005,15 @@ surfaces that turn silence into a statement:
     sitemap — and warns under `asset-missing`. Where both can see the
     same file, the output scan reports it and this one stays quiet.
 
+  A `url()` inside a **custom property** is resolved from the stylesheet that
+  substitutes it, for both of these questions and for the climb check below.
+  It is substituted where it is *used*, so the page that declared it in a
+  style attribute is not its base — a bundle at `styles/` is. Every emitted
+  stylesheet is a candidate, since which one substitutes the variable is not
+  knowable from the bytes; a clean resolution settles it, one that resolves
+  only by climbing is a genuine over-deep against *that* base, and a url that
+  resolves from none of them is reported as broken.
+
   A url under the assets folder gets a cause rather than a guess. Whether a
   preset covers a file is decided by `match` against the entity id, which is
   not visible from a url, so the assets plugin is asked and the answer is one
@@ -971,7 +1037,11 @@ surfaces that turn silence into a statement:
 - **A link that works only by accident** — a url with one `..` too many
   still loads, because a browser discards a climb above the origin root
   rather than failing. Reported under `reference-over-deep`, separately
-  from the outright failures, and grouped by how far each climbed:
+  from the outright failures, and grouped by how far each climbed. A custom
+  property is judged against its stylesheet here too: judged against the page
+  it produced a climb report for references that are correct, with a reason
+  — "a browser discards the extra `..`" — that was false for them, which
+  sends the reader to fix a base that is right:
   - **One url, or several climbing different distances** — each is a
     latent 404, working today and broken as soon as the same markup
     renders one level deeper.

package/package.json

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

package/src/engine.js

@@ -125,7 +125,7 @@ async function reportBrokenReferences(logger) {
     // because the preset does not cover that file. Confidently naming the
     // wrong cause is worse than naming none, so a real answer wins over the
     // heuristic wherever there is one.
-    const explain = runtime.state?.assets?.explainMissing
+    const explain = runtime.engine?.assets?.explainMissing
     const reasons = new Map()
     if (explain) {
         // Every broken entry, not the ones that happen to sort first. The cap
@@ -261,7 +261,7 @@ async function reportMissingAssets(logger, alreadyReported = new Set()) {
     // every page on the site, and a thousand lines of it buries whatever else
     // the build said.
     const SHOWN = 10
-    const explain = runtime.state?.assets?.explainMissing
+    const explain = runtime.engine?.assets?.explainMissing
     for (const [destination, ids] of missing.slice(0, SHOWN)) {
         // Same question, same answer, wherever the symptom surfaces. This path
         // sees urls that never reach an html file at all — a sitemap, a feed —
@@ -381,6 +381,33 @@ export async function runReportOnly(request = {}) {
             await runtime.manifest.auditOutput()
         const total = runtime.manifest.size()
 
+        // The document, under --json.
+        //
+        // This is the check a deploy script wants and it was the one that
+        // could not be read programmatically: it reported through the log and
+        // wrote nothing to stdout, so `--audit-output --json` returned zero
+        // bytes and exit 0 or 2 — a caller had to parse prose, or trust the
+        // exit code and lose every detail behind it.
+        //
+        // Emitted here and returned immediately, because the log lines below
+        // are the human rendering of exactly this and printing both would put
+        // the prose on stderr for no one.
+        if (json) {
+            process.stdout.write(JSON.stringify({
+                verdict,
+                snapshots: total,
+                summary: {
+                    missing: missing.length,
+                    mismatched: mismatched.length,
+                    unverifiable: unverifiable.length,
+                    orphaned: orphaned.length,
+                    collisions: collisions.length,
+                },
+                missing, mismatched, unverifiable, orphaned, collisions,
+            }, null, 2) + '\n')
+            return verdict === 'FAIL' ? 2 : 0
+        }
+
         for (const e of missing)      logger.error('Missing:    %s (entity %s)', e.destination, e.id)
         for (const e of mismatched)   logger.error('Mismatched: %s (entity %s)%s', e.destination, e.id,
             e.writtenBy ? ` — the bytes on disk are ${e.writtenBy}'s` : '')
@@ -495,6 +522,58 @@ export async function setup(options) {
             .option('-e --runtime-folder <folder>', 'set mikser runtime folder relative to working folder', 'runtime')
         attachServerCliOptions(runtime.engine.commander)
 
+        // Which check answers which question.
+        //
+        // The boundaries between these are real and none of them is redundant,
+        // but that knowledge lived only in commit messages — which are the
+        // wrong place for it, because nobody reads them before they need the
+        // answer. A caller choosing how to verify a build was left to learn it
+        // by experiment, one release at a time.
+        //
+        // On --help rather than in a doc alone: this is read at the moment the
+        // question is being asked.
+        runtime.engine.commander.addHelpText('after', `
+Which check answers which question:
+
+  Did this build write what it thought it wrote?
+      --audit-output        compares the output on disk against the manifest.
+                            Catches tampering, truncation and a file deleted
+                            behind the build's back. Structurally CANNOT catch
+                            a render that changed, because a render rewrites
+                            its own snapshot — afterwards the new bytes agree
+                            with themselves.
+
+  Did an upgrade change what a render produces?
+      --force               re-renders everything 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.
+
+  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
+                            resolves to nothing, what a preset never produced,
+                            and what loads only because a browser discarded a
+                            climb above the site root.
+
+  Are the derivatives current?
+      --render-presets [n]  re-derives every preset, or one by name, without
+                            touching anything else. For a preset edited without
+                            bumping its revision.
+
+  Start over.
+      --clear               removes the output folder and reopens the cache.
+                            A boot operation: it is refused while an instance
+                            is running in the same folder.
+
+  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
+                            timings in milliseconds so two releases can be
+                            compared.
+
+The full version, with what each code means: docs/diagnostics.md`)
+
         Object.assign(runtime.options, options || runtime.engine.commander.parse(process.argv).opts())
         // runtime.options.info gates the progress bar — gauge stays
         // silent in --debug/--trace modes because logs are voluminous

package/src/instance.js

@@ -37,6 +37,7 @@ import runtime from './runtime.js'
 import { onLoaded } from './lifecycle.js'
 import { renderErrorCount } from './report.js'
 import { runReportOnly } from './engine.js'
+import { emitReport } from './report.js'
 
 // Where the endpoint lives.
 //
@@ -429,7 +430,20 @@ async function serveBuild(socket, request, logger) {
             // rebuild() — the same call a one-shot makes. Nothing here
             // re-implements it: the contract is what decides whether it
             // writes, so setting the contract is the whole fix.
-            await withRequestOutput(request, () => runtime.rebuild())
+            await withRequestOutput(request, async () => {
+                // Suppressed for the duration of the cycle and emitted once
+                // after it: any cycle already in flight when this request
+                // arrived would otherwise write a second document into a
+                // stream that promises one.
+                runtime.state ??= {}
+                runtime.state.suppressReport = true
+                try {
+                    await runtime.rebuild()
+                } finally {
+                    runtime.state.suppressReport = false
+                }
+                emitReport()
+            })
         } finally {
             runtime.options.renderPresets = priorRenderPresets
         }

package/src/logger.js

@@ -178,9 +178,28 @@ export function createMikserLogger(level = 'info') {
         customPrettifiers: {
             level: () => '',
         },
+        // The CODE, on the line a person is reading.
+        //
+        // A finding had two names: the report called it `output-drift` and the
+        // console said "produced different bytes from the same inputs", and
+        // nothing on the console contained the string someone reading
+        // docs/diagnostics.md would grep for. So a script watching the build
+        // matched prose — the half that is free to be reworded — while the
+        // stable identifier existed only in a document that script was not
+        // reading.
+        //
+        // Printed here because this is the one function every line passes
+        // through, so the code cannot be attached to the record and missing
+        // from the terminal: they come from the same field. `hideObject` still
+        // suppresses the rest of the structured fields, which belong in the
+        // report and would turn a one-line warning into a block.
+        //
+        // Only where there is a code. An ordinary info line has no identity to
+        // print and gains nothing from a bracket.
         messageFormat: (log, key) => {
             const icon = ICONS[LEVEL_LABELS[log.level]] ?? ''
-            return icon + (log[key] ?? '')
+            const code = typeof log.code === 'string' && log.code ? `[${log.code}] ` : ''
+            return icon + code + (log[key] ?? '')
         },
     })
 

package/src/plugins/assets.js

@@ -405,16 +405,26 @@ export function assets(options = {}) {
         runtime.state.assets = {
             presets: {},
             assetsMap: {},
-            // The engine asks this when a linked derivative is not on disk.
-            // Published on state rather than imported, so the engine keeps
-            // knowing nothing about presets and says nothing when this plugin
-            // is not loaded.
-            explainMissing,
             assetsFolder: options.outputFolder
                 ? path.join(options.outputFolder, assetsName)
                 : assetsName,
         }
 
+        // The engine asks this when a linked derivative is not on disk.
+        //
+        // On runtime.engine, NOT on runtime.state. State is structured-cloned
+        // into render and postprocess workers, and a function cannot be
+        // cloned: putting it there made every worker-dispatched render fail
+        // with DataCloneError on any build that loads this plugin, reported as
+        // a render error whose message was this function's own source. Options
+        // already had workerSafeOptions for exactly this hazard; state had no
+        // equivalent, so state is the wrong place to publish anything callable.
+        //
+        // Still published rather than imported, so the engine keeps knowing
+        // nothing about presets and says nothing when this plugin is absent.
+        runtime.engine ??= {}
+        runtime.engine.assets = { explainMissing }
+
         runtime.options.presets = options.presetsFolder || collection
         runtime.options.presetsFolder = path.join(runtime.options.workingFolder, runtime.options.presets)
         logger.debug('Presets folder: %s', runtime.options.presetsFolder)

package/src/references.js

@@ -120,9 +120,22 @@ export function extractReferences(rawSource) {
 export function resolveUrl(pageDir, url, { root = '' } = {}) {
     const clean = url.split('#')[0].split('?')[0]
     const absolute = clean.startsWith('/')
-    const segments = clean.split('/').filter(s => s !== '' && s !== '.')
+    // `.` is not a directory to climb out of, in either half of this.
+    //
+    // The url segments have always dropped it and the page's directory did
+    // not, which mattered for exactly one page on a site: the one at its root,
+    // where path.dirname gives '.'. That lone '.' counted as a real segment,
+    // so a `..` popped it instead of flooring, and the reference resolved to
+    // the same file a browser reaches while reporting floored: 0.
+    //
+    // The target was right and the verdict was wrong, which is why nothing
+    // noticed: a root page's over-deep url was silently exempt on a
+    // single-root build, and reported on a multi-site one where the site root
+    // makes pageDir genuinely empty. Same markup, two answers.
+    const segment = (s) => s !== '' && s !== '.'
+    const segments = clean.split('/').filter(segment)
 
-    const parts = absolute ? [] : pageDir.split('/').filter(Boolean)
+    const parts = absolute ? [] : pageDir.split('/').filter(segment)
     // How FAR above the root it climbed, not merely that it did. When every
     // over-deep url on a site climbs the same distance, that is one base
     // mismatch reported once — not N findings, which is how a real signal gets
@@ -198,21 +211,46 @@ export async function checkReferences(outputFolder, { siteRoots = [] } = {}) {
         const pageDir = path.dirname(file).slice(root.length).replace(/^\/+/, '')
 
         for (const { url, customProperty } of extractReferences(source)) {
-            const { target, overDeep, floored } = resolveUrl(pageDir, url, { root })
+            let { target, overDeep, floored } = resolveUrl(pageDir, url, { root })
             checked++
 
-            if (!exists.has(target)) {
-                exists.set(target, existsSync(path.join(outputFolder, target)))
+            const resolves = (candidate) => {
+                if (!exists.has(candidate)) {
+                    exists.set(candidate, existsSync(path.join(outputFolder, candidate)))
+                }
+                return exists.get(candidate)
             }
+            resolves(target)
 
-            // Resolved from a stylesheet instead, and correct there.
-            if (!exists.get(target) && customProperty && styleBases.some((base) => {
-                const from = resolveUrl(base.dir, url, { root: base.root }).target
-                if (!exists.has(from)) {
-                    exists.set(from, existsSync(path.join(outputFolder, from)))
+            // A custom property is resolved from the STYLESHEET, for BOTH
+            // questions this check asks.
+            //
+            // The first version of this only replaced the verdict when the
+            // page-relative target was missing, which left the climb check
+            // answering from a base it had already been told was the wrong
+            // one. Where the discarded `..` happened to land on a real file,
+            // the reference was reported as climbing above the site root, and
+            // the explanation said it loads "because a browser discards the
+            // extra `..`" — when it loads because it is correct where it is
+            // actually read from. A wrong reason on a correct reference is
+            // worse than the original false positive: it sends the reader to
+            // fix a base that is right.
+            //
+            // Clean beats floored beats missing. A stylesheet that resolves it
+            // without climbing settles it; one that resolves it only by
+            // climbing is a genuine over-deep against THAT base; and if none
+            // resolves it the page-relative answer stands and the url is
+            // simply broken.
+            if (customProperty && styleBases.length) {
+                let best = null
+                for (const base of styleBases) {
+                    const from = resolveUrl(base.dir, url, { root: base.root })
+                    if (!resolves(from.target)) continue
+                    if (!from.overDeep) { best = from; break }
+                    best ??= from
                 }
-                return exists.get(from)
-            })) continue
+                if (best) ({ target, overDeep, floored } = best)
+            }
 
             // Broken outranks over-deep: a url that resolves nowhere is the
             // failure, and adding that it is also one level too deep is noise.

package/src/report.js

@@ -119,6 +119,13 @@ export function resetReport() {
     // time was not re-checked, and claiming otherwise would be the kind of
     // completeness this codebase keeps having to walk back.
     runtime.state.assetUse = new Map()
+    // Per cycle, like everything else here. Accumulating for the life of the
+    // process would make a watcher's second build report what the instance has
+    // spent since boot — a number that only grows, and never answers "what did
+    // this cycle cost", which is the question someone comparing builds is
+    // asking. The boot phases therefore appear in the first cycle's report and
+    // not in later ones, which is what actually happened.
+    runtime.state.timings = {}
 }
 
 // Published on the runtime so runtime.js can start a fresh cycle for a
@@ -433,6 +440,32 @@ function invalidation() {
     }
 }
 
+// Phase durations, rounded to a tenth of a millisecond and ordered slowest
+// first — so a diff between two versions leads with what moved.
+function phaseTimings() {
+    const timings = runtime.state?.timings ?? {}
+    const entries = Object.entries(timings)
+        .map(([phase, { ms, calls }]) => ({ phase, ms: Math.round(ms * 10) / 10, calls }))
+        .sort((a, b) => b.ms - a.ms)
+    return {
+        // This cycle, summed. The phases below add up to it.
+        total: Math.round(entries.reduce((sum, e) => sum + e.ms, 0) * 10) / 10,
+        // How long THIS PROCESS has been alive, which is not the same thing
+        // and is named so nobody reads it as one.
+        //
+        // For a one-shot it is the whole run, and subtracting `total` gives
+        // what the phases do not cover: module loading and engine
+        // construction, which happen before any hook and on a small site are
+        // most of the elapsed time. For a build forwarded to a watcher it is
+        // the INSTANCE's age — minutes or days — and says nothing about the
+        // build. Reported either way, because a caller that knows which case
+        // it is in can use it, and a caller that does not would have been
+        // misled by a name like "elapsed".
+        processUptime: Math.round(process.uptime() * 1000 * 10) / 10,
+        phases: entries,
+    }
+}
+
 export function buildReport() {
     const report = store()
     const cycle = runtime.state?.cycle
@@ -442,6 +475,17 @@ export function buildReport() {
         cycleId: cycle?.id ?? null,
         startedAt: cycle?.startedAt ?? null,
         finishedAt: cycle?.finishedAt ?? null,
+        // What the run COST, per phase, in milliseconds.
+        //
+        // `finishedAt - startedAt` is not this. It spans the processing cycle
+        // only — measured on a small site, 12ms of a 443ms run — so boot, the
+        // config graph, the plugin load and the import scan, which is most of
+        // where a regression lands, had no number anywhere. A caller could
+        // prove an upgrade moved no bytes and not that it halved the speed.
+        //
+        // Milliseconds, because the console's whole-second rounding reports a
+        // phase that doubled from 400ms to 800ms as "0s" both times.
+        ...(runtime.state?.timings ? { timings: phaseTimings() } : {}),
         rendered: report.rendered,
         skipped: report.skipped,
         unchanged: report.unchanged,
@@ -494,5 +538,15 @@ export function emitReport() {
     // questions: a server with the mcp plugin records so a tool can read it,
     // and must not write a document to stdout.
     if (!runtime.options?.json) return
+    // Not while a forwarded request owns the stream.
+    //
+    // The control socket opens in onLoaded, before the instance's own first
+    // build has finished, so a client can connect into that window — turn on
+    // the json contract, and have the INSTANCE's startup cycle write its
+    // report into the client's stdout, followed by the requested build's.
+    // Two documents in a stream promising one, which is the same broken
+    // contract as emitting none. The request emits exactly once, after the
+    // cycle it asked for.
+    if (runtime.state?.suppressReport) return
     process.stdout.write(JSON.stringify(buildReport(), null, 2) + '\n')
 }

package/src/runtime.js

@@ -62,18 +62,52 @@ const runtime = {
         completed: [],
     },
 
+    // What each phase COST, not only what it did.
+    //
+    // A build report says what was done and never what it took, so a
+    // regression is invisible to the one caller that would catch it. The
+    // preset fan-out shipped scanning the whole catalog every cycle and ran
+    // for four releases before anyone happened to time a rebuild by hand:
+    // output was byte-identical, every check passed, and the build was twice
+    // as slow.
+    //
+    // Recorded here because this is the one place every phase passes through,
+    // so nothing has to be instrumented plugin by plugin and no phase can be
+    // added later without being counted. The console's progress lines are not
+    // this: they are per-collection, rounded to whole seconds — so a phase
+    // that doubled from 400ms to 800ms prints "0s" either way — and they are
+    // suppressed entirely off a TTY, which is every CI run and every --json
+    // invocation, meaning the numbers did not exist where a script could read
+    // them.
+    //
+    // Accumulated per phase rather than assigned, because a phase runs more
+    // than once in a watch process and a cycle can re-enter one.
+    recordPhase(phaseName, ms) {
+        if (!phaseName) return
+        this.state ??= {}
+        const timings = (this.state.timings ??= {})
+        const entry = (timings[phaseName] ??= { ms: 0, calls: 0 })
+        entry.ms += ms
+        entry.calls++
+    },
+
     async callHooks(hooks, signal, phaseName) {
         // Lifecycle methods below pass `phaseName` so introspection
         // tools (mikser-io-mcp's mikser://lifecycle resource, debuggers)
         // can see what's running. Direct callers (tests, plugins driving
         // sub-flows) can omit it.
         if (phaseName) this.phase = phaseName
+        const started = performance.now()
         try {
             for (let hook of hooks) {
                 if (signal?.aborted) throw new AbortError()
                 await hook(signal)
             }
         } finally {
+            // In `finally`, so a phase that threw still reports what it spent
+            // before throwing — which is exactly the phase someone is about to
+            // go looking at.
+            this.recordPhase(phaseName, performance.now() - started)
             if (phaseName) this.phase = null
         }
     },