mikser-io-layouts 2.4.1 → 2.5.0

package/index.js

@@ -27,6 +27,7 @@ import {
 import { createInspect } from './lib/inspect.js'
 import { createOnProcessed } from './lib/matching.js'
 import { createOnBeforeRender } from './lib/assembly.js'
+import { installSidecarModuleHook } from './lib/sidecar-modules.js'
 import { registerMcpTools } from './lib/mcp.js'
 
 export function layouts(userOptions = {}) {
@@ -207,6 +208,12 @@ export function layouts(userOptions = {}) {
             logger.debug('Layouts folder: %s', runtime.options.layoutsFolder)
             await mkdir(runtime.options.layoutsFolder, { recursive: true })
 
+            // Keyed by the shared sidecar digest, so a module a sidecar
+            // imports is re-evaluated when any .js under this folder changes
+            // and served from cache when none has. Without it only the
+            // sidecar entry point reloads.
+            installSidecarModuleHook({ layoutsFolder: runtime.options.layoutsFolder, logger })
+
             watch(collection, runtime.options.layoutsFolder)
 
             // Rebuild the in-memory layouts map from the catalog. Indexed

package/lib/assembly.js

@@ -27,6 +27,7 @@ import {
     useDatabase,
 } from 'mikser-io'
 import { compileDestinationTemplate, sanitizeDestination, primaryDestination } from './destination.js'
+import { setSidecarStamp, sidecarHookInstalled } from './sidecar-modules.js'
 
 export function createOnBeforeRender({
     runtime, useLogger, useJournal,
@@ -240,7 +241,19 @@ export function createOnBeforeRender({
                 const sidecarTrack = createTrack({ partial: false })
                 if (existsSync(sidecarPath)) {
                     try {
-                        ({ load, plugins = [] } = await import(`${sidecarPath}?stamp=${Date.now()}`))
+                        // Stamp = the shared sidecar digest, so the URL
+                        // changes exactly when some .js under layoutsFolder
+                        // does. With the resolve hook installed that stamp
+                        // also reaches the sidecar's own imports; without it
+                        // only the entry reloads, so fall back to a
+                        // per-render stamp to keep at least that much.
+                        const stamp = entity.layout.inputs?.shared || ''
+                        setSidecarStamp(stamp)
+                        const entryStamp = sidecarHookInstalled() ? stamp : Date.now();
+                        // Semicolon above is load-bearing: without it the
+                        // parenthesised destructuring assignment below reads
+                        // as a CALL of the preceding expression.
+                        ({ load, plugins = [] } = await import(`${sidecarPath}?stamp=${entryStamp}`))
                     } catch (err) {
                         logger.error('Layout sidecar %s failed to load: %s', sidecarPath.replace(runtime.options.workingFolder + '/', ''), err.message)
                         throw err

package/lib/matching.js

@@ -22,7 +22,7 @@ import path from 'node:path'
 
 import _ from 'lodash'
 import { primaryDestination } from './destination.js'
-import { reportWarning } from 'mikser-io'
+import { reportWarning, isFullCycle } from 'mikser-io'
 
 export function createOnProcessed({
     runtime, useLogger, useJournal,
@@ -47,6 +47,13 @@ export function createOnProcessed({
         if (matchTally.reported) return
         const patterns = Object.keys(options.match || {})
         if (!patterns.length || !matchTally.evaluated) return
+        // Only when the cycle evaluated everything. An incremental run
+        // re-evaluates whatever changed, so a healthy pattern matches none of
+        // the two entities in a settled build — and a warning that fires on
+        // every build is one the reader filters, which takes the real
+        // instance with it. The message already pointed at --force to check
+        // the whole catalog; that is the condition, not a footnote.
+        if (!isFullCycle(runtime)) return
         matchTally.reported = true
 
         for (const pattern of patterns) {
@@ -68,8 +75,7 @@ export function createOnProcessed({
             })
             logger.warn(
                 'Layout pattern %j (→ %j) matched none of the %d entities evaluated. ' +
-                'It is matched against entity.%s%s. On an incremental run unchanged ' +
-                'entities are not re-evaluated; use --force to check the whole catalog.',
+                'It is matched against entity.%s%s.',
                 pattern, options.match[pattern], matchTally.evaluated,
                 onName ? 'name' : 'id',
                 onName ? '' : " — prefix a pattern with '@/' to match entity.name instead, " +

package/lib/sidecar-modules.js

@@ -0,0 +1,82 @@
+// Module identity for layout sidecars.
+//
+// Node's ESM registry keys modules by resolved URL, so a `?stamp=` on the
+// sidecar's own URL re-evaluates the ENTRY and nothing else: its
+// `import './lib/context.js'` resolves to a URL with no query, which the
+// registry answers from cache for the life of the process. Under --watch
+// that leaves an edited helper stale after the first reload:
+//
+//     import('/layouts/page.js?stamp=1')   // page.js fresh, context.js read
+//     …edit lib/context.js…
+//     import('/layouts/page.js?stamp=2')   // page.js fresh, context.js CACHED
+//
+// The stamp has to reach every module in the subgraph, which a resolve
+// hook can do and an entry-point query cannot. `module.registerHooks`
+// (Node 22.15+) runs synchronously in-thread, so the hook can append the
+// current stamp to anything resolving under layoutsFolder.
+//
+// Consequences worth stating, because they are what make this safe to
+// leave installed:
+//
+//   - the stamp is the shared sidecar digest, so an unchanged tree keeps
+//     resolving to the same URLs and nothing is re-parsed. `Date.now()`
+//     re-parsed the entry on every render.
+//   - only paths under layoutsFolder are touched; the engine's own
+//     modules and node_modules resolve untouched.
+//   - a URL that already carries a query is left alone, so the entry
+//     import's explicit stamp is not doubled.
+//
+// Where the hook is unavailable, sidecars still reload and their imports
+// still go stale — the pre-existing behaviour — and that is said out loud
+// once rather than left to be discovered.
+
+import module from 'node:module'
+import { pathToFileURL } from 'node:url'
+
+// Feature-detected rather than imported by name: `import { registerHooks }`
+// throws at parse time on a Node that does not export it.
+const canRegisterHooks = typeof module.registerHooks === 'function'
+
+let installed = false
+let rootUrl = null
+let stamp = ''
+
+// Register once per process. Idempotent, and a no-op on a Node without
+// registerHooks — callers read the return value to decide what to use as
+// the entry stamp.
+export function installSidecarModuleHook({ layoutsFolder, logger }) {
+    if (installed) return true
+    if (!layoutsFolder) return false
+    if (!canRegisterHooks) {
+        logger?.debug(
+            'Sidecar modules: node:module.registerHooks is unavailable (Node %s), so a module a '
+            + 'sidecar imports keeps its first-loaded copy for the life of the process. Editing one '
+            + 'under --watch needs a restart with --force. Node 22.15+ removes the limitation.',
+            process.version,
+        )
+        return false
+    }
+    rootUrl = pathToFileURL(layoutsFolder).href.replace(/\/?$/, '/')
+    module.registerHooks({
+        resolve(specifier, context, nextResolve) {
+            const resolved = nextResolve(specifier, context)
+            if (!resolved?.url?.startsWith(rootUrl)) return resolved
+            if (resolved.url.includes('?')) return resolved
+            return { ...resolved, url: `${resolved.url}?stamp=${stamp}` }
+        },
+    })
+    installed = true
+    return true
+}
+
+// The stamp every subsequent resolution under layoutsFolder is keyed by.
+// Set from the layout's `inputs.shared` digest before importing its
+// sidecar. Every layout in a cycle carries the same shared digest, so
+// concurrent renders set the same value and there is nothing to race.
+export function setSidecarStamp(next) {
+    stamp = next ?? ''
+}
+
+export function sidecarHookInstalled() {
+    return installed
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-layouts",
-  "version": "2.4.1",
+  "version": "2.5.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",
@@ -18,7 +18,7 @@
   },
   "homepage": "https://github.com/almero-digital-marketing/mikser-io-layouts#readme",
   "peerDependencies": {
-    "mikser-io": "^9.18.0"
+    "mikser-io": "^9.20.0"
   },
   "dependencies": {
     "globby": "^14.0.0",

package/test/sidecar-modules.test.js

@@ -0,0 +1,100 @@
+// Module identity for layout sidecars.
+//
+// Node's ESM registry keys modules by resolved URL. A `?stamp=` on the
+// sidecar's own URL therefore re-evaluates the ENTRY and nothing else:
+// its `import './lib/context.js'` resolves to a URL with no query and is
+// answered from cache for the life of the process.
+//
+// Under --watch that shows up as a helper that propagates one edit and
+// then freezes, and the damage outlives the process: the last render ran
+// with the stale module, produced bytes that happened to match what was
+// on disk, skipped the write, and recorded "these inputs produced those
+// bytes". Revert the source and every check agrees with every other and
+// all of them are wrong about the site — only --force recovers.
+//
+// These tests run in ONE process with a real edit between imports, which
+// is the only place the bug exists. A scenario test spawns a fresh
+// process per build, so its module cache is empty every time and the
+// staleness cannot appear.
+
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+import { installSidecarModuleHook, setSidecarStamp, sidecarHookInstalled } from '../lib/sidecar-modules.js'
+
+describe('sidecar module identity', () => {
+    let root, layoutsFolder
+
+    before(async () => {
+        root = await mkdtemp(path.join(tmpdir(), 'mikser-sidecar-'))
+        layoutsFolder = path.join(root, 'layouts')
+        await mkdir(path.join(layoutsFolder, 'lib'), { recursive: true })
+        // page.js is the sidecar; lib/context.js is the module it imports.
+        await writeFile(path.join(layoutsFolder, 'lib', 'context.js'),
+            "export const icon = 'filter.svg'\n")
+        await writeFile(path.join(layoutsFolder, 'page.js'),
+            "import { icon } from './lib/context.js'\nexport const load = () => ({ icon })\n")
+        installSidecarModuleHook({ layoutsFolder, logger: { debug() {} } })
+    })
+
+    after(async () => { await rm(root, { recursive: true, force: true }) })
+
+    const importSidecar = async (stamp) => {
+        setSidecarStamp(stamp)
+        const mod = await import(`${path.join(layoutsFolder, 'page.js')}?stamp=${stamp}`)
+        return mod.load().icon
+    }
+
+    it('installs on a Node that supports registerHooks', () => {
+        // The fix depends on node:module.registerHooks (22.15+). If this
+        // fails the rest is testing the fallback, so it is worth stating.
+        assert.equal(sidecarHookInstalled(), true, `not installed on ${process.version}`)
+    })
+
+    it('reads the helper through the sidecar', async () => {
+        assert.equal(await importSidecar('digest-1'), 'filter.svg')
+    })
+
+    it('picks up an edit to the IMPORTED module when the stamp changes', async () => {
+        await writeFile(path.join(layoutsFolder, 'lib', 'context.js'),
+            "export const icon = 'x.svg'\n")
+        assert.equal(
+            await importSidecar('digest-2'), 'x.svg',
+            'a transitive import must be re-evaluated when the stamp changes',
+        )
+    })
+
+    it('picks up a NOVEL value on the second edit', async () => {
+        // The case that proves it is not the write-skip masking a reload:
+        // a value never seen before cannot match anything already on disk.
+        await writeFile(path.join(layoutsFolder, 'lib', 'context.js'),
+            "export const icon = 'plus.svg'\n")
+        assert.equal(await importSidecar('digest-3'), 'plus.svg')
+    })
+
+    it('returns to the original value when the source is reverted', async () => {
+        await writeFile(path.join(layoutsFolder, 'lib', 'context.js'),
+            "export const icon = 'filter.svg'\n")
+        assert.equal(await importSidecar('digest-4'), 'filter.svg')
+    })
+
+    it('does NOT re-evaluate when the stamp is unchanged', async () => {
+        // The stamp is the shared digest, so an unchanged tree must resolve
+        // to the same URLs and re-parse nothing. Editing behind an unchanged
+        // stamp is not a real scenario — the digest would have moved — but it
+        // is how "cached" is observable.
+        const first = await importSidecar('digest-stable')
+        await writeFile(path.join(layoutsFolder, 'lib', 'context.js'),
+            "export const icon = 'never-seen.svg'\n")
+        assert.equal(
+            await importSidecar('digest-stable'), first,
+            'an unchanged stamp must serve the cached module',
+        )
+        // Leave the tree as the other tests expect.
+        await writeFile(path.join(layoutsFolder, 'lib', 'context.js'),
+            "export const icon = 'filter.svg'\n")
+    })
+})

package/test/unit.test.js

@@ -124,12 +124,16 @@ describe('layouts plugin', () => {
     })
 
     it('warns once about a match pattern that selected nothing', async () => {
-        // A pattern selecting zero entities used to be completely silent —
-        // no warn, no debug — so a typo'd or missing language segment lost a
-        // whole section while the build went green.
+        // A pattern selecting zero entities is otherwise completely silent —
+        // no warn, no debug — so a typo'd or missing language segment loses a
+        // whole section while the build goes green.
+        //
+        // `force` makes this a full cycle. The warning is gated on that,
+        // because on an incremental run the evaluated set is whatever changed
+        // and a healthy pattern legitimately matches none of it.
         await withTempWorking(async (workingFolder) => {
             const h = createHarness({
-                options: { workingFolder, outputFolder: path.join(workingFolder, 'out') },
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
             })
             layouts({
                 autoLayouts: false,
@@ -161,7 +165,42 @@ describe('layouts plugin', () => {
             assert.ok(!text.includes("'post'"), 'must not name the pattern that DID match')
             assert.match(text, /matched against entity\.id/, 'names the field this pattern is matched against')
             assert.match(text, /'@\/'/, "points at the '@/' prefix for name matching")
-            assert.match(text, /--force/, 'tells the reader how to check the whole catalog')
+            // No longer advises --force: the warning only fires on a full
+            // cycle now, so the advice would be telling the reader to do what
+            // they have already done.
+            assert.ok(!text.includes('--force'), 'does not advise what the reader just did')
+        })
+    })
+
+    it('stays silent about an unmatched pattern on an incremental cycle', async () => {
+        // The inverse of the test above, and the reason the gate exists. An
+        // incremental run re-evaluates only what changed, so a pattern that
+        // matches plenty of documents matches none of the two entities in a
+        // settled build. Warning there fires on every healthy build, and a
+        // warning that always fires is one the reader filters out — taking
+        // the real instance with it.
+        await withTempWorking(async (workingFolder) => {
+            const h = createHarness({
+                // No `force`, no `firstRun`, no cache invalidation.
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out') },
+            })
+            layouts({ autoLayouts: false, match: { 'nonesuch/*': 'section' } })(h.core)
+            await h.runHook('loaded')
+            await h.runSync('layouts', { action: 'create', context: { relativePath: 'section.hbs' } })
+
+            const doc = {
+                id: '/documents/post.md', name: 'post', collection: 'documents',
+                type: 'document', format: 'md', meta: {},
+            }
+            h.journal.push({ id: 1, entity: doc, operation: 'create', context: {}, options: {}, output: null })
+            await h.runHook('processed', { aborted: false })
+
+            const warnings = h.logs.filter(l =>
+                l.level === 'warn' && l.args.join(' ').includes('Layout pattern'))
+            assert.deepEqual(
+                warnings, [],
+                'an incremental cycle cannot support the conclusion, so it must not draw it',
+            )
         })
     })
 
@@ -170,7 +209,7 @@ describe('layouts plugin', () => {
         // noise, so it is reported once per process.
         await withTempWorking(async (workingFolder) => {
             const h = createHarness({
-                options: { workingFolder, outputFolder: path.join(workingFolder, 'out') },
+                options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
             })
             layouts({ autoLayouts: false, match: { 'nonesuch/*': 'section' } })(h.core)
             await h.runHook('loaded')