mikser-io-layouts 11.4.0 → 11.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -246,6 +246,38 @@ Everything else means "you may want to look", never "this is broken": `missingOp
246
246
 
247
247
  Yes — layout file changes trigger re-rendering of dependent documents via the refs system.
248
248
 
249
+ ### What a sidecar imports is an input too
250
+
251
+ A layout's `.js` sidecar is part of that layout's checksum, and so is every
252
+ `.js` file under the layouts folder — editing `layouts/lib/context.js`
253
+ re-renders the layouts that depend on it.
254
+
255
+ Sidecars also import helpers from **outside** the layouts folder, which is
256
+ where code shared with `mikser.config.js` or a script lives. Those cannot be
257
+ globbed, because the set is whatever a sidecar happens to import, so they are
258
+ recorded as they resolve: the first build that loads a sidecar learns its
259
+ import graph, stores it in the runtime folder, and from then on editing one of
260
+ those modules re-renders the layouts that reach it, under `--watch` and on a
261
+ plain rebuild alike. This is the same bargain `readFile` and `glob` tracking
262
+ make — an edge is learned from the run that used it.
263
+
264
+ Two consequences worth knowing:
265
+
266
+ - **Only project files count.** `node_modules` and anything outside the
267
+ working folder are left alone: they are not what you are editing, and
268
+ hashing them on every scan would cost the whole tree. Bump the dependency
269
+ and rebuild.
270
+ - **A module in a sidecar's import graph is re-evaluated when layout code
271
+ changes.** That is what makes an edit take effect in a long-running
272
+ `--watch` process rather than serving the copy loaded at boot. It also means
273
+ a process-wide singleton — a connection pool, a cache — does not belong in
274
+ one. Import it lazily inside the function that needs it, or keep it out of
275
+ the graph.
276
+
277
+ The first build after upgrading discovers the graph and **does not** re-render
278
+ anything for it: each module is stored with the checksum it already had, so
279
+ only a later edit moves anything.
280
+
249
281
  ## Href lookups
250
282
 
251
283
  The href resolution path goes through `runtime.lookupHref(href)` — a sync function that hits the `meta_href` index on `mikser_entities`. Render workers open their own read-only sqlite handle on first task and call the same primitive; templates stay sync. The `href` render plugin uses this; layout-side code can call it directly.
package/index.js CHANGED
@@ -24,12 +24,14 @@ import {
24
24
  writeOutput, reportUnchanged,
25
25
  provideService,
26
26
  cliOption,
27
+ watchFolder,
27
28
  } from 'mikser-io'
28
29
 
29
30
  import { createInspect } from './lib/inspect.js'
30
31
  import { createOnProcessed } from './lib/matching.js'
31
32
  import { createOnBeforeRender } from './lib/assembly.js'
32
- import { installSidecarModuleHook, loadSidecarModule } from './lib/sidecar-modules.js'
33
+ import { installSidecarModuleHook, loadSidecarModule, recordedSidecarModules } from './lib/sidecar-modules.js'
34
+ import { createSidecarGraph } from './lib/sidecar-graph.js'
33
35
  import { registerMcpTools } from './lib/mcp.js'
34
36
 
35
37
  export function layouts(userOptions = {}) {
@@ -57,6 +59,8 @@ export function layouts(userOptions = {}) {
57
59
  renderEntities,
58
60
  onComplete,
59
61
  onSync,
62
+ onFinalized,
63
+ triggeredHook,
60
64
  matchEntity,
61
65
  changeExtension,
62
66
  getFormatInfo,
@@ -131,8 +135,17 @@ export function layouts(userOptions = {}) {
131
135
  })
132
136
 
133
137
  onSync(collection, async ({ action, context }) => {
134
- if (!context.relativePath) return false
135
138
  const logger = useLogger()
139
+ // A module a sidecar imports from outside the layouts folder.
140
+ // It has no relativePath because it is not in this collection and
141
+ // is nobody's entity — it is an INPUT, so the response is the same
142
+ // rescan a sidecar edit gets.
143
+ if (context.module) {
144
+ logger.debug('Layouts module changed (%s) — rescanning layouts', context.module)
145
+ await rescanLayouts()
146
+ return
147
+ }
148
+ if (!context.relativePath) return false
136
149
  const { relativePath } = context
137
150
 
138
151
  // A .js file under the layouts folder is a SIDECAR (or something
@@ -245,9 +258,25 @@ export function layouts(userOptions = {}) {
245
258
  // imports is re-evaluated when any .js under this folder changes
246
259
  // and served from cache when none has. Without it only the
247
260
  // sidecar entry point reloads.
248
- installSidecarModuleHook({ layoutsFolder: runtime.options.layoutsFolder, logger })
261
+ installSidecarModuleHook({
262
+ layoutsFolder: runtime.options.layoutsFolder,
263
+ workingFolder: runtime.options.workingFolder,
264
+ logger,
265
+ })
249
266
 
250
267
  watch(collection, runtime.options.layoutsFolder)
268
+ await watchSidecarModules()
269
+
270
+ // The graph is only observable once a sidecar has loaded, which
271
+ // is after this cycle's scan — so it is stored at the end of the
272
+ // cycle for the next one to read. Storing it is not a render:
273
+ // each path is kept with the checksum it has right now, so
274
+ // nothing is reported as changed by being noticed.
275
+ onFinalized(async () => {
276
+ if (await sidecarGraph.discover(recordedSidecarModules())) {
277
+ await watchSidecarModules()
278
+ }
279
+ })
251
280
 
252
281
  // Rebuild the in-memory layouts map from the catalog. Indexed
253
282
  // on `collection`, returns the small layouts set — typically a
@@ -312,6 +341,33 @@ export function layouts(userOptions = {}) {
312
341
  return path.isAbsolute(name) ? name : path.join(runtime.options.workingFolder, name)
313
342
  }
314
343
 
344
+ const sidecarGraph = createSidecarGraph({ runtime, logger: useLogger })
345
+ let watchedModules = null
346
+
347
+ // Watch what the sidecars import from outside the layouts folder.
348
+ //
349
+ // `watch(collection, layoutsFolder)` covers the folder and nothing
350
+ // else, so an edit to a helper one level up produced no event and no
351
+ // cycle — the digest below would have caught it, but only once
352
+ // something else started a build. A plain folder watcher plus a
353
+ // TRIGGER is all this needs: the sync handler rescans, the rescan
354
+ // re-emits whichever layouts moved, and their dependents re-render.
355
+ async function watchSidecarModules() {
356
+ if (runtime.options.watch !== true) return
357
+ const files = await sidecarGraph.tracked()
358
+ if (watchedModules && _.isEqual(watchedModules.files, files)) return
359
+ await watchedModules?.watcher?.close()
360
+ watchedModules = files.length
361
+ ? {
362
+ files,
363
+ watcher: watchFolder(files, async (event, fullPath) => {
364
+ useLogger().debug('Layouts module changed (%s) — triggering a cycle', fullPath)
365
+ await triggeredHook(collection, { module: fullPath })
366
+ }),
367
+ }
368
+ : { files, watcher: null }
369
+ }
370
+
315
371
  async function sidecarInputs() {
316
372
  const scriptPaths = (await globby('**/*.js', { cwd: layoutsFolderNow() }))
317
373
  .filter(isSidecarScript)
@@ -322,6 +378,14 @@ export function layouts(userOptions = {}) {
322
378
  own.set(rel.replace(/\.js$/, ''), sum)
323
379
  shared.push(`${rel}:${sum}`)
324
380
  }
381
+ // Fold in what the sidecars imported from outside this folder.
382
+ // Recorded during the previous cycle's renders and persisted at
383
+ // the end of it — a one-shot build exits between the render that
384
+ // observes the graph and the scan that would use it, so keeping
385
+ // it in memory would mean it was never used at all.
386
+ const moduleDigest = await sidecarGraph.digest()
387
+ if (moduleDigest) shared.push(`modules:${moduleDigest}`)
388
+ await watchSidecarModules()
325
389
  return { own, sharedDigest: shared.length ? checksumOf(shared.join('\n')) : '' }
326
390
  }
327
391
 
package/lib/matching.js CHANGED
@@ -22,7 +22,22 @@ import path from 'node:path'
22
22
 
23
23
  import _ from 'lodash'
24
24
  import { primaryDestination } from './destination.js'
25
- import { isFullCycle } from 'mikser-io'
25
+ import { isFullCycle, readFrontMatter } from 'mikser-io'
26
+
27
+ // A layout as synced, with its front-matter block lifted off — attributes
28
+ // onto meta so `destination:` and `match:` still work, body as the template.
29
+ // Returns the entry untouched when there is no front matter, and when the
30
+ // block cannot be parsed: a renderer showing the author their own malformed
31
+ // YAML is more use than one silently dropping it.
32
+ function withoutFrontMatter(entry) {
33
+ const parsed = readFrontMatter(entry?.content)
34
+ if (!parsed || parsed.error) return entry
35
+ return {
36
+ ...entry,
37
+ meta: { ...(entry.meta ?? {}), ...parsed.attributes },
38
+ content: parsed.body,
39
+ }
40
+ }
26
41
 
27
42
  export function createOnProcessed({
28
43
  runtime, useLogger, useJournal,
@@ -122,7 +137,21 @@ export function createOnProcessed({
122
137
  async function resolveLayout(name) {
123
138
  const stateEntry = layouts[name]
124
139
  if (!stateEntry) return undefined
125
- return (await findEntity({ id: stateEntry.id })) || stateEntry
140
+ const fromCatalog = await findEntity({ id: stateEntry.id })
141
+ if (fromCatalog) return fromCatalog
142
+ // The catalog has not caught up — a sync race, or a setup where
143
+ // the front-matter plugin has not run. The state map holds the
144
+ // file AS SYNCED, so its content still carries the front-matter
145
+ // block, and handing that to a renderer has now failed twice in
146
+ // two different ways: Handlebars emitted the YAML into the page,
147
+ // and LiquidJS refuses to parse it at all, reporting a syntax
148
+ // error at the front-matter line and taking the layout down.
149
+ //
150
+ // Resolving from the catalog was the fix for the first. This is
151
+ // the same fix for the path that bypasses it — stripping through
152
+ // core's reader rather than a regex here, so there is one
153
+ // implementation of what front matter is.
154
+ return withoutFrontMatter(stateEntry)
126
155
  }
127
156
 
128
157
  // `match:` in a layout's own front-matter — the colocated twin of a
@@ -0,0 +1,115 @@
1
+ // What a sidecar imported last time, kept across runs.
2
+ //
3
+ // The resolve hook records the graph while a sidecar LOADS, which is after
4
+ // the scan that decides whether to render it. So the set this run observed
5
+ // is only useful to the next one, and it has to survive a restart — the
6
+ // reported symptom was that a restart did not help either.
7
+ //
8
+ // It lives beside the other derived state in the runtime folder rather than
9
+ // in the catalog, because the scan needs it before it has read a single
10
+ // layout entity, and because a catalog wipe should not cost a full re-render
11
+ // of every layout that imports a shared helper.
12
+ //
13
+ // DISCOVERY MUST NOT MOVE THE DIGEST. Storing a path and hashing the list
14
+ // would mean the first build after an upgrade re-rendered everything, and
15
+ // again the first time any new helper appeared. So each path is stored WITH
16
+ // the checksum it had when it was discovered, and the digest only moves when
17
+ // a stored checksum stops matching the file. A project whose sidecars import
18
+ // nothing outside the layouts folder has an empty store and a digest of '',
19
+ // which is appended nowhere — its layouts hash exactly as they did before.
20
+
21
+ import path from 'node:path'
22
+ import { mkdir, readFile, writeFile } from 'node:fs/promises'
23
+ import { checksum as fileChecksum, checksumOf } from 'mikser-io'
24
+
25
+ const FILE = 'layouts-modules.json'
26
+
27
+ export function createSidecarGraph({ runtime, logger }) {
28
+ let store = null
29
+
30
+ const storeFile = () => path.join(runtime.options.runtimeFolder, FILE)
31
+
32
+ // null means "not there any more", which is a change like any other.
33
+ const sumOf = async (file) => {
34
+ try {
35
+ return await fileChecksum(file)
36
+ } catch {
37
+ return null
38
+ }
39
+ }
40
+
41
+ const recompute = (modules) => {
42
+ const lines = Object.keys(modules).sort().map(file => `${file}:${modules[file]}`)
43
+ return lines.length ? checksumOf(lines.join('\n')) : ''
44
+ }
45
+
46
+ async function read() {
47
+ if (store) return store
48
+ try {
49
+ store = JSON.parse(await readFile(storeFile(), 'utf8'))
50
+ } catch {
51
+ store = {}
52
+ }
53
+ if (!store.modules || typeof store.modules !== 'object') store.modules = {}
54
+ if (typeof store.digest !== 'string') store.digest = ''
55
+ return store
56
+ }
57
+
58
+ async function write() {
59
+ try {
60
+ await mkdir(path.dirname(storeFile()), { recursive: true })
61
+ await writeFile(storeFile(), JSON.stringify(store, null, 2))
62
+ } catch (err) {
63
+ // Losing the store costs one extra render of every layout, next
64
+ // run. It must not cost the build.
65
+ logger?.().debug('Layouts could not store the sidecar module graph: %s', err.message)
66
+ }
67
+ }
68
+
69
+ return {
70
+ // The value folded into the shared digest. '' when nothing is
71
+ // tracked, so an unaffected project's layouts hash is untouched.
72
+ async digest() {
73
+ const current = await read()
74
+ const files = Object.keys(current.modules)
75
+ if (!files.length) return ''
76
+ let moved = false
77
+ for (const file of files) {
78
+ const sum = await sumOf(file)
79
+ if (sum === current.modules[file]) continue
80
+ moved = true
81
+ // A module that is gone is not an input any more. Dropping it
82
+ // rather than remembering it as missing means a renamed helper
83
+ // costs one rebuild instead of leaving a permanent entry that
84
+ // can never match.
85
+ if (sum === null) delete current.modules[file]
86
+ else current.modules[file] = sum
87
+ }
88
+ if (moved) {
89
+ current.digest = recompute(current.modules)
90
+ await write()
91
+ }
92
+ return current.digest
93
+ },
94
+
95
+ // Paths the resolve hook saw this run. Stored with their CURRENT
96
+ // checksum, so nothing newly discovered is reported as changed.
97
+ async discover(files) {
98
+ const current = await read()
99
+ let added = false
100
+ for (const file of files ?? []) {
101
+ if (Object.hasOwn(current.modules, file)) continue
102
+ const sum = await sumOf(file)
103
+ if (sum === null) continue
104
+ current.modules[file] = sum
105
+ added = true
106
+ }
107
+ if (added) await write()
108
+ return added
109
+ },
110
+
111
+ async tracked() {
112
+ return Object.keys((await read()).modules).sort()
113
+ },
114
+ }
115
+ }
@@ -33,7 +33,7 @@
33
33
  import module from 'node:module'
34
34
  import path from 'node:path'
35
35
  import { existsSync } from 'node:fs'
36
- import { pathToFileURL } from 'node:url'
36
+ import { fileURLToPath, pathToFileURL } from 'node:url'
37
37
 
38
38
  // Feature-detected rather than imported by name: `import { registerHooks }`
39
39
  // throws at parse time on a Node that does not export it.
@@ -42,11 +42,49 @@ const canRegisterHooks = typeof module.registerHooks === 'function'
42
42
  let installed = false
43
43
  let rootUrl = null
44
44
  let stamp = ''
45
+ let projectRoot = null
46
+
47
+ // A sidecar's imports that resolve OUTSIDE the layouts folder.
48
+ //
49
+ // The hook below only knew about `layoutsFolder`, and so did the digest:
50
+ // `layouts/lib/context.js` is globbed into the shared digest and stamped, so
51
+ // editing one re-renders and reloads. `lib/context.js` one level up is the
52
+ // same code doing the same job and got neither — the edit changed nothing,
53
+ // a restart changed nothing, and only `--force` produced the new output.
54
+ // Shared helpers live outside a layouts folder all the time: that is where
55
+ // code shared with the config or a script goes.
56
+ //
57
+ // They cannot be globbed — the set is "whatever a sidecar imports", which
58
+ // is unbounded until something imports it. But the resolve hook sees every
59
+ // resolution as it happens, so the graph is RECORDED while a sidecar loads
60
+ // and read back as an input on the next scan. That is the same bargain
61
+ // `readFile`/`glob` tracking already makes: an edge is known from the run
62
+ // that used it, and invalidates the run after.
63
+ //
64
+ // Confined to project-local files: node_modules and the engine's own modules
65
+ // resolve untouched, as before.
66
+ const recorded = new Set()
67
+ let recordDepth = 0
68
+
69
+ function isProjectModule(file) {
70
+ if (!projectRoot || !file.startsWith(projectRoot)) return false
71
+ return !file.split(path.sep).includes('node_modules')
72
+ }
73
+
74
+ // Absolute paths of everything a sidecar has imported from outside the
75
+ // layouts folder so far this process, sorted so a digest over them is stable.
76
+ export function recordedSidecarModules() {
77
+ return [...recorded].sort()
78
+ }
79
+
80
+ export function forgetRecordedSidecarModules() {
81
+ recorded.clear()
82
+ }
45
83
 
46
84
  // Register once per process. Idempotent, and a no-op on a Node without
47
85
  // registerHooks — callers read the return value to decide what to use as
48
86
  // the entry stamp.
49
- export function installSidecarModuleHook({ layoutsFolder, logger }) {
87
+ export function installSidecarModuleHook({ layoutsFolder, workingFolder, logger }) {
50
88
  if (installed) return true
51
89
  if (!layoutsFolder) return false
52
90
  if (!canRegisterHooks) {
@@ -59,12 +97,36 @@ export function installSidecarModuleHook({ layoutsFolder, logger }) {
59
97
  return false
60
98
  }
61
99
  rootUrl = pathToFileURL(layoutsFolder).href.replace(/\/?$/, '/')
100
+ projectRoot = workingFolder ? path.resolve(workingFolder) + path.sep : null
62
101
  module.registerHooks({
63
102
  resolve(specifier, context, nextResolve) {
64
103
  const resolved = nextResolve(specifier, context)
65
- if (!resolved?.url?.startsWith(rootUrl)) return resolved
66
- if (resolved.url.includes('?')) return resolved
67
- return { ...resolved, url: `${resolved.url}?stamp=${stamp}` }
104
+ const url = resolved?.url
105
+ if (typeof url !== 'string' || !url.startsWith('file:')) return resolved
106
+ if (url.includes('?')) return resolved
107
+ if (url.startsWith(rootUrl)) return { ...resolved, url: `${url}?stamp=${stamp}` }
108
+ // Outside the layouts folder, and only while a sidecar is
109
+ // loading — so an import the engine or the config performs on
110
+ // the same file is left alone unless it happens to resolve
111
+ // inside this window.
112
+ if (!recordDepth) return resolved
113
+ let file
114
+ try {
115
+ file = fileURLToPath(url)
116
+ } catch {
117
+ return resolved
118
+ }
119
+ if (!isProjectModule(file)) return resolved
120
+ recorded.add(file)
121
+ // Stamped as well as recorded. Recording alone fixes the
122
+ // rebuild and leaves `--watch` broken in the way this started
123
+ // from: the digest moves, the layout re-renders, and the
124
+ // sidecar imports the copy of the module the process loaded
125
+ // first. The consequence is the one that already applies under
126
+ // layouts/ — a module in a sidecar's import graph is evaluated
127
+ // again when layout code changes, so a process-wide singleton
128
+ // does not belong in one.
129
+ return { ...resolved, url: `${url}?stamp=${stamp}` }
68
130
  },
69
131
  })
70
132
  installed = true
@@ -104,10 +166,16 @@ export async function loadSidecarModule(layout, { layoutsFolder, logger } = {})
104
166
  // imports too; without it only the entry reloads, so fall back to a
105
167
  // per-call stamp to keep at least that much.
106
168
  const entryStamp = sidecarHookInstalled() ? shared : Date.now()
169
+ // The window the resolve hook records in. Depth-counted because layouts
170
+ // render concurrently, so several sidecars are in flight at once and the
171
+ // first to finish must not close the window on the rest.
172
+ recordDepth++
107
173
  try {
108
174
  return await import(`${pathToFileURL(sidecarPath).href}?stamp=${entryStamp}`)
109
175
  } catch (err) {
110
176
  logger?.error('Layout sidecar %s failed to load: %s', sidecarPath, err.message)
111
177
  throw err
178
+ } finally {
179
+ recordDepth--
112
180
  }
113
181
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mikser-io-layouts",
3
- "version": "11.4.0",
3
+ "version": "11.6.0",
4
4
  "description": "SSG-flavor task-production policy for mikser-io. Multi-match layout assignment, per-layout destinations, postprocess chain attachment, layout inspection.",
5
5
  "main": "index.js",
6
6
  "type": "module",
@@ -18,7 +18,7 @@
18
18
  },
19
19
  "homepage": "https://github.com/almero-digital-marketing/mikser-io-layouts#readme",
20
20
  "peerDependencies": {
21
- "mikser-io": "^11.1.0",
21
+ "mikser-io": "^11.10.0",
22
22
  "zod": "^4.0.0"
23
23
  },
24
24
  "dependencies": {
@@ -27,7 +27,7 @@
27
27
  "lodash": "^4.17.0"
28
28
  },
29
29
  "devDependencies": {
30
- "mikser-io": "^11.1.0",
30
+ "mikser-io": "^11.10.0",
31
31
  "mikser-io-render-liquid": "^11.0.1",
32
32
  "zod": "^4.0.0"
33
33
  }
@@ -0,0 +1,109 @@
1
+ // A sidecar's imports that resolve OUTSIDE the layouts folder.
2
+ //
3
+ // `layouts/lib/context.js` was always handled: it is globbed into the shared
4
+ // digest and stamped by the resolve hook, so editing one re-renders its
5
+ // layouts and the new code is what runs. `lib/context.js` one level up is the
6
+ // same code doing the same job and got neither — reported as an edit that
7
+ // rendered nothing, a restart that changed nothing, and `--force` as the only
8
+ // way to see the new output.
9
+ //
10
+ // The set cannot be globbed, because it is "whatever a sidecar imports".
11
+ // The resolve hook is the only place it is observable, so these tests are
12
+ // about what the hook records and what it stamps. The invalidation that
13
+ // record feeds is a scenario test, in core, where a real build runs.
14
+
15
+ import { describe, it, before, after } from 'node:test'
16
+ import assert from 'node:assert/strict'
17
+ import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises'
18
+ import { tmpdir } from 'node:os'
19
+ import path from 'node:path'
20
+
21
+ import {
22
+ installSidecarModuleHook, loadSidecarModule, recordedSidecarModules, sidecarHookInstalled,
23
+ } from '../lib/sidecar-modules.js'
24
+
25
+ describe('a sidecar importing from outside the layouts folder', () => {
26
+ let root, elsewhere, layoutsFolder
27
+ const silent = { debug() {}, error() {} }
28
+ const load = (shared) => loadSidecarModule(
29
+ { name: 'page', inputs: { shared } }, { layoutsFolder, logger: silent })
30
+
31
+ before(async () => {
32
+ root = await mkdtemp(path.join(tmpdir(), 'mikser-sidecar-ext-'))
33
+ // A project the working folder does NOT contain, to prove the
34
+ // boundary is the project and not "anything that is not a layout".
35
+ elsewhere = await mkdtemp(path.join(tmpdir(), 'mikser-elsewhere-'))
36
+ layoutsFolder = path.join(root, 'layouts')
37
+ await mkdir(layoutsFolder, { recursive: true })
38
+ await mkdir(path.join(root, 'shared'), { recursive: true })
39
+ await mkdir(path.join(root, 'node_modules', 'pkg'), { recursive: true })
40
+
41
+ await writeFile(path.join(root, 'shared', 'context.js'), "export const label = 'FIRST'\n")
42
+ await writeFile(path.join(root, 'shared', 'unimported.js'), "export const idle = true\n")
43
+ await writeFile(path.join(root, 'node_modules', 'pkg', 'index.js'), "export const vendor = 'v1'\n")
44
+ await writeFile(path.join(elsewhere, 'far.js'), "export const far = 'far'\n")
45
+ await writeFile(path.join(layoutsFolder, 'page.js'),
46
+ "import { label } from '../shared/context.js'\n"
47
+ + "import { vendor } from '../node_modules/pkg/index.js'\n"
48
+ + `import { far } from '${path.join(elsewhere, 'far.js')}'\n`
49
+ + 'export const load = () => ({ label, vendor, far })\n')
50
+
51
+ installSidecarModuleHook({ layoutsFolder, workingFolder: root, logger: silent })
52
+ })
53
+
54
+ after(async () => {
55
+ await rm(root, { recursive: true, force: true })
56
+ await rm(elsewhere, { recursive: true, force: true })
57
+ })
58
+
59
+ it('installs on a Node that supports registerHooks', () => {
60
+ assert.equal(sidecarHookInstalled(), true, `not installed on ${process.version}`)
61
+ })
62
+
63
+ it('records the helper it imported from the project', async () => {
64
+ const mod = await load('digest-1')
65
+ assert.equal(mod.load().label, 'FIRST')
66
+ assert.ok(
67
+ recordedSidecarModules().includes(path.join(root, 'shared', 'context.js')),
68
+ `shared/context.js was not recorded: ${recordedSidecarModules().join(', ')}`,
69
+ )
70
+ })
71
+
72
+ it('does not record a dependency', () => {
73
+ // node_modules is not something an author edits, and hashing it on
74
+ // every scan would be the cost of the whole tree.
75
+ assert.ok(!recordedSidecarModules().some(file => file.includes(`${path.sep}node_modules${path.sep}`)),
76
+ `a node_modules path was recorded: ${recordedSidecarModules().join(', ')}`)
77
+ })
78
+
79
+ it('does not record a module outside the working folder', () => {
80
+ assert.ok(!recordedSidecarModules().some(file => file.startsWith(elsewhere)),
81
+ `a module outside the project was recorded: ${recordedSidecarModules().join(', ')}`)
82
+ })
83
+
84
+ it('does not record what something other than a sidecar imports', async () => {
85
+ // The window is the sidecar load. Without it the hook would stamp —
86
+ // and so re-evaluate — any project module the engine or the config
87
+ // happened to import, which is a second copy of somebody's singleton.
88
+ await import(path.join(root, 'shared', 'unimported.js'))
89
+ assert.ok(!recordedSidecarModules().includes(path.join(root, 'shared', 'unimported.js')),
90
+ 'a module imported outside a sidecar load was recorded')
91
+ })
92
+
93
+ it('runs the NEW code after the helper is edited and the stamp moves', async () => {
94
+ // The half that recording alone does not fix: the digest moves, the
95
+ // layout re-renders, and without a stamp on this URL the sidecar
96
+ // imports the copy the process loaded first.
97
+ await writeFile(path.join(root, 'shared', 'context.js'), "export const label = 'SECOND'\n")
98
+ const mod = await load('digest-2')
99
+ assert.equal(mod.load().label, 'SECOND',
100
+ 'an out-of-folder helper must be re-evaluated when the stamp changes')
101
+ })
102
+
103
+ it('serves the cached copy while the stamp is unchanged', async () => {
104
+ const first = (await load('digest-stable')).load().label
105
+ await writeFile(path.join(root, 'shared', 'context.js'), "export const label = 'NEVER-SEEN'\n")
106
+ assert.equal((await load('digest-stable')).load().label, first,
107
+ 'an unchanged stamp must not re-parse the graph')
108
+ })
109
+ })
@@ -0,0 +1,94 @@
1
+ // The stored sidecar import graph.
2
+ //
3
+ // Its one hard rule: NOTICING a module must not move the digest. The graph is
4
+ // only observable once a sidecar has loaded, so every project gains entries on
5
+ // its first build after the upgrade — and if the digest were a hash of the
6
+ // list, that first build would be followed by a full re-render of every
7
+ // layout, for nothing. Each path is therefore stored with the checksum it had
8
+ // when it was found, and only a checksum that stops matching moves anything.
9
+
10
+ import { describe, it, before, after, beforeEach } from 'node:test'
11
+ import assert from 'node:assert/strict'
12
+ import { mkdtemp, rm, mkdir, writeFile, readFile } from 'node:fs/promises'
13
+ import { tmpdir } from 'node:os'
14
+ import path from 'node:path'
15
+
16
+ import { createSidecarGraph } from '../lib/sidecar-graph.js'
17
+
18
+ describe('the stored sidecar module graph', () => {
19
+ let root, runtimeFolder, helper, other
20
+ const logger = () => ({ debug() {} })
21
+ const graph = () => createSidecarGraph({ runtime: { options: { runtimeFolder } }, logger })
22
+
23
+ before(async () => {
24
+ root = await mkdtemp(path.join(tmpdir(), 'mikser-graph-'))
25
+ runtimeFolder = path.join(root, 'runtime')
26
+ await mkdir(runtimeFolder, { recursive: true })
27
+ helper = path.join(root, 'context.js')
28
+ other = path.join(root, 'other.js')
29
+ })
30
+
31
+ beforeEach(async () => {
32
+ await rm(path.join(runtimeFolder, 'layouts-modules.json'), { force: true })
33
+ await writeFile(helper, "export const label = 'FIRST'\n")
34
+ await writeFile(other, "export const n = 1\n")
35
+ })
36
+
37
+ after(async () => { await rm(root, { recursive: true, force: true }) })
38
+
39
+ it('contributes nothing when no sidecar has imported anything', async () => {
40
+ // An empty contribution is what keeps a project that never leaves its
41
+ // layouts folder hashing exactly as it did before any of this existed.
42
+ assert.equal(await graph().digest(), '')
43
+ })
44
+
45
+ it('still contributes nothing after a module is discovered', async () => {
46
+ const subject = graph()
47
+ assert.equal(await subject.discover([helper]), true)
48
+ assert.equal(await subject.digest(), '',
49
+ 'discovering a module must not look like a change to it')
50
+ })
51
+
52
+ it('moves once the discovered module changes', async () => {
53
+ const subject = graph()
54
+ await subject.discover([helper])
55
+ await subject.digest()
56
+ await writeFile(helper, "export const label = 'SECOND'\n")
57
+ const moved = await subject.digest()
58
+ assert.notEqual(moved, '', 'an edited module must move the digest')
59
+ assert.equal(await subject.digest(), moved, 'and then settle at the new value')
60
+ })
61
+
62
+ it('reads the graph back in a later run', async () => {
63
+ // A one-shot build exits between the render that observes the graph
64
+ // and the scan that uses it, which is why this is on disk at all.
65
+ await graph().discover([helper])
66
+ await writeFile(helper, "export const label = 'SECOND'\n")
67
+ assert.notEqual(await graph().digest(), '')
68
+ })
69
+
70
+ it('drops a module that is gone instead of remembering it as missing', async () => {
71
+ const subject = graph()
72
+ await subject.discover([helper, other])
73
+ await subject.digest()
74
+ await rm(other)
75
+ const moved = await subject.digest()
76
+ assert.notEqual(moved, '', 'a vanished input is a change')
77
+ const stored = JSON.parse(await readFile(path.join(runtimeFolder, 'layouts-modules.json'), 'utf8'))
78
+ assert.deepEqual(Object.keys(stored.modules), [helper],
79
+ 'a renamed helper must not leave an entry that can never match again')
80
+ assert.equal(await subject.digest(), moved, 'and the digest settles')
81
+ })
82
+
83
+ it('does not record a module that cannot be read', async () => {
84
+ const subject = graph()
85
+ assert.equal(await subject.discover([path.join(root, 'absent.js')]), false)
86
+ assert.deepEqual(await subject.tracked(), [])
87
+ })
88
+
89
+ it('reports what it tracks, for the watcher to follow', async () => {
90
+ const subject = graph()
91
+ await subject.discover([other, helper])
92
+ assert.deepEqual(await subject.tracked(), [helper, other].sort())
93
+ })
94
+ })
package/test/unit.test.js CHANGED
@@ -210,6 +210,81 @@ describe('layouts plugin', () => {
210
210
  })
211
211
  })
212
212
 
213
+ it('never hands a renderer a layout with its front matter still attached', async () => {
214
+ // resolveLayout falls back to the state map when the catalog has not
215
+ // caught up, and the state map holds the file AS SYNCED. That raw
216
+ // text has failed twice, in two engines: Handlebars emitted the YAML
217
+ // into the page, and LiquidJS refuses to parse it at all — reported
218
+ // as "invalid range syntax" at line 2, the front-matter line, which
219
+ // takes the whole layout down.
220
+ //
221
+ // The catalog is deliberately EMPTY here, which is the fallback.
222
+ await withTempWorking(async (workingFolder) => {
223
+ const h = createHarness({
224
+ entities: [],
225
+ options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
226
+ })
227
+ layouts({ autoLayouts: false })(h.core)
228
+ await h.runHook('loaded')
229
+ await h.runSync('layouts', { action: 'create', context: { relativePath: 'post.hbs' } })
230
+ // The file as synced: front matter still on it.
231
+ h.runtime.state.layouts.layouts['post'].content =
232
+ '---\ndestination: "/{{ entity.name }}.html"\n---\n<h1>body</h1>\n'
233
+
234
+ const doc = { id: '/documents/hello.md', collection: 'documents', name: 'hello', format: 'md', meta: { layout: 'post' } }
235
+ h.journal.push({ id: 1, entity: doc, operation: 'create', context: {}, options: {}, output: null })
236
+ await h.runHook('processed', { aborted: false })
237
+
238
+ assert.ok(!doc.layout.content.trimStart().startsWith('---'),
239
+ `front matter reached the renderer: ${JSON.stringify(doc.layout.content.slice(0, 40))}`)
240
+ assert.match(doc.layout.content, /<h1>body<\/h1>/, 'the template survived')
241
+ })
242
+ })
243
+
244
+ it('lifts the fallback layout\'s front matter onto meta, so destination still works', async () => {
245
+ // Stripping without lifting would trade a parse error for a silently
246
+ // ignored `destination:` — the state-map entry carries no meta at all
247
+ // otherwise, which is why a front-matter `match:` saw nothing there.
248
+ await withTempWorking(async (workingFolder) => {
249
+ const h = createHarness({
250
+ entities: [],
251
+ options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
252
+ })
253
+ layouts({ autoLayouts: false })(h.core)
254
+ await h.runHook('loaded')
255
+ await h.runSync('layouts', { action: 'create', context: { relativePath: 'post.hbs' } })
256
+ h.runtime.state.layouts.layouts['post'].content =
257
+ '---\ndestination: "/cards/{{entity.name}}.html"\n---\n<h1>body</h1>\n'
258
+
259
+ const doc = { id: '/documents/hello.md', collection: 'documents', name: 'hello', format: 'md', meta: { layout: 'post' } }
260
+ h.journal.push({ id: 1, entity: doc, operation: 'create', context: {}, options: {}, output: null })
261
+ await h.runHook('processed', { aborted: false })
262
+
263
+ assert.equal(doc.layout.meta.destination, '/cards/{{entity.name}}.html')
264
+ })
265
+ })
266
+
267
+ it('leaves a malformed front-matter block alone rather than dropping it', async () => {
268
+ // Unparseable YAML shown to the author beats silently discarded.
269
+ await withTempWorking(async (workingFolder) => {
270
+ const h = createHarness({
271
+ entities: [],
272
+ options: { workingFolder, outputFolder: path.join(workingFolder, 'out'), force: true },
273
+ })
274
+ layouts({ autoLayouts: false })(h.core)
275
+ await h.runHook('loaded')
276
+ await h.runSync('layouts', { action: 'create', context: { relativePath: 'post.hbs' } })
277
+ const broken = "---\ndestination: '/{{ before (after entity.name '/') '_' }}'\n---\n<h1>body</h1>\n"
278
+ h.runtime.state.layouts.layouts['post'].content = broken
279
+
280
+ const doc = { id: '/documents/hello.md', collection: 'documents', name: 'hello', format: 'md', meta: { layout: 'post' } }
281
+ h.journal.push({ id: 1, entity: doc, operation: 'create', context: {}, options: {}, output: null })
282
+ await h.runHook('processed', { aborted: false })
283
+
284
+ assert.equal(doc.layout.content, broken, 'left as written')
285
+ })
286
+ })
287
+
213
288
  it('a layout matches through `match:` in its own front-matter', async () => {
214
289
  // Documented in the README beside `destination:` and never
215
290
  // implemented. A layout carrying it produced no render task, logged