mikser-io-layouts 2.12.0 → 2.15.0

package/index.js

@@ -245,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
@@ -310,8 +311,43 @@ export function layouts(userOptions = {}) {
             // 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 allScripts = await globby('**/*.js', { cwd: runtime.options.layoutsFolder })
+            const sidecarPaths = allScripts.filter(isSidecarScript)
+
+            // A `.js` that nothing will ever read.
+            //
+            // A sidecar is named after the LAYOUT, and a layout's name drops
+            // BOTH extensions: `robots.txt.liquid` is the layout `robots`, so
+            // its sidecar is `robots.js`. Write `robots.txt.js` and it is
+            // claimed by nothing — isSidecarScript rejects it because
+            // stripping `.js` leaves `.txt`, and the layout glob ignores every
+            // `.js` outright. The file is simply invisible: it does not fail,
+            // it never runs, and the layout renders with empty `data`.
+            //
+            // Downstream that shipped `Sitemap: /sitemap.xml` as a relative
+            // reference in a robots.txt — which in a robots.txt means nothing
+            // — on a green build.
+            //
+            // Only when a layout sits beside it under the same stem, which is
+            // what makes this a misnaming rather than a stray file. A dotted
+            // module a sidecar imports (`lib/data.json.js`) is claimed by
+            // nothing either, and is nobody's mistake; flagging it would be
+            // the noise that gets this line filtered out.
+            for (const script of allScripts) {
+                if (isSidecarScript(script)) continue
+                const stem = script.replace(/\.js$/, '')
+                const layout = paths.find(candidate =>
+                    candidate === stem || candidate.startsWith(`${stem}.`))
+                if (!layout) continue
+                const name = path.basename(stem, path.extname(stem))
+                logger.warn({ code: 'layout-sidecar-misnamed', script, layout },
+                    'layouts/%s is not loaded as a sidecar and nothing else reads it. A sidecar is '
+                    + 'named after the LAYOUT, and %s is the layout `%s` — both extensions are '
+                    + 'dropped — so its sidecar has to be %s.js. The layout renders with empty data '
+                    + 'until it is renamed.',
+                    script, layout, name, path.join(path.dirname(stem) === '.' ? '' : path.dirname(stem), name))
+            }
+
             const inputs = await sidecarInputs()
             const scanned = new Set()
             const stats = { emitted: 0, skipped: 0, deleted: 0 }
@@ -380,6 +416,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/lib/assembly.js

@@ -27,10 +27,21 @@ import {
     observeConsumed,
     queryContext,
     useDatabase,
+    reportError,
 } from 'mikser-io'
 import { compileDestinationTemplate, sanitizeDestination, primaryDestination } from './destination.js'
 import { setSidecarStamp, sidecarHookInstalled } from './sidecar-modules.js'
 
+// What the sidecar actually returned, for a message a reader can act on.
+// `[object Object]` and `` are the two least useful things to print here.
+function describePages(value) {
+    if (Array.isArray(value)) return `an array of ${value.length}`
+    if (value === null) return 'null'
+    if (typeof value === 'object') return `an object with keys ${Object.keys(value).join(', ') || '(none)'}`
+    if (typeof value === 'number') return `the number ${value}`
+    return `a ${typeof value} (${JSON.stringify(value)})`
+}
+
 export function createOnBeforeRender({
     runtime, useLogger, useJournal,
     findById, findEntity, findEntities,
@@ -350,6 +361,56 @@ export function createOnBeforeRender({
                     : null
 
                 if (data?.pages) {
+                    // `pages` is the pagination COUNT, and only a count.
+                    //
+                    // The guard above is truthiness and the loop below is
+                    // `page < data.pages`, so a sidecar returning anything
+                    // truthy that is not a positive number passed the first
+                    // and ran zero times in the second. `{ pages: [] }`
+                    // coerces to 0; `{ pages: [{…}] }` coerces to NaN. Both
+                    // produced NO page: no file, no error, no warning, not
+                    // counted in `Rendered:`, no manifest snapshot — a green
+                    // build with the page simply absent, and --audit-output
+                    // cannot see it either because an entity that never
+                    // rendered has no snapshot to be missing.
+                    //
+                    // `pages` is also the obvious name for the list in a
+                    // sitemap, which is exactly where it lands.
+                    //
+                    // Thrown rather than reinterpreted. The key has one
+                    // meaning; guessing a second from the value's type is how
+                    // a name comes to mean two things depending on what you
+                    // put in it. This fails the render for this entity, which
+                    // is counted, recorded and named.
+                    if (!Number.isInteger(data.pages) || data.pages < 1) {
+                        // Reported, not thrown. This runs in onBeforeRender,
+                        // a lifecycle hook rather than a render, so an
+                        // exception here tears the whole build down with a
+                        // stack trace — one mistyped sidecar stopping every
+                        // other page, which trades a silent failure for a
+                        // total one.
+                        //
+                        // reportError, not logger.error. This entity could
+                        // not be turned into output, which is what a render
+                        // error IS — so it is counted in `errors`, recorded in
+                        // mikser_failures, and makes a one-shot build exit 1.
+                        // A coded logger.error would register as a fault, and
+                        // a fault leaves the build green: "🟢 Mikser completed"
+                        // beside a red line and exit 0 is the same green build
+                        // the report was about.
+                        const message =
+                            `sidecar returned \`pages\` as ${describePages(data.pages)}. `
+                            + '`pages` is the pagination COUNT — a positive integer — and is reserved '
+                            + 'in the data a layout receives, so a list cannot be passed under it. '
+                            + 'Rename it (`items`, `entries`, `urls`) and the layout renders once '
+                            + 'with that list available.'
+                        reportError(entity, new Error(message), { layout: entity.layout?.name ?? null })
+                        logger.error({ code: 'layout-pages-not-a-count', id: entity.id,
+                            layout: entity.layout?.name ?? null },
+                            'Layout %s: %s — %s produced no output.',
+                            entity.layout?.name ?? '?', message, entity.id)
+                        continue
+                    }
                     if (!_.endsWith(entity.name, entity.format)) {
                         // Loop bound is `< data.pages` (not `data.pages - 1`).
                         // With 4 pages and the old bound, iteration only ran
@@ -409,6 +470,19 @@ export function createOnBeforeRender({
                                  sidecarMetaReads: [...(sidecarTrack.metaReads ?? [])],
                                  sidecarConsumedReads: [...(sidecarTrack.consumedReads ?? [])].map(([k, v]) => [k, [...v]]) })
                         }
+                    } else {
+                        // Pagination was asked for, and nothing was queued.
+                        //
+                        // The guard exists so an entity whose name already
+                        // carries its format is not expanded twice, but it
+                        // shares the shape that made the type confusion above
+                        // so expensive: no task, no message, output absent on
+                        // a green build. Whatever the right handling is, it is
+                        // not silence.
+                        logger.warn({ code: 'layout-pagination-skipped', id: entity.id },
+                            'Pagination was requested for %s (pages: %d) but its name already ends '
+                            + 'with its format (%s), so no page was produced.',
+                            entity.id, data.pages, entity.format)
                     }
                 } else {
                     // Same derivation onProcessed persists onto the catalog

package/package.json

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