mikser-io 9.40.0 → 9.40.2

package/package.json

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

package/src/explain.js

@@ -228,6 +228,16 @@ export async function explain(reference) {
                     : 'unknown',
             outputHash: snap.outputHash ?? null,
             parent: snap.parent ?? null,
+            // Which keys of its OWN meta the render read, and which keys it
+            // read off OTHER entities.
+            //
+            // refClosure answers "what would re-render this". These answer
+            // "what does it actually use", which is the question behind a
+            // document that renders to a hole: a key the layout never touches
+            // is either a typo or dead weight, and nothing else on this report
+            // distinguishes them. Empty when the catalog predates the record.
+            metaReads: snap.metaReads ?? [],
+            consumedReads: (snap.consumedReads ?? []).map(([id, keys]) => ({ entity: id, keys })),
             refClosure: (snap.refClosure ?? []).map(entry =>
                 entry.kind === 'query'
                     ? {
@@ -383,6 +393,22 @@ export function formatExplain(report) {
             const gone = e.gone?.length ? '  [TARGET DELETED SINCE]' : ''
             out.push(`  ${e.kind.padEnd(10)} ${e.target}${bound}${e.hash ? `  ${e.hash}` : ''}${gone}`)
         }
+
+        // What the render actually READ, as against what would re-render it.
+        // Capped, because a large page reads a lot and a wall of keys buries
+        // the rest of the report — the full list is in --json.
+        const SHOWN = 12
+        const shown = (keys) => keys.length > SHOWN
+            ? `${keys.slice(0, SHOWN).join(', ')} … +${keys.length - SHOWN} more`
+            : keys.join(', ')
+        if (r.metaReads?.length) {
+            row('metaReads', `${r.metaReads.length} key${r.metaReads.length === 1 ? '' : 's'} of its own meta`)
+            out.push(`             ${shown(r.metaReads)}`)
+        }
+        for (const c of r.consumedReads ?? []) {
+            row('consumed', `${c.entity}  (${c.keys.length})`)
+            out.push(`             ${shown(c.keys)}`)
+        }
     }
 
     out.push('')

package/src/render.js

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync } from 'node:fs'
 import { readFile, unlink } from 'node:fs/promises'
 import { createRequire } from 'node:module'
-import { createTrack, recordReads, serializeTrack } from './track.js'
+import { createTrack, recordReads, serializeTrack, observeConsumed } from './track.js'
 import { randomUUID } from 'node:crypto'
 import path from 'node:path'
 import _ from 'lodash'
@@ -110,7 +110,8 @@ export default async ({ entity, options, config, context, state, logger, port, t
     // so the worker makes its own track here and returns its CONTENTS with the
     // result, where the engine folds them into the real one.
     const ownTrack = !track
-    track = track ?? createTrack({ meta: options?.metaReads !== false })
+    track = track ?? createTrack({ meta: options?.metaReads !== false,
+                                   consumed: options?.metaReads !== false })
 
     logger = logger || {
         info(...args) {
@@ -259,7 +260,20 @@ export default async ({ entity, options, config, context, state, logger, port, t
                 : typeof result.id === 'string' ? [result.id]
                 : Object.values(result).map(e => e?.id).filter(Boolean)
             track?.lookup?.(href, ids)
-            return result
+            // The entity goes to the TEMPLATE, which then reads fields off it.
+            // Recording those against the entity they belong to is what gives a
+            // document that never renders a contract — and this is the second
+            // way one reaches a render, alongside a sidecar's findEntity.
+            //
+            // `lookupUrl` needs no equivalent: it hands back a URL string, so
+            // nothing is ever read off an entity by the caller.
+            if (!result) return result
+            if (typeof result.id === 'string') return observeConsumed(result, track)
+            const observedByLang = {}
+            for (const [lang, row] of Object.entries(result)) {
+                observedByLang[lang] = row?.id ? observeConsumed(row, track) : row
+            }
+            return observedByLang
         },
         // Resolve a served-entity reference to its deployed URL, absolute
         // when runtime.options.url is set (ADR-0011).