mikser-io 9.14.0 → 9.15.1

package/index.js

@@ -45,9 +45,18 @@ export { yaml }          from './src/plugins/yaml.js'
 // loader stores in `runtime.renderers`; the same module also still
 // exports `load`/`render` at the top level so Piscina worker dispatch
 // can resolve via dynamic import. ADR-0010.
-export { renderAsset }    from './src/plugins/render/asset.js'
-export { renderFile }     from './src/plugins/render/file.js'
-export { renderHbs }      from './src/plugins/render/hbs.js'
-export { renderHref }     from './src/plugins/render/href.js'
-export { renderPreset }   from './src/plugins/render/preset.js'
-export { renderResource } from './src/plugins/render/resource.js'
+// Renderers — these have a render() and turn an entity into a file.
+export { renderHbs }    from './src/plugins/render/hbs.js'
+export { renderPreset } from './src/plugins/render/preset.js'
+
+// Template helpers — these only install functions on `runtime` for templates
+// to call. They render nothing, which is what the old render* names hid: two
+// of the six factories in this folder are renderers and four are not, and
+// naming all six after the object they concern rather than the job they do
+// led someone to add renderPreset() expecting a helper and watch every page
+// render throw. Renamed in 10.0.0; there are no aliases.
+export { assetUrlHelper }    from './src/plugins/render/asset.js'
+export { hrefUrlHelpers }    from './src/plugins/render/href.js'
+export { resourceUrlHelper } from './src/plugins/render/resource.js'
+export { fileHelpers }       from './src/plugins/render/file.js'
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.14.0",
+  "version": "9.15.1",
   "description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
   "main": "index.js",
   "exports": {

package/src/manifest.js

@@ -440,6 +440,22 @@ export function createManifest(db) {
                     })
                 }
             }
+            if (track?.lookups) {
+                for (const target of track.lookups) {
+                    // findById is extension-tolerant and also resolves a
+                    // meta.href, so the hash is the resolved entity's when
+                    // there is one. No hash means "nothing resolved" —
+                    // shouldSkip treats a hashless edge whose target mutated
+                    // as a re-render, which is what should happen when a page
+                    // that was linked-to-but-missing finally appears.
+                    const resolved = findById(target)
+                    edges.push({
+                        kind: 'lookup',
+                        target,
+                        hash: resolved ? inputHashOf(resolved) : undefined,
+                    })
+                }
+            }
             if (track?.queries) {
                 for (const filter of track.queries) {
                     edges.push({ kind: 'query', filter })

package/src/plugins/render/asset.js

@@ -10,6 +10,6 @@ export function load({ runtime, entity, state, options }) {
     }
 }
 
-export function renderAsset(options = {}) {
+export function assetUrlHelper(options = {}) {
     return { name: options.name ?? 'asset', options, load }
-}
+}

package/src/plugins/render/file.js

@@ -44,6 +44,6 @@ export function load({ runtime }) {
     }
 }
 
-export function renderFile(options = {}) {
+export function fileHelpers(options = {}) {
     return { name: options.name ?? 'file', options, load }
 }

package/src/plugins/render/href.js

@@ -41,6 +41,6 @@ export function load({ entity, runtime, options }) {
     runtime.next = entity.page + 1 < entity.pages ? entity.page + 1 : false
 }
 
-export function renderHref(options = {}) {
+export function hrefUrlHelpers(options = {}) {
     return { name: options.name ?? 'href', options, load }
-}
+}

package/src/plugins/render/preset.js

@@ -2,7 +2,7 @@ import { mkdir } from 'node:fs/promises'
 import path from 'node:path'
 
 // A renderer's `load` runs for EVERY entity in the cycle, not only the ones
-// this renderer will render — that is deliberate and is how renderAsset
+// this renderer will render — that is deliberate and is how assetUrlHelper
 // installs runtime.asset() for all templates. So this has to tolerate an
 // entity that has no preset, rather than assume it is looking at one.
 //
@@ -11,13 +11,12 @@ import path from 'node:path'
 // "you have found something real", which is a much more expensive wrong
 // signal than a no-op. The names invite exactly that mistake:
 //
-//   renderAsset()   provides runtime.asset() to templates  (a URL helper)
+//   assetUrlHelper() provides runtime.asset() to templates  (a URL helper)
 //   assets()        runs presets and produces derivatives   (the work)
 //   renderPreset()  renders a preset-authored layout        (this file)
 //
-// All three are named after the object they concern rather than the job they
-// do, so reasoning "the one that RUNS presets must be renderPreset" is wrong
-// but not unreasonable.
+// The helpers were renamed for their role in 10.0.0 for exactly this reason;
+// renderPreset keeps its name because it really is a renderer.
 export async function load({ entity, runtime }) {
     if (!entity?.preset?.uri) return
     const preset = await import(`${entity.preset.uri}?stamp=${Date.now()}`)

package/src/plugins/render/resource.js

@@ -16,6 +16,6 @@ export function load({ runtime, entity, state, options }) {
     }
 }
 
-export function renderResource(options = {}) {
+export function resourceUrlHelper(options = {}) {
     return { name: options.name ?? 'resource', options, load }
-}
+}

package/src/render.js

@@ -187,10 +187,28 @@ export default async ({ entity, options, config, context, state, logger, port, t
         // state.layouts.sitemap map that was serialized per render
         // task. Goes through the same WAL-backed read-only handle
         // every worker shares with the engine writer.
-        lookupHref: lookupHrefViaDb,
+        // Both lookups RECORD what they were asked for, via track.lookup.
+        //
+        // They read the catalog directly, and until this they told nobody —
+        // so nothing knew a page depended on the page it links to. Renaming
+        // a target left every page linking to it pointing at a file that no
+        // longer existed, on a green build, because manifest.shouldSkip had
+        // no edge to check. A sidecar's findEntities() was tracked all along;
+        // these two were the asymmetry.
+        //
+        // The recorded target is the string the template asked for, not the
+        // resolved id — see track.lookup for why that also covers a target that
+        // does not exist yet.
+        lookupHref: (href) => {
+            track?.lookup?.(href)
+            return lookupHrefViaDb(href)
+        },
         // Resolve a served-entity reference to its deployed URL, absolute
         // when runtime.options.url is set (ADR-0011).
-        lookupUrl: (ref, preset) => lookupUrlViaDb(ref, preset, options.url),
+        lookupUrl: (ref, preset) => {
+            if (typeof ref === 'string') track?.lookup?.(ref)
+            return lookupUrlViaDb(ref, preset, options.url)
+        },
         content() {
             return readFileSync(entity.source, { encoding: 'utf8' })
         },

package/src/track.js

@@ -40,8 +40,36 @@ export function filterKey(filter) {
 // The returned object exposes `partials: Set<string>` and
 // `queries: Array<filter | null>` directly. Consumers iterate either
 // shape; both are owned by the track for the lifetime of the run.
-export function createTrack({ partial = true, query = true } = {}) {
+export function createTrack({ partial = true, query = true, lookup = true } = {}) {
     const track = {}
+    if (lookup) {
+        // Lookups a TEMPLATE made by name: runtime.href('/contacts'),
+        // runtime.lookupUrl('/media/clip.mp4'). Both read the catalog
+        // directly, and until this existed neither told anyone — so nothing
+        // recorded that a page depends on the page it links to.
+        //
+        // Measured consequence: rename contacts.md to contact-us.md and only
+        // the renamed page re-renders. Every page linking to it keeps a href
+        // pointing at a file that no longer exists, on a green build.
+        //
+        // The edge kind is 'lookup', NOT 'ref': mikser_refs divides ownership
+        // by kind — indexEntity owns kind='ref' (static frontmatter $-refs)
+        // and clears it per source, while replaceDynamic owns everything
+        // else. Writing these as 'ref' got them inserted by replaceDynamic
+        // and then wiped by the next indexEntity, so the edge existed in
+        // the manifest and never in the refs index — recorded, and still
+        // never scheduling a re-render.
+        //
+        // The target is the STRING the template asked for, not the resolved
+        // entity's id, and that is deliberate: lookupKeys() expands a mutated
+        // entity into its id, its meta.href AND its id-minus-extension, so an
+        // edge on '/contacts' fires whether the target was edited, renamed,
+        // deleted, or created for the first time. Recording the resolved id
+        // instead would miss the case where nothing resolved yet.
+        const lookups = new Set()
+        track.lookups = lookups
+        track.lookup = (target) => { if (target && typeof target === 'string') lookups.add(target) }
+    }
     if (partial) {
         const partials = new Set()
         track.partials = partials