@lutrin/core 1.0.0

package/src/deck/highlight.mjs

@@ -0,0 +1,206 @@
+/**
+ * Minimal syntax highlighting (keywords / strings / comments), shared by the
+ * PPTX and HTML renderers. Returns neutral segments
+ * `{ text, kind?, color?, bold?, italic? }` — `kind` ('keyword' | 'string' |
+ * 'comment') is the semantic contract: the HTML renderer relies on it for its
+ * classes, never on the color value (a theme can change the colors without
+ * breaking the highlighting). The colors stay brand design tokens, consumed
+ * as is by the PPTX renderer.
+ *
+ * The block's language (```js, ```python…) picks a profile: comment markers
+ * AND keywords specific to its family — `#097d6c` is not a comment in CSS,
+ * "and" is not a keyword outside Python. Strings are tokenized BEFORE
+ * comments: the `//` of a URL inside a string stays part of the string.
+ */
+
+import { COLORS } from './tokens.mjs';
+
+const kw = (words, flags = '') => new RegExp(`\\b(?:${words})\\b`, flags);
+
+// Keywords by language family. Deliberately without the words that are also
+// ordinary words of the everyday language outside their family (and, or, is,
+// in, not, from…): better a missed keyword than prose set in bold.
+const KEYWORDS = {
+  c: kw(
+    'function|return|const|let|var|if|else|for|while|do|switch|case|break|continue|import|from|export|default|' +
+      'class|extends|implements|new|await|async|try|catch|finally|throw|typeof|instanceof|static|void|this|super|' +
+      'yield|delete|null|true|false|undefined|public|private|protected|interface|type|enum|namespace|readonly|' +
+      'struct|fn|impl|use|mut|pub|match|func|defer|chan|package|int|string|bool|float|double|char|long',
+  ),
+  python: kw(
+    'def|return|if|elif|else|for|while|import|from|as|class|with|lambda|pass|try|except|finally|raise|in|not|' +
+      'and|or|is|global|nonlocal|yield|assert|del|async|await|None|True|False',
+  ),
+  shell: kw(
+    'if|then|else|elif|fi|for|while|until|do|done|case|esac|function|return|exit|export|local|readonly|echo|source',
+  ),
+  ruby: kw(
+    'def|end|class|module|if|elsif|else|unless|while|until|do|return|begin|rescue|ensure|yield|self|nil|true|false|require',
+  ),
+  sql: kw(
+    'SELECT|FROM|WHERE|JOIN|LEFT|RIGHT|INNER|OUTER|FULL|CROSS|ON|GROUP|ORDER|BY|HAVING|LIMIT|OFFSET|INSERT|INTO|' +
+      'VALUES|UPDATE|SET|DELETE|CREATE|ALTER|DROP|TABLE|INDEX|VIEW|AS|AND|OR|NOT|NULL|IN|IS|LIKE|BETWEEN|EXISTS|' +
+      'UNION|DISTINCT|CASE|WHEN|THEN|ELSE|END',
+    'i', // SQL keywords are also written in lowercase
+  ),
+  lua: kw(
+    'function|end|if|then|else|elseif|for|while|repeat|until|do|return|local|nil|true|false|break',
+  ),
+  // unknown language: only words that are unambiguous against prose
+  generic: kw(
+    'function|return|const|let|var|if|else|for|while|import|export|class|def|async|await|new|try|catch|null|true|false|None|True|False',
+  ),
+};
+
+// `#(?!\{)`: #{…} interpolation (Ruby) does not open a comment.
+const HASH = /#.*$/;
+const HASH_NO_INTERP = /#(?!\{).*$/;
+// POSIX: `#` only opens a comment at the start of a word — `$#` (argument
+// count) and `${#var}` (length) are not comments.
+const HASH_SHELL = /(?<=^|\s)#(?!\{).*$/;
+
+/** Profiles: line-comment markers + keyword set. */
+const PROFILES = {
+  c: { comments: [/\/\/.*$/], keywords: KEYWORDS.c },
+  python: { comments: [HASH], keywords: KEYWORDS.python },
+  shell: { comments: [HASH_SHELL], keywords: KEYWORDS.shell },
+  ruby: { comments: [HASH_NO_INTERP], keywords: KEYWORDS.ruby },
+  hash: { comments: [HASH], keywords: null }, // yaml, toml, dockerfile…
+  sql: { comments: [/--.*$/], keywords: KEYWORDS.sql },
+  lua: { comments: [/--.*$/], keywords: KEYWORDS.lua },
+  haskell: { comments: [/--.*$/], keywords: null },
+  tex: { comments: [/(?<!\\)%.*$/], keywords: null }, // \% is the literal percent sign
+  mermaid: { comments: [/%%.*$/], keywords: null },
+  css: { comments: [], keywords: null }, // no line comment: #097d6c stays a color
+  scssline: { comments: [/\/\/.*$/], keywords: null }, // scss/less accept //
+  markup: { comments: [], keywords: null }, // html/xml: <!-- --> is multi-line, out of scope
+  // unknown language: cautious markers — `#` neither interpolation nor
+  // hexadecimal color; `--` only when followed by a space (never a decrement)
+  generic: {
+    comments: [/\/\/.*$/, /#(?!\{)(?![0-9a-fA-F]{3,8}\b).*$/, /--\s.*$/],
+    keywords: KEYWORDS.generic,
+  },
+};
+
+const PROFILE_BY_LANG = {
+  js: 'c',
+  jsx: 'c',
+  mjs: 'c',
+  cjs: 'c',
+  ts: 'c',
+  tsx: 'c',
+  javascript: 'c',
+  typescript: 'c',
+  java: 'c',
+  c: 'c',
+  h: 'c',
+  cpp: 'c',
+  'c++': 'c',
+  cc: 'c',
+  cs: 'c',
+  csharp: 'c',
+  go: 'c',
+  rust: 'c',
+  rs: 'c',
+  swift: 'c',
+  kotlin: 'c',
+  kt: 'c',
+  scala: 'c',
+  php: 'c',
+  dart: 'c',
+  json: 'c',
+  jsonc: 'c',
+  python: 'python',
+  py: 'python',
+  sh: 'shell',
+  bash: 'shell',
+  zsh: 'shell',
+  shell: 'shell',
+  console: 'shell',
+  ruby: 'ruby',
+  rb: 'ruby',
+  yaml: 'hash',
+  yml: 'hash',
+  toml: 'hash',
+  ini: 'hash',
+  dockerfile: 'hash',
+  makefile: 'hash',
+  r: 'hash',
+  sql: 'sql',
+  lua: 'lua',
+  haskell: 'haskell',
+  hs: 'haskell',
+  tex: 'tex',
+  latex: 'tex',
+  mermaid: 'mermaid',
+  css: 'css',
+  scss: 'scssline',
+  less: 'scssline',
+  html: 'markup',
+  xml: 'markup',
+  svg: 'markup',
+};
+
+// Unambiguous alternation (escape OR non-backslash), lazy quantifier bounded
+// by the quote: the form `(?:\\.|(?!\1).)*` blew up into exponential
+// backtracking on an unterminated string full of backslashes (measured:
+// 40 backslashes ≈ 1.3 s, 50 ≈ minutes — the compilation freezes).
+// `[^]` (empty negated class) = "any character, line breaks included": it is
+// the intended idiom, not an oversight — the linter flags it wrongly.
+// biome-ignore lint/correctness/noEmptyCharacterClassInRegex: [^] is deliberate, see above
+const STRING = /(["'`])(?:\\[^]|[^\\])*?\1/;
+
+export function highlightLine(line, lang = '') {
+  // Object.hasOwn: PROFILE_BY_LANG is an object literal — without the guard, a
+  // ```constructor (or ```__proto__) block would pull up a property inherited
+  // from Object.prototype and crash the whole compilation
+  const key = String(lang ?? '').toLowerCase();
+  const prof = PROFILES[Object.hasOwn(PROFILE_BY_LANG, key) ? PROFILE_BY_LANG[key] : 'generic'];
+  const runs = [];
+
+  // text outside strings and comments: look only for keywords in it
+  const plain = (text) => {
+    while (text.length) {
+      const m = prof.keywords ? text.match(prof.keywords) : null;
+      if (!m) {
+        runs.push({ text });
+        return;
+      }
+      if (m.index > 0) runs.push({ text: text.slice(0, m.index) });
+      runs.push({ text: m[0], kind: 'keyword', color: COLORS.primaryDarker, bold: true });
+      text = text.slice(m.index + m[0].length);
+    }
+  };
+
+  let rest = line;
+  while (rest.length) {
+    const str = rest.match(STRING);
+    let com = null;
+    for (const re of prof.comments) {
+      const m = rest.match(re);
+      if (m && (com === null || m.index < com.index)) com = m;
+    }
+    // a string opened before the marker wins: the `//` of a URL inside
+    // "https://…" does not open a comment
+    if (str && (!com || str.index <= com.index)) {
+      if (str.index > 0) plain(rest.slice(0, str.index));
+      runs.push({ text: str[0], kind: 'string', color: COLORS.positiveDark });
+      rest = rest.slice(str.index + str[0].length);
+      continue;
+    }
+    if (com) {
+      if (com.index > 0) plain(rest.slice(0, com.index));
+      runs.push({
+        text: rest.slice(com.index),
+        kind: 'comment',
+        color: COLORS.neutralSecondary,
+        italic: true,
+      });
+      break;
+    }
+    plain(rest);
+    break;
+  }
+  if (!runs.length) runs.push({ text: '' });
+  return runs;
+}

package/src/deck/kit.mjs

@@ -0,0 +1,342 @@
+/**
+ * Kits — a theme, its layouts and its assets as one distributable unit
+ * (see the "Kits" section of the README).
+ *
+ * A KIT is a directory carrying a `kit.json` manifest:
+ *
+ *   my-kit/
+ *   ├── kit.json          manifest — the only mandatory file
+ *   ├── theme.json        design tokens (theme schema, see theme.mjs)
+ *   ├── layouts/*.json    layouts
+ *   ├── fonts/*.woff2     optional
+ *   └── logo/*.svg        optional
+ *
+ * It is distributed either as is, or compressed into a `.deckkit` file (a zip
+ * archive). The extension describes the CONTENT — a deck kit — and not the
+ * tool that reads it: a format named after its tool ages badly the day some
+ * other tool reads it.
+ *
+ * This module knows only the manifest: reading it, validating it, and
+ * resolving its paths INSIDE the kit. It deliberately ignores installation, the
+ * zip archive and applying the theme — that is what makes it testable on its
+ * own, and what lets `kit install` validate a kit before writing it anywhere.
+ *
+ * Two rules carry the whole safety of the format:
+ *
+ *   1. `name` is constrained (`KIT_NAME_RE`) because it becomes a directory
+ *      name at install time. Validating it here closes path traversal BY THE
+ *      MANIFEST — a kit cannot name itself `../../bin`.
+ *   2. `theme` and `layouts` are resolved by `insideKit()`, which refuses any
+ *      path leaving the kit. A manifest never designates a file on the host
+ *      system.
+ *
+ * As in resolveTheme, nothing ever throws: a manifest that could not be read
+ * becomes an `error` diagnostic and `manifest: null`. The caller decides
+ * (refuse the installation, ignore the kit) — this module does not decide on
+ * its behalf.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { closest } from './suggest.mjs';
+
+/** Name of the manifest, at the root of the kit. */
+export const KIT_MANIFEST = 'kit.json';
+
+/** Extension of an archived kit. */
+export const KIT_EXT = '.deckkit';
+
+/**
+ * Accepted kit names: lowercase letters, digits and hyphens, 64 characters at
+ * most, starting with an alphanumeric character.
+ *
+ * This is the name of the installation directory, so the constraint is a
+ * safety one before it is an aesthetic one: neither `.`, nor `/`, nor `..`
+ * gets through, which makes `<config>/kits/<name>` untraversable whatever the
+ * manifest says.
+ */
+export const KIT_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/** Top-level keys recognized in a kit.json. */
+export const KIT_KEYS = [
+  'name',
+  'version',
+  'description',
+  'author',
+  'homepage',
+  'theme',
+  'layouts',
+];
+
+/** Default values of the two paths — a kit that follows the convention only
+ *  has to declare its name. */
+const DEFAULT_THEME = './theme.json';
+const DEFAULT_LAYOUTS = './layouts';
+
+/** `1.0.0`, `1.0.0-beta.2` — enough to order and to display, without carrying
+ *  a full semver parser the format has no need for. */
+const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+const isFile = (p) => {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+};
+const isDir = (p) => {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Does a relative path leave the kit? A purely LEXICAL verdict, with no disk:
+ * this is the check a manifest can undergo before the kit exists anywhere
+ * (an archive validated in memory). `insideKit` adds the disk to it.
+ *
+ * Windows separators are normalized first: under POSIX, `..\\..\\x` is a valid
+ * file name, and letting it through would turn an archive crafted under
+ * Windows into an escape on the other platforms.
+ */
+export function escapesKit(rel) {
+  if (typeof rel !== 'string' || !rel.trim()) return true;
+  const norm = path.normalize(rel.replace(/\\/g, '/'));
+  if (path.isAbsolute(norm) || /^[A-Za-z]:/.test(norm)) return true;
+  return norm === '..' || norm.startsWith(`..${path.sep}`) || norm.startsWith('../');
+}
+
+/**
+ * Resolves `rel` under `kitDir` and refuses anything that leaves it.
+ *
+ * The symbolic link is checked AFTER resolution (realpath): without that, a
+ * kit could carry a link `theme.json → /etc/passwd`, whose declared path is
+ * nonetheless irreproachable. A link that stays inside the kit is accepted.
+ *
+ * @returns {string|null} absolute path, or null if it leaves the kit
+ */
+export function insideKit(kitDir, rel) {
+  if (typeof rel !== 'string' || !rel.trim()) return null;
+  const root = path.resolve(kitDir);
+  const abs = path.resolve(root, rel);
+  const within = (p, base) => {
+    const r = path.relative(base, p);
+    return r === '' || (!r.startsWith('..') && !path.isAbsolute(r));
+  };
+  if (!within(abs, root)) return null;
+  // Comparing a realpath against a root that is not one would make every
+  // legitimate file look escaped as soon as the root crosses a symbolic
+  // link — the case of /var → /private/var under macOS, and of many a HOME.
+  // So both sides are dereferenced, or neither.
+  try {
+    const realRoot = fs.realpathSync(root);
+    // the path may not exist yet (manifest validated off disk): with no link
+    // to dereference, the lexical check above is enough
+    if (!within(fs.realpathSync(abs), realRoot)) return null;
+  } catch {
+    /* nonexistent — the caller will report the absence, not an escape */
+  }
+  return abs;
+}
+
+/**
+ * Validates an ALREADY parsed manifest (no disk access).
+ *
+ * Separated from `readKit` so that validating a `kit.json` extracted from an
+ * archive in memory — which is what `kit install` will do before writing
+ * anything at all — goes through exactly the same code as validating a kit on
+ * disk.
+ *
+ * @param {unknown} json  content of the kit.json
+ * @param {{ where?: string }} [opts]  label of the source, for the messages
+ * @returns {{ manifest: object|null, diagnostics: Array<{severity, code, message, suggestion?}> }}
+ *          `manifest` is CLEANED UP: unknown keys dropped, `theme` and
+ *          `layouts` normalized to their effective value.
+ */
+export function parseKitManifest(json, { where = KIT_MANIFEST } = {}) {
+  const diags = [];
+  const push = (severity, code, message, suggestion) =>
+    diags.push({ severity, code, message, ...(suggestion ? { suggestion } : {}) });
+  const fail = (message) => {
+    push('error', 'KIT_INVALID', message);
+    return { manifest: null, diagnostics: diags };
+  };
+
+  if (!isPlainObject(json)) return fail(`Kit: ${where} must contain a JSON object.`);
+
+  // --- name: the only mandatory key, and the only one that can invalidate ----
+  if (typeof json.name !== 'string' || !json.name.trim())
+    return fail(
+      `Kit: ${where} must declare a "name" (non-empty string) — it is the name the kit installs under and is referenced by.`,
+    );
+  const name = json.name.trim();
+  if (!KIT_NAME_RE.test(name))
+    return fail(
+      `Kit: "${name}" is not an allowed name — lowercase letters, digits and hyphens, 64 characters at most, starting with a letter or a digit (e.g. "brand-acme"). The name becomes a directory at install time.`,
+    );
+
+  const manifest = { name, theme: DEFAULT_THEME, layouts: DEFAULT_LAYOUTS };
+
+  for (const key of Object.keys(json)) {
+    if (UNSAFE_KEYS.has(key)) continue;
+    if (!KIT_KEYS.includes(key))
+      push(
+        'warning',
+        'KIT_UNKNOWN_KEY',
+        `Kit: unknown key "${key}" in ${where} — ignored.`,
+        closest(key, KIT_KEYS) ?? undefined,
+      );
+  }
+
+  // --- version: optional, but if it is there it must be usable --------------
+  if (json.version != null) {
+    if (typeof json.version === 'string' && VERSION_RE.test(json.version.trim()))
+      manifest.version = json.version.trim();
+    else push('warning', 'KIT_BAD_VALUE', 'Kit: version must be of the form "1.0.0" — ignored.');
+  }
+
+  // --- display metadata -----------------------------------------------------
+  for (const key of ['description', 'author', 'homepage']) {
+    if (json[key] == null) continue;
+    if (typeof json[key] === 'string' && json[key].trim()) manifest[key] = json[key].trim();
+    else push('warning', 'KIT_BAD_VALUE', `Kit: ${key} must be a non-empty string — ignored.`);
+  }
+
+  // --- paths: validated for their FORM here, for existence in readKit -------
+  // "leaves the kit" is an error, not a warning: unlike an unknown key, it
+  // reveals a manifest attempting to reach the host.
+  for (const key of ['theme', 'layouts']) {
+    if (json[key] == null) continue;
+    if (typeof json[key] !== 'string' || !json[key].trim()) {
+      push(
+        'warning',
+        'KIT_BAD_VALUE',
+        `Kit: ${key} must be a relative path inside the kit (e.g. "${key === 'theme' ? DEFAULT_THEME : DEFAULT_LAYOUTS}") — default value kept.`,
+      );
+      continue;
+    }
+    const rel = json[key].trim();
+    if (escapesKit(rel))
+      return fail(
+        `Kit: ${where} — the path "${rel}" of ${key} leaves the kit; a manifest only designates its own files.`,
+      );
+    manifest[key] = rel;
+  }
+
+  return { manifest, diagnostics: diags };
+}
+
+/**
+ * Reads and validates the kit installed (or unpacked) in `kitDir`.
+ *
+ * To the manifest is added what only the disk can tell: the effective paths of
+ * `theme.json` and of `layouts/`, and the absence of both — a kit that brings
+ * neither design tokens nor layouts brings nothing, and reporting that at
+ * install time is better than discovering it at compile time.
+ *
+ * The directory name does NOT have to equal `manifest.name` here: an archive
+ * unpacks wherever the caller wants. It is `kit install` that installs under
+ * `manifest.name`, and it alone.
+ *
+ * @returns {{ manifest: object|null, dir: string, themeFile: string|null,
+ *             layoutsDir: string|null,
+ *             diagnostics: Array<{severity, code, message, suggestion?}> }}
+ */
+export function readKit(kitDir) {
+  const dir = path.resolve(kitDir);
+  const bare = { manifest: null, dir, themeFile: null, layoutsDir: null };
+  const file = path.join(dir, KIT_MANIFEST);
+
+  if (!isDir(dir))
+    return {
+      ...bare,
+      diagnostics: [
+        {
+          severity: 'error',
+          code: 'KIT_NOT_FOUND',
+          message: `Kit: ${dir} is not a directory.`,
+        },
+      ],
+    };
+
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return {
+      ...bare,
+      diagnostics: [
+        {
+          severity: 'error',
+          code: 'KIT_NOT_FOUND',
+          message: `Kit: ${KIT_MANIFEST} not found in ${dir} — a kit must carry its manifest at its root.`,
+        },
+      ],
+    };
+  }
+
+  let json;
+  try {
+    json = JSON.parse(raw);
+  } catch (e) {
+    return {
+      ...bare,
+      diagnostics: [
+        {
+          severity: 'error',
+          code: 'KIT_INVALID',
+          message: `Kit: ${file} — invalid JSON (${e?.message ?? e}).`,
+        },
+      ],
+    };
+  }
+
+  const { manifest, diagnostics } = parseKitManifest(json, { where: file });
+  if (!manifest) return { ...bare, diagnostics };
+
+  // insideKit can no longer return null (parseKitManifest has already refused
+  // escaping paths), EXCEPT through a symbolic link — which only the disk
+  // reveals.
+  const themeAbs = insideKit(dir, manifest.theme);
+  const layoutsAbs = insideKit(dir, manifest.layouts);
+  if (manifest.theme !== DEFAULT_THEME && !themeAbs)
+    diagnostics.push({
+      severity: 'error',
+      code: 'KIT_INVALID',
+      message: `Kit: theme "${manifest.theme}" leaves the kit (symbolic link) — kit skipped.`,
+    });
+  if (manifest.layouts !== DEFAULT_LAYOUTS && !layoutsAbs)
+    diagnostics.push({
+      severity: 'error',
+      code: 'KIT_INVALID',
+      message: `Kit: layouts "${manifest.layouts}" leaves the kit (symbolic link) — kit skipped.`,
+    });
+  if (diagnostics.some((d) => d.severity === 'error')) return { ...bare, diagnostics };
+
+  const themeFile = themeAbs && isFile(themeAbs) ? themeAbs : null;
+  const layoutsDir = layoutsAbs && isDir(layoutsAbs) ? layoutsAbs : null;
+
+  // a theme that is DECLARED but absent is an error in the kit; the default
+  // being absent is only the absence of design tokens, legitimate for a kit of
+  // layouts alone
+  if (!themeFile && manifest.theme !== DEFAULT_THEME)
+    diagnostics.push({
+      severity: 'error',
+      code: 'KIT_INVALID',
+      message: `Kit "${manifest.name}": theme "${manifest.theme}" declared but not found.`,
+    });
+  else if (!themeFile && !layoutsDir)
+    diagnostics.push({
+      severity: 'error',
+      code: 'KIT_INVALID',
+      message: `Kit "${manifest.name}": neither ${DEFAULT_THEME} nor ${DEFAULT_LAYOUTS}/ — a kit must bring design tokens, layouts, or both.`,
+    });
+
+  if (diagnostics.some((d) => d.severity === 'error')) return { ...bare, diagnostics };
+  return { manifest, dir, themeFile, layoutsDir, diagnostics };
+}