semantifold 0.12.0 → 0.13.0

package/src/frontends/javascript-typescript.js

@@ -6,7 +6,7 @@ import {missingType, parseFailure, SemantifoldDiagnostic, unsupportedSyntax} fro
 import {blockReferencesProtectedEntry} from "../semantic/effects.js"
 import {locationFromOffsets, moduleLocation} from "../semantic/location.js"
 import {withAdaptedOperation} from "../semantic/operators.js"
-import {withParserRanges} from "../semantic/provenance.js"
+import {setParserRanges, withParserRanges} from "../semantic/provenance.js"
 import {hasOnlyUnicodeScalars, scalarType} from "../semantic/scalars.js"
 import {isTask034ResourceProbe} from "../semantic/capabilities.js"
 import {hasExactEffectSupport} from "../backends/effects.js"
@@ -16,7 +16,7 @@ import {documentedValueType, instantiatedRecordFieldType, iterationBindingType,
 /** @typedef {NonNullable<import("@babel/parser").ParseResult<import("@babel/types").File>["tokens"]>[number]} BabelToken */
 /** @typedef {{byStart: Map<number, BabelToken>, tokens: BabelToken[]}} BabelTokenIndex */
 /** @typedef {{name: string, nameLocation: import("../semantic/types.js").SourceLocation, parameters: import("../semantic/types.js").Parameter[], returnType: import("../semantic/types.js").SemanticFunctionReturnType, typeParameters?: import("../semantic/types.js").TypeParameter[], location: import("../semantic/types.js").SourceLocation}} JavaScriptFunctionSignature */
-/** @typedef {{bindings: Map<string, import("../semantic/types.js").SemanticBindingType>, classes: Map<string, import("../semantic/types.js").ClassDeclaration>, currentClass?: import("../semantic/types.js").ClassDeclaration, errors: Map<string, import("../semantic/types.js").ErrorDeclaration>, errorNames: Map<string, import("../semantic/types.js").ErrorDeclaration>, functions: Map<string, JavaScriptFunctionSignature>, lexicalValueNames?: Set<string>, orderedMapDeclarations?: Set<object>, recordNames: Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>, records: Map<string, import("../semantic/types.js").RecordDeclaration>, returnType?: import("../semantic/types.js").SemanticFunctionReturnType, typeParameters?: Map<string, import("../semantic/types.js").TypeParameter>, valueRecordNames: Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration>}} JavaScriptConversionContext */
+/** @typedef {{bindings: Map<string, import("../semantic/types.js").SemanticBindingType>, catchBindingNames?: Set<string>, catchBindingNodes?: Map<string, import("../semantic/types.js").CatchBinding>, classes: Map<string, import("../semantic/types.js").ClassDeclaration>, currentClass?: import("../semantic/types.js").ClassDeclaration, errors: Map<string, import("../semantic/types.js").ErrorDeclaration>, errorNames: Map<string, import("../semantic/types.js").ErrorDeclaration>, functions: Map<string, JavaScriptFunctionSignature>, lexicalValueNames?: Set<string>, orderedMapDeclarations?: Set<object>, recordNames: Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>, records: Map<string, import("../semantic/types.js").RecordDeclaration>, returnType?: import("../semantic/types.js").SemanticFunctionReturnType, typeParameters?: Map<string, import("../semantic/types.js").TypeParameter>, valueRecordNames: Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration>}} JavaScriptConversionContext */
 
 /** @type {WeakMap<object, BabelTokenIndex>} */
 const nodeTokens = new WeakMap()
@@ -966,12 +966,23 @@ function convertStatement(node, language, filename, source, canonicalZeroRequire
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
  * @param {JavaScriptConversionContext} context - Typed lexical context.
- * @returns {import("../semantic/types.js").RaiseStatement} Semantic raise.
+ * @returns {import("../semantic/types.js").RaiseStatement | import("../semantic/types.js").RethrowStatement} Semantic raise or rethrow.
  */
 function convertTypedThrow(node, language, filename, source, context) {
   const location = nodeLocation(node, filename, source)
   const argument = node.argument
 
+  if (argument?.type == "Identifier" && context.catchBindingNames?.has(argument.name) && context.bindings.get(argument.name)?.kind == "ErrorType") {
+    const bindingNode = context.catchBindingNodes?.get(argument.name)
+
+    if (!bindingNode) return unsupportedSyntax(language, "throw of a catch binding without an exact handler binding", location)
+    return withParserRanges({
+      binding: argument.name,
+      bindingNode,
+      kind: /** @type {const} */ ("RethrowStatement"),
+      location
+    }, {keyword: tokenLocation(node, "throw", node.start ?? 0, argument.start ?? node.end ?? source.length, filename, source)})
+  }
   if (!argument || argument.type != "NewExpression" || argument.callee.type != "Identifier" ||
     context.bindings.has(argument.callee.name) || !context.errorNames.has(argument.callee.name) || argument.arguments.length != 1 ||
     argument.arguments[0].type == "SpreadElement" || argument.arguments[0].type == "ArgumentPlaceholder" ||
@@ -1006,53 +1017,134 @@ function convertTypedThrow(node, language, filename, source, context) {
 function convertTypedTry(node, language, filename, source, canonicalZeroRequired, context) {
   const location = nodeLocation(node, filename, source)
 
-  if (node.finalizer || !node.handler || node.handler.param?.type != "Identifier" || node.handler.body.directives.length > 0) {
-    return unsupportedSyntax(language, "try without one explicit guarded catch", location)
-  }
-  const binding = node.handler.param
-  const guard = node.handler.body.body[0]
-
-  if (!guard || guard.type != "IfStatement" || guard.alternate || guard.test.type != "UnaryExpression" ||
-    guard.test.operator != "!" || guard.test.argument.type != "BinaryExpression" || guard.test.argument.operator != "instanceof" ||
-    guard.test.argument.left.type != "Identifier" || guard.test.argument.left.name != binding.name ||
-    guard.test.argument.right.type != "Identifier" || guard.test.argument.right.name == binding.name ||
-    context.bindings.has(guard.test.argument.right.name) || !context.errorNames.has(guard.test.argument.right.name) ||
-    guard.consequent.type != "BlockStatement" || guard.consequent.body.length != 1 || guard.consequent.directives.length > 0 ||
-    guard.consequent.body[0].type != "ThrowStatement" || guard.consequent.body[0].argument?.type != "Identifier" ||
-    guard.consequent.body[0].argument.name != binding.name) {
-    return unsupportedSyntax(language, "catch without exact instanceof guard and unmatched rethrow", nodeLocation(guard ?? node.handler, filename, source))
-  }
-  const declaration = /** @type {import("../semantic/types.js").ErrorDeclaration} */ (context.errorNames.get(guard.test.argument.right.name))
-  const caughtTypeLocation = identifierLocation(guard.test.argument.right, filename, source)
-  const catchType = withParserRanges({
-    declarationId: /** @type {string} */ (declaration.id),
-    kind: /** @type {const} */ ("ErrorType")
-  }, {type: caughtTypeLocation})
+  if (!node.handler) {
+    if (!node.finalizer) return unsupportedSyntax(language, "try without an explicit guarded catch", location)
+    const bodyContext = {...context, bindings: new Map(context.bindings)}
+    const semantic = /** @type {import("../semantic/types.js").TryStatement} */ (withParserRanges({
+      body: convertBlock(node.block, language, filename, source, canonicalZeroRequired, bodyContext),
+      handlers: [],
+      kind: /** @type {const} */ ("TryStatement"),
+      location
+    }, {
+      try: tokenLocation(node, "try", node.start ?? 0, node.block.start ?? node.end ?? source.length, filename, source)
+    }))
+
+    semantic.finallyBody = convertBlock(node.finalizer.body, language, filename, source, canonicalZeroRequired,
+      {...context, bindings: new Map(context.bindings)}, nodeLocation(node.finalizer, filename, source))
+    setParserRanges(semantic, {finally: nodeLocation(node.finalizer, filename, source),
+      try: tokenLocation(node, "try", node.start ?? 0, node.block.start ?? node.end ?? source.length, filename, source)})
+    return semantic
+  }
+  /** @type {import("../semantic/types.js").CatchHandler[]} */
+  const handlers = []
+  const seenHandlerNames = new Set(context.catchBindingNames ?? [])
   const bodyContext = {...context, bindings: new Map(context.bindings)}
-  const catchContext = {...context, bindings: new Map(context.bindings)}
 
-  catchContext.bindings.set(binding.name, catchType)
-  const catchStatements = node.handler.body.body.slice(1)
+  // JavaScript has no sibling catch clauses, so the exact native profile for ordered
+  // multi-catch is a guarded dispatch chain: each unmatched guard rethrows into the next
+  // clause. The chain flattens back to one ordered handler list here.
+  /** @type {import("@babel/types").CatchClause | undefined} */
+  let clause = node.handler
+
+  while (clause) {
+    const binding = clause.param
+
+    if (binding?.type != "Identifier" || clause.body.directives.length > 0) {
+      return unsupportedSyntax(language, "catch without one explicit binding", nodeLocation(clause, filename, source))
+    }
+    if (seenHandlerNames.has(binding.name)) {
+      return unsupportedSyntax(language, `catch binding '${binding.name}' shadows an outer handler binding`,
+        identifierLocation(binding, filename, source))
+    }
+    seenHandlerNames.add(binding.name)
+
+    /** @type {import("@babel/types").Statement | undefined} */
+    const guard = clause.body.body[0]
+
+    if (!guard || guard.type != "IfStatement" || guard.test.type != "UnaryExpression" ||
+      guard.test.operator != "!" || guard.test.argument.type != "BinaryExpression" || guard.test.argument.operator != "instanceof" ||
+      guard.test.argument.left.type != "Identifier" || guard.test.argument.left.name != binding.name ||
+      guard.test.argument.right.type != "Identifier" || guard.test.argument.right.name == binding.name ||
+      context.bindings.has(guard.test.argument.right.name) || !context.errorNames.has(guard.test.argument.right.name) ||
+      guard.consequent.type != "BlockStatement" || guard.consequent.body.length != 1 || guard.consequent.directives.length > 0 ||
+      (guard.alternate && (guard.alternate.type != "BlockStatement" || guard.alternate.directives.length > 0))) {
+      return unsupportedSyntax(language, "catch without exact instanceof guard", nodeLocation(guard ?? clause, filename, source))
+    }
+
+    /** @type {import("@babel/types").Statement | undefined} */
+    const dispatch = guard.consequent.body[0]
+    /** @type {import("@babel/types").CatchClause | undefined} */
+    let nextClause = undefined
+    /** @type {import("@babel/types").Statement[]} */
+    let handlerBodyStatements = clause.body.body.slice(1)
+    let handlerBodyLocation = nodeLocation(clause.body, filename, source)
+
+    if (dispatch.type == "TryStatement") {
+      if (dispatch.finalizer || !dispatch.handler || dispatch.block.body.length != 1 || dispatch.block.body[0].type != "ThrowStatement" ||
+        dispatch.block.body[0].argument?.type != "Identifier" || dispatch.block.body[0].argument.name != binding.name ||
+        !guard.alternate || clause.body.body.length != 1) {
+        return unsupportedSyntax(language, "catch guard dispatch without exact rethrow of its own binding",
+          nodeLocation(dispatch, filename, source))
+      }
+      nextClause = dispatch.handler
+      handlerBodyStatements = /** @type {import("@babel/types").BlockStatement} */ (guard.alternate).body
+      handlerBodyLocation = nodeLocation(guard.alternate, filename, source)
+    } else if (dispatch.type != "ThrowStatement" || dispatch.argument?.type != "Identifier" || dispatch.argument.name != binding.name) {
+      return unsupportedSyntax(language, "catch guard without exact unmatched rethrow", nodeLocation(dispatch, filename, source))
+    } else if (guard.alternate) {
+      if (clause.body.body.length != 1) {
+        return unsupportedSyntax(language, "catch guard dispatch without exact rethrow of its own binding",
+          nodeLocation(guard.alternate, filename, source))
+      }
+      handlerBodyStatements = /** @type {import("@babel/types").BlockStatement} */ (guard.alternate).body
+      handlerBodyLocation = nodeLocation(guard.alternate, filename, source)
+    }
 
-  return withParserRanges({
-    body: convertBlock(node.block, language, filename, source, canonicalZeroRequired, bodyContext),
-    catchBinding: withParserRanges({
+    const declaration = /** @type {import("../semantic/types.js").ErrorDeclaration} */ (context.errorNames.get(guard.test.argument.right.name))
+    const caughtTypeLocation = identifierLocation(guard.test.argument.right, filename, source)
+    const catchType = withParserRanges({
+      declarationId: /** @type {string} */ (declaration.id),
+      kind: /** @type {const} */ ("ErrorType")
+    }, {type: caughtTypeLocation})
+    const catchContext = {...context, bindings: new Map(context.bindings), catchBindingNames: new Set(seenHandlerNames),
+      catchBindingNodes: new Map(context.catchBindingNodes)}
+
+    catchContext.bindings.set(binding.name, catchType)
+    const catchBindingNode = withParserRanges({
       kind: /** @type {const} */ ("CatchBinding"),
       location: identifierLocation(binding, filename, source),
       mutable: /** @type {const} */ (false),
       name: binding.name,
       type: catchType
-    }, {name: identifierLocation(binding, filename, source)}),
-    catchBody: convertBlock(catchStatements, language, filename, source, canonicalZeroRequired, catchContext,
-      nodeLocation(node.handler.body, filename, source)),
-    catchType,
+    }, {name: identifierLocation(binding, filename, source)})
+
+    catchContext.catchBindingNodes.set(binding.name, catchBindingNode)
+    handlers.push(withParserRanges({
+      catchBinding: catchBindingNode,
+      catchBody: convertBlock(handlerBodyStatements, language, filename, source, canonicalZeroRequired, catchContext,
+        handlerBodyLocation),
+      catchType,
+      kind: /** @type {const} */ ("CatchHandler"),
+      location: nodeLocation(clause, filename, source)
+    }, {catch: tokenLocation(clause, "catch", clause.start ?? 0, binding.start ?? clause.end ?? source.length, filename, source)}))
+    clause = nextClause
+  }
+  const semantic = /** @type {import("../semantic/types.js").TryStatement} */ (withParserRanges({
+    body: convertBlock(node.block, language, filename, source, canonicalZeroRequired, bodyContext),
+    handlers,
     kind: /** @type {const} */ ("TryStatement"),
     location
   }, {
-    catch: tokenLocation(node.handler, "catch", node.handler.start ?? 0, binding.start ?? node.handler.end ?? source.length, filename, source),
-    guard: nodeLocation(guard, filename, source),
     try: tokenLocation(node, "try", node.start ?? 0, node.block.start ?? node.end ?? source.length, filename, source)
-  })
+  }))
+
+  if (node.finalizer) {
+    semantic.finallyBody = convertBlock(node.finalizer.body, language, filename, source, canonicalZeroRequired,
+      {...context, bindings: new Map(context.bindings)}, nodeLocation(node.finalizer, filename, source))
+    setParserRanges(semantic, {finally: nodeLocation(node.finalizer, filename, source),
+      try: tokenLocation(node, "try", node.start ?? 0, node.block.start ?? node.end ?? source.length, filename, source)})
+  }
+  return semantic
 }
 
 /**

package/src/frontends/php.js

@@ -6,7 +6,7 @@ import {missingType, parseFailure, unsupportedSyntax} from "../diagnostic.js"
 import {blockReferencesProtectedEntry} from "../semantic/effects.js"
 import {locationFromOffsets, moduleLocation} from "../semantic/location.js"
 import {withAdaptedOperation} from "../semantic/operators.js"
-import {withParserRanges} from "../semantic/provenance.js"
+import {setParserRanges, withParserRanges} from "../semantic/provenance.js"
 import {isTask034ResourceProbe} from "../semantic/capabilities.js"
 import {hasExactEffectSupport} from "../backends/effects.js"
 import {hasOnlyUnicodeScalars, scalarType} from "../semantic/scalars.js"
@@ -39,6 +39,8 @@ const phpBinaryOperations = new Map([
 /**
  * @typedef PhpConversionContext
  * @property {Map<string, import("../semantic/types.js").SemanticBindingType>} bindings - Explicitly typed visible bindings.
+ * @property {Set<string>} [catchBindingNames] - Lexically visible exact catch binding names.
+ * @property {Map<string, import("../semantic/types.js").CatchBinding>} [catchBindingNodes] - Exact catch binding nodes by visible name.
  * @property {Map<string, import("../semantic/types.js").ClassDeclaration>} classes - Reference classes by identity.
  * @property {import("../semantic/types.js").ClassDeclaration} [currentClass] - Enclosing reference class.
  * @property {Map<string, import("../semantic/types.js").ErrorDeclaration>} errorNames - Error declarations by source name.
@@ -963,12 +965,24 @@ function convertStatement(node, filename, source, context) {
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
  * @param {PhpConversionContext} context - Typed lexical context.
- * @returns {import("../semantic/types.js").RaiseStatement} Semantic raise.
+ * @returns {import("../semantic/types.js").RaiseStatement | import("../semantic/types.js").RethrowStatement} Semantic raise or rethrow.
  */
 function convertPhpRaise(node, filename, source, context) {
   const location = nodeLocation(node, filename, source)
   const construction = Reflect.get(node, "what")
 
+  if (construction?.kind == "variable" && typeof construction.name == "string" && !construction.curly &&
+    context.bindings.get(construction.name)?.kind == "ErrorType" && context.catchBindingNames?.has(construction.name)) {
+    const bindingNode = context.catchBindingNodes?.get(construction.name)
+
+    if (!bindingNode) return unsupportedSyntax("php", "throw of a catch binding without an exact handler binding", location)
+    return withParserRanges({
+      binding: construction.name,
+      bindingNode,
+      kind: /** @type {const} */ ("RethrowStatement"),
+      location
+    }, {keyword: tokenLocation("throw", node.loc?.start.offset ?? 0, construction.loc?.start.offset ?? source.length, filename, source)})
+  }
   if (!construction || construction.kind != "new" || construction.what?.kind != "name" ||
     construction.what.resolution != "uqn" || !context.errorNames.has(construction.what.name) ||
     !Array.isArray(construction.arguments) || construction.arguments.length != 1 ||
@@ -1002,42 +1016,69 @@ function convertPhpTry(node, filename, source, context) {
   const location = nodeLocation(node, filename, source)
   const catches = Reflect.get(node, "catches")
   const body = Reflect.get(node, "body")
+  const always = Reflect.get(node, "always")
 
-  if (Reflect.get(node, "always") || !Array.isArray(catches) || catches.length != 1 || body?.kind != "block") {
-    return unsupportedSyntax("php", "try without one typed catch and no finally", location)
+  if (!Array.isArray(catches) || (catches.length == 0 && !always) || body?.kind != "block") {
+    return unsupportedSyntax("php", "try without typed catches or finally", location)
   }
-  const handler = catches[0]
-  const caught = handler.what?.[0]
-  const binding = handler.variable
+  /** @type {import("../semantic/types.js").CatchHandler[]} */
+  const handlers = []
+  const seenHandlerNames = new Set(context.catchBindingNames ?? [])
 
-  if (handler.what?.length != 1 || caught?.kind != "name" || caught.resolution != "uqn" ||
-    !context.errorNames.has(caught.name) || binding?.kind != "variable" || typeof binding.name != "string" ||
-    binding.curly || handler.body?.kind != "block") {
-    return unsupportedSyntax("php", "broad, multiple, or malformed catch", nodeLocation(handler, filename, source))
-  }
-  const declaration = /** @type {import("../semantic/types.js").ErrorDeclaration} */ (context.errorNames.get(caught.name))
-  const caughtLocation = nodeLocation(caught, filename, source)
-  const catchType = withParserRanges({declarationId: /** @type {string} */ (declaration.id), kind: /** @type {const} */ ("ErrorType")}, {
-    type: caughtLocation
-  })
-  const bodyContext = {...context, bindings: new Map(context.bindings)}
-  const catchContext = {...context, bindings: new Map(context.bindings)}
+  for (const handler of catches) {
+    const caught = handler.what?.[0]
+    const binding = handler.variable
 
-  catchContext.bindings.set(binding.name, catchType)
-  return withParserRanges({
-    body: convertBlock(body, filename, source, bodyContext),
-    catchBinding: withParserRanges({
+    if (handler.what?.length != 1 || caught?.kind != "name" || caught.resolution != "uqn" ||
+      !context.errorNames.has(caught.name) || binding?.kind != "variable" || typeof binding.name != "string" ||
+      binding.curly || handler.body?.kind != "block") {
+      return unsupportedSyntax("php", "broad, multiple, or malformed catch", nodeLocation(handler, filename, source))
+    }
+    if (seenHandlerNames.has(binding.name)) {
+      return unsupportedSyntax("php", `catch binding '${binding.name}' shadows an outer handler binding`, nodeLocation(binding, filename, source))
+    }
+    seenHandlerNames.add(binding.name)
+    const declaration = /** @type {import("../semantic/types.js").ErrorDeclaration} */ (context.errorNames.get(caught.name))
+    const caughtLocation = nodeLocation(caught, filename, source)
+    const catchType = withParserRanges({declarationId: /** @type {string} */ (declaration.id), kind: /** @type {const} */ ("ErrorType")}, {
+      type: caughtLocation
+    })
+    const catchContext = {...context, bindings: new Map(context.bindings), catchBindingNames: new Set(seenHandlerNames),
+      catchBindingNodes: new Map(context.catchBindingNodes)}
+
+    catchContext.bindings.set(binding.name, catchType)
+    const catchBindingNode = withParserRanges({
       kind: /** @type {const} */ ("CatchBinding"),
       location: nodeLocation(binding, filename, source),
       mutable: /** @type {const} */ (false),
       name: binding.name,
       type: catchType
-    }, {name: nodeLocation(binding, filename, source)}),
-    catchBody: convertBlock(handler.body, filename, source, catchContext),
-    catchType,
+    }, {name: nodeLocation(binding, filename, source)})
+
+    catchContext.catchBindingNodes.set(binding.name, catchBindingNode)
+    handlers.push(withParserRanges({
+      catchBinding: catchBindingNode,
+      catchBody: convertBlock(handler.body, filename, source, catchContext),
+      catchType,
+      kind: /** @type {const} */ ("CatchHandler"),
+      location: nodeLocation(handler, filename, source)
+    }, {catch: nodeLocation(handler, filename, source)}))
+  }
+  const bodyContext = {...context, bindings: new Map(context.bindings)}
+  const semantic = /** @type {import("../semantic/types.js").TryStatement} */ (withParserRanges({
+    body: convertBlock(body, filename, source, bodyContext),
+    handlers,
     kind: /** @type {const} */ ("TryStatement"),
     location
-  }, {catch: nodeLocation(handler, filename, source), try: tokenLocation("try", node.loc?.start.offset ?? 0, body.loc?.start.offset ?? source.length, filename, source)})
+  }, {try: tokenLocation("try", node.loc?.start.offset ?? 0, body.loc?.start.offset ?? source.length, filename, source)}))
+
+  if (always) {
+    if (always.kind != "block") return unsupportedSyntax("php", "malformed finally block", nodeLocation(always, filename, source))
+    semantic.finallyBody = convertBlock(always, filename, source, bodyContext)
+    setParserRanges(semantic, {finally: nodeLocation(always, filename, source),
+      try: tokenLocation("try", node.loc?.start.offset ?? 0, body.loc?.start.offset ?? source.length, filename, source)})
+  }
+  return semantic
 }
 
 /**

package/src/frontends/ruby.js

@@ -49,7 +49,7 @@ import {missingType, SemantifoldDiagnostic, unsupportedSyntax} from "../diagnost
 import {blockReferencesProtectedEntry} from "../semantic/effects.js"
 import {locationFromOffsets, moduleLocation, utf8ByteOffsetToUtf16Offset} from "../semantic/location.js"
 import {withAdaptedOperation} from "../semantic/operators.js"
-import {withParserRanges} from "../semantic/provenance.js"
+import {setParserRanges, withParserRanges} from "../semantic/provenance.js"
 import {hasOnlyUnicodeScalars, scalarType} from "../semantic/scalars.js"
 import {isTask034ResourceProbe} from "../semantic/capabilities.js"
 import {hasExactEffectSupport} from "../backends/effects.js"
@@ -61,7 +61,7 @@ const referenceMethodHooks = new Set([
   "respond_to_missing?", "send", "singleton_class", "size"
 ])
 /** @typedef {{name: string, nameLocation: import("../semantic/types.js").SourceLocation, parameters: import("../semantic/types.js").Parameter[], returnType: import("../semantic/types.js").SemanticFunctionReturnType, typeParameters?: import("../semantic/types.js").TypeParameter[], location: import("../semantic/types.js").SourceLocation}} RubyFunctionSignature */
-/** @typedef {{bindings: Map<string, import("../semantic/types.js").SemanticBindingType>, classes: Map<string, import("../semantic/types.js").ClassDeclaration>, currentClass?: import("../semantic/types.js").ClassDeclaration, errorNames: Map<string, import("../semantic/types.js").ErrorDeclaration>, errors: Map<string, import("../semantic/types.js").ErrorDeclaration>, functions: Map<string, RubyFunctionSignature>, orderedMapDeclarations?: Set<object>, records: Map<string, import("../semantic/types.js").RecordDeclaration>, recordNames: Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>, loopDepth?: number, returnType?: import("../semantic/types.js").SemanticFunctionReturnType, typeParameters?: Map<string, import("../semantic/types.js").TypeParameter>}} RubyConversionContext */
+/** @typedef {{bindings: Map<string, import("../semantic/types.js").SemanticBindingType>, catchBindingNames?: Set<string>, classes: Map<string, import("../semantic/types.js").ClassDeclaration>, catchBindingNodes?: Map<string, import("../semantic/types.js").CatchBinding>, currentCatchBindingNode?: import("../semantic/types.js").CatchBinding, currentClass?: import("../semantic/types.js").ClassDeclaration, errorNames: Map<string, import("../semantic/types.js").ErrorDeclaration>, errors: Map<string, import("../semantic/types.js").ErrorDeclaration>, functions: Map<string, RubyFunctionSignature>, orderedMapDeclarations?: Set<object>, records: Map<string, import("../semantic/types.js").RecordDeclaration>, recordNames: Map<string, import("../semantic/types.js").RecordDeclaration | import("../semantic/types.js").ClassDeclaration | import("../semantic/types.js").EffectResourceDeclaration>, loopDepth?: number, returnType?: import("../semantic/types.js").SemanticFunctionReturnType, typeParameters?: Map<string, import("../semantic/types.js").TypeParameter>}} RubyConversionContext */
 const rubyBinaryOperations = new Map([
   ["+", "Add"],
   ["-", "Subtract"],
@@ -969,15 +969,38 @@ function convertStatement(node, comments, context, filename, source) {
  * @param {RubyConversionContext} context - Typed lexical context.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
- * @returns {import("../semantic/types.js").RaiseStatement} Semantic raise.
+ * @returns {import("../semantic/types.js").RaiseStatement | import("../semantic/types.js").RethrowStatement} Semantic raise or rethrow.
  */
 function convertRubyRaise(node, context, filename, source) {
   const location = nodeLocation(node, filename, source)
   const arguments_ = node.arguments_?.arguments_ ?? []
+
+  if (arguments_.length == 0 && context.currentCatchBindingNode) {
+    return withParserRanges({
+      binding: context.currentCatchBindingNode.name,
+      bindingNode: context.currentCatchBindingNode,
+      kind: /** @type {const} */ ("RethrowStatement"),
+      location
+    }, {keyword: prismLocation(node.messageLoc ?? node.location, filename, source)})
+  }
+  if (arguments_.length == 1 && arguments_[0] instanceof LocalVariableReadNode &&
+    context.catchBindingNames?.has(arguments_[0].name) && context.bindings.get(arguments_[0].name)?.kind == "ErrorType") {
+    const bindingNode = context.catchBindingNodes?.get(arguments_[0].name)
+
+    if (!bindingNode) return unsupportedSyntax("ruby", "raise of a catch binding without an exact handler binding", location)
+    return withParserRanges({
+      binding: arguments_[0].name,
+      bindingNode,
+      kind: /** @type {const} */ ("RethrowStatement"),
+      location
+    }, {keyword: prismLocation(node.messageLoc ?? node.location, filename, source)})
+  }
+  if (node.block || node.callOperatorLoc || arguments_.length != 2) {
+    return unsupportedSyntax("ruby", "raise other than exact declared error and message", location)
+  }
   const errorNode = arguments_[0]
 
-  if (node.block || node.callOperatorLoc || arguments_.length != 2 ||
-    !(errorNode instanceof ConstantReadNode) && !(errorNode instanceof ConstantPathNode) ||
+  if (!(errorNode instanceof ConstantReadNode) && !(errorNode instanceof ConstantPathNode) ||
     !context.errorNames.has(constantPathName(errorNode))) {
     return unsupportedSyntax("ruby", "raise other than exact declared error and message", location)
   }
@@ -997,48 +1020,104 @@ function convertRubyRaise(node, context, filename, source) {
 }
 
 /**
- * Converts one exact typed rescue with no else/ensure.
+ * Converts one exact Prism ensure clause body.
+ * @param {import("@ruby/prism").EnsureNode} node - Prism ensure clause.
+ * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Prism comments.
+ * @param {RubyConversionContext} context - Typed lexical context.
+ * @param {string} filename - Source filename.
+ * @param {string} source - Complete source.
+ * @returns {import("../semantic/types.js").Block} Semantic finally block.
+ */
+function convertRubyEnsure(node, comments, context, filename, source) {
+  // A completion block gets its own binding scope, like every other block in convertRubyTry: a local
+  // declaration inside `ensure` must not leak back into the enclosing conversion context.
+  return convertBlock(node.statements ?? null, comments, {...context, bindings: new Map(context.bindings)}, filename, source,
+    nodeLocation(node, filename, source))
+}
+
+/**
+ * Converts one begin block with ordered exact typed rescues and an optional ensure completion block.
  * @param {BeginNode} node - Prism begin node.
  * @param {import("@ruby/prism/src/deserialize.js").Comment[]} comments - Parser-owned comments.
  * @param {RubyConversionContext} context - Typed lexical context.
  * @param {string} filename - Source filename.
  * @param {string} source - Complete source.
- * @returns {import("../semantic/types.js").TryStatement} Semantic exact handler.
+ * @returns {import("../semantic/types.js").TryStatement} Semantic exact handler chain.
  */
 function convertRubyTry(node, comments, context, filename, source) {
   const location = nodeLocation(node, filename, source)
-  const handler = node.rescueClause
 
-  if (!(handler instanceof RescueNode) || handler.subsequent || node.elseClause || node.ensureClause ||
-    handler.exceptions.length != 1 ||
-    !(handler.exceptions[0] instanceof ConstantReadNode) && !(handler.exceptions[0] instanceof ConstantPathNode) ||
-    !context.errorNames.has(constantPathName(handler.exceptions[0])) || !(handler.reference instanceof LocalVariableTargetNode)) {
-    return unsupportedSyntax("ruby", "begin without one exact typed rescue and binding", location)
+  if (node.elseClause) return unsupportedSyntax("ruby", "begin else clause", nodeLocation(node.elseClause, filename, source))
+  /** @type {import("../semantic/types.js").CatchHandler[]} */
+  const handlers = []
+  const seenHandlerNames = new Set(context.catchBindingNames ?? [])
+  let handler = node.rescueClause
+
+  if (!(handler instanceof RescueNode)) {
+    if (node.ensureClause) {
+      return withParserRanges({
+        body: convertBlock(node.statements, comments, context, filename, source, location),
+        handlers,
+        kind: /** @type {const} */ ("TryStatement"),
+        location,
+        finallyBody: convertRubyEnsure(node.ensureClause, comments, context, filename, source)
+      }, {ensure: nodeLocation(node.ensureClause, filename, source), try: location})
+    }
+    return unsupportedSyntax("ruby", "begin without rescue or ensure", location)
   }
-  const errorNode = handler.exceptions[0]
-  const declaration = /** @type {import("../semantic/types.js").ErrorDeclaration} */ (context.errorNames.get(constantPathName(errorNode)))
-  const caughtLocation = nodeLocation(errorNode, filename, source)
-  const catchType = withParserRanges({declarationId: /** @type {string} */ (declaration.id), kind: /** @type {const} */ ("ErrorType")}, {
-    type: caughtLocation
-  })
   const bodyContext = {...context, bindings: new Map(context.bindings)}
-  const catchContext = {...context, bindings: new Map(context.bindings)}
+  while (handler instanceof RescueNode) {
+    if (handler.exceptions.length != 1 ||
+      !(handler.exceptions[0] instanceof ConstantReadNode) && !(handler.exceptions[0] instanceof ConstantPathNode) ||
+      !context.errorNames.has(constantPathName(handler.exceptions[0])) || !(handler.reference instanceof LocalVariableTargetNode)) {
+      return unsupportedSyntax("ruby", "rescue without one exact typed exception and binding", nodeLocation(handler, filename, source))
+    }
+    if (seenHandlerNames.has(handler.reference.name)) {
+      return unsupportedSyntax("ruby", `rescue binding '${handler.reference.name}' shadows an outer handler binding`,
+        nodeLocation(handler.reference, filename, source))
+    }
+    seenHandlerNames.add(handler.reference.name)
+    const errorNode = handler.exceptions[0]
+    const declaration = /** @type {import("../semantic/types.js").ErrorDeclaration} */ (context.errorNames.get(constantPathName(errorNode)))
+    const caughtLocation = nodeLocation(errorNode, filename, source)
+    const catchType = withParserRanges({declarationId: /** @type {string} */ (declaration.id), kind: /** @type {const} */ ("ErrorType")}, {
+      type: caughtLocation
+    })
+    const catchContext = {...context, bindings: new Map(context.bindings), catchBindingNames: new Set(seenHandlerNames),
+      catchBindingNodes: new Map(context.catchBindingNodes)}
 
-  catchContext.bindings.set(handler.reference.name, catchType)
-  return withParserRanges({
-    body: convertBlock(node.statements, comments, bodyContext, filename, source, location),
-    catchBinding: withParserRanges({
+    catchContext.bindings.set(handler.reference.name, catchType)
+    const catchBindingNode = withParserRanges({
       kind: /** @type {const} */ ("CatchBinding"),
       location: nodeLocation(handler.reference, filename, source),
       mutable: /** @type {const} */ (false),
       name: handler.reference.name,
       type: catchType
-    }, {name: nodeLocation(handler.reference, filename, source)}),
-    catchBody: convertBlock(handler.statements, comments, catchContext, filename, source, nodeLocation(handler, filename, source)),
-    catchType,
+    }, {name: nodeLocation(handler.reference, filename, source)})
+
+    catchContext.catchBindingNodes.set(handler.reference.name, catchBindingNode)
+    catchContext.currentCatchBindingNode = catchBindingNode
+    handlers.push(withParserRanges({
+      catchBinding: catchBindingNode,
+      catchBody: convertBlock(handler.statements, comments, catchContext, filename, source, nodeLocation(handler, filename, source)),
+      catchType,
+      kind: /** @type {const} */ ("CatchHandler"),
+      location: nodeLocation(handler, filename, source)
+    }, {catch: nodeLocation(handler, filename, source)}))
+    handler = handler.subsequent
+  }
+  const semantic = /** @type {import("../semantic/types.js").TryStatement} */ (withParserRanges({
+    body: convertBlock(node.statements, comments, bodyContext, filename, source, location),
+    handlers,
     kind: /** @type {const} */ ("TryStatement"),
     location
-  }, {catch: nodeLocation(handler, filename, source), try: location})
+  }, {try: location}))
+
+  if (node.ensureClause) {
+    semantic.finallyBody = convertRubyEnsure(node.ensureClause, comments, context, filename, source)
+    setParserRanges(semantic, {ensure: nodeLocation(node.ensureClause, filename, source), try: location})
+  }
+  return semantic
 }
 
 /**

package/src/semantic/effects.js

@@ -379,10 +379,19 @@ function escapingBlockFailures(block, functionSummaries, methodSummaries, capabi
 
   for (const statement of block.statements) {
     if (statement.kind == "TryStatement") {
-      const body = escapingBlockFailures(statement.body, functionSummaries, methodSummaries, capabilityFailureIds)
+      let body = escapingBlockFailures(statement.body, functionSummaries, methodSummaries, capabilityFailureIds)
 
-      if (body.delete(statement.catchType.declarationId)) {
-        addFailures(result, escapingBlockFailures(statement.catchBody, functionSummaries, methodSummaries, capabilityFailureIds))
+      for (const handler of statement.handlers ?? []) {
+        const caughtId = handler.catchType?.declarationId
+
+        if (typeof caughtId == "string" && body.delete(caughtId)) {
+          addFailures(body, escapingBlockFailures(handler.catchBody, functionSummaries, methodSummaries, capabilityFailureIds))
+        }
+      }
+      if (statement.finallyBody) {
+        // A completion block that can raise replaces the pending completion on the paths where it does,
+        // but pending failures still escape on the paths where it completes normally, so both are reachable.
+        addFailures(body, escapingBlockFailures(statement.finallyBody, functionSummaries, methodSummaries, capabilityFailureIds))
       }
       addFailures(result, body)
       continue
@@ -639,7 +648,9 @@ function forEachBlockExpression(block, visitor, postorder) {
       visit(statement.condition); forEachBlockExpression(statement.body, visitor, postorder)
     } else if (statement.kind == "RaiseStatement") visit(statement.error.message)
     else if (statement.kind == "TryStatement") {
-      forEachBlockExpression(statement.body, visitor, postorder); forEachBlockExpression(statement.catchBody, visitor, postorder)
+      forEachBlockExpression(statement.body, visitor, postorder)
+      for (const handler of statement.handlers) forEachBlockExpression(handler.catchBody, visitor, postorder)
+      if (statement.finallyBody) forEachBlockExpression(statement.finallyBody, visitor, postorder)
     }
   }
 
@@ -694,7 +705,8 @@ function statementReferencesProtectedEntry(statement) {
     case "RaiseStatement":
       return expressionReferencesProtectedEntry(statement.error.message)
     case "TryStatement":
-      return blockReferencesProtectedEntry(statement.body) || blockReferencesProtectedEntry(statement.catchBody)
+      return blockReferencesProtectedEntry(statement.body) || statement.handlers.some((handler) => blockReferencesProtectedEntry(handler.catchBody)) ||
+        (statement.finallyBody ? blockReferencesProtectedEntry(statement.finallyBody) : false)
     default:
       return false
   }