mikser-io 9.21.0 → 9.22.0

package/docs/diagnostics.md

@@ -59,20 +59,39 @@ snapshot: if you have edited a file and not yet built, the verdict is
 `source differs from the catalog` — the edit has not been imported yet, so
 there is nothing to attribute. Build, then ask.
 
-Each `refClosure` edge shows the name that was asked for and the entity
-it bound to, and flags the ones that bound to nothing:
+Each `refClosure` edge shows what was asked for and what answers to it,
+and flags the ones nothing answers to:
 
 ```
-refClosure  4 edges
+refClosure  6 edges
   ref        /hero.txt → /files/hero.txt  24dc5b87
   ref        /does-not-exist  [UNRESOLVED — nothing answers to this name]
   layout     /layouts/page.hbs  f274678c
   lookup     /contacts  [UNRESOLVED — nothing answers to this name]
+  query      {"meta.href":"/system/navigation"}  → /documents/navigation.yml
+  query      {"meta.href":"/cosmetics/celestetic"}  [MATCHES NOTHING]
 ```
 
-An `[UNRESOLVED]` edge is usually the answer on its own. Add `--json` for
-the same report as a machine-readable object. Exits `3` when the entity
-cannot be found.
+A dangling edge is usually the answer on its own, and `query` edges are
+where most of it hides on a site whose references go through a sidecar's
+`findEntity` — there, `ref` and `lookup` may be zero and `query`
+everything.
+
+Query counts are computed when you ask, not when the edge was recorded.
+That is deliberate: an edge stores the filter WITHOUT its results, so an
+entity appearing tomorrow still invalidates the page that links to it
+today. An edge that recorded its bindings would record nothing for a query
+matching nothing, and creating the target later would re-render nothing.
+
+In `--json`, every query edge carries `matched` explicitly — an integer,
+or `null` for a predicate that could not be serialized (`findEntities()`
+with no argument, or a function filter), which invalidates on any mutation
+by design. `matched: 1` also carries `sample` with the id. The field is
+always present, so a consumer never has to read absence as meaning
+anything.
+
+Add `--json` for the whole report as a machine-readable object. Exits `3`
+when the entity cannot be found.
 
 ### `--json`
 

package/index.js

@@ -50,11 +50,11 @@ 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.
+// to call. They render nothing, and the names say so: two of the six
+// factories in this folder are renderers and four are not, so each is named
+// after the job it does rather than the object it concerns. Naming them all
+// `render*` invites adding renderPreset() expecting a helper and watching
+// every page render throw. There are no aliases for the older names.
 export { assetUrlHelper }    from './src/plugins/render/asset.js'
 export { hrefUrlHelpers }    from './src/plugins/render/href.js'
 export { resourceUrlHelper } from './src/plugins/render/resource.js'

package/package.json

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

package/src/catalog.js

@@ -360,8 +360,10 @@ onFinalize(async () => {
     }
 })
 
-// Snapshot the catalog as `{ version, entities: [...] }`. Same shape
-// the NDJSON test harness used to read off disk. O(N) — debug only.
+// Snapshot the catalog as `{ version, entities: [...] }` — the schema
+// version plus every entity body. O(N) in both time and memory, so it is
+// for debugging and inspection, never a hot path; `iterateEntities`
+// streams when the result set might be corpus-scale.
 function exportCatalog() {
     if (!db?.isOpen) return { version: null, entities: [] }
     const rows = stmtAllData.all()

package/src/config.js

@@ -56,11 +56,9 @@ onLoad(async () => {
         }
     }
 
-    // v8 used to walk `runtime.config.plugins` looking for matching
-    // `config/<plugin>.config.js` files to merge into `runtime.config`,
-    // because plugin entries were strings (names). v9 entries are factory
-    // call results (closures or descriptors), and plugin options arrive
-    // as factory args — see ADR-0010 — so per-plugin auxiliary config
-    // files have nothing to bind to. The loader was removed when the
-    // plugins list stopped carrying names.
+    // Nothing else is loaded. There is deliberately no `config/<plugin>
+    // .config.js` channel: plugin options arrive as factory arguments
+    // (ADR-0010), and an entry in `plugins` is a factory call result — a
+    // closure or a descriptor — carrying no name to bind an auxiliary file
+    // to. A plugin wanting file-based config reads it itself.
 })

package/src/explain.js

@@ -9,7 +9,8 @@
 //
 // Follows --verify's shape: report and exit, no build phases run.
 import { inputHashOf, inputPartsOf, diffInputParts, lookupKeys, checksum as fileChecksum } from './utils.js'
-import { findEntity } from './catalog.js'
+import { filterKey } from './track.js'
+import { findEntity, findEntities } from './catalog.js'
 import runtime from './runtime.js'
 
 const shortHash = (h) => (h ? String(h).slice(0, 8) : null)
@@ -28,6 +29,62 @@ async function resolve(reference) {
     return like ?? null
 }
 
+// How many entities each recorded query filter matches RIGHT NOW.
+//
+// A query edge is a predicate — "any entity matching this" — and the
+// recording layer deliberately stores the filter without its results, so
+// that an entity appearing later still invalidates the render. That is the
+// property that makes aggregate pages work and it must not change.
+//
+// Explaining is a different situation: read-only, reporting instead of
+// building, with the catalog already open. So the count is computed here,
+// at read time, where it costs nothing and answers "is this reference
+// dangling?" for the edge kind that carries most of a real site's
+// references.
+//
+// Run through findEntities rather than hand-rolled SQL: stored filters
+// include $regex and anything else sift accepts, and one code path is the
+// only way the count means the same thing the render meant.
+//
+// A null filter is the sentinel for a predicate that could not be
+// serialized (a function filter, or findEntities() with no argument). It
+// invalidates on any mutation by design, and there is nothing to evaluate,
+// so it reports null rather than a misleading zero.
+async function countQueryMatches(snapshots) {
+    const counts = new Map()
+    for (const snap of snapshots) {
+        for (const entry of snap.refClosure ?? []) {
+            if (entry.kind !== 'query') continue
+            const key = filterKey(entry.filter ?? null)
+            if (counts.has(key)) continue
+            if (entry.filter == null) {
+                counts.set(key, null)
+                continue
+            }
+            try {
+                // recordQuery no-ops outside a render's queryContext, so
+                // explaining a page cannot record edges onto it.
+                const matches = await findEntities(entry.filter)
+                counts.set(key, { count: matches.length, sample: matches[0]?.id ?? null })
+            } catch {
+                // A stored filter the catalog can no longer evaluate is worth
+                // saying so about, not worth failing the whole report for.
+                counts.set(key, 'unevaluable')
+            }
+        }
+    }
+    return counts
+}
+
+// Project a counted filter into the report's shape.
+function queryCount(counts, filter) {
+    const hit = counts.get(filterKey(filter ?? null))
+    if (hit === null) return { matched: null }
+    if (hit === 'unevaluable') return { matched: null, unevaluable: true }
+    if (!hit) return { matched: null }
+    return { matched: hit.count, ...(hit.count === 1 && hit.sample ? { sample: hit.sample } : {}) }
+}
+
 // The verdict line names what moved when it can. That line is the one
 // people read, so "the input hash differs" there is the answer stopping one
 // step short of useful.
@@ -60,6 +117,7 @@ export async function explain(reference) {
     const snapshots = runtime.manifest?.snapshotsFor(entity.id) ?? []
     const currentHash = inputHashOf(entity)
     const currentParts = inputPartsOf(entity)
+    const queryMatches = await countQueryMatches(snapshots)
 
     // The catalog is as of the LAST BUILD. If the file has been edited since,
     // nothing here knows it yet — the hashes would all agree and the verdict
@@ -141,7 +199,17 @@ export async function explain(reference) {
             parent: snap.parent ?? null,
             refClosure: (snap.refClosure ?? []).map(entry =>
                 entry.kind === 'query'
-                    ? { kind: 'query', filter: entry.filter }
+                    ? {
+                        kind: 'query',
+                        filter: entry.filter,
+                        // An explicit integer, because a MISSING key is
+                        // ambiguous to a consumer: an audit script reading
+                        // absence as "unresolved" reports every query edge
+                        // as dangling. `null` means the filter could not be
+                        // evaluated (unserializable predicate); a number is
+                        // a number.
+                        ...queryCount(queryMatches, entry.filter),
+                    }
                     : {
                         kind: entry.kind,
                         target: entry.target,
@@ -222,7 +290,16 @@ export function formatExplain(report) {
         row('refClosure', `${closure.length} edge${closure.length === 1 ? '' : 's'}`)
         for (const e of closure) {
             if (e.kind === 'query') {
-                out.push(`  query      ${JSON.stringify(e.filter)}`)
+                // The count is the point: a query matching nothing is the
+                // dangling-reference case for the edge kind that carries most
+                // of a real site's references, and it printed identically to
+                // one that matched.
+                const state = e.unevaluable ? '  [FILTER CANNOT BE EVALUATED]'
+                    : e.matched === null ? '  (untracked predicate — any mutation invalidates)'
+                    : e.matched === 0 ? '  [MATCHES NOTHING]'
+                    : e.matched === 1 ? `  → ${e.sample ?? '1 entity'}`
+                    : `  → ${e.matched} entities`
+                out.push(`  query      ${JSON.stringify(e.filter)}${state}`)
                 continue
             }
             // Show the name asked for and the entity it bound to, since

package/src/manifest.js

@@ -225,10 +225,11 @@ function snapToRow(snap) {
 // 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.
+// One definition for both callers. verify() and hashOutputFile ask the same
+// question, and a private copy of the join in each is how one mistake
+// becomes two symptoms — one loud (every asset reported missing, at its
+// real and present path) and one silent (no outputHash recorded, leaving
+// most snapshots presence-checked only).
 export function resolveOutputPath(destination, outputFolder = runtime.options?.outputFolder) {
     if (!destination) return undefined
     const joined = path.join(outputFolder ?? '', destination)

package/src/plugins/api.js

@@ -607,8 +607,9 @@ export function api(options = {}) {
             // credential declaring `api:delete` still cannot delete on an
             // endpoint whose `operations` omits it, and a bare token (which
             // declares nothing, capabilities === null) is bounded by the
-            // endpoint alone — which is exactly how every endpoint behaved
-            // before this existed.
+            // endpoint alone, which is what makes a plain token still a
+            // complete answer: it grants the endpoint's own ceiling and
+            // nothing more.
             const allow = (op) => (req, res, next) => {
                 if (!allowedOps.has(op)) {
                     return res.status(403).json({

package/src/plugins/render/preset.js

@@ -15,8 +15,8 @@ import path from 'node:path'
 //   assets()        runs presets and produces derivatives   (the work)
 //   renderPreset()  renders a preset-authored layout        (this file)
 //
-// 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.
+// The URL helpers carry `Helper` in their names for exactly this reason;
+// renderPreset keeps its bare 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/postprocess.js

@@ -253,10 +253,10 @@ export default async ({ entity, options, config, context, state, logger, port })
     }
 
     // Cleanup the renderer's origin (first stage's input) when it's
-    // a different path from the chain's final destination. The
-    // single-stage onComplete in layouts.js used to do this; under
-    // the chain contract the dispatcher owns it so onComplete can
-    // stay disk-write-agnostic for postprocess outputs.
+    // a different path from the chain's final destination. The chain
+    // contract puts this on the dispatcher rather than on layouts'
+    // onComplete, which is what lets onComplete stay agnostic about
+    // whether a postprocess output was written to disk at all.
     if (entity.origin && entity.origin !== entity.destination) {
         try { await unlink(path.join(options.outputFolder, entity.origin)) } catch {}
     }
@@ -264,7 +264,7 @@ export default async ({ entity, options, config, context, state, logger, port })
     // Return undefined so the engine's onPostprocess loop doesn't
     // try to thread `result` back through layouts' onComplete (which
     // would attempt a writeFile against a non-bytes value). The
-    // postprocess plugins wrote directly to disk; there's nothing
-    // for the engine to flush.
+    // postprocess plugins have written directly to disk by this point;
+    // there is nothing for the engine to flush.
     return undefined
 }