Refactor and document

Author: nicolasstucki

compiler/src/dotty/tools/dotc/transform/PCPCheckAndHeal.scala

@@ -51,13 +51,12 @@ class PCPCheckAndHeal(@constructorOnly ictx: Context) extends TreeMapWithStages(
         if healedType == tree.tpe then tree
         else TypeTree(healedType).withSpan(tree.span)
 
-      case _: This =>
-        tree.withType(healTermType(tree.sourcePos)(tree.tpe))
-      case _: Ident =>
+      case _: Ident | _: This =>
         tree.withType(healTermType(tree.sourcePos)(tree.tpe))
 
       // Remove inline defs in quoted code. Already fully inlined.
-      case tree: DefDef if tree.symbol.is(Inline) && level > 0 => EmptyTree
+      case tree: DefDef if tree.symbol.is(Inline) && level > 0 =>
+        EmptyTree
 
       case tree: ValOrDefDef =>
         checkAnnotations(tree)
@@ -129,70 +128,84 @@ class PCPCheckAndHeal(@constructorOnly ictx: Context) extends TreeMapWithStages(
   private def healInfo(tree: Tree, pos: SourcePosition)(using Context): Unit =
     tree.symbol.info = healType(pos)(tree.symbol.info)
 
+  /** If the refers to a locally defined symbol (either directly, or in a pickled type),
+   *  check that its staging level matches the current level.
+   *  - Static types and term are allowed at any level.
+   *  - If a type reference is used a higher level, then it is insosistent. Will atempt to heal before failing.
+   *  - If a term reference is used a different level, then it is insosistent.
+   *
+   *  If `T` is a reference to a type at the wrong level, try to heal it by replacing it with
+   *  a type tag of type `quoted.Type[T]`.
+   *  The tag is generated by an instance of `QuoteTypeTags` directly if the splice is explicit
+   *  or indirectly by `tryHeal`.
+   */
   private def healType(pos: SourcePosition)(using Context) = new TypeMap {
     def apply(tp: Type): Type =
       tp match
         case tp: TypeRef =>
           tp.prefix match
             case NoPrefix if level > levelOf(tp.symbol) =>
-              tryHeal(tp.symbol, tp, pos).getOrElse(tp)
+              tryHeal(tp.symbol, tp, pos)
             case prefix: ThisType if !tp.symbol.isStatic && level > levelOf(prefix.cls) =>
-              tryHeal(tp.symbol, tp, pos).getOrElse(tp)
+              tryHeal(tp.symbol, tp, pos)
             case prefix: TermRef if tp.symbol.isSplice =>
               // Heal explice type splice in the code
               if level > 0 then getQuoteTypeTags.getTagRef(prefix) else tp
             case prefix: TermRef if !prefix.symbol.isStatic && level != levelOf(prefix.symbol) =>
-              tryHeal(tp.symbol, tp, pos).getOrElse(tp)
+              tryHeal(tp.symbol, tp, pos)
             case _ =>
               mapOver(tp)
         case tp: ThisType if level != -1 && level != levelOf(tp.cls) =>
           levelError(tp.cls, tp, pos, "")
-          tp
         case tp: AnnotatedType =>
           val newAnnotTree = transform(tp.annot.tree)
           derivedAnnotatedType(tp, apply(tp.parent), tp.annot.derivedAnnotation(newAnnotTree))
         case _ =>
           mapOver(tp)
   }
 
+  /** Check phase consistency of terms and heal incosistent type references. */
   private def healTermType(pos: SourcePosition)(using Context) = new TypeMap {
     def apply(tp: Type): Type =
       tp match
         case tp @ TypeRef(NoPrefix, _) if level > levelOf(tp.symbol) =>
-          tryHeal(tp.symbol, tp, pos).getOrElse(tp)
+          tryHeal(tp.symbol, tp, pos)
         case tp @ TermRef(NoPrefix, _) if !tp.symbol.isStatic && level != levelOf(tp.symbol) =>
           levelError(tp.symbol, tp, pos, "")
-          tp
         case tp: ThisType if level != -1 && level != levelOf(tp.cls) =>
           levelError(tp.cls, tp, pos, "")
-          tp
         case _ =>
           if tp.typeSymbol.is(Package) then tp
           else mapOver(tp)
   }
 
-  // TODO return new type or else old?
-  protected def tryHeal(sym: Symbol, tp: TypeRef, pos: SourcePosition)(implicit ctx: Context): Option[TypeRef] = {
+  /** Try to heal reference to type `T` used in a higher level than its definition.
+   *  Returns a reference to a type tag generated by `QuoteTypeTags` that contains a
+   *  refercence to a type alias containing the equivalent of `${summon[quoted.Type[T]]}`.
+   *  Emits and error if `T` cannot be healed and returns `T`.
+   */
+  protected def tryHeal(sym: Symbol, tp: TypeRef, pos: SourcePosition)(implicit ctx: Context): TypeRef = {
     val reqType = defn.QuotedTypeClass.typeRef.appliedTo(tp)
     val tag = ctx.typer.inferImplicitArg(reqType, pos.span)
     tag.tpe match
+
       case tp: TermRef =>
         checkStable(tp, pos, "type witness")
-        Some(getQuoteTypeTags.getTagRef(tp))
+        getQuoteTypeTags.getTagRef(tp)
       case _: SearchFailureType =>
         levelError(sym, tp, pos,
-                    i"""
-                      |
-                      | The access would be accepted with the right type tag, but
-                      | ${ctx.typer.missingArgMsg(tag, reqType, "")}""")
+            i"""
+                |
+                | The access would be accepted with the right type tag, but
+                | ${ctx.typer.missingArgMsg(tag, reqType, "")}""")
       case _ =>
         levelError(sym, tp, pos,
-                    i"""
-                      |
-                      | The access would be accepted with a given $reqType""")
+            i"""
+                |
+                | The access would be accepted with a given $reqType""")
   }
 
-  private def levelError(sym: Symbol, tp: Type, pos: SourcePosition, errMsg: String)(using Context) = {
+  private def levelError(sym: Symbol, tp: Type, pos: SourcePosition, errMsg: String)(using Context): tp.type = {
     def symStr =
       if (!tp.isInstanceOf[ThisType]) sym.show
       else if (sym.is(ModuleClass)) sym.sourceModule.show
@@ -201,7 +214,7 @@ class PCPCheckAndHeal(@constructorOnly ictx: Context) extends TreeMapWithStages(
       em"""access to $symStr from wrong staging level:
           | - the definition is at level ${levelOf(sym)},
           | - but the access is at level $level.$errMsg""", pos)
-    None
+    tp
   }
 
 }

compiler/src/dotty/tools/dotc/transform/Staging.scala

@@ -43,7 +43,7 @@ class Staging extends MacroTransform {
       tree match {
         case PackageDef(pid, _) if tree.symbol.owner == defn.RootClass =>
           val checker = new PCPCheckAndHeal(freshStagingContext) {
-            override protected def tryHeal(sym: Symbol, tp: TypeRef, pos: SourcePosition)(implicit ctx: Context): Option[TypeRef] = {
+            override protected def tryHeal(sym: Symbol, tp: TypeRef, pos: SourcePosition)(implicit ctx: Context): TypeRef = {
               def symStr =
                 if (sym.is(ModuleClass)) sym.sourceModule.show
                 else i"${sym.name}.this"
@@ -55,7 +55,7 @@ class Staging extends MacroTransform {
                     | - the definition is at level ${levelOf(sym)},
                     | - but the access is at level $level.$errMsg""")
 
-              None
+              tp
             }
           }
           checker.transform(tree)