@rohal12/spindle 0.54.0 → 0.56.0

package/src/markup/validate.ts

@@ -1,13 +1,16 @@
 /**
  * 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).
+ * malformed markup, unknown macros, syntax errors in the code it runs and
+ * passage names that name no passage (see code-check.ts) 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';
+import { codeAndText, parseOrError, withParseCache } from '../code-check';
+import { CodeSyntaxError } from '../js-lexer';
+import type { ParameterDef } from '../registry';
 
 /** A passage to validate. */
 export interface MarkupPassage {
@@ -49,6 +52,18 @@ export interface MarkupValidationOptions {
    * others are still read for the widgets they define.
    */
   only?(passage: MarkupPassage): boolean;
+  /**
+   * Whether passage names written out must name one of the passages
+   * (default: true). Off when only part of a story is validated.
+   */
+  checkPassageNames?: boolean;
+  /**
+   * The declared parameters of a macro, whose `expression` and `statements`
+   * arguments are checked as code and whose `text` and `string` arguments
+   * as markup (see code-check.ts). Without them only the code of `{$…}`,
+   * `{do}`, branch conditions and attributes is checked.
+   */
+  parametersOf?(name: string): readonly ParameterDef[] | undefined;
 }
 
 /** Passages that hold no markup. */
@@ -83,8 +98,15 @@ function distance(a: string, b: string): number {
   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 {
+/**
+ * " Did you mean …?" with the known name closest to `name`, written by
+ * `quote`, if one is close.
+ */
+function didYouMean(
+  name: string,
+  names: Iterable<string>,
+  quote: (name: string) => string,
+): string {
   const lower = name.toLowerCase();
   let best = '';
   let bestDistance = Math.max(2, Math.floor(lower.length / 3)) + 1;
@@ -95,9 +117,16 @@ function suggestion(name: string, names: readonly string[]): string {
       bestDistance = d;
     }
   }
-  return best ? ` Did you mean {${best}}?` : '';
+  return best ? ` Did you mean ${quote(best)}?` : '';
 }
 
+/** What a passage argument may be, after an error in one. */
+const PASSAGE_ARGUMENT_HINT =
+  ' (a passage name is a quoted string or an expression)';
+
+/** A passage argument that is one bare word (`{goto Kitchen}`). */
+const BARE_WORD_RE = /^[A-Za-z][\w$]*$/;
+
 /** The name of the widget a `{widget}` with these arguments defines. */
 function widgetName(rawArgs: string): string | undefined {
   try {
@@ -107,7 +136,10 @@ function widgetName(rawArgs: string): string | undefined {
   }
 }
 
-/** Validate the markup of every passage. */
+/**
+ * Validate the markup of every passage. Passage names written out (links,
+ * quoted `passage` arguments) must name one of `passages`.
+ */
 export function validateMarkup(
   passages: Iterable<MarkupPassage>,
   options: MarkupValidationOptions,
@@ -136,7 +168,9 @@ export function validateMarkup(
   // Parse every passage first: the widgets they define are known macros.
   const parsed: [MarkupPassage, Token[]][] = [];
   const widgets = new Set<string>();
+  const passageNames = new Set<string>();
   for (const passage of passages) {
+    passageNames.add(passage.name);
     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);
@@ -181,39 +215,75 @@ export function validateMarkup(
       report(
         passage,
         base + token.start,
-        `${where}Unknown macro {${token.name}}.${suggestion(token.name, names)}`,
+        `${where}Unknown macro {${token.name}}.${didYouMean(token.name, names, (n) => `{${n}}`)}`,
       );
     }
   };
 
-  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(
+  const parametersOf = options.parametersOf ?? (() => undefined);
+
+  /**
+   * Check `tokens`, the tokens of `src`, which starts at `base` in the
+   * passage: their macros, the code in them and the markup in their text.
+   */
+  const checkTokens = (
+    passage: MarkupPassage,
+    src: string,
+    tokens: Token[],
+    base: number,
+    where: string,
+  ) => {
+    checkMacros(passage, tokens, base, where);
+    for (const piece of codeAndText(src, tokens, parametersOf)) {
+      const at = base + piece.offset;
+      if (piece.kind === 'passage') {
+        if (
+          options.checkPassageNames !== false &&
+          !passageNames.has(piece.name)
+        ) {
+          const hint = didYouMean(piece.name, passageNames, JSON.stringify);
+          report(
             passage,
-            tokenizeMarkup(value, { text: true }),
             at,
-            where,
+            `${where}No passage named ${JSON.stringify(piece.name)} in ${piece.label}.${hint}`,
+          );
+        }
+        continue;
+      }
+      if (piece.kind === 'code') {
+        const result = parseOrError(piece.code, piece.goal);
+        const code = piece.code.trim();
+        if (result instanceof CodeSyntaxError) {
+          const reason = result.reasonIn(passage.content, at);
+          report(
+            passage,
+            at + result.pos,
+            `${where}${reason} in ${piece.label}` +
+              (piece.passage ? PASSAGE_ARGUMENT_HINT : ''),
           );
-        } catch (err) {
-          if (!(err instanceof MarkupError)) throw err;
+        } else if (piece.passage && BARE_WORD_RE.test(code)) {
           report(
             passage,
-            found === -1 ? at : at + err.offset,
-            where + err.reason,
+            at,
+            `${where}Unquoted passage name in ${piece.label}: write ${JSON.stringify(code)}${PASSAGE_ARGUMENT_HINT}`,
           );
         }
+        continue;
+      }
+      if (!piece.text.includes('{')) continue;
+      try {
+        parseMarkup(piece.text, { text: true, hooks });
+        const inner = tokenizeMarkup(piece.text, { text: true });
+        checkTokens(passage, piece.text, inner, at, piece.where);
+      } catch (err) {
+        if (!(err instanceof MarkupError)) throw err;
+        report(passage, at + err.offset, piece.where + err.reason);
       }
     }
+  };
+
+  for (const [passage, tokens] of parsed) {
+    withParseCache(() => checkTokens(passage, passage.content, tokens, 0, ''));
   }
   return diagnostics;
 }

package/src/registry.ts

@@ -69,9 +69,12 @@ export function isSubMacro(name: string): boolean {
 }
 
 /**
- * How a macro argument is read (see components/macros/macro-args.ts).
+ * How a macro argument is read (see components/macros/macro-args.ts). Every
+ * declared parameter names one: there is no default.
  * Quoted strings accept `\"`, `\'` and `\\` escapes.
- * - `expression`: code, as written (the default).
+ * - `expression`: code, as written.
+ * - `statements`: code run as statements (`{set}`), as written.
+ * - `passage`: a passage name: a quoted string or an expression, as written.
  * - `variable`: a variable reference such as `$name` or `"$name"`, as written.
  * - `string`: one quoted string; anything else leaves the argument unset.
  * - `text`: one quoted string, or text with any loose quotes stripped.
@@ -84,27 +87,59 @@ export function isSubMacro(name: string): boolean {
  * - `options`: keywords, the names of its `parameters`, each followed by a
  *   quoted string or a number unless it is a flag.
  */
-export type ParameterType =
-  | 'expression'
-  | 'variable'
-  | 'string'
-  | 'text'
-  | 'names'
-  | 'delay'
-  | 'number'
-  | 'flag'
-  | 'separator'
-  | 'options';
+export const PARAMETER_TYPES = [
+  'expression',
+  'statements',
+  'passage',
+  'variable',
+  'string',
+  'text',
+  'names',
+  'delay',
+  'number',
+  'flag',
+  'separator',
+  'options',
+] as const;
+
+export type ParameterType = (typeof PARAMETER_TYPES)[number];
 
 export interface ParameterDef {
   name: string;
   required?: boolean;
   description?: string;
-  type?: ParameterType;
+  type: ParameterType;
   /** The options of an `options` parameter. */
   parameters?: readonly ParameterDef[];
 }
 
+/**
+ * Throw if a parameter `macro` declares (or an option of one) has no type,
+ * or one that isn't a ParameterType: arguments are read by their type, and
+ * there is no default.
+ */
+export function checkParameterTypes(
+  macro: string,
+  parameters: readonly ParameterDef[],
+): void {
+  for (const param of parameters) {
+    const type: unknown = param.type;
+    if (!PARAMETER_TYPES.includes(type as ParameterType)) {
+      const problem =
+        type === undefined
+          ? 'has no type'
+          : `has the unknown type ${JSON.stringify(type)}`;
+      throw new Error(
+        `spindle: The parameter "${param.name}" of the macro {${macro}} ${problem}. ` +
+          `Give it one of the types ${PARAMETER_TYPES.join(', ')} ` +
+          '(see docs/custom-macros.md#parameter-types), ' +
+          'or declare no parameters and read props.rawArgs.',
+      );
+    }
+    if (param.parameters) checkParameterTypes(macro, param.parameters);
+  }
+}
+
 type ArgValue<T, D> = T extends 'flag' | 'separator'
   ? boolean
   : T extends 'names'

package/src/runtime-errors.ts

@@ -41,6 +41,16 @@ export function showRuntimeError(context: string, error: unknown): void {
   );
 }
 
+/**
+ * The error for `name`, a passage name that names no passage, used in the
+ * passage `from`.
+ */
+export function noPassageError(name: string, from: string): Error {
+  return new Error(
+    `No passage named ${JSON.stringify(name)} (in passage ${JSON.stringify(from)})`,
+  );
+}
+
 /** Remove the shown error `id`. */
 export function dismissRuntimeError(id: number): void {
   update(errors.filter((e) => e.id !== id));

package/src/store.ts

@@ -45,7 +45,7 @@ import {
 
 import { deepClone, mergeKeys, mergesWith, shareEqual } from './structural';
 import { shallowCopy } from './utils/object-path';
-import { showRuntimeError } from './runtime-errors';
+import { noPassageError, showRuntimeError } from './runtime-errors';
 import {
   snapshotPRNG,
   restorePRNG,
@@ -278,6 +278,9 @@ function persistSession(get: () => StoryState): void {
 const SESSION_ERROR_CONTEXT =
   'The game could not be saved for a page reload; a reload goes back to the last passage it could save:';
 
+/** What the page shows before an error naming a missing passage. */
+const NAVIGATION_ERROR_CONTEXT = 'The story could not go to another passage:';
+
 /**
  * Write the session, then run `after` (the rest of the operation: its
  * events and queued navigations), then throw the session's error if writing
@@ -1145,7 +1148,10 @@ export const useStoryStore = create<StoryState>()(
       }
 
       if (!storyData.passages.has(passageName)) {
-        console.error(`spindle: Passage "${passageName}" not found.`);
+        // Shown on the page too: code (Story.goto()) can name any passage
+        const error = noPassageError(passageName, get().currentPassage);
+        console.error(`spindle: ${error.message}`);
+        showRuntimeError(NAVIGATION_ERROR_CONTEXT, error);
         return;
       }
 

package/src/story-variables.ts

@@ -3,7 +3,13 @@ import type { Token } from './markup/tokens';
 import { MarkupError, tokenizeMarkup } from './markup/parse';
 import { isCodeAttribute, splitSigilTemplate } from './markup/code-attributes';
 import { errorMessage } from './utils/error-message';
-import { lexJs, scanStringLiteral, type JsGoal } from './js-lexer';
+import {
+  CodeSyntaxError,
+  lexJs,
+  scanStringLiteral,
+  type JsGoal,
+} from './js-lexer';
+import { parseOrError, withParseCache } from './code-check';
 import { createNamespace, variableNameError } from './utils/namespace';
 
 /**
@@ -245,6 +251,25 @@ function scanCode(
   code: string,
   onRef: RefCallback,
   goal: JsGoal = 'expression',
+): void {
+  const parsed = parseOrError(code, goal);
+  if (parsed instanceof CodeSyntaxError) {
+    scanCodeLeniently(code, onRef, goal);
+    return;
+  }
+  for (const ref of parsed.refs) {
+    if (ref.sigil !== '$') continue;
+    VAR_PATH_RE.lastIndex = ref.start;
+    onRef(VAR_PATH_RE.exec(code)![1]!);
+  }
+  for (const text of parsed.strings) scanInterpolations(text, onRef);
+}
+
+/** `scanCode` for code acorn can't parse: lexed leniently. */
+function scanCodeLeniently(
+  code: string,
+  onRef: RefCallback,
+  goal: JsGoal,
 ): void {
   /** Open template literals: their text so far, null in an interpolation. */
   const templates: { nesting: number; text: string | null }[] = [];
@@ -295,7 +320,9 @@ function collectPassageRefs(
   storeVarMacros: ReadonlySet<string>,
   onRef: RefCallback,
 ): void {
-  collectTokenRefs(content, tokensOf(content, false), storeVarMacros, onRef);
+  withParseCache(() =>
+    collectTokenRefs(content, tokensOf(content, false), storeVarMacros, onRef),
+  );
 }
 
 /** Report the `$var` references in the tokens of `content`. */
@@ -345,8 +372,9 @@ function collectTokenRefs(
 }
 
 /**
- * Scan all passages for $var references, check against schema.
- * Returns list of error messages (empty = valid).
+ * Check the `$var` references of all passages against the schema, at story
+ * start. Returns the error messages (empty = valid). (The syntax of their
+ * code is checked with their markup: see markup/validate.ts.)
  *
  * `storeVarMacros` lists the input macros whose first argument names a bound
  * variable; it defaults to the built-in ones.
@@ -366,7 +394,6 @@ export function validatePassages(
     if (name === 'StoryVariables' || name === 'StoryTransients') continue;
 
     const forLocals = extractForLocals(passage.content);
-
     collectPassageRefs(passage.content, storeVarSet, (ref) => {
       const error = validateRef(ref, schema, forLocals);
       if (error) {

package/src/tooling.ts

@@ -11,40 +11,60 @@ import {
 } from './markup/validate';
 import { isBlockMacro } from './markup/ast';
 import { blockWidgetNames } from './widgets/widget-def';
+import type { ParameterDef } from './registry';
 
 export { parseStoryVariables } from './story-variables';
+export { checkParameterTypes } from './registry';
 export { formatDiagnostic } from './markup/validate';
 export type { MarkupDiagnostic, MarkupPassage } from './markup/validate';
 
 /** What tooling knows about a macro (see MacroMetadata). */
+/** Options for validating markup from tooling. */
+export interface ValidateMarkupOptions {
+  /**
+   * Whether passage names written out (links, quoted `passage` arguments)
+   * must name one of the passages given (default: true). Turn it off to
+   * validate only part of a story.
+   */
+  checkPassageNames?: boolean;
+}
+
 export interface ToolingMacro {
   name: string;
   block: boolean;
   subMacros: string[];
+  /** Its declared parameters: their types tell which arguments are code. */
+  parameters?: readonly ParameterDef[];
 }
 
 /**
  * Validate the markup of a story's passages as Spindle does when the story
  * starts, against the given macros (built-in and user-defined): malformed
- * markup and unknown macros, with their passage, line and column.
+ * markup, unknown macros and syntax errors in code, with their passage, line
+ * and column.
  */
 export function validateStoryMarkup(
   passages: Iterable<MarkupPassage>,
   macros: Iterable<ToolingMacro>,
+  options: ValidateMarkupOptions = {},
 ): MarkupDiagnostic[] {
   const list = [...passages];
   const known = new Set<string>();
+  const parameters = new Map<string, readonly ParameterDef[] | undefined>();
   const blocks = new Set(blockWidgetNames(list).map((n) => n.toLowerCase()));
   for (const macro of macros) {
     const name = macro.name.toLowerCase();
     known.add(name);
+    parameters.set(name, macro.parameters);
     for (const sub of macro.subMacros) known.add(sub.toLowerCase());
     if (macro.block) blocks.add(name);
   }
   return validateMarkup(list, {
     isKnownMacro: (name) => known.has(name),
     macroNames: known,
+    parametersOf: (name) => parameters.get(name),
     isBlockMacro: (name) =>
       blocks.has(name.toLowerCase()) || isBlockMacro(name),
+    checkPassageNames: options.checkPassageNames,
   });
 }

package/src/types-drift-check.ts

@@ -115,5 +115,5 @@ const _exampleMacro: PublishedMacroDefinition = {
 // metadata.
 declare const validateStoryMarkup: typeof SourceValidateStoryMarkup;
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _validateMarkup: typeof PublishedValidateMarkup = (passages) =>
-  validateStoryMarkup(passages, []);
+const _validateMarkup: typeof PublishedValidateMarkup = (passages, options) =>
+  validateStoryMarkup(passages, [], options);

package/src/widgets/widget-def.ts

@@ -8,7 +8,7 @@ import type { MacroArgs } from '../registry';
 /** A {widget} definition's name, then its `@` parameters. */
 export const WIDGET_PARAMETERS = [
   { name: 'name', type: 'text', required: true },
-  { name: 'parameters', type: 'expression' },
+  { name: 'parameters', type: 'text' },
 ] as const;
 
 export interface WidgetDef {

package/types/index.d.ts

@@ -242,7 +242,9 @@ export interface StorageQuota {
 /**
  * How a macro argument is read into `ctx.args`. Quoted strings accept `\"`,
  * `\'` and `\\` escapes.
- * - `expression`: code, as written (the default).
+ * - `expression`: code, as written.
+ * - `statements`: code run as statements (`{set}`), as written.
+ * - `passage`: a passage name: a quoted string or an expression, as written.
  * - `variable`: a variable reference such as `$name` or `"$name"`, as written.
  * - `string`: one quoted string; anything else leaves the argument unset.
  * - `text`: one quoted string, or text with any loose quotes stripped.
@@ -258,6 +260,8 @@ export interface StorageQuota {
  */
 export type ParameterType =
   | 'expression'
+  | 'statements'
+  | 'passage'
   | 'variable'
   | 'string'
   | 'text'
@@ -276,8 +280,8 @@ export interface ParameterDef {
   name: string;
   required?: boolean;
   description?: string;
-  /** How the argument is read (default `expression`). */
-  type?: ParameterType;
+  /** How the argument is read: required, there is no default. */
+  type: ParameterType;
   /** The options of an `options` parameter. */
   parameters?: readonly ParameterDef[];
 }

package/types/tooling.d.ts

@@ -1,7 +1,9 @@
 /**
  * How a macro argument is read into `ctx.args`. Quoted strings accept `\"`,
  * `\'` and `\\` escapes.
- * - `expression`: code, as written (the default).
+ * - `expression`: code, as written.
+ * - `statements`: code run as statements (`{set}`), as written.
+ * - `passage`: a passage name: a quoted string or an expression, as written.
  * - `variable`: a variable reference such as `$name` or `"$name"`, as written.
  * - `string`: one quoted string; anything else leaves the argument unset.
  * - `text`: one quoted string, or text with any loose quotes stripped.
@@ -16,6 +18,8 @@
  */
 export type ParameterType =
   | 'expression'
+  | 'statements'
+  | 'passage'
   | 'variable'
   | 'string'
   | 'text'
@@ -30,8 +34,8 @@ export interface ParameterDef {
   name: string;
   required?: boolean;
   description?: string;
-  /** How the argument is read (default `expression`). */
-  type?: ParameterType;
+  /** How the argument is read: required, there is no default. */
+  type: ParameterType;
   /** The options of an `options` parameter. */
   parameters?: readonly ParameterDef[];
 }
@@ -128,14 +132,29 @@ export interface MarkupDiagnostic {
 /**
  * Validate the markup of a story's passages as Spindle does when the story
  * starts: malformed markup (unclosed or mismatched macros, tags, links,
- * braces and attribute values) and unknown macros, checked against the
- * built-in macros, those registered with `defineMacro` and the widgets the
- * passages define. Spindle refuses to start a story with any of these.
+ * braces and attribute values), unknown macros and syntax errors in the
+ * code passages run (`{$…}` expressions, `{do}` bodies, conditions and the
+ * `expression`/`statements`/`passage` arguments of macros), checked against
+ * the built-in macros, those registered with `defineMacro` and the widgets
+ * the passages define, and passage names that name none of `passages`
+ * (links, quoted `passage` arguments, `{link}`, `{dialog}`, `{watch}`).
+ * Spindle refuses to start a story with any of these.
  */
 export declare function validateMarkup(
   passages: Iterable<MarkupPassage>,
+  options?: ValidateMarkupOptions,
 ): MarkupDiagnostic[];
 
+/** Options for {@link validateMarkup}. */
+export interface ValidateMarkupOptions {
+  /**
+   * Whether passage names written out (links, quoted `passage` arguments)
+   * must name one of `passages` (default: true). Turn it off to validate
+   * only part of a story.
+   */
+  checkPassageNames?: boolean;
+}
+
 /**
  * A diagnostic as one line of text, as Spindle shows it:
  * `Passage "Start", line 3, column 5 (story.twee:12): Unclosed {if}: …`.