jssm 5.142.4 → 5.143.0

package/dist/deno/jssm_compiler.d.ts

@@ -1,4 +1,22 @@
-import { JssmTransition, JssmCompileSe, JssmParseTree, JssmGenericConfig } from './jssm_types';
+import { JssmTransition, JssmCompileSe, JssmCompileSeStart, JssmParseTree, JssmGenericConfig, FslSourceLocation } from './jssm_types';
+/*********
+ *
+ *  Returns the source span of the `n`-th parse-tree node (1-based) matching
+ *  `predicate`, or `undefined` if there are fewer than `n` matches or the
+ *  matched node carries no location.  Used to point semantic compile errors
+ *  at the offending statement when the tree was produced with
+ *  `parse(input, { locations: true })`.
+ *
+ *  @internal
+ *
+ *  @param tree      The parse tree to scan.
+ *  @param predicate Node test.
+ *  @param n         1-based ordinal of the matching node to return.
+ *
+ *  @returns The matching node's `loc`, or `undefined`.
+ *
+ */
+declare function nth_matching_loc<StateType, mDT>(tree: JssmParseTree<StateType, mDT>, predicate: (node: JssmCompileSeStart<StateType, mDT>) => boolean, n: number): FslSourceLocation | undefined;
 /*********
  *
  *  Internal method meant to perform factory assembly of an edge.  Not meant for
@@ -51,6 +69,34 @@ declare function makeTransition<StateType, mDT>(this_se: JssmCompileSe<StateType
  *  This method is mostly for plugin and intermediate tool authors, or people
  *  who need to work with the machine's intermediate representation.
  *
+ *  ## Opt-in source locations
+ *
+ *  Pass `{ locations: true }` to attach source-span information to every
+ *  object node in the AST.  Each node gains a `loc` field of type
+ *  {@link FslSourceLocation} covering its full statement span.  Selected nodes
+ *  also gain curated sub-span fields that pinpoint individual tokens within the
+ *  statement:
+ *
+ *  - Transition nodes: `from_loc` (source state), `to_loc` (target state, on
+ *    the nested `se` object), `l_action_loc` / `r_action_loc` (action labels).
+ *  - State-declaration nodes: `name_loc` (state name), plus `value_loc` on
+ *    each color-bearing item inside the declaration block.
+ *  - Machine-attribute nodes (`machine_name`, `fsl_version`, etc.): `value_loc`
+ *    (the attribute value token).
+ *
+ *  Without `{ locations: true }` the AST is byte-for-byte identical to the
+ *  default output; no `loc` or `*_loc` fields are present.
+ *
+ *  ```typescript
+ *  const tree = wrap_parse('a -> b;', { locations: true });
+ *  // tree[0].loc  === { start: { offset: 0, line: 1, column: 1 },
+ *  //                    end:   { offset: 7, line: 1, column: 8 } }
+ *  // tree[0].from_loc.start.offset === 0   // 'a'
+ *  // tree[0].se.to_loc.start.offset === 5  // 'b'
+ *  ```
+ *
+ *  @see {@link FslSourceLocation}
+ *
  *  # Hey!
  *
  *  Most people looking at this want either the `sm` operator or method `from`,
@@ -79,7 +125,9 @@ declare function makeTransition<StateType, mDT>(this_se: JssmCompileSe<StateType
  *
  *  @param input The FSL code to be evaluated
  *
- *  @param options Things to control about the instance
+ *  @param options Things to control about the instance.  Pass
+ *                 `{ locations: true }` to enable opt-in source location
+ *                 tracking on every AST node.
  *
  */
 declare function wrap_parse(input: string, options?: Object): any;
@@ -106,6 +154,31 @@ declare function wrap_parse(input: string, options?: Object): any;
  *  This method is mostly for plugin and intermediate tool authors, or people
  *  who need to work with the machine's intermediate representation.
  *
+ *  ## Source-location-aware error reporting
+ *
+ *  `compile()` ignores `loc` and `*_loc` fields during machine construction —
+ *  the resulting config is identical whether or not the tree was parsed with
+ *  `{ locations: true }`.  However, when those fields are present, `compile()`
+ *  attaches the offending node's source span to any semantic {@link JssmError}
+ *  it throws, via the error's `source_location` field
+ *  (type {@link FslSourceLocation}).  This lets downstream tooling (e.g. a
+ *  CodeMirror 6 linter) map the error to a precise editor range without any
+ *  additional source-scanning.
+ *
+ *  ```typescript
+ *  import { parse, compile } from 'jssm';
+ *
+ *  try {
+ *    compile(parse('fsl_version: 1.0.0;\nfsl_version: 2.0.0;\na -> b;',
+ *                  { locations: true }));
+ *  } catch (err) {
+ *    // err.source_location.start.offset points at the second fsl_version line
+ *    console.log(err.source_location);
+ *  }
+ *  ```
+ *
+ *  @see {@link FslSourceLocation}
+ *
  *  # Hey!
  *
  *  Most people looking at this want either the `sm` operator or method `from`,
@@ -131,7 +204,10 @@ declare function wrap_parse(input: string, options?: Object): any;
  *
  *  @typeparam mDT The type of the machine data member; usually omitted
  *
- *  @param tree The parse tree to be boiled down into a machine config
+ *  @param tree The parse tree to be boiled down into a machine config.  If the
+ *              tree was produced with `parse(input, { locations: true })`, any
+ *              semantic error thrown will carry a `source_location` span
+ *              pointing at the offending statement.
  *
  */
 declare function compile<StateType, mDT>(tree: JssmParseTree<StateType, mDT>): JssmGenericConfig<StateType, mDT>;
@@ -147,4 +223,4 @@ declare function compile<StateType, mDT>(tree: JssmParseTree<StateType, mDT>): J
  *
  */
 declare function make<StateType, mDT>(plan: string): JssmGenericConfig<StateType, mDT>;
-export { compile, make, makeTransition, wrap_parse };
+export { compile, make, makeTransition, wrap_parse, nth_matching_loc };

package/dist/deno/jssm_error.d.ts

@@ -1,10 +1,16 @@
-import { JssmErrorExtendedInfo } from './jssm_types';
+import { JssmErrorExtendedInfo, FslSourceLocation } from './jssm_types';
 /*******
  *
  *  Custom error class for jssm.  Enriches the standard `Error` with
  *  machine context (current state, instance name) and an optional
  *  `requested_state` so that error messages are self-describing.
  *
+ *  When a semantic error is detected during `compile()` and the parse tree
+ *  was produced with `parse(input, { locations: true })`, the thrown error
+ *  also carries a `source_location` field — the FSL source span of the
+ *  offending statement — so downstream tooling can map the error to a precise
+ *  position in the original source text without additional scanning.
+ *
  *  ```typescript
  *  throw new JssmError(machine, 'no such state', { requested_state: 'Blue' });
  *  // JssmError: [[my-light]]: no such state (at "Red", requested "Blue")
@@ -15,13 +21,17 @@ import { JssmErrorExtendedInfo } from './jssm_types';
  *                           read `state()` and `instance_name()` for context.
  *  @param message         - A human-readable description of the error.
  *  @param JEEI            - Optional {@link JssmErrorExtendedInfo} with extra
- *                           context such as `requested_state`.
+ *                           context such as `requested_state` and/or
+ *                           `source_location` (the FSL source span of the
+ *                           offending statement, present when the error
+ *                           originated from a located parse tree).
  *
  */
 declare class JssmError extends Error {
     message: string;
     base_message: string;
     requested_state: string | undefined;
+    source_location: FslSourceLocation | undefined;
     constructor(machine: any, message: string, JEEI?: JssmErrorExtendedInfo);
 }
 export { JssmError };

package/dist/deno/jssm_types.d.ts

@@ -247,6 +247,26 @@ declare type JssmGenericMachine<DataType> = {
     allow_force?: boolean;
     keep_history?: boolean | number;
 };
+/**
+ *  A source span produced by the FSL parser when `parse(input, { locations:
+ *  true })` is used.  Mirrors PEG.js's native `location()` shape: byte
+ *  `offset`s (0-based, half-open) plus 1-based `line`/`column` for display.
+ *
+ *  ```typescript
+ *  const [t] = parse('a -> b;', { locations: true });
+ *  // t.loc === { start: { offset: 0, line: 1, column: 1 },
+ *  //             end:   { offset: 7, line: 1, column: 8 } }
+ *  ```
+ */
+declare type FslSourcePoint = {
+    offset: number;
+    line: number;
+    column: number;
+};
+declare type FslSourceLocation = {
+    start: FslSourcePoint;
+    end: FslSourcePoint;
+};
 /**
  *  A single key/value pair from an FSL `state X: { ... };` block, in the
  *  raw form produced by the parser before being condensed into a
@@ -256,6 +276,8 @@ declare type JssmStateDeclarationRule = {
     key: string;
     value: any;
     name?: string;
+    loc?: FslSourceLocation;
+    value_loc?: FslSourceLocation;
 };
 /**
  *  The fully-condensed declaration for a single state, including its raw
@@ -472,6 +494,10 @@ declare type JssmCompileSe<StateType, mDT> = {
     r_probability: number;
     l_after?: number;
     r_after?: number;
+    loc?: FslSourceLocation;
+    to_loc?: FslSourceLocation;
+    l_action_loc?: FslSourceLocation;
+    r_action_loc?: FslSourceLocation;
 };
 /**
  *  Internal compiler intermediate: the root of a chained transition
@@ -486,11 +512,15 @@ declare type JssmCompileSeStart<StateType, DataType> = {
     from: StateType;
     se: JssmCompileSe<StateType, DataType>;
     key: string;
-    value?: string | number;
+    value?: string | number | Array<JssmStateDeclarationRule>;
     name?: string;
     state?: string;
     default_value?: any;
     required?: boolean;
+    loc?: FslSourceLocation;
+    from_loc?: FslSourceLocation;
+    value_loc?: FslSourceLocation;
+    name_loc?: FslSourceLocation;
 };
 /**
  *  The output shape of the FSL parser: a flat array of
@@ -712,6 +742,7 @@ declare type PostEverythingHookHandler<mDT> = (hook_context: EverythingHookConte
  */
 declare type JssmErrorExtendedInfo = {
     requested_state?: StateType | undefined;
+    source_location?: FslSourceLocation;
 };
 /**
  *  Bounded history of recently-visited states paired with the data payload
@@ -933,4 +964,4 @@ declare type JssmEventHandler<mDT, Ev extends JssmEventName> = (detail: JssmEven
  *  removes the subscription.  Calling it more than once is a no-op.
  */
 declare type JssmUnsubscribe = () => void;
-export { JssmColor, JssmShape, JssmTransition, JssmTransitions, JssmTransitionList, JssmTransitionRule, JssmArrow, JssmArrowKind, JssmArrowDirection, JssmGenericConfig, JssmGenericState, JssmGenericMachine, JssmParseTree, JssmCompileSe, JssmCompileSeStart, JssmCompileRule, JssmPermitted, JssmPermittedOpt, JssmResult, JssmStateDeclaration, JssmStateDeclarationRule, JssmStateConfig, JssmStateStyleKey, JssmStateStyleKeyList, JssmBaseTheme, JssmTheme, JssmLayout, JssmHistory, JssmSerialization, JssmPropertyDefinition, JssmAllowsOverride, JssmAllowIslands, JssmDefaultSize, JssmParseFunctionType, JssmMachineInternalState, JssmErrorExtendedInfo, FslDirections, FslDirection, FslThemes, FslTheme, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult, EverythingHookContext, EverythingHookHandler, PostEverythingHookHandler, JssmEventName, JssmEventDetailMap, JssmEventFilterMap, JssmEventFilter, JssmEventHandler, JssmUnsubscribe, JssmTransitionEventDetail, JssmRejectionEventDetail, JssmActionEventDetail, JssmEntryEventDetail, JssmExitEventDetail, JssmTerminalEventDetail, JssmCompleteEventDetail, JssmErrorEventDetail, JssmDataChangeEventDetail, JssmOverrideEventDetail, JssmTimeoutEventDetail, JssmHookLifecycleEventDetail, JssmRng };
+export { JssmColor, JssmShape, JssmTransition, JssmTransitions, JssmTransitionList, JssmTransitionRule, JssmArrow, JssmArrowKind, JssmArrowDirection, JssmGenericConfig, JssmGenericState, JssmGenericMachine, JssmParseTree, JssmCompileSe, JssmCompileSeStart, JssmCompileRule, JssmPermitted, JssmPermittedOpt, JssmResult, JssmStateDeclaration, JssmStateDeclarationRule, JssmStateConfig, JssmStateStyleKey, JssmStateStyleKeyList, JssmBaseTheme, JssmTheme, JssmLayout, JssmHistory, JssmSerialization, JssmPropertyDefinition, JssmAllowsOverride, JssmAllowIslands, JssmDefaultSize, JssmParseFunctionType, JssmMachineInternalState, JssmErrorExtendedInfo, FslDirections, FslDirection, FslThemes, FslTheme, FslSourcePoint, FslSourceLocation, HookDescription, HookHandler, HookContext, HookResult, HookComplexResult, EverythingHookContext, EverythingHookHandler, PostEverythingHookHandler, JssmEventName, JssmEventDetailMap, JssmEventFilterMap, JssmEventFilter, JssmEventHandler, JssmUnsubscribe, JssmTransitionEventDetail, JssmRejectionEventDetail, JssmActionEventDetail, JssmEntryEventDetail, JssmExitEventDetail, JssmTerminalEventDetail, JssmCompleteEventDetail, JssmErrorEventDetail, JssmDataChangeEventDetail, JssmOverrideEventDetail, JssmTimeoutEventDetail, JssmHookLifecycleEventDetail, JssmRng };