@rohal12/spindle 0.56.0 → 0.58.0

package/dist/pkg/tooling.js

@@ -2,9 +2,36 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { checkParameterTypes, validateStoryMarkup } from './story-variables.js';
+import {
+  checkParameterTypes,
+  collectStoryPassageReferences,
+  validateStoryMarkup,
+} from './story-variables.js';
 
-export { parseStoryVariables, formatDiagnostic } from './story-variables.js';
+export {
+  parseStoryVariables,
+  formatDiagnostic,
+  findCodeEnd,
+  lexJs,
+  lexTemplate,
+  scanStringLiteral,
+  MarkupError,
+  parseSelectors,
+  tokenizeMarkup,
+  tokenizeMarkupTolerant,
+  transform,
+  passageTarget,
+  evaluatePassageName,
+  SIGIL_SCOPES,
+  isSigil,
+  endsWithOperator,
+  readQuoted,
+  splitArgs,
+  splitTopLevel,
+  stripLooseQuotes,
+  unescapeQuoted,
+  splitIncludeFlag,
+} from './story-variables.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -58,3 +85,13 @@ export function getMacroRegistry() {
 export function validateMarkup(passages, options) {
   return validateStoryMarkup(passages, metadata.values(), options);
 }
+
+/**
+ * The passages the markup of `source` names, with where each is written:
+ * `[[…]]` links and the passage of `{goto}`, `{include}`, `{link}`,
+ * `{watch}` and `{dialog}`, as the macros registered here declare them.
+ * Malformed tags are skipped, so half-typed markup reads.
+ */
+export function collectPassageReferences(source) {
+  return collectStoryPassageReferences(source, metadata.values());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/code-check.ts

@@ -29,8 +29,12 @@ import { isCodeAttribute, splitSigilTemplate } from './markup/code-attributes';
 import { CodeSyntaxError, parseCode, type JsGoal } from './js-lexer';
 import type { ParsedCode } from './js-lexer';
 import type { ParameterDef } from './registry';
-import { parseMacroArgs } from './components/macros/macro-args';
-import { readWholeQuoted } from './components/macros/arg-utils';
+import {
+  MacroArgumentError,
+  parseMacroArgs,
+  passageTarget,
+  type PassageTarget,
+} from './components/macros/macro-args';
 
 /** While a pass runs: the code it parsed so far, by goal and source. */
 let parses: Map<string, ParsedCode | CodeSyntaxError> | null = null;
@@ -77,6 +81,10 @@ export interface CodePiece {
   label: string;
   /** Whether it names a passage: a `passage` argument. */
   passage?: boolean;
+  /** Whether it is the code in a quoted string, as in `{watch}`. */
+  inString?: boolean;
+  /** The macro it is the argument of, for a `passage` argument. */
+  macro?: string;
 }
 
 /** A passage name written out in markup, at `offset` in it. */
@@ -86,6 +94,19 @@ export interface PassagePiece {
   offset: number;
   /** The markup it is in, for the error: `[[Go->Hall]]`. */
   label: string;
+  /** How much of the markup is the name, as written. */
+  length: number;
+  /** The macro it is the argument of; `link` for `[[…]]` links. */
+  macro: string;
+}
+
+/** Macro arguments that don't have their parameters' forms. */
+export interface ArgumentErrorPiece {
+  kind: 'argument-error';
+  message: string;
+  offset: number;
+  /** The markup it is in, for the error: `{link Go}`. */
+  label: string;
 }
 
 /** Text in markup that may hold markup of its own, at `offset` in it. */
@@ -101,20 +122,29 @@ export interface TextPiece {
 const CONDITION_MACROS = new Set(['if', 'elseif', 'case']);
 
 /** Code inside the quoted strings of a macro's arguments, by parameter. */
-const CODE_IN_STRINGS: Record<string, Record<string, JsGoal>> = {
-  watch: { condition: 'expression', run: 'statements' },
-};
+const CODE_IN_STRINGS: ReadonlyMap<string, Record<string, JsGoal>> = new Map([
+  ['watch', { condition: 'expression', run: 'statements' }],
+]);
 
 /** The `string` parameters of a macro that name a passage. */
-const PASSAGE_STRINGS: Record<string, readonly string[]> = {
-  link: ['passage'],
-  watch: ['goto', 'dialog'],
-};
+const PASSAGE_STRINGS: ReadonlyMap<string, readonly string[]> = new Map([
+  ['watch', ['goto', 'dialog']],
+]);
+
+/**
+ * The `text` and `string` parameters of a macro that the runtime keeps as
+ * written, not as markup: an option's value, the name of a watcher.
+ */
+const LITERAL_STRINGS: ReadonlyMap<string, readonly string[]> = new Map([
+  ['option', ['value']],
+  ['watch', ['name']],
+  ['unwatch', ['name']],
+]);
 
 /** Block macros whose body is the name of a passage. */
 const PASSAGE_BODIES = new Set(['dialog']);
 
-type Piece = CodePiece | TextPiece | PassagePiece;
+type Piece = CodePiece | TextPiece | PassagePiece | ArgumentErrorPiece;
 
 /** The goal of the code an argument of this type holds, if it is code. */
 function codeGoal(param: ParameterDef): JsGoal | undefined {
@@ -150,6 +180,8 @@ export function* codeAndText(
         kind: 'passage',
         name: token.target,
         offset: locate(src, token.target, token.start),
+        length: token.target.length,
+        macro: 'link',
         label: src.slice(token.start, token.end),
       };
     } else if (token.type === 'expression') {
@@ -215,6 +247,8 @@ export function* codeAndText(
             kind: 'passage',
             name: passage,
             offset: locate(src, passage, token.end),
+            length: passage.length,
+            macro: name,
             label: src.slice(token.start, token.end),
           };
         }
@@ -239,16 +273,25 @@ export function* codeAndText(
 }
 
 /** The code and text in the arguments `args` (at `offset`) of `macro`. */
-function* argPieces(
+export function* argPieces(
   args: string,
   offset: number,
   params: readonly ParameterDef[],
   macro: string,
   label: string,
 ): Generator<Piece> {
-  const values = parseMacroArgs(args, params) as Record<string, unknown>;
-  const inStrings = CODE_IN_STRINGS[macro.toLowerCase()] ?? {};
-  const passageStrings = PASSAGE_STRINGS[macro.toLowerCase()] ?? [];
+  let values: Record<string, unknown>;
+  try {
+    values = parseMacroArgs(args, params) as Record<string, unknown>;
+  } catch (error) {
+    if (!(error instanceof MacroArgumentError)) throw error;
+    yield { kind: 'argument-error', message: error.message, offset, label };
+    return;
+  }
+  const key = macro.toLowerCase();
+  const inStrings = CODE_IN_STRINGS.get(key) ?? {};
+  const passageStrings = PASSAGE_STRINGS.get(key) ?? [];
+  const literalStrings = LITERAL_STRINGS.get(key) ?? [];
   let cursor = 0;
   /** The pieces of the parameters `list`, with their values in `from`. */
   function* visit(
@@ -276,20 +319,36 @@ function* argPieces(
           goal,
           label,
         };
-        if (param.type === 'passage') piece.passage = true;
+        if (param.type === 'passage') {
+          piece.passage = true;
+          piece.macro = macro.toLowerCase();
+        }
+        if (!codeGoal(param)) piece.inString = true;
         yield piece;
       }
       // A passage written out: a quoted `passage` argument, or a string
-      const name =
+      const written = param.type === 'passage' ? value.trim() : value;
+      const target =
         param.type === 'passage'
-          ? readWholeQuoted(value.trim())
+          ? passageTarget(value)
           : passageStrings.includes(param.name)
-            ? value
+            ? ({ kind: 'name', name: value } as const)
             : null;
-      if (name !== null) {
-        yield { kind: 'passage', name, offset: offset + at, label };
+      if (target?.kind === 'name') {
+        yield {
+          kind: 'passage',
+          name: target.name,
+          offset: offset + at + value.indexOf(written),
+          length: written.length,
+          macro: macro.toLowerCase(),
+          label,
+        };
       }
-      if (!goal && (param.type === 'text' || param.type === 'string')) {
+      if (
+        !goal &&
+        (param.type === 'text' || param.type === 'string') &&
+        !literalStrings.includes(param.name)
+      ) {
         yield {
           kind: 'text',
           text: value,
@@ -312,3 +371,52 @@ function locate(text: string, part: string, from: number): number {
   const anywhere = text.indexOf(part);
   return anywhere >= 0 ? anywhere : from;
 }
+
+/** A passage a piece of markup names, and where. */
+export interface PassageReference {
+  /** The macro it is the argument of; `link` for `[[…]]` links. */
+  macro: string;
+  /** The name written out, or the expression whose value is the name. */
+  target: PassageTarget;
+  /** Where the name is written, as it is written (quotes included). */
+  start: number;
+  end: number;
+}
+
+/**
+ * The passages the markup `src` (with the `tokens` it tokenizes to) names:
+ * `[[…]]` links, the passage argument of `{goto}`, `{include}` and `{link}`
+ * (and of macros that declare one), the `goto` and `dialog` actions of
+ * `{watch}` and the body of `{dialog}`, in source order. A name written out
+ * is a literal; the others are expressions, which name a passage when they
+ * run.
+ */
+export function collectPassageReferences(
+  src: string,
+  tokens: readonly Token[],
+  parametersOf: (macro: string) => readonly ParameterDef[] | undefined,
+): PassageReference[] {
+  const refs: PassageReference[] = [];
+  for (const piece of codeAndText(src, tokens, parametersOf)) {
+    if (piece.kind === 'passage') {
+      refs.push({
+        macro: piece.macro,
+        target: { kind: 'name', name: piece.name },
+        start: piece.offset,
+        end: piece.offset + piece.length,
+      });
+    } else if (piece.kind === 'code' && piece.passage) {
+      refs.push({
+        macro: piece.macro!,
+        target: passageTarget(piece.code),
+        start: piece.offset,
+        end: piece.offset + piece.code.length,
+      });
+    }
+  }
+  return refs.filter(
+    (ref, i) =>
+      refs.findIndex((r) => r.start === ref.start && r.macro === ref.macro) ===
+      i,
+  );
+}

package/src/components/macros/Include.tsx

@@ -4,18 +4,14 @@ import { parseMarkup } from '../../markup/parse';
 import { NobrContext } from '../../markup/render';
 import { defineMacro } from '../../define-macro';
 import { evaluatePassageName } from './macro-args';
+import { INCLUDE_PARAMETERS } from './include-args';
 import { MacroError } from './MacroError';
 
 defineMacro({
   name: 'include',
   interpolate: true,
   merged: true,
-  // A standalone `inline` flag only counts outside quotes and brackets, so
-  // passage names and expressions containing the word stay intact (#201).
-  parameters: [
-    { name: 'inline', type: 'flag' },
-    { name: 'passage', type: 'passage', required: true },
-  ],
+  parameters: INCLUDE_PARAMETERS,
   render(_props, ctx) {
     const { storyData } = useStoryFields('storyData');
 

package/src/components/macros/MacroLink.tsx

@@ -1,24 +1,41 @@
 import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
 import { useDetachedBody } from './detached-body';
+import { evaluatePassageName } from './macro-args';
+import { MacroError } from './MacroError';
 
 defineMacro({
   name: 'link',
   block: true,
   interpolate: true,
-  // {link "text" "Passage"} or {link "text"}; unquoted, the whole arguments
-  // are the text.
+  merged: true,
+  // {link "text" passage} or {link "text"}; the passage is a quoted name or
+  // an expression, as in {goto}.
   parameters: [
     { name: 'text', type: 'string', required: true },
-    { name: 'passage', type: 'string' },
+    { name: 'passage', type: 'passage' },
   ],
-  render({ rawArgs, children = [] }, ctx) {
-    const { text } = ctx.args;
-    const display = text ?? rawArgs.trim();
-    const passage = text === undefined ? null : (ctx.args.passage ?? null);
+  render({ children = [] }, ctx) {
+    const display = ctx.args.text ?? '';
+    let passage: string | null = null;
+    // Boxed: anything can be thrown, including null and other falsy values
+    let failure: { error: unknown } | undefined;
+    if (ctx.args.passage !== undefined) {
+      try {
+        passage = evaluatePassageName(
+          ctx.args.passage,
+          ctx.evaluate!,
+          useStoryStore.getState(),
+        );
+      } catch (error) {
+        failure = { error };
+      }
+    }
     const runBody = useDetachedBody();
 
     const perform = () => {
+      // A link that failed to resolve is an error, not a control
+      if (failure) return;
       runBody(children);
       if (passage) {
         useStoryStore.getState().navigate(passage);
@@ -36,9 +53,18 @@ defineMacro({
       authorId: ctx.id,
       label: display,
       target: passage ?? undefined,
+      disabled: failure ? true : undefined,
       perform,
     });
 
+    if (failure) {
+      return (
+        <MacroError
+          macro="link"
+          error={failure.error}
+        />
+      );
+    }
     return (
       <a
         id={ctx.id}

package/src/components/macros/arg-utils.ts

@@ -69,6 +69,43 @@ export function readWholeQuoted(src: string): string | null {
   return quoted && quoted.end === src.length ? quoted.value : null;
 }
 
+const JS_SIMPLE_ESCAPES: Record<string, string> = {
+  n: '\n',
+  t: '\t',
+  r: '\r',
+  b: '\b',
+  f: '\f',
+  v: '\v',
+  '0': '\0',
+};
+
+/** Undo every escape of a JavaScript string literal's body. */
+function decodeJsEscapes(body: string): string {
+  return body.replace(
+    /\\(?:u\{([0-9a-fA-F]+)\}|u([0-9a-fA-F]{4})|x([0-9a-fA-F]{2})|(\r\n|[\n\r\u2028\u2029])|([\s\S]))/g,
+    (_, braced, unicode, hex, lineBreak, other: string | undefined) => {
+      if (lineBreak !== undefined) return '';
+      const code = braced ?? unicode ?? hex;
+      if (code !== undefined) {
+        const point = parseInt(code, 16);
+        return point <= 0x10ffff ? String.fromCodePoint(point) : '';
+      }
+      return JS_SIMPLE_ESCAPES[other!] ?? other!;
+    },
+  );
+}
+
+/**
+ * The value of `src` when it is exactly one `"…"` or `'…'` string, read as
+ * the JavaScript literal it is (`"\u0048all"` is `Hall`), otherwise `null`.
+ * `readWholeQuoted` keeps other escapes as written, for labels and code.
+ */
+export function readWholeJsString(src: string): string | null {
+  const quoted = readQuoted(src, 0);
+  if (!quoted || quoted.end !== src.length) return null;
+  return decodeJsEscapes(src.slice(1, -1));
+}
+
 /**
  * Strip an optional quote from each end of an unquoted-or-loosely-quoted
  * argument (`"Red`, `Red'`), leaving at least one character. This is the

package/src/components/macros/include-args.ts

@@ -0,0 +1,23 @@
+import { parseMacroArgs } from './macro-args';
+
+/**
+ * The parameters of `{include}`. A standalone `inline` flag only counts
+ * outside quotes and brackets, so passage names and expressions containing
+ * the word stay intact (#201).
+ */
+export const INCLUDE_PARAMETERS = [
+  { name: 'inline', type: 'flag' },
+  { name: 'passage', type: 'passage', required: true },
+] as const;
+
+/**
+ * The arguments of `{include}`: whether it has the `inline` flag, as its
+ * first or last word, and the passage expression that is left.
+ */
+export function splitIncludeFlag(rawArgs: string): {
+  inline: boolean;
+  passage: string | undefined;
+} {
+  const { inline, passage } = parseMacroArgs(rawArgs, INCLUDE_PARAMETERS);
+  return { inline, passage };
+}

package/src/components/macros/macro-args.ts

@@ -22,6 +22,7 @@ import {
   endsWithOperator,
   isWhitespace,
   readQuoted,
+  readWholeJsString,
   readWholeQuoted,
   stripLooseQuotes,
   topLevelIndices,
@@ -50,10 +51,26 @@ export function readText(src: string): string {
   return readWholeQuoted(src) ?? stripLooseQuotes(src);
 }
 
+/**
+ * An argument that doesn't have its parameter's form: a `string` parameter
+ * given anything but one quoted string.
+ */
+export class MacroArgumentError extends Error {
+  constructor(param: ParameterDef, src: string) {
+    super(
+      `The ${param.name} must be a quoted string ("…" or '…'), ${src ? `not ${src}` : 'but it has no value'}`,
+    );
+    this.name = 'MacroArgumentError';
+  }
+}
+
 function readValue(param: ParameterDef, src: string): unknown {
   switch (param.type) {
-    case 'string':
-      return readWholeQuoted(src) ?? undefined;
+    case 'string': {
+      const value = readWholeQuoted(src);
+      if (value === null) throw new MacroArgumentError(param, src);
+      return value;
+    }
     case 'text':
       return readText(src);
     case 'names':
@@ -76,6 +93,7 @@ function unset(param: ParameterDef): unknown {
 
 const WORD_RE = /\w+/y;
 const DIGITS_RE = /\d+/y;
+const WORD_OR_PUNCT_RE = /\S+/y;
 
 /** Match the sticky regex `re` at `pos`, returning the matched text. */
 function matchAt(re: RegExp, src: string, pos: number): string | null {
@@ -86,7 +104,8 @@ function matchAt(re: RegExp, src: string, pos: number): string | null {
 /**
  * Read keyword options (`goto "X" priority 5 once`). A keyword takes the
  * quoted string or digit run after it as its value; keywords that aren't
- * declared, and their values, are skipped.
+ * declared, and their values, are skipped. A keyword of a `string` parameter
+ * must be followed by a quoted string.
  */
 function readOptions(
   params: readonly ParameterDef[],
@@ -105,10 +124,11 @@ function readOptions(
 
     // A value is a quoted string or a digit run, after whitespace.
     let val: string | undefined;
+    let quoted: ReturnType<typeof readQuoted> = null;
     let j = i;
     while (j < src.length && isWhitespace(src[j]!)) j++;
     if (j > i) {
-      const quoted = readQuoted(src, j);
+      quoted = readQuoted(src, j);
       const digits = quoted ? null : matchAt(DIGITS_RE, src, j);
       if (quoted) {
         val = quoted.value;
@@ -120,6 +140,13 @@ function readOptions(
     }
 
     const param = params.find((p) => p.name === key);
+    // A keyword that takes a string was given anything else, or nothing
+    if (param?.type === 'string' && (!quoted || val === undefined)) {
+      throw new MacroArgumentError(
+        param,
+        matchAt(WORD_OR_PUNCT_RE, src, j) ?? '',
+      );
+    }
     if (param?.type === 'flag') options[key] = true;
     else if (param?.type === 'number') options[key] = Number(val ?? 0);
     else if (param) options[key] = val;
@@ -220,10 +247,20 @@ function readGroup(
     args[param.name] =
       from < to ? read(param, slice(text, spans[from++]!)) : unset(param);
   }
+  // Optional ones at the end: a term that doesn't have their form (a
+  // `string` that isn't quoted) belongs to the rest, as in {meter $hp 100}
+  const readTrailing = (param: ParameterDef, value: string) => {
+    try {
+      return read(param, value);
+    } catch (error) {
+      if (error instanceof MacroArgumentError) return undefined;
+      throw error;
+    }
+  };
   for (const param of positional.slice(restIndex + 1).reverse()) {
     const value =
       from < to && !endsWithOperator(text.slice(0, spans[to - 1]![0]))
-        ? read(param, slice(text, spans[to - 1]!))
+        ? readTrailing(param, slice(text, spans[to - 1]!))
         : undefined;
     args[param.name] = value ?? unset(param);
     if (value !== undefined) to--;
@@ -264,6 +301,25 @@ export function parseMacroArgs<const P extends readonly ParameterDef[]>(
   return args as MacroArgs<P>;
 }
 
+/** What a `passage` argument is: a quoted name, or an expression. */
+export type PassageTarget =
+  | { kind: 'name'; name: string }
+  | { kind: 'expression'; expression: string };
+
+/**
+ * Read a `passage` argument as written (`{goto "Hall"}`, `{goto $room}`): a
+ * quoted string is the name its JavaScript literal has (`"\u0048all"` is
+ * `Hall`), anything else an expression, whose value is the name when it
+ * runs (see evaluatePassageName).
+ */
+export function passageTarget(arg: string): PassageTarget {
+  const expression = arg.trim();
+  const name = readWholeJsString(expression);
+  return name === null
+    ? { kind: 'expression', expression }
+    : { kind: 'name', name };
+}
+
 /**
  * The passage a `passage` argument names (`{goto "Hall"}`, `{goto $room}`):
  * the value of its expression. Throws what evaluating it throws, and if no

package/src/components/macros/option-utils.ts

@@ -1,5 +1,6 @@
 import type { ASTNode } from '../../markup/ast';
 import { parseMacroArgs } from './macro-args';
+import type { ParameterDef } from '../../registry';
 
 /** `$var "placeholder"`, the arguments of the input macros. */
 export function parseVarArgs(rawArgs: string): {
@@ -14,7 +15,20 @@ export function parseVarArgs(rawArgs: string): {
 }
 
 /** The parameters of an `{option}` sub-macro: its value. */
-const OPTION_PARAMETERS = [{ name: 'value', type: 'string' }] as const;
+const OPTION_PARAMETERS = [
+  { name: 'value', type: 'string', required: true },
+] as const;
+
+/** The parameters of the built-in sub-macros that take arguments. */
+const SUB_MACRO_PARAMETERS: ReadonlyMap<string, readonly ParameterDef[]> =
+  new Map([['option', OPTION_PARAMETERS]]);
+
+/** The parameters of the built-in sub-macro `name`, if it takes any. */
+export function subMacroParameters(
+  name: string,
+): readonly ParameterDef[] | undefined {
+  return SUB_MACRO_PARAMETERS.get(name.toLowerCase());
+}
 
 /**
  * Walk AST children to find {option} macro nodes, returning their values.
@@ -23,12 +37,9 @@ export function extractOptions(children: ASTNode[]): string[] {
   const options: string[] = [];
   for (const node of children) {
     if (node.type === 'macro' && node.name === 'option') {
-      // {option "Long Sword"} gives `Long Sword`. A value that isn't one
-      // quoted string loses a matching pair of quotes around it, if any.
+      // {option "Long Sword"} gives `Long Sword`
       const { value } = parseMacroArgs(node.rawArgs, OPTION_PARAMETERS);
-      options.push(
-        value ?? node.rawArgs.trim().replace(/^(["'])(.+)\1$/s, '$2'),
-      );
+      options.push(value ?? '');
     }
   }
   return options;

package/src/define-macro.ts

@@ -30,9 +30,11 @@ import { currentSourceLocation } from './utils/source-location';
 import { parseVarArgs, extractOptions } from './components/macros/option-utils';
 import { wrapContent } from './components/macros/display';
 import {
+  MacroArgumentError,
   parseMacroArgs,
   readBoundVariable,
 } from './components/macros/macro-args';
+import { MacroError } from './components/macros/MacroError';
 import {
   checkParameterTypes,
   registerMacro,
@@ -162,8 +164,18 @@ export function defineMacro<const P extends readonly ParameterDef[] = []>(
         raw?: boolean;
       },
     ) => _renderNodes(nodes, { ...renderOptions, ...options });
+    let args: MacroArgs<P>;
+    try {
+      args = parseMacroArgs(props.rawArgs, parameters) as MacroArgs<P>;
+    } catch (error) {
+      // Shown in place, as other macro errors are
+      if (error instanceof MacroArgumentError) {
+        return h(MacroError, { macro: config.name, error });
+      }
+      throw error;
+    }
     const ctx: MacroContext<MacroArgs<P>> = {
-      args: parseMacroArgs(props.rawArgs, parameters) as MacroArgs<P>,
+      args,
       collectText,
       sourceLocation: currentSourceLocation,
       parseVarArgs,
@@ -224,7 +236,15 @@ export function defineMacro<const P extends readonly ParameterDef[] = []>(
       };
     }
 
-    return config.render(props, ctx);
+    try {
+      return config.render(props, ctx);
+    } catch (error) {
+      // An argument read while rendering, e.g. a sub-macro's ({option})
+      if (error instanceof MacroArgumentError) {
+        return h(MacroError, { macro: config.name, error });
+      }
+      throw error;
+    }
   }
 
   registerMacro(config.name, Wrapper);