contentbase 0.0.2 → 0.0.5

package/src/relationships/has-many.ts

@@ -51,6 +51,7 @@ export class HasManyRelationship<
    */
   private extractChildNodes(): ChildNode[] {
     const { astQuery } = this.#document;
+    if (!this.#definition.heading) return [];
     const parentHeading = astQuery.findHeadingByText(this.#definition.heading);
     if (!parentHeading) return [];
 
@@ -100,6 +101,14 @@ export class HasManyRelationship<
 
   fetchAll(): InferModelInstance<TTarget>[] {
     const targetDef = this.#definition.target();
+
+    // Foreign key mode: query for target documents where meta[foreignKey] matches this document's slug
+    // Used when foreignKey is explicitly set, or when no heading is specified (convention-based)
+    if (this.#definition.foreignKey || !this.#definition.heading) {
+      return this.#fetchByForeignKey(targetDef);
+    }
+
+    // Heading mode: extract child nodes from parent document AST
     const childNodes = this.extractChildNodes();
 
     return childNodes.map(({ id, ast }) => {
@@ -119,6 +128,36 @@ export class HasManyRelationship<
     });
   }
 
+  #fetchByForeignKey(targetDef: TTarget): InferModelInstance<TTarget>[] {
+    // If foreignKey is explicitly set, use it. Otherwise infer from the parent document's model.
+    // Convention: look for meta[lowercase(parentModelName)] on target documents.
+    // e.g. Project hasMany Plans → looks for meta.project on Plan documents.
+    const fk = this.#definition.foreignKey || this.#inferForeignKey();
+    const slug = this.#document.slug;
+    const prefix = targetDef.prefix;
+    const results: InferModelInstance<TTarget>[] = [];
+
+    for (const pathId of this.#collection.available) {
+      if (!pathId.startsWith(prefix + "/")) continue;
+      const doc = this.#collection.document(pathId);
+      if (doc.meta[fk] === slug) {
+        results.push(this.#factory(doc, targetDef, this.#collection));
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Infer the foreign key name from the parent document's prefix.
+   * e.g. if the parent is in "projects/", the FK is "project" (singularized, lowercased).
+   */
+  #inferForeignKey(): string {
+    const parentPrefix = this.#document.id.split("/")[0];
+    // Simple singularize: strip trailing "s"
+    return parentPrefix.replace(/s$/, "");
+  }
+
   first(): InferModelInstance<TTarget> | undefined {
     return this.fetchAll()[0];
   }

package/src/relationships/index.ts

@@ -7,7 +7,10 @@ import type {
 
 /**
  * Declare a hasMany relationship.
- * Child models are extracted from sub-headings under a parent heading.
+ *
+ * Two modes:
+ * - `heading`: Children are extracted from sub-headings under a parent heading in the document.
+ * - `foreignKey`: Children are found by querying target documents where meta[foreignKey] matches this document's slug.
  *
  * The target parameter is a thunk (() => ModelDef) to allow circular references.
  */
@@ -16,7 +19,8 @@ export function hasMany<
 >(
   target: () => TTarget,
   options: {
-    heading: string;
+    heading?: string;
+    foreignKey?: string;
     meta?: (self: any) => Record<string, unknown>;
     id?: (slug: string) => string;
   }
@@ -25,6 +29,7 @@ export function hasMany<
     type: "hasMany",
     target,
     heading: options.heading,
+    foreignKey: options.foreignKey,
     meta: options.meta,
     id: options.id,
   };

package/src/section.ts

@@ -19,10 +19,12 @@ export function section<T>(
   options: {
     extract: (query: AstQuery) => T;
     schema?: z.ZodType<T>;
+    alternatives?: string[];
   }
 ): SectionDefinition<T> {
   return {
     heading,
+    alternatives: options.alternatives,
     extract: options.extract,
     schema: options.schema,
   };

package/src/types.ts

@@ -12,6 +12,7 @@ export interface CollectionItem {
   path: string;
   createdAt: Date;
   updatedAt: Date;
+  size: number;
 }
 
 /** Options when constructing a Collection */
@@ -19,6 +20,8 @@ export interface CollectionOptions {
   rootPath: string;
   extensions?: string[];
   name?: string;
+  /** When true (default), load() looks for a models.{ts,js,mjs} in rootPath and auto-registers exported model definitions. */
+  autoDiscover?: boolean;
 }
 
 // ─── Section system ───
@@ -30,6 +33,8 @@ export interface CollectionOptions {
 export interface SectionDefinition<T = unknown> {
   /** The heading text to find in the document */
   heading: string;
+  /** Alternative heading texts to try if the primary heading is not found */
+  alternatives?: string[];
   /** Extract structured data from the section's AST query */
   extract: (query: AstQuery) => T;
   /** Optional Zod schema to validate the extracted value */
@@ -43,7 +48,10 @@ export interface HasManyDefinition<
 > {
   type: "hasMany";
   target: () => TTarget;
-  heading: string;
+  /** Extract children from sub-headings under this heading in the parent document */
+  heading?: string;
+  /** Find children by querying for target documents where meta[foreignKey] matches this document's slug */
+  foreignKey?: string;
   meta?: (self: any) => Record<string, unknown>;
   id?: (slug: string) => string;
 }
@@ -100,8 +108,17 @@ export interface ModelDefinition<
   sections: TSections;
   relationships: TRelationships;
   computed: TComputed;
+  /** Human-readable description of this model, auto-generated if not provided */
+  description: string;
+  /** 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;
 
   /** The inferred Zod schema for convenience (same as meta) */
   schema: TMeta;
@@ -131,6 +148,11 @@ export type InferModelInstance<
         readonly document: import("./document.js").Document;
         readonly collection: import("./collection.js").Collection;
 
+        // File metadata
+        readonly createdAt: Date | undefined;
+        readonly updatedAt: Date | undefined;
+        readonly size: number | undefined;
+
         // Typed meta from Zod schema
         readonly meta: z.infer<TMeta>;
 

package/src/utils/index.ts

@@ -9,3 +9,4 @@ export { stringifyAst } from "./stringify-ast";
 export { parseTable } from "./parse-table";
 export { normalizeHeadings } from "./normalize-headings";
 export { readDirectory } from "./read-directory";
+export { matchPattern, matchPatterns } from "./match-pattern";

package/src/utils/match-pattern.ts

@@ -0,0 +1,65 @@
+/**
+ * Express-style path pattern matching for extracting named parameters
+ * from document pathIds.
+ *
+ * Patterns use `:param` syntax for named segments and literal segments
+ * for exact matching. Segment counts must match exactly.
+ *
+ * Examples:
+ *   matchPattern("plans/:project/:slug", "plans/acme/launch")
+ *   // => { project: "acme", slug: "launch" }
+ *
+ *   matchPattern("plans/:project/:slug", "stories/acme/launch")
+ *   // => null (literal mismatch)
+ */
+
+/**
+ * Match a single pattern against a pathId.
+ * Returns extracted params on match, null on mismatch.
+ */
+export function matchPattern(
+  pattern: string,
+  pathId: string
+): Record<string, string> | null {
+  const patternParts = pattern.split("/").filter(Boolean);
+  const pathParts = pathId.split("/").filter(Boolean);
+
+  if (patternParts.length !== pathParts.length) {
+    return null;
+  }
+
+  const params: Record<string, string> = {};
+
+  for (let i = 0; i < patternParts.length; i++) {
+    const pat = patternParts[i];
+    const val = pathParts[i];
+
+    if (pat.startsWith(":")) {
+      params[pat.slice(1)] = val;
+    } else if (pat !== val) {
+      return null;
+    }
+  }
+
+  return params;
+}
+
+/**
+ * Try multiple patterns against a pathId, returning the first match.
+ * Accepts a single pattern string or an array of patterns.
+ */
+export function matchPatterns(
+  patterns: string | string[],
+  pathId: string
+): Record<string, string> | null {
+  const list = Array.isArray(patterns) ? patterns : [patterns];
+
+  for (const pattern of list) {
+    const result = matchPattern(pattern, pathId);
+    if (result !== null) {
+      return result;
+    }
+  }
+
+  return null;
+}

package/src/validator.ts

@@ -5,6 +5,7 @@ import type {
   ValidationResult,
 } from "./types";
 import type { Document } from "./document";
+import { matchPatterns } from "./utils/match-pattern";
 
 /**
  * Standalone validator that checks a document against a model definition's
@@ -19,12 +20,28 @@ export function validateDocument(
   const errors: z.ZodIssue[] = [];
 
   // Validate meta
-  const rawMeta = { ...(definition.defaults ?? {}), ...document.meta };
+  const patternMeta = definition.pattern
+    ? matchPatterns(definition.pattern, document.id) ?? {}
+    : {};
+  const rawMeta = { ...(definition.defaults ?? {}), ...patternMeta, ...document.meta };
   const metaResult = definition.meta.safeParse(rawMeta);
   if (!metaResult.success) {
     errors.push(...metaResult.error.issues);
   }
 
+  // Validate title: require H1 heading unless titleOptional or meta.title exists
+  if (!definition.titleOptional) {
+    const hasMetaTitle = !!document.meta.title;
+    const hasH1 = !!document.astQuery.select("heading");
+    if (!hasMetaTitle && !hasH1) {
+      errors.push({
+        code: "custom",
+        path: ["title"],
+        message: `Document "${document.id}" is missing a title. Add an H1 heading or set meta.title.`,
+      });
+    }
+  }
+
   // Validate sections
   if (definition.sections) {
     for (const [key, sd] of Object.entries(definition.sections)) {