@rohal12/spindle 0.52.9 → 0.54.0

package/src/markup/validate.ts

@@ -0,0 +1,219 @@
+/**
+ * Markup validation: parse every passage when the story starts and report
+ * malformed markup and unknown macros with the passage, line and column
+ * they are at, instead of failing when the passage renders. Tooling runs it
+ * too (see src/tooling.ts).
+ */
+import { lineColumn, MarkupError, parseMarkup, tokenizeMarkup } from './parse';
+import type { Token } from './tokens';
+import { isCodeAttribute } from './code-attributes';
+import { parseWidgetDef } from '../widgets/widget-def';
+
+/** A passage to validate. */
+export interface MarkupPassage {
+  name: string;
+  content: string;
+  tags?: string[];
+  /**
+   * Passage attributes; `data-source-file` and `data-source-line` (the
+   * line of its `::` header) place errors in the source file.
+   */
+  metadata?: Record<string, string>;
+}
+
+/** An error in a passage's markup. */
+export interface MarkupDiagnostic {
+  passage: string;
+  /** 1-based line within the passage's content. */
+  line: number;
+  /** 1-based column (UTF-16 code units). */
+  column: number;
+  message: string;
+  /** The source file and line, when the passage says where it came from. */
+  file?: string;
+  fileLine?: number;
+}
+
+export interface MarkupValidationOptions {
+  /**
+   * Whether a macro of this name exists. Widgets that passages define with
+   * `{widget}` and branch macros (`{else}`, `{case}`, …) always do.
+   */
+  isKnownMacro(name: string): boolean;
+  /** Names to suggest for a misspelt macro. */
+  macroNames?: Iterable<string>;
+  /** Whether a macro takes a body (default: the registered block macros). */
+  isBlockMacro?(name: string): boolean;
+  /**
+   * Report on only the passages for which this holds (default: all). The
+   * others are still read for the widgets they define.
+   */
+  only?(passage: MarkupPassage): boolean;
+}
+
+/** Passages that hold no markup. */
+const NOT_MARKUP = new Set(['StoryVariables', 'StoryTransients']);
+const NOT_MARKUP_TAGS = ['script', 'stylesheet'];
+
+/** Branch macros, which their parent macro renders. */
+const BRANCH_MACROS = new Set(['elseif', 'else', 'case', 'default', 'next']);
+
+/** A diagnostic as one line of text. */
+export function formatDiagnostic(d: MarkupDiagnostic): string {
+  const source = d.file
+    ? ` (${d.file}${d.fileLine ? `:${d.fileLine}` : ''})`
+    : '';
+  return `Passage "${d.passage}", line ${d.line}, column ${d.column}${source}: ${d.message}`;
+}
+
+/** Edit distance, for "did you mean" suggestions. */
+function distance(a: string, b: string): number {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(
+        prev[j]! + 1,
+        row[j - 1]! + 1,
+        prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    prev = row;
+  }
+  return prev[b.length]!;
+}
+
+/** " Did you mean {name}?" for the closest known name, if one is close. */
+function suggestion(name: string, names: readonly string[]): string {
+  const lower = name.toLowerCase();
+  let best = '';
+  let bestDistance = Math.max(2, Math.floor(lower.length / 3)) + 1;
+  for (const candidate of names) {
+    const d = distance(lower, candidate.toLowerCase());
+    if (d < bestDistance) {
+      best = candidate;
+      bestDistance = d;
+    }
+  }
+  return best ? ` Did you mean {${best}}?` : '';
+}
+
+/** The name of the widget a `{widget}` with these arguments defines. */
+function widgetName(rawArgs: string): string | undefined {
+  try {
+    return parseWidgetDef(rawArgs).name.toLowerCase() || undefined;
+  } catch {
+    return undefined; // the {widget} macro reports it when it renders
+  }
+}
+
+/** Validate the markup of every passage. */
+export function validateMarkup(
+  passages: Iterable<MarkupPassage>,
+  options: MarkupValidationOptions,
+): MarkupDiagnostic[] {
+  const diagnostics: MarkupDiagnostic[] = [];
+  const hooks = options.isBlockMacro
+    ? { isBlock: options.isBlockMacro }
+    : undefined;
+  const report = (passage: MarkupPassage, offset: number, message: string) => {
+    const { line, column } = lineColumn(passage.content, offset);
+    const d: MarkupDiagnostic = {
+      passage: passage.name,
+      line,
+      column,
+      message,
+    };
+    const file = passage.metadata?.['data-source-file'];
+    if (file) {
+      d.file = file;
+      const header = Number(passage.metadata?.['data-source-line']);
+      if (header) d.fileLine = header + line;
+    }
+    diagnostics.push(d);
+  };
+
+  // Parse every passage first: the widgets they define are known macros.
+  const parsed: [MarkupPassage, Token[]][] = [];
+  const widgets = new Set<string>();
+  for (const passage of passages) {
+    if (NOT_MARKUP.has(passage.name)) continue;
+    if (passage.tags?.some((tag) => NOT_MARKUP_TAGS.includes(tag))) continue;
+    const reported = !options.only || options.only(passage);
+    try {
+      // The tokens first: they don't depend on which macros take a body
+      const tokens = tokenizeMarkup(passage.content);
+      for (const token of tokens) {
+        if (token.type !== 'macro' || token.isClose) continue;
+        if (token.name.toLowerCase() !== 'widget') continue;
+        const name = widgetName(token.rawArgs);
+        if (name) widgets.add(name);
+      }
+      if (!reported) continue;
+      parseMarkup(passage.content, { hooks });
+      parsed.push([passage, tokens]);
+    } catch (err) {
+      if (!(err instanceof MarkupError)) throw err;
+      if (reported) {
+        report(passage, err.offset, err.reason);
+      }
+    }
+  }
+  const names = [...(options.macroNames ?? []), ...widgets];
+
+  /** Report the unknown macros among `tokens`, which start at `base`. */
+  const checkMacros = (
+    passage: MarkupPassage,
+    tokens: Token[],
+    base: number,
+    where: string,
+  ) => {
+    for (const token of tokens) {
+      if (token.type !== 'macro' || token.isClose) continue;
+      const lower = token.name.toLowerCase();
+      if (
+        BRANCH_MACROS.has(lower) ||
+        widgets.has(lower) ||
+        options.isKnownMacro(lower)
+      ) {
+        continue;
+      }
+      report(
+        passage,
+        base + token.start,
+        `${where}Unknown macro {${token.name}}.${suggestion(token.name, names)}`,
+      );
+    }
+  };
+
+  for (const [passage, tokens] of parsed) {
+    checkMacros(passage, tokens, 0, '');
+    for (const token of tokens) {
+      if (token.type !== 'html') continue;
+      for (const [attr, value] of Object.entries(token.attributes)) {
+        if (isCodeAttribute(attr) || !value.includes('{')) continue;
+        // The value is the source text between its quotes
+        const found = passage.content.indexOf(value, token.start);
+        const at = found === -1 ? token.start : found;
+        const where = `In the ${attr} attribute of <${token.tag}>: `;
+        try {
+          parseMarkup(value, { text: true, hooks });
+          checkMacros(
+            passage,
+            tokenizeMarkup(value, { text: true }),
+            at,
+            where,
+          );
+        } catch (err) {
+          if (!(err instanceof MarkupError)) throw err;
+          report(
+            passage,
+            found === -1 ? at : at + err.offset,
+            where + err.reason,
+          );
+        }
+      }
+    }
+  }
+  return diagnostics;
+}

package/src/parser.ts

@@ -1,4 +1,4 @@
-import { tokenize } from './markup/tokenizer';
+import { MarkupError, tokenizeMarkup } from './markup/parse';
 import { isCodeAttribute, splitSigilTemplate } from './markup/code-attributes';
 
 export interface Passage {
@@ -88,7 +88,7 @@ function elementMarkup(el: Element): string {
 }
 
 /**
- * An attribute value quoted so that the passage tokenizer reads it back:
+ * An attribute value quoted so that the passage parser reads it back:
  * in double quotes, else single ones, else with the double quotes in its
  * text written as `"`, which rendering decodes. Quotes inside markup in
  * the value (`{print "a"}`) are code, and don't end it.
@@ -97,7 +97,14 @@ function quoteAttribute(name: string, value: string): string {
   const code = isCodeAttribute(name);
   const probe = code ? 'on' : 'a';
   const readsBack = (quoted: string) => {
-    const tokens = tokenize(`<i ${probe}=${quoted}>`);
+    let tokens;
+    try {
+      tokens = tokenizeMarkup(`<i ${probe}=${quoted}>`);
+    } catch (err) {
+      // Malformed markup in the value, such as an unclosed quote
+      if (err instanceof MarkupError) return false;
+      throw err;
+    }
     const tag = tokens[0];
     return (
       tokens.length === 1 &&
@@ -129,7 +136,15 @@ function escapeTextQuotes(value: string, code: boolean): string {
       )
       .join('');
   }
-  return tokenize(value, { text: true })
+  let tokens;
+  try {
+    tokens = tokenizeMarkup(value, { text: true });
+  } catch (err) {
+    // Malformed markup: validation reports it when the story starts
+    if (err instanceof MarkupError) return escape(value);
+    throw err;
+  }
+  return tokens
     .map((token) => {
       const source = value.slice(token.start, token.end);
       return token.type === 'text' ? escape(source) : source;

package/src/runtime-errors.ts

@@ -0,0 +1,65 @@
+// Runtime errors shown to the player on the page (see RuntimeErrors), for
+// errors that would otherwise only reach the browser console.
+
+import { errorMessage } from './utils/error-message';
+
+/** A runtime error shown on the page until the player dismisses it. */
+export interface RuntimeError {
+  /** Identifies the entry, for dismissing it. */
+  id: number;
+  /** What failed, for the player (e.g. "Could not save the game…"). */
+  context: string;
+  /** The error message, without the "spindle: " prefix. */
+  message: string;
+  /** How often the same error happened since it was shown. */
+  count: number;
+}
+
+let errors: readonly RuntimeError[] = [];
+let nextId = 1;
+const listeners = new Set<() => void>();
+
+function update(next: readonly RuntimeError[]): void {
+  errors = next;
+  for (const listener of listeners) listener();
+}
+
+/**
+ * Show `error` on the page, after `context` (what failed). The same error
+ * again, while it is shown, counts up instead of adding an entry. Logging
+ * it to the console is up to the caller.
+ */
+export function showRuntimeError(context: string, error: unknown): void {
+  const message = errorMessage(error).replace(/^spindle: /, '');
+  const same = errors.find(
+    (e) => e.context === context && e.message === message,
+  );
+  update(
+    same
+      ? errors.map((e) => (e === same ? { ...e, count: e.count + 1 } : e))
+      : [...errors, { id: nextId++, context, message, count: 1 }],
+  );
+}
+
+/** Remove the shown error `id`. */
+export function dismissRuntimeError(id: number): void {
+  update(errors.filter((e) => e.id !== id));
+}
+
+/** Remove every shown error. */
+export function clearRuntimeErrors(): void {
+  if (errors.length) update([]);
+}
+
+/** The errors shown now, oldest first. */
+export function getRuntimeErrors(): readonly RuntimeError[] {
+  return errors;
+}
+
+/** Call `listener` whenever the shown errors change; returns unsubscribe. */
+export function subscribeRuntimeErrors(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}

package/src/saves/format.ts

@@ -0,0 +1,199 @@
+// The stored form of a save payload: what saves, exports and the session
+// hold, and the version of that form.
+
+import { deserialize, serialize } from '../class-registry';
+import { createCounts } from '../utils/namespace';
+import type { SavePayload } from './types';
+
+/**
+ * The version of the save format this build writes. Saves, exports and the
+ * session carry it. Bump it when the stored form changes, and add a
+ * migration from the previous version to MIGRATIONS.
+ */
+export const SAVE_FORMAT_VERSION = 1;
+
+/**
+ * A payload as stored: `data` is the payload serialized in one piece (see
+ * serialize() in class-registry.ts), so values the history moments share
+ * are stored once, and cycles survive.
+ */
+export interface EncodedPayload {
+  formatVersion: number;
+  data: string;
+}
+
+/** A save, export or session from a version of Spindle this one cannot read. */
+export class IncompatibleSaveError extends Error {
+  constructor() {
+    super('This save was made by an incompatible version of Spindle');
+    this.name = 'IncompatibleSaveError';
+  }
+}
+
+/**
+ * Migrations of the stored data: MIGRATIONS[v] turns the `data` of format
+ * version v into that of version v + 1. Version 1 is the first versioned
+ * format; data from before it has no version and is refused.
+ */
+const MIGRATIONS: Readonly<Record<number, (data: string) => string>> = {};
+
+/** Throw an IncompatibleSaveError unless this build reads format `version`. */
+export function checkFormatVersion(
+  version: unknown,
+): asserts version is number {
+  if (
+    typeof version !== 'number' ||
+    !Number.isInteger(version) ||
+    version < 1 ||
+    version > SAVE_FORMAT_VERSION
+  ) {
+    throw new IncompatibleSaveError();
+  }
+}
+
+/** Bring `data` of format `version` up to SAVE_FORMAT_VERSION. */
+export function migrate(version: number, data: string): string {
+  checkFormatVersion(version);
+  let current = data;
+  for (let v = version; v < SAVE_FORMAT_VERSION; v++) {
+    const step = MIGRATIONS[v];
+    if (!step) throw new IncompatibleSaveError();
+    current = step(current);
+  }
+  return current;
+}
+
+/**
+ * The passage counters as a Map: a passage may be named "__proto__", which
+ * serialize() refuses as an object key (as every story-state key).
+ */
+const countsToMap = (counts: Record<string, number> | undefined) =>
+  counts && new Map(Object.entries(counts));
+
+/**
+ * The error of serialize() with its path told as a story variable:
+ * `(at .variables.inv[0])` becomes `(at $inv[0])`, and a value only an
+ * earlier history moment holds `(at $inv[0] in history moment 3)`.
+ */
+function variablePathError(err: unknown): unknown {
+  if (!(err instanceof TypeError)) return err;
+  const message = err.message
+    .replace(/\(at \.variables(?=[.[]|\))/, '(at $')
+    .replace(
+      /\(at \.history\[(\d+)\]\.variables(.*)\)$/,
+      (_, i: string, path: string) => `(at $${path} in history moment ${i})`,
+    )
+    .replace(/\(at \$\.?/, '(at $');
+  return message === err.message ? err : new TypeError(message);
+}
+
+/**
+ * The stored form of `payload`. Throws, naming the variable, when the
+ * payload holds a value a save cannot (see serialize()).
+ */
+export function encodePayload(payload: SavePayload): EncodedPayload {
+  try {
+    return {
+      formatVersion: SAVE_FORMAT_VERSION,
+      data: serialize({
+        ...payload,
+        visitCounts: countsToMap(payload.visitCounts),
+        renderCounts: countsToMap(payload.renderCounts),
+      }),
+    };
+  } catch (err) {
+    throw variablePathError(err);
+  }
+}
+
+/** Thrown for stored data that is not a payload this format can hold. */
+const invalid = () => new Error('Invalid save data');
+
+/** A plain object or one without a prototype (a variable namespace). */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const proto = Object.getPrototypeOf(value) as object | null;
+  return proto === Object.prototype || proto === null;
+}
+
+/** Absent, null, or a `{ seed, pull }` PRNG snapshot. */
+function isOptionalPRNGSnapshot(value: unknown): boolean {
+  if (value == null) return true;
+  return (
+    isRecord(value) &&
+    typeof value.seed === 'string' &&
+    typeof value.pull === 'number' &&
+    Number.isInteger(value.pull) &&
+    value.pull >= 0
+  );
+}
+
+const isMoment = (value: unknown): boolean =>
+  isRecord(value) &&
+  typeof value.passage === 'string' &&
+  isRecord(value.variables) &&
+  typeof value.timestamp === 'number' &&
+  isOptionalPRNGSnapshot(value.prng);
+
+const isCountsMap = (value: unknown): boolean =>
+  value === undefined ||
+  (value instanceof Map &&
+    [...value.keys()].every((k) => typeof k === 'string'));
+
+/**
+ * Whether a deserialized payload is well formed: every history moment is,
+ * and `historyIndex` is an integer that points at a moment of the payload's
+ * passage.
+ */
+function isPayload(value: unknown): value is Record<string, unknown> {
+  if (!isRecord(value)) return false;
+  if (typeof value.passage !== 'string' || !isRecord(value.variables)) {
+    return false;
+  }
+  const { history, historyIndex } = value;
+  // Array.from: every() skips the holes of a sparse array
+  if (!Array.isArray(history) || history.length === 0) return false;
+  if (!Array.from(history).every(isMoment)) return false;
+  if (
+    typeof historyIndex !== 'number' ||
+    !Number.isInteger(historyIndex) ||
+    historyIndex < 0 ||
+    historyIndex >= history.length ||
+    (history[historyIndex] as { passage: string }).passage !== value.passage
+  ) {
+    return false;
+  }
+  return (
+    isCountsMap(value.visitCounts) &&
+    isCountsMap(value.renderCounts) &&
+    isOptionalPRNGSnapshot(value.prng)
+  );
+}
+
+const mapToCounts = (counts: unknown) =>
+  counts instanceof Map
+    ? createCounts(Object.fromEntries(counts as Map<string, unknown>))
+    : undefined;
+
+/**
+ * The live payload of a stored one: class instances and built-ins
+ * restored. Throws an IncompatibleSaveError when `encoded` has no format
+ * version or one this build cannot read (saves from before versioning, or
+ * from a newer Spindle), and an error when its data is malformed.
+ */
+export function decodePayload(encoded: unknown): SavePayload {
+  if (typeof encoded !== 'object' || encoded === null) throw invalid();
+  const { formatVersion, data } = encoded as Record<string, unknown>;
+  checkFormatVersion(formatVersion);
+  if (typeof data !== 'string') throw invalid();
+  const body = deserialize(migrate(formatVersion, data));
+  if (!isPayload(body)) throw invalid();
+  const payload = {
+    ...body,
+    visitCounts: mapToCounts(body.visitCounts),
+    renderCounts: mapToCounts(body.renderCounts),
+  } as SavePayload;
+  if (payload.visitCounts === undefined) delete payload.visitCounts;
+  if (payload.renderCounts === undefined) delete payload.renderCounts;
+  return payload;
+}