@rohal12/spindle 0.53.0 → 0.55.0

package/src/types-drift-check.ts

@@ -21,7 +21,19 @@ import type {
   MacroProps as PublishedMacroProps,
   ASTNode as PublishedASTNode,
 } from '../types/index';
-import type { parseStoryVariables as PublishedParse } from '../types/tooling';
+import type {
+  parseStoryVariables as PublishedParse,
+  formatDiagnostic as PublishedFormatDiagnostic,
+  MarkupDiagnostic as PublishedMarkupDiagnostic,
+  MarkupPassage as PublishedMarkupPassage,
+  validateMarkup as PublishedValidateMarkup,
+} from '../types/tooling';
+import type {
+  formatDiagnostic as SourceFormatDiagnostic,
+  MarkupDiagnostic as SourceMarkupDiagnostic,
+  MarkupPassage as SourceMarkupPassage,
+  validateStoryMarkup as SourceValidateStoryMarkup,
+} from './tooling';
 import type { bootStory as PublishedBootStory } from '../types/headless';
 
 /** What the source declares, by published name. */
@@ -30,6 +42,11 @@ interface Source {
   // Tooling entry point (`@rohal12/spindle/tooling`): the parser that
   // dist/pkg/tooling.js re-exports.
   parseStoryVariables: typeof SourceParse;
+  // Its markup validator (pkg/tooling.js binds validateStoryMarkup to the
+  // macro metadata, so validateMarkup itself takes only the passages).
+  MarkupPassage: SourceMarkupPassage;
+  MarkupDiagnostic: SourceMarkupDiagnostic;
+  formatDiagnostic: typeof SourceFormatDiagnostic;
   // Custom macro API: the MacroContext/MacroDefinition defineMacro()
   // actually passes and accepts.
   MacroContext: SourceMacroContext;
@@ -44,6 +61,9 @@ interface Source {
 interface Published {
   StoryAPI: PublishedAPI;
   parseStoryVariables: typeof PublishedParse;
+  MarkupPassage: PublishedMarkupPassage;
+  MarkupDiagnostic: PublishedMarkupDiagnostic;
+  formatDiagnostic: typeof PublishedFormatDiagnostic;
   MacroContext: PublishedMacroContext;
   MacroDefinition: PublishedMacroDefinition;
   MacroProps: PublishedMacroProps;
@@ -90,3 +110,10 @@ const _exampleMacro: PublishedMacroDefinition = {
     );
   },
 };
+
+// pkg/tooling.js's validateMarkup is validateStoryMarkup bound to the macro
+// metadata.
+declare const validateStoryMarkup: typeof SourceValidateStoryMarkup;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _validateMarkup: typeof PublishedValidateMarkup = (passages) =>
+  validateStoryMarkup(passages, []);

package/src/widgets/widget-def.ts

@@ -0,0 +1,60 @@
+/**
+ * Reading widget definitions without rendering anything: the `{widget}`
+ * macro, startup and markup validation (also in tooling) share these.
+ */
+import { parseMacroArgs } from '../components/macros/macro-args';
+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: 'text' },
+] as const;
+
+export interface WidgetDef {
+  name: string;
+  params: string[];
+}
+
+/**
+ * The widget a {widget} definition's arguments declare: its name and its
+ * parameters, the words after it that start with `@` (docs/widgets.md).
+ * Other words, such as `$name`, are not parameters.
+ */
+export function widgetDef({
+  name = '',
+  parameters = '',
+}: MacroArgs<typeof WIDGET_PARAMETERS>): WidgetDef {
+  return {
+    name,
+    params: parameters.split(/\s+/).filter((word) => word.startsWith('@')),
+  };
+}
+
+/** Read the arguments of a {widget} definition (see widgetDef). */
+export function parseWidgetDef(rawArgs: string): WidgetDef {
+  return widgetDef(parseMacroArgs(rawArgs, WIDGET_PARAMETERS));
+}
+
+const BLOCK_WIDGET = /\{widget\s+["']?(\w+)["']?[^}]*\}([\s\S]*?)\{\/widget\}/g;
+
+/**
+ * The names of the block widgets (those whose body renders `{@children}`)
+ * that StoryInit and the passages tagged `widget` define. They must be
+ * known as block macros before any passage is parsed, so that passages
+ * invoking them nest their content whatever the passage order.
+ */
+export function blockWidgetNames(
+  passages: Iterable<{ name: string; tags?: string[]; content: string }>,
+): string[] {
+  const names: string[] = [];
+  for (const passage of passages) {
+    if (passage.name !== 'StoryInit' && !passage.tags?.includes('widget')) {
+      continue;
+    }
+    for (const match of passage.content.matchAll(BLOCK_WIDGET)) {
+      if (/\{@children\}/.test(match[2]!)) names.push(match[1]!);
+    }
+  }
+  return names;
+}

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[];
 }
@@ -99,3 +103,49 @@ export declare function parseStoryVariables(
   content: string,
   sigil?: '$' | '%',
 ): Map<string, VariableSchema>;
+
+/** 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;
+}
+
+/**
+ * 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), 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>,
+): MarkupDiagnostic[];
+
+/**
+ * A diagnostic as one line of text, as Spindle shows it:
+ * `Passage "Start", line 3, column 5 (story.twee:12): Unclosed {if}: …`.
+ */
+export declare function formatDiagnostic(diagnostic: MarkupDiagnostic): string;