stone-lang 0.1.0

package/frontend/analysis/livenessAnalyzer.js

@@ -0,0 +1,568 @@
+/**
+ * Liveness Analyzer for Stone
+ *
+ * Performs backward dataflow analysis to determine the last use of each variable.
+ * Stone's semantics enable precise analysis:
+ * - Immutable bindings → values never change after definition
+ * - No shadowing → each name = one value in scope
+ * - Whole-program analysis → we can see all uses at compile time
+ *
+ * Output is backend-agnostic, reusable for:
+ * - JS VM: CLEAR_LOCAL opcode emission
+ * - WASM codegen: Linear memory management
+ * - C codegen: Stack allocation decisions
+ *
+ * @example
+ * const analyzer = new LivenessAnalyzer();
+ * const info = analyzer.analyze(ast);
+ * // info.bindings: Map of name → binding metadata
+ * // info.isLastUse(name, node): Check if node is the last use of variable
+ */
+
+/**
+ * @typedef {Object} BindingInfo
+ * @property {string} name - Variable name
+ * @property {string} scope - Scope identifier (e.g., "function:main", "block:1")
+ * @property {Object} definedAt - Location where the binding is defined
+ * @property {Object|null} lastUseAt - Location of the last use (null if never used)
+ * @property {Array} uses - Array of all use locations
+ * @property {boolean} escapes - Whether the variable escapes via closure
+ * @property {boolean} canStackAlloc - Whether safe for stack allocation
+ * @property {string} type - Type of value if known
+ */
+
+/**
+ * @typedef {Object} LivenessInfo
+ * @property {Map<string, BindingInfo>} bindings - Map of binding key to binding info
+ * @property {function(string, Object): boolean} isLastUse - Check if a node is the last use
+ * @property {function(Object): string|null} getLastUseName - Get variable name if this is its last use
+ */
+
+export class LivenessAnalyzer {
+  constructor() {
+    this.bindings = new Map(); // key -> BindingInfo
+    this.currentScope = [];
+    this.scopeCounter = 0;
+    this.lastUseMap = new Map(); // nodeId -> { name, scopeKey }
+  }
+
+  /**
+   * Generate a unique key for a binding
+   * @param {string} name - Variable name
+   * @param {string} scope - Scope identifier
+   * @returns {string} Unique key
+   */
+  _bindingKey(name, scope) {
+    return `${scope}:${name}`;
+  }
+
+  /**
+   * Get current scope identifier
+   * @returns {string}
+   */
+  _currentScopeId() {
+    return this.currentScope.length > 0
+      ? this.currentScope[this.currentScope.length - 1]
+      : 'global';
+  }
+
+  /**
+   * Generate a node ID for tracking last uses
+   * @param {Object} node - AST node
+   * @returns {string}
+   */
+  _nodeId(node) {
+    if (!node) return 'unknown';
+    const loc = node.location || node.loc || {};
+    return `${loc.start?.line || 0}:${loc.start?.column || 0}:${node.type || 'node'}`;
+  }
+
+  /**
+   * Enter a new scope
+   * @param {string} type - Scope type (function, block, loop, etc.)
+   * @param {string} name - Optional scope name
+   */
+  _enterScope(type, name = '') {
+    const scopeId = `${type}:${name || this.scopeCounter++}`;
+    this.currentScope.push(scopeId);
+  }
+
+  /**
+   * Exit current scope
+   */
+  _exitScope() {
+    this.currentScope.pop();
+  }
+
+  /**
+   * Record a binding definition
+   * @param {string} name - Variable name
+   * @param {Object} node - AST node where it's defined
+   * @param {string} type - Optional type annotation
+   */
+  _recordDefinition(name, node, type = 'any') {
+    const scope = this._currentScopeId();
+    const key = this._bindingKey(name, scope);
+
+    const loc = node.location || node.loc || {};
+    this.bindings.set(key, {
+      name,
+      scope,
+      definedAt: {
+        line: loc.start?.line || 0,
+        column: loc.start?.column || 0,
+      },
+      lastUseAt: null,
+      uses: [],
+      escapes: false,
+      canStackAlloc: true,
+      type,
+    });
+  }
+
+  /**
+   * Record a variable use
+   * @param {string} name - Variable name
+   * @param {Object} node - AST node where it's used
+   */
+  _recordUse(name, node) {
+    // Find the binding in current or enclosing scopes
+    let key = null;
+    for (let i = this.currentScope.length - 1; i >= 0; i--) {
+      const tryKey = this._bindingKey(name, this.currentScope[i]);
+      if (this.bindings.has(tryKey)) {
+        key = tryKey;
+        break;
+      }
+    }
+
+    // Check global scope
+    if (!key) {
+      const globalKey = this._bindingKey(name, 'global');
+      if (this.bindings.has(globalKey)) {
+        key = globalKey;
+      }
+    }
+
+    if (!key) return; // Unknown variable (might be builtin or external)
+
+    const binding = this.bindings.get(key);
+    const loc = node.location || node.loc || {};
+    const useInfo = {
+      line: loc.start?.line || 0,
+      column: loc.start?.column || 0,
+    };
+
+    binding.uses.push(useInfo);
+    binding.lastUseAt = useInfo; // Will be overwritten by later uses
+
+    // Track for isLastUse lookup
+    const nodeId = this._nodeId(node);
+    this.lastUseMap.set(nodeId, { name, scopeKey: key, binding });
+  }
+
+  /**
+   * Mark a binding as escaping (captured by closure)
+   * @param {string} name - Variable name
+   */
+  _markEscapes(name) {
+    // Find the binding in enclosing scopes
+    for (let i = this.currentScope.length - 1; i >= 0; i--) {
+      const key = this._bindingKey(name, this.currentScope[i]);
+      if (this.bindings.has(key)) {
+        const binding = this.bindings.get(key);
+        binding.escapes = true;
+        binding.canStackAlloc = false;
+        return;
+      }
+    }
+
+    // Check global scope
+    const globalKey = this._bindingKey(name, 'global');
+    if (this.bindings.has(globalKey)) {
+      const binding = this.bindings.get(globalKey);
+      binding.escapes = true;
+      binding.canStackAlloc = false;
+    }
+  }
+
+  /**
+   * Analyze an AST and return liveness information
+   * @param {Object} ast - The AST to analyze
+   * @returns {LivenessInfo} Liveness information
+   */
+  analyze(ast) {
+    // Reset state
+    this.bindings.clear();
+    this.currentScope = [];
+    this.scopeCounter = 0;
+    this.lastUseMap.clear();
+
+    // Phase 1: Collect all definitions and uses
+    this._collectDefinitionsAndUses(ast);
+
+    // Phase 2: Finalize last-use information
+    // The lastUseMap now contains all uses, but we need to keep only the actual last uses
+    const finalLastUseMap = new Map();
+    for (const binding of this.bindings.values()) {
+      if (binding.uses.length > 0) {
+        // The last use is the one with the highest line/column
+        const lastUse = binding.uses[binding.uses.length - 1];
+        binding.lastUseAt = lastUse;
+      }
+    }
+
+    // Update lastUseMap to only include actual last uses
+    for (const [nodeId, info] of this.lastUseMap) {
+      const binding = info.binding;
+      if (binding && binding.uses.length > 0) {
+        const lastUse = binding.lastUseAt;
+        const nodeUse = this._nodeIdToLocation(nodeId);
+        if (nodeUse.line === lastUse.line && nodeUse.column === lastUse.column) {
+          finalLastUseMap.set(nodeId, info);
+        }
+      }
+    }
+    this.lastUseMap = finalLastUseMap;
+
+    // Create the result object
+    const bindings = new Map(this.bindings);
+    const lastUseMap = new Map(this.lastUseMap);
+
+    return {
+      bindings,
+
+      /**
+       * Check if a node is the last use of a variable
+       * @param {string} name - Variable name
+       * @param {Object} node - AST node to check
+       * @returns {boolean}
+       */
+      isLastUse: (name, node) => {
+        const nodeId = this._nodeId(node);
+        const info = lastUseMap.get(nodeId);
+        if (!info) return false;
+        if (info.name !== name) return false;
+
+        // Don't clear if the variable escapes
+        const binding = info.binding;
+        if (binding && binding.escapes) return false;
+
+        return true;
+      },
+
+      /**
+       * Get the variable name if this node is its last use
+       * @param {Object} node - AST node to check
+       * @returns {string|null} Variable name or null
+       */
+      getLastUseName: (node) => {
+        const nodeId = this._nodeId(node);
+        const info = lastUseMap.get(nodeId);
+        if (!info) return null;
+
+        // Don't clear if the variable escapes
+        const binding = info.binding;
+        if (binding && binding.escapes) return null;
+
+        return info.name;
+      },
+    };
+  }
+
+  /**
+   * Parse a node ID back to a location
+   * @param {string} nodeId
+   * @returns {{line: number, column: number}}
+   */
+  _nodeIdToLocation(nodeId) {
+    const parts = nodeId.split(':');
+    return {
+      line: parseInt(parts[0], 10) || 0,
+      column: parseInt(parts[1], 10) || 0,
+    };
+  }
+
+  /**
+   * Traverse the AST and collect all definitions and uses
+   * @param {Object} node - AST node
+   */
+  _collectDefinitionsAndUses(node) {
+    if (!node || typeof node !== 'object') return;
+
+    switch (node.type) {
+      case 'Program':
+        this._enterScope('global', 'main');
+        if (node.body) {
+          for (const stmt of node.body) {
+            this._collectDefinitionsAndUses(stmt);
+          }
+        }
+        this._exitScope();
+        break;
+
+      case 'BindingStatement':
+      case 'Declaration':
+        // Record the definition
+        if (node.name) {
+          const typeStr = node.typeAnnotation?.name || 'any';
+          this._recordDefinition(node.name, node, typeStr);
+        }
+        // Analyze the value expression
+        if (node.value) {
+          this._collectDefinitionsAndUses(node.value);
+        }
+        break;
+
+      case 'FunctionDeclaration':
+      case 'FunctionExpression':
+      case 'ArrowFunction':
+        // Record function name if it exists
+        if (node.name) {
+          this._recordDefinition(node.name, node, 'function');
+        }
+
+        // Enter function scope
+        this._enterScope('function', node.name || '');
+
+        // Record parameters as definitions
+        if (node.params) {
+          for (const param of node.params) {
+            const paramName = typeof param === 'string' ? param : param.name;
+            if (paramName) {
+              const typeStr = param.typeAnnotation?.name || 'any';
+              this._recordDefinition(paramName, param.node || node, typeStr);
+            }
+          }
+        }
+
+        // Check for captured variables (closures)
+        this._checkForClosures(node.body);
+
+        // Analyze function body
+        if (node.body) {
+          this._collectDefinitionsAndUses(node.body);
+        }
+
+        this._exitScope();
+        break;
+
+      case 'BlockExpression':
+      case 'Block':
+        this._enterScope('block');
+        if (node.body) {
+          for (const stmt of node.body) {
+            this._collectDefinitionsAndUses(stmt);
+          }
+        }
+        if (node.result) {
+          this._collectDefinitionsAndUses(node.result);
+        }
+        this._exitScope();
+        break;
+
+      case 'IfExpression':
+      case 'ConditionalExpression':
+        this._collectDefinitionsAndUses(node.condition || node.test);
+        this._collectDefinitionsAndUses(node.consequent || node.then);
+        this._collectDefinitionsAndUses(node.alternate || node.else);
+        break;
+
+      case 'ForExpression':
+      case 'ForLoop':
+        this._enterScope('loop');
+        // Loop variable
+        if (node.variable) {
+          this._recordDefinition(node.variable, node, 'num');
+        }
+        // Initial state
+        if (node.init) {
+          this._collectDefinitionsAndUses(node.init);
+        }
+        // Iterable
+        if (node.iterable) {
+          this._collectDefinitionsAndUses(node.iterable);
+        }
+        // Body
+        if (node.body) {
+          this._collectDefinitionsAndUses(node.body);
+        }
+        this._exitScope();
+        break;
+
+      case 'WhileLoop':
+        this._enterScope('loop');
+        if (node.condition) {
+          this._collectDefinitionsAndUses(node.condition);
+        }
+        if (node.body) {
+          this._collectDefinitionsAndUses(node.body);
+        }
+        this._exitScope();
+        break;
+
+      case 'Identifier':
+        // This is a variable use
+        if (node.name) {
+          this._recordUse(node.name, node);
+        }
+        break;
+
+      case 'CallExpression':
+      case 'Call':
+        // Analyze callee and arguments
+        this._collectDefinitionsAndUses(node.callee || node.func);
+        if (node.arguments || node.args) {
+          for (const arg of node.arguments || node.args) {
+            this._collectDefinitionsAndUses(arg);
+          }
+        }
+        break;
+
+      case 'BinaryExpression':
+      case 'BinaryOp':
+        this._collectDefinitionsAndUses(node.left);
+        this._collectDefinitionsAndUses(node.right);
+        break;
+
+      case 'UnaryExpression':
+      case 'UnaryOp':
+        this._collectDefinitionsAndUses(node.argument || node.operand);
+        break;
+
+      case 'MemberExpression':
+      case 'PropertyAccess':
+        this._collectDefinitionsAndUses(node.object);
+        // Don't record property name as a use
+        break;
+
+      case 'IndexExpression':
+      case 'IndexAccess':
+        this._collectDefinitionsAndUses(node.object || node.array);
+        this._collectDefinitionsAndUses(node.index);
+        break;
+
+      case 'ArrayLiteral':
+      case 'ArrayExpression':
+        if (node.elements) {
+          for (const elem of node.elements) {
+            this._collectDefinitionsAndUses(elem);
+          }
+        }
+        break;
+
+      case 'ObjectLiteral':
+      case 'ObjectExpression':
+      case 'RecordLiteral':
+        if (node.properties || node.fields) {
+          for (const prop of node.properties || node.fields) {
+            // Only analyze value, not key
+            this._collectDefinitionsAndUses(prop.value);
+          }
+        }
+        break;
+
+      case 'ReturnStatement':
+        if (node.value) {
+          this._collectDefinitionsAndUses(node.value);
+        }
+        break;
+
+      case 'ExpressionStatement':
+        this._collectDefinitionsAndUses(node.expression);
+        break;
+
+      default:
+        // Generic traversal for unknown node types
+        for (const key of Object.keys(node)) {
+          if (key === 'location' || key === 'loc' || key === 'type') continue;
+          const value = node[key];
+          if (Array.isArray(value)) {
+            for (const item of value) {
+              if (item && typeof item === 'object') {
+                this._collectDefinitionsAndUses(item);
+              }
+            }
+          } else if (value && typeof value === 'object') {
+            this._collectDefinitionsAndUses(value);
+          }
+        }
+    }
+  }
+
+  /**
+   * Check for variables that are captured by closures
+   * @param {Object} node - AST node to check
+   */
+  _checkForClosures(node) {
+    if (!node || typeof node !== 'object') return;
+
+    // If we find a function inside, check for captured variables
+    if (node.type === 'FunctionExpression' ||
+        node.type === 'FunctionDeclaration' ||
+        node.type === 'ArrowFunction') {
+      // Collect all identifiers used in this function
+      const usedIds = this._collectIdentifiers(node.body);
+
+      // Mark any that are from outer scopes as escaping
+      for (const name of usedIds) {
+        // Check if it's defined in an outer scope (not in this function's params)
+        const isParam = node.params?.some(p =>
+          (typeof p === 'string' ? p : p.name) === name
+        );
+        if (!isParam) {
+          this._markEscapes(name);
+        }
+      }
+    }
+
+    // Continue checking child nodes
+    for (const key of Object.keys(node)) {
+      if (key === 'location' || key === 'loc' || key === 'type') continue;
+      const value = node[key];
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          if (item && typeof item === 'object') {
+            this._checkForClosures(item);
+          }
+        }
+      } else if (value && typeof value === 'object') {
+        this._checkForClosures(value);
+      }
+    }
+  }
+
+  /**
+   * Collect all identifier names used in a subtree
+   * @param {Object} node - AST node
+   * @returns {Set<string>} Set of identifier names
+   */
+  _collectIdentifiers(node) {
+    const identifiers = new Set();
+
+    const visit = (n) => {
+      if (!n || typeof n !== 'object') return;
+
+      if (n.type === 'Identifier' && n.name) {
+        identifiers.add(n.name);
+      }
+
+      for (const key of Object.keys(n)) {
+        if (key === 'location' || key === 'loc' || key === 'type') continue;
+        const value = n[key];
+        if (Array.isArray(value)) {
+          for (const item of value) {
+            visit(item);
+          }
+        } else if (value && typeof value === 'object') {
+          visit(value);
+        }
+      }
+    };
+
+    visit(node);
+    return identifiers;
+  }
+}
+
+export default LivenessAnalyzer;