contentbase 0.0.1 → 0.0.4

package/src/define-model.ts

@@ -11,18 +11,27 @@ 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>,
 > {
   prefix?: string;
+  /** Human-readable description of this model. Auto-generated from schema if not provided. */
+  description?: string;
   meta?: TMeta;
   sections?: TSections;
   relationships?: TRelationships;
   computed?: TComputed;
+  /** Named scopes — reusable query presets */
+  scopes?: Record<string, (query: any) => any>;
   match?: (doc: DocumentRef) => boolean;
   defaults?: Partial<z.input<TMeta>>;
+  pattern?: string | string[];
+  /** Glob patterns or RegExp to exclude matching pathIds from queries, listings, and TOC */
+  exclude?: (string | RegExp)[];
+  /** When true, documents are not required to have an H1 title */
+  titleOptional?: boolean;
 }
 
 /**
@@ -42,7 +51,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,17 +73,105 @@ 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;
+  const sections = (config.sections ?? ({} as any)) as TSections;
+  const relationships = (config.relationships ?? ({} as any)) as TRelationships;
+  const computed = (config.computed ?? ({} as any)) as TComputed;
 
-  return {
+  const def: any = {
     name,
     prefix: config.prefix ?? pluralize(name.toLowerCase()),
     meta,
     schema: meta,
-    sections: (config.sections ?? ({} as any)) as TSections,
-    relationships: (config.relationships ?? ({} as any)) as TRelationships,
-    computed: (config.computed ?? ({} as any)) as TComputed,
+    sections,
+    relationships,
+    computed,
+    scopes: config.scopes ?? {},
     match: config.match,
     defaults: config.defaults,
+    pattern: config.pattern,
+    exclude: config.exclude,
+    titleOptional: config.titleOptional,
   };
+
+  // description is lazy — computed on first access if not provided by the user.
+  // This avoids calling relationship target thunks during defineModel() which
+  // would break circular references (e.g. Epic ↔ Story).
+  if (config.description) {
+    def.description = config.description;
+  } else {
+    let cached: string | undefined;
+    Object.defineProperty(def, "description", {
+      get() {
+        if (cached === undefined) {
+          cached = generateDescription(name, meta, sections, relationships, computed);
+        }
+        return cached;
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  }
+
+  return def;
+}
+
+/**
+ * Auto-generates a human-readable description from the model's schema.
+ * Safe to call after all models are defined (relationship thunks are resolved lazily).
+ */
+export function generateDescription(
+  name: string,
+  meta: z.ZodType,
+  sections: Record<string, SectionDefinition<any>>,
+  relationships: Record<string, RelationshipDefinition<any>>,
+  computed: Record<string, (self: any) => any>
+): string {
+  const parts: string[] = [];
+
+  // Extract meta field names from Zod schema shape
+  const shape = (meta as any)?._zod?.def?.shape;
+  const metaKeys = shape ? Object.keys(shape) : [];
+  if (metaKeys.length > 0) {
+    parts.push(`metadata (${metaKeys.join(", ")})`);
+  }
+
+  // Section headings
+  const sectionEntries = Object.values(sections ?? {});
+  if (sectionEntries.length > 0) {
+    const headings = sectionEntries.map((s: any) => s.heading);
+    parts.push(`section${headings.length === 1 ? "" : "s"} (${headings.join(", ")})`);
+  }
+
+  // Relationships — resolve target thunks now (safe at access time, not at define time)
+  const relEntries = Object.entries(relationships ?? {});
+  if (relEntries.length > 0) {
+    const relDescs = relEntries.map(([key, rel]: [string, any]) => {
+      const targetName = typeof rel.target === "function" ? rel.target()?.name : undefined;
+      return targetName ? `${key} → ${targetName}` : key;
+    });
+    parts.push(`relationship${relDescs.length === 1 ? "" : "s"} (${relDescs.join(", ")})`);
+  }
+
+  // Computed
+  const computedKeys = Object.keys(computed ?? {});
+  if (computedKeys.length > 0) {
+    parts.push(`computed ${computedKeys.length === 1 ? "property" : "properties"} (${computedKeys.join(", ")})`);
+  }
+
+  // Scopes — accessed from the definition at runtime, not passed as parameter
+  // to keep backward compat with existing callers
+
+  if (parts.length === 0) {
+    return `A ${name} document.`;
+  }
+
+  const article = /^[aeiou]/i.test(name) ? "An" : "A";
+  return `${article} ${name} has ${joinNatural(parts)}.`;
+}
+
+function joinNatural(items: string[]): string {
+  if (items.length <= 1) return items[0] ?? "";
+  if (items.length === 2) return `${items[0]} and ${items[1]}`;
+  return items.slice(0, -1).join(", ") + ", and " + items[items.length - 1];
 }

package/src/document.ts

@@ -54,6 +54,7 @@ export class Document {
   }
 
   get title(): string {
+    if (this.#meta.title) return String(this.#meta.title);
     const heading = this.astQuery.select("heading");
     return heading ? toString(heading) : this.id;
   }
@@ -62,6 +63,18 @@ export class Document {
     return kebabCase(this.title.toLowerCase());
   }
 
+  get createdAt(): Date | undefined {
+    return this.collection.items.get(this.id)?.createdAt;
+  }
+
+  get updatedAt(): Date | undefined {
+    return this.collection.items.get(this.id)?.updatedAt;
+  }
+
+  get size(): number | undefined {
+    return this.collection.items.get(this.id)?.size;
+  }
+
   get rawContent(): string {
     if (Object.keys(this.#meta).length === 0) {
       return this.content;
@@ -71,7 +84,7 @@ export class Document {
   }
 
   get path(): string {
-    return this.collection.resolve(this.id) + ".mdx";
+    return this.collection.resolve(this.id) + ".md";
   }
 
   // ─── Processor ───
@@ -112,6 +125,11 @@ export class Document {
       heading = this.astQuery.findHeadingByText(startHeading) as
         | Content
         | undefined;
+
+      // If not found, try alternatives from the model definition's sections
+      if (!heading) {
+        heading = this.#resolveAlternativeHeading(startHeading);
+      }
     } else {
       heading = startHeading;
     }
@@ -128,6 +146,28 @@ export class Document {
     return [heading, ...sectionNodes];
   }
 
+  /**
+   * Look up section alternatives from the model definition.
+   * If the requested heading matches a section's heading or is one of its alternatives,
+   * try all variants (primary + alternatives) until one is found in the AST.
+   */
+  #resolveAlternativeHeading(requestedHeading: string): Content | undefined {
+    const def = this.collection?.findModelDefinition?.(this.id);
+    if (!def?.sections) return undefined;
+
+    for (const sectionDef of Object.values(def.sections) as any[]) {
+      const allNames = [sectionDef.heading, ...(sectionDef.alternatives ?? [])];
+      if (!allNames.some((n: string) => n === requestedHeading)) continue;
+
+      for (const name of allNames) {
+        const found = this.astQuery.findHeadingByText(name) as Content | undefined;
+        if (found) return found;
+      }
+    }
+
+    return undefined;
+  }
+
   /**
    * Returns an AstQuery scoped to the nodes underneath a particular heading,
    * excluding the heading itself.
@@ -388,12 +428,18 @@ export class Document {
     meta: Record<string, unknown>;
     content: string;
     ast: Root;
+    createdAt: Date | undefined;
+    updatedAt: Date | undefined;
+    size: number | undefined;
   } {
     return {
       id: this.id,
       meta: this.meta,
       content: this.content,
       ast: this.ast,
+      createdAt: this.createdAt,
+      updatedAt: this.updatedAt,
+      size: this.size,
     };
   }
 

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

@@ -1,19 +1,34 @@
 // Core classes
-export { Collection } from "./collection";
+export { Collection, introspectMetaSchema } from "./collection";
+export type { FieldInfo } from "./collection";
 export { Document } from "./document";
 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";
+export { defineModel, generateDescription } from "./define-model";
+export { Base } from "./base-model";
 export { section } from "./section";
 export { hasMany, belongsTo } from "./relationships/index";
 
 // Query
 export { CollectionQuery } from "./query/collection-query";
 export { QueryBuilder } from "./query/query-builder";
+export {
+  queryDSLSchema,
+  parseWhereClause,
+  parseSortClause,
+  executeQueryDSL,
+} from "./query/query-dsl";
+export type { QueryDSL } from "./query/query-dsl";
 
 // Model instance factory (advanced use)
 export { createModelInstance } from "./model-instance";
@@ -21,6 +36,9 @@ export { createModelInstance } from "./model-instance";
 // Validation
 export { validateDocument } from "./validator";
 
+// Pattern matching
+export { matchPattern, matchPatterns } from "./utils/match-pattern";
+
 import { toString } from "mdast-util-to-string";
 
 // Types

package/src/model-instance.ts

@@ -12,6 +12,7 @@ import type { Document } from "./document";
 import type { Collection } from "./collection";
 import { HasManyRelationship } from "./relationships/has-many";
 import { BelongsToRelationship } from "./relationships/belongs-to";
+import { matchPatterns } from "./utils/match-pattern";
 
 /**
  * Creates a model instance from a document and its model definition.
@@ -26,8 +27,11 @@ export function createModelInstance<
   definition: TDef,
   collection: Collection
 ): InferModelInstance<TDef> {
-  // ─── Meta: merge defaults, parse with Zod ───
-  const rawMeta = { ...(definition.defaults ?? {}), ...document.meta };
+  // ─── Meta: merge defaults, pattern-inferred values, then frontmatter ───
+  const patternMeta = definition.pattern
+    ? matchPatterns(definition.pattern, document.id) ?? {}
+    : {};
+  const rawMeta = { ...(definition.defaults ?? {}), ...patternMeta, ...document.meta };
   let meta: any;
   try {
     meta = definition.meta.parse(rawMeta);
@@ -46,7 +50,19 @@ export function createModelInstance<
       Object.defineProperty(sections, key, {
         get() {
           if (!cached) {
-            const sectionQuery = document.querySection(sd.heading);
+            let heading = sd.heading;
+            if (sd.alternatives?.length) {
+              const found = document.astQuery.findHeadingByText(heading);
+              if (!found) {
+                for (const alt of sd.alternatives) {
+                  if (document.astQuery.findHeadingByText(alt)) {
+                    heading = alt;
+                    break;
+                  }
+                }
+              }
+            }
+            const sectionQuery = document.querySection(heading);
             cached = { value: sd.extract(sectionQuery) };
           }
           return cached.value;
@@ -152,6 +168,9 @@ export function createModelInstance<
       id: document.id,
       title: document.title,
       meta,
+      createdAt: document.createdAt,
+      updatedAt: document.updatedAt,
+      size: document.size,
     };
 
     // Include requested sections
@@ -198,8 +217,15 @@ export function createModelInstance<
     get slug() {
       return document.slug;
     },
-    document,
-    collection,
+    get createdAt() {
+      return document.createdAt;
+    },
+    get updatedAt() {
+      return document.updatedAt;
+    },
+    get size() {
+      return document.size;
+    },
     meta,
     sections,
     relationships,
@@ -223,5 +249,9 @@ export function createModelInstance<
     },
   };
 
+  // Keep heavy back-references accessible but out of REPL output
+  Object.defineProperty(instance, "document", { value: document, enumerable: false });
+  Object.defineProperty(instance, "collection", { value: collection, enumerable: false });
+
   return instance as InferModelInstance<TDef>;
 }

package/src/node-shortcuts.ts

@@ -50,7 +50,7 @@ export class NodeShortcuts {
     return this.headings.reduce(
       (memo, heading) => {
         memo[heading.depth] = memo[heading.depth] || [];
-        memo[heading.depth].push(heading);
+        memo[heading.depth]!.push(heading);
         return memo;
       },
       {} as Record<number, Heading[]>