mikser-io 9.79.0 → 9.81.0

package/app.js

@@ -43,10 +43,16 @@ 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,
+        // The flags this process was invoked with, forwarded so the INSTANCE
+        // can reject an unknown one. This pre-parser reads the few options it
+        // needs and passes the rest along, so commander never runs on a
+        // forwarded invocation — and a typo was accepted in silence, built,
+        // and reported success.
+        argv,
         workingFolder: value('--working-folder', '-i') ?? '.',
         config: value('--config', '-c') ?? 'mikser.config.js',
         request,
@@ -74,7 +80,7 @@ async function main() {
         const code = await forward({
             workingFolder,
             config: path.resolve(where.workingFolder, where.config),
-            request: where.request,
+            request: { ...where.request, argv: where.argv },
         })
         // null means nobody was listening — carry on exactly as before.
         if (code !== null) process.exit(code)

package/docs/diagnostics.md

@@ -882,6 +882,15 @@ 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
@@ -905,9 +914,12 @@ surfaces that turn silence into a statement:
   evidence:
   - **The emitted output**, read back and resolved the way a browser
     would — `src`, `href`, `poster`, `srcset` and CSS `url()` across
-    html and css. Anything resolving to no file warns under
-    `reference-broken`, naming the url and the pages carrying it. This
-    one sees paths written by hand, not just helper output.
+    html and css. This one sees paths written by hand, not just helper
+    output, and it separates two problems that share a symptom:
+    `reference-wrong-base` when the file exists elsewhere in the output
+    (the url was built from the wrong root, and the report names where
+    the file actually is), `reference-broken` when nothing produced it
+    at all.
   - **The render track**, which records every `asset()` / `resource()`
     call and tests the destination it built. This catches a url that
     never reaches an html file at all — one emitted into a feed or a

package/package.json

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

package/src/engine.js

@@ -116,15 +116,31 @@ async function reportBrokenReferences(logger) {
     const named = (files) =>
         files.slice(0, 3).join(', ') + (files.length > 3 ? ` and ${files.length - 3} more` : '')
 
-    for (const { url, target, files } of broken.slice(0, SHOWN)) {
-        logger.warn({ code: 'reference-broken', url, target, files },
-            'Resolves to nothing: %s (from %s) — %s', url, named(files), target)
+    for (const { url, target, files, elsewhere } of broken.slice(0, SHOWN)) {
+        // Two different problems wear the same symptom. A target whose file
+        // exists elsewhere in the output is a base that is wrong, not an asset
+        // that is missing — and saying which one saves the reader the search.
+        if (elsewhere?.length) {
+            logger.warn({ code: 'reference-wrong-base', url, target, files, elsewhere },
+                'Points at the wrong place: %s (from %s) — nothing at %s, but the file is at %s',
+                url, named(files), target, elsewhere.join(', '))
+        } else {
+            logger.warn({ code: 'reference-broken', url, target, files },
+                'Resolves to nothing, and nothing produced it: %s (from %s) — %s',
+                url, named(files), target)
+        }
     }
     if (broken.length) {
-        logger.warn({ code: 'reference-broken-summary', broken: broken.length, checked },
-            '%d of %d reference(s) in the output resolve to nothing%s. A URL helper builds the '
-            + 'path rather than looking it up, so these are links to files nothing produced.',
-            broken.length, checked, broken.length > SHOWN ? `, ${SHOWN} shown` : '')
+        const misplaced = broken.filter(b => b.elsewhere?.length).length
+        logger.warn({
+            code: 'reference-broken-summary',
+            broken: broken.length, wrongBase: misplaced, checked,
+        },
+            '%d of %d reference(s) in the output resolve to nothing%s. Wrong base (the file exists '
+            + 'elsewhere): %d. Never produced: %d. A URL helper builds the path rather than looking '
+            + 'it up, so neither kind can fail at the point it is written.',
+            broken.length, checked, broken.length > SHOWN ? `, ${SHOWN} shown` : '',
+            misplaced, broken.length - misplaced)
     }
 
     // Grouped by how FAR each climbed, because a site whose every over-deep url
@@ -408,6 +424,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 +1278,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 }
@@ -286,6 +286,39 @@ function refuseConfig(socket, request, wrongConfig) {
     })
 }
 
+// An option the instance's own commander does not recognise.
+//
+// A forwarded invocation never reaches commander: app.js pre-parses the few
+// flags it needs and forwards the rest, so `mikser --bogus` against a running
+// watcher built normally and exited 0, while the same command with nothing
+// listening was rejected outright. Same words, two answers, and the quiet one
+// is the one that looks like it worked.
+//
+// parseOptions REPORTS unknowns without applying anything, which is what makes
+// this safe to run against the live instance's option table.
+function refuseUnknownFlags(socket, request) {
+    const argv = Array.isArray(request.argv) ? request.argv : null
+    if (!argv?.length) return false
+    const commander = runtime.engine?.commander
+    if (!commander) return false
+    let unknown = []
+    try {
+        unknown = commander.parseOptions([...argv]).unknown ?? []
+    } catch {
+        return false   // never let a probe refuse a legitimate build
+    }
+    unknown = unknown.filter(a => a.startsWith('-'))
+    if (!unknown.length) return false
+    frame(socket, {
+        type: 'refused',
+        reason: `unknown option ${unknown.map(u => `'${u}'`).join(', ')}.`,
+        detail: 'Forwarded to the instance running in this folder, which does not recognise it. '
+            + 'The same command with nothing listening would have been rejected too — this says so '
+            + 'rather than building as though the flag had been understood.',
+    })
+    return true
+}
+
 function refuseStale(socket, movedFile) {
     frame(socket, {
         type: 'refused',
@@ -316,7 +349,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.
         //
@@ -363,6 +406,7 @@ export function serveInstance() {
                     // instance's — a report against the wrong config is the
                     // original incident, and it is wrong whether or not it
                     // writes anything.
+                    if (refuseUnknownFlags(socket, request)) return
                     const wrongConfig = configMismatch(request.config)
                     if (wrongConfig) return refuseConfig(socket, request, wrongConfig)
                     const movedFile = await configStale()

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
                     }
                 })
@@ -397,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) {
@@ -421,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)
@@ -480,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.
                 //

package/src/references.js

@@ -173,5 +173,31 @@ export async function checkReferences(outputFolder, { siteRoots = [] } = {}) {
         }
     }
 
+    // "It was never written" and "it is written somewhere else" are different
+    // problems with one symptom, and they were reported with one sentence.
+    //
+    // A missing target whose FILE exists elsewhere in the output is almost
+    // always a base problem: the url was built from the wrong root, or with a
+    // segment too many. Naming where the file actually is turns "resolves to
+    // nothing" into the answer. A target that exists nowhere really was never
+    // produced — a preset that did not run, an extension nothing emits.
+    //
+    // Indexed only when something is broken, so a clean build pays nothing.
+    if (broken.size) {
+        const byName = new Map()
+        for (const file of await globby('**/*', {
+            cwd: outputFolder, followSymbolicLinks: true, onlyFiles: true, suppressErrors: true,
+        })) {
+            const name = path.basename(file)
+            if (!byName.has(name)) byName.set(name, [])
+            byName.get(name).push(file)
+        }
+        for (const entry of broken.values()) {
+            const elsewhere = (byName.get(path.basename(entry.target)) ?? [])
+                .filter(f => f !== entry.target)
+            if (elsewhere.length) entry.elsewhere = elsewhere.slice(0, 3)
+        }
+    }
+
     return { broken: [...broken.values()], overDeep: [...overDeepRefs.values()], checked }
 }