mikser-io 9.23.0 → 9.25.0

package/docs/diagnostics.md

@@ -54,7 +54,23 @@ rendered    2026-08-22 21:07:52   → /page-a.html   [STALE: input hash moved si
 ```
 
 A snapshot written before per-input recording says so rather than
-guessing. Note that `--explain` compares the CATALOG's entity against the
+guessing.
+
+A destination whose **last render attempt threw** reads as such, rather
+than as current:
+
+```
+rendered    2026-08-22 21:52:24   → /page-a.html   [STALE: last render attempt failed]
+  failed     2026-08-22 21:52:25  The partial partials/btn could not be found
+             3 attempts since 2026-08-22 21:52:24
+  partial    /layouts/partials/btn.hbs  b6ab7ccc  [TARGET DELETED SINCE]
+would re-render — the last render attempt failed and nothing has changed since
+```
+
+`[TARGET DELETED SINCE]` is the same distinction one level down: an edge's
+binding is what it resolved to *when recorded*, so a target deleted
+afterwards still shows an id and a hash and reads as healthy unless the
+catalog is asked. Note that `--explain` compares the CATALOG's entity against the
 snapshot: if you have edited a file and not yet built, the verdict is
 `source differs from the catalog` — the edit has not been imported yet, so
 there is nothing to attribute. Build, then ask.
@@ -102,15 +118,39 @@ under this flag, so stdout parses whole.
 npx mikser --json | jq '.summary'
 ```
 
-Four buckets, and the distinction between them is the point:
+Five buckets, and the distinction between them is the point:
 
 | Bucket | Meaning |
 | --- | --- |
-| `rendered` | the render ran, with a `reason` per entity |
+| `rendered` | the render ran and the output moved, with a `reason` per entity |
 | `skipped` | the manifest decided not to render, with a `reason` |
 | `unchanged` | the render ran and produced bytes identical to what was already on disk |
+| `errors` | the render ran and **threw** — with `id`, `destination`, `error`, `layout` |
 | `gated` | a count — the source was unchanged, so no render was ever scheduled |
 
+A failed render appears in `errors` and **not** in `rendered`: that bucket
+means the output moved, and a throw writes nothing. The previous good bytes
+stay on disk, which is what makes a failed render survivable — and also
+what makes it invisible without this bucket.
+
+A failed render is **retried on every subsequent build** until it
+succeeds, reported as `reason: "retry-failed"`. Nothing else would schedule
+it — the entity's own source has not changed, so it is gated at import, and
+the manifest still describes the last good render — so without the retry a
+build after a failing one reported success with the site still stale.
+
+Retries are unbounded and deliberately noisy: a page that fails every cycle
+is failing every cycle. `errors[].since` and `errors[].attempts` are what
+make that readable — "broke just now" and "broken for an hour" are
+different situations. The marker clears itself on the first success.
+
+**A one-shot build with render errors exits `1`.** That is the signal a CI
+gate needs, because `mikser && mikser --verify` would otherwise pass a
+build in which nothing rendered: `--verify` compares the output against the
+manifest, both of which still describe the last good render. Watch mode
+keeps running — a failed render there is a state to fix on the next cycle,
+not a reason to tear down the watcher.
+
 `reason` is a stable vocabulary you can assert on: `unchanged`,
 `never-rendered`, `inputs-changed`, `ref-changed`, `query-matched`,
 `cache-disabled`, `postprocessor`, `force`, `no-manifest`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.23.0",
+  "version": "9.25.0",
   "description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
   "main": "index.js",
   "exports": {

package/src/engine.js

@@ -10,7 +10,7 @@ import { useJournal, updateEntry } from './journal.js'
 import { globby } from 'globby'
 import { OPERATION, TASKS } from './constants.js'
 import { changeExtension, formatErrorContext, projectMeta, lookupKeys } from './utils.js'
-import { reportRendered, reportSkipped, emitReport } from './report.js'
+import { reportRendered, reportSkipped, reportError, renderErrorCount, emitReport } from './report.js'
 import render from './render.js'
 import postprocess, { loadPlugin as loadPostPlugin } from './postprocess.js'
 import map from 'p-map'
@@ -374,7 +374,11 @@ export async function setup(options) {
                     logger.debug('Manifest skip: %s → %s', entity.name || entity.id, entity.destination)
                     return
                 }
-                reportRendered(entity, decision.reason, decision)
+                // Reported on the way OUT, not here: `rendered` means the
+                // output moved, and a render that throws writes nothing. The
+                // decision is carried down to the success path so the reason
+                // and its detail still travel with it.
+                //
                 // Same detail at debug, for tailing a watch run. One line per
                 // render is too much for a build's normal output — the counts
                 // are the summary and --json is the record — but when you are
@@ -522,11 +526,39 @@ export async function setup(options) {
                         await updateEntry({ id, output: entry.output, deps: edges })
                     }
 
+                    // A success clears whatever was recorded about this
+                    // destination failing, so the retry set drains itself.
+                    runtime.manifest?.clearFailure(entity)
+                    reportRendered(entity, decision.reason, decision)
                     logger.debug('Rendered: [%s] %s → %s', options.renderer, entity.name || entity.id, entity.destination)
                 } catch (err) {
                     if (!signal.aborted) {
                         await updateEntry({ id, output: { success: false } })
-                        logger.error('Render error: %s%s %s', entity.id, formatErrorContext(entity, err, runtime.options), err.message)
+                        const context = formatErrorContext(entity, err, runtime.options)
+                        logger.error('Render error: %s%s %s', entity.id, context, err.message)
+                        // The machine-readable half of that same line. Without
+                        // it a build that fails every page reports rendered:N,
+                        // warnings:0 and exits 0 — three clean signals and only
+                        // the human log knowing otherwise.
+                        // Durable, so the next cycle knows to try again and
+                        // --explain stops calling this destination current.
+                        runtime.manifest?.recordFailure(entity, {
+                            error: err.message,
+                            context: context.trim() || null,
+                            at: Date.now(),
+                        })
+                        const failure = runtime.manifest?.failureAt(entity.id, entity.destination)
+                        reportError(entity, err, {
+                            renderer: options.renderer ?? null,
+                            layout: entity.layout?.id ?? null,
+                            context: context.trim() || null,
+                            // When it STARTED failing, and how many attempts.
+                            // "broke just now" and "broken since 14:02" are
+                            // different situations and the reader needs to
+                            // tell them apart at a glance.
+                            since: failure?.firstFailedAt ?? null,
+                            attempts: failure?.attempts ?? 1,
+                        })
                     }
                     logger.debug('Render canceled')
                 }
@@ -537,8 +569,12 @@ export async function setup(options) {
             concurrency: runtime.options.threads,
             signal
         })
-        renderJobs.size && logger.info('Rendered: %d', renderJobs.size - skipped)
+        // Jobs minus skips minus THROWS. Counting a failed render as
+        // rendered is the same overstatement the report used to make.
+        const failed = renderErrorCount()
+        renderJobs.size && logger.info('Rendered: %d', renderJobs.size - skipped - failed)
         skipped && logger.info('Manifest skipped: %d', skipped)
+        failed && logger.error('Render errors: %d', failed)
     })
 
     onBeforePostprocess(async (signal) => {
@@ -765,11 +801,31 @@ export async function setup(options) {
                 }
             }
         }
-        logger.notice('Mikser completed')
+        // A cycle with failed renders is not a completed build, and the word
+        // people read is this one.
+        const failed = renderErrorCount()
+        if (failed) logger.error('Mikser completed with %d render error%s', failed, failed === 1 ? '' : 's')
+        else logger.notice('Mikser completed')
+
         // 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()
+
+        // Non-zero for a one-shot build, so `mikser && mikser --verify` cannot
+        // pass with every page in the site stale. `exitCode` rather than
+        // process.exit so the report above is flushed and shutdown runs.
+        //
+        // Watch mode keeps going: a failed render there is a state to fix in
+        // the next cycle, not a reason to tear down the watcher. That is also
+        // what makes the failure self-concealing in watch — the errors scroll
+        // past between two green builds — so the exit code is precisely the
+        // signal CI needs and the one interactive use must not have.
+        //
+        // 1, not 2: --verify already uses 2 for output drift and --explain 3
+        // for not-found. "The build ran and some renders threw" is its own
+        // thing.
+        if (failed && !runtime.options.watch) process.exitCode = 1
     })
 
     onCancelled(async () => {

package/src/explain.js

@@ -10,7 +10,7 @@
 // Follows --verify's shape: report and exit, no build phases run.
 import { inputHashOf, inputPartsOf, diffInputParts, lookupKeys, checksum as fileChecksum } from './utils.js'
 import { filterKey } from './track.js'
-import { findEntity, findEntities } from './catalog.js'
+import { findEntity, findEntities, findById } from './catalog.js'
 import runtime from './runtime.js'
 
 const shortHash = (h) => (h ? String(h).slice(0, 8) : null)
@@ -118,6 +118,11 @@ export async function explain(reference) {
     const currentHash = inputHashOf(entity)
     const currentParts = inputPartsOf(entity)
     const queryMatches = await countQueryMatches(snapshots)
+    // Checked before the hash comparison in the verdict: a destination whose
+    // last attempt threw will re-render regardless of what the hashes say.
+    const failedSnapshots = snapshots
+        .map(snap => runtime.manifest?.failureAt?.(entity.id, snap.destination))
+        .filter(Boolean)
 
     // The catalog is as of the LAST BUILD. If the file has been edited since,
     // nothing here knows it yet — the hashes would all agree and the verdict
@@ -186,6 +191,21 @@ export async function explain(reference) {
             // The single most useful field: does this entity's current hash
             // match what it was last rendered at?
             stale: snap.inputHash !== currentHash,
+            // The last render ATTEMPT for this destination, if it threw.
+            // Without this, a destination whose render is failing reports
+            // `[current]` and `would be SKIPPED` — both true of the recorded
+            // state, and together the wrong answer to the only question
+            // --explain is ever asked.
+            failed: (() => {
+                const f = runtime.manifest?.failureAt?.(entity.id, snap.destination)
+                if (!f) return null
+                return {
+                    error: f.error,
+                    since: when(f.firstFailedAt),
+                    lastAttempt: when(f.lastFailedAt),
+                    attempts: f.attempts ?? 1,
+                }
+            })(),
             // WHICH input moved, not merely that one did. This is the whole
             // question behind "why did this re-render" — answering it from
             // the recorded parts costs nothing, and not answering it sends
@@ -220,6 +240,14 @@ export async function explain(reference) {
                         bound: entry.targetIds?.length ? entry.targetIds
                             : entry.targetId ? [entry.targetId]
                             : [],
+                        // `bound` is what the edge resolved to WHEN RECORDED.
+                        // A target deleted since then still shows an id and a
+                        // hash, which reads as healthy — so check the catalog
+                        // rather than describing the record as if it were
+                        // current.
+                        gone: (entry.targetIds?.length ? entry.targetIds
+                            : entry.targetId ? [entry.targetId]
+                            : []).filter(id => !findById(id)),
                         hash: shortHash(entry.hash),
                     }),
         })),
@@ -231,6 +259,9 @@ export async function explain(reference) {
                   + '(Some plugins compose a checksum from several files, so verify before concluding.)'
                 : snapshots.length === 0
             ? 'never rendered — no manifest snapshot. Either it has no layout, or its layout produced no destination.'
+            : failedSnapshots.length
+                ? `would re-render — the last render attempt failed and nothing has changed since `
+                  + `(${failedSnapshots[0].error})`
             : snapshots.some(s => s.inputHash !== currentHash)
                 ? renderVerdict(snapshots, currentHash, currentParts)
                 : 'would be SKIPPED — input hash unchanged. A dependency in refClosure changing is the only other thing that would re-render it.',
@@ -285,7 +316,15 @@ export function formatExplain(report) {
     }
     for (const r of report.renders) {
         row('rendered', `${r.renderedAt ?? 'unknown'}   → ${r.destination}`
-            + (r.stale ? '   [STALE: input hash moved since]' : '   [current]'))
+            + (r.failed ? '   [STALE: last render attempt failed]'
+                : r.stale ? '   [STALE: input hash moved since]'
+                : '   [current]'))
+        if (r.failed) {
+            out.push(`  failed     ${r.failed.lastAttempt}  ${r.failed.error}`)
+            if (r.failed.attempts > 1) {
+                out.push(`             ${r.failed.attempts} attempts since ${r.failed.since}`)
+            }
+        }
         const closure = r.refClosure
         row('refClosure', `${closure.length} edge${closure.length === 1 ? '' : 's'}`)
         for (const e of closure) {
@@ -308,7 +347,8 @@ export function formatExplain(report) {
             const bound = e.bound?.length
                 ? (e.bound.length === 1 && e.bound[0] === e.target ? '' : ` → ${e.bound.join(', ')}`)
                 : '  [UNRESOLVED — nothing answers to this name]'
-            out.push(`  ${e.kind.padEnd(10)} ${e.target}${bound}${e.hash ? `  ${e.hash}` : ''}`)
+            const gone = e.gone?.length ? '  [TARGET DELETED SINCE]' : ''
+            out.push(`  ${e.kind.padEnd(10)} ${e.target}${bound}${e.hash ? `  ${e.hash}` : ''}${gone}`)
         }
     }
 

package/src/manifest.js

@@ -85,6 +85,38 @@ export const SNAPSHOTS_SCHEMA = `
 `
 registerSchema('mikser_snapshots', SNAPSHOTS_SCHEMA)
 
+// Failed render attempts, durably.
+//
+// A failed render writes no snapshot — deliberately, so the last good bytes
+// survive — which leaves nothing anywhere saying the attempt happened. The
+// consequences all follow from that one absence: the entity is gated at
+// import next cycle (its own source did not change), so it is never
+// re-dispatched; the manifest still describes the last good render, so
+// --verify is clean; and --explain reports `[current]` and `would be
+// SKIPPED` for a page whose render is throwing — the one tool whose job is
+// "why is this not rebuilding", answering "because there is nothing to do".
+//
+// Keyed by (id, destination) like snapshots, but a SEPARATE table because a
+// render that has never once succeeded has no snapshot to hang a column on.
+//
+// firstFailedAt is kept distinct from lastFailedAt so a report can say
+// "since 14:02" — the difference between "this broke just now" and "this has
+// been broken for an hour" is most of what a reader wants.
+export const FAILURES_SCHEMA = `
+    CREATE TABLE IF NOT EXISTS mikser_failures (
+        id            TEXT NOT NULL,
+        destination   TEXT NOT NULL,
+        error         TEXT,
+        context       TEXT,
+        firstFailedAt INTEGER,
+        lastFailedAt  INTEGER,
+        attempts      INTEGER NOT NULL DEFAULT 1,
+        PRIMARY KEY (id, destination)
+    ) WITHOUT ROWID;
+    CREATE INDEX IF NOT EXISTS idx_mikser_failures_id ON mikser_failures(id);
+`
+registerSchema('mikser_failures', FAILURES_SCHEMA)
+
 // Module-level DB handle + prepared statements for the lifecycle
 // integration. Tests build their own via `createManifest(db)` —
 // the lifecycle hook below grabs useDatabase() and stashes the
@@ -252,6 +284,32 @@ async function hashOutputFile(destination) {
 export function createManifest(db) {
     if (!db) throw new Error('createManifest: db is required')
 
+    const stmtRecordFailure = db.prepare(`
+        INSERT INTO mikser_failures
+            (id, destination, error, context, firstFailedAt, lastFailedAt, attempts)
+        VALUES (@id, @destination, @error, @context, @at, @at, 1)
+        ON CONFLICT(id, destination) DO UPDATE SET
+            error = excluded.error,
+            context = excluded.context,
+            lastFailedAt = excluded.lastFailedAt,
+            attempts = mikser_failures.attempts + 1
+    `)
+    const stmtClearFailure = db.prepare(`
+        DELETE FROM mikser_failures WHERE id = ? AND destination = ?
+    `)
+    const stmtFailuresFor = db.prepare(`
+        SELECT id, destination, error, context, firstFailedAt, lastFailedAt, attempts
+        FROM mikser_failures WHERE id = ?
+    `)
+    const stmtFailureAt = db.prepare(`
+        SELECT id, destination, error, context, firstFailedAt, lastFailedAt, attempts
+        FROM mikser_failures WHERE id = ? AND destination = ?
+    `)
+    const stmtAllFailures = db.prepare(`
+        SELECT id, destination, error, context, firstFailedAt, lastFailedAt, attempts
+        FROM mikser_failures
+    `)
+
     const stmtLookupById = db.prepare(`
         SELECT id, destination, inputHash, inputParts, outputHash, refClosure, renderedAt, parent
         FROM mikser_snapshots WHERE id = ? ORDER BY destination
@@ -359,6 +417,8 @@ export function createManifest(db) {
         //   query-matched    an entity matching a recorded query mutated
         //   cache-disabled   meta.cache === false
         //   force            --force: skip nothing, ask nothing
+        //   retry-failed     the last render attempt for this destination
+        //                    threw; nothing else would reschedule it
         skipDecision(entity, mutatedRefs, currentHashes, mutatedEntities) {
             // --force means "ignore what you think you know". THREE gates
             // can stop a render — source.js's import checksum gate,
@@ -373,6 +433,31 @@ export function createManifest(db) {
             // no-match warning tells the operator to use it.
             if (runtime.options?.force) return { skip: false, reason: 'force' }
             if (entity?.meta?.cache === false) return { skip: false, reason: 'cache-disabled' }
+            // A render whose last attempt threw must be retried, and checked
+            // before anything else: every other branch reasons about hashes,
+            // and the hashes are consistent — the entity did not change, the
+            // snapshot still describes the last GOOD render. Consistency is
+            // exactly why the failure is invisible without this.
+            //
+            // Retried unbounded, and noisily. A page that fails every cycle IS
+            // failing every cycle, and a build that stops mentioning it after
+            // the third attempt is making the same trade as reporting
+            // `rendered: 12, exit 0`. What makes it tolerable is presentation
+            // — one line per failing entity, and `since` on the report so a
+            // reader can tell "broke just now" from "broken since 14:02" —
+            // not backoff.
+            const failure = this.failureAt(entity?.id, entity?.destination)
+            if (failure) {
+                return {
+                    skip: false,
+                    reason: 'retry-failed',
+                    failure: {
+                        error: failure.error,
+                        since: failure.firstFailedAt ?? null,
+                        attempts: failure.attempts ?? 1,
+                    },
+                }
+            }
             const snapshot = this.lookup(entity)
             if (!snapshot?.inputHash) return { skip: false, reason: 'never-rendered' }
             if (inputHashOf(entity) !== snapshot.inputHash) {
@@ -483,6 +568,51 @@ export function createManifest(db) {
             return { skip: true, reason: 'unchanged' }
         },
 
+        // Record that a render attempt threw. `at` is passed in rather than
+        // read from the clock here so the caller owns the timestamp.
+        recordFailure(entity, { error, context, at }) {
+            if (!entity?.id || !entity?.destination) return
+            stmtRecordFailure.run({
+                id: entity.id,
+                destination: entity.destination,
+                error: error ?? null,
+                context: context ?? null,
+                at: at ?? Date.now(),
+            })
+        },
+
+        // A render succeeded, so whatever was recorded about it failing is
+        // no longer true. Called on every success, not only after a failure —
+        // it is a cheap DELETE and forgetting it would strand the marker.
+        clearFailure(entity) {
+            if (!entity?.id || !entity?.destination) return
+            stmtClearFailure.run(entity.id, entity.destination)
+        },
+
+        // Every recorded failure for an entity, across destinations.
+        failuresFor(id) {
+            return id ? stmtFailuresFor.all(id) : []
+        },
+
+        // One, at a known destination.
+        failureAt(id, destination) {
+            if (!id || !destination) return null
+            return stmtFailureAt.get(id, destination) ?? null
+        },
+
+        // Every entity id with a recorded failure. The dispatch set a
+        // task-production plugin unions in so a failed render is retried:
+        // the entity's own source has not changed, so nothing else will
+        // schedule it, and going quiet about a page that will not build is
+        // the failure mode this whole area exists to avoid.
+        failedIds() {
+            return [...new Set(stmtAllFailures.all().map(row => row.id))]
+        },
+
+        allFailures() {
+            return stmtAllFailures.all()
+        },
+
         // Record a successful render. Single INSERT OR REPLACE.
         record(entity, deps) {
             stmtUpsert.run(snapToRow(buildSnapshot(entity, deps)))

package/src/report.js

@@ -13,7 +13,7 @@ import runtime from './runtime.js'
 
 function store() {
     runtime.state ??= {}
-    runtime.state.report ??= { rendered: [], skipped: [], unchanged: [], warnings: [], gated: 0 }
+    runtime.state.report ??= { rendered: [], skipped: [], unchanged: [], errors: [], warnings: [], gated: 0 }
     return runtime.state.report
 }
 
@@ -77,15 +77,53 @@ export function reportWarning(code, fields = {}) {
     store().warnings.push({ code, ...fields })
 }
 
+// A render that RAN and THREW. Recorded unconditionally — not gated on
+// --json like the other buckets — because the exit code depends on the
+// count, and a build that fails 12 renders must not exit 0 just because
+// nobody asked for a report.
+//
+// Failed entities do NOT appear in `rendered`. That bucket means the output
+// moved, and a throw writes nothing: the previous good bytes stay on disk,
+// which is what makes the failure survivable and also what makes it
+// invisible. `rendered: 12` beside zero written files is the misleading
+// half, and summing buckets should not require knowing that.
+export function reportError(entity, err, context = {}) {
+    const store = errorStore()
+    store.push({
+        id: entity?.id ?? null,
+        destination: entity?.destination ?? null,
+        error: err?.message ?? String(err),
+        ...context,
+    })
+}
+
+// Errors are counted even without --json, so they need a store that does
+// not depend on the report being requested.
+function errorStore() {
+    runtime.state ??= {}
+    runtime.state.renderErrors ??= []
+    return runtime.state.renderErrors
+}
+
+// How many renders threw this cycle. Read by the engine to decide the
+// process exit code.
+export function renderErrorCount() {
+    return errorStore().length
+}
+
 export function buildReport() {
     const report = store()
     return {
         rendered: report.rendered,
         skipped: report.skipped,
         unchanged: report.unchanged,
+        // Renders that ran and threw. A build with a non-empty `errors` is a
+        // failed build, whatever the other counts say.
+        errors: errorStore(),
         warnings: report.warnings,
         summary: {
             rendered: report.rendered.length,
+            errors: errorStore().length,
             // Of those renders, how many produced bytes identical to
             // what was already on disk — see reportUnchanged.
             unchanged: report.unchanged.length,