contentbase 0.0.1 → 0.0.2

package/README.md

@@ -376,6 +376,121 @@ await doc.reload();
 
 ---
 
+## Standalone Parsing
+
+The `parse()` function gives you a queryable document from a file path or raw markdown string, without needing a Collection:
+
+```ts
+import { parse } from "contentbase";
+
+const doc = await parse("./content/my-post.mdx");
+doc.title;                                    // first heading text
+doc.meta;                                     // frontmatter
+doc.astQuery.selectAll("heading");            // AST querying
+doc.nodes.links;                              // node shortcuts
+doc.querySection("Introduction").selectAll("paragraph");
+
+// Also works with raw markdown
+const doc2 = await parse("# Hello\n\nWorld");
+```
+
+---
+
+## Extracting Sections Across Documents
+
+`extractSections()` pulls named sections from multiple documents into a single combined document, with heading depths adjusted automatically:
+
+```ts
+import { extractSections } from "contentbase";
+
+const combined = extractSections([
+  { source: doc1, sections: "Acceptance Criteria" },
+  { source: doc2, sections: ["Acceptance Criteria", "Mockups"] },
+], {
+  title: "All Acceptance Criteria",
+});
+```
+
+This produces:
+
+```md
+# All Acceptance Criteria
+
+## Authentication
+### Acceptance Criteria
+- Users can sign up with email and password
+- ...
+
+## Searching And Browsing
+### Acceptance Criteria
+- Users can search by category
+- ...
+```
+
+### Modes
+
+**Grouped** (default) -- each source document gets a heading (its title), with extracted sections nested underneath:
+
+```ts
+extractSections(entries, { mode: "grouped" });
+```
+
+**Flat** -- sections are placed sequentially with no source grouping:
+
+```ts
+extractSections(entries, { mode: "flat" });
+// ## Acceptance Criteria   <- from doc1
+// - ...
+// ## Acceptance Criteria   <- from doc2
+// - ...
+```
+
+### Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `title` | -- | Optional h1 title for the combined document |
+| `mode` | `"grouped"` | `"grouped"` nests under source titles, `"flat"` places sections sequentially |
+| `onMissing` | `"skip"` | `"skip"` silently omits missing sections, `"throw"` raises an error |
+
+The return value is a `ParsedDocument` -- fully queryable with `astQuery`, `nodes`, `extractSection()`, `querySection()`, and `stringify()`.
+
+Sources can be any mix of `Document` and `ParsedDocument` instances.
+
+---
+
+## Table of Contents Generation
+
+Generate a markdown table of contents for a collection with links that work on GitHub:
+
+```ts
+const toc = collection.tableOfContents({ title: "Project Docs" });
+```
+
+Output:
+
+```md
+# Project Docs
+
+## Epic
+
+- [Authentication](./epics/authentication.mdx)
+- [Searching And Browsing](./epics/searching-and-browsing.mdx)
+
+## Story
+
+- [A User should be able to register.](./stories/authentication/a-user-should-be-able-to-register.mdx)
+```
+
+If models are registered, documents are grouped by model. Without models, a flat list is produced. Use `basePath` to control the link prefix:
+
+```ts
+collection.tableOfContents({ basePath: "./content" });
+// links become: ./content/epics/authentication.mdx
+```
+
+---
+
 ## Computed Properties
 
 Derived values that are lazily evaluated from instance data:
@@ -446,6 +561,8 @@ contentbase action publish    # run a named action
 | `section()` | Declare a section extraction |
 | `hasMany()` | Declare a one-to-many relationship |
 | `belongsTo()` | Declare a many-to-one relationship |
+| `parse()` | Parse a file path or markdown string into a queryable `ParsedDocument` |
+| `extractSections()` | Combine sections from multiple documents into one |
 | `CollectionQuery` | Fluent query builder for model instances |
 | `AstQuery` | MDAST query wrapper (select, visit, find) |
 | `NodeShortcuts` | Convenience getters for common AST nodes |

package/bun.lock

@@ -20,7 +20,7 @@
         "unist-util-find-before": "^4.0.0",
         "unist-util-select": "^5.1.0",
         "unist-util-visit": "^5.0.0",
-        "zod": "^3.23.0",
+        "zod": "^4.3.6",
       },
       "devDependencies": {
         "@types/js-yaml": "^4.0.9",
@@ -456,7 +456,7 @@
 
     "yocto-queue": ["yocto-queue@1.2.2", "", {}, "sha512-4LCcse/U2MHZ63HAJVE+v71o7yOdIe4cZ70Wpf8D/IyjDKYQLV5GD46B+hSTjJsvV5PztjvHoU580EftxjDZFQ=="],
 
-    "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
+    "zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
 
     "zwitch": ["zwitch@2.0.4", "", {}, "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A=="],
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contentbase",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -10,7 +10,8 @@
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "examples": "bun run scripts/examples/run-all.ts"
   },
   "dependencies": {
     "citty": "^0.1.6",
@@ -29,7 +30,7 @@
     "unist-util-find-before": "^4.0.0",
     "unist-util-select": "^5.1.0",
     "unist-util-visit": "^5.0.0",
-    "zod": "^3.23.0"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/scripts/examples/01-collection-setup.ts

@@ -0,0 +1,46 @@
+import { scriptTitle, demo, kv, list } from "./lib/format";
+import { createDemoCollection, Epic, Story } from "./lib/setup";
+
+export async function main() {
+  scriptTitle("01", "Collection Setup");
+  const collection = await createDemoCollection();
+
+  await demo({
+    title: "Create and load a collection",
+    description: "Register models, load markdown files from disk.",
+    code: `const collection = new Collection({ rootPath: "./content" });
+collection.register(Epic);
+collection.register(Story);
+await collection.load();`,
+    run: () => {
+      return [
+        kv("Documents loaded", collection.available.length),
+        kv("Models registered", collection.modelDefinitions.length),
+      ].join("\n");
+    },
+  });
+
+  await demo({
+    title: "List available documents",
+    code: `collection.available`,
+    run: () => {
+      return list(collection.available);
+    },
+  });
+
+  await demo({
+    title: "Get a typed model instance",
+    code: `const epic = collection.getModel("epics/authentication", Epic);`,
+    run: () => {
+      const epic = collection.getModel("epics/authentication", Epic);
+      return [
+        kv("Title", epic.title),
+        kv("Slug", epic.slug),
+        kv("Status", epic.meta.status),
+        kv("Priority", epic.meta.priority),
+      ].join("\n");
+    },
+  });
+}
+
+if (import.meta.main) main().catch(console.error);

package/scripts/examples/02-querying.ts

@@ -0,0 +1,67 @@
+import { scriptTitle, demo, kv, list } from "./lib/format";
+import { createDemoCollection, Epic, Story } from "./lib/setup";
+
+export async function main() {
+  scriptTitle("02", "Querying");
+  const collection = await createDemoCollection();
+
+  await demo({
+    title: "Fetch all instances of a model",
+    code: `const epics = await collection.query(Epic).fetchAll();`,
+    run: async () => {
+      const epics = await collection.query(Epic).fetchAll();
+      return list(epics.map((e) => `${e.title} (${e.meta.status})`));
+    },
+  });
+
+  await demo({
+    title: "Filter with where()",
+    code: `const high = await collection.query(Epic)
+  .where("meta.priority", "high")
+  .fetchAll();`,
+    run: async () => {
+      const high = await collection
+        .query(Epic)
+        .where("meta.priority", "high")
+        .fetchAll();
+      return list(high.map((e) => `${e.title} — priority: ${e.meta.priority}`));
+    },
+  });
+
+  await demo({
+    title: "Chained where + whereExists",
+    code: `const filtered = await collection.query(Epic)
+  .where("meta.status", "created")
+  .whereExists("meta.priority")
+  .fetchAll();`,
+    run: async () => {
+      const filtered = await collection
+        .query(Epic)
+        .where("meta.status", "created")
+        .whereExists("meta.priority")
+        .fetchAll();
+      return list(
+        filtered.map((e) => `${e.title} — ${e.meta.status}, ${e.meta.priority}`)
+      );
+    },
+  });
+
+  await demo({
+    title: "Query helpers: first, last, count",
+    code: `const first = await collection.query(Epic).first();
+const last  = await collection.query(Epic).last();
+const count = await collection.query(Epic).count();`,
+    run: async () => {
+      const first = await collection.query(Epic).first();
+      const last = await collection.query(Epic).last();
+      const count = await collection.query(Epic).count();
+      return [
+        kv("First", first?.title),
+        kv("Last", last?.title),
+        kv("Count", count),
+      ].join("\n");
+    },
+  });
+}
+
+if (import.meta.main) main().catch(console.error);

package/scripts/examples/03-sections.ts

@@ -0,0 +1,36 @@
+import { scriptTitle, demo, kv, list } from "./lib/format";
+import { createDemoCollection, Story } from "./lib/setup";
+
+export async function main() {
+  scriptTitle("03", "Sections");
+  const collection = await createDemoCollection();
+  const story = collection.getModel(
+    "stories/authentication/a-user-should-be-able-to-register",
+    Story
+  );
+
+  await demo({
+    title: "Typed section access: acceptanceCriteria",
+    description: "Sections are defined in the model with section() helpers and extracted from headings.",
+    code: `const story = collection.getModel(
+  "stories/authentication/a-user-should-be-able-to-register",
+  Story
+);
+story.sections.acceptanceCriteria;`,
+    run: () => {
+      return list(story.sections.acceptanceCriteria);
+    },
+  });
+
+  await demo({
+    title: "Typed section access: mockups",
+    description: "The mockups section extracts links as a key-value record.",
+    code: `story.sections.mockups;`,
+    run: () => {
+      const entries = Object.entries(story.sections.mockups);
+      return entries.map(([label, url]) => kv(label, url)).join("\n");
+    },
+  });
+}
+
+if (import.meta.main) main().catch(console.error);

package/scripts/examples/04-relationships.ts

@@ -0,0 +1,54 @@
+import { scriptTitle, demo, kv, list } from "./lib/format";
+import { createDemoCollection, Epic, Story } from "./lib/setup";
+
+export async function main() {
+  scriptTitle("04", "Relationships");
+  const collection = await createDemoCollection();
+  const epic = collection.getModel("epics/authentication", Epic);
+
+  await demo({
+    title: "hasMany: Epic → Stories",
+    description: "Navigate from an epic to its child stories.",
+    code: `const epic = collection.getModel("epics/authentication", Epic);
+const stories = epic.relationships.stories.fetchAll();`,
+    run: () => {
+      const stories = epic.relationships.stories.fetchAll();
+      return list(stories.map((s: any) => s.title));
+    },
+  });
+
+  await demo({
+    title: "hasMany helpers: first() and last()",
+    code: `epic.relationships.stories.first()?.title;
+epic.relationships.stories.last()?.title;`,
+    run: () => {
+      return [
+        kv("First story", epic.relationships.stories.first()?.title),
+        kv("Last story", epic.relationships.stories.last()?.title),
+      ].join("\n");
+    },
+  });
+
+  await demo({
+    title: "belongsTo: Story → Epic",
+    description: "Navigate from a story back to its parent epic.",
+    code: `const story = collection.getModel(
+  "stories/authentication/a-user-should-be-able-to-register",
+  Story
+);
+const parent = story.relationships.epic.fetch();`,
+    run: () => {
+      const story = collection.getModel(
+        "stories/authentication/a-user-should-be-able-to-register",
+        Story
+      );
+      const parent = story.relationships.epic.fetch();
+      return [
+        kv("Story", story.title),
+        kv("Parent epic", parent.title),
+      ].join("\n");
+    },
+  });
+}
+
+if (import.meta.main) main().catch(console.error);

package/scripts/examples/05-document-api.ts

@@ -0,0 +1,54 @@
+import path from "path";
+import { scriptTitle, demo, kv } from "./lib/format";
+import { createDemoCollection, FIXTURES_PATH } from "./lib/setup";
+import { parse } from "../../src/index";
+
+export async function main() {
+  scriptTitle("05", "Document API");
+  const collection = await createDemoCollection();
+  const filePath = path.join(FIXTURES_PATH, "epics/authentication.mdx");
+
+  await demo({
+    title: "parse() a standalone file",
+    description: "Parse any markdown file without needing a collection.",
+    code: `import { parse } from "contentbase";
+const doc = await parse("./epics/authentication.mdx");`,
+    run: async () => {
+      const doc = await parse(filePath);
+      return [
+        kv("Title", doc.title),
+        kv("Headings", doc.nodes.headings.length),
+        kv("Links", doc.nodes.links.length),
+        kv("Lists", doc.nodes.lists.length),
+      ].join("\n");
+    },
+  });
+
+  await demo({
+    title: "Document outline",
+    description: "Generate an indented heading outline of any document.",
+    code: `const doc = collection.document("epics/authentication");
+doc.toOutline();`,
+    run: () => {
+      const doc = collection.document("epics/authentication");
+      return doc.toOutline();
+    },
+  });
+
+  await demo({
+    title: "Immutable section removal",
+    description: "removeSection() returns a new document — the original is unchanged.",
+    code: `const original = collection.document("epics/authentication");
+const trimmed = original.removeSection("Stories");`,
+    run: () => {
+      const original = collection.document("epics/authentication");
+      const trimmed = original.removeSection("Stories");
+      return [
+        kv("Original headings", original.nodes.headings.length),
+        kv("After removeSection", trimmed.nodes.headings.length),
+      ].join("\n");
+    },
+  });
+}
+
+if (import.meta.main) main().catch(console.error);

package/scripts/examples/06-extract-sections.ts

@@ -0,0 +1,55 @@
+import { scriptTitle, demo } from "./lib/format";
+import { createDemoCollection, Epic } from "./lib/setup";
+import { extractSections } from "../../src/index";
+
+export async function main() {
+  scriptTitle("06", "Extract Sections");
+  const collection = await createDemoCollection();
+  const allEpics = await collection.query(Epic).fetchAll();
+
+  await demo({
+    title: "Grouped mode (default)",
+    description: "Combine sections from multiple documents, grouped by source.",
+    code: `const combined = extractSections(
+  allEpics.map((e) => ({
+    source: e.document,
+    sections: "Stories",
+  })),
+  { title: "All Stories", mode: "grouped" }
+);`,
+    run: () => {
+      const combined = extractSections(
+        allEpics.map((e: any) => ({
+          source: e.document,
+          sections: "Stories",
+        })),
+        { title: "All Stories", mode: "grouped" }
+      );
+      return combined.content;
+    },
+  });
+
+  await demo({
+    title: "Flat mode",
+    description: "Combine sections without source grouping.",
+    code: `const flat = extractSections(
+  allEpics.map((e) => ({
+    source: e.document,
+    sections: "Stories",
+  })),
+  { title: "All Stories", mode: "flat" }
+);`,
+    run: () => {
+      const flat = extractSections(
+        allEpics.map((e: any) => ({
+          source: e.document,
+          sections: "Stories",
+        })),
+        { title: "All Stories", mode: "flat" }
+      );
+      return flat.content;
+    },
+  });
+}
+
+if (import.meta.main) main().catch(console.error);

package/scripts/examples/07-validation.ts

@@ -0,0 +1,46 @@
+import { scriptTitle, demo, kv } from "./lib/format";
+import { createDemoCollection, Story } from "./lib/setup";
+import { validateDocument } from "../../src/index";
+
+export async function main() {
+  scriptTitle("07", "Validation");
+  const collection = await createDemoCollection();
+  const story = collection.getModel(
+    "stories/authentication/a-user-should-be-able-to-register",
+    Story
+  );
+
+  await demo({
+    title: "Instance validation",
+    description: "Validate a model instance against its Zod schemas.",
+    code: `const story = collection.getModel("stories/.../register", Story);
+const result = await story.validate();`,
+    run: async () => {
+      const result = await story.validate();
+      return [
+        kv("Valid", result.valid),
+        kv("Errors", result.errors.length),
+      ].join("\n");
+    },
+  });
+
+  await demo({
+    title: "Standalone validateDocument()",
+    description: "Validate any document against a model definition without creating an instance.",
+    code: `import { validateDocument } from "contentbase";
+const doc = collection.document("stories/.../register");
+const result = validateDocument(doc, Story);`,
+    run: () => {
+      const doc = collection.document(
+        "stories/authentication/a-user-should-be-able-to-register"
+      );
+      const result = validateDocument(doc, Story);
+      return [
+        kv("Valid", result.valid),
+        kv("Errors", result.errors.length),
+      ].join("\n");
+    },
+  });
+}
+
+if (import.meta.main) main().catch(console.error);

package/scripts/examples/08-serialization.ts

@@ -0,0 +1,51 @@
+import { scriptTitle, demo, kv } from "./lib/format";
+import { createDemoCollection, Epic } from "./lib/setup";
+
+export async function main() {
+  scriptTitle("08", "Serialization");
+  const collection = await createDemoCollection();
+  const epic = collection.getModel("epics/authentication", Epic);
+
+  await demo({
+    title: "toJSON() — basic",
+    code: `epic.toJSON();`,
+    run: () => epic.toJSON(),
+  });
+
+  await demo({
+    title: "toJSON() — with computed and relationships",
+    code: `epic.toJSON({
+  computed: ["isComplete"],
+  related: ["stories"],
+});`,
+    run: () =>
+      epic.toJSON({
+        computed: ["isComplete"],
+        related: ["stories"],
+      }),
+  });
+
+  await demo({
+    title: "Table of contents",
+    description: "Generate a markdown TOC with links for the whole collection.",
+    code: `collection.tableOfContents({ title: "SDLC Docs" });`,
+    run: () => collection.tableOfContents({ title: "SDLC Docs" }),
+  });
+
+  await demo({
+    title: "Collection export",
+    description: "Export all model data as a JSON snapshot.",
+    code: `const data = await collection.export();
+Object.keys(data);`,
+    run: async () => {
+      const data = await collection.export();
+      return [
+        kv("Keys", Object.keys(data).join(", ")),
+        kv("Models", Object.keys(data.modelData as object).join(", ")),
+        kv("Item count", (data.itemIds as string[]).length),
+      ].join("\n");
+    },
+  });
+}
+
+if (import.meta.main) main().catch(console.error);

package/scripts/examples/lib/format.ts

@@ -0,0 +1,87 @@
+// ANSI escape codes
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  yellow: "\x1b[33m",
+  green: "\x1b[32m",
+  gray: "\x1b[90m",
+  magenta: "\x1b[35m",
+  white: "\x1b[37m",
+};
+
+export function scriptTitle(num: string, title: string) {
+  const text = ` ${num}. ${title} `;
+  const line = "═".repeat(text.length + 2);
+  console.log();
+  console.log(`${c.cyan}${c.bold}╔${line}╗${c.reset}`);
+  console.log(`${c.cyan}${c.bold}║ ${text} ║${c.reset}`);
+  console.log(`${c.cyan}${c.bold}╚${line}╝${c.reset}`);
+  console.log();
+}
+
+interface DemoBlock {
+  title: string;
+  description?: string;
+  code: string;
+  run: () => unknown | Promise<unknown>;
+}
+
+export async function demo(block: DemoBlock) {
+  // Title
+  console.log(`  ${c.yellow}${c.bold}▸ ${block.title}${c.reset}`);
+
+  // Description
+  if (block.description) {
+    console.log(`  ${c.dim}${block.description}${c.reset}`);
+  }
+
+  // Code box
+  const codeLines = block.code.split("\n");
+  const maxLen = Math.max(...codeLines.map((l) => l.length));
+  const border = "─".repeat(maxLen + 2);
+
+  console.log(`  ${c.dim}┌${border}┐${c.reset}`);
+  for (const line of codeLines) {
+    console.log(`  ${c.dim}│${c.reset} ${line.padEnd(maxLen)} ${c.dim}│${c.reset}`);
+  }
+  console.log(`  ${c.dim}└${border}┘${c.reset}`);
+
+  // Run and display output
+  const result = await block.run();
+
+  if (result != null) {
+    let output: string;
+    if (typeof result === "string") {
+      output = result;
+    } else {
+      output = JSON.stringify(result, null, 2);
+    }
+
+    const outLines = output.split("\n");
+    const outMaxLen = Math.max(...outLines.map((l) => l.length));
+    const outBorder = "─".repeat(outMaxLen + 2);
+
+    console.log(`  ${c.green}┌${outBorder}┐${c.reset}`);
+    for (const line of outLines) {
+      console.log(`  ${c.green}│${c.reset} ${c.green}${line.padEnd(outMaxLen)}${c.reset} ${c.green}│${c.reset}`);
+    }
+    console.log(`  ${c.green}└${outBorder}┘${c.reset}`);
+  }
+
+  console.log();
+}
+
+export function kv(key: string, value: unknown): string {
+  return `${c.magenta}${key}:${c.reset} ${value}`;
+}
+
+export function list(items: string[]): string {
+  return items.map((item) => `  • ${item}`).join("\n");
+}
+
+export function heading(text: string) {
+  console.log(`  ${c.cyan}${c.bold}${text}${c.reset}`);
+  console.log();
+}