Skip to content

Commit c8a33d7

Browse files
JasonWarrenUKJasonWarrenUK
committed
feat(themis): xml schema
1 parent 263369c commit c8a33d7

File tree

8 files changed

+2823
-20
lines changed

8 files changed

+2823
-20
lines changed

‎docs/dev/course-xml-specification.md‎

Lines changed: 411 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/dev/quick-reference-course-xml.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
# Course XML Quick Reference
2+
3+
**Quick guide for validating and working with Themis course XML**
4+
5+
---
6+
7+
## Basic Usage
8+
9+
### Validate Course XML
10+
11+
```typescript
12+
import { validateCourseXML } from '$lib/schemas/courseValidator';
13+
14+
const result = validateCourseXML(xmlString);
15+
// Returns: { valid: boolean, errors: string[], warnings: string[] }
16+
```
17+
18+
### Get Summary
19+
20+
```typescript
21+
import { validateAndSummarize } from '$lib/schemas/courseValidator';
22+
23+
const summary = validateAndSummarize(xmlString);
24+
console.log(summary.summary);
25+
// "✓ Course XML is valid (2 warnings)" or
26+
// "✗ Course XML validation failed (5 errors, 2 warnings)"
27+
```
28+
29+
---
30+
31+
## Minimum Requirements
32+
33+
### Course Level
34+
- ✓ At least 1 arc
35+
- ✓ Structure: `"facilitated"` or `"peer-led"`
36+
- ✓ CourseDescription with ≥1 paragraph
37+
- ✓ CohortProps with prerequisites and experience
38+
39+
### Arc Level
40+
- ✓ At least 1 module per arc
41+
- ✓ Sequential ordering (1, 2, 3...)
42+
- ✓ ArcDescription, ArcProps, ArcContent
43+
44+
### Module Level
45+
- ✓ Sequential ordering within arc
46+
- ✓ ModuleDescription, ModuleProps, ModuleSpecification
47+
48+
### Module Specification
49+
- ✓ Min 3 objectives
50+
- ✓ Min 5 primary research topics
51+
- ✓ Min 2 project briefs (each: 3+ skills, 3+ examples)
52+
- ✓ Min 2 project twists (each: 2+ examples)
53+
- ✓ Min 1 additional skills category
54+
55+
---
56+
57+
## Temporal Consistency
58+
59+
**Rule:** `sum(module weeks) ≤ arc weeks ≤ course weeks`
60+
61+
**Errors when:**
62+
- Arc weeks exceed course weeks
63+
- Module weeks exceed arc weeks
64+
65+
**Warnings when:**
66+
- Sum is less than parent (indicates buffer/flexibility)
67+
68+
---
69+
70+
## Common Validation Errors
71+
72+
| Error | Fix |
73+
|-------|-----|
74+
| `Root element must be <Course>` | Use `<Course>` as root tag |
75+
| `Course must contain at least one <Arc>` | Add at least one arc |
76+
| `module must have at least 3 objectives` | Add more objectives |
77+
| `module must have at least 5 primary research topics` | Add more topics |
78+
| `sum of arc weeks exceeds course total weeks` | Adjust weeks to be consistent |
79+
| `Structure must be "facilitated" or "peer-led"` | Use exact string value |
80+
81+
---
82+
83+
## Error vs Warning
84+
85+
**Errors** (block validation):
86+
- Missing required elements
87+
- Invalid attribute values
88+
- Cardinality violations (too few objectives/topics/etc)
89+
- Temporal inconsistency (child > parent)
90+
91+
**Warnings** (non-blocking):
92+
- Missing optional metadata
93+
- Count attribute mismatch
94+
- Temporal buffer (child < parent)
95+
- Empty/self-closing modules
96+
97+
---
98+
99+
## XML Structure Cheatsheet
100+
101+
```xml
102+
<Course name="" doc_date="" doc_time="" version="1.0">
103+
<CourseProps arcs="" modules="" weeks="" days="">
104+
<CourseMetadata />
105+
<CourseLogistics><TotalArcs/><TotalModules/><Structure/></CourseLogistics>
106+
<CourseTemporal><TotalWeeks/><DaysPerWeek/><TotalDays/></CourseTemporal>
107+
</CourseProps>
108+
<CohortProps learners="">
109+
<CohortAssumptions><AssumedCohortSize/></CohortAssumptions>
110+
<LearnerPrerequisites/>
111+
<LearnerExperience><PrereqLevel/><FocusArea/></LearnerExperience>
112+
</CohortProps>
113+
<CourseDescription><DescriptionParagraph/></CourseDescription>
114+
<CourseContent>
115+
<CourseProgression />
116+
<Arcs>
117+
<Arc order="" name="" modules="" weeks="">
118+
<ArcDescription />
119+
<ArcProps><ArcLogistics/><ArcTemporal/></ArcProps>
120+
<ArcContent>
121+
<Themes><ArcTheme/></Themes>
122+
<ArcProgression />
123+
<Modules>
124+
<Module order="" in_arc="" name="" weeks="">
125+
<ModuleDescription />
126+
<ModuleProps><ModuleTemporal/></ModuleProps>
127+
<ModuleSpecification>
128+
<ModuleOverview><ModuleObjectives/></ModuleOverview>
129+
<ResearchTopics><PrimaryTopics/></ResearchTopics>
130+
<Projects><ProjectBriefs/><ProjectTwists/></Projects>
131+
<AdditionalSkills><SkillsCategory/></AdditionalSkills>
132+
</ModuleSpecification>
133+
</Module>
134+
</Modules>
135+
</ArcContent>
136+
</Arc>
137+
</Arcs>
138+
</CourseContent>
139+
</Course>
140+
```
141+
142+
---
143+
144+
## File Locations
145+
146+
- **Schema Template:** `src/data/templates/themis/courseSchema.xml`
147+
- **Validator:** `src/lib/schemas/courseValidator.ts`
148+
- **Tests:** `src/lib/schemas/courseValidator.test.ts`
149+
- **Full Docs:** `docs/dev/course-xml-specification.md`
150+
151+
---
152+
153+
## Quick Debug Pattern
154+
155+
```typescript
156+
const result = validateCourseXML(xmlString);
157+
158+
if (!result.valid) {
159+
console.error('Validation Errors:');
160+
result.errors.forEach((e, i) => console.error(`${i + 1}. ${e}`));
161+
162+
console.warn('Validation Warnings:');
163+
result.warnings.forEach((w, i) => console.warn(`${i + 1}. ${w}`));
164+
}
165+
```
166+
167+
---
168+
169+
## Self-Closing vs Full Modules
170+
171+
```xml
172+
<!-- Planned but not generated -->
173+
<Module order="1" in_arc="1" name="" weeks="4" />
174+
175+
<!-- Fully generated -->
176+
<Module order="1" in_arc="1" name="Module Title" weeks="4">
177+
<ModuleDescription>...</ModuleDescription>
178+
<ModuleProps>...</ModuleProps>
179+
<ModuleSpecification>...</ModuleSpecification>
180+
</Module>
181+
```
182+
183+
Validator warns on self-closing modules but doesn't error.
184+
185+
---
186+
187+
## Integration Points
188+
189+
**Themis 2.3 (XML Export):**
190+
```typescript
191+
// 1. Serialize course to XML
192+
const xmlString = serialiseCourseToXml(courseData);
193+
194+
// 2. Validate
195+
const validation = validateCourseXML(xmlString);
196+
if (!validation.valid) {
197+
throw new Error('Invalid XML: ' + validation.errors.join(', '));
198+
}
199+
200+
// 3. Download
201+
downloadCourseXml(courseData);
202+
```
203+
204+
**Theia (XML Upload - Future):**
205+
```typescript
206+
// 1. Upload XML file
207+
const xmlString = await file.text();
208+
209+
// 2. Validate
210+
const validation = validateCourseXML(xmlString);
211+
if (!validation.valid) {
212+
showErrors(validation.errors);
213+
return;
214+
}
215+
216+
// 3. Parse and resume workflow
217+
const courseData = parseXmlToCourseData(xmlString);
218+
```
219+
220+
---
221+
222+
## Related Documentation
223+
224+
- **Full Specification:** `docs/dev/course-xml-specification.md`
225+
- **Module XML Schema:** `src/data/templates/metis/outputSchema.xml`
226+
- **Module Validator:** `src/lib/schemas/moduleValidator.ts`
227+
- **Themis Types:** `src/lib/types/themis.ts`

‎docs/dev/roadmap/README.md‎

Lines changed: 28 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -72,18 +72,32 @@
7272
<li>✅ Course-aware module generation API endpoint (193 lines)</li>
7373
<li>✅ Course context integration in prompt factory</li>
7474
<li>✅ CourseOverview component for final review and export (1462 lines)</li>
75-
<li>📋 Course XML schema and export functionality (pending)</li>
75+
<li>✅ <strong>NEW:</strong> Course XML schema and validator (courseSchema.xml, courseValidator.ts)</li>
76+
<li>✅ <strong>NEW:</strong> Comprehensive validation with temporal consistency checks (15 test cases)</li>
77+
<li>📋 Course XML export implementation (depends on schema - now unblocked)</li>
7678
<li>📋 Technical debt: SSE parsing vulnerability, race conditions, error handling improvements</li>
7779
</ul>
7880
</details>
7981

8082
<details><summary>Next Up</summary>
8183
<ul>
82-
<li>Course XML schema validation (highest priority)</li>
84+
<li>Course XML export implementation (now unblocked by schema completion)</li>
8385
<li>Technical debt resolution (SSE, error handling)</li>
8486
<li>UI polish improvements</li>
8587
</ul>
8688
</details>
89+
</text>
90+
91+
<old_text line=158>
92+
## 3. Next Milestones
93+
> [!NOTE]
94+
> The 5 most significant or important tasks to tackle next.
95+
96+
1. **[Add Course XML Schema and Validator](Themis-MVP.md#2-mvp-milestones)** (Themis 2.2) - Define course-level XML schema wrapping multiple modules with validation
97+
2. **[Implement XML Export Functionality](Themis-MVP.md#2-mvp-milestones)** (Themis 2.3) - Complete course XML export (depends on 2.2)
98+
3. **[Add Dark Mode to UI](Rhea-MVP.md#1a2-other-tasks)** (Rhea 1a2b) - User-selectable light/dark/system theme with dark palettes for all workflows
99+
4. **[Implement Metis boilerplate text insertion](Metis-MVP.md)** - Add standard module text sections for consistent structure
100+
5. **[Address ARIA violations](Rhea-MVP.md#2-mvp-milestones)** (Rhea 2b) - Improve accessibility across all workflow components
87101

88102
#### 2.2.2. Tethys: Arc Designer
89103
<details><summary>Status: 0% MVP</summary>
@@ -211,22 +225,22 @@
211225
> [!NOTE]
212226
> The 5 most significant or important tasks to tackle next.
213227
214-
1. **[Add Course XML Schema and Validator](Themis-MVP.md#2-mvp-milestones)** (Themis 2.2) - Define course-level XML schema wrapping multiple modules with validation
215-
2. **[Implement XML Export Functionality](Themis-MVP.md#2-mvp-milestones)** (Themis 2.3) - Complete course XML export (depends on 2.2)
216-
3. **[Add Dark Mode to UI](Rhea-MVP.md#1a2-other-tasks)** (Rhea 1a2b) - User-selectable light/dark/system theme with dark palettes for all workflows
217-
4. **[Implement Metis boilerplate text insertion](Metis-MVP.md)** - Add standard module text sections for consistent structure
218-
5. **[Address ARIA violations](Rhea-MVP.md#2-mvp-milestones)** (Rhea 2b) - Improve accessibility across all workflow components
228+
1. **[Implement XML Export Functionality](Themis-MVP.md#2-mvp-milestones)** (Themis 2.3) - Complete course XML export with embedded module specifications (unblocked by 2.2 completion)
229+
2. **[Add Dark Mode to UI](Rhea-MVP.md#1a2-other-tasks)** (Rhea 1a2b) - User-selectable light/dark/system theme with dark palettes for all workflows
230+
3. **[Implement Metis boilerplate text insertion](Metis-MVP.md)** - Add standard module text sections for consistent structure
231+
4. **[Address ARIA violations](Rhea-MVP.md#2-mvp-milestones)** (Rhea 2b) - Improve accessibility across all workflow components
232+
5. **[Resolve Technical Debt in Themis](Themis-MVP.md#1-tasks)** - Fix SSE parsing vulnerability, race conditions, and error handling gaps
219233

220234
---
221235

222236
## 4. Recent Wins
223237
> [!NOTE]
224238
> 7 most recent achievements in this codebase
225239
226-
1. **[Themis: Module Coherence with Overview-First Generation](Themis-MVP.md#412-radically-improve-module-to-module-coherence--completed-2025-10-2728)** (2025-10-27/28) - Implemented two-phase workflow: smart title system (undefined/prompt/literal modes) and lightweight module overviews before full generation. Knowledge context builder tracks learner progression cumulatively, reducing content repetition. Review 10 overviews in ~5min vs 10 full modules in ~20min. 1,479 insertions across 21 files (PR #27).
227-
2. **[British English & Emoji Cleanup](Rhea-MVP.md#4a3-british-english--emoji-cleanup--completed-2025-10-28)** (2025-10-28) - Added British English instructions to all prompt factories (Metis standalone, course-aware, overview; Themis structure). Removed emoji from build scripts. All AI-generated content now uses British spelling/terminology consistently (49 lines changed, zero breaking changes).
228-
3. **[Roadmap Maintenance & Technical Debt Documentation](README.md)** (2025-10-28) - Updated all active roadmaps with current task status, moved completed items to work record (timeout extraction, UI improvements, component organization), documented remaining technical debt in Themis (SSE parsing vulnerability, race conditions, error handling gaps)
229-
4. **[Themis: Component Refactoring Complete](Themis-MVP.md#411-break-over-large-themis-components-into-subcomponents--completed-2025-10-27)** (2025-10-27) - Split 896-line ModuleGenerationList into focused components (ProgressSummary, ModuleCard, ArcSection, ModulePreviewModal) and centralized store utilities. Main component reduced 51%, improved maintainability and testability.
230-
5. **[Themis: Complete Module Generation Workflow](Themis-MVP.md#4111-complete-module-generation-workflow-steps-5-6--completed-2025-10-25)** (2025-10-25) - End-to-end course generation complete: ModuleGenerationList (897 lines), course-aware API endpoint (193 lines), CourseOverview (1462 lines), SSE streaming, and Theia export integration
231-
6. **[Rhea: Palette System Overhaul](Rhea-MVP.md#4a2-overhaul-palette-system--completed-2025-10-25)** (2025-10-25) - Complete refactor establishing single source of truth at `src/lib/config/palettes/`, build-time CSS generation, 56 files converted, 2,817 insertions
232-
7. **[Theia: Course Structure Upload (JSON)](Theia-MVP.md#412-course-structure-upload-json--completed-2025-10-24)** (2025-10-24) - Complete JSON upload workflow with validation, drag-and-drop interface, and round-trip capability (Themis → export → upload → continue). Theia branding with magenta/cyan palette (2,417 lines)
240+
1. **[Themis: Course XML Schema and Validator](Themis-MVP.md#2-mvp-milestones)** (2025-10-28) - Created comprehensive course XML schema with hierarchical structure (Course → Arcs → Modules → Specifications). Implemented validator with temporal consistency checks, cardinality constraints, and 15 test cases. Validates complete courses including embedded module specifications. 1,652 lines across 4 files: schema template, validator, tests, and documentation. Task 2.2 complete, unblocks XML export implementation.
241+
2. **[Themis: Module Coherence with Overview-First Generation](Themis-MVP.md#412-radically-improve-module-to-module-coherence--completed-2025-10-2728)** (2025-10-27/28) - Implemented two-phase workflow: smart title system (undefined/prompt/literal modes) and lightweight module overviews before full generation. Knowledge context builder tracks learner progression cumulatively, reducing content repetition. Review 10 overviews in ~5min vs 10 full modules in ~20min. 1,479 insertions across 21 files (PR #27).
242+
3. **[British English & Emoji Cleanup](Rhea-MVP.md#4a3-british-english--emoji-cleanup--completed-2025-10-28)** (2025-10-28) - Added British English instructions to all prompt factories (Metis standalone, course-aware, overview; Themis structure). Removed emoji from build scripts. All AI-generated content now uses British spelling/terminology consistently (49 lines changed, zero breaking changes).
243+
4. **[Roadmap Maintenance & Technical Debt Documentation](README.md)** (2025-10-28) - Updated all active roadmaps with current task status, moved completed items to work record (timeout extraction, UI improvements, component organization), documented remaining technical debt in Themis (SSE parsing vulnerability, race conditions, error handling gaps)
244+
5. **[Themis: Component Refactoring Complete](Themis-MVP.md#411-break-over-large-themis-components-into-subcomponents--completed-2025-10-27)** (2025-10-27) - Split 896-line ModuleGenerationList into focused components (ProgressSummary, ModuleCard, ArcSection, ModulePreviewModal) and centralized store utilities. Main component reduced 51%, improved maintainability and testability.
245+
6. **[Themis: Complete Module Generation Workflow](Themis-MVP.md#4111-complete-module-generation-workflow-steps-5-6--completed-2025-10-25)** (2025-10-25) - End-to-end course generation complete: ModuleGenerationList (897 lines), course-aware API endpoint (193 lines), CourseOverview (1462 lines), SSE streaming, and Theia export integration
246+
7. **[Rhea: Palette System Overhaul](Rhea-MVP.md#4a2-overhaul-palette-system--completed-2025-10-25)** (2025-10-25) - Complete refactor establishing single source of truth at `src/lib/config/palettes/`, build-time CSS generation, 56 files converted, 2,817 insertions

‎docs/dev/roadmap/Themis-MVP.md‎

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -75,13 +75,19 @@
7575

7676
## 2. MVP Milestones
7777

78-
- [ ] 2.2. Add Course XML Schema and Validator 📋 PENDING
79-
- Define course-level XML schema wrapping multiple modules
80-
- Validation for complete course structure
81-
- Include course narratives and metadata
78+
- [x] 2.2. Add Course XML Schema and Validator ✅ COMPLETE (2025-10-28)
79+
- ✅ Comprehensive course XML schema template (`courseSchema.xml`)
80+
- ✅ Hierarchical structure: Course → Arcs → Modules → Module Specifications
81+
- ✅ Full course validator with temporal consistency checks (`courseValidator.ts`)
82+
- ✅ 15 comprehensive test cases covering all validation requirements
83+
- ✅ Complete documentation (`course-xml-specification.md`)
84+
- ✅ Validates course metadata, arc organization, and embedded module specs
85+
- ✅ Enforces cardinality constraints (min arcs, modules, objectives, topics, etc.)
86+
- ✅ Validates temporal consistency (module weeks ≤ arc weeks ≤ course weeks)
8287
- **Why eleventh:** Ensures exported courses meet quality standards
83-
- **Status:** Not yet started - will reuse existing validation patterns
84-
- **Note:** Current export uses Theia service which handles course-to-markdown/HTML conversion
88+
- **Status:** Complete - ready for use in XML export implementation (Task 2.3)
89+
- **Implementation:** 1,652 lines across 4 files (schema, validator, tests, docs)
90+
- **Next Step:** Integrate with course export functionality in Task 2.3
8591
- [ ] 2.3. Implement Export Functionality 📋 PENDING
8692
- XML export for complete course
8793
- PDF export option (stretch goal)

0 commit comments

Comments
 (0)