mikser-io-layouts 2.11.1 → 2.12.0

package/index.js

@@ -123,6 +123,9 @@ export function layouts(userOptions = {}) {
             // what makes their dependents re-render.
             if (_.endsWith(relativePath, '.js') && isSidecarScript(relativePath)) {
                 logger.debug('Layouts sidecar changed (%s) — rescanning layouts', relativePath)
+                // The rescan re-catalogues the sidecar itself and re-emits
+                // whichever layouts its digest moved, so both the entity and
+                // its dependents follow from one call.
                 await rescanLayouts()
                 return
             }
@@ -292,6 +295,23 @@ export function layouts(userOptions = {}) {
             const { layouts } = runtime.state.layouts
             const logger = useLogger()
             const paths = await globby('**/*', { cwd: runtime.options.layoutsFolder, ignore: ['**/*.js'] })
+            // Sidecars are catalogued too — as entities of their own, not as
+            // layouts. They are where a site's data layer lives (`data.children`
+            // on this project is an entire catalog listing), and until now they
+            // were the one source file no tool could read, search or resolve:
+            // an agent could see what a template does but not what feeds it.
+            //
+            // They are scanned in the SAME pass so the checksum gate and the
+            // delete sweep cover them; a separate pass would sweep them away.
+            //
+            // The original objection to giving them entities was the id
+            // stripping — `page.js` becoming a phantom `/layouts/page` beside
+            // the real `/layouts/page.liquid`. Keeping the `.js` removes that,
+            // and they stay out of the layouts NAME map so nothing resolves a
+            // template to one. Rendering is not a risk either: layout matching
+            // skips this collection outright.
+            const sidecarPaths = (await globby('**/*.js', { cwd: runtime.options.layoutsFolder }))
+                .filter(isSidecarScript)
             const inputs = await sidecarInputs()
             const scanned = new Set()
             const stats = { emitted: 0, skipped: 0, deleted: 0 }
@@ -309,11 +329,29 @@ export function layouts(userOptions = {}) {
             // before the loop; the gate hits a Map.get instead of a per-
             // file SQL lookup.
             const priorChecksums = checksumsByCollection(collection)
-            for (let relativePath of paths) {
+            for (let relativePath of [...paths, ...sidecarPaths]) {
                 const uri = path.join(runtime.options.layoutsFolder, relativePath)
                 const id = path.join('/layouts', relativePath)
                 scanned.add(id)
 
+                // A sidecar keeps its extension in both id and name, so it can
+                // never be mistaken for the layout it sits beside, and it is
+                // NOT put in the layouts map — that map answers "which template
+                // renders this", and a sidecar renders nothing.
+                if (sidecarPaths.includes(relativePath)) {
+                    const chksum = await gateChecksum(uri, id, { priorChecksums })
+                    if (chksum === null) { stats.skipped++; continue }
+                    await createEntity({
+                        id, uri, collection,
+                        type: 'sidecar',
+                        name: relativePath,
+                        content: await readLayoutContent(uri),
+                        checksum: chksum,
+                    })
+                    stats.emitted++
+                    continue
+                }
+
                 const name = relativePath.replace(path.extname(relativePath), '')
                 const chksum = await gateChecksum(uri, id, {
                     priorChecksums,

package/lib/mcp.js

@@ -566,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

package/package.json

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

@@ -373,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')

package/test/unit.test.js

@@ -1042,12 +1042,47 @@ describe('layouts plugin: a sidecar is a tracked input (layouts#4)', () => {
         assert.notEqual(before.checksums.post, after.checksums.post)
     })
 
-    it('does not make an entity out of a sidecar', async () => {
-        // Giving it one would put JS source in the catalog, and via onSync's
-        // id-stripping produce a phantom /layouts/page beside the real
-        // /layouts/page.liquid.
+    it('catalogues a sidecar as an entity of its own', async () => {
+        // A sidecar is where a site's data layer lives, and it used to be the
+        // one source file no tool could read, search or resolve: an agent could
+        // see what a template does but not what feeds it.
         const { emitted } = await scan({ 'page.liquid': '<p>x</p>', 'page.js': 'export const load = () => ({})' })
-        assert.deepEqual(emitted.map(e => e.id).sort(), ['/layouts/page.liquid'])
+        assert.deepEqual(emitted.map(e => e.id).sort(), ['/layouts/page.js', '/layouts/page.liquid'])
+    })
+
+    it('keeps the .js, so a sidecar cannot be mistaken for its layout', async () => {
+        // The original objection to cataloguing it: stripping the extension
+        // produces a phantom /layouts/page beside the real
+        // /layouts/page.liquid, and `page` is how layouts are resolved.
+        const { emitted } = await scan({ 'page.liquid': '<p>x</p>', 'page.js': 'export const load = () => ({})' })
+        const sidecar = emitted.find(e => e.id === '/layouts/page.js')
+        assert.equal(sidecar.name, 'page.js', 'the name keeps its extension too')
+        assert.equal(sidecar.type, 'sidecar')
+        assert.ok(!emitted.some(e => e.id === '/layouts/page'), 'no phantom')
+    })
+
+    it('carries the source, so it can be read and searched', async () => {
+        const source = 'export const load = () => ({ children: [] })'
+        const { emitted } = await scan({ 'page.liquid': '<p>x</p>', 'page.js': source })
+        assert.equal(emitted.find(e => e.id === '/layouts/page.js').content, source)
+    })
+
+    it('does not put a sidecar in the layouts name map', async () => {
+        // That map answers "which template renders this". A sidecar renders
+        // nothing, and an entry there would shadow a real layout called `page`.
+        await withTempWorking(async (workingFolder) => {
+            const h = createHarness({ options: { workingFolder, outputFolder: path.join(workingFolder, 'out') } })
+            await mkdir(path.join(workingFolder, 'layouts'), { recursive: true })
+            await writeFile(path.join(workingFolder, 'layouts', 'page.liquid'), '<p>x</p>')
+            await writeFile(path.join(workingFolder, 'layouts', 'page.js'), 'export const load = () => ({})')
+            layouts()(h.core)
+            await h.runHook('loaded')
+            await h.runHook('import')
+            const map = h.runtime.state.layouts.layouts
+            assert.ok(map.page, 'the real layout is there')
+            assert.equal(map.page.id, '/layouts/page.liquid')
+            assert.equal(map['page.js'], undefined, 'the sidecar is not')
+        })
     })
 
     it('still treats a JS-AUTHORED layout as a layout, not a sidecar', async () => {