Skip to content

Commit e028c3d

Browse files
JasonWarrenUKJasonWarrenUK
authored
Merge pull request #29 from foundersandcoders/themis/schema/course-xml-validation
feat(themis): Complete Course XML Export with Embedded Module Specifications (Themis 2.3)
2 parents 4ef5707 + 432f899 commit e028c3d

File tree

13 files changed

+4146
-173
lines changed

13 files changed

+4146
-173
lines changed

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

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

‎docs/dev/features/course-xml-export.md‎

Lines changed: 400 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: 33 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,8 @@
5252
### 2.2. Workflow Modules
5353

5454
#### 2.2.1. Themis: Course Builder
55-
<details><summary>Status: ~95% MVP ✅</summary>
56-
<p>End-to-end workflow complete, component refactoring complete, technical debt identified, polish pending</p>
55+
<details><summary>Status: 100% MVP ✅</summary>
56+
<p>End-to-end workflow complete, component refactoring complete, XML export implemented, polish pending</p>
5757
</details>
5858

5959
<details><summary>Implemented</summary>
@@ -72,18 +72,34 @@
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>✅ <strong>NEW:</strong> Complete course XML export with embedded module specifications</li>
78+
<li>✅ <strong>NEW:</strong> Pre-download validation with user feedback banners</li>
79+
<li>✅ <strong>NEW:</strong> Export button with success/error validation in CourseOverview</li>
7680
<li>📋 Technical debt: SSE parsing vulnerability, race conditions, error handling improvements</li>
7781
</ul>
7882
</details>
7983

8084
<details><summary>Next Up</summary>
8185
<ul>
82-
<li>Course XML schema validation (highest priority)</li>
8386
<li>Technical debt resolution (SSE, error handling)</li>
8487
<li>UI polish improvements</li>
88+
<li>Dark mode implementation</li>
8589
</ul>
8690
</details>
91+
</text>
92+
93+
<old_text line=158>
94+
## 3. Next Milestones
95+
> [!NOTE]
96+
> The 5 most significant or important tasks to tackle next.
97+
98+
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
99+
2. **[Implement XML Export Functionality](Themis-MVP.md#2-mvp-milestones)** (Themis 2.3) - Complete course XML export (depends on 2.2)
100+
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
101+
4. **[Implement Metis boilerplate text insertion](Metis-MVP.md)** - Add standard module text sections for consistent structure
102+
5. **[Address ARIA violations](Rhea-MVP.md#2-mvp-milestones)** (Rhea 2b) - Improve accessibility across all workflow components
87103

88104
#### 2.2.2. Tethys: Arc Designer
89105
<details><summary>Status: 0% MVP</summary>
@@ -211,22 +227,23 @@
211227
> [!NOTE]
212228
> The 5 most significant or important tasks to tackle next.
213229
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
230+
1. **[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
231+
2. **[Implement Metis boilerplate text insertion](Metis-MVP.md)** - Add standard module text sections for consistent structure
232+
3. **[Address ARIA violations](Rhea-MVP.md#2-mvp-milestones)** (Rhea 2b) - Improve accessibility across all workflow components
233+
4. **[Resolve Technical Debt in Themis](Themis-MVP.md#1-tasks)** - Fix SSE parsing vulnerability, race conditions, and error handling gaps
234+
5. **[Implement Module XML Upload in Theia](Theia-MVP.md)** - Upload module XML to continue in Metis or preview/export
219235

220236
---
221237

222238
## 4. Recent Wins
223239
> [!NOTE]
224240
> 7 most recent achievements in this codebase
225241
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)
242+
1. **[Themis: Complete Course XML Export](Themis-MVP.md#2-mvp-milestones)** (2025-10-28) - Implemented complete course XML export with embedded module specifications. Generates validatable XML matching courseSchema.xml, validates before download, and provides user feedback via success/error banners. Export button in CourseOverview with automatic validation. Themis MVP now 100% feature-complete. 575 lines across 3 files: outputSerialiser.ts (rewrite), CourseOverview.svelte (+127 lines), documentation.
243+
2. **[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.
244+
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).
245+
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).
246+
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)
247+
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.
248+
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
249+
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: 25 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -75,20 +75,32 @@
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
85-
- [ ] 2.3. Implement Export Functionality 📋 PENDING
86-
- XML export for complete course
87-
- PDF export option (stretch goal)
88-
- Individual module file exports
89-
- Course metadata inclusion
90-
- **Why twelfth:** Delivers the final product to users
91-
- **Status:** Partially complete - Theia export service operational, needs XML course schema
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
91+
- [x] 2.3. Implement Export Functionality ✅ COMPLETE (2025-10-28)
92+
- ✅ Complete course XML export with embedded module specifications
93+
- ✅ Pre-download validation with user feedback
94+
- ✅ Export button in CourseOverview component with success/error banners
95+
- ✅ Integration with course validator for quality assurance
96+
- ✅ Proper XML structure matching courseSchema.xml hierarchy
97+
- ✅ Temporal metadata and generation provenance tracking
98+
- 📋 PDF export option (stretch goal - future enhancement)
99+
- 📋 Individual module XML file exports (future enhancement)
100+
- **Why twelfth:** Delivers the final product to users in validatable XML format
101+
- **Status:** Complete - Themis MVP now feature-complete
102+
- **Implementation:** 575 lines of new/modified code across 3 files
103+
- **Next Step:** Technical debt resolution and UI polish
92104

93105
---
94106

0 commit comments

Comments
 (0)