Scaladoc fatal error when reading inconsistent TASTy/ClassFiles

[WojciechMazur]

https://contributors.scala-lang.org/t/scala-3-6-3-release-thread/6958/5

Compiler version

All Scala version

Reproductions steps

1. Define project 1 (bson)

// bson/build.sbt 
scalaVersion := "3.4.2"

Compile / packageBin / mappings ~= {
  _.filter { case (_, path) => !path.startsWith("com/github/ghik") }
}
Compile / packageSrc / mappings ~= {
  _.filter { case (_, path) => path != "silent.scala" }
}

// bson/src/main/scala/Handlers.scala 
package bson

trait BSONWriter[T]
trait DefaultHandlers:
  @com.github.ghik.silencer.silent
  given collectionWriter[T, Repr <: Iterable[T]]: BSONWriter[Repr] = ???
  
  
object Handlers extends DefaultHandlers

// bson/src/main/scala/silent.scala
package com.github.ghik.silencer

class silent(s: String = "") extends scala.annotation.StaticAnnotation {
  val _ = s
}

2. Build the jar using sbt

cd bson 
sbt packageBin

3. Use the created jar in other project

// test.scala
trait Foo extends bson.DefaultHandlers

scala doc -f test.scala --jar bson/target/scala-3.4.2/bson_3-0.1.0-SNAPSHOT.jar

Output

-- Error: src/main/scala/Handlers.scala:5:2 -------------------------------------------------------------------------------------------------------------------------------------------------
undefined: new com.github.ghik.silencer.silent # -1: TermRef(TypeRef(TermRef(TermRef(TermRef(TermRef(ThisType(TypeRef(NoPrefix,module class <root>)),object com),object github),object ghik),object silencer),silent),<init>) at readTasty

Expectation

If possible unknown annotations should be skipped when reading TASTy

[Gedochao]

Note: the discussion implies there may be a regression somewhere, but the reproduction from this issue is actually broken all the way to 3.4, and not just for 3.6.3+.
The problem may have been activated by something else.

I'm labelling this as stat:needs minimization, in case we're able to find the case where this breaks for 3.6.3 and 3.6.4-RC1, but not 3.6.2.
Technically not yet proven to be a regression, but we're treating it with priority.
cc @jchyb @Florian3k

[jchyb]

For lila-ws specifically, I want to argue that there is no regression here, if anything an improvement in behavior.
Generating docs via sbt, in 3.6.2 we get:

sbt:lila-ws> doc
[info] compiling 79 Scala sources to /Users/jchyb/workspace/lila-ws/target/scala-3.6.2/classes ...
[info] Main Scala API documentation to /Users/jchyb/workspace/lila-ws/target/scala-3.6.2/api...
[info] Skipping unused scalacOptions: -Xsemanticdb, -Xunchecked-java-output-version, -semanticdb-target, -source, -rewrite, -indent
-- Error: api/target/shaded/scala-3.4.2/src_managed/main/velocity/DefaultBSONHandlers.scala:379:2 
undefined: new com.github.ghik.silencer.silent # -1: TermRef(TypeRef(TermRef(TermRef(TermRef(TermRef(ThisType(TypeRef(NoPrefix,module class <root>)),object com),object github),object ghik),object silencer),silent),<init>) at readTasty
1 error found
[info] Main Scala API documentation successful.
[success] Total time: 13 s, completed 24 sty 2025, 14:40:23

in 3.6.3, we get:

sbt:lila-ws> doc
[info] compiling 79 Scala sources to /Users/jchyb/workspace/lila-ws/target/scala-3.6.3/classes ...
[info] Main Scala API documentation to /Users/jchyb/workspace/lila-ws/target/scala-3.6.3/api...
[info] Skipping unused scalacOptions: -Xsemanticdb, -Xunchecked-java-output-version, -semanticdb-target, -source, -rewrite, -indent
[warn] Flag -classpath set repeatedly
[error] -- Error: api/target/shaded/scala-3.4.2/src_managed/main/velocity/DefaultBSONHandlers.scala:379:2 
[error] undefined: new com.github.ghik.silencer.silent # -1: TermRef(TypeRef(TermRef(TermRef(TermRef(TermRef(ThisType(TypeRef(NoPrefix,module class <root>)),object com),object github),object ghik),object silencer),silent),<init>) at readTasty
[warn] one warning found
[error] one error found
[error] (Compile / doc) DottyDoc Compilation Failed
[error] Total time: 9 s, completed 24 sty 2025, 14:41:27

So both exhibit the same error, but in 3.6.2 it does not cause the sbt build/CI to fail, and in 3.6.3 it does. Inspecting what was actually generated reveals that neither scala version actually managed to generate any html files (only the js scripts, images etc.). Since nothing is generated, i'd argue the build task should fail (with that said, in 3.6.3 we do get an extra warning which I don't think should be there).

I imagine (but unsure) that the difference in behavior is connected to the changes made recently to tasty-inspector, where we reuse the scaladoc Context there - since the tasty-inspector does not create its own, every error from tasty-inspector, read tasty, etc. gets escalated.

Of course, it would probably be better for scaladoc to be able to handle and recover from some missing symbols, but my argument here is that what we see is not a regression.

[i10416]

I came across similar situation on Scala 3.6.3.

Loading Scala 3 binary from /path/to/target/scala-3.6.3/classes/com/example/A$.class.
It should have been loaded from `.tasty` file. This `.tasty` file is missing. Try cleaning the project to fix this issue.

When there are both an object whose name contains $ sign and a package object whose body references the object, scaladoc is unable to read tasty and fails to generate doc.
Scala（from 3.4.0 to 3.6.2）emits the same error though it leniently ignores the error.

Here is minimized reproduction.
https://github.com/i10416/repro-scaladoc-error-on-dollar-symbol

[DavidGregory084]

@i10416 I think that is a totally different problem - scalac probably shouldn't let you define an object with a trailing $, because that is the symbol that is used to disambiguate companion objects from their companion classes.
I guess that scalac probably trims all trailing $ somewhere which leaves it unable to differentiate A$$ from A$ during compilation.
Regardless, it seems unwise to allow the character that is used to define synthetic classes in user code.