Merge pull request 'Knowledge graph table view met sort, group en bulk edit' (#11) from fix/issue-10-knowledge-graph-bulk-changes into main

Reviewed-on: #11

src/components/admin/KnowledgeGraph.jsx

@@ -3,9 +3,11 @@ import * as d3 from 'd3';
 import * as db from '../../lib/db';
 import { callLLM } from '../../lib/llm';
 import { EMIT_GRAPH_ACTIONS_TOOL } from '../../lib/llmTools';
+import { Network, Table2 } from 'lucide-react';
 import { useGraphData } from '../../hooks/useGraphData';
 import GraphControls from './graph/GraphControls';
 import NodeDetailPanel from './graph/NodeDetailPanel';
+import GraphTable from './graph/GraphTable';
 
 // ── Edge visual style per relation type ────────────────────────────────────────
 // stroke — line colour
@@ -72,10 +74,11 @@ const KnowledgeGraph = () => {
   const [isAnalyzing, setIsAnalyzing] = useState(false);
   const [analyzeError, setAnalyzeError] = useState(null);
   const [isRestoring, setIsRestoring] = useState(false);
+  const [viewMode, setViewMode] = useState('graph'); // 'graph' | 'table'
 
   const {
     topics, relations, snapshotMeta,
-    reload, updateTopic, deleteTopic, addRelation, removeRelation, bulkSave, restoreSnapshot,
+    reload, updateTopic, bulkUpdateTopics, deleteTopic, addRelation, removeRelation, bulkSave, restoreSnapshot,
   } = useGraphData();
 
   // ── Canvas sizing ────────────────────────────────────────────────────────────
@@ -94,6 +97,7 @@ const KnowledgeGraph = () => {
   // ── D3 force graph ───────────────────────────────────────────────────────────
 
   useEffect(() => {
+    if (viewMode !== 'graph') return;
     if (!svgRef.current || topics.length === 0) return;
 
     const { width, height } = dimensions;
@@ -236,7 +240,7 @@ const KnowledgeGraph = () => {
     });
 
     return () => simulation.stop();
-  }, [dimensions, topics, relations, showExcludeNodes]);
+  }, [dimensions, topics, relations, showExcludeNodes, viewMode]);
 
   // ── Pan/zoom canvas to a node ────────────────────────────────────────────────
 
@@ -396,17 +400,58 @@ const KnowledgeGraph = () => {
 
   return (
     <div className="relative w-full h-full flex flex-col md:flex-row">
-      {/* D3 canvas */}
+      {/* Main view: graph canvas or table */}
-      <div
+      <div className="flex-1 flex flex-col border-r border-bg-warm min-w-0">
-        ref={wrapperRef}
+        {/* View-mode toggle */}
-        className="flex-1 h-[400px] md:h-full cursor-grab active:cursor-grabbing border-r border-bg-warm"
+        <div className="flex items-center gap-1 px-3 py-2 border-b border-bg-warm bg-paper">
-      >
+          <button
-        {topics.length === 0 ? (
+            onClick={() => setViewMode('graph')}
-          <div className="h-full flex items-center justify-center text-fg-muted p-8 text-center">
+            className={`flex items-center gap-1.5 px-3 py-1 text-xs rounded-[var(--r-sm)] transition-colors ${
-            No knowledge graph data yet. Upload source material in the Sources tab first.
+              viewMode === 'graph' ? 'bg-bg-warm text-teal font-medium' : 'text-fg-muted hover:bg-bg-warm/50'
+            }`}
+            title="Force-directed graph view"
+          >
+            <Network size={13} /> Graph
+          </button>
+          <button
+            onClick={() => setViewMode('table')}
+            className={`flex items-center gap-1.5 px-3 py-1 text-xs rounded-[var(--r-sm)] transition-colors ${
+              viewMode === 'table' ? 'bg-bg-warm text-teal font-medium' : 'text-fg-muted hover:bg-bg-warm/50'
+            }`}
+            title="Sortable table with bulk edit"
+          >
+            <Table2 size={13} /> Table
+          </button>
+        </div>
+
+        {viewMode === 'graph' ? (
+          <div
+            ref={wrapperRef}
+            className="flex-1 h-[400px] md:h-full cursor-grab active:cursor-grabbing"
+          >
+            {topics.length === 0 ? (
+              <div className="h-full flex items-center justify-center text-fg-muted p-8 text-center">
+                No knowledge graph data yet. Upload source material in the Sources tab first.
+              </div>
+            ) : (
+              <svg ref={svgRef} className="w-full h-full" />
+            )}
           </div>
         ) : (
-          <svg ref={svgRef} className="w-full h-full" />
+          <div className="flex-1 min-h-[400px] overflow-hidden">
+            {topics.length === 0 ? (
+              <div className="h-full flex items-center justify-center text-fg-muted p-8 text-center">
+                No knowledge graph data yet. Upload source material in the Sources tab first.
+              </div>
+            ) : (
+              <GraphTable
+                topics={topics}
+                relations={relations}
+                onBulkUpdate={bulkUpdateTopics}
+                onSelectNode={setSelectedNode}
+              />
+            )}
+          </div>
         )}
       </div>
 

src/components/admin/graph/GraphTable.jsx

@@ -0,0 +1,466 @@
+import { useMemo, useState } from 'react';
+import { ArrowUp, ArrowDown, ArrowUpDown, X, Search, ChevronRight, ChevronDown, Lock, Unlock } from 'lucide-react';
+import Button from '../../ui/Button';
+
+const TYPES = ['concept', 'role', 'process'];
+const RELEVANCE = ['core', 'standard', 'peripheral', 'exclude'];
+
+const SORTABLE = ['label', 'type', 'learning_relevance', 'theme', 'complexity_weight', 'difficulty', 'relations'];
+
+const GROUP_OPTIONS = [
+  { value: 'none',                label: 'No grouping' },
+  { value: 'type',                label: 'Type' },
+  { value: 'learning_relevance',  label: 'Relevance' },
+  { value: 'theme',               label: 'Theme' },
+  { value: 'difficulty',          label: 'Difficulty' },
+];
+
+const RELEVANCE_RANK = { core: 0, standard: 1, peripheral: 2, exclude: 3 };
+const DIFFICULTY_RANK = { beginner: 0, intermediate: 1, advanced: 2 };
+
+function compareValues(a, b, key) {
+  if (key === 'learning_relevance') {
+    return (RELEVANCE_RANK[a] ?? 99) - (RELEVANCE_RANK[b] ?? 99);
+  }
+  if (key === 'difficulty') {
+    return (DIFFICULTY_RANK[a] ?? 99) - (DIFFICULTY_RANK[b] ?? 99);
+  }
+  if (typeof a === 'number' && typeof b === 'number') return a - b;
+  return String(a ?? '').localeCompare(String(b ?? ''), undefined, { sensitivity: 'base' });
+}
+
+function SortIcon({ active, dir }) {
+  if (!active) return <ArrowUpDown size={11} className="text-fg-muted/60 inline-block ml-1" />;
+  return dir === 'asc'
+    ? <ArrowUp size={11} className="text-teal inline-block ml-1" />
+    : <ArrowDown size={11} className="text-teal inline-block ml-1" />;
+}
+
+/**
+ * Table view of the knowledge graph.
+ *
+ * Supports sort (per column), grouping (per key), free-text label filter,
+ * multi-row selection, and bulk-change of type / learning_relevance / lock.
+ *
+ * Persistence is delegated to onBulkUpdate(ids, patch). The parent (KnowledgeGraph)
+ * provides this from useGraphData.bulkUpdateTopics.
+ */
+export default function GraphTable({
+  topics,
+  relations,
+  onBulkUpdate,
+  onSelectNode,
+}) {
+  const [sortKey, setSortKey] = useState('label');
+  const [sortDir, setSortDir] = useState('asc');
+  const [groupBy, setGroupBy] = useState('none');
+  const [query, setQuery] = useState('');
+  const [selectedIds, setSelectedIds] = useState(() => new Set());
+  const [collapsed, setCollapsed] = useState(() => new Set());
+
+  // Bulk-action form state
+  const [bulkType, setBulkType] = useState('');
+  const [bulkRelevance, setBulkRelevance] = useState('');
+  const [bulkLockOnRelevance, setBulkLockOnRelevance] = useState(true);
+  const [isApplying, setIsApplying] = useState(false);
+  const [feedback, setFeedback] = useState(null);
+
+  // Pre-compute relation counts per topic so the column is cheap to render.
+  const relationCount = useMemo(() => {
+    const counts = new Map();
+    for (const r of relations) {
+      counts.set(r.source, (counts.get(r.source) || 0) + 1);
+      counts.set(r.target, (counts.get(r.target) || 0) + 1);
+    }
+    return counts;
+  }, [relations]);
+
+  // Filter + sort
+  const filtered = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    const rows = topics
+      .map(t => ({
+        ...t,
+        learning_relevance: t.learning_relevance || 'standard',
+        type: t.type || 'concept',
+        difficulty: t.difficulty || 'intermediate',
+        complexity_weight: t.complexity_weight ?? 3,
+        theme: t.theme || '',
+        relations: relationCount.get(t.id) || 0,
+      }))
+      .filter(t => !q || t.label?.toLowerCase().includes(q) || t.description?.toLowerCase().includes(q));
+
+    const sorted = [...rows].sort((a, b) => {
+      const cmp = compareValues(a[sortKey], b[sortKey], sortKey);
+      return sortDir === 'asc' ? cmp : -cmp;
+    });
+    return sorted;
+  }, [topics, relationCount, query, sortKey, sortDir]);
+
+  // Group rows (flat array if groupBy === 'none')
+  const groups = useMemo(() => {
+    if (groupBy === 'none') return [{ key: '__all__', label: null, rows: filtered }];
+    const map = new Map();
+    for (const t of filtered) {
+      const k = t[groupBy] || '—';
+      if (!map.has(k)) map.set(k, []);
+      map.get(k).push(t);
+    }
+    return [...map.entries()]
+      .sort(([a], [b]) => compareValues(a, b, groupBy))
+      .map(([key, rows]) => ({ key, label: String(key), rows }));
+  }, [filtered, groupBy]);
+
+  // ── Selection helpers ─────────────────────────────────────────────────────
+
+  const allVisibleIds = useMemo(() => filtered.map(t => t.id), [filtered]);
+  const visibleSelected = useMemo(
+    () => allVisibleIds.filter(id => selectedIds.has(id)).length,
+    [allVisibleIds, selectedIds],
+  );
+  const allVisibleChecked = visibleSelected === allVisibleIds.length && allVisibleIds.length > 0;
+  const someVisibleChecked = visibleSelected > 0 && !allVisibleChecked;
+
+  const toggleOne = (id) => {
+    setSelectedIds(prev => {
+      const next = new Set(prev);
+      next.has(id) ? next.delete(id) : next.add(id);
+      return next;
+    });
+  };
+  const toggleAllVisible = () => {
+    setSelectedIds(prev => {
+      const next = new Set(prev);
+      if (allVisibleChecked) {
+        for (const id of allVisibleIds) next.delete(id);
+      } else {
+        for (const id of allVisibleIds) next.add(id);
+      }
+      return next;
+    });
+  };
+  const toggleGroup = (groupRows) => {
+    setSelectedIds(prev => {
+      const next = new Set(prev);
+      const ids = groupRows.map(r => r.id);
+      const allOn = ids.every(id => next.has(id));
+      for (const id of ids) (allOn ? next.delete(id) : next.add(id));
+      return next;
+    });
+  };
+  const clearSelection = () => setSelectedIds(new Set());
+
+  // ── Sorting ───────────────────────────────────────────────────────────────
+
+  const onSort = (key) => {
+    if (!SORTABLE.includes(key)) return;
+    if (sortKey === key) {
+      setSortDir(d => (d === 'asc' ? 'desc' : 'asc'));
+    } else {
+      setSortKey(key);
+      setSortDir('asc');
+    }
+  };
+
+  // ── Bulk actions ──────────────────────────────────────────────────────────
+
+  const runBulk = async (patch, label) => {
+    if (selectedIds.size === 0) return;
+    setIsApplying(true);
+    setFeedback(null);
+    try {
+      const n = await onBulkUpdate([...selectedIds], patch);
+      setFeedback(`${label} — ${n} topic${n === 1 ? '' : 's'} updated.`);
+    } catch (e) {
+      setFeedback(`Failed: ${e.message || 'unknown error'}`);
+    } finally {
+      setIsApplying(false);
+    }
+  };
+
+  const applyBulkType = () => {
+    if (!bulkType) return;
+    runBulk({ type: bulkType }, `Type → ${bulkType}`);
+  };
+  const applyBulkRelevance = () => {
+    if (!bulkRelevance) return;
+    const patch = { learning_relevance: bulkRelevance };
+    if (bulkLockOnRelevance) patch.relevance_locked = true;
+    runBulk(patch, `Relevance → ${bulkRelevance}${bulkLockOnRelevance ? ' (locked)' : ''}`);
+  };
+  const applyLock = (locked) => {
+    runBulk({ relevance_locked: locked }, locked ? 'Locked relevance' : 'Unlocked relevance');
+  };
+
+  // ── Render ────────────────────────────────────────────────────────────────
+
+  const totalSel = selectedIds.size;
+  const isCollapsed = (key) => collapsed.has(key);
+  const toggleCollapse = (key) => {
+    setCollapsed(prev => {
+      const next = new Set(prev);
+      next.has(key) ? next.delete(key) : next.add(key);
+      return next;
+    });
+  };
+
+  return (
+    <div className="h-full flex flex-col bg-paper">
+      {/* Toolbar */}
+      <div className="flex flex-wrap items-center gap-3 p-3 border-b border-bg-warm bg-bg">
+        <div className="relative">
+          <Search size={14} className="absolute left-2 top-1/2 -translate-y-1/2 text-fg-muted pointer-events-none" />
+          <input
+            type="text"
+            value={query}
+            onChange={e => setQuery(e.target.value)}
+            placeholder="Filter by label or description…"
+            className="pl-7 pr-3 py-1.5 text-sm border border-bg-warm rounded-[var(--r-sm)] bg-paper w-64"
+          />
+        </div>
+        <label className="text-xs text-fg-muted flex items-center gap-1.5">
+          Group by
+          <select
+            value={groupBy}
+            onChange={e => setGroupBy(e.target.value)}
+            className="border border-bg-warm rounded-[var(--r-sm)] px-2 py-1 text-xs bg-paper"
+          >
+            {GROUP_OPTIONS.map(o => (
+              <option key={o.value} value={o.value}>{o.label}</option>
+            ))}
+          </select>
+        </label>
+        <span className="text-xs text-fg-muted ml-auto">
+          {filtered.length} of {topics.length} topics
+          {totalSel > 0 && <> · <span className="text-teal font-medium">{totalSel} selected</span></>}
+        </span>
+      </div>
+
+      {/* Bulk action bar */}
+      {totalSel > 0 && (
+        <div className="flex flex-wrap items-center gap-2 p-3 border-b border-bg-warm bg-teal/5">
+          <span className="text-xs font-medium text-teal mr-1">Bulk:</span>
+
+          {/* Type */}
+          <div className="flex items-center gap-1">
+            <select
+              value={bulkType}
+              onChange={e => setBulkType(e.target.value)}
+              className="border border-bg-warm rounded-[var(--r-sm)] px-2 py-1 text-xs bg-paper"
+              disabled={isApplying}
+            >
+              <option value="">— set type —</option>
+              {TYPES.map(t => <option key={t} value={t}>{t}</option>)}
+            </select>
+            <Button
+              onClick={applyBulkType}
+              disabled={!bulkType || isApplying}
+              className="px-2 py-1 text-xs"
+            >Apply</Button>
+          </div>
+
+          {/* Relevance */}
+          <div className="flex items-center gap-1">
+            <select
+              value={bulkRelevance}
+              onChange={e => setBulkRelevance(e.target.value)}
+              className="border border-bg-warm rounded-[var(--r-sm)] px-2 py-1 text-xs bg-paper"
+              disabled={isApplying}
+            >
+              <option value="">— set relevance —</option>
+              {RELEVANCE.map(r => <option key={r} value={r}>{r}</option>)}
+            </select>
+            <label className="flex items-center gap-1 text-xs text-fg-muted cursor-pointer">
+              <input
+                type="checkbox"
+                checked={bulkLockOnRelevance}
+                onChange={e => setBulkLockOnRelevance(e.target.checked)}
+                className="rounded bg-bg-warm border-transparent focus:ring-0 text-teal"
+              />
+              lock
+            </label>
+            <Button
+              onClick={applyBulkRelevance}
+              disabled={!bulkRelevance || isApplying}
+              className="px-2 py-1 text-xs"
+            >Apply</Button>
+          </div>
+
+          {/* Lock toggles */}
+          <button
+            onClick={() => applyLock(true)}
+            disabled={isApplying}
+            className="flex items-center gap-1 px-2 py-1 text-xs border border-bg-warm rounded-[var(--r-sm)] bg-paper hover:bg-bg-warm/50 disabled:opacity-40"
+            title="Lock relevance for selected topics"
+          >
+            <Lock size={11} /> Lock
+          </button>
+          <button
+            onClick={() => applyLock(false)}
+            disabled={isApplying}
+            className="flex items-center gap-1 px-2 py-1 text-xs border border-bg-warm rounded-[var(--r-sm)] bg-paper hover:bg-bg-warm/50 disabled:opacity-40"
+            title="Unlock relevance for selected topics"
+          >
+            <Unlock size={11} /> Unlock
+          </button>
+
+          <button
+            onClick={clearSelection}
+            className="ml-auto flex items-center gap-1 px-2 py-1 text-xs text-fg-muted hover:text-fg"
+          >
+            <X size={12} /> Clear
+          </button>
+
+          {feedback && (
+            <span className="basis-full text-xs text-fg-muted">{feedback}</span>
+          )}
+        </div>
+      )}
+
+      {/* Table */}
+      <div className="flex-1 overflow-auto">
+        <table className="w-full text-sm">
+          <thead className="bg-bg sticky top-0 z-10">
+            <tr className="text-left border-b border-bg-warm">
+              <th className="px-3 py-2 w-8">
+                <input
+                  type="checkbox"
+                  checked={allVisibleChecked}
+                  ref={el => { if (el) el.indeterminate = someVisibleChecked; }}
+                  onChange={toggleAllVisible}
+                  className="rounded bg-bg-warm border-transparent focus:ring-0 text-teal"
+                  title={allVisibleChecked ? 'Deselect all visible' : 'Select all visible'}
+                />
+              </th>
+              {[
+                ['label', 'Label'],
+                ['type', 'Type'],
+                ['learning_relevance', 'Relevance'],
+                ['theme', 'Theme'],
+                ['difficulty', 'Difficulty'],
+                ['complexity_weight', 'Weight'],
+                ['relations', 'Rel.'],
+              ].map(([key, label]) => (
+                <th
+                  key={key}
+                  onClick={() => onSort(key)}
+                  className="px-3 py-2 text-xs uppercase tracking-wider text-fg-muted cursor-pointer select-none hover:text-teal"
+                >
+                  {label}<SortIcon active={sortKey === key} dir={sortDir} />
+                </th>
+              ))}
+              <th className="px-3 py-2 text-xs uppercase tracking-wider text-fg-muted">Lock</th>
+            </tr>
+          </thead>
+
+          <tbody>
+            {groups.map(group => (
+              <Group
+                key={group.key}
+                group={group}
+                groupBy={groupBy}
+                collapsed={isCollapsed(group.key)}
+                onToggleCollapse={() => toggleCollapse(group.key)}
+                onToggleGroup={() => toggleGroup(group.rows)}
+                selectedIds={selectedIds}
+                onToggleOne={toggleOne}
+                onSelectNode={onSelectNode}
+              />
+            ))}
+            {filtered.length === 0 && (
+              <tr>
+                <td colSpan={9} className="px-3 py-12 text-center text-fg-muted text-sm">
+                  No topics match the current filter.
+                </td>
+              </tr>
+            )}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}
+
+function Group({
+  group, groupBy, collapsed, onToggleCollapse, onToggleGroup,
+  selectedIds, onToggleOne, onSelectNode,
+}) {
+  const groupHeader = groupBy !== 'none' && group.label != null;
+  const groupSelectedCount = group.rows.filter(r => selectedIds.has(r.id)).length;
+  const allGroupSelected = groupSelectedCount === group.rows.length && group.rows.length > 0;
+  const someGroupSelected = groupSelectedCount > 0 && !allGroupSelected;
+
+  return (
+    <>
+      {groupHeader && (
+        <tr className="bg-bg-warm/40 border-b border-bg-warm">
+          <td className="px-3 py-1.5 w-8">
+            <input
+              type="checkbox"
+              checked={allGroupSelected}
+              ref={el => { if (el) el.indeterminate = someGroupSelected; }}
+              onChange={onToggleGroup}
+              className="rounded bg-bg-warm border-transparent focus:ring-0 text-teal"
+            />
+          </td>
+          <td colSpan={8} className="px-3 py-1.5 text-xs font-medium text-fg-muted">
+            <button
+              onClick={onToggleCollapse}
+              className="inline-flex items-center gap-1 text-fg-muted hover:text-teal"
+            >
+              {collapsed ? <ChevronRight size={12} /> : <ChevronDown size={12} />}
+              <span className="uppercase tracking-wider">{group.label}</span>
+              <span className="text-fg-muted/70 normal-case">· {group.rows.length}</span>
+            </button>
+          </td>
+        </tr>
+      )}
+      {!collapsed && group.rows.map(t => (
+        <Row
+          key={t.id}
+          topic={t}
+          checked={selectedIds.has(t.id)}
+          onToggle={() => onToggleOne(t.id)}
+          onSelectNode={onSelectNode}
+        />
+      ))}
+    </>
+  );
+}
+
+function Row({ topic, checked, onToggle, onSelectNode }) {
+  return (
+    <tr
+      className={`border-b border-bg-warm/60 hover:bg-bg-warm/30 transition-colors ${checked ? 'bg-teal/5' : ''}`}
+    >
+      <td className="px-3 py-2 w-8">
+        <input
+          type="checkbox"
+          checked={checked}
+          onChange={onToggle}
+          className="rounded bg-bg-warm border-transparent focus:ring-0 text-teal"
+        />
+      </td>
+      <td className="px-3 py-2">
+        <button
+          onClick={() => onSelectNode?.(topic)}
+          className="text-left hover:text-teal underline-offset-2 hover:underline"
+          title={topic.description || ''}
+        >
+          {topic.label}
+        </button>
+      </td>
+      <td className="px-3 py-2 font-mono text-xs">{topic.type}</td>
+      <td className="px-3 py-2 font-mono text-xs">{topic.learning_relevance}</td>
+      <td className="px-3 py-2 text-xs text-fg-muted">{topic.theme || '—'}</td>
+      <td className="px-3 py-2 text-xs">{topic.difficulty}</td>
+      <td className="px-3 py-2 text-xs text-center">{topic.complexity_weight}</td>
+      <td className="px-3 py-2 text-xs text-center text-fg-muted">{topic.relations}</td>
+      <td className="px-3 py-2 text-center">
+        {topic.relevance_locked
+          ? <Lock size={12} className="text-teal inline" />
+          : <Unlock size={12} className="text-fg-muted/40 inline" />}
+      </td>
+    </tr>
+  );
+}

src/hooks/useGraphData.js

@@ -104,6 +104,23 @@ export function useGraphData() {
     return true;
   }, []);
 
+  /**
+   * Apply the same patch to many topics in one call. `ids` is the set of
+   * topic IDs to update; `patch` is the partial-topic to merge into each one
+   * (e.g. `{ type: 'process' }` or `{ learning_relevance: 'core', relevance_locked: true }`).
+   *
+   * Persists each topic via db.upsertTopic in parallel and mirrors into state.
+   * Returns the number of topics actually written (selected ∩ existing).
+   */
+  const bulkUpdateTopics = useCallback(async (ids, patch) => {
+    const idSet = new Set(ids);
+    const targets = topicsRef.current.filter(t => idSet.has(t.id));
+    const updated = targets.map(t => ({ ...t, ...patch }));
+    await Promise.all(updated.map(t => db.upsertTopic(t)));
+    setTopics(prev => prev.map(t => (idSet.has(t.id) ? { ...t, ...patch } : t)));
+    return updated.length;
+  }, []);
+
   /** Remove a specific (source, target, type) relation triple. */
   const removeRelation = useCallback(async (source, target, type) => {
     await db.removeRelation(source, target, type);
@@ -165,6 +182,7 @@ export function useGraphData() {
     snapshotMeta,
     reload,
     updateTopic,
+    bulkUpdateTopics,
     deleteTopic,
     addRelation,
     removeRelation,

src/lib/__tests__/curriculumService.test.js

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import { validateSchedule } from '../curriculumService';
+
+const week = (n, theme, topicIds, duration = 30) => ({
+  week_number: n,
+  theme,
+  topic_ids: topicIds,
+  estimated_duration: duration,
+  week_rationale: 'r',
+});
+
+const makeTopic = (id, theme) => ({
+  id,
+  theme,
+  type: 'concept',
+  learning_relevance: 'include',
+});
+
+const buildScheduleFromTopics = (topics) => {
+  const ids = topics.map(t => t.id);
+  return Array.from({ length: 26 }, (_, i) => {
+    const chunk = ids.slice(i * 2, i * 2 + 2);
+    return week(i + 1, topics[i * 2]?.theme || 'General', chunk.length ? chunk : [ids[0]]);
+  });
+};
+
+describe('validateSchedule', () => {
+  it('does not warn about missing themes when merging was required (themes_kb > 26)', () => {
+    const topics = [];
+    for (let i = 0; i < 60; i++) topics.push(makeTopic(`t${i}`, `Theme ${i % 30}`));
+    const schedule = buildScheduleFromTopics(topics);
+
+    const result = validateSchedule(schedule, topics);
+    expect(result.valid).toBe(true);
+    const themeWarning = result.warnings.find(w => w.includes('not scheduled'));
+    expect(themeWarning).toBeUndefined();
+  });
+
+  it('warns about missing themes only when merging was not required', () => {
+    const topics = [];
+    for (let i = 0; i < 10; i++) topics.push(makeTopic(`t${i}`, `Theme ${i}`));
+    const schedule = Array.from({ length: 26 }, (_, i) =>
+      week(i + 1, 'Theme 0', ['t0'])
+    );
+
+    const result = validateSchedule(schedule, topics);
+    const themeWarning = result.warnings.find(w => w.includes('not scheduled'));
+    expect(themeWarning).toBeDefined();
+    expect(themeWarning).toMatch(/9 theme/);
+  });
+
+  it('warns when learning topics are absent from every week (real coverage gap)', () => {
+    const topics = [
+      makeTopic('t1', 'A'),
+      makeTopic('t2', 'A'),
+      makeTopic('t3', 'B'),
+    ];
+    const schedule = Array.from({ length: 26 }, (_, i) =>
+      week(i + 1, 'A', ['t1'])
+    );
+
+    const result = validateSchedule(schedule, topics);
+    const coverageWarning = result.warnings.find(w => w.includes('not covered'));
+    expect(coverageWarning).toBeDefined();
+    expect(coverageWarning).toMatch(/2 learning topic/);
+  });
+
+  it('ignores topics with type=fact or learning_relevance=exclude in coverage', () => {
+    const topics = [
+      makeTopic('t1', 'A'),
+      { ...makeTopic('t2', 'A'), type: 'fact' },
+      { ...makeTopic('t3', 'B'), learning_relevance: 'exclude' },
+    ];
+    const schedule = Array.from({ length: 26 }, (_, i) =>
+      week(i + 1, 'A', ['t1'])
+    );
+
+    const result = validateSchedule(schedule, topics);
+    expect(result.warnings.find(w => w.includes('not covered'))).toBeUndefined();
+  });
+
+  it('flags hard errors: wrong week count, bad duration, unknown topic_id', () => {
+    const topics = [makeTopic('t1', 'A')];
+    const schedule = [week(1, 'A', ['t1'])];
+    const result = validateSchedule(schedule, topics);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]).toMatch(/exactly 26 weeks/);
+
+    const fullSchedule = Array.from({ length: 26 }, (_, i) => week(i + 1, 'A', ['t1']));
+    fullSchedule[2].estimated_duration = 5;
+    fullSchedule[5].topic_ids = ['missing-id'];
+    const result2 = validateSchedule(fullSchedule, topics);
+    expect(result2.valid).toBe(false);
+    expect(result2.errors.some(e => e.includes('out-of-range duration'))).toBe(true);
+    expect(result2.errors.some(e => e.includes('unknown topic_id'))).toBe(true);
+  });
+});

src/lib/curriculumService.js

@@ -60,8 +60,16 @@ export function buildThemeTopicMap(topics) {
 
 /**
  * Validates a 26-week schedule against the provided topics.
- * Checks for exactly 26 weeks, duration range, theme existence, and topic existence.
+ *
- * Returns { valid: boolean, errors: string[] }
+ * Warning policy:
+ * - Theme names not appearing as a week label are NOT a warning when the KB
+ *   has more than 26 themes — the AI is required to merge in that case, and
+ *   topic_ids from the merged themes are carried through under the chosen
+ *   week label. We only warn about missing themes when merging wasn't needed.
+ * - Real coverage is measured on TOPICS: a topic that exists in the KB but
+ *   is absent from every week's topic_ids is a genuine gap and gets a warning.
+ *
+ * Returns { valid: boolean, errors: string[], warnings: string[] }
  */
 export function validateSchedule(schedule, topics) {
   const errors = [];   // Hard errors — schedule is unusable
@@ -71,10 +79,13 @@ export function validateSchedule(schedule, topics) {
     errors.push(`Schedule must contain exactly 26 weeks. Found ${schedule?.length || 0}.`);
   }
 
-  const validThemes = new Set(topics.filter(t => t.type !== 'fact' && t.learning_relevance !== 'exclude').map(t => t.theme || 'General'));
+  const learningTopics = topics.filter(t => t.type !== 'fact' && t.learning_relevance !== 'exclude');
+  const validThemes = new Set(learningTopics.map(t => t.theme || 'General'));
   const validTopicIds = new Set(topics.map(t => t.id));
+  const learningTopicIds = new Set(learningTopics.map(t => t.id));
 
   const scheduledThemes = new Set();
+  const scheduledTopicIds = new Set();
 
   for (let i = 0; i < (schedule || []).length; i++) {
     const week = schedule[i];
@@ -86,7 +97,7 @@ export function validateSchedule(schedule, topics) {
     }
     // Allow AI-merged theme names — only flag truly unknown themes as warnings
     scheduledThemes.add(week.theme);
-    
+
     if (!week.topic_ids || week.topic_ids.length === 0) {
       errors.push(`Week ${week.week_number} has no topic_ids.`);
     } else {
@@ -94,20 +105,30 @@ export function validateSchedule(schedule, topics) {
         if (!validTopicIds.has(tId)) {
           errors.push(`Week ${week.week_number} references unknown topic_id: ${tId}`);
         }
+        scheduledTopicIds.add(tId);
       }
     }
   }
 
-  // Theme coverage — soft warnings, not hard errors
+  // Theme coverage — only warn when merging wasn't required. When themes_kb > 26
-  // When there are more themes than 26 weeks, the AI must merge some.
+  // the AI is *required* to merge, so absent theme labels are expected.
-  const missingThemes = [];
+  if (validThemes.size <= 26) {
-  for (const t of validThemes) {
+    const missingThemes = [];
-    if (!scheduledThemes.has(t)) {
+    for (const t of validThemes) {
-      missingThemes.push(t);
+      if (!scheduledThemes.has(t)) {
+        missingThemes.push(t);
+      }
+    }
+    if (missingThemes.length > 0) {
+      warnings.push(`${missingThemes.length} theme(s) not scheduled: ${missingThemes.join(', ')}`);
     }
   }
-  if (missingThemes.length > 0) {
+
-    warnings.push(`${missingThemes.length} theme(s) not directly scheduled (topics may appear under merged themes): ${missingThemes.join(', ')}`);
+  // Topic coverage — the real signal. Topics carried under a merged theme are
+  // still covered; topics absent from every week are not.
+  const missingTopicCount = [...learningTopicIds].filter(id => !scheduledTopicIds.has(id)).length;
+  if (missingTopicCount > 0) {
+    warnings.push(`${missingTopicCount} learning topic(s) not covered by any week of the schedule.`);
   }
 
   return { valid: errors.length === 0, errors, warnings };
@@ -224,7 +245,9 @@ Rules:
     throw new Error(`Generated schedule failed validation after retry:\n- ${validationResult.errors.join('\n- ')}`);
   }
 
-  // Log warnings but don't fail
+  // Log warnings but don't fail. With themes_kb > 26 the AI must merge themes,
+  // so most "missing theme" noise is filtered upstream in validateSchedule —
+  // anything that lands here is a genuine coverage gap worth surfacing.
   if (validationResult.warnings.length > 0) {
     console.warn('[Curriculum] Schedule generated with warnings:', validationResult.warnings);
   }