diff --git a/design/author.md b/design/author.md index 1cde0e91..29aedc02 100644 --- a/design/author.md +++ b/design/author.md @@ -377,6 +377,18 @@ text to the content check's rules, and `apps/skills` plays every example untrust `*10:30*` as written is not refused: it is a tip to the library and may be one to its author. Over the 94 real packages of the owner's corpus and the demo, the two checks report nothing. +- **What builds and is almost surely a mistake is a note** (#241, item 4 of #219). H5P allows + each, so none is a problem, and nothing is judged: no answer marked correct (Multiple Choice's + answers, Multimedia Choice's options; Find the Hotspot's areas are refused already), two + answers or statements alike as a learner reads them, without tags or entities and in any case + (Multiple Choice, a Single Choice Set question, a Summary set), a text with no gap (Fill in the + Blanks, Drag the Words, Mark the Words), and a picture with no alt text where its field is + optional (`ALT_TEXTS`, held to the pack's fields by `build.test.ts`; H5P.Image's is required). + Each says what to write. `lib/mistakes.mjs` runs in `checkContent`, so a build says them and so + does a check of saved content, and every type file's example says none. Of the owner's 88 real + packages, the 79 checked against their own libraries give 36 notes of a picture with no alt + text in 8 packages, and 4 of answers alike in one, a test whose answers all read "Test"; no + question with no answer marked correct, and no text with no gap. - **The hand-over carries the source and one web address, the build page's plain one** (#190, #215, the owner's calls). Beside the package, the hand-over gives the source as a file named after the package with `.source.json`, and one fixed line saying to open that file on the build @@ -454,4 +466,5 @@ text to the content check's rules, and `apps/skills` plays every example untrust Not built: changing a package in place, which a tool beside it does with `checkContent` as its check (a package is changed by reading it into a source and building that); reading content made for another version of a library than the pack's; layout for Drag and Drop and Crossword; and any -judgement of whether content is right, which stays the person's, in the verifier's preview. +judgement of whether content is right beyond those notes, which stays the person's, in the +verifier's preview. diff --git a/design/layout.md b/design/layout.md index b4557914..640363f4 100644 --- a/design/layout.md +++ b/design/layout.md @@ -29,7 +29,8 @@ packages/verify/ a package played headless (lib/verify.mjs) and in a brows (lib/preview.mjs); lib/serve.mjs what both share, which the extension bundles packages/author/ a playable .h5p from a short source: lib/build.mjs both builds, node.mjs Node's, generator.mjs content from semantics, check.mjs, outline.mjs, - types.mjs the editor widgets' rules, read.mjs a package back to a source; + types.mjs the editor widgets' rules, mistakes.mjs the notes of what is + almost surely a mistake, read.mjs a package back to a source; scripts/ the skill's sync and copy packages/mcp/ the local MCP server: bin/h5p-mcp.mjs the command, lib/server.mjs its four tools, lib/folders.mjs the folders it may use diff --git a/packages/author/README.md b/packages/author/README.md index edc2ef94..a840d415 100644 --- a/packages/author/README.md +++ b/packages/author/README.md @@ -318,8 +318,8 @@ checks every value against its field, as the build does, and takes what H5P save sub-content metadata, held to what the platforms keep of them, and each part's `subContentId`, which the core names the part's statements by, so a learner's record stays the part's after an edit; a part without one, or with another part's, gets a new one. It places what nobody placed and checks what a -content type's editor would, as the build does, and returns the content as checked with `problems` -and `notes`, each `{ path, message }`. Where the content names an older minor of a library than the +content type's editor would, as the build does, notes what is almost surely a mistake, and returns +the content as checked with `problems` and `notes`, each `{ path, message }`. Where the content names an older minor of a library than the one it is checked against, a field only that minor has is a note: the player upgrades such content as it plays. Content saved by the platforms can hold what their editor let an author save and the build does not, such as a required text left empty; a tool that changes one part keeps the problems under @@ -375,8 +375,10 @@ the package's main export has them. A tool beside a build in either imports it f ## What it does not do -It checks structure, not pedagogy: whether the answers are right, the questions fair, or the -pictures placed well is for a person to judge, in +It checks structure, not pedagogy. In the content types where it looks for them, it notes what H5P +allows and is almost surely a mistake: no answer marked correct, two answers or statements alike, a +text with no gap, an optional alt text left blank beside a picture. Whether +the answers are right, the questions fair, or the pictures placed well is for a person to judge, in [h5p-verify](https://www.npmjs.com/package/@missing-elements/h5p-verify)'s `--preview`. It changes an existing package only by way of its source, read and built again; `checkContent` is the check for a tool that changes one in place. The licence of each library is in the pack's `libraries.txt`. diff --git a/packages/author/lib/check.mjs b/packages/author/lib/check.mjs index 780e1554..1188df05 100644 --- a/packages/author/lib/check.mjs +++ b/packages/author/lib/check.mjs @@ -1,10 +1,11 @@ import { ContentGenerator, libraryString } from './generator.mjs' +import { noteMistakes } from './mistakes.mjs' import { LAYOUTS, placesOf } from './types.mjs' /** * Content checked in the form H5P stores it, as the build checks what it writes: every value - * against its field in the libraries' semantics, the hidden fields the editor's widgets set, and - * what those widgets would not let an author save. A tool that changes a saved package runs it on + * against its field in the libraries' semantics, the hidden fields the editor's widgets set, what + * those widgets would not let an author save, and, as notes, what is almost surely a mistake. A tool that changes a saved package runs it on * what it is about to write, and the build runs it last, on what it is about to write, so that the * two hold content to one set of rules. No Node import of its own: the libraries are handed in. */ @@ -90,6 +91,8 @@ export function checkContent(libraries, { type, params }) { const layout = layoutContext(entries, report, note) const places = placesOf(main.library.machineName, content) for (const place of places) LAYOUTS[place.library]?.after?.(place.params, place.path, layout(place.library)) + // What builds and is almost surely a mistake, which H5P allows: a note, never a problem (#241). + for (const place of places) noteMistakes(place.library, place.params, place.path, note) for (const place of places) { if (place.holder && isObject(place.holder.metadata) && place.holder.metadata.title === undefined) place.holder.metadata.title = place.holder.metadata.contentType } diff --git a/packages/author/lib/mistakes.mjs b/packages/author/lib/mistakes.mjs new file mode 100644 index 00000000..49326ae7 --- /dev/null +++ b/packages/author/lib/mistakes.mjs @@ -0,0 +1,141 @@ +import { decodeEntities, stripTags } from './text.mjs' +import { blanksGaps } from './types.mjs' + +/** + * What builds and is almost surely a mistake (#241, item 4 of #219): no answer marked correct, two + * answers alike, a text with no gap, a picture with no alt text where its field is optional. H5P + * allows each, so each is a note and not a problem, and nothing about the content is judged: whether + * an answer is right stays the person's. Run by `checkContent` on content as H5P stores it, so a + * build says them, and so does a check of saved content. + */ + +/** @typedef {(path: string, message: string) => void} Note */ + +/** @param {unknown} value @returns {value is Record} */ +const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) + +/** + * A text as a learner reads it, to compare one with another: no tags or entities, and in one case + * and spacing. + * @param {unknown} value + */ +function plain(value) { + return typeof value === 'string' ? decodeEntities(stripTags(value)).replace(/\s+/g, ' ').trim().toLowerCase() : '' +} + +/** + * Each item of a list that reads as an earlier one does. + * @param {unknown} items + * @param {(item: any) => unknown} textOf the text of an item + * @param {string} at the list's path + * @param {string} what what an item is to a learner, as "answer" + * @param {Note} note + */ +function alike(items, textOf, at, what, note) { + if (!Array.isArray(items)) return + /** @type {Map} */ + const first = new Map() + items.forEach((item, i) => { + const text = plain(textOf(item)) + if (!text) return + const earlier = first.get(text) + if (earlier === undefined) first.set(text, i) + else note(`${at}[${i}]`, `reads as ${at.slice(at.lastIndexOf('.') + 1)}[${earlier}] does, so a learner sees the same ${what} twice`) + }) +} + +/** + * Whether a list marks no item correct, where it has items. + * @param {unknown} items + */ +const noneCorrect = (items) => Array.isArray(items) && items.length > 0 && !items.some((item) => isObject(item) && item.correct === true) + +/** A text with no gap, `*word*`, in it, as Drag the Words and Mark the Words find one. @param {unknown} text */ +const gapless = (text) => typeof text === 'string' && !/\*[^*]+\*/.test(text) + +/** + * Pictures whose alt text is an optional field beside them, by content type: the group that holds + * both, as a path in the type's parameters (`[]` for each item of a list), the picture's field, and + * its alt text's. H5P.Image's alt text is required, so a build refuses one without it already. + * @type {Record} + * @internal + */ +export const ALT_TEXTS = { + 'H5P.BranchingScenario': [['branchingScenario.startScreen', 'startScreenImage', 'startScreenAltText']], + 'H5P.Dialogcards': [['dialogs[]', 'image', 'imageAltText']], + 'H5P.Flashcards': [['cards[]', 'image', 'imageAltText']], + 'H5P.ImageHotspots': [['', 'image', 'backgroundImageAltText']], + 'H5P.ImagePair': [['cards[]', 'match', 'matchAlt']], + 'H5P.MemoryGame': [['cards[]', 'match', 'matchAlt']], + 'H5P.QuestionSet': [['introPage', 'backgroundImage', 'backgroundImageAltText']], + 'H5P.SpeakTheWordsSet': [['introduction', 'introductionImage', 'introductionImageAltText']] +} + +/** + * The groups at a path in parameters, `[]` taking each item of a list, with their paths. + * @param {unknown} value + * @param {string} path + * @param {string} at the value's own path + * @returns {{ group: Record, at: string }[]} + */ +function groupsAt(value, path, at) { + if (!isObject(value)) return [] + if (!path) return [{ group: value, at }] + const [head, ...rest] = path.split('.') + const name = head.replace(/\[\]$/, '') + const next = value[name] + if (head.endsWith('[]')) return Array.isArray(next) ? next.flatMap((item, i) => groupsAt(item, rest.join('.'), `${at}.${name}[${i}]`)) : [] + return groupsAt(next, rest.join('.'), `${at}.${name}`) +} + +/** + * The checks of each content type, on its parameters as H5P stores them. + * @type {Record, path: string, note: Note) => void>} + */ +const CHECKS = { + 'H5P.MultiChoice'(params, path, note) { + if (noneCorrect(params.answers)) note(`${path}.answers`, 'marks no answer correct, so no learner can score: set "correct": true on the right one') + alike(params.answers, (answer) => answer?.text, `${path}.answers`, 'answer', note) + }, + 'H5P.MultiMediaChoice'(params, path, note) { + if (noneCorrect(params.options)) note(`${path}.options`, 'marks no option correct, so no learner can score: set "correct": true on the right one') + }, + 'H5P.SingleChoiceSet'(params, path, note) { + if (!Array.isArray(params.choices)) return + params.choices.forEach((choice, i) => alike(choice?.answers, (answer) => answer, `${path}.choices[${i}].answers`, 'answer', note)) + }, + 'H5P.Summary'(params, path, note) { + if (!Array.isArray(params.summaries)) return + params.summaries.forEach((set, i) => alike(set?.summary, (statement) => statement, `${path}.summaries[${i}].summary`, 'statement', note)) + }, + 'H5P.Blanks'(params, path, note) { + const texts = Array.isArray(params.questions) ? params.questions.filter((text) => typeof text === 'string') : [] + if (texts.length && texts.every((text) => !blanksGaps(text).length)) note(`${path}.questions`, 'has no gap, so a learner has nothing to fill in: put each answer between asterisks, as *Paris*') + }, + 'H5P.DragText'(params, path, note) { + if (gapless(params.textField)) note(`${path}.textField`, 'has no gap, so a learner has no word to drag: put each word between asterisks, as *Paris*') + }, + 'H5P.MarkTheWords'(params, path, note) { + if (gapless(params.textField)) note(`${path}.textField`, 'marks no word, so a learner has none to find: put each word to find between asterisks, as *Paris*') + } +} + +/** + * What a content type's parameters hold that builds and is almost surely a mistake, noted. + * @param {string} library its machine name + * @param {unknown} params as H5P stores them + * @param {string} path theirs + * @param {Note} note + * @internal + */ +export function noteMistakes(library, params, path, note) { + if (!isObject(params)) return + CHECKS[library]?.(params, path, note) + for (const [group, picture, alt] of ALT_TEXTS[library] ?? []) { + for (const { group: values, at } of groupsAt(params, group, path)) { + const file = values[picture] + if (!isObject(file) || typeof file.path !== 'string' || !file.path.trim() || plain(values[alt])) continue + note(`${at}.${alt}`, `is not written, so a screen reader has nothing to say of the picture in ${picture}: write what it shows`) + } + } +} diff --git a/packages/author/lib/types.mjs b/packages/author/lib/types.mjs index 43b51587..dbe8f3c5 100644 --- a/packages/author/lib/types.mjs +++ b/packages/author/lib/types.mjs @@ -713,7 +713,7 @@ const imageHotspotQuestion = { * @param {string} question * @returns {{ raw: string, content: string }[]} each gap as written, asterisks included, and what the library reads of it */ -function blanksGaps(question) { +export function blanksGaps(question) { const gaps = [] let start = question.indexOf('*') while (start !== -1) { diff --git a/packages/author/tests/build.test.ts b/packages/author/tests/build.test.ts index 8c1522fc..7be540ed 100644 --- a/packages/author/tests/build.test.ts +++ b/packages/author/tests/build.test.ts @@ -14,6 +14,7 @@ import { buildPackage, librariesIn, missingForInstall, SourceError, sourceSchema import { readSource } from '../lib/build.mjs' import { LICENSES } from '../lib/metadata.mjs' import { MediaStore } from '../lib/media.mjs' +import { ALT_TEXTS } from '../lib/mistakes.mjs' import { nodeMedia } from '../lib/node.mjs' import { quizProblems } from '../lib/quiz.mjs' import { jpeg, mp4, png } from './helpers/media' @@ -578,6 +579,99 @@ describe('any content type in the pack', () => { }) }) +describe('notes for what builds and is almost surely a mistake (#241)', () => { + /** The notes a build of a source gives, writing nothing. */ + async function notesOf(source: unknown, base?: string) { + return (await buildPackage(source, undefined, { check: true, ...(base ? { base } : {}) })).notes + } + + it('says where no answer is marked correct, or two read alike, wherever the question sits', async () => { + const question = { question: 'Which river is the longest in Europe?', answers: [{ text: 'Volga' }, { text: 'volga ' }, { text: 'Danube' }] } + expect(await notesOf({ ...META, type: 'H5P.MultiChoice', params: question })).toEqual([ + { path: 'params.answers', message: 'marks no answer correct, so no learner can score: set "correct": true on the right one' }, + { path: 'params.answers[1]', message: 'reads as answers[0] does, so a learner sees the same answer twice' } + ]) + // In a set, by the sub-content's path; one marked correct is enough. + const fine = { question: 'Which river flows through Paris?', answers: [{ text: 'Seine', correct: true }, { text: 'Loire' }] } + expect(await notesOf({ ...META, type: 'H5P.QuestionSet', params: { questions: [{ library: 'H5P.MultiChoice', params: fine }, { library: 'H5P.MultiChoice', params: question }] } })).toEqual([ + { path: 'params.questions[1].params.answers', message: 'marks no answer correct, so no learner can score: set "correct": true on the right one' }, + { path: 'params.questions[1].params.answers[1]', message: 'reads as answers[0] does, so a learner sees the same answer twice' } + ]) + // Entities and spacing read as a learner reads them. + expect(await notesOf({ ...META, type: 'H5P.SingleChoiceSet', params: { choices: [{ question: 'Which sea does the Danube reach?', answers: ['Black Sea', 'North Sea', 'Black Sea'] }, { question: 'Which river flows through Paris?', answers: ['Seine', 'Loire'] }] } })).toEqual([ + { path: 'params.choices[0].answers[2]', message: 'reads as answers[0] does, so a learner sees the same answer twice' } + ]) + expect(await notesOf({ ...META, type: 'H5P.Summary', params: { summaries: [{ summary: ['Rivers flow downhill.', 'Rivers flow uphill.', 'Rivers flow downhill.'] }] } })).toEqual([ + { path: 'params.summaries[0].summary[2]', message: 'reads as summary[0] does, so a learner sees the same statement twice' } + ]) + }) + + it('says where a choice of pictures marks none correct', async () => { + const at = await mkdtemp(join(dir, 'pictures-')) + await writeFile(join(at, 'delta.png'), png(64, 48)) + await writeFile(join(at, 'spring.png'), png(64, 48)) + const option = (path: string, alt: string) => ({ media: { library: 'H5P.Image', params: { file: { path }, alt } } }) + expect(await notesOf({ ...META, type: 'H5P.MultiMediaChoice', params: { question: 'Which picture shows a river delta?', options: [option('delta.png', 'A delta'), option('spring.png', 'A spring')] } }, at)).toEqual([ + { path: 'params.options', message: 'marks no option correct, so no learner can score: set "correct": true on the right one' } + ]) + }) + + it('says where a text has no gap to fill in, drag a word to or find', async () => { + expect(await notesOf({ ...META, type: 'H5P.Blanks', params: { questions: ['The Danube flows into the Black Sea.', 'Paris lies on the Seine.'] } })).toEqual([ + { path: 'params.questions', message: 'has no gap, so a learner has nothing to fill in: put each answer between asterisks, as *Paris*' } + ]) + // One text with a gap is enough: the others may lead in. + expect(await notesOf({ ...META, type: 'H5P.Blanks', params: { questions: ['Rivers of Europe.', 'The *Danube* flows into the Black Sea.'] } })).toEqual([]) + expect(await notesOf({ ...META, type: 'H5P.DragText', params: { textField: 'The Danube flows into the Black Sea.' } })).toEqual([ + { path: 'params.textField', message: 'has no gap, so a learner has no word to drag: put each word between asterisks, as *Paris*' } + ]) + expect(await notesOf({ ...META, type: 'H5P.MarkTheWords', params: { taskDescription: 'Click every name of a river.', textField: 'The Danube rises in the Black Forest.' } })).toEqual([ + { path: 'params.textField', message: 'marks no word, so a learner has none to find: put each word to find between asterisks, as *Paris*' } + ]) + }) + + it('says where a picture has no alt text, where its field is optional', async () => { + const at = await mkdtemp(join(dir, 'alt-')) + await writeFile(join(at, 'river.png'), png(64, 48)) + await writeFile(join(at, 'bridge.png'), png(64, 48)) + expect(await notesOf({ ...META, type: 'H5P.Dialogcards', params: { dialogs: [ + { text: 'the river', answer: 'der Fluss', image: { path: 'river.png' }, imageAltText: 'A river between hills' }, + { text: 'the bridge', answer: 'die Brücke', image: { path: 'bridge.png' } }, + { text: 'the bank', answer: 'das Ufer' } + ] } }, at)).toEqual([ + { path: 'params.dialogs[1].imageAltText', message: 'is not written, so a screen reader has nothing to say of the picture in image: write what it shows' } + ]) + // A card's matching picture: only where there is one. + expect(await notesOf({ ...META, type: 'H5P.MemoryGame', params: { cards: [ + { image: { path: 'river.png' }, imageAlt: 'A river', match: { path: 'bridge.png' } }, + { image: { path: 'bridge.png' }, imageAlt: 'A bridge' } + ] } }, at)).toEqual([ + { path: 'params.cards[0].matchAlt', message: 'is not written, so a screen reader has nothing to say of the picture in match: write what it shows' } + ]) + }) + + it('names, for each picture with an optional alt text, fields the pack has: a picture, and an optional text beside it', async () => { + type Semantic = { name: string, type: string, optional?: boolean, field?: Semantic, fields?: Semantic[] } + for (const [machineName, pictures] of Object.entries(ALT_TEXTS)) { + const library = pack.libraries.filter((each) => each.machineName === machineName).sort((a, b) => b.majorVersion - a.majorVersion || b.minorVersion - a.minorVersion)[0] + expect(library, machineName).toBeTruthy() + const { files } = await archive(new URL(library.url)) + let fields: Semantic[] = JSON.parse(files.get(`${library.folder}/semantics.json`)!) + for (const [group, picture, alt] of pictures) { + let level = fields + for (const name of group ? group.replace(/\[\]/g, '').split('.') : []) { + const field = level.find((each) => each.name === name) + expect(field, `${machineName} ${group}`).toBeTruthy() + level = field!.type === 'list' ? (field!.field!.fields ?? []) : (field!.fields ?? []) + } + expect(level.find((each) => each.name === picture)?.type, `${machineName} ${group}.${picture}`).toBe('image') + expect(level.find((each) => each.name === alt), `${machineName} ${group}.${alt}`).toMatchObject({ type: 'text', optional: true }) + } + fields = [] + } + }) +}) + describe('media', () => { let server: Server let origin: string