contentbase 0.0.1

package/src/utils/normalize-headings.ts

@@ -0,0 +1,31 @@
+import type { Root, Heading } from "mdast";
+
+/**
+ * Normalize heading depths so the minimum heading is depth 1.
+ * If the shallowest heading is h2, all headings are shifted up by 1.
+ * Mutates the AST in place and returns it.
+ */
+export function normalizeHeadings(ast: Root): Root {
+  const headings = ast.children.filter(
+    (n): n is Heading => n.type === "heading"
+  );
+
+  if (headings.length === 0) return ast;
+
+  const minDepth = Math.min(...headings.map((h) => h.depth));
+  const diff = 1 - minDepth;
+
+  if (diff !== 0) {
+    for (const heading of headings) {
+      heading.depth = Math.max(1, Math.min(6, heading.depth + diff)) as
+        | 1
+        | 2
+        | 3
+        | 4
+        | 5
+        | 6;
+    }
+  }
+
+  return ast;
+}

package/src/utils/parse-table.ts

@@ -0,0 +1,30 @@
+import { toString } from "mdast-util-to-string";
+import type { Content } from "mdast";
+
+/**
+ * Parse a markdown table AST node into an array of row objects.
+ * Each row is an object whose keys are the column header texts.
+ */
+export function parseTable(
+  tableNode: Content
+): Record<string, string>[] {
+  const rows = (tableNode as any).children?.filter(
+    (n: any) => n.type === "tableRow"
+  );
+
+  if (!rows || rows.length < 2) return [];
+
+  const [headingsRow, ...dataRows] = rows;
+  const headings: string[] = headingsRow.children.map((c: any) =>
+    toString(c)
+  );
+
+  return dataRows.map((row: any) =>
+    Object.fromEntries(
+      row.children.map((cell: any, index: number) => [
+        headings[index] ?? `col${index}`,
+        toString(cell),
+      ])
+    )
+  );
+}

package/src/utils/read-directory.ts

@@ -0,0 +1,35 @@
+import fs from "fs/promises";
+import path from "path";
+
+/**
+ * Recursively read a directory and return file paths matching a regex.
+ */
+export async function readDirectory(
+  dirPath: string,
+  match: RegExp = /\.mdx?$/i,
+  recursive: boolean = true
+): Promise<string[]> {
+  let paths: string[] = [];
+
+  let entries: string[];
+  try {
+    entries = await fs.readdir(dirPath);
+  } catch {
+    return paths;
+  }
+
+  for (const entry of entries) {
+    if (entry.startsWith(".")) continue;
+
+    const filePath = path.join(dirPath, entry);
+    const stat = await fs.stat(filePath);
+
+    if (stat.isDirectory() && recursive) {
+      paths = paths.concat(await readDirectory(filePath, match, recursive));
+    } else if (stat.isFile() && match.test(filePath)) {
+      paths.push(filePath);
+    }
+  }
+
+  return paths;
+}

package/src/utils/stringify-ast.ts

@@ -0,0 +1,9 @@
+import { toMarkdown } from "mdast-util-to-markdown";
+import type { Root } from "mdast";
+
+/**
+ * Convert an MDAST tree back to a markdown string.
+ */
+export function stringifyAst(ast: Root): string {
+  return toMarkdown(ast);
+}

package/src/validator.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import type {
+  ModelDefinition,
+  SectionDefinition,
+  ValidationResult,
+} from "./types";
+import type { Document } from "./document";
+
+/**
+ * Standalone validator that checks a document against a model definition's
+ * Zod schemas (both meta and section schemas).
+ *
+ * Can be used directly for validation without creating a full model instance.
+ */
+export function validateDocument(
+  document: Document,
+  definition: ModelDefinition
+): ValidationResult {
+  const errors: z.ZodIssue[] = [];
+
+  // Validate meta
+  const rawMeta = { ...(definition.defaults ?? {}), ...document.meta };
+  const metaResult = definition.meta.safeParse(rawMeta);
+  if (!metaResult.success) {
+    errors.push(...metaResult.error.issues);
+  }
+
+  // Validate sections
+  if (definition.sections) {
+    for (const [key, sd] of Object.entries(definition.sections)) {
+      const sectionDef = sd as SectionDefinition<unknown>;
+      if (sectionDef.schema) {
+        const sectionQuery = document.querySection(sectionDef.heading);
+        const sectionData = sectionDef.extract(sectionQuery);
+        const sResult = sectionDef.schema.safeParse(sectionData);
+        if (!sResult.success) {
+          for (const issue of sResult.error.issues) {
+            errors.push({
+              ...issue,
+              path: ["sections", key, ...issue.path],
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/test/ast-query.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { AstQuery } from "../src/ast-query";
+import { Collection } from "../src/collection";
+import { createTestCollection } from "./helpers";
+import type { Heading } from "mdast";
+
+describe("AstQuery", () => {
+  let collection: Collection;
+  let query: AstQuery;
+
+  beforeEach(async () => {
+    collection = await createTestCollection();
+    const doc = collection.document("epics/authentication");
+    query = doc.astQuery;
+  });
+
+  it("select returns first matching node", () => {
+    const heading = query.select("heading");
+    expect(heading).toBeDefined();
+    expect(heading!.type).toBe("heading");
+  });
+
+  it("selectAll returns all matching nodes", () => {
+    const headings = query.selectAll("heading");
+    expect(headings.length).toBeGreaterThan(1);
+  });
+
+  it("selectAll with attribute filter", () => {
+    const h2s = query.selectAll('heading[depth="2"]');
+    expect(h2s.length).toBeGreaterThanOrEqual(1);
+    for (const h of h2s) {
+      expect((h as Heading).depth).toBe(2);
+    }
+  });
+
+  it("visit walks all nodes", () => {
+    let count = 0;
+    query.visit(() => {
+      count++;
+    });
+    expect(count).toBeGreaterThan(0);
+  });
+
+  it("findBefore finds preceding node", () => {
+    const headings = query.selectAll("heading");
+    if (headings.length >= 2) {
+      const before = query.findBefore(headings[1]);
+      expect(before).toBeDefined();
+    }
+  });
+
+  it("findAfter finds following node", () => {
+    const heading = query.select("heading")!;
+    const after = query.findAfter(heading);
+    expect(after).toBeDefined();
+  });
+
+  it("findAllAfter returns all following nodes", () => {
+    const heading = query.select("heading")!;
+    const after = query.findAllAfter(heading);
+    expect(after.length).toBeGreaterThan(0);
+  });
+
+  it("findBetween returns nodes between two markers", () => {
+    const headings = query.selectAll("heading");
+    if (headings.length >= 2) {
+      const between = query.findBetween(headings[0], headings[1]);
+      expect(between).toBeDefined();
+    }
+  });
+
+  it("headingsAtDepth returns correct headings (bug fix)", () => {
+    const h1s = query.headingsAtDepth(1);
+    expect(h1s.length).toBe(1);
+    expect(h1s[0].depth).toBe(1);
+
+    const h3s = query.headingsAtDepth(3);
+    expect(h3s.length).toBeGreaterThanOrEqual(2);
+    for (const h of h3s) {
+      expect(h.depth).toBe(3);
+    }
+  });
+
+  it("findHeadingByText finds exact match (case insensitive)", () => {
+    const heading = query.findHeadingByText("stories");
+    expect(heading).toBeDefined();
+    expect(heading!.depth).toBe(2);
+  });
+
+  it("findHeadingByText with substring matching", () => {
+    const heading = query.findHeadingByText("register", false);
+    expect(heading).toBeDefined();
+  });
+
+  it("findAllHeadingsByText returns multiple matches", () => {
+    const headings = query.findAllHeadingsByText("Acceptance Criteria");
+    expect(headings.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("findNextSiblingHeadingTo finds same-depth sibling", () => {
+    const h3s = query.headingsAtDepth(3);
+    if (h3s.length >= 2) {
+      const next = query.findNextSiblingHeadingTo(h3s[0]);
+      expect(next).toBeDefined();
+      expect(next!.depth).toBe(3);
+    }
+  });
+
+  it("findNextSiblingHeadingTo returns undefined at end", () => {
+    const h3s = query.headingsAtDepth(3);
+    const last = h3s[h3s.length - 1];
+    const next = query.findNextSiblingHeadingTo(last);
+    expect(next).toBeUndefined();
+  });
+
+  it("atLine returns node at specific line", () => {
+    const first = query.ast.children[0];
+    if (first.position) {
+      const found = query.atLine(first.position.start.line);
+      expect(found).toBeDefined();
+    }
+  });
+
+  it("atLine returns undefined for non-existent line", () => {
+    const found = query.atLine(99999);
+    expect(found).toBeUndefined();
+  });
+});

package/test/collection.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { Collection } from "../src/collection";
+import { createTestCollection, FIXTURES_PATH } from "./helpers";
+import { Epic, Story } from "./fixtures/sdlc/models";
+
+describe("Collection", () => {
+  let collection: Collection;
+
+  beforeEach(async () => {
+    collection = await createTestCollection();
+  });
+
+  it("loads all mdx files from rootPath", () => {
+    expect(collection.loaded).toBe(true);
+    expect(collection.available.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it("returns correct path IDs", () => {
+    expect(collection.available).toContain("epics/authentication");
+    expect(collection.available).toContain("epics/searching-and-browsing");
+    expect(collection.available).toContain(
+      "stories/authentication/a-user-should-be-able-to-register"
+    );
+  });
+
+  it("lazily creates documents", () => {
+    const doc = collection.document("epics/authentication");
+    expect(doc).toBeDefined();
+    expect(doc.id).toBe("epics/authentication");
+  });
+
+  it("caches documents", () => {
+    const doc1 = collection.document("epics/authentication");
+    const doc2 = collection.document("epics/authentication");
+    expect(doc1).toBe(doc2);
+  });
+
+  it("throws if not loaded", () => {
+    const fresh = new Collection({ rootPath: FIXTURES_PATH });
+    expect(() => fresh.document("epics/authentication")).toThrow(
+      "Collection has not been loaded"
+    );
+  });
+
+  it("throws for unknown pathId", () => {
+    expect(() => collection.document("nonexistent")).toThrow(
+      'Could not find document "nonexistent"'
+    );
+  });
+
+  it("registers model definitions", () => {
+    expect(collection.getModelDefinition("Epic")).toBeDefined();
+    expect(collection.getModelDefinition("Story")).toBeDefined();
+    expect(collection.modelDefinitions.length).toBe(2);
+  });
+
+  it("finds model definition by pathId prefix", () => {
+    const def = collection.findModelDefinition("epics/authentication");
+    expect(def?.name).toBe("Epic");
+  });
+
+  it("gets typed model instances", () => {
+    const epic = collection.getModel("epics/authentication", Epic);
+    expect(epic.id).toBe("epics/authentication");
+    expect(epic.title).toBe("Authentication");
+    expect(epic.meta.status).toBe("created");
+  });
+
+  it("creates typed queries", async () => {
+    const epics = await collection.query(Epic).fetchAll();
+    expect(epics.length).toBe(2);
+    expect(epics[0].meta.status).toBeDefined();
+  });
+
+  it("serializes to JSON", () => {
+    const json = collection.toJSON();
+    expect(json.models).toBeDefined();
+    expect(json.itemIds).toBeDefined();
+  });
+
+  it("supports actions", async () => {
+    let called = false;
+    collection.action("test-action", () => {
+      called = true;
+    });
+    expect(collection.availableActions).toContain("test-action");
+    await collection.runAction("test-action");
+    expect(called).toBe(true);
+  });
+
+  it("supports plugins", () => {
+    let pluginCalled = false;
+    collection.use((coll) => {
+      pluginCalled = true;
+      expect(coll).toBe(collection);
+    });
+    expect(pluginCalled).toBe(true);
+  });
+});

package/test/define-model.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import { defineModel, z, section, hasMany, belongsTo } from "../src/index";
+
+describe("defineModel", () => {
+  it("creates a ModelDefinition with the given name", () => {
+    const MyModel = defineModel("MyModel");
+    expect(MyModel.name).toBe("MyModel");
+  });
+
+  it("auto-pluralizes the prefix from the name", () => {
+    const Epic = defineModel("Epic");
+    expect(Epic.prefix).toBe("epics");
+  });
+
+  it("uses custom prefix when provided", () => {
+    const MyModel = defineModel("MyModel", { prefix: "custom" });
+    expect(MyModel.prefix).toBe("custom");
+  });
+
+  it("stores the meta Zod schema", () => {
+    const schema = z.object({ status: z.string() });
+    const MyModel = defineModel("MyModel", { meta: schema });
+    expect(MyModel.meta).toBe(schema);
+    expect(MyModel.schema).toBe(schema);
+  });
+
+  it("creates passthrough schema when meta is omitted", () => {
+    const MyModel = defineModel("MyModel");
+    const result = MyModel.meta.safeParse({ anything: "goes" });
+    expect(result.success).toBe(true);
+  });
+
+  it("stores sections", () => {
+    const MyModel = defineModel("MyModel", {
+      sections: {
+        items: section("Items", {
+          extract: (q) => q.selectAll("listItem"),
+        }),
+      },
+    });
+    expect(MyModel.sections.items.heading).toBe("Items");
+  });
+
+  it("stores relationships", () => {
+    const Target = defineModel("Target");
+    const MyModel = defineModel("MyModel", {
+      relationships: {
+        targets: hasMany(() => Target, { heading: "Targets" }),
+      },
+    });
+    expect(MyModel.relationships.targets.type).toBe("hasMany");
+    expect(MyModel.relationships.targets.heading).toBe("Targets");
+  });
+
+  it("stores computed properties", () => {
+    const MyModel = defineModel("MyModel", {
+      computed: {
+        foo: () => 42,
+      },
+    });
+    expect(MyModel.computed.foo).toBeDefined();
+    expect(MyModel.computed.foo({})).toBe(42);
+  });
+
+  it("stores match function", () => {
+    const fn = (doc: any) => doc.id.startsWith("special");
+    const MyModel = defineModel("MyModel", { match: fn });
+    expect(MyModel.match).toBe(fn);
+  });
+
+  it("stores defaults", () => {
+    const MyModel = defineModel("MyModel", {
+      meta: z.object({ status: z.string().default("draft") }),
+      defaults: { status: "draft" },
+    });
+    expect(MyModel.defaults).toEqual({ status: "draft" });
+  });
+});

package/test/document.test.ts

@@ -0,0 +1,225 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { Collection } from "../src/collection";
+import { createTestCollection } from "./helpers";
+import { toString } from "mdast-util-to-string";
+
+describe("Document", () => {
+  let collection: Collection;
+
+  beforeEach(async () => {
+    collection = await createTestCollection();
+  });
+
+  it("lazily parses AST", () => {
+    const doc = collection.document("epics/authentication");
+    // Content should exist but AST is not parsed yet
+    expect(doc.content).toBeDefined();
+    // Accessing ast triggers parsing
+    expect(doc.ast.type).toBe("root");
+    expect(doc.ast.children.length).toBeGreaterThan(0);
+  });
+
+  it("extracts title from first heading", () => {
+    const doc = collection.document("epics/authentication");
+    expect(doc.title).toBe("Authentication");
+  });
+
+  it("falls back to id if no heading", () => {
+    const doc = collection.createDocument({
+      id: "test/no-heading",
+      content: "Just some text without a heading.",
+    });
+    expect(doc.title).toBe("test/no-heading");
+  });
+
+  it("generates slug from title", () => {
+    const doc = collection.document("epics/authentication");
+    expect(doc.slug).toBe("authentication");
+  });
+
+  it("exposes parsed frontmatter as meta", () => {
+    const doc = collection.document("epics/authentication");
+    expect(doc.meta.priority).toBe("high");
+    expect(doc.meta.status).toBe("created");
+  });
+
+  it("serializes rawContent with frontmatter", () => {
+    const doc = collection.document("epics/authentication");
+    expect(doc.rawContent).toContain("---");
+    expect(doc.rawContent).toContain("priority: high");
+    expect(doc.rawContent).toContain("# Authentication");
+  });
+
+  it("omits frontmatter block if meta is empty", () => {
+    const doc = collection.createDocument({
+      id: "test/no-meta",
+      content: "# Hello\n",
+    });
+    expect(doc.rawContent).not.toContain("---");
+  });
+
+  it("provides astQuery", () => {
+    const doc = collection.document("epics/authentication");
+    expect(doc.astQuery.select("heading")).toBeDefined();
+  });
+
+  it("provides nodes shortcuts", () => {
+    const doc = collection.document("epics/authentication");
+    expect(doc.nodes.headings.length).toBeGreaterThan(0);
+    expect(doc.nodes.firstHeading).toBeDefined();
+  });
+
+  describe("extractSection", () => {
+    it("extracts section by heading text", () => {
+      const doc = collection.document("epics/authentication");
+      const section = doc.extractSection("Stories");
+      expect(section.length).toBeGreaterThan(1);
+      expect(toString(section[0])).toBe("Stories");
+    });
+
+    it("throws for non-existent heading", () => {
+      const doc = collection.document("epics/authentication");
+      expect(() => doc.extractSection("Nonexistent")).toThrow(
+        "Heading not found"
+      );
+    });
+  });
+
+  describe("querySection", () => {
+    it("returns scoped AstQuery without the heading", () => {
+      const doc = collection.document("epics/authentication");
+      const query = doc.querySection("Stories");
+      const headings = query.selectAll("heading");
+      // Should have the story sub-headings but not "Stories" itself
+      expect(headings.length).toBeGreaterThan(0);
+    });
+
+    it("returns empty query for non-existent heading", () => {
+      const doc = collection.document("epics/authentication");
+      const query = doc.querySection("Nonexistent");
+      expect(query.selectAll("heading").length).toBe(0);
+    });
+  });
+
+  describe("immutable section mutations", () => {
+    it("removeSection returns new Document", () => {
+      const doc = collection.document("epics/authentication");
+      const originalContent = doc.content;
+      const newDoc = doc.removeSection("Stories");
+      expect(newDoc).not.toBe(doc);
+      expect(doc.content).toBe(originalContent);
+      expect(newDoc.content).not.toContain("A User should be able to register");
+    });
+
+    it("replaceSectionContent returns new Document", () => {
+      const doc = collection.document("epics/authentication");
+      const newDoc = doc.replaceSectionContent(
+        "Stories",
+        "New stories content here."
+      );
+      expect(newDoc).not.toBe(doc);
+      expect(newDoc.content).toContain("New stories content here");
+    });
+
+    it("insertBefore returns new Document", () => {
+      const doc = collection.document("epics/authentication");
+      const heading = doc.astQuery.findHeadingByText("Stories");
+      expect(heading).toBeDefined();
+      const newDoc = doc.insertBefore(heading!, "Inserted before.");
+      expect(newDoc).not.toBe(doc);
+      expect(newDoc.content).toContain("Inserted before");
+    });
+
+    it("insertAfter returns new Document", () => {
+      const doc = collection.document("epics/authentication");
+      const heading = doc.astQuery.findHeadingByText("Stories");
+      expect(heading).toBeDefined();
+      const newDoc = doc.insertAfter(heading!, "Inserted after.");
+      expect(newDoc).not.toBe(doc);
+      expect(newDoc.content).toContain("Inserted after");
+    });
+
+    it("appendToSection returns new Document", () => {
+      const doc = collection.document("epics/authentication");
+      const newDoc = doc.appendToSection(
+        "Stories",
+        "### New Story\n\nAppended story."
+      );
+      expect(newDoc).not.toBe(doc);
+      expect(newDoc.content).toContain("New Story");
+    });
+  });
+
+  describe("mutable mutations", () => {
+    it("removeSection with mutate modifies in place", () => {
+      const doc = collection.createDocument({
+        id: "test/mutable",
+        content:
+          "# Test\n\n## Section A\n\nContent A\n\n## Section B\n\nContent B\n",
+      });
+      const result = doc.removeSection("Section A", { mutate: true });
+      expect(result).toBe(doc);
+      expect(doc.content).not.toContain("Content A");
+      expect(doc.content).toContain("Content B");
+    });
+  });
+
+  it("replaceContent returns new Document", () => {
+    const doc = collection.document("epics/authentication");
+    const newDoc = doc.replaceContent("# Completely new content");
+    expect(newDoc).not.toBe(doc);
+    expect(newDoc.content).toBe("# Completely new content");
+  });
+
+  it("appendContent returns new Document", () => {
+    const doc = collection.createDocument({
+      id: "test/append",
+      content: "# Start\n",
+    });
+    const newDoc = doc.appendContent("\n## Added\n");
+    expect(newDoc).not.toBe(doc);
+    expect(newDoc.content).toContain("Added");
+  });
+
+  it("toJSON serializes document", () => {
+    const doc = collection.document("epics/authentication");
+    const json = doc.toJSON();
+    expect(json.id).toBe("epics/authentication");
+    expect(json.meta).toBeDefined();
+    expect(json.content).toBeDefined();
+    expect(json.ast).toBeDefined();
+  });
+
+  it("toText extracts plain text", () => {
+    const doc = collection.document("epics/authentication");
+    const text = doc.toText();
+    expect(text).toContain("Authentication");
+  });
+
+  describe("toOutline", () => {
+    it("returns indented heading outline", () => {
+      const doc = collection.document("epics/authentication");
+      const outline = doc.toOutline();
+      expect(outline).toBe(
+        [
+          "- Authentication",
+          "  - Stories",
+          "    - A User should be able to register.",
+          "      - Acceptance Criteria",
+          "      - Mockups",
+          "    - A User should be able to login.",
+          "      - Acceptance Criteria",
+          "      - Mockups",
+        ].join("\n")
+      );
+    });
+
+    it("returns empty string for document with no headings", () => {
+      const doc = collection.createDocument({
+        id: "test/no-headings",
+        content: "Just some text without any headings.",
+      });
+      expect(doc.toOutline()).toBe("");
+    });
+  });
+});