mikser-io-layouts 2.6.0 → 2.7.0

package/lib/assembly.js

@@ -23,6 +23,7 @@ import _ from 'lodash'
 import {
     inputHashOf,
     createTrack,
+    recordReads,
     queryContext,
     useDatabase,
 } from 'mikser-io'
@@ -248,7 +249,13 @@ export function createOnBeforeRender({
                 // invalidations when a newly-added entity should make the
                 // listing change. partial slot disabled — sidecars don't
                 // load partials themselves.
-                const sidecarTrack = createTrack({ partial: false })
+                // `meta: true` records which of the entity's own meta keys
+                // the sidecar reads. This is the half of a layout's contract
+                // that static parsing structurally cannot reach: a sidecar is
+                // plain JavaScript, so `row.meta?.hero?.tags` has no syntax
+                // for any template parser to find. Observing the read is the
+                // only way to know the key is required.
+                const sidecarTrack = createTrack({ partial: false, meta: true })
                 if (existsSync(sidecarPath)) {
                     try {
                         // Stamp = the shared sidecar digest, so the URL
@@ -270,9 +277,21 @@ export function createOnBeforeRender({
                     }
                     if (load) {
                         try {
+                            // The sidecar sees a read-recording view of the
+                            // entity. Only `meta` is wrapped — id, name and uri
+                            // are plumbing, and recording them as content keys
+                            // would bury the ones that matter.
+                            //
+                            // Prefixed `meta.` rather than `data.meta.`: these
+                            // are the DOCUMENT's own keys, read before any
+                            // transform the sidecar applies, while the template
+                            // reads whatever the sidecar hands back.
+                            const observed = entity?.meta
+                                ? { ...entity, meta: recordReads(entity.meta, 'meta', sidecarTrack.metaRead) }
+                                : entity
                             data = await queryContext.run(
                                 { entityId: entity.id, track: sidecarTrack },
-                                () => load({ entity, findEntity, findEntities, runtime, signal }),
+                                () => load({ entity: observed, findEntity, findEntities, runtime, signal }),
                             )
                         } catch (err) {
                             logger.error('Layout sidecar %s load() threw: %s', sidecarPath.replace(runtime.options.workingFolder + '/', ''), err.message)
@@ -361,7 +380,8 @@ export function createOnBeforeRender({
                                 postprocessor: entity.layout.postprocessor,
                                 postprocessors: entity.layout.postprocessors ?? (entity.layout.postprocessor ? [entity.layout.postprocessor] : []),
                                 tasks: entity.meta?.task || TASKS.INLINE,
-                            }, { data, plugins, sidecarQueries: sidecarTrack.queries })
+                            }, { data, plugins, sidecarQueries: sidecarTrack.queries,
+                                 sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])] })
                         }
                     }
                 } else {
@@ -388,7 +408,8 @@ export function createOnBeforeRender({
                         // when matching entities are added/modified/
                         // deleted. The paginated branch above already
                         // does this.
-                        { data, plugins, sidecarQueries: sidecarTrack.queries })
+                        { data, plugins, sidecarQueries: sidecarTrack.queries,
+                          sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])] })
                     }
                 }
             } // end per-layout for-loop

package/lib/inspect.js

@@ -65,6 +65,10 @@ export function createInspect({ runtime, findEntity, findEntities, useDatabase,
             sampleEntities, useDatabase, layoutName: layout.name,
         })
 
+        const contract = await buildContract({
+            layout, templateSource, runtime, findEntities, collection,
+        })
+
         return {
             layout: {
                 id:            layout.id,
@@ -78,6 +82,7 @@ export function createInspect({ runtime, findEntity, findEntities, useDatabase,
             references: {
                 runtime: runtimeRefs,
                 static:  staticRefs,
+                contract,
             },
             samples: sampleEntities,
         }
@@ -98,7 +103,7 @@ async function collectRuntimeRefs({ sampleEntities, useDatabase, layoutName }) {
     }
 
     const stmt = db.handle.prepare(`
-        SELECT destination, refClosure, renderedAt, inputHash, outputHash
+        SELECT destination, refClosure, metaReads, renderedAt, inputHash, outputHash
         FROM mikser_snapshots
         WHERE id = ?
         ORDER BY renderedAt DESC
@@ -106,6 +111,11 @@ async function collectRuntimeRefs({ sampleEntities, useDatabase, layoutName }) {
     `)
 
     const perSample = []
+    // Union across samples. One document exercises one set of branches, so the
+    // keys a layout needs are only visible across several of them — which is
+    // also why this can never be a complete answer on its own, and why the
+    // static closure sits beside it.
+    const observed = new Set()
     for (const sample of sampleEntities) {
         const row = stmt.get(sample.id)
         if (!row) {
@@ -116,6 +126,11 @@ async function collectRuntimeRefs({ sampleEntities, useDatabase, layoutName }) {
         try {
             refClosure = row.refClosure ? JSON.parse(row.refClosure) : []
         } catch { /* malformed JSON: surface empty rather than throw */ }
+        let metaReads = []
+        try {
+            metaReads = row.metaReads ? JSON.parse(row.metaReads) : []
+        } catch { /* same: an unreadable column is not worth throwing over */ }
+        for (const path of metaReads) observed.add(path)
         perSample.push({
             entityId:   sample.id,
             destination: row.destination,
@@ -123,6 +138,7 @@ async function collectRuntimeRefs({ sampleEntities, useDatabase, layoutName }) {
             inputHash:  row.inputHash,
             outputHash: row.outputHash,
             refClosure,
+            metaReads,
         })
     }
 
@@ -130,7 +146,18 @@ async function collectRuntimeRefs({ sampleEntities, useDatabase, layoutName }) {
     if (!everRendered) {
         return { available: false, reason: `No sample entity using "${layoutName}" has rendered yet` }
     }
-    return { available: true, samples: perSample }
+    return {
+        available: true,
+        samples: perSample,
+        // Meta keys these renders ACTUALLY read, union of the samples.
+        //
+        // The counterpart to references.contract, and deliberately not merged
+        // with it: the contract says what the templates COULD read, this says
+        // what was read. Only this one sees a sidecar, because a sidecar is
+        // plain JavaScript; only the contract sees a branch no sample took.
+        // Reported apart so a caller can tell which of the two it is trusting.
+        metaReads: [...observed].sort(),
+    }
 }
 
 // Wrap the renderer's parser so a thrown error in one engine doesn't
@@ -148,3 +175,165 @@ function safeParseReferences(renderer, source, templateName) {
         return { available: false, reason: `Renderer "${templateName}" parseReferences() threw: ${err.message}` }
     }
 }
+
+// The contract of a layout AND everything it pulls in.
+//
+// `references.static` answers "what does this FILE mention", which is one file
+// deep and in that file's own vocabulary. Neither is what an author needs. A
+// page layout is mostly `{% include %}`, so its own file mentions almost
+// nothing; and a section that opens `{% assign hero = data.meta.hero %}` then
+// talks about `hero.tags`, which names nothing the author can write.
+//
+// So this walks the whole tree and rewrites every path back into the caller's
+// terms. `hero.tags` inside sections/hero.liquid, reached through
+// `{% render 'ui/tags', tags: hero.tags %}`, comes back out as
+// `data.meta.hero.tags` — which IS the key in the document's front matter.
+//
+// Engine-agnostic by construction: it never looks at template syntax, only at
+// what each renderer's own parseReferences() reports. An engine that exposes no
+// parser contributes nothing and SAYS SO, in `incomplete`. A partial-looking
+// contract reported as complete would be worse than no contract at all, which
+// is the whole reason the caps below are reported rather than silently applied.
+const MAX_DEPTH = 12
+const MAX_TEMPLATES = 200
+
+async function buildContract({ layout, templateSource, runtime, findEntities, collection }) {
+    const consumes  = new Set()
+    const templates = []
+    const incomplete = []
+    const visited   = new Set()
+
+    // A path rewritten through the substitutions in scope. Only the FIRST
+    // segment can be an alias — `hero.tags` where `hero` is bound to
+    // `data.meta.hero` is `data.meta.hero.tags`; the tail is property access on
+    // whatever that resolved to and never needs rewriting.
+    const resolve = (path, subs) => {
+        if (!path) return path
+        const [head, ...rest] = String(path).split('.')
+        // The head may carry the element marker a parser adds for a loop
+        // variable: `{% for t in tags %}{{ t.label }}` reports `tags[].label`.
+        // The binding is keyed by the plain name, so the marker comes off for
+        // the lookup and goes back on after it — otherwise every key read off
+        // a loop item stops dead at the partial boundary, which is precisely
+        // the hop this exists to cross.
+        const isElement = head.endsWith('[]')
+        const base = subs[isElement ? head.slice(0, -2) : head]
+        if (!base) return path
+        return [isElement ? `${base}[]` : base, ...rest].join('.')
+    }
+
+    const layoutNamed = async (name) => {
+        const rows = (await findEntities({ name })) ?? []
+        return rows.find(e => e.collection === collection) ?? null
+    }
+
+    async function walk(name, template, source, bindings, depth) {
+        // Keyed by name AND bindings: one partial rendered with two different
+        // arguments has two different contracts, and collapsing them would
+        // lose one. Cyclic includes and runaway fan-out are bounded instead.
+        const key = `${name}|${JSON.stringify(bindings)}`
+        if (visited.has(key)) return
+        if (depth > MAX_DEPTH) {
+            incomplete.push({ template: name, reason: `include depth exceeded ${MAX_DEPTH}` })
+            return
+        }
+        if (visited.size >= MAX_TEMPLATES) {
+            incomplete.push({ template: name, reason: `stopped after ${MAX_TEMPLATES} templates` })
+            return
+        }
+        visited.add(key)
+
+        const renderer = runtime.renderers?.get(template)
+        if (typeof renderer?.parseReferences !== 'function') {
+            incomplete.push({
+                template: name,
+                reason: renderer
+                    ? `renderer "${template}" exposes no parseReferences(), so nothing under it was read`
+                    : `no renderer registered for template "${template}"`,
+            })
+            return
+        }
+        const parsed = safeParseReferences(renderer, source, template)
+        if (!parsed.available || parsed.parseError) {
+            incomplete.push({ template: name, reason: parsed.reason ?? `parse error: ${parsed.parseError}` })
+            return
+        }
+
+        // Substitutions in scope: what this template was called with, then its
+        // own assigns layered on top — an assign can refer to an argument, so
+        // it is resolved against what is known so far.
+        const subs = { ...bindings }
+        for (const a of parsed.assigns ?? []) {
+            if (a?.key && a.from) subs[a.key] = resolve(a.from, subs)
+        }
+
+        const resolved = []
+        for (const v of parsed.variables ?? []) {
+            const r = resolve(v, subs)
+            consumes.add(r)
+            resolved.push(r)
+        }
+        templates.push({ template: name, bindings, consumes: resolved.sort() })
+
+        for (const p of parsed.partials ?? []) {
+            // Engines that have not been taught to report arguments still
+            // report NAMES, so the tree is still walked — just without the
+            // bindings that make aliases resolvable.
+            const isRich = p && typeof p === 'object'
+            const partialName = isRich ? p.name : p
+            if (!partialName) continue
+
+            const childBindings = {}
+            if (isRich) {
+                for (const [arg, path] of Object.entries(p.args ?? {})) {
+                    childBindings[arg] = resolve(path, subs)
+                }
+                for (const alias of p.aliases ?? []) {
+                    if (alias?.to && alias.from) childBindings[alias.to] = resolve(alias.from, subs)
+                }
+            } else {
+                incomplete.push({
+                    template: partialName,
+                    reason: `renderer "${template}" reports partial names but not their arguments, `
+                        + 'so anything reached through an argument is unresolved',
+                })
+            }
+
+            const entity = await layoutNamed(partialName)
+            if (!entity) {
+                incomplete.push({ template: partialName, reason: 'no layout entity has this name' })
+                continue
+            }
+            let childSource
+            try {
+                childSource = await readFile(entity.uri, 'utf8')
+            } catch (err) {
+                incomplete.push({ template: partialName, reason: `unreadable (${entity.uri}): ${err.message}` })
+                continue
+            }
+            await walk(partialName, entity.template, childSource, childBindings, depth + 1)
+        }
+    }
+
+    await walk(layout.name, layout.template, templateSource, {}, 0)
+
+    // The subset an author actually writes. Everything else in `consumes` is
+    // render-time furniture — helpers, loop variables, plugin surfaces — and
+    // is kept, but it is not what a document's front matter is checked against.
+    const meta = [...consumes]
+        .filter(p => p.startsWith('data.meta.'))
+        .map(p => p.slice('data.meta.'.length))
+        .filter(Boolean)
+
+    return {
+        available: true,
+        // False whenever ANY branch could not be read. A contract that looks
+        // complete but silently omits a partial is the failure this exists to
+        // prevent, so the flag leads and the reasons are named.
+        complete: incomplete.length === 0,
+        meta: [...new Set(meta)].sort(),
+        consumes: [...consumes].sort(),
+        templates,
+        incomplete,
+    }
+}

package/lib/matching.js

@@ -22,7 +22,7 @@ import path from 'node:path'
 
 import _ from 'lodash'
 import { primaryDestination } from './destination.js'
-import { reportWarning, isFullCycle } from 'mikser-io'
+import { isFullCycle } from 'mikser-io'
 
 export function createOnProcessed({
     runtime, useLogger, useJournal,
@@ -69,11 +69,9 @@ 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(
+                { code: 'layout-pattern-no-match', pattern, layout: options.match[pattern],
+                  evaluated: matchTally.evaluated, matchedAgainst: onName ? 'name' : 'id' },
                 'Layout pattern %j (→ %j) matched none of the %d entities evaluated. ' +
                 'It is matched against entity.%s%s.',
                 pattern, options.match[pattern], matchTally.evaluated,

package/lib/mcp.js

@@ -19,7 +19,19 @@ export function registerMcpTools({ runtime, useLogger }) {
 
     mcp.simpleTool(
         'mikser_layouts_inspect',
-        'Inspect a layout: template source, references (runtime: precise refClosure from recent renders via the manifest; static: variables / partials / iterations / helpers parsed from source by the renderer plugin), and sample entities currently targeting it. Use this to answer "what does this layout need from an entity" before drafting a preview render — saves a guess-and-render-empty cycle.',
+        'Inspect a layout and everything it pulls in. Answers "what does this layout need from a document" '
+        + 'before you write one — which saves a guess-and-render-empty cycle, and is the only way to catch a '
+        + 'mistyped key before it ships a page with a section silently missing.\n\n'
+        + 'START WITH references.contract.meta. It is the list of document meta keys the WHOLE layout tree '
+        + 'consumes, resolved through includes and renamings into the vocabulary a document actually writes — '
+        + 'so `data.meta.hero.tags` in a partial three files down comes back as `hero.tags`. Compare it against '
+        + 'the meta you are about to write: a key in the contract with no value is a gap, and a key you wrote '
+        + 'that appears nowhere in it is usually a typo.\n\n'
+        + 'Check references.contract.complete before trusting a comparison. When false, some branch could not be '
+        + 'read and references.contract.incomplete names each one with a reason.\n\n'
+        + 'Also returns the template source, sample entities targeting the layout, and both reference views: '
+        + 'runtime (what recent renders actually touched) and static (what the source mentions, including '
+        + 'branches no render has taken).',
         {
             id: z.string().describe('Layout id, e.g. "/layouts/reports/royalty.html-pdf.liquid". Use mikser_query_entities with { collection: "layouts" } to discover ids.'),
             samples: z.number().int().min(0).max(10).optional().describe('How many existing entities currently using this layout to include as data-shape examples. Default 3. Only entities with explicit meta.layout match; auto-matched layouts are not surfaced.'),
@@ -33,8 +45,12 @@ export function registerMcpTools({ runtime, useLogger }) {
                         text: JSON.stringify({
                             ...result,
                             notes: [
+                                'references.contract is the one to read first: the whole layout tree walked, with partial arguments and renamings resolved, so `meta` lists document keys in the form a document writes them. `[]` marks an element — `hero.tags[].label` means each tag has a label, not that the list does.',
+                                'references.contract.complete is false when any branch could not be read, and `incomplete` names each with a reason. An incomplete contract is still useful, but a key missing from it may only be missing because that branch was unreadable — do not treat absence as proof.',
+                                'references.contract covers TEMPLATES. A layout sidecar is plain JavaScript and cannot be parsed, so a key only it reads will not appear there — look in references.runtime.metaReads instead.',
+                                'references.runtime.metaReads is what renders actually READ, sidecars included, unioned across the samples. It sees a sidecar the contract cannot; it does not see a branch no sample took. The two are complements, not alternatives.',
                                 'references.runtime is the precise answer from manifest snapshots — what the renderer actually touched in recent renders. Empty if the layout has never rendered.',
-                                'references.static is the renderer-plugin AST walk of the template source — what the source mentions, including unexercised conditional branches. Empty when the renderer does not expose parseReferences (markdown / metatext / custom).',
+                                'references.static is the renderer-plugin walk of THIS FILE only, in this file\'s own vocabulary. references.contract is the same walk followed across every partial and resolved into the author\'s. Prefer the contract.',
                                 'samples only includes entities with explicit meta.layout. Auto-matched layouts are not listed; use mikser_query_entities with a filename-pattern filter for those.',
                             ],
                         }, null, 2),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-layouts",
-  "version": "2.6.0",
+  "version": "2.7.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,15 +18,16 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-layouts#readme",
   "peerDependencies": {
-    "mikser-io": "^9.25.0"
+    "mikser-io": "^9.39.0",
+    "zod": "^4.0.0"
   },
   "dependencies": {
     "globby": "^14.0.0",
     "handlebars": "^4.7.0",
-    "lodash": "^4.17.0",
-    "zod": "^4.4.3"
+    "lodash": "^4.17.0"
   },
   "devDependencies": {
-    "mikser-io": "file:../mikser-io"
+    "mikser-io": "file:../mikser-io",
+    "zod": "^4.0.0"
   }
 }

package/test/contract.test.js

@@ -0,0 +1,185 @@
+// The contract of a layout AND everything it pulls in.
+//
+// `references.static` reports what ONE FILE mentions, in that file's own
+// vocabulary. For a real page layout that is close to useless: page.liquid is
+// mostly `{% include %}` and mentions almost nothing itself, while the section
+// that does the work opens `{% assign hero = data.meta.hero %}` and then talks
+// about `hero.tags` — a name that appears in no document and that an author
+// cannot write.
+//
+// So an agent checking a document against a layout had nothing to check
+// against, which is how a typo'd key ships a page with a section missing.
+//
+// These pin the two hops that used to break the chain: a value passed AS AN
+// ARGUMENT to a partial, and a value renamed by an alias. Both have to come
+// back out in the author's terms — `data.meta.*` — or the contract cannot be
+// diffed against a document's front matter.
+
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+import { createInspect } from '../lib/inspect.js'
+import * as liquid from 'mikser-io-render-liquid'
+
+// page → sections/hero → ui/tags. The key under test, `hero.tags`, is reached
+// through an alias in the middle file and an argument into the last one, so
+// nothing but a resolved closure can find it.
+const FILES = {
+    'page.liquid':
+        '<html><body>{% include "chrome/nav" %}'
+        + '{% for section in data.meta.sections %}{% include "sections/hero" %}{% endfor %}'
+        + '</body></html>',
+    'chrome/nav.liquid': '<nav>{{ data.meta.title }}</nav>',
+    'sections/hero.liquid':
+        '{%- assign hero = data.meta.hero -%}'
+        + '<h1>{{ hero.title }}</h1>'
+        + '{% if hero.background %}<img src="{{ hero.background }}">{% endif %}'
+        + '{% render "ui/tags", tags: hero.tags, heading: hero.tagsTitle %}',
+    'ui/tags.liquid':
+        '<ul>{% for t in tags %}<li>{{ t.label }}<span>{{ t.icon }}</span></li>{% endfor %}</ul>',
+}
+
+let dir, inspect, contract
+
+before(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), 'mikser-contract-'))
+    const entities = []
+    for (const [rel, content] of Object.entries(FILES)) {
+        const uri = path.join(dir, rel)
+        await mkdir(path.dirname(uri), { recursive: true })
+        await writeFile(uri, content)
+        const name = rel.replace(/\.liquid$/, '')
+        entities.push({ id: `/layouts/${rel}`, name, uri, collection: 'layouts', template: 'liquid', format: 'html' })
+    }
+
+    // The real liquid parser, dispatched exactly the way render does it — by
+    // `entity.template`. Nothing here knows what liquid syntax looks like.
+    const runtime = { renderers: new Map([['liquid', { parseReferences: liquid.parseReferences }]]) }
+
+    inspect = createInspect({
+        runtime,
+        findEntity:   async ({ id }) => entities.find(e => e.id === id) ?? null,
+        findEntities: async (q) => entities.filter(e => q.name == null || e.name === q.name),
+        useDatabase:  () => null,
+        collection:   'layouts',
+    })
+    contract = (await inspect('/layouts/page.liquid', { samples: 0 })).references.contract
+})
+
+after(async () => { if (dir) await rm(dir, { recursive: true, force: true }) })
+
+describe('the layout contract', () => {
+    it('follows a key through an ARGUMENT into the partial that consumes it', () => {
+        // `{% render "ui/tags", tags: hero.tags %}` — dropping the argument was
+        // the hole: ui/tags talks about `tags`, and nothing tied that back to
+        // the document key it was handed.
+        assert.ok(contract.meta.includes('hero.tags'),
+            `expected hero.tags in the contract, got: ${contract.meta.join(', ')}`)
+    })
+
+    it('resolves an alias back into the vocabulary the author writes', () => {
+        // sections/hero says `hero.title`. No document has a `hero.title` at
+        // the root — it is `data.meta.hero.title`, and only the assign says so.
+        assert.ok(contract.meta.includes('hero.title'))
+        assert.ok(contract.meta.includes('hero.background'))
+        assert.ok(!contract.consumes.some(c => c === 'hero.title'),
+            'the unresolved local name must not survive into the contract')
+    })
+
+    it('reaches keys two hops down, through an argument AND a loop', () => {
+        // ui/tags iterates what it was handed and reads `.label` off each item.
+        // Two rewrites away from the document: tags → hero.tags → an element.
+        assert.ok(contract.meta.includes('hero.tags[].label'),
+            `expected hero.tags[].label, got: ${contract.meta.join(', ')}`)
+        assert.ok(contract.meta.includes('hero.tags[].icon'))
+    })
+
+    it('marks an element as an element, not as the collection', () => {
+        // `hero.tags.label` would be a key that exists on no document — the
+        // label is on each tag, not on the list.
+        assert.ok(!contract.meta.includes('hero.tags.label'))
+    })
+
+    it('includes what the layout itself consumes, not only its partials', () => {
+        assert.ok(contract.meta.includes('sections'))
+        assert.ok(contract.meta.includes('title'), 'chrome/nav is walked too')
+    })
+
+    it('reports itself COMPLETE when every branch was read', () => {
+        assert.equal(contract.complete, true,
+            `unexpected gaps: ${JSON.stringify(contract.incomplete)}`)
+        assert.deepEqual(contract.incomplete, [])
+    })
+
+    it('names every template it walked, so the closure is auditable', () => {
+        const walked = contract.templates.map(t => t.template).sort()
+        assert.deepEqual(walked, ['chrome/nav', 'page', 'sections/hero', 'ui/tags'])
+    })
+})
+
+// A contract that LOOKS complete but silently skipped a branch is worse than
+// no contract: it invites an agent to trust a set difference that is missing
+// half its right-hand side. So every gap has to be named, and `complete` has
+// to go false the moment one exists.
+describe('the layout contract, where it cannot see', () => {
+    const build = async (files, rendererFor) => {
+        const dir = await mkdtemp(path.join(tmpdir(), 'mikser-contract-gap-'))
+        const entities = []
+        for (const [rel, content] of Object.entries(files)) {
+            const uri = path.join(dir, rel)
+            await mkdir(path.dirname(uri), { recursive: true })
+            await writeFile(uri, content)
+            entities.push({
+                id: `/layouts/${rel}`, name: rel.replace(/\.\w+$/, ''), uri,
+                collection: 'layouts', template: rel.endsWith('.liquid') ? 'liquid' : 'mystery',
+                format: 'html',
+            })
+        }
+        const inspect = createInspect({
+            runtime: { renderers: rendererFor },
+            findEntity:   async ({ id }) => entities.find(e => e.id === id) ?? null,
+            findEntities: async (q) => entities.filter(e => q.name == null || e.name === q.name),
+            useDatabase:  () => null,
+            collection:   'layouts',
+        })
+        const out = (await inspect('/layouts/page.liquid', { samples: 0 })).references.contract
+        await rm(dir, { recursive: true, force: true })
+        return out
+    }
+
+    const liquidOnly = new Map([['liquid', { parseReferences: liquid.parseReferences }]])
+
+    it('says so when an included partial does not exist', async () => {
+        const c = await build({ 'page.liquid': '{% include "sections/absent" %}' }, liquidOnly)
+        assert.equal(c.complete, false)
+        assert.ok(c.incomplete.some(i => i.template === 'sections/absent'),
+            `expected the missing partial to be named, got ${JSON.stringify(c.incomplete)}`)
+    })
+
+    it('says so when a partial is rendered by an engine that cannot be parsed', async () => {
+        // markdown and metatext are real cases: they render content, and have
+        // no parseReferences to expose. The closure must degrade loudly.
+        const c = await build({
+            'page.liquid': '{% include "sections/opaque" %}',
+            'sections/opaque.mystery': 'whatever this engine does',
+        }, new Map([
+            ['liquid', { parseReferences: liquid.parseReferences }],
+            ['mystery', { /* a renderer with no parser */ }],
+        ]))
+        assert.equal(c.complete, false)
+        const gap = c.incomplete.find(i => i.template === 'sections/opaque')
+        assert.ok(gap, `expected the opaque partial to be named, got ${JSON.stringify(c.incomplete)}`)
+        assert.match(gap.reason, /parseReferences/)
+    })
+
+    it('still reports everything it COULD read, rather than giving up', async () => {
+        const c = await build({
+            'page.liquid': '{{ data.meta.title }}{% include "sections/absent" %}',
+        }, liquidOnly)
+        assert.equal(c.complete, false)
+        assert.ok(c.meta.includes('title'), 'a gap in one branch must not discard the others')
+    })
+})

package/test/unit.test.js

@@ -158,9 +158,15 @@ describe('layouts plugin', () => {
             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}`)
-            // The harness records (format, ...args) unformatted, so render it
-            // the way the logger would before asserting on the message.
-            const text = format(...warnings[0].args)
+            // Structured first, sentence second — the call is
+            // logger.warn({ code, ... }, msg, ...values), and the fields are
+            // what the build report keys on. The harness records the args
+            // unformatted, so render the message the way the logger would.
+            const [fields, ...message] = warnings[0].args
+            assert.equal(fields.code, 'layout-pattern-no-match', 'carries the code the report is asserted on')
+            assert.equal(fields.pattern, 'nonesuch/*')
+            assert.equal(fields.matchedAgainst, 'id')
+            const text = format(...message)
             assert.match(text, /nonesuch/, 'names the pattern that matched nothing')
             assert.ok(!text.includes("'post'"), 'must not name the pattern that DID match')
             assert.match(text, /matched against entity\.id/, 'names the field this pattern is matched against')