@01-edu/shared 1.0.6 → 1.0.9

package/README.md

@@ -1,5 +1,31 @@
 # 01-Edu shared library
 
-## `check-definitions` command
+## `check-defs` command
 
+Script used to validate content correctness.
 
+It check the overall structure, attributes and other properties in definitions
+
+It also check the existance of needed `README.md` files
+
+### Usage:
+
+```sh
+# Ensure your current working directory is the repository you want to check
+cd piscine-test
+
+# Normal usage
+npx -y -p '@01-edu/shared' check-defs
+
+# Pinned version
+npx -y -p '@01-edu/shared@v1.0.6' check-defs
+```
+
+#### `-w`, `--watch` param
+
+Will re-check on system events (new, updated, removed files)
+Never exit, just keep waiting for changes to update the report
+
+```sh
+npx -y -p '@01-edu/shared' check-defs --watch
+```

package/attrs-defs.js

@@ -9,7 +9,6 @@ import {
 } from './event-utils.js'
 import { onboardingTypes } from './onboarding.js'
 import { getObjectFromRelativePath } from './path.js'
-import { supportedLang } from './programming-languages.js'
 import { gamesScoring } from './score.js'
 import { hasRequiredSkills, skillsSet } from './skill-definitions.js'
 import {
@@ -49,14 +48,14 @@ const numOrOne = x => (typeof x === 'number' && !Number.isNaN(x) ? x : 1)
 const _difficultyXpCoef = o =>
   o.attrs.difficulty * numOrOne(o.attrs.difficultyMod)
 const add = (a, b) => a + b
-const byValueIdx = ([ak, av], [bk, bv]) => av.index - bv.index
+const byValueIdx = ([_ak, av], [_bk, bv]) => av.index - bv.index
 
 const translate = (object, user, key) =>
   object.attrs[`${key}-${user?.attrs?.language}`] ||
   object.attrs[`${key}-en`] ||
   key
 
-const firstOfGroup = (a, i, children) => {
+const firstOfGroup = (a, _i, children) => {
   const { group } = a.attrs
   if (!group) return true
   return children.find(b => b.attrs.group === group) === a
@@ -65,7 +64,9 @@ const firstOfGroup = (a, i, children) => {
 const getCoreName = object => {
   const corePath = object.attrs.requirements?.core
   const core = _children(object.parent).find(
-    child => child.id === getObjectFromRelativePath(corePath, object)?.id,
+    child =>
+      child.id ===
+      getObjectFromRelativePath(corePath, object, { throwError: false })?.id,
   )
   return core?.name || ''
 }
@@ -122,6 +123,7 @@ const TypeObject = def => ({
 //    value*: // defaultValue ONLY IF the attribute is required, or when it is added,
 //    functions: // if the attribute is associated to function(s) (if just one - it's this by default; if several, by default the user can choose in between them),
 //    label: // text displayed in front end, instead of attribute name (client friendly),
+//    restrictive: // if true, the attribute will be defined only on the object itself and cannot be overridden in the relation to the parent object
 //    instruction: // mention displayed under the label in the front end - to give precision that need to be seen,
 //    description: complete explanation of what the attributes does - description is displayed only when the used hover the ℹ️ icon in the front end,
 //    required: // if the attribute is always there by default,
@@ -212,15 +214,13 @@ attrs.allowedFunctions = {
 const autoValidateLabel = 'Automatic success'
 const autoValidateWhereLabel = `${autoValidateLabel} if`
 const autoRejectWhereLabel = `Automatic reject if`
-const sharedAutoValidationOperator = (action, autoValidationLabel) => ({
+const sharedAutoValidationOperator = action => ({
   type: 'string',
   restrictive: true,
   label: `${action} - number of conditions to fulfil`,
   ...Functions({ all: () => 'and', one: () => 'or' }),
 })
-attrs.autoRejectOperator = {
-  games: sharedAutoValidationOperator('Reject', autoRejectWhereLabel),
-}
+attrs.autoRejectOperator = { games: sharedAutoValidationOperator('Reject') }
 
 const games = Object.entries(gamesScoring)
 const gamesParameters = games.flatMap(([game, params]) => [
@@ -244,10 +244,6 @@ const allParameters = [
   ['level', { shouldFailUnder: 10, shouldSucceedFrom: 25 }],
   ...gamesParameters,
 ]
-const allParametersStr = allParameters
-  .map(([parameter, _]) => breath(parameter))
-  .join(', ')
-  .slice(0, -2)
 
 // TODO: mv to a attrs-utils file
 const isntObjectOrIsEmpty = elem =>
@@ -286,7 +282,7 @@ const checkTextLength = (str, length) => {
 const checkValidURL = value => {
   try {
     return Boolean(new URL(value))
-  } catch (err) {
+  } catch {
     throw Error('Invalid URL.')
   }
 }
@@ -350,9 +346,7 @@ attrs.autoValidate = {
   }),
 }
 
-attrs.autoValidateOperator = {
-  games: sharedAutoValidationOperator('Success', autoValidateWhereLabel),
-}
+attrs.autoValidateOperator = { games: sharedAutoValidationOperator('Success') }
 
 // none of these conditions are required
 types.autoValidateWhereConditions = Object.fromEntries(
@@ -554,20 +548,6 @@ attrs.capacity = {
 }
 
 const exerciseCategories = new Set(['required', 'optional', 'bonus'])
-const projectCategories = new Set(['synchronous', 'enrichment', 'asynchronous'])
-// to check: should we set dynamically the enrichment project category relying
-// on the fact that the object has a valid core project set in its requirements?
-// if so, in the admin interface we have to enforce to select a core project for the enrichment category to be applied
-const projectCategory = Literal('synchronous', {
-  label: 'Category of the project',
-  required: true,
-  options: ['synchronous', 'asynchronous', 'enrichment'],
-  check: value => {
-    if (!projectCategories.has(value)) {
-      throw Error('Must be "synchronous", "asynchronous" or "enrichment"')
-    }
-  },
-})
 relationAttrs.category = {
   // exercises in exams need the category for expected xp calculation
   exam: {
@@ -596,11 +576,7 @@ relationAttrs.category = {
       },
     }),
   },
-  module: { project: { ...projectCategory, editable: true } },
-  piscine: {
-    project: { ...projectCategory, private: true },
-    raid: Literal('required', { required: true, private: true }),
-  },
+  piscine: { raid: Literal('required', { required: true, private: true }) },
 }
 
 // checkbox is not required - sign step can be used without, just to display a text
@@ -956,7 +932,10 @@ const getProjectName = object => {
   // only for projects with a core requirement set, and which name starts by the core name:
   // remove the core name from the name to avoid repetition
   const coreName = getCoreName(object)
-  return name.startsWith(coreName) ? name.slice(coreName.length + 1) : name
+  // TODO: couldn't we just display the key?
+  return coreName && name.startsWith(coreName)
+    ? name.slice(coreName.length + 1)
+    : name
 }
 const sharedDisplayedName = Literal('', {
   editable: true,
@@ -981,7 +960,7 @@ attrs.displayedName = {
 }
 
 const isHackathon = object => object.attrs.special
-const getExerciseDuration = ({ parent, attrs }) =>
+const getExerciseDuration = ({ parent }) =>
   isHackathon(parent)
     ? parent.attrs.duration / Object.keys(parent.children).length
     : 0
@@ -1878,7 +1857,7 @@ attrs.input = {
         }
         try {
           return new RegExp(value)
-        } catch (err) {
+        } catch {
           throw Error('Invalid Regular expression.')
         }
       }
@@ -1892,7 +1871,7 @@ const getInScope = ({ attrs }) => {
 }
 const getProjectInScope = ({ attrs }) => attrs.hasStarted
 const getExamExerciseInScope = ({ parent }) => parent.attrs.inScope
-const getExerciseInScope = ({ parent, attrs, index }) => {
+const getExerciseInScope = ({ parent, attrs }) => {
   if (parent.attrs.inScope) {
     if (isHackathon(parent)) {
       const now = Date.now()
@@ -2024,31 +2003,55 @@ types.objectRootRelativePath = Literal('../', {
   label: 'Content relative path',
   instruction: 'In same parent',
   editable: true,
-  check: getObjectFromRelativePath,
+  check: (path, object) => {
+    try {
+      getObjectFromRelativePath(path, object)
+    } catch (err) {
+      err.userFeedback = `This content relative path (${path}) is invalid, please select a valid content in the list below or remove it.`
+      throw err
+    }
+  },
   options: object => {
     if (!object?.parent?.children) return []
     const sorted = Object.entries(object.parent.children).sort(byValueIdx)
-    const index = sorted.findIndex(([k, v]) => k === object.key)
+    const index = sorted.findIndex(([k]) => k === object.key)
     if (index < 1) return sorted.map(([key, _]) => `../${key}`)
     const before = sorted.slice(0, index)
-    // TODO: add a filter on category and let possibility to select the async after?
-    // const after = sorted.slice(index + 1)
-    // .filter(([k, v]) => v.attrs?.category === 'asynchronous')
-    // return [...before, ...after].map(([key, _]) => `../${key}`)
     return before.map(([key, _]) => `../${key}`).reverse()
   },
 })
 types.sharedObjectList = {
   label: 'Contents', // synonyms: item, material
   editable: true,
-  check: objects => {
+  check: (objects, object) => {
     if (!Array.isArray(objects) || !objects.length) {
-      throw Error('Must be a non empty array')
+      const error = new Error('Must be a non empty array')
+      error.userFeedback =
+        'This list cannot be empty! Please add an item or remove the setting.'
+      throw error
     }
     const uniques = [...new Set(objects)]
     if (objects.length !== uniques.length) {
       throw Error('Duplicates are not allowed.')
     }
+
+    const invalidObjectsRequirements = objects.filter(path => {
+      const objectFromPath = getObjectFromRelativePath(path, object, {
+        throwError: false,
+      })
+      return !objectFromPath
+    })
+
+    if (invalidObjectsRequirements.length) {
+      const paths = invalidObjectsRequirements.map(p => `'${p}'`).join(', ')
+      const error = new Error(
+        `Invalid objects requirements - no object found for the following relative paths: ${paths}`,
+      )
+      error.userFeedback =
+        'Some Contents are misconfigured, please update them!'
+      console.error(error.message)
+      throw error
+    }
   },
 }
 
@@ -2067,6 +2070,25 @@ const contentRequirements = {
     if (!skills && !objects && !core) {
       throw Error('Empty requirements, should be removed')
     }
+
+    const allObjects = core ? [...(objects || []), core] : objects || []
+    const invalidObjectsRequirements = allObjects.filter(path => {
+      const objectFromPath = getObjectFromRelativePath(path, object, {
+        throwError: false,
+      })
+      return !objectFromPath
+    })
+
+    if (invalidObjectsRequirements.length) {
+      const paths = invalidObjectsRequirements.map(p => `'${p}'`).join(', ')
+      const error = new Error(
+        `Invalid objects requirements - no object found for the following relative paths: ${paths}`,
+      )
+      error.userFeedback =
+        'You have some misconfigured Access conditions, please update them!'
+      console.error(error.message)
+      throw error
+    }
   },
 }
 
@@ -2075,7 +2097,7 @@ const levelRequirements = {
   instruction: 'Conditions to unlock and earn this level',
   description:
     'Sets the requirements that have to be met for a level to be unlocked and earned by a student.',
-  check: (requirements, object) => {
+  check: requirements => {
     const { skills, objects, ...rest } = requirements
     if (Object.keys(rest).length) {
       throw Error(`Unsupported attribute "${Object.keys(rest)[0]}"`)
@@ -2187,6 +2209,17 @@ attrs.link = {
   }),
 }
 
+relationAttrs.mandatory = {
+  module: {
+    project: {
+      label: 'Mandatory content to validate the curriculum',
+      type: 'boolean',
+      required: false,
+      editable: true,
+    },
+  },
+}
+
 // TODO: should be required for exam exercises.
 // But it is about to be refactored to define group base on exercise level?
 const maxGroupReducer = (t, c) => Math.max(c.attrs.group || 1, t) // added '|| 1' as group is not required and could be undefined
@@ -2351,7 +2384,7 @@ const getCaptainLogin = ({ group, parent }) => {
 }
 const getRepositoryPath = ({ name, group, parent }, user) =>
   `${getCaptainLogin({ group, parent }) || user.login}/${name}`
-const getExerciseRepositoryPath = ({ attrs, parent, path, group }, user) => {
+const getExerciseRepositoryPath = ({ attrs, parent, group }, user) => {
   const captainLogin = getCaptainLogin({ parent, group })
   return captainLogin
     ? `${captainLogin}/${parent.path.replace(/\/+/g, '-')}`
@@ -2775,7 +2808,7 @@ const getProgressStatus = progress => {
 }
 
 const examExerciseStatus = object => {
-  const { prev, attrs, progress, parent, index, event } = object
+  const { attrs, progress, parent } = object
   const progressStatus = getProgressStatus(progress)
   if (progressStatus) return progressStatus
   if (!parent) return 'available'
@@ -2795,7 +2828,7 @@ const examExerciseStatus = object => {
   return prevValidated ? 'available' : 'blocked'
 }
 const questExerciseStatus = object => {
-  const { prev, attrs, progress, parent, index, event } = object
+  const { prev, attrs, progress, parent } = object
   const progressStatus = getProgressStatus(progress)
   if (progressStatus) return progressStatus
   if (!parent) return 'available'
@@ -2847,8 +2880,10 @@ const hasSucceededRequiredObjects = (requirements, object) => {
     try {
       objectFromPath = getObjectFromRelativePath(relativePath, object)
     } catch {
-      // consider the requirement locked if an error is thrown by getObjectFromRelativePath
-      return false
+      // consider the requirement unlocked if an error is thrown by getObjectFromRelativePath,
+      // because it would mean an admin wrongly set the requirement, probably manually in the db
+      // (it is not possible to set an invalid requirement from the admin configuration interface)
+      return true
     }
     return objectFromPath?.attrs.status === 'succeeded'
   })
@@ -3099,6 +3134,74 @@ const sharedText = Literal('', {
   editable: true,
   ...translatable,
 })
+
+types.teamworkRankName = Literal('', {
+  label: 'Rank name',
+  type: 'string',
+  editable: true,
+  required: true,
+  primary: true,
+  check: (name, object) => {
+    const definitionsWithSameName = object.attrs.teamworkRanks?.filter(
+      rankDefinition => rankDefinition.name === name,
+    )
+    if (definitionsWithSameName?.length > 1) {
+      throw Error(
+        `Name "${name}" is already set for a teamwork rank definition! A given name can only be attributed once to a rank.`,
+      )
+    }
+  },
+})
+
+types.teamworkRankParticipations = Literal(0, {
+  label: 'Group Participations',
+  instruction:
+    'The number of users the student has to work with, to unlock this rank.',
+  editable: true,
+  required: true,
+  options: arrayOf(150, 1),
+  type: 'number',
+  check: (groups, object) => {
+    if (!Number.isInteger(groups)) throw Error('Must be a whole number')
+
+    const definitionsWithSameLevel = object.attrs.teamworkRanks.filter(
+      rankDefinition => rankDefinition.groups === groups,
+    )
+    if (definitionsWithSameLevel?.length > 1) {
+      throw Error(
+        `There is already a rank with ${groups} users required for the rank`,
+      )
+    }
+  },
+})
+
+types.teamworkRanks = TypeObject({
+  type: {
+    name: types.teamworkRankName,
+    groups: types.teamworkRankParticipations,
+  },
+})
+
+attrs.teamworkRanks = {
+  campus: {
+    label: 'Teamwork ranks',
+    instruction: 'List of teamwork ranks',
+    type: [types.teamworkRanks],
+    required: true,
+    editable: true,
+    value: (...args) => [
+      mapValues(types.teamworkRanks.type, subDef =>
+        getDefaultValue(subDef, ...args),
+      ),
+    ],
+    check: teamworkRanks => {
+      if (!teamworkRanks?.length || !Array.isArray(teamworkRanks)) {
+        throw Error('Must be a non empty array')
+      }
+    },
+  },
+}
+
 // TODO: rename it documentToSign, or something more specific than 'text'
 attrs.text = {
   'upload-step': {
@@ -3242,6 +3345,7 @@ types.adminSelectionValidation = TypeObject({
       private: true,
       primary: true,
       label: 'Type',
+      options: ['admin_selection'],
     }),
   },
   label: 'Admin selection evaluation',
@@ -3252,7 +3356,12 @@ const getTesterImage = ({ attrs }) =>
 types.testerValidation = TypeObject({
   label: 'Tester evaluation',
   type: {
-    type: Literal('tester', { required: true, private: true, label: 'Type' }),
+    type: Literal('tester', {
+      required: true,
+      private: true,
+      label: 'Type',
+      options: ['tester'],
+    }),
     testImage: {
       type: 'string',
       label: 'Docker image',
@@ -3281,12 +3390,18 @@ const sharedMatchWhere = {
 }
 // matchWhere for user_audit validations
 // NB: user 1 should always be excluded because he has admin role that can't be removed
+const usersOfCampusWithAdmins = ({ attrs }) => ({
+  campus: { _eq: attrs.campus },
+})
 const userInCampus = ({ attrs }) => ({
   campus: { _eq: attrs.campus },
   _not: { roles: { slug: { _in: ['admin', `campus_admin_${attrs.campus}`] } } },
 })
+const usersInEventWithAdmins = ({ attrs }) => ({
+  events: { eventId: { _eq: attrs.eventId } },
+})
 const userInEvent = ({ attrs }) => ({
-  ...userInCampus({ attrs }),
+  _not: { roles: { slug: { _in: ['admin', `campus_admin_${attrs.campus}`] } } },
   events: { eventId: { _eq: attrs.eventId } },
 })
 
@@ -3355,6 +3470,7 @@ types.adminAuditValidation = TypeObject({
       private: true,
       primary: true,
       label: 'Type',
+      options: ['admin_audit'],
     }),
     delay: types.adminAuditValidationDelay,
     required: types.adminAuditValidationRequired,
@@ -3395,6 +3511,35 @@ types.userAuditValidationRatio = Literal(2, {
   },
 })
 
+types.matchInfluence = TypeObject({
+  label: 'Match Algorithm Influence',
+  editable: true,
+  required: true,
+  instruction: 'Adjust weights in the Match algorithm',
+  type: {
+    auditsRatio: Literal(2.0, {
+      label: 'Current Audit Ratio',
+      editable: true,
+      required: true,
+    }),
+    auditsAssigned: Literal(2.0, {
+      editable: true,
+      required: true,
+      label: 'Fewest Pending Audits',
+    }),
+    levelProximity: Literal(2.0, {
+      editable: true,
+      required: true,
+      label: 'Level Proximity',
+    }),
+    lastAuditAttributed: Literal(2.0, {
+      editable: true,
+      required: true,
+      label: 'Last Audit Attributed',
+    }),
+  },
+})
+
 types.userAuditValidation = TypeObject({
   label: 'User audit evaluation',
   type: {
@@ -3403,15 +3548,19 @@ types.userAuditValidation = TypeObject({
       private: true,
       primary: true,
       label: 'Type',
+      options: ['user_audit'],
     }),
     delay: types.userAuditValidationDelay,
     required: types.userAuditValidationRequired,
     ratio: types.userAuditValidationRatio,
+    matchInfluence: types.matchInfluence,
     matchWhere: {
       ...sharedMatchWhere,
       ...Functions({
         'any user in same campus': userInCampus,
         'any user in same event': userInEvent,
+        'any user in same campus (with admins)': usersOfCampusWithAdmins,
+        'any user in same event (with admins)': usersInEventWithAdmins,
       }),
     },
     form: sharedTypesForm,
@@ -3438,6 +3587,7 @@ types.raidAuditorValidation = TypeObject({
       private: true,
       primary: true,
       label: 'Type',
+      options: ['dedicated_auditors_for_event'],
     }),
     delay: types.adminAuditValidationDelay, // no limit to audit?
     required: types.adminAuditValidationRequired,
@@ -3556,7 +3706,7 @@ const sharedZeroXpIndex = Literal(0, {
   private: true,
 })
 const parentXpIndex = ({ parent }) => parent.attrs.xpIndex
-const getXpIndex = ({ id, name, prev, parent, attrs, type }) => {
+const getXpIndex = ({ prev, parent }) => {
   if (prev) return (prev.attrs.xpIndex || 0) + (_difficultyXpCoef(prev) || 1)
   return parent?.attrs.xpIndex || 0
 }

package/attrs.js

@@ -16,8 +16,8 @@ const typeChecker = (defs, value, object, key) => {
   const { type, check, options } = defs
 
   if (value == null) {
-    if (!defs.required) return true
-    // if no value for required attribute, reject
+    if (!defs.required || defs.value !== undefined) return true
+    // if no value for required attribute without a default value, reject
     throw Error(`missing value for required attribute ${key}`)
   }
 
@@ -33,11 +33,17 @@ const typeChecker = (defs, value, object, key) => {
 
   if (options) {
     const opts = typeof options === 'function' ? options(object) : options
-    const isAnOption = opts.includes(value)
-    if (!isAnOption) {
-      throw Error(
-        `invalid option for ${key}: should be included in ${opts.join(', ')}`,
-      )
+    if (opts.length === 1) {
+      if (opts[0] !== value) {
+        throw Error(`${key} must be ${opts[0]} but was ${value}`)
+      }
+    } else {
+      const isAnOption = opts.includes(value)
+      if (!isAnOption) {
+        throw Error(
+          `invalid option for ${key}: should be included in ${opts.join(', ')}`,
+        )
+      }
     }
   }
 
@@ -111,7 +117,7 @@ const typeChecker = (defs, value, object, key) => {
 // same as attrs with the check & function by name generated and descriptions form markdown files
 export const attributes = mapEntries(attrs, ([attrKey, matches]) => [
   attrKey,
-  mapValues(matches, (defs, type) => ({
+  mapValues(matches, (defs /* type */) => ({
     ...defs,
     check: (value, object) => typeChecker(defs, value, object, attrKey),
   })),
@@ -121,8 +127,8 @@ export const relationAttributes = mapEntries(
   relationAttrs,
   ([attrKey, byParent]) => [
     attrKey,
-    mapValues(byParent, (matches, parentType) =>
-      mapValues(matches, (defs, childType) => ({
+    mapValues(byParent, (matches /* parentType */) =>
+      mapValues(matches, (defs /* childType */) => ({
         ...defs,
         check: (value, object) => typeChecker(defs, value, object, attrKey),
       })),

package/bin/check-definitions.js

@@ -4,6 +4,7 @@ import { readFile, stat, watch } from 'node:fs/promises'
 
 import { checkAndBuildDefinitions } from '../definitions-checker.js'
 
+const rootTypes = ['module', 'piscine', 'sign-up', 'onboarding']
 const isAudit = validation => validation.type.endsWith('_audit')
 const readDef = async key => {
   const path = key == null ? 'content/def.json' : `content/${key}/def.json`
@@ -11,6 +12,12 @@ const readDef = async key => {
   def.attrs || (def.attrs = {})
   def.referencePath = path
 
+  if (key == null && !rootTypes.includes(def.type)) {
+    throw Error(
+      `Root definition must be one of ${rootTypes.join(', ')}, found: ${def.type}`,
+    )
+  }
+
   switch (def.type) {
     case 'project':
     // biome-ignore lint/suspicious/noFallthroughSwitchClause: We want to fallthrough
@@ -54,6 +61,7 @@ if (process.argv.includes('--watch') || process.argv.includes('-w')) {
   await runChecks()
   for await (const event of watch('.', { recursive: true })) {
     console.clear()
+    if (!event.filename.endsWith('def.json')) continue
     console.log(event.eventType, 'on', event.filename, '\n')
     await runChecks()
   }

package/definitions-checker.js

@@ -1,5 +1,5 @@
-import { childTypes, objectTypes } from './toolbox.js'
 import { attributes, relationAttributes } from './attrs.js'
+import { childTypes, objectTypes } from './toolbox.js'
 
 const normalize = str =>
   str
@@ -9,16 +9,8 @@ const normalize = str =>
     .replaceAll(' ', '-')
 
 const assertDef = def => {
-  const {
-    type,
-    name,
-    attrs,
-    children,
-    childrenAttrs,
-    refId,
-    referencePath,
-    ...rest
-  } = def
+  const { type, name, attrs, children, childrenAttrs, referencePath, ...rest } =
+    def
   const [extra] = Object.keys(rest)
   if (extra) {
     throw Error(
@@ -27,11 +19,12 @@ const assertDef = def => {
   }
   if (!objectTypes.has(type)) throw Error(`Invalid type property`)
   if (!name || typeof name !== 'string') throw Error(`Invalid name property`)
-  if (attrs && typeof attrs !== 'object') throw Error(`Invalid attrs property`)
-  if (refId && typeof refId !== 'number') throw Error(`Invalid refId property`)
+  if (!attrs || typeof attrs !== 'object' || Array.isArray(attrs)) {
+    throw Error(`Invalid attrs property`)
+  }
   if (childrenAttrs) throw Error(`childrenAttrs is no longer supported`)
 
-  for (const key of Object.keys(attrs)) {
+  for (const key of Object.keys(attrs || {})) {
     if (relationAttributes[key]) {
       throw Error(
         `Attr ${key} should be defined in the relation with its parent, not on the object itself.`,
@@ -52,16 +45,19 @@ const assertDef = def => {
   }
 }
 
-// TODO: maybe check for circularity here
-// I skipped this check for simplicity and performance
-// because since we already have check that we have a correct parent / child type
-// structure, a circular relation should not be possible
-const buildTree = ({ name, type, attrs, children, referencePath }, parent) => {
+const buildTree = (
+  { name, type, attrs, children, referencePath },
+  parent,
+  depth,
+) => {
+  // As we check for the parent / child type structure, this should never happen
+  // so we did not bother to make a more descriptive error for this case
+  if (depth > 100) throw Error('Unexpected very deep tree, maybe circular ?')
   const object = { name, type, attrs, children: {}, referencePath, parent }
   if (!children) return object
   let prev
   for (const [key, { ref, ...rest }] of Object.entries(children)) {
-    const child = buildTree(ref, object)
+    const child = buildTree(ref, object, (depth || 0) + 1)
     child.attrs = { ...child.attrs, ...rest }
     prev && (prev.next = child)
     child.prev = prev
@@ -73,7 +69,9 @@ const buildTree = ({ name, type, attrs, children, referencePath }, parent) => {
 const assertRelation = (parent, key, relation) => {
   if (!/^[a-z0-9-]*$/.test(key)) {
     throw Error(
-      `Invalid key for child ${key} Kebab-case key suggestion: ${normalize(key)}`,
+      `Invalid key for child ${key} Kebab-case key suggestion: ${normalize(
+        key,
+      )}`,
     )
   }
 
@@ -176,7 +174,10 @@ export const checkAndBuildDefinitions = async readDef => {
   const getDefs = async ([key, relation]) => {
     let def
     try {
-      def = cache[key] || (cache[key] = await readDef(key))
+      const cached = cache[key]
+      def = await (cached || (cache[key] = readDef(key)))
+      relation && (relation.ref = def)
+      if (cached) return [] // skip assert and children checks if already cached
     } catch (err) {
       err.name = key
       throw err
@@ -188,11 +189,12 @@ export const checkAndBuildDefinitions = async readDef => {
       err.referencePath = def.referencePath
       throw err
     }
-    relation && (relation.ref = def)
     const relations = Object.entries(def.children || {}).map(getDefs)
     try {
       return [def, ...(await Promise.all(relations)).flat()]
     } catch (err) {
+      // Some content may be used at multiple place (ex: exam exercises)
+      // so we may have multiple parents
       key && (err.parents || (err.parents = [])).push(key)
       throw err
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@01-edu/shared",
-  "version": "1.0.6",
+  "version": "1.0.9",
   "type": "module",
   "description": "",
   "scripts": {
@@ -21,7 +21,7 @@
     "./skill-definitions.js",
     "./toolbox.js"
   ],
-  "license": "MIT",
+  "license": "Fair",
   "bin": {
     "check-defs": "./bin/check-definitions.js"
   },

package/path.js

@@ -39,15 +39,23 @@ const walk = (object, segment) => {
 }
 
 /**
- * @returns {Object} the object in the relative path
- * @argument relativePath {string} a relative path
- * @argument currentObj {Object} the object from where the relative path starts
+ * @param {string} relativePath - a relative path
+ * @param {Object} currentObj - the object from where the relative path starts
+ * @param {Object} [opts = { throwError: true } ] - options object with boolean property `throwError` to throw an error in case the path is invalid or no object is found
+ * @returns {Object} - the object in the relative path
  */
-export const getObjectFromRelativePath = (relativePath, currentObj) => {
+export const getObjectFromRelativePath = (
+  relativePath,
+  currentObj,
+  opts = { throwError: true },
+) => {
   const currentPath = currentObj.path
   if (isAbsolutePath(relativePath)) {
-    throw Error("'relativePath' must be a relative path")
+    if (opts.throwError) throw Error("'relativePath' must be a relative path")
+    console.error("'relativePath' must be a relative path")
+    return undefined
   }
+
   // Ignore trailing `/` in the relative path
   if (relativePath[relativePath.length - 1] === '/') {
     relativePath = relativePath.slice(0, -1)
@@ -55,9 +63,11 @@ export const getObjectFromRelativePath = (relativePath, currentObj) => {
 
   const matchingObject = relativePath.split('/').reduce(walk, currentObj)
   if (matchingObject) return matchingObject
-  throw Error(
-    `Incorrect relative path '${relativePath}': no object found — current path = '${currentPath}'`,
-  )
+
+  const errorMessage = `Incorrect relative path '${relativePath}': no object found — current path = '${currentPath}'`
+  if (opts.throwError) throw Error(errorMessage)
+  console.error(errorMessage)
+  return undefined
 }
 
 const isAbsolutePath = path => path.startsWith('/')

package/toolbox.js

@@ -182,15 +182,17 @@ export const formatedDuration = (seconds, { noSeconds } = {}) => {
 }
 
 const toDate = date => (date instanceof Date ? date : new Date(date))
-export const toDateFormat = d => {
+export const toDateFormat = (d, isISO = true) => {
   const date = toDate(d)
   const month = (date.getMonth() + 1).toString().padStart(2, '0')
   const day = date.getDate().toString().padStart(2, '0')
 
-  return `${date.getFullYear()}-${month}-${day}`
+  return isISO
+    ? `${date.getFullYear()}-${month}-${day}`
+    : `${day}/${month}/${date.getFullYear()}`
 }
 
-export const toISOStringWithTimeZone = d => toDate(d).toISOString().slice(0, -1)
+export const toISOStringWithTimeZone = d => toDate(d).toISOString()
 
 export const toDateFormatWithTime = (d, separator = 'T') => {
   const date = toDate(d)
@@ -220,7 +222,7 @@ export const monthNames = [
   'Dec',
 ]
 
-const weekDays = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
+export const weekDays = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
 
 const hour = hour => {
   if (hour === 0 || hour === 12) return 12
@@ -256,12 +258,12 @@ const getDateElems = date => {
   return { day, jj, mm, yyyy, hh, min }
 }
 
-export const formatedDateTime = date => {
+export const formatedDateTime = (date, splitter = 'at') => {
   if (!date) return '-'
   if (dateIsPermanent(date)) return '∞'
   const { jj, mm, yyyy, hh, min } = getDateElems(date)
 
-  return `${monthNames[mm]} ${jj}, ${yyyy} at ${hour(hh)}:${minPad(
+  return `${monthNames[mm]} ${jj}, ${yyyy} ${splitter} ${hour(hh)}:${minPad(
     min,
   )} ${suffix(hh)}`
 }
@@ -337,13 +339,12 @@ const toSnakeCase = str =>
 // id card > id-card
 // should be enough for unique usage we have of it in check-refs
 // checked the perfs and it is faster + more secure than using replace(s) + toLowerCase
-const toLowerCase = x => x.toLowerCase()
 export const toKebabCase = str =>
   str
     .match(
       /[A-Z](?=[A-Z][a-z]+[0-9]*[a-z]|\b)|[A-Z]?[a-z]+[0-9]+[a-z]?[A-Z]*|[A-Z]?[a-z]+[0-9]*|[A-Z]|[0-9]+/g,
     )
-    .map(toLowerCase)
+    .map(x => x.toLowerCase())
     .join('-')
 
 const spaceJoin = (_, a, b) => `${a} ${b}`
@@ -481,3 +482,18 @@ export const base64Encode = str => {
 
 export const timePlusDelay = (time, delay) =>
   new Date(new Date(time).getTime() + delay).toISOString()
+
+export const getRecordStatus = record => {
+  if (!isFinished(record.startAt)) return 'starting soon'
+  if (record.endAt && isFinished(record.endAt)) {
+    return 'finished'
+  }
+  if (record.type.isPermanent) return 'permanent'
+  return record.endAt ? 'in progress' : 'unblock required'
+}
+
+export const createFrequencyMap = arr =>
+  arr.reduce((map, item) => {
+    map[item] = (map[item] || 0) + 1
+    return map
+  }, {})