mikser-io 9.16.0 → 9.18.0

package/package.json

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

package/src/config.js

@@ -3,6 +3,7 @@ import { useLogger } from './engine.js'
 import { onLoad } from './lifecycle.js'
 import { checksum } from './utils.js'
 import path from 'node:path'
+import { existsSync } from 'node:fs'
 
 onLoad(async () => {
     const logger = useLogger()
@@ -29,15 +30,31 @@ onLoad(async () => {
         runtime.options.configChecksum = null
     }
 
-    try {
+    // Absence is decided by looking for the file, NOT by catching
+    // ERR_MODULE_NOT_FOUND from the import.
+    //
+    // Node raises that same code for "the config file is missing" and for
+    // "the config file exists and something IT imports is missing" — a
+    // mistyped package name, a renamed local module, a dependency that
+    // was never installed. Catching the code swallowed both, so a config
+    // with one bad import loaded as `{}` and the build reported "No
+    // plugins loaded" and exited 0: a green build with an empty output
+    // folder, one line away from having printed the config's path.
+    //
+    // Every other config failure was already loud — a syntax error or a
+    // throw during evaluation both exit 1. Module resolution was the one
+    // silent case, so this brings it in line rather than inventing a new
+    // policy.
+    if (!existsSync(configFile)) {
+        logger.debug('No config file at %s — using defaults', configFile)
+    } else {
+        // No catch: any failure loading a config that EXISTS is fatal.
         const config = await import(configFile)
         if (typeof config.default == 'function') {
             runtime.config = await config.default(runtime)
         } else if (typeof config.default == 'object') {
             runtime.config = config.default
         }
-    } catch (err) {
-        if (err.code != 'ERR_MODULE_NOT_FOUND') throw err
     }
 
     // v8 used to walk `runtime.config.plugins` looking for matching

package/src/manifest.js

@@ -306,7 +306,20 @@ export function createManifest(db) {
         //   ref-changed      a $-ref or partial it depends on moved
         //   query-matched    an entity matching a recorded query mutated
         //   cache-disabled   meta.cache === false
+        //   force            --force: skip nothing, ask nothing
         skipDecision(entity, mutatedRefs, currentHashes, mutatedEntities) {
+            // --force means "ignore what you think you know". THREE gates can
+            // stop a render — source.js's import checksum gate, layouts'
+            // dispatch filter, and this one — and force reached only the
+            // first two. Since this one runs last, a forced build re-imported
+            // everything (gated=0), re-dispatched everything, and then
+            // dropped all of it here with reason `unchanged`: rendered=0, and
+            // a summary that read like a successful build.
+            //
+            // That made --force useless in exactly the situation it exists
+            // for, which is when the invalidation graph is under suspicion —
+            // including the advice the preset no-match warning gives.
+            if (runtime.options?.force) return { skip: false, reason: 'force' }
             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' }

package/src/plugins/files.js

@@ -86,25 +86,41 @@ export function files(options = {}) {
                         link: await link(source)
                     })
                     break
-                case ACTION.UPDATE:
+                case ACTION.UPDATE: {
                     const current = await findEntity({ id })
-                    if (current?.checksum != checksum) {
+                    // `checksum` is the source-checksum FUNCTION from the
+                    // plugin context, not a value. Comparing the stored
+                    // string against it was never equal, so the guard
+                    // always passed and every sync re-wrote the entity —
+                    // `synced = false` was unreachable.
+                    const currentChecksum = await checksum(source)
+                    if (current?.checksum != currentChecksum) {
                         await updateEntity({
                             id,
                             uri,
-                            name: relativePath,
+                            // `name` — the prefixed form, as CREATE uses.
+                            // This read `relativePath`, so an update
+                            // dropped the outputFolder prefix while
+                            // meta.url two lines down kept it. The assets
+                            // plugin builds preset destinations from
+                            // `name`, so a file replaced under watch had
+                            // its derivatives written somewhere else than
+                            // the same file freshly imported, and
+                            // meta.presets recorded the wrong path.
+                            name,
                             collection,
                             type,
                             format,
                             source,
                             meta: { url: '/' + name },
-                            checksum: await checksum(source),
+                            checksum: currentChecksum,
                             link: await link(source)
                         })
                     } else {
                         synced = false
                     }
                     break
+                }
                 case ACTION.DELETE:
                     await removeLink(relativePath)
                     await deleteEntity({
@@ -143,6 +159,13 @@ export function files(options = {}) {
             // journal with phantom mutations and triggering downstream
             // re-dispatch of aggregate layouts whose recorded query deps
             // matched the collection.
+            // --force (and a wiped catalog) must defeat the gate, the same
+            // way source.js's gateChecksum lets them defeat its own. This
+            // plugin carries a second, independent gate, and it honoured
+            // neither — so no amount of forcing ever re-derived a file's
+            // name / meta.url / meta.presets, and a catalog holding bad
+            // `files` rows had no repair path short of deleting them.
+            const forced = runtime.options.force || runtime.catalog?.cacheInvalidated
             const priorChecksums = checksumsByCollection(collection)
             await pMap(paths, async relativePath => {
                 const { uri, source } = await ensureLink(relativePath)
@@ -159,7 +182,7 @@ export function files(options = {}) {
                 // the journal stays accurate (mutations = actual changes),
                 // and downstream aggregate-layout invalidation isn't fired
                 // spuriously.
-                if (priorChecksums.get(id) === newChecksum) return
+                if (!forced && priorChecksums.get(id) === newChecksum) return
                 await createEntity({
                     id,
                     uri,

package/src/plugins.js

@@ -87,7 +87,21 @@ onLoad(() => {
     }
 
     if (!factoryEntries.length && !registeredRenderers && !registeredPostprocessors) {
-        logger.info('No plugins loaded')
+        // "No plugins loaded" is a legitimate state for a project with no
+        // config at all, and a near-certain mistake for one that HAS a
+        // config — the two printed the same line, so a config that
+        // produced no plugins looked like a deliberate choice. Say which
+        // case this is.
+        if (runtime.options.configChecksum) {
+            logger.warn(
+                'No plugins loaded, but a config was read from %s — ' +
+                'it exported no `plugins` array, or the array was empty. ' +
+                'Nothing will be built.',
+                runtime.options.config,
+            )
+        } else {
+            logger.info('No plugins loaded')
+        }
         return
     }
 

package/src/report.js

@@ -13,7 +13,7 @@ import runtime from './runtime.js'
 
 function store() {
     runtime.state ??= {}
-    runtime.state.report ??= { rendered: [], skipped: [], warnings: [], gated: 0 }
+    runtime.state.report ??= { rendered: [], skipped: [], unchanged: [], warnings: [], gated: 0 }
     return runtime.state.report
 }
 
@@ -33,6 +33,17 @@ export function reportRendered(entity, reason) {
     store().rendered.push({ id: entity?.id, destination: entity?.destination ?? null, reason })
 }
 
+// A render that RAN and produced bytes identical to what was already on
+// disk. Distinct from both other outcomes and the interesting one of the
+// three: `rendered` means the output moved, `skipped` means the manifest
+// decided not to look, and this means invalidation was coarser than it
+// needed to be. Nothing downstream should have been disturbed, and the
+// count is the measure of how much conservative invalidation costs.
+export function reportUnchanged(entity) {
+    if (!runtime.options?.json) return
+    store().unchanged.push({ id: entity?.id, destination: entity?.destination ?? null })
+}
+
 export function reportSkipped(entity, reason) {
     if (!runtime.options?.json) return
     store().skipped.push({ id: entity?.id, destination: entity?.destination ?? null, reason })
@@ -54,9 +65,13 @@ export function buildReport() {
     return {
         rendered: report.rendered,
         skipped: report.skipped,
+        unchanged: report.unchanged,
         warnings: report.warnings,
         summary: {
             rendered: report.rendered.length,
+            // Of those renders, how many produced bytes identical to
+            // what was already on disk — see reportUnchanged.
+            unchanged: report.unchanged.length,
             // Renders that were CONSIDERED and skipped by the manifest.
             skipped: report.skipped.length,
             // Entities gated at import because their source was unchanged, so

package/src/utils.js

@@ -1,7 +1,7 @@
 import crypto from 'node:crypto'
 import { createHash } from 'node:crypto'
 import { hashFile } from 'hasha'
-import { stat, readFile, writeFile, mkdir, unlink, open } from 'node:fs/promises'
+import { stat, lstat, readFile, writeFile, mkdir, unlink, open } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import _ from 'lodash'
 import { minimatch } from 'minimatch'
@@ -932,6 +932,68 @@ export function useCollection(runtime, name) {
     }
 }
 
+// Write `bytes` to `file`, unless the file already holds exactly those
+// bytes. Returns true if it wrote, false if the file was already correct.
+//
+// Invalidation is deliberately conservative: an entity that merely READ
+// another entity re-renders when that one changes, because the engine
+// cannot know which field was read. That is the right default, and it
+// means renders regularly produce byte-identical output. Writing anyway
+// moves mtime, and three things downstream key off the file rather than
+// its contents:
+//
+//   - live reload watches the output folder, so editing one photograph
+//     reloaded the browser on pages that had not changed
+//   - rsync, `aws s3 sync` and most CDN tools compare size plus mtime,
+//     so unchanged pages re-upload
+//   - `find out -newer` cannot answer "what did this build change?"
+//
+// Doing it here rather than narrowing the dependency edges fixes every
+// conservative-invalidation case at once, and stays correct as the graph
+// gets more precise instead of becoming redundant.
+//
+// Ordering matters: the size check comes first so the common
+// output-really-changed case never pays for a read, and lstat (not stat)
+// because a destination that is currently a SYMLINK has to be replaced
+// by a real file even when the bytes behind it match — the type of the
+// destination is part of the output, not just its contents.
+export async function writeOutput(file, bytes) {
+    // Size first, and WITHOUT materialising a buffer: Buffer.byteLength
+    // measures a string in place, while Buffer.from copies it (~250µs for
+    // a 1MB page, against ~25µs for the lstat). Since a size mismatch is
+    // the common outcome on a build that changed something, the cheap
+    // path must not pay for the expensive one.
+    const size = Buffer.isBuffer(bytes) ? bytes.length : Buffer.byteLength(bytes)
+    let identical = false
+    try {
+        const info = await lstat(file)
+        if (info.isFile() && info.size === size) {
+            const existing = await readFile(file)
+            identical = Buffer.isBuffer(bytes)
+                ? bytes.equals(existing)
+                : existing.equals(Buffer.from(bytes))
+        }
+    } catch (err) {
+        // Missing or unreadable — fall through and write. Anything else
+        // is a bug in this function, and swallowing it would look
+        // exactly like "the file wasn't there": a missing `lstat` import
+        // made every comparison fail open, so the skip silently never
+        // happened while the tests still passed.
+        if (err.code !== 'ENOENT' && err.code !== 'EACCES') throw err
+    }
+    if (identical) return false
+    await mkdir(path.dirname(file), { recursive: true })
+    // Unlink first so an existing hard link or symlink at this path is
+    // broken rather than written through.
+    try {
+        await unlink(file)
+    } catch { /* not there, or not removable — writeFile will say so */ }
+    // Pass the original value through — writeFile encodes a string
+    // directly, so converting first would add a copy for nothing.
+    await writeFile(file, bytes)
+    return true
+}
+
 // ── operating-system and file-manager litter ────────────────────────────
 //
 // Exposing a source folder over a network filesystem (mikser-io-webdav) or