mikser-io-layouts 2.1.0 → 2.3.0

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.3.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.14.0"
   },
   "dependencies": {
     "globby": "^14.0.0",