@moood/check 0.0.0-stage → 0.1.0

package/problems/problems.js

@@ -0,0 +1,94 @@
+// What check finds wrong, as data: a problem is {at — where (a file, a file:line, a folder), code, values — names,
+// paths, texts and numbers as written} — and say(problem, tr) says it in words, in the language of the translator it
+// is given (MooodI18n.translator: English for the command line; a page its own language — the translations beside
+// this file, lang/<lang>.json: a browser's page loads them as any part of moood's pages, i18n/words.js). A code
+// say(…) knows nothing of is said as it is.
+export const problem = (at, code, values = {}) => ({ at, code, values });
+
+export function say({ code, values: v }, tr) {
+  switch (code) {
+    // where worlds, games and articles lie; what they say of themselves
+    case 'two-kinds': return tr('{files} in one folder — a folder is one world, one game or one article', v);
+    case 'json': return tr('not JSON: {error}', v);
+    case 'not-object': return tr('not an object', v);
+    case 'languages': return tr('"languages" — the languages it is in: a list of moood\'s ({known})', v);
+    case 'languages-unknown': return tr('"languages" — {languages}: not moood\'s ({known})', v);
+    case 'languages-twice': return tr('"languages" — {languages} twice', v);
+    // how they name each other ({field}: "world", "about"; {ref}: as written)
+    case 'ref-not-path': return tr('"{field}" {ref} — not a path', v);
+    case 'ref-repository': return tr('"{field}" {ref} — {name}: not a repository (owner/name)', v);
+    case 'ref-version': return tr('"{field}" {ref} — {version}: not a branch, a tag or a commit', v);
+    case 'ref-path': return tr('"{field}" {ref} — {path}: not a path in the repository (. — its root)', v);
+    case 'ref-neither': return tr('"{field}" {ref} — neither a path from here nor repo@ref:path', v);
+    case 'ref-out': return tr('"{field}" {ref} — out of the repository', v);
+    case 'world-none': return tr('"world" — the world it is played on: a path from here, or repo@ref:path', v);
+    case 'world-not-there': return tr('"{field}" {ref} — no world there ({file})', v);
+    case 'world-languages': return tr('"{field}" {ref} — its world is not in {languages}: a game is in a language only if its world is', v);
+    case 'about-not-list': return tr('"about" — a list of the worlds, games and scenes it is about (paths from here, or repo@ref:path)', v);
+    case 'about-nothing': return tr('"about" {ref} — no world, game or scene there', v);
+    // the engine a scene is for
+    case 'engine': return tr('"engine" {engine} — there is engine 3 (every new scene), and engine 1 (a scene that says none)', v);
+    case 'engine-gone': return tr('"engine" 2 — engine 2 is gone: the scene is written anew for engine 3 ("engine": 3)', v);
+    // a scene's music, as a host makes it (engines/1/music.js: what Lyria takes)
+    case 'music-prompts': return tr('"music" — {count} descriptions that sound: {most} at most', v);
+    case 'music-text': return tr('"music" — the description {n} that sounds: {length} characters, {most} at most', v);
+    case 'music-range': return tr('"music".{field} {value} — {least} to {most}', v);
+    case 'music-scale': return tr('"music".scale "{scale}" — one of {scales}', v);
+    // the code's texts
+    case 'not-javascript': return tr('does not read as JavaScript: {error}', v);
+    case 'tr-not-literal': return tr('tr(…) — its text is not a literal', v);
+    case 'tr-n-not-literal': return tr('tr.n(count, one, other) — its forms are not literals', v);
+    case 'tr-c-not-literal': return tr('tr.c(context, text) — not literals', v);
+    case 'tr-line-not-literal': return tr('tr.{name}(who, text) — not literals', v);
+    case 'tr-not-own': return tr('tr.{name} — not for a world\'s or a game\'s code (tr, tr.n, tr.c, tr.line, tr.thought)', v);
+    case 'tr-tag': return tr('tr`…` — call it: tr(\'…\')', v);
+    case 'tr-value': return tr('tr — not a value (T = tr, f(tr)): call it where its text is written', v);
+    case 'own-variable': return tr('{name} is the language\'s own name — not a variable', v);
+    case 'own-function': return tr('{name} is the language\'s own name — not a function', v);
+    case 'own-set': return tr('{name} is the language\'s own name — not to be set', v);
+    case 'own-parameter': return tr('{name} is the language\'s own name — not a parameter', v);
+    // a line someone says
+    case 'person-line-not-literal': return tr('person(who).{name}(text) — not literals', v);
+    case 'act-say-game': return tr('act(who, \'say\', text) — a game\'s line is b.say(who, text)', v);
+    case 'act-say-not-literal': return tr('act(who, \'say\', text) — not literals', v);
+    case 'line-speaker': return tr('{name}(who, text) — the text written here, its speaker not: a line is said by someone written beside it ({name}(\'who\', \'…\'))', v);
+    case 'line-whose': return tr('.{name}(\'…\') — whose line it is is not written beside it: s.person(\'who\').{name}(\'…\'), or s.{name}(\'who\', \'…\')', v);
+    case 'line-bare': return tr('{name}(who, text) — a text in it is not a line: write it whole here, or mark each where it is written (tr.line, tr.thought)', v);
+    case 'line-kept-how': return tr('{name}(who, line, { how }) — a kept line\'s own manner is kept with it: tr.line(who, text, { how })', v);
+    case 'voice-not-literal': return tr('{name} — its voice, how are not literals', v);
+    case 'how-not-literal': return tr('{name} — its how is not a literal', v);
+    case 'voice-who': return tr('{name} — "who" is not heard: a voice is {voice, how}', v);
+    case 'voice-spread': return tr('{name} — its voice is spread (…): say it whole, in literals', v);
+    case 'voice-game': return tr('{name} — a game\'s line is heard in its person\'s voice (people.json): its own is { how }', v);
+    // a text shown as it is (a read field, markup)
+    case 'braced': return tr('"{text}" — a { name } in a text shown as it is (nothing goes into it)', v);
+    case 'not-text': return tr('{field} — not a text', v);
+    // translations
+    case 'not-strings': return tr('not {"strings": [entries]}', v);
+    case 'translated-twice': return tr('"{text}" — translated twice', v);
+    case 'no-translations': return tr.n(v.count, 'none — {n} text to translate into {lang}', 'none — {n} texts to translate into {lang}', v);
+    case 'untranslated': return tr('"{text}" — not translated', v);
+    case 'untranslated-forms': return tr('"{text}" — not translated (its forms: {forms})', v);
+    case 'no-form': return tr('"{text}" — no "{form}" form', v);
+    case 'form-names': return tr('"{text}" — its "{form}" form says {{names}}, the text {{wanted}} (and { n }, or not)', v);
+    case 'names': return tr('"{text}" — the translation says {{names}}, the text {{wanted}}', v);
+    case 'tags': return tr('"{text}" — the translation\'s tags are {tags}, the line\'s {wanted} (heard as written, in English)', v);
+    case 'unsaid': return tr('"{text}" — the code no longer says it (check --write lays the file out anew)', v);
+    case 'data': return tr('its data ({files}) is not the source\'s ({wanted})', v);
+    // a game's people
+    case 'person-not-object': return tr('"{who}" — not {voice, how, short}', v);
+    case 'person-field': return tr('"{who}".{field} — a person is {voice, how, short}', v);
+    case 'person-name': return tr('"{who}".name — a person is {voice, how, short} (who they are is their voice and their manner)', v);
+    case 'person-not-text': return tr('"{who}".{field} — not a text', v);
+    case 'line-no-person': return tr('"{text}" — said by "{who}", no one of {people}', v);
+    case 'thought-no-short': return tr('"{text}" — thought by "{who}", who has no short name ({people})', v);
+    // articles
+    case 'article-title': return tr('no "title" and "date"', v);
+    case 'article-story': return tr('none — the article\'s text', v);
+    case 'article-none': return tr('none — the article in {lang}', v);
+    case 'article-no-title': return tr('no "title" — the article in {lang}', v);
+    case 'article-no-summary': return tr('no "summary"', v);
+    case 'article-story-lang': return tr('none — the article\'s text in {lang}', v);
+    default: return code;
+  }
+}

package/repository.js

@@ -0,0 +1,126 @@
+// A repository of content as it lies: a folder in which every folder (at any depth, the root too) with world.json is
+// a world, with game.json a game, with article.json an article — as many as it has, mixed; a folder that is one is not
+// searched further (its scenes/, modules/, bespoke/ are its own), and one with two of these files is wrong — and how
+// they name each other: a path from the one that names, or `repo@ref:path` for another repository. What check reads
+// (scopes.js) and the hosts serve (the local player: player/; moood's studio: a git tree at a commit).
+//   A repository is read through a source of its files — a folder on disk (folder), or whatever a host reads one from:
+//     list(dir) → the entries of a folder ('' the root, else ending in /): [{name, dir}], or null — there is none;
+//     read(path) → a file's text (UTF-8), or null — there is none;
+//   and one that is written to (a folder: check --write lays out the translations' files) —
+//     write(path, text) — the file, its folders made as needed;
+//   and a host's (docs/host.md: the files the pages are given by their content) —
+//     id(path) → the id of a file's content: git's blob sha (blobId), or null — there is none.
+//   A folder on disk is read as git reads a repository: a symbolic link is no file and no folder of it — never followed,
+// never written through —, and nothing outside it is read.
+import { createHash } from 'node:crypto';
+import { lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, resolve, sep, posix as P } from 'node:path';
+import { problem } from './problems/problems.js';
+
+export const natural = (a, b) => a.localeCompare(b, 'en', { numeric: true });
+const KINDS = ['world', 'game', 'article'];
+
+// A path of a folder (real: the folder's own path, links resolved) as it lies there → the path, or null: it leads out
+// of the folder, or through a symbolic link (or there is nothing there)
+export function within(real, path) {
+  const p = resolve(real, `.${sep}${path}`);
+  if (p !== real && !p.startsWith(`${real}${sep}`)) return null;
+  try { return realpathSync(p) === p ? p : null; } catch { return null; }
+}
+const kind = p => { try { return lstatSync(p); } catch { return null; } };
+
+// the id of a file's content (its bytes): git's blob sha — the same whether a host reads it from disk or from git
+export const blobId = bytes => createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+
+// a folder on disk as a source
+export function folder(root) {
+  const real = realpathSync(root);
+  return {
+    async list(dir) {
+      const p = within(real, dir);
+      if (!p || !kind(p).isDirectory()) return null;
+      return readdirSync(p, { withFileTypes: true }).filter(d => d.isDirectory() || d.isFile()).map(d => ({ name: d.name, dir: d.isDirectory() }));
+    },
+    async read(path) {
+      const p = within(real, path);
+      return p && kind(p).isFile() ? readFileSync(p, 'utf8') : null;
+    },
+    // (a file that is there is written over only if it is one, not a link; folders made only under one that is the
+    // folder's own)
+    async write(path, text) {
+      const p = resolve(real, `.${sep}${path}`);
+      let up = dirname(p);
+      while (!kind(up)) up = dirname(up);
+      const there = kind(p);
+      if (!p.startsWith(`${real}${sep}`) || !within(real, up.slice(real.length + 1)) || (there && !there.isFile())) throw new Error(`${path}: not a file of the folder (a symbolic link on the way, or out of it) — not written`);
+      mkdirSync(dirname(p), { recursive: true });
+      writeFileSync(p, text);
+    },
+  };
+}
+
+// The worlds, games and articles of a repository (its source): [{kind, base — its folder from root ('' the root, else
+// ending in /), json — its world.json, game.json or article.json read (null: not an object — the problem said)}], and
+// what is wrong with where they lie (problems/problems.js)
+export async function units(source) {
+  const problems = [];
+  const walk = async folder => {
+    const entries = await source.list(folder) ?? [];
+    const kinds = KINDS.filter(k => entries.some(e => !e.dir && e.name === `${k}.json`));
+    if (kinds.length > 1) { problems.push(problem(folder || './', 'two-kinds', { files: kinds.map(k => `${k}.json`).join(', ') })); return []; }
+    if (kinds.length) {
+      const name = `${folder}${kinds[0]}.json`;
+      let json = null;
+      try { json = JSON.parse(await source.read(name)); } catch (e) { problems.push(problem(name, 'json', { error: e.message })); }
+      if (json !== null && (typeof json !== 'object' || Array.isArray(json))) { problems.push(problem(name, 'not-object')); json = null; }
+      return [{ kind: kinds[0], base: folder, json }];
+    }
+    const inside = entries.filter(e => e.dir && !e.name.startsWith('.') && e.name !== 'node_modules').sort((a, b) => natural(a.name, b.name));
+    return (await Promise.all(inside.map(e => walk(`${folder}${e.name}/`)))).flat();
+  };
+  const found = await walk('');
+  return { units: found, problems };
+}
+
+// The languages a world, a game or an article says it is in (its "languages": a list of moood's — `known` —, each
+// once) → {languages} | {problem: {code, values}} — not said rightly: in none (the one rule of check and the hosts)
+export function languagesOf(json, known) {
+  const l = json?.languages, all = known.join(', ');
+  if (!Array.isArray(l) || !l.length || !l.every(x => typeof x === 'string')) return { problem: { code: 'languages', values: { known: all } } };
+  const bad = l.filter(x => !known.includes(x)), twice = l.filter((x, i) => l.indexOf(x) !== i);
+  if (bad.length) return { problem: { code: 'languages-unknown', values: { languages: bad.join(', '), known: all } } };
+  if (twice.length) return { problem: { code: 'languages-twice', values: { languages: twice.join(', ') } } };
+  return { languages: l };
+}
+
+// A reference to a world, a game or a scene (a game's "world"; an article's "about"): another
+// repository's — repo@ref:path (owner/name; a branch, a tag or a commit; a path in it, `.` its root) —, or a path from
+// the folder `from` (from root, '' or ending in /), within the repository:
+// → {foreign: {repo, ref, path — from its root, posix, '' the root}} | {path: from root, posix, '' the root} | {wrong:
+// {code, values} — what is wrong with it: a problem's (problems/problems.js), with the field and the reference}
+const REPO = /^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/;
+const REF = /^(?![-/.])(?!.*(?:\.\.|\/\/|@\{|\.lock$|[/.]$))[A-Za-z0-9._/-]+$/;
+const relativePath = p => p !== '' && !p.startsWith('/') && !p.includes('\\');
+const wrong = (code, values = {}) => ({ wrong: { code, values } });
+export function reference(ref, from) {
+  if (typeof ref !== 'string' || !ref) return wrong('ref-not-path');
+  const m = /^([^@:]+)@([^:]+):(.*)$/.exec(ref);
+  if (m) {
+    if (!REPO.test(m[1])) return wrong('ref-repository', { name: m[1] });
+    if (!REF.test(m[2])) return wrong('ref-version', { version: m[2] });
+    const p = P.normalize(m[3] || '/');
+    if (!relativePath(m[3]) || p === '..' || p.startsWith('../')) return wrong('ref-path', { path: m[3] });
+    return { foreign: { repo: m[1], ref: m[2], path: p === '.' ? '' : p.replace(/\/$/, '') } };
+  }
+  if (ref.includes(':') || !relativePath(ref)) return wrong('ref-neither');
+  const p = P.normalize(`${from}${ref}`);
+  if (p === '..' || p.startsWith('../')) return wrong('ref-out');
+  return { path: p === '.' ? '' : p.replace(/\/$/, '') };
+}
+
+// a path in a repository as a world's scene (<world>/scenes/<folder>): {world — the world's folder ('' the root),
+// folder} | null — it is not one
+export function scenePath(path) {
+  const m = /^(?:(.*)\/)?scenes\/([^/]+)$/.exec(path);
+  return m ? { world: m[1] ?? '', folder: m[2] } : null;
+}

package/scopes.js

@@ -0,0 +1,119 @@
+// What a repository holds, where its texts come from and where their translations lie. A repository is a folder: every
+// folder in it (at any depth, the root too) with world.json is a world, with game.json a game, with article.json an
+// article — as many as it has, mixed; a folder that is one is not searched further (its scenes/, modules/, bespoke/ are
+// its own), and one with two of these files is wrong. Each says its languages (`"languages": [...]`, moood's:
+// i18n/languages.json) and is checked in those, and only those; a game names its world by a path from its own folder,
+// or `repo@ref:path` for another repository (only its form is checked here: nothing is fetched), and is in a language
+// only if its world is; an article names the worlds, games and scenes it is about (`"about": [...]`) the same way
+// (repository.js).
+//   The scopes: a world's (world.json → lang/<lang>.json), each of its scenes' (scenes/<folder>: scene.json, its code,
+// its widgets' markup → scenes/<folder>/lang/<lang>.json), each of its modules' (modules/<name>.js →
+// modules/<name>.<lang>.json); a game's (game.json, bespoke/people.json, bespoke/'s code → bespoke/lang/<lang>/strings.json;
+// its data by language: bespoke/lang/<lang>/<name>.json, the source language's too). An article is translated whole
+// (index.js). A folder with no world, game or article in it is a folder of moood's own pages (its code and pages →
+// lang/<lang>.json), in every language moood has.
+import { readFileSync } from 'node:fs';
+import { FIELDS, fromCode, fromJson, fromMarkup } from './extract.js';
+import { problem } from './problems/problems.js';
+import { languagesOf, natural, reference, scenePath, units } from './repository.js';
+
+export const LANGUAGES = Object.keys(JSON.parse(readFileSync(new URL('./i18n/languages.json', import.meta.url), 'utf8')));
+
+// the files under a folder of the source ('.' the root), by their path from its root, in natural order; skip — a path
+// left out
+async function filesUnder(source, folder, skip = () => false) {
+  const walk = async dir => {
+    const entries = await source.list(dir) ?? [];
+    return (await Promise.all(entries.map(e => (e.dir ? walk(`${dir}${e.name}/`) : [`${dir}${e.name}`])))).flat();
+  };
+  return (await walk(folder === '.' ? '' : `${folder.replace(/\/$/, '')}/`)).filter(p => !skip(p)).sort(natural);
+}
+// whether a file is there
+const there = async (source, path) => await source.read(path) !== null;
+
+// what the files of a scope say: {entries, problems} — own: a world's or a game's (extract.js fromCode); game: a game's
+async function read(source, files, own, game) {
+  const entries = [], problems = [];
+  for (const f of files) {
+    const text = await source.read(f), name = f.split('/').pop();
+    const r = name in FIELDS ? fromJson(text, f, FIELDS[name])
+      : /\.(m?js)$/.test(f) ? fromCode(text, f, own, game)
+        : /\.html$/.test(f) ? fromMarkup(text, f, own, game) : null;
+    if (r) { entries.push(...r.entries); problems.push(...r.problems); }
+  }
+  return { entries, problems };
+}
+
+// a world's, game's or article's languages as it says them (null: not said rightly — the problem said: repository.js)
+function languages(u, problems) {
+  if (!u.json) return null;
+  const l = languagesOf(u.json, LANGUAGES);
+  if (l.problem) problems.push(problem(`${u.base}${u.kind}.json`, l.problem.code, l.problem.values));
+  return l.languages ?? null;
+}
+// what is wrong with a reference (repository.js: its wrong), as a problem of the file that makes it
+const misnamed = (name, field, ref, w) => problem(name, w.code, { field, ref: JSON.stringify(ref), ...w.values });
+
+// A repository's (or a pages' folder's), read through its source (repository.js): its scopes — [{name, kind, languages
+// — the ones it is checked in, files, file(lang) — where its translation lies, data(lang) — the folder of its data by
+// language and people — its people.json (a game's)}] —, its articles ([{base, json, languages}]) and what is wrong with
+// the repository itself: where its worlds, games and articles lie, what they say of themselves and of each other
+// (problems/problems.js)
+export async function scopes(source) {
+  const out = [], articles = [];
+  const { units: found, problems } = await units(source);
+  if (!found.length && !problems.length) {
+    // (a folder of pages: its code, its pages; not a library's bundle built into it, *.min.js)
+    out.push({ name: '.', kind: 'front', languages: LANGUAGES, files: (await filesUnder(source, '.', p => p.startsWith('lang/') || p.includes('node_modules/') || p.endsWith('.min.js')))
+      .filter(p => /\.(m?js|html)$/.test(p) || p.split('/').pop() in FIELDS),
+      file: lang => `lang/${lang}.json` });
+  }
+  const worlds = new Map();  // a world's folder ('' the root; no ending /) → its languages (null: not said rightly)
+  for (const u of found) if (u.kind === 'world') worlds.set(u.base.replace(/\/$/, ''), languages(u, problems));
+  for (const u of found) {
+    const b = u.base, name = `${b}${u.kind}.json`;
+    if (u.kind === 'article') {
+      articles.push({ ...u, languages: languages(u, problems) });
+      // what it is about: worlds, games, scenes — paths from its folder, or repo@ref:path
+      const about = u.json?.about ?? [];
+      if (!Array.isArray(about)) problems.push(problem(name, 'about-not-list'));
+      else for (const a of about) {
+        const r = reference(a, b);
+        if (r.wrong) { problems.push(misnamed(name, 'about', a, r.wrong)); continue; }
+        if (r.foreign) continue;
+        const of = scenePath(r.path), scene = of && worlds.has(of.world) && await there(source, `${r.path}/scene.json`);
+        if (!scene && !found.some(f => f.kind !== 'article' && f.base === (r.path ? `${r.path}/` : ''))) problems.push(problem(name, 'about-nothing', { ref: JSON.stringify(a) }));
+      }
+    } else if (u.kind === 'world') {
+      const said = worlds.get(b.replace(/\/$/, '')) ?? [];
+      out.push({ name, kind: 'world', languages: said, files: [name], file: lang => `${b}lang/${lang}.json` });
+      for (const folder of ((await source.list(`${b}scenes/`)) ?? []).filter(e => e.dir).map(e => e.name).sort(natural)) {
+        const base = `${b}scenes/${folder}`;
+        out.push({ name: base, kind: 'scene', languages: said, files: (await filesUnder(source, base, p => p.startsWith(`${base}/lang/`))).filter(p => /\.(js|html)$/.test(p) || p.endsWith('/scene.json')),
+          file: lang => `${base}/lang/${lang}.json` });
+      }
+      for (const m of (await filesUnder(source, `${b}modules`)).filter(p => /^modules\/[^/]+\.js$/.test(p.slice(b.length)))) {
+        const base = m.slice(0, -3);
+        out.push({ name: base, kind: 'module', languages: said, files: [m], file: lang => `${base}.${lang}.json` });
+      }
+    } else {
+      const said = languages(u, problems);
+      // its world: there, and in every language the game is in
+      if (u.json) {
+        const w = reference(u.json.world, b), at = { field: 'world', ref: JSON.stringify(u.json.world) };
+        if (u.json.world === undefined) problems.push(problem(name, 'world-none'));
+        else if (w.wrong) problems.push(misnamed(name, 'world', u.json.world, w.wrong));
+        else if (!w.foreign && !worlds.has(w.path)) problems.push(problem(name, 'world-not-there', { ...at, file: `${w.path ? `${w.path}/` : ''}world.json` }));
+        else if (!w.foreign) {
+          const l = worlds.get(w.path), missing = l && said ? said.filter(x => !l.includes(x)) : [];
+          if (missing.length) problems.push(problem(name, 'world-languages', { ...at, languages: missing.join(', ') }));
+        }
+      }
+      const skip = p => p.startsWith(`${b}bespoke/lang/`);
+      out.push({ name, kind: 'game', languages: said ?? [],
+        files: [name, ...(await filesUnder(source, `${b}bespoke`, skip)).filter(p => /\.(m?js|html)$/.test(p) || p === `${b}bespoke/people.json`)],
+        file: lang => `${b}bespoke/lang/${lang}/strings.json`, data: lang => `${b}bespoke/lang/${lang}`, people: `${b}bespoke/people.json` });
+    }
+  }
+  return { problems, articles, scopes: await Promise.all(out.map(async s => ({ ...s, ...await read(source, s.files, s.kind !== 'front', s.kind === 'game') }))) };
+}