@fragno-dev/corpus 0.0.3 → 0.0.5

package/dist/index.d.ts

@@ -14,6 +14,7 @@ interface Example {
   explanation: string;
   testName?: string;
   id?: string;
+  typesOnly?: boolean;
 }
 /**
  * A code block with optional ID
@@ -50,7 +51,7 @@ interface Subject {
  */
 declare function getSubjectParent(subjectId: string): string | null;
 /**
- * Gets the children of a subject
+ * Gets the direct children of a subject
  */
 declare function getSubjectChildren(subjectId: string): string[];
 /**
@@ -59,14 +60,22 @@ declare function getSubjectChildren(subjectId: string): string[];
  */
 declare function orderSubjects(subjectIds: string[]): string[];
 /**
- * Expands a subject ID to include its children if it has any
+ * Expands a subject ID to include all its descendants recursively
  * 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
+ * Gets all subject IDs in tree order (depth-first traversal)
  */
 declare function getAllSubjectIdsInOrder(): string[];
+/**
+ * Checks if a subject ID is a category (has no markdown file)
+ */
+declare function isCategory(subjectId: string): boolean;
+/**
+ * Gets the category title for display purposes
+ */
+declare function getCategoryTitle(categoryId: string): string;
 //#endregion
 //#region src/index.d.ts
 /**
@@ -94,5 +103,5 @@ declare function getSubject(...ids: string[]): Subject[];
  */
 declare function getAllSubjects(): Subject[];
 //#endregion
-export { type CodeBlock, type Example, type Section, type Subject, type SubjectInfo, expandSubjectWithChildren, getAllSubjectIdsInOrder, getAllSubjects, getSubject, getSubjectChildren, getSubjectParent, getSubjects, orderSubjects };
+export { type CodeBlock, type Example, type Section, type Subject, type SubjectInfo, expandSubjectWithChildren, getAllSubjectIdsInOrder, getAllSubjects, getCategoryTitle, getSubject, getSubjectChildren, getSubjectParent, getSubjects, isCategory, orderSubjects };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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;;;;ECPH,EAAA,CAAA,EAAA,MAAA;AAOhB;AASA;AAYA;AAWA;UDzDiB,SAAA;;;AEdjB;AAwBA;AAUA;;UFZiB,OAAA;;;;;;;;UASA,OAAA;;;;;WAKN;YACC;YACA;YACA;;;;;;;AAAO,iBCPH,gBAAA,CDOG,SAAA,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,IAAA;;;;ACPH,iBAOA,kBAAA,CAPgB,SAAA,EAAA,MAAA,CAAA,EAAA,MAAA,EAAA;AAOhC;AASA;AAYA;AAWA;iBAvBgB,aAAA;;;AChDhB;AAwBA;AAUgB,iBD0BA,yBAAA,CC1ByB,SAAA,EAAA,MAAA,CAAA,EAAA,MAAA,EAAA;;;;iBDqCzB,uBAAA,CAAA;;;AD3EhB;AAQA;AAUA;AAQA;AASiB,iBE/BD,WAAA,CAAA,CF+BQ,EE/BO,WF+BP,EAAA;;;;;;;;;ACCxB;AAOA;AASA;AAYA;AAWA;iBC/CgB,UAAA,oBAA8B;;;AAxB9C;AAwBA;AAUgB,iBAAA,cAAA,CAAA,CAAyB,EAAP,OAAO,EAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/parser.ts","../src/subject-tree.ts","../src/index.ts"],"sourcesContent":[],"mappings":";;AAcA;AAQA;AAWiB,UAnBA,WAAA,CAmBS;EAQT,EAAA,EAAA,MAAO;EASP,KAAA,EAAA,MAAO;;;;;AAQL,UApCF,OAAA,CAoCE;;;;ECuBH,EAAA,CAAA,EAAA,MAAA;EAOA,SAAA,CAAA,EAAA,OAAA;AAQhB;AAYA;AAoBA;AAsBA;AAOgB,UD5HC,SAAA,CC4He;;;;AC/IhC;AA6BA;AAUA;UFZiB,OAAA;;;;;;;;UASA,OAAA;;;;;WAKN;YACC;YACA;YACA;;;;;;;iBCuBI,gBAAA;;AAAhB;AAOA;AAQgB,iBARA,kBAAA,CAQa,SAAA,EAAA,MAAA,CAAA,EAAA,MAAA,EAAA;AAY7B;AAoBA;AAsBA;AAOA;iBA7DgB,aAAA;;;AClFhB;AA6BA;AAUgB,iBDuDA,yBAAA,CCvDyB,SAAA,EAAA,MAAA,CAAA,EAAA,MAAA,EAAA;;;;iBD2EzB,uBAAA,CAAA;;;;iBAsBA,UAAA;;;;iBAOA,gBAAA;;;AD/IhB;AAQA;AAWA;AAQA;AASiB,iBEpCD,WAAA,CAAA,CFoCQ,EEpCO,WFoCP,EAAA;;;;;;;;;AC+BxB;AAOA;AAQA;AAYA;AAoBA;AAsBgB,iBC3GA,UAAA,CD2GU,GAAA,GAAA,EAAA,MAAA,EAAA,CAAA,EC3GoB,OD2GpB,EAAA;AAO1B;;;;AC/IgB,iBAuCA,cAAA,CAAA,CAvCe,EAuCG,OAvCQ,EAAA"}

package/dist/index.js

@@ -1,18 +1,130 @@
-import { readFileSync, readdirSync } from "node:fs";
+import { existsSync, 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");
+//#region src/subject-tree.ts
+/**
+* Tree structure defining subject hierarchy and ordering
+* - Root-level subjects are listed in order
+* - Children can be arbitrarily nested
+* - Organized by audience: users, fragment authors, and general topics
+*/
+const SUBJECT_TREE = [
+	{
+		id: "for-users",
+		category: true,
+		children: [{ id: "fragment-instantiation" }, { id: "client-state-management" }]
+	},
+	{
+		id: "for-fragment-authors",
+		category: true,
+		children: [
+			{ id: "defining-routes" },
+			{ id: "fragment-services" },
+			{ id: "database-querying" },
+			{
+				id: "database-adapters",
+				children: [{ id: "kysely-adapter" }, { id: "drizzle-adapter" }]
+			}
+		]
+	},
+	{
+		id: "general",
+		category: true,
+		children: []
+	}
+];
+/**
+* Flattened map of all subjects and their parent relationships
+*/
+const SUBJECT_PARENT_MAP = /* @__PURE__ */ new Map();
+const SUBJECT_ORDER_MAP = /* @__PURE__ */ new Map();
+const SUBJECT_CHILDREN_MAP = /* @__PURE__ */ new Map();
+const SUBJECT_CATEGORY_MAP = /* @__PURE__ */ new Map();
+/**
+* Recursively processes a node and its children, building parent/order/category maps
+*/
+function processNode(node, parent, orderIndexRef$1) {
+	SUBJECT_PARENT_MAP.set(node.id, parent);
+	SUBJECT_ORDER_MAP.set(node.id, orderIndexRef$1.value++);
+	if (node.category) SUBJECT_CATEGORY_MAP.set(node.id, true);
+	if (node.children) {
+		const childIds = node.children.map((child) => child.id);
+		SUBJECT_CHILDREN_MAP.set(node.id, childIds);
+		for (const childNode of node.children) processNode(childNode, node.id, orderIndexRef$1);
+	}
+}
+const orderIndexRef = { value: 0 };
+for (const node of SUBJECT_TREE) processNode(node, null, orderIndexRef);
+/**
+* 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 direct children of a subject
+*/
+function getSubjectChildren(subjectId) {
+	return SUBJECT_CHILDREN_MAP.get(subjectId) ?? [];
+}
+/**
+* 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 all its descendants recursively
+* Useful for when a user requests a parent topic and wants to see all related content
+*/
+function expandSubjectWithChildren(subjectId) {
+	const result = [subjectId];
+	function collectDescendants(id) {
+		const children = SUBJECT_CHILDREN_MAP.get(id);
+		if (children) for (const childId of children) {
+			result.push(childId);
+			collectDescendants(childId);
+		}
 	}
-})();
+	collectDescendants(subjectId);
+	return result;
+}
+/**
+* Gets all subject IDs in tree order (depth-first traversal)
+*/
+function getAllSubjectIdsInOrder() {
+	const ids = [];
+	function traverse(node) {
+		ids.push(node.id);
+		if (node.children) for (const childNode of node.children) traverse(childNode);
+	}
+	for (const node of SUBJECT_TREE) traverse(node);
+	return ids;
+}
+/**
+* Checks if a subject ID is a category (has no markdown file)
+*/
+function isCategory(subjectId) {
+	return SUBJECT_CATEGORY_MAP.get(subjectId) ?? false;
+}
+/**
+* Gets the category title for display purposes
+*/
+function getCategoryTitle(categoryId) {
+	return {
+		"for-users": "For Users",
+		"for-fragment-authors": "For Fragment Authors",
+		general: "General"
+	}[categoryId] ?? categoryId;
+}
+
+//#endregion
+//#region src/parser.ts
+const SUBJECTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "subjects");
 /**
 * Helper function to extract code blocks with optional IDs from a directive
 */
@@ -40,21 +152,23 @@ function parseMarkdownFile(content) {
 	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 testBlockRegex = /```typescript @fragno-test(?::(\w+(?:-\w+)*))?\s*(types-only)?\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 typesOnly = match[2] === "types-only";
+		const code = match[3].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();
+		const explanation = match[4].split(/```/)[0].trim();
 		testBlocks.push({
 			code,
 			explanation,
 			testName,
-			id
+			id,
+			typesOnly
 		});
 	}
 	const descriptionMatch = content.substring(content.indexOf(title) + title.length).match(/\n\n([\s\S]*?)(?=```|##|$)/);
@@ -92,7 +206,8 @@ function markdownToSubject(id, parsed) {
 		code: block.code,
 		explanation: block.explanation,
 		testName: block.testName,
-		id: block.id
+		id: block.id,
+		typesOnly: block.typesOnly
 	}));
 	return {
 		id,
@@ -107,9 +222,13 @@ function markdownToSubject(id, parsed) {
 }
 /**
 * Loads and parses a subject file by ID
+* Returns null for category nodes (which have no markdown file)
 */
 function loadSubject(id) {
-	return markdownToSubject(id, parseMarkdownFile(readFileSync(join(SUBJECTS_DIR, `${id}.md`), "utf-8")));
+	if (isCategory(id)) return null;
+	const filePath = join(SUBJECTS_DIR, `${id}.md`);
+	if (!existsSync(filePath)) throw new Error(`Subject file not found: ${filePath}`);
+	return markdownToSubject(id, parseMarkdownFile(readFileSync(filePath, "utf-8")));
 }
 /**
 * Gets all available subject IDs from the subjects directory
@@ -119,9 +238,10 @@ function getAvailableSubjectIds() {
 }
 /**
 * Loads multiple subjects by their IDs
+* Skips category nodes (which have no markdown files)
 */
 function loadSubjects(ids) {
-	return ids.map((id) => loadSubject(id));
+	return ids.map((id) => loadSubject(id)).filter((s) => s !== null);
 }
 /**
 * Loads all available subjects
@@ -130,77 +250,6 @@ 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: "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
 /**
@@ -210,11 +259,12 @@ function getAllSubjectIdsInOrder() {
 function getSubjects() {
 	return getAvailableSubjectIds().map((id) => {
 		const subject = loadSubject(id);
+		if (!subject) return null;
 		return {
 			id: subject.id,
 			title: subject.title
 		};
-	});
+	}).filter((s) => s !== null);
 }
 /**
 * Get one or more subjects by their IDs
@@ -241,5 +291,5 @@ function getAllSubjects() {
 }
 
 //#endregion
-export { expandSubjectWithChildren, getAllSubjectIdsInOrder, getAllSubjects, getSubject, getSubjectChildren, getSubjectParent, getSubjects, orderSubjects };
+export { expandSubjectWithChildren, getAllSubjectIdsInOrder, getAllSubjects, getCategoryTitle, getSubject, getSubjectChildren, getSubjectParent, getSubjects, isCategory, orderSubjects };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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: \"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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"}
+{"version":3,"file":"index.js","names":["SUBJECT_TREE: SubjectNode[]","orderIndexRef","result: string[]","ids: string[]","blocks: CodeBlock[]","testBlocks: Array<{\n    code: string;\n    explanation: string;\n    testName?: string;\n    id?: string;\n    typesOnly?: boolean;\n  }>","testName: string | undefined","sections: Section[]","match","examples: Example[]"],"sources":["../src/subject-tree.ts","../src/parser.ts","../src/index.ts"],"sourcesContent":["/**\n * Subject tree structure defining relationships and ordering\n */\n\nexport interface SubjectNode {\n  id: string;\n  children?: SubjectNode[];\n  /** If true, this is a category node without a markdown file */\n  category?: boolean;\n}\n\n/**\n * Tree structure defining subject hierarchy and ordering\n * - Root-level subjects are listed in order\n * - Children can be arbitrarily nested\n * - Organized by audience: users, fragment authors, and general topics\n */\nconst SUBJECT_TREE: SubjectNode[] = [\n  {\n    id: \"for-users\",\n    category: true,\n    children: [{ id: \"fragment-instantiation\" }, { id: \"client-state-management\" }],\n  },\n  {\n    id: \"for-fragment-authors\",\n    category: true,\n    children: [\n      { id: \"defining-routes\" },\n      { id: \"fragment-services\" },\n      { id: \"database-querying\" },\n      {\n        id: \"database-adapters\",\n        children: [{ id: \"kysely-adapter\" }, { id: \"drizzle-adapter\" }],\n      },\n    ],\n  },\n  {\n    id: \"general\",\n    category: true,\n    children: [],\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>();\nconst SUBJECT_CHILDREN_MAP = new Map<string, string[]>();\nconst SUBJECT_CATEGORY_MAP = new Map<string, boolean>();\n\n/**\n * Recursively processes a node and its children, building parent/order/category maps\n */\nfunction processNode(node: SubjectNode, parent: string | null, orderIndexRef: { value: number }) {\n  SUBJECT_PARENT_MAP.set(node.id, parent);\n  SUBJECT_ORDER_MAP.set(node.id, orderIndexRef.value++);\n\n  if (node.category) {\n    SUBJECT_CATEGORY_MAP.set(node.id, true);\n  }\n\n  if (node.children) {\n    const childIds = node.children.map((child) => child.id);\n    SUBJECT_CHILDREN_MAP.set(node.id, childIds);\n\n    for (const childNode of node.children) {\n      processNode(childNode, node.id, orderIndexRef);\n    }\n  }\n}\n\n// Build the parent and order maps\nconst orderIndexRef = { value: 0 };\nfor (const node of SUBJECT_TREE) {\n  processNode(node, null, orderIndexRef);\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 direct children of a subject\n */\nexport function getSubjectChildren(subjectId: string): string[] {\n  return SUBJECT_CHILDREN_MAP.get(subjectId) ?? [];\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 all its descendants recursively\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 result: string[] = [subjectId];\n\n  function collectDescendants(id: string) {\n    const children = SUBJECT_CHILDREN_MAP.get(id);\n    if (children) {\n      for (const childId of children) {\n        result.push(childId);\n        collectDescendants(childId);\n      }\n    }\n  }\n\n  collectDescendants(subjectId);\n  return result;\n}\n\n/**\n * Gets all subject IDs in tree order (depth-first traversal)\n */\nexport function getAllSubjectIdsInOrder(): string[] {\n  const ids: string[] = [];\n\n  function traverse(node: SubjectNode) {\n    ids.push(node.id);\n    if (node.children) {\n      for (const childNode of node.children) {\n        traverse(childNode);\n      }\n    }\n  }\n\n  for (const node of SUBJECT_TREE) {\n    traverse(node);\n  }\n\n  return ids;\n}\n\n/**\n * Checks if a subject ID is a category (has no markdown file)\n */\nexport function isCategory(subjectId: string): boolean {\n  return SUBJECT_CATEGORY_MAP.get(subjectId) ?? false;\n}\n\n/**\n * Gets the category title for display purposes\n */\nexport function getCategoryTitle(categoryId: string): string {\n  const titles: Record<string, string> = {\n    \"for-users\": \"For Users\",\n    \"for-fragment-authors\": \"For Fragment Authors\",\n    general: \"General\",\n  };\n  return titles[categoryId] ?? categoryId;\n}\n","import { readFileSync, readdirSync, existsSync } from \"node:fs\";\nimport { join, basename, dirname } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { isCategory } from \"./subject-tree.js\";\n\n// __filename will be:\n// - In development: /path/to/packages/corpus/src/parser.ts\n// - In production: /path/to/node_modules/@fragno-dev/corpus/dist/parser.js\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  typesOnly?: boolean;\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    typesOnly?: boolean;\n  }>;\n  sections: Section[];\n}\n\n// SUBJECTS_DIR resolution:\n// - In development: join(__dirname, \"subjects\") = /path/to/packages/corpus/src/subjects\n// - In production: join(__dirname, \"subjects\") = /path/to/node_modules/@fragno-dev/corpus/dist/subjects\n//\n// The tsdown build copies src/subjects/ to dist/subjects/, ensuring the directory exists in both cases.\nconst SUBJECTS_DIR = join(__dirname, \"subjects\");\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  // Pattern: ```typescript @fragno-test[:id] [types-only]\n  const testBlockRegex =\n    /```typescript @fragno-test(?::(\\w+(?:-\\w+)*))?\\s*(types-only)?\\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    typesOnly?: boolean;\n  }> = [];\n\n  let match;\n  while ((match = testBlockRegex.exec(content)) !== null) {\n    const id = match[1] || undefined;\n    const typesOnly = match[2] === \"types-only\";\n    const code = match[3].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[4];\n    const explanation = afterBlock\n      .split(/```/)[0] // Stop at next code block\n      .trim();\n\n    testBlocks.push({ code, explanation, testName, id, typesOnly });\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    typesOnly: block.typesOnly,\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 * Returns null for category nodes (which have no markdown file)\n */\nexport function loadSubject(id: string): Subject | null {\n  // Categories don't have markdown files\n  if (isCategory(id)) {\n    return null;\n  }\n\n  const filePath = join(SUBJECTS_DIR, `${id}.md`);\n\n  // Check if file exists before trying to read\n  if (!existsSync(filePath)) {\n    throw new Error(`Subject file not found: ${filePath}`);\n  }\n\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 * Skips category nodes (which have no markdown files)\n */\nexport function loadSubjects(ids: string[]): Subject[] {\n  return ids.map((id) => loadSubject(id)).filter((s): s is Subject => s !== null);\n}\n\n/**\n * Loads all available subjects\n */\nexport function loadAllSubjects(): Subject[] {\n  const ids = getAvailableSubjectIds();\n  return loadSubjects(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\n    .map((id) => {\n      const subject = loadSubject(id);\n      if (!subject) {\n        return null;\n      }\n      return {\n        id: subject.id,\n        title: subject.title,\n      };\n    })\n    .filter((s): s is SubjectInfo => s !== null);\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  isCategory,\n  getCategoryTitle,\n} from \"./subject-tree.js\";\n"],"mappings":"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"}