@fragno-dev/corpus 0.0.2 → 0.0.4

package/src/index.ts

@@ -1,51 +0,0 @@
-import {
-  getAvailableSubjectIds,
-  loadSubject,
-  loadSubjects,
-  loadAllSubjects,
-  type SubjectInfo,
-  type Subject,
-} from "./parser";
-
-/**
- * Get basic information about all available subjects
- * @returns Array of subject info (id and title)
- */
-export function getSubjects(): SubjectInfo[] {
-  const ids = getAvailableSubjectIds();
-  return ids.map((id) => {
-    const subject = loadSubject(id);
-    return {
-      id: subject.id,
-      title: subject.title,
-    };
-  });
-}
-
-/**
- * Get one or more subjects by their IDs
- * @param ids Subject IDs to load
- * @returns Array of complete subject data
- * @example
- * ```ts
- * // Get single subject
- * const [routes] = getSubject("defining-routes");
- *
- * // Get multiple subjects for combined context
- * const [adapters, kysely] = getSubject("database-adapters", "kysely-adapter");
- * ```
- */
-export function getSubject(...ids: string[]): Subject[] {
-  return loadSubjects(ids);
-}
-
-/**
- * Get all available subjects
- * @returns Array of all subjects with complete data
- */
-export function getAllSubjects(): Subject[] {
-  return loadAllSubjects();
-}
-
-// Re-export types
-export type { Subject, SubjectInfo, Example } from "./parser.js";

package/src/parser.test.ts

@@ -1,115 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { parseMarkdownFile, markdownToSubject } from "./parser.js";
-
-describe("parseMarkdownFile", () => {
-  it("should extract title from markdown", () => {
-    const content = `# Test Title
-
-Description here`;
-
-    const result = parseMarkdownFile(content);
-    expect(result.title).toBe("Test Title");
-  });
-
-  it("should extract description", () => {
-    const content = `# Test Title
-
-This is a description.
-
-\`\`\`typescript @fragno-imports
-import { test } from "test";
-\`\`\``;
-
-    const result = parseMarkdownFile(content);
-    expect(result.description).toBe("This is a description.");
-  });
-
-  it("should extract imports block", () => {
-    const content = `# Test
-
-\`\`\`typescript @fragno-imports
-import { defineRoute } from "@fragno-dev/core";
-import { z } from "zod";
-\`\`\``;
-
-    const result = parseMarkdownFile(content);
-    expect(result.imports).toBe(`import { defineRoute } from "@fragno-dev/core";
-import { z } from "zod";`);
-  });
-
-  it("should extract init block when present", () => {
-    const content = `# Test
-
-\`\`\`typescript @fragno-imports
-import { x } from "y";
-\`\`\`
-
-\`\`\`typescript @fragno-init
-const config = { key: "value" };
-\`\`\``;
-
-    const result = parseMarkdownFile(content);
-    expect(result.init).toBe(`const config = { key: "value" };`);
-  });
-
-  it("should handle missing init block", () => {
-    const content = `# Test
-
-\`\`\`typescript @fragno-imports
-import { x } from "y";
-\`\`\``;
-
-    const result = parseMarkdownFile(content);
-    expect(result.init).toBe("");
-  });
-
-  it("should extract multiple test blocks", () => {
-    const content = `# Test
-
-\`\`\`typescript @fragno-imports
-import { x } from "y";
-\`\`\`
-
-\`\`\`typescript @fragno-test
-const test1 = "value1";
-\`\`\`
-
-This is explanation for test1.
-
-\`\`\`typescript @fragno-test
-const test2 = "value2";
-\`\`\`
-
-This is explanation for test2.`;
-
-    const result = parseMarkdownFile(content);
-    expect(result.testBlocks).toHaveLength(2);
-    expect(result.testBlocks[0].code).toBe(`const test1 = "value1";`);
-    expect(result.testBlocks[0].explanation).toContain("explanation for test1");
-    expect(result.testBlocks[1].code).toBe(`const test2 = "value2";`);
-    expect(result.testBlocks[1].explanation).toContain("explanation for test2");
-  });
-});
-
-describe("markdownToSubject", () => {
-  it("should convert parsed markdown to Subject", () => {
-    const parsed = {
-      title: "Test Subject",
-      description: "Test description",
-      imports: "import { x } from 'y';",
-      init: "const config = {};",
-      testBlocks: [{ code: "const test = 1;", explanation: "Test explanation" }],
-    };
-
-    const result = markdownToSubject("test-id", parsed);
-
-    expect(result.id).toBe("test-id");
-    expect(result.title).toBe("Test Subject");
-    expect(result.description).toBe("Test description");
-    expect(result.imports).toBe("import { x } from 'y';");
-    expect(result.init).toBe("const config = {};");
-    expect(result.examples).toHaveLength(1);
-    expect(result.examples[0].code).toBe("const test = 1;");
-    expect(result.examples[0].explanation).toBe("Test explanation");
-  });
-});

package/src/parser.ts

@@ -1,182 +0,0 @@
-import { readFileSync, readdirSync } from "node:fs";
-import { join, basename, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-/**
- * Basic information about a subject
- */
-export interface SubjectInfo {
-  id: string;
-  title: string;
-}
-
-/**
- * A single example within a subject
- */
-export interface Example {
-  code: string;
-  explanation: string;
-  testType?: "route" | "database" | "none";
-  testName?: string;
-}
-
-/**
- * Complete subject with all examples and metadata
- */
-export interface Subject {
-  id: string;
-  title: string;
-  description: string;
-  imports: string;
-  init: string;
-  examples: Example[];
-}
-
-/**
- * Raw parsed data from markdown before processing
- */
-export interface ParsedMarkdown {
-  title: string;
-  description: string;
-  imports: string;
-  init: string;
-  testBlocks: Array<{
-    code: string;
-    explanation: string;
-    testType?: "route" | "database" | "none";
-    testName?: string;
-  }>;
-}
-
-// Look for subjects directory in source or relative to built dist
-const SUBJECTS_DIR = (() => {
-  // Try dist/../src/subjects (when running from built code)
-  const distRelative = join(__dirname, "..", "src", "subjects");
-  try {
-    readdirSync(distRelative);
-    return distRelative;
-  } catch {
-    // Fall back to ./subjects (when running from source)
-    return join(__dirname, "subjects");
-  }
-})();
-
-/**
- * Parses a markdown file and extracts structured content
- */
-export function parseMarkdownFile(content: string): ParsedMarkdown {
-  // Extract title (first # heading)
-  const titleMatch = content.match(/^#\s+(.+)$/m);
-  const title = titleMatch ? titleMatch[1].trim() : "Untitled";
-
-  // Extract imports block
-  const importsMatch = content.match(/```typescript @fragno-imports\n([\s\S]*?)```/);
-  const imports = importsMatch ? importsMatch[1].trim() : "";
-
-  // Extract init block (optional)
-  const initMatch = content.match(/```typescript @fragno-init\n([\s\S]*?)```/);
-  const init = initMatch ? initMatch[1].trim() : "";
-
-  // Extract all test blocks with their explanations and test type
-  const testBlockRegex =
-    /```typescript @fragno-test(?::(\w+))?\n([\s\S]*?)```([\s\S]*?)(?=```typescript @fragno-test|$)/g;
-  const testBlocks: Array<{
-    code: string;
-    explanation: string;
-    testType?: "route" | "database" | "none";
-    testName?: string;
-  }> = [];
-
-  let match;
-  while ((match = testBlockRegex.exec(content)) !== null) {
-    const testTypeRaw = match[1]; // route, database, or undefined
-    const testType = testTypeRaw === "route" || testTypeRaw === "database" ? testTypeRaw : "none";
-
-    const code = match[2].trim();
-
-    // Extract test name from first line if it's a comment
-    const lines = code.split("\n");
-    let testName: string | undefined;
-    if (lines[0]?.trim().startsWith("//")) {
-      testName = lines[0].replace(/^\/\/\s*/, "").trim();
-    }
-
-    // Get explanation text after the code block until next code block or end
-    const afterBlock = match[3];
-    const explanation = afterBlock
-      .split(/```/)[0] // Stop at next code block
-      .trim();
-
-    testBlocks.push({ code, explanation, testType, testName });
-  }
-
-  // Extract description (everything between title and first code block or ## heading)
-  const afterTitle = content.substring(content.indexOf(title) + title.length);
-  const descriptionMatch = afterTitle.match(/\n\n([\s\S]*?)(?=```|##|$)/);
-  const description = descriptionMatch ? descriptionMatch[1].trim() : "";
-
-  return {
-    title,
-    description,
-    imports,
-    init,
-    testBlocks,
-  };
-}
-
-/**
- * Converts parsed markdown to a Subject
- */
-export function markdownToSubject(id: string, parsed: ParsedMarkdown): Subject {
-  const examples: Example[] = parsed.testBlocks.map((block) => ({
-    code: block.code,
-    explanation: block.explanation,
-    testType: block.testType,
-    testName: block.testName,
-  }));
-
-  return {
-    id,
-    title: parsed.title,
-    description: parsed.description,
-    imports: parsed.imports,
-    init: parsed.init,
-    examples,
-  };
-}
-
-/**
- * Loads and parses a subject file by ID
- */
-export function loadSubject(id: string): Subject {
-  const filePath = join(SUBJECTS_DIR, `${id}.md`);
-  const content = readFileSync(filePath, "utf-8");
-  const parsed = parseMarkdownFile(content);
-  return markdownToSubject(id, parsed);
-}
-
-/**
- * Gets all available subject IDs from the subjects directory
- */
-export function getAvailableSubjectIds(): string[] {
-  const files = readdirSync(SUBJECTS_DIR);
-  return files.filter((file) => file.endsWith(".md")).map((file) => basename(file, ".md"));
-}
-
-/**
- * Loads multiple subjects by their IDs
- */
-export function loadSubjects(ids: string[]): Subject[] {
-  return ids.map((id) => loadSubject(id));
-}
-
-/**
- * Loads all available subjects
- */
-export function loadAllSubjects(): Subject[] {
-  const ids = getAvailableSubjectIds();
-  return loadSubjects(ids);
-}

package/src/subjects/database-adapters.md

@@ -1,68 +0,0 @@
-# Database Adapters
-
-Database adapters connect Fragno's database API to your existing ORM (Kysely or Drizzle). They allow
-fragments to work with your application's database without dictating which ORM you use.
-
-```typescript @fragno-imports
-import type { DatabaseAdapter } from "@fragno-dev/db";
-```
-
-## What is a Database Adapter?
-
-A database adapter is a bridge between Fragno's type-safe database API and your underlying ORM. It
-translates Fragno's query operations into ORM-specific syntax.
-
-```typescript
-// Adapters implement the DatabaseAdapter interface
-declare const adapter: DatabaseAdapter;
-
-// Fragments receive an adapter through their configuration
-interface FragmentConfig {
-  databaseAdapter: DatabaseAdapter;
-}
-```
-
-When a fragment needs database access, users pass an adapter configured with their ORM instance.
-
-## Supported Providers
-
-Both KyselyAdapter and DrizzleAdapter support three database providers:
-
-- `"postgresql"` - PostgreSQL databases
-- `"mysql"` - MySQL and MariaDB databases
-- `"sqlite"` - SQLite databases
-
-Choose the provider that matches your database type when creating an adapter.
-
-## Shared Adapters
-
-Multiple fragments can share the same adapter, meaning they all use your application's single
-database connection.
-
-```typescript
-declare const adapter: DatabaseAdapter;
-
-// All fragments use the same adapter
-export interface Fragment1Config {
-  databaseAdapter: typeof adapter;
-}
-
-export interface Fragment2Config {
-  databaseAdapter: typeof adapter;
-}
-```
-
-This ensures fragments integrate seamlessly with your existing database infrastructure.
-
-## Cleanup
-
-Adapters manage connection lifecycle automatically. Call `close()` when shutting down your
-application to properly release database connections.
-
-```typescript
-declare const adapter: DatabaseAdapter;
-
-export async function cleanup() {
-  await adapter.close();
-}
-```

package/src/subjects/database-querying.md

@@ -1,227 +0,0 @@
-# Database Querying
-
-Fragno provides a unified database query API that works across different ORMs. This guide covers
-CRUD operations and querying with conditions.
-
-```typescript @fragno-imports
-import { defineFragnoDatabase, schema, idColumn, column } from "@fragno-dev/db";
-import type { AbstractQuery } from "@fragno-dev/db";
-```
-
-```typescript @fragno-init
-// Example schema for testing
-const userSchema = schema((s) => {
-  return s
-    .addTable("users", (t) => {
-      return t
-        .addColumn("id", idColumn())
-        .addColumn("email", column("string"))
-        .addColumn("name", column("string"))
-        .addColumn("age", column("integer").nullable())
-        .createIndex("idx_email", ["email"], { unique: true });
-    })
-    .addTable("posts", (t) => {
-      return t
-        .addColumn("id", idColumn())
-        .addColumn("title", column("string"))
-        .addColumn("content", column("string"))
-        .addColumn("authorId", column("string"))
-        .addColumn("publishedAt", column("timestamp").nullable())
-        .createIndex("idx_author", ["authorId"]);
-    });
-});
-
-type UserSchema = typeof userSchema;
-declare const orm: AbstractQuery<UserSchema>;
-```
-
-## Create
-
-Create a single record in the database.
-
-```typescript
-export async function createUser() {
-  const userId = await orm.create("users", {
-    id: "user-123",
-    email: "john@example.com",
-    name: "John Doe",
-    age: 30,
-  });
-
-  return userId; // Returns a FragnoId object
-}
-```
-
-The `create` method returns a `FragnoId` object representing the created record's ID.
-
-## Create Many
-
-Create multiple records at once.
-
-```typescript
-export async function createMultipleUsers() {
-  const userIds = await orm.createMany("users", [
-    {
-      id: "user-1",
-      email: "user1@example.com",
-      name: "User One",
-      age: 25,
-    },
-    {
-      id: "user-2",
-      email: "user2@example.com",
-      name: "User Two",
-      age: 35,
-    },
-  ]);
-
-  return userIds; // Returns an array of FragnoId objects
-}
-```
-
-## Find First
-
-Query for a single record using an index.
-
-```typescript
-export async function findUserByEmail(email: string) {
-  const user = await orm.findFirst("users", (b) =>
-    b.whereIndex("idx_email", (eb) => eb("email", "=", email)),
-  );
-
-  return user; // Returns the user object or null if not found
-}
-```
-
-Use `findFirst` when you expect a single result or want to get the first matching record.
-
-## Find First with Select
-
-Query a single record and select specific columns.
-
-```typescript
-export async function findUserEmailOnly(userId: string) {
-  const user = await orm.findFirst("users", (b) =>
-    b.whereIndex("primary", (eb) => eb("id", "=", userId)).select(["id", "email"]),
-  );
-
-  return user; // Returns only id and email fields
-}
-```
-
-## Find Many
-
-Query for multiple records matching conditions.
-
-```typescript
-export async function findPostsByAuthor(authorId: string) {
-  const posts = await orm.find("posts", (b) =>
-    b.whereIndex("idx_author", (eb) => eb("authorId", "=", authorId)),
-  );
-
-  return posts; // Returns an array of posts
-}
-```
-
-The `find` method returns all records matching the where clause.
-
-## Find with Pagination
-
-Limit the number of results returned.
-
-```typescript
-export async function findUsersPaginated(page: number, pageSize: number) {
-  const users = await orm.find("users", (b) => b.whereIndex("primary").pageSize(pageSize));
-
-  return users;
-}
-```
-
-## Find All
-
-Query all records from a table.
-
-```typescript
-export async function findAllUsers() {
-  const users = await orm.find("users", (b) => b.whereIndex("primary"));
-
-  return users;
-}
-```
-
-When using `whereIndex("primary")` without conditions, it returns all records.
-
-## Update
-
-Update a single record by ID.
-
-```typescript
-export async function updateUserEmail(userId: string, newEmail: string) {
-  await orm.update("users", userId, (b) =>
-    b.set({
-      email: newEmail,
-    }),
-  );
-}
-```
-
-The `update` method modifies a single record identified by its ID.
-
-## Update Many
-
-Update multiple records matching a condition.
-
-```typescript
-export async function updatePostsPublishedDate(authorId: string, publishedAt: Date) {
-  await orm.updateMany("posts", (b) =>
-    b.whereIndex("idx_author", (eb) => eb("authorId", "=", authorId)).set({ publishedAt }),
-  );
-}
-```
-
-`updateMany` finds all matching records and updates them.
-
-## Delete
-
-Delete a single record by ID.
-
-```typescript
-export async function deleteUser(userId: string) {
-  await orm.delete("users", userId);
-}
-```
-
-## Delete Many
-
-Delete multiple records matching a condition.
-
-```typescript
-export async function deletePostsByAuthor(authorId: string) {
-  await orm.deleteMany("posts", (b) =>
-    b.whereIndex("idx_author", (eb) => eb("authorId", "=", authorId)),
-  );
-}
-```
-
-`deleteMany` finds all matching records and deletes them.
-
-## Querying with Conditions
-
-Use condition builders to create complex queries.
-
-```typescript
-export async function findAdultUsers() {
-  const adults = await orm.find("users", (b) =>
-    b.whereIndex("primary").where((cb) => {
-      // Note: Condition builders depend on the underlying ORM
-      // This is a simplified example
-      return cb;
-    }),
-  );
-
-  return adults;
-}
-```
-
-Condition builders allow you to add additional filtering beyond index lookups, though the exact API
-depends on your adapter (Kysely or Drizzle).