mikser-io-layouts 11.3.0 → 11.5.0

package/.github/workflows/publish.yml

@@ -23,6 +23,15 @@ on:
 jobs:
   publish:
     runs-on: ubuntu-latest
+    # A hung test must not cost six hours.
+    #
+    # Without this the job runs to GitHub's own limit, reporting nothing:
+    # a flaky teardown in one suite sat on `npm test` for seventeen
+    # minutes before anyone looked, and would have sat there all day.
+    # The longest suite in the family is a couple of minutes including
+    # install, so fifteen is generous and still fails while someone is
+    # still watching.
+    timeout-minutes: 15
     permissions:
       contents: read
       # The whole mechanism. Without it npm has nothing to verify.

package/README.md

@@ -126,6 +126,33 @@ destination: '/cards/{{entity.name}}.html'
 ---
 ```
 
+### `match:` — a layout claiming its own entities
+
+A layout can declare the pattern that selects it, instead of the config
+naming it from the other side. These two are the same rule:
+
+```js
+layouts({ match: { '@/blog/*': 'post-card' } })
+```
+
+```yaml
+# layouts/post-card.html.hbs
+---
+match: '@/blog/*'          # or a list: ['@/blog/*', '@/news/*']
+---
+```
+
+They are **peers**, not alternatives — an entity matched by a config pattern
+and by a layout's own pattern gets both layouts, exactly as two config
+patterns would. A document's own `meta.layout` still wins over both, and
+auto-layout still only runs when nothing matched at all.
+
+Patterns follow the same rule everywhere: `matchEntity` globs `entity.name`
+only for a pattern starting `@/`; anything else globs `entity.id`, which
+carries the `/<collection>/` prefix and the extension. A pattern that selects
+nothing is reported once per run on a full cycle, naming the layout that
+declared it.
+
 ```yaml
 # Pull from meta
 ---

package/lib/matching.js

@@ -22,7 +22,22 @@ import path from 'node:path'
 
 import _ from 'lodash'
 import { primaryDestination } from './destination.js'
-import { isFullCycle } from 'mikser-io'
+import { isFullCycle, readFrontMatter } from 'mikser-io'
+
+// A layout as synced, with its front-matter block lifted off — attributes
+// onto meta so `destination:` and `match:` still work, body as the template.
+// Returns the entry untouched when there is no front matter, and when the
+// block cannot be parsed: a renderer showing the author their own malformed
+// YAML is more use than one silently dropping it.
+function withoutFrontMatter(entry) {
+    const parsed = readFrontMatter(entry?.content)
+    if (!parsed || parsed.error) return entry
+    return {
+        ...entry,
+        meta: { ...(entry.meta ?? {}), ...parsed.attributes },
+        content: parsed.body,
+    }
+}
 
 export function createOnProcessed({
     runtime, useLogger, useJournal,
@@ -43,9 +58,25 @@ export function createOnProcessed({
     // author cannot see.
     const matchTally = { evaluated: 0, hit: new Set(), reported: false }
 
+    // Patterns a LAYOUT declared for itself in its own front-matter, seen
+    // during the run. Recorded here rather than derived at report time
+    // because by then the cycle's resolved-layout reads are gone, and a
+    // layout deleted mid-run should not be reported as a dud pattern.
+    const declaredSeen = new Map()
+
+    // A pattern's identity for the tally. The same glob can legitimately
+    // appear in config and in a layout's front-matter; they are different
+    // rules and either can be the dead one.
+    const tallyKey = (pattern, layoutName) =>
+        layoutName ? `layout:${layoutName}:${pattern}` : `config:${pattern}`
+
     function reportUnmatchedPatterns(logger) {
         if (matchTally.reported) return
-        const patterns = Object.keys(options.match || {})
+        const patterns = [
+            ...Object.keys(options.match || {}).map(pattern =>
+                ({ pattern, layout: options.match[pattern], source: null })),
+            ...Array.from(declaredSeen.values()),
+        ]
         if (!patterns.length || !matchTally.evaluated) return
         // Only when the cycle evaluated everything. An incremental run
         // re-evaluates whatever changed, so a healthy pattern matches none of
@@ -56,8 +87,8 @@ export function createOnProcessed({
         if (!isFullCycle(runtime)) return
         matchTally.reported = true
 
-        for (const pattern of patterns) {
-            if (matchTally.hit.has(pattern)) continue
+        for (const { pattern, layout: layoutName, source } of patterns) {
+            if (matchTally.hit.has(tallyKey(pattern, source))) continue
             // Phrased as what was observed: an incremental cycle only
             // re-evaluates changed entities, so a pattern can legitimately
             // match nothing in a run of three. The count lets the reader
@@ -69,12 +100,17 @@ export function createOnProcessed({
             // So 'post' does NOT match a document named 'post'; '@/post' and
             // '/documents/post.md' both do.
             const onName = pattern.startsWith('@/')
+            // Where the pattern is written decides where the fix goes, and
+            // the two places look nothing alike. Without this the reader of
+            // a front-matter typo goes hunting through the config.
+            const declaredIn = source ? ` declared in layouts/${source}` : ''
             logger.warn(
-                { code: 'layout-pattern-no-match', pattern, layout: options.match[pattern],
+                { code: 'layout-pattern-no-match', pattern, layout: layoutName,
+                  declaredIn: source || 'layouts.match',
                   evaluated: matchTally.evaluated, matchedAgainst: onName ? 'name' : 'id' },
-                'Layout pattern %j (→ %j) matched none of the %d entities evaluated. ' +
+                'Layout pattern %j (→ %j)%s matched none of the %d entities evaluated. ' +
                 'It is matched against entity.%s%s.',
-                pattern, options.match[pattern], matchTally.evaluated,
+                pattern, layoutName, declaredIn, matchTally.evaluated,
                 onName ? 'name' : 'id',
                 onName ? '' : " — prefix a pattern with '@/' to match entity.name instead, " +
                              'since an id looks like /<collection>/<name>.<ext>')
@@ -101,7 +137,57 @@ export function createOnProcessed({
         async function resolveLayout(name) {
             const stateEntry = layouts[name]
             if (!stateEntry) return undefined
-            return (await findEntity({ id: stateEntry.id })) || stateEntry
+            const fromCatalog = await findEntity({ id: stateEntry.id })
+            if (fromCatalog) return fromCatalog
+            // The catalog has not caught up — a sync race, or a setup where
+            // the front-matter plugin has not run. The state map holds the
+            // file AS SYNCED, so its content still carries the front-matter
+            // block, and handing that to a renderer has now failed twice in
+            // two different ways: Handlebars emitted the YAML into the page,
+            // and LiquidJS refuses to parse it at all, reporting a syntax
+            // error at the front-matter line and taking the layout down.
+            //
+            // Resolving from the catalog was the fix for the first. This is
+            // the same fix for the path that bypasses it — stripping through
+            // core's reader rather than a regex here, so there is one
+            // implementation of what front matter is.
+            return withoutFrontMatter(stateEntry)
+        }
+
+        // `match:` in a layout's own front-matter — the colocated twin of a
+        // `layouts({ match: … })` rule, and documented alongside
+        // `destination:` since before either worked. `destination` was
+        // implemented; this was not, and a layout carrying it matched
+        // nothing, logged nothing, and looked configured. Reported after it
+        // cost a consumer the longest detour of their session.
+        //
+        // Read through resolveLayout for the same reason destination is
+        // (lib/assembly.js): the state map holds the file as synced, before
+        // front-matter has been lifted into meta. The raw entry has no
+        // `meta.match` to find.
+        //
+        // Built once per cycle rather than per entity: one findEntity per
+        // layout over a 5-20 entry map is nothing, the same work repeated
+        // for every document in the catalog is not.
+        let declaredPatterns = null
+        async function layoutDeclaredPatterns() {
+            if (declaredPatterns) return declaredPatterns
+            declaredPatterns = []
+            for (const name of Object.keys(layouts)) {
+                const declared = (await resolveLayout(name))?.meta?.match
+                if (!declared) continue
+                for (const pattern of Array.isArray(declared) ? declared : [declared]) {
+                    if (typeof pattern !== 'string' || !pattern) {
+                        logger.warn(
+                            'Layout %j declares a non-string `match` (%j) — expected a glob, or an array of them.',
+                            name, pattern)
+                        continue
+                    }
+                    declaredPatterns.push({ pattern, layout: name, source: name })
+                    declaredSeen.set(tallyKey(pattern, name), { pattern, layout: name, source: name })
+                }
+            }
+            return declaredPatterns
         }
 
         // Resolve the set of layouts that should render `entity` this
@@ -153,7 +239,7 @@ export function createOnProcessed({
             matchTally.evaluated++
             for (const pattern in options.match || []) {
                 if (matchEntity(entity, pattern)) {
-                    matchTally.hit.add(pattern)
+                    matchTally.hit.add(tallyKey(pattern, null))
                     const name = options.match[pattern]
                     const layout = await resolveLayout(name)
                     if (layout && !matched.find(l => l.name === layout.name)) {
@@ -168,6 +254,22 @@ export function createOnProcessed({
                 }
             }
 
+            // Then the patterns each layout declared for itself. A peer of
+            // the config rules, not a fallback: both are "a pattern claimed
+            // this entity", and an entity legitimately matched by one of
+            // each gets both layouts, exactly as two config patterns would.
+            for (const { pattern, layout: name, source } of await layoutDeclaredPatterns()) {
+                if (!matchEntity(entity, pattern)) continue
+                matchTally.hit.add(tallyKey(pattern, source))
+                const layout = await resolveLayout(name)
+                if (layout && !matched.find(l => l.name === layout.name)) {
+                    // Distinguishable from a config pattern in `--explain`:
+                    // the same glob can be written in either place, and the
+                    // fix goes to a different file depending on which.
+                    matched.push({ ...layout, matchedBy: `${pattern} (layouts/${name})` })
+                }
+            }
+
             // Auto-layout: only as a fallback when no pattern matched.
             // The peel ladder is intentionally first-wins — it's a
             // most-specific-name search, not a multi-match.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-layouts",
-  "version": "11.3.0",
+  "version": "11.5.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": "^11.1.0",
+    "mikser-io": "^11.10.0",
     "zod": "^4.0.0"
   },
   "dependencies": {
@@ -27,7 +27,7 @@
     "lodash": "^4.17.0"
   },
   "devDependencies": {
-    "mikser-io": "^11.1.0",
+    "mikser-io": "^11.10.0",
     "mikser-io-render-liquid": "^11.0.1",
     "zod": "^4.0.0"
   }

package/test/unit.test.js

@@ -210,6 +210,268 @@ describe('layouts plugin', () => {
         })
     })
 
+    it('never hands a renderer a layout with its front matter still attached', async () => {
+        // resolveLayout falls back to the state map when the catalog has not
+        // caught up, and the state map holds the file AS SYNCED. That raw
+        // text has failed twice, in two engines: Handlebars emitted the YAML
+        // into the page, and LiquidJS refuses to parse it at all — reported
+        // as "invalid range syntax" at line 2, the front-matter line, which
+        // takes the whole layout down.
+        //
+        // The catalog is deliberately EMPTY here, which is the fallback.
+        await withTempWorking(async (workingFolder) => {
+            const h = createHarness({
+                entities: [],
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
+            })
+            layouts({ autoLayouts: false })(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'post.hbs' } })
+            // The file as synced: front matter still on it.
+            h.runtime.state.layouts.layouts['post'].content =
+                '---\ndestination: "/{{ entity.name }}.html"\n---\n<h1>body</h1>\n'
+
+            const doc = { id: '/documents/hello.md', collection: 'documents', name: 'hello', format: 'md', meta: { layout: 'post' } }
+            h.journal.push({ id: 1, entity: doc, operation: 'create', context: {}, options: {}, output: null })
+            await h.runHook('processed', { aborted: false })
+
+            assert.ok(!doc.layout.content.trimStart().startsWith('---'),
+                `front matter reached the renderer: ${JSON.stringify(doc.layout.content.slice(0, 40))}`)
+            assert.match(doc.layout.content, /<h1>body<\/h1>/, 'the template survived')
+        })
+    })
+
+    it('lifts the fallback layout\'s front matter onto meta, so destination still works', async () => {
+        // Stripping without lifting would trade a parse error for a silently
+        // ignored `destination:` — the state-map entry carries no meta at all
+        // otherwise, which is why a front-matter `match:` saw nothing there.
+        await withTempWorking(async (workingFolder) => {
+            const h = createHarness({
+                entities: [],
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
+            })
+            layouts({ autoLayouts: false })(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'post.hbs' } })
+            h.runtime.state.layouts.layouts['post'].content =
+                '---\ndestination: "/cards/{{entity.name}}.html"\n---\n<h1>body</h1>\n'
+
+            const doc = { id: '/documents/hello.md', collection: 'documents', name: 'hello', format: 'md', meta: { layout: 'post' } }
+            h.journal.push({ id: 1, entity: doc, operation: 'create', context: {}, options: {}, output: null })
+            await h.runHook('processed', { aborted: false })
+
+            assert.equal(doc.layout.meta.destination, '/cards/{{entity.name}}.html')
+        })
+    })
+
+    it('leaves a malformed front-matter block alone rather than dropping it', async () => {
+        // Unparseable YAML shown to the author beats silently discarded.
+        await withTempWorking(async (workingFolder) => {
+            const h = createHarness({
+                entities: [],
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
+            })
+            layouts({ autoLayouts: false })(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'post.hbs' } })
+            const broken = "---\ndestination: '/{{ before (after entity.name '/') '_' }}'\n---\n<h1>body</h1>\n"
+            h.runtime.state.layouts.layouts['post'].content = broken
+
+            const doc = { id: '/documents/hello.md', collection: 'documents', name: 'hello', format: 'md', meta: { layout: 'post' } }
+            h.journal.push({ id: 1, entity: doc, operation: 'create', context: {}, options: {}, output: null })
+            await h.runHook('processed', { aborted: false })
+
+            assert.equal(doc.layout.content, broken, 'left as written')
+        })
+    })
+
+    it('a layout matches through `match:` in its own front-matter', async () => {
+        // Documented in the README beside `destination:` and never
+        // implemented. A layout carrying it produced no render task, logged
+        // nothing, and looked correctly configured — reported as the longest
+        // single detour of a consumer's session.
+        //
+        // The catalog entity is what carries parsed front-matter; the state
+        // map holds the file as synced. Seeding both is what a real build
+        // does, and is why reading the state map alone found no `match`.
+        await withTempWorking(async (workingFolder) => {
+            const catalog = []
+            const h = createHarness({
+                entities: catalog,
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
+            })
+            layouts({ autoLayouts: false })(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'post-card.hbs' } })
+            catalog.push({
+                id: h.runtime.state.layouts.layouts['post-card'].id,
+                collection: 'layouts', name: 'post-card',
+                meta: { match: '@/blog/*' },
+            })
+
+            const doc = { id: '/documents/blog/welcome.md', collection: 'documents', name: 'blog/welcome', format: 'md', meta: {} }
+            h.journal.push({ id: 1, entity: doc, operation: 'create', context: {}, options: {}, output: null })
+            await h.runHook('processed', { aborted: false })
+
+            assert.deepEqual(doc.layouts.map(l => l.name), ['post-card'])
+            assert.match(doc.layouts[0].matchedBy, /layouts\/post-card/,
+                'explain must say the rule came from the layout, not the config')
+        })
+    })
+
+    it('a layout can declare several patterns', async () => {
+        await withTempWorking(async (workingFolder) => {
+            const catalog = []
+            const h = createHarness({
+                entities: catalog,
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
+            })
+            layouts({ autoLayouts: false })(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'card.hbs' } })
+            catalog.push({
+                id: h.runtime.state.layouts.layouts['card'].id,
+                collection: 'layouts', name: 'card',
+                meta: { match: ['@/blog/*', '@/news/*'] },
+            })
+
+            const news = { id: '/documents/news/launch.md', collection: 'documents', name: 'news/launch', format: 'md', meta: {} }
+            h.journal.push({ id: 1, entity: news, operation: 'create', context: {}, options: {}, output: null })
+            await h.runHook('processed', { aborted: false })
+
+            assert.deepEqual(news.layouts.map(l => l.name), ['card'])
+        })
+    })
+
+    it('a front-matter pattern that selected nothing warns, naming the layout', async () => {
+        // The silence is the whole finding: without this the author of a
+        // typo'd front-matter pattern gets a green build and empty pages.
+        // Naming the layout matters because the same glob can be written in
+        // the config, and the fix lives in a different file.
+        await withTempWorking(async (workingFolder) => {
+            const catalog = []
+            const h = createHarness({
+                entities: catalog,
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
+            })
+            layouts({ autoLayouts: false })(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'post-card.hbs' } })
+            catalog.push({
+                id: h.runtime.state.layouts.layouts['post-card'].id,
+                collection: 'layouts', name: 'post-card',
+                meta: { match: '@/blogg/*' },   // typo
+            })
+
+            const doc = { id: '/documents/blog/welcome.md', collection: 'documents', name: 'blog/welcome', format: 'md', meta: {} }
+            h.journal.push({ id: 1, entity: doc, operation: 'create', context: {}, options: {}, output: null })
+            await h.runHook('processed', { aborted: false })
+
+            const warnings = h.logs.filter(l =>
+                l.level === 'warn' && l.args.join(' ').includes('Layout pattern'))
+            assert.equal(warnings.length, 1, `expected one warning, got ${warnings.length}`)
+            const [fields, ...message] = warnings[0].args
+            assert.equal(fields.code, 'layout-pattern-no-match')
+            assert.equal(fields.pattern, '@/blogg/*')
+            assert.equal(fields.declaredIn, 'post-card', 'says which layout wrote the pattern')
+            assert.match(format(...message), /layouts\/post-card/,
+                'the sentence points at the file to edit')
+        })
+    })
+
+    it('reports the one dud front-matter pattern among working ones', async () => {
+        // The shape this actually takes in a project: several layouts each
+        // claiming their own section, one of them typo'd. A working pattern
+        // elsewhere must not absolve the dead one — that would make the
+        // warning useless in exactly the configuration it is for.
+        await withTempWorking(async (workingFolder) => {
+            const catalog = []
+            const h = createHarness({
+                entities: catalog,
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
+            })
+            layouts({ autoLayouts: false })(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'post-card.hbs' } })
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'news-card.hbs' } })
+            catalog.push({
+                id: h.runtime.state.layouts.layouts['post-card'].id,
+                collection: 'layouts', name: 'post-card',
+                meta: { match: '@/blog/*' },            // works
+            })
+            catalog.push({
+                id: h.runtime.state.layouts.layouts['news-card'].id,
+                collection: 'layouts', name: 'news-card',
+                meta: { match: '@/newss/*' },           // typo
+            })
+
+            const doc = { id: '/documents/blog/welcome.md', collection: 'documents', name: 'blog/welcome', format: 'md', meta: {} }
+            h.journal.push({ id: 1, entity: doc, operation: 'create', context: {}, options: {}, output: null })
+            await h.runHook('processed', { aborted: false })
+
+            assert.deepEqual(doc.layouts.map(l => l.name), ['post-card'], 'the good pattern still matched')
+            const warnings = h.logs.filter(l =>
+                l.level === 'warn' && l.args.join(' ').includes('Layout pattern'))
+            assert.equal(warnings.length, 1, `expected exactly one warning, got ${warnings.length}`)
+            assert.equal(warnings[0].args[0].declaredIn, 'news-card', 'names the dud, not the working one')
+        })
+    })
+
+    it('a front-matter pattern is a peer of a config pattern, not a fallback', async () => {
+        // Two rules claiming one entity give two layouts, exactly as two
+        // config patterns would. Making front-matter a fallback would mean
+        // adding a config rule silently switched a layout off.
+        await withTempWorking(async (workingFolder) => {
+            const catalog = []
+            const h = createHarness({
+                entities: catalog,
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
+            })
+            layouts({ autoLayouts: false, match: { '@/blog/*': 'post' } })(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'post.hbs' } })
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'post-card.hbs' } })
+            catalog.push({
+                id: h.runtime.state.layouts.layouts['post-card'].id,
+                collection: 'layouts', name: 'post-card',
+                meta: { match: '@/blog/*' },
+            })
+
+            const doc = { id: '/documents/blog/welcome.md', collection: 'documents', name: 'blog/welcome', format: 'md', meta: {} }
+            h.journal.push({ id: 1, entity: doc, operation: 'create', context: {}, options: {}, output: null })
+            await h.runHook('processed', { aborted: false })
+
+            assert.deepEqual(doc.layouts.map(l => l.name).sort(), ['post', 'post-card'])
+        })
+    })
+
+    it('an author-declared meta.layout still wins over a front-matter pattern', async () => {
+        // Precedence is unchanged: what the document asks for beats what a
+        // layout claims, the same way it beats a config pattern.
+        await withTempWorking(async (workingFolder) => {
+            const catalog = []
+            const h = createHarness({
+                entities: catalog,
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
+            })
+            layouts({ autoLayouts: false })(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'post.hbs' } })
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'post-card.hbs' } })
+            catalog.push({
+                id: h.runtime.state.layouts.layouts['post-card'].id,
+                collection: 'layouts', name: 'post-card',
+                meta: { match: '@/blog/*' },
+            })
+
+            const doc = { id: '/documents/blog/welcome.md', collection: 'documents', name: 'blog/welcome', format: 'md', meta: { layout: 'post' } }
+            h.journal.push({ id: 1, entity: doc, operation: 'create', context: {}, options: {}, output: null })
+            await h.runHook('processed', { aborted: false })
+
+            assert.deepEqual(doc.layouts.map(l => l.name), ['post'])
+        })
+    })
+
     it('stays silent about an unmatched pattern on an incremental cycle', async () => {
         // The inverse of the test above, and the reason the gate exists. An
         // incremental run re-evaluates only what changed, so a pattern that