feat: expose workspace roots and file system API

Author: sqs

src/client/api/fileSystem.ts

@@ -0,0 +1,29 @@
+import { FileSystem, FileType } from 'sourcegraph'
+import { createProxyAndHandleRequests } from '../../common/proxy'
+import { Connection } from '../../protocol/jsonrpc2/connection'
+import { URI } from '../../shared/uri'
+
+/** @internal */
+export interface ClientFileSystemAPI {
+    $readDirectory(uri: string): Promise<[string, FileType][]>
+    $readFile(uri: string): Promise<Uint8Array>
+}
+
+/** @internal */
+export class ClientFileSystem {
+    constructor(connection: Connection, private getFileSystem: (uri: string) => FileSystem) {
+        createProxyAndHandleRequests('fileSystem', connection, this)
+    }
+
+    public $readDirectory(uri: string): Promise<[string, FileType][]> {
+        return this.getFileSystem(uri).readDirectory(URI.parse(uri))
+    }
+
+    public $readFile(uri: string): Promise<Uint8Array> {
+        return this.getFileSystem(uri).readFile(URI.parse(uri))
+    }
+
+    public unsubscribe(): void {
+        // noop
+    }
+}

src/client/api/roots.ts

@@ -0,0 +1,25 @@
+import { Observable, Subscription } from 'rxjs'
+import { createProxyAndHandleRequests } from '../../common/proxy'
+import { ExtRootsAPI } from '../../extension/api/roots'
+import { Connection } from '../../protocol/jsonrpc2/connection'
+import { WorkspaceRoot } from '../../protocol/plainTypes'
+
+/** @internal */
+export class ClientRoots {
+    private subscriptions = new Subscription()
+    private proxy: ExtRootsAPI
+
+    constructor(connection: Connection, environmentRoots: Observable<WorkspaceRoot[] | null>) {
+        this.proxy = createProxyAndHandleRequests('roots', connection, this)
+
+        this.subscriptions.add(
+            environmentRoots.subscribe(roots => {
+                this.proxy.$acceptRoots(roots || [])
+            })
+        )
+    }
+
+    public unsubscribe(): void {
+        this.subscriptions.unsubscribe()
+    }
+}

src/client/controller.ts

@@ -1,6 +1,6 @@
 import { BehaviorSubject, Observable, Subject, Subscription, Unsubscribable } from 'rxjs'
 import { distinctUntilChanged, map } from 'rxjs/operators'
-import { ContextValues } from 'sourcegraph'
+import { ContextValues, FileSystem } from 'sourcegraph'
 import {
     ConfigurationCascade,
     ConfigurationUpdateParams,
@@ -18,7 +18,9 @@ import { ClientCommands } from './api/commands'
 import { ClientConfiguration } from './api/configuration'
 import { ClientContext } from './api/context'
 import { ClientDocuments } from './api/documents'
+import { ClientFileSystem } from './api/fileSystem'
 import { ClientLanguageFeatures } from './api/languageFeatures'
+import { ClientRoots } from './api/roots'
 import { Search } from './api/search'
 import { ClientViews } from './api/views'
 import { ClientWindows } from './api/windows'
@@ -67,6 +69,11 @@ export interface ControllerOptions<X extends Extension, C extends ConfigurationC
      * Called before applying the next environment in Controller#setEnvironment. It should have no side effects.
      */
     environmentFilter?: (nextEnvironment: Environment<X, C>) => Environment<X, C>
+
+    /**
+     * Called to obtain a {@link module:sourcegraph.FileSystem} to access the file system for a URI.
+     */
+    getFileSystem: (uri: string) => FileSystem
 }
 
 /**
@@ -273,6 +280,16 @@ export class Controller<X extends Extension, C extends ConfigurationCascade> imp
         )
         subscription.add(new Search(client, this.registries.queryTransformer))
         subscription.add(new ClientCommands(client, this.registries.commands))
+        subscription.add(
+            new ClientRoots(
+                client,
+                this.environment.pipe(
+                    map(({ roots }) => roots),
+                    distinctUntilChanged()
+                )
+            )
+        )
+        subscription.add(new ClientFileSystem(client, this.options.getFileSystem))
     }
 
     public set trace(value: Trace) {

src/client/environment.ts

@@ -1,4 +1,5 @@
 import { ConfigurationCascade } from '../protocol'
+import { WorkspaceRoot } from '../protocol/plainTypes'
 import { Context, EMPTY_CONTEXT } from './context/context'
 import { Extension } from './extension'
 import { TextDocumentItem } from './types/textDocument'
@@ -13,6 +14,11 @@ import { TextDocumentItem } from './types/textDocument'
  * @template C configuration cascade type
  */
 export interface Environment<X extends Extension = Extension, C extends ConfigurationCascade = ConfigurationCascade> {
+    /**
+     * The currently open workspace roots (typically a single repository).
+     */
+    readonly roots: WorkspaceRoot[] | null
+
     /**
      * The text documents that are currently visible. Each text document is represented to extensions as being
      * in its own visible CodeEditor.
@@ -31,6 +37,7 @@ export interface Environment<X extends Extension = Extension, C extends Configur
 
 /** An empty Sourcegraph extension client environment. */
 export const EMPTY_ENVIRONMENT: Environment<any, any> = {
+    roots: null,
     visibleTextDocuments: null,
     extensions: null,
     configuration: { merged: {} },

src/extension/api/fileSystem.ts

@@ -0,0 +1,15 @@
+import { FileType, URI } from 'sourcegraph'
+import { ClientFileSystemAPI } from '../../client/api/fileSystem'
+
+/** @internal */
+export class ExtFileSystem {
+    constructor(private proxy: ClientFileSystemAPI) {}
+
+    public readDirectory(uri: URI): Promise<[string, FileType][]> {
+        return this.proxy.$readDirectory(uri.toString())
+    }
+
+    public readFile(uri: URI): Promise<Uint8Array> {
+        return this.proxy.$readFile(uri.toString())
+    }
+}

src/extension/api/roots.ts

@@ -0,0 +1,33 @@
+import { Observable, Subject } from 'rxjs'
+import * as sourcegraph from 'sourcegraph'
+import { WorkspaceRoot as PlainWorkspaceRoot } from '../../protocol/plainTypes'
+import { URI } from '../../shared/uri'
+
+/** @internal */
+export interface ExtRootsAPI {
+    $acceptRoots(roots: PlainWorkspaceRoot[]): void
+}
+
+/** @internal */
+export class ExtRoots implements ExtRootsAPI {
+    private roots: ReadonlyArray<sourcegraph.WorkspaceRoot> = []
+
+    /**
+     * Returns all workspace roots.
+     *
+     * @internal
+     */
+    public getAll(): ReadonlyArray<sourcegraph.WorkspaceRoot> {
+        return this.roots
+    }
+
+    private changes = new Subject<void>()
+    public readonly onDidChange: Observable<void> = this.changes
+
+    public $acceptRoots(roots: PlainWorkspaceRoot[]): void {
+        this.roots = Object.freeze(
+            roots.map(plain => ({ ...plain, uri: URI.parse(plain.uri) } as sourcegraph.WorkspaceRoot))
+        )
+        this.changes.next()
+    }
+}

src/extension/extensionHost.ts

@@ -8,7 +8,9 @@ import { ExtCommands } from './api/commands'
 import { ExtConfiguration } from './api/configuration'
 import { ExtContext } from './api/context'
 import { ExtDocuments } from './api/documents'
+import { ExtFileSystem } from './api/fileSystem'
 import { ExtLanguageFeatures } from './api/languageFeatures'
+import { ExtRoots } from './api/roots'
 import { ExtSearch } from './api/search'
 import { ExtViews } from './api/views'
 import { ExtWindows } from './api/windows'
@@ -81,6 +83,12 @@ function createExtensionHandle(initData: InitData, connection: Connection): type
     const documents = new ExtDocuments(sync)
     handleRequests(connection, 'documents', documents)
 
+    const roots = new ExtRoots()
+    handleRequests(connection, 'roots', roots)
+
+    const fileSystem = new ExtFileSystem(proxy('fileSystem'))
+    handleRequests(connection, 'fileSystem', fileSystem)
+
     const windows = new ExtWindows(proxy('windows'), proxy('codeEditor'), documents)
     handleRequests(connection, 'windows', windows)
 
@@ -109,6 +117,12 @@ function createExtensionHandle(initData: InitData, connection: Connection): type
             PlainText: sourcegraph.MarkupKind.PlainText,
             Markdown: sourcegraph.MarkupKind.Markdown,
         },
+        FileType: {
+            Unknown: sourcegraph.FileType.Unknown,
+            File: sourcegraph.FileType.File,
+            Directory: sourcegraph.FileType.Directory,
+            SymbolicLink: sourcegraph.FileType.SymbolicLink,
+        },
 
         app: {
             get activeWindow(): sourcegraph.Window | undefined {
@@ -125,6 +139,11 @@ function createExtensionHandle(initData: InitData, connection: Connection): type
                 return documents.getAll()
             },
             onDidOpenTextDocument: documents.onDidOpenTextDocument,
+            fileSystem,
+            get roots(): ReadonlyArray<sourcegraph.WorkspaceRoot> {
+                return roots.getAll()
+            },
+            onDidChangeRoots: roots.onDidChange,
         },
 
         configuration: {

src/integration-test/fileSystem.test.ts

@@ -0,0 +1,32 @@
+import * as assert from 'assert'
+import * as sourcegraph from 'sourcegraph'
+import { URI } from '../shared/uri'
+import { tryCatchPromise } from '../util'
+import { integrationTestContext } from './helpers.test'
+
+describe('File system (integration)', () => {
+    describe('workspace.fileSystem', () => {
+        it('readDirectory', async () => {
+            const { extensionHost, ready } = await integrationTestContext()
+
+            await ready
+            assert.deepStrictEqual(await extensionHost.workspace.fileSystem.readDirectory(URI.parse('file:///')), [
+                ['f', 1 as sourcegraph.FileType.File],
+            ] as [string, sourcegraph.FileType][])
+        })
+
+        it('readFile', async () => {
+            const { extensionHost, ready } = await integrationTestContext()
+
+            await ready
+            assert.deepStrictEqual(
+                await extensionHost.workspace.fileSystem.readFile(URI.parse('file:///f')),
+                new Uint8Array([116]) as Uint8Array
+            )
+            // tslint:disable-next-line:no-floating-promises
+            assert.rejects(
+                tryCatchPromise(() => extensionHost.workspace.fileSystem.readFile(URI.parse('file:///does-not-exist')))
+            )
+        })
+    })
+})

src/integration-test/helpers.test.ts

@@ -1,11 +1,13 @@
 import { filter, first } from 'rxjs/operators'
 import * as sourcegraph from 'sourcegraph'
+import { TextEncoder } from 'util'
 import { Controller } from '../client/controller'
 import { Environment } from '../client/environment'
 import { createExtensionHost } from '../extension/extensionHost'
 import { createMessageTransports } from '../protocol/jsonrpc2/helpers.test'
 
 const FIXTURE_ENVIRONMENT: Environment = {
+    roots: [{ uri: 'file:///' }],
     visibleTextDocuments: [
         {
             uri: 'file:///f',
@@ -38,6 +40,7 @@ export async function integrationTestContext(): Promise<
 
     const clientController = new Controller({
         clientOptions: () => ({ createMessageTransports: () => clientTransports }),
+        getFileSystem: () => memoryFileSystem({ 'file:///f': 't' }),
     })
     clientController.setEnvironment(FIXTURE_ENVIRONMENT)
 
@@ -81,6 +84,39 @@ export async function integrationTestContext(): Promise<
     }
 }
 
+/**
+ * Creates a new implementation of {@link sourcegraph.FileSystem} backed by an object whose keys are URIs and whose
+ * values are the file contents.
+ *
+ * @todo Support nested file systems.
+ *
+ * @param data An object of URI to file contents. All entries are treated as files, and no hierarchy is supported.
+ */
+export function memoryFileSystem(data: { [uri: string]: string }): sourcegraph.FileSystem {
+    data = data || {}
+    return {
+        readDirectory: dir =>
+            Promise.resolve(
+                Object.keys(data).map(
+                    // HACK: Can't use sourcegraph.FileType.File value or else it complains "Cannot find module
+                    // 'sourcegraph'".
+                    uri =>
+                        [uri.toString().replace(dir.toString(), ''), 1 as sourcegraph.FileType.File] as [
+                            string,
+                            sourcegraph.FileType
+                        ]
+                )
+            ),
+        readFile: uri => {
+            const contents = data[uri.toString()]
+            if (contents === undefined) {
+                throw new Error(`file not found: ${uri}`)
+            }
+            return Promise.resolve(new TextEncoder().encode(contents))
+        },
+    }
+}
+
 /** @internal */
 async function ready({ extensionHost }: TestContext): Promise<void> {
     await extensionHost.internal.sync()

src/integration-test/roots.test.ts

@@ -0,0 +1,50 @@
+import * as assert from 'assert'
+import { WorkspaceRoot } from 'sourcegraph'
+import { URI } from '../shared/uri'
+import { collectSubscribableValues, integrationTestContext } from './helpers.test'
+
+describe('Workspace roots (integration)', () => {
+    describe('workspace.roots', () => {
+        it('lists roots', async () => {
+            const { extensionHost, ready } = await integrationTestContext()
+
+            await ready
+            assert.deepStrictEqual(extensionHost.workspace.roots, [{ uri: URI.parse('file:///') }] as WorkspaceRoot[])
+        })
+
+        it('adds new text documents', async () => {
+            const { clientController, extensionHost, getEnvironment, ready } = await integrationTestContext()
+
+            const prevEnvironment = getEnvironment()
+            clientController.setEnvironment({
+                ...prevEnvironment,
+                roots: [{ uri: 'file:///a' }, { uri: 'file:///b' }],
+            })
+
+            await ready
+            assert.deepStrictEqual(extensionHost.workspace.roots, [
+                { uri: URI.parse('file:///a') },
+                { uri: URI.parse('file:///b') },
+            ] as WorkspaceRoot[])
+        })
+    })
+
+    describe('workspace.onDidChangeRoots', () => {
+        it('fires when a root is added or removed', async () => {
+            const { clientController, extensionHost, getEnvironment, ready } = await integrationTestContext()
+
+            await ready
+            const values = collectSubscribableValues(extensionHost.workspace.onDidChangeRoots)
+            assert.deepStrictEqual(values, [] as void[])
+
+            const prevEnvironment = getEnvironment()
+            clientController.setEnvironment({
+                ...prevEnvironment,
+                roots: [{ uri: 'file:///a' }],
+            })
+            await extensionHost.internal.sync()
+
+            assert.deepStrictEqual(values, [void 0])
+        })
+    })
+})

src/protocol/plainTypes.ts

@@ -1,5 +1,10 @@
 import * as sourcegraph from 'sourcegraph'
 
+/** The plain properties of a {@link module:sourcegraph.WorkspaceRoot}, without methods and accessors. */
+export interface WorkspaceRoot extends Pick<sourcegraph.WorkspaceRoot, 'repository'> {
+    uri: string
+}
+
 /** The plain properties of a {@link module:sourcegraph.Position}, without methods and accessors. */
 export interface Position extends Pick<sourcegraph.Position, 'line' | 'character'> {}