Metals Notes

• A Dive into how Metals works by Chris Kipp
• BSP link to ScalaBuildTargets, you can find information on a particular build target by clicking on it in Metals Doctor
• Short description of how presentation compilers are created: https://github.com/scalameta/metals/issues/1653

We need a presentation compiler for each build target since different build targets can have different classpaths and compiler settings.

The presentation compiler APIs are compiled against exact Scala versions of the compiler while Metals only runs in a single Scala version. In order to communicate between Metals and the reflectively loaded compiler, a custom classloader, PresentationCompilerClassLoader, is used by scala.meta.internal.metals.Embedded which is in turn used by Compilers.

• https://github.com/scalameta/metals/blob/main/docs/editors/overview.md
  • Diagnostics are triggered on compile, compilation is triggered on file save for the build target (project/module) containing the focused text file.
  • Syntax errors are published as you type but type errors are handled by the build tool
• About scalafix:
  • why removed: https://github.com/scalameta/metals/commit/b84fa4479e614afa4cb6a5ce5b52873c42d1d1ed
  • implementation: https://github.com/scalameta/metals/pull/154

Switch occurs in BspConnector.switchBuildServer. Build servers are generated by BuildServerProvider (an extension of the BuildTool trait) instances.

A semanticdb payload associated with a file contains:

• Uri the uri of the source file, ie metals/src/main/scala/scala/meta/internal/metals/codelenses/RunTestCodeLens.scala

• Symbols which contains information on definitions in the source file, e.g.

  local36 => val local dataKind: String
  local37 => val local data: JsonElement
  scala/meta/internal/metals/codelenses/RunTestCodeLens# => final class RunTestCodeLens extends AnyRef with CodeLens { +17 decls }
  

• Ocurrences a list of identifiers from the source file with their line/column-based positions and unique identifiers pointing to corresponding definitions resolved by the compiler:

  [75:13..75:22) => scala/Option#getOrElse().
  [75:23..75:26) => scala/package.Seq.
  [75:27..75:32) => scala/collection/SeqFactory.Delegate#empty().
  [82:14..82:26) <= scala/meta/internal/metals/codelenses/RunTestCodeLens#isMainMethod().
  

  For example, [2:4..2:11): println => scala/Predef.println(+1). says that the identifier println on line 3 (zero-based numbering scheme!) refers to the second overload of println from scala/Predef

• Indexer.scala -> MetalsLanguageServer.connectToNewBuildServer() -> profiledIndexWorkspace() -> indexWorkspace() -> indexDependencySources()
• DefinitionProvider.scala -> Uses a GlobalSymbolIndex, but only index.definitions (also has access to the raw Mtags?)
• OnDemandSymbolIndex.scala -> GlobalSymbolIndex implementation, holds buckets of symbols

Code lenses are refreshed whenever:

• There is a reindexing (Indexer.indexWorkspace calls languageClient.refreshModel which in turn calls workspace/codeLens/refresh (?), which prompts the client to call textDocument/codeLens
• There is a (re)compilation (Compilations.compile calls languageClient.refreshModel), ie a user saves their document.

MetalsLanguageServer.scala -> Compilers.scala holds a list of ScalaPresentationCompiler.scala -> Which can create a new MetalsGlobal.scala object using newCompiler() ->

Completions call tree:

////////////////////////////////
// MetalsLanguageServer.scala //
////////////////////////////////
@JsonRequest("textDocument/completion")
def completion(params: CompletionParams): CompletableFuture[CompletionList] =
  CancelTokens.future { token => compilers.completions(params, token) }

/////////////////////
// Compilers.scala //
/////////////////////
def completions(
    params: CompletionParams,
    token: CancelToken,
): Future[CompletionList] =
  withPCAndAdjustLsp(params) { (pc, pos, adjust) =>
    val offsetParams =
      CompilerOffsetParams.fromPos(pos, token)
    pc.complete(offsetParams)
      .asScala
      .map { list =>
        adjust.adjustCompletionListInPlace(list)
        list
      }
  }.getOrElse(Future.successful(new CompletionList(Nil.asJava)))

/////////////////////////////////////
// ScalaPresentationCompiler.scala //
/////////////////////////////////////
override def complete(
    params: OffsetParams
): CompletableFuture[CompletionList] =
  compilerAccess.withInterruptableCompiler(
    EmptyCompletionList(),
    params.token
  ) { pc => new CompletionProvider(pc.compiler(), params).completions() }


//////////////////////////////
// CompletionProvider.scala //
//////////////////////////////

def completions(): CompletionList = {
  val filename = params.uri().toString()
  val unit = addCompilationUnit(
    code = params.text,
    filename = filename,
    cursor = Some(params.offset),
    cursorName = cursorName
  )

  val pos = unit.position(params.offset)
  val isSnippet = isSnippetEnabled(pos, params.text())

  val (i, completion, editRange, query) = safeCompletionsAt(pos, params.uri())
  // ...
}

private def safeCompletionsAt(
    pos: Position,
    source: URI
): (InterestingMembers, CompletionPosition, l.Range, String) = {
  // ...
  // Call to the presentation compiler is here
  val completions = completionsAt(pos) match {
    case CompletionResult.NoResults =>
      new DynamicFallbackCompletions(pos).print()
    case r => r
  }
  // ...
  val completion = completionPosition(
    pos,
    source,
    params.text(),
    editRange,
    completions,
    latestParentTrees
  )
  // ... finally the return value
  (items, completion, editRange, query)
}

///////////////////////
// Completions.scala //
///////////////////////
// the implementation of completionPositionUnsafe does a lot of `typedTreeAt(pos).tpe`
// which often causes null pointer exceptions, it's easier to catch the error in
// completePosition
def completionPositionUnsafe(
      pos: Position,
      source: URI,
      text: String,
      editRange: l.Range,
      completions: CompletionResult,
      latestEnclosingArg: List[Tree]
  ): CompletionPosition = {

}