From b35d6bfc4118917d6f3ebbce2aaba79c9703e0ba Mon Sep 17 00:00:00 2001 From: Aleksandr Shevchuk Date: Mon, 2 Nov 2026 22:00:02 +0200 Subject: [PATCH] feat(h5p-author): a check of saved content, which the build runs last (#107) checkContent(libraries, { type, params }) checks content in the form H5P saves it, as the build checks what it writes: files and sub-content metadata as saved, held to what the platforms keep of them; each part's subContentId kept, a new one only for a part without one, with one H5P would not keep or with an earlier part's; a markup field's text not wrapped again. The layouts' after hooks, the empty titles and the unset fields moved into it, and the build runs it last on what it writes. Game Map's before keeps only the conversion of a source's numbers and labels; its checks run on the stored form. packageLibraries(files, pack) serves a package's own libraries where it carries a major, the pack's otherwise, by the player's ownLibraries. Where the content names another minor than the one checked against, a field only that minor has is noted and kept. A group that is sub-content now gets an id in a build, as the editor's initSubContent gives one. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 90 ++++++++--- apps/skills/tests/author-verify.test.ts | 32 +++- packages/author/README.md | 43 ++++- packages/author/lib/author.mjs | 10 +- packages/author/lib/build.mjs | 70 ++++---- packages/author/lib/check.mjs | 115 ++++++++++++++ packages/author/lib/generator.mjs | 202 +++++++++++++++++++++--- packages/author/lib/libraries.mjs | 67 +++++++- packages/author/lib/metadata.mjs | 42 +++++ packages/author/lib/text.mjs | 6 +- packages/author/lib/types.mjs | 68 ++++---- packages/author/tests/check.test.ts | 194 +++++++++++++++++++++++ packages/author/tests/generator.test.ts | 119 +++++++++++++- packages/author/tests/package-types.ts | 22 ++- 14 files changed, 943 insertions(+), 137 deletions(-) create mode 100644 packages/author/lib/check.mjs create mode 100644 packages/author/lib/metadata.mjs create mode 100644 packages/author/tests/check.test.ts diff --git a/AGENTS.md b/AGENTS.md index 20165847..2a77be5a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -184,28 +184,35 @@ packages/author/ @missing-elements/h5p-author — a playable .h5p of an source, published as a command (see *The author package*) bin/h5p-author.mjs the command: `build` and `schema` lib/build.mjs the source read and checked, the libraries loaded, the content generated, - media copied, layouts run, the parts planned with the player's `planPack`, - the archive written + media copied, the content checked as saved, the parts planned with the + player's `planPack`, the archive written + lib/check.mjs `checkContent`: content in the form H5P saves it checked, the layouts' `after` + run, for a tool that edits a saved package and for the build, which runs it + last on what it writes (#107); no Node import of its own lib/libraries.mjs `loadLibraries`: the libraries content brings in, loaded and localized as - the build loads them, for the build and for a tool beside it; no Node + the build loads them, for the build and for a tool beside it; + `packageLibraries`, a package's own over the pack's (#107); no Node import of its own, nor has lib/source-error.mjs, `SourceError` (#106) lib/generator.mjs `ContentGenerator`: content from a type's `semantics.json`, authoring - (every written value checked as the editor's form would) or lenient, as - the sweep runs it; moved out of the demo on 2026-11-01 (#100) + (every written value checked as the editor's form would), lenient, as + the sweep runs it, or saved, as `checkContent` runs it; moved out of the + demo on 2026-11-01 (#100) lib/types.mjs what the editor's own widgets set and check, per content type: Course Presentation's layout, Interactive Video's placement, Branching Scenario's paths, Game Map's stages, Find the Hotspot's areas - lib/text.mjs, translate.mjs, media.mjs, pack.mjs, schema.mjs, quiz.mjs text as H5P stores it; the - libraries' translations; files and web addresses; the pinned pack read - by part; the field list a source is written from; the first skill's - quiz format, still built + lib/text.mjs, translate.mjs, media.mjs, metadata.mjs, pack.mjs, schema.mjs, quiz.mjs text as H5P + stores it; the libraries' translations; files and web addresses; the + licences and roles H5P's metadata takes; the pinned pack read by part; + the field list a source is written from; the first skill's quiz format, + still built scripts/ sync-skill.mjs writes the skill's type files' generated sections from the pack (`pnpm --filter @missing-elements/h5p-author sync:skill`); check-pack-published.mjs, the publish guard for the pinned pack and player tests/ node tests: the generator, text and translations, layouts and schema, the loader, builds with media from disk and a local server, the command, the - quiz format; fixtures/ the quiz format's two examples, which apps/skills - plays too; package-types.ts as for the normalizer + quiz format, the check of saved content, the demo's packages among it; + fixtures/ the quiz format's two examples, which apps/skills plays too; + package-types.ts as for the normalizer types/ generated, not in git: the declarations packages/cmi5/ @missing-elements/h5p-cmi5 — cmi5 for the element, published as a library @@ -328,9 +335,11 @@ apps/skills/ the skills' test project, a project of the kind a skil it installs the commands the skills run with npx, the author package and the verifier, and the library pack; nothing in it ships. Out of the demo since 2026-10-23, by the owner's choice - tests/author-verify.test.ts every h5p-author type file's example built, with sample media, and - played trusted and untrusted through the verifier's published API, each - a pass with no warnings; each file's generated section compared with + tests/author-verify.test.ts every h5p-author type file's example built, with sample media, checked + as saved content against the libraries it carries with nothing reported + and nothing changed (#107), and played trusted and untrusted through the + verifier's published API, each a pass with no warnings; each file's + generated section compared with the pack's, so a pack refresh shows a change; and the quiz format, from the author package's fixtures: both kinds, the eight-scenario example, a quiz in Ukrainian and one whose titles and author carry quotes and @@ -1989,9 +1998,10 @@ already holds text to the content check's rules, from the pack an untrusted chec `apps/skills` plays every example untrusted too. Measured on a five-question quiz, at four characters a token: `content.json` was about 3,470 tokens to write by hand, after reading 3,900 to 9,500 of a type's semantics; the source is 1,000 to 1,800 tokens, written from a type file of 200 -to 3,000. Eight things the code does not say by itself: +to 3,000. Nine things the code does not say by itself: -- **One generator, two ways to run it.** `ContentGenerator` was the sweep's +- **One generator, three ways to run it.** The third, `saved`, checks content as H5P stores it + (*Saved content is checked as the build checks what it writes*, below). `ContentGenerator` was the sweep's (`apps/demo/scripts/lib/sweep-content.mjs`), and moved here so there is one copy; the sweep runs it `lenient`, keeping what its files write as written and filling every required field from its own samples, and its 55 types came out byte for byte the same after the move. Authoring checks @@ -2032,7 +2042,9 @@ to 3,000. Eight things the code does not say by itself: given ids and types, neighbours named by label made indices both ways; end screens numbered. It checks what those widgets would not let pass: a scenario node with no next, a link to no node, a loop no path leaves; a map with no start; a hotspot question with no right area. A hidden field - nothing set is reported. Lists such a widget draws start empty. + nothing set is reported. Lists such a widget draws start empty. All of that runs on content in + the form H5P stores it, in `checkContent`, so it holds saved content too; only a layout's + `before`, Game Map's, works on the source, turning its numbers and labels into the stored text. - **Media are copied and described.** A file is `{ path }`, beside the source or an `http(s)` address, downloaded at build time; it lands under `content/images|videos|audios|files/` with its MIME type, an image's size read from its header (PNG, JPEG, GIF, BMP; a JPEG's segments walked to @@ -2074,9 +2086,42 @@ to 3,000. Eight things the code does not say by itself: first: `scripts/check-pack-published.mjs` refuses to publish until the pinned version is on npm and exports `./plan`, since a player published before it existed would install and fail on the first import. A tool beside the build takes what the build loads (`openPack`, and `loadLibraries` over - any source with the pack's members) and its rules for text; not the build's check, which reads a - source where a tool edits saved content (#107). The runtime's library-name parser, content check - and content upgrade stay out: they are GPL-3.0-only. + any source with the pack's members), its rules for text, and since #107 the check it runs last + (next bullet). The runtime's library-name parser, content check and content upgrade stay out: + they are GPL-3.0-only. +- **Saved content is checked as the build checks what it writes** (2026-11-02, #107). A tool that + changes a saved package, the agent toolset's `apply` in embed-my/creator, could not take the + build's check, which reads a source: it refused every saved file (`mime`, `width`, `height`), every + part's metadata, a Game Map's stored stages and a field only an older minor has, and gave every + part a new `subContentId`, which the core names a part's statements by, so after each edit an LRS + would have counted every question as new. `checkContent` runs the generator `saved`: files and + metadata taken as saved and held to what the platforms keep of them (H5PContentValidator's + `_validateFilelike` and `validateLibrary`, and the licences the core's copyright dialog looks up + without a check, `lib/metadata.mjs`); each part's id kept, unless H5P would not keep it or an + earlier part has it, which copy and paste in the editor leaves; a markup field's text not wrapped + again. Then the layouts' `after`, the titles and the hidden fields nothing set, all moved out of + the build into it, and Game Map's checks with them, its `before` keeping only the conversion of a + source's numbers and labels. The build runs it last, on what it writes, and adds what it finds + except where the source has that problem already or the generator refused what was written + there, so the two hold content to one set of rules. The semantics, the owner's call the same day: + the package's own where it carries a library's major (`packageLibraries`, over the player's + `ownLibraries`), the pack's otherwise; where the content names another minor than the one checked + against, a field only that minor has is noted and kept, since the player upgrades it as it plays + (steps the runtime runs, GPL, in its frame) or plays newer content without it. Every type file's + example, built and then checked against its own libraries and against the pack, comes back with + nothing reported and nothing changed (`apps/skills`); the demo's packages report nothing but + `markup.h5p`'s markup, which it carries to be removed. Content written without its defaults, as + the demo's is, comes back with them, as the editor saves it. Run over the 88 real packages of the + owner's corpus, 61 report nothing; the others hold what their editor let an author save and the + build does not, a required alt text or scenario title left empty, keys an older editor wrote + (Drag and Drop's `dropZones[].type`, Branching Scenario's `contentId`), styles pasted from Word, + so a tool that changes one part keeps the problems under the paths it changed. Three things the + editor saves for an author who never touched them are taken as such, found on that corpus: an + optional group holding nothing an author has to write, empty texts in it included (Interactive + Video's adaptivity); the item it starts an optional list with (its subtitle track); and an + optional select at its empty choice (`goto.type: ""`). A group that is sub-content now gets an id + in a build too, as the editor's `initSubContent` gives one: Summary's statements and Single Choice + Set's choices had none, and Summary names a statement's statements by it. - **The skill's type files are partly generated.** `skills/h5p-author/references/types/.md` holds hand-written notes, an example, and the type's fields between two markers, written by `schemaOf(…, { markdown: true })`: names, kinds, defaults, options, list sizes, a markup field's @@ -2110,8 +2155,9 @@ to 3,000. Eight things the code does not say by itself: out of the content. Both fields are still written, being hidden and required, and the runtime ignores the first and works the second out again. -Not built: editing an existing package, 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. +Not built: editing an existing package, which a tool beside it does with `checkContent` as its +check; 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. ## The VS Code extension diff --git a/apps/skills/tests/author-verify.test.ts b/apps/skills/tests/author-verify.test.ts index 41db3490..8e02af9a 100644 --- a/apps/skills/tests/author-verify.test.ts +++ b/apps/skills/tests/author-verify.test.ts @@ -2,8 +2,8 @@ import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promis import { tmpdir } from 'node:os' import { join, resolve } from 'node:path' import { crc32, deflateSync } from 'node:zlib' -import { BlobReader, Uint8ArrayWriter, ZipReader } from '@zip.js/zip.js' -import { buildPackage, schemaOf } from '@missing-elements/h5p-author' +import { BlobReader, TextWriter, Uint8ArrayWriter, ZipReader, type FileEntry } from '@zip.js/zip.js' +import { buildPackage, checkContent, loadLibraries, packageLibraries, schemaOf } from '@missing-elements/h5p-author' import { verifyPackage } from '@missing-elements/h5p-verify' import { afterAll, beforeAll, describe, expect, it } from 'vitest' @@ -105,8 +105,30 @@ async function playsBothWays(file: string) { } } +/** + * The check a tool that edits a saved package runs on what it writes (#107), on what a build wrote: + * the content its `h5p.json` names, against the libraries it carries, comes back with nothing + * reported and nothing changed. + */ +async function checksAsSaved(file: string) { + const reader = new ZipReader(new BlobReader(new Blob([await readFile(file)]))) + try { + const entries = new Map((await reader.getEntries()).filter((entry) => !entry.directory).map((entry) => [entry.filename, entry as FileEntry])) + const files = { names: entries.keys(), read: (name: string) => entries.get(name)!.getData(new TextWriter()) } + const manifest = JSON.parse(await files.read('h5p.json')) + const params = JSON.parse(await files.read('content/content.json')) + const main = manifest.preloadedDependencies.find((dependency: { machineName: string }) => dependency.machineName === manifest.mainLibrary) + const content = { type: `${main.machineName} ${main.majorVersion}.${main.minorVersion}`, language: manifest.language, params } + const checked = checkContent(await loadLibraries(await packageLibraries(files), content), content) + expect([checked.problems, checked.notes]).toEqual([[], []]) + expect(checked.params).toEqual(params) + } finally { + await reader.close() + } +} + describe.concurrent('every type file', () => { - it.each(files)('%s: its example builds, and plays trusted and untrusted without warnings', async (file) => { + it.each(files)('%s: its example builds, checks as saved content unchanged, and plays trusted and untrusted without warnings', async (file) => { const source = await exampleOf(file) const folder = join(dir, file.slice(0, -'.md'.length)) await mkdir(folder, { recursive: true }) @@ -114,6 +136,7 @@ describe.concurrent('every type file', () => { const output = join(folder, 'example.h5p') const result = await buildPackage(source, output, { base: folder }) expect(result.notes).toEqual([]) + await checksAsSaved(output) await playsBothWays(output) }, 180_000) @@ -138,9 +161,10 @@ describe.concurrent('the quiz format', () => { questions: example.questions.map((question: { title: string }) => ({ ...question, title: `${question.title}'s "draft" & co` })) }] ] - it.each(quizzes)('%s plays trusted and untrusted without warnings', async (name, source) => { + it.each(quizzes)('%s checks as saved content unchanged, and plays trusted and untrusted without warnings', async (name, source) => { const output = join(dir, `${name.replaceAll(' ', '-')}.h5p`) await buildPackage(source, output) + await checksAsSaved(output) await playsBothWays(output) }, 180_000) }) diff --git a/packages/author/README.md b/packages/author/README.md index 41830f6e..c3293905 100644 --- a/packages/author/README.md +++ b/packages/author/README.md @@ -139,16 +139,49 @@ try { loads what the content brings in: the content type, every library its parameters name and each library field's default, with their semantics in the language and marked as the layouts need them. `entries` is the map `ContentGenerator` takes, every other library of the pack in it without its -semantics. It takes any object with `libraries`, `newest`, `open` and `translation`, such as one -over a package's own library folders. `markupText(value, field, report)`, `plainText(value, note)` -and `allowedTags(field)` are the build's rules for one text value against its field. What a type's -editor widget sets, and the check of a source, are the build's own and not exported. +semantics. It takes any object with `libraries`, `newest`, `open` and `translation`. +`markupText(value, field, report)`, `plainText(value, note)` and `allowedTags(field)` are the +build's rules for one text value against its field. + +A tool that changes a saved package checks what it is about to write with the check the build runs +last on what it writes: + +```js +import { checkContent, loadLibraries, openPack, packageLibraries } from '@missing-elements/h5p-author' + +// `names`, the package's entry names; `read(name)`, an entry's text: from zip.js, or any reader. +const manifest = JSON.parse(await read('h5p.json')) +const main = manifest.preloadedDependencies.find((each) => each.machineName === manifest.mainLibrary) +const params = edited(JSON.parse(await read('content/content.json'))) +const content = { type: `${main.machineName} ${main.majorVersion}.${main.minorVersion}`, language: manifest.language, params } +const pack = await openPack() +try { + const libraries = await loadLibraries(await packageLibraries({ names, read }, pack), content) + const { params: checked, problems, notes } = checkContent(libraries, content) +} finally { + await pack.close() +} +``` + +`packageLibraries(files, pack)` serves the package's own libraries where it carries a major of one, +and the pack's for the rest: content is in the shape of the version it was saved with. `checkContent` +checks every value against its field, as the build does, and takes what H5P saves as it is: files and +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 +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 +the paths it changed. ## 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 [h5p-verify](https://www.npmjs.com/package/@missing-elements/h5p-verify)'s `--preview`. It does not -edit an existing package. The licence of each library is in the pack's `libraries.txt`. +edit an existing package itself: `checkContent` is the check for a tool that does. The licence of +each library is in the pack's `libraries.txt`. MIT. diff --git a/packages/author/lib/author.mjs b/packages/author/lib/author.mjs index 26a5bc28..1a893585 100644 --- a/packages/author/lib/author.mjs +++ b/packages/author/lib/author.mjs @@ -3,8 +3,9 @@ * from a short JSON source. The source writes only what the defaults cannot know; everything else * comes from the libraries' own semantics and translations, and the libraries from the pack this * package pins, checked against its index. A tool beside the build takes the libraries as the build - * loads them (`openPack`, `loadLibraries`) and its rules for text (`markupText`, `plainText`, - * `allowedTags`). + * loads them (`openPack`, `loadLibraries`, and `packageLibraries` for a package's own), its rules + * for text (`markupText`, `plainText`, `allowedTags`), and the check it runs last on what it writes, + * for saved content (`checkContent`). */ import { openPack } from './pack.mjs' @@ -12,8 +13,9 @@ import { schemaLines, schemaMarkdown } from './schema.mjs' import { LAYOUTS } from './types.mjs' export { buildPackage, SourceError } from './build.mjs' +export { checkContent } from './check.mjs' export { ContentGenerator, librariesIn, libraryString } from './generator.mjs' -export { loadLibraries } from './libraries.mjs' +export { loadLibraries, packageLibraries } from './libraries.mjs' export { openPack } from './pack.mjs' export { GENERATED_END, GENERATED_START } from './schema.mjs' export { allowedTags, markupText, plainText } from './text.mjs' @@ -22,11 +24,13 @@ export { allowedTags, markupText, plainText } from './text.mjs' * @typedef {import('./build.mjs').Source} Source * @typedef {import('./build.mjs').BuildResult} BuildResult * @typedef {import('./build.mjs').BuildOptions} BuildOptions + * @typedef {import('./check.mjs').CheckedContent} CheckedContent * @typedef {import('./generator.mjs').GeneratorOptions} GeneratorOptions * @typedef {import('./generator.mjs').PackEntry} PackEntry * @typedef {import('./libraries.mjs').LibraryRecord} LibraryRecord * @typedef {import('./libraries.mjs').LibrarySource} LibrarySource * @typedef {import('./libraries.mjs').LoadedLibraries} LoadedLibraries + * @typedef {import('./libraries.mjs').PackageFiles} PackageFiles * @typedef {import('./translate.mjs').TranslationReport} TranslationReport * @typedef {import('./pack.mjs').IndexEntry} IndexEntry * @typedef {import('./pack.mjs').PartLibrary} PartLibrary diff --git a/packages/author/lib/build.mjs b/packages/author/lib/build.mjs index 21da1d73..a90199e0 100644 --- a/packages/author/lib/build.mjs +++ b/packages/author/lib/build.mjs @@ -5,9 +5,11 @@ import { Readable, Writable } from 'node:stream' import { TextReader, ZipWriter } from '@zip.js/zip.js' import { normalizeArchive } from '@missing-elements/h5p-normalize' import { librariesNamedIn, planPack } from '@missing-elements/h5p-offline-player/plan' -import { ContentGenerator } from './generator.mjs' +import { checkContent, layoutContext, valueAt } from './check.mjs' +import { ContentGenerator, libraryString } from './generator.mjs' import { loadLibraries } from './libraries.mjs' import { MediaStore } from './media.mjs' +import { CC_VERSIONS, LICENSES, ROLES } from './metadata.mjs' import { openPack } from './pack.mjs' import { quizProblems, quizSource } from './quiz.mjs' import { SourceError } from './source-error.mjs' @@ -18,16 +20,12 @@ export { SourceError } /** * A source made a package: validated, filled in from the pack's semantics and translations, - * laid out, its media copied and described, and written with the libraries it needs, each part - * checked against the pack's index. Nothing is written unless all of it is right: every problem - * the source has is listed at once, each by its path, so a fix takes one round. + * its media copied and described, checked as saved content is and laid out, and written with the + * libraries it needs, each part checked against the pack's index. Nothing is written unless all of + * it is right: every problem the source has is listed at once, each by its path, so a fix takes one + * round. */ -/** The licences H5P's metadata takes. */ -const LICENSES = ['U', 'CC BY', 'CC BY-SA', 'CC BY-ND', 'CC BY-NC', 'CC BY-NC-SA', 'CC BY-NC-ND', 'CC0 1.0', 'CC PDM', 'GNU GPL', 'PD', 'ODC PDDL', 'C'] -const CC_VERSIONS = ['4.0', '3.0', '2.5', '2.0', '1.0'] -const ROLES = ['Author', 'Editor', 'Licensee', 'Originator'] - /** * @typedef {{ name: string, role: string }} Author * @typedef {{ @@ -192,24 +190,12 @@ export async function buildPackage(input, output, options = {}) { if (!mainLibrary.semantics) report('type', `${source.type} has no semantics: it is not a content type an author fills in`) else if (!mainLibrary.library.runnable) report('type', `${mainLibrary.library.machineName} is a part other content holds, not a content type on its own: put it in one, such as H5P.Column`) - // Layouts that adjust what is written, before it is generated. - const context = (/** @type {string} */ machineName) => { - const entry = [...entries.values()].find((each) => each.library.machineName === machineName && each.semantics) - return { - report, note, - semantics: entry?.semantics ?? [], - library: entry?.library, - title: (/** @type {string} */ library) => { - const name = String(library).split(' ')[0] - const found = [...entries.values()].find((each) => each.library.machineName === name && each.semantics) - return String(found?.library.title ?? name) - } - } - } + // Layouts that turn what a source writes into what H5P stores, before it is generated. + const layout = layoutContext(entries, report, note) const written = structuredClone(source.params) - for (const place of placesOf(main, written)) LAYOUTS[place.library]?.before?.(place.params, place.path, context(place.library)) + for (const place of placesOf(main, written)) LAYOUTS[place.library]?.before?.(place.params, place.path, layout(place.library)) - const content = generator.generate(mainLibrary, written) + const generated = generator.generate(mainLibrary, written) problems.push(...generator.problems) notes.push(...generator.notes) @@ -222,15 +208,18 @@ export async function buildPackage(input, output, options = {}) { Object.assign(value, resolved) } - // Layouts that set what the editor's widgets set, and check what they would not let pass. - for (const place of placesOf(main, content)) LAYOUTS[place.library]?.after?.(place.params, place.path, context(place.library)) - for (const place of placesOf(main, content)) { - if (place.holder && isObject(place.holder.metadata) && place.holder.metadata.title === undefined) place.holder.metadata.title = place.holder.metadata.contentType - } - for (const { field, path } of generator.unset) { - if (valueAt(content, path) === undefined && !problems.some((problem) => problem.path === path)) report(path, `is required (${field.type}), and nothing set it`) - } + // Checked last as saved content is, as a tool that changes a package checks it: the layouts set + // what the editor's widgets set and check what they would not let pass. Where the source has a + // problem already, the check finds the same one again, or the gap it left: a value missing + // where the generator refused what was written inside it. Only what it finds elsewhere is added. + const checked = checkContent({ entries, main: mainLibrary, translations }, { type: libraryString(mainLibrary.library), params: generated }) + const fromSource = [...problems] + const known = (/** @type {Problem} */ problem) => fromSource.some(({ path }) => path === problem.path || inside(problem.path, path) || + (inside(path, problem.path) && valueAt(checked.params, problem.path) === undefined)) + for (const problem of checked.problems) if (!known(problem)) problems.push(problem) + for (const added of checked.notes) if (!notes.some(({ path, message }) => path === added.path && message === added.message)) notes.push(added) if (problems.length) throw new SourceError(problems) + const content = checked.params const { selected, addons } = await closure(pack, mainLibrary.library, content) if (addons.length) notes.push({ path: 'params', message: `its text matches ${addons.join(', ')}, which the package carries, as a site with it installed would add it` }) @@ -295,15 +284,10 @@ export async function buildPackage(input, output, options = {}) { } /** - * The value at a generator path, `params.a[0].b`, in the content. - * @param {any} content - * @param {string} path + * Whether a path lies inside another: `params.a[0].b` inside `params.a`. + * @param {string} inner + * @param {string} outer */ -function valueAt(content, path) { - let value = { params: content } - for (const part of path.replace(/\[(\d+)\]/g, '.$1').split('.')) { - if (value === undefined || value === null) return undefined - value = /** @type {any} */ (value)[part] - } - return value +function inside(inner, outer) { + return inner.startsWith(`${outer}.`) || inner.startsWith(`${outer}[`) } diff --git a/packages/author/lib/check.mjs b/packages/author/lib/check.mjs new file mode 100644 index 00000000..780e1554 --- /dev/null +++ b/packages/author/lib/check.mjs @@ -0,0 +1,115 @@ +import { ContentGenerator, libraryString } from './generator.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 + * 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. + */ + +/** + * @typedef {import('./generator.mjs').PackEntry} PackEntry + * @typedef {import('./libraries.mjs').LoadedLibraries} LoadedLibraries + * @typedef {{ path: string, message: string }} Problem + * @typedef {{ params: Record, problems: Problem[], notes: Problem[] }} CheckedContent + * `params` the content as checked, which a tool writes; `problems` what H5P or the content type + * would not take; `notes` what is worth saying and is no reason not to write it + */ + +/** @param {unknown} value @returns {value is Record} */ +const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) + +/** + * What a content type's layout is handed: where to report and note, the semantics and record of + * its library, and a library's title by its name. + * @param {Map} entries + * @param {(path: string, message: string) => void} report + * @param {(path: string, message: string) => void} note + * @returns {(machineName: string) => import('./types.mjs').LayoutContext} + * @internal + */ +export function layoutContext(entries, report, note) { + const loaded = (/** @type {string} */ machineName) => [...entries.values()].find((each) => each.library.machineName === machineName && each.semantics) + return (machineName) => { + const entry = loaded(machineName) + return { + report, + note, + semantics: entry?.semantics ?? [], + library: entry?.library, + title: (library) => { + const name = String(library).split(' ')[0] + return String(loaded(name)?.library.title ?? name) + } + } + } +} + +/** + * Saved content checked, and what the editor's widgets would have set on it set. Files and + * sub-content metadata are taken as saved and held to what the platforms keep of them; each part + * keeps its `subContentId`, and one that has none, or one another part has, gets a new one; a text + * is held to what its field takes as stored, and a markup field's is not wrapped again. Then each + * content type's layout runs, placing what nobody placed and checking what its editor would check, + * a part without a title takes its content type's, and a hidden field nothing set is a problem. + * + * The libraries are loaded for the content by `loadLibraries`: from a package's own folders where + * it carries them (`packageLibraries`), since content is in the shape of the version it was saved + * with. Where the content names an older minor of a library than the one checked against, as a + * package without its libraries checked against the pack's does, a field the newer semantics do not + * name is noted rather than refused: the player upgrades such content as it plays, with the + * library's own steps, which this cannot run, being the runtime's (GPL) and run in its frame. + * @param {LoadedLibraries} libraries as `loadLibraries` loaded them for this content + * @param {{ type: string, params: unknown }} content `type` the content type, with the major and + * minor it was saved with, `H5P.QuestionSet 1.20`, as `h5p.json` names it; `params` its + * parameters, `content.json`, left as they are + * @returns {CheckedContent} + */ +export function checkContent(libraries, { type, params }) { + /** @type {Problem[]} */ + const problems = [] + /** @type {Problem[]} */ + const notes = [] + const report = (/** @type {string} */ path, /** @type {string} */ message) => problems.push({ path, message }) + const note = (/** @type {string} */ path, /** @type {string} */ message) => notes.push({ path, message }) + const { entries, main } = libraries + const named = /^\s*(\S+?)(?:\s+(\d+)\.(\d+))?\s*$/.exec(String(type)) + if (!named || named[1] !== main.library.machineName || (named[2] !== undefined && Number(named[2]) !== main.library.majorVersion)) { + report('type', `is ${type}, and the libraries were loaded for ${libraryString(main.library)}`) + return { params: isObject(params) ? structuredClone(params) : {}, problems, notes } + } + if (!main.semantics) report('type', `${libraryString(main.library)} has no semantics: it is not a content type an author fills in`) + const generator = new ContentGenerator(entries, { saved: true }) + const content = generator.generate(main, structuredClone(params), 'params', named[3] === undefined ? undefined : Number(named[3])) + problems.push(...generator.problems) + notes.push(...generator.notes) + + // Layouts that set what the editor's widgets set, and check what they would not let pass. + 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)) + 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 + } + for (const { field, path } of generator.unset) { + if (valueAt(content, path) === undefined && !problems.some((problem) => problem.path === path)) report(path, `is required (${field.type}), and nothing set it`) + } + return { params: content, problems, notes } +} + +/** + * The value at a generator path, `params.a[0].b`, in the content. + * @param {any} content + * @param {string} path + * @internal + */ +export function valueAt(content, path) { + let value = { params: content } + for (const part of path.replace(/\[(\d+)\]/g, '.$1').split('.')) { + if (value === undefined || value === null) return undefined + value = /** @type {any} */ (value)[part] + } + return value +} diff --git a/packages/author/lib/generator.mjs b/packages/author/lib/generator.mjs index ebb210b3..7cecb006 100644 --- a/packages/author/lib/generator.mjs +++ b/packages/author/lib/generator.mjs @@ -1,4 +1,5 @@ import { randomUUID } from 'node:crypto' +import { checkMetadata } from './metadata.mjs' import { markupText, plainText } from './text.mjs' /** @@ -8,12 +9,20 @@ import { markupText, plainText } from './text.mjs' * the same way. So a source states only what the defaults cannot know, and a list in it is as long * as it is written. * - * Two ways to run it. Authoring, the default, checks every written value against its field, as the - * editor's form would: a field the semantics do not name, a select's unknown option, a list too + * Three ways to run it. Authoring, the default, checks every written value against its field, as + * the editor's form would: a field the semantics do not name, a select's unknown option, a list too * short or too long, a tag a markup field does not take, a required field with neither a written * value nor a default — each a problem named by its path. The content-type sweep runs it * `lenient`, taking what is written as it is and filling a required field from `fill`, so that - * every content type in the pack plays (apps/demo/scripts/sweep-content-types.mjs). + * every content type in the pack plays (apps/demo/scripts/sweep-content-types.mjs). And `saved`, as + * `checkContent` runs it (check.mjs), checks content in the form H5P stores it rather than the form + * a source writes it: files and sub-content metadata as saved, held to what the platforms keep of + * them; each sub-content's `subContentId` kept, since the core names a part's statements by it; a + * markup field's text not wrapped again; and an optional group that holds nothing an author has to + * write taken as one the editor saved closed. A field the semantics do not name is kept and noted, + * not a problem, where the content names another minor of its library than the semantics are of: + * the player upgrades content written for an older minor, which may be what moves it, and plays + * content written for a newer one without it. * * The editor is h5p-editor-php-library's form at commit 3bec2594356cf1be4e6401f7e7e557650720aa9b * (2026-10-08), and H5PEditor.ShowWhen 1.0.9 at 93678737300e084cb9390a691d3e1ad4e793fbaa for @@ -35,12 +44,28 @@ import { markupText, plainText } from './text.mjs' /** The nesting depth at which a library field stops choosing content of its own. */ const MAX_DEPTH = 4 +/** + * The shape H5P keeps a sub-content id in (H5PContentValidator's `validateLibrary`, at the commit + * the runtime's content check names); one in any other is removed, and the part's statements then + * name it as the content itself. + */ +const SUB_CONTENT_ID = /^\{?[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}\}?$/ + +/** + * What the platforms keep of a saved file beside `path`, `mime` and `copyright`, by its field's + * type (H5PContentValidator's `_validateFilelike` and its callers); a field's `extraAttributes` add + * to it. + * @type {Record} + */ +const FILE_KEYS = { file: [], image: ['width', 'height', 'originalImage'], video: ['width', 'height', 'codecs', 'quality', 'bitrate'], audio: [] } + /** * @typedef {{ folder: string, library: any, semantics: any[] | null }} PackEntry * @typedef {{ path: string, message: string }} Problem * @typedef {{ field: any, value: any, path: string }} MediaReference * @typedef {{ * lenient?: boolean, + * saved?: boolean, * fill?: (field: any, context: { generator: ContentGenerator, stack: string[], path: string }) => unknown, * id?: (count: number) => string, * metadata?: (entry: PackEntry, written: any, path: string) => any @@ -48,6 +73,13 @@ const MAX_DEPTH = 4 */ export class ContentGenerator { + /** + * The library whose parameters are being made, while the content names another minor of it than + * its semantics are of. + * @type {{ library: any, minor: number } | null} + */ + #other = null + /** * @param {Map} pack every library folder the content may use, by folder name * @param {GeneratorOptions} [options] @@ -56,12 +88,15 @@ export class ContentGenerator { this.pack = pack this.options = options this.lenient = options.lenient ?? false + this.saved = options.saved ?? false this.ids = 0 - /** @type {Problem[]} what is wrong with the written content, authoring only */ + /** @type {Set} the sub-content ids given, so that no two parts have one */ + this.taken = new Set() + /** @type {Problem[]} what is wrong with the content, written or saved; never lenient */ this.problems = [] /** @type {Problem[]} what is worth saying about it and does not stop a build */ this.notes = [] - /** @type {MediaReference[]} the files the written content names, for the caller to copy */ + /** @type {MediaReference[]} the files the content names: written, for the caller to copy; saved, as they are */ this.media = [] /** @type {WeakSet} fields a content type's own widget draws: numbers take decimals, lists start empty */ this.drawn = new WeakSet() @@ -168,9 +203,30 @@ export class ContentGenerator { * @param {PackEntry} entry * @param {any} [written] * @param {string} [path] where the parameters sit, for problems: `params` by default + * @param {number} [minor] the minor of the library the content names, where it may be another + * than the entry's, as saved content's may */ - generate(entry, written, path = 'params') { - return this.fields(entry.semantics ?? [], written, [entry.library.machineName], false, path) + generate(entry, written, path = 'params', minor) { + return this.#of(entry, minor, () => this.fields(entry.semantics ?? [], written, [entry.library.machineName], false, path)) + } + + /** + * What a callback makes of a library's parameters, knowing whether the content names another + * minor of the library than its semantics are of. + * @template T + * @param {PackEntry} entry + * @param {number | undefined} minor + * @param {() => T} generate + * @returns {T} + */ + #of(entry, minor, generate) { + const outer = this.#other + this.#other = minor === undefined || minor === entry.library.minorVersion ? null : { library: entry.library, minor } + try { + return generate() + } finally { + this.#other = outer + } } /** A sub-content id: random, or the caller's, numbered, where it wants the same bytes every run. */ @@ -179,6 +235,25 @@ export class ContentGenerator { return this.options.id ? this.options.id(this.ids) : randomUUID() } + /** + * The id of a part: saved, the one it has, unless H5P would not keep it or another part took it + * first; else a new one, as the editor gives new sub-content one (h5peditor-library.js, + * `loadLibrary`, and h5peditor-group.js, `initSubContent`). + * @param {unknown} saved + * @param {string} path the part's + */ + #id(saved, path) { + let id = this.saved && typeof saved === 'string' && SUB_CONTENT_ID.test(saved) && !this.taken.has(saved) ? saved : undefined + if (this.saved && saved !== undefined && id === undefined) { + this.note(`${path}.subContentId`, typeof saved === 'string' && this.taken.has(saved) + ? 'is another part\'s id too, so this part has a new one' + : 'is not an id H5P keeps, so the part has a new one') + } + id ??= this.nextId() + this.taken.add(id) + return id + } + /** @param {string} path @param {string} message */ report(path, message) { this.problems.push({ path, message }) @@ -196,8 +271,10 @@ export class ContentGenerator { * @param {boolean} lenient inside an optional group nobody wrote: defaults only, as the editor * saves a group left closed — and so nothing asked for a field required only within it * @param {string} path + * @param {string[]} [kept] saved, keys these fields do not name that are kept as they are: what + * the group's own default carries, and a part's id */ - fields(fields, written, stack, lenient, path) { + fields(fields, written, stack, lenient, path, kept = []) { /** @type {Record} */ const out = {} if (!this.lenient && written !== undefined && !isObject(written)) { @@ -217,6 +294,10 @@ export class ContentGenerator { // it, which a sweep file may mean to test. if (this.lenient) { if (value !== null) out[key] = value + } else if (this.saved && kept.includes(key)) out[key] = value + else if (this.saved && this.#other) { + out[key] = value + this.note(`${path}.${key}`, otherMinor(this.#other)) } else this.report(`${path}.${key}`, `is not a field here; the fields are ${names(fields)}`) } return out @@ -260,17 +341,26 @@ export class ContentGenerator { if (field.widget && field.widget !== 'showWhen' && field.widget !== 'none') this.#draw(children) // Saved even when optional and untouched, as the editor saves every group in its form // (h5peditor-group.js): content types read into one without looking (Personality Quiz's - // `image.file`). - return this.fields(children, written, stack, optional && written === undefined, path) + // `image.file`). Saved, a group that holds nothing an author has to write is one of those, + // whoever wrote it, and nothing is asked of it either. + const closed = optional && (written === undefined || (this.saved && !holds(field, written))) + const kept = isObject(field.default) ? Object.keys(field.default) : [] + if (field.isSubContent) kept.push('subContentId') + const value = this.fields(children, written, stack, closed, path, kept) + if (field.isSubContent) value.subContentId = this.#id(isObject(written) ? written.subContentId : undefined, path) + return value } case 'list': { const item = this.#copy(field.field, { optional: false }) if (Array.isArray(written)) { if (!this.lenient) { - if (field.min !== undefined && written.length < field.min) this.report(path, `has ${written.length} item${written.length === 1 ? '' : 's'}; it takes at least ${field.min}`) + if (field.min !== undefined && written.length < field.min && !lenient) this.report(path, `has ${written.length} item${written.length === 1 ? '' : 's'}; it takes at least ${field.min}`) if (field.max !== undefined && written.length > field.max) this.report(path, `has ${written.length} items; it takes at most ${field.max}`) } - return this.#level([], {}, () => written.map((each, index) => this.field(item, each, stack, false, `${path}[${index}]`)).filter((each) => each !== undefined)) + // Saved, an item that holds nothing an author has to write is one the editor started an + // optional list with, and nobody filled: nothing is asked of it. + return this.#level([], {}, () => written.map((each, index) => + this.field(item, each, stack, lenient || (this.saved && field.optional === true && !holds(item, each)), `${path}[${index}]`)).filter((each) => each !== undefined)) } if (written !== undefined && !this.lenient) { this.report(path, 'expected a list') @@ -311,7 +401,8 @@ export class ContentGenerator { } return optional ? undefined : this.missing(field, stack, path) case 'text': - if (written !== undefined) return this.lenient ? written : this.text(field, written, path) + // Within what nothing is asked of, an empty text is what the editor saved there. + if (written !== undefined) return this.lenient ? written : this.text(lenient ? this.#optional(field) : field, written, path) // A default of null, which Course Presentation gives its colours, is stored as nothing: the // platforms' check would turn it into an empty text. if (field.default === null && !this.lenient) return undefined @@ -326,6 +417,8 @@ export class ContentGenerator { // The editor's checkbox saves false when nobody ticked it (h5peditor-boolean.js). return written ?? field.default ?? false case 'select': + // Saved, an optional select left at the editor's empty choice holds "". + if (this.saved && optional && written === '') return written if (written !== undefined) return this.lenient ? written : this.select(field, written, path) if (field.default !== undefined) return structuredClone(field.default) return optional ? undefined : this.missing(field, stack, path) @@ -463,6 +556,18 @@ export class ContentGenerator { this.report(`${path}.library`, `the library pack has no ${machineName}${major === undefined ? '' : ` ${major}.x`}`) return undefined } + if (this.saved) { + // As H5P keeps sub-content (validateLibrary): these four, and what the field adds. + const keys = ['library', 'params', 'subContentId', 'metadata', ...extraAttributes(field)] + for (const key of Object.keys(written)) if (!keys.includes(key)) this.report(`${path}.${key}`, `is not part of sub-content; H5P keeps ${keys.join(', ')}`) + if (written.metadata !== undefined) checkMetadata(written.metadata, `${path}.metadata`, (at, message) => this.report(at, message)) + // Content a field gives as its default, Interactive Video's summary task, is as the editor + // started it until an author opens it, which saved content does not tell: what it holds is + // checked, and nothing asked of it. + const started = isObject(field?.default) && typeof field.default.library === 'string' && field.default.library.trim().split(/\s+/)[0] === machineName + const minor = match[3] === undefined ? undefined : Number(match[3]) + return this.subContent(entry, written.params, written.metadata, stack, path, { id: written.subContentId, minor, closed: started }) + } for (const key of Object.keys(written)) { if (!['library', 'params', 'metadata'].includes(key)) this.report(`${path}.${key}`, 'is not part of sub-content; write library, params and metadata') } @@ -479,15 +584,20 @@ export class ContentGenerator { * @param {any} metadata its written metadata * @param {string[]} stack * @param {string} path + * @param {{ id?: unknown, minor?: number, closed?: boolean }} [saved] saved sub-content's id, the + * minor of its library it names, and whether nothing is asked of it */ - subContent(entry, written, metadata, stack, path) { + subContent(entry, written, metadata, stack, path, { id, minor, closed = false } = {}) { + const params = this.#of(entry, minor, () => this.fields(entry.semantics ?? [], written, [...stack, entry.library.machineName], closed, `${path}.params`)) return { library: libraryString(entry.library), - params: this.fields(entry.semantics ?? [], written, [...stack, entry.library.machineName], false, `${path}.params`), - subContentId: this.nextId(), - metadata: this.options.metadata - ? this.options.metadata(entry, metadata, path) - : { contentType: entry.library.title, license: 'U', title: entry.library.title } + params, + subContentId: this.#id(id, path), + metadata: this.saved && isObject(metadata) + ? structuredClone(metadata) + : this.options.metadata + ? this.options.metadata(entry, metadata, path) + : { contentType: entry.library.title, license: 'U', title: entry.library.title } } } @@ -503,7 +613,7 @@ export class ContentGenerator { } const stored = field.tags === undefined || field.tags === null ? plainText(written, (message) => this.note(path, message)) - : markupText(written, field, (message) => this.report(path, message)) + : markupText(written, field, (message) => this.report(path, message), { saved: this.saved }) const length = Array.from(stored).length if (typeof field.maxLength === 'number' && length > field.maxLength) this.report(path, `is ${length} characters as stored; it takes at most ${field.maxLength}`) if (field.regexp?.pattern && !(stored === '' && field.optional)) { @@ -563,7 +673,9 @@ export class ContentGenerator { /** * A written file: `{ "path": … }`, a file beside the source or a web address, with `copyright` * when known. A video or an audio field takes a list of them, one per format, or one alone. - * Checked for its shape here; the caller copies it and fills in its type and size. + * Checked for its shape here; the caller copies it and fills in its type and size. Saved, a file + * is as H5P stores it, its path in the package or a web address, and holds what the platforms + * keep of one. * @param {any} field * @param {unknown} written * @param {string} path @@ -583,12 +695,19 @@ export class ContentGenerator { for (const [index, each] of list.entries()) { const at = many && Array.isArray(written) ? `${path}[${index}]` : path if (!isObject(each) || typeof each.path !== 'string' || !each.path.trim()) { - this.report(at, `expected a file, { "path": "picture.jpg" }, a file beside the source or a web address`) + this.report(at, this.saved + ? 'expected a file as H5P stores it, { "path": "images/picture.jpg", "mime": "image/jpeg" }' + : 'expected a file, { "path": "picture.jpg" }, a file beside the source or a web address') continue } - for (const key of Object.keys(each)) if (!['path', 'copyright'].includes(key)) this.report(`${at}.${key}`, 'is not part of a file here; write path and, when known, copyright') + if (this.saved) { + const keys = ['path', 'mime', 'copyright', ...(FILE_KEYS[field.type] ?? []), ...extraAttributes(field)] + for (const key of Object.keys(each)) if (!keys.includes(key)) this.report(`${at}.${key}`, `is not part of a file as H5P stores it; it keeps ${keys.join(', ')}`) + if (each.mime !== undefined && typeof each.mime !== 'string') this.report(`${at}.mime`, 'expected a MIME type, such as "image/jpeg"') + for (const key of ['width', 'height']) if (each[key] !== undefined && !(Number.isInteger(each[key]) && each[key] >= 0)) this.report(`${at}.${key}`, 'expected a whole number of pixels') + } else for (const key of Object.keys(each)) if (!['path', 'copyright'].includes(key)) this.report(`${at}.${key}`, 'is not part of a file here; write path and, when known, copyright') if (each.copyright !== undefined && !isObject(each.copyright)) this.report(`${at}.copyright`, 'expected an object, such as { "license": "CC BY", "author": "…" }') - const value = { ...each } + const value = this.saved ? structuredClone(each) : { ...each } this.media.push({ field, value, path: at }) files.push(value) } @@ -624,6 +743,41 @@ function optionNames(field) { return libraryOptions(field).map((option) => option.machineName) } +/** What a field's semantics add to what the platforms keep of its value. @param {any} field @returns {string[]} */ +function extraAttributes(field) { + return Array.isArray(field?.extraAttributes) ? field.extraAttributes.filter((/** @type {unknown} */ name) => typeof name === 'string') : [] +} + +/** + * Whether a saved value holds something an author has to write: a value for a required field + * without a default, in it or in a group or list in it. What the editor saves for an author who + * never touched it holds nothing of the kind: an optional group left closed, with its defaults + * alone, and an empty text or list among them, as Interactive Video's editor saves an adaptivity + * nobody set; the item it starts an optional list with, as its text tracks. + * @param {any} field + * @param {unknown} value + * @returns {boolean} + */ +function holds(field, value) { + if (value === undefined || value === null || value === '') return false + if (field.type === 'list') return Array.isArray(value) && value.some((item) => holds(field.field ?? {}, item)) + if (field.type !== 'group' || ((field.fields ?? []).length === 1 && !field.isSubContent)) return true + return isObject(value) && (field.fields ?? []).some((/** @type {any} */ child) => + !child.optional && child.default === undefined && child.type !== 'boolean' && holds(child, value[child.name])) +} + +/** + * Why saved content may hold a field the semantics it is checked against do not name. + * @param {{ library: any, minor: number }} other + */ +function otherMinor({ library, minor }) { + const named = `${library.majorVersion}.${minor}` + const served = `${library.majorVersion}.${library.minorVersion}` + return minor < library.minorVersion + ? `is not a field of ${libraryString(library)}; the content names ${named}, which the player upgrades to ${served} as it plays, and that may move it` + : `is not a field of ${libraryString(library)}; the content names ${named}, newer, which the player plays at ${served} without it` +} + /** @param {any} field @returns {string[]} */ function selectValues(field) { /** @type {string[]} */ diff --git a/packages/author/lib/libraries.mjs b/packages/author/lib/libraries.mjs index 4e211f23..25e4eb3a 100644 --- a/packages/author/lib/libraries.mjs +++ b/packages/author/lib/libraries.mjs @@ -1,3 +1,4 @@ +import { ownLibraries } from '@missing-elements/h5p-offline-player/plan' import { libraryString } from './generator.mjs' import { SourceError } from './source-error.mjs' import { localize, translationFiles } from './translate.mjs' @@ -6,7 +7,7 @@ import { patchSemantics } from './types.mjs' /** * The libraries content brings in, loaded as a build loads them, for the build and for a tool * beside it that reads or changes content as the build would. No Node import of its own: the pack - * the libraries come from is handed in. + * the libraries come from is handed in, and a package's files are read through the caller. */ /** @@ -14,6 +15,12 @@ import { patchSemantics } from './types.mjs' * @typedef {{ folder: string, machineName: string, majorVersion: number, minorVersion: number }} LibraryRecord */ +/** + * A package's files, as a tool that has it open reads them: the names of its entries, and an + * entry's text. + * @typedef {{ names: Iterable, read(name: string): Promise }} PackageFiles + */ + /** * What libraries are loaded from: the pack `openPack` opens, or any other with these members, such * as one over a package's own library folders. `newest` is the library served for a machine name @@ -104,3 +111,61 @@ export async function loadLibraries(pack, { type, language, params }) { } return { entries, main: /** @type {PackEntry} */ (entries.get(mainEntry.folder)), translations } } + +/** + * The libraries a saved package's content is checked against: the package's own, where it carries + * a major of a library, and the fallback's, the pack's, where it does not. Content is in the shape + * of the version it was saved with, which a package that carries its libraries carries, and which + * the pack, keeping the newest minor of each major, may have moved past. A package's own library + * is a folder the player takes as one (its `ownLibraries`): a `library.json` naming the library its + * folder's name does. + * @param {PackageFiles} files the package's + * @param {LibrarySource} [fallback] for what the package does not carry: the pack `openPack` opens + * @returns {Promise} + */ +export async function packageLibraries({ names, read }, fallback) { + const entries = new Set(names) + const json = async (/** @type {string} */ name) => JSON.parse(await read(name)) + const folders = [...entries].flatMap((name) => /^([^/]+)\/library\.json$/.exec(name)?.slice(1) ?? []) + /** @type {(LibraryRecord & { patchVersion: number })[]} */ + const own = [] + for (const { folder, machineName, major, minor, patch } of await ownLibraries(folders, (folder) => json(`${folder}/library.json`))) { + if (major !== null && minor !== null) own.push({ folder, machineName, majorVersion: major, minorVersion: minor, patchVersion: patch ?? 0 }) + } + const carried = new Set(own.map(({ machineName, majorVersion }) => `${machineName} ${majorVersion}`)) + const mine = new Set(own.map(({ folder }) => folder)) + const libraries = [...own, ...(fallback?.libraries ?? []).filter(({ machineName, majorVersion }) => !carried.has(`${machineName} ${majorVersion}`))] + /** @type {Map} each own folder's translation files, by name without `.json` */ + const languages = new Map() + for (const name of entries) { + const match = /^([^/]+)\/language\/([^/]+)\.json$/.exec(name) + if (match && mine.has(match[1])) languages.set(match[1], [...(languages.get(match[1]) ?? []), match[2]]) + } + /** @param {any} record */ + const patchOf = (record) => Number(record.patchVersion ?? 0) + return { + libraries, + newest(machineName, major) { + /** @type {LibraryRecord | null} */ + let best = null + for (const entry of libraries) { + if (entry.machineName !== machineName || (major !== undefined && entry.majorVersion !== major)) continue + if (!best || entry.majorVersion > best.majorVersion || (entry.majorVersion === best.majorVersion && (entry.minorVersion > best.minorVersion || (entry.minorVersion === best.minorVersion && patchOf(entry) > patchOf(best))))) best = entry + } + return best + }, + async open(entry) { + if (!mine.has(entry.folder)) { + if (!fallback) throw new Error(`${entry.folder} is not one of the package's libraries`) + return fallback.open(entry) + } + const semantics = entries.has(`${entry.folder}/semantics.json`) ? await json(`${entry.folder}/semantics.json`) : null + return { folder: entry.folder, library: await json(`${entry.folder}/library.json`), semantics, translations: languages.get(entry.folder) ?? [] } + }, + async translation(part, name) { + if (!mine.has(part.folder)) return fallback?.translation(part, name) + if (!languages.get(part.folder)?.includes(name)) return undefined + return (await json(`${part.folder}/language/${name}.json`))?.semantics + } + } +} diff --git a/packages/author/lib/metadata.mjs b/packages/author/lib/metadata.mjs new file mode 100644 index 00000000..a301abdf --- /dev/null +++ b/packages/author/lib/metadata.mjs @@ -0,0 +1,42 @@ +/** + * H5P's metadata, as the platforms take it (H5PContentValidator's `getMetadataSemantics`, at the + * commit the runtime's content check names): the licences, their versions and an author's roles. A + * source's metadata is held to them, and so is what saved sub-content carries of what the core + * reads without a check: its copyright dialog looks a licence up in a table of these, and a licence + * it has no name for ends the dialog. + */ + +/** The licences H5P's metadata takes. */ +export const LICENSES = ['U', 'CC BY', 'CC BY-SA', 'CC BY-ND', 'CC BY-NC', 'CC BY-NC-SA', 'CC BY-NC-ND', 'CC0 1.0', 'CC PDM', 'GNU GPL', 'PD', 'ODC PDDL', 'C'] +export const CC_VERSIONS = ['4.0', '3.0', '2.5', '2.0', '1.0'] +export const ROLES = ['Author', 'Editor', 'Licensee', 'Originator'] + +/** @param {unknown} value @returns {value is Record} */ +const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) + +/** + * Saved sub-content's metadata, held to what the core reads of it: a title of at most 255 + * characters, a licence and a version of it H5P names, and authors in roles it names. Whatever else + * it carries is kept as saved, the platforms' to check. + * @param {unknown} metadata + * @param {string} path where it sits, for problems + * @param {(path: string, message: string) => void} report + */ +export function checkMetadata(metadata, path, report) { + if (!isObject(metadata)) { + report(path, 'expected an object, such as { "title": "…", "license": "U" }') + return + } + const { title, license, licenseVersion, authors } = metadata + if (title !== undefined && typeof title !== 'string') report(`${path}.title`, 'expected a title') + else if (typeof title === 'string' && title.length > 255) report(`${path}.title`, 'takes at most 255 characters') + if (license !== undefined && !LICENSES.includes(license)) report(`${path}.license`, `use one of ${LICENSES.map((each) => JSON.stringify(each)).join(', ')}`) + if (licenseVersion !== undefined && !CC_VERSIONS.includes(licenseVersion)) report(`${path}.licenseVersion`, `use one of ${CC_VERSIONS.join(', ')}`) + if (authors === undefined) return + if (!Array.isArray(authors)) report(`${path}.authors`, 'expected a list, [{ "name": "…", "role": "Author" }]') + else authors.forEach((/** @type {unknown} */ author, /** @type {number} */ i) => { + if (!isObject(author)) report(`${path}.authors[${i}]`, 'expected an author, { "name": "…", "role": "Author" }') + else if (author.role !== undefined && !ROLES.includes(author.role)) report(`${path}.authors[${i}].role`, `use one of ${ROLES.join(', ')}`) + else if (author.name !== undefined && typeof author.name !== 'string') report(`${path}.authors[${i}].name`, 'expected the author\'s name') + }) +} diff --git a/packages/author/lib/text.mjs b/packages/author/lib/text.mjs index 7ac49261..3aa019f9 100644 --- a/packages/author/lib/text.mjs +++ b/packages/author/lib/text.mjs @@ -98,10 +98,12 @@ export function hasMarkup(value) { * @param {string} value * @param {any} field * @param {(message: string) => void} report + * @param {{ saved?: boolean }} [options] `saved`, a value as H5P stores it: text without markup is + * kept as it is, but for a lone `<` or `>`, where typed text is wrapped as the editor wraps it */ -export function markupText(value, field, report) { +export function markupText(value, field, report, { saved = false } = {}) { const tags = allowedTags(field) ?? new Set() - if (!hasMarkup(value)) { + if (!hasMarkup(value) && !saved) { const block = blockTag(field) const paragraphs = value.trim().split(/\n[ \t]*\n+/).filter((paragraph) => paragraph.trim()) if (!paragraphs.length) return '' diff --git a/packages/author/lib/types.mjs b/packages/author/lib/types.mjs index c48079a0..e9ba6f69 100644 --- a/packages/author/lib/types.mjs +++ b/packages/author/lib/types.mjs @@ -416,7 +416,9 @@ const branchingScenario = { * ways, as the editor's map widget keeps them. Each gets the id that widget gives it, a UUID, and a * `type`, `stage` or `special-stage`, which the widget keeps on its own element rather than in the * content and the runtime works out from `specialStageType` again: the field is hidden and - * required, and would be reported unset. + * required, and would be reported unset. A source's numbers and labels become that text before + * generation; what the map widget would not let pass is checked on the stored form, as saved + * content has it. * @type {Layout} */ const gameMap = { @@ -436,7 +438,8 @@ const gameMap = { elements.forEach((/** @type {any} */ element, /** @type {number} */ i) => { if (!isObject(element)) return const at = `${path}.gamemapSteps.gamemap.elements[${i}]` - // Positions are kept as text; a source writes numbers, percent of the map from the top left. + // Positions are kept as text; a source writes numbers, percent of the map from the top left, + // or leaves a stage to a grid. const telemetry = isObject(element.telemetry) ? element.telemetry : {} const columns = Math.ceil(Math.sqrt(elements.length)) const position = { @@ -445,33 +448,20 @@ const gameMap = { width: telemetry.width ?? 6, height: telemetry.height ?? 10 } - for (const [key, value] of Object.entries(position)) { - if (typeof value !== 'number' || value < 0 || value > 100) context.report(`${at}.telemetry.${key}`, 'expected a number from 0 to 100, percent of the map') - } - element.telemetry = Object.fromEntries(Object.entries(position).map(([key, value]) => [key, String(Math.round(Number(value) * 100) / 100)])) - if (element.neighbors !== undefined) { - if (!Array.isArray(element.neighbors)) { - context.report(`${at}.neighbors`, 'expected a list of stages, by label or index') - element.neighbors = [] - return - } + element.telemetry = Object.fromEntries(Object.entries(position).map(([key, value]) => [key, typeof value === 'number' ? String(Math.round(value * 100) / 100) : value])) + // A neighbour by label is stored as its index; one no label names stays as written, for the + // check of the stored form not to report again. + if (element.neighbors !== undefined && !Array.isArray(element.neighbors)) { + context.report(`${at}.neighbors`, 'expected a list of stages, by label or index') + element.neighbors = [] + } else if (Array.isArray(element.neighbors)) { element.neighbors = element.neighbors.map((/** @type {unknown} */ neighbor, /** @type {number} */ j) => { - const index = typeof neighbor === 'number' ? neighbor : labels.indexOf(String(neighbor).trim()) - if (!Number.isInteger(index) || index < 0 || index >= elements.length || index === i) { - context.report(`${at}.neighbors[${j}]`, `${JSON.stringify(neighbor)} names no other stage; the stages are ${labels.map((label) => JSON.stringify(label)).join(', ')}`) - return null - } - return String(index) - }).filter((/** @type {unknown} */ each) => each !== null) - } - }) - // A connection goes both ways, as the editor draws it. - elements.forEach((/** @type {any} */ element, /** @type {number} */ i) => { - for (const neighbor of element?.neighbors ?? []) { - const other = elements[Number(neighbor)] - if (!isObject(other)) continue - other.neighbors = Array.isArray(other.neighbors) ? other.neighbors : [] - if (!other.neighbors.includes(String(i))) other.neighbors.push(String(i)) + if (typeof neighbor === 'number') return String(neighbor) + const index = labels.indexOf(String(neighbor).trim()) + if (index >= 0 && index !== i) return String(index) + context.report(`${at}.neighbors[${j}]`, `${JSON.stringify(neighbor)} names no other stage; the stages are ${labels.map((label) => JSON.stringify(label)).join(', ')}`) + return neighbor + }) } }) }, @@ -480,14 +470,34 @@ const gameMap = { const elements = gamemap?.elements if (!Array.isArray(elements)) return if (!elements.some((/** @type {any} */ element) => element?.canBeStartStage)) context.report(`${path}.gamemapSteps.gamemap.elements`, 'has no stage a learner can start at: set "canBeStartStage": true on one') + const labels = elements.map((/** @type {any} */ element) => (typeof element?.label === 'string' ? element.label.trim() : '')) elements.forEach((/** @type {any} */ element, /** @type {number} */ i) => { const at = `${path}.gamemapSteps.gamemap.elements[${i}]` + for (const key of ['x', 'y', 'width', 'height']) { + const value = element.telemetry?.[key] + if (value !== undefined && !(typeof value === 'string' && value.trim() !== '' && Number(value) >= 0 && Number(value) <= 100)) context.report(`${at}.telemetry.${key}`, 'expected a number from 0 to 100, percent of the map') + } if (element.id === undefined) element.id = randomUUID() if (element.type === undefined) element.type = element.specialStageType ? 'special-stage' : 'stage' if (!Array.isArray(element.neighbors)) element.neighbors = [] + element.neighbors.forEach((/** @type {unknown} */ neighbor, /** @type {number} */ j) => { + if (!(typeof neighbor === 'string' && /^\d+$/.test(neighbor) && Number(neighbor) < elements.length && Number(neighbor) !== i)) { + context.report(`${at}.neighbors[${j}]`, `${JSON.stringify(neighbor)} names no other stage; the stages are ${labels.map((/** @type {string} */ label) => JSON.stringify(label)).join(', ')}, by their index from 0`) + } + }) if (element.type === 'stage' && !(Array.isArray(element.contentsList) && element.contentsList.length)) context.report(`${at}.contentsList`, 'is required for a stage: write at least 1 content') if (element.specialStageType === 'link' && !element.specialStageLinkURL) context.report(`${at}.specialStageLinkURL`, 'is required for a link stage') - if (!element.neighbors.length && elements.length > 1) context.note(at, 'is joined to no other stage') + }) + // A connection goes both ways, as the editor draws it. + elements.forEach((/** @type {any} */ element, /** @type {number} */ i) => { + for (const neighbor of element.neighbors) { + const other = elements[Number(neighbor)] + if (Number(neighbor) === i || !isObject(other) || !Array.isArray(other.neighbors)) continue + if (!other.neighbors.includes(String(i))) other.neighbors.push(String(i)) + } + }) + elements.forEach((/** @type {any} */ element, /** @type {number} */ i) => { + if (!element.neighbors.length && elements.length > 1) context.note(`${path}.gamemapSteps.gamemap.elements[${i}]`, 'is joined to no other stage') }) if (gamemap.paths === undefined) gamemap.paths = [] } diff --git a/packages/author/tests/check.test.ts b/packages/author/tests/check.test.ts new file mode 100644 index 00000000..18e06d99 --- /dev/null +++ b/packages/author/tests/check.test.ts @@ -0,0 +1,194 @@ +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join, resolve } from 'node:path' +import { BlobReader, TextWriter, ZipReader, type FileEntry } from '@zip.js/zip.js' +import { afterAll, beforeAll, describe, expect, it } from 'vitest' +import { buildPackage, checkContent, loadLibraries, openPack, packageLibraries, type LibrarySource, type PackageFiles } from '../lib/author.mjs' +import { png } from './helpers/media' + +// The demo's packages: five carry their libraries, `formulas.h5p` is an export without them. +const demo = resolve(import.meta.dirname, '../../../apps/demo/demo/content') +const META = { title: 'Saved', language: 'en', license: 'CC BY', authors: [{ name: 'Ann Author', role: 'Author' }] } +let pack: Awaited> +let dir: string +let count = 0 +beforeAll(async () => { + pack = await openPack() + dir = await mkdtemp(join(tmpdir(), 'h5p-author-check-')) +}) +afterAll(async () => { + await pack?.close() + if (dir) await rm(dir, { recursive: true, force: true }) +}) + +/** A package's files as an editing tool reads them, through zip.js. */ +async function openPackage(path: string) { + const reader = new ZipReader(new BlobReader(new Blob([await readFile(path)]))) + const entries = new Map((await reader.getEntries()).filter((entry) => !entry.directory).map((entry) => [entry.filename, entry as FileEntry])) + const files: PackageFiles = { names: entries.keys(), read: (name) => entries.get(name)!.getData(new TextWriter()) } + return { files, close: () => reader.close() } +} + +/** + * A saved package's content checked as a tool that edits it checks what it writes: the content type + * and language its `h5p.json` names, against its own libraries and the pack's for what it does not + * carry. + */ +async function checkPackage(path: string, edit = (params: any) => params) { + const { files, close } = await openPackage(path) + try { + const manifest = JSON.parse(await files.read('h5p.json')) + const params = edit(JSON.parse(await files.read('content/content.json'))) + const main = manifest.preloadedDependencies.find((dependency: { machineName: string }) => dependency.machineName === manifest.mainLibrary) + const content = { type: `${main.machineName} ${main.majorVersion}.${main.minorVersion}`, language: manifest.language, params } + const libraries = await loadLibraries(await packageLibraries(files, pack), content) + return { saved: params, libraries, ...checkContent(libraries, content) } + } finally { + await close() + } +} + +async function built(type: string, params: unknown) { + await writeFile(join(dir, 'river.png'), png(480, 270)) + const output = join(dir, `saved-${++count}.h5p`) + await buildPackage({ ...META, type, params }, output, { base: dir }) + return output +} + +describe('checkContent', () => { + it('takes what a build wrote as it is: nothing reported, nothing changed', async () => { + const output = await built('H5P.Column', { + content: [ + { content: { library: 'H5P.Image', params: { file: { path: 'river.png', copyright: { license: 'CC BY', author: 'Ann' } }, alt: 'A river' }, metadata: { title: 'River' } } }, + { content: { library: 'H5P.SingleChoiceSet', params: { choices: [{ question: 'Which flows?', answers: ['A river', 'A rock'] }] } } }, + { content: { library: 'H5P.Blanks', params: { questions: ['Rivers flow *down*hill.'] } } } + ] + }) + const { saved, params, problems, notes } = await checkPackage(output) + expect([problems, notes]).toEqual([[], []]) + expect(params).toEqual(saved) + // The editor gives a group that is sub-content an id of its own, as a library's. + expect(saved.content[1].content.params.choices[0].subContentId).toMatch(/^[0-9a-f-]{36}$/) + }) + + it('reports what an edit broke by path, and keeps each part\'s id', async () => { + const output = await built('H5P.Column', { content: [{ content: { library: 'H5P.MultiChoice', params: { question: 'Which flows?', answers: [{ text: 'A river', correct: true }, { text: 'A rock' }] } } }] }) + const { saved, params, problems } = await checkPackage(output, (params) => { + const question = params.content[0].content + question.params.answers = [{ text: '

A river

', correct: 'yes' }] + question.params.behaviour.typo = true + params.content.push({ content: { library: 'H5P.AdvancedText', params: { text: '' } } }) + return params + }) + expect(problems.map(({ path }) => path)).toEqual([ + 'params.content[0].content.params.answers[0].correct', + 'params.content[0].content.params.behaviour.typo', + 'params.content[1].content.params.text' + ]) + expect(problems[0].message).toBe('expected true or false') + expect(problems[2].message).toMatch(/^has