Update documentation further

Author: leeyi45

docs/src/repotools/docserver/1-overview.md

@@ -91,3 +91,11 @@ this
 ```
 
 are generated via their own markdown plugin, the details of which can be found [here](./2-dirtree).
+
+## Production Build and Dead Links
+
+The preview version of the docs rendered by Vitepress when the `vitepress dev` command is executed is not the final version that is intended to be displayed.
+For this, Vitepress provides the `vitepress build` command, which converts the documentation source into its final, minified HTML form.
+
+As part of this process, Vitepress will highlight any "dead" links (i.e links that don't point to anything) and will fail if it finds any. If you're editing
+the documentation, you should run the build command to check for the dead links before pushing to the repository.

docs/src/repotools/index.md

@@ -9,4 +9,7 @@ Below is a list of other tools:
 - [ESLint](./linting)
 - [Github Workflows](./workflows/index)
 - [VSCode](./vscode)
+- [Vitest Reporters](./reporters)
 - [Yarn](./yarn)
+
+You may also want to refer to the Source Academy wide developer conventions which can be found [here](https://github.com/source-academy/general/wiki/Conventions-and-practices).

docs/src/repotools/reporters.md

@@ -0,0 +1,17 @@
+# Vitest Reporters
+
+The `@sourceacademy/vitest-reporter` package contains 2 reporters designed to work with Vitest. One is a reporter
+for the test results as produced by Vitest.
+
+The other is a test coverage reporter. Vitest internally uses the Istanbul reporter interface, which as of the time of writing
+seems to only be available in CommonJS format. Thus, this reporter has to be written and built for the CJS format.
+
+Both reporters write their output to the Github Actions summary, which is as simple as opening the file specified by the
+`GITHUB_STEP_SUMMARY` environment available in **append** mode and then writing to it.
+
+If the reporters aren't running in the Github Actions environment, `GITHUB_STEP_SUMMARY` won't be defined and neither
+reporter will produce any output.
+
+Unlike the other packages in this repository, the transpiled version of both reporters is committed to Github and the
+reporters are referenced using their local paths by Vitest configurations.
+Otherwise, every other package in this repository will have to add the `@sourceacademy/vitest-reporter` as a (dev) dependency.

docs/src/repotools/workflows/3-workflows.md

@@ -17,5 +17,3 @@ These Git Hooks are powered by [`husky`](https://github.com/typicode/husky).
 ## Deployment to Github Pages
 
 Upon any successful merge into `master`, this action runs to deploy the modules site onto Github pages to automatically serve the default modules and their documentation.
-
-Its configuration is shown below:

docs/src/repotools/yarn.md

@@ -32,6 +32,23 @@ For example, the root package specifies `react@^18.3.1` as a depdendency, so all
 
 This validation is not carried out across child workspaces, however. Two different bundles could use two different versions of the same package. This should not cause an issue **unless** the bundles are somehow dependendent on each other.
 
+Furthermore, if you are depending on a package from within the modules repository, you should be using the `workspace:^` version specification as the packages within this repository
+are not intended to be published to NPM so a regular version specification would be invalid.
+
+### 3. `js-slang` has no resolution override
+
+Yarn allows users to override the resolution of packages via the [`resolutions`](https://yarnpkg.com/configuration/manifest#resolutions) field. There are several reasons to do this,
+but the most common reason a resolution would be used in this repository would be to point Yarn to a local copy of `js-slang`.
+
+Of course, the final production versions of your code shouldn't be relying on a local copy of `js-slang` (that wouldn't exist anyway), so the constraint is enforced here to
+make sure that `js-slang` isn't incorrectly resolved.
+
+### 4. `repotools` doesn't have another local dependency
+
+The `repotools` package is designed to be the 'root' for all the tooling in the repository. If it were to depend on another package within this repository, we would create
+a dependency loop that Yarn would not be able to resolve. So we enforce the constraint that the `@sourceacademy/modules-repotools` package is not allowed to depend on any
+other package within this repository.
+
 ## Parallel Execution of Scripts
 
 Using the various options of the `yarn workspaces foreach` command, you can execute multiple tasks in parallel, which is how many of the commands in the root repository have been set up.

lib/vitest-reporter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sourceacademy/vitest-reporter",
-  "description": "A Vitest coverage reporter designed to work with Github Actions",
+  "description": "Vitest test and coverage reporters designed to work with Github Actions",
   "version": "1.0.0",
   "type": "module",
   "dependencies": {

yarn.config.cjs

@@ -31,7 +31,11 @@ module.exports = defineConfig({
     for (const dep of Yarn.dependencies()) {
       // Dependencies that are from this repository should use
       // the correct version
-      if (dep.ident.startsWith('@sourceacademy')) {
+      if (
+        dep.ident.startsWith('@sourceacademy/modules') ||
+        dep.ident.startsWith('@sourceacademy/bundle') ||
+        dep.ident.startsWith('@sourceacademy/tab')
+      ) {
         dep.update('workspace:^');
       }
     }