Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions design/author.md
Original file line number Diff line number Diff line change
Expand Up @@ -305,6 +305,15 @@ text to the content check's rules, and `apps/skills` plays every example untrust
of the library is the sub-content's `metadata.title`. `readSource` keeps its contract.
`sourceType(source, names)` is exported (#176) so the build page hands back the type the build
took and keeps no copy of the rule.
- **A source's own fields are declared once, as `sourceSchema`** (#230). `sourceOf` takes the list
of fields from it, holds each field to it and says its message where the field was written; it is
the `Source` type, it takes no other field, as a build does not, and it is exported so that a
model can be shown the shape before writing a source. What one field cannot say alone stays in
`sourceOf`: the content type named loosely, a licence written with its version, a version for a
licence that takes none, and fields in the wrong place. Every problem of an author is said at
once, and an author written as a name alone is said with the object to write. It is zod/mini,
23 kB minified, since a build runs in a page too, where zod's chained API takes 93 kB; JSON
Schema is made where it is shown.
- **The skill is installed, and its page lists what step 3 fetches.** Claude and ChatGPT install
the skill as a zip, and Grok reads the zip attached to a message; reading it by its link was
dropped (missing-elements.github.io#42). Since the 0.10.0 pin the organisation's site serves the
Expand Down
9 changes: 8 additions & 1 deletion packages/author/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,14 @@ of the machine names given: its `type`, as it is or loosely (`"interactive-book"
none the one name under `contentType` or `library`; `null` where none can be meant, and for a quiz
in the published format (`{ "kind": … }`), which the build reads as a Question Set or a Multiple
Choice by rules of its own. A page that hands a chat a type's notes with a source's problems asks
it, and hands over the type the build took. `ContentGenerator` is the engine underneath, also run by
it, and hands over the type the build took. `sourceSchema` is a source's own fields, `type`,
`title`, `language`, `license`, `authors` and the rest, as the zod/mini schema a build holds them to,
and no other field. To show a model the shape of a source before it writes one, turn it into JSON
Schema with `toJSONSchema(sourceSchema, { io: 'input' })` from zod 4.2 or later, installed as a
dependency of your own, since the author package's copy is not yours to import. A build reads a
source more loosely than the schema, and says what to write: check one with
`buildPackage(source, undefined, { check: true })`, not with the schema alone. `ContentGenerator`
is the engine underneath, also run by
the repository's sweep of every content type.

A tool beside the build takes the libraries as the build loads them, the generator, and the
Expand Down
71 changes: 25 additions & 46 deletions packages/author/lib/build.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,12 @@ import { checkContent, layoutContext, valueAt } from './check.mjs'
import { ContentGenerator, libraryString } from './generator.mjs'
import { installClosure } from './install.mjs'
import { loadLibraries } from './libraries.mjs'
import { CC_VERSIONS, LICENSES, ROLES } from './metadata.mjs'
import { CC_VERSIONS } from './metadata.mjs'
import { machineNameOf, NAMING_KEYS, namingKey, nearestNames } from './names.mjs'
import { quizProblems, quizSource } from './quiz.mjs'
import { outlineOf } from './outline.mjs'
import { SourceError } from './source-error.mjs'
import { authorHolds, holds, NO_FIELD, NO_SOURCE, sourceSchema, TYPE } from './source-schema.mjs'
import { escapeText } from './text.mjs'
import { LAYOUTS, placesOf, videoTimes } from './types.mjs'

Expand All @@ -24,20 +25,18 @@ export { SourceError }
*/

/**
* @typedef {{ name: string, role: string }} Author
* @typedef {{
* type: string, title: string, language: string, license: string, licenseVersion?: string,
* authors: Author[], source?: string, yearFrom?: number, yearTo?: number, params: Record<string, unknown>
* }} Source a package's source: the content type, its metadata, and the parameters that differ from the defaults
* @typedef {import('zod/mini').output<typeof sourceSchema>} Source a package's source, as `sourceSchema`
* declares it: the content type, its metadata, and the parameters that differ from the defaults
* @typedef {Source['authors'][number]} Author
* @typedef {{ path: string, message: string }} Problem
* @typedef {import('./translate.mjs').TranslationReport} TranslationReport
*/

/** @param {unknown} value @returns {value is Record<string, any>} */
const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)

/** A source's fields. */
const FIELDS = ['type', 'title', 'language', 'license', 'licenseVersion', 'authors', 'source', 'yearFrom', 'yearTo', 'params']
/** A source's fields, as `sourceSchema` declares them. */
const FIELDS = Object.keys(sourceSchema.shape)
/** Those a source says of itself, which H5P keeps in an object of their own, `metadata`. */
const OWN = FIELDS.filter((name) => name !== 'type' && name !== 'params')

Expand Down Expand Up @@ -79,8 +78,7 @@ export function sourceOf(input, names) {
/** @type {Problem[]} */
const problems = []
const report = (/** @type {string} */ path, /** @type {string} */ message) => problems.push({ path, message })
if (!isObject(input)) throw new SourceError([{ path: 'source', message: 'expected an object: { "type", "title", "language", "license", "authors", "params" }' }])
const fields = `the fields are ${FIELDS.join(', ')}`
if (!isObject(input)) throw new SourceError([{ path: 'source', message: NO_SOURCE }])
/** @type {Record<string, any>} what is written for each field */
const given = Object.fromEntries(FIELDS.filter((name) => input[name] !== undefined).map((name) => [name, input[name]]))
/** @type {Record<string, string>} where each is written */
Expand Down Expand Up @@ -111,20 +109,22 @@ export function sourceOf(input, names) {
at[name] = `metadata.${name}`
}
for (const inner of Object.keys(value)) {
if (!own.includes(inner)) report(`metadata.${inner}`, OWN.includes(inner) ? 'is written beside type already' : `is not a field of a source; ${fields}`)
if (!own.includes(inner)) report(`metadata.${inner}`, OWN.includes(inner) ? 'is written beside type already' : NO_FIELD)
}
rest = rest.filter((each) => each !== 'metadata')
}
// The content's fields beside `type`.
if (rest.length && given.params === undefined) {
report('params', `is not written: the content's fields go in it, not beside type: write "params": { ${rest.map((key) => `"${key}": …`).join(', ')} }`)
given.params = Object.fromEntries(rest.map((key) => [key, input[key]]))
} else for (const key of rest) report(key, `is not a field of a source; ${fields}`)
} else for (const key of rest) report(key, NO_FIELD)

// Each field held to `sourceSchema`, with what it cannot say alone written here.
const field = sourceSchema.shape
let typed = false
const type = typeof given.type === 'string' ? given.type.trim() : ''
if (named) typed = true
else if (!type) report(at.type, 'expected a content type\'s machine name, such as "H5P.Blanks"')
else if (!type) holds(field.type, given.type, at.type, report)
else if (names) {
const found = machineNameOf(type, names)
if (!found) {
Expand All @@ -142,57 +142,36 @@ export function sourceOf(input, names) {
report(at.type, `takes the machine name alone, "${name}": the version is the pack's newest`)
given.type = name
typed = true
} else if (!/^\S+$/.test(type)) report(at.type, 'expected a content type\'s machine name, such as "H5P.Blanks"')
} else if (!/^\S+$/.test(type)) report(at.type, TYPE)
else typed = true

/** @type {Record<string, any>} */
/** @type {Record<string, any>} a stand-in for each field that does not hold */
const source = { type: typed ? String(given.type).trim() : '', title: '', language: 'en', license: 'U', authors: [], params: {} }
if (typeof given.title !== 'string' || !given.title.trim()) report(at.title, 'expected the activity\'s title')
else if (given.title.length > 255) report(at.title, 'takes at most 255 characters')
else source.title = given.title
let tag = typeof given.language === 'string'
try {
if (tag) Intl.getCanonicalLocales(given.language)
} catch {
tag = false
}
if (tag) source.language = given.language
else report(at.language, 'expected a BCP 47 language tag, such as "en" or "de-AT"')
if (holds(field.title, given.title, at.title, report)) source.title = given.title
if (holds(field.language, given.language, at.language, report)) source.language = given.language
// A licence written with its version, "CC BY 4.0", as it is spoken of: H5P keeps the version in
// a field of its own. The names alone, which this problem used to list, had a chat drop the
// version to fit them.
const versioned = typeof given.license === 'string' ? /^CC[ -](BY(?:-(?:NC-SA|NC-ND|NC|ND|SA))?)[ -]v?(\d\.\d)$/i.exec(given.license.trim()) : null
const license = versioned ? `CC ${versioned[1].toUpperCase()}` : given.license
if (LICENSES.includes(given.license)) source.license = given.license
else if (versioned) {
if (versioned) {
const written = JSON.stringify(given.license)
if (given.licenseVersion !== undefined) report(at.license, `${written} holds the version too, which licenseVersion names: write "license": "${license}"`)
else if (CC_VERSIONS.includes(versioned[2])) report(at.license, `${written} holds the version too: write "license": "${license}" and "licenseVersion": "${versioned[2]}"`)
else report(at.license, `${written} holds a version too: write "license": "${license}" and "licenseVersion", one of ${CC_VERSIONS.join(', ')}`)
source.license = license
if (given.licenseVersion === undefined && CC_VERSIONS.includes(versioned[2])) source.licenseVersion = versioned[2]
} else report(at.license, `use one of ${LICENSES.map((each) => JSON.stringify(each)).join(', ')}; "U" when it is not known`)
} else if (holds(field.license, given.license, at.license, report)) source.license = given.license
if (given.licenseVersion !== undefined) {
if (!String(license).startsWith('CC ') || license === 'CC0 1.0' || license === 'CC PDM') report(at.licenseVersion, 'is for a Creative Commons BY licence only')
else if (!CC_VERSIONS.includes(given.licenseVersion)) report(at.licenseVersion, `use one of ${CC_VERSIONS.join(', ')}`)
else source.licenseVersion = given.licenseVersion
else if (holds(field.licenseVersion, given.licenseVersion, at.licenseVersion, report)) source.licenseVersion = given.licenseVersion
}
if (!Array.isArray(given.authors) || !given.authors.length) report(at.authors, 'name at least one author: [{ "name": "…", "role": "Author" }]')
else given.authors.forEach((/** @type {unknown} */ author, /** @type {number} */ i) => {
const before = problems.length
if (!isObject(author) || typeof author.name !== 'string' || !author.name.trim()) report(`${at.authors}[${i}].name`, 'expected the author\'s name')
else if (!ROLES.includes(author.role)) report(`${at.authors}[${i}].role`, `use one of ${ROLES.join(', ')}`)
else for (const key of Object.keys(author)) if (key !== 'name' && key !== 'role') report(`${at.authors}[${i}].${key}`, 'is not part of an author; write name and role')
if (problems.length === before) source.authors.push(author)
})
if (given.source !== undefined && (typeof given.source !== 'string' || !/^https?:\/\/\S+$/i.test(given.source))) report(at.source, 'expected the address the content comes from')
else if (given.source !== undefined) source.source = given.source
for (const key of ['yearFrom', 'yearTo']) {
if (given[key] !== undefined && !Number.isInteger(given[key])) report(at[key], 'expected a year')
else if (given[key] !== undefined) source[key] = given[key]
// The authors that hold are kept, so the content is checked with them.
const authorsHold = holds(field.authors, given.authors, at.authors, report)
if (Array.isArray(given.authors)) source.authors = authorsHold ? given.authors : given.authors.filter(authorHolds)
for (const key of /** @type {const} */ (['source', 'yearFrom', 'yearTo', 'params'])) {
if (given[key] !== undefined && holds(field[key], given[key], at[key], report)) source[key] = given[key]
}
if (given.params !== undefined && !isObject(given.params)) report('params', 'expected an object of the content type\'s fields')
else if (given.params !== undefined) source.params = given.params
return { source: /** @type {Source} */ (source), problems, typed }
}

Expand Down
6 changes: 4 additions & 2 deletions packages/author/lib/core.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,9 @@
* @missing-elements/h5p-author/core: what the package does that needs neither Node nor a page, for
* a tool that runs beside a build in either: the generator, the libraries loaded as a build loads
* them from any source of them, the parts a content type's build can read, the check of saved
* content, the rules for text, and which content type a source is written in, as a build reads it. The package's entry for Node (`.`) and the one for a page
* (`./browser`) carry all of it, each with its own `buildPackage` and `openPack`.
* content, the rules for text, which content type a source is written in, as a build reads it, and
* a source's own fields as the schema a build holds them to. The package's entry for Node (`.`) and
* the one for a page (`./browser`) carry all of it, each with its own `buildPackage` and `openPack`.
*/

export { bundleLibraries, contentTypes } from './bundle.mjs'
Expand All @@ -15,6 +16,7 @@ export { loadLibraries, packageLibraries } from './libraries.mjs'
export { sourceType } from './names.mjs'
export { GENERATED_END, GENERATED_START } from './schema.mjs'
export { SourceError } from './source-error.mjs'
export { sourceSchema } from './source-schema.mjs'
export { allowedTags, editorWidget, markupText, plainText, takesMarkup } from './text.mjs'

/**
Expand Down
105 changes: 105 additions & 0 deletions packages/author/lib/source-schema.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
/**
* A source's own fields, declared once: the outer shape of what a build takes. `sourceOf` holds
* each field to it and says its message where the field was written, it is the `Source` type, and
* an app is shown it as the shape of a source before one is written (#230).
*
* In zod/mini, since a build runs in a page too, where zod's chained API weighs four times as
* much. Its messages are the build's problems, each with what to write.
*/
import * as z from 'zod/mini'
import { CC_VERSIONS, LICENSES, ROLES } from './metadata.mjs'

/** @internal */
export const TYPE = 'expected a content type\'s machine name, such as "H5P.Blanks"'
const TITLE = 'expected the activity\'s title'
const LANGUAGE = 'expected a BCP 47 language tag, such as "en" or "de-AT"'
const NAME = 'expected the author\'s name'
const AUTHORS = 'name at least one author: [{ "name": "…", "role": "Author" }]'
const ADDRESS = 'expected the address the content comes from'
const YEAR = 'expected a year'

/** @param {string} text */
const written = (text) => text.trim() !== ''

/** @param {string} tag */
const isTag = (tag) => {
try {
Intl.getCanonicalLocales(tag)
return true
} catch {
return false
}
}

/** An author, in a role H5P names. One written as a name alone, as a chat writes one, is said with the object to write. */
const author = z.strictObject({
name: z.string({ error: NAME }).check(z.refine(written, { error: NAME })),
role: z.enum(ROLES, { error: `use one of ${ROLES.join(', ')}` })
}, {
error: (issue) => {
if (issue.code === 'unrecognized_keys') return 'is not part of an author; write name and role'
return typeof issue.input === 'string'
? `expected an author: write { "name": ${JSON.stringify(issue.input)}, "role": "Author" }`
: 'expected an author, { "name": "…", "role": "Author" }'
}
})

/** A source's fields, in the order they are listed, each with what it takes. */
const fields = {
type: z.string({ error: TYPE }).check(z.refine(written, { error: TYPE }), z.describe('The content type\'s machine name, as "H5P.MultiChoice"')),
title: z.string({ error: TITLE }).check(z.refine(written, { error: TITLE }), z.maxLength(255, { error: 'takes at most 255 characters' })),
language: z.string({ error: LANGUAGE }).check(z.refine(isTag, { error: LANGUAGE }), z.describe('A BCP 47 tag, as "en"')),
license: z.enum(LICENSES, { error: `use one of ${LICENSES.map((each) => JSON.stringify(each)).join(', ')}; "U" when it is not known` }),
licenseVersion: z.optional(z.enum(CC_VERSIONS, { error: `use one of ${CC_VERSIONS.join(', ')}` }).check(z.describe('For a CC BY licence only'))),
authors: z.array(author, { error: AUTHORS }).check(z.minLength(1, { error: AUTHORS })),
source: z.optional(z.string({ error: ADDRESS }).check(z.regex(/^https?:\/\/\S+$/i, { error: ADDRESS }))),
yearFrom: z.optional(z.int({ error: YEAR })),
yearTo: z.optional(z.int({ error: YEAR })),
params: z.optional(z.record(z.string(), z.unknown(), { error: 'expected an object of the content type\'s fields' })
.check(z.describe('The content type\'s fields that differ from their defaults')))
}

/** @internal What is said of a key that is no field of a source. */
export const NO_FIELD = `is not a field of a source; the fields are ${Object.keys(fields).join(', ')}`
/** @internal What is said of a source that is no object. */
export const NO_SOURCE = 'expected an object: { "type", "title", "language", "license", "authors", "params" }'

/**
* What a source says of itself, and its content's fields in `params`, and nothing else, as a build
* refuses any other field. What a field cannot say alone stays in `sourceOf`: a content type named
* loosely, a licence written with its version, a version for a licence that takes none, and fields
* written in the wrong place.
*/
export const sourceSchema = z.strictObject(fields, {
error: (issue) => (issue.code === 'unrecognized_keys' ? NO_FIELD : NO_SOURCE)
})

/**
* Holds a value written for one of `sourceSchema`'s fields to it, and says each problem at the path
* it was written at, one a path, as a build says one thing of a field.
* @param {z.ZodMiniType} schema one of `sourceSchema.shape`
* @param {unknown} value as written
* @param {string} path where it was written
* @param {(path: string, message: string) => void} report
* @returns {boolean} whether it holds
* @internal
*/
export function holds(schema, value, path, report) {
const result = schema.safeParse(value)
if (result.success) return true
const said = new Set()
for (const issue of result.error.issues) {
// Keys that are no part of an object are one issue: a problem each, at its own path.
const places = issue.code === 'unrecognized_keys' ? issue.keys.map((key) => [...issue.path, key]) : [issue.path]
for (const place of places) {
const at = path + place.map((key) => (typeof key === 'number' ? `[${key}]` : `.${String(key)}`)).join('')
if (said.has(at)) continue
said.add(at)
report(at, issue.message)
}
}
return false
}

/** @internal An author as `sourceSchema` takes one, for keeping those that are right. */
export const authorHolds = (/** @type {unknown} */ value) => author.safeParse(value).success
3 changes: 2 additions & 1 deletion packages/author/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,8 @@
"@missing-elements/h5p-libraries": "workspace:*",
"@missing-elements/h5p-normalize": "workspace:^",
"@missing-elements/h5p-offline-player": "workspace:*",
"@zip.js/zip.js": "^2.24.0"
"@zip.js/zip.js": "^2.24.0",
"zod": "^4.6.7"
},
"devDependencies": {
"@missing-elements/h5p-verify": "workspace:*",
Expand Down
Loading
Loading