@rohal12/spindle 0.57.0 → 0.59.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.57.0",
+  "version": "0.59.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/code-check.ts

@@ -8,18 +8,20 @@
  * - `{$…}` expressions, and `{do}` bodies (statements);
  * - the conditions of `{if}`, `{elseif}` and `{case}`;
  * - macro arguments whose declared parameter type is `expression`,
- *   `statements` or `passage`, built-in and custom macros alike; the
- *   condition and `run` action of `{watch}`, code in quoted strings;
+ *   `statements` or `passage`, built-in and custom macros alike, and the
+ *   `string` and `text` arguments that hold code (ParameterDef.holds: the
+ *   condition and `run` action of `{watch}`);
  * - the `{$…}` references in attributes holding code (`onclick`).
  *
- * Text that may hold markup is found in quoted labels (arguments of type
- * `text` and `string`) and HTML attribute values; the check reads its
- * markup in turn.
+ * Text that may hold markup is found in the `string` and `text` arguments
+ * that hold markup (labels such as `{button}`'s) and HTML attribute values;
+ * the check reads its markup in turn.
  *
  * Passage names written out are found in links (`[[Go->Hall]]`), in
  * `passage` arguments that are one quoted string (`{goto "Hall"}`), in the
- * passage of `{link}`, the `goto` and `dialog` actions of `{watch}` and the
- * body of `{dialog}`; the check looks each one up.
+ * `string` and `text` arguments that hold a passage name (the `goto` and
+ * `dialog` actions of `{watch}`) and in the body of `{dialog}`; the check
+ * looks each one up.
  *
  * The arguments of macros that declare no parameters may be anything:
  * they are not checked.
@@ -28,12 +30,16 @@ import type { Token } from './markup/tokens';
 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 type { ParameterDef, StringHolds } from './registry';
 import {
   MacroArgumentError,
   parseMacroArgs,
+  passageTarget,
+  type ArgSpans,
+  type PassageTarget,
 } from './components/macros/macro-args';
-import { readWholeQuoted } from './components/macros/arg-utils';
+import { subMacroParameters } from './components/macros/option-utils';
+import { NameMap } from './utils/macro-names';
 
 /** While a pass runs: the code it parsed so far, by goal and source. */
 let parses: Map<string, ParsedCode | CodeSyntaxError> | null = null;
@@ -78,8 +84,15 @@ export interface CodePiece {
   goal: JsGoal;
   /** The markup it is in, for the error: `{print $a +}`. */
   label: string;
-  /** Whether it names a passage: a `passage` argument. */
+  /**
+   * Whether it names a passage: a `passage` argument that is an
+   * expression (one that is a string literal is a PassagePiece).
+   */
   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. */
@@ -89,6 +102,10 @@ 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 (quotes included). */
+  length: number;
+  /** The macro it is the argument of; `link` for `[[…]]` links. */
+  macro: string;
 }
 
 /** Macro arguments that don't have their parameters' forms. */
@@ -112,21 +129,79 @@ export interface TextPiece {
 /** Macros whose whole argument text is one expression: branch conditions. */
 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' },
-};
-
-/** The `string` parameters of a macro that name a passage. */
-const PASSAGE_STRINGS: Record<string, readonly string[]> = {
-  watch: ['goto', 'dialog'],
-};
-
 /** Block macros whose body is the name of a passage. */
 const PASSAGE_BODIES = new Set(['dialog']);
 
 type Piece = CodePiece | TextPiece | PassagePiece | ArgumentErrorPiece;
 
+/** The declared parameters of a macro, if it has any. */
+export type ParametersOf = (
+  macro: string,
+) => readonly ParameterDef[] | undefined;
+
+/** What the argument check needs to know of a macro (see MacroMetadata). */
+export interface MacroParameters {
+  name: string;
+  parameters?: readonly ParameterDef[];
+  interpolate?: boolean;
+}
+
+/**
+ * `params` with each `string` and `text` parameter (options too) saying
+ * what it holds: what it declares, else `holds`.
+ */
+function withHolds(
+  params: readonly ParameterDef[],
+  holds: StringHolds,
+): readonly ParameterDef[] {
+  return params.map((param) => {
+    if (param.parameters) {
+      return { ...param, parameters: withHolds(param.parameters, holds) };
+    }
+    const isString = param.type === 'string' || param.type === 'text';
+    return isString && !param.holds ? { ...param, holds } : param;
+  });
+}
+
+/**
+ * The declared parameters of `macros`, by name in any case, and of the
+ * built-in sub-macros (`{option}`): what the story-start check, reference
+ * collection and tooling read arguments by. Each `string` and `text`
+ * parameter says what it holds: what it declares, else `markup` for a macro
+ * with `interpolate` (which can resolve markup) and `text` for any other.
+ */
+export function parameterLookup(
+  macros: Iterable<MacroParameters>,
+): ParametersOf {
+  const parameters = new NameMap<readonly ParameterDef[]>();
+  for (const { name, parameters: params, interpolate } of macros) {
+    if (params)
+      parameters.set(name, withHolds(params, holdsByDefault(interpolate)));
+  }
+  return (name) => {
+    let params = parameters.get(name);
+    if (!params) {
+      const sub = subMacroParameters(name);
+      if (sub) parameters.set(name, (params = withHolds(sub, 'text')));
+    }
+    return params;
+  };
+}
+
+/** What a `string` or `text` argument holds when its parameter doesn't say. */
+const holdsByDefault = (interpolate: boolean | undefined): StringHolds =>
+  interpolate ? 'markup' : 'text';
+
+/** Whether a parameter in `params` (options too) holds code in a string. */
+export function holdsCode(params: readonly ParameterDef[]): boolean {
+  return params.some(
+    (p) =>
+      p.holds === 'expression' ||
+      p.holds === 'statements' ||
+      (!!p.parameters && holdsCode(p.parameters)),
+  );
+}
+
 /** The goal of the code an argument of this type holds, if it is code. */
 function codeGoal(param: ParameterDef): JsGoal | undefined {
   if (param.type === 'expression' || param.type === 'passage') {
@@ -136,6 +211,15 @@ function codeGoal(param: ParameterDef): JsGoal | undefined {
   return undefined;
 }
 
+/**
+ * What a `string` or `text` argument holds: what its parameter says (see
+ * parameterLookup), else markup, which is checked.
+ */
+function stringHolds(param: ParameterDef): StringHolds | undefined {
+  if (param.type !== 'string' && param.type !== 'text') return undefined;
+  return param.holds ?? 'markup';
+}
+
 /**
  * The code and the markup-holding text in `tokens`, the tokens of `src`.
  * `parametersOf` gives the declared parameters of a macro, if it has any.
@@ -143,7 +227,7 @@ function codeGoal(param: ParameterDef): JsGoal | undefined {
 export function* codeAndText(
   src: string,
   tokens: readonly Token[],
-  parametersOf: (macro: string) => readonly ParameterDef[] | undefined,
+  parametersOf: ParametersOf,
 ): Generator<Piece> {
   /** The index of the closing tag of the `name` macro opened at `t`. */
   const closeOf = (t: number, name: string) =>
@@ -160,7 +244,9 @@ export function* codeAndText(
       yield {
         kind: 'passage',
         name: token.target,
-        offset: locate(src, token.target, token.start),
+        offset: token.targetStart,
+        length: token.targetEnd - token.targetStart,
+        macro: 'link',
         label: src.slice(token.start, token.end),
       };
     } else if (token.type === 'expression') {
@@ -172,9 +258,11 @@ export function* codeAndText(
         label: `{${token.expression}}`,
       };
     } else if (token.type === 'html') {
+      // The values are the source text between their quotes, in order
+      let cursor = token.start;
       for (const [name, value] of Object.entries(token.attributes)) {
-        // The value is the source text between its quotes
-        const at = locate(src, value, token.start);
+        const at = locate(src, value, cursor);
+        cursor = at + value.length;
         if (!isCodeAttribute(name)) {
           yield {
             kind: 'text',
@@ -221,18 +309,22 @@ export function* codeAndText(
         const body = tokens.slice(t + 1, close);
         if (close > t + 1 && body.every((b) => b.type === 'text')) {
           const text = src.slice(token.end, tokens[close]!.start);
-          const passage = text.trim().replace(/^["']|["']$/g, '');
+          const written = text.trim();
           yield {
             kind: 'passage',
-            name: passage,
-            offset: locate(src, passage, token.end),
+            name: written.replace(/^["']|["']$/g, ''),
+            offset: token.end + text.indexOf(written),
+            length: written.length,
+            macro: name,
             label: src.slice(token.start, token.end),
           };
         }
       }
       if (!args) continue;
       const label = `{${token.name} ${args}}`;
-      const argsAt = locate(src, args, token.start + 1);
+      // The arguments end the tag, but for the whitespace before its }
+      const tag = src.slice(token.start, token.end - 1);
+      const argsAt = token.start + tag.trimEnd().length - args.length;
       if (CONDITION_MACROS.has(name)) {
         yield {
           kind: 'code',
@@ -250,7 +342,7 @@ 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[],
@@ -258,16 +350,15 @@ function* argPieces(
   label: string,
 ): Generator<Piece> {
   let values: Record<string, unknown>;
+  const spans: ArgSpans = new Map();
   try {
-    values = parseMacroArgs(args, params) as Record<string, unknown>;
+    values = parseMacroArgs(args, params, spans) as Record<string, unknown>;
   } catch (error) {
     if (!(error instanceof MacroArgumentError)) throw error;
     yield { kind: 'argument-error', message: error.message, offset, label };
     return;
   }
-  const inStrings = CODE_IN_STRINGS[macro.toLowerCase()] ?? {};
-  const passageStrings = PASSAGE_STRINGS[macro.toLowerCase()] ?? [];
-  let cursor = 0;
+  const name = macro.toLowerCase();
   /** The pieces of the parameters `list`, with their values in `from`. */
   function* visit(
     list: readonly ParameterDef[],
@@ -282,36 +373,63 @@ function* argPieces(
         );
         continue;
       }
-      if (typeof value !== 'string' || !value.trim()) continue;
-      const at = locate(args, value, cursor);
-      if (at >= cursor) cursor = at + value.length;
-      const goal = codeGoal(param) ?? inStrings[param.name];
+      const span = spans.get(param);
+      if (typeof value !== 'string' || !value.trim() || !span) continue;
+      const [start, end] = span;
+      const written = args.slice(start, end);
+      /** The name as written (quotes included), at the argument. */
+      const passage = (passageName: string): PassagePiece => ({
+        kind: 'passage',
+        name: passageName,
+        offset: offset + start,
+        length: end - start,
+        macro: name,
+        label,
+      });
+      const goal = codeGoal(param);
+      if (param.type === 'passage') {
+        // A name written out, else an expression naming one
+        const target = passageTarget(value);
+        if (target.kind === 'name') {
+          yield passage(target.name);
+          continue;
+        }
+      }
       if (goal) {
         const piece: CodePiece = {
           kind: 'code',
           code: value,
-          offset: offset + at,
+          offset: offset + start,
           goal,
           label,
         };
-        if (param.type === 'passage') piece.passage = true;
+        if (param.type === 'passage') {
+          piece.passage = true;
+          piece.macro = name;
+        }
         yield piece;
+        continue;
       }
-      // A passage written out: a quoted `passage` argument, or a string
-      const name =
-        param.type === 'passage'
-          ? readWholeQuoted(value.trim())
-          : passageStrings.includes(param.name)
-            ? value
-            : null;
-      if (name !== null) {
-        yield { kind: 'passage', name, offset: offset + at, label };
-      }
-      if (!goal && (param.type === 'text' || param.type === 'string')) {
+      // The value of a string is inside its quotes
+      const at =
+        offset + start + (value !== written && /^["']/.test(written) ? 1 : 0);
+      const holds = stringHolds(param);
+      if (holds === 'expression' || holds === 'statements') {
+        yield {
+          kind: 'code',
+          code: value,
+          offset: at,
+          goal: holds,
+          label,
+          inString: true,
+        };
+      } else if (holds === 'passage') {
+        yield passage(value);
+      } else if (holds === 'markup') {
         yield {
           kind: 'text',
           text: value,
-          offset: offset + at,
+          offset: at,
           where: `In the ${param.name} of {${macro}}: `,
         };
       }
@@ -330,3 +448,49 @@ 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 `string` and `text` arguments of macros that declare
+ * they hold one) 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: ParametersOf,
+): 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: { kind: 'expression', expression: piece.code },
+        start: piece.offset,
+        end: piece.offset + piece.code.length,
+      });
+    }
+  }
+  return refs;
+}

package/src/components/macros/Button.tsx

@@ -5,7 +5,9 @@ defineMacro({
   name: 'button',
   block: true,
   interpolate: true,
-  parameters: [{ name: 'label', type: 'text', required: true }],
+  parameters: [
+    { name: 'label', type: 'text', holds: 'markup', required: true },
+  ],
   render({ rawArgs, children = [] }, ctx) {
     const label = ctx.resolve?.(ctx.args.label ?? '') ?? rawArgs;
     const runBody = useDetachedBody();

package/src/components/macros/Checkbox.tsx

@@ -4,7 +4,10 @@ import { VARIABLE_PARAMETER, useVariableAction } from './input-macro';
 defineMacro({
   name: 'checkbox',
   storeVar: true,
-  parameters: [VARIABLE_PARAMETER, { name: 'label', type: 'text' }],
+  parameters: [
+    VARIABLE_PARAMETER,
+    { name: 'label', type: 'text', holds: 'text' },
+  ],
   render(_props, ctx) {
     const label = ctx.args.label ?? '';
 

package/src/components/macros/Dialog.tsx

@@ -6,7 +6,7 @@ defineMacro({
   block: true,
   interpolate: true,
   parameters: [
-    { name: 'label', type: 'text', required: true },
+    { name: 'label', type: 'text', holds: 'markup', required: true },
     { name: 'noclose', type: 'flag' },
   ],
   render({ children = [] }, ctx) {

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

@@ -12,7 +12,7 @@ defineMacro({
   // {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: 'text', type: 'string', holds: 'markup', required: true },
     { name: 'passage', type: 'passage' },
   ],
   render({ children = [] }, ctx) {
@@ -34,6 +34,8 @@ defineMacro({
     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);
@@ -51,6 +53,7 @@ defineMacro({
       authorId: ctx.id,
       label: display,
       target: passage ?? undefined,
+      disabled: failure ? true : undefined,
       perform,
     });
 

package/src/components/macros/Meter.tsx

@@ -40,7 +40,7 @@ defineMacro({
   parameters: [
     { name: 'current', type: 'expression', required: true },
     { name: 'max', type: 'expression', required: true },
-    { name: 'label', type: 'string' },
+    { name: 'label', type: 'string', holds: 'markup' },
   ],
   render(_props, ctx) {
     try {

package/src/components/macros/Radiobutton.tsx

@@ -6,8 +6,8 @@ defineMacro({
   storeVar: true,
   parameters: [
     VARIABLE_PARAMETER,
-    { name: 'value', type: 'text', required: true },
-    { name: 'label', type: 'text' },
+    { name: 'value', type: 'text', holds: 'text', required: true },
+    { name: 'label', type: 'text', holds: 'text' },
   ],
   render(_props, ctx) {
     const radioValue = ctx.args.value ?? '';

package/src/components/macros/Watch.tsx

@@ -5,15 +5,20 @@ defineMacro({
   name: 'watch',
   // {watch "condition" goto "X" dialog "X" run "X" name "X" priority N once}
   parameters: [
-    { name: 'condition', type: 'string', required: true },
+    {
+      name: 'condition',
+      type: 'string',
+      holds: 'expression',
+      required: true,
+    },
     {
       name: 'options',
       type: 'options',
       parameters: [
-        { name: 'goto', type: 'string' },
-        { name: 'dialog', type: 'string' },
-        { name: 'run', type: 'string' },
-        { name: 'name', type: 'string' },
+        { name: 'goto', type: 'string', holds: 'passage' },
+        { name: 'dialog', type: 'string', holds: 'passage' },
+        { name: 'run', type: 'string', holds: 'statements' },
+        { name: 'name', type: 'string', holds: 'text' },
         { name: 'priority', type: 'number' },
         { name: 'once', type: 'flag' },
       ],
@@ -41,7 +46,7 @@ defineMacro({
 
 defineMacro({
   name: 'unwatch',
-  parameters: [{ name: 'name', type: 'text', required: true }],
+  parameters: [{ name: 'name', type: 'text', holds: 'text', required: true }],
   render(_props, ctx) {
     const name = ctx.args.name ?? '';
 

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/input-macro.ts

@@ -46,7 +46,10 @@ export function defineInputMacro(
   defineMacro({
     name,
     storeVar: true,
-    parameters: [VARIABLE_PARAMETER, { name: 'placeholder', type: 'string' }],
+    parameters: [
+      VARIABLE_PARAMETER,
+      { name: 'placeholder', type: 'string', holds: 'text' },
+    ],
     render(_props, ctx) {
       const placeholder = ctx.args.placeholder ?? '';