mikser-io-layouts 2.11.0 → 2.11.2

package/lib/mcp.js

@@ -188,6 +188,9 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                 }
                 return
             case 'array':
+                // The element path is NOT added as a key of its own. Requiring
+                // `tags[]` would claim the array must be non-empty, which no
+                // schema said — an empty list is a valid `z.array()`.
                 schemaKeys(def.element, `${prefix}[]`, required, optional, depth + 1)
                 return
             default:
@@ -448,14 +451,23 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                     // must contain, where consumer reads only say what someone
                     // happened to look at. Without this a data document was the
                     // one kind that could not benefit from its own schema.
+                    // Two questions, two comparisons — as on a page.
+                    //
+                    // `unused` and `untraceable` ask "does anything READ this",
+                    // which only consumption answers. Running them against the
+                    // schema instead reported keys as unread that the recorded
+                    // reads plainly contain: a schema does not enumerate array
+                    // elements, so every `x[]` in the document looked untouched.
+                    const byReads = compare(entity, new Set(read.keys), new Set())
                     const declared = schemaFor(entity)
-                    let cmp
+                    let cmp = byReads
                     if (declared) {
                         const req = new Set(); const opt = new Set()
                         schemaKeys(declared.schema, '', req, opt)
-                        cmp = compare(entity, new Set([...req, ...opt]), opt)
-                    } else {
-                        cmp = compare(entity, new Set(read.keys), new Set())
+                        const bySchema = compare(entity, new Set([...req, ...opt]), opt)
+                        // `missing` from the declaration, the rest from reality.
+                        cmp = { ...byReads, missing: bySchema.missing,
+                                missingOptional: bySchema.missingOptional }
                     }
                     // Matters most here: a data document is otherwise only
                     // checked against whatever its consumers happen to read, so
@@ -481,14 +493,9 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                         counts: { consumedKeys: read.keys.length, provided: cmp.provided.size,
                                   missing: cmp.missing.length, unused: cmp.unused.length },
                         notes: [
-                            `This entity never renders. ${consumers.length} render(s) pulled it in through a catalog query, so it is data, not a page — building will not make it appear.`,
-                            read.keys.length
-                                ? 'consumedKeys is what those renders actually READ off this entity. That is its contract: a key here with no value is a hole in the pages listed above, not in this file.'
-                                : 'No key-level reads are recorded yet, so only the consumer list is known. Build once with a current mikser and the fields each render takes off this entity get recorded.',
-                            'untraceable means an ancestor WAS read but the members could not be followed: the value was handed to a template and provenance does not survive that hop. Treat them as consumed.',
-                            'missingFrom says where `missing` came from: "schema" is declared and authoritative; "consumers" means it is derived from what renders actually read off this entity, which only covers what someone happened to look at.',
-                            'peerGaps compares this record with the others declaring the same type — keys most of them carry that this one lacks. For a data document this is often the only check with teeth, since everything else here depends on what a consumer happened to read. Weak evidence, never a failure.',
-                            'unused here means no render took the key. It may still be served to an API client or another process, which this tool cannot see — mikser is not always a static site generator.',
+                            `Never renders — ${consumers.length} render(s) query it. Building will not make it appear, and a key it lacks shows up as a hole in those pages.`,
+                            'missing: check missingFrom — "schema" is declared, "consumers" is only what someone happened to read off it.',
+                            'Look, do not panic: consumedKeys (what renders actually took), peerGaps (most records of this type carry it), unused (may still be served to an API client), untraceable (an ancestor was read but its members could not be followed). None of these is a defect on its own.',
                         ],
                     })
                 }
@@ -506,12 +513,11 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                             peerGroup: { type: orphanPeers.type, peers: orphanPeers.peers } }
                         : {}),
                     notes: [
+                        'Never renders, declares no layout, and no render queried it. Not an error: the catalog is readable over the API, so a consumer outside this project may depend on it.',
                         ...(orphanPeers?.gaps.length
-                            ? ['peerGaps is the only check that could be made here: nothing reads this entity, so nothing defines what it needs, but the other records declaring the same type do. Weak evidence, never a failure — records differ for good reasons.']
+                            ? ['peerGaps is the only check possible here — nothing reads this entity, so only the other records of its type say anything about it.']
                             : []),
-                        'This entity has never rendered, declares no meta.layout, and no render in the manifest queried it. Nothing in this project reads it.',
-                        'That is not an error. The catalog is readable over the API, so another process or an external consumer may depend on it, and this tool cannot see them.',
-                        'If it was MEANT to be a page, it matched no layout — check the layouts match patterns or set meta.layout.',
+                        'If it was meant to be a page it matched no layout: check the layouts match patterns, or set meta.layout.',
                     ],
                 })
             }
@@ -560,13 +566,36 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                 // 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}[`))
+
+                // `declaredButNotRead` asks whether a declared key is read by
+                // ANY layout, so it is answered against the UNSCOPED contract —
+                // the opposite of `missing`, which asks what THIS page needs.
+                //
+                // Scoped, a shorter edition of a page looked broken: every
+                // section it does not use made the schema's keys for that
+                // section look dead, and one such page reported 118 of them
+                // while its longer sibling reported none. The document's only
+                // difference was using fewer sections.
+                const wide = await runtime.options.layouts.inspect(layoutId, { samples: 0 })
+                const anyLayout = new Set([
+                    ...(wide.references?.contract?.meta ?? []),
+                    ...observed,
+                ])
+                const readAnywhere = (k) => anyLayout.has(k)
+                    || [...anyLayout].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(),
+                    declaredButNotRead: [...req].filter(k => !readAnywhere(k)).sort(),
                 }
+
+                // And the same noise in the softer list: a key this page's
+                // layout cannot reach is not an omission, it is not applicable.
+                // Reporting 139 of them is the noise the scoping fix removed
+                // from `missing`, arriving by another route.
+                const reachable = (k) => consumed.has(k)
+                    || [...consumed].some(c => c.startsWith(`${k}.`) || c.startsWith(`${k}[`))
+                missingOptional = missingOptional.filter(reachable)
             }
 
             // A declared section that resolved to no template under this
@@ -605,17 +634,14 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                 contract: { complete: contract.complete, incomplete: contract.incomplete ?? [],
                             scopedToPartials: usedPartials?.length ?? null },
                 observedReads: observed.length,
+                // One line per field, saying what to DO with it. These are
+                // read on every call, so anything that is not actionable is
+                // cost without value.
                 notes: [
-                    '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.',
-                    'peerGaps compares this record with the others declaring the same type: keys most of them carry that this one lacks, with the count as evidence. A layout contract cannot see this — a record missing a field its siblings all have renders perfectly and reads nothing that is absent. Weak evidence, and never a failure: records differ for good reasons.',
-                    '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.',
-                    'untraceable is NOT a list of problems. An ancestor of each key WAS read, but the value was handed on — a sidecar returning it to a template — and provenance does not survive that hop, so the members could not be followed. Treat them as consumed unless you have another reason to doubt it.',
-                    'unused is weak evidence too, and weakest of all where mikser is not a static site generator. A key may be consumed by a DIFFERENT layout, or by an API client reading the catalog over HTTP, or by another process entirely — none of which this tool can see. Engine-owned keys (href, lang, layout, task, ...) are excluded outright.',
-                    'The contract is scoped to the partials this entity ACTUALLY rendered with, not to every branch the layout could take. Unscoped, a page that uses two of twenty sections is checked against all twenty.',
-                    'reliable is false unless the contract was fully read AND this entity has rendered. An absence is only evidence when it is true.',
+                    'missing: the layout needs it and this document has no value for it. Check missingFrom — "schema" is declared and authoritative, "inferred" is read from templates and is strong evidence rather than proof.',
+                    'likelyTypos: a key you wrote paired with one the layout wanted, within two edits. A typo produces both, so the pair is worth more than either list.',
+                    'Look, do not panic: missingOptional (guarded by the layout, safe to omit), unused (may be read by another layout or an API client), untraceable (an ancestor was read but its members could not be followed), unresolvedSections (matched no template here), peerGaps (most records of this type carry it). None of these is a defect on its own.',
+                    'reliable: false means the contract had gaps or this entity has not rendered. An absence is only evidence when it is true.',
                 ],
             })
         },

package/package.json

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

@@ -198,7 +198,8 @@ describe('mikser_check_entity: a page', () => {
         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)))
+        assert.ok(r.notes.some(n => /another layout or an API client/.test(n)),
+            'the caveat has to travel with the finding')
     })
 
     it('never reports engine-owned keys as unused', async () => {
@@ -214,7 +215,8 @@ describe('mikser_check_entity: a page', () => {
         const r = await check('/documents/ghost.md')
         assert.deepEqual(r.unresolvedSections, ['nosuchsection'])
         assert.deepEqual(r.missing, [], 'an unresolved section is not a missing key')
-        assert.ok(r.notes.some(n => /unresolvedSections/.test(n) && /never fails/.test(n)))
+        assert.ok(r.notes.some(n => /unresolvedSections/.test(n) && /defect/.test(n)),
+            'it must be named as something to look at, not a failure')
     })
 
     it('uses the layout the entity actually rendered with', async () => {
@@ -233,7 +235,7 @@ describe('mikser_check_entity: not a page', () => {
         assert.equal(r.kind, 'data')
         assert.deepEqual(r.consumedBy, ['/documents/good.md'])
         assert.ok(!JSON.stringify(r.notes).includes('build once'))
-        assert.ok(r.notes.some(n => /hole in the pages listed above/.test(n)),
+        assert.ok(r.notes.some(n => /hole in those pages/.test(n)),
             'it has to say where a mistake would actually show up')
     })
 
@@ -260,7 +262,8 @@ describe('mikser_check_entity: not a page', () => {
         const group = r.untraceable.find(g => g.under === 'enquiry')
         assert.ok(group, `expected them collapsed under enquiry, got ${JSON.stringify(r.untraceable)}`)
         assert.ok(group.keys.includes('enquiry.fields[].label'))
-        assert.ok(r.notes.some(n => /Treat them as consumed/.test(n)))
+        assert.ok(r.notes.some(n => /untraceable/.test(n) && /could not be followed/.test(n)),
+            'the reason it cannot be judged has to travel with it')
     })
 
     it('still reports a key nothing read at all', async () => {
@@ -370,6 +373,27 @@ describe('mikser_check_entity: with a declared schema', () => {
             `missingOptional: ${r.missingOptional.join(', ')}`)
     })
 
+    it('answers declaredButNotRead against ANY layout, not just this page', async () => {
+        // The mirror of the scoping fix. `missing` asks what THIS page needs,
+        // so it is scoped; "is this key read anywhere" is the opposite question
+        // and must not be. Scoped, a shorter edition of a page reported every
+        // key of every section it does not use as dead — 118 of them on a page
+        // whose only difference was using fewer sections than its sibling.
+        const r = await checkWithSchema('/documents/schemed.md')
+        assert.ok(!r.drift.declaredButNotRead.some(k => k.startsWith('hero.')),
+            `hero keys are read by a layout, just not this render: ${r.drift.declaredButNotRead.join(', ')}`)
+    })
+
+    it('does not list an optional key this page could not use anyway', async () => {
+        // Same noise by another route: a key outside what this page renders is
+        // not an omission, it is not applicable.
+        const r = await checkWithSchema('/documents/schemed.md')
+        for (const k of r.missingOptional) {
+            assert.ok(!/^(specs|series|results)\./.test(k),
+                `${k} belongs to a section this page does not render`)
+        }
+    })
+
     it('reports drift in both directions', async () => {
         const r = await checkWithSchema('/documents/schemed.md')
         assert.equal(r.drift.schema, 'article')
@@ -384,7 +408,7 @@ describe('mikser_check_entity: with a declared schema', () => {
     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)),
+        assert.ok(r.notes.some(n => /strong evidence rather than proof/.test(n)),
             'the weaker source has to say that it is weaker')
     })
 })
@@ -460,7 +484,7 @@ describe('mikser_check_entity: peer comparison', () => {
     it('never fails the check — it is a prompt, not a defect', async () => {
         const r = await peerCheck('/documents/cat-gap.md')
         assert.notEqual(r.kind, undefined)
-        assert.ok(r.notes.some(n => /Weak evidence, never a failure|never a failure/.test(n)),
+        assert.ok(r.notes.some(n => /peerGaps/.test(n) && /defect|only check possible/.test(n)),
             'the weakness has to travel with the finding')
     })