@fragno-dev/corpus 0.0.2 → 0.0.4

package/README.md

@@ -21,9 +21,9 @@ import { getSubjects, getSubject, getAllSubjects } from "@fragno-dev/corpus";
 const subjects = getSubjects();
 // [{ id: "defining-routes", title: "Defining Routes" }, ...]
 
-// Get one or more subjects
+// Get one or more subjects (deterministically ordered by subject tree)
 const [routes] = getSubject("defining-routes");
-// { id, title, description, imports, init, examples }
+// { id, title, description, imports, prelude, testInit, examples, sections }
 
 // Get multiple subjects for combined context
 const [adapters, kysely] = getSubject("database-adapters", "kysely-adapter");
@@ -40,26 +40,34 @@ Required block at the top with all imports:
 \`\`\`typescript @fragno-imports import { defineRoute } from "@fragno-dev/core"; import { z } from
 "zod"; \`\`\`
 
-### @fragno-init (optional)
+### @fragno-prelude (optional)
 
-Initialization code needed for examples:
+Setup code shown to users reading the corpus (e.g., schema definitions, configuration):
 
-\`\`\`typescript @fragno-init const config = { apiKey: "test-key" }; \`\`\`
+\`\`\`typescript @fragno-prelude:schema const userSchema = schema((s) => { return
+s.addTable("users", (t) => { return t.addColumn("id", idColumn()); }); }); \`\`\`
 
-### @fragno-test:route or @fragno-test:database
+Optional ID syntax (`:schema`) helps identify code blocks for agent references.
 
-Runnable test code with type annotations:
+### @fragno-test-init (optional)
 
-\`\`\`typescript @fragno-test:route // test name from first comment line const route = defineRoute({
-method: "GET", path: "/hello", outputSchema: z.string(), handler: async (\_, { json }) =>
-json("Hello"), });
+Test-only initialization code (not shown to users, only used in generated tests):
 
-expect(route.method).toBe("GET"); \`\`\`
+\`\`\`typescript @fragno-test-init const { fragment } = await
+createDatabaseFragmentForTest(testFragmentDef, []); const orm = fragment.services.orm; \`\`\`
 
-- Use `@fragno-test:route` for route tests (uses `@fragno-dev/core/test`)
-- Use `@fragno-test:database` for database tests (uses `@fragno-dev/test`)
-- Omit `:route` or `:database` for documentation-only examples (no test generation)
+### @fragno-test
+
+Runnable test code with optional IDs:
+
+\`\`\`typescript @fragno-test:create-user // should create a single user const userId = await
+orm.create("users", { id: "user-123", email: "john@example.com", });
+
+expect(userId).toBeDefined(); \`\`\`
+
+- Optional ID syntax (`:create-user`) helps agents reference specific examples
 - First comment line becomes the test name
+- IDs are optional - tests generate properly without them
 
 Between code blocks, add markdown explanations.
 
@@ -67,26 +75,53 @@ Between code blocks, add markdown explanations.
 
 1. Create `src/subjects/your-subject.md`
 2. Add `@fragno-imports` block at top
-3. Add optional `@fragno-init` if needed
-4. Add multiple `@fragno-test` blocks with examples
-5. Write explanations between code blocks
-6. Run `pnpm test` to validate
+3. Add optional `@fragno-prelude` for user-visible setup code
+4. Add optional `@fragno-test-init` for test-only initialization
+5. Add multiple `@fragno-test` blocks with examples (optional IDs)
+6. Write explanations between code blocks
+7. Update `src/subject-tree.ts` to add subject to the tree structure
+8. Run `pnpm test` to validate
 
 ## Testing
 
 Tests use vitest `globalSetup` to:
 
 1. Parse all markdown files
-2. Extract `@fragno-test:route` and `@fragno-test:database` blocks
+2. Extract `@fragno-prelude` (user-visible setup), `@fragno-test-init` (test-only), and
+   `@fragno-test` blocks
 3. Generate temporary `.test.ts` files with actual vitest test cases
 4. Type-check and execute them
 
-Each test block becomes a `describe()` suite with `it()` test cases. Test names come from the first
-comment line in each block.
+Each subject's test file includes:
+
+- Imports from `@fragno-imports`
+- Setup from `@fragno-prelude` (shown to users)
+- Initialization from `@fragno-test-init` (test-only)
+- Test cases from `@fragno-test` blocks
+
+Test names come from the first comment line in each `@fragno-test` block.
 
 Run tests: `pnpm test`
 
-Generated tests are in `.corpus-tests/` (temporary directory).
+Generated tests are in `corpus-tests/` (temporary directory).
+
+## CLI Integration
+
+The corpus can be viewed via the Fragno CLI with various options:
+
+```bash
+# View a subject
+fragno-cli corpus database-querying
+
+# Show only headings and code block IDs with line numbers
+fragno-cli corpus --headings database-querying
+
+# Show specific line range with line numbers
+fragno-cli corpus --line-numbers --start 1 --end 50 database-querying
+
+# Multiple subjects (automatically ordered by subject tree)
+fragno-cli corpus database-adapters kysely-adapter
+```
 
 ## TODO: Future Subjects
 

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+//#region src/parser.d.ts
+/**
+ * Basic information about a subject
+ */
+interface SubjectInfo {
+  id: string;
+  title: string;
+}
+/**
+ * A single example within a subject
+ */
+interface Example {
+  code: string;
+  explanation: string;
+  testName?: string;
+  id?: string;
+}
+/**
+ * A code block with optional ID
+ */
+interface CodeBlock {
+  code: string;
+  id?: string;
+}
+/**
+ * A markdown section with heading and content
+ */
+interface Section {
+  heading: string;
+  content: string;
+  lineNumber?: number;
+}
+/**
+ * Complete subject with all examples and metadata
+ */
+interface Subject {
+  id: string;
+  title: string;
+  description: string;
+  imports: string;
+  prelude: CodeBlock[];
+  testInit: CodeBlock[];
+  examples: Example[];
+  sections: Section[];
+}
+//#endregion
+//#region src/subject-tree.d.ts
+/**
+ * Gets the parent of a subject, or null if it's a root subject
+ */
+declare function getSubjectParent(subjectId: string): string | null;
+/**
+ * Gets the children of a subject
+ */
+declare function getSubjectChildren(subjectId: string): string[];
+/**
+ * Orders an array of subject IDs according to the tree structure
+ * This ensures deterministic ordering regardless of input order
+ */
+declare function orderSubjects(subjectIds: string[]): string[];
+/**
+ * Expands a subject ID to include its children if it has any
+ * Useful for when a user requests a parent topic and wants to see all related content
+ */
+declare function expandSubjectWithChildren(subjectId: string): string[];
+/**
+ * Gets all subject IDs in tree order
+ */
+declare function getAllSubjectIdsInOrder(): string[];
+//#endregion
+//#region src/index.d.ts
+/**
+ * Get basic information about all available subjects
+ * @returns Array of subject info (id and title)
+ */
+declare function getSubjects(): SubjectInfo[];
+/**
+ * Get one or more subjects by their IDs
+ * @param ids Subject IDs to load
+ * @returns Array of complete subject data ordered by the subject tree
+ * @example
+ * ```ts
+ * // Get single subject
+ * const [routes] = getSubject("defining-routes");
+ *
+ * // Get multiple subjects for combined context
+ * const [adapters, kysely] = getSubject("database-adapters", "kysely-adapter");
+ * ```
+ */
+declare function getSubject(...ids: string[]): Subject[];
+/**
+ * Get all available subjects
+ * @returns Array of all subjects with complete data
+ */
+declare function getAllSubjects(): Subject[];
+//#endregion
+export { type CodeBlock, type Example, type Section, type Subject, type SubjectInfo, expandSubjectWithChildren, getAllSubjectIdsInOrder, getAllSubjects, getSubject, getSubjectChildren, getSubjectParent, getSubjects, orderSubjects };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/parser.ts","../src/subject-tree.ts","../src/index.ts"],"sourcesContent":[],"mappings":";;AAUA;AAQA;AAUiB,UAlBA,WAAA,CAkBS;EAQT,EAAA,EAAA,MAAO;EASP,KAAA,EAAA,MAAO;;;;;AAQL,UAnCF,OAAA,CAmCE;;;;ECLH,EAAA,CAAA,EAAA,MAAA;AAOhB;AASA;AAYA;AAWA;UD3DiB,SAAA;;;AEdjB;AAwBA;AAUA;;UFZiB,OAAA;;;;;;;;UASA,OAAA;;;;;WAKN;YACC;YACA;YACA;;;;;;;AAAO,iBCLH,gBAAA,CDKG,SAAA,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,IAAA;;;;ACLH,iBAOA,kBAAA,CAPgB,SAAA,EAAA,MAAA,CAAA,EAAA,MAAA,EAAA;AAOhC;AASA;AAYA;AAWA;iBAvBgB,aAAA;;;AClDhB;AAwBA;AAUgB,iBD4BA,yBAAA,CC5ByB,SAAA,EAAA,MAAA,CAAA,EAAA,MAAA,EAAA;;;;iBDuCzB,uBAAA,CAAA;;;AD7EhB;AAQA;AAUA;AAQA;AASiB,iBE/BD,WAAA,CAAA,CF+BQ,EE/BO,WF+BP,EAAA;;;;;;;;;ACGxB;AAOA;AASA;AAYA;AAWA;iBCjDgB,UAAA,oBAA8B;;;AAxB9C;AAwBA;AAUgB,iBAAA,cAAA,CAAA,CAAyB,EAAP,OAAO,EAAA"}

package/dist/index.js

@@ -0,0 +1,247 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/parser.ts
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SUBJECTS_DIR = (() => {
+	const distRelative = join(__dirname, "..", "src", "subjects");
+	try {
+		readdirSync(distRelative);
+		return distRelative;
+	} catch {
+		return join(__dirname, "subjects");
+	}
+})();
+/**
+* Helper function to extract code blocks with optional IDs from a directive
+*/
+function extractCodeBlocks(content, directive) {
+	const regex = new RegExp(`\`\`\`typescript @fragno-${directive}(?::(\\w+(?:-\\w+)*))?\\n([\\s\\S]*?)\`\`\``, "g");
+	const blocks = [];
+	let match;
+	while ((match = regex.exec(content)) !== null) {
+		const id = match[1] || void 0;
+		const code = match[2].trim();
+		blocks.push({
+			code,
+			id
+		});
+	}
+	return blocks;
+}
+/**
+* Parses a markdown file and extracts structured content
+*/
+function parseMarkdownFile(content) {
+	const titleMatch = content.match(/^#\s+(.+)$/m);
+	const title = titleMatch ? titleMatch[1].trim() : "Untitled";
+	const importsMatch = content.match(/```typescript @fragno-imports\n([\s\S]*?)```/);
+	const imports = importsMatch ? importsMatch[1].trim() : "";
+	const prelude = extractCodeBlocks(content, "prelude");
+	const testInit = extractCodeBlocks(content, "test-init");
+	const testBlockRegex = /```typescript @fragno-test(?::(\w+(?:-\w+)*))?\n([\s\S]*?)```([\s\S]*?)(?=```typescript @fragno-test|$)/g;
+	const testBlocks = [];
+	let match;
+	while ((match = testBlockRegex.exec(content)) !== null) {
+		const id = match[1] || void 0;
+		const code = match[2].trim();
+		const lines = code.split("\n");
+		let testName;
+		if (lines[0]?.trim().startsWith("//")) testName = lines[0].replace(/^\/\/\s*/, "").trim();
+		const explanation = match[3].split(/```/)[0].trim();
+		testBlocks.push({
+			code,
+			explanation,
+			testName,
+			id
+		});
+	}
+	const descriptionMatch = content.substring(content.indexOf(title) + title.length).match(/\n\n([\s\S]*?)(?=```|##|$)/);
+	const description = descriptionMatch ? descriptionMatch[1].trim() : "";
+	const sections = [];
+	const matches = [...content.matchAll(/^##\s+(.+)$/gm)];
+	for (let i = 0; i < matches.length; i++) {
+		const match$1 = matches[i];
+		const heading = match$1[1].trim();
+		const sectionStart = match$1.index + match$1[0].length;
+		const nextSectionStart = matches[i + 1]?.index ?? content.length;
+		let sectionContent = content.substring(sectionStart, nextSectionStart).trim();
+		sectionContent = sectionContent.replace(/```typescript @fragno-\w+(?::\w+(?:-\w+)*)?/g, "```typescript");
+		sectionContent = sectionContent.trim();
+		if (sectionContent) sections.push({
+			heading,
+			content: sectionContent
+		});
+	}
+	return {
+		title,
+		description,
+		imports,
+		prelude,
+		testInit,
+		testBlocks,
+		sections
+	};
+}
+/**
+* Converts parsed markdown to a Subject
+*/
+function markdownToSubject(id, parsed) {
+	const examples = parsed.testBlocks.map((block) => ({
+		code: block.code,
+		explanation: block.explanation,
+		testName: block.testName,
+		id: block.id
+	}));
+	return {
+		id,
+		title: parsed.title,
+		description: parsed.description,
+		imports: parsed.imports,
+		prelude: parsed.prelude,
+		testInit: parsed.testInit,
+		examples,
+		sections: parsed.sections
+	};
+}
+/**
+* Loads and parses a subject file by ID
+*/
+function loadSubject(id) {
+	return markdownToSubject(id, parseMarkdownFile(readFileSync(join(SUBJECTS_DIR, `${id}.md`), "utf-8")));
+}
+/**
+* Gets all available subject IDs from the subjects directory
+*/
+function getAvailableSubjectIds() {
+	return readdirSync(SUBJECTS_DIR).filter((file) => file.endsWith(".md")).map((file) => basename(file, ".md"));
+}
+/**
+* Loads multiple subjects by their IDs
+*/
+function loadSubjects(ids) {
+	return ids.map((id) => loadSubject(id));
+}
+/**
+* Loads all available subjects
+*/
+function loadAllSubjects() {
+	return loadSubjects(getAvailableSubjectIds());
+}
+
+//#endregion
+//#region src/subject-tree.ts
+/**
+* Tree structure defining subject hierarchy and ordering
+* - Root-level subjects are listed in order
+* - Children are indented under their parents
+*/
+const SUBJECT_TREE = [
+	{ id: "defining-routes" },
+	{ id: "fragment-services" },
+	{ id: "fragment-instantiation" },
+	{ id: "database-querying" },
+	{
+		id: "database-adapters",
+		children: ["kysely-adapter", "drizzle-adapter"]
+	}
+];
+/**
+* Flattened map of all subjects and their parent relationships
+*/
+const SUBJECT_PARENT_MAP = /* @__PURE__ */ new Map();
+const SUBJECT_ORDER_MAP = /* @__PURE__ */ new Map();
+let orderIndex = 0;
+for (const node of SUBJECT_TREE) {
+	SUBJECT_PARENT_MAP.set(node.id, null);
+	SUBJECT_ORDER_MAP.set(node.id, orderIndex++);
+	if (node.children) for (const childId of node.children) {
+		SUBJECT_PARENT_MAP.set(childId, node.id);
+		SUBJECT_ORDER_MAP.set(childId, orderIndex++);
+	}
+}
+/**
+* Gets the parent of a subject, or null if it's a root subject
+*/
+function getSubjectParent(subjectId) {
+	return SUBJECT_PARENT_MAP.get(subjectId) ?? null;
+}
+/**
+* Gets the children of a subject
+*/
+function getSubjectChildren(subjectId) {
+	return SUBJECT_TREE.find((n) => n.id === subjectId)?.children ?? [];
+}
+/**
+* Orders an array of subject IDs according to the tree structure
+* This ensures deterministic ordering regardless of input order
+*/
+function orderSubjects(subjectIds) {
+	return [...subjectIds].sort((a, b) => {
+		return (SUBJECT_ORDER_MAP.get(a) ?? Number.MAX_SAFE_INTEGER) - (SUBJECT_ORDER_MAP.get(b) ?? Number.MAX_SAFE_INTEGER);
+	});
+}
+/**
+* Expands a subject ID to include its children if it has any
+* Useful for when a user requests a parent topic and wants to see all related content
+*/
+function expandSubjectWithChildren(subjectId) {
+	const children = getSubjectChildren(subjectId);
+	if (children.length > 0) return [subjectId, ...children];
+	return [subjectId];
+}
+/**
+* Gets all subject IDs in tree order
+*/
+function getAllSubjectIdsInOrder() {
+	const ids = [];
+	for (const node of SUBJECT_TREE) {
+		ids.push(node.id);
+		if (node.children) ids.push(...node.children);
+	}
+	return ids;
+}
+
+//#endregion
+//#region src/index.ts
+/**
+* Get basic information about all available subjects
+* @returns Array of subject info (id and title)
+*/
+function getSubjects() {
+	return getAvailableSubjectIds().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 ordered by the subject tree
+* @example
+* ```ts
+* // Get single subject
+* const [routes] = getSubject("defining-routes");
+*
+* // Get multiple subjects for combined context
+* const [adapters, kysely] = getSubject("database-adapters", "kysely-adapter");
+* ```
+*/
+function getSubject(...ids) {
+	return loadSubjects(orderSubjects(ids));
+}
+/**
+* Get all available subjects
+* @returns Array of all subjects with complete data
+*/
+function getAllSubjects() {
+	return loadAllSubjects();
+}
+
+//#endregion
+export { expandSubjectWithChildren, getAllSubjectIdsInOrder, getAllSubjects, getSubject, getSubjectChildren, getSubjectParent, getSubjects, orderSubjects };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["blocks: CodeBlock[]","testBlocks: Array<{\n    code: string;\n    explanation: string;\n    testName?: string;\n    id?: string;\n  }>","testName: string | undefined","sections: Section[]","match","examples: Example[]","SUBJECT_TREE: SubjectNode[]","ids: string[]"],"sources":["../src/parser.ts","../src/subject-tree.ts","../src/index.ts"],"sourcesContent":["import { readFileSync, readdirSync } from \"node:fs\";\nimport { join, basename, dirname } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = dirname(__filename);\n\n/**\n * Basic information about a subject\n */\nexport interface SubjectInfo {\n  id: string;\n  title: string;\n}\n\n/**\n * A single example within a subject\n */\nexport interface Example {\n  code: string;\n  explanation: string;\n  testName?: string;\n  id?: string;\n}\n\n/**\n * A code block with optional ID\n */\nexport interface CodeBlock {\n  code: string;\n  id?: string;\n}\n\n/**\n * A markdown section with heading and content\n */\nexport interface Section {\n  heading: string;\n  content: string;\n  lineNumber?: number;\n}\n\n/**\n * Complete subject with all examples and metadata\n */\nexport interface Subject {\n  id: string;\n  title: string;\n  description: string;\n  imports: string;\n  prelude: CodeBlock[];\n  testInit: CodeBlock[];\n  examples: Example[];\n  sections: Section[];\n}\n\n/**\n * Raw parsed data from markdown before processing\n */\nexport interface ParsedMarkdown {\n  title: string;\n  description: string;\n  imports: string;\n  prelude: CodeBlock[];\n  testInit: CodeBlock[];\n  testBlocks: Array<{\n    code: string;\n    explanation: string;\n    testName?: string;\n    id?: string;\n  }>;\n  sections: Section[];\n}\n\n// Look for subjects directory in source or relative to built dist\nconst SUBJECTS_DIR = (() => {\n  // Try dist/../src/subjects (when running from built code)\n  const distRelative = join(__dirname, \"..\", \"src\", \"subjects\");\n  try {\n    readdirSync(distRelative);\n    return distRelative;\n  } catch {\n    // Fall back to ./subjects (when running from source)\n    return join(__dirname, \"subjects\");\n  }\n})();\n\n/**\n * Helper function to extract code blocks with optional IDs from a directive\n */\nfunction extractCodeBlocks(content: string, directive: string): CodeBlock[] {\n  const regex = new RegExp(\n    `\\`\\`\\`typescript @fragno-${directive}(?::(\\\\w+(?:-\\\\w+)*))?\\\\n([\\\\s\\\\S]*?)\\`\\`\\``,\n    \"g\",\n  );\n  const blocks: CodeBlock[] = [];\n\n  let match;\n  while ((match = regex.exec(content)) !== null) {\n    const id = match[1] || undefined;\n    const code = match[2].trim();\n    blocks.push({ code, id });\n  }\n\n  return blocks;\n}\n\n/**\n * Parses a markdown file and extracts structured content\n */\nexport function parseMarkdownFile(content: string): ParsedMarkdown {\n  // Extract title (first # heading)\n  const titleMatch = content.match(/^#\\s+(.+)$/m);\n  const title = titleMatch ? titleMatch[1].trim() : \"Untitled\";\n\n  // Extract imports block\n  const importsMatch = content.match(/```typescript @fragno-imports\\n([\\s\\S]*?)```/);\n  const imports = importsMatch ? importsMatch[1].trim() : \"\";\n\n  // Extract prelude blocks\n  const prelude = extractCodeBlocks(content, \"prelude\");\n\n  // Extract test-init blocks\n  const testInit = extractCodeBlocks(content, \"test-init\");\n\n  // Extract all test blocks with their explanations and optional IDs\n  const testBlockRegex =\n    /```typescript @fragno-test(?::(\\w+(?:-\\w+)*))?\\n([\\s\\S]*?)```([\\s\\S]*?)(?=```typescript @fragno-test|$)/g;\n  const testBlocks: Array<{\n    code: string;\n    explanation: string;\n    testName?: string;\n    id?: string;\n  }> = [];\n\n  let match;\n  while ((match = testBlockRegex.exec(content)) !== null) {\n    const id = match[1] || undefined;\n    const code = match[2].trim();\n\n    // Extract test name from first line if it's a comment\n    const lines = code.split(\"\\n\");\n    let testName: string | undefined;\n    if (lines[0]?.trim().startsWith(\"//\")) {\n      testName = lines[0].replace(/^\\/\\/\\s*/, \"\").trim();\n    }\n\n    // Get explanation text after the code block until next code block or end\n    const afterBlock = match[3];\n    const explanation = afterBlock\n      .split(/```/)[0] // Stop at next code block\n      .trim();\n\n    testBlocks.push({ code, explanation, testName, id });\n  }\n\n  // Extract description (everything between title and first code block or ## heading)\n  const afterTitle = content.substring(content.indexOf(title) + title.length);\n  const descriptionMatch = afterTitle.match(/\\n\\n([\\s\\S]*?)(?=```|##|$)/);\n  const description = descriptionMatch ? descriptionMatch[1].trim() : \"\";\n\n  // Extract all sections (## headings and their content)\n  const sections: Section[] = [];\n  const sectionRegex = /^##\\s+(.+)$/gm;\n  const matches = [...content.matchAll(sectionRegex)];\n\n  for (let i = 0; i < matches.length; i++) {\n    const match = matches[i];\n    const heading = match[1].trim();\n    const sectionStart = match.index! + match[0].length;\n    const nextSectionStart = matches[i + 1]?.index ?? content.length;\n    let sectionContent = content.substring(sectionStart, nextSectionStart).trim();\n\n    // Convert @fragno directive code blocks to regular typescript blocks for display\n    sectionContent = sectionContent.replace(\n      /```typescript @fragno-\\w+(?::\\w+(?:-\\w+)*)?/g,\n      \"```typescript\",\n    );\n    sectionContent = sectionContent.trim();\n\n    if (sectionContent) {\n      sections.push({ heading, content: sectionContent });\n    }\n  }\n\n  return {\n    title,\n    description,\n    imports,\n    prelude,\n    testInit,\n    testBlocks,\n    sections,\n  };\n}\n\n/**\n * Converts parsed markdown to a Subject\n */\nexport function markdownToSubject(id: string, parsed: ParsedMarkdown): Subject {\n  const examples: Example[] = parsed.testBlocks.map((block) => ({\n    code: block.code,\n    explanation: block.explanation,\n    testName: block.testName,\n    id: block.id,\n  }));\n\n  return {\n    id,\n    title: parsed.title,\n    description: parsed.description,\n    imports: parsed.imports,\n    prelude: parsed.prelude,\n    testInit: parsed.testInit,\n    examples,\n    sections: parsed.sections,\n  };\n}\n\n/**\n * Loads and parses a subject file by ID\n */\nexport function loadSubject(id: string): Subject {\n  const filePath = join(SUBJECTS_DIR, `${id}.md`);\n  const content = readFileSync(filePath, \"utf-8\");\n  const parsed = parseMarkdownFile(content);\n  return markdownToSubject(id, parsed);\n}\n\n/**\n * Gets all available subject IDs from the subjects directory\n */\nexport function getAvailableSubjectIds(): string[] {\n  const files = readdirSync(SUBJECTS_DIR);\n  return files.filter((file) => file.endsWith(\".md\")).map((file) => basename(file, \".md\"));\n}\n\n/**\n * Loads multiple subjects by their IDs\n */\nexport function loadSubjects(ids: string[]): Subject[] {\n  return ids.map((id) => loadSubject(id));\n}\n\n/**\n * Loads all available subjects\n */\nexport function loadAllSubjects(): Subject[] {\n  const ids = getAvailableSubjectIds();\n  return loadSubjects(ids);\n}\n","/**\n * Subject tree structure defining relationships and ordering\n */\n\nexport interface SubjectNode {\n  id: string;\n  children?: string[];\n}\n\n/**\n * Tree structure defining subject hierarchy and ordering\n * - Root-level subjects are listed in order\n * - Children are indented under their parents\n */\nconst SUBJECT_TREE: SubjectNode[] = [\n  { id: \"defining-routes\" },\n  { id: \"fragment-services\" },\n  { id: \"fragment-instantiation\" },\n  { id: \"database-querying\" },\n  {\n    id: \"database-adapters\",\n    children: [\"kysely-adapter\", \"drizzle-adapter\"],\n  },\n];\n\n/**\n * Flattened map of all subjects and their parent relationships\n */\nconst SUBJECT_PARENT_MAP = new Map<string, string | null>();\nconst SUBJECT_ORDER_MAP = new Map<string, number>();\n\n// Build the parent and order maps\nlet orderIndex = 0;\nfor (const node of SUBJECT_TREE) {\n  SUBJECT_PARENT_MAP.set(node.id, null);\n  SUBJECT_ORDER_MAP.set(node.id, orderIndex++);\n\n  if (node.children) {\n    for (const childId of node.children) {\n      SUBJECT_PARENT_MAP.set(childId, node.id);\n      SUBJECT_ORDER_MAP.set(childId, orderIndex++);\n    }\n  }\n}\n\n/**\n * Gets the parent of a subject, or null if it's a root subject\n */\nexport function getSubjectParent(subjectId: string): string | null {\n  return SUBJECT_PARENT_MAP.get(subjectId) ?? null;\n}\n\n/**\n * Gets the children of a subject\n */\nexport function getSubjectChildren(subjectId: string): string[] {\n  const node = SUBJECT_TREE.find((n) => n.id === subjectId);\n  return node?.children ?? [];\n}\n\n/**\n * Orders an array of subject IDs according to the tree structure\n * This ensures deterministic ordering regardless of input order\n */\nexport function orderSubjects(subjectIds: string[]): string[] {\n  return [...subjectIds].sort((a, b) => {\n    const orderA = SUBJECT_ORDER_MAP.get(a) ?? Number.MAX_SAFE_INTEGER;\n    const orderB = SUBJECT_ORDER_MAP.get(b) ?? Number.MAX_SAFE_INTEGER;\n    return orderA - orderB;\n  });\n}\n\n/**\n * Expands a subject ID to include its children if it has any\n * Useful for when a user requests a parent topic and wants to see all related content\n */\nexport function expandSubjectWithChildren(subjectId: string): string[] {\n  const children = getSubjectChildren(subjectId);\n  if (children.length > 0) {\n    return [subjectId, ...children];\n  }\n  return [subjectId];\n}\n\n/**\n * Gets all subject IDs in tree order\n */\nexport function getAllSubjectIdsInOrder(): string[] {\n  const ids: string[] = [];\n  for (const node of SUBJECT_TREE) {\n    ids.push(node.id);\n    if (node.children) {\n      ids.push(...node.children);\n    }\n  }\n  return ids;\n}\n","import {\n  getAvailableSubjectIds,\n  loadSubject,\n  loadSubjects,\n  loadAllSubjects,\n  type SubjectInfo,\n  type Subject,\n} from \"./parser\";\nimport { orderSubjects } from \"./subject-tree\";\n\n/**\n * Get basic information about all available subjects\n * @returns Array of subject info (id and title)\n */\nexport function getSubjects(): SubjectInfo[] {\n  const ids = getAvailableSubjectIds();\n  return ids.map((id) => {\n    const subject = loadSubject(id);\n    return {\n      id: subject.id,\n      title: subject.title,\n    };\n  });\n}\n\n/**\n * Get one or more subjects by their IDs\n * @param ids Subject IDs to load\n * @returns Array of complete subject data ordered by the subject tree\n * @example\n * ```ts\n * // Get single subject\n * const [routes] = getSubject(\"defining-routes\");\n *\n * // Get multiple subjects for combined context\n * const [adapters, kysely] = getSubject(\"database-adapters\", \"kysely-adapter\");\n * ```\n */\nexport function getSubject(...ids: string[]): Subject[] {\n  // Order subjects deterministically according to the tree structure\n  const orderedIds = orderSubjects(ids);\n  return loadSubjects(orderedIds);\n}\n\n/**\n * Get all available subjects\n * @returns Array of all subjects with complete data\n */\nexport function getAllSubjects(): Subject[] {\n  return loadAllSubjects();\n}\n\n// Re-export types\nexport type { Subject, SubjectInfo, Example, Section, CodeBlock } from \"./parser.js\";\n\n// Re-export subject tree utilities\nexport {\n  orderSubjects,\n  getSubjectParent,\n  getSubjectChildren,\n  expandSubjectWithChildren,\n  getAllSubjectIdsInOrder,\n} from \"./subject-tree.js\";\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragno-dev/corpus",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -12,15 +12,20 @@
       "default": "./dist/index.js"
     }
   },
+  "files": [
+    "dist"
+  ],
   "devDependencies": {
-    "zod": "^4.0.5",
+    "@types/marked-terminal": "^6.1.1",
     "@types/node": "^22",
     "drizzle-orm": "^0.44.7",
     "kysely": "^0.28.0",
+    "zod": "^4.0.5",
+    "@fragno-dev/core": "0.1.8",
+    "@fragno-dev/db": "0.1.14",
+    "@fragno-dev/test": "0.1.12",
     "@fragno-private/typescript-config": "0.0.1",
-    "@fragno-private/vitest-config": "0.0.0",
-    "@fragno-dev/core": "0.1.6",
-    "@fragno-dev/db": "0.1.12"
+    "@fragno-private/vitest-config": "0.0.0"
   },
   "scripts": {
     "build": "tsdown",

package/.turbo/turbo-build.log

@@ -1,15 +0,0 @@
-
-> @fragno-dev/corpus@0.0.2 build /home/runner/work/fragno/fragno/packages/corpus
-> tsdown
-
-ℹ tsdown v0.15.12 powered by rolldown v1.0.0-beta.45
-ℹ Using tsdown config: /home/runner/work/fragno/fragno/packages/corpus/tsdown.config.ts
-ℹ entry: src/index.ts
-ℹ tsconfig: tsconfig.json
-ℹ Build start
-ℹ dist/index.js        3.84 kB │ gzip: 1.42 kB
-ℹ dist/index.js.map    8.62 kB │ gzip: 2.81 kB
-ℹ dist/index.d.ts.map  0.34 kB │ gzip: 0.22 kB
-ℹ dist/index.d.ts      1.39 kB │ gzip: 0.57 kB
-ℹ 4 files, total: 14.18 kB
-✔ Build complete in 7620ms

package/CHANGELOG.md

@@ -1,7 +0,0 @@
-# @fragno-dev/corpus
-
-## 0.0.2
-
-### Patch Changes
-
-- 27cc540: fix: Corpus dependency issue

package/src/index.test.ts

@@ -1,107 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { getSubjects, getSubject, getAllSubjects } from "./index.js";
-
-describe("corpus API", () => {
-  describe("getSubjects", () => {
-    it("should return array of subject info", () => {
-      const subjects = getSubjects();
-
-      expect(subjects).toBeInstanceOf(Array);
-      expect(subjects.length).toBeGreaterThan(0);
-
-      // Check structure of first subject
-      const first = subjects[0];
-      expect(first).toHaveProperty("id");
-      expect(first).toHaveProperty("title");
-      expect(typeof first.id).toBe("string");
-      expect(typeof first.title).toBe("string");
-    });
-
-    it("should include expected subjects", () => {
-      const subjects = getSubjects();
-      const ids = subjects.map((s) => s.id);
-
-      expect(ids).toContain("defining-routes");
-      expect(ids).toContain("database-querying");
-      expect(ids).toContain("database-adapters");
-      expect(ids).toContain("kysely-adapter");
-      expect(ids).toContain("drizzle-adapter");
-    });
-  });
-
-  describe("getSubject", () => {
-    it("should return single subject when given one id", () => {
-      const [subject] = getSubject("defining-routes");
-
-      expect(subject).toBeDefined();
-      expect(subject.id).toBe("defining-routes");
-      expect(subject.title).toBeTruthy();
-      expect(subject.description).toBeTruthy();
-      expect(subject.imports).toBeTruthy();
-      expect(subject.examples).toBeInstanceOf(Array);
-      expect(subject.examples.length).toBeGreaterThan(0);
-    });
-
-    it("should return multiple subjects when given multiple ids", () => {
-      const subjects = getSubject("database-adapters", "kysely-adapter");
-
-      expect(subjects).toHaveLength(2);
-      expect(subjects[0].id).toBe("database-adapters");
-      expect(subjects[1].id).toBe("kysely-adapter");
-    });
-
-    it("should include examples with code and explanation", () => {
-      const [subject] = getSubject("defining-routes");
-
-      const example = subject.examples[0];
-      expect(example).toHaveProperty("code");
-      expect(example).toHaveProperty("explanation");
-      expect(typeof example.code).toBe("string");
-      expect(typeof example.explanation).toBe("string");
-    });
-  });
-
-  describe("getAllSubjects", () => {
-    it("should return all available subjects", () => {
-      const allSubjects = getAllSubjects();
-      const subjectsList = getSubjects();
-
-      expect(allSubjects).toHaveLength(subjectsList.length);
-    });
-
-    it("should return complete subject data", () => {
-      const allSubjects = getAllSubjects();
-
-      for (const subject of allSubjects) {
-        expect(subject.id).toBeTruthy();
-        expect(subject.title).toBeTruthy();
-        expect(subject.imports).toBeDefined(); // Can be empty string
-        expect(subject.examples).toBeInstanceOf(Array);
-      }
-    });
-  });
-
-  describe("subject content validation", () => {
-    it("defining-routes should have multiple examples", () => {
-      const [subject] = getSubject("defining-routes");
-
-      expect(subject.examples.length).toBeGreaterThan(3);
-      expect(subject.imports).toContain("defineRoute");
-    });
-
-    it("database-querying should have database content", () => {
-      const [subject] = getSubject("database-querying");
-
-      // Database querying examples are currently documentation-only
-      expect(subject.title).toBe("Database Querying");
-      expect(subject.imports).toContain("defineFragnoDatabase");
-    });
-
-    it("database-adapters should have adapter overview", () => {
-      const [subject] = getSubject("database-adapters");
-
-      expect(subject.description).toContain("adapter");
-      expect(subject.imports).toContain("DatabaseAdapter");
-    });
-  });
-});