canon-atlas 0.1.0 → 0.2.0

package/README.md

@@ -60,6 +60,10 @@ To define your own, put a `canon-atlas.json` at the root:
 
 References that resolve nowhere are not errors: they render as dashed, unwritten nodes, because a name the corpus reaches for but has not written yet is a fact worth seeing. In live mode an unwritten node offers to be written.
 
+### The article schema
+
+A store may carry a `schema.json` beside its collections ([pi-canon](https://github.com/shaneconner/pi-canon) writes one when it creates a store), declaring rules for an article's `capsule`, `title`, and `body`: `required`, `min_chars`, `max_chars`, and a `hint`. The atlas enforces the same contract at every one of its write doors. Enforcement is asymmetric on purpose: a `required` rule rejects a save that touches the field (and everything on create), with nothing written and the editor keeping your text while it tells you what to correct; every other rule warns, and a document already in violation shows heal notes in the reader instead of errors, so a body edit is never held hostage to a legacy omission. A malformed `schema.json` fails open and loud: nothing is enforced, and the map panel and every save say so, because a contract the owner believes is enforced while a typo disabled it is the worst state.
+
 ## Color
 
 Color is the cluster a document belongs to, sampled from one perceptual ramp (Batlow), and the force layout pulls each cluster into its own region, so a band of the palette and a region of the map mean the same thing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canon-atlas",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "An atlas over a catalog of markdown documents that reference each other: a constellation graph, search, a reader, and local editing. Agnostic to what wrote the catalog.",
   "type": "module",
   "bin": {

package/src/config.mjs

@@ -22,15 +22,31 @@ function isDir(p) {
 }
 
 /* Resolution order: an explicit canon-atlas.json at the root wins, then preset
-   detection (a store with both articles/ and journal/ is pi-canon), then the
-   bare default of one mutable collection over every markdown file. A config
-   that names a title but no collections keeps the detected preset. */
+   detection (a store with both articles/ and journal/, at the root or nested
+   under .canon/, is pi-canon), then the bare default of one mutable collection
+   over every markdown file. A config that names a title but no collections
+   keeps the detected preset. The prefix handling lives in the shared
+   detectPreset so Node and the browser resolve the same store the same way. */
 export function loadConfig(root) {
   const file = join(root, CONFIG_NAME);
   const raw = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : null;
-  const detect = () =>
-    isDir(join(root, "articles")) && isDir(join(root, "journal")) ? P.PI_CANON_PRESET : P.DEFAULT_CONFIG;
-  return P.buildConfig(P.composeConfig(raw, detect));
+  const detect = () => {
+    for (const prefix of ["", ".canon/"]) {
+      if (isDir(join(root, prefix, "articles")) && isDir(join(root, prefix, "journal"))) {
+        return P.detectPreset([prefix + "articles/x.md", prefix + "journal/x.md"]);
+      }
+    }
+    return P.DEFAULT_CONFIG;
+  };
+  const config = P.buildConfig(P.composeConfig(raw, detect));
+  /* The store's article contract, when it carries one: schema.json beside the
+     collections (pi-canon writes it at store creation). Parsed by the shared
+     pipeline so the browser and this process enforce identical rules. */
+  const sf = join(root, P.schemaPrefix(config), P.SCHEMA_FILE);
+  const s = P.parseSchema(existsSync(sf) ? readFileSync(sf, "utf8") : null);
+  config.schema = s.schema;
+  config.schemaProblems = s.problems;
+  return config;
 }
 
 /* Optional embedding vectors at the path config.embeddings names. Absent is

package/src/serve.mjs

@@ -26,11 +26,14 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { createRequire } from "node:module";
 import { loadConfig, loadVectors, collectionFor } from "./config.mjs";
 import { scanCorpus } from "./scan.mjs";
 import { buildGraph } from "./graph.mjs";
 import { buildData, renderPage, renderAppPage } from "./page.mjs";
 
+const P = createRequire(import.meta.url)("./ui/pipeline.cjs");
+
 const CACHE_TTL_MS = 3000;
 const BODY_LIMIT = 4_000_000;
 
@@ -149,6 +152,22 @@ export function corpusApi(rootArg) {
     return { full, rel: norm, col };
   }
 
+  /* The store's schema, enforced at this door the way pi-canon enforces it at
+     its own: a required violation the save touched (or a create) rejects with
+     nothing written, so the client keeps the text and says what to correct;
+     everything else comes back as warnings beside the success. */
+  function schemaGate(content, prevRaw, col) {
+    const cfg = config();
+    if (col.immutable) return [];
+    /* A broken declaration enforces nothing, but every write says so. */
+    if (!cfg.schema) return cfg.schemaProblems || [];
+    const r = P.checkDoc(String(content ?? ""), prevRaw, cfg.schema, col.fields.summary);
+    if (r.rejects.length) {
+      throw httpError(422, "Write rejected by this store's schema.json:\n- " + r.rejects.join("\n- "));
+    }
+    return r.warns.concat(cfg.schemaProblems || []);
+  }
+
   /* Serve one API request whose path inside the API is sub ("/graph",
      "/doc"). Returns true when the route was taken; errors throw httpError
      for the caller's catch, so both hosts report them the same way. */
@@ -169,12 +188,13 @@ export function corpusApi(rootArg) {
       if (req.method === "POST") {
         guardMutation(req);
         const body = await readBody(req);
-        const { full, rel } = confine(body.path);
+        const { full, rel, col } = confine(body.path);
         if (existsSync(full)) throw httpError(409, "document already exists");
+        const warnings = schemaGate(body.content, null, col);
         mkdirSync(dirname(full), { recursive: true });
         writeFileSync(full, String(body.content ?? ""), { flag: "wx" });
         bust();
-        send(201, { path: rel });
+        send(201, warnings.length ? { path: rel, warnings } : { path: rel });
         return true;
       }
       if (req.method === "PUT") {
@@ -183,9 +203,10 @@ export function corpusApi(rootArg) {
         const { full, rel, col } = confine(body.path);
         if (col.immutable) throw httpError(403, `${col.name} is immutable`);
         if (!existsSync(full)) throw httpError(404, "no such document");
+        const warnings = schemaGate(body.content, readFileSync(full, "utf8"), col);
         atomicWrite(full, String(body.content ?? ""));
         bust();
-        send(200, { path: rel });
+        send(200, warnings.length ? { path: rel, warnings } : { path: rel });
         return true;
       }
       if (req.method === "DELETE") {

package/src/ui/app.js

@@ -554,6 +554,11 @@
         none: "No clusters yet: add links between documents, or provide embeddings, and regions will form.",
       }[data.basis];
       ov.appendChild(el("p", "side-meta", basisLine + " Select a cluster to isolate it, or any node to read it."));
+      /* A schema the owner believes is enforced while a typo disabled it is
+         the worst state, so declaration problems surface here, loud. */
+      if (data.schemaProblems && data.schemaProblems.length) {
+        ov.appendChild(el("p", "err", data.schemaProblems.join("\n")));
+      }
       data.collections.forEach(function (c) {
         if (state.mode[c.name] === "off" && c.count) {
           ov.appendChild(el("p", "side-meta",
@@ -779,6 +784,11 @@
       }
       var kind = n.exists ? n.collection + (n.immutable ? ", immutable" : "") : "unwritten reference";
       side.appendChild(el("p", "side-kind", kind));
+      /* A document in violation of the store's schema reads fine; the notes
+         say what an edit would heal. */
+      if (n.schemaNotes && n.schemaNotes.length) {
+        side.appendChild(el("p", "schema-note", n.schemaNotes.join("\n")));
+      }
       var t = el("p", "side-title", n.title);
       if (n.exists) t.style.color = d3.hcl(d3.color(n.color)).brighter(1.1) + "";
       side.appendChild(t);
@@ -862,6 +872,9 @@
     }
 
     function showErr(err) {
+      /* Replace any standing error: a corrected retry must not stack lines. */
+      var old = side.querySelector(".err");
+      if (old) old.parentNode.removeChild(old);
       var p = el("p", "err", String((err && err.message) || err));
       side.insertBefore(p, side.firstChild);
     }

package/src/ui/pipeline.cjs

@@ -96,13 +96,22 @@ var AtlasPipeline = (function () {
   }
 
   function detectPreset(relPaths) {
-    let hasArticles = false;
-    let hasJournal = false;
-    for (const p of relPaths) {
-      if (p.startsWith("articles/")) hasArticles = true;
-      if (p.startsWith("journal/")) hasJournal = true;
+    for (const prefix of ["", ".canon/"]) {
+      let hasArticles = false;
+      let hasJournal = false;
+      for (const p of relPaths) {
+        if (p.startsWith(prefix + "articles/")) hasArticles = true;
+        if (p.startsWith(prefix + "journal/")) hasJournal = true;
+      }
+      if (hasArticles && hasJournal) {
+        if (!prefix) return PI_CANON_PRESET;
+        return Object.assign({}, PI_CANON_PRESET, {
+          collections: PI_CANON_PRESET.collections.map((c) =>
+            Object.assign({}, c, { match: prefix + c.match })),
+        });
+      }
     }
-    return hasArticles && hasJournal ? PI_CANON_PRESET : DEFAULT_CONFIG;
+    return DEFAULT_CONFIG;
   }
 
   /* Optional embedding vectors: a parsed JSON object of root-relative markdown
@@ -224,6 +233,124 @@ var AtlasPipeline = (function () {
     return m ? m[1].trim() : "";
   }
 
+  /* ── article schema ────────────────────────────────────────────────────────
+     A store may carry a schema.json beside its collections: pi-canon writes one
+     when it creates a store, and this file is the shared contract, so the atlas
+     enforces the same rules at its own write doors. The shape mirrors pi-canon
+     exactly: an "article" object with capsule / title / body rules, each rule
+     taking required, min_chars, max_chars, hint. Enforcement is asymmetric on
+     purpose: required rejects a save that touches the field (and everything on
+     create), everything else warns, and a document read in violation carries
+     heal notes instead of errors. A malformed file fails open and loud: nothing
+     is enforced and the problems say so, because a contract the owner believes
+     is enforced while a typo disabled it is the worst state. */
+
+  const SCHEMA_FILE = "schema.json";
+  const SCHEMA_FIELDS = ["capsule", "title", "body"];
+  const SCHEMA_RULE_KEYS = ["required", "min_chars", "max_chars", "hint"];
+
+  /* The store lives either at the corpus root or nested under .canon/; the
+     schema file sits beside the collections, wherever they are. */
+  function schemaPrefix(config) {
+    return config.collections.some((c) => (c.match || "").startsWith(".canon/")) ? ".canon/" : "";
+  }
+
+  /* Raw file text (or null when absent) into { schema, problems }. */
+  function parseSchema(text) {
+    if (text == null) return { schema: undefined, problems: [] };
+    let raw;
+    try {
+      raw = JSON.parse(text);
+    } catch (e) {
+      return {
+        schema: undefined,
+        problems: [SCHEMA_FILE + " is not valid JSON (" + e.message + "); its rules are not being enforced."],
+      };
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      return { schema: undefined, problems: [SCHEMA_FILE + " must hold a JSON object; its rules are not being enforced."] };
+    }
+    const problems = [];
+    const declared = raw.article;
+    if (declared === undefined) return { schema: {}, problems };
+    if (typeof declared !== "object" || declared === null || Array.isArray(declared)) {
+      return { schema: undefined, problems: [SCHEMA_FILE + ': "article" must be an object; its rules are not being enforced.'] };
+    }
+    const schema = {};
+    for (const [name, value] of Object.entries(declared)) {
+      if (!SCHEMA_FIELDS.includes(name)) {
+        problems.push(SCHEMA_FILE + ': unknown article field "' + name + '" is ignored (fields: ' + SCHEMA_FIELDS.join(", ") + ").");
+        continue;
+      }
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        problems.push(SCHEMA_FILE + ': rule for "' + name + '" must be an object and is ignored.');
+        continue;
+      }
+      const rule = {};
+      for (const [key, val] of Object.entries(value)) {
+        if (!SCHEMA_RULE_KEYS.includes(key)) {
+          problems.push(SCHEMA_FILE + ': unknown rule key "' + name + "." + key + '" is ignored (keys: ' + SCHEMA_RULE_KEYS.join(", ") + ").");
+        } else if (key === "required" && typeof val === "boolean") rule.required = val;
+        else if ((key === "min_chars" || key === "max_chars") && typeof val === "number" && Number.isInteger(val) && val >= 0) rule[key] = val;
+        else if (key === "hint" && typeof val === "string") rule.hint = val;
+        else problems.push(SCHEMA_FILE + ': "' + name + "." + key + '" has the wrong type and is ignored.');
+      }
+      schema[name] = rule;
+    }
+    return { schema, problems };
+  }
+
+  /* The title the schema means: the body's leading # heading, nothing later. */
+  function titleOf(body) {
+    for (const line of body.split("\n")) {
+      if (!line.trim()) continue;
+      const m = /^#\s+(.+)$/.exec(line);
+      return m ? m[1].trim() : "";
+    }
+    return "";
+  }
+
+  /* One save (or one read, when prevRaw === raw so nothing counts as touched)
+     against the schema. summaryKey is the frontmatter key this collection
+     carries its capsule under. A required violation rejects only when the save
+     touched that field or created the document; a legacy violation the save
+     left alone warns instead, so a body edit is never held hostage to an old
+     missing capsule. */
+  function checkDoc(raw, prevRaw, schema, summaryKey) {
+    const rejects = [];
+    const warns = [];
+    if (!schema) return { rejects, warns };
+    const created = prevRaw == null;
+    const extract = (text) => {
+      const { meta, body } = parseFrontmatter(text);
+      return {
+        capsule: String(meta[summaryKey] || "").trim(),
+        title: titleOf(body),
+        body: body.trim(),
+      };
+    };
+    const now = extract(raw);
+    const before = created ? null : extract(prevRaw);
+    for (const name of SCHEMA_FIELDS) {
+      const rule = schema[name];
+      if (!rule) continue;
+      const value = now[name];
+      const touched = created || value !== before[name];
+      const hint = rule.hint ? " (" + rule.hint + ")" : "";
+      if (rule.required && !value) {
+        if (touched) rejects.push(name + " is required" + hint);
+        else warns.push("schema: " + name + " is required and missing; this document can be healed by editing" + hint);
+      }
+      if (value && rule.min_chars != null && value.length < rule.min_chars) {
+        warns.push("schema: " + name + " is under " + rule.min_chars + " characters" + hint);
+      }
+      if (value && rule.max_chars != null && value.length > rule.max_chars) {
+        warns.push("schema: " + name + " is over " + rule.max_chars + " characters (" + value.length + ")" + hint);
+      }
+    }
+    return { rejects, warns };
+  }
+
   function extractLinks(body) {
     const out = [];
     // Fenced code carries example links that were never authored as references.
@@ -265,7 +392,14 @@ var AtlasPipeline = (function () {
     const allTags = asTags(meta[f.tags]);
     const lift = config.preset === "pi-canon";
     const fromPath = lift ? allTags.filter((t) => t.startsWith("path:")) : [];
+    /* A read never rejects: a document in violation carries heal notes. */
+    let schemaNotes;
+    if (config.schema && !col.immutable) {
+      const w = checkDoc(text, text, config.schema, f.summary).warns;
+      if (w.length) schemaNotes = w;
+    }
     return {
+      schemaNotes,
       path: rel,
       address,
       collection: col.name,
@@ -787,6 +921,7 @@ var AtlasPipeline = (function () {
       preset: config.preset,
       mode,
       basis,
+      schemaProblems: config.schemaProblems && config.schemaProblems.length ? config.schemaProblems : undefined,
       collections: config.collections.map((c) => ({
         name: c.name,
         match: c.match,
@@ -811,6 +946,7 @@ var AtlasPipeline = (function () {
         exists: n.exists,
         degree: n.degree,
         rank: n.rank,
+        schemaNotes: n.schemaNotes,
         html: n.body ? renderMarkdown(n.body) : "",
       })),
       edges,
@@ -832,6 +968,13 @@ var AtlasPipeline = (function () {
     const raw = composeConfig(opts.configJson, () => detectPreset(md.map((f) => f.path)));
     const config = buildConfig(raw);
     config.vectors = parseVectors(opts.vectorsJson);
+    /* schemaTexts carries both candidate files ({ root, nested }); which one is
+       the store's contract depends on where the collections landed, so the
+       choice waits for the config. */
+    const texts = opts.schemaTexts || {};
+    const s = parseSchema((schemaPrefix(config) ? texts.nested : texts.root) ?? null);
+    config.schema = s.schema;
+    config.schemaProblems = s.problems;
     const docs = scanFiles(md, config);
     const graph = buildGraph(docs);
     return buildData(config, graph, opts.mode || "fs");
@@ -839,12 +982,16 @@ var AtlasPipeline = (function () {
 
   return {
     CONFIG_NAME,
+    SCHEMA_FILE,
     PI_CANON_PRESET,
     DEFAULT_CONFIG,
     buildConfig,
     composeConfig,
     detectPreset,
     parseVectors,
+    parseSchema,
+    schemaPrefix,
+    checkDoc,
     collectionFor,
     parseFrontmatter,
     extractLinks,

package/src/ui/shell.js

@@ -193,10 +193,29 @@
       .catch(function () { return null; });
   }
 
+  /* Raw text at a nested path under the handle, or null when absent. */
+  function readTextAt(parts) {
+    var dir = Promise.resolve(handle);
+    for (var i = 0; i < parts.length - 1; i++) {
+      (function (name) {
+        dir = dir.then(function (d) { return d.getDirectoryHandle(name); });
+      })(parts[i]);
+    }
+    return dir
+      .then(function (d) { return d.getFileHandle(parts[parts.length - 1]); })
+      .then(function (fh) { return fh.getFile(); })
+      .then(function (f) { return f.text(); })
+      .catch(function () { return null; });
+  }
+
   /* "fs" when the handle came with write permission, "browse" when it is
      read-only (a dropped folder whose write grant was declined still reads). */
   var handleMode = "fs";
 
+  /* The store's article contract, parsed after each mount so the write path
+     enforces the same rules the wire data's heal notes report. */
+  var storeSchema = { schema: undefined, problems: [] };
+
   function buildFromFolder(progress) {
     return listDir(handle, "", [])
       .then(function (list) {
@@ -206,12 +225,20 @@
       .then(function (files) {
         return readJson(CONFIG).then(function (configJson) {
           var vecName = (configJson && configJson.embeddings) || "embeddings.json";
-          return readJson(vecName).then(function (vectorsJson) {
+          return Promise.all([
+            readJson(vecName),
+            readTextAt(["schema.json"]),
+            readTextAt([".canon", "schema.json"]),
+          ]).then(function (loaded) {
+            var schemaTexts = { root: loaded[1], nested: loaded[2] };
             currentData = AtlasPipeline.buildWireData(files, {
               configJson: configJson,
-              vectorsJson: vectorsJson,
+              vectorsJson: loaded[0],
+              schemaTexts: schemaTexts,
               mode: handleMode,
             });
+            var nested = currentData.collections.some(function (c) { return (c.match || "").indexOf(".canon/") === 0; });
+            storeSchema = AtlasPipeline.parseSchema(nested ? schemaTexts.nested : schemaTexts.root);
             return currentData;
           });
         });
@@ -252,6 +279,21 @@
     });
   }
 
+  /* The same asymmetric enforcement the server applies: a required violation
+     the save touched (or a create) rejects with nothing written, so the editor
+     keeps the text and says what to correct; everything else is a warning. */
+  function schemaGateFs(content, prevRaw, col) {
+    if (col.immutable) return [];
+    /* A broken declaration enforces nothing, but every write says so. */
+    if (!storeSchema.schema) return storeSchema.problems || [];
+    var summaryKey = (col.fields && col.fields.summary) || "summary";
+    var r = AtlasPipeline.checkDoc(String(content == null ? "" : content), prevRaw, storeSchema.schema, summaryKey);
+    if (r.rejects.length) {
+      throw new Error("Write rejected by this store's schema.json:\n- " + r.rejects.join("\n- "));
+    }
+    return r.warns.concat(storeSchema.problems);
+  }
+
   var fsBackend = {
     graph: function () { return buildFromFolder(); },
     readDoc: function (path) {
@@ -264,18 +306,25 @@
     writeDoc: function (path, content) {
       var col = confine(path);
       if (col.immutable) return Promise.reject(new Error(col.name + " is immutable"));
-      return fileHandleFor(path, false).then(function (fh) { return writeThrough(fh, content); }).then(function () {
-        return { path: path };
-      });
+      return fileHandleFor(path, false)
+        .then(function (fh) {
+          return fh.getFile().then(function (f) { return f.text(); }).then(function (prev) {
+            var warnings = schemaGateFs(content, prev, col);
+            return writeThrough(fh, content).then(function () {
+              return warnings.length ? { path: path, warnings: warnings } : { path: path };
+            });
+          });
+        });
     },
     createDoc: function (path, content) {
-      confine(path);
+      var col = confine(path);
       // Refuse to overwrite: succeed only if the file does not already exist.
       return fileHandleFor(path, false).then(
         function () { throw new Error("document already exists"); },
         function () {
+          var warnings = schemaGateFs(content, null, col);
           return fileHandleFor(path, true).then(function (fh) { return writeThrough(fh, content); }).then(function () {
-            return { path: path };
+            return warnings.length ? { path: path, warnings: warnings } : { path: path };
           });
         }
       );
@@ -361,9 +410,15 @@
           ).then(function (docs) {
             var mem = {};
             docs.forEach(function (f) { mem[f.path] = f.text; });
-            var data = AtlasPipeline.buildWireData(docs, {
+            return Promise.all([textOf("schema.json"), textOf(".canon/schema.json")]).then(function (st) {
+              return { docs: docs, mem: mem, schemaTexts: { root: st[0], nested: st[1] } };
+            });
+          }).then(function (got) {
+            var mem = got.mem;
+            var data = AtlasPipeline.buildWireData(got.docs, {
               configJson: configJson,
               vectorsJson: vectorsJson,
+              schemaTexts: got.schemaTexts,
               mode: "browse",
             });
             currentData = data;

package/src/ui/style.css

@@ -555,4 +555,7 @@ select.abtn option { background: var(--bg-elevated); color: var(--text); }
 
 .abtn.danger:hover { border-color: #8b2942; color: #e08a9c; }
 
-.err { margin: 0.5rem 0; font-size: 0.75rem; color: #e08a9c; }
+.err { margin: 0.5rem 0; font-size: 0.75rem; color: #e08a9c; white-space: pre-line; }
+
+/* Schema heal notes: information beside a document, never a wall. */
+.schema-note { margin: 0.35rem 0 0.6rem; font-size: 0.72rem; color: #a89a5f; white-space: pre-line; }