mikser-io-layouts 2.9.3 → 2.10.0

package/README.md

@@ -176,7 +176,28 @@ See the [mikser-io rendering docs](https://github.com/almero-digital-marketing/m
 
 ## `inspect()` primitive
 
-`runtime.options.layouts.inspect(layoutId, { samples })` runs a layout against `samples` real entities and returns the resolved template source, render context, parsed refs, and any errors. Used by the `mikser-io-mcp` plugin's `mikser_layouts_inspect` MCP tool but available to any plugin that wants to surface layout introspection.
+`runtime.options.layouts.inspect(layoutId, { samples, partials })` returns a layout's template source, sample entities, and three views of what it depends on:
+
+- **`references.contract`** — the whole layout tree walked, with partial arguments and renamings resolved, so `meta` lists document keys in the form a document writes them. Pass `partials` (the ids a render actually used, from the manifest) to scope it to one page: a layout that dispatches sections through a registry otherwise resolves statically to *every* section in the project.
+- **`references.runtime`** — what recent renders actually touched, including `metaReads`, which sees a layout sidecar that no parser can.
+- **`references.static`** — the single-file parse, in that file's own vocabulary.
+
+`contract.complete` is false when a branch could not be read, and `incomplete` names each with a reason. An incomplete contract is still useful, but absence is not proof.
+
+## Checking a document — `mikser_check_entity`
+
+Answers "does this document have what its layout needs", before the mistake ships. A mistyped key does not fail a build: the section it named simply does not render.
+
+It classifies the entity first, because not every document is a page — `page`, `data` (never renders, but other entities query it; reports who, and what they read off it) or `unreferenced` (nothing in the catalog reads it, which is not an error — the catalog is readable over the API).
+
+Read `missing` first, but check **`missingFrom`**:
+
+- `schema` — a [zod schema](https://www.npmjs.com/package/mikser-io-schemas) declares the key required. Authoritative, and it needed no template parsing.
+- `inferred` — read out of the templates. Strong evidence, not proof: it models one engine's semantics and a guard it cannot see makes a fine document look broken.
+
+With a schema you also get `drift`: `readButNotDeclared` (layouts consume a key nothing declares — a schema gap, or a template typo) and `declaredButNotRead` (declared, unread — dead, or served over the API).
+
+Everything else means "you may want to look", never "this is broken": `missingOptional` is guarded and safe to omit, `unused` may be consumed by another layout or an API client, `untraceable` means an ancestor was read but its members could not be followed, and `unresolvedSections` names a section that matched no template.
 
 ## Entity properties
 

package/lib/mcp.js

@@ -153,6 +153,69 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
     const edgesOf = (snap) => parse(snap?.refClosure, [])
     const readsOf = (snap) => parse(snap?.metaReads, [])
 
+    // A DECLARED contract, walked out of a zod schema.
+    //
+    // This is the only source here that is engine-agnostic by construction. It
+    // says nothing about liquid or handlebars, it needs no filter table, and it
+    // states required-versus-optional outright instead of inferring it from
+    // `{% if %}` guards and `| default:` filters — which is the same distinction
+    // reconstructed by reading templates, and got wrong twice.
+    //
+    // Where a schema exists it therefore OUTRANKS anything read out of a
+    // template, and the inferred contract is demoted to reporting drift.
+    const zdef = (t) => t?._zod?.def ?? t?._def ?? {}
+    function schemaKeys(type, prefix, required, optional, depth = 0) {
+        const def = zdef(type)
+        if (!def.type || depth > 12) return
+        switch (def.type) {
+            // A wrapper says the value beneath it may be absent; everything
+            // under it inherits that, since a document omitting the parent
+            // cannot be faulted for omitting its members.
+            case 'optional':
+            case 'nullable':
+            case 'default':
+                if (prefix) { required.delete(prefix); optional.add(prefix) }
+                schemaKeys(def.innerType, prefix, required, new Set(), depth + 1)
+                for (const k of collectAll(def.innerType, prefix, depth + 1)) optional.add(k)
+                return
+            case 'object':
+                for (const [key, child] of Object.entries(def.shape ?? {})) {
+                    const path = prefix ? `${prefix}.${key}` : key
+                    const childDef = zdef(child)
+                    const soft = ['optional', 'nullable', 'default'].includes(childDef.type)
+                    ;(soft ? optional : required).add(path)
+                    schemaKeys(child, path, required, optional, depth + 1)
+                }
+                return
+            case 'array':
+                schemaKeys(def.element, `${prefix}[]`, required, optional, depth + 1)
+                return
+            default:
+                return
+        }
+    }
+    // Every path under a type, regardless of requiredness — used to mark a whole
+    // optional subtree optional.
+    function collectAll(type, prefix, depth = 0) {
+        const req = new Set(); const opt = new Set()
+        schemaKeys(type, prefix, req, opt, depth)
+        return [...req, ...opt]
+    }
+
+    // The schema declared for this entity, if the schemas plugin is loaded and
+    // the entity names one. `schemaKey` is the plugin's own config — commonly
+    // `meta.layout`, so a layout and its schema share a name.
+    const schemaFor = (entity) => {
+        const api = runtime.options.schemas
+        if (!api?.lookup) return null
+        const key = runtime.options.schemasKey ?? runtime.options.schemaKey ?? 'meta.schema'
+        const name = key.split('.').reduce((o, k) => o?.[k], entity)
+            ?? entity?.meta?.schema ?? entity?.meta?.layout
+        if (!name) return null
+        const schema = api.lookup(name)
+        return schema ? { name, schema } : null
+    }
+
     // What every render read OFF this entity, and who read it.
     //
     // The contract for a document that never renders. `metaReads` answers "what
@@ -383,8 +446,41 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
             // `missing` is the ONLY list that should read as "this is probably
             // wrong". A key the layout guards with `{% if %}` is one the layout
             // was written to work without, so it belongs in the softer list.
-            const { provided, missing, missingOptional, unused, untraceable, likelyTypos } =
-                compare(entity, consumed, optional)
+            // `unused` always comes from what is CONSUMED — a key nothing reads
+            // is the question there, and a schema does not answer it.
+            const inferred = compare(entity, consumed, optional)
+            const { provided, unused, untraceable, likelyTypos } = inferred
+
+            // `missing` prefers the DECLARED contract. A schema states
+            // required-versus-optional outright, needs no template parsing, and
+            // is engine-agnostic by construction — where one exists, nothing
+            // read out of a template should be able to call a document broken.
+            const declaredSchema = schemaFor(entity)
+            let missing = inferred.missing
+            let missingOptional = inferred.missingOptional
+            let drift = null
+            if (declaredSchema) {
+                const req = new Set(); const opt = new Set()
+                schemaKeys(declaredSchema.schema, '', req, opt)
+                // Both sets are candidates: an absent OPTIONAL key still has
+                // to be reported, in the softer list, or a schema's optionality
+                // would silently drop it from the report altogether.
+                const bySchema = compare(entity, new Set([...req, ...opt]), opt)
+                missing = bySchema.missing
+                missingOptional = bySchema.missingOptional
+                // Where the two disagree, which is the drift the schemas plugin
+                // exists to catch: a layout reading a key nobody declared, or a
+                // declared key no layout reads.
+                const knows = (k) => req.has(k) || opt.has(k)
+                    || [...req, ...opt].some(d => d.startsWith(`${k}.`) || d.startsWith(`${k}[`))
+                const isRead = (k) => consumed.has(k)
+                    || [...consumed].some(c => c.startsWith(`${k}.`) || c.startsWith(`${k}[`))
+                drift = {
+                    schema: declaredSchema.name,
+                    readButNotDeclared: [...consumed].filter(k => k && !knows(k)).sort(),
+                    declaredButNotRead: [...req].filter(k => !isRead(k)).sort(),
+                }
+            }
 
             // A declared section that resolved to no template under this
             // layout. Weak evidence, reported apart from `missing` and never a
@@ -402,9 +498,15 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                 layout: layoutId,
                 layoutFrom: mode,
                 reliable,
+                // Where `missing` came from, because the two are not equally
+                // trustworthy and a caller acting on it deserves to know which
+                // it has: 'schema' is declared, 'inferred' is read out of
+                // templates and can be wrong.
+                missingFrom: declaredSchema ? 'schema' : 'inferred',
                 missing,
                 likelyTypos,
                 missingOptional,
+                ...(drift ? { drift } : {}),
                 unused,
                 untraceable,
                 unresolvedSections,
@@ -414,7 +516,8 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                             scopedToPartials: usedPartials?.length ?? null },
                 observedReads: observed.length,
                 notes: [
-                    'missing is the strong signal: the layout consumes the key unconditionally and this document has no value for it.',
+                    'missing is the strong signal, but read missingFrom first. "schema" means a zod schema DECLARES the key required — authoritative, and it needed no template parsing. "inferred" means it was read out of the templates, which models one engine\'s semantics and has been wrong: a guard it cannot see makes a fine document look broken. Treat an inferred missing as strong evidence, not proof.',
+                    'drift appears only with a schema, and is where the two sources disagree: readButNotDeclared is a key the layouts consume that nothing declares (a schema gap, or a typo in a template), declaredButNotRead is a declared key no layout reads (dead, or consumed over the API).',
                     'likelyTypos pairs an unused key against a wanted one within two edits. A real typo produces both, which is why the pair is worth more than either list.',
                     'missingOptional is NOT a defect. The layout guards these behind a condition, so it was written to work without them — they are listed only so a deliberate omission can be told from a forgotten one.',
                     'unresolvedSections named a section that resolved to no template under THIS layout. Weak evidence: the section may render under a different layout, its template may not be written yet, or the data may be consumed outside the SSG entirely — the catalog is readable over the API. It never fails a check.',

package/package.json

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

@@ -291,3 +291,100 @@ describe('mikser_check_entity: not a page', () => {
         assert.equal(r, null)
     })
 })
+
+// A DECLARED contract outranks one read out of templates.
+//
+// A zod schema says nothing about liquid. It needs no filter table, states
+// required-versus-optional outright rather than inferring it from `{% if %}`
+// guards and `| default:`, and is engine-agnostic by construction. Where one
+// exists, nothing parsed out of a template should be able to call a document
+// broken — that inference has been wrong, and `missing` is the one list that
+// must only ever mean "probably wrong".
+describe('mikser_check_entity: with a declared schema', () => {
+    let checkWithSchema, dir2
+
+    before(async () => {
+        const { z } = await import('zod')
+        dir2 = await mkdtemp(path.join(tmpdir(), 'mikser-check-schema-'))
+        const entities = []
+        for (const [rel, content] of Object.entries(LAYOUTS)) {
+            const uri = path.join(dir2, 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' })
+        }
+        // Declares a key the layouts do NOT read, and omits one they do.
+        const schema = z.object({
+            title: z.string(),
+            byline: z.string(),                    // declared, no layout reads it
+            hero: z.object({
+                title: z.string(),
+                subtitle: z.string().optional(),   // declared optional
+            }),
+        })
+        const doc = { id: '/documents/schemed.md', name: 'schemed', collection: 'documents',
+                      meta: { schema: 'article', title: 'T', sections: ['hero'],
+                              hero: { title: 'T', tags: [{ label: 'A' }] } } }
+        entities.push(doc)
+
+        const useDatabase = () => ({ handle: { prepare: (sql) => ({
+            all: () => [],
+            get: () => (sql.includes('refClosure')
+                ? { refClosure: JSON.stringify([
+                    { kind: 'layout', target: '/layouts/page.liquid' },
+                    ...PAGE_PARTIALS.map(t => ({ kind: 'partial', target: t })),
+                  ]) }
+                : { metaReads: JSON.stringify(['data.meta.title', 'data.meta.hero.title']) }),
+        }) } })
+        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: { schemas: { lookup: (n) => (n === 'article' ? schema : undefined), names: () => ['article'] } },
+            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: (n, _d, _s, h) => registry.set(n, h) }
+        registerCheckTool({ runtime, findEntity, findEntities, useDatabase,
+                            collection: 'layouts', logger: { debug() {} } })
+        checkWithSchema = async (id) =>
+            JSON.parse((await registry.get('mikser_check_entity')({ id })).content[0].text)
+    })
+
+    after(async () => { if (dir2) await rm(dir2, { recursive: true, force: true }) })
+
+    it('takes `missing` from the schema and says so', async () => {
+        const r = await checkWithSchema('/documents/schemed.md')
+        assert.equal(r.missingFrom, 'schema')
+        assert.ok(r.missing.includes('byline'), `missing: ${r.missing.join(', ')}`)
+    })
+
+    it('honours zod optionality instead of inferring it from the template', async () => {
+        // `.optional()` states it. No guard analysis, no filter table.
+        const r = await checkWithSchema('/documents/schemed.md')
+        assert.ok(!r.missing.includes('hero.subtitle'))
+        assert.ok(r.missingOptional.includes('hero.subtitle'),
+            `missingOptional: ${r.missingOptional.join(', ')}`)
+    })
+
+    it('reports drift in both directions', async () => {
+        const r = await checkWithSchema('/documents/schemed.md')
+        assert.equal(r.drift.schema, 'article')
+        // The layouts read hero.tags[].label; nothing declares it.
+        assert.ok(r.drift.readButNotDeclared.some(k => k.startsWith('hero.tags')),
+            `readButNotDeclared: ${r.drift.readButNotDeclared.join(', ')}`)
+        // byline is declared and no layout reads it.
+        assert.ok(r.drift.declaredButNotRead.includes('byline'),
+            `declaredButNotRead: ${r.drift.declaredButNotRead.join(', ')}`)
+    })
+
+    it('labels an inferred contract as inferred when there is no schema', async () => {
+        const r = await check('/documents/good.md')
+        assert.equal(r.missingFrom, 'inferred')
+        assert.ok(r.notes.some(n => /has been wrong/.test(n)),
+            'the weaker source has to say that it is weaker')
+    })
+})