mikser-io 9.80.0 → 9.81.0

package/app.js

@@ -47,6 +47,12 @@ function locate(argv) {
 
     return {
         longRunning,
+        // The flags this process was invoked with, forwarded so the INSTANCE
+        // can reject an unknown one. This pre-parser reads the few options it
+        // needs and passes the rest along, so commander never runs on a
+        // forwarded invocation — and a typo was accepted in silence, built,
+        // and reported success.
+        argv,
         workingFolder: value('--working-folder', '-i') ?? '.',
         config: value('--config', '-c') ?? 'mikser.config.js',
         request,
@@ -74,7 +80,7 @@ async function main() {
         const code = await forward({
             workingFolder,
             config: path.resolve(where.workingFolder, where.config),
-            request: where.request,
+            request: { ...where.request, argv: where.argv },
         })
         // null means nobody was listening — carry on exactly as before.
         if (code !== null) process.exit(code)

package/docs/diagnostics.md

@@ -914,9 +914,12 @@ surfaces that turn silence into a statement:
   evidence:
   - **The emitted output**, read back and resolved the way a browser
     would — `src`, `href`, `poster`, `srcset` and CSS `url()` across
-    html and css. Anything resolving to no file warns under
-    `reference-broken`, naming the url and the pages carrying it. This
-    one sees paths written by hand, not just helper output.
+    html and css. This one sees paths written by hand, not just helper
+    output, and it separates two problems that share a symptom:
+    `reference-wrong-base` when the file exists elsewhere in the output
+    (the url was built from the wrong root, and the report names where
+    the file actually is), `reference-broken` when nothing produced it
+    at all.
   - **The render track**, which records every `asset()` / `resource()`
     call and tests the destination it built. This catches a url that
     never reaches an html file at all — one emitted into a feed or a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.80.0",
+  "version": "9.81.0",
   "files": [
     "app.js",
     "index.js",

package/src/engine.js

@@ -116,15 +116,31 @@ async function reportBrokenReferences(logger) {
     const named = (files) =>
         files.slice(0, 3).join(', ') + (files.length > 3 ? ` and ${files.length - 3} more` : '')
 
-    for (const { url, target, files } of broken.slice(0, SHOWN)) {
-        logger.warn({ code: 'reference-broken', url, target, files },
-            'Resolves to nothing: %s (from %s) — %s', url, named(files), target)
+    for (const { url, target, files, elsewhere } of broken.slice(0, SHOWN)) {
+        // Two different problems wear the same symptom. A target whose file
+        // exists elsewhere in the output is a base that is wrong, not an asset
+        // that is missing — and saying which one saves the reader the search.
+        if (elsewhere?.length) {
+            logger.warn({ code: 'reference-wrong-base', url, target, files, elsewhere },
+                'Points at the wrong place: %s (from %s) — nothing at %s, but the file is at %s',
+                url, named(files), target, elsewhere.join(', '))
+        } else {
+            logger.warn({ code: 'reference-broken', url, target, files },
+                'Resolves to nothing, and nothing produced it: %s (from %s) — %s',
+                url, named(files), target)
+        }
     }
     if (broken.length) {
-        logger.warn({ code: 'reference-broken-summary', broken: broken.length, checked },
-            '%d of %d reference(s) in the output resolve to nothing%s. A URL helper builds the '
-            + 'path rather than looking it up, so these are links to files nothing produced.',
-            broken.length, checked, broken.length > SHOWN ? `, ${SHOWN} shown` : '')
+        const misplaced = broken.filter(b => b.elsewhere?.length).length
+        logger.warn({
+            code: 'reference-broken-summary',
+            broken: broken.length, wrongBase: misplaced, checked,
+        },
+            '%d of %d reference(s) in the output resolve to nothing%s. Wrong base (the file exists '
+            + 'elsewhere): %d. Never produced: %d. A URL helper builds the path rather than looking '
+            + 'it up, so neither kind can fail at the point it is written.',
+            broken.length, checked, broken.length > SHOWN ? `, ${SHOWN} shown` : '',
+            misplaced, broken.length - misplaced)
     }
 
     // Grouped by how FAR each climbed, because a site whose every over-deep url

package/src/instance.js

@@ -286,6 +286,39 @@ function refuseConfig(socket, request, wrongConfig) {
     })
 }
 
+// An option the instance's own commander does not recognise.
+//
+// A forwarded invocation never reaches commander: app.js pre-parses the few
+// flags it needs and forwards the rest, so `mikser --bogus` against a running
+// watcher built normally and exited 0, while the same command with nothing
+// listening was rejected outright. Same words, two answers, and the quiet one
+// is the one that looks like it worked.
+//
+// parseOptions REPORTS unknowns without applying anything, which is what makes
+// this safe to run against the live instance's option table.
+function refuseUnknownFlags(socket, request) {
+    const argv = Array.isArray(request.argv) ? request.argv : null
+    if (!argv?.length) return false
+    const commander = runtime.engine?.commander
+    if (!commander) return false
+    let unknown = []
+    try {
+        unknown = commander.parseOptions([...argv]).unknown ?? []
+    } catch {
+        return false   // never let a probe refuse a legitimate build
+    }
+    unknown = unknown.filter(a => a.startsWith('-'))
+    if (!unknown.length) return false
+    frame(socket, {
+        type: 'refused',
+        reason: `unknown option ${unknown.map(u => `'${u}'`).join(', ')}.`,
+        detail: 'Forwarded to the instance running in this folder, which does not recognise it. '
+            + 'The same command with nothing listening would have been rejected too — this says so '
+            + 'rather than building as though the flag had been understood.',
+    })
+    return true
+}
+
 function refuseStale(socket, movedFile) {
     frame(socket, {
         type: 'refused',
@@ -373,6 +406,7 @@ export function serveInstance() {
                     // instance's — a report against the wrong config is the
                     // original incident, and it is wrong whether or not it
                     // writes anything.
+                    if (refuseUnknownFlags(socket, request)) return
                     const wrongConfig = configMismatch(request.config)
                     if (wrongConfig) return refuseConfig(socket, request, wrongConfig)
                     const movedFile = await configStale()

package/src/references.js

@@ -173,5 +173,31 @@ export async function checkReferences(outputFolder, { siteRoots = [] } = {}) {
         }
     }
 
+    // "It was never written" and "it is written somewhere else" are different
+    // problems with one symptom, and they were reported with one sentence.
+    //
+    // A missing target whose FILE exists elsewhere in the output is almost
+    // always a base problem: the url was built from the wrong root, or with a
+    // segment too many. Naming where the file actually is turns "resolves to
+    // nothing" into the answer. A target that exists nowhere really was never
+    // produced — a preset that did not run, an extension nothing emits.
+    //
+    // Indexed only when something is broken, so a clean build pays nothing.
+    if (broken.size) {
+        const byName = new Map()
+        for (const file of await globby('**/*', {
+            cwd: outputFolder, followSymbolicLinks: true, onlyFiles: true, suppressErrors: true,
+        })) {
+            const name = path.basename(file)
+            if (!byName.has(name)) byName.set(name, [])
+            byName.get(name).push(file)
+        }
+        for (const entry of broken.values()) {
+            const elsewhere = (byName.get(path.basename(entry.target)) ?? [])
+                .filter(f => f !== entry.target)
+            if (elsewhere.length) entry.elsewhere = elsewhere.slice(0, 3)
+        }
+    }
+
     return { broken: [...broken.values()], overDeep: [...overDeepRefs.values()], checked }
 }