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 +32 -0
- package/index.js +67 -3
- package/lib/matching.js +31 -2
- package/lib/sidecar-graph.js +115 -0
- package/lib/sidecar-modules.js +73 -5
- package/package.json +3 -3
- package/test/sidecar-external-modules.test.js +109 -0
- package/test/sidecar-graph.test.js +94 -0
- package/test/unit.test.js +75 -0
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({
|
|
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
|
-
|
|
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
|
+
}
|
package/lib/sidecar-modules.js
CHANGED
|
@@ -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
|
-
|
|
66
|
-
if (
|
|
67
|
-
|
|
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.
|
|
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.
|
|
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.
|
|
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
|