Update docs and lint configuration for quotes

Author: leeyi45

README.md

@@ -21,6 +21,32 @@ If you are a developer looking to do things like create a new bundle or work wit
 | `js-slang` | https://github.com/source-academy/js-slang |
 | Frontend | https://github.com/source-academy/frontend |
 
+## Repository Structure
+
+```txt
+.
+├── .github
+│   ├── actions        // Custom Github Actions
+│   └── workflow       // CI/CD Workflow files
+├── build              // Output for compiled assets
+├── devserver          // Development Server
+├── docs               // Documentation Server
+├── lib
+│   ├── __test_mocks__ // Mock bundles and tabs used for testing
+│   ├── buildtools     // Command line tools for bundles and tabs
+│   ├── lintplugin     // ESLint Plugin
+│   ├── markdown-tree  // Markdown-It plugin for generating directory trees
+│   ├── modules-lib    // Common library for utilities used by bundles and tabs
+│   └── repotools      // Repository wide tooling
+├── src                // Code for bundles, tabs and java-slang
+│   ├── bundles
+│   ├── tabs
+│   └── java
+├── vitest.config.js   // Root Vitest Config
+├── eslint.config.js   // ESLint Config
+└── yarn.config.cjs    // Yarn Constraints file
+```
+
 ## Building the documentation server
 
 1. Run the command: `yarn workspaces focus @sourceacademy/modules-docserver`

docs/src/modules/1-getting-started/3-git.md

@@ -18,6 +18,10 @@ When making changes to the code in this repository, you should abide by some goo
 > When you add a dependency to your bundle/tab, remember to run your installation command to ensure that the lockfile gets updated, and then
 > commit the changes to the lockfile.
 
+> [!WARNING] package-lock.json
+> If you accidentally run installation commands with `npm` instead (i.e `npm i`), a different type of lockfile will get generated. This file should be
+> deleted if present and should not be added to the repository.
+
 ## Creating your own branch
 
 The `master` branch of the repository is protected. This means that you cannot push commits directly to it, nor can pull requests be merged
@@ -45,3 +49,12 @@ Once your code has been reviewed, the pull request will be merged.
 ## Opening Issues
 
 If you have a bug report or feature request, open an issue with the appropriate label(s) [here](https://github.com/source-academy/modules/issues)
+
+## `.gitignore` Files
+
+You should include files that are produced from compilation into your own `.gitignore` file and avoid committing them to the repository. By default,
+the `dist` folders are ignored for all bundles and tabs, but if you need to add other files you can create a custom `.gitignore` in your bundle/tab's
+directory.
+
+> [!TIP]
+> If you want to remove a file that been committed in the past you can use `git rm`

docs/src/modules/1-getting-started/4-cheat.md

@@ -23,16 +23,16 @@ All commands have a `-h` or `--help` option that can be used to get more informa
     </tr>
     <tr>
       <td><code>yarn workspaces focus @sourceacademy/bundle-curve</code></td>
-      <td>Installs the dependencies required for the `curve` bundle <strong>only</strong> </td>
+      <td>Installs the dependencies required for the <code>curve</code> bundle <strong>only</strong> </td>
     </tr>
     <tr>
-      <td><code>yarn add &lt;package&gt;</code>*</td>
+      <td><code>yarn add &lt;package&gt;</code></td>
       <td>
         Adds a package to the current bundle or tab <br />
       </td>
     </tr>
     <tr>
-      <td><code>yarn add -D &lt;package&gt;</code>*</td>
+      <td><code>yarn add -D &lt;package&gt;</code></td>
       <td>
         Adds a package to the current bundle or tab that will only be used during runtime <br />
       </td>
@@ -156,10 +156,10 @@ In general, global scripts for this repository follow the same format.
 - `:modules` will be run for all bundle and tab code
 
 > [!WARNING] On Focused Installs
-> If you used a focus install, the dependencies for the other bundles and tabs will not be available. In fact, the root
+> If you used a focused install, the dependencies for the other bundles and tabs will not be available. The root
 > repository's package may not have been installed either.
 >
-> This means that many of the `:all` and `:modules` commands will not work. You should use the bundle or tab specific
+> Without the root package being installed, many of the `:all` and `:modules` commands may not work. You can still use the bundle or tab specific
 > commands instead.
 
 <table>

docs/src/modules/2-bundle/4-conventions/2-abstractions.md

@@ -35,8 +35,8 @@ Functionally, `Sound` behaves like a primitive type: as far as a cadet using the
 ## Breaking Abstractions with `display` and `stringify`
 
 `js-slang` provides a built-in function for converting any value into a string: `stringify()`. `display()` behaves like the typical `console.log` and prints the string representation
-as returned by `stringify` to the REPL. Under the hood, `stringify` uses the default Javascript `toString` functionality to convert primitive types to their string representations. This does
-mean that for "primitives" that are actually objects, `js-slang`'s default implementation will end up exposing implementation details.
+as returned by `stringify` to the REPL. Under the hood, `stringify` uses the default Javascript `toString` functionality to convert Javascript types to their string representations. This does
+mean that for Source primitives that are actually Javascript objects, `js-slang`'s default implementation will end up exposing implementation details.
 
 Taking an example from the `curve` bundle, `RenderFunction`s are considered a type of primitive. Without any further changes, calling `display` on a `RenderFunction` produces the following
 output:
@@ -116,6 +116,13 @@ export class Point implements ReplResult {
 `Point` is a class that directly implements the `ReplResult` interface.  If it didn't implement this interface, then calling `display(make_point(20, 20))`
 would result in the infamous `[object Object]` being printed.
 
+The type doesn't have to be a class, it can also be a Typescript [interface](https://www.typescriptlang.org/docs/handbook/2/objects.html):
+```ts
+interface Thing extends ReplResult {
+  // ...implementation details
+}
+```
+
 The benefit of implementing the interface this way in Typescript is that it enables type-checking to ensure that the interface is properly implemented.
 
 ### Implementing `ReplResult` indirectly
@@ -251,4 +258,4 @@ const options = create_text_options('blue', 20);
 change_text_options(options);
 ```
 
-The idea is that the abstraction of the `TextOptions` type is never broken and that the cadet never interacts with the object directly.
+The idea is that the abstraction of the `TextOptions` type is never broken and that the cadet never interacts with the object's component parts directly.

docs/src/modules/2-bundle/4-conventions/3-errors.md

@@ -53,7 +53,7 @@ Then, the error can be thrown with the correct function name. Otherwise, cadets
 that is visible to them. Many other functions might rely on `throwIfNotRune`. If they were all called in the same program, it doesn't tell the cadet which function the error was thrown from
 (was it `show`? or `anaglyph`? or something else?)
 
-## Type Checking
+## Source Type Checking
 
 Though bundles are written in Typescript, Source (except for the Typed Variant) does not support anything beyond rudimentary type checking. This means that it can determine that an expression
 like `1 - "string"` is badly typed, but it can't type check more complex programs like the one below, especially when bundle functions are involved:

docs/src/modules/4-testing/2-devserver/2-devserver.md

@@ -44,3 +44,5 @@ to compiled mode by following the steps below:
 
 2. Switch to compiled mode
 ![](./step2.png)
+
+If need be, you can use the the textbox to customize which server to load modules from.

docs/src/modules/4-testing/4-unit.md

@@ -211,7 +211,7 @@ The default testing configuration for tabs has browser mode disabled. This is so
 
 ### Setting up Browser Mode
 
-Should you wish to enable browser mode, create a custom `vitest` configuration file for your tab with the `browswer.enabled` option set to `true`:
+Should you wish to enable browser mode, create a custom `vitest` configuration file for your tab with the `browser.enabled` option set to `true`:
 
 ```js {9}
 // @ts-check
@@ -228,11 +228,23 @@ export default defineProject({
 });
 ```
 
-Now, the tests for your tab will be run in browser mode.
+You will also need to add (to your dev dependencies) other packages:
+- `@vitest/browser`
+- `vitest-browser-react`
+- `playwright`
+
+In the case of `playwright`, you might also have to run `playwright install chromium`.
+
+If your system doesn't have the necessary dependencies for `playwright`'s install, you will have to run `playwright install chromium --with-deps` instead.
+
+Now, the tests for your tab can be run in browser mode.
 
 > [!INFO] Default Browser Instance
 > By default, one `chromium` browser instance will be provided. This should be sufficient, but you can always
 > add more instances if necessary.
+>
+> Then, you will also have to specify this instance when running the `playwright` installation command above.
+
 
 ### Writing Interactive Tests
 
@@ -350,3 +362,55 @@ test('An animation', async () => {
   await expect.element(finishScreen).toBeVisible();
 });
 ```
+
+### Element Locators
+
+In the above examples, you might have noticed that we can actually grab elements that are within the DOM and do things with them (like performing
+assertions or clicking).
+
+`vitest` provides several ways to "locate" an element helpfully called [locators](https://vitest.dev/guide/browser/locators.html).
+
+While writing tabs, if we believe that a component will need to be interacted with during unit testing, we can use attributes like `title` to make it
+easier to refer to these elements:
+
+```tsx
+export function Foo() {
+  return <p title="important" />;
+}
+
+// Can then be referred to:
+test('test0', () => {
+  const screen = render(<Foo />);
+  const p = screen.getByTitle('important');
+  await expect.element(p).toBeVisible();
+});
+```
+
+### Simulating User Input
+
+You can simulate user input by using the `userEvent` utility from `@vitest/browser`:
+```tsx
+export function Foo() {
+  const [text, setText] = useState('');
+  return <div>
+    <input
+      onChange={e => setText(e.target.value)}
+      value={text}
+    />
+    <p>You said: {text}</p>
+  </div>;
+}
+
+// In tests:
+import { userEvent } from '@vitest/browser/context';
+import { render } from 'vitest-browser-react';
+
+test('Changing text works', () => {
+  const screen = render(<Foo />);
+  await userEvent.keyboard('abcd');
+  const element = screen.getByText('abcd');
+  await expect.element(element).toBeVisible();
+});
+```
+
+It can also simulate sustained keypresses, mouse inputs and a whole lot of [other things](https://testing-library.com/docs/user-event/keyboard/).

eslint.config.js

@@ -394,7 +394,15 @@ export default tseslint.config(
     rules: {
       'no-empty-pattern': 'off', // vitest requires certain things to be destructured using an object pattern
 
-      '@stylistic/quotes': 'off', // Turn this off to avoid conflicting with snapshots
+      // Change to avoid conflicting with snapshots
+      '@stylistic/quotes': [
+        'warn',
+        'single',
+        {
+          avoidEscape: true,
+          allowTemplateLiterals: 'always'
+        }
+      ],
 
       'vitest/expect-expect': ['error', {
         assertFunctionNames: ['expect*'],

lib/buildtools/src/commands/__tests__/commandUtils.test.ts

@@ -1,6 +1,6 @@
-import type { Severity } from "@sourceacademy/modules-repotools/types";
-import { describe, expect, test } from "vitest";
-import { processResult } from "../commandUtils.js";
+import type { Severity } from '@sourceacademy/modules-repotools/types';
+import { describe, expect, test } from 'vitest';
+import { processResult } from '../commandUtils.js';
 
 describe('Testing processResults', () => {
   const testCases: [any, Severity][] = [

lib/buildtools/src/testing/__tests__/utils.test.ts

@@ -270,7 +270,7 @@ describe('Test getTestConfiguration', () => {
       mockedReadFile.mockImplementation(p => {
         if (p === pathlib.join(libPath, 'package.json')) {
           return Promise.resolve(JSON.stringify({
-            name: "@sourceacademy/a-pacakge"
+            name: '@sourceacademy/a-pacakge'
           }));
         }
         throw new ENOENT();