contentbase 0.0.2 → 0.0.4

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)) {

package/test/collection.test.ts

@@ -1,4 +1,6 @@
-import { describe, it, expect, beforeEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs/promises";
+import path from "path";
 import { Collection } from "../src/collection";
 import { createTestCollection, FIXTURES_PATH } from "./helpers";
 import { Epic, Story } from "./fixtures/sdlc/models";
@@ -51,7 +53,8 @@ describe("Collection", () => {
   it("registers model definitions", () => {
     expect(collection.getModelDefinition("Epic")).toBeDefined();
     expect(collection.getModelDefinition("Story")).toBeDefined();
-    expect(collection.modelDefinitions.length).toBe(2);
+    expect(collection.getModelDefinition("Base")).toBeDefined();
+    expect(collection.modelDefinitions.length).toBe(3);
   });
 
   it("finds model definition by pathId prefix", () => {
@@ -96,4 +99,117 @@ describe("Collection", () => {
     });
     expect(pluginCalled).toBe(true);
   });
+
+  describe("refresh after delete", () => {
+    let tmpDir: string;
+    let tmpCollection: Collection;
+
+    beforeEach(async () => {
+      tmpDir = await fs.mkdtemp(path.join(import.meta.dirname, ".tmp-refresh-"));
+      // Create two documents
+      const epicDir = path.join(tmpDir, "epics");
+      await fs.mkdir(epicDir, { recursive: true });
+      await fs.writeFile(
+        path.join(epicDir, "one.mdx"),
+        "---\nstatus: created\npriority: 1\n---\n# One\n"
+      );
+      await fs.writeFile(
+        path.join(epicDir, "two.mdx"),
+        "---\nstatus: created\npriority: 2\n---\n# Two\n"
+      );
+
+      tmpCollection = new Collection({ rootPath: tmpDir });
+      tmpCollection.register(Epic);
+      await tmpCollection.load();
+    });
+
+    afterEach(async () => {
+      await fs.rm(tmpDir, { recursive: true });
+    });
+
+    it("evicts cached documents whose files were deleted", async () => {
+      // Access a document so it's in the #documents cache
+      const doc = tmpCollection.document("epics/one");
+      expect(doc.title).toBe("One");
+
+      // Delete the file externally
+      await fs.unlink(path.join(tmpDir, "epics", "one.mdx"));
+
+      // Refresh should succeed without ENOENT
+      await tmpCollection.load({ refresh: true });
+
+      // The deleted document should no longer be available
+      expect(tmpCollection.available).not.toContain("epics/one");
+      expect(tmpCollection.available).toContain("epics/two");
+    });
+  });
+
+  describe("generateModelSummary", () => {
+    let tmpDir: string;
+    let tmpCollection: Collection;
+
+    beforeEach(async () => {
+      tmpDir = await fs.mkdtemp(path.join(import.meta.dirname, ".tmp-summary-"));
+      tmpCollection = new Collection({ rootPath: tmpDir });
+      tmpCollection.register(Epic);
+      tmpCollection.register(Story);
+      await tmpCollection.load();
+    });
+
+    afterEach(async () => {
+      await fs.rm(tmpDir, { recursive: true });
+    });
+
+    it("generates inspect-style text with model info", () => {
+      const text = tmpCollection.generateModelSummary();
+
+      // Collection header
+      expect(text).toContain("Collection:");
+      expect(text).toContain("Root:");
+      expect(text).toContain("Items:");
+
+      // Model entries
+      expect(text).toContain("Model: Epic");
+      expect(text).toContain("Model: Story");
+
+      // Prefixes
+      expect(text).toContain("Prefix: epics");
+      expect(text).toContain("Prefix: stories");
+
+      // Meta attributes
+      expect(text).toContain("priority");
+      expect(text).toContain("status");
+
+      // Sections
+      expect(text).toContain("Sections:");
+
+      // Relationships
+      expect(text).toContain("Relationships:");
+    });
+
+    it("saveModelSummary writes README.md to rootPath", async () => {
+      await tmpCollection.saveModelSummary();
+      const content = await fs.readFile(path.join(tmpDir, "README.md"), "utf8");
+      expect(content).toContain("# Models");
+      expect(content).toContain("## Overview");
+      expect(content).toContain("## Summary");
+    });
+
+    it("saveModelSummary preserves existing Overview content", async () => {
+      // Write an initial README.md with user content in Overview
+      const initial = "# Models\n\n## Overview\n\nThis is my custom overview.\n\n## Summary\n\n```\nold summary\n```\n";
+      await fs.writeFile(path.join(tmpDir, "README.md"), initial, "utf8");
+
+      await tmpCollection.saveModelSummary();
+      const content = await fs.readFile(path.join(tmpDir, "README.md"), "utf8");
+      expect(content).toContain("This is my custom overview.");
+      expect(content).toContain("Model: Epic");
+    });
+
+    it("includes collection actions", () => {
+      tmpCollection.action("deploy", () => {});
+      const text = tmpCollection.generateModelSummary();
+      expect(text).toContain("Actions: deploy");
+    });
+  });
 });

package/test/fixtures/sdlc/MODELS.md

@@ -0,0 +1,106 @@
+# Models
+
+Models define the structure of markdown documents in this collection. Each document is a markdown file with YAML frontmatter (metadata attributes) and a heading-based structure (sections). Models specify the expected frontmatter fields via a schema, named sections that map to `##` headings in the document body, relationships to other models, and computed properties derived at query time.
+
+## Epics
+
+**Prefix:** `epics`
+
+### Attributes
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| priority | enum(`low`, `medium`, `high`) | optional | — | Importance level for prioritization |
+| status | enum(`created`, `in-progress`, `complete`) | optional | `"created"` | Current workflow state |
+
+### Relationships
+
+| Name | Type | Target |
+|------|------|--------|
+| stories | hasMany | Story |
+
+### Computed Properties
+
+- `isComplete`
+
+### Example
+
+```markdown
+---
+priority: medium
+status: created
+---
+
+# Epic Title
+
+A brief description of this epic and its goals.
+
+## Stories
+
+### Story Title
+
+A brief description of this story.
+
+#### Acceptance Criteria
+
+- First acceptance criterion
+- Second acceptance criterion
+
+#### Mockups
+
+[Wireframe](https://example.com/wireframe)
+```
+
+---
+
+## Stories
+
+**Prefix:** `stories`
+
+### Attributes
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| status | enum(`created`, `in-progress`, `complete`) | optional | `"created"` | Current workflow state |
+| epic | string | optional | — | Slug of the parent epic |
+
+### Sections
+
+| Name | Heading | Alternatives | Description |
+|------|---------|--------------|-------------|
+| acceptanceCriteria | Acceptance Criteria | — | List of acceptance criteria as plain text strings |
+| mockups | Mockups | — | Map of mockup label to URL |
+
+### Relationships
+
+| Name | Type | Target |
+|------|------|--------|
+| epic | belongsTo | Epic |
+
+### Computed Properties
+
+- `isComplete`
+
+### Example
+
+```markdown
+---
+status: created
+epic: epic-slug
+---
+
+# Story Title
+
+A brief description of what this story accomplishes.
+
+## Acceptance Criteria
+
+- First acceptance criterion
+- Second acceptance criterion
+- Third acceptance criterion
+
+## Mockups
+
+[Main View](https://example.com/main-view)
+[Detail View](https://example.com/detail-view)
+```