contentbase 0.0.2 → 0.0.5

package/src/collection.ts

@@ -1,17 +1,110 @@
 import fs from "fs/promises";
 import path from "path";
 import matter from "gray-matter";
+import picomatch from "picomatch";
 import { Document } from "./document";
 import { CollectionQuery } from "./query/collection-query";
 import { createModelInstance } from "./model-instance";
 import { readDirectory } from "./utils/read-directory";
+import { pluralize } from "./utils/inflect";
+import { Base } from "./base-model";
 import type {
   ModelDefinition,
   CollectionItem,
   CollectionOptions,
   InferModelInstance,
+  HasManyDefinition,
+  RelationshipDefinition,
 } from "./types";
 
+// ─── Zod schema introspection ───
+
+export interface FieldInfo {
+  name: string;
+  type: string;
+  required: boolean;
+  defaultValue?: unknown;
+  description?: string;
+}
+
+function describeZodType(schema: any): { type: string; defaultValue?: unknown; optional: boolean; description?: string } {
+  const def = schema?._zod?.def;
+  if (!def) return { type: "unknown", optional: false };
+
+  const description = schema.description ?? def.description;
+
+  let optional = schema._zod.optout === "optional";
+  let defaultValue: unknown = undefined;
+
+  if (def.type === "default") {
+    defaultValue = def.defaultValue;
+    const inner = describeZodType(def.innerType);
+    return { type: inner.type, defaultValue, optional: true, description: description ?? inner.description };
+  }
+
+  if (def.type === "optional") {
+    const inner = describeZodType(def.innerType);
+    return { ...inner, optional: true, description: description ?? inner.description };
+  }
+
+  if (def.type === "nullable") {
+    const inner = describeZodType(def.innerType);
+    return { type: `${inner.type} | null`, optional: inner.optional, defaultValue: inner.defaultValue, description: description ?? inner.description };
+  }
+
+  if (def.type === "enum") {
+    const values = Object.keys(def.entries);
+    return { type: `enum(\`${values.join("`, `")}\`)`, optional, description };
+  }
+
+  if (def.type === "array") {
+    const element = describeZodType(def.element);
+    return { type: `${element.type}[]`, optional, description };
+  }
+
+  if (def.type === "record") {
+    const valType = describeZodType(def.valueType);
+    return { type: `record<string, ${valType.type}>`, optional, description };
+  }
+
+  if (def.type === "literal") {
+    return { type: `literal(${JSON.stringify(def.value)})`, optional, description };
+  }
+
+  if (def.type === "union") {
+    const options = (def.options as any[]).map((o: any) => describeZodType(o).type);
+    return { type: options.join(" | "), optional, description };
+  }
+
+  return { type: def.type ?? "unknown", optional, description };
+}
+
+export function introspectMetaSchema(schema: any): FieldInfo[] {
+  const shape = schema?._zod?.def?.shape;
+  if (!shape) return [];
+
+  return Object.entries(shape).map(([name, fieldSchema]) => {
+    const info = describeZodType(fieldSchema);
+    return {
+      name,
+      type: info.type,
+      required: !info.optional,
+      ...(info.defaultValue !== undefined && { defaultValue: info.defaultValue }),
+      ...(info.description && { description: info.description }),
+    };
+  });
+}
+
+function isModelDefinition(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as any).name === "string" &&
+    typeof (value as any).prefix === "string" &&
+    "meta" in (value as any)
+  );
+}
+
 export class Collection {
   readonly rootPath: string;
   readonly name: string;
@@ -23,11 +116,13 @@ export class Collection {
   #actions: Map<string, (collection: Collection, ...args: any[]) => any> =
     new Map();
   #loaded = false;
+  #autoDiscover: boolean;
 
   constructor(options: CollectionOptions) {
     this.rootPath = path.resolve(options.rootPath);
     this.name = options.name ?? options.rootPath;
     this.extensions = options.extensions ?? ["mdx", "md"];
+    this.#autoDiscover = options.autoDiscover ?? true;
   }
 
   // ─── Model registration ───
@@ -54,6 +149,29 @@ export class Collection {
     return Array.from(this.#models.values());
   }
 
+  // ─── Model auto-discovery ───
+
+  /**
+   * Discover and register model definitions from a
+   * models.{ts,js,mjs} file in the collection's root path.
+   */
+  async #discoverModels(): Promise<void> {
+    for (const ext of ["ts", "js", "mjs"]) {
+      const candidate = path.resolve(this.rootPath, `models.${ext}`);
+      try {
+        const mod = await import(candidate);
+        for (const value of Object.values(mod)) {
+          if (isModelDefinition(value) && !this.#models.has((value as any).name)) {
+            this.register(value as any);
+          }
+        }
+        return;
+      } catch {
+        continue;
+      }
+    }
+  }
+
   // ─── Loading ───
 
   get loaded(): boolean {
@@ -69,7 +187,28 @@ export class Collection {
   }
 
   get available(): string[] {
-    return Array.from(this.#items.keys());
+    return Array.from(this.#items.keys()).filter(
+      (id) => !this.#isExcludedByModel(id)
+    );
+  }
+
+  /**
+   * Check if a pathId is excluded by any model's exclude patterns.
+   * Patterns are matched against the full pathId using picomatch (globs) or RegExp.
+   */
+  #isExcludedByModel(pathId: string): boolean {
+    for (const def of this.modelDefinitions) {
+      if (!def.exclude || def.exclude.length === 0) continue;
+      if (!pathId.startsWith(def.prefix)) continue;
+      for (const pattern of def.exclude) {
+        if (pattern instanceof RegExp) {
+          if (pattern.test(pathId)) return true;
+        } else {
+          if (picomatch.isMatch(pathId, pattern)) return true;
+        }
+      }
+    }
+    return false;
   }
 
   /**
@@ -83,6 +222,16 @@ export class Collection {
       return this;
     }
 
+    // Auto-discover models if none have been manually registered
+    if (this.#models.size === 0 && this.#autoDiscover) {
+      await this.#discoverModels();
+    }
+
+    // Auto-register Base model as catch-all if not already registered
+    if (!this.#models.has("Base")) {
+      this.register(Base);
+    }
+
     if (this.#loaded && refresh) {
       this.#items.clear();
     }
@@ -96,6 +245,11 @@ export class Collection {
     await Promise.all(
       paths.map(async (filePath) => {
         const pathId = this.getPathId(filePath);
+
+        // Globally exclude templates directory — templates are only used
+        // for scaffolding and should never appear in queries or listings
+        if (pathId.startsWith("templates/") || pathId === "templates") return;
+
         const raw = await fs.readFile(filePath, "utf8");
         const stat = await fs.stat(filePath);
         const { data, content } = matter(raw);
@@ -107,12 +261,19 @@ export class Collection {
           path: filePath,
           createdAt: stat.ctime,
           updatedAt: stat.mtime,
+          size: stat.size,
         });
       })
     );
 
     // Refresh any already-created documents
     if (this.#loaded && refresh) {
+      // Evict documents that no longer exist on disk
+      for (const [pathId] of this.#documents) {
+        if (!this.#items.has(pathId)) {
+          this.#documents.delete(pathId);
+        }
+      }
       await Promise.all(
         Array.from(this.#documents.values()).map((doc) => doc.reload())
       );
@@ -135,6 +296,13 @@ export class Collection {
       );
     }
 
+    // Strip known extensions if provided (e.g. "some-doc.md" -> "some-doc")
+    const extensionPattern = new RegExp(
+      `\\.(${this.extensions.join("|")})$`,
+      "i"
+    );
+    pathId = pathId.replace(extensionPattern, "");
+
     let doc = this.#documents.get(pathId);
     if (doc) return doc;
 
@@ -198,13 +366,31 @@ export class Collection {
     const item = this.#items.get(pathId);
     if (!item) return undefined;
 
+    // 1. Explicit _model meta key takes priority
+    if (item.meta._model && typeof item.meta._model === "string") {
+      const explicit = this.#models.get(item.meta._model);
+      if (explicit) return explicit;
+    }
+
+    // 2. Check non-Base models by match/prefix
+    let baseModel: ModelDefinition<any, any, any, any, any> | undefined;
     for (const def of this.#models.values()) {
+      if (def.name === "Base") {
+        baseModel = def;
+        continue;
+      }
       if (def.match) {
         if (def.match({ id: pathId, meta: item.meta })) return def;
       } else {
         if (pathId.startsWith(def.prefix)) return def;
       }
     }
+
+    // 3. Fall back to Base model only for root-level documents (no subfolder)
+    if (baseModel && !pathId.includes("/")) {
+      return baseModel;
+    }
+
     return undefined;
   }
 
@@ -225,7 +411,13 @@ export class Collection {
     pathId: string,
     options: { content: string; extension?: string }
   ): Promise<CollectionItem> {
-    const extension = options.extension ?? ".mdx";
+    const extension = options.extension ?? ".md";
+    if (options.content == null) {
+      throw new Error(
+        `saveItem("${pathId}"): content must be a string, got ${typeof options.content}. ` +
+        `Use doc.save() or pass the full raw content including frontmatter.`
+      );
+    }
     const { data, content } = matter(options.content);
 
     if (!this.#items.has(pathId)) {
@@ -237,6 +429,7 @@ export class Collection {
         path: filePath,
         createdAt: new Date(),
         updatedAt: new Date(),
+        size: Buffer.byteLength(options.content, "utf8"),
       });
     }
 
@@ -251,6 +444,10 @@ export class Collection {
     item.content = content;
     item.meta = data;
     item.updatedAt = new Date();
+    item.size = Buffer.byteLength(options.content, "utf8");
+
+    // Invalidate cached Document so the next query rebuilds from fresh data
+    this.#documents.delete(pathId);
 
     return item;
   }
@@ -271,7 +468,7 @@ export class Collection {
 
   async readItem(
     pathId: string,
-    extension: string = "mdx"
+    extension: string = "md"
   ): Promise<CollectionItem> {
     let filePath: string;
 
@@ -292,6 +489,7 @@ export class Collection {
       path: filePath,
       createdAt: stat.ctime,
       updatedAt: stat.mtime,
+      size: stat.size,
     };
 
     this.#items.set(pathId, item);
@@ -412,8 +610,7 @@ export class Collection {
         const ids = grouped.get(def.name);
         if (!ids || ids.length === 0) continue;
 
-        const depth = options.title ? "##" : "#";
-        lines.push(`${depth} ${def.name}`, "");
+        lines.push(`## ${pluralize(def.name)}`, "");
         for (const id of ids) {
           lines.push(this.#tocEntry(id, basePath));
         }
@@ -421,8 +618,7 @@ export class Collection {
       }
 
       if (ungrouped.length > 0) {
-        const depth = options.title ? "##" : "#";
-        lines.push(`${depth} Other`, "");
+        lines.push(`## Other`, "");
         for (const id of ungrouped) {
           lines.push(this.#tocEntry(id, basePath));
         }
@@ -438,6 +634,69 @@ export class Collection {
     return lines.join("\n").trimEnd() + "\n";
   }
 
+  /**
+   * Renders an ASCII file tree of all documents in the collection.
+   *
+   * @example
+   * ```
+   * const tree = collection.renderFileTree();
+   * // epics/
+   * //   authentication.mdx
+   * //   searching-and-browsing.mdx
+   * // stories/
+   * //   authentication/
+   * //     a-user-should-be-able-to-register.mdx
+   * ```
+   */
+  renderFileTree(): string {
+    if (!this.#loaded) {
+      throw new Error(
+        "Collection has not been loaded. Call load() first."
+      );
+    }
+
+    const sorted = [...this.available].sort();
+
+    // Build a nested tree structure from pathIds
+    interface TreeNode {
+      children: Map<string, TreeNode>;
+    }
+    const root: TreeNode = { children: new Map() };
+
+    for (const pathId of sorted) {
+      const item = this.#items.get(pathId)!;
+      const ext = path.extname(item.path);
+      const fullPath = `${pathId}${ext}`;
+      const parts = fullPath.split("/");
+
+      let node = root;
+      for (const part of parts) {
+        if (!node.children.has(part)) {
+          node.children.set(part, { children: new Map() });
+        }
+        node = node.children.get(part)!;
+      }
+    }
+
+    // Render the tree with indentation and connector lines
+    const lines: string[] = [];
+
+    const render = (node: TreeNode, prefix: string) => {
+      const entries = [...node.children.entries()];
+      entries.forEach(([name, child], i) => {
+        const isLast = i === entries.length - 1;
+        const connector = isLast ? "└── " : "├── ";
+        const isDir = child.children.size > 0;
+        lines.push(`${prefix}${connector}${name}${isDir ? "/" : ""}`);
+        const nextPrefix = prefix + (isLast ? "    " : "│   ");
+        render(child, nextPrefix);
+      });
+    };
+
+    render(root, "");
+    return lines.join("\n") + "\n";
+  }
+
   #tocEntry(pathId: string, basePath: string): string {
     const item = this.#items.get(pathId)!;
     const ext = path.extname(item.path);
@@ -446,20 +705,112 @@ export class Collection {
     return `- [${doc.title}](${relativePath})`;
   }
 
+  // ─── Model Summary ───
+
+  /**
+   * Generate a plain-text summary of the collection and its models.
+   * Returns the same output as `cnotes inspect`.
+   */
+  generateModelSummary(): string {
+    if (!this.#loaded) {
+      throw new Error("Collection has not been loaded. Call load() first.");
+    }
+
+    const lines: string[] = [];
+
+    lines.push(`Collection: ${this.name}`);
+    lines.push(`Root: ${this.rootPath}`);
+    lines.push(`Items: ${this.available.length}`);
+    lines.push("");
+
+    for (const def of this.modelDefinitions) {
+      const matchingItems = this.available.filter(
+        (id) => this.findModelDefinition(id)?.name === def.name
+      );
+      lines.push(`  Model: ${def.name}`);
+      lines.push(`    Prefix: ${def.prefix}`);
+      const fields = introspectMetaSchema(def.meta);
+      lines.push(
+        `    Meta: ${fields.length > 0 ? fields.map((f) => `${f.name}(${f.type})`).join(", ") : "(none)"}`
+      );
+      lines.push(
+        `    Sections: ${Object.keys(def.sections).join(", ") || "(none)"}`
+      );
+      lines.push(
+        `    Relationships: ${Object.keys(def.relationships).join(", ") || "(none)"}`
+      );
+      lines.push(`    Documents: ${matchingItems.length}`);
+      if (matchingItems.length > 0) {
+        lines.push(`    IDs: ${matchingItems.join(", ")}`);
+      }
+      lines.push("");
+    }
+
+    if (this.availableActions.length > 0) {
+      lines.push(`Actions: ${this.availableActions.join(", ")}`);
+    }
+
+    return lines.join("\n").trimEnd();
+  }
+
+  /**
+   * Write README.md to the collection root.
+   * Preserves the `## Overview` section if it already exists.
+   * The generated summary is placed in the `## Summary` section.
+   */
+  async saveModelSummary(): Promise<string> {
+    const summary = this.generateModelSummary();
+    const modelsPath = path.join(this.rootPath, "README.md");
+
+    // Preserve existing Overview section content
+    let overview = "";
+    try {
+      const existing = await fs.readFile(modelsPath, "utf8");
+      const overviewStart = existing.indexOf("## Overview");
+      if (overviewStart !== -1) {
+        const contentStart = existing.indexOf("\n", overviewStart) + 1;
+        const nextHeading = existing.indexOf("\n## ", contentStart);
+        const contentEnd = nextHeading !== -1 ? nextHeading : existing.length;
+        overview = existing.slice(contentStart, contentEnd).trim();
+      }
+    } catch {
+      // No existing file
+    }
+
+    const lines: string[] = [
+      "# Models",
+      "",
+      "## Overview",
+      "",
+      overview || "",
+      "",
+      "## Summary",
+      "",
+      "```",
+      summary,
+      "```",
+      "",
+    ];
+
+    const markdown = lines.join("\n");
+    await fs.writeFile(modelsPath, markdown, "utf8");
+    return summary;
+  }
+
   // ─── Serialization ───
 
   toJSON(options: { content?: boolean } = {}): Record<string, unknown> {
     const models = this.modelDefinitions.map((def) => ({
       name: def.name,
       prefix: def.prefix,
-      matchingPaths: this.available.filter((id) =>
-        id.startsWith(def.prefix)
+      matchingPaths: this.available.filter(
+        (id) => this.findModelDefinition(id)?.name === def.name
       ),
     }));
 
     const result: Record<string, unknown> = {
       models,
-      itemIds: Array.from(this.#items.keys()),
+      itemIds: this.available,
     };
 
     if (options.content) {

package/src/define-model.ts

@@ -17,12 +17,21 @@ export interface DefineModelConfig<
   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;
 }
 
 /**
@@ -65,16 +74,104 @@ export function defineModel<
   > = {} as any
 ): ModelDefinition<TName, TMeta, TSections, TRelationships, TComputed> {
   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];
 }