mikser-io 9.72.0 → 9.74.0

package/app.js

@@ -49,8 +49,6 @@ function locate(argv) {
         longRunning,
         workingFolder: value('--working-folder', '-i') ?? '.',
         config: value('--config', '-c') ?? 'mikser.config.js',
-        // Commander's negated form: `attach` is true unless --no-attach said so.
-        attach: has('--no-attach') ? false : true,
         request,
     }
 }
@@ -62,18 +60,17 @@ async function main() {
     // A second server or watcher is the hazard this whole surface exists to
     // remove, and it is the one shape that cannot be answered by forwarding.
     // So it stops, rather than silently doing something else.
-    if (where.attach !== false && where.longRunning) {
+    if (where.longRunning) {
         if (await isInstanceLive(workingFolder)) {
             process.stderr.write(
                 'mikser: another mikser is already running in this folder, and a server or watcher cannot be '
                 + 'forwarded to it — it would have to open a port on your behalf.\n'
-                + 'Stop that one, or pass --no-attach to run a second engine here (two engines share the '
-                + 'catalogue and the output tree, with no lock between them).\n')
+                + 'Stop that one first.\n')
             process.exit(1)
         }
     }
 
-    if (where.attach !== false && !where.longRunning) {
+    if (!where.longRunning) {
         const code = await forward({
             workingFolder,
             config: path.resolve(where.workingFolder, where.config),

package/docs/configuration.md

@@ -70,24 +70,39 @@ Which subtrees of the output folder are deployed as their own domain root.
 
 ```js
 export default {
-    // out/bg becomes lmed.bg, out/en becomes lmed.info, out/mk becomes lmed.mk
+    // out/bg, out/en and out/mk each deploy to their own domain
     siteRoots: ['bg', 'en', 'mk'],
 }
 ```
 
-Read only by the broken-reference check. It resolves urls the way a browser
-does, and a browser cannot climb above the origin root — it discards the
-extra `..` and loads the file. Where the site root actually is therefore
-decides whether `../../x.svg` on a given page is correct, merely over-deep,
-or broken.
+Read by the url helpers and by the broken-reference check.
 
-Default is the output folder itself, which is right for the ordinary case of
-one site per build. Declare this only when a build emits several sites, as a
-per-language deploy does — resolving those against the output root instead
-misses the over-escape entirely and reports the working urls as broken.
+**It changes the output.** `asset`, `href` and `resource` build a path from the
+page to the target, and without this they measure from the output folder. When
+`out/bg` is what gets deployed, that is one directory too far — every url
+carries an extra `..` for the site segment. A browser floors a climb above the
+origin root rather than failing, so those urls load and nothing reports them.
+Declaring the roots makes the helpers measure from the site instead, and the
+urls become what they should have been.
+
+The check reads it for the same reason, and resolves urls the way a browser
+does. Where the site root is decides whether `../../x.svg` on a given page is
+correct, merely over-deep, or broken.
 
-Nothing can infer it: it is a fact about where the bytes get deployed, not
-about the bytes.
+Default is the output folder itself, which is right for the ordinary case of
+one site per build — and with nothing declared every url is byte-identical to
+what it was. Only a build that emits several sites moves, and it moves from
+working-by-flooring to correct.
+
+Declaring it also asserts something: **a site root is a deployable unit.** It
+is served alone, so anything its pages reference has to exist beneath it —
+share a common assets folder into each root rather than beside them. A url to
+a target in a *different* root is left as it was, because on a per-domain
+deploy no relative path reaches another origin; the check will report it, which
+is the honest answer.
+
+Nothing can infer any of this: it is a fact about where the bytes get deployed,
+not about the bytes.
 
 ## Engine Substrate
 

package/docs/diagnostics.md

@@ -231,7 +231,7 @@ the whole question:
 ```json
 { "destination": "/index.html", "reason": "query-matched",
   "matched": { "filter": { "id": { "$regex": "^/documents/devices/" } },
-               "by": "/documents/devices/hera.md" } }
+               "by": "/documents/devices/model-a.md" } }
 ```
 
 A `matched.filter` of `null` is a different statement: the page's predicate
@@ -760,8 +760,9 @@ Three things it refuses or reports rather than guessing:
   to *become* the instance, which is not something a running one can do for
   you — it would have to open a port in your process. They exit 1 and say so,
   rather than building and leaving nothing on the port.
-- **A folder held by someone else.** `--no-attach` runs a private engine
-  anyway — for checking that a cold start works — and says the folder is held.
+There is no opt-out. A flag for running a second engine on a held folder
+only ever enabled the accident this surface prevents, and stopping the
+instance serves every case it was reached for.
 
 `--tool`, `--tools`, `--verify` and `--explain` forward as well, and for a
 different reason than builds do. They only read, so running one locally never
@@ -887,12 +888,16 @@ surfaces that turn silence into a statement:
     same file, the output scan reports it and this one stays quiet.
 - **A link that works only by accident** — a url with one `..` too many
   still loads, because a browser discards a climb above the origin root
-  rather than failing. It is one level of nesting away from a 404, and
-  it means the emitted depth does not match the page. Reported under
-  `reference-over-deep`, separately from the outright failures. Which
-  root to floor at is deployment intent and cannot be derived, so
-  declare it — see `siteRoots` in
-  [configuration](./configuration.md#siteroots).
+  rather than failing. Reported under `reference-over-deep`, separately
+  from the outright failures, and grouped by how far each climbed:
+  - **One url, or several climbing different distances** — each is a
+    latent 404, working today and broken as soon as the same markup
+    renders one level deeper.
+  - **Every url climbing the same distance** — not N problems but one
+    base that is off by a constant, reported once and flagged
+    `structural` in `--json`. The urls work at every depth. Usually it
+    means `siteRoots` is undeclared for a build that emits several
+    sites; see [configuration](./configuration.md#siteroots).
 
 ## See also
 

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "mikser-io",
-  "version": "9.72.0",
+  "version": "9.74.0",
+  "files": [
+    "app.js",
+    "index.js",
+    "src/",
+    "testing/",
+    "docs/",
+    "favicon.ico",
+    "favicon.svg",
+    "mikser-mark.svg",
+    "mikser-lockup-stacked.svg"
+  ],
   "description": "A mixer for content: entities in, configurable render pipelines, outputs of any kind. Static sites are the canonical recipe, not the definition — the same engine renders PDFs, emails and whatever a renderer plugin produces. Files are the source of truth, every lifecycle phase is observable, and the build graph is queryable by an agent.",
   "main": "index.js",
   "exports": {

package/src/engine.js

@@ -127,19 +127,45 @@ async function reportBrokenReferences(logger) {
             broken.length, checked, broken.length > SHOWN ? `, ${SHOWN} shown` : '')
     }
 
-    for (const { url, target, files } of overDeep.slice(0, SHOWN)) {
-        logger.warn({ code: 'reference-over-deep', url, target, files },
-            'Over-deep, loads only because the browser floors it: %s (from %s) — %s',
-            url, named(files), target)
+    // Grouped by how FAR each climbed, because a site whose every over-deep url
+    // climbs the same distance does not have N problems — it has one base that
+    // is off by a constant. Printing it N times is precisely how a real signal
+    // gets filtered out, which is the failure this check exists to prevent.
+    const byClimb = new Map()
+    for (const entry of overDeep) {
+        if (!byClimb.has(entry.floored)) byClimb.set(entry.floored, [])
+        byClimb.get(entry.floored).push(entry)
     }
+    // One distance, many urls: structural. The helper's base is wrong, the urls
+    // are not — they load at every depth, because the climb is always floored.
+    // That wants a different reaction than a hand-written `../..` that happens
+    // to be right on one page and is a 404 waiting on the next.
+    const structural = byClimb.size === 1 && overDeep.length > 1
+
+    for (const [climb, entries] of [...byClimb].sort(([a], [b]) => a - b)) {
+        const examples = entries.slice(0, 3).map(e => e.url)
+        logger.warn(
+            {
+                code: 'reference-over-deep', climbs: climb, count: entries.length,
+                structural, urls: examples,
+                files: [...new Set(entries.flatMap(e => e.files))].slice(0, 3),
+            },
+            structural
+                ? '%d references climb %d level(s) above the site root — every one of them, by the '
+                  + 'same amount. They load: a browser discards the extra `..`. What is wrong is the '
+                  + 'base they were built from, not the links. Examples: %s'
+                : '%d reference(s) climb %d level(s) above the site root and load only because a '
+                  + 'browser discards the extra `..`. Each breaks if the same markup renders one '
+                  + 'level deeper. Examples: %s',
+            entries.length, climb, examples.join(', '))
+    }
+
     if (overDeep.length) {
-        logger.warn({ code: 'reference-over-deep-summary', overDeep: overDeep.length, checked },
-            '%d of %d reference(s) climb above the site root and load only because a browser '
-            + 'discards the extra `..`%s. They break as soon as the same markup renders one '
-            + 'level deeper.%s',
-            overDeep.length, checked, overDeep.length > SHOWN ? `, ${SHOWN} shown` : '',
-            siteRoots.length ? '' : ' No siteRoots are declared, so this resolved against the '
-                + 'output root — declare runtime.config.siteRoots if a subtree is deployed as its own domain.')
+        logger.warn({ code: 'reference-over-deep-summary', overDeep: overDeep.length, checked, structural },
+            '%d of %d reference(s) resolve above the site root.%s',
+            overDeep.length, checked,
+            siteRoots.length ? '' : ' No siteRoots are declared, so this resolved against the output '
+                + 'root — declare siteRoots if a subtree is deployed as its own domain.')
     }
 
     return new Set(broken.map(b => b.target))
@@ -360,7 +386,6 @@ export async function setup(options) {
         runtime.engine.commander?.version(packageInfo.version)
             .option('-i --working-folder <folder>', 'set mikser working folder', './')
             .option('-c --config <file>', 'set mikser mikser.config.js location', './mikser.config.js')
-            .option('--no-attach', 'start a private engine instead of forwarding to the one already running here')
             .option('-m --mode <mode>', 'set mikser runtime mode', 'development')
             .option('-r --clear', 'clear current state before execution', false)
             .option('-o --output-folder <folder>', 'set mikser output folder relative to working folder', 'out')
@@ -472,6 +497,15 @@ export async function setup(options) {
     // runtime.config) and before any plugin's onLoaded.
     onLoad(async () => {
         const logger = useLogger()
+
+        // Onto OPTIONS, not left on config: the url helpers read it, and they
+        // run in render workers, which receive the worker-safe options and
+        // never see runtime.config.
+        runtime.options.siteRoots = runtime.config?.siteRoots ?? []
+        if (runtime.options.siteRoots.length) {
+            logger.info('Site roots: %s', runtime.options.siteRoots.join(', '))
+        }
+
         const cli = runtime.options.url
         const cfg = runtime.config?.url
         const raw = cli ?? cfg

package/src/instance.js

@@ -19,10 +19,12 @@
 // new to learn and no watermark to reason about — which matters, because a
 // design that needs discipline from the caller is the one that gets violated.
 //
-// `--no-attach` opts out, for when a fresh process IS the point: checking that
-// a cold start works, that startup ordering hides nothing. Named for what it
-// switches off rather than for a property of the process — the default is to
-// attach, and the flag should say which behaviour is being declined.
+// There is no opt-out. A flag for "run a second engine here anyway" only ever
+// enabled the accident this file exists to prevent — two engines sharing one
+// catalogue and one output tree with no lock between them — and no caller had
+// a reason to want it that a stopped instance would not serve better. An
+// option whose only use is the wrong one is not an escape hatch, it is a trap
+// with a name.
 
 import net from 'node:net'
 import { createHash } from 'node:crypto'
@@ -280,7 +282,7 @@ function refuseConfig(socket, request, wrongConfig) {
         type: 'refused',
         reason: `this instance is running ${wrongConfig}, and you asked for ${path.resolve(request.config)}.`,
         detail: 'Answering would use the wrong config — the accident this refusal exists to prevent. '
-            + 'Stop that instance, or pass --no-attach to run your own.',
+            + 'Stop that instance and run this again.',
     })
 }
 
@@ -341,7 +343,6 @@ async function serveBuild(socket, request, logger) {
 export function serveInstance() {
     onLoaded(async () => {
         if (!runtime.options.watch && !runtime.options.server) return
-        if (runtime.options.attach === false) return
         const logger = runtime.engine?.logger
         const endpoint = socketPath(runtime.options.workingFolder)
 
@@ -402,53 +403,7 @@ export function serveInstance() {
 
 // Say so when a private engine is starting in a folder someone else holds.
 //
-// The local counterpart of the rule already written down for deployments —
-// "never run a one-shot mikser command against the deployment" — which existed
-// because there was no alternative. There is one now, so this covers what is
-// left: --no-attach, and the report-only runs that stay local by design.
-//
-// A warning rather than a refusal. --no-attach is how you deliberately check
-// that a cold start works, and refusing it would take away the escape hatch
-// this design depends on having.
-export async function warnIfHeld({ workingFolder, attached }) {
-    const endpoint = socketPath(workingFolder)
-    if (process.platform !== 'win32' && !existsSync(endpoint)) return false
-
-    const live = await new Promise((resolve) => {
-        const probe = net.connect(endpoint)
-        const done = (answer) => { try { probe.destroy() } catch { /* already gone */ } resolve(answer) }
-        probe.on('connect', () => done(true))
-        probe.on('error', () => done(false))
-        setTimeout(() => done(false), 250).unref?.()
-    })
-    if (!live) return false
-
-    const logger = runtime.engine?.logger
-    const message = attached === false
-        ? 'Another mikser is already running in this folder, and --no-attach means this one will not talk to '
-          + 'it. Two engines share the catalogue and the output tree with no lock between them; a --clear from '
-          + 'either is what produces a cold rebuild that renders nothing.'
-        : 'Another mikser is already running in this folder. This command reads and does not write, so it is '
-          + 'safe — but it may see a catalogue mid-cycle.'
-    logger?.warn?.({ code: 'instance-already-running' }, message)
-    return true
-}
-
 // Registered at setup so both halves are wired from one call.
 export function instanceControl() {
     serveInstance()
-    onLoaded(async () => {
-        // Only --no-attach reaches this now. Everything else either forwarded
-        // (a build, a report) or refused before setup ran (a second server or
-        // watcher), so a process that is still here and not attaching is one
-        // that deliberately opted out — and that is exactly the case worth
-        // saying something about, long-running or not. The earlier gate
-        // skipped watch and server, which excluded `--no-attach --server`:
-        // the very command that puts two engines on one folder.
-        if (runtime.options.attach !== false) return
-        await warnIfHeld({
-            workingFolder: runtime.options.workingFolder,
-            attached: false,
-        })
-    })
 }

package/src/plugins/render/asset.js

@@ -1,6 +1,6 @@
 import path from 'node:path'
 
-import { changeExtension } from '../../utils.js'
+import { changeExtension, siteRelativeUrl } from '../../utils.js'
 
 // `{{asset 'web' '/media/hero.jpg'}}` — the deployed URL of a preset
 // derivative, relative to the page asking for it.
@@ -71,8 +71,10 @@ export function load({ runtime, entity, state, options, logger, track }) {
         // itself — it takes a path, not an entity, so there is nothing to look
         // up and the URL is well-formed whether or not anything produced it.
         track?.asset?.(destination)
-        const from = path.dirname(entity.destination || '/')
-        return { url: path.relative(from, destination) }
+        // Resolved within the site this page belongs to, not against the
+        // output root — see siteRelativeUrl. With no siteRoots declared the two
+        // are the same folder and the url is byte-identical.
+        return { url: siteRelativeUrl(entity.destination, destination, options?.siteRoots) }
     }
 }
 

package/src/plugins/render/file.js

@@ -72,7 +72,7 @@ function warnIfUntrackable(options, resolved, logger) {
     //
     // The first version of this hardcoded five content folders, and a project
     // registering its own collections through sources() has more than five. On
-    // lmed that meant 63 warnings per build, one for every stylesheet and
+    // one real site that meant 63 warnings per build, one for every stylesheet and
     // script, all of them tracked correctly and every one of them saying the
     // opposite. Which is worse than not warning: 63 spurious lines a build
     // teaches you to filter the channel, and the filtered-out line is the real

package/src/plugins/render/href.js

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import { siteRelativeUrl } from '../../utils.js'
 
 export function load({ entity, runtime, options }) {
     const { clear } = options
@@ -19,16 +20,14 @@ export function load({ entity, runtime, options }) {
 
         let found = runtime.hrefLang(href)
         if (!found) {
-            const from = path.dirname(entity.destination || '/')
-            return { url: path.relative(from, href) }
+            return { url: siteRelativeUrl(entity.destination, href, options?.siteRoots) }
         } else {
             if (!found.id) {
                 found = found[lang]
             }
             if (found?.destination) {
                 const destination = clear ? found.destination.replace('index.html', '') : found.destination
-                const from = path.dirname(entity.destination || '/')
-                found.url = path.relative(from, destination)
+                found.url = siteRelativeUrl(entity.destination, destination, options?.siteRoots)
             }
             return found
         }

package/src/plugins/render/resource.js

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import { matchesLibrary } from '../../utils.js'
+import { matchesLibrary, siteRelativeUrl } from '../../utils.js'
 
 export function load({ runtime, entity, state, options, track }) {
     runtime.resource = (url) => {
@@ -17,8 +17,7 @@ export function load({ runtime, entity, state, options, track }) {
                 // than resolving one, so a library that was never copied
                 // yields a link to nothing on a green build.
                 track?.asset?.(destination)
-                const from = path.dirname(entity.destination || '/')
-                return { url: path.relative(from, destination), name }
+                return { url: siteRelativeUrl(entity.destination, destination, options?.siteRoots), name }
             }
         }
     }

package/src/references.js

@@ -25,6 +25,7 @@ import path from 'node:path'
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { globby } from 'globby'
+import { siteRootFor } from './utils.js'
 
 // Documents that can carry a reference. Anything else in the output is either
 // an asset itself or something whose internal structure this has no business
@@ -82,6 +83,8 @@ function decodeEntities(source) {
 }
 
 // Everything a page points at, as raw url strings.
+export { siteRootFor }
+
 export function extractReferences(rawSource) {
     const source = decodeEntities(rawSource)
     const found = new Set()
@@ -111,30 +114,17 @@ export function resolveUrl(pageDir, url, { root = '' } = {}) {
     const segments = clean.split('/').filter(s => s !== '' && s !== '.')
 
     const parts = absolute ? [] : pageDir.split('/').filter(Boolean)
-    let overDeep = false
+    // How FAR above the root it climbed, not merely that it did. When every
+    // over-deep url on a site climbs the same distance, that is one base
+    // mismatch reported once — not N findings, which is how a real signal gets
+    // filtered.
+    let floored = 0
     for (const segment of segments) {
         if (segment !== '..') { parts.push(segment); continue }
         if (parts.length) parts.pop()
-        else overDeep = true      // a climb above the root, floored
-    }
-    return { target: path.join(root, ...parts), overDeep }
-}
-
-// Which declared site root a file belongs to.
-//
-// lmed emits one subtree per language and deploys each as its own domain root
-// (out/bg becomes lmed.bg), so the site root is out/<lang>/ and every url
-// carries one extra `..` for the language segment that the browser then floors.
-// Resolving against the output root instead would miss the over-escape entirely
-// and report working urls as broken. Nothing can derive this — it is deployment
-// intent — so it is declared, and the default is the output root itself.
-export function siteRootFor(relativeFile, roots) {
-    let best = ''
-    for (const root of roots) {
-        if (!root) continue
-        if (relativeFile.startsWith(`${root}/`) && root.length > best.length) best = root
+        else floored++            // a climb above the root, discarded
     }
-    return best
+    return { target: path.join(root, ...parts), overDeep: floored > 0, floored }
 }
 
 // Everything the output points at that is not there.
@@ -150,7 +140,7 @@ export async function checkReferences(outputFolder, { siteRoots = [] } = {}) {
     })
 
     const broken = new Map()
-    const overDeep = new Map()
+    const overDeepRefs = new Map()
     let checked = 0
     // Existence is the expensive part and the same target repeats across a
     // site — one lookup each.
@@ -166,7 +156,7 @@ export async function checkReferences(outputFolder, { siteRoots = [] } = {}) {
         const pageDir = path.dirname(file).slice(root.length).replace(/^\/+/, '')
 
         for (const url of extractReferences(source)) {
-            const { target, overDeep: floored } = resolveUrl(pageDir, url, { root })
+            const { target, overDeep, floored } = resolveUrl(pageDir, url, { root })
             checked++
 
             if (!exists.has(target)) {
@@ -174,14 +164,14 @@ export async function checkReferences(outputFolder, { siteRoots = [] } = {}) {
             }
             // Broken outranks over-deep: a url that resolves nowhere is the
             // failure, and adding that it is also one level too deep is noise.
-            const bucket = !exists.get(target) ? broken : (floored ? overDeep : null)
+            const bucket = !exists.get(target) ? broken : (overDeep ? overDeepRefs : null)
             if (!bucket) continue
 
             const key = `${target} ${url}`
-            if (!bucket.has(key)) bucket.set(key, { url, target, files: [] })
+            if (!bucket.has(key)) bucket.set(key, { url, target, floored, files: [] })
             bucket.get(key).files.push(file)
         }
     }
 
-    return { broken: [...broken.values()], overDeep: [...overDeep.values()], checked }
+    return { broken: [...broken.values()], overDeep: [...overDeepRefs.values()], checked }
 }

package/src/utils.js

@@ -1343,3 +1343,50 @@ export function matchesLibrary(value, pattern) {
     }
     return libraryPatterns.get(pattern).test(value)
 }
+
+// Which declared site root a path belongs to.
+//
+// A build can emit one subtree per language and deploy each as its own domain
+// root, which puts the site root at out/<lang>/ rather than at out/. Nothing
+// can derive that — it is a fact about where the bytes get deployed, not about
+// the bytes — so it is declared as `siteRoots` and the default is the output
+// root itself. Accepts a path with or without a leading slash, because an
+// entity destination has one and an output-relative file path does not.
+export function siteRootFor(file, roots = []) {
+    const relative = String(file ?? '').replace(/^\/+/, '')
+    let best = ''
+    for (const root of roots) {
+        if (!root) continue
+        if (relative.startsWith(`${root}/`) && root.length > best.length) best = root
+    }
+    return best
+}
+
+// A page-relative url from one output destination to another, addressed within
+// the site the page belongs to.
+//
+// Both are output-root absolute (`/bg/aparati/index.html`, `/derived/x.webp`),
+// which is the only shape the engine has. With one site per build that is also
+// the deployed root and this is a plain path.relative. With several, it is not:
+// out/bg IS the domain root, so a url computed against out/ carries one extra
+// `..` for the language segment. The browser floors that rather than failing,
+// which is why it worked and why nothing said so.
+//
+// Three cases, and the middle one is the reason this is not a one-liner:
+//
+//   target outside every root   a shared asset. It has to be reachable from
+//                               inside this page's site, so it is addressed
+//                               there — this is the case that was wrong.
+//   target in the same root     already correct; a plain relative path.
+//   target in a DIFFERENT root  a cross-site link. On a per-domain deploy the
+//                               other site is another origin and no relative
+//                               path reaches it. Left as it was, so the
+//                               reference check reports it broken instead of
+//                               this silently inventing a path that is not.
+export function siteRelativeUrl(pageDestination, target, siteRoots = []) {
+    const from = path.dirname(pageDestination || '/')
+    const pageRoot = siteRootFor(pageDestination, siteRoots)
+    if (!pageRoot) return path.relative(from, target)
+    if (siteRootFor(target, siteRoots)) return path.relative(from, target)
+    return path.relative(from, path.join('/', pageRoot, target))
+}