@fro.bot/wiki-write-core 0.2.0 → 0.3.0

package/README.md

@@ -59,6 +59,8 @@ A page that opens a frontmatter block and never closes it is reported as `invali
 
 The package's own readers (`parseFrontmatterDocument`, `splitFrontmatter`, the ingest's page parser and the repo-page move) all use it. Each keeps its error texts and its body handling. An empty block is an empty mapping for the document reader and the ingest parser; a block that parses to `null` (whitespace, comments, `null`, `...`) is not a mapping and gets each reader's rule for a non-mapping. The wiki page reader reports an unclosed block as `Invalid frontmatter: missing closing --- delimiter`.
 
+The wiki page reader also says why a page could not be read, apart from the text. `splitFrontmatter` returns `errorKind` next to `error`, and `parseWikiPage` and `collectWikiPages` return `frontmatterErrorKind` next to `frontmatterError` (type `WikiFrontmatterErrorKind` from `@fro.bot/wiki-write-core/wiki-utils`). The kind is `'unclosed'` for a block that opens and never closes (the text above) and `'invalid'` for a block the YAML parser rejects (`Invalid YAML frontmatter: <parser message>`). The kind is present exactly when the text is, and the text is unchanged. A block that parses to something other than a mapping is read as empty frontmatter with no error, so it has no kind. Switch on the kind; do not match the wording of the text.
+
 ## Target page sources
 
 When the ingest writes the page of the `repo:` target and that page lists no sources (no `sources` key, or an empty list), the page lists `{url, accessed}` with the target's `https://github.com/<owner>/<name>` URL and the date of the ingest's timestamp. When the page on the branch already has an entry for the target, its whole `sources` list is carried over as it is, so a repeat write changes nothing, a repeat after a migration included. The stamp applies only when the owner and name are plain GitHub names (ASCII letters, digits, `.`, `_` and `-`, not `.` or `..`); for any other target the page is written without one. A page that lists any source is never changed, and neither is a `sources` value that is not a list. When the ingest migrates a page to the target's slug by a trusted node ID, the merged page also gains the target's URL if no entry matches it, and keeps its other entries. No other repo page in the write is stamped, and a write whose target is a page path (the dashboard's case) is never stamped. Whether an entry matches the target uses the privacy gate's URL rule: `https`, host `github.com`, no port, owner and name equal without case, any path after them.

package/dist/gate-contract.js

@@ -1,4 +1,4 @@
 // Bump deliberately when an intentional consumer-visible gate contract break ships.
 export const GATE_CONTRACT_VERSION = 1;
 // Replaced with the deterministic source-tree hash by the package build.
-export const GATE_SOURCE_TREE_HASH = '637b237dc25880625d73dde771514ff4ff64fd845cb6dd1a07c61184570de419';
+export const GATE_SOURCE_TREE_HASH = 'bc3fa911b668e723571bcdb57e15a619e6998ac71675b03330719ad662d54d1b';

package/dist/gate-contract.json

@@ -1 +1 @@
-{"version":1,"sourceTreeHash":"637b237dc25880625d73dde771514ff4ff64fd845cb6dd1a07c61184570de419"}
+{"version":1,"sourceTreeHash":"bc3fa911b668e723571bcdb57e15a619e6998ac71675b03330719ad662d54d1b"}

package/dist/wiki-utils.d.ts

@@ -1,6 +1,13 @@
 /** Canonical root directory for wiki page content. Shared by every wiki script. */
 export declare const WIKI_ROOT = "knowledge/wiki";
 export type WikiPageType = 'repo' | 'topic' | 'entity' | 'comparison';
+/**
+ * Why a page's frontmatter could not be read, as a closed vocabulary a caller can switch on without matching the
+ * wording of the error text. `unclosed` is a block that opens with `---` and never closes; `invalid` is a block the
+ * YAML parser rejects. A block that parses to something other than a mapping is read as empty frontmatter and is
+ * not an error, so it has no kind.
+ */
+export type WikiFrontmatterErrorKind = 'unclosed' | 'invalid';
 export interface WikiPage {
     readonly path: string;
     readonly slug: string;
@@ -11,11 +18,15 @@ export interface WikiPage {
     readonly body: string;
     readonly frontmatter: Record<string, unknown>;
     readonly frontmatterError?: string;
+    /** Set exactly when `frontmatterError` is. */
+    readonly frontmatterErrorKind?: WikiFrontmatterErrorKind;
 }
 export interface SplitFrontmatterResult {
     readonly frontmatter: Record<string, unknown>;
     readonly body: string;
     readonly error?: string;
+    /** Set exactly when `error` is. */
+    readonly errorKind?: WikiFrontmatterErrorKind;
 }
 /**
  * Split raw wiki page content into frontmatter and body.

package/dist/wiki-utils.js

@@ -17,7 +17,12 @@ export function splitFrontmatter(content) {
         return { frontmatter: {}, body: content.trim() };
     }
     if (split.kind === 'malformed') {
-        return { frontmatter: {}, body: content.trim(), error: 'Invalid frontmatter: missing closing --- delimiter' };
+        return {
+            frontmatter: {},
+            body: content.trim(),
+            error: 'Invalid frontmatter: missing closing --- delimiter',
+            errorKind: 'unclosed',
+        };
     }
     let parsed;
     try {
@@ -29,6 +34,7 @@ export function splitFrontmatter(content) {
             frontmatter: {},
             body: split.body.trim(),
             error: `Invalid YAML frontmatter: ${message}`,
+            errorKind: 'invalid',
         };
     }
     return {
@@ -100,7 +106,7 @@ export function findWikilinkSpans(content) {
 }
 /** Parse a single wiki page's content (relative path + raw content) into a page record. */
 export function parseWikiPage(path, content) {
-    const { frontmatter, body, error } = splitFrontmatter(content);
+    const { frontmatter, body, error, errorKind } = splitFrontmatter(content);
     const slug = basename(path, '.md');
     return {
         path,
@@ -114,6 +120,7 @@ export function parseWikiPage(path, content) {
         body,
         frontmatter,
         frontmatterError: error,
+        frontmatterErrorKind: errorKind,
     };
 }
 /** Collect all `knowledge/wiki/**.md` pages from a path→content file map. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/wiki-write-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared validation and commit primitives for Fro Bot wiki writes",
   "homepage": "https://github.com/fro-bot/.github/tree/main/packages/wiki-write-core#readme",
   "bugs": {