mikser-io-layouts 2.1.0 → 2.4.0

package/index.js

@@ -21,6 +21,7 @@ import {
     checksumsByCollection,
     checksum as fileChecksum, checksumOf,
     useDatabase,
+    writeOutput, reportUnchanged,
 } from 'mikser-io'
 
 import { createInspect } from './lib/inspect.js'
@@ -408,12 +409,20 @@ export function layouts(userOptions = {}) {
 
                 if (!skipWrite) {
                     const destinationFile = path.join(writeBase, entity.destination)
-                    await mkdir(path.dirname(destinationFile), { recursive: true })
-                    try {
-                        await unlink(destinationFile)
-                    } catch { }
-                    await writeFile(destinationFile, output.result)
-                    logger.debug('Layout render finished: %s', entity.destination.replace(runtime.options.workingFolder, ''))
+                    // writeOutput skips the write when the bytes already on
+                    // disk are identical. Invalidation is deliberately
+                    // conservative — an entity that merely READ another
+                    // re-renders, because the engine cannot know which field
+                    // was read — so byte-identical output is routine, and
+                    // rewriting it moved mtime for live-reload, rsync and
+                    // `find -newer` alike. mkdir/unlink moved inside it.
+                    const wrote = await writeOutput(destinationFile, output.result)
+                    if (wrote) {
+                        logger.debug('Layout render finished: %s', entity.destination.replace(runtime.options.workingFolder, ''))
+                    } else {
+                        reportUnchanged(entity)
+                        logger.debug('Layout render finished, output unchanged: %s', entity.destination.replace(runtime.options.workingFolder, ''))
+                    }
                 } else {
                     logger.debug('Layout render finished (save:false, bytes only): %s', entity.id)
                 }

package/lib/matching.js

@@ -22,6 +22,7 @@ import path from 'node:path'
 
 import _ from 'lodash'
 import { primaryDestination } from './destination.js'
+import { reportWarning } from 'mikser-io'
 
 export function createOnProcessed({
     runtime, useLogger, useJournal,
@@ -61,6 +62,10 @@ export function createOnProcessed({
             // So 'post' does NOT match a document named 'post'; '@/post' and
             // '/documents/post.md' both do.
             const onName = pattern.startsWith('@/')
+            reportWarning('layout-pattern-no-match', {
+                pattern, layout: options.match[pattern], evaluated: matchTally.evaluated,
+                matchedAgainst: onName ? 'name' : 'id',
+            })
             logger.warn(
                 'Layout pattern %j (→ %j) matched none of the %d entities evaluated. ' +
                 'It is matched against entity.%s%s. On an incremental run unchanged ' +
@@ -125,7 +130,13 @@ export function createOnProcessed({
                 for (const name of declared) {
                     const layout = await resolveLayout(name)
                     if (layout) {
-                        if (!resolved.find(l => l.name === layout.name)) resolved.push(layout)
+                        // meta.layout / meta.layouts in the document's own
+                        // frontmatter. Labelled so --explain says the choice
+                        // came from the content, not from config — which is
+                        // where you would otherwise go looking.
+                        if (!resolved.find(l => l.name === layout.name)) {
+                            resolved.push({ ...layout, matchedBy: 'meta.layout' })
+                        }
                     } else {
                         logger.warn('Layout not found for %s: %s', entity.collection, entity.id, name)
                     }
@@ -142,7 +153,13 @@ export function createOnProcessed({
                     const name = options.match[pattern]
                     const layout = await resolveLayout(name)
                     if (layout && !matched.find(l => l.name === layout.name)) {
-                        matched.push(layout)
+                        // Record WHICH pattern claimed it. With several
+                        // patterns able to match one entity, "why did this
+                        // page get that layout" is otherwise only answerable
+                        // by re-running the matcher by hand — and it is the
+                        // question asked whenever the answer is surprising.
+                        // Surfaced by `mikser --explain`.
+                        matched.push({ ...layout, matchedBy: pattern })
                     }
                 }
             }
@@ -163,7 +180,11 @@ export function createOnProcessed({
                 const autoLayout = candidates.find(name => layouts[name])
                 if (autoLayout) {
                     const layout = await resolveLayout(autoLayout)
-                    if (layout) matched.push(layout)
+                    // Labelled so `mikser --explain` can distinguish "a
+                    // pattern you wrote chose this" from "the name happened
+                    // to match a layout file" — a distinction that decides
+                    // whether the fix is in the config or in a filename.
+                    if (layout) matched.push({ ...layout, matchedBy: 'auto-layout' })
                     logger.debug('Auto layout matched %s -> %s for %s', entity.name, autoLayout, entity.id)
                 } else {
                     logger.trace('Auto layout no match for %s tried: %s', entity.id, candidates.join(', '))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-layouts",
-  "version": "2.1.0",
+  "version": "2.4.0",
   "description": "SSG-flavor task-production policy for mikser-io. Multi-match layout assignment, per-layout destinations, postprocess chain attachment, layout inspection.",
   "main": "index.js",
   "type": "module",
@@ -18,7 +18,7 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-layouts#readme",
   "peerDependencies": {
-    "mikser-io": "^9.11.0"
+    "mikser-io": "^9.18.0"
   },
   "dependencies": {
     "globby": "^14.0.0",