mikser-io 11.9.0 → 11.10.0

package/docs/diagnostics.md

@@ -1065,6 +1065,7 @@ distinction is the whole of [Faults](#faults) above.
 | Code | Severity | Means |
 | --- | --- | --- |
 | `source-content-not-text` | warn | A `sources()` collection with `content: true` loaded a file whose bytes are not text. They are decoded as UTF-8 and stored mangled, and every consumer inherits that. Set `content: false` to catalogue the files by path instead — `entity.uri` still points at them. Once per collection. |
+| `front-matter-unreadable` | warn | A file's front-matter block is present but not valid YAML. Its attributes are not available and the text is left as written. Previously this threw and ended the whole run with a parser stack that never named the file. |
 | `observer-bad-uri` | warn | An observer's `uri` is not an absolute URL, so no webhook can be routed to it. |
 | `untracked-file-read` | warn | A template read a file outside every folder mikser takes entities from, so it has no entity and changing it invalidates nothing. |
 | `progress` | info | A long phase reporting where it has got to. See [Progress](#progress). |

package/index.js

@@ -57,7 +57,7 @@ export { commands }      from './src/plugins/commands.js'
 export { data }          from './src/plugins/data.js'
 export { documents }     from './src/plugins/documents.js'
 export { files }         from './src/plugins/files.js'
-export { frontMatter }   from './src/plugins/front-matter.js'
+export { frontMatter, readFrontMatter } from './src/plugins/front-matter.js'
 export { json }          from './src/plugins/json.js'
 // layouts moved to sibling: import from 'mikser-io-layouts'
 export { mapper }        from './src/plugins/mapper.js'

package/package.json

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

package/src/plugins/front-matter.js

@@ -1,5 +1,28 @@
 import fm from 'front-matter'
 
+// Read front matter out of a string.
+//
+// Exported because more than one place needs the answer and a second
+// implementation would drift from this one. mikser-io-layouts calls it when
+// it has to fall back to a layout as SYNCED — the file before this plugin has
+// lifted its attributes out — and handing that raw text to a renderer is a
+// bug with two faces: Handlebars emitted the YAML into the page, and LiquidJS
+// refuses to parse it at all, failing at the front-matter line and taking the
+// layout down with it.
+//
+// Returns { attributes, body }, or null when there is no front matter or it
+// cannot be parsed. Never throws: a malformed block is the author's problem
+// to see, not the build's to die on.
+export function readFrontMatter(content) {
+    if (typeof content !== 'string' || !fm.test(content)) return null
+    try {
+        const info = fm(content)
+        return info?.attributes ? { attributes: info.attributes, body: info.body } : null
+    } catch (err) {
+        return { error: err.message }
+    }
+}
+
 export function frontMatter(options = {}) {
     return ({
         onProcess,
@@ -10,14 +33,25 @@ export function frontMatter(options = {}) {
         onProcess(async () => {
             const logger = useLogger()
             for await (let { entity } of useJournal('Front matter', [OPERATION.CREATE, OPERATION.UPDATE])) {
-                if (entity.content && fm.test(entity.content)) {
-                    const info = fm(entity.content)
-                    if (info.attributes) {
-                        entity.meta = Object.assign(entity.meta || {}, info.attributes)
-                        entity.content = info.body
-                        logger.trace('Front matter %s: %s', entity.collection, entity.id)
-                    }
+                const parsed = readFrontMatter(entity.content)
+                if (!parsed) continue
+                if (parsed.error) {
+                    // Was an uncaught throw, which ended the RUN: js-yaml's
+                    // exception went up through the journal loop and out of
+                    // the process, printing a stack that named js-yaml and
+                    // front-matter and not one word about which file. One
+                    // mistyped line in one document stopped every other
+                    // document from building, and left the author reading a
+                    // parser's internals to find out where.
+                    logger.warn(
+                        { code: 'front-matter-unreadable', id: entity.id, collection: entity.collection },
+                        'Front matter in %s could not be parsed, so it is left as written and its attributes '
+                        + 'are not available: %s', entity.id, parsed.error)
+                    continue
                 }
+                entity.meta = Object.assign(entity.meta || {}, parsed.attributes)
+                entity.content = parsed.body
+                logger.trace('Front matter %s: %s', entity.collection, entity.id)
             }
         })