@panaversity/ksor 0.0.39 → 0.0.41

package/templates/scaffold/system/site/record/yaml-file.ts

@@ -0,0 +1,103 @@
+/**
+ * One reader for the control files beside the bundle (`.ksor/*.yaml`): the
+ * same parser posture as a concept's frontmatter — one document, unique keys,
+ * plain data throughout, a mapping at the root — refused under the file's own
+ * slug.
+ *
+ * Every clause of that posture was re-probed against `yaml` 2.9.0 on
+ * 2026-08-25, because the previous wording listed `schema: "core"` among them
+ * as though it were a safety property. What the options really buy:
+ *
+ * - `uniqueKeys` makes a repeated key an ERROR, so a second `takedown_authorities:`
+ *   cannot quietly win over the first.
+ * - An unknown tag (`!Foo`) is an error, so nothing resolves through a handler
+ *   this codebase never wrote.
+ * - An alias bomb throws at `toJS()` ("Excessive alias count"), which the
+ *   `catch` turns into a refusal rather than a hung process.
+ * - `schema: "core"` decides how PLAIN scalars resolve — `.inf` is a number,
+ *   `2026-01-01` stays a string — and that is all it decides. It does NOT
+ *   refuse the YAML 1.1 type tags: `!!binary` resolves to a Buffer, `!!set` to
+ *   a Set and `!!omap` to a Map, with no error and no warning. The root-only
+ *   mapping check never looked at a value, so a control file could carry an
+ *   object no rule here is written against — `Policy.raw` is published
+ *   verbatim — which is why `firstNonPlain` walks the whole document.
+ * - `__proto__` needs no defence and gets none: `yaml` assigns through
+ *   `Object.defineProperty`, so it lands as an ordinary own key and the global
+ *   prototype is untouched. Pinned in the tests, not asserted here.
+ */
+import { parseAllDocuments } from "yaml";
+
+import type { Refusal, RefusalSlug } from "./refusal";
+
+export type YamlFileResult =
+  | { readonly ok: true; readonly value: Readonly<Record<string, unknown>> }
+  | { readonly ok: false; readonly refusals: readonly Refusal[] };
+
+const SHAPE_FIX = "fix the YAML so the file is one mapping of the keys the spec names";
+
+export function parseYamlFile(text: string, path: string, slug: RefusalSlug): YamlFileResult {
+  const refuse = (why: string, fix: string = SHAPE_FIX): YamlFileResult => ({
+    ok: false,
+    refusals: [{ slug, path, why, fix }],
+  });
+  let value: unknown;
+  try {
+    const docs = parseAllDocuments(text.replace(/^\uFEFF/, ""), {
+      schema: "core",
+      uniqueKeys: true,
+      logLevel: "silent",
+    });
+    if (docs.length > 1) return refuse("the file holds more than one YAML document");
+    const problem = docs[0]?.errors[0] ?? docs[0]?.warnings[0];
+    if (problem !== undefined) {
+      return refuse(`not valid YAML: ${problem.message.split("\n")[0] ?? ""}`);
+    }
+    value = docs[0]?.toJS();
+  } catch (error) {
+    const first = String(error).split("\n")[0] ?? "";
+    return refuse(`not valid YAML: ${first.replace(/^\w*Error: /, "")}`);
+  }
+  if (value === null || value === undefined) value = {};
+  if (!isPlainMapping(value)) return refuse("the file is not a mapping at its root");
+  const tagged = firstNonPlain(value, "");
+  if (tagged !== null) {
+    return refuse(
+      `the value at \`${tagged}\` is not plain data — a \`!!tag\` turned it into something no reader expects`,
+      "write strings, numbers, booleans, lists and mappings only; timestamps stay quoted strings",
+    );
+  }
+  return { ok: true, value };
+}
+
+export function isPlainMapping(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Path of the first value that is neither a scalar, an array nor a plain
+ * mapping — `null` when all are. One walk, shared with `splitFrontmatter`: the
+ * frontmatter reader grew it first, and a control file that decides authority
+ * and denial is the last place to enforce a weaker rule than a document's own
+ * header does.
+ */
+export function firstNonPlain(value: unknown, at: string): string | null {
+  if (value === null) return null;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return null;
+  }
+  if (Array.isArray(value)) {
+    for (const [i, item] of value.entries()) {
+      const hit = firstNonPlain(item, `${at}[${i}]`);
+      if (hit !== null) return hit;
+    }
+    return null;
+  }
+  if (!isPlainMapping(value)) return at === "" ? "(root)" : at;
+  for (const [key, item] of Object.entries(value)) {
+    const hit = firstNonPlain(item, at === "" ? key : `${at}.${key}`);
+    if (hit !== null) return hit;
+  }
+  return null;
+}

package/templates/scaffold/system/site/source.config.ts

@@ -1,5 +1,10 @@
+import path from "node:path";
+
 import { defineCollections, defineConfig, defineDocs } from "fumadocs-mdx/config";
+import { rehypeCodeDefaultOptions } from "fumadocs-core/mdx-plugins";
 import { remarkCodeTab } from "fumadocs-core/mdx-plugins/remark-code-tab";
+import { rehypeGithubAlerts } from "./lib/alert-rule";
+import { rehypeEmbeds } from "./lib/embed-rule";
 import { metaSchema, pageSchema } from "fumadocs-core/source/schema";
 import { z } from "zod";
 import { DeckSchema } from "./lib/deck";
@@ -7,40 +12,50 @@ import { QuizSchema } from "./lib/quiz";
 import { SlidesSchema } from "./lib/slides";
 import { isAttachment } from "./lib/attachment-rule";
 import { rehypeTeachingAid } from "./lib/teaching-aid-rule";
+import { STAGE_DIR } from "./lib/stage-manifest";
 import { knowledgeSourceDir } from "./lib/stage-knowledge";
 
-// The record lives at <repo>/knowledge — two levels up from this site.
-// Governance frontmatter (status, owner, provenance, superseded_by) is
-// tolerated on top of the default page schema so a governed document
-// always renders; `pnpm check` at the repo root is what enforces it.
+// The record lives at <repo>/knowledge — two levels up from this site. The
+// profile's governance frontmatter (record spec §2) is tolerated on top of
+// the default page schema so a governed document always renders; the record
+// checker, which staging runs, is what enforces it.
 //
-// When instance.md declares `audiences:`, the documents this build may
-// publish (and the assets they reference) are staged into a filtered copy
-// FIRST, and this is where that copy is chosen: one directory, one filter,
-// every surface downstream. See lib/stage-knowledge.ts.
+// The documents this build's viewer may see (and the assets they reference)
+// are staged into a filtered copy FIRST, for EVERY build, and this is where
+// that copy is chosen: one directory, one filter, every surface downstream.
+// See lib/stage-knowledge.ts.
 export const docs = defineDocs({
   dir: knowledgeSourceDir(),
   docs: {
-    // ONE exclusion, and it is the whole of "an attachment is not a document".
-    // The route table, the sidebar, llms.txt, llms-full.txt, /md/, the search
-    // index and the caveat map ALL read `source`, and `source` reads exactly
-    // this collection — so subtracting attachments here subtracts them from
-    // every surface at once. Doing it per-surface instead is the failure mode
-    // research/visibility.md §4-§5 is cited for; pruning the page tree is not
-    // even sufficient, because getSortedPages() deliberately re-adds what the
-    // tree dropped and the search index never consults the tree.
-    files: ["**/*.md", "**/*.mdx", "!**/*.summary.md", "!**/*.summary.mdx"],
+    // TWO exclusions, and they are the whole of "an attachment is not a
+    // document" and "an index is not a document". The route table, the
+    // sidebar, llms.txt, llms-full.txt, /md/, the search index and the badge
+    // map ALL read `source`, and `source` reads exactly this collection — so
+    // subtracting here subtracts from every surface at once. Doing it
+    // per-surface is the failure mode research/visibility.md §4-§5 is cited
+    // for; pruning the page tree is not even sufficient, because the search
+    // index never consults the tree. The regenerated `index.md` is rendered by
+    // the folder page component instead (record spec §1: no route, no twin,
+    // no llms.txt line — it carries no governance to publish under).
+    // `.md` only: the record is CommonMark (record spec §1), the checker
+    // refuses an `.mdx` under knowledge/ by name (`ksor-file-type`), and
+    // staging copies nothing else — so an `.mdx` pattern here advertised a
+    // shape the stage can never contain.
+    files: ["**/*.md", "!**/*.summary.md", "!**/index.md"],
     schema: pageSchema
       .extend({
+        type: z.string().optional(),
         status: z.string().optional(),
-        owner: z.string().optional(),
-        provenance: z.array(z.string()).optional(),
-        superseded_by: z.string().optional(),
+        order: z.number().optional(),
+        ksor: z.record(z.string(), z.any()).optional(),
       })
       .catchall(z.any()),
     postprocess: {
-      // Exposes each page's processed markdown — llms.txt/llms-full.txt
-      // depend on it.
+      // Exposes each page's processed markdown, for the page's reading time.
+      // NOT for the machine surfaces: `/md/` and `llms-full.txt` republish the
+      // STAGED bytes, because the processed markdown is the mdast serialized
+      // after every remark plugin has run and carries this shell's rendering
+      // rather than the record's grammar (lib/stage-manifest.ts, `stagedBody`).
       includeProcessedMarkdown: true,
     },
   },
@@ -117,13 +132,84 @@ export const slides = defineCollections({
 
 export default defineConfig({
   mdxOptions: {
+    /**
+     * A bundle-absolute image (`![chart](/chart.png)`) resolves against the
+     * STAGE, which is where `/`-rooted links resolve everywhere else in the
+     * record.
+     *
+     * OKF §6.1 allows both link forms and record spec §2.3 says the record
+     * carries both, so the checker accepts `/chart.png` and staging copies the
+     * file to `.staged-knowledge/chart.png`. fumadocs' `remarkImage` is applied
+     * by default and resolves a `/`-rooted src against `<cwd>/public` — a
+     * directory this scaffold does not have — so it emitted
+     * `import __img0 from "../../public/chart.png"` and the export died with
+     * "Module not found" naming a path that exists nowhere in the record. Two
+     * halves of one pipeline resolving the same string against two roots; this
+     * gives them one root. Absolute, because `remarkImage` joins it with the
+     * src and then takes a path RELATIVE to the document's directory.
+     */
+    remarkImageOptions: { publicDir: path.resolve(process.cwd(), STAGE_DIR) },
+    /**
+     * A fence in a language the highlighter does not carry renders as PLAIN
+     * TEXT rather than failing the build.
+     *
+     * A record is not a code project: an author writing ```promql, ```logql or
+     * ```gotemplate is describing their own stack, and shiki throws on a
+     * language it has no grammar for. Without this, one fence anywhere in the
+     * record takes the whole site down with a stack trace naming a file in
+     * node_modules — found live on a real 187-document handbook, where three
+     * such languages appeared across 3,000 fences.
+     *
+     * `lazy` so only the grammars a record actually uses are loaded, which is
+     * also what keeps that first unknown fence from being fatal.
+     *
+     * The defaults are SPREAD, not replaced: `RehypeCodeOptions` is a full
+     * options object (it requires `themes`), so passing the two keys alone
+     * type-errors on a manager that resolves fumadocs fresh rather than from
+     * the pinned lockfile — found in CI on the npm and bun scaffolds, which
+     * ship no lockfile by design (decision 25).
+     */
+    rehypeCodeOptions: {
+      ...rehypeCodeDefaultOptions,
+      lazy: true,
+      fallbackLanguage: "text",
+    },
     /**
      * WHERE the teaching aid sits: after the document's introduction, which
      * is everything before its first `##` section. The plugin only marks the
      * place; the page decides whether there is a deck to put there. See
      * lib/teaching-aid-rule.ts.
      */
-    rehypePlugins: [[rehypeTeachingAid, { isAttachment }]],
+    rehypePlugins: [
+      [rehypeTeachingAid, { isAttachment }],
+      /**
+       * A passage the reader must not miss, as a CALLOUT.
+       *
+       * GitHub's alert syntax: a blockquote whose first line is `[!WARNING]`.
+       * GitHub renders it as a styled alert, every other viewer renders an
+       * ordinary blockquote carrying a visible label, and it reaches `/md/`
+       * and `llms-full.txt` as the author's blockquote rather than as markup.
+       *
+       * Not `:::warning`. fumadocs ships `remarkAdmonition` for that form and
+       * deprecates it in favour of a `remark-directive` setup — but the deeper
+       * objection is that `:::` is a dialect, and a record written in one
+       * renders as literal punctuation everywhere it is read outside this site.
+       *
+       * REHYPE rather than remark, and lib/alert-rule.ts records why: the
+       * record's markdown is serialized from the mdast, so converting there
+       * publishes this site's React component to the agent surface.
+       */
+      rehypeGithubAlerts,
+      /**
+       * An interactive page the document points at, as a click-to-load
+       * frame. Authored as an ordinary link titled `embed`, so the record
+       * stays CommonMark and every other reader of it sees a link.
+       *
+       * REHYPE, so `/md/` and `llms-full.txt` keep the author's link
+       * rather than this site's component. See lib/embed-rule.ts.
+       */
+      rehypeEmbeds,
+    ],
     /**
      * Alternative versions of the same instruction, as TABS.
      *