mikser-io-layouts 2.7.0 → 2.8.0

package/index.js

@@ -102,7 +102,7 @@ export function layouts(userOptions = {}) {
         // in the plugins array for this to fire; that constraint is
         // documented in mikser-io's CLAUDE.md.
         onLoaded(async () => {
-            registerMcpTools({ runtime, useLogger })
+            registerMcpTools({ runtime, useLogger, findEntity, findEntities, useDatabase, collection })
         })
 
         onSync(collection, async ({ action, context }) => {

package/lib/inspect.js

@@ -320,9 +320,17 @@ async function buildContract({ layout, templateSource, runtime, findEntities, co
     // 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.
+    // Entity meta, whichever root binding reached it.
+    //
+    // A template can arrive at the same keys by more than one name: `data` is
+    // whatever a layout sidecar returned, and the entity is ALSO bound under
+    // its own type, so `document.meta.title` and `data.meta.title` are the same
+    // document key. Matching only `data.` was lmed-shaped — a project with no
+    // sidecar writes `document.meta.` and would have got an empty contract,
+    // which reads exactly like a layout that needs nothing.
+    const META_ROOT = /^[A-Za-z_$][\w$]*\.meta\./
     const meta = [...consumes]
-        .filter(p => p.startsWith('data.meta.'))
-        .map(p => p.slice('data.meta.'.length))
+        .map(p => (META_ROOT.test(p) ? p.replace(META_ROOT, '') : (p.startsWith('meta.') ? p.slice(5) : null)))
         .filter(Boolean)
 
     return {

package/lib/mcp.js

@@ -10,7 +10,7 @@
 
 import { z } from 'zod'
 
-export function registerMcpTools({ runtime, useLogger }) {
+export function registerMcpTools({ runtime, useLogger, findEntity, findEntities, useDatabase, collection }) {
     const mcp = runtime.options.mcp
     if (!mcp) return   // mcp plugin not loaded — nothing to register
     if (!runtime.options.layouts?.inspect) return   // shouldn't happen if we run after our own inspect setup, but defensive
@@ -66,5 +66,207 @@ export function registerMcpTools({ runtime, useLogger }) {
         },
     )
 
+    registerCheckTool({ runtime, findEntity, findEntities, useDatabase, collection, logger })
+
     logger.debug('MCP tool registered: mikser_layouts_inspect (layouts plugin)')
 }
+
+// Meta keys the ENGINE owns. They appear on documents, are consumed by mikser
+// itself rather than by any layout, and would otherwise be reported as unused on
+// every entity — noise that teaches a reader to ignore the list.
+const ENGINE_KEYS = new Set([
+    'layout', 'layouts', 'task', 'destination', 'format', 'template', 'href',
+    'lang', 'url', 'pages', 'parent', 'plugins', 'presets', 'refs', 'date',
+    'draft', 'stamp', 'postprocessor',
+])
+
+// A document's meta in the same vocabulary a layout contract uses: dotted
+// paths, with `[]` for "each element of" rather than an index. Both sides have
+// to speak it or the comparison is meaningless.
+function flattenMeta(value, prefix, out) {
+    if (value === null || typeof value !== 'object') return out
+    if (Array.isArray(value)) {
+        // One `[]` for the whole array: the contract says "each tag has a
+        // label", never "tag 7 has a label", so element shapes are merged.
+        if (value.length) out.add(`${prefix}[]`)
+        for (const item of value) flattenMeta(item, `${prefix}[]`, out)
+        return out
+    }
+    for (const [k, v] of Object.entries(value)) {
+        const path = prefix ? `${prefix}.${k}` : k
+        out.add(path)
+        flattenMeta(v, path, out)
+    }
+    return out
+}
+
+// Observed reads carry the prefix of where they were seen — `meta.` for the
+// document's own keys as a sidecar read them, `data.meta.` for what a template
+// read. Both describe the same document, so both reduce to the bare key.
+const bareKey = (p) => p.replace(/^[A-Za-z_$][\w$]*\.meta\./, '').replace(/^meta\./, '')
+
+// Edit distance, capped: only used to ask "did they mean this one", so anything
+// past a couple of edits is not a typo and the answer stops mattering.
+function distance(a, b) {
+    if (Math.abs(a.length - b.length) > 3) return 99
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+    for (let i = 1; i <= a.length; i++) {
+        let last = prev[0]
+        prev[0] = i
+        for (let j = 1; j <= b.length; j++) {
+            const tmp = prev[j]
+            prev[j] = Math.min(
+                prev[j] + 1,
+                prev[j - 1] + 1,
+                last + (a[i - 1] === b[j - 1] ? 0 : 1),
+            )
+            last = tmp
+        }
+    }
+    return prev[b.length]
+}
+
+export function registerCheckTool({ runtime, findEntity, findEntities, useDatabase, collection, logger }) {
+    const mcp = runtime.options.mcp
+
+    // Which layout this entity ACTUALLY rendered with, taken from its most
+    // recent snapshot rather than predicted.
+    //
+    // Layout selection has three mechanisms — declared meta.layout, a match
+    // pattern, and the auto-layout peel ladder — and re-deriving them here
+    // would be a second implementation to keep in step with the first. The
+    // manifest already recorded the answer.
+    const layoutFromSnapshot = (id) => {
+        const db = useDatabase?.()
+        if (!db?.handle) return null
+        const row = db.handle.prepare(
+            'SELECT refClosure FROM mikser_snapshots WHERE id = ? ORDER BY renderedAt DESC LIMIT 1',
+        ).get(id)
+        if (!row?.refClosure) return null
+        try {
+            return JSON.parse(row.refClosure).find(e => e.kind === 'layout')?.target ?? null
+        } catch { return null }
+    }
+
+    const readsFromSnapshot = (id) => {
+        const db = useDatabase?.()
+        if (!db?.handle) return []
+        const row = db.handle.prepare(
+            'SELECT metaReads FROM mikser_snapshots WHERE id = ? ORDER BY renderedAt DESC LIMIT 1',
+        ).get(id)
+        if (!row?.metaReads) return []
+        try { return JSON.parse(row.metaReads) } catch { return [] }
+    }
+
+    mcp.simpleTool(
+        'mikser_check_entity',
+        'Check a document against the contract of the layout that renders it, BEFORE the mistake ships.\n\n'
+        + 'A mistyped key does not fail a build. The section it named simply does not render, the page goes out '
+        + 'with a hole in it, and every signal reads clean. This is the check that catches it: what the layout '
+        + 'tree needs, against what the document actually provides.\n\n'
+        + 'Read `missing` first — keys the layout consumes that this document has no value for. Then '
+        + '`likelyTypos`, which pairs a key you wrote against a key the layout wanted that is one or two edits '
+        + 'away; a typo usually shows up as both at once, which is a far stronger signal than either alone.\n\n'
+        + '`unused` is weaker evidence and says so: another layout may consume the key, and keys the engine '
+        + 'itself owns are excluded. Treat it as a prompt to look, not a defect.\n\n'
+        + 'Check `reliable` before trusting an absence. When false, some branch of the layout could not be read '
+        + 'or the document has never rendered, and a key may be missing from the analysis rather than from the '
+        + 'document.',
+        {
+            id: z.string().describe('Entity id, e.g. "/documents/en/index.md".'),
+            layout: z.string().optional()
+                .describe('Layout id to check against. Omit to use the layout this entity last rendered with, '
+                    + 'which is what the manifest recorded rather than a prediction.'),
+        },
+        async ({ id, layout }) => {
+            const entity = await findEntity({ id })
+            if (!entity) {
+                return { isError: true, content: [{ type: 'text', text:
+                    `No entity ${JSON.stringify(id)}. Use mikser_query_entities to find its id.` }] }
+            }
+
+            // Resolve the layout: explicit, then what it rendered with, then
+            // what it asked for. Each fallback is weaker, and which one was
+            // used is reported so the caller can judge.
+            let layoutId = layout ?? layoutFromSnapshot(id)
+            let source = layout ? 'given' : (layoutId ? 'last render' : null)
+            if (!layoutId && entity.meta?.layout) {
+                const named = (await findEntities({ name: entity.meta.layout })) ?? []
+                layoutId = named.find(e => e.collection === collection)?.id ?? null
+                source = layoutId ? 'meta.layout' : null
+            }
+            if (!layoutId) {
+                return { isError: true, content: [{ type: 'text', text:
+                    `Cannot tell which layout renders ${id}: it has never rendered and declares no meta.layout. `
+                    + 'Pass `layout` explicitly, or build once so the manifest records it.' }] }
+            }
+
+            const inspected = await runtime.options.layouts.inspect(layoutId, { samples: 0 })
+            const contract = inspected.references?.contract ?? { meta: [], complete: false, incomplete: [] }
+
+            // Consumed is the UNION of both halves, and it has to be: the
+            // contract is blind to a sidecar (plain JavaScript, nothing to
+            // parse) and the observed reads are blind to a branch this document
+            // never took. Using either alone reports keys as unused that are
+            // demonstrably read.
+            const observed = readsFromSnapshot(id).map(bareKey)
+            const consumed = new Set([...(contract.meta ?? []), ...observed])
+            const provided = flattenMeta(entity.meta ?? {}, '', new Set())
+
+            const isUsed = (key) => consumed.has(key)
+                // A parent is used when anything under it is: a document
+                // providing `hero` for a layout that reads `hero.title` has not
+                // provided a spare key.
+                || [...consumed].some(c => c.startsWith(`${key}.`) || c.startsWith(`${key}[`))
+            const isProvided = (key) => provided.has(key)
+                // And the reverse: a layout reading `hero.tags[]` is satisfied
+                // by a document that provided the array.
+                || [...provided].some(p => p.startsWith(`${key}.`) || p.startsWith(`${key}[`))
+
+            const missing = [...consumed].filter(k => k && !isProvided(k)).sort()
+            const unused = [...provided]
+                .filter(k => !isUsed(k))
+                .filter(k => !ENGINE_KEYS.has(k.split('.')[0].replace(/\[\]$/, '')))
+                .sort()
+
+            // The pair. A mistyped key leaves a hole where the real key was
+            // wanted AND a stray key nothing reads, so matching one list
+            // against the other turns two weak signals into one strong one.
+            const likelyTypos = []
+            for (const wrote of unused) {
+                let best = null
+                for (const wanted of missing) {
+                    const d = distance(wrote, wanted)
+                    if (d > 0 && d <= 2 && (!best || d < best.distance)) best = { meant: wanted, distance: d }
+                }
+                if (best) likelyTypos.push({ wrote, ...best })
+            }
+
+            const reliable = contract.complete === true && observed.length > 0
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                    entity: id,
+                    layout: layoutId,
+                    layoutFrom: source,
+                    reliable,
+                    missing,
+                    likelyTypos,
+                    unused,
+                    counts: { consumed: consumed.size, provided: provided.size,
+                              missing: missing.length, unused: unused.length },
+                    contract: { complete: contract.complete, incomplete: contract.incomplete ?? [] },
+                    observedReads: observed.length,
+                    notes: [
+                        'missing is the strong signal: the layout consumes the key and this document has no value for it.',
+                        'likelyTypos pairs an unused key against a missing one within two edits. A real typo usually produces both, which is why the pair is worth more than either list.',
+                        'unused is weak evidence. A key may be consumed by a DIFFERENT layout — a card rendered on a listing page is the common case — and keys the engine owns (href, lang, layout, task, ...) are excluded outright.',
+                        'reliable is false when the contract could not be fully read, or when this entity has never rendered so nothing was observed. An absence is only evidence when reliable is true.',
+                        'Coverage is the union of what the layout templates read (the contract) and what renders actually read (observed, which includes sidecars). Neither sees everything alone.',
+                    ],
+                }, null, 2) }],
+            }
+        },
+    )
+
+    logger.debug('MCP tool registered: mikser_check_entity (layouts plugin)')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-layouts",
-  "version": "2.7.0",
+  "version": "2.8.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",

package/test/check-entity.test.js

@@ -0,0 +1,150 @@
+// Checking a document against the contract of the layout that renders it.
+//
+// A mistyped key does not fail a build. The section it named simply does not
+// render, the page ships with a hole, and every signal reads clean. This is the
+// check that catches it before it ships, and it exists because the two halves it
+// needs — the layout contract and what renders actually read — are useless
+// separately: the contract is blind to a sidecar, and observed reads are blind
+// to a branch this document never took.
+
+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 { registerCheckTool } from '../lib/mcp.js'
+import * as liquid from 'mikser-io-render-liquid'
+
+const LAYOUTS = {
+    'page.liquid': '<html>{% include "sections/hero" %}<p>{{ document.meta.summary }}</p></html>',
+    'sections/hero.liquid':
+        '{%- assign hero = document.meta.hero -%}<h1>{{ hero.title }}</h1>'
+        + '{% for t in hero.tags %}<i>{{ t.label }}</i>{% endfor %}',
+}
+
+const DOCS = {
+    '/documents/good.md': { summary: 'S', hero: { title: 'T', tags: [{ label: 'A' }] } },
+    // `heroo` instead of `hero`: nothing under it is read, and everything the
+    // layout wanted is absent. One mistake, visible from both sides.
+    '/documents/typo.md': { summary: 'S', heroo: { title: 'T' } },
+    // Provides a key no layout here consumes. Weak evidence on purpose.
+    '/documents/extra.md': { summary: 'S', hero: { title: 'T', tags: [{ label: 'A' }] }, card: { order: 2 } },
+    // Engine-owned keys must never be reported as unused.
+    '/documents/routing.md': { summary: 'S', href: '/r', lang: 'bg', task: 'worker',
+                               hero: { title: 'T', tags: [{ label: 'A' }] } },
+}
+
+let dir, check
+
+before(async () => {
+    dir = await mkdtemp(path.join(tmpdir(), 'mikser-check-'))
+    const entities = []
+    for (const [rel, content] of Object.entries(LAYOUTS)) {
+        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(/\.liquid$/, ''), uri,
+                        collection: 'layouts', template: 'liquid' })
+    }
+    for (const [id, meta] of Object.entries(DOCS)) {
+        entities.push({ id, name: id.slice(11), collection: 'documents', meta })
+    }
+
+    // A stand-in manifest. Every document rendered with page.liquid, and read
+    // what a correct one would — so `unused` and `missing` are exercised
+    // without needing a real build in a unit test.
+    const observed = ['data.meta.summary', 'data.meta.hero', 'data.meta.hero.title',
+                      'data.meta.hero.tags', 'data.meta.hero.tags[]', 'data.meta.hero.tags[].label']
+    const useDatabase = () => ({
+        handle: {
+            prepare: (sql) => ({
+                get: (id) => (DOCS[id]
+                    ? (sql.includes('refClosure')
+                        ? { refClosure: JSON.stringify([{ kind: 'layout', target: '/layouts/page.liquid' }]) }
+                        : { metaReads: JSON.stringify(observed) })
+                    : undefined),
+            }),
+        },
+    })
+
+    const findEntity   = async ({ id }) => entities.find(e => e.id === id) ?? null
+    const findEntities = async (q) => entities.filter(e => q.name == null || e.name === q.name)
+    const runtime = {
+        options: {},
+        renderers: new Map([['liquid', { parseReferences: liquid.parseReferences }]]),
+    }
+    runtime.options.layouts = {
+        inspect: createInspect({ runtime, findEntity, findEntities, useDatabase, collection: 'layouts' }),
+    }
+    const registry = new Map()
+    runtime.options.mcp = { simpleTool: (name, _d, _s, handler) => registry.set(name, handler) }
+    registerCheckTool({ runtime, findEntity, findEntities, useDatabase,
+                        collection: 'layouts', logger: { debug() {} } })
+
+    check = async (id) => JSON.parse((await registry.get('mikser_check_entity')({ id })).content[0].text)
+})
+
+after(async () => { if (dir) await rm(dir, { recursive: true, force: true }) })
+
+describe('mikser_check_entity', () => {
+    it('says nothing is wrong with a document that satisfies the layout', async () => {
+        // The assertion that matters most: no false positives. A check that
+        // cries wolf on a correct document is one nobody reads.
+        const r = await check('/documents/good.md')
+        assert.deepEqual(r.missing, [])
+        assert.deepEqual(r.unused, [])
+        assert.deepEqual(r.likelyTypos, [])
+    })
+
+    it('names the keys the layout wants and the document lacks', async () => {
+        const r = await check('/documents/typo.md')
+        assert.ok(r.missing.includes('hero.title'), `missing: ${r.missing.join(', ')}`)
+        assert.ok(r.missing.includes('hero.tags[].label'))
+    })
+
+    it('pairs the key written against the key meant', async () => {
+        // The point of the tool. A typo shows up as a hole AND a stray key, and
+        // matching one list against the other turns two weak signals into one
+        // strong one.
+        const r = await check('/documents/typo.md')
+        const pair = r.likelyTypos.find(t => t.wrote === 'heroo')
+        assert.ok(pair, `no pairing found in ${JSON.stringify(r.likelyTypos)}`)
+        assert.equal(pair.meant, 'hero')
+        assert.equal(pair.distance, 1)
+    })
+
+    it('reports a key no layout reads, without calling it an error', async () => {
+        const r = await check('/documents/extra.md')
+        assert.ok(r.unused.includes('card'), `unused: ${r.unused.join(', ')}`)
+        assert.deepEqual(r.missing, [], 'an unused key is not a missing one')
+        assert.ok(r.notes.some(n => /DIFFERENT layout/.test(n)),
+            'the weakness of this signal has to travel with it')
+    })
+
+    it('never reports engine-owned keys as unused', async () => {
+        // href, lang and task are consumed by mikser, not by any layout. Listing
+        // them on every document would teach a reader to skip the list.
+        const r = await check('/documents/routing.md')
+        for (const key of ['href', 'lang', 'task']) {
+            assert.ok(!r.unused.includes(key), `${key} leaked into unused: ${r.unused.join(', ')}`)
+        }
+    })
+
+    it('counts a parent as provided when the layout reads through it', async () => {
+        const r = await check('/documents/good.md')
+        assert.ok(!r.missing.includes('hero'), 'hero is provided by providing its contents')
+    })
+
+    it('uses the layout the entity actually rendered with', async () => {
+        const r = await check('/documents/good.md')
+        assert.equal(r.layout, '/layouts/page.liquid')
+        assert.equal(r.layoutFrom, 'last render')
+    })
+
+    it('refuses an entity it cannot find rather than guessing', async () => {
+        const r = await check('/documents/nope.md').catch(() => null)
+        assert.equal(r, null, 'a missing entity must not produce a report')
+    })
+})