More linting changes

Author: leeyi45

.vscode/settings.json

@@ -4,7 +4,7 @@
     {
       "fileMatch": ["src/bundles/**/manifest.json"],
       "url": "./lib/buildtools/src/build/modules/manifest.schema.json"
-    }, 
+    },
     {
       "fileMatch": ["tsconfig.json", "tsconfig.*.json"],
       "schema": {

devserver/src/components/sideContent/importers/importers.ts

@@ -49,7 +49,7 @@ export async function getCompiledTabs(context: Context) {
       if (manifest.tabs) {
         const tabsToSpawn = manifest.tabs as string[];
         return Promise.all(tabsToSpawn.map(async (tabName): Promise<ModuleSideContent> => {
-          const { default: rawTab } = await import(`../../../../../build/tabs/${tabName}.js`);
+          const { default: rawTab } = await import(/* @vite-ignore */ `../../../../../build/tabs/${tabName}.js`);
           const { default: content } = await (rawTab as RawTab)(requireProvider, React);
           return content;
         }));

devserver/tsconfig.json

@@ -25,7 +25,7 @@
     "verbatimModuleSyntax": true,
     "types": [
       "@vitest/browser/matchers",
-      "@vitest/browser/providers/playwright" 
+      "@vitest/browser/providers/playwright"
     ]
   },
   "include": ["src"],

docs/.vitepress/config.ts

@@ -17,7 +17,7 @@ const vitepressOptions: UserConfig = {
   title: 'Modules Developer Documentation',
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
-    logo: './favicon.ico',
+    logo: '/favicon.ico',
     nav: [
       { text: 'Home', link: '/' },
       {
@@ -30,10 +30,28 @@ const vitepressOptions: UserConfig = {
           {
             text: 'Getting Started',
             link: '/modules/1-getting-started/2-start'
+          },
+          {
+            text: 'Bundles',
+            link: '/modules/2-bundle/1-overview/1-overview'
+          },
+          {
+            text: 'Tabs',
+            link: '/modules/3-tabs/1-overview'
           }
         ]
       },
-      { text: 'Common Library', link: '/lib' },
+      {
+        text: 'Libraries',
+        items: [
+          {
+            text: 'Common Libraries',
+            link: '/lib'
+          }, {
+            text: 'Developer Docs',
+            link: '/lib/dev'
+          }]
+      },
       {
         text: 'Dev Tools',
         items: [

docs/src/buildtools/2-command.md

@@ -15,3 +15,31 @@ Command execution follows the following steps:
 ## CI Pipeline Compatibility
 Since the buildtools need to be run as part of the CI pipeline, it is important that they return non-zero exit codes when appropriate so that
 the CI pipeline can detect that errors have occurred and halt the pipeline.
+
+## Command Execution Flow
+
+### Single Bundle/Tab
+For a command that processes a single bundle or tab, this is the flow of the command:
+```mermaid
+graph TD
+  A[Resolve bundle/tab]
+  C["Run prebuilds (if necessary)"]
+  B[Run Command]
+  D[Check if running in CI Mode]
+  E[Display error and exit with code 1]
+  F[Display success message]
+
+  A -- Is resolved --> C
+  A -- Is not resolved --> E
+
+  C -- No errors or warnings --> B
+  C -- Warnings present --> D
+  C -- Errors present --> E
+
+  B -- Warnings present --> D
+  B -- Errors present --> E
+
+  D -- Is CI Mode --> E
+  D -- Not CI Mode --> F
+  B -- No errors or warnings --> F
+```

docs/src/buildtools/6-prebuild.md

@@ -18,6 +18,11 @@ errors always cause a non-zero exit code.
 ESLint provides several [formatters](https://eslint.org/docs/latest/use/formatters/) for processing the results objects it returns. To produce the human readable output that is printed to the command line, the `stylish` formatter
 is loaded and used.
 
+::: details Inspecting the Linting Config
+The entire repository's linting configuration is located at the root of the repository within `eslint.config.js`. If you want to view the view what rules are being applied to which files you can
+use the config inspector, which can be started using `yarn lint:inspect`
+:::
+
 ## Calling Typescript from Node
 
 Most of the code for running Typescript functionality from Node was taken from [this](https://github.com/Microsoft/TypeScript/issues/6387) Github issue.
@@ -39,7 +44,7 @@ The first three steps in the process involve reading the raw text from the `tsco
 in use, as well as the file paths to the files that are to be processed.
 
 ### Type Checking
-The first time `ts.createProgram` is called, it is called with every single file as returned from `ts.parseJsonConfigFileContent`. However, it is called with `noEmit: true`. This prevents any Javascript and Typescript declaration files from being written.
+At step 4, `ts.createProgram` is called for the first time. It is called with every single file as returned from `ts.parseJsonConfigFileContent`. However, it is called with `noEmit: true`. This prevents any Javascript and Typescript declaration files from being written.
 This is important because we want test files to be type checked, but we don't want them to be compiled into Javascript and exported with the rest of the code. If they were included and the `tsconfig` was configured to produce outputs, the test files would end
 up being written to the `outDir`. `typecheckProgram.emit` is called to perform the type checking.
 

docs/src/lib/dev/index.md

@@ -3,11 +3,11 @@ title: Modules Developer Docs
 ---
 
 <script setup>
-  import { data } from './devdocs.data.js'
+  import { data } from './devdocs.data.ts'
 </script>
 
 <h1>Bundles Developer Documentation</h1>
-<p>This an the index page for bundles that have documentation for developers working them</p>
+<p>This an the index page for bundles that have documentation for developers working with them</p>
 <ul>
   <li v-for="doc of data">
     <a :href="doc.url">{{ doc.frontmatter.title }}</a>

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

@@ -1,48 +1,112 @@
+<script setup>
+  import { data } from './scripts.data.ts';
+  const { globalScripts, rootScripts } = data
+</script>
+
 # Commands Cheat Sheet
+All commands have a `-h` or `--help` option that can be used to get more information about the command. 
+
+## Icon Legend
+<table>
+  <thead>
+    <tr>
+      <th>Icon</th>
+      <th>Meaning</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>💼</td>
+      <td>Can be run from a bundle's directory or any of its subdirectories</td>
+    </tr>
+    <tr>
+      <td>🖥</td>
+      <td>Can be run from a tab's directory or any of its subdirectories</td>
+    </tr>
+    <tr>
+      <td>🏠</td>
+      <td>Can be run from the repository root</td>
+    </tr>
+  </tbody>
+</table>
 
 ## Installation Commands
 <table>
   <thead>
     <tr>
       <th>Command</th>
       <th>Purpose</th>
+      <th><a href="#icon-legend">💼</a></th>
+      <th><a href="#icon-legend">🖥</a></th>
+      <th><a href="#icon-legend">🏠</a></th>
     </tr>
   </thead>
   <tbody>
     <tr>
       <td><code>yarn workspaces focus @sourceacademy/modules</code></td>
       <td>Installs the dependencies required for the repository <strong>only</strong> (like the build tools)</td>
+      <td/>
+      <td/>
+      <td>✅</td>
     </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>✅</td>
+      <td/>
+      <td>✅</td>
     </tr>
     <tr>
       <td><code>yarn add &lt;package&gt;</code></td>
       <td>
         Adds a package to the current bundle or tab <br />
-        (SHOULD ONLY BE RUN WITHIN THE BUNDLE OR TAB DIRECTORY)
       </td>
+      <td>✅</td>
+      <td>✅</td>
+      <td>✅*</td>
     </tr>
     <tr>
       <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 />
-        (SHOULD ONLY BE RUN WITHIN THE BUNDLE OR TAB DIRECTORY)
       </td>
+      <td>✅</td>
+      <td>✅</td>
+      <td>✅*</td>
     </tr>
   </tbody>
 </table>
 
+\* Will add packages to the root repository. Only do this if you are adding or updating a constraint for the entire repository.
+
 ## Bundle or Tab Specific Commands
+These commands are only applicable to bundles or tabs and should only be run from within the bundle or tab's directory.
 
 ### Compilation
-| Command                   | Purpose                                                       |
-|---------------------------|---------------------------------------------------------------|
-| `yarn build`              | Compiles the bundle or tab to the `/build` directory          |
-| `yarn build --tsc`        | Same as `yarn build` but also runs `tsc` for type checking    |
-| `yarn build --lint`       | Same as `yarn build` but also runs ESLint for linting         |
-| `yarn build --lint --tsc` | Run both ESLint and `tsc` simultaneously before running build |
+<table>
+  <thead>
+    <tr>
+      <th>Command</th>
+      <th>Purpose</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>yarn build</code></td>
+      <td>Compiles the bundle or tab to the <code>/build</code> directory</td>
+    </tr>
+    <tr>
+      <td><nobr><code>yarn build --tsc</code></nobr></td>
+      <td>Same as <code>yarn build</code> but also runs <code>tsc</code> for type checking</td>
+    </tr>
+    <tr>
+      <td><nobr><code>yarn build --lint</code></nobr></td>
+      <td>Same as <code>yarn build</code> but also runs ESLint</td>
+    </tr>
+  </tbody>
+</table>
+
+Both the `--tsc` and `--lint` options can be used togther to run `tsc` and ESLint simultaneously.
 
 ### Prebuild and Testing
 <ins>Prebuild</ins> refers to commands that are to be run **before** the build/compilation commands are executed.
@@ -65,13 +129,9 @@ These commands should only be run from the root of the Git repository.
     </tr>
   </thead>
   <tbody>
-    <tr>
-      <td><nobr><code>yarn devserver</code></nobr></td>
-      <td>Start the modules development server</td>
-    </tr>
-    <tr>
-      <td><nobr><code>yarn serve</code></nobr></td>
-      <td>Run the modules server to serve modules to local copies of <code>js-slang</code> and the frontend </td>
+    <tr v-for="cmd of rootScripts">
+      <td><nobr><code>yarn {{ cmd.name }}</code></nobr></td>
+      <td>{{ cmd.info }} </td>
     </tr>
   </tbody>
 </table>
@@ -80,6 +140,12 @@ These commands should only be run from the root of the Git repository.
 Yarn considers scripts with a ":" in their name to be a [global script](https://yarnpkg.com/features/workspaces#global-scripts) that can be run from anywhere,
 including child workspaces. In other words, these commands are available throughout the repository, not just at the root level.
 
+In general, global scripts for this repository follow the same format.
+- `:all` will be run for all code in the respository
+- `:devserver` will only be run for the devserver.
+- `:libs` will be run for all code under the `lib` folder (common modules libraries)
+- `:modules` will be run for all bundle and tab code
+
 <table>
   <thead>
     <tr>
@@ -88,17 +154,9 @@ including child workspaces. In other words, these commands are available through
     </tr>
   </thead>
   <tbody>
-    <tr>
-      <td><nobr><code>yarn build:modules</code></nobr></td>
-      <td>Builds all bundles, tabs, JSONS and HTML documentation</td>
-    </tr>
-    <tr>
-      <td><nobr><code>yarn build:docs</code></nobr></td>
-      <td>Builds JSONS and HTML documentation for all bundles. <br /> Useful if you're only changing documentation.</td>
-    </tr>
-    <tr>
-      <td><nobr><code>yarn template</code></nobr></td>
-      <td>Starts the interactive bundle/tab creator</td>
+    <tr v-for="cmd of globalScripts">
+      <td><nobr><code>yarn {{ cmd.name }}</code></nobr></td>
+      <td>{{ cmd.info }} </td>
     </tr>
   </tbody>
 </table>

docs/src/modules/1-getting-started/scripts.data.ts

@@ -0,0 +1,32 @@
+import _package from '../../../../package.json' with { type: 'json' };
+
+type Script = {
+  name: string
+  info: string
+};
+
+export default {
+  watch: ['../../../../package.json'],
+  load() {
+    const [globalScripts, rootScripts] = Object.keys(_package.scripts).reduce<[Script[], Script[]]>(([globals, roots], scriptNames) => {
+      const scriptInfo = _package['scripts-info'][scriptNames];
+
+      if (scriptInfo === undefined) return [globals, roots];
+      const script: Script = {
+        name: scriptNames,
+        info: scriptInfo
+      };
+
+      if (scriptNames.includes(':')) {
+        return [[...globals, script ], roots];
+      } else {
+        return [globals, [...roots, script]];
+      }
+    }, [[], []]);
+
+    return {
+      globalScripts,
+      rootScripts
+    };
+  }
+};

docs/src/modules/2-bundle/1-overview/1-overview.md

@@ -8,14 +8,16 @@ For example, the `binary_tree` module may want to provide an abstraction for Sou
 
 The typical bundle structure for a bundle is shown below. Each section will have its own explanation.
 ```txt
-bundle_name          // Name of the root folder is the name of the bundle
+bundle_name             // Name of the root folder is the name of the bundle
 ├── src
-│   ├── index.ts     // Entry Point
-│   ├── functions.ts // Example file
-│   └── ....         // Other files your bundle may use
-├── package.json     // Package Manifest
-├── manifest.json    // Bundle Manifest
-└── tsconfig.json    // Typescript Configuration
+│   ├── __tests__       // Folder containing unit tests
+│   │   └── index.ts    // File containing unit tests
+│   ├── index.ts        // Entry Point
+│   ├── functions.ts    // Example file
+│   └── ....            // Other files your bundle may use
+├── package.json        // Package Manifest
+├── manifest.json       // Bundle Manifest
+└── tsconfig.json       // Typescript Configuration
 ```
 
 > [!NOTE]
@@ -95,8 +97,16 @@ The `package.json` file follows the same format as your typical `package.json` u
 ```
 You can find more information about each of the fields and what they mean [here](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#devdependencies).
 
-> [!WARNING]
-> The `name` field must follow the format `@sourceacademy/bundle-[your bundle name]`.
+> [!WARNING] Bundle vs Package Name
+> The `name` field in `package.json` is the package name and must follow the format `@sourceacademy/bundle-[your bundle name]`.
+> The bundle name is what users will actually use to import your bundle from within Source code:
+> ```ts
+> import { whatever } from 'bundle_name';
+> ```
+> However, if people consuming your bundle from regular Javascript and Typescript need to use the full (scoped) package name:
+> ```ts
+> import { whatever } from '@sourceacademy/bundle-bundle_name';
+> ```
 
 ### `manifest.json`
 `manifest.json` contains the information required by `js-slang` to load your bundle.
@@ -114,7 +124,7 @@ Your bundle may rely on features that are only present in later Source Chapters.
 :::
 
 >[!TIP] Verifying your manifest
-> You can use the `buildtools list` command to check that your bundle can be properly detected and has the correct format.
+> You can use the `buildtools list bundle` command to check that your bundle can be properly detected and has the correct format.
 
 ## `tsconfig.json`
 This file controls the behaviour of Typescript. By default, it should look like this: