contentbase 0.0.1 → 0.0.2

package/scripts/examples/lib/setup.ts

@@ -0,0 +1,21 @@
+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 };

package/scripts/examples/run-all.ts

@@ -0,0 +1,43 @@
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+};
+
+const scripts = [
+  "01-collection-setup",
+  "02-querying",
+  "03-sections",
+  "04-relationships",
+  "05-document-api",
+  "06-extract-sections",
+  "07-validation",
+  "08-serialization",
+];
+
+async function runAll() {
+  console.log();
+  console.log(
+    `${c.cyan}${c.bold}  ╔══════════════════════════════════════╗${c.reset}`
+  );
+  console.log(
+    `${c.cyan}${c.bold}  ║   Contentbase — Interactive Examples ║${c.reset}`
+  );
+  console.log(
+    `${c.cyan}${c.bold}  ╚══════════════════════════════════════╝${c.reset}`
+  );
+
+  for (const script of scripts) {
+    const mod = await import(`./${script}`);
+    await mod.main();
+  }
+
+  console.log(
+    `${c.green}${c.bold}  ✓ All ${scripts.length} example scripts completed.${c.reset}`
+  );
+  console.log();
+}
+
+runAll().catch(console.error);

package/src/collection.ts

@@ -348,6 +348,104 @@ export class Collection {
     return relativePath.replace(/\.[a-z]+$/i, "");
   }
 
+  // ─── Table of Contents ───
+
+  /**
+   * Generate a markdown table of contents with links to each document.
+   * Links use relative paths that work for GitHub navigation.
+   *
+   * If models are registered, items are grouped under model name headings.
+   * Items that don't match any model appear under an "Other" group.
+   *
+   * @example
+   * ```ts
+   * const toc = collection.tableOfContents({ title: "Project Docs" });
+   * // # Project Docs
+   * //
+   * // ## Epics
+   * //
+   * // - [Authentication](./epics/authentication.mdx)
+   * // - [Searching And Browsing](./epics/searching-and-browsing.mdx)
+   * //
+   * // ## Stories
+   * //
+   * // - [A User should be able to register.](./stories/authentication/a-user-should-be-able-to-register.mdx)
+   * ```
+   */
+  tableOfContents(
+    options: { title?: string; basePath?: string } = {}
+  ): string {
+    if (!this.#loaded) {
+      throw new Error(
+        "Collection has not been loaded. Call load() first."
+      );
+    }
+
+    const basePath = options.basePath ?? ".";
+    const lines: string[] = [];
+
+    if (options.title) {
+      lines.push(`# ${options.title}`, "");
+    }
+
+    const sorted = [...this.available].sort();
+
+    if (this.#models.size > 0) {
+      const grouped = new Map<string, string[]>();
+      const ungrouped: string[] = [];
+
+      for (const pathId of sorted) {
+        const def = this.findModelDefinition(pathId);
+        if (def) {
+          let group = grouped.get(def.name);
+          if (!group) {
+            group = [];
+            grouped.set(def.name, group);
+          }
+          group.push(pathId);
+        } else {
+          ungrouped.push(pathId);
+        }
+      }
+
+      for (const def of this.modelDefinitions) {
+        const ids = grouped.get(def.name);
+        if (!ids || ids.length === 0) continue;
+
+        const depth = options.title ? "##" : "#";
+        lines.push(`${depth} ${def.name}`, "");
+        for (const id of ids) {
+          lines.push(this.#tocEntry(id, basePath));
+        }
+        lines.push("");
+      }
+
+      if (ungrouped.length > 0) {
+        const depth = options.title ? "##" : "#";
+        lines.push(`${depth} Other`, "");
+        for (const id of ungrouped) {
+          lines.push(this.#tocEntry(id, basePath));
+        }
+        lines.push("");
+      }
+    } else {
+      for (const id of sorted) {
+        lines.push(this.#tocEntry(id, basePath));
+      }
+      lines.push("");
+    }
+
+    return lines.join("\n").trimEnd() + "\n";
+  }
+
+  #tocEntry(pathId: string, basePath: string): string {
+    const item = this.#items.get(pathId)!;
+    const ext = path.extname(item.path);
+    const relativePath = `${basePath}/${pathId}${ext}`;
+    const doc = this.document(pathId);
+    return `- [${doc.title}](${relativePath})`;
+  }
+
   // ─── Serialization ───
 
   toJSON(options: { content?: boolean } = {}): Record<string, unknown> {

package/src/define-model.ts

@@ -11,7 +11,7 @@ import type {
  * Configuration input for defineModel. This is what the user writes.
  */
 export interface DefineModelConfig<
-  TMeta extends z.ZodTypeAny,
+  TMeta extends z.ZodType,
   TSections extends Record<string, SectionDefinition<any>>,
   TRelationships extends Record<string, RelationshipDefinition<any>>,
   TComputed extends Record<string, (self: any) => any>,
@@ -42,7 +42,7 @@ export interface DefineModelConfig<
  */
 export function defineModel<
   TName extends string,
-  TMeta extends z.ZodTypeAny = z.ZodObject<{}, "passthrough">,
+  TMeta extends z.ZodType = z.ZodObject<{}, z.core.$loose>,
   TSections extends Record<string, SectionDefinition<any>> = Record<
     string,
     never
@@ -64,7 +64,7 @@ export function defineModel<
     TComputed
   > = {} as any
 ): ModelDefinition<TName, TMeta, TSections, TRelationships, TComputed> {
-  const meta = (config.meta ?? z.object({}).passthrough()) as TMeta;
+  const meta = (config.meta ?? z.looseObject({})) as TMeta;
 
   return {
     name,

package/src/extract-sections.ts

@@ -0,0 +1,222 @@
+import { toString } from "mdast-util-to-string";
+import { AstQuery } from "./ast-query";
+import { NodeShortcuts } from "./node-shortcuts";
+import { stringifyAst } from "./utils/stringify-ast";
+import type { Root, Content, RootContent, Heading } from "mdast";
+import type { ParsedDocument } from "./parse";
+
+/** Any object that exposes a title and section extraction — satisfied by both Document and ParsedDocument. */
+export type SectionSource = {
+  title: string;
+  extractSection(heading: string | Content): Content[];
+};
+
+export interface ExtractionEntry {
+  /** The source document or parsed document */
+  source: SectionSource;
+  /** Section heading name(s) to extract. A string extracts one section; an array extracts multiple. */
+  sections: string | string[];
+}
+
+export interface ExtractSectionsOptions {
+  /** Optional title for the combined document (becomes an h1). */
+  title?: string;
+  /**
+   * How to organize extracted sections.
+   * - `"grouped"` (default): Each source document gets a heading (its title),
+   *   with extracted sections nested underneath.
+   * - `"flat"`: All extracted sections are placed sequentially with no source grouping.
+   */
+  mode?: "grouped" | "flat";
+  /**
+   * What to do when a requested section is not found in a source document.
+   * - `"skip"` (default): silently omit the missing section
+   * - `"throw"`: throw an error
+   */
+  onMissing?: "skip" | "throw";
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createHeadingNode(
+  text: string,
+  depth: 1 | 2 | 3 | 4 | 5 | 6,
+): Heading {
+  return {
+    type: "heading",
+    depth,
+    children: [{ type: "text", value: text }],
+  };
+}
+
+function clampDepth(d: number): 1 | 2 | 3 | 4 | 5 | 6 {
+  return Math.max(1, Math.min(6, d)) as 1 | 2 | 3 | 4 | 5 | 6;
+}
+
+/** Deep-clone section nodes and shift all heading depths to the target depth. */
+function cloneAndShiftHeadings(
+  nodes: Content[],
+  targetDepth: number,
+): RootContent[] {
+  if (nodes.length === 0) return [];
+
+  const firstNode = nodes[0];
+  const originalDepth =
+    firstNode.type === "heading" ? (firstNode as Heading).depth : 1;
+  const depthShift = targetDepth - originalDepth;
+
+  const cloned = structuredClone(nodes) as RootContent[];
+
+  if (depthShift !== 0) {
+    for (const node of cloned) {
+      if (node.type === "heading") {
+        (node as Heading).depth = clampDepth(
+          (node as Heading).depth + depthShift,
+        );
+      }
+    }
+  }
+
+  return cloned;
+}
+
+function tryExtractSection(
+  source: SectionSource,
+  sectionName: string,
+  onMissing: "skip" | "throw",
+): Content[] | null {
+  try {
+    return source.extractSection(sectionName);
+  } catch (err) {
+    if (onMissing === "throw") throw err;
+    return null;
+  }
+}
+
+function normalizeSections(sections: string | string[]): string[] {
+  return Array.isArray(sections) ? sections : [sections];
+}
+
+/** Build a fully queryable ParsedDocument from an AST root (mirrors parse.ts). */
+function buildParsedDocument(ast: Root): ParsedDocument {
+  const astQuery = new AstQuery(ast);
+  const nodes = new NodeShortcuts(astQuery);
+  const firstHeading = astQuery.select("heading");
+  const title = firstHeading ? toString(firstHeading) : "";
+  const content = stringifyAst(ast);
+
+  function extractSection(startHeading: string | Content): Content[] {
+    let heading: Content | undefined;
+    if (typeof startHeading === "string") {
+      heading = astQuery.findHeadingByText(startHeading) as
+        | Content
+        | undefined;
+    } else {
+      heading = startHeading;
+    }
+    if (!heading) {
+      throw new Error(
+        `Heading not found: ${typeof startHeading === "string" ? startHeading : toString(startHeading)}`,
+      );
+    }
+
+    const endHeading = astQuery.findNextSiblingHeadingTo(heading as any);
+    const sectionNodes = endHeading
+      ? astQuery.findBetween(heading, endHeading)
+      : astQuery.findAllAfter(heading);
+    return [heading, ...sectionNodes];
+  }
+
+  function querySection(startHeading: string | Content): AstQuery {
+    let children: Content[] = [];
+    try {
+      children = extractSection(startHeading).slice(1);
+    } catch {
+      // Section not found: return empty query
+    }
+    return new AstQuery({
+      type: "root",
+      children: children as RootContent[],
+    });
+  }
+
+  return {
+    meta: {},
+    content,
+    ast,
+    astQuery,
+    nodes,
+    title,
+    stringify: (tree: Root = ast) => stringifyAst(tree),
+    extractSection,
+    querySection,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract named sections from multiple documents into a single combined document.
+ *
+ * @example
+ * ```ts
+ * const combined = extractSections([
+ *   { source: doc1, sections: "Acceptance Criteria" },
+ *   { source: doc2, sections: ["Acceptance Criteria", "Mockups"] },
+ * ], {
+ *   title: "All Acceptance Criteria",
+ *   mode: "grouped",
+ * });
+ * ```
+ */
+export function extractSections(
+  entries: ExtractionEntry[],
+  options: ExtractSectionsOptions = {},
+): ParsedDocument {
+  const { title, mode = "grouped", onMissing = "skip" } = options;
+  const combinedChildren: RootContent[] = [];
+
+  let baseDepth = 1;
+  if (title) {
+    combinedChildren.push(createHeadingNode(title, 1));
+    baseDepth = 2;
+  }
+
+  for (const entry of entries) {
+    const { source } = entry;
+    const sectionNames = normalizeSections(entry.sections);
+
+    if (mode === "grouped") {
+      const sourceTitle = source.title || "(Untitled)";
+      combinedChildren.push(
+        createHeadingNode(sourceTitle, clampDepth(baseDepth)),
+      );
+      const sectionTargetDepth = baseDepth + 1;
+
+      for (const sectionName of sectionNames) {
+        const sectionNodes = tryExtractSection(source, sectionName, onMissing);
+        if (!sectionNodes) continue;
+        const shifted = cloneAndShiftHeadings(
+          sectionNodes,
+          sectionTargetDepth,
+        );
+        combinedChildren.push(...shifted);
+      }
+    } else {
+      // flat mode
+      for (const sectionName of sectionNames) {
+        const sectionNodes = tryExtractSection(source, sectionName, onMissing);
+        if (!sectionNodes) continue;
+        const shifted = cloneAndShiftHeadings(sectionNodes, baseDepth);
+        combinedChildren.push(...shifted);
+      }
+    }
+  }
+
+  const ast: Root = { type: "root", children: combinedChildren };
+  return buildParsedDocument(ast);
+}

package/src/index.ts

@@ -5,6 +5,12 @@ export { AstQuery } from "./ast-query";
 export { NodeShortcuts } from "./node-shortcuts";
 export { parse } from "./parse";
 export type { ParsedDocument } from "./parse";
+export { extractSections } from "./extract-sections";
+export type {
+  ExtractionEntry,
+  ExtractSectionsOptions,
+  SectionSource,
+} from "./extract-sections";
 
 // defineModel and helpers
 export { defineModel } from "./define-model";

package/src/types.ts

@@ -80,7 +80,7 @@ export interface DocumentRef {
  */
 export interface ModelDefinition<
   TName extends string = string,
-  TMeta extends z.ZodTypeAny = z.ZodTypeAny,
+  TMeta extends z.ZodType = z.ZodType,
   TSections extends Record<string, SectionDefinition<any>> = Record<
     string,
     never