@vue-skuilder/db 0.2.35 → 0.2.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (263) hide show
  1. package/CLAUDE.md +15 -4
  2. package/build.entries.mjs +12 -0
  3. package/dist/_virtual/_rolldown/runtime.mjs +8 -0
  4. package/dist/{contentSource-BteiDpxH.d.ts → contentSource-D_E7JaxR.d.ts} +1 -1
  5. package/dist/core/UserDBDebugger.mjs +285 -0
  6. package/dist/core/UserDBDebugger.mjs.map +1 -0
  7. package/dist/core/bulkImport/cardProcessor.mjs +106 -0
  8. package/dist/core/bulkImport/cardProcessor.mjs.map +1 -0
  9. package/dist/core/{index.js → index.cjs} +6413 -7738
  10. package/dist/core/index.cjs.map +1 -0
  11. package/dist/core/index.d.ts +5 -5
  12. package/dist/core/index.mjs +20 -11368
  13. package/dist/core/interfaces/contentSource.mjs +20 -0
  14. package/dist/core/interfaces/contentSource.mjs.map +1 -0
  15. package/dist/core/navigators/Pipeline.mjs +723 -0
  16. package/dist/core/navigators/Pipeline.mjs.map +1 -0
  17. package/dist/core/navigators/PipelineAssembler.mjs +86 -0
  18. package/dist/core/navigators/PipelineAssembler.mjs.map +1 -0
  19. package/dist/core/navigators/PipelineDebugger.mjs +771 -0
  20. package/dist/core/navigators/PipelineDebugger.mjs.map +1 -0
  21. package/dist/core/navigators/SrsDebugger.mjs +34 -0
  22. package/dist/core/navigators/SrsDebugger.mjs.map +1 -0
  23. package/dist/core/navigators/StrategyPressureDebugger.mjs +19 -0
  24. package/dist/core/navigators/StrategyPressureDebugger.mjs.map +1 -0
  25. package/dist/core/navigators/defaults.mjs +96 -0
  26. package/dist/core/navigators/defaults.mjs.map +1 -0
  27. package/dist/core/navigators/diversityRerank.mjs +85 -0
  28. package/dist/core/navigators/diversityRerank.mjs.map +1 -0
  29. package/dist/core/navigators/filters/WeightedFilter.mjs +81 -0
  30. package/dist/core/navigators/filters/WeightedFilter.mjs.map +1 -0
  31. package/dist/core/navigators/filters/eloDistance.mjs +244 -0
  32. package/dist/core/navigators/filters/eloDistance.mjs.map +1 -0
  33. package/dist/core/navigators/filters/hierarchyDefinition.mjs +235 -0
  34. package/dist/core/navigators/filters/hierarchyDefinition.mjs.map +1 -0
  35. package/dist/core/navigators/filters/interferenceMitigator.mjs +201 -0
  36. package/dist/core/navigators/filters/interferenceMitigator.mjs.map +1 -0
  37. package/dist/core/navigators/filters/relativePriority.mjs +135 -0
  38. package/dist/core/navigators/filters/relativePriority.mjs.map +1 -0
  39. package/dist/core/navigators/filters/userTagPreference.mjs +101 -0
  40. package/dist/core/navigators/filters/userTagPreference.mjs.map +1 -0
  41. package/dist/core/navigators/generators/CompositeGenerator.mjs +203 -0
  42. package/dist/core/navigators/generators/CompositeGenerator.mjs.map +1 -0
  43. package/dist/core/navigators/generators/elo.mjs +77 -0
  44. package/dist/core/navigators/generators/elo.mjs.map +1 -0
  45. package/dist/core/navigators/generators/prescribed.mjs +694 -0
  46. package/dist/core/navigators/generators/prescribed.mjs.map +1 -0
  47. package/dist/core/navigators/generators/srs.mjs +158 -0
  48. package/dist/core/navigators/generators/srs.mjs.map +1 -0
  49. package/dist/core/navigators/index.mjs +345 -0
  50. package/dist/core/navigators/index.mjs.map +1 -0
  51. package/dist/core/navigators/pipelinePlan.mjs +109 -0
  52. package/dist/core/navigators/pipelinePlan.mjs.map +1 -0
  53. package/dist/core/navigators/regulators.mjs +128 -0
  54. package/dist/core/navigators/regulators.mjs.map +1 -0
  55. package/dist/core/orchestration/gradient.mjs +101 -0
  56. package/dist/core/orchestration/gradient.mjs.map +1 -0
  57. package/dist/core/orchestration/index.mjs +115 -0
  58. package/dist/core/orchestration/index.mjs.map +1 -0
  59. package/dist/core/orchestration/learning.mjs +140 -0
  60. package/dist/core/orchestration/learning.mjs.map +1 -0
  61. package/dist/core/orchestration/recording.mjs +64 -0
  62. package/dist/core/orchestration/recording.mjs.map +1 -0
  63. package/dist/core/orchestration/signal.mjs +40 -0
  64. package/dist/core/orchestration/signal.mjs.map +1 -0
  65. package/dist/core/types/contentNavigationStrategy.mjs +10 -0
  66. package/dist/core/types/contentNavigationStrategy.mjs.map +1 -0
  67. package/dist/core/types/hydration.mjs +13 -0
  68. package/dist/core/types/hydration.mjs.map +1 -0
  69. package/dist/core/types/strategyState.mjs +16 -0
  70. package/dist/core/types/strategyState.mjs.map +1 -0
  71. package/dist/core/types/studySession.mjs +14 -0
  72. package/dist/core/types/studySession.mjs.map +1 -0
  73. package/dist/core/types/types-legacy.mjs +44 -0
  74. package/dist/core/types/types-legacy.mjs.map +1 -0
  75. package/dist/core/util/index.mjs +31 -0
  76. package/dist/core/util/index.mjs.map +1 -0
  77. package/dist/core/versionStamps.mjs +46 -0
  78. package/dist/core/versionStamps.mjs.map +1 -0
  79. package/dist/courseConfigRegistration.mjs +306 -0
  80. package/dist/courseConfigRegistration.mjs.map +1 -0
  81. package/dist/{dataLayerProvider-C_QWzHf-.d.ts → dataLayerProvider-BDshhSp_.d.ts} +1 -1
  82. package/dist/diagnostics/dataset.mjs +118 -0
  83. package/dist/diagnostics/dataset.mjs.map +1 -0
  84. package/dist/diagnostics/derive.mjs +318 -0
  85. package/dist/diagnostics/derive.mjs.map +1 -0
  86. package/dist/diagnostics/{index.js → index.cjs} +1 -1
  87. package/dist/diagnostics/index.d.ts +3 -3
  88. package/dist/diagnostics/index.mjs +7 -1042
  89. package/dist/diagnostics/loader.mjs +151 -0
  90. package/dist/diagnostics/loader.mjs.map +1 -0
  91. package/dist/diagnostics/pipeline.mjs +161 -0
  92. package/dist/diagnostics/pipeline.mjs.map +1 -0
  93. package/dist/diagnostics/tagElo.mjs +177 -0
  94. package/dist/diagnostics/tagElo.mjs.map +1 -0
  95. package/dist/diagnostics/text.mjs +174 -0
  96. package/dist/diagnostics/text.mjs.map +1 -0
  97. package/dist/factory.mjs +70 -0
  98. package/dist/factory.mjs.map +1 -0
  99. package/dist/impl/common/BaseUserDB.mjs +1115 -0
  100. package/dist/impl/common/BaseUserDB.mjs.map +1 -0
  101. package/dist/impl/common/userDBHelpers.mjs +49 -0
  102. package/dist/impl/common/userDBHelpers.mjs.map +1 -0
  103. package/dist/impl/common/userDBKeys.mjs +45 -0
  104. package/dist/impl/common/userDBKeys.mjs.map +1 -0
  105. package/dist/impl/couch/CouchDBSyncStrategy.mjs +272 -0
  106. package/dist/impl/couch/CouchDBSyncStrategy.mjs.map +1 -0
  107. package/dist/impl/couch/CourseSyncService.mjs +320 -0
  108. package/dist/impl/couch/CourseSyncService.mjs.map +1 -0
  109. package/dist/impl/couch/PouchDataLayerProvider.mjs +89 -0
  110. package/dist/impl/couch/PouchDataLayerProvider.mjs.map +1 -0
  111. package/dist/impl/couch/adminDB.mjs +61 -0
  112. package/dist/impl/couch/adminDB.mjs.map +1 -0
  113. package/dist/impl/couch/auth.mjs +33 -0
  114. package/dist/impl/couch/auth.mjs.map +1 -0
  115. package/dist/impl/couch/classroomDB.mjs +227 -0
  116. package/dist/impl/couch/classroomDB.mjs.map +1 -0
  117. package/dist/impl/couch/clientCache.mjs +15 -0
  118. package/dist/impl/couch/clientCache.mjs.map +1 -0
  119. package/dist/impl/couch/courseAPI.mjs +197 -0
  120. package/dist/impl/couch/courseAPI.mjs.map +1 -0
  121. package/dist/impl/couch/courseDB.mjs +735 -0
  122. package/dist/impl/couch/courseDB.mjs.map +1 -0
  123. package/dist/impl/couch/courseLookupDB.mjs +94 -0
  124. package/dist/impl/couch/courseLookupDB.mjs.map +1 -0
  125. package/dist/impl/couch/{index.js → index.cjs} +7003 -10358
  126. package/dist/impl/couch/index.cjs.map +1 -0
  127. package/dist/impl/couch/index.d.ts +33 -5
  128. package/dist/impl/couch/index.mjs +152 -12147
  129. package/dist/impl/couch/index.mjs.map +1 -1
  130. package/dist/impl/couch/pouchdb-setup.mjs +15 -0
  131. package/dist/impl/couch/pouchdb-setup.mjs.map +1 -0
  132. package/dist/impl/couch/updateQueue.mjs +101 -0
  133. package/dist/impl/couch/updateQueue.mjs.map +1 -0
  134. package/dist/impl/couch/user-course-relDB.mjs +55 -0
  135. package/dist/impl/couch/user-course-relDB.mjs.map +1 -0
  136. package/dist/impl/static/NoOpSyncStrategy.mjs +49 -0
  137. package/dist/impl/static/NoOpSyncStrategy.mjs.map +1 -0
  138. package/dist/impl/static/StaticDataLayerProvider.mjs +94 -0
  139. package/dist/impl/static/StaticDataLayerProvider.mjs.map +1 -0
  140. package/dist/impl/static/StaticDataUnpacker.mjs +311 -0
  141. package/dist/impl/static/StaticDataUnpacker.mjs.map +1 -0
  142. package/dist/impl/static/courseDB.mjs +368 -0
  143. package/dist/impl/static/courseDB.mjs.map +1 -0
  144. package/dist/impl/static/coursesDB.mjs +38 -0
  145. package/dist/impl/static/coursesDB.mjs.map +1 -0
  146. package/dist/impl/static/{index.js → index.cjs} +2486 -5993
  147. package/dist/impl/static/index.cjs.map +1 -0
  148. package/dist/impl/static/index.d.ts +4 -4
  149. package/dist/impl/static/index.mjs +6 -10741
  150. package/dist/{index-C745YB_6.d.ts → index-BLDpFYG3.d.ts} +1 -1
  151. package/dist/{index.js → index.cjs} +14190 -14249
  152. package/dist/index.cjs.map +1 -0
  153. package/dist/index.d.ts +12 -23
  154. package/dist/index.mjs +38 -16937
  155. package/dist/pouch/{index.js → index.cjs} +5 -1
  156. package/dist/pouch/index.cjs.map +1 -0
  157. package/dist/pouch/index.mjs +2 -19
  158. package/dist/study/ItemQueue.mjs +95 -0
  159. package/dist/study/ItemQueue.mjs.map +1 -0
  160. package/dist/study/MixerDebugger.mjs +303 -0
  161. package/dist/study/MixerDebugger.mjs.map +1 -0
  162. package/dist/study/SessionController.mjs +1187 -0
  163. package/dist/study/SessionController.mjs.map +1 -0
  164. package/dist/study/SessionDebugger.mjs +271 -0
  165. package/dist/study/SessionDebugger.mjs.map +1 -0
  166. package/dist/study/SessionOverlay.mjs +407 -0
  167. package/dist/study/SessionOverlay.mjs.map +1 -0
  168. package/dist/study/SourceMixer.mjs +45 -0
  169. package/dist/study/SourceMixer.mjs.map +1 -0
  170. package/dist/study/SpacedRepetition.mjs +108 -0
  171. package/dist/study/SpacedRepetition.mjs.map +1 -0
  172. package/dist/study/TagFilteredContentSource.mjs +136 -0
  173. package/dist/study/TagFilteredContentSource.mjs.map +1 -0
  174. package/dist/study/services/CardHydrationService.mjs +172 -0
  175. package/dist/study/services/CardHydrationService.mjs.map +1 -0
  176. package/dist/study/services/EloService.mjs +217 -0
  177. package/dist/study/services/EloService.mjs.map +1 -0
  178. package/dist/study/services/ResponseProcessor.mjs +190 -0
  179. package/dist/study/services/ResponseProcessor.mjs.map +1 -0
  180. package/dist/study/services/SrsService.mjs +49 -0
  181. package/dist/study/services/SrsService.mjs.map +1 -0
  182. package/dist/study/services/tagRecent.mjs +65 -0
  183. package/dist/study/services/tagRecent.mjs.map +1 -0
  184. package/dist/{types-DF0JuPbs.d.ts → types-DChCz22D.d.ts} +1 -1
  185. package/dist/{types-legacy-DdVjg81H.d.cts → types-legacy-fT5Y1Wuy.d.ts} +1 -1
  186. package/dist/userDBKeys-ne1g4Xuq.d.ts +16 -0
  187. package/dist/util/Loggable.mjs +14 -0
  188. package/dist/util/Loggable.mjs.map +1 -0
  189. package/dist/util/dataDirectory.mjs +47 -0
  190. package/dist/util/dataDirectory.mjs.map +1 -0
  191. package/dist/util/logger.mjs +86 -0
  192. package/dist/util/logger.mjs.map +1 -0
  193. package/dist/util/migrator/FileSystemAdapter.mjs +18 -0
  194. package/dist/util/migrator/FileSystemAdapter.mjs.map +1 -0
  195. package/dist/util/migrator/StaticToCouchDBMigrator.mjs +428 -0
  196. package/dist/util/migrator/StaticToCouchDBMigrator.mjs.map +1 -0
  197. package/dist/util/migrator/types.mjs +11 -0
  198. package/dist/util/migrator/types.mjs.map +1 -0
  199. package/dist/util/migrator/validation.mjs +334 -0
  200. package/dist/util/migrator/validation.mjs.map +1 -0
  201. package/dist/util/packer/CouchDBToStaticPacker.mjs +438 -0
  202. package/dist/util/packer/CouchDBToStaticPacker.mjs.map +1 -0
  203. package/dist/util/packer/{index.js → index.cjs} +73 -9
  204. package/dist/util/packer/index.cjs.map +1 -0
  205. package/dist/util/packer/index.d.ts +3 -3
  206. package/dist/util/packer/index.mjs +2 -537
  207. package/eslint.config.mjs +9 -1
  208. package/package.json +25 -13
  209. package/rolldown.config.mjs +44 -0
  210. package/src/core/UserDBDebugger.ts +47 -46
  211. package/src/core/navigators/Pipeline.ts +10 -10
  212. package/src/core/navigators/PipelineDebugger.ts +55 -55
  213. package/src/core/navigators/filters/eloDistance.ts +1 -1
  214. package/src/core/navigators/generators/elo.ts +5 -1
  215. package/src/core/navigators/generators/prescribed.ts +42 -16
  216. package/src/core/navigators/index.ts +9 -3
  217. package/src/factory.ts +10 -1
  218. package/src/impl/common/BaseUserDB.ts +16 -5
  219. package/src/impl/common/index.ts +2 -0
  220. package/src/impl/common/userDBHelpers.ts +4 -58
  221. package/src/impl/common/userDBKeys.ts +64 -0
  222. package/src/impl/couch/CourseSyncService.ts +130 -20
  223. package/src/impl/couch/PouchDataLayerProvider.ts +14 -1
  224. package/src/impl/couch/courseAPI.ts +26 -12
  225. package/src/impl/couch/courseDB.ts +35 -15
  226. package/src/impl/couch/index.ts +18 -23
  227. package/src/impl/couch/pouchdb-setup.ts +8 -0
  228. package/src/index.ts +1 -1
  229. package/src/study/MixerDebugger.ts +46 -46
  230. package/src/study/SessionDebugger.ts +20 -20
  231. package/src/study/SessionOverlay.ts +4 -4
  232. package/src/util/logger.ts +112 -13
  233. package/tests/core/navigators/eloGenerator.test.ts +36 -0
  234. package/tests/impl/courseSync.test.ts +139 -0
  235. package/tsup.config.ts +24 -21
  236. package/dist/SyncStrategy-BXliog1m.d.cts +0 -116
  237. package/dist/classroomDB-DLTtLZct.d.cts +0 -86
  238. package/dist/contentSource-FQZcZopC.d.cts +0 -2007
  239. package/dist/core/index.d.cts +0 -521
  240. package/dist/core/index.js.map +0 -1
  241. package/dist/core/index.mjs.map +0 -1
  242. package/dist/dataLayerProvider-3y21KtF-.d.cts +0 -61
  243. package/dist/diagnostics/index.d.cts +0 -561
  244. package/dist/diagnostics/index.mjs.map +0 -1
  245. package/dist/impl/couch/index.d.cts +0 -620
  246. package/dist/impl/couch/index.js.map +0 -1
  247. package/dist/impl/static/index.d.cts +0 -232
  248. package/dist/impl/static/index.js.map +0 -1
  249. package/dist/impl/static/index.mjs.map +0 -1
  250. package/dist/index-BIum9Ue2.d.cts +0 -137
  251. package/dist/index.d.cts +0 -1663
  252. package/dist/index.js.map +0 -1
  253. package/dist/index.mjs.map +0 -1
  254. package/dist/pouch/index.d.cts +0 -1
  255. package/dist/pouch/index.js.map +0 -1
  256. package/dist/pouch/index.mjs.map +0 -1
  257. package/dist/types-BcWVH4ww.d.cts +0 -58
  258. package/dist/types-legacy-DdVjg81H.d.ts +0 -168
  259. package/dist/util/packer/index.d.cts +0 -5
  260. package/dist/util/packer/index.js.map +0 -1
  261. package/dist/util/packer/index.mjs.map +0 -1
  262. package/src/study/getCardDataShape.ts +0 -34
  263. /package/dist/diagnostics/{index.js.map → index.cjs.map} +0 -0
@@ -237,19 +237,19 @@ export function captureMixerRun(
237
237
  function printMixerSummary(run: MixerRunReport): void {
238
238
  // eslint-disable-next-line no-console
239
239
  console.group(`🎨 Mixer Run: ${run.mixerType}`);
240
- logger.info(`Run ID: ${run.runId}`);
241
- logger.info(`Time: ${run.timestamp.toISOString()}`);
242
- logger.info(
240
+ logger.print(`Run ID: ${run.runId}`);
241
+ logger.print(`Time: ${run.timestamp.toISOString()}`);
242
+ logger.print(
243
243
  `Config: limit=${run.requestedLimit}${run.quotaPerSource ? `, quota/source=${run.quotaPerSource}` : ''}`
244
244
  );
245
245
 
246
246
  // eslint-disable-next-line no-console
247
247
  console.group(`📥 Input: ${run.sourceSummaries.length} sources`);
248
248
  for (const src of run.sourceSummaries) {
249
- logger.info(
249
+ logger.print(
250
250
  ` ${src.sourceName || src.sourceId}: ${src.totalCards} cards (${src.reviewCount} reviews, ${src.newCount} new)`
251
251
  );
252
- logger.info(` Score range: [${src.scoreRange[0].toFixed(2)}, ${src.scoreRange[1].toFixed(2)}], avg: ${src.avgScore.toFixed(2)}`);
252
+ logger.print(` Score range: [${src.scoreRange[0].toFixed(2)}, ${src.scoreRange[1].toFixed(2)}], avg: ${src.avgScore.toFixed(2)}`);
253
253
  }
254
254
  // eslint-disable-next-line no-console
255
255
  console.groupEnd();
@@ -258,7 +258,7 @@ function printMixerSummary(run: MixerRunReport): void {
258
258
  console.group(`📤 Output: ${run.finalCount} cards selected (${run.reviewsSelected} reviews, ${run.newSelected} new)`);
259
259
  for (const breakdown of run.sourceBreakdowns) {
260
260
  const name = breakdown.sourceName || breakdown.sourceId;
261
- logger.info(
261
+ logger.print(
262
262
  ` ${name}: ${breakdown.totalSelected} selected (${breakdown.reviewsSelected} reviews, ${breakdown.newSelected} new) - ${breakdown.selectionRate.toFixed(1)}% selection rate`
263
263
  );
264
264
  }
@@ -285,7 +285,7 @@ export const mixerDebugAPI = {
285
285
  */
286
286
  showRun(idOrIndex: string | number = 0): void {
287
287
  if (runHistory.length === 0) {
288
- logger.info('[Mixer Debug] No runs captured yet.');
288
+ logger.print('[Mixer Debug] No runs captured yet.');
289
289
  return;
290
290
  }
291
291
 
@@ -294,13 +294,13 @@ export const mixerDebugAPI = {
294
294
  if (typeof idOrIndex === 'number') {
295
295
  run = runHistory[idOrIndex];
296
296
  if (!run) {
297
- logger.info(`[Mixer Debug] No run found at index ${idOrIndex}. History length: ${runHistory.length}`);
297
+ logger.print(`[Mixer Debug] No run found at index ${idOrIndex}. History length: ${runHistory.length}`);
298
298
  return;
299
299
  }
300
300
  } else {
301
301
  run = runHistory.find((r) => r.runId.endsWith(idOrIndex));
302
302
  if (!run) {
303
- logger.info(`[Mixer Debug] No run found matching ID '${idOrIndex}'.`);
303
+ logger.print(`[Mixer Debug] No run found matching ID '${idOrIndex}'.`);
304
304
  return;
305
305
  }
306
306
  }
@@ -320,7 +320,7 @@ export const mixerDebugAPI = {
320
320
  */
321
321
  explainSourceBalance(): void {
322
322
  if (runHistory.length === 0) {
323
- logger.info('[Mixer Debug] No runs captured yet.');
323
+ logger.print('[Mixer Debug] No runs captured yet.');
324
324
  return;
325
325
  }
326
326
 
@@ -329,19 +329,19 @@ export const mixerDebugAPI = {
329
329
  // eslint-disable-next-line no-console
330
330
  console.group('⚖️ Source Balance Analysis');
331
331
 
332
- logger.info(`Mixer: ${run.mixerType}`);
333
- logger.info(`Requested limit: ${run.requestedLimit}`);
332
+ logger.print(`Mixer: ${run.mixerType}`);
333
+ logger.print(`Requested limit: ${run.requestedLimit}`);
334
334
  if (run.quotaPerSource) {
335
- logger.info(`Quota per source: ${run.quotaPerSource}`);
335
+ logger.print(`Quota per source: ${run.quotaPerSource}`);
336
336
  }
337
337
 
338
338
  // eslint-disable-next-line no-console
339
339
  console.group('Input Distribution:');
340
340
  for (const src of run.sourceSummaries) {
341
341
  const name = src.sourceName || src.sourceId;
342
- logger.info(`${name}:`);
343
- logger.info(` Provided: ${src.totalCards} cards (${src.reviewCount} reviews, ${src.newCount} new)`);
344
- logger.info(` Score range: [${src.scoreRange[0].toFixed(2)}, ${src.scoreRange[1].toFixed(2)}]`);
342
+ logger.print(`${name}:`);
343
+ logger.print(` Provided: ${src.totalCards} cards (${src.reviewCount} reviews, ${src.newCount} new)`);
344
+ logger.print(` Score range: [${src.scoreRange[0].toFixed(2)}, ${src.scoreRange[1].toFixed(2)}]`);
345
345
  }
346
346
  // eslint-disable-next-line no-console
347
347
  console.groupEnd();
@@ -350,19 +350,19 @@ export const mixerDebugAPI = {
350
350
  console.group('Selection Results:');
351
351
  for (const breakdown of run.sourceBreakdowns) {
352
352
  const name = breakdown.sourceName || breakdown.sourceId;
353
- logger.info(`${name}:`);
354
- logger.info(
353
+ logger.print(`${name}:`);
354
+ logger.print(
355
355
  ` Selected: ${breakdown.totalSelected}/${breakdown.reviewsProvided + breakdown.newProvided} (${breakdown.selectionRate.toFixed(1)}%)`
356
356
  );
357
- logger.info(` Reviews: ${breakdown.reviewsSelected}/${breakdown.reviewsProvided}`);
358
- logger.info(` New: ${breakdown.newSelected}/${breakdown.newProvided}`);
357
+ logger.print(` Reviews: ${breakdown.reviewsSelected}/${breakdown.reviewsProvided}`);
358
+ logger.print(` New: ${breakdown.newSelected}/${breakdown.newProvided}`);
359
359
 
360
360
  // Identify potential issues
361
361
  if (breakdown.reviewsProvided > 0 && breakdown.reviewsSelected === 0) {
362
- logger.info(` ⚠️ Had reviews but none selected!`);
362
+ logger.print(` ⚠️ Had reviews but none selected!`);
363
363
  }
364
364
  if (breakdown.totalSelected === 0 && breakdown.reviewsProvided + breakdown.newProvided > 0) {
365
- logger.info(` ⚠️ Had cards but none selected!`);
365
+ logger.print(` ⚠️ Had cards but none selected!`);
366
366
  }
367
367
  }
368
368
  // eslint-disable-next-line no-console
@@ -374,11 +374,11 @@ export const mixerDebugAPI = {
374
374
  const maxDeviation = Math.max(...selectionRates.map((r) => Math.abs(r - avgRate)));
375
375
 
376
376
  if (maxDeviation > 20) {
377
- logger.info(`\n⚠️ Significant imbalance detected (max deviation: ${maxDeviation.toFixed(1)}%)`);
378
- logger.info('Possible causes:');
379
- logger.info(' - Score range differences between sources');
380
- logger.info(' - One source has much better quality cards');
381
- logger.info(' - Different card availability (reviews vs new)');
377
+ logger.print(`\n⚠️ Significant imbalance detected (max deviation: ${maxDeviation.toFixed(1)}%)`);
378
+ logger.print('Possible causes:');
379
+ logger.print(' - Score range differences between sources');
380
+ logger.print(' - One source has much better quality cards');
381
+ logger.print(' - Different card availability (reviews vs new)');
382
382
  }
383
383
 
384
384
  // eslint-disable-next-line no-console
@@ -390,7 +390,7 @@ export const mixerDebugAPI = {
390
390
  */
391
391
  compareScores(): void {
392
392
  if (runHistory.length === 0) {
393
- logger.info('[Mixer Debug] No runs captured yet.');
393
+ logger.print('[Mixer Debug] No runs captured yet.');
394
394
  return;
395
395
  }
396
396
 
@@ -419,8 +419,8 @@ export const mixerDebugAPI = {
419
419
  const avgDiff = Math.max(...avgScores) - Math.min(...avgScores);
420
420
 
421
421
  if (rangeDiff > 0.3 || avgDiff > 0.2) {
422
- logger.info('\n⚠️ Significant score distribution differences detected');
423
- logger.info(
422
+ logger.print('\n⚠️ Significant score distribution differences detected');
423
+ logger.print(
424
424
  'This may cause one source to dominate selection if using global sorting (not quota-based)'
425
425
  );
426
426
  }
@@ -440,24 +440,24 @@ export const mixerDebugAPI = {
440
440
 
441
441
  // eslint-disable-next-line no-console
442
442
  console.group(`🎴 Card: ${cardId}`);
443
- logger.info(`Course: ${card.courseId}`);
444
- logger.info(`Source: ${source?.sourceName || source?.sourceId || 'unknown'}`);
445
- logger.info(`Origin: ${card.origin}`);
446
- logger.info(`Score: ${card.score.toFixed(3)}`);
443
+ logger.print(`Course: ${card.courseId}`);
444
+ logger.print(`Source: ${source?.sourceName || source?.sourceId || 'unknown'}`);
445
+ logger.print(`Origin: ${card.origin}`);
446
+ logger.print(`Score: ${card.score.toFixed(3)}`);
447
447
  if (card.rankInSource) {
448
- logger.info(`Rank in source: #${card.rankInSource}`);
448
+ logger.print(`Rank in source: #${card.rankInSource}`);
449
449
  }
450
450
  if (card.rankInMix) {
451
- logger.info(`Rank in mixed results: #${card.rankInMix}`);
451
+ logger.print(`Rank in mixed results: #${card.rankInMix}`);
452
452
  }
453
- logger.info(`Selected: ${card.selected ? 'Yes ✅' : 'No ❌'}`);
453
+ logger.print(`Selected: ${card.selected ? 'Yes ✅' : 'No ❌'}`);
454
454
 
455
455
  if (!card.selected && card.rankInSource) {
456
- logger.info('\nWhy not selected:');
456
+ logger.print('\nWhy not selected:');
457
457
  if (run.quotaPerSource && card.rankInSource > run.quotaPerSource) {
458
- logger.info(` - Ranked #${card.rankInSource} in source, but quota was ${run.quotaPerSource}`);
458
+ logger.print(` - Ranked #${card.rankInSource} in source, but quota was ${run.quotaPerSource}`);
459
459
  }
460
- logger.info(' - Check score compared to selected cards using .showRun()');
460
+ logger.print(' - Check score compared to selected cards using .showRun()');
461
461
  }
462
462
 
463
463
  // eslint-disable-next-line no-console
@@ -465,7 +465,7 @@ export const mixerDebugAPI = {
465
465
  return;
466
466
  }
467
467
  }
468
- logger.info(`[Mixer Debug] Card '${cardId}' not found in recent runs.`);
468
+ logger.print(`[Mixer Debug] Card '${cardId}' not found in recent runs.`);
469
469
  },
470
470
 
471
471
  /**
@@ -473,7 +473,7 @@ export const mixerDebugAPI = {
473
473
  */
474
474
  listRuns(): void {
475
475
  if (runHistory.length === 0) {
476
- logger.info('[Mixer Debug] No runs captured yet.');
476
+ logger.print('[Mixer Debug] No runs captured yet.');
477
477
  return;
478
478
  }
479
479
 
@@ -496,8 +496,8 @@ export const mixerDebugAPI = {
496
496
  */
497
497
  export(): string {
498
498
  const json = JSON.stringify(runHistory, null, 2);
499
- logger.info('[Mixer Debug] Run history exported. Copy the returned string or use:');
500
- logger.info(' copy(window.skuilder.mixer.export())');
499
+ logger.print('[Mixer Debug] Run history exported. Copy the returned string or use:');
500
+ logger.print(' copy(window.skuilder.mixer.export())');
501
501
  return json;
502
502
  },
503
503
 
@@ -506,14 +506,14 @@ export const mixerDebugAPI = {
506
506
  */
507
507
  clear(): void {
508
508
  runHistory.length = 0;
509
- logger.info('[Mixer Debug] Run history cleared.');
509
+ logger.print('[Mixer Debug] Run history cleared.');
510
510
  },
511
511
 
512
512
  /**
513
513
  * Show help.
514
514
  */
515
515
  help(): void {
516
- logger.info(`
516
+ logger.print(`
517
517
  🎨 Mixer Debug API
518
518
 
519
519
  Commands:
@@ -188,7 +188,7 @@ export function endSessionTracking(): void {
188
188
  */
189
189
  function showCurrentQueue(): void {
190
190
  if (!activeSession) {
191
- logger.info('[Session Debug] No active session.');
191
+ logger.print('[Session Debug] No active session.');
192
192
  return;
193
193
  }
194
194
 
@@ -196,11 +196,11 @@ function showCurrentQueue(): void {
196
196
 
197
197
  // eslint-disable-next-line no-console
198
198
  console.group('📊 Current Queue State');
199
- logger.info(`Supply Queue: ${latest.supplyQLength} cards`);
199
+ logger.print(`Supply Queue: ${latest.supplyQLength} cards`);
200
200
  if (latest.supplyQNext3 && latest.supplyQNext3.length > 0) {
201
- logger.info(` Next: ${latest.supplyQNext3.join(', ')}`);
201
+ logger.print(` Next: ${latest.supplyQNext3.join(', ')}`);
202
202
  }
203
- logger.info(`Failed Queue: ${latest.failedQLength} cards`);
203
+ logger.print(`Failed Queue: ${latest.failedQLength} cards`);
204
204
  // eslint-disable-next-line no-console
205
205
  console.groupEnd();
206
206
  }
@@ -212,17 +212,17 @@ function showPresentationHistory(sessionIndex: number = 0): void {
212
212
  const session = sessionIndex === 0 && activeSession ? activeSession : sessionHistory[sessionIndex];
213
213
 
214
214
  if (!session) {
215
- logger.info(`[Session Debug] No session found at index ${sessionIndex}`);
215
+ logger.print(`[Session Debug] No session found at index ${sessionIndex}`);
216
216
  return;
217
217
  }
218
218
 
219
219
  // eslint-disable-next-line no-console
220
220
  console.group(`📜 Session History: ${session.sessionId}`);
221
- logger.info(`Started: ${session.startTime.toLocaleTimeString()}`);
221
+ logger.print(`Started: ${session.startTime.toLocaleTimeString()}`);
222
222
  if (session.endTime) {
223
- logger.info(`Ended: ${session.endTime.toLocaleTimeString()}`);
223
+ logger.print(`Ended: ${session.endTime.toLocaleTimeString()}`);
224
224
  }
225
- logger.info(`Cards presented: ${session.presentations.length}`);
225
+ logger.print(`Cards presented: ${session.presentations.length}`);
226
226
 
227
227
  if (session.presentations.length > 0) {
228
228
  // eslint-disable-next-line no-console
@@ -249,7 +249,7 @@ function showInterleaving(sessionIndex: number = 0): void {
249
249
  const session = sessionIndex === 0 && activeSession ? activeSession : sessionHistory[sessionIndex];
250
250
 
251
251
  if (!session) {
252
- logger.info(`[Session Debug] No session found at index ${sessionIndex}`);
252
+ logger.print(`[Session Debug] No session found at index ${sessionIndex}`);
253
253
  return;
254
254
  }
255
255
 
@@ -271,7 +271,7 @@ function showInterleaving(sessionIndex: number = 0): void {
271
271
  origins[p.origin]++;
272
272
  });
273
273
 
274
- logger.info('Course distribution:');
274
+ logger.print('Course distribution:');
275
275
  // eslint-disable-next-line no-console
276
276
  console.table(
277
277
  Array.from(courseCounts.entries()).map(([course, count]) => {
@@ -289,12 +289,12 @@ function showInterleaving(sessionIndex: number = 0): void {
289
289
 
290
290
  // Show interleaving pattern (first 20 cards)
291
291
  if (session.presentations.length > 0) {
292
- logger.info('\nPresentation sequence (first 20):');
292
+ logger.print('\nPresentation sequence (first 20):');
293
293
  const sequence = session.presentations
294
294
  .slice(0, 20)
295
295
  .map((p, idx) => `${idx + 1}. ${p.courseName || p.courseId.slice(0, 8)} (${p.origin})`)
296
296
  .join('\n');
297
- logger.info(sequence);
297
+ logger.print(sequence);
298
298
  }
299
299
 
300
300
  // Detect clustering (same course in a row)
@@ -313,8 +313,8 @@ function showInterleaving(sessionIndex: number = 0): void {
313
313
  }
314
314
 
315
315
  if (maxCluster > 3) {
316
- logger.info(`\n⚠️ Detected clustering: max ${maxCluster} cards from same course in a row`);
317
- logger.info('This suggests cards are sorted by score rather than round-robin by course.');
316
+ logger.print(`\n⚠️ Detected clustering: max ${maxCluster} cards from same course in a row`);
317
+ logger.print('This suggests cards are sorted by score rather than round-robin by course.');
318
318
  }
319
319
 
320
320
  // eslint-disable-next-line no-console
@@ -373,11 +373,11 @@ export const sessionDebugAPI = {
373
373
  */
374
374
  listSessions(): void {
375
375
  if (activeSession) {
376
- logger.info(`Active session: ${activeSession.sessionId} (${activeSession.presentations.length} cards presented)`);
376
+ logger.print(`Active session: ${activeSession.sessionId} (${activeSession.presentations.length} cards presented)`);
377
377
  }
378
378
 
379
379
  if (sessionHistory.length === 0) {
380
- logger.info('[Session Debug] No completed sessions in history.');
380
+ logger.print('[Session Debug] No completed sessions in history.');
381
381
  return;
382
382
  }
383
383
 
@@ -402,8 +402,8 @@ export const sessionDebugAPI = {
402
402
  history: sessionHistory,
403
403
  };
404
404
  const json = JSON.stringify(data, null, 2);
405
- logger.info('[Session Debug] Session data exported. Copy the returned string or use:');
406
- logger.info(' copy(window.skuilder.session.export())');
405
+ logger.print('[Session Debug] Session data exported. Copy the returned string or use:');
406
+ logger.print(' copy(window.skuilder.session.export())');
407
407
  return json;
408
408
  },
409
409
 
@@ -412,14 +412,14 @@ export const sessionDebugAPI = {
412
412
  */
413
413
  clear(): void {
414
414
  sessionHistory.length = 0;
415
- logger.info('[Session Debug] Session history cleared.');
415
+ logger.print('[Session Debug] Session history cleared.');
416
416
  },
417
417
 
418
418
  /**
419
419
  * Show help.
420
420
  */
421
421
  help(): void {
422
- logger.info(`
422
+ logger.print(`
423
423
  🎯 Session Debug API
424
424
 
425
425
  Commands:
@@ -170,15 +170,15 @@ const expanded: Record<string, boolean> = {
170
170
  */
171
171
  export function toggleSessionOverlay(): void {
172
172
  if (typeof document === 'undefined') {
173
- logger.info('[Session Overlay] No DOM available (non-browser host); overlay unavailable.');
173
+ logger.print('[Session Overlay] No DOM available (non-browser host); overlay unavailable.');
174
174
  return;
175
175
  }
176
176
  if (overlayEl) {
177
177
  teardown();
178
- logger.info('[Session Overlay] Hidden.');
178
+ logger.print('[Session Overlay] Hidden.');
179
179
  } else {
180
180
  mount();
181
- logger.info('[Session Overlay] Shown. Toggle off with window.skuilder.session.dbgOverlay().');
181
+ logger.print('[Session Overlay] Shown. Toggle off with window.skuilder.session.dbgOverlay().');
182
182
  }
183
183
  }
184
184
 
@@ -303,7 +303,7 @@ function copySnapshot(): void {
303
303
  logger.warn(`[Session Overlay] Clipboard write failed: ${String(err)}`);
304
304
  });
305
305
  } else {
306
- logger.info(`[Session Overlay] Clipboard unavailable; snapshot follows:\n${text}`);
306
+ logger.print(`[Session Overlay] Clipboard unavailable; snapshot follows:\n${text}`);
307
307
  }
308
308
  }
309
309
 
@@ -1,18 +1,82 @@
1
1
  /**
2
2
  * Simple logging utility for @vue-skuilder/db package
3
3
  *
4
- * This utility provides environment-aware logging with ESLint suppressions
5
- * to resolve console statement violations while maintaining logging functionality.
4
+ * Level-gated logging with ESLint suppressions to resolve console statement
5
+ * violations while maintaining logging functionality.
6
+ *
7
+ * Level resolution:
8
+ * - Browser: `localStorage['sk.logLevel']`, else `warn`. Change it live (and
9
+ * persistently) with `window.skuilder.logLevel('info')`.
10
+ * - Node: `SK_LOG_LEVEL`, else `debug` when NODE_ENV=development, else `info`
11
+ * (CLI tools report progress through `info`).
6
12
  */
7
13
 
8
- const isDevelopment = typeof process !== 'undefined' && process.env.NODE_ENV === 'development';
14
+ export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
15
+
16
+ const LEVELS: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
17
+ const STORAGE_KEY = 'sk.logLevel';
18
+
19
+ const isBrowser = typeof window !== 'undefined';
20
+
21
+ function isLevel(v: unknown): v is LogLevel {
22
+ return typeof v === 'string' && v in LEVELS;
23
+ }
24
+
25
+ function initialLevel(): LogLevel {
26
+ if (isBrowser) {
27
+ try {
28
+ const stored = window.localStorage?.getItem(STORAGE_KEY);
29
+ if (isLevel(stored)) return stored;
30
+ } catch {
31
+ // storage blocked (private mode, sandboxed iframe) - fall through
32
+ }
33
+ return 'warn';
34
+ }
35
+ if (typeof process !== 'undefined') {
36
+ const env = process.env.SK_LOG_LEVEL;
37
+ if (isLevel(env)) return env;
38
+ if (process.env.NODE_ENV === 'development') return 'debug';
39
+ }
40
+ return 'info';
41
+ }
42
+
43
+ // tsup builds each db entry point without code splitting, so a consumer can
44
+ // hold several copies of this module. Keep the level on a shared global so
45
+ // `window.skuilder.logLevel(...)` reaches all of them.
46
+ const shared: { level: LogLevel } = ((globalThis as any).__skuilderDbLog ??= {
47
+ level: initialLevel(),
48
+ });
49
+
50
+ export function getLogLevel(): LogLevel {
51
+ return shared.level;
52
+ }
53
+
54
+ /**
55
+ * Set the active log level. In the browser this persists across reloads
56
+ * unless `persist` is false.
57
+ */
58
+ export function setLogLevel(level: LogLevel, persist = true): void {
59
+ if (!isLevel(level)) {
60
+ // eslint-disable-next-line no-console
61
+ console.warn(`[DB] Unknown log level '${level}'. Use one of: ${Object.keys(LEVELS).join(', ')}`);
62
+ return;
63
+ }
64
+ shared.level = level;
65
+ if (isBrowser && persist) {
66
+ try {
67
+ window.localStorage?.setItem(STORAGE_KEY, level);
68
+ } catch {
69
+ // storage blocked - level still applies for this page load
70
+ }
71
+ }
72
+ }
9
73
 
10
74
  export const logger = {
11
75
  /**
12
- * Debug-level logging - only shown in development
76
+ * Debug-level logging
13
77
  */
14
78
  debug: (message: string, ...args: any[]): void => {
15
- if (isDevelopment) {
79
+ if (LEVELS[shared.level] <= LEVELS.debug) {
16
80
  // eslint-disable-next-line no-console
17
81
  console.debug(`[DB:DEBUG] ${message}`, ...args);
18
82
  }
@@ -22,33 +86,68 @@ export const logger = {
22
86
  * Info-level logging - general information
23
87
  */
24
88
  info: (message: string, ...args: any[]): void => {
25
- // eslint-disable-next-line no-console
26
- console.info(`[DB:INFO] ${message}`, ...args);
89
+ if (LEVELS[shared.level] <= LEVELS.info) {
90
+ // eslint-disable-next-line no-console
91
+ console.info(`[DB:INFO] ${message}`, ...args);
92
+ }
27
93
  },
28
94
 
29
95
  /**
30
96
  * Warning-level logging - potential issues
31
97
  */
32
98
  warn: (message: string, ...args: any[]): void => {
33
- // eslint-disable-next-line no-console
34
- console.warn(`[DB:WARN] ${message}`, ...args);
99
+ if (LEVELS[shared.level] <= LEVELS.warn) {
100
+ // eslint-disable-next-line no-console
101
+ console.warn(`[DB:WARN] ${message}`, ...args);
102
+ }
35
103
  },
36
104
 
37
105
  /**
38
106
  * Error-level logging - serious problems
39
107
  */
40
108
  error: (message: string, ...args: any[]): void => {
41
- // eslint-disable-next-line no-console
42
- console.error(`[DB:ERROR] ${message}`, ...args);
109
+ if (LEVELS[shared.level] <= LEVELS.error) {
110
+ // eslint-disable-next-line no-console
111
+ console.error(`[DB:ERROR] ${message}`, ...args);
112
+ }
43
113
  },
44
114
 
45
115
  /**
46
- * Log function for backward compatibility with existing log() usage
116
+ * Log function for backward compatibility with existing log() usage.
117
+ * Debug level.
47
118
  */
48
119
  log: (message: string, ...args: any[]): void => {
49
- if (isDevelopment) {
120
+ if (LEVELS[shared.level] <= LEVELS.debug) {
50
121
  // eslint-disable-next-line no-console
51
122
  console.log(`[DB:LOG] ${message}`, ...args);
52
123
  }
53
124
  },
125
+
126
+ /**
127
+ * Ungated output for interactive console tools (`window.skuilder.*`). The
128
+ * user asked for it, so it prints regardless of level.
129
+ */
130
+ print: (message: string, ...args: any[]): void => {
131
+ // eslint-disable-next-line no-console
132
+ console.log(message, ...args);
133
+ },
54
134
  };
135
+
136
+ /**
137
+ * Mount the level control on window.skuilder.logLevel
138
+ *
139
+ * window.skuilder.logLevel() // current level
140
+ * window.skuilder.logLevel('info') // set + persist
141
+ */
142
+ export function mountLogLevelControl(): void {
143
+ if (!isBrowser) return;
144
+
145
+ const win = window as any;
146
+ win.skuilder = win.skuilder || {};
147
+ win.skuilder.logLevel = (level?: LogLevel): LogLevel => {
148
+ if (level !== undefined) setLogLevel(level);
149
+ return getLogLevel();
150
+ };
151
+ }
152
+
153
+ mountLogLevelControl();
@@ -0,0 +1,36 @@
1
+ import { describe, it, expect, vi } from 'vitest';
2
+ import ELONavigator from '../../../src/core/navigators/generators/elo';
3
+ import type { CourseDBInterface } from '../../../src/core/interfaces/courseDB';
4
+ import type { UserDBInterface } from '../../../src/core/interfaces/userDB';
5
+
6
+ // The generator's retrieval window must be centred on the ELO of the user it
7
+ // runs for, passed explicitly, never resolved by the course DB from its own
8
+ // notion of the current user (`elo: 'user'`).
9
+
10
+ function setup() {
11
+ const getCardsCenteredAtELO = vi.fn().mockResolvedValue([]);
12
+ const course = {
13
+ getCourseID: () => 'c1',
14
+ getCardsCenteredAtELO,
15
+ } as unknown as CourseDBInterface;
16
+ const user = {
17
+ getCourseRegDoc: vi.fn().mockResolvedValue({ courseID: 'c1', elo: 1234 }),
18
+ getActiveCards: vi.fn().mockResolvedValue([]),
19
+ getSeenCards: vi.fn().mockResolvedValue([]),
20
+ } as unknown as UserDBInterface;
21
+ return { gen: new ELONavigator(user, course), getCardsCenteredAtELO };
22
+ }
23
+
24
+ describe('ELONavigator retrieval', () => {
25
+ it("centres on the pipeline context's user ELO", async () => {
26
+ const { gen, getCardsCenteredAtELO } = setup();
27
+ await gen.getWeightedCards(5, { userElo: 987 } as never);
28
+ expect(getCardsCenteredAtELO.mock.calls[0][0]).toEqual({ limit: 5, elo: 987 });
29
+ });
30
+
31
+ it("falls back to its own user's registration, not the course DB's current user", async () => {
32
+ const { gen, getCardsCenteredAtELO } = setup();
33
+ await gen.getWeightedCards(5);
34
+ expect(getCardsCenteredAtELO.mock.calls[0][0]).toEqual({ limit: 5, elo: 1234 });
35
+ });
36
+ });