mikser-io-layouts 2.11.2 → 2.13.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
             }
@@ -242,12 +245,13 @@ export function layouts(userOptions = {}) {
         //
         // Two components:
         //   own     — the layout's own sidecar, `<name>.js`
-        //   shared  — every OTHER .js under the folder, as one digest
+        //   shared  — ALL sidecar scripts under the folder, as one digest
+        //             (its own included; `own` just names it separately)
         //
         // `shared` is coarse on purpose: a sidecar's own imports
         // (layouts/lib/context.js and friends) would otherwise need a module
-        // graph walk. Treating any shared .js change as invalidating every
-        // layout is what the folder can afford — tens of files, not
+        // graph walk. One global digest means any sidecar change invalidates
+        // EVERY layout, which is what the folder can afford — tens of files, not
         // thousands — and it is predictable, which a partial graph walk
         // would not be.
         // NOT every .js under the folder is a sidecar. `post.hbs.js` is a
@@ -292,6 +296,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 +330,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,
@@ -342,6 +381,35 @@ export function layouts(userOptions = {}) {
                     },
                 }
                 Object.assign(layout, await getFormatInfo(relativePath))
+
+                // Two files can resolve to ONE layout name, and this map is
+                // keyed by name — so the second one silently replaced the
+                // first and which one won depended on scan order.
+                //
+                // getFormatInfo strips the whole compound extension:
+                // sitemap.xml.liquid, sitemap.liquid and sitemap.xml.js are
+                // all named `sitemap`. A document asking for `layout: sitemap`
+                // then got whichever landed last, and if that was a `js`
+                // template it rendered nothing — no error, no warning, the
+                // build green and the page absent. Reported from a real
+                // migration, where the same shape worked for one layout and
+                // not another and no rule could be found, because the rule was
+                // directory order.
+                //
+                // Not resolved here, because picking a winner would be
+                // guessing at intent. Said out loud instead, naming both
+                // files, which is the thing that was missing.
+                const clash = layouts[layout.name]
+                if (clash && clash.id !== layout.id) {
+                    logger.warn(
+                        { code: 'layout-name-collision', name: layout.name, files: [clash.uri, layout.uri] },
+                        'Layouts %j is claimed by two files — %s and %s. Both reduce to the same layout name, '
+                        + 'so one replaces the other and which one wins is directory order. A document asking '
+                        + 'for this layout may render with the wrong template, or with a `js` template that '
+                        + 'emits nothing at all. Rename one of them.',
+                        layout.name, clash.uri, layout.uri)
+                }
+
                 layouts[layout.name] = layout
                 await createEntity(layout)
                 stats.emitted++

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-layouts",
-  "version": "2.11.2",
+  "version": "2.13.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/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 () => {