contentbase 0.0.2 → 0.0.5

package/examples/sdlc-queries.ts

@@ -1,161 +0,0 @@
-/**
- * Contentbase Example: Querying an SDLC Content Collection
- *
- * This script demonstrates loading a collection of Epics and Stories
- * from markdown files and querying them using the Contentbase API.
- *
- * Run with: bun run examples/sdlc-queries.ts
- */
-import path from "path";
-import { fileURLToPath } from "url";
-import { Collection, type InferModelInstance } from "../src/index";
-import { Epic, Story, type StoryDef } from "../test/fixtures/sdlc/models";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const basePath = path.resolve(__dirname, "../test/fixtures/sdlc");
-
-async function main() {
-  // 1. Create and load the collection
-  const collection = new Collection({
-    rootPath: basePath,
-    name: "sdlc",
-  });
-
-  collection.register(Epic);
-  collection.register(Story);
-  await collection.load();
-
-  console.log("Available documents:", collection.available);
-
-  // -------------------------------------------------------
-  // 2. Get a single model instance by path ID
-  // -------------------------------------------------------
-  const authEpic = collection.getModel("epics/authentication", Epic);
-
-  console.log("\n--- Epic: Authentication ---");
-  console.log("Title:", authEpic.title);
-  console.log("Slug:", authEpic.slug);
-  console.log("Status:", authEpic.meta.status);
-  console.log("Priority:", authEpic.meta.priority);
-  console.log("Is complete?", authEpic.computed.isComplete);
-
-  // -------------------------------------------------------
-  // 3. Query all epics
-  // -------------------------------------------------------
-  const allEpics = await collection.query(Epic).fetchAll();
-
-  console.log("\n--- All Epics ---");
-  for (const epic of allEpics) {
-    console.log(`  ${epic.title} (${epic.meta.status})`);
-  }
-
-  // -------------------------------------------------------
-  // 4. Filter with where clauses
-  // -------------------------------------------------------
-  const highPriority = await collection
-    .query(Epic)
-    .where("meta.priority", "high")
-    .fetchAll();
-
-  console.log("\n--- High Priority Epics ---");
-  for (const epic of highPriority) {
-    console.log(`  ${epic.title} — priority: ${epic.meta.priority}`);
-  }
-
-  // -------------------------------------------------------
-  // 5. Query helpers: first, last, count
-  // -------------------------------------------------------
-  const firstEpic = await collection.query(Epic).first();
-  const lastEpic = await collection.query(Epic).last();
-  const epicCount = await collection.query(Epic).count();
-
-  console.log("\n--- Query Helpers ---");
-  console.log("First epic:", firstEpic?.title);
-  console.log("Last epic:", lastEpic?.title);
-  console.log("Total epics:", epicCount);
-
-  // -------------------------------------------------------
-  // 6. Chained where clauses (AND logic)
-  // -------------------------------------------------------
-  const filtered = await collection
-    .query(Epic)
-    .where("meta.status", "created")
-    .whereExists("meta.priority")
-    .fetchAll();
-
-  console.log("\n--- Created Epics with Priority Set ---");
-  for (const epic of filtered) {
-    console.log(`  ${epic.title} — ${epic.meta.priority}`);
-  }
-
-  // -------------------------------------------------------
-  // 7. HasMany relationships — Epic -> Stories
-  // -------------------------------------------------------
-  const stories = authEpic.relationships.stories.fetchAll();
-
-  console.log("\n--- Stories under Authentication Epic ---");
-  for (const story of stories) {
-    console.log(`  ${story.title}`);
-  }
-
-  console.log("First story:", authEpic.relationships.stories.first()?.title);
-  console.log("Last story:", authEpic.relationships.stories.last()?.title);
-
-  // -------------------------------------------------------
-  // 8. BelongsTo relationships — Story -> Epic
-  // -------------------------------------------------------
-  const registerStory: InferModelInstance<StoryDef> = collection.getModel(
-    "stories/authentication/a-user-should-be-able-to-register",
-    Story
-  );
-
-  const parentEpic = registerStory.relationships.epic.fetch();
-
-  console.log("\n--- Story -> Epic (belongsTo) ---");
-  console.log(`"${registerStory.title}" belongs to "${parentEpic.title}"`);
-
-  // -------------------------------------------------------
-  // 9. Sections — structured data extracted from headings
-  // -------------------------------------------------------
-  console.log("\n--- Sections: Acceptance Criteria ---");
-  for (const criterion of registerStory.sections.acceptanceCriteria) {
-    console.log(`  • ${criterion}`);
-  }
-
-  console.log("\n--- Sections: Mockups ---");
-  for (const [label, url] of Object.entries(registerStory.sections.mockups)) {
-    console.log(`  ${label}: ${url}`);
-  }
-
-  // -------------------------------------------------------
-  // 10. Validation
-  // -------------------------------------------------------
-  const result = await registerStory.validate();
-
-  console.log("\n--- Validation ---");
-  console.log("Valid?", result.valid);
-  console.log("Error count:", result.errors.length);
-
-  // -------------------------------------------------------
-  // 11. Serialization
-  // -------------------------------------------------------
-  const json = authEpic.toJSON({
-    computed: ["isComplete"],
-    related: ["stories"],
-  });
-
-  console.log("\n--- toJSON ---");
-  console.log(JSON.stringify(json, null, 2));
-
-  // -------------------------------------------------------
-  // 12. Working with the raw Document
-  // -------------------------------------------------------
-  const doc = authEpic.document;
-
-  console.log("\n--- Raw Document ---");
-  console.log("Headings:", doc.nodes.headings.length);
-  console.log("Links:", doc.nodes.links.length);
-  console.log("Lists:", doc.nodes.lists.length);
-}
-
-main().catch(console.error);

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

@@ -1,46 +0,0 @@
-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

@@ -1,67 +0,0 @@
-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

@@ -1,36 +0,0 @@
-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

@@ -1,54 +0,0 @@
-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

@@ -1,54 +0,0 @@
-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

@@ -1,55 +0,0 @@
-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

@@ -1,46 +0,0 @@
-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

@@ -1,51 +0,0 @@
-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

@@ -1,87 +0,0 @@
-// 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();
-}

package/scripts/examples/lib/setup.ts

@@ -1,21 +0,0 @@
-import path from "path";
-import { Collection } from "../../../src/collection";
-import { Epic, Story } from "../../../test/fixtures/sdlc/models";
-
-const dir = import.meta.dirname ?? new URL(".", import.meta.url).pathname;
-
-const FIXTURES_PATH = path.resolve(dir, "../../../test/fixtures/sdlc");
-
-export async function createDemoCollection(): Promise<Collection> {
-  const collection = new Collection({
-    rootPath: FIXTURES_PATH,
-    name: "sdlc",
-  });
-  collection.register(Epic);
-  collection.register(Story);
-  await collection.load();
-  return collection;
-}
-
-export { Epic, Story };
-export { FIXTURES_PATH };