mikser-io-layouts 2.9.1 → 2.9.3

package/lib/assembly.js

@@ -398,6 +398,14 @@ export function createOnBeforeRender({
                                 postprocessors: entity.layout.postprocessors ?? (entity.layout.postprocessor ? [entity.layout.postprocessor] : []),
                                 tasks: entity.meta?.task || TASKS.INLINE,
                             }, { data, plugins, sidecarQueries: sidecarTrack.queries,
+                                 // Plain arrays, because this context is journaled as JSON
+                                 // before the render runs — a Set arrives as {}.
+                                 //
+                                 // That same round-trip is why these are what the
+                                 // SIDECAR read and nothing more: the recording
+                                 // views inside `data` do not survive it, so a key
+                                 // only the template touches is never recorded
+                                 // here. See check_entity's untraceable handling.
                                  sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])],
                                  sidecarConsumedReads: [...(sidecarTrack.consumedReads ?? [])].map(([k, v]) => [k, [...v]]) })
                         }
@@ -427,7 +435,15 @@ export function createOnBeforeRender({
                         // deleted. The paginated branch above already
                         // does this.
                         { data, plugins, sidecarQueries: sidecarTrack.queries,
-                          sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])],
+                          // Plain arrays, because this context is journaled as JSON
+                                 // before the render runs — a Set arrives as {}.
+                                 //
+                                 // That same round-trip is why these are what the
+                                 // SIDECAR read and nothing more: the recording
+                                 // views inside `data` do not survive it, so a key
+                                 // only the template touches is never recorded
+                                 // here. See check_entity's untraceable handling.
+                                 sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])],
                                  sidecarConsumedReads: [...(sidecarTrack.consumedReads ?? [])].map(([k, v]) => [k, [...v]]) })
                     }
                 }

package/lib/inspect.js

@@ -270,7 +270,15 @@ async function buildContract({ layout, templateSource, runtime, findEntities, co
         // 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)
+            // A DERIVED value is not an alias. `{% assign rows = c.specs |
+            // split: '|' %}` turns a string into a list, so a read of `rows[0]`
+            // says nothing about `specs` having members — binding it would
+            // report `specs[]` as a required key of a document whose `specs` is
+            // the string being split, and no document can satisfy that.
+            //
+            // The source path is still recorded by the parser as consumed,
+            // which is the true dependency.
+            if (a?.key && a.from && !a.derived) subs[a.key] = resolve(a.from, subs)
         }
 
         const resolved = []

package/lib/mcp.js

@@ -193,10 +193,55 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
         const absent = [...consumedSet].filter(k => k && !isProvided(k))
         const missing = absent.filter(k => !isOptional(k)).sort()
         const missingOptional = absent.filter(isOptional).sort()
-        const unused = [...provided]
+        const candidates = [...provided]
             .filter(k => !isUsed(k))
             .filter(k => !ENGINE_KEYS.has(k.split('.')[0].replace(/\[\]$/, '')))
             .sort()
+
+        // "The parent was read, and every child looks unused" is the signature
+        // of a read this engine cannot follow, not of dead data.
+        //
+        // Provenance is recorded where a value is READ off an entity. When that
+        // value is then handed on — a sidecar returning it to a template — the
+        // context carrying it is journaled as JSON in between, so the recording
+        // view does not survive and only the top-level access was ever seen. A
+        // form built from `enquiry.fields` shows `enquiry` consumed and every
+        // field beneath it apparently unused, on pages that visibly render it.
+        //
+        // Reporting those as unused is worse than saying nothing: someone
+        // acting on the list deletes a working form. They are collapsed under
+        // the ancestor that WAS read, and named for what they are — untraceable.
+        // Only when the ancestor was read and NOTHING under it was — "parent
+        // consumed, every child unused" is the signature.
+        //
+        // If any sibling IS consumed, the engine can evidently see inside that
+        // structure, so a key nobody read is real evidence and must stay in
+        // `unused`. Without this the safeguard would swallow the strongest
+        // signal the tool has: a typo like `hero.subtitile` sits under `hero`,
+        // which is certainly consumed.
+        const blind = (ancestor) => ![...consumedSet].some(c =>
+            c.startsWith(`${ancestor}.`) || c.startsWith(`${ancestor}[`))
+        const ancestorRead = (key) => {
+            let p = key
+            while (true) {
+                if (p.endsWith('[]')) p = p.slice(0, -2)
+                else if (p.includes('.')) p = p.replace(/\.[^.]+$/, '')
+                else return null
+                if (!p) return null
+                if (consumedSet.has(p)) return blind(p) ? p : null
+            }
+        }
+        const unused = []
+        const byAncestor = new Map()
+        for (const key of candidates) {
+            const under = ancestorRead(key)
+            if (!under) { unused.push(key); continue }
+            if (!byAncestor.has(under)) byAncestor.set(under, [])
+            byAncestor.get(under).push(key)
+        }
+        const untraceable = [...byAncestor]
+            .map(([under, keys]) => ({ under, keys: keys.sort() }))
+            .sort((a, b) => a.under.localeCompare(b.under))
         const likelyTypos = []
         for (const wrote of unused) {
             let best = null
@@ -206,7 +251,7 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
             }
             if (best) likelyTypos.push({ wrote, ...best })
         }
-        return { provided, missing, missingOptional, unused, likelyTypos }
+        return { provided, missing, missingOptional, unused, untraceable, likelyTypos }
     }
 
 
@@ -296,6 +341,7 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                         missing: cmp.missing,
                         likelyTypos: cmp.likelyTypos,
                         unused: cmp.unused,
+                        untraceable: cmp.untraceable,
                         consumedKeys: read.keys,
                         counts: { consumedKeys: read.keys.length, provided: cmp.provided.size,
                                   missing: cmp.missing.length, unused: cmp.unused.length },
@@ -304,6 +350,7 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                             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.',
                             '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.',
                         ],
                     })
@@ -336,7 +383,7 @@ 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, likelyTypos } =
+            const { provided, missing, missingOptional, unused, untraceable, likelyTypos } =
                 compare(entity, consumed, optional)
 
             // A declared section that resolved to no template under this
@@ -359,6 +406,7 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                 likelyTypos,
                 missingOptional,
                 unused,
+                untraceable,
                 unresolvedSections,
                 counts: { consumed: consumed.size, provided: provided.size, missing: missing.length,
                           missingOptional: missingOptional.length, unused: unused.length },
@@ -370,6 +418,7 @@ export function registerCheckTool({ runtime, findEntity, findEntities, useDataba
                     '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.',
+                    '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.',

package/package.json

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

@@ -53,7 +53,10 @@ const DOCS = {
     '/documents/ghost.md': { title: 'T', sections: ['hero', 'nosuchsection'],
                              hero: { title: 'T', subtitle: 'S', tags: [{ label: 'A' }] } },
     // Never renders; a page queries it. Data, not an unbuilt page.
-    '/documents/nav.yml': { href: '/system/nav', items: [{ label: 'Home', href: '/' }], menuLabel: 'Menu' },
+    '/documents/nav.yml': { href: '/system/nav', items: [{ label: 'Home', href: '/' }], menuLabel: 'Menu',
+                            // Read as a whole and then handed to a template, so
+                            // only the top-level access is ever recorded.
+                            enquiry: { title: 'Ask', fields: [{ label: 'Message', name: 'message' }] } },
     // Never renders and nothing reads it.
     '/documents/orphan.yml': { href: '/system/orphan', whatever: 1 },
     // Engine-owned keys must never be reported as unused.
@@ -94,7 +97,7 @@ before(async () => {
     // What renders took OFF other entities. good.md read two fields of nav.yml
     // and never touched menuLabel — which is the whole point: the contract for a
     // document that never renders is what its consumers actually read.
-    const CONSUMED = [['/documents/nav.yml', ['items', 'items[]', 'items[].label', 'items[].href']]]
+    const CONSUMED = [['/documents/nav.yml', ['items', 'items[]', 'items[].label', 'items[].href', 'enquiry']]]
     const useDatabase = () => ({
         handle: {
             prepare: (sql) => ({
@@ -244,12 +247,35 @@ describe('mikser_check_entity: not a page', () => {
         assert.deepEqual(r.missing, [], 'this document provides everything its consumers read')
     })
 
+    it('does not call a key unused when an ancestor of it WAS read', async () => {
+        // The signature of a read this engine cannot follow: `enquiry` was read
+        // and handed to a template, and provenance does not survive that hop, so
+        // every field under it looks untouched while being on every page.
+        // Reporting nine false findings is worse than one honest line — someone
+        // acting on the list deletes a working form.
+        const r = await check('/documents/nav.yml')
+        for (const key of ['enquiry.title', 'enquiry.fields[].label', 'enquiry.fields[].name']) {
+            assert.ok(!r.unused.includes(key), `${key} was reported unused: ${r.unused.join(', ')}`)
+        }
+        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)))
+    })
+
+    it('still reports a key nothing read at all', async () => {
+        // The safeguard must not swallow the real signal: menuLabel has no
+        // ancestor that was read, so it stays where it belongs.
+        const r = await check('/documents/nav.yml')
+        assert.ok(r.unused.includes('menuLabel'), `unused: ${r.unused.join(', ')}`)
+        assert.ok(r.notes.some(n => /API client/.test(n)), 'its caveat has to travel with it')
+    })
+
     it('holds a data document to the same standard as a page', async () => {
         // menuLabel is provided and no render reads it. Weak evidence, exactly
         // as on a page — an API client may well be the consumer.
         const r = await check('/documents/nav.yml')
-        assert.ok(r.unused.includes('menuLabel'), `unused: ${r.unused.join(', ')}`)
-        assert.ok(r.notes.some(n => /API client/.test(n)))
+        assert.ok(r.consumedKeys.includes('items[].label'))
     })
 
     it('says plainly when no contract can be derived', async () => {