mikser-io 9.12.0 → 9.14.0

package/index.js

@@ -2,6 +2,7 @@ export { default as runtime } from './src/runtime.js'
 export * as constants from './src/constants.js'
 export * from './src/utils.js'
 export * from './src/auth.js'
+export * from './src/report.js'
 export * from './src/lifecycle.js'
 export * from './src/database/index.js'
 export * from './src/journal.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.12.0",
+  "version": "9.14.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,6 +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 render from './render.js'
 import postprocess, { loadPlugin as loadPostPlugin } from './postprocess.js'
 import map from 'p-map'
@@ -115,6 +116,8 @@ export async function setup(options) {
             .option('-f --force', 'rebuild everything; disable incremental dispatch', false)
             .option('-R --resume', 'continue from journal entries left by a previous interrupted run; skip the initial filesystem scan', false)
             .option('--verify', 'verify output folder against manifest; report drift instead of building', false)
+            .option('--explain <entity>', 'explain one entity — layout, destination, hashes, refClosure, and whether a build would re-render it. Accepts an id, a meta.href, or an id without its extension. Reports instead of building.')
+            .option('--json', 'machine-readable output (with --explain, and for a build\'s render/skip/warning report)', false)
             .option('-d --debug', 'display debug statements')
             .option('-t --trace', 'display trace statements')
             .option('-e --runtime-folder <folder>', 'set mikser runtime folder relative to working folder', 'runtime')
@@ -226,6 +229,25 @@ export async function setup(options) {
         //                 corruption, but state is messy)
         //   2 — errors   (missing or mismatched files — output is
         //                 actually wrong on disk)
+        // --explain: report on one entity and exit, like --verify. Placed
+        // before it because a caller reaching for both means the explain.
+        //
+        // Exit codes:
+        //   0 — the entity was found and described
+        //   3 — not in the catalog (distinct from --verify's 1/2, which are
+        //       about output drift; "no such entity" is neither clean nor
+        //       corrupt, it is a question that could not be answered)
+        if (runtime.options.explain) {
+            const { explain, formatExplain } = await import('./explain.js')
+            const report = await explain(runtime.options.explain)
+            if (runtime.options.json) {
+                process.stdout.write(JSON.stringify(report, null, 2) + '\n')
+            } else {
+                process.stdout.write(formatExplain(report) + '\n')
+            }
+            process.exit(report.found ? 0 : 3)
+        }
+
         if (runtime.options.verify) {
             if (!runtime.manifest) {
                 logger.error('Verify: no manifest available — nothing to check against')
@@ -331,13 +353,21 @@ export async function setup(options) {
                 // next run. A postprocess-aware manifest that also
                 // skips when the postprocess output is current would
                 // close the gap — not yet implemented.
-                if (!options.postprocessor && runtime.manifest?.shouldSkip(entity, mutatedRefs, currentHashes, mutatedEntities)) {
+                const decision = options.postprocessor
+                    // A postprocessor consumes the intermediate rendered
+                    // file, so skipping would leave its input missing.
+                    ? { skip: false, reason: 'postprocessor' }
+                    : runtime.manifest?.skipDecision(entity, mutatedRefs, currentHashes, mutatedEntities)
+                        ?? { skip: false, reason: 'no-manifest' }
+                if (decision.skip) {
                     skipped++
                     entry.output = { success: true, skipped: 'manifest' }
                     await updateEntry({ id, output: entry.output })
+                    reportSkipped(entity, decision.reason)
                     logger.debug('Manifest skip: %s → %s', entity.name || entity.id, entity.destination)
                     return
                 }
+                reportRendered(entity, decision.reason)
                 // Project reference-marker keys (`$author`, `$hero`, …)
                 // into their normalized form (`author`, `hero`) before
                 // the entity crosses into the renderer — applies whether
@@ -716,6 +746,10 @@ export async function setup(options) {
             }
         }
         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()
     })
 
     onCancelled(async () => {
@@ -723,7 +757,18 @@ export async function setup(options) {
         logger.notice('Mikser restarted')
     })
 
-    console.info('\x1b[1mmikser\x1b[22;5;38;2;255;63;0m.\x1b[0m %s\n', packageInfo.version)
+    // Banner to stderr under --json, for the same reason the logger goes
+    // there: stdout must contain only the document.
+    //
+    // argv directly, not runtime.options: commander parses in a lifecycle
+    // hook, which runs after setup() returns, so options.json is still
+    // undefined here. The logger has no such problem — it writes during the
+    // run, by which time options exist.
+    if (runtime.options?.json || process.argv.includes('--json')) {
+        process.stderr.write(`mikser. ${packageInfo.version}\n`)
+    } else {
+        console.info('\x1b[1mmikser\x1b[22;5;38;2;255;63;0m.\x1b[0m %s\n', packageInfo.version)
+    }
     return runtime
 }
 

package/src/explain.js

@@ -0,0 +1,194 @@
+// `--explain <entity-id>` — what happened to one entity, and why.
+//
+// Assembly, not new machinery: every line comes from state the engine already
+// keeps (catalog, manifest snapshots, inputHashOf, the layouts matcher's
+// output). It exists because the question asked most often about a build is
+// "why did this NOT change?", and until now the only way to answer it was to
+// read plugin source and hand-query runtime/mikser.sqlite — which works, and
+// 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 { findEntity } from './catalog.js'
+import runtime from './runtime.js'
+
+const shortHash = (h) => (h ? String(h).slice(0, 8) : null)
+const when = (ms) => (ms ? new Date(ms).toISOString().replace('T', ' ').slice(0, 19) : null)
+
+// Resolve loosely: an id, a meta.href, or an id without its extension. The
+// same extension-tolerant resolution refs and the catalog already use — so a
+// caller can paste whatever form they have in front of them.
+async function resolve(reference) {
+    const direct = await findEntity({ id: reference })
+    if (direct) return direct
+    const byHref = await findEntity({ 'meta.href': reference })
+    if (byHref) return byHref
+    // id-minus-extension: /documents/bg/index → /documents/bg/index.md
+    const like = await findEntity({ id: { $regex: `^${reference.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.[^./]+$` } })
+    return like ?? null
+}
+
+export async function explain(reference) {
+    const entity = await resolve(reference)
+    if (!entity) {
+        return {
+            found: false,
+            reference,
+            // The likeliest reasons, in the order they actually happen.
+            hint: 'Not in the catalog. Either nothing imported it (check the source plugin\'s folder and extensions), '
+                + 'it was filtered as junk (see the `junk` config), or the id is spelled differently — '
+                + 'try the meta.href or the id without its extension.',
+        }
+    }
+
+    const snapshots = runtime.manifest?.snapshotsFor(entity.id) ?? []
+    const currentHash = inputHashOf(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
+    // would say "skipped", which is true of the catalog and misleading about
+    // the next build. So check the file too, and say which is being reported.
+    //
+    // A caveat rather than a bug: some plugins compose a checksum from more
+    // than one file (layouts folds in its .js sidecar), so a difference does
+    // not always mean the entity's own source moved. Both values are reported
+    // and the wording avoids claiming more than is known.
+    let source = null
+    if (entity.uri) {
+        try {
+            const onDisk = await fileChecksum(entity.uri)
+            source = {
+                uri: entity.uri,
+                catalogChecksum: entity.checksum ?? null,
+                fileChecksum: onDisk,
+                differs: entity.checksum != null && entity.checksum !== onDisk,
+            }
+        } catch (err) {
+            source = { uri: entity.uri, error: err.code === 'ENOENT' ? 'file is gone' : err.message }
+        }
+    }
+
+    return {
+        found: true,
+        id: entity.id,
+        collection: entity.collection,
+        type: entity.type,
+        name: entity.name,
+        // The layouts matcher records both the layout and the pattern that
+        // claimed the entity; with several layouts, all of them.
+        layouts: (entity.layouts ?? (entity.layout ? [entity.layout] : [])).map(l => ({
+            name: l?.name ?? null,
+            matchedBy: l?.matchedBy ?? entity.meta?.layoutMatch ?? null,
+            format: l?.format ?? null,
+            postprocessors: l?.postprocessors ?? (l?.postprocessor ? [l.postprocessor] : []),
+            // The layout's OWN declared inputs — its .js sidecar, and the
+            // digest covering everything the sidecar imports. Surfaced on the
+            // page's report rather than only the layout's, because "does
+            // editing this helper module invalidate my page" is asked about
+            // the page. Not seeing it is what makes people build a workaround
+            // for something already handled.
+            inputs: l?.inputs ?? null,
+        })),
+        destination: entity.destination ?? null,
+        lang: entity.meta?.lang ?? null,
+        href: entity.meta?.href ?? null,
+        // Why a render would or would not happen. `inputHash` is the entity's
+        // 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',
+        inputs: entity.inputs ?? null,
+        checksum: entity.checksum ?? null,
+        source,
+        renders: snapshots.map(snap => ({
+            destination: snap.destination,
+            renderedAt: when(snap.renderedAt),
+            inputHash: snap.inputHash,
+            // The single most useful field: does this entity's current hash
+            // match what it was last rendered at?
+            stale: snap.inputHash !== currentHash,
+            outputHash: snap.outputHash ?? null,
+            parent: snap.parent ?? null,
+            refClosure: (snap.refClosure ?? []).map(entry =>
+                entry.kind === 'query'
+                    ? { kind: 'query', filter: entry.filter }
+                    : { kind: entry.kind, target: entry.target, hash: shortHash(entry.hash) }),
+        })),
+        // What a plain build would do next, stated plainly.
+        verdict: source?.error === 'file is gone'
+            ? 'source file is gone — a build would DELETE this entity and unlink its output'
+            : source?.differs
+                ? 'source differs from the catalog — a build would re-import it first, then re-render. '
+                  + '(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.'
+            : snapshots.some(s => s.inputHash !== currentHash)
+                ? 'would re-render — the entity\'s input hash differs from what it was last rendered at'
+                : 'would be SKIPPED — input hash unchanged. A dependency in refClosure changing is the only other thing that would re-render it.',
+        lookupKeys: lookupKeys(entity),
+    }
+}
+
+// Human-readable rendering. Deliberately aligned columns rather than prose:
+// the point is to be scanned, and to be diffable between two runs.
+export function formatExplain(report) {
+    const out = []
+    const row = (label, value) => out.push(`${label.padEnd(12)}${value}`)
+
+    if (!report.found) {
+        out.push(`not found   ${report.reference}`)
+        out.push('')
+        out.push(report.hint)
+        return out.join('\n')
+    }
+
+    row('entity', `${report.id}   (${report.collection}/${report.type})`)
+    if (report.href) row('href', report.href)
+    if (report.lang) row('lang', report.lang)
+    if (report.layouts.length) {
+        for (const l of report.layouts) {
+            row('layout', `${l.name ?? '(unnamed)'}${l.matchedBy ? `   (matched ${JSON.stringify(l.matchedBy)})` : ''}`
+                + (l.postprocessors?.length ? `   → ${l.postprocessors.join(' → ')}` : ''))
+            const li = l.inputs && Object.entries(l.inputs).filter(([, v]) => v != null)
+            if (li?.length) {
+                out.push(`  inputs     ${li.map(([k, v]) => `${k} ${shortHash(v)}`).join(', ')}`)
+            }
+        }
+    } else {
+        row('layout', 'none matched — this entity is not rendered')
+    }
+    row('destination', report.destination ?? '(none — never assigned)')
+    row('inputHash', `${shortHash(report.inputHash)}  = ${report.inputHashOf}`)
+    if (report.source) {
+        row('source', report.source.error
+            ? `${report.source.uri}   [${report.source.error}]`
+            : `${report.source.uri}${report.source.differs ? '   [DIFFERS from the catalog — not yet re-imported]' : ''}`)
+    }
+    if (report.inputs) {
+        const parts = Object.entries(report.inputs)
+            .filter(([, v]) => v != null)
+            .map(([k, v]) => `${k} ${shortHash(v)}`)
+        if (parts.length) row('inputs', parts.join(', '))
+    }
+
+    if (!report.renders.length) {
+        row('rendered', 'never')
+    }
+    for (const r of report.renders) {
+        row('rendered', `${r.renderedAt ?? 'unknown'}   → ${r.destination}`
+            + (r.stale ? '   [STALE: input hash moved since]' : '   [current]'))
+        const closure = r.refClosure
+        row('refClosure', `${closure.length} edge${closure.length === 1 ? '' : 's'}`)
+        for (const e of closure) {
+            out.push(e.kind === 'query'
+                ? `  query      ${JSON.stringify(e.filter)}`
+                : `  ${e.kind.padEnd(10)} ${e.target}${e.hash ? `  ${e.hash}` : ''}`)
+        }
+    }
+
+    out.push('')
+    out.push(report.verdict)
+    return out.join('\n')
+}

package/src/logger.js

@@ -122,7 +122,13 @@ function createTerminalStream() {
     return new Writable({
         write(chunk, enc, cb) {
             if (gauge) gauge.disable()
-            process.stdout.write(chunk, enc)
+            // --json puts a machine-readable document on stdout, so every
+            // log line has to go somewhere else or the document cannot be
+            // parsed. stderr rather than silence: the operator still sees
+            // the build, and `mikser --explain x --json | jq` still works —
+            // which is the entire point of the flag.
+            const out = runtime.options?.json ? process.stderr : process.stdout
+            out.write(chunk, enc)
             if (gauge) gauge.enable()
             cb()
         },

package/src/manifest.js

@@ -180,6 +180,10 @@ async function hashOutputFile(destination) {
 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
+        FROM mikser_snapshots WHERE id = ? ORDER BY destination
+    `)
     const stmtLookup = db.prepare(`
         SELECT id, destination, inputHash, outputHash, refClosure, renderedAt, parent
         FROM mikser_snapshots WHERE id = ? AND destination = ?
@@ -251,23 +255,51 @@ export function createManifest(db) {
             return rowToSnap(stmtLookup.get(query.id, query.destination))
         },
 
+        // EVERY snapshot for an entity, not just the one at a known
+        // destination. An entity can have several — one per matched layout,
+        // one per paginated page — and a caller asking "what happened to
+        // this?" does not know the destinations in advance. That is exactly
+        // the position an operator (or an agent) is in when a page did not
+        // change and they want to know why.
+        snapshotsFor(id) {
+            if (!id) return []
+            return stmtLookupById.all(id).map(rowToSnap)
+        },
+
         // Should this render be skipped? See the original docstring in
         // the prior NDJSON-backed implementation — logic is unchanged,
         // backing storage is the only thing that changed.
+        // Boolean wrapper, kept because that is what the render loop asked
+        // for first. skipDecision carries the same logic plus WHY, which is
+        // what a machine-readable build report needs — "Rendered: 16" is a
+        // number nobody can assert on.
         shouldSkip(entity, mutatedRefs, currentHashes, mutatedEntities) {
-            if (entity?.meta?.cache === false) return false
+            return this.skipDecision(entity, mutatedRefs, currentHashes, mutatedEntities).skip
+        },
+
+        // { skip, reason } — reason is set either way, and the vocabulary is
+        // stable so it can be asserted against:
+        //
+        //   unchanged        nothing this render depends on moved
+        //   never-rendered   no snapshot: first build, or it never rendered
+        //   inputs-changed   the entity's own hash moved
+        //   ref-changed      a $-ref or partial it depends on moved
+        //   query-matched    an entity matching a recorded query mutated
+        //   cache-disabled   meta.cache === false
+        skipDecision(entity, mutatedRefs, currentHashes, mutatedEntities) {
+            if (entity?.meta?.cache === false) return { skip: false, reason: 'cache-disabled' }
             const snapshot = this.lookup(entity)
-            if (!snapshot?.inputHash) return false
-            if (inputHashOf(entity) !== snapshot.inputHash) return false
-            if (!snapshot.refClosure?.length) return true
+            if (!snapshot?.inputHash) return { skip: false, reason: 'never-rendered' }
+            if (inputHashOf(entity) !== snapshot.inputHash) return { skip: false, reason: 'inputs-changed' }
+            if (!snapshot.refClosure?.length) return { skip: true, reason: 'unchanged' }
             const sourceLang = entity?.meta?.lang ?? null
             for (const entry of snapshot.refClosure) {
                 if (entry.kind === 'query') {
-                    if (!entry.filter) return false
+                    if (!entry.filter) return { skip: false, reason: 'query-matched' }
                     if (!mutatedEntities?.size) continue
                     const matcher = sift(entry.filter)
                     for (const mutated of mutatedEntities.values()) {
-                        if (matcher(mutated)) return false
+                        if (matcher(mutated)) return { skip: false, reason: 'query-matched' }
                     }
                     continue
                 }
@@ -286,13 +318,13 @@ export function createManifest(db) {
                         continue
                     }
                 }
-                if (!entry.hash) return false
+                if (!entry.hash) return { skip: false, reason: 'ref-changed' }
                 const currentHash = currentHashes?.get(entry.target)
                 if (currentHash === undefined) continue
-                if (currentHash === null) return false
-                if (currentHash !== entry.hash) return false
+                if (currentHash === null) return { skip: false, reason: 'ref-changed' }
+                if (currentHash !== entry.hash) return { skip: false, reason: 'ref-changed' }
             }
-            return true
+            return { skip: true, reason: 'unchanged' }
         },
 
         // Record a successful render. Single INSERT OR REPLACE.

package/src/plugins/assets.js

@@ -5,6 +5,7 @@ import { createRequire } from 'node:module'
 import { globby } from 'globby'
 import _ from 'lodash'
 import map from 'p-map'
+import { reportWarning } from '../report.js'
 
 // Normalize a `options.presets[name]` value to a consistent
 // { matches, options } shape so callers don't have to inspect which form
@@ -124,6 +125,7 @@ export function assets(options = {}) {
         for (const preset of configured) {
             if (matchTally.matched.has(preset)) continue
             const { matches } = normalizePresetConfig(options.presets[preset])
+            reportWarning('preset-no-match', { preset, evaluated: matchTally.evaluated, patterns: matches })
             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 — ' +

package/src/plugins/commands.js

@@ -31,16 +31,16 @@ export function commands(options = {}) {
             if (_.endsWith(command, '&')) {
                 command = command.slice(0, -1)
                 if (!running[command]) {
-                    logger.info('Command: %s', command, runtime.options.wokrkingFolder)
-                    const subprocess = execaCommand(command, { cwd: runtime.options.wokrkingFolder, all: true })
+                    logger.info('Command: %s', command, runtime.options.workingFolder)
+                    const subprocess = execaCommand(command, { cwd: runtime.options.workingFolder, all: true })
                     eachLine(subprocess.all, line => logger.info(line))
                     running[command] = subprocess
                         .then(() => delete running[command])
                         .catch(err => logger.error(err, 'Command error'))
                 }
             } else {
-                logger.info('Command: %s', command, runtime.options.wokrkingFolder)
-                const subprocess = execaCommand(command, { cwd: runtime.options.wokrkingFolder, all: true })
+                logger.info('Command: %s', command, runtime.options.workingFolder)
+                const subprocess = execaCommand(command, { cwd: runtime.options.workingFolder, all: true })
                 await eachLine(subprocess.all, line => logger.debug(line))
                 await subprocess
             }

package/src/plugins/render/preset.js

@@ -1,7 +1,25 @@
 import { mkdir } from 'node:fs/promises'
 import path from 'node:path'
 
+// A renderer's `load` runs for EVERY entity in the cycle, not only the ones
+// this renderer will render — that is deliberate and is how renderAsset
+// installs runtime.asset() for all templates. So this has to tolerate an
+// entity that has no preset, rather than assume it is looking at one.
+//
+// Without the guard, adding renderPreset() to a project's plugin list made
+// every page render throw on `entity.preset.uri` — and a crash reads as
+// "you have found something real", which is a much more expensive wrong
+// signal than a no-op. The names invite exactly that mistake:
+//
+//   renderAsset()   provides runtime.asset() to templates  (a URL helper)
+//   assets()        runs presets and produces derivatives   (the work)
+//   renderPreset()  renders a preset-authored layout        (this file)
+//
+// All three are named after the object they concern rather than the job they
+// do, so reasoning "the one that RUNS presets must be renderPreset" is wrong
+// but not unreasonable.
 export async function load({ entity, runtime }) {
+    if (!entity?.preset?.uri) return
     const preset = await import(`${entity.preset.uri}?stamp=${Date.now()}`)
     runtime.preset = preset.default
 }

package/src/report.js

@@ -0,0 +1,76 @@
+// The machine-readable build report behind `--json`.
+//
+// `Rendered: 16` is a number nobody can assert on. Verifying "did my change
+// land" without this means diffing the output folder against a snapshot taken
+// beforehand — a lot of ceremony for one question.
+//
+// The valuable field is `reason`, not the counts. And a stable `code` on a
+// warning matters more than its prose: it lets a caller assert "this build
+// produced no preset-no-match" instead of grepping a sentence that may be
+// reworded — which is exactly the kind of assertion that should not break
+// when someone improves the wording.
+import runtime from './runtime.js'
+
+function store() {
+    runtime.state ??= {}
+    runtime.state.report ??= { rendered: [], skipped: [], warnings: [], gated: 0 }
+    return runtime.state.report
+}
+
+// An entity whose SOURCE did not change is gated at import and never becomes
+// a render task at all — so it appears in neither `rendered` nor `skipped`,
+// and the two lists would not reconcile with the corpus size without saying
+// so. Counted rather than listed: on a 14k-entity site the list would be
+// almost the whole catalog on almost every build, which is noise in a
+// document meant to answer "did my change land".
+export function reportGated(count = 1) {
+    if (!runtime.options?.json) return
+    store().gated += count
+}
+
+export function reportRendered(entity, reason) {
+    if (!runtime.options?.json) return
+    store().rendered.push({ id: entity?.id, destination: entity?.destination ?? null, reason })
+}
+
+export function reportSkipped(entity, reason) {
+    if (!runtime.options?.json) return
+    store().skipped.push({ id: entity?.id, destination: entity?.destination ?? null, reason })
+}
+
+// Called ALONGSIDE logger.warn, not instead of it: a human reading the
+// terminal still needs the sentence, and the sentence is where the
+// explanation lives. This carries the assertable part.
+//
+// `code` is the contract. Add fields freely; renaming a code is a breaking
+// change to anyone asserting on it.
+export function reportWarning(code, fields = {}) {
+    if (!runtime.options?.json) return
+    store().warnings.push({ code, ...fields })
+}
+
+export function buildReport() {
+    const report = store()
+    return {
+        rendered: report.rendered,
+        skipped: report.skipped,
+        warnings: report.warnings,
+        summary: {
+            rendered: report.rendered.length,
+            // Renders that were CONSIDERED and skipped by the manifest.
+            skipped: report.skipped.length,
+            // Entities gated at import because their source was unchanged, so
+            // no render was ever scheduled. Different question, different
+            // number — see reportGated.
+            gated: report.gated,
+            warnings: report.warnings.length,
+        },
+    }
+}
+
+// Emitted once, after the cycle, on stdout — which the logger has vacated
+// under --json precisely so this can be the only thing there.
+export function emitReport() {
+    if (!runtime.options?.json) return
+    process.stdout.write(JSON.stringify(buildReport(), null, 2) + '\n')
+}

package/src/source.js

@@ -44,6 +44,7 @@ import pMap from 'p-map'
 import runtime from './runtime.js'
 import { ACTION } from './constants.js'
 import { checksum as fileChecksum, checksumOf, junkIgnore } from './utils.js'
+import { reportGated } from './report.js'
 import { findById, findEntities, checksumsByCollection } from './catalog.js'
 import { useDatabase } from './database/index.js'
 
@@ -450,6 +451,9 @@ export function useSource(core, options) {
         const chksum = await gateChecksum(file, id, { reload, priorChecksums, bytes })
         if (chksum === null) {
             if (stats) stats.skipped++
+            // Never becomes a render task, so it would otherwise be invisible
+            // in the --json report. Counted, not listed.
+            reportGated()
             return
         }