sandstone 1.0.0-beta.2 → 1.0.0-beta.4

package/src/flow/loops/for_of.ts

@@ -3,7 +3,6 @@ import type { SandstoneCore } from 'sandstone/core/sandstoneCore'
 import type { DataPointClass, IterableDataClass, Score, StringDataPointClass } from 'sandstone/variables'
 import { LoopArgument } from 'sandstone/variables'
 import { IfStatement } from '../if_else'
-import type { ConditionNode } from '..'
 import { LoopNode } from '../loop'
 
 export type ForOfIterator = 'entry' | ['i', 'entry'] | ['key', 'value']
@@ -17,54 +16,61 @@ export type ForOfIterate<ITERATOR extends ForOfIterator> = ITERATOR extends 'ent
       : [key: StringDataPointClass, value: DataPointClass]
     : [never]
 
+function isMultipleVariable(iteratorType: ForOfIterator): iteratorType is Exclude<ForOfIterator, 'entry'> {
+  if (Array.isArray(iteratorType)) {
+    return true
+  }
+  return false
+}
+
+function isMapIterator(iteratorType: ForOfIterator, iterable: IterableDataClass<'list' | 'map'>): iterable is IterableDataClass<'map'> {
+  if (isMultipleVariable(iteratorType) && iteratorType[0] === 'key') {
+    if (iterable.iteratorType === 'map') {
+      return true
+    }
+    throw new Error(
+      'Attempt to use "for key value" loop with a List iterable; this is not supported. (Hint: use "for entry" or "for i entry" instead)',
+    )
+  }
+  return false
+}
+
 export class ForOfNode<ITERATOR extends ForOfIterator, ITERATE extends ForOfIterate<ForOfIterator>> extends LoopNode {
   constructor(
     sandstoneCore: SandstoneCore,
     iteratorType: ITERATOR,
-    iterable: IterableDataClass,
+    direction: 'normal' | 'reverse',
+    iterable: IterableDataClass<ITERATOR extends string[] ? ITERATOR[0] extends 'key' ? 'map' : ('list' | 'map') : ('list' | 'map')>,
     callback: (...args: ITERATE) => any,
   ) {
-    const _iterable = iterable._toDataPoint()
-
-    let startCondition: SubCommand
-
     let iterate: () => void
 
-    let continueCondition: ConditionNode
-
-    if (Array.isArray(iteratorType)) {
-      if (iteratorType[0] === 'key') {
-        startCondition = ['if', 'data', _iterable.type, `${_iterable.path}{}`]
-
+    if (isMultipleVariable(iteratorType)) {
+      if (isMapIterator(iteratorType, iterable)) {
         iterate = iterable.iterator((dataPoints) => {
-          if (dataPoints.length === 1) {
-            throw new Error(
-              'Error: Attempt to use "for key value" loop with an Array dataset; this is not supported. (Hint: use "for entry" or "for i entry" instead)',
-            )
-          }
-          callback(...([dataPoints[0], dataPoints[1]] as unknown as ITERATE))
-        })
+          callback(...([dataPoints[0], dataPoints[1]] as ITERATE))
+        }, direction)
       } else {
-        startCondition = ['if', 'data', _iterable.type, `${_iterable.path}{}`]
-
-        const _iterator = sandstoneCore.pack.Variable()
+        const _iterator = sandstoneCore.pack.Variable(direction === 'normal' ? -1 : undefined)
 
-        _iterator.set(iterable.size()) // Store the size of the array to the iterator
-
-        continueCondition = _iterator['!='](-1)
+        if (direction === 'reverse') {
+          _iterator.set(iterable.size()) // Store the size of the array to the iterator
+        }
 
         iterate = iterable.iterator((dataPoints) => {
-          _iterator.decrease()
+          if (direction === 'normal') {
+            _iterator.increase()
+          } else {
+            _iterator.decrease()
+          }
 
           if (dataPoints.length === 1) {
-            return callback(...([_iterator, dataPoints[0]] as unknown as ITERATE))
+            return callback(...([_iterator, dataPoints[0]] as ITERATE))
           }
-          return callback(...([_iterator, dataPoints[1]] as unknown as ITERATE))
-        })
+          return callback(...([_iterator, dataPoints[1]] as ITERATE))
+        }, direction)
       }
     } else {
-      startCondition = ['if', 'data', _iterable.type, `${_iterable.path}{}`]
-
       iterate = iterable.iterator((dataPoints) => {
         if (dataPoints.length === 1) {
           return callback(...([dataPoints[0]] as unknown as ITERATE))
@@ -73,16 +79,16 @@ export class ForOfNode<ITERATOR extends ForOfIterator, ITERATE extends ForOfIter
       })
     }
 
-    iterate()
+    const continueCondition = iterable.continue(direction)
 
     super(
       sandstoneCore,
-      [startCondition],
-      () => iterate,
+      continueCondition,
+      iterate,
       () =>
         new IfStatement(
           sandstoneCore,
-          continueCondition || iterable.continue,
+          continueCondition,
           () => new LoopArgument(sandstoneCore.pack),
         ),
     )
@@ -95,10 +101,11 @@ export class ForOfStatement<ITERATOR extends ForOfIterator, ITERATE extends ForO
   constructor(
     protected sandstoneCore: SandstoneCore,
     protected iteratorType: ITERATOR,
-    protected iterable: IterableDataClass,
+    protected direction: 'normal' | 'reverse',
+    protected iterable: IterableDataClass<ITERATOR extends string[] ? ITERATOR[0] extends 'key' ? 'map' : ('list' | 'map') : ('list' | 'map')>,
     protected callback: (...args: ITERATE) => any,
   ) {
-    this.node = new ForOfNode(sandstoneCore, iteratorType, iterable, callback)
+    this.node = new ForOfNode(sandstoneCore, iteratorType, direction, iterable, callback)
   }
 
   protected getNode = () => this.node

package/src/flow/loops/staticAnalysis.ts

@@ -0,0 +1,114 @@
+import type { ConditionNode } from '..'
+import type { Score } from 'sandstone/variables'
+import { ScoreConditionNode } from '../conditions/variables/score'
+import { AndNode } from '../conditions/and'
+import { OrNode } from '../conditions/or'
+import { NotNode } from '../conditions/not'
+
+/**
+ * Parses a Minecraft range string (e.g., "..4", "0..10", "5") and checks if a value satisfies it.
+ */
+function valueMatchesRange(value: number, rangeStr: string): boolean {
+  // Range format: "min..max", "min..", "..max", or exact "N"
+  if (rangeStr.includes('..')) {
+    const [minStr, maxStr] = rangeStr.split('..')
+    const min = minStr !== '' ? parseInt(minStr, 10) : Number.NEGATIVE_INFINITY
+    const max = maxStr !== '' ? parseInt(maxStr, 10) : Number.POSITIVE_INFINITY
+    return value >= min && value <= max
+  }
+  // Exact match
+  return value === parseInt(rangeStr, 10)
+}
+
+/**
+ * Result of static condition analysis.
+ * - `{ canAnalyze: false }` - condition references other variables or can't be analyzed
+ * - `{ canAnalyze: true, result: boolean }` - condition was evaluated statically
+ */
+export type AnalysisResult = { canAnalyze: false } | { canAnalyze: true; result: boolean }
+
+/**
+ * Recursively analyzes a condition node to check if it only references the given score
+ * and evaluates to true/false for the given value.
+ */
+export function analyzeCondition(
+  condition: ConditionNode,
+  targetScore: Score,
+  value: number,
+  negated = false,
+): AnalysisResult {
+  if (condition instanceof ScoreConditionNode) {
+    // ScoreConditionNode.args = [target, objective, 'matches', range]
+    // or for comparisons: [target, objective, operator, otherTarget, otherObjective]
+    const args = condition.args
+
+    if (args.length >= 4 && args[2] === 'matches') {
+      const [target, objective, , rangeStr] = args
+
+      // Check if condition references the target score (and only the target score)
+      if (target !== `${targetScore.target}` || objective !== `${targetScore.objective}`) {
+        return { canAnalyze: false }
+      }
+
+      // Evaluate the range against the value
+      let result = valueMatchesRange(value, rangeStr)
+      if (negated) result = !result
+      return { canAnalyze: true, result }
+    }
+
+    // Score comparison against another score - can't analyze statically
+    return { canAnalyze: false }
+  }
+
+  if (condition instanceof AndNode) {
+    // All conditions must be analyzable and true
+    for (const subCondition of condition.conditions) {
+      const subResult = analyzeCondition(subCondition, targetScore, value, negated)
+      if (!subResult.canAnalyze) return { canAnalyze: false }
+      if (!subResult.result) return { canAnalyze: true, result: false }
+    }
+    return { canAnalyze: true, result: true }
+  }
+
+  if (condition instanceof OrNode) {
+    // At least one condition must be true (all must be analyzable)
+    let anyTrue = false
+    for (const subCondition of condition.conditions) {
+      const subResult = analyzeCondition(subCondition, targetScore, value, negated)
+      if (!subResult.canAnalyze) return { canAnalyze: false }
+      if (subResult.result) anyTrue = true
+    }
+    return { canAnalyze: true, result: anyTrue }
+  }
+
+  if (condition instanceof NotNode) {
+    // Negate the result
+    return analyzeCondition(condition.condition, targetScore, value, !negated)
+  }
+
+  // Unknown condition type - can't analyze
+  return { canAnalyze: false }
+}
+
+/**
+ * Gets a user-friendly location string from a stack trace, filtering out internal files.
+ */
+export function getDeclarationLocation(): string {
+  const stack = new Error().stack
+  const locationMatch = stack?.split('\n').find(line =>
+    line.includes('.ts:') && !line.includes('/loops/') && !line.includes('node_modules'),
+  )
+  return locationMatch?.trim() || 'unknown location'
+}
+
+/**
+ * Warns about a statically false loop condition.
+ */
+export function warnStaticallyFalseCondition(loopType: string, details: string): void {
+  const location = getDeclarationLocation()
+  console.warn(
+    `[Sandstone] Warning: ${loopType} loop condition is statically false (${details}). ` +
+    `The loop body will never execute. If this is intentional, you can ignore this warning.\n` +
+    `  at ${location}`,
+  )
+}

package/src/flow/loops/while.ts

@@ -1,17 +1,20 @@
-import type { SubCommand } from 'sandstone/commands'
 import type { SandstoneCore } from 'sandstone/core'
 import { LoopArgument } from 'sandstone/variables'
 import { IfStatement } from '../if_else'
-import type { ConditionNode } from '..'
+import { conditionToNode, type ConditionNode } from '..'
 import { LoopNode } from '../loop'
 
 export class WhileNode extends LoopNode {
-  constructor(sandstoneCore: SandstoneCore, condition: ConditionNode, callback: () => void) {
-    const _condition = sandstoneCore.pack._.conditionToNode(condition)
+  constructor(
+    sandstoneCore: SandstoneCore,
+    condition: ConditionNode,
+    callback: () => void,
+  ) {
+    const _condition = conditionToNode(condition)
 
     super(
       sandstoneCore,
-      [_condition.getValue().split(' ') as SubCommand],
+      _condition,
       callback,
       () => new IfStatement(sandstoneCore, _condition, () => new LoopArgument(sandstoneCore.pack)),
     )

package/src/flow/switch_case.ts

@@ -1,33 +1,234 @@
 import type { NBTObject } from 'sandstone/arguments'
+import type { DataPointPickClass, MCFunctionNode, SandstoneCore } from 'sandstone/core'
+import { ContainerNode } from 'sandstone/core'
+import type { DataPointClass } from 'sandstone/variables'
+import { Score } from 'sandstone/variables'
+import type { Condition } from './Flow'
 
-export type DefaultType<ValueType extends number | NBTObject> = {
-  cases: CaseStatement<ValueType>[]
+/** A condition callback that receives the switch value and returns a condition */
+export type ConditionCallback<ValueType> = (value: ValueType) => Condition
+
+/** Widen literal types to their base types for better inference */
+type Widen<T> = T extends number ? number : T
+
+/** Static value case */
+type StaticCaseEntry<CheckType> = { type: 'static'; value: Widen<CheckType>; callback: () => any }
+
+/** Condition callback case */
+type ConditionCaseEntry<ValueType> = { type: 'condition'; condition: ConditionCallback<ValueType>; callback: () => any }
+
+/** Either a static or condition case entry */
+type CaseEntry<ValueType, CheckType> = StaticCaseEntry<CheckType> | ConditionCaseEntry<ValueType>
+
+/** Static value case tuple */
+export type StaticCase<CheckType> = readonly ['case', Widen<CheckType>, () => any]
+
+/** Condition callback case tuple */
+export type ConditionCase<ValueType> = readonly ['case', ConditionCallback<ValueType>, () => any]
+
+/** Either a static or condition case */
+export type SwitchCase<ValueType, CheckType> = StaticCase<CheckType> | ConditionCase<ValueType>
+
+export type DefaultType<ValueType extends number | NBTObject, SwitchValueType = unknown> = {
+  entries: CaseEntry<SwitchValueType, ValueType>[]
   default: () => any
 }
 
-export class CaseStatement<ValueType extends number | NBTObject> {
+export class CaseStatement<ValueType extends number | NBTObject, SwitchValueType = unknown> {
   constructor(
-    readonly value: ValueType,
-    readonly callback: () => any,
-    readonly previous?: CaseStatement<ValueType>[],
+    readonly entries: CaseEntry<SwitchValueType, ValueType>[] = [],
   ) {}
 
   /** @internal */
-  getCases = () => (this.previous ? [...this.previous, this] : [this])
+  getStaticCases(): StaticCaseEntry<ValueType>[] {
+    return this.entries.filter((e): e is StaticCaseEntry<ValueType> => e.type === 'static')
+  }
 
   /** @internal */
-  getValue(): readonly ['case', ValueType, () => any] {
-    return ['case', this.value, this.callback]
+  getConditionCases(): ConditionCaseEntry<SwitchValueType>[] {
+    return this.entries.filter((e): e is ConditionCaseEntry<SwitchValueType> => e.type === 'condition')
   }
 
-  case(value: ValueType, callback: () => any) {
-    return new CaseStatement(value, callback, this.getCases())
+  /** Add a static value case */
+  case(value: ValueType, callback: () => any): CaseStatement<ValueType, SwitchValueType>
+
+  /** Add a condition case - checked after static cases fail. Use generic to specify switch value type on first condition: `.case<Score>(v => ...)` */
+  case<T = SwitchValueType>(condition: ConditionCallback<T>, callback: () => any): CaseStatement<ValueType, T>
+
+  case<T = SwitchValueType>(
+    valueOrCondition: ValueType | ConditionCallback<T>,
+    callback: () => any,
+  ) {
+    if (typeof valueOrCondition === 'function') {
+      return new CaseStatement<ValueType, T>([
+        ...this.entries as CaseEntry<T, ValueType>[],
+        { type: 'condition', condition: valueOrCondition, callback },
+      ])
+    }
+    return new CaseStatement<ValueType, SwitchValueType>([
+      ...this.entries,
+      { type: 'static', value: valueOrCondition as Widen<ValueType>, callback },
+    ])
   }
 
-  default(callback: () => any) {
+  default(callback: () => any): DefaultType<ValueType, SwitchValueType> {
     return {
-      cases: this.getCases(),
+      entries: this.entries,
       default: callback,
     }
   }
 }
+
+/**
+ * AST node representing a switch statement.
+ * Transformed into MCFunctions by SwitchTransformationVisitor during save().
+ */
+export class SwitchNode extends ContainerNode {
+  parentMCFunction: MCFunctionNode
+
+  constructor(
+    sandstoneCore: SandstoneCore,
+    public value: DataPointClass | DataPointPickClass | Score,
+    public staticCases: StaticCaseNode[],
+    public conditionCases: ConditionCaseNode[],
+    public defaultCase: DefaultCaseNode | undefined,
+  ) {
+    super(sandstoneCore)
+    this.parentMCFunction = sandstoneCore.getCurrentMCFunctionOrThrow()
+
+    // Generate case bodies within switch context
+    this.parentMCFunction.enterContext(this)
+    for (const caseNode of [...staticCases, ...conditionCases]) {
+      this.parentMCFunction.enterContext(caseNode)
+      caseNode.callback()
+      this.parentMCFunction.exitContext()
+    }
+    if (defaultCase) {
+      this.parentMCFunction.enterContext(defaultCase)
+      defaultCase.callback()
+      this.parentMCFunction.exitContext()
+    }
+    this.parentMCFunction.exitContext()
+  }
+
+  getValue = () => {
+    throw new Error('SwitchNode must be transformed by SwitchTransformationVisitor')
+  }
+}
+
+/**
+ * AST node representing a static value case in a switch statement.
+ */
+export class StaticCaseNode extends ContainerNode {
+  constructor(
+    sandstoneCore: SandstoneCore,
+    public value: number | NBTObject,
+    public callback: () => any,
+  ) {
+    super(sandstoneCore)
+  }
+
+  getValue = () => null
+}
+
+/**
+ * AST node representing a condition-based case in a switch statement.
+ */
+export class ConditionCaseNode extends ContainerNode {
+  constructor(
+    sandstoneCore: SandstoneCore,
+    public condition: ConditionCallback<any>,
+    public callback: () => any,
+  ) {
+    super(sandstoneCore)
+  }
+
+  getValue = () => null
+}
+
+/**
+ * AST node representing the default case in a switch statement.
+ */
+export class DefaultCaseNode extends ContainerNode {
+  constructor(
+    sandstoneCore: SandstoneCore,
+    public callback: () => any,
+  ) {
+    super(sandstoneCore)
+  }
+
+  getValue = () => null
+}
+
+function isConditionCase<ValueType>(
+  c: ConditionCallback<ValueType> | NBTObject,
+): c is ConditionCallback<ValueType> {
+  return typeof c === 'function'
+}
+
+export function executeSwitch<
+  ValueType extends DataPointClass | DataPointPickClass | Score,
+  CheckType extends ValueType extends Score ? number : NBTObject,
+>(
+  sandstoneCore: SandstoneCore,
+  value: ValueType,
+  _cases: SwitchCase<ValueType, CheckType>[] | [...SwitchCase<ValueType, CheckType>[], ['default', () => any]] | CaseStatement<CheckType, ValueType> | DefaultType<CheckType, ValueType>,
+) {
+  let staticCaseEntries: StaticCaseEntry<CheckType>[] = []
+  let conditionCaseEntries: ConditionCaseEntry<ValueType>[] = []
+
+  let _default: ['default', () => {}] | undefined
+
+  // Parse cases from the various input formats
+  if (_cases instanceof CaseStatement) {
+    staticCaseEntries = _cases.getStaticCases()
+    conditionCaseEntries = _cases.getConditionCases() as ConditionCaseEntry<ValueType>[]
+  } else if (Array.isArray(_cases)) {
+    for (const _case of _cases) {
+      if (_case[0] === 'default') {
+        _default = _case
+        continue
+      }
+      const [, condition, callback] = _case
+
+      if (isConditionCase(condition)) {
+        conditionCaseEntries.push({ type: 'condition' as const, condition, callback })
+      } else {
+        staticCaseEntries.push({ type: 'static' as const, value: condition, callback })
+      }
+    }
+  } else {
+    for (const _case of _cases.entries) {
+      if (_case.type === 'condition') {
+        conditionCaseEntries.push(_case)
+      } else {
+        staticCaseEntries.push(_case)
+      }
+    }
+    if (_cases.default) {
+      _default = ['default', _cases.default]
+    }
+  }
+
+  // Create case nodes
+  const staticCaseNodes = staticCaseEntries.map(
+    (c) => new StaticCaseNode(sandstoneCore, c.value, c.callback),
+  )
+  const conditionCaseNodes = conditionCaseEntries.map(
+    (c) => new ConditionCaseNode(sandstoneCore, c.condition, c.callback),
+  )
+  const defaultCaseNode = _default
+    ? new DefaultCaseNode(sandstoneCore, _default[1])
+    : undefined
+
+  // Create SwitchNode (commits to current MCFunction context)
+  // The node constructor executes callbacks to populate case body nodes
+  // SwitchTransformationVisitor transforms this into MCFunctions during save()
+  new SwitchNode(
+    sandstoneCore,
+    value,
+    staticCaseNodes,
+    conditionCaseNodes,
+    defaultCaseNode,
+  )
+}