contentbase 0.0.1

package/test/fixtures/sdlc/epics/authentication.mdx

@@ -0,0 +1,42 @@
+---
+priority: high
+status: created
+---
+
+# Authentication
+
+The Authentication stories cover users logging in and out of the application, as well as the roles and permissions granted to these users and how they are enforced in the application.
+
+## Stories
+
+### A User should be able to register.
+
+As a User I would like to register so that I can use the application.
+
+#### Acceptance Criteria
+
+- A user can visit the signup form, supply their name, email, and password
+- The signup form should validate the user's information and supply errors
+- The user should receive a confirmation email
+- The user should show up in our database as confirmed after clicking the confirmation link
+
+#### Mockups
+
+- [Invision: Registration Form](https://invisionapp.com)
+- [Invision: Registration Form Error State](https://invisionapp.com)
+
+### A User should be able to login.
+
+As a User I would like to login so that I can use the application.
+
+#### Acceptance Criteria
+
+- A user can visit the signup form, supply their name, email, and password
+- The signup form should validate the user's information and supply errors
+- The user should receive a confirmation email
+- The user should show up in our database as confirmed after clicking the confirmation link
+
+#### Mockups
+
+- [Invision: Login Form](https://invisionapp.com)
+- [Invision: Login Form Error State ](https://invisionapp.com)

package/test/fixtures/sdlc/epics/searching-and-browsing.mdx

@@ -0,0 +1,21 @@
+---
+status: created
+---
+
+# Searching And Browsing
+
+This epic covers the stories related to searching for a specific item.
+
+## Stories
+
+### Searching for a product by category
+
+As a user I want to be able to search for a product by category so that I can find the right product for me.
+
+### Searching for a product by manufacturer
+
+As a user I want to be able to search for a product by manufacturer so that I can find the right product for me.
+
+### Searching for a product by name
+
+As a user I want to be able to search for a product by name so that I can find the right product for me.

package/test/fixtures/sdlc/models.ts

@@ -0,0 +1,89 @@
+import {
+  defineModel,
+  section,
+  hasMany,
+  belongsTo,
+  z,
+  type ModelDefinition,
+  type HasManyDefinition,
+  type BelongsToDefinition,
+  type SectionDefinition,
+} from "../../../src/index";
+import { toString } from "mdast-util-to-string";
+
+const epicMeta = z.object({
+  priority: z.enum(["low", "medium", "high"]).optional(),
+  status: z
+    .enum(["created", "in-progress", "complete"])
+    .default("created"),
+});
+
+const storyMeta = z.object({
+  status: z
+    .enum(["created", "in-progress", "complete"])
+    .default("created"),
+  epic: z.string().optional(),
+});
+
+/** Explicit type for Epic so circular Epic↔Story inference doesn’t collapse to never */
+export type EpicDef = ModelDefinition<
+  "Epic",
+  typeof epicMeta,
+  Record<string, never>,
+  { stories: HasManyDefinition<StoryDef> },
+  { isComplete: (self: any) => boolean }
+>;
+
+/** Explicit type for Story so circular Epic↔Story inference doesn’t collapse to never */
+export type StoryDef = ModelDefinition<
+  "Story",
+  typeof storyMeta,
+  Record<string, SectionDefinition<any>>,
+  { epic: BelongsToDefinition<EpicDef> },
+  { isComplete: (self: any) => boolean }
+>;
+
+export const Epic: EpicDef = defineModel("Epic", {
+  prefix: "epics",
+  meta: epicMeta,
+  relationships: {
+    stories: hasMany(() => Story, {
+      heading: "Stories",
+    }),
+  },
+  computed: {
+    isComplete: (self: any) => self.meta.status === "complete",
+  },
+  defaults: {
+    status: "created",
+  },
+});
+
+export const Story: StoryDef = defineModel("Story", {
+  prefix: "stories",
+  meta: storyMeta,
+  sections: {
+    acceptanceCriteria: section("Acceptance Criteria", {
+      extract: (query) =>
+        query.selectAll("listItem").map((n) => toString(n)),
+      schema: z.array(z.string()),
+    }),
+    mockups: section("Mockups", {
+      extract: (query) =>
+        Object.fromEntries(
+          query
+            .selectAll("link")
+            .map((l: any) => [toString(l), l.url])
+        ),
+      schema: z.record(z.string(), z.string()),
+    }),
+  },
+  relationships: {
+    epic: belongsTo(() => Epic, {
+      foreignKey: (doc) => doc.meta.epic as string,
+    }),
+  },
+  computed: {
+    isComplete: (self: any) => self.meta.status === "complete",
+  },
+});

package/test/fixtures/sdlc/stories/authentication/a-user-should-be-able-to-register.mdx

@@ -0,0 +1,20 @@
+---
+status: created
+epic: authentication
+---
+
+# A User should be able to register.
+
+As a User I would like to register so that I can use the application.
+
+## Acceptance Criteria
+
+- A user can visit the signup form, supply their name, email, and password
+- The signup form should validate the user's information and supply errors
+- The user should receive a confirmation email
+- The user should show up in our database as confirmed after clicking the confirmation link
+
+## Mockups
+
+- [Invision: Registration Form](https://invisionapp.com)
+- [Invision: Registration Form Error State](https://invisionapp.com)

package/test/helpers.ts

@@ -0,0 +1,21 @@
+import path from "path";
+import { Collection } from "../src/collection";
+import { Epic, Story } from "./fixtures/sdlc/models";
+
+const dir = import.meta.dirname ?? new URL(".", import.meta.url).pathname;
+
+export const FIXTURES_PATH = path.resolve(
+  dir,
+  "fixtures/sdlc"
+);
+
+export async function createTestCollection(): Promise<Collection> {
+  const collection = new Collection({
+    rootPath: FIXTURES_PATH,
+    name: "test-sdlc",
+  });
+  collection.register(Epic);
+  collection.register(Story);
+  await collection.load();
+  return collection;
+}

package/test/model-instance.test.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { Collection } from "../src/collection";
+import { createModelInstance } from "../src/model-instance";
+import { createTestCollection } from "./helpers";
+import { Epic, Story } from "./fixtures/sdlc/models";
+
+describe("createModelInstance", () => {
+  let collection: Collection;
+
+  beforeEach(async () => {
+    collection = await createTestCollection();
+  });
+
+  describe("core properties", () => {
+    it("has correct id", () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      expect(instance.id).toBe("epics/authentication");
+    });
+
+    it("has correct title", () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      expect(instance.title).toBe("Authentication");
+    });
+
+    it("has correct slug", () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      expect(instance.slug).toBe("authentication");
+    });
+
+    it("references the original document", () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      expect(instance.document).toBe(doc);
+    });
+
+    it("references the collection", () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      expect(instance.collection).toBe(collection);
+    });
+  });
+
+  describe("meta", () => {
+    it("returns Zod-parsed frontmatter", () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      expect(instance.meta.priority).toBe("high");
+      expect(instance.meta.status).toBe("created");
+    });
+
+    it("applies defaults where fields are missing", () => {
+      const doc = collection.document("epics/searching-and-browsing");
+      const instance = createModelInstance(doc, Epic, collection);
+      expect(instance.meta.status).toBe("created");
+    });
+  });
+
+  describe("sections", () => {
+    it("lazily extracts section data", () => {
+      const doc = collection.document(
+        "stories/authentication/a-user-should-be-able-to-register"
+      );
+      const instance = createModelInstance(doc, Story, collection);
+      const criteria = instance.sections.acceptanceCriteria;
+      expect(Array.isArray(criteria)).toBe(true);
+      expect(criteria.length).toBe(4);
+    });
+
+    it("extracts mockups as record", () => {
+      const doc = collection.document(
+        "stories/authentication/a-user-should-be-able-to-register"
+      );
+      const instance = createModelInstance(doc, Story, collection);
+      const mockups = instance.sections.mockups;
+      expect(typeof mockups).toBe("object");
+      expect(Object.keys(mockups).length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("computed", () => {
+    it("evaluates computed properties", () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      expect(instance.computed.isComplete).toBe(false);
+    });
+  });
+
+  describe("relationships", () => {
+    it("hasMany fetchAll returns related instances", () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      const stories = instance.relationships.stories.fetchAll();
+      expect(stories.length).toBe(2);
+      expect(stories[0].title).toBeDefined();
+    });
+
+    it("hasMany first returns first child", () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      const first = instance.relationships.stories.first();
+      expect(first).toBeDefined();
+      expect(first!.title).toContain("register");
+    });
+
+    it("hasMany last returns last child", () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      const last = instance.relationships.stories.last();
+      expect(last).toBeDefined();
+      expect(last!.title).toContain("login");
+    });
+
+    it("belongsTo fetch returns parent", () => {
+      const doc = collection.document(
+        "stories/authentication/a-user-should-be-able-to-register"
+      );
+      const instance = createModelInstance(doc, Story, collection);
+      const epic = instance.relationships.epic.fetch();
+      expect(epic.title).toBe("Authentication");
+    });
+  });
+
+  describe("validation", () => {
+    it("returns valid for good data", async () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      const result = await instance.validate();
+      expect(result.valid).toBe(true);
+      expect(result.errors.length).toBe(0);
+    });
+
+    it("returns errors for bad meta", async () => {
+      const doc = collection.createDocument({
+        id: "test/bad",
+        content: "# Bad Doc\n",
+        meta: { status: "INVALID_STATUS" },
+      });
+      const instance = createModelInstance(doc, Epic, collection);
+      const result = await instance.validate();
+      expect(result.valid).toBe(false);
+      expect(result.errors.length).toBeGreaterThan(0);
+    });
+
+    it("populates errors map", async () => {
+      const doc = collection.createDocument({
+        id: "test/bad",
+        content: "# Bad Doc\n",
+        meta: { status: "INVALID_STATUS" },
+      });
+      const instance = createModelInstance(doc, Epic, collection);
+      await instance.validate();
+      expect(instance.hasErrors).toBe(true);
+      expect(instance.errors.size).toBeGreaterThan(0);
+    });
+  });
+
+  describe("toJSON", () => {
+    it("returns id, title, meta by default", () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      const json = instance.toJSON();
+      expect(json.id).toBe("epics/authentication");
+      expect(json.title).toBe("Authentication");
+      expect(json.meta).toBeDefined();
+    });
+
+    it("includes requested sections", () => {
+      const doc = collection.document(
+        "stories/authentication/a-user-should-be-able-to-register"
+      );
+      const instance = createModelInstance(doc, Story, collection);
+      const json = instance.toJSON({
+        sections: ["acceptanceCriteria"],
+      });
+      expect(json.acceptanceCriteria).toBeDefined();
+      expect(Array.isArray(json.acceptanceCriteria)).toBe(true);
+    });
+
+    it("includes requested computed values", () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      const json = instance.toJSON({ computed: ["isComplete"] });
+      expect(json.isComplete).toBe(false);
+    });
+
+    it("includes requested relationships", () => {
+      const doc = collection.document("epics/authentication");
+      const instance = createModelInstance(doc, Epic, collection);
+      const json = instance.toJSON({ related: ["stories"] });
+      expect(json.stories).toBeDefined();
+      expect(Array.isArray(json.stories)).toBe(true);
+    });
+  });
+});

package/test/query.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { QueryBuilder } from "../src/query/query-builder";
+import { operators } from "../src/query/operators";
+import { Collection } from "../src/collection";
+import { createTestCollection } from "./helpers";
+import { Epic } from "./fixtures/sdlc/models";
+
+describe("QueryBuilder", () => {
+  it("builds eq conditions with two args", () => {
+    const qb = new QueryBuilder();
+    qb.where("meta.status", "active");
+    expect(qb.conditions).toEqual([
+      { path: "meta.status", operator: "eq", value: "active" },
+    ]);
+  });
+
+  it("builds conditions with explicit operator", () => {
+    const qb = new QueryBuilder();
+    qb.where("meta.count", "gt", 5);
+    expect(qb.conditions[0].operator).toBe("gt");
+    expect(qb.conditions[0].value).toBe(5);
+  });
+
+  it("builds conditions from object shorthand", () => {
+    const qb = new QueryBuilder();
+    qb.where({ "meta.status": "active", "meta.type": "post" });
+    expect(qb.conditions.length).toBe(2);
+  });
+
+  it("whereIn adds in condition", () => {
+    const qb = new QueryBuilder();
+    qb.whereIn("meta.tags", ["a", "b"]);
+    expect(qb.conditions[0].operator).toBe("in");
+  });
+
+  it("whereNotIn adds notIn condition", () => {
+    const qb = new QueryBuilder();
+    qb.whereNotIn("meta.status", ["archived"]);
+    expect(qb.conditions[0].operator).toBe("notIn");
+  });
+
+  it("supports all chainable methods", () => {
+    const qb = new QueryBuilder();
+    const result = qb
+      .where("a", "1")
+      .whereGt("b", 2)
+      .whereLt("c", 3)
+      .whereGte("d", 4)
+      .whereLte("e", 5)
+      .whereContains("f", "hello")
+      .whereStartsWith("g", "pre")
+      .whereEndsWith("h", "suf")
+      .whereRegex("i", /test/)
+      .whereExists("j")
+      .whereNotExists("k");
+
+    expect(result).toBe(qb); // chaining returns this
+    expect(qb.conditions.length).toBe(11);
+  });
+
+  it("where with three args returns this (bug fix)", () => {
+    const qb = new QueryBuilder();
+    const result = qb.where("path", "neq", "value");
+    expect(result).toBe(qb);
+  });
+});
+
+describe("operators", () => {
+  it("eq handles primitive equality", () => {
+    expect(operators.eq("a", "a")).toBe(true);
+    expect(operators.eq("a", "b")).toBe(false);
+    expect(operators.eq(1, 1)).toBe(true);
+  });
+
+  it("eq handles deep equality", () => {
+    expect(operators.eq({ a: 1 }, { a: 1 })).toBe(true);
+    expect(operators.eq({ a: 1 }, { a: 2 })).toBe(false);
+  });
+
+  it("neq is negation of eq", () => {
+    expect(operators.neq("a", "b")).toBe(true);
+    expect(operators.neq("a", "a")).toBe(false);
+  });
+
+  it("in checks membership", () => {
+    expect(operators.in("a", ["a", "b"])).toBe(true);
+    expect(operators.in("c", ["a", "b"])).toBe(false);
+  });
+
+  it("notIn checks non-membership", () => {
+    expect(operators.notIn("c", ["a", "b"])).toBe(true);
+    expect(operators.notIn("a", ["a", "b"])).toBe(false);
+  });
+
+  it("gt/lt/gte/lte compare values", () => {
+    expect(operators.gt(5, 3)).toBe(true);
+    expect(operators.lt(3, 5)).toBe(true);
+    expect(operators.gte(5, 5)).toBe(true);
+    expect(operators.lte(5, 5)).toBe(true);
+  });
+
+  it("contains checks string inclusion", () => {
+    expect(operators.contains("hello world", "world")).toBe(true);
+    expect(operators.contains("hello", "world")).toBe(false);
+  });
+
+  it("startsWith/endsWith check string prefixes/suffixes", () => {
+    expect(operators.startsWith("hello", "hel")).toBe(true);
+    expect(operators.endsWith("hello", "llo")).toBe(true);
+  });
+
+  it("regex tests patterns", () => {
+    expect(operators.regex("hello123", /\d+/)).toBe(true);
+    expect(operators.regex("hello123", "\\d+")).toBe(true);
+    expect(operators.regex("hello", /\d+/)).toBe(false);
+  });
+
+  it("exists checks for defined values", () => {
+    expect(operators.exists("value", true)).toBe(true);
+    expect(operators.exists(null, true)).toBe(false);
+    expect(operators.exists(undefined, true)).toBe(false);
+    expect(operators.exists(null, false)).toBe(true);
+  });
+});
+
+describe("CollectionQuery", () => {
+  let collection: Collection;
+
+  beforeEach(async () => {
+    collection = await createTestCollection();
+  });
+
+  it("fetchAll returns matching model instances", async () => {
+    const epics = await collection.query(Epic).fetchAll();
+    expect(epics.length).toBe(2);
+  });
+
+  it("where filters results", async () => {
+    const epics = await collection
+      .query(Epic)
+      .where("meta.priority", "high")
+      .fetchAll();
+    expect(epics.length).toBe(1);
+    expect(epics[0].meta.priority).toBe("high");
+  });
+
+  it("first returns first result", async () => {
+    const first = await collection.query(Epic).first();
+    expect(first).toBeDefined();
+    expect(first!.title).toBeDefined();
+  });
+
+  it("last returns last result", async () => {
+    const last = await collection.query(Epic).last();
+    expect(last).toBeDefined();
+  });
+
+  it("count returns correct count", async () => {
+    const count = await collection.query(Epic).count();
+    expect(count).toBe(2);
+  });
+
+  it("empty conditions returns all of model type", async () => {
+    const all = await collection.query(Epic).fetchAll();
+    expect(all.length).toBe(2);
+  });
+});

package/test/relationships.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { Collection } from "../src/collection";
+import { createModelInstance } from "../src/model-instance";
+import { createTestCollection } from "./helpers";
+import { Epic, Story } from "./fixtures/sdlc/models";
+
+describe("HasManyRelationship", () => {
+  let collection: Collection;
+
+  beforeEach(async () => {
+    collection = await createTestCollection();
+  });
+
+  it("extracts child headings from parent section", () => {
+    const epic = collection.getModel("epics/authentication", Epic);
+    const stories = epic.relationships.stories.fetchAll();
+    expect(stories.length).toBe(2);
+  });
+
+  it("child instances have correct titles", () => {
+    const epic = collection.getModel("epics/authentication", Epic);
+    const stories = epic.relationships.stories.fetchAll();
+    expect(stories[0].title).toContain("register");
+    expect(stories[1].title).toContain("login");
+  });
+
+  it("first returns first child", () => {
+    const epic = collection.getModel("epics/authentication", Epic);
+    const first = epic.relationships.stories.first();
+    expect(first).toBeDefined();
+  });
+
+  it("last returns last child", () => {
+    const epic = collection.getModel("epics/authentication", Epic);
+    const last = epic.relationships.stories.last();
+    expect(last).toBeDefined();
+  });
+
+  it("works with epic that has multiple stories", () => {
+    const epic = collection.getModel(
+      "epics/searching-and-browsing",
+      Epic
+    );
+    const stories = epic.relationships.stories.fetchAll();
+    expect(stories.length).toBe(3);
+  });
+
+  it("computes IDs as targetPrefix/parentSlug/childSlug", () => {
+    const epic = collection.getModel("epics/authentication", Epic);
+    const stories = epic.relationships.stories.fetchAll();
+    expect(stories[0].id).toContain("stories/");
+    expect(stories[0].id).toContain("authentication");
+  });
+});
+
+describe("BelongsToRelationship", () => {
+  let collection: Collection;
+
+  beforeEach(async () => {
+    collection = await createTestCollection();
+  });
+
+  it("resolves parent by foreign key", () => {
+    const story = collection.getModel(
+      "stories/authentication/a-user-should-be-able-to-register",
+      Story
+    );
+    const epic = story.relationships.epic.fetch();
+    expect(epic.title).toBe("Authentication");
+    expect(epic.id).toBe("epics/authentication");
+  });
+
+  it("throws if parent not found", () => {
+    const doc = collection.createDocument({
+      id: "test/orphan",
+      content: "# Orphan Story\n",
+      meta: { epic: "nonexistent" },
+    });
+    const instance = createModelInstance(doc, Story, collection);
+    expect(() => instance.relationships.epic.fetch()).toThrow(
+      'Could not find Epic'
+    );
+  });
+});