Fix warnings, docs, and repo structure (#651)

.github/workflows/scala.yml

@@ -66,35 +66,29 @@ jobs:
         path: ./project/target
         key: ${{ runner.os }}-sbt-project-${{ hashFiles('project/**') }}
         restore-keys: ${{ runner.os }}-sbt-project-
-    - name: Cache Unused (JVM)
-      uses: actions/cache@v1.1.2
-      with:
-        path: ./common/unused/.jvm
-        key: ${{ runner.os }}-unused-jvm-${{ hashFiles('common/unused/src/**') }}
-        restore-keys: ${{ runner.os }}-unused-jvm-
     - name: Cache Logger (JVM)
       uses: actions/cache@v1.1.2
       with:
-        path: ./common/logger/.jvm
-        key: ${{ runner.os }}-logger-jvm-${{ hashFiles('common/logger/src/**') }}
+        path: ./lib/logger/.jvm
+        key: ${{ runner.os }}-logger-jvm-${{ hashFiles('lib/logger/src/**') }}
         restore-keys: ${{ runner.os }}-logger-jvm-
     - name: Cache Flexer (JVM)
       uses: actions/cache@v1.1.2
       with:
-        path: ./common/flexer/.jvm
-        key: ${{ runner.os }}-flexer-jvm-${{ hashFiles('common/flexer/src/**') }}
+        path: ./lib/flexer/.jvm
+        key: ${{ runner.os }}-flexer-jvm-${{ hashFiles('lib/flexer/src/**') }}
         restore-keys: ${{ runner.os }}-flexer-jvm-
     - name: Cache Syntax Definition (JVM)
       uses: actions/cache@v1.1.2
       with:
-        path: ./common/syntax/definition/.jvm
-        key: ${{ runner.os }}-syntax-definition-jvm-${{ hashFiles('common/syntax/definition/src/**') }}
+        path: ./lib/syntax/definition/.jvm
+        key: ${{ runner.os }}-syntax-definition-jvm-${{ hashFiles('lib/syntax/definition/src/**') }}
         restore-keys: ${{ runner.os }}-syntax-defintion-jvm-
     - name: Cache Syntax Specialization (JVM)
       uses: actions/cache@v1.1.2
       with:
-        path: ./common/syntax/specialization/jvm
-        key: ${{ runner.os }}-syntax-specialization-jvm-${{ hashFiles('common/syntax/specialization/shared/src/**') }}
+        path: ./lib/syntax/specialization/jvm
+        key: ${{ runner.os }}-syntax-specialization-jvm-${{ hashFiles('lib/syntax/specialization/shared/src/**') }}
         restore-keys: ${{ runner.os }}-syntax-specialization-jvm-
 
     # Tests
@@ -107,7 +101,7 @@ jobs:
     - name: Build the Uberjar
       run: sbt -no-colors runner/assembly
     - name: Test the Uberjar
-      run: ./enso.jar --run ci/Test.enso
+      run: ./enso.jar --run tools/ci/Test.enso
 
   # This job is responsible for building the artifacts
   build:
@@ -152,65 +146,53 @@ jobs:
         path: ./project/target
         key: ${{ runner.os }}-sbt-project-${{ hashFiles('project/**') }}
         restore-keys: ${{ runner.os }}-sbt-project-
-    - name: Cache Unused (JVM)
-      uses: actions/cache@v1.1.2
-      with:
-        path: ./common/unused/.jvm
-        key: ${{ runner.os }}-unused-jvm-${{ hashFiles('common/unused/src/**') }}
-        restore-keys: ${{ runner.os }}-unused-jvm-
     - name: Cache Logger (JVM)
       uses: actions/cache@v1.1.2
       with:
-        path: ./common/logger/.jvm
-        key: ${{ runner.os }}-logger-jvm-${{ hashFiles('common/logger/src/**') }}
+        path: ./lib/logger/.jvm
+        key: ${{ runner.os }}-logger-jvm-${{ hashFiles('lib/logger/src/**') }}
         restore-keys: ${{ runner.os }}-logger-jvm-
     - name: Cache Flexer (JVM)
       uses: actions/cache@v1.1.2
       with:
-        path: ./common/flexer/.jvm
-        key: ${{ runner.os }}-flexer-jvm-${{ hashFiles('common/flexer/src/**') }}
+        path: ./lib/flexer/.jvm
+        key: ${{ runner.os }}-flexer-jvm-${{ hashFiles('lib/flexer/src/**') }}
         restore-keys: ${{ runner.os }}-flexer-jvm-
     - name: Cache Syntax Definition (JVM)
       uses: actions/cache@v1.1.2
       with:
-        path: ./common/syntax/definition/.jvm
-        key: ${{ runner.os }}-syntax-definition-jvm-${{ hashFiles('common/syntax/definition/src/**') }}
+        path: ./lib/syntax/definition/.jvm
+        key: ${{ runner.os }}-syntax-definition-jvm-${{ hashFiles('lib/syntax/definition/src/**') }}
         restore-keys: ${{ runner.os }}-syntax-defintion-jvm-
     - name: Cache Syntax Specialization (JVM)
       uses: actions/cache@v1.1.2
       with:
-        path: ./common/syntax/specialization/jvm
-        key: ${{ runner.os }}-syntax-specialization-jvm-${{ hashFiles('common/syntax/specialization/shared/src/**') }}
+        path: ./lib/syntax/specialization/jvm
+        key: ${{ runner.os }}-syntax-specialization-jvm-${{ hashFiles('lib/syntax/specialization/shared/src/**') }}
         restore-keys: ${{ runner.os }}-syntax-specialization-jvm-
-    - name: Cache Unused (JS)
-      uses: actions/cache@v1.1.2
-      with:
-        path: ./common/unused/.js
-        key: ${{ runner.os }}-unused-js-${{ hashFiles('common/unused/src/**') }}
-        restore-keys: ${{ runner.os }}-unused-js-
     - name: Cache Logger (JS)
       uses: actions/cache@v1.1.2
       with:
-        path: ./common/logger/.js
-        key: ${{ runner.os }}-logger-js-${{ hashFiles('common/logger/src/**') }}
+        path: ./lib/logger/.js
+        key: ${{ runner.os }}-logger-js-${{ hashFiles('lib/logger/src/**') }}
         restore-keys: ${{ runner.os }}-logger-js-
     - name: Cache Flexer (JS)
       uses: actions/cache@v1.1.2
       with:
-        path: ./common/flexer/.js
-        key: ${{ runner.os }}-flexer-js-${{ hashFiles('common/flexer/src/**') }}
+        path: ./lib/flexer/.js
+        key: ${{ runner.os }}-flexer-js-${{ hashFiles('lib/flexer/src/**') }}
         restore-keys: ${{ runner.os }}-flexer-js-
     - name: Cache Syntax Definition (JS)
       uses: actions/cache@v1.1.2
       with:
-        path: ./common/syntax/definition/.js
-        key: ${{ runner.os }}-syntax-definition-js-${{ hashFiles('common/syntax/definition/src/**') }}
+        path: ./lib/syntax/definition/.js
+        key: ${{ runner.os }}-syntax-definition-js-${{ hashFiles('lib/syntax/definition/src/**') }}
         restore-keys: ${{ runner.os }}-syntax-defintion-js-
     - name: Cache Syntax Specialization (JS)
       uses: actions/cache@v1.1.2
       with:
-        path: ./common/syntax/specialization/js
-        key: ${{ runner.os }}-syntax-specialization-js-${{ hashFiles('common/syntax/specialization/shared/src/**') }}
+        path: ./lib/syntax/specialization/js
+        key: ${{ runner.os }}-syntax-specialization-js-${{ hashFiles('lib/syntax/specialization/shared/src/**') }}
         restore-keys: ${{ runner.os }}-syntax-specialization-js-
 
     # Builds
@@ -251,4 +233,3 @@ jobs:
         null
         text
         EOF
-

build.sbt

@@ -68,8 +68,7 @@ scalacOptions in ThisBuild ++= Seq(
   "-Ywarn-unused:locals",               // Warn if a local definition is unused.
   "-Ywarn-unused:patvars",              // Warn if a variable bound in a pattern is unused.
   "-Ywarn-unused:privates",             // Warn if a private member is unused.
-  "-Ywarn-unused:params",               // Warn if a value parameter is unused.
-  "-Ywarn-value-discard"                // Warn when non-Unit expression results are unused.
+  "-Ywarn-unused:params"                // Warn if a value parameter is unused.
 )
 
 /////////////////////////////////
@@ -89,19 +88,18 @@ lazy val buildNativeImage =
 lazy val enso = (project in file("."))
   .settings(version := "0.1")
   .aggregate(
-    unused.jvm,
     flexer.jvm,
-    syntax_definition.jvm,
+    `syntax-definition`.jvm,
     syntax.jvm,
     pkg,
     runtime,
-    polyglot_api,
-    parser_service,
-    file_manager,
-    project_manager,
+    `polyglot-api`,
+    `parser-service`,
+    `file-manager`,
+    `project-manager`,
     graph,
     runner,
-    language_server
+    `language-server`
   )
   .settings(Global / concurrentRestrictions += Tags.exclusive(Exclusive))
 
@@ -174,8 +172,7 @@ val jsSettings = Seq(
 lazy val logger = crossProject(JVMPlatform, JSPlatform)
   .withoutSuffixFor(JVMPlatform)
   .crossType(CrossType.Pure)
-  .in(file("common/logger"))
-  .dependsOn(unused)
+  .in(file("lib/logger"))
   .settings(
     version := "0.1",
     libraryDependencies ++= scala_compiler
@@ -185,7 +182,7 @@ lazy val logger = crossProject(JVMPlatform, JSPlatform)
 lazy val flexer = crossProject(JVMPlatform, JSPlatform)
   .withoutSuffixFor(JVMPlatform)
   .crossType(CrossType.Pure)
-  .in(file("common/flexer"))
+  .in(file("lib/flexer"))
   .dependsOn(logger)
   .settings(
     version := "0.1",
@@ -198,19 +195,13 @@ lazy val flexer = crossProject(JVMPlatform, JSPlatform)
   )
   .jsSettings(jsSettings)
 
-lazy val unused = crossProject(JVMPlatform, JSPlatform)
+lazy val `syntax-definition` = crossProject(JVMPlatform, JSPlatform)
   .withoutSuffixFor(JVMPlatform)
   .crossType(CrossType.Pure)
-  .in(file("common/unused"))
-  .settings(version := "0.1", scalacOptions += "-nowarn")
-  .jsSettings(testFrameworks := Nil)
-
-lazy val syntax_definition = crossProject(JVMPlatform, JSPlatform)
-  .withoutSuffixFor(JVMPlatform)
-  .crossType(CrossType.Pure)
-  .in(file("common/syntax/definition"))
+  .in(file("lib/syntax/definition"))
   .dependsOn(logger, flexer)
   .settings(
+    scalacOptions ++= Seq("-Ypatmat-exhaust-depth", "off"),
     libraryDependencies ++= monocle ++ scala_compiler ++ Seq(
       "org.typelevel" %%% "cats-core"     % catsVersion,
       "org.typelevel" %%% "kittens"       % "2.0.0",
@@ -225,12 +216,13 @@ lazy val syntax_definition = crossProject(JVMPlatform, JSPlatform)
 lazy val syntax = crossProject(JVMPlatform, JSPlatform)
   .withoutSuffixFor(JVMPlatform)
   .crossType(CrossType.Full)
-  .in(file("common/syntax/specialization"))
-  .dependsOn(logger, flexer, syntax_definition)
+  .in(file("lib/syntax/specialization"))
+  .dependsOn(logger, flexer, `syntax-definition`)
   .configs(Test)
   .configs(Benchmark)
   .settings(
     testFrameworks := Nil,
+    scalacOptions ++= Seq("-Ypatmat-exhaust-depth", "off"),
     mainClass in (Compile, run) := Some("org.enso.syntax.text.Main"),
     version := "0.1",
     logBuffered := false,
@@ -244,7 +236,7 @@ lazy val syntax = crossProject(JVMPlatform, JSPlatform)
     compile := (Compile / compile)
       .dependsOn(Def.taskDyn {
         val parserCompile =
-          (syntax_definition.jvm / Compile / compileIncremental).value
+          (`syntax-definition`.jvm / Compile / compileIncremental).value
         if (parserCompile.hasModified) {
           Def.task {
             streams.value.log.info("Parser changed, forcing recompilation.")
@@ -272,14 +264,14 @@ lazy val syntax = crossProject(JVMPlatform, JSPlatform)
     Compile / fullOptJS / artifactPath := file("target/scala-parser.js")
   )
 
-lazy val parser_service = (project in file("common/parser-service"))
+lazy val `parser-service` = (project in file("lib/parser-service"))
   .dependsOn(syntax.jvm)
   .settings(
     libraryDependencies ++= akka,
     mainClass := Some("org.enso.ParserServiceMain")
   )
 
-lazy val graph = (project in file("common/graph/"))
+lazy val graph = (project in file("lib/graph/"))
   .dependsOn(logger.jvm)
   .configs(Test)
   .settings(
@@ -315,7 +307,7 @@ lazy val graph = (project in file("common/graph/"))
     )
   )
 
-lazy val pkg = (project in file("common/pkg"))
+lazy val pkg = (project in file("lib/pkg"))
   .settings(
     mainClass in (Compile, run) := Some("org.enso.pkg.Main"),
     version := "0.1",
@@ -325,7 +317,7 @@ lazy val pkg = (project in file("common/pkg"))
     )
   )
 
-lazy val file_manager = (project in file("common/file-manager"))
+lazy val `file-manager` = (project in file("lib/file-manager"))
   .settings(
     (Compile / mainClass) := Some("org.enso.filemanager.FileManager")
   )
@@ -341,7 +333,7 @@ lazy val file_manager = (project in file("common/file-manager"))
     libraryDependencies += "io.methvin" % "directory-watcher" % "0.9.6"
   )
 
-lazy val project_manager = (project in file("common/project-manager"))
+lazy val `project-manager` = (project in file("lib/project-manager"))
   .settings(
     (Compile / mainClass) := Some("org.enso.projectmanager.boot.ProjectManager")
   )
@@ -377,27 +369,36 @@ lazy val project_manager = (project in file("common/project-manager"))
     )
   )
   .dependsOn(pkg)
-  .dependsOn(language_server)
+  .dependsOn(`language-server`)
   .dependsOn(`json-rpc-server`)
   .dependsOn(`json-rpc-server-test` % Test)
 
-//////////////////////
-//// Sub Projects ////
-//////////////////////
+lazy val `json-rpc-server` = project
+  .in(file("lib/json-rpc-server"))
+  .settings(
+    libraryDependencies ++= akka,
+    libraryDependencies ++= circe,
+    libraryDependencies ++= Seq(
+      "io.circe"      %% "circe-literal" % circeVersion,
+      akkaTestkit     % Test,
+      "org.scalatest" %% "scalatest" % "3.2.0-M2" % Test
+    )
+  )
 
-val truffleRunOptions = Seq(
-  "-Dpolyglot.engine.IterativePartialEscape=true",
-  "-XX:-UseJVMCIClassLoader",
-  "-Dpolyglot.engine.BackgroundCompilation=false",
-  "-Dgraalvm.locatorDisabled=true"
-)
+lazy val `json-rpc-server-test` = project
+  .in(file("lib/json-rpc-server-test"))
+  .settings(
+    libraryDependencies ++= akka,
+    libraryDependencies ++= circe,
+    libraryDependencies ++= Seq(
+      "io.circe" %% "circe-literal" % circeVersion,
+      akkaTestkit,
+      "org.scalatest" %% "scalatest" % "3.2.0-M2"
+    )
+  )
+  .dependsOn(`json-rpc-server`)
 
-val truffleRunOptionsSettings = Seq(
-  fork := true,
-  javaOptions ++= truffleRunOptions
-)
-
-lazy val core_definition = (project in file("engine/core-definition"))
+lazy val `core-definition` = (project in file("lib/core-definition"))
   .configs(Benchmark)
   .settings(
     version := "0.1",
@@ -428,7 +429,23 @@ lazy val core_definition = (project in file("engine/core-definition"))
   .dependsOn(graph)
   .dependsOn(syntax.jvm)
 
-lazy val polyglot_api = project
+//////////////////////
+//// Sub Projects ////
+//////////////////////
+
+val truffleRunOptions = Seq(
+  "-Dpolyglot.engine.IterativePartialEscape=true",
+  "-XX:-UseJVMCIClassLoader",
+  "-Dpolyglot.engine.BackgroundCompilation=false",
+  "-Dgraalvm.locatorDisabled=true"
+)
+
+val truffleRunOptionsSettings = Seq(
+  fork := true,
+  javaOptions ++= truffleRunOptions
+)
+
+lazy val `polyglot-api` = project
   .in(file("engine/polyglot-api"))
   .settings(
     Test / fork := true,
@@ -462,7 +479,7 @@ lazy val polyglot_api = project
   )
   .dependsOn(pkg)
 
-lazy val language_server = (project in file("engine/language-server"))
+lazy val `language-server` = (project in file("engine/language-server"))
   .settings(
     libraryDependencies ++= akka ++ circe ++ Seq(
       "ch.qos.logback"             % "logback-classic" % "1.2.3",
@@ -491,7 +508,7 @@ lazy val language_server = (project in file("engine/language-server"))
       new TestFramework("org.scalameter.ScalaMeterFramework")
     )
   )
-  .dependsOn(polyglot_api)
+  .dependsOn(`polyglot-api`)
   .dependsOn(`json-rpc-server`)
   .dependsOn(`json-rpc-server-test` % Test)
 
@@ -524,10 +541,10 @@ lazy val runtime = (project in file("engine/runtime"))
       "eu.timepit"          %% "refined"              % "0.9.12"
     ),
     // Note [Unmanaged Classpath]
-    Compile / unmanagedClasspath += (core_definition / Compile / packageBin).value,
-    Test / unmanagedClasspath += (core_definition / Compile / packageBin).value,
+    Compile / unmanagedClasspath += (`core-definition` / Compile / packageBin).value,
+    Test / unmanagedClasspath += (`core-definition` / Compile / packageBin).value,
     Compile / compile := (Compile / compile)
-      .dependsOn(core_definition / Compile / packageBin)
+      .dependsOn(`core-definition` / Compile / packageBin)
       .value
   )
   .settings(
@@ -569,7 +586,7 @@ lazy val runtime = (project in file("engine/runtime"))
   .dependsOn(pkg)
   .dependsOn(syntax.jvm)
   .dependsOn(graph)
-  .dependsOn(polyglot_api)
+  .dependsOn(`polyglot-api`)
 
 /* Note [Unmanaged Classpath]
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -651,30 +668,5 @@ lazy val runner = project
   )
   .dependsOn(runtime)
   .dependsOn(pkg)
-  .dependsOn(language_server)
-  .dependsOn(polyglot_api)
-
-lazy val `json-rpc-server` = project
-  .in(file("common/json-rpc-server"))
-  .settings(
-    libraryDependencies ++= akka,
-    libraryDependencies ++= circe,
-    libraryDependencies ++= Seq(
-      "io.circe"      %% "circe-literal" % circeVersion,
-      akkaTestkit     % Test,
-      "org.scalatest" %% "scalatest" % "3.2.0-M2" % Test
-    )
-  )
-
-lazy val `json-rpc-server-test` = project
-  .in(file("common/json-rpc-server-test"))
-  .settings(
-    libraryDependencies ++= akka,
-    libraryDependencies ++= circe,
-    libraryDependencies ++= Seq(
-      "io.circe" %% "circe-literal" % circeVersion,
-      akkaTestkit,
-      "org.scalatest" %% "scalatest" % "3.2.0-M2"
-    )
-  )
-  .dependsOn(`json-rpc-server`)
+  .dependsOn(`language-server`)
+  .dependsOn(`polyglot-api`)

common/unused/src/main/scala/org/enso/lint/Unused.scala

@@ -1,5 +0,0 @@
-package org.enso.lint
-
-object Unused {
-  def apply(arg: Any): Unit = {}
-}

doc/README.md

@@ -0,0 +1,3 @@
+# Enso Documentation
+This folder contains the documentation for the implementation of the Enso
+programming language.

doc/language-server/README.md

@@ -0,0 +1,24 @@
+# Language Server Documentation
+The Enso Language Server is responsible for providing language services to the
+Enso IDE (and other clients). This mainly involves speaking the Enso protocol
+and orchestrating the runtime in response to this. It is responsible for:
+
+- **Introspection Services:** Giving clients the ability to observe information
+  about their running code including values, types, profiling information, and
+  debugging.
+- **Code Execution:** The ability for clients to execute arbitrary Enso code in
+  arbitrary scopes. This can be used in conjunction with the above to provide
+  a REPL with an integrated debugger.
+- **Code Completion:** Sophisticated completion functionality that refines
+  suggestions intelligently based on context.
+- **Node Management:** Tracking and providing the language server's internal
+  node representation of the Enso program.
+- **Code Analysis:** Analysis functionality for Enso code (e.g. find usages,
+  jump-to-definition, and so on).
+- **Refactoring:** Refactoring functionality for Enso code (e.g. rename, move,
+  extract, and so on).
+- **Type Interactions:** Features for type-driven-development that allow users
+  to interact with the types of their programs.
+
+This folder contains all documentation pertaining to the Language Server.
+

doc/language-server/specification/enso-protocol.md

@@ -1,4 +1,4 @@
-# The Enso Engine Services
+# The Enso Protocol
 Enso is a sophisticated language, but in order to provide a great user
 experience to our users we also need the ability to provide great tooling. This
 tooling means a language server, but it also means a set of extra peripheral

doc/runtime/README.md

@@ -0,0 +1,21 @@
+# Enso Runtime
+The Enso runtime refers to both the compiler and the optimising JIT runtime for
+Enso. While this might seem like a strange choice, it makes sense internally as
+the components are integrated to a level not seen in most languages. It
+encompasses the following functionality:
+
+- **Parsing:** Taking Enso code as input and generating an AST that maintains a
+  sophisticated set of information about the input.
+- **Desugaring:** Reducing the user-facing Enso code into a simplified language
+  known as `Core`.
+- **Type Inference:** Inferring the types of bindings in the user's code.
+- **Type Checking:** Checking that the inferred and provided types for bindings
+  match up across the codebase.
+- **Optimisation:** Static optimisation processes to improve the performance of
+  the user's program.
+- **Code Execution:** Actually running the Enso code.
+- **Introspection Hooks:** Providing hooks into the running code to allow the
+  language server to inspect information about the code as it runs.
+
+This folder contains all of the documentation related to the runtime.
+

engine/README.md

@@ -1,47 +1,11 @@
 # The Enso Engine
 The Enso engine is the codebase responsible for compiling and executing Enso
-code, as well as providing language server functionality to users of the 
+code, as well as providing language server functionality to users of the
 language. It is subdivided into two major components:
 
-- [Runtime](#runtime)
-- [Language Server](#language-server)
+- [Language Server](./language-server): The Enso language service.
+- [Polyglot API](./polyglot-api): The truffle-boundary safe API for
+  communication between the language server and the runtime.
+- [Runner](./runner): The command-line interface for Enso.
+- [Runtime](./runtime): The compiler and interpreter for Enso.
 
-## Runtime
-The Enso [runtime](/runtime) is responsible for the actual execution of Enso
-code. This means that it encompasses the following functionality:
-
-- **Parsing:** Taking Enso code as input and generating an AST that maintains a
-  sophisticated set of information about the input.
-- **Desugaring:** Reducing the user-facing Enso code into a simplified language
-  known as `Core`.
-- **Type Inference:** Inferring the types of bindings in the user's code.
-- **Type Checking:** Checking that the inferred and provided types for bindings
-  match up across the codebase.
-- **Optimisation:** Static optimisation processes to improve the performance of
-  the user's program.
-- **Code Execution:** Actually running the Enso code.
-- **Introspection Hooks:** Providing hooks into the running code to allow the
-  language server to inspect information about the code as it runs.
-
-## Language Server
-The Enso Language Server is responsibile for providing a remote-communication
-protocol for the runtime, exposing many of its features to the users. In
-addition it provides the backing service for much of the IDE functionality
-associated with the language. It encompasses the following functionality:
-
-- **Introspection Services:** Giving clients the ability to observe information
-  about their running code including values, types, profiling information, and
-  debugging.
-- **Code Execution:** The ability for clients to execute arbitrary Enso code in
-  arbitrary scopes. This can be used in conjunction with the above to provide
-  a REPL with an integrated debugger.
-- **Code Completion:** Sophisticated completion functionality that refines
-  suggestions intelligently based on context.
-- **Node Management:** Tracking and providing the language server's internal
-  node representation of the Enso program.
-- **Code Analysis:** Analysis functionality for Enso code (e.g. find usages,
-  jump-to-definition, and so on).
-- **Refactoring:** Refactoring functionality for Enso code (e.g. rename, move,
-  extract, and so on).
-- **Type Interactions:** Features for type-driven-development that allow users
-  to interact with the types of their programs.

engine/language-server/README.md

@@ -0,0 +1,23 @@
+# Enso Language Server
+The Enso Language Server is responsibile for providing a remote-communication
+protocol for the runtime, exposing many of its features to the users. In
+addition it provides the backing service for much of the IDE functionality
+associated with the language. It encompasses the following functionality:
+
+- **Introspection Services:** Giving clients the ability to observe information
+  about their running code including values, types, profiling information, and
+  debugging.
+- **Code Execution:** The ability for clients to execute arbitrary Enso code in
+  arbitrary scopes. This can be used in conjunction with the above to provide
+  a REPL with an integrated debugger.
+- **Code Completion:** Sophisticated completion functionality that refines
+  suggestions intelligently based on context.
+- **Node Management:** Tracking and providing the language server's internal
+  node representation of the Enso program.
+- **Code Analysis:** Analysis functionality for Enso code (e.g. find usages,
+  jump-to-definition, and so on).
+- **Refactoring:** Refactoring functionality for Enso code (e.g. rename, move,
+  extract, and so on).
+- **Type Interactions:** Features for type-driven-development that allow users
+  to interact with the types of their programs.
+

engine/language-server/src/main/scala/org/enso/languageserver/boot/LanguageServerComponent.scala

@@ -74,6 +74,7 @@ class LanguageServerComponent(config: LanguageServerConfig)
           _ <- Future { mainModule.context.close(true) }.recover(logError)
           _ <- Future { maybeServerState = None }
         } yield ComponentStopped
+       Future()
     }
   }
 

engine/runtime/README.md

@@ -1,4 +1,19 @@
-# Enso Compiler and Interpreter
+# Enso Runtime
+The Enso [runtime](/runtime) is responsible for the actual execution of Enso
+code. This means that it encompasses the following functionality:
+
+- **Parsing:** Taking Enso code as input and generating an AST that maintains a
+  sophisticated set of information about the input.
+- **Desugaring:** Reducing the user-facing Enso code into a simplified language
+  known as `Core`.
+- **Type Inference:** Inferring the types of bindings in the user's code.
+- **Type Checking:** Checking that the inferred and provided types for bindings
+  match up across the codebase.
+- **Optimisation:** Static optimisation processes to improve the performance of
+  the user's program.
+- **Code Execution:** Actually running the Enso code.
+- **Introspection Hooks:** Providing hooks into the running code to allow the
+  language server to inspect information about the code as it runs.
 
 ### Truffle Nodes creation convention
 

engine/runtime/src/test/scala/org/enso/interpreter/test/instrument/RuntimeServerTest.scala

@@ -86,7 +86,7 @@ class RuntimeServerTest
 
   "Runtime server" should "allow executing a stack of functions by entering them through call-sites" in {
     val metadata = new Metadata
-    val idMainX  = metadata.addItem(14, 7)
+    val _        = metadata.addItem(14, 7)
     val idMainY  = metadata.addItem(30, 7)
     val idFooY   = metadata.addItem(85, 8)
     val idFooZ   = metadata.addItem(102, 5)

lib/README.md

@@ -0,0 +1,3 @@
+# Libraries
+This directory contains the libraries that should remain in this project, but 
+that are not technically _part_ of the main language implementation itself.

lib/core-definition/README.md

@@ -0,0 +1,4 @@
+# Core Definition
+This library contains the definition of the Enso core language. This language is
+used in the Enso compiler as an intermediate representation to enable both a
+flexible, pass-based architecture, and integrated type-checking.

lib/file-manager/README.md

@@ -0,0 +1,4 @@
+# File Manager
+This library implements the functionality that backs the file-management
+operations that are part of the
+[Enso Protocol](../../doc/language-server/specification/enso-protocol.md).

lib/flexer/README.md

@@ -0,0 +1,3 @@
+# Flexer
+The Flexer is an incredibly fast and flexible lexing engine for Enso source
+code.

lib/flexer/src/main/scala/org/enso/flexer/spec/Macro.scala

@@ -1,8 +1,8 @@
 package org.enso.flexer.spec
 
 import org.enso.flexer.Parser
-import org.enso.lint.Unused
 
+import scala.annotation.unused
 import scala.reflect.macros.blackbox.Context
 
 // FIXME: Needs to be refactored. Contains deprecated API usage
@@ -28,9 +28,8 @@ object Macro {
 
   def compileImpl[T: c.WeakTypeTag, P: c.WeakTypeTag](
     c: Context
-  )(p: c.Expr[P])(ev: c.Expr[P <:< Parser[T]]): c.Expr[() => P] = {
+  )(p: c.Expr[P])(@unused ev: c.Expr[P <:< Parser[T]]): c.Expr[() => P] = {
     import c.universe._
-    Unused(ev)
     val tree   = p.tree
     val expr   = q"$tree"
     val parser = c.eval(c.Expr[Parser[T]](c.untypecheck(expr.duplicate)))

lib/graph/README.md

@@ -0,0 +1,3 @@
+# Graph
+This is a flexible and high-performance graph library that encodes the graphs in
+a fashion amenable to incredibly rapid serialisation.

lib/json-rpc-server-test/README.md

@@ -0,0 +1,3 @@
+# JSON-RPC Server Test
+Tests for the [JSON-RPC Server](../json-rpc-server).
+

lib/json-rpc-server/README.md

@@ -0,0 +1,4 @@
+# JSON-RPC Server
+This library implements a universal JSON RPC server with a flexible API for
+defining the message format.
+

lib/logger/README.md

@@ -0,0 +1,3 @@
+# Logger
+A configurable logging library.
+

lib/logger/src/main/scala/org/enso/Logger.scala

@@ -1,7 +1,7 @@
 package org.enso
 
+import scala.annotation.unused
 import scala.reflect.macros.blackbox.Context
-import org.enso.lint.Unused
 
 class Logger {
   import Logger._
@@ -70,9 +70,8 @@ class Logger {
 object Logger {
   def groupRedirect[R: c.WeakTypeTag](
     c: Context
-  )(msg: c.Tree)(body: c.Tree): c.Expr[R] = {
+  )(@unused msg: c.Tree)(body: c.Tree): c.Expr[R] = {
     import c.universe._
-    Unused(msg)
     val target = c.macroApplication match {
       case Apply(Apply(TypeApply(Select(base, name), typ), msg2), body2) =>
         val newName = TermName("_" + name.toString)
@@ -131,9 +130,8 @@ object Logger {
     if (checkEnabled(c)) c.Expr(q"$target") else c.Expr(q"$body")
   }
 
-  def funcRedirect(c: Context)(s: c.Tree): c.Expr[Unit] = {
+  def funcRedirect(c: Context)(@unused s: c.Tree): c.Expr[Unit] = {
     import c.universe._
-    Unused(s)
     val target = c.macroApplication match {
       case Apply(Select(base, name), args) =>
         val newName = TermName("_" + name.toString)

lib/parser-service/README.md

@@ -0,0 +1,2 @@
+# Parser Service
+A debugging service for the Enso parser.

lib/pkg/README.md

@@ -0,0 +1,4 @@
+# Package
+This library implements and describes the Enso package format used by both the
+language tooling and the interpreter.
+

lib/project-manager/README.md

@@ -0,0 +1,5 @@
+# Project Manager
+This library implements the functionality and messages backing the project
+manager component of the
+[Enso Protocol](../../doc/language-server/specification/enso-protocol.md).
+

lib/project-manager/src/main/scala/org/enso/projectmanager/control/effect/ZioErrorChannel.scala

@@ -3,12 +3,16 @@ package org.enso.projectmanager.control.effect
 import shapeless.=:!=
 import zio.{CanFail, ZIO}
 
+import scala.annotation.unused
+
 /**
   * Instance of [[ErrorChannel]] class for ZIO.
   */
 class ZioErrorChannel[R] extends ErrorChannel[ZIO[R, +*, +*]] {
 
-  implicit private def canFailEv[E](implicit ev: E =:!= Nothing): CanFail[E] =
+  implicit private def canFailEv[E](
+    implicit @unused ev: E =:!= Nothing
+  ): CanFail[E] =
     CanFail
 
   /** @inheritdoc **/