mikser-io 9.19.0 → 9.20.0

package/docs/diagnostics.md

@@ -106,9 +106,16 @@ there is no manifest to check against.
 npx mikser --verify || echo "output folder has drifted"
 ```
 
-`Orphan` is the one to read carefully — it is normal for files that
-another plugin writes (assets, files, data), and a real signal for a page
-whose layout stopped producing it.
+A destination is resolved against the output folder first and, when that
+finds nothing, treated as a filesystem path — assets carry an absolute
+destination built from `assetsFolder`, which may sit outside the output
+folder entirely.
+
+`Orphan` still needs reading with that in mind: only files under the
+output folder are walked, and a file is an orphan when no snapshot claims
+it. That is normal for anything written without a render snapshot (the
+`files` and `data` plugins), and a real signal for a page whose layout
+stopped producing it.
 
 ### The rest, briefly
 

package/package.json

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

package/src/database/index.js

@@ -331,6 +331,11 @@ export function createSqliteDatabase({
             logger: logger ?? null,
         }
 
+        // Published so plugins can tell an everything-was-evaluated cycle
+        // from an incremental one without reaching into the db handle. Read
+        // through `isFullCycle()` in utils.js rather than directly.
+        runtime.options.firstRun = provisioningCtx.firstRun
+
         // Fire provisioning callbacks before schema apply, so they can
         // load runtime extensions (sqlite-vec's vec0, etc.) that the
         // schemas about to apply might reference, register custom

package/src/engine.js

@@ -265,8 +265,15 @@ export async function setup(options) {
             for (const e of unverifiable) logger.warn('No hash:    %s (entity %s)', e.destination, e.id)
             for (const e of orphaned)    logger.warn('Orphan:     %s', e.path)
 
+            // Level picked from the verdict, because the level IS the marker
+            // in pino-pretty's messageFormat: notice renders 🟢, warn 🟡,
+            // error 🔴. A fixed `notice` prints a green tick next to the word
+            // FAIL, which reads as success at a glance even though the exit
+            // code is right.
             const verdict = errors > 0 ? 'FAIL' : (warnings > 0 ? 'WARN' : 'OK')
-            logger.notice('Verify %s: %d snapshots, %d missing, %d mismatched, %d unverifiable, %d orphaned',
+            const report = errors > 0 ? logger.error : (warnings > 0 ? logger.warn : logger.notice)
+            report.call(logger,
+                'Verify %s: %d snapshots, %d missing, %d mismatched, %d unverifiable, %d orphaned',
                 verdict, total, missing.length, mismatched.length, unverifiable.length, orphaned.length)
             process.exit(errors > 0 ? 2 : (warnings > 0 ? 1 : 0))
         }

package/src/manifest.js

@@ -66,7 +66,10 @@ import { useDatabase, registerSchema } from './database/index.js'
 // PK index, no separate id index needed. Parent index is for pagination
 // cleanup (drop all children of X). WITHOUT ROWID keeps the file
 // smaller.
-registerSchema('mikser_snapshots', `
+// Exported so tests build against the real schema rather than a copy. A
+// copy drifts the moment a column is added, and the failure is a bare
+// SQLITE_ERROR that names nothing.
+export const SNAPSHOTS_SCHEMA = `
     CREATE TABLE IF NOT EXISTS mikser_snapshots (
         id          TEXT NOT NULL,
         destination TEXT NOT NULL,
@@ -78,7 +81,8 @@ registerSchema('mikser_snapshots', `
         PRIMARY KEY (id, destination)
     ) WITHOUT ROWID;
     CREATE INDEX IF NOT EXISTS idx_mikser_snapshots_parent ON mikser_snapshots(parent) WHERE parent IS NOT NULL;
-`)
+`
+registerSchema('mikser_snapshots', SNAPSHOTS_SCHEMA)
 
 // Module-level DB handle + prepared statements for the lifecycle
 // integration. Tests build their own via `createManifest(db)` —
@@ -186,9 +190,34 @@ function snapToRow(snap) {
     }
 }
 
-async function hashOutputFile(destination) {
+// Where a `destination` actually is on disk.
+//
+// Two shapes are in circulation and both are legitimate. A page's is
+// output-relative with a leading slash (`/bg/index.html`); an asset's is a
+// real filesystem path, because assets.js builds it from
+// `runtime.options.assetsFolder`, which resolves inside the WORKING folder
+// and can sit outside outputFolder entirely.
+//
+// `path.isAbsolute` cannot separate them — on POSIX `/bg/index.html` is
+// absolute too — so resolve by EXISTENCE, output-relative first since that
+// is the dominant shape. A page destination treated as a filesystem path
+// would otherwise be looked for at the root of the disk.
+//
+// Shared, because the two callers needing it drifted into two separate
+// bugs: verify() reported every asset missing while printing its real
+// path, and hashOutputFile silently recorded no outputHash for one, which
+// left 78% of a real project's snapshots presence-checked only.
+export function resolveOutputPath(destination, outputFolder = runtime.options?.outputFolder) {
     if (!destination) return undefined
-    const filePath = path.join(runtime.options.outputFolder, destination)
+    const joined = path.join(outputFolder ?? '', destination)
+    if (existsSync(joined)) return joined
+    if (path.isAbsolute(destination) && existsSync(destination)) return destination
+    return joined
+}
+
+async function hashOutputFile(destination) {
+    const filePath = resolveOutputPath(destination)
+    if (!filePath) return undefined
     try {
         const buf = await readFile(filePath)
         return sha1(buf)
@@ -548,8 +577,17 @@ export function createManifest(db) {
             for (const row of stmtSelectAll.iterate()) {
                 const snap = rowToSnap(row)
                 if (!snap.destination) continue
-                claimed.add(snap.destination.replace(/^\/+/, ''))
-                const filePath = path.join(outputFolder, snap.destination)
+                const filePath = resolveOutputPath(snap.destination, outputFolder)
+                // Orphan detection compares against a globby walk of
+                // outputFolder, so `claimed` has to hold exactly the relative
+                // form that walk produces. A destination resolving outside
+                // outputFolder can never appear in it and is not claimable;
+                // one inside it must be claimed by its relative path, not by
+                // the raw string with its leading slashes stripped.
+                const relative = path.relative(outputFolder, filePath)
+                if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
+                    claimed.add(relative)
+                }
                 if (!existsSync(filePath)) {
                     missing.push({ id: snap.id, destination: snap.destination })
                     continue

package/src/plugins/assets.js

@@ -6,6 +6,7 @@ import { globby } from 'globby'
 import _ from 'lodash'
 import map from 'p-map'
 import { reportWarning } from '../report.js'
+import { isFullCycle } from '../utils.js'
 
 // Normalize a `options.presets[name]` value to a consistent
 // { matches, options } shape so callers don't have to inspect which form
@@ -120,6 +121,14 @@ export function assets(options = {}) {
         if (matchTally.reported) return
         const configured = Object.keys(options.presets || {})
         if (!configured.length || !matchTally.evaluated) return
+        // Only when the cycle evaluated everything. On an incremental run the
+        // evaluated set is whatever changed, so a healthy preset matches
+        // nothing in a run of two and the warning fires on every build —
+        // which trains the reader to filter it, and the filtered-out line is
+        // the real one. The message already told the reader to use --force to
+        // check the whole catalog; that condition gates it now instead of
+        // annotating it.
+        if (!isFullCycle(runtime)) return
         matchTally.reported = true
 
         for (const preset of configured) {
@@ -129,8 +138,7 @@ export function assets(options = {}) {
             logger.warn(
                 'Assets preset %j matched none of the %d entities evaluated (patterns: %s). ' +
                 'Patterns run against entity.id, which files({ outputFolder }) does NOT prefix — ' +
-                'the prefix appears on name and meta.url only. On an incremental run unchanged ' +
-                'entities are not re-evaluated; use --force to check the whole catalog.',
+                'the prefix appears on name and meta.url only.',
                 preset, matchTally.evaluated, matches.join(', '))
         }
     }

package/src/utils.js

@@ -990,6 +990,29 @@ export async function writeOutput(file, bytes) {
     return true
 }
 
+// Did this cycle evaluate the whole corpus, or only what changed?
+//
+// The distinction is what makes a "declared X matched nothing" warning
+// worth printing. On an incremental cycle only changed entities are
+// re-evaluated, so a pattern or preset legitimately matches nothing in a
+// run of two — printing it there means the warning fires on every healthy
+// build, and a warning that always fires is one people filter out, taking
+// the real instance with it.
+//
+// True for: --force, a first-run or wiped database, and a cache
+// invalidation. Those are exactly the cases where the import gate is
+// bypassed and every entity is presented for evaluation.
+// Takes the runtime rather than reading the singleton, so a plugin passes
+// the one it was injected with — which is the singleton in a real build and
+// the harness's stand-in under test.
+export function isFullCycle(rt = runtime) {
+    return !!(
+        rt?.options?.force
+        || rt?.options?.firstRun
+        || rt?.catalog?.cacheInvalidated
+    )
+}
+
 // ── operating-system and file-manager litter ────────────────────────────
 //
 // Exposing a source folder over a network filesystem (mikser-io-webdav) or