mikser-io 9.19.1 → 9.21.0

package/docs/diagnostics.md

@@ -35,10 +35,29 @@ npx mikser --explain /documents/en/posts/hello.md
 ```
 
 It prints the entity's layout and **why that layout matched**, its
-destination, its `inputHash`, whether the file on disk still agrees with
-the catalog, every recorded render with its `refClosure`, and a verdict
-in plain words — `would be SKIPPED — input hash unchanged`, or `would
-re-render`, or `source file is gone`.
+destination, its `inputHash` and the components that went into it,
+whether the file on disk still agrees with the catalog, every recorded
+render with its `refClosure`, and a verdict in plain words.
+
+When an entity's inputs have moved since a render, the verdict names what
+moved rather than only that something did:
+
+```
+would re-render — meta.title changed since it was last rendered
+```
+
+and the render line carries the same detail per snapshot:
+
+```
+rendered    2026-08-22 21:07:52   → /page-a.html   [STALE: input hash moved since]
+  moved      content, meta.weight (added)
+```
+
+A snapshot written before per-input recording says so rather than
+guessing. 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.
 
 Each `refClosure` edge shows the name that was asked for and the entity
 it bound to, and flags the ones that bound to nothing:
@@ -77,6 +96,27 @@ Four buckets, and the distinction between them is the point:
 `never-rendered`, `inputs-changed`, `ref-changed`, `query-matched`,
 `cache-disabled`, `postprocessor`, `force`, `no-manifest`.
 
+`inputs-changed` carries a `changed` array naming **which** input moved,
+so you do not have to go to the database to find out:
+
+```json
+{ "id": "/files/hero.jpg",     "reason": "inputs-changed", "changed": ["checksum"] }
+{ "id": "/documents/page.md",  "reason": "inputs-changed", "changed": ["meta.title"] }
+{ "id": "/documents/page.md",  "reason": "inputs-changed", "changed": ["content"] }
+{ "id": "/layouts/post.hbs",   "reason": "inputs-changed", "changed": ["inputs.shared"] }
+```
+
+`checksum` means the bytes on disk moved; `content` means the body did;
+`meta.<field>` names the front-matter field; `inputs.<key>` is a declared
+input such as a layout's sidecar digest. A field that appeared or vanished
+reads as `meta.weight (added)` / `(removed)`, which is the answer when a
+document gains or loses front-matter.
+
+The array is absent on a first render — there is no prior snapshot to
+compare against — and on `ref-changed`, because that is a dependency
+moving rather than the entity's own inputs. Conflating the two would make
+the attribution misleading.
+
 `unchanged` is the interesting one. It means invalidation was coarser
 than it needed to be — the render was scheduled, ran, and produced
 nothing new. A high count is not a bug, but it tells you where the

package/package.json

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

package/src/database/index.js

@@ -331,6 +331,11 @@ export function createSqliteDatabase({
             logger: logger ?? null,
         }
 
+        // Published so plugins can tell an everything-was-evaluated cycle
+        // from an incremental one without reaching into the db handle. Read
+        // through `isFullCycle()` in utils.js rather than directly.
+        runtime.options.firstRun = provisioningCtx.firstRun
+
         // Fire provisioning callbacks before schema apply, so they can
         // load runtime extensions (sqlite-vec's vec0, etc.) that the
         // schemas about to apply might reference, register custom

package/src/engine.js

@@ -374,7 +374,7 @@ export async function setup(options) {
                     logger.debug('Manifest skip: %s → %s', entity.name || entity.id, entity.destination)
                     return
                 }
-                reportRendered(entity, decision.reason)
+                reportRendered(entity, decision.reason, decision.changed)
                 // Project reference-marker keys (`$author`, `$hero`, …)
                 // into their normalized form (`author`, `hero`) before
                 // the entity crosses into the renderer — applies whether

package/src/explain.js

@@ -8,7 +8,7 @@
 // needs knowledge a user of the tool should not need.
 //
 // Follows --verify's shape: report and exit, no build phases run.
-import { inputHashOf, lookupKeys, checksum as fileChecksum } from './utils.js'
+import { inputHashOf, inputPartsOf, diffInputParts, lookupKeys, checksum as fileChecksum } from './utils.js'
 import { findEntity } from './catalog.js'
 import runtime from './runtime.js'
 
@@ -28,6 +28,22 @@ async function resolve(reference) {
     return like ?? null
 }
 
+// The verdict line names what moved when it can. That line is the one
+// people read, so "the input hash differs" there is the answer stopping one
+// step short of useful.
+function renderVerdict(snapshots, currentHash, currentParts) {
+    const moved = new Set()
+    for (const snap of snapshots) {
+        if (snap.inputHash === currentHash || !snap.inputParts) continue
+        const d = diffInputParts(snap.inputParts, currentParts)
+        for (const key of [...d.changed, ...d.added, ...d.removed]) moved.add(key)
+    }
+    if (!moved.size) {
+        return 'would re-render — the entity\'s input hash differs from what it was last rendered at'
+    }
+    return `would re-render — ${[...moved].join(', ')} changed since it was last rendered`
+}
+
 export async function explain(reference) {
     const entity = await resolve(reference)
     if (!entity) {
@@ -43,6 +59,7 @@ export async function explain(reference) {
 
     const snapshots = runtime.manifest?.snapshotsFor(entity.id) ?? []
     const currentHash = inputHashOf(entity)
+    const currentParts = inputPartsOf(entity)
 
     // 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
@@ -96,9 +113,11 @@ export async function explain(reference) {
         // current hash; each snapshot carries the hash it was rendered at, so
         // the two disagreeing IS the answer to "why did this change".
         inputHash: currentHash,
-        inputHashOf: entity.checksum && entity.meta == null && entity.content == null
-            ? 'checksum'
-            : 'meta+content+inputs',
+        // The components that actually went into the hash for THIS entity,
+        // read off the parts rather than restated — a hardcoded label drifts
+        // the moment the payload changes, and this one had.
+        inputHashOf: [...new Set(Object.keys(currentParts).map(k => k.split('.')[0]))].join('+')
+            || 'nothing',
         inputs: entity.inputs ?? null,
         checksum: entity.checksum ?? null,
         source,
@@ -109,6 +128,15 @@ 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,
+            // 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
+            // the reader to a database query for something already here.
+            moved: snap.inputHash === currentHash
+                ? null
+                : snap.inputParts
+                    ? diffInputParts(snap.inputParts, currentParts)
+                    : 'unknown',
             outputHash: snap.outputHash ?? null,
             parent: snap.parent ?? null,
             refClosure: (snap.refClosure ?? []).map(entry =>
@@ -136,7 +164,7 @@ export async function explain(reference) {
                 : snapshots.length === 0
             ? 'never rendered — no manifest snapshot. Either it has no layout, or its layout produced no destination.'
             : snapshots.some(s => s.inputHash !== currentHash)
-                ? 'would re-render — the entity\'s input hash differs from what it was last rendered at'
+                ? 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.',
         lookupKeys: lookupKeys(entity),
     }

package/src/manifest.js

@@ -56,7 +56,7 @@ import { useLogger } from './engine.js'
 import { onLoaded, onFinalize } from './lifecycle.js'
 import { useJournal } from './journal.js'
 import { OPERATION } from './constants.js'
-import { extractRefs, inputHashOf } from './utils.js'
+import { extractRefs, inputHashOf, inputPartsOf, diffInputParts } from './utils.js'
 import { filterKey } from './track.js'
 import { findById } from './catalog.js'
 import { useDatabase, registerSchema } from './database/index.js'
@@ -74,6 +74,7 @@ export const SNAPSHOTS_SCHEMA = `
         id          TEXT NOT NULL,
         destination TEXT NOT NULL,
         inputHash   TEXT,
+        inputParts  TEXT,
         outputHash  TEXT,
         refClosure  TEXT,
         renderedAt  INTEGER,
@@ -97,6 +98,20 @@ function sha1(payload) {
 }
 
 // refClosure builder — same logic as before, no DB involvement.
+// Which input moved, as a flat list of part names ('content',
+// 'meta.title', 'checksum', 'inputs.shared'). Empty when the snapshot
+// predates part recording — the combined hash still says the entity
+// changed, and saying nothing is better than guessing which part.
+function describeInputChange(entity, snapshot) {
+    if (!snapshot?.inputParts) return []
+    const { changed, added, removed } = diffInputParts(snapshot.inputParts, inputPartsOf(entity))
+    return [
+        ...changed,
+        ...added.map(key => `${key} (added)`),
+        ...removed.map(key => `${key} (removed)`),
+    ]
+}
+
 function buildRefClosure(entity, deps) {
     const closure = []
     const seen = new Set()
@@ -155,6 +170,11 @@ function buildSnapshot(entity, deps, outputHash) {
         id: entity.id,
         destination: entity.destination,
         inputHash: inputHashOf(entity),
+        // Per-component hashes of the same payload the combined hash covers,
+        // so a later run can name WHICH input moved instead of only that one
+        // did. Without it `inputs-changed` sends the reader to a database
+        // query for something the tool already has in hand.
+        inputParts: inputPartsOf(entity),
         refClosure: buildRefClosure(entity, deps),
         renderedAt: Date.now(),
     }
@@ -171,6 +191,7 @@ function rowToSnap(row) {
         id:          row.id,
         destination: row.destination,
         inputHash:   row.inputHash ?? undefined,
+        inputParts:  row.inputParts ? JSON.parse(row.inputParts) : undefined,
         outputHash:  row.outputHash ?? undefined,
         refClosure:  row.refClosure ? JSON.parse(row.refClosure) : undefined,
         renderedAt:  row.renderedAt ?? undefined,
@@ -183,6 +204,7 @@ function snapToRow(snap) {
         id:          snap.id,
         destination: snap.destination,
         inputHash:   snap.inputHash   ?? null,
+        inputParts:  snap.inputParts  ? JSON.stringify(snap.inputParts) : null,
         outputHash:  snap.outputHash  ?? null,
         refClosure:  snap.refClosure  ? JSON.stringify(snap.refClosure) : null,
         renderedAt:  snap.renderedAt  ?? null,
@@ -190,9 +212,34 @@ function snapToRow(snap) {
     }
 }
 
-async function hashOutputFile(destination) {
+// Where a `destination` actually is on disk.
+//
+// Two shapes are in circulation and both are legitimate. A page's is
+// output-relative with a leading slash (`/bg/index.html`); an asset's is a
+// real filesystem path, because assets.js builds it from
+// `runtime.options.assetsFolder`, which resolves inside the WORKING folder
+// and can sit outside outputFolder entirely.
+//
+// `path.isAbsolute` cannot separate them — on POSIX `/bg/index.html` is
+// absolute too — so resolve by EXISTENCE, output-relative first since that
+// is the dominant shape. A page destination treated as a filesystem path
+// would otherwise be looked for at the root of the disk.
+//
+// Shared, because the two callers needing it drifted into two separate
+// bugs: verify() reported every asset missing while printing its real
+// path, and hashOutputFile silently recorded no outputHash for one, which
+// left 78% of a real project's snapshots presence-checked only.
+export function resolveOutputPath(destination, outputFolder = runtime.options?.outputFolder) {
     if (!destination) return undefined
-    const filePath = path.join(runtime.options.outputFolder, destination)
+    const joined = path.join(outputFolder ?? '', destination)
+    if (existsSync(joined)) return joined
+    if (path.isAbsolute(destination) && existsSync(destination)) return destination
+    return joined
+}
+
+async function hashOutputFile(destination) {
+    const filePath = resolveOutputPath(destination)
+    if (!filePath) return undefined
     try {
         const buf = await readFile(filePath)
         return sha1(buf)
@@ -205,18 +252,18 @@ export function createManifest(db) {
     if (!db) throw new Error('createManifest: db is required')
 
     const stmtLookupById = db.prepare(`
-        SELECT id, destination, inputHash, outputHash, refClosure, renderedAt, parent
+        SELECT id, destination, inputHash, inputParts, outputHash, refClosure, renderedAt, parent
         FROM mikser_snapshots WHERE id = ? ORDER BY destination
     `)
     const stmtLookup = db.prepare(`
-        SELECT id, destination, inputHash, outputHash, refClosure, renderedAt, parent
+        SELECT id, destination, inputHash, inputParts, outputHash, refClosure, renderedAt, parent
         FROM mikser_snapshots WHERE id = ? AND destination = ?
     `)
     const stmtUpsert = db.prepare(`
         INSERT OR REPLACE INTO mikser_snapshots
-            (id, destination, inputHash, outputHash, refClosure, renderedAt, parent)
+            (id, destination, inputHash, inputParts, outputHash, refClosure, renderedAt, parent)
         VALUES
-            (@id, @destination, @inputHash, @outputHash, @refClosure, @renderedAt, @parent)
+            (@id, @destination, @inputHash, @inputParts, @outputHash, @refClosure, @renderedAt, @parent)
     `)
     const stmtDeleteByPK = db.prepare(`
         DELETE FROM mikser_snapshots WHERE id = ? AND destination = ?
@@ -232,7 +279,7 @@ export function createManifest(db) {
         SELECT id, destination FROM mikser_snapshots WHERE parent = ?
     `)
     const stmtSelectAll = db.prepare(`
-        SELECT id, destination, inputHash, outputHash, refClosure, renderedAt, parent
+        SELECT id, destination, inputHash, inputParts, outputHash, refClosure, renderedAt, parent
         FROM mikser_snapshots
     `)
     const stmtCount = db.prepare(`SELECT COUNT(*) AS c FROM mikser_snapshots`)
@@ -327,7 +374,16 @@ export function createManifest(db) {
             if (entity?.meta?.cache === false) return { skip: false, reason: 'cache-disabled' }
             const snapshot = this.lookup(entity)
             if (!snapshot?.inputHash) return { skip: false, reason: 'never-rendered' }
-            if (inputHashOf(entity) !== snapshot.inputHash) return { skip: false, reason: 'inputs-changed' }
+            if (inputHashOf(entity) !== snapshot.inputHash) {
+                // Name the component that moved. "inputs-changed" alone is
+                // the answer to a question nobody asked — the reader wants to
+                // know WHICH input, and the recorded parts have it.
+                return {
+                    skip: false,
+                    reason: 'inputs-changed',
+                    changed: describeInputChange(entity, snapshot),
+                }
+            }
             if (!snapshot.refClosure?.length) return { skip: true, reason: 'unchanged' }
             const sourceLang = entity?.meta?.lang ?? null
             for (const entry of snapshot.refClosure) {
@@ -552,31 +608,7 @@ export function createManifest(db) {
             for (const row of stmtSelectAll.iterate()) {
                 const snap = rowToSnap(row)
                 if (!snap.destination) continue
-                // `destination` arrives in two shapes and both are legitimate.
-                // A page's is output-relative with a leading slash
-                // (`/bg/index.html`); an asset's is a real filesystem path,
-                // because assets.js builds it from
-                // `runtime.options.assetsFolder` — which resolves inside the
-                // WORKING folder and may sit outside outputFolder entirely
-                // (a `derived/` tree that `shares` symlinks into each language
-                // root is the case that proves it).
-                //
-                // `path.isAbsolute` cannot tell them apart: on POSIX
-                // `/bg/index.html` is absolute too. So resolve by EXISTENCE,
-                // output-relative first — that is the dominant shape, and a
-                // page destination interpreted as a filesystem path would
-                // otherwise be looked for at the root of the disk.
-                //
-                // Only the fallback path is a filesystem path, so it is only
-                // tried when the destination is absolute and joining changed
-                // nothing that resolves.
-                const joined = path.join(outputFolder, snap.destination)
-                let filePath = joined
-                if (!existsSync(joined)
-                    && path.isAbsolute(snap.destination)
-                    && existsSync(snap.destination)) {
-                    filePath = snap.destination
-                }
+                const filePath = resolveOutputPath(snap.destination, outputFolder)
                 // Orphan detection compares against a globby walk of
                 // outputFolder, so `claimed` has to hold exactly the relative
                 // form that walk produces. A destination resolving outside

package/src/plugins/assets.js

@@ -6,6 +6,7 @@ import { globby } from 'globby'
 import _ from 'lodash'
 import map from 'p-map'
 import { reportWarning } from '../report.js'
+import { isFullCycle } from '../utils.js'
 
 // Normalize a `options.presets[name]` value to a consistent
 // { matches, options } shape so callers don't have to inspect which form
@@ -120,6 +121,14 @@ export function assets(options = {}) {
         if (matchTally.reported) return
         const configured = Object.keys(options.presets || {})
         if (!configured.length || !matchTally.evaluated) return
+        // Only when the cycle evaluated everything. On an incremental run the
+        // evaluated set is whatever changed, so a healthy preset matches
+        // nothing in a run of two and the warning fires on every build —
+        // which trains the reader to filter it, and the filtered-out line is
+        // the real one. The message already told the reader to use --force to
+        // check the whole catalog; that condition gates it now instead of
+        // annotating it.
+        if (!isFullCycle(runtime)) return
         matchTally.reported = true
 
         for (const preset of configured) {
@@ -129,8 +138,7 @@ export function assets(options = {}) {
             logger.warn(
                 'Assets preset %j matched none of the %d entities evaluated (patterns: %s). ' +
                 'Patterns run against entity.id, which files({ outputFolder }) does NOT prefix — ' +
-                'the prefix appears on name and meta.url only. On an incremental run unchanged ' +
-                'entities are not re-evaluated; use --force to check the whole catalog.',
+                'the prefix appears on name and meta.url only.',
                 preset, matchTally.evaluated, matches.join(', '))
         }
     }

package/src/report.js

@@ -28,9 +28,16 @@ export function reportGated(count = 1) {
     store().gated += count
 }
 
-export function reportRendered(entity, reason) {
+export function reportRendered(entity, reason, changed) {
     if (!runtime.options?.json) return
-    store().rendered.push({ id: entity?.id, destination: entity?.destination ?? null, reason })
+    store().rendered.push({
+        id: entity?.id,
+        destination: entity?.destination ?? null,
+        reason,
+        // Which input moved, when the reason is inputs-changed. Omitted
+        // rather than empty so a consumer can test for its presence.
+        ...(changed?.length ? { changed } : {}),
+    })
 }
 
 // A render that RAN and produced bytes identical to what was already on

package/src/utils.js

@@ -15,9 +15,11 @@ import runtime from './runtime.js'
 // seeding. Excludes volatile fields like stamp/time/uri so re-discovery
 // on startup doesn't produce a different hash for an unchanged file.
 // Pure: synchronous, no I/O, no engine state.
-export function inputHashOf(entity) {
-    if (!entity) return ''
-    return crypto.createHash('sha1').update(JSON.stringify({
+// The payload both `inputHashOf` and `inputPartsOf` describe. One
+// definition, because a hash and an attribution of that hash that disagree
+// about what went into it is worse than having no attribution.
+function inputPayload(entity) {
+    return {
         meta: entity.meta ?? null,
         content: entity.content ?? null,
         // The bytes' fingerprint, for entities whose content is not in
@@ -46,7 +48,69 @@ export function inputHashOf(entity) {
         // an entity that HAS content is hashed on {meta, content} and its
         // checksum is ignored. This is the seam that was missing.
         inputs: entity.inputs ?? null,
-    })).digest('hex')
+    }
+}
+
+export function inputHashOf(entity) {
+    if (!entity) return ''
+    return crypto.createHash('sha1').update(JSON.stringify(inputPayload(entity))).digest('hex')
+}
+
+// Per-component hashes of the same payload, flat and one level deep:
+//
+//   { 'meta.title': 'ab12cd34', content: '…', 'inputs.shared': '…' }
+//
+// Recorded alongside the combined hash so a later run can say WHICH input
+// moved rather than only that one did. `inputs-changed` on its own sends
+// the reader to a database query to answer something already known here.
+//
+// Components that are null are omitted rather than hashed, so a component
+// appearing or disappearing reads as an added or removed key — which is
+// the answer in its own right when a document gains front-matter or a
+// layout gains a sidecar.
+//
+// Depth one: naming `meta.title` is the difference between a useful answer
+// and "something under meta". Deeper nesting would grow the snapshot for
+// diminishing returns — the key names the field to look at, and the field
+// is then in front of you.
+export function inputPartsOf(entity) {
+    if (!entity) return {}
+    const parts = {}
+    const short = (value) => crypto.createHash('sha1')
+        .update(JSON.stringify(value ?? null)).digest('hex').slice(0, 8)
+    const payload = inputPayload(entity)
+    for (const [component, value] of Object.entries(payload)) {
+        if (value == null) continue
+        if (component === 'meta' || component === 'inputs') {
+            if (typeof value !== 'object' || Array.isArray(value)) {
+                parts[component] = short(value)
+                continue
+            }
+            for (const [key, inner] of Object.entries(value)) {
+                parts[`${component}.${key}`] = short(inner)
+            }
+            continue
+        }
+        parts[component] = short(value)
+    }
+    return parts
+}
+
+// What moved between two part maps. Returns the keys, split by how they
+// differ, so a caller can say "content changed" or "meta.title added"
+// without re-deriving the comparison.
+export function diffInputParts(before, after) {
+    const from = before ?? {}
+    const to = after ?? {}
+    const changed = [], added = [], removed = []
+    for (const key of Object.keys(to)) {
+        if (!(key in from)) added.push(key)
+        else if (from[key] !== to[key]) changed.push(key)
+    }
+    for (const key of Object.keys(from)) {
+        if (!(key in to)) removed.push(key)
+    }
+    return { changed: changed.sort(), added: added.sort(), removed: removed.sort() }
 }
 
 // Canonical lookup variants for an entity — the same four forms the
@@ -990,6 +1054,29 @@ export async function writeOutput(file, bytes) {
     return true
 }
 
+// Did this cycle evaluate the whole corpus, or only what changed?
+//
+// The distinction is what makes a "declared X matched nothing" warning
+// worth printing. On an incremental cycle only changed entities are
+// re-evaluated, so a pattern or preset legitimately matches nothing in a
+// run of two — printing it there means the warning fires on every healthy
+// build, and a warning that always fires is one people filter out, taking
+// the real instance with it.
+//
+// True for: --force, a first-run or wiped database, and a cache
+// invalidation. Those are exactly the cases where the import gate is
+// bypassed and every entity is presented for evaluation.
+// Takes the runtime rather than reading the singleton, so a plugin passes
+// the one it was injected with — which is the singleton in a real build and
+// the harness's stand-in under test.
+export function isFullCycle(rt = runtime) {
+    return !!(
+        rt?.options?.force
+        || rt?.options?.firstRun
+        || rt?.catalog?.cacheInvalidated
+    )
+}
+
 // ── operating-system and file-manager litter ────────────────────────────
 //
 // Exposing a source folder over a network filesystem (mikser-io-webdav) or