mikser-io 9.16.0 → 9.19.0

package/CLAUDE.md

@@ -94,16 +94,39 @@ brevity.
   corpus-scale and the caller doesn't need an array), `queryEntities`,
   `readEntity`, `subscribe`, `assertExpand`. Expand internals
   (`expandLimits`, `expandAndProject`, `findRef`) are PRIVATE.
+  All three readers accept either a sift object or a **function**
+  predicate; a function cannot be pushed into SQL, so it forces a full
+  scan and a JSON.parse per row — prefer an object, and `refFilter(ref)`
+  for the "resolve a ref string" case. `refFilter` / `matchesRef` /
+  `lookupKeys` are one relation in three directions (query, predicate,
+  reverse) and must be changed together: `meta.url` once lived in only
+  the first, which made every `$`-ref to a served path silently
+  non-invalidating. `test/unit/utils.test.js` property-tests the
+  symmetry.
 - `subscriptions.js` — `subscribe()` primitive. Two modes: journal-
   walk dispatch (default) and graph dispatch via
   `runtime.refs.subscribeGraph` (when `expand` is set).
 - `refs.js` — inverse-reference graph (`$`-keyed refs per ADR-0007).
-  Persisted as `mikser_refs` rows with FK to `mikser_entities`
-  (`ON DELETE CASCADE`). Indexed on `target` and `source`. Exposed
-  at `runtime.refs.*`: `inboundFor`, `outboundFor`, `allRefs`,
-  `size`, `rename`, `subscribeGraph`, `inverseClosureOf`. Plus
-  `refExists` module-level. Prepared statements through the shared
-  sqlite handle.
+  Persisted as `mikser_refs` rows with FK on `source_id` to
+  `mikser_entities` (`ON DELETE CASCADE`); indexed on `target_ref`
+  and `target_id`. Each row carries BOTH the string asked for
+  (`target_ref` — an id, `meta.href`, `meta.url`, or id-minus-
+  extension) and the entity it resolved to (`target_id`, `''` when
+  nothing did). Both are load-bearing: a name alone cannot survive the
+  target renaming itself, and an id alone cannot express a forward or
+  dangling reference. `inverseClosureOf` takes the union of a name
+  query and an identity query, so it is a superset of name-only
+  matching. Kinds: `ref` (static `$`-ref, owned by `indexEntity`),
+  and `layout` / `partial` / `query` / `lookup` (render-time, owned by
+  `replaceDynamic`) — the clears divide on `kind = 'ref'` vs
+  `kind != 'ref'`, so a render-time edge must never use `ref`.
+  Exposed at `runtime.refs.*`: `inboundFor`, `outboundFor`,
+  `dynamicInboundFor`, `dynamicOutboundFor`, `allRefs`, `size`,
+  `rename`, `inverseClosureOf`, `resolveRefIds`, `replaceDynamic`,
+  `clearDynamic`, `subscribeGraph`, `subscribeQuery`. Plus `refExists`
+  module-level. `REFS_SCHEMA` is exported so tests build against the
+  real schema instead of a copy. Prepared statements through the
+  shared sqlite handle.
 - `engine.js` — `setup()`, lifecycle wiring, render + postprocess
   dispatchers, manifest tracking. Owns the Piscina worker pools
   (`renderWorkers`, `postprocessWorkers`); both are lazy
@@ -191,6 +214,12 @@ brevity.
 - `constants.js` — `OPERATION` (CREATE/UPDATE/DELETE/RENDER/
   POSTPROCESS), `ACTION` (sync action types), `TASKS` (`INLINE`/
   `SERIAL`/`WORKER` — dispatch modes).
+- `../testing/harness.js` — the in-memory plugin harness, OUTSIDE
+  `src/` because it ships in the package (`.npmignore` excludes
+  `test/`). Sibling plugins import it as
+  `mikser-io/testing/harness.js` rather than copying it; the copies
+  drifted before it moved here. `test/unit/plugin-harness.js` is a
+  re-export for this repo's own tests.
 
 ## Canonical sibling plugins
 
@@ -516,11 +545,15 @@ There is **no `--mcp` CLI flag**. Activation is plugin-presence only.
 
 ## Test suites
 
-- `npm run test:unit` — 363 unit tests across plugins + utilities
-- `npm run test:scenarios` — 18 subprocess-spawned end-to-end runs
-  (manifest skip, refs replay, watch-mode change/delete). Spawns
-  mikser fresh per scenario so module-level catalog/refs/manifest
-  state can't leak between tests.
+- `npm run test:unit` — 540 unit tests across plugins + utilities
+- `npm run test:scenarios` — 96 assertions over 20 subprocess-spawned
+  end-to-end runs (manifest skip, refs replay, watch-mode
+  change/delete, lookup + asset invalidation, unchanged output,
+  `--force`, `--explain`, `--json`). Spawns mikser fresh per scenario
+  so module-level catalog/refs/manifest state can't leak between
+  tests. Scenarios use `freshWorkdir()` in os.tmpdir — never
+  `test/fixture`, which is tracked and must stay byte-identical
+  (`git status --short test/fixture` after any run that builds).
 - `npm run test:smoke` — full lifecycle build of `test/fixture/`
   (with vector + decap + post-mjml + post-pdf if env supports).
   Exercises both INLINE postprocess (PDF) and WORKER postprocess
@@ -531,8 +564,8 @@ There is **no `--mcp` CLI flag**. Activation is plugin-presence only.
 
 ## Dev workspace
 
-The siblings live side-by-side under `/Users/dick/Projects/mikser/`
-and share an npm workspace declared at the parent's `package.json`:
+The siblings live side-by-side in one parent folder and share an npm
+workspace declared at that parent's `package.json`:
 
 ```json
 {
@@ -573,6 +606,10 @@ the consumer's own project tree — no duplication, no bug.
 
 ## Reference
 
+- `docs/diagnostics.md` — "why did it do that?" — `--explain`,
+  `--json`, `--verify`, the sqlite tables, and every introspection
+  surface, indexed by the question it answers. Start here when
+  debugging rather than reading engine source.
 - `docs/architecture.md` — module map (audit before relying
   on specifics; may have drift)
 - `docs/decisions/` — ADRs

package/README.md

@@ -286,6 +286,7 @@ Mikser itself has a previous chapter: the [legacy 7.x line](https://github.com/a
 | [Entities](./docs/entities.md)               | Users & Developers | Entity model, operations, journal, catalog         |
 | [Rendering](./docs/rendering.md)             | Users & Developers | Render pipeline, render plugins, render modes      |
 | [Watch Mode](./docs/watch-mode.md)           | Users              | File watching, scheduled tasks, incremental builds |
+| [Diagnostics](./docs/diagnostics.md)         | Users & Developers | **"Why did it do that?"** — `--explain`, `--json`, `--verify`, the sqlite tables, and every introspection surface, indexed by the question it answers |
 | [MCP](https://github.com/almero-digital-marketing/mikser-io-mcp#readme) | Users              | The `mikser-io-mcp` plugin — tool surface, `mikser://` resources, twelve worked AI-driven scenarios |
 | [Caching](./docs/caching.md)                 | Users (production) | The `cache: true` disk cache + working nginx config for reverse-proxy failover |
 | [Architecture](./docs/architecture.md)       | Developers         | Module-level reference — what's in each file       |

package/docs/diagnostics.md

@@ -0,0 +1,289 @@
+# Diagnostics
+
+The other documents here are organised by subsystem — the lifecycle, the
+catalog, the render pipeline. That is the shape for learning how mikser
+works. This one is organised by the question you arrive with, which is
+almost always a form of *"why did it do that?"*
+
+Every surface below already exists. If answering a question means reading
+engine source, the entry point is missing and belongs on this page.
+
+## Start here
+
+| Your question | Reach for |
+| --- | --- |
+| Why didn't this page rebuild? | [`--explain`](#--explain-entity) |
+| What did this build actually change? | [`--json`](#--json) |
+| Does the output folder match what mikser thinks it wrote? | [`--verify`](#--verify) |
+| What happened during the last cycle, in order? | [`mikser_journal`](#mikser_journal) |
+| What depends on this entity? | [`runtime.refs`](#runtimerefs) |
+| Which layout claimed this document, and why that one? | [`layouts.inspect()`](#layoutsinspect) |
+| Why does this page's output look stale? | [`runtime.manifest`](#runtimemanifest) |
+| Did my schema validate anything at all? | [`schemas.names()`](#schemasnames--schemaslookup) |
+
+## Command line
+
+### `--explain <entity>`
+
+The single most direct answer to "why didn't this rebuild". Reports
+instead of building. Accepts an id, a `meta.href`, or an id without its
+extension — the same three forms a `$`-ref accepts, so you can paste
+whatever you have.
+
+```bash
+npx mikser --explain /documents/en/posts/hello.md
+```
+
+It prints the entity's layout and **why that layout matched**, its
+destination, its `inputHash`, whether the file on disk still agrees with
+the catalog, every recorded render with its `refClosure`, and a verdict
+in plain words — `would be SKIPPED — input hash unchanged`, or `would
+re-render`, or `source file is gone`.
+
+Each `refClosure` edge shows the name that was asked for and the entity
+it bound to, and flags the ones that bound to nothing:
+
+```
+refClosure  4 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]
+```
+
+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.
+
+### `--json`
+
+A build report on stdout, as JSON. Logs and the banner move to stderr
+under this flag, so stdout parses whole.
+
+```bash
+npx mikser --json | jq '.summary'
+```
+
+Four buckets, and the distinction between them is the point:
+
+| Bucket | Meaning |
+| --- | --- |
+| `rendered` | the render ran, with a `reason` per entity |
+| `skipped` | the manifest decided not to render, with a `reason` |
+| `unchanged` | the render ran and produced bytes identical to what was already on disk |
+| `gated` | a count — the source was unchanged, so no render was ever scheduled |
+
+`reason` is a stable vocabulary you can assert on: `unchanged`,
+`never-rendered`, `inputs-changed`, `ref-changed`, `query-matched`,
+`cache-disabled`, `postprocessor`, `force`, `no-manifest`.
+
+`unchanged` is the interesting one. It means invalidation was coarser
+than it needed to be — the render was scheduled, ran, and produced
+nothing new. A high count is not a bug, but it tells you where the
+dependency graph is conservative.
+
+Warnings carry a stable `code` alongside their prose, so a test can
+assert "this build produced no preset-no-match" without grepping a
+sentence someone may later reword.
+
+### `--verify`
+
+Walks the output folder against the recorded snapshots and reports drift
+instead of building. Four categories, and the split matters:
+
+| Category | Meaning | Severity |
+| --- | --- | --- |
+| `Missing` | a snapshot records a destination that is not on disk | error |
+| `Mismatched` | the file's bytes differ from the recorded `outputHash` | error |
+| `No hash` | a snapshot with no recorded hash — nothing to compare | warning |
+| `Orphan` | a file on disk that no snapshot claims | warning |
+
+Exit codes make it usable as a CI gate directly: `2` if anything is
+missing or mismatched, `1` if only warnings, `0` when clean, and `2` when
+there is no manifest to check against.
+
+```bash
+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.
+
+### The rest, briefly
+
+| Flag | Use |
+| --- | --- |
+| `-f, --force` | ignore all three gates (import checksum, dispatch, manifest) and re-render everything |
+| `-R, --resume` | continue from a previous interrupted run's journal; skips the filesystem scan |
+| `-r, --clear` | clear state before running |
+| `-d, --debug` / `-t, --trace` | raise log level; `trace` includes per-entity catalog writes |
+
+`--force` composes with the unchanged-output check: it redoes the work
+without touching files whose bytes did not move, so it is cheap to reach
+for and its `unchanged` count tells you how much of the catalog was stale
+by suspicion rather than in fact.
+
+## The database
+
+Everything mikser knows lives in one SQLite file at
+`<workingFolder>/runtime/mikser.sqlite`. It is readable while a build
+runs (WAL mode) and it is often faster to ask it directly than to add
+logging.
+
+```bash
+sqlite3 runtime/mikser.sqlite
+```
+
+Five tables:
+
+| Table | Holds |
+| --- | --- |
+| `mikser_entities` | the catalog — one row per entity, `data` is the JSON body |
+| `mikser_journal` | the current cycle's operations, in order — cleared per cycle, which is what makes `--resume` possible |
+| `mikser_refs` | the dependency graph, both directions |
+| `mikser_snapshots` | what was rendered, where, and from which inputs |
+| `mikser_meta` | schema version and config checksum, for cache invalidation |
+
+### `mikser_journal`
+
+The ordered record of what the engine did this cycle — one row per
+operation, per consumer. When a build "did nothing" and you cannot see
+why, this is where the absence becomes visible: an entity that was never
+imported has no CREATE, and an entity gated at import has no RENDER.
+
+```sql
+SELECT operation, count(*) FROM mikser_journal GROUP BY operation;
+```
+
+### `mikser_refs`
+
+One row per dependency edge, carrying both the question and the answer:
+
+| Column | Meaning |
+| --- | --- |
+| `source_id` | the entity that depends |
+| `target_ref` | the string it asked for — an id, a `meta.href`, a `meta.url`, or an id minus its extension |
+| `target_id` | the entity that string resolved to, `''` if nothing did |
+| `kind` | `ref` (static `$`-ref), `layout`, `partial`, `query`, `lookup` |
+| `field` | for `ref`, the dotted path in `meta` |
+
+"What breaks if I rename this?" is one query:
+
+```sql
+SELECT source_id, kind, target_ref FROM mikser_refs
+ WHERE target_id = '/documents/en/authors/dick.yml';
+```
+
+A row with `target_id = ''` is a dangling reference — the dependent asked
+for a name nothing currently answers to.
+
+### `mikser_snapshots`
+
+One row per rendered destination: `inputHash` (what it was rendered
+from), `outputHash` (the bytes it produced), `refClosure` (the
+dependencies it recorded), `renderedAt`. An entity can have several — one
+per matched layout, one per paginated page.
+
+## From inside a plugin or a REPL
+
+### `runtime.refs`
+
+The dependency graph, queryable both ways.
+
+| Method | Answers |
+| --- | --- |
+| `inboundFor(ref)` | which entities `$`-ref this, and through which field |
+| `outboundFor(id)` | which refs this entity emits |
+| `dynamicInboundFor(target)` | which entities depend on this via layout / partial / query / lookup |
+| `dynamicOutboundFor(id)` | the render-time edges this entity recorded |
+| `inverseClosureOf(seeds)` | everything that transitively depends on these — the set a change dispatches |
+| `resolveRefIds(ref)` | which entity ids a ref string resolves to, by all four forms |
+| `allRefs()` / `size()` | every static ref target; edge and source counts |
+| `subscribeGraph(opts)` | react to changes within N hops of entities matching a filter |
+| `subscribeQuery(opts)` | react to changes matching a query |
+
+`inverseClosureOf` is the one to reach for when a change re-rendered more
+than you expected — it returns exactly the set the scheduler will act on.
+
+### `runtime.manifest`
+
+What was rendered and whether it needs redoing.
+
+| Method | Answers |
+| --- | --- |
+| `snapshotsFor(id)` | every snapshot for an entity, without knowing its destinations |
+| `lookup({id, destination})` | one snapshot |
+| `skipDecision(entity, …)` | `{ skip, reason }` — the same reason `--json` reports |
+| `recordedHashes()` | the dep-hashes dependents last saw |
+| `queryAffected(mutated)` | which query-dependent snapshots this mutation hits |
+| `verify({outputFolder})` | `{ missing, mismatched, unverifiable, orphaned }` — what `--verify` reports; pure, no mutations |
+| `size()` | snapshot count |
+
+`snapshotsFor(id)` exists because an entity can render to several
+destinations and a caller asking "what happened to this?" does not know
+them in advance — which is exactly the position you are in when a page
+did not change and you want to know why.
+
+### `layouts.inspect()`
+
+Exposed by `mikser-io-layouts` at `runtime.options.layouts.inspect(id)`.
+Answers "what does this layout actually do?" — its template source, the
+partials and references the renderer parses out of it, and the recorded
+`refClosure` of up to `samples` entities that used it, so you can see
+what it depended on in practice rather than in theory.
+
+```js
+const report = await runtime.options.layouts.inspect('/layouts/post.hbs', { samples: 3 })
+```
+
+Throws with `code: 'LAYOUT_NOT_FOUND'` for an id that is not a layout.
+
+### `schemas.names()` / `schemas.lookup()`
+
+Exposed by `mikser-io-schemas` at `runtime.options.schemas`. `names()`
+lists every loaded schema; `lookup(name)` returns the zod object.
+
+The failure worth knowing about: a schema that loaded but matched no
+entity is reported at finalize, because validation that silently never
+runs looks exactly like validation that passed. If you configured
+schemas and see no errors, check that warning before believing the
+content is clean.
+
+### `preview`
+
+`mikser-io`'s preview plugin exposes `runtime.options.preview = { store,
+get, stats, config }` — the on-demand render cache, useful for asking
+what has been rendered outside a build.
+
+## When mikser is silent
+
+Silence is this engine's characteristic failure mode: a declaration that
+selected nothing, or an input nothing tracked, and a green build. The
+surfaces that turn silence into a statement:
+
+- **A build that rendered nothing** — `--json` distinguishes `gated`
+  (source unchanged, never scheduled) from `skipped` (scheduled, manifest
+  declined). Those have different causes.
+- **A page pinned to stale bytes** — `--explain` on it, then read the
+  `refClosure` for an `[UNRESOLVED]` edge or a dependency you expected to
+  be listed and is not. An input nothing recorded is an input nothing
+  invalidates.
+- **A pattern or query that matched nothing** — several plugins warn on
+  this now (layout patterns, preset matching, null filters). The warnings
+  carry stable `code`s in `--json`.
+- **Output that does not match the config** — the config's bytes take
+  part in cache invalidation, so a config change forces a rebuild; but a
+  module the config *imports* does not. If you changed a helper the config
+  pulls in, use `--force`.
+- **A plugin that appears to do nothing** — `No plugins loaded` with a
+  config present is a warning naming the file. A config that fails to
+  load now exits non-zero rather than loading as empty.
+
+## See also
+
+- [Entities](./entities.md) — the entity model, operations, journal, catalog
+- [Lifecycle](./lifecycle.md) — which phase a hook can see what in
+- [API Reference](./api-reference.md) — full signatures
+- [Decisions](./decisions/) — why the graph is shaped this way, especially
+  ADR-0002 (files are the source of truth) and ADR-0009 (SQLite substrate)

package/package.json

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

package/src/catalog.js

@@ -414,7 +414,10 @@ export function findById(id) {
 // (hit the LRU and validate remaining clauses inline). For other
 // filters, translate to SQL + JS fallback.
 export async function findEntity(query) {
-    if (!query || typeof query !== 'object') return
+    // A function is a valid filter, so the guard has to admit one:
+    // `typeof fn !== 'object'`, and rejecting it here returns undefined
+    // for every function filter without a word.
+    if (!query || (typeof query !== 'object' && typeof query !== 'function')) return
     recordQuery(query)
 
     if (db?.isOpen) {
@@ -429,13 +432,12 @@ export async function findEntity(query) {
         }
 
         const t = siftToSql(query)
-        const sql = `SELECT data FROM mikser_entities ${t.sql} LIMIT ${t.jsFilter ? '' : '1'}`
-        // With a jsFilter we may need to scan multiple rows before
-        // finding a match; without one, LIMIT 1 short-circuits.
-        const stmt = db.prepare(t.jsFilter
+        // With a residual predicate we may need to scan multiple rows
+        // before finding a match; without one, LIMIT 1 short-circuits.
+        const matcher = residualMatcher(query, t.jsFilter)
+        const stmt = db.prepare(matcher
             ? `SELECT data FROM mikser_entities ${t.sql}`
             : `SELECT data FROM mikser_entities ${t.sql} LIMIT 1`)
-        const matcher = t.jsFilter ? sift(t.jsFilter) : null
         for (const row of stmt.iterate(...t.params)) {
             const entity = JSON.parse(row.data)
             if (!matcher || matcher(entity)) return entity
@@ -454,7 +456,7 @@ export async function findEntity(query) {
         if (Object.keys(rest).length === 0) return entity
         return sift(rest)(entity) ? entity : undefined
     }
-    const m = sift(query)
+    const m = typeof query === 'function' ? query : sift(query)
     for (const entity of shim.all()) {
         if (m(entity)) return entity
     }
@@ -463,6 +465,46 @@ export async function findEntity(query) {
 // All entities (no arg) or those matching `query`. Indexed clauses
 // push down to SQL; un-indexed clauses run as a sift filter over the
 // pushdown result set.
+// The residual predicate a SQL translation could not absorb.
+//
+// `translate()` reports `jsFilter: null` for two different situations:
+// nothing is left to check in JS, and the filter could not be read at
+// all. A function filter is the second. Reading that null as the first
+// discards the predicate — `findEntities(fn)` then answers with the
+// entire catalog and `findEntity(fn)` with whichever row LIMIT 1
+// returns, both silently. So the function case is decided HERE, from
+// `query` itself, rather than inferred from what translate returned.
+//
+// The plugin harness applies function filters, so a plugin that relies
+// on this passes its own tests either way; only production diverges.
+//
+// A function cannot be indexed — it forces a full scan and a JSON.parse
+// per row — so prefer an object filter, and `refFilter()` for the common
+// "resolve a ref string" case.
+function residualMatcher(query, jsFilter) {
+    if (jsFilter) return sift(jsFilter)
+    if (typeof query === 'function') {
+        warnFullScan()
+        return query
+    }
+    return null
+}
+
+// Once per process: a function filter is a performance cliff, not an
+// error, and a message per call on a hot path costs more than the cliff.
+let warnedFullScan = false
+function warnFullScan() {
+    if (warnedFullScan) return
+    warnedFullScan = true
+    try {
+        useLogger().debug(
+            'Catalog query used a function filter: this cannot be indexed and '
+            + 'scans the whole catalog. Prefer an object filter, or refFilter(ref) '
+            + 'to resolve a ref string.',
+        )
+    } catch { /* logger may not exist yet */ }
+}
+
 export async function findEntities(query) {
     recordQuery(query)
 
@@ -474,17 +516,14 @@ export async function findEntities(query) {
         const stmt = db.prepare(`SELECT data FROM mikser_entities ${t.sql}`)
         const rows = stmt.all(...t.params)
         const entities = rows.map(r => JSON.parse(r.data))
-        if (t.jsFilter) {
-            const matcher = sift(t.jsFilter)
-            return entities.filter(matcher)
-        }
-        return entities
+        const matcher = residualMatcher(query, t.jsFilter)
+        return matcher ? entities.filter(matcher) : entities
     }
 
     const shim = mapStub()
     if (!shim) return []
     if (!query) return shim.all()
-    const m = sift(query)
+    const m = typeof query === 'function' ? query : sift(query)
     return shim.all().filter(m)
 }
 
@@ -522,7 +561,7 @@ export async function* iterateEntities(query) {
         const stmt = db.prepare(
             `SELECT id, data FROM mikser_entities ${where} ORDER BY id LIMIT ?`,
         )
-        const matcher = t.jsFilter ? sift(t.jsFilter) : null
+        const matcher = residualMatcher(query, t.jsFilter)
 
         let lastId = ''
         while (true) {
@@ -540,7 +579,7 @@ export async function* iterateEntities(query) {
     // Stub path — for tests that don't bring up the database.
     const shim = mapStub()
     if (!shim) return
-    const m = query ? sift(query) : null
+    const m = query ? (typeof query === 'function' ? query : sift(query)) : null
     for (const entity of shim.all()) {
         if (!m || m(entity)) yield entity
     }

package/src/config.js

@@ -3,6 +3,7 @@ import { useLogger } from './engine.js'
 import { onLoad } from './lifecycle.js'
 import { checksum } from './utils.js'
 import path from 'node:path'
+import { existsSync } from 'node:fs'
 
 onLoad(async () => {
     const logger = useLogger()
@@ -29,15 +30,30 @@ onLoad(async () => {
         runtime.options.configChecksum = null
     }
 
-    try {
+    // Absence is decided by looking for the file, NOT by catching
+    // ERR_MODULE_NOT_FOUND from the import.
+    //
+    // Node raises that same code for "the config file is missing" and for
+    // "the config file exists and something IT imports is missing" — a
+    // mistyped package name, a renamed local module, a dependency that was
+    // never installed. Catching the code cannot tell them apart, and a
+    // config with one bad import then loads as `{}`: the build reports "No
+    // plugins loaded" and exits 0, a green build with an empty output
+    // folder, one line below having printed the config's path.
+    //
+    // Every other config failure is loud — a syntax error and a throw
+    // during evaluation both exit 1. Module resolution is the only one that
+    // needs this to stay in line with them.
+    if (!existsSync(configFile)) {
+        logger.debug('No config file at %s — using defaults', configFile)
+    } else {
+        // No catch: any failure loading a config that EXISTS is fatal.
         const config = await import(configFile)
         if (typeof config.default == 'function') {
             runtime.config = await config.default(runtime)
         } else if (typeof config.default == 'object') {
             runtime.config = config.default
         }
-    } catch (err) {
-        if (err.code != 'ERR_MODULE_NOT_FOUND') throw err
     }
 
     // v8 used to walk `runtime.config.plugins` looking for matching

package/src/explain.js

@@ -117,10 +117,10 @@ export async function explain(reference) {
                     : {
                         kind: entry.kind,
                         target: entry.target,
-                        // What the name actually resolved to. A binding
-                        // that is absent means the edge is dangling —
-                        // the single most useful thing to know when a
-                        // page will not re-render and nobody can say why.
+                        // What the name resolved to. An absent binding
+                        // means a dangling edge — the most useful single
+                        // fact when a page will not re-render and nothing
+                        // says why.
                         bound: entry.targetIds?.length ? entry.targetIds
                             : entry.targetId ? [entry.targetId]
                             : [],