I think this is incomplete because the build client might want to know for each resource URI if it is a file or a directory.

URIs ending with / should be treated as a directory, same as for SourceItem. I think this is a standard convention for URIs.

In the case it is a file, it does not know the relative path of the file to be copied to the target directory.

My understanding is that files should get added directly to the runtime classpath, without getting relativized by a directory. I'm not sure what effect that has however, I'm unable to load up a resource file that was added directly to the classpath.

❯ scala -cp $PWD/FuzzySearch.ts
Welcome to Scala 2.13.4 (OpenJDK 64-Bit Server VM, Java 1.8.0_292).
Type in expressions for evaluation. Or try :help.

scala> this.getClass.getResource("/FuzzySearch.ts")
val res0: java.net.URL = null

scala> this.getClass.getClassLoader.getResource("/FuzzySearch.ts")
val res1: java.net.URL = null

scala> this.getClass.getClassLoader.getResource("FuzzySearch.ts")
val res2: java.net.URL = null

scala> this.getClass.getResource("FuzzySearch.ts")
val res3: java.net.URL = null

The roots docstring should use a trailing slash for the example ["file://Users/name/dev/metals/src/main/scala/"]

My understanding is that files should get added directly to the runtime classpath, without getting relativized by a directory. I'm not sure what effect that has however, I'm unable to load up a resource file that was added directly to the classpath.

Well yes that should work but it would be better if made explicit in the data structure and specification of ResourcesItem.

Also I think the client might need to know if a resource is generated or not for the same reason as a SourceItem:

/** Indicates if this source is automatically generated by the build and is not
   * intended to be manually edited by the user. */

So I think it is worth aligning the ResourceItems structure and spec with the existing SourceItems. It would look like this:

export interface ResourcesItem {
  target: BuildTargetIdentifer;
  /** The resource files or and directories that belong to this build target. */
  resources: ResourceItem[];
}

export interface ResourceItem {
  /** Either a file or a directory.
   * A directory entry must end with a forward slash "/".
   * A directory entry implies that every nested file within the
   * directory belongs to this resource item.
   */
  uri: Uri;

  /** Type of file of the source item, such as whether it is file or directory.
   */
  kind: ResourceItemKind;

  /** Indicates if this resource is automatically generated by the build and is not
   * intended to be manually edited by the user. */
  generated: Boolean;
}

export namespace ResourceItemKind {
  /** The resource item references a normal file.  */
  export const File: Int = 1;
  /** The resource item references a directory. */
  export const Directory: Int = 2;
}

Yes, not fixing this was an oversight that I've been procrastinating on fixing ever since I noticed it after we changed SourceItem ...

The problem now is that changing ResourcesItem to the same format as SourcesItem would be an incompatible change, and we have somewhat more API adoption now. Ideas on this? One way would be to put it behind a new request, so that clients/servers that know only the old request can continue to work with that. Of course that adds additional work for implementors on both sides.

Yes it's indeed a breaking change, a new request will probably be a good solution.

It still remains to find a relevant name for this new request !

Or we can mix the old spec with the new spec so that all the old and new clients/servers can talk to each other:

export interface ResourcesItem {
  target: BuildTargetIdentifer;

  /** The resource files or and directories that belong to this build target. */
  resourceItems: ResourceItem[]

  /** Deprecated version of the resourceItems field
  * Servers should provide it to maintain the compatibility with older clients
  * Clients should try to read resourceItems first and fallback to resources if 
  * resourceItems is not defined.
  */
  resources: Uri[];
}

Yup, I was thinking that, though it would duplicate some data. But it would keep the implementations simpler.