feat(author): notes for what builds and is almost surely a mistake

Merged
AL
2h ago
+263-9

Closes #241. Item 4 of #219.

What changes

A build notes what H5P allows and is almost surely a mistake. Each is a note, not a problem, and each says what to write:

NoteWhere
No answer marked correctMultiple 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: no tags or entities, any case or spacingMultiple Choice, a Single Choice Set question, a Summary set
A text with no gap, *word*Fill in the Blanks (none in any of its texts), Drag the Words, Mark the Words
A picture with no alt text, where its field is optionalDialog Cards, Flashcards, Image Hotspots, Memory Game's and Image Pairing's matching picture, Question Set's intro, Speak the Words Set's introduction, Branching Scenario's start screen
  • lib/mistakes.mjs runs in checkContent, so a build says them, and so does a check of saved content. The read is unchanged: it says nothing of these.
  • The pictures are one table, ALT_TEXTS, which a test holds to the pack's fields: a picture, and an optional text beside it.
  • blanksGaps in types.mjs is exported, so the gap rule stays H5P.Blanks' own.
  • Docs: design/author.md (a rule, and "Not built"), the README, design/layout.md.

The skill and the MCP server already pass every note on, and each note says what to write, so neither text changes.

Tested

  • One test per kind of note, in a Question Set too, by the sub-content's path. Entities and spacing compare as read. One text with a gap is enough for Fill in the Blanks.
  • The table is held to each type's semantics in the pack.
  • No type file's example says any of them: all 32 build with no new note. apps/skills holds them to that.
  • The owner's 88 real packages, checked as saved: 79 checked against their own libraries.
    • 8 have pictures with no alt text: 36 notes.
    • 1 has answers alike: a test package whose answers all read "Test", 4 notes.
    • None has a question with no answer marked correct or a text with no gap.
  • Suites: the author package, 266 tests in Node and Chromium; pnpm typecheck for the package.

Summary by cubic

Adds notes for H5P content that builds but is almost surely a mistake, closing #241 (item 4 of #219). The build now reports these instead of staying silent, and each note says what to write. Text comparison is locale-independent, so a note does not change with the host's locale.

  • Notes cover: no answer marked correct, duplicate answers or statements (compared as a learner reads them), texts with no gap, and pictures with no alt text where the field is optional.
  • Runs in checkContent, so both builds and checks of saved content report them.
  • ALT_TEXTS maps each picture-with-optional-alt-text location to its fields; a test holds it against the pack's semantics.
  • The read of saved content is unchanged; these come back only as notes, never problems.
  • README and design docs now list which notes appear in which content types.