mikser-io 9.78.0 → 9.80.0

package/app.js

@@ -43,7 +43,7 @@ function locate(argv) {
         : tool                    ? { type: 'report', tool, toolArgs: value('--tool-args'), json: has('--json') }
         : explain                 ? { type: 'report', explain, json: has('--json') }
         : has('--audit-output')   ? { type: 'report', auditOutput: true, json: has('--json') }
-        : { type: 'build', clear: has('--clear') }
+        : { type: 'build', clear: has('--clear'), renderPresets: has('--render-presets') ? (value('--render-presets') ?? true) : undefined }
 
     return {
         longRunning,

package/docs/diagnostics.md

@@ -882,6 +882,23 @@ surfaces that turn silence into a statement:
 - **A plugin that appears to do nothing** — `No plugins loaded` with a
   config present is a warning naming the file. A config that fails to
   load now exits non-zero rather than loading as empty.
+- **A derivative that did not re-render.** A preset is re-evaluated when
+  its definition moves — its `revision`, its module, or its `match`
+  patterns, all of which the preset entity now carries. Nothing else
+  schedules it: an entity whose source and preset both stood still is
+  skipped, which is what keeps a no-op build from scanning the corpus.
+  When the cause is outside all of that — a preset edited without bumping
+  `revision`, an image library upgraded under the build, a marker deleted
+  by hand — `--render-presets [name]` re-derives regardless. It fails
+  loudly if no assets plugin is loaded to act on it.
+- **A derivative for a source that is gone.** The assets folder sits at
+  the working-folder root, outside both `outputFolder` and the runtime
+  folder, and it is symlinked INTO the output — so an orphaned derivative
+  is still served, and `find out -type f` cannot see it (that tree is
+  reached through a link; use `find -L`). `--clear` removes the folder and
+  re-derives what still has a source. An ordinary build does not: the
+  files plugin performs no delete sweep, so a source deleted from disk
+  stays in the catalog and its derivative stays with it.
 - **A postprocess that could not run** — a stage whose external
   dependency is absent (no chrome for a PDF, no binary for a conversion)
   reports a fault naming the subsystem, and each page that wanted that

package/package.json

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

package/src/engine.js

@@ -408,6 +408,7 @@ export async function setup(options) {
             .option('-c --config <file>', 'set mikser mikser.config.js location', './mikser.config.js')
             .option('-m --mode <mode>', 'set mikser runtime mode', 'development')
             .option('-r --clear', 'clear current state before execution', false)
+            .option('--render-presets [name]', 're-render preset derivatives whose sources and revisions are unchanged; with a name, only that preset')
             .option('-o --output-folder <folder>', 'set mikser output folder relative to working folder', 'out')
             .option('-w --watch', 'watch entities for changes', false)
             .option('-f --force', 'rebuild everything; disable incremental dispatch', false)
@@ -1261,6 +1262,20 @@ export async function setup(options) {
         // Checked at the end of the cycle because that is the first moment the
         // answer is stable: derivatives are produced during the cycle, so
         // asking any earlier would report files that were about to appear.
+        // --render-presets with nothing to consume it.
+        //
+        // The flag is implemented by the assets plugin, so without that plugin
+        // it reaches nobody: the build runs normally, nothing is re-derived,
+        // and the operator is left to notice. Checked here rather than at
+        // onLoaded because the engine's own onLoaded is registered first and
+        // runs before any plugin has set itself up.
+        if (runtime.options.renderPresets && !runtime.state?.assets?.renderPresetsHandled) {
+            useLogger().error({ code: 'render-presets-unhandled' },
+                '--render-presets was passed, but no assets plugin is loaded to act on it. '
+                + 'Nothing was re-derived. Add assets() to the plugins array, or drop the flag.')
+            process.exitCode = 1
+        }
+
         const brokenTargets = await reportBrokenReferences(useLogger())
         await reportMissingAssets(useLogger(), brokenTargets)
 

package/src/instance.js

@@ -69,7 +69,7 @@ export function socketPath(workingFolder) {
 // Newline-delimited JSON, one object per line. Deliberately boring: both ends
 // ship together, so there is nothing to negotiate and no version to carry.
 //
-//   → { type: 'build',  config, clear }
+//   → { type: 'build',  config, clear, renderPresets }
 //   → { type: 'report', config, tool, tools, toolArgs, explain, auditOutput, json }
 //   ← { type: 'log', chunk }        (zero or more, in order)
 //   ← { type: 'done', code }
@@ -316,7 +316,17 @@ async function serveBuild(socket, request, logger) {
         // change that prompted the request — the watermark bug wearing a
         // different hat. Rescanning makes a forwarded build mean what a
         // one-shot means, which is what every existing caller assumes.
-        await runtime.rebuild()
+        // Applied for THIS cycle only. A flag the forwarded path drops is a
+        // silent no-op, which is the failure this surface exists to remove —
+        // and restoring it after keeps the watcher from forcing every later
+        // rebuild.
+        const priorRenderPresets = runtime.options.renderPresets
+        if (request.renderPresets !== undefined) runtime.options.renderPresets = request.renderPresets
+        try {
+            await runtime.rebuild()
+        } finally {
+            runtime.options.renderPresets = priorRenderPresets
+        }
 
         // From the render-error count, NOT from process.exitCode.
         //

package/src/plugins/assets.js

@@ -173,9 +173,30 @@ export function assets(options = {}) {
     // the (revision, format, options) export contract so onImport and
     // onSync stay in sync. Cache-busts local presets so watch-mode edits
     // reload; npm presets import once (their version is the cache key).
+    // Presets whose effective definition moved this cycle: a bumped revision,
+    // an edited module, or widened patterns.
+    //
+    // The fan-out this gates is a full catalog scan, and onImport writes every
+    // preset entity on every build — so gating on "a preset is in the journal"
+    // ran that scan every cycle, including a no-op watch rebuild, where
+    // responsiveness matters most.
+    const changedPresets = new Set()
+
+    async function notePresetChange(preset) {
+        const prior = await findEntity({ id: preset.id })
+        const moved = !prior
+            || prior.checksum !== preset.checksum
+            || JSON.stringify(prior.matches ?? null) !== JSON.stringify(preset.matches ?? null)
+        if (moved) changedPresets.add(preset.name)
+        return moved
+    }
+
     async function buildPreset({ name, uri, watchable }) {
         const cacheBust = watchable ? `?stamp=${Date.now()}` : ''
-        const { revision = 1, format, options } = await import(`${uri}${cacheBust}`)
+        // `options` here would SHADOW the plugin's own config, which the
+        // patterns below need. The module's export and the factory argument
+        // are two different things that were both called options.
+        const { revision = 1, format, options: moduleOptions } = await import(`${uri}${cacheBust}`)
         return {
             id: `/presets/${name}`,
             collection,
@@ -185,7 +206,17 @@ export function assets(options = {}) {
             source: uri,
             format,
             checksum: revision,
-            options,
+            // The patterns this preset selects by, carried on the entity.
+            //
+            // They are half of what decides which files a preset owns, and
+            // they live in CONFIG rather than in the module — so `revision`
+            // alone cannot say the preset's effective definition moved.
+            // Widening a pattern was a silent no-op: match is evaluated as a
+            // file ENTERS the catalog, so a wider one left everything already
+            // in it alone, the build stayed green and the derivative never
+            // appeared.
+            matches: normalizePresetConfig(options.presets?.[name]).matches,
+            options: moduleOptions,
         }
     }
 
@@ -251,7 +282,13 @@ export function assets(options = {}) {
                     destination = changeExtension(destination, entity.preset.format)
                 }
                 entity.destination = path.join(runtime.options.assetsFolder, entityPreset, destination)
-                const ignore = await isPresetRendered(entity)
+                // Two gates sit between a scheduled entity and a render: the
+                // manifest's "its source did not change", and this plugin's
+                // marker. A forced render clears both — a marker at the
+                // current revision is exactly what --render-presets exists to
+                // disregard.
+                const forced = rendererChanged.has(entityToRender.id)
+                const ignore = forced ? false : await isPresetRendered(entity)
                 tasks.push({
                     entity,
                     options: {
@@ -261,7 +298,7 @@ export function assets(options = {}) {
                         // The preset itself moved this cycle, so the manifest's
                         // "its source is unchanged" is true and beside the
                         // point. See the skip decision in engine.js.
-                        rendererChanged: rendererChanged.has(entityToRender.id),
+                        rendererChanged: forced,
                         ignore
                     }
                 })
@@ -291,6 +328,28 @@ export function assets(options = {}) {
         runtime.options.assets = options.assetsFolder || 'assets'
         runtime.options.assetsFolder = path.join(runtime.options.workingFolder, runtime.options.assets)
         logger.debug('Assets folder: %s', runtime.options.assetsFolder)
+
+        // --clear means "throw away what was derived and build it again", and
+        // derivatives are derived — but this folder sits at the working-folder
+        // root, outside both outputFolder and runtimeFolder, so the engine's
+        // clear never reached it. Anything here whose source had gone stayed
+        // forever: still on disk, still SERVED through the symlink below, and
+        // invisible to `find out -type f` because that tree is reached through
+        // a link. The only way out was deleting the folder by hand.
+        //
+        // Cleared here rather than in the engine because the path is not known
+        // until this plugin resolves it — the engine's clear runs before any
+        // plugin's onLoaded.
+        //
+        // Whole folder, not a sweep of orphans: identifying an orphan means
+        // mapping a derivative back to a source, which is the id/name mapping
+        // that has bitten this plugin twice. --clear already accepts a full
+        // rebuild, so re-deriving is the honest cost of asking for one.
+        if (runtime.options.clear) {
+            await rm(runtime.options.assetsFolder, { recursive: true, force: true })
+            logger.info('Assets cleared: %s', runtime.options.assetsFolder)
+        }
+
         await mkdir(runtime.options.assetsFolder, { recursive: true })
 
         let link = path.join(runtime.options.outputFolder, runtime.options.assets)
@@ -375,6 +434,7 @@ export function assets(options = {}) {
             const uri = path.join(runtime.options.presetsFolder, relativePath)
             try {
                 const preset = await buildPreset({ name, uri, watchable: true })
+                await notePresetChange(preset)
                 await createEntity(preset)
                 presets[name] = preset
             } catch (err) {
@@ -399,6 +459,7 @@ export function assets(options = {}) {
             }
             try {
                 const preset = await buildPreset({ name, uri: resolved.uri, watchable: resolved.watchable })
+                await notePresetChange(preset)
                 await createEntity(preset)
                 presets[name] = preset
                 logger.debug('Preset loaded from npm: mikser-io-preset-%s', name)
@@ -458,10 +519,49 @@ export function assets(options = {}) {
         }
 
         const entitiesToRender = new Map()
-        // Entities scheduled because their PRESET changed, not their source.
+        // Entities that must render regardless of markers or manifest: their
+        // preset moved, or --render-presets asked for them.
         const presetMoved = new Set()
+
+        // --render-presets [name]: re-derive though nothing moved.
+        //
+        // The escape hatch for what the incremental machinery cannot see — a
+        // preset edited without bumping `revision`, a marker deleted by hand,
+        // an image library upgraded underneath the build. --clear reaches the
+        // same end only by rebuilding the whole site, and only at startup, so
+        // it cannot be asked of a running watcher at all.
+        const wanted = runtime.options.renderPresets
+        if (wanted) {
+            // Consumed here and nowhere else. The engine checks this at the
+            // end of the cycle: a flag that reaches no plugin has to say so,
+            // rather than building normally and leaving the operator to
+            // notice nothing was re-derived.
+            runtime.state.assets.renderPresetsHandled = true
+
+            const known = Object.keys(runtime.state.assets.presets)
+            const names = wanted === true ? known : [wanted]
+            for (const name of names.filter(n => !known.includes(n))) {
+                useLogger().warn({ code: 'preset-unknown', preset: name },
+                    '--render-presets asked for %j, which is not configured. Known: %s',
+                    name, known.join(', ') || '(none)')
+            }
+            const selected = names.filter(n => known.includes(n))
+            if (selected.length) {
+                for await (const candidate of iterateEntities({ collection: { $ne: collection } })) {
+                    const candidatePresets = await getEntityPresets(candidate)
+                    if (!candidatePresets.some(n => selected.includes(n))) continue
+                    assetsMap[candidate.id] ??= candidatePresets
+                    presetMoved.add(candidate.id)
+                    entitiesToRender.set(candidate.id, candidate)
+                }
+                useLogger().info('Presets re-rendering: %s (%d source(s))',
+                    selected.join(', '), entitiesToRender.size)
+            }
+        }
         await map(useJournal('Assets provision', [OPERATION.CREATE, OPERATION.UPDATE], signal), async ({ entity }) => {
             if (entity.collection == collection) {
+                // Only when this preset's definition actually moved.
+                if (!changedPresets.has(entity.name)) return
                 // A preset moved — its `revision` was bumped, or its module
                 // changed. Everything that uses it has to re-render.
                 //